You've already forked linux-apfs
mirror of
https://github.com/linux-apfs/linux-apfs.git
synced 2026-05-01 15:00:59 -07:00
Merge branch 'mauro-books' into docs-next
Merge Mauro's massive patch series creating the process and admin-guide books. I think there's a lot of stuff to clean up here, but there's no point in holding things up for that. Mauro sez: This patch series continues the efforts of converting the Linux Kernel documentation to Sphinx. It contains text to ReST conversion of several files under Documentation, and a few ones under the main dir (README, REPORTING-BUGS). All patches on this series can be found on my development tree: https://git.linuxtv.org/mchehab/experimental.git/log/?h=lkml-books-v2 The Kernel docs html output after this series can be seen at: https://mchehab.fedorapeople.org/kernel_docs/
This commit is contained in:
Jonathan Corbet
+28
-32
@@ -15,11 +15,11 @@ Following translations are available on the WWW:
|
||||
ABI/
|
||||
- info on kernel <-> userspace ABI and relative interface stability.
|
||||
|
||||
BUG-HUNTING
|
||||
admin-guide/bug-hunting.rst
|
||||
- brute force method of doing binary search of patches to find bug.
|
||||
Changes
|
||||
process/changes.rst
|
||||
- list of changes that break older software packages.
|
||||
CodingStyle
|
||||
process/coding-style.rst
|
||||
- how the maintainers expect the C code in the kernel to look.
|
||||
DMA-API.txt
|
||||
- DMA API, pci_ API & extensions for non-consistent memory machines.
|
||||
@@ -33,7 +33,7 @@ DocBook/
|
||||
- directory with DocBook templates etc. for kernel documentation.
|
||||
EDID/
|
||||
- directory with info on customizing EDID for broken gfx/displays.
|
||||
HOWTO
|
||||
process/howto.rst
|
||||
- the process and procedures of how to do Linux kernel development.
|
||||
IPMI.txt
|
||||
- info on Linux Intelligent Platform Management Interface (IPMI) Driver.
|
||||
@@ -48,7 +48,7 @@ Intel-IOMMU.txt
|
||||
Makefile
|
||||
- This file does nothing. Removing it breaks make htmldocs and
|
||||
make distclean.
|
||||
ManagementStyle
|
||||
process/management-style.rst
|
||||
- how to (attempt to) manage kernel hackers.
|
||||
RCU/
|
||||
- directory with info on RCU (read-copy update).
|
||||
@@ -56,13 +56,13 @@ SAK.txt
|
||||
- info on Secure Attention Keys.
|
||||
SM501.txt
|
||||
- Silicon Motion SM501 multimedia companion chip
|
||||
SecurityBugs
|
||||
admin-guide/security-bugs.rst
|
||||
- procedure for reporting security bugs found in the kernel.
|
||||
SubmitChecklist
|
||||
process/submit-checklist.rst
|
||||
- Linux kernel patch submission checklist.
|
||||
SubmittingDrivers
|
||||
process/submitting-drivers.rst
|
||||
- procedure to get a new driver source included into the kernel tree.
|
||||
SubmittingPatches
|
||||
process/submitting-patches.rst
|
||||
- procedure to get a source patch included into the kernel tree.
|
||||
VGA-softcursor.txt
|
||||
- how to change your VGA cursor from a blinking underscore.
|
||||
@@ -72,7 +72,7 @@ acpi/
|
||||
- info on ACPI-specific hooks in the kernel.
|
||||
aoe/
|
||||
- description of AoE (ATA over Ethernet) along with config examples.
|
||||
applying-patches.txt
|
||||
process/applying-patches.rst
|
||||
- description of various trees and how to apply their patches.
|
||||
arm/
|
||||
- directory with info about Linux on the ARM architecture.
|
||||
@@ -86,7 +86,7 @@ auxdisplay/
|
||||
- misc. LCD driver documentation (cfag12864b, ks0108).
|
||||
backlight/
|
||||
- directory with info on controlling backlights in flat panel displays
|
||||
bad_memory.txt
|
||||
admin-guide/bad-memory.rst
|
||||
- how to use kernel parameters to exclude bad RAM regions.
|
||||
basic_profiling.txt
|
||||
- basic instructions for those who wants to profile Linux kernel.
|
||||
@@ -150,11 +150,11 @@ debugging-via-ohci1394.txt
|
||||
- how to use firewire like a hardware debugger memory reader.
|
||||
dell_rbu.txt
|
||||
- document demonstrating the use of the Dell Remote BIOS Update driver.
|
||||
development-process/
|
||||
process/
|
||||
- how to work with the mainline kernel development process.
|
||||
device-mapper/
|
||||
- directory with info on Device Mapper.
|
||||
devices.txt
|
||||
admin-guide/devices.rst
|
||||
- plain ASCII listing of all the nodes in /dev/ with major minor #'s.
|
||||
devicetree/
|
||||
- directory with info on device tree files used by OF/PowerPC/ARM
|
||||
@@ -166,8 +166,6 @@ dontdiff
|
||||
- file containing a list of files that should never be diff'ed.
|
||||
driver-model/
|
||||
- directory with info about Linux driver model.
|
||||
dvb/
|
||||
- info on Linux Digital Video Broadcast (DVB) subsystem.
|
||||
dynamic-debug-howto.txt
|
||||
- how to use the dynamic debug (dyndbg) feature.
|
||||
early-userspace/
|
||||
@@ -178,7 +176,7 @@ efi-stub.txt
|
||||
- How to use the EFI boot stub to bypass GRUB or elilo on EFI systems.
|
||||
eisa.txt
|
||||
- info on EISA bus support.
|
||||
email-clients.txt
|
||||
process/email-clients.rst
|
||||
- info on how to use e-mail to send un-mangled (git) patches.
|
||||
extcon/
|
||||
- directory with porting guide for Android kernel switch driver.
|
||||
@@ -226,9 +224,9 @@ ia64/
|
||||
- directory with info about Linux on Intel 64 bit architecture.
|
||||
infiniband/
|
||||
- directory with documents concerning Linux InfiniBand support.
|
||||
init.txt
|
||||
admin-guide/init.rst
|
||||
- what to do when the kernel can't find the 1st process to run.
|
||||
initrd.txt
|
||||
admin-guide/initrd.rst
|
||||
- how to use the RAM disk as an initial/temporary root filesystem.
|
||||
input/
|
||||
- info on Linux input device support.
|
||||
@@ -248,7 +246,7 @@ isapnp.txt
|
||||
- info on Linux ISA Plug & Play support.
|
||||
isdn/
|
||||
- directory with info on the Linux ISDN support, and supported cards.
|
||||
java.txt
|
||||
admin-guide/java.rst
|
||||
- info on the in-kernel binary support for Java(tm).
|
||||
ja_JP/
|
||||
- directory with Japanese translations of various documents
|
||||
@@ -256,11 +254,11 @@ kbuild/
|
||||
- directory with info about the kernel build process.
|
||||
kdump/
|
||||
- directory with mini HowTo on getting the crash dump code to work.
|
||||
kernel-docs.txt
|
||||
process/kernel-docs.rst
|
||||
- listing of various WWW + books that document kernel internals.
|
||||
kernel-documentation.rst
|
||||
- how to write and format reStructuredText kernel documentation
|
||||
kernel-parameters.txt
|
||||
admin-guide/kernel-parameters.rst
|
||||
- summary listing of command line / boot prompt args for the kernel.
|
||||
kernel-per-CPU-kthreads.txt
|
||||
- List of all per-CPU kthreads and how they introduce jitter.
|
||||
@@ -302,7 +300,7 @@ magic-number.txt
|
||||
- list of magic numbers used to mark/protect kernel data structures.
|
||||
mailbox.txt
|
||||
- How to write drivers for the common mailbox framework (IPC).
|
||||
md.txt
|
||||
admin-guide/md.rst
|
||||
- info on boot arguments for the multiple devices driver.
|
||||
media-framework.txt
|
||||
- info on media framework, its data structures, functions and usage.
|
||||
@@ -326,7 +324,7 @@ module-signing.txt
|
||||
- Kernel module signing for increased security when loading modules.
|
||||
mtd/
|
||||
- directory with info about memory technology devices (flash)
|
||||
mono.txt
|
||||
admin-guide/mono.rst
|
||||
- how to execute Mono-based .NET binaries with the help of BINFMT_MISC.
|
||||
namespaces/
|
||||
- directory with various information about namespaces
|
||||
@@ -340,7 +338,7 @@ nommu-mmap.txt
|
||||
- documentation about no-mmu memory mapping support.
|
||||
numastat.txt
|
||||
- info on how to read Numa policy hit/miss statistics in sysfs.
|
||||
oops-tracing.txt
|
||||
admin-guide/oops-tracing.rst
|
||||
- how to decode those nasty internal kernel error dump messages.
|
||||
padata.txt
|
||||
- An introduction to the "padata" parallel execution API
|
||||
@@ -378,7 +376,7 @@ ptp/
|
||||
- directory with info on support for IEEE 1588 PTP clocks in Linux.
|
||||
pwm.txt
|
||||
- info on the pulse width modulation driver subsystem
|
||||
ramoops.txt
|
||||
admin-guide/ramoops.rst
|
||||
- documentation of the ramoops oops/panic logging module.
|
||||
rapidio/
|
||||
- directory with info on RapidIO packet-based fabric interconnect
|
||||
@@ -406,7 +404,7 @@ security/
|
||||
- directory that contains security-related info
|
||||
serial/
|
||||
- directory with info on the low level serial API.
|
||||
serial-console.txt
|
||||
admin-guide/serial-console.rst
|
||||
- how to set up Linux with a serial line console as the default.
|
||||
sgi-ioc4.txt
|
||||
- description of the SGI IOC4 PCI (multi function) device.
|
||||
@@ -420,9 +418,9 @@ sparse.txt
|
||||
- info on how to obtain and use the sparse tool for typechecking.
|
||||
spi/
|
||||
- overview of Linux kernel Serial Peripheral Interface (SPI) support.
|
||||
stable_api_nonsense.txt
|
||||
process/stable-api-nonsense.rst
|
||||
- info on why the kernel does not have a stable in-kernel api or abi.
|
||||
stable_kernel_rules.txt
|
||||
process/stable-kernel-rules.rst
|
||||
- rules and procedures for the -stable kernel releases.
|
||||
static-keys.txt
|
||||
- info on how static keys allow debug code in hotpaths via patching
|
||||
@@ -444,7 +442,7 @@ trace/
|
||||
- directory with info on tracing technologies within linux
|
||||
unaligned-memory-access.txt
|
||||
- info on how to avoid arch breaking unaligned memory access in code.
|
||||
unicode.txt
|
||||
admin-guide/unicode.rst
|
||||
- info on the Unicode character/font mapping used in Linux.
|
||||
unshare.txt
|
||||
- description of the Linux unshare system call.
|
||||
@@ -458,15 +456,13 @@ vgaarbiter.txt
|
||||
- info on enable/disable the legacy decoding on different VGA devices
|
||||
video-output.txt
|
||||
- sysfs class driver interface to enable/disable a video output device.
|
||||
video4linux/
|
||||
- directory with info regarding video/TV/radio cards and linux.
|
||||
virtual/
|
||||
- directory with information on the various linux virtualizations.
|
||||
vm/
|
||||
- directory with info on the Linux vm code.
|
||||
vme_api.txt
|
||||
- file relating info on the VME bus API in linux
|
||||
volatile-considered-harmful.txt
|
||||
process/volatile-considered-harmful.rst
|
||||
- Why the "volatile" type class should not be used
|
||||
w1/
|
||||
- directory with documents regarding the 1-wire (w1) subsystem.
|
||||
|
||||
@@ -84,4 +84,4 @@ stable:
|
||||
|
||||
- Kernel-internal symbols. Do not rely on the presence, absence, location, or
|
||||
type of any kernel symbol, either in System.map files or the kernel binary
|
||||
itself. See Documentation/stable_api_nonsense.txt.
|
||||
itself. See Documentation/process/stable-api-nonsense.rst.
|
||||
|
||||
@@ -347,7 +347,7 @@ Description:
|
||||
because of fragmentation, SLUB will retry with the minimum order
|
||||
possible depending on its characteristics.
|
||||
When debug_guardpage_minorder=N (N > 0) parameter is specified
|
||||
(see Documentation/kernel-parameters.txt), the minimum possible
|
||||
(see Documentation/admin-guide/kernel-parameters.rst), the minimum possible
|
||||
order is used and this sysfs entry can not be used to change
|
||||
the order at run time.
|
||||
|
||||
|
||||
+1
-1062
File diff suppressed because it is too large
Load Diff
@@ -1208,8 +1208,8 @@ static struct block_device_operations opt_fops = {
|
||||
|
||||
<listitem>
|
||||
<para>
|
||||
Finally, don't forget to read <filename>Documentation/SubmittingPatches</filename>
|
||||
and possibly <filename>Documentation/SubmittingDrivers</filename>.
|
||||
Finally, don't forget to read <filename>Documentation/process/submitting-patches.rst</filename>
|
||||
and possibly <filename>Documentation/process/submitting-drivers.rst</filename>.
|
||||
</para>
|
||||
</listitem>
|
||||
</itemizedlist>
|
||||
|
||||
File diff suppressed because it is too large
Load Diff
@@ -1,39 +0,0 @@
|
||||
Software cursor for VGA 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
|
||||
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
|
||||
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.
|
||||
|
||||
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).
|
||||
|
||||
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.
|
||||
|
||||
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'
|
||||
@@ -101,6 +101,6 @@ received a notification, it will set the backlight level accordingly. This does
|
||||
not affect the sending of event to user space, they are always sent to user
|
||||
space regardless of whether or not the video module controls the backlight level
|
||||
directly. This behaviour can be controlled through the brightness_switch_enabled
|
||||
module parameter as documented in kernel-parameters.txt. It is recommended to
|
||||
module parameter as documented in admin-guide/kernel-parameters.rst. It is recommended to
|
||||
disable this behaviour once a GUI environment starts up and wants to have full
|
||||
control of the backlight level.
|
||||
|
||||
@@ -0,0 +1,411 @@
|
||||
Linux kernel release 4.x <http://kernel.org/>
|
||||
=============================================
|
||||
|
||||
These are the release notes for Linux version 4. Read them carefully,
|
||||
as they tell you what this is all about, explain how to install the
|
||||
kernel, and what to do if something goes wrong.
|
||||
|
||||
What is Linux?
|
||||
--------------
|
||||
|
||||
Linux is a clone of the operating system Unix, written from scratch by
|
||||
Linus Torvalds with assistance from a loosely-knit team of hackers across
|
||||
the Net. It aims towards POSIX and Single UNIX Specification compliance.
|
||||
|
||||
It has all the features you would expect in a modern fully-fledged Unix,
|
||||
including true multitasking, virtual memory, shared libraries, demand
|
||||
loading, shared copy-on-write executables, proper memory management,
|
||||
and multistack networking including IPv4 and IPv6.
|
||||
|
||||
It is distributed under the GNU General Public License - see the
|
||||
accompanying COPYING file for more details.
|
||||
|
||||
On what hardware does it run?
|
||||
-----------------------------
|
||||
|
||||
Although originally developed first for 32-bit x86-based PCs (386 or higher),
|
||||
today Linux also runs on (at least) the Compaq Alpha AXP, Sun SPARC and
|
||||
UltraSPARC, Motorola 68000, PowerPC, PowerPC64, ARM, Hitachi SuperH, Cell,
|
||||
IBM S/390, MIPS, HP PA-RISC, Intel IA-64, DEC VAX, AMD x86-64, AXIS CRIS,
|
||||
Xtensa, Tilera TILE, AVR32, ARC and Renesas M32R architectures.
|
||||
|
||||
Linux is easily portable to most general-purpose 32- or 64-bit architectures
|
||||
as long as they have a paged memory management unit (PMMU) and a port of the
|
||||
GNU C compiler (gcc) (part of The GNU Compiler Collection, GCC). Linux has
|
||||
also been ported to a number of architectures without a PMMU, although
|
||||
functionality is then obviously somewhat limited.
|
||||
Linux has also been ported to itself. You can now run the kernel as a
|
||||
userspace application - this is called UserMode Linux (UML).
|
||||
|
||||
Documentation
|
||||
-------------
|
||||
|
||||
- There is a lot of documentation available both in electronic form on
|
||||
the Internet and in books, both Linux-specific and pertaining to
|
||||
general UNIX questions. I'd recommend looking into the documentation
|
||||
subdirectories on any Linux FTP site for the LDP (Linux Documentation
|
||||
Project) books. This README is not meant to be documentation on the
|
||||
system: there are much better sources available.
|
||||
|
||||
- There are various README files in the Documentation/ subdirectory:
|
||||
these typically contain kernel-specific installation notes for some
|
||||
drivers for example. See Documentation/00-INDEX for a list of what
|
||||
is contained in each file. Please read the
|
||||
:ref:`Documentation/process/changes.rst <changes>` file, as it
|
||||
contains information about the problems, which may result by upgrading
|
||||
your kernel.
|
||||
|
||||
- The Documentation/DocBook/ subdirectory contains several guides for
|
||||
kernel developers and users. These guides can be rendered in a
|
||||
number of formats: PostScript (.ps), PDF, HTML, & man-pages, among others.
|
||||
After installation, ``make psdocs``, ``make pdfdocs``, ``make htmldocs``,
|
||||
or ``make mandocs`` will render the documentation in the requested format.
|
||||
|
||||
Installing the kernel source
|
||||
----------------------------
|
||||
|
||||
- If you install the full sources, put the kernel tarball in a
|
||||
directory where you have permissions (e.g. your home directory) and
|
||||
unpack it::
|
||||
|
||||
xz -cd linux-4.X.tar.xz | tar xvf -
|
||||
|
||||
Replace "X" with the version number of the latest kernel.
|
||||
|
||||
Do NOT use the /usr/src/linux area! This area has a (usually
|
||||
incomplete) set of kernel headers that are used by the library header
|
||||
files. They should match the library, and not get messed up by
|
||||
whatever the kernel-du-jour happens to be.
|
||||
|
||||
- You can also upgrade between 4.x releases by patching. Patches are
|
||||
distributed in the xz format. To install by patching, get all the
|
||||
newer patch files, enter the top level directory of the kernel source
|
||||
(linux-4.X) and execute::
|
||||
|
||||
xz -cd ../patch-4.x.xz | patch -p1
|
||||
|
||||
Replace "x" for all versions bigger than the version "X" of your current
|
||||
source tree, **in_order**, and you should be ok. You may want to remove
|
||||
the backup files (some-file-name~ or some-file-name.orig), and make sure
|
||||
that there are no failed patches (some-file-name# or some-file-name.rej).
|
||||
If there are, either you or I have made a mistake.
|
||||
|
||||
Unlike patches for the 4.x kernels, patches for the 4.x.y kernels
|
||||
(also known as the -stable kernels) are not incremental but instead apply
|
||||
directly to the base 4.x kernel. For example, if your base kernel is 4.0
|
||||
and you want to apply the 4.0.3 patch, you must not first apply the 4.0.1
|
||||
and 4.0.2 patches. Similarly, if you are running kernel version 4.0.2 and
|
||||
want to jump to 4.0.3, you must first reverse the 4.0.2 patch (that is,
|
||||
patch -R) **before** applying the 4.0.3 patch. You can read more on this in
|
||||
:ref:`Documentation/process/applying-patches.rst <applying_patches>`.
|
||||
|
||||
Alternatively, the script patch-kernel can be used to automate this
|
||||
process. It determines the current kernel version and applies any
|
||||
patches found::
|
||||
|
||||
linux/scripts/patch-kernel linux
|
||||
|
||||
The first argument in the command above is the location of the
|
||||
kernel source. Patches are applied from the current directory, but
|
||||
an alternative directory can be specified as the second argument.
|
||||
|
||||
- Make sure you have no stale .o files and dependencies lying around::
|
||||
|
||||
cd linux
|
||||
make mrproper
|
||||
|
||||
You should now have the sources correctly installed.
|
||||
|
||||
Software requirements
|
||||
---------------------
|
||||
|
||||
Compiling and running the 4.x kernels requires up-to-date
|
||||
versions of various software packages. Consult
|
||||
:ref:`Documentation/process/changes.rst <changes>` for the minimum version numbers
|
||||
required and how to get updates for these packages. Beware that using
|
||||
excessively old versions of these packages can cause indirect
|
||||
errors that are very difficult to track down, so don't assume that
|
||||
you can just update packages when obvious problems arise during
|
||||
build or operation.
|
||||
|
||||
Build directory for the kernel
|
||||
------------------------------
|
||||
|
||||
When compiling the kernel, all output files will per default be
|
||||
stored together with the kernel source code.
|
||||
Using the option ``make O=output/dir`` allows you to specify an alternate
|
||||
place for the output files (including .config).
|
||||
Example::
|
||||
|
||||
kernel source code: /usr/src/linux-4.X
|
||||
build directory: /home/name/build/kernel
|
||||
|
||||
To configure and build the kernel, use::
|
||||
|
||||
cd /usr/src/linux-4.X
|
||||
make O=/home/name/build/kernel menuconfig
|
||||
make O=/home/name/build/kernel
|
||||
sudo make O=/home/name/build/kernel modules_install install
|
||||
|
||||
Please note: If the ``O=output/dir`` option is used, then it must be
|
||||
used for all invocations of make.
|
||||
|
||||
Configuring the kernel
|
||||
----------------------
|
||||
|
||||
Do not skip this step even if you are only upgrading one minor
|
||||
version. New configuration options are added in each release, and
|
||||
odd problems will turn up if the configuration files are not set up
|
||||
as expected. If you want to carry your existing configuration to a
|
||||
new version with minimal work, use ``make oldconfig``, which will
|
||||
only ask you for the answers to new questions.
|
||||
|
||||
- Alternative configuration commands are::
|
||||
|
||||
"make config" Plain text interface.
|
||||
|
||||
"make menuconfig" Text based color menus, radiolists & dialogs.
|
||||
|
||||
"make nconfig" Enhanced text based color menus.
|
||||
|
||||
"make xconfig" Qt based configuration tool.
|
||||
|
||||
"make gconfig" GTK+ based configuration tool.
|
||||
|
||||
"make oldconfig" Default all questions based on the contents of
|
||||
your existing ./.config file and asking about
|
||||
new config symbols.
|
||||
|
||||
"make silentoldconfig"
|
||||
Like above, but avoids cluttering the screen
|
||||
with questions already answered.
|
||||
Additionally updates the dependencies.
|
||||
|
||||
"make olddefconfig"
|
||||
Like above, but sets new symbols to their default
|
||||
values without prompting.
|
||||
|
||||
"make defconfig" Create a ./.config file by using the default
|
||||
symbol values from either arch/$ARCH/defconfig
|
||||
or arch/$ARCH/configs/${PLATFORM}_defconfig,
|
||||
depending on the architecture.
|
||||
|
||||
"make ${PLATFORM}_defconfig"
|
||||
Create a ./.config file by using the default
|
||||
symbol values from
|
||||
arch/$ARCH/configs/${PLATFORM}_defconfig.
|
||||
Use "make help" to get a list of all available
|
||||
platforms of your architecture.
|
||||
|
||||
"make allyesconfig"
|
||||
Create a ./.config file by setting symbol
|
||||
values to 'y' as much as possible.
|
||||
|
||||
"make allmodconfig"
|
||||
Create a ./.config file by setting symbol
|
||||
values to 'm' as much as possible.
|
||||
|
||||
"make allnoconfig" Create a ./.config file by setting symbol
|
||||
values to 'n' as much as possible.
|
||||
|
||||
"make randconfig" Create a ./.config file by setting symbol
|
||||
values to random values.
|
||||
|
||||
"make localmodconfig" Create a config based on current config and
|
||||
loaded modules (lsmod). Disables any module
|
||||
option that is not needed for the loaded modules.
|
||||
|
||||
To create a localmodconfig for another machine,
|
||||
store the lsmod of that machine into a file
|
||||
and pass it in as a LSMOD parameter.
|
||||
|
||||
target$ lsmod > /tmp/mylsmod
|
||||
target$ scp /tmp/mylsmod host:/tmp
|
||||
|
||||
host$ make LSMOD=/tmp/mylsmod localmodconfig
|
||||
|
||||
The above also works when cross compiling.
|
||||
|
||||
"make localyesconfig" Similar to localmodconfig, except it will convert
|
||||
all module options to built in (=y) options.
|
||||
|
||||
You can find more information on using the Linux kernel config tools
|
||||
in Documentation/kbuild/kconfig.txt.
|
||||
|
||||
- NOTES on ``make config``:
|
||||
|
||||
- Having unnecessary drivers will make the kernel bigger, and can
|
||||
under some circumstances lead to problems: probing for a
|
||||
nonexistent controller card may confuse your other controllers
|
||||
|
||||
- A kernel with math-emulation compiled in will still use the
|
||||
coprocessor if one is present: the math emulation will just
|
||||
never get used in that case. The kernel will be slightly larger,
|
||||
but will work on different machines regardless of whether they
|
||||
have a math coprocessor or not.
|
||||
|
||||
- The "kernel hacking" configuration details usually result in a
|
||||
bigger or slower kernel (or both), and can even make the kernel
|
||||
less stable by configuring some routines to actively try to
|
||||
break bad code to find kernel problems (kmalloc()). Thus you
|
||||
should probably answer 'n' to the questions for "development",
|
||||
"experimental", or "debugging" features.
|
||||
|
||||
Compiling the kernel
|
||||
--------------------
|
||||
|
||||
- Make sure you have at least gcc 3.2 available.
|
||||
For more information, refer to :ref:`Documentation/process/changes.rst <changes>`.
|
||||
|
||||
Please note that you can still run a.out user programs with this kernel.
|
||||
|
||||
- Do a ``make`` to create a compressed kernel image. It is also
|
||||
possible to do ``make install`` if you have lilo installed to suit the
|
||||
kernel makefiles, but you may want to check your particular lilo setup first.
|
||||
|
||||
To do the actual install, you have to be root, but none of the normal
|
||||
build should require that. Don't take the name of root in vain.
|
||||
|
||||
- If you configured any of the parts of the kernel as ``modules``, you
|
||||
will also have to do ``make modules_install``.
|
||||
|
||||
- Verbose kernel compile/build output:
|
||||
|
||||
Normally, the kernel build system runs in a fairly quiet mode (but not
|
||||
totally silent). However, sometimes you or other kernel developers need
|
||||
to see compile, link, or other commands exactly as they are executed.
|
||||
For this, use "verbose" build mode. This is done by passing
|
||||
``V=1`` to the ``make`` command, e.g.::
|
||||
|
||||
make V=1 all
|
||||
|
||||
To have the build system also tell the reason for the rebuild of each
|
||||
target, use ``V=2``. The default is ``V=0``.
|
||||
|
||||
- Keep a backup kernel handy in case something goes wrong. This is
|
||||
especially true for the development releases, since each new release
|
||||
contains new code which has not been debugged. Make sure you keep a
|
||||
backup of the modules corresponding to that kernel, as well. If you
|
||||
are installing a new kernel with the same version number as your
|
||||
working kernel, make a backup of your modules directory before you
|
||||
do a ``make modules_install``.
|
||||
|
||||
Alternatively, before compiling, use the kernel config option
|
||||
"LOCALVERSION" to append a unique suffix to the regular kernel version.
|
||||
LOCALVERSION can be set in the "General Setup" menu.
|
||||
|
||||
- In order to boot your new kernel, you'll need to copy the kernel
|
||||
image (e.g. .../linux/arch/x86/boot/bzImage after compilation)
|
||||
to the place where your regular bootable kernel is found.
|
||||
|
||||
- Booting a kernel directly from a floppy without the assistance of a
|
||||
bootloader such as LILO, is no longer supported.
|
||||
|
||||
If you boot Linux from the hard drive, chances are you use LILO, which
|
||||
uses the kernel image as specified in the file /etc/lilo.conf. The
|
||||
kernel image file is usually /vmlinuz, /boot/vmlinuz, /bzImage or
|
||||
/boot/bzImage. To use the new kernel, save a copy of the old image
|
||||
and copy the new image over the old one. Then, you MUST RERUN LILO
|
||||
to update the loading map! If you don't, you won't be able to boot
|
||||
the new kernel image.
|
||||
|
||||
Reinstalling LILO is usually a matter of running /sbin/lilo.
|
||||
You may wish to edit /etc/lilo.conf to specify an entry for your
|
||||
old kernel image (say, /vmlinux.old) in case the new one does not
|
||||
work. See the LILO docs for more information.
|
||||
|
||||
After reinstalling LILO, you should be all set. Shutdown the system,
|
||||
reboot, and enjoy!
|
||||
|
||||
If you ever need to change the default root device, video mode,
|
||||
ramdisk size, etc. in the kernel image, use the ``rdev`` program (or
|
||||
alternatively the LILO boot options when appropriate). No need to
|
||||
recompile the kernel to change these parameters.
|
||||
|
||||
- Reboot with the new kernel and enjoy.
|
||||
|
||||
If something goes wrong
|
||||
-----------------------
|
||||
|
||||
- If you have problems that seem to be due to kernel bugs, please check
|
||||
the file MAINTAINERS to see if there is a particular person associated
|
||||
with the part of the kernel that you are having trouble with. If there
|
||||
isn't anyone listed there, then the second best thing is to mail
|
||||
them to me (torvalds@linux-foundation.org), and possibly to any other
|
||||
relevant mailing-list or to the newsgroup.
|
||||
|
||||
- In all bug-reports, *please* tell what kernel you are talking about,
|
||||
how to duplicate the problem, and what your setup is (use your common
|
||||
sense). If the problem is new, tell me so, and if the problem is
|
||||
old, please try to tell me when you first noticed it.
|
||||
|
||||
- If the bug results in a message like::
|
||||
|
||||
unable to handle kernel paging request at address C0000010
|
||||
Oops: 0002
|
||||
EIP: 0010:XXXXXXXX
|
||||
eax: xxxxxxxx ebx: xxxxxxxx ecx: xxxxxxxx edx: xxxxxxxx
|
||||
esi: xxxxxxxx edi: xxxxxxxx ebp: xxxxxxxx
|
||||
ds: xxxx es: xxxx fs: xxxx gs: xxxx
|
||||
Pid: xx, process nr: xx
|
||||
xx xx xx xx xx xx xx xx xx xx
|
||||
|
||||
or similar kernel debugging information on your screen or in your
|
||||
system log, please duplicate it *exactly*. The dump may look
|
||||
incomprehensible to you, but it does contain information that may
|
||||
help debugging the problem. The text above the dump is also
|
||||
important: it tells something about why the kernel dumped code (in
|
||||
the above example, it's due to a bad kernel pointer). More information
|
||||
on making sense of the dump is in Documentation/admin-guide/oops-tracing.rst
|
||||
|
||||
- If you compiled the kernel with CONFIG_KALLSYMS you can send the dump
|
||||
as is, otherwise you will have to use the ``ksymoops`` program to make
|
||||
sense of the dump (but compiling with CONFIG_KALLSYMS is usually preferred).
|
||||
This utility can be downloaded from
|
||||
ftp://ftp.<country>.kernel.org/pub/linux/utils/kernel/ksymoops/ .
|
||||
Alternatively, you can do the dump lookup by hand:
|
||||
|
||||
- In debugging dumps like the above, it helps enormously if you can
|
||||
look up what the EIP value means. The hex value as such doesn't help
|
||||
me or anybody else very much: it will depend on your particular
|
||||
kernel setup. What you should do is take the hex value from the EIP
|
||||
line (ignore the ``0010:``), and look it up in the kernel namelist to
|
||||
see which kernel function contains the offending address.
|
||||
|
||||
To find out the kernel function name, you'll need to find the system
|
||||
binary associated with the kernel that exhibited the symptom. This is
|
||||
the file 'linux/vmlinux'. To extract the namelist and match it against
|
||||
the EIP from the kernel crash, do::
|
||||
|
||||
nm vmlinux | sort | less
|
||||
|
||||
This will give you a list of kernel addresses sorted in ascending
|
||||
order, from which it is simple to find the function that contains the
|
||||
offending address. Note that the address given by the kernel
|
||||
debugging messages will not necessarily match exactly with the
|
||||
function addresses (in fact, that is very unlikely), so you can't
|
||||
just 'grep' the list: the list will, however, give you the starting
|
||||
point of each kernel function, so by looking for the function that
|
||||
has a starting address lower than the one you are searching for but
|
||||
is followed by a function with a higher address you will find the one
|
||||
you want. In fact, it may be a good idea to include a bit of
|
||||
"context" in your problem report, giving a few lines around the
|
||||
interesting one.
|
||||
|
||||
If you for some reason cannot do the above (you have a pre-compiled
|
||||
kernel image or similar), telling me as much about your setup as
|
||||
possible will help. Please read the :ref:`admin-guide/reporting-bugs.rst <reportingbugs>`
|
||||
document for details.
|
||||
|
||||
- Alternatively, you can use gdb on a running kernel. (read-only; i.e. you
|
||||
cannot change values or set break points.) To do this, first compile the
|
||||
kernel with -g; edit arch/x86/Makefile appropriately, then do a ``make
|
||||
clean``. You'll also need to enable CONFIG_PROC_FS (via ``make config``).
|
||||
|
||||
After you've rebooted with the new kernel, do ``gdb vmlinux /proc/kcore``.
|
||||
You can now use all the usual gdb commands. The command to look up the
|
||||
point where your system crashed is ``l *0xXXXXXXXX``. (Replace the XXXes
|
||||
with the EIP value.)
|
||||
|
||||
gdb'ing a non-running kernel currently fails because ``gdb`` (wrongly)
|
||||
disregards the starting offset for which the kernel is compiled.
|
||||
@@ -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,18 @@ 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 admin-guide/kernel-parameters.rst 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
|
||||
@@ -0,0 +1,68 @@
|
||||
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.
|
||||
|
||||
``<test>`` is the thing you're trying to measure.
|
||||
Make sure you have the correct ``System.map`` / ``vmlinux`` referenced!
|
||||
|
||||
It is probably easiest to use ``make install`` for linux and hack
|
||||
``/sbin/installkernel`` to copy ``vmlinux`` to ``/boot``, in addition to
|
||||
``vmlinuz``, ``config``, ``System.map``, which are usually installed by default.
|
||||
|
||||
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
|
||||
<test>
|
||||
dump output readprofile -m /boot/System.map > captured_profile
|
||||
|
||||
Oprofile
|
||||
--------
|
||||
|
||||
Get the source (see Changes for required version) from
|
||||
http://oprofile.sourceforge.net/ and add ``idle=poll`` to the kernel command
|
||||
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
|
||||
<test>
|
||||
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.
|
||||
@@ -0,0 +1,151 @@
|
||||
Kernel Support for miscellaneous (your favourite) Binary Formats v1.1
|
||||
=====================================================================
|
||||
|
||||
This Kernel feature allows you to invoke almost (for restrictions see below)
|
||||
every program by simply typing its name in the shell.
|
||||
This includes for example compiled Java(TM), Python or Emacs programs.
|
||||
|
||||
To achieve this you must tell binfmt_misc which interpreter has to be invoked
|
||||
with which binary. Binfmt_misc recognises the binary-type by matching some bytes
|
||||
at the beginning of the file with a magic byte sequence (masking out specified
|
||||
bits) you have supplied. Binfmt_misc can also recognise a filename extension
|
||||
aka ``.com`` or ``.exe``.
|
||||
|
||||
First you must mount binfmt_misc::
|
||||
|
||||
mount binfmt_misc -t binfmt_misc /proc/sys/fs/binfmt_misc
|
||||
|
||||
To actually register a new binary type, you have to set up a string looking like
|
||||
``:name:type:offset:magic:mask:interpreter:flags`` (where you can choose the
|
||||
``:`` upon your needs) and echo it to ``/proc/sys/fs/binfmt_misc/register``.
|
||||
|
||||
Here is what the fields mean:
|
||||
|
||||
- ``name``
|
||||
is an identifier string. A new /proc file will be created with this
|
||||
``name below /proc/sys/fs/binfmt_misc``; cannot contain slashes ``/`` for
|
||||
obvious reasons.
|
||||
- ``type``
|
||||
is the type of recognition. Give ``M`` for magic and ``E`` for extension.
|
||||
- ``offset``
|
||||
is the offset of the magic/mask in the file, counted in bytes. This
|
||||
defaults to 0 if you omit it (i.e. you write ``:name:type::magic...``).
|
||||
Ignored when using filename extension matching.
|
||||
- ``magic``
|
||||
is the byte sequence binfmt_misc is matching for. The magic string
|
||||
may contain hex-encoded characters like ``\x0a`` or ``\xA4``. Note that you
|
||||
must escape any NUL bytes; parsing halts at the first one. In a shell
|
||||
environment you might have to write ``\\x0a`` to prevent the shell from
|
||||
eating your ``\``.
|
||||
If you chose filename extension matching, this is the extension to be
|
||||
recognised (without the ``.``, the ``\x0a`` specials are not allowed).
|
||||
Extension matching is case sensitive, and slashes ``/`` are not allowed!
|
||||
- ``mask``
|
||||
is an (optional, defaults to all 0xff) mask. You can mask out some
|
||||
bits from matching by supplying a string like magic and as long as magic.
|
||||
The mask is anded with the byte sequence of the file. Note that you must
|
||||
escape any NUL bytes; parsing halts at the first one. Ignored when using
|
||||
filename extension matching.
|
||||
- ``interpreter``
|
||||
is the program that should be invoked with the binary as first
|
||||
argument (specify the full path)
|
||||
- ``flags``
|
||||
is an optional field that controls several aspects of the invocation
|
||||
of the interpreter. It is a string of capital letters, each controls a
|
||||
certain aspect. The following flags are supported:
|
||||
|
||||
``P`` - preserve-argv[0]
|
||||
Legacy behavior of binfmt_misc is to overwrite
|
||||
the original argv[0] with the full path to the binary. When this
|
||||
flag is included, binfmt_misc will add an argument to the argument
|
||||
vector for this purpose, thus preserving the original ``argv[0]``.
|
||||
e.g. If your interp is set to ``/bin/foo`` and you run ``blah``
|
||||
(which is in ``/usr/local/bin``), then the kernel will execute
|
||||
``/bin/foo`` with ``argv[]`` set to ``["/bin/foo", "/usr/local/bin/blah", "blah"]``. The interp has to be aware of this so it can
|
||||
execute ``/usr/local/bin/blah``
|
||||
with ``argv[]`` set to ``["blah"]``.
|
||||
``O`` - open-binary
|
||||
Legacy behavior of binfmt_misc is to pass the full path
|
||||
of the binary to the interpreter as an argument. When this flag is
|
||||
included, binfmt_misc will open the file for reading and pass its
|
||||
descriptor as an argument, instead of the full path, thus allowing
|
||||
the interpreter to execute non-readable binaries. This feature
|
||||
should be used with care - the interpreter has to be trusted not to
|
||||
emit the contents of the non-readable binary.
|
||||
``C`` - credentials
|
||||
Currently, the behavior of binfmt_misc is to calculate
|
||||
the credentials and security token of the new process according to
|
||||
the interpreter. When this flag is included, these attributes are
|
||||
calculated according to the binary. It also implies the ``O`` flag.
|
||||
This feature should be used with care as the interpreter
|
||||
will run with root permissions when a setuid binary owned by root
|
||||
is run with binfmt_misc.
|
||||
``F`` - fix binary
|
||||
The usual behaviour of binfmt_misc is to spawn the
|
||||
binary lazily when the misc format file is invoked. However,
|
||||
this doesn``t work very well in the face of mount namespaces and
|
||||
changeroots, so the ``F`` mode opens the binary as soon as the
|
||||
emulation is installed and uses the opened image to spawn the
|
||||
emulator, meaning it is always available once installed,
|
||||
regardless of how the environment changes.
|
||||
|
||||
|
||||
There are some restrictions:
|
||||
|
||||
- the whole register string may not exceed 1920 characters
|
||||
- the magic must reside in the first 128 bytes of the file, i.e.
|
||||
offset+size(magic) has to be less than 128
|
||||
- the interpreter string may not exceed 127 characters
|
||||
|
||||
To use binfmt_misc you have to mount it first. You can mount it with
|
||||
``mount -t binfmt_misc none /proc/sys/fs/binfmt_misc`` command, or you can add
|
||||
a line ``none /proc/sys/fs/binfmt_misc binfmt_misc defaults 0 0`` to your
|
||||
``/etc/fstab`` so it auto mounts on boot.
|
||||
|
||||
You may want to add the binary formats in one of your ``/etc/rc`` scripts during
|
||||
boot-up. Read the manual of your init program to figure out how to do this
|
||||
right.
|
||||
|
||||
Think about the order of adding entries! Later added entries are matched first!
|
||||
|
||||
|
||||
A few examples (assumed you are in ``/proc/sys/fs/binfmt_misc``):
|
||||
|
||||
- enable support for em86 (like binfmt_em86, for Alpha AXP only)::
|
||||
|
||||
echo ':i386:M::\x7fELF\x01\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x02\x00\x03:\xff\xff\xff\xff\xff\xfe\xfe\xff\xff\xff\xff\xff\xff\xff\xff\xff\xfb\xff\xff:/bin/em86:' > register
|
||||
echo ':i486:M::\x7fELF\x01\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x02\x00\x06:\xff\xff\xff\xff\xff\xfe\xfe\xff\xff\xff\xff\xff\xff\xff\xff\xff\xfb\xff\xff:/bin/em86:' > register
|
||||
|
||||
- enable support for packed DOS applications (pre-configured dosemu hdimages)::
|
||||
|
||||
echo ':DEXE:M::\x0eDEX::/usr/bin/dosexec:' > register
|
||||
|
||||
- enable support for Windows executables using wine::
|
||||
|
||||
echo ':DOSWin:M::MZ::/usr/local/bin/wine:' > register
|
||||
|
||||
For java support see Documentation/admin-guide/java.rst
|
||||
|
||||
|
||||
You can enable/disable binfmt_misc or one binary type by echoing 0 (to disable)
|
||||
or 1 (to enable) to ``/proc/sys/fs/binfmt_misc/status`` or
|
||||
``/proc/.../the_name``.
|
||||
Catting the file tells you the current status of ``binfmt_misc/the_entry``.
|
||||
|
||||
You can remove one entry or all entries by echoing -1 to ``/proc/.../the_name``
|
||||
or ``/proc/sys/fs/binfmt_misc/status``.
|
||||
|
||||
|
||||
Hints
|
||||
-----
|
||||
|
||||
If you want to pass special arguments to your interpreter, you can
|
||||
write a wrapper script for it. See Documentation/admin-guide/java.rst for an
|
||||
example.
|
||||
|
||||
Your interpreter should NOT look in the PATH for the filename; the kernel
|
||||
passes it the full filename (or the file descriptor) to use. Using ``$PATH`` can
|
||||
cause unexpected behaviour and can be a security hazard.
|
||||
|
||||
|
||||
Richard Günther <rguenth@tat.physik.uni-tuebingen.de>
|
||||
@@ -0,0 +1,38 @@
|
||||
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 :ref:`Documentation/admin-guide/serial-console.rst <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::
|
||||
|
||||
console=brl,serial_options...
|
||||
|
||||
where ``serial_options...`` are the same as described in
|
||||
:ref:`Documentation/admin-guide/serial-console.rst <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.
|
||||
|
||||
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,
|
||||
: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
|
||||
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
|
||||
:ref:`Documentation/admin-guide/serial-console.rst <serial_console>`.
|
||||
|
||||
For now, only the VisioBraille device is supported.
|
||||
|
||||
Samuel Thibault <samuel.thibault@ens-lyon.org>
|
||||
@@ -1,18 +1,8 @@
|
||||
Table of contents
|
||||
=================
|
||||
Bug hunting
|
||||
+++++++++++
|
||||
|
||||
Last updated: 20 December 2005
|
||||
|
||||
Contents
|
||||
========
|
||||
|
||||
- Introduction
|
||||
- Devices not appearing
|
||||
- Finding patch that caused a bug
|
||||
-- Finding using git-bisect
|
||||
-- Finding it the old way
|
||||
- Fixing the bug
|
||||
|
||||
Introduction
|
||||
============
|
||||
|
||||
@@ -24,7 +14,8 @@ Finding bugs is not always easy. Have a go though. If you can't find it don't
|
||||
give up. Report as much as you have found to the relevant maintainer. See
|
||||
MAINTAINERS for who that is for the subsystem you have worked on.
|
||||
|
||||
Before you submit a bug report read REPORTING-BUGS.
|
||||
Before you submit a bug report read
|
||||
:ref:`Documentation/admin-guide/reporting-bugs.rst <reportingbugs>`.
|
||||
|
||||
Devices not appearing
|
||||
=====================
|
||||
@@ -37,15 +28,16 @@ Finding patch that caused a bug
|
||||
|
||||
|
||||
|
||||
Finding using git-bisect
|
||||
------------------------
|
||||
Finding using ``git-bisect``
|
||||
----------------------------
|
||||
|
||||
Using the provided tools with git makes finding bugs easy provided the bug is
|
||||
reproducible.
|
||||
Using the provided tools with ``git`` makes finding bugs easy provided the bug
|
||||
is reproducible.
|
||||
|
||||
Steps to do it:
|
||||
|
||||
- start using git for the kernel source
|
||||
- read the man page for git-bisect
|
||||
- read the man page for ``git-bisect``
|
||||
- have fun
|
||||
|
||||
Finding it the old way
|
||||
@@ -58,22 +50,22 @@ It's a brute force approach but it works pretty well.
|
||||
|
||||
You need:
|
||||
|
||||
. A reproducible bug - it has to happen predictably (sorry)
|
||||
. All the kernel tar files from a revision that worked to the
|
||||
- A reproducible bug - it has to happen predictably (sorry)
|
||||
- All the kernel tar files from a revision that worked to the
|
||||
revision that doesn't
|
||||
|
||||
You will then do:
|
||||
|
||||
. Rebuild a revision that you believe works, install, and verify that.
|
||||
. Do a binary search over the kernels to figure out which one
|
||||
- Rebuild a revision that you believe works, install, and verify that.
|
||||
- Do a binary search over the kernels to figure out which one
|
||||
introduced the bug. I.e., suppose 1.3.28 didn't have the bug, but
|
||||
you know that 1.3.69 does. Pick a kernel in the middle and build
|
||||
that, like 1.3.50. Build & test; if it works, pick the mid point
|
||||
between .50 and .69, else the mid point between .28 and .50.
|
||||
. You'll narrow it down to the kernel that introduced the bug. You
|
||||
- You'll narrow it down to the kernel that introduced the bug. You
|
||||
can probably do better than this but it gets tricky.
|
||||
|
||||
. Narrow it down to a subdirectory
|
||||
- Narrow it down to a subdirectory
|
||||
|
||||
- Copy kernel that works into "test". Let's say that 3.62 works,
|
||||
but 3.63 doesn't. So you diff -r those two kernels and come
|
||||
@@ -83,7 +75,7 @@ You will then do:
|
||||
Copy the non-working directory next to the working directory
|
||||
as "dir.63".
|
||||
One directory at time, try moving the working directory to
|
||||
"dir.62" and mv dir.63 dir"time, try
|
||||
"dir.62" and mv dir.63 dir"time, try::
|
||||
|
||||
mv dir dir.62
|
||||
mv dir.63 dir
|
||||
@@ -97,15 +89,15 @@ You will then do:
|
||||
found in my case that they were self explanatory - you may
|
||||
or may not want to give up when that happens.
|
||||
|
||||
. Narrow it down to a file
|
||||
- Narrow it down to a file
|
||||
|
||||
- You can apply the same technique to each file in the directory,
|
||||
hoping that the changes in that file are self contained.
|
||||
|
||||
. Narrow it down to a routine
|
||||
- Narrow it down to a routine
|
||||
|
||||
- You can take the old file and the new file and manually create
|
||||
a merged file that has
|
||||
a merged file that has::
|
||||
|
||||
#ifdef VER62
|
||||
routine()
|
||||
@@ -120,7 +112,7 @@ You will then do:
|
||||
#endif
|
||||
|
||||
And then walk through that file, one routine at a time and
|
||||
prefix it with
|
||||
prefix it with::
|
||||
|
||||
#define VER62
|
||||
/* both routines here */
|
||||
@@ -153,94 +145,105 @@ To debug a kernel, use objdump and look for the hex offset from the crash
|
||||
output to find the valid line of code/assembler. Without debug symbols, you
|
||||
will see the assembler code for the routine shown, but if your kernel has
|
||||
debug symbols the C code will also be available. (Debug symbols can be enabled
|
||||
in the kernel hacking menu of the menu configuration.) For example:
|
||||
in the kernel hacking menu of the menu configuration.) For example::
|
||||
|
||||
objdump -r -S -l --disassemble net/dccp/ipv4.o
|
||||
|
||||
NB.: you need to be at the top level of the kernel tree for this to pick up
|
||||
your C files.
|
||||
.. note::
|
||||
|
||||
You need to be at the top level of the kernel tree for this to pick up
|
||||
your C files.
|
||||
|
||||
If you don't have access to the code you can also debug on some crash dumps
|
||||
e.g. crash dump output as shown by Dave Miller.
|
||||
e.g. crash dump output as shown by Dave Miller::
|
||||
|
||||
> EIP is at ip_queue_xmit+0x14/0x4c0
|
||||
> ...
|
||||
> Code: 44 24 04 e8 6f 05 00 00 e9 e8 fe ff ff 8d 76 00 8d bc 27 00 00
|
||||
> 00 00 55 57 56 53 81 ec bc 00 00 00 8b ac 24 d0 00 00 00 8b 5d 08
|
||||
> <8b> 83 3c 01 00 00 89 44 24 14 8b 45 28 85 c0 89 44 24 18 0f 85
|
||||
>
|
||||
> Put the bytes into a "foo.s" file like this:
|
||||
>
|
||||
> .text
|
||||
> .globl foo
|
||||
> foo:
|
||||
> .byte .... /* bytes from Code: part of OOPS dump */
|
||||
>
|
||||
> Compile it with "gcc -c -o foo.o foo.s" then look at the output of
|
||||
> "objdump --disassemble foo.o".
|
||||
>
|
||||
> Output:
|
||||
>
|
||||
> ip_queue_xmit:
|
||||
> push %ebp
|
||||
> push %edi
|
||||
> push %esi
|
||||
> push %ebx
|
||||
> sub $0xbc, %esp
|
||||
> mov 0xd0(%esp), %ebp ! %ebp = arg0 (skb)
|
||||
> mov 0x8(%ebp), %ebx ! %ebx = skb->sk
|
||||
> mov 0x13c(%ebx), %eax ! %eax = inet_sk(sk)->opt
|
||||
EIP is at ip_queue_xmit+0x14/0x4c0
|
||||
...
|
||||
Code: 44 24 04 e8 6f 05 00 00 e9 e8 fe ff ff 8d 76 00 8d bc 27 00 00
|
||||
00 00 55 57 56 53 81 ec bc 00 00 00 8b ac 24 d0 00 00 00 8b 5d 08
|
||||
<8b> 83 3c 01 00 00 89 44 24 14 8b 45 28 85 c0 89 44 24 18 0f 85
|
||||
|
||||
Put the bytes into a "foo.s" file like this:
|
||||
|
||||
.text
|
||||
.globl foo
|
||||
foo:
|
||||
.byte .... /* bytes from Code: part of OOPS dump */
|
||||
|
||||
Compile it with "gcc -c -o foo.o foo.s" then look at the output of
|
||||
"objdump --disassemble foo.o".
|
||||
|
||||
Output:
|
||||
|
||||
ip_queue_xmit:
|
||||
push %ebp
|
||||
push %edi
|
||||
push %esi
|
||||
push %ebx
|
||||
sub $0xbc, %esp
|
||||
mov 0xd0(%esp), %ebp ! %ebp = arg0 (skb)
|
||||
mov 0x8(%ebp), %ebx ! %ebx = skb->sk
|
||||
mov 0x13c(%ebx), %eax ! %eax = inet_sk(sk)->opt
|
||||
|
||||
In addition, you can use GDB to figure out the exact file and line
|
||||
number of the OOPS from the vmlinux file. If you have
|
||||
CONFIG_DEBUG_INFO enabled, you can simply copy the EIP value from the
|
||||
OOPS:
|
||||
number of the OOPS from the ``vmlinux`` file. If you have
|
||||
``CONFIG_DEBUG_INFO`` enabled, you can simply copy the EIP value from the
|
||||
OOPS::
|
||||
|
||||
EIP: 0060:[<c021e50e>] Not tainted VLI
|
||||
|
||||
And use GDB to translate that to human-readable form:
|
||||
And use GDB to translate that to human-readable form::
|
||||
|
||||
gdb vmlinux
|
||||
(gdb) l *0xc021e50e
|
||||
|
||||
If you don't have CONFIG_DEBUG_INFO enabled, you use the function
|
||||
offset from the OOPS:
|
||||
If you don't have ``CONFIG_DEBUG_INFO`` enabled, you use the function
|
||||
offset from the OOPS::
|
||||
|
||||
EIP is at vt_ioctl+0xda8/0x1482
|
||||
|
||||
And recompile the kernel with CONFIG_DEBUG_INFO enabled:
|
||||
And recompile the kernel with ``CONFIG_DEBUG_INFO`` enabled::
|
||||
|
||||
make vmlinux
|
||||
gdb vmlinux
|
||||
(gdb) p vt_ioctl
|
||||
(gdb) l *(0x<address of vt_ioctl> + 0xda8)
|
||||
or, as one command
|
||||
|
||||
or, as one command::
|
||||
|
||||
(gdb) l *(vt_ioctl + 0xda8)
|
||||
|
||||
If you have a call trace, such as :-
|
||||
>Call Trace:
|
||||
> [<ffffffff8802c8e9>] :jbd:log_wait_commit+0xa3/0xf5
|
||||
> [<ffffffff810482d9>] autoremove_wake_function+0x0/0x2e
|
||||
> [<ffffffff8802770b>] :jbd:journal_stop+0x1be/0x1ee
|
||||
> ...
|
||||
If you have a call trace, such as::
|
||||
|
||||
Call Trace:
|
||||
[<ffffffff8802c8e9>] :jbd:log_wait_commit+0xa3/0xf5
|
||||
[<ffffffff810482d9>] autoremove_wake_function+0x0/0x2e
|
||||
[<ffffffff8802770b>] :jbd:journal_stop+0x1be/0x1ee
|
||||
...
|
||||
|
||||
this shows the problem in the :jbd: module. You can load that module in gdb
|
||||
and list the relevant code.
|
||||
and list the relevant code::
|
||||
|
||||
gdb fs/jbd/jbd.ko
|
||||
(gdb) p log_wait_commit
|
||||
(gdb) l *(0x<address> + 0xa3)
|
||||
or
|
||||
|
||||
or::
|
||||
|
||||
(gdb) l *(log_wait_commit + 0xa3)
|
||||
|
||||
|
||||
Another very useful option of the Kernel Hacking section in menuconfig is
|
||||
Debug memory allocations. This will help you see whether data has been
|
||||
initialised and not set before use etc. To see the values that get assigned
|
||||
with this look at mm/slab.c and search for POISON_INUSE. When using this an
|
||||
Oops will often show the poisoned data instead of zero which is the default.
|
||||
with this look at ``mm/slab.c`` and search for ``POISON_INUSE``. When using
|
||||
this an Oops will often show the poisoned data instead of zero which is the
|
||||
default.
|
||||
|
||||
Once you have worked out a fix please submit it upstream. After all open
|
||||
source is about sharing what you do and don't you want to be recognised for
|
||||
your genius?
|
||||
|
||||
Please do read Documentation/SubmittingPatches though to help your code get
|
||||
accepted.
|
||||
Please do read
|
||||
ref:`Documentation/process/submitting-patches.rst <submittingpatches>` though
|
||||
to help your code get accepted.
|
||||
@@ -0,0 +1,10 @@
|
||||
# -*- coding: utf-8; mode: python -*-
|
||||
|
||||
project = 'Linux Kernel User Documentation'
|
||||
|
||||
tags.add("subproject")
|
||||
|
||||
latex_documents = [
|
||||
('index', 'linux-user.tex', 'Linux Kernel User Documentation',
|
||||
'The kernel development community', 'manual'),
|
||||
]
|
||||
File diff suppressed because it is too large
Load Diff
@@ -0,0 +1,353 @@
|
||||
Dynamic debug
|
||||
+++++++++++++
|
||||
|
||||
|
||||
Introduction
|
||||
============
|
||||
|
||||
This document describes how to use the dynamic debug (dyndbg) feature.
|
||||
|
||||
Dynamic debug is designed to allow you to dynamically enable/disable
|
||||
kernel code to obtain additional kernel information. Currently, if
|
||||
``CONFIG_DYNAMIC_DEBUG`` is set, then all ``pr_debug()``/``dev_dbg()`` and
|
||||
``print_hex_dump_debug()``/``print_hex_dump_bytes()`` calls can be dynamically
|
||||
enabled per-callsite.
|
||||
|
||||
If ``CONFIG_DYNAMIC_DEBUG`` is not set, ``print_hex_dump_debug()`` is just
|
||||
shortcut for ``print_hex_dump(KERN_DEBUG)``.
|
||||
|
||||
For ``print_hex_dump_debug()``/``print_hex_dump_bytes()``, format string is
|
||||
its ``prefix_str`` argument, if it is constant string; or ``hexdump``
|
||||
in case ``prefix_str`` is build dynamically.
|
||||
|
||||
Dynamic debug has even more useful features:
|
||||
|
||||
* Simple query language allows turning on and off debugging
|
||||
statements by matching any combination of 0 or 1 of:
|
||||
|
||||
- source filename
|
||||
- function name
|
||||
- line number (including ranges of line numbers)
|
||||
- module name
|
||||
- format string
|
||||
|
||||
* Provides a debugfs control file: ``<debugfs>/dynamic_debug/control``
|
||||
which can be read to display the complete list of known debug
|
||||
statements, to help guide you
|
||||
|
||||
Controlling dynamic debug Behaviour
|
||||
===================================
|
||||
|
||||
The behaviour of ``pr_debug()``/``dev_dbg()`` are controlled via writing to a
|
||||
control file in the 'debugfs' filesystem. Thus, you must first mount
|
||||
the debugfs filesystem, in order to make use of this feature.
|
||||
Subsequently, we refer to the control file as:
|
||||
``<debugfs>/dynamic_debug/control``. For example, if you want to enable
|
||||
printing from source file ``svcsock.c``, line 1603 you simply do::
|
||||
|
||||
nullarbor:~ # echo 'file svcsock.c line 1603 +p' >
|
||||
<debugfs>/dynamic_debug/control
|
||||
|
||||
If you make a mistake with the syntax, the write will fail thus::
|
||||
|
||||
nullarbor:~ # echo 'file svcsock.c wtf 1 +p' >
|
||||
<debugfs>/dynamic_debug/control
|
||||
-bash: echo: write error: Invalid argument
|
||||
|
||||
Viewing Dynamic Debug Behaviour
|
||||
===============================
|
||||
|
||||
You can view the currently configured behaviour of all the debug
|
||||
statements via::
|
||||
|
||||
nullarbor:~ # cat <debugfs>/dynamic_debug/control
|
||||
# filename:lineno [module]function flags format
|
||||
/usr/src/packages/BUILD/sgi-enhancednfs-1.4/default/net/sunrpc/svc_rdma.c:323 [svcxprt_rdma]svc_rdma_cleanup =_ "SVCRDMA Module Removed, deregister RPC RDMA transport\012"
|
||||
/usr/src/packages/BUILD/sgi-enhancednfs-1.4/default/net/sunrpc/svc_rdma.c:341 [svcxprt_rdma]svc_rdma_init =_ "\011max_inline : %d\012"
|
||||
/usr/src/packages/BUILD/sgi-enhancednfs-1.4/default/net/sunrpc/svc_rdma.c:340 [svcxprt_rdma]svc_rdma_init =_ "\011sq_depth : %d\012"
|
||||
/usr/src/packages/BUILD/sgi-enhancednfs-1.4/default/net/sunrpc/svc_rdma.c:338 [svcxprt_rdma]svc_rdma_init =_ "\011max_requests : %d\012"
|
||||
...
|
||||
|
||||
|
||||
You can also apply standard Unix text manipulation filters to this
|
||||
data, e.g.::
|
||||
|
||||
nullarbor:~ # grep -i rdma <debugfs>/dynamic_debug/control | wc -l
|
||||
62
|
||||
|
||||
nullarbor:~ # grep -i tcp <debugfs>/dynamic_debug/control | wc -l
|
||||
42
|
||||
|
||||
The third column shows the currently enabled flags for each debug
|
||||
statement callsite (see below for definitions of the flags). The
|
||||
default value, with no flags enabled, is ``=_``. So you can view all
|
||||
the debug statement callsites with any non-default flags::
|
||||
|
||||
nullarbor:~ # awk '$3 != "=_"' <debugfs>/dynamic_debug/control
|
||||
# filename:lineno [module]function flags format
|
||||
/usr/src/packages/BUILD/sgi-enhancednfs-1.4/default/net/sunrpc/svcsock.c:1603 [sunrpc]svc_send p "svc_process: st_sendto returned %d\012"
|
||||
|
||||
Command Language Reference
|
||||
==========================
|
||||
|
||||
At the lexical level, a command comprises a sequence of words separated
|
||||
by spaces or tabs. So these are all equivalent::
|
||||
|
||||
nullarbor:~ # echo -c 'file svcsock.c line 1603 +p' >
|
||||
<debugfs>/dynamic_debug/control
|
||||
nullarbor:~ # echo -c ' file svcsock.c line 1603 +p ' >
|
||||
<debugfs>/dynamic_debug/control
|
||||
nullarbor:~ # echo -n 'file svcsock.c line 1603 +p' >
|
||||
<debugfs>/dynamic_debug/control
|
||||
|
||||
Command submissions are bounded by a write() system call.
|
||||
Multiple commands can be written together, separated by ``;`` or ``\n``::
|
||||
|
||||
~# echo "func pnpacpi_get_resources +p; func pnp_assign_mem +p" \
|
||||
> <debugfs>/dynamic_debug/control
|
||||
|
||||
If your query set is big, you can batch them too::
|
||||
|
||||
~# cat query-batch-file > <debugfs>/dynamic_debug/control
|
||||
|
||||
A another way is to use wildcard. The match rule support ``*`` (matches
|
||||
zero or more characters) and ``?`` (matches exactly one character).For
|
||||
example, you can match all usb drivers::
|
||||
|
||||
~# echo "file drivers/usb/* +p" > <debugfs>/dynamic_debug/control
|
||||
|
||||
At the syntactical level, a command comprises a sequence of match
|
||||
specifications, followed by a flags change specification::
|
||||
|
||||
command ::= match-spec* flags-spec
|
||||
|
||||
The match-spec's are used to choose a subset of the known pr_debug()
|
||||
callsites to which to apply the flags-spec. Think of them as a query
|
||||
with implicit ANDs between each pair. Note that an empty list of
|
||||
match-specs will select all debug statement callsites.
|
||||
|
||||
A match specification comprises a keyword, which controls the
|
||||
attribute of the callsite to be compared, and a value to compare
|
||||
against. Possible keywords are:::
|
||||
|
||||
match-spec ::= 'func' string |
|
||||
'file' string |
|
||||
'module' string |
|
||||
'format' string |
|
||||
'line' line-range
|
||||
|
||||
line-range ::= lineno |
|
||||
'-'lineno |
|
||||
lineno'-' |
|
||||
lineno'-'lineno
|
||||
|
||||
lineno ::= unsigned-int
|
||||
|
||||
.. note::
|
||||
|
||||
``line-range`` cannot contain space, e.g.
|
||||
"1-30" is valid range but "1 - 30" is not.
|
||||
|
||||
|
||||
The meanings of each keyword are:
|
||||
|
||||
func
|
||||
The given string is compared against the function name
|
||||
of each callsite. Example::
|
||||
|
||||
func svc_tcp_accept
|
||||
|
||||
file
|
||||
The given string is compared against either the full pathname, the
|
||||
src-root relative pathname, or the basename of the source file of
|
||||
each callsite. Examples::
|
||||
|
||||
file svcsock.c
|
||||
file kernel/freezer.c
|
||||
file /usr/src/packages/BUILD/sgi-enhancednfs-1.4/default/net/sunrpc/svcsock.c
|
||||
|
||||
module
|
||||
The given string is compared against the module name
|
||||
of each callsite. The module name is the string as
|
||||
seen in ``lsmod``, i.e. without the directory or the ``.ko``
|
||||
suffix and with ``-`` changed to ``_``. Examples::
|
||||
|
||||
module sunrpc
|
||||
module nfsd
|
||||
|
||||
format
|
||||
The given string is searched for in the dynamic debug format
|
||||
string. Note that the string does not need to match the
|
||||
entire format, only some part. Whitespace and other
|
||||
special characters can be escaped using C octal character
|
||||
escape ``\ooo`` notation, e.g. the space character is ``\040``.
|
||||
Alternatively, the string can be enclosed in double quote
|
||||
characters (``"``) or single quote characters (``'``).
|
||||
Examples::
|
||||
|
||||
format svcrdma: // many of the NFS/RDMA server pr_debugs
|
||||
format readahead // some pr_debugs in the readahead cache
|
||||
format nfsd:\040SETATTR // one way to match a format with whitespace
|
||||
format "nfsd: SETATTR" // a neater way to match a format with whitespace
|
||||
format 'nfsd: SETATTR' // yet another way to match a format with whitespace
|
||||
|
||||
line
|
||||
The given line number or range of line numbers is compared
|
||||
against the line number of each ``pr_debug()`` callsite. A single
|
||||
line number matches the callsite line number exactly. A
|
||||
range of line numbers matches any callsite between the first
|
||||
and last line number inclusive. An empty first number means
|
||||
the first line in the file, an empty line number means the
|
||||
last number in the file. Examples::
|
||||
|
||||
line 1603 // exactly line 1603
|
||||
line 1600-1605 // the six lines from line 1600 to line 1605
|
||||
line -1605 // the 1605 lines from line 1 to line 1605
|
||||
line 1600- // all lines from line 1600 to the end of the file
|
||||
|
||||
The flags specification comprises a change operation followed
|
||||
by one or more flag characters. The change operation is one
|
||||
of the characters::
|
||||
|
||||
- remove the given flags
|
||||
+ add the given flags
|
||||
= set the flags to the given flags
|
||||
|
||||
The flags are::
|
||||
|
||||
p enables the pr_debug() callsite.
|
||||
f Include the function name in the printed message
|
||||
l Include line number in the printed message
|
||||
m Include module name in the printed message
|
||||
t Include thread ID in messages not generated from interrupt context
|
||||
_ No flags are set. (Or'd with others on input)
|
||||
|
||||
For ``print_hex_dump_debug()`` and ``print_hex_dump_bytes()``, only ``p`` flag
|
||||
have meaning, other flags ignored.
|
||||
|
||||
For display, the flags are preceded by ``=``
|
||||
(mnemonic: what the flags are currently equal to).
|
||||
|
||||
Note the regexp ``^[-+=][flmpt_]+$`` matches a flags specification.
|
||||
To clear all flags at once, use ``=_`` or ``-flmpt``.
|
||||
|
||||
|
||||
Debug messages during Boot Process
|
||||
==================================
|
||||
|
||||
To activate debug messages for core code and built-in modules during
|
||||
the boot process, even before userspace and debugfs exists, use
|
||||
``dyndbg="QUERY"``, ``module.dyndbg="QUERY"``, or ``ddebug_query="QUERY"``
|
||||
(``ddebug_query`` is obsoleted by ``dyndbg``, and deprecated). QUERY follows
|
||||
the syntax described above, but must not exceed 1023 characters. Your
|
||||
bootloader may impose lower limits.
|
||||
|
||||
These ``dyndbg`` params are processed just after the ddebug tables are
|
||||
processed, as part of the arch_initcall. Thus you can enable debug
|
||||
messages in all code run after this arch_initcall via this boot
|
||||
parameter.
|
||||
|
||||
On an x86 system for example ACPI enablement is a subsys_initcall and::
|
||||
|
||||
dyndbg="file ec.c +p"
|
||||
|
||||
will show early Embedded Controller transactions during ACPI setup if
|
||||
your machine (typically a laptop) has an Embedded Controller.
|
||||
PCI (or other devices) initialization also is a hot candidate for using
|
||||
this boot parameter for debugging purposes.
|
||||
|
||||
If ``foo`` module is not built-in, ``foo.dyndbg`` will still be processed at
|
||||
boot time, without effect, but will be reprocessed when module is
|
||||
loaded later. ``dyndbg_query=`` and bare ``dyndbg=`` are only processed at
|
||||
boot.
|
||||
|
||||
|
||||
Debug Messages at Module Initialization Time
|
||||
============================================
|
||||
|
||||
When ``modprobe foo`` is called, modprobe scans ``/proc/cmdline`` for
|
||||
``foo.params``, strips ``foo.``, and passes them to the kernel along with
|
||||
params given in modprobe args or ``/etc/modprob.d/*.conf`` files,
|
||||
in the following order:
|
||||
|
||||
1. parameters given via ``/etc/modprobe.d/*.conf``::
|
||||
|
||||
options foo dyndbg=+pt
|
||||
options foo dyndbg # defaults to +p
|
||||
|
||||
2. ``foo.dyndbg`` as given in boot args, ``foo.`` is stripped and passed::
|
||||
|
||||
foo.dyndbg=" func bar +p; func buz +mp"
|
||||
|
||||
3. args to modprobe::
|
||||
|
||||
modprobe foo dyndbg==pmf # override previous settings
|
||||
|
||||
These ``dyndbg`` queries are applied in order, with last having final say.
|
||||
This allows boot args to override or modify those from ``/etc/modprobe.d``
|
||||
(sensible, since 1 is system wide, 2 is kernel or boot specific), and
|
||||
modprobe args to override both.
|
||||
|
||||
In the ``foo.dyndbg="QUERY"`` form, the query must exclude ``module foo``.
|
||||
``foo`` is extracted from the param-name, and applied to each query in
|
||||
``QUERY``, and only 1 match-spec of each type is allowed.
|
||||
|
||||
The ``dyndbg`` option is a "fake" module parameter, which means:
|
||||
|
||||
- modules do not need to define it explicitly
|
||||
- every module gets it tacitly, whether they use pr_debug or not
|
||||
- it doesn't appear in ``/sys/module/$module/parameters/``
|
||||
To see it, grep the control file, or inspect ``/proc/cmdline.``
|
||||
|
||||
For ``CONFIG_DYNAMIC_DEBUG`` kernels, any settings given at boot-time (or
|
||||
enabled by ``-DDEBUG`` flag during compilation) can be disabled later via
|
||||
the sysfs interface if the debug messages are no longer needed::
|
||||
|
||||
echo "module module_name -p" > <debugfs>/dynamic_debug/control
|
||||
|
||||
Examples
|
||||
========
|
||||
|
||||
::
|
||||
|
||||
// enable the message at line 1603 of file svcsock.c
|
||||
nullarbor:~ # echo -n 'file svcsock.c line 1603 +p' >
|
||||
<debugfs>/dynamic_debug/control
|
||||
|
||||
// enable all the messages in file svcsock.c
|
||||
nullarbor:~ # echo -n 'file svcsock.c +p' >
|
||||
<debugfs>/dynamic_debug/control
|
||||
|
||||
// enable all the messages in the NFS server module
|
||||
nullarbor:~ # echo -n 'module nfsd +p' >
|
||||
<debugfs>/dynamic_debug/control
|
||||
|
||||
// enable all 12 messages in the function svc_process()
|
||||
nullarbor:~ # echo -n 'func svc_process +p' >
|
||||
<debugfs>/dynamic_debug/control
|
||||
|
||||
// disable all 12 messages in the function svc_process()
|
||||
nullarbor:~ # echo -n 'func svc_process -p' >
|
||||
<debugfs>/dynamic_debug/control
|
||||
|
||||
// enable messages for NFS calls READ, READLINK, READDIR and READDIR+.
|
||||
nullarbor:~ # echo -n 'format "nfsd: READ" +p' >
|
||||
<debugfs>/dynamic_debug/control
|
||||
|
||||
// enable messages in files of which the paths include string "usb"
|
||||
nullarbor:~ # echo -n '*usb* +p' > <debugfs>/dynamic_debug/control
|
||||
|
||||
// enable all messages
|
||||
nullarbor:~ # echo -n '+p' > <debugfs>/dynamic_debug/control
|
||||
|
||||
// add module, function to all enabled messages
|
||||
nullarbor:~ # echo -n '+mf' > <debugfs>/dynamic_debug/control
|
||||
|
||||
// boot-args example, with newlines and comments for readability
|
||||
Kernel command line: ...
|
||||
// see whats going on in dyndbg=value processing
|
||||
dynamic_debug.verbose=1
|
||||
// enable pr_debugs in 2 builtins, #cmt is stripped
|
||||
dyndbg="module params +p #cmt ; module sys +p"
|
||||
// enable pr_debugs in 2 functions in a module loaded later
|
||||
pc87360.dyndbg="func pc87360_init_device +p; func pc87360_find +p"
|
||||
@@ -0,0 +1,34 @@
|
||||
Linux Kernel User's Documentation
|
||||
=================================
|
||||
|
||||
Contents:
|
||||
|
||||
.. toctree::
|
||||
:maxdepth: 2
|
||||
:numbered:
|
||||
|
||||
README
|
||||
reporting-bugs
|
||||
bug-hunting
|
||||
oops-tracing
|
||||
ramoops
|
||||
initrd
|
||||
init
|
||||
dynamic-debug-howto
|
||||
security-bugs
|
||||
kernel-parameters
|
||||
serial-console
|
||||
braille-console
|
||||
parport
|
||||
md
|
||||
module-signing
|
||||
sysrq
|
||||
unicode
|
||||
vga-softcursor
|
||||
sysfs-rules
|
||||
devices
|
||||
binfmt-misc
|
||||
mono
|
||||
java
|
||||
bad-memory
|
||||
basic-profiling
|
||||
@@ -5,6 +5,7 @@ OK, so you've got this pretty unintuitive message (currently located
|
||||
in init/main.c) and are wondering what the H*** went wrong.
|
||||
Some high-level reasons for failure (listed roughly in order of execution)
|
||||
to load the init binary are:
|
||||
|
||||
A) Unable to mount root FS
|
||||
B) init binary doesn't exist on rootfs
|
||||
C) broken console device
|
||||
@@ -12,37 +13,39 @@ D) binary exists but dependencies not available
|
||||
E) binary cannot be loaded
|
||||
|
||||
Detailed explanations:
|
||||
0) Set "debug" kernel parameter (in bootloader config file or CONFIG_CMDLINE)
|
||||
|
||||
A) Set "debug" kernel parameter (in bootloader config file or CONFIG_CMDLINE)
|
||||
to get more detailed kernel messages.
|
||||
A) make sure you have the correct root FS type
|
||||
(and root= kernel parameter points to the correct partition),
|
||||
B) make sure you have the correct root FS type
|
||||
(and ``root=`` kernel parameter points to the correct partition),
|
||||
required drivers such as storage hardware (such as SCSI or USB!)
|
||||
and filesystem (ext3, jffs2 etc.) are builtin (alternatively as modules,
|
||||
to be pre-loaded by an initrd)
|
||||
C) Possibly a conflict in console= setup --> initial console unavailable.
|
||||
C) Possibly a conflict in ``console= setup`` --> initial console unavailable.
|
||||
E.g. some serial consoles are unreliable due to serial IRQ issues (e.g.
|
||||
missing interrupt-based configuration).
|
||||
Try using a different console= device or e.g. netconsole= .
|
||||
Try using a different ``console= device`` or e.g. ``netconsole=``.
|
||||
D) e.g. required library dependencies of the init binary such as
|
||||
/lib/ld-linux.so.2 missing or broken. Use readelf -d <INIT>|grep NEEDED
|
||||
to find out which libraries are required.
|
||||
``/lib/ld-linux.so.2`` missing or broken. Use
|
||||
``readelf -d <INIT>|grep NEEDED`` to find out which libraries are required.
|
||||
E) make sure the binary's architecture matches your hardware.
|
||||
E.g. i386 vs. x86_64 mismatch, or trying to load x86 on ARM hardware.
|
||||
In case you tried loading a non-binary file here (shell script?),
|
||||
you should make sure that the script specifies an interpreter in its shebang
|
||||
header line (#!/...) that is fully working (including its library
|
||||
header line (``#!/...``) that is fully working (including its library
|
||||
dependencies). And before tackling scripts, better first test a simple
|
||||
non-script binary such as /bin/sh and confirm its successful execution.
|
||||
To find out more, add code to init/main.c to display kernel_execve()s
|
||||
non-script binary such as ``/bin/sh`` and confirm its successful execution.
|
||||
To find out more, add code ``to init/main.c`` to display kernel_execve()s
|
||||
return values.
|
||||
|
||||
Please extend this explanation whenever you find new failure causes
|
||||
(after all loading the init binary is a CRITICAL and hard transition step
|
||||
which needs to be made as painless as possible), then submit patch to LKML.
|
||||
Further TODOs:
|
||||
- Implement the various run_init_process() invocations via a struct array
|
||||
which can then store the kernel_execve() result value and on failure
|
||||
log it all by iterating over _all_ results (very important usability fix).
|
||||
|
||||
- Implement the various ``run_init_process()`` invocations via a struct array
|
||||
which can then store the ``kernel_execve()`` result value and on failure
|
||||
log it all by iterating over **all** results (very important usability fix).
|
||||
- try to make the implementation itself more helpful in general,
|
||||
e.g. by providing additional error messages at affected places.
|
||||
|
||||
@@ -2,7 +2,7 @@ Using the initial RAM disk (initrd)
|
||||
===================================
|
||||
|
||||
Written 1996,2000 by Werner Almesberger <werner.almesberger@epfl.ch> and
|
||||
Hans Lermen <lermen@fgan.de>
|
||||
Hans Lermen <lermen@fgan.de>
|
||||
|
||||
|
||||
initrd provides the capability to load a RAM disk by the boot loader.
|
||||
@@ -16,7 +16,7 @@ where the kernel comes up with a minimum set of compiled-in drivers, and
|
||||
where additional modules are loaded from initrd.
|
||||
|
||||
This document gives a brief overview of the use of initrd. A more detailed
|
||||
discussion of the boot process can be found in [1].
|
||||
discussion of the boot process can be found in [#f1]_.
|
||||
|
||||
|
||||
Operation
|
||||
@@ -27,10 +27,10 @@ When using initrd, the system typically boots as follows:
|
||||
1) the boot loader loads the kernel and the initial RAM disk
|
||||
2) the kernel converts initrd into a "normal" RAM disk and
|
||||
frees the memory used by initrd
|
||||
3) if the root device is not /dev/ram0, the old (deprecated)
|
||||
3) if the root device is not ``/dev/ram0``, the old (deprecated)
|
||||
change_root procedure is followed. see the "Obsolete root change
|
||||
mechanism" section below.
|
||||
4) root device is mounted. if it is /dev/ram0, the initrd image is
|
||||
4) root device is mounted. if it is ``/dev/ram0``, the initrd image is
|
||||
then mounted as root
|
||||
5) /sbin/init is executed (this can be any valid executable, including
|
||||
shell scripts; it is run with uid 0 and can do basically everything
|
||||
@@ -38,7 +38,7 @@ When using initrd, the system typically boots as follows:
|
||||
6) init mounts the "real" root file system
|
||||
7) init places the root file system at the root directory using the
|
||||
pivot_root system call
|
||||
8) init execs the /sbin/init on the new root filesystem, performing
|
||||
8) init execs the ``/sbin/init`` on the new root filesystem, performing
|
||||
the usual boot sequence
|
||||
9) the initrd file system is removed
|
||||
|
||||
@@ -51,7 +51,7 @@ be accessible.
|
||||
Boot command-line options
|
||||
-------------------------
|
||||
|
||||
initrd adds the following new options:
|
||||
initrd adds the following new options::
|
||||
|
||||
initrd=<path> (e.g. LOADLIN)
|
||||
|
||||
@@ -83,36 +83,36 @@ Recent kernels have support for populating a ramdisk from a compressed cpio
|
||||
archive. On such systems, the creation of a ramdisk image doesn't need to
|
||||
involve special block devices or loopbacks; you merely create a directory on
|
||||
disk with the desired initrd content, cd to that directory, and run (as an
|
||||
example):
|
||||
example)::
|
||||
|
||||
find . | cpio --quiet -H newc -o | gzip -9 -n > /boot/imagefile.img
|
||||
find . | cpio --quiet -H newc -o | gzip -9 -n > /boot/imagefile.img
|
||||
|
||||
Examining the contents of an existing image file is just as simple:
|
||||
Examining the contents of an existing image file is just as simple::
|
||||
|
||||
mkdir /tmp/imagefile
|
||||
cd /tmp/imagefile
|
||||
gzip -cd /boot/imagefile.img | cpio -imd --quiet
|
||||
mkdir /tmp/imagefile
|
||||
cd /tmp/imagefile
|
||||
gzip -cd /boot/imagefile.img | cpio -imd --quiet
|
||||
|
||||
Installation
|
||||
------------
|
||||
|
||||
First, a directory for the initrd file system has to be created on the
|
||||
"normal" root file system, e.g.
|
||||
"normal" root file system, e.g.::
|
||||
|
||||
# mkdir /initrd
|
||||
# mkdir /initrd
|
||||
|
||||
The name is not relevant. More details can be found on the pivot_root(2)
|
||||
man page.
|
||||
The name is not relevant. More details can be found on the
|
||||
:manpage:`pivot_root(2)` man page.
|
||||
|
||||
If the root file system is created during the boot procedure (i.e. if
|
||||
you're building an install floppy), the root file system creation
|
||||
procedure should create the /initrd directory.
|
||||
procedure should create the ``/initrd`` directory.
|
||||
|
||||
If initrd will not be mounted in some cases, its content is still
|
||||
accessible if the following device has been created:
|
||||
accessible if the following device has been created::
|
||||
|
||||
# mknod /dev/initrd b 1 250
|
||||
# chmod 400 /dev/initrd
|
||||
# mknod /dev/initrd b 1 250
|
||||
# chmod 400 /dev/initrd
|
||||
|
||||
Second, the kernel has to be compiled with RAM disk support and with
|
||||
support for the initial RAM disk enabled. Also, at least all components
|
||||
@@ -131,60 +131,76 @@ kernels, at least three types of devices are suitable for that:
|
||||
We'll describe the loopback device method:
|
||||
|
||||
1) make sure loopback block devices are configured into the kernel
|
||||
2) create an empty file system of the appropriate size, e.g.
|
||||
# dd if=/dev/zero of=initrd bs=300k count=1
|
||||
# mke2fs -F -m0 initrd
|
||||
2) create an empty file system of the appropriate size, e.g.::
|
||||
|
||||
# dd if=/dev/zero of=initrd bs=300k count=1
|
||||
# mke2fs -F -m0 initrd
|
||||
|
||||
(if space is critical, you may want to use the Minix FS instead of Ext2)
|
||||
3) mount the file system, e.g.
|
||||
# mount -t ext2 -o loop initrd /mnt
|
||||
4) create the console device:
|
||||
3) mount the file system, e.g.::
|
||||
|
||||
# mount -t ext2 -o loop initrd /mnt
|
||||
|
||||
4) create the console device::
|
||||
|
||||
# mkdir /mnt/dev
|
||||
# mknod /mnt/dev/console c 5 1
|
||||
|
||||
5) copy all the files that are needed to properly use the initrd
|
||||
environment. Don't forget the most important file, /sbin/init
|
||||
Note that /sbin/init's permissions must include "x" (execute).
|
||||
environment. Don't forget the most important file, ``/sbin/init``
|
||||
|
||||
.. note:: ``/sbin/init`` permissions must include "x" (execute).
|
||||
|
||||
6) correct operation the initrd environment can frequently be tested
|
||||
even without rebooting with the command
|
||||
# chroot /mnt /sbin/init
|
||||
even without rebooting with the command::
|
||||
|
||||
# chroot /mnt /sbin/init
|
||||
|
||||
This is of course limited to initrds that do not interfere with the
|
||||
general system state (e.g. by reconfiguring network interfaces,
|
||||
overwriting mounted devices, trying to start already running demons,
|
||||
etc. Note however that it is usually possible to use pivot_root in
|
||||
such a chroot'ed initrd environment.)
|
||||
7) unmount the file system
|
||||
# umount /mnt
|
||||
7) unmount the file system::
|
||||
|
||||
# umount /mnt
|
||||
|
||||
8) the initrd is now in the file "initrd". Optionally, it can now be
|
||||
compressed
|
||||
# gzip -9 initrd
|
||||
compressed::
|
||||
|
||||
# gzip -9 initrd
|
||||
|
||||
For experimenting with initrd, you may want to take a rescue floppy and
|
||||
only add a symbolic link from /sbin/init to /bin/sh. Alternatively, you
|
||||
can try the experimental newlib environment [2] to create a small
|
||||
only add a symbolic link from ``/sbin/init`` to ``/bin/sh``. Alternatively, you
|
||||
can try the experimental newlib environment [#f2]_ to create a small
|
||||
initrd.
|
||||
|
||||
Finally, you have to boot the kernel and load initrd. Almost all Linux
|
||||
boot loaders support initrd. Since the boot process is still compatible
|
||||
with an older mechanism, the following boot command line parameters
|
||||
have to be given:
|
||||
have to be given::
|
||||
|
||||
root=/dev/ram0 rw
|
||||
|
||||
(rw is only necessary if writing to the initrd file system.)
|
||||
|
||||
With LOADLIN, you simply execute
|
||||
With LOADLIN, you simply execute::
|
||||
|
||||
LOADLIN <kernel> initrd=<disk_image>
|
||||
e.g. LOADLIN C:\LINUX\BZIMAGE initrd=C:\LINUX\INITRD.GZ root=/dev/ram0 rw
|
||||
|
||||
With LILO, you add the option INITRD=<path> to either the global section
|
||||
or to the section of the respective kernel in /etc/lilo.conf, and pass
|
||||
the options using APPEND, e.g.
|
||||
e.g.::
|
||||
|
||||
LOADLIN C:\LINUX\BZIMAGE initrd=C:\LINUX\INITRD.GZ root=/dev/ram0 rw
|
||||
|
||||
With LILO, you add the option ``INITRD=<path>`` to either the global section
|
||||
or to the section of the respective kernel in ``/etc/lilo.conf``, and pass
|
||||
the options using APPEND, e.g.::
|
||||
|
||||
image = /bzImage
|
||||
initrd = /boot/initrd.gz
|
||||
append = "root=/dev/ram0 rw"
|
||||
|
||||
and run /sbin/lilo
|
||||
and run ``/sbin/lilo``
|
||||
|
||||
For other boot loaders, please refer to the respective documentation.
|
||||
|
||||
@@ -204,33 +220,33 @@ The procedure involves the following steps:
|
||||
- unmounting the initrd file system and de-allocating the RAM disk
|
||||
|
||||
Mounting the new root file system is easy: it just needs to be mounted on
|
||||
a directory under the current root. Example:
|
||||
a directory under the current root. Example::
|
||||
|
||||
# mkdir /new-root
|
||||
# mount -o ro /dev/hda1 /new-root
|
||||
# mkdir /new-root
|
||||
# mount -o ro /dev/hda1 /new-root
|
||||
|
||||
The root change is accomplished with the pivot_root system call, which
|
||||
is also available via the pivot_root utility (see pivot_root(8) man
|
||||
page; pivot_root is distributed with util-linux version 2.10h or higher
|
||||
[3]). pivot_root moves the current root to a directory under the new
|
||||
is also available via the ``pivot_root`` utility (see :manpage:`pivot_root(8)`
|
||||
man page; ``pivot_root`` is distributed with util-linux version 2.10h or higher
|
||||
[#f3]_). ``pivot_root`` moves the current root to a directory under the new
|
||||
root, and puts the new root at its place. The directory for the old root
|
||||
must exist before calling pivot_root. Example:
|
||||
must exist before calling ``pivot_root``. Example::
|
||||
|
||||
# cd /new-root
|
||||
# mkdir initrd
|
||||
# pivot_root . initrd
|
||||
# cd /new-root
|
||||
# mkdir initrd
|
||||
# pivot_root . initrd
|
||||
|
||||
Now, the init process may still access the old root via its
|
||||
executable, shared libraries, standard input/output/error, and its
|
||||
current root directory. All these references are dropped by the
|
||||
following command:
|
||||
following command::
|
||||
|
||||
# exec chroot . what-follows <dev/console >dev/console 2>&1
|
||||
# exec chroot . what-follows <dev/console >dev/console 2>&1
|
||||
|
||||
Where what-follows is a program under the new root, e.g. /sbin/init
|
||||
Where what-follows is a program under the new root, e.g. ``/sbin/init``
|
||||
If the new root file system will be used with udev and has no valid
|
||||
/dev directory, udev must be initialized before invoking chroot in order
|
||||
to provide /dev/console.
|
||||
``/dev`` directory, udev must be initialized before invoking chroot in order
|
||||
to provide ``/dev/console``.
|
||||
|
||||
Note: implementation details of pivot_root may change with time. In order
|
||||
to ensure compatibility, the following points should be observed:
|
||||
@@ -244,13 +260,13 @@ to ensure compatibility, the following points should be observed:
|
||||
- use relative paths for dev/console in the exec command
|
||||
|
||||
Now, the initrd can be unmounted and the memory allocated by the RAM
|
||||
disk can be freed:
|
||||
disk can be freed::
|
||||
|
||||
# umount /initrd
|
||||
# blockdev --flushbufs /dev/ram0
|
||||
# umount /initrd
|
||||
# blockdev --flushbufs /dev/ram0
|
||||
|
||||
It is also possible to use initrd with an NFS-mounted root, see the
|
||||
pivot_root(8) man page for details.
|
||||
:manpage:`pivot_root(8)` man page for details.
|
||||
|
||||
|
||||
Usage scenarios
|
||||
@@ -263,21 +279,21 @@ as follows:
|
||||
1) system boots from floppy or other media with a minimal kernel
|
||||
(e.g. support for RAM disks, initrd, a.out, and the Ext2 FS) and
|
||||
loads initrd
|
||||
2) /sbin/init determines what is needed to (1) mount the "real" root FS
|
||||
2) ``/sbin/init`` determines what is needed to (1) mount the "real" root FS
|
||||
(i.e. device type, device drivers, file system) and (2) the
|
||||
distribution media (e.g. CD-ROM, network, tape, ...). This can be
|
||||
done by asking the user, by auto-probing, or by using a hybrid
|
||||
approach.
|
||||
3) /sbin/init loads the necessary kernel modules
|
||||
4) /sbin/init creates and populates the root file system (this doesn't
|
||||
3) ``/sbin/init`` loads the necessary kernel modules
|
||||
4) ``/sbin/init`` creates and populates the root file system (this doesn't
|
||||
have to be a very usable system yet)
|
||||
5) /sbin/init invokes pivot_root to change the root file system and
|
||||
5) ``/sbin/init`` invokes ``pivot_root`` to change the root file system and
|
||||
execs - via chroot - a program that continues the installation
|
||||
6) the boot loader is installed
|
||||
7) the boot loader is configured to load an initrd with the set of
|
||||
modules that was used to bring up the system (e.g. /initrd can be
|
||||
modules that was used to bring up the system (e.g. ``/initrd`` can be
|
||||
modified, then unmounted, and finally, the image is written from
|
||||
/dev/ram0 or /dev/rd/0 to a file)
|
||||
``/dev/ram0`` or ``/dev/rd/0`` to a file)
|
||||
8) now the system is bootable and additional installation tasks can be
|
||||
performed
|
||||
|
||||
@@ -290,7 +306,7 @@ different hardware configurations in a single administrative domain. In
|
||||
such cases, it is desirable to generate only a small set of kernels
|
||||
(ideally only one) and to keep the system-specific part of configuration
|
||||
information as small as possible. In this case, a common initrd could be
|
||||
generated with all the necessary modules. Then, only /sbin/init or a file
|
||||
generated with all the necessary modules. Then, only ``/sbin/init`` or a file
|
||||
read by it would have to be different.
|
||||
|
||||
A third scenario is more convenient recovery disks, because information
|
||||
@@ -301,9 +317,9 @@ auto-detection).
|
||||
|
||||
Last not least, CD-ROM distributors may use it for better installation
|
||||
from CD, e.g. by using a boot floppy and bootstrapping a bigger RAM disk
|
||||
via initrd from CD; or by booting via a loader like LOADLIN or directly
|
||||
via initrd from CD; or by booting via a loader like ``LOADLIN`` or directly
|
||||
from the CD-ROM, and loading the RAM disk from CD without need of
|
||||
floppies.
|
||||
floppies.
|
||||
|
||||
|
||||
Obsolete root change mechanism
|
||||
@@ -316,51 +332,52 @@ continued availability.
|
||||
It works by mounting the "real" root device (i.e. the one set with rdev
|
||||
in the kernel image or with root=... at the boot command line) as the
|
||||
root file system when linuxrc exits. The initrd file system is then
|
||||
unmounted, or, if it is still busy, moved to a directory /initrd, if
|
||||
unmounted, or, if it is still busy, moved to a directory ``/initrd``, if
|
||||
such a directory exists on the new root file system.
|
||||
|
||||
In order to use this mechanism, you do not have to specify the boot
|
||||
command options root, init, or rw. (If specified, they will affect
|
||||
the real root file system, not the initrd environment.)
|
||||
|
||||
|
||||
If /proc is mounted, the "real" root device can be changed from within
|
||||
linuxrc by writing the number of the new root FS device to the special
|
||||
file /proc/sys/kernel/real-root-dev, e.g.
|
||||
file /proc/sys/kernel/real-root-dev, e.g.::
|
||||
|
||||
# echo 0x301 >/proc/sys/kernel/real-root-dev
|
||||
|
||||
Note that the mechanism is incompatible with NFS and similar file
|
||||
systems.
|
||||
|
||||
This old, deprecated mechanism is commonly called "change_root", while
|
||||
the new, supported mechanism is called "pivot_root".
|
||||
This old, deprecated mechanism is commonly called ``change_root``, while
|
||||
the new, supported mechanism is called ``pivot_root``.
|
||||
|
||||
|
||||
Mixed change_root and pivot_root mechanism
|
||||
------------------------------------------
|
||||
|
||||
In case you did not want to use root=/dev/ram0 to trigger the pivot_root
|
||||
mechanism, you may create both /linuxrc and /sbin/init in your initrd image.
|
||||
In case you did not want to use ``root=/dev/ram0`` to trigger the pivot_root
|
||||
mechanism, you may create both ``/linuxrc`` and ``/sbin/init`` in your initrd
|
||||
image.
|
||||
|
||||
/linuxrc would contain only the following:
|
||||
``/linuxrc`` would contain only the following::
|
||||
|
||||
#! /bin/sh
|
||||
mount -n -t proc proc /proc
|
||||
echo 0x0100 >/proc/sys/kernel/real-root-dev
|
||||
umount -n /proc
|
||||
#! /bin/sh
|
||||
mount -n -t proc proc /proc
|
||||
echo 0x0100 >/proc/sys/kernel/real-root-dev
|
||||
umount -n /proc
|
||||
|
||||
Once linuxrc exited, the kernel would mount again your initrd as root,
|
||||
this time executing /sbin/init. Again, it would be the duty of this init
|
||||
to build the right environment (maybe using the root= device passed on
|
||||
the cmdline) before the final execution of the real /sbin/init.
|
||||
this time executing ``/sbin/init``. Again, it would be the duty of this init
|
||||
to build the right environment (maybe using the ``root= device`` passed on
|
||||
the cmdline) before the final execution of the real ``/sbin/init``.
|
||||
|
||||
|
||||
Resources
|
||||
---------
|
||||
|
||||
[1] Almesberger, Werner; "Booting Linux: The History and the Future"
|
||||
.. [#f1] Almesberger, Werner; "Booting Linux: The History and the Future"
|
||||
http://www.almesberger.net/cv/papers/ols2k-9.ps.gz
|
||||
[2] newlib package (experimental), with initrd example
|
||||
http://sources.redhat.com/newlib/
|
||||
[3] util-linux: Miscellaneous utilities for Linux
|
||||
http://www.kernel.org/pub/linux/utils/util-linux/
|
||||
.. [#f2] newlib package (experimental), with initrd example
|
||||
https://www.sourceware.org/newlib/
|
||||
.. [#f3] util-linux: Miscellaneous utilities for Linux
|
||||
https://www.kernel.org/pub/linux/utils/util-linux/
|
||||
Some files were not shown because too many files have changed in this diff Show More
Reference in New Issue
Block a user