From 3a61baddcec3e7873b49deb5804d3d6f39b92def Mon Sep 17 00:00:00 2001 From: Mauro Carvalho Chehab Date: Wed, 21 Sep 2016 10:04:16 -0300 Subject: Documentation/applying-patches.txt: fix a bad external link We can't use :ref: for external links. Signed-off-by: Mauro Carvalho Chehab --- Documentation/applying-patches.txt | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Documentation/applying-patches.txt b/Documentation/applying-patches.txt index 02ce4924468e..3395da13d415 100644 --- a/Documentation/applying-patches.txt +++ b/Documentation/applying-patches.txt @@ -427,7 +427,7 @@ The -mm patches are experimental patches released by Andrew Morton. In the past, -mm tree were used to also test subsystem patches, but this function is now done via the -:ref:`linux-next ` +`linux-next ` tree. The Subsystem maintainers push their patches first to linux-next, and, during the merge window, sends them directly to Linus. -- cgit v1.2.3 From 12983bcd822f5c13a0f350cc97bc9fb781cae944 Mon Sep 17 00:00:00 2001 From: Mauro Carvalho Chehab Date: Wed, 21 Sep 2016 13:14:35 -0300 Subject: Documentation/adding-syscalls.txt: convert it to ReST markup Convert adding-syscalls.txt to ReST markup and add it to the development-process book: - add extra lines to make Sphinx to correctly parse paragraphs; - use quote blocks for examples; - use monotonic font for dirs, function calls, etc; - mark manpage pages using the right markup; - add cross-reference to SubmittingPatches. Signed-off-by: Mauro Carvalho Chehab --- Documentation/adding-syscalls.txt | 527 ------------------------------------ Documentation/adding-syscals.txt | 542 ++++++++++++++++++++++++++++++++++++++ 2 files changed, 542 insertions(+), 527 deletions(-) delete mode 100644 Documentation/adding-syscalls.txt create mode 100644 Documentation/adding-syscals.txt diff --git a/Documentation/adding-syscalls.txt b/Documentation/adding-syscalls.txt deleted file mode 100644 index bbb31e091b28..000000000000 --- a/Documentation/adding-syscalls.txt +++ /dev/null @@ -1,527 +0,0 @@ -Adding a New System Call -======================== - -This document describes what's involved in adding a new system call to the -Linux kernel, over and above the normal submission advice in -Documentation/SubmittingPatches. - - -System Call Alternatives ------------------------- - -The first thing to consider when adding a new system call is whether one of -the alternatives might be suitable instead. Although system calls are the -most traditional and most obvious interaction points between userspace and the -kernel, there are other possibilities -- choose what fits best for your -interface. - - - If the operations involved can be made to look like a filesystem-like - object, it may make more sense to create a new filesystem or device. This - also makes it easier to encapsulate the new functionality in a kernel module - rather than requiring it to be built into the main kernel. - - If the new functionality involves operations where the kernel notifies - userspace that something has happened, then returning a new file - descriptor for the relevant object allows userspace to use - poll/select/epoll to receive that notification. - - However, operations that don't map to read(2)/write(2)-like operations - have to be implemented as ioctl(2) requests, which can lead to a - somewhat opaque API. - - If you're just exposing runtime system information, a new node in sysfs - (see Documentation/filesystems/sysfs.txt) or the /proc filesystem may be - more appropriate. However, access to these mechanisms requires that the - relevant filesystem is mounted, which might not always be the case (e.g. - in a namespaced/sandboxed/chrooted environment). Avoid adding any API to - debugfs, as this is not considered a 'production' interface to userspace. - - If the operation is specific to a particular file or file descriptor, then - an additional fcntl(2) command option may be more appropriate. However, - fcntl(2) is a multiplexing system call that hides a lot of complexity, so - this option is best for when the new function is closely analogous to - existing fcntl(2) functionality, or the new functionality is very simple - (for example, getting/setting a simple flag related to a file descriptor). - - If the operation is specific to a particular task or process, then an - additional prctl(2) command option may be more appropriate. As with - fcntl(2), this system call is a complicated multiplexor so is best reserved - for near-analogs of existing prctl() commands or getting/setting a simple - flag related to a process. - - -Designing the API: Planning for Extension ------------------------------------------ - -A new system call forms part of the API of the kernel, and has to be supported -indefinitely. As such, it's a very good idea to explicitly discuss the -interface on the kernel mailing list, and it's important to plan for future -extensions of the interface. - -(The syscall table is littered with historical examples where this wasn't done, -together with the corresponding follow-up system calls -- eventfd/eventfd2, -dup2/dup3, inotify_init/inotify_init1, pipe/pipe2, renameat/renameat2 -- so -learn from the history of the kernel and plan for extensions from the start.) - -For simpler system calls that only take a couple of arguments, the preferred -way to allow for future extensibility is to include a flags argument to the -system call. To make sure that userspace programs can safely use flags -between kernel versions, check whether the flags value holds any unknown -flags, and reject the system call (with EINVAL) if it does: - - if (flags & ~(THING_FLAG1 | THING_FLAG2 | THING_FLAG3)) - return -EINVAL; - -(If no flags values are used yet, check that the flags argument is zero.) - -For more sophisticated system calls that involve a larger number of arguments, -it's preferred to encapsulate the majority of the arguments into a structure -that is passed in by pointer. Such a structure can cope with future extension -by including a size argument in the structure: - - struct xyzzy_params { - u32 size; /* userspace sets p->size = sizeof(struct xyzzy_params) */ - u32 param_1; - u64 param_2; - u64 param_3; - }; - -As long as any subsequently added field, say param_4, is designed so that a -zero value gives the previous behaviour, then this allows both directions of -version mismatch: - - - To cope with a later userspace program calling an older kernel, the kernel - code should check that any memory beyond the size of the structure that it - expects is zero (effectively checking that param_4 == 0). - - To cope with an older userspace program calling a newer kernel, the kernel - code can zero-extend a smaller instance of the structure (effectively - setting param_4 = 0). - -See perf_event_open(2) and the perf_copy_attr() function (in -kernel/events/core.c) for an example of this approach. - - -Designing the API: Other Considerations ---------------------------------------- - -If your new system call allows userspace to refer to a kernel object, it -should use a file descriptor as the handle for that object -- don't invent a -new type of userspace object handle when the kernel already has mechanisms and -well-defined semantics for using file descriptors. - -If your new xyzzy(2) system call does return a new file descriptor, then the -flags argument should include a value that is equivalent to setting O_CLOEXEC -on the new FD. This makes it possible for userspace to close the timing -window between xyzzy() and calling fcntl(fd, F_SETFD, FD_CLOEXEC), where an -unexpected fork() and execve() in another thread could leak a descriptor to -the exec'ed program. (However, resist the temptation to re-use the actual value -of the O_CLOEXEC constant, as it is architecture-specific and is part of a -numbering space of O_* flags that is fairly full.) - -If your system call returns a new file descriptor, you should also consider -what it means to use the poll(2) family of system calls on that file -descriptor. Making a file descriptor ready for reading or writing is the -normal way for the kernel to indicate to userspace that an event has -occurred on the corresponding kernel object. - -If your new xyzzy(2) system call involves a filename argument: - - int sys_xyzzy(const char __user *path, ..., unsigned int flags); - -you should also consider whether an xyzzyat(2) version is more appropriate: - - int sys_xyzzyat(int dfd, const char __user *path, ..., unsigned int flags); - -This allows more flexibility for how userspace specifies the file in question; -in particular it allows userspace to request the functionality for an -already-opened file descriptor using the AT_EMPTY_PATH flag, effectively giving -an fxyzzy(3) operation for free: - - - xyzzyat(AT_FDCWD, path, ..., 0) is equivalent to xyzzy(path,...) - - xyzzyat(fd, "", ..., AT_EMPTY_PATH) is equivalent to fxyzzy(fd, ...) - -(For more details on the rationale of the *at() calls, see the openat(2) man -page; for an example of AT_EMPTY_PATH, see the fstatat(2) man page.) - -If your new xyzzy(2) system call involves a parameter describing an offset -within a file, make its type loff_t so that 64-bit offsets can be supported -even on 32-bit architectures. - -If your new xyzzy(2) system call involves privileged functionality, it needs -to be governed by the appropriate Linux capability bit (checked with a call to -capable()), as described in the capabilities(7) man page. Choose an existing -capability bit that governs related functionality, but try to avoid combining -lots of only vaguely related functions together under the same bit, as this -goes against capabilities' purpose of splitting the power of root. In -particular, avoid adding new uses of the already overly-general CAP_SYS_ADMIN -capability. - -If your new xyzzy(2) system call manipulates a process other than the calling -process, it should be restricted (using a call to ptrace_may_access()) so that -only a calling process with the same permissions as the target process, or -with the necessary capabilities, can manipulate the target process. - -Finally, be aware that some non-x86 architectures have an easier time if -system call parameters that are explicitly 64-bit fall on odd-numbered -arguments (i.e. parameter 1, 3, 5), to allow use of contiguous pairs of 32-bit -registers. (This concern does not apply if the arguments are part of a -structure that's passed in by pointer.) - - -Proposing the API ------------------ - -To make new system calls easy to review, it's best to divide up the patchset -into separate chunks. These should include at least the following items as -distinct commits (each of which is described further below): - - - The core implementation of the system call, together with prototypes, - generic numbering, Kconfig changes and fallback stub implementation. - - Wiring up of the new system call for one particular architecture, usually - x86 (including all of x86_64, x86_32 and x32). - - A demonstration of the use of the new system call in userspace via a - selftest in tools/testing/selftests/. - - A draft man-page for the new system call, either as plain text in the - cover letter, or as a patch to the (separate) man-pages repository. - -New system call proposals, like any change to the kernel's API, should always -be cc'ed to linux-api@vger.kernel.org. - - -Generic System Call Implementation ----------------------------------- - -The main entry point for your new xyzzy(2) system call will be called -sys_xyzzy(), but you add this entry point with the appropriate -SYSCALL_DEFINEn() macro rather than explicitly. The 'n' indicates the number -of arguments to the system call, and the macro takes the system call name -followed by the (type, name) pairs for the parameters as arguments. Using -this macro allows metadata about the new system call to be made available for -other tools. - -The new entry point also needs a corresponding function prototype, in -include/linux/syscalls.h, marked as asmlinkage to match the way that system -calls are invoked: - - asmlinkage long sys_xyzzy(...); - -Some architectures (e.g. x86) have their own architecture-specific syscall -tables, but several other architectures share a generic syscall table. Add your -new system call to the generic list by adding an entry to the list in -include/uapi/asm-generic/unistd.h: - - #define __NR_xyzzy 292 - __SYSCALL(__NR_xyzzy, sys_xyzzy) - -Also update the __NR_syscalls count to reflect the additional system call, and -note that if multiple new system calls are added in the same merge window, -your new syscall number may get adjusted to resolve conflicts. - -The file kernel/sys_ni.c provides a fallback stub implementation of each system -call, returning -ENOSYS. Add your new system call here too: - - cond_syscall(sys_xyzzy); - -Your new kernel functionality, and the system call that controls it, should -normally be optional, so add a CONFIG option (typically to init/Kconfig) for -it. As usual for new CONFIG options: - - - Include a description of the new functionality and system call controlled - by the option. - - Make the option depend on EXPERT if it should be hidden from normal users. - - Make any new source files implementing the function dependent on the CONFIG - option in the Makefile (e.g. "obj-$(CONFIG_XYZZY_SYSCALL) += xyzzy.c"). - - Double check that the kernel still builds with the new CONFIG option turned - off. - -To summarize, you need a commit that includes: - - - CONFIG option for the new function, normally in init/Kconfig - - SYSCALL_DEFINEn(xyzzy, ...) for the entry point - - corresponding prototype in include/linux/syscalls.h - - generic table entry in include/uapi/asm-generic/unistd.h - - fallback stub in kernel/sys_ni.c - - -x86 System Call Implementation ------------------------------- - -To wire up your new system call for x86 platforms, you need to update the -master syscall tables. Assuming your new system call isn't special in some -way (see below), this involves a "common" entry (for x86_64 and x32) in -arch/x86/entry/syscalls/syscall_64.tbl: - - 333 common xyzzy sys_xyzzy - -and an "i386" entry in arch/x86/entry/syscalls/syscall_32.tbl: - - 380 i386 xyzzy sys_xyzzy - -Again, these numbers are liable to be changed if there are conflicts in the -relevant merge window. - - -Compatibility System Calls (Generic) ------------------------------------- - -For most system calls the same 64-bit implementation can be invoked even when -the userspace program is itself 32-bit; even if the system call's parameters -include an explicit pointer, this is handled transparently. - -However, there are a couple of situations where a compatibility layer is -needed to cope with size differences between 32-bit and 64-bit. - -The first is if the 64-bit kernel also supports 32-bit userspace programs, and -so needs to parse areas of (__user) memory that could hold either 32-bit or -64-bit values. In particular, this is needed whenever a system call argument -is: - - - a pointer to a pointer - - a pointer to a struct containing a pointer (e.g. struct iovec __user *) - - a pointer to a varying sized integral type (time_t, off_t, long, ...) - - a pointer to a struct containing a varying sized integral type. - -The second situation that requires a compatibility layer is if one of the -system call's arguments has a type that is explicitly 64-bit even on a 32-bit -architecture, for example loff_t or __u64. In this case, a value that arrives -at a 64-bit kernel from a 32-bit application will be split into two 32-bit -values, which then need to be re-assembled in the compatibility layer. - -(Note that a system call argument that's a pointer to an explicit 64-bit type -does *not* need a compatibility layer; for example, splice(2)'s arguments of -type loff_t __user * do not trigger the need for a compat_ system call.) - -The compatibility version of the system call is called compat_sys_xyzzy(), and -is added with the COMPAT_SYSCALL_DEFINEn() macro, analogously to -SYSCALL_DEFINEn. This version of the implementation runs as part of a 64-bit -kernel, but expects to receive 32-bit parameter values and does whatever is -needed to deal with them. (Typically, the compat_sys_ version converts the -values to 64-bit versions and either calls on to the sys_ version, or both of -them call a common inner implementation function.) - -The compat entry point also needs a corresponding function prototype, in -include/linux/compat.h, marked as asmlinkage to match the way that system -calls are invoked: - - asmlinkage long compat_sys_xyzzy(...); - -If the system call involves a structure that is laid out differently on 32-bit -and 64-bit systems, say struct xyzzy_args, then the include/linux/compat.h -header file should also include a compat version of the structure (struct -compat_xyzzy_args) where each variable-size field has the appropriate compat_ -type that corresponds to the type in struct xyzzy_args. The -compat_sys_xyzzy() routine can then use this compat_ structure to parse the -arguments from a 32-bit invocation. - -For example, if there are fields: - - struct xyzzy_args { - const char __user *ptr; - __kernel_long_t varying_val; - u64 fixed_val; - /* ... */ - }; - -in struct xyzzy_args, then struct compat_xyzzy_args would have: - - struct compat_xyzzy_args { - compat_uptr_t ptr; - compat_long_t varying_val; - u64 fixed_val; - /* ... */ - }; - -The generic system call list also needs adjusting to allow for the compat -version; the entry in include/uapi/asm-generic/unistd.h should use -__SC_COMP rather than __SYSCALL: - - #define __NR_xyzzy 292 - __SC_COMP(__NR_xyzzy, sys_xyzzy, compat_sys_xyzzy) - -To summarize, you need: - - - a COMPAT_SYSCALL_DEFINEn(xyzzy, ...) for the compat entry point - - corresponding prototype in include/linux/compat.h - - (if needed) 32-bit mapping struct in include/linux/compat.h - - instance of __SC_COMP not __SYSCALL in include/uapi/asm-generic/unistd.h - - -Compatibility System Calls (x86) --------------------------------- - -To wire up the x86 architecture of a system call with a compatibility version, -the entries in the syscall tables need to be adjusted. - -First, the entry in arch/x86/entry/syscalls/syscall_32.tbl gets an extra -column to indicate that a 32-bit userspace program running on a 64-bit kernel -should hit the compat entry point: - - 380 i386 xyzzy sys_xyzzy compat_sys_xyzzy - -Second, you need to figure out what should happen for the x32 ABI version of -the new system call. There's a choice here: the layout of the arguments -should either match the 64-bit version or the 32-bit version. - -If there's a pointer-to-a-pointer involved, the decision is easy: x32 is -ILP32, so the layout should match the 32-bit version, and the entry in -arch/x86/entry/syscalls/syscall_64.tbl is split so that x32 programs hit the -compatibility wrapper: - - 333 64 xyzzy sys_xyzzy - ... - 555 x32 xyzzy compat_sys_xyzzy - -If no pointers are involved, then it is preferable to re-use the 64-bit system -call for the x32 ABI (and consequently the entry in -arch/x86/entry/syscalls/syscall_64.tbl is unchanged). - -In either case, you should check that the types involved in your argument -layout do indeed map exactly from x32 (-mx32) to either the 32-bit (-m32) or -64-bit (-m64) equivalents. - - -System Calls Returning Elsewhere --------------------------------- - -For most system calls, once the system call is complete the user program -continues exactly where it left off -- at the next instruction, with the -stack the same and most of the registers the same as before the system call, -and with the same virtual memory space. - -However, a few system calls do things differently. They might return to a -different location (rt_sigreturn) or change the memory space (fork/vfork/clone) -or even architecture (execve/execveat) of the program. - -To allow for this, the kernel implementation of the system call may need to -save and restore additional registers to the kernel stack, allowing complete -control of where and how execution continues after the system call. - -This is arch-specific, but typically involves defining assembly entry points -that save/restore additional registers and invoke the real system call entry -point. - -For x86_64, this is implemented as a stub_xyzzy entry point in -arch/x86/entry/entry_64.S, and the entry in the syscall table -(arch/x86/entry/syscalls/syscall_64.tbl) is adjusted to match: - - 333 common xyzzy stub_xyzzy - -The equivalent for 32-bit programs running on a 64-bit kernel is normally -called stub32_xyzzy and implemented in arch/x86/entry/entry_64_compat.S, -with the corresponding syscall table adjustment in -arch/x86/entry/syscalls/syscall_32.tbl: - - 380 i386 xyzzy sys_xyzzy stub32_xyzzy - -If the system call needs a compatibility layer (as in the previous section) -then the stub32_ version needs to call on to the compat_sys_ version of the -system call rather than the native 64-bit version. Also, if the x32 ABI -implementation is not common with the x86_64 version, then its syscall -table will also need to invoke a stub that calls on to the compat_sys_ -version. - -For completeness, it's also nice to set up a mapping so that user-mode Linux -still works -- its syscall table will reference stub_xyzzy, but the UML build -doesn't include arch/x86/entry/entry_64.S implementation (because UML -simulates registers etc). Fixing this is as simple as adding a #define to -arch/x86/um/sys_call_table_64.c: - - #define stub_xyzzy sys_xyzzy - - -Other Details -------------- - -Most of the kernel treats system calls in a generic way, but there is the -occasional exception that may need updating for your particular system call. - -The audit subsystem is one such special case; it includes (arch-specific) -functions that classify some special types of system call -- specifically -file open (open/openat), program execution (execve/exeveat) or socket -multiplexor (socketcall) operations. If your new system call is analogous to -one of these, then the audit system should be updated. - -More generally, if there is an existing system call that is analogous to your -new system call, it's worth doing a kernel-wide grep for the existing system -call to check there are no other special cases. - - -Testing -------- - -A new system call should obviously be tested; it is also useful to provide -reviewers with a demonstration of how user space programs will use the system -call. A good way to combine these aims is to include a simple self-test -program in a new directory under tools/testing/selftests/. - -For a new system call, there will obviously be no libc wrapper function and so -the test will need to invoke it using syscall(); also, if the system call -involves a new userspace-visible structure, the corresponding header will need -to be installed to compile the test. - -Make sure the selftest runs successfully on all supported architectures. For -example, check that it works when compiled as an x86_64 (-m64), x86_32 (-m32) -and x32 (-mx32) ABI program. - -For more extensive and thorough testing of new functionality, you should also -consider adding tests to the Linux Test Project, or to the xfstests project -for filesystem-related changes. - - https://linux-test-project.github.io/ - - git://git.kernel.org/pub/scm/fs/xfs/xfstests-dev.git - - -Man Page --------- - -All new system calls should come with a complete man page, ideally using groff -markup, but plain text will do. If groff is used, it's helpful to include a -pre-rendered ASCII version of the man page in the cover email for the -patchset, for the convenience of reviewers. - -The man page should be cc'ed to linux-man@vger.kernel.org -For more details, see https://www.kernel.org/doc/man-pages/patches.html - -References and Sources ----------------------- - - - LWN article from Michael Kerrisk on use of flags argument in system calls: - https://lwn.net/Articles/585415/ - - LWN article from Michael Kerrisk on how to handle unknown flags in a system - call: https://lwn.net/Articles/588444/ - - LWN article from Jake Edge describing constraints on 64-bit system call - arguments: https://lwn.net/Articles/311630/ - - Pair of LWN articles from David Drysdale that describe the system call - implementation paths in detail for v3.14: - - https://lwn.net/Articles/604287/ - - https://lwn.net/Articles/604515/ - - Architecture-specific requirements for system calls are discussed in the - syscall(2) man-page: - http://man7.org/linux/man-pages/man2/syscall.2.html#NOTES - - Collated emails from Linus Torvalds discussing the problems with ioctl(): - http://yarchive.net/comp/linux/ioctl.html - - "How to not invent kernel interfaces", Arnd Bergmann, - http://www.ukuug.org/events/linux2007/2007/papers/Bergmann.pdf - - LWN article from Michael Kerrisk on avoiding new uses of CAP_SYS_ADMIN: - https://lwn.net/Articles/486306/ - - Recommendation from Andrew Morton that all related information for a new - system call should come in the same email thread: - https://lkml.org/lkml/2014/7/24/641 - - Recommendation from Michael Kerrisk that a new system call should come with - a man page: https://lkml.org/lkml/2014/6/13/309 - - Suggestion from Thomas Gleixner that x86 wire-up should be in a separate - commit: https://lkml.org/lkml/2014/11/19/254 - - Suggestion from Greg Kroah-Hartman that it's good for new system calls to - come with a man-page & selftest: https://lkml.org/lkml/2014/3/19/710 - - Discussion from Michael Kerrisk of new system call vs. prctl(2) extension: - https://lkml.org/lkml/2014/6/3/411 - - Suggestion from Ingo Molnar that system calls that involve multiple - arguments should encapsulate those arguments in a struct, which includes a - size field for future extensibility: https://lkml.org/lkml/2015/7/30/117 - - Numbering oddities arising from (re-)use of O_* numbering space flags: - - commit 75069f2b5bfb ("vfs: renumber FMODE_NONOTIFY and add to uniqueness - check") - - commit 12ed2e36c98a ("fanotify: FMODE_NONOTIFY and __O_SYNC in sparc - conflict") - - commit bb458c644a59 ("Safer ABI for O_TMPFILE") - - Discussion from Matthew Wilcox about restrictions on 64-bit arguments: - https://lkml.org/lkml/2008/12/12/187 - - Recommendation from Greg Kroah-Hartman that unknown flags should be - policed: https://lkml.org/lkml/2014/7/17/577 - - Recommendation from Linus Torvalds that x32 system calls should prefer - compatibility with 64-bit versions rather than 32-bit versions: - https://lkml.org/lkml/2011/8/31/244 diff --git a/Documentation/adding-syscals.txt b/Documentation/adding-syscals.txt new file mode 100644 index 000000000000..f5b5b1aa51b3 --- /dev/null +++ b/Documentation/adding-syscals.txt @@ -0,0 +1,542 @@ +Adding a New System Call +======================== + +This document describes what's involved in adding a new system call to the +Linux kernel, over and above the normal submission advice in +:ref:`Documentation/SubmittingPatches `. + + +System Call Alternatives +------------------------ + +The first thing to consider when adding a new system call is whether one of +the alternatives might be suitable instead. Although system calls are the +most traditional and most obvious interaction points between userspace and the +kernel, there are other possibilities -- choose what fits best for your +interface. + + - If the operations involved can be made to look like a filesystem-like + object, it may make more sense to create a new filesystem or device. This + also makes it easier to encapsulate the new functionality in a kernel module + rather than requiring it to be built into the main kernel. + + - If the new functionality involves operations where the kernel notifies + userspace that something has happened, then returning a new file + descriptor for the relevant object allows userspace to use + ``poll``/``select``/``epoll`` to receive that notification. + - However, operations that don't map to + :manpage:`read(2)`/:manpage:`write(2)`-like operations + have to be implemented as :manpage:`ioctl(2)` requests, which can lead + to a somewhat opaque API. + + - If you're just exposing runtime system information, a new node in sysfs + (see ``Documentation/filesystems/sysfs.txt``) or the ``/proc`` filesystem may + be more appropriate. However, access to these mechanisms requires that the + relevant filesystem is mounted, which might not always be the case (e.g. + in a namespaced/sandboxed/chrooted environment). Avoid adding any API to + debugfs, as this is not considered a 'production' interface to userspace. + - If the operation is specific to a particular file or file descriptor, then + an additional :manpage:`fcntl(2)` command option may be more appropriate. However, + :manpage:`fcntl(2)` is a multiplexing system call that hides a lot of complexity, so + this option is best for when the new function is closely analogous to + existing :manpage:`fcntl(2)` functionality, or the new functionality is very simple + (for example, getting/setting a simple flag related to a file descriptor). + - If the operation is specific to a particular task or process, then an + additional :manpage:`prctl(2)` command option may be more appropriate. As + with :manpage:`fcntl(2)`, this system call is a complicated multiplexor so + is best reserved for near-analogs of existing ``prctl()`` commands or + getting/setting a simple flag related to a process. + + +Designing the API: Planning for Extension +----------------------------------------- + +A new system call forms part of the API of the kernel, and has to be supported +indefinitely. As such, it's a very good idea to explicitly discuss the +interface on the kernel mailing list, and it's important to plan for future +extensions of the interface. + +(The syscall table is littered with historical examples where this wasn't done, +together with the corresponding follow-up system calls -- +``eventfd``/``eventfd2``, ``dup2``/``dup3``, ``inotify_init``/``inotify_init1``, +``pipe``/``pipe2``, ``renameat``/``renameat2`` -- so +learn from the history of the kernel and plan for extensions from the start.) + +For simpler system calls that only take a couple of arguments, the preferred +way to allow for future extensibility is to include a flags argument to the +system call. To make sure that userspace programs can safely use flags +between kernel versions, check whether the flags value holds any unknown +flags, and reject the system call (with ``EINVAL``) if it does:: + + if (flags & ~(THING_FLAG1 | THING_FLAG2 | THING_FLAG3)) + return -EINVAL; + +(If no flags values are used yet, check that the flags argument is zero.) + +For more sophisticated system calls that involve a larger number of arguments, +it's preferred to encapsulate the majority of the arguments into a structure +that is passed in by pointer. Such a structure can cope with future extension +by including a size argument in the structure:: + + struct xyzzy_params { + u32 size; /* userspace sets p->size = sizeof(struct xyzzy_params) */ + u32 param_1; + u64 param_2; + u64 param_3; + }; + +As long as any subsequently added field, say ``param_4``, is designed so that a +zero value gives the previous behaviour, then this allows both directions of +version mismatch: + + - To cope with a later userspace program calling an older kernel, the kernel + code should check that any memory beyond the size of the structure that it + expects is zero (effectively checking that ``param_4 == 0``). + - To cope with an older userspace program calling a newer kernel, the kernel + code can zero-extend a smaller instance of the structure (effectively + setting ``param_4 = 0``). + +See :manpage:`perf_event_open(2)` and the ``perf_copy_attr()`` function (in +``kernel/events/core.c``) for an example of this approach. + + +Designing the API: Other Considerations +--------------------------------------- + +If your new system call allows userspace to refer to a kernel object, it +should use a file descriptor as the handle for that object -- don't invent a +new type of userspace object handle when the kernel already has mechanisms and +well-defined semantics for using file descriptors. + +If your new :manpage:`xyzzy(2)` system call does return a new file descriptor, +then the flags argument should include a value that is equivalent to setting +``O_CLOEXEC`` on the new FD. This makes it possible for userspace to close +the timing window between ``xyzzy()`` and calling +``fcntl(fd, F_SETFD, FD_CLOEXEC)``, where an unexpected ``fork()`` and +``execve()`` in another thread could leak a descriptor to +the exec'ed program. (However, resist the temptation to re-use the actual value +of the ``O_CLOEXEC`` constant, as it is architecture-specific and is part of a +numbering space of ``O_*`` flags that is fairly full.) + +If your system call returns a new file descriptor, you should also consider +what it means to use the :manpage:`poll(2)` family of system calls on that file +descriptor. Making a file descriptor ready for reading or writing is the +normal way for the kernel to indicate to userspace that an event has +occurred on the corresponding kernel object. + +If your new :manpage:`xyzzy(2)` system call involves a filename argument:: + + int sys_xyzzy(const char __user *path, ..., unsigned int flags); + +you should also consider whether an :manpage:`xyzzyat(2)` version is more appropriate:: + + int sys_xyzzyat(int dfd, const char __user *path, ..., unsigned int flags); + +This allows more flexibility for how userspace specifies the file in question; +in particular it allows userspace to request the functionality for an +already-opened file descriptor using the ``AT_EMPTY_PATH`` flag, effectively +giving an :manpage:`fxyzzy(3)` operation for free:: + + - xyzzyat(AT_FDCWD, path, ..., 0) is equivalent to xyzzy(path,...) + - xyzzyat(fd, "", ..., AT_EMPTY_PATH) is equivalent to fxyzzy(fd, ...) + +(For more details on the rationale of the \*at() calls, see the +:manpage:`openat(2)` man page; for an example of AT_EMPTY_PATH, see the +:manpage:`fstatat(2)` man page.) + +If your new :manpage:`xyzzy(2)` system call involves a parameter describing an +offset within a file, make its type ``loff_t`` so that 64-bit offsets can be +supported even on 32-bit architectures. + +If your new :manpage:`xyzzy(2)` system call involves privileged functionality, +it needs to be governed by the appropriate Linux capability bit (checked with +a call to ``capable()``), as described in the :manpage:`capabilities(7)` man +page. Choose an existing capability bit that governs related functionality, +but try to avoid combining lots of only vaguely related functions together +under the same bit, as this goes against capabilities' purpose of splitting +the power of root. In particular, avoid adding new uses of the already +overly-general ``CAP_SYS_ADMIN`` capability. + +If your new :manpage:`xyzzy(2)` system call manipulates a process other than +the calling process, it should be restricted (using a call to +``ptrace_may_access()``) so that only a calling process with the same +permissions as the target process, or with the necessary capabilities, can +manipulate the target process. + +Finally, be aware that some non-x86 architectures have an easier time if +system call parameters that are explicitly 64-bit fall on odd-numbered +arguments (i.e. parameter 1, 3, 5), to allow use of contiguous pairs of 32-bit +registers. (This concern does not apply if the arguments are part of a +structure that's passed in by pointer.) + + +Proposing the API +----------------- + +To make new system calls easy to review, it's best to divide up the patchset +into separate chunks. These should include at least the following items as +distinct commits (each of which is described further below): + + - The core implementation of the system call, together with prototypes, + generic numbering, Kconfig changes and fallback stub implementation. + - Wiring up of the new system call for one particular architecture, usually + x86 (including all of x86_64, x86_32 and x32). + - A demonstration of the use of the new system call in userspace via a + selftest in ``tools/testing/selftests/``. + - A draft man-page for the new system call, either as plain text in the + cover letter, or as a patch to the (separate) man-pages repository. + +New system call proposals, like any change to the kernel's API, should always +be cc'ed to linux-api@vger.kernel.org. + + +Generic System Call Implementation +---------------------------------- + +The main entry point for your new :manpage:`xyzzy(2)` system call will be called +``sys_xyzzy()``, but you add this entry point with the appropriate +``SYSCALL_DEFINEn()`` macro rather than explicitly. The 'n' indicates the +number of arguments to the system call, and the macro takes the system call name +followed by the (type, name) pairs for the parameters as arguments. Using +this macro allows metadata about the new system call to be made available for +other tools. + +The new entry point also needs a corresponding function prototype, in +``include/linux/syscalls.h``, marked as asmlinkage to match the way that system +calls are invoked:: + + asmlinkage long sys_xyzzy(...); + +Some architectures (e.g. x86) have their own architecture-specific syscall +tables, but several other architectures share a generic syscall table. Add your +new system call to the generic list by adding an entry to the list in +``include/uapi/asm-generic/unistd.h``:: + + #define __NR_xyzzy 292 + __SYSCALL(__NR_xyzzy, sys_xyzzy) + +Also update the __NR_syscalls count to reflect the additional system call, and +note that if multiple new system calls are added in the same merge window, +your new syscall number may get adjusted to resolve conflicts. + +The file ``kernel/sys_ni.c`` provides a fallback stub implementation of each +system call, returning ``-ENOSYS``. Add your new system call here too:: + + cond_syscall(sys_xyzzy); + +Your new kernel functionality, and the system call that controls it, should +normally be optional, so add a ``CONFIG`` option (typically to +``init/Kconfig``) for it. As usual for new ``CONFIG`` options: + + - Include a description of the new functionality and system call controlled + by the option. + - Make the option depend on EXPERT if it should be hidden from normal users. + - Make any new source files implementing the function dependent on the CONFIG + option in the Makefile (e.g. ``obj-$(CONFIG_XYZZY_SYSCALL) += xyzzy.c``). + - Double check that the kernel still builds with the new CONFIG option turned + off. + +To summarize, you need a commit that includes: + + - ``CONFIG`` option for the new function, normally in ``init/Kconfig`` + - ``SYSCALL_DEFINEn(xyzzy, ...)`` for the entry point + - corresponding prototype in ``include/linux/syscalls.h`` + - generic table entry in ``include/uapi/asm-generic/unistd.h`` + - fallback stub in ``kernel/sys_ni.c`` + + +x86 System Call Implementation +------------------------------ + +To wire up your new system call for x86 platforms, you need to update the +master syscall tables. Assuming your new system call isn't special in some +way (see below), this involves a "common" entry (for x86_64 and x32) in +arch/x86/entry/syscalls/syscall_64.tbl:: + + 333 common xyzzy sys_xyzzy + +and an "i386" entry in ``arch/x86/entry/syscalls/syscall_32.tbl``:: + + 380 i386 xyzzy sys_xyzzy + +Again, these numbers are liable to be changed if there are conflicts in the +relevant merge window. + + +Compatibility System Calls (Generic) +------------------------------------ + +For most system calls the same 64-bit implementation can be invoked even when +the userspace program is itself 32-bit; even if the system call's parameters +include an explicit pointer, this is handled transparently. + +However, there are a couple of situations where a compatibility layer is +needed to cope with size differences between 32-bit and 64-bit. + +The first is if the 64-bit kernel also supports 32-bit userspace programs, and +so needs to parse areas of (``__user``) memory that could hold either 32-bit or +64-bit values. In particular, this is needed whenever a system call argument +is: + + - a pointer to a pointer + - a pointer to a struct containing a pointer (e.g. ``struct iovec __user *``) + - a pointer to a varying sized integral type (``time_t``, ``off_t``, + ``long``, ...) + - a pointer to a struct containing a varying sized integral type. + +The second situation that requires a compatibility layer is if one of the +system call's arguments has a type that is explicitly 64-bit even on a 32-bit +architecture, for example ``loff_t`` or ``__u64``. In this case, a value that +arrives at a 64-bit kernel from a 32-bit application will be split into two +32-bit values, which then need to be re-assembled in the compatibility layer. + +(Note that a system call argument that's a pointer to an explicit 64-bit type +does **not** need a compatibility layer; for example, :manpage:`splice(2)`'s arguments of +type ``loff_t __user *`` do not trigger the need for a ``compat_`` system call.) + +The compatibility version of the system call is called ``compat_sys_xyzzy()``, +and is added with the ``COMPAT_SYSCALL_DEFINEn()`` macro, analogously to +SYSCALL_DEFINEn. This version of the implementation runs as part of a 64-bit +kernel, but expects to receive 32-bit parameter values and does whatever is +needed to deal with them. (Typically, the ``compat_sys_`` version converts the +values to 64-bit versions and either calls on to the ``sys_`` version, or both of +them call a common inner implementation function.) + +The compat entry point also needs a corresponding function prototype, in +``include/linux/compat.h``, marked as asmlinkage to match the way that system +calls are invoked:: + + asmlinkage long compat_sys_xyzzy(...); + +If the system call involves a structure that is laid out differently on 32-bit +and 64-bit systems, say ``struct xyzzy_args``, then the include/linux/compat.h +header file should also include a compat version of the structure (``struct +compat_xyzzy_args``) where each variable-size field has the appropriate +``compat_`` type that corresponds to the type in ``struct xyzzy_args``. The +``compat_sys_xyzzy()`` routine can then use this ``compat_`` structure to +parse the arguments from a 32-bit invocation. + +For example, if there are fields:: + + struct xyzzy_args { + const char __user *ptr; + __kernel_long_t varying_val; + u64 fixed_val; + /* ... */ + }; + +in struct xyzzy_args, then struct compat_xyzzy_args would have:: + + struct compat_xyzzy_args { + compat_uptr_t ptr; + compat_long_t varying_val; + u64 fixed_val; + /* ... */ + }; + +The generic system call list also needs adjusting to allow for the compat +version; the entry in ``include/uapi/asm-generic/unistd.h`` should use +``__SC_COMP`` rather than ``__SYSCALL``:: + + #define __NR_xyzzy 292 + __SC_COMP(__NR_xyzzy, sys_xyzzy, compat_sys_xyzzy) + +To summarize, you need: + + - a ``COMPAT_SYSCALL_DEFINEn(xyzzy, ...)`` for the compat entry point + - corresponding prototype in ``include/linux/compat.h`` + - (if needed) 32-bit mapping struct in ``include/linux/compat.h`` + - instance of ``__SC_COMP`` not ``__SYSCALL`` in + ``include/uapi/asm-generic/unistd.h`` + + +Compatibility System Calls (x86) +-------------------------------- + +To wire up the x86 architecture of a system call with a compatibility version, +the entries in the syscall tables need to be adjusted. + +First, the entry in ``arch/x86/entry/syscalls/syscall_32.tbl`` gets an extra +column to indicate that a 32-bit userspace program running on a 64-bit kernel +should hit the compat entry point:: + + 380 i386 xyzzy sys_xyzzy compat_sys_xyzzy + +Second, you need to figure out what should happen for the x32 ABI version of +the new system call. There's a choice here: the layout of the arguments +should either match the 64-bit version or the 32-bit version. + +If there's a pointer-to-a-pointer involved, the decision is easy: x32 is +ILP32, so the layout should match the 32-bit version, and the entry in +``arch/x86/entry/syscalls/syscall_64.tbl`` is split so that x32 programs hit +the compatibility wrapper:: + + 333 64 xyzzy sys_xyzzy + ... + 555 x32 xyzzy compat_sys_xyzzy + +If no pointers are involved, then it is preferable to re-use the 64-bit system +call for the x32 ABI (and consequently the entry in +arch/x86/entry/syscalls/syscall_64.tbl is unchanged). + +In either case, you should check that the types involved in your argument +layout do indeed map exactly from x32 (-mx32) to either the 32-bit (-m32) or +64-bit (-m64) equivalents. + + +System Calls Returning Elsewhere +-------------------------------- + +For most system calls, once the system call is complete the user program +continues exactly where it left off -- at the next instruction, with the +stack the same and most of the registers the same as before the system call, +and with the same virtual memory space. + +However, a few system calls do things differently. They might return to a +different location (``rt_sigreturn``) or change the memory space +(``fork``/``vfork``/``clone``) or even architecture (``execve``/``execveat``) +of the program. + +To allow for this, the kernel implementation of the system call may need to +save and restore additional registers to the kernel stack, allowing complete +control of where and how execution continues after the system call. + +This is arch-specific, but typically involves defining assembly entry points +that save/restore additional registers and invoke the real system call entry +point. + +For x86_64, this is implemented as a ``stub_xyzzy`` entry point in +``arch/x86/entry/entry_64.S``, and the entry in the syscall table +(``arch/x86/entry/syscalls/syscall_64.tbl``) is adjusted to match:: + + 333 common xyzzy stub_xyzzy + +The equivalent for 32-bit programs running on a 64-bit kernel is normally +called ``stub32_xyzzy`` and implemented in ``arch/x86/entry/entry_64_compat.S``, +with the corresponding syscall table adjustment in +``arch/x86/entry/syscalls/syscall_32.tbl``:: + + 380 i386 xyzzy sys_xyzzy stub32_xyzzy + +If the system call needs a compatibility layer (as in the previous section) +then the ``stub32_`` version needs to call on to the ``compat_sys_`` version +of the system call rather than the native 64-bit version. Also, if the x32 ABI +implementation is not common with the x86_64 version, then its syscall +table will also need to invoke a stub that calls on to the ``compat_sys_`` +version. + +For completeness, it's also nice to set up a mapping so that user-mode Linux +still works -- its syscall table will reference stub_xyzzy, but the UML build +doesn't include ``arch/x86/entry/entry_64.S`` implementation (because UML +simulates registers etc). Fixing this is as simple as adding a #define to +``arch/x86/um/sys_call_table_64.c``:: + + #define stub_xyzzy sys_xyzzy + + +Other Details +------------- + +Most of the kernel treats system calls in a generic way, but there is the +occasional exception that may need updating for your particular system call. + +The audit subsystem is one such special case; it includes (arch-specific) +functions that classify some special types of system call -- specifically +file open (``open``/``openat``), program execution (``execve``/``exeveat``) or +socket multiplexor (``socketcall``) operations. If your new system call is +analogous to one of these, then the audit system should be updated. + +More generally, if there is an existing system call that is analogous to your +new system call, it's worth doing a kernel-wide grep for the existing system +call to check there are no other special cases. + + +Testing +------- + +A new system call should obviously be tested; it is also useful to provide +reviewers with a demonstration of how user space programs will use the system +call. A good way to combine these aims is to include a simple self-test +program in a new directory under ``tools/testing/selftests/``. + +For a new system call, there will obviously be no libc wrapper function and so +the test will need to invoke it using ``syscall()``; also, if the system call +involves a new userspace-visible structure, the corresponding header will need +to be installed to compile the test. + +Make sure the selftest runs successfully on all supported architectures. For +example, check that it works when compiled as an x86_64 (-m64), x86_32 (-m32) +and x32 (-mx32) ABI program. + +For more extensive and thorough testing of new functionality, you should also +consider adding tests to the Linux Test Project, or to the xfstests project +for filesystem-related changes. + + - https://linux-test-project.github.io/ + - git://git.kernel.org/pub/scm/fs/xfs/xfstests-dev.git + + +Man Page +-------- + +All new system calls should come with a complete man page, ideally using groff +markup, but plain text will do. If groff is used, it's helpful to include a +pre-rendered ASCII version of the man page in the cover email for the +patchset, for the convenience of reviewers. + +The man page should be cc'ed to linux-man@vger.kernel.org +For more details, see https://www.kernel.org/doc/man-pages/patches.html + +References and Sources +---------------------- + + - LWN article from Michael Kerrisk on use of flags argument in system calls: + https://lwn.net/Articles/585415/ + - LWN article from Michael Kerrisk on how to handle unknown flags in a system + call: https://lwn.net/Articles/588444/ + - LWN article from Jake Edge describing constraints on 64-bit system call + arguments: https://lwn.net/Articles/311630/ + - Pair of LWN articles from David Drysdale that describe the system call + implementation paths in detail for v3.14: + + - https://lwn.net/Articles/604287/ + - https://lwn.net/Articles/604515/ + + - Architecture-specific requirements for system calls are discussed in the + :manpage:`syscall(2)` man-page: + http://man7.org/linux/man-pages/man2/syscall.2.html#NOTES + - Collated emails from Linus Torvalds discussing the problems with ``ioctl()``: + http://yarchive.net/comp/linux/ioctl.html + - "How to not invent kernel interfaces", Arnd Bergmann, + http://www.ukuug.org/events/linux2007/2007/papers/Bergmann.pdf + - LWN article from Michael Kerrisk on avoiding new uses of CAP_SYS_ADMIN: + https://lwn.net/Articles/486306/ + - Recommendation from Andrew Morton that all related information for a new + system call should come in the same email thread: + https://lkml.org/lkml/2014/7/24/641 + - Recommendation from Michael Kerrisk that a new system call should come with + a man page: https://lkml.org/lkml/2014/6/13/309 + - Suggestion from Thomas Gleixner that x86 wire-up should be in a separate + commit: https://lkml.org/lkml/2014/11/19/254 + - Suggestion from Greg Kroah-Hartman that it's good for new system calls to + come with a man-page & selftest: https://lkml.org/lkml/2014/3/19/710 + - Discussion from Michael Kerrisk of new system call vs. :manpage:`prctl(2)` extension: + https://lkml.org/lkml/2014/6/3/411 + - Suggestion from Ingo Molnar that system calls that involve multiple + arguments should encapsulate those arguments in a struct, which includes a + size field for future extensibility: https://lkml.org/lkml/2015/7/30/117 + - Numbering oddities arising from (re-)use of O_* numbering space flags: + + - commit 75069f2b5bfb ("vfs: renumber FMODE_NONOTIFY and add to uniqueness + check") + - commit 12ed2e36c98a ("fanotify: FMODE_NONOTIFY and __O_SYNC in sparc + conflict") + - commit bb458c644a59 ("Safer ABI for O_TMPFILE") + + - Discussion from Matthew Wilcox about restrictions on 64-bit arguments: + https://lkml.org/lkml/2008/12/12/187 + - Recommendation from Greg Kroah-Hartman that unknown flags should be + policed: https://lkml.org/lkml/2014/7/17/577 + - Recommendation from Linus Torvalds that x32 system calls should prefer + compatibility with 64-bit versions rather than 32-bit versions: + https://lkml.org/lkml/2011/8/31/244 -- cgit v1.2.3 From 684adc0aa3d482228d0727ee9a9a7b8deec62ca5 Mon Sep 17 00:00:00 2001 From: Mauro Carvalho Chehab Date: Wed, 21 Sep 2016 09:48:55 -0300 Subject: Documentation/kernel-parameters.txt: convert to ReST markup Adjust the file for it to be parsed by Sphinx: - adjust the document title to be parsed; - use :: for quote blocks; - fix the horizontal bar markup; - lower case the TODO title. Signed-off-by: Mauro Carvalho Chehab --- Documentation/kernel-parameters.txt | 33 +++++++++++++++++++-------------- 1 file changed, 19 insertions(+), 14 deletions(-) diff --git a/Documentation/kernel-parameters.txt b/Documentation/kernel-parameters.txt index 37babf91f2cb..b0804273b6e3 100644 --- a/Documentation/kernel-parameters.txt +++ b/Documentation/kernel-parameters.txt @@ -1,5 +1,5 @@ - Kernel Parameters - ~~~~~~~~~~~~~~~~~ +Kernel Parameters +~~~~~~~~~~~~~~~~~ The following is a consolidated list of the kernel parameters as implemented by the __setup(), core_param() and module_param() macros @@ -14,7 +14,7 @@ environment, others are passed as command line arguments to init. Everything after "--" is passed as an argument to init. Module parameters can be specified in two ways: via the kernel command -line with a module name prefix, or via modprobe, e.g.: +line with a module name prefix, or via modprobe, e.g.:: (kernel command line) usbcore.blinkenlights=1 (modprobe command line) modprobe usbcore blinkenlights=1 @@ -25,12 +25,16 @@ kernel command line (/proc/cmdline) and collects module parameters when it loads a module, so the kernel command line can be used for loadable modules too. -Hyphens (dashes) and underscores are equivalent in parameter names, so +Hyphens (dashes) and underscores are equivalent in parameter names, so:: + log_buf_len=1M print-fatal-signals=1 -can also be entered as + +can also be entered as:: + log-buf-len=1M print_fatal_signals=1 -Double-quotes can be used to protect spaces in values, e.g.: +Double-quotes can be used to protect spaces in values, e.g.:: + param="spaces in here" cpu lists: @@ -69,12 +73,12 @@ This document may not be entirely up to date and comprehensive. The command module. Loadable modules, after being loaded into the running kernel, also reveal their parameters in /sys/module/${modulename}/parameters/. Some of these parameters may be changed at runtime by the command -"echo -n ${value} > /sys/module/${modulename}/parameters/${parm}". +``echo -n ${value} > /sys/module/${modulename}/parameters/${parm}``. The parameters listed below are only valid if certain kernel build options were enabled and if respective hardware is present. The text in square brackets at the beginning of each description states the restrictions within which a -parameter is applicable: +parameter is applicable:: ACPI ACPI support is enabled. AGP AGP (Accelerated Graphics Port) is enabled. @@ -165,7 +169,7 @@ parameter is applicable: X86_UV SGI UV support is enabled. XEN Xen support is enabled -In addition, the following text indicates that the option: +In addition, the following text indicates that the option:: BUGS= Relates to possible processor bugs on the said processor. KNL Is a kernel start-up parameter. @@ -194,7 +198,7 @@ and is between 256 and 4096 characters. It is defined in the file Finally, the [KMG] suffix is commonly described after a number of kernel parameter values. These 'K', 'M', and 'G' letters represent the _binary_ multipliers 'Kilo', 'Mega', and 'Giga', equalling 2^10, 2^20, and 2^30 -bytes respectively. Such letter suffixes can also be entirely omitted. +bytes respectively. Such letter suffixes can also be entirely omitted:: acpi= [HW,ACPI,X86,ARM64] @@ -2545,7 +2549,7 @@ bytes respectively. Such letter suffixes can also be entirely omitted. will be sent. The default is to send the implementation identification information. - + nfs.recover_lost_locks = [NFSv4] Attempt to recover locks that were lost due to a lease timeout on the server. Please note that @@ -4197,7 +4201,7 @@ bytes respectively. Such letter suffixes can also be entirely omitted. See also Documentation/input/joystick-parport.txt udbg-immortal [PPC] When debugging early kernel crashes that - happen after console_init() and before a proper + happen after console_init() and before a proper console driver takes over, this boot options might help "seeing" what's going on. @@ -4565,8 +4569,9 @@ bytes respectively. Such letter suffixes can also be entirely omitted. Format: ,,,,,[,[,[,]]] -______________________________________________________________________ +------------------------ -TODO: +Todo +---- Add more DRM drivers. -- cgit v1.2.3 From d078a815196bc4b3d8fe728a0dbd83c07b928a47 Mon Sep 17 00:00:00 2001 From: Mauro Carvalho Chehab Date: Wed, 21 Sep 2016 13:24:12 -0300 Subject: Documentation/bad_memory.txt: convert it to ReST markup - promote the section level of the document name; - add/remove spaces/new lines where needed to format the output; - use quote blocks. - add it to the user book. Signed-off-by: Mauro Carvalho Chehab --- Documentation/bad_memory.txt | 26 ++++++++++++++++---------- 1 file changed, 16 insertions(+), 10 deletions(-) diff --git a/Documentation/bad_memory.txt b/Documentation/bad_memory.txt index df8416213202..5cac93e27a97 100644 --- a/Documentation/bad_memory.txt +++ b/Documentation/bad_memory.txt @@ -1,9 +1,10 @@ +How to deal with bad memory e.g. reported by memtest86+ ? +========================================================= + March 2008 Jan-Simon Moeller, dl9pf@gmx.de -How to deal with bad memory e.g. reported by memtest86+ ? -######################################################### There are three possibilities I know of: @@ -19,6 +20,7 @@ This Howto is about number 3) . BadRAM ###### + BadRAM is the actively developed and available as kernel-patch here: http://rick.vanrein.org/linux/badram/ @@ -31,15 +33,19 @@ memmap is already in the kernel and usable as kernel-parameter at boot-time. Its syntax is slightly strange and you may need to calculate the values by yourself! -Syntax to exclude a memory area (see kernel-parameters.txt for details): -memmap=$
+Syntax to exclude a memory area (see kernel-parameters.txt for details):: + + memmap=$
Example: memtest86+ reported here errors at address 0x18691458, 0x18698424 and - some others. All had 0x1869xxxx in common, so I chose a pattern of - 0x18690000,0xffff0000. +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:: -With the numbers of the example above: -memmap=64K$0x18690000 - or -memmap=0x10000$0x18690000 + memmap=0x10000$0x18690000 -- cgit v1.2.3 From 3bdb5971ffc6e87362787c770353eb3e54b7af30 Mon Sep 17 00:00:00 2001 From: Mauro Carvalho Chehab Date: Wed, 21 Sep 2016 13:38:38 -0300 Subject: Documentation/basic_profiling.rst: convert to ReST markup Convert it to ReST markup and add it to the user book: - Add a title to the document; - touch spaces/new lines to fix Sphinx format; - use ``foo`` for commands; - use quote blocks where needed; - add it to the user book; Signed-off-by: Mauro Carvalho Chehab --- Documentation/basic_profiling.txt | 59 ++++++++++++++++++++++++--------------- 1 file changed, 36 insertions(+), 23 deletions(-) diff --git a/Documentation/basic_profiling.txt b/Documentation/basic_profiling.txt index 8764e9f70821..15a49dbd0189 100644 --- a/Documentation/basic_profiling.txt +++ b/Documentation/basic_profiling.txt @@ -1,56 +1,69 @@ +Basic kernel profiling +====================== + + These instructions are deliberately very basic. If you want something clever, -go read the real docs ;-) Please don't add more stuff, but feel free to +go read the real docs ;-) + +Please don't add more stuff, but feel free to correct my mistakes ;-) (mbligh@aracnet.com) + Thanks to John Levon, Dave Hansen, et al. for help writing this. - is the thing you're trying to measure. -Make sure you have the correct System.map / vmlinux referenced! +```` is the thing you're trying to measure. +Make sure you have the correct ``System.map`` / ``vmlinux`` referenced! -It is probably easiest to use "make install" for linux and hack -/sbin/installkernel to copy vmlinux to /boot, in addition to vmlinuz, -config, System.map, which are usually installed by default. +It is probably easiest to use ``make install`` for linux and hack +``/sbin/installkernel`` to copy ``vmlinux`` to ``/boot``, in addition to +``vmlinuz``, ``config``, ``System.map``, which are usually installed by default. Readprofile ----------- -A recent readprofile command is needed for 2.6, such as found in util-linux + +A recent ``readprofile`` command is needed for 2.6, such as found in util-linux 2.12a, which can be downloaded from: -http://www.kernel.org/pub/linux/utils/util-linux/ + http://www.kernel.org/pub/linux/utils/util-linux/ Most distributions will ship it already. -Add "profile=2" to the kernel command line. +Add ``profile=2`` to the kernel command line. -clear readprofile -r - -dump output readprofile -m /boot/System.map > captured_profile +Some ``readprofile`` commands:: + + clear readprofile -r + + dump output readprofile -m /boot/System.map > captured_profile Oprofile -------- Get the source (see Changes for required version) from -http://oprofile.sourceforge.net/ and add "idle=poll" to the kernel command +http://oprofile.sourceforge.net/ and add ``idle=poll`` to the kernel command line. -Configure with CONFIG_PROFILING=y and CONFIG_OPROFILE=y & reboot on new kernel +Configure with ``CONFIG_PROFILING=y`` and ``CONFIG_OPROFILE=y`` & reboot on new kernel:: -./configure --with-kernel-support -make install + ./configure --with-kernel-support + make install For superior results, be sure to enable the local APIC. If opreport sees a 0Hz CPU, APIC was not on. Be aware that idle=poll may mean a performance penalty. -One time setup: - opcontrol --setup --vmlinux=/boot/vmlinux +One time setup:: + + opcontrol --setup --vmlinux=/boot/vmlinux + +Some ``opcontrol`` commands:: -clear opcontrol --reset -start opcontrol --start + clear opcontrol --reset + start opcontrol --start -stop opcontrol --stop -dump output opreport > output_file + stop opcontrol --stop + dump output opreport > output_file -To only report on the kernel, run opreport -l /boot/vmlinux > output_file +To only report on the kernel, run ``opreport -l /boot/vmlinux > output_file`` A reset is needed to clear old statistics, which survive a reboot. -- cgit v1.2.3 From 5902981bce634dc218f0f8884649efebca7b8bcc Mon Sep 17 00:00:00 2001 From: Mauro Carvalho Chehab Date: Wed, 21 Sep 2016 13:56:19 -0300 Subject: Documentation/binfmt_misc.txt: convert it to ReST markup - Fix identation for the document title; - use monotonic fonts for commands, paths, etc; - use quote blocks where needed; - adjust spaces to properly format paragraphs; - add it to the user book. Signed-off-by: Mauro Carvalho Chehab --- Documentation/binfmt_misc.txt | 134 ++++++++++++++++++++++++------------------ 1 file changed, 77 insertions(+), 57 deletions(-) diff --git a/Documentation/binfmt_misc.txt b/Documentation/binfmt_misc.txt index ec83bbce547a..9c5ff8f260bf 100644 --- a/Documentation/binfmt_misc.txt +++ b/Documentation/binfmt_misc.txt @@ -1,5 +1,5 @@ - Kernel Support for miscellaneous (your favourite) Binary Formats v1.1 - ===================================================================== +Kernel Support for miscellaneous (your favourite) Binary Formats v1.1 +===================================================================== This Kernel feature allows you to invoke almost (for restrictions see below) every program by simply typing its name in the shell. @@ -9,122 +9,142 @@ To achieve this you must tell binfmt_misc which interpreter has to be invoked with which binary. Binfmt_misc recognises the binary-type by matching some bytes at the beginning of the file with a magic byte sequence (masking out specified bits) you have supplied. Binfmt_misc can also recognise a filename extension -aka '.com' or '.exe'. +aka ``.com`` or ``.exe``. -First you must mount binfmt_misc: - mount binfmt_misc -t binfmt_misc /proc/sys/fs/binfmt_misc +First you must mount binfmt_misc:: + + mount binfmt_misc -t binfmt_misc /proc/sys/fs/binfmt_misc To actually register a new binary type, you have to set up a string looking like -:name:type:offset:magic:mask:interpreter:flags (where you can choose the ':' -upon your needs) and echo it to /proc/sys/fs/binfmt_misc/register. +``:name:type:offset:magic:mask:interpreter:flags`` (where you can choose the +``:`` upon your needs) and echo it to ``/proc/sys/fs/binfmt_misc/register``. Here is what the fields mean: - - 'name' is an identifier string. A new /proc file will be created with this - name below /proc/sys/fs/binfmt_misc; cannot contain slashes '/' for obvious - reasons. - - 'type' is the type of recognition. Give 'M' for magic and 'E' for extension. - - 'offset' is the offset of the magic/mask in the file, counted in bytes. This - defaults to 0 if you omit it (i.e. you write ':name:type::magic...'). Ignored - when using filename extension matching. - - 'magic' is the byte sequence binfmt_misc is matching for. The magic string - may contain hex-encoded characters like \x0a or \xA4. Note that you must - escape any NUL bytes; parsing halts at the first one. In a shell environment - you might have to write \\x0a to prevent the shell from eating your \. + +- ``name`` + is an identifier string. A new /proc file will be created with this + ``name below /proc/sys/fs/binfmt_misc``; cannot contain slashes ``/`` for + obvious reasons. +- ``type`` + is the type of recognition. Give ``M`` for magic and ``E`` for extension. +- ``offset`` + is the offset of the magic/mask in the file, counted in bytes. This + defaults to 0 if you omit it (i.e. you write ``:name:type::magic...``). + Ignored when using filename extension matching. +- ``magic`` + is the byte sequence binfmt_misc is matching for. The magic string + may contain hex-encoded characters like ``\x0a`` or ``\xA4``. Note that you + must escape any NUL bytes; parsing halts at the first one. In a shell + environment you might have to write ``\\x0a`` to prevent the shell from + eating your ``\``. If you chose filename extension matching, this is the extension to be - recognised (without the '.', the \x0a specials are not allowed). Extension - matching is case sensitive, and slashes '/' are not allowed! - - 'mask' is an (optional, defaults to all 0xff) mask. You can mask out some + recognised (without the ``.``, the ``\x0a`` specials are not allowed). + Extension matching is case sensitive, and slashes ``/`` are not allowed! +- ``mask`` + is an (optional, defaults to all 0xff) mask. You can mask out some bits from matching by supplying a string like magic and as long as magic. The mask is anded with the byte sequence of the file. Note that you must escape any NUL bytes; parsing halts at the first one. Ignored when using filename extension matching. - - 'interpreter' is the program that should be invoked with the binary as first +- ``interpreter`` + is the program that should be invoked with the binary as first argument (specify the full path) - - 'flags' is an optional field that controls several aspects of the invocation +- ``flags`` + is an optional field that controls several aspects of the invocation of the interpreter. It is a string of capital letters, each controls a - certain aspect. The following flags are supported - - 'P' - preserve-argv[0]. Legacy behavior of binfmt_misc is to overwrite + certain aspect. The following flags are supported: + + ``P`` - preserve-argv[0] + Legacy behavior of binfmt_misc is to overwrite the original argv[0] with the full path to the binary. When this flag is included, binfmt_misc will add an argument to the argument - vector for this purpose, thus preserving the original argv[0]. - e.g. If your interp is set to /bin/foo and you run `blah` (which is - in /usr/local/bin), then the kernel will execute /bin/foo with - argv[] set to ["/bin/foo", "/usr/local/bin/blah", "blah"]. The - interp has to be aware of this so it can execute /usr/local/bin/blah - with argv[] set to ["blah"]. - 'O' - open-binary. Legacy behavior of binfmt_misc is to pass the full path + vector for this purpose, thus preserving the original ``argv[0]``. + e.g. If your interp is set to ``/bin/foo`` and you run ``blah`` + (which is in ``/usr/local/bin``), then the kernel will execute + ``/bin/foo`` with ``argv[]`` set to ``["/bin/foo", "/usr/local/bin/blah", "blah"]``. The interp has to be aware of this so it can + execute ``/usr/local/bin/blah`` + with ``argv[]`` set to ``["blah"]``. + ``O`` - open-binary + Legacy behavior of binfmt_misc is to pass the full path of the binary to the interpreter as an argument. When this flag is included, binfmt_misc will open the file for reading and pass its descriptor as an argument, instead of the full path, thus allowing the interpreter to execute non-readable binaries. This feature should be used with care - the interpreter has to be trusted not to emit the contents of the non-readable binary. - 'C' - credentials. Currently, the behavior of binfmt_misc is to calculate + ``C`` - credentials + Currently, the behavior of binfmt_misc is to calculate the credentials and security token of the new process according to the interpreter. When this flag is included, these attributes are - calculated according to the binary. It also implies the 'O' flag. + calculated according to the binary. It also implies the ``O`` flag. This feature should be used with care as the interpreter will run with root permissions when a setuid binary owned by root is run with binfmt_misc. - 'F' - fix binary. The usual behaviour of binfmt_misc is to spawn the - binary lazily when the misc format file is invoked. However, - this doesn't work very well in the face of mount namespaces and - changeroots, so the F mode opens the binary as soon as the + ``F`` - fix binary + The usual behaviour of binfmt_misc is to spawn the + binary lazily when the misc format file is invoked. However, + this doesn``t work very well in the face of mount namespaces and + changeroots, so the ``F`` mode opens the binary as soon as the emulation is installed and uses the opened image to spawn the emulator, meaning it is always available once installed, regardless of how the environment changes. There are some restrictions: + - the whole register string may not exceed 1920 characters - the magic must reside in the first 128 bytes of the file, i.e. offset+size(magic) has to be less than 128 - the interpreter string may not exceed 127 characters To use binfmt_misc you have to mount it first. You can mount it with -"mount -t binfmt_misc none /proc/sys/fs/binfmt_misc" command, or you can add -a line "none /proc/sys/fs/binfmt_misc binfmt_misc defaults 0 0" to your -/etc/fstab so it auto mounts on boot. +``mount -t binfmt_misc none /proc/sys/fs/binfmt_misc`` command, or you can add +a line ``none /proc/sys/fs/binfmt_misc binfmt_misc defaults 0 0`` to your +``/etc/fstab`` so it auto mounts on boot. -You may want to add the binary formats in one of your /etc/rc scripts during +You may want to add the binary formats in one of your ``/etc/rc`` scripts during boot-up. Read the manual of your init program to figure out how to do this right. Think about the order of adding entries! Later added entries are matched first! -A few examples (assumed you are in /proc/sys/fs/binfmt_misc): +A few examples (assumed you are in ``/proc/sys/fs/binfmt_misc``): + +- enable support for em86 (like binfmt_em86, for Alpha AXP only):: + + echo ':i386:M::\x7fELF\x01\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x02\x00\x03:\xff\xff\xff\xff\xff\xfe\xfe\xff\xff\xff\xff\xff\xff\xff\xff\xff\xfb\xff\xff:/bin/em86:' > register + echo ':i486:M::\x7fELF\x01\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x02\x00\x06:\xff\xff\xff\xff\xff\xfe\xfe\xff\xff\xff\xff\xff\xff\xff\xff\xff\xfb\xff\xff:/bin/em86:' > register + +- enable support for packed DOS applications (pre-configured dosemu hdimages):: -- 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 + echo ':DEXE:M::\x0eDEX::/usr/bin/dosexec:' > 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:: -- enable support for Windows executables using wine: - echo ':DOSWin:M::MZ::/usr/local/bin/wine:' > register + echo ':DOSWin:M::MZ::/usr/local/bin/wine:' > register For java support see Documentation/java.txt You can enable/disable binfmt_misc or one binary type by echoing 0 (to disable) -or 1 (to enable) to /proc/sys/fs/binfmt_misc/status or /proc/.../the_name. -Catting the file tells you the current status of binfmt_misc/the entry. +or 1 (to enable) to ``/proc/sys/fs/binfmt_misc/status`` or +``/proc/.../the_name``. +Catting the file tells you the current status of ``binfmt_misc/the_entry``. -You can remove one entry or all entries by echoing -1 to /proc/.../the_name -or /proc/sys/fs/binfmt_misc/status. +You can remove one entry or all entries by echoing -1 to ``/proc/.../the_name`` +or ``/proc/sys/fs/binfmt_misc/status``. -HINTS: -====== +Hints +----- If you want to pass special arguments to your interpreter, you can write a wrapper script for it. See Documentation/java.txt for an example. Your interpreter should NOT look in the PATH for the filename; the kernel -passes it the full filename (or the file descriptor) to use. Using $PATH can +passes it the full filename (or the file descriptor) to use. Using ``$PATH`` can cause unexpected behaviour and can be a security hazard. -- cgit v1.2.3 From c2ffd5dafa9dfbc48d5198c6d355617a756d2690 Mon Sep 17 00:00:00 2001 From: Mauro Carvalho Chehab Date: Wed, 21 Sep 2016 14:08:10 -0300 Subject: Documentation/serial-console.txt: convert it to ReST markup - Fix identation for the document title; - use monotonic fonts for paths; - use quote blocks where needed; - adjust spaces to properly format paragraphs; - use :menuselection: for the menu item; - add it to the user book. Signed-off-by: Mauro Carvalho Chehab --- Documentation/serial-console.txt | 66 +++++++++++++++++++++------------------- 1 file changed, 35 insertions(+), 31 deletions(-) diff --git a/Documentation/serial-console.txt b/Documentation/serial-console.txt index 9a7bc8b3f479..1d9a3e48e929 100644 --- a/Documentation/serial-console.txt +++ b/Documentation/serial-console.txt @@ -1,15 +1,19 @@ - Linux Serial Console +Linux Serial Console +==================== To use a serial port as console you need to compile the support into your kernel - by default it is not compiled in. For PC style serial ports -it's the config option next to "Standard/generic (dumb) serial support". +it's the config option next to menu option: + +:menuselection:`Character devices --> Serial drivers --> 8250/16550 and compatible serial support --> Console on 8250/16550 and compatible serial port` + You must compile serial support into the kernel and not as a module. It is possible to specify multiple devices for console output. You can define a new kernel command line option to select which device(s) to use for console output. -The format of this option is: +The format of this option is:: console=device,options @@ -28,11 +32,11 @@ The format of this option is: You can specify multiple console= options on the kernel command line. Output will appear on all of them. The last device will be used when -you open /dev/console. So, for example: +you open ``/dev/console``. So, for example:: console=ttyS1,9600 console=tty0 -defines that opening /dev/console will get you the current foreground +defines that opening ``/dev/console`` will get you the current foreground virtual console, and kernel messages will appear on both the VGA console and the 2nd serial port (ttyS1 or COM2) at 9600 baud. @@ -44,61 +48,61 @@ first looks for a VGA card and then for a serial port. So if you don't have a VGA card in your system the first serial port will automatically become the console. -You will need to create a new device to use /dev/console. The official -/dev/console is now character device 5,1. +You will need to create a new device to use ``/dev/console``. The official +``/dev/console`` is now character device 5,1. (You can also use a network device as a console. See -Documentation/networking/netconsole.txt for information on that.) +``Documentation/networking/netconsole.txt`` for information on that.) -Here's an example that will use /dev/ttyS1 (COM2) as the console. +Here's an example that will use ``/dev/ttyS1`` (COM2) as the console. Replace the sample values as needed. -1. Create /dev/console (real console) and /dev/tty0 (master virtual - console): +1. Create ``/dev/console`` (real console) and ``/dev/tty0`` (master virtual + console):: - cd /dev - rm -f console tty0 - mknod -m 622 console c 5 1 - mknod -m 622 tty0 c 4 0 + cd /dev + rm -f console tty0 + mknod -m 622 console c 5 1 + mknod -m 622 tty0 c 4 0 2. LILO can also take input from a serial device. This is a very useful option. To tell LILO to use the serial port: - In lilo.conf (global section): + In lilo.conf (global section):: - serial = 1,9600n8 (ttyS1, 9600 bd, no parity, 8 bits) + serial = 1,9600n8 (ttyS1, 9600 bd, no parity, 8 bits) 3. Adjust to kernel flags for the new kernel, - again in lilo.conf (kernel section) + again in lilo.conf (kernel section):: - append = "console=ttyS1,9600" + append = "console=ttyS1,9600" 4. Make sure a getty runs on the serial port so that you can login to it once the system is done booting. This is done by adding a line - like this to /etc/inittab (exact syntax depends on your getty): + like this to ``/etc/inittab`` (exact syntax depends on your getty):: - S1:23:respawn:/sbin/getty -L ttyS1 9600 vt100 + S1:23:respawn:/sbin/getty -L ttyS1 9600 vt100 -5. Init and /etc/ioctl.save +5. Init and ``/etc/ioctl.save`` - Sysvinit remembers its stty settings in a file in /etc, called - `/etc/ioctl.save'. REMOVE THIS FILE before using the serial + Sysvinit remembers its stty settings in a file in ``/etc``, called + ``/etc/ioctl.save``. REMOVE THIS FILE before using the serial console for the first time, because otherwise init will probably set the baudrate to 38400 (baudrate of the virtual console). -6. /dev/console and X +6. ``/dev/console`` and X Programs that want to do something with the virtual console usually - open /dev/console. If you have created the new /dev/console device, + open ``/dev/console``. If you have created the new ``/dev/console`` device, and your console is NOT the virtual console some programs will fail. Those are programs that want to access the VT interface, and use - /dev/console instead of /dev/tty0. Some of those programs are: + ``/dev/console instead of /dev/tty0``. Some of those programs are:: - Xfree86, svgalib, gpm, SVGATextMode + Xfree86, svgalib, gpm, SVGATextMode It should be fixed in modern versions of these programs though. - Note that if you boot without a console= option (or with - console=/dev/tty0), /dev/console is the same as /dev/tty0. In that - case everything will still work. + Note that if you boot without a ``console=`` option (or with + ``console=/dev/tty0``), ``/dev/console`` is the same as ``/dev/tty0``. + In that case everything will still work. 7. Thanks -- cgit v1.2.3 From 8e7fbec662554b25ac832116cfe2d47db635d33c Mon Sep 17 00:00:00 2001 From: Mauro Carvalho Chehab Date: Wed, 21 Sep 2016 14:44:59 -0300 Subject: Documentation/braille-console: convert it to ReST markup - Fix identation for the document title; - use monotonic fonts for paths; - use quote blocks where needed; - adjust spaces to properly format paragraphs; - use :menuselection: and :kbd: for the menu item and keys; - point too the right item at the menu; - add it to the user book. Signed-off-by: Mauro Carvalho Chehab --- Documentation/braille-console.txt | 30 +++++++++++++++++------------- Documentation/serial-console.txt | 2 ++ 2 files changed, 19 insertions(+), 13 deletions(-) diff --git a/Documentation/braille-console.txt b/Documentation/braille-console.txt index d0d042c2fd5e..fa3702dc04ab 100644 --- a/Documentation/braille-console.txt +++ b/Documentation/braille-console.txt @@ -1,33 +1,37 @@ - Linux Braille Console +Linux Braille Console +===================== To get early boot messages on a braille device (before userspace screen readers can start), you first need to compile the support for the usual serial -console (see serial-console.txt), and for braille device (in Device Drivers - -Accessibility). +console (see :ref:`Documentation/serial-console.txt `), and +for braille device +(in :menuselection:`Device Drivers --> Accessibility support --> Console on braille device`). -Then you need to specify a console=brl, option on the kernel command line, the -format is: +Then you need to specify a ``console=brl``, option on the kernel command line, the +format is:: console=brl,serial_options... -where serial_options... are the same as described in serial-console.txt +where ``serial_options...`` are the same as described in +:ref:`Documentation/serial-console.txt `. -So for instance you can use console=brl,ttyS0 if the braille device is connected -to the first serial port, and console=brl,ttyS0,115200 to override the baud rate -to 115200, etc. +So for instance you can use ``console=brl,ttyS0`` if the braille device is connected to the first serial port, and ``console=brl,ttyS0,115200`` to +override the baud rate to 115200, etc. By default, the braille device will just show the last kernel message (console mode). To review previous messages, press the Insert key to switch to the VT review mode. In review mode, the arrow keys permit to browse in the VT content, -page up/down keys go at the top/bottom of the screen, and the home key goes back +:kbd:`PAGE-UP`/:kbd:`PAGE-DOWN` keys go at the top/bottom of the screen, and +the :kbd:`HOME` key goes back to the cursor, hence providing very basic screen reviewing facility. -Sound feedback can be obtained by adding the braille_console.sound=1 kernel +Sound feedback can be obtained by adding the ``braille_console.sound=1`` kernel parameter. For simplicity, only one braille console can be enabled, other uses of -console=brl,... will be discarded. Also note that it does not interfere with -the console selection mechanism described in serial-console.txt +``console=brl,...`` will be discarded. Also note that it does not interfere with +the console selection mechanism described in +:ref:`Documentation/serial-console.txt `. For now, only the VisioBraille device is supported. diff --git a/Documentation/serial-console.txt b/Documentation/serial-console.txt index 1d9a3e48e929..a8d1e36b627a 100644 --- a/Documentation/serial-console.txt +++ b/Documentation/serial-console.txt @@ -1,3 +1,5 @@ +.. _serial_console: + Linux Serial Console ==================== -- cgit v1.2.3 From 953ab835a98166529e971e91d20d78c2ce2c7f7d Mon Sep 17 00:00:00 2001 From: Mauro Carvalho Chehab Date: Wed, 21 Sep 2016 15:16:45 -0300 Subject: Documentation/BUG-HUNTING: convert to ReST markup - Add a document title and remove its own index; - use monotonic fonts for paths; - use quote blocks where needed; - adjust/use spaces to properly format paragraphs; - add it to the user book. Signed-off-by: Mauro Carvalho Chehab --- Documentation/BUG-HUNTING | 164 +++++++++++++++++++++++----------------------- 1 file changed, 83 insertions(+), 81 deletions(-) diff --git a/Documentation/BUG-HUNTING b/Documentation/BUG-HUNTING index 65022a87bf17..a8ef794aadae 100644 --- a/Documentation/BUG-HUNTING +++ b/Documentation/BUG-HUNTING @@ -1,18 +1,8 @@ -Table of contents -================= +Bug hunting ++++++++++++ Last updated: 20 December 2005 -Contents -======== - -- Introduction -- Devices not appearing -- Finding patch that caused a bug --- Finding using git-bisect --- Finding it the old way -- Fixing the bug - Introduction ============ @@ -24,7 +14,8 @@ Finding bugs is not always easy. Have a go though. If you can't find it don't give up. Report as much as you have found to the relevant maintainer. See MAINTAINERS for who that is for the subsystem you have worked on. -Before you submit a bug report read REPORTING-BUGS. +Before you submit a bug report read +:ref:`Documentation/REPORTING-BUGS `. Devices not appearing ===================== @@ -37,15 +28,16 @@ Finding patch that caused a bug -Finding using git-bisect ------------------------- +Finding using ``git-bisect`` +---------------------------- -Using the provided tools with git makes finding bugs easy provided the bug is -reproducible. +Using the provided tools with ``git`` makes finding bugs easy provided the bug +is reproducible. Steps to do it: + - start using git for the kernel source -- read the man page for git-bisect +- read the man page for ``git-bisect`` - have fun Finding it the old way @@ -58,22 +50,22 @@ It's a brute force approach but it works pretty well. You need: - . A reproducible bug - it has to happen predictably (sorry) - . All the kernel tar files from a revision that worked to the + - A reproducible bug - it has to happen predictably (sorry) + - All the kernel tar files from a revision that worked to the revision that doesn't You will then do: - . Rebuild a revision that you believe works, install, and verify that. - . Do a binary search over the kernels to figure out which one + - Rebuild a revision that you believe works, install, and verify that. + - Do a binary search over the kernels to figure out which one introduced the bug. I.e., suppose 1.3.28 didn't have the bug, but you know that 1.3.69 does. Pick a kernel in the middle and build that, like 1.3.50. Build & test; if it works, pick the mid point between .50 and .69, else the mid point between .28 and .50. - . You'll narrow it down to the kernel that introduced the bug. You + - You'll narrow it down to the kernel that introduced the bug. You can probably do better than this but it gets tricky. - . Narrow it down to a subdirectory + - Narrow it down to a subdirectory - Copy kernel that works into "test". Let's say that 3.62 works, but 3.63 doesn't. So you diff -r those two kernels and come @@ -83,7 +75,7 @@ You will then do: Copy the non-working directory next to the working directory as "dir.63". One directory at time, try moving the working directory to - "dir.62" and mv dir.63 dir"time, try + "dir.62" and mv dir.63 dir"time, try:: mv dir dir.62 mv dir.63 dir @@ -97,15 +89,15 @@ You will then do: found in my case that they were self explanatory - you may or may not want to give up when that happens. - . Narrow it down to a file + - Narrow it down to a file - You can apply the same technique to each file in the directory, hoping that the changes in that file are self contained. - . Narrow it down to a routine + - Narrow it down to a routine - You can take the old file and the new file and manually create - a merged file that has + a merged file that has:: #ifdef VER62 routine() @@ -120,7 +112,7 @@ You will then do: #endif And then walk through that file, one routine at a time and - prefix it with + prefix it with:: #define VER62 /* both routines here */ @@ -153,94 +145,104 @@ To debug a kernel, use objdump and look for the hex offset from the crash output to find the valid line of code/assembler. Without debug symbols, you will see the assembler code for the routine shown, but if your kernel has debug symbols the C code will also be available. (Debug symbols can be enabled -in the kernel hacking menu of the menu configuration.) For example: +in the kernel hacking menu of the menu configuration.) For example:: objdump -r -S -l --disassemble net/dccp/ipv4.o -NB.: you need to be at the top level of the kernel tree for this to pick up -your C files. +.. note:: + + You need to be at the top level of the kernel tree for this to pick up + your C files. If you don't have access to the code you can also debug on some crash dumps -e.g. crash dump output as shown by Dave Miller. - -> 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 +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 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:[] 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
+ 0xda8) -or, as one command + +or, as one command:: + (gdb) l *(vt_ioctl + 0xda8) -If you have a call trace, such as :- ->Call Trace: -> [] :jbd:log_wait_commit+0xa3/0xf5 -> [] autoremove_wake_function+0x0/0x2e -> [] :jbd:journal_stop+0x1be/0x1ee -> ... +If you have a call trace, such as:: + + Call Trace: + [] :jbd:log_wait_commit+0xa3/0xf5 + [] autoremove_wake_function+0x0/0x2e + [] :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
+ 0xa3) -or + +or:: + (gdb) l *(log_wait_commit + 0xa3) Another very useful option of the Kernel Hacking section in menuconfig is Debug memory allocations. This will help you see whether data has been initialised and not set before use etc. To see the values that get assigned -with this look at mm/slab.c and search for POISON_INUSE. When using this an -Oops will often show the poisoned data instead of zero which is the default. +with this look at ``mm/slab.c`` and search for ``POISON_INUSE``. When using +this an Oops will often show the poisoned data instead of zero which is the +default. Once you have worked out a fix please submit it upstream. After all open source is about sharing what you do and don't you want to be recognised for your genius? -Please do read Documentation/SubmittingPatches though to help your code get -accepted. +Please do read :ref:`Documentation/SubmittingPatches ` +though to help your code get accepted. -- cgit v1.2.3 From d9f92f9f9d0e6e6ea98cd5c52cfd474cff20af22 Mon Sep 17 00:00:00 2001 From: Mauro Carvalho Chehab Date: Wed, 21 Sep 2016 15:47:58 -0300 Subject: Documentation/devices.rst: convert it to ReST markup - use a quote block for the big device major/minor list; - use tables for the other device tables; - fix the chapter/section/subsection markups; - use ``foo`` for monotonic; - use .. attention:: for the attention note to developers; - use cross-references where needed; - cleanup whitespaces; - add it to the user's book. Signed-off-by: Mauro Carvalho Chehab --- Documentation/devices.txt | 1090 +++++++++++++++++++++++---------------------- 1 file changed, 558 insertions(+), 532 deletions(-) diff --git a/Documentation/devices.txt b/Documentation/devices.txt index 4035eca87144..17b365331f23 100644 --- a/Documentation/devices.txt +++ b/Documentation/devices.txt @@ -1,14 +1,16 @@ - LINUX ALLOCATED DEVICES (4.x+ version) +Linux allocated devices (4.x+ version) +====================================== This list is the Linux Device List, the official registry of allocated -device numbers and /dev directory nodes for the Linux operating +device numbers and ``/dev`` directory nodes for the Linux operating system. The LaTeX version of this document is no longer maintained, nor is the document that used to reside at lanana.org. This version in the mainline Linux kernel is the master document. Updates shall be sent -as patches to the kernel maintainers (see the SubmittingPatches document). +as patches to the kernel maintainers (see the +:ref:`Documentation/SubmittingPatches ` document). Specifically explore the sections titled "CHAR and MISC DRIVERS", and "BLOCK LAYER" in the MAINTAINERS file to find the right maintainers to involve for character and block devices. @@ -26,38 +28,41 @@ permission of the authors, assuming the authors can be contacted without an unreasonable effort. - **** DEVICE DRIVERS AUTHORS PLEASE READ THIS **** +.. attention:: -Linux now has extensive support for dynamic allocation of device numbering -and can use sysfs and udev (systemd) to handle the naming needs. There are -still some exceptions in the serial and boot device area. Before asking -for a device number make sure you actually need one. + DEVICE DRIVERS AUTHORS PLEASE READ THIS -To have a major number allocated, or a minor number in situations -where that applies (e.g. busmice), please submit a patch and send to -the authors as indicated above. + Linux now has extensive support for dynamic allocation of device numbering + and can use ``sysfs`` and ``udev`` (``systemd``) to handle the naming needs. + There are still some exceptions in the serial and boot device area. Before + asking for a device number make sure you actually need one. -Keep the description of the device *in the same format -as this list*. The reason for this is that it is the only way we have -found to ensure we have all the requisite information to publish your -device and avoid conflicts. + To have a major number allocated, or a minor number in situations + where that applies (e.g. busmice), please submit a patch and send to + the authors as indicated above. -Finally, sometimes we have to play "namespace police." Please don't be -offended. We often get submissions for /dev names that would be bound -to cause conflicts down the road. We are trying to avoid getting in a -situation where we would have to suffer an incompatible forward -change. Therefore, please consult with us *before* you make your -device names and numbers in any way public, at least to the point -where it would be at all difficult to get them changed. + Keep the description of the device *in the same format + as this list*. The reason for this is that it is the only way we have + found to ensure we have all the requisite information to publish your + device and avoid conflicts. -Your cooperation is appreciated. + Finally, sometimes we have to play "namespace police." Please don't be + offended. We often get submissions for ``/dev`` names that would be bound + to cause conflicts down the road. We are trying to avoid getting in a + situation where we would have to suffer an incompatible forward + change. Therefore, please consult with us **before** you make your + device names and numbers in any way public, at least to the point + where it would be at all difficult to get them changed. + Your cooperation is appreciated. - 0 Unnamed devices (e.g. non-device mounts) +:: + + 0 Unnamed devices (e.g. non-device mounts) 0 = reserved as null device number See block major 144, 145, 146 for expansion areas. - 1 char Memory devices + 1 char Memory devices 1 = /dev/mem Physical memory access 2 = /dev/kmem Kernel virtual memory access 3 = /dev/null Null device @@ -72,7 +77,7 @@ Your cooperation is appreciated. export the buffered printk records. 12 = /dev/oldmem OBSOLETE - replaced by /proc/vmcore - 1 block RAM disk + 1 block RAM disk 0 = /dev/ram0 First RAM disk 1 = /dev/ram1 Second RAM disk ... @@ -83,7 +88,7 @@ Your cooperation is appreciated. by the boot loader; newer kernels use /dev/ram0 for the initrd. - 2 char Pseudo-TTY masters + 2 char Pseudo-TTY masters 0 = /dev/ptyp0 First PTY master 1 = /dev/ptyp1 Second PTY master ... @@ -101,7 +106,7 @@ Your cooperation is appreciated. master multiplex (/dev/ptmx) to acquire a PTY on demand. - 2 block Floppy disks + 2 block Floppy disks 0 = /dev/fd0 Controller 0, drive 0, autodetect 1 = /dev/fd1 Controller 0, drive 1, autodetect 2 = /dev/fd2 Controller 0, drive 2, autodetect @@ -158,7 +163,7 @@ Your cooperation is appreciated. and E for the 3.5" models have been deprecated, since the drive type is insignificant for these devices. - 3 char Pseudo-TTY slaves + 3 char Pseudo-TTY slaves 0 = /dev/ttyp0 First PTY slave 1 = /dev/ttyp1 Second PTY slave ... @@ -167,7 +172,7 @@ Your cooperation is appreciated. These are the old-style (BSD) PTY devices; Unix98 devices are on major 136 and above. - 3 block First MFM, RLL and IDE hard disk/CD-ROM interface + 3 block First MFM, RLL and IDE hard disk/CD-ROM interface 0 = /dev/hda Master: whole disk (or CD-ROM) 64 = /dev/hdb Slave: whole disk (or CD-ROM) @@ -183,7 +188,7 @@ Your cooperation is appreciated. Other versions of Linux use partitioning schemes appropriate to their respective architectures. - 4 char TTY devices + 4 char TTY devices 0 = /dev/tty0 Current virtual console 1 = /dev/tty1 First virtual console @@ -199,13 +204,13 @@ Your cooperation is appreciated. number for BSD PTY devices. As of Linux 2.1.115, this is no longer supported. Use major numbers 2 and 3. - 4 block Aliases for dynamically allocated major devices to be used + 4 block Aliases for dynamically allocated major devices to be used when its not possible to create the real device nodes because the root filesystem is mounted read-only. - 0 = /dev/root + 0 = /dev/root - 5 char Alternate TTY devices + 5 char Alternate TTY devices 0 = /dev/tty Current TTY device 1 = /dev/console System console 2 = /dev/ptmx PTY master multiplex @@ -218,7 +223,7 @@ Your cooperation is appreciated. the section on terminal devices for more information on /dev/console. - 6 char Parallel printer devices + 6 char Parallel printer devices 0 = /dev/lp0 Parallel printer on parport0 1 = /dev/lp1 Parallel printer on parport1 ... @@ -227,7 +232,7 @@ Your cooperation is appreciated. between parallel ports and I/O addresses. Instead, they are redirected through the parport multiplex layer. - 7 char Virtual console capture devices + 7 char Virtual console capture devices 0 = /dev/vcs Current vc text contents 1 = /dev/vcs1 tty1 text contents ... @@ -239,7 +244,7 @@ Your cooperation is appreciated. NOTE: These devices permit both read and write access. - 7 block Loopback devices + 7 block Loopback devices 0 = /dev/loop0 First loop device 1 = /dev/loop1 Second loop device ... @@ -248,7 +253,7 @@ Your cooperation is appreciated. associated with block devices. The binding to the loop devices is handled by mount(8) or losetup(8). - 8 block SCSI disk devices (0-15) + 8 block SCSI disk devices (0-15) 0 = /dev/sda First SCSI disk whole disk 16 = /dev/sdb Second SCSI disk whole disk 32 = /dev/sdc Third SCSI disk whole disk @@ -259,7 +264,7 @@ Your cooperation is appreciated. disks (see major number 3) except that the limit on partitions is 15. - 9 char SCSI tape devices + 9 char SCSI tape devices 0 = /dev/st0 First SCSI tape, mode 0 1 = /dev/st1 Second SCSI tape, mode 0 ... @@ -290,7 +295,7 @@ Your cooperation is appreciated. ioctl()'s can be used to rewind the tape regardless of the device used to access it. - 9 block Metadisk (RAID) devices + 9 block Metadisk (RAID) devices 0 = /dev/md0 First metadisk group 1 = /dev/md1 Second metadisk group ... @@ -298,7 +303,7 @@ Your cooperation is appreciated. The metadisk driver is used to span a filesystem across multiple physical disks. - 10 char Non-serial mice, misc features + 10 char Non-serial mice, misc features 0 = /dev/logibm Logitech bus mouse 1 = /dev/psaux PS/2-style mouse port 2 = /dev/inportbm Microsoft Inport bus mouse @@ -428,22 +433,22 @@ Your cooperation is appreciated. 240-254 Reserved for local use 255 Reserved for MISC_DYNAMIC_MINOR - 11 char Raw keyboard device (Linux/SPARC only) + 11 char Raw keyboard device (Linux/SPARC only) 0 = /dev/kbd Raw keyboard device - 11 char Serial Mux device (Linux/PA-RISC only) + 11 char Serial Mux device (Linux/PA-RISC only) 0 = /dev/ttyB0 First mux port 1 = /dev/ttyB1 Second mux port ... - 11 block SCSI CD-ROM devices + 11 block SCSI CD-ROM devices 0 = /dev/scd0 First SCSI CD-ROM 1 = /dev/scd1 Second SCSI CD-ROM ... The prefix /dev/sr (instead of /dev/scd) has been deprecated. - 12 char QIC-02 tape + 12 char QIC-02 tape 2 = /dev/ntpqic11 QIC-11, no rewind-on-close 3 = /dev/tpqic11 QIC-11, rewind-on-close 4 = /dev/ntpqic24 QIC-24, no rewind-on-close @@ -456,9 +461,9 @@ Your cooperation is appreciated. The device names specified are proposed -- if there are "standard" names for these devices, please let me know. - 12 block + 12 block - 13 char Input core + 13 char Input core 0 = /dev/input/js0 First joystick 1 = /dev/input/js1 Second joystick ... @@ -472,10 +477,10 @@ Your cooperation is appreciated. Each device type has 5 bits (32 minors). - 13 block Previously used for the XT disk (/dev/xdN) + 13 block Previously used for the XT disk (/dev/xdN) Deleted in kernel v3.9. - 14 char Open Sound System (OSS) + 14 char Open Sound System (OSS) 0 = /dev/mixer Mixer control 1 = /dev/sequencer Audio sequencer 2 = /dev/midi00 First MIDI port @@ -493,44 +498,44 @@ Your cooperation is appreciated. 34 = /dev/midi02 Third MIDI port 50 = /dev/midi03 Fourth MIDI port - 14 block + 14 block - 15 char Joystick + 15 char Joystick 0 = /dev/js0 First analog joystick 1 = /dev/js1 Second analog joystick ... 128 = /dev/djs0 First digital joystick 129 = /dev/djs1 Second digital joystick ... - 15 block Sony CDU-31A/CDU-33A CD-ROM + 15 block Sony CDU-31A/CDU-33A CD-ROM 0 = /dev/sonycd Sony CDU-31a CD-ROM - 16 char Non-SCSI scanners + 16 char Non-SCSI scanners 0 = /dev/gs4500 Genius 4500 handheld scanner - 16 block GoldStar CD-ROM + 16 block GoldStar CD-ROM 0 = /dev/gscd GoldStar CD-ROM - 17 char OBSOLETE (was Chase serial card) + 17 char OBSOLETE (was Chase serial card) 0 = /dev/ttyH0 First Chase port 1 = /dev/ttyH1 Second Chase port ... - 17 block Optics Storage CD-ROM + 17 block Optics Storage CD-ROM 0 = /dev/optcd Optics Storage CD-ROM - 18 char OBSOLETE (was Chase serial card - alternate devices) + 18 char OBSOLETE (was Chase serial card - alternate devices) 0 = /dev/cuh0 Callout device for ttyH0 1 = /dev/cuh1 Callout device for ttyH1 ... - 18 block Sanyo CD-ROM + 18 block Sanyo CD-ROM 0 = /dev/sjcd Sanyo CD-ROM - 19 char Cyclades serial card + 19 char Cyclades serial card 0 = /dev/ttyC0 First Cyclades port ... 31 = /dev/ttyC31 32nd Cyclades port - 19 block "Double" compressed disk + 19 block "Double" compressed disk 0 = /dev/double0 First compressed disk ... 7 = /dev/double7 Eighth compressed disk @@ -541,15 +546,15 @@ Your cooperation is appreciated. See the Double documentation for the meaning of the mirror devices. - 20 char Cyclades serial card - alternate devices + 20 char Cyclades serial card - alternate devices 0 = /dev/cub0 Callout device for ttyC0 ... 31 = /dev/cub31 Callout device for ttyC31 - 20 block Hitachi CD-ROM (under development) + 20 block Hitachi CD-ROM (under development) 0 = /dev/hitcd Hitachi CD-ROM - 21 char Generic SCSI access + 21 char Generic SCSI access 0 = /dev/sg0 First generic SCSI device 1 = /dev/sg1 Second generic SCSI device ... @@ -559,7 +564,7 @@ Your cooperation is appreciated. the system and is counter to standard Linux device-naming practice. - 21 block Acorn MFM hard drive interface + 21 block Acorn MFM hard drive interface 0 = /dev/mfma First MFM drive whole disk 64 = /dev/mfmb Second MFM drive whole disk @@ -567,25 +572,25 @@ Your cooperation is appreciated. Partitions are handled the same way as for IDE disks (see major number 3). - 22 char Digiboard serial card + 22 char Digiboard serial card 0 = /dev/ttyD0 First Digiboard port 1 = /dev/ttyD1 Second Digiboard port ... - 22 block Second IDE hard disk/CD-ROM interface + 22 block Second IDE hard disk/CD-ROM interface 0 = /dev/hdc Master: whole disk (or CD-ROM) 64 = /dev/hdd Slave: whole disk (or CD-ROM) Partitions are handled the same way as for the first interface (see major number 3). - 23 char Digiboard serial card - alternate devices + 23 char Digiboard serial card - alternate devices 0 = /dev/cud0 Callout device for ttyD0 1 = /dev/cud1 Callout device for ttyD1 ... - 23 block Mitsumi proprietary CD-ROM + 23 block Mitsumi proprietary CD-ROM 0 = /dev/mcd Mitsumi CD-ROM - 24 char Stallion serial card + 24 char Stallion serial card 0 = /dev/ttyE0 Stallion port 0 card 0 1 = /dev/ttyE1 Stallion port 1 card 0 ... @@ -598,10 +603,10 @@ Your cooperation is appreciated. 192 = /dev/ttyE192 Stallion port 0 card 3 193 = /dev/ttyE193 Stallion port 1 card 3 ... - 24 block Sony CDU-535 CD-ROM + 24 block Sony CDU-535 CD-ROM 0 = /dev/cdu535 Sony CDU-535 CD-ROM - 25 char Stallion serial card - alternate devices + 25 char Stallion serial card - alternate devices 0 = /dev/cue0 Callout device for ttyE0 1 = /dev/cue1 Callout device for ttyE1 ... @@ -614,21 +619,21 @@ Your cooperation is appreciated. 192 = /dev/cue192 Callout device for ttyE192 193 = /dev/cue193 Callout device for ttyE193 ... - 25 block First Matsushita (Panasonic/SoundBlaster) CD-ROM + 25 block First Matsushita (Panasonic/SoundBlaster) CD-ROM 0 = /dev/sbpcd0 Panasonic CD-ROM controller 0 unit 0 1 = /dev/sbpcd1 Panasonic CD-ROM controller 0 unit 1 2 = /dev/sbpcd2 Panasonic CD-ROM controller 0 unit 2 3 = /dev/sbpcd3 Panasonic CD-ROM controller 0 unit 3 - 26 char + 26 char - 26 block Second Matsushita (Panasonic/SoundBlaster) CD-ROM + 26 block Second Matsushita (Panasonic/SoundBlaster) CD-ROM 0 = /dev/sbpcd4 Panasonic CD-ROM controller 1 unit 0 1 = /dev/sbpcd5 Panasonic CD-ROM controller 1 unit 1 2 = /dev/sbpcd6 Panasonic CD-ROM controller 1 unit 2 3 = /dev/sbpcd7 Panasonic CD-ROM controller 1 unit 3 - 27 char QIC-117 tape + 27 char QIC-117 tape 0 = /dev/qft0 Unit 0, rewind-on-close 1 = /dev/qft1 Unit 1, rewind-on-close 2 = /dev/qft2 Unit 2, rewind-on-close @@ -654,29 +659,29 @@ Your cooperation is appreciated. 38 = /dev/nrawqft2 Unit 2, no rewind-on-close, no file marks 39 = /dev/nrawqft3 Unit 3, no rewind-on-close, no file marks - 27 block Third Matsushita (Panasonic/SoundBlaster) CD-ROM + 27 block Third Matsushita (Panasonic/SoundBlaster) CD-ROM 0 = /dev/sbpcd8 Panasonic CD-ROM controller 2 unit 0 1 = /dev/sbpcd9 Panasonic CD-ROM controller 2 unit 1 2 = /dev/sbpcd10 Panasonic CD-ROM controller 2 unit 2 3 = /dev/sbpcd11 Panasonic CD-ROM controller 2 unit 3 - 28 char Stallion serial card - card programming + 28 char Stallion serial card - card programming 0 = /dev/staliomem0 First Stallion card I/O memory 1 = /dev/staliomem1 Second Stallion card I/O memory 2 = /dev/staliomem2 Third Stallion card I/O memory 3 = /dev/staliomem3 Fourth Stallion card I/O memory - 28 char Atari SLM ACSI laser printer (68k/Atari) + 28 char Atari SLM ACSI laser printer (68k/Atari) 0 = /dev/slm0 First SLM laser printer 1 = /dev/slm1 Second SLM laser printer ... - 28 block Fourth Matsushita (Panasonic/SoundBlaster) CD-ROM + 28 block Fourth Matsushita (Panasonic/SoundBlaster) CD-ROM 0 = /dev/sbpcd12 Panasonic CD-ROM controller 3 unit 0 1 = /dev/sbpcd13 Panasonic CD-ROM controller 3 unit 1 2 = /dev/sbpcd14 Panasonic CD-ROM controller 3 unit 2 3 = /dev/sbpcd15 Panasonic CD-ROM controller 3 unit 3 - 28 block ACSI disk (68k/Atari) + 28 block ACSI disk (68k/Atari) 0 = /dev/ada First ACSI disk whole disk 16 = /dev/adb Second ACSI disk whole disk 32 = /dev/adc Third ACSI disk whole disk @@ -687,16 +692,16 @@ Your cooperation is appreciated. disks (see major number 3) except that the limit on partitions is 15, like SCSI. - 29 char Universal frame buffer + 29 char Universal frame buffer 0 = /dev/fb0 First frame buffer 1 = /dev/fb1 Second frame buffer ... 31 = /dev/fb31 32nd frame buffer - 29 block Aztech/Orchid/Okano/Wearnes CD-ROM + 29 block Aztech/Orchid/Okano/Wearnes CD-ROM 0 = /dev/aztcd Aztech CD-ROM - 30 char iBCS-2 compatibility devices + 30 char iBCS-2 compatibility devices 0 = /dev/socksys Socket access 1 = /dev/spx SVR3 local X interface 32 = /dev/inet/ip Network access @@ -727,17 +732,17 @@ Your cooperation is appreciated. /dev/nfsd -> /dev/socksys /dev/X0R -> /dev/null (? apparently not required ?) - 30 block Philips LMS CM-205 CD-ROM + 30 block Philips LMS CM-205 CD-ROM 0 = /dev/cm205cd Philips LMS CM-205 CD-ROM /dev/lmscd is an older name for this device. This driver does not work with the CM-205MS CD-ROM. - 31 char MPU-401 MIDI + 31 char MPU-401 MIDI 0 = /dev/mpu401data MPU-401 data port 1 = /dev/mpu401stat MPU-401 status port - 31 block ROM/flash memory card + 31 block ROM/flash memory card 0 = /dev/rom0 First ROM card (rw) ... 7 = /dev/rom7 Eighth ROM card (rw) @@ -756,25 +761,25 @@ Your cooperation is appreciated. devices. The read-only devices (ro) support reading only. - 32 char Specialix serial card + 32 char Specialix serial card 0 = /dev/ttyX0 First Specialix port 1 = /dev/ttyX1 Second Specialix port ... - 32 block Philips LMS CM-206 CD-ROM + 32 block Philips LMS CM-206 CD-ROM 0 = /dev/cm206cd Philips LMS CM-206 CD-ROM - 33 char Specialix serial card - alternate devices + 33 char Specialix serial card - alternate devices 0 = /dev/cux0 Callout device for ttyX0 1 = /dev/cux1 Callout device for ttyX1 ... - 33 block Third IDE hard disk/CD-ROM interface + 33 block Third IDE hard disk/CD-ROM interface 0 = /dev/hde Master: whole disk (or CD-ROM) 64 = /dev/hdf Slave: whole disk (or CD-ROM) Partitions are handled the same way as for the first interface (see major number 3). - 34 char Z8530 HDLC driver + 34 char Z8530 HDLC driver 0 = /dev/scc0 First Z8530, first port 1 = /dev/scc1 First Z8530, second port 2 = /dev/scc2 Second Z8530, first port @@ -785,14 +790,14 @@ Your cooperation is appreciated. /dev/sc1 for /dev/scc0, /dev/sc2 for /dev/scc1, and so on. - 34 block Fourth IDE hard disk/CD-ROM interface + 34 block Fourth IDE hard disk/CD-ROM interface 0 = /dev/hdg Master: whole disk (or CD-ROM) 64 = /dev/hdh Slave: whole disk (or CD-ROM) Partitions are handled the same way as for the first interface (see major number 3). - 35 char tclmidi MIDI driver + 35 char tclmidi MIDI driver 0 = /dev/midi0 First MIDI port, kernel timed 1 = /dev/midi1 Second MIDI port, kernel timed 2 = /dev/midi2 Third MIDI port, kernel timed @@ -806,10 +811,10 @@ Your cooperation is appreciated. 130 = /dev/smpte2 Third MIDI port, SMPTE timed 131 = /dev/smpte3 Fourth MIDI port, SMPTE timed - 35 block Slow memory ramdisk + 35 block Slow memory ramdisk 0 = /dev/slram Slow memory ramdisk - 36 char Netlink support + 36 char Netlink support 0 = /dev/route Routing, device updates, kernel to user 1 = /dev/skip enSKIP security cache control 3 = /dev/fwmonitor Firewall packet copies @@ -817,9 +822,9 @@ Your cooperation is appreciated. ... 31 = /dev/tap15 16th Ethertap device - 36 block OBSOLETE (was MCA ESDI hard disk) + 36 block OBSOLETE (was MCA ESDI hard disk) - 37 char IDE tape + 37 char IDE tape 0 = /dev/ht0 First IDE tape 1 = /dev/ht1 Second IDE tape ... @@ -829,10 +834,10 @@ Your cooperation is appreciated. Currently, only one IDE tape drive is supported. - 37 block Zorro II ramdisk + 37 block Zorro II ramdisk 0 = /dev/z2ram Zorro II ramdisk - 38 char Myricom PCI Myrinet board + 38 char Myricom PCI Myrinet board 0 = /dev/mlanai0 First Myrinet board 1 = /dev/mlanai1 Second Myrinet board ... @@ -841,9 +846,9 @@ Your cooperation is appreciated. and "user level packet I/O." This board is also accessible as a standard networking "eth" device. - 38 block OBSOLETE (was Linux/AP+) + 38 block OBSOLETE (was Linux/AP+) - 39 char ML-16P experimental I/O board + 39 char ML-16P experimental I/O board 0 = /dev/ml16pa-a0 First card, first analog channel 1 = /dev/ml16pa-a1 First card, second analog channel ... @@ -861,20 +866,20 @@ Your cooperation is appreciated. 50 = /dev/ml16pb-c1 Second card, second counter/timer 51 = /dev/ml16pb-c2 Second card, third counter/timer ... - 39 block + 39 block - 40 char + 40 char - 40 block + 40 block - 41 char Yet Another Micro Monitor + 41 char Yet Another Micro Monitor 0 = /dev/yamm Yet Another Micro Monitor - 41 block + 41 block - 42 char Demo/sample use + 42 char Demo/sample use - 42 block Demo/sample use + 42 block Demo/sample use This number is intended for use in sample code, as well as a general "example" device number. It @@ -887,12 +892,12 @@ Your cooperation is appreciated. IN PARTICULAR, ANY DISTRIBUTION WHICH CONTAINS A DEVICE DRIVER USING MAJOR NUMBER 42 IS NONCOMPLIANT. - 43 char isdn4linux virtual modem + 43 char isdn4linux virtual modem 0 = /dev/ttyI0 First virtual modem ... 63 = /dev/ttyI63 64th virtual modem - 43 block Network block devices + 43 block Network block devices 0 = /dev/nb0 First network block device 1 = /dev/nb1 Second network block device ... @@ -904,12 +909,12 @@ Your cooperation is appreciated. to mounting filesystems over the net, swapping over the net, implementing block device in userland etc. - 44 char isdn4linux virtual modem - alternate devices + 44 char isdn4linux virtual modem - alternate devices 0 = /dev/cui0 Callout device for ttyI0 ... 63 = /dev/cui63 Callout device for ttyI63 - 44 block Flash Translation Layer (FTL) filesystems + 44 block Flash Translation Layer (FTL) filesystems 0 = /dev/ftla FTL on first Memory Technology Device 16 = /dev/ftlb FTL on second Memory Technology Device 32 = /dev/ftlc FTL on third Memory Technology Device @@ -920,7 +925,7 @@ Your cooperation is appreciated. disks (see major number 3) except that the partition limit is 15 rather than 63 per disk (same as SCSI.) - 45 char isdn4linux ISDN BRI driver + 45 char isdn4linux ISDN BRI driver 0 = /dev/isdn0 First virtual B channel raw data ... 63 = /dev/isdn63 64th virtual B channel raw data @@ -934,7 +939,7 @@ Your cooperation is appreciated. 255 = /dev/isdninfo ISDN monitor interface - 45 block Parallel port IDE disk devices + 45 block Parallel port IDE disk devices 0 = /dev/pda First parallel port IDE disk 16 = /dev/pdb Second parallel port IDE disk 32 = /dev/pdc Third parallel port IDE disk @@ -944,21 +949,21 @@ Your cooperation is appreciated. disks (see major number 3) except that the partition limit is 15 rather than 63 per disk. - 46 char Comtrol Rocketport serial card + 46 char Comtrol Rocketport serial card 0 = /dev/ttyR0 First Rocketport port 1 = /dev/ttyR1 Second Rocketport port ... - 46 block Parallel port ATAPI CD-ROM devices + 46 block Parallel port ATAPI CD-ROM devices 0 = /dev/pcd0 First parallel port ATAPI CD-ROM 1 = /dev/pcd1 Second parallel port ATAPI CD-ROM 2 = /dev/pcd2 Third parallel port ATAPI CD-ROM 3 = /dev/pcd3 Fourth parallel port ATAPI CD-ROM - 47 char Comtrol Rocketport serial card - alternate devices + 47 char Comtrol Rocketport serial card - alternate devices 0 = /dev/cur0 Callout device for ttyR0 1 = /dev/cur1 Callout device for ttyR1 ... - 47 block Parallel port ATAPI disk devices + 47 block Parallel port ATAPI disk devices 0 = /dev/pf0 First parallel port ATAPI disk 1 = /dev/pf1 Second parallel port ATAPI disk 2 = /dev/pf2 Third parallel port ATAPI disk @@ -967,11 +972,11 @@ Your cooperation is appreciated. This driver is intended for floppy disks and similar devices and hence does not support partitioning. - 48 char SDL RISCom serial card + 48 char SDL RISCom serial card 0 = /dev/ttyL0 First RISCom port 1 = /dev/ttyL1 Second RISCom port ... - 48 block Mylex DAC960 PCI RAID controller; first controller + 48 block Mylex DAC960 PCI RAID controller; first controller 0 = /dev/rd/c0d0 First disk, whole disk 8 = /dev/rd/c0d1 Second disk, whole disk ... @@ -983,11 +988,11 @@ Your cooperation is appreciated. ... 7 = /dev/rd/c?d?p7 Seventh partition - 49 char SDL RISCom serial card - alternate devices + 49 char SDL RISCom serial card - alternate devices 0 = /dev/cul0 Callout device for ttyL0 1 = /dev/cul1 Callout device for ttyL1 ... - 49 block Mylex DAC960 PCI RAID controller; second controller + 49 block Mylex DAC960 PCI RAID controller; second controller 0 = /dev/rd/c1d0 First disk, whole disk 8 = /dev/rd/c1d1 Second disk, whole disk ... @@ -995,19 +1000,19 @@ Your cooperation is appreciated. Partitions are handled as for major 48. - 50 char Reserved for GLINT + 50 char Reserved for GLINT - 50 block Mylex DAC960 PCI RAID controller; third controller + 50 block Mylex DAC960 PCI RAID controller; third controller 0 = /dev/rd/c2d0 First disk, whole disk 8 = /dev/rd/c2d1 Second disk, whole disk ... 248 = /dev/rd/c2d31 32nd disk, whole disk - 51 char Baycom radio modem OR Radio Tech BIM-XXX-RS232 radio modem + 51 char Baycom radio modem OR Radio Tech BIM-XXX-RS232 radio modem 0 = /dev/bc0 First Baycom radio modem 1 = /dev/bc1 Second Baycom radio modem ... - 51 block Mylex DAC960 PCI RAID controller; fourth controller + 51 block Mylex DAC960 PCI RAID controller; fourth controller 0 = /dev/rd/c3d0 First disk, whole disk 8 = /dev/rd/c3d1 Second disk, whole disk ... @@ -1015,13 +1020,13 @@ Your cooperation is appreciated. Partitions are handled as for major 48. - 52 char Spellcaster DataComm/BRI ISDN card + 52 char Spellcaster DataComm/BRI ISDN card 0 = /dev/dcbri0 First DataComm card 1 = /dev/dcbri1 Second DataComm card 2 = /dev/dcbri2 Third DataComm card 3 = /dev/dcbri3 Fourth DataComm card - 52 block Mylex DAC960 PCI RAID controller; fifth controller + 52 block Mylex DAC960 PCI RAID controller; fifth controller 0 = /dev/rd/c4d0 First disk, whole disk 8 = /dev/rd/c4d1 Second disk, whole disk ... @@ -1029,7 +1034,7 @@ Your cooperation is appreciated. Partitions are handled as for major 48. - 53 char BDM interface for remote debugging MC683xx microcontrollers + 53 char BDM interface for remote debugging MC683xx microcontrollers 0 = /dev/pd_bdm0 PD BDM interface on lp0 1 = /dev/pd_bdm1 PD BDM interface on lp1 2 = /dev/pd_bdm2 PD BDM interface on lp2 @@ -1043,7 +1048,7 @@ Your cooperation is appreciated. Domain Interface and ICD is the commercial interface by P&E. - 53 block Mylex DAC960 PCI RAID controller; sixth controller + 53 block Mylex DAC960 PCI RAID controller; sixth controller 0 = /dev/rd/c5d0 First disk, whole disk 8 = /dev/rd/c5d1 Second disk, whole disk ... @@ -1051,7 +1056,7 @@ Your cooperation is appreciated. Partitions are handled as for major 48. - 54 char Electrocardiognosis Holter serial card + 54 char Electrocardiognosis Holter serial card 0 = /dev/holter0 First Holter port 1 = /dev/holter1 Second Holter port 2 = /dev/holter2 Third Holter port @@ -1060,7 +1065,7 @@ Your cooperation is appreciated. to transfer data from Holter 24-hour heart monitoring equipment. - 54 block Mylex DAC960 PCI RAID controller; seventh controller + 54 block Mylex DAC960 PCI RAID controller; seventh controller 0 = /dev/rd/c6d0 First disk, whole disk 8 = /dev/rd/c6d1 Second disk, whole disk ... @@ -1068,10 +1073,10 @@ Your cooperation is appreciated. Partitions are handled as for major 48. - 55 char DSP56001 digital signal processor + 55 char DSP56001 digital signal processor 0 = /dev/dsp56k First DSP56001 - 55 block Mylex DAC960 PCI RAID controller; eighth controller + 55 block Mylex DAC960 PCI RAID controller; eighth controller 0 = /dev/rd/c7d0 First disk, whole disk 8 = /dev/rd/c7d1 Second disk, whole disk ... @@ -1079,42 +1084,42 @@ Your cooperation is appreciated. Partitions are handled as for major 48. - 56 char Apple Desktop Bus + 56 char Apple Desktop Bus 0 = /dev/adb ADB bus control Additional devices will be added to this number, all starting with /dev/adb. - 56 block Fifth IDE hard disk/CD-ROM interface + 56 block Fifth IDE hard disk/CD-ROM interface 0 = /dev/hdi Master: whole disk (or CD-ROM) 64 = /dev/hdj Slave: whole disk (or CD-ROM) Partitions are handled the same way as for the first interface (see major number 3). - 57 char Hayes ESP serial card + 57 char Hayes ESP serial card 0 = /dev/ttyP0 First ESP port 1 = /dev/ttyP1 Second ESP port ... - 57 block Sixth IDE hard disk/CD-ROM interface + 57 block Sixth IDE hard disk/CD-ROM interface 0 = /dev/hdk Master: whole disk (or CD-ROM) 64 = /dev/hdl Slave: whole disk (or CD-ROM) Partitions are handled the same way as for the first interface (see major number 3). - 58 char Hayes ESP serial card - alternate devices + 58 char Hayes ESP serial card - alternate devices 0 = /dev/cup0 Callout device for ttyP0 1 = /dev/cup1 Callout device for ttyP1 ... - 58 block Reserved for logical volume manager + 58 block Reserved for logical volume manager - 59 char sf firewall package + 59 char sf firewall package 0 = /dev/firewall Communication with sf kernel module - 59 block Generic PDA filesystem device + 59 block Generic PDA filesystem device 0 = /dev/pda0 First PDA device 1 = /dev/pda1 Second PDA device ... @@ -1127,17 +1132,17 @@ Your cooperation is appreciated. NAMING CONFLICT -- PROPOSED REVISED NAME /dev/rpda0 etc - 60-63 char LOCAL/EXPERIMENTAL USE + 60-63 char LOCAL/EXPERIMENTAL USE - 60-63 block LOCAL/EXPERIMENTAL USE + 60-63 block LOCAL/EXPERIMENTAL USE Allocated for local/experimental use. For devices not assigned official numbers, these ranges should be used in order to avoid conflicting with future assignments. - 64 char ENskip kernel encryption package + 64 char ENskip kernel encryption package 0 = /dev/enskip Communication with ENskip kernel module - 64 block Scramdisk/DriveCrypt encrypted devices + 64 block Scramdisk/DriveCrypt encrypted devices 0 = /dev/scramdisk/master Master node for ioctls 1 = /dev/scramdisk/1 First encrypted device 2 = /dev/scramdisk/2 Second encrypted device @@ -1152,7 +1157,7 @@ Your cooperation is appreciated. Requested by: andy@scramdisklinux.org - 65 char Sundance "plink" Transputer boards (obsolete, unused) + 65 char Sundance "plink" Transputer boards (obsolete, unused) 0 = /dev/plink0 First plink device 1 = /dev/plink1 Second plink device 2 = /dev/plink2 Third plink device @@ -1173,7 +1178,7 @@ Your cooperation is appreciated. This is a commercial driver; contact James Howes for information. - 65 block SCSI disk devices (16-31) + 65 block SCSI disk devices (16-31) 0 = /dev/sdq 17th SCSI disk whole disk 16 = /dev/sdr 18th SCSI disk whole disk 32 = /dev/sds 19th SCSI disk whole disk @@ -1184,12 +1189,12 @@ Your cooperation is appreciated. disks (see major number 3) except that the limit on partitions is 15. - 66 char YARC PowerPC PCI coprocessor card + 66 char YARC PowerPC PCI coprocessor card 0 = /dev/yppcpci0 First YARC card 1 = /dev/yppcpci1 Second YARC card ... - 66 block SCSI disk devices (32-47) + 66 block SCSI disk devices (32-47) 0 = /dev/sdag 33th SCSI disk whole disk 16 = /dev/sdah 34th SCSI disk whole disk 32 = /dev/sdai 35th SCSI disk whole disk @@ -1200,12 +1205,12 @@ Your cooperation is appreciated. disks (see major number 3) except that the limit on partitions is 15. - 67 char Coda network file system + 67 char Coda network file system 0 = /dev/cfs0 Coda cache manager See http://www.coda.cs.cmu.edu for information about Coda. - 67 block SCSI disk devices (48-63) + 67 block SCSI disk devices (48-63) 0 = /dev/sdaw 49th SCSI disk whole disk 16 = /dev/sdax 50th SCSI disk whole disk 32 = /dev/sday 51st SCSI disk whole disk @@ -1216,7 +1221,7 @@ Your cooperation is appreciated. disks (see major number 3) except that the limit on partitions is 15. - 68 char CAPI 2.0 interface + 68 char CAPI 2.0 interface 0 = /dev/capi20 Control device 1 = /dev/capi20.00 First CAPI 2.0 application 2 = /dev/capi20.01 Second CAPI 2.0 application @@ -1226,7 +1231,7 @@ Your cooperation is appreciated. ISDN CAPI 2.0 driver for use with CAPI 2.0 applications; currently supports the AVM B1 card. - 68 block SCSI disk devices (64-79) + 68 block SCSI disk devices (64-79) 0 = /dev/sdbm 65th SCSI disk whole disk 16 = /dev/sdbn 66th SCSI disk whole disk 32 = /dev/sdbo 67th SCSI disk whole disk @@ -1237,10 +1242,10 @@ Your cooperation is appreciated. disks (see major number 3) except that the limit on partitions is 15. - 69 char MA16 numeric accelerator card + 69 char MA16 numeric accelerator card 0 = /dev/ma16 Board memory access - 69 block SCSI disk devices (80-95) + 69 block SCSI disk devices (80-95) 0 = /dev/sdcc 81st SCSI disk whole disk 16 = /dev/sdcd 82nd SCSI disk whole disk 32 = /dev/sdce 83th SCSI disk whole disk @@ -1251,7 +1256,7 @@ Your cooperation is appreciated. disks (see major number 3) except that the limit on partitions is 15. - 70 char SpellCaster Protocol Services Interface + 70 char SpellCaster Protocol Services Interface 0 = /dev/apscfg Configuration interface 1 = /dev/apsauth Authentication interface 2 = /dev/apslog Logging interface @@ -1260,7 +1265,7 @@ Your cooperation is appreciated. 65 = /dev/apsasync Async command interface 128 = /dev/apsmon Monitor interface - 70 block SCSI disk devices (96-111) + 70 block SCSI disk devices (96-111) 0 = /dev/sdcs 97th SCSI disk whole disk 16 = /dev/sdct 98th SCSI disk whole disk 32 = /dev/sdcu 99th SCSI disk whole disk @@ -1271,7 +1276,7 @@ Your cooperation is appreciated. disks (see major number 3) except that the limit on partitions is 15. - 71 char Computone IntelliPort II serial card + 71 char Computone IntelliPort II serial card 0 = /dev/ttyF0 IntelliPort II board 0, port 0 1 = /dev/ttyF1 IntelliPort II board 0, port 1 ... @@ -1289,7 +1294,7 @@ Your cooperation is appreciated. ... 255 = /dev/ttyF255 IntelliPort II board 3, port 63 - 71 block SCSI disk devices (112-127) + 71 block SCSI disk devices (112-127) 0 = /dev/sddi 113th SCSI disk whole disk 16 = /dev/sddj 114th SCSI disk whole disk 32 = /dev/sddk 115th SCSI disk whole disk @@ -1300,7 +1305,7 @@ Your cooperation is appreciated. disks (see major number 3) except that the limit on partitions is 15. - 72 char Computone IntelliPort II serial card - alternate devices + 72 char Computone IntelliPort II serial card - alternate devices 0 = /dev/cuf0 Callout device for ttyF0 1 = /dev/cuf1 Callout device for ttyF1 ... @@ -1318,7 +1323,7 @@ Your cooperation is appreciated. ... 255 = /dev/cuf255 Callout device for ttyF255 - 72 block Compaq Intelligent Drive Array, first controller + 72 block Compaq Intelligent Drive Array, first controller 0 = /dev/ida/c0d0 First logical drive whole disk 16 = /dev/ida/c0d1 Second logical drive whole disk ... @@ -1328,7 +1333,7 @@ Your cooperation is appreciated. DAC960 (see major number 48) except that the limit on partitions is 15. - 73 char Computone IntelliPort II serial card - control devices + 73 char Computone IntelliPort II serial card - control devices 0 = /dev/ip2ipl0 Loadware device for board 0 1 = /dev/ip2stat0 Status device for board 0 4 = /dev/ip2ipl1 Loadware device for board 1 @@ -1338,7 +1343,7 @@ Your cooperation is appreciated. 12 = /dev/ip2ipl3 Loadware device for board 3 13 = /dev/ip2stat3 Status device for board 3 - 73 block Compaq Intelligent Drive Array, second controller + 73 block Compaq Intelligent Drive Array, second controller 0 = /dev/ida/c1d0 First logical drive whole disk 16 = /dev/ida/c1d1 Second logical drive whole disk ... @@ -1348,7 +1353,7 @@ Your cooperation is appreciated. DAC960 (see major number 48) except that the limit on partitions is 15. - 74 char SCI bridge + 74 char SCI bridge 0 = /dev/SCI/0 SCI device 0 1 = /dev/SCI/1 SCI device 1 ... @@ -1356,7 +1361,7 @@ Your cooperation is appreciated. Currently for Dolphin Interconnect Solutions' PCI-SCI bridge. - 74 block Compaq Intelligent Drive Array, third controller + 74 block Compaq Intelligent Drive Array, third controller 0 = /dev/ida/c2d0 First logical drive whole disk 16 = /dev/ida/c2d1 Second logical drive whole disk ... @@ -1366,14 +1371,14 @@ Your cooperation is appreciated. DAC960 (see major number 48) except that the limit on partitions is 15. - 75 char Specialix IO8+ serial card + 75 char Specialix IO8+ serial card 0 = /dev/ttyW0 First IO8+ port, first card 1 = /dev/ttyW1 Second IO8+ port, first card ... 8 = /dev/ttyW8 First IO8+ port, second card ... - 75 block Compaq Intelligent Drive Array, fourth controller + 75 block Compaq Intelligent Drive Array, fourth controller 0 = /dev/ida/c3d0 First logical drive whole disk 16 = /dev/ida/c3d1 Second logical drive whole disk ... @@ -1383,14 +1388,14 @@ Your cooperation is appreciated. DAC960 (see major number 48) except that the limit on partitions is 15. - 76 char Specialix IO8+ serial card - alternate devices + 76 char Specialix IO8+ serial card - alternate devices 0 = /dev/cuw0 Callout device for ttyW0 1 = /dev/cuw1 Callout device for ttyW1 ... 8 = /dev/cuw8 Callout device for ttyW8 ... - 76 block Compaq Intelligent Drive Array, fifth controller + 76 block Compaq Intelligent Drive Array, fifth controller 0 = /dev/ida/c4d0 First logical drive whole disk 16 = /dev/ida/c4d1 Second logical drive whole disk ... @@ -1401,10 +1406,10 @@ Your cooperation is appreciated. partitions is 15. - 77 char ComScire Quantum Noise Generator + 77 char ComScire Quantum Noise Generator 0 = /dev/qng ComScire Quantum Noise Generator - 77 block Compaq Intelligent Drive Array, sixth controller + 77 block Compaq Intelligent Drive Array, sixth controller 0 = /dev/ida/c5d0 First logical drive whole disk 16 = /dev/ida/c5d1 Second logical drive whole disk ... @@ -1414,12 +1419,12 @@ Your cooperation is appreciated. DAC960 (see major number 48) except that the limit on partitions is 15. - 78 char PAM Software's multimodem boards + 78 char PAM Software's multimodem boards 0 = /dev/ttyM0 First PAM modem 1 = /dev/ttyM1 Second PAM modem ... - 78 block Compaq Intelligent Drive Array, seventh controller + 78 block Compaq Intelligent Drive Array, seventh controller 0 = /dev/ida/c6d0 First logical drive whole disk 16 = /dev/ida/c6d1 Second logical drive whole disk ... @@ -1429,12 +1434,12 @@ Your cooperation is appreciated. DAC960 (see major number 48) except that the limit on partitions is 15. - 79 char PAM Software's multimodem boards - alternate devices + 79 char PAM Software's multimodem boards - alternate devices 0 = /dev/cum0 Callout device for ttyM0 1 = /dev/cum1 Callout device for ttyM1 ... - 79 block Compaq Intelligent Drive Array, eighth controller + 79 block Compaq Intelligent Drive Array, eighth controller 0 = /dev/ida/c7d0 First logical drive whole disk 16 = /dev/ida/c7d1 Second logical drive whole disk ... @@ -1444,10 +1449,10 @@ Your cooperation is appreciated. DAC960 (see major number 48) except that the limit on partitions is 15. - 80 char Photometrics AT200 CCD camera + 80 char Photometrics AT200 CCD camera 0 = /dev/at200 Photometrics AT200 CCD camera - 80 block I2O hard disk + 80 block I2O hard disk 0 = /dev/i2o/hda First I2O hard disk, whole disk 16 = /dev/i2o/hdb Second I2O hard disk, whole disk ... @@ -1457,7 +1462,7 @@ Your cooperation is appreciated. disks (see major number 3) except that the limit on partitions is 15. - 81 char video4linux + 81 char video4linux 0 = /dev/video0 Video capture/overlay device ... 63 = /dev/video63 Video capture/overlay device @@ -1475,7 +1480,7 @@ Your cooperation is appreciated. CONFIG_VIDEO_FIXED_MINOR_RANGES (default n) configuration option is set. - 81 block I2O hard disk + 81 block I2O hard disk 0 = /dev/i2o/hdq 17th I2O hard disk, whole disk 16 = /dev/i2o/hdr 18th I2O hard disk, whole disk ... @@ -1485,7 +1490,7 @@ Your cooperation is appreciated. disks (see major number 3) except that the limit on partitions is 15. - 82 char WiNRADiO communications receiver card + 82 char WiNRADiO communications receiver card 0 = /dev/winradio0 First WiNRADiO card 1 = /dev/winradio1 Second WiNRADiO card ... @@ -1493,7 +1498,7 @@ Your cooperation is appreciated. The driver and documentation may be obtained from http://www.winradio.com/ - 82 block I2O hard disk + 82 block I2O hard disk 0 = /dev/i2o/hdag 33rd I2O hard disk, whole disk 16 = /dev/i2o/hdah 34th I2O hard disk, whole disk ... @@ -1503,14 +1508,14 @@ Your cooperation is appreciated. disks (see major number 3) except that the limit on partitions is 15. - 83 char Matrox mga_vid video driver - 0 = /dev/mga_vid0 1st video card + 83 char Matrox mga_vid video driver + 0 = /dev/mga_vid0 1st video card 1 = /dev/mga_vid1 2nd video card 2 = /dev/mga_vid2 3rd video card ... - 15 = /dev/mga_vid15 16th video card + 15 = /dev/mga_vid15 16th video card - 83 block I2O hard disk + 83 block I2O hard disk 0 = /dev/i2o/hdaw 49th I2O hard disk, whole disk 16 = /dev/i2o/hdax 50th I2O hard disk, whole disk ... @@ -1520,11 +1525,11 @@ Your cooperation is appreciated. disks (see major number 3) except that the limit on partitions is 15. - 84 char Ikon 1011[57] Versatec Greensheet Interface + 84 char Ikon 1011[57] Versatec Greensheet Interface 0 = /dev/ihcp0 First Greensheet port 1 = /dev/ihcp1 Second Greensheet port - 84 block I2O hard disk + 84 block I2O hard disk 0 = /dev/i2o/hdbm 65th I2O hard disk, whole disk 16 = /dev/i2o/hdbn 66th I2O hard disk, whole disk ... @@ -1534,13 +1539,13 @@ Your cooperation is appreciated. disks (see major number 3) except that the limit on partitions is 15. - 85 char Linux/SGI shared memory input queue + 85 char Linux/SGI shared memory input queue 0 = /dev/shmiq Master shared input queue 1 = /dev/qcntl0 First device pushed 2 = /dev/qcntl1 Second device pushed ... - 85 block I2O hard disk + 85 block I2O hard disk 0 = /dev/i2o/hdcc 81st I2O hard disk, whole disk 16 = /dev/i2o/hdcd 82nd I2O hard disk, whole disk ... @@ -1550,12 +1555,12 @@ Your cooperation is appreciated. disks (see major number 3) except that the limit on partitions is 15. - 86 char SCSI media changer + 86 char SCSI media changer 0 = /dev/sch0 First SCSI media changer 1 = /dev/sch1 Second SCSI media changer ... - 86 block I2O hard disk + 86 block I2O hard disk 0 = /dev/i2o/hdcs 97th I2O hard disk, whole disk 16 = /dev/i2o/hdct 98th I2O hard disk, whole disk ... @@ -1565,12 +1570,12 @@ Your cooperation is appreciated. disks (see major number 3) except that the limit on partitions is 15. - 87 char Sony Control-A1 stereo control bus + 87 char Sony Control-A1 stereo control bus 0 = /dev/controla0 First device on chain 1 = /dev/controla1 Second device on chain ... - 87 block I2O hard disk + 87 block I2O hard disk 0 = /dev/i2o/hddi 113rd I2O hard disk, whole disk 16 = /dev/i2o/hddj 114th I2O hard disk, whole disk ... @@ -1580,59 +1585,59 @@ Your cooperation is appreciated. disks (see major number 3) except that the limit on partitions is 15. - 88 char COMX synchronous serial card + 88 char COMX synchronous serial card 0 = /dev/comx0 COMX channel 0 1 = /dev/comx1 COMX channel 1 ... - 88 block Seventh IDE hard disk/CD-ROM interface + 88 block Seventh IDE hard disk/CD-ROM interface 0 = /dev/hdm Master: whole disk (or CD-ROM) 64 = /dev/hdn Slave: whole disk (or CD-ROM) Partitions are handled the same way as for the first interface (see major number 3). - 89 char I2C bus interface + 89 char I2C bus interface 0 = /dev/i2c-0 First I2C adapter 1 = /dev/i2c-1 Second I2C adapter ... - 89 block Eighth IDE hard disk/CD-ROM interface + 89 block Eighth IDE hard disk/CD-ROM interface 0 = /dev/hdo Master: whole disk (or CD-ROM) 64 = /dev/hdp Slave: whole disk (or CD-ROM) Partitions are handled the same way as for the first interface (see major number 3). - 90 char Memory Technology Device (RAM, ROM, Flash) + 90 char Memory Technology Device (RAM, ROM, Flash) 0 = /dev/mtd0 First MTD (rw) 1 = /dev/mtdr0 First MTD (ro) ... 30 = /dev/mtd15 16th MTD (rw) 31 = /dev/mtdr15 16th MTD (ro) - 90 block Ninth IDE hard disk/CD-ROM interface + 90 block Ninth IDE hard disk/CD-ROM interface 0 = /dev/hdq Master: whole disk (or CD-ROM) 64 = /dev/hdr Slave: whole disk (or CD-ROM) Partitions are handled the same way as for the first interface (see major number 3). - 91 char CAN-Bus devices + 91 char CAN-Bus devices 0 = /dev/can0 First CAN-Bus controller 1 = /dev/can1 Second CAN-Bus controller ... - 91 block Tenth IDE hard disk/CD-ROM interface + 91 block Tenth IDE hard disk/CD-ROM interface 0 = /dev/hds Master: whole disk (or CD-ROM) 64 = /dev/hdt Slave: whole disk (or CD-ROM) Partitions are handled the same way as for the first interface (see major number 3). - 92 char Reserved for ith Kommunikationstechnik MIC ISDN card + 92 char Reserved for ith Kommunikationstechnik MIC ISDN card - 92 block PPDD encrypted disk driver + 92 block PPDD encrypted disk driver 0 = /dev/ppdd0 First encrypted disk 1 = /dev/ppdd1 Second encrypted disk ... @@ -1641,35 +1646,35 @@ Your cooperation is appreciated. disks (see major number 3) except that the limit on partitions is 15. - 93 char + 93 char - 93 block NAND Flash Translation Layer filesystem + 93 block NAND Flash Translation Layer filesystem 0 = /dev/nftla First NFTL layer 16 = /dev/nftlb Second NFTL layer ... 240 = /dev/nftlp 16th NTFL layer - 94 char + 94 char - 94 block IBM S/390 DASD block storage - 0 = /dev/dasda First DASD device, major - 1 = /dev/dasda1 First DASD device, block 1 - 2 = /dev/dasda2 First DASD device, block 2 - 3 = /dev/dasda3 First DASD device, block 3 - 4 = /dev/dasdb Second DASD device, major - 5 = /dev/dasdb1 Second DASD device, block 1 - 6 = /dev/dasdb2 Second DASD device, block 2 - 7 = /dev/dasdb3 Second DASD device, block 3 + 94 block IBM S/390 DASD block storage + 0 = /dev/dasda First DASD device, major + 1 = /dev/dasda1 First DASD device, block 1 + 2 = /dev/dasda2 First DASD device, block 2 + 3 = /dev/dasda3 First DASD device, block 3 + 4 = /dev/dasdb Second DASD device, major + 5 = /dev/dasdb1 Second DASD device, block 1 + 6 = /dev/dasdb2 Second DASD device, block 2 + 7 = /dev/dasdb3 Second DASD device, block 3 ... - 95 char IP filter + 95 char IP filter 0 = /dev/ipl Filter control device/log file 1 = /dev/ipnat NAT control device/log file 2 = /dev/ipstate State information log file 3 = /dev/ipauth Authentication control device/log file ... - 96 char Parallel port ATAPI tape devices + 96 char Parallel port ATAPI tape devices 0 = /dev/pt0 First parallel port ATAPI tape 1 = /dev/pt1 Second parallel port ATAPI tape ... @@ -1677,13 +1682,13 @@ Your cooperation is appreciated. 129 = /dev/npt1 Second p.p. ATAPI tape, no rewind ... - 96 block Inverse NAND Flash Translation Layer + 96 block Inverse NAND Flash Translation Layer 0 = /dev/inftla First INFTL layer 16 = /dev/inftlb Second INFTL layer ... 240 = /dev/inftlp 16th INTFL layer - 97 char Parallel port generic ATAPI interface + 97 char Parallel port generic ATAPI interface 0 = /dev/pg0 First parallel port ATAPI device 1 = /dev/pg1 Second parallel port ATAPI device 2 = /dev/pg2 Third parallel port ATAPI device @@ -1692,14 +1697,14 @@ Your cooperation is appreciated. These devices support the same API as the generic SCSI devices. - 98 char Control and Measurement Device (comedi) + 98 char Control and Measurement Device (comedi) 0 = /dev/comedi0 First comedi device 1 = /dev/comedi1 Second comedi device ... See http://stm.lbl.gov/comedi. - 98 block User-mode virtual block device + 98 block User-mode virtual block device 0 = /dev/ubda First user-mode block device 16 = /dev/udbb Second user-mode block device ... @@ -1710,26 +1715,26 @@ Your cooperation is appreciated. This device is used by the user-mode virtual kernel port. - 99 char Raw parallel ports + 99 char Raw parallel ports 0 = /dev/parport0 First parallel port 1 = /dev/parport1 Second parallel port ... - 99 block JavaStation flash disk + 99 block JavaStation flash disk 0 = /dev/jsfd JavaStation flash disk -100 char Telephony for Linux + 100 char Telephony for Linux 0 = /dev/phone0 First telephony device 1 = /dev/phone1 Second telephony device ... -101 char Motorola DSP 56xxx board + 101 char Motorola DSP 56xxx board 0 = /dev/mdspstat Status information 1 = /dev/mdsp1 First DSP board I/O controls ... 16 = /dev/mdsp16 16th DSP board I/O controls -101 block AMI HyperDisk RAID controller + 101 block AMI HyperDisk RAID controller 0 = /dev/amiraid/ar0 First array whole disk 16 = /dev/amiraid/ar1 Second array whole disk ... @@ -1742,9 +1747,9 @@ Your cooperation is appreciated. ... 15 = /dev/amiraid/ar?p15 15th partition -102 char + 102 char -102 block Compressed block device + 102 block Compressed block device 0 = /dev/cbd/a First compressed block device, whole device 16 = /dev/cbd/b Second compressed block device, whole device ... @@ -1754,7 +1759,7 @@ Your cooperation is appreciated. disks (see major number 3) except that the limit on partitions is 15. -103 char Arla network file system + 103 char Arla network file system 0 = /dev/nnpfs0 First NNPFS device 1 = /dev/nnpfs1 Second NNPFS device @@ -1765,12 +1770,12 @@ Your cooperation is appreciated. write to or see http://www.stacken.kth.se/project/arla/ -103 block Audit device + 103 block Audit device 0 = /dev/audit Audit device -104 char Flash BIOS support + 104 char Flash BIOS support -104 block Compaq Next Generation Drive Array, first controller + 104 block Compaq Next Generation Drive Array, first controller 0 = /dev/cciss/c0d0 First logical drive, whole disk 16 = /dev/cciss/c0d1 Second logical drive, whole disk ... @@ -1780,12 +1785,12 @@ Your cooperation is appreciated. DAC960 (see major number 48) except that the limit on partitions is 15. -105 char Comtrol VS-1000 serial controller + 105 char Comtrol VS-1000 serial controller 0 = /dev/ttyV0 First VS-1000 port 1 = /dev/ttyV1 Second VS-1000 port ... -105 block Compaq Next Generation Drive Array, second controller + 105 block Compaq Next Generation Drive Array, second controller 0 = /dev/cciss/c1d0 First logical drive, whole disk 16 = /dev/cciss/c1d1 Second logical drive, whole disk ... @@ -1795,12 +1800,12 @@ Your cooperation is appreciated. DAC960 (see major number 48) except that the limit on partitions is 15. -106 char Comtrol VS-1000 serial controller - alternate devices + 106 char Comtrol VS-1000 serial controller - alternate devices 0 = /dev/cuv0 First VS-1000 port 1 = /dev/cuv1 Second VS-1000 port ... -106 block Compaq Next Generation Drive Array, third controller + 106 block Compaq Next Generation Drive Array, third controller 0 = /dev/cciss/c2d0 First logical drive, whole disk 16 = /dev/cciss/c2d1 Second logical drive, whole disk ... @@ -1810,10 +1815,10 @@ Your cooperation is appreciated. DAC960 (see major number 48) except that the limit on partitions is 15. -107 char 3Dfx Voodoo Graphics device + 107 char 3Dfx Voodoo Graphics device 0 = /dev/3dfx Primary 3Dfx graphics device -107 block Compaq Next Generation Drive Array, fourth controller + 107 block Compaq Next Generation Drive Array, fourth controller 0 = /dev/cciss/c3d0 First logical drive, whole disk 16 = /dev/cciss/c3d1 Second logical drive, whole disk ... @@ -1823,10 +1828,10 @@ Your cooperation is appreciated. DAC960 (see major number 48) except that the limit on partitions is 15. -108 char Device independent PPP interface + 108 char Device independent PPP interface 0 = /dev/ppp Device independent PPP interface -108 block Compaq Next Generation Drive Array, fifth controller + 108 block Compaq Next Generation Drive Array, fifth controller 0 = /dev/cciss/c4d0 First logical drive, whole disk 16 = /dev/cciss/c4d1 Second logical drive, whole disk ... @@ -1836,9 +1841,9 @@ Your cooperation is appreciated. DAC960 (see major number 48) except that the limit on partitions is 15. -109 char Reserved for logical volume manager + 109 char Reserved for logical volume manager -109 block Compaq Next Generation Drive Array, sixth controller + 109 block Compaq Next Generation Drive Array, sixth controller 0 = /dev/cciss/c5d0 First logical drive, whole disk 16 = /dev/cciss/c5d1 Second logical drive, whole disk ... @@ -1848,12 +1853,12 @@ Your cooperation is appreciated. DAC960 (see major number 48) except that the limit on partitions is 15. -110 char miroMEDIA Surround board + 110 char miroMEDIA Surround board 0 = /dev/srnd0 First miroMEDIA Surround board 1 = /dev/srnd1 Second miroMEDIA Surround board ... -110 block Compaq Next Generation Drive Array, seventh controller + 110 block Compaq Next Generation Drive Array, seventh controller 0 = /dev/cciss/c6d0 First logical drive, whole disk 16 = /dev/cciss/c6d1 Second logical drive, whole disk ... @@ -1863,9 +1868,9 @@ Your cooperation is appreciated. DAC960 (see major number 48) except that the limit on partitions is 15. -111 char + 111 char -111 block Compaq Next Generation Drive Array, eighth controller + 111 block Compaq Next Generation Drive Array, eighth controller 0 = /dev/cciss/c7d0 First logical drive, whole disk 16 = /dev/cciss/c7d1 Second logical drive, whole disk ... @@ -1875,7 +1880,7 @@ Your cooperation is appreciated. DAC960 (see major number 48) except that the limit on partitions is 15. -112 char ISI serial card + 112 char ISI serial card 0 = /dev/ttyM0 First ISI port 1 = /dev/ttyM1 Second ISI port ... @@ -1883,7 +1888,7 @@ Your cooperation is appreciated. There is currently a device-naming conflict between these and PAM multimodems (major 78). -112 block IBM iSeries virtual disk + 112 block IBM iSeries virtual disk 0 = /dev/iseries/vda First virtual disk, whole disk 8 = /dev/iseries/vdb Second virtual disk, whole disk ... @@ -1896,17 +1901,17 @@ Your cooperation is appreciated. disks (see major number 3) except that the limit on partitions is 7. -113 char ISI serial card - alternate devices + 113 char ISI serial card - alternate devices 0 = /dev/cum0 Callout device for ttyM0 1 = /dev/cum1 Callout device for ttyM1 ... -113 block IBM iSeries virtual CD-ROM + 113 block IBM iSeries virtual CD-ROM 0 = /dev/iseries/vcda First virtual CD-ROM 1 = /dev/iseries/vcdb Second virtual CD-ROM ... -114 char Picture Elements ISE board + 114 char Picture Elements ISE board 0 = /dev/ise0 First ISE board 1 = /dev/ise1 Second ISE board ... @@ -1919,24 +1924,24 @@ Your cooperation is appreciated. I/O access to the board, the /dev/isex0 nodes command nodes used to control the board. -114 block IDE BIOS powered software RAID interfaces such as the - Promise Fastrak + 114 block IDE BIOS powered software RAID interfaces such as the + Promise Fastrak - 0 = /dev/ataraid/d0 - 1 = /dev/ataraid/d0p1 - 2 = /dev/ataraid/d0p2 - ... - 16 = /dev/ataraid/d1 - 17 = /dev/ataraid/d1p1 - 18 = /dev/ataraid/d1p2 - ... - 255 = /dev/ataraid/d15p15 + 0 = /dev/ataraid/d0 + 1 = /dev/ataraid/d0p1 + 2 = /dev/ataraid/d0p2 + ... + 16 = /dev/ataraid/d1 + 17 = /dev/ataraid/d1p1 + 18 = /dev/ataraid/d1p2 + ... + 255 = /dev/ataraid/d15p15 Partitions are handled in the same way as for IDE disks (see major number 3) except that the limit on partitions is 15. -115 char TI link cable devices (115 was formerly the console driver speaker) + 115 char TI link cable devices (115 was formerly the console driver speaker) 0 = /dev/tipar0 Parallel cable on first parallel port ... 7 = /dev/tipar7 Parallel cable on seventh parallel port @@ -1949,28 +1954,28 @@ Your cooperation is appreciated. ... 47 = /dev/tiusb31 32nd USB cable -115 block NetWare (NWFS) Devices (0-255) + 115 block NetWare (NWFS) Devices (0-255) - The NWFS (NetWare) devices are used to present a - collection of NetWare Mirror Groups or NetWare - Partitions as a logical storage segment for - use in mounting NetWare volumes. A maximum of - 256 NetWare volumes can be supported in a single - machine. + The NWFS (NetWare) devices are used to present a + collection of NetWare Mirror Groups or NetWare + Partitions as a logical storage segment for + use in mounting NetWare volumes. A maximum of + 256 NetWare volumes can be supported in a single + machine. - http://cgfa.telepac.pt/ftp2/kernel.org/linux/kernel/people/jmerkey/nwfs/ + http://cgfa.telepac.pt/ftp2/kernel.org/linux/kernel/people/jmerkey/nwfs/ - 0 = /dev/nwfs/v0 First NetWare (NWFS) Logical Volume - 1 = /dev/nwfs/v1 Second NetWare (NWFS) Logical Volume - 2 = /dev/nwfs/v2 Third NetWare (NWFS) Logical Volume - ... - 255 = /dev/nwfs/v255 Last NetWare (NWFS) Logical Volume + 0 = /dev/nwfs/v0 First NetWare (NWFS) Logical Volume + 1 = /dev/nwfs/v1 Second NetWare (NWFS) Logical Volume + 2 = /dev/nwfs/v2 Third NetWare (NWFS) Logical Volume + ... + 255 = /dev/nwfs/v255 Last NetWare (NWFS) Logical Volume -116 char Advanced Linux Sound Driver (ALSA) + 116 char Advanced Linux Sound Driver (ALSA) -116 block MicroMemory battery backed RAM adapter (NVRAM) - Supports 16 boards, 15 partitions each. - Requested by neilb at cse.unsw.edu.au. + 116 block MicroMemory battery backed RAM adapter (NVRAM) + Supports 16 boards, 15 partitions each. + Requested by neilb at cse.unsw.edu.au. 0 = /dev/umem/d0 Whole of first board 1 = /dev/umem/d0p1 First partition of first board @@ -1982,7 +1987,7 @@ Your cooperation is appreciated. ... 255= /dev/umem/d15p15 15th partition of 16th board. -117 char COSA/SRP synchronous serial card + 117 char COSA/SRP synchronous serial card 0 = /dev/cosa0c0 1st board, 1st channel 1 = /dev/cosa0c1 1st board, 2nd channel ... @@ -1990,147 +1995,147 @@ Your cooperation is appreciated. 17 = /dev/cosa1c1 2nd board, 2nd channel ... -117 block Enterprise Volume Management System (EVMS) + 117 block Enterprise Volume Management System (EVMS) - The EVMS driver uses a layered, plug-in model to provide - unparalleled flexibility and extensibility in managing - storage. This allows for easy expansion or customization - of various levels of volume management. Requested by - Mark Peloquin (peloquin at us.ibm.com). + The EVMS driver uses a layered, plug-in model to provide + unparalleled flexibility and extensibility in managing + storage. This allows for easy expansion or customization + of various levels of volume management. Requested by + Mark Peloquin (peloquin at us.ibm.com). - Note: EVMS populates and manages all the devnodes in - /dev/evms. + Note: EVMS populates and manages all the devnodes in + /dev/evms. - http://sf.net/projects/evms + http://sf.net/projects/evms - 0 = /dev/evms/block_device EVMS block device - 1 = /dev/evms/legacyname1 First EVMS legacy device - 2 = /dev/evms/legacyname2 Second EVMS legacy device - ... - Both ranges can grow (down or up) until they meet. - ... - 254 = /dev/evms/EVMSname2 Second EVMS native device - 255 = /dev/evms/EVMSname1 First EVMS native device + 0 = /dev/evms/block_device EVMS block device + 1 = /dev/evms/legacyname1 First EVMS legacy device + 2 = /dev/evms/legacyname2 Second EVMS legacy device + ... + Both ranges can grow (down or up) until they meet. + ... + 254 = /dev/evms/EVMSname2 Second EVMS native device + 255 = /dev/evms/EVMSname1 First EVMS native device - Note: legacyname(s) are derived from the normal legacy - device names. For example, /dev/hda5 would become - /dev/evms/hda5. + Note: legacyname(s) are derived from the normal legacy + device names. For example, /dev/hda5 would become + /dev/evms/hda5. -118 char IBM Cryptographic Accelerator + 118 char IBM Cryptographic Accelerator 0 = /dev/ica Virtual interface to all IBM Crypto Accelerators 1 = /dev/ica0 IBMCA Device 0 2 = /dev/ica1 IBMCA Device 1 ... -119 char VMware virtual network control + 119 char VMware virtual network control 0 = /dev/vnet0 1st virtual network 1 = /dev/vnet1 2nd virtual network ... -120-127 char LOCAL/EXPERIMENTAL USE + 120-127 char LOCAL/EXPERIMENTAL USE -120-127 block LOCAL/EXPERIMENTAL USE + 120-127 block LOCAL/EXPERIMENTAL USE Allocated for local/experimental use. For devices not assigned official numbers, these ranges should be used in order to avoid conflicting with future assignments. -128-135 char Unix98 PTY masters + 128-135 char Unix98 PTY masters These devices should not have corresponding device nodes; instead they should be accessed through the /dev/ptmx cloning interface. -128 block SCSI disk devices (128-143) - 0 = /dev/sddy 129th SCSI disk whole disk - 16 = /dev/sddz 130th SCSI disk whole disk - 32 = /dev/sdea 131th SCSI disk whole disk - ... - 240 = /dev/sden 144th SCSI disk whole disk + 128 block SCSI disk devices (128-143) + 0 = /dev/sddy 129th SCSI disk whole disk + 16 = /dev/sddz 130th SCSI disk whole disk + 32 = /dev/sdea 131th SCSI disk whole disk + ... + 240 = /dev/sden 144th SCSI disk whole disk Partitions are handled in the same way as for IDE disks (see major number 3) except that the limit on partitions is 15. -129 block SCSI disk devices (144-159) - 0 = /dev/sdeo 145th SCSI disk whole disk - 16 = /dev/sdep 146th SCSI disk whole disk - 32 = /dev/sdeq 147th SCSI disk whole disk - ... - 240 = /dev/sdfd 160th SCSI disk whole disk + 129 block SCSI disk devices (144-159) + 0 = /dev/sdeo 145th SCSI disk whole disk + 16 = /dev/sdep 146th SCSI disk whole disk + 32 = /dev/sdeq 147th SCSI disk whole disk + ... + 240 = /dev/sdfd 160th SCSI disk whole disk Partitions are handled in the same way as for IDE disks (see major number 3) except that the limit on partitions is 15. -130 char (Misc devices) + 130 char (Misc devices) -130 block SCSI disk devices (160-175) - 0 = /dev/sdfe 161st SCSI disk whole disk - 16 = /dev/sdff 162nd SCSI disk whole disk - 32 = /dev/sdfg 163rd SCSI disk whole disk - ... - 240 = /dev/sdft 176th SCSI disk whole disk + 130 block SCSI disk devices (160-175) + 0 = /dev/sdfe 161st SCSI disk whole disk + 16 = /dev/sdff 162nd SCSI disk whole disk + 32 = /dev/sdfg 163rd SCSI disk whole disk + ... + 240 = /dev/sdft 176th SCSI disk whole disk Partitions are handled in the same way as for IDE disks (see major number 3) except that the limit on partitions is 15. -131 block SCSI disk devices (176-191) - 0 = /dev/sdfu 177th SCSI disk whole disk - 16 = /dev/sdfv 178th SCSI disk whole disk - 32 = /dev/sdfw 179th SCSI disk whole disk - ... - 240 = /dev/sdgj 192nd SCSI disk whole disk + 131 block SCSI disk devices (176-191) + 0 = /dev/sdfu 177th SCSI disk whole disk + 16 = /dev/sdfv 178th SCSI disk whole disk + 32 = /dev/sdfw 179th SCSI disk whole disk + ... + 240 = /dev/sdgj 192nd SCSI disk whole disk Partitions are handled in the same way as for IDE disks (see major number 3) except that the limit on partitions is 15. -132 block SCSI disk devices (192-207) - 0 = /dev/sdgk 193rd SCSI disk whole disk - 16 = /dev/sdgl 194th SCSI disk whole disk - 32 = /dev/sdgm 195th SCSI disk whole disk - ... - 240 = /dev/sdgz 208th SCSI disk whole disk + 132 block SCSI disk devices (192-207) + 0 = /dev/sdgk 193rd SCSI disk whole disk + 16 = /dev/sdgl 194th SCSI disk whole disk + 32 = /dev/sdgm 195th SCSI disk whole disk + ... + 240 = /dev/sdgz 208th SCSI disk whole disk Partitions are handled in the same way as for IDE disks (see major number 3) except that the limit on partitions is 15. -133 block SCSI disk devices (208-223) - 0 = /dev/sdha 209th SCSI disk whole disk - 16 = /dev/sdhb 210th SCSI disk whole disk - 32 = /dev/sdhc 211th SCSI disk whole disk - ... - 240 = /dev/sdhp 224th SCSI disk whole disk + 133 block SCSI disk devices (208-223) + 0 = /dev/sdha 209th SCSI disk whole disk + 16 = /dev/sdhb 210th SCSI disk whole disk + 32 = /dev/sdhc 211th SCSI disk whole disk + ... + 240 = /dev/sdhp 224th SCSI disk whole disk Partitions are handled in the same way as for IDE disks (see major number 3) except that the limit on partitions is 15. -134 block SCSI disk devices (224-239) - 0 = /dev/sdhq 225th SCSI disk whole disk - 16 = /dev/sdhr 226th SCSI disk whole disk - 32 = /dev/sdhs 227th SCSI disk whole disk - ... - 240 = /dev/sdif 240th SCSI disk whole disk + 134 block SCSI disk devices (224-239) + 0 = /dev/sdhq 225th SCSI disk whole disk + 16 = /dev/sdhr 226th SCSI disk whole disk + 32 = /dev/sdhs 227th SCSI disk whole disk + ... + 240 = /dev/sdif 240th SCSI disk whole disk Partitions are handled in the same way as for IDE disks (see major number 3) except that the limit on partitions is 15. -135 block SCSI disk devices (240-255) - 0 = /dev/sdig 241st SCSI disk whole disk - 16 = /dev/sdih 242nd SCSI disk whole disk - 32 = /dev/sdih 243rd SCSI disk whole disk - ... - 240 = /dev/sdiv 256th SCSI disk whole disk + 135 block SCSI disk devices (240-255) + 0 = /dev/sdig 241st SCSI disk whole disk + 16 = /dev/sdih 242nd SCSI disk whole disk + 32 = /dev/sdih 243rd SCSI disk whole disk + ... + 240 = /dev/sdiv 256th SCSI disk whole disk Partitions are handled in the same way as for IDE disks (see major number 3) except that the limit on partitions is 15. -136-143 char Unix98 PTY slaves + 136-143 char Unix98 PTY slaves 0 = /dev/pts/0 First Unix98 pseudo-TTY 1 = /dev/pts/1 Second Unix98 pseudo-TTY ... @@ -2142,7 +2147,7 @@ Your cooperation is appreciated. *most* distributions the appropriate options are "mode=0620,gid=".) -136 block Mylex DAC960 PCI RAID controller; ninth controller + 136 block Mylex DAC960 PCI RAID controller; ninth controller 0 = /dev/rd/c8d0 First disk, whole disk 8 = /dev/rd/c8d1 Second disk, whole disk ... @@ -2150,7 +2155,7 @@ Your cooperation is appreciated. Partitions are handled as for major 48. -137 block Mylex DAC960 PCI RAID controller; tenth controller + 137 block Mylex DAC960 PCI RAID controller; tenth controller 0 = /dev/rd/c9d0 First disk, whole disk 8 = /dev/rd/c9d1 Second disk, whole disk ... @@ -2158,7 +2163,7 @@ Your cooperation is appreciated. Partitions are handled as for major 48. -138 block Mylex DAC960 PCI RAID controller; eleventh controller + 138 block Mylex DAC960 PCI RAID controller; eleventh controller 0 = /dev/rd/c10d0 First disk, whole disk 8 = /dev/rd/c10d1 Second disk, whole disk ... @@ -2166,7 +2171,7 @@ Your cooperation is appreciated. Partitions are handled as for major 48. -139 block Mylex DAC960 PCI RAID controller; twelfth controller + 139 block Mylex DAC960 PCI RAID controller; twelfth controller 0 = /dev/rd/c11d0 First disk, whole disk 8 = /dev/rd/c11d1 Second disk, whole disk ... @@ -2174,7 +2179,7 @@ Your cooperation is appreciated. Partitions are handled as for major 48. -140 block Mylex DAC960 PCI RAID controller; thirteenth controller + 140 block Mylex DAC960 PCI RAID controller; thirteenth controller 0 = /dev/rd/c12d0 First disk, whole disk 8 = /dev/rd/c12d1 Second disk, whole disk ... @@ -2182,7 +2187,7 @@ Your cooperation is appreciated. Partitions are handled as for major 48. -141 block Mylex DAC960 PCI RAID controller; fourteenth controller + 141 block Mylex DAC960 PCI RAID controller; fourteenth controller 0 = /dev/rd/c13d0 First disk, whole disk 8 = /dev/rd/c13d1 Second disk, whole disk ... @@ -2190,7 +2195,7 @@ Your cooperation is appreciated. Partitions are handled as for major 48. -142 block Mylex DAC960 PCI RAID controller; fifteenth controller + 142 block Mylex DAC960 PCI RAID controller; fifteenth controller 0 = /dev/rd/c14d0 First disk, whole disk 8 = /dev/rd/c14d1 Second disk, whole disk ... @@ -2198,7 +2203,7 @@ Your cooperation is appreciated. Partitions are handled as for major 48. -143 block Mylex DAC960 PCI RAID controller; sixteenth controller + 143 block Mylex DAC960 PCI RAID controller; sixteenth controller 0 = /dev/rd/c15d0 First disk, whole disk 8 = /dev/rd/c15d1 Second disk, whole disk ... @@ -2206,7 +2211,7 @@ Your cooperation is appreciated. Partitions are handled as for major 48. -144 char Encapsulated PPP + 144 char Encapsulated PPP 0 = /dev/pppox0 First PPP over Ethernet ... 63 = /dev/pppox63 64th PPP over Ethernet @@ -2216,11 +2221,11 @@ Your cooperation is appreciated. The SST 5136-DN DeviceNet interface driver has been relocated to major 183 due to an unfortunate conflict. -144 block Expansion Area #1 for more non-device (e.g. NFS) mounts + 144 block Expansion Area #1 for more non-device (e.g. NFS) mounts 0 = mounted device 256 255 = mounted device 511 -145 char SAM9407-based soundcard + 145 char SAM9407-based soundcard 0 = /dev/sam0_mixer 1 = /dev/sam0_sequencer 2 = /dev/sam0_midi00 @@ -2241,66 +2246,66 @@ Your cooperation is appreciated. addons, which are sam9407 specific. OSS can be operated simultaneously, taking care of the codec. -145 block Expansion Area #2 for more non-device (e.g. NFS) mounts + 145 block Expansion Area #2 for more non-device (e.g. NFS) mounts 0 = mounted device 512 255 = mounted device 767 -146 char SYSTRAM SCRAMNet mirrored-memory network + 146 char SYSTRAM SCRAMNet mirrored-memory network 0 = /dev/scramnet0 First SCRAMNet device 1 = /dev/scramnet1 Second SCRAMNet device ... -146 block Expansion Area #3 for more non-device (e.g. NFS) mounts + 146 block Expansion Area #3 for more non-device (e.g. NFS) mounts 0 = mounted device 768 255 = mounted device 1023 -147 char Aureal Semiconductor Vortex Audio device + 147 char Aureal Semiconductor Vortex Audio device 0 = /dev/aureal0 First Aureal Vortex 1 = /dev/aureal1 Second Aureal Vortex ... -147 block Distributed Replicated Block Device (DRBD) + 147 block Distributed Replicated Block Device (DRBD) 0 = /dev/drbd0 First DRBD device 1 = /dev/drbd1 Second DRBD device ... -148 char Technology Concepts serial card + 148 char Technology Concepts serial card 0 = /dev/ttyT0 First TCL port 1 = /dev/ttyT1 Second TCL port ... -149 char Technology Concepts serial card - alternate devices + 149 char Technology Concepts serial card - alternate devices 0 = /dev/cut0 Callout device for ttyT0 1 = /dev/cut0 Callout device for ttyT1 ... -150 char Real-Time Linux FIFOs + 150 char Real-Time Linux FIFOs 0 = /dev/rtf0 First RTLinux FIFO 1 = /dev/rtf1 Second RTLinux FIFO ... -151 char DPT I2O SmartRaid V controller + 151 char DPT I2O SmartRaid V controller 0 = /dev/dpti0 First DPT I2O adapter 1 = /dev/dpti1 Second DPT I2O adapter ... -152 char EtherDrive Control Device + 152 char EtherDrive Control Device 0 = /dev/etherd/ctl Connect/Disconnect an EtherDrive 1 = /dev/etherd/err Monitor errors 2 = /dev/etherd/raw Raw AoE packet monitor -152 block EtherDrive Block Devices + 152 block EtherDrive Block Devices 0 = /dev/etherd/0 EtherDrive 0 ... 255 = /dev/etherd/255 EtherDrive 255 -153 char SPI Bus Interface (sometimes referred to as MicroWire) + 153 char SPI Bus Interface (sometimes referred to as MicroWire) 0 = /dev/spi0 First SPI device on the bus 1 = /dev/spi1 Second SPI device on the bus ... 15 = /dev/spi15 Sixteenth SPI device on the bus -153 block Enhanced Metadisk RAID (EMD) storage units + 153 block Enhanced Metadisk RAID (EMD) storage units 0 = /dev/emd/0 First unit 1 = /dev/emd/0p1 Partition 1 on First unit 2 = /dev/emd/0p2 Partition 2 on First unit @@ -2316,41 +2321,41 @@ Your cooperation is appreciated. disks (see major number 3) except that the limit on partitions is 15. -154 char Specialix RIO serial card + 154 char Specialix RIO serial card 0 = /dev/ttySR0 First RIO port ... 255 = /dev/ttySR255 256th RIO port -155 char Specialix RIO serial card - alternate devices + 155 char Specialix RIO serial card - alternate devices 0 = /dev/cusr0 Callout device for ttySR0 ... 255 = /dev/cusr255 Callout device for ttySR255 -156 char Specialix RIO serial card + 156 char Specialix RIO serial card 0 = /dev/ttySR256 257th RIO port ... 255 = /dev/ttySR511 512th RIO port -157 char Specialix RIO serial card - alternate devices + 157 char Specialix RIO serial card - alternate devices 0 = /dev/cusr256 Callout device for ttySR256 ... 255 = /dev/cusr511 Callout device for ttySR511 -158 char Dialogic GammaLink fax driver + 158 char Dialogic GammaLink fax driver 0 = /dev/gfax0 GammaLink channel 0 1 = /dev/gfax1 GammaLink channel 1 ... -159 char RESERVED + 159 char RESERVED -159 block RESERVED + 159 block RESERVED -160 char General Purpose Instrument Bus (GPIB) + 160 char General Purpose Instrument Bus (GPIB) 0 = /dev/gpib0 First GPIB bus 1 = /dev/gpib1 Second GPIB bus ... -160 block Carmel 8-port SATA Disks on First Controller + 160 block Carmel 8-port SATA Disks on First Controller 0 = /dev/carmel/0 SATA disk 0 whole disk 1 = /dev/carmel/0p1 SATA disk 0 partition 1 ... @@ -2365,7 +2370,7 @@ Your cooperation is appreciated. disks (see major number 3) except that the limit on partitions is 31. -161 char IrCOMM devices (IrDA serial/parallel emulation) + 161 char IrCOMM devices (IrDA serial/parallel emulation) 0 = /dev/ircomm0 First IrCOMM device 1 = /dev/ircomm1 Second IrCOMM device ... @@ -2373,7 +2378,7 @@ Your cooperation is appreciated. 17 = /dev/irlpt1 Second IrLPT device ... -161 block Carmel 8-port SATA Disks on Second Controller + 161 block Carmel 8-port SATA Disks on Second Controller 0 = /dev/carmel/8 SATA disk 8 whole disk 1 = /dev/carmel/8p1 SATA disk 8 partition 1 ... @@ -2388,17 +2393,17 @@ Your cooperation is appreciated. disks (see major number 3) except that the limit on partitions is 31. -162 char Raw block device interface + 162 char Raw block device interface 0 = /dev/rawctl Raw I/O control device 1 = /dev/raw/raw1 First raw I/O device 2 = /dev/raw/raw2 Second raw I/O device ... - max minor number of raw device is set by kernel config - MAX_RAW_DEVS or raw module parameter 'max_raw_devs' + max minor number of raw device is set by kernel config + MAX_RAW_DEVS or raw module parameter 'max_raw_devs' -163 char + 163 char -164 char Chase Research AT/PCI-Fast serial card + 164 char Chase Research AT/PCI-Fast serial card 0 = /dev/ttyCH0 AT/PCI-Fast board 0, port 0 ... 15 = /dev/ttyCH15 AT/PCI-Fast board 0, port 15 @@ -2412,67 +2417,67 @@ Your cooperation is appreciated. ... 63 = /dev/ttyCH63 AT/PCI-Fast board 3, port 15 -165 char Chase Research AT/PCI-Fast serial card - alternate devices + 165 char Chase Research AT/PCI-Fast serial card - alternate devices 0 = /dev/cuch0 Callout device for ttyCH0 ... 63 = /dev/cuch63 Callout device for ttyCH63 -166 char ACM USB modems + 166 char ACM USB modems 0 = /dev/ttyACM0 First ACM modem 1 = /dev/ttyACM1 Second ACM modem ... -167 char ACM USB modems - alternate devices + 167 char ACM USB modems - alternate devices 0 = /dev/cuacm0 Callout device for ttyACM0 1 = /dev/cuacm1 Callout device for ttyACM1 ... -168 char Eracom CSA7000 PCI encryption adaptor + 168 char Eracom CSA7000 PCI encryption adaptor 0 = /dev/ecsa0 First CSA7000 1 = /dev/ecsa1 Second CSA7000 ... -169 char Eracom CSA8000 PCI encryption adaptor + 169 char Eracom CSA8000 PCI encryption adaptor 0 = /dev/ecsa8-0 First CSA8000 1 = /dev/ecsa8-1 Second CSA8000 ... -170 char AMI MegaRAC remote access controller + 170 char AMI MegaRAC remote access controller 0 = /dev/megarac0 First MegaRAC card 1 = /dev/megarac1 Second MegaRAC card ... -171 char Reserved for IEEE 1394 (Firewire) + 171 char Reserved for IEEE 1394 (Firewire) -172 char Moxa Intellio serial card + 172 char Moxa Intellio serial card 0 = /dev/ttyMX0 First Moxa port 1 = /dev/ttyMX1 Second Moxa port ... 127 = /dev/ttyMX127 128th Moxa port 128 = /dev/moxactl Moxa control port -173 char Moxa Intellio serial card - alternate devices + 173 char Moxa Intellio serial card - alternate devices 0 = /dev/cumx0 Callout device for ttyMX0 1 = /dev/cumx1 Callout device for ttyMX1 ... 127 = /dev/cumx127 Callout device for ttyMX127 -174 char SmartIO serial card + 174 char SmartIO serial card 0 = /dev/ttySI0 First SmartIO port 1 = /dev/ttySI1 Second SmartIO port ... -175 char SmartIO serial card - alternate devices + 175 char SmartIO serial card - alternate devices 0 = /dev/cusi0 Callout device for ttySI0 1 = /dev/cusi1 Callout device for ttySI1 ... -176 char nCipher nFast PCI crypto accelerator + 176 char nCipher nFast PCI crypto accelerator 0 = /dev/nfastpci0 First nFast PCI device 1 = /dev/nfastpci1 First nFast PCI device ... -177 char TI PCILynx memory spaces + 177 char TI PCILynx memory spaces 0 = /dev/pcilynx/aux0 AUX space of first PCILynx card ... 15 = /dev/pcilynx/aux15 AUX space of 16th PCILynx card @@ -2483,12 +2488,12 @@ Your cooperation is appreciated. ... 47 = /dev/pcilynx/ram15 RAM space of 16th PCILynx card -178 char Giganet cLAN1xxx virtual interface adapter + 178 char Giganet cLAN1xxx virtual interface adapter 0 = /dev/clanvi0 First cLAN adapter 1 = /dev/clanvi1 Second cLAN adapter ... -179 block MMC block devices + 179 block MMC block devices 0 = /dev/mmcblk0 First SD/MMC card 1 = /dev/mmcblk0p1 First partition on first MMC card 8 = /dev/mmcblk1 Second SD/MMC card @@ -2500,12 +2505,12 @@ Your cooperation is appreciated. bump the offset between each card to be the configured value instead of the default 8. -179 char CCube DVXChip-based PCI products + 179 char CCube DVXChip-based PCI products 0 = /dev/dvxirq0 First DVX device 1 = /dev/dvxirq1 Second DVX device ... -180 char USB devices + 180 char USB devices 0 = /dev/usb/lp0 First USB printer ... 15 = /dev/usb/lp15 16th USB printer @@ -2539,23 +2544,23 @@ Your cooperation is appreciated. ... 209 = /dev/usb/yurex16 16th USB Yurex device -180 block USB block devices + 180 block USB block devices 0 = /dev/uba First USB block device 8 = /dev/ubb Second USB block device 16 = /dev/ubc Third USB block device - ... + ... -181 char Conrad Electronic parallel port radio clocks + 181 char Conrad Electronic parallel port radio clocks 0 = /dev/pcfclock0 First Conrad radio clock 1 = /dev/pcfclock1 Second Conrad radio clock ... -182 char Picture Elements THR2 binarizer + 182 char Picture Elements THR2 binarizer 0 = /dev/pethr0 First THR2 board 1 = /dev/pethr1 Second THR2 board ... -183 char SST 5136-DN DeviceNet interface + 183 char SST 5136-DN DeviceNet interface 0 = /dev/ss5136dn0 First DeviceNet interface 1 = /dev/ss5136dn1 Second DeviceNet interface ... @@ -2563,12 +2568,12 @@ Your cooperation is appreciated. This device used to be assigned to major number 144. It had to be moved due to an unfortunate conflict. -184 char Picture Elements' video simulator/sender + 184 char Picture Elements' video simulator/sender 0 = /dev/pevss0 First sender board 1 = /dev/pevss1 Second sender board ... -185 char InterMezzo high availability file system + 185 char InterMezzo high availability file system 0 = /dev/intermezzo0 First cache manager 1 = /dev/intermezzo1 Second cache manager ... @@ -2576,48 +2581,48 @@ Your cooperation is appreciated. See http://web.archive.org/web/20080115195241/ http://inter-mezzo.org/index.html -186 char Object-based storage control device + 186 char Object-based storage control device 0 = /dev/obd0 First obd control device 1 = /dev/obd1 Second obd control device ... See ftp://ftp.lustre.org/pub/obd for code and information. -187 char DESkey hardware encryption device + 187 char DESkey hardware encryption device 0 = /dev/deskey0 First DES key 1 = /dev/deskey1 Second DES key ... -188 char USB serial converters + 188 char USB serial converters 0 = /dev/ttyUSB0 First USB serial converter 1 = /dev/ttyUSB1 Second USB serial converter ... -189 char USB serial converters - alternate devices + 189 char USB serial converters - alternate devices 0 = /dev/cuusb0 Callout device for ttyUSB0 1 = /dev/cuusb1 Callout device for ttyUSB1 ... -190 char Kansas City tracker/tuner card + 190 char Kansas City tracker/tuner card 0 = /dev/kctt0 First KCT/T card 1 = /dev/kctt1 Second KCT/T card ... -191 char Reserved for PCMCIA + 191 char Reserved for PCMCIA -192 char Kernel profiling interface + 192 char Kernel profiling interface 0 = /dev/profile Profiling control device 1 = /dev/profile0 Profiling device for CPU 0 2 = /dev/profile1 Profiling device for CPU 1 ... -193 char Kernel event-tracing interface + 193 char Kernel event-tracing interface 0 = /dev/trace Tracing control device 1 = /dev/trace0 Tracing device for CPU 0 2 = /dev/trace1 Tracing device for CPU 1 ... -194 char linVideoStreams (LINVS) + 194 char linVideoStreams (LINVS) 0 = /dev/mvideo/status0 Video compression status 1 = /dev/mvideo/stream0 Video stream 2 = /dev/mvideo/frame0 Single compressed frame @@ -2633,13 +2638,13 @@ Your cooperation is appreciated. 240 = /dev/mvideo/status15 16th device ... -195 char Nvidia graphics devices + 195 char Nvidia graphics devices 0 = /dev/nvidia0 First Nvidia card 1 = /dev/nvidia1 Second Nvidia card ... 255 = /dev/nvidiactl Nvidia card control device -196 char Tormenta T1 card + 196 char Tormenta T1 card 0 = /dev/tor/0 Master control channel for all cards 1 = /dev/tor/1 First DS0 2 = /dev/tor/2 Second DS0 @@ -2649,24 +2654,24 @@ Your cooperation is appreciated. 50 = /dev/tor/50 Second pseudo-channel ... -197 char OpenTNF tracing facility + 197 char OpenTNF tracing facility 0 = /dev/tnf/t0 Trace 0 data extraction 1 = /dev/tnf/t1 Trace 1 data extraction ... 128 = /dev/tnf/status Tracing facility status 130 = /dev/tnf/trace Tracing device -198 char Total Impact TPMP2 quad coprocessor PCI card + 198 char Total Impact TPMP2 quad coprocessor PCI card 0 = /dev/tpmp2/0 First card 1 = /dev/tpmp2/1 Second card ... -199 char Veritas volume manager (VxVM) volumes + 199 char Veritas volume manager (VxVM) volumes 0 = /dev/vx/rdsk/*/* First volume 1 = /dev/vx/rdsk/*/* Second volume ... -199 block Veritas volume manager (VxVM) volumes + 199 block Veritas volume manager (VxVM) volumes 0 = /dev/vx/dsk/*/* First volume 1 = /dev/vx/dsk/*/* Second volume ... @@ -2674,19 +2679,19 @@ Your cooperation is appreciated. The namespace in these directories is maintained by the user space VxVM software. -200 char Veritas VxVM configuration interface - 0 = /dev/vx/config Configuration access node - 1 = /dev/vx/trace Volume i/o trace access node - 2 = /dev/vx/iod Volume i/o daemon access node - 3 = /dev/vx/info Volume information access node - 4 = /dev/vx/task Volume tasks access node - 5 = /dev/vx/taskmon Volume tasks monitor daemon + 200 char Veritas VxVM configuration interface + 0 = /dev/vx/config Configuration access node + 1 = /dev/vx/trace Volume i/o trace access node + 2 = /dev/vx/iod Volume i/o daemon access node + 3 = /dev/vx/info Volume information access node + 4 = /dev/vx/task Volume tasks access node + 5 = /dev/vx/taskmon Volume tasks monitor daemon -201 char Veritas VxVM dynamic multipathing driver + 201 char Veritas VxVM dynamic multipathing driver 0 = /dev/vx/rdmp/* First multipath device 1 = /dev/vx/rdmp/* Second multipath device ... -201 block Veritas VxVM dynamic multipathing driver + 201 block Veritas VxVM dynamic multipathing driver 0 = /dev/vx/dmp/* First multipath device 1 = /dev/vx/dmp/* Second multipath device ... @@ -2694,28 +2699,28 @@ Your cooperation is appreciated. The namespace in these directories is maintained by the user space VxVM software. -202 char CPU model-specific registers + 202 char CPU model-specific registers 0 = /dev/cpu/0/msr MSRs on CPU 0 1 = /dev/cpu/1/msr MSRs on CPU 1 ... -202 block Xen Virtual Block Device + 202 block Xen Virtual Block Device 0 = /dev/xvda First Xen VBD whole disk 16 = /dev/xvdb Second Xen VBD whole disk 32 = /dev/xvdc Third Xen VBD whole disk ... 240 = /dev/xvdp Sixteenth Xen VBD whole disk - Partitions are handled in the same way as for IDE - disks (see major number 3) except that the limit on - partitions is 15. + Partitions are handled in the same way as for IDE + disks (see major number 3) except that the limit on + partitions is 15. -203 char CPU CPUID information + 203 char CPU CPUID information 0 = /dev/cpu/0/cpuid CPUID on CPU 0 1 = /dev/cpu/1/cpuid CPUID on CPU 1 ... -204 char Low-density serial ports + 204 char Low-density serial ports 0 = /dev/ttyLU0 LinkUp Systems L72xx UART - port 0 1 = /dev/ttyLU1 LinkUp Systems L72xx UART - port 1 2 = /dev/ttyLU2 LinkUp Systems L72xx UART - port 2 @@ -2787,7 +2792,7 @@ Your cooperation is appreciated. 211 = /dev/ttyMAX2 MAX3100 serial port 2 212 = /dev/ttyMAX3 MAX3100 serial port 3 -205 char Low-density serial ports (alternate device) + 205 char Low-density serial ports (alternate device) 0 = /dev/culu0 Callout device for ttyLU0 1 = /dev/culu1 Callout device for ttyLU1 2 = /dev/culu2 Callout device for ttyLU2 @@ -2823,7 +2828,7 @@ Your cooperation is appreciated. 82 = /dev/cuvr0 Callout device for ttyVR0 83 = /dev/cuvr1 Callout device for ttyVR1 -206 char OnStream SC-x0 tape devices + 206 char OnStream SC-x0 tape devices 0 = /dev/osst0 First OnStream SCSI tape, mode 0 1 = /dev/osst1 Second OnStream SCSI tape, mode 0 ... @@ -2857,7 +2862,7 @@ Your cooperation is appreciated. driver as well. The ADR-x0 drives are QIC-157 compliant and don't need osst. -207 char Compaq ProLiant health feature indicate + 207 char Compaq ProLiant health feature indicate 0 = /dev/cpqhealth/cpqw Redirector interface 1 = /dev/cpqhealth/crom EISA CROM 2 = /dev/cpqhealth/cdt Data Table @@ -2871,17 +2876,17 @@ Your cooperation is appreciated. 10 = /dev/cpqhealth/cram CMOS interface 11 = /dev/cpqhealth/cpci PCI IRQ interface -208 char User space serial ports + 208 char User space serial ports 0 = /dev/ttyU0 First user space serial port 1 = /dev/ttyU1 Second user space serial port ... -209 char User space serial ports (alternate devices) + 209 char User space serial ports (alternate devices) 0 = /dev/cuu0 Callout device for ttyU0 1 = /dev/cuu1 Callout device for ttyU1 ... -210 char SBE, Inc. sync/async serial card + 210 char SBE, Inc. sync/async serial card 0 = /dev/sbei/wxcfg0 Configuration device for board 0 1 = /dev/sbei/dld0 Download device for board 0 2 = /dev/sbei/wan00 WAN device, port 0, board 0 @@ -2906,12 +2911,12 @@ Your cooperation is appreciated. Yes, each board is really spaced 10 (decimal) apart. -211 char Addinum CPCI1500 digital I/O card + 211 char Addinum CPCI1500 digital I/O card 0 = /dev/addinum/cpci1500/0 First CPCI1500 card 1 = /dev/addinum/cpci1500/1 Second CPCI1500 card ... -212 char LinuxTV.org DVB driver subsystem + 212 char LinuxTV.org DVB driver subsystem 0 = /dev/dvb/adapter0/video0 first video decoder of first card 1 = /dev/dvb/adapter0/audio0 first audio decoder of first card 2 = /dev/dvb/adapter0/sec0 (obsolete/unused) @@ -2929,34 +2934,34 @@ Your cooperation is appreciated. ... 196 = /dev/dvb/adapter3/video0 first video decoder of fourth card -216 char Bluetooth RFCOMM TTY devices + 216 char Bluetooth RFCOMM TTY devices 0 = /dev/rfcomm0 First Bluetooth RFCOMM TTY device 1 = /dev/rfcomm1 Second Bluetooth RFCOMM TTY device ... -217 char Bluetooth RFCOMM TTY devices (alternate devices) + 217 char Bluetooth RFCOMM TTY devices (alternate devices) 0 = /dev/curf0 Callout device for rfcomm0 1 = /dev/curf1 Callout device for rfcomm1 ... -218 char The Logical Company bus Unibus/Qbus adapters + 218 char The Logical Company bus Unibus/Qbus adapters 0 = /dev/logicalco/bci/0 First bus adapter 1 = /dev/logicalco/bci/1 First bus adapter ... -219 char The Logical Company DCI-1300 digital I/O card + 219 char The Logical Company DCI-1300 digital I/O card 0 = /dev/logicalco/dci1300/0 First DCI-1300 card 1 = /dev/logicalco/dci1300/1 Second DCI-1300 card ... -220 char Myricom Myrinet "GM" board + 220 char Myricom Myrinet "GM" board 0 = /dev/myricom/gm0 First Myrinet GM board 1 = /dev/myricom/gmp0 First board "root access" 2 = /dev/myricom/gm1 Second Myrinet GM board 3 = /dev/myricom/gmp1 Second board "root access" ... -221 char VME bus + 221 char VME bus 0 = /dev/bus/vme/m0 First master image 1 = /dev/bus/vme/m1 Second master image 2 = /dev/bus/vme/m2 Third master image @@ -2971,38 +2976,38 @@ Your cooperation is appreciated. same interface. For interface documentation see http://www.vmelinux.org/. -224 char A2232 serial card + 224 char A2232 serial card 0 = /dev/ttyY0 First A2232 port 1 = /dev/ttyY1 Second A2232 port ... -225 char A2232 serial card (alternate devices) + 225 char A2232 serial card (alternate devices) 0 = /dev/cuy0 Callout device for ttyY0 1 = /dev/cuy1 Callout device for ttyY1 ... -226 char Direct Rendering Infrastructure (DRI) + 226 char Direct Rendering Infrastructure (DRI) 0 = /dev/dri/card0 First graphics card 1 = /dev/dri/card1 Second graphics card ... -227 char IBM 3270 terminal Unix tty access + 227 char IBM 3270 terminal Unix tty access 1 = /dev/3270/tty1 First 3270 terminal 2 = /dev/3270/tty2 Seconds 3270 terminal ... -228 char IBM 3270 terminal block-mode access + 228 char IBM 3270 terminal block-mode access 0 = /dev/3270/tub Controlling interface 1 = /dev/3270/tub1 First 3270 terminal 2 = /dev/3270/tub2 Second 3270 terminal ... -229 char IBM iSeries/pSeries virtual console + 229 char IBM iSeries/pSeries virtual console 0 = /dev/hvc0 First console port 1 = /dev/hvc1 Second console port ... -230 char IBM iSeries virtual tape + 230 char IBM iSeries virtual tape 0 = /dev/iseries/vt0 First virtual tape, mode 0 1 = /dev/iseries/vt1 Second virtual tape, mode 0 ... @@ -3033,7 +3038,7 @@ Your cooperation is appreciated. ioctl()'s can be used to rewind the tape regardless of the device used to access it. -231 char InfiniBand + 231 char InfiniBand 0 = /dev/infiniband/umad0 1 = /dev/infiniband/umad1 ... @@ -3047,7 +3052,7 @@ Your cooperation is appreciated. ... 159 = /dev/infiniband/uverbs31 31st InfiniBand verbs device -232 char Biometric Devices + 232 char Biometric Devices 0 = /dev/biometric/sensor0/fingerprint first fingerprint sensor on first device 1 = /dev/biometric/sensor0/iris first iris sensor on first device 2 = /dev/biometric/sensor0/retina first retina sensor on first device @@ -3060,7 +3065,7 @@ Your cooperation is appreciated. 20 = /dev/biometric/sensor2/fingerprint first fingerprint sensor on third device ... -233 char PathScale InfiniPath interconnect + 233 char PathScale InfiniPath interconnect 0 = /dev/ipath Primary device for programs (any unit) 1 = /dev/ipath0 Access specifically to unit 0 2 = /dev/ipath1 Access specifically to unit 1 @@ -3069,18 +3074,18 @@ Your cooperation is appreciated. 129 = /dev/ipath_sma Device used by Subnet Management Agent 130 = /dev/ipath_diag Device used by diagnostics programs -234-254 char RESERVED FOR DYNAMIC ASSIGNMENT + 234-254 char RESERVED FOR DYNAMIC ASSIGNMENT Character devices that request a dynamic allocation of major number will take numbers starting from 254 and downward. -240-254 block LOCAL/EXPERIMENTAL USE + 240-254 block LOCAL/EXPERIMENTAL USE Allocated for local/experimental use. For devices not assigned official numbers, these ranges should be used in order to avoid conflicting with future assignments. -255 char RESERVED + 255 char RESERVED -255 block RESERVED + 255 block RESERVED This major is reserved to assist the expansion to a larger number space. No device nodes with this major @@ -3088,25 +3093,25 @@ Your cooperation is appreciated. (This is probably not true anymore, but I'll leave it for now /Torben) ----LARGE MAJORS!!!!!--- + ---LARGE MAJORS!!!!!--- -256 char Equinox SST multi-port serial boards + 256 char Equinox SST multi-port serial boards 0 = /dev/ttyEQ0 First serial port on first Equinox SST board 127 = /dev/ttyEQ127 Last serial port on first Equinox SST board 128 = /dev/ttyEQ128 First serial port on second Equinox SST board ... 1027 = /dev/ttyEQ1027 Last serial port on eighth Equinox SST board -256 block Resident Flash Disk Flash Translation Layer + 256 block Resident Flash Disk Flash Translation Layer 0 = /dev/rfda First RFD FTL layer 16 = /dev/rfdb Second RFD FTL layer ... 240 = /dev/rfdp 16th RFD FTL layer -257 char Phoenix Technologies Cryptographic Services Driver + 257 char Phoenix Technologies Cryptographic Services Driver 0 = /dev/ptlsec Crypto Services Driver -257 block SSFDC Flash Translation Layer filesystem + 257 block SSFDC Flash Translation Layer filesystem 0 = /dev/ssfdca First SSFDC layer 8 = /dev/ssfdcb Second SSFDC layer 16 = /dev/ssfdcc Third SSFDC layer @@ -3116,26 +3121,28 @@ Your cooperation is appreciated. 48 = /dev/ssfdcg 7th SSFDC layer 56 = /dev/ssfdch 8th SSFDC layer -258 block ROM/Flash read-only translation layer + 258 block ROM/Flash read-only translation layer 0 = /dev/blockrom0 First ROM card's translation layer interface 1 = /dev/blockrom1 Second ROM card's translation layer interface ... -259 block Block Extended Major + 259 block Block Extended Major Used dynamically to hold additional partition minor numbers and allow large numbers of partitions per device -259 char FPGA configuration interfaces + 259 char FPGA configuration interfaces 0 = /dev/icap0 First Xilinx internal configuration 1 = /dev/icap1 Second Xilinx internal configuration -260 char OSD (Object-based-device) SCSI Device + 260 char OSD (Object-based-device) SCSI Device 0 = /dev/osd0 First OSD Device 1 = /dev/osd1 Second OSD Device ... 255 = /dev/osd255 256th OSD Device - **** ADDITIONAL /dev DIRECTORY ENTRIES + +Additional ``/dev/`` directory entries +-------------------------------------- This section details additional entries that should or may exist in the /dev directory. It is preferred that symbolic links use the same @@ -3143,24 +3150,29 @@ form (absolute or relative) as is indicated here. Links are classified as "hard" or "symbolic" depending on the preferred type of link; if possible, the indicated type of link should be used. - - Compulsory links +Compulsory links +++++++++++++++++ These links should exist on all systems: +=============== =============== =============== =============================== /dev/fd /proc/self/fd symbolic File descriptors /dev/stdin fd/0 symbolic stdin file descriptor /dev/stdout fd/1 symbolic stdout file descriptor /dev/stderr fd/2 symbolic stderr file descriptor /dev/nfsd socksys symbolic Required by iBCS-2 /dev/X0R null symbolic Required by iBCS-2 +=============== =============== =============== =============================== -Note: /dev/X0R is --. +Note: ``/dev/X0R`` is --. - Recommended links +Recommended links ++++++++++++++++++ It is recommended that these links exist on all systems: + +=============== =============== =============== =============================== /dev/core /proc/kcore symbolic Backward compatibility /dev/ramdisk ram0 symbolic Backward compatibility /dev/ftape qft0 symbolic Backward compatibility @@ -3168,14 +3180,17 @@ It is recommended that these links exist on all systems: /dev/radio radio0 symbolic Backward compatibility /dev/i2o* /dev/i2o/* symbolic Backward compatibility /dev/scd? sr? hard Alternate SCSI CD-ROM name +=============== =============== =============== =============================== - Locally defined links +Locally defined links ++++++++++++++++++++++ The following links may be established locally to conform to the configuration of the system. This is merely a tabulation of existing practice, and does not constitute a recommendation. However, if they exist, they should have the following uses. +=============== =============== =============== =============================== /dev/mouse mouse port symbolic Current mouse device /dev/tape tape device symbolic Current tape device /dev/cdrom CD-ROM device symbolic Current CD-ROM device @@ -3184,38 +3199,46 @@ exist, they should have the following uses. /dev/modem modem port symbolic Current dialout device /dev/root root device symbolic Current root filesystem /dev/swap swap device symbolic Current swap device +=============== =============== =============== =============================== -/dev/modem should not be used for a modem which supports dialin as +``/dev/modem`` should not be used for a modem which supports dialin as well as dialout, as it tends to cause lock file problems. If it -exists, /dev/modem should point to the appropriate primary TTY device +exists, ``/dev/modem`` should point to the appropriate primary TTY device (the use of the alternate callout devices is deprecated). -For SCSI devices, /dev/tape and /dev/cdrom should point to the -``cooked'' devices (/dev/st* and /dev/sr*, respectively), whereas -/dev/cdwriter and /dev/scanner should point to the appropriate generic +For SCSI devices, ``/dev/tape`` and ``/dev/cdrom`` should point to the +*cooked* devices (``/dev/st*`` and ``/dev/sr*``, respectively), whereas +``/dev/cdwriter`` and /dev/scanner should point to the appropriate generic SCSI devices (/dev/sg*). -/dev/mouse may point to a primary serial TTY device, a hardware mouse -device, or a socket for a mouse driver program (e.g. /dev/gpmdata). +``/dev/mouse`` may point to a primary serial TTY device, a hardware mouse +device, or a socket for a mouse driver program (e.g. ``/dev/gpmdata``). - Sockets and pipes +Sockets and pipes ++++++++++++++++++ Non-transient sockets and named pipes may exist in /dev. Common entries are: +=============== =============== =============================================== /dev/printer socket lpd local socket /dev/log socket syslog local socket /dev/gpmdata socket gpm mouse multiplexer +=============== =============== =============================================== - Mount points +Mount points +++++++++++++ The following names are reserved for mounting special filesystems under /dev. These special filesystems provide kernel interfaces that cannot be provided with standard device nodes. +=============== =============== =============================================== /dev/pts devpts PTY slave filesystem /dev/shm tmpfs POSIX shared memory maintenance access +=============== =============== =============================================== - **** TERMINAL DEVICES +Terminal devices +---------------- Terminal, or TTY devices are a special class of character devices. A terminal device is any device that could act as a controlling terminal @@ -3232,42 +3255,44 @@ conventions include several historical warts; some of these are Linux-specific, some were inherited from other systems, and some reflect Linux outgrowing a borrowed convention. -A hash mark (#) in a device name is used here to indicate a decimal +A hash mark (``#``) in a device name is used here to indicate a decimal number without leading zeroes. - Virtual consoles and the console device +Virtual consoles and the console device ++++++++++++++++++++++++++++++++++++++++ Virtual consoles are full-screen terminal displays on the system video -monitor. Virtual consoles are named /dev/tty#, with numbering -starting at /dev/tty1; /dev/tty0 is the current virtual console. -/dev/tty0 is the device that should be used to access the system video +monitor. Virtual consoles are named ``/dev/tty#``, with numbering +starting at ``/dev/tty1``; ``/dev/tty0`` is the current virtual console. +``/dev/tty0`` is the device that should be used to access the system video card on those architectures for which the frame buffer devices -(/dev/fb*) are not applicable. Do not use /dev/console +(``/dev/fb*``) are not applicable. Do not use ``/dev/console`` for this purpose. -The console device, /dev/console, is the device to which system +The console device, ``/dev/console``, is the device to which system messages should be sent, and on which logins should be permitted in -single-user mode. Starting with Linux 2.1.71, /dev/console is managed +single-user mode. Starting with Linux 2.1.71, ``/dev/console`` is managed by the kernel; for previous versions it should be a symbolic link to -either /dev/tty0, a specific virtual console such as /dev/tty1, or to -a serial port primary (tty*, not cu*) device, depending on the +either ``/dev/tty0``, a specific virtual console such as ``/dev/tty1``, or to +a serial port primary (``tty*``, not ``cu*``) device, depending on the configuration of the system. - Serial ports +Serial ports +++++++++++++ Serial ports are RS-232 serial ports and any device which simulates one, either in hardware (such as internal modems) or in software (such as the ISDN driver.) Under Linux, each serial ports has two device names, the primary or callin device and the alternate or callout one. Each kind of device is indicated by a different letter. For any -letter X, the names of the devices are /dev/ttyX# and /dev/cux#, -respectively; for historical reasons, /dev/ttyS# and /dev/ttyC# -correspond to /dev/cua# and /dev/cub#. In the future, it should be +letter X, the names of the devices are ``/dev/ttyX#`` and ``/dev/cux#``, +respectively; for historical reasons, ``/dev/ttyS#`` and ``/dev/ttyC#`` +correspond to ``/dev/cua#`` and ``/dev/cub#``. In the future, it should be expected that multiple letters will be used; all letters will be upper -case for the "tty" device (e.g. /dev/ttyDP#) and lower case for the -"cu" device (e.g. /dev/cudp#). +case for the "tty" device (e.g. ``/dev/ttyDP#``) and lower case for the +"cu" device (e.g. ``/dev/cudp#``). -The names /dev/ttyQ# and /dev/cuq# are reserved for local use. +The names ``/dev/ttyQ#`` and ``/dev/cuq#`` are reserved for local use. The alternate devices provide for kernel-based exclusion and somewhat different defaults than the primary devices. Their main purpose is to @@ -3276,7 +3301,7 @@ support for serial ports. Their use is deprecated, and they may be removed from a future version of Linux. Arbitration of serial ports is provided by the use of lock files with -the names /var/lock/LCK..ttyX#. The contents of the lock file should +the names ``/var/lock/LCK..ttyX#``. The contents of the lock file should be the PID of the locking process as an ASCII number. It is common practice to install links such as /dev/modem @@ -3287,9 +3312,9 @@ that a lock file be installed with the corresponding alternate device. In order to avoid deadlocks, it is recommended that the locks are acquired in the following order, and released in the reverse: - 1. The symbolic link name, if any (/var/lock/LCK..modem) - 2. The "tty" name (/var/lock/LCK..ttyS2) - 3. The alternate device name (/var/lock/LCK..cua2) + 1. The symbolic link name, if any (``/var/lock/LCK..modem``) + 2. The "tty" name (``/var/lock/LCK..ttyS2``) + 3. The alternate device name (``/var/lock/LCK..cua2``) In the case of nested symbolic links, the lock files should be installed in the order the symlinks are resolved. @@ -3300,13 +3325,14 @@ to create lock files for the corresponding alternate device names should take into account the possibility of being used on a non-serial port TTY, for which no alternate device would exist. - Pseudoterminals (PTYs) +Pseudoterminals (PTYs) +++++++++++++++++++++++ Pseudoterminals, or PTYs, are used to create login sessions or provide other capabilities requiring a TTY line discipline (including SLIP or PPP capability) to arbitrary data-generation processes. Each PTY has -a master side, named /dev/pty[p-za-e][0-9a-f], and a slave side, named -/dev/tty[p-za-e][0-9a-f]. The kernel arbitrates the use of PTYs by +a master side, named ``/dev/pty[p-za-e][0-9a-f]``, and a slave side, named +``/dev/tty[p-za-e][0-9a-f]``. The kernel arbitrates the use of PTYs by allowing each master side to be opened only once. Once the master side has been opened, the corresponding slave device @@ -3316,9 +3342,9 @@ of a bidirectional pipe with TTY capabilities. Recent versions of the Linux kernels and GNU libc contain support for the System V/Unix98 naming scheme for PTYs, which assigns a common -device, /dev/ptmx, to all the masters (opening it will automatically -give you a previously unassigned PTY) and a subdirectory, /dev/pts, -for the slaves; the slaves are named with decimal integers (/dev/pts/# +device, ``/dev/ptmx``, to all the masters (opening it will automatically +give you a previously unassigned PTY) and a subdirectory, ``/dev/pts``, +for the slaves; the slaves are named with decimal integers (``/dev/pts/#`` in our notation). This removes the problem of exhausting the namespace and enables the kernel to automatically create the device nodes for the slaves on demand using the "devpts" filesystem. -- cgit v1.2.3 From 7d4e3517bdc2972e0dd35be34e07832841fc036a Mon Sep 17 00:00:00 2001 From: Mauro Carvalho Chehab Date: Wed, 21 Sep 2016 16:32:00 -0300 Subject: Documentation/dynamic-debug-howto.txt: convert it to ReST markup - use a quote blocks where needed; - fix the chapter/section/subsection markups; - use ``foo`` for monotonic; - use .. note:: for the line-range note; - cleanup whitespaces; - add it to the user's book. Signed-off-by: Mauro Carvalho Chehab --- Documentation/dynamic-debug-howto.txt | 297 ++++++++++++++++++---------------- 1 file changed, 155 insertions(+), 142 deletions(-) diff --git a/Documentation/dynamic-debug-howto.txt b/Documentation/dynamic-debug-howto.txt index 9417871b8758..88adcfdf5b2b 100644 --- a/Documentation/dynamic-debug-howto.txt +++ b/Documentation/dynamic-debug-howto.txt @@ -1,3 +1,6 @@ +Dynamic debug ++++++++++++++ + Introduction ============ @@ -6,16 +9,16 @@ 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 +``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). +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. +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: @@ -28,96 +31,95 @@ Dynamic debug has even more useful features: - module name - format string - * Provides a debugfs control file: /dynamic_debug/control + * Provides a debugfs control file: ``/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()s are controlled via writing to a +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: -/dynamic_debug/control. For example, if you want to enable -printing from source file 'svcsock.c', line 1603 you simply do: +``/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' > + nullarbor:~ # echo 'file svcsock.c line 1603 +p' > /dynamic_debug/control -If you make a mistake with the syntax, the write will fail thus: +If you make a mistake with the syntax, the write will fail thus:: -nullarbor:~ # echo 'file svcsock.c wtf 1 +p' > + nullarbor:~ # echo 'file svcsock.c wtf 1 +p' > /dynamic_debug/control --bash: echo: write error: Invalid argument + -bash: echo: write error: Invalid argument Viewing Dynamic Debug Behaviour -=========================== +=============================== You can view the currently configured behaviour of all the debug -statements via: +statements via:: -nullarbor:~ # cat /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" -... + nullarbor:~ # cat /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. +data, e.g.:: -nullarbor:~ # grep -i rdma /dynamic_debug/control | wc -l -62 + nullarbor:~ # grep -i rdma /dynamic_debug/control | wc -l + 62 -nullarbor:~ # grep -i tcp /dynamic_debug/control | wc -l -42 + nullarbor:~ # grep -i tcp /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 != "=_"' /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" +default value, with no flags enabled, is ``=_``. So you can view all +the debug statement callsites with any non-default flags:: + nullarbor:~ # awk '$3 != "=_"' /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: +by spaces or tabs. So these are all equivalent:: -nullarbor:~ # echo -c 'file svcsock.c line 1603 +p' > + nullarbor:~ # echo -c 'file svcsock.c line 1603 +p' > /dynamic_debug/control -nullarbor:~ # echo -c ' file svcsock.c line 1603 +p ' > + nullarbor:~ # echo -c ' file svcsock.c line 1603 +p ' > /dynamic_debug/control -nullarbor:~ # echo -n 'file svcsock.c line 1603 +p' > + nullarbor:~ # echo -n 'file svcsock.c line 1603 +p' > /dynamic_debug/control Command submissions are bounded by a write() system call. -Multiple commands can be written together, separated by ';' or '\n'. +Multiple commands can be written together, separated by ``;`` or ``\n``:: ~# echo "func pnpacpi_get_resources +p; func pnp_assign_mem +p" \ > /dynamic_debug/control -If your query set is big, you can batch them too: +If your query set is big, you can batch them too:: ~# cat query-batch-file > /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: +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" > /dynamic_debug/control At the syntactical level, a command comprises a sequence of match -specifications, followed by a flags change specification. +specifications, followed by a flags change specification:: -command ::= match-spec* flags-spec + 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 @@ -126,88 +128,92 @@ 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: +against. Possible keywords are::: + + match-spec ::= 'func' string | + 'file' string | + 'module' string | + 'format' string | + 'line' line-range -match-spec ::= 'func' string | - 'file' string | - 'module' string | - 'format' string | - 'line' line-range + line-range ::= lineno | + '-'lineno | + lineno'-' | + lineno'-'lineno -line-range ::= lineno | - '-'lineno | - lineno'-' | - lineno'-'lineno -// Note: line-range cannot contain space, e.g. -// "1-30" is valid range but "1 - 30" is not. + lineno ::= unsigned-int + +.. note:: + + ``line-range`` cannot contain space, e.g. + "1-30" is valid range but "1 - 30" is not. -lineno ::= unsigned-int The meanings of each keyword are: func The given string is compared against the function name - of each callsite. Example: + of each callsite. Example:: - func svc_tcp_accept + 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: + each callsite. Examples:: - file svcsock.c - file kernel/freezer.c - file /usr/src/packages/BUILD/sgi-enhancednfs-1.4/default/net/sunrpc/svcsock.c + 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: + seen in ``lsmod``, i.e. without the directory or the ``.ko`` + suffix and with ``-`` changed to ``_``. Examples:: - module sunrpc - module nfsd + 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. + 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: + 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 + 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 + 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: + 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 + 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: +of the characters:: - remove the given flags + add the given flags = set the flags to the given flags -The flags are: +The flags are:: p enables the pr_debug() callsite. f Include the function name in the printed message @@ -216,14 +222,14 @@ The flags are: 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 +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 '=' +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". +Note the regexp ``^[-+=][flmpt_]+$`` matches a flags specification. +To clear all flags at once, use ``=_`` or ``-flmpt``. Debug messages during Boot Process @@ -231,110 +237,117 @@ 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 +``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 +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 +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 +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 +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, +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 +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:: -2. # foo.dyndbg as given in boot args, "foo." is stripped and passed - foo.dyndbg=" func bar +p; func buz +mp" + foo.dyndbg=" func bar +p; func buz +mp" -3. # args to modprobe - modprobe foo dyndbg==pmf # override previous settings +3. args to modprobe:: -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 + 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. +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: +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. +- 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: +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" > /dynamic_debug/control Examples ======== -// enable the message at line 1603 of file svcsock.c -nullarbor:~ # echo -n 'file svcsock.c line 1603 +p' > +:: + + // enable the message at line 1603 of file svcsock.c + nullarbor:~ # echo -n 'file svcsock.c line 1603 +p' > /dynamic_debug/control -// enable all the messages in file svcsock.c -nullarbor:~ # echo -n 'file svcsock.c +p' > + // enable all the messages in file svcsock.c + nullarbor:~ # echo -n 'file svcsock.c +p' > /dynamic_debug/control -// enable all the messages in the NFS server module -nullarbor:~ # echo -n 'module nfsd +p' > + // enable all the messages in the NFS server module + nullarbor:~ # echo -n 'module nfsd +p' > /dynamic_debug/control -// enable all 12 messages in the function svc_process() -nullarbor:~ # echo -n 'func svc_process +p' > + // enable all 12 messages in the function svc_process() + nullarbor:~ # echo -n 'func svc_process +p' > /dynamic_debug/control -// disable all 12 messages in the function svc_process() -nullarbor:~ # echo -n 'func svc_process -p' > + // disable all 12 messages in the function svc_process() + nullarbor:~ # echo -n 'func svc_process -p' > /dynamic_debug/control -// enable messages for NFS calls READ, READLINK, READDIR and READDIR+. -nullarbor:~ # echo -n 'format "nfsd: READ" +p' > + // enable messages for NFS calls READ, READLINK, READDIR and READDIR+. + nullarbor:~ # echo -n 'format "nfsd: READ" +p' > /dynamic_debug/control -// enable messages in files of which the paths include string "usb" -nullarbor:~ # echo -n '*usb* +p' > /dynamic_debug/control + // enable messages in files of which the paths include string "usb" + nullarbor:~ # echo -n '*usb* +p' > /dynamic_debug/control -// enable all messages -nullarbor:~ # echo -n '+p' > /dynamic_debug/control + // enable all messages + nullarbor:~ # echo -n '+p' > /dynamic_debug/control -// add module, function to all enabled messages -nullarbor:~ # echo -n '+mf' > /dynamic_debug/control + // add module, function to all enabled messages + nullarbor:~ # echo -n '+mf' > /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" + // 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" -- cgit v1.2.3 From 5d0ad553783f408f9c79d23e06fdfe9c4bc6c0a9 Mon Sep 17 00:00:00 2001 From: Mauro Carvalho Chehab Date: Wed, 21 Sep 2016 16:52:26 -0300 Subject: Documentation/initrd.txt: convert to ReST markup - use a quote blocks where needed; - fix the chapter/section/subsection markups; - use ``foo`` for monotonic; - use .. note:: for /sbin/init file permissions; - adjust whitespaces and blank lines; - add it to the user's book. Signed-off-by: Mauro Carvalho Chehab --- Documentation/initrd.txt | 199 +++++++++++++++++++++++++---------------------- 1 file changed, 108 insertions(+), 91 deletions(-) diff --git a/Documentation/initrd.txt b/Documentation/initrd.txt index 4e1839ccb555..a03dabaaf3a3 100644 --- a/Documentation/initrd.txt +++ b/Documentation/initrd.txt @@ -2,7 +2,7 @@ Using the initial RAM disk (initrd) =================================== Written 1996,2000 by Werner Almesberger and - Hans Lermen +Hans Lermen 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= (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 initrd= -e.g. LOADLIN C:\LINUX\BZIMAGE initrd=C:\LINUX\INITRD.GZ root=/dev/ram0 rw -With LILO, you add the option INITRD= 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=`` 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 2>&1 + # exec chroot . what-follows 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/ -- cgit v1.2.3 From 8887addef55f1298b967bcf67285f4a43c9db85c Mon Sep 17 00:00:00 2001 From: Mauro Carvalho Chehab Date: Wed, 21 Sep 2016 16:59:42 -0300 Subject: Documentation/init.txt: convert to ReST markup - use a quote blocks where needed; - use ``foo`` for monotonic; - adjust whitespaces and blank lines; - fix the second list (that starts with 0, instead of A) - add it to the user's book. Signed-off-by: Mauro Carvalho Chehab --- Documentation/init.txt | 29 ++++++++++++++++------------- 1 file changed, 16 insertions(+), 13 deletions(-) diff --git a/Documentation/init.txt b/Documentation/init.txt index 535ad5e82b98..e89d97f31eaf 100644 --- a/Documentation/init.txt +++ b/Documentation/init.txt @@ -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 |grep NEEDED - to find out which libraries are required. + ``/lib/ld-linux.so.2`` missing or broken. Use + ``readelf -d |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. -- cgit v1.2.3 From 9a11e15381b3503e51c4bbab4f9dad7c001f7c94 Mon Sep 17 00:00:00 2001 From: Mauro Carvalho Chehab Date: Wed, 21 Sep 2016 17:18:36 -0300 Subject: Documentation/magic-number.txt: convert it to ReST markup - add a title for the document; - convert the table; - use quote block for the changelog; - use monotonic fonts for file names; - adjust whitespaces and blank lines; - add it to the user's book. Signed-off-by: Mauro Carvalho Chehab --- Documentation/magic-number.txt | 216 +++++++++++++++++++++-------------------- 1 file changed, 111 insertions(+), 105 deletions(-) diff --git a/Documentation/magic-number.txt b/Documentation/magic-number.txt index 28befed9f610..c74199f60c6c 100644 --- a/Documentation/magic-number.txt +++ b/Documentation/magic-number.txt @@ -1,9 +1,12 @@ +Linux magic numbers +=================== + This file is a registry of magic numbers which are in use. When you add a magic number to a structure, you should also add it to this file, since it is best if the magic numbers used by various structures are unique. -It is a *very* good idea to protect kernel data structures with magic +It is a **very** good idea to protect kernel data structures with magic numbers. This allows you to check at run time whether (a) a structure has been clobbered, or (b) you've passed the wrong structure to a routine. This last is especially useful --- particularly when you are @@ -12,12 +15,12 @@ for example, does this frequently to pass driver-specific and line discipline-specific structures back and forth. The way to use magic numbers is to declare then at the beginning of -the structure, like so: +the structure, like so:: -struct tty_ldisc { - int magic; - ... -}; + struct tty_ldisc { + int magic; + ... + }; Please follow this discipline when you are adding future enhancements to the kernel! It has saved me countless hours of debugging, @@ -25,134 +28,137 @@ especially in the screwy cases where an array has been overrun and structures following the array have been overwritten. Using this discipline, these cases get detected quickly and safely. +Changelog:: + Theodore Ts'o 31 Mar 94 -The magic table is current to Linux 2.1.55. + The magic table is current to Linux 2.1.55. Michael Chastain 22 Sep 1997 -Now it should be up to date with Linux 2.1.112. Because -we are in feature freeze time it is very unlikely that -something will change before 2.2.x. The entries are -sorted by number field. + Now it should be up to date with Linux 2.1.112. Because + we are in feature freeze time it is very unlikely that + something will change before 2.2.x. The entries are + sorted by number field. Krzysztof G. Baranowski 29 Jul 1998 -Updated the magic table to Linux 2.5.45. Right over the feature freeze, -but it is possible that some new magic numbers will sneak into the -kernel before 2.6.x yet. + Updated the magic table to Linux 2.5.45. Right over the feature freeze, + but it is possible that some new magic numbers will sneak into the + kernel before 2.6.x yet. Petr Baudis 03 Nov 2002 -Updated the magic table to Linux 2.5.74. + Updated the magic table to Linux 2.5.74. Fabian Frederick 09 Jul 2003 -Magic Name Number Structure File -=========================================================================== -PG_MAGIC 'P' pg_{read,write}_hdr include/linux/pg.h -CMAGIC 0x0111 user include/linux/a.out.h -MKISS_DRIVER_MAGIC 0x04bf mkiss_channel drivers/net/mkiss.h -HDLC_MAGIC 0x239e n_hdlc drivers/char/n_hdlc.c -APM_BIOS_MAGIC 0x4101 apm_user arch/x86/kernel/apm_32.c -CYCLADES_MAGIC 0x4359 cyclades_port include/linux/cyclades.h -DB_MAGIC 0x4442 fc_info drivers/net/iph5526_novram.c -DL_MAGIC 0x444d fc_info drivers/net/iph5526_novram.c -FASYNC_MAGIC 0x4601 fasync_struct include/linux/fs.h -FF_MAGIC 0x4646 fc_info drivers/net/iph5526_novram.c -ISICOM_MAGIC 0x4d54 isi_port include/linux/isicom.h -PTY_MAGIC 0x5001 drivers/char/pty.c -PPP_MAGIC 0x5002 ppp include/linux/if_pppvar.h -SERIAL_MAGIC 0x5301 async_struct include/linux/serial.h -SSTATE_MAGIC 0x5302 serial_state include/linux/serial.h -SLIP_MAGIC 0x5302 slip drivers/net/slip.h -STRIP_MAGIC 0x5303 strip drivers/net/strip.c -X25_ASY_MAGIC 0x5303 x25_asy drivers/net/x25_asy.h -SIXPACK_MAGIC 0x5304 sixpack drivers/net/hamradio/6pack.h -AX25_MAGIC 0x5316 ax_disp drivers/net/mkiss.h -TTY_MAGIC 0x5401 tty_struct include/linux/tty.h -MGSL_MAGIC 0x5401 mgsl_info drivers/char/synclink.c -TTY_DRIVER_MAGIC 0x5402 tty_driver include/linux/tty_driver.h -MGSLPC_MAGIC 0x5402 mgslpc_info drivers/char/pcmcia/synclink_cs.c -TTY_LDISC_MAGIC 0x5403 tty_ldisc include/linux/tty_ldisc.h -USB_SERIAL_MAGIC 0x6702 usb_serial drivers/usb/serial/usb-serial.h -FULL_DUPLEX_MAGIC 0x6969 drivers/net/ethernet/dec/tulip/de2104x.c -USB_BLUETOOTH_MAGIC 0x6d02 usb_bluetooth drivers/usb/class/bluetty.c -RFCOMM_TTY_MAGIC 0x6d02 net/bluetooth/rfcomm/tty.c -USB_SERIAL_PORT_MAGIC 0x7301 usb_serial_port drivers/usb/serial/usb-serial.h -CG_MAGIC 0x00090255 ufs_cylinder_group include/linux/ufs_fs.h -RPORT_MAGIC 0x00525001 r_port drivers/char/rocket_int.h -LSEMAGIC 0x05091998 lse drivers/fc4/fc.c -GDTIOCTL_MAGIC 0x06030f07 gdth_iowr_str drivers/scsi/gdth_ioctl.h -RIEBL_MAGIC 0x09051990 drivers/net/atarilance.c -NBD_REQUEST_MAGIC 0x12560953 nbd_request include/linux/nbd.h -RED_MAGIC2 0x170fc2a5 (any) mm/slab.c -BAYCOM_MAGIC 0x19730510 baycom_state drivers/net/baycom_epp.c -ISDN_X25IFACE_MAGIC 0x1e75a2b9 isdn_x25iface_proto_data - drivers/isdn/isdn_x25iface.h -ECP_MAGIC 0x21504345 cdkecpsig include/linux/cdk.h -LSOMAGIC 0x27091997 lso drivers/fc4/fc.c -LSMAGIC 0x2a3b4d2a ls drivers/fc4/fc.c -WANPIPE_MAGIC 0x414C4453 sdla_{dump,exec} include/linux/wanpipe.h -CS_CARD_MAGIC 0x43525553 cs_card sound/oss/cs46xx.c -LABELCL_MAGIC 0x4857434c labelcl_info_s include/asm/ia64/sn/labelcl.h -ISDN_ASYNC_MAGIC 0x49344C01 modem_info include/linux/isdn.h -CTC_ASYNC_MAGIC 0x49344C01 ctc_tty_info drivers/s390/net/ctctty.c -ISDN_NET_MAGIC 0x49344C02 isdn_net_local_s drivers/isdn/i4l/isdn_net_lib.h -SAVEKMSG_MAGIC2 0x4B4D5347 savekmsg arch/*/amiga/config.c -CS_STATE_MAGIC 0x4c4f4749 cs_state sound/oss/cs46xx.c -SLAB_C_MAGIC 0x4f17a36d kmem_cache mm/slab.c -COW_MAGIC 0x4f4f4f4d cow_header_v1 arch/um/drivers/ubd_user.c -I810_CARD_MAGIC 0x5072696E i810_card sound/oss/i810_audio.c -TRIDENT_CARD_MAGIC 0x5072696E trident_card sound/oss/trident.c -ROUTER_MAGIC 0x524d4157 wan_device [in wanrouter.h pre 3.9] -SAVEKMSG_MAGIC1 0x53415645 savekmsg arch/*/amiga/config.c -GDA_MAGIC 0x58464552 gda arch/mips/include/asm/sn/gda.h -RED_MAGIC1 0x5a2cf071 (any) mm/slab.c -EEPROM_MAGIC_VALUE 0x5ab478d2 lanai_dev drivers/atm/lanai.c -HDLCDRV_MAGIC 0x5ac6e778 hdlcdrv_state include/linux/hdlcdrv.h -PCXX_MAGIC 0x5c6df104 channel drivers/char/pcxx.h -KV_MAGIC 0x5f4b565f kernel_vars_s arch/mips/include/asm/sn/klkernvars.h -I810_STATE_MAGIC 0x63657373 i810_state sound/oss/i810_audio.c -TRIDENT_STATE_MAGIC 0x63657373 trient_state sound/oss/trident.c -M3_CARD_MAGIC 0x646e6f50 m3_card sound/oss/maestro3.c -FW_HEADER_MAGIC 0x65726F66 fw_header drivers/atm/fore200e.h -SLOT_MAGIC 0x67267321 slot drivers/hotplug/cpqphp.h -SLOT_MAGIC 0x67267322 slot drivers/hotplug/acpiphp.h -LO_MAGIC 0x68797548 nbd_device include/linux/nbd.h -OPROFILE_MAGIC 0x6f70726f super_block drivers/oprofile/oprofilefs.h -M3_STATE_MAGIC 0x734d724d m3_state sound/oss/maestro3.c -VMALLOC_MAGIC 0x87654320 snd_alloc_track sound/core/memory.c -KMALLOC_MAGIC 0x87654321 snd_alloc_track sound/core/memory.c -PWC_MAGIC 0x89DC10AB pwc_device drivers/usb/media/pwc.h -NBD_REPLY_MAGIC 0x96744668 nbd_reply include/linux/nbd.h -ENI155_MAGIC 0xa54b872d midway_eprom drivers/atm/eni.h -CODA_MAGIC 0xC0DAC0DA coda_file_info fs/coda/coda_fs_i.h -DPMEM_MAGIC 0xc0ffee11 gdt_pci_sram drivers/scsi/gdth.h -YAM_MAGIC 0xF10A7654 yam_port drivers/net/hamradio/yam.c -CCB_MAGIC 0xf2691ad2 ccb drivers/scsi/ncr53c8xx.c -QUEUE_MAGIC_FREE 0xf7e1c9a3 queue_entry drivers/scsi/arm/queue.c -QUEUE_MAGIC_USED 0xf7e1cc33 queue_entry drivers/scsi/arm/queue.c -HTB_CMAGIC 0xFEFAFEF1 htb_class net/sched/sch_htb.c -NMI_MAGIC 0x48414d4d455201 nmi_s arch/mips/include/asm/sn/nmi.h +===================== ================ ======================== ========================================== +Magic Name Number Structure File +===================== ================ ======================== ========================================== +PG_MAGIC 'P' pg_{read,write}_hdr ``include/linux/pg.h`` +CMAGIC 0x0111 user ``include/linux/a.out.h`` +MKISS_DRIVER_MAGIC 0x04bf mkiss_channel ``drivers/net/mkiss.h`` +HDLC_MAGIC 0x239e n_hdlc ``drivers/char/n_hdlc.c`` +APM_BIOS_MAGIC 0x4101 apm_user ``arch/x86/kernel/apm_32.c`` +CYCLADES_MAGIC 0x4359 cyclades_port ``include/linux/cyclades.h`` +DB_MAGIC 0x4442 fc_info ``drivers/net/iph5526_novram.c`` +DL_MAGIC 0x444d fc_info ``drivers/net/iph5526_novram.c`` +FASYNC_MAGIC 0x4601 fasync_struct ``include/linux/fs.h`` +FF_MAGIC 0x4646 fc_info ``drivers/net/iph5526_novram.c`` +ISICOM_MAGIC 0x4d54 isi_port ``include/linux/isicom.h`` +PTY_MAGIC 0x5001 ``drivers/char/pty.c`` +PPP_MAGIC 0x5002 ppp ``include/linux/if_pppvar.h`` +SERIAL_MAGIC 0x5301 async_struct ``include/linux/serial.h`` +SSTATE_MAGIC 0x5302 serial_state ``include/linux/serial.h`` +SLIP_MAGIC 0x5302 slip ``drivers/net/slip.h`` +STRIP_MAGIC 0x5303 strip ``drivers/net/strip.c`` +X25_ASY_MAGIC 0x5303 x25_asy ``drivers/net/x25_asy.h`` +SIXPACK_MAGIC 0x5304 sixpack ``drivers/net/hamradio/6pack.h`` +AX25_MAGIC 0x5316 ax_disp ``drivers/net/mkiss.h`` +TTY_MAGIC 0x5401 tty_struct ``include/linux/tty.h`` +MGSL_MAGIC 0x5401 mgsl_info ``drivers/char/synclink.c`` +TTY_DRIVER_MAGIC 0x5402 tty_driver ``include/linux/tty_driver.h`` +MGSLPC_MAGIC 0x5402 mgslpc_info ``drivers/char/pcmcia/synclink_cs.c`` +TTY_LDISC_MAGIC 0x5403 tty_ldisc ``include/linux/tty_ldisc.h`` +USB_SERIAL_MAGIC 0x6702 usb_serial ``drivers/usb/serial/usb-serial.h`` +FULL_DUPLEX_MAGIC 0x6969 ``drivers/net/ethernet/dec/tulip/de2104x.c`` +USB_BLUETOOTH_MAGIC 0x6d02 usb_bluetooth ``drivers/usb/class/bluetty.c`` +RFCOMM_TTY_MAGIC 0x6d02 ``net/bluetooth/rfcomm/tty.c`` +USB_SERIAL_PORT_MAGIC 0x7301 usb_serial_port ``drivers/usb/serial/usb-serial.h`` +CG_MAGIC 0x00090255 ufs_cylinder_group ``include/linux/ufs_fs.h`` +RPORT_MAGIC 0x00525001 r_port ``drivers/char/rocket_int.h`` +LSEMAGIC 0x05091998 lse ``drivers/fc4/fc.c`` +GDTIOCTL_MAGIC 0x06030f07 gdth_iowr_str ``drivers/scsi/gdth_ioctl.h`` +RIEBL_MAGIC 0x09051990 ``drivers/net/atarilance.c`` +NBD_REQUEST_MAGIC 0x12560953 nbd_request ``include/linux/nbd.h`` +RED_MAGIC2 0x170fc2a5 (any) ``mm/slab.c`` +BAYCOM_MAGIC 0x19730510 baycom_state ``drivers/net/baycom_epp.c`` +ISDN_X25IFACE_MAGIC 0x1e75a2b9 isdn_x25iface_proto_data ``drivers/isdn/isdn_x25iface.h`` +ECP_MAGIC 0x21504345 cdkecpsig ``include/linux/cdk.h`` +LSOMAGIC 0x27091997 lso ``drivers/fc4/fc.c`` +LSMAGIC 0x2a3b4d2a ls ``drivers/fc4/fc.c`` +WANPIPE_MAGIC 0x414C4453 sdla_{dump,exec} ``include/linux/wanpipe.h`` +CS_CARD_MAGIC 0x43525553 cs_card ``sound/oss/cs46xx.c`` +LABELCL_MAGIC 0x4857434c labelcl_info_s ``include/asm/ia64/sn/labelcl.h`` +ISDN_ASYNC_MAGIC 0x49344C01 modem_info ``include/linux/isdn.h`` +CTC_ASYNC_MAGIC 0x49344C01 ctc_tty_info ``drivers/s390/net/ctctty.c`` +ISDN_NET_MAGIC 0x49344C02 isdn_net_local_s ``drivers/isdn/i4l/isdn_net_lib.h`` +SAVEKMSG_MAGIC2 0x4B4D5347 savekmsg ``arch/*/amiga/config.c`` +CS_STATE_MAGIC 0x4c4f4749 cs_state ``sound/oss/cs46xx.c`` +SLAB_C_MAGIC 0x4f17a36d kmem_cache ``mm/slab.c`` +COW_MAGIC 0x4f4f4f4d cow_header_v1 ``arch/um/drivers/ubd_user.c`` +I810_CARD_MAGIC 0x5072696E i810_card ``sound/oss/i810_audio.c`` +TRIDENT_CARD_MAGIC 0x5072696E trident_card ``sound/oss/trident.c`` +ROUTER_MAGIC 0x524d4157 wan_device [in ``wanrouter.h`` pre 3.9] +SAVEKMSG_MAGIC1 0x53415645 savekmsg ``arch/*/amiga/config.c`` +GDA_MAGIC 0x58464552 gda ``arch/mips/include/asm/sn/gda.h`` +RED_MAGIC1 0x5a2cf071 (any) ``mm/slab.c`` +EEPROM_MAGIC_VALUE 0x5ab478d2 lanai_dev ``drivers/atm/lanai.c`` +HDLCDRV_MAGIC 0x5ac6e778 hdlcdrv_state ``include/linux/hdlcdrv.h`` +PCXX_MAGIC 0x5c6df104 channel ``drivers/char/pcxx.h`` +KV_MAGIC 0x5f4b565f kernel_vars_s ``arch/mips/include/asm/sn/klkernvars.h`` +I810_STATE_MAGIC 0x63657373 i810_state ``sound/oss/i810_audio.c`` +TRIDENT_STATE_MAGIC 0x63657373 trient_state ``sound/oss/trident.c`` +M3_CARD_MAGIC 0x646e6f50 m3_card ``sound/oss/maestro3.c`` +FW_HEADER_MAGIC 0x65726F66 fw_header ``drivers/atm/fore200e.h`` +SLOT_MAGIC 0x67267321 slot ``drivers/hotplug/cpqphp.h`` +SLOT_MAGIC 0x67267322 slot ``drivers/hotplug/acpiphp.h`` +LO_MAGIC 0x68797548 nbd_device ``include/linux/nbd.h`` +OPROFILE_MAGIC 0x6f70726f super_block ``drivers/oprofile/oprofilefs.h`` +M3_STATE_MAGIC 0x734d724d m3_state ``sound/oss/maestro3.c`` +VMALLOC_MAGIC 0x87654320 snd_alloc_track ``sound/core/memory.c`` +KMALLOC_MAGIC 0x87654321 snd_alloc_track ``sound/core/memory.c`` +PWC_MAGIC 0x89DC10AB pwc_device ``drivers/usb/media/pwc.h`` +NBD_REPLY_MAGIC 0x96744668 nbd_reply ``include/linux/nbd.h`` +ENI155_MAGIC 0xa54b872d midway_eprom ``drivers/atm/eni.h`` +CODA_MAGIC 0xC0DAC0DA coda_file_info ``fs/coda/coda_fs_i.h`` +DPMEM_MAGIC 0xc0ffee11 gdt_pci_sram ``drivers/scsi/gdth.h`` +YAM_MAGIC 0xF10A7654 yam_port ``drivers/net/hamradio/yam.c`` +CCB_MAGIC 0xf2691ad2 ccb ``drivers/scsi/ncr53c8xx.c`` +QUEUE_MAGIC_FREE 0xf7e1c9a3 queue_entry ``drivers/scsi/arm/queue.c`` +QUEUE_MAGIC_USED 0xf7e1cc33 queue_entry ``drivers/scsi/arm/queue.c`` +HTB_CMAGIC 0xFEFAFEF1 htb_class ``net/sched/sch_htb.c`` +NMI_MAGIC 0x48414d4d455201 nmi_s ``arch/mips/include/asm/sn/nmi.h`` +===================== ================ ======================== ========================================== Note that there are also defined special per-driver magic numbers in sound -memory management. See include/sound/sndmagic.h for complete list of them. Many +memory management. See ``include/sound/sndmagic.h`` for complete list of them. Many OSS sound drivers have their magic numbers constructed from the soundcard PCI ID - these are not listed here as well. IrDA subsystem also uses large number of own magic numbers, see -include/net/irda/irda.h for a complete list of them. +``include/net/irda/irda.h`` for a complete list of them. HFS is another larger user of magic numbers - you can find them in -fs/hfs/hfs.h. +``fs/hfs/hfs.h``. -- cgit v1.2.3 From aeb04e52f1145308c013b2ec7ea660309857a1f1 Mon Sep 17 00:00:00 2001 From: Mauro Carvalho Chehab Date: Fri, 23 Sep 2016 13:22:41 -0300 Subject: Documentation/md.txt: Convert to ReST markup - add a title for the document; - convert some parameters to tables; - use quote blocks where needed; - use monotonic fonts for parameters; - adjust whitespaces and blank lines; - add it to the user's book. Signed-off-by: Mauro Carvalho Chehab --- Documentation/md.txt | 528 +++++++++++++++++++++++++++++++-------------------- 1 file changed, 321 insertions(+), 207 deletions(-) diff --git a/Documentation/md.txt b/Documentation/md.txt index d6e2fcf27337..e449fb5f277c 100644 --- a/Documentation/md.txt +++ b/Documentation/md.txt @@ -1,42 +1,77 @@ -Tools that manage md devices can be found at - http://www.kernel.org/pub/linux/utils/raid/ - +RAID arrays +=========== Boot time assembly of RAID arrays --------------------------------- +Tools that manage md devices can be found at + http://www.kernel.org/pub/linux/utils/raid/ + + You can boot with your md device with the following kernel command lines: -for old raid arrays without persistent superblocks: +for old raid arrays without persistent superblocks:: + md=,,,,dev0,dev1,...,devn -for raid arrays with persistent superblocks +for raid arrays with persistent superblocks:: + md=,dev0,dev1,...,devn -or, to assemble a partitionable array: + +or, to assemble a partitionable array:: + md=d,dev0,dev1,...,devn - -md device no. = the number of the md device ... - 0 means md0, - 1 md1, - 2 md2, - 3 md3, - 4 md4 - -raid level = -1 linear mode - 0 striped mode - other modes are only supported with persistent super blocks - -chunk size factor = (raid-0 and raid-1 only) - Set the chunk size as 4k << n. - -fault level = totally ignored - -dev0-devn: e.g. /dev/hda1,/dev/hdc1,/dev/sda1,/dev/sdb1 - -A possible loadlin line (Harald Hoyer ) looks like this: - -e:\loadlin\loadlin e:\zimage root=/dev/md0 md=0,0,4,0,/dev/hdb2,/dev/hdc3 ro + +``md device no.`` ++++++++++++++++++ + +The number of the md device + +================= ========= +``md device no.`` device +================= ========= + 0 md0 + 1 md1 + 2 md2 + 3 md3 + 4 md4 +================= ========= + +``raid level`` +++++++++++++++ + +level of the RAID array + +=============== ============= +``raid level`` level +=============== ============= +-1 linear mode +0 striped mode +=============== ============= + +other modes are only supported with persistent super blocks + +``chunk size factor`` ++++++++++++++++++++++ + +(raid-0 and raid-1 only) + +Set the chunk size as 4k << n. + +``fault level`` ++++++++++++++++ + +Totally ignored + +``dev0`` to ``devn`` +++++++++++++++++++++ + +e.g. ``/dev/hda1``, ``/dev/hdc1``, ``/dev/sda1``, ``/dev/sdb1`` + +A possible loadlin line (Harald Hoyer ) looks like this:: + + e:\loadlin\loadlin e:\zimage root=/dev/md0 md=0,0,4,0,/dev/hdb2,/dev/hdc3 ro Boot time autodetection of RAID arrays @@ -45,10 +80,10 @@ Boot time autodetection of RAID arrays When md is compiled into the kernel (not as module), partitions of type 0xfd are scanned and automatically assembled into RAID arrays. This autodetection may be suppressed with the kernel parameter -"raid=noautodetect". As of kernel 2.6.9, only drives with a type 0 +``raid=noautodetect``. As of kernel 2.6.9, only drives with a type 0 superblock can be autodetected and run at boot time. -The kernel parameter "raid=partitionable" (or "raid=part") means +The kernel parameter ``raid=partitionable`` (or ``raid=part``) means that all auto-detected arrays are assembled as partitionable. Boot time assembly of degraded/dirty arrays @@ -56,22 +91,23 @@ Boot time assembly of degraded/dirty arrays If a raid5 or raid6 array is both dirty and degraded, it could have undetectable data corruption. This is because the fact that it is -'dirty' means that the parity cannot be trusted, and the fact that it +``dirty`` means that the parity cannot be trusted, and the fact that it is degraded means that some datablocks are missing and cannot reliably be reconstructed (due to no parity). For this reason, md will normally refuse to start such an array. This requires the sysadmin to take action to explicitly start the array -despite possible corruption. This is normally done with +despite possible corruption. This is normally done with:: + mdadm --assemble --force .... This option is not really available if the array has the root filesystem on it. In order to support this booting from such an -array, md supports a module parameter "start_dirty_degraded" which, +array, md supports a module parameter ``start_dirty_degraded`` which, when set to 1, bypassed the checks and will allows dirty degraded arrays to be started. -So, to boot with a root filesystem of a dirty degraded raid[56], use +So, to boot with a root filesystem of a dirty degraded raid 5 or 6, use:: md-mod.start_dirty_degraded=1 @@ -80,30 +116,30 @@ Superblock formats ------------------ The md driver can support a variety of different superblock formats. -Currently, it supports superblock formats "0.90.0" and the "md-1" format +Currently, it supports superblock formats ``0.90.0`` and the ``md-1`` format introduced in the 2.5 development series. The kernel will autodetect which format superblock is being used. -Superblock format '0' is treated differently to others for legacy +Superblock format ``0`` is treated differently to others for legacy reasons - it is the original superblock format. General Rules - apply for all superblock formats ------------------------------------------------ -An array is 'created' by writing appropriate superblocks to all +An array is ``created`` by writing appropriate superblocks to all devices. -It is 'assembled' by associating each of these devices with an +It is ``assembled`` by associating each of these devices with an particular md virtual device. Once it is completely assembled, it can be accessed. An array should be created by a user-space tool. This will write superblocks to all devices. It will usually mark the array as -'unclean', or with some devices missing so that the kernel md driver -can create appropriate redundancy (copying in raid1, parity -calculation in raid4/5). +``unclean``, or with some devices missing so that the kernel md driver +can create appropriate redundancy (copying in raid 1, parity +calculation in raid 4/5). When an array is assembled, it is first initialized with the SET_ARRAY_INFO ioctl. This contains, in particular, a major and minor @@ -126,13 +162,12 @@ Devices that have failed or are not yet active can be detached from an array using HOT_REMOVE_DISK. -Specific Rules that apply to format-0 super block arrays, and - arrays with no superblock (non-persistent). -------------------------------------------------------------- +Specific Rules that apply to format-0 super block arrays, and arrays with no superblock (non-persistent) +-------------------------------------------------------------------------------------------------------- -An array can be 'created' by describing the array (level, chunksize -etc) in a SET_ARRAY_INFO ioctl. This must have major_version==0 and -raid_disks != 0. +An array can be ``created`` by describing the array (level, chunksize +etc) in a SET_ARRAY_INFO ioctl. This must have ``major_version==0`` and +``raid_disks != 0``. Then uninitialized devices can be added with ADD_NEW_DISK. The structure passed to ADD_NEW_DISK must specify the state of the device @@ -142,24 +177,26 @@ Once started with RUN_ARRAY, uninitialized spares can be added with HOT_ADD_DISK. - MD devices in sysfs ------------------- -md devices appear in sysfs (/sys) as regular block devices, -e.g. + +md devices appear in sysfs (``/sys``) as regular block devices, +e.g.:: + /sys/block/md0 -Each 'md' device will contain a subdirectory called 'md' which +Each ``md`` device will contain a subdirectory called ``md`` which contains further md-specific information about the device. All md devices contain: + level - a text file indicating the 'raid level'. e.g. raid0, raid1, + a text file indicating the ``raid level``. e.g. raid0, raid1, raid5, linear, multipath, faulty. If no raid level has been set yet (array is still being assembled), the value will reflect whatever has been written to it, which may be a name like the above, or may be a number - such as '0', '5', etc. + such as ``0``, ``5``, etc. raid_disks a text file with a simple number indicating the number of devices @@ -172,10 +209,10 @@ All md devices contain: A change to this attribute will not be permitted if it would reduce the size of the array. To reduce the number of drives in an e.g. raid5, the array size must first be reduced by - setting the 'array_size' attribute. + setting the ``array_size`` attribute. chunk_size - This is the size in bytes for 'chunks' and is only relevant to + This is the size in bytes for ``chunks`` and is only relevant to raid levels that involve striping (0,4,5,6,10). The address space of the array is conceptually divided into chunks and consecutive chunks are striped onto neighbouring devices. @@ -183,7 +220,7 @@ All md devices contain: of 2. This can only be set while assembling an array layout - The "layout" for the array for the particular level. This is + The ``layout`` for the array for the particular level. This is simply a number that is interpretted differently by different levels. It can be written while assembling an array. @@ -193,22 +230,24 @@ All md devices contain: devices. Writing a number (in Kilobytes) which is less than the available size will set the size. Any reconfiguration of the array (e.g. adding devices) will not cause the size to change. - Writing the word 'default' will cause the effective size of the + Writing the word ``default`` will cause the effective size of the array to be whatever size is actually available based on - 'level', 'chunk_size' and 'component_size'. + ``level``, ``chunk_size`` and ``component_size``. This can be used to reduce the size of the array before reducing the number of devices in a raid4/5/6, or to support external metadata formats which mandate such clipping. reshape_position - This is either "none" or a sector number within the devices of - the array where "reshape" is up to. If this is set, the three + This is either ``none`` or a sector number within the devices of + the array where ``reshape`` is up to. If this is set, the three attributes mentioned above (raid_disks, chunk_size, layout) can potentially have 2 values, an old and a new value. If these - values differ, reading the attribute returns + values differ, reading the attribute returns:: + new (old) - and writing will effect the 'new' value, leaving the 'old' + + and writing will effect the ``new`` value, leaving the ``old`` unchanged. component_size @@ -223,9 +262,9 @@ All md devices contain: metadata_version This indicates the format that is being used to record metadata about the array. It can be 0.90 (traditional format), 1.0, 1.1, - 1.2 (newer format in varying locations) or "none" indicating that + 1.2 (newer format in varying locations) or ``none`` indicating that the kernel isn't managing metadata at all. - Alternately it can be "external:" followed by a string which + Alternately it can be ``external:`` followed by a string which is set by user-space. This indicates that metadata is managed by a user-space program. Any device failure or other event that requires a metadata update will cause array activity to be @@ -233,9 +272,9 @@ All md devices contain: resync_start The point at which resync should start. If no resync is needed, - this will be a very large number (or 'none' since 2.6.30-rc1). At + this will be a very large number (or ``none`` since 2.6.30-rc1). At array creation it will default to 0, though starting the array as - 'clean' will set it much larger. + ``clean`` will set it much larger. new_dev This file can be written but not read. The value written should @@ -246,10 +285,10 @@ All md devices contain: safe_mode_delay When an md array has seen no write requests for a certain period - of time, it will be marked as 'clean'. When another write - request arrives, the array is marked as 'dirty' before the write - commences. This is known as 'safe_mode'. - The 'certain period' is controlled by this file which stores the + of time, it will be marked as ``clean``. When another write + request arrives, the array is marked as ``dirty`` before the write + commences. This is known as ``safe_mode``. + The ``certain period`` is controlled by this file which stores the period as a number of seconds. The default is 200msec (0.200). Writing a value of 0 disables safemode. @@ -260,38 +299,50 @@ All md devices contain: cannot be explicitly set, and some transitions are not allowed. Select/poll works on this file. All changes except between - active_idle and active (which can be frequent and are not - very interesting) are notified. active->active_idle is - reported if the metadata is externally managed. + Active_idle and active (which can be frequent and are not + very interesting) are notified. active->active_idle is + reported if the metadata is externally managed. clear No devices, no size, no level + Writing is equivalent to STOP_ARRAY ioctl + inactive May have some settings, but array is not active - all IO results in error + all IO results in error + When written, doesn't tear down array, but just stops it + suspended (not supported yet) All IO requests will block. The array can be reconfigured. + Writing this, if accepted, will block until array is quiessent + readonly no resync can happen. no superblocks get written. - write requests fail + + Write requests fail + read-auto - like readonly, but behaves like 'clean' on a write request. + like readonly, but behaves like ``clean`` on a write request. + + clean + no pending writes, but otherwise active. - clean - no pending writes, but otherwise active. When written to inactive array, starts without resync + If a write request arrives then - if metadata is known, mark 'dirty' and switch to 'active'. - if not known, block and switch to write-pending + if metadata is known, mark ``dirty`` and switch to ``active``. + if not known, block and switch to write-pending + If written to an active array that has pending writes, then fails. active fully active: IO and resync can be happening. When written to inactive array, starts with resync write-pending - clean, but writes are blocked waiting for 'active' to be written. + clean, but writes are blocked waiting for ``active`` to be written. active-idle like active, but no writes have been seen for a while (safe_mode_delay). @@ -299,57 +350,71 @@ All md devices contain: bitmap/location This indicates where the write-intent bitmap for the array is stored. - It can be one of "none", "file" or "[+-]N". - "file" may later be extended to "file:/file/name" - "[+-]N" means that many sectors from the start of the metadata. - This is replicated on all devices. For arrays with externally - managed metadata, the offset is from the beginning of the - device. + + It can be one of ``none``, ``file`` or ``[+-]N``. + ``file`` may later be extended to ``file:/file/name`` + ``[+-]N`` means that many sectors from the start of the metadata. + + This is replicated on all devices. For arrays with externally + managed metadata, the offset is from the beginning of the + device. + bitmap/chunksize The size, in bytes, of the chunk which will be represented by a single bit. For RAID456, it is a portion of an individual device. For RAID10, it is a portion of the array. For RAID1, it is both (they come to the same thing). + bitmap/time_base The time, in seconds, between looking for bits in the bitmap to be cleared. In the current implementation, a bit will be cleared - between 2 and 3 times "time_base" after all the covered blocks + between 2 and 3 times ``time_base`` after all the covered blocks are known to be in-sync. + bitmap/backlog When write-mostly devices are active in a RAID1, write requests to those devices proceed in the background - the filesystem (or other user of the device) does not have to wait for them. - 'backlog' sets a limit on the number of concurrent background + ``backlog`` sets a limit on the number of concurrent background writes. If there are more than this, new writes will by synchronous. + bitmap/metadata - This can be either 'internal' or 'external'. - 'internal' is the default and means the metadata for the bitmap - is stored in the first 256 bytes of the allocated space and is - managed by the md module. - 'external' means that bitmap metadata is managed externally to - the kernel (i.e. by some userspace program) + This can be either ``internal`` or ``external``. + + ``internal`` + is the default and means the metadata for the bitmap + is stored in the first 256 bytes of the allocated space and is + managed by the md module. + + ``external`` + means that bitmap metadata is managed externally to + the kernel (i.e. by some userspace program) + bitmap/can_clear - This is either 'true' or 'false'. If 'true', then bits in the + This is either ``true`` or ``false``. If ``true``, then bits in the bitmap will be cleared when the corresponding blocks are thought - to be in-sync. If 'false', bits will never be cleared. - This is automatically set to 'false' if a write happens on a + to be in-sync. If ``false``, bits will never be cleared. + This is automatically set to ``false`` if a write happens on a degraded array, or if the array becomes degraded during a write. When metadata is managed externally, it should be set to true once the array becomes non-degraded, and this fact has been recorded in the metadata. - - - -As component devices are added to an md array, they appear in the 'md' -directory as new directories named + + + +As component devices are added to an md array, they appear in the ``md`` +directory as new directories named:: + dev-XXX -where XXX is a name that the kernel knows for the device, e.g. hdb1. + +where ``XXX`` is a name that the kernel knows for the device, e.g. hdb1. Each directory contains: block - a symlink to the block device in /sys/block, e.g. + a symlink to the block device in /sys/block, e.g.:: + /sys/block/md0/md/dev-hdb1/block -> ../../../../block/hdb/hdb1 super @@ -358,51 +423,83 @@ Each directory contains: state A file recording the current state of the device in the array - which can be a comma separated list of - faulty - device has been kicked from active use due to - a detected fault, or it has unacknowledged bad - blocks - in_sync - device is a fully in-sync member of the array - writemostly - device will only be subject to read - requests if there are no other options. - This applies only to raid1 arrays. - blocked - device has failed, and the failure hasn't been - acknowledged yet by the metadata handler. - Writes that would write to this device if - it were not faulty are blocked. - spare - device is working, but not a full member. - This includes spares that are in the process - of being recovered to - write_error - device has ever seen a write error. - want_replacement - device is (mostly) working but probably - should be replaced, either due to errors or - due to user request. - replacement - device is a replacement for another active - device with same raid_disk. + which can be a comma separated list of: + + faulty + device has been kicked from active use due to + a detected fault, or it has unacknowledged bad + blocks + + in_sync + device is a fully in-sync member of the array + + writemostly + device will only be subject to read + requests if there are no other options. + + This applies only to raid1 arrays. + + blocked + device has failed, and the failure hasn't been + acknowledged yet by the metadata handler. + + Writes that would write to this device if + it were not faulty are blocked. + + spare + device is working, but not a full member. + + This includes spares that are in the process + of being recovered to + + write_error + device has ever seen a write error. + + want_replacement + device is (mostly) working but probably + should be replaced, either due to errors or + due to user request. + + replacement + device is a replacement for another active + device with same raid_disk. This list may grow in future. + This can be written to. - Writing "faulty" simulates a failure on the device. - Writing "remove" removes the device from the array. - Writing "writemostly" sets the writemostly flag. - Writing "-writemostly" clears the writemostly flag. - Writing "blocked" sets the "blocked" flag. - Writing "-blocked" clears the "blocked" flags and allows writes - to complete and possibly simulates an error. - Writing "in_sync" sets the in_sync flag. - Writing "write_error" sets writeerrorseen flag. - Writing "-write_error" clears writeerrorseen flag. - Writing "want_replacement" is allowed at any time except to a - replacement device or a spare. It sets the flag. - Writing "-want_replacement" is allowed at any time. It clears - the flag. - Writing "replacement" or "-replacement" is only allowed before - starting the array. It sets or clears the flag. - - - This file responds to select/poll. Any change to 'faulty' - or 'blocked' causes an event. + + Writing ``faulty`` simulates a failure on the device. + + Writing ``remove`` removes the device from the array. + + Writing ``writemostly`` sets the writemostly flag. + + Writing ``-writemostly`` clears the writemostly flag. + + Writing ``blocked`` sets the ``blocked`` flag. + + Writing ``-blocked`` clears the ``blocked`` flags and allows writes + to complete and possibly simulates an error. + + Writing ``in_sync`` sets the in_sync flag. + + Writing ``write_error`` sets writeerrorseen flag. + + Writing ``-write_error`` clears writeerrorseen flag. + + Writing ``want_replacement`` is allowed at any time except to a + replacement device or a spare. It sets the flag. + + Writing ``-want_replacement`` is allowed at any time. It clears + the flag. + + Writing ``replacement`` or ``-replacement`` is only allowed before + starting the array. It sets or clears the flag. + + + This file responds to select/poll. Any change to ``faulty`` + or ``blocked`` causes an event. errors An approximate count of read errors that have been detected on @@ -417,9 +514,9 @@ Each directory contains: slot This gives the role that the device has in the array. It will - either be 'none' if the device is not active in the array + either be ``none`` if the device is not active in the array (i.e. is a spare or has failed) or an integer less than the - 'raid_disks' number for the array indicating which position + ``raid_disks`` number for the array indicating which position it currently fills. This can only be set while assembling an array. A device for which this is set is assumed to be working. @@ -437,7 +534,7 @@ Each directory contains: written, it will be rejected. recovery_start - When the device is not 'in_sync', this records the number of + When the device is not ``in_sync``, this records the number of sectors from the start of the device which are known to be correct. This is normally zero, but during a recovery operation it will steadily increase, and if the recovery is @@ -447,21 +544,21 @@ Each directory contains: This can be set whenever the device is not an active member of the array, either before the array is activated, or before - the 'slot' is set. + the ``slot`` is set. + + Setting this to ``none`` is equivalent to setting ``in_sync``. + Setting to any other value also clears the ``in_sync`` flag. - Setting this to 'none' is equivalent to setting 'in_sync'. - Setting to any other value also clears the 'in_sync' flag. - bad_blocks This gives the list of all known bad blocks in the form of start address and length (in sectors respectively). If output is too big to fit in a page, it will be truncated. Writing - "sector length" to this file adds new acknowledged (i.e. + ``sector length`` to this file adds new acknowledged (i.e. recorded to disk safely) bad blocks. unacknowledged_bad_blocks This gives the list of known-but-not-yet-saved-to-disk bad - blocks in the same form of 'bad_blocks'. If output is too big + blocks in the same form of ``bad_blocks``. If output is too big to fit in a page, it will be truncated. Writing to this file adds bad blocks without acknowledging them. This is largely for testing. @@ -469,16 +566,18 @@ Each directory contains: An active md device will also contain an entry for each active device -in the array. These are named +in the array. These are named:: rdNN -where 'NN' is the position in the array, starting from 0. +where ``NN`` is the position in the array, starting from 0. So for a 3 drive array there will be rd0, rd1, rd2. -These are symbolic links to the appropriate 'dev-XXX' entry. -Thus, for example, +These are symbolic links to the appropriate ``dev-XXX`` entry. +Thus, for example:: + cat /sys/block/md*/md/rd*/state -will show 'in_sync' on every line. + +will show ``in_sync`` on every line. @@ -488,50 +587,62 @@ also have sync_action a text file that can be used to monitor and control the rebuild process. It contains one word which can be one of: - resync - redundancy is being recalculated after unclean - shutdown or creation - recover - a hot spare is being built to replace a - failed/missing device - idle - nothing is happening - check - A full check of redundancy was requested and is - happening. This reads all blocks and checks - them. A repair may also happen for some raid - levels. - repair - A full check and repair is happening. This is - similar to 'resync', but was requested by the - user, and the write-intent bitmap is NOT used to - optimise the process. + + resync + redundancy is being recalculated after unclean + shutdown or creation + + recover + a hot spare is being built to replace a + failed/missing device + + idle + nothing is happening + check + A full check of redundancy was requested and is + happening. This reads all blocks and checks + them. A repair may also happen for some raid + levels. + + repair + A full check and repair is happening. This is + similar to ``resync``, but was requested by the + user, and the write-intent bitmap is NOT used to + optimise the process. This file is writable, and each of the strings that could be read are meaningful for writing. - 'idle' will stop an active resync/recovery etc. There is no - guarantee that another resync/recovery may not be automatically - started again, though some event will be needed to trigger - this. - 'resync' or 'recovery' can be used to restart the - corresponding operation if it was stopped with 'idle'. - 'check' and 'repair' will start the appropriate process - providing the current state is 'idle'. + ``idle`` will stop an active resync/recovery etc. There is no + guarantee that another resync/recovery may not be automatically + started again, though some event will be needed to trigger + this. + + ``resync`` or ``recovery`` can be used to restart the + corresponding operation if it was stopped with ``idle``. + + ``check`` and ``repair`` will start the appropriate process + providing the current state is ``idle``. This file responds to select/poll. Any important change in the value triggers a poll event. Sometimes the value will briefly be - "recover" if a recovery seems to be needed, but cannot be - achieved. In that case, the transition to "recover" isn't + ``recover`` if a recovery seems to be needed, but cannot be + achieved. In that case, the transition to ``recover`` isn't notified, but the transition away is. degraded This contains a count of the number of devices by which the - arrays is degraded. So an optimal array will show '0'. A - single failed/missing drive will show '1', etc. + arrays is degraded. So an optimal array will show ``0``. A + single failed/missing drive will show ``1``, etc. + This file responds to select/poll, any increase or decrease in the count of missing devices will trigger an event. mismatch_count - When performing 'check' and 'repair', and possibly when - performing 'resync', md will count the number of errors that are - found. The count in 'mismatch_cnt' is the number of sectors - that were re-written, or (for 'check') would have been + When performing ``check`` and ``repair``, and possibly when + performing ``resync``, md will count the number of errors that are + found. The count in ``mismatch_cnt`` is the number of sectors + that were re-written, or (for ``check``) would have been re-written. As most raid levels work in units of pages rather than sectors, this may be larger than the number of actual errors by a factor of the number of sectors in a page. @@ -542,27 +653,30 @@ also have would need to check the corresponding blocks. Either individual numbers or start-end pairs can be written. Multiple numbers can be separated by a space. - Note that the numbers are 'bit' numbers, not 'block' numbers. + + Note that the numbers are ``bit`` numbers, not ``block`` numbers. They should be scaled by the bitmap_chunksize. - sync_speed_min - sync_speed_max - This are similar to /proc/sys/dev/raid/speed_limit_{min,max} + sync_speed_min, sync_speed_max + This are similar to ``/proc/sys/dev/raid/speed_limit_{min,max}`` however they only apply to the particular array. - If no value has been written to these, or if the word 'system' + + If no value has been written to these, or if the word ``system`` is written, then the system-wide value is used. If a value, in kibibytes-per-second is written, then it is used. + When the files are read, they show the currently active value - followed by "(local)" or "(system)" depending on whether it is + followed by ``(local)`` or ``(system)`` depending on whether it is a locally set or system-wide value. sync_completed This shows the number of sectors that have been completed of whatever the current sync_action is, followed by the number of sectors in total that could need to be processed. The two - numbers are separated by a '/' thus effectively showing one + numbers are separated by a ``/`` thus effectively showing one value, a fraction of the process that is complete. - A 'select' on this attribute will return when resync completes, + + A ``select`` on this attribute will return when resync completes, when it reaches the current sync_max (below) and possibly at other times. @@ -570,26 +684,24 @@ also have This shows the current actual speed, in K/sec, of the current sync_action. It is averaged over the last 30 seconds. - suspend_lo - suspend_hi + suspend_lo, suspend_hi The two values, given as numbers of sectors, indicate a range within the array where IO will be blocked. This is currently only supported for raid4/5/6. - sync_min - sync_max + sync_min, sync_max The two values, given as numbers of sectors, indicate a range - within the array where 'check'/'repair' will operate. Must be - a multiple of chunk_size. When it reaches "sync_max" it will + within the array where ``check``/``repair`` will operate. Must be + a multiple of chunk_size. When it reaches ``sync_max`` it will pause, rather than complete. - You can use 'select' or 'poll' on "sync_completed" to wait for + You can use ``select`` or ``poll`` on ``sync_completed`` to wait for that number to reach sync_max. Then you can either increase - "sync_max", or can write 'idle' to "sync_action". + ``sync_max``, or can write ``idle`` to ``sync_action``. - The value of 'max' for "sync_max" effectively disables the limit. + The value of ``max`` for ``sync_max`` effectively disables the limit. When a resync is active, the value can only ever be increased, never decreased. - The value of '0' is the minimum for "sync_min". + The value of ``0`` is the minimum for ``sync_min``. @@ -598,13 +710,15 @@ personality module that manages it. These are specific to the implementation of the module and could change substantially if the implementation changes. -These currently include +These currently include: stripe_cache_size (currently raid5 only) number of entries in the stripe cache. This is writable, but there are upper and lower limits (32768, 17). Default is 256. + strip_cache_active (currently raid5 only) number of active entries in the stripe cache + preread_bypass_threshold (currently raid5 only) number of times a stripe requiring preread will be bypassed by a stripe that does not require preread. For fairness defaults -- cgit v1.2.3 From 94e980cc45f2b21afceff0cb1866a1af32d20325 Mon Sep 17 00:00:00 2001 From: Mauro Carvalho Chehab Date: Fri, 23 Sep 2016 13:44:24 -0300 Subject: Documentation/module-signing.txt: convert to ReST markup - Fix identatio for the document title; - remove its index; - create a table for hash algorithm to be used; - use quote blocks where needed; - use monotonic fonts for parameters; - adjust whitespaces and blank lines; - Fix case on section titles; - add it to the user's book. Signed-off-by: Mauro Carvalho Chehab --- Documentation/admin-guide/module-signing.rst | 285 +++++++++++++++++++++++++++ Documentation/module-signing.txt | 279 -------------------------- 2 files changed, 285 insertions(+), 279 deletions(-) create mode 100644 Documentation/admin-guide/module-signing.rst delete mode 100644 Documentation/module-signing.txt diff --git a/Documentation/admin-guide/module-signing.rst b/Documentation/admin-guide/module-signing.rst new file mode 100644 index 000000000000..27e59498b487 --- /dev/null +++ b/Documentation/admin-guide/module-signing.rst @@ -0,0 +1,285 @@ +Kernel module signing facility +------------------------------ + +.. CONTENTS +.. +.. - Overview. +.. - Configuring module signing. +.. - Generating signing keys. +.. - Public keys in the kernel. +.. - Manually signing modules. +.. - Signed modules and stripping. +.. - Loading signed modules. +.. - Non-valid signatures and unsigned modules. +.. - Administering/protecting the private key. + + +======== +Overview +======== + +The kernel module signing facility cryptographically signs modules during +installation and then checks the signature upon loading the module. This +allows increased kernel security by disallowing the loading of unsigned modules +or modules signed with an invalid key. Module signing increases security by +making it harder to load a malicious module into the kernel. The module +signature checking is done by the kernel so that it is not necessary to have +trusted userspace bits. + +This facility uses X.509 ITU-T standard certificates to encode the public keys +involved. The signatures are not themselves encoded in any industrial standard +type. The facility currently only supports the RSA public key encryption +standard (though it is pluggable and permits others to be used). The possible +hash algorithms that can be used are SHA-1, SHA-224, SHA-256, SHA-384, and +SHA-512 (the algorithm is selected by data in the signature). + + +========================== +Configuring module signing +========================== + +The module signing facility is enabled by going to the +:menuselection:`Enable Loadable Module Support` section of +the kernel configuration and turning on:: + + CONFIG_MODULE_SIG "Module signature verification" + +This has a number of options available: + + (1) :menuselection:`Require modules to be validly signed` + (``CONFIG_MODULE_SIG_FORCE``) + + This specifies how the kernel should deal with a module that has a + signature for which the key is not known or a module that is unsigned. + + If this is off (ie. "permissive"), then modules for which the key is not + available and modules that are unsigned are permitted, but the kernel will + be marked as being tainted, and the concerned modules will be marked as + tainted, shown with the character 'E'. + + If this is on (ie. "restrictive"), only modules that have a valid + signature that can be verified by a public key in the kernel's possession + will be loaded. All other modules will generate an error. + + Irrespective of the setting here, if the module has a signature block that + cannot be parsed, it will be rejected out of hand. + + + (2) :menuselection:`Automatically sign all modules` + (``CONFIG_MODULE_SIG_ALL``) + + If this is on then modules will be automatically signed during the + modules_install phase of a build. If this is off, then the modules must + be signed manually using:: + + scripts/sign-file + + + (3) :menuselection:`Which hash algorithm should modules be signed with?` + + This presents a choice of which hash algorithm the installation phase will + sign the modules with: + + =============================== ========================================== + ``CONFIG_MODULE_SIG_SHA1`` :menuselection:`Sign modules with SHA-1` + ``CONFIG_MODULE_SIG_SHA224`` :menuselection:`Sign modules with SHA-224` + ``CONFIG_MODULE_SIG_SHA256`` :menuselection:`Sign modules with SHA-256` + ``CONFIG_MODULE_SIG_SHA384`` :menuselection:`Sign modules with SHA-384` + ``CONFIG_MODULE_SIG_SHA512`` :menuselection:`Sign modules with SHA-512` + =============================== ========================================== + + The algorithm selected here will also be built into the kernel (rather + than being a module) so that modules signed with that algorithm can have + their signatures checked without causing a dependency loop. + + + (4) :menuselection:`File name or PKCS#11 URI of module signing key` + (``CONFIG_MODULE_SIG_KEY``) + + Setting this option to something other than its default of + ``certs/signing_key.pem`` will disable the autogeneration of signing keys + and allow the kernel modules to be signed with a key of your choosing. + The string provided should identify a file containing both a private key + and its corresponding X.509 certificate in PEM form, or — on systems where + the OpenSSL ENGINE_pkcs11 is functional — a PKCS#11 URI as defined by + RFC7512. In the latter case, the PKCS#11 URI should reference both a + certificate and a private key. + + If the PEM file containing the private key is encrypted, or if the + PKCS#11 token requries a PIN, this can be provided at build time by + means of the ``KBUILD_SIGN_PIN`` variable. + + + (5) :menuselection:`Additional X.509 keys for default system keyring` + (``CONFIG_SYSTEM_TRUSTED_KEYS``) + + This option can be set to the filename of a PEM-encoded file containing + additional certificates which will be included in the system keyring by + default. + +Note that enabling module signing adds a dependency on the OpenSSL devel +packages to the kernel build processes for the tool that does the signing. + + +======================= +Generating signing keys +======================= + +Cryptographic keypairs are required to generate and check signatures. A +private key is used to generate a signature and the corresponding public key is +used to check it. The private key is only needed during the build, after which +it can be deleted or stored securely. The public key gets built into the +kernel so that it can be used to check the signatures as the modules are +loaded. + +Under normal conditions, when ``CONFIG_MODULE_SIG_KEY`` is unchanged from its +default, the kernel build will automatically generate a new keypair using +openssl if one does not exist in the file:: + + certs/signing_key.pem + +during the building of vmlinux (the public part of the key needs to be built +into vmlinux) using parameters in the:: + + certs/x509.genkey + +file (which is also generated if it does not already exist). + +It is strongly recommended that you provide your own x509.genkey file. + +Most notably, in the x509.genkey file, the req_distinguished_name section +should be altered from the default:: + + [ req_distinguished_name ] + #O = Unspecified company + CN = Build time autogenerated kernel key + #emailAddress = unspecified.user@unspecified.company + +The generated RSA key size can also be set with:: + + [ req ] + default_bits = 4096 + + +It is also possible to manually generate the key private/public files using the +x509.genkey key generation configuration file in the root node of the Linux +kernel sources tree and the openssl command. The following is an example to +generate the public/private key files:: + + openssl req -new -nodes -utf8 -sha256 -days 36500 -batch -x509 \ + -config x509.genkey -outform PEM -out kernel_key.pem \ + -keyout kernel_key.pem + +The full pathname for the resulting kernel_key.pem file can then be specified +in the ``CONFIG_MODULE_SIG_KEY`` option, and the certificate and key therein will +be used instead of an autogenerated keypair. + + +========================= +Public keys in the kernel +========================= + +The kernel contains a ring of public keys that can be viewed by root. They're +in a keyring called ".system_keyring" that can be seen by:: + + [root@deneb ~]# cat /proc/keys + ... + 223c7853 I------ 1 perm 1f030000 0 0 keyring .system_keyring: 1 + 302d2d52 I------ 1 perm 1f010000 0 0 asymmetri Fedora kernel signing key: d69a84e6bce3d216b979e9505b3e3ef9a7118079: X509.RSA a7118079 [] + ... + +Beyond the public key generated specifically for module signing, additional +trusted certificates can be provided in a PEM-encoded file referenced by the +``CONFIG_SYSTEM_TRUSTED_KEYS`` configuration option. + +Further, the architecture code may take public keys from a hardware store and +add those in also (e.g. from the UEFI key database). + +Finally, it is possible to add additional public keys by doing:: + + keyctl padd asymmetric "" [.system_keyring-ID] <[key-file] + +e.g.:: + + keyctl padd asymmetric "" 0x223c7853 Date: Fri, 23 Sep 2016 13:52:05 -0300 Subject: Documentation/mono.txt: convert to ReST markup - Fix document title; - use quote blocks where needed; - use .. note:: for notes; - use monotonic fonts for config options and file names; - adjust whitespaces and blank lines; - add it to the user's book. Signed-off-by: Mauro Carvalho Chehab --- Documentation/mono.txt | 44 +++++++++++++++++++++++--------------------- 1 file changed, 23 insertions(+), 21 deletions(-) diff --git a/Documentation/mono.txt b/Documentation/mono.txt index d01ac6052194..9a9744ca0cf3 100644 --- a/Documentation/mono.txt +++ b/Documentation/mono.txt @@ -1,5 +1,5 @@ - Mono(tm) Binary Kernel Support for Linux - ----------------------------------------- +Mono(tm) Binary Kernel Support for Linux +----------------------------------------- To configure Linux to automatically execute Mono-based .NET binaries (in the form of .exe files) without the need to use the mono CLR @@ -19,22 +19,22 @@ other program after you have done the following: http://www.go-mono.com/compiling.html Once the Mono CLR support has been installed, just check that - /usr/bin/mono (which could be located elsewhere, for example - /usr/local/bin/mono) is working. + ``/usr/bin/mono`` (which could be located elsewhere, for example + ``/usr/local/bin/mono``) is working. 2) You have to compile BINFMT_MISC either as a module or into - the kernel (CONFIG_BINFMT_MISC) and set it up properly. + the kernel (``CONFIG_BINFMT_MISC``) and set it up properly. If you choose to compile it as a module, you will have to insert it manually with modprobe/insmod, as kmod - cannot be easily supported with binfmt_misc. - Read the file 'binfmt_misc.txt' in this directory to know + cannot be easily supported with binfmt_misc. + Read the file ``binfmt_misc.txt`` in this directory to know more about the configuration process. -3) Add the following entries to /etc/rc.local or similar script - to be run at system startup: +3) Add the following entries to ``/etc/rc.local`` or similar script + to be run at system startup:: -# Insert BINFMT_MISC module into the kernel -if [ ! -e /proc/sys/fs/binfmt_misc/register ]; then + # Insert BINFMT_MISC module into the kernel + if [ ! -e /proc/sys/fs/binfmt_misc/register ]; then /sbin/modprobe binfmt_misc # Some distributions, like Fedora Core, perform # the following command automatically when the @@ -43,24 +43,26 @@ if [ ! -e /proc/sys/fs/binfmt_misc/register ]; then # Thus, it is possible that the following line # is not needed at all. mount -t binfmt_misc none /proc/sys/fs/binfmt_misc -fi + fi -# Register support for .NET CLR binaries -if [ -e /proc/sys/fs/binfmt_misc/register ]; then + # Register support for .NET CLR binaries + if [ -e /proc/sys/fs/binfmt_misc/register ]; then # Replace /usr/bin/mono with the correct pathname to # the Mono CLR runtime (usually /usr/local/bin/mono # when compiling from sources or CVS). echo ':CLR:M::MZ::/usr/bin/mono:' > /proc/sys/fs/binfmt_misc/register -else + else echo "No binfmt_misc support" exit 1 -fi + fi -4) Check that .exe binaries can be ran without the need of a - wrapper script, simply by launching the .exe file directly - from a command prompt, for example: +4) Check that ``.exe`` binaries can be ran without the need of a + wrapper script, simply by launching the ``.exe`` file directly + from a command prompt, for example:: /usr/bin/xsd.exe - NOTE: If this fails with a permission denied error, check - that the .exe file has execute permissions. + .. note:: + + If this fails with a permission denied error, check + that the ``.exe`` file has execute permissions. -- cgit v1.2.3 From 503c5bf9fa4622195bef0b46ebcc0ab6afeefed8 Mon Sep 17 00:00:00 2001 From: Mauro Carvalho Chehab Date: Fri, 23 Sep 2016 14:02:36 -0300 Subject: Documentation/java.txt: convert to ReST markup - Fix document title; - use quote blocks where needed; - use monotonic fonts for config options and file names; - adjust whitespaces and blank lines; - add it to the user's book. Signed-off-by: Mauro Carvalho Chehab --- Documentation/java.txt | 244 ++++++++++++++++++++++++++----------------------- 1 file changed, 129 insertions(+), 115 deletions(-) diff --git a/Documentation/java.txt b/Documentation/java.txt index 418020584ccc..ae33d959638c 100644 --- a/Documentation/java.txt +++ b/Documentation/java.txt @@ -1,5 +1,5 @@ - Java(tm) Binary Kernel Support for Linux v1.03 - ---------------------------------------------- +Java(tm) Binary Kernel Support for Linux v1.03 +---------------------------------------------- Linux beats them ALL! While all other OS's are TALKING about direct support of Java Binaries in the OS, Linux is doing it! @@ -19,70 +19,80 @@ other program after you have done the following: as the application itself). 2) You have to compile BINFMT_MISC either as a module or into - the kernel (CONFIG_BINFMT_MISC) and set it up properly. + the kernel (``CONFIG_BINFMT_MISC``) and set it up properly. If you choose to compile it as a module, you will have to insert it manually with modprobe/insmod, as kmod - cannot easily be supported with binfmt_misc. + cannot easily be supported with binfmt_misc. Read the file 'binfmt_misc.txt' in this directory to know more about the configuration process. 3) Add the following configuration items to binfmt_misc - (you should really have read binfmt_misc.txt now): - support for Java applications: + (you should really have read ``binfmt_misc.txt`` now): + support for Java applications:: + ':Java:M::\xca\xfe\xba\xbe::/usr/local/bin/javawrapper:' - support for executable Jar files: + + support for executable Jar files:: + ':ExecutableJAR:E::jar::/usr/local/bin/jarwrapper:' - support for Java Applets: + + support for Java Applets:: + ':Applet:E::html::/usr/bin/appletviewer:' - or the following, if you want to be more selective: + + or the following, if you want to be more selective:: + ':Applet:M:: in the first line - ('<' has to be the first character!) to let this work! + existing html-files to contain ```` in the first line + (``<`` has to be the first character!) to let this work! For the compiled Java programs you need a wrapper script like the following (this is because Java is broken in case of the filename handling), again fix the path names, both in the script and in the above given configuration string. - You, too, need the little program after the script. Compile like - gcc -O2 -o javaclassname javaclassname.c - and stick it to /usr/local/bin. + You, too, need the little program after the script. Compile like:: + + gcc -O2 -o javaclassname javaclassname.c + + and stick it to ``/usr/local/bin``. Both the javawrapper shellscript and the javaclassname program were supplied by Colin J. Watson . -====================== Cut here =================== -#!/bin/bash -# /usr/local/bin/javawrapper - the wrapper for binfmt_misc/java +Javawrapper shell script:: + + #!/bin/bash + # /usr/local/bin/javawrapper - the wrapper for binfmt_misc/java -if [ -z "$1" ]; then + if [ -z "$1" ]; then exec 1>&2 echo Usage: $0 class-file exit 1 -fi + fi -CLASS=$1 -FQCLASS=`/usr/local/bin/javaclassname $1` -FQCLASSN=`echo $FQCLASS | sed -e 's/^.*\.\([^.]*\)$/\1/'` -FQCLASSP=`echo $FQCLASS | sed -e 's-\.-/-g' -e 's-^[^/]*$--' -e 's-/[^/]*$--'` + CLASS=$1 + FQCLASS=`/usr/local/bin/javaclassname $1` + FQCLASSN=`echo $FQCLASS | sed -e 's/^.*\.\([^.]*\)$/\1/'` + FQCLASSP=`echo $FQCLASS | sed -e 's-\.-/-g' -e 's-^[^/]*$--' -e 's-/[^/]*$--'` -# for example: -# CLASS=Test.class -# FQCLASS=foo.bar.Test -# FQCLASSN=Test -# FQCLASSP=foo/bar + # for example: + # CLASS=Test.class + # FQCLASS=foo.bar.Test + # FQCLASSN=Test + # FQCLASSP=foo/bar -unset CLASSBASE + unset CLASSBASE -declare -i LINKLEVEL=0 + declare -i LINKLEVEL=0 -while :; do + while :; do if [ "`basename $CLASS .class`" == "$FQCLASSN" ]; then # See if this directory works straight off cd -L `dirname $CLASS` @@ -119,9 +129,9 @@ while :; do exit 1 fi CLASS=`ls --color=no -l $CLASS | sed -e 's/^.* \([^ ]*\)$/\1/'` -done + done -if [ -z "$CLASSBASE" ]; then + if [ -z "$CLASSBASE" ]; then if [ -z "$FQCLASSP" ]; then GOODNAME=$FQCLASSN.class else @@ -131,24 +141,23 @@ if [ -z "$CLASSBASE" ]; then echo $0: echo " $FQCLASS should be in a file called $GOODNAME" exit 1 -fi + fi -if ! echo $CLASSPATH | grep -q "^\(.*:\)*$CLASSBASE\(:.*\)*"; then + if ! echo $CLASSPATH | grep -q "^\(.*:\)*$CLASSBASE\(:.*\)*"; then # class is not in CLASSPATH, so prepend dir of class to CLASSPATH if [ -z "${CLASSPATH}" ] ; then export CLASSPATH=$CLASSBASE else export CLASSPATH=$CLASSBASE:$CLASSPATH fi -fi + fi -shift -/usr/bin/java $FQCLASS "$@" -====================== Cut here =================== + shift + /usr/bin/java $FQCLASS "$@" +javaclassname.c:: -====================== Cut here =================== -/* javaclassname.c + /* javaclassname.c * * Extracts the class name from a Java class file; intended for use in a Java * wrapper of the type supported by the binfmt_misc option in the Linux kernel. @@ -170,57 +179,57 @@ shift * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA */ -#include -#include -#include -#include - -/* From Sun's Java VM Specification, as tag entries in the constant pool. */ - -#define CP_UTF8 1 -#define CP_INTEGER 3 -#define CP_FLOAT 4 -#define CP_LONG 5 -#define CP_DOUBLE 6 -#define CP_CLASS 7 -#define CP_STRING 8 -#define CP_FIELDREF 9 -#define CP_METHODREF 10 -#define CP_INTERFACEMETHODREF 11 -#define CP_NAMEANDTYPE 12 -#define CP_METHODHANDLE 15 -#define CP_METHODTYPE 16 -#define CP_INVOKEDYNAMIC 18 - -/* Define some commonly used error messages */ - -#define seek_error() error("%s: Cannot seek\n", program) -#define corrupt_error() error("%s: Class file corrupt\n", program) -#define eof_error() error("%s: Unexpected end of file\n", program) -#define utf8_error() error("%s: Only ASCII 1-255 supported\n", program); - -char *program; - -long *pool; - -u_int8_t read_8(FILE *classfile); -u_int16_t read_16(FILE *classfile); -void skip_constant(FILE *classfile, u_int16_t *cur); -void error(const char *format, ...); -int main(int argc, char **argv); - -/* Reads in an unsigned 8-bit integer. */ -u_int8_t read_8(FILE *classfile) -{ + #include + #include + #include + #include + + /* From Sun's Java VM Specification, as tag entries in the constant pool. */ + + #define CP_UTF8 1 + #define CP_INTEGER 3 + #define CP_FLOAT 4 + #define CP_LONG 5 + #define CP_DOUBLE 6 + #define CP_CLASS 7 + #define CP_STRING 8 + #define CP_FIELDREF 9 + #define CP_METHODREF 10 + #define CP_INTERFACEMETHODREF 11 + #define CP_NAMEANDTYPE 12 + #define CP_METHODHANDLE 15 + #define CP_METHODTYPE 16 + #define CP_INVOKEDYNAMIC 18 + + /* Define some commonly used error messages */ + + #define seek_error() error("%s: Cannot seek\n", program) + #define corrupt_error() error("%s: Class file corrupt\n", program) + #define eof_error() error("%s: Unexpected end of file\n", program) + #define utf8_error() error("%s: Only ASCII 1-255 supported\n", program); + + char *program; + + long *pool; + + u_int8_t read_8(FILE *classfile); + u_int16_t read_16(FILE *classfile); + void skip_constant(FILE *classfile, u_int16_t *cur); + void error(const char *format, ...); + int main(int argc, char **argv); + + /* Reads in an unsigned 8-bit integer. */ + u_int8_t read_8(FILE *classfile) + { int b = fgetc(classfile); if(b == EOF) eof_error(); return (u_int8_t)b; -} + } -/* Reads in an unsigned 16-bit integer. */ -u_int16_t read_16(FILE *classfile) -{ + /* Reads in an unsigned 16-bit integer. */ + u_int16_t read_16(FILE *classfile) + { int b1, b2; b1 = fgetc(classfile); if(b1 == EOF) @@ -229,11 +238,11 @@ u_int16_t read_16(FILE *classfile) if(b2 == EOF) eof_error(); return (u_int16_t)((b1 << 8) | b2); -} + } -/* Reads in a value from the constant pool. */ -void skip_constant(FILE *classfile, u_int16_t *cur) -{ + /* Reads in a value from the constant pool. */ + void skip_constant(FILE *classfile, u_int16_t *cur) + { u_int16_t len; int seekerr = 1; pool[*cur] = ftell(classfile); @@ -270,19 +279,19 @@ void skip_constant(FILE *classfile, u_int16_t *cur) } if(seekerr) seek_error(); -} + } -void error(const char *format, ...) -{ + void error(const char *format, ...) + { va_list ap; va_start(ap, format); vfprintf(stderr, format, ap); va_end(ap); exit(1); -} + } -int main(int argc, char **argv) -{ + int main(int argc, char **argv) + { FILE *classfile; u_int16_t cp_count, i, this_class, classinfo_ptr; u_int8_t length; @@ -349,19 +358,19 @@ int main(int argc, char **argv) free(pool); fclose(classfile); return 0; -} -====================== Cut here =================== + } +jarwrapper:: -====================== Cut here =================== -#!/bin/bash -# /usr/local/java/bin/jarwrapper - the wrapper for binfmt_misc/jar + #!/bin/bash + # /usr/local/java/bin/jarwrapper - the wrapper for binfmt_misc/jar -java -jar $1 -====================== Cut here =================== + java -jar $1 -Now simply chmod +x the .class, .jar and/or .html files you want to execute. +Now simply ``chmod +x`` the ``.class``, ``.jar`` and/or ``.html`` files you +want to execute. + To add a Java program to your path best put a symbolic link to the main .class file into /usr/bin (or another place you like) omitting the .class extension. The directory containing the original .class file will be @@ -369,7 +378,7 @@ added to your CLASSPATH during execution. To test your new setup, enter in the following simple Java app, and name -it "HelloWorld.java": +it "HelloWorld.java":: class HelloWorld { public static void main(String args[]) { @@ -377,23 +386,28 @@ it "HelloWorld.java": } } -Now compile the application with: +Now compile the application with:: + javac HelloWorld.java -Set the executable permissions of the binary file, with: +Set the executable permissions of the binary file, with:: + chmod 755 HelloWorld.class -And then execute it: +And then execute it:: + ./HelloWorld.class -To execute Java Jar files, simple chmod the *.jar files to include -the execution bit, then just do +To execute Java Jar files, simple chmod the ``*.jar`` files to include +the execution bit, then just do:: + ./Application.jar -To execute Java Applets, simple chmod the *.html files to include -the execution bit, then just do +To execute Java Applets, simple chmod the ``*.html`` files to include +the execution bit, then just do:: + ./Applet.html -- cgit v1.2.3 From 9f4b9ec63cff0048aae43b0119e64f10a7887836 Mon Sep 17 00:00:00 2001 From: Mauro Carvalho Chehab Date: Fri, 23 Sep 2016 14:40:40 -0300 Subject: Documentation/oops-tracing.txt: convert to ReST markup - Add a document title; - use .. note:: markup; - use quote blocks where needed; - use monotonic fonts for config options and file names; - adjust whitespaces and blank lines; - replace _foo_ by **foo**; - while here, remove whitespaces at the end of paragraph; - add it to the user's book. Signed-off-by: Mauro Carvalho Chehab --- Documentation/oops-tracing.txt | 255 ++++++++++++++++++++++------------------- 1 file changed, 138 insertions(+), 117 deletions(-) diff --git a/Documentation/oops-tracing.txt b/Documentation/oops-tracing.txt index f3ac05cc23e4..3e25ea7349ee 100644 --- a/Documentation/oops-tracing.txt +++ b/Documentation/oops-tracing.txt @@ -1,7 +1,13 @@ -NOTE: ksymoops is useless on 2.6. Please use the Oops in its original format -(from dmesg, etc). Ignore any references in this or other docs to "decoding -the Oops" or "running it through ksymoops". If you post an Oops from 2.6 that -has been run through ksymoops, people will just tell you to repost it. +OOPS tracing +============ + +.. note:: + + ``ksymoops`` is useless on 2.6 or upper. Please use the Oops in its original + format (from ``dmesg``, etc). Ignore any references in this or other docs to + "decoding the Oops" or "running it through ksymoops". + If you post an Oops from 2.6+ that has been run through ``ksymoops``, + people will just tell you to repost it. Quick Summary ------------- @@ -12,7 +18,7 @@ If you are unsure send it to the person responsible for the code relevant to what you were doing. If it occurs repeatably try and describe how to recreate it. That's worth even more than the oops. -If you are totally stumped as to whom to send the report, send it to +If you are totally stumped as to whom to send the report, send it to linux-kernel@vger.kernel.org. Thanks for your help in making Linux as stable as humanly possible. @@ -20,24 +26,25 @@ Where is the Oops? ---------------------- Normally the Oops text is read from the kernel buffers by klogd and -handed to syslogd which writes it to a syslog file, typically -/var/log/messages (depends on /etc/syslog.conf). Sometimes klogd dies, -in which case you can run dmesg > file to read the data from the kernel -buffers and save it. Or you can cat /proc/kmsg > file, however you -have to break in to stop the transfer, kmsg is a "never ending file". +handed to ``syslogd`` which writes it to a syslog file, typically +``/var/log/messages`` (depends on ``/etc/syslog.conf``). Sometimes ``klogd`` +dies, in which case you can run ``dmesg > file`` to read the data from the +kernel buffers and save it. Or you can ``cat /proc/kmsg > file``, however you +have to break in to stop the transfer, ``kmsg`` is a "never ending file". If the machine has crashed so badly that you cannot enter commands or -the disk is not available then you have three options :- +the disk is not available then you have three options : (1) Hand copy the text from the screen and type it in after the machine has restarted. Messy but it is the only option if you have not planned for a crash. Alternatively, you can take a picture of the screen with a digital camera - not nice, but better than nothing. If the messages scroll off the top of the console, you - may find that booting with a higher resolution (eg, vga=791) - will allow you to read more of the text. (Caveat: This needs vesafb, + may find that booting with a higher resolution (eg, ``vga=791``) + will allow you to read more of the text. (Caveat: This needs ``vesafb``, so won't help for 'early' oopses) -(2) Boot with a serial console (see Documentation/serial-console.txt), +(2) Boot with a serial console (see + :ref:`Documentation/serial-console.txt `), run a null modem to a second machine and capture the output there using your favourite communication program. Minicom works well. @@ -49,117 +56,126 @@ the disk is not available then you have three options :- Full Information ---------------- -NOTE: the message from Linus below applies to 2.4 kernel. I have preserved it -for historical reasons, and because some of the information in it still -applies. Especially, please ignore any references to ksymoops. +.. note:: + + the message from Linus below applies to 2.4 kernel. I have preserved it + for historical reasons, and because some of the information in it still + applies. Especially, please ignore any references to ksymoops. -From: Linus Torvalds + :: -How to track down an Oops.. [originally a mail to linux-kernel] + From: Linus Torvalds -The main trick is having 5 years of experience with those pesky oops -messages ;-) + How to track down an Oops.. [originally a mail to linux-kernel] -Actually, there are things you can do that make this easier. I have two -separate approaches: + The main trick is having 5 years of experience with those pesky oops + messages ;-) + +Actually, there are things you can do that make this easier. I have two +separate approaches:: gdb /usr/src/linux/vmlinux gdb> disassemble -That's the easy way to find the problem, at least if the bug-report is -well made (like this one was - run through ksymoops to get the -information of which function and the offset in the function that it +That's the easy way to find the problem, at least if the bug-report is +well made (like this one was - run through ``ksymoops`` to get the +information of which function and the offset in the function that it happened in). -Oh, it helps if the report happens on a kernel that is compiled with the +Oh, it helps if the report happens on a kernel that is compiled with the same compiler and similar setups. -The other thing to do is disassemble the "Code:" part of the bug report: +The other thing to do is disassemble the "Code:" part of the bug report: ksymoops will do this too with the correct tools, but if you don't have -the tools you can just do a silly program: +the tools you can just do a silly program:: char str[] = "\xXX\xXX\xXX..."; main(){} -and compile it with gcc -g and then do "disassemble str" (where the "XX" -stuff are the values reported by the Oops - you can just cut-and-paste -and do a replace of spaces to "\x" - that's what I do, as I'm too lazy +and compile it with ``gcc -g`` and then do ``disassemble str`` (where the ``XX`` +stuff are the values reported by the Oops - you can just cut-and-paste +and do a replace of spaces to ``\x`` - that's what I do, as I'm too lazy to write a program to automate this all). -Alternatively, you can use the shell script in scripts/decodecode. -Its usage is: decodecode < oops.txt +Alternatively, you can use the shell script in ``scripts/decodecode``. +Its usage is:: + + decodecode < oops.txt The hex bytes that follow "Code:" may (in some architectures) have a series of bytes that precede the current instruction pointer as well as bytes at and following the current instruction pointer. In some cases, one instruction -byte or word is surrounded by <> or (), as in "<86>" or "(f00d)". These -<> or () markings indicate the current instruction pointer. Example from -i386, split into multiple lines for readability: +byte or word is surrounded by ``<>`` or ``()``, as in ``<86>`` or ``(f00d)``. +These ``<>`` or ``()`` markings indicate the current instruction pointer. + +Example from i386, split into multiple lines for readability:: -Code: f9 0f 8d f9 00 00 00 8d 42 0c e8 dd 26 11 c7 a1 60 ea 2b f9 8b 50 08 a1 -64 ea 2b f9 8d 34 82 8b 1e 85 db 74 6d 8b 15 60 ea 2b f9 <8b> 43 04 39 42 54 -7e 04 40 89 42 54 8b 43 04 3b 05 00 f6 52 c0 + Code: f9 0f 8d f9 00 00 00 8d 42 0c e8 dd 26 11 c7 a1 60 ea 2b f9 8b 50 08 a1 + 64 ea 2b f9 8d 34 82 8b 1e 85 db 74 6d 8b 15 60 ea 2b f9 <8b> 43 04 39 42 54 + 7e 04 40 89 42 54 8b 43 04 3b 05 00 f6 52 c0 -Finally, if you want to see where the code comes from, you can do +Finally, if you want to see where the code comes from, you can do:: cd /usr/src/linux make fs/buffer.s # or whatever file the bug happened in -and then you get a better idea of what happens than with the gdb +and then you get a better idea of what happens than with the gdb disassembly. -Now, the trick is just then to combine all the data you have: the C -sources (and general knowledge of what it _should_ do), the assembly -listing and the code disassembly (and additionally the register dump you -also get from the "oops" message - that can be useful to see _what_ the -corrupted pointers were, and when you have the assembler listing you can -also match the other registers to whatever C expressions they were used +Now, the trick is just then to combine all the data you have: the C +sources (and general knowledge of what it **should** do), the assembly +listing and the code disassembly (and additionally the register dump you +also get from the "oops" message - that can be useful to see **what** the +corrupted pointers were, and when you have the assembler listing you can +also match the other registers to whatever C expressions they were used for). -Essentially, you just look at what doesn't match (in this case it was the -"Code" disassembly that didn't match with what the compiler generated). -Then you need to find out _why_ they don't match. Often it's simple - you -see that the code uses a NULL pointer and then you look at the code and -wonder how the NULL pointer got there, and if it's a valid thing to do +Essentially, you just look at what doesn't match (in this case it was the +"Code" disassembly that didn't match with what the compiler generated). +Then you need to find out **why** they don't match. Often it's simple - you +see that the code uses a NULL pointer and then you look at the code and +wonder how the NULL pointer got there, and if it's a valid thing to do you just check against it.. -Now, if somebody gets the idea that this is time-consuming and requires -some small amount of concentration, you're right. Which is why I will -mostly just ignore any panic reports that don't have the symbol table -info etc looked up: it simply gets too hard to look it up (I have some -programs to search for specific patterns in the kernel code segment, and -sometimes I have been able to look up those kinds of panics too, but -that really requires pretty good knowledge of the kernel just to be able +Now, if somebody gets the idea that this is time-consuming and requires +some small amount of concentration, you're right. Which is why I will +mostly just ignore any panic reports that don't have the symbol table +info etc looked up: it simply gets too hard to look it up (I have some +programs to search for specific patterns in the kernel code segment, and +sometimes I have been able to look up those kinds of panics too, but +that really requires pretty good knowledge of the kernel just to be able to pick out the right sequences etc..) -_Sometimes_ it happens that I just see the disassembled code sequence -from the panic, and I know immediately where it's coming from. That's when +**Sometimes** it happens that I just see the disassembled code sequence +from the panic, and I know immediately where it's coming from. That's when I get worried that I've been doing this for too long ;-) Linus --------------------------------------------------------------------------- -Notes on Oops tracing with klogd: + +Notes on Oops tracing with ``klogd`` +------------------------------------ In order to help Linus and the other kernel developers there has been -substantial support incorporated into klogd for processing protection +substantial support incorporated into ``klogd`` for processing protection faults. In order to have full support for address resolution at least -version 1.3-pl3 of the sysklogd package should be used. +version 1.3-pl3 of the ``sysklogd`` package should be used. -When a protection fault occurs the klogd daemon automatically +When a protection fault occurs the ``klogd`` daemon automatically translates important addresses in the kernel log messages to their symbolic equivalents. This translated kernel message is then -forwarded through whatever reporting mechanism klogd is using. The +forwarded through whatever reporting mechanism ``klogd`` is using. The protection fault message can be simply cut out of the message files and forwarded to the kernel developers. -Two types of address resolution are performed by klogd. The first is +Two types of address resolution are performed by ``klogd``. The first is static translation and the second is dynamic translation. Static translation uses the System.map file in much the same manner that -ksymoops does. In order to do static translation the klogd daemon +ksymoops does. In order to do static translation the ``klogd`` daemon must be able to find a system map file at daemon initialization time. -See the klogd man page for information on how klogd searches for map +See the klogd man page for information on how ``klogd`` searches for map files. Dynamic address translation is important when kernel loadable modules @@ -178,101 +194,106 @@ information available if the developer of the loadable module chose to export symbol information from the module. Since the kernel module environment can be dynamic there must be a -mechanism for notifying the klogd daemon when a change in module +mechanism for notifying the ``klogd`` daemon when a change in module environment occurs. There are command line options available which allow klogd to signal the currently executing daemon that symbol -information should be refreshed. See the klogd manual page for more +information should be refreshed. See the ``klogd`` manual page for more information. A patch is included with the sysklogd distribution which modifies the -modules-2.0.0 package to automatically signal klogd whenever a module +``modules-2.0.0`` package to automatically signal klogd whenever a module is loaded or unloaded. Applying this patch provides essentially seamless support for debugging protection faults which occur with kernel loadable modules. The following is an example of a protection fault in a loadable module -processed by klogd: ---------------------------------------------------------------------------- -Aug 29 09:51:01 blizard kernel: Unable to handle kernel paging request at virtual address f15e97cc -Aug 29 09:51:01 blizard kernel: current->tss.cr3 = 0062d000, %cr3 = 0062d000 -Aug 29 09:51:01 blizard kernel: *pde = 00000000 -Aug 29 09:51:01 blizard kernel: Oops: 0002 -Aug 29 09:51:01 blizard kernel: CPU: 0 -Aug 29 09:51:01 blizard kernel: EIP: 0010:[oops:_oops+16/3868] -Aug 29 09:51:01 blizard kernel: EFLAGS: 00010212 -Aug 29 09:51:01 blizard kernel: eax: 315e97cc ebx: 003a6f80 ecx: 001be77b edx: 00237c0c -Aug 29 09:51:01 blizard kernel: esi: 00000000 edi: bffffdb3 ebp: 00589f90 esp: 00589f8c -Aug 29 09:51:01 blizard kernel: ds: 0018 es: 0018 fs: 002b gs: 002b ss: 0018 -Aug 29 09:51:01 blizard kernel: Process oops_test (pid: 3374, process nr: 21, stackpage=00589000) -Aug 29 09:51:01 blizard kernel: Stack: 315e97cc 00589f98 0100b0b4 bffffed4 0012e38e 00240c64 003a6f80 00000001 -Aug 29 09:51:01 blizard kernel: 00000000 00237810 bfffff00 0010a7fa 00000003 00000001 00000000 bfffff00 -Aug 29 09:51:01 blizard kernel: bffffdb3 bffffed4 ffffffda 0000002b 0007002b 0000002b 0000002b 00000036 -Aug 29 09:51:01 blizard kernel: Call Trace: [oops:_oops_ioctl+48/80] [_sys_ioctl+254/272] [_system_call+82/128] -Aug 29 09:51:01 blizard kernel: Code: c7 00 05 00 00 00 eb 08 90 90 90 90 90 90 90 90 89 ec 5d c3 +processed by ``klogd``:: + + Aug 29 09:51:01 blizard kernel: Unable to handle kernel paging request at virtual address f15e97cc + Aug 29 09:51:01 blizard kernel: current->tss.cr3 = 0062d000, %cr3 = 0062d000 + Aug 29 09:51:01 blizard kernel: *pde = 00000000 + Aug 29 09:51:01 blizard kernel: Oops: 0002 + Aug 29 09:51:01 blizard kernel: CPU: 0 + Aug 29 09:51:01 blizard kernel: EIP: 0010:[oops:_oops+16/3868] + Aug 29 09:51:01 blizard kernel: EFLAGS: 00010212 + Aug 29 09:51:01 blizard kernel: eax: 315e97cc ebx: 003a6f80 ecx: 001be77b edx: 00237c0c + Aug 29 09:51:01 blizard kernel: esi: 00000000 edi: bffffdb3 ebp: 00589f90 esp: 00589f8c + Aug 29 09:51:01 blizard kernel: ds: 0018 es: 0018 fs: 002b gs: 002b ss: 0018 + Aug 29 09:51:01 blizard kernel: Process oops_test (pid: 3374, process nr: 21, stackpage=00589000) + Aug 29 09:51:01 blizard kernel: Stack: 315e97cc 00589f98 0100b0b4 bffffed4 0012e38e 00240c64 003a6f80 00000001 + Aug 29 09:51:01 blizard kernel: 00000000 00237810 bfffff00 0010a7fa 00000003 00000001 00000000 bfffff00 + Aug 29 09:51:01 blizard kernel: bffffdb3 bffffed4 ffffffda 0000002b 0007002b 0000002b 0000002b 00000036 + Aug 29 09:51:01 blizard kernel: Call Trace: [oops:_oops_ioctl+48/80] [_sys_ioctl+254/272] [_system_call+82/128] + Aug 29 09:51:01 blizard kernel: Code: c7 00 05 00 00 00 eb 08 90 90 90 90 90 90 90 90 89 ec 5d c3 + --------------------------------------------------------------------------- -Dr. G.W. Wettstein Oncology Research Div. Computing Facility -Roger Maris Cancer Center INTERNET: greg@wind.rmcc.com -820 4th St. N. -Fargo, ND 58122 -Phone: 701-234-7556 +:: + + Dr. G.W. Wettstein Oncology Research Div. Computing Facility + Roger Maris Cancer Center INTERNET: greg@wind.rmcc.com + 820 4th St. N. + Fargo, ND 58122 + Phone: 701-234-7556 --------------------------------------------------------------------------- -Tainted kernels: -Some oops reports contain the string 'Tainted: ' after the program +Tainted kernels +--------------- + +Some oops reports contain the string **'Tainted: '** after the program counter. This indicates that the kernel has been tainted by some mechanism. The string is followed by a series of position-sensitive characters, each representing a particular tainted value. - 1: 'G' if all modules loaded have a GPL or compatible license, 'P' if + 1) 'G' if all modules loaded have a GPL or compatible license, 'P' if any proprietary module has been loaded. Modules without a MODULE_LICENSE or with a MODULE_LICENSE that is not recognised by insmod as GPL compatible are assumed to be proprietary. - 2: 'F' if any module was force loaded by "insmod -f", ' ' if all + 2) ``F`` if any module was force loaded by ``insmod -f``, ``' '`` if all modules were loaded normally. - 3: 'S' if the oops occurred on an SMP kernel running on hardware that + 3) ``S`` if the oops occurred on an SMP kernel running on hardware that hasn't been certified as safe to run multiprocessor. Currently this occurs only on various Athlons that are not SMP capable. - 4: 'R' if a module was force unloaded by "rmmod -f", ' ' if all + 4) ``R`` if a module was force unloaded by ``rmmod -f``, ``' '`` if all modules were unloaded normally. - 5: 'M' if any processor has reported a Machine Check Exception, - ' ' if no Machine Check Exceptions have occurred. + 5) ``M`` if any processor has reported a Machine Check Exception, + ``' '`` if no Machine Check Exceptions have occurred. - 6: 'B' if a page-release function has found a bad page reference or + 6) ``B`` if a page-release function has found a bad page reference or some unexpected page flags. - 7: 'U' if a user or user application specifically requested that the - Tainted flag be set, ' ' otherwise. + 7) ``U`` if a user or user application specifically requested that the + Tainted flag be set, ``' '`` otherwise. - 8: 'D' if the kernel has died recently, i.e. there was an OOPS or BUG. + 8) ``D`` if the kernel has died recently, i.e. there was an OOPS or BUG. - 9: 'A' if the ACPI table has been overridden. + 9) ``A`` if the ACPI table has been overridden. - 10: 'W' if a warning has previously been issued by the kernel. + 10) ``W`` if a warning has previously been issued by the kernel. (Though some warnings may set more specific taint flags.) - 11: 'C' if a staging driver has been loaded. + 11) ``C`` if a staging driver has been loaded. - 12: 'I' if the kernel is working around a severe bug in the platform + 12) ``I`` if the kernel is working around a severe bug in the platform firmware (BIOS or similar). - 13: 'O' if an externally-built ("out-of-tree") module has been loaded. + 13) ``O`` if an externally-built ("out-of-tree") module has been loaded. - 14: 'E' if an unsigned module has been loaded in a kernel supporting + 14) ``E`` if an unsigned module has been loaded in a kernel supporting module signature. - 15: 'L' if a soft lockup has previously occurred on the system. + 15) ``L`` if a soft lockup has previously occurred on the system. - 16: 'K' if the kernel has been live patched. + 16) ``K`` if the kernel has been live patched. -The primary reason for the 'Tainted: ' string is to tell kernel +The primary reason for the **'Tainted: '** string is to tell kernel debuggers if this is a clean kernel or if anything unusual has occurred. Tainting is permanent: even if an offending module is unloaded, the tainted value remains to indicate that the kernel is not -- cgit v1.2.3 From e095f0711b49269e34941098b9bd60a87eb50866 Mon Sep 17 00:00:00 2001 From: Mauro Carvalho Chehab Date: Fri, 23 Sep 2016 15:07:00 -0300 Subject: Documentation/parport.txt: convert to ReST markup - Add a document title; - use quote blocks where needed; - convert parameters to a nested table; - use monotonic fonts for config options and file names; - adjust whitespaces and blank lines; - replace _foo_ by **foo**; - add it to the user's book. Signed-off-by: Mauro Carvalho Chehab --- Documentation/parport.txt | 294 ++++++++++++++++++++++++---------------------- 1 file changed, 151 insertions(+), 143 deletions(-) diff --git a/Documentation/parport.txt b/Documentation/parport.txt index c208e4366c03..3273ce79f9e3 100644 --- a/Documentation/parport.txt +++ b/Documentation/parport.txt @@ -1,15 +1,18 @@ -The `parport' code provides parallel-port support under Linux. This +Parport ++++++++ + +The ``parport`` code provides parallel-port support under Linux. This includes the ability to share one port between multiple device drivers. -You can pass parameters to the parport code to override its automatic +You can pass parameters to the ``parport`` code to override its automatic detection of your hardware. This is particularly useful if you want to use IRQs, since in general these can't be autoprobed successfully. -By default IRQs are not used even if they _can_ be probed. This is +By default IRQs are not used even if they **can** be probed. This is because there are a lot of people using the same IRQ for their parallel port and a sound card or network card. -The parport code is split into two parts: generic (which deals with +The ``parport`` code is split into two parts: generic (which deals with port-sharing) and architecture-dependent (which deals with actually using the port). @@ -17,21 +20,21 @@ using the port). Parport as modules ================== -If you load the parport code as a module, say +If you load the `parport`` code as a module, say:: # insmod parport -to load the generic parport code. You then must load the -architecture-dependent code with (for example): +to load the generic ``parport`` code. You then must load the +architecture-dependent code with (for example):: # insmod parport_pc io=0x3bc,0x378,0x278 irq=none,7,auto -to tell the parport code that you want three PC-style ports, one at +to tell the ``parport`` code that you want three PC-style ports, one at 0x3bc with no IRQ, one at 0x378 using IRQ 7, and one at 0x278 with an -auto-detected IRQ. Currently, PC-style (parport_pc), Sun `bpp', +auto-detected IRQ. Currently, PC-style (``parport_pc``), Sun ``bpp``, Amiga, Atari, and MFC3 hardware is supported. -PCI parallel I/O card support comes from parport_pc. Base I/O +PCI parallel I/O card support comes from ``parport_pc``. Base I/O addresses should not be specified for supported PCI cards since they are automatically detected. @@ -40,151 +43,154 @@ modprobe -------- If you use modprobe , you will find it useful to add lines as below to a -configuration file in /etc/modprobe.d/ directory:. +configuration file in /etc/modprobe.d/ directory:: alias parport_lowlevel parport_pc options parport_pc io=0x378,0x278 irq=7,auto -modprobe will load parport_pc (with the options "io=0x378,0x278 irq=7,auto") -whenever a parallel port device driver (such as lp) is loaded. +modprobe will load ``parport_pc`` (with the options ``io=0x378,0x278 irq=7,auto``) +whenever a parallel port device driver (such as ``lp``) is loaded. Note that these are example lines only! You shouldn't in general need -to specify any options to parport_pc in order to be able to use a +to specify any options to ``parport_pc`` in order to be able to use a parallel port. Parport probe [optional] -------------- +------------------------ -In 2.2 kernels there was a module called parport_probe, which was used +In 2.2 kernels there was a module called ``parport_probe``, which was used for collecting IEEE 1284 device ID information. This has now been enhanced and now lives with the IEEE 1284 support. When a parallel port is detected, the devices that are connected to it are analysed, -and information is logged like this: +and information is logged like this:: parport0: Printer, BJC-210 (Canon) -The probe information is available from files in /proc/sys/dev/parport/. +The probe information is available from files in ``/proc/sys/dev/parport/``. Parport linked into the kernel statically ========================================= -If you compile the parport code into the kernel, then you can use +If you compile the ``parport`` code into the kernel, then you can use kernel boot parameters to get the same effect. Add something like the -following to your LILO command line: +following to your LILO command line:: parport=0x3bc parport=0x378,7 parport=0x278,auto,nofifo -You can have many `parport=...' statements, one for each port you want -to add. Adding `parport=0' to the kernel command-line will disable -parport support entirely. Adding `parport=auto' to the kernel -command-line will make parport use any IRQ lines or DMA channels that +You can have many ``parport=...`` statements, one for each port you want +to add. Adding ``parport=0`` to the kernel command-line will disable +parport support entirely. Adding ``parport=auto`` to the kernel +command-line will make ``parport`` use any IRQ lines or DMA channels that it auto-detects. Files in /proc ============== -If you have configured the /proc filesystem into your kernel, you will -see a new directory entry: /proc/sys/dev/parport. In there will be a +If you have configured the ``/proc`` filesystem into your kernel, you will +see a new directory entry: ``/proc/sys/dev/parport``. In there will be a directory entry for each parallel port for which parport is configured. In each of those directories are a collection of files describing that parallel port. -The /proc/sys/dev/parport directory tree looks like: - -parport -|-- default -| |-- spintime -| `-- timeslice -|-- parport0 -| |-- autoprobe -| |-- autoprobe0 -| |-- autoprobe1 -| |-- autoprobe2 -| |-- autoprobe3 -| |-- devices -| | |-- active -| | `-- lp -| | `-- timeslice -| |-- base-addr -| |-- irq -| |-- dma -| |-- modes -| `-- spintime -`-- parport1 - |-- autoprobe - |-- autoprobe0 - |-- autoprobe1 - |-- autoprobe2 - |-- autoprobe3 - |-- devices - | |-- active - | `-- ppa - | `-- timeslice - |-- base-addr - |-- irq - |-- dma - |-- modes - `-- spintime - - -File: Contents: - -devices/active A list of the device drivers using that port. A "+" - will appear by the name of the device currently using - the port (it might not appear against any). The - string "none" means that there are no device drivers - using that port. - -base-addr Parallel port's base address, or addresses if the port - has more than one in which case they are separated - with tabs. These values might not have any sensible - meaning for some ports. - -irq Parallel port's IRQ, or -1 if none is being used. - -dma Parallel port's DMA channel, or -1 if none is being - used. - -modes Parallel port's hardware modes, comma-separated, - meaning: - - PCSPP PC-style SPP registers are available. - TRISTATE Port is bidirectional. - COMPAT Hardware acceleration for printers is - available and will be used. - EPP Hardware acceleration for EPP protocol - is available and will be used. - ECP Hardware acceleration for ECP protocol - is available and will be used. - DMA DMA is available and will be used. - - Note that the current implementation will only take - advantage of COMPAT and ECP modes if it has an IRQ - line to use. - -autoprobe Any IEEE-1284 device ID information that has been - acquired from the (non-IEEE 1284.3) device. - -autoprobe[0-3] IEEE 1284 device ID information retrieved from - daisy-chain devices that conform to IEEE 1284.3. - -spintime The number of microseconds to busy-loop while waiting - for the peripheral to respond. You might find that - adjusting this improves performance, depending on your - peripherals. This is a port-wide setting, i.e. it - applies to all devices on a particular port. - -timeslice The number of milliseconds that a device driver is - allowed to keep a port claimed for. This is advisory, - and driver can ignore it if it must. - -default/* The defaults for spintime and timeslice. When a new - port is registered, it picks up the default spintime. - When a new device is registered, it picks up the - default timeslice. +The ``/proc/sys/dev/parport`` directory tree looks like:: + + parport + |-- default + | |-- spintime + | `-- timeslice + |-- parport0 + | |-- autoprobe + | |-- autoprobe0 + | |-- autoprobe1 + | |-- autoprobe2 + | |-- autoprobe3 + | |-- devices + | | |-- active + | | `-- lp + | | `-- timeslice + | |-- base-addr + | |-- irq + | |-- dma + | |-- modes + | `-- spintime + `-- parport1 + |-- autoprobe + |-- autoprobe0 + |-- autoprobe1 + |-- autoprobe2 + |-- autoprobe3 + |-- devices + | |-- active + | `-- ppa + | `-- timeslice + |-- base-addr + |-- irq + |-- dma + |-- modes + `-- spintime + +======================= ======================================================= +File Contents +======================= ======================================================= +``devices/active`` A list of the device drivers using that port. A "+" + will appear by the name of the device currently using + the port (it might not appear against any). The + string "none" means that there are no device drivers + using that port. + +``base-addr`` Parallel port's base address, or addresses if the port + has more than one in which case they are separated + with tabs. These values might not have any sensible + meaning for some ports. + +``irq`` Parallel port's IRQ, or -1 if none is being used. + +``dma`` Parallel port's DMA channel, or -1 if none is being + used. + +``modes`` Parallel port's hardware modes, comma-separated, + meaning: + + =============== ======================================= + PCSPP PC-style SPP registers are available. + TRISTATE Port is bidirectional. + COMPAT Hardware acceleration for printers is + available and will be used. + EPP Hardware acceleration for EPP protocol + is available and will be used. + ECP Hardware acceleration for ECP protocol + is available and will be used. + DMA DMA is available and will be used. + =============== ======================================= + + Note that the current implementation will only take + advantage of COMPAT and ECP modes if it has an IRQ + line to use. + +``autoprobe`` Any IEEE-1284 device ID information that has been + acquired from the (non-IEEE 1284.3) device. + +``autoprobe[0-3]`` IEEE 1284 device ID information retrieved from + daisy-chain devices that conform to IEEE 1284.3. + +``spintime`` The number of microseconds to busy-loop while waiting + for the peripheral to respond. You might find that + adjusting this improves performance, depending on your + peripherals. This is a port-wide setting, i.e. it + applies to all devices on a particular port. + +``timeslice`` The number of milliseconds that a device driver is + allowed to keep a port claimed for. This is advisory, + and driver can ignore it if it must. + +``default/*`` The defaults for spintime and timeslice. When a new + port is registered, it picks up the default spintime. + When a new device is registered, it picks up the + default timeslice. +======================= ======================================================= Device drivers ============== @@ -193,31 +199,31 @@ Once the parport code is initialised, you can attach device drivers to specific ports. Normally this happens automatically; if the lp driver is loaded it will create one lp device for each port found. You can override this, though, by using parameters either when you load the lp -driver: +driver:: # insmod lp parport=0,2 -or on the LILO command line: +or on the LILO command line:: lp=parport0 lp=parport2 -Both the above examples would inform lp that you want /dev/lp0 to be -the first parallel port, and /dev/lp1 to be the _third_ parallel port, +Both the above examples would inform lp that you want ``/dev/lp0`` to be +the first parallel port, and /dev/lp1 to be the **third** parallel port, with no lp device associated with the second port (parport1). Note that this is different to the way older kernels worked; there used to be a static association between the I/O port address and the device -name, so /dev/lp0 was always the port at 0x3bc. This is no longer the -case - if you only have one port, it will default to being /dev/lp0, +name, so ``/dev/lp0`` was always the port at 0x3bc. This is no longer the +case - if you only have one port, it will default to being ``/dev/lp0``, regardless of base address. Also: * If you selected the IEEE 1284 support at compile time, you can say - `lp=auto' on the kernel command line, and lp will create devices + ``lp=auto`` on the kernel command line, and lp will create devices only for those ports that seem to have printers attached. - * If you give PLIP the `timid' parameter, either with `plip=timid' on - the command line, or with `insmod plip timid=1' when using modules, + * If you give PLIP the ``timid`` parameter, either with ``plip=timid`` on + the command line, or with ``insmod plip timid=1`` when using modules, it will avoid any ports that seem to be in use by other devices. * IRQ autoprobing works only for a few port types at the moment. @@ -229,39 +235,41 @@ If you are having problems printing, please go through these steps to try to narrow down where the problem area is. When reporting problems with parport, really you need to give all of -the messages that parport_pc spits out when it initialises. There are +the messages that ``parport_pc`` spits out when it initialises. There are several code paths: -o polling -o interrupt-driven, protocol in software -o interrupt-driven, protocol in hardware using PIO -o interrupt-driven, protocol in hardware using DMA +- polling +- interrupt-driven, protocol in software +- interrupt-driven, protocol in hardware using PIO +- interrupt-driven, protocol in hardware using DMA -The kernel messages that parport_pc logs give an indication of which +The kernel messages that ``parport_pc`` logs give an indication of which code path is being used. (They could be a lot better actually..) For normal printer protocol, having IEEE 1284 modes enabled or not should not make a difference. To turn off the 'protocol in hardware' code paths, disable -CONFIG_PARPORT_PC_FIFO. Note that when they are enabled they are not -necessarily _used_; it depends on whether the hardware is available, +``CONFIG_PARPORT_PC_FIFO``. Note that when they are enabled they are not +necessarily **used**; it depends on whether the hardware is available, enabled by the BIOS, and detected by the driver. -So, to start with, disable CONFIG_PARPORT_PC_FIFO, and load parport_pc -with 'irq=none'. See if printing works then. It really should, +So, to start with, disable ``CONFIG_PARPORT_PC_FIFO``, and load ``parport_pc`` +with ``irq=none``. See if printing works then. It really should, because this is the simplest code path. -If that works fine, try with 'io=0x378 irq=7' (adjust for your +If that works fine, try with ``io=0x378 irq=7`` (adjust for your hardware), to make it use interrupt-driven in-software protocol. -If _that_ works fine, then one of the hardware modes isn't working -right. Enable CONFIG_PARPORT_PC_FIFO (no, it isn't a module option, +If **that** works fine, then one of the hardware modes isn't working +right. Enable ``CONFIG_FIFO`` (no, it isn't a module option, and yes, it should be), set the port to ECP mode in the BIOS and note -the DMA channel, and try with: +the DMA channel, and try with:: io=0x378 irq=7 dma=none (for PIO) io=0x378 irq=7 dma=3 (for DMA) --- + +---------- + philb@gnu.org tim@cyberelk.net -- cgit v1.2.3 From b2777b650c5073010adea8ec2bb38eaad1cf800a Mon Sep 17 00:00:00 2001 From: Mauro Carvalho Chehab Date: Fri, 23 Sep 2016 15:24:07 -0300 Subject: Documentation/ramoops.txt: convert it to ReST format - Fix document title; - use quote blocks where needed; - use monotonic fonts for config options and file names; - adjust whitespaces and blank lines; - add it to the user's book. Signed-off-by: Mauro Carvalho Chehab --- Documentation/ramoops.txt | 88 ++++++++++++++++++++++++++--------------------- 1 file changed, 48 insertions(+), 40 deletions(-) diff --git a/Documentation/ramoops.txt b/Documentation/ramoops.txt index 26b9f31cf65a..7eaf1e71c083 100644 --- a/Documentation/ramoops.txt +++ b/Documentation/ramoops.txt @@ -5,34 +5,37 @@ Sergiu Iordache Updated: 17 November 2011 -0. Introduction +Introduction +------------ Ramoops is an oops/panic logger that writes its logs to RAM before the system crashes. It works by logging oopses and panics in a circular buffer. Ramoops needs a system with persistent RAM so that the content of that area can survive after a restart. -1. Ramoops concepts +Ramoops concepts +---------------- Ramoops uses a predefined memory area to store the dump. The start and size and type of the memory area are set using three variables: - * "mem_address" for the start - * "mem_size" for the size. The memory size will be rounded down to a - power of two. - * "mem_type" to specifiy if the memory type (default is pgprot_writecombine). - -Typically the default value of mem_type=0 should be used as that sets the pstore -mapping to pgprot_writecombine. Setting mem_type=1 attempts to use -pgprot_noncached, which only works on some platforms. This is because pstore + + * ``mem_address`` for the start + * ``mem_size`` for the size. The memory size will be rounded down to a + power of two. + * ``mem_type`` to specifiy if the memory type (default is pgprot_writecombine). + +Typically the default value of ``mem_type=0`` should be used as that sets the pstore +mapping to pgprot_writecombine. Setting ``mem_type=1`` attempts to use +``pgprot_noncached``, which only works on some platforms. This is because pstore depends on atomic operations. At least on ARM, pgprot_noncached causes the memory to be mapped strongly ordered, and atomic operations on strongly ordered memory are implementation defined, and won't work on many ARMs such as omaps. -The memory area is divided into "record_size" chunks (also rounded down to -power of two) and each oops/panic writes a "record_size" chunk of +The memory area is divided into ``record_size`` chunks (also rounded down to +power of two) and each oops/panic writes a ``record_size`` chunk of information. -Dumping both oopses and panics can be done by setting 1 in the "dump_oops" +Dumping both oopses and panics can be done by setting 1 in the ``dump_oops`` variable while setting 0 in that variable dumps only the panics. The module uses a counter to record multiple dumps but the counter gets reset @@ -43,7 +46,8 @@ This might be useful when a hardware reset was used to bring the machine back to life (i.e. a watchdog triggered). In such cases, RAM may be somewhat corrupt, but usually it is restorable. -2. Setting the parameters +Setting the parameters +---------------------- Setting the ramoops parameters can be done in several different manners: @@ -52,12 +56,13 @@ Setting the ramoops parameters can be done in several different manners: boot and then use the reserved memory for ramoops. For example, assuming a machine with > 128 MB of memory, the following kernel command line will tell the kernel to use only the first 128 MB of memory, and place ECC-protected - ramoops region at 128 MB boundary: - "mem=128M ramoops.mem_address=0x8000000 ramoops.ecc=1" + ramoops region at 128 MB boundary:: + + mem=128M ramoops.mem_address=0x8000000 ramoops.ecc=1 B. Use Device Tree bindings, as described in - Documentation/device-tree/bindings/reserved-memory/ramoops.txt. - For example: + ``Documentation/device-tree/bindings/reserved-memory/ramoops.txt``. + For example:: reserved-memory { #address-cells = <2>; @@ -73,60 +78,63 @@ Setting the ramoops parameters can be done in several different manners: }; C. Use a platform device and set the platform data. The parameters can then - be set through that platform data. An example of doing that is: + be set through that platform data. An example of doing that is:: -#include -[...] + #include + [...] -static struct ramoops_platform_data ramoops_data = { + static struct ramoops_platform_data ramoops_data = { .mem_size = <...>, .mem_address = <...>, .mem_type = <...>, .record_size = <...>, .dump_oops = <...>, .ecc = <...>, -}; + }; -static struct platform_device ramoops_dev = { + static struct platform_device ramoops_dev = { .name = "ramoops", .dev = { .platform_data = &ramoops_data, }, -}; + }; -[... inside a function ...] -int ret; + [... inside a function ...] + int ret; -ret = platform_device_register(&ramoops_dev); -if (ret) { + ret = platform_device_register(&ramoops_dev); + if (ret) { printk(KERN_ERR "unable to register platform device\n"); return ret; -} + } You can specify either RAM memory or peripheral devices' memory. However, when specifying RAM, be sure to reserve the memory by issuing memblock_reserve() -very early in the architecture code, e.g.: +very early in the architecture code, e.g.:: -#include + #include -memblock_reserve(ramoops_data.mem_address, ramoops_data.mem_size); + memblock_reserve(ramoops_data.mem_address, ramoops_data.mem_size); -3. Dump format +Dump format +----------- -The data dump begins with a header, currently defined as "====" followed by a +The data dump begins with a header, currently defined as ``====`` followed by a timestamp and a new line. The dump then continues with the actual data. -4. Reading the data +Reading the data +---------------- The dump data can be read from the pstore filesystem. The format for these -files is "dmesg-ramoops-N", where N is the record number in memory. To delete +files is ``dmesg-ramoops-N``, where N is the record number in memory. To delete a stored record from RAM, simply unlink the respective pstore file. -5. Persistent function tracing +Persistent function tracing +--------------------------- Persistent function tracing might be useful for debugging software or hardware -related hangs. The functions call chain log is stored in a "ftrace-ramoops" -file. Here is an example of usage: +related hangs. The functions call chain log is stored in a ``ftrace-ramoops`` +file. Here is an example of usage:: # mount -t debugfs debugfs /sys/kernel/debug/ # echo 1 > /sys/kernel/debug/pstore/record_ftrace -- cgit v1.2.3 From 3177ae4a1034482efe2c3eef5ab9988d050c5b4f Mon Sep 17 00:00:00 2001 From: Mauro Carvalho Chehab Date: Fri, 23 Sep 2016 15:44:01 -0300 Subject: Documentation/sysfs-rules.txt: convert it to ReST markup - Fix document title; - use quote blocks where needed; - use monotonic fonts for config options and file names; - adjust whitespaces and blank lines; - add it to the user's book. Signed-off-by: Mauro Carvalho Chehab --- Documentation/sysfs-rules.txt | 230 ++++++++++++++++++++++-------------------- 1 file changed, 119 insertions(+), 111 deletions(-) diff --git a/Documentation/sysfs-rules.txt b/Documentation/sysfs-rules.txt index ce60ffa94d2d..04bdd52cba1d 100644 --- a/Documentation/sysfs-rules.txt +++ b/Documentation/sysfs-rules.txt @@ -1,4 +1,5 @@ Rules on how to access information in the Linux kernel sysfs +============================================================ The kernel-exported sysfs exports internal kernel implementation details and depends on internal kernel structures and layout. It is agreed upon @@ -18,36 +19,38 @@ the following rules and then your programs should work with future versions of the sysfs interface. - Do not use libsysfs - It makes assumptions about sysfs which are not true. Its API does not - offer any abstraction, it exposes all the kernel driver-core - implementation details in its own API. Therefore it is not better than - reading directories and opening the files yourself. - Also, it is not actively maintained, in the sense of reflecting the - current kernel development. The goal of providing a stable interface - to sysfs has failed; it causes more problems than it solves. It - violates many of the rules in this document. - -- sysfs is always at /sys - Parsing /proc/mounts is a waste of time. Other mount points are a - system configuration bug you should not try to solve. For test cases, - possibly support a SYSFS_PATH environment variable to overwrite the - application's behavior, but never try to search for sysfs. Never try - to mount it, if you are not an early boot script. + It makes assumptions about sysfs which are not true. Its API does not + offer any abstraction, it exposes all the kernel driver-core + implementation details in its own API. Therefore it is not better than + reading directories and opening the files yourself. + Also, it is not actively maintained, in the sense of reflecting the + current kernel development. The goal of providing a stable interface + to sysfs has failed; it causes more problems than it solves. It + violates many of the rules in this document. + +- sysfs is always at ``/sys`` + Parsing ``/proc/mounts`` is a waste of time. Other mount points are a + system configuration bug you should not try to solve. For test cases, + possibly support a ``SYSFS_PATH`` environment variable to overwrite the + application's behavior, but never try to search for sysfs. Never try + to mount it, if you are not an early boot script. - devices are only "devices" - There is no such thing like class-, bus-, physical devices, - interfaces, and such that you can rely on in userspace. Everything is - just simply a "device". Class-, bus-, physical, ... types are just - kernel implementation details which should not be expected by - applications that look for devices in sysfs. - - The properties of a device are: - o devpath (/devices/pci0000:00/0000:00:1d.1/usb2/2-2/2-2:1.0) + There is no such thing like class-, bus-, physical devices, + interfaces, and such that you can rely on in userspace. Everything is + just simply a "device". Class-, bus-, physical, ... types are just + kernel implementation details which should not be expected by + applications that look for devices in sysfs. + + The properties of a device are: + + - devpath (``/devices/pci0000:00/0000:00:1d.1/usb2/2-2/2-2:1.0``) + - identical to the DEVPATH value in the event sent from the kernel at device creation and removal - the unique key to the device at that point in time - the kernel's path to the device directory without the leading - /sys, and always starting with a slash + ``/sys``, and always starting with a slash - all elements of a devpath must be real directories. Symlinks pointing to /sys/devices must always be resolved to their real target and the target path must be used to access the device. @@ -56,17 +59,20 @@ versions of the sysfs interface. - using or exposing symlink values as elements in a devpath string is a bug in the application - o kernel name (sda, tty, 0000:00:1f.2, ...) + - kernel name (``sda``, ``tty``, ``0000:00:1f.2``, ...) + - a directory name, identical to the last element of the devpath - - applications need to handle spaces and characters like '!' in + - applications need to handle spaces and characters like ``!`` in the name - o subsystem (block, tty, pci, ...) + - subsystem (``block``, ``tty``, ``pci``, ...) + - simple string, never a path or a link - retrieved by reading the "subsystem"-link and using only the last element of the target path - o driver (tg3, ata_piix, uhci_hcd) + - driver (``tg3``, ``ata_piix``, ``uhci_hcd``) + - a simple string, which may contain spaces, never a path or a link - it is retrieved by reading the "driver"-link and using only the @@ -75,110 +81,112 @@ versions of the sysfs interface. driver; copying the driver value in a child device context is a bug in the application - o attributes + - attributes + - the files in the device directory or files below subdirectories of the same device directory - accessing attributes reached by a symlink pointing to another device, like the "device"-link, is a bug in the application - Everything else is just a kernel driver-core implementation detail - that should not be assumed to be stable across kernel releases. + Everything else is just a kernel driver-core implementation detail + that should not be assumed to be stable across kernel releases. - Properties of parent devices never belong into a child device. - Always look at the parent devices themselves for determining device - context properties. If the device 'eth0' or 'sda' does not have a - "driver"-link, then this device does not have a driver. Its value is empty. - Never copy any property of the parent-device into a child-device. Parent - device properties may change dynamically without any notice to the - child device. + Always look at the parent devices themselves for determining device + context properties. If the device ``eth0`` or ``sda`` does not have a + "driver"-link, then this device does not have a driver. Its value is empty. + Never copy any property of the parent-device into a child-device. Parent + device properties may change dynamically without any notice to the + child device. - Hierarchy in a single device tree - There is only one valid place in sysfs where hierarchy can be examined - and this is below: /sys/devices. - It is planned that all device directories will end up in the tree - below this directory. + There is only one valid place in sysfs where hierarchy can be examined + and this is below: ``/sys/devices.`` + It is planned that all device directories will end up in the tree + below this directory. - Classification by subsystem - There are currently three places for classification of devices: - /sys/block, /sys/class and /sys/bus. It is planned that these will - not contain any device directories themselves, but only flat lists of - symlinks pointing to the unified /sys/devices tree. - All three places have completely different rules on how to access - device information. It is planned to merge all three - classification directories into one place at /sys/subsystem, - following the layout of the bus directories. All buses and - classes, including the converted block subsystem, will show up - there. - The devices belonging to a subsystem will create a symlink in the - "devices" directory at /sys/subsystem//devices. - - If /sys/subsystem exists, /sys/bus, /sys/class and /sys/block can be - ignored. If it does not exist, you always have to scan all three - places, as the kernel is free to move a subsystem from one place to - the other, as long as the devices are still reachable by the same - subsystem name. - - Assuming /sys/class/ and /sys/bus/, or - /sys/block and /sys/class/block are not interchangeable is a bug in - the application. + There are currently three places for classification of devices: + ``/sys/block,`` ``/sys/class`` and ``/sys/bus.`` It is planned that these will + not contain any device directories themselves, but only flat lists of + symlinks pointing to the unified ``/sys/devices`` tree. + All three places have completely different rules on how to access + device information. It is planned to merge all three + classification directories into one place at ``/sys/subsystem``, + following the layout of the bus directories. All buses and + classes, including the converted block subsystem, will show up + there. + The devices belonging to a subsystem will create a symlink in the + "devices" directory at ``/sys/subsystem//devices``, + + If ``/sys/subsystem`` exists, ``/sys/bus``, ``/sys/class`` and ``/sys/block`` + can be ignored. If it does not exist, you always have to scan all three + places, as the kernel is free to move a subsystem from one place to + the other, as long as the devices are still reachable by the same + subsystem name. + + Assuming ``/sys/class/`` and ``/sys/bus/``, or + ``/sys/block`` and ``/sys/class/block`` are not interchangeable is a bug in + the application. - Block - The converted block subsystem at /sys/class/block or - /sys/subsystem/block will contain the links for disks and partitions - at the same level, never in a hierarchy. Assuming the block subsystem to - contain only disks and not partition devices in the same flat list is - a bug in the application. + The converted block subsystem at ``/sys/class/block`` or + ``/sys/subsystem/block`` will contain the links for disks and partitions + at the same level, never in a hierarchy. Assuming the block subsystem to + contain only disks and not partition devices in the same flat list is + a bug in the application. - "device"-link and :-links - Never depend on the "device"-link. The "device"-link is a workaround - for the old layout, where class devices are not created in - /sys/devices/ like the bus devices. If the link-resolving of a - device directory does not end in /sys/devices/, you can use the - "device"-link to find the parent devices in /sys/devices/. That is the - single valid use of the "device"-link; it must never appear in any - path as an element. Assuming the existence of the "device"-link for - a device in /sys/devices/ is a bug in the application. - Accessing /sys/class/net/eth0/device is a bug in the application. - - Never depend on the class-specific links back to the /sys/class - directory. These links are also a workaround for the design mistake - that class devices are not created in /sys/devices. If a device - directory does not contain directories for child devices, these links - may be used to find the child devices in /sys/class. That is the single - valid use of these links; they must never appear in any path as an - element. Assuming the existence of these links for devices which are - real child device directories in the /sys/devices tree is a bug in - the application. - - It is planned to remove all these links when all class device - directories live in /sys/devices. + Never depend on the "device"-link. The "device"-link is a workaround + for the old layout, where class devices are not created in + ``/sys/devices/`` like the bus devices. If the link-resolving of a + device directory does not end in ``/sys/devices/``, you can use the + "device"-link to find the parent devices in ``/sys/devices/``, That is the + single valid use of the "device"-link; it must never appear in any + path as an element. Assuming the existence of the "device"-link for + a device in ``/sys/devices/`` is a bug in the application. + Accessing ``/sys/class/net/eth0/device`` is a bug in the application. + + Never depend on the class-specific links back to the ``/sys/class`` + directory. These links are also a workaround for the design mistake + that class devices are not created in ``/sys/devices.`` If a device + directory does not contain directories for child devices, these links + may be used to find the child devices in ``/sys/class.`` That is the single + valid use of these links; they must never appear in any path as an + element. Assuming the existence of these links for devices which are + real child device directories in the ``/sys/devices`` tree is a bug in + the application. + + It is planned to remove all these links when all class device + directories live in ``/sys/devices.`` - Position of devices along device chain can change. - Never depend on a specific parent device position in the devpath, - or the chain of parent devices. The kernel is free to insert devices into - the chain. You must always request the parent device you are looking for - by its subsystem value. You need to walk up the chain until you find - the device that matches the expected subsystem. Depending on a specific - position of a parent device or exposing relative paths using "../" to - access the chain of parents is a bug in the application. + Never depend on a specific parent device position in the devpath, + or the chain of parent devices. The kernel is free to insert devices into + the chain. You must always request the parent device you are looking for + by its subsystem value. You need to walk up the chain until you find + the device that matches the expected subsystem. Depending on a specific + position of a parent device or exposing relative paths using ``../`` to + access the chain of parents is a bug in the application. - When reading and writing sysfs device attribute files, avoid dependency - on specific error codes wherever possible. This minimizes coupling to - the error handling implementation within the kernel. + on specific error codes wherever possible. This minimizes coupling to + the error handling implementation within the kernel. - In general, failures to read or write sysfs device attributes shall - propagate errors wherever possible. Common errors include, but are not - limited to: + In general, failures to read or write sysfs device attributes shall + propagate errors wherever possible. Common errors include, but are not + limited to: - -EIO: The read or store operation is not supported, typically returned by - the sysfs system itself if the read or store pointer is NULL. + ``-EIO``: The read or store operation is not supported, typically + returned by the sysfs system itself if the read or store pointer + is ``NULL``. - -ENXIO: The read or store operation failed + ``-ENXIO``: The read or store operation failed - Error codes will not be changed without good reason, and should a change - to error codes result in user-space breakage, it will be fixed, or the - the offending change will be reverted. + Error codes will not be changed without good reason, and should a change + to error codes result in user-space breakage, it will be fixed, or the + the offending change will be reverted. - Userspace applications can, however, expect the format and contents of - the attribute files to remain consistent in the absence of a version - attribute change in the context of a given attribute. + Userspace applications can, however, expect the format and contents of + the attribute files to remain consistent in the absence of a version + attribute change in the context of a given attribute. -- cgit v1.2.3 From c8956bb7dd9525bba4155bf5a09022f036224b3c Mon Sep 17 00:00:00 2001 From: Mauro Carvalho Chehab Date: Fri, 23 Sep 2016 16:07:08 -0300 Subject: Documentation/sysrq.txt: convert to ReST markup - Fix document title; - use a table for the valid commands; - use quote blocks where needed; - use monotonic fonts for config options and file names; - adjust whitespaces and blank lines; - add it to the user's book. Signed-off-by: Mauro Carvalho Chehab --- Documentation/sysrq.txt | 266 +++++++++++++++++++++++++++--------------------- 1 file changed, 149 insertions(+), 117 deletions(-) diff --git a/Documentation/sysrq.txt b/Documentation/sysrq.txt index 3a3b30ac2a75..d1712ea2d314 100644 --- a/Documentation/sysrq.txt +++ b/Documentation/sysrq.txt @@ -1,23 +1,29 @@ Linux Magic System Request Key Hacks +==================================== + Documentation for sysrq.c -* What is the magic SysRq key? -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +What is the magic SysRq key? +~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + It is a 'magical' key combo you can hit which the kernel will respond to regardless of whatever else it is doing, unless it is completely locked up. -* How do I enable the magic SysRq key? -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +How do I enable the magic SysRq key? +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + You need to say "yes" to 'Magic SysRq key (CONFIG_MAGIC_SYSRQ)' when configuring the kernel. When running a kernel with SysRq compiled in, /proc/sys/kernel/sysrq controls the functions allowed to be invoked via the SysRq key. The default value in this file is set by the CONFIG_MAGIC_SYSRQ_DEFAULT_ENABLE config symbol, which itself defaults to 1. Here is the list of possible values in /proc/sys/kernel/sysrq: - 0 - disable sysrq completely - 1 - enable all functions of sysrq - >1 - bitmask of allowed sysrq functions (see below for detailed function - description): + + - 0 - disable sysrq completely + - 1 - enable all functions of sysrq + - >1 - bitmask of allowed sysrq functions (see below for detailed function + description):: + 2 = 0x2 - enable control of console logging level 4 = 0x4 - enable control of keyboard (SAK, unraw) 8 = 0x8 - enable debugging dumps of processes etc. @@ -27,112 +33,126 @@ to 1. Here is the list of possible values in /proc/sys/kernel/sysrq: 128 = 0x80 - allow reboot/poweroff 256 = 0x100 - allow nicing of all RT tasks -You can set the value in the file by the following command: +You can set the value in the file by the following command:: + echo "number" >/proc/sys/kernel/sysrq The number may be written here either as decimal or as hexadecimal with the 0x prefix. CONFIG_MAGIC_SYSRQ_DEFAULT_ENABLE must always be written in hexadecimal. -Note that the value of /proc/sys/kernel/sysrq influences only the invocation -via a keyboard. Invocation of any operation via /proc/sysrq-trigger is always -allowed (by a user with admin privileges). +Note that the value of ``/proc/sys/kernel/sysrq`` influences only the invocation +via a keyboard. Invocation of any operation via ``/proc/sysrq-trigger`` is +always allowed (by a user with admin privileges). -* How do I use the magic SysRq key? -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -On x86 - You press the key combo 'ALT-SysRq-'. Note - Some +How do I use the magic SysRq key? +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +On x86 - You press the key combo :kbd:`ALT-SysRq-`. + +.. note:: + Some keyboards may not have a key labeled 'SysRq'. The 'SysRq' key is also known as the 'Print Screen' key. Also some keyboards cannot handle so many keys being pressed at the same time, so you might - have better luck with "press Alt", "press SysRq", "release SysRq", - "press ", release everything. + have better luck with press :kbd:`Alt`, press :kbd:`SysRq`, + release :kbd:`SysRq`, press :kbd:``, release everything. -On SPARC - You press 'ALT-STOP-', I believe. +On SPARC - You press :kbd:`ALT-STOP-`, I believe. -On the serial console (PC style standard serial ports only) - - You send a BREAK, then within 5 seconds a command key. Sending - BREAK twice is interpreted as a normal BREAK. +On the serial console (PC style standard serial ports only) + You send a ``BREAK``, then within 5 seconds a command key. Sending + ``BREAK`` twice is interpreted as a normal BREAK. -On PowerPC - Press 'ALT - Print Screen (or F13) - , - Print Screen (or F13) - may suffice. +On PowerPC + Press :kbd:`ALT - Print Screen` (or :kbd:`F13`) - :kbd:``, + :kbd:`Print Screen` (or :kbd:`F13`) - :kbd:`` may suffice. -On other - If you know of the key combos for other architectures, please - let me know so I can add them to this section. +On other + If you know of the key combos for other architectures, please + let me know so I can add them to this section. -On all - write a character to /proc/sysrq-trigger. e.g.: +On all + write a character to /proc/sysrq-trigger. e.g.:: echo t > /proc/sysrq-trigger -* What are the 'command' keys? -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -'b' - Will immediately reboot the system without syncing or unmounting - your disks. +What are the 'command' keys? +~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -'c' - Will perform a system crash by a NULL pointer dereference. - A crashdump will be taken if configured. +=========== =================================================================== +Command Function +=========== =================================================================== +``b`` Will immediately reboot the system without syncing or unmounting + your disks. -'d' - Shows all locks that are held. +``c`` Will perform a system crash by a NULL pointer dereference. + A crashdump will be taken if configured. -'e' - Send a SIGTERM to all processes, except for init. +``d`` Shows all locks that are held. -'f' - Will call the oom killer to kill a memory hog process, but do not - panic if nothing can be killed. +``e`` Send a SIGTERM to all processes, except for init. -'g' - Used by kgdb (kernel debugger) +``f`` Will call the oom killer to kill a memory hog process, but do not + panic if nothing can be killed. -'h' - Will display help (actually any other key than those listed - here will display help. but 'h' is easy to remember :-) +``g`` Used by kgdb (kernel debugger) -'i' - Send a SIGKILL to all processes, except for init. +``h`` Will display help (actually any other key than those listed + here will display help. but ``h`` is easy to remember :-) -'j' - Forcibly "Just thaw it" - filesystems frozen by the FIFREEZE ioctl. +``i`` Send a SIGKILL to all processes, except for init. -'k' - Secure Access Key (SAK) Kills all programs on the current virtual - console. NOTE: See important comments below in SAK section. +``j`` Forcibly "Just thaw it" - filesystems frozen by the FIFREEZE ioctl. -'l' - Shows a stack backtrace for all active CPUs. +``k`` Secure Access Key (SAK) Kills all programs on the current virtual + console. NOTE: See important comments below in SAK section. -'m' - Will dump current memory info to your console. +``l`` Shows a stack backtrace for all active CPUs. -'n' - Used to make RT tasks nice-able +``m`` Will dump current memory info to your console. -'o' - Will shut your system off (if configured and supported). +``n`` Used to make RT tasks nice-able -'p' - Will dump the current registers and flags to your console. +``o`` Will shut your system off (if configured and supported). -'q' - Will dump per CPU lists of all armed hrtimers (but NOT regular - timer_list timers) and detailed information about all - clockevent devices. +``p`` Will dump the current registers and flags to your console. -'r' - Turns off keyboard raw mode and sets it to XLATE. +``q`` Will dump per CPU lists of all armed hrtimers (but NOT regular + timer_list timers) and detailed information about all + clockevent devices. -'s' - Will attempt to sync all mounted filesystems. +``r`` Turns off keyboard raw mode and sets it to XLATE. -'t' - Will dump a list of current tasks and their information to your - console. +``s`` Will attempt to sync all mounted filesystems. -'u' - Will attempt to remount all mounted filesystems read-only. +``t`` Will dump a list of current tasks and their information to your + console. -'v' - Forcefully restores framebuffer console -'v' - Causes ETM buffer dump [ARM-specific] +``u`` Will attempt to remount all mounted filesystems read-only. -'w' - Dumps tasks that are in uninterruptable (blocked) state. +``v`` Forcefully restores framebuffer console +``v`` Causes ETM buffer dump [ARM-specific] -'x' - Used by xmon interface on ppc/powerpc platforms. - Show global PMU Registers on sparc64. - Dump all TLB entries on MIPS. +``w`` Dumps tasks that are in uninterruptable (blocked) state. -'y' - Show global CPU Registers [SPARC-64 specific] +``x`` Used by xmon interface on ppc/powerpc platforms. + Show global PMU Registers on sparc64. + Dump all TLB entries on MIPS. -'z' - Dump the ftrace buffer +``y`` Show global CPU Registers [SPARC-64 specific] -'0'-'9' - Sets the console log level, controlling which kernel messages - will be printed to your console. ('0', for example would make - it so that only emergency messages like PANICs or OOPSes would - make it to your console.) +``z`` Dump the ftrace buffer + +``0``-``9`` Sets the console log level, controlling which kernel messages + will be printed to your console. (``0``, for example would make + it so that only emergency messages like PANICs or OOPSes would + make it to your console.) +=========== =================================================================== + +Okay, so what can I use them for? +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -* Okay, so what can I use them for? -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Well, unraw(r) is very handy when your X server or a svgalib program crashes. sak(k) (Secure Access Key) is useful when you want to be sure there is no @@ -140,73 +160,80 @@ trojan program running at console which could grab your password when you would try to login. It will kill all programs on given console, thus letting you make sure that the login prompt you see is actually the one from init, not some trojan program. -IMPORTANT: In its true form it is not a true SAK like the one in a :IMPORTANT -IMPORTANT: c2 compliant system, and it should not be mistaken as :IMPORTANT -IMPORTANT: such. :IMPORTANT - It seems others find it useful as (System Attention Key) which is + +.. important:: + + In its true form it is not a true SAK like the one in a + c2 compliant system, and it should not be mistaken as + such. + +It seems others find it useful as (System Attention Key) which is useful when you want to exit a program that will not let you switch consoles. (For example, X or a svgalib program.) -reboot(b) is good when you're unable to shut down. But you should also -sync(s) and umount(u) first. +``reboot(b)`` is good when you're unable to shut down. But you should also +``sync(s)`` and ``umount(u)`` first. -crash(c) can be used to manually trigger a crashdump when the system is hung. +``crash(c)`` can be used to manually trigger a crashdump when the system is hung. Note that this just triggers a crash if there is no dump mechanism available. -sync(s) is great when your system is locked up, it allows you to sync your +``sync(s)`` is great when your system is locked up, it allows you to sync your disks and will certainly lessen the chance of data loss and fscking. Note that the sync hasn't taken place until you see the "OK" and "Done" appear on the screen. (If the kernel is really in strife, you may not ever get the OK or Done message...) -umount(u) is basically useful in the same ways as sync(s). I generally sync(s), -umount(u), then reboot(b) when my system locks. It's saved me many a fsck. -Again, the unmount (remount read-only) hasn't taken place until you see the -"OK" and "Done" message appear on the screen. +``umount(u)`` is basically useful in the same ways as ``sync(s)``. I generally +``sync(s)``, ``umount(u)``, then ``reboot(b)`` when my system locks. It's saved +me many a fsck. Again, the unmount (remount read-only) hasn't taken place until +you see the "OK" and "Done" message appear on the screen. -The loglevels '0'-'9' are useful when your console is being flooded with -kernel messages you do not want to see. Selecting '0' will prevent all but +The loglevels ``0``-``9`` are useful when your console is being flooded with +kernel messages you do not want to see. Selecting ``0`` will prevent all but the most urgent kernel messages from reaching your console. (They will still be logged if syslogd/klogd are alive, though.) -term(e) and kill(i) are useful if you have some sort of runaway process you -are unable to kill any other way, especially if it's spawning other +``term(e)`` and ``kill(i)`` are useful if you have some sort of runaway process +you are unable to kill any other way, especially if it's spawning other processes. -"just thaw it(j)" is useful if your system becomes unresponsive due to a frozen -(probably root) filesystem via the FIFREEZE ioctl. +"just thaw ``it(j)``" is useful if your system becomes unresponsive due to a +frozen (probably root) filesystem via the FIFREEZE ioctl. + +Sometimes SysRq seems to get 'stuck' after using it, what can I do? +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -* Sometimes SysRq seems to get 'stuck' after using it, what can I do? -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ That happens to me, also. I've found that tapping shift, alt, and control on both sides of the keyboard, and hitting an invalid sysrq sequence again -will fix the problem. (i.e., something like alt-sysrq-z). Switching to another -virtual console (ALT+Fn) and then back again should also help. +will fix the problem. (i.e., something like :kbd:`alt-sysrq-z`). Switching to +another virtual console (:kbd:`ALT+Fn`) and then back again should also help. + +I hit SysRq, but nothing seems to happen, what's wrong? +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -* I hit SysRq, but nothing seems to happen, what's wrong? -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ There are some keyboards that produce a different keycode for SysRq than the -pre-defined value of 99 (see KEY_SYSRQ in include/linux/input.h), or which -don't have a SysRq key at all. In these cases, run 'showkey -s' to find an -appropriate scancode sequence, and use 'setkeycodes 99' to map -this sequence to the usual SysRq code (e.g., 'setkeycodes e05b 99'). It's +pre-defined value of 99 (see ``KEY_SYSRQ`` in ``include/linux/input.h``), or +which don't have a SysRq key at all. In these cases, run ``showkey -s`` to find +an appropriate scancode sequence, and use ``setkeycodes 99`` to map +this sequence to the usual SysRq code (e.g., ``setkeycodes e05b 99``). It's probably best to put this command in a boot script. Oh, and by the way, you -exit 'showkey' by not typing anything for ten seconds. +exit ``showkey`` by not typing anything for ten seconds. + +I want to add SysRQ key events to a module, how does it work? +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -* I want to add SysRQ key events to a module, how does it work? -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ In order to register a basic function with the table, you must first include -the header 'include/linux/sysrq.h', this will define everything else you need. -Next, you must create a sysrq_key_op struct, and populate it with A) the key +the header ``include/linux/sysrq.h``, this will define everything else you need. +Next, you must create a ``sysrq_key_op`` struct, and populate it with A) the key handler function you will use, B) a help_msg string, that will print when SysRQ prints help, and C) an action_msg string, that will print right before your handler is called. Your handler must conform to the prototype in 'sysrq.h'. -After the sysrq_key_op is created, you can call the kernel function -register_sysrq_key(int key, struct sysrq_key_op *op_p); this will -register the operation pointed to by 'op_p' at table key 'key', +After the ``sysrq_key_op`` is created, you can call the kernel function +``register_sysrq_key(int key, struct sysrq_key_op *op_p);`` this will +register the operation pointed to by ``op_p`` at table key 'key', if that slot in the table is blank. At module unload time, you must call -the function unregister_sysrq_key(int key, struct sysrq_key_op *op_p), which +the function ``unregister_sysrq_key(int key, struct sysrq_key_op *op_p)``, which will remove the key op pointed to by 'op_p' from the key 'key', if and only if it is currently registered in that slot. This is in case the slot has been overwritten since you registered it. @@ -214,8 +241,10 @@ overwritten since you registered it. The Magic SysRQ system works by registering key operations against a key op lookup table, which is defined in 'drivers/tty/sysrq.c'. This key table has a number of operations registered into it at compile time, but is mutable, -and 2 functions are exported for interface to it: +and 2 functions are exported for interface to it:: + register_sysrq_key and unregister_sysrq_key. + Of course, never ever leave an invalid pointer in the table. I.e., when your module that called register_sysrq_key() exits, it must call unregister_sysrq_key() to clean up the sysrq key table entry that it used. @@ -224,33 +253,36 @@ Null pointers in the table are always safe. :) If for some reason you feel the need to call the handle_sysrq function from within a function called by handle_sysrq, you must be aware that you are in a lock (you are also in an interrupt handler, which means don't sleep!), so -you must call __handle_sysrq_nolock instead. +you must call ``__handle_sysrq_nolock`` instead. + +When I hit a SysRq key combination only the header appears on the console? +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -* When I hit a SysRq key combination only the header appears on the console? -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Sysrq output is subject to the same console loglevel control as all other console output. This means that if the kernel was booted 'quiet' as is common on distro kernels the output may not appear on the actual console, even though it will appear in the dmesg buffer, and be accessible -via the dmesg command and to the consumers of /proc/kmsg. As a specific +via the dmesg command and to the consumers of ``/proc/kmsg``. As a specific exception the header line from the sysrq command is passed to all console consumers as if the current loglevel was maximum. If only the header is emitted it is almost certain that the kernel loglevel is too low. Should you require the output on the console channel then you will need -to temporarily up the console loglevel using alt-sysrq-8 or: +to temporarily up the console loglevel using :kbd:`alt-sysrq-8` or:: echo 8 > /proc/sysrq-trigger Remember to return the loglevel to normal after triggering the sysrq command you are interested in. -* I have more questions, who can I ask? -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +I have more questions, who can I ask? +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + Just ask them on the linux-kernel mailing list: linux-kernel@vger.kernel.org -* Credits -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +Credits +~~~~~~~ + Written by Mydraal Updated by Adam Sulmicki Updated by Jeremy M. Dolan 2001/01/28 10:15:59 -- cgit v1.2.3 From 77514391ee1af3adaa33219109d2ca81fc09e30e Mon Sep 17 00:00:00 2001 From: Mauro Carvalho Chehab Date: Fri, 23 Sep 2016 16:14:29 -0300 Subject: Documentation/unicode.txt: convert it to ReST markup Probably, unicode is something that we might remove from the docs, as all modern systems support it. Yet, this chapter is fun, as it mentions support for the Klington fictional charset ;) On the other hand, I bet all other OS user manuals explicit mention unicode support. So, convert it to ReST and include it at the user's book. Signed-off-by: Mauro Carvalho Chehab --- Documentation/unicode.txt | 22 ++++++++++++++++++---- 1 file changed, 18 insertions(+), 4 deletions(-) diff --git a/Documentation/unicode.txt b/Documentation/unicode.txt index 4a33f81cadb1..012e8e895842 100644 --- a/Documentation/unicode.txt +++ b/Documentation/unicode.txt @@ -1,3 +1,6 @@ +Unicode support +=============== + Last update: 2005-01-17, version 1.4 This file is maintained by H. Peter Anvin as part @@ -6,7 +9,8 @@ The current version can be found at: http://www.lanana.org/docs/unicode/unicode.txt - ------------------------ +Introdution +----------- The Linux kernel code has been rewritten to use Unicode to map characters to fonts. By downloading a single Unicode-to-font table, @@ -16,12 +20,14 @@ the font as indicated. This changes the semantics of the eight-bit character tables subtly. The four character tables are now: +=============== =============================== ================ Map symbol Map name Escape code (G0) - +=============== =============================== ================ LAT1_MAP Latin-1 (ISO 8859-1) ESC ( B GRAF_MAP DEC VT100 pseudographics ESC ( 0 IBMPC_MAP IBM code page 437 ESC ( U USER_MAP User defined ESC ( K +=============== =============================== ================ In particular, ESC ( U is no longer "straight to font", since the font might be completely different than the IBM character set. This @@ -55,10 +61,12 @@ In addition, the following characters not present in Unicode 1.1.4 have been defined; these are used by the DEC VT graphics map. [v1.2] THIS USE IS OBSOLETE AND SHOULD NO LONGER BE USED; PLEASE SEE BELOW. +====== ====================================== U+F800 DEC VT GRAPHICS HORIZONTAL LINE SCAN 1 U+F801 DEC VT GRAPHICS HORIZONTAL LINE SCAN 3 U+F803 DEC VT GRAPHICS HORIZONTAL LINE SCAN 7 U+F804 DEC VT GRAPHICS HORIZONTAL LINE SCAN 9 +====== ====================================== The DEC VT220 uses a 6x10 character matrix, and these characters form a smooth progression in the DEC VT graphics character set. I have @@ -74,10 +82,12 @@ keyboard symbols that are unlikely to ever be added to Unicode proper since they are horribly vendor-specific. This, of course, is an excellent example of horrible design. +====== ====================================== U+F810 KEYBOARD SYMBOL FLYING FLAG U+F811 KEYBOARD SYMBOL PULLDOWN MENU U+F812 KEYBOARD SYMBOL OPEN APPLE U+F813 KEYBOARD SYMBOL SOLID APPLE +====== ====================================== Klingon language support ------------------------ @@ -99,8 +109,10 @@ of the dingbats/symbols/forms type and this is a language, I have located it at the end, on a 16-cell boundary in keeping with standard Unicode practice. -NOTE: This range is now officially managed by the ConScript Unicode -Registry. The normative reference is at: +.. note:: + + This range is now officially managed by the ConScript Unicode + Registry. The normative reference is at: http://www.evertype.com/standards/csur/klingon.html @@ -112,6 +124,7 @@ However, since the set of symbols appear to be consistent throughout, with only the actual shapes being different, in keeping with standard Unicode practice these differences are considered font variants. +====== ======================================================= U+F8D0 KLINGON LETTER A U+F8D1 KLINGON LETTER B U+F8D2 KLINGON LETTER CH @@ -155,6 +168,7 @@ U+F8F9 KLINGON DIGIT NINE U+F8FD KLINGON COMMA U+F8FE KLINGON FULL STOP U+F8FF KLINGON SYMBOL FOR EMPIRE +====== ======================================================= Other Fictional and Artificial Scripts -------------------------------------- -- cgit v1.2.3 From 27641b953c54643acfd28fcd9ebbe03cdc724605 Mon Sep 17 00:00:00 2001 From: Mauro Carvalho Chehab Date: Fri, 23 Sep 2016 16:26:03 -0300 Subject: Documentation/VGA-softcursor.txt: convert to ReST markup - Fix document title; - use quote blocks where needed; - use monotonic fonts for config options and file names; - adjust whitespaces and blank lines; - add it to the user's book. Signed-off-by: Mauro Carvalho Chehab --- Documentation/VGA-softcursor.txt | 73 +++++++++++++++++++++++++++------------- 1 file changed, 50 insertions(+), 23 deletions(-) diff --git a/Documentation/VGA-softcursor.txt b/Documentation/VGA-softcursor.txt index 70acfbf399eb..9eac6744b3a1 100644 --- a/Documentation/VGA-softcursor.txt +++ b/Documentation/VGA-softcursor.txt @@ -1,39 +1,66 @@ -Software cursor for VGA by Pavel Machek -======================= and Martin Mares +Software cursor for VGA +======================= - Linux now has some ability to manipulate cursor appearance. Normally, you +by Pavel Machek +and Martin Mares + +Linux now has some ability to manipulate cursor appearance. Normally, you can set the size of hardware cursor (and also work around some ugly bugs in -those miserable Trident cards--see #define TRIDENT_GLITCH in drivers/video/ -vgacon.c). You can now play a few new tricks: you can make your cursor look +those miserable Trident cards [#f1]_. You can now play a few new tricks: +you can make your cursor look + like a non-blinking red block, make it inverse background of the character it's over or to highlight that character and still choose whether the original hardware cursor should remain visible or not. There may be other things I have never thought of. - The cursor appearance is controlled by a "[?1;2;3c" escape sequence +The cursor appearance is controlled by a ``[?1;2;3c`` escape sequence where 1, 2 and 3 are parameters described below. If you omit any of them, they will default to zeroes. - Parameter 1 specifies cursor size (0=default, 1=invisible, 2=underline, ..., -8=full block) + 16 if you want the software cursor to be applied + 32 if you -want to always change the background color + 64 if you dislike having the -background the same as the foreground. Highlights are ignored for the last two -flags. +first Parameter + specifies cursor size:: + + 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. + +second parameter + selects character attribute bits you want to change + (by simply XORing them with the value of this parameter). On standard + VGA, the high four bits specify background and the low four the + foreground. In both groups, low three bits set color (as in normal + color codes used by the console) and the most significant one turns + on highlight (or sometimes blinking -- it depends on the configuration + of your VGA). + +third parameter + consists of character attribute bits you want to set. - 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). + 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. - 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. +.. [#f1] see ``#define TRIDENT_GLITCH`` in ``drivers/video/vgacon.c``. Examples: ========= -To get normal blinking underline, use: echo -e '\033[?2c' -To get blinking block, use: echo -e '\033[?6c' -To get red non-blinking block, use: echo -e '\033[?17;0;64c' +To get normal blinking underline, use:: + + echo -e '\033[?2c' + +To get blinking block, use:: + + echo -e '\033[?6c' + +To get red non-blinking block, use:: + + echo -e '\033[?17;0;64c' -- cgit v1.2.3 From 9c27d77d999491d6c80c570887dc95d32908cae5 Mon Sep 17 00:00:00 2001 From: Mauro Carvalho Chehab Date: Fri, 23 Sep 2016 16:33:27 -0300 Subject: Documentation/volatile-considered-harmful.txt: convert to ReST markup - Fix document section markups; - use quote blocks where needed; - adjust spaces and blank lines; - add it to the development-processs book. Signed-off-by: Mauro Carvalho Chehab --- Documentation/volatile-considered-harmful.txt | 19 +++++++++++-------- 1 file changed, 11 insertions(+), 8 deletions(-) diff --git a/Documentation/volatile-considered-harmful.txt b/Documentation/volatile-considered-harmful.txt index db0cb228d64a..e0d042af386c 100644 --- a/Documentation/volatile-considered-harmful.txt +++ b/Documentation/volatile-considered-harmful.txt @@ -22,7 +22,7 @@ need to use volatile as well. If volatile is still necessary, there is almost certainly a bug in the code somewhere. In properly-written kernel code, volatile can only serve to slow things down. -Consider a typical block of kernel code: +Consider a typical block of kernel code:: spin_lock(&the_lock); do_something_on(&shared_data); @@ -57,7 +57,7 @@ optimization, so, once again, volatile is unnecessary. Another situation where one might be tempted to use volatile is when the processor is busy-waiting on the value of a variable. The right -way to perform a busy wait is: +way to perform a busy wait is:: while (my_variable != what_i_want) cpu_relax(); @@ -103,17 +103,20 @@ they come with a justification which shows that the concurrency issues have been properly thought through. -NOTES ------ +References +========== [1] http://lwn.net/Articles/233481/ + [2] http://lwn.net/Articles/233482/ -CREDITS -------- +Credits +======= Original impetus and research by Randy Dunlap + Written by Jonathan Corbet + Improvements via comments from Satyam Sharma, Johannes Stezenbach, Jesper - Juhl, Heikki Orsila, H. Peter Anvin, Philipp Hahn, and Stefan - Richter. +Juhl, Heikki Orsila, H. Peter Anvin, Philipp Hahn, and Stefan +Richter. -- cgit v1.2.3 From 35a1beb9c45d62d1e22e5d4274a220dfa6246cce Mon Sep 17 00:00:00 2001 From: Mauro Carvalho Chehab Date: Fri, 23 Sep 2016 17:22:55 -0300 Subject: Documentation/parport.txt: fix table to show on LaTeX Sphinx doesn't like nested tables on the LaTex output. So, change the table there to be displayed properly at the PDF output. Signed-off-by: Mauro Carvalho Chehab --- Documentation/parport.txt | 33 ++++++++++++++++++++++----------- 1 file changed, 22 insertions(+), 11 deletions(-) diff --git a/Documentation/parport.txt b/Documentation/parport.txt index 3273ce79f9e3..ad3f9b8a11e1 100644 --- a/Documentation/parport.txt +++ b/Documentation/parport.txt @@ -132,6 +132,8 @@ The ``/proc/sys/dev/parport`` directory tree looks like:: |-- modes `-- spintime +.. tabularcolumns:: |p{4.0cm}|p{13.5cm}| + ======================= ======================================================= File Contents ======================= ======================================================= @@ -154,17 +156,26 @@ File Contents ``modes`` Parallel port's hardware modes, comma-separated, meaning: - =============== ======================================= - PCSPP PC-style SPP registers are available. - TRISTATE Port is bidirectional. - COMPAT Hardware acceleration for printers is - available and will be used. - EPP Hardware acceleration for EPP protocol - is available and will be used. - ECP Hardware acceleration for ECP protocol - is available and will be used. - DMA DMA is available and will be used. - =============== ======================================= + - PCSPP + PC-style SPP registers are available. + + - TRISTATE + Port is bidirectional. + + - COMPAT + Hardware acceleration for printers is + available and will be used. + + - EPP + Hardware acceleration for EPP protocol + is available and will be used. + + - ECP + Hardware acceleration for ECP protocol + is available and will be used. + + - DMA + DMA is available and will be used. Note that the current implementation will only take advantage of COMPAT and ECP modes if it has an IRQ -- cgit v1.2.3 From 8c287de37b2cd4ae9ef95a9e83d7e0da3d60aa1f Mon Sep 17 00:00:00 2001 From: Mauro Carvalho Chehab Date: Tue, 18 Oct 2016 11:57:16 -0200 Subject: Documentation/CodeOfConflict: convert to ReST Fix ReST notation for a bullet item Signed-off-by: Mauro Carvalho Chehab --- Documentation/CodeOfConflict | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/Documentation/CodeOfConflict b/Documentation/CodeOfConflict index 49a8ecc157a2..47b6de763203 100644 --- a/Documentation/CodeOfConflict +++ b/Documentation/CodeOfConflict @@ -19,7 +19,8 @@ please contact the Linux Foundation's Technical Advisory Board at will work to resolve the issue to the best of their ability. For more information on who is on the Technical Advisory Board and what their role is, please see: - http://www.linuxfoundation.org/projects/linux/tab + + - http://www.linuxfoundation.org/projects/linux/tab As a reviewer of code, please strive to keep things civil and focused on the technical issues involved. We are all humans, and frustrations can -- cgit v1.2.3 From afeb000e1a0596e89174a85c96e890f4f0e802e0 Mon Sep 17 00:00:00 2001 From: Mauro Carvalho Chehab Date: Wed, 21 Sep 2016 09:27:00 -0300 Subject: REPORTING-BUGS: convert to ReST markup - add a title to the document; - use :: before verbatim blocks; - add blank lines where required; - use protocol for URL references; - use a verbatim block for the bugs template; - add cross references to SecurityBugs. Signed-off-by: Mauro Carvalho Chehab --- REPORTING-BUGS | 68 ++++++++++++++++++++++++++++++++-------------------------- 1 file changed, 38 insertions(+), 30 deletions(-) diff --git a/REPORTING-BUGS b/REPORTING-BUGS index 914baf9cf5fa..05c53ac7fa76 100644 --- a/REPORTING-BUGS +++ b/REPORTING-BUGS @@ -1,3 +1,8 @@ +.. _reportingbugs: + +Reporting bugs +++++++++++++++ + Background ========== @@ -50,12 +55,13 @@ maintainer replies to you, make sure to 'Reply-all' in order to keep the public mailing list(s) in the email thread. If you know which driver is causing issues, you can pass one of the driver -files to the get_maintainer.pl script: +files to the get_maintainer.pl script:: + perl scripts/get_maintainer.pl -f If it is a security bug, please copy the Security Contact listed in the MAINTAINERS file. They can help coordinate bugfix and disclosure. See -Documentation/SecurityBugs for more information. +:ref:`Documentation/SecurityBugs ` for more information. If you can't figure out which subsystem caused the issue, you should file a bug in kernel.org bugzilla and send email to @@ -69,8 +75,9 @@ Tips for reporting bugs If you haven't reported a bug before, please read: -http://www.chiark.greenend.org.uk/~sgtatham/bugs.html -http://www.catb.org/esr/faqs/smart-questions.html + http://www.chiark.greenend.org.uk/~sgtatham/bugs.html + + http://www.catb.org/esr/faqs/smart-questions.html It's REALLY important to report bugs that seem unrelated as separate email threads or separate bugzilla entries. If you report several unrelated @@ -99,34 +106,34 @@ relevant to your bug, feel free to exclude it. First run the ver_linux script included as scripts/ver_linux, which reports the version of some important subsystems. Run this script with -the command "sh scripts/ver_linux". +the command ``sh scripts/ver_linux``. Use that information to fill in all fields of the bug report form, and post it to the mailing list with a subject of "PROBLEM: " for easy identification by the developers. - -[1.] One line summary of the problem: -[2.] Full description of the problem/report: -[3.] Keywords (i.e., modules, networking, kernel): -[4.] Kernel information -[4.1.] Kernel version (from /proc/version): -[4.2.] Kernel .config file: -[5.] Most recent kernel version which did not have the bug: -[6.] Output of Oops.. message (if applicable) with symbolic information - resolved (see Documentation/oops-tracing.txt) -[7.] A small shell script or example program which triggers the - problem (if possible) -[8.] Environment -[8.1.] Software (add the output of the ver_linux script here) -[8.2.] Processor information (from /proc/cpuinfo): -[8.3.] Module information (from /proc/modules): -[8.4.] Loaded driver and hardware information (/proc/ioports, /proc/iomem) -[8.5.] PCI information ('lspci -vvv' as root) -[8.6.] SCSI information (from /proc/scsi/scsi) -[8.7.] Other information that might be relevant to the problem - (please look in /proc and include all information that you - think to be relevant): -[X.] Other notes, patches, fixes, workarounds: +summary from [1.]>" for easy identification by the developers:: + + [1.] One line summary of the problem: + [2.] Full description of the problem/report: + [3.] Keywords (i.e., modules, networking, kernel): + [4.] Kernel information + [4.1.] Kernel version (from /proc/version): + [4.2.] Kernel .config file: + [5.] Most recent kernel version which did not have the bug: + [6.] Output of Oops.. message (if applicable) with symbolic information + resolved (see Documentation/oops-tracing.txt) + [7.] A small shell script or example program which triggers the + problem (if possible) + [8.] Environment + [8.1.] Software (add the output of the ver_linux script here) + [8.2.] Processor information (from /proc/cpuinfo): + [8.3.] Module information (from /proc/modules): + [8.4.] Loaded driver and hardware information (/proc/ioports, /proc/iomem) + [8.5.] PCI information ('lspci -vvv' as root) + [8.6.] SCSI information (from /proc/scsi/scsi) + [8.7.] Other information that might be relevant to the problem + (please look in /proc and include all information that you + think to be relevant): + [X.] Other notes, patches, fixes, workarounds: Follow up @@ -153,7 +160,8 @@ Expectations for kernel maintainers Linux kernel maintainers are busy, overworked human beings. Some times they may not be able to address your bug in a day, a week, or two weeks. If they don't answer your email, they may be on vacation, or at a Linux -conference. Check the conference schedule at LWN.net for more info: +conference. Check the conference schedule at https://LWN.net for more info: + https://lwn.net/Calendar/ In general, kernel maintainers take 1 to 5 business days to respond to -- cgit v1.2.3 From 44b10006a97ec50874634ba5325a6499ead7db66 Mon Sep 17 00:00:00 2001 From: Mauro Carvalho Chehab Date: Wed, 21 Sep 2016 09:09:49 -0300 Subject: README: convert it to ReST markup Adjust the readme file for it to use the ReST markup: - add chapter/section markups; - use ``foo`` for commands; - use :: for verbatim and script blocks; - replace unsupported markup _foo_ by **foo**; - add cross-references to other ReST files; - use lower case on the section titles, to match other ReST files. Signed-off-by: Mauro Carvalho Chehab --- README | 105 ++++++++++++++++++++++++++++++++++++----------------------------- 1 file changed, 58 insertions(+), 47 deletions(-) diff --git a/README b/README index 09f34f78f2bb..3335b3b2973a 100644 --- a/README +++ b/README @@ -1,10 +1,12 @@ - Linux kernel release 4.x +Linux kernel release 4.x +============================================= These are the release notes for Linux version 4. Read them carefully, as they tell you what this is all about, explain how to install the kernel, and what to do if something goes wrong. -WHAT IS LINUX? +What is Linux? +-------------- Linux is a clone of the operating system Unix, written from scratch by Linus Torvalds with assistance from a loosely-knit team of hackers across @@ -18,7 +20,8 @@ WHAT IS LINUX? It is distributed under the GNU General Public License - see the accompanying COPYING file for more details. -ON WHAT HARDWARE DOES IT RUN? +On what hardware does it run? +----------------------------- Although originally developed first for 32-bit x86-based PCs (386 or higher), today Linux also runs on (at least) the Compaq Alpha AXP, Sun SPARC and @@ -34,7 +37,8 @@ ON WHAT HARDWARE DOES IT RUN? Linux has also been ported to itself. You can now run the kernel as a userspace application - this is called UserMode Linux (UML). -DOCUMENTATION: +Documentation +------------- - There is a lot of documentation available both in electronic form on the Internet and in books, both Linux-specific and pertaining to @@ -53,14 +57,15 @@ DOCUMENTATION: - The Documentation/DocBook/ subdirectory contains several guides for kernel developers and users. These guides can be rendered in a number of formats: PostScript (.ps), PDF, HTML, & man-pages, among others. - After installation, "make psdocs", "make pdfdocs", "make htmldocs", - or "make mandocs" will render the documentation in the requested format. + After installation, ``make psdocs``, ``make pdfdocs``, ``make htmldocs``, + or ``make mandocs`` will render the documentation in the requested format. -INSTALLING the kernel source: +Installing the kernel source +---------------------------- - If you install the full sources, put the kernel tarball in a directory where you have permissions (e.g. your home directory) and - unpack it: + unpack it:: xz -cd linux-4.X.tar.xz | tar xvf - @@ -74,12 +79,12 @@ INSTALLING the kernel source: - You can also upgrade between 4.x releases by patching. Patches are distributed in the xz format. To install by patching, get all the newer patch files, enter the top level directory of the kernel source - (linux-4.X) and execute: + (linux-4.X) and execute:: xz -cd ../patch-4.x.xz | patch -p1 Replace "x" for all versions bigger than the version "X" of your current - source tree, _in_order_, and you should be ok. You may want to remove + source tree, **in_order**, and you should be ok. You may want to remove the backup files (some-file-name~ or some-file-name.orig), and make sure that there are no failed patches (some-file-name# or some-file-name.rej). If there are, either you or I have made a mistake. @@ -90,12 +95,12 @@ INSTALLING the kernel source: and you want to apply the 4.0.3 patch, you must not first apply the 4.0.1 and 4.0.2 patches. Similarly, if you are running kernel version 4.0.2 and want to jump to 4.0.3, you must first reverse the 4.0.2 patch (that is, - patch -R) _before_ applying the 4.0.3 patch. You can read more on this in - Documentation/applying-patches.txt + patch -R) **before** applying the 4.0.3 patch. You can read more on this in + :ref:`Documentation/applying-patches.txt `. Alternatively, the script patch-kernel can be used to automate this process. It determines the current kernel version and applies any - patches found. + patches found:: linux/scripts/patch-kernel linux @@ -103,55 +108,58 @@ INSTALLING the kernel source: kernel source. Patches are applied from the current directory, but an alternative directory can be specified as the second argument. - - Make sure you have no stale .o files and dependencies lying around: + - Make sure you have no stale .o files and dependencies lying around:: cd linux make mrproper You should now have the sources correctly installed. -SOFTWARE REQUIREMENTS +Software requirements +--------------------- Compiling and running the 4.x kernels requires up-to-date versions of various software packages. Consult - Documentation/Changes for the minimum version numbers required - and how to get updates for these packages. Beware that using + :ref:`Documentation/Changes ` for the minimum version numbers + required and how to get updates for these packages. Beware that using excessively old versions of these packages can cause indirect errors that are very difficult to track down, so don't assume that you can just update packages when obvious problems arise during build or operation. -BUILD directory for the kernel: +Build directory for the kernel +------------------------------ When compiling the kernel, all output files will per default be stored together with the kernel source code. - Using the option "make O=output/dir" allows you to specify an alternate + Using the option ``make O=output/dir`` allows you to specify an alternate place for the output files (including .config). - Example: + Example:: kernel source code: /usr/src/linux-4.X build directory: /home/name/build/kernel - To configure and build the kernel, use: + To configure and build the kernel, use:: cd /usr/src/linux-4.X make O=/home/name/build/kernel menuconfig make O=/home/name/build/kernel sudo make O=/home/name/build/kernel modules_install install - Please note: If the 'O=output/dir' option is used, then it must be + Please note: If the ``O=output/dir`` option is used, then it must be used for all invocations of make. -CONFIGURING the kernel: +Configuring the kernel +---------------------- Do not skip this step even if you are only upgrading one minor version. New configuration options are added in each release, and odd problems will turn up if the configuration files are not set up as expected. If you want to carry your existing configuration to a - new version with minimal work, use "make oldconfig", which will + new version with minimal work, use ``make oldconfig``, which will only ask you for the answers to new questions. - - Alternative configuration commands are: + - Alternative configuration commands are:: "make config" Plain text interface. @@ -223,7 +231,7 @@ CONFIGURING the kernel: You can find more information on using the Linux kernel config tools in Documentation/kbuild/kconfig.txt. - - NOTES on "make config": + - NOTES on ``make config``: - Having unnecessary drivers will make the kernel bigger, and can under some circumstances lead to problems: probing for a @@ -242,22 +250,23 @@ CONFIGURING the kernel: should probably answer 'n' to the questions for "development", "experimental", or "debugging" features. -COMPILING the kernel: +Compiling the kernel +-------------------- - Make sure you have at least gcc 3.2 available. - For more information, refer to Documentation/Changes. + For more information, refer to :ref:`Documentation/Changes `. Please note that you can still run a.out user programs with this kernel. - - Do a "make" to create a compressed kernel image. It is also - possible to do "make install" if you have lilo installed to suit the + - Do a ``make`` to create a compressed kernel image. It is also + possible to do ``make install`` if you have lilo installed to suit the kernel makefiles, but you may want to check your particular lilo setup first. To do the actual install, you have to be root, but none of the normal build should require that. Don't take the name of root in vain. - - If you configured any of the parts of the kernel as `modules', you - will also have to do "make modules_install". + - If you configured any of the parts of the kernel as ``modules``, you + will also have to do ``make modules_install``. - Verbose kernel compile/build output: @@ -265,12 +274,12 @@ COMPILING the kernel: totally silent). However, sometimes you or other kernel developers need to see compile, link, or other commands exactly as they are executed. For this, use "verbose" build mode. This is done by passing - "V=1" to the "make" command, e.g. + ``V=1`` to the ``make`` command, e.g.:: make V=1 all To have the build system also tell the reason for the rebuild of each - target, use "V=2". The default is "V=0". + target, use ``V=2``. The default is ``V=0``. - Keep a backup kernel handy in case something goes wrong. This is especially true for the development releases, since each new release @@ -278,7 +287,7 @@ COMPILING the kernel: backup of the modules corresponding to that kernel, as well. If you are installing a new kernel with the same version number as your working kernel, make a backup of your modules directory before you - do a "make modules_install". + do a ``make modules_install``. Alternatively, before compiling, use the kernel config option "LOCALVERSION" to append a unique suffix to the regular kernel version. @@ -308,13 +317,14 @@ COMPILING the kernel: reboot, and enjoy! If you ever need to change the default root device, video mode, - ramdisk size, etc. in the kernel image, use the 'rdev' program (or + ramdisk size, etc. in the kernel image, use the ``rdev`` program (or alternatively the LILO boot options when appropriate). No need to recompile the kernel to change these parameters. - Reboot with the new kernel and enjoy. -IF SOMETHING GOES WRONG: +If something goes wrong +----------------------- - If you have problems that seem to be due to kernel bugs, please check the file MAINTAINERS to see if there is a particular person associated @@ -328,7 +338,7 @@ IF SOMETHING GOES WRONG: sense). If the problem is new, tell me so, and if the problem is old, please try to tell me when you first noticed it. - - If the bug results in a message like + - If the bug results in a message like:: unable to handle kernel paging request at address C0000010 Oops: 0002 @@ -348,7 +358,7 @@ IF SOMETHING GOES WRONG: on making sense of the dump is in Documentation/oops-tracing.txt - If you compiled the kernel with CONFIG_KALLSYMS you can send the dump - as is, otherwise you will have to use the "ksymoops" program to make + as is, otherwise you will have to use the ``ksymoops`` program to make sense of the dump (but compiling with CONFIG_KALLSYMS is usually preferred). This utility can be downloaded from ftp://ftp..kernel.org/pub/linux/utils/kernel/ksymoops/ . @@ -358,13 +368,13 @@ IF SOMETHING GOES WRONG: look up what the EIP value means. The hex value as such doesn't help me or anybody else very much: it will depend on your particular kernel setup. What you should do is take the hex value from the EIP - line (ignore the "0010:"), and look it up in the kernel namelist to + line (ignore the ``0010:``), and look it up in the kernel namelist to see which kernel function contains the offending address. To find out the kernel function name, you'll need to find the system binary associated with the kernel that exhibited the symptom. This is the file 'linux/vmlinux'. To extract the namelist and match it against - the EIP from the kernel crash, do: + the EIP from the kernel crash, do:: nm vmlinux | sort | less @@ -383,18 +393,19 @@ IF SOMETHING GOES WRONG: If you for some reason cannot do the above (you have a pre-compiled kernel image or similar), telling me as much about your setup as - possible will help. Please read the REPORTING-BUGS document for details. + possible will help. Please read the :ref:`REPORTING-BUGS ` + document for details. - Alternatively, you can use gdb on a running kernel. (read-only; i.e. you cannot change values or set break points.) To do this, first compile the - kernel with -g; edit arch/x86/Makefile appropriately, then do a "make - clean". You'll also need to enable CONFIG_PROC_FS (via "make config"). + kernel with -g; edit arch/x86/Makefile appropriately, then do a ``make + clean``. You'll also need to enable CONFIG_PROC_FS (via ``make config``). - After you've rebooted with the new kernel, do "gdb vmlinux /proc/kcore". + After you've rebooted with the new kernel, do ``gdb vmlinux /proc/kcore``. You can now use all the usual gdb commands. The command to look up the - point where your system crashed is "l *0xXXXXXXXX". (Replace the XXXes + point where your system crashed is ``l *0xXXXXXXXX``. (Replace the XXXes with the EIP value.) - gdb'ing a non-running kernel currently fails because gdb (wrongly) + gdb'ing a non-running kernel currently fails because ``gdb`` (wrongly) disregards the starting offset for which the kernel is compiled. -- cgit v1.2.3 From 0e4f07a65f53e7b3afab71925e56fe6aaa07d696 Mon Sep 17 00:00:00 2001 From: Mauro Carvalho Chehab Date: Tue, 18 Oct 2016 09:05:32 -0200 Subject: docs: rename development-process/ to process/ As we'll type this a lot, after adding CodingStyle & friends, let's rename the directory name to a shorter one. Signed-off-by: Mauro Carvalho Chehab --- Documentation/00-INDEX | 2 +- Documentation/SubmittingPatches | 2 +- Documentation/conf.py | 2 +- Documentation/development-process/1.Intro.rst | 266 ----------- Documentation/development-process/2.Process.rst | 497 --------------------- .../development-process/3.Early-stage.rst | 222 --------- Documentation/development-process/4.Coding.rst | 413 ----------------- Documentation/development-process/5.Posting.rst | 321 ------------- .../development-process/6.Followthrough.rst | 212 --------- .../development-process/7.AdvancedTopics.rst | 180 -------- Documentation/development-process/8.Conclusion.rst | 74 --- Documentation/development-process/conf.py | 10 - .../development-process/development-process.rst | 29 -- Documentation/development-process/index.rst | 9 - Documentation/index.rst | 2 +- Documentation/process/1.Intro.rst | 266 +++++++++++ Documentation/process/2.Process.rst | 497 +++++++++++++++++++++ Documentation/process/3.Early-stage.rst | 222 +++++++++ Documentation/process/4.Coding.rst | 413 +++++++++++++++++ Documentation/process/5.Posting.rst | 321 +++++++++++++ Documentation/process/6.Followthrough.rst | 212 +++++++++ Documentation/process/7.AdvancedTopics.rst | 178 ++++++++ Documentation/process/8.Conclusion.rst | 74 +++ Documentation/process/conf.py | 10 + Documentation/process/development-process.rst | 28 ++ Documentation/process/index.rst | 9 + 26 files changed, 2234 insertions(+), 2237 deletions(-) delete mode 100644 Documentation/development-process/1.Intro.rst delete mode 100644 Documentation/development-process/2.Process.rst delete mode 100644 Documentation/development-process/3.Early-stage.rst delete mode 100644 Documentation/development-process/4.Coding.rst delete mode 100644 Documentation/development-process/5.Posting.rst delete mode 100644 Documentation/development-process/6.Followthrough.rst delete mode 100644 Documentation/development-process/7.AdvancedTopics.rst delete mode 100644 Documentation/development-process/8.Conclusion.rst delete mode 100644 Documentation/development-process/conf.py delete mode 100644 Documentation/development-process/development-process.rst delete mode 100644 Documentation/development-process/index.rst create mode 100644 Documentation/process/1.Intro.rst create mode 100644 Documentation/process/2.Process.rst create mode 100644 Documentation/process/3.Early-stage.rst create mode 100644 Documentation/process/4.Coding.rst create mode 100644 Documentation/process/5.Posting.rst create mode 100644 Documentation/process/6.Followthrough.rst create mode 100644 Documentation/process/7.AdvancedTopics.rst create mode 100644 Documentation/process/8.Conclusion.rst create mode 100644 Documentation/process/conf.py create mode 100644 Documentation/process/development-process.rst create mode 100644 Documentation/process/index.rst diff --git a/Documentation/00-INDEX b/Documentation/00-INDEX index 3acc4f1a6f84..d07575a8499e 100644 --- a/Documentation/00-INDEX +++ b/Documentation/00-INDEX @@ -150,7 +150,7 @@ 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. diff --git a/Documentation/SubmittingPatches b/Documentation/SubmittingPatches index 36f1dedc944c..e62ddcdcaf5d 100644 --- a/Documentation/SubmittingPatches +++ b/Documentation/SubmittingPatches @@ -10,7 +10,7 @@ can greatly increase the chances of your change being accepted. This document contains a large number of suggestions in a relatively terse format. For detailed information on how the kernel development process -works, see :ref:`Documentation/development-process `. +works, see :ref:`Documentation/process `. Also, read :ref:`Documentation/SubmitChecklist ` for a list of items to check before submitting code. If you are submitting a driver, also read diff --git a/Documentation/conf.py b/Documentation/conf.py index 4db1993658ea..b08e0c9b73b7 100644 --- a/Documentation/conf.py +++ b/Documentation/conf.py @@ -338,7 +338,7 @@ latex_elements = { latex_documents = [ ('kernel-documentation', 'kernel-documentation.tex', 'The Linux Kernel Documentation', 'The kernel development community', 'manual'), - ('development-process/index', 'development-process.tex', 'Linux Kernel Development Documentation', + ('process/index', 'development-process.tex', 'Linux Kernel Development Documentation', 'The kernel development community', 'manual'), ('gpu/index', 'gpu.tex', 'Linux GPU Driver Developer\'s Guide', 'The kernel development community', 'manual'), diff --git a/Documentation/development-process/1.Intro.rst b/Documentation/development-process/1.Intro.rst deleted file mode 100644 index 22642b3fe903..000000000000 --- a/Documentation/development-process/1.Intro.rst +++ /dev/null @@ -1,266 +0,0 @@ -Introdution -=========== - -Executive summary ------------------ - -The rest of this section covers the scope of the kernel development process -and the kinds of frustrations that developers and their employers can -encounter there. There are a great many reasons why kernel code should be -merged into the official ("mainline") kernel, including automatic -availability to users, community support in many forms, and the ability to -influence the direction of kernel development. Code contributed to the -Linux kernel must be made available under a GPL-compatible license. - -:ref:`development_process` introduces the development process, the kernel -release cycle, and the mechanics of the merge window. The various phases in -the patch development, review, and merging cycle are covered. There is some -discussion of tools and mailing lists. Developers wanting to get started -with kernel development are encouraged to track down and fix bugs as an -initial exercise. - -:ref:`development_early_stage` covers early-stage project planning, with an -emphasis on involving the development community as soon as possible. - -:ref:`development_coding` is about the coding process; several pitfalls which -have been encountered by other developers are discussed. Some requirements for -patches are covered, and there is an introduction to some of the tools -which can help to ensure that kernel patches are correct. - -:ref:`development_posting` talks about the process of posting patches for -review. To be taken seriously by the development community, patches must be -properly formatted and described, and they must be sent to the right place. -Following the advice in this section should help to ensure the best -possible reception for your work. - -:ref:`development_followthrough` covers what happens after posting patches; the -job is far from done at that point. Working with reviewers is a crucial part -of the development process; this section offers a number of tips on how to -avoid problems at this important stage. Developers are cautioned against -assuming that the job is done when a patch is merged into the mainline. - -:ref:`development_advancedtopics` introduces a couple of "advanced" topics: -managing patches with git and reviewing patches posted by others. - -:ref:`development_conclusion` concludes the document with pointers to sources -for more information on kernel development. - -What this document is about ---------------------------- - -The Linux kernel, at over 8 million lines of code and well over 1000 -contributors to each release, is one of the largest and most active free -software projects in existence. Since its humble beginning in 1991, this -kernel has evolved into a best-of-breed operating system component which -runs on pocket-sized digital music players, desktop PCs, the largest -supercomputers in existence, and all types of systems in between. It is a -robust, efficient, and scalable solution for almost any situation. - -With the growth of Linux has come an increase in the number of developers -(and companies) wishing to participate in its development. Hardware -vendors want to ensure that Linux supports their products well, making -those products attractive to Linux users. Embedded systems vendors, who -use Linux as a component in an integrated product, want Linux to be as -capable and well-suited to the task at hand as possible. Distributors and -other software vendors who base their products on Linux have a clear -interest in the capabilities, performance, and reliability of the Linux -kernel. And end users, too, will often wish to change Linux to make it -better suit their needs. - -One of the most compelling features of Linux is that it is accessible to -these developers; anybody with the requisite skills can improve Linux and -influence the direction of its development. Proprietary products cannot -offer this kind of openness, which is a characteristic of the free software -process. But, if anything, the kernel is even more open than most other -free software projects. A typical three-month kernel development cycle can -involve over 1000 developers working for more than 100 different companies -(or for no company at all). - -Working with the kernel development community is not especially hard. But, -that notwithstanding, many potential contributors have experienced -difficulties when trying to do kernel work. The kernel community has -evolved its own distinct ways of operating which allow it to function -smoothly (and produce a high-quality product) in an environment where -thousands of lines of code are being changed every day. So it is not -surprising that Linux kernel development process differs greatly from -proprietary development methods. - -The kernel's development process may come across as strange and -intimidating to new developers, but there are good reasons and solid -experience behind it. A developer who does not understand the kernel -community's ways (or, worse, who tries to flout or circumvent them) will -have a frustrating experience in store. The development community, while -being helpful to those who are trying to learn, has little time for those -who will not listen or who do not care about the development process. - -It is hoped that those who read this document will be able to avoid that -frustrating experience. There is a lot of material here, but the effort -involved in reading it will be repaid in short order. The development -community is always in need of developers who will help to make the kernel -better; the following text should help you - or those who work for you - -join our community. - -Credits -------- - -This document was written by Jonathan Corbet, corbet@lwn.net. It has been -improved by comments from Johannes Berg, James Berry, Alex Chiang, Roland -Dreier, Randy Dunlap, Jake Edge, Jiri Kosina, Matt Mackall, Arthur Marsh, -Amanda McPherson, Andrew Morton, Andrew Price, Tsugikazu Shibata, and -Jochen Voß. - -This work was supported by the Linux Foundation; thanks especially to -Amanda McPherson, who saw the value of this effort and made it all happen. - -The importance of getting code into the mainline ------------------------------------------------- - -Some companies and developers occasionally wonder why they should bother -learning how to work with the kernel community and get their code into the -mainline kernel (the "mainline" being the kernel maintained by Linus -Torvalds and used as a base by Linux distributors). In the short term, -contributing code can look like an avoidable expense; it seems easier to -just keep the code separate and support users directly. The truth of the -matter is that keeping code separate ("out of tree") is a false economy. - -As a way of illustrating the costs of out-of-tree code, here are a few -relevant aspects of the kernel development process; most of these will be -discussed in greater detail later in this document. Consider: - -- Code which has been merged into the mainline kernel is available to all - Linux users. It will automatically be present on all distributions which - enable it. There is no need for driver disks, downloads, or the hassles - of supporting multiple versions of multiple distributions; it all just - works, for the developer and for the user. Incorporation into the - mainline solves a large number of distribution and support problems. - -- While kernel developers strive to maintain a stable interface to user - space, the internal kernel API is in constant flux. The lack of a stable - internal interface is a deliberate design decision; it allows fundamental - improvements to be made at any time and results in higher-quality code. - But one result of that policy is that any out-of-tree code requires - constant upkeep if it is to work with new kernels. Maintaining - out-of-tree code requires significant amounts of work just to keep that - code working. - - Code which is in the mainline, instead, does not require this work as the - result of a simple rule requiring any developer who makes an API change - to also fix any code that breaks as the result of that change. So code - which has been merged into the mainline has significantly lower - maintenance costs. - -- Beyond that, code which is in the kernel will often be improved by other - developers. Surprising results can come from empowering your user - community and customers to improve your product. - -- Kernel code is subjected to review, both before and after merging into - the mainline. No matter how strong the original developer's skills are, - this review process invariably finds ways in which the code can be - improved. Often review finds severe bugs and security problems. This is - especially true for code which has been developed in a closed - environment; such code benefits strongly from review by outside - developers. Out-of-tree code is lower-quality code. - -- Participation in the development process is your way to influence the - direction of kernel development. Users who complain from the sidelines - are heard, but active developers have a stronger voice - and the ability - to implement changes which make the kernel work better for their needs. - -- When code is maintained separately, the possibility that a third party - will contribute a different implementation of a similar feature always - exists. Should that happen, getting your code merged will become much - harder - to the point of impossibility. Then you will be faced with the - unpleasant alternatives of either (1) maintaining a nonstandard feature - out of tree indefinitely, or (2) abandoning your code and migrating your - users over to the in-tree version. - -- Contribution of code is the fundamental action which makes the whole - process work. By contributing your code you can add new functionality to - the kernel and provide capabilities and examples which are of use to - other kernel developers. If you have developed code for Linux (or are - thinking about doing so), you clearly have an interest in the continued - success of this platform; contributing code is one of the best ways to - help ensure that success. - -All of the reasoning above applies to any out-of-tree kernel code, -including code which is distributed in proprietary, binary-only form. -There are, however, additional factors which should be taken into account -before considering any sort of binary-only kernel code distribution. These -include: - -- The legal issues around the distribution of proprietary kernel modules - are cloudy at best; quite a few kernel copyright holders believe that - most binary-only modules are derived products of the kernel and that, as - a result, their distribution is a violation of the GNU General Public - license (about which more will be said below). Your author is not a - lawyer, and nothing in this document can possibly be considered to be - legal advice. The true legal status of closed-source modules can only be - determined by the courts. But the uncertainty which haunts those modules - is there regardless. - -- Binary modules greatly increase the difficulty of debugging kernel - problems, to the point that most kernel developers will not even try. So - the distribution of binary-only modules will make it harder for your - users to get support from the community. - -- Support is also harder for distributors of binary-only modules, who must - provide a version of the module for every distribution and every kernel - version they wish to support. Dozens of builds of a single module can - be required to provide reasonably comprehensive coverage, and your users - will have to upgrade your module separately every time they upgrade their - kernel. - -- Everything that was said above about code review applies doubly to - closed-source code. Since this code is not available at all, it cannot - have been reviewed by the community and will, beyond doubt, have serious - problems. - -Makers of embedded systems, in particular, may be tempted to disregard much -of what has been said in this section in the belief that they are shipping -a self-contained product which uses a frozen kernel version and requires no -more development after its release. This argument misses the value of -widespread code review and the value of allowing your users to add -capabilities to your product. But these products, too, have a limited -commercial life, after which a new version must be released. At that -point, vendors whose code is in the mainline and well maintained will be -much better positioned to get the new product ready for market quickly. - -Licensing ---------- - -Code is contributed to the Linux kernel under a number of licenses, but all -code must be compatible with version 2 of the GNU General Public License -(GPLv2), which is the license covering the kernel distribution as a whole. -In practice, that means that all code contributions are covered either by -GPLv2 (with, optionally, language allowing distribution under later -versions of the GPL) or the three-clause BSD license. Any contributions -which are not covered by a compatible license will not be accepted into the -kernel. - -Copyright assignments are not required (or requested) for code contributed -to the kernel. All code merged into the mainline kernel retains its -original ownership; as a result, the kernel now has thousands of owners. - -One implication of this ownership structure is that any attempt to change -the licensing of the kernel is doomed to almost certain failure. There are -few practical scenarios where the agreement of all copyright holders could -be obtained (or their code removed from the kernel). So, in particular, -there is no prospect of a migration to version 3 of the GPL in the -foreseeable future. - -It is imperative that all code contributed to the kernel be legitimately -free software. For that reason, code from anonymous (or pseudonymous) -contributors will not be accepted. All contributors are required to "sign -off" on their code, stating that the code can be distributed with the -kernel under the GPL. Code which has not been licensed as free software by -its owner, or which risks creating copyright-related problems for the -kernel (such as code which derives from reverse-engineering efforts lacking -proper safeguards) cannot be contributed. - -Questions about copyright-related issues are common on Linux development -mailing lists. Such questions will normally receive no shortage of -answers, but one should bear in mind that the people answering those -questions are not lawyers and cannot provide legal advice. If you have -legal questions relating to Linux source code, there is no substitute for -talking with a lawyer who understands this field. Relying on answers -obtained on technical mailing lists is a risky affair. diff --git a/Documentation/development-process/2.Process.rst b/Documentation/development-process/2.Process.rst deleted file mode 100644 index ce5561bb3f8e..000000000000 --- a/Documentation/development-process/2.Process.rst +++ /dev/null @@ -1,497 +0,0 @@ -.. _development_process: - -How the development process works -================================= - -Linux kernel development in the early 1990's was a pretty loose affair, -with relatively small numbers of users and developers involved. With a -user base in the millions and with some 2,000 developers involved over the -course of one year, the kernel has since had to evolve a number of -processes to keep development happening smoothly. A solid understanding of -how the process works is required in order to be an effective part of it. - -The big picture ---------------- - -The kernel developers use a loosely time-based release process, with a new -major kernel release happening every two or three months. The recent -release history looks like this: - - ====== ================= - 2.6.38 March 14, 2011 - 2.6.37 January 4, 2011 - 2.6.36 October 20, 2010 - 2.6.35 August 1, 2010 - 2.6.34 May 15, 2010 - 2.6.33 February 24, 2010 - ====== ================= - -Every 2.6.x release is a major kernel release with new features, internal -API changes, and more. A typical 2.6 release can contain nearly 10,000 -changesets with changes to several hundred thousand lines of code. 2.6 is -thus the leading edge of Linux kernel development; the kernel uses a -rolling development model which is continually integrating major changes. - -A relatively straightforward discipline is followed with regard to the -merging of patches for each release. At the beginning of each development -cycle, the "merge window" is said to be open. At that time, code which is -deemed to be sufficiently stable (and which is accepted by the development -community) is merged into the mainline kernel. The bulk of changes for a -new development cycle (and all of the major changes) will be merged during -this time, at a rate approaching 1,000 changes ("patches," or "changesets") -per day. - -(As an aside, it is worth noting that the changes integrated during the -merge window do not come out of thin air; they have been collected, tested, -and staged ahead of time. How that process works will be described in -detail later on). - -The merge window lasts for approximately two weeks. At the end of this -time, Linus Torvalds will declare that the window is closed and release the -first of the "rc" kernels. For the kernel which is destined to be 2.6.40, -for example, the release which happens at the end of the merge window will -be called 2.6.40-rc1. The -rc1 release is the signal that the time to -merge new features has passed, and that the time to stabilize the next -kernel has begun. - -Over the next six to ten weeks, only patches which fix problems should be -submitted to the mainline. On occasion a more significant change will be -allowed, but such occasions are rare; developers who try to merge new -features outside of the merge window tend to get an unfriendly reception. -As a general rule, if you miss the merge window for a given feature, the -best thing to do is to wait for the next development cycle. (An occasional -exception is made for drivers for previously-unsupported hardware; if they -touch no in-tree code, they cannot cause regressions and should be safe to -add at any time). - -As fixes make their way into the mainline, the patch rate will slow over -time. Linus releases new -rc kernels about once a week; a normal series -will get up to somewhere between -rc6 and -rc9 before the kernel is -considered to be sufficiently stable and the final 2.6.x release is made. -At that point the whole process starts over again. - -As an example, here is how the 2.6.38 development cycle went (all dates in -2011): - - ============== =============================== - January 4 2.6.37 stable release - January 18 2.6.38-rc1, merge window closes - January 21 2.6.38-rc2 - February 1 2.6.38-rc3 - February 7 2.6.38-rc4 - February 15 2.6.38-rc5 - February 21 2.6.38-rc6 - March 1 2.6.38-rc7 - March 7 2.6.38-rc8 - March 14 2.6.38 stable release - ============== =============================== - -How do the developers decide when to close the development cycle and create -the stable release? The most significant metric used is the list of -regressions from previous releases. No bugs are welcome, but those which -break systems which worked in the past are considered to be especially -serious. For this reason, patches which cause regressions are looked upon -unfavorably and are quite likely to be reverted during the stabilization -period. - -The developers' goal is to fix all known regressions before the stable -release is made. In the real world, this kind of perfection is hard to -achieve; there are just too many variables in a project of this size. -There comes a point where delaying the final release just makes the problem -worse; the pile of changes waiting for the next merge window will grow -larger, creating even more regressions the next time around. So most 2.6.x -kernels go out with a handful of known regressions though, hopefully, none -of them are serious. - -Once a stable release is made, its ongoing maintenance is passed off to the -"stable team," currently consisting of Greg Kroah-Hartman. The stable team -will release occasional updates to the stable release using the 2.6.x.y -numbering scheme. To be considered for an update release, a patch must (1) -fix a significant bug, and (2) already be merged into the mainline for the -next development kernel. Kernels will typically receive stable updates for -a little more than one development cycle past their initial release. So, -for example, the 2.6.36 kernel's history looked like: - - ============== =============================== - October 10 2.6.36 stable release - November 22 2.6.36.1 - December 9 2.6.36.2 - January 7 2.6.36.3 - February 17 2.6.36.4 - ============== =============================== - -2.6.36.4 was the final stable update for the 2.6.36 release. - -Some kernels are designated "long term" kernels; they will receive support -for a longer period. As of this writing, the current long term kernels -and their maintainers are: - - ====== ====================== =========================== - 2.6.27 Willy Tarreau (Deep-frozen stable kernel) - 2.6.32 Greg Kroah-Hartman - 2.6.35 Andi Kleen (Embedded flag kernel) - ====== ====================== =========================== - -The selection of a kernel for long-term support is purely a matter of a -maintainer having the need and the time to maintain that release. There -are no known plans for long-term support for any specific upcoming -release. - - -The lifecycle of a patch ------------------------- - -Patches do not go directly from the developer's keyboard into the mainline -kernel. There is, instead, a somewhat involved (if somewhat informal) -process designed to ensure that each patch is reviewed for quality and that -each patch implements a change which is desirable to have in the mainline. -This process can happen quickly for minor fixes, or, in the case of large -and controversial changes, go on for years. Much developer frustration -comes from a lack of understanding of this process or from attempts to -circumvent it. - -In the hopes of reducing that frustration, this document will describe how -a patch gets into the kernel. What follows below is an introduction which -describes the process in a somewhat idealized way. A much more detailed -treatment will come in later sections. - -The stages that a patch goes through are, generally: - - - Design. This is where the real requirements for the patch - and the way - those requirements will be met - are laid out. Design work is often - done without involving the community, but it is better to do this work - in the open if at all possible; it can save a lot of time redesigning - things later. - - - Early review. Patches are posted to the relevant mailing list, and - developers on that list reply with any comments they may have. This - process should turn up any major problems with a patch if all goes - well. - - - Wider review. When the patch is getting close to ready for mainline - inclusion, it should be accepted by a relevant subsystem maintainer - - though this acceptance is not a guarantee that the patch will make it - all the way to the mainline. The patch will show up in the maintainer's - subsystem tree and into the -next trees (described below). When the - process works, this step leads to more extensive review of the patch and - the discovery of any problems resulting from the integration of this - patch with work being done by others. - -- Please note that most maintainers also have day jobs, so merging - your patch may not be their highest priority. If your patch is - getting feedback about changes that are needed, you should either - make those changes or justify why they should not be made. If your - patch has no review complaints but is not being merged by its - appropriate subsystem or driver maintainer, you should be persistent - in updating the patch to the current kernel so that it applies cleanly - and keep sending it for review and merging. - - - Merging into the mainline. Eventually, a successful patch will be - merged into the mainline repository managed by Linus Torvalds. More - comments and/or problems may surface at this time; it is important that - the developer be responsive to these and fix any issues which arise. - - - Stable release. The number of users potentially affected by the patch - is now large, so, once again, new problems may arise. - - - Long-term maintenance. While it is certainly possible for a developer - to forget about code after merging it, that sort of behavior tends to - leave a poor impression in the development community. Merging code - eliminates some of the maintenance burden, in that others will fix - problems caused by API changes. But the original developer should - continue to take responsibility for the code if it is to remain useful - in the longer term. - -One of the largest mistakes made by kernel developers (or their employers) -is to try to cut the process down to a single "merging into the mainline" -step. This approach invariably leads to frustration for everybody -involved. - -How patches get into the Kernel -------------------------------- - -There is exactly one person who can merge patches into the mainline kernel -repository: Linus Torvalds. But, of the over 9,500 patches which went -into the 2.6.38 kernel, only 112 (around 1.3%) were directly chosen by Linus -himself. The kernel project has long since grown to a size where no single -developer could possibly inspect and select every patch unassisted. The -way the kernel developers have addressed this growth is through the use of -a lieutenant system built around a chain of trust. - -The kernel code base is logically broken down into a set of subsystems: -networking, specific architecture support, memory management, video -devices, etc. Most subsystems have a designated maintainer, a developer -who has overall responsibility for the code within that subsystem. These -subsystem maintainers are the gatekeepers (in a loose way) for the portion -of the kernel they manage; they are the ones who will (usually) accept a -patch for inclusion into the mainline kernel. - -Subsystem maintainers each manage their own version of the kernel source -tree, usually (but certainly not always) using the git source management -tool. Tools like git (and related tools like quilt or mercurial) allow -maintainers to track a list of patches, including authorship information -and other metadata. At any given time, the maintainer can identify which -patches in his or her repository are not found in the mainline. - -When the merge window opens, top-level maintainers will ask Linus to "pull" -the patches they have selected for merging from their repositories. If -Linus agrees, the stream of patches will flow up into his repository, -becoming part of the mainline kernel. The amount of attention that Linus -pays to specific patches received in a pull operation varies. It is clear -that, sometimes, he looks quite closely. But, as a general rule, Linus -trusts the subsystem maintainers to not send bad patches upstream. - -Subsystem maintainers, in turn, can pull patches from other maintainers. -For example, the networking tree is built from patches which accumulated -first in trees dedicated to network device drivers, wireless networking, -etc. This chain of repositories can be arbitrarily long, though it rarely -exceeds two or three links. Since each maintainer in the chain trusts -those managing lower-level trees, this process is known as the "chain of -trust." - -Clearly, in a system like this, getting patches into the kernel depends on -finding the right maintainer. Sending patches directly to Linus is not -normally the right way to go. - - -Next trees ----------- - -The chain of subsystem trees guides the flow of patches into the kernel, -but it also raises an interesting question: what if somebody wants to look -at all of the patches which are being prepared for the next merge window? -Developers will be interested in what other changes are pending to see -whether there are any conflicts to worry about; a patch which changes a -core kernel function prototype, for example, will conflict with any other -patches which use the older form of that function. Reviewers and testers -want access to the changes in their integrated form before all of those -changes land in the mainline kernel. One could pull changes from all of -the interesting subsystem trees, but that would be a big and error-prone -job. - -The answer comes in the form of -next trees, where subsystem trees are -collected for testing and review. The older of these trees, maintained by -Andrew Morton, is called "-mm" (for memory management, which is how it got -started). The -mm tree integrates patches from a long list of subsystem -trees; it also has some patches aimed at helping with debugging. - -Beyond that, -mm contains a significant collection of patches which have -been selected by Andrew directly. These patches may have been posted on a -mailing list, or they may apply to a part of the kernel for which there is -no designated subsystem tree. As a result, -mm operates as a sort of -subsystem tree of last resort; if there is no other obvious path for a -patch into the mainline, it is likely to end up in -mm. Miscellaneous -patches which accumulate in -mm will eventually either be forwarded on to -an appropriate subsystem tree or be sent directly to Linus. In a typical -development cycle, approximately 5-10% of the patches going into the -mainline get there via -mm. - -The current -mm patch is available in the "mmotm" (-mm of the moment) -directory at: - - http://www.ozlabs.org/~akpm/mmotm/ - -Use of the MMOTM tree is likely to be a frustrating experience, though; -there is a definite chance that it will not even compile. - -The primary tree for next-cycle patch merging is linux-next, maintained by -Stephen Rothwell. The linux-next tree is, by design, a snapshot of what -the mainline is expected to look like after the next merge window closes. -Linux-next trees are announced on the linux-kernel and linux-next mailing -lists when they are assembled; they can be downloaded from: - - http://www.kernel.org/pub/linux/kernel/next/ - -Linux-next has become an integral part of the kernel development process; -all patches merged during a given merge window should really have found -their way into linux-next some time before the merge window opens. - - -Staging trees -------------- - -The kernel source tree contains the drivers/staging/ directory, where -many sub-directories for drivers or filesystems that are on their way to -being added to the kernel tree live. They remain in drivers/staging while -they still need more work; once complete, they can be moved into the -kernel proper. This is a way to keep track of drivers that aren't -up to Linux kernel coding or quality standards, but people may want to use -them and track development. - -Greg Kroah-Hartman currently maintains the staging tree. Drivers that -still need work are sent to him, with each driver having its own -subdirectory in drivers/staging/. Along with the driver source files, a -TODO file should be present in the directory as well. The TODO file lists -the pending work that the driver needs for acceptance into the kernel -proper, as well as a list of people that should be Cc'd for any patches to -the driver. Current rules require that drivers contributed to staging -must, at a minimum, compile properly. - -Staging can be a relatively easy way to get new drivers into the mainline -where, with luck, they will come to the attention of other developers and -improve quickly. Entry into staging is not the end of the story, though; -code in staging which is not seeing regular progress will eventually be -removed. Distributors also tend to be relatively reluctant to enable -staging drivers. So staging is, at best, a stop on the way toward becoming -a proper mainline driver. - - -Tools ------ - -As can be seen from the above text, the kernel development process depends -heavily on the ability to herd collections of patches in various -directions. The whole thing would not work anywhere near as well as it -does without suitably powerful tools. Tutorials on how to use these tools -are well beyond the scope of this document, but there is space for a few -pointers. - -By far the dominant source code management system used by the kernel -community is git. Git is one of a number of distributed version control -systems being developed in the free software community. It is well tuned -for kernel development, in that it performs quite well when dealing with -large repositories and large numbers of patches. It also has a reputation -for being difficult to learn and use, though it has gotten better over -time. Some sort of familiarity with git is almost a requirement for kernel -developers; even if they do not use it for their own work, they'll need git -to keep up with what other developers (and the mainline) are doing. - -Git is now packaged by almost all Linux distributions. There is a home -page at: - - http://git-scm.com/ - -That page has pointers to documentation and tutorials. - -Among the kernel developers who do not use git, the most popular choice is -almost certainly Mercurial: - - http://www.selenic.com/mercurial/ - -Mercurial shares many features with git, but it provides an interface which -many find easier to use. - -The other tool worth knowing about is Quilt: - - http://savannah.nongnu.org/projects/quilt/ - -Quilt is a patch management system, rather than a source code management -system. It does not track history over time; it is, instead, oriented -toward tracking a specific set of changes against an evolving code base. -Some major subsystem maintainers use quilt to manage patches intended to go -upstream. For the management of certain kinds of trees (-mm, for example), -quilt is the best tool for the job. - - -Mailing lists -------------- - -A great deal of Linux kernel development work is done by way of mailing -lists. It is hard to be a fully-functioning member of the community -without joining at least one list somewhere. But Linux mailing lists also -represent a potential hazard to developers, who risk getting buried under a -load of electronic mail, running afoul of the conventions used on the Linux -lists, or both. - -Most kernel mailing lists are run on vger.kernel.org; the master list can -be found at: - - http://vger.kernel.org/vger-lists.html - -There are lists hosted elsewhere, though; a number of them are at -lists.redhat.com. - -The core mailing list for kernel development is, of course, linux-kernel. -This list is an intimidating place to be; volume can reach 500 messages per -day, the amount of noise is high, the conversation can be severely -technical, and participants are not always concerned with showing a high -degree of politeness. But there is no other place where the kernel -development community comes together as a whole; developers who avoid this -list will miss important information. - -There are a few hints which can help with linux-kernel survival: - -- Have the list delivered to a separate folder, rather than your main - mailbox. One must be able to ignore the stream for sustained periods of - time. - -- Do not try to follow every conversation - nobody else does. It is - important to filter on both the topic of interest (though note that - long-running conversations can drift away from the original subject - without changing the email subject line) and the people who are - participating. - -- Do not feed the trolls. If somebody is trying to stir up an angry - response, ignore them. - -- When responding to linux-kernel email (or that on other lists) preserve - the Cc: header for all involved. In the absence of a strong reason (such - as an explicit request), you should never remove recipients. Always make - sure that the person you are responding to is in the Cc: list. This - convention also makes it unnecessary to explicitly ask to be copied on - replies to your postings. - -- Search the list archives (and the net as a whole) before asking - questions. Some developers can get impatient with people who clearly - have not done their homework. - -- Avoid top-posting (the practice of putting your answer above the quoted - text you are responding to). It makes your response harder to read and - makes a poor impression. - -- Ask on the correct mailing list. Linux-kernel may be the general meeting - point, but it is not the best place to find developers from all - subsystems. - -The last point - finding the correct mailing list - is a common place for -beginning developers to go wrong. Somebody who asks a networking-related -question on linux-kernel will almost certainly receive a polite suggestion -to ask on the netdev list instead, as that is the list frequented by most -networking developers. Other lists exist for the SCSI, video4linux, IDE, -filesystem, etc. subsystems. The best place to look for mailing lists is -in the MAINTAINERS file packaged with the kernel source. - - -Getting started with Kernel development ---------------------------------------- - -Questions about how to get started with the kernel development process are -common - from both individuals and companies. Equally common are missteps -which make the beginning of the relationship harder than it has to be. - -Companies often look to hire well-known developers to get a development -group started. This can, in fact, be an effective technique. But it also -tends to be expensive and does not do much to grow the pool of experienced -kernel developers. It is possible to bring in-house developers up to speed -on Linux kernel development, given the investment of a bit of time. Taking -this time can endow an employer with a group of developers who understand -the kernel and the company both, and who can help to train others as well. -Over the medium term, this is often the more profitable approach. - -Individual developers are often, understandably, at a loss for a place to -start. Beginning with a large project can be intimidating; one often wants -to test the waters with something smaller first. This is the point where -some developers jump into the creation of patches fixing spelling errors or -minor coding style issues. Unfortunately, such patches create a level of -noise which is distracting for the development community as a whole, so, -increasingly, they are looked down upon. New developers wishing to -introduce themselves to the community will not get the sort of reception -they wish for by these means. - -Andrew Morton gives this advice for aspiring kernel developers - -:: - - The #1 project for all kernel beginners should surely be "make sure - that the kernel runs perfectly at all times on all machines which - you can lay your hands on". Usually the way to do this is to work - with others on getting things fixed up (this can require - persistence!) but that's fine - it's a part of kernel development. - -(http://lwn.net/Articles/283982/). - -In the absence of obvious problems to fix, developers are advised to look -at the current lists of regressions and open bugs in general. There is -never any shortage of issues in need of fixing; by addressing these issues, -developers will gain experience with the process while, at the same time, -building respect with the rest of the development community. diff --git a/Documentation/development-process/3.Early-stage.rst b/Documentation/development-process/3.Early-stage.rst deleted file mode 100644 index af2c0af931d6..000000000000 --- a/Documentation/development-process/3.Early-stage.rst +++ /dev/null @@ -1,222 +0,0 @@ -.. _development_early_stage: - -Early-stage planning -==================== - -When contemplating a Linux kernel development project, it can be tempting -to jump right in and start coding. As with any significant project, -though, much of the groundwork for success is best laid before the first -line of code is written. Some time spent in early planning and -communication can save far more time later on. - - -Specifying the problem ----------------------- - -Like any engineering project, a successful kernel enhancement starts with a -clear description of the problem to be solved. In some cases, this step is -easy: when a driver is needed for a specific piece of hardware, for -example. In others, though, it is tempting to confuse the real problem -with the proposed solution, and that can lead to difficulties. - -Consider an example: some years ago, developers working with Linux audio -sought a way to run applications without dropouts or other artifacts caused -by excessive latency in the system. The solution they arrived at was a -kernel module intended to hook into the Linux Security Module (LSM) -framework; this module could be configured to give specific applications -access to the realtime scheduler. This module was implemented and sent to -the linux-kernel mailing list, where it immediately ran into problems. - -To the audio developers, this security module was sufficient to solve their -immediate problem. To the wider kernel community, though, it was seen as a -misuse of the LSM framework (which is not intended to confer privileges -onto processes which they would not otherwise have) and a risk to system -stability. Their preferred solutions involved realtime scheduling access -via the rlimit mechanism for the short term, and ongoing latency reduction -work in the long term. - -The audio community, however, could not see past the particular solution -they had implemented; they were unwilling to accept alternatives. The -resulting disagreement left those developers feeling disillusioned with the -entire kernel development process; one of them went back to an audio list -and posted this: - - There are a number of very good Linux kernel developers, but they - tend to get outshouted by a large crowd of arrogant fools. Trying - to communicate user requirements to these people is a waste of - time. They are much too "intelligent" to listen to lesser mortals. - -(http://lwn.net/Articles/131776/). - -The reality of the situation was different; the kernel developers were far -more concerned about system stability, long-term maintenance, and finding -the right solution to the problem than they were with a specific module. -The moral of the story is to focus on the problem - not a specific solution -- and to discuss it with the development community before investing in the -creation of a body of code. - -So, when contemplating a kernel development project, one should obtain -answers to a short set of questions: - - - What, exactly, is the problem which needs to be solved? - - - Who are the users affected by this problem? Which use cases should the - solution address? - - - How does the kernel fall short in addressing that problem now? - -Only then does it make sense to start considering possible solutions. - - -Early discussion ----------------- - -When planning a kernel development project, it makes great sense to hold -discussions with the community before launching into implementation. Early -communication can save time and trouble in a number of ways: - - - It may well be that the problem is addressed by the kernel in ways which - you have not understood. The Linux kernel is large and has a number of - features and capabilities which are not immediately obvious. Not all - kernel capabilities are documented as well as one might like, and it is - easy to miss things. Your author has seen the posting of a complete - driver which duplicated an existing driver that the new author had been - unaware of. Code which reinvents existing wheels is not only wasteful; - it will also not be accepted into the mainline kernel. - - - There may be elements of the proposed solution which will not be - acceptable for mainline merging. It is better to find out about - problems like this before writing the code. - - - It's entirely possible that other developers have thought about the - problem; they may have ideas for a better solution, and may be willing - to help in the creation of that solution. - -Years of experience with the kernel development community have taught a -clear lesson: kernel code which is designed and developed behind closed -doors invariably has problems which are only revealed when the code is -released into the community. Sometimes these problems are severe, -requiring months or years of effort before the code can be brought up to -the kernel community's standards. Some examples include: - - - The Devicescape network stack was designed and implemented for - single-processor systems. It could not be merged into the mainline - until it was made suitable for multiprocessor systems. Retrofitting - locking and such into code is a difficult task; as a result, the merging - of this code (now called mac80211) was delayed for over a year. - - - The Reiser4 filesystem included a number of capabilities which, in the - core kernel developers' opinion, should have been implemented in the - virtual filesystem layer instead. It also included features which could - not easily be implemented without exposing the system to user-caused - deadlocks. The late revelation of these problems - and refusal to - address some of them - has caused Reiser4 to stay out of the mainline - kernel. - - - The AppArmor security module made use of internal virtual filesystem - data structures in ways which were considered to be unsafe and - unreliable. This concern (among others) kept AppArmor out of the - mainline for years. - -In each of these cases, a great deal of pain and extra work could have been -avoided with some early discussion with the kernel developers. - - -Who do you talk to? -------------------- - -When developers decide to take their plans public, the next question will -be: where do we start? The answer is to find the right mailing list(s) and -the right maintainer. For mailing lists, the best approach is to look in -the MAINTAINERS file for a relevant place to post. If there is a suitable -subsystem list, posting there is often preferable to posting on -linux-kernel; you are more likely to reach developers with expertise in the -relevant subsystem and the environment may be more supportive. - -Finding maintainers can be a bit harder. Again, the MAINTAINERS file is -the place to start. That file tends to not always be up to date, though, -and not all subsystems are represented there. The person listed in the -MAINTAINERS file may, in fact, not be the person who is actually acting in -that role currently. So, when there is doubt about who to contact, a -useful trick is to use git (and "git log" in particular) to see who is -currently active within the subsystem of interest. Look at who is writing -patches, and who, if anybody, is attaching Signed-off-by lines to those -patches. Those are the people who will be best placed to help with a new -development project. - -The task of finding the right maintainer is sometimes challenging enough -that the kernel developers have added a script to ease the process: - -:: - - .../scripts/get_maintainer.pl - -This script will return the current maintainer(s) for a given file or -directory when given the "-f" option. If passed a patch on the -command line, it will list the maintainers who should probably receive -copies of the patch. There are a number of options regulating how hard -get_maintainer.pl will search for maintainers; please be careful about -using the more aggressive options as you may end up including developers -who have no real interest in the code you are modifying. - -If all else fails, talking to Andrew Morton can be an effective way to -track down a maintainer for a specific piece of code. - - -When to post? -------------- - -If possible, posting your plans during the early stages can only be -helpful. Describe the problem being solved and any plans that have been -made on how the implementation will be done. Any information you can -provide can help the development community provide useful input on the -project. - -One discouraging thing which can happen at this stage is not a hostile -reaction, but, instead, little or no reaction at all. The sad truth of the -matter is (1) kernel developers tend to be busy, (2) there is no shortage -of people with grand plans and little code (or even prospect of code) to -back them up, and (3) nobody is obligated to review or comment on ideas -posted by others. Beyond that, high-level designs often hide problems -which are only reviewed when somebody actually tries to implement those -designs; for that reason, kernel developers would rather see the code. - -If a request-for-comments posting yields little in the way of comments, do -not assume that it means there is no interest in the project. -Unfortunately, you also cannot assume that there are no problems with your -idea. The best thing to do in this situation is to proceed, keeping the -community informed as you go. - - -Getting official buy-in ------------------------ - -If your work is being done in a corporate environment - as most Linux -kernel work is - you must, obviously, have permission from suitably -empowered managers before you can post your company's plans or code to a -public mailing list. The posting of code which has not been cleared for -release under a GPL-compatible license can be especially problematic; the -sooner that a company's management and legal staff can agree on the posting -of a kernel development project, the better off everybody involved will be. - -Some readers may be thinking at this point that their kernel work is -intended to support a product which does not yet have an officially -acknowledged existence. Revealing their employer's plans on a public -mailing list may not be a viable option. In cases like this, it is worth -considering whether the secrecy is really necessary; there is often no real -need to keep development plans behind closed doors. - -That said, there are also cases where a company legitimately cannot -disclose its plans early in the development process. Companies with -experienced kernel developers may choose to proceed in an open-loop manner -on the assumption that they will be able to avoid serious integration -problems later. For companies without that sort of in-house expertise, the -best option is often to hire an outside developer to review the plans under -a non-disclosure agreement. The Linux Foundation operates an NDA program -designed to help with this sort of situation; more information can be found -at: - - http://www.linuxfoundation.org/en/NDA_program - -This kind of review is often enough to avoid serious problems later on -without requiring public disclosure of the project. diff --git a/Documentation/development-process/4.Coding.rst b/Documentation/development-process/4.Coding.rst deleted file mode 100644 index 9d5cef996f7f..000000000000 --- a/Documentation/development-process/4.Coding.rst +++ /dev/null @@ -1,413 +0,0 @@ -.. _development_coding: - -Getting the code right -====================== - -While there is much to be said for a solid and community-oriented design -process, the proof of any kernel development project is in the resulting -code. It is the code which will be examined by other developers and merged -(or not) into the mainline tree. So it is the quality of this code which -will determine the ultimate success of the project. - -This section will examine the coding process. We'll start with a look at a -number of ways in which kernel developers can go wrong. Then the focus -will shift toward doing things right and the tools which can help in that -quest. - - -Pitfalls ---------- - -Coding style -************ - -The kernel has long had a standard coding style, described in -Documentation/CodingStyle. For much of that time, the policies described -in that file were taken as being, at most, advisory. As a result, there is -a substantial amount of code in the kernel which does not meet the coding -style guidelines. The presence of that code leads to two independent -hazards for kernel developers. - -The first of these is to believe that the kernel coding standards do not -matter and are not enforced. The truth of the matter is that adding new -code to the kernel is very difficult if that code is not coded according to -the standard; many developers will request that the code be reformatted -before they will even review it. A code base as large as the kernel -requires some uniformity of code to make it possible for developers to -quickly understand any part of it. So there is no longer room for -strangely-formatted code. - -Occasionally, the kernel's coding style will run into conflict with an -employer's mandated style. In such cases, the kernel's style will have to -win before the code can be merged. Putting code into the kernel means -giving up a degree of control in a number of ways - including control over -how the code is formatted. - -The other trap is to assume that code which is already in the kernel is -urgently in need of coding style fixes. Developers may start to generate -reformatting patches as a way of gaining familiarity with the process, or -as a way of getting their name into the kernel changelogs - or both. But -pure coding style fixes are seen as noise by the development community; -they tend to get a chilly reception. So this type of patch is best -avoided. It is natural to fix the style of a piece of code while working -on it for other reasons, but coding style changes should not be made for -their own sake. - -The coding style document also should not be read as an absolute law which -can never be transgressed. If there is a good reason to go against the -style (a line which becomes far less readable if split to fit within the -80-column limit, for example), just do it. - - -Abstraction layers -****************** - -Computer Science professors teach students to make extensive use of -abstraction layers in the name of flexibility and information hiding. -Certainly the kernel makes extensive use of abstraction; no project -involving several million lines of code could do otherwise and survive. -But experience has shown that excessive or premature abstraction can be -just as harmful as premature optimization. Abstraction should be used to -the level required and no further. - -At a simple level, consider a function which has an argument which is -always passed as zero by all callers. One could retain that argument just -in case somebody eventually needs to use the extra flexibility that it -provides. By that time, though, chances are good that the code which -implements this extra argument has been broken in some subtle way which was -never noticed - because it has never been used. Or, when the need for -extra flexibility arises, it does not do so in a way which matches the -programmer's early expectation. Kernel developers will routinely submit -patches to remove unused arguments; they should, in general, not be added -in the first place. - -Abstraction layers which hide access to hardware - often to allow the bulk -of a driver to be used with multiple operating systems - are especially -frowned upon. Such layers obscure the code and may impose a performance -penalty; they do not belong in the Linux kernel. - -On the other hand, if you find yourself copying significant amounts of code -from another kernel subsystem, it is time to ask whether it would, in fact, -make sense to pull out some of that code into a separate library or to -implement that functionality at a higher level. There is no value in -replicating the same code throughout the kernel. - - -#ifdef and preprocessor use in general -************************************** - -The C preprocessor seems to present a powerful temptation to some C -programmers, who see it as a way to efficiently encode a great deal of -flexibility into a source file. But the preprocessor is not C, and heavy -use of it results in code which is much harder for others to read and -harder for the compiler to check for correctness. Heavy preprocessor use -is almost always a sign of code which needs some cleanup work. - -Conditional compilation with #ifdef is, indeed, a powerful feature, and it -is used within the kernel. But there is little desire to see code which is -sprinkled liberally with #ifdef blocks. As a general rule, #ifdef use -should be confined to header files whenever possible. -Conditionally-compiled code can be confined to functions which, if the code -is not to be present, simply become empty. The compiler will then quietly -optimize out the call to the empty function. The result is far cleaner -code which is easier to follow. - -C preprocessor macros present a number of hazards, including possible -multiple evaluation of expressions with side effects and no type safety. -If you are tempted to define a macro, consider creating an inline function -instead. The code which results will be the same, but inline functions are -easier to read, do not evaluate their arguments multiple times, and allow -the compiler to perform type checking on the arguments and return value. - - -Inline functions -**************** - -Inline functions present a hazard of their own, though. Programmers can -become enamored of the perceived efficiency inherent in avoiding a function -call and fill a source file with inline functions. Those functions, -however, can actually reduce performance. Since their code is replicated -at each call site, they end up bloating the size of the compiled kernel. -That, in turn, creates pressure on the processor's memory caches, which can -slow execution dramatically. Inline functions, as a rule, should be quite -small and relatively rare. The cost of a function call, after all, is not -that high; the creation of large numbers of inline functions is a classic -example of premature optimization. - -In general, kernel programmers ignore cache effects at their peril. The -classic time/space tradeoff taught in beginning data structures classes -often does not apply to contemporary hardware. Space *is* time, in that a -larger program will run slower than one which is more compact. - -More recent compilers take an increasingly active role in deciding whether -a given function should actually be inlined or not. So the liberal -placement of "inline" keywords may not just be excessive; it could also be -irrelevant. - - -Locking -******* - -In May, 2006, the "Devicescape" networking stack was, with great -fanfare, released under the GPL and made available for inclusion in the -mainline kernel. This donation was welcome news; support for wireless -networking in Linux was considered substandard at best, and the Devicescape -stack offered the promise of fixing that situation. Yet, this code did not -actually make it into the mainline until June, 2007 (2.6.22). What -happened? - -This code showed a number of signs of having been developed behind -corporate doors. But one large problem in particular was that it was not -designed to work on multiprocessor systems. Before this networking stack -(now called mac80211) could be merged, a locking scheme needed to be -retrofitted onto it. - -Once upon a time, Linux kernel code could be developed without thinking -about the concurrency issues presented by multiprocessor systems. Now, -however, this document is being written on a dual-core laptop. Even on -single-processor systems, work being done to improve responsiveness will -raise the level of concurrency within the kernel. The days when kernel -code could be written without thinking about locking are long past. - -Any resource (data structures, hardware registers, etc.) which could be -accessed concurrently by more than one thread must be protected by a lock. -New code should be written with this requirement in mind; retrofitting -locking after the fact is a rather more difficult task. Kernel developers -should take the time to understand the available locking primitives well -enough to pick the right tool for the job. Code which shows a lack of -attention to concurrency will have a difficult path into the mainline. - - -Regressions -*********** - -One final hazard worth mentioning is this: it can be tempting to make a -change (which may bring big improvements) which causes something to break -for existing users. This kind of change is called a "regression," and -regressions have become most unwelcome in the mainline kernel. With few -exceptions, changes which cause regressions will be backed out if the -regression cannot be fixed in a timely manner. Far better to avoid the -regression in the first place. - -It is often argued that a regression can be justified if it causes things -to work for more people than it creates problems for. Why not make a -change if it brings new functionality to ten systems for each one it -breaks? The best answer to this question was expressed by Linus in July, -2007: - -:: - - So we don't fix bugs by introducing new problems. That way lies - madness, and nobody ever knows if you actually make any real - progress at all. Is it two steps forwards, one step back, or one - step forward and two steps back? - -(http://lwn.net/Articles/243460/). - -An especially unwelcome type of regression is any sort of change to the -user-space ABI. Once an interface has been exported to user space, it must -be supported indefinitely. This fact makes the creation of user-space -interfaces particularly challenging: since they cannot be changed in -incompatible ways, they must be done right the first time. For this -reason, a great deal of thought, clear documentation, and wide review for -user-space interfaces is always required. - - -Code checking tools -------------------- - -For now, at least, the writing of error-free code remains an ideal that few -of us can reach. What we can hope to do, though, is to catch and fix as -many of those errors as possible before our code goes into the mainline -kernel. To that end, the kernel developers have put together an impressive -array of tools which can catch a wide variety of obscure problems in an -automated way. Any problem caught by the computer is a problem which will -not afflict a user later on, so it stands to reason that the automated -tools should be used whenever possible. - -The first step is simply to heed the warnings produced by the compiler. -Contemporary versions of gcc can detect (and warn about) a large number of -potential errors. Quite often, these warnings point to real problems. -Code submitted for review should, as a rule, not produce any compiler -warnings. When silencing warnings, take care to understand the real cause -and try to avoid "fixes" which make the warning go away without addressing -its cause. - -Note that not all compiler warnings are enabled by default. Build the -kernel with "make EXTRA_CFLAGS=-W" to get the full set. - -The kernel provides several configuration options which turn on debugging -features; most of these are found in the "kernel hacking" submenu. Several -of these options should be turned on for any kernel used for development or -testing purposes. In particular, you should turn on: - - - ENABLE_WARN_DEPRECATED, ENABLE_MUST_CHECK, and FRAME_WARN to get an - extra set of warnings for problems like the use of deprecated interfaces - or ignoring an important return value from a function. The output - generated by these warnings can be verbose, but one need not worry about - warnings from other parts of the kernel. - - - DEBUG_OBJECTS will add code to track the lifetime of various objects - created by the kernel and warn when things are done out of order. If - you are adding a subsystem which creates (and exports) complex objects - of its own, consider adding support for the object debugging - infrastructure. - - - DEBUG_SLAB can find a variety of memory allocation and use errors; it - should be used on most development kernels. - - - DEBUG_SPINLOCK, DEBUG_ATOMIC_SLEEP, and DEBUG_MUTEXES will find a - number of common locking errors. - -There are quite a few other debugging options, some of which will be -discussed below. Some of them have a significant performance impact and -should not be used all of the time. But some time spent learning the -available options will likely be paid back many times over in short order. - -One of the heavier debugging tools is the locking checker, or "lockdep." -This tool will track the acquisition and release of every lock (spinlock or -mutex) in the system, the order in which locks are acquired relative to -each other, the current interrupt environment, and more. It can then -ensure that locks are always acquired in the same order, that the same -interrupt assumptions apply in all situations, and so on. In other words, -lockdep can find a number of scenarios in which the system could, on rare -occasion, deadlock. This kind of problem can be painful (for both -developers and users) in a deployed system; lockdep allows them to be found -in an automated manner ahead of time. Code with any sort of non-trivial -locking should be run with lockdep enabled before being submitted for -inclusion. - -As a diligent kernel programmer, you will, beyond doubt, check the return -status of any operation (such as a memory allocation) which can fail. The -fact of the matter, though, is that the resulting failure recovery paths -are, probably, completely untested. Untested code tends to be broken code; -you could be much more confident of your code if all those error-handling -paths had been exercised a few times. - -The kernel provides a fault injection framework which can do exactly that, -especially where memory allocations are involved. With fault injection -enabled, a configurable percentage of memory allocations will be made to -fail; these failures can be restricted to a specific range of code. -Running with fault injection enabled allows the programmer to see how the -code responds when things go badly. See -Documentation/fault-injection/fault-injection.txt for more information on -how to use this facility. - -Other kinds of errors can be found with the "sparse" static analysis tool. -With sparse, the programmer can be warned about confusion between -user-space and kernel-space addresses, mixture of big-endian and -small-endian quantities, the passing of integer values where a set of bit -flags is expected, and so on. Sparse must be installed separately (it can -be found at https://sparse.wiki.kernel.org/index.php/Main_Page if your -distributor does not package it); it can then be run on the code by adding -"C=1" to your make command. - -The "Coccinelle" tool (http://coccinelle.lip6.fr/) is able to find a wide -variety of potential coding problems; it can also propose fixes for those -problems. Quite a few "semantic patches" for the kernel have been packaged -under the scripts/coccinelle directory; running "make coccicheck" will run -through those semantic patches and report on any problems found. See -Documentation/coccinelle.txt for more information. - -Other kinds of portability errors are best found by compiling your code for -other architectures. If you do not happen to have an S/390 system or a -Blackfin development board handy, you can still perform the compilation -step. A large set of cross compilers for x86 systems can be found at - - http://www.kernel.org/pub/tools/crosstool/ - -Some time spent installing and using these compilers will help avoid -embarrassment later. - - -Documentation -------------- - -Documentation has often been more the exception than the rule with kernel -development. Even so, adequate documentation will help to ease the merging -of new code into the kernel, make life easier for other developers, and -will be helpful for your users. In many cases, the addition of -documentation has become essentially mandatory. - -The first piece of documentation for any patch is its associated -changelog. Log entries should describe the problem being solved, the form -of the solution, the people who worked on the patch, any relevant -effects on performance, and anything else that might be needed to -understand the patch. Be sure that the changelog says *why* the patch is -worth applying; a surprising number of developers fail to provide that -information. - -Any code which adds a new user-space interface - including new sysfs or -/proc files - should include documentation of that interface which enables -user-space developers to know what they are working with. See -Documentation/ABI/README for a description of how this documentation should -be formatted and what information needs to be provided. - -The file Documentation/kernel-parameters.txt describes all of the kernel's -boot-time parameters. Any patch which adds new parameters should add the -appropriate entries to this file. - -Any new configuration options must be accompanied by help text which -clearly explains the options and when the user might want to select them. - -Internal API information for many subsystems is documented by way of -specially-formatted comments; these comments can be extracted and formatted -in a number of ways by the "kernel-doc" script. If you are working within -a subsystem which has kerneldoc comments, you should maintain them and add -them, as appropriate, for externally-available functions. Even in areas -which have not been so documented, there is no harm in adding kerneldoc -comments for the future; indeed, this can be a useful activity for -beginning kernel developers. The format of these comments, along with some -information on how to create kerneldoc templates can be found in the file -Documentation/kernel-documentation.rst. - -Anybody who reads through a significant amount of existing kernel code will -note that, often, comments are most notable by their absence. Once again, -the expectations for new code are higher than they were in the past; -merging uncommented code will be harder. That said, there is little desire -for verbosely-commented code. The code should, itself, be readable, with -comments explaining the more subtle aspects. - -Certain things should always be commented. Uses of memory barriers should -be accompanied by a line explaining why the barrier is necessary. The -locking rules for data structures generally need to be explained somewhere. -Major data structures need comprehensive documentation in general. -Non-obvious dependencies between separate bits of code should be pointed -out. Anything which might tempt a code janitor to make an incorrect -"cleanup" needs a comment saying why it is done the way it is. And so on. - - -Internal API changes --------------------- - -The binary interface provided by the kernel to user space cannot be broken -except under the most severe circumstances. The kernel's internal -programming interfaces, instead, are highly fluid and can be changed when -the need arises. If you find yourself having to work around a kernel API, -or simply not using a specific functionality because it does not meet your -needs, that may be a sign that the API needs to change. As a kernel -developer, you are empowered to make such changes. - -There are, of course, some catches. API changes can be made, but they need -to be well justified. So any patch making an internal API change should be -accompanied by a description of what the change is and why it is -necessary. This kind of change should also be broken out into a separate -patch, rather than buried within a larger patch. - -The other catch is that a developer who changes an internal API is -generally charged with the task of fixing any code within the kernel tree -which is broken by the change. For a widely-used function, this duty can -lead to literally hundreds or thousands of changes - many of which are -likely to conflict with work being done by other developers. Needless to -say, this can be a large job, so it is best to be sure that the -justification is solid. Note that the Coccinelle tool can help with -wide-ranging API changes. - -When making an incompatible API change, one should, whenever possible, -ensure that code which has not been updated is caught by the compiler. -This will help you to be sure that you have found all in-tree uses of that -interface. It will also alert developers of out-of-tree code that there is -a change that they need to respond to. Supporting out-of-tree code is not -something that kernel developers need to be worried about, but we also do -not have to make life harder for out-of-tree developers than it needs to -be. diff --git a/Documentation/development-process/5.Posting.rst b/Documentation/development-process/5.Posting.rst deleted file mode 100644 index b511ddf7e82a..000000000000 --- a/Documentation/development-process/5.Posting.rst +++ /dev/null @@ -1,321 +0,0 @@ -.. _development_posting: - -Posting patches -=============== - -Sooner or later, the time comes when your work is ready to be presented to -the community for review and, eventually, inclusion into the mainline -kernel. Unsurprisingly, the kernel development community has evolved a set -of conventions and procedures which are used in the posting of patches; -following them will make life much easier for everybody involved. This -document will attempt to cover these expectations in reasonable detail; -more information can also be found in the files SubmittingPatches, -SubmittingDrivers, and SubmitChecklist in the kernel documentation -directory. - - -When to post ------------- - -There is a constant temptation to avoid posting patches before they are -completely "ready." For simple patches, that is not a problem. If the -work being done is complex, though, there is a lot to be gained by getting -feedback from the community before the work is complete. So you should -consider posting in-progress work, or even making a git tree available so -that interested developers can catch up with your work at any time. - -When posting code which is not yet considered ready for inclusion, it is a -good idea to say so in the posting itself. Also mention any major work -which remains to be done and any known problems. Fewer people will look at -patches which are known to be half-baked, but those who do will come in -with the idea that they can help you drive the work in the right direction. - - -Before creating patches ------------------------ - -There are a number of things which should be done before you consider -sending patches to the development community. These include: - - - Test the code to the extent that you can. Make use of the kernel's - debugging tools, ensure that the kernel will build with all reasonable - combinations of configuration options, use cross-compilers to build for - different architectures, etc. - - - Make sure your code is compliant with the kernel coding style - guidelines. - - - Does your change have performance implications? If so, you should run - benchmarks showing what the impact (or benefit) of your change is; a - summary of the results should be included with the patch. - - - Be sure that you have the right to post the code. If this work was done - for an employer, the employer likely has a right to the work and must be - agreeable with its release under the GPL. - -As a general rule, putting in some extra thought before posting code almost -always pays back the effort in short order. - - -Patch preparation ------------------ - -The preparation of patches for posting can be a surprising amount of work, -but, once again, attempting to save time here is not generally advisable -even in the short term. - -Patches must be prepared against a specific version of the kernel. As a -general rule, a patch should be based on the current mainline as found in -Linus's git tree. When basing on mainline, start with a well-known release -point - a stable or -rc release - rather than branching off the mainline at -an arbitrary spot. - -It may become necessary to make versions against -mm, linux-next, or a -subsystem tree, though, to facilitate wider testing and review. Depending -on the area of your patch and what is going on elsewhere, basing a patch -against these other trees can require a significant amount of work -resolving conflicts and dealing with API changes. - -Only the most simple changes should be formatted as a single patch; -everything else should be made as a logical series of changes. Splitting -up patches is a bit of an art; some developers spend a long time figuring -out how to do it in the way that the community expects. There are a few -rules of thumb, however, which can help considerably: - - - The patch series you post will almost certainly not be the series of - changes found in your working revision control system. Instead, the - changes you have made need to be considered in their final form, then - split apart in ways which make sense. The developers are interested in - discrete, self-contained changes, not the path you took to get to those - changes. - - - Each logically independent change should be formatted as a separate - patch. These changes can be small ("add a field to this structure") or - large (adding a significant new driver, for example), but they should be - conceptually small and amenable to a one-line description. Each patch - should make a specific change which can be reviewed on its own and - verified to do what it says it does. - - - As a way of restating the guideline above: do not mix different types of - changes in the same patch. If a single patch fixes a critical security - bug, rearranges a few structures, and reformats the code, there is a - good chance that it will be passed over and the important fix will be - lost. - - - Each patch should yield a kernel which builds and runs properly; if your - patch series is interrupted in the middle, the result should still be a - working kernel. Partial application of a patch series is a common - scenario when the "git bisect" tool is used to find regressions; if the - result is a broken kernel, you will make life harder for developers and - users who are engaging in the noble work of tracking down problems. - - - Do not overdo it, though. One developer once posted a set of edits - to a single file as 500 separate patches - an act which did not make him - the most popular person on the kernel mailing list. A single patch can - be reasonably large as long as it still contains a single *logical* - change. - - - It can be tempting to add a whole new infrastructure with a series of - patches, but to leave that infrastructure unused until the final patch - in the series enables the whole thing. This temptation should be - avoided if possible; if that series adds regressions, bisection will - finger the last patch as the one which caused the problem, even though - the real bug is elsewhere. Whenever possible, a patch which adds new - code should make that code active immediately. - -Working to create the perfect patch series can be a frustrating process -which takes quite a bit of time and thought after the "real work" has been -done. When done properly, though, it is time well spent. - - -Patch formatting and changelogs -------------------------------- - -So now you have a perfect series of patches for posting, but the work is -not done quite yet. Each patch needs to be formatted into a message which -quickly and clearly communicates its purpose to the rest of the world. To -that end, each patch will be composed of the following: - - - An optional "From" line naming the author of the patch. This line is - only necessary if you are passing on somebody else's patch via email, - but it never hurts to add it when in doubt. - - - A one-line description of what the patch does. This message should be - enough for a reader who sees it with no other context to figure out the - scope of the patch; it is the line that will show up in the "short form" - changelogs. This message is usually formatted with the relevant - subsystem name first, followed by the purpose of the patch. For - example: - - :: - - gpio: fix build on CONFIG_GPIO_SYSFS=n - - - A blank line followed by a detailed description of the contents of the - patch. This description can be as long as is required; it should say - what the patch does and why it should be applied to the kernel. - - - One or more tag lines, with, at a minimum, one Signed-off-by: line from - the author of the patch. Tags will be described in more detail below. - -The items above, together, form the changelog for the patch. Writing good -changelogs is a crucial but often-neglected art; it's worth spending -another moment discussing this issue. When writing a changelog, you should -bear in mind that a number of different people will be reading your words. -These include subsystem maintainers and reviewers who need to decide -whether the patch should be included, distributors and other maintainers -trying to decide whether a patch should be backported to other kernels, bug -hunters wondering whether the patch is responsible for a problem they are -chasing, users who want to know how the kernel has changed, and more. A -good changelog conveys the needed information to all of these people in the -most direct and concise way possible. - -To that end, the summary line should describe the effects of and motivation -for the change as well as possible given the one-line constraint. The -detailed description can then amplify on those topics and provide any -needed additional information. If the patch fixes a bug, cite the commit -which introduced the bug if possible (and please provide both the commit ID -and the title when citing commits). If a problem is associated with -specific log or compiler output, include that output to help others -searching for a solution to the same problem. If the change is meant to -support other changes coming in later patch, say so. If internal APIs are -changed, detail those changes and how other developers should respond. In -general, the more you can put yourself into the shoes of everybody who will -be reading your changelog, the better that changelog (and the kernel as a -whole) will be. - -Needless to say, the changelog should be the text used when committing the -change to a revision control system. It will be followed by: - - - The patch itself, in the unified ("-u") patch format. Using the "-p" - option to diff will associate function names with changes, making the - resulting patch easier for others to read. - -You should avoid including changes to irrelevant files (those generated by -the build process, for example, or editor backup files) in the patch. The -file "dontdiff" in the Documentation directory can help in this regard; -pass it to diff with the "-X" option. - -The tags mentioned above are used to describe how various developers have -been associated with the development of this patch. They are described in -detail in the SubmittingPatches document; what follows here is a brief -summary. Each of these lines has the format: - -:: - - tag: Full Name optional-other-stuff - -The tags in common use are: - - - Signed-off-by: this is a developer's certification that he or she has - the right to submit the patch for inclusion into the kernel. It is an - agreement to the Developer's Certificate of Origin, the full text of - which can be found in Documentation/SubmittingPatches. Code without a - proper signoff cannot be merged into the mainline. - - - Acked-by: indicates an agreement by another developer (often a - maintainer of the relevant code) that the patch is appropriate for - inclusion into the kernel. - - - Tested-by: states that the named person has tested the patch and found - it to work. - - - Reviewed-by: the named developer has reviewed the patch for correctness; - see the reviewer's statement in Documentation/SubmittingPatches for more - detail. - - - Reported-by: names a user who reported a problem which is fixed by this - patch; this tag is used to give credit to the (often underappreciated) - people who test our code and let us know when things do not work - correctly. - - - Cc: the named person received a copy of the patch and had the - opportunity to comment on it. - -Be careful in the addition of tags to your patches: only Cc: is appropriate -for addition without the explicit permission of the person named. - - -Sending the patch ------------------ - -Before you mail your patches, there are a couple of other things you should -take care of: - - - Are you sure that your mailer will not corrupt the patches? Patches - which have had gratuitous white-space changes or line wrapping performed - by the mail client will not apply at the other end, and often will not - be examined in any detail. If there is any doubt at all, mail the patch - to yourself and convince yourself that it shows up intact. - - Documentation/email-clients.txt has some helpful hints on making - specific mail clients work for sending patches. - - - Are you sure your patch is free of silly mistakes? You should always - run patches through scripts/checkpatch.pl and address the complaints it - comes up with. Please bear in mind that checkpatch.pl, while being the - embodiment of a fair amount of thought about what kernel patches should - look like, is not smarter than you. If fixing a checkpatch.pl complaint - would make the code worse, don't do it. - -Patches should always be sent as plain text. Please do not send them as -attachments; that makes it much harder for reviewers to quote sections of -the patch in their replies. Instead, just put the patch directly into your -message. - -When mailing patches, it is important to send copies to anybody who might -be interested in it. Unlike some other projects, the kernel encourages -people to err on the side of sending too many copies; don't assume that the -relevant people will see your posting on the mailing lists. In particular, -copies should go to: - - - The maintainer(s) of the affected subsystem(s). As described earlier, - the MAINTAINERS file is the first place to look for these people. - - - Other developers who have been working in the same area - especially - those who might be working there now. Using git to see who else has - modified the files you are working on can be helpful. - - - If you are responding to a bug report or a feature request, copy the - original poster as well. - - - Send a copy to the relevant mailing list, or, if nothing else applies, - the linux-kernel list. - - - If you are fixing a bug, think about whether the fix should go into the - next stable update. If so, stable@vger.kernel.org should get a copy of - the patch. Also add a "Cc: stable@vger.kernel.org" to the tags within - the patch itself; that will cause the stable team to get a notification - when your fix goes into the mainline. - -When selecting recipients for a patch, it is good to have an idea of who -you think will eventually accept the patch and get it merged. While it -is possible to send patches directly to Linus Torvalds and have him merge -them, things are not normally done that way. Linus is busy, and there are -subsystem maintainers who watch over specific parts of the kernel. Usually -you will be wanting that maintainer to merge your patches. If there is no -obvious maintainer, Andrew Morton is often the patch target of last resort. - -Patches need good subject lines. The canonical format for a patch line is -something like: - -:: - - [PATCH nn/mm] subsys: one-line description of the patch - -where "nn" is the ordinal number of the patch, "mm" is the total number of -patches in the series, and "subsys" is the name of the affected subsystem. -Clearly, nn/mm can be omitted for a single, standalone patch. - -If you have a significant series of patches, it is customary to send an -introductory description as part zero. This convention is not universally -followed though; if you use it, remember that information in the -introduction does not make it into the kernel changelogs. So please ensure -that the patches, themselves, have complete changelog information. - -In general, the second and following parts of a multi-part patch should be -sent as a reply to the first part so that they all thread together at the -receiving end. Tools like git and quilt have commands to mail out a set of -patches with the proper threading. If you have a long series, though, and -are using git, please stay away from the --chain-reply-to option to avoid -creating exceptionally deep nesting. diff --git a/Documentation/development-process/6.Followthrough.rst b/Documentation/development-process/6.Followthrough.rst deleted file mode 100644 index a173cd5f93d2..000000000000 --- a/Documentation/development-process/6.Followthrough.rst +++ /dev/null @@ -1,212 +0,0 @@ -.. _development_followthrough: - -Followthrough -============= - -At this point, you have followed the guidelines given so far and, with the -addition of your own engineering skills, have posted a perfect series of -patches. One of the biggest mistakes that even experienced kernel -developers can make is to conclude that their work is now done. In truth, -posting patches indicates a transition into the next stage of the process, -with, possibly, quite a bit of work yet to be done. - -It is a rare patch which is so good at its first posting that there is no -room for improvement. The kernel development process recognizes this fact, -and, as a result, is heavily oriented toward the improvement of posted -code. You, as the author of that code, will be expected to work with the -kernel community to ensure that your code is up to the kernel's quality -standards. A failure to participate in this process is quite likely to -prevent the inclusion of your patches into the mainline. - - -Working with reviewers ----------------------- - -A patch of any significance will result in a number of comments from other -developers as they review the code. Working with reviewers can be, for -many developers, the most intimidating part of the kernel development -process. Life can be made much easier, though, if you keep a few things in -mind: - - - If you have explained your patch well, reviewers will understand its - value and why you went to the trouble of writing it. But that value - will not keep them from asking a fundamental question: what will it be - like to maintain a kernel with this code in it five or ten years later? - Many of the changes you may be asked to make - from coding style tweaks - to substantial rewrites - come from the understanding that Linux will - still be around and under development a decade from now. - - - Code review is hard work, and it is a relatively thankless occupation; - people remember who wrote kernel code, but there is little lasting fame - for those who reviewed it. So reviewers can get grumpy, especially when - they see the same mistakes being made over and over again. If you get a - review which seems angry, insulting, or outright offensive, resist the - impulse to respond in kind. Code review is about the code, not about - the people, and code reviewers are not attacking you personally. - - - Similarly, code reviewers are not trying to promote their employers' - agendas at the expense of your own. Kernel developers often expect to - be working on the kernel years from now, but they understand that their - employer could change. They truly are, almost without exception, - working toward the creation of the best kernel they can; they are not - trying to create discomfort for their employers' competitors. - -What all of this comes down to is that, when reviewers send you comments, -you need to pay attention to the technical observations that they are -making. Do not let their form of expression or your own pride keep that -from happening. When you get review comments on a patch, take the time to -understand what the reviewer is trying to say. If possible, fix the things -that the reviewer is asking you to fix. And respond back to the reviewer: -thank them, and describe how you will answer their questions. - -Note that you do not have to agree with every change suggested by -reviewers. If you believe that the reviewer has misunderstood your code, -explain what is really going on. If you have a technical objection to a -suggested change, describe it and justify your solution to the problem. If -your explanations make sense, the reviewer will accept them. Should your -explanation not prove persuasive, though, especially if others start to -agree with the reviewer, take some time to think things over again. It can -be easy to become blinded by your own solution to a problem to the point -that you don't realize that something is fundamentally wrong or, perhaps, -you're not even solving the right problem. - -Andrew Morton has suggested that every review comment which does not result -in a code change should result in an additional code comment instead; that -can help future reviewers avoid the questions which came up the first time -around. - -One fatal mistake is to ignore review comments in the hope that they will -go away. They will not go away. If you repost code without having -responded to the comments you got the time before, you're likely to find -that your patches go nowhere. - -Speaking of reposting code: please bear in mind that reviewers are not -going to remember all the details of the code you posted the last time -around. So it is always a good idea to remind reviewers of previously -raised issues and how you dealt with them; the patch changelog is a good -place for this kind of information. Reviewers should not have to search -through list archives to familiarize themselves with what was said last -time; if you help them get a running start, they will be in a better mood -when they revisit your code. - -What if you've tried to do everything right and things still aren't going -anywhere? Most technical disagreements can be resolved through discussion, -but there are times when somebody simply has to make a decision. If you -honestly believe that this decision is going against you wrongly, you can -always try appealing to a higher power. As of this writing, that higher -power tends to be Andrew Morton. Andrew has a great deal of respect in the -kernel development community; he can often unjam a situation which seems to -be hopelessly blocked. Appealing to Andrew should not be done lightly, -though, and not before all other alternatives have been explored. And bear -in mind, of course, that he may not agree with you either. - - -What happens next ------------------ - -If a patch is considered to be a good thing to add to the kernel, and once -most of the review issues have been resolved, the next step is usually -entry into a subsystem maintainer's tree. How that works varies from one -subsystem to the next; each maintainer has his or her own way of doing -things. In particular, there may be more than one tree - one, perhaps, -dedicated to patches planned for the next merge window, and another for -longer-term work. - -For patches applying to areas for which there is no obvious subsystem tree -(memory management patches, for example), the default tree often ends up -being -mm. Patches which affect multiple subsystems can also end up going -through the -mm tree. - -Inclusion into a subsystem tree can bring a higher level of visibility to a -patch. Now other developers working with that tree will get the patch by -default. Subsystem trees typically feed linux-next as well, making their -contents visible to the development community as a whole. At this point, -there's a good chance that you will get more comments from a new set of -reviewers; these comments need to be answered as in the previous round. - -What may also happen at this point, depending on the nature of your patch, -is that conflicts with work being done by others turn up. In the worst -case, heavy patch conflicts can result in some work being put on the back -burner so that the remaining patches can be worked into shape and merged. -Other times, conflict resolution will involve working with the other -developers and, possibly, moving some patches between trees to ensure that -everything applies cleanly. This work can be a pain, but count your -blessings: before the advent of the linux-next tree, these conflicts often -only turned up during the merge window and had to be addressed in a hurry. -Now they can be resolved at leisure, before the merge window opens. - -Some day, if all goes well, you'll log on and see that your patch has been -merged into the mainline kernel. Congratulations! Once the celebration is -complete (and you have added yourself to the MAINTAINERS file), though, it -is worth remembering an important little fact: the job still is not done. -Merging into the mainline brings its own challenges. - -To begin with, the visibility of your patch has increased yet again. There -may be a new round of comments from developers who had not been aware of -the patch before. It may be tempting to ignore them, since there is no -longer any question of your code being merged. Resist that temptation, -though; you still need to be responsive to developers who have questions or -suggestions. - -More importantly, though: inclusion into the mainline puts your code into -the hands of a much larger group of testers. Even if you have contributed -a driver for hardware which is not yet available, you will be surprised by -how many people will build your code into their kernels. And, of course, -where there are testers, there will be bug reports. - -The worst sort of bug reports are regressions. If your patch causes a -regression, you'll find an uncomfortable number of eyes upon you; -regressions need to be fixed as soon as possible. If you are unwilling or -unable to fix the regression (and nobody else does it for you), your patch -will almost certainly be removed during the stabilization period. Beyond -negating all of the work you have done to get your patch into the mainline, -having a patch pulled as the result of a failure to fix a regression could -well make it harder for you to get work merged in the future. - -After any regressions have been dealt with, there may be other, ordinary -bugs to deal with. The stabilization period is your best opportunity to -fix these bugs and ensure that your code's debut in a mainline kernel -release is as solid as possible. So, please, answer bug reports, and fix -the problems if at all possible. That's what the stabilization period is -for; you can start creating cool new patches once any problems with the old -ones have been taken care of. - -And don't forget that there are other milestones which may also create bug -reports: the next mainline stable release, when prominent distributors pick -up a version of the kernel containing your patch, etc. Continuing to -respond to these reports is a matter of basic pride in your work. If that -is insufficient motivation, though, it's also worth considering that the -development community remembers developers who lose interest in their code -after it's merged. The next time you post a patch, they will be evaluating -it with the assumption that you will not be around to maintain it -afterward. - - -Other things that can happen ------------------------------ - -One day, you may open your mail client and see that somebody has mailed you -a patch to your code. That is one of the advantages of having your code -out there in the open, after all. If you agree with the patch, you can -either forward it on to the subsystem maintainer (be sure to include a -proper From: line so that the attribution is correct, and add a signoff of -your own), or send an Acked-by: response back and let the original poster -send it upward. - -If you disagree with the patch, send a polite response explaining why. If -possible, tell the author what changes need to be made to make the patch -acceptable to you. There is a certain resistance to merging patches which -are opposed by the author and maintainer of the code, but it only goes so -far. If you are seen as needlessly blocking good work, those patches will -eventually flow around you and get into the mainline anyway. In the Linux -kernel, nobody has absolute veto power over any code. Except maybe Linus. - -On very rare occasion, you may see something completely different: another -developer posts a different solution to your problem. At that point, -chances are that one of the two patches will not be merged, and "mine was -here first" is not considered to be a compelling technical argument. If -somebody else's patch displaces yours and gets into the mainline, there is -really only one way to respond: be pleased that your problem got solved and -get on with your work. Having one's work shoved aside in this manner can -be hurtful and discouraging, but the community will remember your reaction -long after they have forgotten whose patch actually got merged. diff --git a/Documentation/development-process/7.AdvancedTopics.rst b/Documentation/development-process/7.AdvancedTopics.rst deleted file mode 100644 index 81d61c5d62dd..000000000000 --- a/Documentation/development-process/7.AdvancedTopics.rst +++ /dev/null @@ -1,180 +0,0 @@ -.. _development_advancedtopics: - -Advanced topics -=============== - -At this point, hopefully, you have a handle on how the development process -works. There is still more to learn, however! This section will cover a -number of topics which can be helpful for developers wanting to become a -regular part of the Linux kernel development process. - -Managing patches with git -------------------------- - -The use of distributed version control for the kernel began in early 2002, -when Linus first started playing with the proprietary BitKeeper -application. While BitKeeper was controversial, the approach to software -version management it embodied most certainly was not. Distributed version -control enabled an immediate acceleration of the kernel development -project. In current times, there are several free alternatives to -BitKeeper. For better or for worse, the kernel project has settled on git -as its tool of choice. - -Managing patches with git can make life much easier for the developer, -especially as the volume of those patches grows. Git also has its rough -edges and poses certain hazards; it is a young and powerful tool which is -still being civilized by its developers. This document will not attempt to -teach the reader how to use git; that would be sufficient material for a -long document in its own right. Instead, the focus here will be on how git -fits into the kernel development process in particular. Developers who -wish to come up to speed with git will find more information at: - - http://git-scm.com/ - - http://www.kernel.org/pub/software/scm/git/docs/user-manual.html - -and on various tutorials found on the web. - -The first order of business is to read the above sites and get a solid -understanding of how git works before trying to use it to make patches -available to others. A git-using developer should be able to obtain a copy -of the mainline repository, explore the revision history, commit changes to -the tree, use branches, etc. An understanding of git's tools for the -rewriting of history (such as rebase) is also useful. Git comes with its -own terminology and concepts; a new user of git should know about refs, -remote branches, the index, fast-forward merges, pushes and pulls, detached -heads, etc. It can all be a little intimidating at the outset, but the -concepts are not that hard to grasp with a bit of study. - -Using git to generate patches for submission by email can be a good -exercise while coming up to speed. - -When you are ready to start putting up git trees for others to look at, you -will, of course, need a server that can be pulled from. Setting up such a -server with git-daemon is relatively straightforward if you have a system -which is accessible to the Internet. Otherwise, free, public hosting sites -(Github, for example) are starting to appear on the net. Established -developers can get an account on kernel.org, but those are not easy to come -by; see http://kernel.org/faq/ for more information. - -The normal git workflow involves the use of a lot of branches. Each line -of development can be separated into a separate "topic branch" and -maintained independently. Branches in git are cheap, there is no reason to -not make free use of them. And, in any case, you should not do your -development in any branch which you intend to ask others to pull from. -Publicly-available branches should be created with care; merge in patches -from development branches when they are in complete form and ready to go - -not before. - -Git provides some powerful tools which can allow you to rewrite your -development history. An inconvenient patch (one which breaks bisection, -say, or which has some other sort of obvious bug) can be fixed in place or -made to disappear from the history entirely. A patch series can be -rewritten as if it had been written on top of today's mainline, even though -you have been working on it for months. Changes can be transparently -shifted from one branch to another. And so on. Judicious use of git's -ability to revise history can help in the creation of clean patch sets with -fewer problems. - -Excessive use of this capability can lead to other problems, though, beyond -a simple obsession for the creation of the perfect project history. -Rewriting history will rewrite the changes contained in that history, -turning a tested (hopefully) kernel tree into an untested one. But, beyond -that, developers cannot easily collaborate if they do not have a shared -view of the project history; if you rewrite history which other developers -have pulled into their repositories, you will make life much more difficult -for those developers. So a simple rule of thumb applies here: history -which has been exported to others should generally be seen as immutable -thereafter. - -So, once you push a set of changes to your publicly-available server, those -changes should not be rewritten. Git will attempt to enforce this rule if -you try to push changes which do not result in a fast-forward merge -(i.e. changes which do not share the same history). It is possible to -override this check, and there may be times when it is necessary to rewrite -an exported tree. Moving changesets between trees to avoid conflicts in -linux-next is one example. But such actions should be rare. This is one -of the reasons why development should be done in private branches (which -can be rewritten if necessary) and only moved into public branches when -it's in a reasonably advanced state. - -As the mainline (or other tree upon which a set of changes is based) -advances, it is tempting to merge with that tree to stay on the leading -edge. For a private branch, rebasing can be an easy way to keep up with -another tree, but rebasing is not an option once a tree is exported to the -world. Once that happens, a full merge must be done. Merging occasionally -makes good sense, but overly frequent merges can clutter the history -needlessly. Suggested technique in this case is to merge infrequently, and -generally only at specific release points (such as a mainline -rc -release). If you are nervous about specific changes, you can always -perform test merges in a private branch. The git "rerere" tool can be -useful in such situations; it remembers how merge conflicts were resolved -so that you don't have to do the same work twice. - -One of the biggest recurring complaints about tools like git is this: the -mass movement of patches from one repository to another makes it easy to -slip in ill-advised changes which go into the mainline below the review -radar. Kernel developers tend to get unhappy when they see that kind of -thing happening; putting up a git tree with unreviewed or off-topic patches -can affect your ability to get trees pulled in the future. Quoting Linus: - -:: - - You can send me patches, but for me to pull a git patch from you, I - need to know that you know what you're doing, and I need to be able - to trust things *without* then having to go and check every - individual change by hand. - -(http://lwn.net/Articles/224135/). - -To avoid this kind of situation, ensure that all patches within a given -branch stick closely to the associated topic; a "driver fixes" branch -should not be making changes to the core memory management code. And, most -importantly, do not use a git tree to bypass the review process. Post an -occasional summary of the tree to the relevant list, and, when the time is -right, request that the tree be included in linux-next. - -If and when others start to send patches for inclusion into your tree, -don't forget to review them. Also ensure that you maintain the correct -authorship information; the git "am" tool does its best in this regard, but -you may have to add a "From:" line to the patch if it has been relayed to -you via a third party. - -When requesting a pull, be sure to give all the relevant information: where -your tree is, what branch to pull, and what changes will result from the -pull. The git request-pull command can be helpful in this regard; it will -format the request as other developers expect, and will also check to be -sure that you have remembered to push those changes to the public server. - - -Reviewing patches ------------------ - -Some readers will certainly object to putting this section with "advanced -topics" on the grounds that even beginning kernel developers should be -reviewing patches. It is certainly true that there is no better way to -learn how to program in the kernel environment than by looking at code -posted by others. In addition, reviewers are forever in short supply; by -looking at code you can make a significant contribution to the process as a -whole. - -Reviewing code can be an intimidating prospect, especially for a new kernel -developer who may well feel nervous about questioning code - in public - -which has been posted by those with more experience. Even code written by -the most experienced developers can be improved, though. Perhaps the best -piece of advice for reviewers (all reviewers) is this: phrase review -comments as questions rather than criticisms. Asking "how does the lock -get released in this path?" will always work better than stating "the -locking here is wrong." - -Different developers will review code from different points of view. Some -are mostly concerned with coding style and whether code lines have trailing -white space. Others will focus primarily on whether the change implemented -by the patch as a whole is a good thing for the kernel or not. Yet others -will check for problematic locking, excessive stack usage, possible -security issues, duplication of code found elsewhere, adequate -documentation, adverse effects on performance, user-space ABI changes, etc. -All types of review, if they lead to better code going into the kernel, are -welcome and worthwhile. - - diff --git a/Documentation/development-process/8.Conclusion.rst b/Documentation/development-process/8.Conclusion.rst deleted file mode 100644 index 23ec7cbc2d2b..000000000000 --- a/Documentation/development-process/8.Conclusion.rst +++ /dev/null @@ -1,74 +0,0 @@ -.. _development_conclusion: - -For more information -==================== - -There are numerous sources of information on Linux kernel development and -related topics. First among those will always be the Documentation -directory found in the kernel source distribution. The top-level HOWTO -file is an important starting point; SubmittingPatches and -SubmittingDrivers are also something which all kernel developers should -read. Many internal kernel APIs are documented using the kerneldoc -mechanism; "make htmldocs" or "make pdfdocs" can be used to generate those -documents in HTML or PDF format (though the version of TeX shipped by some -distributions runs into internal limits and fails to process the documents -properly). - -Various web sites discuss kernel development at all levels of detail. Your -author would like to humbly suggest http://lwn.net/ as a source; -information on many specific kernel topics can be found via the LWN kernel -index at: - - http://lwn.net/Kernel/Index/ - -Beyond that, a valuable resource for kernel developers is: - - http://kernelnewbies.org/ - -And, of course, one should not forget http://kernel.org/, the definitive -location for kernel release information. - -There are a number of books on kernel development: - - Linux Device Drivers, 3rd Edition (Jonathan Corbet, Alessandro - Rubini, and Greg Kroah-Hartman). Online at - http://lwn.net/Kernel/LDD3/. - - Linux Kernel Development (Robert Love). - - Understanding the Linux Kernel (Daniel Bovet and Marco Cesati). - -All of these books suffer from a common fault, though: they tend to be -somewhat obsolete by the time they hit the shelves, and they have been on -the shelves for a while now. Still, there is quite a bit of good -information to be found there. - -Documentation for git can be found at: - - http://www.kernel.org/pub/software/scm/git/docs/ - - http://www.kernel.org/pub/software/scm/git/docs/user-manual.html - - -Conclusion -========== - -Congratulations to anybody who has made it through this long-winded -document. Hopefully it has provided a helpful understanding of how the -Linux kernel is developed and how you can participate in that process. - -In the end, it's the participation that matters. Any open source software -project is no more than the sum of what its contributors put into it. The -Linux kernel has progressed as quickly and as well as it has because it has -been helped by an impressively large group of developers, all of whom are -working to make it better. The kernel is a premier example of what can be -done when thousands of people work together toward a common goal. - -The kernel can always benefit from a larger developer base, though. There -is always more work to do. But, just as importantly, most other -participants in the Linux ecosystem can benefit through contributing to the -kernel. Getting code into the mainline is the key to higher code quality, -lower maintenance and distribution costs, a higher level of influence over -the direction of kernel development, and more. It is a situation where -everybody involved wins. Fire up your editor and come join us; you will be -more than welcome. diff --git a/Documentation/development-process/conf.py b/Documentation/development-process/conf.py deleted file mode 100644 index 4b4a12dace02..000000000000 --- a/Documentation/development-process/conf.py +++ /dev/null @@ -1,10 +0,0 @@ -# -*- coding: utf-8; mode: python -*- - -project = 'Linux Kernel Development Documentation' - -tags.add("subproject") - -latex_documents = [ - ('index', 'development-process.tex', 'Linux Kernel Development Documentation', - 'The kernel development community', 'manual'), -] diff --git a/Documentation/development-process/development-process.rst b/Documentation/development-process/development-process.rst deleted file mode 100644 index bd1399f7202a..000000000000 --- a/Documentation/development-process/development-process.rst +++ /dev/null @@ -1,29 +0,0 @@ -.. _development_process_main: - -A guide to the Kernel Development Process -========================================= - -Contents: - -.. toctree:: - :numbered: - :maxdepth: 2 - - 1.Intro - 2.Process - 3.Early-stage - 4.Coding - 5.Posting - 6.Followthrough - 7.AdvancedTopics - 8.Conclusion - -The purpose of this document is to help developers (and their managers) -work with the development community with a minimum of frustration. It is -an attempt to document how this community works in a way which is -accessible to those who are not intimately familiar with Linux kernel -development (or, indeed, free software development in general). While -there is some technical material here, this is very much a process-oriented -discussion which does not require a deep knowledge of kernel programming to -understand. - diff --git a/Documentation/development-process/index.rst b/Documentation/development-process/index.rst deleted file mode 100644 index c37475d91090..000000000000 --- a/Documentation/development-process/index.rst +++ /dev/null @@ -1,9 +0,0 @@ -Linux Kernel Development Documentation -====================================== - -Contents: - -.. toctree:: - :maxdepth: 2 - - development-process diff --git a/Documentation/index.rst b/Documentation/index.rst index c53d089455a4..e1f18b3db6e4 100644 --- a/Documentation/index.rst +++ b/Documentation/index.rst @@ -12,7 +12,7 @@ Contents: :maxdepth: 2 kernel-documentation - development-process/index + process/index dev-tools/tools driver-api/index media/index diff --git a/Documentation/process/1.Intro.rst b/Documentation/process/1.Intro.rst new file mode 100644 index 000000000000..22642b3fe903 --- /dev/null +++ b/Documentation/process/1.Intro.rst @@ -0,0 +1,266 @@ +Introdution +=========== + +Executive summary +----------------- + +The rest of this section covers the scope of the kernel development process +and the kinds of frustrations that developers and their employers can +encounter there. There are a great many reasons why kernel code should be +merged into the official ("mainline") kernel, including automatic +availability to users, community support in many forms, and the ability to +influence the direction of kernel development. Code contributed to the +Linux kernel must be made available under a GPL-compatible license. + +:ref:`development_process` introduces the development process, the kernel +release cycle, and the mechanics of the merge window. The various phases in +the patch development, review, and merging cycle are covered. There is some +discussion of tools and mailing lists. Developers wanting to get started +with kernel development are encouraged to track down and fix bugs as an +initial exercise. + +:ref:`development_early_stage` covers early-stage project planning, with an +emphasis on involving the development community as soon as possible. + +:ref:`development_coding` is about the coding process; several pitfalls which +have been encountered by other developers are discussed. Some requirements for +patches are covered, and there is an introduction to some of the tools +which can help to ensure that kernel patches are correct. + +:ref:`development_posting` talks about the process of posting patches for +review. To be taken seriously by the development community, patches must be +properly formatted and described, and they must be sent to the right place. +Following the advice in this section should help to ensure the best +possible reception for your work. + +:ref:`development_followthrough` covers what happens after posting patches; the +job is far from done at that point. Working with reviewers is a crucial part +of the development process; this section offers a number of tips on how to +avoid problems at this important stage. Developers are cautioned against +assuming that the job is done when a patch is merged into the mainline. + +:ref:`development_advancedtopics` introduces a couple of "advanced" topics: +managing patches with git and reviewing patches posted by others. + +:ref:`development_conclusion` concludes the document with pointers to sources +for more information on kernel development. + +What this document is about +--------------------------- + +The Linux kernel, at over 8 million lines of code and well over 1000 +contributors to each release, is one of the largest and most active free +software projects in existence. Since its humble beginning in 1991, this +kernel has evolved into a best-of-breed operating system component which +runs on pocket-sized digital music players, desktop PCs, the largest +supercomputers in existence, and all types of systems in between. It is a +robust, efficient, and scalable solution for almost any situation. + +With the growth of Linux has come an increase in the number of developers +(and companies) wishing to participate in its development. Hardware +vendors want to ensure that Linux supports their products well, making +those products attractive to Linux users. Embedded systems vendors, who +use Linux as a component in an integrated product, want Linux to be as +capable and well-suited to the task at hand as possible. Distributors and +other software vendors who base their products on Linux have a clear +interest in the capabilities, performance, and reliability of the Linux +kernel. And end users, too, will often wish to change Linux to make it +better suit their needs. + +One of the most compelling features of Linux is that it is accessible to +these developers; anybody with the requisite skills can improve Linux and +influence the direction of its development. Proprietary products cannot +offer this kind of openness, which is a characteristic of the free software +process. But, if anything, the kernel is even more open than most other +free software projects. A typical three-month kernel development cycle can +involve over 1000 developers working for more than 100 different companies +(or for no company at all). + +Working with the kernel development community is not especially hard. But, +that notwithstanding, many potential contributors have experienced +difficulties when trying to do kernel work. The kernel community has +evolved its own distinct ways of operating which allow it to function +smoothly (and produce a high-quality product) in an environment where +thousands of lines of code are being changed every day. So it is not +surprising that Linux kernel development process differs greatly from +proprietary development methods. + +The kernel's development process may come across as strange and +intimidating to new developers, but there are good reasons and solid +experience behind it. A developer who does not understand the kernel +community's ways (or, worse, who tries to flout or circumvent them) will +have a frustrating experience in store. The development community, while +being helpful to those who are trying to learn, has little time for those +who will not listen or who do not care about the development process. + +It is hoped that those who read this document will be able to avoid that +frustrating experience. There is a lot of material here, but the effort +involved in reading it will be repaid in short order. The development +community is always in need of developers who will help to make the kernel +better; the following text should help you - or those who work for you - +join our community. + +Credits +------- + +This document was written by Jonathan Corbet, corbet@lwn.net. It has been +improved by comments from Johannes Berg, James Berry, Alex Chiang, Roland +Dreier, Randy Dunlap, Jake Edge, Jiri Kosina, Matt Mackall, Arthur Marsh, +Amanda McPherson, Andrew Morton, Andrew Price, Tsugikazu Shibata, and +Jochen Voß. + +This work was supported by the Linux Foundation; thanks especially to +Amanda McPherson, who saw the value of this effort and made it all happen. + +The importance of getting code into the mainline +------------------------------------------------ + +Some companies and developers occasionally wonder why they should bother +learning how to work with the kernel community and get their code into the +mainline kernel (the "mainline" being the kernel maintained by Linus +Torvalds and used as a base by Linux distributors). In the short term, +contributing code can look like an avoidable expense; it seems easier to +just keep the code separate and support users directly. The truth of the +matter is that keeping code separate ("out of tree") is a false economy. + +As a way of illustrating the costs of out-of-tree code, here are a few +relevant aspects of the kernel development process; most of these will be +discussed in greater detail later in this document. Consider: + +- Code which has been merged into the mainline kernel is available to all + Linux users. It will automatically be present on all distributions which + enable it. There is no need for driver disks, downloads, or the hassles + of supporting multiple versions of multiple distributions; it all just + works, for the developer and for the user. Incorporation into the + mainline solves a large number of distribution and support problems. + +- While kernel developers strive to maintain a stable interface to user + space, the internal kernel API is in constant flux. The lack of a stable + internal interface is a deliberate design decision; it allows fundamental + improvements to be made at any time and results in higher-quality code. + But one result of that policy is that any out-of-tree code requires + constant upkeep if it is to work with new kernels. Maintaining + out-of-tree code requires significant amounts of work just to keep that + code working. + + Code which is in the mainline, instead, does not require this work as the + result of a simple rule requiring any developer who makes an API change + to also fix any code that breaks as the result of that change. So code + which has been merged into the mainline has significantly lower + maintenance costs. + +- Beyond that, code which is in the kernel will often be improved by other + developers. Surprising results can come from empowering your user + community and customers to improve your product. + +- Kernel code is subjected to review, both before and after merging into + the mainline. No matter how strong the original developer's skills are, + this review process invariably finds ways in which the code can be + improved. Often review finds severe bugs and security problems. This is + especially true for code which has been developed in a closed + environment; such code benefits strongly from review by outside + developers. Out-of-tree code is lower-quality code. + +- Participation in the development process is your way to influence the + direction of kernel development. Users who complain from the sidelines + are heard, but active developers have a stronger voice - and the ability + to implement changes which make the kernel work better for their needs. + +- When code is maintained separately, the possibility that a third party + will contribute a different implementation of a similar feature always + exists. Should that happen, getting your code merged will become much + harder - to the point of impossibility. Then you will be faced with the + unpleasant alternatives of either (1) maintaining a nonstandard feature + out of tree indefinitely, or (2) abandoning your code and migrating your + users over to the in-tree version. + +- Contribution of code is the fundamental action which makes the whole + process work. By contributing your code you can add new functionality to + the kernel and provide capabilities and examples which are of use to + other kernel developers. If you have developed code for Linux (or are + thinking about doing so), you clearly have an interest in the continued + success of this platform; contributing code is one of the best ways to + help ensure that success. + +All of the reasoning above applies to any out-of-tree kernel code, +including code which is distributed in proprietary, binary-only form. +There are, however, additional factors which should be taken into account +before considering any sort of binary-only kernel code distribution. These +include: + +- The legal issues around the distribution of proprietary kernel modules + are cloudy at best; quite a few kernel copyright holders believe that + most binary-only modules are derived products of the kernel and that, as + a result, their distribution is a violation of the GNU General Public + license (about which more will be said below). Your author is not a + lawyer, and nothing in this document can possibly be considered to be + legal advice. The true legal status of closed-source modules can only be + determined by the courts. But the uncertainty which haunts those modules + is there regardless. + +- Binary modules greatly increase the difficulty of debugging kernel + problems, to the point that most kernel developers will not even try. So + the distribution of binary-only modules will make it harder for your + users to get support from the community. + +- Support is also harder for distributors of binary-only modules, who must + provide a version of the module for every distribution and every kernel + version they wish to support. Dozens of builds of a single module can + be required to provide reasonably comprehensive coverage, and your users + will have to upgrade your module separately every time they upgrade their + kernel. + +- Everything that was said above about code review applies doubly to + closed-source code. Since this code is not available at all, it cannot + have been reviewed by the community and will, beyond doubt, have serious + problems. + +Makers of embedded systems, in particular, may be tempted to disregard much +of what has been said in this section in the belief that they are shipping +a self-contained product which uses a frozen kernel version and requires no +more development after its release. This argument misses the value of +widespread code review and the value of allowing your users to add +capabilities to your product. But these products, too, have a limited +commercial life, after which a new version must be released. At that +point, vendors whose code is in the mainline and well maintained will be +much better positioned to get the new product ready for market quickly. + +Licensing +--------- + +Code is contributed to the Linux kernel under a number of licenses, but all +code must be compatible with version 2 of the GNU General Public License +(GPLv2), which is the license covering the kernel distribution as a whole. +In practice, that means that all code contributions are covered either by +GPLv2 (with, optionally, language allowing distribution under later +versions of the GPL) or the three-clause BSD license. Any contributions +which are not covered by a compatible license will not be accepted into the +kernel. + +Copyright assignments are not required (or requested) for code contributed +to the kernel. All code merged into the mainline kernel retains its +original ownership; as a result, the kernel now has thousands of owners. + +One implication of this ownership structure is that any attempt to change +the licensing of the kernel is doomed to almost certain failure. There are +few practical scenarios where the agreement of all copyright holders could +be obtained (or their code removed from the kernel). So, in particular, +there is no prospect of a migration to version 3 of the GPL in the +foreseeable future. + +It is imperative that all code contributed to the kernel be legitimately +free software. For that reason, code from anonymous (or pseudonymous) +contributors will not be accepted. All contributors are required to "sign +off" on their code, stating that the code can be distributed with the +kernel under the GPL. Code which has not been licensed as free software by +its owner, or which risks creating copyright-related problems for the +kernel (such as code which derives from reverse-engineering efforts lacking +proper safeguards) cannot be contributed. + +Questions about copyright-related issues are common on Linux development +mailing lists. Such questions will normally receive no shortage of +answers, but one should bear in mind that the people answering those +questions are not lawyers and cannot provide legal advice. If you have +legal questions relating to Linux source code, there is no substitute for +talking with a lawyer who understands this field. Relying on answers +obtained on technical mailing lists is a risky affair. diff --git a/Documentation/process/2.Process.rst b/Documentation/process/2.Process.rst new file mode 100644 index 000000000000..ce5561bb3f8e --- /dev/null +++ b/Documentation/process/2.Process.rst @@ -0,0 +1,497 @@ +.. _development_process: + +How the development process works +================================= + +Linux kernel development in the early 1990's was a pretty loose affair, +with relatively small numbers of users and developers involved. With a +user base in the millions and with some 2,000 developers involved over the +course of one year, the kernel has since had to evolve a number of +processes to keep development happening smoothly. A solid understanding of +how the process works is required in order to be an effective part of it. + +The big picture +--------------- + +The kernel developers use a loosely time-based release process, with a new +major kernel release happening every two or three months. The recent +release history looks like this: + + ====== ================= + 2.6.38 March 14, 2011 + 2.6.37 January 4, 2011 + 2.6.36 October 20, 2010 + 2.6.35 August 1, 2010 + 2.6.34 May 15, 2010 + 2.6.33 February 24, 2010 + ====== ================= + +Every 2.6.x release is a major kernel release with new features, internal +API changes, and more. A typical 2.6 release can contain nearly 10,000 +changesets with changes to several hundred thousand lines of code. 2.6 is +thus the leading edge of Linux kernel development; the kernel uses a +rolling development model which is continually integrating major changes. + +A relatively straightforward discipline is followed with regard to the +merging of patches for each release. At the beginning of each development +cycle, the "merge window" is said to be open. At that time, code which is +deemed to be sufficiently stable (and which is accepted by the development +community) is merged into the mainline kernel. The bulk of changes for a +new development cycle (and all of the major changes) will be merged during +this time, at a rate approaching 1,000 changes ("patches," or "changesets") +per day. + +(As an aside, it is worth noting that the changes integrated during the +merge window do not come out of thin air; they have been collected, tested, +and staged ahead of time. How that process works will be described in +detail later on). + +The merge window lasts for approximately two weeks. At the end of this +time, Linus Torvalds will declare that the window is closed and release the +first of the "rc" kernels. For the kernel which is destined to be 2.6.40, +for example, the release which happens at the end of the merge window will +be called 2.6.40-rc1. The -rc1 release is the signal that the time to +merge new features has passed, and that the time to stabilize the next +kernel has begun. + +Over the next six to ten weeks, only patches which fix problems should be +submitted to the mainline. On occasion a more significant change will be +allowed, but such occasions are rare; developers who try to merge new +features outside of the merge window tend to get an unfriendly reception. +As a general rule, if you miss the merge window for a given feature, the +best thing to do is to wait for the next development cycle. (An occasional +exception is made for drivers for previously-unsupported hardware; if they +touch no in-tree code, they cannot cause regressions and should be safe to +add at any time). + +As fixes make their way into the mainline, the patch rate will slow over +time. Linus releases new -rc kernels about once a week; a normal series +will get up to somewhere between -rc6 and -rc9 before the kernel is +considered to be sufficiently stable and the final 2.6.x release is made. +At that point the whole process starts over again. + +As an example, here is how the 2.6.38 development cycle went (all dates in +2011): + + ============== =============================== + January 4 2.6.37 stable release + January 18 2.6.38-rc1, merge window closes + January 21 2.6.38-rc2 + February 1 2.6.38-rc3 + February 7 2.6.38-rc4 + February 15 2.6.38-rc5 + February 21 2.6.38-rc6 + March 1 2.6.38-rc7 + March 7 2.6.38-rc8 + March 14 2.6.38 stable release + ============== =============================== + +How do the developers decide when to close the development cycle and create +the stable release? The most significant metric used is the list of +regressions from previous releases. No bugs are welcome, but those which +break systems which worked in the past are considered to be especially +serious. For this reason, patches which cause regressions are looked upon +unfavorably and are quite likely to be reverted during the stabilization +period. + +The developers' goal is to fix all known regressions before the stable +release is made. In the real world, this kind of perfection is hard to +achieve; there are just too many variables in a project of this size. +There comes a point where delaying the final release just makes the problem +worse; the pile of changes waiting for the next merge window will grow +larger, creating even more regressions the next time around. So most 2.6.x +kernels go out with a handful of known regressions though, hopefully, none +of them are serious. + +Once a stable release is made, its ongoing maintenance is passed off to the +"stable team," currently consisting of Greg Kroah-Hartman. The stable team +will release occasional updates to the stable release using the 2.6.x.y +numbering scheme. To be considered for an update release, a patch must (1) +fix a significant bug, and (2) already be merged into the mainline for the +next development kernel. Kernels will typically receive stable updates for +a little more than one development cycle past their initial release. So, +for example, the 2.6.36 kernel's history looked like: + + ============== =============================== + October 10 2.6.36 stable release + November 22 2.6.36.1 + December 9 2.6.36.2 + January 7 2.6.36.3 + February 17 2.6.36.4 + ============== =============================== + +2.6.36.4 was the final stable update for the 2.6.36 release. + +Some kernels are designated "long term" kernels; they will receive support +for a longer period. As of this writing, the current long term kernels +and their maintainers are: + + ====== ====================== =========================== + 2.6.27 Willy Tarreau (Deep-frozen stable kernel) + 2.6.32 Greg Kroah-Hartman + 2.6.35 Andi Kleen (Embedded flag kernel) + ====== ====================== =========================== + +The selection of a kernel for long-term support is purely a matter of a +maintainer having the need and the time to maintain that release. There +are no known plans for long-term support for any specific upcoming +release. + + +The lifecycle of a patch +------------------------ + +Patches do not go directly from the developer's keyboard into the mainline +kernel. There is, instead, a somewhat involved (if somewhat informal) +process designed to ensure that each patch is reviewed for quality and that +each patch implements a change which is desirable to have in the mainline. +This process can happen quickly for minor fixes, or, in the case of large +and controversial changes, go on for years. Much developer frustration +comes from a lack of understanding of this process or from attempts to +circumvent it. + +In the hopes of reducing that frustration, this document will describe how +a patch gets into the kernel. What follows below is an introduction which +describes the process in a somewhat idealized way. A much more detailed +treatment will come in later sections. + +The stages that a patch goes through are, generally: + + - Design. This is where the real requirements for the patch - and the way + those requirements will be met - are laid out. Design work is often + done without involving the community, but it is better to do this work + in the open if at all possible; it can save a lot of time redesigning + things later. + + - Early review. Patches are posted to the relevant mailing list, and + developers on that list reply with any comments they may have. This + process should turn up any major problems with a patch if all goes + well. + + - Wider review. When the patch is getting close to ready for mainline + inclusion, it should be accepted by a relevant subsystem maintainer - + though this acceptance is not a guarantee that the patch will make it + all the way to the mainline. The patch will show up in the maintainer's + subsystem tree and into the -next trees (described below). When the + process works, this step leads to more extensive review of the patch and + the discovery of any problems resulting from the integration of this + patch with work being done by others. + +- Please note that most maintainers also have day jobs, so merging + your patch may not be their highest priority. If your patch is + getting feedback about changes that are needed, you should either + make those changes or justify why they should not be made. If your + patch has no review complaints but is not being merged by its + appropriate subsystem or driver maintainer, you should be persistent + in updating the patch to the current kernel so that it applies cleanly + and keep sending it for review and merging. + + - Merging into the mainline. Eventually, a successful patch will be + merged into the mainline repository managed by Linus Torvalds. More + comments and/or problems may surface at this time; it is important that + the developer be responsive to these and fix any issues which arise. + + - Stable release. The number of users potentially affected by the patch + is now large, so, once again, new problems may arise. + + - Long-term maintenance. While it is certainly possible for a developer + to forget about code after merging it, that sort of behavior tends to + leave a poor impression in the development community. Merging code + eliminates some of the maintenance burden, in that others will fix + problems caused by API changes. But the original developer should + continue to take responsibility for the code if it is to remain useful + in the longer term. + +One of the largest mistakes made by kernel developers (or their employers) +is to try to cut the process down to a single "merging into the mainline" +step. This approach invariably leads to frustration for everybody +involved. + +How patches get into the Kernel +------------------------------- + +There is exactly one person who can merge patches into the mainline kernel +repository: Linus Torvalds. But, of the over 9,500 patches which went +into the 2.6.38 kernel, only 112 (around 1.3%) were directly chosen by Linus +himself. The kernel project has long since grown to a size where no single +developer could possibly inspect and select every patch unassisted. The +way the kernel developers have addressed this growth is through the use of +a lieutenant system built around a chain of trust. + +The kernel code base is logically broken down into a set of subsystems: +networking, specific architecture support, memory management, video +devices, etc. Most subsystems have a designated maintainer, a developer +who has overall responsibility for the code within that subsystem. These +subsystem maintainers are the gatekeepers (in a loose way) for the portion +of the kernel they manage; they are the ones who will (usually) accept a +patch for inclusion into the mainline kernel. + +Subsystem maintainers each manage their own version of the kernel source +tree, usually (but certainly not always) using the git source management +tool. Tools like git (and related tools like quilt or mercurial) allow +maintainers to track a list of patches, including authorship information +and other metadata. At any given time, the maintainer can identify which +patches in his or her repository are not found in the mainline. + +When the merge window opens, top-level maintainers will ask Linus to "pull" +the patches they have selected for merging from their repositories. If +Linus agrees, the stream of patches will flow up into his repository, +becoming part of the mainline kernel. The amount of attention that Linus +pays to specific patches received in a pull operation varies. It is clear +that, sometimes, he looks quite closely. But, as a general rule, Linus +trusts the subsystem maintainers to not send bad patches upstream. + +Subsystem maintainers, in turn, can pull patches from other maintainers. +For example, the networking tree is built from patches which accumulated +first in trees dedicated to network device drivers, wireless networking, +etc. This chain of repositories can be arbitrarily long, though it rarely +exceeds two or three links. Since each maintainer in the chain trusts +those managing lower-level trees, this process is known as the "chain of +trust." + +Clearly, in a system like this, getting patches into the kernel depends on +finding the right maintainer. Sending patches directly to Linus is not +normally the right way to go. + + +Next trees +---------- + +The chain of subsystem trees guides the flow of patches into the kernel, +but it also raises an interesting question: what if somebody wants to look +at all of the patches which are being prepared for the next merge window? +Developers will be interested in what other changes are pending to see +whether there are any conflicts to worry about; a patch which changes a +core kernel function prototype, for example, will conflict with any other +patches which use the older form of that function. Reviewers and testers +want access to the changes in their integrated form before all of those +changes land in the mainline kernel. One could pull changes from all of +the interesting subsystem trees, but that would be a big and error-prone +job. + +The answer comes in the form of -next trees, where subsystem trees are +collected for testing and review. The older of these trees, maintained by +Andrew Morton, is called "-mm" (for memory management, which is how it got +started). The -mm tree integrates patches from a long list of subsystem +trees; it also has some patches aimed at helping with debugging. + +Beyond that, -mm contains a significant collection of patches which have +been selected by Andrew directly. These patches may have been posted on a +mailing list, or they may apply to a part of the kernel for which there is +no designated subsystem tree. As a result, -mm operates as a sort of +subsystem tree of last resort; if there is no other obvious path for a +patch into the mainline, it is likely to end up in -mm. Miscellaneous +patches which accumulate in -mm will eventually either be forwarded on to +an appropriate subsystem tree or be sent directly to Linus. In a typical +development cycle, approximately 5-10% of the patches going into the +mainline get there via -mm. + +The current -mm patch is available in the "mmotm" (-mm of the moment) +directory at: + + http://www.ozlabs.org/~akpm/mmotm/ + +Use of the MMOTM tree is likely to be a frustrating experience, though; +there is a definite chance that it will not even compile. + +The primary tree for next-cycle patch merging is linux-next, maintained by +Stephen Rothwell. The linux-next tree is, by design, a snapshot of what +the mainline is expected to look like after the next merge window closes. +Linux-next trees are announced on the linux-kernel and linux-next mailing +lists when they are assembled; they can be downloaded from: + + http://www.kernel.org/pub/linux/kernel/next/ + +Linux-next has become an integral part of the kernel development process; +all patches merged during a given merge window should really have found +their way into linux-next some time before the merge window opens. + + +Staging trees +------------- + +The kernel source tree contains the drivers/staging/ directory, where +many sub-directories for drivers or filesystems that are on their way to +being added to the kernel tree live. They remain in drivers/staging while +they still need more work; once complete, they can be moved into the +kernel proper. This is a way to keep track of drivers that aren't +up to Linux kernel coding or quality standards, but people may want to use +them and track development. + +Greg Kroah-Hartman currently maintains the staging tree. Drivers that +still need work are sent to him, with each driver having its own +subdirectory in drivers/staging/. Along with the driver source files, a +TODO file should be present in the directory as well. The TODO file lists +the pending work that the driver needs for acceptance into the kernel +proper, as well as a list of people that should be Cc'd for any patches to +the driver. Current rules require that drivers contributed to staging +must, at a minimum, compile properly. + +Staging can be a relatively easy way to get new drivers into the mainline +where, with luck, they will come to the attention of other developers and +improve quickly. Entry into staging is not the end of the story, though; +code in staging which is not seeing regular progress will eventually be +removed. Distributors also tend to be relatively reluctant to enable +staging drivers. So staging is, at best, a stop on the way toward becoming +a proper mainline driver. + + +Tools +----- + +As can be seen from the above text, the kernel development process depends +heavily on the ability to herd collections of patches in various +directions. The whole thing would not work anywhere near as well as it +does without suitably powerful tools. Tutorials on how to use these tools +are well beyond the scope of this document, but there is space for a few +pointers. + +By far the dominant source code management system used by the kernel +community is git. Git is one of a number of distributed version control +systems being developed in the free software community. It is well tuned +for kernel development, in that it performs quite well when dealing with +large repositories and large numbers of patches. It also has a reputation +for being difficult to learn and use, though it has gotten better over +time. Some sort of familiarity with git is almost a requirement for kernel +developers; even if they do not use it for their own work, they'll need git +to keep up with what other developers (and the mainline) are doing. + +Git is now packaged by almost all Linux distributions. There is a home +page at: + + http://git-scm.com/ + +That page has pointers to documentation and tutorials. + +Among the kernel developers who do not use git, the most popular choice is +almost certainly Mercurial: + + http://www.selenic.com/mercurial/ + +Mercurial shares many features with git, but it provides an interface which +many find easier to use. + +The other tool worth knowing about is Quilt: + + http://savannah.nongnu.org/projects/quilt/ + +Quilt is a patch management system, rather than a source code management +system. It does not track history over time; it is, instead, oriented +toward tracking a specific set of changes against an evolving code base. +Some major subsystem maintainers use quilt to manage patches intended to go +upstream. For the management of certain kinds of trees (-mm, for example), +quilt is the best tool for the job. + + +Mailing lists +------------- + +A great deal of Linux kernel development work is done by way of mailing +lists. It is hard to be a fully-functioning member of the community +without joining at least one list somewhere. But Linux mailing lists also +represent a potential hazard to developers, who risk getting buried under a +load of electronic mail, running afoul of the conventions used on the Linux +lists, or both. + +Most kernel mailing lists are run on vger.kernel.org; the master list can +be found at: + + http://vger.kernel.org/vger-lists.html + +There are lists hosted elsewhere, though; a number of them are at +lists.redhat.com. + +The core mailing list for kernel development is, of course, linux-kernel. +This list is an intimidating place to be; volume can reach 500 messages per +day, the amount of noise is high, the conversation can be severely +technical, and participants are not always concerned with showing a high +degree of politeness. But there is no other place where the kernel +development community comes together as a whole; developers who avoid this +list will miss important information. + +There are a few hints which can help with linux-kernel survival: + +- Have the list delivered to a separate folder, rather than your main + mailbox. One must be able to ignore the stream for sustained periods of + time. + +- Do not try to follow every conversation - nobody else does. It is + important to filter on both the topic of interest (though note that + long-running conversations can drift away from the original subject + without changing the email subject line) and the people who are + participating. + +- Do not feed the trolls. If somebody is trying to stir up an angry + response, ignore them. + +- When responding to linux-kernel email (or that on other lists) preserve + the Cc: header for all involved. In the absence of a strong reason (such + as an explicit request), you should never remove recipients. Always make + sure that the person you are responding to is in the Cc: list. This + convention also makes it unnecessary to explicitly ask to be copied on + replies to your postings. + +- Search the list archives (and the net as a whole) before asking + questions. Some developers can get impatient with people who clearly + have not done their homework. + +- Avoid top-posting (the practice of putting your answer above the quoted + text you are responding to). It makes your response harder to read and + makes a poor impression. + +- Ask on the correct mailing list. Linux-kernel may be the general meeting + point, but it is not the best place to find developers from all + subsystems. + +The last point - finding the correct mailing list - is a common place for +beginning developers to go wrong. Somebody who asks a networking-related +question on linux-kernel will almost certainly receive a polite suggestion +to ask on the netdev list instead, as that is the list frequented by most +networking developers. Other lists exist for the SCSI, video4linux, IDE, +filesystem, etc. subsystems. The best place to look for mailing lists is +in the MAINTAINERS file packaged with the kernel source. + + +Getting started with Kernel development +--------------------------------------- + +Questions about how to get started with the kernel development process are +common - from both individuals and companies. Equally common are missteps +which make the beginning of the relationship harder than it has to be. + +Companies often look to hire well-known developers to get a development +group started. This can, in fact, be an effective technique. But it also +tends to be expensive and does not do much to grow the pool of experienced +kernel developers. It is possible to bring in-house developers up to speed +on Linux kernel development, given the investment of a bit of time. Taking +this time can endow an employer with a group of developers who understand +the kernel and the company both, and who can help to train others as well. +Over the medium term, this is often the more profitable approach. + +Individual developers are often, understandably, at a loss for a place to +start. Beginning with a large project can be intimidating; one often wants +to test the waters with something smaller first. This is the point where +some developers jump into the creation of patches fixing spelling errors or +minor coding style issues. Unfortunately, such patches create a level of +noise which is distracting for the development community as a whole, so, +increasingly, they are looked down upon. New developers wishing to +introduce themselves to the community will not get the sort of reception +they wish for by these means. + +Andrew Morton gives this advice for aspiring kernel developers + +:: + + The #1 project for all kernel beginners should surely be "make sure + that the kernel runs perfectly at all times on all machines which + you can lay your hands on". Usually the way to do this is to work + with others on getting things fixed up (this can require + persistence!) but that's fine - it's a part of kernel development. + +(http://lwn.net/Articles/283982/). + +In the absence of obvious problems to fix, developers are advised to look +at the current lists of regressions and open bugs in general. There is +never any shortage of issues in need of fixing; by addressing these issues, +developers will gain experience with the process while, at the same time, +building respect with the rest of the development community. diff --git a/Documentation/process/3.Early-stage.rst b/Documentation/process/3.Early-stage.rst new file mode 100644 index 000000000000..af2c0af931d6 --- /dev/null +++ b/Documentation/process/3.Early-stage.rst @@ -0,0 +1,222 @@ +.. _development_early_stage: + +Early-stage planning +==================== + +When contemplating a Linux kernel development project, it can be tempting +to jump right in and start coding. As with any significant project, +though, much of the groundwork for success is best laid before the first +line of code is written. Some time spent in early planning and +communication can save far more time later on. + + +Specifying the problem +---------------------- + +Like any engineering project, a successful kernel enhancement starts with a +clear description of the problem to be solved. In some cases, this step is +easy: when a driver is needed for a specific piece of hardware, for +example. In others, though, it is tempting to confuse the real problem +with the proposed solution, and that can lead to difficulties. + +Consider an example: some years ago, developers working with Linux audio +sought a way to run applications without dropouts or other artifacts caused +by excessive latency in the system. The solution they arrived at was a +kernel module intended to hook into the Linux Security Module (LSM) +framework; this module could be configured to give specific applications +access to the realtime scheduler. This module was implemented and sent to +the linux-kernel mailing list, where it immediately ran into problems. + +To the audio developers, this security module was sufficient to solve their +immediate problem. To the wider kernel community, though, it was seen as a +misuse of the LSM framework (which is not intended to confer privileges +onto processes which they would not otherwise have) and a risk to system +stability. Their preferred solutions involved realtime scheduling access +via the rlimit mechanism for the short term, and ongoing latency reduction +work in the long term. + +The audio community, however, could not see past the particular solution +they had implemented; they were unwilling to accept alternatives. The +resulting disagreement left those developers feeling disillusioned with the +entire kernel development process; one of them went back to an audio list +and posted this: + + There are a number of very good Linux kernel developers, but they + tend to get outshouted by a large crowd of arrogant fools. Trying + to communicate user requirements to these people is a waste of + time. They are much too "intelligent" to listen to lesser mortals. + +(http://lwn.net/Articles/131776/). + +The reality of the situation was different; the kernel developers were far +more concerned about system stability, long-term maintenance, and finding +the right solution to the problem than they were with a specific module. +The moral of the story is to focus on the problem - not a specific solution +- and to discuss it with the development community before investing in the +creation of a body of code. + +So, when contemplating a kernel development project, one should obtain +answers to a short set of questions: + + - What, exactly, is the problem which needs to be solved? + + - Who are the users affected by this problem? Which use cases should the + solution address? + + - How does the kernel fall short in addressing that problem now? + +Only then does it make sense to start considering possible solutions. + + +Early discussion +---------------- + +When planning a kernel development project, it makes great sense to hold +discussions with the community before launching into implementation. Early +communication can save time and trouble in a number of ways: + + - It may well be that the problem is addressed by the kernel in ways which + you have not understood. The Linux kernel is large and has a number of + features and capabilities which are not immediately obvious. Not all + kernel capabilities are documented as well as one might like, and it is + easy to miss things. Your author has seen the posting of a complete + driver which duplicated an existing driver that the new author had been + unaware of. Code which reinvents existing wheels is not only wasteful; + it will also not be accepted into the mainline kernel. + + - There may be elements of the proposed solution which will not be + acceptable for mainline merging. It is better to find out about + problems like this before writing the code. + + - It's entirely possible that other developers have thought about the + problem; they may have ideas for a better solution, and may be willing + to help in the creation of that solution. + +Years of experience with the kernel development community have taught a +clear lesson: kernel code which is designed and developed behind closed +doors invariably has problems which are only revealed when the code is +released into the community. Sometimes these problems are severe, +requiring months or years of effort before the code can be brought up to +the kernel community's standards. Some examples include: + + - The Devicescape network stack was designed and implemented for + single-processor systems. It could not be merged into the mainline + until it was made suitable for multiprocessor systems. Retrofitting + locking and such into code is a difficult task; as a result, the merging + of this code (now called mac80211) was delayed for over a year. + + - The Reiser4 filesystem included a number of capabilities which, in the + core kernel developers' opinion, should have been implemented in the + virtual filesystem layer instead. It also included features which could + not easily be implemented without exposing the system to user-caused + deadlocks. The late revelation of these problems - and refusal to + address some of them - has caused Reiser4 to stay out of the mainline + kernel. + + - The AppArmor security module made use of internal virtual filesystem + data structures in ways which were considered to be unsafe and + unreliable. This concern (among others) kept AppArmor out of the + mainline for years. + +In each of these cases, a great deal of pain and extra work could have been +avoided with some early discussion with the kernel developers. + + +Who do you talk to? +------------------- + +When developers decide to take their plans public, the next question will +be: where do we start? The answer is to find the right mailing list(s) and +the right maintainer. For mailing lists, the best approach is to look in +the MAINTAINERS file for a relevant place to post. If there is a suitable +subsystem list, posting there is often preferable to posting on +linux-kernel; you are more likely to reach developers with expertise in the +relevant subsystem and the environment may be more supportive. + +Finding maintainers can be a bit harder. Again, the MAINTAINERS file is +the place to start. That file tends to not always be up to date, though, +and not all subsystems are represented there. The person listed in the +MAINTAINERS file may, in fact, not be the person who is actually acting in +that role currently. So, when there is doubt about who to contact, a +useful trick is to use git (and "git log" in particular) to see who is +currently active within the subsystem of interest. Look at who is writing +patches, and who, if anybody, is attaching Signed-off-by lines to those +patches. Those are the people who will be best placed to help with a new +development project. + +The task of finding the right maintainer is sometimes challenging enough +that the kernel developers have added a script to ease the process: + +:: + + .../scripts/get_maintainer.pl + +This script will return the current maintainer(s) for a given file or +directory when given the "-f" option. If passed a patch on the +command line, it will list the maintainers who should probably receive +copies of the patch. There are a number of options regulating how hard +get_maintainer.pl will search for maintainers; please be careful about +using the more aggressive options as you may end up including developers +who have no real interest in the code you are modifying. + +If all else fails, talking to Andrew Morton can be an effective way to +track down a maintainer for a specific piece of code. + + +When to post? +------------- + +If possible, posting your plans during the early stages can only be +helpful. Describe the problem being solved and any plans that have been +made on how the implementation will be done. Any information you can +provide can help the development community provide useful input on the +project. + +One discouraging thing which can happen at this stage is not a hostile +reaction, but, instead, little or no reaction at all. The sad truth of the +matter is (1) kernel developers tend to be busy, (2) there is no shortage +of people with grand plans and little code (or even prospect of code) to +back them up, and (3) nobody is obligated to review or comment on ideas +posted by others. Beyond that, high-level designs often hide problems +which are only reviewed when somebody actually tries to implement those +designs; for that reason, kernel developers would rather see the code. + +If a request-for-comments posting yields little in the way of comments, do +not assume that it means there is no interest in the project. +Unfortunately, you also cannot assume that there are no problems with your +idea. The best thing to do in this situation is to proceed, keeping the +community informed as you go. + + +Getting official buy-in +----------------------- + +If your work is being done in a corporate environment - as most Linux +kernel work is - you must, obviously, have permission from suitably +empowered managers before you can post your company's plans or code to a +public mailing list. The posting of code which has not been cleared for +release under a GPL-compatible license can be especially problematic; the +sooner that a company's management and legal staff can agree on the posting +of a kernel development project, the better off everybody involved will be. + +Some readers may be thinking at this point that their kernel work is +intended to support a product which does not yet have an officially +acknowledged existence. Revealing their employer's plans on a public +mailing list may not be a viable option. In cases like this, it is worth +considering whether the secrecy is really necessary; there is often no real +need to keep development plans behind closed doors. + +That said, there are also cases where a company legitimately cannot +disclose its plans early in the development process. Companies with +experienced kernel developers may choose to proceed in an open-loop manner +on the assumption that they will be able to avoid serious integration +problems later. For companies without that sort of in-house expertise, the +best option is often to hire an outside developer to review the plans under +a non-disclosure agreement. The Linux Foundation operates an NDA program +designed to help with this sort of situation; more information can be found +at: + + http://www.linuxfoundation.org/en/NDA_program + +This kind of review is often enough to avoid serious problems later on +without requiring public disclosure of the project. diff --git a/Documentation/process/4.Coding.rst b/Documentation/process/4.Coding.rst new file mode 100644 index 000000000000..9d5cef996f7f --- /dev/null +++ b/Documentation/process/4.Coding.rst @@ -0,0 +1,413 @@ +.. _development_coding: + +Getting the code right +====================== + +While there is much to be said for a solid and community-oriented design +process, the proof of any kernel development project is in the resulting +code. It is the code which will be examined by other developers and merged +(or not) into the mainline tree. So it is the quality of this code which +will determine the ultimate success of the project. + +This section will examine the coding process. We'll start with a look at a +number of ways in which kernel developers can go wrong. Then the focus +will shift toward doing things right and the tools which can help in that +quest. + + +Pitfalls +--------- + +Coding style +************ + +The kernel has long had a standard coding style, described in +Documentation/CodingStyle. For much of that time, the policies described +in that file were taken as being, at most, advisory. As a result, there is +a substantial amount of code in the kernel which does not meet the coding +style guidelines. The presence of that code leads to two independent +hazards for kernel developers. + +The first of these is to believe that the kernel coding standards do not +matter and are not enforced. The truth of the matter is that adding new +code to the kernel is very difficult if that code is not coded according to +the standard; many developers will request that the code be reformatted +before they will even review it. A code base as large as the kernel +requires some uniformity of code to make it possible for developers to +quickly understand any part of it. So there is no longer room for +strangely-formatted code. + +Occasionally, the kernel's coding style will run into conflict with an +employer's mandated style. In such cases, the kernel's style will have to +win before the code can be merged. Putting code into the kernel means +giving up a degree of control in a number of ways - including control over +how the code is formatted. + +The other trap is to assume that code which is already in the kernel is +urgently in need of coding style fixes. Developers may start to generate +reformatting patches as a way of gaining familiarity with the process, or +as a way of getting their name into the kernel changelogs - or both. But +pure coding style fixes are seen as noise by the development community; +they tend to get a chilly reception. So this type of patch is best +avoided. It is natural to fix the style of a piece of code while working +on it for other reasons, but coding style changes should not be made for +their own sake. + +The coding style document also should not be read as an absolute law which +can never be transgressed. If there is a good reason to go against the +style (a line which becomes far less readable if split to fit within the +80-column limit, for example), just do it. + + +Abstraction layers +****************** + +Computer Science professors teach students to make extensive use of +abstraction layers in the name of flexibility and information hiding. +Certainly the kernel makes extensive use of abstraction; no project +involving several million lines of code could do otherwise and survive. +But experience has shown that excessive or premature abstraction can be +just as harmful as premature optimization. Abstraction should be used to +the level required and no further. + +At a simple level, consider a function which has an argument which is +always passed as zero by all callers. One could retain that argument just +in case somebody eventually needs to use the extra flexibility that it +provides. By that time, though, chances are good that the code which +implements this extra argument has been broken in some subtle way which was +never noticed - because it has never been used. Or, when the need for +extra flexibility arises, it does not do so in a way which matches the +programmer's early expectation. Kernel developers will routinely submit +patches to remove unused arguments; they should, in general, not be added +in the first place. + +Abstraction layers which hide access to hardware - often to allow the bulk +of a driver to be used with multiple operating systems - are especially +frowned upon. Such layers obscure the code and may impose a performance +penalty; they do not belong in the Linux kernel. + +On the other hand, if you find yourself copying significant amounts of code +from another kernel subsystem, it is time to ask whether it would, in fact, +make sense to pull out some of that code into a separate library or to +implement that functionality at a higher level. There is no value in +replicating the same code throughout the kernel. + + +#ifdef and preprocessor use in general +************************************** + +The C preprocessor seems to present a powerful temptation to some C +programmers, who see it as a way to efficiently encode a great deal of +flexibility into a source file. But the preprocessor is not C, and heavy +use of it results in code which is much harder for others to read and +harder for the compiler to check for correctness. Heavy preprocessor use +is almost always a sign of code which needs some cleanup work. + +Conditional compilation with #ifdef is, indeed, a powerful feature, and it +is used within the kernel. But there is little desire to see code which is +sprinkled liberally with #ifdef blocks. As a general rule, #ifdef use +should be confined to header files whenever possible. +Conditionally-compiled code can be confined to functions which, if the code +is not to be present, simply become empty. The compiler will then quietly +optimize out the call to the empty function. The result is far cleaner +code which is easier to follow. + +C preprocessor macros present a number of hazards, including possible +multiple evaluation of expressions with side effects and no type safety. +If you are tempted to define a macro, consider creating an inline function +instead. The code which results will be the same, but inline functions are +easier to read, do not evaluate their arguments multiple times, and allow +the compiler to perform type checking on the arguments and return value. + + +Inline functions +**************** + +Inline functions present a hazard of their own, though. Programmers can +become enamored of the perceived efficiency inherent in avoiding a function +call and fill a source file with inline functions. Those functions, +however, can actually reduce performance. Since their code is replicated +at each call site, they end up bloating the size of the compiled kernel. +That, in turn, creates pressure on the processor's memory caches, which can +slow execution dramatically. Inline functions, as a rule, should be quite +small and relatively rare. The cost of a function call, after all, is not +that high; the creation of large numbers of inline functions is a classic +example of premature optimization. + +In general, kernel programmers ignore cache effects at their peril. The +classic time/space tradeoff taught in beginning data structures classes +often does not apply to contemporary hardware. Space *is* time, in that a +larger program will run slower than one which is more compact. + +More recent compilers take an increasingly active role in deciding whether +a given function should actually be inlined or not. So the liberal +placement of "inline" keywords may not just be excessive; it could also be +irrelevant. + + +Locking +******* + +In May, 2006, the "Devicescape" networking stack was, with great +fanfare, released under the GPL and made available for inclusion in the +mainline kernel. This donation was welcome news; support for wireless +networking in Linux was considered substandard at best, and the Devicescape +stack offered the promise of fixing that situation. Yet, this code did not +actually make it into the mainline until June, 2007 (2.6.22). What +happened? + +This code showed a number of signs of having been developed behind +corporate doors. But one large problem in particular was that it was not +designed to work on multiprocessor systems. Before this networking stack +(now called mac80211) could be merged, a locking scheme needed to be +retrofitted onto it. + +Once upon a time, Linux kernel code could be developed without thinking +about the concurrency issues presented by multiprocessor systems. Now, +however, this document is being written on a dual-core laptop. Even on +single-processor systems, work being done to improve responsiveness will +raise the level of concurrency within the kernel. The days when kernel +code could be written without thinking about locking are long past. + +Any resource (data structures, hardware registers, etc.) which could be +accessed concurrently by more than one thread must be protected by a lock. +New code should be written with this requirement in mind; retrofitting +locking after the fact is a rather more difficult task. Kernel developers +should take the time to understand the available locking primitives well +enough to pick the right tool for the job. Code which shows a lack of +attention to concurrency will have a difficult path into the mainline. + + +Regressions +*********** + +One final hazard worth mentioning is this: it can be tempting to make a +change (which may bring big improvements) which causes something to break +for existing users. This kind of change is called a "regression," and +regressions have become most unwelcome in the mainline kernel. With few +exceptions, changes which cause regressions will be backed out if the +regression cannot be fixed in a timely manner. Far better to avoid the +regression in the first place. + +It is often argued that a regression can be justified if it causes things +to work for more people than it creates problems for. Why not make a +change if it brings new functionality to ten systems for each one it +breaks? The best answer to this question was expressed by Linus in July, +2007: + +:: + + So we don't fix bugs by introducing new problems. That way lies + madness, and nobody ever knows if you actually make any real + progress at all. Is it two steps forwards, one step back, or one + step forward and two steps back? + +(http://lwn.net/Articles/243460/). + +An especially unwelcome type of regression is any sort of change to the +user-space ABI. Once an interface has been exported to user space, it must +be supported indefinitely. This fact makes the creation of user-space +interfaces particularly challenging: since they cannot be changed in +incompatible ways, they must be done right the first time. For this +reason, a great deal of thought, clear documentation, and wide review for +user-space interfaces is always required. + + +Code checking tools +------------------- + +For now, at least, the writing of error-free code remains an ideal that few +of us can reach. What we can hope to do, though, is to catch and fix as +many of those errors as possible before our code goes into the mainline +kernel. To that end, the kernel developers have put together an impressive +array of tools which can catch a wide variety of obscure problems in an +automated way. Any problem caught by the computer is a problem which will +not afflict a user later on, so it stands to reason that the automated +tools should be used whenever possible. + +The first step is simply to heed the warnings produced by the compiler. +Contemporary versions of gcc can detect (and warn about) a large number of +potential errors. Quite often, these warnings point to real problems. +Code submitted for review should, as a rule, not produce any compiler +warnings. When silencing warnings, take care to understand the real cause +and try to avoid "fixes" which make the warning go away without addressing +its cause. + +Note that not all compiler warnings are enabled by default. Build the +kernel with "make EXTRA_CFLAGS=-W" to get the full set. + +The kernel provides several configuration options which turn on debugging +features; most of these are found in the "kernel hacking" submenu. Several +of these options should be turned on for any kernel used for development or +testing purposes. In particular, you should turn on: + + - ENABLE_WARN_DEPRECATED, ENABLE_MUST_CHECK, and FRAME_WARN to get an + extra set of warnings for problems like the use of deprecated interfaces + or ignoring an important return value from a function. The output + generated by these warnings can be verbose, but one need not worry about + warnings from other parts of the kernel. + + - DEBUG_OBJECTS will add code to track the lifetime of various objects + created by the kernel and warn when things are done out of order. If + you are adding a subsystem which creates (and exports) complex objects + of its own, consider adding support for the object debugging + infrastructure. + + - DEBUG_SLAB can find a variety of memory allocation and use errors; it + should be used on most development kernels. + + - DEBUG_SPINLOCK, DEBUG_ATOMIC_SLEEP, and DEBUG_MUTEXES will find a + number of common locking errors. + +There are quite a few other debugging options, some of which will be +discussed below. Some of them have a significant performance impact and +should not be used all of the time. But some time spent learning the +available options will likely be paid back many times over in short order. + +One of the heavier debugging tools is the locking checker, or "lockdep." +This tool will track the acquisition and release of every lock (spinlock or +mutex) in the system, the order in which locks are acquired relative to +each other, the current interrupt environment, and more. It can then +ensure that locks are always acquired in the same order, that the same +interrupt assumptions apply in all situations, and so on. In other words, +lockdep can find a number of scenarios in which the system could, on rare +occasion, deadlock. This kind of problem can be painful (for both +developers and users) in a deployed system; lockdep allows them to be found +in an automated manner ahead of time. Code with any sort of non-trivial +locking should be run with lockdep enabled before being submitted for +inclusion. + +As a diligent kernel programmer, you will, beyond doubt, check the return +status of any operation (such as a memory allocation) which can fail. The +fact of the matter, though, is that the resulting failure recovery paths +are, probably, completely untested. Untested code tends to be broken code; +you could be much more confident of your code if all those error-handling +paths had been exercised a few times. + +The kernel provides a fault injection framework which can do exactly that, +especially where memory allocations are involved. With fault injection +enabled, a configurable percentage of memory allocations will be made to +fail; these failures can be restricted to a specific range of code. +Running with fault injection enabled allows the programmer to see how the +code responds when things go badly. See +Documentation/fault-injection/fault-injection.txt for more information on +how to use this facility. + +Other kinds of errors can be found with the "sparse" static analysis tool. +With sparse, the programmer can be warned about confusion between +user-space and kernel-space addresses, mixture of big-endian and +small-endian quantities, the passing of integer values where a set of bit +flags is expected, and so on. Sparse must be installed separately (it can +be found at https://sparse.wiki.kernel.org/index.php/Main_Page if your +distributor does not package it); it can then be run on the code by adding +"C=1" to your make command. + +The "Coccinelle" tool (http://coccinelle.lip6.fr/) is able to find a wide +variety of potential coding problems; it can also propose fixes for those +problems. Quite a few "semantic patches" for the kernel have been packaged +under the scripts/coccinelle directory; running "make coccicheck" will run +through those semantic patches and report on any problems found. See +Documentation/coccinelle.txt for more information. + +Other kinds of portability errors are best found by compiling your code for +other architectures. If you do not happen to have an S/390 system or a +Blackfin development board handy, you can still perform the compilation +step. A large set of cross compilers for x86 systems can be found at + + http://www.kernel.org/pub/tools/crosstool/ + +Some time spent installing and using these compilers will help avoid +embarrassment later. + + +Documentation +------------- + +Documentation has often been more the exception than the rule with kernel +development. Even so, adequate documentation will help to ease the merging +of new code into the kernel, make life easier for other developers, and +will be helpful for your users. In many cases, the addition of +documentation has become essentially mandatory. + +The first piece of documentation for any patch is its associated +changelog. Log entries should describe the problem being solved, the form +of the solution, the people who worked on the patch, any relevant +effects on performance, and anything else that might be needed to +understand the patch. Be sure that the changelog says *why* the patch is +worth applying; a surprising number of developers fail to provide that +information. + +Any code which adds a new user-space interface - including new sysfs or +/proc files - should include documentation of that interface which enables +user-space developers to know what they are working with. See +Documentation/ABI/README for a description of how this documentation should +be formatted and what information needs to be provided. + +The file Documentation/kernel-parameters.txt describes all of the kernel's +boot-time parameters. Any patch which adds new parameters should add the +appropriate entries to this file. + +Any new configuration options must be accompanied by help text which +clearly explains the options and when the user might want to select them. + +Internal API information for many subsystems is documented by way of +specially-formatted comments; these comments can be extracted and formatted +in a number of ways by the "kernel-doc" script. If you are working within +a subsystem which has kerneldoc comments, you should maintain them and add +them, as appropriate, for externally-available functions. Even in areas +which have not been so documented, there is no harm in adding kerneldoc +comments for the future; indeed, this can be a useful activity for +beginning kernel developers. The format of these comments, along with some +information on how to create kerneldoc templates can be found in the file +Documentation/kernel-documentation.rst. + +Anybody who reads through a significant amount of existing kernel code will +note that, often, comments are most notable by their absence. Once again, +the expectations for new code are higher than they were in the past; +merging uncommented code will be harder. That said, there is little desire +for verbosely-commented code. The code should, itself, be readable, with +comments explaining the more subtle aspects. + +Certain things should always be commented. Uses of memory barriers should +be accompanied by a line explaining why the barrier is necessary. The +locking rules for data structures generally need to be explained somewhere. +Major data structures need comprehensive documentation in general. +Non-obvious dependencies between separate bits of code should be pointed +out. Anything which might tempt a code janitor to make an incorrect +"cleanup" needs a comment saying why it is done the way it is. And so on. + + +Internal API changes +-------------------- + +The binary interface provided by the kernel to user space cannot be broken +except under the most severe circumstances. The kernel's internal +programming interfaces, instead, are highly fluid and can be changed when +the need arises. If you find yourself having to work around a kernel API, +or simply not using a specific functionality because it does not meet your +needs, that may be a sign that the API needs to change. As a kernel +developer, you are empowered to make such changes. + +There are, of course, some catches. API changes can be made, but they need +to be well justified. So any patch making an internal API change should be +accompanied by a description of what the change is and why it is +necessary. This kind of change should also be broken out into a separate +patch, rather than buried within a larger patch. + +The other catch is that a developer who changes an internal API is +generally charged with the task of fixing any code within the kernel tree +which is broken by the change. For a widely-used function, this duty can +lead to literally hundreds or thousands of changes - many of which are +likely to conflict with work being done by other developers. Needless to +say, this can be a large job, so it is best to be sure that the +justification is solid. Note that the Coccinelle tool can help with +wide-ranging API changes. + +When making an incompatible API change, one should, whenever possible, +ensure that code which has not been updated is caught by the compiler. +This will help you to be sure that you have found all in-tree uses of that +interface. It will also alert developers of out-of-tree code that there is +a change that they need to respond to. Supporting out-of-tree code is not +something that kernel developers need to be worried about, but we also do +not have to make life harder for out-of-tree developers than it needs to +be. diff --git a/Documentation/process/5.Posting.rst b/Documentation/process/5.Posting.rst new file mode 100644 index 000000000000..b511ddf7e82a --- /dev/null +++ b/Documentation/process/5.Posting.rst @@ -0,0 +1,321 @@ +.. _development_posting: + +Posting patches +=============== + +Sooner or later, the time comes when your work is ready to be presented to +the community for review and, eventually, inclusion into the mainline +kernel. Unsurprisingly, the kernel development community has evolved a set +of conventions and procedures which are used in the posting of patches; +following them will make life much easier for everybody involved. This +document will attempt to cover these expectations in reasonable detail; +more information can also be found in the files SubmittingPatches, +SubmittingDrivers, and SubmitChecklist in the kernel documentation +directory. + + +When to post +------------ + +There is a constant temptation to avoid posting patches before they are +completely "ready." For simple patches, that is not a problem. If the +work being done is complex, though, there is a lot to be gained by getting +feedback from the community before the work is complete. So you should +consider posting in-progress work, or even making a git tree available so +that interested developers can catch up with your work at any time. + +When posting code which is not yet considered ready for inclusion, it is a +good idea to say so in the posting itself. Also mention any major work +which remains to be done and any known problems. Fewer people will look at +patches which are known to be half-baked, but those who do will come in +with the idea that they can help you drive the work in the right direction. + + +Before creating patches +----------------------- + +There are a number of things which should be done before you consider +sending patches to the development community. These include: + + - Test the code to the extent that you can. Make use of the kernel's + debugging tools, ensure that the kernel will build with all reasonable + combinations of configuration options, use cross-compilers to build for + different architectures, etc. + + - Make sure your code is compliant with the kernel coding style + guidelines. + + - Does your change have performance implications? If so, you should run + benchmarks showing what the impact (or benefit) of your change is; a + summary of the results should be included with the patch. + + - Be sure that you have the right to post the code. If this work was done + for an employer, the employer likely has a right to the work and must be + agreeable with its release under the GPL. + +As a general rule, putting in some extra thought before posting code almost +always pays back the effort in short order. + + +Patch preparation +----------------- + +The preparation of patches for posting can be a surprising amount of work, +but, once again, attempting to save time here is not generally advisable +even in the short term. + +Patches must be prepared against a specific version of the kernel. As a +general rule, a patch should be based on the current mainline as found in +Linus's git tree. When basing on mainline, start with a well-known release +point - a stable or -rc release - rather than branching off the mainline at +an arbitrary spot. + +It may become necessary to make versions against -mm, linux-next, or a +subsystem tree, though, to facilitate wider testing and review. Depending +on the area of your patch and what is going on elsewhere, basing a patch +against these other trees can require a significant amount of work +resolving conflicts and dealing with API changes. + +Only the most simple changes should be formatted as a single patch; +everything else should be made as a logical series of changes. Splitting +up patches is a bit of an art; some developers spend a long time figuring +out how to do it in the way that the community expects. There are a few +rules of thumb, however, which can help considerably: + + - The patch series you post will almost certainly not be the series of + changes found in your working revision control system. Instead, the + changes you have made need to be considered in their final form, then + split apart in ways which make sense. The developers are interested in + discrete, self-contained changes, not the path you took to get to those + changes. + + - Each logically independent change should be formatted as a separate + patch. These changes can be small ("add a field to this structure") or + large (adding a significant new driver, for example), but they should be + conceptually small and amenable to a one-line description. Each patch + should make a specific change which can be reviewed on its own and + verified to do what it says it does. + + - As a way of restating the guideline above: do not mix different types of + changes in the same patch. If a single patch fixes a critical security + bug, rearranges a few structures, and reformats the code, there is a + good chance that it will be passed over and the important fix will be + lost. + + - Each patch should yield a kernel which builds and runs properly; if your + patch series is interrupted in the middle, the result should still be a + working kernel. Partial application of a patch series is a common + scenario when the "git bisect" tool is used to find regressions; if the + result is a broken kernel, you will make life harder for developers and + users who are engaging in the noble work of tracking down problems. + + - Do not overdo it, though. One developer once posted a set of edits + to a single file as 500 separate patches - an act which did not make him + the most popular person on the kernel mailing list. A single patch can + be reasonably large as long as it still contains a single *logical* + change. + + - It can be tempting to add a whole new infrastructure with a series of + patches, but to leave that infrastructure unused until the final patch + in the series enables the whole thing. This temptation should be + avoided if possible; if that series adds regressions, bisection will + finger the last patch as the one which caused the problem, even though + the real bug is elsewhere. Whenever possible, a patch which adds new + code should make that code active immediately. + +Working to create the perfect patch series can be a frustrating process +which takes quite a bit of time and thought after the "real work" has been +done. When done properly, though, it is time well spent. + + +Patch formatting and changelogs +------------------------------- + +So now you have a perfect series of patches for posting, but the work is +not done quite yet. Each patch needs to be formatted into a message which +quickly and clearly communicates its purpose to the rest of the world. To +that end, each patch will be composed of the following: + + - An optional "From" line naming the author of the patch. This line is + only necessary if you are passing on somebody else's patch via email, + but it never hurts to add it when in doubt. + + - A one-line description of what the patch does. This message should be + enough for a reader who sees it with no other context to figure out the + scope of the patch; it is the line that will show up in the "short form" + changelogs. This message is usually formatted with the relevant + subsystem name first, followed by the purpose of the patch. For + example: + + :: + + gpio: fix build on CONFIG_GPIO_SYSFS=n + + - A blank line followed by a detailed description of the contents of the + patch. This description can be as long as is required; it should say + what the patch does and why it should be applied to the kernel. + + - One or more tag lines, with, at a minimum, one Signed-off-by: line from + the author of the patch. Tags will be described in more detail below. + +The items above, together, form the changelog for the patch. Writing good +changelogs is a crucial but often-neglected art; it's worth spending +another moment discussing this issue. When writing a changelog, you should +bear in mind that a number of different people will be reading your words. +These include subsystem maintainers and reviewers who need to decide +whether the patch should be included, distributors and other maintainers +trying to decide whether a patch should be backported to other kernels, bug +hunters wondering whether the patch is responsible for a problem they are +chasing, users who want to know how the kernel has changed, and more. A +good changelog conveys the needed information to all of these people in the +most direct and concise way possible. + +To that end, the summary line should describe the effects of and motivation +for the change as well as possible given the one-line constraint. The +detailed description can then amplify on those topics and provide any +needed additional information. If the patch fixes a bug, cite the commit +which introduced the bug if possible (and please provide both the commit ID +and the title when citing commits). If a problem is associated with +specific log or compiler output, include that output to help others +searching for a solution to the same problem. If the change is meant to +support other changes coming in later patch, say so. If internal APIs are +changed, detail those changes and how other developers should respond. In +general, the more you can put yourself into the shoes of everybody who will +be reading your changelog, the better that changelog (and the kernel as a +whole) will be. + +Needless to say, the changelog should be the text used when committing the +change to a revision control system. It will be followed by: + + - The patch itself, in the unified ("-u") patch format. Using the "-p" + option to diff will associate function names with changes, making the + resulting patch easier for others to read. + +You should avoid including changes to irrelevant files (those generated by +the build process, for example, or editor backup files) in the patch. The +file "dontdiff" in the Documentation directory can help in this regard; +pass it to diff with the "-X" option. + +The tags mentioned above are used to describe how various developers have +been associated with the development of this patch. They are described in +detail in the SubmittingPatches document; what follows here is a brief +summary. Each of these lines has the format: + +:: + + tag: Full Name optional-other-stuff + +The tags in common use are: + + - Signed-off-by: this is a developer's certification that he or she has + the right to submit the patch for inclusion into the kernel. It is an + agreement to the Developer's Certificate of Origin, the full text of + which can be found in Documentation/SubmittingPatches. Code without a + proper signoff cannot be merged into the mainline. + + - Acked-by: indicates an agreement by another developer (often a + maintainer of the relevant code) that the patch is appropriate for + inclusion into the kernel. + + - Tested-by: states that the named person has tested the patch and found + it to work. + + - Reviewed-by: the named developer has reviewed the patch for correctness; + see the reviewer's statement in Documentation/SubmittingPatches for more + detail. + + - Reported-by: names a user who reported a problem which is fixed by this + patch; this tag is used to give credit to the (often underappreciated) + people who test our code and let us know when things do not work + correctly. + + - Cc: the named person received a copy of the patch and had the + opportunity to comment on it. + +Be careful in the addition of tags to your patches: only Cc: is appropriate +for addition without the explicit permission of the person named. + + +Sending the patch +----------------- + +Before you mail your patches, there are a couple of other things you should +take care of: + + - Are you sure that your mailer will not corrupt the patches? Patches + which have had gratuitous white-space changes or line wrapping performed + by the mail client will not apply at the other end, and often will not + be examined in any detail. If there is any doubt at all, mail the patch + to yourself and convince yourself that it shows up intact. + + Documentation/email-clients.txt has some helpful hints on making + specific mail clients work for sending patches. + + - Are you sure your patch is free of silly mistakes? You should always + run patches through scripts/checkpatch.pl and address the complaints it + comes up with. Please bear in mind that checkpatch.pl, while being the + embodiment of a fair amount of thought about what kernel patches should + look like, is not smarter than you. If fixing a checkpatch.pl complaint + would make the code worse, don't do it. + +Patches should always be sent as plain text. Please do not send them as +attachments; that makes it much harder for reviewers to quote sections of +the patch in their replies. Instead, just put the patch directly into your +message. + +When mailing patches, it is important to send copies to anybody who might +be interested in it. Unlike some other projects, the kernel encourages +people to err on the side of sending too many copies; don't assume that the +relevant people will see your posting on the mailing lists. In particular, +copies should go to: + + - The maintainer(s) of the affected subsystem(s). As described earlier, + the MAINTAINERS file is the first place to look for these people. + + - Other developers who have been working in the same area - especially + those who might be working there now. Using git to see who else has + modified the files you are working on can be helpful. + + - If you are responding to a bug report or a feature request, copy the + original poster as well. + + - Send a copy to the relevant mailing list, or, if nothing else applies, + the linux-kernel list. + + - If you are fixing a bug, think about whether the fix should go into the + next stable update. If so, stable@vger.kernel.org should get a copy of + the patch. Also add a "Cc: stable@vger.kernel.org" to the tags within + the patch itself; that will cause the stable team to get a notification + when your fix goes into the mainline. + +When selecting recipients for a patch, it is good to have an idea of who +you think will eventually accept the patch and get it merged. While it +is possible to send patches directly to Linus Torvalds and have him merge +them, things are not normally done that way. Linus is busy, and there are +subsystem maintainers who watch over specific parts of the kernel. Usually +you will be wanting that maintainer to merge your patches. If there is no +obvious maintainer, Andrew Morton is often the patch target of last resort. + +Patches need good subject lines. The canonical format for a patch line is +something like: + +:: + + [PATCH nn/mm] subsys: one-line description of the patch + +where "nn" is the ordinal number of the patch, "mm" is the total number of +patches in the series, and "subsys" is the name of the affected subsystem. +Clearly, nn/mm can be omitted for a single, standalone patch. + +If you have a significant series of patches, it is customary to send an +introductory description as part zero. This convention is not universally +followed though; if you use it, remember that information in the +introduction does not make it into the kernel changelogs. So please ensure +that the patches, themselves, have complete changelog information. + +In general, the second and following parts of a multi-part patch should be +sent as a reply to the first part so that they all thread together at the +receiving end. Tools like git and quilt have commands to mail out a set of +patches with the proper threading. If you have a long series, though, and +are using git, please stay away from the --chain-reply-to option to avoid +creating exceptionally deep nesting. diff --git a/Documentation/process/6.Followthrough.rst b/Documentation/process/6.Followthrough.rst new file mode 100644 index 000000000000..a173cd5f93d2 --- /dev/null +++ b/Documentation/process/6.Followthrough.rst @@ -0,0 +1,212 @@ +.. _development_followthrough: + +Followthrough +============= + +At this point, you have followed the guidelines given so far and, with the +addition of your own engineering skills, have posted a perfect series of +patches. One of the biggest mistakes that even experienced kernel +developers can make is to conclude that their work is now done. In truth, +posting patches indicates a transition into the next stage of the process, +with, possibly, quite a bit of work yet to be done. + +It is a rare patch which is so good at its first posting that there is no +room for improvement. The kernel development process recognizes this fact, +and, as a result, is heavily oriented toward the improvement of posted +code. You, as the author of that code, will be expected to work with the +kernel community to ensure that your code is up to the kernel's quality +standards. A failure to participate in this process is quite likely to +prevent the inclusion of your patches into the mainline. + + +Working with reviewers +---------------------- + +A patch of any significance will result in a number of comments from other +developers as they review the code. Working with reviewers can be, for +many developers, the most intimidating part of the kernel development +process. Life can be made much easier, though, if you keep a few things in +mind: + + - If you have explained your patch well, reviewers will understand its + value and why you went to the trouble of writing it. But that value + will not keep them from asking a fundamental question: what will it be + like to maintain a kernel with this code in it five or ten years later? + Many of the changes you may be asked to make - from coding style tweaks + to substantial rewrites - come from the understanding that Linux will + still be around and under development a decade from now. + + - Code review is hard work, and it is a relatively thankless occupation; + people remember who wrote kernel code, but there is little lasting fame + for those who reviewed it. So reviewers can get grumpy, especially when + they see the same mistakes being made over and over again. If you get a + review which seems angry, insulting, or outright offensive, resist the + impulse to respond in kind. Code review is about the code, not about + the people, and code reviewers are not attacking you personally. + + - Similarly, code reviewers are not trying to promote their employers' + agendas at the expense of your own. Kernel developers often expect to + be working on the kernel years from now, but they understand that their + employer could change. They truly are, almost without exception, + working toward the creation of the best kernel they can; they are not + trying to create discomfort for their employers' competitors. + +What all of this comes down to is that, when reviewers send you comments, +you need to pay attention to the technical observations that they are +making. Do not let their form of expression or your own pride keep that +from happening. When you get review comments on a patch, take the time to +understand what the reviewer is trying to say. If possible, fix the things +that the reviewer is asking you to fix. And respond back to the reviewer: +thank them, and describe how you will answer their questions. + +Note that you do not have to agree with every change suggested by +reviewers. If you believe that the reviewer has misunderstood your code, +explain what is really going on. If you have a technical objection to a +suggested change, describe it and justify your solution to the problem. If +your explanations make sense, the reviewer will accept them. Should your +explanation not prove persuasive, though, especially if others start to +agree with the reviewer, take some time to think things over again. It can +be easy to become blinded by your own solution to a problem to the point +that you don't realize that something is fundamentally wrong or, perhaps, +you're not even solving the right problem. + +Andrew Morton has suggested that every review comment which does not result +in a code change should result in an additional code comment instead; that +can help future reviewers avoid the questions which came up the first time +around. + +One fatal mistake is to ignore review comments in the hope that they will +go away. They will not go away. If you repost code without having +responded to the comments you got the time before, you're likely to find +that your patches go nowhere. + +Speaking of reposting code: please bear in mind that reviewers are not +going to remember all the details of the code you posted the last time +around. So it is always a good idea to remind reviewers of previously +raised issues and how you dealt with them; the patch changelog is a good +place for this kind of information. Reviewers should not have to search +through list archives to familiarize themselves with what was said last +time; if you help them get a running start, they will be in a better mood +when they revisit your code. + +What if you've tried to do everything right and things still aren't going +anywhere? Most technical disagreements can be resolved through discussion, +but there are times when somebody simply has to make a decision. If you +honestly believe that this decision is going against you wrongly, you can +always try appealing to a higher power. As of this writing, that higher +power tends to be Andrew Morton. Andrew has a great deal of respect in the +kernel development community; he can often unjam a situation which seems to +be hopelessly blocked. Appealing to Andrew should not be done lightly, +though, and not before all other alternatives have been explored. And bear +in mind, of course, that he may not agree with you either. + + +What happens next +----------------- + +If a patch is considered to be a good thing to add to the kernel, and once +most of the review issues have been resolved, the next step is usually +entry into a subsystem maintainer's tree. How that works varies from one +subsystem to the next; each maintainer has his or her own way of doing +things. In particular, there may be more than one tree - one, perhaps, +dedicated to patches planned for the next merge window, and another for +longer-term work. + +For patches applying to areas for which there is no obvious subsystem tree +(memory management patches, for example), the default tree often ends up +being -mm. Patches which affect multiple subsystems can also end up going +through the -mm tree. + +Inclusion into a subsystem tree can bring a higher level of visibility to a +patch. Now other developers working with that tree will get the patch by +default. Subsystem trees typically feed linux-next as well, making their +contents visible to the development community as a whole. At this point, +there's a good chance that you will get more comments from a new set of +reviewers; these comments need to be answered as in the previous round. + +What may also happen at this point, depending on the nature of your patch, +is that conflicts with work being done by others turn up. In the worst +case, heavy patch conflicts can result in some work being put on the back +burner so that the remaining patches can be worked into shape and merged. +Other times, conflict resolution will involve working with the other +developers and, possibly, moving some patches between trees to ensure that +everything applies cleanly. This work can be a pain, but count your +blessings: before the advent of the linux-next tree, these conflicts often +only turned up during the merge window and had to be addressed in a hurry. +Now they can be resolved at leisure, before the merge window opens. + +Some day, if all goes well, you'll log on and see that your patch has been +merged into the mainline kernel. Congratulations! Once the celebration is +complete (and you have added yourself to the MAINTAINERS file), though, it +is worth remembering an important little fact: the job still is not done. +Merging into the mainline brings its own challenges. + +To begin with, the visibility of your patch has increased yet again. There +may be a new round of comments from developers who had not been aware of +the patch before. It may be tempting to ignore them, since there is no +longer any question of your code being merged. Resist that temptation, +though; you still need to be responsive to developers who have questions or +suggestions. + +More importantly, though: inclusion into the mainline puts your code into +the hands of a much larger group of testers. Even if you have contributed +a driver for hardware which is not yet available, you will be surprised by +how many people will build your code into their kernels. And, of course, +where there are testers, there will be bug reports. + +The worst sort of bug reports are regressions. If your patch causes a +regression, you'll find an uncomfortable number of eyes upon you; +regressions need to be fixed as soon as possible. If you are unwilling or +unable to fix the regression (and nobody else does it for you), your patch +will almost certainly be removed during the stabilization period. Beyond +negating all of the work you have done to get your patch into the mainline, +having a patch pulled as the result of a failure to fix a regression could +well make it harder for you to get work merged in the future. + +After any regressions have been dealt with, there may be other, ordinary +bugs to deal with. The stabilization period is your best opportunity to +fix these bugs and ensure that your code's debut in a mainline kernel +release is as solid as possible. So, please, answer bug reports, and fix +the problems if at all possible. That's what the stabilization period is +for; you can start creating cool new patches once any problems with the old +ones have been taken care of. + +And don't forget that there are other milestones which may also create bug +reports: the next mainline stable release, when prominent distributors pick +up a version of the kernel containing your patch, etc. Continuing to +respond to these reports is a matter of basic pride in your work. If that +is insufficient motivation, though, it's also worth considering that the +development community remembers developers who lose interest in their code +after it's merged. The next time you post a patch, they will be evaluating +it with the assumption that you will not be around to maintain it +afterward. + + +Other things that can happen +----------------------------- + +One day, you may open your mail client and see that somebody has mailed you +a patch to your code. That is one of the advantages of having your code +out there in the open, after all. If you agree with the patch, you can +either forward it on to the subsystem maintainer (be sure to include a +proper From: line so that the attribution is correct, and add a signoff of +your own), or send an Acked-by: response back and let the original poster +send it upward. + +If you disagree with the patch, send a polite response explaining why. If +possible, tell the author what changes need to be made to make the patch +acceptable to you. There is a certain resistance to merging patches which +are opposed by the author and maintainer of the code, but it only goes so +far. If you are seen as needlessly blocking good work, those patches will +eventually flow around you and get into the mainline anyway. In the Linux +kernel, nobody has absolute veto power over any code. Except maybe Linus. + +On very rare occasion, you may see something completely different: another +developer posts a different solution to your problem. At that point, +chances are that one of the two patches will not be merged, and "mine was +here first" is not considered to be a compelling technical argument. If +somebody else's patch displaces yours and gets into the mainline, there is +really only one way to respond: be pleased that your problem got solved and +get on with your work. Having one's work shoved aside in this manner can +be hurtful and discouraging, but the community will remember your reaction +long after they have forgotten whose patch actually got merged. diff --git a/Documentation/process/7.AdvancedTopics.rst b/Documentation/process/7.AdvancedTopics.rst new file mode 100644 index 000000000000..172733cff097 --- /dev/null +++ b/Documentation/process/7.AdvancedTopics.rst @@ -0,0 +1,178 @@ +.. _development_advancedtopics: + +Advanced topics +=============== + +At this point, hopefully, you have a handle on how the development process +works. There is still more to learn, however! This section will cover a +number of topics which can be helpful for developers wanting to become a +regular part of the Linux kernel development process. + +Managing patches with git +------------------------- + +The use of distributed version control for the kernel began in early 2002, +when Linus first started playing with the proprietary BitKeeper +application. While BitKeeper was controversial, the approach to software +version management it embodied most certainly was not. Distributed version +control enabled an immediate acceleration of the kernel development +project. In current times, there are several free alternatives to +BitKeeper. For better or for worse, the kernel project has settled on git +as its tool of choice. + +Managing patches with git can make life much easier for the developer, +especially as the volume of those patches grows. Git also has its rough +edges and poses certain hazards; it is a young and powerful tool which is +still being civilized by its developers. This document will not attempt to +teach the reader how to use git; that would be sufficient material for a +long document in its own right. Instead, the focus here will be on how git +fits into the kernel development process in particular. Developers who +wish to come up to speed with git will find more information at: + + http://git-scm.com/ + + http://www.kernel.org/pub/software/scm/git/docs/user-manual.html + +and on various tutorials found on the web. + +The first order of business is to read the above sites and get a solid +understanding of how git works before trying to use it to make patches +available to others. A git-using developer should be able to obtain a copy +of the mainline repository, explore the revision history, commit changes to +the tree, use branches, etc. An understanding of git's tools for the +rewriting of history (such as rebase) is also useful. Git comes with its +own terminology and concepts; a new user of git should know about refs, +remote branches, the index, fast-forward merges, pushes and pulls, detached +heads, etc. It can all be a little intimidating at the outset, but the +concepts are not that hard to grasp with a bit of study. + +Using git to generate patches for submission by email can be a good +exercise while coming up to speed. + +When you are ready to start putting up git trees for others to look at, you +will, of course, need a server that can be pulled from. Setting up such a +server with git-daemon is relatively straightforward if you have a system +which is accessible to the Internet. Otherwise, free, public hosting sites +(Github, for example) are starting to appear on the net. Established +developers can get an account on kernel.org, but those are not easy to come +by; see http://kernel.org/faq/ for more information. + +The normal git workflow involves the use of a lot of branches. Each line +of development can be separated into a separate "topic branch" and +maintained independently. Branches in git are cheap, there is no reason to +not make free use of them. And, in any case, you should not do your +development in any branch which you intend to ask others to pull from. +Publicly-available branches should be created with care; merge in patches +from development branches when they are in complete form and ready to go - +not before. + +Git provides some powerful tools which can allow you to rewrite your +development history. An inconvenient patch (one which breaks bisection, +say, or which has some other sort of obvious bug) can be fixed in place or +made to disappear from the history entirely. A patch series can be +rewritten as if it had been written on top of today's mainline, even though +you have been working on it for months. Changes can be transparently +shifted from one branch to another. And so on. Judicious use of git's +ability to revise history can help in the creation of clean patch sets with +fewer problems. + +Excessive use of this capability can lead to other problems, though, beyond +a simple obsession for the creation of the perfect project history. +Rewriting history will rewrite the changes contained in that history, +turning a tested (hopefully) kernel tree into an untested one. But, beyond +that, developers cannot easily collaborate if they do not have a shared +view of the project history; if you rewrite history which other developers +have pulled into their repositories, you will make life much more difficult +for those developers. So a simple rule of thumb applies here: history +which has been exported to others should generally be seen as immutable +thereafter. + +So, once you push a set of changes to your publicly-available server, those +changes should not be rewritten. Git will attempt to enforce this rule if +you try to push changes which do not result in a fast-forward merge +(i.e. changes which do not share the same history). It is possible to +override this check, and there may be times when it is necessary to rewrite +an exported tree. Moving changesets between trees to avoid conflicts in +linux-next is one example. But such actions should be rare. This is one +of the reasons why development should be done in private branches (which +can be rewritten if necessary) and only moved into public branches when +it's in a reasonably advanced state. + +As the mainline (or other tree upon which a set of changes is based) +advances, it is tempting to merge with that tree to stay on the leading +edge. For a private branch, rebasing can be an easy way to keep up with +another tree, but rebasing is not an option once a tree is exported to the +world. Once that happens, a full merge must be done. Merging occasionally +makes good sense, but overly frequent merges can clutter the history +needlessly. Suggested technique in this case is to merge infrequently, and +generally only at specific release points (such as a mainline -rc +release). If you are nervous about specific changes, you can always +perform test merges in a private branch. The git "rerere" tool can be +useful in such situations; it remembers how merge conflicts were resolved +so that you don't have to do the same work twice. + +One of the biggest recurring complaints about tools like git is this: the +mass movement of patches from one repository to another makes it easy to +slip in ill-advised changes which go into the mainline below the review +radar. Kernel developers tend to get unhappy when they see that kind of +thing happening; putting up a git tree with unreviewed or off-topic patches +can affect your ability to get trees pulled in the future. Quoting Linus: + +:: + + You can send me patches, but for me to pull a git patch from you, I + need to know that you know what you're doing, and I need to be able + to trust things *without* then having to go and check every + individual change by hand. + +(http://lwn.net/Articles/224135/). + +To avoid this kind of situation, ensure that all patches within a given +branch stick closely to the associated topic; a "driver fixes" branch +should not be making changes to the core memory management code. And, most +importantly, do not use a git tree to bypass the review process. Post an +occasional summary of the tree to the relevant list, and, when the time is +right, request that the tree be included in linux-next. + +If and when others start to send patches for inclusion into your tree, +don't forget to review them. Also ensure that you maintain the correct +authorship information; the git "am" tool does its best in this regard, but +you may have to add a "From:" line to the patch if it has been relayed to +you via a third party. + +When requesting a pull, be sure to give all the relevant information: where +your tree is, what branch to pull, and what changes will result from the +pull. The git request-pull command can be helpful in this regard; it will +format the request as other developers expect, and will also check to be +sure that you have remembered to push those changes to the public server. + + +Reviewing patches +----------------- + +Some readers will certainly object to putting this section with "advanced +topics" on the grounds that even beginning kernel developers should be +reviewing patches. It is certainly true that there is no better way to +learn how to program in the kernel environment than by looking at code +posted by others. In addition, reviewers are forever in short supply; by +looking at code you can make a significant contribution to the process as a +whole. + +Reviewing code can be an intimidating prospect, especially for a new kernel +developer who may well feel nervous about questioning code - in public - +which has been posted by those with more experience. Even code written by +the most experienced developers can be improved, though. Perhaps the best +piece of advice for reviewers (all reviewers) is this: phrase review +comments as questions rather than criticisms. Asking "how does the lock +get released in this path?" will always work better than stating "the +locking here is wrong." + +Different developers will review code from different points of view. Some +are mostly concerned with coding style and whether code lines have trailing +white space. Others will focus primarily on whether the change implemented +by the patch as a whole is a good thing for the kernel or not. Yet others +will check for problematic locking, excessive stack usage, possible +security issues, duplication of code found elsewhere, adequate +documentation, adverse effects on performance, user-space ABI changes, etc. +All types of review, if they lead to better code going into the kernel, are +welcome and worthwhile. diff --git a/Documentation/process/8.Conclusion.rst b/Documentation/process/8.Conclusion.rst new file mode 100644 index 000000000000..23ec7cbc2d2b --- /dev/null +++ b/Documentation/process/8.Conclusion.rst @@ -0,0 +1,74 @@ +.. _development_conclusion: + +For more information +==================== + +There are numerous sources of information on Linux kernel development and +related topics. First among those will always be the Documentation +directory found in the kernel source distribution. The top-level HOWTO +file is an important starting point; SubmittingPatches and +SubmittingDrivers are also something which all kernel developers should +read. Many internal kernel APIs are documented using the kerneldoc +mechanism; "make htmldocs" or "make pdfdocs" can be used to generate those +documents in HTML or PDF format (though the version of TeX shipped by some +distributions runs into internal limits and fails to process the documents +properly). + +Various web sites discuss kernel development at all levels of detail. Your +author would like to humbly suggest http://lwn.net/ as a source; +information on many specific kernel topics can be found via the LWN kernel +index at: + + http://lwn.net/Kernel/Index/ + +Beyond that, a valuable resource for kernel developers is: + + http://kernelnewbies.org/ + +And, of course, one should not forget http://kernel.org/, the definitive +location for kernel release information. + +There are a number of books on kernel development: + + Linux Device Drivers, 3rd Edition (Jonathan Corbet, Alessandro + Rubini, and Greg Kroah-Hartman). Online at + http://lwn.net/Kernel/LDD3/. + + Linux Kernel Development (Robert Love). + + Understanding the Linux Kernel (Daniel Bovet and Marco Cesati). + +All of these books suffer from a common fault, though: they tend to be +somewhat obsolete by the time they hit the shelves, and they have been on +the shelves for a while now. Still, there is quite a bit of good +information to be found there. + +Documentation for git can be found at: + + http://www.kernel.org/pub/software/scm/git/docs/ + + http://www.kernel.org/pub/software/scm/git/docs/user-manual.html + + +Conclusion +========== + +Congratulations to anybody who has made it through this long-winded +document. Hopefully it has provided a helpful understanding of how the +Linux kernel is developed and how you can participate in that process. + +In the end, it's the participation that matters. Any open source software +project is no more than the sum of what its contributors put into it. The +Linux kernel has progressed as quickly and as well as it has because it has +been helped by an impressively large group of developers, all of whom are +working to make it better. The kernel is a premier example of what can be +done when thousands of people work together toward a common goal. + +The kernel can always benefit from a larger developer base, though. There +is always more work to do. But, just as importantly, most other +participants in the Linux ecosystem can benefit through contributing to the +kernel. Getting code into the mainline is the key to higher code quality, +lower maintenance and distribution costs, a higher level of influence over +the direction of kernel development, and more. It is a situation where +everybody involved wins. Fire up your editor and come join us; you will be +more than welcome. diff --git a/Documentation/process/conf.py b/Documentation/process/conf.py new file mode 100644 index 000000000000..1b01a80ad9ce --- /dev/null +++ b/Documentation/process/conf.py @@ -0,0 +1,10 @@ +# -*- coding: utf-8; mode: python -*- + +project = 'Linux Kernel Development Documentation' + +tags.add("subproject") + +latex_documents = [ + ('index', 'process.tex', 'Linux Kernel Development Documentation', + 'The kernel development community', 'manual'), +] diff --git a/Documentation/process/development-process.rst b/Documentation/process/development-process.rst new file mode 100644 index 000000000000..61c627e41ba8 --- /dev/null +++ b/Documentation/process/development-process.rst @@ -0,0 +1,28 @@ +.. _development_process_main: + +A guide to the Kernel Development Process +========================================= + +Contents: + +.. toctree:: + :numbered: + :maxdepth: 2 + + 1.Intro + 2.Process + 3.Early-stage + 4.Coding + 5.Posting + 6.Followthrough + 7.AdvancedTopics + 8.Conclusion + +The purpose of this document is to help developers (and their managers) +work with the development community with a minimum of frustration. It is +an attempt to document how this community works in a way which is +accessible to those who are not intimately familiar with Linux kernel +development (or, indeed, free software development in general). While +there is some technical material here, this is very much a process-oriented +discussion which does not require a deep knowledge of kernel programming to +understand. diff --git a/Documentation/process/index.rst b/Documentation/process/index.rst new file mode 100644 index 000000000000..c37475d91090 --- /dev/null +++ b/Documentation/process/index.rst @@ -0,0 +1,9 @@ +Linux Kernel Development Documentation +====================================== + +Contents: + +.. toctree:: + :maxdepth: 2 + + development-process -- cgit v1.2.3 From 186128f75392f8478ad1b32a675627d738881ca4 Mon Sep 17 00:00:00 2001 From: Mauro Carvalho Chehab Date: Wed, 21 Sep 2016 08:40:21 -0300 Subject: docs-rst: add documents to development-process Add several documents to the development-process ReST book. As we don't want renames, use symlinks instead, keeping those documents on their original place. Acked-by: Greg Kroah-Hartman Signed-off-by: Mauro Carvalho Chehab --- Documentation/Changes | 485 --------- Documentation/CodeOfConflict | 28 - Documentation/CodingStyle | 1062 -------------------- Documentation/HOWTO | 652 ------------ Documentation/ManagementStyle | 288 ------ Documentation/SubmitChecklist | 120 --- Documentation/SubmittingDrivers | 183 ---- Documentation/SubmittingPatches | 841 ---------------- Documentation/adding-syscals.txt | 542 ---------- Documentation/applying-patches.txt | 465 --------- Documentation/email-clients.txt | 319 ------ Documentation/kernel-docs.txt | 652 ------------ Documentation/magic-number.txt | 164 --- Documentation/process/adding-syscalls.rst | 542 ++++++++++ Documentation/process/applying-patches.rst | 464 +++++++++ Documentation/process/changes.rst | 485 +++++++++ Documentation/process/code-of-conflict.rst | 28 + Documentation/process/coding-style.rst | 1062 ++++++++++++++++++++ Documentation/process/email-clients.rst | 319 ++++++ Documentation/process/howto.rst | 652 ++++++++++++ Documentation/process/index.rst | 23 + Documentation/process/kernel-docs.rst | 652 ++++++++++++ Documentation/process/magic-number.rst | 164 +++ Documentation/process/management-style.rst | 288 ++++++ Documentation/process/stable-api-nonsense.rst | 205 ++++ Documentation/process/stable-kernel-rules.rst | 181 ++++ Documentation/process/submit-checklist.rst | 120 +++ Documentation/process/submitting-drivers.rst | 183 ++++ Documentation/process/submitting-patches.rst | 840 ++++++++++++++++ .../process/volatile-considered-harmful.rst | 122 +++ Documentation/stable_api_nonsense.txt | 205 ---- Documentation/stable_kernel_rules.txt | 181 ---- Documentation/volatile-considered-harmful.txt | 122 --- 33 files changed, 6330 insertions(+), 6309 deletions(-) delete mode 100644 Documentation/Changes delete mode 100644 Documentation/CodeOfConflict delete mode 100644 Documentation/CodingStyle delete mode 100644 Documentation/HOWTO delete mode 100644 Documentation/ManagementStyle delete mode 100644 Documentation/SubmitChecklist delete mode 100644 Documentation/SubmittingDrivers delete mode 100644 Documentation/SubmittingPatches delete mode 100644 Documentation/adding-syscals.txt delete mode 100644 Documentation/applying-patches.txt delete mode 100644 Documentation/email-clients.txt delete mode 100644 Documentation/kernel-docs.txt delete mode 100644 Documentation/magic-number.txt create mode 100644 Documentation/process/adding-syscalls.rst create mode 100644 Documentation/process/applying-patches.rst create mode 100644 Documentation/process/changes.rst create mode 100644 Documentation/process/code-of-conflict.rst create mode 100644 Documentation/process/coding-style.rst create mode 100644 Documentation/process/email-clients.rst create mode 100644 Documentation/process/howto.rst create mode 100644 Documentation/process/kernel-docs.rst create mode 100644 Documentation/process/magic-number.rst create mode 100644 Documentation/process/management-style.rst create mode 100644 Documentation/process/stable-api-nonsense.rst create mode 100644 Documentation/process/stable-kernel-rules.rst create mode 100644 Documentation/process/submit-checklist.rst create mode 100644 Documentation/process/submitting-drivers.rst create mode 100644 Documentation/process/submitting-patches.rst create mode 100644 Documentation/process/volatile-considered-harmful.rst delete mode 100644 Documentation/stable_api_nonsense.txt delete mode 100644 Documentation/stable_kernel_rules.txt delete mode 100644 Documentation/volatile-considered-harmful.txt diff --git a/Documentation/Changes b/Documentation/Changes deleted file mode 100644 index 22797a15dc24..000000000000 --- a/Documentation/Changes +++ /dev/null @@ -1,485 +0,0 @@ -.. _changes: - -Minimal requerements to compile the Kernel -++++++++++++++++++++++++++++++++++++++++++ - -Intro -===== - -This document is designed to provide a list of the minimum levels of -software necessary to run the 4.x kernels. - -This document is originally based on my "Changes" file for 2.0.x kernels -and therefore owes credit to the same people as that file (Jared Mauch, -Axel Boldt, Alessandro Sigala, and countless other users all over the -'net). - -Current Minimal Requirements -**************************** - -Upgrade to at **least** these software revisions before thinking you've -encountered a bug! If you're unsure what version you're currently -running, the suggested command should tell you. - -Again, keep in mind that this list assumes you are already functionally -running a Linux kernel. Also, not all tools are necessary on all -systems; obviously, if you don't have any ISDN hardware, for example, -you probably needn't concern yourself with isdn4k-utils. - -====================== =============== ======================================== - Program Minimal version Command to check the version -====================== =============== ======================================== -GNU C 3.2 gcc --version -GNU make 3.80 make --version -binutils 2.12 ld -v -util-linux 2.10o fdformat --version -module-init-tools 0.9.10 depmod -V -e2fsprogs 1.41.4 e2fsck -V -jfsutils 1.1.3 fsck.jfs -V -reiserfsprogs 3.6.3 reiserfsck -V -xfsprogs 2.6.0 xfs_db -V -squashfs-tools 4.0 mksquashfs -version -btrfs-progs 0.18 btrfsck -pcmciautils 004 pccardctl -V -quota-tools 3.09 quota -V -PPP 2.4.0 pppd --version -isdn4k-utils 3.1pre1 isdnctrl 2>&1|grep version -nfs-utils 1.0.5 showmount --version -procps 3.2.0 ps --version -oprofile 0.9 oprofiled --version -udev 081 udevd --version -grub 0.93 grub --version || grub-install --version -mcelog 0.6 mcelog --version -iptables 1.4.2 iptables -V -openssl & libcrypto 1.0.0 openssl version -bc 1.06.95 bc --version -Sphinx\ [#f1]_ 1.2 sphinx-build --version -====================== =============== ======================================== - -.. [#f1] Sphinx is needed only to build the Kernel documentation - -Kernel compilation -****************** - -GCC ---- - -The gcc version requirements may vary depending on the type of CPU in your -computer. - -Make ----- - -You will need GNU make 3.80 or later to build the kernel. - -Binutils --------- - -Linux on IA-32 has recently switched from using ``as86`` to using ``gas`` for -assembling the 16-bit boot code, removing the need for ``as86`` to compile -your kernel. This change does, however, mean that you need a recent -release of binutils. - -Perl ----- - -You will need perl 5 and the following modules: ``Getopt::Long``, -``Getopt::Std``, ``File::Basename``, and ``File::Find`` to build the kernel. - -BC --- - -You will need bc to build kernels 3.10 and higher - - -OpenSSL -------- - -Module signing and external certificate handling use the OpenSSL program and -crypto library to do key creation and signature generation. - -You will need openssl to build kernels 3.7 and higher if module signing is -enabled. You will also need openssl development packages to build kernels 4.3 -and higher. - - -System utilities -**************** - -Architectural changes ---------------------- - -DevFS has been obsoleted in favour of udev -(http://www.kernel.org/pub/linux/utils/kernel/hotplug/) - -32-bit UID support is now in place. Have fun! - -Linux documentation for functions is transitioning to inline -documentation via specially-formatted comments near their -definitions in the source. These comments can be combined with the -SGML templates in the Documentation/DocBook directory to make DocBook -files, which can then be converted by DocBook stylesheets to PostScript, -HTML, PDF files, and several other formats. In order to convert from -DocBook format to a format of your choice, you'll need to install Jade as -well as the desired DocBook stylesheets. - -Util-linux ----------- - -New versions of util-linux provide ``fdisk`` support for larger disks, -support new options to mount, recognize more supported partition -types, have a fdformat which works with 2.4 kernels, and similar goodies. -You'll probably want to upgrade. - -Ksymoops --------- - -If the unthinkable happens and your kernel oopses, you may need the -ksymoops tool to decode it, but in most cases you don't. -It is generally preferred to build the kernel with ``CONFIG_KALLSYMS`` so -that it produces readable dumps that can be used as-is (this also -produces better output than ksymoops). If for some reason your kernel -is not build with ``CONFIG_KALLSYMS`` and you have no way to rebuild and -reproduce the Oops with that option, then you can still decode that Oops -with ksymoops. - -Module-Init-Tools ------------------ - -A new module loader is now in the kernel that requires ``module-init-tools`` -to use. It is backward compatible with the 2.4.x series kernels. - -Mkinitrd --------- - -These changes to the ``/lib/modules`` file tree layout also require that -mkinitrd be upgraded. - -E2fsprogs ---------- - -The latest version of ``e2fsprogs`` fixes several bugs in fsck and -debugfs. Obviously, it's a good idea to upgrade. - -JFSutils --------- - -The ``jfsutils`` package contains the utilities for the file system. -The following utilities are available: - -- ``fsck.jfs`` - initiate replay of the transaction log, and check - and repair a JFS formatted partition. - -- ``mkfs.jfs`` - create a JFS formatted partition. - -- other file system utilities are also available in this package. - -Reiserfsprogs -------------- - -The reiserfsprogs package should be used for reiserfs-3.6.x -(Linux kernels 2.4.x). It is a combined package and contains working -versions of ``mkreiserfs``, ``resize_reiserfs``, ``debugreiserfs`` and -``reiserfsck``. These utils work on both i386 and alpha platforms. - -Xfsprogs --------- - -The latest version of ``xfsprogs`` contains ``mkfs.xfs``, ``xfs_db``, and the -``xfs_repair`` utilities, among others, for the XFS filesystem. It is -architecture independent and any version from 2.0.0 onward should -work correctly with this version of the XFS kernel code (2.6.0 or -later is recommended, due to some significant improvements). - -PCMCIAutils ------------ - -PCMCIAutils replaces ``pcmcia-cs``. It properly sets up -PCMCIA sockets at system startup and loads the appropriate modules -for 16-bit PCMCIA devices if the kernel is modularized and the hotplug -subsystem is used. - -Quota-tools ------------ - -Support for 32 bit uid's and gid's is required if you want to use -the newer version 2 quota format. Quota-tools version 3.07 and -newer has this support. Use the recommended version or newer -from the table above. - -Intel IA32 microcode --------------------- - -A driver has been added to allow updating of Intel IA32 microcode, -accessible as a normal (misc) character device. If you are not using -udev you may need to:: - - mkdir /dev/cpu - mknod /dev/cpu/microcode c 10 184 - chmod 0644 /dev/cpu/microcode - -as root before you can use this. You'll probably also want to -get the user-space microcode_ctl utility to use with this. - -udev ----- - -``udev`` is a userspace application for populating ``/dev`` dynamically with -only entries for devices actually present. ``udev`` replaces the basic -functionality of devfs, while allowing persistent device naming for -devices. - -FUSE ----- - -Needs libfuse 2.4.0 or later. Absolute minimum is 2.3.0 but mount -options ``direct_io`` and ``kernel_cache`` won't work. - -Networking -********** - -General changes ---------------- - -If you have advanced network configuration needs, you should probably -consider using the network tools from ip-route2. - -Packet Filter / NAT -------------------- -The packet filtering and NAT code uses the same tools like the previous 2.4.x -kernel series (iptables). It still includes backwards-compatibility modules -for 2.2.x-style ipchains and 2.0.x-style ipfwadm. - -PPP ---- - -The PPP driver has been restructured to support multilink and to -enable it to operate over diverse media layers. If you use PPP, -upgrade pppd to at least 2.4.0. - -If you are not using udev, you must have the device file /dev/ppp -which can be made by:: - - mknod /dev/ppp c 108 0 - -as root. - -Isdn4k-utils ------------- - -Due to changes in the length of the phone number field, isdn4k-utils -needs to be recompiled or (preferably) upgraded. - -NFS-utils ---------- - -In ancient (2.4 and earlier) kernels, the nfs server needed to know -about any client that expected to be able to access files via NFS. This -information would be given to the kernel by ``mountd`` when the client -mounted the filesystem, or by ``exportfs`` at system startup. exportfs -would take information about active clients from ``/var/lib/nfs/rmtab``. - -This approach is quite fragile as it depends on rmtab being correct -which is not always easy, particularly when trying to implement -fail-over. Even when the system is working well, ``rmtab`` suffers from -getting lots of old entries that never get removed. - -With modern kernels we have the option of having the kernel tell mountd -when it gets a request from an unknown host, and mountd can give -appropriate export information to the kernel. This removes the -dependency on ``rmtab`` and means that the kernel only needs to know about -currently active clients. - -To enable this new functionality, you need to:: - - mount -t nfsd nfsd /proc/fs/nfsd - -before running exportfs or mountd. It is recommended that all NFS -services be protected from the internet-at-large by a firewall where -that is possible. - -mcelog ------- - -On x86 kernels the mcelog utility is needed to process and log machine check -events when ``CONFIG_X86_MCE`` is enabled. Machine check events are errors -reported by the CPU. Processing them is strongly encouraged. - -Kernel documentation -******************** - -Sphinx ------- - -The ReST markups currently used by the Documentation/ files are meant to be -built with ``Sphinx`` version 1.2 or upper. If you're desiring to build -PDF outputs, it is recommended to use version 1.4.6. - -.. note:: - - Please notice that, for PDF and LaTeX output, you'll also need ``XeLaTeX`` - version 3.14159265. Depending on the distribution, you may also need - to install a series of ``texlive`` packages that provide the minimal - set of functionalities required for ``XeLaTex`` to work. - -Other tools ------------ - -In order to produce documentation from DocBook, you'll also need ``xmlto``. -Please notice, however, that we're currently migrating all documents to use -``Sphinx``. - -Getting updated software -======================== - -Kernel compilation -****************** - -gcc ---- - -- - -Make ----- - -- - -Binutils --------- - -- - -OpenSSL -------- - -- - -System utilities -**************** - -Util-linux ----------- - -- - -Ksymoops --------- - -- - -Module-Init-Tools ------------------ - -- - -Mkinitrd --------- - -- - -E2fsprogs ---------- - -- - -JFSutils --------- - -- - -Reiserfsprogs -------------- - -- - -Xfsprogs --------- - -- - -Pcmciautils ------------ - -- - -Quota-tools ------------ - -- - -DocBook Stylesheets -------------------- - -- - -XMLTO XSLT Frontend -------------------- - -- - -Intel P6 microcode ------------------- - -- - -udev ----- - -- - -FUSE ----- - -- - -mcelog ------- - -- - -Networking -********** - -PPP ---- - -- - -Isdn4k-utils ------------- - -- - -NFS-utils ---------- - -- - -Iptables --------- - -- - -Ip-route2 ---------- - -- - -OProfile --------- - -- - -NFS-Utils ---------- - -- - -Kernel documentation -******************** - -Sphinx ------- - -- diff --git a/Documentation/CodeOfConflict b/Documentation/CodeOfConflict deleted file mode 100644 index 47b6de763203..000000000000 --- a/Documentation/CodeOfConflict +++ /dev/null @@ -1,28 +0,0 @@ -Code of Conflict ----------------- - -The Linux kernel development effort is a very personal process compared -to "traditional" ways of developing software. Your code and ideas -behind it will be carefully reviewed, often resulting in critique and -criticism. The review will almost always require improvements to the -code before it can be included in the kernel. Know that this happens -because everyone involved wants to see the best possible solution for -the overall success of Linux. This development process has been proven -to create the most robust operating system kernel ever, and we do not -want to do anything to cause the quality of submission and eventual -result to ever decrease. - -If however, anyone feels personally abused, threatened, or otherwise -uncomfortable due to this process, that is not acceptable. If so, -please contact the Linux Foundation's Technical Advisory Board at -, or the individual members, and they -will work to resolve the issue to the best of their ability. For more -information on who is on the Technical Advisory Board and what their -role is, please see: - - - http://www.linuxfoundation.org/projects/linux/tab - -As a reviewer of code, please strive to keep things civil and focused on -the technical issues involved. We are all humans, and frustrations can -be high on both sides of the process. Try to keep in mind the immortal -words of Bill and Ted, "Be excellent to each other." diff --git a/Documentation/CodingStyle b/Documentation/CodingStyle deleted file mode 100644 index 9c61c039ccd9..000000000000 --- a/Documentation/CodingStyle +++ /dev/null @@ -1,1062 +0,0 @@ -.. _codingstyle: - -Linux kernel coding style -========================= - -This is a short document describing the preferred coding style for the -linux kernel. Coding style is very personal, and I won't **force** my -views on anybody, but this is what goes for anything that I have to be -able to maintain, and I'd prefer it for most other things too. Please -at least consider the points made here. - -First off, I'd suggest printing out a copy of the GNU coding standards, -and NOT read it. Burn them, it's a great symbolic gesture. - -Anyway, here goes: - - -1) Indentation --------------- - -Tabs are 8 characters, and thus indentations are also 8 characters. -There are heretic movements that try to make indentations 4 (or even 2!) -characters deep, and that is akin to trying to define the value of PI to -be 3. - -Rationale: The whole idea behind indentation is to clearly define where -a block of control starts and ends. Especially when you've been looking -at your screen for 20 straight hours, you'll find it a lot easier to see -how the indentation works if you have large indentations. - -Now, some people will claim that having 8-character indentations makes -the code move too far to the right, and makes it hard to read on a -80-character terminal screen. The answer to that is that if you need -more than 3 levels of indentation, you're screwed anyway, and should fix -your program. - -In short, 8-char indents make things easier to read, and have the added -benefit of warning you when you're nesting your functions too deep. -Heed that warning. - -The preferred way to ease multiple indentation levels in a switch statement is -to align the ``switch`` and its subordinate ``case`` labels in the same column -instead of ``double-indenting`` the ``case`` labels. E.g.: - -.. code-block:: c - - switch (suffix) { - case 'G': - case 'g': - mem <<= 30; - break; - case 'M': - case 'm': - mem <<= 20; - break; - case 'K': - case 'k': - mem <<= 10; - /* fall through */ - default: - break; - } - -Don't put multiple statements on a single line unless you have -something to hide: - -.. code-block:: c - - if (condition) do_this; - do_something_everytime; - -Don't put multiple assignments on a single line either. Kernel coding style -is super simple. Avoid tricky expressions. - -Outside of comments, documentation and except in Kconfig, spaces are never -used for indentation, and the above example is deliberately broken. - -Get a decent editor and don't leave whitespace at the end of lines. - - -2) Breaking long lines and strings ----------------------------------- - -Coding style is all about readability and maintainability using commonly -available tools. - -The limit on the length of lines is 80 columns and this is a strongly -preferred limit. - -Statements longer than 80 columns will be broken into sensible chunks, unless -exceeding 80 columns significantly increases readability and does not hide -information. Descendants are always substantially shorter than the parent and -are placed substantially to the right. The same applies to function headers -with a long argument list. However, never break user-visible strings such as -printk messages, because that breaks the ability to grep for them. - - -3) Placing Braces and Spaces ----------------------------- - -The other issue that always comes up in C styling is the placement of -braces. Unlike the indent size, there are few technical reasons to -choose one placement strategy over the other, but the preferred way, as -shown to us by the prophets Kernighan and Ritchie, is to put the opening -brace last on the line, and put the closing brace first, thusly: - -.. code-block:: c - - if (x is true) { - we do y - } - -This applies to all non-function statement blocks (if, switch, for, -while, do). E.g.: - -.. code-block:: c - - switch (action) { - case KOBJ_ADD: - return "add"; - case KOBJ_REMOVE: - return "remove"; - case KOBJ_CHANGE: - return "change"; - default: - return NULL; - } - -However, there is one special case, namely functions: they have the -opening brace at the beginning of the next line, thus: - -.. code-block:: c - - int function(int x) - { - body of function - } - -Heretic people all over the world have claimed that this inconsistency -is ... well ... inconsistent, but all right-thinking people know that -(a) K&R are **right** and (b) K&R are right. Besides, functions are -special anyway (you can't nest them in C). - -Note that the closing brace is empty on a line of its own, **except** in -the cases where it is followed by a continuation of the same statement, -ie a ``while`` in a do-statement or an ``else`` in an if-statement, like -this: - -.. code-block:: c - - do { - body of do-loop - } while (condition); - -and - -.. code-block:: c - - if (x == y) { - .. - } else if (x > y) { - ... - } else { - .... - } - -Rationale: K&R. - -Also, note that this brace-placement also minimizes the number of empty -(or almost empty) lines, without any loss of readability. Thus, as the -supply of new-lines on your screen is not a renewable resource (think -25-line terminal screens here), you have more empty lines to put -comments on. - -Do not unnecessarily use braces where a single statement will do. - -.. code-block:: c - - if (condition) - action(); - -and - -.. code-block:: none - - if (condition) - do_this(); - else - do_that(); - -This does not apply if only one branch of a conditional statement is a single -statement; in the latter case use braces in both branches: - -.. code-block:: c - - if (condition) { - do_this(); - do_that(); - } else { - otherwise(); - } - -3.1) Spaces -*********** - -Linux kernel style for use of spaces depends (mostly) on -function-versus-keyword usage. Use a space after (most) keywords. The -notable exceptions are sizeof, typeof, alignof, and __attribute__, which look -somewhat like functions (and are usually used with parentheses in Linux, -although they are not required in the language, as in: ``sizeof info`` after -``struct fileinfo info;`` is declared). - -So use a space after these keywords:: - - if, switch, case, for, do, while - -but not with sizeof, typeof, alignof, or __attribute__. E.g., - -.. code-block:: c - - - s = sizeof(struct file); - -Do not add spaces around (inside) parenthesized expressions. This example is -**bad**: - -.. code-block:: c - - - s = sizeof( struct file ); - -When declaring pointer data or a function that returns a pointer type, the -preferred use of ``*`` is adjacent to the data name or function name and not -adjacent to the type name. Examples: - -.. code-block:: c - - - char *linux_banner; - unsigned long long memparse(char *ptr, char **retptr); - char *match_strdup(substring_t *s); - -Use one space around (on each side of) most binary and ternary operators, -such as any of these:: - - = + - < > * / % | & ^ <= >= == != ? : - -but no space after unary operators:: - - & * + - ~ ! sizeof typeof alignof __attribute__ defined - -no space before the postfix increment & decrement unary operators:: - - ++ -- - -no space after the prefix increment & decrement unary operators:: - - ++ -- - -and no space around the ``.`` and ``->`` structure member operators. - -Do not leave trailing whitespace at the ends of lines. Some editors with -``smart`` indentation will insert whitespace at the beginning of new lines as -appropriate, so you can start typing the next line of code right away. -However, some such editors do not remove the whitespace if you end up not -putting a line of code there, such as if you leave a blank line. As a result, -you end up with lines containing trailing whitespace. - -Git will warn you about patches that introduce trailing whitespace, and can -optionally strip the trailing whitespace for you; however, if applying a series -of patches, this may make later patches in the series fail by changing their -context lines. - - -4) Naming ---------- - -C is a Spartan language, and so should your naming be. Unlike Modula-2 -and Pascal programmers, C programmers do not use cute names like -ThisVariableIsATemporaryCounter. A C programmer would call that -variable ``tmp``, which is much easier to write, and not the least more -difficult to understand. - -HOWEVER, while mixed-case names are frowned upon, descriptive names for -global variables are a must. To call a global function ``foo`` is a -shooting offense. - -GLOBAL variables (to be used only if you **really** need them) need to -have descriptive names, as do global functions. If you have a function -that counts the number of active users, you should call that -``count_active_users()`` or similar, you should **not** call it ``cntusr()``. - -Encoding the type of a function into the name (so-called Hungarian -notation) is brain damaged - the compiler knows the types anyway and can -check those, and it only confuses the programmer. No wonder MicroSoft -makes buggy programs. - -LOCAL variable names should be short, and to the point. If you have -some random integer loop counter, it should probably be called ``i``. -Calling it ``loop_counter`` is non-productive, if there is no chance of it -being mis-understood. Similarly, ``tmp`` can be just about any type of -variable that is used to hold a temporary value. - -If you are afraid to mix up your local variable names, you have another -problem, which is called the function-growth-hormone-imbalance syndrome. -See chapter 6 (Functions). - - -5) Typedefs ------------ - -Please don't use things like ``vps_t``. -It's a **mistake** to use typedef for structures and pointers. When you see a - -.. code-block:: c - - - vps_t a; - -in the source, what does it mean? -In contrast, if it says - -.. code-block:: c - - struct virtual_container *a; - -you can actually tell what ``a`` is. - -Lots of people think that typedefs ``help readability``. Not so. They are -useful only for: - - (a) totally opaque objects (where the typedef is actively used to **hide** - what the object is). - - Example: ``pte_t`` etc. opaque objects that you can only access using - the proper accessor functions. - - .. note:: - - Opaqueness and ``accessor functions`` are not good in themselves. - The reason we have them for things like pte_t etc. is that there - really is absolutely **zero** portably accessible information there. - - (b) Clear integer types, where the abstraction **helps** avoid confusion - whether it is ``int`` or ``long``. - - u8/u16/u32 are perfectly fine typedefs, although they fit into - category (d) better than here. - - .. note:: - - Again - there needs to be a **reason** for this. If something is - ``unsigned long``, then there's no reason to do - - typedef unsigned long myflags_t; - - but if there is a clear reason for why it under certain circumstances - might be an ``unsigned int`` and under other configurations might be - ``unsigned long``, then by all means go ahead and use a typedef. - - (c) when you use sparse to literally create a **new** type for - type-checking. - - (d) New types which are identical to standard C99 types, in certain - exceptional circumstances. - - Although it would only take a short amount of time for the eyes and - brain to become accustomed to the standard types like ``uint32_t``, - some people object to their use anyway. - - Therefore, the Linux-specific ``u8/u16/u32/u64`` types and their - signed equivalents which are identical to standard types are - permitted -- although they are not mandatory in new code of your - own. - - When editing existing code which already uses one or the other set - of types, you should conform to the existing choices in that code. - - (e) Types safe for use in userspace. - - In certain structures which are visible to userspace, we cannot - require C99 types and cannot use the ``u32`` form above. Thus, we - use __u32 and similar types in all structures which are shared - with userspace. - -Maybe there are other cases too, but the rule should basically be to NEVER -EVER use a typedef unless you can clearly match one of those rules. - -In general, a pointer, or a struct that has elements that can reasonably -be directly accessed should **never** be a typedef. - - -6) Functions ------------- - -Functions should be short and sweet, and do just one thing. They should -fit on one or two screenfuls of text (the ISO/ANSI screen size is 80x24, -as we all know), and do one thing and do that well. - -The maximum length of a function is inversely proportional to the -complexity and indentation level of that function. So, if you have a -conceptually simple function that is just one long (but simple) -case-statement, where you have to do lots of small things for a lot of -different cases, it's OK to have a longer function. - -However, if you have a complex function, and you suspect that a -less-than-gifted first-year high-school student might not even -understand what the function is all about, you should adhere to the -maximum limits all the more closely. Use helper functions with -descriptive names (you can ask the compiler to in-line them if you think -it's performance-critical, and it will probably do a better job of it -than you would have done). - -Another measure of the function is the number of local variables. They -shouldn't exceed 5-10, or you're doing something wrong. Re-think the -function, and split it into smaller pieces. A human brain can -generally easily keep track of about 7 different things, anything more -and it gets confused. You know you're brilliant, but maybe you'd like -to understand what you did 2 weeks from now. - -In source files, separate functions with one blank line. If the function is -exported, the **EXPORT** macro for it should follow immediately after the -closing function brace line. E.g.: - -.. code-block:: c - - int system_is_up(void) - { - return system_state == SYSTEM_RUNNING; - } - EXPORT_SYMBOL(system_is_up); - -In function prototypes, include parameter names with their data types. -Although this is not required by the C language, it is preferred in Linux -because it is a simple way to add valuable information for the reader. - - -7) Centralized exiting of functions ------------------------------------ - -Albeit deprecated by some people, the equivalent of the goto statement is -used frequently by compilers in form of the unconditional jump instruction. - -The goto statement comes in handy when a function exits from multiple -locations and some common work such as cleanup has to be done. If there is no -cleanup needed then just return directly. - -Choose label names which say what the goto does or why the goto exists. An -example of a good name could be ``out_free_buffer:`` if the goto frees ``buffer``. -Avoid using GW-BASIC names like ``err1:`` and ``err2:``, as you would have to -renumber them if you ever add or remove exit paths, and they make correctness -difficult to verify anyway. - -The rationale for using gotos is: - -- unconditional statements are easier to understand and follow -- nesting is reduced -- errors by not updating individual exit points when making - modifications are prevented -- saves the compiler work to optimize redundant code away ;) - -.. code-block:: c - - int fun(int a) - { - int result = 0; - char *buffer; - - buffer = kmalloc(SIZE, GFP_KERNEL); - if (!buffer) - return -ENOMEM; - - if (condition1) { - while (loop1) { - ... - } - result = 1; - goto out_buffer; - } - ... - out_free_buffer: - kfree(buffer); - return result; - } - -A common type of bug to be aware of is ``one err bugs`` which look like this: - -.. code-block:: c - - err: - kfree(foo->bar); - kfree(foo); - return ret; - -The bug in this code is that on some exit paths ``foo`` is NULL. Normally the -fix for this is to split it up into two error labels ``err_free_bar:`` and -``err_free_foo:``: - -.. code-block:: c - - err_free_bar: - kfree(foo->bar); - err_free_foo: - kfree(foo); - return ret; - -Ideally you should simulate errors to test all exit paths. - - -8) Commenting -------------- - -Comments are good, but there is also a danger of over-commenting. NEVER -try to explain HOW your code works in a comment: it's much better to -write the code so that the **working** is obvious, and it's a waste of -time to explain badly written code. - -Generally, you want your comments to tell WHAT your code does, not HOW. -Also, try to avoid putting comments inside a function body: if the -function is so complex that you need to separately comment parts of it, -you should probably go back to chapter 6 for a while. You can make -small comments to note or warn about something particularly clever (or -ugly), but try to avoid excess. Instead, put the comments at the head -of the function, telling people what it does, and possibly WHY it does -it. - -When commenting the kernel API functions, please use the kernel-doc format. -See the files Documentation/kernel-documentation.rst and scripts/kernel-doc -for details. - -The preferred style for long (multi-line) comments is: - -.. code-block:: c - - /* - * This is the preferred style for multi-line - * comments in the Linux kernel source code. - * Please use it consistently. - * - * Description: A column of asterisks on the left side, - * with beginning and ending almost-blank lines. - */ - -For files in net/ and drivers/net/ the preferred style for long (multi-line) -comments is a little different. - -.. code-block:: c - - /* The preferred comment style for files in net/ and drivers/net - * looks like this. - * - * It is nearly the same as the generally preferred comment style, - * but there is no initial almost-blank line. - */ - -It's also important to comment data, whether they are basic types or derived -types. To this end, use just one data declaration per line (no commas for -multiple data declarations). This leaves you room for a small comment on each -item, explaining its use. - - -9) You've made a mess of it ---------------------------- - -That's OK, we all do. You've probably been told by your long-time Unix -user helper that ``GNU emacs`` automatically formats the C sources for -you, and you've noticed that yes, it does do that, but the defaults it -uses are less than desirable (in fact, they are worse than random -typing - an infinite number of monkeys typing into GNU emacs would never -make a good program). - -So, you can either get rid of GNU emacs, or change it to use saner -values. To do the latter, you can stick the following in your .emacs file: - -.. code-block:: none - - (defun c-lineup-arglist-tabs-only (ignored) - "Line up argument lists by tabs, not spaces" - (let* ((anchor (c-langelem-pos c-syntactic-element)) - (column (c-langelem-2nd-pos c-syntactic-element)) - (offset (- (1+ column) anchor)) - (steps (floor offset c-basic-offset))) - (* (max steps 1) - c-basic-offset))) - - (add-hook 'c-mode-common-hook - (lambda () - ;; Add kernel style - (c-add-style - "linux-tabs-only" - '("linux" (c-offsets-alist - (arglist-cont-nonempty - c-lineup-gcc-asm-reg - c-lineup-arglist-tabs-only)))))) - - (add-hook 'c-mode-hook - (lambda () - (let ((filename (buffer-file-name))) - ;; Enable kernel mode for the appropriate files - (when (and filename - (string-match (expand-file-name "~/src/linux-trees") - filename)) - (setq indent-tabs-mode t) - (setq show-trailing-whitespace t) - (c-set-style "linux-tabs-only"))))) - -This will make emacs go better with the kernel coding style for C -files below ``~/src/linux-trees``. - -But even if you fail in getting emacs to do sane formatting, not -everything is lost: use ``indent``. - -Now, again, GNU indent has the same brain-dead settings that GNU emacs -has, which is why you need to give it a few command line options. -However, that's not too bad, because even the makers of GNU indent -recognize the authority of K&R (the GNU people aren't evil, they are -just severely misguided in this matter), so you just give indent the -options ``-kr -i8`` (stands for ``K&R, 8 character indents``), or use -``scripts/Lindent``, which indents in the latest style. - -``indent`` has a lot of options, and especially when it comes to comment -re-formatting you may want to take a look at the man page. But -remember: ``indent`` is not a fix for bad programming. - - -10) Kconfig configuration files -------------------------------- - -For all of the Kconfig* configuration files throughout the source tree, -the indentation is somewhat different. Lines under a ``config`` definition -are indented with one tab, while help text is indented an additional two -spaces. Example:: - - config AUDIT - bool "Auditing support" - depends on NET - help - Enable auditing infrastructure that can be used with another - kernel subsystem, such as SELinux (which requires this for - logging of avc messages output). Does not do system-call - auditing without CONFIG_AUDITSYSCALL. - -Seriously dangerous features (such as write support for certain -filesystems) should advertise this prominently in their prompt string:: - - config ADFS_FS_RW - bool "ADFS write support (DANGEROUS)" - depends on ADFS_FS - ... - -For full documentation on the configuration files, see the file -Documentation/kbuild/kconfig-language.txt. - - -11) Data structures -------------------- - -Data structures that have visibility outside the single-threaded -environment they are created and destroyed in should always have -reference counts. In the kernel, garbage collection doesn't exist (and -outside the kernel garbage collection is slow and inefficient), which -means that you absolutely **have** to reference count all your uses. - -Reference counting means that you can avoid locking, and allows multiple -users to have access to the data structure in parallel - and not having -to worry about the structure suddenly going away from under them just -because they slept or did something else for a while. - -Note that locking is **not** a replacement for reference counting. -Locking is used to keep data structures coherent, while reference -counting is a memory management technique. Usually both are needed, and -they are not to be confused with each other. - -Many data structures can indeed have two levels of reference counting, -when there are users of different ``classes``. The subclass count counts -the number of subclass users, and decrements the global count just once -when the subclass count goes to zero. - -Examples of this kind of ``multi-level-reference-counting`` can be found in -memory management (``struct mm_struct``: mm_users and mm_count), and in -filesystem code (``struct super_block``: s_count and s_active). - -Remember: if another thread can find your data structure, and you don't -have a reference count on it, you almost certainly have a bug. - - -12) Macros, Enums and RTL -------------------------- - -Names of macros defining constants and labels in enums are capitalized. - -.. code-block:: c - - #define CONSTANT 0x12345 - -Enums are preferred when defining several related constants. - -CAPITALIZED macro names are appreciated but macros resembling functions -may be named in lower case. - -Generally, inline functions are preferable to macros resembling functions. - -Macros with multiple statements should be enclosed in a do - while block: - -.. code-block:: c - - #define macrofun(a, b, c) \ - do { \ - if (a == 5) \ - do_this(b, c); \ - } while (0) - -Things to avoid when using macros: - -1) macros that affect control flow: - -.. code-block:: c - - #define FOO(x) \ - do { \ - if (blah(x) < 0) \ - return -EBUGGERED; \ - } while (0) - -is a **very** bad idea. It looks like a function call but exits the ``calling`` -function; don't break the internal parsers of those who will read the code. - -2) macros that depend on having a local variable with a magic name: - -.. code-block:: c - - #define FOO(val) bar(index, val) - -might look like a good thing, but it's confusing as hell when one reads the -code and it's prone to breakage from seemingly innocent changes. - -3) macros with arguments that are used as l-values: FOO(x) = y; will -bite you if somebody e.g. turns FOO into an inline function. - -4) forgetting about precedence: macros defining constants using expressions -must enclose the expression in parentheses. Beware of similar issues with -macros using parameters. - -.. code-block:: c - - #define CONSTANT 0x4000 - #define CONSTEXP (CONSTANT | 3) - -5) namespace collisions when defining local variables in macros resembling -functions: - -.. code-block:: c - - #define FOO(x) \ - ({ \ - typeof(x) ret; \ - ret = calc_ret(x); \ - (ret); \ - }) - -ret is a common name for a local variable - __foo_ret is less likely -to collide with an existing variable. - -The cpp manual deals with macros exhaustively. The gcc internals manual also -covers RTL which is used frequently with assembly language in the kernel. - - -13) Printing kernel messages ----------------------------- - -Kernel developers like to be seen as literate. Do mind the spelling -of kernel messages to make a good impression. Do not use crippled -words like ``dont``; use ``do not`` or ``don't`` instead. Make the messages -concise, clear, and unambiguous. - -Kernel messages do not have to be terminated with a period. - -Printing numbers in parentheses (%d) adds no value and should be avoided. - -There are a number of driver model diagnostic macros in -which you should use to make sure messages are matched to the right device -and driver, and are tagged with the right level: dev_err(), dev_warn(), -dev_info(), and so forth. For messages that aren't associated with a -particular device, defines pr_notice(), pr_info(), -pr_warn(), pr_err(), etc. - -Coming up with good debugging messages can be quite a challenge; and once -you have them, they can be a huge help for remote troubleshooting. However -debug message printing is handled differently than printing other non-debug -messages. While the other pr_XXX() functions print unconditionally, -pr_debug() does not; it is compiled out by default, unless either DEBUG is -defined or CONFIG_DYNAMIC_DEBUG is set. That is true for dev_dbg() also, -and a related convention uses VERBOSE_DEBUG to add dev_vdbg() messages to -the ones already enabled by DEBUG. - -Many subsystems have Kconfig debug options to turn on -DDEBUG in the -corresponding Makefile; in other cases specific files #define DEBUG. And -when a debug message should be unconditionally printed, such as if it is -already inside a debug-related #ifdef section, printk(KERN_DEBUG ...) can be -used. - - -14) Allocating memory ---------------------- - -The kernel provides the following general purpose memory allocators: -kmalloc(), kzalloc(), kmalloc_array(), kcalloc(), vmalloc(), and -vzalloc(). Please refer to the API documentation for further information -about them. - -The preferred form for passing a size of a struct is the following: - -.. code-block:: c - - p = kmalloc(sizeof(*p), ...); - -The alternative form where struct name is spelled out hurts readability and -introduces an opportunity for a bug when the pointer variable type is changed -but the corresponding sizeof that is passed to a memory allocator is not. - -Casting the return value which is a void pointer is redundant. The conversion -from void pointer to any other pointer type is guaranteed by the C programming -language. - -The preferred form for allocating an array is the following: - -.. code-block:: c - - p = kmalloc_array(n, sizeof(...), ...); - -The preferred form for allocating a zeroed array is the following: - -.. code-block:: c - - p = kcalloc(n, sizeof(...), ...); - -Both forms check for overflow on the allocation size n * sizeof(...), -and return NULL if that occurred. - - -15) The inline disease ----------------------- - -There appears to be a common misperception that gcc has a magic "make me -faster" speedup option called ``inline``. While the use of inlines can be -appropriate (for example as a means of replacing macros, see Chapter 12), it -very often is not. Abundant use of the inline keyword leads to a much bigger -kernel, which in turn slows the system as a whole down, due to a bigger -icache footprint for the CPU and simply because there is less memory -available for the pagecache. Just think about it; a pagecache miss causes a -disk seek, which easily takes 5 milliseconds. There are a LOT of cpu cycles -that can go into these 5 milliseconds. - -A reasonable rule of thumb is to not put inline at functions that have more -than 3 lines of code in them. An exception to this rule are the cases where -a parameter is known to be a compiletime constant, and as a result of this -constantness you *know* the compiler will be able to optimize most of your -function away at compile time. For a good example of this later case, see -the kmalloc() inline function. - -Often people argue that adding inline to functions that are static and used -only once is always a win since there is no space tradeoff. While this is -technically correct, gcc is capable of inlining these automatically without -help, and the maintenance issue of removing the inline when a second user -appears outweighs the potential value of the hint that tells gcc to do -something it would have done anyway. - - -16) Function return values and names ------------------------------------- - -Functions can return values of many different kinds, and one of the -most common is a value indicating whether the function succeeded or -failed. Such a value can be represented as an error-code integer -(-Exxx = failure, 0 = success) or a ``succeeded`` boolean (0 = failure, -non-zero = success). - -Mixing up these two sorts of representations is a fertile source of -difficult-to-find bugs. If the C language included a strong distinction -between integers and booleans then the compiler would find these mistakes -for us... but it doesn't. To help prevent such bugs, always follow this -convention:: - - If the name of a function is an action or an imperative command, - the function should return an error-code integer. If the name - is a predicate, the function should return a "succeeded" boolean. - -For example, ``add work`` is a command, and the add_work() function returns 0 -for success or -EBUSY for failure. In the same way, ``PCI device present`` is -a predicate, and the pci_dev_present() function returns 1 if it succeeds in -finding a matching device or 0 if it doesn't. - -All EXPORTed functions must respect this convention, and so should all -public functions. Private (static) functions need not, but it is -recommended that they do. - -Functions whose return value is the actual result of a computation, rather -than an indication of whether the computation succeeded, are not subject to -this rule. Generally they indicate failure by returning some out-of-range -result. Typical examples would be functions that return pointers; they use -NULL or the ERR_PTR mechanism to report failure. - - -17) Don't re-invent the kernel macros -------------------------------------- - -The header file include/linux/kernel.h contains a number of macros that -you should use, rather than explicitly coding some variant of them yourself. -For example, if you need to calculate the length of an array, take advantage -of the macro - -.. code-block:: c - - #define ARRAY_SIZE(x) (sizeof(x) / sizeof((x)[0])) - -Similarly, if you need to calculate the size of some structure member, use - -.. code-block:: c - - #define FIELD_SIZEOF(t, f) (sizeof(((t*)0)->f)) - -There are also min() and max() macros that do strict type checking if you -need them. Feel free to peruse that header file to see what else is already -defined that you shouldn't reproduce in your code. - - -18) Editor modelines and other cruft ------------------------------------- - -Some editors can interpret configuration information embedded in source files, -indicated with special markers. For example, emacs interprets lines marked -like this: - -.. code-block:: c - - -*- mode: c -*- - -Or like this: - -.. code-block:: c - - /* - Local Variables: - compile-command: "gcc -DMAGIC_DEBUG_FLAG foo.c" - End: - */ - -Vim interprets markers that look like this: - -.. code-block:: c - - /* vim:set sw=8 noet */ - -Do not include any of these in source files. People have their own personal -editor configurations, and your source files should not override them. This -includes markers for indentation and mode configuration. People may use their -own custom mode, or may have some other magic method for making indentation -work correctly. - - -19) Inline assembly -------------------- - -In architecture-specific code, you may need to use inline assembly to interface -with CPU or platform functionality. Don't hesitate to do so when necessary. -However, don't use inline assembly gratuitously when C can do the job. You can -and should poke hardware from C when possible. - -Consider writing simple helper functions that wrap common bits of inline -assembly, rather than repeatedly writing them with slight variations. Remember -that inline assembly can use C parameters. - -Large, non-trivial assembly functions should go in .S files, with corresponding -C prototypes defined in C header files. The C prototypes for assembly -functions should use ``asmlinkage``. - -You may need to mark your asm statement as volatile, to prevent GCC from -removing it if GCC doesn't notice any side effects. You don't always need to -do so, though, and doing so unnecessarily can limit optimization. - -When writing a single inline assembly statement containing multiple -instructions, put each instruction on a separate line in a separate quoted -string, and end each string except the last with \n\t to properly indent the -next instruction in the assembly output: - -.. code-block:: c - - asm ("magic %reg1, #42\n\t" - "more_magic %reg2, %reg3" - : /* outputs */ : /* inputs */ : /* clobbers */); - - -20) Conditional Compilation ---------------------------- - -Wherever possible, don't use preprocessor conditionals (#if, #ifdef) in .c -files; doing so makes code harder to read and logic harder to follow. Instead, -use such conditionals in a header file defining functions for use in those .c -files, providing no-op stub versions in the #else case, and then call those -functions unconditionally from .c files. The compiler will avoid generating -any code for the stub calls, producing identical results, but the logic will -remain easy to follow. - -Prefer to compile out entire functions, rather than portions of functions or -portions of expressions. Rather than putting an ifdef in an expression, factor -out part or all of the expression into a separate helper function and apply the -conditional to that function. - -If you have a function or variable which may potentially go unused in a -particular configuration, and the compiler would warn about its definition -going unused, mark the definition as __maybe_unused rather than wrapping it in -a preprocessor conditional. (However, if a function or variable *always* goes -unused, delete it.) - -Within code, where possible, use the IS_ENABLED macro to convert a Kconfig -symbol into a C boolean expression, and use it in a normal C conditional: - -.. code-block:: c - - if (IS_ENABLED(CONFIG_SOMETHING)) { - ... - } - -The compiler will constant-fold the conditional away, and include or exclude -the block of code just as with an #ifdef, so this will not add any runtime -overhead. However, this approach still allows the C compiler to see the code -inside the block, and check it for correctness (syntax, types, symbol -references, etc). Thus, you still have to use an #ifdef if the code inside the -block references symbols that will not exist if the condition is not met. - -At the end of any non-trivial #if or #ifdef block (more than a few lines), -place a comment after the #endif on the same line, noting the conditional -expression used. For instance: - -.. code-block:: c - - #ifdef CONFIG_SOMETHING - ... - #endif /* CONFIG_SOMETHING */ - - -Appendix I) References ----------------------- - -The C Programming Language, Second Edition -by Brian W. Kernighan and Dennis M. Ritchie. -Prentice Hall, Inc., 1988. -ISBN 0-13-110362-8 (paperback), 0-13-110370-9 (hardback). - -The Practice of Programming -by Brian W. Kernighan and Rob Pike. -Addison-Wesley, Inc., 1999. -ISBN 0-201-61586-X. - -GNU manuals - where in compliance with K&R and this text - for cpp, gcc, -gcc internals and indent, all available from http://www.gnu.org/manual/ - -WG14 is the international standardization working group for the programming -language C, URL: http://www.open-std.org/JTC1/SC22/WG14/ - -Kernel CodingStyle, by greg@kroah.com at OLS 2002: -http://www.kroah.com/linux/talks/ols_2002_kernel_codingstyle_talk/html/ diff --git a/Documentation/HOWTO b/Documentation/HOWTO deleted file mode 100644 index 5f042349f987..000000000000 --- a/Documentation/HOWTO +++ /dev/null @@ -1,652 +0,0 @@ -HOWTO do Linux kernel development -================================= - -This is the be-all, end-all document on this topic. It contains -instructions on how to become a Linux kernel developer and how to learn -to work with the Linux kernel development community. It tries to not -contain anything related to the technical aspects of kernel programming, -but will help point you in the right direction for that. - -If anything in this document becomes out of date, please send in patches -to the maintainer of this file, who is listed at the bottom of the -document. - - -Introduction ------------- - -So, you want to learn how to become a Linux kernel developer? Or you -have been told by your manager, "Go write a Linux driver for this -device." This document's goal is to teach you everything you need to -know to achieve this by describing the process you need to go through, -and hints on how to work with the community. It will also try to -explain some of the reasons why the community works like it does. - -The kernel is written mostly in C, with some architecture-dependent -parts written in assembly. A good understanding of C is required for -kernel development. Assembly (any architecture) is not required unless -you plan to do low-level development for that architecture. Though they -are not a good substitute for a solid C education and/or years of -experience, the following books are good for, if anything, reference: - - - "The C Programming Language" by Kernighan and Ritchie [Prentice Hall] - - "Practical C Programming" by Steve Oualline [O'Reilly] - - "C: A Reference Manual" by Harbison and Steele [Prentice Hall] - -The kernel is written using GNU C and the GNU toolchain. While it -adheres to the ISO C89 standard, it uses a number of extensions that are -not featured in the standard. The kernel is a freestanding C -environment, with no reliance on the standard C library, so some -portions of the C standard are not supported. Arbitrary long long -divisions and floating point are not allowed. It can sometimes be -difficult to understand the assumptions the kernel has on the toolchain -and the extensions that it uses, and unfortunately there is no -definitive reference for them. Please check the gcc info pages (`info -gcc`) for some information on them. - -Please remember that you are trying to learn how to work with the -existing development community. It is a diverse group of people, with -high standards for coding, style and procedure. These standards have -been created over time based on what they have found to work best for -such a large and geographically dispersed team. Try to learn as much as -possible about these standards ahead of time, as they are well -documented; do not expect people to adapt to you or your company's way -of doing things. - - -Legal Issues ------------- - -The Linux kernel source code is released under the GPL. Please see the -file, COPYING, in the main directory of the source tree, for details on -the license. If you have further questions about the license, please -contact a lawyer, and do not ask on the Linux kernel mailing list. The -people on the mailing lists are not lawyers, and you should not rely on -their statements on legal matters. - -For common questions and answers about the GPL, please see: - - https://www.gnu.org/licenses/gpl-faq.html - - -Documentation -------------- - -The Linux kernel source tree has a large range of documents that are -invaluable for learning how to interact with the kernel community. When -new features are added to the kernel, it is recommended that new -documentation files are also added which explain how to use the feature. -When a kernel change causes the interface that the kernel exposes to -userspace to change, it is recommended that you send the information or -a patch to the manual pages explaining the change to the manual pages -maintainer at mtk.manpages@gmail.com, and CC the list -linux-api@vger.kernel.org. - -Here is a list of files that are in the kernel source tree that are -required reading: - - README - This file gives a short background on the Linux kernel and describes - what is necessary to do to configure and build the kernel. People - who are new to the kernel should start here. - - :ref:`Documentation/Changes ` - This file gives a list of the minimum levels of various software - packages that are necessary to build and run the kernel - successfully. - - :ref:`Documentation/CodingStyle ` - This describes the Linux kernel coding style, and some of the - rationale behind it. All new code is expected to follow the - guidelines in this document. Most maintainers will only accept - patches if these rules are followed, and many people will only - review code if it is in the proper style. - - :ref:`Documentation/SubmittingPatches ` and :ref:`Documentation/SubmittingDrivers ` - These files describe in explicit detail how to successfully create - and send a patch, including (but not limited to): - - - Email contents - - Email format - - Who to send it to - - Following these rules will not guarantee success (as all patches are - subject to scrutiny for content and style), but not following them - will almost always prevent it. - - Other excellent descriptions of how to create patches properly are: - - "The Perfect Patch" - https://www.ozlabs.org/~akpm/stuff/tpp.txt - - "Linux kernel patch submission format" - http://linux.yyz.us/patch-format.html - - :ref:`Documentation/stable_api_nonsense.txt ` - This file describes the rationale behind the conscious decision to - not have a stable API within the kernel, including things like: - - - Subsystem shim-layers (for compatibility?) - - Driver portability between Operating Systems. - - Mitigating rapid change within the kernel source tree (or - preventing rapid change) - - This document is crucial for understanding the Linux development - philosophy and is very important for people moving to Linux from - development on other Operating Systems. - - :ref:`Documentation/SecurityBugs ` - If you feel you have found a security problem in the Linux kernel, - please follow the steps in this document to help notify the kernel - developers, and help solve the issue. - - :ref:`Documentation/ManagementStyle ` - This document describes how Linux kernel maintainers operate and the - shared ethos behind their methodologies. This is important reading - for anyone new to kernel development (or anyone simply curious about - it), as it resolves a lot of common misconceptions and confusion - about the unique behavior of kernel maintainers. - - :ref:`Documentation/stable_kernel_rules.txt ` - This file describes the rules on how the stable kernel releases - happen, and what to do if you want to get a change into one of these - releases. - - :ref:`Documentation/kernel-docs.txt ` - A list of external documentation that pertains to kernel - development. Please consult this list if you do not find what you - are looking for within the in-kernel documentation. - - :ref:`Documentation/applying-patches.txt ` - A good introduction describing exactly what a patch is and how to - apply it to the different development branches of the kernel. - -The kernel also has a large number of documents that can be -automatically generated from the source code itself or from -ReStructuredText markups (ReST), like this one. This includes a -full description of the in-kernel API, and rules on how to handle -locking properly. - -All such documents can be generated as PDF or HTML by running:: - - make pdfdocs - make htmldocs - -respectively from the main kernel source directory. - -The documents that uses ReST markup will be generated at Documentation/output. -They can also be generated on LaTeX and ePub formats with:: - - make latexdocs - make epubdocs - -Currently, there are some documents written on DocBook that are in -the process of conversion to ReST. Such documents will be created in the -Documentation/DocBook/ directory and can be generated also as -Postscript or man pages by running:: - - make psdocs - make mandocs - -Becoming A Kernel Developer ---------------------------- - -If you do not know anything about Linux kernel development, you should -look at the Linux KernelNewbies project: - - https://kernelnewbies.org - -It consists of a helpful mailing list where you can ask almost any type -of basic kernel development question (make sure to search the archives -first, before asking something that has already been answered in the -past.) It also has an IRC channel that you can use to ask questions in -real-time, and a lot of helpful documentation that is useful for -learning about Linux kernel development. - -The website has basic information about code organization, subsystems, -and current projects (both in-tree and out-of-tree). It also describes -some basic logistical information, like how to compile a kernel and -apply a patch. - -If you do not know where you want to start, but you want to look for -some task to start doing to join into the kernel development community, -go to the Linux Kernel Janitor's project: - - https://kernelnewbies.org/KernelJanitors - -It is a great place to start. It describes a list of relatively simple -problems that need to be cleaned up and fixed within the Linux kernel -source tree. Working with the developers in charge of this project, you -will learn the basics of getting your patch into the Linux kernel tree, -and possibly be pointed in the direction of what to go work on next, if -you do not already have an idea. - -If you already have a chunk of code that you want to put into the kernel -tree, but need some help getting it in the proper form, the -kernel-mentors project was created to help you out with this. It is a -mailing list, and can be found at: - - https://selenic.com/mailman/listinfo/kernel-mentors - -Before making any actual modifications to the Linux kernel code, it is -imperative to understand how the code in question works. For this -purpose, nothing is better than reading through it directly (most tricky -bits are commented well), perhaps even with the help of specialized -tools. One such tool that is particularly recommended is the Linux -Cross-Reference project, which is able to present source code in a -self-referential, indexed webpage format. An excellent up-to-date -repository of the kernel code may be found at: - - http://lxr.free-electrons.com/ - - -The development process ------------------------ - -Linux kernel development process currently consists of a few different -main kernel "branches" and lots of different subsystem-specific kernel -branches. These different branches are: - - - main 4.x kernel tree - - 4.x.y -stable kernel tree - - 4.x -git kernel patches - - subsystem specific kernel trees and patches - - the 4.x -next kernel tree for integration tests - -4.x kernel tree ------------------ -4.x kernels are maintained by Linus Torvalds, and can be found on -https://kernel.org in the pub/linux/kernel/v4.x/ directory. Its development -process is as follows: - - - As soon as a new kernel is released a two weeks window is open, - during this period of time maintainers can submit big diffs to - Linus, usually the patches that have already been included in the - -next kernel for a few weeks. The preferred way to submit big changes - is using git (the kernel's source management tool, more information - can be found at https://git-scm.com/) but plain patches are also just - fine. - - After two weeks a -rc1 kernel is released it is now possible to push - only patches that do not include new features that could affect the - stability of the whole kernel. Please note that a whole new driver - (or filesystem) might be accepted after -rc1 because there is no - risk of causing regressions with such a change as long as the change - is self-contained and does not affect areas outside of the code that - is being added. git can be used to send patches to Linus after -rc1 - is released, but the patches need to also be sent to a public - mailing list for review. - - A new -rc is released whenever Linus deems the current git tree to - be in a reasonably sane state adequate for testing. The goal is to - release a new -rc kernel every week. - - Process continues until the kernel is considered "ready", the - process should last around 6 weeks. - -It is worth mentioning what Andrew Morton wrote on the linux-kernel -mailing list about kernel releases: - - *"Nobody knows when a kernel will be released, because it's - released according to perceived bug status, not according to a - preconceived timeline."* - -4.x.y -stable kernel tree -------------------------- -Kernels with 3-part versions are -stable kernels. They contain -relatively small and critical fixes for security problems or significant -regressions discovered in a given 4.x kernel. - -This is the recommended branch for users who want the most recent stable -kernel and are not interested in helping test development/experimental -versions. - -If no 4.x.y kernel is available, then the highest numbered 4.x -kernel is the current stable kernel. - -4.x.y are maintained by the "stable" team , and -are released as needs dictate. The normal release period is approximately -two weeks, but it can be longer if there are no pressing problems. A -security-related problem, instead, can cause a release to happen almost -instantly. - -The file Documentation/stable_kernel_rules.txt in the kernel tree -documents what kinds of changes are acceptable for the -stable tree, and -how the release process works. - -4.x -git patches ----------------- -These are daily snapshots of Linus' kernel tree which are managed in a -git repository (hence the name.) These patches are usually released -daily and represent the current state of Linus' tree. They are more -experimental than -rc kernels since they are generated automatically -without even a cursory glance to see if they are sane. - -Subsystem Specific kernel trees and patches -------------------------------------------- -The maintainers of the various kernel subsystems --- and also many -kernel subsystem developers --- expose their current state of -development in source repositories. That way, others can see what is -happening in the different areas of the kernel. In areas where -development is rapid, a developer may be asked to base his submissions -onto such a subsystem kernel tree so that conflicts between the -submission and other already ongoing work are avoided. - -Most of these repositories are git trees, but there are also other SCMs -in use, or patch queues being published as quilt series. Addresses of -these subsystem repositories are listed in the MAINTAINERS file. Many -of them can be browsed at https://git.kernel.org/. - -Before a proposed patch is committed to such a subsystem tree, it is -subject to review which primarily happens on mailing lists (see the -respective section below). For several kernel subsystems, this review -process is tracked with the tool patchwork. Patchwork offers a web -interface which shows patch postings, any comments on a patch or -revisions to it, and maintainers can mark patches as under review, -accepted, or rejected. Most of these patchwork sites are listed at -https://patchwork.kernel.org/. - -4.x -next kernel tree for integration tests -------------------------------------------- -Before updates from subsystem trees are merged into the mainline 4.x -tree, they need to be integration-tested. For this purpose, a special -testing repository exists into which virtually all subsystem trees are -pulled on an almost daily basis: - - https://git.kernel.org/?p=linux/kernel/git/next/linux-next.git - -This way, the -next kernel gives a summary outlook onto what will be -expected to go into the mainline kernel at the next merge period. -Adventurous testers are very welcome to runtime-test the -next kernel. - - -Bug Reporting -------------- - -https://bugzilla.kernel.org is where the Linux kernel developers track kernel -bugs. Users are encouraged to report all bugs that they find in this -tool. For details on how to use the kernel bugzilla, please see: - - https://bugzilla.kernel.org/page.cgi?id=faq.html - -The file REPORTING-BUGS in the main kernel source directory has a good -template for how to report a possible kernel bug, and details what kind -of information is needed by the kernel developers to help track down the -problem. - - -Managing bug reports --------------------- - -One of the best ways to put into practice your hacking skills is by fixing -bugs reported by other people. Not only you will help to make the kernel -more stable, you'll learn to fix real world problems and you will improve -your skills, and other developers will be aware of your presence. Fixing -bugs is one of the best ways to get merits among other developers, because -not many people like wasting time fixing other people's bugs. - -To work in the already reported bug reports, go to https://bugzilla.kernel.org. -If you want to be advised of the future bug reports, you can subscribe to the -bugme-new mailing list (only new bug reports are mailed here) or to the -bugme-janitor mailing list (every change in the bugzilla is mailed here) - - https://lists.linux-foundation.org/mailman/listinfo/bugme-new - - https://lists.linux-foundation.org/mailman/listinfo/bugme-janitors - - - -Mailing lists -------------- - -As some of the above documents describe, the majority of the core kernel -developers participate on the Linux Kernel Mailing list. Details on how -to subscribe and unsubscribe from the list can be found at: - - http://vger.kernel.org/vger-lists.html#linux-kernel - -There are archives of the mailing list on the web in many different -places. Use a search engine to find these archives. For example: - - http://dir.gmane.org/gmane.linux.kernel - -It is highly recommended that you search the archives about the topic -you want to bring up, before you post it to the list. A lot of things -already discussed in detail are only recorded at the mailing list -archives. - -Most of the individual kernel subsystems also have their own separate -mailing list where they do their development efforts. See the -MAINTAINERS file for a list of what these lists are for the different -groups. - -Many of the lists are hosted on kernel.org. Information on them can be -found at: - - http://vger.kernel.org/vger-lists.html - -Please remember to follow good behavioral habits when using the lists. -Though a bit cheesy, the following URL has some simple guidelines for -interacting with the list (or any list): - - http://www.albion.com/netiquette/ - -If multiple people respond to your mail, the CC: list of recipients may -get pretty large. Don't remove anybody from the CC: list without a good -reason, or don't reply only to the list address. Get used to receiving the -mail twice, one from the sender and the one from the list, and don't try -to tune that by adding fancy mail-headers, people will not like it. - -Remember to keep the context and the attribution of your replies intact, -keep the "John Kernelhacker wrote ...:" lines at the top of your reply, and -add your statements between the individual quoted sections instead of -writing at the top of the mail. - -If you add patches to your mail, make sure they are plain readable text -as stated in Documentation/SubmittingPatches. -Kernel developers don't want to deal with -attachments or compressed patches; they may want to comment on -individual lines of your patch, which works only that way. Make sure you -use a mail program that does not mangle spaces and tab characters. A -good first test is to send the mail to yourself and try to apply your -own patch by yourself. If that doesn't work, get your mail program fixed -or change it until it works. - -Above all, please remember to show respect to other subscribers. - - -Working with the community --------------------------- - -The goal of the kernel community is to provide the best possible kernel -there is. When you submit a patch for acceptance, it will be reviewed -on its technical merits and those alone. So, what should you be -expecting? - - - criticism - - comments - - requests for change - - requests for justification - - silence - -Remember, this is part of getting your patch into the kernel. You have -to be able to take criticism and comments about your patches, evaluate -them at a technical level and either rework your patches or provide -clear and concise reasoning as to why those changes should not be made. -If there are no responses to your posting, wait a few days and try -again, sometimes things get lost in the huge volume. - -What should you not do? - - - expect your patch to be accepted without question - - become defensive - - ignore comments - - resubmit the patch without making any of the requested changes - -In a community that is looking for the best technical solution possible, -there will always be differing opinions on how beneficial a patch is. -You have to be cooperative, and willing to adapt your idea to fit within -the kernel. Or at least be willing to prove your idea is worth it. -Remember, being wrong is acceptable as long as you are willing to work -toward a solution that is right. - -It is normal that the answers to your first patch might simply be a list -of a dozen things you should correct. This does **not** imply that your -patch will not be accepted, and it is **not** meant against you -personally. Simply correct all issues raised against your patch and -resend it. - - -Differences between the kernel community and corporate structures ------------------------------------------------------------------ - -The kernel community works differently than most traditional corporate -development environments. Here are a list of things that you can try to -do to avoid problems: - - Good things to say regarding your proposed changes: - - - "This solves multiple problems." - - "This deletes 2000 lines of code." - - "Here is a patch that explains what I am trying to describe." - - "I tested it on 5 different architectures..." - - "Here is a series of small patches that..." - - "This increases performance on typical machines..." - - Bad things you should avoid saying: - - - "We did it this way in AIX/ptx/Solaris, so therefore it must be - good..." - - "I've being doing this for 20 years, so..." - - "This is required for my company to make money" - - "This is for our Enterprise product line." - - "Here is my 1000 page design document that describes my idea" - - "I've been working on this for 6 months..." - - "Here's a 5000 line patch that..." - - "I rewrote all of the current mess, and here it is..." - - "I have a deadline, and this patch needs to be applied now." - -Another way the kernel community is different than most traditional -software engineering work environments is the faceless nature of -interaction. One benefit of using email and irc as the primary forms of -communication is the lack of discrimination based on gender or race. -The Linux kernel work environment is accepting of women and minorities -because all you are is an email address. The international aspect also -helps to level the playing field because you can't guess gender based on -a person's name. A man may be named Andrea and a woman may be named Pat. -Most women who have worked in the Linux kernel and have expressed an -opinion have had positive experiences. - -The language barrier can cause problems for some people who are not -comfortable with English. A good grasp of the language can be needed in -order to get ideas across properly on mailing lists, so it is -recommended that you check your emails to make sure they make sense in -English before sending them. - - -Break up your changes ---------------------- - -The Linux kernel community does not gladly accept large chunks of code -dropped on it all at once. The changes need to be properly introduced, -discussed, and broken up into tiny, individual portions. This is almost -the exact opposite of what companies are used to doing. Your proposal -should also be introduced very early in the development process, so that -you can receive feedback on what you are doing. It also lets the -community feel that you are working with them, and not simply using them -as a dumping ground for your feature. However, don't send 50 emails at -one time to a mailing list, your patch series should be smaller than -that almost all of the time. - -The reasons for breaking things up are the following: - -1) Small patches increase the likelihood that your patches will be - applied, since they don't take much time or effort to verify for - correctness. A 5 line patch can be applied by a maintainer with - barely a second glance. However, a 500 line patch may take hours to - review for correctness (the time it takes is exponentially - proportional to the size of the patch, or something). - - Small patches also make it very easy to debug when something goes - wrong. It's much easier to back out patches one by one than it is - to dissect a very large patch after it's been applied (and broken - something). - -2) It's important not only to send small patches, but also to rewrite - and simplify (or simply re-order) patches before submitting them. - -Here is an analogy from kernel developer Al Viro: - - *"Think of a teacher grading homework from a math student. The - teacher does not want to see the student's trials and errors - before they came up with the solution. They want to see the - cleanest, most elegant answer. A good student knows this, and - would never submit her intermediate work before the final - solution.* - - *The same is true of kernel development. The maintainers and - reviewers do not want to see the thought process behind the - solution to the problem one is solving. They want to see a - simple and elegant solution."* - -It may be challenging to keep the balance between presenting an elegant -solution and working together with the community and discussing your -unfinished work. Therefore it is good to get early in the process to -get feedback to improve your work, but also keep your changes in small -chunks that they may get already accepted, even when your whole task is -not ready for inclusion now. - -Also realize that it is not acceptable to send patches for inclusion -that are unfinished and will be "fixed up later." - - -Justify your change -------------------- - -Along with breaking up your patches, it is very important for you to let -the Linux community know why they should add this change. New features -must be justified as being needed and useful. - - -Document your change --------------------- - -When sending in your patches, pay special attention to what you say in -the text in your email. This information will become the ChangeLog -information for the patch, and will be preserved for everyone to see for -all time. It should describe the patch completely, containing: - - - why the change is necessary - - the overall design approach in the patch - - implementation details - - testing results - -For more details on what this should all look like, please see the -ChangeLog section of the document: - - "The Perfect Patch" - http://www.ozlabs.org/~akpm/stuff/tpp.txt - - -All of these things are sometimes very hard to do. It can take years to -perfect these practices (if at all). It's a continuous process of -improvement that requires a lot of patience and determination. But -don't give up, it's possible. Many have done it before, and each had to -start exactly where you are now. - - - - ----------- - -Thanks to Paolo Ciarrocchi who allowed the "Development Process" -(https://lwn.net/Articles/94386/) section -to be based on text he had written, and to Randy Dunlap and Gerrit -Huizenga for some of the list of things you should and should not say. -Also thanks to Pat Mochel, Hanna Linder, Randy Dunlap, Kay Sievers, -Vojtech Pavlik, Jan Kara, Josh Boyer, Kees Cook, Andrew Morton, Andi -Kleen, Vadim Lobanov, Jesper Juhl, Adrian Bunk, Keri Harris, Frans Pop, -David A. Wheeler, Junio Hamano, Michael Kerrisk, and Alex Shepard for -their review, comments, and contributions. Without their help, this -document would not have been possible. - - - -Maintainer: Greg Kroah-Hartman diff --git a/Documentation/ManagementStyle b/Documentation/ManagementStyle deleted file mode 100644 index dea2e66c9a10..000000000000 --- a/Documentation/ManagementStyle +++ /dev/null @@ -1,288 +0,0 @@ -.. _managementstyle: - -Linux kernel management style -============================= - -This is a short document describing the preferred (or made up, depending -on who you ask) management style for the linux kernel. It's meant to -mirror the CodingStyle document to some degree, and mainly written to -avoid answering [#f1]_ the same (or similar) questions over and over again. - -Management style is very personal and much harder to quantify than -simple coding style rules, so this document may or may not have anything -to do with reality. It started as a lark, but that doesn't mean that it -might not actually be true. You'll have to decide for yourself. - -Btw, when talking about "kernel manager", it's all about the technical -lead persons, not the people who do traditional management inside -companies. If you sign purchase orders or you have any clue about the -budget of your group, you're almost certainly not a kernel manager. -These suggestions may or may not apply to you. - -First off, I'd suggest buying "Seven Habits of Highly Effective -People", and NOT read it. Burn it, it's a great symbolic gesture. - -.. [#f1] This document does so not so much by answering the question, but by - making it painfully obvious to the questioner that we don't have a clue - to what the answer is. - -Anyway, here goes: - -.. _decisions: - -1) Decisions ------------- - -Everybody thinks managers make decisions, and that decision-making is -important. The bigger and more painful the decision, the bigger the -manager must be to make it. That's very deep and obvious, but it's not -actually true. - -The name of the game is to **avoid** having to make a decision. In -particular, if somebody tells you "choose (a) or (b), we really need you -to decide on this", you're in trouble as a manager. The people you -manage had better know the details better than you, so if they come to -you for a technical decision, you're screwed. You're clearly not -competent to make that decision for them. - -(Corollary:if the people you manage don't know the details better than -you, you're also screwed, although for a totally different reason. -Namely that you are in the wrong job, and that **they** should be managing -your brilliance instead). - -So the name of the game is to **avoid** decisions, at least the big and -painful ones. Making small and non-consequential decisions is fine, and -makes you look like you know what you're doing, so what a kernel manager -needs to do is to turn the big and painful ones into small things where -nobody really cares. - -It helps to realize that the key difference between a big decision and a -small one is whether you can fix your decision afterwards. Any decision -can be made small by just always making sure that if you were wrong (and -you **will** be wrong), you can always undo the damage later by -backtracking. Suddenly, you get to be doubly managerial for making -**two** inconsequential decisions - the wrong one **and** the right one. - -And people will even see that as true leadership (*cough* bullshit -*cough*). - -Thus the key to avoiding big decisions becomes to just avoiding to do -things that can't be undone. Don't get ushered into a corner from which -you cannot escape. A cornered rat may be dangerous - a cornered manager -is just pitiful. - -It turns out that since nobody would be stupid enough to ever really let -a kernel manager have huge fiscal responsibility **anyway**, it's usually -fairly easy to backtrack. Since you're not going to be able to waste -huge amounts of money that you might not be able to repay, the only -thing you can backtrack on is a technical decision, and there -back-tracking is very easy: just tell everybody that you were an -incompetent nincompoop, say you're sorry, and undo all the worthless -work you had people work on for the last year. Suddenly the decision -you made a year ago wasn't a big decision after all, since it could be -easily undone. - -It turns out that some people have trouble with this approach, for two -reasons: - - - admitting you were an idiot is harder than it looks. We all like to - maintain appearances, and coming out in public to say that you were - wrong is sometimes very hard indeed. - - having somebody tell you that what you worked on for the last year - wasn't worthwhile after all can be hard on the poor lowly engineers - too, and while the actual **work** was easy enough to undo by just - deleting it, you may have irrevocably lost the trust of that - engineer. And remember: "irrevocable" was what we tried to avoid in - the first place, and your decision ended up being a big one after - all. - -Happily, both of these reasons can be mitigated effectively by just -admitting up-front that you don't have a friggin' clue, and telling -people ahead of the fact that your decision is purely preliminary, and -might be the wrong thing. You should always reserve the right to change -your mind, and make people very **aware** of that. And it's much easier -to admit that you are stupid when you haven't **yet** done the really -stupid thing. - -Then, when it really does turn out to be stupid, people just roll their -eyes and say "Oops, he did it again". - -This preemptive admission of incompetence might also make the people who -actually do the work also think twice about whether it's worth doing or -not. After all, if **they** aren't certain whether it's a good idea, you -sure as hell shouldn't encourage them by promising them that what they -work on will be included. Make them at least think twice before they -embark on a big endeavor. - -Remember: they'd better know more about the details than you do, and -they usually already think they have the answer to everything. The best -thing you can do as a manager is not to instill confidence, but rather a -healthy dose of critical thinking on what they do. - -Btw, another way to avoid a decision is to plaintively just whine "can't -we just do both?" and look pitiful. Trust me, it works. If it's not -clear which approach is better, they'll eventually figure it out. The -answer may end up being that both teams get so frustrated by the -situation that they just give up. - -That may sound like a failure, but it's usually a sign that there was -something wrong with both projects, and the reason the people involved -couldn't decide was that they were both wrong. You end up coming up -smelling like roses, and you avoided yet another decision that you could -have screwed up on. - - -2) People ---------- - -Most people are idiots, and being a manager means you'll have to deal -with it, and perhaps more importantly, that **they** have to deal with -**you**. - -It turns out that while it's easy to undo technical mistakes, it's not -as easy to undo personality disorders. You just have to live with -theirs - and yours. - -However, in order to prepare yourself as a kernel manager, it's best to -remember not to burn any bridges, bomb any innocent villagers, or -alienate too many kernel developers. It turns out that alienating people -is fairly easy, and un-alienating them is hard. Thus "alienating" -immediately falls under the heading of "not reversible", and becomes a -no-no according to :ref:`decisions`. - -There's just a few simple rules here: - - (1) don't call people d*ckheads (at least not in public) - (2) learn how to apologize when you forgot rule (1) - -The problem with #1 is that it's very easy to do, since you can say -"you're a d*ckhead" in millions of different ways [#f2]_, sometimes without -even realizing it, and almost always with a white-hot conviction that -you are right. - -And the more convinced you are that you are right (and let's face it, -you can call just about **anybody** a d*ckhead, and you often **will** be -right), the harder it ends up being to apologize afterwards. - -To solve this problem, you really only have two options: - - - get really good at apologies - - spread the "love" out so evenly that nobody really ends up feeling - like they get unfairly targeted. Make it inventive enough, and they - might even be amused. - -The option of being unfailingly polite really doesn't exist. Nobody will -trust somebody who is so clearly hiding his true character. - -.. [#f2] Paul Simon sang "Fifty Ways to Leave Your Lover", because quite - frankly, "A Million Ways to Tell a Developer He Is a D*ckhead" doesn't - scan nearly as well. But I'm sure he thought about it. - - -3) People II - the Good Kind ----------------------------- - -While it turns out that most people are idiots, the corollary to that is -sadly that you are one too, and that while we can all bask in the secure -knowledge that we're better than the average person (let's face it, -nobody ever believes that they're average or below-average), we should -also admit that we're not the sharpest knife around, and there will be -other people that are less of an idiot than you are. - -Some people react badly to smart people. Others take advantage of them. - -Make sure that you, as a kernel maintainer, are in the second group. -Suck up to them, because they are the people who will make your job -easier. In particular, they'll be able to make your decisions for you, -which is what the game is all about. - -So when you find somebody smarter than you are, just coast along. Your -management responsibilities largely become ones of saying "Sounds like a -good idea - go wild", or "That sounds good, but what about xxx?". The -second version in particular is a great way to either learn something -new about "xxx" or seem **extra** managerial by pointing out something the -smarter person hadn't thought about. In either case, you win. - -One thing to look out for is to realize that greatness in one area does -not necessarily translate to other areas. So you might prod people in -specific directions, but let's face it, they might be good at what they -do, and suck at everything else. The good news is that people tend to -naturally gravitate back to what they are good at, so it's not like you -are doing something irreversible when you **do** prod them in some -direction, just don't push too hard. - - -4) Placing blame ----------------- - -Things will go wrong, and people want somebody to blame. Tag, you're it. - -It's not actually that hard to accept the blame, especially if people -kind of realize that it wasn't **all** your fault. Which brings us to the -best way of taking the blame: do it for another guy. You'll feel good -for taking the fall, he'll feel good about not getting blamed, and the -guy who lost his whole 36GB porn-collection because of your incompetence -will grudgingly admit that you at least didn't try to weasel out of it. - -Then make the developer who really screwed up (if you can find him) know -**in_private** that he screwed up. Not just so he can avoid it in the -future, but so that he knows he owes you one. And, perhaps even more -importantly, he's also likely the person who can fix it. Because, let's -face it, it sure ain't you. - -Taking the blame is also why you get to be manager in the first place. -It's part of what makes people trust you, and allow you the potential -glory, because you're the one who gets to say "I screwed up". And if -you've followed the previous rules, you'll be pretty good at saying that -by now. - - -5) Things to avoid ------------------- - -There's one thing people hate even more than being called "d*ckhead", -and that is being called a "d*ckhead" in a sanctimonious voice. The -first you can apologize for, the second one you won't really get the -chance. They likely will no longer be listening even if you otherwise -do a good job. - -We all think we're better than anybody else, which means that when -somebody else puts on airs, it **really** rubs us the wrong way. You may -be morally and intellectually superior to everybody around you, but -don't try to make it too obvious unless you really **intend** to irritate -somebody [#f3]_. - -Similarly, don't be too polite or subtle about things. Politeness easily -ends up going overboard and hiding the problem, and as they say, "On the -internet, nobody can hear you being subtle". Use a big blunt object to -hammer the point in, because you can't really depend on people getting -your point otherwise. - -Some humor can help pad both the bluntness and the moralizing. Going -overboard to the point of being ridiculous can drive a point home -without making it painful to the recipient, who just thinks you're being -silly. It can thus help get through the personal mental block we all -have about criticism. - -.. [#f3] Hint: internet newsgroups that are not directly related to your work - are great ways to take out your frustrations at other people. Write - insulting posts with a sneer just to get into a good flame every once in - a while, and you'll feel cleansed. Just don't crap too close to home. - - -6) Why me? ----------- - -Since your main responsibility seems to be to take the blame for other -peoples mistakes, and make it painfully obvious to everybody else that -you're incompetent, the obvious question becomes one of why do it in the -first place? - -First off, while you may or may not get screaming teenage girls (or -boys, let's not be judgmental or sexist here) knocking on your dressing -room door, you **will** get an immense feeling of personal accomplishment -for being "in charge". Never mind the fact that you're really leading -by trying to keep up with everybody else and running after them as fast -as you can. Everybody will still think you're the person in charge. - -It's a great job if you can hack it. diff --git a/Documentation/SubmitChecklist b/Documentation/SubmitChecklist deleted file mode 100644 index 894289b22b15..000000000000 --- a/Documentation/SubmitChecklist +++ /dev/null @@ -1,120 +0,0 @@ -.. _submitchecklist: - -Linux Kernel patch submission checklist -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -Here are some basic things that developers should do if they want to see their -kernel patch submissions accepted more quickly. - -These are all above and beyond the documentation that is provided in -:ref:`Documentation/SubmittingPatches ` -and elsewhere regarding submitting Linux kernel patches. - - -1) If you use a facility then #include the file that defines/declares - that facility. Don't depend on other header files pulling in ones - that you use. - -2) Builds cleanly: - - a) with applicable or modified ``CONFIG`` options ``=y``, ``=m``, and - ``=n``. No ``gcc`` warnings/errors, no linker warnings/errors. - - b) Passes ``allnoconfig``, ``allmodconfig`` - - c) Builds successfully when using ``O=builddir`` - -3) Builds on multiple CPU architectures by using local cross-compile tools - or some other build farm. - -4) ppc64 is a good architecture for cross-compilation checking because it - tends to use ``unsigned long`` for 64-bit quantities. - -5) Check your patch for general style as detailed in - :ref:`Documentation/CodingStyle `. - Check for trivial violations with the patch style checker prior to - submission (``scripts/checkpatch.pl``). - You should be able to justify all violations that remain in - your patch. - -6) Any new or modified ``CONFIG`` options don't muck up the config menu. - -7) All new ``Kconfig`` options have help text. - -8) Has been carefully reviewed with respect to relevant ``Kconfig`` - combinations. This is very hard to get right with testing -- brainpower - pays off here. - -9) Check cleanly with sparse. - -10) Use ``make checkstack`` and ``make namespacecheck`` and fix any problems - that they find. - - .. note:: - - ``checkstack`` does not point out problems explicitly, - but any one function that uses more than 512 bytes on the stack is a - candidate for change. - -11) Include :ref:`kernel-doc ` to document global kernel APIs. - (Not required for static functions, but OK there also.) Use - ``make htmldocs`` or ``make pdfdocs`` to check the - :ref:`kernel-doc ` and fix any issues. - -12) Has been tested with ``CONFIG_PREEMPT``, ``CONFIG_DEBUG_PREEMPT``, - ``CONFIG_DEBUG_SLAB``, ``CONFIG_DEBUG_PAGEALLOC``, ``CONFIG_DEBUG_MUTEXES``, - ``CONFIG_DEBUG_SPINLOCK``, ``CONFIG_DEBUG_ATOMIC_SLEEP``, - ``CONFIG_PROVE_RCU`` and ``CONFIG_DEBUG_OBJECTS_RCU_HEAD`` all - simultaneously enabled. - -13) Has been build- and runtime tested with and without ``CONFIG_SMP`` and - ``CONFIG_PREEMPT.`` - -14) If the patch affects IO/Disk, etc: has been tested with and without - ``CONFIG_LBDAF.`` - -15) All codepaths have been exercised with all lockdep features enabled. - -16) All new ``/proc`` entries are documented under ``Documentation/`` - -17) All new kernel boot parameters are documented in - ``Documentation/kernel-parameters.txt``. - -18) All new module parameters are documented with ``MODULE_PARM_DESC()`` - -19) All new userspace interfaces are documented in ``Documentation/ABI/``. - See ``Documentation/ABI/README`` for more information. - Patches that change userspace interfaces should be CCed to - linux-api@vger.kernel.org. - -20) Check that it all passes ``make headers_check``. - -21) Has been checked with injection of at least slab and page-allocation - failures. See ``Documentation/fault-injection/``. - - If the new code is substantial, addition of subsystem-specific fault - injection might be appropriate. - -22) Newly-added code has been compiled with ``gcc -W`` (use - ``make EXTRA_CFLAGS=-W``). This will generate lots of noise, but is good - for finding bugs like "warning: comparison between signed and unsigned". - -23) Tested after it has been merged into the -mm patchset to make sure - that it still works with all of the other queued patches and various - changes in the VM, VFS, and other subsystems. - -24) All memory barriers {e.g., ``barrier()``, ``rmb()``, ``wmb()``} need a - comment in the source code that explains the logic of what they are doing - and why. - -25) If any ioctl's are added by the patch, then also update - ``Documentation/ioctl/ioctl-number.txt``. - -26) If your modified source code depends on or uses any of the kernel - APIs or features that are related to the following ``Kconfig`` symbols, - then test multiple builds with the related ``Kconfig`` symbols disabled - and/or ``=m`` (if that option is available) [not all of these at the - same time, just various/random combinations of them]: - - ``CONFIG_SMP``, ``CONFIG_SYSFS``, ``CONFIG_PROC_FS``, ``CONFIG_INPUT``, ``CONFIG_PCI``, ``CONFIG_BLOCK``, ``CONFIG_PM``, ``CONFIG_MAGIC_SYSRQ``, - ``CONFIG_NET``, ``CONFIG_INET=n`` (but latter with ``CONFIG_NET=y``). diff --git a/Documentation/SubmittingDrivers b/Documentation/SubmittingDrivers deleted file mode 100644 index 252b77a23fad..000000000000 --- a/Documentation/SubmittingDrivers +++ /dev/null @@ -1,183 +0,0 @@ -.. _submittingdrivers: - -Submitting Drivers For The Linux Kernel -======================================= - -This document is intended to explain how to submit device drivers to the -various kernel trees. Note that if you are interested in video card drivers -you should probably talk to XFree86 (http://www.xfree86.org/) and/or X.Org -(http://x.org/) instead. - -Also read the Documentation/SubmittingPatches document. - - -Allocating Device Numbers -------------------------- - -Major and minor numbers for block and character devices are allocated -by the Linux assigned name and number authority (currently this is -Torben Mathiasen). The site is http://www.lanana.org/. This -also deals with allocating numbers for devices that are not going to -be submitted to the mainstream kernel. -See Documentation/devices.txt for more information on this. - -If you don't use assigned numbers then when your device is submitted it will -be given an assigned number even if that is different from values you may -have shipped to customers before. - -Who To Submit Drivers To ------------------------- - -Linux 2.0: - No new drivers are accepted for this kernel tree. - -Linux 2.2: - No new drivers are accepted for this kernel tree. - -Linux 2.4: - If the code area has a general maintainer then please submit it to - the maintainer listed in MAINTAINERS in the kernel file. If the - maintainer does not respond or you cannot find the appropriate - maintainer then please contact Willy Tarreau . - -Linux 2.6 and upper: - The same rules apply as 2.4 except that you should follow linux-kernel - to track changes in API's. The final contact point for Linux 2.6+ - submissions is Andrew Morton. - -What Criteria Determine Acceptance ----------------------------------- - -Licensing: - The code must be released to us under the - GNU General Public License. We don't insist on any kind - of exclusive GPL licensing, and if you wish the driver - to be useful to other communities such as BSD you may well - wish to release under multiple licenses. - See accepted licenses at include/linux/module.h - -Copyright: - The copyright owner must agree to use of GPL. - It's best if the submitter and copyright owner - are the same person/entity. If not, the name of - the person/entity authorizing use of GPL should be - listed in case it's necessary to verify the will of - the copyright owner. - -Interfaces: - If your driver uses existing interfaces and behaves like - other drivers in the same class it will be much more likely - to be accepted than if it invents gratuitous new ones. - If you need to implement a common API over Linux and NT - drivers do it in userspace. - -Code: - Please use the Linux style of code formatting as documented - in :ref:`Documentation/CodingStyle `. - If you have sections of code - that need to be in other formats, for example because they - are shared with a windows driver kit and you want to - maintain them just once separate them out nicely and note - this fact. - -Portability: - Pointers are not always 32bits, not all computers are little - endian, people do not all have floating point and you - shouldn't use inline x86 assembler in your driver without - careful thought. Pure x86 drivers generally are not popular. - If you only have x86 hardware it is hard to test portability - but it is easy to make sure the code can easily be made - portable. - -Clarity: - It helps if anyone can see how to fix the driver. It helps - you because you get patches not bug reports. If you submit a - driver that intentionally obfuscates how the hardware works - it will go in the bitbucket. - -PM support: - Since Linux is used on many portable and desktop systems, your - driver is likely to be used on such a system and therefore it - should support basic power management by implementing, if - necessary, the .suspend and .resume methods used during the - system-wide suspend and resume transitions. You should verify - that your driver correctly handles the suspend and resume, but - if you are unable to ensure that, please at least define the - .suspend method returning the -ENOSYS ("Function not - implemented") error. You should also try to make sure that your - driver uses as little power as possible when it's not doing - anything. For the driver testing instructions see - Documentation/power/drivers-testing.txt and for a relatively - complete overview of the power management issues related to - drivers see Documentation/power/devices.txt . - -Control: - In general if there is active maintenance of a driver by - the author then patches will be redirected to them unless - they are totally obvious and without need of checking. - If you want to be the contact and update point for the - driver it is a good idea to state this in the comments, - and include an entry in MAINTAINERS for your driver. - -What Criteria Do Not Determine Acceptance ------------------------------------------ - -Vendor: - Being the hardware vendor and maintaining the driver is - often a good thing. If there is a stable working driver from - other people already in the tree don't expect 'we are the - vendor' to get your driver chosen. Ideally work with the - existing driver author to build a single perfect driver. - -Author: - It doesn't matter if a large Linux company wrote the driver, - or you did. Nobody has any special access to the kernel - tree. Anyone who tells you otherwise isn't telling the - whole story. - - -Resources ---------- - -Linux kernel master tree: - ftp.\ *country_code*\ .kernel.org:/pub/linux/kernel/... - - where *country_code* == your country code, such as - **us**, **uk**, **fr**, etc. - - http://git.kernel.org/?p=linux/kernel/git/torvalds/linux.git - -Linux kernel mailing list: - linux-kernel@vger.kernel.org - [mail majordomo@vger.kernel.org to subscribe] - -Linux Device Drivers, Third Edition (covers 2.6.10): - http://lwn.net/Kernel/LDD3/ (free version) - -LWN.net: - Weekly summary of kernel development activity - http://lwn.net/ - - 2.6 API changes: - - http://lwn.net/Articles/2.6-kernel-api/ - - Porting drivers from prior kernels to 2.6: - - http://lwn.net/Articles/driver-porting/ - -KernelNewbies: - Documentation and assistance for new kernel programmers - - http://kernelnewbies.org/ - -Linux USB project: - http://www.linux-usb.org/ - -How to NOT write kernel driver by Arjan van de Ven: - http://www.fenrus.org/how-to-not-write-a-device-driver-paper.pdf - -Kernel Janitor: - http://kernelnewbies.org/KernelJanitors - -GIT, Fast Version Control System: - http://git-scm.com/ diff --git a/Documentation/SubmittingPatches b/Documentation/SubmittingPatches deleted file mode 100644 index e62ddcdcaf5d..000000000000 --- a/Documentation/SubmittingPatches +++ /dev/null @@ -1,841 +0,0 @@ -.. _submittingpatches: - -How to Get Your Change Into the Linux Kernel or Care And Operation Of Your Linus Torvalds -========================================================================================= - -For a person or company who wishes to submit a change to the Linux -kernel, the process can sometimes be daunting if you're not familiar -with "the system." This text is a collection of suggestions which -can greatly increase the chances of your change being accepted. - -This document contains a large number of suggestions in a relatively terse -format. For detailed information on how the kernel development process -works, see :ref:`Documentation/process `. -Also, read :ref:`Documentation/SubmitChecklist ` -for a list of items to check before -submitting code. If you are submitting a driver, also read -:ref:`Documentation/SubmittingDrivers `; -for device tree binding patches, read -Documentation/devicetree/bindings/submitting-patches.txt. - -Many of these steps describe the default behavior of the ``git`` version -control system; if you use ``git`` to prepare your patches, you'll find much -of the mechanical work done for you, though you'll still need to prepare -and document a sensible set of patches. In general, use of ``git`` will make -your life as a kernel developer easier. - -Creating and Sending your Change -******************************** - - -0) Obtain a current source tree -------------------------------- - -If you do not have a repository with the current kernel source handy, use -``git`` to obtain one. You'll want to start with the mainline repository, -which can be grabbed with:: - - git clone git://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git - -Note, however, that you may not want to develop against the mainline tree -directly. Most subsystem maintainers run their own trees and want to see -patches prepared against those trees. See the **T:** entry for the subsystem -in the MAINTAINERS file to find that tree, or simply ask the maintainer if -the tree is not listed there. - -It is still possible to download kernel releases via tarballs (as described -in the next section), but that is the hard way to do kernel development. - -1) ``diff -up`` ---------------- - -If you must generate your patches by hand, use ``diff -up`` or ``diff -uprN`` -to create patches. Git generates patches in this form by default; if -you're using ``git``, you can skip this section entirely. - -All changes to the Linux kernel occur in the form of patches, as -generated by :manpage:`diff(1)`. When creating your patch, make sure to -create it in "unified diff" format, as supplied by the ``-u`` argument -to :manpage:`diff(1)`. -Also, please use the ``-p`` argument which shows which C function each -change is in - that makes the resultant ``diff`` a lot easier to read. -Patches should be based in the root kernel source directory, -not in any lower subdirectory. - -To create a patch for a single file, it is often sufficient to do:: - - SRCTREE= linux - MYFILE= drivers/net/mydriver.c - - cd $SRCTREE - cp $MYFILE $MYFILE.orig - vi $MYFILE # make your change - cd .. - diff -up $SRCTREE/$MYFILE{.orig,} > /tmp/patch - -To create a patch for multiple files, you should unpack a "vanilla", -or unmodified kernel source tree, and generate a ``diff`` against your -own source tree. For example:: - - MYSRC= /devel/linux - - tar xvfz linux-3.19.tar.gz - mv linux-3.19 linux-3.19-vanilla - diff -uprN -X linux-3.19-vanilla/Documentation/dontdiff \ - linux-3.19-vanilla $MYSRC > /tmp/patch - -``dontdiff`` is a list of files which are generated by the kernel during -the build process, and should be ignored in any :manpage:`diff(1)`-generated -patch. - -Make sure your patch does not include any extra files which do not -belong in a patch submission. Make sure to review your patch -after- -generating it with :manpage:`diff(1)`, to ensure accuracy. - -If your changes produce a lot of deltas, you need to split them into -individual patches which modify things in logical stages; see -:ref:`split_changes`. This will facilitate review by other kernel developers, -very important if you want your patch accepted. - -If you're using ``git``, ``git rebase -i`` can help you with this process. If -you're not using ``git``, ``quilt`` -is another popular alternative. - -.. _describe_changes: - -2) Describe your changes ------------------------- - -Describe your problem. Whether your patch is a one-line bug fix or -5000 lines of a new feature, there must be an underlying problem that -motivated you to do this work. Convince the reviewer that there is a -problem worth fixing and that it makes sense for them to read past the -first paragraph. - -Describe user-visible impact. Straight up crashes and lockups are -pretty convincing, but not all bugs are that blatant. Even if the -problem was spotted during code review, describe the impact you think -it can have on users. Keep in mind that the majority of Linux -installations run kernels from secondary stable trees or -vendor/product-specific trees that cherry-pick only specific patches -from upstream, so include anything that could help route your change -downstream: provoking circumstances, excerpts from dmesg, crash -descriptions, performance regressions, latency spikes, lockups, etc. - -Quantify optimizations and trade-offs. If you claim improvements in -performance, memory consumption, stack footprint, or binary size, -include numbers that back them up. But also describe non-obvious -costs. Optimizations usually aren't free but trade-offs between CPU, -memory, and readability; or, when it comes to heuristics, between -different workloads. Describe the expected downsides of your -optimization so that the reviewer can weigh costs against benefits. - -Once the problem is established, describe what you are actually doing -about it in technical detail. It's important to describe the change -in plain English for the reviewer to verify that the code is behaving -as you intend it to. - -The maintainer will thank you if you write your patch description in a -form which can be easily pulled into Linux's source code management -system, ``git``, as a "commit log". See :ref:`explicit_in_reply_to`. - -Solve only one problem per patch. If your description starts to get -long, that's a sign that you probably need to split up your patch. -See :ref:`split_changes`. - -When you submit or resubmit a patch or patch series, include the -complete patch description and justification for it. Don't just -say that this is version N of the patch (series). Don't expect the -subsystem maintainer to refer back to earlier patch versions or referenced -URLs to find the patch description and put that into the patch. -I.e., the patch (series) and its description should be self-contained. -This benefits both the maintainers and reviewers. Some reviewers -probably didn't even receive earlier versions of the patch. - -Describe your changes in imperative mood, e.g. "make xyzzy do frotz" -instead of "[This patch] makes xyzzy do frotz" or "[I] changed xyzzy -to do frotz", as if you are giving orders to the codebase to change -its behaviour. - -If the patch fixes a logged bug entry, refer to that bug entry by -number and URL. If the patch follows from a mailing list discussion, -give a URL to the mailing list archive; use the https://lkml.kernel.org/ -redirector with a ``Message-Id``, to ensure that the links cannot become -stale. - -However, try to make your explanation understandable without external -resources. In addition to giving a URL to a mailing list archive or -bug, summarize the relevant points of the discussion that led to the -patch as submitted. - -If you want to refer to a specific commit, don't just refer to the -SHA-1 ID of the commit. Please also include the oneline summary of -the commit, to make it easier for reviewers to know what it is about. -Example:: - - Commit e21d2170f36602ae2708 ("video: remove unnecessary - platform_set_drvdata()") removed the unnecessary - platform_set_drvdata(), but left the variable "dev" unused, - delete it. - -You should also be sure to use at least the first twelve characters of the -SHA-1 ID. The kernel repository holds a *lot* of objects, making -collisions with shorter IDs a real possibility. Bear in mind that, even if -there is no collision with your six-character ID now, that condition may -change five years from now. - -If your patch fixes a bug in a specific commit, e.g. you found an issue using -``git bisect``, please use the 'Fixes:' tag with the first 12 characters of -the SHA-1 ID, and the one line summary. For example:: - - Fixes: e21d2170f366 ("video: remove unnecessary platform_set_drvdata()") - -The following ``git config`` settings can be used to add a pretty format for -outputting the above style in the ``git log`` or ``git show`` commands:: - - [core] - abbrev = 12 - [pretty] - fixes = Fixes: %h (\"%s\") - -.. _split_changes: - -3) Separate your changes ------------------------- - -Separate each **logical change** into a separate patch. - -For example, if your changes include both bug fixes and performance -enhancements for a single driver, separate those changes into two -or more patches. If your changes include an API update, and a new -driver which uses that new API, separate those into two patches. - -On the other hand, if you make a single change to numerous files, -group those changes into a single patch. Thus a single logical change -is contained within a single patch. - -The point to remember is that each patch should make an easily understood -change that can be verified by reviewers. Each patch should be justifiable -on its own merits. - -If one patch depends on another patch in order for a change to be -complete, that is OK. Simply note **"this patch depends on patch X"** -in your patch description. - -When dividing your change into a series of patches, take special care to -ensure that the kernel builds and runs properly after each patch in the -series. Developers using ``git bisect`` to track down a problem can end up -splitting your patch series at any point; they will not thank you if you -introduce bugs in the middle. - -If you cannot condense your patch set into a smaller set of patches, -then only post say 15 or so at a time and wait for review and integration. - - - -4) Style-check your changes ---------------------------- - -Check your patch for basic style violations, details of which can be -found in -:ref:`Documentation/CodingStyle `. -Failure to do so simply wastes -the reviewers time and will get your patch rejected, probably -without even being read. - -One significant exception is when moving code from one file to -another -- in this case you should not modify the moved code at all in -the same patch which moves it. This clearly delineates the act of -moving the code and your changes. This greatly aids review of the -actual differences and allows tools to better track the history of -the code itself. - -Check your patches with the patch style checker prior to submission -(scripts/checkpatch.pl). Note, though, that the style checker should be -viewed as a guide, not as a replacement for human judgment. If your code -looks better with a violation then its probably best left alone. - -The checker reports at three levels: - - ERROR: things that are very likely to be wrong - - WARNING: things requiring careful review - - CHECK: things requiring thought - -You should be able to justify all violations that remain in your -patch. - - -5) Select the recipients for your patch ---------------------------------------- - -You should always copy the appropriate subsystem maintainer(s) on any patch -to code that they maintain; look through the MAINTAINERS file and the -source code revision history to see who those maintainers are. The -script scripts/get_maintainer.pl can be very useful at this step. If you -cannot find a maintainer for the subsystem you are working on, Andrew -Morton (akpm@linux-foundation.org) serves as a maintainer of last resort. - -You should also normally choose at least one mailing list to receive a copy -of your patch set. linux-kernel@vger.kernel.org functions as a list of -last resort, but the volume on that list has caused a number of developers -to tune it out. Look in the MAINTAINERS file for a subsystem-specific -list; your patch will probably get more attention there. Please do not -spam unrelated lists, though. - -Many kernel-related lists are hosted on vger.kernel.org; you can find a -list of them at http://vger.kernel.org/vger-lists.html. There are -kernel-related lists hosted elsewhere as well, though. - -Do not send more than 15 patches at once to the vger mailing lists!!! - -Linus Torvalds is the final arbiter of all changes accepted into the -Linux kernel. His e-mail address is . -He gets a lot of e-mail, and, at this point, very few patches go through -Linus directly, so typically you should do your best to -avoid- -sending him e-mail. - -If you have a patch that fixes an exploitable security bug, send that patch -to security@kernel.org. For severe bugs, a short embargo may be considered -to allow distributors to get the patch out to users; in such cases, -obviously, the patch should not be sent to any public lists. - -Patches that fix a severe bug in a released kernel should be directed -toward the stable maintainers by putting a line like this:: - - Cc: stable@vger.kernel.org - -into the sign-off area of your patch (note, NOT an email recipient). You -should also read -:ref:`Documentation/stable_kernel_rules.txt ` -in addition to this file. - -Note, however, that some subsystem maintainers want to come to their own -conclusions on which patches should go to the stable trees. The networking -maintainer, in particular, would rather not see individual developers -adding lines like the above to their patches. - -If changes affect userland-kernel interfaces, please send the MAN-PAGES -maintainer (as listed in the MAINTAINERS file) a man-pages patch, or at -least a notification of the change, so that some information makes its way -into the manual pages. User-space API changes should also be copied to -linux-api@vger.kernel.org. - -For small patches you may want to CC the Trivial Patch Monkey -trivial@kernel.org which collects "trivial" patches. Have a look -into the MAINTAINERS file for its current manager. - -Trivial patches must qualify for one of the following rules: - -- Spelling fixes in documentation -- Spelling fixes for errors which could break :manpage:`grep(1)` -- Warning fixes (cluttering with useless warnings is bad) -- Compilation fixes (only if they are actually correct) -- Runtime fixes (only if they actually fix things) -- Removing use of deprecated functions/macros -- Contact detail and documentation fixes -- Non-portable code replaced by portable code (even in arch-specific, - since people copy, as long as it's trivial) -- Any fix by the author/maintainer of the file (ie. patch monkey - in re-transmission mode) - - - -6) No MIME, no links, no compression, no attachments. Just plain text ----------------------------------------------------------------------- - -Linus and other kernel developers need to be able to read and comment -on the changes you are submitting. It is important for a kernel -developer to be able to "quote" your changes, using standard e-mail -tools, so that they may comment on specific portions of your code. - -For this reason, all patches should be submitted by e-mail "inline". - -.. warning:: - - Be wary of your editor's word-wrap corrupting your patch, - if you choose to cut-n-paste your patch. - -Do not attach the patch as a MIME attachment, compressed or not. -Many popular e-mail applications will not always transmit a MIME -attachment as plain text, making it impossible to comment on your -code. A MIME attachment also takes Linus a bit more time to process, -decreasing the likelihood of your MIME-attached change being accepted. - -Exception: If your mailer is mangling patches then someone may ask -you to re-send them using MIME. - -See :ref:`Documentation/email-clients.txt ` -for hints about configuring your e-mail client so that it sends your patches -untouched. - -7) E-mail size --------------- - -Large changes are not appropriate for mailing lists, and some -maintainers. If your patch, uncompressed, exceeds 300 kB in size, -it is preferred that you store your patch on an Internet-accessible -server, and provide instead a URL (link) pointing to your patch. But note -that if your patch exceeds 300 kB, it almost certainly needs to be broken up -anyway. - -8) Respond to review comments ------------------------------ - -Your patch will almost certainly get comments from reviewers on ways in -which the patch can be improved. You must respond to those comments; -ignoring reviewers is a good way to get ignored in return. Review comments -or questions that do not lead to a code change should almost certainly -bring about a comment or changelog entry so that the next reviewer better -understands what is going on. - -Be sure to tell the reviewers what changes you are making and to thank them -for their time. Code review is a tiring and time-consuming process, and -reviewers sometimes get grumpy. Even in that case, though, respond -politely and address the problems they have pointed out. - - -9) Don't get discouraged - or impatient ---------------------------------------- - -After you have submitted your change, be patient and wait. Reviewers are -busy people and may not get to your patch right away. - -Once upon a time, patches used to disappear into the void without comment, -but the development process works more smoothly than that now. You should -receive comments within a week or so; if that does not happen, make sure -that you have sent your patches to the right place. Wait for a minimum of -one week before resubmitting or pinging reviewers - possibly longer during -busy times like merge windows. - - -10) Include PATCH in the subject --------------------------------- - -Due to high e-mail traffic to Linus, and to linux-kernel, it is common -convention to prefix your subject line with [PATCH]. This lets Linus -and other kernel developers more easily distinguish patches from other -e-mail discussions. - - - -11) Sign your work ------------------- - -To improve tracking of who did what, especially with patches that can -percolate to their final resting place in the kernel through several -layers of maintainers, we've introduced a "sign-off" procedure on -patches that are being emailed around. - -The sign-off is a simple line at the end of the explanation for the -patch, which certifies that you wrote it or otherwise have the right to -pass it on as an open-source patch. The rules are pretty simple: if you -can certify the below: - -Developer's Certificate of Origin 1.1 -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -By making a contribution to this project, I certify that: - - (a) The contribution was created in whole or in part by me and I - have the right to submit it under the open source license - indicated in the file; or - - (b) The contribution is based upon previous work that, to the best - of my knowledge, is covered under an appropriate open source - license and I have the right under that license to submit that - work with modifications, whether created in whole or in part - by me, under the same open source license (unless I am - permitted to submit under a different license), as indicated - in the file; or - - (c) The contribution was provided directly to me by some other - person who certified (a), (b) or (c) and I have not modified - it. - - (d) I understand and agree that this project and the contribution - are public and that a record of the contribution (including all - personal information I submit with it, including my sign-off) is - maintained indefinitely and may be redistributed consistent with - this project or the open source license(s) involved. - -then you just add a line saying:: - - Signed-off-by: Random J Developer - -using your real name (sorry, no pseudonyms or anonymous contributions.) - -Some people also put extra tags at the end. They'll just be ignored for -now, but you can do this to mark internal company procedures or just -point out some special detail about the sign-off. - -If you are a subsystem or branch maintainer, sometimes you need to slightly -modify patches you receive in order to merge them, because the code is not -exactly the same in your tree and the submitters'. If you stick strictly to -rule (c), you should ask the submitter to rediff, but this is a totally -counter-productive waste of time and energy. Rule (b) allows you to adjust -the code, but then it is very impolite to change one submitter's code and -make him endorse your bugs. To solve this problem, it is recommended that -you add a line between the last Signed-off-by header and yours, indicating -the nature of your changes. While there is nothing mandatory about this, it -seems like prepending the description with your mail and/or name, all -enclosed in square brackets, is noticeable enough to make it obvious that -you are responsible for last-minute changes. Example:: - - Signed-off-by: Random J Developer - [lucky@maintainer.example.org: struct foo moved from foo.c to foo.h] - Signed-off-by: Lucky K Maintainer - -This practice is particularly helpful if you maintain a stable branch and -want at the same time to credit the author, track changes, merge the fix, -and protect the submitter from complaints. Note that under no circumstances -can you change the author's identity (the From header), as it is the one -which appears in the changelog. - -Special note to back-porters: It seems to be a common and useful practice -to insert an indication of the origin of a patch at the top of the commit -message (just after the subject line) to facilitate tracking. For instance, -here's what we see in a 3.x-stable release:: - - Date: Tue Oct 7 07:26:38 2014 -0400 - - libata: Un-break ATA blacklist - - commit 1c40279960bcd7d52dbdf1d466b20d24b99176c8 upstream. - -And here's what might appear in an older kernel once a patch is backported:: - - Date: Tue May 13 22:12:27 2008 +0200 - - wireless, airo: waitbusy() won't delay - - [backport of 2.6 commit b7acbdfbd1f277c1eb23f344f899cfa4cd0bf36a] - -Whatever the format, this information provides a valuable help to people -tracking your trees, and to people trying to troubleshoot bugs in your -tree. - - -12) When to use Acked-by: and Cc: ---------------------------------- - -The Signed-off-by: tag indicates that the signer was involved in the -development of the patch, or that he/she was in the patch's delivery path. - -If a person was not directly involved in the preparation or handling of a -patch but wishes to signify and record their approval of it then they can -ask to have an Acked-by: line added to the patch's changelog. - -Acked-by: is often used by the maintainer of the affected code when that -maintainer neither contributed to nor forwarded the patch. - -Acked-by: is not as formal as Signed-off-by:. It is a record that the acker -has at least reviewed the patch and has indicated acceptance. Hence patch -mergers will sometimes manually convert an acker's "yep, looks good to me" -into an Acked-by: (but note that it is usually better to ask for an -explicit ack). - -Acked-by: does not necessarily indicate acknowledgement of the entire patch. -For example, if a patch affects multiple subsystems and has an Acked-by: from -one subsystem maintainer then this usually indicates acknowledgement of just -the part which affects that maintainer's code. Judgement should be used here. -When in doubt people should refer to the original discussion in the mailing -list archives. - -If a person has had the opportunity to comment on a patch, but has not -provided such comments, you may optionally add a ``Cc:`` tag to the patch. -This is the only tag which might be added without an explicit action by the -person it names - but it should indicate that this person was copied on the -patch. This tag documents that potentially interested parties -have been included in the discussion. - - -13) Using Reported-by:, Tested-by:, Reviewed-by:, Suggested-by: and Fixes: --------------------------------------------------------------------------- - -The Reported-by tag gives credit to people who find bugs and report them and it -hopefully inspires them to help us again in the future. Please note that if -the bug was reported in private, then ask for permission first before using the -Reported-by tag. - -A Tested-by: tag indicates that the patch has been successfully tested (in -some environment) by the person named. This tag informs maintainers that -some testing has been performed, provides a means to locate testers for -future patches, and ensures credit for the testers. - -Reviewed-by:, instead, indicates that the patch has been reviewed and found -acceptable according to the Reviewer's Statement: - -Reviewer's statement of oversight -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -By offering my Reviewed-by: tag, I state that: - - (a) I have carried out a technical review of this patch to - evaluate its appropriateness and readiness for inclusion into - the mainline kernel. - - (b) Any problems, concerns, or questions relating to the patch - have been communicated back to the submitter. I am satisfied - with the submitter's response to my comments. - - (c) While there may be things that could be improved with this - submission, I believe that it is, at this time, (1) a - worthwhile modification to the kernel, and (2) free of known - issues which would argue against its inclusion. - - (d) While I have reviewed the patch and believe it to be sound, I - do not (unless explicitly stated elsewhere) make any - warranties or guarantees that it will achieve its stated - purpose or function properly in any given situation. - -A Reviewed-by tag is a statement of opinion that the patch is an -appropriate modification of the kernel without any remaining serious -technical issues. Any interested reviewer (who has done the work) can -offer a Reviewed-by tag for a patch. This tag serves to give credit to -reviewers and to inform maintainers of the degree of review which has been -done on the patch. Reviewed-by: tags, when supplied by reviewers known to -understand the subject area and to perform thorough reviews, will normally -increase the likelihood of your patch getting into the kernel. - -A Suggested-by: tag indicates that the patch idea is suggested by the person -named and ensures credit to the person for the idea. Please note that this -tag should not be added without the reporter's permission, especially if the -idea was not posted in a public forum. That said, if we diligently credit our -idea reporters, they will, hopefully, be inspired to help us again in the -future. - -A Fixes: tag indicates that the patch fixes an issue in a previous commit. It -is used to make it easy to determine where a bug originated, which can help -review a bug fix. This tag also assists the stable kernel team in determining -which stable kernel versions should receive your fix. This is the preferred -method for indicating a bug fixed by the patch. See :ref:`describe_changes` -for more details. - - -14) The canonical patch format ------------------------------- - -This section describes how the patch itself should be formatted. Note -that, if you have your patches stored in a ``git`` repository, proper patch -formatting can be had with ``git format-patch``. The tools cannot create -the necessary text, though, so read the instructions below anyway. - -The canonical patch subject line is:: - - Subject: [PATCH 001/123] subsystem: summary phrase - -The canonical patch message body contains the following: - - - A ``from`` line specifying the patch author (only needed if the person - sending the patch is not the author). - - - An empty line. - - - The body of the explanation, line wrapped at 75 columns, which will - be copied to the permanent changelog to describe this patch. - - - The ``Signed-off-by:`` lines, described above, which will - also go in the changelog. - - - A marker line containing simply ``---``. - - - Any additional comments not suitable for the changelog. - - - The actual patch (``diff`` output). - -The Subject line format makes it very easy to sort the emails -alphabetically by subject line - pretty much any email reader will -support that - since because the sequence number is zero-padded, -the numerical and alphabetic sort is the same. - -The ``subsystem`` in the email's Subject should identify which -area or subsystem of the kernel is being patched. - -The ``summary phrase`` in the email's Subject should concisely -describe the patch which that email contains. The ``summary -phrase`` should not be a filename. Do not use the same ``summary -phrase`` for every patch in a whole patch series (where a ``patch -series`` is an ordered sequence of multiple, related patches). - -Bear in mind that the ``summary phrase`` of your email becomes a -globally-unique identifier for that patch. It propagates all the way -into the ``git`` changelog. The ``summary phrase`` may later be used in -developer discussions which refer to the patch. People will want to -google for the ``summary phrase`` to read discussion regarding that -patch. It will also be the only thing that people may quickly see -when, two or three months later, they are going through perhaps -thousands of patches using tools such as ``gitk`` or ``git log ---oneline``. - -For these reasons, the ``summary`` must be no more than 70-75 -characters, and it must describe both what the patch changes, as well -as why the patch might be necessary. It is challenging to be both -succinct and descriptive, but that is what a well-written summary -should do. - -The ``summary phrase`` may be prefixed by tags enclosed in square -brackets: "Subject: [PATCH ...] ". The tags are -not considered part of the summary phrase, but describe how the patch -should be treated. Common tags might include a version descriptor if -the multiple versions of the patch have been sent out in response to -comments (i.e., "v1, v2, v3"), or "RFC" to indicate a request for -comments. If there are four patches in a patch series the individual -patches may be numbered like this: 1/4, 2/4, 3/4, 4/4. This assures -that developers understand the order in which the patches should be -applied and that they have reviewed or applied all of the patches in -the patch series. - -A couple of example Subjects:: - - Subject: [PATCH 2/5] ext2: improve scalability of bitmap searching - Subject: [PATCH v2 01/27] x86: fix eflags tracking - -The ``from`` line must be the very first line in the message body, -and has the form: - - From: Original Author - -The ``from`` line specifies who will be credited as the author of the -patch in the permanent changelog. If the ``from`` line is missing, -then the ``From:`` line from the email header will be used to determine -the patch author in the changelog. - -The explanation body will be committed to the permanent source -changelog, so should make sense to a competent reader who has long -since forgotten the immediate details of the discussion that might -have led to this patch. Including symptoms of the failure which the -patch addresses (kernel log messages, oops messages, etc.) is -especially useful for people who might be searching the commit logs -looking for the applicable patch. If a patch fixes a compile failure, -it may not be necessary to include _all_ of the compile failures; just -enough that it is likely that someone searching for the patch can find -it. As in the ``summary phrase``, it is important to be both succinct as -well as descriptive. - -The ``---`` marker line serves the essential purpose of marking for patch -handling tools where the changelog message ends. - -One good use for the additional comments after the ``---`` marker is for -a ``diffstat``, to show what files have changed, and the number of -inserted and deleted lines per file. A ``diffstat`` is especially useful -on bigger patches. Other comments relevant only to the moment or the -maintainer, not suitable for the permanent changelog, should also go -here. A good example of such comments might be ``patch changelogs`` -which describe what has changed between the v1 and v2 version of the -patch. - -If you are going to include a ``diffstat`` after the ``---`` marker, please -use ``diffstat`` options ``-p 1 -w 70`` so that filenames are listed from -the top of the kernel source tree and don't use too much horizontal -space (easily fit in 80 columns, maybe with some indentation). (``git`` -generates appropriate diffstats by default.) - -See more details on the proper patch format in the following -references. - -.. _explicit_in_reply_to: - -15) Explicit In-Reply-To headers --------------------------------- - -It can be helpful to manually add In-Reply-To: headers to a patch -(e.g., when using ``git send-email``) to associate the patch with -previous relevant discussion, e.g. to link a bug fix to the email with -the bug report. However, for a multi-patch series, it is generally -best to avoid using In-Reply-To: to link to older versions of the -series. This way multiple versions of the patch don't become an -unmanageable forest of references in email clients. If a link is -helpful, you can use the https://lkml.kernel.org/ redirector (e.g., in -the cover email text) to link to an earlier version of the patch series. - - -16) Sending ``git pull`` requests ---------------------------------- - -If you have a series of patches, it may be most convenient to have the -maintainer pull them directly into the subsystem repository with a -``git pull`` operation. Note, however, that pulling patches from a developer -requires a higher degree of trust than taking patches from a mailing list. -As a result, many subsystem maintainers are reluctant to take pull -requests, especially from new, unknown developers. If in doubt you can use -the pull request as the cover letter for a normal posting of the patch -series, giving the maintainer the option of using either. - -A pull request should have [GIT] or [PULL] in the subject line. The -request itself should include the repository name and the branch of -interest on a single line; it should look something like:: - - Please pull from - - git://jdelvare.pck.nerim.net/jdelvare-2.6 i2c-for-linus - - to get these changes: - -A pull request should also include an overall message saying what will be -included in the request, a ``git shortlog`` listing of the patches -themselves, and a ``diffstat`` showing the overall effect of the patch series. -The easiest way to get all this information together is, of course, to let -``git`` do it for you with the ``git request-pull`` command. - -Some maintainers (including Linus) want to see pull requests from signed -commits; that increases their confidence that the request actually came -from you. Linus, in particular, will not pull from public hosting sites -like GitHub in the absence of a signed tag. - -The first step toward creating such tags is to make a GNUPG key and get it -signed by one or more core kernel developers. This step can be hard for -new developers, but there is no way around it. Attending conferences can -be a good way to find developers who can sign your key. - -Once you have prepared a patch series in ``git`` that you wish to have somebody -pull, create a signed tag with ``git tag -s``. This will create a new tag -identifying the last commit in the series and containing a signature -created with your private key. You will also have the opportunity to add a -changelog-style message to the tag; this is an ideal place to describe the -effects of the pull request as a whole. - -If the tree the maintainer will be pulling from is not the repository you -are working from, don't forget to push the signed tag explicitly to the -public tree. - -When generating your pull request, use the signed tag as the target. A -command like this will do the trick:: - - git request-pull master git://my.public.tree/linux.git my-signed-tag - - -REFERENCES -********** - -Andrew Morton, "The perfect patch" (tpp). - - -Jeff Garzik, "Linux kernel patch submission format". - - -Greg Kroah-Hartman, "How to piss off a kernel subsystem maintainer". - - - - - - - - - - - - -NO!!!! No more huge patch bombs to linux-kernel@vger.kernel.org people! - - -Kernel Documentation/CodingStyle: - :ref:`Documentation/CodingStyle ` - -Linus Torvalds's mail on the canonical patch format: - - -Andi Kleen, "On submitting kernel patches" - Some strategies to get difficult or controversial changes in. - - http://halobates.de/on-submitting-patches.pdf - diff --git a/Documentation/adding-syscals.txt b/Documentation/adding-syscals.txt deleted file mode 100644 index f5b5b1aa51b3..000000000000 --- a/Documentation/adding-syscals.txt +++ /dev/null @@ -1,542 +0,0 @@ -Adding a New System Call -======================== - -This document describes what's involved in adding a new system call to the -Linux kernel, over and above the normal submission advice in -:ref:`Documentation/SubmittingPatches `. - - -System Call Alternatives ------------------------- - -The first thing to consider when adding a new system call is whether one of -the alternatives might be suitable instead. Although system calls are the -most traditional and most obvious interaction points between userspace and the -kernel, there are other possibilities -- choose what fits best for your -interface. - - - If the operations involved can be made to look like a filesystem-like - object, it may make more sense to create a new filesystem or device. This - also makes it easier to encapsulate the new functionality in a kernel module - rather than requiring it to be built into the main kernel. - - - If the new functionality involves operations where the kernel notifies - userspace that something has happened, then returning a new file - descriptor for the relevant object allows userspace to use - ``poll``/``select``/``epoll`` to receive that notification. - - However, operations that don't map to - :manpage:`read(2)`/:manpage:`write(2)`-like operations - have to be implemented as :manpage:`ioctl(2)` requests, which can lead - to a somewhat opaque API. - - - If you're just exposing runtime system information, a new node in sysfs - (see ``Documentation/filesystems/sysfs.txt``) or the ``/proc`` filesystem may - be more appropriate. However, access to these mechanisms requires that the - relevant filesystem is mounted, which might not always be the case (e.g. - in a namespaced/sandboxed/chrooted environment). Avoid adding any API to - debugfs, as this is not considered a 'production' interface to userspace. - - If the operation is specific to a particular file or file descriptor, then - an additional :manpage:`fcntl(2)` command option may be more appropriate. However, - :manpage:`fcntl(2)` is a multiplexing system call that hides a lot of complexity, so - this option is best for when the new function is closely analogous to - existing :manpage:`fcntl(2)` functionality, or the new functionality is very simple - (for example, getting/setting a simple flag related to a file descriptor). - - If the operation is specific to a particular task or process, then an - additional :manpage:`prctl(2)` command option may be more appropriate. As - with :manpage:`fcntl(2)`, this system call is a complicated multiplexor so - is best reserved for near-analogs of existing ``prctl()`` commands or - getting/setting a simple flag related to a process. - - -Designing the API: Planning for Extension ------------------------------------------ - -A new system call forms part of the API of the kernel, and has to be supported -indefinitely. As such, it's a very good idea to explicitly discuss the -interface on the kernel mailing list, and it's important to plan for future -extensions of the interface. - -(The syscall table is littered with historical examples where this wasn't done, -together with the corresponding follow-up system calls -- -``eventfd``/``eventfd2``, ``dup2``/``dup3``, ``inotify_init``/``inotify_init1``, -``pipe``/``pipe2``, ``renameat``/``renameat2`` -- so -learn from the history of the kernel and plan for extensions from the start.) - -For simpler system calls that only take a couple of arguments, the preferred -way to allow for future extensibility is to include a flags argument to the -system call. To make sure that userspace programs can safely use flags -between kernel versions, check whether the flags value holds any unknown -flags, and reject the system call (with ``EINVAL``) if it does:: - - if (flags & ~(THING_FLAG1 | THING_FLAG2 | THING_FLAG3)) - return -EINVAL; - -(If no flags values are used yet, check that the flags argument is zero.) - -For more sophisticated system calls that involve a larger number of arguments, -it's preferred to encapsulate the majority of the arguments into a structure -that is passed in by pointer. Such a structure can cope with future extension -by including a size argument in the structure:: - - struct xyzzy_params { - u32 size; /* userspace sets p->size = sizeof(struct xyzzy_params) */ - u32 param_1; - u64 param_2; - u64 param_3; - }; - -As long as any subsequently added field, say ``param_4``, is designed so that a -zero value gives the previous behaviour, then this allows both directions of -version mismatch: - - - To cope with a later userspace program calling an older kernel, the kernel - code should check that any memory beyond the size of the structure that it - expects is zero (effectively checking that ``param_4 == 0``). - - To cope with an older userspace program calling a newer kernel, the kernel - code can zero-extend a smaller instance of the structure (effectively - setting ``param_4 = 0``). - -See :manpage:`perf_event_open(2)` and the ``perf_copy_attr()`` function (in -``kernel/events/core.c``) for an example of this approach. - - -Designing the API: Other Considerations ---------------------------------------- - -If your new system call allows userspace to refer to a kernel object, it -should use a file descriptor as the handle for that object -- don't invent a -new type of userspace object handle when the kernel already has mechanisms and -well-defined semantics for using file descriptors. - -If your new :manpage:`xyzzy(2)` system call does return a new file descriptor, -then the flags argument should include a value that is equivalent to setting -``O_CLOEXEC`` on the new FD. This makes it possible for userspace to close -the timing window between ``xyzzy()`` and calling -``fcntl(fd, F_SETFD, FD_CLOEXEC)``, where an unexpected ``fork()`` and -``execve()`` in another thread could leak a descriptor to -the exec'ed program. (However, resist the temptation to re-use the actual value -of the ``O_CLOEXEC`` constant, as it is architecture-specific and is part of a -numbering space of ``O_*`` flags that is fairly full.) - -If your system call returns a new file descriptor, you should also consider -what it means to use the :manpage:`poll(2)` family of system calls on that file -descriptor. Making a file descriptor ready for reading or writing is the -normal way for the kernel to indicate to userspace that an event has -occurred on the corresponding kernel object. - -If your new :manpage:`xyzzy(2)` system call involves a filename argument:: - - int sys_xyzzy(const char __user *path, ..., unsigned int flags); - -you should also consider whether an :manpage:`xyzzyat(2)` version is more appropriate:: - - int sys_xyzzyat(int dfd, const char __user *path, ..., unsigned int flags); - -This allows more flexibility for how userspace specifies the file in question; -in particular it allows userspace to request the functionality for an -already-opened file descriptor using the ``AT_EMPTY_PATH`` flag, effectively -giving an :manpage:`fxyzzy(3)` operation for free:: - - - xyzzyat(AT_FDCWD, path, ..., 0) is equivalent to xyzzy(path,...) - - xyzzyat(fd, "", ..., AT_EMPTY_PATH) is equivalent to fxyzzy(fd, ...) - -(For more details on the rationale of the \*at() calls, see the -:manpage:`openat(2)` man page; for an example of AT_EMPTY_PATH, see the -:manpage:`fstatat(2)` man page.) - -If your new :manpage:`xyzzy(2)` system call involves a parameter describing an -offset within a file, make its type ``loff_t`` so that 64-bit offsets can be -supported even on 32-bit architectures. - -If your new :manpage:`xyzzy(2)` system call involves privileged functionality, -it needs to be governed by the appropriate Linux capability bit (checked with -a call to ``capable()``), as described in the :manpage:`capabilities(7)` man -page. Choose an existing capability bit that governs related functionality, -but try to avoid combining lots of only vaguely related functions together -under the same bit, as this goes against capabilities' purpose of splitting -the power of root. In particular, avoid adding new uses of the already -overly-general ``CAP_SYS_ADMIN`` capability. - -If your new :manpage:`xyzzy(2)` system call manipulates a process other than -the calling process, it should be restricted (using a call to -``ptrace_may_access()``) so that only a calling process with the same -permissions as the target process, or with the necessary capabilities, can -manipulate the target process. - -Finally, be aware that some non-x86 architectures have an easier time if -system call parameters that are explicitly 64-bit fall on odd-numbered -arguments (i.e. parameter 1, 3, 5), to allow use of contiguous pairs of 32-bit -registers. (This concern does not apply if the arguments are part of a -structure that's passed in by pointer.) - - -Proposing the API ------------------ - -To make new system calls easy to review, it's best to divide up the patchset -into separate chunks. These should include at least the following items as -distinct commits (each of which is described further below): - - - The core implementation of the system call, together with prototypes, - generic numbering, Kconfig changes and fallback stub implementation. - - Wiring up of the new system call for one particular architecture, usually - x86 (including all of x86_64, x86_32 and x32). - - A demonstration of the use of the new system call in userspace via a - selftest in ``tools/testing/selftests/``. - - A draft man-page for the new system call, either as plain text in the - cover letter, or as a patch to the (separate) man-pages repository. - -New system call proposals, like any change to the kernel's API, should always -be cc'ed to linux-api@vger.kernel.org. - - -Generic System Call Implementation ----------------------------------- - -The main entry point for your new :manpage:`xyzzy(2)` system call will be called -``sys_xyzzy()``, but you add this entry point with the appropriate -``SYSCALL_DEFINEn()`` macro rather than explicitly. The 'n' indicates the -number of arguments to the system call, and the macro takes the system call name -followed by the (type, name) pairs for the parameters as arguments. Using -this macro allows metadata about the new system call to be made available for -other tools. - -The new entry point also needs a corresponding function prototype, in -``include/linux/syscalls.h``, marked as asmlinkage to match the way that system -calls are invoked:: - - asmlinkage long sys_xyzzy(...); - -Some architectures (e.g. x86) have their own architecture-specific syscall -tables, but several other architectures share a generic syscall table. Add your -new system call to the generic list by adding an entry to the list in -``include/uapi/asm-generic/unistd.h``:: - - #define __NR_xyzzy 292 - __SYSCALL(__NR_xyzzy, sys_xyzzy) - -Also update the __NR_syscalls count to reflect the additional system call, and -note that if multiple new system calls are added in the same merge window, -your new syscall number may get adjusted to resolve conflicts. - -The file ``kernel/sys_ni.c`` provides a fallback stub implementation of each -system call, returning ``-ENOSYS``. Add your new system call here too:: - - cond_syscall(sys_xyzzy); - -Your new kernel functionality, and the system call that controls it, should -normally be optional, so add a ``CONFIG`` option (typically to -``init/Kconfig``) for it. As usual for new ``CONFIG`` options: - - - Include a description of the new functionality and system call controlled - by the option. - - Make the option depend on EXPERT if it should be hidden from normal users. - - Make any new source files implementing the function dependent on the CONFIG - option in the Makefile (e.g. ``obj-$(CONFIG_XYZZY_SYSCALL) += xyzzy.c``). - - Double check that the kernel still builds with the new CONFIG option turned - off. - -To summarize, you need a commit that includes: - - - ``CONFIG`` option for the new function, normally in ``init/Kconfig`` - - ``SYSCALL_DEFINEn(xyzzy, ...)`` for the entry point - - corresponding prototype in ``include/linux/syscalls.h`` - - generic table entry in ``include/uapi/asm-generic/unistd.h`` - - fallback stub in ``kernel/sys_ni.c`` - - -x86 System Call Implementation ------------------------------- - -To wire up your new system call for x86 platforms, you need to update the -master syscall tables. Assuming your new system call isn't special in some -way (see below), this involves a "common" entry (for x86_64 and x32) in -arch/x86/entry/syscalls/syscall_64.tbl:: - - 333 common xyzzy sys_xyzzy - -and an "i386" entry in ``arch/x86/entry/syscalls/syscall_32.tbl``:: - - 380 i386 xyzzy sys_xyzzy - -Again, these numbers are liable to be changed if there are conflicts in the -relevant merge window. - - -Compatibility System Calls (Generic) ------------------------------------- - -For most system calls the same 64-bit implementation can be invoked even when -the userspace program is itself 32-bit; even if the system call's parameters -include an explicit pointer, this is handled transparently. - -However, there are a couple of situations where a compatibility layer is -needed to cope with size differences between 32-bit and 64-bit. - -The first is if the 64-bit kernel also supports 32-bit userspace programs, and -so needs to parse areas of (``__user``) memory that could hold either 32-bit or -64-bit values. In particular, this is needed whenever a system call argument -is: - - - a pointer to a pointer - - a pointer to a struct containing a pointer (e.g. ``struct iovec __user *``) - - a pointer to a varying sized integral type (``time_t``, ``off_t``, - ``long``, ...) - - a pointer to a struct containing a varying sized integral type. - -The second situation that requires a compatibility layer is if one of the -system call's arguments has a type that is explicitly 64-bit even on a 32-bit -architecture, for example ``loff_t`` or ``__u64``. In this case, a value that -arrives at a 64-bit kernel from a 32-bit application will be split into two -32-bit values, which then need to be re-assembled in the compatibility layer. - -(Note that a system call argument that's a pointer to an explicit 64-bit type -does **not** need a compatibility layer; for example, :manpage:`splice(2)`'s arguments of -type ``loff_t __user *`` do not trigger the need for a ``compat_`` system call.) - -The compatibility version of the system call is called ``compat_sys_xyzzy()``, -and is added with the ``COMPAT_SYSCALL_DEFINEn()`` macro, analogously to -SYSCALL_DEFINEn. This version of the implementation runs as part of a 64-bit -kernel, but expects to receive 32-bit parameter values and does whatever is -needed to deal with them. (Typically, the ``compat_sys_`` version converts the -values to 64-bit versions and either calls on to the ``sys_`` version, or both of -them call a common inner implementation function.) - -The compat entry point also needs a corresponding function prototype, in -``include/linux/compat.h``, marked as asmlinkage to match the way that system -calls are invoked:: - - asmlinkage long compat_sys_xyzzy(...); - -If the system call involves a structure that is laid out differently on 32-bit -and 64-bit systems, say ``struct xyzzy_args``, then the include/linux/compat.h -header file should also include a compat version of the structure (``struct -compat_xyzzy_args``) where each variable-size field has the appropriate -``compat_`` type that corresponds to the type in ``struct xyzzy_args``. The -``compat_sys_xyzzy()`` routine can then use this ``compat_`` structure to -parse the arguments from a 32-bit invocation. - -For example, if there are fields:: - - struct xyzzy_args { - const char __user *ptr; - __kernel_long_t varying_val; - u64 fixed_val; - /* ... */ - }; - -in struct xyzzy_args, then struct compat_xyzzy_args would have:: - - struct compat_xyzzy_args { - compat_uptr_t ptr; - compat_long_t varying_val; - u64 fixed_val; - /* ... */ - }; - -The generic system call list also needs adjusting to allow for the compat -version; the entry in ``include/uapi/asm-generic/unistd.h`` should use -``__SC_COMP`` rather than ``__SYSCALL``:: - - #define __NR_xyzzy 292 - __SC_COMP(__NR_xyzzy, sys_xyzzy, compat_sys_xyzzy) - -To summarize, you need: - - - a ``COMPAT_SYSCALL_DEFINEn(xyzzy, ...)`` for the compat entry point - - corresponding prototype in ``include/linux/compat.h`` - - (if needed) 32-bit mapping struct in ``include/linux/compat.h`` - - instance of ``__SC_COMP`` not ``__SYSCALL`` in - ``include/uapi/asm-generic/unistd.h`` - - -Compatibility System Calls (x86) --------------------------------- - -To wire up the x86 architecture of a system call with a compatibility version, -the entries in the syscall tables need to be adjusted. - -First, the entry in ``arch/x86/entry/syscalls/syscall_32.tbl`` gets an extra -column to indicate that a 32-bit userspace program running on a 64-bit kernel -should hit the compat entry point:: - - 380 i386 xyzzy sys_xyzzy compat_sys_xyzzy - -Second, you need to figure out what should happen for the x32 ABI version of -the new system call. There's a choice here: the layout of the arguments -should either match the 64-bit version or the 32-bit version. - -If there's a pointer-to-a-pointer involved, the decision is easy: x32 is -ILP32, so the layout should match the 32-bit version, and the entry in -``arch/x86/entry/syscalls/syscall_64.tbl`` is split so that x32 programs hit -the compatibility wrapper:: - - 333 64 xyzzy sys_xyzzy - ... - 555 x32 xyzzy compat_sys_xyzzy - -If no pointers are involved, then it is preferable to re-use the 64-bit system -call for the x32 ABI (and consequently the entry in -arch/x86/entry/syscalls/syscall_64.tbl is unchanged). - -In either case, you should check that the types involved in your argument -layout do indeed map exactly from x32 (-mx32) to either the 32-bit (-m32) or -64-bit (-m64) equivalents. - - -System Calls Returning Elsewhere --------------------------------- - -For most system calls, once the system call is complete the user program -continues exactly where it left off -- at the next instruction, with the -stack the same and most of the registers the same as before the system call, -and with the same virtual memory space. - -However, a few system calls do things differently. They might return to a -different location (``rt_sigreturn``) or change the memory space -(``fork``/``vfork``/``clone``) or even architecture (``execve``/``execveat``) -of the program. - -To allow for this, the kernel implementation of the system call may need to -save and restore additional registers to the kernel stack, allowing complete -control of where and how execution continues after the system call. - -This is arch-specific, but typically involves defining assembly entry points -that save/restore additional registers and invoke the real system call entry -point. - -For x86_64, this is implemented as a ``stub_xyzzy`` entry point in -``arch/x86/entry/entry_64.S``, and the entry in the syscall table -(``arch/x86/entry/syscalls/syscall_64.tbl``) is adjusted to match:: - - 333 common xyzzy stub_xyzzy - -The equivalent for 32-bit programs running on a 64-bit kernel is normally -called ``stub32_xyzzy`` and implemented in ``arch/x86/entry/entry_64_compat.S``, -with the corresponding syscall table adjustment in -``arch/x86/entry/syscalls/syscall_32.tbl``:: - - 380 i386 xyzzy sys_xyzzy stub32_xyzzy - -If the system call needs a compatibility layer (as in the previous section) -then the ``stub32_`` version needs to call on to the ``compat_sys_`` version -of the system call rather than the native 64-bit version. Also, if the x32 ABI -implementation is not common with the x86_64 version, then its syscall -table will also need to invoke a stub that calls on to the ``compat_sys_`` -version. - -For completeness, it's also nice to set up a mapping so that user-mode Linux -still works -- its syscall table will reference stub_xyzzy, but the UML build -doesn't include ``arch/x86/entry/entry_64.S`` implementation (because UML -simulates registers etc). Fixing this is as simple as adding a #define to -``arch/x86/um/sys_call_table_64.c``:: - - #define stub_xyzzy sys_xyzzy - - -Other Details -------------- - -Most of the kernel treats system calls in a generic way, but there is the -occasional exception that may need updating for your particular system call. - -The audit subsystem is one such special case; it includes (arch-specific) -functions that classify some special types of system call -- specifically -file open (``open``/``openat``), program execution (``execve``/``exeveat``) or -socket multiplexor (``socketcall``) operations. If your new system call is -analogous to one of these, then the audit system should be updated. - -More generally, if there is an existing system call that is analogous to your -new system call, it's worth doing a kernel-wide grep for the existing system -call to check there are no other special cases. - - -Testing -------- - -A new system call should obviously be tested; it is also useful to provide -reviewers with a demonstration of how user space programs will use the system -call. A good way to combine these aims is to include a simple self-test -program in a new directory under ``tools/testing/selftests/``. - -For a new system call, there will obviously be no libc wrapper function and so -the test will need to invoke it using ``syscall()``; also, if the system call -involves a new userspace-visible structure, the corresponding header will need -to be installed to compile the test. - -Make sure the selftest runs successfully on all supported architectures. For -example, check that it works when compiled as an x86_64 (-m64), x86_32 (-m32) -and x32 (-mx32) ABI program. - -For more extensive and thorough testing of new functionality, you should also -consider adding tests to the Linux Test Project, or to the xfstests project -for filesystem-related changes. - - - https://linux-test-project.github.io/ - - git://git.kernel.org/pub/scm/fs/xfs/xfstests-dev.git - - -Man Page --------- - -All new system calls should come with a complete man page, ideally using groff -markup, but plain text will do. If groff is used, it's helpful to include a -pre-rendered ASCII version of the man page in the cover email for the -patchset, for the convenience of reviewers. - -The man page should be cc'ed to linux-man@vger.kernel.org -For more details, see https://www.kernel.org/doc/man-pages/patches.html - -References and Sources ----------------------- - - - LWN article from Michael Kerrisk on use of flags argument in system calls: - https://lwn.net/Articles/585415/ - - LWN article from Michael Kerrisk on how to handle unknown flags in a system - call: https://lwn.net/Articles/588444/ - - LWN article from Jake Edge describing constraints on 64-bit system call - arguments: https://lwn.net/Articles/311630/ - - Pair of LWN articles from David Drysdale that describe the system call - implementation paths in detail for v3.14: - - - https://lwn.net/Articles/604287/ - - https://lwn.net/Articles/604515/ - - - Architecture-specific requirements for system calls are discussed in the - :manpage:`syscall(2)` man-page: - http://man7.org/linux/man-pages/man2/syscall.2.html#NOTES - - Collated emails from Linus Torvalds discussing the problems with ``ioctl()``: - http://yarchive.net/comp/linux/ioctl.html - - "How to not invent kernel interfaces", Arnd Bergmann, - http://www.ukuug.org/events/linux2007/2007/papers/Bergmann.pdf - - LWN article from Michael Kerrisk on avoiding new uses of CAP_SYS_ADMIN: - https://lwn.net/Articles/486306/ - - Recommendation from Andrew Morton that all related information for a new - system call should come in the same email thread: - https://lkml.org/lkml/2014/7/24/641 - - Recommendation from Michael Kerrisk that a new system call should come with - a man page: https://lkml.org/lkml/2014/6/13/309 - - Suggestion from Thomas Gleixner that x86 wire-up should be in a separate - commit: https://lkml.org/lkml/2014/11/19/254 - - Suggestion from Greg Kroah-Hartman that it's good for new system calls to - come with a man-page & selftest: https://lkml.org/lkml/2014/3/19/710 - - Discussion from Michael Kerrisk of new system call vs. :manpage:`prctl(2)` extension: - https://lkml.org/lkml/2014/6/3/411 - - Suggestion from Ingo Molnar that system calls that involve multiple - arguments should encapsulate those arguments in a struct, which includes a - size field for future extensibility: https://lkml.org/lkml/2015/7/30/117 - - Numbering oddities arising from (re-)use of O_* numbering space flags: - - - commit 75069f2b5bfb ("vfs: renumber FMODE_NONOTIFY and add to uniqueness - check") - - commit 12ed2e36c98a ("fanotify: FMODE_NONOTIFY and __O_SYNC in sparc - conflict") - - commit bb458c644a59 ("Safer ABI for O_TMPFILE") - - - Discussion from Matthew Wilcox about restrictions on 64-bit arguments: - https://lkml.org/lkml/2008/12/12/187 - - Recommendation from Greg Kroah-Hartman that unknown flags should be - policed: https://lkml.org/lkml/2014/7/17/577 - - Recommendation from Linus Torvalds that x32 system calls should prefer - compatibility with 64-bit versions rather than 32-bit versions: - https://lkml.org/lkml/2011/8/31/244 diff --git a/Documentation/applying-patches.txt b/Documentation/applying-patches.txt deleted file mode 100644 index 3395da13d415..000000000000 --- a/Documentation/applying-patches.txt +++ /dev/null @@ -1,465 +0,0 @@ -.. _applying_patches: - -Applying Patches To The Linux Kernel -++++++++++++++++++++++++++++++++++++ - -Original by: - Jesper Juhl, August 2005 - -Last update: - 2016-09-14 - - -A frequently asked question on the Linux Kernel Mailing List is how to apply -a patch to the kernel or, more specifically, what base kernel a patch for -one of the many trees/branches should be applied to. Hopefully this document -will explain this to you. - -In addition to explaining how to apply and revert patches, a brief -description of the different kernel trees (and examples of how to apply -their specific patches) is also provided. - - -What is a patch? -================ - -A patch is a small text document containing a delta of changes between two -different versions of a source tree. Patches are created with the ``diff`` -program. - -To correctly apply a patch you need to know what base it was generated from -and what new version the patch will change the source tree into. These -should both be present in the patch file metadata or be possible to deduce -from the filename. - - -How do I apply or revert a patch? -================================= - -You apply a patch with the ``patch`` program. The patch program reads a diff -(or patch) file and makes the changes to the source tree described in it. - -Patches for the Linux kernel are generated relative to the parent directory -holding the kernel source dir. - -This means that paths to files inside the patch file contain the name of the -kernel source directories it was generated against (or some other directory -names like "a/" and "b/"). - -Since this is unlikely to match the name of the kernel source dir on your -local machine (but is often useful info to see what version an otherwise -unlabeled patch was generated against) you should change into your kernel -source directory and then strip the first element of the path from filenames -in the patch file when applying it (the ``-p1`` argument to ``patch`` does -this). - -To revert a previously applied patch, use the -R argument to patch. -So, if you applied a patch like this:: - - patch -p1 < ../patch-x.y.z - -You can revert (undo) it like this:: - - patch -R -p1 < ../patch-x.y.z - - -How do I feed a patch/diff file to ``patch``? -============================================= - -This (as usual with Linux and other UNIX like operating systems) can be -done in several different ways. - -In all the examples below I feed the file (in uncompressed form) to patch -via stdin using the following syntax:: - - patch -p1 < path/to/patch-x.y.z - -If you just want to be able to follow the examples below and don't want to -know of more than one way to use patch, then you can stop reading this -section here. - -Patch can also get the name of the file to use via the -i argument, like -this:: - - patch -p1 -i path/to/patch-x.y.z - -If your patch file is compressed with gzip or xz and you don't want to -uncompress it before applying it, then you can feed it to patch like this -instead:: - - xzcat path/to/patch-x.y.z.xz | patch -p1 - bzcat path/to/patch-x.y.z.gz | patch -p1 - -If you wish to uncompress the patch file by hand first before applying it -(what I assume you've done in the examples below), then you simply run -gunzip or xz on the file -- like this:: - - gunzip patch-x.y.z.gz - xz -d patch-x.y.z.xz - -Which will leave you with a plain text patch-x.y.z file that you can feed to -patch via stdin or the ``-i`` argument, as you prefer. - -A few other nice arguments for patch are ``-s`` which causes patch to be silent -except for errors which is nice to prevent errors from scrolling out of the -screen too fast, and ``--dry-run`` which causes patch to just print a listing of -what would happen, but doesn't actually make any changes. Finally ``--verbose`` -tells patch to print more information about the work being done. - - -Common errors when patching -=========================== - -When patch applies a patch file it attempts to verify the sanity of the -file in different ways. - -Checking that the file looks like a valid patch file and checking the code -around the bits being modified matches the context provided in the patch are -just two of the basic sanity checks patch does. - -If patch encounters something that doesn't look quite right it has two -options. It can either refuse to apply the changes and abort or it can try -to find a way to make the patch apply with a few minor changes. - -One example of something that's not 'quite right' that patch will attempt to -fix up is if all the context matches, the lines being changed match, but the -line numbers are different. This can happen, for example, if the patch makes -a change in the middle of the file but for some reasons a few lines have -been added or removed near the beginning of the file. In that case -everything looks good it has just moved up or down a bit, and patch will -usually adjust the line numbers and apply the patch. - -Whenever patch applies a patch that it had to modify a bit to make it fit -it'll tell you about it by saying the patch applied with **fuzz**. -You should be wary of such changes since even though patch probably got it -right it doesn't /always/ get it right, and the result will sometimes be -wrong. - -When patch encounters a change that it can't fix up with fuzz it rejects it -outright and leaves a file with a ``.rej`` extension (a reject file). You can -read this file to see exactly what change couldn't be applied, so you can -go fix it up by hand if you wish. - -If you don't have any third-party patches applied to your kernel source, but -only patches from kernel.org and you apply the patches in the correct order, -and have made no modifications yourself to the source files, then you should -never see a fuzz or reject message from patch. If you do see such messages -anyway, then there's a high risk that either your local source tree or the -patch file is corrupted in some way. In that case you should probably try -re-downloading the patch and if things are still not OK then you'd be advised -to start with a fresh tree downloaded in full from kernel.org. - -Let's look a bit more at some of the messages patch can produce. - -If patch stops and presents a ``File to patch:`` prompt, then patch could not -find a file to be patched. Most likely you forgot to specify -p1 or you are -in the wrong directory. Less often, you'll find patches that need to be -applied with ``-p0`` instead of ``-p1`` (reading the patch file should reveal if -this is the case -- if so, then this is an error by the person who created -the patch but is not fatal). - -If you get ``Hunk #2 succeeded at 1887 with fuzz 2 (offset 7 lines).`` or a -message similar to that, then it means that patch had to adjust the location -of the change (in this example it needed to move 7 lines from where it -expected to make the change to make it fit). - -The resulting file may or may not be OK, depending on the reason the file -was different than expected. - -This often happens if you try to apply a patch that was generated against a -different kernel version than the one you are trying to patch. - -If you get a message like ``Hunk #3 FAILED at 2387.``, then it means that the -patch could not be applied correctly and the patch program was unable to -fuzz its way through. This will generate a ``.rej`` file with the change that -caused the patch to fail and also a ``.orig`` file showing you the original -content that couldn't be changed. - -If you get ``Reversed (or previously applied) patch detected! Assume -R? [n]`` -then patch detected that the change contained in the patch seems to have -already been made. - -If you actually did apply this patch previously and you just re-applied it -in error, then just say [n]o and abort this patch. If you applied this patch -previously and actually intended to revert it, but forgot to specify -R, -then you can say [**y**]es here to make patch revert it for you. - -This can also happen if the creator of the patch reversed the source and -destination directories when creating the patch, and in that case reverting -the patch will in fact apply it. - -A message similar to ``patch: **** unexpected end of file in patch`` or -``patch unexpectedly ends in middle of line`` means that patch could make no -sense of the file you fed to it. Either your download is broken, you tried to -feed patch a compressed patch file without uncompressing it first, or the patch -file that you are using has been mangled by a mail client or mail transfer -agent along the way somewhere, e.g., by splitting a long line into two lines. -Often these warnings can easily be fixed by joining (concatenating) the -two lines that had been split. - -As I already mentioned above, these errors should never happen if you apply -a patch from kernel.org to the correct version of an unmodified source tree. -So if you get these errors with kernel.org patches then you should probably -assume that either your patch file or your tree is broken and I'd advise you -to start over with a fresh download of a full kernel tree and the patch you -wish to apply. - - -Are there any alternatives to ``patch``? -======================================== - - -Yes there are alternatives. - -You can use the ``interdiff`` program (http://cyberelk.net/tim/patchutils/) to -generate a patch representing the differences between two patches and then -apply the result. - -This will let you move from something like 4.7.2 to 4.7.3 in a single -step. The -z flag to interdiff will even let you feed it patches in gzip or -bzip2 compressed form directly without the use of zcat or bzcat or manual -decompression. - -Here's how you'd go from 4.7.2 to 4.7.3 in a single step:: - - interdiff -z ../patch-4.7.2.gz ../patch-4.7.3.gz | patch -p1 - -Although interdiff may save you a step or two you are generally advised to -do the additional steps since interdiff can get things wrong in some cases. - -Another alternative is ``ketchup``, which is a python script for automatic -downloading and applying of patches (http://www.selenic.com/ketchup/). - -Other nice tools are diffstat, which shows a summary of changes made by a -patch; lsdiff, which displays a short listing of affected files in a patch -file, along with (optionally) the line numbers of the start of each patch; -and grepdiff, which displays a list of the files modified by a patch where -the patch contains a given regular expression. - - -Where can I download the patches? -================================= - -The patches are available at http://kernel.org/ -Most recent patches are linked from the front page, but they also have -specific homes. - -The 4.x.y (-stable) and 4.x patches live at - - ftp://ftp.kernel.org/pub/linux/kernel/v4.x/ - -The -rc patches live at - - ftp://ftp.kernel.org/pub/linux/kernel/v4.x/testing/ - -In place of ``ftp.kernel.org`` you can use ``ftp.cc.kernel.org``, where cc is a -country code. This way you'll be downloading from a mirror site that's most -likely geographically closer to you, resulting in faster downloads for you, -less bandwidth used globally and less load on the main kernel.org servers -- -these are good things, so do use mirrors when possible. - - -The 4.x kernels -=============== - -These are the base stable releases released by Linus. The highest numbered -release is the most recent. - -If regressions or other serious flaws are found, then a -stable fix patch -will be released (see below) on top of this base. Once a new 4.x base -kernel is released, a patch is made available that is a delta between the -previous 4.x kernel and the new one. - -To apply a patch moving from 4.6 to 4.7, you'd do the following (note -that such patches do **NOT** apply on top of 4.x.y kernels but on top of the -base 4.x kernel -- if you need to move from 4.x.y to 4.x+1 you need to -first revert the 4.x.y patch). - -Here are some examples:: - - # moving from 4.6 to 4.7 - - $ cd ~/linux-4.6 # change to kernel source dir - $ patch -p1 < ../patch-4.7 # apply the 4.7 patch - $ cd .. - $ mv linux-4.6 linux-4.7 # rename source dir - - # moving from 4.6.1 to 4.7 - - $ cd ~/linux-4.6.1 # change to kernel source dir - $ patch -p1 -R < ../patch-4.6.1 # revert the 4.6.1 patch - # source dir is now 4.6 - $ patch -p1 < ../patch-4.7 # apply new 4.7 patch - $ cd .. - $ mv linux-4.6.1 linux-4.7 # rename source dir - - -The 4.x.y kernels -================= - -Kernels with 3-digit versions are -stable kernels. They contain small(ish) -critical fixes for security problems or significant regressions discovered -in a given 4.x kernel. - -This is the recommended branch for users who want the most recent stable -kernel and are not interested in helping test development/experimental -versions. - -If no 4.x.y kernel is available, then the highest numbered 4.x kernel is -the current stable kernel. - -.. note:: - - The -stable team usually do make incremental patches available as well - as patches against the latest mainline release, but I only cover the - non-incremental ones below. The incremental ones can be found at - ftp://ftp.kernel.org/pub/linux/kernel/v4.x/incr/ - -These patches are not incremental, meaning that for example the 4.7.3 -patch does not apply on top of the 4.7.2 kernel source, but rather on top -of the base 4.7 kernel source. - -So, in order to apply the 4.7.3 patch to your existing 4.7.2 kernel -source you have to first back out the 4.7.2 patch (so you are left with a -base 4.7 kernel source) and then apply the new 4.7.3 patch. - -Here's a small example:: - - $ cd ~/linux-4.7.2 # change to the kernel source dir - $ patch -p1 -R < ../patch-4.7.2 # revert the 4.7.2 patch - $ patch -p1 < ../patch-4.7.3 # apply the new 4.7.3 patch - $ cd .. - $ mv linux-4.7.2 linux-4.7.3 # rename the kernel source dir - -The -rc kernels -=============== - -These are release-candidate kernels. These are development kernels released -by Linus whenever he deems the current git (the kernel's source management -tool) tree to be in a reasonably sane state adequate for testing. - -These kernels are not stable and you should expect occasional breakage if -you intend to run them. This is however the most stable of the main -development branches and is also what will eventually turn into the next -stable kernel, so it is important that it be tested by as many people as -possible. - -This is a good branch to run for people who want to help out testing -development kernels but do not want to run some of the really experimental -stuff (such people should see the sections about -git and -mm kernels below). - -The -rc patches are not incremental, they apply to a base 4.x kernel, just -like the 4.x.y patches described above. The kernel version before the -rcN -suffix denotes the version of the kernel that this -rc kernel will eventually -turn into. - -So, 4.8-rc5 means that this is the fifth release candidate for the 4.8 -kernel and the patch should be applied on top of the 4.7 kernel source. - -Here are 3 examples of how to apply these patches:: - - # first an example of moving from 4.7 to 4.8-rc3 - - $ cd ~/linux-4.7 # change to the 4.7 source dir - $ patch -p1 < ../patch-4.8-rc3 # apply the 4.8-rc3 patch - $ cd .. - $ mv linux-4.7 linux-4.8-rc3 # rename the source dir - - # now let's move from 4.8-rc3 to 4.8-rc5 - - $ cd ~/linux-4.8-rc3 # change to the 4.8-rc3 dir - $ patch -p1 -R < ../patch-4.8-rc3 # revert the 4.8-rc3 patch - $ patch -p1 < ../patch-4.8-rc5 # apply the new 4.8-rc5 patch - $ cd .. - $ mv linux-4.8-rc3 linux-4.8-rc5 # rename the source dir - - # finally let's try and move from 4.7.3 to 4.8-rc5 - - $ cd ~/linux-4.7.3 # change to the kernel source dir - $ patch -p1 -R < ../patch-4.7.3 # revert the 4.7.3 patch - $ patch -p1 < ../patch-4.8-rc5 # apply new 4.8-rc5 patch - $ cd .. - $ mv linux-4.7.3 linux-4.8-rc5 # rename the kernel source dir - - -The -git kernels -================ - -These are daily snapshots of Linus' kernel tree (managed in a git -repository, hence the name). - -These patches are usually released daily and represent the current state of -Linus's tree. They are more experimental than -rc kernels since they are -generated automatically without even a cursory glance to see if they are -sane. - --git patches are not incremental and apply either to a base 4.x kernel or -a base 4.x-rc kernel -- you can see which from their name. -A patch named 4.7-git1 applies to the 4.7 kernel source and a patch -named 4.8-rc3-git2 applies to the source of the 4.8-rc3 kernel. - -Here are some examples of how to apply these patches:: - - # moving from 4.7 to 4.7-git1 - - $ cd ~/linux-4.7 # change to the kernel source dir - $ patch -p1 < ../patch-4.7-git1 # apply the 4.7-git1 patch - $ cd .. - $ mv linux-4.7 linux-4.7-git1 # rename the kernel source dir - - # moving from 4.7-git1 to 4.8-rc2-git3 - - $ cd ~/linux-4.7-git1 # change to the kernel source dir - $ patch -p1 -R < ../patch-4.7-git1 # revert the 4.7-git1 patch - # we now have a 4.7 kernel - $ patch -p1 < ../patch-4.8-rc2 # apply the 4.8-rc2 patch - # the kernel is now 4.8-rc2 - $ patch -p1 < ../patch-4.8-rc2-git3 # apply the 4.8-rc2-git3 patch - # the kernel is now 4.8-rc2-git3 - $ cd .. - $ mv linux-4.7-git1 linux-4.8-rc2-git3 # rename source dir - - -The -mm patches and the linux-next tree -======================================= - -The -mm patches are experimental patches released by Andrew Morton. - -In the past, -mm tree were used to also test subsystem patches, but this -function is now done via the -`linux-next ` -tree. The Subsystem maintainers push their patches first to linux-next, -and, during the merge window, sends them directly to Linus. - -The -mm patches serve as a sort of proving ground for new features and other -experimental patches that aren't merged via a subsystem tree. -Once such patches has proved its worth in -mm for a while Andrew pushes -it on to Linus for inclusion in mainline. - -The linux-next tree is daily updated, and includes the -mm patches. -Both are in constant flux and contains many experimental features, a -lot of debugging patches not appropriate for mainline etc., and is the most -experimental of the branches described in this document. - -These patches are not appropriate for use on systems that are supposed to be -stable and they are more risky to run than any of the other branches (make -sure you have up-to-date backups -- that goes for any experimental kernel but -even more so for -mm patches or using a Kernel from the linux-next tree). - -Testing of -mm patches and linux-next is greatly appreciated since the whole -point of those are to weed out regressions, crashes, data corruption bugs, -build breakage (and any other bug in general) before changes are merged into -the more stable mainline Linus tree. - -But testers of -mm and linux-next should be aware that breakages are -more common than in any other tree. - - -This concludes this list of explanations of the various kernel trees. -I hope you are now clear on how to apply the various patches and help testing -the kernel. - -Thank you's to Randy Dunlap, Rolf Eike Beer, Linus Torvalds, Bodo Eggert, -Johannes Stezenbach, Grant Coady, Pavel Machek and others that I may have -forgotten for their reviews and contributions to this document. - diff --git a/Documentation/email-clients.txt b/Documentation/email-clients.txt deleted file mode 100644 index ac892b30815e..000000000000 --- a/Documentation/email-clients.txt +++ /dev/null @@ -1,319 +0,0 @@ -.. _email_clients: - -Email clients info for Linux -============================ - -Git ---- - -These days most developers use ``git send-email`` instead of regular -email clients. The man page for this is quite good. On the receiving -end, maintainers use ``git am`` to apply the patches. - -If you are new to ``git`` then send your first patch to yourself. Save it -as raw text including all the headers. Run ``git am raw_email.txt`` and -then review the changelog with ``git log``. When that works then send -the patch to the appropriate mailing list(s). - -General Preferences -------------------- - -Patches for the Linux kernel are submitted via email, preferably as -inline text in the body of the email. Some maintainers accept -attachments, but then the attachments should have content-type -``text/plain``. However, attachments are generally frowned upon because -it makes quoting portions of the patch more difficult in the patch -review process. - -Email clients that are used for Linux kernel patches should send the -patch text untouched. For example, they should not modify or delete tabs -or spaces, even at the beginning or end of lines. - -Don't send patches with ``format=flowed``. This can cause unexpected -and unwanted line breaks. - -Don't let your email client do automatic word wrapping for you. -This can also corrupt your patch. - -Email clients should not modify the character set encoding of the text. -Emailed patches should be in ASCII or UTF-8 encoding only. -If you configure your email client to send emails with UTF-8 encoding, -you avoid some possible charset problems. - -Email clients should generate and maintain References: or In-Reply-To: -headers so that mail threading is not broken. - -Copy-and-paste (or cut-and-paste) usually does not work for patches -because tabs are converted to spaces. Using xclipboard, xclip, and/or -xcutsel may work, but it's best to test this for yourself or just avoid -copy-and-paste. - -Don't use PGP/GPG signatures in mail that contains patches. -This breaks many scripts that read and apply the patches. -(This should be fixable.) - -It's a good idea to send a patch to yourself, save the received message, -and successfully apply it with 'patch' before sending patches to Linux -mailing lists. - - -Some email client (MUA) hints ------------------------------ - -Here are some specific MUA configuration hints for editing and sending -patches for the Linux kernel. These are not meant to be complete -software package configuration summaries. - - -Legend: - -- TUI = text-based user interface -- GUI = graphical user interface - -Alpine (TUI) -************ - -Config options: - -In the :menuselection:`Sending Preferences` section: - -- :menuselection:`Do Not Send Flowed Text` must be ``enabled`` -- :menuselection:`Strip Whitespace Before Sending` must be ``disabled`` - -When composing the message, the cursor should be placed where the patch -should appear, and then pressing :kbd:`CTRL-R` let you specify the patch file -to insert into the message. - -Claws Mail (GUI) -**************** - -Works. Some people use this successfully for patches. - -To insert a patch use :menuselection:`Message-->Insert` File (:kbd:`CTRL-I`) -or an external editor. - -If the inserted patch has to be edited in the Claws composition window -"Auto wrapping" in -:menuselection:`Configuration-->Preferences-->Compose-->Wrapping` should be -disabled. - -Evolution (GUI) -*************** - -Some people use this successfully for patches. - -When composing mail select: Preformat - from :menuselection:`Format-->Paragraph Style-->Preformatted` (:kbd:`CTRL-7`) - or the toolbar - -Then use: -:menuselection:`Insert-->Text File...` (:kbd:`ALT-N x`) -to insert the patch. - -You can also ``diff -Nru old.c new.c | xclip``, select -:menuselection:`Preformat`, then paste with the middle button. - -Kmail (GUI) -*********** - -Some people use Kmail successfully for patches. - -The default setting of not composing in HTML is appropriate; do not -enable it. - -When composing an email, under options, uncheck "word wrap". The only -disadvantage is any text you type in the email will not be word-wrapped -so you will have to manually word wrap text before the patch. The easiest -way around this is to compose your email with word wrap enabled, then save -it as a draft. Once you pull it up again from your drafts it is now hard -word-wrapped and you can uncheck "word wrap" without losing the existing -wrapping. - -At the bottom of your email, put the commonly-used patch delimiter before -inserting your patch: three hyphens (``---``). - -Then from the :menuselection:`Message` menu item, select insert file and -choose your patch. -As an added bonus you can customise the message creation toolbar menu -and put the :menuselection:`insert file` icon there. - -Make the composer window wide enough so that no lines wrap. As of -KMail 1.13.5 (KDE 4.5.4), KMail will apply word wrapping when sending -the email if the lines wrap in the composer window. Having word wrapping -disabled in the Options menu isn't enough. Thus, if your patch has very -long lines, you must make the composer window very wide before sending -the email. See: https://bugs.kde.org/show_bug.cgi?id=174034 - -You can safely GPG sign attachments, but inlined text is preferred for -patches so do not GPG sign them. Signing patches that have been inserted -as inlined text will make them tricky to extract from their 7-bit encoding. - -If you absolutely must send patches as attachments instead of inlining -them as text, right click on the attachment and select properties, and -highlight :menuselection:`Suggest automatic display` to make the attachment -inlined to make it more viewable. - -When saving patches that are sent as inlined text, select the email that -contains the patch from the message list pane, right click and select -:menuselection:`save as`. You can use the whole email unmodified as a patch -if it was properly composed. There is no option currently to save the email -when you are actually viewing it in its own window -- there has been a request -filed at kmail's bugzilla and hopefully this will be addressed. Emails are -saved as read-write for user only so you will have to chmod them to make them -group and world readable if you copy them elsewhere. - -Lotus Notes (GUI) -***************** - -Run away from it. - -Mutt (TUI) -********** - -Plenty of Linux developers use ``mutt``, so it must work pretty well. - -Mutt doesn't come with an editor, so whatever editor you use should be -used in a way that there are no automatic linebreaks. Most editors have -an :menuselection:`insert file` option that inserts the contents of a file -unaltered. - -To use ``vim`` with mutt:: - - set editor="vi" - -If using xclip, type the command:: - - :set paste - -before middle button or shift-insert or use:: - - :r filename - -if you want to include the patch inline. -(a)ttach works fine without ``set paste``. - -You can also generate patches with ``git format-patch`` and then use Mutt -to send them:: - - $ mutt -H 0001-some-bug-fix.patch - -Config options: - -It should work with default settings. -However, it's a good idea to set the ``send_charset`` to:: - - set send_charset="us-ascii:utf-8" - -Mutt is highly customizable. Here is a minimum configuration to start -using Mutt to send patches through Gmail:: - - # .muttrc - # ================ IMAP ==================== - set imap_user = 'yourusername@gmail.com' - set imap_pass = 'yourpassword' - set spoolfile = imaps://imap.gmail.com/INBOX - set folder = imaps://imap.gmail.com/ - set record="imaps://imap.gmail.com/[Gmail]/Sent Mail" - set postponed="imaps://imap.gmail.com/[Gmail]/Drafts" - set mbox="imaps://imap.gmail.com/[Gmail]/All Mail" - - # ================ SMTP ==================== - set smtp_url = "smtp://username@smtp.gmail.com:587/" - set smtp_pass = $imap_pass - set ssl_force_tls = yes # Require encrypted connection - - # ================ Composition ==================== - set editor = `echo \$EDITOR` - set edit_headers = yes # See the headers when editing - set charset = UTF-8 # value of $LANG; also fallback for send_charset - # Sender, email address, and sign-off line must match - unset use_domain # because joe@localhost is just embarrassing - set realname = "YOUR NAME" - set from = "username@gmail.com" - set use_from = yes - -The Mutt docs have lots more information: - - http://dev.mutt.org/trac/wiki/UseCases/Gmail - - http://dev.mutt.org/doc/manual.html - -Pine (TUI) -********** - -Pine has had some whitespace truncation issues in the past, but these -should all be fixed now. - -Use alpine (pine's successor) if you can. - -Config options: - -- ``quell-flowed-text`` is needed for recent versions -- the ``no-strip-whitespace-before-send`` option is needed - - -Sylpheed (GUI) -************** - -- Works well for inlining text (or using attachments). -- Allows use of an external editor. -- Is slow on large folders. -- Won't do TLS SMTP auth over a non-SSL connection. -- Has a helpful ruler bar in the compose window. -- Adding addresses to address book doesn't understand the display name - properly. - -Thunderbird (GUI) -***************** - -Thunderbird is an Outlook clone that likes to mangle text, but there are ways -to coerce it into behaving. - -- Allow use of an external editor: - The easiest thing to do with Thunderbird and patches is to use an - "external editor" extension and then just use your favorite ``$EDITOR`` - for reading/merging patches into the body text. To do this, download - and install the extension, then add a button for it using - :menuselection:`View-->Toolbars-->Customize...` and finally just click on it - when in the :menuselection:`Compose` dialog. - - Please note that "external editor" requires that your editor must not - fork, or in other words, the editor must not return before closing. - You may have to pass additional flags or change the settings of your - editor. Most notably if you are using gvim then you must pass the -f - option to gvim by putting ``/usr/bin/gvim -f`` (if the binary is in - ``/usr/bin``) to the text editor field in :menuselection:`external editor` - settings. If you are using some other editor then please read its manual - to find out how to do this. - -To beat some sense out of the internal editor, do this: - -- Edit your Thunderbird config settings so that it won't use ``format=flowed``. - Go to :menuselection:`edit-->preferences-->advanced-->config editor` to bring up - the thunderbird's registry editor. - -- Set ``mailnews.send_plaintext_flowed`` to ``false`` - -- Set ``mailnews.wraplength`` from ``72`` to ``0`` - -- :menuselection:`View-->Message Body As-->Plain Text` - -- :menuselection:`View-->Character Encoding-->Unicode (UTF-8)` - -TkRat (GUI) -*********** - -Works. Use "Insert file..." or external editor. - -Gmail (Web GUI) -*************** - -Does not work for sending patches. - -Gmail web client converts tabs to spaces automatically. - -At the same time it wraps lines every 78 chars with CRLF style line breaks -although tab2space problem can be solved with external editor. - -Another problem is that Gmail will base64-encode any message that has a -non-ASCII character. That includes things like European names. diff --git a/Documentation/kernel-docs.txt b/Documentation/kernel-docs.txt deleted file mode 100644 index 05a7857a4a83..000000000000 --- a/Documentation/kernel-docs.txt +++ /dev/null @@ -1,652 +0,0 @@ -.. _kernel_docs: - -Index of Documentation for People Interested in Writing and/or Understanding the Linux Kernel -============================================================================================= - - Juan-Mariano de Goyeneche - -The need for a document like this one became apparent in the -linux-kernel mailing list as the same questions, asking for pointers -to information, appeared again and again. - -Fortunately, as more and more people get to GNU/Linux, more and more -get interested in the Kernel. But reading the sources is not always -enough. It is easy to understand the code, but miss the concepts, the -philosophy and design decisions behind this code. - -Unfortunately, not many documents are available for beginners to -start. And, even if they exist, there was no "well-known" place which -kept track of them. These lines try to cover this lack. All documents -available on line known by the author are listed, while some reference -books are also mentioned. - -PLEASE, if you know any paper not listed here or write a new document, -send me an e-mail, and I'll include a reference to it here. Any -corrections, ideas or comments are also welcomed. - -The papers that follow are listed in no particular order. All are -cataloged with the following fields: the document's "Title", the -"Author"/s, the "URL" where they can be found, some "Keywords" helpful -when searching for specific topics, and a brief "Description" of the -Document. - -Enjoy! - -.. note:: - - The documents on each section of this document are ordered by its - published date, from the newest to the oldest. - -Docs at the Linux Kernel tree ------------------------------ - -The DocBook books should be built with ``make {htmldocs | psdocs | pdfdocs}``. -The Sphinx books should be built with ``make {htmldocs | pdfdocs | epubdocs}``. - - * Name: **linux/Documentation** - - :Author: Many. - :Location: Documentation/ - :Keywords: text files, Sphinx, DocBook. - :Description: Documentation that comes with the kernel sources, - inside the Documentation directory. Some pages from this document - (including this document itself) have been moved there, and might - be more up to date than the web version. - - * Title: **The Kernel Hacking HOWTO** - - :Author: Various Talented People, and Rusty. - :Location: Documentation/DocBook/kernel-hacking.tmpl - :Keywords: HOWTO, kernel contexts, deadlock, locking, modules, - symbols, return conventions. - :Description: From the Introduction: "Please understand that I - never wanted to write this document, being grossly underqualified, - but I always wanted to read it, and this was the only way. I - simply explain some best practices, and give reading entry-points - into the kernel sources. I avoid implementation details: that's - what the code is for, and I ignore whole tracts of useful - routines. This document assumes familiarity with C, and an - understanding of what the kernel is, and how it is used. It was - originally written for the 2.3 kernels, but nearly all of it - applies to 2.2 too; 2.0 is slightly different". - - * Title: **Linux Kernel Locking HOWTO** - - :Author: Various Talented People, and Rusty. - :Location: Documentation/DocBook/kernel-locking.tmpl - :Keywords: locks, locking, spinlock, semaphore, atomic, race - condition, bottom halves, tasklets, softirqs. - :Description: The title says it all: document describing the - locking system in the Linux Kernel either in uniprocessor or SMP - systems. - :Notes: "It was originally written for the later (>2.3.47) 2.3 - kernels, but most of it applies to 2.2 too; 2.0 is slightly - different". Freely redistributable under the conditions of the GNU - General Public License. - -On-line docs ------------- - - * Title: **Linux Kernel Mailing List Glossary** - - :Author: various - :URL: http://kernelnewbies.org/glossary/ - :Date: rolling version - :Keywords: glossary, terms, linux-kernel. - :Description: From the introduction: "This glossary is intended as - a brief description of some of the acronyms and terms you may hear - during discussion of the Linux kernel". - - * Title: **Tracing the Way of Data in a TCP Connection through the Linux Kernel** - - :Author: Richard Sailer - :URL: https://archive.org/details/linux_kernel_data_flow_short_paper - :Date: 2016 - :Keywords: Linux Kernel Networking, TCP, tracing, ftrace - :Description: A seminar paper explaining ftrace and how to use it for - understanding linux kernel internals, - illustrated at tracing the way of a TCP packet through the kernel. - :Abstract: *This short paper outlines the usage of ftrace a tracing framework - as a tool to understand a running Linux system. - Having obtained a trace-log a kernel hacker can read and understand - source code more determined and with context. - In a detailed example this approach is demonstrated in tracing - and the way of data in a TCP Connection through the kernel. - Finally this trace-log is used as base for more a exact conceptual - exploration and description of the Linux TCP/IP implementation.* - - * Title: **On submitting kernel Patches** - - :Author: Andi Kleen - :URL: http://halobates.de/on-submitting-kernel-patches.pdf - :Date: 2008 - :Keywords: patches, review process, types of submissions, basic rules, case studies - :Description: This paper gives several experience values on what types of patches - there are and how likley they get merged. - :Abstract: - [...]. This paper examines some common problems for - submitting larger changes and some strategies to avoid problems. - - * Title: **Overview of the Virtual File System** - - :Author: Richard Gooch. - :URL: http://www.mjmwired.net/kernel/Documentation/filesystems/vfs.txt - :Date: 2007 - :Keywords: VFS, File System, mounting filesystems, opening files, - dentries, dcache. - :Description: Brief introduction to the Linux Virtual File System. - What is it, how it works, operations taken when opening a file or - mounting a file system and description of important data - structures explaining the purpose of each of their entries. - - * Title: **Linux Device Drivers, Third Edition** - - :Author: Jonathan Corbet, Alessandro Rubini, Greg Kroah-Hartman - :URL: http://lwn.net/Kernel/LDD3/ - :Date: 2005 - :Description: A 600-page book covering the (2.6.10) driver - programming API and kernel hacking in general. Available under the - Creative Commons Attribution-ShareAlike 2.0 license. - :note: You can also :ref:`purchase a copy from O'Reilly or elsewhere `. - - * Title: **Writing an ALSA Driver** - - :Author: Takashi Iwai - :URL: http://www.alsa-project.org/~iwai/writing-an-alsa-driver/index.html - :Date: 2005 - :Keywords: ALSA, sound, soundcard, driver, lowlevel, hardware. - :Description: Advanced Linux Sound Architecture for developers, - both at kernel and user-level sides. ALSA is the Linux kernel - sound architecture in the 2.6 kernel version. - - * Title: **Linux PCMCIA Programmer's Guide** - - :Author: David Hinds. - :URL: http://pcmcia-cs.sourceforge.net/ftp/doc/PCMCIA-PROG.html - :Date: 2003 - :Keywords: PCMCIA. - :Description: "This document describes how to write kernel device - drivers for the Linux PCMCIA Card Services interface. It also - describes how to write user-mode utilities for communicating with - Card Services. - - * Title: **Linux Kernel Module Programming Guide** - - :Author: Ori Pomerantz. - :URL: http://tldp.org/LDP/lkmpg/2.6/html/index.html - :Date: 2001 - :Keywords: modules, GPL book, /proc, ioctls, system calls, - interrupt handlers . - :Description: Very nice 92 pages GPL book on the topic of modules - programming. Lots of examples. - - * Title: **Global spinlock list and usage** - - :Author: Rick Lindsley. - :URL: http://lse.sourceforge.net/lockhier/global-spin-lock - :Date: 2001 - :Keywords: spinlock. - :Description: This is an attempt to document both the existence and - usage of the spinlocks in the Linux 2.4.5 kernel. Comprehensive - list of spinlocks showing when they are used, which functions - access them, how each lock is acquired, under what conditions it - is held, whether interrupts can occur or not while it is held... - - * Title: **A Linux vm README** - - :Author: Kanoj Sarcar. - :URL: http://kos.enix.org/pub/linux-vmm.html - :Date: 2001 - :Keywords: virtual memory, mm, pgd, vma, page, page flags, page - cache, swap cache, kswapd. - :Description: Telegraphic, short descriptions and definitions - relating the Linux virtual memory implementation. - - * Title: **Video4linux Drivers, Part 1: Video-Capture Device** - - :Author: Alan Cox. - :URL: http://www.linux-mag.com/id/406 - :Date: 2000 - :Keywords: video4linux, driver, video capture, capture devices, - camera driver. - :Description: The title says it all. - - * Title: **Video4linux Drivers, Part 2: Video-capture Devices** - - :Author: Alan Cox. - :URL: http://www.linux-mag.com/id/429 - :Date: 2000 - :Keywords: video4linux, driver, video capture, capture devices, - camera driver, control, query capabilities, capability, facility. - :Description: The title says it all. - - * Title: **Linux IP Networking. A Guide to the Implementation and Modification of the Linux Protocol Stack.** - - :Author: Glenn Herrin. - :URL: http://www.cs.unh.edu/cnrg/gherrin - :Date: 2000 - :Keywords: network, networking, protocol, IP, UDP, TCP, connection, - socket, receiving, transmitting, forwarding, routing, packets, - modules, /proc, sk_buff, FIB, tags. - :Description: Excellent paper devoted to the Linux IP Networking, - explaining anything from the kernel's to the user space - configuration tools' code. Very good to get a general overview of - the kernel networking implementation and understand all steps - packets follow from the time they are received at the network - device till they are delivered to applications. The studied kernel - code is from 2.2.14 version. Provides code for a working packet - dropper example. - - * Title: **How To Make Sure Your Driver Will Work On The Power Macintosh** - - :Author: Paul Mackerras. - :URL: http://www.linux-mag.com/id/261 - :Date: 1999 - :Keywords: Mac, Power Macintosh, porting, drivers, compatibility. - :Description: The title says it all. - - * Title: **An Introduction to SCSI Drivers** - - :Author: Alan Cox. - :URL: http://www.linux-mag.com/id/284 - :Date: 1999 - :Keywords: SCSI, device, driver. - :Description: The title says it all. - - * Title: **Advanced SCSI Drivers And Other Tales** - - :Author: Alan Cox. - :URL: http://www.linux-mag.com/id/307 - :Date: 1999 - :Keywords: SCSI, device, driver, advanced. - :Description: The title says it all. - - * Title: **Writing Linux Mouse Drivers** - - :Author: Alan Cox. - :URL: http://www.linux-mag.com/id/330 - :Date: 1999 - :Keywords: mouse, driver, gpm. - :Description: The title says it all. - - * Title: **More on Mouse Drivers** - - :Author: Alan Cox. - :URL: http://www.linux-mag.com/id/356 - :Date: 1999 - :Keywords: mouse, driver, gpm, races, asynchronous I/O. - :Description: The title still says it all. - - * Title: **Writing Video4linux Radio Driver** - - :Author: Alan Cox. - :URL: http://www.linux-mag.com/id/381 - :Date: 1999 - :Keywords: video4linux, driver, radio, radio devices. - :Description: The title says it all. - - * Title: **I/O Event Handling Under Linux** - - :Author: Richard Gooch. - :URL: http://web.mit.edu/~yandros/doc/io-events.html - :Date: 1999 - :Keywords: IO, I/O, select(2), poll(2), FDs, aio_read(2), readiness - event queues. - :Description: From the Introduction: "I/O Event handling is about - how your Operating System allows you to manage a large number of - open files (file descriptors in UNIX/POSIX, or FDs) in your - application. You want the OS to notify you when FDs become active - (have data ready to be read or are ready for writing). Ideally you - want a mechanism that is scalable. This means a large number of - inactive FDs cost very little in memory and CPU time to manage". - - * Title: **(nearly) Complete Linux Loadable Kernel Modules. The definitive guide for hackers, virus coders and system administrators.** - - :Author: pragmatic/THC. - :URL: http://packetstormsecurity.org/docs/hack/LKM_HACKING.html - :Date: 1999 - :Keywords: syscalls, intercept, hide, abuse, symbol table. - :Description: Interesting paper on how to abuse the Linux kernel in - order to intercept and modify syscalls, make - files/directories/processes invisible, become root, hijack ttys, - write kernel modules based virus... and solutions for admins to - avoid all those abuses. - :Notes: For 2.0.x kernels. Gives guidances to port it to 2.2.x - kernels. - - * Name: **Linux Virtual File System** - - :Author: Peter J. Braam. - :URL: http://www.coda.cs.cmu.edu/doc/talks/linuxvfs/ - :Date: 1998 - :Keywords: slides, VFS, inode, superblock, dentry, dcache. - :Description: Set of slides, presumably from a presentation on the - Linux VFS layer. Covers version 2.1.x, with dentries and the - dcache. - - * Title: **The Venus kernel interface** - - :Author: Peter J. Braam. - :URL: http://www.coda.cs.cmu.edu/doc/html/kernel-venus-protocol.html - :Date: 1998 - :Keywords: coda, filesystem, venus, cache manager. - :Description: "This document describes the communication between - Venus and kernel level file system code needed for the operation - of the Coda filesystem. This version document is meant to describe - the current interface (version 1.0) as well as improvements we - envisage". - - * Title: **Design and Implementation of the Second Extended Filesystem** - - :Author: Rémy Card, Theodore Ts'o, Stephen Tweedie. - :URL: http://web.mit.edu/tytso/www/linux/ext2intro.html - :Date: 1998 - :Keywords: ext2, linux fs history, inode, directory, link, devices, - VFS, physical structure, performance, benchmarks, ext2fs library, - ext2fs tools, e2fsck. - :Description: Paper written by three of the top ext2 hackers. - Covers Linux filesystems history, ext2 motivation, ext2 features, - design, physical structure on disk, performance, benchmarks, - e2fsck's passes description... A must read! - :Notes: This paper was first published in the Proceedings of the - First Dutch International Symposium on Linux, ISBN 90-367-0385-9. - - * Title: **The Linux RAID-1, 4, 5 Code** - - :Author: Ingo Molnar, Gadi Oxman and Miguel de Icaza. - :URL: http://www.linuxjournal.com/article.php?sid=2391 - :Date: 1997 - :Keywords: RAID, MD driver. - :Description: Linux Journal Kernel Korner article. Here is its - :Abstract: *A description of the implementation of the RAID-1, - RAID-4 and RAID-5 personalities of the MD device driver in the - Linux kernel, providing users with high performance and reliable, - secondary-storage capability using software*. - - * Title: **Linux Kernel Hackers' Guide** - - :Author: Michael K. Johnson. - :URL: http://www.tldp.org/LDP/khg/HyperNews/get/khg.html - :Date: 1997 - :Keywords: device drivers, files, VFS, kernel interface, character vs - block devices, hardware interrupts, scsi, DMA, access to user memory, - memory allocation, timers. - :Description: A guide designed to help you get up to speed on the - concepts that are not intuitevly obvious, and to document the internal - structures of Linux. - - * Title: **Dynamic Kernels: Modularized Device Drivers** - - :Author: Alessandro Rubini. - :URL: http://www.linuxjournal.com/article.php?sid=1219 - :Date: 1996 - :Keywords: device driver, module, loading/unloading modules, - allocating resources. - :Description: Linux Journal Kernel Korner article. Here is its - :Abstract: *This is the first of a series of four articles - co-authored by Alessandro Rubini and Georg Zezchwitz which present - a practical approach to writing Linux device drivers as kernel - loadable modules. This installment presents an introduction to the - topic, preparing the reader to understand next month's - installment*. - - * Title: **Dynamic Kernels: Discovery** - - :Author: Alessandro Rubini. - :URL: http://www.linuxjournal.com/article.php?sid=1220 - :Date: 1996 - :Keywords: character driver, init_module, clean_up module, - autodetection, mayor number, minor number, file operations, - open(), close(). - :Description: Linux Journal Kernel Korner article. Here is its - :Abstract: *This article, the second of four, introduces part of - the actual code to create custom module implementing a character - device driver. It describes the code for module initialization and - cleanup, as well as the open() and close() system calls*. - - * Title: **The Devil's in the Details** - - :Author: Georg v. Zezschwitz and Alessandro Rubini. - :URL: http://www.linuxjournal.com/article.php?sid=1221 - :Date: 1996 - :Keywords: read(), write(), select(), ioctl(), blocking/non - blocking mode, interrupt handler. - :Description: Linux Journal Kernel Korner article. Here is its - :Abstract: *This article, the third of four on writing character - device drivers, introduces concepts of reading, writing, and using - ioctl-calls*. - - * Title: **Dissecting Interrupts and Browsing DMA** - - :Author: Alessandro Rubini and Georg v. Zezschwitz. - :URL: http://www.linuxjournal.com/article.php?sid=1222 - :Date: 1996 - :Keywords: interrupts, irqs, DMA, bottom halves, task queues. - :Description: Linux Journal Kernel Korner article. Here is its - :Abstract: *This is the fourth in a series of articles about - writing character device drivers as loadable kernel modules. This - month, we further investigate the field of interrupt handling. - Though it is conceptually simple, practical limitations and - constraints make this an ''interesting'' part of device driver - writing, and several different facilities have been provided for - different situations. We also investigate the complex topic of - DMA*. - - * Title: **Device Drivers Concluded** - - :Author: Georg v. Zezschwitz. - :URL: http://www.linuxjournal.com/article.php?sid=1287 - :Date: 1996 - :Keywords: address spaces, pages, pagination, page management, - demand loading, swapping, memory protection, memory mapping, mmap, - virtual memory areas (VMAs), vremap, PCI. - :Description: Finally, the above turned out into a five articles - series. This latest one's introduction reads: "This is the last of - five articles about character device drivers. In this final - section, Georg deals with memory mapping devices, beginning with - an overall description of the Linux memory management concepts". - - * Title: **Network Buffers And Memory Management** - - :Author: Alan Cox. - :URL: http://www.linuxjournal.com/article.php?sid=1312 - :Date: 1996 - :Keywords: sk_buffs, network devices, protocol/link layer - variables, network devices flags, transmit, receive, - configuration, multicast. - :Description: Linux Journal Kernel Korner. - :Abstract: *Writing a network device driver for Linux is fundamentally - simple---most of the complexity (other than talking to the - hardware) involves managing network packets in memory*. - - * Title: **Analysis of the Ext2fs structure** - - :Author: Louis-Dominique Dubeau. - :URL: http://teaching.csse.uwa.edu.au/units/CITS2002/fs-ext2/ - :Date: 1994 - :Keywords: ext2, filesystem, ext2fs. - :Description: Description of ext2's blocks, directories, inodes, - bitmaps, invariants... - -Published books ---------------- - - * Title: **Linux Treiber entwickeln** - - :Author: Jürgen Quade, Eva-Katharina Kunst - :Publisher: dpunkt.verlag - :Date: Oct 2015 (4th edition) - :Pages: 688 - :ISBN: 978-3-86490-288-8 - :Note: German. The third edition from 2011 is - much cheaper and still quite up-to-date. - - * Title: **Linux Kernel Networking: Implementation and Theory** - - :Author: Rami Rosen - :Publisher: Apress - :Date: December 22, 2013 - :Pages: 648 - :ISBN: 978-1430261964 - - * Title: **Embedded Linux Primer: A practical Real-World Approach, 2nd Edition** - - :Author: Christopher Hallinan - :Publisher: Pearson - :Date: November, 2010 - :Pages: 656 - :ISBN: 978-0137017836 - - * Title: **Linux Kernel Development, 3rd Edition** - - :Author: Robert Love - :Publisher: Addison-Wesley - :Date: July, 2010 - :Pages: 440 - :ISBN: 978-0672329463 - - * Title: **Essential Linux Device Drivers** - - :Author: Sreekrishnan Venkateswaran - :Published: Prentice Hall - :Date: April, 2008 - :Pages: 744 - :ISBN: 978-0132396554 - -.. _ldd3_published: - - * Title: **Linux Device Drivers, 3rd Edition** - - :Authors: Jonathan Corbet, Alessandro Rubini, and Greg Kroah-Hartman - :Publisher: O'Reilly & Associates - :Date: 2005 - :Pages: 636 - :ISBN: 0-596-00590-3 - :Notes: Further information in - http://www.oreilly.com/catalog/linuxdrive3/ - PDF format, URL: http://lwn.net/Kernel/LDD3/ - - * Title: **Linux Kernel Internals** - - :Author: Michael Beck - :Publisher: Addison-Wesley - :Date: 1997 - :ISBN: 0-201-33143-8 (second edition) - - * Title: **Programmation Linux 2.0 API systeme et fonctionnement du noyau** - - :Author: Remy Card, Eric Dumas, Franck Mevel - :Publisher: Eyrolles - :Date: 1997 - :Pages: 520 - :ISBN: 2-212-08932-5 - :Notes: French - - * Title: **The Design and Implementation of the 4.4 BSD UNIX Operating System** - - :Author: Marshall Kirk McKusick, Keith Bostic, Michael J. Karels, - John S. Quarterman - :Publisher: Addison-Wesley - :Date: 1996 - :ISBN: 0-201-54979-4 - - * Title: **Unix internals -- the new frontiers** - - :Author: Uresh Vahalia - :Publisher: Prentice Hall - :Date: 1996 - :Pages: 600 - :ISBN: 0-13-101908-2 - - * Title: **Programming for the real world - POSIX.4** - - :Author: Bill O. Gallmeister - :Publisher: O'Reilly & Associates, Inc - :Date: 1995 - :Pages: 552 - :ISBN: I-56592-074-0 - :Notes: Though not being directly about Linux, Linux aims to be - POSIX. Good reference. - - * Title: **UNIX Systems for Modern Architectures: Symmetric Multiprocessing and Caching for Kernel Programmers** - - :Author: Curt Schimmel - :Publisher: Addison Wesley - :Date: June, 1994 - :Pages: 432 - :ISBN: 0-201-63338-8 - - * Title: **The Design and Implementation of the 4.3 BSD UNIX Operating System** - - :Author: Samuel J. Leffler, Marshall Kirk McKusick, Michael J - Karels, John S. Quarterman - :Publisher: Addison-Wesley - :Date: 1989 (reprinted with corrections on October, 1990) - :ISBN: 0-201-06196-1 - - * Title: **The Design of the UNIX Operating System** - - :Author: Maurice J. Bach - :Publisher: Prentice Hall - :Date: 1986 - :Pages: 471 - :ISBN: 0-13-201757-1 - -Miscellaneous -------------- - - * Name: **Cross-Referencing Linux** - - :URL: http://lxr.free-electrons.com/ - :Keywords: Browsing source code. - :Description: Another web-based Linux kernel source code browser. - Lots of cross references to variables and functions. You can see - where they are defined and where they are used. - - * Name: **Linux Weekly News** - - :URL: http://lwn.net - :Keywords: latest kernel news. - :Description: The title says it all. There's a fixed kernel section - summarizing developers' work, bug fixes, new features and versions - produced during the week. Published every Thursday. - - * Name: **The home page of Linux-MM** - - :Author: The Linux-MM team. - :URL: http://linux-mm.org/ - :Keywords: memory management, Linux-MM, mm patches, TODO, docs, - mailing list. - :Description: Site devoted to Linux Memory Management development. - Memory related patches, HOWTOs, links, mm developers... Don't miss - it if you are interested in memory management development! - - * Name: **Kernel Newbies IRC Channel and Website** - - :URL: http://www.kernelnewbies.org - :Keywords: IRC, newbies, channel, asking doubts. - :Description: #kernelnewbies on irc.oftc.net. - #kernelnewbies is an IRC network dedicated to the 'newbie' - kernel hacker. The audience mostly consists of people who are - learning about the kernel, working on kernel projects or - professional kernel hackers that want to help less seasoned kernel - people. - #kernelnewbies is on the OFTC IRC Network. - Try irc.oftc.net as your server and then /join #kernelnewbies. - The kernelnewbies website also hosts articles, documents, FAQs... - - * Name: **linux-kernel mailing list archives and search engines** - - :URL: http://vger.kernel.org/vger-lists.html - :URL: http://www.uwsg.indiana.edu/hypermail/linux/kernel/index.html - :URL: http://groups.google.com/group/mlist.linux.kernel - :Keywords: linux-kernel, archives, search. - :Description: Some of the linux-kernel mailing list archivers. If - you have a better/another one, please let me know. - -------- - -Document last updated on Tue 2016-Sep-20 - -This document is based on: - http://www.dit.upm.es/~jmseyas/linux/kernel/hackers-docs.html diff --git a/Documentation/magic-number.txt b/Documentation/magic-number.txt deleted file mode 100644 index c74199f60c6c..000000000000 --- a/Documentation/magic-number.txt +++ /dev/null @@ -1,164 +0,0 @@ -Linux magic numbers -=================== - -This file is a registry of magic numbers which are in use. When you -add a magic number to a structure, you should also add it to this -file, since it is best if the magic numbers used by various structures -are unique. - -It is a **very** good idea to protect kernel data structures with magic -numbers. This allows you to check at run time whether (a) a structure -has been clobbered, or (b) you've passed the wrong structure to a -routine. This last is especially useful --- particularly when you are -passing pointers to structures via a void * pointer. The tty code, -for example, does this frequently to pass driver-specific and line -discipline-specific structures back and forth. - -The way to use magic numbers is to declare then at the beginning of -the structure, like so:: - - struct tty_ldisc { - int magic; - ... - }; - -Please follow this discipline when you are adding future enhancements -to the kernel! It has saved me countless hours of debugging, -especially in the screwy cases where an array has been overrun and -structures following the array have been overwritten. Using this -discipline, these cases get detected quickly and safely. - -Changelog:: - - Theodore Ts'o - 31 Mar 94 - - The magic table is current to Linux 2.1.55. - - Michael Chastain - - 22 Sep 1997 - - Now it should be up to date with Linux 2.1.112. Because - we are in feature freeze time it is very unlikely that - something will change before 2.2.x. The entries are - sorted by number field. - - Krzysztof G. Baranowski - - 29 Jul 1998 - - Updated the magic table to Linux 2.5.45. Right over the feature freeze, - but it is possible that some new magic numbers will sneak into the - kernel before 2.6.x yet. - - Petr Baudis - - 03 Nov 2002 - - Updated the magic table to Linux 2.5.74. - - Fabian Frederick - - 09 Jul 2003 - - -===================== ================ ======================== ========================================== -Magic Name Number Structure File -===================== ================ ======================== ========================================== -PG_MAGIC 'P' pg_{read,write}_hdr ``include/linux/pg.h`` -CMAGIC 0x0111 user ``include/linux/a.out.h`` -MKISS_DRIVER_MAGIC 0x04bf mkiss_channel ``drivers/net/mkiss.h`` -HDLC_MAGIC 0x239e n_hdlc ``drivers/char/n_hdlc.c`` -APM_BIOS_MAGIC 0x4101 apm_user ``arch/x86/kernel/apm_32.c`` -CYCLADES_MAGIC 0x4359 cyclades_port ``include/linux/cyclades.h`` -DB_MAGIC 0x4442 fc_info ``drivers/net/iph5526_novram.c`` -DL_MAGIC 0x444d fc_info ``drivers/net/iph5526_novram.c`` -FASYNC_MAGIC 0x4601 fasync_struct ``include/linux/fs.h`` -FF_MAGIC 0x4646 fc_info ``drivers/net/iph5526_novram.c`` -ISICOM_MAGIC 0x4d54 isi_port ``include/linux/isicom.h`` -PTY_MAGIC 0x5001 ``drivers/char/pty.c`` -PPP_MAGIC 0x5002 ppp ``include/linux/if_pppvar.h`` -SERIAL_MAGIC 0x5301 async_struct ``include/linux/serial.h`` -SSTATE_MAGIC 0x5302 serial_state ``include/linux/serial.h`` -SLIP_MAGIC 0x5302 slip ``drivers/net/slip.h`` -STRIP_MAGIC 0x5303 strip ``drivers/net/strip.c`` -X25_ASY_MAGIC 0x5303 x25_asy ``drivers/net/x25_asy.h`` -SIXPACK_MAGIC 0x5304 sixpack ``drivers/net/hamradio/6pack.h`` -AX25_MAGIC 0x5316 ax_disp ``drivers/net/mkiss.h`` -TTY_MAGIC 0x5401 tty_struct ``include/linux/tty.h`` -MGSL_MAGIC 0x5401 mgsl_info ``drivers/char/synclink.c`` -TTY_DRIVER_MAGIC 0x5402 tty_driver ``include/linux/tty_driver.h`` -MGSLPC_MAGIC 0x5402 mgslpc_info ``drivers/char/pcmcia/synclink_cs.c`` -TTY_LDISC_MAGIC 0x5403 tty_ldisc ``include/linux/tty_ldisc.h`` -USB_SERIAL_MAGIC 0x6702 usb_serial ``drivers/usb/serial/usb-serial.h`` -FULL_DUPLEX_MAGIC 0x6969 ``drivers/net/ethernet/dec/tulip/de2104x.c`` -USB_BLUETOOTH_MAGIC 0x6d02 usb_bluetooth ``drivers/usb/class/bluetty.c`` -RFCOMM_TTY_MAGIC 0x6d02 ``net/bluetooth/rfcomm/tty.c`` -USB_SERIAL_PORT_MAGIC 0x7301 usb_serial_port ``drivers/usb/serial/usb-serial.h`` -CG_MAGIC 0x00090255 ufs_cylinder_group ``include/linux/ufs_fs.h`` -RPORT_MAGIC 0x00525001 r_port ``drivers/char/rocket_int.h`` -LSEMAGIC 0x05091998 lse ``drivers/fc4/fc.c`` -GDTIOCTL_MAGIC 0x06030f07 gdth_iowr_str ``drivers/scsi/gdth_ioctl.h`` -RIEBL_MAGIC 0x09051990 ``drivers/net/atarilance.c`` -NBD_REQUEST_MAGIC 0x12560953 nbd_request ``include/linux/nbd.h`` -RED_MAGIC2 0x170fc2a5 (any) ``mm/slab.c`` -BAYCOM_MAGIC 0x19730510 baycom_state ``drivers/net/baycom_epp.c`` -ISDN_X25IFACE_MAGIC 0x1e75a2b9 isdn_x25iface_proto_data ``drivers/isdn/isdn_x25iface.h`` -ECP_MAGIC 0x21504345 cdkecpsig ``include/linux/cdk.h`` -LSOMAGIC 0x27091997 lso ``drivers/fc4/fc.c`` -LSMAGIC 0x2a3b4d2a ls ``drivers/fc4/fc.c`` -WANPIPE_MAGIC 0x414C4453 sdla_{dump,exec} ``include/linux/wanpipe.h`` -CS_CARD_MAGIC 0x43525553 cs_card ``sound/oss/cs46xx.c`` -LABELCL_MAGIC 0x4857434c labelcl_info_s ``include/asm/ia64/sn/labelcl.h`` -ISDN_ASYNC_MAGIC 0x49344C01 modem_info ``include/linux/isdn.h`` -CTC_ASYNC_MAGIC 0x49344C01 ctc_tty_info ``drivers/s390/net/ctctty.c`` -ISDN_NET_MAGIC 0x49344C02 isdn_net_local_s ``drivers/isdn/i4l/isdn_net_lib.h`` -SAVEKMSG_MAGIC2 0x4B4D5347 savekmsg ``arch/*/amiga/config.c`` -CS_STATE_MAGIC 0x4c4f4749 cs_state ``sound/oss/cs46xx.c`` -SLAB_C_MAGIC 0x4f17a36d kmem_cache ``mm/slab.c`` -COW_MAGIC 0x4f4f4f4d cow_header_v1 ``arch/um/drivers/ubd_user.c`` -I810_CARD_MAGIC 0x5072696E i810_card ``sound/oss/i810_audio.c`` -TRIDENT_CARD_MAGIC 0x5072696E trident_card ``sound/oss/trident.c`` -ROUTER_MAGIC 0x524d4157 wan_device [in ``wanrouter.h`` pre 3.9] -SAVEKMSG_MAGIC1 0x53415645 savekmsg ``arch/*/amiga/config.c`` -GDA_MAGIC 0x58464552 gda ``arch/mips/include/asm/sn/gda.h`` -RED_MAGIC1 0x5a2cf071 (any) ``mm/slab.c`` -EEPROM_MAGIC_VALUE 0x5ab478d2 lanai_dev ``drivers/atm/lanai.c`` -HDLCDRV_MAGIC 0x5ac6e778 hdlcdrv_state ``include/linux/hdlcdrv.h`` -PCXX_MAGIC 0x5c6df104 channel ``drivers/char/pcxx.h`` -KV_MAGIC 0x5f4b565f kernel_vars_s ``arch/mips/include/asm/sn/klkernvars.h`` -I810_STATE_MAGIC 0x63657373 i810_state ``sound/oss/i810_audio.c`` -TRIDENT_STATE_MAGIC 0x63657373 trient_state ``sound/oss/trident.c`` -M3_CARD_MAGIC 0x646e6f50 m3_card ``sound/oss/maestro3.c`` -FW_HEADER_MAGIC 0x65726F66 fw_header ``drivers/atm/fore200e.h`` -SLOT_MAGIC 0x67267321 slot ``drivers/hotplug/cpqphp.h`` -SLOT_MAGIC 0x67267322 slot ``drivers/hotplug/acpiphp.h`` -LO_MAGIC 0x68797548 nbd_device ``include/linux/nbd.h`` -OPROFILE_MAGIC 0x6f70726f super_block ``drivers/oprofile/oprofilefs.h`` -M3_STATE_MAGIC 0x734d724d m3_state ``sound/oss/maestro3.c`` -VMALLOC_MAGIC 0x87654320 snd_alloc_track ``sound/core/memory.c`` -KMALLOC_MAGIC 0x87654321 snd_alloc_track ``sound/core/memory.c`` -PWC_MAGIC 0x89DC10AB pwc_device ``drivers/usb/media/pwc.h`` -NBD_REPLY_MAGIC 0x96744668 nbd_reply ``include/linux/nbd.h`` -ENI155_MAGIC 0xa54b872d midway_eprom ``drivers/atm/eni.h`` -CODA_MAGIC 0xC0DAC0DA coda_file_info ``fs/coda/coda_fs_i.h`` -DPMEM_MAGIC 0xc0ffee11 gdt_pci_sram ``drivers/scsi/gdth.h`` -YAM_MAGIC 0xF10A7654 yam_port ``drivers/net/hamradio/yam.c`` -CCB_MAGIC 0xf2691ad2 ccb ``drivers/scsi/ncr53c8xx.c`` -QUEUE_MAGIC_FREE 0xf7e1c9a3 queue_entry ``drivers/scsi/arm/queue.c`` -QUEUE_MAGIC_USED 0xf7e1cc33 queue_entry ``drivers/scsi/arm/queue.c`` -HTB_CMAGIC 0xFEFAFEF1 htb_class ``net/sched/sch_htb.c`` -NMI_MAGIC 0x48414d4d455201 nmi_s ``arch/mips/include/asm/sn/nmi.h`` -===================== ================ ======================== ========================================== - -Note that there are also defined special per-driver magic numbers in sound -memory management. See ``include/sound/sndmagic.h`` for complete list of them. Many -OSS sound drivers have their magic numbers constructed from the soundcard PCI -ID - these are not listed here as well. - -IrDA subsystem also uses large number of own magic numbers, see -``include/net/irda/irda.h`` for a complete list of them. - -HFS is another larger user of magic numbers - you can find them in -``fs/hfs/hfs.h``. diff --git a/Documentation/process/adding-syscalls.rst b/Documentation/process/adding-syscalls.rst new file mode 100644 index 000000000000..f5b5b1aa51b3 --- /dev/null +++ b/Documentation/process/adding-syscalls.rst @@ -0,0 +1,542 @@ +Adding a New System Call +======================== + +This document describes what's involved in adding a new system call to the +Linux kernel, over and above the normal submission advice in +:ref:`Documentation/SubmittingPatches `. + + +System Call Alternatives +------------------------ + +The first thing to consider when adding a new system call is whether one of +the alternatives might be suitable instead. Although system calls are the +most traditional and most obvious interaction points between userspace and the +kernel, there are other possibilities -- choose what fits best for your +interface. + + - If the operations involved can be made to look like a filesystem-like + object, it may make more sense to create a new filesystem or device. This + also makes it easier to encapsulate the new functionality in a kernel module + rather than requiring it to be built into the main kernel. + + - If the new functionality involves operations where the kernel notifies + userspace that something has happened, then returning a new file + descriptor for the relevant object allows userspace to use + ``poll``/``select``/``epoll`` to receive that notification. + - However, operations that don't map to + :manpage:`read(2)`/:manpage:`write(2)`-like operations + have to be implemented as :manpage:`ioctl(2)` requests, which can lead + to a somewhat opaque API. + + - If you're just exposing runtime system information, a new node in sysfs + (see ``Documentation/filesystems/sysfs.txt``) or the ``/proc`` filesystem may + be more appropriate. However, access to these mechanisms requires that the + relevant filesystem is mounted, which might not always be the case (e.g. + in a namespaced/sandboxed/chrooted environment). Avoid adding any API to + debugfs, as this is not considered a 'production' interface to userspace. + - If the operation is specific to a particular file or file descriptor, then + an additional :manpage:`fcntl(2)` command option may be more appropriate. However, + :manpage:`fcntl(2)` is a multiplexing system call that hides a lot of complexity, so + this option is best for when the new function is closely analogous to + existing :manpage:`fcntl(2)` functionality, or the new functionality is very simple + (for example, getting/setting a simple flag related to a file descriptor). + - If the operation is specific to a particular task or process, then an + additional :manpage:`prctl(2)` command option may be more appropriate. As + with :manpage:`fcntl(2)`, this system call is a complicated multiplexor so + is best reserved for near-analogs of existing ``prctl()`` commands or + getting/setting a simple flag related to a process. + + +Designing the API: Planning for Extension +----------------------------------------- + +A new system call forms part of the API of the kernel, and has to be supported +indefinitely. As such, it's a very good idea to explicitly discuss the +interface on the kernel mailing list, and it's important to plan for future +extensions of the interface. + +(The syscall table is littered with historical examples where this wasn't done, +together with the corresponding follow-up system calls -- +``eventfd``/``eventfd2``, ``dup2``/``dup3``, ``inotify_init``/``inotify_init1``, +``pipe``/``pipe2``, ``renameat``/``renameat2`` -- so +learn from the history of the kernel and plan for extensions from the start.) + +For simpler system calls that only take a couple of arguments, the preferred +way to allow for future extensibility is to include a flags argument to the +system call. To make sure that userspace programs can safely use flags +between kernel versions, check whether the flags value holds any unknown +flags, and reject the system call (with ``EINVAL``) if it does:: + + if (flags & ~(THING_FLAG1 | THING_FLAG2 | THING_FLAG3)) + return -EINVAL; + +(If no flags values are used yet, check that the flags argument is zero.) + +For more sophisticated system calls that involve a larger number of arguments, +it's preferred to encapsulate the majority of the arguments into a structure +that is passed in by pointer. Such a structure can cope with future extension +by including a size argument in the structure:: + + struct xyzzy_params { + u32 size; /* userspace sets p->size = sizeof(struct xyzzy_params) */ + u32 param_1; + u64 param_2; + u64 param_3; + }; + +As long as any subsequently added field, say ``param_4``, is designed so that a +zero value gives the previous behaviour, then this allows both directions of +version mismatch: + + - To cope with a later userspace program calling an older kernel, the kernel + code should check that any memory beyond the size of the structure that it + expects is zero (effectively checking that ``param_4 == 0``). + - To cope with an older userspace program calling a newer kernel, the kernel + code can zero-extend a smaller instance of the structure (effectively + setting ``param_4 = 0``). + +See :manpage:`perf_event_open(2)` and the ``perf_copy_attr()`` function (in +``kernel/events/core.c``) for an example of this approach. + + +Designing the API: Other Considerations +--------------------------------------- + +If your new system call allows userspace to refer to a kernel object, it +should use a file descriptor as the handle for that object -- don't invent a +new type of userspace object handle when the kernel already has mechanisms and +well-defined semantics for using file descriptors. + +If your new :manpage:`xyzzy(2)` system call does return a new file descriptor, +then the flags argument should include a value that is equivalent to setting +``O_CLOEXEC`` on the new FD. This makes it possible for userspace to close +the timing window between ``xyzzy()`` and calling +``fcntl(fd, F_SETFD, FD_CLOEXEC)``, where an unexpected ``fork()`` and +``execve()`` in another thread could leak a descriptor to +the exec'ed program. (However, resist the temptation to re-use the actual value +of the ``O_CLOEXEC`` constant, as it is architecture-specific and is part of a +numbering space of ``O_*`` flags that is fairly full.) + +If your system call returns a new file descriptor, you should also consider +what it means to use the :manpage:`poll(2)` family of system calls on that file +descriptor. Making a file descriptor ready for reading or writing is the +normal way for the kernel to indicate to userspace that an event has +occurred on the corresponding kernel object. + +If your new :manpage:`xyzzy(2)` system call involves a filename argument:: + + int sys_xyzzy(const char __user *path, ..., unsigned int flags); + +you should also consider whether an :manpage:`xyzzyat(2)` version is more appropriate:: + + int sys_xyzzyat(int dfd, const char __user *path, ..., unsigned int flags); + +This allows more flexibility for how userspace specifies the file in question; +in particular it allows userspace to request the functionality for an +already-opened file descriptor using the ``AT_EMPTY_PATH`` flag, effectively +giving an :manpage:`fxyzzy(3)` operation for free:: + + - xyzzyat(AT_FDCWD, path, ..., 0) is equivalent to xyzzy(path,...) + - xyzzyat(fd, "", ..., AT_EMPTY_PATH) is equivalent to fxyzzy(fd, ...) + +(For more details on the rationale of the \*at() calls, see the +:manpage:`openat(2)` man page; for an example of AT_EMPTY_PATH, see the +:manpage:`fstatat(2)` man page.) + +If your new :manpage:`xyzzy(2)` system call involves a parameter describing an +offset within a file, make its type ``loff_t`` so that 64-bit offsets can be +supported even on 32-bit architectures. + +If your new :manpage:`xyzzy(2)` system call involves privileged functionality, +it needs to be governed by the appropriate Linux capability bit (checked with +a call to ``capable()``), as described in the :manpage:`capabilities(7)` man +page. Choose an existing capability bit that governs related functionality, +but try to avoid combining lots of only vaguely related functions together +under the same bit, as this goes against capabilities' purpose of splitting +the power of root. In particular, avoid adding new uses of the already +overly-general ``CAP_SYS_ADMIN`` capability. + +If your new :manpage:`xyzzy(2)` system call manipulates a process other than +the calling process, it should be restricted (using a call to +``ptrace_may_access()``) so that only a calling process with the same +permissions as the target process, or with the necessary capabilities, can +manipulate the target process. + +Finally, be aware that some non-x86 architectures have an easier time if +system call parameters that are explicitly 64-bit fall on odd-numbered +arguments (i.e. parameter 1, 3, 5), to allow use of contiguous pairs of 32-bit +registers. (This concern does not apply if the arguments are part of a +structure that's passed in by pointer.) + + +Proposing the API +----------------- + +To make new system calls easy to review, it's best to divide up the patchset +into separate chunks. These should include at least the following items as +distinct commits (each of which is described further below): + + - The core implementation of the system call, together with prototypes, + generic numbering, Kconfig changes and fallback stub implementation. + - Wiring up of the new system call for one particular architecture, usually + x86 (including all of x86_64, x86_32 and x32). + - A demonstration of the use of the new system call in userspace via a + selftest in ``tools/testing/selftests/``. + - A draft man-page for the new system call, either as plain text in the + cover letter, or as a patch to the (separate) man-pages repository. + +New system call proposals, like any change to the kernel's API, should always +be cc'ed to linux-api@vger.kernel.org. + + +Generic System Call Implementation +---------------------------------- + +The main entry point for your new :manpage:`xyzzy(2)` system call will be called +``sys_xyzzy()``, but you add this entry point with the appropriate +``SYSCALL_DEFINEn()`` macro rather than explicitly. The 'n' indicates the +number of arguments to the system call, and the macro takes the system call name +followed by the (type, name) pairs for the parameters as arguments. Using +this macro allows metadata about the new system call to be made available for +other tools. + +The new entry point also needs a corresponding function prototype, in +``include/linux/syscalls.h``, marked as asmlinkage to match the way that system +calls are invoked:: + + asmlinkage long sys_xyzzy(...); + +Some architectures (e.g. x86) have their own architecture-specific syscall +tables, but several other architectures share a generic syscall table. Add your +new system call to the generic list by adding an entry to the list in +``include/uapi/asm-generic/unistd.h``:: + + #define __NR_xyzzy 292 + __SYSCALL(__NR_xyzzy, sys_xyzzy) + +Also update the __NR_syscalls count to reflect the additional system call, and +note that if multiple new system calls are added in the same merge window, +your new syscall number may get adjusted to resolve conflicts. + +The file ``kernel/sys_ni.c`` provides a fallback stub implementation of each +system call, returning ``-ENOSYS``. Add your new system call here too:: + + cond_syscall(sys_xyzzy); + +Your new kernel functionality, and the system call that controls it, should +normally be optional, so add a ``CONFIG`` option (typically to +``init/Kconfig``) for it. As usual for new ``CONFIG`` options: + + - Include a description of the new functionality and system call controlled + by the option. + - Make the option depend on EXPERT if it should be hidden from normal users. + - Make any new source files implementing the function dependent on the CONFIG + option in the Makefile (e.g. ``obj-$(CONFIG_XYZZY_SYSCALL) += xyzzy.c``). + - Double check that the kernel still builds with the new CONFIG option turned + off. + +To summarize, you need a commit that includes: + + - ``CONFIG`` option for the new function, normally in ``init/Kconfig`` + - ``SYSCALL_DEFINEn(xyzzy, ...)`` for the entry point + - corresponding prototype in ``include/linux/syscalls.h`` + - generic table entry in ``include/uapi/asm-generic/unistd.h`` + - fallback stub in ``kernel/sys_ni.c`` + + +x86 System Call Implementation +------------------------------ + +To wire up your new system call for x86 platforms, you need to update the +master syscall tables. Assuming your new system call isn't special in some +way (see below), this involves a "common" entry (for x86_64 and x32) in +arch/x86/entry/syscalls/syscall_64.tbl:: + + 333 common xyzzy sys_xyzzy + +and an "i386" entry in ``arch/x86/entry/syscalls/syscall_32.tbl``:: + + 380 i386 xyzzy sys_xyzzy + +Again, these numbers are liable to be changed if there are conflicts in the +relevant merge window. + + +Compatibility System Calls (Generic) +------------------------------------ + +For most system calls the same 64-bit implementation can be invoked even when +the userspace program is itself 32-bit; even if the system call's parameters +include an explicit pointer, this is handled transparently. + +However, there are a couple of situations where a compatibility layer is +needed to cope with size differences between 32-bit and 64-bit. + +The first is if the 64-bit kernel also supports 32-bit userspace programs, and +so needs to parse areas of (``__user``) memory that could hold either 32-bit or +64-bit values. In particular, this is needed whenever a system call argument +is: + + - a pointer to a pointer + - a pointer to a struct containing a pointer (e.g. ``struct iovec __user *``) + - a pointer to a varying sized integral type (``time_t``, ``off_t``, + ``long``, ...) + - a pointer to a struct containing a varying sized integral type. + +The second situation that requires a compatibility layer is if one of the +system call's arguments has a type that is explicitly 64-bit even on a 32-bit +architecture, for example ``loff_t`` or ``__u64``. In this case, a value that +arrives at a 64-bit kernel from a 32-bit application will be split into two +32-bit values, which then need to be re-assembled in the compatibility layer. + +(Note that a system call argument that's a pointer to an explicit 64-bit type +does **not** need a compatibility layer; for example, :manpage:`splice(2)`'s arguments of +type ``loff_t __user *`` do not trigger the need for a ``compat_`` system call.) + +The compatibility version of the system call is called ``compat_sys_xyzzy()``, +and is added with the ``COMPAT_SYSCALL_DEFINEn()`` macro, analogously to +SYSCALL_DEFINEn. This version of the implementation runs as part of a 64-bit +kernel, but expects to receive 32-bit parameter values and does whatever is +needed to deal with them. (Typically, the ``compat_sys_`` version converts the +values to 64-bit versions and either calls on to the ``sys_`` version, or both of +them call a common inner implementation function.) + +The compat entry point also needs a corresponding function prototype, in +``include/linux/compat.h``, marked as asmlinkage to match the way that system +calls are invoked:: + + asmlinkage long compat_sys_xyzzy(...); + +If the system call involves a structure that is laid out differently on 32-bit +and 64-bit systems, say ``struct xyzzy_args``, then the include/linux/compat.h +header file should also include a compat version of the structure (``struct +compat_xyzzy_args``) where each variable-size field has the appropriate +``compat_`` type that corresponds to the type in ``struct xyzzy_args``. The +``compat_sys_xyzzy()`` routine can then use this ``compat_`` structure to +parse the arguments from a 32-bit invocation. + +For example, if there are fields:: + + struct xyzzy_args { + const char __user *ptr; + __kernel_long_t varying_val; + u64 fixed_val; + /* ... */ + }; + +in struct xyzzy_args, then struct compat_xyzzy_args would have:: + + struct compat_xyzzy_args { + compat_uptr_t ptr; + compat_long_t varying_val; + u64 fixed_val; + /* ... */ + }; + +The generic system call list also needs adjusting to allow for the compat +version; the entry in ``include/uapi/asm-generic/unistd.h`` should use +``__SC_COMP`` rather than ``__SYSCALL``:: + + #define __NR_xyzzy 292 + __SC_COMP(__NR_xyzzy, sys_xyzzy, compat_sys_xyzzy) + +To summarize, you need: + + - a ``COMPAT_SYSCALL_DEFINEn(xyzzy, ...)`` for the compat entry point + - corresponding prototype in ``include/linux/compat.h`` + - (if needed) 32-bit mapping struct in ``include/linux/compat.h`` + - instance of ``__SC_COMP`` not ``__SYSCALL`` in + ``include/uapi/asm-generic/unistd.h`` + + +Compatibility System Calls (x86) +-------------------------------- + +To wire up the x86 architecture of a system call with a compatibility version, +the entries in the syscall tables need to be adjusted. + +First, the entry in ``arch/x86/entry/syscalls/syscall_32.tbl`` gets an extra +column to indicate that a 32-bit userspace program running on a 64-bit kernel +should hit the compat entry point:: + + 380 i386 xyzzy sys_xyzzy compat_sys_xyzzy + +Second, you need to figure out what should happen for the x32 ABI version of +the new system call. There's a choice here: the layout of the arguments +should either match the 64-bit version or the 32-bit version. + +If there's a pointer-to-a-pointer involved, the decision is easy: x32 is +ILP32, so the layout should match the 32-bit version, and the entry in +``arch/x86/entry/syscalls/syscall_64.tbl`` is split so that x32 programs hit +the compatibility wrapper:: + + 333 64 xyzzy sys_xyzzy + ... + 555 x32 xyzzy compat_sys_xyzzy + +If no pointers are involved, then it is preferable to re-use the 64-bit system +call for the x32 ABI (and consequently the entry in +arch/x86/entry/syscalls/syscall_64.tbl is unchanged). + +In either case, you should check that the types involved in your argument +layout do indeed map exactly from x32 (-mx32) to either the 32-bit (-m32) or +64-bit (-m64) equivalents. + + +System Calls Returning Elsewhere +-------------------------------- + +For most system calls, once the system call is complete the user program +continues exactly where it left off -- at the next instruction, with the +stack the same and most of the registers the same as before the system call, +and with the same virtual memory space. + +However, a few system calls do things differently. They might return to a +different location (``rt_sigreturn``) or change the memory space +(``fork``/``vfork``/``clone``) or even architecture (``execve``/``execveat``) +of the program. + +To allow for this, the kernel implementation of the system call may need to +save and restore additional registers to the kernel stack, allowing complete +control of where and how execution continues after the system call. + +This is arch-specific, but typically involves defining assembly entry points +that save/restore additional registers and invoke the real system call entry +point. + +For x86_64, this is implemented as a ``stub_xyzzy`` entry point in +``arch/x86/entry/entry_64.S``, and the entry in the syscall table +(``arch/x86/entry/syscalls/syscall_64.tbl``) is adjusted to match:: + + 333 common xyzzy stub_xyzzy + +The equivalent for 32-bit programs running on a 64-bit kernel is normally +called ``stub32_xyzzy`` and implemented in ``arch/x86/entry/entry_64_compat.S``, +with the corresponding syscall table adjustment in +``arch/x86/entry/syscalls/syscall_32.tbl``:: + + 380 i386 xyzzy sys_xyzzy stub32_xyzzy + +If the system call needs a compatibility layer (as in the previous section) +then the ``stub32_`` version needs to call on to the ``compat_sys_`` version +of the system call rather than the native 64-bit version. Also, if the x32 ABI +implementation is not common with the x86_64 version, then its syscall +table will also need to invoke a stub that calls on to the ``compat_sys_`` +version. + +For completeness, it's also nice to set up a mapping so that user-mode Linux +still works -- its syscall table will reference stub_xyzzy, but the UML build +doesn't include ``arch/x86/entry/entry_64.S`` implementation (because UML +simulates registers etc). Fixing this is as simple as adding a #define to +``arch/x86/um/sys_call_table_64.c``:: + + #define stub_xyzzy sys_xyzzy + + +Other Details +------------- + +Most of the kernel treats system calls in a generic way, but there is the +occasional exception that may need updating for your particular system call. + +The audit subsystem is one such special case; it includes (arch-specific) +functions that classify some special types of system call -- specifically +file open (``open``/``openat``), program execution (``execve``/``exeveat``) or +socket multiplexor (``socketcall``) operations. If your new system call is +analogous to one of these, then the audit system should be updated. + +More generally, if there is an existing system call that is analogous to your +new system call, it's worth doing a kernel-wide grep for the existing system +call to check there are no other special cases. + + +Testing +------- + +A new system call should obviously be tested; it is also useful to provide +reviewers with a demonstration of how user space programs will use the system +call. A good way to combine these aims is to include a simple self-test +program in a new directory under ``tools/testing/selftests/``. + +For a new system call, there will obviously be no libc wrapper function and so +the test will need to invoke it using ``syscall()``; also, if the system call +involves a new userspace-visible structure, the corresponding header will need +to be installed to compile the test. + +Make sure the selftest runs successfully on all supported architectures. For +example, check that it works when compiled as an x86_64 (-m64), x86_32 (-m32) +and x32 (-mx32) ABI program. + +For more extensive and thorough testing of new functionality, you should also +consider adding tests to the Linux Test Project, or to the xfstests project +for filesystem-related changes. + + - https://linux-test-project.github.io/ + - git://git.kernel.org/pub/scm/fs/xfs/xfstests-dev.git + + +Man Page +-------- + +All new system calls should come with a complete man page, ideally using groff +markup, but plain text will do. If groff is used, it's helpful to include a +pre-rendered ASCII version of the man page in the cover email for the +patchset, for the convenience of reviewers. + +The man page should be cc'ed to linux-man@vger.kernel.org +For more details, see https://www.kernel.org/doc/man-pages/patches.html + +References and Sources +---------------------- + + - LWN article from Michael Kerrisk on use of flags argument in system calls: + https://lwn.net/Articles/585415/ + - LWN article from Michael Kerrisk on how to handle unknown flags in a system + call: https://lwn.net/Articles/588444/ + - LWN article from Jake Edge describing constraints on 64-bit system call + arguments: https://lwn.net/Articles/311630/ + - Pair of LWN articles from David Drysdale that describe the system call + implementation paths in detail for v3.14: + + - https://lwn.net/Articles/604287/ + - https://lwn.net/Articles/604515/ + + - Architecture-specific requirements for system calls are discussed in the + :manpage:`syscall(2)` man-page: + http://man7.org/linux/man-pages/man2/syscall.2.html#NOTES + - Collated emails from Linus Torvalds discussing the problems with ``ioctl()``: + http://yarchive.net/comp/linux/ioctl.html + - "How to not invent kernel interfaces", Arnd Bergmann, + http://www.ukuug.org/events/linux2007/2007/papers/Bergmann.pdf + - LWN article from Michael Kerrisk on avoiding new uses of CAP_SYS_ADMIN: + https://lwn.net/Articles/486306/ + - Recommendation from Andrew Morton that all related information for a new + system call should come in the same email thread: + https://lkml.org/lkml/2014/7/24/641 + - Recommendation from Michael Kerrisk that a new system call should come with + a man page: https://lkml.org/lkml/2014/6/13/309 + - Suggestion from Thomas Gleixner that x86 wire-up should be in a separate + commit: https://lkml.org/lkml/2014/11/19/254 + - Suggestion from Greg Kroah-Hartman that it's good for new system calls to + come with a man-page & selftest: https://lkml.org/lkml/2014/3/19/710 + - Discussion from Michael Kerrisk of new system call vs. :manpage:`prctl(2)` extension: + https://lkml.org/lkml/2014/6/3/411 + - Suggestion from Ingo Molnar that system calls that involve multiple + arguments should encapsulate those arguments in a struct, which includes a + size field for future extensibility: https://lkml.org/lkml/2015/7/30/117 + - Numbering oddities arising from (re-)use of O_* numbering space flags: + + - commit 75069f2b5bfb ("vfs: renumber FMODE_NONOTIFY and add to uniqueness + check") + - commit 12ed2e36c98a ("fanotify: FMODE_NONOTIFY and __O_SYNC in sparc + conflict") + - commit bb458c644a59 ("Safer ABI for O_TMPFILE") + + - Discussion from Matthew Wilcox about restrictions on 64-bit arguments: + https://lkml.org/lkml/2008/12/12/187 + - Recommendation from Greg Kroah-Hartman that unknown flags should be + policed: https://lkml.org/lkml/2014/7/17/577 + - Recommendation from Linus Torvalds that x32 system calls should prefer + compatibility with 64-bit versions rather than 32-bit versions: + https://lkml.org/lkml/2011/8/31/244 diff --git a/Documentation/process/applying-patches.rst b/Documentation/process/applying-patches.rst new file mode 100644 index 000000000000..abd7dc7ae240 --- /dev/null +++ b/Documentation/process/applying-patches.rst @@ -0,0 +1,464 @@ +.. _applying_patches: + +Applying Patches To The Linux Kernel +++++++++++++++++++++++++++++++++++++ + +Original by: + Jesper Juhl, August 2005 + +Last update: + 2016-09-14 + + +A frequently asked question on the Linux Kernel Mailing List is how to apply +a patch to the kernel or, more specifically, what base kernel a patch for +one of the many trees/branches should be applied to. Hopefully this document +will explain this to you. + +In addition to explaining how to apply and revert patches, a brief +description of the different kernel trees (and examples of how to apply +their specific patches) is also provided. + + +What is a patch? +================ + +A patch is a small text document containing a delta of changes between two +different versions of a source tree. Patches are created with the ``diff`` +program. + +To correctly apply a patch you need to know what base it was generated from +and what new version the patch will change the source tree into. These +should both be present in the patch file metadata or be possible to deduce +from the filename. + + +How do I apply or revert a patch? +================================= + +You apply a patch with the ``patch`` program. The patch program reads a diff +(or patch) file and makes the changes to the source tree described in it. + +Patches for the Linux kernel are generated relative to the parent directory +holding the kernel source dir. + +This means that paths to files inside the patch file contain the name of the +kernel source directories it was generated against (or some other directory +names like "a/" and "b/"). + +Since this is unlikely to match the name of the kernel source dir on your +local machine (but is often useful info to see what version an otherwise +unlabeled patch was generated against) you should change into your kernel +source directory and then strip the first element of the path from filenames +in the patch file when applying it (the ``-p1`` argument to ``patch`` does +this). + +To revert a previously applied patch, use the -R argument to patch. +So, if you applied a patch like this:: + + patch -p1 < ../patch-x.y.z + +You can revert (undo) it like this:: + + patch -R -p1 < ../patch-x.y.z + + +How do I feed a patch/diff file to ``patch``? +============================================= + +This (as usual with Linux and other UNIX like operating systems) can be +done in several different ways. + +In all the examples below I feed the file (in uncompressed form) to patch +via stdin using the following syntax:: + + patch -p1 < path/to/patch-x.y.z + +If you just want to be able to follow the examples below and don't want to +know of more than one way to use patch, then you can stop reading this +section here. + +Patch can also get the name of the file to use via the -i argument, like +this:: + + patch -p1 -i path/to/patch-x.y.z + +If your patch file is compressed with gzip or xz and you don't want to +uncompress it before applying it, then you can feed it to patch like this +instead:: + + xzcat path/to/patch-x.y.z.xz | patch -p1 + bzcat path/to/patch-x.y.z.gz | patch -p1 + +If you wish to uncompress the patch file by hand first before applying it +(what I assume you've done in the examples below), then you simply run +gunzip or xz on the file -- like this:: + + gunzip patch-x.y.z.gz + xz -d patch-x.y.z.xz + +Which will leave you with a plain text patch-x.y.z file that you can feed to +patch via stdin or the ``-i`` argument, as you prefer. + +A few other nice arguments for patch are ``-s`` which causes patch to be silent +except for errors which is nice to prevent errors from scrolling out of the +screen too fast, and ``--dry-run`` which causes patch to just print a listing of +what would happen, but doesn't actually make any changes. Finally ``--verbose`` +tells patch to print more information about the work being done. + + +Common errors when patching +=========================== + +When patch applies a patch file it attempts to verify the sanity of the +file in different ways. + +Checking that the file looks like a valid patch file and checking the code +around the bits being modified matches the context provided in the patch are +just two of the basic sanity checks patch does. + +If patch encounters something that doesn't look quite right it has two +options. It can either refuse to apply the changes and abort or it can try +to find a way to make the patch apply with a few minor changes. + +One example of something that's not 'quite right' that patch will attempt to +fix up is if all the context matches, the lines being changed match, but the +line numbers are different. This can happen, for example, if the patch makes +a change in the middle of the file but for some reasons a few lines have +been added or removed near the beginning of the file. In that case +everything looks good it has just moved up or down a bit, and patch will +usually adjust the line numbers and apply the patch. + +Whenever patch applies a patch that it had to modify a bit to make it fit +it'll tell you about it by saying the patch applied with **fuzz**. +You should be wary of such changes since even though patch probably got it +right it doesn't /always/ get it right, and the result will sometimes be +wrong. + +When patch encounters a change that it can't fix up with fuzz it rejects it +outright and leaves a file with a ``.rej`` extension (a reject file). You can +read this file to see exactly what change couldn't be applied, so you can +go fix it up by hand if you wish. + +If you don't have any third-party patches applied to your kernel source, but +only patches from kernel.org and you apply the patches in the correct order, +and have made no modifications yourself to the source files, then you should +never see a fuzz or reject message from patch. If you do see such messages +anyway, then there's a high risk that either your local source tree or the +patch file is corrupted in some way. In that case you should probably try +re-downloading the patch and if things are still not OK then you'd be advised +to start with a fresh tree downloaded in full from kernel.org. + +Let's look a bit more at some of the messages patch can produce. + +If patch stops and presents a ``File to patch:`` prompt, then patch could not +find a file to be patched. Most likely you forgot to specify -p1 or you are +in the wrong directory. Less often, you'll find patches that need to be +applied with ``-p0`` instead of ``-p1`` (reading the patch file should reveal if +this is the case -- if so, then this is an error by the person who created +the patch but is not fatal). + +If you get ``Hunk #2 succeeded at 1887 with fuzz 2 (offset 7 lines).`` or a +message similar to that, then it means that patch had to adjust the location +of the change (in this example it needed to move 7 lines from where it +expected to make the change to make it fit). + +The resulting file may or may not be OK, depending on the reason the file +was different than expected. + +This often happens if you try to apply a patch that was generated against a +different kernel version than the one you are trying to patch. + +If you get a message like ``Hunk #3 FAILED at 2387.``, then it means that the +patch could not be applied correctly and the patch program was unable to +fuzz its way through. This will generate a ``.rej`` file with the change that +caused the patch to fail and also a ``.orig`` file showing you the original +content that couldn't be changed. + +If you get ``Reversed (or previously applied) patch detected! Assume -R? [n]`` +then patch detected that the change contained in the patch seems to have +already been made. + +If you actually did apply this patch previously and you just re-applied it +in error, then just say [n]o and abort this patch. If you applied this patch +previously and actually intended to revert it, but forgot to specify -R, +then you can say [**y**]es here to make patch revert it for you. + +This can also happen if the creator of the patch reversed the source and +destination directories when creating the patch, and in that case reverting +the patch will in fact apply it. + +A message similar to ``patch: **** unexpected end of file in patch`` or +``patch unexpectedly ends in middle of line`` means that patch could make no +sense of the file you fed to it. Either your download is broken, you tried to +feed patch a compressed patch file without uncompressing it first, or the patch +file that you are using has been mangled by a mail client or mail transfer +agent along the way somewhere, e.g., by splitting a long line into two lines. +Often these warnings can easily be fixed by joining (concatenating) the +two lines that had been split. + +As I already mentioned above, these errors should never happen if you apply +a patch from kernel.org to the correct version of an unmodified source tree. +So if you get these errors with kernel.org patches then you should probably +assume that either your patch file or your tree is broken and I'd advise you +to start over with a fresh download of a full kernel tree and the patch you +wish to apply. + + +Are there any alternatives to ``patch``? +======================================== + + +Yes there are alternatives. + +You can use the ``interdiff`` program (http://cyberelk.net/tim/patchutils/) to +generate a patch representing the differences between two patches and then +apply the result. + +This will let you move from something like 4.7.2 to 4.7.3 in a single +step. The -z flag to interdiff will even let you feed it patches in gzip or +bzip2 compressed form directly without the use of zcat or bzcat or manual +decompression. + +Here's how you'd go from 4.7.2 to 4.7.3 in a single step:: + + interdiff -z ../patch-4.7.2.gz ../patch-4.7.3.gz | patch -p1 + +Although interdiff may save you a step or two you are generally advised to +do the additional steps since interdiff can get things wrong in some cases. + +Another alternative is ``ketchup``, which is a python script for automatic +downloading and applying of patches (http://www.selenic.com/ketchup/). + +Other nice tools are diffstat, which shows a summary of changes made by a +patch; lsdiff, which displays a short listing of affected files in a patch +file, along with (optionally) the line numbers of the start of each patch; +and grepdiff, which displays a list of the files modified by a patch where +the patch contains a given regular expression. + + +Where can I download the patches? +================================= + +The patches are available at http://kernel.org/ +Most recent patches are linked from the front page, but they also have +specific homes. + +The 4.x.y (-stable) and 4.x patches live at + + ftp://ftp.kernel.org/pub/linux/kernel/v4.x/ + +The -rc patches live at + + ftp://ftp.kernel.org/pub/linux/kernel/v4.x/testing/ + +In place of ``ftp.kernel.org`` you can use ``ftp.cc.kernel.org``, where cc is a +country code. This way you'll be downloading from a mirror site that's most +likely geographically closer to you, resulting in faster downloads for you, +less bandwidth used globally and less load on the main kernel.org servers -- +these are good things, so do use mirrors when possible. + + +The 4.x kernels +=============== + +These are the base stable releases released by Linus. The highest numbered +release is the most recent. + +If regressions or other serious flaws are found, then a -stable fix patch +will be released (see below) on top of this base. Once a new 4.x base +kernel is released, a patch is made available that is a delta between the +previous 4.x kernel and the new one. + +To apply a patch moving from 4.6 to 4.7, you'd do the following (note +that such patches do **NOT** apply on top of 4.x.y kernels but on top of the +base 4.x kernel -- if you need to move from 4.x.y to 4.x+1 you need to +first revert the 4.x.y patch). + +Here are some examples:: + + # moving from 4.6 to 4.7 + + $ cd ~/linux-4.6 # change to kernel source dir + $ patch -p1 < ../patch-4.7 # apply the 4.7 patch + $ cd .. + $ mv linux-4.6 linux-4.7 # rename source dir + + # moving from 4.6.1 to 4.7 + + $ cd ~/linux-4.6.1 # change to kernel source dir + $ patch -p1 -R < ../patch-4.6.1 # revert the 4.6.1 patch + # source dir is now 4.6 + $ patch -p1 < ../patch-4.7 # apply new 4.7 patch + $ cd .. + $ mv linux-4.6.1 linux-4.7 # rename source dir + + +The 4.x.y kernels +================= + +Kernels with 3-digit versions are -stable kernels. They contain small(ish) +critical fixes for security problems or significant regressions discovered +in a given 4.x kernel. + +This is the recommended branch for users who want the most recent stable +kernel and are not interested in helping test development/experimental +versions. + +If no 4.x.y kernel is available, then the highest numbered 4.x kernel is +the current stable kernel. + +.. note:: + + The -stable team usually do make incremental patches available as well + as patches against the latest mainline release, but I only cover the + non-incremental ones below. The incremental ones can be found at + ftp://ftp.kernel.org/pub/linux/kernel/v4.x/incr/ + +These patches are not incremental, meaning that for example the 4.7.3 +patch does not apply on top of the 4.7.2 kernel source, but rather on top +of the base 4.7 kernel source. + +So, in order to apply the 4.7.3 patch to your existing 4.7.2 kernel +source you have to first back out the 4.7.2 patch (so you are left with a +base 4.7 kernel source) and then apply the new 4.7.3 patch. + +Here's a small example:: + + $ cd ~/linux-4.7.2 # change to the kernel source dir + $ patch -p1 -R < ../patch-4.7.2 # revert the 4.7.2 patch + $ patch -p1 < ../patch-4.7.3 # apply the new 4.7.3 patch + $ cd .. + $ mv linux-4.7.2 linux-4.7.3 # rename the kernel source dir + +The -rc kernels +=============== + +These are release-candidate kernels. These are development kernels released +by Linus whenever he deems the current git (the kernel's source management +tool) tree to be in a reasonably sane state adequate for testing. + +These kernels are not stable and you should expect occasional breakage if +you intend to run them. This is however the most stable of the main +development branches and is also what will eventually turn into the next +stable kernel, so it is important that it be tested by as many people as +possible. + +This is a good branch to run for people who want to help out testing +development kernels but do not want to run some of the really experimental +stuff (such people should see the sections about -git and -mm kernels below). + +The -rc patches are not incremental, they apply to a base 4.x kernel, just +like the 4.x.y patches described above. The kernel version before the -rcN +suffix denotes the version of the kernel that this -rc kernel will eventually +turn into. + +So, 4.8-rc5 means that this is the fifth release candidate for the 4.8 +kernel and the patch should be applied on top of the 4.7 kernel source. + +Here are 3 examples of how to apply these patches:: + + # first an example of moving from 4.7 to 4.8-rc3 + + $ cd ~/linux-4.7 # change to the 4.7 source dir + $ patch -p1 < ../patch-4.8-rc3 # apply the 4.8-rc3 patch + $ cd .. + $ mv linux-4.7 linux-4.8-rc3 # rename the source dir + + # now let's move from 4.8-rc3 to 4.8-rc5 + + $ cd ~/linux-4.8-rc3 # change to the 4.8-rc3 dir + $ patch -p1 -R < ../patch-4.8-rc3 # revert the 4.8-rc3 patch + $ patch -p1 < ../patch-4.8-rc5 # apply the new 4.8-rc5 patch + $ cd .. + $ mv linux-4.8-rc3 linux-4.8-rc5 # rename the source dir + + # finally let's try and move from 4.7.3 to 4.8-rc5 + + $ cd ~/linux-4.7.3 # change to the kernel source dir + $ patch -p1 -R < ../patch-4.7.3 # revert the 4.7.3 patch + $ patch -p1 < ../patch-4.8-rc5 # apply new 4.8-rc5 patch + $ cd .. + $ mv linux-4.7.3 linux-4.8-rc5 # rename the kernel source dir + + +The -git kernels +================ + +These are daily snapshots of Linus' kernel tree (managed in a git +repository, hence the name). + +These patches are usually released daily and represent the current state of +Linus's tree. They are more experimental than -rc kernels since they are +generated automatically without even a cursory glance to see if they are +sane. + +-git patches are not incremental and apply either to a base 4.x kernel or +a base 4.x-rc kernel -- you can see which from their name. +A patch named 4.7-git1 applies to the 4.7 kernel source and a patch +named 4.8-rc3-git2 applies to the source of the 4.8-rc3 kernel. + +Here are some examples of how to apply these patches:: + + # moving from 4.7 to 4.7-git1 + + $ cd ~/linux-4.7 # change to the kernel source dir + $ patch -p1 < ../patch-4.7-git1 # apply the 4.7-git1 patch + $ cd .. + $ mv linux-4.7 linux-4.7-git1 # rename the kernel source dir + + # moving from 4.7-git1 to 4.8-rc2-git3 + + $ cd ~/linux-4.7-git1 # change to the kernel source dir + $ patch -p1 -R < ../patch-4.7-git1 # revert the 4.7-git1 patch + # we now have a 4.7 kernel + $ patch -p1 < ../patch-4.8-rc2 # apply the 4.8-rc2 patch + # the kernel is now 4.8-rc2 + $ patch -p1 < ../patch-4.8-rc2-git3 # apply the 4.8-rc2-git3 patch + # the kernel is now 4.8-rc2-git3 + $ cd .. + $ mv linux-4.7-git1 linux-4.8-rc2-git3 # rename source dir + + +The -mm patches and the linux-next tree +======================================= + +The -mm patches are experimental patches released by Andrew Morton. + +In the past, -mm tree were used to also test subsystem patches, but this +function is now done via the +`linux-next ` +tree. The Subsystem maintainers push their patches first to linux-next, +and, during the merge window, sends them directly to Linus. + +The -mm patches serve as a sort of proving ground for new features and other +experimental patches that aren't merged via a subsystem tree. +Once such patches has proved its worth in -mm for a while Andrew pushes +it on to Linus for inclusion in mainline. + +The linux-next tree is daily updated, and includes the -mm patches. +Both are in constant flux and contains many experimental features, a +lot of debugging patches not appropriate for mainline etc., and is the most +experimental of the branches described in this document. + +These patches are not appropriate for use on systems that are supposed to be +stable and they are more risky to run than any of the other branches (make +sure you have up-to-date backups -- that goes for any experimental kernel but +even more so for -mm patches or using a Kernel from the linux-next tree). + +Testing of -mm patches and linux-next is greatly appreciated since the whole +point of those are to weed out regressions, crashes, data corruption bugs, +build breakage (and any other bug in general) before changes are merged into +the more stable mainline Linus tree. + +But testers of -mm and linux-next should be aware that breakages are +more common than in any other tree. + + +This concludes this list of explanations of the various kernel trees. +I hope you are now clear on how to apply the various patches and help testing +the kernel. + +Thank you's to Randy Dunlap, Rolf Eike Beer, Linus Torvalds, Bodo Eggert, +Johannes Stezenbach, Grant Coady, Pavel Machek and others that I may have +forgotten for their reviews and contributions to this document. diff --git a/Documentation/process/changes.rst b/Documentation/process/changes.rst new file mode 100644 index 000000000000..22797a15dc24 --- /dev/null +++ b/Documentation/process/changes.rst @@ -0,0 +1,485 @@ +.. _changes: + +Minimal requerements to compile the Kernel +++++++++++++++++++++++++++++++++++++++++++ + +Intro +===== + +This document is designed to provide a list of the minimum levels of +software necessary to run the 4.x kernels. + +This document is originally based on my "Changes" file for 2.0.x kernels +and therefore owes credit to the same people as that file (Jared Mauch, +Axel Boldt, Alessandro Sigala, and countless other users all over the +'net). + +Current Minimal Requirements +**************************** + +Upgrade to at **least** these software revisions before thinking you've +encountered a bug! If you're unsure what version you're currently +running, the suggested command should tell you. + +Again, keep in mind that this list assumes you are already functionally +running a Linux kernel. Also, not all tools are necessary on all +systems; obviously, if you don't have any ISDN hardware, for example, +you probably needn't concern yourself with isdn4k-utils. + +====================== =============== ======================================== + Program Minimal version Command to check the version +====================== =============== ======================================== +GNU C 3.2 gcc --version +GNU make 3.80 make --version +binutils 2.12 ld -v +util-linux 2.10o fdformat --version +module-init-tools 0.9.10 depmod -V +e2fsprogs 1.41.4 e2fsck -V +jfsutils 1.1.3 fsck.jfs -V +reiserfsprogs 3.6.3 reiserfsck -V +xfsprogs 2.6.0 xfs_db -V +squashfs-tools 4.0 mksquashfs -version +btrfs-progs 0.18 btrfsck +pcmciautils 004 pccardctl -V +quota-tools 3.09 quota -V +PPP 2.4.0 pppd --version +isdn4k-utils 3.1pre1 isdnctrl 2>&1|grep version +nfs-utils 1.0.5 showmount --version +procps 3.2.0 ps --version +oprofile 0.9 oprofiled --version +udev 081 udevd --version +grub 0.93 grub --version || grub-install --version +mcelog 0.6 mcelog --version +iptables 1.4.2 iptables -V +openssl & libcrypto 1.0.0 openssl version +bc 1.06.95 bc --version +Sphinx\ [#f1]_ 1.2 sphinx-build --version +====================== =============== ======================================== + +.. [#f1] Sphinx is needed only to build the Kernel documentation + +Kernel compilation +****************** + +GCC +--- + +The gcc version requirements may vary depending on the type of CPU in your +computer. + +Make +---- + +You will need GNU make 3.80 or later to build the kernel. + +Binutils +-------- + +Linux on IA-32 has recently switched from using ``as86`` to using ``gas`` for +assembling the 16-bit boot code, removing the need for ``as86`` to compile +your kernel. This change does, however, mean that you need a recent +release of binutils. + +Perl +---- + +You will need perl 5 and the following modules: ``Getopt::Long``, +``Getopt::Std``, ``File::Basename``, and ``File::Find`` to build the kernel. + +BC +-- + +You will need bc to build kernels 3.10 and higher + + +OpenSSL +------- + +Module signing and external certificate handling use the OpenSSL program and +crypto library to do key creation and signature generation. + +You will need openssl to build kernels 3.7 and higher if module signing is +enabled. You will also need openssl development packages to build kernels 4.3 +and higher. + + +System utilities +**************** + +Architectural changes +--------------------- + +DevFS has been obsoleted in favour of udev +(http://www.kernel.org/pub/linux/utils/kernel/hotplug/) + +32-bit UID support is now in place. Have fun! + +Linux documentation for functions is transitioning to inline +documentation via specially-formatted comments near their +definitions in the source. These comments can be combined with the +SGML templates in the Documentation/DocBook directory to make DocBook +files, which can then be converted by DocBook stylesheets to PostScript, +HTML, PDF files, and several other formats. In order to convert from +DocBook format to a format of your choice, you'll need to install Jade as +well as the desired DocBook stylesheets. + +Util-linux +---------- + +New versions of util-linux provide ``fdisk`` support for larger disks, +support new options to mount, recognize more supported partition +types, have a fdformat which works with 2.4 kernels, and similar goodies. +You'll probably want to upgrade. + +Ksymoops +-------- + +If the unthinkable happens and your kernel oopses, you may need the +ksymoops tool to decode it, but in most cases you don't. +It is generally preferred to build the kernel with ``CONFIG_KALLSYMS`` so +that it produces readable dumps that can be used as-is (this also +produces better output than ksymoops). If for some reason your kernel +is not build with ``CONFIG_KALLSYMS`` and you have no way to rebuild and +reproduce the Oops with that option, then you can still decode that Oops +with ksymoops. + +Module-Init-Tools +----------------- + +A new module loader is now in the kernel that requires ``module-init-tools`` +to use. It is backward compatible with the 2.4.x series kernels. + +Mkinitrd +-------- + +These changes to the ``/lib/modules`` file tree layout also require that +mkinitrd be upgraded. + +E2fsprogs +--------- + +The latest version of ``e2fsprogs`` fixes several bugs in fsck and +debugfs. Obviously, it's a good idea to upgrade. + +JFSutils +-------- + +The ``jfsutils`` package contains the utilities for the file system. +The following utilities are available: + +- ``fsck.jfs`` - initiate replay of the transaction log, and check + and repair a JFS formatted partition. + +- ``mkfs.jfs`` - create a JFS formatted partition. + +- other file system utilities are also available in this package. + +Reiserfsprogs +------------- + +The reiserfsprogs package should be used for reiserfs-3.6.x +(Linux kernels 2.4.x). It is a combined package and contains working +versions of ``mkreiserfs``, ``resize_reiserfs``, ``debugreiserfs`` and +``reiserfsck``. These utils work on both i386 and alpha platforms. + +Xfsprogs +-------- + +The latest version of ``xfsprogs`` contains ``mkfs.xfs``, ``xfs_db``, and the +``xfs_repair`` utilities, among others, for the XFS filesystem. It is +architecture independent and any version from 2.0.0 onward should +work correctly with this version of the XFS kernel code (2.6.0 or +later is recommended, due to some significant improvements). + +PCMCIAutils +----------- + +PCMCIAutils replaces ``pcmcia-cs``. It properly sets up +PCMCIA sockets at system startup and loads the appropriate modules +for 16-bit PCMCIA devices if the kernel is modularized and the hotplug +subsystem is used. + +Quota-tools +----------- + +Support for 32 bit uid's and gid's is required if you want to use +the newer version 2 quota format. Quota-tools version 3.07 and +newer has this support. Use the recommended version or newer +from the table above. + +Intel IA32 microcode +-------------------- + +A driver has been added to allow updating of Intel IA32 microcode, +accessible as a normal (misc) character device. If you are not using +udev you may need to:: + + mkdir /dev/cpu + mknod /dev/cpu/microcode c 10 184 + chmod 0644 /dev/cpu/microcode + +as root before you can use this. You'll probably also want to +get the user-space microcode_ctl utility to use with this. + +udev +---- + +``udev`` is a userspace application for populating ``/dev`` dynamically with +only entries for devices actually present. ``udev`` replaces the basic +functionality of devfs, while allowing persistent device naming for +devices. + +FUSE +---- + +Needs libfuse 2.4.0 or later. Absolute minimum is 2.3.0 but mount +options ``direct_io`` and ``kernel_cache`` won't work. + +Networking +********** + +General changes +--------------- + +If you have advanced network configuration needs, you should probably +consider using the network tools from ip-route2. + +Packet Filter / NAT +------------------- +The packet filtering and NAT code uses the same tools like the previous 2.4.x +kernel series (iptables). It still includes backwards-compatibility modules +for 2.2.x-style ipchains and 2.0.x-style ipfwadm. + +PPP +--- + +The PPP driver has been restructured to support multilink and to +enable it to operate over diverse media layers. If you use PPP, +upgrade pppd to at least 2.4.0. + +If you are not using udev, you must have the device file /dev/ppp +which can be made by:: + + mknod /dev/ppp c 108 0 + +as root. + +Isdn4k-utils +------------ + +Due to changes in the length of the phone number field, isdn4k-utils +needs to be recompiled or (preferably) upgraded. + +NFS-utils +--------- + +In ancient (2.4 and earlier) kernels, the nfs server needed to know +about any client that expected to be able to access files via NFS. This +information would be given to the kernel by ``mountd`` when the client +mounted the filesystem, or by ``exportfs`` at system startup. exportfs +would take information about active clients from ``/var/lib/nfs/rmtab``. + +This approach is quite fragile as it depends on rmtab being correct +which is not always easy, particularly when trying to implement +fail-over. Even when the system is working well, ``rmtab`` suffers from +getting lots of old entries that never get removed. + +With modern kernels we have the option of having the kernel tell mountd +when it gets a request from an unknown host, and mountd can give +appropriate export information to the kernel. This removes the +dependency on ``rmtab`` and means that the kernel only needs to know about +currently active clients. + +To enable this new functionality, you need to:: + + mount -t nfsd nfsd /proc/fs/nfsd + +before running exportfs or mountd. It is recommended that all NFS +services be protected from the internet-at-large by a firewall where +that is possible. + +mcelog +------ + +On x86 kernels the mcelog utility is needed to process and log machine check +events when ``CONFIG_X86_MCE`` is enabled. Machine check events are errors +reported by the CPU. Processing them is strongly encouraged. + +Kernel documentation +******************** + +Sphinx +------ + +The ReST markups currently used by the Documentation/ files are meant to be +built with ``Sphinx`` version 1.2 or upper. If you're desiring to build +PDF outputs, it is recommended to use version 1.4.6. + +.. note:: + + Please notice that, for PDF and LaTeX output, you'll also need ``XeLaTeX`` + version 3.14159265. Depending on the distribution, you may also need + to install a series of ``texlive`` packages that provide the minimal + set of functionalities required for ``XeLaTex`` to work. + +Other tools +----------- + +In order to produce documentation from DocBook, you'll also need ``xmlto``. +Please notice, however, that we're currently migrating all documents to use +``Sphinx``. + +Getting updated software +======================== + +Kernel compilation +****************** + +gcc +--- + +- + +Make +---- + +- + +Binutils +-------- + +- + +OpenSSL +------- + +- + +System utilities +**************** + +Util-linux +---------- + +- + +Ksymoops +-------- + +- + +Module-Init-Tools +----------------- + +- + +Mkinitrd +-------- + +- + +E2fsprogs +--------- + +- + +JFSutils +-------- + +- + +Reiserfsprogs +------------- + +- + +Xfsprogs +-------- + +- + +Pcmciautils +----------- + +- + +Quota-tools +----------- + +- + +DocBook Stylesheets +------------------- + +- + +XMLTO XSLT Frontend +------------------- + +- + +Intel P6 microcode +------------------ + +- + +udev +---- + +- + +FUSE +---- + +- + +mcelog +------ + +- + +Networking +********** + +PPP +--- + +- + +Isdn4k-utils +------------ + +- + +NFS-utils +--------- + +- + +Iptables +-------- + +- + +Ip-route2 +--------- + +- + +OProfile +-------- + +- + +NFS-Utils +--------- + +- + +Kernel documentation +******************** + +Sphinx +------ + +- diff --git a/Documentation/process/code-of-conflict.rst b/Documentation/process/code-of-conflict.rst new file mode 100644 index 000000000000..47b6de763203 --- /dev/null +++ b/Documentation/process/code-of-conflict.rst @@ -0,0 +1,28 @@ +Code of Conflict +---------------- + +The Linux kernel development effort is a very personal process compared +to "traditional" ways of developing software. Your code and ideas +behind it will be carefully reviewed, often resulting in critique and +criticism. The review will almost always require improvements to the +code before it can be included in the kernel. Know that this happens +because everyone involved wants to see the best possible solution for +the overall success of Linux. This development process has been proven +to create the most robust operating system kernel ever, and we do not +want to do anything to cause the quality of submission and eventual +result to ever decrease. + +If however, anyone feels personally abused, threatened, or otherwise +uncomfortable due to this process, that is not acceptable. If so, +please contact the Linux Foundation's Technical Advisory Board at +, or the individual members, and they +will work to resolve the issue to the best of their ability. For more +information on who is on the Technical Advisory Board and what their +role is, please see: + + - http://www.linuxfoundation.org/projects/linux/tab + +As a reviewer of code, please strive to keep things civil and focused on +the technical issues involved. We are all humans, and frustrations can +be high on both sides of the process. Try to keep in mind the immortal +words of Bill and Ted, "Be excellent to each other." diff --git a/Documentation/process/coding-style.rst b/Documentation/process/coding-style.rst new file mode 100644 index 000000000000..9c61c039ccd9 --- /dev/null +++ b/Documentation/process/coding-style.rst @@ -0,0 +1,1062 @@ +.. _codingstyle: + +Linux kernel coding style +========================= + +This is a short document describing the preferred coding style for the +linux kernel. Coding style is very personal, and I won't **force** my +views on anybody, but this is what goes for anything that I have to be +able to maintain, and I'd prefer it for most other things too. Please +at least consider the points made here. + +First off, I'd suggest printing out a copy of the GNU coding standards, +and NOT read it. Burn them, it's a great symbolic gesture. + +Anyway, here goes: + + +1) Indentation +-------------- + +Tabs are 8 characters, and thus indentations are also 8 characters. +There are heretic movements that try to make indentations 4 (or even 2!) +characters deep, and that is akin to trying to define the value of PI to +be 3. + +Rationale: The whole idea behind indentation is to clearly define where +a block of control starts and ends. Especially when you've been looking +at your screen for 20 straight hours, you'll find it a lot easier to see +how the indentation works if you have large indentations. + +Now, some people will claim that having 8-character indentations makes +the code move too far to the right, and makes it hard to read on a +80-character terminal screen. The answer to that is that if you need +more than 3 levels of indentation, you're screwed anyway, and should fix +your program. + +In short, 8-char indents make things easier to read, and have the added +benefit of warning you when you're nesting your functions too deep. +Heed that warning. + +The preferred way to ease multiple indentation levels in a switch statement is +to align the ``switch`` and its subordinate ``case`` labels in the same column +instead of ``double-indenting`` the ``case`` labels. E.g.: + +.. code-block:: c + + switch (suffix) { + case 'G': + case 'g': + mem <<= 30; + break; + case 'M': + case 'm': + mem <<= 20; + break; + case 'K': + case 'k': + mem <<= 10; + /* fall through */ + default: + break; + } + +Don't put multiple statements on a single line unless you have +something to hide: + +.. code-block:: c + + if (condition) do_this; + do_something_everytime; + +Don't put multiple assignments on a single line either. Kernel coding style +is super simple. Avoid tricky expressions. + +Outside of comments, documentation and except in Kconfig, spaces are never +used for indentation, and the above example is deliberately broken. + +Get a decent editor and don't leave whitespace at the end of lines. + + +2) Breaking long lines and strings +---------------------------------- + +Coding style is all about readability and maintainability using commonly +available tools. + +The limit on the length of lines is 80 columns and this is a strongly +preferred limit. + +Statements longer than 80 columns will be broken into sensible chunks, unless +exceeding 80 columns significantly increases readability and does not hide +information. Descendants are always substantially shorter than the parent and +are placed substantially to the right. The same applies to function headers +with a long argument list. However, never break user-visible strings such as +printk messages, because that breaks the ability to grep for them. + + +3) Placing Braces and Spaces +---------------------------- + +The other issue that always comes up in C styling is the placement of +braces. Unlike the indent size, there are few technical reasons to +choose one placement strategy over the other, but the preferred way, as +shown to us by the prophets Kernighan and Ritchie, is to put the opening +brace last on the line, and put the closing brace first, thusly: + +.. code-block:: c + + if (x is true) { + we do y + } + +This applies to all non-function statement blocks (if, switch, for, +while, do). E.g.: + +.. code-block:: c + + switch (action) { + case KOBJ_ADD: + return "add"; + case KOBJ_REMOVE: + return "remove"; + case KOBJ_CHANGE: + return "change"; + default: + return NULL; + } + +However, there is one special case, namely functions: they have the +opening brace at the beginning of the next line, thus: + +.. code-block:: c + + int function(int x) + { + body of function + } + +Heretic people all over the world have claimed that this inconsistency +is ... well ... inconsistent, but all right-thinking people know that +(a) K&R are **right** and (b) K&R are right. Besides, functions are +special anyway (you can't nest them in C). + +Note that the closing brace is empty on a line of its own, **except** in +the cases where it is followed by a continuation of the same statement, +ie a ``while`` in a do-statement or an ``else`` in an if-statement, like +this: + +.. code-block:: c + + do { + body of do-loop + } while (condition); + +and + +.. code-block:: c + + if (x == y) { + .. + } else if (x > y) { + ... + } else { + .... + } + +Rationale: K&R. + +Also, note that this brace-placement also minimizes the number of empty +(or almost empty) lines, without any loss of readability. Thus, as the +supply of new-lines on your screen is not a renewable resource (think +25-line terminal screens here), you have more empty lines to put +comments on. + +Do not unnecessarily use braces where a single statement will do. + +.. code-block:: c + + if (condition) + action(); + +and + +.. code-block:: none + + if (condition) + do_this(); + else + do_that(); + +This does not apply if only one branch of a conditional statement is a single +statement; in the latter case use braces in both branches: + +.. code-block:: c + + if (condition) { + do_this(); + do_that(); + } else { + otherwise(); + } + +3.1) Spaces +*********** + +Linux kernel style for use of spaces depends (mostly) on +function-versus-keyword usage. Use a space after (most) keywords. The +notable exceptions are sizeof, typeof, alignof, and __attribute__, which look +somewhat like functions (and are usually used with parentheses in Linux, +although they are not required in the language, as in: ``sizeof info`` after +``struct fileinfo info;`` is declared). + +So use a space after these keywords:: + + if, switch, case, for, do, while + +but not with sizeof, typeof, alignof, or __attribute__. E.g., + +.. code-block:: c + + + s = sizeof(struct file); + +Do not add spaces around (inside) parenthesized expressions. This example is +**bad**: + +.. code-block:: c + + + s = sizeof( struct file ); + +When declaring pointer data or a function that returns a pointer type, the +preferred use of ``*`` is adjacent to the data name or function name and not +adjacent to the type name. Examples: + +.. code-block:: c + + + char *linux_banner; + unsigned long long memparse(char *ptr, char **retptr); + char *match_strdup(substring_t *s); + +Use one space around (on each side of) most binary and ternary operators, +such as any of these:: + + = + - < > * / % | & ^ <= >= == != ? : + +but no space after unary operators:: + + & * + - ~ ! sizeof typeof alignof __attribute__ defined + +no space before the postfix increment & decrement unary operators:: + + ++ -- + +no space after the prefix increment & decrement unary operators:: + + ++ -- + +and no space around the ``.`` and ``->`` structure member operators. + +Do not leave trailing whitespace at the ends of lines. Some editors with +``smart`` indentation will insert whitespace at the beginning of new lines as +appropriate, so you can start typing the next line of code right away. +However, some such editors do not remove the whitespace if you end up not +putting a line of code there, such as if you leave a blank line. As a result, +you end up with lines containing trailing whitespace. + +Git will warn you about patches that introduce trailing whitespace, and can +optionally strip the trailing whitespace for you; however, if applying a series +of patches, this may make later patches in the series fail by changing their +context lines. + + +4) Naming +--------- + +C is a Spartan language, and so should your naming be. Unlike Modula-2 +and Pascal programmers, C programmers do not use cute names like +ThisVariableIsATemporaryCounter. A C programmer would call that +variable ``tmp``, which is much easier to write, and not the least more +difficult to understand. + +HOWEVER, while mixed-case names are frowned upon, descriptive names for +global variables are a must. To call a global function ``foo`` is a +shooting offense. + +GLOBAL variables (to be used only if you **really** need them) need to +have descriptive names, as do global functions. If you have a function +that counts the number of active users, you should call that +``count_active_users()`` or similar, you should **not** call it ``cntusr()``. + +Encoding the type of a function into the name (so-called Hungarian +notation) is brain damaged - the compiler knows the types anyway and can +check those, and it only confuses the programmer. No wonder MicroSoft +makes buggy programs. + +LOCAL variable names should be short, and to the point. If you have +some random integer loop counter, it should probably be called ``i``. +Calling it ``loop_counter`` is non-productive, if there is no chance of it +being mis-understood. Similarly, ``tmp`` can be just about any type of +variable that is used to hold a temporary value. + +If you are afraid to mix up your local variable names, you have another +problem, which is called the function-growth-hormone-imbalance syndrome. +See chapter 6 (Functions). + + +5) Typedefs +----------- + +Please don't use things like ``vps_t``. +It's a **mistake** to use typedef for structures and pointers. When you see a + +.. code-block:: c + + + vps_t a; + +in the source, what does it mean? +In contrast, if it says + +.. code-block:: c + + struct virtual_container *a; + +you can actually tell what ``a`` is. + +Lots of people think that typedefs ``help readability``. Not so. They are +useful only for: + + (a) totally opaque objects (where the typedef is actively used to **hide** + what the object is). + + Example: ``pte_t`` etc. opaque objects that you can only access using + the proper accessor functions. + + .. note:: + + Opaqueness and ``accessor functions`` are not good in themselves. + The reason we have them for things like pte_t etc. is that there + really is absolutely **zero** portably accessible information there. + + (b) Clear integer types, where the abstraction **helps** avoid confusion + whether it is ``int`` or ``long``. + + u8/u16/u32 are perfectly fine typedefs, although they fit into + category (d) better than here. + + .. note:: + + Again - there needs to be a **reason** for this. If something is + ``unsigned long``, then there's no reason to do + + typedef unsigned long myflags_t; + + but if there is a clear reason for why it under certain circumstances + might be an ``unsigned int`` and under other configurations might be + ``unsigned long``, then by all means go ahead and use a typedef. + + (c) when you use sparse to literally create a **new** type for + type-checking. + + (d) New types which are identical to standard C99 types, in certain + exceptional circumstances. + + Although it would only take a short amount of time for the eyes and + brain to become accustomed to the standard types like ``uint32_t``, + some people object to their use anyway. + + Therefore, the Linux-specific ``u8/u16/u32/u64`` types and their + signed equivalents which are identical to standard types are + permitted -- although they are not mandatory in new code of your + own. + + When editing existing code which already uses one or the other set + of types, you should conform to the existing choices in that code. + + (e) Types safe for use in userspace. + + In certain structures which are visible to userspace, we cannot + require C99 types and cannot use the ``u32`` form above. Thus, we + use __u32 and similar types in all structures which are shared + with userspace. + +Maybe there are other cases too, but the rule should basically be to NEVER +EVER use a typedef unless you can clearly match one of those rules. + +In general, a pointer, or a struct that has elements that can reasonably +be directly accessed should **never** be a typedef. + + +6) Functions +------------ + +Functions should be short and sweet, and do just one thing. They should +fit on one or two screenfuls of text (the ISO/ANSI screen size is 80x24, +as we all know), and do one thing and do that well. + +The maximum length of a function is inversely proportional to the +complexity and indentation level of that function. So, if you have a +conceptually simple function that is just one long (but simple) +case-statement, where you have to do lots of small things for a lot of +different cases, it's OK to have a longer function. + +However, if you have a complex function, and you suspect that a +less-than-gifted first-year high-school student might not even +understand what the function is all about, you should adhere to the +maximum limits all the more closely. Use helper functions with +descriptive names (you can ask the compiler to in-line them if you think +it's performance-critical, and it will probably do a better job of it +than you would have done). + +Another measure of the function is the number of local variables. They +shouldn't exceed 5-10, or you're doing something wrong. Re-think the +function, and split it into smaller pieces. A human brain can +generally easily keep track of about 7 different things, anything more +and it gets confused. You know you're brilliant, but maybe you'd like +to understand what you did 2 weeks from now. + +In source files, separate functions with one blank line. If the function is +exported, the **EXPORT** macro for it should follow immediately after the +closing function brace line. E.g.: + +.. code-block:: c + + int system_is_up(void) + { + return system_state == SYSTEM_RUNNING; + } + EXPORT_SYMBOL(system_is_up); + +In function prototypes, include parameter names with their data types. +Although this is not required by the C language, it is preferred in Linux +because it is a simple way to add valuable information for the reader. + + +7) Centralized exiting of functions +----------------------------------- + +Albeit deprecated by some people, the equivalent of the goto statement is +used frequently by compilers in form of the unconditional jump instruction. + +The goto statement comes in handy when a function exits from multiple +locations and some common work such as cleanup has to be done. If there is no +cleanup needed then just return directly. + +Choose label names which say what the goto does or why the goto exists. An +example of a good name could be ``out_free_buffer:`` if the goto frees ``buffer``. +Avoid using GW-BASIC names like ``err1:`` and ``err2:``, as you would have to +renumber them if you ever add or remove exit paths, and they make correctness +difficult to verify anyway. + +The rationale for using gotos is: + +- unconditional statements are easier to understand and follow +- nesting is reduced +- errors by not updating individual exit points when making + modifications are prevented +- saves the compiler work to optimize redundant code away ;) + +.. code-block:: c + + int fun(int a) + { + int result = 0; + char *buffer; + + buffer = kmalloc(SIZE, GFP_KERNEL); + if (!buffer) + return -ENOMEM; + + if (condition1) { + while (loop1) { + ... + } + result = 1; + goto out_buffer; + } + ... + out_free_buffer: + kfree(buffer); + return result; + } + +A common type of bug to be aware of is ``one err bugs`` which look like this: + +.. code-block:: c + + err: + kfree(foo->bar); + kfree(foo); + return ret; + +The bug in this code is that on some exit paths ``foo`` is NULL. Normally the +fix for this is to split it up into two error labels ``err_free_bar:`` and +``err_free_foo:``: + +.. code-block:: c + + err_free_bar: + kfree(foo->bar); + err_free_foo: + kfree(foo); + return ret; + +Ideally you should simulate errors to test all exit paths. + + +8) Commenting +------------- + +Comments are good, but there is also a danger of over-commenting. NEVER +try to explain HOW your code works in a comment: it's much better to +write the code so that the **working** is obvious, and it's a waste of +time to explain badly written code. + +Generally, you want your comments to tell WHAT your code does, not HOW. +Also, try to avoid putting comments inside a function body: if the +function is so complex that you need to separately comment parts of it, +you should probably go back to chapter 6 for a while. You can make +small comments to note or warn about something particularly clever (or +ugly), but try to avoid excess. Instead, put the comments at the head +of the function, telling people what it does, and possibly WHY it does +it. + +When commenting the kernel API functions, please use the kernel-doc format. +See the files Documentation/kernel-documentation.rst and scripts/kernel-doc +for details. + +The preferred style for long (multi-line) comments is: + +.. code-block:: c + + /* + * This is the preferred style for multi-line + * comments in the Linux kernel source code. + * Please use it consistently. + * + * Description: A column of asterisks on the left side, + * with beginning and ending almost-blank lines. + */ + +For files in net/ and drivers/net/ the preferred style for long (multi-line) +comments is a little different. + +.. code-block:: c + + /* The preferred comment style for files in net/ and drivers/net + * looks like this. + * + * It is nearly the same as the generally preferred comment style, + * but there is no initial almost-blank line. + */ + +It's also important to comment data, whether they are basic types or derived +types. To this end, use just one data declaration per line (no commas for +multiple data declarations). This leaves you room for a small comment on each +item, explaining its use. + + +9) You've made a mess of it +--------------------------- + +That's OK, we all do. You've probably been told by your long-time Unix +user helper that ``GNU emacs`` automatically formats the C sources for +you, and you've noticed that yes, it does do that, but the defaults it +uses are less than desirable (in fact, they are worse than random +typing - an infinite number of monkeys typing into GNU emacs would never +make a good program). + +So, you can either get rid of GNU emacs, or change it to use saner +values. To do the latter, you can stick the following in your .emacs file: + +.. code-block:: none + + (defun c-lineup-arglist-tabs-only (ignored) + "Line up argument lists by tabs, not spaces" + (let* ((anchor (c-langelem-pos c-syntactic-element)) + (column (c-langelem-2nd-pos c-syntactic-element)) + (offset (- (1+ column) anchor)) + (steps (floor offset c-basic-offset))) + (* (max steps 1) + c-basic-offset))) + + (add-hook 'c-mode-common-hook + (lambda () + ;; Add kernel style + (c-add-style + "linux-tabs-only" + '("linux" (c-offsets-alist + (arglist-cont-nonempty + c-lineup-gcc-asm-reg + c-lineup-arglist-tabs-only)))))) + + (add-hook 'c-mode-hook + (lambda () + (let ((filename (buffer-file-name))) + ;; Enable kernel mode for the appropriate files + (when (and filename + (string-match (expand-file-name "~/src/linux-trees") + filename)) + (setq indent-tabs-mode t) + (setq show-trailing-whitespace t) + (c-set-style "linux-tabs-only"))))) + +This will make emacs go better with the kernel coding style for C +files below ``~/src/linux-trees``. + +But even if you fail in getting emacs to do sane formatting, not +everything is lost: use ``indent``. + +Now, again, GNU indent has the same brain-dead settings that GNU emacs +has, which is why you need to give it a few command line options. +However, that's not too bad, because even the makers of GNU indent +recognize the authority of K&R (the GNU people aren't evil, they are +just severely misguided in this matter), so you just give indent the +options ``-kr -i8`` (stands for ``K&R, 8 character indents``), or use +``scripts/Lindent``, which indents in the latest style. + +``indent`` has a lot of options, and especially when it comes to comment +re-formatting you may want to take a look at the man page. But +remember: ``indent`` is not a fix for bad programming. + + +10) Kconfig configuration files +------------------------------- + +For all of the Kconfig* configuration files throughout the source tree, +the indentation is somewhat different. Lines under a ``config`` definition +are indented with one tab, while help text is indented an additional two +spaces. Example:: + + config AUDIT + bool "Auditing support" + depends on NET + help + Enable auditing infrastructure that can be used with another + kernel subsystem, such as SELinux (which requires this for + logging of avc messages output). Does not do system-call + auditing without CONFIG_AUDITSYSCALL. + +Seriously dangerous features (such as write support for certain +filesystems) should advertise this prominently in their prompt string:: + + config ADFS_FS_RW + bool "ADFS write support (DANGEROUS)" + depends on ADFS_FS + ... + +For full documentation on the configuration files, see the file +Documentation/kbuild/kconfig-language.txt. + + +11) Data structures +------------------- + +Data structures that have visibility outside the single-threaded +environment they are created and destroyed in should always have +reference counts. In the kernel, garbage collection doesn't exist (and +outside the kernel garbage collection is slow and inefficient), which +means that you absolutely **have** to reference count all your uses. + +Reference counting means that you can avoid locking, and allows multiple +users to have access to the data structure in parallel - and not having +to worry about the structure suddenly going away from under them just +because they slept or did something else for a while. + +Note that locking is **not** a replacement for reference counting. +Locking is used to keep data structures coherent, while reference +counting is a memory management technique. Usually both are needed, and +they are not to be confused with each other. + +Many data structures can indeed have two levels of reference counting, +when there are users of different ``classes``. The subclass count counts +the number of subclass users, and decrements the global count just once +when the subclass count goes to zero. + +Examples of this kind of ``multi-level-reference-counting`` can be found in +memory management (``struct mm_struct``: mm_users and mm_count), and in +filesystem code (``struct super_block``: s_count and s_active). + +Remember: if another thread can find your data structure, and you don't +have a reference count on it, you almost certainly have a bug. + + +12) Macros, Enums and RTL +------------------------- + +Names of macros defining constants and labels in enums are capitalized. + +.. code-block:: c + + #define CONSTANT 0x12345 + +Enums are preferred when defining several related constants. + +CAPITALIZED macro names are appreciated but macros resembling functions +may be named in lower case. + +Generally, inline functions are preferable to macros resembling functions. + +Macros with multiple statements should be enclosed in a do - while block: + +.. code-block:: c + + #define macrofun(a, b, c) \ + do { \ + if (a == 5) \ + do_this(b, c); \ + } while (0) + +Things to avoid when using macros: + +1) macros that affect control flow: + +.. code-block:: c + + #define FOO(x) \ + do { \ + if (blah(x) < 0) \ + return -EBUGGERED; \ + } while (0) + +is a **very** bad idea. It looks like a function call but exits the ``calling`` +function; don't break the internal parsers of those who will read the code. + +2) macros that depend on having a local variable with a magic name: + +.. code-block:: c + + #define FOO(val) bar(index, val) + +might look like a good thing, but it's confusing as hell when one reads the +code and it's prone to breakage from seemingly innocent changes. + +3) macros with arguments that are used as l-values: FOO(x) = y; will +bite you if somebody e.g. turns FOO into an inline function. + +4) forgetting about precedence: macros defining constants using expressions +must enclose the expression in parentheses. Beware of similar issues with +macros using parameters. + +.. code-block:: c + + #define CONSTANT 0x4000 + #define CONSTEXP (CONSTANT | 3) + +5) namespace collisions when defining local variables in macros resembling +functions: + +.. code-block:: c + + #define FOO(x) \ + ({ \ + typeof(x) ret; \ + ret = calc_ret(x); \ + (ret); \ + }) + +ret is a common name for a local variable - __foo_ret is less likely +to collide with an existing variable. + +The cpp manual deals with macros exhaustively. The gcc internals manual also +covers RTL which is used frequently with assembly language in the kernel. + + +13) Printing kernel messages +---------------------------- + +Kernel developers like to be seen as literate. Do mind the spelling +of kernel messages to make a good impression. Do not use crippled +words like ``dont``; use ``do not`` or ``don't`` instead. Make the messages +concise, clear, and unambiguous. + +Kernel messages do not have to be terminated with a period. + +Printing numbers in parentheses (%d) adds no value and should be avoided. + +There are a number of driver model diagnostic macros in +which you should use to make sure messages are matched to the right device +and driver, and are tagged with the right level: dev_err(), dev_warn(), +dev_info(), and so forth. For messages that aren't associated with a +particular device, defines pr_notice(), pr_info(), +pr_warn(), pr_err(), etc. + +Coming up with good debugging messages can be quite a challenge; and once +you have them, they can be a huge help for remote troubleshooting. However +debug message printing is handled differently than printing other non-debug +messages. While the other pr_XXX() functions print unconditionally, +pr_debug() does not; it is compiled out by default, unless either DEBUG is +defined or CONFIG_DYNAMIC_DEBUG is set. That is true for dev_dbg() also, +and a related convention uses VERBOSE_DEBUG to add dev_vdbg() messages to +the ones already enabled by DEBUG. + +Many subsystems have Kconfig debug options to turn on -DDEBUG in the +corresponding Makefile; in other cases specific files #define DEBUG. And +when a debug message should be unconditionally printed, such as if it is +already inside a debug-related #ifdef section, printk(KERN_DEBUG ...) can be +used. + + +14) Allocating memory +--------------------- + +The kernel provides the following general purpose memory allocators: +kmalloc(), kzalloc(), kmalloc_array(), kcalloc(), vmalloc(), and +vzalloc(). Please refer to the API documentation for further information +about them. + +The preferred form for passing a size of a struct is the following: + +.. code-block:: c + + p = kmalloc(sizeof(*p), ...); + +The alternative form where struct name is spelled out hurts readability and +introduces an opportunity for a bug when the pointer variable type is changed +but the corresponding sizeof that is passed to a memory allocator is not. + +Casting the return value which is a void pointer is redundant. The conversion +from void pointer to any other pointer type is guaranteed by the C programming +language. + +The preferred form for allocating an array is the following: + +.. code-block:: c + + p = kmalloc_array(n, sizeof(...), ...); + +The preferred form for allocating a zeroed array is the following: + +.. code-block:: c + + p = kcalloc(n, sizeof(...), ...); + +Both forms check for overflow on the allocation size n * sizeof(...), +and return NULL if that occurred. + + +15) The inline disease +---------------------- + +There appears to be a common misperception that gcc has a magic "make me +faster" speedup option called ``inline``. While the use of inlines can be +appropriate (for example as a means of replacing macros, see Chapter 12), it +very often is not. Abundant use of the inline keyword leads to a much bigger +kernel, which in turn slows the system as a whole down, due to a bigger +icache footprint for the CPU and simply because there is less memory +available for the pagecache. Just think about it; a pagecache miss causes a +disk seek, which easily takes 5 milliseconds. There are a LOT of cpu cycles +that can go into these 5 milliseconds. + +A reasonable rule of thumb is to not put inline at functions that have more +than 3 lines of code in them. An exception to this rule are the cases where +a parameter is known to be a compiletime constant, and as a result of this +constantness you *know* the compiler will be able to optimize most of your +function away at compile time. For a good example of this later case, see +the kmalloc() inline function. + +Often people argue that adding inline to functions that are static and used +only once is always a win since there is no space tradeoff. While this is +technically correct, gcc is capable of inlining these automatically without +help, and the maintenance issue of removing the inline when a second user +appears outweighs the potential value of the hint that tells gcc to do +something it would have done anyway. + + +16) Function return values and names +------------------------------------ + +Functions can return values of many different kinds, and one of the +most common is a value indicating whether the function succeeded or +failed. Such a value can be represented as an error-code integer +(-Exxx = failure, 0 = success) or a ``succeeded`` boolean (0 = failure, +non-zero = success). + +Mixing up these two sorts of representations is a fertile source of +difficult-to-find bugs. If the C language included a strong distinction +between integers and booleans then the compiler would find these mistakes +for us... but it doesn't. To help prevent such bugs, always follow this +convention:: + + If the name of a function is an action or an imperative command, + the function should return an error-code integer. If the name + is a predicate, the function should return a "succeeded" boolean. + +For example, ``add work`` is a command, and the add_work() function returns 0 +for success or -EBUSY for failure. In the same way, ``PCI device present`` is +a predicate, and the pci_dev_present() function returns 1 if it succeeds in +finding a matching device or 0 if it doesn't. + +All EXPORTed functions must respect this convention, and so should all +public functions. Private (static) functions need not, but it is +recommended that they do. + +Functions whose return value is the actual result of a computation, rather +than an indication of whether the computation succeeded, are not subject to +this rule. Generally they indicate failure by returning some out-of-range +result. Typical examples would be functions that return pointers; they use +NULL or the ERR_PTR mechanism to report failure. + + +17) Don't re-invent the kernel macros +------------------------------------- + +The header file include/linux/kernel.h contains a number of macros that +you should use, rather than explicitly coding some variant of them yourself. +For example, if you need to calculate the length of an array, take advantage +of the macro + +.. code-block:: c + + #define ARRAY_SIZE(x) (sizeof(x) / sizeof((x)[0])) + +Similarly, if you need to calculate the size of some structure member, use + +.. code-block:: c + + #define FIELD_SIZEOF(t, f) (sizeof(((t*)0)->f)) + +There are also min() and max() macros that do strict type checking if you +need them. Feel free to peruse that header file to see what else is already +defined that you shouldn't reproduce in your code. + + +18) Editor modelines and other cruft +------------------------------------ + +Some editors can interpret configuration information embedded in source files, +indicated with special markers. For example, emacs interprets lines marked +like this: + +.. code-block:: c + + -*- mode: c -*- + +Or like this: + +.. code-block:: c + + /* + Local Variables: + compile-command: "gcc -DMAGIC_DEBUG_FLAG foo.c" + End: + */ + +Vim interprets markers that look like this: + +.. code-block:: c + + /* vim:set sw=8 noet */ + +Do not include any of these in source files. People have their own personal +editor configurations, and your source files should not override them. This +includes markers for indentation and mode configuration. People may use their +own custom mode, or may have some other magic method for making indentation +work correctly. + + +19) Inline assembly +------------------- + +In architecture-specific code, you may need to use inline assembly to interface +with CPU or platform functionality. Don't hesitate to do so when necessary. +However, don't use inline assembly gratuitously when C can do the job. You can +and should poke hardware from C when possible. + +Consider writing simple helper functions that wrap common bits of inline +assembly, rather than repeatedly writing them with slight variations. Remember +that inline assembly can use C parameters. + +Large, non-trivial assembly functions should go in .S files, with corresponding +C prototypes defined in C header files. The C prototypes for assembly +functions should use ``asmlinkage``. + +You may need to mark your asm statement as volatile, to prevent GCC from +removing it if GCC doesn't notice any side effects. You don't always need to +do so, though, and doing so unnecessarily can limit optimization. + +When writing a single inline assembly statement containing multiple +instructions, put each instruction on a separate line in a separate quoted +string, and end each string except the last with \n\t to properly indent the +next instruction in the assembly output: + +.. code-block:: c + + asm ("magic %reg1, #42\n\t" + "more_magic %reg2, %reg3" + : /* outputs */ : /* inputs */ : /* clobbers */); + + +20) Conditional Compilation +--------------------------- + +Wherever possible, don't use preprocessor conditionals (#if, #ifdef) in .c +files; doing so makes code harder to read and logic harder to follow. Instead, +use such conditionals in a header file defining functions for use in those .c +files, providing no-op stub versions in the #else case, and then call those +functions unconditionally from .c files. The compiler will avoid generating +any code for the stub calls, producing identical results, but the logic will +remain easy to follow. + +Prefer to compile out entire functions, rather than portions of functions or +portions of expressions. Rather than putting an ifdef in an expression, factor +out part or all of the expression into a separate helper function and apply the +conditional to that function. + +If you have a function or variable which may potentially go unused in a +particular configuration, and the compiler would warn about its definition +going unused, mark the definition as __maybe_unused rather than wrapping it in +a preprocessor conditional. (However, if a function or variable *always* goes +unused, delete it.) + +Within code, where possible, use the IS_ENABLED macro to convert a Kconfig +symbol into a C boolean expression, and use it in a normal C conditional: + +.. code-block:: c + + if (IS_ENABLED(CONFIG_SOMETHING)) { + ... + } + +The compiler will constant-fold the conditional away, and include or exclude +the block of code just as with an #ifdef, so this will not add any runtime +overhead. However, this approach still allows the C compiler to see the code +inside the block, and check it for correctness (syntax, types, symbol +references, etc). Thus, you still have to use an #ifdef if the code inside the +block references symbols that will not exist if the condition is not met. + +At the end of any non-trivial #if or #ifdef block (more than a few lines), +place a comment after the #endif on the same line, noting the conditional +expression used. For instance: + +.. code-block:: c + + #ifdef CONFIG_SOMETHING + ... + #endif /* CONFIG_SOMETHING */ + + +Appendix I) References +---------------------- + +The C Programming Language, Second Edition +by Brian W. Kernighan and Dennis M. Ritchie. +Prentice Hall, Inc., 1988. +ISBN 0-13-110362-8 (paperback), 0-13-110370-9 (hardback). + +The Practice of Programming +by Brian W. Kernighan and Rob Pike. +Addison-Wesley, Inc., 1999. +ISBN 0-201-61586-X. + +GNU manuals - where in compliance with K&R and this text - for cpp, gcc, +gcc internals and indent, all available from http://www.gnu.org/manual/ + +WG14 is the international standardization working group for the programming +language C, URL: http://www.open-std.org/JTC1/SC22/WG14/ + +Kernel CodingStyle, by greg@kroah.com at OLS 2002: +http://www.kroah.com/linux/talks/ols_2002_kernel_codingstyle_talk/html/ diff --git a/Documentation/process/email-clients.rst b/Documentation/process/email-clients.rst new file mode 100644 index 000000000000..ac892b30815e --- /dev/null +++ b/Documentation/process/email-clients.rst @@ -0,0 +1,319 @@ +.. _email_clients: + +Email clients info for Linux +============================ + +Git +--- + +These days most developers use ``git send-email`` instead of regular +email clients. The man page for this is quite good. On the receiving +end, maintainers use ``git am`` to apply the patches. + +If you are new to ``git`` then send your first patch to yourself. Save it +as raw text including all the headers. Run ``git am raw_email.txt`` and +then review the changelog with ``git log``. When that works then send +the patch to the appropriate mailing list(s). + +General Preferences +------------------- + +Patches for the Linux kernel are submitted via email, preferably as +inline text in the body of the email. Some maintainers accept +attachments, but then the attachments should have content-type +``text/plain``. However, attachments are generally frowned upon because +it makes quoting portions of the patch more difficult in the patch +review process. + +Email clients that are used for Linux kernel patches should send the +patch text untouched. For example, they should not modify or delete tabs +or spaces, even at the beginning or end of lines. + +Don't send patches with ``format=flowed``. This can cause unexpected +and unwanted line breaks. + +Don't let your email client do automatic word wrapping for you. +This can also corrupt your patch. + +Email clients should not modify the character set encoding of the text. +Emailed patches should be in ASCII or UTF-8 encoding only. +If you configure your email client to send emails with UTF-8 encoding, +you avoid some possible charset problems. + +Email clients should generate and maintain References: or In-Reply-To: +headers so that mail threading is not broken. + +Copy-and-paste (or cut-and-paste) usually does not work for patches +because tabs are converted to spaces. Using xclipboard, xclip, and/or +xcutsel may work, but it's best to test this for yourself or just avoid +copy-and-paste. + +Don't use PGP/GPG signatures in mail that contains patches. +This breaks many scripts that read and apply the patches. +(This should be fixable.) + +It's a good idea to send a patch to yourself, save the received message, +and successfully apply it with 'patch' before sending patches to Linux +mailing lists. + + +Some email client (MUA) hints +----------------------------- + +Here are some specific MUA configuration hints for editing and sending +patches for the Linux kernel. These are not meant to be complete +software package configuration summaries. + + +Legend: + +- TUI = text-based user interface +- GUI = graphical user interface + +Alpine (TUI) +************ + +Config options: + +In the :menuselection:`Sending Preferences` section: + +- :menuselection:`Do Not Send Flowed Text` must be ``enabled`` +- :menuselection:`Strip Whitespace Before Sending` must be ``disabled`` + +When composing the message, the cursor should be placed where the patch +should appear, and then pressing :kbd:`CTRL-R` let you specify the patch file +to insert into the message. + +Claws Mail (GUI) +**************** + +Works. Some people use this successfully for patches. + +To insert a patch use :menuselection:`Message-->Insert` File (:kbd:`CTRL-I`) +or an external editor. + +If the inserted patch has to be edited in the Claws composition window +"Auto wrapping" in +:menuselection:`Configuration-->Preferences-->Compose-->Wrapping` should be +disabled. + +Evolution (GUI) +*************** + +Some people use this successfully for patches. + +When composing mail select: Preformat + from :menuselection:`Format-->Paragraph Style-->Preformatted` (:kbd:`CTRL-7`) + or the toolbar + +Then use: +:menuselection:`Insert-->Text File...` (:kbd:`ALT-N x`) +to insert the patch. + +You can also ``diff -Nru old.c new.c | xclip``, select +:menuselection:`Preformat`, then paste with the middle button. + +Kmail (GUI) +*********** + +Some people use Kmail successfully for patches. + +The default setting of not composing in HTML is appropriate; do not +enable it. + +When composing an email, under options, uncheck "word wrap". The only +disadvantage is any text you type in the email will not be word-wrapped +so you will have to manually word wrap text before the patch. The easiest +way around this is to compose your email with word wrap enabled, then save +it as a draft. Once you pull it up again from your drafts it is now hard +word-wrapped and you can uncheck "word wrap" without losing the existing +wrapping. + +At the bottom of your email, put the commonly-used patch delimiter before +inserting your patch: three hyphens (``---``). + +Then from the :menuselection:`Message` menu item, select insert file and +choose your patch. +As an added bonus you can customise the message creation toolbar menu +and put the :menuselection:`insert file` icon there. + +Make the composer window wide enough so that no lines wrap. As of +KMail 1.13.5 (KDE 4.5.4), KMail will apply word wrapping when sending +the email if the lines wrap in the composer window. Having word wrapping +disabled in the Options menu isn't enough. Thus, if your patch has very +long lines, you must make the composer window very wide before sending +the email. See: https://bugs.kde.org/show_bug.cgi?id=174034 + +You can safely GPG sign attachments, but inlined text is preferred for +patches so do not GPG sign them. Signing patches that have been inserted +as inlined text will make them tricky to extract from their 7-bit encoding. + +If you absolutely must send patches as attachments instead of inlining +them as text, right click on the attachment and select properties, and +highlight :menuselection:`Suggest automatic display` to make the attachment +inlined to make it more viewable. + +When saving patches that are sent as inlined text, select the email that +contains the patch from the message list pane, right click and select +:menuselection:`save as`. You can use the whole email unmodified as a patch +if it was properly composed. There is no option currently to save the email +when you are actually viewing it in its own window -- there has been a request +filed at kmail's bugzilla and hopefully this will be addressed. Emails are +saved as read-write for user only so you will have to chmod them to make them +group and world readable if you copy them elsewhere. + +Lotus Notes (GUI) +***************** + +Run away from it. + +Mutt (TUI) +********** + +Plenty of Linux developers use ``mutt``, so it must work pretty well. + +Mutt doesn't come with an editor, so whatever editor you use should be +used in a way that there are no automatic linebreaks. Most editors have +an :menuselection:`insert file` option that inserts the contents of a file +unaltered. + +To use ``vim`` with mutt:: + + set editor="vi" + +If using xclip, type the command:: + + :set paste + +before middle button or shift-insert or use:: + + :r filename + +if you want to include the patch inline. +(a)ttach works fine without ``set paste``. + +You can also generate patches with ``git format-patch`` and then use Mutt +to send them:: + + $ mutt -H 0001-some-bug-fix.patch + +Config options: + +It should work with default settings. +However, it's a good idea to set the ``send_charset`` to:: + + set send_charset="us-ascii:utf-8" + +Mutt is highly customizable. Here is a minimum configuration to start +using Mutt to send patches through Gmail:: + + # .muttrc + # ================ IMAP ==================== + set imap_user = 'yourusername@gmail.com' + set imap_pass = 'yourpassword' + set spoolfile = imaps://imap.gmail.com/INBOX + set folder = imaps://imap.gmail.com/ + set record="imaps://imap.gmail.com/[Gmail]/Sent Mail" + set postponed="imaps://imap.gmail.com/[Gmail]/Drafts" + set mbox="imaps://imap.gmail.com/[Gmail]/All Mail" + + # ================ SMTP ==================== + set smtp_url = "smtp://username@smtp.gmail.com:587/" + set smtp_pass = $imap_pass + set ssl_force_tls = yes # Require encrypted connection + + # ================ Composition ==================== + set editor = `echo \$EDITOR` + set edit_headers = yes # See the headers when editing + set charset = UTF-8 # value of $LANG; also fallback for send_charset + # Sender, email address, and sign-off line must match + unset use_domain # because joe@localhost is just embarrassing + set realname = "YOUR NAME" + set from = "username@gmail.com" + set use_from = yes + +The Mutt docs have lots more information: + + http://dev.mutt.org/trac/wiki/UseCases/Gmail + + http://dev.mutt.org/doc/manual.html + +Pine (TUI) +********** + +Pine has had some whitespace truncation issues in the past, but these +should all be fixed now. + +Use alpine (pine's successor) if you can. + +Config options: + +- ``quell-flowed-text`` is needed for recent versions +- the ``no-strip-whitespace-before-send`` option is needed + + +Sylpheed (GUI) +************** + +- Works well for inlining text (or using attachments). +- Allows use of an external editor. +- Is slow on large folders. +- Won't do TLS SMTP auth over a non-SSL connection. +- Has a helpful ruler bar in the compose window. +- Adding addresses to address book doesn't understand the display name + properly. + +Thunderbird (GUI) +***************** + +Thunderbird is an Outlook clone that likes to mangle text, but there are ways +to coerce it into behaving. + +- Allow use of an external editor: + The easiest thing to do with Thunderbird and patches is to use an + "external editor" extension and then just use your favorite ``$EDITOR`` + for reading/merging patches into the body text. To do this, download + and install the extension, then add a button for it using + :menuselection:`View-->Toolbars-->Customize...` and finally just click on it + when in the :menuselection:`Compose` dialog. + + Please note that "external editor" requires that your editor must not + fork, or in other words, the editor must not return before closing. + You may have to pass additional flags or change the settings of your + editor. Most notably if you are using gvim then you must pass the -f + option to gvim by putting ``/usr/bin/gvim -f`` (if the binary is in + ``/usr/bin``) to the text editor field in :menuselection:`external editor` + settings. If you are using some other editor then please read its manual + to find out how to do this. + +To beat some sense out of the internal editor, do this: + +- Edit your Thunderbird config settings so that it won't use ``format=flowed``. + Go to :menuselection:`edit-->preferences-->advanced-->config editor` to bring up + the thunderbird's registry editor. + +- Set ``mailnews.send_plaintext_flowed`` to ``false`` + +- Set ``mailnews.wraplength`` from ``72`` to ``0`` + +- :menuselection:`View-->Message Body As-->Plain Text` + +- :menuselection:`View-->Character Encoding-->Unicode (UTF-8)` + +TkRat (GUI) +*********** + +Works. Use "Insert file..." or external editor. + +Gmail (Web GUI) +*************** + +Does not work for sending patches. + +Gmail web client converts tabs to spaces automatically. + +At the same time it wraps lines every 78 chars with CRLF style line breaks +although tab2space problem can be solved with external editor. + +Another problem is that Gmail will base64-encode any message that has a +non-ASCII character. That includes things like European names. diff --git a/Documentation/process/howto.rst b/Documentation/process/howto.rst new file mode 100644 index 000000000000..5f042349f987 --- /dev/null +++ b/Documentation/process/howto.rst @@ -0,0 +1,652 @@ +HOWTO do Linux kernel development +================================= + +This is the be-all, end-all document on this topic. It contains +instructions on how to become a Linux kernel developer and how to learn +to work with the Linux kernel development community. It tries to not +contain anything related to the technical aspects of kernel programming, +but will help point you in the right direction for that. + +If anything in this document becomes out of date, please send in patches +to the maintainer of this file, who is listed at the bottom of the +document. + + +Introduction +------------ + +So, you want to learn how to become a Linux kernel developer? Or you +have been told by your manager, "Go write a Linux driver for this +device." This document's goal is to teach you everything you need to +know to achieve this by describing the process you need to go through, +and hints on how to work with the community. It will also try to +explain some of the reasons why the community works like it does. + +The kernel is written mostly in C, with some architecture-dependent +parts written in assembly. A good understanding of C is required for +kernel development. Assembly (any architecture) is not required unless +you plan to do low-level development for that architecture. Though they +are not a good substitute for a solid C education and/or years of +experience, the following books are good for, if anything, reference: + + - "The C Programming Language" by Kernighan and Ritchie [Prentice Hall] + - "Practical C Programming" by Steve Oualline [O'Reilly] + - "C: A Reference Manual" by Harbison and Steele [Prentice Hall] + +The kernel is written using GNU C and the GNU toolchain. While it +adheres to the ISO C89 standard, it uses a number of extensions that are +not featured in the standard. The kernel is a freestanding C +environment, with no reliance on the standard C library, so some +portions of the C standard are not supported. Arbitrary long long +divisions and floating point are not allowed. It can sometimes be +difficult to understand the assumptions the kernel has on the toolchain +and the extensions that it uses, and unfortunately there is no +definitive reference for them. Please check the gcc info pages (`info +gcc`) for some information on them. + +Please remember that you are trying to learn how to work with the +existing development community. It is a diverse group of people, with +high standards for coding, style and procedure. These standards have +been created over time based on what they have found to work best for +such a large and geographically dispersed team. Try to learn as much as +possible about these standards ahead of time, as they are well +documented; do not expect people to adapt to you or your company's way +of doing things. + + +Legal Issues +------------ + +The Linux kernel source code is released under the GPL. Please see the +file, COPYING, in the main directory of the source tree, for details on +the license. If you have further questions about the license, please +contact a lawyer, and do not ask on the Linux kernel mailing list. The +people on the mailing lists are not lawyers, and you should not rely on +their statements on legal matters. + +For common questions and answers about the GPL, please see: + + https://www.gnu.org/licenses/gpl-faq.html + + +Documentation +------------- + +The Linux kernel source tree has a large range of documents that are +invaluable for learning how to interact with the kernel community. When +new features are added to the kernel, it is recommended that new +documentation files are also added which explain how to use the feature. +When a kernel change causes the interface that the kernel exposes to +userspace to change, it is recommended that you send the information or +a patch to the manual pages explaining the change to the manual pages +maintainer at mtk.manpages@gmail.com, and CC the list +linux-api@vger.kernel.org. + +Here is a list of files that are in the kernel source tree that are +required reading: + + README + This file gives a short background on the Linux kernel and describes + what is necessary to do to configure and build the kernel. People + who are new to the kernel should start here. + + :ref:`Documentation/Changes ` + This file gives a list of the minimum levels of various software + packages that are necessary to build and run the kernel + successfully. + + :ref:`Documentation/CodingStyle ` + This describes the Linux kernel coding style, and some of the + rationale behind it. All new code is expected to follow the + guidelines in this document. Most maintainers will only accept + patches if these rules are followed, and many people will only + review code if it is in the proper style. + + :ref:`Documentation/SubmittingPatches ` and :ref:`Documentation/SubmittingDrivers ` + These files describe in explicit detail how to successfully create + and send a patch, including (but not limited to): + + - Email contents + - Email format + - Who to send it to + + Following these rules will not guarantee success (as all patches are + subject to scrutiny for content and style), but not following them + will almost always prevent it. + + Other excellent descriptions of how to create patches properly are: + + "The Perfect Patch" + https://www.ozlabs.org/~akpm/stuff/tpp.txt + + "Linux kernel patch submission format" + http://linux.yyz.us/patch-format.html + + :ref:`Documentation/stable_api_nonsense.txt ` + This file describes the rationale behind the conscious decision to + not have a stable API within the kernel, including things like: + + - Subsystem shim-layers (for compatibility?) + - Driver portability between Operating Systems. + - Mitigating rapid change within the kernel source tree (or + preventing rapid change) + + This document is crucial for understanding the Linux development + philosophy and is very important for people moving to Linux from + development on other Operating Systems. + + :ref:`Documentation/SecurityBugs ` + If you feel you have found a security problem in the Linux kernel, + please follow the steps in this document to help notify the kernel + developers, and help solve the issue. + + :ref:`Documentation/ManagementStyle ` + This document describes how Linux kernel maintainers operate and the + shared ethos behind their methodologies. This is important reading + for anyone new to kernel development (or anyone simply curious about + it), as it resolves a lot of common misconceptions and confusion + about the unique behavior of kernel maintainers. + + :ref:`Documentation/stable_kernel_rules.txt ` + This file describes the rules on how the stable kernel releases + happen, and what to do if you want to get a change into one of these + releases. + + :ref:`Documentation/kernel-docs.txt ` + A list of external documentation that pertains to kernel + development. Please consult this list if you do not find what you + are looking for within the in-kernel documentation. + + :ref:`Documentation/applying-patches.txt ` + A good introduction describing exactly what a patch is and how to + apply it to the different development branches of the kernel. + +The kernel also has a large number of documents that can be +automatically generated from the source code itself or from +ReStructuredText markups (ReST), like this one. This includes a +full description of the in-kernel API, and rules on how to handle +locking properly. + +All such documents can be generated as PDF or HTML by running:: + + make pdfdocs + make htmldocs + +respectively from the main kernel source directory. + +The documents that uses ReST markup will be generated at Documentation/output. +They can also be generated on LaTeX and ePub formats with:: + + make latexdocs + make epubdocs + +Currently, there are some documents written on DocBook that are in +the process of conversion to ReST. Such documents will be created in the +Documentation/DocBook/ directory and can be generated also as +Postscript or man pages by running:: + + make psdocs + make mandocs + +Becoming A Kernel Developer +--------------------------- + +If you do not know anything about Linux kernel development, you should +look at the Linux KernelNewbies project: + + https://kernelnewbies.org + +It consists of a helpful mailing list where you can ask almost any type +of basic kernel development question (make sure to search the archives +first, before asking something that has already been answered in the +past.) It also has an IRC channel that you can use to ask questions in +real-time, and a lot of helpful documentation that is useful for +learning about Linux kernel development. + +The website has basic information about code organization, subsystems, +and current projects (both in-tree and out-of-tree). It also describes +some basic logistical information, like how to compile a kernel and +apply a patch. + +If you do not know where you want to start, but you want to look for +some task to start doing to join into the kernel development community, +go to the Linux Kernel Janitor's project: + + https://kernelnewbies.org/KernelJanitors + +It is a great place to start. It describes a list of relatively simple +problems that need to be cleaned up and fixed within the Linux kernel +source tree. Working with the developers in charge of this project, you +will learn the basics of getting your patch into the Linux kernel tree, +and possibly be pointed in the direction of what to go work on next, if +you do not already have an idea. + +If you already have a chunk of code that you want to put into the kernel +tree, but need some help getting it in the proper form, the +kernel-mentors project was created to help you out with this. It is a +mailing list, and can be found at: + + https://selenic.com/mailman/listinfo/kernel-mentors + +Before making any actual modifications to the Linux kernel code, it is +imperative to understand how the code in question works. For this +purpose, nothing is better than reading through it directly (most tricky +bits are commented well), perhaps even with the help of specialized +tools. One such tool that is particularly recommended is the Linux +Cross-Reference project, which is able to present source code in a +self-referential, indexed webpage format. An excellent up-to-date +repository of the kernel code may be found at: + + http://lxr.free-electrons.com/ + + +The development process +----------------------- + +Linux kernel development process currently consists of a few different +main kernel "branches" and lots of different subsystem-specific kernel +branches. These different branches are: + + - main 4.x kernel tree + - 4.x.y -stable kernel tree + - 4.x -git kernel patches + - subsystem specific kernel trees and patches + - the 4.x -next kernel tree for integration tests + +4.x kernel tree +----------------- +4.x kernels are maintained by Linus Torvalds, and can be found on +https://kernel.org in the pub/linux/kernel/v4.x/ directory. Its development +process is as follows: + + - As soon as a new kernel is released a two weeks window is open, + during this period of time maintainers can submit big diffs to + Linus, usually the patches that have already been included in the + -next kernel for a few weeks. The preferred way to submit big changes + is using git (the kernel's source management tool, more information + can be found at https://git-scm.com/) but plain patches are also just + fine. + - After two weeks a -rc1 kernel is released it is now possible to push + only patches that do not include new features that could affect the + stability of the whole kernel. Please note that a whole new driver + (or filesystem) might be accepted after -rc1 because there is no + risk of causing regressions with such a change as long as the change + is self-contained and does not affect areas outside of the code that + is being added. git can be used to send patches to Linus after -rc1 + is released, but the patches need to also be sent to a public + mailing list for review. + - A new -rc is released whenever Linus deems the current git tree to + be in a reasonably sane state adequate for testing. The goal is to + release a new -rc kernel every week. + - Process continues until the kernel is considered "ready", the + process should last around 6 weeks. + +It is worth mentioning what Andrew Morton wrote on the linux-kernel +mailing list about kernel releases: + + *"Nobody knows when a kernel will be released, because it's + released according to perceived bug status, not according to a + preconceived timeline."* + +4.x.y -stable kernel tree +------------------------- +Kernels with 3-part versions are -stable kernels. They contain +relatively small and critical fixes for security problems or significant +regressions discovered in a given 4.x kernel. + +This is the recommended branch for users who want the most recent stable +kernel and are not interested in helping test development/experimental +versions. + +If no 4.x.y kernel is available, then the highest numbered 4.x +kernel is the current stable kernel. + +4.x.y are maintained by the "stable" team , and +are released as needs dictate. The normal release period is approximately +two weeks, but it can be longer if there are no pressing problems. A +security-related problem, instead, can cause a release to happen almost +instantly. + +The file Documentation/stable_kernel_rules.txt in the kernel tree +documents what kinds of changes are acceptable for the -stable tree, and +how the release process works. + +4.x -git patches +---------------- +These are daily snapshots of Linus' kernel tree which are managed in a +git repository (hence the name.) These patches are usually released +daily and represent the current state of Linus' tree. They are more +experimental than -rc kernels since they are generated automatically +without even a cursory glance to see if they are sane. + +Subsystem Specific kernel trees and patches +------------------------------------------- +The maintainers of the various kernel subsystems --- and also many +kernel subsystem developers --- expose their current state of +development in source repositories. That way, others can see what is +happening in the different areas of the kernel. In areas where +development is rapid, a developer may be asked to base his submissions +onto such a subsystem kernel tree so that conflicts between the +submission and other already ongoing work are avoided. + +Most of these repositories are git trees, but there are also other SCMs +in use, or patch queues being published as quilt series. Addresses of +these subsystem repositories are listed in the MAINTAINERS file. Many +of them can be browsed at https://git.kernel.org/. + +Before a proposed patch is committed to such a subsystem tree, it is +subject to review which primarily happens on mailing lists (see the +respective section below). For several kernel subsystems, this review +process is tracked with the tool patchwork. Patchwork offers a web +interface which shows patch postings, any comments on a patch or +revisions to it, and maintainers can mark patches as under review, +accepted, or rejected. Most of these patchwork sites are listed at +https://patchwork.kernel.org/. + +4.x -next kernel tree for integration tests +------------------------------------------- +Before updates from subsystem trees are merged into the mainline 4.x +tree, they need to be integration-tested. For this purpose, a special +testing repository exists into which virtually all subsystem trees are +pulled on an almost daily basis: + + https://git.kernel.org/?p=linux/kernel/git/next/linux-next.git + +This way, the -next kernel gives a summary outlook onto what will be +expected to go into the mainline kernel at the next merge period. +Adventurous testers are very welcome to runtime-test the -next kernel. + + +Bug Reporting +------------- + +https://bugzilla.kernel.org is where the Linux kernel developers track kernel +bugs. Users are encouraged to report all bugs that they find in this +tool. For details on how to use the kernel bugzilla, please see: + + https://bugzilla.kernel.org/page.cgi?id=faq.html + +The file REPORTING-BUGS in the main kernel source directory has a good +template for how to report a possible kernel bug, and details what kind +of information is needed by the kernel developers to help track down the +problem. + + +Managing bug reports +-------------------- + +One of the best ways to put into practice your hacking skills is by fixing +bugs reported by other people. Not only you will help to make the kernel +more stable, you'll learn to fix real world problems and you will improve +your skills, and other developers will be aware of your presence. Fixing +bugs is one of the best ways to get merits among other developers, because +not many people like wasting time fixing other people's bugs. + +To work in the already reported bug reports, go to https://bugzilla.kernel.org. +If you want to be advised of the future bug reports, you can subscribe to the +bugme-new mailing list (only new bug reports are mailed here) or to the +bugme-janitor mailing list (every change in the bugzilla is mailed here) + + https://lists.linux-foundation.org/mailman/listinfo/bugme-new + + https://lists.linux-foundation.org/mailman/listinfo/bugme-janitors + + + +Mailing lists +------------- + +As some of the above documents describe, the majority of the core kernel +developers participate on the Linux Kernel Mailing list. Details on how +to subscribe and unsubscribe from the list can be found at: + + http://vger.kernel.org/vger-lists.html#linux-kernel + +There are archives of the mailing list on the web in many different +places. Use a search engine to find these archives. For example: + + http://dir.gmane.org/gmane.linux.kernel + +It is highly recommended that you search the archives about the topic +you want to bring up, before you post it to the list. A lot of things +already discussed in detail are only recorded at the mailing list +archives. + +Most of the individual kernel subsystems also have their own separate +mailing list where they do their development efforts. See the +MAINTAINERS file for a list of what these lists are for the different +groups. + +Many of the lists are hosted on kernel.org. Information on them can be +found at: + + http://vger.kernel.org/vger-lists.html + +Please remember to follow good behavioral habits when using the lists. +Though a bit cheesy, the following URL has some simple guidelines for +interacting with the list (or any list): + + http://www.albion.com/netiquette/ + +If multiple people respond to your mail, the CC: list of recipients may +get pretty large. Don't remove anybody from the CC: list without a good +reason, or don't reply only to the list address. Get used to receiving the +mail twice, one from the sender and the one from the list, and don't try +to tune that by adding fancy mail-headers, people will not like it. + +Remember to keep the context and the attribution of your replies intact, +keep the "John Kernelhacker wrote ...:" lines at the top of your reply, and +add your statements between the individual quoted sections instead of +writing at the top of the mail. + +If you add patches to your mail, make sure they are plain readable text +as stated in Documentation/SubmittingPatches. +Kernel developers don't want to deal with +attachments or compressed patches; they may want to comment on +individual lines of your patch, which works only that way. Make sure you +use a mail program that does not mangle spaces and tab characters. A +good first test is to send the mail to yourself and try to apply your +own patch by yourself. If that doesn't work, get your mail program fixed +or change it until it works. + +Above all, please remember to show respect to other subscribers. + + +Working with the community +-------------------------- + +The goal of the kernel community is to provide the best possible kernel +there is. When you submit a patch for acceptance, it will be reviewed +on its technical merits and those alone. So, what should you be +expecting? + + - criticism + - comments + - requests for change + - requests for justification + - silence + +Remember, this is part of getting your patch into the kernel. You have +to be able to take criticism and comments about your patches, evaluate +them at a technical level and either rework your patches or provide +clear and concise reasoning as to why those changes should not be made. +If there are no responses to your posting, wait a few days and try +again, sometimes things get lost in the huge volume. + +What should you not do? + + - expect your patch to be accepted without question + - become defensive + - ignore comments + - resubmit the patch without making any of the requested changes + +In a community that is looking for the best technical solution possible, +there will always be differing opinions on how beneficial a patch is. +You have to be cooperative, and willing to adapt your idea to fit within +the kernel. Or at least be willing to prove your idea is worth it. +Remember, being wrong is acceptable as long as you are willing to work +toward a solution that is right. + +It is normal that the answers to your first patch might simply be a list +of a dozen things you should correct. This does **not** imply that your +patch will not be accepted, and it is **not** meant against you +personally. Simply correct all issues raised against your patch and +resend it. + + +Differences between the kernel community and corporate structures +----------------------------------------------------------------- + +The kernel community works differently than most traditional corporate +development environments. Here are a list of things that you can try to +do to avoid problems: + + Good things to say regarding your proposed changes: + + - "This solves multiple problems." + - "This deletes 2000 lines of code." + - "Here is a patch that explains what I am trying to describe." + - "I tested it on 5 different architectures..." + - "Here is a series of small patches that..." + - "This increases performance on typical machines..." + + Bad things you should avoid saying: + + - "We did it this way in AIX/ptx/Solaris, so therefore it must be + good..." + - "I've being doing this for 20 years, so..." + - "This is required for my company to make money" + - "This is for our Enterprise product line." + - "Here is my 1000 page design document that describes my idea" + - "I've been working on this for 6 months..." + - "Here's a 5000 line patch that..." + - "I rewrote all of the current mess, and here it is..." + - "I have a deadline, and this patch needs to be applied now." + +Another way the kernel community is different than most traditional +software engineering work environments is the faceless nature of +interaction. One benefit of using email and irc as the primary forms of +communication is the lack of discrimination based on gender or race. +The Linux kernel work environment is accepting of women and minorities +because all you are is an email address. The international aspect also +helps to level the playing field because you can't guess gender based on +a person's name. A man may be named Andrea and a woman may be named Pat. +Most women who have worked in the Linux kernel and have expressed an +opinion have had positive experiences. + +The language barrier can cause problems for some people who are not +comfortable with English. A good grasp of the language can be needed in +order to get ideas across properly on mailing lists, so it is +recommended that you check your emails to make sure they make sense in +English before sending them. + + +Break up your changes +--------------------- + +The Linux kernel community does not gladly accept large chunks of code +dropped on it all at once. The changes need to be properly introduced, +discussed, and broken up into tiny, individual portions. This is almost +the exact opposite of what companies are used to doing. Your proposal +should also be introduced very early in the development process, so that +you can receive feedback on what you are doing. It also lets the +community feel that you are working with them, and not simply using them +as a dumping ground for your feature. However, don't send 50 emails at +one time to a mailing list, your patch series should be smaller than +that almost all of the time. + +The reasons for breaking things up are the following: + +1) Small patches increase the likelihood that your patches will be + applied, since they don't take much time or effort to verify for + correctness. A 5 line patch can be applied by a maintainer with + barely a second glance. However, a 500 line patch may take hours to + review for correctness (the time it takes is exponentially + proportional to the size of the patch, or something). + + Small patches also make it very easy to debug when something goes + wrong. It's much easier to back out patches one by one than it is + to dissect a very large patch after it's been applied (and broken + something). + +2) It's important not only to send small patches, but also to rewrite + and simplify (or simply re-order) patches before submitting them. + +Here is an analogy from kernel developer Al Viro: + + *"Think of a teacher grading homework from a math student. The + teacher does not want to see the student's trials and errors + before they came up with the solution. They want to see the + cleanest, most elegant answer. A good student knows this, and + would never submit her intermediate work before the final + solution.* + + *The same is true of kernel development. The maintainers and + reviewers do not want to see the thought process behind the + solution to the problem one is solving. They want to see a + simple and elegant solution."* + +It may be challenging to keep the balance between presenting an elegant +solution and working together with the community and discussing your +unfinished work. Therefore it is good to get early in the process to +get feedback to improve your work, but also keep your changes in small +chunks that they may get already accepted, even when your whole task is +not ready for inclusion now. + +Also realize that it is not acceptable to send patches for inclusion +that are unfinished and will be "fixed up later." + + +Justify your change +------------------- + +Along with breaking up your patches, it is very important for you to let +the Linux community know why they should add this change. New features +must be justified as being needed and useful. + + +Document your change +-------------------- + +When sending in your patches, pay special attention to what you say in +the text in your email. This information will become the ChangeLog +information for the patch, and will be preserved for everyone to see for +all time. It should describe the patch completely, containing: + + - why the change is necessary + - the overall design approach in the patch + - implementation details + - testing results + +For more details on what this should all look like, please see the +ChangeLog section of the document: + + "The Perfect Patch" + http://www.ozlabs.org/~akpm/stuff/tpp.txt + + +All of these things are sometimes very hard to do. It can take years to +perfect these practices (if at all). It's a continuous process of +improvement that requires a lot of patience and determination. But +don't give up, it's possible. Many have done it before, and each had to +start exactly where you are now. + + + + +---------- + +Thanks to Paolo Ciarrocchi who allowed the "Development Process" +(https://lwn.net/Articles/94386/) section +to be based on text he had written, and to Randy Dunlap and Gerrit +Huizenga for some of the list of things you should and should not say. +Also thanks to Pat Mochel, Hanna Linder, Randy Dunlap, Kay Sievers, +Vojtech Pavlik, Jan Kara, Josh Boyer, Kees Cook, Andrew Morton, Andi +Kleen, Vadim Lobanov, Jesper Juhl, Adrian Bunk, Keri Harris, Frans Pop, +David A. Wheeler, Junio Hamano, Michael Kerrisk, and Alex Shepard for +their review, comments, and contributions. Without their help, this +document would not have been possible. + + + +Maintainer: Greg Kroah-Hartman diff --git a/Documentation/process/index.rst b/Documentation/process/index.rst index c37475d91090..6ee818752474 100644 --- a/Documentation/process/index.rst +++ b/Documentation/process/index.rst @@ -1,3 +1,9 @@ +.. raw:: latex + + \renewcommand\thesection* + \renewcommand\thesubsection* + + Linux Kernel Development Documentation ====================================== @@ -6,4 +12,21 @@ Contents: .. toctree:: :maxdepth: 2 + howto + changes + coding-style + submitting-patches + submitting-drivers + stable-api-nonsense + management-style + stable-kernel-rules + kernel-docs + applying-patches + email-clients + submit-checklist + code-of-conflict + adding-syscalls + magic-number + volatile-considered-harmful + development-process diff --git a/Documentation/process/kernel-docs.rst b/Documentation/process/kernel-docs.rst new file mode 100644 index 000000000000..05a7857a4a83 --- /dev/null +++ b/Documentation/process/kernel-docs.rst @@ -0,0 +1,652 @@ +.. _kernel_docs: + +Index of Documentation for People Interested in Writing and/or Understanding the Linux Kernel +============================================================================================= + + Juan-Mariano de Goyeneche + +The need for a document like this one became apparent in the +linux-kernel mailing list as the same questions, asking for pointers +to information, appeared again and again. + +Fortunately, as more and more people get to GNU/Linux, more and more +get interested in the Kernel. But reading the sources is not always +enough. It is easy to understand the code, but miss the concepts, the +philosophy and design decisions behind this code. + +Unfortunately, not many documents are available for beginners to +start. And, even if they exist, there was no "well-known" place which +kept track of them. These lines try to cover this lack. All documents +available on line known by the author are listed, while some reference +books are also mentioned. + +PLEASE, if you know any paper not listed here or write a new document, +send me an e-mail, and I'll include a reference to it here. Any +corrections, ideas or comments are also welcomed. + +The papers that follow are listed in no particular order. All are +cataloged with the following fields: the document's "Title", the +"Author"/s, the "URL" where they can be found, some "Keywords" helpful +when searching for specific topics, and a brief "Description" of the +Document. + +Enjoy! + +.. note:: + + The documents on each section of this document are ordered by its + published date, from the newest to the oldest. + +Docs at the Linux Kernel tree +----------------------------- + +The DocBook books should be built with ``make {htmldocs | psdocs | pdfdocs}``. +The Sphinx books should be built with ``make {htmldocs | pdfdocs | epubdocs}``. + + * Name: **linux/Documentation** + + :Author: Many. + :Location: Documentation/ + :Keywords: text files, Sphinx, DocBook. + :Description: Documentation that comes with the kernel sources, + inside the Documentation directory. Some pages from this document + (including this document itself) have been moved there, and might + be more up to date than the web version. + + * Title: **The Kernel Hacking HOWTO** + + :Author: Various Talented People, and Rusty. + :Location: Documentation/DocBook/kernel-hacking.tmpl + :Keywords: HOWTO, kernel contexts, deadlock, locking, modules, + symbols, return conventions. + :Description: From the Introduction: "Please understand that I + never wanted to write this document, being grossly underqualified, + but I always wanted to read it, and this was the only way. I + simply explain some best practices, and give reading entry-points + into the kernel sources. I avoid implementation details: that's + what the code is for, and I ignore whole tracts of useful + routines. This document assumes familiarity with C, and an + understanding of what the kernel is, and how it is used. It was + originally written for the 2.3 kernels, but nearly all of it + applies to 2.2 too; 2.0 is slightly different". + + * Title: **Linux Kernel Locking HOWTO** + + :Author: Various Talented People, and Rusty. + :Location: Documentation/DocBook/kernel-locking.tmpl + :Keywords: locks, locking, spinlock, semaphore, atomic, race + condition, bottom halves, tasklets, softirqs. + :Description: The title says it all: document describing the + locking system in the Linux Kernel either in uniprocessor or SMP + systems. + :Notes: "It was originally written for the later (>2.3.47) 2.3 + kernels, but most of it applies to 2.2 too; 2.0 is slightly + different". Freely redistributable under the conditions of the GNU + General Public License. + +On-line docs +------------ + + * Title: **Linux Kernel Mailing List Glossary** + + :Author: various + :URL: http://kernelnewbies.org/glossary/ + :Date: rolling version + :Keywords: glossary, terms, linux-kernel. + :Description: From the introduction: "This glossary is intended as + a brief description of some of the acronyms and terms you may hear + during discussion of the Linux kernel". + + * Title: **Tracing the Way of Data in a TCP Connection through the Linux Kernel** + + :Author: Richard Sailer + :URL: https://archive.org/details/linux_kernel_data_flow_short_paper + :Date: 2016 + :Keywords: Linux Kernel Networking, TCP, tracing, ftrace + :Description: A seminar paper explaining ftrace and how to use it for + understanding linux kernel internals, + illustrated at tracing the way of a TCP packet through the kernel. + :Abstract: *This short paper outlines the usage of ftrace a tracing framework + as a tool to understand a running Linux system. + Having obtained a trace-log a kernel hacker can read and understand + source code more determined and with context. + In a detailed example this approach is demonstrated in tracing + and the way of data in a TCP Connection through the kernel. + Finally this trace-log is used as base for more a exact conceptual + exploration and description of the Linux TCP/IP implementation.* + + * Title: **On submitting kernel Patches** + + :Author: Andi Kleen + :URL: http://halobates.de/on-submitting-kernel-patches.pdf + :Date: 2008 + :Keywords: patches, review process, types of submissions, basic rules, case studies + :Description: This paper gives several experience values on what types of patches + there are and how likley they get merged. + :Abstract: + [...]. This paper examines some common problems for + submitting larger changes and some strategies to avoid problems. + + * Title: **Overview of the Virtual File System** + + :Author: Richard Gooch. + :URL: http://www.mjmwired.net/kernel/Documentation/filesystems/vfs.txt + :Date: 2007 + :Keywords: VFS, File System, mounting filesystems, opening files, + dentries, dcache. + :Description: Brief introduction to the Linux Virtual File System. + What is it, how it works, operations taken when opening a file or + mounting a file system and description of important data + structures explaining the purpose of each of their entries. + + * Title: **Linux Device Drivers, Third Edition** + + :Author: Jonathan Corbet, Alessandro Rubini, Greg Kroah-Hartman + :URL: http://lwn.net/Kernel/LDD3/ + :Date: 2005 + :Description: A 600-page book covering the (2.6.10) driver + programming API and kernel hacking in general. Available under the + Creative Commons Attribution-ShareAlike 2.0 license. + :note: You can also :ref:`purchase a copy from O'Reilly or elsewhere `. + + * Title: **Writing an ALSA Driver** + + :Author: Takashi Iwai + :URL: http://www.alsa-project.org/~iwai/writing-an-alsa-driver/index.html + :Date: 2005 + :Keywords: ALSA, sound, soundcard, driver, lowlevel, hardware. + :Description: Advanced Linux Sound Architecture for developers, + both at kernel and user-level sides. ALSA is the Linux kernel + sound architecture in the 2.6 kernel version. + + * Title: **Linux PCMCIA Programmer's Guide** + + :Author: David Hinds. + :URL: http://pcmcia-cs.sourceforge.net/ftp/doc/PCMCIA-PROG.html + :Date: 2003 + :Keywords: PCMCIA. + :Description: "This document describes how to write kernel device + drivers for the Linux PCMCIA Card Services interface. It also + describes how to write user-mode utilities for communicating with + Card Services. + + * Title: **Linux Kernel Module Programming Guide** + + :Author: Ori Pomerantz. + :URL: http://tldp.org/LDP/lkmpg/2.6/html/index.html + :Date: 2001 + :Keywords: modules, GPL book, /proc, ioctls, system calls, + interrupt handlers . + :Description: Very nice 92 pages GPL book on the topic of modules + programming. Lots of examples. + + * Title: **Global spinlock list and usage** + + :Author: Rick Lindsley. + :URL: http://lse.sourceforge.net/lockhier/global-spin-lock + :Date: 2001 + :Keywords: spinlock. + :Description: This is an attempt to document both the existence and + usage of the spinlocks in the Linux 2.4.5 kernel. Comprehensive + list of spinlocks showing when they are used, which functions + access them, how each lock is acquired, under what conditions it + is held, whether interrupts can occur or not while it is held... + + * Title: **A Linux vm README** + + :Author: Kanoj Sarcar. + :URL: http://kos.enix.org/pub/linux-vmm.html + :Date: 2001 + :Keywords: virtual memory, mm, pgd, vma, page, page flags, page + cache, swap cache, kswapd. + :Description: Telegraphic, short descriptions and definitions + relating the Linux virtual memory implementation. + + * Title: **Video4linux Drivers, Part 1: Video-Capture Device** + + :Author: Alan Cox. + :URL: http://www.linux-mag.com/id/406 + :Date: 2000 + :Keywords: video4linux, driver, video capture, capture devices, + camera driver. + :Description: The title says it all. + + * Title: **Video4linux Drivers, Part 2: Video-capture Devices** + + :Author: Alan Cox. + :URL: http://www.linux-mag.com/id/429 + :Date: 2000 + :Keywords: video4linux, driver, video capture, capture devices, + camera driver, control, query capabilities, capability, facility. + :Description: The title says it all. + + * Title: **Linux IP Networking. A Guide to the Implementation and Modification of the Linux Protocol Stack.** + + :Author: Glenn Herrin. + :URL: http://www.cs.unh.edu/cnrg/gherrin + :Date: 2000 + :Keywords: network, networking, protocol, IP, UDP, TCP, connection, + socket, receiving, transmitting, forwarding, routing, packets, + modules, /proc, sk_buff, FIB, tags. + :Description: Excellent paper devoted to the Linux IP Networking, + explaining anything from the kernel's to the user space + configuration tools' code. Very good to get a general overview of + the kernel networking implementation and understand all steps + packets follow from the time they are received at the network + device till they are delivered to applications. The studied kernel + code is from 2.2.14 version. Provides code for a working packet + dropper example. + + * Title: **How To Make Sure Your Driver Will Work On The Power Macintosh** + + :Author: Paul Mackerras. + :URL: http://www.linux-mag.com/id/261 + :Date: 1999 + :Keywords: Mac, Power Macintosh, porting, drivers, compatibility. + :Description: The title says it all. + + * Title: **An Introduction to SCSI Drivers** + + :Author: Alan Cox. + :URL: http://www.linux-mag.com/id/284 + :Date: 1999 + :Keywords: SCSI, device, driver. + :Description: The title says it all. + + * Title: **Advanced SCSI Drivers And Other Tales** + + :Author: Alan Cox. + :URL: http://www.linux-mag.com/id/307 + :Date: 1999 + :Keywords: SCSI, device, driver, advanced. + :Description: The title says it all. + + * Title: **Writing Linux Mouse Drivers** + + :Author: Alan Cox. + :URL: http://www.linux-mag.com/id/330 + :Date: 1999 + :Keywords: mouse, driver, gpm. + :Description: The title says it all. + + * Title: **More on Mouse Drivers** + + :Author: Alan Cox. + :URL: http://www.linux-mag.com/id/356 + :Date: 1999 + :Keywords: mouse, driver, gpm, races, asynchronous I/O. + :Description: The title still says it all. + + * Title: **Writing Video4linux Radio Driver** + + :Author: Alan Cox. + :URL: http://www.linux-mag.com/id/381 + :Date: 1999 + :Keywords: video4linux, driver, radio, radio devices. + :Description: The title says it all. + + * Title: **I/O Event Handling Under Linux** + + :Author: Richard Gooch. + :URL: http://web.mit.edu/~yandros/doc/io-events.html + :Date: 1999 + :Keywords: IO, I/O, select(2), poll(2), FDs, aio_read(2), readiness + event queues. + :Description: From the Introduction: "I/O Event handling is about + how your Operating System allows you to manage a large number of + open files (file descriptors in UNIX/POSIX, or FDs) in your + application. You want the OS to notify you when FDs become active + (have data ready to be read or are ready for writing). Ideally you + want a mechanism that is scalable. This means a large number of + inactive FDs cost very little in memory and CPU time to manage". + + * Title: **(nearly) Complete Linux Loadable Kernel Modules. The definitive guide for hackers, virus coders and system administrators.** + + :Author: pragmatic/THC. + :URL: http://packetstormsecurity.org/docs/hack/LKM_HACKING.html + :Date: 1999 + :Keywords: syscalls, intercept, hide, abuse, symbol table. + :Description: Interesting paper on how to abuse the Linux kernel in + order to intercept and modify syscalls, make + files/directories/processes invisible, become root, hijack ttys, + write kernel modules based virus... and solutions for admins to + avoid all those abuses. + :Notes: For 2.0.x kernels. Gives guidances to port it to 2.2.x + kernels. + + * Name: **Linux Virtual File System** + + :Author: Peter J. Braam. + :URL: http://www.coda.cs.cmu.edu/doc/talks/linuxvfs/ + :Date: 1998 + :Keywords: slides, VFS, inode, superblock, dentry, dcache. + :Description: Set of slides, presumably from a presentation on the + Linux VFS layer. Covers version 2.1.x, with dentries and the + dcache. + + * Title: **The Venus kernel interface** + + :Author: Peter J. Braam. + :URL: http://www.coda.cs.cmu.edu/doc/html/kernel-venus-protocol.html + :Date: 1998 + :Keywords: coda, filesystem, venus, cache manager. + :Description: "This document describes the communication between + Venus and kernel level file system code needed for the operation + of the Coda filesystem. This version document is meant to describe + the current interface (version 1.0) as well as improvements we + envisage". + + * Title: **Design and Implementation of the Second Extended Filesystem** + + :Author: Rémy Card, Theodore Ts'o, Stephen Tweedie. + :URL: http://web.mit.edu/tytso/www/linux/ext2intro.html + :Date: 1998 + :Keywords: ext2, linux fs history, inode, directory, link, devices, + VFS, physical structure, performance, benchmarks, ext2fs library, + ext2fs tools, e2fsck. + :Description: Paper written by three of the top ext2 hackers. + Covers Linux filesystems history, ext2 motivation, ext2 features, + design, physical structure on disk, performance, benchmarks, + e2fsck's passes description... A must read! + :Notes: This paper was first published in the Proceedings of the + First Dutch International Symposium on Linux, ISBN 90-367-0385-9. + + * Title: **The Linux RAID-1, 4, 5 Code** + + :Author: Ingo Molnar, Gadi Oxman and Miguel de Icaza. + :URL: http://www.linuxjournal.com/article.php?sid=2391 + :Date: 1997 + :Keywords: RAID, MD driver. + :Description: Linux Journal Kernel Korner article. Here is its + :Abstract: *A description of the implementation of the RAID-1, + RAID-4 and RAID-5 personalities of the MD device driver in the + Linux kernel, providing users with high performance and reliable, + secondary-storage capability using software*. + + * Title: **Linux Kernel Hackers' Guide** + + :Author: Michael K. Johnson. + :URL: http://www.tldp.org/LDP/khg/HyperNews/get/khg.html + :Date: 1997 + :Keywords: device drivers, files, VFS, kernel interface, character vs + block devices, hardware interrupts, scsi, DMA, access to user memory, + memory allocation, timers. + :Description: A guide designed to help you get up to speed on the + concepts that are not intuitevly obvious, and to document the internal + structures of Linux. + + * Title: **Dynamic Kernels: Modularized Device Drivers** + + :Author: Alessandro Rubini. + :URL: http://www.linuxjournal.com/article.php?sid=1219 + :Date: 1996 + :Keywords: device driver, module, loading/unloading modules, + allocating resources. + :Description: Linux Journal Kernel Korner article. Here is its + :Abstract: *This is the first of a series of four articles + co-authored by Alessandro Rubini and Georg Zezchwitz which present + a practical approach to writing Linux device drivers as kernel + loadable modules. This installment presents an introduction to the + topic, preparing the reader to understand next month's + installment*. + + * Title: **Dynamic Kernels: Discovery** + + :Author: Alessandro Rubini. + :URL: http://www.linuxjournal.com/article.php?sid=1220 + :Date: 1996 + :Keywords: character driver, init_module, clean_up module, + autodetection, mayor number, minor number, file operations, + open(), close(). + :Description: Linux Journal Kernel Korner article. Here is its + :Abstract: *This article, the second of four, introduces part of + the actual code to create custom module implementing a character + device driver. It describes the code for module initialization and + cleanup, as well as the open() and close() system calls*. + + * Title: **The Devil's in the Details** + + :Author: Georg v. Zezschwitz and Alessandro Rubini. + :URL: http://www.linuxjournal.com/article.php?sid=1221 + :Date: 1996 + :Keywords: read(), write(), select(), ioctl(), blocking/non + blocking mode, interrupt handler. + :Description: Linux Journal Kernel Korner article. Here is its + :Abstract: *This article, the third of four on writing character + device drivers, introduces concepts of reading, writing, and using + ioctl-calls*. + + * Title: **Dissecting Interrupts and Browsing DMA** + + :Author: Alessandro Rubini and Georg v. Zezschwitz. + :URL: http://www.linuxjournal.com/article.php?sid=1222 + :Date: 1996 + :Keywords: interrupts, irqs, DMA, bottom halves, task queues. + :Description: Linux Journal Kernel Korner article. Here is its + :Abstract: *This is the fourth in a series of articles about + writing character device drivers as loadable kernel modules. This + month, we further investigate the field of interrupt handling. + Though it is conceptually simple, practical limitations and + constraints make this an ''interesting'' part of device driver + writing, and several different facilities have been provided for + different situations. We also investigate the complex topic of + DMA*. + + * Title: **Device Drivers Concluded** + + :Author: Georg v. Zezschwitz. + :URL: http://www.linuxjournal.com/article.php?sid=1287 + :Date: 1996 + :Keywords: address spaces, pages, pagination, page management, + demand loading, swapping, memory protection, memory mapping, mmap, + virtual memory areas (VMAs), vremap, PCI. + :Description: Finally, the above turned out into a five articles + series. This latest one's introduction reads: "This is the last of + five articles about character device drivers. In this final + section, Georg deals with memory mapping devices, beginning with + an overall description of the Linux memory management concepts". + + * Title: **Network Buffers And Memory Management** + + :Author: Alan Cox. + :URL: http://www.linuxjournal.com/article.php?sid=1312 + :Date: 1996 + :Keywords: sk_buffs, network devices, protocol/link layer + variables, network devices flags, transmit, receive, + configuration, multicast. + :Description: Linux Journal Kernel Korner. + :Abstract: *Writing a network device driver for Linux is fundamentally + simple---most of the complexity (other than talking to the + hardware) involves managing network packets in memory*. + + * Title: **Analysis of the Ext2fs structure** + + :Author: Louis-Dominique Dubeau. + :URL: http://teaching.csse.uwa.edu.au/units/CITS2002/fs-ext2/ + :Date: 1994 + :Keywords: ext2, filesystem, ext2fs. + :Description: Description of ext2's blocks, directories, inodes, + bitmaps, invariants... + +Published books +--------------- + + * Title: **Linux Treiber entwickeln** + + :Author: Jürgen Quade, Eva-Katharina Kunst + :Publisher: dpunkt.verlag + :Date: Oct 2015 (4th edition) + :Pages: 688 + :ISBN: 978-3-86490-288-8 + :Note: German. The third edition from 2011 is + much cheaper and still quite up-to-date. + + * Title: **Linux Kernel Networking: Implementation and Theory** + + :Author: Rami Rosen + :Publisher: Apress + :Date: December 22, 2013 + :Pages: 648 + :ISBN: 978-1430261964 + + * Title: **Embedded Linux Primer: A practical Real-World Approach, 2nd Edition** + + :Author: Christopher Hallinan + :Publisher: Pearson + :Date: November, 2010 + :Pages: 656 + :ISBN: 978-0137017836 + + * Title: **Linux Kernel Development, 3rd Edition** + + :Author: Robert Love + :Publisher: Addison-Wesley + :Date: July, 2010 + :Pages: 440 + :ISBN: 978-0672329463 + + * Title: **Essential Linux Device Drivers** + + :Author: Sreekrishnan Venkateswaran + :Published: Prentice Hall + :Date: April, 2008 + :Pages: 744 + :ISBN: 978-0132396554 + +.. _ldd3_published: + + * Title: **Linux Device Drivers, 3rd Edition** + + :Authors: Jonathan Corbet, Alessandro Rubini, and Greg Kroah-Hartman + :Publisher: O'Reilly & Associates + :Date: 2005 + :Pages: 636 + :ISBN: 0-596-00590-3 + :Notes: Further information in + http://www.oreilly.com/catalog/linuxdrive3/ + PDF format, URL: http://lwn.net/Kernel/LDD3/ + + * Title: **Linux Kernel Internals** + + :Author: Michael Beck + :Publisher: Addison-Wesley + :Date: 1997 + :ISBN: 0-201-33143-8 (second edition) + + * Title: **Programmation Linux 2.0 API systeme et fonctionnement du noyau** + + :Author: Remy Card, Eric Dumas, Franck Mevel + :Publisher: Eyrolles + :Date: 1997 + :Pages: 520 + :ISBN: 2-212-08932-5 + :Notes: French + + * Title: **The Design and Implementation of the 4.4 BSD UNIX Operating System** + + :Author: Marshall Kirk McKusick, Keith Bostic, Michael J. Karels, + John S. Quarterman + :Publisher: Addison-Wesley + :Date: 1996 + :ISBN: 0-201-54979-4 + + * Title: **Unix internals -- the new frontiers** + + :Author: Uresh Vahalia + :Publisher: Prentice Hall + :Date: 1996 + :Pages: 600 + :ISBN: 0-13-101908-2 + + * Title: **Programming for the real world - POSIX.4** + + :Author: Bill O. Gallmeister + :Publisher: O'Reilly & Associates, Inc + :Date: 1995 + :Pages: 552 + :ISBN: I-56592-074-0 + :Notes: Though not being directly about Linux, Linux aims to be + POSIX. Good reference. + + * Title: **UNIX Systems for Modern Architectures: Symmetric Multiprocessing and Caching for Kernel Programmers** + + :Author: Curt Schimmel + :Publisher: Addison Wesley + :Date: June, 1994 + :Pages: 432 + :ISBN: 0-201-63338-8 + + * Title: **The Design and Implementation of the 4.3 BSD UNIX Operating System** + + :Author: Samuel J. Leffler, Marshall Kirk McKusick, Michael J + Karels, John S. Quarterman + :Publisher: Addison-Wesley + :Date: 1989 (reprinted with corrections on October, 1990) + :ISBN: 0-201-06196-1 + + * Title: **The Design of the UNIX Operating System** + + :Author: Maurice J. Bach + :Publisher: Prentice Hall + :Date: 1986 + :Pages: 471 + :ISBN: 0-13-201757-1 + +Miscellaneous +------------- + + * Name: **Cross-Referencing Linux** + + :URL: http://lxr.free-electrons.com/ + :Keywords: Browsing source code. + :Description: Another web-based Linux kernel source code browser. + Lots of cross references to variables and functions. You can see + where they are defined and where they are used. + + * Name: **Linux Weekly News** + + :URL: http://lwn.net + :Keywords: latest kernel news. + :Description: The title says it all. There's a fixed kernel section + summarizing developers' work, bug fixes, new features and versions + produced during the week. Published every Thursday. + + * Name: **The home page of Linux-MM** + + :Author: The Linux-MM team. + :URL: http://linux-mm.org/ + :Keywords: memory management, Linux-MM, mm patches, TODO, docs, + mailing list. + :Description: Site devoted to Linux Memory Management development. + Memory related patches, HOWTOs, links, mm developers... Don't miss + it if you are interested in memory management development! + + * Name: **Kernel Newbies IRC Channel and Website** + + :URL: http://www.kernelnewbies.org + :Keywords: IRC, newbies, channel, asking doubts. + :Description: #kernelnewbies on irc.oftc.net. + #kernelnewbies is an IRC network dedicated to the 'newbie' + kernel hacker. The audience mostly consists of people who are + learning about the kernel, working on kernel projects or + professional kernel hackers that want to help less seasoned kernel + people. + #kernelnewbies is on the OFTC IRC Network. + Try irc.oftc.net as your server and then /join #kernelnewbies. + The kernelnewbies website also hosts articles, documents, FAQs... + + * Name: **linux-kernel mailing list archives and search engines** + + :URL: http://vger.kernel.org/vger-lists.html + :URL: http://www.uwsg.indiana.edu/hypermail/linux/kernel/index.html + :URL: http://groups.google.com/group/mlist.linux.kernel + :Keywords: linux-kernel, archives, search. + :Description: Some of the linux-kernel mailing list archivers. If + you have a better/another one, please let me know. + +------- + +Document last updated on Tue 2016-Sep-20 + +This document is based on: + http://www.dit.upm.es/~jmseyas/linux/kernel/hackers-docs.html diff --git a/Documentation/process/magic-number.rst b/Documentation/process/magic-number.rst new file mode 100644 index 000000000000..c74199f60c6c --- /dev/null +++ b/Documentation/process/magic-number.rst @@ -0,0 +1,164 @@ +Linux magic numbers +=================== + +This file is a registry of magic numbers which are in use. When you +add a magic number to a structure, you should also add it to this +file, since it is best if the magic numbers used by various structures +are unique. + +It is a **very** good idea to protect kernel data structures with magic +numbers. This allows you to check at run time whether (a) a structure +has been clobbered, or (b) you've passed the wrong structure to a +routine. This last is especially useful --- particularly when you are +passing pointers to structures via a void * pointer. The tty code, +for example, does this frequently to pass driver-specific and line +discipline-specific structures back and forth. + +The way to use magic numbers is to declare then at the beginning of +the structure, like so:: + + struct tty_ldisc { + int magic; + ... + }; + +Please follow this discipline when you are adding future enhancements +to the kernel! It has saved me countless hours of debugging, +especially in the screwy cases where an array has been overrun and +structures following the array have been overwritten. Using this +discipline, these cases get detected quickly and safely. + +Changelog:: + + Theodore Ts'o + 31 Mar 94 + + The magic table is current to Linux 2.1.55. + + Michael Chastain + + 22 Sep 1997 + + Now it should be up to date with Linux 2.1.112. Because + we are in feature freeze time it is very unlikely that + something will change before 2.2.x. The entries are + sorted by number field. + + Krzysztof G. Baranowski + + 29 Jul 1998 + + Updated the magic table to Linux 2.5.45. Right over the feature freeze, + but it is possible that some new magic numbers will sneak into the + kernel before 2.6.x yet. + + Petr Baudis + + 03 Nov 2002 + + Updated the magic table to Linux 2.5.74. + + Fabian Frederick + + 09 Jul 2003 + + +===================== ================ ======================== ========================================== +Magic Name Number Structure File +===================== ================ ======================== ========================================== +PG_MAGIC 'P' pg_{read,write}_hdr ``include/linux/pg.h`` +CMAGIC 0x0111 user ``include/linux/a.out.h`` +MKISS_DRIVER_MAGIC 0x04bf mkiss_channel ``drivers/net/mkiss.h`` +HDLC_MAGIC 0x239e n_hdlc ``drivers/char/n_hdlc.c`` +APM_BIOS_MAGIC 0x4101 apm_user ``arch/x86/kernel/apm_32.c`` +CYCLADES_MAGIC 0x4359 cyclades_port ``include/linux/cyclades.h`` +DB_MAGIC 0x4442 fc_info ``drivers/net/iph5526_novram.c`` +DL_MAGIC 0x444d fc_info ``drivers/net/iph5526_novram.c`` +FASYNC_MAGIC 0x4601 fasync_struct ``include/linux/fs.h`` +FF_MAGIC 0x4646 fc_info ``drivers/net/iph5526_novram.c`` +ISICOM_MAGIC 0x4d54 isi_port ``include/linux/isicom.h`` +PTY_MAGIC 0x5001 ``drivers/char/pty.c`` +PPP_MAGIC 0x5002 ppp ``include/linux/if_pppvar.h`` +SERIAL_MAGIC 0x5301 async_struct ``include/linux/serial.h`` +SSTATE_MAGIC 0x5302 serial_state ``include/linux/serial.h`` +SLIP_MAGIC 0x5302 slip ``drivers/net/slip.h`` +STRIP_MAGIC 0x5303 strip ``drivers/net/strip.c`` +X25_ASY_MAGIC 0x5303 x25_asy ``drivers/net/x25_asy.h`` +SIXPACK_MAGIC 0x5304 sixpack ``drivers/net/hamradio/6pack.h`` +AX25_MAGIC 0x5316 ax_disp ``drivers/net/mkiss.h`` +TTY_MAGIC 0x5401 tty_struct ``include/linux/tty.h`` +MGSL_MAGIC 0x5401 mgsl_info ``drivers/char/synclink.c`` +TTY_DRIVER_MAGIC 0x5402 tty_driver ``include/linux/tty_driver.h`` +MGSLPC_MAGIC 0x5402 mgslpc_info ``drivers/char/pcmcia/synclink_cs.c`` +TTY_LDISC_MAGIC 0x5403 tty_ldisc ``include/linux/tty_ldisc.h`` +USB_SERIAL_MAGIC 0x6702 usb_serial ``drivers/usb/serial/usb-serial.h`` +FULL_DUPLEX_MAGIC 0x6969 ``drivers/net/ethernet/dec/tulip/de2104x.c`` +USB_BLUETOOTH_MAGIC 0x6d02 usb_bluetooth ``drivers/usb/class/bluetty.c`` +RFCOMM_TTY_MAGIC 0x6d02 ``net/bluetooth/rfcomm/tty.c`` +USB_SERIAL_PORT_MAGIC 0x7301 usb_serial_port ``drivers/usb/serial/usb-serial.h`` +CG_MAGIC 0x00090255 ufs_cylinder_group ``include/linux/ufs_fs.h`` +RPORT_MAGIC 0x00525001 r_port ``drivers/char/rocket_int.h`` +LSEMAGIC 0x05091998 lse ``drivers/fc4/fc.c`` +GDTIOCTL_MAGIC 0x06030f07 gdth_iowr_str ``drivers/scsi/gdth_ioctl.h`` +RIEBL_MAGIC 0x09051990 ``drivers/net/atarilance.c`` +NBD_REQUEST_MAGIC 0x12560953 nbd_request ``include/linux/nbd.h`` +RED_MAGIC2 0x170fc2a5 (any) ``mm/slab.c`` +BAYCOM_MAGIC 0x19730510 baycom_state ``drivers/net/baycom_epp.c`` +ISDN_X25IFACE_MAGIC 0x1e75a2b9 isdn_x25iface_proto_data ``drivers/isdn/isdn_x25iface.h`` +ECP_MAGIC 0x21504345 cdkecpsig ``include/linux/cdk.h`` +LSOMAGIC 0x27091997 lso ``drivers/fc4/fc.c`` +LSMAGIC 0x2a3b4d2a ls ``drivers/fc4/fc.c`` +WANPIPE_MAGIC 0x414C4453 sdla_{dump,exec} ``include/linux/wanpipe.h`` +CS_CARD_MAGIC 0x43525553 cs_card ``sound/oss/cs46xx.c`` +LABELCL_MAGIC 0x4857434c labelcl_info_s ``include/asm/ia64/sn/labelcl.h`` +ISDN_ASYNC_MAGIC 0x49344C01 modem_info ``include/linux/isdn.h`` +CTC_ASYNC_MAGIC 0x49344C01 ctc_tty_info ``drivers/s390/net/ctctty.c`` +ISDN_NET_MAGIC 0x49344C02 isdn_net_local_s ``drivers/isdn/i4l/isdn_net_lib.h`` +SAVEKMSG_MAGIC2 0x4B4D5347 savekmsg ``arch/*/amiga/config.c`` +CS_STATE_MAGIC 0x4c4f4749 cs_state ``sound/oss/cs46xx.c`` +SLAB_C_MAGIC 0x4f17a36d kmem_cache ``mm/slab.c`` +COW_MAGIC 0x4f4f4f4d cow_header_v1 ``arch/um/drivers/ubd_user.c`` +I810_CARD_MAGIC 0x5072696E i810_card ``sound/oss/i810_audio.c`` +TRIDENT_CARD_MAGIC 0x5072696E trident_card ``sound/oss/trident.c`` +ROUTER_MAGIC 0x524d4157 wan_device [in ``wanrouter.h`` pre 3.9] +SAVEKMSG_MAGIC1 0x53415645 savekmsg ``arch/*/amiga/config.c`` +GDA_MAGIC 0x58464552 gda ``arch/mips/include/asm/sn/gda.h`` +RED_MAGIC1 0x5a2cf071 (any) ``mm/slab.c`` +EEPROM_MAGIC_VALUE 0x5ab478d2 lanai_dev ``drivers/atm/lanai.c`` +HDLCDRV_MAGIC 0x5ac6e778 hdlcdrv_state ``include/linux/hdlcdrv.h`` +PCXX_MAGIC 0x5c6df104 channel ``drivers/char/pcxx.h`` +KV_MAGIC 0x5f4b565f kernel_vars_s ``arch/mips/include/asm/sn/klkernvars.h`` +I810_STATE_MAGIC 0x63657373 i810_state ``sound/oss/i810_audio.c`` +TRIDENT_STATE_MAGIC 0x63657373 trient_state ``sound/oss/trident.c`` +M3_CARD_MAGIC 0x646e6f50 m3_card ``sound/oss/maestro3.c`` +FW_HEADER_MAGIC 0x65726F66 fw_header ``drivers/atm/fore200e.h`` +SLOT_MAGIC 0x67267321 slot ``drivers/hotplug/cpqphp.h`` +SLOT_MAGIC 0x67267322 slot ``drivers/hotplug/acpiphp.h`` +LO_MAGIC 0x68797548 nbd_device ``include/linux/nbd.h`` +OPROFILE_MAGIC 0x6f70726f super_block ``drivers/oprofile/oprofilefs.h`` +M3_STATE_MAGIC 0x734d724d m3_state ``sound/oss/maestro3.c`` +VMALLOC_MAGIC 0x87654320 snd_alloc_track ``sound/core/memory.c`` +KMALLOC_MAGIC 0x87654321 snd_alloc_track ``sound/core/memory.c`` +PWC_MAGIC 0x89DC10AB pwc_device ``drivers/usb/media/pwc.h`` +NBD_REPLY_MAGIC 0x96744668 nbd_reply ``include/linux/nbd.h`` +ENI155_MAGIC 0xa54b872d midway_eprom ``drivers/atm/eni.h`` +CODA_MAGIC 0xC0DAC0DA coda_file_info ``fs/coda/coda_fs_i.h`` +DPMEM_MAGIC 0xc0ffee11 gdt_pci_sram ``drivers/scsi/gdth.h`` +YAM_MAGIC 0xF10A7654 yam_port ``drivers/net/hamradio/yam.c`` +CCB_MAGIC 0xf2691ad2 ccb ``drivers/scsi/ncr53c8xx.c`` +QUEUE_MAGIC_FREE 0xf7e1c9a3 queue_entry ``drivers/scsi/arm/queue.c`` +QUEUE_MAGIC_USED 0xf7e1cc33 queue_entry ``drivers/scsi/arm/queue.c`` +HTB_CMAGIC 0xFEFAFEF1 htb_class ``net/sched/sch_htb.c`` +NMI_MAGIC 0x48414d4d455201 nmi_s ``arch/mips/include/asm/sn/nmi.h`` +===================== ================ ======================== ========================================== + +Note that there are also defined special per-driver magic numbers in sound +memory management. See ``include/sound/sndmagic.h`` for complete list of them. Many +OSS sound drivers have their magic numbers constructed from the soundcard PCI +ID - these are not listed here as well. + +IrDA subsystem also uses large number of own magic numbers, see +``include/net/irda/irda.h`` for a complete list of them. + +HFS is another larger user of magic numbers - you can find them in +``fs/hfs/hfs.h``. diff --git a/Documentation/process/management-style.rst b/Documentation/process/management-style.rst new file mode 100644 index 000000000000..dea2e66c9a10 --- /dev/null +++ b/Documentation/process/management-style.rst @@ -0,0 +1,288 @@ +.. _managementstyle: + +Linux kernel management style +============================= + +This is a short document describing the preferred (or made up, depending +on who you ask) management style for the linux kernel. It's meant to +mirror the CodingStyle document to some degree, and mainly written to +avoid answering [#f1]_ the same (or similar) questions over and over again. + +Management style is very personal and much harder to quantify than +simple coding style rules, so this document may or may not have anything +to do with reality. It started as a lark, but that doesn't mean that it +might not actually be true. You'll have to decide for yourself. + +Btw, when talking about "kernel manager", it's all about the technical +lead persons, not the people who do traditional management inside +companies. If you sign purchase orders or you have any clue about the +budget of your group, you're almost certainly not a kernel manager. +These suggestions may or may not apply to you. + +First off, I'd suggest buying "Seven Habits of Highly Effective +People", and NOT read it. Burn it, it's a great symbolic gesture. + +.. [#f1] This document does so not so much by answering the question, but by + making it painfully obvious to the questioner that we don't have a clue + to what the answer is. + +Anyway, here goes: + +.. _decisions: + +1) Decisions +------------ + +Everybody thinks managers make decisions, and that decision-making is +important. The bigger and more painful the decision, the bigger the +manager must be to make it. That's very deep and obvious, but it's not +actually true. + +The name of the game is to **avoid** having to make a decision. In +particular, if somebody tells you "choose (a) or (b), we really need you +to decide on this", you're in trouble as a manager. The people you +manage had better know the details better than you, so if they come to +you for a technical decision, you're screwed. You're clearly not +competent to make that decision for them. + +(Corollary:if the people you manage don't know the details better than +you, you're also screwed, although for a totally different reason. +Namely that you are in the wrong job, and that **they** should be managing +your brilliance instead). + +So the name of the game is to **avoid** decisions, at least the big and +painful ones. Making small and non-consequential decisions is fine, and +makes you look like you know what you're doing, so what a kernel manager +needs to do is to turn the big and painful ones into small things where +nobody really cares. + +It helps to realize that the key difference between a big decision and a +small one is whether you can fix your decision afterwards. Any decision +can be made small by just always making sure that if you were wrong (and +you **will** be wrong), you can always undo the damage later by +backtracking. Suddenly, you get to be doubly managerial for making +**two** inconsequential decisions - the wrong one **and** the right one. + +And people will even see that as true leadership (*cough* bullshit +*cough*). + +Thus the key to avoiding big decisions becomes to just avoiding to do +things that can't be undone. Don't get ushered into a corner from which +you cannot escape. A cornered rat may be dangerous - a cornered manager +is just pitiful. + +It turns out that since nobody would be stupid enough to ever really let +a kernel manager have huge fiscal responsibility **anyway**, it's usually +fairly easy to backtrack. Since you're not going to be able to waste +huge amounts of money that you might not be able to repay, the only +thing you can backtrack on is a technical decision, and there +back-tracking is very easy: just tell everybody that you were an +incompetent nincompoop, say you're sorry, and undo all the worthless +work you had people work on for the last year. Suddenly the decision +you made a year ago wasn't a big decision after all, since it could be +easily undone. + +It turns out that some people have trouble with this approach, for two +reasons: + + - admitting you were an idiot is harder than it looks. We all like to + maintain appearances, and coming out in public to say that you were + wrong is sometimes very hard indeed. + - having somebody tell you that what you worked on for the last year + wasn't worthwhile after all can be hard on the poor lowly engineers + too, and while the actual **work** was easy enough to undo by just + deleting it, you may have irrevocably lost the trust of that + engineer. And remember: "irrevocable" was what we tried to avoid in + the first place, and your decision ended up being a big one after + all. + +Happily, both of these reasons can be mitigated effectively by just +admitting up-front that you don't have a friggin' clue, and telling +people ahead of the fact that your decision is purely preliminary, and +might be the wrong thing. You should always reserve the right to change +your mind, and make people very **aware** of that. And it's much easier +to admit that you are stupid when you haven't **yet** done the really +stupid thing. + +Then, when it really does turn out to be stupid, people just roll their +eyes and say "Oops, he did it again". + +This preemptive admission of incompetence might also make the people who +actually do the work also think twice about whether it's worth doing or +not. After all, if **they** aren't certain whether it's a good idea, you +sure as hell shouldn't encourage them by promising them that what they +work on will be included. Make them at least think twice before they +embark on a big endeavor. + +Remember: they'd better know more about the details than you do, and +they usually already think they have the answer to everything. The best +thing you can do as a manager is not to instill confidence, but rather a +healthy dose of critical thinking on what they do. + +Btw, another way to avoid a decision is to plaintively just whine "can't +we just do both?" and look pitiful. Trust me, it works. If it's not +clear which approach is better, they'll eventually figure it out. The +answer may end up being that both teams get so frustrated by the +situation that they just give up. + +That may sound like a failure, but it's usually a sign that there was +something wrong with both projects, and the reason the people involved +couldn't decide was that they were both wrong. You end up coming up +smelling like roses, and you avoided yet another decision that you could +have screwed up on. + + +2) People +--------- + +Most people are idiots, and being a manager means you'll have to deal +with it, and perhaps more importantly, that **they** have to deal with +**you**. + +It turns out that while it's easy to undo technical mistakes, it's not +as easy to undo personality disorders. You just have to live with +theirs - and yours. + +However, in order to prepare yourself as a kernel manager, it's best to +remember not to burn any bridges, bomb any innocent villagers, or +alienate too many kernel developers. It turns out that alienating people +is fairly easy, and un-alienating them is hard. Thus "alienating" +immediately falls under the heading of "not reversible", and becomes a +no-no according to :ref:`decisions`. + +There's just a few simple rules here: + + (1) don't call people d*ckheads (at least not in public) + (2) learn how to apologize when you forgot rule (1) + +The problem with #1 is that it's very easy to do, since you can say +"you're a d*ckhead" in millions of different ways [#f2]_, sometimes without +even realizing it, and almost always with a white-hot conviction that +you are right. + +And the more convinced you are that you are right (and let's face it, +you can call just about **anybody** a d*ckhead, and you often **will** be +right), the harder it ends up being to apologize afterwards. + +To solve this problem, you really only have two options: + + - get really good at apologies + - spread the "love" out so evenly that nobody really ends up feeling + like they get unfairly targeted. Make it inventive enough, and they + might even be amused. + +The option of being unfailingly polite really doesn't exist. Nobody will +trust somebody who is so clearly hiding his true character. + +.. [#f2] Paul Simon sang "Fifty Ways to Leave Your Lover", because quite + frankly, "A Million Ways to Tell a Developer He Is a D*ckhead" doesn't + scan nearly as well. But I'm sure he thought about it. + + +3) People II - the Good Kind +---------------------------- + +While it turns out that most people are idiots, the corollary to that is +sadly that you are one too, and that while we can all bask in the secure +knowledge that we're better than the average person (let's face it, +nobody ever believes that they're average or below-average), we should +also admit that we're not the sharpest knife around, and there will be +other people that are less of an idiot than you are. + +Some people react badly to smart people. Others take advantage of them. + +Make sure that you, as a kernel maintainer, are in the second group. +Suck up to them, because they are the people who will make your job +easier. In particular, they'll be able to make your decisions for you, +which is what the game is all about. + +So when you find somebody smarter than you are, just coast along. Your +management responsibilities largely become ones of saying "Sounds like a +good idea - go wild", or "That sounds good, but what about xxx?". The +second version in particular is a great way to either learn something +new about "xxx" or seem **extra** managerial by pointing out something the +smarter person hadn't thought about. In either case, you win. + +One thing to look out for is to realize that greatness in one area does +not necessarily translate to other areas. So you might prod people in +specific directions, but let's face it, they might be good at what they +do, and suck at everything else. The good news is that people tend to +naturally gravitate back to what they are good at, so it's not like you +are doing something irreversible when you **do** prod them in some +direction, just don't push too hard. + + +4) Placing blame +---------------- + +Things will go wrong, and people want somebody to blame. Tag, you're it. + +It's not actually that hard to accept the blame, especially if people +kind of realize that it wasn't **all** your fault. Which brings us to the +best way of taking the blame: do it for another guy. You'll feel good +for taking the fall, he'll feel good about not getting blamed, and the +guy who lost his whole 36GB porn-collection because of your incompetence +will grudgingly admit that you at least didn't try to weasel out of it. + +Then make the developer who really screwed up (if you can find him) know +**in_private** that he screwed up. Not just so he can avoid it in the +future, but so that he knows he owes you one. And, perhaps even more +importantly, he's also likely the person who can fix it. Because, let's +face it, it sure ain't you. + +Taking the blame is also why you get to be manager in the first place. +It's part of what makes people trust you, and allow you the potential +glory, because you're the one who gets to say "I screwed up". And if +you've followed the previous rules, you'll be pretty good at saying that +by now. + + +5) Things to avoid +------------------ + +There's one thing people hate even more than being called "d*ckhead", +and that is being called a "d*ckhead" in a sanctimonious voice. The +first you can apologize for, the second one you won't really get the +chance. They likely will no longer be listening even if you otherwise +do a good job. + +We all think we're better than anybody else, which means that when +somebody else puts on airs, it **really** rubs us the wrong way. You may +be morally and intellectually superior to everybody around you, but +don't try to make it too obvious unless you really **intend** to irritate +somebody [#f3]_. + +Similarly, don't be too polite or subtle about things. Politeness easily +ends up going overboard and hiding the problem, and as they say, "On the +internet, nobody can hear you being subtle". Use a big blunt object to +hammer the point in, because you can't really depend on people getting +your point otherwise. + +Some humor can help pad both the bluntness and the moralizing. Going +overboard to the point of being ridiculous can drive a point home +without making it painful to the recipient, who just thinks you're being +silly. It can thus help get through the personal mental block we all +have about criticism. + +.. [#f3] Hint: internet newsgroups that are not directly related to your work + are great ways to take out your frustrations at other people. Write + insulting posts with a sneer just to get into a good flame every once in + a while, and you'll feel cleansed. Just don't crap too close to home. + + +6) Why me? +---------- + +Since your main responsibility seems to be to take the blame for other +peoples mistakes, and make it painfully obvious to everybody else that +you're incompetent, the obvious question becomes one of why do it in the +first place? + +First off, while you may or may not get screaming teenage girls (or +boys, let's not be judgmental or sexist here) knocking on your dressing +room door, you **will** get an immense feeling of personal accomplishment +for being "in charge". Never mind the fact that you're really leading +by trying to keep up with everybody else and running after them as fast +as you can. Everybody will still think you're the person in charge. + +It's a great job if you can hack it. diff --git a/Documentation/process/stable-api-nonsense.rst b/Documentation/process/stable-api-nonsense.rst new file mode 100644 index 000000000000..24f5aeecee91 --- /dev/null +++ b/Documentation/process/stable-api-nonsense.rst @@ -0,0 +1,205 @@ +.. _stable_api_nonsense: + +The Linux Kernel Driver Interface +================================== + +(all of your questions answered and then some) + +Greg Kroah-Hartman + +This is being written to try to explain why Linux **does not have a binary +kernel interface, nor does it have a stable kernel interface**. + +.. note:: + + Please realize that this article describes the **in kernel** interfaces, not + the kernel to userspace interfaces. + + The kernel to userspace interface is the one that application programs use, + the syscall interface. That interface is **very** stable over time, and + will not break. I have old programs that were built on a pre 0.9something + kernel that still work just fine on the latest 2.6 kernel release. + That interface is the one that users and application programmers can count + on being stable. + + +Executive Summary +----------------- +You think you want a stable kernel interface, but you really do not, and +you don't even know it. What you want is a stable running driver, and +you get that only if your driver is in the main kernel tree. You also +get lots of other good benefits if your driver is in the main kernel +tree, all of which has made Linux into such a strong, stable, and mature +operating system which is the reason you are using it in the first +place. + + +Intro +----- + +It's only the odd person who wants to write a kernel driver that needs +to worry about the in-kernel interfaces changing. For the majority of +the world, they neither see this interface, nor do they care about it at +all. + +First off, I'm not going to address **any** legal issues about closed +source, hidden source, binary blobs, source wrappers, or any other term +that describes kernel drivers that do not have their source code +released under the GPL. Please consult a lawyer if you have any legal +questions, I'm a programmer and hence, I'm just going to be describing +the technical issues here (not to make light of the legal issues, they +are real, and you do need to be aware of them at all times.) + +So, there are two main topics here, binary kernel interfaces and stable +kernel source interfaces. They both depend on each other, but we will +discuss the binary stuff first to get it out of the way. + + +Binary Kernel Interface +----------------------- +Assuming that we had a stable kernel source interface for the kernel, a +binary interface would naturally happen too, right? Wrong. Please +consider the following facts about the Linux kernel: + + - Depending on the version of the C compiler you use, different kernel + data structures will contain different alignment of structures, and + possibly include different functions in different ways (putting + functions inline or not.) The individual function organization + isn't that important, but the different data structure padding is + very important. + + - Depending on what kernel build options you select, a wide range of + different things can be assumed by the kernel: + + - different structures can contain different fields + - Some functions may not be implemented at all, (i.e. some locks + compile away to nothing for non-SMP builds.) + - Memory within the kernel can be aligned in different ways, + depending on the build options. + + - Linux runs on a wide range of different processor architectures. + There is no way that binary drivers from one architecture will run + on another architecture properly. + +Now a number of these issues can be addressed by simply compiling your +module for the exact specific kernel configuration, using the same exact +C compiler that the kernel was built with. This is sufficient if you +want to provide a module for a specific release version of a specific +Linux distribution. But multiply that single build by the number of +different Linux distributions and the number of different supported +releases of the Linux distribution and you quickly have a nightmare of +different build options on different releases. Also realize that each +Linux distribution release contains a number of different kernels, all +tuned to different hardware types (different processor types and +different options), so for even a single release you will need to create +multiple versions of your module. + +Trust me, you will go insane over time if you try to support this kind +of release, I learned this the hard way a long time ago... + + +Stable Kernel Source Interfaces +------------------------------- + +This is a much more "volatile" topic if you talk to people who try to +keep a Linux kernel driver that is not in the main kernel tree up to +date over time. + +Linux kernel development is continuous and at a rapid pace, never +stopping to slow down. As such, the kernel developers find bugs in +current interfaces, or figure out a better way to do things. If they do +that, they then fix the current interfaces to work better. When they do +so, function names may change, structures may grow or shrink, and +function parameters may be reworked. If this happens, all of the +instances of where this interface is used within the kernel are fixed up +at the same time, ensuring that everything continues to work properly. + +As a specific examples of this, the in-kernel USB interfaces have +undergone at least three different reworks over the lifetime of this +subsystem. These reworks were done to address a number of different +issues: + + - A change from a synchronous model of data streams to an asynchronous + one. This reduced the complexity of a number of drivers and + increased the throughput of all USB drivers such that we are now + running almost all USB devices at their maximum speed possible. + - A change was made in the way data packets were allocated from the + USB core by USB drivers so that all drivers now needed to provide + more information to the USB core to fix a number of documented + deadlocks. + +This is in stark contrast to a number of closed source operating systems +which have had to maintain their older USB interfaces over time. This +provides the ability for new developers to accidentally use the old +interfaces and do things in improper ways, causing the stability of the +operating system to suffer. + +In both of these instances, all developers agreed that these were +important changes that needed to be made, and they were made, with +relatively little pain. If Linux had to ensure that it will preserve a +stable source interface, a new interface would have been created, and +the older, broken one would have had to be maintained over time, leading +to extra work for the USB developers. Since all Linux USB developers do +their work on their own time, asking programmers to do extra work for no +gain, for free, is not a possibility. + +Security issues are also very important for Linux. When a +security issue is found, it is fixed in a very short amount of time. A +number of times this has caused internal kernel interfaces to be +reworked to prevent the security problem from occurring. When this +happens, all drivers that use the interfaces were also fixed at the +same time, ensuring that the security problem was fixed and could not +come back at some future time accidentally. If the internal interfaces +were not allowed to change, fixing this kind of security problem and +insuring that it could not happen again would not be possible. + +Kernel interfaces are cleaned up over time. If there is no one using a +current interface, it is deleted. This ensures that the kernel remains +as small as possible, and that all potential interfaces are tested as +well as they can be (unused interfaces are pretty much impossible to +test for validity.) + + +What to do +---------- + +So, if you have a Linux kernel driver that is not in the main kernel +tree, what are you, a developer, supposed to do? Releasing a binary +driver for every different kernel version for every distribution is a +nightmare, and trying to keep up with an ever changing kernel interface +is also a rough job. + +Simple, get your kernel driver into the main kernel tree (remember we +are talking about GPL released drivers here, if your code doesn't fall +under this category, good luck, you are on your own here, you leech +.) If your +driver is in the tree, and a kernel interface changes, it will be fixed +up by the person who did the kernel change in the first place. This +ensures that your driver is always buildable, and works over time, with +very little effort on your part. + +The very good side effects of having your driver in the main kernel tree +are: + + - The quality of the driver will rise as the maintenance costs (to the + original developer) will decrease. + - Other developers will add features to your driver. + - Other people will find and fix bugs in your driver. + - Other people will find tuning opportunities in your driver. + - Other people will update the driver for you when external interface + changes require it. + - The driver automatically gets shipped in all Linux distributions + without having to ask the distros to add it. + +As Linux supports a larger number of different devices "out of the box" +than any other operating system, and it supports these devices on more +different processor architectures than any other operating system, this +proven type of development model must be doing something right :) + + + +------ + +Thanks to Randy Dunlap, Andrew Morton, David Brownell, Hanna Linder, +Robert Love, and Nishanth Aravamudan for their review and comments on +early drafts of this paper. diff --git a/Documentation/process/stable-kernel-rules.rst b/Documentation/process/stable-kernel-rules.rst new file mode 100644 index 000000000000..4d82e31b7958 --- /dev/null +++ b/Documentation/process/stable-kernel-rules.rst @@ -0,0 +1,181 @@ +.. _stable_kernel_rules: + +Everything you ever wanted to know about Linux -stable releases +=============================================================== + +Rules on what kind of patches are accepted, and which ones are not, into the +"-stable" tree: + + - It must be obviously correct and tested. + - It cannot be bigger than 100 lines, with context. + - It must fix only one thing. + - It must fix a real bug that bothers people (not a, "This could be a + problem..." type thing). + - It must fix a problem that causes a build error (but not for things + marked CONFIG_BROKEN), an oops, a hang, data corruption, a real + security issue, or some "oh, that's not good" issue. In short, something + critical. + - Serious issues as reported by a user of a distribution kernel may also + be considered if they fix a notable performance or interactivity issue. + As these fixes are not as obvious and have a higher risk of a subtle + regression they should only be submitted by a distribution kernel + maintainer and include an addendum linking to a bugzilla entry if it + exists and additional information on the user-visible impact. + - New device IDs and quirks are also accepted. + - No "theoretical race condition" issues, unless an explanation of how the + race can be exploited is also provided. + - It cannot contain any "trivial" fixes in it (spelling changes, + whitespace cleanups, etc). + - It must follow the + :ref:`Documentation/SubmittingPatches ` + rules. + - It or an equivalent fix must already exist in Linus' tree (upstream). + + +Procedure for submitting patches to the -stable tree +---------------------------------------------------- + + - If the patch covers files in net/ or drivers/net please follow netdev stable + submission guidelines as described in + Documentation/networking/netdev-FAQ.txt + - Security patches should not be handled (solely) by the -stable review + process but should follow the procedures in + :ref:`Documentation/SecurityBugs `. + +For all other submissions, choose one of the following procedures +----------------------------------------------------------------- + +.. _option_1: + +Option 1 +******** + +To have the patch automatically included in the stable tree, add the tag + +.. code-block:: none + + Cc: stable@vger.kernel.org + +in the sign-off area. Once the patch is merged it will be applied to +the stable tree without anything else needing to be done by the author +or subsystem maintainer. + +.. _option_2: + +Option 2 +******** + +After the patch has been merged to Linus' tree, send an email to +stable@vger.kernel.org containing the subject of the patch, the commit ID, +why you think it should be applied, and what kernel version you wish it to +be applied to. + +.. _option_3: + +Option 3 +******** + +Send the patch, after verifying that it follows the above rules, to +stable@vger.kernel.org. You must note the upstream commit ID in the +changelog of your submission, as well as the kernel version you wish +it to be applied to. + +:ref:`option_1` is **strongly** preferred, is the easiest and most common. +:ref:`option_2` and :ref:`option_3` are more useful if the patch isn't deemed +worthy at the time it is applied to a public git tree (for instance, because +it deserves more regression testing first). :ref:`option_3` is especially +useful if the patch needs some special handling to apply to an older kernel +(e.g., if API's have changed in the meantime). + +Note that for :ref:`option_3`, if the patch deviates from the original +upstream patch (for example because it had to be backported) this must be very +clearly documented and justified in the patch description. + +The upstream commit ID must be specified with a separate line above the commit +text, like this: + +.. code-block:: none + + commit upstream. + +Additionally, some patches submitted via Option 1 may have additional patch +prerequisites which can be cherry-picked. This can be specified in the following +format in the sign-off area: + +.. code-block:: none + + Cc: # 3.3.x: a1f84a3: sched: Check for idle + Cc: # 3.3.x: 1b9508f: sched: Rate-limit newidle + Cc: # 3.3.x: fd21073: sched: Fix affinity logic + Cc: # 3.3.x + Signed-off-by: Ingo Molnar + +The tag sequence has the meaning of: + +.. code-block:: none + + git cherry-pick a1f84a3 + git cherry-pick 1b9508f + git cherry-pick fd21073 + git cherry-pick + +Also, some patches may have kernel version prerequisites. This can be +specified in the following format in the sign-off area: + +.. code-block:: none + + Cc: # 3.3.x- + +The tag has the meaning of: + +.. code-block:: none + + git cherry-pick + +For each "-stable" tree starting with the specified version. + +Following the submission: + + - The sender will receive an ACK when the patch has been accepted into the + queue, or a NAK if the patch is rejected. This response might take a few + days, according to the developer's schedules. + - If accepted, the patch will be added to the -stable queue, for review by + other developers and by the relevant subsystem maintainer. + + +Review cycle +------------ + + - When the -stable maintainers decide for a review cycle, the patches will be + sent to the review committee, and the maintainer of the affected area of + the patch (unless the submitter is the maintainer of the area) and CC: to + the linux-kernel mailing list. + - The review committee has 48 hours in which to ACK or NAK the patch. + - If the patch is rejected by a member of the committee, or linux-kernel + members object to the patch, bringing up issues that the maintainers and + members did not realize, the patch will be dropped from the queue. + - At the end of the review cycle, the ACKed patches will be added to the + latest -stable release, and a new -stable release will happen. + - Security patches will be accepted into the -stable tree directly from the + security kernel team, and not go through the normal review cycle. + Contact the kernel security team for more details on this procedure. + +Trees +----- + + - The queues of patches, for both completed versions and in progress + versions can be found at: + + http://git.kernel.org/?p=linux/kernel/git/stable/stable-queue.git + + - The finalized and tagged releases of all stable kernels can be found + in separate branches per version at: + + http://git.kernel.org/?p=linux/kernel/git/stable/linux-stable.git + + +Review committee +---------------- + + - This is made up of a number of kernel developers who have volunteered for + this task, and a few that haven't. diff --git a/Documentation/process/submit-checklist.rst b/Documentation/process/submit-checklist.rst new file mode 100644 index 000000000000..894289b22b15 --- /dev/null +++ b/Documentation/process/submit-checklist.rst @@ -0,0 +1,120 @@ +.. _submitchecklist: + +Linux Kernel patch submission checklist +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Here are some basic things that developers should do if they want to see their +kernel patch submissions accepted more quickly. + +These are all above and beyond the documentation that is provided in +:ref:`Documentation/SubmittingPatches ` +and elsewhere regarding submitting Linux kernel patches. + + +1) If you use a facility then #include the file that defines/declares + that facility. Don't depend on other header files pulling in ones + that you use. + +2) Builds cleanly: + + a) with applicable or modified ``CONFIG`` options ``=y``, ``=m``, and + ``=n``. No ``gcc`` warnings/errors, no linker warnings/errors. + + b) Passes ``allnoconfig``, ``allmodconfig`` + + c) Builds successfully when using ``O=builddir`` + +3) Builds on multiple CPU architectures by using local cross-compile tools + or some other build farm. + +4) ppc64 is a good architecture for cross-compilation checking because it + tends to use ``unsigned long`` for 64-bit quantities. + +5) Check your patch for general style as detailed in + :ref:`Documentation/CodingStyle `. + Check for trivial violations with the patch style checker prior to + submission (``scripts/checkpatch.pl``). + You should be able to justify all violations that remain in + your patch. + +6) Any new or modified ``CONFIG`` options don't muck up the config menu. + +7) All new ``Kconfig`` options have help text. + +8) Has been carefully reviewed with respect to relevant ``Kconfig`` + combinations. This is very hard to get right with testing -- brainpower + pays off here. + +9) Check cleanly with sparse. + +10) Use ``make checkstack`` and ``make namespacecheck`` and fix any problems + that they find. + + .. note:: + + ``checkstack`` does not point out problems explicitly, + but any one function that uses more than 512 bytes on the stack is a + candidate for change. + +11) Include :ref:`kernel-doc ` to document global kernel APIs. + (Not required for static functions, but OK there also.) Use + ``make htmldocs`` or ``make pdfdocs`` to check the + :ref:`kernel-doc ` and fix any issues. + +12) Has been tested with ``CONFIG_PREEMPT``, ``CONFIG_DEBUG_PREEMPT``, + ``CONFIG_DEBUG_SLAB``, ``CONFIG_DEBUG_PAGEALLOC``, ``CONFIG_DEBUG_MUTEXES``, + ``CONFIG_DEBUG_SPINLOCK``, ``CONFIG_DEBUG_ATOMIC_SLEEP``, + ``CONFIG_PROVE_RCU`` and ``CONFIG_DEBUG_OBJECTS_RCU_HEAD`` all + simultaneously enabled. + +13) Has been build- and runtime tested with and without ``CONFIG_SMP`` and + ``CONFIG_PREEMPT.`` + +14) If the patch affects IO/Disk, etc: has been tested with and without + ``CONFIG_LBDAF.`` + +15) All codepaths have been exercised with all lockdep features enabled. + +16) All new ``/proc`` entries are documented under ``Documentation/`` + +17) All new kernel boot parameters are documented in + ``Documentation/kernel-parameters.txt``. + +18) All new module parameters are documented with ``MODULE_PARM_DESC()`` + +19) All new userspace interfaces are documented in ``Documentation/ABI/``. + See ``Documentation/ABI/README`` for more information. + Patches that change userspace interfaces should be CCed to + linux-api@vger.kernel.org. + +20) Check that it all passes ``make headers_check``. + +21) Has been checked with injection of at least slab and page-allocation + failures. See ``Documentation/fault-injection/``. + + If the new code is substantial, addition of subsystem-specific fault + injection might be appropriate. + +22) Newly-added code has been compiled with ``gcc -W`` (use + ``make EXTRA_CFLAGS=-W``). This will generate lots of noise, but is good + for finding bugs like "warning: comparison between signed and unsigned". + +23) Tested after it has been merged into the -mm patchset to make sure + that it still works with all of the other queued patches and various + changes in the VM, VFS, and other subsystems. + +24) All memory barriers {e.g., ``barrier()``, ``rmb()``, ``wmb()``} need a + comment in the source code that explains the logic of what they are doing + and why. + +25) If any ioctl's are added by the patch, then also update + ``Documentation/ioctl/ioctl-number.txt``. + +26) If your modified source code depends on or uses any of the kernel + APIs or features that are related to the following ``Kconfig`` symbols, + then test multiple builds with the related ``Kconfig`` symbols disabled + and/or ``=m`` (if that option is available) [not all of these at the + same time, just various/random combinations of them]: + + ``CONFIG_SMP``, ``CONFIG_SYSFS``, ``CONFIG_PROC_FS``, ``CONFIG_INPUT``, ``CONFIG_PCI``, ``CONFIG_BLOCK``, ``CONFIG_PM``, ``CONFIG_MAGIC_SYSRQ``, + ``CONFIG_NET``, ``CONFIG_INET=n`` (but latter with ``CONFIG_NET=y``). diff --git a/Documentation/process/submitting-drivers.rst b/Documentation/process/submitting-drivers.rst new file mode 100644 index 000000000000..252b77a23fad --- /dev/null +++ b/Documentation/process/submitting-drivers.rst @@ -0,0 +1,183 @@ +.. _submittingdrivers: + +Submitting Drivers For The Linux Kernel +======================================= + +This document is intended to explain how to submit device drivers to the +various kernel trees. Note that if you are interested in video card drivers +you should probably talk to XFree86 (http://www.xfree86.org/) and/or X.Org +(http://x.org/) instead. + +Also read the Documentation/SubmittingPatches document. + + +Allocating Device Numbers +------------------------- + +Major and minor numbers for block and character devices are allocated +by the Linux assigned name and number authority (currently this is +Torben Mathiasen). The site is http://www.lanana.org/. This +also deals with allocating numbers for devices that are not going to +be submitted to the mainstream kernel. +See Documentation/devices.txt for more information on this. + +If you don't use assigned numbers then when your device is submitted it will +be given an assigned number even if that is different from values you may +have shipped to customers before. + +Who To Submit Drivers To +------------------------ + +Linux 2.0: + No new drivers are accepted for this kernel tree. + +Linux 2.2: + No new drivers are accepted for this kernel tree. + +Linux 2.4: + If the code area has a general maintainer then please submit it to + the maintainer listed in MAINTAINERS in the kernel file. If the + maintainer does not respond or you cannot find the appropriate + maintainer then please contact Willy Tarreau . + +Linux 2.6 and upper: + The same rules apply as 2.4 except that you should follow linux-kernel + to track changes in API's. The final contact point for Linux 2.6+ + submissions is Andrew Morton. + +What Criteria Determine Acceptance +---------------------------------- + +Licensing: + The code must be released to us under the + GNU General Public License. We don't insist on any kind + of exclusive GPL licensing, and if you wish the driver + to be useful to other communities such as BSD you may well + wish to release under multiple licenses. + See accepted licenses at include/linux/module.h + +Copyright: + The copyright owner must agree to use of GPL. + It's best if the submitter and copyright owner + are the same person/entity. If not, the name of + the person/entity authorizing use of GPL should be + listed in case it's necessary to verify the will of + the copyright owner. + +Interfaces: + If your driver uses existing interfaces and behaves like + other drivers in the same class it will be much more likely + to be accepted than if it invents gratuitous new ones. + If you need to implement a common API over Linux and NT + drivers do it in userspace. + +Code: + Please use the Linux style of code formatting as documented + in :ref:`Documentation/CodingStyle `. + If you have sections of code + that need to be in other formats, for example because they + are shared with a windows driver kit and you want to + maintain them just once separate them out nicely and note + this fact. + +Portability: + Pointers are not always 32bits, not all computers are little + endian, people do not all have floating point and you + shouldn't use inline x86 assembler in your driver without + careful thought. Pure x86 drivers generally are not popular. + If you only have x86 hardware it is hard to test portability + but it is easy to make sure the code can easily be made + portable. + +Clarity: + It helps if anyone can see how to fix the driver. It helps + you because you get patches not bug reports. If you submit a + driver that intentionally obfuscates how the hardware works + it will go in the bitbucket. + +PM support: + Since Linux is used on many portable and desktop systems, your + driver is likely to be used on such a system and therefore it + should support basic power management by implementing, if + necessary, the .suspend and .resume methods used during the + system-wide suspend and resume transitions. You should verify + that your driver correctly handles the suspend and resume, but + if you are unable to ensure that, please at least define the + .suspend method returning the -ENOSYS ("Function not + implemented") error. You should also try to make sure that your + driver uses as little power as possible when it's not doing + anything. For the driver testing instructions see + Documentation/power/drivers-testing.txt and for a relatively + complete overview of the power management issues related to + drivers see Documentation/power/devices.txt . + +Control: + In general if there is active maintenance of a driver by + the author then patches will be redirected to them unless + they are totally obvious and without need of checking. + If you want to be the contact and update point for the + driver it is a good idea to state this in the comments, + and include an entry in MAINTAINERS for your driver. + +What Criteria Do Not Determine Acceptance +----------------------------------------- + +Vendor: + Being the hardware vendor and maintaining the driver is + often a good thing. If there is a stable working driver from + other people already in the tree don't expect 'we are the + vendor' to get your driver chosen. Ideally work with the + existing driver author to build a single perfect driver. + +Author: + It doesn't matter if a large Linux company wrote the driver, + or you did. Nobody has any special access to the kernel + tree. Anyone who tells you otherwise isn't telling the + whole story. + + +Resources +--------- + +Linux kernel master tree: + ftp.\ *country_code*\ .kernel.org:/pub/linux/kernel/... + + where *country_code* == your country code, such as + **us**, **uk**, **fr**, etc. + + http://git.kernel.org/?p=linux/kernel/git/torvalds/linux.git + +Linux kernel mailing list: + linux-kernel@vger.kernel.org + [mail majordomo@vger.kernel.org to subscribe] + +Linux Device Drivers, Third Edition (covers 2.6.10): + http://lwn.net/Kernel/LDD3/ (free version) + +LWN.net: + Weekly summary of kernel development activity - http://lwn.net/ + + 2.6 API changes: + + http://lwn.net/Articles/2.6-kernel-api/ + + Porting drivers from prior kernels to 2.6: + + http://lwn.net/Articles/driver-porting/ + +KernelNewbies: + Documentation and assistance for new kernel programmers + + http://kernelnewbies.org/ + +Linux USB project: + http://www.linux-usb.org/ + +How to NOT write kernel driver by Arjan van de Ven: + http://www.fenrus.org/how-to-not-write-a-device-driver-paper.pdf + +Kernel Janitor: + http://kernelnewbies.org/KernelJanitors + +GIT, Fast Version Control System: + http://git-scm.com/ diff --git a/Documentation/process/submitting-patches.rst b/Documentation/process/submitting-patches.rst new file mode 100644 index 000000000000..4cc20b2c6df3 --- /dev/null +++ b/Documentation/process/submitting-patches.rst @@ -0,0 +1,840 @@ +.. _submittingpatches: + +How to Get Your Change Into the Linux Kernel or Care And Operation Of Your Linus Torvalds +========================================================================================= + +For a person or company who wishes to submit a change to the Linux +kernel, the process can sometimes be daunting if you're not familiar +with "the system." This text is a collection of suggestions which +can greatly increase the chances of your change being accepted. + +This document contains a large number of suggestions in a relatively terse +format. For detailed information on how the kernel development process +works, see :ref:`Documentation/process `. +Also, read :ref:`Documentation/SubmitChecklist ` +for a list of items to check before +submitting code. If you are submitting a driver, also read +:ref:`Documentation/SubmittingDrivers `; +for device tree binding patches, read +Documentation/devicetree/bindings/submitting-patches.txt. + +Many of these steps describe the default behavior of the ``git`` version +control system; if you use ``git`` to prepare your patches, you'll find much +of the mechanical work done for you, though you'll still need to prepare +and document a sensible set of patches. In general, use of ``git`` will make +your life as a kernel developer easier. + +Creating and Sending your Change +******************************** + + +0) Obtain a current source tree +------------------------------- + +If you do not have a repository with the current kernel source handy, use +``git`` to obtain one. You'll want to start with the mainline repository, +which can be grabbed with:: + + git clone git://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git + +Note, however, that you may not want to develop against the mainline tree +directly. Most subsystem maintainers run their own trees and want to see +patches prepared against those trees. See the **T:** entry for the subsystem +in the MAINTAINERS file to find that tree, or simply ask the maintainer if +the tree is not listed there. + +It is still possible to download kernel releases via tarballs (as described +in the next section), but that is the hard way to do kernel development. + +1) ``diff -up`` +--------------- + +If you must generate your patches by hand, use ``diff -up`` or ``diff -uprN`` +to create patches. Git generates patches in this form by default; if +you're using ``git``, you can skip this section entirely. + +All changes to the Linux kernel occur in the form of patches, as +generated by :manpage:`diff(1)`. When creating your patch, make sure to +create it in "unified diff" format, as supplied by the ``-u`` argument +to :manpage:`diff(1)`. +Also, please use the ``-p`` argument which shows which C function each +change is in - that makes the resultant ``diff`` a lot easier to read. +Patches should be based in the root kernel source directory, +not in any lower subdirectory. + +To create a patch for a single file, it is often sufficient to do:: + + SRCTREE= linux + MYFILE= drivers/net/mydriver.c + + cd $SRCTREE + cp $MYFILE $MYFILE.orig + vi $MYFILE # make your change + cd .. + diff -up $SRCTREE/$MYFILE{.orig,} > /tmp/patch + +To create a patch for multiple files, you should unpack a "vanilla", +or unmodified kernel source tree, and generate a ``diff`` against your +own source tree. For example:: + + MYSRC= /devel/linux + + tar xvfz linux-3.19.tar.gz + mv linux-3.19 linux-3.19-vanilla + diff -uprN -X linux-3.19-vanilla/Documentation/dontdiff \ + linux-3.19-vanilla $MYSRC > /tmp/patch + +``dontdiff`` is a list of files which are generated by the kernel during +the build process, and should be ignored in any :manpage:`diff(1)`-generated +patch. + +Make sure your patch does not include any extra files which do not +belong in a patch submission. Make sure to review your patch -after- +generating it with :manpage:`diff(1)`, to ensure accuracy. + +If your changes produce a lot of deltas, you need to split them into +individual patches which modify things in logical stages; see +:ref:`split_changes`. This will facilitate review by other kernel developers, +very important if you want your patch accepted. + +If you're using ``git``, ``git rebase -i`` can help you with this process. If +you're not using ``git``, ``quilt`` +is another popular alternative. + +.. _describe_changes: + +2) Describe your changes +------------------------ + +Describe your problem. Whether your patch is a one-line bug fix or +5000 lines of a new feature, there must be an underlying problem that +motivated you to do this work. Convince the reviewer that there is a +problem worth fixing and that it makes sense for them to read past the +first paragraph. + +Describe user-visible impact. Straight up crashes and lockups are +pretty convincing, but not all bugs are that blatant. Even if the +problem was spotted during code review, describe the impact you think +it can have on users. Keep in mind that the majority of Linux +installations run kernels from secondary stable trees or +vendor/product-specific trees that cherry-pick only specific patches +from upstream, so include anything that could help route your change +downstream: provoking circumstances, excerpts from dmesg, crash +descriptions, performance regressions, latency spikes, lockups, etc. + +Quantify optimizations and trade-offs. If you claim improvements in +performance, memory consumption, stack footprint, or binary size, +include numbers that back them up. But also describe non-obvious +costs. Optimizations usually aren't free but trade-offs between CPU, +memory, and readability; or, when it comes to heuristics, between +different workloads. Describe the expected downsides of your +optimization so that the reviewer can weigh costs against benefits. + +Once the problem is established, describe what you are actually doing +about it in technical detail. It's important to describe the change +in plain English for the reviewer to verify that the code is behaving +as you intend it to. + +The maintainer will thank you if you write your patch description in a +form which can be easily pulled into Linux's source code management +system, ``git``, as a "commit log". See :ref:`explicit_in_reply_to`. + +Solve only one problem per patch. If your description starts to get +long, that's a sign that you probably need to split up your patch. +See :ref:`split_changes`. + +When you submit or resubmit a patch or patch series, include the +complete patch description and justification for it. Don't just +say that this is version N of the patch (series). Don't expect the +subsystem maintainer to refer back to earlier patch versions or referenced +URLs to find the patch description and put that into the patch. +I.e., the patch (series) and its description should be self-contained. +This benefits both the maintainers and reviewers. Some reviewers +probably didn't even receive earlier versions of the patch. + +Describe your changes in imperative mood, e.g. "make xyzzy do frotz" +instead of "[This patch] makes xyzzy do frotz" or "[I] changed xyzzy +to do frotz", as if you are giving orders to the codebase to change +its behaviour. + +If the patch fixes a logged bug entry, refer to that bug entry by +number and URL. If the patch follows from a mailing list discussion, +give a URL to the mailing list archive; use the https://lkml.kernel.org/ +redirector with a ``Message-Id``, to ensure that the links cannot become +stale. + +However, try to make your explanation understandable without external +resources. In addition to giving a URL to a mailing list archive or +bug, summarize the relevant points of the discussion that led to the +patch as submitted. + +If you want to refer to a specific commit, don't just refer to the +SHA-1 ID of the commit. Please also include the oneline summary of +the commit, to make it easier for reviewers to know what it is about. +Example:: + + Commit e21d2170f36602ae2708 ("video: remove unnecessary + platform_set_drvdata()") removed the unnecessary + platform_set_drvdata(), but left the variable "dev" unused, + delete it. + +You should also be sure to use at least the first twelve characters of the +SHA-1 ID. The kernel repository holds a *lot* of objects, making +collisions with shorter IDs a real possibility. Bear in mind that, even if +there is no collision with your six-character ID now, that condition may +change five years from now. + +If your patch fixes a bug in a specific commit, e.g. you found an issue using +``git bisect``, please use the 'Fixes:' tag with the first 12 characters of +the SHA-1 ID, and the one line summary. For example:: + + Fixes: e21d2170f366 ("video: remove unnecessary platform_set_drvdata()") + +The following ``git config`` settings can be used to add a pretty format for +outputting the above style in the ``git log`` or ``git show`` commands:: + + [core] + abbrev = 12 + [pretty] + fixes = Fixes: %h (\"%s\") + +.. _split_changes: + +3) Separate your changes +------------------------ + +Separate each **logical change** into a separate patch. + +For example, if your changes include both bug fixes and performance +enhancements for a single driver, separate those changes into two +or more patches. If your changes include an API update, and a new +driver which uses that new API, separate those into two patches. + +On the other hand, if you make a single change to numerous files, +group those changes into a single patch. Thus a single logical change +is contained within a single patch. + +The point to remember is that each patch should make an easily understood +change that can be verified by reviewers. Each patch should be justifiable +on its own merits. + +If one patch depends on another patch in order for a change to be +complete, that is OK. Simply note **"this patch depends on patch X"** +in your patch description. + +When dividing your change into a series of patches, take special care to +ensure that the kernel builds and runs properly after each patch in the +series. Developers using ``git bisect`` to track down a problem can end up +splitting your patch series at any point; they will not thank you if you +introduce bugs in the middle. + +If you cannot condense your patch set into a smaller set of patches, +then only post say 15 or so at a time and wait for review and integration. + + + +4) Style-check your changes +--------------------------- + +Check your patch for basic style violations, details of which can be +found in +:ref:`Documentation/CodingStyle `. +Failure to do so simply wastes +the reviewers time and will get your patch rejected, probably +without even being read. + +One significant exception is when moving code from one file to +another -- in this case you should not modify the moved code at all in +the same patch which moves it. This clearly delineates the act of +moving the code and your changes. This greatly aids review of the +actual differences and allows tools to better track the history of +the code itself. + +Check your patches with the patch style checker prior to submission +(scripts/checkpatch.pl). Note, though, that the style checker should be +viewed as a guide, not as a replacement for human judgment. If your code +looks better with a violation then its probably best left alone. + +The checker reports at three levels: + - ERROR: things that are very likely to be wrong + - WARNING: things requiring careful review + - CHECK: things requiring thought + +You should be able to justify all violations that remain in your +patch. + + +5) Select the recipients for your patch +--------------------------------------- + +You should always copy the appropriate subsystem maintainer(s) on any patch +to code that they maintain; look through the MAINTAINERS file and the +source code revision history to see who those maintainers are. The +script scripts/get_maintainer.pl can be very useful at this step. If you +cannot find a maintainer for the subsystem you are working on, Andrew +Morton (akpm@linux-foundation.org) serves as a maintainer of last resort. + +You should also normally choose at least one mailing list to receive a copy +of your patch set. linux-kernel@vger.kernel.org functions as a list of +last resort, but the volume on that list has caused a number of developers +to tune it out. Look in the MAINTAINERS file for a subsystem-specific +list; your patch will probably get more attention there. Please do not +spam unrelated lists, though. + +Many kernel-related lists are hosted on vger.kernel.org; you can find a +list of them at http://vger.kernel.org/vger-lists.html. There are +kernel-related lists hosted elsewhere as well, though. + +Do not send more than 15 patches at once to the vger mailing lists!!! + +Linus Torvalds is the final arbiter of all changes accepted into the +Linux kernel. His e-mail address is . +He gets a lot of e-mail, and, at this point, very few patches go through +Linus directly, so typically you should do your best to -avoid- +sending him e-mail. + +If you have a patch that fixes an exploitable security bug, send that patch +to security@kernel.org. For severe bugs, a short embargo may be considered +to allow distributors to get the patch out to users; in such cases, +obviously, the patch should not be sent to any public lists. + +Patches that fix a severe bug in a released kernel should be directed +toward the stable maintainers by putting a line like this:: + + Cc: stable@vger.kernel.org + +into the sign-off area of your patch (note, NOT an email recipient). You +should also read +:ref:`Documentation/stable_kernel_rules.txt ` +in addition to this file. + +Note, however, that some subsystem maintainers want to come to their own +conclusions on which patches should go to the stable trees. The networking +maintainer, in particular, would rather not see individual developers +adding lines like the above to their patches. + +If changes affect userland-kernel interfaces, please send the MAN-PAGES +maintainer (as listed in the MAINTAINERS file) a man-pages patch, or at +least a notification of the change, so that some information makes its way +into the manual pages. User-space API changes should also be copied to +linux-api@vger.kernel.org. + +For small patches you may want to CC the Trivial Patch Monkey +trivial@kernel.org which collects "trivial" patches. Have a look +into the MAINTAINERS file for its current manager. + +Trivial patches must qualify for one of the following rules: + +- Spelling fixes in documentation +- Spelling fixes for errors which could break :manpage:`grep(1)` +- Warning fixes (cluttering with useless warnings is bad) +- Compilation fixes (only if they are actually correct) +- Runtime fixes (only if they actually fix things) +- Removing use of deprecated functions/macros +- Contact detail and documentation fixes +- Non-portable code replaced by portable code (even in arch-specific, + since people copy, as long as it's trivial) +- Any fix by the author/maintainer of the file (ie. patch monkey + in re-transmission mode) + + + +6) No MIME, no links, no compression, no attachments. Just plain text +---------------------------------------------------------------------- + +Linus and other kernel developers need to be able to read and comment +on the changes you are submitting. It is important for a kernel +developer to be able to "quote" your changes, using standard e-mail +tools, so that they may comment on specific portions of your code. + +For this reason, all patches should be submitted by e-mail "inline". + +.. warning:: + + Be wary of your editor's word-wrap corrupting your patch, + if you choose to cut-n-paste your patch. + +Do not attach the patch as a MIME attachment, compressed or not. +Many popular e-mail applications will not always transmit a MIME +attachment as plain text, making it impossible to comment on your +code. A MIME attachment also takes Linus a bit more time to process, +decreasing the likelihood of your MIME-attached change being accepted. + +Exception: If your mailer is mangling patches then someone may ask +you to re-send them using MIME. + +See :ref:`Documentation/email-clients.txt ` +for hints about configuring your e-mail client so that it sends your patches +untouched. + +7) E-mail size +-------------- + +Large changes are not appropriate for mailing lists, and some +maintainers. If your patch, uncompressed, exceeds 300 kB in size, +it is preferred that you store your patch on an Internet-accessible +server, and provide instead a URL (link) pointing to your patch. But note +that if your patch exceeds 300 kB, it almost certainly needs to be broken up +anyway. + +8) Respond to review comments +----------------------------- + +Your patch will almost certainly get comments from reviewers on ways in +which the patch can be improved. You must respond to those comments; +ignoring reviewers is a good way to get ignored in return. Review comments +or questions that do not lead to a code change should almost certainly +bring about a comment or changelog entry so that the next reviewer better +understands what is going on. + +Be sure to tell the reviewers what changes you are making and to thank them +for their time. Code review is a tiring and time-consuming process, and +reviewers sometimes get grumpy. Even in that case, though, respond +politely and address the problems they have pointed out. + + +9) Don't get discouraged - or impatient +--------------------------------------- + +After you have submitted your change, be patient and wait. Reviewers are +busy people and may not get to your patch right away. + +Once upon a time, patches used to disappear into the void without comment, +but the development process works more smoothly than that now. You should +receive comments within a week or so; if that does not happen, make sure +that you have sent your patches to the right place. Wait for a minimum of +one week before resubmitting or pinging reviewers - possibly longer during +busy times like merge windows. + + +10) Include PATCH in the subject +-------------------------------- + +Due to high e-mail traffic to Linus, and to linux-kernel, it is common +convention to prefix your subject line with [PATCH]. This lets Linus +and other kernel developers more easily distinguish patches from other +e-mail discussions. + + + +11) Sign your work +------------------ + +To improve tracking of who did what, especially with patches that can +percolate to their final resting place in the kernel through several +layers of maintainers, we've introduced a "sign-off" procedure on +patches that are being emailed around. + +The sign-off is a simple line at the end of the explanation for the +patch, which certifies that you wrote it or otherwise have the right to +pass it on as an open-source patch. The rules are pretty simple: if you +can certify the below: + +Developer's Certificate of Origin 1.1 +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +By making a contribution to this project, I certify that: + + (a) The contribution was created in whole or in part by me and I + have the right to submit it under the open source license + indicated in the file; or + + (b) The contribution is based upon previous work that, to the best + of my knowledge, is covered under an appropriate open source + license and I have the right under that license to submit that + work with modifications, whether created in whole or in part + by me, under the same open source license (unless I am + permitted to submit under a different license), as indicated + in the file; or + + (c) The contribution was provided directly to me by some other + person who certified (a), (b) or (c) and I have not modified + it. + + (d) I understand and agree that this project and the contribution + are public and that a record of the contribution (including all + personal information I submit with it, including my sign-off) is + maintained indefinitely and may be redistributed consistent with + this project or the open source license(s) involved. + +then you just add a line saying:: + + Signed-off-by: Random J Developer + +using your real name (sorry, no pseudonyms or anonymous contributions.) + +Some people also put extra tags at the end. They'll just be ignored for +now, but you can do this to mark internal company procedures or just +point out some special detail about the sign-off. + +If you are a subsystem or branch maintainer, sometimes you need to slightly +modify patches you receive in order to merge them, because the code is not +exactly the same in your tree and the submitters'. If you stick strictly to +rule (c), you should ask the submitter to rediff, but this is a totally +counter-productive waste of time and energy. Rule (b) allows you to adjust +the code, but then it is very impolite to change one submitter's code and +make him endorse your bugs. To solve this problem, it is recommended that +you add a line between the last Signed-off-by header and yours, indicating +the nature of your changes. While there is nothing mandatory about this, it +seems like prepending the description with your mail and/or name, all +enclosed in square brackets, is noticeable enough to make it obvious that +you are responsible for last-minute changes. Example:: + + Signed-off-by: Random J Developer + [lucky@maintainer.example.org: struct foo moved from foo.c to foo.h] + Signed-off-by: Lucky K Maintainer + +This practice is particularly helpful if you maintain a stable branch and +want at the same time to credit the author, track changes, merge the fix, +and protect the submitter from complaints. Note that under no circumstances +can you change the author's identity (the From header), as it is the one +which appears in the changelog. + +Special note to back-porters: It seems to be a common and useful practice +to insert an indication of the origin of a patch at the top of the commit +message (just after the subject line) to facilitate tracking. For instance, +here's what we see in a 3.x-stable release:: + + Date: Tue Oct 7 07:26:38 2014 -0400 + + libata: Un-break ATA blacklist + + commit 1c40279960bcd7d52dbdf1d466b20d24b99176c8 upstream. + +And here's what might appear in an older kernel once a patch is backported:: + + Date: Tue May 13 22:12:27 2008 +0200 + + wireless, airo: waitbusy() won't delay + + [backport of 2.6 commit b7acbdfbd1f277c1eb23f344f899cfa4cd0bf36a] + +Whatever the format, this information provides a valuable help to people +tracking your trees, and to people trying to troubleshoot bugs in your +tree. + + +12) When to use Acked-by: and Cc: +--------------------------------- + +The Signed-off-by: tag indicates that the signer was involved in the +development of the patch, or that he/she was in the patch's delivery path. + +If a person was not directly involved in the preparation or handling of a +patch but wishes to signify and record their approval of it then they can +ask to have an Acked-by: line added to the patch's changelog. + +Acked-by: is often used by the maintainer of the affected code when that +maintainer neither contributed to nor forwarded the patch. + +Acked-by: is not as formal as Signed-off-by:. It is a record that the acker +has at least reviewed the patch and has indicated acceptance. Hence patch +mergers will sometimes manually convert an acker's "yep, looks good to me" +into an Acked-by: (but note that it is usually better to ask for an +explicit ack). + +Acked-by: does not necessarily indicate acknowledgement of the entire patch. +For example, if a patch affects multiple subsystems and has an Acked-by: from +one subsystem maintainer then this usually indicates acknowledgement of just +the part which affects that maintainer's code. Judgement should be used here. +When in doubt people should refer to the original discussion in the mailing +list archives. + +If a person has had the opportunity to comment on a patch, but has not +provided such comments, you may optionally add a ``Cc:`` tag to the patch. +This is the only tag which might be added without an explicit action by the +person it names - but it should indicate that this person was copied on the +patch. This tag documents that potentially interested parties +have been included in the discussion. + + +13) Using Reported-by:, Tested-by:, Reviewed-by:, Suggested-by: and Fixes: +-------------------------------------------------------------------------- + +The Reported-by tag gives credit to people who find bugs and report them and it +hopefully inspires them to help us again in the future. Please note that if +the bug was reported in private, then ask for permission first before using the +Reported-by tag. + +A Tested-by: tag indicates that the patch has been successfully tested (in +some environment) by the person named. This tag informs maintainers that +some testing has been performed, provides a means to locate testers for +future patches, and ensures credit for the testers. + +Reviewed-by:, instead, indicates that the patch has been reviewed and found +acceptable according to the Reviewer's Statement: + +Reviewer's statement of oversight +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +By offering my Reviewed-by: tag, I state that: + + (a) I have carried out a technical review of this patch to + evaluate its appropriateness and readiness for inclusion into + the mainline kernel. + + (b) Any problems, concerns, or questions relating to the patch + have been communicated back to the submitter. I am satisfied + with the submitter's response to my comments. + + (c) While there may be things that could be improved with this + submission, I believe that it is, at this time, (1) a + worthwhile modification to the kernel, and (2) free of known + issues which would argue against its inclusion. + + (d) While I have reviewed the patch and believe it to be sound, I + do not (unless explicitly stated elsewhere) make any + warranties or guarantees that it will achieve its stated + purpose or function properly in any given situation. + +A Reviewed-by tag is a statement of opinion that the patch is an +appropriate modification of the kernel without any remaining serious +technical issues. Any interested reviewer (who has done the work) can +offer a Reviewed-by tag for a patch. This tag serves to give credit to +reviewers and to inform maintainers of the degree of review which has been +done on the patch. Reviewed-by: tags, when supplied by reviewers known to +understand the subject area and to perform thorough reviews, will normally +increase the likelihood of your patch getting into the kernel. + +A Suggested-by: tag indicates that the patch idea is suggested by the person +named and ensures credit to the person for the idea. Please note that this +tag should not be added without the reporter's permission, especially if the +idea was not posted in a public forum. That said, if we diligently credit our +idea reporters, they will, hopefully, be inspired to help us again in the +future. + +A Fixes: tag indicates that the patch fixes an issue in a previous commit. It +is used to make it easy to determine where a bug originated, which can help +review a bug fix. This tag also assists the stable kernel team in determining +which stable kernel versions should receive your fix. This is the preferred +method for indicating a bug fixed by the patch. See :ref:`describe_changes` +for more details. + + +14) The canonical patch format +------------------------------ + +This section describes how the patch itself should be formatted. Note +that, if you have your patches stored in a ``git`` repository, proper patch +formatting can be had with ``git format-patch``. The tools cannot create +the necessary text, though, so read the instructions below anyway. + +The canonical patch subject line is:: + + Subject: [PATCH 001/123] subsystem: summary phrase + +The canonical patch message body contains the following: + + - A ``from`` line specifying the patch author (only needed if the person + sending the patch is not the author). + + - An empty line. + + - The body of the explanation, line wrapped at 75 columns, which will + be copied to the permanent changelog to describe this patch. + + - The ``Signed-off-by:`` lines, described above, which will + also go in the changelog. + + - A marker line containing simply ``---``. + + - Any additional comments not suitable for the changelog. + + - The actual patch (``diff`` output). + +The Subject line format makes it very easy to sort the emails +alphabetically by subject line - pretty much any email reader will +support that - since because the sequence number is zero-padded, +the numerical and alphabetic sort is the same. + +The ``subsystem`` in the email's Subject should identify which +area or subsystem of the kernel is being patched. + +The ``summary phrase`` in the email's Subject should concisely +describe the patch which that email contains. The ``summary +phrase`` should not be a filename. Do not use the same ``summary +phrase`` for every patch in a whole patch series (where a ``patch +series`` is an ordered sequence of multiple, related patches). + +Bear in mind that the ``summary phrase`` of your email becomes a +globally-unique identifier for that patch. It propagates all the way +into the ``git`` changelog. The ``summary phrase`` may later be used in +developer discussions which refer to the patch. People will want to +google for the ``summary phrase`` to read discussion regarding that +patch. It will also be the only thing that people may quickly see +when, two or three months later, they are going through perhaps +thousands of patches using tools such as ``gitk`` or ``git log +--oneline``. + +For these reasons, the ``summary`` must be no more than 70-75 +characters, and it must describe both what the patch changes, as well +as why the patch might be necessary. It is challenging to be both +succinct and descriptive, but that is what a well-written summary +should do. + +The ``summary phrase`` may be prefixed by tags enclosed in square +brackets: "Subject: [PATCH ...] ". The tags are +not considered part of the summary phrase, but describe how the patch +should be treated. Common tags might include a version descriptor if +the multiple versions of the patch have been sent out in response to +comments (i.e., "v1, v2, v3"), or "RFC" to indicate a request for +comments. If there are four patches in a patch series the individual +patches may be numbered like this: 1/4, 2/4, 3/4, 4/4. This assures +that developers understand the order in which the patches should be +applied and that they have reviewed or applied all of the patches in +the patch series. + +A couple of example Subjects:: + + Subject: [PATCH 2/5] ext2: improve scalability of bitmap searching + Subject: [PATCH v2 01/27] x86: fix eflags tracking + +The ``from`` line must be the very first line in the message body, +and has the form: + + From: Original Author + +The ``from`` line specifies who will be credited as the author of the +patch in the permanent changelog. If the ``from`` line is missing, +then the ``From:`` line from the email header will be used to determine +the patch author in the changelog. + +The explanation body will be committed to the permanent source +changelog, so should make sense to a competent reader who has long +since forgotten the immediate details of the discussion that might +have led to this patch. Including symptoms of the failure which the +patch addresses (kernel log messages, oops messages, etc.) is +especially useful for people who might be searching the commit logs +looking for the applicable patch. If a patch fixes a compile failure, +it may not be necessary to include _all_ of the compile failures; just +enough that it is likely that someone searching for the patch can find +it. As in the ``summary phrase``, it is important to be both succinct as +well as descriptive. + +The ``---`` marker line serves the essential purpose of marking for patch +handling tools where the changelog message ends. + +One good use for the additional comments after the ``---`` marker is for +a ``diffstat``, to show what files have changed, and the number of +inserted and deleted lines per file. A ``diffstat`` is especially useful +on bigger patches. Other comments relevant only to the moment or the +maintainer, not suitable for the permanent changelog, should also go +here. A good example of such comments might be ``patch changelogs`` +which describe what has changed between the v1 and v2 version of the +patch. + +If you are going to include a ``diffstat`` after the ``---`` marker, please +use ``diffstat`` options ``-p 1 -w 70`` so that filenames are listed from +the top of the kernel source tree and don't use too much horizontal +space (easily fit in 80 columns, maybe with some indentation). (``git`` +generates appropriate diffstats by default.) + +See more details on the proper patch format in the following +references. + +.. _explicit_in_reply_to: + +15) Explicit In-Reply-To headers +-------------------------------- + +It can be helpful to manually add In-Reply-To: headers to a patch +(e.g., when using ``git send-email``) to associate the patch with +previous relevant discussion, e.g. to link a bug fix to the email with +the bug report. However, for a multi-patch series, it is generally +best to avoid using In-Reply-To: to link to older versions of the +series. This way multiple versions of the patch don't become an +unmanageable forest of references in email clients. If a link is +helpful, you can use the https://lkml.kernel.org/ redirector (e.g., in +the cover email text) to link to an earlier version of the patch series. + + +16) Sending ``git pull`` requests +--------------------------------- + +If you have a series of patches, it may be most convenient to have the +maintainer pull them directly into the subsystem repository with a +``git pull`` operation. Note, however, that pulling patches from a developer +requires a higher degree of trust than taking patches from a mailing list. +As a result, many subsystem maintainers are reluctant to take pull +requests, especially from new, unknown developers. If in doubt you can use +the pull request as the cover letter for a normal posting of the patch +series, giving the maintainer the option of using either. + +A pull request should have [GIT] or [PULL] in the subject line. The +request itself should include the repository name and the branch of +interest on a single line; it should look something like:: + + Please pull from + + git://jdelvare.pck.nerim.net/jdelvare-2.6 i2c-for-linus + + to get these changes: + +A pull request should also include an overall message saying what will be +included in the request, a ``git shortlog`` listing of the patches +themselves, and a ``diffstat`` showing the overall effect of the patch series. +The easiest way to get all this information together is, of course, to let +``git`` do it for you with the ``git request-pull`` command. + +Some maintainers (including Linus) want to see pull requests from signed +commits; that increases their confidence that the request actually came +from you. Linus, in particular, will not pull from public hosting sites +like GitHub in the absence of a signed tag. + +The first step toward creating such tags is to make a GNUPG key and get it +signed by one or more core kernel developers. This step can be hard for +new developers, but there is no way around it. Attending conferences can +be a good way to find developers who can sign your key. + +Once you have prepared a patch series in ``git`` that you wish to have somebody +pull, create a signed tag with ``git tag -s``. This will create a new tag +identifying the last commit in the series and containing a signature +created with your private key. You will also have the opportunity to add a +changelog-style message to the tag; this is an ideal place to describe the +effects of the pull request as a whole. + +If the tree the maintainer will be pulling from is not the repository you +are working from, don't forget to push the signed tag explicitly to the +public tree. + +When generating your pull request, use the signed tag as the target. A +command like this will do the trick:: + + git request-pull master git://my.public.tree/linux.git my-signed-tag + + +REFERENCES +********** + +Andrew Morton, "The perfect patch" (tpp). + + +Jeff Garzik, "Linux kernel patch submission format". + + +Greg Kroah-Hartman, "How to piss off a kernel subsystem maintainer". + + + + + + + + + + + + +NO!!!! No more huge patch bombs to linux-kernel@vger.kernel.org people! + + +Kernel Documentation/CodingStyle: + :ref:`Documentation/CodingStyle ` + +Linus Torvalds's mail on the canonical patch format: + + +Andi Kleen, "On submitting kernel patches" + Some strategies to get difficult or controversial changes in. + + http://halobates.de/on-submitting-patches.pdf diff --git a/Documentation/process/volatile-considered-harmful.rst b/Documentation/process/volatile-considered-harmful.rst new file mode 100644 index 000000000000..e0d042af386c --- /dev/null +++ b/Documentation/process/volatile-considered-harmful.rst @@ -0,0 +1,122 @@ +Why the "volatile" type class should not be used +------------------------------------------------ + +C programmers have often taken volatile to mean that the variable could be +changed outside of the current thread of execution; as a result, they are +sometimes tempted to use it in kernel code when shared data structures are +being used. In other words, they have been known to treat volatile types +as a sort of easy atomic variable, which they are not. The use of volatile in +kernel code is almost never correct; this document describes why. + +The key point to understand with regard to volatile is that its purpose is +to suppress optimization, which is almost never what one really wants to +do. In the kernel, one must protect shared data structures against +unwanted concurrent access, which is very much a different task. The +process of protecting against unwanted concurrency will also avoid almost +all optimization-related problems in a more efficient way. + +Like volatile, the kernel primitives which make concurrent access to data +safe (spinlocks, mutexes, memory barriers, etc.) are designed to prevent +unwanted optimization. If they are being used properly, there will be no +need to use volatile as well. If volatile is still necessary, there is +almost certainly a bug in the code somewhere. In properly-written kernel +code, volatile can only serve to slow things down. + +Consider a typical block of kernel code:: + + spin_lock(&the_lock); + do_something_on(&shared_data); + do_something_else_with(&shared_data); + spin_unlock(&the_lock); + +If all the code follows the locking rules, the value of shared_data cannot +change unexpectedly while the_lock is held. Any other code which might +want to play with that data will be waiting on the lock. The spinlock +primitives act as memory barriers - they are explicitly written to do so - +meaning that data accesses will not be optimized across them. So the +compiler might think it knows what will be in shared_data, but the +spin_lock() call, since it acts as a memory barrier, will force it to +forget anything it knows. There will be no optimization problems with +accesses to that data. + +If shared_data were declared volatile, the locking would still be +necessary. But the compiler would also be prevented from optimizing access +to shared_data _within_ the critical section, when we know that nobody else +can be working with it. While the lock is held, shared_data is not +volatile. When dealing with shared data, proper locking makes volatile +unnecessary - and potentially harmful. + +The volatile storage class was originally meant for memory-mapped I/O +registers. Within the kernel, register accesses, too, should be protected +by locks, but one also does not want the compiler "optimizing" register +accesses within a critical section. But, within the kernel, I/O memory +accesses are always done through accessor functions; accessing I/O memory +directly through pointers is frowned upon and does not work on all +architectures. Those accessors are written to prevent unwanted +optimization, so, once again, volatile is unnecessary. + +Another situation where one might be tempted to use volatile is +when the processor is busy-waiting on the value of a variable. The right +way to perform a busy wait is:: + + while (my_variable != what_i_want) + cpu_relax(); + +The cpu_relax() call can lower CPU power consumption or yield to a +hyperthreaded twin processor; it also happens to serve as a compiler +barrier, so, once again, volatile is unnecessary. Of course, busy- +waiting is generally an anti-social act to begin with. + +There are still a few rare situations where volatile makes sense in the +kernel: + + - The above-mentioned accessor functions might use volatile on + architectures where direct I/O memory access does work. Essentially, + each accessor call becomes a little critical section on its own and + ensures that the access happens as expected by the programmer. + + - Inline assembly code which changes memory, but which has no other + visible side effects, risks being deleted by GCC. Adding the volatile + keyword to asm statements will prevent this removal. + + - The jiffies variable is special in that it can have a different value + every time it is referenced, but it can be read without any special + locking. So jiffies can be volatile, but the addition of other + variables of this type is strongly frowned upon. Jiffies is considered + to be a "stupid legacy" issue (Linus's words) in this regard; fixing it + would be more trouble than it is worth. + + - Pointers to data structures in coherent memory which might be modified + by I/O devices can, sometimes, legitimately be volatile. A ring buffer + used by a network adapter, where that adapter changes pointers to + indicate which descriptors have been processed, is an example of this + type of situation. + +For most code, none of the above justifications for volatile apply. As a +result, the use of volatile is likely to be seen as a bug and will bring +additional scrutiny to the code. Developers who are tempted to use +volatile should take a step back and think about what they are truly trying +to accomplish. + +Patches to remove volatile variables are generally welcome - as long as +they come with a justification which shows that the concurrency issues have +been properly thought through. + + +References +========== + +[1] http://lwn.net/Articles/233481/ + +[2] http://lwn.net/Articles/233482/ + +Credits +======= + +Original impetus and research by Randy Dunlap + +Written by Jonathan Corbet + +Improvements via comments from Satyam Sharma, Johannes Stezenbach, Jesper +Juhl, Heikki Orsila, H. Peter Anvin, Philipp Hahn, and Stefan +Richter. diff --git a/Documentation/stable_api_nonsense.txt b/Documentation/stable_api_nonsense.txt deleted file mode 100644 index 24f5aeecee91..000000000000 --- a/Documentation/stable_api_nonsense.txt +++ /dev/null @@ -1,205 +0,0 @@ -.. _stable_api_nonsense: - -The Linux Kernel Driver Interface -================================== - -(all of your questions answered and then some) - -Greg Kroah-Hartman - -This is being written to try to explain why Linux **does not have a binary -kernel interface, nor does it have a stable kernel interface**. - -.. note:: - - Please realize that this article describes the **in kernel** interfaces, not - the kernel to userspace interfaces. - - The kernel to userspace interface is the one that application programs use, - the syscall interface. That interface is **very** stable over time, and - will not break. I have old programs that were built on a pre 0.9something - kernel that still work just fine on the latest 2.6 kernel release. - That interface is the one that users and application programmers can count - on being stable. - - -Executive Summary ------------------ -You think you want a stable kernel interface, but you really do not, and -you don't even know it. What you want is a stable running driver, and -you get that only if your driver is in the main kernel tree. You also -get lots of other good benefits if your driver is in the main kernel -tree, all of which has made Linux into such a strong, stable, and mature -operating system which is the reason you are using it in the first -place. - - -Intro ------ - -It's only the odd person who wants to write a kernel driver that needs -to worry about the in-kernel interfaces changing. For the majority of -the world, they neither see this interface, nor do they care about it at -all. - -First off, I'm not going to address **any** legal issues about closed -source, hidden source, binary blobs, source wrappers, or any other term -that describes kernel drivers that do not have their source code -released under the GPL. Please consult a lawyer if you have any legal -questions, I'm a programmer and hence, I'm just going to be describing -the technical issues here (not to make light of the legal issues, they -are real, and you do need to be aware of them at all times.) - -So, there are two main topics here, binary kernel interfaces and stable -kernel source interfaces. They both depend on each other, but we will -discuss the binary stuff first to get it out of the way. - - -Binary Kernel Interface ------------------------ -Assuming that we had a stable kernel source interface for the kernel, a -binary interface would naturally happen too, right? Wrong. Please -consider the following facts about the Linux kernel: - - - Depending on the version of the C compiler you use, different kernel - data structures will contain different alignment of structures, and - possibly include different functions in different ways (putting - functions inline or not.) The individual function organization - isn't that important, but the different data structure padding is - very important. - - - Depending on what kernel build options you select, a wide range of - different things can be assumed by the kernel: - - - different structures can contain different fields - - Some functions may not be implemented at all, (i.e. some locks - compile away to nothing for non-SMP builds.) - - Memory within the kernel can be aligned in different ways, - depending on the build options. - - - Linux runs on a wide range of different processor architectures. - There is no way that binary drivers from one architecture will run - on another architecture properly. - -Now a number of these issues can be addressed by simply compiling your -module for the exact specific kernel configuration, using the same exact -C compiler that the kernel was built with. This is sufficient if you -want to provide a module for a specific release version of a specific -Linux distribution. But multiply that single build by the number of -different Linux distributions and the number of different supported -releases of the Linux distribution and you quickly have a nightmare of -different build options on different releases. Also realize that each -Linux distribution release contains a number of different kernels, all -tuned to different hardware types (different processor types and -different options), so for even a single release you will need to create -multiple versions of your module. - -Trust me, you will go insane over time if you try to support this kind -of release, I learned this the hard way a long time ago... - - -Stable Kernel Source Interfaces -------------------------------- - -This is a much more "volatile" topic if you talk to people who try to -keep a Linux kernel driver that is not in the main kernel tree up to -date over time. - -Linux kernel development is continuous and at a rapid pace, never -stopping to slow down. As such, the kernel developers find bugs in -current interfaces, or figure out a better way to do things. If they do -that, they then fix the current interfaces to work better. When they do -so, function names may change, structures may grow or shrink, and -function parameters may be reworked. If this happens, all of the -instances of where this interface is used within the kernel are fixed up -at the same time, ensuring that everything continues to work properly. - -As a specific examples of this, the in-kernel USB interfaces have -undergone at least three different reworks over the lifetime of this -subsystem. These reworks were done to address a number of different -issues: - - - A change from a synchronous model of data streams to an asynchronous - one. This reduced the complexity of a number of drivers and - increased the throughput of all USB drivers such that we are now - running almost all USB devices at their maximum speed possible. - - A change was made in the way data packets were allocated from the - USB core by USB drivers so that all drivers now needed to provide - more information to the USB core to fix a number of documented - deadlocks. - -This is in stark contrast to a number of closed source operating systems -which have had to maintain their older USB interfaces over time. This -provides the ability for new developers to accidentally use the old -interfaces and do things in improper ways, causing the stability of the -operating system to suffer. - -In both of these instances, all developers agreed that these were -important changes that needed to be made, and they were made, with -relatively little pain. If Linux had to ensure that it will preserve a -stable source interface, a new interface would have been created, and -the older, broken one would have had to be maintained over time, leading -to extra work for the USB developers. Since all Linux USB developers do -their work on their own time, asking programmers to do extra work for no -gain, for free, is not a possibility. - -Security issues are also very important for Linux. When a -security issue is found, it is fixed in a very short amount of time. A -number of times this has caused internal kernel interfaces to be -reworked to prevent the security problem from occurring. When this -happens, all drivers that use the interfaces were also fixed at the -same time, ensuring that the security problem was fixed and could not -come back at some future time accidentally. If the internal interfaces -were not allowed to change, fixing this kind of security problem and -insuring that it could not happen again would not be possible. - -Kernel interfaces are cleaned up over time. If there is no one using a -current interface, it is deleted. This ensures that the kernel remains -as small as possible, and that all potential interfaces are tested as -well as they can be (unused interfaces are pretty much impossible to -test for validity.) - - -What to do ----------- - -So, if you have a Linux kernel driver that is not in the main kernel -tree, what are you, a developer, supposed to do? Releasing a binary -driver for every different kernel version for every distribution is a -nightmare, and trying to keep up with an ever changing kernel interface -is also a rough job. - -Simple, get your kernel driver into the main kernel tree (remember we -are talking about GPL released drivers here, if your code doesn't fall -under this category, good luck, you are on your own here, you leech -.) If your -driver is in the tree, and a kernel interface changes, it will be fixed -up by the person who did the kernel change in the first place. This -ensures that your driver is always buildable, and works over time, with -very little effort on your part. - -The very good side effects of having your driver in the main kernel tree -are: - - - The quality of the driver will rise as the maintenance costs (to the - original developer) will decrease. - - Other developers will add features to your driver. - - Other people will find and fix bugs in your driver. - - Other people will find tuning opportunities in your driver. - - Other people will update the driver for you when external interface - changes require it. - - The driver automatically gets shipped in all Linux distributions - without having to ask the distros to add it. - -As Linux supports a larger number of different devices "out of the box" -than any other operating system, and it supports these devices on more -different processor architectures than any other operating system, this -proven type of development model must be doing something right :) - - - ------- - -Thanks to Randy Dunlap, Andrew Morton, David Brownell, Hanna Linder, -Robert Love, and Nishanth Aravamudan for their review and comments on -early drafts of this paper. diff --git a/Documentation/stable_kernel_rules.txt b/Documentation/stable_kernel_rules.txt deleted file mode 100644 index 4d82e31b7958..000000000000 --- a/Documentation/stable_kernel_rules.txt +++ /dev/null @@ -1,181 +0,0 @@ -.. _stable_kernel_rules: - -Everything you ever wanted to know about Linux -stable releases -=============================================================== - -Rules on what kind of patches are accepted, and which ones are not, into the -"-stable" tree: - - - It must be obviously correct and tested. - - It cannot be bigger than 100 lines, with context. - - It must fix only one thing. - - It must fix a real bug that bothers people (not a, "This could be a - problem..." type thing). - - It must fix a problem that causes a build error (but not for things - marked CONFIG_BROKEN), an oops, a hang, data corruption, a real - security issue, or some "oh, that's not good" issue. In short, something - critical. - - Serious issues as reported by a user of a distribution kernel may also - be considered if they fix a notable performance or interactivity issue. - As these fixes are not as obvious and have a higher risk of a subtle - regression they should only be submitted by a distribution kernel - maintainer and include an addendum linking to a bugzilla entry if it - exists and additional information on the user-visible impact. - - New device IDs and quirks are also accepted. - - No "theoretical race condition" issues, unless an explanation of how the - race can be exploited is also provided. - - It cannot contain any "trivial" fixes in it (spelling changes, - whitespace cleanups, etc). - - It must follow the - :ref:`Documentation/SubmittingPatches ` - rules. - - It or an equivalent fix must already exist in Linus' tree (upstream). - - -Procedure for submitting patches to the -stable tree ----------------------------------------------------- - - - If the patch covers files in net/ or drivers/net please follow netdev stable - submission guidelines as described in - Documentation/networking/netdev-FAQ.txt - - Security patches should not be handled (solely) by the -stable review - process but should follow the procedures in - :ref:`Documentation/SecurityBugs `. - -For all other submissions, choose one of the following procedures ------------------------------------------------------------------ - -.. _option_1: - -Option 1 -******** - -To have the patch automatically included in the stable tree, add the tag - -.. code-block:: none - - Cc: stable@vger.kernel.org - -in the sign-off area. Once the patch is merged it will be applied to -the stable tree without anything else needing to be done by the author -or subsystem maintainer. - -.. _option_2: - -Option 2 -******** - -After the patch has been merged to Linus' tree, send an email to -stable@vger.kernel.org containing the subject of the patch, the commit ID, -why you think it should be applied, and what kernel version you wish it to -be applied to. - -.. _option_3: - -Option 3 -******** - -Send the patch, after verifying that it follows the above rules, to -stable@vger.kernel.org. You must note the upstream commit ID in the -changelog of your submission, as well as the kernel version you wish -it to be applied to. - -:ref:`option_1` is **strongly** preferred, is the easiest and most common. -:ref:`option_2` and :ref:`option_3` are more useful if the patch isn't deemed -worthy at the time it is applied to a public git tree (for instance, because -it deserves more regression testing first). :ref:`option_3` is especially -useful if the patch needs some special handling to apply to an older kernel -(e.g., if API's have changed in the meantime). - -Note that for :ref:`option_3`, if the patch deviates from the original -upstream patch (for example because it had to be backported) this must be very -clearly documented and justified in the patch description. - -The upstream commit ID must be specified with a separate line above the commit -text, like this: - -.. code-block:: none - - commit upstream. - -Additionally, some patches submitted via Option 1 may have additional patch -prerequisites which can be cherry-picked. This can be specified in the following -format in the sign-off area: - -.. code-block:: none - - Cc: # 3.3.x: a1f84a3: sched: Check for idle - Cc: # 3.3.x: 1b9508f: sched: Rate-limit newidle - Cc: # 3.3.x: fd21073: sched: Fix affinity logic - Cc: # 3.3.x - Signed-off-by: Ingo Molnar - -The tag sequence has the meaning of: - -.. code-block:: none - - git cherry-pick a1f84a3 - git cherry-pick 1b9508f - git cherry-pick fd21073 - git cherry-pick - -Also, some patches may have kernel version prerequisites. This can be -specified in the following format in the sign-off area: - -.. code-block:: none - - Cc: # 3.3.x- - -The tag has the meaning of: - -.. code-block:: none - - git cherry-pick - -For each "-stable" tree starting with the specified version. - -Following the submission: - - - The sender will receive an ACK when the patch has been accepted into the - queue, or a NAK if the patch is rejected. This response might take a few - days, according to the developer's schedules. - - If accepted, the patch will be added to the -stable queue, for review by - other developers and by the relevant subsystem maintainer. - - -Review cycle ------------- - - - When the -stable maintainers decide for a review cycle, the patches will be - sent to the review committee, and the maintainer of the affected area of - the patch (unless the submitter is the maintainer of the area) and CC: to - the linux-kernel mailing list. - - The review committee has 48 hours in which to ACK or NAK the patch. - - If the patch is rejected by a member of the committee, or linux-kernel - members object to the patch, bringing up issues that the maintainers and - members did not realize, the patch will be dropped from the queue. - - At the end of the review cycle, the ACKed patches will be added to the - latest -stable release, and a new -stable release will happen. - - Security patches will be accepted into the -stable tree directly from the - security kernel team, and not go through the normal review cycle. - Contact the kernel security team for more details on this procedure. - -Trees ------ - - - The queues of patches, for both completed versions and in progress - versions can be found at: - - http://git.kernel.org/?p=linux/kernel/git/stable/stable-queue.git - - - The finalized and tagged releases of all stable kernels can be found - in separate branches per version at: - - http://git.kernel.org/?p=linux/kernel/git/stable/linux-stable.git - - -Review committee ----------------- - - - This is made up of a number of kernel developers who have volunteered for - this task, and a few that haven't. diff --git a/Documentation/volatile-considered-harmful.txt b/Documentation/volatile-considered-harmful.txt deleted file mode 100644 index e0d042af386c..000000000000 --- a/Documentation/volatile-considered-harmful.txt +++ /dev/null @@ -1,122 +0,0 @@ -Why the "volatile" type class should not be used ------------------------------------------------- - -C programmers have often taken volatile to mean that the variable could be -changed outside of the current thread of execution; as a result, they are -sometimes tempted to use it in kernel code when shared data structures are -being used. In other words, they have been known to treat volatile types -as a sort of easy atomic variable, which they are not. The use of volatile in -kernel code is almost never correct; this document describes why. - -The key point to understand with regard to volatile is that its purpose is -to suppress optimization, which is almost never what one really wants to -do. In the kernel, one must protect shared data structures against -unwanted concurrent access, which is very much a different task. The -process of protecting against unwanted concurrency will also avoid almost -all optimization-related problems in a more efficient way. - -Like volatile, the kernel primitives which make concurrent access to data -safe (spinlocks, mutexes, memory barriers, etc.) are designed to prevent -unwanted optimization. If they are being used properly, there will be no -need to use volatile as well. If volatile is still necessary, there is -almost certainly a bug in the code somewhere. In properly-written kernel -code, volatile can only serve to slow things down. - -Consider a typical block of kernel code:: - - spin_lock(&the_lock); - do_something_on(&shared_data); - do_something_else_with(&shared_data); - spin_unlock(&the_lock); - -If all the code follows the locking rules, the value of shared_data cannot -change unexpectedly while the_lock is held. Any other code which might -want to play with that data will be waiting on the lock. The spinlock -primitives act as memory barriers - they are explicitly written to do so - -meaning that data accesses will not be optimized across them. So the -compiler might think it knows what will be in shared_data, but the -spin_lock() call, since it acts as a memory barrier, will force it to -forget anything it knows. There will be no optimization problems with -accesses to that data. - -If shared_data were declared volatile, the locking would still be -necessary. But the compiler would also be prevented from optimizing access -to shared_data _within_ the critical section, when we know that nobody else -can be working with it. While the lock is held, shared_data is not -volatile. When dealing with shared data, proper locking makes volatile -unnecessary - and potentially harmful. - -The volatile storage class was originally meant for memory-mapped I/O -registers. Within the kernel, register accesses, too, should be protected -by locks, but one also does not want the compiler "optimizing" register -accesses within a critical section. But, within the kernel, I/O memory -accesses are always done through accessor functions; accessing I/O memory -directly through pointers is frowned upon and does not work on all -architectures. Those accessors are written to prevent unwanted -optimization, so, once again, volatile is unnecessary. - -Another situation where one might be tempted to use volatile is -when the processor is busy-waiting on the value of a variable. The right -way to perform a busy wait is:: - - while (my_variable != what_i_want) - cpu_relax(); - -The cpu_relax() call can lower CPU power consumption or yield to a -hyperthreaded twin processor; it also happens to serve as a compiler -barrier, so, once again, volatile is unnecessary. Of course, busy- -waiting is generally an anti-social act to begin with. - -There are still a few rare situations where volatile makes sense in the -kernel: - - - The above-mentioned accessor functions might use volatile on - architectures where direct I/O memory access does work. Essentially, - each accessor call becomes a little critical section on its own and - ensures that the access happens as expected by the programmer. - - - Inline assembly code which changes memory, but which has no other - visible side effects, risks being deleted by GCC. Adding the volatile - keyword to asm statements will prevent this removal. - - - The jiffies variable is special in that it can have a different value - every time it is referenced, but it can be read without any special - locking. So jiffies can be volatile, but the addition of other - variables of this type is strongly frowned upon. Jiffies is considered - to be a "stupid legacy" issue (Linus's words) in this regard; fixing it - would be more trouble than it is worth. - - - Pointers to data structures in coherent memory which might be modified - by I/O devices can, sometimes, legitimately be volatile. A ring buffer - used by a network adapter, where that adapter changes pointers to - indicate which descriptors have been processed, is an example of this - type of situation. - -For most code, none of the above justifications for volatile apply. As a -result, the use of volatile is likely to be seen as a bug and will bring -additional scrutiny to the code. Developers who are tempted to use -volatile should take a step back and think about what they are truly trying -to accomplish. - -Patches to remove volatile variables are generally welcome - as long as -they come with a justification which shows that the concurrency issues have -been properly thought through. - - -References -========== - -[1] http://lwn.net/Articles/233481/ - -[2] http://lwn.net/Articles/233482/ - -Credits -======= - -Original impetus and research by Randy Dunlap - -Written by Jonathan Corbet - -Improvements via comments from Satyam Sharma, Johannes Stezenbach, Jesper -Juhl, Heikki Orsila, H. Peter Anvin, Philipp Hahn, and Stefan -Richter. -- cgit v1.2.3 From 9d85025b0418163fae079c9ba8f8445212de8568 Mon Sep 17 00:00:00 2001 From: Mauro Carvalho Chehab Date: Wed, 21 Sep 2016 09:51:11 -0300 Subject: docs-rst: create an user's manual book Place README, REPORTING-BUGS, SecurityBugs and kernel-parameters on an user's manual book. As we'll be numbering the user's manual, remove the manual numbering from SecurityBugs. Signed-off-by: Mauro Carvalho Chehab --- Documentation/BUG-HUNTING | 248 -- Documentation/SecurityBugs | 46 - Documentation/VGA-softcursor.txt | 66 - Documentation/admin-guide/README.rst | 410 ++ Documentation/admin-guide/bad-memory.rst | 50 + Documentation/admin-guide/basic-profiling.rst | 68 + Documentation/admin-guide/binfmt-misc.rst | 151 + Documentation/admin-guide/braille-console.rst | 38 + Documentation/admin-guide/bug-hunting.rst | 248 ++ Documentation/admin-guide/conf.py | 10 + Documentation/admin-guide/devices.rst | 3350 +++++++++++++++ Documentation/admin-guide/dynamic-debug-howto.rst | 353 ++ Documentation/admin-guide/index.rst | 34 + Documentation/admin-guide/init.rst | 52 + Documentation/admin-guide/initrd.rst | 383 ++ Documentation/admin-guide/java.rst | 417 ++ Documentation/admin-guide/kernel-parameters.rst | 4577 +++++++++++++++++++++ Documentation/admin-guide/md.rst | 727 ++++ Documentation/admin-guide/mono.rst | 68 + Documentation/admin-guide/oops-tracing.rst | 300 ++ Documentation/admin-guide/parport.rst | 286 ++ Documentation/admin-guide/ramoops.rst | 154 + Documentation/admin-guide/reporting-bugs.rst | 182 + Documentation/admin-guide/security-bugs.rst | 46 + Documentation/admin-guide/serial-console.rst | 115 + Documentation/admin-guide/sysfs-rules.rst | 192 + Documentation/admin-guide/sysrq.rst | 289 ++ Documentation/admin-guide/unicode.rst | 189 + Documentation/admin-guide/vga-softcursor.rst | 66 + Documentation/bad_memory.txt | 51 - Documentation/basic_profiling.txt | 69 - Documentation/binfmt_misc.txt | 151 - Documentation/braille-console.txt | 38 - Documentation/conf.py | 2 + Documentation/devices.txt | 3351 --------------- Documentation/dynamic-debug-howto.txt | 353 -- Documentation/index.rst | 1 + Documentation/init.txt | 52 - Documentation/initrd.txt | 383 -- Documentation/java.txt | 418 -- Documentation/kernel-parameters.txt | 4577 --------------------- Documentation/md.txt | 727 ---- Documentation/mono.txt | 68 - Documentation/oops-tracing.txt | 300 -- Documentation/parport.txt | 286 -- Documentation/ramoops.txt | 154 - Documentation/serial-console.txt | 115 - Documentation/sysfs-rules.txt | 192 - Documentation/sysrq.txt | 289 -- Documentation/unicode.txt | 189 - README | 411 -- REPORTING-BUGS | 182 - 52 files changed, 12758 insertions(+), 12716 deletions(-) delete mode 100644 Documentation/BUG-HUNTING delete mode 100644 Documentation/SecurityBugs delete mode 100644 Documentation/VGA-softcursor.txt create mode 100644 Documentation/admin-guide/README.rst create mode 100644 Documentation/admin-guide/bad-memory.rst create mode 100644 Documentation/admin-guide/basic-profiling.rst create mode 100644 Documentation/admin-guide/binfmt-misc.rst create mode 100644 Documentation/admin-guide/braille-console.rst create mode 100644 Documentation/admin-guide/bug-hunting.rst create mode 100644 Documentation/admin-guide/conf.py create mode 100644 Documentation/admin-guide/devices.rst create mode 100644 Documentation/admin-guide/dynamic-debug-howto.rst create mode 100644 Documentation/admin-guide/index.rst create mode 100644 Documentation/admin-guide/init.rst create mode 100644 Documentation/admin-guide/initrd.rst create mode 100644 Documentation/admin-guide/java.rst create mode 100644 Documentation/admin-guide/kernel-parameters.rst create mode 100644 Documentation/admin-guide/md.rst create mode 100644 Documentation/admin-guide/mono.rst create mode 100644 Documentation/admin-guide/oops-tracing.rst create mode 100644 Documentation/admin-guide/parport.rst create mode 100644 Documentation/admin-guide/ramoops.rst create mode 100644 Documentation/admin-guide/reporting-bugs.rst create mode 100644 Documentation/admin-guide/security-bugs.rst create mode 100644 Documentation/admin-guide/serial-console.rst create mode 100644 Documentation/admin-guide/sysfs-rules.rst create mode 100644 Documentation/admin-guide/sysrq.rst create mode 100644 Documentation/admin-guide/unicode.rst create mode 100644 Documentation/admin-guide/vga-softcursor.rst delete mode 100644 Documentation/bad_memory.txt delete mode 100644 Documentation/basic_profiling.txt delete mode 100644 Documentation/binfmt_misc.txt delete mode 100644 Documentation/braille-console.txt delete mode 100644 Documentation/devices.txt delete mode 100644 Documentation/dynamic-debug-howto.txt delete mode 100644 Documentation/init.txt delete mode 100644 Documentation/initrd.txt delete mode 100644 Documentation/java.txt delete mode 100644 Documentation/kernel-parameters.txt delete mode 100644 Documentation/md.txt delete mode 100644 Documentation/mono.txt delete mode 100644 Documentation/oops-tracing.txt delete mode 100644 Documentation/parport.txt delete mode 100644 Documentation/ramoops.txt delete mode 100644 Documentation/serial-console.txt delete mode 100644 Documentation/sysfs-rules.txt delete mode 100644 Documentation/sysrq.txt delete mode 100644 Documentation/unicode.txt delete mode 100644 README delete mode 100644 REPORTING-BUGS diff --git a/Documentation/BUG-HUNTING b/Documentation/BUG-HUNTING deleted file mode 100644 index a8ef794aadae..000000000000 --- a/Documentation/BUG-HUNTING +++ /dev/null @@ -1,248 +0,0 @@ -Bug hunting -+++++++++++ - -Last updated: 20 December 2005 - -Introduction -============ - -Always try the latest kernel from kernel.org and build from source. If you are -not confident in doing that please report the bug to your distribution vendor -instead of to a kernel developer. - -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 -:ref:`Documentation/REPORTING-BUGS `. - -Devices not appearing -===================== - -Often this is caused by udev. Check that first before blaming it on the -kernel. - -Finding patch that caused a bug -=============================== - - - -Finding using ``git-bisect`` ----------------------------- - -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`` -- have fun - -Finding it the old way ----------------------- - -[Sat Mar 2 10:32:33 PST 1996 KERNEL_BUG-HOWTO lm@sgi.com (Larry McVoy)] - -This is how to track down a bug if you know nothing about kernel hacking. -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 - 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 - 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 - can probably do better than this but it gets tricky. - - - 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 - up with a list of directories that changed. For each of those - directories: - - 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:: - - mv dir dir.62 - mv dir.63 dir - find dir -name '*.[oa]' -print | xargs rm -f - - And then rebuild and retest. Assuming that all related - changes were contained in the sub directory, this should - isolate the change to a directory. - - Problems: changes in header files may have occurred; I've - 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 - - - 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 - - - You can take the old file and the new file and manually create - a merged file that has:: - - #ifdef VER62 - routine() - { - ... - } - #else - routine() - { - ... - } - #endif - - And then walk through that file, one routine at a time and - prefix it with:: - - #define VER62 - /* both routines here */ - #undef VER62 - - Then recompile, retest, move the ifdefs until you find the one - that makes the difference. - -Finally, you take all the info that you have, kernel revisions, bug -description, the extent to which you have narrowed it down, and pass -that off to whomever you believe is the maintainer of that section. -A post to linux.dev.kernel isn't such a bad idea if you've done some -work to narrow it down. - -If you get it down to a routine, you'll probably get a fix in 24 hours. - -My apologies to Linus and the other kernel hackers for describing this -brute force approach, it's hardly what a kernel hacker would do. However, -it does work and it lets non-hackers help fix bugs. And it is cool -because Linux snapshots will let you do this - something that you can't -do with vendor supplied releases. - -Fixing the bug -============== - -Nobody is going to tell you how to fix bugs. Seriously. You need to work it -out. But below are some hints on how to use the tools. - -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:: - - objdump -r -S -l --disassemble net/dccp/ipv4.o - -.. 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:: - - 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:: - - EIP: 0060:[] Not tainted VLI - -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:: - - EIP is at vt_ioctl+0xda8/0x1482 - -And recompile the kernel with ``CONFIG_DEBUG_INFO`` enabled:: - - make vmlinux - gdb vmlinux - (gdb) p vt_ioctl - (gdb) l *(0x
+ 0xda8) - -or, as one command:: - - (gdb) l *(vt_ioctl + 0xda8) - -If you have a call trace, such as:: - - Call Trace: - [] :jbd:log_wait_commit+0xa3/0xf5 - [] autoremove_wake_function+0x0/0x2e - [] :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:: - - gdb fs/jbd/jbd.ko - (gdb) p log_wait_commit - (gdb) l *(0x
+ 0xa3) - -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. - -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 :ref:`Documentation/SubmittingPatches ` -though to help your code get accepted. diff --git a/Documentation/SecurityBugs b/Documentation/SecurityBugs deleted file mode 100644 index 342d769834f6..000000000000 --- a/Documentation/SecurityBugs +++ /dev/null @@ -1,46 +0,0 @@ -.. _securitybugs: - -Security bugs -============= - -Linux kernel developers take security very seriously. As such, we'd -like to know when a security bug is found so that it can be fixed and -disclosed as quickly as possible. Please report security bugs to the -Linux kernel security team. - -1) Contact ----------- - -The Linux kernel security team can be contacted by email at -. This is a private list of security officers -who will help verify the bug report and develop and release a fix. -It is possible that the security team will bring in extra help from -area maintainers to understand and fix the security vulnerability. - -As it is with any bug, the more information provided the easier it -will be to diagnose and fix. Please review the procedure outlined in -REPORTING-BUGS if you are unclear about what information is helpful. -Any exploit code is very helpful and will not be released without -consent from the reporter unless it has already been made public. - -2) Disclosure -------------- - -The goal of the Linux kernel security team is to work with the -bug submitter to bug resolution as well as disclosure. We prefer -to fully disclose the bug as soon as possible. It is reasonable to -delay disclosure when the bug or the fix is not yet fully understood, -the solution is not well-tested or for vendor coordination. However, we -expect these delays to be short, measurable in days, not weeks or months. -A disclosure date is negotiated by the security team working with the -bug submitter as well as vendors. However, the kernel security team -holds the final say when setting a disclosure date. The timeframe for -disclosure is from immediate (esp. if it's already publicly known) -to a few weeks. As a basic default policy, we expect report date to -disclosure date to be on the order of 7 days. - -3) Non-disclosure agreements ----------------------------- - -The Linux kernel security team is not a formal body and therefore unable -to enter any non-disclosure agreements. diff --git a/Documentation/VGA-softcursor.txt b/Documentation/VGA-softcursor.txt deleted file mode 100644 index 9eac6744b3a1..000000000000 --- a/Documentation/VGA-softcursor.txt +++ /dev/null @@ -1,66 +0,0 @@ -Software cursor for VGA -======================= - -by Pavel Machek -and Martin Mares - -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 [#f1]_. You can now play a few new tricks: -you can make your cursor look - -like a non-blinking red block, make it inverse background of the character it's -over or to highlight that character and still choose whether the original -hardware cursor should remain visible or not. There may be other things I have -never thought of. - -The cursor appearance is controlled by a ``[?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. - -first Parameter - 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. - -second parameter - selects character attribute bits you want to change - (by simply XORing them with the value of this parameter). On standard - VGA, the high four bits specify background and the low four the - foreground. In both groups, low three bits set color (as in normal - color codes used by the console) and the most significant one turns - on highlight (or sometimes blinking -- it depends on the configuration - of your VGA). - -third parameter - consists of character attribute bits you want to set. - - Bit setting takes place before bit toggling, so you can simply clear a - bit by including it in both the set mask and the toggle mask. - -.. [#f1] see ``#define TRIDENT_GLITCH`` in ``drivers/video/vgacon.c``. - -Examples: -========= - -To get normal blinking underline, use:: - - echo -e '\033[?2c' - -To get blinking block, use:: - - echo -e '\033[?6c' - -To get red non-blinking block, use:: - - echo -e '\033[?17;0;64c' diff --git a/Documentation/admin-guide/README.rst b/Documentation/admin-guide/README.rst new file mode 100644 index 000000000000..05aad8543340 --- /dev/null +++ b/Documentation/admin-guide/README.rst @@ -0,0 +1,410 @@ +Linux kernel release 4.x +============================================= + +These are the release notes for Linux version 4. Read them carefully, +as they tell you what this is all about, explain how to install the +kernel, and what to do if something goes wrong. + +What is Linux? +-------------- + + Linux is a clone of the operating system Unix, written from scratch by + Linus Torvalds with assistance from a loosely-knit team of hackers across + the Net. It aims towards POSIX and Single UNIX Specification compliance. + + It has all the features you would expect in a modern fully-fledged Unix, + including true multitasking, virtual memory, shared libraries, demand + loading, shared copy-on-write executables, proper memory management, + and multistack networking including IPv4 and IPv6. + + It is distributed under the GNU General Public License - see the + accompanying COPYING file for more details. + +On what hardware does it run? +----------------------------- + + Although originally developed first for 32-bit x86-based PCs (386 or higher), + today Linux also runs on (at least) the Compaq Alpha AXP, Sun SPARC and + UltraSPARC, Motorola 68000, PowerPC, PowerPC64, ARM, Hitachi SuperH, Cell, + IBM S/390, MIPS, HP PA-RISC, Intel IA-64, DEC VAX, AMD x86-64, AXIS CRIS, + Xtensa, Tilera TILE, AVR32, ARC and Renesas M32R architectures. + + Linux is easily portable to most general-purpose 32- or 64-bit architectures + as long as they have a paged memory management unit (PMMU) and a port of the + GNU C compiler (gcc) (part of The GNU Compiler Collection, GCC). Linux has + also been ported to a number of architectures without a PMMU, although + functionality is then obviously somewhat limited. + Linux has also been ported to itself. You can now run the kernel as a + userspace application - this is called UserMode Linux (UML). + +Documentation +------------- + + - There is a lot of documentation available both in electronic form on + the Internet and in books, both Linux-specific and pertaining to + general UNIX questions. I'd recommend looking into the documentation + subdirectories on any Linux FTP site for the LDP (Linux Documentation + Project) books. This README is not meant to be documentation on the + system: there are much better sources available. + + - There are various README files in the Documentation/ subdirectory: + these typically contain kernel-specific installation notes for some + drivers for example. See Documentation/00-INDEX for a list of what + is contained in each file. Please read the Changes file, as it + contains information about the problems, which may result by upgrading + your kernel. + + - The Documentation/DocBook/ subdirectory contains several guides for + kernel developers and users. These guides can be rendered in a + number of formats: PostScript (.ps), PDF, HTML, & man-pages, among others. + After installation, ``make psdocs``, ``make pdfdocs``, ``make htmldocs``, + or ``make mandocs`` will render the documentation in the requested format. + +Installing the kernel source +---------------------------- + + - If you install the full sources, put the kernel tarball in a + directory where you have permissions (e.g. your home directory) and + unpack it:: + + xz -cd linux-4.X.tar.xz | tar xvf - + + Replace "X" with the version number of the latest kernel. + + Do NOT use the /usr/src/linux area! This area has a (usually + incomplete) set of kernel headers that are used by the library header + files. They should match the library, and not get messed up by + whatever the kernel-du-jour happens to be. + + - You can also upgrade between 4.x releases by patching. Patches are + distributed in the xz format. To install by patching, get all the + newer patch files, enter the top level directory of the kernel source + (linux-4.X) and execute:: + + xz -cd ../patch-4.x.xz | patch -p1 + + Replace "x" for all versions bigger than the version "X" of your current + source tree, **in_order**, and you should be ok. You may want to remove + the backup files (some-file-name~ or some-file-name.orig), and make sure + that there are no failed patches (some-file-name# or some-file-name.rej). + If there are, either you or I have made a mistake. + + Unlike patches for the 4.x kernels, patches for the 4.x.y kernels + (also known as the -stable kernels) are not incremental but instead apply + directly to the base 4.x kernel. For example, if your base kernel is 4.0 + and you want to apply the 4.0.3 patch, you must not first apply the 4.0.1 + and 4.0.2 patches. Similarly, if you are running kernel version 4.0.2 and + want to jump to 4.0.3, you must first reverse the 4.0.2 patch (that is, + patch -R) **before** applying the 4.0.3 patch. You can read more on this in + :ref:`Documentation/applying-patches.txt `. + + Alternatively, the script patch-kernel can be used to automate this + process. It determines the current kernel version and applies any + patches found:: + + linux/scripts/patch-kernel linux + + The first argument in the command above is the location of the + kernel source. Patches are applied from the current directory, but + an alternative directory can be specified as the second argument. + + - Make sure you have no stale .o files and dependencies lying around:: + + cd linux + make mrproper + + You should now have the sources correctly installed. + +Software requirements +--------------------- + + Compiling and running the 4.x kernels requires up-to-date + versions of various software packages. Consult + :ref:`Documentation/Changes ` for the minimum version numbers + required and how to get updates for these packages. Beware that using + excessively old versions of these packages can cause indirect + errors that are very difficult to track down, so don't assume that + you can just update packages when obvious problems arise during + build or operation. + +Build directory for the kernel +------------------------------ + + When compiling the kernel, all output files will per default be + stored together with the kernel source code. + Using the option ``make O=output/dir`` allows you to specify an alternate + place for the output files (including .config). + Example:: + + kernel source code: /usr/src/linux-4.X + build directory: /home/name/build/kernel + + To configure and build the kernel, use:: + + cd /usr/src/linux-4.X + make O=/home/name/build/kernel menuconfig + make O=/home/name/build/kernel + sudo make O=/home/name/build/kernel modules_install install + + Please note: If the ``O=output/dir`` option is used, then it must be + used for all invocations of make. + +Configuring the kernel +---------------------- + + Do not skip this step even if you are only upgrading one minor + version. New configuration options are added in each release, and + odd problems will turn up if the configuration files are not set up + as expected. If you want to carry your existing configuration to a + new version with minimal work, use ``make oldconfig``, which will + only ask you for the answers to new questions. + + - Alternative configuration commands are:: + + "make config" Plain text interface. + + "make menuconfig" Text based color menus, radiolists & dialogs. + + "make nconfig" Enhanced text based color menus. + + "make xconfig" Qt based configuration tool. + + "make gconfig" GTK+ based configuration tool. + + "make oldconfig" Default all questions based on the contents of + your existing ./.config file and asking about + new config symbols. + + "make silentoldconfig" + Like above, but avoids cluttering the screen + with questions already answered. + Additionally updates the dependencies. + + "make olddefconfig" + Like above, but sets new symbols to their default + values without prompting. + + "make defconfig" Create a ./.config file by using the default + symbol values from either arch/$ARCH/defconfig + or arch/$ARCH/configs/${PLATFORM}_defconfig, + depending on the architecture. + + "make ${PLATFORM}_defconfig" + Create a ./.config file by using the default + symbol values from + arch/$ARCH/configs/${PLATFORM}_defconfig. + Use "make help" to get a list of all available + platforms of your architecture. + + "make allyesconfig" + Create a ./.config file by setting symbol + values to 'y' as much as possible. + + "make allmodconfig" + Create a ./.config file by setting symbol + values to 'm' as much as possible. + + "make allnoconfig" Create a ./.config file by setting symbol + values to 'n' as much as possible. + + "make randconfig" Create a ./.config file by setting symbol + values to random values. + + "make localmodconfig" Create a config based on current config and + loaded modules (lsmod). Disables any module + option that is not needed for the loaded modules. + + To create a localmodconfig for another machine, + store the lsmod of that machine into a file + and pass it in as a LSMOD parameter. + + target$ lsmod > /tmp/mylsmod + target$ scp /tmp/mylsmod host:/tmp + + host$ make LSMOD=/tmp/mylsmod localmodconfig + + The above also works when cross compiling. + + "make localyesconfig" Similar to localmodconfig, except it will convert + all module options to built in (=y) options. + + You can find more information on using the Linux kernel config tools + in Documentation/kbuild/kconfig.txt. + + - NOTES on ``make config``: + + - Having unnecessary drivers will make the kernel bigger, and can + under some circumstances lead to problems: probing for a + nonexistent controller card may confuse your other controllers + + - A kernel with math-emulation compiled in will still use the + coprocessor if one is present: the math emulation will just + never get used in that case. The kernel will be slightly larger, + but will work on different machines regardless of whether they + have a math coprocessor or not. + + - The "kernel hacking" configuration details usually result in a + bigger or slower kernel (or both), and can even make the kernel + less stable by configuring some routines to actively try to + break bad code to find kernel problems (kmalloc()). Thus you + should probably answer 'n' to the questions for "development", + "experimental", or "debugging" features. + +Compiling the kernel +-------------------- + + - Make sure you have at least gcc 3.2 available. + For more information, refer to :ref:`Documentation/Changes `. + + Please note that you can still run a.out user programs with this kernel. + + - Do a ``make`` to create a compressed kernel image. It is also + possible to do ``make install`` if you have lilo installed to suit the + kernel makefiles, but you may want to check your particular lilo setup first. + + To do the actual install, you have to be root, but none of the normal + build should require that. Don't take the name of root in vain. + + - If you configured any of the parts of the kernel as ``modules``, you + will also have to do ``make modules_install``. + + - Verbose kernel compile/build output: + + Normally, the kernel build system runs in a fairly quiet mode (but not + totally silent). However, sometimes you or other kernel developers need + to see compile, link, or other commands exactly as they are executed. + For this, use "verbose" build mode. This is done by passing + ``V=1`` to the ``make`` command, e.g.:: + + make V=1 all + + To have the build system also tell the reason for the rebuild of each + target, use ``V=2``. The default is ``V=0``. + + - Keep a backup kernel handy in case something goes wrong. This is + especially true for the development releases, since each new release + contains new code which has not been debugged. Make sure you keep a + backup of the modules corresponding to that kernel, as well. If you + are installing a new kernel with the same version number as your + working kernel, make a backup of your modules directory before you + do a ``make modules_install``. + + Alternatively, before compiling, use the kernel config option + "LOCALVERSION" to append a unique suffix to the regular kernel version. + LOCALVERSION can be set in the "General Setup" menu. + + - In order to boot your new kernel, you'll need to copy the kernel + image (e.g. .../linux/arch/x86/boot/bzImage after compilation) + to the place where your regular bootable kernel is found. + + - Booting a kernel directly from a floppy without the assistance of a + bootloader such as LILO, is no longer supported. + + If you boot Linux from the hard drive, chances are you use LILO, which + uses the kernel image as specified in the file /etc/lilo.conf. The + kernel image file is usually /vmlinuz, /boot/vmlinuz, /bzImage or + /boot/bzImage. To use the new kernel, save a copy of the old image + and copy the new image over the old one. Then, you MUST RERUN LILO + to update the loading map! If you don't, you won't be able to boot + the new kernel image. + + Reinstalling LILO is usually a matter of running /sbin/lilo. + You may wish to edit /etc/lilo.conf to specify an entry for your + old kernel image (say, /vmlinux.old) in case the new one does not + work. See the LILO docs for more information. + + After reinstalling LILO, you should be all set. Shutdown the system, + reboot, and enjoy! + + If you ever need to change the default root device, video mode, + ramdisk size, etc. in the kernel image, use the ``rdev`` program (or + alternatively the LILO boot options when appropriate). No need to + recompile the kernel to change these parameters. + + - Reboot with the new kernel and enjoy. + +If something goes wrong +----------------------- + + - If you have problems that seem to be due to kernel bugs, please check + the file MAINTAINERS to see if there is a particular person associated + with the part of the kernel that you are having trouble with. If there + isn't anyone listed there, then the second best thing is to mail + them to me (torvalds@linux-foundation.org), and possibly to any other + relevant mailing-list or to the newsgroup. + + - In all bug-reports, *please* tell what kernel you are talking about, + how to duplicate the problem, and what your setup is (use your common + sense). If the problem is new, tell me so, and if the problem is + old, please try to tell me when you first noticed it. + + - If the bug results in a message like:: + + unable to handle kernel paging request at address C0000010 + Oops: 0002 + EIP: 0010:XXXXXXXX + eax: xxxxxxxx ebx: xxxxxxxx ecx: xxxxxxxx edx: xxxxxxxx + esi: xxxxxxxx edi: xxxxxxxx ebp: xxxxxxxx + ds: xxxx es: xxxx fs: xxxx gs: xxxx + Pid: xx, process nr: xx + xx xx xx xx xx xx xx xx xx xx + + or similar kernel debugging information on your screen or in your + system log, please duplicate it *exactly*. The dump may look + incomprehensible to you, but it does contain information that may + help debugging the problem. The text above the dump is also + important: it tells something about why the kernel dumped code (in + the above example, it's due to a bad kernel pointer). More information + on making sense of the dump is in Documentation/oops-tracing.txt + + - If you compiled the kernel with CONFIG_KALLSYMS you can send the dump + as is, otherwise you will have to use the ``ksymoops`` program to make + sense of the dump (but compiling with CONFIG_KALLSYMS is usually preferred). + This utility can be downloaded from + ftp://ftp..kernel.org/pub/linux/utils/kernel/ksymoops/ . + Alternatively, you can do the dump lookup by hand: + + - In debugging dumps like the above, it helps enormously if you can + look up what the EIP value means. The hex value as such doesn't help + me or anybody else very much: it will depend on your particular + kernel setup. What you should do is take the hex value from the EIP + line (ignore the ``0010:``), and look it up in the kernel namelist to + see which kernel function contains the offending address. + + To find out the kernel function name, you'll need to find the system + binary associated with the kernel that exhibited the symptom. This is + the file 'linux/vmlinux'. To extract the namelist and match it against + the EIP from the kernel crash, do:: + + nm vmlinux | sort | less + + This will give you a list of kernel addresses sorted in ascending + order, from which it is simple to find the function that contains the + offending address. Note that the address given by the kernel + debugging messages will not necessarily match exactly with the + function addresses (in fact, that is very unlikely), so you can't + just 'grep' the list: the list will, however, give you the starting + point of each kernel function, so by looking for the function that + has a starting address lower than the one you are searching for but + is followed by a function with a higher address you will find the one + you want. In fact, it may be a good idea to include a bit of + "context" in your problem report, giving a few lines around the + interesting one. + + If you for some reason cannot do the above (you have a pre-compiled + kernel image or similar), telling me as much about your setup as + possible will help. Please read the :ref:`REPORTING-BUGS ` + document for details. + + - Alternatively, you can use gdb on a running kernel. (read-only; i.e. you + cannot change values or set break points.) To do this, first compile the + kernel with -g; edit arch/x86/Makefile appropriately, then do a ``make + clean``. You'll also need to enable CONFIG_PROC_FS (via ``make config``). + + After you've rebooted with the new kernel, do ``gdb vmlinux /proc/kcore``. + You can now use all the usual gdb commands. The command to look up the + point where your system crashed is ``l *0xXXXXXXXX``. (Replace the XXXes + with the EIP value.) + + gdb'ing a non-running kernel currently fails because ``gdb`` (wrongly) + disregards the starting offset for which the kernel is compiled. diff --git a/Documentation/admin-guide/bad-memory.rst b/Documentation/admin-guide/bad-memory.rst new file mode 100644 index 000000000000..017fc86430c3 --- /dev/null +++ b/Documentation/admin-guide/bad-memory.rst @@ -0,0 +1,50 @@ +How to deal with bad memory e.g. reported by memtest86+ ? +========================================================= + +March 2008 +Jan-Simon Moeller, dl9pf@gmx.de + + + +There are three possibilities I know of: + +1) Reinsert/swap the memory modules + +2) Buy new modules (best!) or try to exchange the memory + if you have spare-parts + +3) Use BadRAM or memmap + +This Howto is about number 3) . + + +BadRAM +###### + +BadRAM is the actively developed and available as kernel-patch +here: http://rick.vanrein.org/linux/badram/ + +For more details see the BadRAM documentation. + +memmap +###### + +memmap is already in the kernel and usable as kernel-parameter at +boot-time. Its syntax is slightly strange and you may need to +calculate the values by yourself! + +Syntax to exclude a memory area (see kernel-parameters.txt for details):: + + memmap=$
+ +Example: memtest86+ reported here errors at address 0x18691458, 0x18698424 and +some others. All had 0x1869xxxx in common, so I chose a pattern of +0x18690000,0xffff0000. + +With the numbers of the example above:: + + memmap=64K$0x18690000 + +or:: + + memmap=0x10000$0x18690000 diff --git a/Documentation/admin-guide/basic-profiling.rst b/Documentation/admin-guide/basic-profiling.rst new file mode 100644 index 000000000000..72babc71b771 --- /dev/null +++ b/Documentation/admin-guide/basic-profiling.rst @@ -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. + +```` is the thing you're trying to measure. +Make sure you have the correct ``System.map`` / ``vmlinux`` referenced! + +It is probably easiest to use ``make install`` for linux and hack +``/sbin/installkernel`` to copy ``vmlinux`` to ``/boot``, in addition to +``vmlinuz``, ``config``, ``System.map``, which are usually installed by default. + +Readprofile +----------- + +A recent ``readprofile`` command is needed for 2.6, such as found in util-linux +2.12a, which can be downloaded from: + + http://www.kernel.org/pub/linux/utils/util-linux/ + +Most distributions will ship it already. + +Add ``profile=2`` to the kernel command line. + +Some ``readprofile`` commands:: + + clear readprofile -r + + dump output readprofile -m /boot/System.map > captured_profile + +Oprofile +-------- + +Get the source (see Changes for required version) from +http://oprofile.sourceforge.net/ and add ``idle=poll`` to the kernel command +line. + +Configure with ``CONFIG_PROFILING=y`` and ``CONFIG_OPROFILE=y`` & reboot on new kernel:: + + ./configure --with-kernel-support + make install + +For superior results, be sure to enable the local APIC. If opreport sees +a 0Hz CPU, APIC was not on. Be aware that idle=poll may mean a performance +penalty. + +One time setup:: + + opcontrol --setup --vmlinux=/boot/vmlinux + +Some ``opcontrol`` commands:: + + clear opcontrol --reset + start opcontrol --start + + stop opcontrol --stop + dump output opreport > output_file + +To only report on the kernel, run ``opreport -l /boot/vmlinux > output_file`` + +A reset is needed to clear old statistics, which survive a reboot. diff --git a/Documentation/admin-guide/binfmt-misc.rst b/Documentation/admin-guide/binfmt-misc.rst new file mode 100644 index 000000000000..9c5ff8f260bf --- /dev/null +++ b/Documentation/admin-guide/binfmt-misc.rst @@ -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/java.txt + + +You can enable/disable binfmt_misc or one binary type by echoing 0 (to disable) +or 1 (to enable) to ``/proc/sys/fs/binfmt_misc/status`` or +``/proc/.../the_name``. +Catting the file tells you the current status of ``binfmt_misc/the_entry``. + +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/java.txt for an +example. + +Your interpreter should NOT look in the PATH for the filename; the kernel +passes it the full filename (or the file descriptor) to use. Using ``$PATH`` can +cause unexpected behaviour and can be a security hazard. + + +Richard Günther diff --git a/Documentation/admin-guide/braille-console.rst b/Documentation/admin-guide/braille-console.rst new file mode 100644 index 000000000000..fa3702dc04ab --- /dev/null +++ b/Documentation/admin-guide/braille-console.rst @@ -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/serial-console.txt `), 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/serial-console.txt `. + +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/serial-console.txt `. + +For now, only the VisioBraille device is supported. + +Samuel Thibault diff --git a/Documentation/admin-guide/bug-hunting.rst b/Documentation/admin-guide/bug-hunting.rst new file mode 100644 index 000000000000..a8ef794aadae --- /dev/null +++ b/Documentation/admin-guide/bug-hunting.rst @@ -0,0 +1,248 @@ +Bug hunting ++++++++++++ + +Last updated: 20 December 2005 + +Introduction +============ + +Always try the latest kernel from kernel.org and build from source. If you are +not confident in doing that please report the bug to your distribution vendor +instead of to a kernel developer. + +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 +:ref:`Documentation/REPORTING-BUGS `. + +Devices not appearing +===================== + +Often this is caused by udev. Check that first before blaming it on the +kernel. + +Finding patch that caused a bug +=============================== + + + +Finding using ``git-bisect`` +---------------------------- + +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`` +- have fun + +Finding it the old way +---------------------- + +[Sat Mar 2 10:32:33 PST 1996 KERNEL_BUG-HOWTO lm@sgi.com (Larry McVoy)] + +This is how to track down a bug if you know nothing about kernel hacking. +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 + 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 + 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 + can probably do better than this but it gets tricky. + + - 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 + up with a list of directories that changed. For each of those + directories: + + 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:: + + mv dir dir.62 + mv dir.63 dir + find dir -name '*.[oa]' -print | xargs rm -f + + And then rebuild and retest. Assuming that all related + changes were contained in the sub directory, this should + isolate the change to a directory. + + Problems: changes in header files may have occurred; I've + 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 + + - 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 + + - You can take the old file and the new file and manually create + a merged file that has:: + + #ifdef VER62 + routine() + { + ... + } + #else + routine() + { + ... + } + #endif + + And then walk through that file, one routine at a time and + prefix it with:: + + #define VER62 + /* both routines here */ + #undef VER62 + + Then recompile, retest, move the ifdefs until you find the one + that makes the difference. + +Finally, you take all the info that you have, kernel revisions, bug +description, the extent to which you have narrowed it down, and pass +that off to whomever you believe is the maintainer of that section. +A post to linux.dev.kernel isn't such a bad idea if you've done some +work to narrow it down. + +If you get it down to a routine, you'll probably get a fix in 24 hours. + +My apologies to Linus and the other kernel hackers for describing this +brute force approach, it's hardly what a kernel hacker would do. However, +it does work and it lets non-hackers help fix bugs. And it is cool +because Linux snapshots will let you do this - something that you can't +do with vendor supplied releases. + +Fixing the bug +============== + +Nobody is going to tell you how to fix bugs. Seriously. You need to work it +out. But below are some hints on how to use the tools. + +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:: + + objdump -r -S -l --disassemble net/dccp/ipv4.o + +.. 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:: + + 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:: + + EIP: 0060:[] Not tainted VLI + +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:: + + EIP is at vt_ioctl+0xda8/0x1482 + +And recompile the kernel with ``CONFIG_DEBUG_INFO`` enabled:: + + make vmlinux + gdb vmlinux + (gdb) p vt_ioctl + (gdb) l *(0x
+ 0xda8) + +or, as one command:: + + (gdb) l *(vt_ioctl + 0xda8) + +If you have a call trace, such as:: + + Call Trace: + [] :jbd:log_wait_commit+0xa3/0xf5 + [] autoremove_wake_function+0x0/0x2e + [] :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:: + + gdb fs/jbd/jbd.ko + (gdb) p log_wait_commit + (gdb) l *(0x
+ 0xa3) + +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. + +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 :ref:`Documentation/SubmittingPatches ` +though to help your code get accepted. diff --git a/Documentation/admin-guide/conf.py b/Documentation/admin-guide/conf.py new file mode 100644 index 000000000000..86f738953799 --- /dev/null +++ b/Documentation/admin-guide/conf.py @@ -0,0 +1,10 @@ +# -*- coding: utf-8; mode: python -*- + +project = 'Linux Kernel User Documentation' + +tags.add("subproject") + +latex_documents = [ + ('index', 'linux-user.tex', 'Linux Kernel User Documentation', + 'The kernel development community', 'manual'), +] diff --git a/Documentation/admin-guide/devices.rst b/Documentation/admin-guide/devices.rst new file mode 100644 index 000000000000..b29555041531 --- /dev/null +++ b/Documentation/admin-guide/devices.rst @@ -0,0 +1,3350 @@ + +Linux allocated devices (4.x+ version) +====================================== + +This list is the Linux Device List, the official registry of allocated +device numbers and ``/dev`` directory nodes for the Linux operating +system. + +The LaTeX version of this document is no longer maintained, nor is +the document that used to reside at lanana.org. This version in the +mainline Linux kernel is the master document. Updates shall be sent +as patches to the kernel maintainers (see the +:ref:`Documentation/SubmittingPatches ` document). +Specifically explore the sections titled "CHAR and MISC DRIVERS", and +"BLOCK LAYER" in the MAINTAINERS file to find the right maintainers +to involve for character and block devices. + +This document is included by reference into the Filesystem Hierarchy +Standard (FHS). The FHS is available from http://www.pathname.com/fhs/. + +Allocations marked (68k/Amiga) apply to Linux/68k on the Amiga +platform only. Allocations marked (68k/Atari) apply to Linux/68k on +the Atari platform only. + +This document is in the public domain. The authors requests, however, +that semantically altered versions are not distributed without +permission of the authors, assuming the authors can be contacted without +an unreasonable effort. + + +.. attention:: + + DEVICE DRIVERS AUTHORS PLEASE READ THIS + + Linux now has extensive support for dynamic allocation of device numbering + and can use ``sysfs`` and ``udev`` (``systemd``) to handle the naming needs. + There are still some exceptions in the serial and boot device area. Before + asking for a device number make sure you actually need one. + + To have a major number allocated, or a minor number in situations + where that applies (e.g. busmice), please submit a patch and send to + the authors as indicated above. + + Keep the description of the device *in the same format + as this list*. The reason for this is that it is the only way we have + found to ensure we have all the requisite information to publish your + device and avoid conflicts. + + Finally, sometimes we have to play "namespace police." Please don't be + offended. We often get submissions for ``/dev`` names that would be bound + to cause conflicts down the road. We are trying to avoid getting in a + situation where we would have to suffer an incompatible forward + change. Therefore, please consult with us **before** you make your + device names and numbers in any way public, at least to the point + where it would be at all difficult to get them changed. + + Your cooperation is appreciated. + +:: + + 0 Unnamed devices (e.g. non-device mounts) + 0 = reserved as null device number + See block major 144, 145, 146 for expansion areas. + + 1 char Memory devices + 1 = /dev/mem Physical memory access + 2 = /dev/kmem Kernel virtual memory access + 3 = /dev/null Null device + 4 = /dev/port I/O port access + 5 = /dev/zero Null byte source + 6 = /dev/core OBSOLETE - replaced by /proc/kcore + 7 = /dev/full Returns ENOSPC on write + 8 = /dev/random Nondeterministic random number gen. + 9 = /dev/urandom Faster, less secure random number gen. + 10 = /dev/aio Asynchronous I/O notification interface + 11 = /dev/kmsg Writes to this come out as printk's, reads + export the buffered printk records. + 12 = /dev/oldmem OBSOLETE - replaced by /proc/vmcore + + 1 block RAM disk + 0 = /dev/ram0 First RAM disk + 1 = /dev/ram1 Second RAM disk + ... + 250 = /dev/initrd Initial RAM disk + + Older kernels had /dev/ramdisk (1, 1) here. + /dev/initrd refers to a RAM disk which was preloaded + by the boot loader; newer kernels use /dev/ram0 for + the initrd. + + 2 char Pseudo-TTY masters + 0 = /dev/ptyp0 First PTY master + 1 = /dev/ptyp1 Second PTY master + ... + 255 = /dev/ptyef 256th PTY master + + Pseudo-tty's are named as follows: + * Masters are "pty", slaves are "tty"; + * the fourth letter is one of pqrstuvwxyzabcde indicating + the 1st through 16th series of 16 pseudo-ttys each, and + * the fifth letter is one of 0123456789abcdef indicating + the position within the series. + + These are the old-style (BSD) PTY devices; Unix98 + devices are on major 128 and above and use the PTY + master multiplex (/dev/ptmx) to acquire a PTY on + demand. + + 2 block Floppy disks + 0 = /dev/fd0 Controller 0, drive 0, autodetect + 1 = /dev/fd1 Controller 0, drive 1, autodetect + 2 = /dev/fd2 Controller 0, drive 2, autodetect + 3 = /dev/fd3 Controller 0, drive 3, autodetect + 128 = /dev/fd4 Controller 1, drive 0, autodetect + 129 = /dev/fd5 Controller 1, drive 1, autodetect + 130 = /dev/fd6 Controller 1, drive 2, autodetect + 131 = /dev/fd7 Controller 1, drive 3, autodetect + + To specify format, add to the autodetect device number: + 0 = /dev/fd? Autodetect format + 4 = /dev/fd?d360 5.25" 360K in a 360K drive(1) + 20 = /dev/fd?h360 5.25" 360K in a 1200K drive(1) + 48 = /dev/fd?h410 5.25" 410K in a 1200K drive + 64 = /dev/fd?h420 5.25" 420K in a 1200K drive + 24 = /dev/fd?h720 5.25" 720K in a 1200K drive + 80 = /dev/fd?h880 5.25" 880K in a 1200K drive(1) + 8 = /dev/fd?h1200 5.25" 1200K in a 1200K drive(1) + 40 = /dev/fd?h1440 5.25" 1440K in a 1200K drive(1) + 56 = /dev/fd?h1476 5.25" 1476K in a 1200K drive + 72 = /dev/fd?h1494 5.25" 1494K in a 1200K drive + 92 = /dev/fd?h1600 5.25" 1600K in a 1200K drive(1) + + 12 = /dev/fd?u360 3.5" 360K Double Density(2) + 16 = /dev/fd?u720 3.5" 720K Double Density(1) + 120 = /dev/fd?u800 3.5" 800K Double Density(2) + 52 = /dev/fd?u820 3.5" 820K Double Density + 68 = /dev/fd?u830 3.5" 830K Double Density + 84 = /dev/fd?u1040 3.5" 1040K Double Density(1) + 88 = /dev/fd?u1120 3.5" 1120K Double Density(1) + 28 = /dev/fd?u1440 3.5" 1440K High Density(1) + 124 = /dev/fd?u1600 3.5" 1600K High Density(1) + 44 = /dev/fd?u1680 3.5" 1680K High Density(3) + 60 = /dev/fd?u1722 3.5" 1722K High Density + 76 = /dev/fd?u1743 3.5" 1743K High Density + 96 = /dev/fd?u1760 3.5" 1760K High Density + 116 = /dev/fd?u1840 3.5" 1840K High Density(3) + 100 = /dev/fd?u1920 3.5" 1920K High Density(1) + 32 = /dev/fd?u2880 3.5" 2880K Extra Density(1) + 104 = /dev/fd?u3200 3.5" 3200K Extra Density + 108 = /dev/fd?u3520 3.5" 3520K Extra Density + 112 = /dev/fd?u3840 3.5" 3840K Extra Density(1) + + 36 = /dev/fd?CompaQ Compaq 2880K drive; obsolete? + + (1) Autodetectable format + (2) Autodetectable format in a Double Density (720K) drive only + (3) Autodetectable format in a High Density (1440K) drive only + + NOTE: The letter in the device name (d, q, h or u) + signifies the type of drive: 5.25" Double Density (d), + 5.25" Quad Density (q), 5.25" High Density (h) or 3.5" + (any model, u). The use of the capital letters D, H + and E for the 3.5" models have been deprecated, since + the drive type is insignificant for these devices. + + 3 char Pseudo-TTY slaves + 0 = /dev/ttyp0 First PTY slave + 1 = /dev/ttyp1 Second PTY slave + ... + 255 = /dev/ttyef 256th PTY slave + + These are the old-style (BSD) PTY devices; Unix98 + devices are on major 136 and above. + + 3 block First MFM, RLL and IDE hard disk/CD-ROM interface + 0 = /dev/hda Master: whole disk (or CD-ROM) + 64 = /dev/hdb Slave: whole disk (or CD-ROM) + + For partitions, add to the whole disk device number: + 0 = /dev/hd? Whole disk + 1 = /dev/hd?1 First partition + 2 = /dev/hd?2 Second partition + ... + 63 = /dev/hd?63 63rd partition + + For Linux/i386, partitions 1-4 are the primary + partitions, and 5 and above are logical partitions. + Other versions of Linux use partitioning schemes + appropriate to their respective architectures. + + 4 char TTY devices + 0 = /dev/tty0 Current virtual console + + 1 = /dev/tty1 First virtual console + ... + 63 = /dev/tty63 63rd virtual console + 64 = /dev/ttyS0 First UART serial port + ... + 255 = /dev/ttyS191 192nd UART serial port + + UART serial ports refer to 8250/16450/16550 series devices. + + Older versions of the Linux kernel used this major + number for BSD PTY devices. As of Linux 2.1.115, this + is no longer supported. Use major numbers 2 and 3. + + 4 block Aliases for dynamically allocated major devices to be used + when its not possible to create the real device nodes + because the root filesystem is mounted read-only. + + 0 = /dev/root + + 5 char Alternate TTY devices + 0 = /dev/tty Current TTY device + 1 = /dev/console System console + 2 = /dev/ptmx PTY master multiplex + 3 = /dev/ttyprintk User messages via printk TTY device + 64 = /dev/cua0 Callout device for ttyS0 + ... + 255 = /dev/cua191 Callout device for ttyS191 + + (5,1) is /dev/console starting with Linux 2.1.71. See + the section on terminal devices for more information + on /dev/console. + + 6 char Parallel printer devices + 0 = /dev/lp0 Parallel printer on parport0 + 1 = /dev/lp1 Parallel printer on parport1 + ... + + Current Linux kernels no longer have a fixed mapping + between parallel ports and I/O addresses. Instead, + they are redirected through the parport multiplex layer. + + 7 char Virtual console capture devices + 0 = /dev/vcs Current vc text contents + 1 = /dev/vcs1 tty1 text contents + ... + 63 = /dev/vcs63 tty63 text contents + 128 = /dev/vcsa Current vc text/attribute contents + 129 = /dev/vcsa1 tty1 text/attribute contents + ... + 191 = /dev/vcsa63 tty63 text/attribute contents + + NOTE: These devices permit both read and write access. + + 7 block Loopback devices + 0 = /dev/loop0 First loop device + 1 = /dev/loop1 Second loop device + ... + + The loop devices are used to mount filesystems not + associated with block devices. The binding to the + loop devices is handled by mount(8) or losetup(8). + + 8 block SCSI disk devices (0-15) + 0 = /dev/sda First SCSI disk whole disk + 16 = /dev/sdb Second SCSI disk whole disk + 32 = /dev/sdc Third SCSI disk whole disk + ... + 240 = /dev/sdp Sixteenth SCSI disk whole disk + + Partitions are handled in the same way as for IDE + disks (see major number 3) except that the limit on + partitions is 15. + + 9 char SCSI tape devices + 0 = /dev/st0 First SCSI tape, mode 0 + 1 = /dev/st1 Second SCSI tape, mode 0 + ... + 32 = /dev/st0l First SCSI tape, mode 1 + 33 = /dev/st1l Second SCSI tape, mode 1 + ... + 64 = /dev/st0m First SCSI tape, mode 2 + 65 = /dev/st1m Second SCSI tape, mode 2 + ... + 96 = /dev/st0a First SCSI tape, mode 3 + 97 = /dev/st1a Second SCSI tape, mode 3 + ... + 128 = /dev/nst0 First SCSI tape, mode 0, no rewind + 129 = /dev/nst1 Second SCSI tape, mode 0, no rewind + ... + 160 = /dev/nst0l First SCSI tape, mode 1, no rewind + 161 = /dev/nst1l Second SCSI tape, mode 1, no rewind + ... + 192 = /dev/nst0m First SCSI tape, mode 2, no rewind + 193 = /dev/nst1m Second SCSI tape, mode 2, no rewind + ... + 224 = /dev/nst0a First SCSI tape, mode 3, no rewind + 225 = /dev/nst1a Second SCSI tape, mode 3, no rewind + ... + + "No rewind" refers to the omission of the default + automatic rewind on device close. The MTREW or MTOFFL + ioctl()'s can be used to rewind the tape regardless of + the device used to access it. + + 9 block Metadisk (RAID) devices + 0 = /dev/md0 First metadisk group + 1 = /dev/md1 Second metadisk group + ... + + The metadisk driver is used to span a + filesystem across multiple physical disks. + + 10 char Non-serial mice, misc features + 0 = /dev/logibm Logitech bus mouse + 1 = /dev/psaux PS/2-style mouse port + 2 = /dev/inportbm Microsoft Inport bus mouse + 3 = /dev/atibm ATI XL bus mouse + 4 = /dev/jbm J-mouse + 4 = /dev/amigamouse Amiga mouse (68k/Amiga) + 5 = /dev/atarimouse Atari mouse + 6 = /dev/sunmouse Sun mouse + 7 = /dev/amigamouse1 Second Amiga mouse + 8 = /dev/smouse Simple serial mouse driver + 9 = /dev/pc110pad IBM PC-110 digitizer pad + 10 = /dev/adbmouse Apple Desktop Bus mouse + 11 = /dev/vrtpanel Vr41xx embedded touch panel + 13 = /dev/vpcmouse Connectix Virtual PC Mouse + 14 = /dev/touchscreen/ucb1x00 UCB 1x00 touchscreen + 15 = /dev/touchscreen/mk712 MK712 touchscreen + 128 = /dev/beep Fancy beep device + 129 = + 130 = /dev/watchdog Watchdog timer port + 131 = /dev/temperature Machine internal temperature + 132 = /dev/hwtrap Hardware fault trap + 133 = /dev/exttrp External device trap + 134 = /dev/apm_bios Advanced Power Management BIOS + 135 = /dev/rtc Real Time Clock + 137 = /dev/vhci Bluetooth virtual HCI driver + 139 = /dev/openprom SPARC OpenBoot PROM + 140 = /dev/relay8 Berkshire Products Octal relay card + 141 = /dev/relay16 Berkshire Products ISO-16 relay card + 142 = + 143 = /dev/pciconf PCI configuration space + 144 = /dev/nvram Non-volatile configuration RAM + 145 = /dev/hfmodem Soundcard shortwave modem control + 146 = /dev/graphics Linux/SGI graphics device + 147 = /dev/opengl Linux/SGI OpenGL pipe + 148 = /dev/gfx Linux/SGI graphics effects device + 149 = /dev/input/mouse Linux/SGI Irix emulation mouse + 150 = /dev/input/keyboard Linux/SGI Irix emulation keyboard + 151 = /dev/led Front panel LEDs + 152 = /dev/kpoll Kernel Poll Driver + 153 = /dev/mergemem Memory merge device + 154 = /dev/pmu Macintosh PowerBook power manager + 155 = /dev/isictl MultiTech ISICom serial control + 156 = /dev/lcd Front panel LCD display + 157 = /dev/ac Applicom Intl Profibus card + 158 = /dev/nwbutton Netwinder external button + 159 = /dev/nwdebug Netwinder debug interface + 160 = /dev/nwflash Netwinder flash memory + 161 = /dev/userdma User-space DMA access + 162 = /dev/smbus System Management Bus + 163 = /dev/lik Logitech Internet Keyboard + 164 = /dev/ipmo Intel Intelligent Platform Management + 165 = /dev/vmmon VMware virtual machine monitor + 166 = /dev/i2o/ctl I2O configuration manager + 167 = /dev/specialix_sxctl Specialix serial control + 168 = /dev/tcldrv Technology Concepts serial control + 169 = /dev/specialix_rioctl Specialix RIO serial control + 170 = /dev/thinkpad/thinkpad IBM Thinkpad devices + 171 = /dev/srripc QNX4 API IPC manager + 172 = /dev/usemaclone Semaphore clone device + 173 = /dev/ipmikcs Intelligent Platform Management + 174 = /dev/uctrl SPARCbook 3 microcontroller + 175 = /dev/agpgart AGP Graphics Address Remapping Table + 176 = /dev/gtrsc Gorgy Timing radio clock + 177 = /dev/cbm Serial CBM bus + 178 = /dev/jsflash JavaStation OS flash SIMM + 179 = /dev/xsvc High-speed shared-mem/semaphore service + 180 = /dev/vrbuttons Vr41xx button input device + 181 = /dev/toshiba Toshiba laptop SMM support + 182 = /dev/perfctr Performance-monitoring counters + 183 = /dev/hwrng Generic random number generator + 184 = /dev/cpu/microcode CPU microcode update interface + 186 = /dev/atomicps Atomic shapshot of process state data + 187 = /dev/irnet IrNET device + 188 = /dev/smbusbios SMBus BIOS + 189 = /dev/ussp_ctl User space serial port control + 190 = /dev/crash Mission Critical Linux crash dump facility + 191 = /dev/pcl181 + 192 = /dev/nas_xbus NAS xbus LCD/buttons access + 193 = /dev/d7s SPARC 7-segment display + 194 = /dev/zkshim Zero-Knowledge network shim control + 195 = /dev/elographics/e2201 Elographics touchscreen E271-2201 + 196 = /dev/vfio/vfio VFIO userspace driver interface + 197 = /dev/pxa3xx-gcu PXA3xx graphics controller unit driver + 198 = /dev/sexec Signed executable interface + 199 = /dev/scanners/cuecat :CueCat barcode scanner + 200 = /dev/net/tun TAP/TUN network device + 201 = /dev/button/gulpb Transmeta GULP-B buttons + 202 = /dev/emd/ctl Enhanced Metadisk RAID (EMD) control + 203 = /dev/cuse Cuse (character device in user-space) + 204 = /dev/video/em8300 EM8300 DVD decoder control + 205 = /dev/video/em8300_mv EM8300 DVD decoder video + 206 = /dev/video/em8300_ma EM8300 DVD decoder audio + 207 = /dev/video/em8300_sp EM8300 DVD decoder subpicture + 208 = /dev/compaq/cpqphpc Compaq PCI Hot Plug Controller + 209 = /dev/compaq/cpqrid Compaq Remote Insight Driver + 210 = /dev/impi/bt IMPI coprocessor block transfer + 211 = /dev/impi/smic IMPI coprocessor stream interface + 212 = /dev/watchdogs/0 First watchdog device + 213 = /dev/watchdogs/1 Second watchdog device + 214 = /dev/watchdogs/2 Third watchdog device + 215 = /dev/watchdogs/3 Fourth watchdog device + 216 = /dev/fujitsu/apanel Fujitsu/Siemens application panel + 217 = /dev/ni/natmotn National Instruments Motion + 218 = /dev/kchuid Inter-process chuid control + 219 = /dev/modems/mwave MWave modem firmware upload + 220 = /dev/mptctl Message passing technology (MPT) control + 221 = /dev/mvista/hssdsi Montavista PICMG hot swap system driver + 222 = /dev/mvista/hasi Montavista PICMG high availability + 223 = /dev/input/uinput User level driver support for input + 224 = /dev/tpm TCPA TPM driver + 225 = /dev/pps Pulse Per Second driver + 226 = /dev/systrace Systrace device + 227 = /dev/mcelog X86_64 Machine Check Exception driver + 228 = /dev/hpet HPET driver + 229 = /dev/fuse Fuse (virtual filesystem in user-space) + 230 = /dev/midishare MidiShare driver + 231 = /dev/snapshot System memory snapshot device + 232 = /dev/kvm Kernel-based virtual machine (hardware virtualization extensions) + 233 = /dev/kmview View-OS A process with a view + 234 = /dev/btrfs-control Btrfs control device + 235 = /dev/autofs Autofs control device + 236 = /dev/mapper/control Device-Mapper control device + 237 = /dev/loop-control Loopback control device + 238 = /dev/vhost-net Host kernel accelerator for virtio net + 239 = /dev/uhid User-space I/O driver support for HID subsystem + + 240-254 Reserved for local use + 255 Reserved for MISC_DYNAMIC_MINOR + + 11 char Raw keyboard device (Linux/SPARC only) + 0 = /dev/kbd Raw keyboard device + + 11 char Serial Mux device (Linux/PA-RISC only) + 0 = /dev/ttyB0 First mux port + 1 = /dev/ttyB1 Second mux port + ... + + 11 block SCSI CD-ROM devices + 0 = /dev/scd0 First SCSI CD-ROM + 1 = /dev/scd1 Second SCSI CD-ROM + ... + + The prefix /dev/sr (instead of /dev/scd) has been deprecated. + + 12 char QIC-02 tape + 2 = /dev/ntpqic11 QIC-11, no rewind-on-close + 3 = /dev/tpqic11 QIC-11, rewind-on-close + 4 = /dev/ntpqic24 QIC-24, no rewind-on-close + 5 = /dev/tpqic24 QIC-24, rewind-on-close + 6 = /dev/ntpqic120 QIC-120, no rewind-on-close + 7 = /dev/tpqic120 QIC-120, rewind-on-close + 8 = /dev/ntpqic150 QIC-150, no rewind-on-close + 9 = /dev/tpqic150 QIC-150, rewind-on-close + + The device names specified are proposed -- if there + are "standard" names for these devices, please let me know. + + 12 block + + 13 char Input core + 0 = /dev/input/js0 First joystick + 1 = /dev/input/js1 Second joystick + ... + 32 = /dev/input/mouse0 First mouse + 33 = /dev/input/mouse1 Second mouse + ... + 63 = /dev/input/mice Unified mouse + 64 = /dev/input/event0 First event queue + 65 = /dev/input/event1 Second event queue + ... + + Each device type has 5 bits (32 minors). + + 13 block Previously used for the XT disk (/dev/xdN) + Deleted in kernel v3.9. + + 14 char Open Sound System (OSS) + 0 = /dev/mixer Mixer control + 1 = /dev/sequencer Audio sequencer + 2 = /dev/midi00 First MIDI port + 3 = /dev/dsp Digital audio + 4 = /dev/audio Sun-compatible digital audio + 6 = + 7 = /dev/audioctl SPARC audio control device + 8 = /dev/sequencer2 Sequencer -- alternate device + 16 = /dev/mixer1 Second soundcard mixer control + 17 = /dev/patmgr0 Sequencer patch manager + 18 = /dev/midi01 Second MIDI port + 19 = /dev/dsp1 Second soundcard digital audio + 20 = /dev/audio1 Second soundcard Sun digital audio + 33 = /dev/patmgr1 Sequencer patch manager + 34 = /dev/midi02 Third MIDI port + 50 = /dev/midi03 Fourth MIDI port + + 14 block + + 15 char Joystick + 0 = /dev/js0 First analog joystick + 1 = /dev/js1 Second analog joystick + ... + 128 = /dev/djs0 First digital joystick + 129 = /dev/djs1 Second digital joystick + ... + 15 block Sony CDU-31A/CDU-33A CD-ROM + 0 = /dev/sonycd Sony CDU-31a CD-ROM + + 16 char Non-SCSI scanners + 0 = /dev/gs4500 Genius 4500 handheld scanner + + 16 block GoldStar CD-ROM + 0 = /dev/gscd GoldStar CD-ROM + + 17 char OBSOLETE (was Chase serial card) + 0 = /dev/ttyH0 First Chase port + 1 = /dev/ttyH1 Second Chase port + ... + 17 block Optics Storage CD-ROM + 0 = /dev/optcd Optics Storage CD-ROM + + 18 char OBSOLETE (was Chase serial card - alternate devices) + 0 = /dev/cuh0 Callout device for ttyH0 + 1 = /dev/cuh1 Callout device for ttyH1 + ... + 18 block Sanyo CD-ROM + 0 = /dev/sjcd Sanyo CD-ROM + + 19 char Cyclades serial card + 0 = /dev/ttyC0 First Cyclades port + ... + 31 = /dev/ttyC31 32nd Cyclades port + + 19 block "Double" compressed disk + 0 = /dev/double0 First compressed disk + ... + 7 = /dev/double7 Eighth compressed disk + 128 = /dev/cdouble0 Mirror of first compressed disk + ... + 135 = /dev/cdouble7 Mirror of eighth compressed disk + + See the Double documentation for the meaning of the + mirror devices. + + 20 char Cyclades serial card - alternate devices + 0 = /dev/cub0 Callout device for ttyC0 + ... + 31 = /dev/cub31 Callout device for ttyC31 + + 20 block Hitachi CD-ROM (under development) + 0 = /dev/hitcd Hitachi CD-ROM + + 21 char Generic SCSI access + 0 = /dev/sg0 First generic SCSI device + 1 = /dev/sg1 Second generic SCSI device + ... + + Most distributions name these /dev/sga, /dev/sgb...; + this sets an unnecessary limit of 26 SCSI devices in + the system and is counter to standard Linux + device-naming practice. + + 21 block Acorn MFM hard drive interface + 0 = /dev/mfma First MFM drive whole disk + 64 = /dev/mfmb Second MFM drive whole disk + + This device is used on the ARM-based Acorn RiscPC. + Partitions are handled the same way as for IDE disks + (see major number 3). + + 22 char Digiboard serial card + 0 = /dev/ttyD0 First Digiboard port + 1 = /dev/ttyD1 Second Digiboard port + ... + 22 block Second IDE hard disk/CD-ROM interface + 0 = /dev/hdc Master: whole disk (or CD-ROM) + 64 = /dev/hdd Slave: whole disk (or CD-ROM) + + Partitions are handled the same way as for the first + interface (see major number 3). + + 23 char Digiboard serial card - alternate devices + 0 = /dev/cud0 Callout device for ttyD0 + 1 = /dev/cud1 Callout device for ttyD1 + ... + 23 block Mitsumi proprietary CD-ROM + 0 = /dev/mcd Mitsumi CD-ROM + + 24 char Stallion serial card + 0 = /dev/ttyE0 Stallion port 0 card 0 + 1 = /dev/ttyE1 Stallion port 1 card 0 + ... + 64 = /dev/ttyE64 Stallion port 0 card 1 + 65 = /dev/ttyE65 Stallion port 1 card 1 + ... + 128 = /dev/ttyE128 Stallion port 0 card 2 + 129 = /dev/ttyE129 Stallion port 1 card 2 + ... + 192 = /dev/ttyE192 Stallion port 0 card 3 + 193 = /dev/ttyE193 Stallion port 1 card 3 + ... + 24 block Sony CDU-535 CD-ROM + 0 = /dev/cdu535 Sony CDU-535 CD-ROM + + 25 char Stallion serial card - alternate devices + 0 = /dev/cue0 Callout device for ttyE0 + 1 = /dev/cue1 Callout device for ttyE1 + ... + 64 = /dev/cue64 Callout device for ttyE64 + 65 = /dev/cue65 Callout device for ttyE65 + ... + 128 = /dev/cue128 Callout device for ttyE128 + 129 = /dev/cue129 Callout device for ttyE129 + ... + 192 = /dev/cue192 Callout device for ttyE192 + 193 = /dev/cue193 Callout device for ttyE193 + ... + 25 block First Matsushita (Panasonic/SoundBlaster) CD-ROM + 0 = /dev/sbpcd0 Panasonic CD-ROM controller 0 unit 0 + 1 = /dev/sbpcd1 Panasonic CD-ROM controller 0 unit 1 + 2 = /dev/sbpcd2 Panasonic CD-ROM controller 0 unit 2 + 3 = /dev/sbpcd3 Panasonic CD-ROM controller 0 unit 3 + + 26 char + + 26 block Second Matsushita (Panasonic/SoundBlaster) CD-ROM + 0 = /dev/sbpcd4 Panasonic CD-ROM controller 1 unit 0 + 1 = /dev/sbpcd5 Panasonic CD-ROM controller 1 unit 1 + 2 = /dev/sbpcd6 Panasonic CD-ROM controller 1 unit 2 + 3 = /dev/sbpcd7 Panasonic CD-ROM controller 1 unit 3 + + 27 char QIC-117 tape + 0 = /dev/qft0 Unit 0, rewind-on-close + 1 = /dev/qft1 Unit 1, rewind-on-close + 2 = /dev/qft2 Unit 2, rewind-on-close + 3 = /dev/qft3 Unit 3, rewind-on-close + 4 = /dev/nqft0 Unit 0, no rewind-on-close + 5 = /dev/nqft1 Unit 1, no rewind-on-close + 6 = /dev/nqft2 Unit 2, no rewind-on-close + 7 = /dev/nqft3 Unit 3, no rewind-on-close + 16 = /dev/zqft0 Unit 0, rewind-on-close, compression + 17 = /dev/zqft1 Unit 1, rewind-on-close, compression + 18 = /dev/zqft2 Unit 2, rewind-on-close, compression + 19 = /dev/zqft3 Unit 3, rewind-on-close, compression + 20 = /dev/nzqft0 Unit 0, no rewind-on-close, compression + 21 = /dev/nzqft1 Unit 1, no rewind-on-close, compression + 22 = /dev/nzqft2 Unit 2, no rewind-on-close, compression + 23 = /dev/nzqft3 Unit 3, no rewind-on-close, compression + 32 = /dev/rawqft0 Unit 0, rewind-on-close, no file marks + 33 = /dev/rawqft1 Unit 1, rewind-on-close, no file marks + 34 = /dev/rawqft2 Unit 2, rewind-on-close, no file marks + 35 = /dev/rawqft3 Unit 3, rewind-on-close, no file marks + 36 = /dev/nrawqft0 Unit 0, no rewind-on-close, no file marks + 37 = /dev/nrawqft1 Unit 1, no rewind-on-close, no file marks + 38 = /dev/nrawqft2 Unit 2, no rewind-on-close, no file marks + 39 = /dev/nrawqft3 Unit 3, no rewind-on-close, no file marks + + 27 block Third Matsushita (Panasonic/SoundBlaster) CD-ROM + 0 = /dev/sbpcd8 Panasonic CD-ROM controller 2 unit 0 + 1 = /dev/sbpcd9 Panasonic CD-ROM controller 2 unit 1 + 2 = /dev/sbpcd10 Panasonic CD-ROM controller 2 unit 2 + 3 = /dev/sbpcd11 Panasonic CD-ROM controller 2 unit 3 + + 28 char Stallion serial card - card programming + 0 = /dev/staliomem0 First Stallion card I/O memory + 1 = /dev/staliomem1 Second Stallion card I/O memory + 2 = /dev/staliomem2 Third Stallion card I/O memory + 3 = /dev/staliomem3 Fourth Stallion card I/O memory + + 28 char Atari SLM ACSI laser printer (68k/Atari) + 0 = /dev/slm0 First SLM laser printer + 1 = /dev/slm1 Second SLM laser printer + ... + 28 block Fourth Matsushita (Panasonic/SoundBlaster) CD-ROM + 0 = /dev/sbpcd12 Panasonic CD-ROM controller 3 unit 0 + 1 = /dev/sbpcd13 Panasonic CD-ROM controller 3 unit 1 + 2 = /dev/sbpcd14 Panasonic CD-ROM controller 3 unit 2 + 3 = /dev/sbpcd15 Panasonic CD-ROM controller 3 unit 3 + + 28 block ACSI disk (68k/Atari) + 0 = /dev/ada First ACSI disk whole disk + 16 = /dev/adb Second ACSI disk whole disk + 32 = /dev/adc Third ACSI disk whole disk + ... + 240 = /dev/adp 16th ACSI disk whole disk + + Partitions are handled in the same way as for IDE + disks (see major number 3) except that the limit on + partitions is 15, like SCSI. + + 29 char Universal frame buffer + 0 = /dev/fb0 First frame buffer + 1 = /dev/fb1 Second frame buffer + ... + 31 = /dev/fb31 32nd frame buffer + + 29 block Aztech/Orchid/Okano/Wearnes CD-ROM + 0 = /dev/aztcd Aztech CD-ROM + + 30 char iBCS-2 compatibility devices + 0 = /dev/socksys Socket access + 1 = /dev/spx SVR3 local X interface + 32 = /dev/inet/ip Network access + 33 = /dev/inet/icmp + 34 = /dev/inet/ggp + 35 = /dev/inet/ipip + 36 = /dev/inet/tcp + 37 = /dev/inet/egp + 38 = /dev/inet/pup + 39 = /dev/inet/udp + 40 = /dev/inet/idp + 41 = /dev/inet/rawip + + Additionally, iBCS-2 requires the following links: + + /dev/ip -> /dev/inet/ip + /dev/icmp -> /dev/inet/icmp + /dev/ggp -> /dev/inet/ggp + /dev/ipip -> /dev/inet/ipip + /dev/tcp -> /dev/inet/tcp + /dev/egp -> /dev/inet/egp + /dev/pup -> /dev/inet/pup + /dev/udp -> /dev/inet/udp + /dev/idp -> /dev/inet/idp + /dev/rawip -> /dev/inet/rawip + /dev/inet/arp -> /dev/inet/udp + /dev/inet/rip -> /dev/inet/udp + /dev/nfsd -> /dev/socksys + /dev/X0R -> /dev/null (? apparently not required ?) + + 30 block Philips LMS CM-205 CD-ROM + 0 = /dev/cm205cd Philips LMS CM-205 CD-ROM + + /dev/lmscd is an older name for this device. This + driver does not work with the CM-205MS CD-ROM. + + 31 char MPU-401 MIDI + 0 = /dev/mpu401data MPU-401 data port + 1 = /dev/mpu401stat MPU-401 status port + + 31 block ROM/flash memory card + 0 = /dev/rom0 First ROM card (rw) + ... + 7 = /dev/rom7 Eighth ROM card (rw) + 8 = /dev/rrom0 First ROM card (ro) + ... + 15 = /dev/rrom7 Eighth ROM card (ro) + 16 = /dev/flash0 First flash memory card (rw) + ... + 23 = /dev/flash7 Eighth flash memory card (rw) + 24 = /dev/rflash0 First flash memory card (ro) + ... + 31 = /dev/rflash7 Eighth flash memory card (ro) + + The read-write (rw) devices support back-caching + written data in RAM, as well as writing to flash RAM + devices. The read-only devices (ro) support reading + only. + + 32 char Specialix serial card + 0 = /dev/ttyX0 First Specialix port + 1 = /dev/ttyX1 Second Specialix port + ... + 32 block Philips LMS CM-206 CD-ROM + 0 = /dev/cm206cd Philips LMS CM-206 CD-ROM + + 33 char Specialix serial card - alternate devices + 0 = /dev/cux0 Callout device for ttyX0 + 1 = /dev/cux1 Callout device for ttyX1 + ... + 33 block Third IDE hard disk/CD-ROM interface + 0 = /dev/hde Master: whole disk (or CD-ROM) + 64 = /dev/hdf Slave: whole disk (or CD-ROM) + + Partitions are handled the same way as for the first + interface (see major number 3). + + 34 char Z8530 HDLC driver + 0 = /dev/scc0 First Z8530, first port + 1 = /dev/scc1 First Z8530, second port + 2 = /dev/scc2 Second Z8530, first port + 3 = /dev/scc3 Second Z8530, second port + ... + + In a previous version these devices were named + /dev/sc1 for /dev/scc0, /dev/sc2 for /dev/scc1, and so + on. + + 34 block Fourth IDE hard disk/CD-ROM interface + 0 = /dev/hdg Master: whole disk (or CD-ROM) + 64 = /dev/hdh Slave: whole disk (or CD-ROM) + + Partitions are handled the same way as for the first + interface (see major number 3). + + 35 char tclmidi MIDI driver + 0 = /dev/midi0 First MIDI port, kernel timed + 1 = /dev/midi1 Second MIDI port, kernel timed + 2 = /dev/midi2 Third MIDI port, kernel timed + 3 = /dev/midi3 Fourth MIDI port, kernel timed + 64 = /dev/rmidi0 First MIDI port, untimed + 65 = /dev/rmidi1 Second MIDI port, untimed + 66 = /dev/rmidi2 Third MIDI port, untimed + 67 = /dev/rmidi3 Fourth MIDI port, untimed + 128 = /dev/smpte0 First MIDI port, SMPTE timed + 129 = /dev/smpte1 Second MIDI port, SMPTE timed + 130 = /dev/smpte2 Third MIDI port, SMPTE timed + 131 = /dev/smpte3 Fourth MIDI port, SMPTE timed + + 35 block Slow memory ramdisk + 0 = /dev/slram Slow memory ramdisk + + 36 char Netlink support + 0 = /dev/route Routing, device updates, kernel to user + 1 = /dev/skip enSKIP security cache control + 3 = /dev/fwmonitor Firewall packet copies + 16 = /dev/tap0 First Ethertap device + ... + 31 = /dev/tap15 16th Ethertap device + + 36 block OBSOLETE (was MCA ESDI hard disk) + + 37 char IDE tape + 0 = /dev/ht0 First IDE tape + 1 = /dev/ht1 Second IDE tape + ... + 128 = /dev/nht0 First IDE tape, no rewind-on-close + 129 = /dev/nht1 Second IDE tape, no rewind-on-close + ... + + Currently, only one IDE tape drive is supported. + + 37 block Zorro II ramdisk + 0 = /dev/z2ram Zorro II ramdisk + + 38 char Myricom PCI Myrinet board + 0 = /dev/mlanai0 First Myrinet board + 1 = /dev/mlanai1 Second Myrinet board + ... + + This device is used for status query, board control + and "user level packet I/O." This board is also + accessible as a standard networking "eth" device. + + 38 block OBSOLETE (was Linux/AP+) + + 39 char ML-16P experimental I/O board + 0 = /dev/ml16pa-a0 First card, first analog channel + 1 = /dev/ml16pa-a1 First card, second analog channel + ... + 15 = /dev/ml16pa-a15 First card, 16th analog channel + 16 = /dev/ml16pa-d First card, digital lines + 17 = /dev/ml16pa-c0 First card, first counter/timer + 18 = /dev/ml16pa-c1 First card, second counter/timer + 19 = /dev/ml16pa-c2 First card, third counter/timer + 32 = /dev/ml16pb-a0 Second card, first analog channel + 33 = /dev/ml16pb-a1 Second card, second analog channel + ... + 47 = /dev/ml16pb-a15 Second card, 16th analog channel + 48 = /dev/ml16pb-d Second card, digital lines + 49 = /dev/ml16pb-c0 Second card, first counter/timer + 50 = /dev/ml16pb-c1 Second card, second counter/timer + 51 = /dev/ml16pb-c2 Second card, third counter/timer + ... + 39 block + + 40 char + + 40 block + + 41 char Yet Another Micro Monitor + 0 = /dev/yamm Yet Another Micro Monitor + + 41 block + + 42 char Demo/sample use + + 42 block Demo/sample use + + This number is intended for use in sample code, as + well as a general "example" device number. It + should never be used for a device driver that is being + distributed; either obtain an official number or use + the local/experimental range. The sudden addition or + removal of a driver with this number should not cause + ill effects to the system (bugs excepted.) + + IN PARTICULAR, ANY DISTRIBUTION WHICH CONTAINS A + DEVICE DRIVER USING MAJOR NUMBER 42 IS NONCOMPLIANT. + + 43 char isdn4linux virtual modem + 0 = /dev/ttyI0 First virtual modem + ... + 63 = /dev/ttyI63 64th virtual modem + + 43 block Network block devices + 0 = /dev/nb0 First network block device + 1 = /dev/nb1 Second network block device + ... + + Network Block Device is somehow similar to loopback + devices: If you read from it, it sends packet across + network asking server for data. If you write to it, it + sends packet telling server to write. It could be used + to mounting filesystems over the net, swapping over + the net, implementing block device in userland etc. + + 44 char isdn4linux virtual modem - alternate devices + 0 = /dev/cui0 Callout device for ttyI0 + ... + 63 = /dev/cui63 Callout device for ttyI63 + + 44 block Flash Translation Layer (FTL) filesystems + 0 = /dev/ftla FTL on first Memory Technology Device + 16 = /dev/ftlb FTL on second Memory Technology Device + 32 = /dev/ftlc FTL on third Memory Technology Device + ... + 240 = /dev/ftlp FTL on 16th Memory Technology Device + + Partitions are handled in the same way as for IDE + disks (see major number 3) except that the partition + limit is 15 rather than 63 per disk (same as SCSI.) + + 45 char isdn4linux ISDN BRI driver + 0 = /dev/isdn0 First virtual B channel raw data + ... + 63 = /dev/isdn63 64th virtual B channel raw data + 64 = /dev/isdnctrl0 First channel control/debug + ... + 127 = /dev/isdnctrl63 64th channel control/debug + + 128 = /dev/ippp0 First SyncPPP device + ... + 191 = /dev/ippp63 64th SyncPPP device + + 255 = /dev/isdninfo ISDN monitor interface + + 45 block Parallel port IDE disk devices + 0 = /dev/pda First parallel port IDE disk + 16 = /dev/pdb Second parallel port IDE disk + 32 = /dev/pdc Third parallel port IDE disk + 48 = /dev/pdd Fourth parallel port IDE disk + + Partitions are handled in the same way as for IDE + disks (see major number 3) except that the partition + limit is 15 rather than 63 per disk. + + 46 char Comtrol Rocketport serial card + 0 = /dev/ttyR0 First Rocketport port + 1 = /dev/ttyR1 Second Rocketport port + ... + 46 block Parallel port ATAPI CD-ROM devices + 0 = /dev/pcd0 First parallel port ATAPI CD-ROM + 1 = /dev/pcd1 Second parallel port ATAPI CD-ROM + 2 = /dev/pcd2 Third parallel port ATAPI CD-ROM + 3 = /dev/pcd3 Fourth parallel port ATAPI CD-ROM + + 47 char Comtrol Rocketport serial card - alternate devices + 0 = /dev/cur0 Callout device for ttyR0 + 1 = /dev/cur1 Callout device for ttyR1 + ... + 47 block Parallel port ATAPI disk devices + 0 = /dev/pf0 First parallel port ATAPI disk + 1 = /dev/pf1 Second parallel port ATAPI disk + 2 = /dev/pf2 Third parallel port ATAPI disk + 3 = /dev/pf3 Fourth parallel port ATAPI disk + + This driver is intended for floppy disks and similar + devices and hence does not support partitioning. + + 48 char SDL RISCom serial card + 0 = /dev/ttyL0 First RISCom port + 1 = /dev/ttyL1 Second RISCom port + ... + 48 block Mylex DAC960 PCI RAID controller; first controller + 0 = /dev/rd/c0d0 First disk, whole disk + 8 = /dev/rd/c0d1 Second disk, whole disk + ... + 248 = /dev/rd/c0d31 32nd disk, whole disk + + For partitions add: + 0 = /dev/rd/c?d? Whole disk + 1 = /dev/rd/c?d?p1 First partition + ... + 7 = /dev/rd/c?d?p7 Seventh partition + + 49 char SDL RISCom serial card - alternate devices + 0 = /dev/cul0 Callout device for ttyL0 + 1 = /dev/cul1 Callout device for ttyL1 + ... + 49 block Mylex DAC960 PCI RAID controller; second controller + 0 = /dev/rd/c1d0 First disk, whole disk + 8 = /dev/rd/c1d1 Second disk, whole disk + ... + 248 = /dev/rd/c1d31 32nd disk, whole disk + + Partitions are handled as for major 48. + + 50 char Reserved for GLINT + + 50 block Mylex DAC960 PCI RAID controller; third controller + 0 = /dev/rd/c2d0 First disk, whole disk + 8 = /dev/rd/c2d1 Second disk, whole disk + ... + 248 = /dev/rd/c2d31 32nd disk, whole disk + + 51 char Baycom radio modem OR Radio Tech BIM-XXX-RS232 radio modem + 0 = /dev/bc0 First Baycom radio modem + 1 = /dev/bc1 Second Baycom radio modem + ... + 51 block Mylex DAC960 PCI RAID controller; fourth controller + 0 = /dev/rd/c3d0 First disk, whole disk + 8 = /dev/rd/c3d1 Second disk, whole disk + ... + 248 = /dev/rd/c3d31 32nd disk, whole disk + + Partitions are handled as for major 48. + + 52 char Spellcaster DataComm/BRI ISDN card + 0 = /dev/dcbri0 First DataComm card + 1 = /dev/dcbri1 Second DataComm card + 2 = /dev/dcbri2 Third DataComm card + 3 = /dev/dcbri3 Fourth DataComm card + + 52 block Mylex DAC960 PCI RAID controller; fifth controller + 0 = /dev/rd/c4d0 First disk, whole disk + 8 = /dev/rd/c4d1 Second disk, whole disk + ... + 248 = /dev/rd/c4d31 32nd disk, whole disk + + Partitions are handled as for major 48. + + 53 char BDM interface for remote debugging MC683xx microcontrollers + 0 = /dev/pd_bdm0 PD BDM interface on lp0 + 1 = /dev/pd_bdm1 PD BDM interface on lp1 + 2 = /dev/pd_bdm2 PD BDM interface on lp2 + 4 = /dev/icd_bdm0 ICD BDM interface on lp0 + 5 = /dev/icd_bdm1 ICD BDM interface on lp1 + 6 = /dev/icd_bdm2 ICD BDM interface on lp2 + + This device is used for the interfacing to the MC683xx + microcontrollers via Background Debug Mode by use of a + Parallel Port interface. PD is the Motorola Public + Domain Interface and ICD is the commercial interface + by P&E. + + 53 block Mylex DAC960 PCI RAID controller; sixth controller + 0 = /dev/rd/c5d0 First disk, whole disk + 8 = /dev/rd/c5d1 Second disk, whole disk + ... + 248 = /dev/rd/c5d31 32nd disk, whole disk + + Partitions are handled as for major 48. + + 54 char Electrocardiognosis Holter serial card + 0 = /dev/holter0 First Holter port + 1 = /dev/holter1 Second Holter port + 2 = /dev/holter2 Third Holter port + + A custom serial card used by Electrocardiognosis SRL + to transfer data from Holter + 24-hour heart monitoring equipment. + + 54 block Mylex DAC960 PCI RAID controller; seventh controller + 0 = /dev/rd/c6d0 First disk, whole disk + 8 = /dev/rd/c6d1 Second disk, whole disk + ... + 248 = /dev/rd/c6d31 32nd disk, whole disk + + Partitions are handled as for major 48. + + 55 char DSP56001 digital signal processor + 0 = /dev/dsp56k First DSP56001 + + 55 block Mylex DAC960 PCI RAID controller; eighth controller + 0 = /dev/rd/c7d0 First disk, whole disk + 8 = /dev/rd/c7d1 Second disk, whole disk + ... + 248 = /dev/rd/c7d31 32nd disk, whole disk + + Partitions are handled as for major 48. + + 56 char Apple Desktop Bus + 0 = /dev/adb ADB bus control + + Additional devices will be added to this number, all + starting with /dev/adb. + + 56 block Fifth IDE hard disk/CD-ROM interface + 0 = /dev/hdi Master: whole disk (or CD-ROM) + 64 = /dev/hdj Slave: whole disk (or CD-ROM) + + Partitions are handled the same way as for the first + interface (see major number 3). + + 57 char Hayes ESP serial card + 0 = /dev/ttyP0 First ESP port + 1 = /dev/ttyP1 Second ESP port + ... + + 57 block Sixth IDE hard disk/CD-ROM interface + 0 = /dev/hdk Master: whole disk (or CD-ROM) + 64 = /dev/hdl Slave: whole disk (or CD-ROM) + + Partitions are handled the same way as for the first + interface (see major number 3). + + 58 char Hayes ESP serial card - alternate devices + 0 = /dev/cup0 Callout device for ttyP0 + 1 = /dev/cup1 Callout device for ttyP1 + ... + + 58 block Reserved for logical volume manager + + 59 char sf firewall package + 0 = /dev/firewall Communication with sf kernel module + + 59 block Generic PDA filesystem device + 0 = /dev/pda0 First PDA device + 1 = /dev/pda1 Second PDA device + ... + + The pda devices are used to mount filesystems on + remote pda's (basically slow handheld machines with + proprietary OS's and limited memory and storage + running small fs translation drivers) through serial / + IRDA / parallel links. + + NAMING CONFLICT -- PROPOSED REVISED NAME /dev/rpda0 etc + + 60-63 char LOCAL/EXPERIMENTAL USE + + 60-63 block LOCAL/EXPERIMENTAL USE + Allocated for local/experimental use. For devices not + assigned official numbers, these ranges should be + used in order to avoid conflicting with future assignments. + + 64 char ENskip kernel encryption package + 0 = /dev/enskip Communication with ENskip kernel module + + 64 block Scramdisk/DriveCrypt encrypted devices + 0 = /dev/scramdisk/master Master node for ioctls + 1 = /dev/scramdisk/1 First encrypted device + 2 = /dev/scramdisk/2 Second encrypted device + ... + 255 = /dev/scramdisk/255 255th encrypted device + + The filename of the encrypted container and the passwords + are sent via ioctls (using the sdmount tool) to the master + node which then activates them via one of the + /dev/scramdisk/x nodes for loop mounting (all handled + through the sdmount tool). + + Requested by: andy@scramdisklinux.org + + 65 char Sundance "plink" Transputer boards (obsolete, unused) + 0 = /dev/plink0 First plink device + 1 = /dev/plink1 Second plink device + 2 = /dev/plink2 Third plink device + 3 = /dev/plink3 Fourth plink device + 64 = /dev/rplink0 First plink device, raw + 65 = /dev/rplink1 Second plink device, raw + 66 = /dev/rplink2 Third plink device, raw + 67 = /dev/rplink3 Fourth plink device, raw + 128 = /dev/plink0d First plink device, debug + 129 = /dev/plink1d Second plink device, debug + 130 = /dev/plink2d Third plink device, debug + 131 = /dev/plink3d Fourth plink device, debug + 192 = /dev/rplink0d First plink device, raw, debug + 193 = /dev/rplink1d Second plink device, raw, debug + 194 = /dev/rplink2d Third plink device, raw, debug + 195 = /dev/rplink3d Fourth plink device, raw, debug + + This is a commercial driver; contact James Howes + for information. + + 65 block SCSI disk devices (16-31) + 0 = /dev/sdq 17th SCSI disk whole disk + 16 = /dev/sdr 18th SCSI disk whole disk + 32 = /dev/sds 19th SCSI disk whole disk + ... + 240 = /dev/sdaf 32nd SCSI disk whole disk + + Partitions are handled in the same way as for IDE + disks (see major number 3) except that the limit on + partitions is 15. + + 66 char YARC PowerPC PCI coprocessor card + 0 = /dev/yppcpci0 First YARC card + 1 = /dev/yppcpci1 Second YARC card + ... + + 66 block SCSI disk devices (32-47) + 0 = /dev/sdag 33th SCSI disk whole disk + 16 = /dev/sdah 34th SCSI disk whole disk + 32 = /dev/sdai 35th SCSI disk whole disk + ... + 240 = /dev/sdav 48nd SCSI disk whole disk + + Partitions are handled in the same way as for IDE + disks (see major number 3) except that the limit on + partitions is 15. + + 67 char Coda network file system + 0 = /dev/cfs0 Coda cache manager + + See http://www.coda.cs.cmu.edu for information about Coda. + + 67 block SCSI disk devices (48-63) + 0 = /dev/sdaw 49th SCSI disk whole disk + 16 = /dev/sdax 50th SCSI disk whole disk + 32 = /dev/sday 51st SCSI disk whole disk + ... + 240 = /dev/sdbl 64th SCSI disk whole disk + + Partitions are handled in the same way as for IDE + disks (see major number 3) except that the limit on + partitions is 15. + + 68 char CAPI 2.0 interface + 0 = /dev/capi20 Control device + 1 = /dev/capi20.00 First CAPI 2.0 application + 2 = /dev/capi20.01 Second CAPI 2.0 application + ... + 20 = /dev/capi20.19 19th CAPI 2.0 application + + ISDN CAPI 2.0 driver for use with CAPI 2.0 + applications; currently supports the AVM B1 card. + + 68 block SCSI disk devices (64-79) + 0 = /dev/sdbm 65th SCSI disk whole disk + 16 = /dev/sdbn 66th SCSI disk whole disk + 32 = /dev/sdbo 67th SCSI disk whole disk + ... + 240 = /dev/sdcb 80th SCSI disk whole disk + + Partitions are handled in the same way as for IDE + disks (see major number 3) except that the limit on + partitions is 15. + + 69 char MA16 numeric accelerator card + 0 = /dev/ma16 Board memory access + + 69 block SCSI disk devices (80-95) + 0 = /dev/sdcc 81st SCSI disk whole disk + 16 = /dev/sdcd 82nd SCSI disk whole disk + 32 = /dev/sdce 83th SCSI disk whole disk + ... + 240 = /dev/sdcr 96th SCSI disk whole disk + + Partitions are handled in the same way as for IDE + disks (see major number 3) except that the limit on + partitions is 15. + + 70 char SpellCaster Protocol Services Interface + 0 = /dev/apscfg Configuration interface + 1 = /dev/apsauth Authentication interface + 2 = /dev/apslog Logging interface + 3 = /dev/apsdbg Debugging interface + 64 = /dev/apsisdn ISDN command interface + 65 = /dev/apsasync Async command interface + 128 = /dev/apsmon Monitor interface + + 70 block SCSI disk devices (96-111) + 0 = /dev/sdcs 97th SCSI disk whole disk + 16 = /dev/sdct 98th SCSI disk whole disk + 32 = /dev/sdcu 99th SCSI disk whole disk + ... + 240 = /dev/sddh 112nd SCSI disk whole disk + + Partitions are handled in the same way as for IDE + disks (see major number 3) except that the limit on + partitions is 15. + + 71 char Computone IntelliPort II serial card + 0 = /dev/ttyF0 IntelliPort II board 0, port 0 + 1 = /dev/ttyF1 IntelliPort II board 0, port 1 + ... + 63 = /dev/ttyF63 IntelliPort II board 0, port 63 + 64 = /dev/ttyF64 IntelliPort II board 1, port 0 + 65 = /dev/ttyF65 IntelliPort II board 1, port 1 + ... + 127 = /dev/ttyF127 IntelliPort II board 1, port 63 + 128 = /dev/ttyF128 IntelliPort II board 2, port 0 + 129 = /dev/ttyF129 IntelliPort II board 2, port 1 + ... + 191 = /dev/ttyF191 IntelliPort II board 2, port 63 + 192 = /dev/ttyF192 IntelliPort II board 3, port 0 + 193 = /dev/ttyF193 IntelliPort II board 3, port 1 + ... + 255 = /dev/ttyF255 IntelliPort II board 3, port 63 + + 71 block SCSI disk devices (112-127) + 0 = /dev/sddi 113th SCSI disk whole disk + 16 = /dev/sddj 114th SCSI disk whole disk + 32 = /dev/sddk 115th SCSI disk whole disk + ... + 240 = /dev/sddx 128th SCSI disk whole disk + + Partitions are handled in the same way as for IDE + disks (see major number 3) except that the limit on + partitions is 15. + + 72 char Computone IntelliPort II serial card - alternate devices + 0 = /dev/cuf0 Callout device for ttyF0 + 1 = /dev/cuf1 Callout device for ttyF1 + ... + 63 = /dev/cuf63 Callout device for ttyF63 + 64 = /dev/cuf64 Callout device for ttyF64 + 65 = /dev/cuf65 Callout device for ttyF65 + ... + 127 = /dev/cuf127 Callout device for ttyF127 + 128 = /dev/cuf128 Callout device for ttyF128 + 129 = /dev/cuf129 Callout device for ttyF129 + ... + 191 = /dev/cuf191 Callout device for ttyF191 + 192 = /dev/cuf192 Callout device for ttyF192 + 193 = /dev/cuf193 Callout device for ttyF193 + ... + 255 = /dev/cuf255 Callout device for ttyF255 + + 72 block Compaq Intelligent Drive Array, first controller + 0 = /dev/ida/c0d0 First logical drive whole disk + 16 = /dev/ida/c0d1 Second logical drive whole disk + ... + 240 = /dev/ida/c0d15 16th logical drive whole disk + + Partitions are handled the same way as for Mylex + DAC960 (see major number 48) except that the limit on + partitions is 15. + + 73 char Computone IntelliPort II serial card - control devices + 0 = /dev/ip2ipl0 Loadware device for board 0 + 1 = /dev/ip2stat0 Status device for board 0 + 4 = /dev/ip2ipl1 Loadware device for board 1 + 5 = /dev/ip2stat1 Status device for board 1 + 8 = /dev/ip2ipl2 Loadware device for board 2 + 9 = /dev/ip2stat2 Status device for board 2 + 12 = /dev/ip2ipl3 Loadware device for board 3 + 13 = /dev/ip2stat3 Status device for board 3 + + 73 block Compaq Intelligent Drive Array, second controller + 0 = /dev/ida/c1d0 First logical drive whole disk + 16 = /dev/ida/c1d1 Second logical drive whole disk + ... + 240 = /dev/ida/c1d15 16th logical drive whole disk + + Partitions are handled the same way as for Mylex + DAC960 (see major number 48) except that the limit on + partitions is 15. + + 74 char SCI bridge + 0 = /dev/SCI/0 SCI device 0 + 1 = /dev/SCI/1 SCI device 1 + ... + + Currently for Dolphin Interconnect Solutions' PCI-SCI + bridge. + + 74 block Compaq Intelligent Drive Array, third controller + 0 = /dev/ida/c2d0 First logical drive whole disk + 16 = /dev/ida/c2d1 Second logical drive whole disk + ... + 240 = /dev/ida/c2d15 16th logical drive whole disk + + Partitions are handled the same way as for Mylex + DAC960 (see major number 48) except that the limit on + partitions is 15. + + 75 char Specialix IO8+ serial card + 0 = /dev/ttyW0 First IO8+ port, first card + 1 = /dev/ttyW1 Second IO8+ port, first card + ... + 8 = /dev/ttyW8 First IO8+ port, second card + ... + + 75 block Compaq Intelligent Drive Array, fourth controller + 0 = /dev/ida/c3d0 First logical drive whole disk + 16 = /dev/ida/c3d1 Second logical drive whole disk + ... + 240 = /dev/ida/c3d15 16th logical drive whole disk + + Partitions are handled the same way as for Mylex + DAC960 (see major number 48) except that the limit on + partitions is 15. + + 76 char Specialix IO8+ serial card - alternate devices + 0 = /dev/cuw0 Callout device for ttyW0 + 1 = /dev/cuw1 Callout device for ttyW1 + ... + 8 = /dev/cuw8 Callout device for ttyW8 + ... + + 76 block Compaq Intelligent Drive Array, fifth controller + 0 = /dev/ida/c4d0 First logical drive whole disk + 16 = /dev/ida/c4d1 Second logical drive whole disk + ... + 240 = /dev/ida/c4d15 16th logical drive whole disk + + Partitions are handled the same way as for Mylex + DAC960 (see major number 48) except that the limit on + partitions is 15. + + + 77 char ComScire Quantum Noise Generator + 0 = /dev/qng ComScire Quantum Noise Generator + + 77 block Compaq Intelligent Drive Array, sixth controller + 0 = /dev/ida/c5d0 First logical drive whole disk + 16 = /dev/ida/c5d1 Second logical drive whole disk + ... + 240 = /dev/ida/c5d15 16th logical drive whole disk + + Partitions are handled the same way as for Mylex + DAC960 (see major number 48) except that the limit on + partitions is 15. + + 78 char PAM Software's multimodem boards + 0 = /dev/ttyM0 First PAM modem + 1 = /dev/ttyM1 Second PAM modem + ... + + 78 block Compaq Intelligent Drive Array, seventh controller + 0 = /dev/ida/c6d0 First logical drive whole disk + 16 = /dev/ida/c6d1 Second logical drive whole disk + ... + 240 = /dev/ida/c6d15 16th logical drive whole disk + + Partitions are handled the same way as for Mylex + DAC960 (see major number 48) except that the limit on + partitions is 15. + + 79 char PAM Software's multimodem boards - alternate devices + 0 = /dev/cum0 Callout device for ttyM0 + 1 = /dev/cum1 Callout device for ttyM1 + ... + + 79 block Compaq Intelligent Drive Array, eighth controller + 0 = /dev/ida/c7d0 First logical drive whole disk + 16 = /dev/ida/c7d1 Second logical drive whole disk + ... + 240 = /dev/ida/c715 16th logical drive whole disk + + Partitions are handled the same way as for Mylex + DAC960 (see major number 48) except that the limit on + partitions is 15. + + 80 char Photometrics AT200 CCD camera + 0 = /dev/at200 Photometrics AT200 CCD camera + + 80 block I2O hard disk + 0 = /dev/i2o/hda First I2O hard disk, whole disk + 16 = /dev/i2o/hdb Second I2O hard disk, whole disk + ... + 240 = /dev/i2o/hdp 16th I2O hard disk, whole disk + + Partitions are handled in the same way as for IDE + disks (see major number 3) except that the limit on + partitions is 15. + + 81 char video4linux + 0 = /dev/video0 Video capture/overlay device + ... + 63 = /dev/video63 Video capture/overlay device + 64 = /dev/radio0 Radio device + ... + 127 = /dev/radio63 Radio device + 128 = /dev/swradio0 Software Defined Radio device + ... + 191 = /dev/swradio63 Software Defined Radio device + 224 = /dev/vbi0 Vertical blank interrupt + ... + 255 = /dev/vbi31 Vertical blank interrupt + + Minor numbers are allocated dynamically unless + CONFIG_VIDEO_FIXED_MINOR_RANGES (default n) + configuration option is set. + + 81 block I2O hard disk + 0 = /dev/i2o/hdq 17th I2O hard disk, whole disk + 16 = /dev/i2o/hdr 18th I2O hard disk, whole disk + ... + 240 = /dev/i2o/hdaf 32nd I2O hard disk, whole disk + + Partitions are handled in the same way as for IDE + disks (see major number 3) except that the limit on + partitions is 15. + + 82 char WiNRADiO communications receiver card + 0 = /dev/winradio0 First WiNRADiO card + 1 = /dev/winradio1 Second WiNRADiO card + ... + + The driver and documentation may be obtained from + http://www.winradio.com/ + + 82 block I2O hard disk + 0 = /dev/i2o/hdag 33rd I2O hard disk, whole disk + 16 = /dev/i2o/hdah 34th I2O hard disk, whole disk + ... + 240 = /dev/i2o/hdav 48th I2O hard disk, whole disk + + Partitions are handled in the same way as for IDE + disks (see major number 3) except that the limit on + partitions is 15. + + 83 char Matrox mga_vid video driver + 0 = /dev/mga_vid0 1st video card + 1 = /dev/mga_vid1 2nd video card + 2 = /dev/mga_vid2 3rd video card + ... + 15 = /dev/mga_vid15 16th video card + + 83 block I2O hard disk + 0 = /dev/i2o/hdaw 49th I2O hard disk, whole disk + 16 = /dev/i2o/hdax 50th I2O hard disk, whole disk + ... + 240 = /dev/i2o/hdbl 64th I2O hard disk, whole disk + + Partitions are handled in the same way as for IDE + disks (see major number 3) except that the limit on + partitions is 15. + + 84 char Ikon 1011[57] Versatec Greensheet Interface + 0 = /dev/ihcp0 First Greensheet port + 1 = /dev/ihcp1 Second Greensheet port + + 84 block I2O hard disk + 0 = /dev/i2o/hdbm 65th I2O hard disk, whole disk + 16 = /dev/i2o/hdbn 66th I2O hard disk, whole disk + ... + 240 = /dev/i2o/hdcb 80th I2O hard disk, whole disk + + Partitions are handled in the same way as for IDE + disks (see major number 3) except that the limit on + partitions is 15. + + 85 char Linux/SGI shared memory input queue + 0 = /dev/shmiq Master shared input queue + 1 = /dev/qcntl0 First device pushed + 2 = /dev/qcntl1 Second device pushed + ... + + 85 block I2O hard disk + 0 = /dev/i2o/hdcc 81st I2O hard disk, whole disk + 16 = /dev/i2o/hdcd 82nd I2O hard disk, whole disk + ... + 240 = /dev/i2o/hdcr 96th I2O hard disk, whole disk + + Partitions are handled in the same way as for IDE + disks (see major number 3) except that the limit on + partitions is 15. + + 86 char SCSI media changer + 0 = /dev/sch0 First SCSI media changer + 1 = /dev/sch1 Second SCSI media changer + ... + + 86 block I2O hard disk + 0 = /dev/i2o/hdcs 97th I2O hard disk, whole disk + 16 = /dev/i2o/hdct 98th I2O hard disk, whole disk + ... + 240 = /dev/i2o/hddh 112th I2O hard disk, whole disk + + Partitions are handled in the same way as for IDE + disks (see major number 3) except that the limit on + partitions is 15. + + 87 char Sony Control-A1 stereo control bus + 0 = /dev/controla0 First device on chain + 1 = /dev/controla1 Second device on chain + ... + + 87 block I2O hard disk + 0 = /dev/i2o/hddi 113rd I2O hard disk, whole disk + 16 = /dev/i2o/hddj 114th I2O hard disk, whole disk + ... + 240 = /dev/i2o/hddx 128th I2O hard disk, whole disk + + Partitions are handled in the same way as for IDE + disks (see major number 3) except that the limit on + partitions is 15. + + 88 char COMX synchronous serial card + 0 = /dev/comx0 COMX channel 0 + 1 = /dev/comx1 COMX channel 1 + ... + + 88 block Seventh IDE hard disk/CD-ROM interface + 0 = /dev/hdm Master: whole disk (or CD-ROM) + 64 = /dev/hdn Slave: whole disk (or CD-ROM) + + Partitions are handled the same way as for the first + interface (see major number 3). + + 89 char I2C bus interface + 0 = /dev/i2c-0 First I2C adapter + 1 = /dev/i2c-1 Second I2C adapter + ... + + 89 block Eighth IDE hard disk/CD-ROM interface + 0 = /dev/hdo Master: whole disk (or CD-ROM) + 64 = /dev/hdp Slave: whole disk (or CD-ROM) + + Partitions are handled the same way as for the first + interface (see major number 3). + + 90 char Memory Technology Device (RAM, ROM, Flash) + 0 = /dev/mtd0 First MTD (rw) + 1 = /dev/mtdr0 First MTD (ro) + ... + 30 = /dev/mtd15 16th MTD (rw) + 31 = /dev/mtdr15 16th MTD (ro) + + 90 block Ninth IDE hard disk/CD-ROM interface + 0 = /dev/hdq Master: whole disk (or CD-ROM) + 64 = /dev/hdr Slave: whole disk (or CD-ROM) + + Partitions are handled the same way as for the first + interface (see major number 3). + + 91 char CAN-Bus devices + 0 = /dev/can0 First CAN-Bus controller + 1 = /dev/can1 Second CAN-Bus controller + ... + + 91 block Tenth IDE hard disk/CD-ROM interface + 0 = /dev/hds Master: whole disk (or CD-ROM) + 64 = /dev/hdt Slave: whole disk (or CD-ROM) + + Partitions are handled the same way as for the first + interface (see major number 3). + + 92 char Reserved for ith Kommunikationstechnik MIC ISDN card + + 92 block PPDD encrypted disk driver + 0 = /dev/ppdd0 First encrypted disk + 1 = /dev/ppdd1 Second encrypted disk + ... + + Partitions are handled in the same way as for IDE + disks (see major number 3) except that the limit on + partitions is 15. + + 93 char + + 93 block NAND Flash Translation Layer filesystem + 0 = /dev/nftla First NFTL layer + 16 = /dev/nftlb Second NFTL layer + ... + 240 = /dev/nftlp 16th NTFL layer + + 94 char + + 94 block IBM S/390 DASD block storage + 0 = /dev/dasda First DASD device, major + 1 = /dev/dasda1 First DASD device, block 1 + 2 = /dev/dasda2 First DASD device, block 2 + 3 = /dev/dasda3 First DASD device, block 3 + 4 = /dev/dasdb Second DASD device, major + 5 = /dev/dasdb1 Second DASD device, block 1 + 6 = /dev/dasdb2 Second DASD device, block 2 + 7 = /dev/dasdb3 Second DASD device, block 3 + ... + + 95 char IP filter + 0 = /dev/ipl Filter control device/log file + 1 = /dev/ipnat NAT control device/log file + 2 = /dev/ipstate State information log file + 3 = /dev/ipauth Authentication control device/log file + ... + + 96 char Parallel port ATAPI tape devices + 0 = /dev/pt0 First parallel port ATAPI tape + 1 = /dev/pt1 Second parallel port ATAPI tape + ... + 128 = /dev/npt0 First p.p. ATAPI tape, no rewind + 129 = /dev/npt1 Second p.p. ATAPI tape, no rewind + ... + + 96 block Inverse NAND Flash Translation Layer + 0 = /dev/inftla First INFTL layer + 16 = /dev/inftlb Second INFTL layer + ... + 240 = /dev/inftlp 16th INTFL layer + + 97 char Parallel port generic ATAPI interface + 0 = /dev/pg0 First parallel port ATAPI device + 1 = /dev/pg1 Second parallel port ATAPI device + 2 = /dev/pg2 Third parallel port ATAPI device + 3 = /dev/pg3 Fourth parallel port ATAPI device + + These devices support the same API as the generic SCSI + devices. + + 98 char Control and Measurement Device (comedi) + 0 = /dev/comedi0 First comedi device + 1 = /dev/comedi1 Second comedi device + ... + + See http://stm.lbl.gov/comedi. + + 98 block User-mode virtual block device + 0 = /dev/ubda First user-mode block device + 16 = /dev/udbb Second user-mode block device + ... + + Partitions are handled in the same way as for IDE + disks (see major number 3) except that the limit on + partitions is 15. + + This device is used by the user-mode virtual kernel port. + + 99 char Raw parallel ports + 0 = /dev/parport0 First parallel port + 1 = /dev/parport1 Second parallel port + ... + + 99 block JavaStation flash disk + 0 = /dev/jsfd JavaStation flash disk + + 100 char Telephony for Linux + 0 = /dev/phone0 First telephony device + 1 = /dev/phone1 Second telephony device + ... + + 101 char Motorola DSP 56xxx board + 0 = /dev/mdspstat Status information + 1 = /dev/mdsp1 First DSP board I/O controls + ... + 16 = /dev/mdsp16 16th DSP board I/O controls + + 101 block AMI HyperDisk RAID controller + 0 = /dev/amiraid/ar0 First array whole disk + 16 = /dev/amiraid/ar1 Second array whole disk + ... + 240 = /dev/amiraid/ar15 16th array whole disk + + For each device, partitions are added as: + 0 = /dev/amiraid/ar? Whole disk + 1 = /dev/amiraid/ar?p1 First partition + 2 = /dev/amiraid/ar?p2 Second partition + ... + 15 = /dev/amiraid/ar?p15 15th partition + + 102 char + + 102 block Compressed block device + 0 = /dev/cbd/a First compressed block device, whole device + 16 = /dev/cbd/b Second compressed block device, whole device + ... + 240 = /dev/cbd/p 16th compressed block device, whole device + + Partitions are handled in the same way as for IDE + disks (see major number 3) except that the limit on + partitions is 15. + + 103 char Arla network file system + 0 = /dev/nnpfs0 First NNPFS device + 1 = /dev/nnpfs1 Second NNPFS device + + Arla is a free clone of the Andrew File System, AFS. + The NNPFS device gives user mode filesystem + implementations a kernel presence for caching and easy + mounting. For more information about the project, + write to or see + http://www.stacken.kth.se/project/arla/ + + 103 block Audit device + 0 = /dev/audit Audit device + + 104 char Flash BIOS support + + 104 block Compaq Next Generation Drive Array, first controller + 0 = /dev/cciss/c0d0 First logical drive, whole disk + 16 = /dev/cciss/c0d1 Second logical drive, whole disk + ... + 240 = /dev/cciss/c0d15 16th logical drive, whole disk + + Partitions are handled the same way as for Mylex + DAC960 (see major number 48) except that the limit on + partitions is 15. + + 105 char Comtrol VS-1000 serial controller + 0 = /dev/ttyV0 First VS-1000 port + 1 = /dev/ttyV1 Second VS-1000 port + ... + + 105 block Compaq Next Generation Drive Array, second controller + 0 = /dev/cciss/c1d0 First logical drive, whole disk + 16 = /dev/cciss/c1d1 Second logical drive, whole disk + ... + 240 = /dev/cciss/c1d15 16th logical drive, whole disk + + Partitions are handled the same way as for Mylex + DAC960 (see major number 48) except that the limit on + partitions is 15. + + 106 char Comtrol VS-1000 serial controller - alternate devices + 0 = /dev/cuv0 First VS-1000 port + 1 = /dev/cuv1 Second VS-1000 port + ... + + 106 block Compaq Next Generation Drive Array, third controller + 0 = /dev/cciss/c2d0 First logical drive, whole disk + 16 = /dev/cciss/c2d1 Second logical drive, whole disk + ... + 240 = /dev/cciss/c2d15 16th logical drive, whole disk + + Partitions are handled the same way as for Mylex + DAC960 (see major number 48) except that the limit on + partitions is 15. + + 107 char 3Dfx Voodoo Graphics device + 0 = /dev/3dfx Primary 3Dfx graphics device + + 107 block Compaq Next Generation Drive Array, fourth controller + 0 = /dev/cciss/c3d0 First logical drive, whole disk + 16 = /dev/cciss/c3d1 Second logical drive, whole disk + ... + 240 = /dev/cciss/c3d15 16th logical drive, whole disk + + Partitions are handled the same way as for Mylex + DAC960 (see major number 48) except that the limit on + partitions is 15. + + 108 char Device independent PPP interface + 0 = /dev/ppp Device independent PPP interface + + 108 block Compaq Next Generation Drive Array, fifth controller + 0 = /dev/cciss/c4d0 First logical drive, whole disk + 16 = /dev/cciss/c4d1 Second logical drive, whole disk + ... + 240 = /dev/cciss/c4d15 16th logical drive, whole disk + + Partitions are handled the same way as for Mylex + DAC960 (see major number 48) except that the limit on + partitions is 15. + + 109 char Reserved for logical volume manager + + 109 block Compaq Next Generation Drive Array, sixth controller + 0 = /dev/cciss/c5d0 First logical drive, whole disk + 16 = /dev/cciss/c5d1 Second logical drive, whole disk + ... + 240 = /dev/cciss/c5d15 16th logical drive, whole disk + + Partitions are handled the same way as for Mylex + DAC960 (see major number 48) except that the limit on + partitions is 15. + + 110 char miroMEDIA Surround board + 0 = /dev/srnd0 First miroMEDIA Surround board + 1 = /dev/srnd1 Second miroMEDIA Surround board + ... + + 110 block Compaq Next Generation Drive Array, seventh controller + 0 = /dev/cciss/c6d0 First logical drive, whole disk + 16 = /dev/cciss/c6d1 Second logical drive, whole disk + ... + 240 = /dev/cciss/c6d15 16th logical drive, whole disk + + Partitions are handled the same way as for Mylex + DAC960 (see major number 48) except that the limit on + partitions is 15. + + 111 char + + 111 block Compaq Next Generation Drive Array, eighth controller + 0 = /dev/cciss/c7d0 First logical drive, whole disk + 16 = /dev/cciss/c7d1 Second logical drive, whole disk + ... + 240 = /dev/cciss/c7d15 16th logical drive, whole disk + + Partitions are handled the same way as for Mylex + DAC960 (see major number 48) except that the limit on + partitions is 15. + + 112 char ISI serial card + 0 = /dev/ttyM0 First ISI port + 1 = /dev/ttyM1 Second ISI port + ... + + There is currently a device-naming conflict between + these and PAM multimodems (major 78). + + 112 block IBM iSeries virtual disk + 0 = /dev/iseries/vda First virtual disk, whole disk + 8 = /dev/iseries/vdb Second virtual disk, whole disk + ... + 200 = /dev/iseries/vdz 26th virtual disk, whole disk + 208 = /dev/iseries/vdaa 27th virtual disk, whole disk + ... + 248 = /dev/iseries/vdaf 32nd virtual disk, whole disk + + Partitions are handled in the same way as for IDE + disks (see major number 3) except that the limit on + partitions is 7. + + 113 char ISI serial card - alternate devices + 0 = /dev/cum0 Callout device for ttyM0 + 1 = /dev/cum1 Callout device for ttyM1 + ... + + 113 block IBM iSeries virtual CD-ROM + 0 = /dev/iseries/vcda First virtual CD-ROM + 1 = /dev/iseries/vcdb Second virtual CD-ROM + ... + + 114 char Picture Elements ISE board + 0 = /dev/ise0 First ISE board + 1 = /dev/ise1 Second ISE board + ... + 128 = /dev/isex0 Control node for first ISE board + 129 = /dev/isex1 Control node for second ISE board + ... + + The ISE board is an embedded computer, optimized for + image processing. The /dev/iseN nodes are the general + I/O access to the board, the /dev/isex0 nodes command + nodes used to control the board. + + 114 block IDE BIOS powered software RAID interfaces such as the + Promise Fastrak + + 0 = /dev/ataraid/d0 + 1 = /dev/ataraid/d0p1 + 2 = /dev/ataraid/d0p2 + ... + 16 = /dev/ataraid/d1 + 17 = /dev/ataraid/d1p1 + 18 = /dev/ataraid/d1p2 + ... + 255 = /dev/ataraid/d15p15 + + Partitions are handled in the same way as for IDE + disks (see major number 3) except that the limit on + partitions is 15. + + 115 char TI link cable devices (115 was formerly the console driver speaker) + 0 = /dev/tipar0 Parallel cable on first parallel port + ... + 7 = /dev/tipar7 Parallel cable on seventh parallel port + + 8 = /dev/tiser0 Serial cable on first serial port + ... + 15 = /dev/tiser7 Serial cable on seventh serial port + + 16 = /dev/tiusb0 First USB cable + ... + 47 = /dev/tiusb31 32nd USB cable + + 115 block NetWare (NWFS) Devices (0-255) + + The NWFS (NetWare) devices are used to present a + collection of NetWare Mirror Groups or NetWare + Partitions as a logical storage segment for + use in mounting NetWare volumes. A maximum of + 256 NetWare volumes can be supported in a single + machine. + + http://cgfa.telepac.pt/ftp2/kernel.org/linux/kernel/people/jmerkey/nwfs/ + + 0 = /dev/nwfs/v0 First NetWare (NWFS) Logical Volume + 1 = /dev/nwfs/v1 Second NetWare (NWFS) Logical Volume + 2 = /dev/nwfs/v2 Third NetWare (NWFS) Logical Volume + ... + 255 = /dev/nwfs/v255 Last NetWare (NWFS) Logical Volume + + 116 char Advanced Linux Sound Driver (ALSA) + + 116 block MicroMemory battery backed RAM adapter (NVRAM) + Supports 16 boards, 15 partitions each. + Requested by neilb at cse.unsw.edu.au. + + 0 = /dev/umem/d0 Whole of first board + 1 = /dev/umem/d0p1 First partition of first board + 2 = /dev/umem/d0p2 Second partition of first board + 15 = /dev/umem/d0p15 15th partition of first board + + 16 = /dev/umem/d1 Whole of second board + 17 = /dev/umem/d1p1 First partition of second board + ... + 255= /dev/umem/d15p15 15th partition of 16th board. + + 117 char COSA/SRP synchronous serial card + 0 = /dev/cosa0c0 1st board, 1st channel + 1 = /dev/cosa0c1 1st board, 2nd channel + ... + 16 = /dev/cosa1c0 2nd board, 1st channel + 17 = /dev/cosa1c1 2nd board, 2nd channel + ... + + 117 block Enterprise Volume Management System (EVMS) + + The EVMS driver uses a layered, plug-in model to provide + unparalleled flexibility and extensibility in managing + storage. This allows for easy expansion or customization + of various levels of volume management. Requested by + Mark Peloquin (peloquin at us.ibm.com). + + Note: EVMS populates and manages all the devnodes in + /dev/evms. + + http://sf.net/projects/evms + + 0 = /dev/evms/block_device EVMS block device + 1 = /dev/evms/legacyname1 First EVMS legacy device + 2 = /dev/evms/legacyname2 Second EVMS legacy device + ... + Both ranges can grow (down or up) until they meet. + ... + 254 = /dev/evms/EVMSname2 Second EVMS native device + 255 = /dev/evms/EVMSname1 First EVMS native device + + Note: legacyname(s) are derived from the normal legacy + device names. For example, /dev/hda5 would become + /dev/evms/hda5. + + 118 char IBM Cryptographic Accelerator + 0 = /dev/ica Virtual interface to all IBM Crypto Accelerators + 1 = /dev/ica0 IBMCA Device 0 + 2 = /dev/ica1 IBMCA Device 1 + ... + + 119 char VMware virtual network control + 0 = /dev/vnet0 1st virtual network + 1 = /dev/vnet1 2nd virtual network + ... + + 120-127 char LOCAL/EXPERIMENTAL USE + + 120-127 block LOCAL/EXPERIMENTAL USE + Allocated for local/experimental use. For devices not + assigned official numbers, these ranges should be + used in order to avoid conflicting with future assignments. + + 128-135 char Unix98 PTY masters + + These devices should not have corresponding device + nodes; instead they should be accessed through the + /dev/ptmx cloning interface. + + 128 block SCSI disk devices (128-143) + 0 = /dev/sddy 129th SCSI disk whole disk + 16 = /dev/sddz 130th SCSI disk whole disk + 32 = /dev/sdea 131th SCSI disk whole disk + ... + 240 = /dev/sden 144th SCSI disk whole disk + + Partitions are handled in the same way as for IDE + disks (see major number 3) except that the limit on + partitions is 15. + + 129 block SCSI disk devices (144-159) + 0 = /dev/sdeo 145th SCSI disk whole disk + 16 = /dev/sdep 146th SCSI disk whole disk + 32 = /dev/sdeq 147th SCSI disk whole disk + ... + 240 = /dev/sdfd 160th SCSI disk whole disk + + Partitions are handled in the same way as for IDE + disks (see major number 3) except that the limit on + partitions is 15. + + 130 char (Misc devices) + + 130 block SCSI disk devices (160-175) + 0 = /dev/sdfe 161st SCSI disk whole disk + 16 = /dev/sdff 162nd SCSI disk whole disk + 32 = /dev/sdfg 163rd SCSI disk whole disk + ... + 240 = /dev/sdft 176th SCSI disk whole disk + + Partitions are handled in the same way as for IDE + disks (see major number 3) except that the limit on + partitions is 15. + + 131 block SCSI disk devices (176-191) + 0 = /dev/sdfu 177th SCSI disk whole disk + 16 = /dev/sdfv 178th SCSI disk whole disk + 32 = /dev/sdfw 179th SCSI disk whole disk + ... + 240 = /dev/sdgj 192nd SCSI disk whole disk + + Partitions are handled in the same way as for IDE + disks (see major number 3) except that the limit on + partitions is 15. + + 132 block SCSI disk devices (192-207) + 0 = /dev/sdgk 193rd SCSI disk whole disk + 16 = /dev/sdgl 194th SCSI disk whole disk + 32 = /dev/sdgm 195th SCSI disk whole disk + ... + 240 = /dev/sdgz 208th SCSI disk whole disk + + Partitions are handled in the same way as for IDE + disks (see major number 3) except that the limit on + partitions is 15. + + 133 block SCSI disk devices (208-223) + 0 = /dev/sdha 209th SCSI disk whole disk + 16 = /dev/sdhb 210th SCSI disk whole disk + 32 = /dev/sdhc 211th SCSI disk whole disk + ... + 240 = /dev/sdhp 224th SCSI disk whole disk + + Partitions are handled in the same way as for IDE + disks (see major number 3) except that the limit on + partitions is 15. + + 134 block SCSI disk devices (224-239) + 0 = /dev/sdhq 225th SCSI disk whole disk + 16 = /dev/sdhr 226th SCSI disk whole disk + 32 = /dev/sdhs 227th SCSI disk whole disk + ... + 240 = /dev/sdif 240th SCSI disk whole disk + + Partitions are handled in the same way as for IDE + disks (see major number 3) except that the limit on + partitions is 15. + + 135 block SCSI disk devices (240-255) + 0 = /dev/sdig 241st SCSI disk whole disk + 16 = /dev/sdih 242nd SCSI disk whole disk + 32 = /dev/sdih 243rd SCSI disk whole disk + ... + 240 = /dev/sdiv 256th SCSI disk whole disk + + Partitions are handled in the same way as for IDE + disks (see major number 3) except that the limit on + partitions is 15. + + 136-143 char Unix98 PTY slaves + 0 = /dev/pts/0 First Unix98 pseudo-TTY + 1 = /dev/pts/1 Second Unix98 pseudo-TTY + ... + + These device nodes are automatically generated with + the proper permissions and modes by mounting the + devpts filesystem onto /dev/pts with the appropriate + mount options (distribution dependent, however, on + *most* distributions the appropriate options are + "mode=0620,gid=".) + + 136 block Mylex DAC960 PCI RAID controller; ninth controller + 0 = /dev/rd/c8d0 First disk, whole disk + 8 = /dev/rd/c8d1 Second disk, whole disk + ... + 248 = /dev/rd/c8d31 32nd disk, whole disk + + Partitions are handled as for major 48. + + 137 block Mylex DAC960 PCI RAID controller; tenth controller + 0 = /dev/rd/c9d0 First disk, whole disk + 8 = /dev/rd/c9d1 Second disk, whole disk + ... + 248 = /dev/rd/c9d31 32nd disk, whole disk + + Partitions are handled as for major 48. + + 138 block Mylex DAC960 PCI RAID controller; eleventh controller + 0 = /dev/rd/c10d0 First disk, whole disk + 8 = /dev/rd/c10d1 Second disk, whole disk + ... + 248 = /dev/rd/c10d31 32nd disk, whole disk + + Partitions are handled as for major 48. + + 139 block Mylex DAC960 PCI RAID controller; twelfth controller + 0 = /dev/rd/c11d0 First disk, whole disk + 8 = /dev/rd/c11d1 Second disk, whole disk + ... + 248 = /dev/rd/c11d31 32nd disk, whole disk + + Partitions are handled as for major 48. + + 140 block Mylex DAC960 PCI RAID controller; thirteenth controller + 0 = /dev/rd/c12d0 First disk, whole disk + 8 = /dev/rd/c12d1 Second disk, whole disk + ... + 248 = /dev/rd/c12d31 32nd disk, whole disk + + Partitions are handled as for major 48. + + 141 block Mylex DAC960 PCI RAID controller; fourteenth controller + 0 = /dev/rd/c13d0 First disk, whole disk + 8 = /dev/rd/c13d1 Second disk, whole disk + ... + 248 = /dev/rd/c13d31 32nd disk, whole disk + + Partitions are handled as for major 48. + + 142 block Mylex DAC960 PCI RAID controller; fifteenth controller + 0 = /dev/rd/c14d0 First disk, whole disk + 8 = /dev/rd/c14d1 Second disk, whole disk + ... + 248 = /dev/rd/c14d31 32nd disk, whole disk + + Partitions are handled as for major 48. + + 143 block Mylex DAC960 PCI RAID controller; sixteenth controller + 0 = /dev/rd/c15d0 First disk, whole disk + 8 = /dev/rd/c15d1 Second disk, whole disk + ... + 248 = /dev/rd/c15d31 32nd disk, whole disk + + Partitions are handled as for major 48. + + 144 char Encapsulated PPP + 0 = /dev/pppox0 First PPP over Ethernet + ... + 63 = /dev/pppox63 64th PPP over Ethernet + + This is primarily used for ADSL. + + The SST 5136-DN DeviceNet interface driver has been + relocated to major 183 due to an unfortunate conflict. + + 144 block Expansion Area #1 for more non-device (e.g. NFS) mounts + 0 = mounted device 256 + 255 = mounted device 511 + + 145 char SAM9407-based soundcard + 0 = /dev/sam0_mixer + 1 = /dev/sam0_sequencer + 2 = /dev/sam0_midi00 + 3 = /dev/sam0_dsp + 4 = /dev/sam0_audio + 6 = /dev/sam0_sndstat + 18 = /dev/sam0_midi01 + 34 = /dev/sam0_midi02 + 50 = /dev/sam0_midi03 + 64 = /dev/sam1_mixer + ... + 128 = /dev/sam2_mixer + ... + 192 = /dev/sam3_mixer + ... + + Device functions match OSS, but offer a number of + addons, which are sam9407 specific. OSS can be + operated simultaneously, taking care of the codec. + + 145 block Expansion Area #2 for more non-device (e.g. NFS) mounts + 0 = mounted device 512 + 255 = mounted device 767 + + 146 char SYSTRAM SCRAMNet mirrored-memory network + 0 = /dev/scramnet0 First SCRAMNet device + 1 = /dev/scramnet1 Second SCRAMNet device + ... + + 146 block Expansion Area #3 for more non-device (e.g. NFS) mounts + 0 = mounted device 768 + 255 = mounted device 1023 + + 147 char Aureal Semiconductor Vortex Audio device + 0 = /dev/aureal0 First Aureal Vortex + 1 = /dev/aureal1 Second Aureal Vortex + ... + + 147 block Distributed Replicated Block Device (DRBD) + 0 = /dev/drbd0 First DRBD device + 1 = /dev/drbd1 Second DRBD device + ... + + 148 char Technology Concepts serial card + 0 = /dev/ttyT0 First TCL port + 1 = /dev/ttyT1 Second TCL port + ... + + 149 char Technology Concepts serial card - alternate devices + 0 = /dev/cut0 Callout device for ttyT0 + 1 = /dev/cut0 Callout device for ttyT1 + ... + + 150 char Real-Time Linux FIFOs + 0 = /dev/rtf0 First RTLinux FIFO + 1 = /dev/rtf1 Second RTLinux FIFO + ... + + 151 char DPT I2O SmartRaid V controller + 0 = /dev/dpti0 First DPT I2O adapter + 1 = /dev/dpti1 Second DPT I2O adapter + ... + + 152 char EtherDrive Control Device + 0 = /dev/etherd/ctl Connect/Disconnect an EtherDrive + 1 = /dev/etherd/err Monitor errors + 2 = /dev/etherd/raw Raw AoE packet monitor + + 152 block EtherDrive Block Devices + 0 = /dev/etherd/0 EtherDrive 0 + ... + 255 = /dev/etherd/255 EtherDrive 255 + + 153 char SPI Bus Interface (sometimes referred to as MicroWire) + 0 = /dev/spi0 First SPI device on the bus + 1 = /dev/spi1 Second SPI device on the bus + ... + 15 = /dev/spi15 Sixteenth SPI device on the bus + + 153 block Enhanced Metadisk RAID (EMD) storage units + 0 = /dev/emd/0 First unit + 1 = /dev/emd/0p1 Partition 1 on First unit + 2 = /dev/emd/0p2 Partition 2 on First unit + ... + 15 = /dev/emd/0p15 Partition 15 on First unit + + 16 = /dev/emd/1 Second unit + 32 = /dev/emd/2 Third unit + ... + 240 = /dev/emd/15 Sixteenth unit + + Partitions are handled in the same way as for IDE + disks (see major number 3) except that the limit on + partitions is 15. + + 154 char Specialix RIO serial card + 0 = /dev/ttySR0 First RIO port + ... + 255 = /dev/ttySR255 256th RIO port + + 155 char Specialix RIO serial card - alternate devices + 0 = /dev/cusr0 Callout device for ttySR0 + ... + 255 = /dev/cusr255 Callout device for ttySR255 + + 156 char Specialix RIO serial card + 0 = /dev/ttySR256 257th RIO port + ... + 255 = /dev/ttySR511 512th RIO port + + 157 char Specialix RIO serial card - alternate devices + 0 = /dev/cusr256 Callout device for ttySR256 + ... + 255 = /dev/cusr511 Callout device for ttySR511 + + 158 char Dialogic GammaLink fax driver + 0 = /dev/gfax0 GammaLink channel 0 + 1 = /dev/gfax1 GammaLink channel 1 + ... + + 159 char RESERVED + + 159 block RESERVED + + 160 char General Purpose Instrument Bus (GPIB) + 0 = /dev/gpib0 First GPIB bus + 1 = /dev/gpib1 Second GPIB bus + ... + + 160 block Carmel 8-port SATA Disks on First Controller + 0 = /dev/carmel/0 SATA disk 0 whole disk + 1 = /dev/carmel/0p1 SATA disk 0 partition 1 + ... + 31 = /dev/carmel/0p31 SATA disk 0 partition 31 + + 32 = /dev/carmel/1 SATA disk 1 whole disk + 64 = /dev/carmel/2 SATA disk 2 whole disk + ... + 224 = /dev/carmel/7 SATA disk 7 whole disk + + Partitions are handled in the same way as for IDE + disks (see major number 3) except that the limit on + partitions is 31. + + 161 char IrCOMM devices (IrDA serial/parallel emulation) + 0 = /dev/ircomm0 First IrCOMM device + 1 = /dev/ircomm1 Second IrCOMM device + ... + 16 = /dev/irlpt0 First IrLPT device + 17 = /dev/irlpt1 Second IrLPT device + ... + + 161 block Carmel 8-port SATA Disks on Second Controller + 0 = /dev/carmel/8 SATA disk 8 whole disk + 1 = /dev/carmel/8p1 SATA disk 8 partition 1 + ... + 31 = /dev/carmel/8p31 SATA disk 8 partition 31 + + 32 = /dev/carmel/9 SATA disk 9 whole disk + 64 = /dev/carmel/10 SATA disk 10 whole disk + ... + 224 = /dev/carmel/15 SATA disk 15 whole disk + + Partitions are handled in the same way as for IDE + disks (see major number 3) except that the limit on + partitions is 31. + + 162 char Raw block device interface + 0 = /dev/rawctl Raw I/O control device + 1 = /dev/raw/raw1 First raw I/O device + 2 = /dev/raw/raw2 Second raw I/O device + ... + max minor number of raw device is set by kernel config + MAX_RAW_DEVS or raw module parameter 'max_raw_devs' + + 163 char + + 164 char Chase Research AT/PCI-Fast serial card + 0 = /dev/ttyCH0 AT/PCI-Fast board 0, port 0 + ... + 15 = /dev/ttyCH15 AT/PCI-Fast board 0, port 15 + 16 = /dev/ttyCH16 AT/PCI-Fast board 1, port 0 + ... + 31 = /dev/ttyCH31 AT/PCI-Fast board 1, port 15 + 32 = /dev/ttyCH32 AT/PCI-Fast board 2, port 0 + ... + 47 = /dev/ttyCH47 AT/PCI-Fast board 2, port 15 + 48 = /dev/ttyCH48 AT/PCI-Fast board 3, port 0 + ... + 63 = /dev/ttyCH63 AT/PCI-Fast board 3, port 15 + + 165 char Chase Research AT/PCI-Fast serial card - alternate devices + 0 = /dev/cuch0 Callout device for ttyCH0 + ... + 63 = /dev/cuch63 Callout device for ttyCH63 + + 166 char ACM USB modems + 0 = /dev/ttyACM0 First ACM modem + 1 = /dev/ttyACM1 Second ACM modem + ... + + 167 char ACM USB modems - alternate devices + 0 = /dev/cuacm0 Callout device for ttyACM0 + 1 = /dev/cuacm1 Callout device for ttyACM1 + ... + + 168 char Eracom CSA7000 PCI encryption adaptor + 0 = /dev/ecsa0 First CSA7000 + 1 = /dev/ecsa1 Second CSA7000 + ... + + 169 char Eracom CSA8000 PCI encryption adaptor + 0 = /dev/ecsa8-0 First CSA8000 + 1 = /dev/ecsa8-1 Second CSA8000 + ... + + 170 char AMI MegaRAC remote access controller + 0 = /dev/megarac0 First MegaRAC card + 1 = /dev/megarac1 Second MegaRAC card + ... + + 171 char Reserved for IEEE 1394 (Firewire) + + 172 char Moxa Intellio serial card + 0 = /dev/ttyMX0 First Moxa port + 1 = /dev/ttyMX1 Second Moxa port + ... + 127 = /dev/ttyMX127 128th Moxa port + 128 = /dev/moxactl Moxa control port + + 173 char Moxa Intellio serial card - alternate devices + 0 = /dev/cumx0 Callout device for ttyMX0 + 1 = /dev/cumx1 Callout device for ttyMX1 + ... + 127 = /dev/cumx127 Callout device for ttyMX127 + + 174 char SmartIO serial card + 0 = /dev/ttySI0 First SmartIO port + 1 = /dev/ttySI1 Second SmartIO port + ... + + 175 char SmartIO serial card - alternate devices + 0 = /dev/cusi0 Callout device for ttySI0 + 1 = /dev/cusi1 Callout device for ttySI1 + ... + + 176 char nCipher nFast PCI crypto accelerator + 0 = /dev/nfastpci0 First nFast PCI device + 1 = /dev/nfastpci1 First nFast PCI device + ... + + 177 char TI PCILynx memory spaces + 0 = /dev/pcilynx/aux0 AUX space of first PCILynx card + ... + 15 = /dev/pcilynx/aux15 AUX space of 16th PCILynx card + 16 = /dev/pcilynx/rom0 ROM space of first PCILynx card + ... + 31 = /dev/pcilynx/rom15 ROM space of 16th PCILynx card + 32 = /dev/pcilynx/ram0 RAM space of first PCILynx card + ... + 47 = /dev/pcilynx/ram15 RAM space of 16th PCILynx card + + 178 char Giganet cLAN1xxx virtual interface adapter + 0 = /dev/clanvi0 First cLAN adapter + 1 = /dev/clanvi1 Second cLAN adapter + ... + + 179 block MMC block devices + 0 = /dev/mmcblk0 First SD/MMC card + 1 = /dev/mmcblk0p1 First partition on first MMC card + 8 = /dev/mmcblk1 Second SD/MMC card + ... + + The start of next SD/MMC card can be configured with + CONFIG_MMC_BLOCK_MINORS, or overridden at boot/modprobe + time using the mmcblk.perdev_minors option. That would + bump the offset between each card to be the configured + value instead of the default 8. + + 179 char CCube DVXChip-based PCI products + 0 = /dev/dvxirq0 First DVX device + 1 = /dev/dvxirq1 Second DVX device + ... + + 180 char USB devices + 0 = /dev/usb/lp0 First USB printer + ... + 15 = /dev/usb/lp15 16th USB printer + 48 = /dev/usb/scanner0 First USB scanner + ... + 63 = /dev/usb/scanner15 16th USB scanner + 64 = /dev/usb/rio500 Diamond Rio 500 + 65 = /dev/usb/usblcd USBLCD Interface (info@usblcd.de) + 66 = /dev/usb/cpad0 Synaptics cPad (mouse/LCD) + 96 = /dev/usb/hiddev0 1st USB HID device + ... + 111 = /dev/usb/hiddev15 16th USB HID device + 112 = /dev/usb/auer0 1st auerswald ISDN device + ... + 127 = /dev/usb/auer15 16th auerswald ISDN device + 128 = /dev/usb/brlvgr0 First Braille Voyager device + ... + 131 = /dev/usb/brlvgr3 Fourth Braille Voyager device + 132 = /dev/usb/idmouse ID Mouse (fingerprint scanner) device + 133 = /dev/usb/sisusbvga1 First SiSUSB VGA device + ... + 140 = /dev/usb/sisusbvga8 Eighth SISUSB VGA device + 144 = /dev/usb/lcd USB LCD device + 160 = /dev/usb/legousbtower0 1st USB Legotower device + ... + 175 = /dev/usb/legousbtower15 16th USB Legotower device + 176 = /dev/usb/usbtmc1 First USB TMC device + ... + 191 = /dev/usb/usbtmc16 16th USB TMC device + 192 = /dev/usb/yurex1 First USB Yurex device + ... + 209 = /dev/usb/yurex16 16th USB Yurex device + + 180 block USB block devices + 0 = /dev/uba First USB block device + 8 = /dev/ubb Second USB block device + 16 = /dev/ubc Third USB block device + ... + + 181 char Conrad Electronic parallel port radio clocks + 0 = /dev/pcfclock0 First Conrad radio clock + 1 = /dev/pcfclock1 Second Conrad radio clock + ... + + 182 char Picture Elements THR2 binarizer + 0 = /dev/pethr0 First THR2 board + 1 = /dev/pethr1 Second THR2 board + ... + + 183 char SST 5136-DN DeviceNet interface + 0 = /dev/ss5136dn0 First DeviceNet interface + 1 = /dev/ss5136dn1 Second DeviceNet interface + ... + + This device used to be assigned to major number 144. + It had to be moved due to an unfortunate conflict. + + 184 char Picture Elements' video simulator/sender + 0 = /dev/pevss0 First sender board + 1 = /dev/pevss1 Second sender board + ... + + 185 char InterMezzo high availability file system + 0 = /dev/intermezzo0 First cache manager + 1 = /dev/intermezzo1 Second cache manager + ... + + See http://web.archive.org/web/20080115195241/ + http://inter-mezzo.org/index.html + + 186 char Object-based storage control device + 0 = /dev/obd0 First obd control device + 1 = /dev/obd1 Second obd control device + ... + + See ftp://ftp.lustre.org/pub/obd for code and information. + + 187 char DESkey hardware encryption device + 0 = /dev/deskey0 First DES key + 1 = /dev/deskey1 Second DES key + ... + + 188 char USB serial converters + 0 = /dev/ttyUSB0 First USB serial converter + 1 = /dev/ttyUSB1 Second USB serial converter + ... + + 189 char USB serial converters - alternate devices + 0 = /dev/cuusb0 Callout device for ttyUSB0 + 1 = /dev/cuusb1 Callout device for ttyUSB1 + ... + + 190 char Kansas City tracker/tuner card + 0 = /dev/kctt0 First KCT/T card + 1 = /dev/kctt1 Second KCT/T card + ... + + 191 char Reserved for PCMCIA + + 192 char Kernel profiling interface + 0 = /dev/profile Profiling control device + 1 = /dev/profile0 Profiling device for CPU 0 + 2 = /dev/profile1 Profiling device for CPU 1 + ... + + 193 char Kernel event-tracing interface + 0 = /dev/trace Tracing control device + 1 = /dev/trace0 Tracing device for CPU 0 + 2 = /dev/trace1 Tracing device for CPU 1 + ... + + 194 char linVideoStreams (LINVS) + 0 = /dev/mvideo/status0 Video compression status + 1 = /dev/mvideo/stream0 Video stream + 2 = /dev/mvideo/frame0 Single compressed frame + 3 = /dev/mvideo/rawframe0 Raw uncompressed frame + 4 = /dev/mvideo/codec0 Direct codec access + 5 = /dev/mvideo/video4linux0 Video4Linux compatibility + + 16 = /dev/mvideo/status1 Second device + ... + 32 = /dev/mvideo/status2 Third device + ... + ... + 240 = /dev/mvideo/status15 16th device + ... + + 195 char Nvidia graphics devices + 0 = /dev/nvidia0 First Nvidia card + 1 = /dev/nvidia1 Second Nvidia card + ... + 255 = /dev/nvidiactl Nvidia card control device + + 196 char Tormenta T1 card + 0 = /dev/tor/0 Master control channel for all cards + 1 = /dev/tor/1 First DS0 + 2 = /dev/tor/2 Second DS0 + ... + 48 = /dev/tor/48 48th DS0 + 49 = /dev/tor/49 First pseudo-channel + 50 = /dev/tor/50 Second pseudo-channel + ... + + 197 char OpenTNF tracing facility + 0 = /dev/tnf/t0 Trace 0 data extraction + 1 = /dev/tnf/t1 Trace 1 data extraction + ... + 128 = /dev/tnf/status Tracing facility status + 130 = /dev/tnf/trace Tracing device + + 198 char Total Impact TPMP2 quad coprocessor PCI card + 0 = /dev/tpmp2/0 First card + 1 = /dev/tpmp2/1 Second card + ... + + 199 char Veritas volume manager (VxVM) volumes + 0 = /dev/vx/rdsk/*/* First volume + 1 = /dev/vx/rdsk/*/* Second volume + ... + + 199 block Veritas volume manager (VxVM) volumes + 0 = /dev/vx/dsk/*/* First volume + 1 = /dev/vx/dsk/*/* Second volume + ... + + The namespace in these directories is maintained by + the user space VxVM software. + + 200 char Veritas VxVM configuration interface + 0 = /dev/vx/config Configuration access node + 1 = /dev/vx/trace Volume i/o trace access node + 2 = /dev/vx/iod Volume i/o daemon access node + 3 = /dev/vx/info Volume information access node + 4 = /dev/vx/task Volume tasks access node + 5 = /dev/vx/taskmon Volume tasks monitor daemon + + 201 char Veritas VxVM dynamic multipathing driver + 0 = /dev/vx/rdmp/* First multipath device + 1 = /dev/vx/rdmp/* Second multipath device + ... + 201 block Veritas VxVM dynamic multipathing driver + 0 = /dev/vx/dmp/* First multipath device + 1 = /dev/vx/dmp/* Second multipath device + ... + + The namespace in these directories is maintained by + the user space VxVM software. + + 202 char CPU model-specific registers + 0 = /dev/cpu/0/msr MSRs on CPU 0 + 1 = /dev/cpu/1/msr MSRs on CPU 1 + ... + + 202 block Xen Virtual Block Device + 0 = /dev/xvda First Xen VBD whole disk + 16 = /dev/xvdb Second Xen VBD whole disk + 32 = /dev/xvdc Third Xen VBD whole disk + ... + 240 = /dev/xvdp Sixteenth Xen VBD whole disk + + Partitions are handled in the same way as for IDE + disks (see major number 3) except that the limit on + partitions is 15. + + 203 char CPU CPUID information + 0 = /dev/cpu/0/cpuid CPUID on CPU 0 + 1 = /dev/cpu/1/cpuid CPUID on CPU 1 + ... + + 204 char Low-density serial ports + 0 = /dev/ttyLU0 LinkUp Systems L72xx UART - port 0 + 1 = /dev/ttyLU1 LinkUp Systems L72xx UART - port 1 + 2 = /dev/ttyLU2 LinkUp Systems L72xx UART - port 2 + 3 = /dev/ttyLU3 LinkUp Systems L72xx UART - port 3 + 4 = /dev/ttyFB0 Intel Footbridge (ARM) + 5 = /dev/ttySA0 StrongARM builtin serial port 0 + 6 = /dev/ttySA1 StrongARM builtin serial port 1 + 7 = /dev/ttySA2 StrongARM builtin serial port 2 + 8 = /dev/ttySC0 SCI serial port (SuperH) - port 0 + 9 = /dev/ttySC1 SCI serial port (SuperH) - port 1 + 10 = /dev/ttySC2 SCI serial port (SuperH) - port 2 + 11 = /dev/ttySC3 SCI serial port (SuperH) - port 3 + 12 = /dev/ttyFW0 Firmware console - port 0 + 13 = /dev/ttyFW1 Firmware console - port 1 + 14 = /dev/ttyFW2 Firmware console - port 2 + 15 = /dev/ttyFW3 Firmware console - port 3 + 16 = /dev/ttyAM0 ARM "AMBA" serial port 0 + ... + 31 = /dev/ttyAM15 ARM "AMBA" serial port 15 + 32 = /dev/ttyDB0 DataBooster serial port 0 + ... + 39 = /dev/ttyDB7 DataBooster serial port 7 + 40 = /dev/ttySG0 SGI Altix console port + 41 = /dev/ttySMX0 Motorola i.MX - port 0 + 42 = /dev/ttySMX1 Motorola i.MX - port 1 + 43 = /dev/ttySMX2 Motorola i.MX - port 2 + 44 = /dev/ttyMM0 Marvell MPSC - port 0 + 45 = /dev/ttyMM1 Marvell MPSC - port 1 + 46 = /dev/ttyCPM0 PPC CPM (SCC or SMC) - port 0 + ... + 47 = /dev/ttyCPM5 PPC CPM (SCC or SMC) - port 5 + 50 = /dev/ttyIOC0 Altix serial card + ... + 81 = /dev/ttyIOC31 Altix serial card + 82 = /dev/ttyVR0 NEC VR4100 series SIU + 83 = /dev/ttyVR1 NEC VR4100 series DSIU + 84 = /dev/ttyIOC84 Altix ioc4 serial card + ... + 115 = /dev/ttyIOC115 Altix ioc4 serial card + 116 = /dev/ttySIOC0 Altix ioc3 serial card + ... + 147 = /dev/ttySIOC31 Altix ioc3 serial card + 148 = /dev/ttyPSC0 PPC PSC - port 0 + ... + 153 = /dev/ttyPSC5 PPC PSC - port 5 + 154 = /dev/ttyAT0 ATMEL serial port 0 + ... + 169 = /dev/ttyAT15 ATMEL serial port 15 + 170 = /dev/ttyNX0 Hilscher netX serial port 0 + ... + 185 = /dev/ttyNX15 Hilscher netX serial port 15 + 186 = /dev/ttyJ0 JTAG1 DCC protocol based serial port emulation + 187 = /dev/ttyUL0 Xilinx uartlite - port 0 + ... + 190 = /dev/ttyUL3 Xilinx uartlite - port 3 + 191 = /dev/xvc0 Xen virtual console - port 0 + 192 = /dev/ttyPZ0 pmac_zilog - port 0 + ... + 195 = /dev/ttyPZ3 pmac_zilog - port 3 + 196 = /dev/ttyTX0 TX39/49 serial port 0 + ... + 204 = /dev/ttyTX7 TX39/49 serial port 7 + 205 = /dev/ttySC0 SC26xx serial port 0 + 206 = /dev/ttySC1 SC26xx serial port 1 + 207 = /dev/ttySC2 SC26xx serial port 2 + 208 = /dev/ttySC3 SC26xx serial port 3 + 209 = /dev/ttyMAX0 MAX3100 serial port 0 + 210 = /dev/ttyMAX1 MAX3100 serial port 1 + 211 = /dev/ttyMAX2 MAX3100 serial port 2 + 212 = /dev/ttyMAX3 MAX3100 serial port 3 + + 205 char Low-density serial ports (alternate device) + 0 = /dev/culu0 Callout device for ttyLU0 + 1 = /dev/culu1 Callout device for ttyLU1 + 2 = /dev/culu2 Callout device for ttyLU2 + 3 = /dev/culu3 Callout device for ttyLU3 + 4 = /dev/cufb0 Callout device for ttyFB0 + 5 = /dev/cusa0 Callout device for ttySA0 + 6 = /dev/cusa1 Callout device for ttySA1 + 7 = /dev/cusa2 Callout device for ttySA2 + 8 = /dev/cusc0 Callout device for ttySC0 + 9 = /dev/cusc1 Callout device for ttySC1 + 10 = /dev/cusc2 Callout device for ttySC2 + 11 = /dev/cusc3 Callout device for ttySC3 + 12 = /dev/cufw0 Callout device for ttyFW0 + 13 = /dev/cufw1 Callout device for ttyFW1 + 14 = /dev/cufw2 Callout device for ttyFW2 + 15 = /dev/cufw3 Callout device for ttyFW3 + 16 = /dev/cuam0 Callout device for ttyAM0 + ... + 31 = /dev/cuam15 Callout device for ttyAM15 + 32 = /dev/cudb0 Callout device for ttyDB0 + ... + 39 = /dev/cudb7 Callout device for ttyDB7 + 40 = /dev/cusg0 Callout device for ttySG0 + 41 = /dev/ttycusmx0 Callout device for ttySMX0 + 42 = /dev/ttycusmx1 Callout device for ttySMX1 + 43 = /dev/ttycusmx2 Callout device for ttySMX2 + 46 = /dev/cucpm0 Callout device for ttyCPM0 + ... + 49 = /dev/cucpm5 Callout device for ttyCPM5 + 50 = /dev/cuioc40 Callout device for ttyIOC40 + ... + 81 = /dev/cuioc431 Callout device for ttyIOC431 + 82 = /dev/cuvr0 Callout device for ttyVR0 + 83 = /dev/cuvr1 Callout device for ttyVR1 + + 206 char OnStream SC-x0 tape devices + 0 = /dev/osst0 First OnStream SCSI tape, mode 0 + 1 = /dev/osst1 Second OnStream SCSI tape, mode 0 + ... + 32 = /dev/osst0l First OnStream SCSI tape, mode 1 + 33 = /dev/osst1l Second OnStream SCSI tape, mode 1 + ... + 64 = /dev/osst0m First OnStream SCSI tape, mode 2 + 65 = /dev/osst1m Second OnStream SCSI tape, mode 2 + ... + 96 = /dev/osst0a First OnStream SCSI tape, mode 3 + 97 = /dev/osst1a Second OnStream SCSI tape, mode 3 + ... + 128 = /dev/nosst0 No rewind version of /dev/osst0 + 129 = /dev/nosst1 No rewind version of /dev/osst1 + ... + 160 = /dev/nosst0l No rewind version of /dev/osst0l + 161 = /dev/nosst1l No rewind version of /dev/osst1l + ... + 192 = /dev/nosst0m No rewind version of /dev/osst0m + 193 = /dev/nosst1m No rewind version of /dev/osst1m + ... + 224 = /dev/nosst0a No rewind version of /dev/osst0a + 225 = /dev/nosst1a No rewind version of /dev/osst1a + ... + + The OnStream SC-x0 SCSI tapes do not support the + standard SCSI SASD command set and therefore need + their own driver "osst". Note that the IDE, USB (and + maybe ParPort) versions may be driven via ide-scsi or + usb-storage SCSI emulation and this osst device and + driver as well. The ADR-x0 drives are QIC-157 + compliant and don't need osst. + + 207 char Compaq ProLiant health feature indicate + 0 = /dev/cpqhealth/cpqw Redirector interface + 1 = /dev/cpqhealth/crom EISA CROM + 2 = /dev/cpqhealth/cdt Data Table + 3 = /dev/cpqhealth/cevt Event Log + 4 = /dev/cpqhealth/casr Automatic Server Recovery + 5 = /dev/cpqhealth/cecc ECC Memory + 6 = /dev/cpqhealth/cmca Machine Check Architecture + 7 = /dev/cpqhealth/ccsm Deprecated CDT + 8 = /dev/cpqhealth/cnmi NMI Handling + 9 = /dev/cpqhealth/css Sideshow Management + 10 = /dev/cpqhealth/cram CMOS interface + 11 = /dev/cpqhealth/cpci PCI IRQ interface + + 208 char User space serial ports + 0 = /dev/ttyU0 First user space serial port + 1 = /dev/ttyU1 Second user space serial port + ... + + 209 char User space serial ports (alternate devices) + 0 = /dev/cuu0 Callout device for ttyU0 + 1 = /dev/cuu1 Callout device for ttyU1 + ... + + 210 char SBE, Inc. sync/async serial card + 0 = /dev/sbei/wxcfg0 Configuration device for board 0 + 1 = /dev/sbei/dld0 Download device for board 0 + 2 = /dev/sbei/wan00 WAN device, port 0, board 0 + 3 = /dev/sbei/wan01 WAN device, port 1, board 0 + 4 = /dev/sbei/wan02 WAN device, port 2, board 0 + 5 = /dev/sbei/wan03 WAN device, port 3, board 0 + 6 = /dev/sbei/wanc00 WAN clone device, port 0, board 0 + 7 = /dev/sbei/wanc01 WAN clone device, port 1, board 0 + 8 = /dev/sbei/wanc02 WAN clone device, port 2, board 0 + 9 = /dev/sbei/wanc03 WAN clone device, port 3, board 0 + 10 = /dev/sbei/wxcfg1 Configuration device for board 1 + 11 = /dev/sbei/dld1 Download device for board 1 + 12 = /dev/sbei/wan10 WAN device, port 0, board 1 + 13 = /dev/sbei/wan11 WAN device, port 1, board 1 + 14 = /dev/sbei/wan12 WAN device, port 2, board 1 + 15 = /dev/sbei/wan13 WAN device, port 3, board 1 + 16 = /dev/sbei/wanc10 WAN clone device, port 0, board 1 + 17 = /dev/sbei/wanc11 WAN clone device, port 1, board 1 + 18 = /dev/sbei/wanc12 WAN clone device, port 2, board 1 + 19 = /dev/sbei/wanc13 WAN clone device, port 3, board 1 + ... + + Yes, each board is really spaced 10 (decimal) apart. + + 211 char Addinum CPCI1500 digital I/O card + 0 = /dev/addinum/cpci1500/0 First CPCI1500 card + 1 = /dev/addinum/cpci1500/1 Second CPCI1500 card + ... + + 212 char LinuxTV.org DVB driver subsystem + 0 = /dev/dvb/adapter0/video0 first video decoder of first card + 1 = /dev/dvb/adapter0/audio0 first audio decoder of first card + 2 = /dev/dvb/adapter0/sec0 (obsolete/unused) + 3 = /dev/dvb/adapter0/frontend0 first frontend device of first card + 4 = /dev/dvb/adapter0/demux0 first demux device of first card + 5 = /dev/dvb/adapter0/dvr0 first digital video recoder device of first card + 6 = /dev/dvb/adapter0/ca0 first common access port of first card + 7 = /dev/dvb/adapter0/net0 first network device of first card + 8 = /dev/dvb/adapter0/osd0 first on-screen-display device of first card + 9 = /dev/dvb/adapter0/video1 second video decoder of first card + ... + 64 = /dev/dvb/adapter1/video0 first video decoder of second card + ... + 128 = /dev/dvb/adapter2/video0 first video decoder of third card + ... + 196 = /dev/dvb/adapter3/video0 first video decoder of fourth card + + 216 char Bluetooth RFCOMM TTY devices + 0 = /dev/rfcomm0 First Bluetooth RFCOMM TTY device + 1 = /dev/rfcomm1 Second Bluetooth RFCOMM TTY device + ... + + 217 char Bluetooth RFCOMM TTY devices (alternate devices) + 0 = /dev/curf0 Callout device for rfcomm0 + 1 = /dev/curf1 Callout device for rfcomm1 + ... + + 218 char The Logical Company bus Unibus/Qbus adapters + 0 = /dev/logicalco/bci/0 First bus adapter + 1 = /dev/logicalco/bci/1 First bus adapter + ... + + 219 char The Logical Company DCI-1300 digital I/O card + 0 = /dev/logicalco/dci1300/0 First DCI-1300 card + 1 = /dev/logicalco/dci1300/1 Second DCI-1300 card + ... + + 220 char Myricom Myrinet "GM" board + 0 = /dev/myricom/gm0 First Myrinet GM board + 1 = /dev/myricom/gmp0 First board "root access" + 2 = /dev/myricom/gm1 Second Myrinet GM board + 3 = /dev/myricom/gmp1 Second board "root access" + ... + + 221 char VME bus + 0 = /dev/bus/vme/m0 First master image + 1 = /dev/bus/vme/m1 Second master image + 2 = /dev/bus/vme/m2 Third master image + 3 = /dev/bus/vme/m3 Fourth master image + 4 = /dev/bus/vme/s0 First slave image + 5 = /dev/bus/vme/s1 Second slave image + 6 = /dev/bus/vme/s2 Third slave image + 7 = /dev/bus/vme/s3 Fourth slave image + 8 = /dev/bus/vme/ctl Control + + It is expected that all VME bus drivers will use the + same interface. For interface documentation see + http://www.vmelinux.org/. + + 224 char A2232 serial card + 0 = /dev/ttyY0 First A2232 port + 1 = /dev/ttyY1 Second A2232 port + ... + + 225 char A2232 serial card (alternate devices) + 0 = /dev/cuy0 Callout device for ttyY0 + 1 = /dev/cuy1 Callout device for ttyY1 + ... + + 226 char Direct Rendering Infrastructure (DRI) + 0 = /dev/dri/card0 First graphics card + 1 = /dev/dri/card1 Second graphics card + ... + + 227 char IBM 3270 terminal Unix tty access + 1 = /dev/3270/tty1 First 3270 terminal + 2 = /dev/3270/tty2 Seconds 3270 terminal + ... + + 228 char IBM 3270 terminal block-mode access + 0 = /dev/3270/tub Controlling interface + 1 = /dev/3270/tub1 First 3270 terminal + 2 = /dev/3270/tub2 Second 3270 terminal + ... + + 229 char IBM iSeries/pSeries virtual console + 0 = /dev/hvc0 First console port + 1 = /dev/hvc1 Second console port + ... + + 230 char IBM iSeries virtual tape + 0 = /dev/iseries/vt0 First virtual tape, mode 0 + 1 = /dev/iseries/vt1 Second virtual tape, mode 0 + ... + 32 = /dev/iseries/vt0l First virtual tape, mode 1 + 33 = /dev/iseries/vt1l Second virtual tape, mode 1 + ... + 64 = /dev/iseries/vt0m First virtual tape, mode 2 + 65 = /dev/iseries/vt1m Second virtual tape, mode 2 + ... + 96 = /dev/iseries/vt0a First virtual tape, mode 3 + 97 = /dev/iseries/vt1a Second virtual tape, mode 3 + ... + 128 = /dev/iseries/nvt0 First virtual tape, mode 0, no rewind + 129 = /dev/iseries/nvt1 Second virtual tape, mode 0, no rewind + ... + 160 = /dev/iseries/nvt0l First virtual tape, mode 1, no rewind + 161 = /dev/iseries/nvt1l Second virtual tape, mode 1, no rewind + ... + 192 = /dev/iseries/nvt0m First virtual tape, mode 2, no rewind + 193 = /dev/iseries/nvt1m Second virtual tape, mode 2, no rewind + ... + 224 = /dev/iseries/nvt0a First virtual tape, mode 3, no rewind + 225 = /dev/iseries/nvt1a Second virtual tape, mode 3, no rewind + ... + + "No rewind" refers to the omission of the default + automatic rewind on device close. The MTREW or MTOFFL + ioctl()'s can be used to rewind the tape regardless of + the device used to access it. + + 231 char InfiniBand + 0 = /dev/infiniband/umad0 + 1 = /dev/infiniband/umad1 + ... + 63 = /dev/infiniband/umad63 63rd InfiniBandMad device + 64 = /dev/infiniband/issm0 First InfiniBand IsSM device + 65 = /dev/infiniband/issm1 Second InfiniBand IsSM device + ... + 127 = /dev/infiniband/issm63 63rd InfiniBand IsSM device + 128 = /dev/infiniband/uverbs0 First InfiniBand verbs device + 129 = /dev/infiniband/uverbs1 Second InfiniBand verbs device + ... + 159 = /dev/infiniband/uverbs31 31st InfiniBand verbs device + + 232 char Biometric Devices + 0 = /dev/biometric/sensor0/fingerprint first fingerprint sensor on first device + 1 = /dev/biometric/sensor0/iris first iris sensor on first device + 2 = /dev/biometric/sensor0/retina first retina sensor on first device + 3 = /dev/biometric/sensor0/voiceprint first voiceprint sensor on first device + 4 = /dev/biometric/sensor0/facial first facial sensor on first device + 5 = /dev/biometric/sensor0/hand first hand sensor on first device + ... + 10 = /dev/biometric/sensor1/fingerprint first fingerprint sensor on second device + ... + 20 = /dev/biometric/sensor2/fingerprint first fingerprint sensor on third device + ... + + 233 char PathScale InfiniPath interconnect + 0 = /dev/ipath Primary device for programs (any unit) + 1 = /dev/ipath0 Access specifically to unit 0 + 2 = /dev/ipath1 Access specifically to unit 1 + ... + 4 = /dev/ipath3 Access specifically to unit 3 + 129 = /dev/ipath_sma Device used by Subnet Management Agent + 130 = /dev/ipath_diag Device used by diagnostics programs + + 234-254 char RESERVED FOR DYNAMIC ASSIGNMENT + Character devices that request a dynamic allocation of major number will + take numbers starting from 254 and downward. + + 240-254 block LOCAL/EXPERIMENTAL USE + Allocated for local/experimental use. For devices not + assigned official numbers, these ranges should be + used in order to avoid conflicting with future assignments. + + 255 char RESERVED + + 255 block RESERVED + + This major is reserved to assist the expansion to a + larger number space. No device nodes with this major + should ever be created on the filesystem. + (This is probably not true anymore, but I'll leave it + for now /Torben) + + ---LARGE MAJORS!!!!!--- + + 256 char Equinox SST multi-port serial boards + 0 = /dev/ttyEQ0 First serial port on first Equinox SST board + 127 = /dev/ttyEQ127 Last serial port on first Equinox SST board + 128 = /dev/ttyEQ128 First serial port on second Equinox SST board + ... + 1027 = /dev/ttyEQ1027 Last serial port on eighth Equinox SST board + + 256 block Resident Flash Disk Flash Translation Layer + 0 = /dev/rfda First RFD FTL layer + 16 = /dev/rfdb Second RFD FTL layer + ... + 240 = /dev/rfdp 16th RFD FTL layer + + 257 char Phoenix Technologies Cryptographic Services Driver + 0 = /dev/ptlsec Crypto Services Driver + + 257 block SSFDC Flash Translation Layer filesystem + 0 = /dev/ssfdca First SSFDC layer + 8 = /dev/ssfdcb Second SSFDC layer + 16 = /dev/ssfdcc Third SSFDC layer + 24 = /dev/ssfdcd 4th SSFDC layer + 32 = /dev/ssfdce 5th SSFDC layer + 40 = /dev/ssfdcf 6th SSFDC layer + 48 = /dev/ssfdcg 7th SSFDC layer + 56 = /dev/ssfdch 8th SSFDC layer + + 258 block ROM/Flash read-only translation layer + 0 = /dev/blockrom0 First ROM card's translation layer interface + 1 = /dev/blockrom1 Second ROM card's translation layer interface + ... + + 259 block Block Extended Major + Used dynamically to hold additional partition minor + numbers and allow large numbers of partitions per device + + 259 char FPGA configuration interfaces + 0 = /dev/icap0 First Xilinx internal configuration + 1 = /dev/icap1 Second Xilinx internal configuration + + 260 char OSD (Object-based-device) SCSI Device + 0 = /dev/osd0 First OSD Device + 1 = /dev/osd1 Second OSD Device + ... + 255 = /dev/osd255 256th OSD Device + + +Additional ``/dev/`` directory entries +-------------------------------------- + +This section details additional entries that should or may exist in +the /dev directory. It is preferred that symbolic links use the same +form (absolute or relative) as is indicated here. Links are +classified as "hard" or "symbolic" depending on the preferred type of +link; if possible, the indicated type of link should be used. + +Compulsory links +++++++++++++++++ + +These links should exist on all systems: + +=============== =============== =============== =============================== +/dev/fd /proc/self/fd symbolic File descriptors +/dev/stdin fd/0 symbolic stdin file descriptor +/dev/stdout fd/1 symbolic stdout file descriptor +/dev/stderr fd/2 symbolic stderr file descriptor +/dev/nfsd socksys symbolic Required by iBCS-2 +/dev/X0R null symbolic Required by iBCS-2 +=============== =============== =============== =============================== + +Note: ``/dev/X0R`` is --. + +Recommended links ++++++++++++++++++ + +It is recommended that these links exist on all systems: + + +=============== =============== =============== =============================== +/dev/core /proc/kcore symbolic Backward compatibility +/dev/ramdisk ram0 symbolic Backward compatibility +/dev/ftape qft0 symbolic Backward compatibility +/dev/bttv0 video0 symbolic Backward compatibility +/dev/radio radio0 symbolic Backward compatibility +/dev/i2o* /dev/i2o/* symbolic Backward compatibility +/dev/scd? sr? hard Alternate SCSI CD-ROM name +=============== =============== =============== =============================== + +Locally defined links ++++++++++++++++++++++ + +The following links may be established locally to conform to the +configuration of the system. This is merely a tabulation of existing +practice, and does not constitute a recommendation. However, if they +exist, they should have the following uses. + +=============== =============== =============== =============================== +/dev/mouse mouse port symbolic Current mouse device +/dev/tape tape device symbolic Current tape device +/dev/cdrom CD-ROM device symbolic Current CD-ROM device +/dev/cdwriter CD-writer symbolic Current CD-writer device +/dev/scanner scanner symbolic Current scanner device +/dev/modem modem port symbolic Current dialout device +/dev/root root device symbolic Current root filesystem +/dev/swap swap device symbolic Current swap device +=============== =============== =============== =============================== + +``/dev/modem`` should not be used for a modem which supports dialin as +well as dialout, as it tends to cause lock file problems. If it +exists, ``/dev/modem`` should point to the appropriate primary TTY device +(the use of the alternate callout devices is deprecated). + +For SCSI devices, ``/dev/tape`` and ``/dev/cdrom`` should point to the +*cooked* devices (``/dev/st*`` and ``/dev/sr*``, respectively), whereas +``/dev/cdwriter`` and /dev/scanner should point to the appropriate generic +SCSI devices (/dev/sg*). + +``/dev/mouse`` may point to a primary serial TTY device, a hardware mouse +device, or a socket for a mouse driver program (e.g. ``/dev/gpmdata``). + +Sockets and pipes ++++++++++++++++++ + +Non-transient sockets and named pipes may exist in /dev. Common entries are: + +=============== =============== =============================================== +/dev/printer socket lpd local socket +/dev/log socket syslog local socket +/dev/gpmdata socket gpm mouse multiplexer +=============== =============== =============================================== + +Mount points +++++++++++++ + +The following names are reserved for mounting special filesystems +under /dev. These special filesystems provide kernel interfaces that +cannot be provided with standard device nodes. + +=============== =============== =============================================== +/dev/pts devpts PTY slave filesystem +/dev/shm tmpfs POSIX shared memory maintenance access +=============== =============== =============================================== + +Terminal devices +---------------- + +Terminal, or TTY devices are a special class of character devices. A +terminal device is any device that could act as a controlling terminal +for a session; this includes virtual consoles, serial ports, and +pseudoterminals (PTYs). + +All terminal devices share a common set of capabilities known as line +disciplines; these include the common terminal line discipline as well +as SLIP and PPP modes. + +All terminal devices are named similarly; this section explains the +naming and use of the various types of TTYs. Note that the naming +conventions include several historical warts; some of these are +Linux-specific, some were inherited from other systems, and some +reflect Linux outgrowing a borrowed convention. + +A hash mark (``#``) in a device name is used here to indicate a decimal +number without leading zeroes. + +Virtual consoles and the console device ++++++++++++++++++++++++++++++++++++++++ + +Virtual consoles are full-screen terminal displays on the system video +monitor. Virtual consoles are named ``/dev/tty#``, with numbering +starting at ``/dev/tty1``; ``/dev/tty0`` is the current virtual console. +``/dev/tty0`` is the device that should be used to access the system video +card on those architectures for which the frame buffer devices +(``/dev/fb*``) are not applicable. Do not use ``/dev/console`` +for this purpose. + +The console device, ``/dev/console``, is the device to which system +messages should be sent, and on which logins should be permitted in +single-user mode. Starting with Linux 2.1.71, ``/dev/console`` is managed +by the kernel; for previous versions it should be a symbolic link to +either ``/dev/tty0``, a specific virtual console such as ``/dev/tty1``, or to +a serial port primary (``tty*``, not ``cu*``) device, depending on the +configuration of the system. + +Serial ports +++++++++++++ + +Serial ports are RS-232 serial ports and any device which simulates +one, either in hardware (such as internal modems) or in software (such +as the ISDN driver.) Under Linux, each serial ports has two device +names, the primary or callin device and the alternate or callout one. +Each kind of device is indicated by a different letter. For any +letter X, the names of the devices are ``/dev/ttyX#`` and ``/dev/cux#``, +respectively; for historical reasons, ``/dev/ttyS#`` and ``/dev/ttyC#`` +correspond to ``/dev/cua#`` and ``/dev/cub#``. In the future, it should be +expected that multiple letters will be used; all letters will be upper +case for the "tty" device (e.g. ``/dev/ttyDP#``) and lower case for the +"cu" device (e.g. ``/dev/cudp#``). + +The names ``/dev/ttyQ#`` and ``/dev/cuq#`` are reserved for local use. + +The alternate devices provide for kernel-based exclusion and somewhat +different defaults than the primary devices. Their main purpose is to +allow the use of serial ports with programs with no inherent or broken +support for serial ports. Their use is deprecated, and they may be +removed from a future version of Linux. + +Arbitration of serial ports is provided by the use of lock files with +the names ``/var/lock/LCK..ttyX#``. The contents of the lock file should +be the PID of the locking process as an ASCII number. + +It is common practice to install links such as /dev/modem +which point to serial ports. In order to ensure proper locking in the +presence of these links, it is recommended that software chase +symlinks and lock all possible names; additionally, it is recommended +that a lock file be installed with the corresponding alternate +device. In order to avoid deadlocks, it is recommended that the locks +are acquired in the following order, and released in the reverse: + + 1. The symbolic link name, if any (``/var/lock/LCK..modem``) + 2. The "tty" name (``/var/lock/LCK..ttyS2``) + 3. The alternate device name (``/var/lock/LCK..cua2``) + +In the case of nested symbolic links, the lock files should be +installed in the order the symlinks are resolved. + +Under no circumstances should an application hold a lock while waiting +for another to be released. In addition, applications which attempt +to create lock files for the corresponding alternate device names +should take into account the possibility of being used on a non-serial +port TTY, for which no alternate device would exist. + +Pseudoterminals (PTYs) +++++++++++++++++++++++ + +Pseudoterminals, or PTYs, are used to create login sessions or provide +other capabilities requiring a TTY line discipline (including SLIP or +PPP capability) to arbitrary data-generation processes. Each PTY has +a master side, named ``/dev/pty[p-za-e][0-9a-f]``, and a slave side, named +``/dev/tty[p-za-e][0-9a-f]``. The kernel arbitrates the use of PTYs by +allowing each master side to be opened only once. + +Once the master side has been opened, the corresponding slave device +can be used in the same manner as any TTY device. The master and +slave devices are connected by the kernel, generating the equivalent +of a bidirectional pipe with TTY capabilities. + +Recent versions of the Linux kernels and GNU libc contain support for +the System V/Unix98 naming scheme for PTYs, which assigns a common +device, ``/dev/ptmx``, to all the masters (opening it will automatically +give you a previously unassigned PTY) and a subdirectory, ``/dev/pts``, +for the slaves; the slaves are named with decimal integers (``/dev/pts/#`` +in our notation). This removes the problem of exhausting the +namespace and enables the kernel to automatically create the device +nodes for the slaves on demand using the "devpts" filesystem. diff --git a/Documentation/admin-guide/dynamic-debug-howto.rst b/Documentation/admin-guide/dynamic-debug-howto.rst new file mode 100644 index 000000000000..88adcfdf5b2b --- /dev/null +++ b/Documentation/admin-guide/dynamic-debug-howto.rst @@ -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: ``/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: +``/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' > + /dynamic_debug/control + +If you make a mistake with the syntax, the write will fail thus:: + + nullarbor:~ # echo 'file svcsock.c wtf 1 +p' > + /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 /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 /dynamic_debug/control | wc -l + 62 + + nullarbor:~ # grep -i tcp /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 != "=_"' /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' > + /dynamic_debug/control + nullarbor:~ # echo -c ' file svcsock.c line 1603 +p ' > + /dynamic_debug/control + nullarbor:~ # echo -n 'file svcsock.c line 1603 +p' > + /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" \ + > /dynamic_debug/control + +If your query set is big, you can batch them too:: + + ~# cat query-batch-file > /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" > /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" > /dynamic_debug/control + +Examples +======== + +:: + + // enable the message at line 1603 of file svcsock.c + nullarbor:~ # echo -n 'file svcsock.c line 1603 +p' > + /dynamic_debug/control + + // enable all the messages in file svcsock.c + nullarbor:~ # echo -n 'file svcsock.c +p' > + /dynamic_debug/control + + // enable all the messages in the NFS server module + nullarbor:~ # echo -n 'module nfsd +p' > + /dynamic_debug/control + + // enable all 12 messages in the function svc_process() + nullarbor:~ # echo -n 'func svc_process +p' > + /dynamic_debug/control + + // disable all 12 messages in the function svc_process() + nullarbor:~ # echo -n 'func svc_process -p' > + /dynamic_debug/control + + // enable messages for NFS calls READ, READLINK, READDIR and READDIR+. + nullarbor:~ # echo -n 'format "nfsd: READ" +p' > + /dynamic_debug/control + + // enable messages in files of which the paths include string "usb" + nullarbor:~ # echo -n '*usb* +p' > /dynamic_debug/control + + // enable all messages + nullarbor:~ # echo -n '+p' > /dynamic_debug/control + + // add module, function to all enabled messages + nullarbor:~ # echo -n '+mf' > /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" diff --git a/Documentation/admin-guide/index.rst b/Documentation/admin-guide/index.rst new file mode 100644 index 000000000000..4e5abbb4bbd5 --- /dev/null +++ b/Documentation/admin-guide/index.rst @@ -0,0 +1,34 @@ +Linux Kernel User's Documentation +================================= + +Contents: + +.. toctree:: + :maxdepth: 2 + :numbered: + + README + reporting-bugs + bug-hunting + oops-tracing + ramoops + initrd + init + dynamic-debug-howto + security-bugs + kernel-parameters + serial-console + braille-console + parport + md + module-signing + sysrq + unicode + vga-softcursor + sysfs-rules + devices + binfmt-misc + mono + java + bad-memory + basic-profiling diff --git a/Documentation/admin-guide/init.rst b/Documentation/admin-guide/init.rst new file mode 100644 index 000000000000..e89d97f31eaf --- /dev/null +++ b/Documentation/admin-guide/init.rst @@ -0,0 +1,52 @@ +Explaining the dreaded "No init found." boot hang message +========================================================= + +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 +D) binary exists but dependencies not available +E) binary cannot be loaded + +Detailed explanations: + +A) Set "debug" kernel parameter (in bootloader config file or CONFIG_CMDLINE) + to get more detailed kernel messages. +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. + 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=``. +D) e.g. required library dependencies of the init binary such as + ``/lib/ld-linux.so.2`` missing or broken. Use + ``readelf -d |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 + 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 + 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). +- try to make the implementation itself more helpful in general, + e.g. by providing additional error messages at affected places. + +Andreas Mohr diff --git a/Documentation/admin-guide/initrd.rst b/Documentation/admin-guide/initrd.rst new file mode 100644 index 000000000000..a03dabaaf3a3 --- /dev/null +++ b/Documentation/admin-guide/initrd.rst @@ -0,0 +1,383 @@ +Using the initial RAM disk (initrd) +=================================== + +Written 1996,2000 by Werner Almesberger and +Hans Lermen + + +initrd provides the capability to load a RAM disk by the boot loader. +This RAM disk can then be mounted as the root file system and programs +can be run from it. Afterwards, a new root file system can be mounted +from a different device. The previous root (from initrd) is then moved +to a directory and can be subsequently unmounted. + +initrd is mainly designed to allow system startup to occur in two phases, +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 [#f1]_. + + +Operation +--------- + +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) + 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 + 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 + init can do). + 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 + the usual boot sequence + 9) the initrd file system is removed + +Note that changing the root directory does not involve unmounting it. +It is therefore possible to leave processes running on initrd during that +procedure. Also note that file systems mounted under initrd continue to +be accessible. + + +Boot command-line options +------------------------- + +initrd adds the following new options:: + + initrd= (e.g. LOADLIN) + + Loads the specified file as the initial RAM disk. When using LILO, you + have to specify the RAM disk image file in /etc/lilo.conf, using the + INITRD configuration variable. + + noinitrd + + initrd data is preserved but it is not converted to a RAM disk and + the "normal" root file system is mounted. initrd data can be read + from /dev/initrd. Note that the data in initrd can have any structure + in this case and doesn't necessarily have to be a file system image. + This option is used mainly for debugging. + + Note: /dev/initrd is read-only and it can only be used once. As soon + as the last process has closed it, all data is freed and /dev/initrd + can't be opened anymore. + + root=/dev/ram0 + + initrd is mounted as root, and the normal boot procedure is followed, + with the RAM disk mounted as root. + +Compressed cpio images +---------------------- + +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):: + + find . | cpio --quiet -H newc -o | gzip -9 -n > /boot/imagefile.img + +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 + +Installation +------------ + +First, a directory for the initrd file system has to be created on the +"normal" root file system, e.g.:: + + # mkdir /initrd + +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. + +If initrd will not be mounted in some cases, its content is still +accessible if the following device has been created:: + + # 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 +needed to execute programs from initrd (e.g. executable format and file +system) must be compiled into the kernel. + +Third, you have to create the RAM disk image. This is done by creating a +file system on a block device, copying files to it as needed, and then +copying the content of the block device to the initrd file. With recent +kernels, at least three types of devices are suitable for that: + + - a floppy disk (works everywhere but it's painfully slow) + - a RAM disk (fast, but allocates physical memory) + - a loopback device (the most elegant solution) + +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 + + (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:: + + # 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:: ``/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 + + 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 + + 8) the initrd is now in the file "initrd". Optionally, it can now be + 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 [#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:: + + root=/dev/ram0 rw + +(rw is only necessary if writing to the initrd file system.) + +With LOADLIN, you simply execute:: + + LOADLIN initrd= + +e.g.:: + + LOADLIN C:\LINUX\BZIMAGE initrd=C:\LINUX\INITRD.GZ root=/dev/ram0 rw + +With LILO, you add the option ``INITRD=`` 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`` + +For other boot loaders, please refer to the respective documentation. + +Now you can boot and enjoy using initrd. + + +Changing the root device +------------------------ + +When finished with its duties, init typically changes the root device +and proceeds with starting the Linux system on the "real" root device. + +The procedure involves the following steps: + - mounting the new root file system + - turning it into the root file system + - removing all accesses to the old (initrd) root file system + - 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:: + + # 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 :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:: + + # 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:: + + # exec chroot . what-follows dev/console 2>&1 + +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``. + +Note: implementation details of pivot_root may change with time. In order +to ensure compatibility, the following points should be observed: + + - before calling pivot_root, the current directory of the invoking + process should point to the new root directory + - use . as the first argument, and the _relative_ path of the directory + for the old root as the second argument + - a chroot program must be available under the old and the new root + - chroot to the new root afterwards + - 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:: + + # umount /initrd + # blockdev --flushbufs /dev/ram0 + +It is also possible to use initrd with an NFS-mounted root, see the +:manpage:`pivot_root(8)` man page for details. + + +Usage scenarios +--------------- + +The main motivation for implementing initrd was to allow for modular +kernel configuration at system installation. The procedure would work +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 + (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 + have to be a very usable system yet) + 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 + modified, then unmounted, and finally, the image is written from + ``/dev/ram0`` or ``/dev/rd/0`` to a file) + 8) now the system is bootable and additional installation tasks can be + performed + +The key role of initrd here is to re-use the configuration data during +normal system operation without requiring the use of a bloated "generic" +kernel or re-compiling or re-linking the kernel. + +A second scenario is for installations where Linux runs on systems with +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 +read by it would have to be different. + +A third scenario is more convenient recovery disks, because information +like the location of the root FS partition doesn't have to be provided at +boot time, but the system loaded from initrd can invoke a user-friendly +dialog and it can also perform some sanity checks (or even some form of +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 +from the CD-ROM, and loading the RAM disk from CD without need of +floppies. + + +Obsolete root change mechanism +------------------------------ + +The following mechanism was used before the introduction of pivot_root. +Current kernels still support it, but you should _not_ rely on its +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 +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.:: + + # 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``. + + +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. + +``/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 + +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``. + + +Resources +--------- + +.. [#f1] Almesberger, Werner; "Booting Linux: The History and the Future" + http://www.almesberger.net/cv/papers/ols2k-9.ps.gz +.. [#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/ diff --git a/Documentation/admin-guide/java.rst b/Documentation/admin-guide/java.rst new file mode 100644 index 000000000000..a0de7c1a1ed9 --- /dev/null +++ b/Documentation/admin-guide/java.rst @@ -0,0 +1,417 @@ +Java(tm) Binary Kernel Support for Linux v1.03 +---------------------------------------------- + +Linux beats them ALL! While all other OS's are TALKING about direct +support of Java Binaries in the OS, Linux is doing it! + +You can execute Java applications and Java Applets just like any +other program after you have done the following: + +1) You MUST FIRST install the Java Developers Kit for Linux. + The Java on Linux HOWTO gives the details on getting and + installing this. This HOWTO can be found at: + + ftp://sunsite.unc.edu/pub/Linux/docs/HOWTO/Java-HOWTO + + You should also set up a reasonable CLASSPATH environment + variable to use Java applications that make use of any + nonstandard classes (not included in the same directory + as the application itself). + +2) You have to compile BINFMT_MISC either as a module or into + the kernel (``CONFIG_BINFMT_MISC``) and set it up properly. + If you choose to compile it as a module, you will have + to insert it manually with modprobe/insmod, as kmod + cannot easily be supported with binfmt_misc. + Read the file 'binfmt_misc.txt' in this directory to know + more about the configuration process. + +3) Add the following configuration items to binfmt_misc + (you should really have read ``binfmt_misc.txt`` now): + support for Java applications:: + + ':Java:M::\xca\xfe\xba\xbe::/usr/local/bin/javawrapper:' + + support for executable Jar files:: + + ':ExecutableJAR:E::jar::/usr/local/bin/jarwrapper:' + + support for Java Applets:: + + ':Applet:E::html::/usr/bin/appletviewer:' + + or the following, if you want to be more selective:: + + ':Applet:M::`` in the first line + (``<`` has to be the first character!) to let this work! + + For the compiled Java programs you need a wrapper script like the + following (this is because Java is broken in case of the filename + handling), again fix the path names, both in the script and in the + above given configuration string. + + You, too, need the little program after the script. Compile like:: + + gcc -O2 -o javaclassname javaclassname.c + + and stick it to ``/usr/local/bin``. + + Both the javawrapper shellscript and the javaclassname program + were supplied by Colin J. Watson . + +Javawrapper shell script:: + + #!/bin/bash + # /usr/local/bin/javawrapper - the wrapper for binfmt_misc/java + + if [ -z "$1" ]; then + exec 1>&2 + echo Usage: $0 class-file + exit 1 + fi + + CLASS=$1 + FQCLASS=`/usr/local/bin/javaclassname $1` + FQCLASSN=`echo $FQCLASS | sed -e 's/^.*\.\([^.]*\)$/\1/'` + FQCLASSP=`echo $FQCLASS | sed -e 's-\.-/-g' -e 's-^[^/]*$--' -e 's-/[^/]*$--'` + + # for example: + # CLASS=Test.class + # FQCLASS=foo.bar.Test + # FQCLASSN=Test + # FQCLASSP=foo/bar + + unset CLASSBASE + + declare -i LINKLEVEL=0 + + while :; do + if [ "`basename $CLASS .class`" == "$FQCLASSN" ]; then + # See if this directory works straight off + cd -L `dirname $CLASS` + CLASSDIR=$PWD + cd $OLDPWD + if echo $CLASSDIR | grep -q "$FQCLASSP$"; then + CLASSBASE=`echo $CLASSDIR | sed -e "s.$FQCLASSP$.."` + break; + fi + # Try dereferencing the directory name + cd -P `dirname $CLASS` + CLASSDIR=$PWD + cd $OLDPWD + if echo $CLASSDIR | grep -q "$FQCLASSP$"; then + CLASSBASE=`echo $CLASSDIR | sed -e "s.$FQCLASSP$.."` + break; + fi + # If no other possible filename exists + if [ ! -L $CLASS ]; then + exec 1>&2 + echo $0: + echo " $CLASS should be in a" \ + "directory tree called $FQCLASSP" + exit 1 + fi + fi + if [ ! -L $CLASS ]; then break; fi + # Go down one more level of symbolic links + let LINKLEVEL+=1 + if [ $LINKLEVEL -gt 5 ]; then + exec 1>&2 + echo $0: + echo " Too many symbolic links encountered" + exit 1 + fi + CLASS=`ls --color=no -l $CLASS | sed -e 's/^.* \([^ ]*\)$/\1/'` + done + + if [ -z "$CLASSBASE" ]; then + if [ -z "$FQCLASSP" ]; then + GOODNAME=$FQCLASSN.class + else + GOODNAME=$FQCLASSP/$FQCLASSN.class + fi + exec 1>&2 + echo $0: + echo " $FQCLASS should be in a file called $GOODNAME" + exit 1 + fi + + if ! echo $CLASSPATH | grep -q "^\(.*:\)*$CLASSBASE\(:.*\)*"; then + # class is not in CLASSPATH, so prepend dir of class to CLASSPATH + if [ -z "${CLASSPATH}" ] ; then + export CLASSPATH=$CLASSBASE + else + export CLASSPATH=$CLASSBASE:$CLASSPATH + fi + fi + + shift + /usr/bin/java $FQCLASS "$@" + +javaclassname.c:: + + /* javaclassname.c + * + * Extracts the class name from a Java class file; intended for use in a Java + * wrapper of the type supported by the binfmt_misc option in the Linux kernel. + * + * Copyright (C) 1999 Colin J. Watson . + * + * This program is free software; you can redistribute it and/or modify + * it under the terms of the GNU General Public License as published by + * the Free Software Foundation; either version 2 of the License, or + * (at your option) any later version. + * + * This program is distributed in the hope that it will be useful, + * but WITHOUT ANY WARRANTY; without even the implied warranty of + * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the + * GNU General Public License for more details. + * + * You should have received a copy of the GNU General Public License + * along with this program; if not, write to the Free Software + * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA + */ + + #include + #include + #include + #include + + /* From Sun's Java VM Specification, as tag entries in the constant pool. */ + + #define CP_UTF8 1 + #define CP_INTEGER 3 + #define CP_FLOAT 4 + #define CP_LONG 5 + #define CP_DOUBLE 6 + #define CP_CLASS 7 + #define CP_STRING 8 + #define CP_FIELDREF 9 + #define CP_METHODREF 10 + #define CP_INTERFACEMETHODREF 11 + #define CP_NAMEANDTYPE 12 + #define CP_METHODHANDLE 15 + #define CP_METHODTYPE 16 + #define CP_INVOKEDYNAMIC 18 + + /* Define some commonly used error messages */ + + #define seek_error() error("%s: Cannot seek\n", program) + #define corrupt_error() error("%s: Class file corrupt\n", program) + #define eof_error() error("%s: Unexpected end of file\n", program) + #define utf8_error() error("%s: Only ASCII 1-255 supported\n", program); + + char *program; + + long *pool; + + u_int8_t read_8(FILE *classfile); + u_int16_t read_16(FILE *classfile); + void skip_constant(FILE *classfile, u_int16_t *cur); + void error(const char *format, ...); + int main(int argc, char **argv); + + /* Reads in an unsigned 8-bit integer. */ + u_int8_t read_8(FILE *classfile) + { + int b = fgetc(classfile); + if(b == EOF) + eof_error(); + return (u_int8_t)b; + } + + /* Reads in an unsigned 16-bit integer. */ + u_int16_t read_16(FILE *classfile) + { + int b1, b2; + b1 = fgetc(classfile); + if(b1 == EOF) + eof_error(); + b2 = fgetc(classfile); + if(b2 == EOF) + eof_error(); + return (u_int16_t)((b1 << 8) | b2); + } + + /* Reads in a value from the constant pool. */ + void skip_constant(FILE *classfile, u_int16_t *cur) + { + u_int16_t len; + int seekerr = 1; + pool[*cur] = ftell(classfile); + switch(read_8(classfile)) + { + case CP_UTF8: + len = read_16(classfile); + seekerr = fseek(classfile, len, SEEK_CUR); + break; + case CP_CLASS: + case CP_STRING: + case CP_METHODTYPE: + seekerr = fseek(classfile, 2, SEEK_CUR); + break; + case CP_METHODHANDLE: + seekerr = fseek(classfile, 3, SEEK_CUR); + break; + case CP_INTEGER: + case CP_FLOAT: + case CP_FIELDREF: + case CP_METHODREF: + case CP_INTERFACEMETHODREF: + case CP_NAMEANDTYPE: + case CP_INVOKEDYNAMIC: + seekerr = fseek(classfile, 4, SEEK_CUR); + break; + case CP_LONG: + case CP_DOUBLE: + seekerr = fseek(classfile, 8, SEEK_CUR); + ++(*cur); + break; + default: + corrupt_error(); + } + if(seekerr) + seek_error(); + } + + void error(const char *format, ...) + { + va_list ap; + va_start(ap, format); + vfprintf(stderr, format, ap); + va_end(ap); + exit(1); + } + + int main(int argc, char **argv) + { + FILE *classfile; + u_int16_t cp_count, i, this_class, classinfo_ptr; + u_int8_t length; + + program = argv[0]; + + if(!argv[1]) + error("%s: Missing input file\n", program); + classfile = fopen(argv[1], "rb"); + if(!classfile) + error("%s: Error opening %s\n", program, argv[1]); + + if(fseek(classfile, 8, SEEK_SET)) /* skip magic and version numbers */ + seek_error(); + cp_count = read_16(classfile); + pool = calloc(cp_count, sizeof(long)); + if(!pool) + error("%s: Out of memory for constant pool\n", program); + + for(i = 1; i < cp_count; ++i) + skip_constant(classfile, &i); + if(fseek(classfile, 2, SEEK_CUR)) /* skip access flags */ + seek_error(); + + this_class = read_16(classfile); + if(this_class < 1 || this_class >= cp_count) + corrupt_error(); + if(!pool[this_class] || pool[this_class] == -1) + corrupt_error(); + if(fseek(classfile, pool[this_class] + 1, SEEK_SET)) + seek_error(); + + classinfo_ptr = read_16(classfile); + if(classinfo_ptr < 1 || classinfo_ptr >= cp_count) + corrupt_error(); + if(!pool[classinfo_ptr] || pool[classinfo_ptr] == -1) + corrupt_error(); + if(fseek(classfile, pool[classinfo_ptr] + 1, SEEK_SET)) + seek_error(); + + length = read_16(classfile); + for(i = 0; i < length; ++i) + { + u_int8_t x = read_8(classfile); + if((x & 0x80) || !x) + { + if((x & 0xE0) == 0xC0) + { + u_int8_t y = read_8(classfile); + if((y & 0xC0) == 0x80) + { + int c = ((x & 0x1f) << 6) + (y & 0x3f); + if(c) putchar(c); + else utf8_error(); + } + else utf8_error(); + } + else utf8_error(); + } + else if(x == '/') putchar('.'); + else putchar(x); + } + putchar('\n'); + free(pool); + fclose(classfile); + return 0; + } + +jarwrapper:: + + #!/bin/bash + # /usr/local/java/bin/jarwrapper - the wrapper for binfmt_misc/jar + + java -jar $1 + + +Now simply ``chmod +x`` the ``.class``, ``.jar`` and/or ``.html`` files you +want to execute. + +To add a Java program to your path best put a symbolic link to the main +.class file into /usr/bin (or another place you like) omitting the .class +extension. The directory containing the original .class file will be +added to your CLASSPATH during execution. + + +To test your new setup, enter in the following simple Java app, and name +it "HelloWorld.java":: + + class HelloWorld { + public static void main(String args[]) { + System.out.println("Hello World!"); + } + } + +Now compile the application with:: + + javac HelloWorld.java + +Set the executable permissions of the binary file, with:: + + chmod 755 HelloWorld.class + +And then execute it:: + + ./HelloWorld.class + + +To execute Java Jar files, simple chmod the ``*.jar`` files to include +the execution bit, then just do:: + + ./Application.jar + + +To execute Java Applets, simple chmod the ``*.html`` files to include +the execution bit, then just do:: + + ./Applet.html + + +originally by Brian A. Lantz, brian@lantz.com +heavily edited for binfmt_misc by Richard Günther +new scripts by Colin J. Watson +added executable Jar file support by Kurt Huwig diff --git a/Documentation/admin-guide/kernel-parameters.rst b/Documentation/admin-guide/kernel-parameters.rst new file mode 100644 index 000000000000..b0804273b6e3 --- /dev/null +++ b/Documentation/admin-guide/kernel-parameters.rst @@ -0,0 +1,4577 @@ +Kernel Parameters +~~~~~~~~~~~~~~~~~ + +The following is a consolidated list of the kernel parameters as +implemented by the __setup(), core_param() and module_param() macros +and sorted into English Dictionary order (defined as ignoring all +punctuation and sorting digits before letters in a case insensitive +manner), and with descriptions where known. + +The kernel parses parameters from the kernel command line up to "--"; +if it doesn't recognize a parameter and it doesn't contain a '.', the +parameter gets passed to init: parameters with '=' go into init's +environment, others are passed as command line arguments to init. +Everything after "--" is passed as an argument to init. + +Module parameters can be specified in two ways: via the kernel command +line with a module name prefix, or via modprobe, e.g.:: + + (kernel command line) usbcore.blinkenlights=1 + (modprobe command line) modprobe usbcore blinkenlights=1 + +Parameters for modules which are built into the kernel need to be +specified on the kernel command line. modprobe looks through the +kernel command line (/proc/cmdline) and collects module parameters +when it loads a module, so the kernel command line can be used for +loadable modules too. + +Hyphens (dashes) and underscores are equivalent in parameter names, so:: + + log_buf_len=1M print-fatal-signals=1 + +can also be entered as:: + + log-buf-len=1M print_fatal_signals=1 + +Double-quotes can be used to protect spaces in values, e.g.:: + + param="spaces in here" + +cpu lists: +---------- + +Some kernel parameters take a list of CPUs as a value, e.g. isolcpus, +nohz_full, irqaffinity, rcu_nocbs. The format of this list is: + + ,..., + +or + + - + (must be a positive range in ascending order) + +or a mixture + +,...,- + +Note that for the special case of a range one can split the range into equal +sized groups and for each group use some amount from the beginning of that +group: + + -cpu number>:/ + +For example one can add to the command line following parameter: + + isolcpus=1,2,10-20,100-2000:2/25 + +where the final item represents CPUs 100,101,125,126,150,151,... + + + +This document may not be entirely up to date and comprehensive. The command +"modinfo -p ${modulename}" shows a current list of all parameters of a loadable +module. Loadable modules, after being loaded into the running kernel, also +reveal their parameters in /sys/module/${modulename}/parameters/. Some of these +parameters may be changed at runtime by the command +``echo -n ${value} > /sys/module/${modulename}/parameters/${parm}``. + +The parameters listed below are only valid if certain kernel build options were +enabled and if respective hardware is present. The text in square brackets at +the beginning of each description states the restrictions within which a +parameter is applicable:: + + ACPI ACPI support is enabled. + AGP AGP (Accelerated Graphics Port) is enabled. + ALSA ALSA sound support is enabled. + APIC APIC support is enabled. + APM Advanced Power Management support is enabled. + ARM ARM architecture is enabled. + AVR32 AVR32 architecture is enabled. + AX25 Appropriate AX.25 support is enabled. + BLACKFIN Blackfin architecture is enabled. + CLK Common clock infrastructure is enabled. + CMA Contiguous Memory Area support is enabled. + DRM Direct Rendering Management support is enabled. + DYNAMIC_DEBUG Build in debug messages and enable them at runtime + EDD BIOS Enhanced Disk Drive Services (EDD) is enabled + EFI EFI Partitioning (GPT) is enabled + EIDE EIDE/ATAPI support is enabled. + EVM Extended Verification Module + FB The frame buffer device is enabled. + FTRACE Function tracing enabled. + GCOV GCOV profiling is enabled. + HW Appropriate hardware is enabled. + IA-64 IA-64 architecture is enabled. + IMA Integrity measurement architecture is enabled. + IOSCHED More than one I/O scheduler is enabled. + IP_PNP IP DHCP, BOOTP, or RARP is enabled. + IPV6 IPv6 support is enabled. + ISAPNP ISA PnP code is enabled. + ISDN Appropriate ISDN support is enabled. + JOY Appropriate joystick support is enabled. + KGDB Kernel debugger support is enabled. + KVM Kernel Virtual Machine support is enabled. + LIBATA Libata driver is enabled + LP Printer support is enabled. + LOOP Loopback device support is enabled. + M68k M68k architecture is enabled. + These options have more detailed description inside of + Documentation/m68k/kernel-options.txt. + MDA MDA console support is enabled. + MIPS MIPS architecture is enabled. + MOUSE Appropriate mouse support is enabled. + MSI Message Signaled Interrupts (PCI). + MTD MTD (Memory Technology Device) support is enabled. + NET Appropriate network support is enabled. + NUMA NUMA support is enabled. + NFS Appropriate NFS support is enabled. + OSS OSS sound support is enabled. + PV_OPS A paravirtualized kernel is enabled. + PARIDE The ParIDE (parallel port IDE) subsystem is enabled. + PARISC The PA-RISC architecture is enabled. + PCI PCI bus support is enabled. + PCIE PCI Express support is enabled. + PCMCIA The PCMCIA subsystem is enabled. + PNP Plug & Play support is enabled. + PPC PowerPC architecture is enabled. + PPT Parallel port support is enabled. + PS2 Appropriate PS/2 support is enabled. + RAM RAM disk support is enabled. + S390 S390 architecture is enabled. + SCSI Appropriate SCSI support is enabled. + A lot of drivers have their options described inside + the Documentation/scsi/ sub-directory. + SECURITY Different security models are enabled. + SELINUX SELinux support is enabled. + APPARMOR AppArmor support is enabled. + SERIAL Serial support is enabled. + SH SuperH architecture is enabled. + SMP The kernel is an SMP kernel. + SPARC Sparc architecture is enabled. + SWSUSP Software suspend (hibernation) is enabled. + SUSPEND System suspend states are enabled. + TPM TPM drivers are enabled. + TS Appropriate touchscreen support is enabled. + UMS USB Mass Storage support is enabled. + USB USB support is enabled. + USBHID USB Human Interface Device support is enabled. + V4L Video For Linux support is enabled. + VMMIO Driver for memory mapped virtio devices is enabled. + VGA The VGA console has been enabled. + VT Virtual terminal support is enabled. + WDT Watchdog support is enabled. + XT IBM PC/XT MFM hard disk support is enabled. + X86-32 X86-32, aka i386 architecture is enabled. + X86-64 X86-64 architecture is enabled. + More X86-64 boot options can be found in + Documentation/x86/x86_64/boot-options.txt . + X86 Either 32-bit or 64-bit x86 (same as X86-32+X86-64) + X86_UV SGI UV support is enabled. + XEN Xen support is enabled + +In addition, the following text indicates that the option:: + + BUGS= Relates to possible processor bugs on the said processor. + KNL Is a kernel start-up parameter. + BOOT Is a boot loader parameter. + +Parameters denoted with BOOT are actually interpreted by the boot +loader, and have no meaning to the kernel directly. +Do not modify the syntax of boot loader parameters without extreme +need or coordination with . + +There are also arch-specific kernel-parameters not documented here. +See for example . + +Note that ALL kernel parameters listed below are CASE SENSITIVE, and that +a trailing = on the name of any parameter states that that parameter will +be entered as an environment variable, whereas its absence indicates that +it will appear as a kernel argument readable via /proc/cmdline by programs +running once the system is up. + +The number of kernel parameters is not limited, but the length of the +complete command line (parameters including spaces etc.) is limited to +a fixed number of characters. This limit depends on the architecture +and is between 256 and 4096 characters. It is defined in the file +./include/asm/setup.h as COMMAND_LINE_SIZE. + +Finally, the [KMG] suffix is commonly described after a number of kernel +parameter values. These 'K', 'M', and 'G' letters represent the _binary_ +multipliers 'Kilo', 'Mega', and 'Giga', equalling 2^10, 2^20, and 2^30 +bytes respectively. Such letter suffixes can also be entirely omitted:: + + + acpi= [HW,ACPI,X86,ARM64] + Advanced Configuration and Power Interface + Format: { force | on | off | strict | noirq | rsdt | + copy_dsdt } + force -- enable ACPI if default was off + on -- enable ACPI but allow fallback to DT [arm64] + off -- disable ACPI if default was on + noirq -- do not use ACPI for IRQ routing + strict -- Be less tolerant of platforms that are not + strictly ACPI specification compliant. + rsdt -- prefer RSDT over (default) XSDT + copy_dsdt -- copy DSDT to memory + For ARM64, ONLY "acpi=off", "acpi=on" or "acpi=force" + are available + + See also Documentation/power/runtime_pm.txt, pci=noacpi + + acpi_apic_instance= [ACPI, IOAPIC] + Format: + 2: use 2nd APIC table, if available + 1,0: use 1st APIC table + default: 0 + + acpi_backlight= [HW,ACPI] + acpi_backlight=vendor + acpi_backlight=video + If set to vendor, prefer vendor specific driver + (e.g. thinkpad_acpi, sony_acpi, etc.) instead + of the ACPI video.ko driver. + + acpi_force_32bit_fadt_addr + force FADT to use 32 bit addresses rather than the + 64 bit X_* addresses. Some firmware have broken 64 + bit addresses for force ACPI ignore these and use + the older legacy 32 bit addresses. + + acpica_no_return_repair [HW, ACPI] + Disable AML predefined validation mechanism + This mechanism can repair the evaluation result to make + the return objects more ACPI specification compliant. + This option is useful for developers to identify the + root cause of an AML interpreter issue when the issue + has something to do with the repair mechanism. + + acpi.debug_layer= [HW,ACPI,ACPI_DEBUG] + acpi.debug_level= [HW,ACPI,ACPI_DEBUG] + Format: + CONFIG_ACPI_DEBUG must be enabled to produce any ACPI + debug output. Bits in debug_layer correspond to a + _COMPONENT in an ACPI source file, e.g., + #define _COMPONENT ACPI_PCI_COMPONENT + Bits in debug_level correspond to a level in + ACPI_DEBUG_PRINT statements, e.g., + ACPI_DEBUG_PRINT((ACPI_DB_INFO, ... + The debug_level mask defaults to "info". See + Documentation/acpi/debug.txt for more information about + debug layers and levels. + + Enable processor driver info messages: + acpi.debug_layer=0x20000000 + Enable PCI/PCI interrupt routing info messages: + acpi.debug_layer=0x400000 + Enable AML "Debug" output, i.e., stores to the Debug + object while interpreting AML: + acpi.debug_layer=0xffffffff acpi.debug_level=0x2 + Enable all messages related to ACPI hardware: + acpi.debug_layer=0x2 acpi.debug_level=0xffffffff + + Some values produce so much output that the system is + unusable. The "log_buf_len" parameter may be useful + if you need to capture more output. + + acpi_enforce_resources= [ACPI] + { strict | lax | no } + Check for resource conflicts between native drivers + and ACPI OperationRegions (SystemIO and SystemMemory + only). IO ports and memory declared in ACPI might be + used by the ACPI subsystem in arbitrary AML code and + can interfere with legacy drivers. + strict (default): access to resources claimed by ACPI + is denied; legacy drivers trying to access reserved + resources will fail to bind to device using them. + lax: access to resources claimed by ACPI is allowed; + legacy drivers trying to access reserved resources + will bind successfully but a warning message is logged. + no: ACPI OperationRegions are not marked as reserved, + no further checks are performed. + + acpi_force_table_verification [HW,ACPI] + Enable table checksum verification during early stage. + By default, this is disabled due to x86 early mapping + size limitation. + + acpi_irq_balance [HW,ACPI] + ACPI will balance active IRQs + default in APIC mode + + acpi_irq_nobalance [HW,ACPI] + ACPI will not move active IRQs (default) + default in PIC mode + + acpi_irq_isa= [HW,ACPI] If irq_balance, mark listed IRQs used by ISA + Format: ,... + + acpi_irq_pci= [HW,ACPI] If irq_balance, clear listed IRQs for + use by PCI + Format: ,... + + acpi_no_auto_serialize [HW,ACPI] + Disable auto-serialization of AML methods + AML control methods that contain the opcodes to create + named objects will be marked as "Serialized" by the + auto-serialization feature. + This feature is enabled by default. + This option allows to turn off the feature. + + acpi_no_memhotplug [ACPI] Disable memory hotplug. Useful for kdump + kernels. + + acpi_no_static_ssdt [HW,ACPI] + Disable installation of static SSDTs at early boot time + By default, SSDTs contained in the RSDT/XSDT will be + installed automatically and they will appear under + /sys/firmware/acpi/tables. + This option turns off this feature. + Note that specifying this option does not affect + dynamic table installation which will install SSDT + tables to /sys/firmware/acpi/tables/dynamic. + + acpi_rsdp= [ACPI,EFI,KEXEC] + Pass the RSDP address to the kernel, mostly used + on machines running EFI runtime service to boot the + second kernel for kdump. + + acpi_os_name= [HW,ACPI] Tell ACPI BIOS the name of the OS + Format: To spoof as Windows 98: ="Microsoft Windows" + + acpi_rev_override [ACPI] Override the _REV object to return 5 (instead + of 2 which is mandated by ACPI 6) as the supported ACPI + specification revision (when using this switch, it may + be necessary to carry out a cold reboot _twice_ in a + row to make it take effect on the platform firmware). + + acpi_osi= [HW,ACPI] Modify list of supported OS interface strings + acpi_osi="string1" # add string1 + acpi_osi="!string2" # remove string2 + acpi_osi=!* # remove all strings + acpi_osi=! # disable all built-in OS vendor + strings + acpi_osi=!! # enable all built-in OS vendor + strings + acpi_osi= # disable all strings + + 'acpi_osi=!' can be used in combination with single or + multiple 'acpi_osi="string1"' to support specific OS + vendor string(s). Note that such command can only + affect the default state of the OS vendor strings, thus + it cannot affect the default state of the feature group + strings and the current state of the OS vendor strings, + specifying it multiple times through kernel command line + is meaningless. This command is useful when one do not + care about the state of the feature group strings which + should be controlled by the OSPM. + Examples: + 1. 'acpi_osi=! acpi_osi="Windows 2000"' is equivalent + to 'acpi_osi="Windows 2000" acpi_osi=!', they all + can make '_OSI("Windows 2000")' TRUE. + + 'acpi_osi=' cannot be used in combination with other + 'acpi_osi=' command lines, the _OSI method will not + exist in the ACPI namespace. NOTE that such command can + only affect the _OSI support state, thus specifying it + multiple times through kernel command line is also + meaningless. + Examples: + 1. 'acpi_osi=' can make 'CondRefOf(_OSI, Local1)' + FALSE. + + 'acpi_osi=!*' can be used in combination with single or + multiple 'acpi_osi="string1"' to support specific + string(s). Note that such command can affect the + current state of both the OS vendor strings and the + feature group strings, thus specifying it multiple times + through kernel command line is meaningful. But it may + still not able to affect the final state of a string if + there are quirks related to this string. This command + is useful when one want to control the state of the + feature group strings to debug BIOS issues related to + the OSPM features. + Examples: + 1. 'acpi_osi="Module Device" acpi_osi=!*' can make + '_OSI("Module Device")' FALSE. + 2. 'acpi_osi=!* acpi_osi="Module Device"' can make + '_OSI("Module Device")' TRUE. + 3. 'acpi_osi=! acpi_osi=!* acpi_osi="Windows 2000"' is + equivalent to + 'acpi_osi=!* acpi_osi=! acpi_osi="Windows 2000"' + and + 'acpi_osi=!* acpi_osi="Windows 2000" acpi_osi=!', + they all will make '_OSI("Windows 2000")' TRUE. + + acpi_pm_good [X86] + Override the pmtimer bug detection: force the kernel + to assume that this machine's pmtimer latches its value + and always returns good values. + + acpi_sci= [HW,ACPI] ACPI System Control Interrupt trigger mode + Format: { level | edge | high | low } + + acpi_skip_timer_override [HW,ACPI] + Recognize and ignore IRQ0/pin2 Interrupt Override. + For broken nForce2 BIOS resulting in XT-PIC timer. + + acpi_sleep= [HW,ACPI] Sleep options + Format: { s3_bios, s3_mode, s3_beep, s4_nohwsig, + old_ordering, nonvs, sci_force_enable } + See Documentation/power/video.txt for information on + s3_bios and s3_mode. + s3_beep is for debugging; it makes the PC's speaker beep + as soon as the kernel's real-mode entry point is called. + s4_nohwsig prevents ACPI hardware signature from being + used during resume from hibernation. + old_ordering causes the ACPI 1.0 ordering of the _PTS + control method, with respect to putting devices into + low power states, to be enforced (the ACPI 2.0 ordering + of _PTS is used by default). + nonvs prevents the kernel from saving/restoring the + ACPI NVS memory during suspend/hibernation and resume. + sci_force_enable causes the kernel to set SCI_EN directly + on resume from S1/S3 (which is against the ACPI spec, + but some broken systems don't work without it). + + acpi_use_timer_override [HW,ACPI] + Use timer override. For some broken Nvidia NF5 boards + that require a timer override, but don't have HPET + + add_efi_memmap [EFI; X86] Include EFI memory map in + kernel's map of available physical RAM. + + agp= [AGP] + { off | try_unsupported } + off: disable AGP support + try_unsupported: try to drive unsupported chipsets + (may crash computer or cause data corruption) + + ALSA [HW,ALSA] + See Documentation/sound/alsa/alsa-parameters.txt + + alignment= [KNL,ARM] + Allow the default userspace alignment fault handler + behaviour to be specified. Bit 0 enables warnings, + bit 1 enables fixups, and bit 2 sends a segfault. + + align_va_addr= [X86-64] + Align virtual addresses by clearing slice [14:12] when + allocating a VMA at process creation time. This option + gives you up to 3% performance improvement on AMD F15h + machines (where it is enabled by default) for a + CPU-intensive style benchmark, and it can vary highly in + a microbenchmark depending on workload and compiler. + + 32: only for 32-bit processes + 64: only for 64-bit processes + on: enable for both 32- and 64-bit processes + off: disable for both 32- and 64-bit processes + + alloc_snapshot [FTRACE] + Allocate the ftrace snapshot buffer on boot up when the + main buffer is allocated. This is handy if debugging + and you need to use tracing_snapshot() on boot up, and + do not want to use tracing_snapshot_alloc() as it needs + to be done where GFP_KERNEL allocations are allowed. + + amd_iommu= [HW,X86-64] + Pass parameters to the AMD IOMMU driver in the system. + Possible values are: + fullflush - enable flushing of IO/TLB entries when + they are unmapped. Otherwise they are + flushed before they will be reused, which + is a lot of faster + off - do not initialize any AMD IOMMU found in + the system + force_isolation - Force device isolation for all + devices. The IOMMU driver is not + allowed anymore to lift isolation + requirements as needed. This option + does not override iommu=pt + + amd_iommu_dump= [HW,X86-64] + Enable AMD IOMMU driver option to dump the ACPI table + for AMD IOMMU. With this option enabled, AMD IOMMU + driver will print ACPI tables for AMD IOMMU during + IOMMU initialization. + + amd_iommu_intr= [HW,X86-64] + Specifies one of the following AMD IOMMU interrupt + remapping modes: + legacy - Use legacy interrupt remapping mode. + vapic - Use virtual APIC mode, which allows IOMMU + to inject interrupts directly into guest. + This mode requires kvm-amd.avic=1. + (Default when IOMMU HW support is present.) + + amijoy.map= [HW,JOY] Amiga joystick support + Map of devices attached to JOY0DAT and JOY1DAT + Format: , + See also Documentation/input/joystick.txt + + analog.map= [HW,JOY] Analog joystick and gamepad support + Specifies type or capabilities of an analog joystick + connected to one of 16 gameports + Format: ,,.. + + apc= [HW,SPARC] + Power management functions (SPARCstation-4/5 + deriv.) + Format: noidle + Disable APC CPU standby support. SPARCstation-Fox does + not play well with APC CPU idle - disable it if you have + APC and your system crashes randomly. + + apic= [APIC,X86-32] Advanced Programmable Interrupt Controller + Change the output verbosity whilst booting + Format: { quiet (default) | verbose | debug } + Change the amount of debugging information output + when initialising the APIC and IO-APIC components. + + apic_extnmi= [APIC,X86] External NMI delivery setting + Format: { bsp (default) | all | none } + bsp: External NMI is delivered only to CPU 0 + all: External NMIs are broadcast to all CPUs as a + backup of CPU 0 + none: External NMI is masked for all CPUs. This is + useful so that a dump capture kernel won't be + shot down by NMI + + autoconf= [IPV6] + See Documentation/networking/ipv6.txt. + + show_lapic= [APIC,X86] Advanced Programmable Interrupt Controller + Limit apic dumping. The parameter defines the maximal + number of local apics being dumped. Also it is possible + to set it to "all" by meaning -- no limit here. + Format: { 1 (default) | 2 | ... | all }. + The parameter valid if only apic=debug or + apic=verbose is specified. + Example: apic=debug show_lapic=all + + apm= [APM] Advanced Power Management + See header of arch/x86/kernel/apm_32.c. + + arcrimi= [HW,NET] ARCnet - "RIM I" (entirely mem-mapped) cards + Format: ,, + + ataflop= [HW,M68k] + + atarimouse= [HW,MOUSE] Atari Mouse + + atkbd.extra= [HW] Enable extra LEDs and keys on IBM RapidAccess, + EzKey and similar keyboards + + atkbd.reset= [HW] Reset keyboard during initialization + + atkbd.set= [HW] Select keyboard code set + Format: (2 = AT (default), 3 = PS/2) + + atkbd.scroll= [HW] Enable scroll wheel on MS Office and similar + keyboards + + atkbd.softraw= [HW] Choose between synthetic and real raw mode + Format: (0 = real, 1 = synthetic (default)) + + atkbd.softrepeat= [HW] + Use software keyboard repeat + + audit= [KNL] Enable the audit sub-system + Format: { "0" | "1" } (0 = disabled, 1 = enabled) + 0 - kernel audit is disabled and can not be enabled + until the next reboot + unset - kernel audit is initialized but disabled and + will be fully enabled by the userspace auditd. + 1 - kernel audit is initialized and partially enabled, + storing at most audit_backlog_limit messages in + RAM until it is fully enabled by the userspace + auditd. + Default: unset + + audit_backlog_limit= [KNL] Set the audit queue size limit. + Format: (must be >=0) + Default: 64 + + bau= [X86_UV] Enable the BAU on SGI UV. The default + behavior is to disable the BAU (i.e. bau=0). + Format: { "0" | "1" } + 0 - Disable the BAU. + 1 - Enable the BAU. + unset - Disable the BAU. + + baycom_epp= [HW,AX25] + Format: , + + baycom_par= [HW,AX25] BayCom Parallel Port AX.25 Modem + Format: , + See header of drivers/net/hamradio/baycom_par.c. + + baycom_ser_fdx= [HW,AX25] + BayCom Serial Port AX.25 Modem (Full Duplex Mode) + Format: ,,[,] + See header of drivers/net/hamradio/baycom_ser_fdx.c. + + baycom_ser_hdx= [HW,AX25] + BayCom Serial Port AX.25 Modem (Half Duplex Mode) + Format: ,, + See header of drivers/net/hamradio/baycom_ser_hdx.c. + + blkdevparts= Manual partition parsing of block device(s) for + embedded devices based on command line input. + See Documentation/block/cmdline-partition.txt + + boot_delay= Milliseconds to delay each printk during boot. + Values larger than 10 seconds (10000) are changed to + no delay (0). + Format: integer + + bootmem_debug [KNL] Enable bootmem allocator debug messages. + + bert_disable [ACPI] + Disable BERT OS support on buggy BIOSes. + + bttv.card= [HW,V4L] bttv (bt848 + bt878 based grabber cards) + bttv.radio= Most important insmod options are available as + kernel args too. + bttv.pll= See Documentation/video4linux/bttv/Insmod-options + bttv.tuner= + + bulk_remove=off [PPC] This parameter disables the use of the pSeries + firmware feature for flushing multiple hpte entries + at a time. + + c101= [NET] Moxa C101 synchronous serial card + + cachesize= [BUGS=X86-32] Override level 2 CPU cache size detection. + Sometimes CPU hardware bugs make them report the cache + size incorrectly. The kernel will attempt work arounds + to fix known problems, but for some CPUs it is not + possible to determine what the correct size should be. + This option provides an override for these situations. + + ca_keys= [KEYS] This parameter identifies a specific key(s) on + the system trusted keyring to be used for certificate + trust validation. + format: { id: | builtin } + + cca= [MIPS] Override the kernel pages' cache coherency + algorithm. Accepted values range from 0 to 7 + inclusive. See arch/mips/include/asm/pgtable-bits.h + for platform specific values (SB1, Loongson3 and + others). + + ccw_timeout_log [S390] + See Documentation/s390/CommonIO for details. + + cgroup_disable= [KNL] Disable a particular controller + Format: {name of the controller(s) to disable} + The effects of cgroup_disable=foo are: + - foo isn't auto-mounted if you mount all cgroups in + a single hierarchy + - foo isn't visible as an individually mountable + subsystem + {Currently only "memory" controller deal with this and + cut the overhead, others just disable the usage. So + only cgroup_disable=memory is actually worthy} + + cgroup_no_v1= [KNL] Disable one, multiple, all cgroup controllers in v1 + Format: { controller[,controller...] | "all" } + Like cgroup_disable, but only applies to cgroup v1; + the blacklisted controllers remain available in cgroup2. + + cgroup.memory= [KNL] Pass options to the cgroup memory controller. + Format: + nosocket -- Disable socket memory accounting. + nokmem -- Disable kernel memory accounting. + + checkreqprot [SELINUX] Set initial checkreqprot flag value. + Format: { "0" | "1" } + See security/selinux/Kconfig help text. + 0 -- check protection applied by kernel (includes + any implied execute protection). + 1 -- check protection requested by application. + Default value is set via a kernel config option. + Value can be changed at runtime via + /selinux/checkreqprot. + + cio_ignore= [S390] + See Documentation/s390/CommonIO for details. + clk_ignore_unused + [CLK] + Prevents the clock framework from automatically gating + clocks that have not been explicitly enabled by a Linux + device driver but are enabled in hardware at reset or + by the bootloader/firmware. Note that this does not + force such clocks to be always-on nor does it reserve + those clocks in any way. This parameter is useful for + debug and development, but should not be needed on a + platform with proper driver support. For more + information, see Documentation/clk.txt. + + clock= [BUGS=X86-32, HW] gettimeofday clocksource override. + [Deprecated] + Forces specified clocksource (if available) to be used + when calculating gettimeofday(). If specified + clocksource is not available, it defaults to PIT. + Format: { pit | tsc | cyclone | pmtmr } + + clocksource= Override the default clocksource + Format: + Override the default clocksource and use the clocksource + with the name specified. + Some clocksource names to choose from, depending on + the platform: + [all] jiffies (this is the base, fallback clocksource) + [ACPI] acpi_pm + [ARM] imx_timer1,OSTS,netx_timer,mpu_timer2, + pxa_timer,timer3,32k_counter,timer0_1 + [AVR32] avr32 + [X86-32] pit,hpet,tsc; + scx200_hrt on Geode; cyclone on IBM x440 + [MIPS] MIPS + [PARISC] cr16 + [S390] tod + [SH] SuperH + [SPARC64] tick + [X86-64] hpet,tsc + + clocksource.arm_arch_timer.evtstrm= + [ARM,ARM64] + Format: + Enable/disable the eventstream feature of the ARM + architected timer so that code using WFE-based polling + loops can be debugged more effectively on production + systems. + + clocksource.arm_arch_timer.fsl-a008585= + [ARM64] + Format: + Enable/disable the workaround of Freescale/NXP + erratum A-008585. This can be useful for KVM + guests, if the guest device tree doesn't show the + erratum. If unspecified, the workaround is + enabled based on the device tree. + + clearcpuid=BITNUM [X86] + Disable CPUID feature X for the kernel. See + arch/x86/include/asm/cpufeatures.h for the valid bit + numbers. Note the Linux specific bits are not necessarily + stable over kernel options, but the vendor specific + ones should be. + Also note that user programs calling CPUID directly + or using the feature without checking anything + will still see it. This just prevents it from + being used by the kernel or shown in /proc/cpuinfo. + Also note the kernel might malfunction if you disable + some critical bits. + + cma=nn[MG]@[start[MG][-end[MG]]] + [ARM,X86,KNL] + Sets the size of kernel global memory area for + contiguous memory allocations and optionally the + placement constraint by the physical address range of + memory allocations. A value of 0 disables CMA + altogether. For more information, see + include/linux/dma-contiguous.h + + cmo_free_hint= [PPC] Format: { yes | no } + Specify whether pages are marked as being inactive + when they are freed. This is used in CMO environments + to determine OS memory pressure for page stealing by + a hypervisor. + Default: yes + + coherent_pool=nn[KMG] [ARM,KNL] + Sets the size of memory pool for coherent, atomic dma + allocations, by default set to 256K. + + code_bytes [X86] How many bytes of object code to print + in an oops report. + Range: 0 - 8192 + Default: 64 + + com20020= [HW,NET] ARCnet - COM20020 chipset + Format: + [,[,[,[,[,]]]]] + + com90io= [HW,NET] ARCnet - COM90xx chipset (IO-mapped buffers) + Format: [,] + + com90xx= [HW,NET] + ARCnet - COM90xx chipset (memory-mapped buffers) + Format: [,[,]] + + condev= [HW,S390] console device + conmode= + + console= [KNL] Output console device and options. + + tty Use the virtual console device . + + ttyS[,options] + ttyUSB0[,options] + Use the specified serial port. The options are of + the form "bbbbpnf", where "bbbb" is the baud rate, + "p" is parity ("n", "o", or "e"), "n" is number of + bits, and "f" is flow control ("r" for RTS or + omit it). Default is "9600n8". + + See Documentation/serial-console.txt for more + information. See + Documentation/networking/netconsole.txt for an + alternative. + + uart[8250],io,[,options] + uart[8250],mmio,[,options] + uart[8250],mmio16,[,options] + uart[8250],mmio32,[,options] + uart[8250],0x[,options] + Start an early, polled-mode console on the 8250/16550 + UART at the specified I/O port or MMIO address, + switching to the matching ttyS device later. + MMIO inter-register address stride is either 8-bit + (mmio), 16-bit (mmio16), or 32-bit (mmio32). + If none of [io|mmio|mmio16|mmio32], is assumed + to be equivalent to 'mmio'. 'options' are specified in + the same format described for ttyS above; if unspecified, + the h/w is not re-initialized. + + hvc Use the hypervisor console device . This is for + both Xen and PowerPC hypervisors. + + If the device connected to the port is not a TTY but a braille + device, prepend "brl," before the device type, for instance + console=brl,ttyS0 + For now, only VisioBraille is supported. + + consoleblank= [KNL] The console blank (screen saver) timeout in + seconds. Defaults to 10*60 = 10mins. A value of 0 + disables the blank timer. + + coredump_filter= + [KNL] Change the default value for + /proc//coredump_filter. + See also Documentation/filesystems/proc.txt. + + cpuidle.off=1 [CPU_IDLE] + disable the cpuidle sub-system + + cpu_init_udelay=N + [X86] Delay for N microsec between assert and de-assert + of APIC INIT to start processors. This delay occurs + on every CPU online, such as boot, and resume from suspend. + Default: 10000 + + cpcihp_generic= [HW,PCI] Generic port I/O CompactPCI driver + Format: + ,,,[,] + + crashkernel=size[KMG][@offset[KMG]] + [KNL] Using kexec, Linux can switch to a 'crash kernel' + upon panic. This parameter reserves the physical + memory region [offset, offset + size] for that kernel + image. If '@offset' is omitted, then a suitable offset + is selected automatically. Check + Documentation/kdump/kdump.txt for further details. + + crashkernel=range1:size1[,range2:size2,...][@offset] + [KNL] Same as above, but depends on the memory + in the running system. The syntax of range is + start-[end] where start and end are both + a memory unit (amount[KMG]). See also + Documentation/kdump/kdump.txt for an example. + + crashkernel=size[KMG],high + [KNL, x86_64] range could be above 4G. Allow kernel + to allocate physical memory region from top, so could + be above 4G if system have more than 4G ram installed. + Otherwise memory region will be allocated below 4G, if + available. + It will be ignored if crashkernel=X is specified. + crashkernel=size[KMG],low + [KNL, x86_64] range under 4G. When crashkernel=X,high + is passed, kernel could allocate physical memory region + above 4G, that cause second kernel crash on system + that require some amount of low memory, e.g. swiotlb + requires at least 64M+32K low memory, also enough extra + low memory is needed to make sure DMA buffers for 32-bit + devices won't run out. Kernel would try to allocate at + at least 256M below 4G automatically. + This one let user to specify own low range under 4G + for second kernel instead. + 0: to disable low allocation. + It will be ignored when crashkernel=X,high is not used + or memory reserved is below 4G. + + cryptomgr.notests + [KNL] Disable crypto self-tests + + cs89x0_dma= [HW,NET] + Format: + + cs89x0_media= [HW,NET] + Format: { rj45 | aui | bnc } + + dasd= [HW,NET] + See header of drivers/s390/block/dasd_devmap.c. + + db9.dev[2|3]= [HW,JOY] Multisystem joystick support via parallel port + (one device per port) + Format: , + See also Documentation/input/joystick-parport.txt + + ddebug_query= [KNL,DYNAMIC_DEBUG] Enable debug messages at early boot + time. See Documentation/dynamic-debug-howto.txt for + details. Deprecated, see dyndbg. + + debug [KNL] Enable kernel debugging (events log level). + + debug_locks_verbose= + [KNL] verbose self-tests + Format=<0|1> + Print debugging info while doing the locking API + self-tests. + We default to 0 (no extra messages), setting it to + 1 will print _a lot_ more information - normally + only useful to kernel developers. + + debug_objects [KNL] Enable object debugging + + no_debug_objects + [KNL] Disable object debugging + + debug_guardpage_minorder= + [KNL] When CONFIG_DEBUG_PAGEALLOC is set, this + parameter allows control of the order of pages that will + be intentionally kept free (and hence protected) by the + buddy allocator. Bigger value increase the probability + of catching random memory corruption, but reduce the + amount of memory for normal system use. The maximum + possible value is MAX_ORDER/2. Setting this parameter + to 1 or 2 should be enough to identify most random + memory corruption problems caused by bugs in kernel or + driver code when a CPU writes to (or reads from) a + random memory location. Note that there exists a class + of memory corruptions problems caused by buggy H/W or + F/W or by drivers badly programing DMA (basically when + memory is written at bus level and the CPU MMU is + bypassed) which are not detectable by + CONFIG_DEBUG_PAGEALLOC, hence this option will not help + tracking down these problems. + + debug_pagealloc= + [KNL] When CONFIG_DEBUG_PAGEALLOC is set, this + parameter enables the feature at boot time. In + default, it is disabled. We can avoid allocating huge + chunk of memory for debug pagealloc if we don't enable + it at boot time and the system will work mostly same + with the kernel built without CONFIG_DEBUG_PAGEALLOC. + on: enable the feature + + debugpat [X86] Enable PAT debugging + + decnet.addr= [HW,NET] + Format: [,] + See also Documentation/networking/decnet.txt. + + default_hugepagesz= + [same as hugepagesz=] The size of the default + HugeTLB page size. This is the size represented by + the legacy /proc/ hugepages APIs, used for SHM, and + default size when mounting hugetlbfs filesystems. + Defaults to the default architecture's huge page size + if not specified. + + dhash_entries= [KNL] + Set number of hash buckets for dentry cache. + + disable_1tb_segments [PPC] + Disables the use of 1TB hash page table segments. This + causes the kernel to fall back to 256MB segments which + can be useful when debugging issues that require an SLB + miss to occur. + + disable= [IPV6] + See Documentation/networking/ipv6.txt. + + disable_radix [PPC] + Disable RADIX MMU mode on POWER9 + + disable_cpu_apicid= [X86,APIC,SMP] + Format: + The number of initial APIC ID for the + corresponding CPU to be disabled at boot, + mostly used for the kdump 2nd kernel to + disable BSP to wake up multiple CPUs without + causing system reset or hang due to sending + INIT from AP to BSP. + + disable_ddw [PPC/PSERIES] + Disable Dynamic DMA Window support. Use this if + to workaround buggy firmware. + + disable_ipv6= [IPV6] + See Documentation/networking/ipv6.txt. + + disable_mtrr_cleanup [X86] + The kernel tries to adjust MTRR layout from continuous + to discrete, to make X server driver able to add WB + entry later. This parameter disables that. + + disable_mtrr_trim [X86, Intel and AMD only] + By default the kernel will trim any uncacheable + memory out of your available memory pool based on + MTRR settings. This parameter disables that behavior, + possibly causing your machine to run very slowly. + + disable_timer_pin_1 [X86] + Disable PIN 1 of APIC timer + Can be useful to work around chipset bugs. + + dis_ucode_ldr [X86] Disable the microcode loader. + + dma_debug=off If the kernel is compiled with DMA_API_DEBUG support, + this option disables the debugging code at boot. + + dma_debug_entries= + This option allows to tune the number of preallocated + entries for DMA-API debugging code. One entry is + required per DMA-API allocation. Use this if the + DMA-API debugging code disables itself because the + architectural default is too low. + + dma_debug_driver= + With this option the DMA-API debugging driver + filter feature can be enabled at boot time. Just + pass the driver to filter for as the parameter. + The filter can be disabled or changed to another + driver later using sysfs. + + drm_kms_helper.edid_firmware=[:][,[:]] + Broken monitors, graphic adapters, KVMs and EDIDless + panels may send no or incorrect EDID data sets. + This parameter allows to specify an EDID data sets + in the /lib/firmware directory that are used instead. + Generic built-in EDID data sets are used, if one of + edid/1024x768.bin, edid/1280x1024.bin, + edid/1680x1050.bin, or edid/1920x1080.bin is given + and no file with the same name exists. Details and + instructions how to build your own EDID data are + available in Documentation/EDID/HOWTO.txt. An EDID + data set will only be used for a particular connector, + if its name and a colon are prepended to the EDID + name. Each connector may use a unique EDID data + set by separating the files with a comma. An EDID + data set with no connector name will be used for + any connectors not explicitly specified. + + dscc4.setup= [NET] + + dyndbg[="val"] [KNL,DYNAMIC_DEBUG] + module.dyndbg[="val"] + Enable debug messages at boot time. See + Documentation/dynamic-debug-howto.txt for details. + + nompx [X86] Disables Intel Memory Protection Extensions. + See Documentation/x86/intel_mpx.txt for more + information about the feature. + + nopku [X86] Disable Memory Protection Keys CPU feature found + in some Intel CPUs. + + eagerfpu= [X86] + on enable eager fpu restore + off disable eager fpu restore + auto selects the default scheme, which automatically + enables eagerfpu restore for xsaveopt. + + module.async_probe [KNL] + Enable asynchronous probe on this module. + + early_ioremap_debug [KNL] + Enable debug messages in early_ioremap support. This + is useful for tracking down temporary early mappings + which are not unmapped. + + earlycon= [KNL] Output early console device and options. + + When used with no options, the early console is + determined by the stdout-path property in device + tree's chosen node. + + cdns,[,options] + Start an early, polled-mode console on a Cadence + (xuartps) serial port at the specified address. Only + supported option is baud rate. If baud rate is not + specified, the serial port must already be setup and + configured. + + uart[8250],io,[,options] + uart[8250],mmio,[,options] + uart[8250],mmio32,[,options] + uart[8250],mmio32be,[,options] + uart[8250],0x[,options] + Start an early, polled-mode console on the 8250/16550 + UART at the specified I/O port or MMIO address. + MMIO inter-register address stride is either 8-bit + (mmio) or 32-bit (mmio32 or mmio32be). + If none of [io|mmio|mmio32|mmio32be], is assumed + to be equivalent to 'mmio'. 'options' are specified + in the same format described for "console=ttyS"; if + unspecified, the h/w is not initialized. + + pl011, + pl011,mmio32, + Start an early, polled-mode console on a pl011 serial + port at the specified address. The pl011 serial port + must already be setup and configured. Options are not + yet supported. If 'mmio32' is specified, then only + the driver will use only 32-bit accessors to read/write + the device registers. + + meson, + Start an early, polled-mode console on a meson serial + port at the specified address. The serial port must + already be setup and configured. Options are not yet + supported. + + msm_serial, + Start an early, polled-mode console on an msm serial + port at the specified address. The serial port + must already be setup and configured. Options are not + yet supported. + + msm_serial_dm, + Start an early, polled-mode console on an msm serial + dm port at the specified address. The serial port + must already be setup and configured. Options are not + yet supported. + + smh Use ARM semihosting calls for early console. + + s3c2410, + s3c2412, + s3c2440, + s3c6400, + s5pv210, + exynos4210, + Use early console provided by serial driver available + on Samsung SoCs, requires selecting proper type and + a correct base address of the selected UART port. The + serial port must already be setup and configured. + Options are not yet supported. + + lpuart, + lpuart32, + Use early console provided by Freescale LP UART driver + found on Freescale Vybrid and QorIQ LS1021A processors. + A valid base address must be provided, and the serial + port must already be setup and configured. + + armada3700_uart, + Start an early, polled-mode console on the + Armada 3700 serial port at the specified + address. The serial port must already be setup + and configured. Options are not yet supported. + + earlyprintk= [X86,SH,BLACKFIN,ARM,M68k] + earlyprintk=vga + earlyprintk=efi + earlyprintk=xen + earlyprintk=serial[,ttySn[,baudrate]] + earlyprintk=serial[,0x...[,baudrate]] + earlyprintk=ttySn[,baudrate] + earlyprintk=dbgp[debugController#] + earlyprintk=pciserial,bus:device.function[,baudrate] + + earlyprintk is useful when the kernel crashes before + the normal console is initialized. It is not enabled by + default because it has some cosmetic problems. + + Append ",keep" to not disable it when the real console + takes over. + + Only one of vga, efi, serial, or usb debug port can + be used at a time. + + Currently only ttyS0 and ttyS1 may be specified by + name. Other I/O ports may be explicitly specified + on some architectures (x86 and arm at least) by + replacing ttySn with an I/O port address, like this: + earlyprintk=serial,0x1008,115200 + You can find the port for a given device in + /proc/tty/driver/serial: + 2: uart:ST16650V2 port:00001008 irq:18 ... + + Interaction with the standard serial driver is not + very good. + + The VGA and EFI output is eventually overwritten by + the real console. + + The xen output can only be used by Xen PV guests. + + edac_report= [HW,EDAC] Control how to report EDAC event + Format: {"on" | "off" | "force"} + on: enable EDAC to report H/W event. May be overridden + by other higher priority error reporting module. + off: disable H/W event reporting through EDAC. + force: enforce the use of EDAC to report H/W event. + default: on. + + ekgdboc= [X86,KGDB] Allow early kernel console debugging + ekgdboc=kbd + + This is designed to be used in conjunction with + the boot argument: earlyprintk=vga + + edd= [EDD] + Format: {"off" | "on" | "skip[mbr]"} + + efi= [EFI] + Format: { "old_map", "nochunk", "noruntime", "debug" } + old_map [X86-64]: switch to the old ioremap-based EFI + runtime services mapping. 32-bit still uses this one by + default. + nochunk: disable reading files in "chunks" in the EFI + boot stub, as chunking can cause problems with some + firmware implementations. + noruntime : disable EFI runtime services support + debug: enable misc debug output + + efi_no_storage_paranoia [EFI; X86] + Using this parameter you can use more than 50% of + your efi variable storage. Use this parameter only if + you are really sure that your UEFI does sane gc and + fulfills the spec otherwise your board may brick. + + efi_fake_mem= nn[KMG]@ss[KMG]:aa[,nn[KMG]@ss[KMG]:aa,..] [EFI; X86] + Add arbitrary attribute to specific memory range by + updating original EFI memory map. + Region of memory which aa attribute is added to is + from ss to ss+nn. + If efi_fake_mem=2G@4G:0x10000,2G@0x10a0000000:0x10000 + is specified, EFI_MEMORY_MORE_RELIABLE(0x10000) + attribute is added to range 0x100000000-0x180000000 and + 0x10a0000000-0x1120000000. + + Using this parameter you can do debugging of EFI memmap + related feature. For example, you can do debugging of + Address Range Mirroring feature even if your box + doesn't support it. + + efivar_ssdt= [EFI; X86] Name of an EFI variable that contains an SSDT + that is to be dynamically loaded by Linux. If there are + multiple variables with the same name but with different + vendor GUIDs, all of them will be loaded. See + Documentation/acpi/ssdt-overlays.txt for details. + + + eisa_irq_edge= [PARISC,HW] + See header of drivers/parisc/eisa.c. + + elanfreq= [X86-32] + See comment before function elanfreq_setup() in + arch/x86/kernel/cpu/cpufreq/elanfreq.c. + + elevator= [IOSCHED] + Format: {"cfq" | "deadline" | "noop"} + See Documentation/block/cfq-iosched.txt and + Documentation/block/deadline-iosched.txt for details. + + elfcorehdr=[size[KMG]@]offset[KMG] [IA64,PPC,SH,X86,S390] + Specifies physical address of start of kernel core + image elf header and optionally the size. Generally + kexec loader will pass this option to capture kernel. + See Documentation/kdump/kdump.txt for details. + + enable_mtrr_cleanup [X86] + The kernel tries to adjust MTRR layout from continuous + to discrete, to make X server driver able to add WB + entry later. This parameter enables that. + + enable_timer_pin_1 [X86] + Enable PIN 1 of APIC timer + Can be useful to work around chipset bugs + (in particular on some ATI chipsets). + The kernel tries to set a reasonable default. + + enforcing [SELINUX] Set initial enforcing status. + Format: {"0" | "1"} + See security/selinux/Kconfig help text. + 0 -- permissive (log only, no denials). + 1 -- enforcing (deny and log). + Default value is 0. + Value can be changed at runtime via /selinux/enforce. + + erst_disable [ACPI] + Disable Error Record Serialization Table (ERST) + support. + + ether= [HW,NET] Ethernet cards parameters + This option is obsoleted by the "netdev=" option, which + has equivalent usage. See its documentation for details. + + evm= [EVM] + Format: { "fix" } + Permit 'security.evm' to be updated regardless of + current integrity status. + + failslab= + fail_page_alloc= + fail_make_request=[KNL] + General fault injection mechanism. + Format: ,,, + See also Documentation/fault-injection/. + + floppy= [HW] + See Documentation/blockdev/floppy.txt. + + force_pal_cache_flush + [IA-64] Avoid check_sal_cache_flush which may hang on + buggy SAL_CACHE_FLUSH implementations. Using this + parameter will force ia64_sal_cache_flush to call + ia64_pal_cache_flush instead of SAL_CACHE_FLUSH. + + forcepae [X86-32] + Forcefully enable Physical Address Extension (PAE). + Many Pentium M systems disable PAE but may have a + functionally usable PAE implementation. + Warning: use of this parameter will taint the kernel + and may cause unknown problems. + + ftrace=[tracer] + [FTRACE] will set and start the specified tracer + as early as possible in order to facilitate early + boot debugging. + + ftrace_dump_on_oops[=orig_cpu] + [FTRACE] will dump the trace buffers on oops. + If no parameter is passed, ftrace will dump + buffers of all CPUs, but if you pass orig_cpu, it will + dump only the buffer of the CPU that triggered the + oops. + + ftrace_filter=[function-list] + [FTRACE] Limit the functions traced by the function + tracer at boot up. function-list is a comma separated + list of functions. This list can be changed at run + time by the set_ftrace_filter file in the debugfs + tracing directory. + + ftrace_notrace=[function-list] + [FTRACE] Do not trace the functions specified in + function-list. This list can be changed at run time + by the set_ftrace_notrace file in the debugfs + tracing directory. + + ftrace_graph_filter=[function-list] + [FTRACE] Limit the top level callers functions traced + by the function graph tracer at boot up. + function-list is a comma separated list of functions + that can be changed at run time by the + set_graph_function file in the debugfs tracing directory. + + ftrace_graph_notrace=[function-list] + [FTRACE] Do not trace from the functions specified in + function-list. This list is a comma separated list of + functions that can be changed at run time by the + set_graph_notrace file in the debugfs tracing directory. + + gamecon.map[2|3]= + [HW,JOY] Multisystem joystick and NES/SNES/PSX pad + support via parallel port (up to 5 devices per port) + Format: ,,,,, + See also Documentation/input/joystick-parport.txt + + gamma= [HW,DRM] + + gart_fix_e820= [X86_64] disable the fix e820 for K8 GART + Format: off | on + default: on + + gcov_persist= [GCOV] When non-zero (default), profiling data for + kernel modules is saved and remains accessible via + debugfs, even when the module is unloaded/reloaded. + When zero, profiling data is discarded and associated + debugfs files are removed at module unload time. + + gpt [EFI] Forces disk with valid GPT signature but + invalid Protective MBR to be treated as GPT. If the + primary GPT is corrupted, it enables the backup/alternate + GPT to be used instead. + + grcan.enable0= [HW] Configuration of physical interface 0. Determines + the "Enable 0" bit of the configuration register. + Format: 0 | 1 + Default: 0 + grcan.enable1= [HW] Configuration of physical interface 1. Determines + the "Enable 0" bit of the configuration register. + Format: 0 | 1 + Default: 0 + grcan.select= [HW] Select which physical interface to use. + Format: 0 | 1 + Default: 0 + grcan.txsize= [HW] Sets the size of the tx buffer. + Format: such that (txsize & ~0x1fffc0) == 0. + Default: 1024 + grcan.rxsize= [HW] Sets the size of the rx buffer. + Format: such that (rxsize & ~0x1fffc0) == 0. + Default: 1024 + + gpio-mockup.gpio_mockup_ranges + [HW] Sets the ranges of gpiochip of for this device. + Format: ,,,... + + hardlockup_all_cpu_backtrace= + [KNL] Should the hard-lockup detector generate + backtraces on all cpus. + Format: + + hashdist= [KNL,NUMA] Large hashes allocated during boot + are distributed across NUMA nodes. Defaults on + for 64-bit NUMA, off otherwise. + Format: 0 | 1 (for off | on) + + hcl= [IA-64] SGI's Hardware Graph compatibility layer + + hd= [EIDE] (E)IDE hard drive subsystem geometry + Format: ,, + + hest_disable [ACPI] + Disable Hardware Error Source Table (HEST) support; + corresponding firmware-first mode error processing + logic will be disabled. + + highmem=nn[KMG] [KNL,BOOT] forces the highmem zone to have an exact + size of . This works even on boxes that have no + highmem otherwise. This also works to reduce highmem + size on bigger boxes. + + highres= [KNL] Enable/disable high resolution timer mode. + Valid parameters: "on", "off" + Default: "on" + + hisax= [HW,ISDN] + See Documentation/isdn/README.HiSax. + + hlt [BUGS=ARM,SH] + + hpet= [X86-32,HPET] option to control HPET usage + Format: { enable (default) | disable | force | + verbose } + disable: disable HPET and use PIT instead + force: allow force enabled of undocumented chips (ICH4, + VIA, nVidia) + verbose: show contents of HPET registers during setup + + hpet_mmap= [X86, HPET_MMAP] Allow userspace to mmap HPET + registers. Default set by CONFIG_HPET_MMAP_DEFAULT. + + hugepages= [HW,X86-32,IA-64] HugeTLB pages to allocate at boot. + hugepagesz= [HW,IA-64,PPC,X86-64] The size of the HugeTLB pages. + On x86-64 and powerpc, this option can be specified + multiple times interleaved with hugepages= to reserve + huge pages of different sizes. Valid pages sizes on + x86-64 are 2M (when the CPU supports "pse") and 1G + (when the CPU supports the "pdpe1gb" cpuinfo flag). + + hvc_iucv= [S390] Number of z/VM IUCV hypervisor console (HVC) + terminal devices. Valid values: 0..8 + hvc_iucv_allow= [S390] Comma-separated list of z/VM user IDs. + If specified, z/VM IUCV HVC accepts connections + from listed z/VM user IDs only. + + hwthread_map= [METAG] Comma-separated list of Linux cpu id to + hardware thread id mappings. + Format: : + + keep_bootcon [KNL] + Do not unregister boot console at start. This is only + useful for debugging when something happens in the window + between unregistering the boot console and initializing + the real console. + + i2c_bus= [HW] Override the default board specific I2C bus speed + or register an additional I2C bus that is not + registered from board initialization code. + Format: + , + + i8042.debug [HW] Toggle i8042 debug mode + i8042.unmask_kbd_data + [HW] Enable printing of interrupt data from the KBD port + (disabled by default, and as a pre-condition + requires that i8042.debug=1 be enabled) + i8042.direct [HW] Put keyboard port into non-translated mode + i8042.dumbkbd [HW] Pretend that controller can only read data from + keyboard and cannot control its state + (Don't attempt to blink the leds) + i8042.noaux [HW] Don't check for auxiliary (== mouse) port + i8042.nokbd [HW] Don't check/create keyboard port + i8042.noloop [HW] Disable the AUX Loopback command while probing + for the AUX port + i8042.nomux [HW] Don't check presence of an active multiplexing + controller + i8042.nopnp [HW] Don't use ACPIPnP / PnPBIOS to discover KBD/AUX + controllers + i8042.notimeout [HW] Ignore timeout condition signalled by controller + i8042.reset [HW] Reset the controller during init, cleanup and + suspend-to-ram transitions, only during s2r + transitions, or never reset + Format: { 1 | Y | y | 0 | N | n } + 1, Y, y: always reset controller + 0, N, n: don't ever reset controller + Default: only on s2r transitions on x86; most other + architectures force reset to be always executed + i8042.unlock [HW] Unlock (ignore) the keylock + i8042.kbdreset [HW] Reset device connected to KBD port + + i810= [HW,DRM] + + i8k.ignore_dmi [HW] Continue probing hardware even if DMI data + indicates that the driver is running on unsupported + hardware. + i8k.force [HW] Activate i8k driver even if SMM BIOS signature + does not match list of supported models. + i8k.power_status + [HW] Report power status in /proc/i8k + (disabled by default) + i8k.restricted [HW] Allow controlling fans only if SYS_ADMIN + capability is set. + + i915.invert_brightness= + [DRM] Invert the sense of the variable that is used to + set the brightness of the panel backlight. Normally a + brightness value of 0 indicates backlight switched off, + and the maximum of the brightness value sets the backlight + to maximum brightness. If this parameter is set to 0 + (default) and the machine requires it, or this parameter + is set to 1, a brightness value of 0 sets the backlight + to maximum brightness, and the maximum of the brightness + value switches the backlight off. + -1 -- never invert brightness + 0 -- machine default + 1 -- force brightness inversion + + icn= [HW,ISDN] + Format: [,[,[,]]] + + ide-core.nodma= [HW] (E)IDE subsystem + Format: =0.0 to prevent dma on hda, =0.1 hdb =1.0 hdc + .vlb_clock .pci_clock .noflush .nohpa .noprobe .nowerr + .cdrom .chs .ignore_cable are additional options + See Documentation/ide/ide.txt. + + ide-generic.probe-mask= [HW] (E)IDE subsystem + Format: + Probe mask for legacy ISA IDE ports. Depending on + platform up to 6 ports are supported, enabled by + setting corresponding bits in the mask to 1. The + default value is 0x0, which has a special meaning. + On systems that have PCI, it triggers scanning the + PCI bus for the first and the second port, which + are then probed. On systems without PCI the value + of 0x0 enables probing the two first ports as if it + was 0x3. + + ide-pci-generic.all-generic-ide [HW] (E)IDE subsystem + Claim all unknown PCI IDE storage controllers. + + idle= [X86] + Format: idle=poll, idle=halt, idle=nomwait + Poll forces a polling idle loop that can slightly + improve the performance of waking up a idle CPU, but + will use a lot of power and make the system run hot. + Not recommended. + idle=halt: Halt is forced to be used for CPU idle. + In such case C2/C3 won't be used again. + idle=nomwait: Disable mwait for CPU C-states + + ieee754= [MIPS] Select IEEE Std 754 conformance mode + Format: { strict | legacy | 2008 | relaxed } + Default: strict + + Choose which programs will be accepted for execution + based on the IEEE 754 NaN encoding(s) supported by + the FPU and the NaN encoding requested with the value + of an ELF file header flag individually set by each + binary. Hardware implementations are permitted to + support either or both of the legacy and the 2008 NaN + encoding mode. + + Available settings are as follows: + strict accept binaries that request a NaN encoding + supported by the FPU + legacy only accept legacy-NaN binaries, if supported + by the FPU + 2008 only accept 2008-NaN binaries, if supported + by the FPU + relaxed accept any binaries regardless of whether + supported by the FPU + + The FPU emulator is always able to support both NaN + encodings, so if no FPU hardware is present or it has + been disabled with 'nofpu', then the settings of + 'legacy' and '2008' strap the emulator accordingly, + 'relaxed' straps the emulator for both legacy-NaN and + 2008-NaN, whereas 'strict' enables legacy-NaN only on + legacy processors and both NaN encodings on MIPS32 or + MIPS64 CPUs. + + The setting for ABS.fmt/NEG.fmt instruction execution + mode generally follows that for the NaN encoding, + except where unsupported by hardware. + + ignore_loglevel [KNL] + Ignore loglevel setting - this will print /all/ + kernel messages to the console. Useful for debugging. + We also add it as printk module parameter, so users + could change it dynamically, usually by + /sys/module/printk/parameters/ignore_loglevel. + + ignore_rlimit_data + Ignore RLIMIT_DATA setting for data mappings, + print warning at first misuse. Can be changed via + /sys/module/kernel/parameters/ignore_rlimit_data. + + ihash_entries= [KNL] + Set number of hash buckets for inode cache. + + ima_appraise= [IMA] appraise integrity measurements + Format: { "off" | "enforce" | "fix" | "log" } + default: "enforce" + + ima_appraise_tcb [IMA] + The builtin appraise policy appraises all files + owned by uid=0. + + ima_hash= [IMA] + Format: { md5 | sha1 | rmd160 | sha256 | sha384 + | sha512 | ... } + default: "sha1" + + The list of supported hash algorithms is defined + in crypto/hash_info.h. + + ima_policy= [IMA] + The builtin measurement policy to load during IMA + setup. Specyfing "tcb" as the value, measures all + programs exec'd, files mmap'd for exec, and all files + opened with the read mode bit set by either the + effective uid (euid=0) or uid=0. + Format: "tcb" + + ima_tcb [IMA] Deprecated. Use ima_policy= instead. + Load a policy which meets the needs of the Trusted + Computing Base. This means IMA will measure all + programs exec'd, files mmap'd for exec, and all files + opened for read by uid=0. + + ima_template= [IMA] + Select one of defined IMA measurements template formats. + Formats: { "ima" | "ima-ng" | "ima-sig" } + Default: "ima-ng" + + ima_template_fmt= + [IMA] Define a custom template format. + Format: { "field1|...|fieldN" } + + ima.ahash_minsize= [IMA] Minimum file size for asynchronous hash usage + Format: + Set the minimal file size for using asynchronous hash. + If left unspecified, ahash usage is disabled. + + ahash performance varies for different data sizes on + different crypto accelerators. This option can be used + to achieve the best performance for a particular HW. + + ima.ahash_bufsize= [IMA] Asynchronous hash buffer size + Format: + Set hashing buffer size. Default: 4k. + + ahash performance varies for different chunk sizes on + different crypto accelerators. This option can be used + to achieve best performance for particular HW. + + init= [KNL] + Format: + Run specified binary instead of /sbin/init as init + process. + + initcall_debug [KNL] Trace initcalls as they are executed. Useful + for working out where the kernel is dying during + startup. + + initcall_blacklist= [KNL] Do not execute a comma-separated list of + initcall functions. Useful for debugging built-in + modules and initcalls. + + initrd= [BOOT] Specify the location of the initial ramdisk + + init_pkru= [x86] Specify the default memory protection keys rights + register contents for all processes. 0x55555554 by + default (disallow access to all but pkey 0). Can + override in debugfs after boot. + + inport.irq= [HW] Inport (ATI XL and Microsoft) busmouse driver + Format: + + int_pln_enable [x86] Enable power limit notification interrupt + + integrity_audit=[IMA] + Format: { "0" | "1" } + 0 -- basic integrity auditing messages. (Default) + 1 -- additional integrity auditing messages. + + intel_iommu= [DMAR] Intel IOMMU driver (DMAR) option + on + Enable intel iommu driver. + off + Disable intel iommu driver. + igfx_off [Default Off] + By default, gfx is mapped as normal device. If a gfx + device has a dedicated DMAR unit, the DMAR unit is + bypassed by not enabling DMAR with this option. In + this case, gfx device will use physical address for + DMA. + forcedac [x86_64] + With this option iommu will not optimize to look + for io virtual address below 32-bit forcing dual + address cycle on pci bus for cards supporting greater + than 32-bit addressing. The default is to look + for translation below 32-bit and if not available + then look in the higher range. + strict [Default Off] + With this option on every unmap_single operation will + result in a hardware IOTLB flush operation as opposed + to batching them for performance. + sp_off [Default Off] + By default, super page will be supported if Intel IOMMU + has the capability. With this option, super page will + not be supported. + ecs_off [Default Off] + By default, extended context tables will be supported if + the hardware advertises that it has support both for the + extended tables themselves, and also PASID support. With + this option set, extended tables will not be used even + on hardware which claims to support them. + + intel_idle.max_cstate= [KNL,HW,ACPI,X86] + 0 disables intel_idle and fall back on acpi_idle. + 1 to 9 specify maximum depth of C-state. + + intel_pstate= [X86] + disable + Do not enable intel_pstate as the default + scaling driver for the supported processors + force + Enable intel_pstate on systems that prohibit it by default + in favor of acpi-cpufreq. Forcing the intel_pstate driver + instead of acpi-cpufreq may disable platform features, such + as thermal controls and power capping, that rely on ACPI + P-States information being indicated to OSPM and therefore + should be used with caution. This option does not work with + processors that aren't supported by the intel_pstate driver + or on platforms that use pcc-cpufreq instead of acpi-cpufreq. + no_hwp + Do not enable hardware P state control (HWP) + if available. + hwp_only + Only load intel_pstate on systems which support + hardware P state control (HWP) if available. + support_acpi_ppc + Enforce ACPI _PPC performance limits. If the Fixed ACPI + Description Table, specifies preferred power management + profile as "Enterprise Server" or "Performance Server", + then this feature is turned on by default. + + intremap= [X86-64, Intel-IOMMU] + on enable Interrupt Remapping (default) + off disable Interrupt Remapping + nosid disable Source ID checking + no_x2apic_optout + BIOS x2APIC opt-out request will be ignored + nopost disable Interrupt Posting + + iomem= Disable strict checking of access to MMIO memory + strict regions from userspace. + relaxed + + iommu= [x86] + off + force + noforce + biomerge + panic + nopanic + merge + nomerge + forcesac + soft + pt [x86, IA-64] + nobypass [PPC/POWERNV] + Disable IOMMU bypass, using IOMMU for PCI devices. + + + io7= [HW] IO7 for Marvel based alpha systems + See comment before marvel_specify_io7 in + arch/alpha/kernel/core_marvel.c. + + io_delay= [X86] I/O delay method + 0x80 + Standard port 0x80 based delay + 0xed + Alternate port 0xed based delay (needed on some systems) + udelay + Simple two microseconds delay + none + No delay + + ip= [IP_PNP] + See Documentation/filesystems/nfs/nfsroot.txt. + + irqaffinity= [SMP] Set the default irq affinity mask + The argument is a cpu list, as described above. + + irqfixup [HW] + When an interrupt is not handled search all handlers + for it. Intended to get systems with badly broken + firmware running. + + irqpoll [HW] + When an interrupt is not handled search all handlers + for it. Also check all handlers each timer + interrupt. Intended to get systems with badly broken + firmware running. + + isapnp= [ISAPNP] + Format: ,,, + + isolcpus= [KNL,SMP] Isolate CPUs from the general scheduler. + The argument is a cpu list, as described above. + + This option can be used to specify one or more CPUs + to isolate from the general SMP balancing and scheduling + algorithms. You can move a process onto or off an + "isolated" CPU via the CPU affinity syscalls or cpuset. + begins at 0 and the maximum value is + "number of CPUs in system - 1". + + This option is the preferred way to isolate CPUs. The + alternative -- manually setting the CPU mask of all + tasks in the system -- can cause problems and + suboptimal load balancer performance. + + iucv= [HW,NET] + + ivrs_ioapic [HW,X86_64] + Provide an override to the IOAPIC-ID<->DEVICE-ID + mapping provided in the IVRS ACPI table. For + example, to map IOAPIC-ID decimal 10 to + PCI device 00:14.0 write the parameter as: + ivrs_ioapic[10]=00:14.0 + + ivrs_hpet [HW,X86_64] + Provide an override to the HPET-ID<->DEVICE-ID + mapping provided in the IVRS ACPI table. For + example, to map HPET-ID decimal 0 to + PCI device 00:14.0 write the parameter as: + ivrs_hpet[0]=00:14.0 + + ivrs_acpihid [HW,X86_64] + Provide an override to the ACPI-HID:UID<->DEVICE-ID + mapping provided in the IVRS ACPI table. For + example, to map UART-HID:UID AMD0020:0 to + PCI device 00:14.5 write the parameter as: + ivrs_acpihid[00:14.5]=AMD0020:0 + + js= [HW,JOY] Analog joystick + See Documentation/input/joystick.txt. + + nokaslr [KNL] + When CONFIG_RANDOMIZE_BASE is set, this disables + kernel and module base offset ASLR (Address Space + Layout Randomization). + + keepinitrd [HW,ARM] + + kernelcore= [KNL,X86,IA-64,PPC] + Format: nn[KMGTPE] | "mirror" + This parameter + specifies the amount of memory usable by the kernel + for non-movable allocations. The requested amount is + spread evenly throughout all nodes in the system. The + remaining memory in each node is used for Movable + pages. In the event, a node is too small to have both + kernelcore and Movable pages, kernelcore pages will + take priority and other nodes will have a larger number + of Movable pages. The Movable zone is used for the + allocation of pages that may be reclaimed or moved + by the page migration subsystem. This means that + HugeTLB pages may not be allocated from this zone. + Note that allocations like PTEs-from-HighMem still + use the HighMem zone if it exists, and the Normal + zone if it does not. + + Instead of specifying the amount of memory (nn[KMGTPE]), + you can specify "mirror" option. In case "mirror" + option is specified, mirrored (reliable) memory is used + for non-movable allocations and remaining memory is used + for Movable pages. nn[KMGTPE] and "mirror" are exclusive, + so you can NOT specify nn[KMGTPE] and "mirror" at the same + time. + + kgdbdbgp= [KGDB,HW] kgdb over EHCI usb debug port. + Format: [,poll interval] + The controller # is the number of the ehci usb debug + port as it is probed via PCI. The poll interval is + optional and is the number seconds in between + each poll cycle to the debug port in case you need + the functionality for interrupting the kernel with + gdb or control-c on the dbgp connection. When + not using this parameter you use sysrq-g to break into + the kernel debugger. + + kgdboc= [KGDB,HW] kgdb over consoles. + Requires a tty driver that supports console polling, + or a supported polling keyboard driver (non-usb). + Serial only format: [,baud] + keyboard only format: kbd + keyboard and serial format: kbd,[,baud] + Optional Kernel mode setting: + kms, kbd format: kms,kbd + kms, kbd and serial format: kms,kbd,[,baud] + + kgdbwait [KGDB] Stop kernel execution and enter the + kernel debugger at the earliest opportunity. + + kmac= [MIPS] korina ethernet MAC address. + Configure the RouterBoard 532 series on-chip + Ethernet adapter MAC address. + + kmemleak= [KNL] Boot-time kmemleak enable/disable + Valid arguments: on, off + Default: on + Built with CONFIG_DEBUG_KMEMLEAK_DEFAULT_OFF=y, + the default is off. + + kmemcheck= [X86] Boot-time kmemcheck enable/disable/one-shot mode + Valid arguments: 0, 1, 2 + kmemcheck=0 (disabled) + kmemcheck=1 (enabled) + kmemcheck=2 (one-shot mode) + Default: 2 (one-shot mode) + + kstack=N [X86] Print N words from the kernel stack + in oops dumps. + + kvm.ignore_msrs=[KVM] Ignore guest accesses to unhandled MSRs. + Default is 0 (don't ignore, but inject #GP) + + kvm.mmu_audit= [KVM] This is a R/W parameter which allows audit + KVM MMU at runtime. + Default is 0 (off) + + kvm-amd.nested= [KVM,AMD] Allow nested virtualization in KVM/SVM. + Default is 1 (enabled) + + kvm-amd.npt= [KVM,AMD] Disable nested paging (virtualized MMU) + for all guests. + Default is 1 (enabled) if in 64-bit or 32-bit PAE mode. + + kvm-intel.ept= [KVM,Intel] Disable extended page tables + (virtualized MMU) support on capable Intel chips. + Default is 1 (enabled) + + kvm-intel.emulate_invalid_guest_state= + [KVM,Intel] Enable emulation of invalid guest states + Default is 0 (disabled) + + kvm-intel.flexpriority= + [KVM,Intel] Disable FlexPriority feature (TPR shadow). + Default is 1 (enabled) + + kvm-intel.nested= + [KVM,Intel] Enable VMX nesting (nVMX). + Default is 0 (disabled) + + kvm-intel.unrestricted_guest= + [KVM,Intel] Disable unrestricted guest feature + (virtualized real and unpaged mode) on capable + Intel chips. Default is 1 (enabled) + + kvm-intel.vpid= [KVM,Intel] Disable Virtual Processor Identification + feature (tagged TLBs) on capable Intel chips. + Default is 1 (enabled) + + l2cr= [PPC] + + l3cr= [PPC] + + lapic [X86-32,APIC] Enable the local APIC even if BIOS + disabled it. + + lapic= [x86,APIC] "notscdeadline" Do not use TSC deadline + value for LAPIC timer one-shot implementation. Default + back to the programmable timer unit in the LAPIC. + + lapic_timer_c2_ok [X86,APIC] trust the local apic timer + in C2 power state. + + libata.dma= [LIBATA] DMA control + libata.dma=0 Disable all PATA and SATA DMA + libata.dma=1 PATA and SATA Disk DMA only + libata.dma=2 ATAPI (CDROM) DMA only + libata.dma=4 Compact Flash DMA only + Combinations also work, so libata.dma=3 enables DMA + for disks and CDROMs, but not CFs. + + libata.ignore_hpa= [LIBATA] Ignore HPA limit + libata.ignore_hpa=0 keep BIOS limits (default) + libata.ignore_hpa=1 ignore limits, using full disk + + libata.noacpi [LIBATA] Disables use of ACPI in libata suspend/resume + when set. + Format: + + libata.force= [LIBATA] Force configurations. The format is comma + separated list of "[ID:]VAL" where ID is + PORT[.DEVICE]. PORT and DEVICE are decimal numbers + matching port, link or device. Basically, it matches + the ATA ID string printed on console by libata. If + the whole ID part is omitted, the last PORT and DEVICE + values are used. If ID hasn't been specified yet, the + configuration applies to all ports, links and devices. + + If only DEVICE is omitted, the parameter applies to + the port and all links and devices behind it. DEVICE + number of 0 either selects the first device or the + first fan-out link behind PMP device. It does not + select the host link. DEVICE number of 15 selects the + host link and device attached to it. + + The VAL specifies the configuration to force. As long + as there's no ambiguity shortcut notation is allowed. + For example, both 1.5 and 1.5G would work for 1.5Gbps. + The following configurations can be forced. + + * Cable type: 40c, 80c, short40c, unk, ign or sata. + Any ID with matching PORT is used. + + * SATA link speed limit: 1.5Gbps or 3.0Gbps. + + * Transfer mode: pio[0-7], mwdma[0-4] and udma[0-7]. + udma[/][16,25,33,44,66,100,133] notation is also + allowed. + + * [no]ncq: Turn on or off NCQ. + + * [no]ncqtrim: Turn off queued DSM TRIM. + + * nohrst, nosrst, norst: suppress hard, soft + and both resets. + + * rstonce: only attempt one reset during + hot-unplug link recovery + + * dump_id: dump IDENTIFY data. + + * atapi_dmadir: Enable ATAPI DMADIR bridge support + + * disable: Disable this device. + + If there are multiple matching configurations changing + the same attribute, the last one is used. + + memblock=debug [KNL] Enable memblock debug messages. + + load_ramdisk= [RAM] List of ramdisks to load from floppy + See Documentation/blockdev/ramdisk.txt. + + lockd.nlm_grace_period=P [NFS] Assign grace period. + Format: + + lockd.nlm_tcpport=N [NFS] Assign TCP port. + Format: + + lockd.nlm_timeout=T [NFS] Assign timeout value. + Format: + + lockd.nlm_udpport=M [NFS] Assign UDP port. + Format: + + locktorture.nreaders_stress= [KNL] + Set the number of locking read-acquisition kthreads. + Defaults to being automatically set based on the + number of online CPUs. + + locktorture.nwriters_stress= [KNL] + Set the number of locking write-acquisition kthreads. + + locktorture.onoff_holdoff= [KNL] + Set time (s) after boot for CPU-hotplug testing. + + locktorture.onoff_interval= [KNL] + Set time (s) between CPU-hotplug operations, or + zero to disable CPU-hotplug testing. + + locktorture.shuffle_interval= [KNL] + Set task-shuffle interval (jiffies). Shuffling + tasks allows some CPUs to go into dyntick-idle + mode during the locktorture test. + + locktorture.shutdown_secs= [KNL] + Set time (s) after boot system shutdown. This + is useful for hands-off automated testing. + + locktorture.stat_interval= [KNL] + Time (s) between statistics printk()s. + + locktorture.stutter= [KNL] + Time (s) to stutter testing, for example, + specifying five seconds causes the test to run for + five seconds, wait for five seconds, and so on. + This tests the locking primitive's ability to + transition abruptly to and from idle. + + locktorture.torture_runnable= [BOOT] + Start locktorture running at boot time. + + locktorture.torture_type= [KNL] + Specify the locking implementation to test. + + locktorture.verbose= [KNL] + Enable additional printk() statements. + + logibm.irq= [HW,MOUSE] Logitech Bus Mouse Driver + Format: + + loglevel= All Kernel Messages with a loglevel smaller than the + console loglevel will be printed to the console. It can + also be changed with klogd or other programs. The + loglevels are defined as follows: + + 0 (KERN_EMERG) system is unusable + 1 (KERN_ALERT) action must be taken immediately + 2 (KERN_CRIT) critical conditions + 3 (KERN_ERR) error conditions + 4 (KERN_WARNING) warning conditions + 5 (KERN_NOTICE) normal but significant condition + 6 (KERN_INFO) informational + 7 (KERN_DEBUG) debug-level messages + + log_buf_len=n[KMG] Sets the size of the printk ring buffer, + in bytes. n must be a power of two and greater + than the minimal size. The minimal size is defined + by LOG_BUF_SHIFT kernel config parameter. There is + also CONFIG_LOG_CPU_MAX_BUF_SHIFT config parameter + that allows to increase the default size depending on + the number of CPUs. See init/Kconfig for more details. + + logo.nologo [FB] Disables display of the built-in Linux logo. + This may be used to provide more screen space for + kernel log messages and is useful when debugging + kernel boot problems. + + lp=0 [LP] Specify parallel ports to use, e.g, + lp=port[,port...] lp=none,parport0 (lp0 not configured, lp1 uses + lp=reset first parallel port). 'lp=0' disables the + lp=auto printer driver. 'lp=reset' (which can be + specified in addition to the ports) causes + attached printers to be reset. Using + lp=port1,port2,... specifies the parallel ports + to associate lp devices with, starting with + lp0. A port specification may be 'none' to skip + that lp device, or a parport name such as + 'parport0'. Specifying 'lp=auto' instead of a + port specification list means that device IDs + from each port should be examined, to see if + an IEEE 1284-compliant printer is attached; if + so, the driver will manage that printer. + See also header of drivers/char/lp.c. + + lpj=n [KNL] + Sets loops_per_jiffy to given constant, thus avoiding + time-consuming boot-time autodetection (up to 250 ms per + CPU). 0 enables autodetection (default). To determine + the correct value for your kernel, boot with normal + autodetection and see what value is printed. Note that + on SMP systems the preset will be applied to all CPUs, + which is likely to cause problems if your CPUs need + significantly divergent settings. An incorrect value + will cause delays in the kernel to be wrong, leading to + unpredictable I/O errors and other breakage. Although + unlikely, in the extreme case this might damage your + hardware. + + ltpc= [NET] + Format: ,, + + machvec= [IA-64] Force the use of a particular machine-vector + (machvec) in a generic kernel. + Example: machvec=hpzx1_swiotlb + + machtype= [Loongson] Share the same kernel image file between different + yeeloong laptop. + Example: machtype=lemote-yeeloong-2f-7inch + + max_addr=nn[KMG] [KNL,BOOT,ia64] All physical memory greater + than or equal to this physical address is ignored. + + maxcpus= [SMP] Maximum number of processors that an SMP kernel + will bring up during bootup. maxcpus=n : n >= 0 limits + the kernel to bring up 'n' processors. Surely after + bootup you can bring up the other plugged cpu by executing + "echo 1 > /sys/devices/system/cpu/cpuX/online". So maxcpus + only takes effect during system bootup. + While n=0 is a special case, it is equivalent to "nosmp", + which also disables the IO APIC. + + max_loop= [LOOP] The number of loop block devices that get + (loop.max_loop) unconditionally pre-created at init time. The default + number is configured by BLK_DEV_LOOP_MIN_COUNT. Instead + of statically allocating a predefined number, loop + devices can be requested on-demand with the + /dev/loop-control interface. + + mce [X86-32] Machine Check Exception + + mce=option [X86-64] See Documentation/x86/x86_64/boot-options.txt + + md= [HW] RAID subsystems devices and level + See Documentation/md.txt. + + mdacon= [MDA] + Format: , + Specifies range of consoles to be captured by the MDA. + + mem=nn[KMG] [KNL,BOOT] Force usage of a specific amount of memory + Amount of memory to be used when the kernel is not able + to see the whole system memory or for test. + [X86] Work as limiting max address. Use together + with memmap= to avoid physical address space collisions. + Without memmap= PCI devices could be placed at addresses + belonging to unused RAM. + + mem=nopentium [BUGS=X86-32] Disable usage of 4MB pages for kernel + memory. + + memchunk=nn[KMG] + [KNL,SH] Allow user to override the default size for + per-device physically contiguous DMA buffers. + + memhp_default_state=online/offline + [KNL] Set the initial state for the memory hotplug + onlining policy. If not specified, the default value is + set according to the + CONFIG_MEMORY_HOTPLUG_DEFAULT_ONLINE kernel config + option. + See Documentation/memory-hotplug.txt. + + memmap=exactmap [KNL,X86] Enable setting of an exact + E820 memory map, as specified by the user. + Such memmap=exactmap lines can be constructed based on + BIOS output or other requirements. See the memmap=nn@ss + option description. + + memmap=nn[KMG]@ss[KMG] + [KNL] Force usage of a specific region of memory. + Region of memory to be used is from ss to ss+nn. + + memmap=nn[KMG]#ss[KMG] + [KNL,ACPI] Mark specific memory as ACPI data. + Region of memory to be marked is from ss to ss+nn. + + memmap=nn[KMG]$ss[KMG] + [KNL,ACPI] Mark specific memory as reserved. + Region of memory to be reserved is from ss to ss+nn. + Example: Exclude memory from 0x18690000-0x1869ffff + memmap=64K$0x18690000 + or + memmap=0x10000$0x18690000 + + memmap=nn[KMG]!ss[KMG] + [KNL,X86] Mark specific memory as protected. + Region of memory to be used, from ss to ss+nn. + The memory region may be marked as e820 type 12 (0xc) + and is NVDIMM or ADR memory. + + memory_corruption_check=0/1 [X86] + Some BIOSes seem to corrupt the first 64k of + memory when doing things like suspend/resume. + Setting this option will scan the memory + looking for corruption. Enabling this will + both detect corruption and prevent the kernel + from using the memory being corrupted. + However, its intended as a diagnostic tool; if + repeatable BIOS-originated corruption always + affects the same memory, you can use memmap= + to prevent the kernel from using that memory. + + memory_corruption_check_size=size [X86] + By default it checks for corruption in the low + 64k, making this memory unavailable for normal + use. Use this parameter to scan for + corruption in more or less memory. + + memory_corruption_check_period=seconds [X86] + By default it checks for corruption every 60 + seconds. Use this parameter to check at some + other rate. 0 disables periodic checking. + + memtest= [KNL,X86,ARM] Enable memtest + Format: + default : 0 + Specifies the number of memtest passes to be + performed. Each pass selects another test + pattern from a given set of patterns. Memtest + fills the memory with this pattern, validates + memory contents and reserves bad memory + regions that are detected. + + meye.*= [HW] Set MotionEye Camera parameters + See Documentation/video4linux/meye.txt. + + mfgpt_irq= [IA-32] Specify the IRQ to use for the + Multi-Function General Purpose Timers on AMD Geode + platforms. + + mfgptfix [X86-32] Fix MFGPT timers on AMD Geode platforms when + the BIOS has incorrectly applied a workaround. TinyBIOS + version 0.98 is known to be affected, 0.99 fixes the + problem by letting the user disable the workaround. + + mga= [HW,DRM] + + min_addr=nn[KMG] [KNL,BOOT,ia64] All physical memory below this + physical address is ignored. + + mini2440= [ARM,HW,KNL] + Format:[0..2][b][c][t] + Default: "0tb" + MINI2440 configuration specification: + 0 - The attached screen is the 3.5" TFT + 1 - The attached screen is the 7" TFT + 2 - The VGA Shield is attached (1024x768) + Leaving out the screen size parameter will not load + the TFT driver, and the framebuffer will be left + unconfigured. + b - Enable backlight. The TFT backlight pin will be + linked to the kernel VESA blanking code and a GPIO + LED. This parameter is not necessary when using the + VGA shield. + c - Enable the s3c camera interface. + t - Reserved for enabling touchscreen support. The + touchscreen support is not enabled in the mainstream + kernel as of 2.6.30, a preliminary port can be found + in the "bleeding edge" mini2440 support kernel at + http://repo.or.cz/w/linux-2.6/mini2440.git + + mminit_loglevel= + [KNL] When CONFIG_DEBUG_MEMORY_INIT is set, this + parameter allows control of the logging verbosity for + the additional memory initialisation checks. A value + of 0 disables mminit logging and a level of 4 will + log everything. Information is printed at KERN_DEBUG + so loglevel=8 may also need to be specified. + + module.sig_enforce + [KNL] When CONFIG_MODULE_SIG is set, this means that + modules without (valid) signatures will fail to load. + Note that if CONFIG_MODULE_SIG_FORCE is set, that + is always true, so this option does nothing. + + module_blacklist= [KNL] Do not load a comma-separated list of + modules. Useful for debugging problem modules. + + mousedev.tap_time= + [MOUSE] Maximum time between finger touching and + leaving touchpad surface for touch to be considered + a tap and be reported as a left button click (for + touchpads working in absolute mode only). + Format: + mousedev.xres= [MOUSE] Horizontal screen resolution, used for devices + reporting absolute coordinates, such as tablets + mousedev.yres= [MOUSE] Vertical screen resolution, used for devices + reporting absolute coordinates, such as tablets + + movablecore=nn[KMG] [KNL,X86,IA-64,PPC] This parameter + is similar to kernelcore except it specifies the + amount of memory used for migratable allocations. + If both kernelcore and movablecore is specified, + then kernelcore will be at *least* the specified + value but may be more. If movablecore on its own + is specified, the administrator must be careful + that the amount of memory usable for all allocations + is not too small. + + movable_node [KNL,X86] Boot-time switch to enable the effects + of CONFIG_MOVABLE_NODE=y. See mm/Kconfig for details. + + MTD_Partition= [MTD] + Format: ,,, + + MTD_Region= [MTD] Format: + ,[,,,,] + + mtdparts= [MTD] + See drivers/mtd/cmdlinepart.c. + + multitce=off [PPC] This parameter disables the use of the pSeries + firmware feature for updating multiple TCE entries + at a time. + + onenand.bdry= [HW,MTD] Flex-OneNAND Boundary Configuration + + Format: [die0_boundary][,die0_lock][,die1_boundary][,die1_lock] + + boundary - index of last SLC block on Flex-OneNAND. + The remaining blocks are configured as MLC blocks. + lock - Configure if Flex-OneNAND boundary should be locked. + Once locked, the boundary cannot be changed. + 1 indicates lock status, 0 indicates unlock status. + + mtdset= [ARM] + ARM/S3C2412 JIVE boot control + + See arch/arm/mach-s3c2412/mach-jive.c + + mtouchusb.raw_coordinates= + [HW] Make the MicroTouch USB driver use raw coordinates + ('y', default) or cooked coordinates ('n') + + mtrr_chunk_size=nn[KMG] [X86] + used for mtrr cleanup. It is largest continuous chunk + that could hold holes aka. UC entries. + + mtrr_gran_size=nn[KMG] [X86] + Used for mtrr cleanup. It is granularity of mtrr block. + Default is 1. + Large value could prevent small alignment from + using up MTRRs. + + mtrr_spare_reg_nr=n [X86] + Format: + Range: 0,7 : spare reg number + Default : 1 + Used for mtrr cleanup. It is spare mtrr entries number. + Set to 2 or more if your graphical card needs more. + + n2= [NET] SDL Inc. RISCom/N2 synchronous serial card + + netdev= [NET] Network devices parameters + Format: ,,,, + Note that mem_start is often overloaded to mean + something different and driver-specific. + This usage is only documented in each driver source + file if at all. + + nf_conntrack.acct= + [NETFILTER] Enable connection tracking flow accounting + 0 to disable accounting + 1 to enable accounting + Default value is 0. + + nfsaddrs= [NFS] Deprecated. Use ip= instead. + See Documentation/filesystems/nfs/nfsroot.txt. + + nfsroot= [NFS] nfs root filesystem for disk-less boxes. + See Documentation/filesystems/nfs/nfsroot.txt. + + nfsrootdebug [NFS] enable nfsroot debugging messages. + See Documentation/filesystems/nfs/nfsroot.txt. + + nfs.callback_nr_threads= + [NFSv4] set the total number of threads that the + NFS client will assign to service NFSv4 callback + requests. + + nfs.callback_tcpport= + [NFS] set the TCP port on which the NFSv4 callback + channel should listen. + + nfs.cache_getent= + [NFS] sets the pathname to the program which is used + to update the NFS client cache entries. + + nfs.cache_getent_timeout= + [NFS] sets the timeout after which an attempt to + update a cache entry is deemed to have failed. + + nfs.idmap_cache_timeout= + [NFS] set the maximum lifetime for idmapper cache + entries. + + nfs.enable_ino64= + [NFS] enable 64-bit inode numbers. + If zero, the NFS client will fake up a 32-bit inode + number for the readdir() and stat() syscalls instead + of returning the full 64-bit number. + The default is to return 64-bit inode numbers. + + nfs.max_session_cb_slots= + [NFSv4.1] Sets the maximum number of session + slots the client will assign to the callback + channel. This determines the maximum number of + callbacks the client will process in parallel for + a particular server. + + nfs.max_session_slots= + [NFSv4.1] Sets the maximum number of session slots + the client will attempt to negotiate with the server. + This limits the number of simultaneous RPC requests + that the client can send to the NFSv4.1 server. + Note that there is little point in setting this + value higher than the max_tcp_slot_table_limit. + + nfs.nfs4_disable_idmapping= + [NFSv4] When set to the default of '1', this option + ensures that both the RPC level authentication + scheme and the NFS level operations agree to use + numeric uids/gids if the mount is using the + 'sec=sys' security flavour. In effect it is + disabling idmapping, which can make migration from + legacy NFSv2/v3 systems to NFSv4 easier. + Servers that do not support this mode of operation + will be autodetected by the client, and it will fall + back to using the idmapper. + To turn off this behaviour, set the value to '0'. + nfs.nfs4_unique_id= + [NFS4] Specify an additional fixed unique ident- + ification string that NFSv4 clients can insert into + their nfs_client_id4 string. This is typically a + UUID that is generated at system install time. + + nfs.send_implementation_id = + [NFSv4.1] Send client implementation identification + information in exchange_id requests. + If zero, no implementation identification information + will be sent. + The default is to send the implementation identification + information. + + nfs.recover_lost_locks = + [NFSv4] Attempt to recover locks that were lost due + to a lease timeout on the server. Please note that + doing this risks data corruption, since there are + no guarantees that the file will remain unchanged + after the locks are lost. + If you want to enable the kernel legacy behaviour of + attempting to recover these locks, then set this + parameter to '1'. + The default parameter value of '0' causes the kernel + not to attempt recovery of lost locks. + + nfs4.layoutstats_timer = + [NFSv4.2] Change the rate at which the kernel sends + layoutstats to the pNFS metadata server. + + Setting this to value to 0 causes the kernel to use + whatever value is the default set by the layout + driver. A non-zero value sets the minimum interval + in seconds between layoutstats transmissions. + + nfsd.nfs4_disable_idmapping= + [NFSv4] When set to the default of '1', the NFSv4 + server will return only numeric uids and gids to + clients using auth_sys, and will accept numeric uids + and gids from such clients. This is intended to ease + migration from NFSv2/v3. + + objlayoutdriver.osd_login_prog= + [NFS] [OBJLAYOUT] sets the pathname to the program which + is used to automatically discover and login into new + osd-targets. Please see: + Documentation/filesystems/pnfs.txt for more explanations + + nmi_debug= [KNL,AVR32,SH] Specify one or more actions to take + when a NMI is triggered. + Format: [state][,regs][,debounce][,die] + + nmi_watchdog= [KNL,BUGS=X86] Debugging features for SMP kernels + Format: [panic,][nopanic,][num] + Valid num: 0 or 1 + 0 - turn hardlockup detector in nmi_watchdog off + 1 - turn hardlockup detector in nmi_watchdog on + When panic is specified, panic when an NMI watchdog + timeout occurs (or 'nopanic' to override the opposite + default). To disable both hard and soft lockup detectors, + please see 'nowatchdog'. + This is useful when you use a panic=... timeout and + need the box quickly up again. + + netpoll.carrier_timeout= + [NET] Specifies amount of time (in seconds) that + netpoll should wait for a carrier. By default netpoll + waits 4 seconds. + + no387 [BUGS=X86-32] Tells the kernel to use the 387 maths + emulation library even if a 387 maths coprocessor + is present. + + no_console_suspend + [HW] Never suspend the console + Disable suspending of consoles during suspend and + hibernate operations. Once disabled, debugging + messages can reach various consoles while the rest + of the system is being put to sleep (ie, while + debugging driver suspend/resume hooks). This may + not work reliably with all consoles, but is known + to work with serial and VGA consoles. + To facilitate more flexible debugging, we also add + console_suspend, a printk module parameter to control + it. Users could use console_suspend (usually + /sys/module/printk/parameters/console_suspend) to + turn on/off it dynamically. + + noaliencache [MM, NUMA, SLAB] Disables the allocation of alien + caches in the slab allocator. Saves per-node memory, + but will impact performance. + + noalign [KNL,ARM] + + noapic [SMP,APIC] Tells the kernel to not make use of any + IOAPICs that may be present in the system. + + noautogroup Disable scheduler automatic task group creation. + + nobats [PPC] Do not use BATs for mapping kernel lowmem + on "Classic" PPC cores. + + nocache [ARM] + + noclflush [BUGS=X86] Don't use the CLFLUSH instruction + + nodelayacct [KNL] Disable per-task delay accounting + + nodsp [SH] Disable hardware DSP at boot time. + + noefi Disable EFI runtime services support. + + noexec [IA-64] + + noexec [X86] + On X86-32 available only on PAE configured kernels. + noexec=on: enable non-executable mappings (default) + noexec=off: disable non-executable mappings + + nosmap [X86] + Disable SMAP (Supervisor Mode Access Prevention) + even if it is supported by processor. + + nosmep [X86] + Disable SMEP (Supervisor Mode Execution Prevention) + even if it is supported by processor. + + noexec32 [X86-64] + This affects only 32-bit executables. + noexec32=on: enable non-executable mappings (default) + read doesn't imply executable mappings + noexec32=off: disable non-executable mappings + read implies executable mappings + + nofpu [MIPS,SH] Disable hardware FPU at boot time. + + nofxsr [BUGS=X86-32] Disables x86 floating point extended + register save and restore. The kernel will only save + legacy floating-point registers on task switch. + + nohugeiomap [KNL,x86] Disable kernel huge I/O mappings. + + nosmt [KNL,S390] Disable symmetric multithreading (SMT). + Equivalent to smt=1. + + noxsave [BUGS=X86] Disables x86 extended register state save + and restore using xsave. The kernel will fallback to + enabling legacy floating-point and sse state. + + noxsaveopt [X86] Disables xsaveopt used in saving x86 extended + register states. The kernel will fall back to use + xsave to save the states. By using this parameter, + performance of saving the states is degraded because + xsave doesn't support modified optimization while + xsaveopt supports it on xsaveopt enabled systems. + + noxsaves [X86] Disables xsaves and xrstors used in saving and + restoring x86 extended register state in compacted + form of xsave area. The kernel will fall back to use + xsaveopt and xrstor to save and restore the states + in standard form of xsave area. By using this + parameter, xsave area per process might occupy more + memory on xsaves enabled systems. + + nohlt [BUGS=ARM,SH] Tells the kernel that the sleep(SH) or + wfi(ARM) instruction doesn't work correctly and not to + use it. This is also useful when using JTAG debugger. + + no_file_caps Tells the kernel not to honor file capabilities. The + only way then for a file to be executed with privilege + is to be setuid root or executed by root. + + nohalt [IA-64] Tells the kernel not to use the power saving + function PAL_HALT_LIGHT when idle. This increases + power-consumption. On the positive side, it reduces + interrupt wake-up latency, which may improve performance + in certain environments such as networked servers or + real-time systems. + + nohibernate [HIBERNATION] Disable hibernation and resume. + + nohz= [KNL] Boottime enable/disable dynamic ticks + Valid arguments: on, off + Default: on + + nohz_full= [KNL,BOOT] + The argument is a cpu list, as described above. + In kernels built with CONFIG_NO_HZ_FULL=y, set + the specified list of CPUs whose tick will be stopped + whenever possible. The boot CPU will be forced outside + the range to maintain the timekeeping. + The CPUs in this range must also be included in the + rcu_nocbs= set. + + noiotrap [SH] Disables trapped I/O port accesses. + + noirqdebug [X86-32] Disables the code which attempts to detect and + disable unhandled interrupt sources. + + no_timer_check [X86,APIC] Disables the code which tests for + broken timer IRQ sources. + + noisapnp [ISAPNP] Disables ISA PnP code. + + noinitrd [RAM] Tells the kernel not to load any configured + initial RAM disk. + + nointremap [X86-64, Intel-IOMMU] Do not enable interrupt + remapping. + [Deprecated - use intremap=off] + + nointroute [IA-64] + + noinvpcid [X86] Disable the INVPCID cpu feature. + + nojitter [IA-64] Disables jitter checking for ITC timers. + + no-kvmclock [X86,KVM] Disable paravirtualized KVM clock driver + + no-kvmapf [X86,KVM] Disable paravirtualized asynchronous page + fault handling. + + no-steal-acc [X86,KVM] Disable paravirtualized steal time accounting. + steal time is computed, but won't influence scheduler + behaviour + + nolapic [X86-32,APIC] Do not enable or use the local APIC. + + nolapic_timer [X86-32,APIC] Do not use the local APIC timer. + + noltlbs [PPC] Do not use large page/tlb entries for kernel + lowmem mapping on PPC40x and PPC8xx + + nomca [IA-64] Disable machine check abort handling + + nomce [X86-32] Disable Machine Check Exception + + nomfgpt [X86-32] Disable Multi-Function General Purpose + Timer usage (for AMD Geode machines). + + nonmi_ipi [X86] Disable using NMI IPIs during panic/reboot to + shutdown the other cpus. Instead use the REBOOT_VECTOR + irq. + + nomodule Disable module load + + nopat [X86] Disable PAT (page attribute table extension of + pagetables) support. + + norandmaps Don't use address space randomization. Equivalent to + echo 0 > /proc/sys/kernel/randomize_va_space + + noreplace-paravirt [X86,IA-64,PV_OPS] Don't patch paravirt_ops + + noreplace-smp [X86-32,SMP] Don't replace SMP instructions + with UP alternatives + + nordrand [X86] Disable kernel use of the RDRAND and + RDSEED instructions even if they are supported + by the processor. RDRAND and RDSEED are still + available to user space applications. + + noresume [SWSUSP] Disables resume and restores original swap + space. + + no-scroll [VGA] Disables scrollback. + This is required for the Braillex ib80-piezo Braille + reader made by F.H. Papenmeier (Germany). + + nosbagart [IA-64] + + nosep [BUGS=X86-32] Disables x86 SYSENTER/SYSEXIT support. + + nosmp [SMP] Tells an SMP kernel to act as a UP kernel, + and disable the IO APIC. legacy for "maxcpus=0". + + nosoftlockup [KNL] Disable the soft-lockup detector. + + nosync [HW,M68K] Disables sync negotiation for all devices. + + notsc [BUGS=X86-32] Disable Time Stamp Counter + + nowatchdog [KNL] Disable both lockup detectors, i.e. + soft-lockup and NMI watchdog (hard-lockup). + + nowb [ARM] + + nox2apic [X86-64,APIC] Do not enable x2APIC mode. + + cpu0_hotplug [X86] Turn on CPU0 hotplug feature when + CONFIG_BOOTPARAM_HOTPLUG_CPU0 is off. + Some features depend on CPU0. Known dependencies are: + 1. Resume from suspend/hibernate depends on CPU0. + Suspend/hibernate will fail if CPU0 is offline and you + need to online CPU0 before suspend/hibernate. + 2. PIC interrupts also depend on CPU0. CPU0 can't be + removed if a PIC interrupt is detected. + It's said poweroff/reboot may depend on CPU0 on some + machines although I haven't seen such issues so far + after CPU0 is offline on a few tested machines. + If the dependencies are under your control, you can + turn on cpu0_hotplug. + + nptcg= [IA-64] Override max number of concurrent global TLB + purges which is reported from either PAL_VM_SUMMARY or + SAL PALO. + + nr_cpus= [SMP] Maximum number of processors that an SMP kernel + could support. nr_cpus=n : n >= 1 limits the kernel to + support 'n' processors. It could be larger than the + number of already plugged CPU during bootup, later in + runtime you can physically add extra cpu until it reaches + n. So during boot up some boot time memory for per-cpu + variables need be pre-allocated for later physical cpu + hot plugging. + + nr_uarts= [SERIAL] maximum number of UARTs to be registered. + + numa_balancing= [KNL,X86] Enable or disable automatic NUMA balancing. + Allowed values are enable and disable + + numa_zonelist_order= [KNL, BOOT] Select zonelist order for NUMA. + one of ['zone', 'node', 'default'] can be specified + This can be set from sysctl after boot. + See Documentation/sysctl/vm.txt for details. + + ohci1394_dma=early [HW] enable debugging via the ohci1394 driver. + See Documentation/debugging-via-ohci1394.txt for more + info. + + olpc_ec_timeout= [OLPC] ms delay when issuing EC commands + Rather than timing out after 20 ms if an EC + command is not properly ACKed, override the length + of the timeout. We have interrupts disabled while + waiting for the ACK, so if this is set too high + interrupts *may* be lost! + + omap_mux= [OMAP] Override bootloader pin multiplexing. + Format: ... + For example, to override I2C bus2: + omap_mux=i2c2_scl.i2c2_scl=0x100,i2c2_sda.i2c2_sda=0x100 + + oprofile.timer= [HW] + Use timer interrupt instead of performance counters + + oprofile.cpu_type= Force an oprofile cpu type + This might be useful if you have an older oprofile + userland or if you want common events. + Format: { arch_perfmon } + arch_perfmon: [X86] Force use of architectural + perfmon on Intel CPUs instead of the + CPU specific event set. + timer: [X86] Force use of architectural NMI + timer mode (see also oprofile.timer + for generic hr timer mode) + + oops=panic Always panic on oopses. Default is to just kill the + process, but there is a small probability of + deadlocking the machine. + This will also cause panics on machine check exceptions. + Useful together with panic=30 to trigger a reboot. + + OSS [HW,OSS] + See Documentation/sound/oss/oss-parameters.txt + + page_owner= [KNL] Boot-time page_owner enabling option. + Storage of the information about who allocated + each page is disabled in default. With this switch, + we can turn it on. + on: enable the feature + + page_poison= [KNL] Boot-time parameter changing the state of + poisoning on the buddy allocator. + off: turn off poisoning + on: turn on poisoning + + panic= [KNL] Kernel behaviour on panic: delay + timeout > 0: seconds before rebooting + timeout = 0: wait forever + timeout < 0: reboot immediately + Format: + + panic_on_warn panic() instead of WARN(). Useful to cause kdump + on a WARN(). + + crash_kexec_post_notifiers + Run kdump after running panic-notifiers and dumping + kmsg. This only for the users who doubt kdump always + succeeds in any situation. + Note that this also increases risks of kdump failure, + because some panic notifiers can make the crashed + kernel more unstable. + + parkbd.port= [HW] Parallel port number the keyboard adapter is + connected to, default is 0. + Format: + parkbd.mode= [HW] Parallel port keyboard adapter mode of operation, + 0 for XT, 1 for AT (default is AT). + Format: + + parport= [HW,PPT] Specify parallel ports. 0 disables. + Format: { 0 | auto | 0xBBB[,IRQ[,DMA]] } + Use 'auto' to force the driver to use any + IRQ/DMA settings detected (the default is to + ignore detected IRQ/DMA settings because of + possible conflicts). You can specify the base + address, IRQ, and DMA settings; IRQ and DMA + should be numbers, or 'auto' (for using detected + settings on that particular port), or 'nofifo' + (to avoid using a FIFO even if it is detected). + Parallel ports are assigned in the order they + are specified on the command line, starting + with parport0. + + parport_init_mode= [HW,PPT] + Configure VIA parallel port to operate in + a specific mode. This is necessary on Pegasos + computer where firmware has no options for setting + up parallel port mode and sets it to spp. + Currently this function knows 686a and 8231 chips. + Format: [spp|ps2|epp|ecp|ecpepp] + + pause_on_oops= + Halt all CPUs after the first oops has been printed for + the specified number of seconds. This is to be used if + your oopses keep scrolling off the screen. + + pcbit= [HW,ISDN] + + pcd. [PARIDE] + See header of drivers/block/paride/pcd.c. + See also Documentation/blockdev/paride.txt. + + pci=option[,option...] [PCI] various PCI subsystem options: + earlydump [X86] dump PCI config space before the kernel + changes anything + off [X86] don't probe for the PCI bus + bios [X86-32] force use of PCI BIOS, don't access + the hardware directly. Use this if your machine + has a non-standard PCI host bridge. + nobios [X86-32] disallow use of PCI BIOS, only direct + hardware access methods are allowed. Use this + if you experience crashes upon bootup and you + suspect they are caused by the BIOS. + conf1 [X86] Force use of PCI Configuration Access + Mechanism 1 (config address in IO port 0xCF8, + data in IO port 0xCFC, both 32-bit). + conf2 [X86] Force use of PCI Configuration Access + Mechanism 2 (IO port 0xCF8 is an 8-bit port for + the function, IO port 0xCFA, also 8-bit, sets + bus number. The config space is then accessed + through ports 0xC000-0xCFFF). + See http://wiki.osdev.org/PCI for more info + on the configuration access mechanisms. + noaer [PCIE] If the PCIEAER kernel config parameter is + enabled, this kernel boot option can be used to + disable the use of PCIE advanced error reporting. + nodomains [PCI] Disable support for multiple PCI + root domains (aka PCI segments, in ACPI-speak). + nommconf [X86] Disable use of MMCONFIG for PCI + Configuration + check_enable_amd_mmconf [X86] check for and enable + properly configured MMIO access to PCI + config space on AMD family 10h CPU + nomsi [MSI] If the PCI_MSI kernel config parameter is + enabled, this kernel boot option can be used to + disable the use of MSI interrupts system-wide. + noioapicquirk [APIC] Disable all boot interrupt quirks. + Safety option to keep boot IRQs enabled. This + should never be necessary. + ioapicreroute [APIC] Enable rerouting of boot IRQs to the + primary IO-APIC for bridges that cannot disable + boot IRQs. This fixes a source of spurious IRQs + when the system masks IRQs. + noioapicreroute [APIC] Disable workaround that uses the + boot IRQ equivalent of an IRQ that connects to + a chipset where boot IRQs cannot be disabled. + The opposite of ioapicreroute. + biosirq [X86-32] Use PCI BIOS calls to get the interrupt + routing table. These calls are known to be buggy + on several machines and they hang the machine + when used, but on other computers it's the only + way to get the interrupt routing table. Try + this option if the kernel is unable to allocate + IRQs or discover secondary PCI buses on your + motherboard. + rom [X86] Assign address space to expansion ROMs. + Use with caution as certain devices share + address decoders between ROMs and other + resources. + norom [X86] Do not assign address space to + expansion ROMs that do not already have + BIOS assigned address ranges. + nobar [X86] Do not assign address space to the + BARs that weren't assigned by the BIOS. + irqmask=0xMMMM [X86] Set a bit mask of IRQs allowed to be + assigned automatically to PCI devices. You can + make the kernel exclude IRQs of your ISA cards + this way. + pirqaddr=0xAAAAA [X86] Specify the physical address + of the PIRQ table (normally generated + by the BIOS) if it is outside the + F0000h-100000h range. + lastbus=N [X86] Scan all buses thru bus #N. Can be + useful if the kernel is unable to find your + secondary buses and you want to tell it + explicitly which ones they are. + assign-busses [X86] Always assign all PCI bus + numbers ourselves, overriding + whatever the firmware may have done. + usepirqmask [X86] Honor the possible IRQ mask stored + in the BIOS $PIR table. This is needed on + some systems with broken BIOSes, notably + some HP Pavilion N5400 and Omnibook XE3 + notebooks. This will have no effect if ACPI + IRQ routing is enabled. + noacpi [X86] Do not use ACPI for IRQ routing + or for PCI scanning. + use_crs [X86] Use PCI host bridge window information + from ACPI. On BIOSes from 2008 or later, this + is enabled by default. If you need to use this, + please report a bug. + nocrs [X86] Ignore PCI host bridge windows from ACPI. + If you need to use this, please report a bug. + routeirq Do IRQ routing for all PCI devices. + This is normally done in pci_enable_device(), + so this option is a temporary workaround + for broken drivers that don't call it. + skip_isa_align [X86] do not align io start addr, so can + handle more pci cards + noearly [X86] Don't do any early type 1 scanning. + This might help on some broken boards which + machine check when some devices' config space + is read. But various workarounds are disabled + and some IOMMU drivers will not work. + bfsort Sort PCI devices into breadth-first order. + This sorting is done to get a device + order compatible with older (<= 2.4) kernels. + nobfsort Don't sort PCI devices into breadth-first order. + pcie_bus_tune_off Disable PCIe MPS (Max Payload Size) + tuning and use the BIOS-configured MPS defaults. + pcie_bus_safe Set every device's MPS to the largest value + supported by all devices below the root complex. + pcie_bus_perf Set device MPS to the largest allowable MPS + based on its parent bus. Also set MRRS (Max + Read Request Size) to the largest supported + value (no larger than the MPS that the device + or bus can support) for best performance. + pcie_bus_peer2peer Set every device's MPS to 128B, which + every device is guaranteed to support. This + configuration allows peer-to-peer DMA between + any pair of devices, possibly at the cost of + reduced performance. This also guarantees + that hot-added devices will work. + cbiosize=nn[KMG] The fixed amount of bus space which is + reserved for the CardBus bridge's IO window. + The default value is 256 bytes. + cbmemsize=nn[KMG] The fixed amount of bus space which is + reserved for the CardBus bridge's memory + window. The default value is 64 megabytes. + resource_alignment= + Format: + [@][:]:.[; ...] + [@]pci::\ + [::][; ...] + Specifies alignment and device to reassign + aligned memory resources. + If is not specified, + PAGE_SIZE is used as alignment. + PCI-PCI bridge can be specified, if resource + windows need to be expanded. + To specify the alignment for several + instances of a device, the PCI vendor, + device, subvendor, and subdevice may be + specified, e.g., 4096@pci:8086:9c22:103c:198f + ecrc= Enable/disable PCIe ECRC (transaction layer + end-to-end CRC checking). + bios: Use BIOS/firmware settings. This is the + the default. + off: Turn ECRC off + on: Turn ECRC on. + hpiosize=nn[KMG] The fixed amount of bus space which is + reserved for hotplug bridge's IO window. + Default size is 256 bytes. + hpmemsize=nn[KMG] The fixed amount of bus space which is + reserved for hotplug bridge's memory window. + Default size is 2 megabytes. + hpbussize=nn The minimum amount of additional bus numbers + reserved for buses below a hotplug bridge. + Default is 1. + realloc= Enable/disable reallocating PCI bridge resources + if allocations done by BIOS are too small to + accommodate resources required by all child + devices. + off: Turn realloc off + on: Turn realloc on + realloc same as realloc=on + noari do not use PCIe ARI. + pcie_scan_all Scan all possible PCIe devices. Otherwise we + only look for one device below a PCIe downstream + port. + + pcie_aspm= [PCIE] Forcibly enable or disable PCIe Active State Power + Management. + off Disable ASPM. + force Enable ASPM even on devices that claim not to support it. + WARNING: Forcing ASPM on may cause system lockups. + + pcie_hp= [PCIE] PCI Express Hotplug driver options: + nomsi Do not use MSI for PCI Express Native Hotplug (this + makes all PCIe ports use INTx for hotplug services). + + pcie_ports= [PCIE] PCIe ports handling: + auto Ask the BIOS whether or not to use native PCIe services + associated with PCIe ports (PME, hot-plug, AER). Use + them only if that is allowed by the BIOS. + native Use native PCIe services associated with PCIe ports + unconditionally. + compat Treat PCIe ports as PCI-to-PCI bridges, disable the PCIe + ports driver. + + pcie_port_pm= [PCIE] PCIe port power management handling: + off Disable power management of all PCIe ports + force Forcibly enable power management of all PCIe ports + + pcie_pme= [PCIE,PM] Native PCIe PME signaling options: + nomsi Do not use MSI for native PCIe PME signaling (this makes + all PCIe root ports use INTx for all services). + + pcmv= [HW,PCMCIA] BadgePAD 4 + + pd_ignore_unused + [PM] + Keep all power-domains already enabled by bootloader on, + even if no driver has claimed them. This is useful + for debug and development, but should not be + needed on a platform with proper driver support. + + pd. [PARIDE] + See Documentation/blockdev/paride.txt. + + pdcchassis= [PARISC,HW] Disable/Enable PDC Chassis Status codes at + boot time. + Format: { 0 | 1 } + See arch/parisc/kernel/pdc_chassis.c + + percpu_alloc= Select which percpu first chunk allocator to use. + Currently supported values are "embed" and "page". + Archs may support subset or none of the selections. + See comments in mm/percpu.c for details on each + allocator. This parameter is primarily for debugging + and performance comparison. + + pf. [PARIDE] + See Documentation/blockdev/paride.txt. + + pg. [PARIDE] + See Documentation/blockdev/paride.txt. + + pirq= [SMP,APIC] Manual mp-table setup + See Documentation/x86/i386/IO-APIC.txt. + + plip= [PPT,NET] Parallel port network link + Format: { parport | timid | 0 } + See also Documentation/parport.txt. + + pmtmr= [X86] Manual setup of pmtmr I/O Port. + Override pmtimer IOPort with a hex value. + e.g. pmtmr=0x508 + + pnp.debug=1 [PNP] + Enable PNP debug messages (depends on the + CONFIG_PNP_DEBUG_MESSAGES option). Change at run-time + via /sys/module/pnp/parameters/debug. We always show + current resource usage; turning this on also shows + possible settings and some assignment information. + + pnpacpi= [ACPI] + { off } + + pnpbios= [ISAPNP] + { on | off | curr | res | no-curr | no-res } + + pnp_reserve_irq= + [ISAPNP] Exclude IRQs for the autoconfiguration + + pnp_reserve_dma= + [ISAPNP] Exclude DMAs for the autoconfiguration + + pnp_reserve_io= [ISAPNP] Exclude I/O ports for the autoconfiguration + Ranges are in pairs (I/O port base and size). + + pnp_reserve_mem= + [ISAPNP] Exclude memory regions for the + autoconfiguration. + Ranges are in pairs (memory base and size). + + ports= [IP_VS_FTP] IPVS ftp helper module + Default is 21. + Up to 8 (IP_VS_APP_MAX_PORTS) ports + may be specified. + Format: ,.... + + ppc_strict_facility_enable + [PPC] This option catches any kernel floating point, + Altivec, VSX and SPE outside of regions specifically + allowed (eg kernel_enable_fpu()/kernel_disable_fpu()). + There is some performance impact when enabling this. + + print-fatal-signals= + [KNL] debug: print fatal signals + + If enabled, warn about various signal handling + related application anomalies: too many signals, + too many POSIX.1 timers, fatal signals causing a + coredump - etc. + + If you hit the warning due to signal overflow, + you might want to try "ulimit -i unlimited". + + default: off. + + printk.always_kmsg_dump= + Trigger kmsg_dump for cases other than kernel oops or + panics + Format: (1/Y/y=enable, 0/N/n=disable) + default: disabled + + printk.devkmsg={on,off,ratelimit} + Control writing to /dev/kmsg. + on - unlimited logging to /dev/kmsg from userspace + off - logging to /dev/kmsg disabled + ratelimit - ratelimit the logging + Default: ratelimit + + printk.time= Show timing data prefixed to each printk message line + Format: (1/Y/y=enable, 0/N/n=disable) + + processor.max_cstate= [HW,ACPI] + Limit processor to maximum C-state + max_cstate=9 overrides any DMI blacklist limit. + + processor.nocst [HW,ACPI] + Ignore the _CST method to determine C-states, + instead using the legacy FADT method + + profile= [KNL] Enable kernel profiling via /proc/profile + Format: [schedule,] + Param: "schedule" - profile schedule points. + Param: - step/bucket size as a power of 2 for + statistical time based profiling. + Param: "sleep" - profile D-state sleeping (millisecs). + Requires CONFIG_SCHEDSTATS + Param: "kvm" - profile VM exits. + + prompt_ramdisk= [RAM] List of RAM disks to prompt for floppy disk + before loading. + See Documentation/blockdev/ramdisk.txt. + + psmouse.proto= [HW,MOUSE] Highest PS2 mouse protocol extension to + probe for; one of (bare|imps|exps|lifebook|any). + psmouse.rate= [HW,MOUSE] Set desired mouse report rate, in reports + per second. + psmouse.resetafter= [HW,MOUSE] + Try to reset the device after so many bad packets + (0 = never). + psmouse.resolution= + [HW,MOUSE] Set desired mouse resolution, in dpi. + psmouse.smartscroll= + [HW,MOUSE] Controls Logitech smartscroll autorepeat. + 0 = disabled, 1 = enabled (default). + + pstore.backend= Specify the name of the pstore backend to use + + pt. [PARIDE] + See Documentation/blockdev/paride.txt. + + pty.legacy_count= + [KNL] Number of legacy pty's. Overwrites compiled-in + default number. + + quiet [KNL] Disable most log messages + + r128= [HW,DRM] + + raid= [HW,RAID] + See Documentation/md.txt. + + ramdisk_size= [RAM] Sizes of RAM disks in kilobytes + See Documentation/blockdev/ramdisk.txt. + + rcu_nocbs= [KNL] + The argument is a cpu list, as described above. + + In kernels built with CONFIG_RCU_NOCB_CPU=y, set + the specified list of CPUs to be no-callback CPUs. + Invocation of these CPUs' RCU callbacks will + be offloaded to "rcuox/N" kthreads created for + that purpose, where "x" is "b" for RCU-bh, "p" + for RCU-preempt, and "s" for RCU-sched, and "N" + is the CPU number. This reduces OS jitter on the + offloaded CPUs, which can be useful for HPC and + real-time workloads. It can also improve energy + efficiency for asymmetric multiprocessors. + + rcu_nocb_poll [KNL] + Rather than requiring that offloaded CPUs + (specified by rcu_nocbs= above) explicitly + awaken the corresponding "rcuoN" kthreads, + make these kthreads poll for callbacks. + This improves the real-time response for the + offloaded CPUs by relieving them of the need to + wake up the corresponding kthread, but degrades + energy efficiency by requiring that the kthreads + periodically wake up to do the polling. + + rcutree.blimit= [KNL] + Set maximum number of finished RCU callbacks to + process in one batch. + + rcutree.dump_tree= [KNL] + Dump the structure of the rcu_node combining tree + out at early boot. This is used for diagnostic + purposes, to verify correct tree setup. + + rcutree.gp_cleanup_delay= [KNL] + Set the number of jiffies to delay each step of + RCU grace-period cleanup. This only has effect + when CONFIG_RCU_TORTURE_TEST_SLOW_CLEANUP is set. + + rcutree.gp_init_delay= [KNL] + Set the number of jiffies to delay each step of + RCU grace-period initialization. This only has + effect when CONFIG_RCU_TORTURE_TEST_SLOW_INIT + is set. + + rcutree.gp_preinit_delay= [KNL] + Set the number of jiffies to delay each step of + RCU grace-period pre-initialization, that is, + the propagation of recent CPU-hotplug changes up + the rcu_node combining tree. This only has effect + when CONFIG_RCU_TORTURE_TEST_SLOW_PREINIT is set. + + rcutree.rcu_fanout_exact= [KNL] + Disable autobalancing of the rcu_node combining + tree. This is used by rcutorture, and might + possibly be useful for architectures having high + cache-to-cache transfer latencies. + + rcutree.rcu_fanout_leaf= [KNL] + Change the number of CPUs assigned to each + leaf rcu_node structure. Useful for very + large systems, which will choose the value 64, + and for NUMA systems with large remote-access + latencies, which will choose a value aligned + with the appropriate hardware boundaries. + + rcutree.jiffies_till_sched_qs= [KNL] + Set required age in jiffies for a + given grace period before RCU starts + soliciting quiescent-state help from + rcu_note_context_switch(). + + rcutree.jiffies_till_first_fqs= [KNL] + Set delay from grace-period initialization to + first attempt to force quiescent states. + Units are jiffies, minimum value is zero, + and maximum value is HZ. + + rcutree.jiffies_till_next_fqs= [KNL] + Set delay between subsequent attempts to force + quiescent states. Units are jiffies, minimum + value is one, and maximum value is HZ. + + rcutree.kthread_prio= [KNL,BOOT] + Set the SCHED_FIFO priority of the RCU per-CPU + kthreads (rcuc/N). This value is also used for + the priority of the RCU boost threads (rcub/N) + and for the RCU grace-period kthreads (rcu_bh, + rcu_preempt, and rcu_sched). If RCU_BOOST is + set, valid values are 1-99 and the default is 1 + (the least-favored priority). Otherwise, when + RCU_BOOST is not set, valid values are 0-99 and + the default is zero (non-realtime operation). + + rcutree.rcu_nocb_leader_stride= [KNL] + Set the number of NOCB kthread groups, which + defaults to the square root of the number of + CPUs. Larger numbers reduces the wakeup overhead + on the per-CPU grace-period kthreads, but increases + that same overhead on each group's leader. + + rcutree.qhimark= [KNL] + Set threshold of queued RCU callbacks beyond which + batch limiting is disabled. + + rcutree.qlowmark= [KNL] + Set threshold of queued RCU callbacks below which + batch limiting is re-enabled. + + rcutree.rcu_idle_gp_delay= [KNL] + Set wakeup interval for idle CPUs that have + RCU callbacks (RCU_FAST_NO_HZ=y). + + rcutree.rcu_idle_lazy_gp_delay= [KNL] + Set wakeup interval for idle CPUs that have + only "lazy" RCU callbacks (RCU_FAST_NO_HZ=y). + Lazy RCU callbacks are those which RCU can + prove do nothing more than free memory. + + rcuperf.gp_exp= [KNL] + Measure performance of expedited synchronous + grace-period primitives. + + rcuperf.holdoff= [KNL] + Set test-start holdoff period. The purpose of + this parameter is to delay the start of the + test until boot completes in order to avoid + interference. + + rcuperf.nreaders= [KNL] + Set number of RCU readers. The value -1 selects + N, where N is the number of CPUs. A value + "n" less than -1 selects N-n+1, where N is again + the number of CPUs. For example, -2 selects N + (the number of CPUs), -3 selects N+1, and so on. + A value of "n" less than or equal to -N selects + a single reader. + + rcuperf.nwriters= [KNL] + Set number of RCU writers. The values operate + the same as for rcuperf.nreaders. + N, where N is the number of CPUs + + rcuperf.perf_runnable= [BOOT] + Start rcuperf running at boot time. + + rcuperf.shutdown= [KNL] + Shut the system down after performance tests + complete. This is useful for hands-off automated + testing. + + rcuperf.perf_type= [KNL] + Specify the RCU implementation to test. + + rcuperf.verbose= [KNL] + Enable additional printk() statements. + + rcutorture.cbflood_inter_holdoff= [KNL] + Set holdoff time (jiffies) between successive + callback-flood tests. + + rcutorture.cbflood_intra_holdoff= [KNL] + Set holdoff time (jiffies) between successive + bursts of callbacks within a given callback-flood + test. + + rcutorture.cbflood_n_burst= [KNL] + Set the number of bursts making up a given + callback-flood test. Set this to zero to + disable callback-flood testing. + + rcutorture.cbflood_n_per_burst= [KNL] + Set the number of callbacks to be registered + in a given burst of a callback-flood test. + + rcutorture.fqs_duration= [KNL] + Set duration of force_quiescent_state bursts + in microseconds. + + rcutorture.fqs_holdoff= [KNL] + Set holdoff time within force_quiescent_state bursts + in microseconds. + + rcutorture.fqs_stutter= [KNL] + Set wait time between force_quiescent_state bursts + in seconds. + + rcutorture.gp_cond= [KNL] + Use conditional/asynchronous update-side + primitives, if available. + + rcutorture.gp_exp= [KNL] + Use expedited update-side primitives, if available. + + rcutorture.gp_normal= [KNL] + Use normal (non-expedited) asynchronous + update-side primitives, if available. + + rcutorture.gp_sync= [KNL] + Use normal (non-expedited) synchronous + update-side primitives, if available. If all + of rcutorture.gp_cond=, rcutorture.gp_exp=, + rcutorture.gp_normal=, and rcutorture.gp_sync= + are zero, rcutorture acts as if is interpreted + they are all non-zero. + + rcutorture.n_barrier_cbs= [KNL] + Set callbacks/threads for rcu_barrier() testing. + + rcutorture.nfakewriters= [KNL] + Set number of concurrent RCU writers. These just + stress RCU, they don't participate in the actual + test, hence the "fake". + + rcutorture.nreaders= [KNL] + Set number of RCU readers. The value -1 selects + N-1, where N is the number of CPUs. A value + "n" less than -1 selects N-n-2, where N is again + the number of CPUs. For example, -2 selects N + (the number of CPUs), -3 selects N+1, and so on. + + rcutorture.object_debug= [KNL] + Enable debug-object double-call_rcu() testing. + + rcutorture.onoff_holdoff= [KNL] + Set time (s) after boot for CPU-hotplug testing. + + rcutorture.onoff_interval= [KNL] + Set time (s) between CPU-hotplug operations, or + zero to disable CPU-hotplug testing. + + rcutorture.shuffle_interval= [KNL] + Set task-shuffle interval (s). Shuffling tasks + allows some CPUs to go into dyntick-idle mode + during the rcutorture test. + + rcutorture.shutdown_secs= [KNL] + Set time (s) after boot system shutdown. This + is useful for hands-off automated testing. + + rcutorture.stall_cpu= [KNL] + Duration of CPU stall (s) to test RCU CPU stall + warnings, zero to disable. + + rcutorture.stall_cpu_holdoff= [KNL] + Time to wait (s) after boot before inducing stall. + + rcutorture.stat_interval= [KNL] + Time (s) between statistics printk()s. + + rcutorture.stutter= [KNL] + Time (s) to stutter testing, for example, specifying + five seconds causes the test to run for five seconds, + wait for five seconds, and so on. This tests RCU's + ability to transition abruptly to and from idle. + + rcutorture.test_boost= [KNL] + Test RCU priority boosting? 0=no, 1=maybe, 2=yes. + "Maybe" means test if the RCU implementation + under test support RCU priority boosting. + + rcutorture.test_boost_duration= [KNL] + Duration (s) of each individual boost test. + + rcutorture.test_boost_interval= [KNL] + Interval (s) between each boost test. + + rcutorture.test_no_idle_hz= [KNL] + Test RCU's dyntick-idle handling. See also the + rcutorture.shuffle_interval parameter. + + rcutorture.torture_runnable= [BOOT] + Start rcutorture running at boot time. + + rcutorture.torture_type= [KNL] + Specify the RCU implementation to test. + + rcutorture.verbose= [KNL] + Enable additional printk() statements. + + rcupdate.rcu_cpu_stall_suppress= [KNL] + Suppress RCU CPU stall warning messages. + + rcupdate.rcu_cpu_stall_timeout= [KNL] + Set timeout for RCU CPU stall warning messages. + + rcupdate.rcu_expedited= [KNL] + Use expedited grace-period primitives, for + example, synchronize_rcu_expedited() instead + of synchronize_rcu(). This reduces latency, + but can increase CPU utilization, degrade + real-time latency, and degrade energy efficiency. + No effect on CONFIG_TINY_RCU kernels. + + rcupdate.rcu_normal= [KNL] + Use only normal grace-period primitives, + for example, synchronize_rcu() instead of + synchronize_rcu_expedited(). This improves + real-time latency, CPU utilization, and + energy efficiency, but can expose users to + increased grace-period latency. This parameter + overrides rcupdate.rcu_expedited. No effect on + CONFIG_TINY_RCU kernels. + + rcupdate.rcu_normal_after_boot= [KNL] + Once boot has completed (that is, after + rcu_end_inkernel_boot() has been invoked), use + only normal grace-period primitives. No effect + on CONFIG_TINY_RCU kernels. + + rcupdate.rcu_task_stall_timeout= [KNL] + Set timeout in jiffies for RCU task stall warning + messages. Disable with a value less than or equal + to zero. + + rcupdate.rcu_self_test= [KNL] + Run the RCU early boot self tests + + rcupdate.rcu_self_test_bh= [KNL] + Run the RCU bh early boot self tests + + rcupdate.rcu_self_test_sched= [KNL] + Run the RCU sched early boot self tests + + rdinit= [KNL] + Format: + Run specified binary instead of /init from the ramdisk, + used for early userspace startup. See initrd. + + reboot= [KNL] + Format (x86 or x86_64): + [w[arm] | c[old] | h[ard] | s[oft] | g[pio]] \ + [[,]s[mp]#### \ + [[,]b[ios] | a[cpi] | k[bd] | t[riple] | e[fi] | p[ci]] \ + [[,]f[orce] + Where reboot_mode is one of warm (soft) or cold (hard) or gpio, + reboot_type is one of bios, acpi, kbd, triple, efi, or pci, + reboot_force is either force or not specified, + reboot_cpu is s[mp]#### with #### being the processor + to be used for rebooting. + + relax_domain_level= + [KNL, SMP] Set scheduler's default relax_domain_level. + See Documentation/cgroup-v1/cpusets.txt. + + relative_sleep_states= + [SUSPEND] Use sleep state labeling where the deepest + state available other than hibernation is always "mem". + Format: { "0" | "1" } + 0 -- Traditional sleep state labels. + 1 -- Relative sleep state labels. + + reserve= [KNL,BUGS] Force the kernel to ignore some iomem area + + reservetop= [X86-32] + Format: nn[KMG] + Reserves a hole at the top of the kernel virtual + address space. + + reservelow= [X86] + Format: nn[K] + Set the amount of memory to reserve for BIOS at + the bottom of the address space. + + reset_devices [KNL] Force drivers to reset the underlying device + during initialization. + + resume= [SWSUSP] + Specify the partition device for software suspend + Format: + {/dev/ | PARTUUID= | : | } + + resume_offset= [SWSUSP] + Specify the offset from the beginning of the partition + given by "resume=" at which the swap header is located, + in units (needed only for swap files). + See Documentation/power/swsusp-and-swap-files.txt + + resumedelay= [HIBERNATION] Delay (in seconds) to pause before attempting to + read the resume files + + resumewait [HIBERNATION] Wait (indefinitely) for resume device to show up. + Useful for devices that are detected asynchronously + (e.g. USB and MMC devices). + + hibernate= [HIBERNATION] + noresume Don't check if there's a hibernation image + present during boot. + nocompress Don't compress/decompress hibernation images. + no Disable hibernation and resume. + protect_image Turn on image protection during restoration + (that will set all pages holding image data + during restoration read-only). + + retain_initrd [RAM] Keep initrd memory after extraction + + rfkill.default_state= + 0 "airplane mode". All wifi, bluetooth, wimax, gps, fm, + etc. communication is blocked by default. + 1 Unblocked. + + rfkill.master_switch_mode= + 0 The "airplane mode" button does nothing. + 1 The "airplane mode" button toggles between everything + blocked and the previous configuration. + 2 The "airplane mode" button toggles between everything + blocked and everything unblocked. + + rhash_entries= [KNL,NET] + Set number of hash buckets for route cache + + ro [KNL] Mount root device read-only on boot + + rodata= [KNL] + on Mark read-only kernel memory as read-only (default). + off Leave read-only kernel memory writable for debugging. + + rockchip.usb_uart + Enable the uart passthrough on the designated usb port + on Rockchip SoCs. When active, the signals of the + debug-uart get routed to the D+ and D- pins of the usb + port and the regular usb controller gets disabled. + + root= [KNL] Root filesystem + See name_to_dev_t comment in init/do_mounts.c. + + rootdelay= [KNL] Delay (in seconds) to pause before attempting to + mount the root filesystem + + rootflags= [KNL] Set root filesystem mount option string + + rootfstype= [KNL] Set root filesystem type + + rootwait [KNL] Wait (indefinitely) for root device to show up. + Useful for devices that are detected asynchronously + (e.g. USB and MMC devices). + + rproc_mem=nn[KMG][@address] + [KNL,ARM,CMA] Remoteproc physical memory block. + Memory area to be used by remote processor image, + managed by CMA. + + rw [KNL] Mount root device read-write on boot + + S [KNL] Run init in single mode + + s390_iommu= [HW,S390] + Set s390 IOTLB flushing mode + strict + With strict flushing every unmap operation will result in + an IOTLB flush. Default is lazy flushing before reuse, + which is faster. + + sa1100ir [NET] + See drivers/net/irda/sa1100_ir.c. + + sbni= [NET] Granch SBNI12 leased line adapter + + sched_debug [KNL] Enables verbose scheduler debug messages. + + schedstats= [KNL,X86] Enable or disable scheduled statistics. + Allowed values are enable and disable. This feature + incurs a small amount of overhead in the scheduler + but is useful for debugging and performance tuning. + + skew_tick= [KNL] Offset the periodic timer tick per cpu to mitigate + xtime_lock contention on larger systems, and/or RCU lock + contention on all systems with CONFIG_MAXSMP set. + Format: { "0" | "1" } + 0 -- disable. (may be 1 via CONFIG_CMDLINE="skew_tick=1" + 1 -- enable. + Note: increases power consumption, thus should only be + enabled if running jitter sensitive (HPC/RT) workloads. + + security= [SECURITY] Choose a security module to enable at boot. + If this boot parameter is not specified, only the first + security module asking for security registration will be + loaded. An invalid security module name will be treated + as if no module has been chosen. + + selinux= [SELINUX] Disable or enable SELinux at boot time. + Format: { "0" | "1" } + See security/selinux/Kconfig help text. + 0 -- disable. + 1 -- enable. + Default value is set via kernel config option. + If enabled at boot time, /selinux/disable can be used + later to disable prior to initial policy load. + + apparmor= [APPARMOR] Disable or enable AppArmor at boot time + Format: { "0" | "1" } + See security/apparmor/Kconfig help text + 0 -- disable. + 1 -- enable. + Default value is set via kernel config option. + + serialnumber [BUGS=X86-32] + + shapers= [NET] + Maximal number of shapers. + + show_msr= [x86] show boot-time MSR settings + Format: { } + Show boot-time (BIOS-initialized) MSR settings. + The parameter means the number of CPUs to show, + for example 1 means boot CPU only. + + simeth= [IA-64] + simscsi= + + slram= [HW,MTD] + + slab_nomerge [MM] + Disable merging of slabs with similar size. May be + necessary if there is some reason to distinguish + allocs to different slabs. Debug options disable + merging on their own. + For more information see Documentation/vm/slub.txt. + + slab_max_order= [MM, SLAB] + Determines the maximum allowed order for slabs. + A high setting may cause OOMs due to memory + fragmentation. Defaults to 1 for systems with + more than 32MB of RAM, 0 otherwise. + + slub_debug[=options[,slabs]] [MM, SLUB] + Enabling slub_debug allows one to determine the + culprit if slab objects become corrupted. Enabling + slub_debug can create guard zones around objects and + may poison objects when not in use. Also tracks the + last alloc / free. For more information see + Documentation/vm/slub.txt. + + slub_max_order= [MM, SLUB] + Determines the maximum allowed order for slabs. + A high setting may cause OOMs due to memory + fragmentation. For more information see + Documentation/vm/slub.txt. + + slub_min_objects= [MM, SLUB] + The minimum number of objects per slab. SLUB will + increase the slab order up to slub_max_order to + generate a sufficiently large slab able to contain + the number of objects indicated. The higher the number + of objects the smaller the overhead of tracking slabs + and the less frequently locks need to be acquired. + For more information see Documentation/vm/slub.txt. + + slub_min_order= [MM, SLUB] + Determines the minimum page order for slabs. Must be + lower than slub_max_order. + For more information see Documentation/vm/slub.txt. + + slub_nomerge [MM, SLUB] + Same with slab_nomerge. This is supported for legacy. + See slab_nomerge for more information. + + smart2= [HW] + Format: [,[,...,]] + + smsc-ircc2.nopnp [HW] Don't use PNP to discover SMC devices + smsc-ircc2.ircc_cfg= [HW] Device configuration I/O port + smsc-ircc2.ircc_sir= [HW] SIR base I/O port + smsc-ircc2.ircc_fir= [HW] FIR base I/O port + smsc-ircc2.ircc_irq= [HW] IRQ line + smsc-ircc2.ircc_dma= [HW] DMA channel + smsc-ircc2.ircc_transceiver= [HW] Transceiver type: + 0: Toshiba Satellite 1800 (GP data pin select) + 1: Fast pin select (default) + 2: ATC IRMode + + smt [KNL,S390] Set the maximum number of threads (logical + CPUs) to use per physical CPU on systems capable of + symmetric multithreading (SMT). Will be capped to the + actual hardware limit. + Format: + Default: -1 (no limit) + + softlockup_panic= + [KNL] Should the soft-lockup detector generate panics. + Format: + + softlockup_all_cpu_backtrace= + [KNL] Should the soft-lockup detector generate + backtraces on all cpus. + Format: + + sonypi.*= [HW] Sony Programmable I/O Control Device driver + See Documentation/laptops/sonypi.txt + + spia_io_base= [HW,MTD] + spia_fio_base= + spia_pedr= + spia_peddr= + + stacktrace [FTRACE] + Enabled the stack tracer on boot up. + + stacktrace_filter=[function-list] + [FTRACE] Limit the functions that the stack tracer + will trace at boot up. function-list is a comma separated + list of functions. This list can be changed at run + time by the stack_trace_filter file in the debugfs + tracing directory. Note, this enables stack tracing + and the stacktrace above is not needed. + + sti= [PARISC,HW] + Format: + Set the STI (builtin display/keyboard on the HP-PARISC + machines) console (graphic card) which should be used + as the initial boot-console. + See also comment in drivers/video/console/sticore.c. + + sti_font= [HW] + See comment in drivers/video/console/sticore.c. + + stifb= [HW] + Format: bpp:[:[:...]] + + sunrpc.min_resvport= + sunrpc.max_resvport= + [NFS,SUNRPC] + SunRPC servers often require that client requests + originate from a privileged port (i.e. a port in the + range 0 < portnr < 1024). + An administrator who wishes to reserve some of these + ports for other uses may adjust the range that the + kernel's sunrpc client considers to be privileged + using these two parameters to set the minimum and + maximum port values. + + sunrpc.svc_rpc_per_connection_limit= + [NFS,SUNRPC] + Limit the number of requests that the server will + process in parallel from a single connection. + The default value is 0 (no limit). + + sunrpc.pool_mode= + [NFS] + Control how the NFS server code allocates CPUs to + service thread pools. Depending on how many NICs + you have and where their interrupts are bound, this + option will affect which CPUs will do NFS serving. + Note: this parameter cannot be changed while the + NFS server is running. + + auto the server chooses an appropriate mode + automatically using heuristics + global a single global pool contains all CPUs + percpu one pool for each CPU + pernode one pool for each NUMA node (equivalent + to global on non-NUMA machines) + + sunrpc.tcp_slot_table_entries= + sunrpc.udp_slot_table_entries= + [NFS,SUNRPC] + Sets the upper limit on the number of simultaneous + RPC calls that can be sent from the client to a + server. Increasing these values may allow you to + improve throughput, but will also increase the + amount of memory reserved for use by the client. + + suspend.pm_test_delay= + [SUSPEND] + Sets the number of seconds to remain in a suspend test + mode before resuming the system (see + /sys/power/pm_test). Only available when CONFIG_PM_DEBUG + is set. Default value is 5. + + swapaccount=[0|1] + [KNL] Enable accounting of swap in memory resource + controller if no parameter or 1 is given or disable + it if 0 is given (See Documentation/cgroup-v1/memory.txt) + + swiotlb= [ARM,IA-64,PPC,MIPS,X86] + Format: { | force } + -- Number of I/O TLB slabs + force -- force using of bounce buffers even if they + wouldn't be automatically used by the kernel + + switches= [HW,M68k] + + sysfs.deprecated=0|1 [KNL] + Enable/disable old style sysfs layout for old udev + on older distributions. When this option is enabled + very new udev will not work anymore. When this option + is disabled (or CONFIG_SYSFS_DEPRECATED not compiled) + in older udev will not work anymore. + Default depends on CONFIG_SYSFS_DEPRECATED_V2 set in + the kernel configuration. + + sysrq_always_enabled + [KNL] + Ignore sysrq setting - this boot parameter will + neutralize any effect of /proc/sys/kernel/sysrq. + Useful for debugging. + + tcpmhash_entries= [KNL,NET] + Set the number of tcp_metrics_hash slots. + Default value is 8192 or 16384 depending on total + ram pages. This is used to specify the TCP metrics + cache size. See Documentation/networking/ip-sysctl.txt + "tcp_no_metrics_save" section for more details. + + tdfx= [HW,DRM] + + test_suspend= [SUSPEND][,N] + Specify "mem" (for Suspend-to-RAM) or "standby" (for + standby suspend) or "freeze" (for suspend type freeze) + as the system sleep state during system startup with + the optional capability to repeat N number of times. + The system is woken from this state using a + wakeup-capable RTC alarm. + + thash_entries= [KNL,NET] + Set number of hash buckets for TCP connection + + thermal.act= [HW,ACPI] + -1: disable all active trip points in all thermal zones + : override all lowest active trip points + + thermal.crt= [HW,ACPI] + -1: disable all critical trip points in all thermal zones + : override all critical trip points + + thermal.nocrt= [HW,ACPI] + Set to disable actions on ACPI thermal zone + critical and hot trip points. + + thermal.off= [HW,ACPI] + 1: disable ACPI thermal control + + thermal.psv= [HW,ACPI] + -1: disable all passive trip points + : override all passive trip points to this + value + + thermal.tzp= [HW,ACPI] + Specify global default ACPI thermal zone polling rate + : poll all this frequency + 0: no polling (default) + + threadirqs [KNL] + Force threading of all interrupt handlers except those + marked explicitly IRQF_NO_THREAD. + + tmem [KNL,XEN] + Enable the Transcendent memory driver if built-in. + + tmem.cleancache=0|1 [KNL, XEN] + Default is on (1). Disable the usage of the cleancache + API to send anonymous pages to the hypervisor. + + tmem.frontswap=0|1 [KNL, XEN] + Default is on (1). Disable the usage of the frontswap + API to send swap pages to the hypervisor. If disabled + the selfballooning and selfshrinking are force disabled. + + tmem.selfballooning=0|1 [KNL, XEN] + Default is on (1). Disable the driving of swap pages + to the hypervisor. + + tmem.selfshrinking=0|1 [KNL, XEN] + Default is on (1). Partial swapoff that immediately + transfers pages from Xen hypervisor back to the + kernel based on different criteria. + + topology= [S390] + Format: {off | on} + Specify if the kernel should make use of the cpu + topology information if the hardware supports this. + The scheduler will make use of this information and + e.g. base its process migration decisions on it. + Default is on. + + topology_updates= [KNL, PPC, NUMA] + Format: {off} + Specify if the kernel should ignore (off) + topology updates sent by the hypervisor to this + LPAR. + + tp720= [HW,PS2] + + tpm_suspend_pcr=[HW,TPM] + Format: integer pcr id + Specify that at suspend time, the tpm driver + should extend the specified pcr with zeros, + as a workaround for some chips which fail to + flush the last written pcr on TPM_SaveState. + This will guarantee that all the other pcrs + are saved. + + trace_buf_size=nn[KMG] + [FTRACE] will set tracing buffer size on each cpu. + + trace_event=[event-list] + [FTRACE] Set and start specified trace events in order + to facilitate early boot debugging. The event-list is a + comma separated list of trace events to enable. See + also Documentation/trace/events.txt + + trace_options=[option-list] + [FTRACE] Enable or disable tracer options at boot. + The option-list is a comma delimited list of options + that can be enabled or disabled just as if you were + to echo the option name into + + /sys/kernel/debug/tracing/trace_options + + For example, to enable stacktrace option (to dump the + stack trace of each event), add to the command line: + + trace_options=stacktrace + + See also Documentation/trace/ftrace.txt "trace options" + section. + + tp_printk[FTRACE] + Have the tracepoints sent to printk as well as the + tracing ring buffer. This is useful for early boot up + where the system hangs or reboots and does not give the + option for reading the tracing buffer or performing a + ftrace_dump_on_oops. + + To turn off having tracepoints sent to printk, + echo 0 > /proc/sys/kernel/tracepoint_printk + Note, echoing 1 into this file without the + tracepoint_printk kernel cmdline option has no effect. + + ** CAUTION ** + + Having tracepoints sent to printk() and activating high + frequency tracepoints such as irq or sched, can cause + the system to live lock. + + traceoff_on_warning + [FTRACE] enable this option to disable tracing when a + warning is hit. This turns off "tracing_on". Tracing can + be enabled again by echoing '1' into the "tracing_on" + file located in /sys/kernel/debug/tracing/ + + This option is useful, as it disables the trace before + the WARNING dump is called, which prevents the trace to + be filled with content caused by the warning output. + + This option can also be set at run time via the sysctl + option: kernel/traceoff_on_warning + + transparent_hugepage= + [KNL] + Format: [always|madvise|never] + Can be used to control the default behavior of the system + with respect to transparent hugepages. + See Documentation/vm/transhuge.txt for more details. + + tsc= Disable clocksource stability checks for TSC. + Format: + [x86] reliable: mark tsc clocksource as reliable, this + disables clocksource verification at runtime, as well + as the stability checks done at bootup. Used to enable + high-resolution timer mode on older hardware, and in + virtualized environment. + [x86] noirqtime: Do not use TSC to do irq accounting. + Used to run time disable IRQ_TIME_ACCOUNTING on any + platforms where RDTSC is slow and this accounting + can add overhead. + + turbografx.map[2|3]= [HW,JOY] + TurboGraFX parallel port interface + Format: + ,,,,,,, + See also Documentation/input/joystick-parport.txt + + udbg-immortal [PPC] When debugging early kernel crashes that + happen after console_init() and before a proper + console driver takes over, this boot options might + help "seeing" what's going on. + + uhash_entries= [KNL,NET] + Set number of hash buckets for UDP/UDP-Lite connections + + uhci-hcd.ignore_oc= + [USB] Ignore overcurrent events (default N). + Some badly-designed motherboards generate lots of + bogus events, for ports that aren't wired to + anything. Set this parameter to avoid log spamming. + Note that genuine overcurrent events won't be + reported either. + + unknown_nmi_panic + [X86] Cause panic on unknown NMI. + + usbcore.authorized_default= + [USB] Default USB device authorization: + (default -1 = authorized except for wireless USB, + 0 = not authorized, 1 = authorized) + + usbcore.autosuspend= + [USB] The autosuspend time delay (in seconds) used + for newly-detected USB devices (default 2). This + is the time required before an idle device will be + autosuspended. Devices for which the delay is set + to a negative value won't be autosuspended at all. + + usbcore.usbfs_snoop= + [USB] Set to log all usbfs traffic (default 0 = off). + + usbcore.usbfs_snoop_max= + [USB] Maximum number of bytes to snoop in each URB + (default = 65536). + + usbcore.blinkenlights= + [USB] Set to cycle leds on hubs (default 0 = off). + + usbcore.old_scheme_first= + [USB] Start with the old device initialization + scheme (default 0 = off). + + usbcore.usbfs_memory_mb= + [USB] Memory limit (in MB) for buffers allocated by + usbfs (default = 16, 0 = max = 2047). + + usbcore.use_both_schemes= + [USB] Try the other device initialization scheme + if the first one fails (default 1 = enabled). + + usbcore.initial_descriptor_timeout= + [USB] Specifies timeout for the initial 64-byte + USB_REQ_GET_DESCRIPTOR request in milliseconds + (default 5000 = 5.0 seconds). + + usbcore.nousb [USB] Disable the USB subsystem + + usbhid.mousepoll= + [USBHID] The interval which mice are to be polled at. + + usb-storage.delay_use= + [UMS] The delay in seconds before a new device is + scanned for Logical Units (default 1). + + usb-storage.quirks= + [UMS] A list of quirks entries to supplement or + override the built-in unusual_devs list. List + entries are separated by commas. Each entry has + the form VID:PID:Flags where VID and PID are Vendor + and Product ID values (4-digit hex numbers) and + Flags is a set of characters, each corresponding + to a common usb-storage quirk flag as follows: + a = SANE_SENSE (collect more than 18 bytes + of sense data); + b = BAD_SENSE (don't collect more than 18 + bytes of sense data); + c = FIX_CAPACITY (decrease the reported + device capacity by one sector); + d = NO_READ_DISC_INFO (don't use + READ_DISC_INFO command); + e = NO_READ_CAPACITY_16 (don't use + READ_CAPACITY_16 command); + f = NO_REPORT_OPCODES (don't use report opcodes + command, uas only); + g = MAX_SECTORS_240 (don't transfer more than + 240 sectors at a time, uas only); + h = CAPACITY_HEURISTICS (decrease the + reported device capacity by one + sector if the number is odd); + i = IGNORE_DEVICE (don't bind to this + device); + j = NO_REPORT_LUNS (don't use report luns + command, uas only); + l = NOT_LOCKABLE (don't try to lock and + unlock ejectable media); + m = MAX_SECTORS_64 (don't transfer more + than 64 sectors = 32 KB at a time); + n = INITIAL_READ10 (force a retry of the + initial READ(10) command); + o = CAPACITY_OK (accept the capacity + reported by the device); + p = WRITE_CACHE (the device cache is ON + by default); + r = IGNORE_RESIDUE (the device reports + bogus residue values); + s = SINGLE_LUN (the device has only one + Logical Unit); + t = NO_ATA_1X (don't allow ATA(12) and ATA(16) + commands, uas only); + u = IGNORE_UAS (don't bind to the uas driver); + w = NO_WP_DETECT (don't test whether the + medium is write-protected). + y = ALWAYS_SYNC (issue a SYNCHRONIZE_CACHE + even if the device claims no cache) + Example: quirks=0419:aaf5:rl,0421:0433:rc + + user_debug= [KNL,ARM] + Format: + See arch/arm/Kconfig.debug help text. + 1 - undefined instruction events + 2 - system calls + 4 - invalid data aborts + 8 - SIGSEGV faults + 16 - SIGBUS faults + Example: user_debug=31 + + userpte= + [X86] Flags controlling user PTE allocations. + + nohigh = do not allocate PTE pages in + HIGHMEM regardless of setting + of CONFIG_HIGHPTE. + + vdso= [X86,SH] + On X86_32, this is an alias for vdso32=. Otherwise: + + vdso=1: enable VDSO (the default) + vdso=0: disable VDSO mapping + + vdso32= [X86] Control the 32-bit vDSO + vdso32=1: enable 32-bit VDSO + vdso32=0 or vdso32=2: disable 32-bit VDSO + + See the help text for CONFIG_COMPAT_VDSO for more + details. If CONFIG_COMPAT_VDSO is set, the default is + vdso32=0; otherwise, the default is vdso32=1. + + For compatibility with older kernels, vdso32=2 is an + alias for vdso32=0. + + Try vdso32=0 if you encounter an error that says: + dl_main: Assertion `(void *) ph->p_vaddr == _rtld_local._dl_sysinfo_dso' failed! + + vector= [IA-64,SMP] + vector=percpu: enable percpu vector domain + + video= [FB] Frame buffer configuration + See Documentation/fb/modedb.txt. + + video.brightness_switch_enabled= [0,1] + If set to 1, on receiving an ACPI notify event + generated by hotkey, video driver will adjust brightness + level and then send out the event to user space through + the allocated input device; If set to 0, video driver + will only send out the event without touching backlight + brightness level. + default: 1 + + virtio_mmio.device= + [VMMIO] Memory mapped virtio (platform) device. + + @:[:] + where: + := size (can use standard suffixes + like K, M and G) + := physical base address + := interrupt number (as passed to + request_irq()) + := (optional) platform device id + example: + virtio_mmio.device=1K@0x100b0000:48:7 + + Can be used multiple times for multiple devices. + + vga= [BOOT,X86-32] Select a particular video mode + See Documentation/x86/boot.txt and + Documentation/svga.txt. + Use vga=ask for menu. + This is actually a boot loader parameter; the value is + passed to the kernel using a special protocol. + + vmalloc=nn[KMG] [KNL,BOOT] Forces the vmalloc area to have an exact + size of . This can be used to increase the + minimum size (128MB on x86). It can also be used to + decrease the size and leave more room for directly + mapped kernel RAM. + + vmhalt= [KNL,S390] Perform z/VM CP command after system halt. + Format: + + vmpanic= [KNL,S390] Perform z/VM CP command after kernel panic. + Format: + + vmpoff= [KNL,S390] Perform z/VM CP command after power off. + Format: + + vsyscall= [X86-64] + Controls the behavior of vsyscalls (i.e. calls to + fixed addresses of 0xffffffffff600x00 from legacy + code). Most statically-linked binaries and older + versions of glibc use these calls. Because these + functions are at fixed addresses, they make nice + targets for exploits that can control RIP. + + emulate [default] Vsyscalls turn into traps and are + emulated reasonably safely. + + native Vsyscalls are native syscall instructions. + This is a little bit faster than trapping + and makes a few dynamic recompilers work + better than they would in emulation mode. + It also makes exploits much easier to write. + + none Vsyscalls don't work at all. This makes + them quite hard to use for exploits but + might break your system. + + vt.color= [VT] Default text color. + Format: 0xYX, X = foreground, Y = background. + Default: 0x07 = light gray on black. + + vt.cur_default= [VT] Default cursor shape. + Format: 0xCCBBAA, where AA, BB, and CC are the same as + the parameters of the [?A;B;Cc escape sequence; + see VGA-softcursor.txt. Default: 2 = underline. + + vt.default_blu= [VT] + Format: ,,,..., + Change the default blue palette of the console. + This is a 16-member array composed of values + ranging from 0-255. + + vt.default_grn= [VT] + Format: ,,,..., + Change the default green palette of the console. + This is a 16-member array composed of values + ranging from 0-255. + + vt.default_red= [VT] + Format: ,,,..., + Change the default red palette of the console. + This is a 16-member array composed of values + ranging from 0-255. + + vt.default_utf8= + [VT] + Format=<0|1> + Set system-wide default UTF-8 mode for all tty's. + Default is 1, i.e. UTF-8 mode is enabled for all + newly opened terminals. + + vt.global_cursor_default= + [VT] + Format=<-1|0|1> + Set system-wide default for whether a cursor + is shown on new VTs. Default is -1, + i.e. cursors will be created by default unless + overridden by individual drivers. 0 will hide + cursors, 1 will display them. + + vt.italic= [VT] Default color for italic text; 0-15. + Default: 2 = green. + + vt.underline= [VT] Default color for underlined text; 0-15. + Default: 3 = cyan. + + watchdog timers [HW,WDT] For information on watchdog timers, + see Documentation/watchdog/watchdog-parameters.txt + or other driver-specific files in the + Documentation/watchdog/ directory. + + workqueue.watchdog_thresh= + If CONFIG_WQ_WATCHDOG is configured, workqueue can + warn stall conditions and dump internal state to + help debugging. 0 disables workqueue stall + detection; otherwise, it's the stall threshold + duration in seconds. The default value is 30 and + it can be updated at runtime by writing to the + corresponding sysfs file. + + workqueue.disable_numa + By default, all work items queued to unbound + workqueues are affine to the NUMA nodes they're + issued on, which results in better behavior in + general. If NUMA affinity needs to be disabled for + whatever reason, this option can be used. Note + that this also can be controlled per-workqueue for + workqueues visible under /sys/bus/workqueue/. + + workqueue.power_efficient + Per-cpu workqueues are generally preferred because + they show better performance thanks to cache + locality; unfortunately, per-cpu workqueues tend to + be more power hungry than unbound workqueues. + + Enabling this makes the per-cpu workqueues which + were observed to contribute significantly to power + consumption unbound, leading to measurably lower + power usage at the cost of small performance + overhead. + + The default value of this parameter is determined by + the config option CONFIG_WQ_POWER_EFFICIENT_DEFAULT. + + workqueue.debug_force_rr_cpu + Workqueue used to implicitly guarantee that work + items queued without explicit CPU specified are put + on the local CPU. This guarantee is no longer true + and while local CPU is still preferred work items + may be put on foreign CPUs. This debug option + forces round-robin CPU selection to flush out + usages which depend on the now broken guarantee. + When enabled, memory and cache locality will be + impacted. + + x2apic_phys [X86-64,APIC] Use x2apic physical mode instead of + default x2apic cluster mode on platforms + supporting x2apic. + + x86_intel_mid_timer= [X86-32,APBT] + Choose timer option for x86 Intel MID platform. + Two valid options are apbt timer only and lapic timer + plus one apbt timer for broadcast timer. + x86_intel_mid_timer=apbt_only | lapic_and_apbt + + xen_512gb_limit [KNL,X86-64,XEN] + Restricts the kernel running paravirtualized under Xen + to use only up to 512 GB of RAM. The reason to do so is + crash analysis tools and Xen tools for doing domain + save/restore/migration must be enabled to handle larger + domains. + + xen_emul_unplug= [HW,X86,XEN] + Unplug Xen emulated devices + Format: [unplug0,][unplug1] + ide-disks -- unplug primary master IDE devices + aux-ide-disks -- unplug non-primary-master IDE devices + nics -- unplug network devices + all -- unplug all emulated devices (NICs and IDE disks) + unnecessary -- unplugging emulated devices is + unnecessary even if the host did not respond to + the unplug protocol + never -- do not unplug even if version check succeeds + + xen_nopvspin [X86,XEN] + Disables the ticketlock slowpath using Xen PV + optimizations. + + xen_nopv [X86] + Disables the PV optimizations forcing the HVM guest to + run as generic HVM guest with no PV drivers. + + xirc2ps_cs= [NET,PCMCIA] + Format: + ,,,,,[,[,[,]]] + +------------------------ + +Todo +---- + + Add more DRM drivers. diff --git a/Documentation/admin-guide/md.rst b/Documentation/admin-guide/md.rst new file mode 100644 index 000000000000..e449fb5f277c --- /dev/null +++ b/Documentation/admin-guide/md.rst @@ -0,0 +1,727 @@ +RAID arrays +=========== + +Boot time assembly of RAID arrays +--------------------------------- + +Tools that manage md devices can be found at + http://www.kernel.org/pub/linux/utils/raid/ + + +You can boot with your md device with the following kernel command +lines: + +for old raid arrays without persistent superblocks:: + + md=,,,,dev0,dev1,...,devn + +for raid arrays with persistent superblocks:: + + md=,dev0,dev1,...,devn + +or, to assemble a partitionable array:: + + md=d,dev0,dev1,...,devn + +``md device no.`` ++++++++++++++++++ + +The number of the md device + +================= ========= +``md device no.`` device +================= ========= + 0 md0 + 1 md1 + 2 md2 + 3 md3 + 4 md4 +================= ========= + +``raid level`` +++++++++++++++ + +level of the RAID array + +=============== ============= +``raid level`` level +=============== ============= +-1 linear mode +0 striped mode +=============== ============= + +other modes are only supported with persistent super blocks + +``chunk size factor`` ++++++++++++++++++++++ + +(raid-0 and raid-1 only) + +Set the chunk size as 4k << n. + +``fault level`` ++++++++++++++++ + +Totally ignored + +``dev0`` to ``devn`` +++++++++++++++++++++ + +e.g. ``/dev/hda1``, ``/dev/hdc1``, ``/dev/sda1``, ``/dev/sdb1`` + +A possible loadlin line (Harald Hoyer ) looks like this:: + + e:\loadlin\loadlin e:\zimage root=/dev/md0 md=0,0,4,0,/dev/hdb2,/dev/hdc3 ro + + +Boot time autodetection of RAID arrays +-------------------------------------- + +When md is compiled into the kernel (not as module), partitions of +type 0xfd are scanned and automatically assembled into RAID arrays. +This autodetection may be suppressed with the kernel parameter +``raid=noautodetect``. As of kernel 2.6.9, only drives with a type 0 +superblock can be autodetected and run at boot time. + +The kernel parameter ``raid=partitionable`` (or ``raid=part``) means +that all auto-detected arrays are assembled as partitionable. + +Boot time assembly of degraded/dirty arrays +------------------------------------------- + +If a raid5 or raid6 array is both dirty and degraded, it could have +undetectable data corruption. This is because the fact that it is +``dirty`` means that the parity cannot be trusted, and the fact that it +is degraded means that some datablocks are missing and cannot reliably +be reconstructed (due to no parity). + +For this reason, md will normally refuse to start such an array. This +requires the sysadmin to take action to explicitly start the array +despite possible corruption. This is normally done with:: + + mdadm --assemble --force .... + +This option is not really available if the array has the root +filesystem on it. In order to support this booting from such an +array, md supports a module parameter ``start_dirty_degraded`` which, +when set to 1, bypassed the checks and will allows dirty degraded +arrays to be started. + +So, to boot with a root filesystem of a dirty degraded raid 5 or 6, use:: + + md-mod.start_dirty_degraded=1 + + +Superblock formats +------------------ + +The md driver can support a variety of different superblock formats. +Currently, it supports superblock formats ``0.90.0`` and the ``md-1`` format +introduced in the 2.5 development series. + +The kernel will autodetect which format superblock is being used. + +Superblock format ``0`` is treated differently to others for legacy +reasons - it is the original superblock format. + + +General Rules - apply for all superblock formats +------------------------------------------------ + +An array is ``created`` by writing appropriate superblocks to all +devices. + +It is ``assembled`` by associating each of these devices with an +particular md virtual device. Once it is completely assembled, it can +be accessed. + +An array should be created by a user-space tool. This will write +superblocks to all devices. It will usually mark the array as +``unclean``, or with some devices missing so that the kernel md driver +can create appropriate redundancy (copying in raid 1, parity +calculation in raid 4/5). + +When an array is assembled, it is first initialized with the +SET_ARRAY_INFO ioctl. This contains, in particular, a major and minor +version number. The major version number selects which superblock +format is to be used. The minor number might be used to tune handling +of the format, such as suggesting where on each device to look for the +superblock. + +Then each device is added using the ADD_NEW_DISK ioctl. This +provides, in particular, a major and minor number identifying the +device to add. + +The array is started with the RUN_ARRAY ioctl. + +Once started, new devices can be added. They should have an +appropriate superblock written to them, and then be passed in with +ADD_NEW_DISK. + +Devices that have failed or are not yet active can be detached from an +array using HOT_REMOVE_DISK. + + +Specific Rules that apply to format-0 super block arrays, and arrays with no superblock (non-persistent) +-------------------------------------------------------------------------------------------------------- + +An array can be ``created`` by describing the array (level, chunksize +etc) in a SET_ARRAY_INFO ioctl. This must have ``major_version==0`` and +``raid_disks != 0``. + +Then uninitialized devices can be added with ADD_NEW_DISK. The +structure passed to ADD_NEW_DISK must specify the state of the device +and its role in the array. + +Once started with RUN_ARRAY, uninitialized spares can be added with +HOT_ADD_DISK. + + +MD devices in sysfs +------------------- + +md devices appear in sysfs (``/sys``) as regular block devices, +e.g.:: + + /sys/block/md0 + +Each ``md`` device will contain a subdirectory called ``md`` which +contains further md-specific information about the device. + +All md devices contain: + + level + a text file indicating the ``raid level``. e.g. raid0, raid1, + raid5, linear, multipath, faulty. + If no raid level has been set yet (array is still being + assembled), the value will reflect whatever has been written + to it, which may be a name like the above, or may be a number + such as ``0``, ``5``, etc. + + raid_disks + a text file with a simple number indicating the number of devices + in a fully functional array. If this is not yet known, the file + will be empty. If an array is being resized this will contain + the new number of devices. + Some raid levels allow this value to be set while the array is + active. This will reconfigure the array. Otherwise it can only + be set while assembling an array. + A change to this attribute will not be permitted if it would + reduce the size of the array. To reduce the number of drives + in an e.g. raid5, the array size must first be reduced by + setting the ``array_size`` attribute. + + chunk_size + This is the size in bytes for ``chunks`` and is only relevant to + raid levels that involve striping (0,4,5,6,10). The address space + of the array is conceptually divided into chunks and consecutive + chunks are striped onto neighbouring devices. + The size should be at least PAGE_SIZE (4k) and should be a power + of 2. This can only be set while assembling an array + + layout + The ``layout`` for the array for the particular level. This is + simply a number that is interpretted differently by different + levels. It can be written while assembling an array. + + array_size + This can be used to artificially constrain the available space in + the array to be less than is actually available on the combined + devices. Writing a number (in Kilobytes) which is less than + the available size will set the size. Any reconfiguration of the + array (e.g. adding devices) will not cause the size to change. + Writing the word ``default`` will cause the effective size of the + array to be whatever size is actually available based on + ``level``, ``chunk_size`` and ``component_size``. + + This can be used to reduce the size of the array before reducing + the number of devices in a raid4/5/6, or to support external + metadata formats which mandate such clipping. + + reshape_position + This is either ``none`` or a sector number within the devices of + the array where ``reshape`` is up to. If this is set, the three + attributes mentioned above (raid_disks, chunk_size, layout) can + potentially have 2 values, an old and a new value. If these + values differ, reading the attribute returns:: + + new (old) + + and writing will effect the ``new`` value, leaving the ``old`` + unchanged. + + component_size + For arrays with data redundancy (i.e. not raid0, linear, faulty, + multipath), all components must be the same size - or at least + there must a size that they all provide space for. This is a key + part or the geometry of the array. It is measured in sectors + and can be read from here. Writing to this value may resize + the array if the personality supports it (raid1, raid5, raid6), + and if the component drives are large enough. + + metadata_version + This indicates the format that is being used to record metadata + about the array. It can be 0.90 (traditional format), 1.0, 1.1, + 1.2 (newer format in varying locations) or ``none`` indicating that + the kernel isn't managing metadata at all. + Alternately it can be ``external:`` followed by a string which + is set by user-space. This indicates that metadata is managed + by a user-space program. Any device failure or other event that + requires a metadata update will cause array activity to be + suspended until the event is acknowledged. + + resync_start + The point at which resync should start. If no resync is needed, + this will be a very large number (or ``none`` since 2.6.30-rc1). At + array creation it will default to 0, though starting the array as + ``clean`` will set it much larger. + + new_dev + This file can be written but not read. The value written should + be a block device number as major:minor. e.g. 8:0 + This will cause that device to be attached to the array, if it is + available. It will then appear at md/dev-XXX (depending on the + name of the device) and further configuration is then possible. + + safe_mode_delay + When an md array has seen no write requests for a certain period + of time, it will be marked as ``clean``. When another write + request arrives, the array is marked as ``dirty`` before the write + commences. This is known as ``safe_mode``. + The ``certain period`` is controlled by this file which stores the + period as a number of seconds. The default is 200msec (0.200). + Writing a value of 0 disables safemode. + + array_state + This file contains a single word which describes the current + state of the array. In many cases, the state can be set by + writing the word for the desired state, however some states + cannot be explicitly set, and some transitions are not allowed. + + Select/poll works on this file. All changes except between + Active_idle and active (which can be frequent and are not + very interesting) are notified. active->active_idle is + reported if the metadata is externally managed. + + clear + No devices, no size, no level + + Writing is equivalent to STOP_ARRAY ioctl + + inactive + May have some settings, but array is not active + all IO results in error + + When written, doesn't tear down array, but just stops it + + suspended (not supported yet) + All IO requests will block. The array can be reconfigured. + + Writing this, if accepted, will block until array is quiessent + + readonly + no resync can happen. no superblocks get written. + + Write requests fail + + read-auto + like readonly, but behaves like ``clean`` on a write request. + + clean + no pending writes, but otherwise active. + + When written to inactive array, starts without resync + + If a write request arrives then + if metadata is known, mark ``dirty`` and switch to ``active``. + if not known, block and switch to write-pending + + If written to an active array that has pending writes, then fails. + active + fully active: IO and resync can be happening. + When written to inactive array, starts with resync + + write-pending + clean, but writes are blocked waiting for ``active`` to be written. + + active-idle + like active, but no writes have been seen for a while (safe_mode_delay). + + bitmap/location + This indicates where the write-intent bitmap for the array is + stored. + + It can be one of ``none``, ``file`` or ``[+-]N``. + ``file`` may later be extended to ``file:/file/name`` + ``[+-]N`` means that many sectors from the start of the metadata. + + This is replicated on all devices. For arrays with externally + managed metadata, the offset is from the beginning of the + device. + + bitmap/chunksize + The size, in bytes, of the chunk which will be represented by a + single bit. For RAID456, it is a portion of an individual + device. For RAID10, it is a portion of the array. For RAID1, it + is both (they come to the same thing). + + bitmap/time_base + The time, in seconds, between looking for bits in the bitmap to + be cleared. In the current implementation, a bit will be cleared + between 2 and 3 times ``time_base`` after all the covered blocks + are known to be in-sync. + + bitmap/backlog + When write-mostly devices are active in a RAID1, write requests + to those devices proceed in the background - the filesystem (or + other user of the device) does not have to wait for them. + ``backlog`` sets a limit on the number of concurrent background + writes. If there are more than this, new writes will by + synchronous. + + bitmap/metadata + This can be either ``internal`` or ``external``. + + ``internal`` + is the default and means the metadata for the bitmap + is stored in the first 256 bytes of the allocated space and is + managed by the md module. + + ``external`` + means that bitmap metadata is managed externally to + the kernel (i.e. by some userspace program) + + bitmap/can_clear + This is either ``true`` or ``false``. If ``true``, then bits in the + bitmap will be cleared when the corresponding blocks are thought + to be in-sync. If ``false``, bits will never be cleared. + This is automatically set to ``false`` if a write happens on a + degraded array, or if the array becomes degraded during a write. + When metadata is managed externally, it should be set to true + once the array becomes non-degraded, and this fact has been + recorded in the metadata. + + + + +As component devices are added to an md array, they appear in the ``md`` +directory as new directories named:: + + dev-XXX + +where ``XXX`` is a name that the kernel knows for the device, e.g. hdb1. +Each directory contains: + + block + a symlink to the block device in /sys/block, e.g.:: + + /sys/block/md0/md/dev-hdb1/block -> ../../../../block/hdb/hdb1 + + super + A file containing an image of the superblock read from, or + written to, that device. + + state + A file recording the current state of the device in the array + which can be a comma separated list of: + + faulty + device has been kicked from active use due to + a detected fault, or it has unacknowledged bad + blocks + + in_sync + device is a fully in-sync member of the array + + writemostly + device will only be subject to read + requests if there are no other options. + + This applies only to raid1 arrays. + + blocked + device has failed, and the failure hasn't been + acknowledged yet by the metadata handler. + + Writes that would write to this device if + it were not faulty are blocked. + + spare + device is working, but not a full member. + + This includes spares that are in the process + of being recovered to + + write_error + device has ever seen a write error. + + want_replacement + device is (mostly) working but probably + should be replaced, either due to errors or + due to user request. + + replacement + device is a replacement for another active + device with same raid_disk. + + + This list may grow in future. + + This can be written to. + + Writing ``faulty`` simulates a failure on the device. + + Writing ``remove`` removes the device from the array. + + Writing ``writemostly`` sets the writemostly flag. + + Writing ``-writemostly`` clears the writemostly flag. + + Writing ``blocked`` sets the ``blocked`` flag. + + Writing ``-blocked`` clears the ``blocked`` flags and allows writes + to complete and possibly simulates an error. + + Writing ``in_sync`` sets the in_sync flag. + + Writing ``write_error`` sets writeerrorseen flag. + + Writing ``-write_error`` clears writeerrorseen flag. + + Writing ``want_replacement`` is allowed at any time except to a + replacement device or a spare. It sets the flag. + + Writing ``-want_replacement`` is allowed at any time. It clears + the flag. + + Writing ``replacement`` or ``-replacement`` is only allowed before + starting the array. It sets or clears the flag. + + + This file responds to select/poll. Any change to ``faulty`` + or ``blocked`` causes an event. + + errors + An approximate count of read errors that have been detected on + this device but have not caused the device to be evicted from + the array (either because they were corrected or because they + happened while the array was read-only). When using version-1 + metadata, this value persists across restarts of the array. + + This value can be written while assembling an array thus + providing an ongoing count for arrays with metadata managed by + userspace. + + slot + This gives the role that the device has in the array. It will + either be ``none`` if the device is not active in the array + (i.e. is a spare or has failed) or an integer less than the + ``raid_disks`` number for the array indicating which position + it currently fills. This can only be set while assembling an + array. A device for which this is set is assumed to be working. + + offset + This gives the location in the device (in sectors from the + start) where data from the array will be stored. Any part of + the device before this offset is not touched, unless it is + used for storing metadata (Formats 1.1 and 1.2). + + size + The amount of the device, after the offset, that can be used + for storage of data. This will normally be the same as the + component_size. This can be written while assembling an + array. If a value less than the current component_size is + written, it will be rejected. + + recovery_start + When the device is not ``in_sync``, this records the number of + sectors from the start of the device which are known to be + correct. This is normally zero, but during a recovery + operation it will steadily increase, and if the recovery is + interrupted, restoring this value can cause recovery to + avoid repeating the earlier blocks. With v1.x metadata, this + value is saved and restored automatically. + + This can be set whenever the device is not an active member of + the array, either before the array is activated, or before + the ``slot`` is set. + + Setting this to ``none`` is equivalent to setting ``in_sync``. + Setting to any other value also clears the ``in_sync`` flag. + + bad_blocks + This gives the list of all known bad blocks in the form of + start address and length (in sectors respectively). If output + is too big to fit in a page, it will be truncated. Writing + ``sector length`` to this file adds new acknowledged (i.e. + recorded to disk safely) bad blocks. + + unacknowledged_bad_blocks + This gives the list of known-but-not-yet-saved-to-disk bad + blocks in the same form of ``bad_blocks``. If output is too big + to fit in a page, it will be truncated. Writing to this file + adds bad blocks without acknowledging them. This is largely + for testing. + + + +An active md device will also contain an entry for each active device +in the array. These are named:: + + rdNN + +where ``NN`` is the position in the array, starting from 0. +So for a 3 drive array there will be rd0, rd1, rd2. +These are symbolic links to the appropriate ``dev-XXX`` entry. +Thus, for example:: + + cat /sys/block/md*/md/rd*/state + +will show ``in_sync`` on every line. + + + +Active md devices for levels that support data redundancy (1,4,5,6,10) +also have + + sync_action + a text file that can be used to monitor and control the rebuild + process. It contains one word which can be one of: + + resync + redundancy is being recalculated after unclean + shutdown or creation + + recover + a hot spare is being built to replace a + failed/missing device + + idle + nothing is happening + check + A full check of redundancy was requested and is + happening. This reads all blocks and checks + them. A repair may also happen for some raid + levels. + + repair + A full check and repair is happening. This is + similar to ``resync``, but was requested by the + user, and the write-intent bitmap is NOT used to + optimise the process. + + This file is writable, and each of the strings that could be + read are meaningful for writing. + + ``idle`` will stop an active resync/recovery etc. There is no + guarantee that another resync/recovery may not be automatically + started again, though some event will be needed to trigger + this. + + ``resync`` or ``recovery`` can be used to restart the + corresponding operation if it was stopped with ``idle``. + + ``check`` and ``repair`` will start the appropriate process + providing the current state is ``idle``. + + This file responds to select/poll. Any important change in the value + triggers a poll event. Sometimes the value will briefly be + ``recover`` if a recovery seems to be needed, but cannot be + achieved. In that case, the transition to ``recover`` isn't + notified, but the transition away is. + + degraded + This contains a count of the number of devices by which the + arrays is degraded. So an optimal array will show ``0``. A + single failed/missing drive will show ``1``, etc. + + This file responds to select/poll, any increase or decrease + in the count of missing devices will trigger an event. + + mismatch_count + When performing ``check`` and ``repair``, and possibly when + performing ``resync``, md will count the number of errors that are + found. The count in ``mismatch_cnt`` is the number of sectors + that were re-written, or (for ``check``) would have been + re-written. As most raid levels work in units of pages rather + than sectors, this may be larger than the number of actual errors + by a factor of the number of sectors in a page. + + bitmap_set_bits + If the array has a write-intent bitmap, then writing to this + attribute can set bits in the bitmap, indicating that a resync + would need to check the corresponding blocks. Either individual + numbers or start-end pairs can be written. Multiple numbers + can be separated by a space. + + Note that the numbers are ``bit`` numbers, not ``block`` numbers. + They should be scaled by the bitmap_chunksize. + + sync_speed_min, sync_speed_max + This are similar to ``/proc/sys/dev/raid/speed_limit_{min,max}`` + however they only apply to the particular array. + + If no value has been written to these, or if the word ``system`` + is written, then the system-wide value is used. If a value, + in kibibytes-per-second is written, then it is used. + + When the files are read, they show the currently active value + followed by ``(local)`` or ``(system)`` depending on whether it is + a locally set or system-wide value. + + sync_completed + This shows the number of sectors that have been completed of + whatever the current sync_action is, followed by the number of + sectors in total that could need to be processed. The two + numbers are separated by a ``/`` thus effectively showing one + value, a fraction of the process that is complete. + + A ``select`` on this attribute will return when resync completes, + when it reaches the current sync_max (below) and possibly at + other times. + + sync_speed + This shows the current actual speed, in K/sec, of the current + sync_action. It is averaged over the last 30 seconds. + + suspend_lo, suspend_hi + The two values, given as numbers of sectors, indicate a range + within the array where IO will be blocked. This is currently + only supported for raid4/5/6. + + sync_min, sync_max + The two values, given as numbers of sectors, indicate a range + within the array where ``check``/``repair`` will operate. Must be + a multiple of chunk_size. When it reaches ``sync_max`` it will + pause, rather than complete. + You can use ``select`` or ``poll`` on ``sync_completed`` to wait for + that number to reach sync_max. Then you can either increase + ``sync_max``, or can write ``idle`` to ``sync_action``. + + The value of ``max`` for ``sync_max`` effectively disables the limit. + When a resync is active, the value can only ever be increased, + never decreased. + The value of ``0`` is the minimum for ``sync_min``. + + + +Each active md device may also have attributes specific to the +personality module that manages it. +These are specific to the implementation of the module and could +change substantially if the implementation changes. + +These currently include: + + stripe_cache_size (currently raid5 only) + number of entries in the stripe cache. This is writable, but + there are upper and lower limits (32768, 17). Default is 256. + + strip_cache_active (currently raid5 only) + number of active entries in the stripe cache + + preread_bypass_threshold (currently raid5 only) + number of times a stripe requiring preread will be bypassed by + a stripe that does not require preread. For fairness defaults + to 1. Setting this to 0 disables bypass accounting and + requires preread stripes to wait until all full-width stripe- + writes are complete. Valid values are 0 to stripe_cache_size. diff --git a/Documentation/admin-guide/mono.rst b/Documentation/admin-guide/mono.rst new file mode 100644 index 000000000000..9a9744ca0cf3 --- /dev/null +++ b/Documentation/admin-guide/mono.rst @@ -0,0 +1,68 @@ +Mono(tm) Binary Kernel Support for Linux +----------------------------------------- + +To configure Linux to automatically execute Mono-based .NET binaries +(in the form of .exe files) without the need to use the mono CLR +wrapper, you can use the BINFMT_MISC kernel support. + +This will allow you to execute Mono-based .NET binaries just like any +other program after you have done the following: + +1) You MUST FIRST install the Mono CLR support, either by downloading + a binary package, a source tarball or by installing from CVS. Binary + packages for several distributions can be found at: + + http://go-mono.com/download.html + + Instructions for compiling Mono can be found at: + + http://www.go-mono.com/compiling.html + + Once the Mono CLR support has been installed, just check that + ``/usr/bin/mono`` (which could be located elsewhere, for example + ``/usr/local/bin/mono``) is working. + +2) You have to compile BINFMT_MISC either as a module or into + the kernel (``CONFIG_BINFMT_MISC``) and set it up properly. + If you choose to compile it as a module, you will have + to insert it manually with modprobe/insmod, as kmod + cannot be easily supported with binfmt_misc. + Read the file ``binfmt_misc.txt`` in this directory to know + more about the configuration process. + +3) Add the following entries to ``/etc/rc.local`` or similar script + to be run at system startup:: + + # Insert BINFMT_MISC module into the kernel + if [ ! -e /proc/sys/fs/binfmt_misc/register ]; then + /sbin/modprobe binfmt_misc + # Some distributions, like Fedora Core, perform + # the following command automatically when the + # binfmt_misc module is loaded into the kernel + # or during normal boot up (systemd-based systems). + # Thus, it is possible that the following line + # is not needed at all. + mount -t binfmt_misc none /proc/sys/fs/binfmt_misc + fi + + # Register support for .NET CLR binaries + if [ -e /proc/sys/fs/binfmt_misc/register ]; then + # Replace /usr/bin/mono with the correct pathname to + # the Mono CLR runtime (usually /usr/local/bin/mono + # when compiling from sources or CVS). + echo ':CLR:M::MZ::/usr/bin/mono:' > /proc/sys/fs/binfmt_misc/register + else + echo "No binfmt_misc support" + exit 1 + fi + +4) Check that ``.exe`` binaries can be ran without the need of a + wrapper script, simply by launching the ``.exe`` file directly + from a command prompt, for example:: + + /usr/bin/xsd.exe + + .. note:: + + If this fails with a permission denied error, check + that the ``.exe`` file has execute permissions. diff --git a/Documentation/admin-guide/oops-tracing.rst b/Documentation/admin-guide/oops-tracing.rst new file mode 100644 index 000000000000..3e25ea7349ee --- /dev/null +++ b/Documentation/admin-guide/oops-tracing.rst @@ -0,0 +1,300 @@ +OOPS tracing +============ + +.. note:: + + ``ksymoops`` is useless on 2.6 or upper. Please use the Oops in its original + format (from ``dmesg``, etc). Ignore any references in this or other docs to + "decoding the Oops" or "running it through ksymoops". + If you post an Oops from 2.6+ that has been run through ``ksymoops``, + people will just tell you to repost it. + +Quick Summary +------------- + +Find the Oops and send it to the maintainer of the kernel area that seems to be +involved with the problem. Don't worry too much about getting the wrong person. +If you are unsure send it to the person responsible for the code relevant to +what you were doing. If it occurs repeatably try and describe how to recreate +it. That's worth even more than the oops. + +If you are totally stumped as to whom to send the report, send it to +linux-kernel@vger.kernel.org. Thanks for your help in making Linux as +stable as humanly possible. + +Where is the Oops? +---------------------- + +Normally the Oops text is read from the kernel buffers by klogd and +handed to ``syslogd`` which writes it to a syslog file, typically +``/var/log/messages`` (depends on ``/etc/syslog.conf``). Sometimes ``klogd`` +dies, in which case you can run ``dmesg > file`` to read the data from the +kernel buffers and save it. Or you can ``cat /proc/kmsg > file``, however you +have to break in to stop the transfer, ``kmsg`` is a "never ending file". +If the machine has crashed so badly that you cannot enter commands or +the disk is not available then you have three options : + +(1) Hand copy the text from the screen and type it in after the machine + has restarted. Messy but it is the only option if you have not + planned for a crash. Alternatively, you can take a picture of + the screen with a digital camera - not nice, but better than + nothing. If the messages scroll off the top of the console, you + may find that booting with a higher resolution (eg, ``vga=791``) + will allow you to read more of the text. (Caveat: This needs ``vesafb``, + so won't help for 'early' oopses) + +(2) Boot with a serial console (see + :ref:`Documentation/serial-console.txt `), + run a null modem to a second machine and capture the output there + using your favourite communication program. Minicom works well. + +(3) Use Kdump (see Documentation/kdump/kdump.txt), + extract the kernel ring buffer from old memory with using dmesg + gdbmacro in Documentation/kdump/gdbmacros.txt. + + +Full Information +---------------- + +.. note:: + + the message from Linus below applies to 2.4 kernel. I have preserved it + for historical reasons, and because some of the information in it still + applies. Especially, please ignore any references to ksymoops. + + :: + + From: Linus Torvalds + + How to track down an Oops.. [originally a mail to linux-kernel] + + The main trick is having 5 years of experience with those pesky oops + messages ;-) + +Actually, there are things you can do that make this easier. I have two +separate approaches:: + + gdb /usr/src/linux/vmlinux + gdb> disassemble + +That's the easy way to find the problem, at least if the bug-report is +well made (like this one was - run through ``ksymoops`` to get the +information of which function and the offset in the function that it +happened in). + +Oh, it helps if the report happens on a kernel that is compiled with the +same compiler and similar setups. + +The other thing to do is disassemble the "Code:" part of the bug report: +ksymoops will do this too with the correct tools, but if you don't have +the tools you can just do a silly program:: + + char str[] = "\xXX\xXX\xXX..."; + main(){} + +and compile it with ``gcc -g`` and then do ``disassemble str`` (where the ``XX`` +stuff are the values reported by the Oops - you can just cut-and-paste +and do a replace of spaces to ``\x`` - that's what I do, as I'm too lazy +to write a program to automate this all). + +Alternatively, you can use the shell script in ``scripts/decodecode``. +Its usage is:: + + decodecode < oops.txt + +The hex bytes that follow "Code:" may (in some architectures) have a series +of bytes that precede the current instruction pointer as well as bytes at and +following the current instruction pointer. In some cases, one instruction +byte or word is surrounded by ``<>`` or ``()``, as in ``<86>`` or ``(f00d)``. +These ``<>`` or ``()`` markings indicate the current instruction pointer. + +Example from i386, split into multiple lines for readability:: + + Code: f9 0f 8d f9 00 00 00 8d 42 0c e8 dd 26 11 c7 a1 60 ea 2b f9 8b 50 08 a1 + 64 ea 2b f9 8d 34 82 8b 1e 85 db 74 6d 8b 15 60 ea 2b f9 <8b> 43 04 39 42 54 + 7e 04 40 89 42 54 8b 43 04 3b 05 00 f6 52 c0 + +Finally, if you want to see where the code comes from, you can do:: + + cd /usr/src/linux + make fs/buffer.s # or whatever file the bug happened in + +and then you get a better idea of what happens than with the gdb +disassembly. + +Now, the trick is just then to combine all the data you have: the C +sources (and general knowledge of what it **should** do), the assembly +listing and the code disassembly (and additionally the register dump you +also get from the "oops" message - that can be useful to see **what** the +corrupted pointers were, and when you have the assembler listing you can +also match the other registers to whatever C expressions they were used +for). + +Essentially, you just look at what doesn't match (in this case it was the +"Code" disassembly that didn't match with what the compiler generated). +Then you need to find out **why** they don't match. Often it's simple - you +see that the code uses a NULL pointer and then you look at the code and +wonder how the NULL pointer got there, and if it's a valid thing to do +you just check against it.. + +Now, if somebody gets the idea that this is time-consuming and requires +some small amount of concentration, you're right. Which is why I will +mostly just ignore any panic reports that don't have the symbol table +info etc looked up: it simply gets too hard to look it up (I have some +programs to search for specific patterns in the kernel code segment, and +sometimes I have been able to look up those kinds of panics too, but +that really requires pretty good knowledge of the kernel just to be able +to pick out the right sequences etc..) + +**Sometimes** it happens that I just see the disassembled code sequence +from the panic, and I know immediately where it's coming from. That's when +I get worried that I've been doing this for too long ;-) + + Linus + + +--------------------------------------------------------------------------- + +Notes on Oops tracing with ``klogd`` +------------------------------------ + +In order to help Linus and the other kernel developers there has been +substantial support incorporated into ``klogd`` for processing protection +faults. In order to have full support for address resolution at least +version 1.3-pl3 of the ``sysklogd`` package should be used. + +When a protection fault occurs the ``klogd`` daemon automatically +translates important addresses in the kernel log messages to their +symbolic equivalents. This translated kernel message is then +forwarded through whatever reporting mechanism ``klogd`` is using. The +protection fault message can be simply cut out of the message files +and forwarded to the kernel developers. + +Two types of address resolution are performed by ``klogd``. The first is +static translation and the second is dynamic translation. Static +translation uses the System.map file in much the same manner that +ksymoops does. In order to do static translation the ``klogd`` daemon +must be able to find a system map file at daemon initialization time. +See the klogd man page for information on how ``klogd`` searches for map +files. + +Dynamic address translation is important when kernel loadable modules +are being used. Since memory for kernel modules is allocated from the +kernel's dynamic memory pools there are no fixed locations for either +the start of the module or for functions and symbols in the module. + +The kernel supports system calls which allow a program to determine +which modules are loaded and their location in memory. Using these +system calls the klogd daemon builds a symbol table which can be used +to debug a protection fault which occurs in a loadable kernel module. + +At the very minimum klogd will provide the name of the module which +generated the protection fault. There may be additional symbolic +information available if the developer of the loadable module chose to +export symbol information from the module. + +Since the kernel module environment can be dynamic there must be a +mechanism for notifying the ``klogd`` daemon when a change in module +environment occurs. There are command line options available which +allow klogd to signal the currently executing daemon that symbol +information should be refreshed. See the ``klogd`` manual page for more +information. + +A patch is included with the sysklogd distribution which modifies the +``modules-2.0.0`` package to automatically signal klogd whenever a module +is loaded or unloaded. Applying this patch provides essentially +seamless support for debugging protection faults which occur with +kernel loadable modules. + +The following is an example of a protection fault in a loadable module +processed by ``klogd``:: + + Aug 29 09:51:01 blizard kernel: Unable to handle kernel paging request at virtual address f15e97cc + Aug 29 09:51:01 blizard kernel: current->tss.cr3 = 0062d000, %cr3 = 0062d000 + Aug 29 09:51:01 blizard kernel: *pde = 00000000 + Aug 29 09:51:01 blizard kernel: Oops: 0002 + Aug 29 09:51:01 blizard kernel: CPU: 0 + Aug 29 09:51:01 blizard kernel: EIP: 0010:[oops:_oops+16/3868] + Aug 29 09:51:01 blizard kernel: EFLAGS: 00010212 + Aug 29 09:51:01 blizard kernel: eax: 315e97cc ebx: 003a6f80 ecx: 001be77b edx: 00237c0c + Aug 29 09:51:01 blizard kernel: esi: 00000000 edi: bffffdb3 ebp: 00589f90 esp: 00589f8c + Aug 29 09:51:01 blizard kernel: ds: 0018 es: 0018 fs: 002b gs: 002b ss: 0018 + Aug 29 09:51:01 blizard kernel: Process oops_test (pid: 3374, process nr: 21, stackpage=00589000) + Aug 29 09:51:01 blizard kernel: Stack: 315e97cc 00589f98 0100b0b4 bffffed4 0012e38e 00240c64 003a6f80 00000001 + Aug 29 09:51:01 blizard kernel: 00000000 00237810 bfffff00 0010a7fa 00000003 00000001 00000000 bfffff00 + Aug 29 09:51:01 blizard kernel: bffffdb3 bffffed4 ffffffda 0000002b 0007002b 0000002b 0000002b 00000036 + Aug 29 09:51:01 blizard kernel: Call Trace: [oops:_oops_ioctl+48/80] [_sys_ioctl+254/272] [_system_call+82/128] + Aug 29 09:51:01 blizard kernel: Code: c7 00 05 00 00 00 eb 08 90 90 90 90 90 90 90 90 89 ec 5d c3 + +--------------------------------------------------------------------------- + +:: + + Dr. G.W. Wettstein Oncology Research Div. Computing Facility + Roger Maris Cancer Center INTERNET: greg@wind.rmcc.com + 820 4th St. N. + Fargo, ND 58122 + Phone: 701-234-7556 + + +--------------------------------------------------------------------------- + +Tainted kernels +--------------- + +Some oops reports contain the string **'Tainted: '** after the program +counter. This indicates that the kernel has been tainted by some +mechanism. The string is followed by a series of position-sensitive +characters, each representing a particular tainted value. + + 1) 'G' if all modules loaded have a GPL or compatible license, 'P' if + any proprietary module has been loaded. Modules without a + MODULE_LICENSE or with a MODULE_LICENSE that is not recognised by + insmod as GPL compatible are assumed to be proprietary. + + 2) ``F`` if any module was force loaded by ``insmod -f``, ``' '`` if all + modules were loaded normally. + + 3) ``S`` if the oops occurred on an SMP kernel running on hardware that + hasn't been certified as safe to run multiprocessor. + Currently this occurs only on various Athlons that are not + SMP capable. + + 4) ``R`` if a module was force unloaded by ``rmmod -f``, ``' '`` if all + modules were unloaded normally. + + 5) ``M`` if any processor has reported a Machine Check Exception, + ``' '`` if no Machine Check Exceptions have occurred. + + 6) ``B`` if a page-release function has found a bad page reference or + some unexpected page flags. + + 7) ``U`` if a user or user application specifically requested that the + Tainted flag be set, ``' '`` otherwise. + + 8) ``D`` if the kernel has died recently, i.e. there was an OOPS or BUG. + + 9) ``A`` if the ACPI table has been overridden. + + 10) ``W`` if a warning has previously been issued by the kernel. + (Though some warnings may set more specific taint flags.) + + 11) ``C`` if a staging driver has been loaded. + + 12) ``I`` if the kernel is working around a severe bug in the platform + firmware (BIOS or similar). + + 13) ``O`` if an externally-built ("out-of-tree") module has been loaded. + + 14) ``E`` if an unsigned module has been loaded in a kernel supporting + module signature. + + 15) ``L`` if a soft lockup has previously occurred on the system. + + 16) ``K`` if the kernel has been live patched. + +The primary reason for the **'Tainted: '** string is to tell kernel +debuggers if this is a clean kernel or if anything unusual has +occurred. Tainting is permanent: even if an offending module is +unloaded, the tainted value remains to indicate that the kernel is not +trustworthy. diff --git a/Documentation/admin-guide/parport.rst b/Documentation/admin-guide/parport.rst new file mode 100644 index 000000000000..ad3f9b8a11e1 --- /dev/null +++ b/Documentation/admin-guide/parport.rst @@ -0,0 +1,286 @@ +Parport ++++++++ + +The ``parport`` code provides parallel-port support under Linux. This +includes the ability to share one port between multiple device +drivers. + +You can pass parameters to the ``parport`` code to override its automatic +detection of your hardware. This is particularly useful if you want +to use IRQs, since in general these can't be autoprobed successfully. +By default IRQs are not used even if they **can** be probed. This is +because there are a lot of people using the same IRQ for their +parallel port and a sound card or network card. + +The ``parport`` code is split into two parts: generic (which deals with +port-sharing) and architecture-dependent (which deals with actually +using the port). + + +Parport as modules +================== + +If you load the `parport`` code as a module, say:: + + # insmod parport + +to load the generic ``parport`` code. You then must load the +architecture-dependent code with (for example):: + + # insmod parport_pc io=0x3bc,0x378,0x278 irq=none,7,auto + +to tell the ``parport`` code that you want three PC-style ports, one at +0x3bc with no IRQ, one at 0x378 using IRQ 7, and one at 0x278 with an +auto-detected IRQ. Currently, PC-style (``parport_pc``), Sun ``bpp``, +Amiga, Atari, and MFC3 hardware is supported. + +PCI parallel I/O card support comes from ``parport_pc``. Base I/O +addresses should not be specified for supported PCI cards since they +are automatically detected. + + +modprobe +-------- + +If you use modprobe , you will find it useful to add lines as below to a +configuration file in /etc/modprobe.d/ directory:: + + alias parport_lowlevel parport_pc + options parport_pc io=0x378,0x278 irq=7,auto + +modprobe will load ``parport_pc`` (with the options ``io=0x378,0x278 irq=7,auto``) +whenever a parallel port device driver (such as ``lp``) is loaded. + +Note that these are example lines only! You shouldn't in general need +to specify any options to ``parport_pc`` in order to be able to use a +parallel port. + + +Parport probe [optional] +------------------------ + +In 2.2 kernels there was a module called ``parport_probe``, which was used +for collecting IEEE 1284 device ID information. This has now been +enhanced and now lives with the IEEE 1284 support. When a parallel +port is detected, the devices that are connected to it are analysed, +and information is logged like this:: + + parport0: Printer, BJC-210 (Canon) + +The probe information is available from files in ``/proc/sys/dev/parport/``. + + +Parport linked into the kernel statically +========================================= + +If you compile the ``parport`` code into the kernel, then you can use +kernel boot parameters to get the same effect. Add something like the +following to your LILO command line:: + + parport=0x3bc parport=0x378,7 parport=0x278,auto,nofifo + +You can have many ``parport=...`` statements, one for each port you want +to add. Adding ``parport=0`` to the kernel command-line will disable +parport support entirely. Adding ``parport=auto`` to the kernel +command-line will make ``parport`` use any IRQ lines or DMA channels that +it auto-detects. + + +Files in /proc +============== + +If you have configured the ``/proc`` filesystem into your kernel, you will +see a new directory entry: ``/proc/sys/dev/parport``. In there will be a +directory entry for each parallel port for which parport is +configured. In each of those directories are a collection of files +describing that parallel port. + +The ``/proc/sys/dev/parport`` directory tree looks like:: + + parport + |-- default + | |-- spintime + | `-- timeslice + |-- parport0 + | |-- autoprobe + | |-- autoprobe0 + | |-- autoprobe1 + | |-- autoprobe2 + | |-- autoprobe3 + | |-- devices + | | |-- active + | | `-- lp + | | `-- timeslice + | |-- base-addr + | |-- irq + | |-- dma + | |-- modes + | `-- spintime + `-- parport1 + |-- autoprobe + |-- autoprobe0 + |-- autoprobe1 + |-- autoprobe2 + |-- autoprobe3 + |-- devices + | |-- active + | `-- ppa + | `-- timeslice + |-- base-addr + |-- irq + |-- dma + |-- modes + `-- spintime + +.. tabularcolumns:: |p{4.0cm}|p{13.5cm}| + +======================= ======================================================= +File Contents +======================= ======================================================= +``devices/active`` A list of the device drivers using that port. A "+" + will appear by the name of the device currently using + the port (it might not appear against any). The + string "none" means that there are no device drivers + using that port. + +``base-addr`` Parallel port's base address, or addresses if the port + has more than one in which case they are separated + with tabs. These values might not have any sensible + meaning for some ports. + +``irq`` Parallel port's IRQ, or -1 if none is being used. + +``dma`` Parallel port's DMA channel, or -1 if none is being + used. + +``modes`` Parallel port's hardware modes, comma-separated, + meaning: + + - PCSPP + PC-style SPP registers are available. + + - TRISTATE + Port is bidirectional. + + - COMPAT + Hardware acceleration for printers is + available and will be used. + + - EPP + Hardware acceleration for EPP protocol + is available and will be used. + + - ECP + Hardware acceleration for ECP protocol + is available and will be used. + + - DMA + DMA is available and will be used. + + Note that the current implementation will only take + advantage of COMPAT and ECP modes if it has an IRQ + line to use. + +``autoprobe`` Any IEEE-1284 device ID information that has been + acquired from the (non-IEEE 1284.3) device. + +``autoprobe[0-3]`` IEEE 1284 device ID information retrieved from + daisy-chain devices that conform to IEEE 1284.3. + +``spintime`` The number of microseconds to busy-loop while waiting + for the peripheral to respond. You might find that + adjusting this improves performance, depending on your + peripherals. This is a port-wide setting, i.e. it + applies to all devices on a particular port. + +``timeslice`` The number of milliseconds that a device driver is + allowed to keep a port claimed for. This is advisory, + and driver can ignore it if it must. + +``default/*`` The defaults for spintime and timeslice. When a new + port is registered, it picks up the default spintime. + When a new device is registered, it picks up the + default timeslice. +======================= ======================================================= + +Device drivers +============== + +Once the parport code is initialised, you can attach device drivers to +specific ports. Normally this happens automatically; if the lp driver +is loaded it will create one lp device for each port found. You can +override this, though, by using parameters either when you load the lp +driver:: + + # insmod lp parport=0,2 + +or on the LILO command line:: + + lp=parport0 lp=parport2 + +Both the above examples would inform lp that you want ``/dev/lp0`` to be +the first parallel port, and /dev/lp1 to be the **third** parallel port, +with no lp device associated with the second port (parport1). Note +that this is different to the way older kernels worked; there used to +be a static association between the I/O port address and the device +name, so ``/dev/lp0`` was always the port at 0x3bc. This is no longer the +case - if you only have one port, it will default to being ``/dev/lp0``, +regardless of base address. + +Also: + + * If you selected the IEEE 1284 support at compile time, you can say + ``lp=auto`` on the kernel command line, and lp will create devices + only for those ports that seem to have printers attached. + + * If you give PLIP the ``timid`` parameter, either with ``plip=timid`` on + the command line, or with ``insmod plip timid=1`` when using modules, + it will avoid any ports that seem to be in use by other devices. + + * IRQ autoprobing works only for a few port types at the moment. + +Reporting printer problems with parport +======================================= + +If you are having problems printing, please go through these steps to +try to narrow down where the problem area is. + +When reporting problems with parport, really you need to give all of +the messages that ``parport_pc`` spits out when it initialises. There are +several code paths: + +- polling +- interrupt-driven, protocol in software +- interrupt-driven, protocol in hardware using PIO +- interrupt-driven, protocol in hardware using DMA + +The kernel messages that ``parport_pc`` logs give an indication of which +code path is being used. (They could be a lot better actually..) + +For normal printer protocol, having IEEE 1284 modes enabled or not +should not make a difference. + +To turn off the 'protocol in hardware' code paths, disable +``CONFIG_PARPORT_PC_FIFO``. Note that when they are enabled they are not +necessarily **used**; it depends on whether the hardware is available, +enabled by the BIOS, and detected by the driver. + +So, to start with, disable ``CONFIG_PARPORT_PC_FIFO``, and load ``parport_pc`` +with ``irq=none``. See if printing works then. It really should, +because this is the simplest code path. + +If that works fine, try with ``io=0x378 irq=7`` (adjust for your +hardware), to make it use interrupt-driven in-software protocol. + +If **that** works fine, then one of the hardware modes isn't working +right. Enable ``CONFIG_FIFO`` (no, it isn't a module option, +and yes, it should be), set the port to ECP mode in the BIOS and note +the DMA channel, and try with:: + + io=0x378 irq=7 dma=none (for PIO) + io=0x378 irq=7 dma=3 (for DMA) + +---------- + +philb@gnu.org +tim@cyberelk.net diff --git a/Documentation/admin-guide/ramoops.rst b/Documentation/admin-guide/ramoops.rst new file mode 100644 index 000000000000..7eaf1e71c083 --- /dev/null +++ b/Documentation/admin-guide/ramoops.rst @@ -0,0 +1,154 @@ +Ramoops oops/panic logger +========================= + +Sergiu Iordache + +Updated: 17 November 2011 + +Introduction +------------ + +Ramoops is an oops/panic logger that writes its logs to RAM before the system +crashes. It works by logging oopses and panics in a circular buffer. Ramoops +needs a system with persistent RAM so that the content of that area can +survive after a restart. + +Ramoops concepts +---------------- + +Ramoops uses a predefined memory area to store the dump. The start and size +and type of the memory area are set using three variables: + + * ``mem_address`` for the start + * ``mem_size`` for the size. The memory size will be rounded down to a + power of two. + * ``mem_type`` to specifiy if the memory type (default is pgprot_writecombine). + +Typically the default value of ``mem_type=0`` should be used as that sets the pstore +mapping to pgprot_writecombine. Setting ``mem_type=1`` attempts to use +``pgprot_noncached``, which only works on some platforms. This is because pstore +depends on atomic operations. At least on ARM, pgprot_noncached causes the +memory to be mapped strongly ordered, and atomic operations on strongly ordered +memory are implementation defined, and won't work on many ARMs such as omaps. + +The memory area is divided into ``record_size`` chunks (also rounded down to +power of two) and each oops/panic writes a ``record_size`` chunk of +information. + +Dumping both oopses and panics can be done by setting 1 in the ``dump_oops`` +variable while setting 0 in that variable dumps only the panics. + +The module uses a counter to record multiple dumps but the counter gets reset +on restart (i.e. new dumps after the restart will overwrite old ones). + +Ramoops also supports software ECC protection of persistent memory regions. +This might be useful when a hardware reset was used to bring the machine back +to life (i.e. a watchdog triggered). In such cases, RAM may be somewhat +corrupt, but usually it is restorable. + +Setting the parameters +---------------------- + +Setting the ramoops parameters can be done in several different manners: + + A. Use the module parameters (which have the names of the variables described + as before). For quick debugging, you can also reserve parts of memory during + boot and then use the reserved memory for ramoops. For example, assuming a + machine with > 128 MB of memory, the following kernel command line will tell + the kernel to use only the first 128 MB of memory, and place ECC-protected + ramoops region at 128 MB boundary:: + + mem=128M ramoops.mem_address=0x8000000 ramoops.ecc=1 + + B. Use Device Tree bindings, as described in + ``Documentation/device-tree/bindings/reserved-memory/ramoops.txt``. + For example:: + + reserved-memory { + #address-cells = <2>; + #size-cells = <2>; + ranges; + + ramoops@8f000000 { + compatible = "ramoops"; + reg = <0 0x8f000000 0 0x100000>; + record-size = <0x4000>; + console-size = <0x4000>; + }; + }; + + C. Use a platform device and set the platform data. The parameters can then + be set through that platform data. An example of doing that is:: + + #include + [...] + + static struct ramoops_platform_data ramoops_data = { + .mem_size = <...>, + .mem_address = <...>, + .mem_type = <...>, + .record_size = <...>, + .dump_oops = <...>, + .ecc = <...>, + }; + + static struct platform_device ramoops_dev = { + .name = "ramoops", + .dev = { + .platform_data = &ramoops_data, + }, + }; + + [... inside a function ...] + int ret; + + ret = platform_device_register(&ramoops_dev); + if (ret) { + printk(KERN_ERR "unable to register platform device\n"); + return ret; + } + +You can specify either RAM memory or peripheral devices' memory. However, when +specifying RAM, be sure to reserve the memory by issuing memblock_reserve() +very early in the architecture code, e.g.:: + + #include + + memblock_reserve(ramoops_data.mem_address, ramoops_data.mem_size); + +Dump format +----------- + +The data dump begins with a header, currently defined as ``====`` followed by a +timestamp and a new line. The dump then continues with the actual data. + +Reading the data +---------------- + +The dump data can be read from the pstore filesystem. The format for these +files is ``dmesg-ramoops-N``, where N is the record number in memory. To delete +a stored record from RAM, simply unlink the respective pstore file. + +Persistent function tracing +--------------------------- + +Persistent function tracing might be useful for debugging software or hardware +related hangs. The functions call chain log is stored in a ``ftrace-ramoops`` +file. Here is an example of usage:: + + # mount -t debugfs debugfs /sys/kernel/debug/ + # echo 1 > /sys/kernel/debug/pstore/record_ftrace + # reboot -f + [...] + # mount -t pstore pstore /mnt/ + # tail /mnt/ftrace-ramoops + 0 ffffffff8101ea64 ffffffff8101bcda native_apic_mem_read <- disconnect_bsp_APIC+0x6a/0xc0 + 0 ffffffff8101ea44 ffffffff8101bcf6 native_apic_mem_write <- disconnect_bsp_APIC+0x86/0xc0 + 0 ffffffff81020084 ffffffff8101a4b5 hpet_disable <- native_machine_shutdown+0x75/0x90 + 0 ffffffff81005f94 ffffffff8101a4bb iommu_shutdown_noop <- native_machine_shutdown+0x7b/0x90 + 0 ffffffff8101a6a1 ffffffff8101a437 native_machine_emergency_restart <- native_machine_restart+0x37/0x40 + 0 ffffffff811f9876 ffffffff8101a73a acpi_reboot <- native_machine_emergency_restart+0xaa/0x1e0 + 0 ffffffff8101a514 ffffffff8101a772 mach_reboot_fixups <- native_machine_emergency_restart+0xe2/0x1e0 + 0 ffffffff811d9c54 ffffffff8101a7a0 __const_udelay <- native_machine_emergency_restart+0x110/0x1e0 + 0 ffffffff811d9c34 ffffffff811d9c80 __delay <- __const_udelay+0x30/0x40 + 0 ffffffff811d9d14 ffffffff811d9c3f delay_tsc <- __delay+0xf/0x20 diff --git a/Documentation/admin-guide/reporting-bugs.rst b/Documentation/admin-guide/reporting-bugs.rst new file mode 100644 index 000000000000..05c53ac7fa76 --- /dev/null +++ b/Documentation/admin-guide/reporting-bugs.rst @@ -0,0 +1,182 @@ +.. _reportingbugs: + +Reporting bugs +++++++++++++++ + +Background +========== + +The upstream Linux kernel maintainers only fix bugs for specific kernel +versions. Those versions include the current "release candidate" (or -rc) +kernel, any "stable" kernel versions, and any "long term" kernels. + +Please see https://www.kernel.org/ for a list of supported kernels. Any +kernel marked with [EOL] is "end of life" and will not have any fixes +backported to it. + +If you've found a bug on a kernel version that isn't listed on kernel.org, +contact your Linux distribution or embedded vendor for support. +Alternatively, you can attempt to run one of the supported stable or -rc +kernels, and see if you can reproduce the bug on that. It's preferable +to reproduce the bug on the latest -rc kernel. + + +How to report Linux kernel bugs +=============================== + + +Identify the problematic subsystem +---------------------------------- + +Identifying which part of the Linux kernel might be causing your issue +increases your chances of getting your bug fixed. Simply posting to the +generic linux-kernel mailing list (LKML) may cause your bug report to be +lost in the noise of a mailing list that gets 1000+ emails a day. + +Instead, try to figure out which kernel subsystem is causing the issue, +and email that subsystem's maintainer and mailing list. If the subsystem +maintainer doesn't answer, then expand your scope to mailing lists like +LKML. + + +Identify who to notify +---------------------- + +Once you know the subsystem that is causing the issue, you should send a +bug report. Some maintainers prefer bugs to be reported via bugzilla +(https://bugzilla.kernel.org), while others prefer that bugs be reported +via the subsystem mailing list. + +To find out where to send an emailed bug report, find your subsystem or +device driver in the MAINTAINERS file. Search in the file for relevant +entries, and send your bug report to the person(s) listed in the "M:" +lines, making sure to Cc the mailing list(s) in the "L:" lines. When the +maintainer replies to you, make sure to 'Reply-all' in order to keep the +public mailing list(s) in the email thread. + +If you know which driver is causing issues, you can pass one of the driver +files to the get_maintainer.pl script:: + + perl scripts/get_maintainer.pl -f + +If it is a security bug, please copy the Security Contact listed in the +MAINTAINERS file. They can help coordinate bugfix and disclosure. See +:ref:`Documentation/SecurityBugs ` for more information. + +If you can't figure out which subsystem caused the issue, you should file +a bug in kernel.org bugzilla and send email to +linux-kernel@vger.kernel.org, referencing the bugzilla URL. (For more +information on the linux-kernel mailing list see +http://www.tux.org/lkml/). + + +Tips for reporting bugs +----------------------- + +If you haven't reported a bug before, please read: + + http://www.chiark.greenend.org.uk/~sgtatham/bugs.html + + http://www.catb.org/esr/faqs/smart-questions.html + +It's REALLY important to report bugs that seem unrelated as separate email +threads or separate bugzilla entries. If you report several unrelated +bugs at once, it's difficult for maintainers to tease apart the relevant +data. + + +Gather information +------------------ + +The most important information in a bug report is how to reproduce the +bug. This includes system information, and (most importantly) +step-by-step instructions for how a user can trigger the bug. + +If the failure includes an "OOPS:", take a picture of the screen, capture +a netconsole trace, or type the message from your screen into the bug +report. Please read "Documentation/oops-tracing.txt" before posting your +bug report. This explains what you should do with the "Oops" information +to make it useful to the recipient. + +This is a suggested format for a bug report sent via email or bugzilla. +Having a standardized bug report form makes it easier for you not to +overlook things, and easier for the developers to find the pieces of +information they're really interested in. If some information is not +relevant to your bug, feel free to exclude it. + +First run the ver_linux script included as scripts/ver_linux, which +reports the version of some important subsystems. Run this script with +the command ``sh scripts/ver_linux``. + +Use that information to fill in all fields of the bug report form, and +post it to the mailing list with a subject of "PROBLEM: " for easy identification by the developers:: + + [1.] One line summary of the problem: + [2.] Full description of the problem/report: + [3.] Keywords (i.e., modules, networking, kernel): + [4.] Kernel information + [4.1.] Kernel version (from /proc/version): + [4.2.] Kernel .config file: + [5.] Most recent kernel version which did not have the bug: + [6.] Output of Oops.. message (if applicable) with symbolic information + resolved (see Documentation/oops-tracing.txt) + [7.] A small shell script or example program which triggers the + problem (if possible) + [8.] Environment + [8.1.] Software (add the output of the ver_linux script here) + [8.2.] Processor information (from /proc/cpuinfo): + [8.3.] Module information (from /proc/modules): + [8.4.] Loaded driver and hardware information (/proc/ioports, /proc/iomem) + [8.5.] PCI information ('lspci -vvv' as root) + [8.6.] SCSI information (from /proc/scsi/scsi) + [8.7.] Other information that might be relevant to the problem + (please look in /proc and include all information that you + think to be relevant): + [X.] Other notes, patches, fixes, workarounds: + + +Follow up +========= + +Expectations for bug reporters +------------------------------ + +Linux kernel maintainers expect bug reporters to be able to follow up on +bug reports. That may include running new tests, applying patches, +recompiling your kernel, and/or re-triggering your bug. The most +frustrating thing for maintainers is for someone to report a bug, and then +never follow up on a request to try out a fix. + +That said, it's still useful for a kernel maintainer to know a bug exists +on a supported kernel, even if you can't follow up with retests. Follow +up reports, such as replying to the email thread with "I tried the latest +kernel and I can't reproduce my bug anymore" are also helpful, because +maintainers have to assume silence means things are still broken. + +Expectations for kernel maintainers +----------------------------------- + +Linux kernel maintainers are busy, overworked human beings. Some times +they may not be able to address your bug in a day, a week, or two weeks. +If they don't answer your email, they may be on vacation, or at a Linux +conference. Check the conference schedule at https://LWN.net for more info: + + https://lwn.net/Calendar/ + +In general, kernel maintainers take 1 to 5 business days to respond to +bugs. The majority of kernel maintainers are employed to work on the +kernel, and they may not work on the weekends. Maintainers are scattered +around the world, and they may not work in your time zone. Unless you +have a high priority bug, please wait at least a week after the first bug +report before sending the maintainer a reminder email. + +The exceptions to this rule are regressions, kernel crashes, security holes, +or userspace breakage caused by new kernel behavior. Those bugs should be +addressed by the maintainers ASAP. If you suspect a maintainer is not +responding to these types of bugs in a timely manner (especially during a +merge window), escalate the bug to LKML and Linus Torvalds. + +Thank you! + +[Some of this is taken from Frohwalt Egerer's original linux-kernel FAQ] diff --git a/Documentation/admin-guide/security-bugs.rst b/Documentation/admin-guide/security-bugs.rst new file mode 100644 index 000000000000..df795e22d08b --- /dev/null +++ b/Documentation/admin-guide/security-bugs.rst @@ -0,0 +1,46 @@ +.. _securitybugs: + +Security bugs +============= + +Linux kernel developers take security very seriously. As such, we'd +like to know when a security bug is found so that it can be fixed and +disclosed as quickly as possible. Please report security bugs to the +Linux kernel security team. + +Contact +------- + +The Linux kernel security team can be contacted by email at +. This is a private list of security officers +who will help verify the bug report and develop and release a fix. +It is possible that the security team will bring in extra help from +area maintainers to understand and fix the security vulnerability. + +As it is with any bug, the more information provided the easier it +will be to diagnose and fix. Please review the procedure outlined in +REPORTING-BUGS if you are unclear about what information is helpful. +Any exploit code is very helpful and will not be released without +consent from the reporter unless it has already been made public. + +Disclosure +---------- + +The goal of the Linux kernel security team is to work with the +bug submitter to bug resolution as well as disclosure. We prefer +to fully disclose the bug as soon as possible. It is reasonable to +delay disclosure when the bug or the fix is not yet fully understood, +the solution is not well-tested or for vendor coordination. However, we +expect these delays to be short, measurable in days, not weeks or months. +A disclosure date is negotiated by the security team working with the +bug submitter as well as vendors. However, the kernel security team +holds the final say when setting a disclosure date. The timeframe for +disclosure is from immediate (esp. if it's already publicly known) +to a few weeks. As a basic default policy, we expect report date to +disclosure date to be on the order of 7 days. + +Non-disclosure agreements +------------------------- + +The Linux kernel security team is not a formal body and therefore unable +to enter any non-disclosure agreements. diff --git a/Documentation/admin-guide/serial-console.rst b/Documentation/admin-guide/serial-console.rst new file mode 100644 index 000000000000..a8d1e36b627a --- /dev/null +++ b/Documentation/admin-guide/serial-console.rst @@ -0,0 +1,115 @@ +.. _serial_console: + +Linux Serial Console +==================== + +To use a serial port as console you need to compile the support into your +kernel - by default it is not compiled in. For PC style serial ports +it's the config option next to menu option: + +:menuselection:`Character devices --> Serial drivers --> 8250/16550 and compatible serial support --> Console on 8250/16550 and compatible serial port` + +You must compile serial support into the kernel and not as a module. + +It is possible to specify multiple devices for console output. You can +define a new kernel command line option to select which device(s) to +use for console output. + +The format of this option is:: + + console=device,options + + device: tty0 for the foreground virtual console + ttyX for any other virtual console + ttySx for a serial port + lp0 for the first parallel port + ttyUSB0 for the first USB serial device + + options: depend on the driver. For the serial port this + defines the baudrate/parity/bits/flow control of + the port, in the format BBBBPNF, where BBBB is the + speed, P is parity (n/o/e), N is number of bits, + and F is flow control ('r' for RTS). Default is + 9600n8. The maximum baudrate is 115200. + +You can specify multiple console= options on the kernel command line. +Output will appear on all of them. The last device will be used when +you open ``/dev/console``. So, for example:: + + console=ttyS1,9600 console=tty0 + +defines that opening ``/dev/console`` will get you the current foreground +virtual console, and kernel messages will appear on both the VGA +console and the 2nd serial port (ttyS1 or COM2) at 9600 baud. + +Note that you can only define one console per device type (serial, video). + +If no console device is specified, the first device found capable of +acting as a system console will be used. At this time, the system +first looks for a VGA card and then for a serial port. So if you don't +have a VGA card in your system the first serial port will automatically +become the console. + +You will need to create a new device to use ``/dev/console``. The official +``/dev/console`` is now character device 5,1. + +(You can also use a network device as a console. See +``Documentation/networking/netconsole.txt`` for information on that.) + +Here's an example that will use ``/dev/ttyS1`` (COM2) as the console. +Replace the sample values as needed. + +1. Create ``/dev/console`` (real console) and ``/dev/tty0`` (master virtual + console):: + + cd /dev + rm -f console tty0 + mknod -m 622 console c 5 1 + mknod -m 622 tty0 c 4 0 + +2. LILO can also take input from a serial device. This is a very + useful option. To tell LILO to use the serial port: + In lilo.conf (global section):: + + serial = 1,9600n8 (ttyS1, 9600 bd, no parity, 8 bits) + +3. Adjust to kernel flags for the new kernel, + again in lilo.conf (kernel section):: + + append = "console=ttyS1,9600" + +4. Make sure a getty runs on the serial port so that you can login to + it once the system is done booting. This is done by adding a line + like this to ``/etc/inittab`` (exact syntax depends on your getty):: + + S1:23:respawn:/sbin/getty -L ttyS1 9600 vt100 + +5. Init and ``/etc/ioctl.save`` + + Sysvinit remembers its stty settings in a file in ``/etc``, called + ``/etc/ioctl.save``. REMOVE THIS FILE before using the serial + console for the first time, because otherwise init will probably + set the baudrate to 38400 (baudrate of the virtual console). + +6. ``/dev/console`` and X + Programs that want to do something with the virtual console usually + open ``/dev/console``. If you have created the new ``/dev/console`` device, + and your console is NOT the virtual console some programs will fail. + Those are programs that want to access the VT interface, and use + ``/dev/console instead of /dev/tty0``. Some of those programs are:: + + Xfree86, svgalib, gpm, SVGATextMode + + It should be fixed in modern versions of these programs though. + + Note that if you boot without a ``console=`` option (or with + ``console=/dev/tty0``), ``/dev/console`` is the same as ``/dev/tty0``. + In that case everything will still work. + +7. Thanks + + Thanks to Geert Uytterhoeven + for porting the patches from 2.1.4x to 2.1.6x for taking care of + the integration of these patches into m68k, ppc and alpha. + +Miquel van Smoorenburg , 11-Jun-2000 diff --git a/Documentation/admin-guide/sysfs-rules.rst b/Documentation/admin-guide/sysfs-rules.rst new file mode 100644 index 000000000000..04bdd52cba1d --- /dev/null +++ b/Documentation/admin-guide/sysfs-rules.rst @@ -0,0 +1,192 @@ +Rules on how to access information in the Linux kernel sysfs +============================================================ + +The kernel-exported sysfs exports internal kernel implementation details +and depends on internal kernel structures and layout. It is agreed upon +by the kernel developers that the Linux kernel does not provide a stable +internal API. Therefore, there are aspects of the sysfs interface that +may not be stable across kernel releases. + +To minimize the risk of breaking users of sysfs, which are in most cases +low-level userspace applications, with a new kernel release, the users +of sysfs must follow some rules to use an as-abstract-as-possible way to +access this filesystem. The current udev and HAL programs already +implement this and users are encouraged to plug, if possible, into the +abstractions these programs provide instead of accessing sysfs directly. + +But if you really do want or need to access sysfs directly, please follow +the following rules and then your programs should work with future +versions of the sysfs interface. + +- Do not use libsysfs + It makes assumptions about sysfs which are not true. Its API does not + offer any abstraction, it exposes all the kernel driver-core + implementation details in its own API. Therefore it is not better than + reading directories and opening the files yourself. + Also, it is not actively maintained, in the sense of reflecting the + current kernel development. The goal of providing a stable interface + to sysfs has failed; it causes more problems than it solves. It + violates many of the rules in this document. + +- sysfs is always at ``/sys`` + Parsing ``/proc/mounts`` is a waste of time. Other mount points are a + system configuration bug you should not try to solve. For test cases, + possibly support a ``SYSFS_PATH`` environment variable to overwrite the + application's behavior, but never try to search for sysfs. Never try + to mount it, if you are not an early boot script. + +- devices are only "devices" + There is no such thing like class-, bus-, physical devices, + interfaces, and such that you can rely on in userspace. Everything is + just simply a "device". Class-, bus-, physical, ... types are just + kernel implementation details which should not be expected by + applications that look for devices in sysfs. + + The properties of a device are: + + - devpath (``/devices/pci0000:00/0000:00:1d.1/usb2/2-2/2-2:1.0``) + + - identical to the DEVPATH value in the event sent from the kernel + at device creation and removal + - the unique key to the device at that point in time + - the kernel's path to the device directory without the leading + ``/sys``, and always starting with a slash + - all elements of a devpath must be real directories. Symlinks + pointing to /sys/devices must always be resolved to their real + target and the target path must be used to access the device. + That way the devpath to the device matches the devpath of the + kernel used at event time. + - using or exposing symlink values as elements in a devpath string + is a bug in the application + + - kernel name (``sda``, ``tty``, ``0000:00:1f.2``, ...) + + - a directory name, identical to the last element of the devpath + - applications need to handle spaces and characters like ``!`` in + the name + + - subsystem (``block``, ``tty``, ``pci``, ...) + + - simple string, never a path or a link + - retrieved by reading the "subsystem"-link and using only the + last element of the target path + + - driver (``tg3``, ``ata_piix``, ``uhci_hcd``) + + - a simple string, which may contain spaces, never a path or a + link + - it is retrieved by reading the "driver"-link and using only the + last element of the target path + - devices which do not have "driver"-link just do not have a + driver; copying the driver value in a child device context is a + bug in the application + + - attributes + + - the files in the device directory or files below subdirectories + of the same device directory + - accessing attributes reached by a symlink pointing to another device, + like the "device"-link, is a bug in the application + + Everything else is just a kernel driver-core implementation detail + that should not be assumed to be stable across kernel releases. + +- Properties of parent devices never belong into a child device. + Always look at the parent devices themselves for determining device + context properties. If the device ``eth0`` or ``sda`` does not have a + "driver"-link, then this device does not have a driver. Its value is empty. + Never copy any property of the parent-device into a child-device. Parent + device properties may change dynamically without any notice to the + child device. + +- Hierarchy in a single device tree + There is only one valid place in sysfs where hierarchy can be examined + and this is below: ``/sys/devices.`` + It is planned that all device directories will end up in the tree + below this directory. + +- Classification by subsystem + There are currently three places for classification of devices: + ``/sys/block,`` ``/sys/class`` and ``/sys/bus.`` It is planned that these will + not contain any device directories themselves, but only flat lists of + symlinks pointing to the unified ``/sys/devices`` tree. + All three places have completely different rules on how to access + device information. It is planned to merge all three + classification directories into one place at ``/sys/subsystem``, + following the layout of the bus directories. All buses and + classes, including the converted block subsystem, will show up + there. + The devices belonging to a subsystem will create a symlink in the + "devices" directory at ``/sys/subsystem//devices``, + + If ``/sys/subsystem`` exists, ``/sys/bus``, ``/sys/class`` and ``/sys/block`` + can be ignored. If it does not exist, you always have to scan all three + places, as the kernel is free to move a subsystem from one place to + the other, as long as the devices are still reachable by the same + subsystem name. + + Assuming ``/sys/class/`` and ``/sys/bus/``, or + ``/sys/block`` and ``/sys/class/block`` are not interchangeable is a bug in + the application. + +- Block + The converted block subsystem at ``/sys/class/block`` or + ``/sys/subsystem/block`` will contain the links for disks and partitions + at the same level, never in a hierarchy. Assuming the block subsystem to + contain only disks and not partition devices in the same flat list is + a bug in the application. + +- "device"-link and :-links + Never depend on the "device"-link. The "device"-link is a workaround + for the old layout, where class devices are not created in + ``/sys/devices/`` like the bus devices. If the link-resolving of a + device directory does not end in ``/sys/devices/``, you can use the + "device"-link to find the parent devices in ``/sys/devices/``, That is the + single valid use of the "device"-link; it must never appear in any + path as an element. Assuming the existence of the "device"-link for + a device in ``/sys/devices/`` is a bug in the application. + Accessing ``/sys/class/net/eth0/device`` is a bug in the application. + + Never depend on the class-specific links back to the ``/sys/class`` + directory. These links are also a workaround for the design mistake + that class devices are not created in ``/sys/devices.`` If a device + directory does not contain directories for child devices, these links + may be used to find the child devices in ``/sys/class.`` That is the single + valid use of these links; they must never appear in any path as an + element. Assuming the existence of these links for devices which are + real child device directories in the ``/sys/devices`` tree is a bug in + the application. + + It is planned to remove all these links when all class device + directories live in ``/sys/devices.`` + +- Position of devices along device chain can change. + Never depend on a specific parent device position in the devpath, + or the chain of parent devices. The kernel is free to insert devices into + the chain. You must always request the parent device you are looking for + by its subsystem value. You need to walk up the chain until you find + the device that matches the expected subsystem. Depending on a specific + position of a parent device or exposing relative paths using ``../`` to + access the chain of parents is a bug in the application. + +- When reading and writing sysfs device attribute files, avoid dependency + on specific error codes wherever possible. This minimizes coupling to + the error handling implementation within the kernel. + + In general, failures to read or write sysfs device attributes shall + propagate errors wherever possible. Common errors include, but are not + limited to: + + ``-EIO``: The read or store operation is not supported, typically + returned by the sysfs system itself if the read or store pointer + is ``NULL``. + + ``-ENXIO``: The read or store operation failed + + Error codes will not be changed without good reason, and should a change + to error codes result in user-space breakage, it will be fixed, or the + the offending change will be reverted. + + Userspace applications can, however, expect the format and contents of + the attribute files to remain consistent in the absence of a version + attribute change in the context of a given attribute. diff --git a/Documentation/admin-guide/sysrq.rst b/Documentation/admin-guide/sysrq.rst new file mode 100644 index 000000000000..d1712ea2d314 --- /dev/null +++ b/Documentation/admin-guide/sysrq.rst @@ -0,0 +1,289 @@ +Linux Magic System Request Key Hacks +==================================== + +Documentation for sysrq.c + +What is the magic SysRq key? +~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +It is a 'magical' key combo you can hit which the kernel will respond to +regardless of whatever else it is doing, unless it is completely locked up. + +How do I enable the magic SysRq key? +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +You need to say "yes" to 'Magic SysRq key (CONFIG_MAGIC_SYSRQ)' when +configuring the kernel. When running a kernel with SysRq compiled in, +/proc/sys/kernel/sysrq controls the functions allowed to be invoked via +the SysRq key. The default value in this file is set by the +CONFIG_MAGIC_SYSRQ_DEFAULT_ENABLE config symbol, which itself defaults +to 1. Here is the list of possible values in /proc/sys/kernel/sysrq: + + - 0 - disable sysrq completely + - 1 - enable all functions of sysrq + - >1 - bitmask of allowed sysrq functions (see below for detailed function + description):: + + 2 = 0x2 - enable control of console logging level + 4 = 0x4 - enable control of keyboard (SAK, unraw) + 8 = 0x8 - enable debugging dumps of processes etc. + 16 = 0x10 - enable sync command + 32 = 0x20 - enable remount read-only + 64 = 0x40 - enable signalling of processes (term, kill, oom-kill) + 128 = 0x80 - allow reboot/poweroff + 256 = 0x100 - allow nicing of all RT tasks + +You can set the value in the file by the following command:: + + echo "number" >/proc/sys/kernel/sysrq + +The number may be written here either as decimal or as hexadecimal +with the 0x prefix. CONFIG_MAGIC_SYSRQ_DEFAULT_ENABLE must always be +written in hexadecimal. + +Note that the value of ``/proc/sys/kernel/sysrq`` influences only the invocation +via a keyboard. Invocation of any operation via ``/proc/sysrq-trigger`` is +always allowed (by a user with admin privileges). + +How do I use the magic SysRq key? +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +On x86 - You press the key combo :kbd:`ALT-SysRq-`. + +.. note:: + Some + keyboards may not have a key labeled 'SysRq'. The 'SysRq' key is + also known as the 'Print Screen' key. Also some keyboards cannot + handle so many keys being pressed at the same time, so you might + have better luck with press :kbd:`Alt`, press :kbd:`SysRq`, + release :kbd:`SysRq`, press :kbd:``, release everything. + +On SPARC - You press :kbd:`ALT-STOP-`, I believe. + +On the serial console (PC style standard serial ports only) + You send a ``BREAK``, then within 5 seconds a command key. Sending + ``BREAK`` twice is interpreted as a normal BREAK. + +On PowerPC + Press :kbd:`ALT - Print Screen` (or :kbd:`F13`) - :kbd:``, + :kbd:`Print Screen` (or :kbd:`F13`) - :kbd:`` may suffice. + +On other + If you know of the key combos for other architectures, please + let me know so I can add them to this section. + +On all + write a character to /proc/sysrq-trigger. e.g.:: + + echo t > /proc/sysrq-trigger + +What are the 'command' keys? +~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +=========== =================================================================== +Command Function +=========== =================================================================== +``b`` Will immediately reboot the system without syncing or unmounting + your disks. + +``c`` Will perform a system crash by a NULL pointer dereference. + A crashdump will be taken if configured. + +``d`` Shows all locks that are held. + +``e`` Send a SIGTERM to all processes, except for init. + +``f`` Will call the oom killer to kill a memory hog process, but do not + panic if nothing can be killed. + +``g`` Used by kgdb (kernel debugger) + +``h`` Will display help (actually any other key than those listed + here will display help. but ``h`` is easy to remember :-) + +``i`` Send a SIGKILL to all processes, except for init. + +``j`` Forcibly "Just thaw it" - filesystems frozen by the FIFREEZE ioctl. + +``k`` Secure Access Key (SAK) Kills all programs on the current virtual + console. NOTE: See important comments below in SAK section. + +``l`` Shows a stack backtrace for all active CPUs. + +``m`` Will dump current memory info to your console. + +``n`` Used to make RT tasks nice-able + +``o`` Will shut your system off (if configured and supported). + +``p`` Will dump the current registers and flags to your console. + +``q`` Will dump per CPU lists of all armed hrtimers (but NOT regular + timer_list timers) and detailed information about all + clockevent devices. + +``r`` Turns off keyboard raw mode and sets it to XLATE. + +``s`` Will attempt to sync all mounted filesystems. + +``t`` Will dump a list of current tasks and their information to your + console. + +``u`` Will attempt to remount all mounted filesystems read-only. + +``v`` Forcefully restores framebuffer console +``v`` Causes ETM buffer dump [ARM-specific] + +``w`` Dumps tasks that are in uninterruptable (blocked) state. + +``x`` Used by xmon interface on ppc/powerpc platforms. + Show global PMU Registers on sparc64. + Dump all TLB entries on MIPS. + +``y`` Show global CPU Registers [SPARC-64 specific] + +``z`` Dump the ftrace buffer + +``0``-``9`` Sets the console log level, controlling which kernel messages + will be printed to your console. (``0``, for example would make + it so that only emergency messages like PANICs or OOPSes would + make it to your console.) +=========== =================================================================== + +Okay, so what can I use them for? +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Well, unraw(r) is very handy when your X server or a svgalib program crashes. + +sak(k) (Secure Access Key) is useful when you want to be sure there is no +trojan program running at console which could grab your password +when you would try to login. It will kill all programs on given console, +thus letting you make sure that the login prompt you see is actually +the one from init, not some trojan program. + +.. important:: + + In its true form it is not a true SAK like the one in a + c2 compliant system, and it should not be mistaken as + such. + +It seems others find it useful as (System Attention Key) which is +useful when you want to exit a program that will not let you switch consoles. +(For example, X or a svgalib program.) + +``reboot(b)`` is good when you're unable to shut down. But you should also +``sync(s)`` and ``umount(u)`` first. + +``crash(c)`` can be used to manually trigger a crashdump when the system is hung. +Note that this just triggers a crash if there is no dump mechanism available. + +``sync(s)`` is great when your system is locked up, it allows you to sync your +disks and will certainly lessen the chance of data loss and fscking. Note +that the sync hasn't taken place until you see the "OK" and "Done" appear +on the screen. (If the kernel is really in strife, you may not ever get the +OK or Done message...) + +``umount(u)`` is basically useful in the same ways as ``sync(s)``. I generally +``sync(s)``, ``umount(u)``, then ``reboot(b)`` when my system locks. It's saved +me many a fsck. Again, the unmount (remount read-only) hasn't taken place until +you see the "OK" and "Done" message appear on the screen. + +The loglevels ``0``-``9`` are useful when your console is being flooded with +kernel messages you do not want to see. Selecting ``0`` will prevent all but +the most urgent kernel messages from reaching your console. (They will +still be logged if syslogd/klogd are alive, though.) + +``term(e)`` and ``kill(i)`` are useful if you have some sort of runaway process +you are unable to kill any other way, especially if it's spawning other +processes. + +"just thaw ``it(j)``" is useful if your system becomes unresponsive due to a +frozen (probably root) filesystem via the FIFREEZE ioctl. + +Sometimes SysRq seems to get 'stuck' after using it, what can I do? +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +That happens to me, also. I've found that tapping shift, alt, and control +on both sides of the keyboard, and hitting an invalid sysrq sequence again +will fix the problem. (i.e., something like :kbd:`alt-sysrq-z`). Switching to +another virtual console (:kbd:`ALT+Fn`) and then back again should also help. + +I hit SysRq, but nothing seems to happen, what's wrong? +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +There are some keyboards that produce a different keycode for SysRq than the +pre-defined value of 99 (see ``KEY_SYSRQ`` in ``include/linux/input.h``), or +which don't have a SysRq key at all. In these cases, run ``showkey -s`` to find +an appropriate scancode sequence, and use ``setkeycodes 99`` to map +this sequence to the usual SysRq code (e.g., ``setkeycodes e05b 99``). It's +probably best to put this command in a boot script. Oh, and by the way, you +exit ``showkey`` by not typing anything for ten seconds. + +I want to add SysRQ key events to a module, how does it work? +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +In order to register a basic function with the table, you must first include +the header ``include/linux/sysrq.h``, this will define everything else you need. +Next, you must create a ``sysrq_key_op`` struct, and populate it with A) the key +handler function you will use, B) a help_msg string, that will print when SysRQ +prints help, and C) an action_msg string, that will print right before your +handler is called. Your handler must conform to the prototype in 'sysrq.h'. + +After the ``sysrq_key_op`` is created, you can call the kernel function +``register_sysrq_key(int key, struct sysrq_key_op *op_p);`` this will +register the operation pointed to by ``op_p`` at table key 'key', +if that slot in the table is blank. At module unload time, you must call +the function ``unregister_sysrq_key(int key, struct sysrq_key_op *op_p)``, which +will remove the key op pointed to by 'op_p' from the key 'key', if and only if +it is currently registered in that slot. This is in case the slot has been +overwritten since you registered it. + +The Magic SysRQ system works by registering key operations against a key op +lookup table, which is defined in 'drivers/tty/sysrq.c'. This key table has +a number of operations registered into it at compile time, but is mutable, +and 2 functions are exported for interface to it:: + + register_sysrq_key and unregister_sysrq_key. + +Of course, never ever leave an invalid pointer in the table. I.e., when +your module that called register_sysrq_key() exits, it must call +unregister_sysrq_key() to clean up the sysrq key table entry that it used. +Null pointers in the table are always safe. :) + +If for some reason you feel the need to call the handle_sysrq function from +within a function called by handle_sysrq, you must be aware that you are in +a lock (you are also in an interrupt handler, which means don't sleep!), so +you must call ``__handle_sysrq_nolock`` instead. + +When I hit a SysRq key combination only the header appears on the console? +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Sysrq output is subject to the same console loglevel control as all +other console output. This means that if the kernel was booted 'quiet' +as is common on distro kernels the output may not appear on the actual +console, even though it will appear in the dmesg buffer, and be accessible +via the dmesg command and to the consumers of ``/proc/kmsg``. As a specific +exception the header line from the sysrq command is passed to all console +consumers as if the current loglevel was maximum. If only the header +is emitted it is almost certain that the kernel loglevel is too low. +Should you require the output on the console channel then you will need +to temporarily up the console loglevel using :kbd:`alt-sysrq-8` or:: + + echo 8 > /proc/sysrq-trigger + +Remember to return the loglevel to normal after triggering the sysrq +command you are interested in. + +I have more questions, who can I ask? +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Just ask them on the linux-kernel mailing list: + linux-kernel@vger.kernel.org + +Credits +~~~~~~~ + +Written by Mydraal +Updated by Adam Sulmicki +Updated by Jeremy M. Dolan 2001/01/28 10:15:59 +Added to by Crutcher Dunnavant diff --git a/Documentation/admin-guide/unicode.rst b/Documentation/admin-guide/unicode.rst new file mode 100644 index 000000000000..012e8e895842 --- /dev/null +++ b/Documentation/admin-guide/unicode.rst @@ -0,0 +1,189 @@ +Unicode support +=============== + + Last update: 2005-01-17, version 1.4 + +This file is maintained by H. Peter Anvin as part +of the Linux Assigned Names And Numbers Authority (LANANA) project. +The current version can be found at: + + http://www.lanana.org/docs/unicode/unicode.txt + +Introdution +----------- + +The Linux kernel code has been rewritten to use Unicode to map +characters to fonts. By downloading a single Unicode-to-font table, +both the eight-bit character sets and UTF-8 mode are changed to use +the font as indicated. + +This changes the semantics of the eight-bit character tables subtly. +The four character tables are now: + +=============== =============================== ================ +Map symbol Map name Escape code (G0) +=============== =============================== ================ +LAT1_MAP Latin-1 (ISO 8859-1) ESC ( B +GRAF_MAP DEC VT100 pseudographics ESC ( 0 +IBMPC_MAP IBM code page 437 ESC ( U +USER_MAP User defined ESC ( K +=============== =============================== ================ + +In particular, ESC ( U is no longer "straight to font", since the font +might be completely different than the IBM character set. This +permits for example the use of block graphics even with a Latin-1 font +loaded. + +Note that although these codes are similar to ISO 2022, neither the +codes nor their uses match ISO 2022; Linux has two 8-bit codes (G0 and +G1), whereas ISO 2022 has four 7-bit codes (G0-G3). + +In accordance with the Unicode standard/ISO 10646 the range U+F000 to +U+F8FF has been reserved for OS-wide allocation (the Unicode Standard +refers to this as a "Corporate Zone", since this is inaccurate for +Linux we call it the "Linux Zone"). U+F000 was picked as the starting +point since it lets the direct-mapping area start on a large power of +two (in case 1024- or 2048-character fonts ever become necessary). +This leaves U+E000 to U+EFFF as End User Zone. + +[v1.2]: The Unicodes range from U+F000 and up to U+F7FF have been +hard-coded to map directly to the loaded font, bypassing the +translation table. The user-defined map now defaults to U+F000 to +U+F0FF, emulating the previous behaviour. In practice, this range +might be shorter; for example, vgacon can only handle 256-character +(U+F000..U+F0FF) or 512-character (U+F000..U+F1FF) fonts. + + +Actual characters assigned in the Linux Zone +-------------------------------------------- + +In addition, the following characters not present in Unicode 1.1.4 +have been defined; these are used by the DEC VT graphics map. [v1.2] +THIS USE IS OBSOLETE AND SHOULD NO LONGER BE USED; PLEASE SEE BELOW. + +====== ====================================== +U+F800 DEC VT GRAPHICS HORIZONTAL LINE SCAN 1 +U+F801 DEC VT GRAPHICS HORIZONTAL LINE SCAN 3 +U+F803 DEC VT GRAPHICS HORIZONTAL LINE SCAN 7 +U+F804 DEC VT GRAPHICS HORIZONTAL LINE SCAN 9 +====== ====================================== + +The DEC VT220 uses a 6x10 character matrix, and these characters form +a smooth progression in the DEC VT graphics character set. I have +omitted the scan 5 line, since it is also used as a block-graphics +character, and hence has been coded as U+2500 FORMS LIGHT HORIZONTAL. + +[v1.3]: These characters have been officially added to Unicode 3.2.0; +they are added at U+23BA, U+23BB, U+23BC, U+23BD. Linux now uses the +new values. + +[v1.2]: The following characters have been added to represent common +keyboard symbols that are unlikely to ever be added to Unicode proper +since they are horribly vendor-specific. This, of course, is an +excellent example of horrible design. + +====== ====================================== +U+F810 KEYBOARD SYMBOL FLYING FLAG +U+F811 KEYBOARD SYMBOL PULLDOWN MENU +U+F812 KEYBOARD SYMBOL OPEN APPLE +U+F813 KEYBOARD SYMBOL SOLID APPLE +====== ====================================== + +Klingon language support +------------------------ + +In 1996, Linux was the first operating system in the world to add +support for the artificial language Klingon, created by Marc Okrand +for the "Star Trek" television series. This encoding was later +adopted by the ConScript Unicode Registry and proposed (but ultimately +rejected) for inclusion in Unicode Plane 1. Thus, it remains as a +Linux/CSUR private assignment in the Linux Zone. + +This encoding has been endorsed by the Klingon Language Institute. +For more information, contact them at: + + http://www.kli.org/ + +Since the characters in the beginning of the Linux CZ have been more +of the dingbats/symbols/forms type and this is a language, I have +located it at the end, on a 16-cell boundary in keeping with standard +Unicode practice. + +.. note:: + + This range is now officially managed by the ConScript Unicode + Registry. The normative reference is at: + + http://www.evertype.com/standards/csur/klingon.html + +Klingon has an alphabet of 26 characters, a positional numeric writing +system with 10 digits, and is written left-to-right, top-to-bottom. + +Several glyph forms for the Klingon alphabet have been proposed. +However, since the set of symbols appear to be consistent throughout, +with only the actual shapes being different, in keeping with standard +Unicode practice these differences are considered font variants. + +====== ======================================================= +U+F8D0 KLINGON LETTER A +U+F8D1 KLINGON LETTER B +U+F8D2 KLINGON LETTER CH +U+F8D3 KLINGON LETTER D +U+F8D4 KLINGON LETTER E +U+F8D5 KLINGON LETTER GH +U+F8D6 KLINGON LETTER H +U+F8D7 KLINGON LETTER I +U+F8D8 KLINGON LETTER J +U+F8D9 KLINGON LETTER L +U+F8DA KLINGON LETTER M +U+F8DB KLINGON LETTER N +U+F8DC KLINGON LETTER NG +U+F8DD KLINGON LETTER O +U+F8DE KLINGON LETTER P +U+F8DF KLINGON LETTER Q + - Written in standard Okrand Latin transliteration +U+F8E0 KLINGON LETTER QH + - Written in standard Okrand Latin transliteration +U+F8E1 KLINGON LETTER R +U+F8E2 KLINGON LETTER S +U+F8E3 KLINGON LETTER T +U+F8E4 KLINGON LETTER TLH +U+F8E5 KLINGON LETTER U +U+F8E6 KLINGON LETTER V +U+F8E7 KLINGON LETTER W +U+F8E8 KLINGON LETTER Y +U+F8E9 KLINGON LETTER GLOTTAL STOP + +U+F8F0 KLINGON DIGIT ZERO +U+F8F1 KLINGON DIGIT ONE +U+F8F2 KLINGON DIGIT TWO +U+F8F3 KLINGON DIGIT THREE +U+F8F4 KLINGON DIGIT FOUR +U+F8F5 KLINGON DIGIT FIVE +U+F8F6 KLINGON DIGIT SIX +U+F8F7 KLINGON DIGIT SEVEN +U+F8F8 KLINGON DIGIT EIGHT +U+F8F9 KLINGON DIGIT NINE + +U+F8FD KLINGON COMMA +U+F8FE KLINGON FULL STOP +U+F8FF KLINGON SYMBOL FOR EMPIRE +====== ======================================================= + +Other Fictional and Artificial Scripts +-------------------------------------- + +Since the assignment of the Klingon Linux Unicode block, a registry of +fictional and artificial scripts has been established by John Cowan + and Michael Everson . +The ConScript Unicode Registry is accessible at: + + http://www.evertype.com/standards/csur/ + +The ranges used fall at the low end of the End User Zone and can hence +not be normatively assigned, but it is recommended that people who +wish to encode fictional scripts use these codes, in the interest of +interoperability. For Klingon, CSUR has adopted the Linux encoding. +The CSUR people are driving adding Tengwar and Cirth into Unicode +Plane 1; the addition of Klingon to Unicode Plane 1 has been rejected +and so the above encoding remains official. diff --git a/Documentation/admin-guide/vga-softcursor.rst b/Documentation/admin-guide/vga-softcursor.rst new file mode 100644 index 000000000000..9eac6744b3a1 --- /dev/null +++ b/Documentation/admin-guide/vga-softcursor.rst @@ -0,0 +1,66 @@ +Software cursor for VGA +======================= + +by Pavel Machek +and Martin Mares + +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 [#f1]_. You can now play a few new tricks: +you can make your cursor look + +like a non-blinking red block, make it inverse background of the character it's +over or to highlight that character and still choose whether the original +hardware cursor should remain visible or not. There may be other things I have +never thought of. + +The cursor appearance is controlled by a ``[?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. + +first Parameter + 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. + +second parameter + selects character attribute bits you want to change + (by simply XORing them with the value of this parameter). On standard + VGA, the high four bits specify background and the low four the + foreground. In both groups, low three bits set color (as in normal + color codes used by the console) and the most significant one turns + on highlight (or sometimes blinking -- it depends on the configuration + of your VGA). + +third parameter + consists of character attribute bits you want to set. + + Bit setting takes place before bit toggling, so you can simply clear a + bit by including it in both the set mask and the toggle mask. + +.. [#f1] see ``#define TRIDENT_GLITCH`` in ``drivers/video/vgacon.c``. + +Examples: +========= + +To get normal blinking underline, use:: + + echo -e '\033[?2c' + +To get blinking block, use:: + + echo -e '\033[?6c' + +To get red non-blinking block, use:: + + echo -e '\033[?17;0;64c' diff --git a/Documentation/bad_memory.txt b/Documentation/bad_memory.txt deleted file mode 100644 index 5cac93e27a97..000000000000 --- a/Documentation/bad_memory.txt +++ /dev/null @@ -1,51 +0,0 @@ -How to deal with bad memory e.g. reported by memtest86+ ? -========================================================= - -March 2008 -Jan-Simon Moeller, dl9pf@gmx.de - - - -There are three possibilities I know of: - -1) Reinsert/swap the memory modules - -2) Buy new modules (best!) or try to exchange the memory - if you have spare-parts - -3) Use BadRAM or memmap - -This Howto is about number 3) . - - -BadRAM -###### - -BadRAM is the actively developed and available as kernel-patch -here: http://rick.vanrein.org/linux/badram/ - -For more details see the BadRAM documentation. - -memmap -###### - -memmap is already in the kernel and usable as kernel-parameter at -boot-time. Its syntax is slightly strange and you may need to -calculate the values by yourself! - -Syntax to exclude a memory area (see kernel-parameters.txt for details):: - - memmap=$
- -Example: memtest86+ reported here errors at address 0x18691458, 0x18698424 and -some others. All had 0x1869xxxx in common, so I chose a pattern of -0x18690000,0xffff0000. - -With the numbers of the example above:: - - memmap=64K$0x18690000 - -or:: - - memmap=0x10000$0x18690000 - diff --git a/Documentation/basic_profiling.txt b/Documentation/basic_profiling.txt deleted file mode 100644 index 15a49dbd0189..000000000000 --- a/Documentation/basic_profiling.txt +++ /dev/null @@ -1,69 +0,0 @@ -Basic kernel profiling -====================== - - -These instructions are deliberately very basic. If you want something clever, -go read the real docs ;-) - -Please don't add more stuff, but feel free to -correct my mistakes ;-) (mbligh@aracnet.com) - -Thanks to John Levon, Dave Hansen, et al. for help writing this. - -```` is the thing you're trying to measure. -Make sure you have the correct ``System.map`` / ``vmlinux`` referenced! - -It is probably easiest to use ``make install`` for linux and hack -``/sbin/installkernel`` to copy ``vmlinux`` to ``/boot``, in addition to -``vmlinuz``, ``config``, ``System.map``, which are usually installed by default. - -Readprofile ------------ - -A recent ``readprofile`` command is needed for 2.6, such as found in util-linux -2.12a, which can be downloaded from: - - http://www.kernel.org/pub/linux/utils/util-linux/ - -Most distributions will ship it already. - -Add ``profile=2`` to the kernel command line. - -Some ``readprofile`` commands:: - - clear readprofile -r - - dump output readprofile -m /boot/System.map > captured_profile - -Oprofile --------- - -Get the source (see Changes for required version) from -http://oprofile.sourceforge.net/ and add ``idle=poll`` to the kernel command -line. - -Configure with ``CONFIG_PROFILING=y`` and ``CONFIG_OPROFILE=y`` & reboot on new kernel:: - - ./configure --with-kernel-support - make install - -For superior results, be sure to enable the local APIC. If opreport sees -a 0Hz CPU, APIC was not on. Be aware that idle=poll may mean a performance -penalty. - -One time setup:: - - opcontrol --setup --vmlinux=/boot/vmlinux - -Some ``opcontrol`` commands:: - - clear opcontrol --reset - start opcontrol --start - - stop opcontrol --stop - dump output opreport > output_file - -To only report on the kernel, run ``opreport -l /boot/vmlinux > output_file`` - -A reset is needed to clear old statistics, which survive a reboot. - diff --git a/Documentation/binfmt_misc.txt b/Documentation/binfmt_misc.txt deleted file mode 100644 index 9c5ff8f260bf..000000000000 --- a/Documentation/binfmt_misc.txt +++ /dev/null @@ -1,151 +0,0 @@ -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/java.txt - - -You can enable/disable binfmt_misc or one binary type by echoing 0 (to disable) -or 1 (to enable) to ``/proc/sys/fs/binfmt_misc/status`` or -``/proc/.../the_name``. -Catting the file tells you the current status of ``binfmt_misc/the_entry``. - -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/java.txt for an -example. - -Your interpreter should NOT look in the PATH for the filename; the kernel -passes it the full filename (or the file descriptor) to use. Using ``$PATH`` can -cause unexpected behaviour and can be a security hazard. - - -Richard Günther diff --git a/Documentation/braille-console.txt b/Documentation/braille-console.txt deleted file mode 100644 index fa3702dc04ab..000000000000 --- a/Documentation/braille-console.txt +++ /dev/null @@ -1,38 +0,0 @@ -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/serial-console.txt `), 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/serial-console.txt `. - -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/serial-console.txt `. - -For now, only the VisioBraille device is supported. - -Samuel Thibault diff --git a/Documentation/conf.py b/Documentation/conf.py index b08e0c9b73b7..d9bad21dd427 100644 --- a/Documentation/conf.py +++ b/Documentation/conf.py @@ -336,6 +336,8 @@ latex_elements = { # (source start file, target name, title, # author, documentclass [howto, manual, or own class]). latex_documents = [ + ('user/index', 'linux-user.tex', 'Linux Kernel User Documentation', + 'The kernel development community', 'manual'), ('kernel-documentation', 'kernel-documentation.tex', 'The Linux Kernel Documentation', 'The kernel development community', 'manual'), ('process/index', 'development-process.tex', 'Linux Kernel Development Documentation', diff --git a/Documentation/devices.txt b/Documentation/devices.txt deleted file mode 100644 index 17b365331f23..000000000000 --- a/Documentation/devices.txt +++ /dev/null @@ -1,3351 +0,0 @@ - -Linux allocated devices (4.x+ version) -====================================== - -This list is the Linux Device List, the official registry of allocated -device numbers and ``/dev`` directory nodes for the Linux operating -system. - -The LaTeX version of this document is no longer maintained, nor is -the document that used to reside at lanana.org. This version in the -mainline Linux kernel is the master document. Updates shall be sent -as patches to the kernel maintainers (see the -:ref:`Documentation/SubmittingPatches ` document). -Specifically explore the sections titled "CHAR and MISC DRIVERS", and -"BLOCK LAYER" in the MAINTAINERS file to find the right maintainers -to involve for character and block devices. - -This document is included by reference into the Filesystem Hierarchy -Standard (FHS). The FHS is available from http://www.pathname.com/fhs/. - -Allocations marked (68k/Amiga) apply to Linux/68k on the Amiga -platform only. Allocations marked (68k/Atari) apply to Linux/68k on -the Atari platform only. - -This document is in the public domain. The authors requests, however, -that semantically altered versions are not distributed without -permission of the authors, assuming the authors can be contacted without -an unreasonable effort. - - -.. attention:: - - DEVICE DRIVERS AUTHORS PLEASE READ THIS - - Linux now has extensive support for dynamic allocation of device numbering - and can use ``sysfs`` and ``udev`` (``systemd``) to handle the naming needs. - There are still some exceptions in the serial and boot device area. Before - asking for a device number make sure you actually need one. - - To have a major number allocated, or a minor number in situations - where that applies (e.g. busmice), please submit a patch and send to - the authors as indicated above. - - Keep the description of the device *in the same format - as this list*. The reason for this is that it is the only way we have - found to ensure we have all the requisite information to publish your - device and avoid conflicts. - - Finally, sometimes we have to play "namespace police." Please don't be - offended. We often get submissions for ``/dev`` names that would be bound - to cause conflicts down the road. We are trying to avoid getting in a - situation where we would have to suffer an incompatible forward - change. Therefore, please consult with us **before** you make your - device names and numbers in any way public, at least to the point - where it would be at all difficult to get them changed. - - Your cooperation is appreciated. - -:: - - 0 Unnamed devices (e.g. non-device mounts) - 0 = reserved as null device number - See block major 144, 145, 146 for expansion areas. - - 1 char Memory devices - 1 = /dev/mem Physical memory access - 2 = /dev/kmem Kernel virtual memory access - 3 = /dev/null Null device - 4 = /dev/port I/O port access - 5 = /dev/zero Null byte source - 6 = /dev/core OBSOLETE - replaced by /proc/kcore - 7 = /dev/full Returns ENOSPC on write - 8 = /dev/random Nondeterministic random number gen. - 9 = /dev/urandom Faster, less secure random number gen. - 10 = /dev/aio Asynchronous I/O notification interface - 11 = /dev/kmsg Writes to this come out as printk's, reads - export the buffered printk records. - 12 = /dev/oldmem OBSOLETE - replaced by /proc/vmcore - - 1 block RAM disk - 0 = /dev/ram0 First RAM disk - 1 = /dev/ram1 Second RAM disk - ... - 250 = /dev/initrd Initial RAM disk - - Older kernels had /dev/ramdisk (1, 1) here. - /dev/initrd refers to a RAM disk which was preloaded - by the boot loader; newer kernels use /dev/ram0 for - the initrd. - - 2 char Pseudo-TTY masters - 0 = /dev/ptyp0 First PTY master - 1 = /dev/ptyp1 Second PTY master - ... - 255 = /dev/ptyef 256th PTY master - - Pseudo-tty's are named as follows: - * Masters are "pty", slaves are "tty"; - * the fourth letter is one of pqrstuvwxyzabcde indicating - the 1st through 16th series of 16 pseudo-ttys each, and - * the fifth letter is one of 0123456789abcdef indicating - the position within the series. - - These are the old-style (BSD) PTY devices; Unix98 - devices are on major 128 and above and use the PTY - master multiplex (/dev/ptmx) to acquire a PTY on - demand. - - 2 block Floppy disks - 0 = /dev/fd0 Controller 0, drive 0, autodetect - 1 = /dev/fd1 Controller 0, drive 1, autodetect - 2 = /dev/fd2 Controller 0, drive 2, autodetect - 3 = /dev/fd3 Controller 0, drive 3, autodetect - 128 = /dev/fd4 Controller 1, drive 0, autodetect - 129 = /dev/fd5 Controller 1, drive 1, autodetect - 130 = /dev/fd6 Controller 1, drive 2, autodetect - 131 = /dev/fd7 Controller 1, drive 3, autodetect - - To specify format, add to the autodetect device number: - 0 = /dev/fd? Autodetect format - 4 = /dev/fd?d360 5.25" 360K in a 360K drive(1) - 20 = /dev/fd?h360 5.25" 360K in a 1200K drive(1) - 48 = /dev/fd?h410 5.25" 410K in a 1200K drive - 64 = /dev/fd?h420 5.25" 420K in a 1200K drive - 24 = /dev/fd?h720 5.25" 720K in a 1200K drive - 80 = /dev/fd?h880 5.25" 880K in a 1200K drive(1) - 8 = /dev/fd?h1200 5.25" 1200K in a 1200K drive(1) - 40 = /dev/fd?h1440 5.25" 1440K in a 1200K drive(1) - 56 = /dev/fd?h1476 5.25" 1476K in a 1200K drive - 72 = /dev/fd?h1494 5.25" 1494K in a 1200K drive - 92 = /dev/fd?h1600 5.25" 1600K in a 1200K drive(1) - - 12 = /dev/fd?u360 3.5" 360K Double Density(2) - 16 = /dev/fd?u720 3.5" 720K Double Density(1) - 120 = /dev/fd?u800 3.5" 800K Double Density(2) - 52 = /dev/fd?u820 3.5" 820K Double Density - 68 = /dev/fd?u830 3.5" 830K Double Density - 84 = /dev/fd?u1040 3.5" 1040K Double Density(1) - 88 = /dev/fd?u1120 3.5" 1120K Double Density(1) - 28 = /dev/fd?u1440 3.5" 1440K High Density(1) - 124 = /dev/fd?u1600 3.5" 1600K High Density(1) - 44 = /dev/fd?u1680 3.5" 1680K High Density(3) - 60 = /dev/fd?u1722 3.5" 1722K High Density - 76 = /dev/fd?u1743 3.5" 1743K High Density - 96 = /dev/fd?u1760 3.5" 1760K High Density - 116 = /dev/fd?u1840 3.5" 1840K High Density(3) - 100 = /dev/fd?u1920 3.5" 1920K High Density(1) - 32 = /dev/fd?u2880 3.5" 2880K Extra Density(1) - 104 = /dev/fd?u3200 3.5" 3200K Extra Density - 108 = /dev/fd?u3520 3.5" 3520K Extra Density - 112 = /dev/fd?u3840 3.5" 3840K Extra Density(1) - - 36 = /dev/fd?CompaQ Compaq 2880K drive; obsolete? - - (1) Autodetectable format - (2) Autodetectable format in a Double Density (720K) drive only - (3) Autodetectable format in a High Density (1440K) drive only - - NOTE: The letter in the device name (d, q, h or u) - signifies the type of drive: 5.25" Double Density (d), - 5.25" Quad Density (q), 5.25" High Density (h) or 3.5" - (any model, u). The use of the capital letters D, H - and E for the 3.5" models have been deprecated, since - the drive type is insignificant for these devices. - - 3 char Pseudo-TTY slaves - 0 = /dev/ttyp0 First PTY slave - 1 = /dev/ttyp1 Second PTY slave - ... - 255 = /dev/ttyef 256th PTY slave - - These are the old-style (BSD) PTY devices; Unix98 - devices are on major 136 and above. - - 3 block First MFM, RLL and IDE hard disk/CD-ROM interface - 0 = /dev/hda Master: whole disk (or CD-ROM) - 64 = /dev/hdb Slave: whole disk (or CD-ROM) - - For partitions, add to the whole disk device number: - 0 = /dev/hd? Whole disk - 1 = /dev/hd?1 First partition - 2 = /dev/hd?2 Second partition - ... - 63 = /dev/hd?63 63rd partition - - For Linux/i386, partitions 1-4 are the primary - partitions, and 5 and above are logical partitions. - Other versions of Linux use partitioning schemes - appropriate to their respective architectures. - - 4 char TTY devices - 0 = /dev/tty0 Current virtual console - - 1 = /dev/tty1 First virtual console - ... - 63 = /dev/tty63 63rd virtual console - 64 = /dev/ttyS0 First UART serial port - ... - 255 = /dev/ttyS191 192nd UART serial port - - UART serial ports refer to 8250/16450/16550 series devices. - - Older versions of the Linux kernel used this major - number for BSD PTY devices. As of Linux 2.1.115, this - is no longer supported. Use major numbers 2 and 3. - - 4 block Aliases for dynamically allocated major devices to be used - when its not possible to create the real device nodes - because the root filesystem is mounted read-only. - - 0 = /dev/root - - 5 char Alternate TTY devices - 0 = /dev/tty Current TTY device - 1 = /dev/console System console - 2 = /dev/ptmx PTY master multiplex - 3 = /dev/ttyprintk User messages via printk TTY device - 64 = /dev/cua0 Callout device for ttyS0 - ... - 255 = /dev/cua191 Callout device for ttyS191 - - (5,1) is /dev/console starting with Linux 2.1.71. See - the section on terminal devices for more information - on /dev/console. - - 6 char Parallel printer devices - 0 = /dev/lp0 Parallel printer on parport0 - 1 = /dev/lp1 Parallel printer on parport1 - ... - - Current Linux kernels no longer have a fixed mapping - between parallel ports and I/O addresses. Instead, - they are redirected through the parport multiplex layer. - - 7 char Virtual console capture devices - 0 = /dev/vcs Current vc text contents - 1 = /dev/vcs1 tty1 text contents - ... - 63 = /dev/vcs63 tty63 text contents - 128 = /dev/vcsa Current vc text/attribute contents - 129 = /dev/vcsa1 tty1 text/attribute contents - ... - 191 = /dev/vcsa63 tty63 text/attribute contents - - NOTE: These devices permit both read and write access. - - 7 block Loopback devices - 0 = /dev/loop0 First loop device - 1 = /dev/loop1 Second loop device - ... - - The loop devices are used to mount filesystems not - associated with block devices. The binding to the - loop devices is handled by mount(8) or losetup(8). - - 8 block SCSI disk devices (0-15) - 0 = /dev/sda First SCSI disk whole disk - 16 = /dev/sdb Second SCSI disk whole disk - 32 = /dev/sdc Third SCSI disk whole disk - ... - 240 = /dev/sdp Sixteenth SCSI disk whole disk - - Partitions are handled in the same way as for IDE - disks (see major number 3) except that the limit on - partitions is 15. - - 9 char SCSI tape devices - 0 = /dev/st0 First SCSI tape, mode 0 - 1 = /dev/st1 Second SCSI tape, mode 0 - ... - 32 = /dev/st0l First SCSI tape, mode 1 - 33 = /dev/st1l Second SCSI tape, mode 1 - ... - 64 = /dev/st0m First SCSI tape, mode 2 - 65 = /dev/st1m Second SCSI tape, mode 2 - ... - 96 = /dev/st0a First SCSI tape, mode 3 - 97 = /dev/st1a Second SCSI tape, mode 3 - ... - 128 = /dev/nst0 First SCSI tape, mode 0, no rewind - 129 = /dev/nst1 Second SCSI tape, mode 0, no rewind - ... - 160 = /dev/nst0l First SCSI tape, mode 1, no rewind - 161 = /dev/nst1l Second SCSI tape, mode 1, no rewind - ... - 192 = /dev/nst0m First SCSI tape, mode 2, no rewind - 193 = /dev/nst1m Second SCSI tape, mode 2, no rewind - ... - 224 = /dev/nst0a First SCSI tape, mode 3, no rewind - 225 = /dev/nst1a Second SCSI tape, mode 3, no rewind - ... - - "No rewind" refers to the omission of the default - automatic rewind on device close. The MTREW or MTOFFL - ioctl()'s can be used to rewind the tape regardless of - the device used to access it. - - 9 block Metadisk (RAID) devices - 0 = /dev/md0 First metadisk group - 1 = /dev/md1 Second metadisk group - ... - - The metadisk driver is used to span a - filesystem across multiple physical disks. - - 10 char Non-serial mice, misc features - 0 = /dev/logibm Logitech bus mouse - 1 = /dev/psaux PS/2-style mouse port - 2 = /dev/inportbm Microsoft Inport bus mouse - 3 = /dev/atibm ATI XL bus mouse - 4 = /dev/jbm J-mouse - 4 = /dev/amigamouse Amiga mouse (68k/Amiga) - 5 = /dev/atarimouse Atari mouse - 6 = /dev/sunmouse Sun mouse - 7 = /dev/amigamouse1 Second Amiga mouse - 8 = /dev/smouse Simple serial mouse driver - 9 = /dev/pc110pad IBM PC-110 digitizer pad - 10 = /dev/adbmouse Apple Desktop Bus mouse - 11 = /dev/vrtpanel Vr41xx embedded touch panel - 13 = /dev/vpcmouse Connectix Virtual PC Mouse - 14 = /dev/touchscreen/ucb1x00 UCB 1x00 touchscreen - 15 = /dev/touchscreen/mk712 MK712 touchscreen - 128 = /dev/beep Fancy beep device - 129 = - 130 = /dev/watchdog Watchdog timer port - 131 = /dev/temperature Machine internal temperature - 132 = /dev/hwtrap Hardware fault trap - 133 = /dev/exttrp External device trap - 134 = /dev/apm_bios Advanced Power Management BIOS - 135 = /dev/rtc Real Time Clock - 137 = /dev/vhci Bluetooth virtual HCI driver - 139 = /dev/openprom SPARC OpenBoot PROM - 140 = /dev/relay8 Berkshire Products Octal relay card - 141 = /dev/relay16 Berkshire Products ISO-16 relay card - 142 = - 143 = /dev/pciconf PCI configuration space - 144 = /dev/nvram Non-volatile configuration RAM - 145 = /dev/hfmodem Soundcard shortwave modem control - 146 = /dev/graphics Linux/SGI graphics device - 147 = /dev/opengl Linux/SGI OpenGL pipe - 148 = /dev/gfx Linux/SGI graphics effects device - 149 = /dev/input/mouse Linux/SGI Irix emulation mouse - 150 = /dev/input/keyboard Linux/SGI Irix emulation keyboard - 151 = /dev/led Front panel LEDs - 152 = /dev/kpoll Kernel Poll Driver - 153 = /dev/mergemem Memory merge device - 154 = /dev/pmu Macintosh PowerBook power manager - 155 = /dev/isictl MultiTech ISICom serial control - 156 = /dev/lcd Front panel LCD display - 157 = /dev/ac Applicom Intl Profibus card - 158 = /dev/nwbutton Netwinder external button - 159 = /dev/nwdebug Netwinder debug interface - 160 = /dev/nwflash Netwinder flash memory - 161 = /dev/userdma User-space DMA access - 162 = /dev/smbus System Management Bus - 163 = /dev/lik Logitech Internet Keyboard - 164 = /dev/ipmo Intel Intelligent Platform Management - 165 = /dev/vmmon VMware virtual machine monitor - 166 = /dev/i2o/ctl I2O configuration manager - 167 = /dev/specialix_sxctl Specialix serial control - 168 = /dev/tcldrv Technology Concepts serial control - 169 = /dev/specialix_rioctl Specialix RIO serial control - 170 = /dev/thinkpad/thinkpad IBM Thinkpad devices - 171 = /dev/srripc QNX4 API IPC manager - 172 = /dev/usemaclone Semaphore clone device - 173 = /dev/ipmikcs Intelligent Platform Management - 174 = /dev/uctrl SPARCbook 3 microcontroller - 175 = /dev/agpgart AGP Graphics Address Remapping Table - 176 = /dev/gtrsc Gorgy Timing radio clock - 177 = /dev/cbm Serial CBM bus - 178 = /dev/jsflash JavaStation OS flash SIMM - 179 = /dev/xsvc High-speed shared-mem/semaphore service - 180 = /dev/vrbuttons Vr41xx button input device - 181 = /dev/toshiba Toshiba laptop SMM support - 182 = /dev/perfctr Performance-monitoring counters - 183 = /dev/hwrng Generic random number generator - 184 = /dev/cpu/microcode CPU microcode update interface - 186 = /dev/atomicps Atomic shapshot of process state data - 187 = /dev/irnet IrNET device - 188 = /dev/smbusbios SMBus BIOS - 189 = /dev/ussp_ctl User space serial port control - 190 = /dev/crash Mission Critical Linux crash dump facility - 191 = /dev/pcl181 - 192 = /dev/nas_xbus NAS xbus LCD/buttons access - 193 = /dev/d7s SPARC 7-segment display - 194 = /dev/zkshim Zero-Knowledge network shim control - 195 = /dev/elographics/e2201 Elographics touchscreen E271-2201 - 196 = /dev/vfio/vfio VFIO userspace driver interface - 197 = /dev/pxa3xx-gcu PXA3xx graphics controller unit driver - 198 = /dev/sexec Signed executable interface - 199 = /dev/scanners/cuecat :CueCat barcode scanner - 200 = /dev/net/tun TAP/TUN network device - 201 = /dev/button/gulpb Transmeta GULP-B buttons - 202 = /dev/emd/ctl Enhanced Metadisk RAID (EMD) control - 203 = /dev/cuse Cuse (character device in user-space) - 204 = /dev/video/em8300 EM8300 DVD decoder control - 205 = /dev/video/em8300_mv EM8300 DVD decoder video - 206 = /dev/video/em8300_ma EM8300 DVD decoder audio - 207 = /dev/video/em8300_sp EM8300 DVD decoder subpicture - 208 = /dev/compaq/cpqphpc Compaq PCI Hot Plug Controller - 209 = /dev/compaq/cpqrid Compaq Remote Insight Driver - 210 = /dev/impi/bt IMPI coprocessor block transfer - 211 = /dev/impi/smic IMPI coprocessor stream interface - 212 = /dev/watchdogs/0 First watchdog device - 213 = /dev/watchdogs/1 Second watchdog device - 214 = /dev/watchdogs/2 Third watchdog device - 215 = /dev/watchdogs/3 Fourth watchdog device - 216 = /dev/fujitsu/apanel Fujitsu/Siemens application panel - 217 = /dev/ni/natmotn National Instruments Motion - 218 = /dev/kchuid Inter-process chuid control - 219 = /dev/modems/mwave MWave modem firmware upload - 220 = /dev/mptctl Message passing technology (MPT) control - 221 = /dev/mvista/hssdsi Montavista PICMG hot swap system driver - 222 = /dev/mvista/hasi Montavista PICMG high availability - 223 = /dev/input/uinput User level driver support for input - 224 = /dev/tpm TCPA TPM driver - 225 = /dev/pps Pulse Per Second driver - 226 = /dev/systrace Systrace device - 227 = /dev/mcelog X86_64 Machine Check Exception driver - 228 = /dev/hpet HPET driver - 229 = /dev/fuse Fuse (virtual filesystem in user-space) - 230 = /dev/midishare MidiShare driver - 231 = /dev/snapshot System memory snapshot device - 232 = /dev/kvm Kernel-based virtual machine (hardware virtualization extensions) - 233 = /dev/kmview View-OS A process with a view - 234 = /dev/btrfs-control Btrfs control device - 235 = /dev/autofs Autofs control device - 236 = /dev/mapper/control Device-Mapper control device - 237 = /dev/loop-control Loopback control device - 238 = /dev/vhost-net Host kernel accelerator for virtio net - 239 = /dev/uhid User-space I/O driver support for HID subsystem - - 240-254 Reserved for local use - 255 Reserved for MISC_DYNAMIC_MINOR - - 11 char Raw keyboard device (Linux/SPARC only) - 0 = /dev/kbd Raw keyboard device - - 11 char Serial Mux device (Linux/PA-RISC only) - 0 = /dev/ttyB0 First mux port - 1 = /dev/ttyB1 Second mux port - ... - - 11 block SCSI CD-ROM devices - 0 = /dev/scd0 First SCSI CD-ROM - 1 = /dev/scd1 Second SCSI CD-ROM - ... - - The prefix /dev/sr (instead of /dev/scd) has been deprecated. - - 12 char QIC-02 tape - 2 = /dev/ntpqic11 QIC-11, no rewind-on-close - 3 = /dev/tpqic11 QIC-11, rewind-on-close - 4 = /dev/ntpqic24 QIC-24, no rewind-on-close - 5 = /dev/tpqic24 QIC-24, rewind-on-close - 6 = /dev/ntpqic120 QIC-120, no rewind-on-close - 7 = /dev/tpqic120 QIC-120, rewind-on-close - 8 = /dev/ntpqic150 QIC-150, no rewind-on-close - 9 = /dev/tpqic150 QIC-150, rewind-on-close - - The device names specified are proposed -- if there - are "standard" names for these devices, please let me know. - - 12 block - - 13 char Input core - 0 = /dev/input/js0 First joystick - 1 = /dev/input/js1 Second joystick - ... - 32 = /dev/input/mouse0 First mouse - 33 = /dev/input/mouse1 Second mouse - ... - 63 = /dev/input/mice Unified mouse - 64 = /dev/input/event0 First event queue - 65 = /dev/input/event1 Second event queue - ... - - Each device type has 5 bits (32 minors). - - 13 block Previously used for the XT disk (/dev/xdN) - Deleted in kernel v3.9. - - 14 char Open Sound System (OSS) - 0 = /dev/mixer Mixer control - 1 = /dev/sequencer Audio sequencer - 2 = /dev/midi00 First MIDI port - 3 = /dev/dsp Digital audio - 4 = /dev/audio Sun-compatible digital audio - 6 = - 7 = /dev/audioctl SPARC audio control device - 8 = /dev/sequencer2 Sequencer -- alternate device - 16 = /dev/mixer1 Second soundcard mixer control - 17 = /dev/patmgr0 Sequencer patch manager - 18 = /dev/midi01 Second MIDI port - 19 = /dev/dsp1 Second soundcard digital audio - 20 = /dev/audio1 Second soundcard Sun digital audio - 33 = /dev/patmgr1 Sequencer patch manager - 34 = /dev/midi02 Third MIDI port - 50 = /dev/midi03 Fourth MIDI port - - 14 block - - 15 char Joystick - 0 = /dev/js0 First analog joystick - 1 = /dev/js1 Second analog joystick - ... - 128 = /dev/djs0 First digital joystick - 129 = /dev/djs1 Second digital joystick - ... - 15 block Sony CDU-31A/CDU-33A CD-ROM - 0 = /dev/sonycd Sony CDU-31a CD-ROM - - 16 char Non-SCSI scanners - 0 = /dev/gs4500 Genius 4500 handheld scanner - - 16 block GoldStar CD-ROM - 0 = /dev/gscd GoldStar CD-ROM - - 17 char OBSOLETE (was Chase serial card) - 0 = /dev/ttyH0 First Chase port - 1 = /dev/ttyH1 Second Chase port - ... - 17 block Optics Storage CD-ROM - 0 = /dev/optcd Optics Storage CD-ROM - - 18 char OBSOLETE (was Chase serial card - alternate devices) - 0 = /dev/cuh0 Callout device for ttyH0 - 1 = /dev/cuh1 Callout device for ttyH1 - ... - 18 block Sanyo CD-ROM - 0 = /dev/sjcd Sanyo CD-ROM - - 19 char Cyclades serial card - 0 = /dev/ttyC0 First Cyclades port - ... - 31 = /dev/ttyC31 32nd Cyclades port - - 19 block "Double" compressed disk - 0 = /dev/double0 First compressed disk - ... - 7 = /dev/double7 Eighth compressed disk - 128 = /dev/cdouble0 Mirror of first compressed disk - ... - 135 = /dev/cdouble7 Mirror of eighth compressed disk - - See the Double documentation for the meaning of the - mirror devices. - - 20 char Cyclades serial card - alternate devices - 0 = /dev/cub0 Callout device for ttyC0 - ... - 31 = /dev/cub31 Callout device for ttyC31 - - 20 block Hitachi CD-ROM (under development) - 0 = /dev/hitcd Hitachi CD-ROM - - 21 char Generic SCSI access - 0 = /dev/sg0 First generic SCSI device - 1 = /dev/sg1 Second generic SCSI device - ... - - Most distributions name these /dev/sga, /dev/sgb...; - this sets an unnecessary limit of 26 SCSI devices in - the system and is counter to standard Linux - device-naming practice. - - 21 block Acorn MFM hard drive interface - 0 = /dev/mfma First MFM drive whole disk - 64 = /dev/mfmb Second MFM drive whole disk - - This device is used on the ARM-based Acorn RiscPC. - Partitions are handled the same way as for IDE disks - (see major number 3). - - 22 char Digiboard serial card - 0 = /dev/ttyD0 First Digiboard port - 1 = /dev/ttyD1 Second Digiboard port - ... - 22 block Second IDE hard disk/CD-ROM interface - 0 = /dev/hdc Master: whole disk (or CD-ROM) - 64 = /dev/hdd Slave: whole disk (or CD-ROM) - - Partitions are handled the same way as for the first - interface (see major number 3). - - 23 char Digiboard serial card - alternate devices - 0 = /dev/cud0 Callout device for ttyD0 - 1 = /dev/cud1 Callout device for ttyD1 - ... - 23 block Mitsumi proprietary CD-ROM - 0 = /dev/mcd Mitsumi CD-ROM - - 24 char Stallion serial card - 0 = /dev/ttyE0 Stallion port 0 card 0 - 1 = /dev/ttyE1 Stallion port 1 card 0 - ... - 64 = /dev/ttyE64 Stallion port 0 card 1 - 65 = /dev/ttyE65 Stallion port 1 card 1 - ... - 128 = /dev/ttyE128 Stallion port 0 card 2 - 129 = /dev/ttyE129 Stallion port 1 card 2 - ... - 192 = /dev/ttyE192 Stallion port 0 card 3 - 193 = /dev/ttyE193 Stallion port 1 card 3 - ... - 24 block Sony CDU-535 CD-ROM - 0 = /dev/cdu535 Sony CDU-535 CD-ROM - - 25 char Stallion serial card - alternate devices - 0 = /dev/cue0 Callout device for ttyE0 - 1 = /dev/cue1 Callout device for ttyE1 - ... - 64 = /dev/cue64 Callout device for ttyE64 - 65 = /dev/cue65 Callout device for ttyE65 - ... - 128 = /dev/cue128 Callout device for ttyE128 - 129 = /dev/cue129 Callout device for ttyE129 - ... - 192 = /dev/cue192 Callout device for ttyE192 - 193 = /dev/cue193 Callout device for ttyE193 - ... - 25 block First Matsushita (Panasonic/SoundBlaster) CD-ROM - 0 = /dev/sbpcd0 Panasonic CD-ROM controller 0 unit 0 - 1 = /dev/sbpcd1 Panasonic CD-ROM controller 0 unit 1 - 2 = /dev/sbpcd2 Panasonic CD-ROM controller 0 unit 2 - 3 = /dev/sbpcd3 Panasonic CD-ROM controller 0 unit 3 - - 26 char - - 26 block Second Matsushita (Panasonic/SoundBlaster) CD-ROM - 0 = /dev/sbpcd4 Panasonic CD-ROM controller 1 unit 0 - 1 = /dev/sbpcd5 Panasonic CD-ROM controller 1 unit 1 - 2 = /dev/sbpcd6 Panasonic CD-ROM controller 1 unit 2 - 3 = /dev/sbpcd7 Panasonic CD-ROM controller 1 unit 3 - - 27 char QIC-117 tape - 0 = /dev/qft0 Unit 0, rewind-on-close - 1 = /dev/qft1 Unit 1, rewind-on-close - 2 = /dev/qft2 Unit 2, rewind-on-close - 3 = /dev/qft3 Unit 3, rewind-on-close - 4 = /dev/nqft0 Unit 0, no rewind-on-close - 5 = /dev/nqft1 Unit 1, no rewind-on-close - 6 = /dev/nqft2 Unit 2, no rewind-on-close - 7 = /dev/nqft3 Unit 3, no rewind-on-close - 16 = /dev/zqft0 Unit 0, rewind-on-close, compression - 17 = /dev/zqft1 Unit 1, rewind-on-close, compression - 18 = /dev/zqft2 Unit 2, rewind-on-close, compression - 19 = /dev/zqft3 Unit 3, rewind-on-close, compression - 20 = /dev/nzqft0 Unit 0, no rewind-on-close, compression - 21 = /dev/nzqft1 Unit 1, no rewind-on-close, compression - 22 = /dev/nzqft2 Unit 2, no rewind-on-close, compression - 23 = /dev/nzqft3 Unit 3, no rewind-on-close, compression - 32 = /dev/rawqft0 Unit 0, rewind-on-close, no file marks - 33 = /dev/rawqft1 Unit 1, rewind-on-close, no file marks - 34 = /dev/rawqft2 Unit 2, rewind-on-close, no file marks - 35 = /dev/rawqft3 Unit 3, rewind-on-close, no file marks - 36 = /dev/nrawqft0 Unit 0, no rewind-on-close, no file marks - 37 = /dev/nrawqft1 Unit 1, no rewind-on-close, no file marks - 38 = /dev/nrawqft2 Unit 2, no rewind-on-close, no file marks - 39 = /dev/nrawqft3 Unit 3, no rewind-on-close, no file marks - - 27 block Third Matsushita (Panasonic/SoundBlaster) CD-ROM - 0 = /dev/sbpcd8 Panasonic CD-ROM controller 2 unit 0 - 1 = /dev/sbpcd9 Panasonic CD-ROM controller 2 unit 1 - 2 = /dev/sbpcd10 Panasonic CD-ROM controller 2 unit 2 - 3 = /dev/sbpcd11 Panasonic CD-ROM controller 2 unit 3 - - 28 char Stallion serial card - card programming - 0 = /dev/staliomem0 First Stallion card I/O memory - 1 = /dev/staliomem1 Second Stallion card I/O memory - 2 = /dev/staliomem2 Third Stallion card I/O memory - 3 = /dev/staliomem3 Fourth Stallion card I/O memory - - 28 char Atari SLM ACSI laser printer (68k/Atari) - 0 = /dev/slm0 First SLM laser printer - 1 = /dev/slm1 Second SLM laser printer - ... - 28 block Fourth Matsushita (Panasonic/SoundBlaster) CD-ROM - 0 = /dev/sbpcd12 Panasonic CD-ROM controller 3 unit 0 - 1 = /dev/sbpcd13 Panasonic CD-ROM controller 3 unit 1 - 2 = /dev/sbpcd14 Panasonic CD-ROM controller 3 unit 2 - 3 = /dev/sbpcd15 Panasonic CD-ROM controller 3 unit 3 - - 28 block ACSI disk (68k/Atari) - 0 = /dev/ada First ACSI disk whole disk - 16 = /dev/adb Second ACSI disk whole disk - 32 = /dev/adc Third ACSI disk whole disk - ... - 240 = /dev/adp 16th ACSI disk whole disk - - Partitions are handled in the same way as for IDE - disks (see major number 3) except that the limit on - partitions is 15, like SCSI. - - 29 char Universal frame buffer - 0 = /dev/fb0 First frame buffer - 1 = /dev/fb1 Second frame buffer - ... - 31 = /dev/fb31 32nd frame buffer - - 29 block Aztech/Orchid/Okano/Wearnes CD-ROM - 0 = /dev/aztcd Aztech CD-ROM - - 30 char iBCS-2 compatibility devices - 0 = /dev/socksys Socket access - 1 = /dev/spx SVR3 local X interface - 32 = /dev/inet/ip Network access - 33 = /dev/inet/icmp - 34 = /dev/inet/ggp - 35 = /dev/inet/ipip - 36 = /dev/inet/tcp - 37 = /dev/inet/egp - 38 = /dev/inet/pup - 39 = /dev/inet/udp - 40 = /dev/inet/idp - 41 = /dev/inet/rawip - - Additionally, iBCS-2 requires the following links: - - /dev/ip -> /dev/inet/ip - /dev/icmp -> /dev/inet/icmp - /dev/ggp -> /dev/inet/ggp - /dev/ipip -> /dev/inet/ipip - /dev/tcp -> /dev/inet/tcp - /dev/egp -> /dev/inet/egp - /dev/pup -> /dev/inet/pup - /dev/udp -> /dev/inet/udp - /dev/idp -> /dev/inet/idp - /dev/rawip -> /dev/inet/rawip - /dev/inet/arp -> /dev/inet/udp - /dev/inet/rip -> /dev/inet/udp - /dev/nfsd -> /dev/socksys - /dev/X0R -> /dev/null (? apparently not required ?) - - 30 block Philips LMS CM-205 CD-ROM - 0 = /dev/cm205cd Philips LMS CM-205 CD-ROM - - /dev/lmscd is an older name for this device. This - driver does not work with the CM-205MS CD-ROM. - - 31 char MPU-401 MIDI - 0 = /dev/mpu401data MPU-401 data port - 1 = /dev/mpu401stat MPU-401 status port - - 31 block ROM/flash memory card - 0 = /dev/rom0 First ROM card (rw) - ... - 7 = /dev/rom7 Eighth ROM card (rw) - 8 = /dev/rrom0 First ROM card (ro) - ... - 15 = /dev/rrom7 Eighth ROM card (ro) - 16 = /dev/flash0 First flash memory card (rw) - ... - 23 = /dev/flash7 Eighth flash memory card (rw) - 24 = /dev/rflash0 First flash memory card (ro) - ... - 31 = /dev/rflash7 Eighth flash memory card (ro) - - The read-write (rw) devices support back-caching - written data in RAM, as well as writing to flash RAM - devices. The read-only devices (ro) support reading - only. - - 32 char Specialix serial card - 0 = /dev/ttyX0 First Specialix port - 1 = /dev/ttyX1 Second Specialix port - ... - 32 block Philips LMS CM-206 CD-ROM - 0 = /dev/cm206cd Philips LMS CM-206 CD-ROM - - 33 char Specialix serial card - alternate devices - 0 = /dev/cux0 Callout device for ttyX0 - 1 = /dev/cux1 Callout device for ttyX1 - ... - 33 block Third IDE hard disk/CD-ROM interface - 0 = /dev/hde Master: whole disk (or CD-ROM) - 64 = /dev/hdf Slave: whole disk (or CD-ROM) - - Partitions are handled the same way as for the first - interface (see major number 3). - - 34 char Z8530 HDLC driver - 0 = /dev/scc0 First Z8530, first port - 1 = /dev/scc1 First Z8530, second port - 2 = /dev/scc2 Second Z8530, first port - 3 = /dev/scc3 Second Z8530, second port - ... - - In a previous version these devices were named - /dev/sc1 for /dev/scc0, /dev/sc2 for /dev/scc1, and so - on. - - 34 block Fourth IDE hard disk/CD-ROM interface - 0 = /dev/hdg Master: whole disk (or CD-ROM) - 64 = /dev/hdh Slave: whole disk (or CD-ROM) - - Partitions are handled the same way as for the first - interface (see major number 3). - - 35 char tclmidi MIDI driver - 0 = /dev/midi0 First MIDI port, kernel timed - 1 = /dev/midi1 Second MIDI port, kernel timed - 2 = /dev/midi2 Third MIDI port, kernel timed - 3 = /dev/midi3 Fourth MIDI port, kernel timed - 64 = /dev/rmidi0 First MIDI port, untimed - 65 = /dev/rmidi1 Second MIDI port, untimed - 66 = /dev/rmidi2 Third MIDI port, untimed - 67 = /dev/rmidi3 Fourth MIDI port, untimed - 128 = /dev/smpte0 First MIDI port, SMPTE timed - 129 = /dev/smpte1 Second MIDI port, SMPTE timed - 130 = /dev/smpte2 Third MIDI port, SMPTE timed - 131 = /dev/smpte3 Fourth MIDI port, SMPTE timed - - 35 block Slow memory ramdisk - 0 = /dev/slram Slow memory ramdisk - - 36 char Netlink support - 0 = /dev/route Routing, device updates, kernel to user - 1 = /dev/skip enSKIP security cache control - 3 = /dev/fwmonitor Firewall packet copies - 16 = /dev/tap0 First Ethertap device - ... - 31 = /dev/tap15 16th Ethertap device - - 36 block OBSOLETE (was MCA ESDI hard disk) - - 37 char IDE tape - 0 = /dev/ht0 First IDE tape - 1 = /dev/ht1 Second IDE tape - ... - 128 = /dev/nht0 First IDE tape, no rewind-on-close - 129 = /dev/nht1 Second IDE tape, no rewind-on-close - ... - - Currently, only one IDE tape drive is supported. - - 37 block Zorro II ramdisk - 0 = /dev/z2ram Zorro II ramdisk - - 38 char Myricom PCI Myrinet board - 0 = /dev/mlanai0 First Myrinet board - 1 = /dev/mlanai1 Second Myrinet board - ... - - This device is used for status query, board control - and "user level packet I/O." This board is also - accessible as a standard networking "eth" device. - - 38 block OBSOLETE (was Linux/AP+) - - 39 char ML-16P experimental I/O board - 0 = /dev/ml16pa-a0 First card, first analog channel - 1 = /dev/ml16pa-a1 First card, second analog channel - ... - 15 = /dev/ml16pa-a15 First card, 16th analog channel - 16 = /dev/ml16pa-d First card, digital lines - 17 = /dev/ml16pa-c0 First card, first counter/timer - 18 = /dev/ml16pa-c1 First card, second counter/timer - 19 = /dev/ml16pa-c2 First card, third counter/timer - 32 = /dev/ml16pb-a0 Second card, first analog channel - 33 = /dev/ml16pb-a1 Second card, second analog channel - ... - 47 = /dev/ml16pb-a15 Second card, 16th analog channel - 48 = /dev/ml16pb-d Second card, digital lines - 49 = /dev/ml16pb-c0 Second card, first counter/timer - 50 = /dev/ml16pb-c1 Second card, second counter/timer - 51 = /dev/ml16pb-c2 Second card, third counter/timer - ... - 39 block - - 40 char - - 40 block - - 41 char Yet Another Micro Monitor - 0 = /dev/yamm Yet Another Micro Monitor - - 41 block - - 42 char Demo/sample use - - 42 block Demo/sample use - - This number is intended for use in sample code, as - well as a general "example" device number. It - should never be used for a device driver that is being - distributed; either obtain an official number or use - the local/experimental range. The sudden addition or - removal of a driver with this number should not cause - ill effects to the system (bugs excepted.) - - IN PARTICULAR, ANY DISTRIBUTION WHICH CONTAINS A - DEVICE DRIVER USING MAJOR NUMBER 42 IS NONCOMPLIANT. - - 43 char isdn4linux virtual modem - 0 = /dev/ttyI0 First virtual modem - ... - 63 = /dev/ttyI63 64th virtual modem - - 43 block Network block devices - 0 = /dev/nb0 First network block device - 1 = /dev/nb1 Second network block device - ... - - Network Block Device is somehow similar to loopback - devices: If you read from it, it sends packet across - network asking server for data. If you write to it, it - sends packet telling server to write. It could be used - to mounting filesystems over the net, swapping over - the net, implementing block device in userland etc. - - 44 char isdn4linux virtual modem - alternate devices - 0 = /dev/cui0 Callout device for ttyI0 - ... - 63 = /dev/cui63 Callout device for ttyI63 - - 44 block Flash Translation Layer (FTL) filesystems - 0 = /dev/ftla FTL on first Memory Technology Device - 16 = /dev/ftlb FTL on second Memory Technology Device - 32 = /dev/ftlc FTL on third Memory Technology Device - ... - 240 = /dev/ftlp FTL on 16th Memory Technology Device - - Partitions are handled in the same way as for IDE - disks (see major number 3) except that the partition - limit is 15 rather than 63 per disk (same as SCSI.) - - 45 char isdn4linux ISDN BRI driver - 0 = /dev/isdn0 First virtual B channel raw data - ... - 63 = /dev/isdn63 64th virtual B channel raw data - 64 = /dev/isdnctrl0 First channel control/debug - ... - 127 = /dev/isdnctrl63 64th channel control/debug - - 128 = /dev/ippp0 First SyncPPP device - ... - 191 = /dev/ippp63 64th SyncPPP device - - 255 = /dev/isdninfo ISDN monitor interface - - 45 block Parallel port IDE disk devices - 0 = /dev/pda First parallel port IDE disk - 16 = /dev/pdb Second parallel port IDE disk - 32 = /dev/pdc Third parallel port IDE disk - 48 = /dev/pdd Fourth parallel port IDE disk - - Partitions are handled in the same way as for IDE - disks (see major number 3) except that the partition - limit is 15 rather than 63 per disk. - - 46 char Comtrol Rocketport serial card - 0 = /dev/ttyR0 First Rocketport port - 1 = /dev/ttyR1 Second Rocketport port - ... - 46 block Parallel port ATAPI CD-ROM devices - 0 = /dev/pcd0 First parallel port ATAPI CD-ROM - 1 = /dev/pcd1 Second parallel port ATAPI CD-ROM - 2 = /dev/pcd2 Third parallel port ATAPI CD-ROM - 3 = /dev/pcd3 Fourth parallel port ATAPI CD-ROM - - 47 char Comtrol Rocketport serial card - alternate devices - 0 = /dev/cur0 Callout device for ttyR0 - 1 = /dev/cur1 Callout device for ttyR1 - ... - 47 block Parallel port ATAPI disk devices - 0 = /dev/pf0 First parallel port ATAPI disk - 1 = /dev/pf1 Second parallel port ATAPI disk - 2 = /dev/pf2 Third parallel port ATAPI disk - 3 = /dev/pf3 Fourth parallel port ATAPI disk - - This driver is intended for floppy disks and similar - devices and hence does not support partitioning. - - 48 char SDL RISCom serial card - 0 = /dev/ttyL0 First RISCom port - 1 = /dev/ttyL1 Second RISCom port - ... - 48 block Mylex DAC960 PCI RAID controller; first controller - 0 = /dev/rd/c0d0 First disk, whole disk - 8 = /dev/rd/c0d1 Second disk, whole disk - ... - 248 = /dev/rd/c0d31 32nd disk, whole disk - - For partitions add: - 0 = /dev/rd/c?d? Whole disk - 1 = /dev/rd/c?d?p1 First partition - ... - 7 = /dev/rd/c?d?p7 Seventh partition - - 49 char SDL RISCom serial card - alternate devices - 0 = /dev/cul0 Callout device for ttyL0 - 1 = /dev/cul1 Callout device for ttyL1 - ... - 49 block Mylex DAC960 PCI RAID controller; second controller - 0 = /dev/rd/c1d0 First disk, whole disk - 8 = /dev/rd/c1d1 Second disk, whole disk - ... - 248 = /dev/rd/c1d31 32nd disk, whole disk - - Partitions are handled as for major 48. - - 50 char Reserved for GLINT - - 50 block Mylex DAC960 PCI RAID controller; third controller - 0 = /dev/rd/c2d0 First disk, whole disk - 8 = /dev/rd/c2d1 Second disk, whole disk - ... - 248 = /dev/rd/c2d31 32nd disk, whole disk - - 51 char Baycom radio modem OR Radio Tech BIM-XXX-RS232 radio modem - 0 = /dev/bc0 First Baycom radio modem - 1 = /dev/bc1 Second Baycom radio modem - ... - 51 block Mylex DAC960 PCI RAID controller; fourth controller - 0 = /dev/rd/c3d0 First disk, whole disk - 8 = /dev/rd/c3d1 Second disk, whole disk - ... - 248 = /dev/rd/c3d31 32nd disk, whole disk - - Partitions are handled as for major 48. - - 52 char Spellcaster DataComm/BRI ISDN card - 0 = /dev/dcbri0 First DataComm card - 1 = /dev/dcbri1 Second DataComm card - 2 = /dev/dcbri2 Third DataComm card - 3 = /dev/dcbri3 Fourth DataComm card - - 52 block Mylex DAC960 PCI RAID controller; fifth controller - 0 = /dev/rd/c4d0 First disk, whole disk - 8 = /dev/rd/c4d1 Second disk, whole disk - ... - 248 = /dev/rd/c4d31 32nd disk, whole disk - - Partitions are handled as for major 48. - - 53 char BDM interface for remote debugging MC683xx microcontrollers - 0 = /dev/pd_bdm0 PD BDM interface on lp0 - 1 = /dev/pd_bdm1 PD BDM interface on lp1 - 2 = /dev/pd_bdm2 PD BDM interface on lp2 - 4 = /dev/icd_bdm0 ICD BDM interface on lp0 - 5 = /dev/icd_bdm1 ICD BDM interface on lp1 - 6 = /dev/icd_bdm2 ICD BDM interface on lp2 - - This device is used for the interfacing to the MC683xx - microcontrollers via Background Debug Mode by use of a - Parallel Port interface. PD is the Motorola Public - Domain Interface and ICD is the commercial interface - by P&E. - - 53 block Mylex DAC960 PCI RAID controller; sixth controller - 0 = /dev/rd/c5d0 First disk, whole disk - 8 = /dev/rd/c5d1 Second disk, whole disk - ... - 248 = /dev/rd/c5d31 32nd disk, whole disk - - Partitions are handled as for major 48. - - 54 char Electrocardiognosis Holter serial card - 0 = /dev/holter0 First Holter port - 1 = /dev/holter1 Second Holter port - 2 = /dev/holter2 Third Holter port - - A custom serial card used by Electrocardiognosis SRL - to transfer data from Holter - 24-hour heart monitoring equipment. - - 54 block Mylex DAC960 PCI RAID controller; seventh controller - 0 = /dev/rd/c6d0 First disk, whole disk - 8 = /dev/rd/c6d1 Second disk, whole disk - ... - 248 = /dev/rd/c6d31 32nd disk, whole disk - - Partitions are handled as for major 48. - - 55 char DSP56001 digital signal processor - 0 = /dev/dsp56k First DSP56001 - - 55 block Mylex DAC960 PCI RAID controller; eighth controller - 0 = /dev/rd/c7d0 First disk, whole disk - 8 = /dev/rd/c7d1 Second disk, whole disk - ... - 248 = /dev/rd/c7d31 32nd disk, whole disk - - Partitions are handled as for major 48. - - 56 char Apple Desktop Bus - 0 = /dev/adb ADB bus control - - Additional devices will be added to this number, all - starting with /dev/adb. - - 56 block Fifth IDE hard disk/CD-ROM interface - 0 = /dev/hdi Master: whole disk (or CD-ROM) - 64 = /dev/hdj Slave: whole disk (or CD-ROM) - - Partitions are handled the same way as for the first - interface (see major number 3). - - 57 char Hayes ESP serial card - 0 = /dev/ttyP0 First ESP port - 1 = /dev/ttyP1 Second ESP port - ... - - 57 block Sixth IDE hard disk/CD-ROM interface - 0 = /dev/hdk Master: whole disk (or CD-ROM) - 64 = /dev/hdl Slave: whole disk (or CD-ROM) - - Partitions are handled the same way as for the first - interface (see major number 3). - - 58 char Hayes ESP serial card - alternate devices - 0 = /dev/cup0 Callout device for ttyP0 - 1 = /dev/cup1 Callout device for ttyP1 - ... - - 58 block Reserved for logical volume manager - - 59 char sf firewall package - 0 = /dev/firewall Communication with sf kernel module - - 59 block Generic PDA filesystem device - 0 = /dev/pda0 First PDA device - 1 = /dev/pda1 Second PDA device - ... - - The pda devices are used to mount filesystems on - remote pda's (basically slow handheld machines with - proprietary OS's and limited memory and storage - running small fs translation drivers) through serial / - IRDA / parallel links. - - NAMING CONFLICT -- PROPOSED REVISED NAME /dev/rpda0 etc - - 60-63 char LOCAL/EXPERIMENTAL USE - - 60-63 block LOCAL/EXPERIMENTAL USE - Allocated for local/experimental use. For devices not - assigned official numbers, these ranges should be - used in order to avoid conflicting with future assignments. - - 64 char ENskip kernel encryption package - 0 = /dev/enskip Communication with ENskip kernel module - - 64 block Scramdisk/DriveCrypt encrypted devices - 0 = /dev/scramdisk/master Master node for ioctls - 1 = /dev/scramdisk/1 First encrypted device - 2 = /dev/scramdisk/2 Second encrypted device - ... - 255 = /dev/scramdisk/255 255th encrypted device - - The filename of the encrypted container and the passwords - are sent via ioctls (using the sdmount tool) to the master - node which then activates them via one of the - /dev/scramdisk/x nodes for loop mounting (all handled - through the sdmount tool). - - Requested by: andy@scramdisklinux.org - - 65 char Sundance "plink" Transputer boards (obsolete, unused) - 0 = /dev/plink0 First plink device - 1 = /dev/plink1 Second plink device - 2 = /dev/plink2 Third plink device - 3 = /dev/plink3 Fourth plink device - 64 = /dev/rplink0 First plink device, raw - 65 = /dev/rplink1 Second plink device, raw - 66 = /dev/rplink2 Third plink device, raw - 67 = /dev/rplink3 Fourth plink device, raw - 128 = /dev/plink0d First plink device, debug - 129 = /dev/plink1d Second plink device, debug - 130 = /dev/plink2d Third plink device, debug - 131 = /dev/plink3d Fourth plink device, debug - 192 = /dev/rplink0d First plink device, raw, debug - 193 = /dev/rplink1d Second plink device, raw, debug - 194 = /dev/rplink2d Third plink device, raw, debug - 195 = /dev/rplink3d Fourth plink device, raw, debug - - This is a commercial driver; contact James Howes - for information. - - 65 block SCSI disk devices (16-31) - 0 = /dev/sdq 17th SCSI disk whole disk - 16 = /dev/sdr 18th SCSI disk whole disk - 32 = /dev/sds 19th SCSI disk whole disk - ... - 240 = /dev/sdaf 32nd SCSI disk whole disk - - Partitions are handled in the same way as for IDE - disks (see major number 3) except that the limit on - partitions is 15. - - 66 char YARC PowerPC PCI coprocessor card - 0 = /dev/yppcpci0 First YARC card - 1 = /dev/yppcpci1 Second YARC card - ... - - 66 block SCSI disk devices (32-47) - 0 = /dev/sdag 33th SCSI disk whole disk - 16 = /dev/sdah 34th SCSI disk whole disk - 32 = /dev/sdai 35th SCSI disk whole disk - ... - 240 = /dev/sdav 48nd SCSI disk whole disk - - Partitions are handled in the same way as for IDE - disks (see major number 3) except that the limit on - partitions is 15. - - 67 char Coda network file system - 0 = /dev/cfs0 Coda cache manager - - See http://www.coda.cs.cmu.edu for information about Coda. - - 67 block SCSI disk devices (48-63) - 0 = /dev/sdaw 49th SCSI disk whole disk - 16 = /dev/sdax 50th SCSI disk whole disk - 32 = /dev/sday 51st SCSI disk whole disk - ... - 240 = /dev/sdbl 64th SCSI disk whole disk - - Partitions are handled in the same way as for IDE - disks (see major number 3) except that the limit on - partitions is 15. - - 68 char CAPI 2.0 interface - 0 = /dev/capi20 Control device - 1 = /dev/capi20.00 First CAPI 2.0 application - 2 = /dev/capi20.01 Second CAPI 2.0 application - ... - 20 = /dev/capi20.19 19th CAPI 2.0 application - - ISDN CAPI 2.0 driver for use with CAPI 2.0 - applications; currently supports the AVM B1 card. - - 68 block SCSI disk devices (64-79) - 0 = /dev/sdbm 65th SCSI disk whole disk - 16 = /dev/sdbn 66th SCSI disk whole disk - 32 = /dev/sdbo 67th SCSI disk whole disk - ... - 240 = /dev/sdcb 80th SCSI disk whole disk - - Partitions are handled in the same way as for IDE - disks (see major number 3) except that the limit on - partitions is 15. - - 69 char MA16 numeric accelerator card - 0 = /dev/ma16 Board memory access - - 69 block SCSI disk devices (80-95) - 0 = /dev/sdcc 81st SCSI disk whole disk - 16 = /dev/sdcd 82nd SCSI disk whole disk - 32 = /dev/sdce 83th SCSI disk whole disk - ... - 240 = /dev/sdcr 96th SCSI disk whole disk - - Partitions are handled in the same way as for IDE - disks (see major number 3) except that the limit on - partitions is 15. - - 70 char SpellCaster Protocol Services Interface - 0 = /dev/apscfg Configuration interface - 1 = /dev/apsauth Authentication interface - 2 = /dev/apslog Logging interface - 3 = /dev/apsdbg Debugging interface - 64 = /dev/apsisdn ISDN command interface - 65 = /dev/apsasync Async command interface - 128 = /dev/apsmon Monitor interface - - 70 block SCSI disk devices (96-111) - 0 = /dev/sdcs 97th SCSI disk whole disk - 16 = /dev/sdct 98th SCSI disk whole disk - 32 = /dev/sdcu 99th SCSI disk whole disk - ... - 240 = /dev/sddh 112nd SCSI disk whole disk - - Partitions are handled in the same way as for IDE - disks (see major number 3) except that the limit on - partitions is 15. - - 71 char Computone IntelliPort II serial card - 0 = /dev/ttyF0 IntelliPort II board 0, port 0 - 1 = /dev/ttyF1 IntelliPort II board 0, port 1 - ... - 63 = /dev/ttyF63 IntelliPort II board 0, port 63 - 64 = /dev/ttyF64 IntelliPort II board 1, port 0 - 65 = /dev/ttyF65 IntelliPort II board 1, port 1 - ... - 127 = /dev/ttyF127 IntelliPort II board 1, port 63 - 128 = /dev/ttyF128 IntelliPort II board 2, port 0 - 129 = /dev/ttyF129 IntelliPort II board 2, port 1 - ... - 191 = /dev/ttyF191 IntelliPort II board 2, port 63 - 192 = /dev/ttyF192 IntelliPort II board 3, port 0 - 193 = /dev/ttyF193 IntelliPort II board 3, port 1 - ... - 255 = /dev/ttyF255 IntelliPort II board 3, port 63 - - 71 block SCSI disk devices (112-127) - 0 = /dev/sddi 113th SCSI disk whole disk - 16 = /dev/sddj 114th SCSI disk whole disk - 32 = /dev/sddk 115th SCSI disk whole disk - ... - 240 = /dev/sddx 128th SCSI disk whole disk - - Partitions are handled in the same way as for IDE - disks (see major number 3) except that the limit on - partitions is 15. - - 72 char Computone IntelliPort II serial card - alternate devices - 0 = /dev/cuf0 Callout device for ttyF0 - 1 = /dev/cuf1 Callout device for ttyF1 - ... - 63 = /dev/cuf63 Callout device for ttyF63 - 64 = /dev/cuf64 Callout device for ttyF64 - 65 = /dev/cuf65 Callout device for ttyF65 - ... - 127 = /dev/cuf127 Callout device for ttyF127 - 128 = /dev/cuf128 Callout device for ttyF128 - 129 = /dev/cuf129 Callout device for ttyF129 - ... - 191 = /dev/cuf191 Callout device for ttyF191 - 192 = /dev/cuf192 Callout device for ttyF192 - 193 = /dev/cuf193 Callout device for ttyF193 - ... - 255 = /dev/cuf255 Callout device for ttyF255 - - 72 block Compaq Intelligent Drive Array, first controller - 0 = /dev/ida/c0d0 First logical drive whole disk - 16 = /dev/ida/c0d1 Second logical drive whole disk - ... - 240 = /dev/ida/c0d15 16th logical drive whole disk - - Partitions are handled the same way as for Mylex - DAC960 (see major number 48) except that the limit on - partitions is 15. - - 73 char Computone IntelliPort II serial card - control devices - 0 = /dev/ip2ipl0 Loadware device for board 0 - 1 = /dev/ip2stat0 Status device for board 0 - 4 = /dev/ip2ipl1 Loadware device for board 1 - 5 = /dev/ip2stat1 Status device for board 1 - 8 = /dev/ip2ipl2 Loadware device for board 2 - 9 = /dev/ip2stat2 Status device for board 2 - 12 = /dev/ip2ipl3 Loadware device for board 3 - 13 = /dev/ip2stat3 Status device for board 3 - - 73 block Compaq Intelligent Drive Array, second controller - 0 = /dev/ida/c1d0 First logical drive whole disk - 16 = /dev/ida/c1d1 Second logical drive whole disk - ... - 240 = /dev/ida/c1d15 16th logical drive whole disk - - Partitions are handled the same way as for Mylex - DAC960 (see major number 48) except that the limit on - partitions is 15. - - 74 char SCI bridge - 0 = /dev/SCI/0 SCI device 0 - 1 = /dev/SCI/1 SCI device 1 - ... - - Currently for Dolphin Interconnect Solutions' PCI-SCI - bridge. - - 74 block Compaq Intelligent Drive Array, third controller - 0 = /dev/ida/c2d0 First logical drive whole disk - 16 = /dev/ida/c2d1 Second logical drive whole disk - ... - 240 = /dev/ida/c2d15 16th logical drive whole disk - - Partitions are handled the same way as for Mylex - DAC960 (see major number 48) except that the limit on - partitions is 15. - - 75 char Specialix IO8+ serial card - 0 = /dev/ttyW0 First IO8+ port, first card - 1 = /dev/ttyW1 Second IO8+ port, first card - ... - 8 = /dev/ttyW8 First IO8+ port, second card - ... - - 75 block Compaq Intelligent Drive Array, fourth controller - 0 = /dev/ida/c3d0 First logical drive whole disk - 16 = /dev/ida/c3d1 Second logical drive whole disk - ... - 240 = /dev/ida/c3d15 16th logical drive whole disk - - Partitions are handled the same way as for Mylex - DAC960 (see major number 48) except that the limit on - partitions is 15. - - 76 char Specialix IO8+ serial card - alternate devices - 0 = /dev/cuw0 Callout device for ttyW0 - 1 = /dev/cuw1 Callout device for ttyW1 - ... - 8 = /dev/cuw8 Callout device for ttyW8 - ... - - 76 block Compaq Intelligent Drive Array, fifth controller - 0 = /dev/ida/c4d0 First logical drive whole disk - 16 = /dev/ida/c4d1 Second logical drive whole disk - ... - 240 = /dev/ida/c4d15 16th logical drive whole disk - - Partitions are handled the same way as for Mylex - DAC960 (see major number 48) except that the limit on - partitions is 15. - - - 77 char ComScire Quantum Noise Generator - 0 = /dev/qng ComScire Quantum Noise Generator - - 77 block Compaq Intelligent Drive Array, sixth controller - 0 = /dev/ida/c5d0 First logical drive whole disk - 16 = /dev/ida/c5d1 Second logical drive whole disk - ... - 240 = /dev/ida/c5d15 16th logical drive whole disk - - Partitions are handled the same way as for Mylex - DAC960 (see major number 48) except that the limit on - partitions is 15. - - 78 char PAM Software's multimodem boards - 0 = /dev/ttyM0 First PAM modem - 1 = /dev/ttyM1 Second PAM modem - ... - - 78 block Compaq Intelligent Drive Array, seventh controller - 0 = /dev/ida/c6d0 First logical drive whole disk - 16 = /dev/ida/c6d1 Second logical drive whole disk - ... - 240 = /dev/ida/c6d15 16th logical drive whole disk - - Partitions are handled the same way as for Mylex - DAC960 (see major number 48) except that the limit on - partitions is 15. - - 79 char PAM Software's multimodem boards - alternate devices - 0 = /dev/cum0 Callout device for ttyM0 - 1 = /dev/cum1 Callout device for ttyM1 - ... - - 79 block Compaq Intelligent Drive Array, eighth controller - 0 = /dev/ida/c7d0 First logical drive whole disk - 16 = /dev/ida/c7d1 Second logical drive whole disk - ... - 240 = /dev/ida/c715 16th logical drive whole disk - - Partitions are handled the same way as for Mylex - DAC960 (see major number 48) except that the limit on - partitions is 15. - - 80 char Photometrics AT200 CCD camera - 0 = /dev/at200 Photometrics AT200 CCD camera - - 80 block I2O hard disk - 0 = /dev/i2o/hda First I2O hard disk, whole disk - 16 = /dev/i2o/hdb Second I2O hard disk, whole disk - ... - 240 = /dev/i2o/hdp 16th I2O hard disk, whole disk - - Partitions are handled in the same way as for IDE - disks (see major number 3) except that the limit on - partitions is 15. - - 81 char video4linux - 0 = /dev/video0 Video capture/overlay device - ... - 63 = /dev/video63 Video capture/overlay device - 64 = /dev/radio0 Radio device - ... - 127 = /dev/radio63 Radio device - 128 = /dev/swradio0 Software Defined Radio device - ... - 191 = /dev/swradio63 Software Defined Radio device - 224 = /dev/vbi0 Vertical blank interrupt - ... - 255 = /dev/vbi31 Vertical blank interrupt - - Minor numbers are allocated dynamically unless - CONFIG_VIDEO_FIXED_MINOR_RANGES (default n) - configuration option is set. - - 81 block I2O hard disk - 0 = /dev/i2o/hdq 17th I2O hard disk, whole disk - 16 = /dev/i2o/hdr 18th I2O hard disk, whole disk - ... - 240 = /dev/i2o/hdaf 32nd I2O hard disk, whole disk - - Partitions are handled in the same way as for IDE - disks (see major number 3) except that the limit on - partitions is 15. - - 82 char WiNRADiO communications receiver card - 0 = /dev/winradio0 First WiNRADiO card - 1 = /dev/winradio1 Second WiNRADiO card - ... - - The driver and documentation may be obtained from - http://www.winradio.com/ - - 82 block I2O hard disk - 0 = /dev/i2o/hdag 33rd I2O hard disk, whole disk - 16 = /dev/i2o/hdah 34th I2O hard disk, whole disk - ... - 240 = /dev/i2o/hdav 48th I2O hard disk, whole disk - - Partitions are handled in the same way as for IDE - disks (see major number 3) except that the limit on - partitions is 15. - - 83 char Matrox mga_vid video driver - 0 = /dev/mga_vid0 1st video card - 1 = /dev/mga_vid1 2nd video card - 2 = /dev/mga_vid2 3rd video card - ... - 15 = /dev/mga_vid15 16th video card - - 83 block I2O hard disk - 0 = /dev/i2o/hdaw 49th I2O hard disk, whole disk - 16 = /dev/i2o/hdax 50th I2O hard disk, whole disk - ... - 240 = /dev/i2o/hdbl 64th I2O hard disk, whole disk - - Partitions are handled in the same way as for IDE - disks (see major number 3) except that the limit on - partitions is 15. - - 84 char Ikon 1011[57] Versatec Greensheet Interface - 0 = /dev/ihcp0 First Greensheet port - 1 = /dev/ihcp1 Second Greensheet port - - 84 block I2O hard disk - 0 = /dev/i2o/hdbm 65th I2O hard disk, whole disk - 16 = /dev/i2o/hdbn 66th I2O hard disk, whole disk - ... - 240 = /dev/i2o/hdcb 80th I2O hard disk, whole disk - - Partitions are handled in the same way as for IDE - disks (see major number 3) except that the limit on - partitions is 15. - - 85 char Linux/SGI shared memory input queue - 0 = /dev/shmiq Master shared input queue - 1 = /dev/qcntl0 First device pushed - 2 = /dev/qcntl1 Second device pushed - ... - - 85 block I2O hard disk - 0 = /dev/i2o/hdcc 81st I2O hard disk, whole disk - 16 = /dev/i2o/hdcd 82nd I2O hard disk, whole disk - ... - 240 = /dev/i2o/hdcr 96th I2O hard disk, whole disk - - Partitions are handled in the same way as for IDE - disks (see major number 3) except that the limit on - partitions is 15. - - 86 char SCSI media changer - 0 = /dev/sch0 First SCSI media changer - 1 = /dev/sch1 Second SCSI media changer - ... - - 86 block I2O hard disk - 0 = /dev/i2o/hdcs 97th I2O hard disk, whole disk - 16 = /dev/i2o/hdct 98th I2O hard disk, whole disk - ... - 240 = /dev/i2o/hddh 112th I2O hard disk, whole disk - - Partitions are handled in the same way as for IDE - disks (see major number 3) except that the limit on - partitions is 15. - - 87 char Sony Control-A1 stereo control bus - 0 = /dev/controla0 First device on chain - 1 = /dev/controla1 Second device on chain - ... - - 87 block I2O hard disk - 0 = /dev/i2o/hddi 113rd I2O hard disk, whole disk - 16 = /dev/i2o/hddj 114th I2O hard disk, whole disk - ... - 240 = /dev/i2o/hddx 128th I2O hard disk, whole disk - - Partitions are handled in the same way as for IDE - disks (see major number 3) except that the limit on - partitions is 15. - - 88 char COMX synchronous serial card - 0 = /dev/comx0 COMX channel 0 - 1 = /dev/comx1 COMX channel 1 - ... - - 88 block Seventh IDE hard disk/CD-ROM interface - 0 = /dev/hdm Master: whole disk (or CD-ROM) - 64 = /dev/hdn Slave: whole disk (or CD-ROM) - - Partitions are handled the same way as for the first - interface (see major number 3). - - 89 char I2C bus interface - 0 = /dev/i2c-0 First I2C adapter - 1 = /dev/i2c-1 Second I2C adapter - ... - - 89 block Eighth IDE hard disk/CD-ROM interface - 0 = /dev/hdo Master: whole disk (or CD-ROM) - 64 = /dev/hdp Slave: whole disk (or CD-ROM) - - Partitions are handled the same way as for the first - interface (see major number 3). - - 90 char Memory Technology Device (RAM, ROM, Flash) - 0 = /dev/mtd0 First MTD (rw) - 1 = /dev/mtdr0 First MTD (ro) - ... - 30 = /dev/mtd15 16th MTD (rw) - 31 = /dev/mtdr15 16th MTD (ro) - - 90 block Ninth IDE hard disk/CD-ROM interface - 0 = /dev/hdq Master: whole disk (or CD-ROM) - 64 = /dev/hdr Slave: whole disk (or CD-ROM) - - Partitions are handled the same way as for the first - interface (see major number 3). - - 91 char CAN-Bus devices - 0 = /dev/can0 First CAN-Bus controller - 1 = /dev/can1 Second CAN-Bus controller - ... - - 91 block Tenth IDE hard disk/CD-ROM interface - 0 = /dev/hds Master: whole disk (or CD-ROM) - 64 = /dev/hdt Slave: whole disk (or CD-ROM) - - Partitions are handled the same way as for the first - interface (see major number 3). - - 92 char Reserved for ith Kommunikationstechnik MIC ISDN card - - 92 block PPDD encrypted disk driver - 0 = /dev/ppdd0 First encrypted disk - 1 = /dev/ppdd1 Second encrypted disk - ... - - Partitions are handled in the same way as for IDE - disks (see major number 3) except that the limit on - partitions is 15. - - 93 char - - 93 block NAND Flash Translation Layer filesystem - 0 = /dev/nftla First NFTL layer - 16 = /dev/nftlb Second NFTL layer - ... - 240 = /dev/nftlp 16th NTFL layer - - 94 char - - 94 block IBM S/390 DASD block storage - 0 = /dev/dasda First DASD device, major - 1 = /dev/dasda1 First DASD device, block 1 - 2 = /dev/dasda2 First DASD device, block 2 - 3 = /dev/dasda3 First DASD device, block 3 - 4 = /dev/dasdb Second DASD device, major - 5 = /dev/dasdb1 Second DASD device, block 1 - 6 = /dev/dasdb2 Second DASD device, block 2 - 7 = /dev/dasdb3 Second DASD device, block 3 - ... - - 95 char IP filter - 0 = /dev/ipl Filter control device/log file - 1 = /dev/ipnat NAT control device/log file - 2 = /dev/ipstate State information log file - 3 = /dev/ipauth Authentication control device/log file - ... - - 96 char Parallel port ATAPI tape devices - 0 = /dev/pt0 First parallel port ATAPI tape - 1 = /dev/pt1 Second parallel port ATAPI tape - ... - 128 = /dev/npt0 First p.p. ATAPI tape, no rewind - 129 = /dev/npt1 Second p.p. ATAPI tape, no rewind - ... - - 96 block Inverse NAND Flash Translation Layer - 0 = /dev/inftla First INFTL layer - 16 = /dev/inftlb Second INFTL layer - ... - 240 = /dev/inftlp 16th INTFL layer - - 97 char Parallel port generic ATAPI interface - 0 = /dev/pg0 First parallel port ATAPI device - 1 = /dev/pg1 Second parallel port ATAPI device - 2 = /dev/pg2 Third parallel port ATAPI device - 3 = /dev/pg3 Fourth parallel port ATAPI device - - These devices support the same API as the generic SCSI - devices. - - 98 char Control and Measurement Device (comedi) - 0 = /dev/comedi0 First comedi device - 1 = /dev/comedi1 Second comedi device - ... - - See http://stm.lbl.gov/comedi. - - 98 block User-mode virtual block device - 0 = /dev/ubda First user-mode block device - 16 = /dev/udbb Second user-mode block device - ... - - Partitions are handled in the same way as for IDE - disks (see major number 3) except that the limit on - partitions is 15. - - This device is used by the user-mode virtual kernel port. - - 99 char Raw parallel ports - 0 = /dev/parport0 First parallel port - 1 = /dev/parport1 Second parallel port - ... - - 99 block JavaStation flash disk - 0 = /dev/jsfd JavaStation flash disk - - 100 char Telephony for Linux - 0 = /dev/phone0 First telephony device - 1 = /dev/phone1 Second telephony device - ... - - 101 char Motorola DSP 56xxx board - 0 = /dev/mdspstat Status information - 1 = /dev/mdsp1 First DSP board I/O controls - ... - 16 = /dev/mdsp16 16th DSP board I/O controls - - 101 block AMI HyperDisk RAID controller - 0 = /dev/amiraid/ar0 First array whole disk - 16 = /dev/amiraid/ar1 Second array whole disk - ... - 240 = /dev/amiraid/ar15 16th array whole disk - - For each device, partitions are added as: - 0 = /dev/amiraid/ar? Whole disk - 1 = /dev/amiraid/ar?p1 First partition - 2 = /dev/amiraid/ar?p2 Second partition - ... - 15 = /dev/amiraid/ar?p15 15th partition - - 102 char - - 102 block Compressed block device - 0 = /dev/cbd/a First compressed block device, whole device - 16 = /dev/cbd/b Second compressed block device, whole device - ... - 240 = /dev/cbd/p 16th compressed block device, whole device - - Partitions are handled in the same way as for IDE - disks (see major number 3) except that the limit on - partitions is 15. - - 103 char Arla network file system - 0 = /dev/nnpfs0 First NNPFS device - 1 = /dev/nnpfs1 Second NNPFS device - - Arla is a free clone of the Andrew File System, AFS. - The NNPFS device gives user mode filesystem - implementations a kernel presence for caching and easy - mounting. For more information about the project, - write to or see - http://www.stacken.kth.se/project/arla/ - - 103 block Audit device - 0 = /dev/audit Audit device - - 104 char Flash BIOS support - - 104 block Compaq Next Generation Drive Array, first controller - 0 = /dev/cciss/c0d0 First logical drive, whole disk - 16 = /dev/cciss/c0d1 Second logical drive, whole disk - ... - 240 = /dev/cciss/c0d15 16th logical drive, whole disk - - Partitions are handled the same way as for Mylex - DAC960 (see major number 48) except that the limit on - partitions is 15. - - 105 char Comtrol VS-1000 serial controller - 0 = /dev/ttyV0 First VS-1000 port - 1 = /dev/ttyV1 Second VS-1000 port - ... - - 105 block Compaq Next Generation Drive Array, second controller - 0 = /dev/cciss/c1d0 First logical drive, whole disk - 16 = /dev/cciss/c1d1 Second logical drive, whole disk - ... - 240 = /dev/cciss/c1d15 16th logical drive, whole disk - - Partitions are handled the same way as for Mylex - DAC960 (see major number 48) except that the limit on - partitions is 15. - - 106 char Comtrol VS-1000 serial controller - alternate devices - 0 = /dev/cuv0 First VS-1000 port - 1 = /dev/cuv1 Second VS-1000 port - ... - - 106 block Compaq Next Generation Drive Array, third controller - 0 = /dev/cciss/c2d0 First logical drive, whole disk - 16 = /dev/cciss/c2d1 Second logical drive, whole disk - ... - 240 = /dev/cciss/c2d15 16th logical drive, whole disk - - Partitions are handled the same way as for Mylex - DAC960 (see major number 48) except that the limit on - partitions is 15. - - 107 char 3Dfx Voodoo Graphics device - 0 = /dev/3dfx Primary 3Dfx graphics device - - 107 block Compaq Next Generation Drive Array, fourth controller - 0 = /dev/cciss/c3d0 First logical drive, whole disk - 16 = /dev/cciss/c3d1 Second logical drive, whole disk - ... - 240 = /dev/cciss/c3d15 16th logical drive, whole disk - - Partitions are handled the same way as for Mylex - DAC960 (see major number 48) except that the limit on - partitions is 15. - - 108 char Device independent PPP interface - 0 = /dev/ppp Device independent PPP interface - - 108 block Compaq Next Generation Drive Array, fifth controller - 0 = /dev/cciss/c4d0 First logical drive, whole disk - 16 = /dev/cciss/c4d1 Second logical drive, whole disk - ... - 240 = /dev/cciss/c4d15 16th logical drive, whole disk - - Partitions are handled the same way as for Mylex - DAC960 (see major number 48) except that the limit on - partitions is 15. - - 109 char Reserved for logical volume manager - - 109 block Compaq Next Generation Drive Array, sixth controller - 0 = /dev/cciss/c5d0 First logical drive, whole disk - 16 = /dev/cciss/c5d1 Second logical drive, whole disk - ... - 240 = /dev/cciss/c5d15 16th logical drive, whole disk - - Partitions are handled the same way as for Mylex - DAC960 (see major number 48) except that the limit on - partitions is 15. - - 110 char miroMEDIA Surround board - 0 = /dev/srnd0 First miroMEDIA Surround board - 1 = /dev/srnd1 Second miroMEDIA Surround board - ... - - 110 block Compaq Next Generation Drive Array, seventh controller - 0 = /dev/cciss/c6d0 First logical drive, whole disk - 16 = /dev/cciss/c6d1 Second logical drive, whole disk - ... - 240 = /dev/cciss/c6d15 16th logical drive, whole disk - - Partitions are handled the same way as for Mylex - DAC960 (see major number 48) except that the limit on - partitions is 15. - - 111 char - - 111 block Compaq Next Generation Drive Array, eighth controller - 0 = /dev/cciss/c7d0 First logical drive, whole disk - 16 = /dev/cciss/c7d1 Second logical drive, whole disk - ... - 240 = /dev/cciss/c7d15 16th logical drive, whole disk - - Partitions are handled the same way as for Mylex - DAC960 (see major number 48) except that the limit on - partitions is 15. - - 112 char ISI serial card - 0 = /dev/ttyM0 First ISI port - 1 = /dev/ttyM1 Second ISI port - ... - - There is currently a device-naming conflict between - these and PAM multimodems (major 78). - - 112 block IBM iSeries virtual disk - 0 = /dev/iseries/vda First virtual disk, whole disk - 8 = /dev/iseries/vdb Second virtual disk, whole disk - ... - 200 = /dev/iseries/vdz 26th virtual disk, whole disk - 208 = /dev/iseries/vdaa 27th virtual disk, whole disk - ... - 248 = /dev/iseries/vdaf 32nd virtual disk, whole disk - - Partitions are handled in the same way as for IDE - disks (see major number 3) except that the limit on - partitions is 7. - - 113 char ISI serial card - alternate devices - 0 = /dev/cum0 Callout device for ttyM0 - 1 = /dev/cum1 Callout device for ttyM1 - ... - - 113 block IBM iSeries virtual CD-ROM - 0 = /dev/iseries/vcda First virtual CD-ROM - 1 = /dev/iseries/vcdb Second virtual CD-ROM - ... - - 114 char Picture Elements ISE board - 0 = /dev/ise0 First ISE board - 1 = /dev/ise1 Second ISE board - ... - 128 = /dev/isex0 Control node for first ISE board - 129 = /dev/isex1 Control node for second ISE board - ... - - The ISE board is an embedded computer, optimized for - image processing. The /dev/iseN nodes are the general - I/O access to the board, the /dev/isex0 nodes command - nodes used to control the board. - - 114 block IDE BIOS powered software RAID interfaces such as the - Promise Fastrak - - 0 = /dev/ataraid/d0 - 1 = /dev/ataraid/d0p1 - 2 = /dev/ataraid/d0p2 - ... - 16 = /dev/ataraid/d1 - 17 = /dev/ataraid/d1p1 - 18 = /dev/ataraid/d1p2 - ... - 255 = /dev/ataraid/d15p15 - - Partitions are handled in the same way as for IDE - disks (see major number 3) except that the limit on - partitions is 15. - - 115 char TI link cable devices (115 was formerly the console driver speaker) - 0 = /dev/tipar0 Parallel cable on first parallel port - ... - 7 = /dev/tipar7 Parallel cable on seventh parallel port - - 8 = /dev/tiser0 Serial cable on first serial port - ... - 15 = /dev/tiser7 Serial cable on seventh serial port - - 16 = /dev/tiusb0 First USB cable - ... - 47 = /dev/tiusb31 32nd USB cable - - 115 block NetWare (NWFS) Devices (0-255) - - The NWFS (NetWare) devices are used to present a - collection of NetWare Mirror Groups or NetWare - Partitions as a logical storage segment for - use in mounting NetWare volumes. A maximum of - 256 NetWare volumes can be supported in a single - machine. - - http://cgfa.telepac.pt/ftp2/kernel.org/linux/kernel/people/jmerkey/nwfs/ - - 0 = /dev/nwfs/v0 First NetWare (NWFS) Logical Volume - 1 = /dev/nwfs/v1 Second NetWare (NWFS) Logical Volume - 2 = /dev/nwfs/v2 Third NetWare (NWFS) Logical Volume - ... - 255 = /dev/nwfs/v255 Last NetWare (NWFS) Logical Volume - - 116 char Advanced Linux Sound Driver (ALSA) - - 116 block MicroMemory battery backed RAM adapter (NVRAM) - Supports 16 boards, 15 partitions each. - Requested by neilb at cse.unsw.edu.au. - - 0 = /dev/umem/d0 Whole of first board - 1 = /dev/umem/d0p1 First partition of first board - 2 = /dev/umem/d0p2 Second partition of first board - 15 = /dev/umem/d0p15 15th partition of first board - - 16 = /dev/umem/d1 Whole of second board - 17 = /dev/umem/d1p1 First partition of second board - ... - 255= /dev/umem/d15p15 15th partition of 16th board. - - 117 char COSA/SRP synchronous serial card - 0 = /dev/cosa0c0 1st board, 1st channel - 1 = /dev/cosa0c1 1st board, 2nd channel - ... - 16 = /dev/cosa1c0 2nd board, 1st channel - 17 = /dev/cosa1c1 2nd board, 2nd channel - ... - - 117 block Enterprise Volume Management System (EVMS) - - The EVMS driver uses a layered, plug-in model to provide - unparalleled flexibility and extensibility in managing - storage. This allows for easy expansion or customization - of various levels of volume management. Requested by - Mark Peloquin (peloquin at us.ibm.com). - - Note: EVMS populates and manages all the devnodes in - /dev/evms. - - http://sf.net/projects/evms - - 0 = /dev/evms/block_device EVMS block device - 1 = /dev/evms/legacyname1 First EVMS legacy device - 2 = /dev/evms/legacyname2 Second EVMS legacy device - ... - Both ranges can grow (down or up) until they meet. - ... - 254 = /dev/evms/EVMSname2 Second EVMS native device - 255 = /dev/evms/EVMSname1 First EVMS native device - - Note: legacyname(s) are derived from the normal legacy - device names. For example, /dev/hda5 would become - /dev/evms/hda5. - - 118 char IBM Cryptographic Accelerator - 0 = /dev/ica Virtual interface to all IBM Crypto Accelerators - 1 = /dev/ica0 IBMCA Device 0 - 2 = /dev/ica1 IBMCA Device 1 - ... - - 119 char VMware virtual network control - 0 = /dev/vnet0 1st virtual network - 1 = /dev/vnet1 2nd virtual network - ... - - 120-127 char LOCAL/EXPERIMENTAL USE - - 120-127 block LOCAL/EXPERIMENTAL USE - Allocated for local/experimental use. For devices not - assigned official numbers, these ranges should be - used in order to avoid conflicting with future assignments. - - 128-135 char Unix98 PTY masters - - These devices should not have corresponding device - nodes; instead they should be accessed through the - /dev/ptmx cloning interface. - - 128 block SCSI disk devices (128-143) - 0 = /dev/sddy 129th SCSI disk whole disk - 16 = /dev/sddz 130th SCSI disk whole disk - 32 = /dev/sdea 131th SCSI disk whole disk - ... - 240 = /dev/sden 144th SCSI disk whole disk - - Partitions are handled in the same way as for IDE - disks (see major number 3) except that the limit on - partitions is 15. - - 129 block SCSI disk devices (144-159) - 0 = /dev/sdeo 145th SCSI disk whole disk - 16 = /dev/sdep 146th SCSI disk whole disk - 32 = /dev/sdeq 147th SCSI disk whole disk - ... - 240 = /dev/sdfd 160th SCSI disk whole disk - - Partitions are handled in the same way as for IDE - disks (see major number 3) except that the limit on - partitions is 15. - - 130 char (Misc devices) - - 130 block SCSI disk devices (160-175) - 0 = /dev/sdfe 161st SCSI disk whole disk - 16 = /dev/sdff 162nd SCSI disk whole disk - 32 = /dev/sdfg 163rd SCSI disk whole disk - ... - 240 = /dev/sdft 176th SCSI disk whole disk - - Partitions are handled in the same way as for IDE - disks (see major number 3) except that the limit on - partitions is 15. - - 131 block SCSI disk devices (176-191) - 0 = /dev/sdfu 177th SCSI disk whole disk - 16 = /dev/sdfv 178th SCSI disk whole disk - 32 = /dev/sdfw 179th SCSI disk whole disk - ... - 240 = /dev/sdgj 192nd SCSI disk whole disk - - Partitions are handled in the same way as for IDE - disks (see major number 3) except that the limit on - partitions is 15. - - 132 block SCSI disk devices (192-207) - 0 = /dev/sdgk 193rd SCSI disk whole disk - 16 = /dev/sdgl 194th SCSI disk whole disk - 32 = /dev/sdgm 195th SCSI disk whole disk - ... - 240 = /dev/sdgz 208th SCSI disk whole disk - - Partitions are handled in the same way as for IDE - disks (see major number 3) except that the limit on - partitions is 15. - - 133 block SCSI disk devices (208-223) - 0 = /dev/sdha 209th SCSI disk whole disk - 16 = /dev/sdhb 210th SCSI disk whole disk - 32 = /dev/sdhc 211th SCSI disk whole disk - ... - 240 = /dev/sdhp 224th SCSI disk whole disk - - Partitions are handled in the same way as for IDE - disks (see major number 3) except that the limit on - partitions is 15. - - 134 block SCSI disk devices (224-239) - 0 = /dev/sdhq 225th SCSI disk whole disk - 16 = /dev/sdhr 226th SCSI disk whole disk - 32 = /dev/sdhs 227th SCSI disk whole disk - ... - 240 = /dev/sdif 240th SCSI disk whole disk - - Partitions are handled in the same way as for IDE - disks (see major number 3) except that the limit on - partitions is 15. - - 135 block SCSI disk devices (240-255) - 0 = /dev/sdig 241st SCSI disk whole disk - 16 = /dev/sdih 242nd SCSI disk whole disk - 32 = /dev/sdih 243rd SCSI disk whole disk - ... - 240 = /dev/sdiv 256th SCSI disk whole disk - - Partitions are handled in the same way as for IDE - disks (see major number 3) except that the limit on - partitions is 15. - - 136-143 char Unix98 PTY slaves - 0 = /dev/pts/0 First Unix98 pseudo-TTY - 1 = /dev/pts/1 Second Unix98 pseudo-TTY - ... - - These device nodes are automatically generated with - the proper permissions and modes by mounting the - devpts filesystem onto /dev/pts with the appropriate - mount options (distribution dependent, however, on - *most* distributions the appropriate options are - "mode=0620,gid=".) - - 136 block Mylex DAC960 PCI RAID controller; ninth controller - 0 = /dev/rd/c8d0 First disk, whole disk - 8 = /dev/rd/c8d1 Second disk, whole disk - ... - 248 = /dev/rd/c8d31 32nd disk, whole disk - - Partitions are handled as for major 48. - - 137 block Mylex DAC960 PCI RAID controller; tenth controller - 0 = /dev/rd/c9d0 First disk, whole disk - 8 = /dev/rd/c9d1 Second disk, whole disk - ... - 248 = /dev/rd/c9d31 32nd disk, whole disk - - Partitions are handled as for major 48. - - 138 block Mylex DAC960 PCI RAID controller; eleventh controller - 0 = /dev/rd/c10d0 First disk, whole disk - 8 = /dev/rd/c10d1 Second disk, whole disk - ... - 248 = /dev/rd/c10d31 32nd disk, whole disk - - Partitions are handled as for major 48. - - 139 block Mylex DAC960 PCI RAID controller; twelfth controller - 0 = /dev/rd/c11d0 First disk, whole disk - 8 = /dev/rd/c11d1 Second disk, whole disk - ... - 248 = /dev/rd/c11d31 32nd disk, whole disk - - Partitions are handled as for major 48. - - 140 block Mylex DAC960 PCI RAID controller; thirteenth controller - 0 = /dev/rd/c12d0 First disk, whole disk - 8 = /dev/rd/c12d1 Second disk, whole disk - ... - 248 = /dev/rd/c12d31 32nd disk, whole disk - - Partitions are handled as for major 48. - - 141 block Mylex DAC960 PCI RAID controller; fourteenth controller - 0 = /dev/rd/c13d0 First disk, whole disk - 8 = /dev/rd/c13d1 Second disk, whole disk - ... - 248 = /dev/rd/c13d31 32nd disk, whole disk - - Partitions are handled as for major 48. - - 142 block Mylex DAC960 PCI RAID controller; fifteenth controller - 0 = /dev/rd/c14d0 First disk, whole disk - 8 = /dev/rd/c14d1 Second disk, whole disk - ... - 248 = /dev/rd/c14d31 32nd disk, whole disk - - Partitions are handled as for major 48. - - 143 block Mylex DAC960 PCI RAID controller; sixteenth controller - 0 = /dev/rd/c15d0 First disk, whole disk - 8 = /dev/rd/c15d1 Second disk, whole disk - ... - 248 = /dev/rd/c15d31 32nd disk, whole disk - - Partitions are handled as for major 48. - - 144 char Encapsulated PPP - 0 = /dev/pppox0 First PPP over Ethernet - ... - 63 = /dev/pppox63 64th PPP over Ethernet - - This is primarily used for ADSL. - - The SST 5136-DN DeviceNet interface driver has been - relocated to major 183 due to an unfortunate conflict. - - 144 block Expansion Area #1 for more non-device (e.g. NFS) mounts - 0 = mounted device 256 - 255 = mounted device 511 - - 145 char SAM9407-based soundcard - 0 = /dev/sam0_mixer - 1 = /dev/sam0_sequencer - 2 = /dev/sam0_midi00 - 3 = /dev/sam0_dsp - 4 = /dev/sam0_audio - 6 = /dev/sam0_sndstat - 18 = /dev/sam0_midi01 - 34 = /dev/sam0_midi02 - 50 = /dev/sam0_midi03 - 64 = /dev/sam1_mixer - ... - 128 = /dev/sam2_mixer - ... - 192 = /dev/sam3_mixer - ... - - Device functions match OSS, but offer a number of - addons, which are sam9407 specific. OSS can be - operated simultaneously, taking care of the codec. - - 145 block Expansion Area #2 for more non-device (e.g. NFS) mounts - 0 = mounted device 512 - 255 = mounted device 767 - - 146 char SYSTRAM SCRAMNet mirrored-memory network - 0 = /dev/scramnet0 First SCRAMNet device - 1 = /dev/scramnet1 Second SCRAMNet device - ... - - 146 block Expansion Area #3 for more non-device (e.g. NFS) mounts - 0 = mounted device 768 - 255 = mounted device 1023 - - 147 char Aureal Semiconductor Vortex Audio device - 0 = /dev/aureal0 First Aureal Vortex - 1 = /dev/aureal1 Second Aureal Vortex - ... - - 147 block Distributed Replicated Block Device (DRBD) - 0 = /dev/drbd0 First DRBD device - 1 = /dev/drbd1 Second DRBD device - ... - - 148 char Technology Concepts serial card - 0 = /dev/ttyT0 First TCL port - 1 = /dev/ttyT1 Second TCL port - ... - - 149 char Technology Concepts serial card - alternate devices - 0 = /dev/cut0 Callout device for ttyT0 - 1 = /dev/cut0 Callout device for ttyT1 - ... - - 150 char Real-Time Linux FIFOs - 0 = /dev/rtf0 First RTLinux FIFO - 1 = /dev/rtf1 Second RTLinux FIFO - ... - - 151 char DPT I2O SmartRaid V controller - 0 = /dev/dpti0 First DPT I2O adapter - 1 = /dev/dpti1 Second DPT I2O adapter - ... - - 152 char EtherDrive Control Device - 0 = /dev/etherd/ctl Connect/Disconnect an EtherDrive - 1 = /dev/etherd/err Monitor errors - 2 = /dev/etherd/raw Raw AoE packet monitor - - 152 block EtherDrive Block Devices - 0 = /dev/etherd/0 EtherDrive 0 - ... - 255 = /dev/etherd/255 EtherDrive 255 - - 153 char SPI Bus Interface (sometimes referred to as MicroWire) - 0 = /dev/spi0 First SPI device on the bus - 1 = /dev/spi1 Second SPI device on the bus - ... - 15 = /dev/spi15 Sixteenth SPI device on the bus - - 153 block Enhanced Metadisk RAID (EMD) storage units - 0 = /dev/emd/0 First unit - 1 = /dev/emd/0p1 Partition 1 on First unit - 2 = /dev/emd/0p2 Partition 2 on First unit - ... - 15 = /dev/emd/0p15 Partition 15 on First unit - - 16 = /dev/emd/1 Second unit - 32 = /dev/emd/2 Third unit - ... - 240 = /dev/emd/15 Sixteenth unit - - Partitions are handled in the same way as for IDE - disks (see major number 3) except that the limit on - partitions is 15. - - 154 char Specialix RIO serial card - 0 = /dev/ttySR0 First RIO port - ... - 255 = /dev/ttySR255 256th RIO port - - 155 char Specialix RIO serial card - alternate devices - 0 = /dev/cusr0 Callout device for ttySR0 - ... - 255 = /dev/cusr255 Callout device for ttySR255 - - 156 char Specialix RIO serial card - 0 = /dev/ttySR256 257th RIO port - ... - 255 = /dev/ttySR511 512th RIO port - - 157 char Specialix RIO serial card - alternate devices - 0 = /dev/cusr256 Callout device for ttySR256 - ... - 255 = /dev/cusr511 Callout device for ttySR511 - - 158 char Dialogic GammaLink fax driver - 0 = /dev/gfax0 GammaLink channel 0 - 1 = /dev/gfax1 GammaLink channel 1 - ... - - 159 char RESERVED - - 159 block RESERVED - - 160 char General Purpose Instrument Bus (GPIB) - 0 = /dev/gpib0 First GPIB bus - 1 = /dev/gpib1 Second GPIB bus - ... - - 160 block Carmel 8-port SATA Disks on First Controller - 0 = /dev/carmel/0 SATA disk 0 whole disk - 1 = /dev/carmel/0p1 SATA disk 0 partition 1 - ... - 31 = /dev/carmel/0p31 SATA disk 0 partition 31 - - 32 = /dev/carmel/1 SATA disk 1 whole disk - 64 = /dev/carmel/2 SATA disk 2 whole disk - ... - 224 = /dev/carmel/7 SATA disk 7 whole disk - - Partitions are handled in the same way as for IDE - disks (see major number 3) except that the limit on - partitions is 31. - - 161 char IrCOMM devices (IrDA serial/parallel emulation) - 0 = /dev/ircomm0 First IrCOMM device - 1 = /dev/ircomm1 Second IrCOMM device - ... - 16 = /dev/irlpt0 First IrLPT device - 17 = /dev/irlpt1 Second IrLPT device - ... - - 161 block Carmel 8-port SATA Disks on Second Controller - 0 = /dev/carmel/8 SATA disk 8 whole disk - 1 = /dev/carmel/8p1 SATA disk 8 partition 1 - ... - 31 = /dev/carmel/8p31 SATA disk 8 partition 31 - - 32 = /dev/carmel/9 SATA disk 9 whole disk - 64 = /dev/carmel/10 SATA disk 10 whole disk - ... - 224 = /dev/carmel/15 SATA disk 15 whole disk - - Partitions are handled in the same way as for IDE - disks (see major number 3) except that the limit on - partitions is 31. - - 162 char Raw block device interface - 0 = /dev/rawctl Raw I/O control device - 1 = /dev/raw/raw1 First raw I/O device - 2 = /dev/raw/raw2 Second raw I/O device - ... - max minor number of raw device is set by kernel config - MAX_RAW_DEVS or raw module parameter 'max_raw_devs' - - 163 char - - 164 char Chase Research AT/PCI-Fast serial card - 0 = /dev/ttyCH0 AT/PCI-Fast board 0, port 0 - ... - 15 = /dev/ttyCH15 AT/PCI-Fast board 0, port 15 - 16 = /dev/ttyCH16 AT/PCI-Fast board 1, port 0 - ... - 31 = /dev/ttyCH31 AT/PCI-Fast board 1, port 15 - 32 = /dev/ttyCH32 AT/PCI-Fast board 2, port 0 - ... - 47 = /dev/ttyCH47 AT/PCI-Fast board 2, port 15 - 48 = /dev/ttyCH48 AT/PCI-Fast board 3, port 0 - ... - 63 = /dev/ttyCH63 AT/PCI-Fast board 3, port 15 - - 165 char Chase Research AT/PCI-Fast serial card - alternate devices - 0 = /dev/cuch0 Callout device for ttyCH0 - ... - 63 = /dev/cuch63 Callout device for ttyCH63 - - 166 char ACM USB modems - 0 = /dev/ttyACM0 First ACM modem - 1 = /dev/ttyACM1 Second ACM modem - ... - - 167 char ACM USB modems - alternate devices - 0 = /dev/cuacm0 Callout device for ttyACM0 - 1 = /dev/cuacm1 Callout device for ttyACM1 - ... - - 168 char Eracom CSA7000 PCI encryption adaptor - 0 = /dev/ecsa0 First CSA7000 - 1 = /dev/ecsa1 Second CSA7000 - ... - - 169 char Eracom CSA8000 PCI encryption adaptor - 0 = /dev/ecsa8-0 First CSA8000 - 1 = /dev/ecsa8-1 Second CSA8000 - ... - - 170 char AMI MegaRAC remote access controller - 0 = /dev/megarac0 First MegaRAC card - 1 = /dev/megarac1 Second MegaRAC card - ... - - 171 char Reserved for IEEE 1394 (Firewire) - - 172 char Moxa Intellio serial card - 0 = /dev/ttyMX0 First Moxa port - 1 = /dev/ttyMX1 Second Moxa port - ... - 127 = /dev/ttyMX127 128th Moxa port - 128 = /dev/moxactl Moxa control port - - 173 char Moxa Intellio serial card - alternate devices - 0 = /dev/cumx0 Callout device for ttyMX0 - 1 = /dev/cumx1 Callout device for ttyMX1 - ... - 127 = /dev/cumx127 Callout device for ttyMX127 - - 174 char SmartIO serial card - 0 = /dev/ttySI0 First SmartIO port - 1 = /dev/ttySI1 Second SmartIO port - ... - - 175 char SmartIO serial card - alternate devices - 0 = /dev/cusi0 Callout device for ttySI0 - 1 = /dev/cusi1 Callout device for ttySI1 - ... - - 176 char nCipher nFast PCI crypto accelerator - 0 = /dev/nfastpci0 First nFast PCI device - 1 = /dev/nfastpci1 First nFast PCI device - ... - - 177 char TI PCILynx memory spaces - 0 = /dev/pcilynx/aux0 AUX space of first PCILynx card - ... - 15 = /dev/pcilynx/aux15 AUX space of 16th PCILynx card - 16 = /dev/pcilynx/rom0 ROM space of first PCILynx card - ... - 31 = /dev/pcilynx/rom15 ROM space of 16th PCILynx card - 32 = /dev/pcilynx/ram0 RAM space of first PCILynx card - ... - 47 = /dev/pcilynx/ram15 RAM space of 16th PCILynx card - - 178 char Giganet cLAN1xxx virtual interface adapter - 0 = /dev/clanvi0 First cLAN adapter - 1 = /dev/clanvi1 Second cLAN adapter - ... - - 179 block MMC block devices - 0 = /dev/mmcblk0 First SD/MMC card - 1 = /dev/mmcblk0p1 First partition on first MMC card - 8 = /dev/mmcblk1 Second SD/MMC card - ... - - The start of next SD/MMC card can be configured with - CONFIG_MMC_BLOCK_MINORS, or overridden at boot/modprobe - time using the mmcblk.perdev_minors option. That would - bump the offset between each card to be the configured - value instead of the default 8. - - 179 char CCube DVXChip-based PCI products - 0 = /dev/dvxirq0 First DVX device - 1 = /dev/dvxirq1 Second DVX device - ... - - 180 char USB devices - 0 = /dev/usb/lp0 First USB printer - ... - 15 = /dev/usb/lp15 16th USB printer - 48 = /dev/usb/scanner0 First USB scanner - ... - 63 = /dev/usb/scanner15 16th USB scanner - 64 = /dev/usb/rio500 Diamond Rio 500 - 65 = /dev/usb/usblcd USBLCD Interface (info@usblcd.de) - 66 = /dev/usb/cpad0 Synaptics cPad (mouse/LCD) - 96 = /dev/usb/hiddev0 1st USB HID device - ... - 111 = /dev/usb/hiddev15 16th USB HID device - 112 = /dev/usb/auer0 1st auerswald ISDN device - ... - 127 = /dev/usb/auer15 16th auerswald ISDN device - 128 = /dev/usb/brlvgr0 First Braille Voyager device - ... - 131 = /dev/usb/brlvgr3 Fourth Braille Voyager device - 132 = /dev/usb/idmouse ID Mouse (fingerprint scanner) device - 133 = /dev/usb/sisusbvga1 First SiSUSB VGA device - ... - 140 = /dev/usb/sisusbvga8 Eighth SISUSB VGA device - 144 = /dev/usb/lcd USB LCD device - 160 = /dev/usb/legousbtower0 1st USB Legotower device - ... - 175 = /dev/usb/legousbtower15 16th USB Legotower device - 176 = /dev/usb/usbtmc1 First USB TMC device - ... - 191 = /dev/usb/usbtmc16 16th USB TMC device - 192 = /dev/usb/yurex1 First USB Yurex device - ... - 209 = /dev/usb/yurex16 16th USB Yurex device - - 180 block USB block devices - 0 = /dev/uba First USB block device - 8 = /dev/ubb Second USB block device - 16 = /dev/ubc Third USB block device - ... - - 181 char Conrad Electronic parallel port radio clocks - 0 = /dev/pcfclock0 First Conrad radio clock - 1 = /dev/pcfclock1 Second Conrad radio clock - ... - - 182 char Picture Elements THR2 binarizer - 0 = /dev/pethr0 First THR2 board - 1 = /dev/pethr1 Second THR2 board - ... - - 183 char SST 5136-DN DeviceNet interface - 0 = /dev/ss5136dn0 First DeviceNet interface - 1 = /dev/ss5136dn1 Second DeviceNet interface - ... - - This device used to be assigned to major number 144. - It had to be moved due to an unfortunate conflict. - - 184 char Picture Elements' video simulator/sender - 0 = /dev/pevss0 First sender board - 1 = /dev/pevss1 Second sender board - ... - - 185 char InterMezzo high availability file system - 0 = /dev/intermezzo0 First cache manager - 1 = /dev/intermezzo1 Second cache manager - ... - - See http://web.archive.org/web/20080115195241/ - http://inter-mezzo.org/index.html - - 186 char Object-based storage control device - 0 = /dev/obd0 First obd control device - 1 = /dev/obd1 Second obd control device - ... - - See ftp://ftp.lustre.org/pub/obd for code and information. - - 187 char DESkey hardware encryption device - 0 = /dev/deskey0 First DES key - 1 = /dev/deskey1 Second DES key - ... - - 188 char USB serial converters - 0 = /dev/ttyUSB0 First USB serial converter - 1 = /dev/ttyUSB1 Second USB serial converter - ... - - 189 char USB serial converters - alternate devices - 0 = /dev/cuusb0 Callout device for ttyUSB0 - 1 = /dev/cuusb1 Callout device for ttyUSB1 - ... - - 190 char Kansas City tracker/tuner card - 0 = /dev/kctt0 First KCT/T card - 1 = /dev/kctt1 Second KCT/T card - ... - - 191 char Reserved for PCMCIA - - 192 char Kernel profiling interface - 0 = /dev/profile Profiling control device - 1 = /dev/profile0 Profiling device for CPU 0 - 2 = /dev/profile1 Profiling device for CPU 1 - ... - - 193 char Kernel event-tracing interface - 0 = /dev/trace Tracing control device - 1 = /dev/trace0 Tracing device for CPU 0 - 2 = /dev/trace1 Tracing device for CPU 1 - ... - - 194 char linVideoStreams (LINVS) - 0 = /dev/mvideo/status0 Video compression status - 1 = /dev/mvideo/stream0 Video stream - 2 = /dev/mvideo/frame0 Single compressed frame - 3 = /dev/mvideo/rawframe0 Raw uncompressed frame - 4 = /dev/mvideo/codec0 Direct codec access - 5 = /dev/mvideo/video4linux0 Video4Linux compatibility - - 16 = /dev/mvideo/status1 Second device - ... - 32 = /dev/mvideo/status2 Third device - ... - ... - 240 = /dev/mvideo/status15 16th device - ... - - 195 char Nvidia graphics devices - 0 = /dev/nvidia0 First Nvidia card - 1 = /dev/nvidia1 Second Nvidia card - ... - 255 = /dev/nvidiactl Nvidia card control device - - 196 char Tormenta T1 card - 0 = /dev/tor/0 Master control channel for all cards - 1 = /dev/tor/1 First DS0 - 2 = /dev/tor/2 Second DS0 - ... - 48 = /dev/tor/48 48th DS0 - 49 = /dev/tor/49 First pseudo-channel - 50 = /dev/tor/50 Second pseudo-channel - ... - - 197 char OpenTNF tracing facility - 0 = /dev/tnf/t0 Trace 0 data extraction - 1 = /dev/tnf/t1 Trace 1 data extraction - ... - 128 = /dev/tnf/status Tracing facility status - 130 = /dev/tnf/trace Tracing device - - 198 char Total Impact TPMP2 quad coprocessor PCI card - 0 = /dev/tpmp2/0 First card - 1 = /dev/tpmp2/1 Second card - ... - - 199 char Veritas volume manager (VxVM) volumes - 0 = /dev/vx/rdsk/*/* First volume - 1 = /dev/vx/rdsk/*/* Second volume - ... - - 199 block Veritas volume manager (VxVM) volumes - 0 = /dev/vx/dsk/*/* First volume - 1 = /dev/vx/dsk/*/* Second volume - ... - - The namespace in these directories is maintained by - the user space VxVM software. - - 200 char Veritas VxVM configuration interface - 0 = /dev/vx/config Configuration access node - 1 = /dev/vx/trace Volume i/o trace access node - 2 = /dev/vx/iod Volume i/o daemon access node - 3 = /dev/vx/info Volume information access node - 4 = /dev/vx/task Volume tasks access node - 5 = /dev/vx/taskmon Volume tasks monitor daemon - - 201 char Veritas VxVM dynamic multipathing driver - 0 = /dev/vx/rdmp/* First multipath device - 1 = /dev/vx/rdmp/* Second multipath device - ... - 201 block Veritas VxVM dynamic multipathing driver - 0 = /dev/vx/dmp/* First multipath device - 1 = /dev/vx/dmp/* Second multipath device - ... - - The namespace in these directories is maintained by - the user space VxVM software. - - 202 char CPU model-specific registers - 0 = /dev/cpu/0/msr MSRs on CPU 0 - 1 = /dev/cpu/1/msr MSRs on CPU 1 - ... - - 202 block Xen Virtual Block Device - 0 = /dev/xvda First Xen VBD whole disk - 16 = /dev/xvdb Second Xen VBD whole disk - 32 = /dev/xvdc Third Xen VBD whole disk - ... - 240 = /dev/xvdp Sixteenth Xen VBD whole disk - - Partitions are handled in the same way as for IDE - disks (see major number 3) except that the limit on - partitions is 15. - - 203 char CPU CPUID information - 0 = /dev/cpu/0/cpuid CPUID on CPU 0 - 1 = /dev/cpu/1/cpuid CPUID on CPU 1 - ... - - 204 char Low-density serial ports - 0 = /dev/ttyLU0 LinkUp Systems L72xx UART - port 0 - 1 = /dev/ttyLU1 LinkUp Systems L72xx UART - port 1 - 2 = /dev/ttyLU2 LinkUp Systems L72xx UART - port 2 - 3 = /dev/ttyLU3 LinkUp Systems L72xx UART - port 3 - 4 = /dev/ttyFB0 Intel Footbridge (ARM) - 5 = /dev/ttySA0 StrongARM builtin serial port 0 - 6 = /dev/ttySA1 StrongARM builtin serial port 1 - 7 = /dev/ttySA2 StrongARM builtin serial port 2 - 8 = /dev/ttySC0 SCI serial port (SuperH) - port 0 - 9 = /dev/ttySC1 SCI serial port (SuperH) - port 1 - 10 = /dev/ttySC2 SCI serial port (SuperH) - port 2 - 11 = /dev/ttySC3 SCI serial port (SuperH) - port 3 - 12 = /dev/ttyFW0 Firmware console - port 0 - 13 = /dev/ttyFW1 Firmware console - port 1 - 14 = /dev/ttyFW2 Firmware console - port 2 - 15 = /dev/ttyFW3 Firmware console - port 3 - 16 = /dev/ttyAM0 ARM "AMBA" serial port 0 - ... - 31 = /dev/ttyAM15 ARM "AMBA" serial port 15 - 32 = /dev/ttyDB0 DataBooster serial port 0 - ... - 39 = /dev/ttyDB7 DataBooster serial port 7 - 40 = /dev/ttySG0 SGI Altix console port - 41 = /dev/ttySMX0 Motorola i.MX - port 0 - 42 = /dev/ttySMX1 Motorola i.MX - port 1 - 43 = /dev/ttySMX2 Motorola i.MX - port 2 - 44 = /dev/ttyMM0 Marvell MPSC - port 0 - 45 = /dev/ttyMM1 Marvell MPSC - port 1 - 46 = /dev/ttyCPM0 PPC CPM (SCC or SMC) - port 0 - ... - 47 = /dev/ttyCPM5 PPC CPM (SCC or SMC) - port 5 - 50 = /dev/ttyIOC0 Altix serial card - ... - 81 = /dev/ttyIOC31 Altix serial card - 82 = /dev/ttyVR0 NEC VR4100 series SIU - 83 = /dev/ttyVR1 NEC VR4100 series DSIU - 84 = /dev/ttyIOC84 Altix ioc4 serial card - ... - 115 = /dev/ttyIOC115 Altix ioc4 serial card - 116 = /dev/ttySIOC0 Altix ioc3 serial card - ... - 147 = /dev/ttySIOC31 Altix ioc3 serial card - 148 = /dev/ttyPSC0 PPC PSC - port 0 - ... - 153 = /dev/ttyPSC5 PPC PSC - port 5 - 154 = /dev/ttyAT0 ATMEL serial port 0 - ... - 169 = /dev/ttyAT15 ATMEL serial port 15 - 170 = /dev/ttyNX0 Hilscher netX serial port 0 - ... - 185 = /dev/ttyNX15 Hilscher netX serial port 15 - 186 = /dev/ttyJ0 JTAG1 DCC protocol based serial port emulation - 187 = /dev/ttyUL0 Xilinx uartlite - port 0 - ... - 190 = /dev/ttyUL3 Xilinx uartlite - port 3 - 191 = /dev/xvc0 Xen virtual console - port 0 - 192 = /dev/ttyPZ0 pmac_zilog - port 0 - ... - 195 = /dev/ttyPZ3 pmac_zilog - port 3 - 196 = /dev/ttyTX0 TX39/49 serial port 0 - ... - 204 = /dev/ttyTX7 TX39/49 serial port 7 - 205 = /dev/ttySC0 SC26xx serial port 0 - 206 = /dev/ttySC1 SC26xx serial port 1 - 207 = /dev/ttySC2 SC26xx serial port 2 - 208 = /dev/ttySC3 SC26xx serial port 3 - 209 = /dev/ttyMAX0 MAX3100 serial port 0 - 210 = /dev/ttyMAX1 MAX3100 serial port 1 - 211 = /dev/ttyMAX2 MAX3100 serial port 2 - 212 = /dev/ttyMAX3 MAX3100 serial port 3 - - 205 char Low-density serial ports (alternate device) - 0 = /dev/culu0 Callout device for ttyLU0 - 1 = /dev/culu1 Callout device for ttyLU1 - 2 = /dev/culu2 Callout device for ttyLU2 - 3 = /dev/culu3 Callout device for ttyLU3 - 4 = /dev/cufb0 Callout device for ttyFB0 - 5 = /dev/cusa0 Callout device for ttySA0 - 6 = /dev/cusa1 Callout device for ttySA1 - 7 = /dev/cusa2 Callout device for ttySA2 - 8 = /dev/cusc0 Callout device for ttySC0 - 9 = /dev/cusc1 Callout device for ttySC1 - 10 = /dev/cusc2 Callout device for ttySC2 - 11 = /dev/cusc3 Callout device for ttySC3 - 12 = /dev/cufw0 Callout device for ttyFW0 - 13 = /dev/cufw1 Callout device for ttyFW1 - 14 = /dev/cufw2 Callout device for ttyFW2 - 15 = /dev/cufw3 Callout device for ttyFW3 - 16 = /dev/cuam0 Callout device for ttyAM0 - ... - 31 = /dev/cuam15 Callout device for ttyAM15 - 32 = /dev/cudb0 Callout device for ttyDB0 - ... - 39 = /dev/cudb7 Callout device for ttyDB7 - 40 = /dev/cusg0 Callout device for ttySG0 - 41 = /dev/ttycusmx0 Callout device for ttySMX0 - 42 = /dev/ttycusmx1 Callout device for ttySMX1 - 43 = /dev/ttycusmx2 Callout device for ttySMX2 - 46 = /dev/cucpm0 Callout device for ttyCPM0 - ... - 49 = /dev/cucpm5 Callout device for ttyCPM5 - 50 = /dev/cuioc40 Callout device for ttyIOC40 - ... - 81 = /dev/cuioc431 Callout device for ttyIOC431 - 82 = /dev/cuvr0 Callout device for ttyVR0 - 83 = /dev/cuvr1 Callout device for ttyVR1 - - 206 char OnStream SC-x0 tape devices - 0 = /dev/osst0 First OnStream SCSI tape, mode 0 - 1 = /dev/osst1 Second OnStream SCSI tape, mode 0 - ... - 32 = /dev/osst0l First OnStream SCSI tape, mode 1 - 33 = /dev/osst1l Second OnStream SCSI tape, mode 1 - ... - 64 = /dev/osst0m First OnStream SCSI tape, mode 2 - 65 = /dev/osst1m Second OnStream SCSI tape, mode 2 - ... - 96 = /dev/osst0a First OnStream SCSI tape, mode 3 - 97 = /dev/osst1a Second OnStream SCSI tape, mode 3 - ... - 128 = /dev/nosst0 No rewind version of /dev/osst0 - 129 = /dev/nosst1 No rewind version of /dev/osst1 - ... - 160 = /dev/nosst0l No rewind version of /dev/osst0l - 161 = /dev/nosst1l No rewind version of /dev/osst1l - ... - 192 = /dev/nosst0m No rewind version of /dev/osst0m - 193 = /dev/nosst1m No rewind version of /dev/osst1m - ... - 224 = /dev/nosst0a No rewind version of /dev/osst0a - 225 = /dev/nosst1a No rewind version of /dev/osst1a - ... - - The OnStream SC-x0 SCSI tapes do not support the - standard SCSI SASD command set and therefore need - their own driver "osst". Note that the IDE, USB (and - maybe ParPort) versions may be driven via ide-scsi or - usb-storage SCSI emulation and this osst device and - driver as well. The ADR-x0 drives are QIC-157 - compliant and don't need osst. - - 207 char Compaq ProLiant health feature indicate - 0 = /dev/cpqhealth/cpqw Redirector interface - 1 = /dev/cpqhealth/crom EISA CROM - 2 = /dev/cpqhealth/cdt Data Table - 3 = /dev/cpqhealth/cevt Event Log - 4 = /dev/cpqhealth/casr Automatic Server Recovery - 5 = /dev/cpqhealth/cecc ECC Memory - 6 = /dev/cpqhealth/cmca Machine Check Architecture - 7 = /dev/cpqhealth/ccsm Deprecated CDT - 8 = /dev/cpqhealth/cnmi NMI Handling - 9 = /dev/cpqhealth/css Sideshow Management - 10 = /dev/cpqhealth/cram CMOS interface - 11 = /dev/cpqhealth/cpci PCI IRQ interface - - 208 char User space serial ports - 0 = /dev/ttyU0 First user space serial port - 1 = /dev/ttyU1 Second user space serial port - ... - - 209 char User space serial ports (alternate devices) - 0 = /dev/cuu0 Callout device for ttyU0 - 1 = /dev/cuu1 Callout device for ttyU1 - ... - - 210 char SBE, Inc. sync/async serial card - 0 = /dev/sbei/wxcfg0 Configuration device for board 0 - 1 = /dev/sbei/dld0 Download device for board 0 - 2 = /dev/sbei/wan00 WAN device, port 0, board 0 - 3 = /dev/sbei/wan01 WAN device, port 1, board 0 - 4 = /dev/sbei/wan02 WAN device, port 2, board 0 - 5 = /dev/sbei/wan03 WAN device, port 3, board 0 - 6 = /dev/sbei/wanc00 WAN clone device, port 0, board 0 - 7 = /dev/sbei/wanc01 WAN clone device, port 1, board 0 - 8 = /dev/sbei/wanc02 WAN clone device, port 2, board 0 - 9 = /dev/sbei/wanc03 WAN clone device, port 3, board 0 - 10 = /dev/sbei/wxcfg1 Configuration device for board 1 - 11 = /dev/sbei/dld1 Download device for board 1 - 12 = /dev/sbei/wan10 WAN device, port 0, board 1 - 13 = /dev/sbei/wan11 WAN device, port 1, board 1 - 14 = /dev/sbei/wan12 WAN device, port 2, board 1 - 15 = /dev/sbei/wan13 WAN device, port 3, board 1 - 16 = /dev/sbei/wanc10 WAN clone device, port 0, board 1 - 17 = /dev/sbei/wanc11 WAN clone device, port 1, board 1 - 18 = /dev/sbei/wanc12 WAN clone device, port 2, board 1 - 19 = /dev/sbei/wanc13 WAN clone device, port 3, board 1 - ... - - Yes, each board is really spaced 10 (decimal) apart. - - 211 char Addinum CPCI1500 digital I/O card - 0 = /dev/addinum/cpci1500/0 First CPCI1500 card - 1 = /dev/addinum/cpci1500/1 Second CPCI1500 card - ... - - 212 char LinuxTV.org DVB driver subsystem - 0 = /dev/dvb/adapter0/video0 first video decoder of first card - 1 = /dev/dvb/adapter0/audio0 first audio decoder of first card - 2 = /dev/dvb/adapter0/sec0 (obsolete/unused) - 3 = /dev/dvb/adapter0/frontend0 first frontend device of first card - 4 = /dev/dvb/adapter0/demux0 first demux device of first card - 5 = /dev/dvb/adapter0/dvr0 first digital video recoder device of first card - 6 = /dev/dvb/adapter0/ca0 first common access port of first card - 7 = /dev/dvb/adapter0/net0 first network device of first card - 8 = /dev/dvb/adapter0/osd0 first on-screen-display device of first card - 9 = /dev/dvb/adapter0/video1 second video decoder of first card - ... - 64 = /dev/dvb/adapter1/video0 first video decoder of second card - ... - 128 = /dev/dvb/adapter2/video0 first video decoder of third card - ... - 196 = /dev/dvb/adapter3/video0 first video decoder of fourth card - - 216 char Bluetooth RFCOMM TTY devices - 0 = /dev/rfcomm0 First Bluetooth RFCOMM TTY device - 1 = /dev/rfcomm1 Second Bluetooth RFCOMM TTY device - ... - - 217 char Bluetooth RFCOMM TTY devices (alternate devices) - 0 = /dev/curf0 Callout device for rfcomm0 - 1 = /dev/curf1 Callout device for rfcomm1 - ... - - 218 char The Logical Company bus Unibus/Qbus adapters - 0 = /dev/logicalco/bci/0 First bus adapter - 1 = /dev/logicalco/bci/1 First bus adapter - ... - - 219 char The Logical Company DCI-1300 digital I/O card - 0 = /dev/logicalco/dci1300/0 First DCI-1300 card - 1 = /dev/logicalco/dci1300/1 Second DCI-1300 card - ... - - 220 char Myricom Myrinet "GM" board - 0 = /dev/myricom/gm0 First Myrinet GM board - 1 = /dev/myricom/gmp0 First board "root access" - 2 = /dev/myricom/gm1 Second Myrinet GM board - 3 = /dev/myricom/gmp1 Second board "root access" - ... - - 221 char VME bus - 0 = /dev/bus/vme/m0 First master image - 1 = /dev/bus/vme/m1 Second master image - 2 = /dev/bus/vme/m2 Third master image - 3 = /dev/bus/vme/m3 Fourth master image - 4 = /dev/bus/vme/s0 First slave image - 5 = /dev/bus/vme/s1 Second slave image - 6 = /dev/bus/vme/s2 Third slave image - 7 = /dev/bus/vme/s3 Fourth slave image - 8 = /dev/bus/vme/ctl Control - - It is expected that all VME bus drivers will use the - same interface. For interface documentation see - http://www.vmelinux.org/. - - 224 char A2232 serial card - 0 = /dev/ttyY0 First A2232 port - 1 = /dev/ttyY1 Second A2232 port - ... - - 225 char A2232 serial card (alternate devices) - 0 = /dev/cuy0 Callout device for ttyY0 - 1 = /dev/cuy1 Callout device for ttyY1 - ... - - 226 char Direct Rendering Infrastructure (DRI) - 0 = /dev/dri/card0 First graphics card - 1 = /dev/dri/card1 Second graphics card - ... - - 227 char IBM 3270 terminal Unix tty access - 1 = /dev/3270/tty1 First 3270 terminal - 2 = /dev/3270/tty2 Seconds 3270 terminal - ... - - 228 char IBM 3270 terminal block-mode access - 0 = /dev/3270/tub Controlling interface - 1 = /dev/3270/tub1 First 3270 terminal - 2 = /dev/3270/tub2 Second 3270 terminal - ... - - 229 char IBM iSeries/pSeries virtual console - 0 = /dev/hvc0 First console port - 1 = /dev/hvc1 Second console port - ... - - 230 char IBM iSeries virtual tape - 0 = /dev/iseries/vt0 First virtual tape, mode 0 - 1 = /dev/iseries/vt1 Second virtual tape, mode 0 - ... - 32 = /dev/iseries/vt0l First virtual tape, mode 1 - 33 = /dev/iseries/vt1l Second virtual tape, mode 1 - ... - 64 = /dev/iseries/vt0m First virtual tape, mode 2 - 65 = /dev/iseries/vt1m Second virtual tape, mode 2 - ... - 96 = /dev/iseries/vt0a First virtual tape, mode 3 - 97 = /dev/iseries/vt1a Second virtual tape, mode 3 - ... - 128 = /dev/iseries/nvt0 First virtual tape, mode 0, no rewind - 129 = /dev/iseries/nvt1 Second virtual tape, mode 0, no rewind - ... - 160 = /dev/iseries/nvt0l First virtual tape, mode 1, no rewind - 161 = /dev/iseries/nvt1l Second virtual tape, mode 1, no rewind - ... - 192 = /dev/iseries/nvt0m First virtual tape, mode 2, no rewind - 193 = /dev/iseries/nvt1m Second virtual tape, mode 2, no rewind - ... - 224 = /dev/iseries/nvt0a First virtual tape, mode 3, no rewind - 225 = /dev/iseries/nvt1a Second virtual tape, mode 3, no rewind - ... - - "No rewind" refers to the omission of the default - automatic rewind on device close. The MTREW or MTOFFL - ioctl()'s can be used to rewind the tape regardless of - the device used to access it. - - 231 char InfiniBand - 0 = /dev/infiniband/umad0 - 1 = /dev/infiniband/umad1 - ... - 63 = /dev/infiniband/umad63 63rd InfiniBandMad device - 64 = /dev/infiniband/issm0 First InfiniBand IsSM device - 65 = /dev/infiniband/issm1 Second InfiniBand IsSM device - ... - 127 = /dev/infiniband/issm63 63rd InfiniBand IsSM device - 128 = /dev/infiniband/uverbs0 First InfiniBand verbs device - 129 = /dev/infiniband/uverbs1 Second InfiniBand verbs device - ... - 159 = /dev/infiniband/uverbs31 31st InfiniBand verbs device - - 232 char Biometric Devices - 0 = /dev/biometric/sensor0/fingerprint first fingerprint sensor on first device - 1 = /dev/biometric/sensor0/iris first iris sensor on first device - 2 = /dev/biometric/sensor0/retina first retina sensor on first device - 3 = /dev/biometric/sensor0/voiceprint first voiceprint sensor on first device - 4 = /dev/biometric/sensor0/facial first facial sensor on first device - 5 = /dev/biometric/sensor0/hand first hand sensor on first device - ... - 10 = /dev/biometric/sensor1/fingerprint first fingerprint sensor on second device - ... - 20 = /dev/biometric/sensor2/fingerprint first fingerprint sensor on third device - ... - - 233 char PathScale InfiniPath interconnect - 0 = /dev/ipath Primary device for programs (any unit) - 1 = /dev/ipath0 Access specifically to unit 0 - 2 = /dev/ipath1 Access specifically to unit 1 - ... - 4 = /dev/ipath3 Access specifically to unit 3 - 129 = /dev/ipath_sma Device used by Subnet Management Agent - 130 = /dev/ipath_diag Device used by diagnostics programs - - 234-254 char RESERVED FOR DYNAMIC ASSIGNMENT - Character devices that request a dynamic allocation of major number will - take numbers starting from 254 and downward. - - 240-254 block LOCAL/EXPERIMENTAL USE - Allocated for local/experimental use. For devices not - assigned official numbers, these ranges should be - used in order to avoid conflicting with future assignments. - - 255 char RESERVED - - 255 block RESERVED - - This major is reserved to assist the expansion to a - larger number space. No device nodes with this major - should ever be created on the filesystem. - (This is probably not true anymore, but I'll leave it - for now /Torben) - - ---LARGE MAJORS!!!!!--- - - 256 char Equinox SST multi-port serial boards - 0 = /dev/ttyEQ0 First serial port on first Equinox SST board - 127 = /dev/ttyEQ127 Last serial port on first Equinox SST board - 128 = /dev/ttyEQ128 First serial port on second Equinox SST board - ... - 1027 = /dev/ttyEQ1027 Last serial port on eighth Equinox SST board - - 256 block Resident Flash Disk Flash Translation Layer - 0 = /dev/rfda First RFD FTL layer - 16 = /dev/rfdb Second RFD FTL layer - ... - 240 = /dev/rfdp 16th RFD FTL layer - - 257 char Phoenix Technologies Cryptographic Services Driver - 0 = /dev/ptlsec Crypto Services Driver - - 257 block SSFDC Flash Translation Layer filesystem - 0 = /dev/ssfdca First SSFDC layer - 8 = /dev/ssfdcb Second SSFDC layer - 16 = /dev/ssfdcc Third SSFDC layer - 24 = /dev/ssfdcd 4th SSFDC layer - 32 = /dev/ssfdce 5th SSFDC layer - 40 = /dev/ssfdcf 6th SSFDC layer - 48 = /dev/ssfdcg 7th SSFDC layer - 56 = /dev/ssfdch 8th SSFDC layer - - 258 block ROM/Flash read-only translation layer - 0 = /dev/blockrom0 First ROM card's translation layer interface - 1 = /dev/blockrom1 Second ROM card's translation layer interface - ... - - 259 block Block Extended Major - Used dynamically to hold additional partition minor - numbers and allow large numbers of partitions per device - - 259 char FPGA configuration interfaces - 0 = /dev/icap0 First Xilinx internal configuration - 1 = /dev/icap1 Second Xilinx internal configuration - - 260 char OSD (Object-based-device) SCSI Device - 0 = /dev/osd0 First OSD Device - 1 = /dev/osd1 Second OSD Device - ... - 255 = /dev/osd255 256th OSD Device - - -Additional ``/dev/`` directory entries --------------------------------------- - -This section details additional entries that should or may exist in -the /dev directory. It is preferred that symbolic links use the same -form (absolute or relative) as is indicated here. Links are -classified as "hard" or "symbolic" depending on the preferred type of -link; if possible, the indicated type of link should be used. - -Compulsory links -++++++++++++++++ - -These links should exist on all systems: - -=============== =============== =============== =============================== -/dev/fd /proc/self/fd symbolic File descriptors -/dev/stdin fd/0 symbolic stdin file descriptor -/dev/stdout fd/1 symbolic stdout file descriptor -/dev/stderr fd/2 symbolic stderr file descriptor -/dev/nfsd socksys symbolic Required by iBCS-2 -/dev/X0R null symbolic Required by iBCS-2 -=============== =============== =============== =============================== - -Note: ``/dev/X0R`` is --. - -Recommended links -+++++++++++++++++ - -It is recommended that these links exist on all systems: - - -=============== =============== =============== =============================== -/dev/core /proc/kcore symbolic Backward compatibility -/dev/ramdisk ram0 symbolic Backward compatibility -/dev/ftape qft0 symbolic Backward compatibility -/dev/bttv0 video0 symbolic Backward compatibility -/dev/radio radio0 symbolic Backward compatibility -/dev/i2o* /dev/i2o/* symbolic Backward compatibility -/dev/scd? sr? hard Alternate SCSI CD-ROM name -=============== =============== =============== =============================== - -Locally defined links -+++++++++++++++++++++ - -The following links may be established locally to conform to the -configuration of the system. This is merely a tabulation of existing -practice, and does not constitute a recommendation. However, if they -exist, they should have the following uses. - -=============== =============== =============== =============================== -/dev/mouse mouse port symbolic Current mouse device -/dev/tape tape device symbolic Current tape device -/dev/cdrom CD-ROM device symbolic Current CD-ROM device -/dev/cdwriter CD-writer symbolic Current CD-writer device -/dev/scanner scanner symbolic Current scanner device -/dev/modem modem port symbolic Current dialout device -/dev/root root device symbolic Current root filesystem -/dev/swap swap device symbolic Current swap device -=============== =============== =============== =============================== - -``/dev/modem`` should not be used for a modem which supports dialin as -well as dialout, as it tends to cause lock file problems. If it -exists, ``/dev/modem`` should point to the appropriate primary TTY device -(the use of the alternate callout devices is deprecated). - -For SCSI devices, ``/dev/tape`` and ``/dev/cdrom`` should point to the -*cooked* devices (``/dev/st*`` and ``/dev/sr*``, respectively), whereas -``/dev/cdwriter`` and /dev/scanner should point to the appropriate generic -SCSI devices (/dev/sg*). - -``/dev/mouse`` may point to a primary serial TTY device, a hardware mouse -device, or a socket for a mouse driver program (e.g. ``/dev/gpmdata``). - -Sockets and pipes -+++++++++++++++++ - -Non-transient sockets and named pipes may exist in /dev. Common entries are: - -=============== =============== =============================================== -/dev/printer socket lpd local socket -/dev/log socket syslog local socket -/dev/gpmdata socket gpm mouse multiplexer -=============== =============== =============================================== - -Mount points -++++++++++++ - -The following names are reserved for mounting special filesystems -under /dev. These special filesystems provide kernel interfaces that -cannot be provided with standard device nodes. - -=============== =============== =============================================== -/dev/pts devpts PTY slave filesystem -/dev/shm tmpfs POSIX shared memory maintenance access -=============== =============== =============================================== - -Terminal devices ----------------- - -Terminal, or TTY devices are a special class of character devices. A -terminal device is any device that could act as a controlling terminal -for a session; this includes virtual consoles, serial ports, and -pseudoterminals (PTYs). - -All terminal devices share a common set of capabilities known as line -disciplines; these include the common terminal line discipline as well -as SLIP and PPP modes. - -All terminal devices are named similarly; this section explains the -naming and use of the various types of TTYs. Note that the naming -conventions include several historical warts; some of these are -Linux-specific, some were inherited from other systems, and some -reflect Linux outgrowing a borrowed convention. - -A hash mark (``#``) in a device name is used here to indicate a decimal -number without leading zeroes. - -Virtual consoles and the console device -+++++++++++++++++++++++++++++++++++++++ - -Virtual consoles are full-screen terminal displays on the system video -monitor. Virtual consoles are named ``/dev/tty#``, with numbering -starting at ``/dev/tty1``; ``/dev/tty0`` is the current virtual console. -``/dev/tty0`` is the device that should be used to access the system video -card on those architectures for which the frame buffer devices -(``/dev/fb*``) are not applicable. Do not use ``/dev/console`` -for this purpose. - -The console device, ``/dev/console``, is the device to which system -messages should be sent, and on which logins should be permitted in -single-user mode. Starting with Linux 2.1.71, ``/dev/console`` is managed -by the kernel; for previous versions it should be a symbolic link to -either ``/dev/tty0``, a specific virtual console such as ``/dev/tty1``, or to -a serial port primary (``tty*``, not ``cu*``) device, depending on the -configuration of the system. - -Serial ports -++++++++++++ - -Serial ports are RS-232 serial ports and any device which simulates -one, either in hardware (such as internal modems) or in software (such -as the ISDN driver.) Under Linux, each serial ports has two device -names, the primary or callin device and the alternate or callout one. -Each kind of device is indicated by a different letter. For any -letter X, the names of the devices are ``/dev/ttyX#`` and ``/dev/cux#``, -respectively; for historical reasons, ``/dev/ttyS#`` and ``/dev/ttyC#`` -correspond to ``/dev/cua#`` and ``/dev/cub#``. In the future, it should be -expected that multiple letters will be used; all letters will be upper -case for the "tty" device (e.g. ``/dev/ttyDP#``) and lower case for the -"cu" device (e.g. ``/dev/cudp#``). - -The names ``/dev/ttyQ#`` and ``/dev/cuq#`` are reserved for local use. - -The alternate devices provide for kernel-based exclusion and somewhat -different defaults than the primary devices. Their main purpose is to -allow the use of serial ports with programs with no inherent or broken -support for serial ports. Their use is deprecated, and they may be -removed from a future version of Linux. - -Arbitration of serial ports is provided by the use of lock files with -the names ``/var/lock/LCK..ttyX#``. The contents of the lock file should -be the PID of the locking process as an ASCII number. - -It is common practice to install links such as /dev/modem -which point to serial ports. In order to ensure proper locking in the -presence of these links, it is recommended that software chase -symlinks and lock all possible names; additionally, it is recommended -that a lock file be installed with the corresponding alternate -device. In order to avoid deadlocks, it is recommended that the locks -are acquired in the following order, and released in the reverse: - - 1. The symbolic link name, if any (``/var/lock/LCK..modem``) - 2. The "tty" name (``/var/lock/LCK..ttyS2``) - 3. The alternate device name (``/var/lock/LCK..cua2``) - -In the case of nested symbolic links, the lock files should be -installed in the order the symlinks are resolved. - -Under no circumstances should an application hold a lock while waiting -for another to be released. In addition, applications which attempt -to create lock files for the corresponding alternate device names -should take into account the possibility of being used on a non-serial -port TTY, for which no alternate device would exist. - -Pseudoterminals (PTYs) -++++++++++++++++++++++ - -Pseudoterminals, or PTYs, are used to create login sessions or provide -other capabilities requiring a TTY line discipline (including SLIP or -PPP capability) to arbitrary data-generation processes. Each PTY has -a master side, named ``/dev/pty[p-za-e][0-9a-f]``, and a slave side, named -``/dev/tty[p-za-e][0-9a-f]``. The kernel arbitrates the use of PTYs by -allowing each master side to be opened only once. - -Once the master side has been opened, the corresponding slave device -can be used in the same manner as any TTY device. The master and -slave devices are connected by the kernel, generating the equivalent -of a bidirectional pipe with TTY capabilities. - -Recent versions of the Linux kernels and GNU libc contain support for -the System V/Unix98 naming scheme for PTYs, which assigns a common -device, ``/dev/ptmx``, to all the masters (opening it will automatically -give you a previously unassigned PTY) and a subdirectory, ``/dev/pts``, -for the slaves; the slaves are named with decimal integers (``/dev/pts/#`` -in our notation). This removes the problem of exhausting the -namespace and enables the kernel to automatically create the device -nodes for the slaves on demand using the "devpts" filesystem. - diff --git a/Documentation/dynamic-debug-howto.txt b/Documentation/dynamic-debug-howto.txt deleted file mode 100644 index 88adcfdf5b2b..000000000000 --- a/Documentation/dynamic-debug-howto.txt +++ /dev/null @@ -1,353 +0,0 @@ -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: ``/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: -``/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' > - /dynamic_debug/control - -If you make a mistake with the syntax, the write will fail thus:: - - nullarbor:~ # echo 'file svcsock.c wtf 1 +p' > - /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 /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 /dynamic_debug/control | wc -l - 62 - - nullarbor:~ # grep -i tcp /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 != "=_"' /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' > - /dynamic_debug/control - nullarbor:~ # echo -c ' file svcsock.c line 1603 +p ' > - /dynamic_debug/control - nullarbor:~ # echo -n 'file svcsock.c line 1603 +p' > - /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" \ - > /dynamic_debug/control - -If your query set is big, you can batch them too:: - - ~# cat query-batch-file > /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" > /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" > /dynamic_debug/control - -Examples -======== - -:: - - // enable the message at line 1603 of file svcsock.c - nullarbor:~ # echo -n 'file svcsock.c line 1603 +p' > - /dynamic_debug/control - - // enable all the messages in file svcsock.c - nullarbor:~ # echo -n 'file svcsock.c +p' > - /dynamic_debug/control - - // enable all the messages in the NFS server module - nullarbor:~ # echo -n 'module nfsd +p' > - /dynamic_debug/control - - // enable all 12 messages in the function svc_process() - nullarbor:~ # echo -n 'func svc_process +p' > - /dynamic_debug/control - - // disable all 12 messages in the function svc_process() - nullarbor:~ # echo -n 'func svc_process -p' > - /dynamic_debug/control - - // enable messages for NFS calls READ, READLINK, READDIR and READDIR+. - nullarbor:~ # echo -n 'format "nfsd: READ" +p' > - /dynamic_debug/control - - // enable messages in files of which the paths include string "usb" - nullarbor:~ # echo -n '*usb* +p' > /dynamic_debug/control - - // enable all messages - nullarbor:~ # echo -n '+p' > /dynamic_debug/control - - // add module, function to all enabled messages - nullarbor:~ # echo -n '+mf' > /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" diff --git a/Documentation/index.rst b/Documentation/index.rst index e1f18b3db6e4..f6a3d4766495 100644 --- a/Documentation/index.rst +++ b/Documentation/index.rst @@ -11,6 +11,7 @@ Contents: .. toctree:: :maxdepth: 2 + admin-guide/index kernel-documentation process/index dev-tools/tools diff --git a/Documentation/init.txt b/Documentation/init.txt deleted file mode 100644 index e89d97f31eaf..000000000000 --- a/Documentation/init.txt +++ /dev/null @@ -1,52 +0,0 @@ -Explaining the dreaded "No init found." boot hang message -========================================================= - -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 -D) binary exists but dependencies not available -E) binary cannot be loaded - -Detailed explanations: - -A) Set "debug" kernel parameter (in bootloader config file or CONFIG_CMDLINE) - to get more detailed kernel messages. -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. - 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=``. -D) e.g. required library dependencies of the init binary such as - ``/lib/ld-linux.so.2`` missing or broken. Use - ``readelf -d |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 - 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 - 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). -- try to make the implementation itself more helpful in general, - e.g. by providing additional error messages at affected places. - -Andreas Mohr diff --git a/Documentation/initrd.txt b/Documentation/initrd.txt deleted file mode 100644 index a03dabaaf3a3..000000000000 --- a/Documentation/initrd.txt +++ /dev/null @@ -1,383 +0,0 @@ -Using the initial RAM disk (initrd) -=================================== - -Written 1996,2000 by Werner Almesberger and -Hans Lermen - - -initrd provides the capability to load a RAM disk by the boot loader. -This RAM disk can then be mounted as the root file system and programs -can be run from it. Afterwards, a new root file system can be mounted -from a different device. The previous root (from initrd) is then moved -to a directory and can be subsequently unmounted. - -initrd is mainly designed to allow system startup to occur in two phases, -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 [#f1]_. - - -Operation ---------- - -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) - 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 - 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 - init can do). - 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 - the usual boot sequence - 9) the initrd file system is removed - -Note that changing the root directory does not involve unmounting it. -It is therefore possible to leave processes running on initrd during that -procedure. Also note that file systems mounted under initrd continue to -be accessible. - - -Boot command-line options -------------------------- - -initrd adds the following new options:: - - initrd= (e.g. LOADLIN) - - Loads the specified file as the initial RAM disk. When using LILO, you - have to specify the RAM disk image file in /etc/lilo.conf, using the - INITRD configuration variable. - - noinitrd - - initrd data is preserved but it is not converted to a RAM disk and - the "normal" root file system is mounted. initrd data can be read - from /dev/initrd. Note that the data in initrd can have any structure - in this case and doesn't necessarily have to be a file system image. - This option is used mainly for debugging. - - Note: /dev/initrd is read-only and it can only be used once. As soon - as the last process has closed it, all data is freed and /dev/initrd - can't be opened anymore. - - root=/dev/ram0 - - initrd is mounted as root, and the normal boot procedure is followed, - with the RAM disk mounted as root. - -Compressed cpio images ----------------------- - -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):: - - find . | cpio --quiet -H newc -o | gzip -9 -n > /boot/imagefile.img - -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 - -Installation ------------- - -First, a directory for the initrd file system has to be created on the -"normal" root file system, e.g.:: - - # mkdir /initrd - -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. - -If initrd will not be mounted in some cases, its content is still -accessible if the following device has been created:: - - # 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 -needed to execute programs from initrd (e.g. executable format and file -system) must be compiled into the kernel. - -Third, you have to create the RAM disk image. This is done by creating a -file system on a block device, copying files to it as needed, and then -copying the content of the block device to the initrd file. With recent -kernels, at least three types of devices are suitable for that: - - - a floppy disk (works everywhere but it's painfully slow) - - a RAM disk (fast, but allocates physical memory) - - a loopback device (the most elegant solution) - -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 - - (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:: - - # 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:: ``/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 - - 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 - - 8) the initrd is now in the file "initrd". Optionally, it can now be - 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 [#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:: - - root=/dev/ram0 rw - -(rw is only necessary if writing to the initrd file system.) - -With LOADLIN, you simply execute:: - - LOADLIN initrd= - -e.g.:: - - LOADLIN C:\LINUX\BZIMAGE initrd=C:\LINUX\INITRD.GZ root=/dev/ram0 rw - -With LILO, you add the option ``INITRD=`` 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`` - -For other boot loaders, please refer to the respective documentation. - -Now you can boot and enjoy using initrd. - - -Changing the root device ------------------------- - -When finished with its duties, init typically changes the root device -and proceeds with starting the Linux system on the "real" root device. - -The procedure involves the following steps: - - mounting the new root file system - - turning it into the root file system - - removing all accesses to the old (initrd) root file system - - 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:: - - # 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 :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:: - - # 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:: - - # exec chroot . what-follows dev/console 2>&1 - -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``. - -Note: implementation details of pivot_root may change with time. In order -to ensure compatibility, the following points should be observed: - - - before calling pivot_root, the current directory of the invoking - process should point to the new root directory - - use . as the first argument, and the _relative_ path of the directory - for the old root as the second argument - - a chroot program must be available under the old and the new root - - chroot to the new root afterwards - - 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:: - - # umount /initrd - # blockdev --flushbufs /dev/ram0 - -It is also possible to use initrd with an NFS-mounted root, see the -:manpage:`pivot_root(8)` man page for details. - - -Usage scenarios ---------------- - -The main motivation for implementing initrd was to allow for modular -kernel configuration at system installation. The procedure would work -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 - (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 - have to be a very usable system yet) - 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 - modified, then unmounted, and finally, the image is written from - ``/dev/ram0`` or ``/dev/rd/0`` to a file) - 8) now the system is bootable and additional installation tasks can be - performed - -The key role of initrd here is to re-use the configuration data during -normal system operation without requiring the use of a bloated "generic" -kernel or re-compiling or re-linking the kernel. - -A second scenario is for installations where Linux runs on systems with -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 -read by it would have to be different. - -A third scenario is more convenient recovery disks, because information -like the location of the root FS partition doesn't have to be provided at -boot time, but the system loaded from initrd can invoke a user-friendly -dialog and it can also perform some sanity checks (or even some form of -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 -from the CD-ROM, and loading the RAM disk from CD without need of -floppies. - - -Obsolete root change mechanism ------------------------------- - -The following mechanism was used before the introduction of pivot_root. -Current kernels still support it, but you should _not_ rely on its -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 -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.:: - - # 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``. - - -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. - -``/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 - -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``. - - -Resources ---------- - -.. [#f1] Almesberger, Werner; "Booting Linux: The History and the Future" - http://www.almesberger.net/cv/papers/ols2k-9.ps.gz -.. [#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/ diff --git a/Documentation/java.txt b/Documentation/java.txt deleted file mode 100644 index ae33d959638c..000000000000 --- a/Documentation/java.txt +++ /dev/null @@ -1,418 +0,0 @@ -Java(tm) Binary Kernel Support for Linux v1.03 ----------------------------------------------- - -Linux beats them ALL! While all other OS's are TALKING about direct -support of Java Binaries in the OS, Linux is doing it! - -You can execute Java applications and Java Applets just like any -other program after you have done the following: - -1) You MUST FIRST install the Java Developers Kit for Linux. - The Java on Linux HOWTO gives the details on getting and - installing this. This HOWTO can be found at: - - ftp://sunsite.unc.edu/pub/Linux/docs/HOWTO/Java-HOWTO - - You should also set up a reasonable CLASSPATH environment - variable to use Java applications that make use of any - nonstandard classes (not included in the same directory - as the application itself). - -2) You have to compile BINFMT_MISC either as a module or into - the kernel (``CONFIG_BINFMT_MISC``) and set it up properly. - If you choose to compile it as a module, you will have - to insert it manually with modprobe/insmod, as kmod - cannot easily be supported with binfmt_misc. - Read the file 'binfmt_misc.txt' in this directory to know - more about the configuration process. - -3) Add the following configuration items to binfmt_misc - (you should really have read ``binfmt_misc.txt`` now): - support for Java applications:: - - ':Java:M::\xca\xfe\xba\xbe::/usr/local/bin/javawrapper:' - - support for executable Jar files:: - - ':ExecutableJAR:E::jar::/usr/local/bin/jarwrapper:' - - support for Java Applets:: - - ':Applet:E::html::/usr/bin/appletviewer:' - - or the following, if you want to be more selective:: - - ':Applet:M::`` in the first line - (``<`` has to be the first character!) to let this work! - - For the compiled Java programs you need a wrapper script like the - following (this is because Java is broken in case of the filename - handling), again fix the path names, both in the script and in the - above given configuration string. - - You, too, need the little program after the script. Compile like:: - - gcc -O2 -o javaclassname javaclassname.c - - and stick it to ``/usr/local/bin``. - - Both the javawrapper shellscript and the javaclassname program - were supplied by Colin J. Watson . - -Javawrapper shell script:: - - #!/bin/bash - # /usr/local/bin/javawrapper - the wrapper for binfmt_misc/java - - if [ -z "$1" ]; then - exec 1>&2 - echo Usage: $0 class-file - exit 1 - fi - - CLASS=$1 - FQCLASS=`/usr/local/bin/javaclassname $1` - FQCLASSN=`echo $FQCLASS | sed -e 's/^.*\.\([^.]*\)$/\1/'` - FQCLASSP=`echo $FQCLASS | sed -e 's-\.-/-g' -e 's-^[^/]*$--' -e 's-/[^/]*$--'` - - # for example: - # CLASS=Test.class - # FQCLASS=foo.bar.Test - # FQCLASSN=Test - # FQCLASSP=foo/bar - - unset CLASSBASE - - declare -i LINKLEVEL=0 - - while :; do - if [ "`basename $CLASS .class`" == "$FQCLASSN" ]; then - # See if this directory works straight off - cd -L `dirname $CLASS` - CLASSDIR=$PWD - cd $OLDPWD - if echo $CLASSDIR | grep -q "$FQCLASSP$"; then - CLASSBASE=`echo $CLASSDIR | sed -e "s.$FQCLASSP$.."` - break; - fi - # Try dereferencing the directory name - cd -P `dirname $CLASS` - CLASSDIR=$PWD - cd $OLDPWD - if echo $CLASSDIR | grep -q "$FQCLASSP$"; then - CLASSBASE=`echo $CLASSDIR | sed -e "s.$FQCLASSP$.."` - break; - fi - # If no other possible filename exists - if [ ! -L $CLASS ]; then - exec 1>&2 - echo $0: - echo " $CLASS should be in a" \ - "directory tree called $FQCLASSP" - exit 1 - fi - fi - if [ ! -L $CLASS ]; then break; fi - # Go down one more level of symbolic links - let LINKLEVEL+=1 - if [ $LINKLEVEL -gt 5 ]; then - exec 1>&2 - echo $0: - echo " Too many symbolic links encountered" - exit 1 - fi - CLASS=`ls --color=no -l $CLASS | sed -e 's/^.* \([^ ]*\)$/\1/'` - done - - if [ -z "$CLASSBASE" ]; then - if [ -z "$FQCLASSP" ]; then - GOODNAME=$FQCLASSN.class - else - GOODNAME=$FQCLASSP/$FQCLASSN.class - fi - exec 1>&2 - echo $0: - echo " $FQCLASS should be in a file called $GOODNAME" - exit 1 - fi - - if ! echo $CLASSPATH | grep -q "^\(.*:\)*$CLASSBASE\(:.*\)*"; then - # class is not in CLASSPATH, so prepend dir of class to CLASSPATH - if [ -z "${CLASSPATH}" ] ; then - export CLASSPATH=$CLASSBASE - else - export CLASSPATH=$CLASSBASE:$CLASSPATH - fi - fi - - shift - /usr/bin/java $FQCLASS "$@" - -javaclassname.c:: - - /* javaclassname.c - * - * Extracts the class name from a Java class file; intended for use in a Java - * wrapper of the type supported by the binfmt_misc option in the Linux kernel. - * - * Copyright (C) 1999 Colin J. Watson . - * - * This program is free software; you can redistribute it and/or modify - * it under the terms of the GNU General Public License as published by - * the Free Software Foundation; either version 2 of the License, or - * (at your option) any later version. - * - * This program is distributed in the hope that it will be useful, - * but WITHOUT ANY WARRANTY; without even the implied warranty of - * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the - * GNU General Public License for more details. - * - * You should have received a copy of the GNU General Public License - * along with this program; if not, write to the Free Software - * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA - */ - - #include - #include - #include - #include - - /* From Sun's Java VM Specification, as tag entries in the constant pool. */ - - #define CP_UTF8 1 - #define CP_INTEGER 3 - #define CP_FLOAT 4 - #define CP_LONG 5 - #define CP_DOUBLE 6 - #define CP_CLASS 7 - #define CP_STRING 8 - #define CP_FIELDREF 9 - #define CP_METHODREF 10 - #define CP_INTERFACEMETHODREF 11 - #define CP_NAMEANDTYPE 12 - #define CP_METHODHANDLE 15 - #define CP_METHODTYPE 16 - #define CP_INVOKEDYNAMIC 18 - - /* Define some commonly used error messages */ - - #define seek_error() error("%s: Cannot seek\n", program) - #define corrupt_error() error("%s: Class file corrupt\n", program) - #define eof_error() error("%s: Unexpected end of file\n", program) - #define utf8_error() error("%s: Only ASCII 1-255 supported\n", program); - - char *program; - - long *pool; - - u_int8_t read_8(FILE *classfile); - u_int16_t read_16(FILE *classfile); - void skip_constant(FILE *classfile, u_int16_t *cur); - void error(const char *format, ...); - int main(int argc, char **argv); - - /* Reads in an unsigned 8-bit integer. */ - u_int8_t read_8(FILE *classfile) - { - int b = fgetc(classfile); - if(b == EOF) - eof_error(); - return (u_int8_t)b; - } - - /* Reads in an unsigned 16-bit integer. */ - u_int16_t read_16(FILE *classfile) - { - int b1, b2; - b1 = fgetc(classfile); - if(b1 == EOF) - eof_error(); - b2 = fgetc(classfile); - if(b2 == EOF) - eof_error(); - return (u_int16_t)((b1 << 8) | b2); - } - - /* Reads in a value from the constant pool. */ - void skip_constant(FILE *classfile, u_int16_t *cur) - { - u_int16_t len; - int seekerr = 1; - pool[*cur] = ftell(classfile); - switch(read_8(classfile)) - { - case CP_UTF8: - len = read_16(classfile); - seekerr = fseek(classfile, len, SEEK_CUR); - break; - case CP_CLASS: - case CP_STRING: - case CP_METHODTYPE: - seekerr = fseek(classfile, 2, SEEK_CUR); - break; - case CP_METHODHANDLE: - seekerr = fseek(classfile, 3, SEEK_CUR); - break; - case CP_INTEGER: - case CP_FLOAT: - case CP_FIELDREF: - case CP_METHODREF: - case CP_INTERFACEMETHODREF: - case CP_NAMEANDTYPE: - case CP_INVOKEDYNAMIC: - seekerr = fseek(classfile, 4, SEEK_CUR); - break; - case CP_LONG: - case CP_DOUBLE: - seekerr = fseek(classfile, 8, SEEK_CUR); - ++(*cur); - break; - default: - corrupt_error(); - } - if(seekerr) - seek_error(); - } - - void error(const char *format, ...) - { - va_list ap; - va_start(ap, format); - vfprintf(stderr, format, ap); - va_end(ap); - exit(1); - } - - int main(int argc, char **argv) - { - FILE *classfile; - u_int16_t cp_count, i, this_class, classinfo_ptr; - u_int8_t length; - - program = argv[0]; - - if(!argv[1]) - error("%s: Missing input file\n", program); - classfile = fopen(argv[1], "rb"); - if(!classfile) - error("%s: Error opening %s\n", program, argv[1]); - - if(fseek(classfile, 8, SEEK_SET)) /* skip magic and version numbers */ - seek_error(); - cp_count = read_16(classfile); - pool = calloc(cp_count, sizeof(long)); - if(!pool) - error("%s: Out of memory for constant pool\n", program); - - for(i = 1; i < cp_count; ++i) - skip_constant(classfile, &i); - if(fseek(classfile, 2, SEEK_CUR)) /* skip access flags */ - seek_error(); - - this_class = read_16(classfile); - if(this_class < 1 || this_class >= cp_count) - corrupt_error(); - if(!pool[this_class] || pool[this_class] == -1) - corrupt_error(); - if(fseek(classfile, pool[this_class] + 1, SEEK_SET)) - seek_error(); - - classinfo_ptr = read_16(classfile); - if(classinfo_ptr < 1 || classinfo_ptr >= cp_count) - corrupt_error(); - if(!pool[classinfo_ptr] || pool[classinfo_ptr] == -1) - corrupt_error(); - if(fseek(classfile, pool[classinfo_ptr] + 1, SEEK_SET)) - seek_error(); - - length = read_16(classfile); - for(i = 0; i < length; ++i) - { - u_int8_t x = read_8(classfile); - if((x & 0x80) || !x) - { - if((x & 0xE0) == 0xC0) - { - u_int8_t y = read_8(classfile); - if((y & 0xC0) == 0x80) - { - int c = ((x & 0x1f) << 6) + (y & 0x3f); - if(c) putchar(c); - else utf8_error(); - } - else utf8_error(); - } - else utf8_error(); - } - else if(x == '/') putchar('.'); - else putchar(x); - } - putchar('\n'); - free(pool); - fclose(classfile); - return 0; - } - -jarwrapper:: - - #!/bin/bash - # /usr/local/java/bin/jarwrapper - the wrapper for binfmt_misc/jar - - java -jar $1 - - -Now simply ``chmod +x`` the ``.class``, ``.jar`` and/or ``.html`` files you -want to execute. - -To add a Java program to your path best put a symbolic link to the main -.class file into /usr/bin (or another place you like) omitting the .class -extension. The directory containing the original .class file will be -added to your CLASSPATH during execution. - - -To test your new setup, enter in the following simple Java app, and name -it "HelloWorld.java":: - - class HelloWorld { - public static void main(String args[]) { - System.out.println("Hello World!"); - } - } - -Now compile the application with:: - - javac HelloWorld.java - -Set the executable permissions of the binary file, with:: - - chmod 755 HelloWorld.class - -And then execute it:: - - ./HelloWorld.class - - -To execute Java Jar files, simple chmod the ``*.jar`` files to include -the execution bit, then just do:: - - ./Application.jar - - -To execute Java Applets, simple chmod the ``*.html`` files to include -the execution bit, then just do:: - - ./Applet.html - - -originally by Brian A. Lantz, brian@lantz.com -heavily edited for binfmt_misc by Richard Günther -new scripts by Colin J. Watson -added executable Jar file support by Kurt Huwig - diff --git a/Documentation/kernel-parameters.txt b/Documentation/kernel-parameters.txt deleted file mode 100644 index b0804273b6e3..000000000000 --- a/Documentation/kernel-parameters.txt +++ /dev/null @@ -1,4577 +0,0 @@ -Kernel Parameters -~~~~~~~~~~~~~~~~~ - -The following is a consolidated list of the kernel parameters as -implemented by the __setup(), core_param() and module_param() macros -and sorted into English Dictionary order (defined as ignoring all -punctuation and sorting digits before letters in a case insensitive -manner), and with descriptions where known. - -The kernel parses parameters from the kernel command line up to "--"; -if it doesn't recognize a parameter and it doesn't contain a '.', the -parameter gets passed to init: parameters with '=' go into init's -environment, others are passed as command line arguments to init. -Everything after "--" is passed as an argument to init. - -Module parameters can be specified in two ways: via the kernel command -line with a module name prefix, or via modprobe, e.g.:: - - (kernel command line) usbcore.blinkenlights=1 - (modprobe command line) modprobe usbcore blinkenlights=1 - -Parameters for modules which are built into the kernel need to be -specified on the kernel command line. modprobe looks through the -kernel command line (/proc/cmdline) and collects module parameters -when it loads a module, so the kernel command line can be used for -loadable modules too. - -Hyphens (dashes) and underscores are equivalent in parameter names, so:: - - log_buf_len=1M print-fatal-signals=1 - -can also be entered as:: - - log-buf-len=1M print_fatal_signals=1 - -Double-quotes can be used to protect spaces in values, e.g.:: - - param="spaces in here" - -cpu lists: ----------- - -Some kernel parameters take a list of CPUs as a value, e.g. isolcpus, -nohz_full, irqaffinity, rcu_nocbs. The format of this list is: - - ,..., - -or - - - - (must be a positive range in ascending order) - -or a mixture - -,...,- - -Note that for the special case of a range one can split the range into equal -sized groups and for each group use some amount from the beginning of that -group: - - -cpu number>:/ - -For example one can add to the command line following parameter: - - isolcpus=1,2,10-20,100-2000:2/25 - -where the final item represents CPUs 100,101,125,126,150,151,... - - - -This document may not be entirely up to date and comprehensive. The command -"modinfo -p ${modulename}" shows a current list of all parameters of a loadable -module. Loadable modules, after being loaded into the running kernel, also -reveal their parameters in /sys/module/${modulename}/parameters/. Some of these -parameters may be changed at runtime by the command -``echo -n ${value} > /sys/module/${modulename}/parameters/${parm}``. - -The parameters listed below are only valid if certain kernel build options were -enabled and if respective hardware is present. The text in square brackets at -the beginning of each description states the restrictions within which a -parameter is applicable:: - - ACPI ACPI support is enabled. - AGP AGP (Accelerated Graphics Port) is enabled. - ALSA ALSA sound support is enabled. - APIC APIC support is enabled. - APM Advanced Power Management support is enabled. - ARM ARM architecture is enabled. - AVR32 AVR32 architecture is enabled. - AX25 Appropriate AX.25 support is enabled. - BLACKFIN Blackfin architecture is enabled. - CLK Common clock infrastructure is enabled. - CMA Contiguous Memory Area support is enabled. - DRM Direct Rendering Management support is enabled. - DYNAMIC_DEBUG Build in debug messages and enable them at runtime - EDD BIOS Enhanced Disk Drive Services (EDD) is enabled - EFI EFI Partitioning (GPT) is enabled - EIDE EIDE/ATAPI support is enabled. - EVM Extended Verification Module - FB The frame buffer device is enabled. - FTRACE Function tracing enabled. - GCOV GCOV profiling is enabled. - HW Appropriate hardware is enabled. - IA-64 IA-64 architecture is enabled. - IMA Integrity measurement architecture is enabled. - IOSCHED More than one I/O scheduler is enabled. - IP_PNP IP DHCP, BOOTP, or RARP is enabled. - IPV6 IPv6 support is enabled. - ISAPNP ISA PnP code is enabled. - ISDN Appropriate ISDN support is enabled. - JOY Appropriate joystick support is enabled. - KGDB Kernel debugger support is enabled. - KVM Kernel Virtual Machine support is enabled. - LIBATA Libata driver is enabled - LP Printer support is enabled. - LOOP Loopback device support is enabled. - M68k M68k architecture is enabled. - These options have more detailed description inside of - Documentation/m68k/kernel-options.txt. - MDA MDA console support is enabled. - MIPS MIPS architecture is enabled. - MOUSE Appropriate mouse support is enabled. - MSI Message Signaled Interrupts (PCI). - MTD MTD (Memory Technology Device) support is enabled. - NET Appropriate network support is enabled. - NUMA NUMA support is enabled. - NFS Appropriate NFS support is enabled. - OSS OSS sound support is enabled. - PV_OPS A paravirtualized kernel is enabled. - PARIDE The ParIDE (parallel port IDE) subsystem is enabled. - PARISC The PA-RISC architecture is enabled. - PCI PCI bus support is enabled. - PCIE PCI Express support is enabled. - PCMCIA The PCMCIA subsystem is enabled. - PNP Plug & Play support is enabled. - PPC PowerPC architecture is enabled. - PPT Parallel port support is enabled. - PS2 Appropriate PS/2 support is enabled. - RAM RAM disk support is enabled. - S390 S390 architecture is enabled. - SCSI Appropriate SCSI support is enabled. - A lot of drivers have their options described inside - the Documentation/scsi/ sub-directory. - SECURITY Different security models are enabled. - SELINUX SELinux support is enabled. - APPARMOR AppArmor support is enabled. - SERIAL Serial support is enabled. - SH SuperH architecture is enabled. - SMP The kernel is an SMP kernel. - SPARC Sparc architecture is enabled. - SWSUSP Software suspend (hibernation) is enabled. - SUSPEND System suspend states are enabled. - TPM TPM drivers are enabled. - TS Appropriate touchscreen support is enabled. - UMS USB Mass Storage support is enabled. - USB USB support is enabled. - USBHID USB Human Interface Device support is enabled. - V4L Video For Linux support is enabled. - VMMIO Driver for memory mapped virtio devices is enabled. - VGA The VGA console has been enabled. - VT Virtual terminal support is enabled. - WDT Watchdog support is enabled. - XT IBM PC/XT MFM hard disk support is enabled. - X86-32 X86-32, aka i386 architecture is enabled. - X86-64 X86-64 architecture is enabled. - More X86-64 boot options can be found in - Documentation/x86/x86_64/boot-options.txt . - X86 Either 32-bit or 64-bit x86 (same as X86-32+X86-64) - X86_UV SGI UV support is enabled. - XEN Xen support is enabled - -In addition, the following text indicates that the option:: - - BUGS= Relates to possible processor bugs on the said processor. - KNL Is a kernel start-up parameter. - BOOT Is a boot loader parameter. - -Parameters denoted with BOOT are actually interpreted by the boot -loader, and have no meaning to the kernel directly. -Do not modify the syntax of boot loader parameters without extreme -need or coordination with . - -There are also arch-specific kernel-parameters not documented here. -See for example . - -Note that ALL kernel parameters listed below are CASE SENSITIVE, and that -a trailing = on the name of any parameter states that that parameter will -be entered as an environment variable, whereas its absence indicates that -it will appear as a kernel argument readable via /proc/cmdline by programs -running once the system is up. - -The number of kernel parameters is not limited, but the length of the -complete command line (parameters including spaces etc.) is limited to -a fixed number of characters. This limit depends on the architecture -and is between 256 and 4096 characters. It is defined in the file -./include/asm/setup.h as COMMAND_LINE_SIZE. - -Finally, the [KMG] suffix is commonly described after a number of kernel -parameter values. These 'K', 'M', and 'G' letters represent the _binary_ -multipliers 'Kilo', 'Mega', and 'Giga', equalling 2^10, 2^20, and 2^30 -bytes respectively. Such letter suffixes can also be entirely omitted:: - - - acpi= [HW,ACPI,X86,ARM64] - Advanced Configuration and Power Interface - Format: { force | on | off | strict | noirq | rsdt | - copy_dsdt } - force -- enable ACPI if default was off - on -- enable ACPI but allow fallback to DT [arm64] - off -- disable ACPI if default was on - noirq -- do not use ACPI for IRQ routing - strict -- Be less tolerant of platforms that are not - strictly ACPI specification compliant. - rsdt -- prefer RSDT over (default) XSDT - copy_dsdt -- copy DSDT to memory - For ARM64, ONLY "acpi=off", "acpi=on" or "acpi=force" - are available - - See also Documentation/power/runtime_pm.txt, pci=noacpi - - acpi_apic_instance= [ACPI, IOAPIC] - Format: - 2: use 2nd APIC table, if available - 1,0: use 1st APIC table - default: 0 - - acpi_backlight= [HW,ACPI] - acpi_backlight=vendor - acpi_backlight=video - If set to vendor, prefer vendor specific driver - (e.g. thinkpad_acpi, sony_acpi, etc.) instead - of the ACPI video.ko driver. - - acpi_force_32bit_fadt_addr - force FADT to use 32 bit addresses rather than the - 64 bit X_* addresses. Some firmware have broken 64 - bit addresses for force ACPI ignore these and use - the older legacy 32 bit addresses. - - acpica_no_return_repair [HW, ACPI] - Disable AML predefined validation mechanism - This mechanism can repair the evaluation result to make - the return objects more ACPI specification compliant. - This option is useful for developers to identify the - root cause of an AML interpreter issue when the issue - has something to do with the repair mechanism. - - acpi.debug_layer= [HW,ACPI,ACPI_DEBUG] - acpi.debug_level= [HW,ACPI,ACPI_DEBUG] - Format: - CONFIG_ACPI_DEBUG must be enabled to produce any ACPI - debug output. Bits in debug_layer correspond to a - _COMPONENT in an ACPI source file, e.g., - #define _COMPONENT ACPI_PCI_COMPONENT - Bits in debug_level correspond to a level in - ACPI_DEBUG_PRINT statements, e.g., - ACPI_DEBUG_PRINT((ACPI_DB_INFO, ... - The debug_level mask defaults to "info". See - Documentation/acpi/debug.txt for more information about - debug layers and levels. - - Enable processor driver info messages: - acpi.debug_layer=0x20000000 - Enable PCI/PCI interrupt routing info messages: - acpi.debug_layer=0x400000 - Enable AML "Debug" output, i.e., stores to the Debug - object while interpreting AML: - acpi.debug_layer=0xffffffff acpi.debug_level=0x2 - Enable all messages related to ACPI hardware: - acpi.debug_layer=0x2 acpi.debug_level=0xffffffff - - Some values produce so much output that the system is - unusable. The "log_buf_len" parameter may be useful - if you need to capture more output. - - acpi_enforce_resources= [ACPI] - { strict | lax | no } - Check for resource conflicts between native drivers - and ACPI OperationRegions (SystemIO and SystemMemory - only). IO ports and memory declared in ACPI might be - used by the ACPI subsystem in arbitrary AML code and - can interfere with legacy drivers. - strict (default): access to resources claimed by ACPI - is denied; legacy drivers trying to access reserved - resources will fail to bind to device using them. - lax: access to resources claimed by ACPI is allowed; - legacy drivers trying to access reserved resources - will bind successfully but a warning message is logged. - no: ACPI OperationRegions are not marked as reserved, - no further checks are performed. - - acpi_force_table_verification [HW,ACPI] - Enable table checksum verification during early stage. - By default, this is disabled due to x86 early mapping - size limitation. - - acpi_irq_balance [HW,ACPI] - ACPI will balance active IRQs - default in APIC mode - - acpi_irq_nobalance [HW,ACPI] - ACPI will not move active IRQs (default) - default in PIC mode - - acpi_irq_isa= [HW,ACPI] If irq_balance, mark listed IRQs used by ISA - Format: ,... - - acpi_irq_pci= [HW,ACPI] If irq_balance, clear listed IRQs for - use by PCI - Format: ,... - - acpi_no_auto_serialize [HW,ACPI] - Disable auto-serialization of AML methods - AML control methods that contain the opcodes to create - named objects will be marked as "Serialized" by the - auto-serialization feature. - This feature is enabled by default. - This option allows to turn off the feature. - - acpi_no_memhotplug [ACPI] Disable memory hotplug. Useful for kdump - kernels. - - acpi_no_static_ssdt [HW,ACPI] - Disable installation of static SSDTs at early boot time - By default, SSDTs contained in the RSDT/XSDT will be - installed automatically and they will appear under - /sys/firmware/acpi/tables. - This option turns off this feature. - Note that specifying this option does not affect - dynamic table installation which will install SSDT - tables to /sys/firmware/acpi/tables/dynamic. - - acpi_rsdp= [ACPI,EFI,KEXEC] - Pass the RSDP address to the kernel, mostly used - on machines running EFI runtime service to boot the - second kernel for kdump. - - acpi_os_name= [HW,ACPI] Tell ACPI BIOS the name of the OS - Format: To spoof as Windows 98: ="Microsoft Windows" - - acpi_rev_override [ACPI] Override the _REV object to return 5 (instead - of 2 which is mandated by ACPI 6) as the supported ACPI - specification revision (when using this switch, it may - be necessary to carry out a cold reboot _twice_ in a - row to make it take effect on the platform firmware). - - acpi_osi= [HW,ACPI] Modify list of supported OS interface strings - acpi_osi="string1" # add string1 - acpi_osi="!string2" # remove string2 - acpi_osi=!* # remove all strings - acpi_osi=! # disable all built-in OS vendor - strings - acpi_osi=!! # enable all built-in OS vendor - strings - acpi_osi= # disable all strings - - 'acpi_osi=!' can be used in combination with single or - multiple 'acpi_osi="string1"' to support specific OS - vendor string(s). Note that such command can only - affect the default state of the OS vendor strings, thus - it cannot affect the default state of the feature group - strings and the current state of the OS vendor strings, - specifying it multiple times through kernel command line - is meaningless. This command is useful when one do not - care about the state of the feature group strings which - should be controlled by the OSPM. - Examples: - 1. 'acpi_osi=! acpi_osi="Windows 2000"' is equivalent - to 'acpi_osi="Windows 2000" acpi_osi=!', they all - can make '_OSI("Windows 2000")' TRUE. - - 'acpi_osi=' cannot be used in combination with other - 'acpi_osi=' command lines, the _OSI method will not - exist in the ACPI namespace. NOTE that such command can - only affect the _OSI support state, thus specifying it - multiple times through kernel command line is also - meaningless. - Examples: - 1. 'acpi_osi=' can make 'CondRefOf(_OSI, Local1)' - FALSE. - - 'acpi_osi=!*' can be used in combination with single or - multiple 'acpi_osi="string1"' to support specific - string(s). Note that such command can affect the - current state of both the OS vendor strings and the - feature group strings, thus specifying it multiple times - through kernel command line is meaningful. But it may - still not able to affect the final state of a string if - there are quirks related to this string. This command - is useful when one want to control the state of the - feature group strings to debug BIOS issues related to - the OSPM features. - Examples: - 1. 'acpi_osi="Module Device" acpi_osi=!*' can make - '_OSI("Module Device")' FALSE. - 2. 'acpi_osi=!* acpi_osi="Module Device"' can make - '_OSI("Module Device")' TRUE. - 3. 'acpi_osi=! acpi_osi=!* acpi_osi="Windows 2000"' is - equivalent to - 'acpi_osi=!* acpi_osi=! acpi_osi="Windows 2000"' - and - 'acpi_osi=!* acpi_osi="Windows 2000" acpi_osi=!', - they all will make '_OSI("Windows 2000")' TRUE. - - acpi_pm_good [X86] - Override the pmtimer bug detection: force the kernel - to assume that this machine's pmtimer latches its value - and always returns good values. - - acpi_sci= [HW,ACPI] ACPI System Control Interrupt trigger mode - Format: { level | edge | high | low } - - acpi_skip_timer_override [HW,ACPI] - Recognize and ignore IRQ0/pin2 Interrupt Override. - For broken nForce2 BIOS resulting in XT-PIC timer. - - acpi_sleep= [HW,ACPI] Sleep options - Format: { s3_bios, s3_mode, s3_beep, s4_nohwsig, - old_ordering, nonvs, sci_force_enable } - See Documentation/power/video.txt for information on - s3_bios and s3_mode. - s3_beep is for debugging; it makes the PC's speaker beep - as soon as the kernel's real-mode entry point is called. - s4_nohwsig prevents ACPI hardware signature from being - used during resume from hibernation. - old_ordering causes the ACPI 1.0 ordering of the _PTS - control method, with respect to putting devices into - low power states, to be enforced (the ACPI 2.0 ordering - of _PTS is used by default). - nonvs prevents the kernel from saving/restoring the - ACPI NVS memory during suspend/hibernation and resume. - sci_force_enable causes the kernel to set SCI_EN directly - on resume from S1/S3 (which is against the ACPI spec, - but some broken systems don't work without it). - - acpi_use_timer_override [HW,ACPI] - Use timer override. For some broken Nvidia NF5 boards - that require a timer override, but don't have HPET - - add_efi_memmap [EFI; X86] Include EFI memory map in - kernel's map of available physical RAM. - - agp= [AGP] - { off | try_unsupported } - off: disable AGP support - try_unsupported: try to drive unsupported chipsets - (may crash computer or cause data corruption) - - ALSA [HW,ALSA] - See Documentation/sound/alsa/alsa-parameters.txt - - alignment= [KNL,ARM] - Allow the default userspace alignment fault handler - behaviour to be specified. Bit 0 enables warnings, - bit 1 enables fixups, and bit 2 sends a segfault. - - align_va_addr= [X86-64] - Align virtual addresses by clearing slice [14:12] when - allocating a VMA at process creation time. This option - gives you up to 3% performance improvement on AMD F15h - machines (where it is enabled by default) for a - CPU-intensive style benchmark, and it can vary highly in - a microbenchmark depending on workload and compiler. - - 32: only for 32-bit processes - 64: only for 64-bit processes - on: enable for both 32- and 64-bit processes - off: disable for both 32- and 64-bit processes - - alloc_snapshot [FTRACE] - Allocate the ftrace snapshot buffer on boot up when the - main buffer is allocated. This is handy if debugging - and you need to use tracing_snapshot() on boot up, and - do not want to use tracing_snapshot_alloc() as it needs - to be done where GFP_KERNEL allocations are allowed. - - amd_iommu= [HW,X86-64] - Pass parameters to the AMD IOMMU driver in the system. - Possible values are: - fullflush - enable flushing of IO/TLB entries when - they are unmapped. Otherwise they are - flushed before they will be reused, which - is a lot of faster - off - do not initialize any AMD IOMMU found in - the system - force_isolation - Force device isolation for all - devices. The IOMMU driver is not - allowed anymore to lift isolation - requirements as needed. This option - does not override iommu=pt - - amd_iommu_dump= [HW,X86-64] - Enable AMD IOMMU driver option to dump the ACPI table - for AMD IOMMU. With this option enabled, AMD IOMMU - driver will print ACPI tables for AMD IOMMU during - IOMMU initialization. - - amd_iommu_intr= [HW,X86-64] - Specifies one of the following AMD IOMMU interrupt - remapping modes: - legacy - Use legacy interrupt remapping mode. - vapic - Use virtual APIC mode, which allows IOMMU - to inject interrupts directly into guest. - This mode requires kvm-amd.avic=1. - (Default when IOMMU HW support is present.) - - amijoy.map= [HW,JOY] Amiga joystick support - Map of devices attached to JOY0DAT and JOY1DAT - Format: , - See also Documentation/input/joystick.txt - - analog.map= [HW,JOY] Analog joystick and gamepad support - Specifies type or capabilities of an analog joystick - connected to one of 16 gameports - Format: ,,.. - - apc= [HW,SPARC] - Power management functions (SPARCstation-4/5 + deriv.) - Format: noidle - Disable APC CPU standby support. SPARCstation-Fox does - not play well with APC CPU idle - disable it if you have - APC and your system crashes randomly. - - apic= [APIC,X86-32] Advanced Programmable Interrupt Controller - Change the output verbosity whilst booting - Format: { quiet (default) | verbose | debug } - Change the amount of debugging information output - when initialising the APIC and IO-APIC components. - - apic_extnmi= [APIC,X86] External NMI delivery setting - Format: { bsp (default) | all | none } - bsp: External NMI is delivered only to CPU 0 - all: External NMIs are broadcast to all CPUs as a - backup of CPU 0 - none: External NMI is masked for all CPUs. This is - useful so that a dump capture kernel won't be - shot down by NMI - - autoconf= [IPV6] - See Documentation/networking/ipv6.txt. - - show_lapic= [APIC,X86] Advanced Programmable Interrupt Controller - Limit apic dumping. The parameter defines the maximal - number of local apics being dumped. Also it is possible - to set it to "all" by meaning -- no limit here. - Format: { 1 (default) | 2 | ... | all }. - The parameter valid if only apic=debug or - apic=verbose is specified. - Example: apic=debug show_lapic=all - - apm= [APM] Advanced Power Management - See header of arch/x86/kernel/apm_32.c. - - arcrimi= [HW,NET] ARCnet - "RIM I" (entirely mem-mapped) cards - Format: ,, - - ataflop= [HW,M68k] - - atarimouse= [HW,MOUSE] Atari Mouse - - atkbd.extra= [HW] Enable extra LEDs and keys on IBM RapidAccess, - EzKey and similar keyboards - - atkbd.reset= [HW] Reset keyboard during initialization - - atkbd.set= [HW] Select keyboard code set - Format: (2 = AT (default), 3 = PS/2) - - atkbd.scroll= [HW] Enable scroll wheel on MS Office and similar - keyboards - - atkbd.softraw= [HW] Choose between synthetic and real raw mode - Format: (0 = real, 1 = synthetic (default)) - - atkbd.softrepeat= [HW] - Use software keyboard repeat - - audit= [KNL] Enable the audit sub-system - Format: { "0" | "1" } (0 = disabled, 1 = enabled) - 0 - kernel audit is disabled and can not be enabled - until the next reboot - unset - kernel audit is initialized but disabled and - will be fully enabled by the userspace auditd. - 1 - kernel audit is initialized and partially enabled, - storing at most audit_backlog_limit messages in - RAM until it is fully enabled by the userspace - auditd. - Default: unset - - audit_backlog_limit= [KNL] Set the audit queue size limit. - Format: (must be >=0) - Default: 64 - - bau= [X86_UV] Enable the BAU on SGI UV. The default - behavior is to disable the BAU (i.e. bau=0). - Format: { "0" | "1" } - 0 - Disable the BAU. - 1 - Enable the BAU. - unset - Disable the BAU. - - baycom_epp= [HW,AX25] - Format: , - - baycom_par= [HW,AX25] BayCom Parallel Port AX.25 Modem - Format: , - See header of drivers/net/hamradio/baycom_par.c. - - baycom_ser_fdx= [HW,AX25] - BayCom Serial Port AX.25 Modem (Full Duplex Mode) - Format: ,,[,] - See header of drivers/net/hamradio/baycom_ser_fdx.c. - - baycom_ser_hdx= [HW,AX25] - BayCom Serial Port AX.25 Modem (Half Duplex Mode) - Format: ,, - See header of drivers/net/hamradio/baycom_ser_hdx.c. - - blkdevparts= Manual partition parsing of block device(s) for - embedded devices based on command line input. - See Documentation/block/cmdline-partition.txt - - boot_delay= Milliseconds to delay each printk during boot. - Values larger than 10 seconds (10000) are changed to - no delay (0). - Format: integer - - bootmem_debug [KNL] Enable bootmem allocator debug messages. - - bert_disable [ACPI] - Disable BERT OS support on buggy BIOSes. - - bttv.card= [HW,V4L] bttv (bt848 + bt878 based grabber cards) - bttv.radio= Most important insmod options are available as - kernel args too. - bttv.pll= See Documentation/video4linux/bttv/Insmod-options - bttv.tuner= - - bulk_remove=off [PPC] This parameter disables the use of the pSeries - firmware feature for flushing multiple hpte entries - at a time. - - c101= [NET] Moxa C101 synchronous serial card - - cachesize= [BUGS=X86-32] Override level 2 CPU cache size detection. - Sometimes CPU hardware bugs make them report the cache - size incorrectly. The kernel will attempt work arounds - to fix known problems, but for some CPUs it is not - possible to determine what the correct size should be. - This option provides an override for these situations. - - ca_keys= [KEYS] This parameter identifies a specific key(s) on - the system trusted keyring to be used for certificate - trust validation. - format: { id: | builtin } - - cca= [MIPS] Override the kernel pages' cache coherency - algorithm. Accepted values range from 0 to 7 - inclusive. See arch/mips/include/asm/pgtable-bits.h - for platform specific values (SB1, Loongson3 and - others). - - ccw_timeout_log [S390] - See Documentation/s390/CommonIO for details. - - cgroup_disable= [KNL] Disable a particular controller - Format: {name of the controller(s) to disable} - The effects of cgroup_disable=foo are: - - foo isn't auto-mounted if you mount all cgroups in - a single hierarchy - - foo isn't visible as an individually mountable - subsystem - {Currently only "memory" controller deal with this and - cut the overhead, others just disable the usage. So - only cgroup_disable=memory is actually worthy} - - cgroup_no_v1= [KNL] Disable one, multiple, all cgroup controllers in v1 - Format: { controller[,controller...] | "all" } - Like cgroup_disable, but only applies to cgroup v1; - the blacklisted controllers remain available in cgroup2. - - cgroup.memory= [KNL] Pass options to the cgroup memory controller. - Format: - nosocket -- Disable socket memory accounting. - nokmem -- Disable kernel memory accounting. - - checkreqprot [SELINUX] Set initial checkreqprot flag value. - Format: { "0" | "1" } - See security/selinux/Kconfig help text. - 0 -- check protection applied by kernel (includes - any implied execute protection). - 1 -- check protection requested by application. - Default value is set via a kernel config option. - Value can be changed at runtime via - /selinux/checkreqprot. - - cio_ignore= [S390] - See Documentation/s390/CommonIO for details. - clk_ignore_unused - [CLK] - Prevents the clock framework from automatically gating - clocks that have not been explicitly enabled by a Linux - device driver but are enabled in hardware at reset or - by the bootloader/firmware. Note that this does not - force such clocks to be always-on nor does it reserve - those clocks in any way. This parameter is useful for - debug and development, but should not be needed on a - platform with proper driver support. For more - information, see Documentation/clk.txt. - - clock= [BUGS=X86-32, HW] gettimeofday clocksource override. - [Deprecated] - Forces specified clocksource (if available) to be used - when calculating gettimeofday(). If specified - clocksource is not available, it defaults to PIT. - Format: { pit | tsc | cyclone | pmtmr } - - clocksource= Override the default clocksource - Format: - Override the default clocksource and use the clocksource - with the name specified. - Some clocksource names to choose from, depending on - the platform: - [all] jiffies (this is the base, fallback clocksource) - [ACPI] acpi_pm - [ARM] imx_timer1,OSTS,netx_timer,mpu_timer2, - pxa_timer,timer3,32k_counter,timer0_1 - [AVR32] avr32 - [X86-32] pit,hpet,tsc; - scx200_hrt on Geode; cyclone on IBM x440 - [MIPS] MIPS - [PARISC] cr16 - [S390] tod - [SH] SuperH - [SPARC64] tick - [X86-64] hpet,tsc - - clocksource.arm_arch_timer.evtstrm= - [ARM,ARM64] - Format: - Enable/disable the eventstream feature of the ARM - architected timer so that code using WFE-based polling - loops can be debugged more effectively on production - systems. - - clocksource.arm_arch_timer.fsl-a008585= - [ARM64] - Format: - Enable/disable the workaround of Freescale/NXP - erratum A-008585. This can be useful for KVM - guests, if the guest device tree doesn't show the - erratum. If unspecified, the workaround is - enabled based on the device tree. - - clearcpuid=BITNUM [X86] - Disable CPUID feature X for the kernel. See - arch/x86/include/asm/cpufeatures.h for the valid bit - numbers. Note the Linux specific bits are not necessarily - stable over kernel options, but the vendor specific - ones should be. - Also note that user programs calling CPUID directly - or using the feature without checking anything - will still see it. This just prevents it from - being used by the kernel or shown in /proc/cpuinfo. - Also note the kernel might malfunction if you disable - some critical bits. - - cma=nn[MG]@[start[MG][-end[MG]]] - [ARM,X86,KNL] - Sets the size of kernel global memory area for - contiguous memory allocations and optionally the - placement constraint by the physical address range of - memory allocations. A value of 0 disables CMA - altogether. For more information, see - include/linux/dma-contiguous.h - - cmo_free_hint= [PPC] Format: { yes | no } - Specify whether pages are marked as being inactive - when they are freed. This is used in CMO environments - to determine OS memory pressure for page stealing by - a hypervisor. - Default: yes - - coherent_pool=nn[KMG] [ARM,KNL] - Sets the size of memory pool for coherent, atomic dma - allocations, by default set to 256K. - - code_bytes [X86] How many bytes of object code to print - in an oops report. - Range: 0 - 8192 - Default: 64 - - com20020= [HW,NET] ARCnet - COM20020 chipset - Format: - [,[,[,[,[,]]]]] - - com90io= [HW,NET] ARCnet - COM90xx chipset (IO-mapped buffers) - Format: [,] - - com90xx= [HW,NET] - ARCnet - COM90xx chipset (memory-mapped buffers) - Format: [,[,]] - - condev= [HW,S390] console device - conmode= - - console= [KNL] Output console device and options. - - tty Use the virtual console device . - - ttyS[,options] - ttyUSB0[,options] - Use the specified serial port. The options are of - the form "bbbbpnf", where "bbbb" is the baud rate, - "p" is parity ("n", "o", or "e"), "n" is number of - bits, and "f" is flow control ("r" for RTS or - omit it). Default is "9600n8". - - See Documentation/serial-console.txt for more - information. See - Documentation/networking/netconsole.txt for an - alternative. - - uart[8250],io,[,options] - uart[8250],mmio,[,options] - uart[8250],mmio16,[,options] - uart[8250],mmio32,[,options] - uart[8250],0x[,options] - Start an early, polled-mode console on the 8250/16550 - UART at the specified I/O port or MMIO address, - switching to the matching ttyS device later. - MMIO inter-register address stride is either 8-bit - (mmio), 16-bit (mmio16), or 32-bit (mmio32). - If none of [io|mmio|mmio16|mmio32], is assumed - to be equivalent to 'mmio'. 'options' are specified in - the same format described for ttyS above; if unspecified, - the h/w is not re-initialized. - - hvc Use the hypervisor console device . This is for - both Xen and PowerPC hypervisors. - - If the device connected to the port is not a TTY but a braille - device, prepend "brl," before the device type, for instance - console=brl,ttyS0 - For now, only VisioBraille is supported. - - consoleblank= [KNL] The console blank (screen saver) timeout in - seconds. Defaults to 10*60 = 10mins. A value of 0 - disables the blank timer. - - coredump_filter= - [KNL] Change the default value for - /proc//coredump_filter. - See also Documentation/filesystems/proc.txt. - - cpuidle.off=1 [CPU_IDLE] - disable the cpuidle sub-system - - cpu_init_udelay=N - [X86] Delay for N microsec between assert and de-assert - of APIC INIT to start processors. This delay occurs - on every CPU online, such as boot, and resume from suspend. - Default: 10000 - - cpcihp_generic= [HW,PCI] Generic port I/O CompactPCI driver - Format: - ,,,[,] - - crashkernel=size[KMG][@offset[KMG]] - [KNL] Using kexec, Linux can switch to a 'crash kernel' - upon panic. This parameter reserves the physical - memory region [offset, offset + size] for that kernel - image. If '@offset' is omitted, then a suitable offset - is selected automatically. Check - Documentation/kdump/kdump.txt for further details. - - crashkernel=range1:size1[,range2:size2,...][@offset] - [KNL] Same as above, but depends on the memory - in the running system. The syntax of range is - start-[end] where start and end are both - a memory unit (amount[KMG]). See also - Documentation/kdump/kdump.txt for an example. - - crashkernel=size[KMG],high - [KNL, x86_64] range could be above 4G. Allow kernel - to allocate physical memory region from top, so could - be above 4G if system have more than 4G ram installed. - Otherwise memory region will be allocated below 4G, if - available. - It will be ignored if crashkernel=X is specified. - crashkernel=size[KMG],low - [KNL, x86_64] range under 4G. When crashkernel=X,high - is passed, kernel could allocate physical memory region - above 4G, that cause second kernel crash on system - that require some amount of low memory, e.g. swiotlb - requires at least 64M+32K low memory, also enough extra - low memory is needed to make sure DMA buffers for 32-bit - devices won't run out. Kernel would try to allocate at - at least 256M below 4G automatically. - This one let user to specify own low range under 4G - for second kernel instead. - 0: to disable low allocation. - It will be ignored when crashkernel=X,high is not used - or memory reserved is below 4G. - - cryptomgr.notests - [KNL] Disable crypto self-tests - - cs89x0_dma= [HW,NET] - Format: - - cs89x0_media= [HW,NET] - Format: { rj45 | aui | bnc } - - dasd= [HW,NET] - See header of drivers/s390/block/dasd_devmap.c. - - db9.dev[2|3]= [HW,JOY] Multisystem joystick support via parallel port - (one device per port) - Format: , - See also Documentation/input/joystick-parport.txt - - ddebug_query= [KNL,DYNAMIC_DEBUG] Enable debug messages at early boot - time. See Documentation/dynamic-debug-howto.txt for - details. Deprecated, see dyndbg. - - debug [KNL] Enable kernel debugging (events log level). - - debug_locks_verbose= - [KNL] verbose self-tests - Format=<0|1> - Print debugging info while doing the locking API - self-tests. - We default to 0 (no extra messages), setting it to - 1 will print _a lot_ more information - normally - only useful to kernel developers. - - debug_objects [KNL] Enable object debugging - - no_debug_objects - [KNL] Disable object debugging - - debug_guardpage_minorder= - [KNL] When CONFIG_DEBUG_PAGEALLOC is set, this - parameter allows control of the order of pages that will - be intentionally kept free (and hence protected) by the - buddy allocator. Bigger value increase the probability - of catching random memory corruption, but reduce the - amount of memory for normal system use. The maximum - possible value is MAX_ORDER/2. Setting this parameter - to 1 or 2 should be enough to identify most random - memory corruption problems caused by bugs in kernel or - driver code when a CPU writes to (or reads from) a - random memory location. Note that there exists a class - of memory corruptions problems caused by buggy H/W or - F/W or by drivers badly programing DMA (basically when - memory is written at bus level and the CPU MMU is - bypassed) which are not detectable by - CONFIG_DEBUG_PAGEALLOC, hence this option will not help - tracking down these problems. - - debug_pagealloc= - [KNL] When CONFIG_DEBUG_PAGEALLOC is set, this - parameter enables the feature at boot time. In - default, it is disabled. We can avoid allocating huge - chunk of memory for debug pagealloc if we don't enable - it at boot time and the system will work mostly same - with the kernel built without CONFIG_DEBUG_PAGEALLOC. - on: enable the feature - - debugpat [X86] Enable PAT debugging - - decnet.addr= [HW,NET] - Format: [,] - See also Documentation/networking/decnet.txt. - - default_hugepagesz= - [same as hugepagesz=] The size of the default - HugeTLB page size. This is the size represented by - the legacy /proc/ hugepages APIs, used for SHM, and - default size when mounting hugetlbfs filesystems. - Defaults to the default architecture's huge page size - if not specified. - - dhash_entries= [KNL] - Set number of hash buckets for dentry cache. - - disable_1tb_segments [PPC] - Disables the use of 1TB hash page table segments. This - causes the kernel to fall back to 256MB segments which - can be useful when debugging issues that require an SLB - miss to occur. - - disable= [IPV6] - See Documentation/networking/ipv6.txt. - - disable_radix [PPC] - Disable RADIX MMU mode on POWER9 - - disable_cpu_apicid= [X86,APIC,SMP] - Format: - The number of initial APIC ID for the - corresponding CPU to be disabled at boot, - mostly used for the kdump 2nd kernel to - disable BSP to wake up multiple CPUs without - causing system reset or hang due to sending - INIT from AP to BSP. - - disable_ddw [PPC/PSERIES] - Disable Dynamic DMA Window support. Use this if - to workaround buggy firmware. - - disable_ipv6= [IPV6] - See Documentation/networking/ipv6.txt. - - disable_mtrr_cleanup [X86] - The kernel tries to adjust MTRR layout from continuous - to discrete, to make X server driver able to add WB - entry later. This parameter disables that. - - disable_mtrr_trim [X86, Intel and AMD only] - By default the kernel will trim any uncacheable - memory out of your available memory pool based on - MTRR settings. This parameter disables that behavior, - possibly causing your machine to run very slowly. - - disable_timer_pin_1 [X86] - Disable PIN 1 of APIC timer - Can be useful to work around chipset bugs. - - dis_ucode_ldr [X86] Disable the microcode loader. - - dma_debug=off If the kernel is compiled with DMA_API_DEBUG support, - this option disables the debugging code at boot. - - dma_debug_entries= - This option allows to tune the number of preallocated - entries for DMA-API debugging code. One entry is - required per DMA-API allocation. Use this if the - DMA-API debugging code disables itself because the - architectural default is too low. - - dma_debug_driver= - With this option the DMA-API debugging driver - filter feature can be enabled at boot time. Just - pass the driver to filter for as the parameter. - The filter can be disabled or changed to another - driver later using sysfs. - - drm_kms_helper.edid_firmware=[:][,[:]] - Broken monitors, graphic adapters, KVMs and EDIDless - panels may send no or incorrect EDID data sets. - This parameter allows to specify an EDID data sets - in the /lib/firmware directory that are used instead. - Generic built-in EDID data sets are used, if one of - edid/1024x768.bin, edid/1280x1024.bin, - edid/1680x1050.bin, or edid/1920x1080.bin is given - and no file with the same name exists. Details and - instructions how to build your own EDID data are - available in Documentation/EDID/HOWTO.txt. An EDID - data set will only be used for a particular connector, - if its name and a colon are prepended to the EDID - name. Each connector may use a unique EDID data - set by separating the files with a comma. An EDID - data set with no connector name will be used for - any connectors not explicitly specified. - - dscc4.setup= [NET] - - dyndbg[="val"] [KNL,DYNAMIC_DEBUG] - module.dyndbg[="val"] - Enable debug messages at boot time. See - Documentation/dynamic-debug-howto.txt for details. - - nompx [X86] Disables Intel Memory Protection Extensions. - See Documentation/x86/intel_mpx.txt for more - information about the feature. - - nopku [X86] Disable Memory Protection Keys CPU feature found - in some Intel CPUs. - - eagerfpu= [X86] - on enable eager fpu restore - off disable eager fpu restore - auto selects the default scheme, which automatically - enables eagerfpu restore for xsaveopt. - - module.async_probe [KNL] - Enable asynchronous probe on this module. - - early_ioremap_debug [KNL] - Enable debug messages in early_ioremap support. This - is useful for tracking down temporary early mappings - which are not unmapped. - - earlycon= [KNL] Output early console device and options. - - When used with no options, the early console is - determined by the stdout-path property in device - tree's chosen node. - - cdns,[,options] - Start an early, polled-mode console on a Cadence - (xuartps) serial port at the specified address. Only - supported option is baud rate. If baud rate is not - specified, the serial port must already be setup and - configured. - - uart[8250],io,[,options] - uart[8250],mmio,[,options] - uart[8250],mmio32,[,options] - uart[8250],mmio32be,[,options] - uart[8250],0x[,options] - Start an early, polled-mode console on the 8250/16550 - UART at the specified I/O port or MMIO address. - MMIO inter-register address stride is either 8-bit - (mmio) or 32-bit (mmio32 or mmio32be). - If none of [io|mmio|mmio32|mmio32be], is assumed - to be equivalent to 'mmio'. 'options' are specified - in the same format described for "console=ttyS"; if - unspecified, the h/w is not initialized. - - pl011, - pl011,mmio32, - Start an early, polled-mode console on a pl011 serial - port at the specified address. The pl011 serial port - must already be setup and configured. Options are not - yet supported. If 'mmio32' is specified, then only - the driver will use only 32-bit accessors to read/write - the device registers. - - meson, - Start an early, polled-mode console on a meson serial - port at the specified address. The serial port must - already be setup and configured. Options are not yet - supported. - - msm_serial, - Start an early, polled-mode console on an msm serial - port at the specified address. The serial port - must already be setup and configured. Options are not - yet supported. - - msm_serial_dm, - Start an early, polled-mode console on an msm serial - dm port at the specified address. The serial port - must already be setup and configured. Options are not - yet supported. - - smh Use ARM semihosting calls for early console. - - s3c2410, - s3c2412, - s3c2440, - s3c6400, - s5pv210, - exynos4210, - Use early console provided by serial driver available - on Samsung SoCs, requires selecting proper type and - a correct base address of the selected UART port. The - serial port must already be setup and configured. - Options are not yet supported. - - lpuart, - lpuart32, - Use early console provided by Freescale LP UART driver - found on Freescale Vybrid and QorIQ LS1021A processors. - A valid base address must be provided, and the serial - port must already be setup and configured. - - armada3700_uart, - Start an early, polled-mode console on the - Armada 3700 serial port at the specified - address. The serial port must already be setup - and configured. Options are not yet supported. - - earlyprintk= [X86,SH,BLACKFIN,ARM,M68k] - earlyprintk=vga - earlyprintk=efi - earlyprintk=xen - earlyprintk=serial[,ttySn[,baudrate]] - earlyprintk=serial[,0x...[,baudrate]] - earlyprintk=ttySn[,baudrate] - earlyprintk=dbgp[debugController#] - earlyprintk=pciserial,bus:device.function[,baudrate] - - earlyprintk is useful when the kernel crashes before - the normal console is initialized. It is not enabled by - default because it has some cosmetic problems. - - Append ",keep" to not disable it when the real console - takes over. - - Only one of vga, efi, serial, or usb debug port can - be used at a time. - - Currently only ttyS0 and ttyS1 may be specified by - name. Other I/O ports may be explicitly specified - on some architectures (x86 and arm at least) by - replacing ttySn with an I/O port address, like this: - earlyprintk=serial,0x1008,115200 - You can find the port for a given device in - /proc/tty/driver/serial: - 2: uart:ST16650V2 port:00001008 irq:18 ... - - Interaction with the standard serial driver is not - very good. - - The VGA and EFI output is eventually overwritten by - the real console. - - The xen output can only be used by Xen PV guests. - - edac_report= [HW,EDAC] Control how to report EDAC event - Format: {"on" | "off" | "force"} - on: enable EDAC to report H/W event. May be overridden - by other higher priority error reporting module. - off: disable H/W event reporting through EDAC. - force: enforce the use of EDAC to report H/W event. - default: on. - - ekgdboc= [X86,KGDB] Allow early kernel console debugging - ekgdboc=kbd - - This is designed to be used in conjunction with - the boot argument: earlyprintk=vga - - edd= [EDD] - Format: {"off" | "on" | "skip[mbr]"} - - efi= [EFI] - Format: { "old_map", "nochunk", "noruntime", "debug" } - old_map [X86-64]: switch to the old ioremap-based EFI - runtime services mapping. 32-bit still uses this one by - default. - nochunk: disable reading files in "chunks" in the EFI - boot stub, as chunking can cause problems with some - firmware implementations. - noruntime : disable EFI runtime services support - debug: enable misc debug output - - efi_no_storage_paranoia [EFI; X86] - Using this parameter you can use more than 50% of - your efi variable storage. Use this parameter only if - you are really sure that your UEFI does sane gc and - fulfills the spec otherwise your board may brick. - - efi_fake_mem= nn[KMG]@ss[KMG]:aa[,nn[KMG]@ss[KMG]:aa,..] [EFI; X86] - Add arbitrary attribute to specific memory range by - updating original EFI memory map. - Region of memory which aa attribute is added to is - from ss to ss+nn. - If efi_fake_mem=2G@4G:0x10000,2G@0x10a0000000:0x10000 - is specified, EFI_MEMORY_MORE_RELIABLE(0x10000) - attribute is added to range 0x100000000-0x180000000 and - 0x10a0000000-0x1120000000. - - Using this parameter you can do debugging of EFI memmap - related feature. For example, you can do debugging of - Address Range Mirroring feature even if your box - doesn't support it. - - efivar_ssdt= [EFI; X86] Name of an EFI variable that contains an SSDT - that is to be dynamically loaded by Linux. If there are - multiple variables with the same name but with different - vendor GUIDs, all of them will be loaded. See - Documentation/acpi/ssdt-overlays.txt for details. - - - eisa_irq_edge= [PARISC,HW] - See header of drivers/parisc/eisa.c. - - elanfreq= [X86-32] - See comment before function elanfreq_setup() in - arch/x86/kernel/cpu/cpufreq/elanfreq.c. - - elevator= [IOSCHED] - Format: {"cfq" | "deadline" | "noop"} - See Documentation/block/cfq-iosched.txt and - Documentation/block/deadline-iosched.txt for details. - - elfcorehdr=[size[KMG]@]offset[KMG] [IA64,PPC,SH,X86,S390] - Specifies physical address of start of kernel core - image elf header and optionally the size. Generally - kexec loader will pass this option to capture kernel. - See Documentation/kdump/kdump.txt for details. - - enable_mtrr_cleanup [X86] - The kernel tries to adjust MTRR layout from continuous - to discrete, to make X server driver able to add WB - entry later. This parameter enables that. - - enable_timer_pin_1 [X86] - Enable PIN 1 of APIC timer - Can be useful to work around chipset bugs - (in particular on some ATI chipsets). - The kernel tries to set a reasonable default. - - enforcing [SELINUX] Set initial enforcing status. - Format: {"0" | "1"} - See security/selinux/Kconfig help text. - 0 -- permissive (log only, no denials). - 1 -- enforcing (deny and log). - Default value is 0. - Value can be changed at runtime via /selinux/enforce. - - erst_disable [ACPI] - Disable Error Record Serialization Table (ERST) - support. - - ether= [HW,NET] Ethernet cards parameters - This option is obsoleted by the "netdev=" option, which - has equivalent usage. See its documentation for details. - - evm= [EVM] - Format: { "fix" } - Permit 'security.evm' to be updated regardless of - current integrity status. - - failslab= - fail_page_alloc= - fail_make_request=[KNL] - General fault injection mechanism. - Format: ,,, - See also Documentation/fault-injection/. - - floppy= [HW] - See Documentation/blockdev/floppy.txt. - - force_pal_cache_flush - [IA-64] Avoid check_sal_cache_flush which may hang on - buggy SAL_CACHE_FLUSH implementations. Using this - parameter will force ia64_sal_cache_flush to call - ia64_pal_cache_flush instead of SAL_CACHE_FLUSH. - - forcepae [X86-32] - Forcefully enable Physical Address Extension (PAE). - Many Pentium M systems disable PAE but may have a - functionally usable PAE implementation. - Warning: use of this parameter will taint the kernel - and may cause unknown problems. - - ftrace=[tracer] - [FTRACE] will set and start the specified tracer - as early as possible in order to facilitate early - boot debugging. - - ftrace_dump_on_oops[=orig_cpu] - [FTRACE] will dump the trace buffers on oops. - If no parameter is passed, ftrace will dump - buffers of all CPUs, but if you pass orig_cpu, it will - dump only the buffer of the CPU that triggered the - oops. - - ftrace_filter=[function-list] - [FTRACE] Limit the functions traced by the function - tracer at boot up. function-list is a comma separated - list of functions. This list can be changed at run - time by the set_ftrace_filter file in the debugfs - tracing directory. - - ftrace_notrace=[function-list] - [FTRACE] Do not trace the functions specified in - function-list. This list can be changed at run time - by the set_ftrace_notrace file in the debugfs - tracing directory. - - ftrace_graph_filter=[function-list] - [FTRACE] Limit the top level callers functions traced - by the function graph tracer at boot up. - function-list is a comma separated list of functions - that can be changed at run time by the - set_graph_function file in the debugfs tracing directory. - - ftrace_graph_notrace=[function-list] - [FTRACE] Do not trace from the functions specified in - function-list. This list is a comma separated list of - functions that can be changed at run time by the - set_graph_notrace file in the debugfs tracing directory. - - gamecon.map[2|3]= - [HW,JOY] Multisystem joystick and NES/SNES/PSX pad - support via parallel port (up to 5 devices per port) - Format: ,,,,, - See also Documentation/input/joystick-parport.txt - - gamma= [HW,DRM] - - gart_fix_e820= [X86_64] disable the fix e820 for K8 GART - Format: off | on - default: on - - gcov_persist= [GCOV] When non-zero (default), profiling data for - kernel modules is saved and remains accessible via - debugfs, even when the module is unloaded/reloaded. - When zero, profiling data is discarded and associated - debugfs files are removed at module unload time. - - gpt [EFI] Forces disk with valid GPT signature but - invalid Protective MBR to be treated as GPT. If the - primary GPT is corrupted, it enables the backup/alternate - GPT to be used instead. - - grcan.enable0= [HW] Configuration of physical interface 0. Determines - the "Enable 0" bit of the configuration register. - Format: 0 | 1 - Default: 0 - grcan.enable1= [HW] Configuration of physical interface 1. Determines - the "Enable 0" bit of the configuration register. - Format: 0 | 1 - Default: 0 - grcan.select= [HW] Select which physical interface to use. - Format: 0 | 1 - Default: 0 - grcan.txsize= [HW] Sets the size of the tx buffer. - Format: such that (txsize & ~0x1fffc0) == 0. - Default: 1024 - grcan.rxsize= [HW] Sets the size of the rx buffer. - Format: such that (rxsize & ~0x1fffc0) == 0. - Default: 1024 - - gpio-mockup.gpio_mockup_ranges - [HW] Sets the ranges of gpiochip of for this device. - Format: ,,,... - - hardlockup_all_cpu_backtrace= - [KNL] Should the hard-lockup detector generate - backtraces on all cpus. - Format: - - hashdist= [KNL,NUMA] Large hashes allocated during boot - are distributed across NUMA nodes. Defaults on - for 64-bit NUMA, off otherwise. - Format: 0 | 1 (for off | on) - - hcl= [IA-64] SGI's Hardware Graph compatibility layer - - hd= [EIDE] (E)IDE hard drive subsystem geometry - Format: ,, - - hest_disable [ACPI] - Disable Hardware Error Source Table (HEST) support; - corresponding firmware-first mode error processing - logic will be disabled. - - highmem=nn[KMG] [KNL,BOOT] forces the highmem zone to have an exact - size of . This works even on boxes that have no - highmem otherwise. This also works to reduce highmem - size on bigger boxes. - - highres= [KNL] Enable/disable high resolution timer mode. - Valid parameters: "on", "off" - Default: "on" - - hisax= [HW,ISDN] - See Documentation/isdn/README.HiSax. - - hlt [BUGS=ARM,SH] - - hpet= [X86-32,HPET] option to control HPET usage - Format: { enable (default) | disable | force | - verbose } - disable: disable HPET and use PIT instead - force: allow force enabled of undocumented chips (ICH4, - VIA, nVidia) - verbose: show contents of HPET registers during setup - - hpet_mmap= [X86, HPET_MMAP] Allow userspace to mmap HPET - registers. Default set by CONFIG_HPET_MMAP_DEFAULT. - - hugepages= [HW,X86-32,IA-64] HugeTLB pages to allocate at boot. - hugepagesz= [HW,IA-64,PPC,X86-64] The size of the HugeTLB pages. - On x86-64 and powerpc, this option can be specified - multiple times interleaved with hugepages= to reserve - huge pages of different sizes. Valid pages sizes on - x86-64 are 2M (when the CPU supports "pse") and 1G - (when the CPU supports the "pdpe1gb" cpuinfo flag). - - hvc_iucv= [S390] Number of z/VM IUCV hypervisor console (HVC) - terminal devices. Valid values: 0..8 - hvc_iucv_allow= [S390] Comma-separated list of z/VM user IDs. - If specified, z/VM IUCV HVC accepts connections - from listed z/VM user IDs only. - - hwthread_map= [METAG] Comma-separated list of Linux cpu id to - hardware thread id mappings. - Format: : - - keep_bootcon [KNL] - Do not unregister boot console at start. This is only - useful for debugging when something happens in the window - between unregistering the boot console and initializing - the real console. - - i2c_bus= [HW] Override the default board specific I2C bus speed - or register an additional I2C bus that is not - registered from board initialization code. - Format: - , - - i8042.debug [HW] Toggle i8042 debug mode - i8042.unmask_kbd_data - [HW] Enable printing of interrupt data from the KBD port - (disabled by default, and as a pre-condition - requires that i8042.debug=1 be enabled) - i8042.direct [HW] Put keyboard port into non-translated mode - i8042.dumbkbd [HW] Pretend that controller can only read data from - keyboard and cannot control its state - (Don't attempt to blink the leds) - i8042.noaux [HW] Don't check for auxiliary (== mouse) port - i8042.nokbd [HW] Don't check/create keyboard port - i8042.noloop [HW] Disable the AUX Loopback command while probing - for the AUX port - i8042.nomux [HW] Don't check presence of an active multiplexing - controller - i8042.nopnp [HW] Don't use ACPIPnP / PnPBIOS to discover KBD/AUX - controllers - i8042.notimeout [HW] Ignore timeout condition signalled by controller - i8042.reset [HW] Reset the controller during init, cleanup and - suspend-to-ram transitions, only during s2r - transitions, or never reset - Format: { 1 | Y | y | 0 | N | n } - 1, Y, y: always reset controller - 0, N, n: don't ever reset controller - Default: only on s2r transitions on x86; most other - architectures force reset to be always executed - i8042.unlock [HW] Unlock (ignore) the keylock - i8042.kbdreset [HW] Reset device connected to KBD port - - i810= [HW,DRM] - - i8k.ignore_dmi [HW] Continue probing hardware even if DMI data - indicates that the driver is running on unsupported - hardware. - i8k.force [HW] Activate i8k driver even if SMM BIOS signature - does not match list of supported models. - i8k.power_status - [HW] Report power status in /proc/i8k - (disabled by default) - i8k.restricted [HW] Allow controlling fans only if SYS_ADMIN - capability is set. - - i915.invert_brightness= - [DRM] Invert the sense of the variable that is used to - set the brightness of the panel backlight. Normally a - brightness value of 0 indicates backlight switched off, - and the maximum of the brightness value sets the backlight - to maximum brightness. If this parameter is set to 0 - (default) and the machine requires it, or this parameter - is set to 1, a brightness value of 0 sets the backlight - to maximum brightness, and the maximum of the brightness - value switches the backlight off. - -1 -- never invert brightness - 0 -- machine default - 1 -- force brightness inversion - - icn= [HW,ISDN] - Format: [,[,[,]]] - - ide-core.nodma= [HW] (E)IDE subsystem - Format: =0.0 to prevent dma on hda, =0.1 hdb =1.0 hdc - .vlb_clock .pci_clock .noflush .nohpa .noprobe .nowerr - .cdrom .chs .ignore_cable are additional options - See Documentation/ide/ide.txt. - - ide-generic.probe-mask= [HW] (E)IDE subsystem - Format: - Probe mask for legacy ISA IDE ports. Depending on - platform up to 6 ports are supported, enabled by - setting corresponding bits in the mask to 1. The - default value is 0x0, which has a special meaning. - On systems that have PCI, it triggers scanning the - PCI bus for the first and the second port, which - are then probed. On systems without PCI the value - of 0x0 enables probing the two first ports as if it - was 0x3. - - ide-pci-generic.all-generic-ide [HW] (E)IDE subsystem - Claim all unknown PCI IDE storage controllers. - - idle= [X86] - Format: idle=poll, idle=halt, idle=nomwait - Poll forces a polling idle loop that can slightly - improve the performance of waking up a idle CPU, but - will use a lot of power and make the system run hot. - Not recommended. - idle=halt: Halt is forced to be used for CPU idle. - In such case C2/C3 won't be used again. - idle=nomwait: Disable mwait for CPU C-states - - ieee754= [MIPS] Select IEEE Std 754 conformance mode - Format: { strict | legacy | 2008 | relaxed } - Default: strict - - Choose which programs will be accepted for execution - based on the IEEE 754 NaN encoding(s) supported by - the FPU and the NaN encoding requested with the value - of an ELF file header flag individually set by each - binary. Hardware implementations are permitted to - support either or both of the legacy and the 2008 NaN - encoding mode. - - Available settings are as follows: - strict accept binaries that request a NaN encoding - supported by the FPU - legacy only accept legacy-NaN binaries, if supported - by the FPU - 2008 only accept 2008-NaN binaries, if supported - by the FPU - relaxed accept any binaries regardless of whether - supported by the FPU - - The FPU emulator is always able to support both NaN - encodings, so if no FPU hardware is present or it has - been disabled with 'nofpu', then the settings of - 'legacy' and '2008' strap the emulator accordingly, - 'relaxed' straps the emulator for both legacy-NaN and - 2008-NaN, whereas 'strict' enables legacy-NaN only on - legacy processors and both NaN encodings on MIPS32 or - MIPS64 CPUs. - - The setting for ABS.fmt/NEG.fmt instruction execution - mode generally follows that for the NaN encoding, - except where unsupported by hardware. - - ignore_loglevel [KNL] - Ignore loglevel setting - this will print /all/ - kernel messages to the console. Useful for debugging. - We also add it as printk module parameter, so users - could change it dynamically, usually by - /sys/module/printk/parameters/ignore_loglevel. - - ignore_rlimit_data - Ignore RLIMIT_DATA setting for data mappings, - print warning at first misuse. Can be changed via - /sys/module/kernel/parameters/ignore_rlimit_data. - - ihash_entries= [KNL] - Set number of hash buckets for inode cache. - - ima_appraise= [IMA] appraise integrity measurements - Format: { "off" | "enforce" | "fix" | "log" } - default: "enforce" - - ima_appraise_tcb [IMA] - The builtin appraise policy appraises all files - owned by uid=0. - - ima_hash= [IMA] - Format: { md5 | sha1 | rmd160 | sha256 | sha384 - | sha512 | ... } - default: "sha1" - - The list of supported hash algorithms is defined - in crypto/hash_info.h. - - ima_policy= [IMA] - The builtin measurement policy to load during IMA - setup. Specyfing "tcb" as the value, measures all - programs exec'd, files mmap'd for exec, and all files - opened with the read mode bit set by either the - effective uid (euid=0) or uid=0. - Format: "tcb" - - ima_tcb [IMA] Deprecated. Use ima_policy= instead. - Load a policy which meets the needs of the Trusted - Computing Base. This means IMA will measure all - programs exec'd, files mmap'd for exec, and all files - opened for read by uid=0. - - ima_template= [IMA] - Select one of defined IMA measurements template formats. - Formats: { "ima" | "ima-ng" | "ima-sig" } - Default: "ima-ng" - - ima_template_fmt= - [IMA] Define a custom template format. - Format: { "field1|...|fieldN" } - - ima.ahash_minsize= [IMA] Minimum file size for asynchronous hash usage - Format: - Set the minimal file size for using asynchronous hash. - If left unspecified, ahash usage is disabled. - - ahash performance varies for different data sizes on - different crypto accelerators. This option can be used - to achieve the best performance for a particular HW. - - ima.ahash_bufsize= [IMA] Asynchronous hash buffer size - Format: - Set hashing buffer size. Default: 4k. - - ahash performance varies for different chunk sizes on - different crypto accelerators. This option can be used - to achieve best performance for particular HW. - - init= [KNL] - Format: - Run specified binary instead of /sbin/init as init - process. - - initcall_debug [KNL] Trace initcalls as they are executed. Useful - for working out where the kernel is dying during - startup. - - initcall_blacklist= [KNL] Do not execute a comma-separated list of - initcall functions. Useful for debugging built-in - modules and initcalls. - - initrd= [BOOT] Specify the location of the initial ramdisk - - init_pkru= [x86] Specify the default memory protection keys rights - register contents for all processes. 0x55555554 by - default (disallow access to all but pkey 0). Can - override in debugfs after boot. - - inport.irq= [HW] Inport (ATI XL and Microsoft) busmouse driver - Format: - - int_pln_enable [x86] Enable power limit notification interrupt - - integrity_audit=[IMA] - Format: { "0" | "1" } - 0 -- basic integrity auditing messages. (Default) - 1 -- additional integrity auditing messages. - - intel_iommu= [DMAR] Intel IOMMU driver (DMAR) option - on - Enable intel iommu driver. - off - Disable intel iommu driver. - igfx_off [Default Off] - By default, gfx is mapped as normal device. If a gfx - device has a dedicated DMAR unit, the DMAR unit is - bypassed by not enabling DMAR with this option. In - this case, gfx device will use physical address for - DMA. - forcedac [x86_64] - With this option iommu will not optimize to look - for io virtual address below 32-bit forcing dual - address cycle on pci bus for cards supporting greater - than 32-bit addressing. The default is to look - for translation below 32-bit and if not available - then look in the higher range. - strict [Default Off] - With this option on every unmap_single operation will - result in a hardware IOTLB flush operation as opposed - to batching them for performance. - sp_off [Default Off] - By default, super page will be supported if Intel IOMMU - has the capability. With this option, super page will - not be supported. - ecs_off [Default Off] - By default, extended context tables will be supported if - the hardware advertises that it has support both for the - extended tables themselves, and also PASID support. With - this option set, extended tables will not be used even - on hardware which claims to support them. - - intel_idle.max_cstate= [KNL,HW,ACPI,X86] - 0 disables intel_idle and fall back on acpi_idle. - 1 to 9 specify maximum depth of C-state. - - intel_pstate= [X86] - disable - Do not enable intel_pstate as the default - scaling driver for the supported processors - force - Enable intel_pstate on systems that prohibit it by default - in favor of acpi-cpufreq. Forcing the intel_pstate driver - instead of acpi-cpufreq may disable platform features, such - as thermal controls and power capping, that rely on ACPI - P-States information being indicated to OSPM and therefore - should be used with caution. This option does not work with - processors that aren't supported by the intel_pstate driver - or on platforms that use pcc-cpufreq instead of acpi-cpufreq. - no_hwp - Do not enable hardware P state control (HWP) - if available. - hwp_only - Only load intel_pstate on systems which support - hardware P state control (HWP) if available. - support_acpi_ppc - Enforce ACPI _PPC performance limits. If the Fixed ACPI - Description Table, specifies preferred power management - profile as "Enterprise Server" or "Performance Server", - then this feature is turned on by default. - - intremap= [X86-64, Intel-IOMMU] - on enable Interrupt Remapping (default) - off disable Interrupt Remapping - nosid disable Source ID checking - no_x2apic_optout - BIOS x2APIC opt-out request will be ignored - nopost disable Interrupt Posting - - iomem= Disable strict checking of access to MMIO memory - strict regions from userspace. - relaxed - - iommu= [x86] - off - force - noforce - biomerge - panic - nopanic - merge - nomerge - forcesac - soft - pt [x86, IA-64] - nobypass [PPC/POWERNV] - Disable IOMMU bypass, using IOMMU for PCI devices. - - - io7= [HW] IO7 for Marvel based alpha systems - See comment before marvel_specify_io7 in - arch/alpha/kernel/core_marvel.c. - - io_delay= [X86] I/O delay method - 0x80 - Standard port 0x80 based delay - 0xed - Alternate port 0xed based delay (needed on some systems) - udelay - Simple two microseconds delay - none - No delay - - ip= [IP_PNP] - See Documentation/filesystems/nfs/nfsroot.txt. - - irqaffinity= [SMP] Set the default irq affinity mask - The argument is a cpu list, as described above. - - irqfixup [HW] - When an interrupt is not handled search all handlers - for it. Intended to get systems with badly broken - firmware running. - - irqpoll [HW] - When an interrupt is not handled search all handlers - for it. Also check all handlers each timer - interrupt. Intended to get systems with badly broken - firmware running. - - isapnp= [ISAPNP] - Format: ,,, - - isolcpus= [KNL,SMP] Isolate CPUs from the general scheduler. - The argument is a cpu list, as described above. - - This option can be used to specify one or more CPUs - to isolate from the general SMP balancing and scheduling - algorithms. You can move a process onto or off an - "isolated" CPU via the CPU affinity syscalls or cpuset. - begins at 0 and the maximum value is - "number of CPUs in system - 1". - - This option is the preferred way to isolate CPUs. The - alternative -- manually setting the CPU mask of all - tasks in the system -- can cause problems and - suboptimal load balancer performance. - - iucv= [HW,NET] - - ivrs_ioapic [HW,X86_64] - Provide an override to the IOAPIC-ID<->DEVICE-ID - mapping provided in the IVRS ACPI table. For - example, to map IOAPIC-ID decimal 10 to - PCI device 00:14.0 write the parameter as: - ivrs_ioapic[10]=00:14.0 - - ivrs_hpet [HW,X86_64] - Provide an override to the HPET-ID<->DEVICE-ID - mapping provided in the IVRS ACPI table. For - example, to map HPET-ID decimal 0 to - PCI device 00:14.0 write the parameter as: - ivrs_hpet[0]=00:14.0 - - ivrs_acpihid [HW,X86_64] - Provide an override to the ACPI-HID:UID<->DEVICE-ID - mapping provided in the IVRS ACPI table. For - example, to map UART-HID:UID AMD0020:0 to - PCI device 00:14.5 write the parameter as: - ivrs_acpihid[00:14.5]=AMD0020:0 - - js= [HW,JOY] Analog joystick - See Documentation/input/joystick.txt. - - nokaslr [KNL] - When CONFIG_RANDOMIZE_BASE is set, this disables - kernel and module base offset ASLR (Address Space - Layout Randomization). - - keepinitrd [HW,ARM] - - kernelcore= [KNL,X86,IA-64,PPC] - Format: nn[KMGTPE] | "mirror" - This parameter - specifies the amount of memory usable by the kernel - for non-movable allocations. The requested amount is - spread evenly throughout all nodes in the system. The - remaining memory in each node is used for Movable - pages. In the event, a node is too small to have both - kernelcore and Movable pages, kernelcore pages will - take priority and other nodes will have a larger number - of Movable pages. The Movable zone is used for the - allocation of pages that may be reclaimed or moved - by the page migration subsystem. This means that - HugeTLB pages may not be allocated from this zone. - Note that allocations like PTEs-from-HighMem still - use the HighMem zone if it exists, and the Normal - zone if it does not. - - Instead of specifying the amount of memory (nn[KMGTPE]), - you can specify "mirror" option. In case "mirror" - option is specified, mirrored (reliable) memory is used - for non-movable allocations and remaining memory is used - for Movable pages. nn[KMGTPE] and "mirror" are exclusive, - so you can NOT specify nn[KMGTPE] and "mirror" at the same - time. - - kgdbdbgp= [KGDB,HW] kgdb over EHCI usb debug port. - Format: [,poll interval] - The controller # is the number of the ehci usb debug - port as it is probed via PCI. The poll interval is - optional and is the number seconds in between - each poll cycle to the debug port in case you need - the functionality for interrupting the kernel with - gdb or control-c on the dbgp connection. When - not using this parameter you use sysrq-g to break into - the kernel debugger. - - kgdboc= [KGDB,HW] kgdb over consoles. - Requires a tty driver that supports console polling, - or a supported polling keyboard driver (non-usb). - Serial only format: [,baud] - keyboard only format: kbd - keyboard and serial format: kbd,[,baud] - Optional Kernel mode setting: - kms, kbd format: kms,kbd - kms, kbd and serial format: kms,kbd,[,baud] - - kgdbwait [KGDB] Stop kernel execution and enter the - kernel debugger at the earliest opportunity. - - kmac= [MIPS] korina ethernet MAC address. - Configure the RouterBoard 532 series on-chip - Ethernet adapter MAC address. - - kmemleak= [KNL] Boot-time kmemleak enable/disable - Valid arguments: on, off - Default: on - Built with CONFIG_DEBUG_KMEMLEAK_DEFAULT_OFF=y, - the default is off. - - kmemcheck= [X86] Boot-time kmemcheck enable/disable/one-shot mode - Valid arguments: 0, 1, 2 - kmemcheck=0 (disabled) - kmemcheck=1 (enabled) - kmemcheck=2 (one-shot mode) - Default: 2 (one-shot mode) - - kstack=N [X86] Print N words from the kernel stack - in oops dumps. - - kvm.ignore_msrs=[KVM] Ignore guest accesses to unhandled MSRs. - Default is 0 (don't ignore, but inject #GP) - - kvm.mmu_audit= [KVM] This is a R/W parameter which allows audit - KVM MMU at runtime. - Default is 0 (off) - - kvm-amd.nested= [KVM,AMD] Allow nested virtualization in KVM/SVM. - Default is 1 (enabled) - - kvm-amd.npt= [KVM,AMD] Disable nested paging (virtualized MMU) - for all guests. - Default is 1 (enabled) if in 64-bit or 32-bit PAE mode. - - kvm-intel.ept= [KVM,Intel] Disable extended page tables - (virtualized MMU) support on capable Intel chips. - Default is 1 (enabled) - - kvm-intel.emulate_invalid_guest_state= - [KVM,Intel] Enable emulation of invalid guest states - Default is 0 (disabled) - - kvm-intel.flexpriority= - [KVM,Intel] Disable FlexPriority feature (TPR shadow). - Default is 1 (enabled) - - kvm-intel.nested= - [KVM,Intel] Enable VMX nesting (nVMX). - Default is 0 (disabled) - - kvm-intel.unrestricted_guest= - [KVM,Intel] Disable unrestricted guest feature - (virtualized real and unpaged mode) on capable - Intel chips. Default is 1 (enabled) - - kvm-intel.vpid= [KVM,Intel] Disable Virtual Processor Identification - feature (tagged TLBs) on capable Intel chips. - Default is 1 (enabled) - - l2cr= [PPC] - - l3cr= [PPC] - - lapic [X86-32,APIC] Enable the local APIC even if BIOS - disabled it. - - lapic= [x86,APIC] "notscdeadline" Do not use TSC deadline - value for LAPIC timer one-shot implementation. Default - back to the programmable timer unit in the LAPIC. - - lapic_timer_c2_ok [X86,APIC] trust the local apic timer - in C2 power state. - - libata.dma= [LIBATA] DMA control - libata.dma=0 Disable all PATA and SATA DMA - libata.dma=1 PATA and SATA Disk DMA only - libata.dma=2 ATAPI (CDROM) DMA only - libata.dma=4 Compact Flash DMA only - Combinations also work, so libata.dma=3 enables DMA - for disks and CDROMs, but not CFs. - - libata.ignore_hpa= [LIBATA] Ignore HPA limit - libata.ignore_hpa=0 keep BIOS limits (default) - libata.ignore_hpa=1 ignore limits, using full disk - - libata.noacpi [LIBATA] Disables use of ACPI in libata suspend/resume - when set. - Format: - - libata.force= [LIBATA] Force configurations. The format is comma - separated list of "[ID:]VAL" where ID is - PORT[.DEVICE]. PORT and DEVICE are decimal numbers - matching port, link or device. Basically, it matches - the ATA ID string printed on console by libata. If - the whole ID part is omitted, the last PORT and DEVICE - values are used. If ID hasn't been specified yet, the - configuration applies to all ports, links and devices. - - If only DEVICE is omitted, the parameter applies to - the port and all links and devices behind it. DEVICE - number of 0 either selects the first device or the - first fan-out link behind PMP device. It does not - select the host link. DEVICE number of 15 selects the - host link and device attached to it. - - The VAL specifies the configuration to force. As long - as there's no ambiguity shortcut notation is allowed. - For example, both 1.5 and 1.5G would work for 1.5Gbps. - The following configurations can be forced. - - * Cable type: 40c, 80c, short40c, unk, ign or sata. - Any ID with matching PORT is used. - - * SATA link speed limit: 1.5Gbps or 3.0Gbps. - - * Transfer mode: pio[0-7], mwdma[0-4] and udma[0-7]. - udma[/][16,25,33,44,66,100,133] notation is also - allowed. - - * [no]ncq: Turn on or off NCQ. - - * [no]ncqtrim: Turn off queued DSM TRIM. - - * nohrst, nosrst, norst: suppress hard, soft - and both resets. - - * rstonce: only attempt one reset during - hot-unplug link recovery - - * dump_id: dump IDENTIFY data. - - * atapi_dmadir: Enable ATAPI DMADIR bridge support - - * disable: Disable this device. - - If there are multiple matching configurations changing - the same attribute, the last one is used. - - memblock=debug [KNL] Enable memblock debug messages. - - load_ramdisk= [RAM] List of ramdisks to load from floppy - See Documentation/blockdev/ramdisk.txt. - - lockd.nlm_grace_period=P [NFS] Assign grace period. - Format: - - lockd.nlm_tcpport=N [NFS] Assign TCP port. - Format: - - lockd.nlm_timeout=T [NFS] Assign timeout value. - Format: - - lockd.nlm_udpport=M [NFS] Assign UDP port. - Format: - - locktorture.nreaders_stress= [KNL] - Set the number of locking read-acquisition kthreads. - Defaults to being automatically set based on the - number of online CPUs. - - locktorture.nwriters_stress= [KNL] - Set the number of locking write-acquisition kthreads. - - locktorture.onoff_holdoff= [KNL] - Set time (s) after boot for CPU-hotplug testing. - - locktorture.onoff_interval= [KNL] - Set time (s) between CPU-hotplug operations, or - zero to disable CPU-hotplug testing. - - locktorture.shuffle_interval= [KNL] - Set task-shuffle interval (jiffies). Shuffling - tasks allows some CPUs to go into dyntick-idle - mode during the locktorture test. - - locktorture.shutdown_secs= [KNL] - Set time (s) after boot system shutdown. This - is useful for hands-off automated testing. - - locktorture.stat_interval= [KNL] - Time (s) between statistics printk()s. - - locktorture.stutter= [KNL] - Time (s) to stutter testing, for example, - specifying five seconds causes the test to run for - five seconds, wait for five seconds, and so on. - This tests the locking primitive's ability to - transition abruptly to and from idle. - - locktorture.torture_runnable= [BOOT] - Start locktorture running at boot time. - - locktorture.torture_type= [KNL] - Specify the locking implementation to test. - - locktorture.verbose= [KNL] - Enable additional printk() statements. - - logibm.irq= [HW,MOUSE] Logitech Bus Mouse Driver - Format: - - loglevel= All Kernel Messages with a loglevel smaller than the - console loglevel will be printed to the console. It can - also be changed with klogd or other programs. The - loglevels are defined as follows: - - 0 (KERN_EMERG) system is unusable - 1 (KERN_ALERT) action must be taken immediately - 2 (KERN_CRIT) critical conditions - 3 (KERN_ERR) error conditions - 4 (KERN_WARNING) warning conditions - 5 (KERN_NOTICE) normal but significant condition - 6 (KERN_INFO) informational - 7 (KERN_DEBUG) debug-level messages - - log_buf_len=n[KMG] Sets the size of the printk ring buffer, - in bytes. n must be a power of two and greater - than the minimal size. The minimal size is defined - by LOG_BUF_SHIFT kernel config parameter. There is - also CONFIG_LOG_CPU_MAX_BUF_SHIFT config parameter - that allows to increase the default size depending on - the number of CPUs. See init/Kconfig for more details. - - logo.nologo [FB] Disables display of the built-in Linux logo. - This may be used to provide more screen space for - kernel log messages and is useful when debugging - kernel boot problems. - - lp=0 [LP] Specify parallel ports to use, e.g, - lp=port[,port...] lp=none,parport0 (lp0 not configured, lp1 uses - lp=reset first parallel port). 'lp=0' disables the - lp=auto printer driver. 'lp=reset' (which can be - specified in addition to the ports) causes - attached printers to be reset. Using - lp=port1,port2,... specifies the parallel ports - to associate lp devices with, starting with - lp0. A port specification may be 'none' to skip - that lp device, or a parport name such as - 'parport0'. Specifying 'lp=auto' instead of a - port specification list means that device IDs - from each port should be examined, to see if - an IEEE 1284-compliant printer is attached; if - so, the driver will manage that printer. - See also header of drivers/char/lp.c. - - lpj=n [KNL] - Sets loops_per_jiffy to given constant, thus avoiding - time-consuming boot-time autodetection (up to 250 ms per - CPU). 0 enables autodetection (default). To determine - the correct value for your kernel, boot with normal - autodetection and see what value is printed. Note that - on SMP systems the preset will be applied to all CPUs, - which is likely to cause problems if your CPUs need - significantly divergent settings. An incorrect value - will cause delays in the kernel to be wrong, leading to - unpredictable I/O errors and other breakage. Although - unlikely, in the extreme case this might damage your - hardware. - - ltpc= [NET] - Format: ,, - - machvec= [IA-64] Force the use of a particular machine-vector - (machvec) in a generic kernel. - Example: machvec=hpzx1_swiotlb - - machtype= [Loongson] Share the same kernel image file between different - yeeloong laptop. - Example: machtype=lemote-yeeloong-2f-7inch - - max_addr=nn[KMG] [KNL,BOOT,ia64] All physical memory greater - than or equal to this physical address is ignored. - - maxcpus= [SMP] Maximum number of processors that an SMP kernel - will bring up during bootup. maxcpus=n : n >= 0 limits - the kernel to bring up 'n' processors. Surely after - bootup you can bring up the other plugged cpu by executing - "echo 1 > /sys/devices/system/cpu/cpuX/online". So maxcpus - only takes effect during system bootup. - While n=0 is a special case, it is equivalent to "nosmp", - which also disables the IO APIC. - - max_loop= [LOOP] The number of loop block devices that get - (loop.max_loop) unconditionally pre-created at init time. The default - number is configured by BLK_DEV_LOOP_MIN_COUNT. Instead - of statically allocating a predefined number, loop - devices can be requested on-demand with the - /dev/loop-control interface. - - mce [X86-32] Machine Check Exception - - mce=option [X86-64] See Documentation/x86/x86_64/boot-options.txt - - md= [HW] RAID subsystems devices and level - See Documentation/md.txt. - - mdacon= [MDA] - Format: , - Specifies range of consoles to be captured by the MDA. - - mem=nn[KMG] [KNL,BOOT] Force usage of a specific amount of memory - Amount of memory to be used when the kernel is not able - to see the whole system memory or for test. - [X86] Work as limiting max address. Use together - with memmap= to avoid physical address space collisions. - Without memmap= PCI devices could be placed at addresses - belonging to unused RAM. - - mem=nopentium [BUGS=X86-32] Disable usage of 4MB pages for kernel - memory. - - memchunk=nn[KMG] - [KNL,SH] Allow user to override the default size for - per-device physically contiguous DMA buffers. - - memhp_default_state=online/offline - [KNL] Set the initial state for the memory hotplug - onlining policy. If not specified, the default value is - set according to the - CONFIG_MEMORY_HOTPLUG_DEFAULT_ONLINE kernel config - option. - See Documentation/memory-hotplug.txt. - - memmap=exactmap [KNL,X86] Enable setting of an exact - E820 memory map, as specified by the user. - Such memmap=exactmap lines can be constructed based on - BIOS output or other requirements. See the memmap=nn@ss - option description. - - memmap=nn[KMG]@ss[KMG] - [KNL] Force usage of a specific region of memory. - Region of memory to be used is from ss to ss+nn. - - memmap=nn[KMG]#ss[KMG] - [KNL,ACPI] Mark specific memory as ACPI data. - Region of memory to be marked is from ss to ss+nn. - - memmap=nn[KMG]$ss[KMG] - [KNL,ACPI] Mark specific memory as reserved. - Region of memory to be reserved is from ss to ss+nn. - Example: Exclude memory from 0x18690000-0x1869ffff - memmap=64K$0x18690000 - or - memmap=0x10000$0x18690000 - - memmap=nn[KMG]!ss[KMG] - [KNL,X86] Mark specific memory as protected. - Region of memory to be used, from ss to ss+nn. - The memory region may be marked as e820 type 12 (0xc) - and is NVDIMM or ADR memory. - - memory_corruption_check=0/1 [X86] - Some BIOSes seem to corrupt the first 64k of - memory when doing things like suspend/resume. - Setting this option will scan the memory - looking for corruption. Enabling this will - both detect corruption and prevent the kernel - from using the memory being corrupted. - However, its intended as a diagnostic tool; if - repeatable BIOS-originated corruption always - affects the same memory, you can use memmap= - to prevent the kernel from using that memory. - - memory_corruption_check_size=size [X86] - By default it checks for corruption in the low - 64k, making this memory unavailable for normal - use. Use this parameter to scan for - corruption in more or less memory. - - memory_corruption_check_period=seconds [X86] - By default it checks for corruption every 60 - seconds. Use this parameter to check at some - other rate. 0 disables periodic checking. - - memtest= [KNL,X86,ARM] Enable memtest - Format: - default : 0 - Specifies the number of memtest passes to be - performed. Each pass selects another test - pattern from a given set of patterns. Memtest - fills the memory with this pattern, validates - memory contents and reserves bad memory - regions that are detected. - - meye.*= [HW] Set MotionEye Camera parameters - See Documentation/video4linux/meye.txt. - - mfgpt_irq= [IA-32] Specify the IRQ to use for the - Multi-Function General Purpose Timers on AMD Geode - platforms. - - mfgptfix [X86-32] Fix MFGPT timers on AMD Geode platforms when - the BIOS has incorrectly applied a workaround. TinyBIOS - version 0.98 is known to be affected, 0.99 fixes the - problem by letting the user disable the workaround. - - mga= [HW,DRM] - - min_addr=nn[KMG] [KNL,BOOT,ia64] All physical memory below this - physical address is ignored. - - mini2440= [ARM,HW,KNL] - Format:[0..2][b][c][t] - Default: "0tb" - MINI2440 configuration specification: - 0 - The attached screen is the 3.5" TFT - 1 - The attached screen is the 7" TFT - 2 - The VGA Shield is attached (1024x768) - Leaving out the screen size parameter will not load - the TFT driver, and the framebuffer will be left - unconfigured. - b - Enable backlight. The TFT backlight pin will be - linked to the kernel VESA blanking code and a GPIO - LED. This parameter is not necessary when using the - VGA shield. - c - Enable the s3c camera interface. - t - Reserved for enabling touchscreen support. The - touchscreen support is not enabled in the mainstream - kernel as of 2.6.30, a preliminary port can be found - in the "bleeding edge" mini2440 support kernel at - http://repo.or.cz/w/linux-2.6/mini2440.git - - mminit_loglevel= - [KNL] When CONFIG_DEBUG_MEMORY_INIT is set, this - parameter allows control of the logging verbosity for - the additional memory initialisation checks. A value - of 0 disables mminit logging and a level of 4 will - log everything. Information is printed at KERN_DEBUG - so loglevel=8 may also need to be specified. - - module.sig_enforce - [KNL] When CONFIG_MODULE_SIG is set, this means that - modules without (valid) signatures will fail to load. - Note that if CONFIG_MODULE_SIG_FORCE is set, that - is always true, so this option does nothing. - - module_blacklist= [KNL] Do not load a comma-separated list of - modules. Useful for debugging problem modules. - - mousedev.tap_time= - [MOUSE] Maximum time between finger touching and - leaving touchpad surface for touch to be considered - a tap and be reported as a left button click (for - touchpads working in absolute mode only). - Format: - mousedev.xres= [MOUSE] Horizontal screen resolution, used for devices - reporting absolute coordinates, such as tablets - mousedev.yres= [MOUSE] Vertical screen resolution, used for devices - reporting absolute coordinates, such as tablets - - movablecore=nn[KMG] [KNL,X86,IA-64,PPC] This parameter - is similar to kernelcore except it specifies the - amount of memory used for migratable allocations. - If both kernelcore and movablecore is specified, - then kernelcore will be at *least* the specified - value but may be more. If movablecore on its own - is specified, the administrator must be careful - that the amount of memory usable for all allocations - is not too small. - - movable_node [KNL,X86] Boot-time switch to enable the effects - of CONFIG_MOVABLE_NODE=y. See mm/Kconfig for details. - - MTD_Partition= [MTD] - Format: ,,, - - MTD_Region= [MTD] Format: - ,[,,,,] - - mtdparts= [MTD] - See drivers/mtd/cmdlinepart.c. - - multitce=off [PPC] This parameter disables the use of the pSeries - firmware feature for updating multiple TCE entries - at a time. - - onenand.bdry= [HW,MTD] Flex-OneNAND Boundary Configuration - - Format: [die0_boundary][,die0_lock][,die1_boundary][,die1_lock] - - boundary - index of last SLC block on Flex-OneNAND. - The remaining blocks are configured as MLC blocks. - lock - Configure if Flex-OneNAND boundary should be locked. - Once locked, the boundary cannot be changed. - 1 indicates lock status, 0 indicates unlock status. - - mtdset= [ARM] - ARM/S3C2412 JIVE boot control - - See arch/arm/mach-s3c2412/mach-jive.c - - mtouchusb.raw_coordinates= - [HW] Make the MicroTouch USB driver use raw coordinates - ('y', default) or cooked coordinates ('n') - - mtrr_chunk_size=nn[KMG] [X86] - used for mtrr cleanup. It is largest continuous chunk - that could hold holes aka. UC entries. - - mtrr_gran_size=nn[KMG] [X86] - Used for mtrr cleanup. It is granularity of mtrr block. - Default is 1. - Large value could prevent small alignment from - using up MTRRs. - - mtrr_spare_reg_nr=n [X86] - Format: - Range: 0,7 : spare reg number - Default : 1 - Used for mtrr cleanup. It is spare mtrr entries number. - Set to 2 or more if your graphical card needs more. - - n2= [NET] SDL Inc. RISCom/N2 synchronous serial card - - netdev= [NET] Network devices parameters - Format: ,,,, - Note that mem_start is often overloaded to mean - something different and driver-specific. - This usage is only documented in each driver source - file if at all. - - nf_conntrack.acct= - [NETFILTER] Enable connection tracking flow accounting - 0 to disable accounting - 1 to enable accounting - Default value is 0. - - nfsaddrs= [NFS] Deprecated. Use ip= instead. - See Documentation/filesystems/nfs/nfsroot.txt. - - nfsroot= [NFS] nfs root filesystem for disk-less boxes. - See Documentation/filesystems/nfs/nfsroot.txt. - - nfsrootdebug [NFS] enable nfsroot debugging messages. - See Documentation/filesystems/nfs/nfsroot.txt. - - nfs.callback_nr_threads= - [NFSv4] set the total number of threads that the - NFS client will assign to service NFSv4 callback - requests. - - nfs.callback_tcpport= - [NFS] set the TCP port on which the NFSv4 callback - channel should listen. - - nfs.cache_getent= - [NFS] sets the pathname to the program which is used - to update the NFS client cache entries. - - nfs.cache_getent_timeout= - [NFS] sets the timeout after which an attempt to - update a cache entry is deemed to have failed. - - nfs.idmap_cache_timeout= - [NFS] set the maximum lifetime for idmapper cache - entries. - - nfs.enable_ino64= - [NFS] enable 64-bit inode numbers. - If zero, the NFS client will fake up a 32-bit inode - number for the readdir() and stat() syscalls instead - of returning the full 64-bit number. - The default is to return 64-bit inode numbers. - - nfs.max_session_cb_slots= - [NFSv4.1] Sets the maximum number of session - slots the client will assign to the callback - channel. This determines the maximum number of - callbacks the client will process in parallel for - a particular server. - - nfs.max_session_slots= - [NFSv4.1] Sets the maximum number of session slots - the client will attempt to negotiate with the server. - This limits the number of simultaneous RPC requests - that the client can send to the NFSv4.1 server. - Note that there is little point in setting this - value higher than the max_tcp_slot_table_limit. - - nfs.nfs4_disable_idmapping= - [NFSv4] When set to the default of '1', this option - ensures that both the RPC level authentication - scheme and the NFS level operations agree to use - numeric uids/gids if the mount is using the - 'sec=sys' security flavour. In effect it is - disabling idmapping, which can make migration from - legacy NFSv2/v3 systems to NFSv4 easier. - Servers that do not support this mode of operation - will be autodetected by the client, and it will fall - back to using the idmapper. - To turn off this behaviour, set the value to '0'. - nfs.nfs4_unique_id= - [NFS4] Specify an additional fixed unique ident- - ification string that NFSv4 clients can insert into - their nfs_client_id4 string. This is typically a - UUID that is generated at system install time. - - nfs.send_implementation_id = - [NFSv4.1] Send client implementation identification - information in exchange_id requests. - If zero, no implementation identification information - will be sent. - The default is to send the implementation identification - information. - - nfs.recover_lost_locks = - [NFSv4] Attempt to recover locks that were lost due - to a lease timeout on the server. Please note that - doing this risks data corruption, since there are - no guarantees that the file will remain unchanged - after the locks are lost. - If you want to enable the kernel legacy behaviour of - attempting to recover these locks, then set this - parameter to '1'. - The default parameter value of '0' causes the kernel - not to attempt recovery of lost locks. - - nfs4.layoutstats_timer = - [NFSv4.2] Change the rate at which the kernel sends - layoutstats to the pNFS metadata server. - - Setting this to value to 0 causes the kernel to use - whatever value is the default set by the layout - driver. A non-zero value sets the minimum interval - in seconds between layoutstats transmissions. - - nfsd.nfs4_disable_idmapping= - [NFSv4] When set to the default of '1', the NFSv4 - server will return only numeric uids and gids to - clients using auth_sys, and will accept numeric uids - and gids from such clients. This is intended to ease - migration from NFSv2/v3. - - objlayoutdriver.osd_login_prog= - [NFS] [OBJLAYOUT] sets the pathname to the program which - is used to automatically discover and login into new - osd-targets. Please see: - Documentation/filesystems/pnfs.txt for more explanations - - nmi_debug= [KNL,AVR32,SH] Specify one or more actions to take - when a NMI is triggered. - Format: [state][,regs][,debounce][,die] - - nmi_watchdog= [KNL,BUGS=X86] Debugging features for SMP kernels - Format: [panic,][nopanic,][num] - Valid num: 0 or 1 - 0 - turn hardlockup detector in nmi_watchdog off - 1 - turn hardlockup detector in nmi_watchdog on - When panic is specified, panic when an NMI watchdog - timeout occurs (or 'nopanic' to override the opposite - default). To disable both hard and soft lockup detectors, - please see 'nowatchdog'. - This is useful when you use a panic=... timeout and - need the box quickly up again. - - netpoll.carrier_timeout= - [NET] Specifies amount of time (in seconds) that - netpoll should wait for a carrier. By default netpoll - waits 4 seconds. - - no387 [BUGS=X86-32] Tells the kernel to use the 387 maths - emulation library even if a 387 maths coprocessor - is present. - - no_console_suspend - [HW] Never suspend the console - Disable suspending of consoles during suspend and - hibernate operations. Once disabled, debugging - messages can reach various consoles while the rest - of the system is being put to sleep (ie, while - debugging driver suspend/resume hooks). This may - not work reliably with all consoles, but is known - to work with serial and VGA consoles. - To facilitate more flexible debugging, we also add - console_suspend, a printk module parameter to control - it. Users could use console_suspend (usually - /sys/module/printk/parameters/console_suspend) to - turn on/off it dynamically. - - noaliencache [MM, NUMA, SLAB] Disables the allocation of alien - caches in the slab allocator. Saves per-node memory, - but will impact performance. - - noalign [KNL,ARM] - - noapic [SMP,APIC] Tells the kernel to not make use of any - IOAPICs that may be present in the system. - - noautogroup Disable scheduler automatic task group creation. - - nobats [PPC] Do not use BATs for mapping kernel lowmem - on "Classic" PPC cores. - - nocache [ARM] - - noclflush [BUGS=X86] Don't use the CLFLUSH instruction - - nodelayacct [KNL] Disable per-task delay accounting - - nodsp [SH] Disable hardware DSP at boot time. - - noefi Disable EFI runtime services support. - - noexec [IA-64] - - noexec [X86] - On X86-32 available only on PAE configured kernels. - noexec=on: enable non-executable mappings (default) - noexec=off: disable non-executable mappings - - nosmap [X86] - Disable SMAP (Supervisor Mode Access Prevention) - even if it is supported by processor. - - nosmep [X86] - Disable SMEP (Supervisor Mode Execution Prevention) - even if it is supported by processor. - - noexec32 [X86-64] - This affects only 32-bit executables. - noexec32=on: enable non-executable mappings (default) - read doesn't imply executable mappings - noexec32=off: disable non-executable mappings - read implies executable mappings - - nofpu [MIPS,SH] Disable hardware FPU at boot time. - - nofxsr [BUGS=X86-32] Disables x86 floating point extended - register save and restore. The kernel will only save - legacy floating-point registers on task switch. - - nohugeiomap [KNL,x86] Disable kernel huge I/O mappings. - - nosmt [KNL,S390] Disable symmetric multithreading (SMT). - Equivalent to smt=1. - - noxsave [BUGS=X86] Disables x86 extended register state save - and restore using xsave. The kernel will fallback to - enabling legacy floating-point and sse state. - - noxsaveopt [X86] Disables xsaveopt used in saving x86 extended - register states. The kernel will fall back to use - xsave to save the states. By using this parameter, - performance of saving the states is degraded because - xsave doesn't support modified optimization while - xsaveopt supports it on xsaveopt enabled systems. - - noxsaves [X86] Disables xsaves and xrstors used in saving and - restoring x86 extended register state in compacted - form of xsave area. The kernel will fall back to use - xsaveopt and xrstor to save and restore the states - in standard form of xsave area. By using this - parameter, xsave area per process might occupy more - memory on xsaves enabled systems. - - nohlt [BUGS=ARM,SH] Tells the kernel that the sleep(SH) or - wfi(ARM) instruction doesn't work correctly and not to - use it. This is also useful when using JTAG debugger. - - no_file_caps Tells the kernel not to honor file capabilities. The - only way then for a file to be executed with privilege - is to be setuid root or executed by root. - - nohalt [IA-64] Tells the kernel not to use the power saving - function PAL_HALT_LIGHT when idle. This increases - power-consumption. On the positive side, it reduces - interrupt wake-up latency, which may improve performance - in certain environments such as networked servers or - real-time systems. - - nohibernate [HIBERNATION] Disable hibernation and resume. - - nohz= [KNL] Boottime enable/disable dynamic ticks - Valid arguments: on, off - Default: on - - nohz_full= [KNL,BOOT] - The argument is a cpu list, as described above. - In kernels built with CONFIG_NO_HZ_FULL=y, set - the specified list of CPUs whose tick will be stopped - whenever possible. The boot CPU will be forced outside - the range to maintain the timekeeping. - The CPUs in this range must also be included in the - rcu_nocbs= set. - - noiotrap [SH] Disables trapped I/O port accesses. - - noirqdebug [X86-32] Disables the code which attempts to detect and - disable unhandled interrupt sources. - - no_timer_check [X86,APIC] Disables the code which tests for - broken timer IRQ sources. - - noisapnp [ISAPNP] Disables ISA PnP code. - - noinitrd [RAM] Tells the kernel not to load any configured - initial RAM disk. - - nointremap [X86-64, Intel-IOMMU] Do not enable interrupt - remapping. - [Deprecated - use intremap=off] - - nointroute [IA-64] - - noinvpcid [X86] Disable the INVPCID cpu feature. - - nojitter [IA-64] Disables jitter checking for ITC timers. - - no-kvmclock [X86,KVM] Disable paravirtualized KVM clock driver - - no-kvmapf [X86,KVM] Disable paravirtualized asynchronous page - fault handling. - - no-steal-acc [X86,KVM] Disable paravirtualized steal time accounting. - steal time is computed, but won't influence scheduler - behaviour - - nolapic [X86-32,APIC] Do not enable or use the local APIC. - - nolapic_timer [X86-32,APIC] Do not use the local APIC timer. - - noltlbs [PPC] Do not use large page/tlb entries for kernel - lowmem mapping on PPC40x and PPC8xx - - nomca [IA-64] Disable machine check abort handling - - nomce [X86-32] Disable Machine Check Exception - - nomfgpt [X86-32] Disable Multi-Function General Purpose - Timer usage (for AMD Geode machines). - - nonmi_ipi [X86] Disable using NMI IPIs during panic/reboot to - shutdown the other cpus. Instead use the REBOOT_VECTOR - irq. - - nomodule Disable module load - - nopat [X86] Disable PAT (page attribute table extension of - pagetables) support. - - norandmaps Don't use address space randomization. Equivalent to - echo 0 > /proc/sys/kernel/randomize_va_space - - noreplace-paravirt [X86,IA-64,PV_OPS] Don't patch paravirt_ops - - noreplace-smp [X86-32,SMP] Don't replace SMP instructions - with UP alternatives - - nordrand [X86] Disable kernel use of the RDRAND and - RDSEED instructions even if they are supported - by the processor. RDRAND and RDSEED are still - available to user space applications. - - noresume [SWSUSP] Disables resume and restores original swap - space. - - no-scroll [VGA] Disables scrollback. - This is required for the Braillex ib80-piezo Braille - reader made by F.H. Papenmeier (Germany). - - nosbagart [IA-64] - - nosep [BUGS=X86-32] Disables x86 SYSENTER/SYSEXIT support. - - nosmp [SMP] Tells an SMP kernel to act as a UP kernel, - and disable the IO APIC. legacy for "maxcpus=0". - - nosoftlockup [KNL] Disable the soft-lockup detector. - - nosync [HW,M68K] Disables sync negotiation for all devices. - - notsc [BUGS=X86-32] Disable Time Stamp Counter - - nowatchdog [KNL] Disable both lockup detectors, i.e. - soft-lockup and NMI watchdog (hard-lockup). - - nowb [ARM] - - nox2apic [X86-64,APIC] Do not enable x2APIC mode. - - cpu0_hotplug [X86] Turn on CPU0 hotplug feature when - CONFIG_BOOTPARAM_HOTPLUG_CPU0 is off. - Some features depend on CPU0. Known dependencies are: - 1. Resume from suspend/hibernate depends on CPU0. - Suspend/hibernate will fail if CPU0 is offline and you - need to online CPU0 before suspend/hibernate. - 2. PIC interrupts also depend on CPU0. CPU0 can't be - removed if a PIC interrupt is detected. - It's said poweroff/reboot may depend on CPU0 on some - machines although I haven't seen such issues so far - after CPU0 is offline on a few tested machines. - If the dependencies are under your control, you can - turn on cpu0_hotplug. - - nptcg= [IA-64] Override max number of concurrent global TLB - purges which is reported from either PAL_VM_SUMMARY or - SAL PALO. - - nr_cpus= [SMP] Maximum number of processors that an SMP kernel - could support. nr_cpus=n : n >= 1 limits the kernel to - support 'n' processors. It could be larger than the - number of already plugged CPU during bootup, later in - runtime you can physically add extra cpu until it reaches - n. So during boot up some boot time memory for per-cpu - variables need be pre-allocated for later physical cpu - hot plugging. - - nr_uarts= [SERIAL] maximum number of UARTs to be registered. - - numa_balancing= [KNL,X86] Enable or disable automatic NUMA balancing. - Allowed values are enable and disable - - numa_zonelist_order= [KNL, BOOT] Select zonelist order for NUMA. - one of ['zone', 'node', 'default'] can be specified - This can be set from sysctl after boot. - See Documentation/sysctl/vm.txt for details. - - ohci1394_dma=early [HW] enable debugging via the ohci1394 driver. - See Documentation/debugging-via-ohci1394.txt for more - info. - - olpc_ec_timeout= [OLPC] ms delay when issuing EC commands - Rather than timing out after 20 ms if an EC - command is not properly ACKed, override the length - of the timeout. We have interrupts disabled while - waiting for the ACK, so if this is set too high - interrupts *may* be lost! - - omap_mux= [OMAP] Override bootloader pin multiplexing. - Format: ... - For example, to override I2C bus2: - omap_mux=i2c2_scl.i2c2_scl=0x100,i2c2_sda.i2c2_sda=0x100 - - oprofile.timer= [HW] - Use timer interrupt instead of performance counters - - oprofile.cpu_type= Force an oprofile cpu type - This might be useful if you have an older oprofile - userland or if you want common events. - Format: { arch_perfmon } - arch_perfmon: [X86] Force use of architectural - perfmon on Intel CPUs instead of the - CPU specific event set. - timer: [X86] Force use of architectural NMI - timer mode (see also oprofile.timer - for generic hr timer mode) - - oops=panic Always panic on oopses. Default is to just kill the - process, but there is a small probability of - deadlocking the machine. - This will also cause panics on machine check exceptions. - Useful together with panic=30 to trigger a reboot. - - OSS [HW,OSS] - See Documentation/sound/oss/oss-parameters.txt - - page_owner= [KNL] Boot-time page_owner enabling option. - Storage of the information about who allocated - each page is disabled in default. With this switch, - we can turn it on. - on: enable the feature - - page_poison= [KNL] Boot-time parameter changing the state of - poisoning on the buddy allocator. - off: turn off poisoning - on: turn on poisoning - - panic= [KNL] Kernel behaviour on panic: delay - timeout > 0: seconds before rebooting - timeout = 0: wait forever - timeout < 0: reboot immediately - Format: - - panic_on_warn panic() instead of WARN(). Useful to cause kdump - on a WARN(). - - crash_kexec_post_notifiers - Run kdump after running panic-notifiers and dumping - kmsg. This only for the users who doubt kdump always - succeeds in any situation. - Note that this also increases risks of kdump failure, - because some panic notifiers can make the crashed - kernel more unstable. - - parkbd.port= [HW] Parallel port number the keyboard adapter is - connected to, default is 0. - Format: - parkbd.mode= [HW] Parallel port keyboard adapter mode of operation, - 0 for XT, 1 for AT (default is AT). - Format: - - parport= [HW,PPT] Specify parallel ports. 0 disables. - Format: { 0 | auto | 0xBBB[,IRQ[,DMA]] } - Use 'auto' to force the driver to use any - IRQ/DMA settings detected (the default is to - ignore detected IRQ/DMA settings because of - possible conflicts). You can specify the base - address, IRQ, and DMA settings; IRQ and DMA - should be numbers, or 'auto' (for using detected - settings on that particular port), or 'nofifo' - (to avoid using a FIFO even if it is detected). - Parallel ports are assigned in the order they - are specified on the command line, starting - with parport0. - - parport_init_mode= [HW,PPT] - Configure VIA parallel port to operate in - a specific mode. This is necessary on Pegasos - computer where firmware has no options for setting - up parallel port mode and sets it to spp. - Currently this function knows 686a and 8231 chips. - Format: [spp|ps2|epp|ecp|ecpepp] - - pause_on_oops= - Halt all CPUs after the first oops has been printed for - the specified number of seconds. This is to be used if - your oopses keep scrolling off the screen. - - pcbit= [HW,ISDN] - - pcd. [PARIDE] - See header of drivers/block/paride/pcd.c. - See also Documentation/blockdev/paride.txt. - - pci=option[,option...] [PCI] various PCI subsystem options: - earlydump [X86] dump PCI config space before the kernel - changes anything - off [X86] don't probe for the PCI bus - bios [X86-32] force use of PCI BIOS, don't access - the hardware directly. Use this if your machine - has a non-standard PCI host bridge. - nobios [X86-32] disallow use of PCI BIOS, only direct - hardware access methods are allowed. Use this - if you experience crashes upon bootup and you - suspect they are caused by the BIOS. - conf1 [X86] Force use of PCI Configuration Access - Mechanism 1 (config address in IO port 0xCF8, - data in IO port 0xCFC, both 32-bit). - conf2 [X86] Force use of PCI Configuration Access - Mechanism 2 (IO port 0xCF8 is an 8-bit port for - the function, IO port 0xCFA, also 8-bit, sets - bus number. The config space is then accessed - through ports 0xC000-0xCFFF). - See http://wiki.osdev.org/PCI for more info - on the configuration access mechanisms. - noaer [PCIE] If the PCIEAER kernel config parameter is - enabled, this kernel boot option can be used to - disable the use of PCIE advanced error reporting. - nodomains [PCI] Disable support for multiple PCI - root domains (aka PCI segments, in ACPI-speak). - nommconf [X86] Disable use of MMCONFIG for PCI - Configuration - check_enable_amd_mmconf [X86] check for and enable - properly configured MMIO access to PCI - config space on AMD family 10h CPU - nomsi [MSI] If the PCI_MSI kernel config parameter is - enabled, this kernel boot option can be used to - disable the use of MSI interrupts system-wide. - noioapicquirk [APIC] Disable all boot interrupt quirks. - Safety option to keep boot IRQs enabled. This - should never be necessary. - ioapicreroute [APIC] Enable rerouting of boot IRQs to the - primary IO-APIC for bridges that cannot disable - boot IRQs. This fixes a source of spurious IRQs - when the system masks IRQs. - noioapicreroute [APIC] Disable workaround that uses the - boot IRQ equivalent of an IRQ that connects to - a chipset where boot IRQs cannot be disabled. - The opposite of ioapicreroute. - biosirq [X86-32] Use PCI BIOS calls to get the interrupt - routing table. These calls are known to be buggy - on several machines and they hang the machine - when used, but on other computers it's the only - way to get the interrupt routing table. Try - this option if the kernel is unable to allocate - IRQs or discover secondary PCI buses on your - motherboard. - rom [X86] Assign address space to expansion ROMs. - Use with caution as certain devices share - address decoders between ROMs and other - resources. - norom [X86] Do not assign address space to - expansion ROMs that do not already have - BIOS assigned address ranges. - nobar [X86] Do not assign address space to the - BARs that weren't assigned by the BIOS. - irqmask=0xMMMM [X86] Set a bit mask of IRQs allowed to be - assigned automatically to PCI devices. You can - make the kernel exclude IRQs of your ISA cards - this way. - pirqaddr=0xAAAAA [X86] Specify the physical address - of the PIRQ table (normally generated - by the BIOS) if it is outside the - F0000h-100000h range. - lastbus=N [X86] Scan all buses thru bus #N. Can be - useful if the kernel is unable to find your - secondary buses and you want to tell it - explicitly which ones they are. - assign-busses [X86] Always assign all PCI bus - numbers ourselves, overriding - whatever the firmware may have done. - usepirqmask [X86] Honor the possible IRQ mask stored - in the BIOS $PIR table. This is needed on - some systems with broken BIOSes, notably - some HP Pavilion N5400 and Omnibook XE3 - notebooks. This will have no effect if ACPI - IRQ routing is enabled. - noacpi [X86] Do not use ACPI for IRQ routing - or for PCI scanning. - use_crs [X86] Use PCI host bridge window information - from ACPI. On BIOSes from 2008 or later, this - is enabled by default. If you need to use this, - please report a bug. - nocrs [X86] Ignore PCI host bridge windows from ACPI. - If you need to use this, please report a bug. - routeirq Do IRQ routing for all PCI devices. - This is normally done in pci_enable_device(), - so this option is a temporary workaround - for broken drivers that don't call it. - skip_isa_align [X86] do not align io start addr, so can - handle more pci cards - noearly [X86] Don't do any early type 1 scanning. - This might help on some broken boards which - machine check when some devices' config space - is read. But various workarounds are disabled - and some IOMMU drivers will not work. - bfsort Sort PCI devices into breadth-first order. - This sorting is done to get a device - order compatible with older (<= 2.4) kernels. - nobfsort Don't sort PCI devices into breadth-first order. - pcie_bus_tune_off Disable PCIe MPS (Max Payload Size) - tuning and use the BIOS-configured MPS defaults. - pcie_bus_safe Set every device's MPS to the largest value - supported by all devices below the root complex. - pcie_bus_perf Set device MPS to the largest allowable MPS - based on its parent bus. Also set MRRS (Max - Read Request Size) to the largest supported - value (no larger than the MPS that the device - or bus can support) for best performance. - pcie_bus_peer2peer Set every device's MPS to 128B, which - every device is guaranteed to support. This - configuration allows peer-to-peer DMA between - any pair of devices, possibly at the cost of - reduced performance. This also guarantees - that hot-added devices will work. - cbiosize=nn[KMG] The fixed amount of bus space which is - reserved for the CardBus bridge's IO window. - The default value is 256 bytes. - cbmemsize=nn[KMG] The fixed amount of bus space which is - reserved for the CardBus bridge's memory - window. The default value is 64 megabytes. - resource_alignment= - Format: - [@][:]:.[; ...] - [@]pci::\ - [::][; ...] - Specifies alignment and device to reassign - aligned memory resources. - If is not specified, - PAGE_SIZE is used as alignment. - PCI-PCI bridge can be specified, if resource - windows need to be expanded. - To specify the alignment for several - instances of a device, the PCI vendor, - device, subvendor, and subdevice may be - specified, e.g., 4096@pci:8086:9c22:103c:198f - ecrc= Enable/disable PCIe ECRC (transaction layer - end-to-end CRC checking). - bios: Use BIOS/firmware settings. This is the - the default. - off: Turn ECRC off - on: Turn ECRC on. - hpiosize=nn[KMG] The fixed amount of bus space which is - reserved for hotplug bridge's IO window. - Default size is 256 bytes. - hpmemsize=nn[KMG] The fixed amount of bus space which is - reserved for hotplug bridge's memory window. - Default size is 2 megabytes. - hpbussize=nn The minimum amount of additional bus numbers - reserved for buses below a hotplug bridge. - Default is 1. - realloc= Enable/disable reallocating PCI bridge resources - if allocations done by BIOS are too small to - accommodate resources required by all child - devices. - off: Turn realloc off - on: Turn realloc on - realloc same as realloc=on - noari do not use PCIe ARI. - pcie_scan_all Scan all possible PCIe devices. Otherwise we - only look for one device below a PCIe downstream - port. - - pcie_aspm= [PCIE] Forcibly enable or disable PCIe Active State Power - Management. - off Disable ASPM. - force Enable ASPM even on devices that claim not to support it. - WARNING: Forcing ASPM on may cause system lockups. - - pcie_hp= [PCIE] PCI Express Hotplug driver options: - nomsi Do not use MSI for PCI Express Native Hotplug (this - makes all PCIe ports use INTx for hotplug services). - - pcie_ports= [PCIE] PCIe ports handling: - auto Ask the BIOS whether or not to use native PCIe services - associated with PCIe ports (PME, hot-plug, AER). Use - them only if that is allowed by the BIOS. - native Use native PCIe services associated with PCIe ports - unconditionally. - compat Treat PCIe ports as PCI-to-PCI bridges, disable the PCIe - ports driver. - - pcie_port_pm= [PCIE] PCIe port power management handling: - off Disable power management of all PCIe ports - force Forcibly enable power management of all PCIe ports - - pcie_pme= [PCIE,PM] Native PCIe PME signaling options: - nomsi Do not use MSI for native PCIe PME signaling (this makes - all PCIe root ports use INTx for all services). - - pcmv= [HW,PCMCIA] BadgePAD 4 - - pd_ignore_unused - [PM] - Keep all power-domains already enabled by bootloader on, - even if no driver has claimed them. This is useful - for debug and development, but should not be - needed on a platform with proper driver support. - - pd. [PARIDE] - See Documentation/blockdev/paride.txt. - - pdcchassis= [PARISC,HW] Disable/Enable PDC Chassis Status codes at - boot time. - Format: { 0 | 1 } - See arch/parisc/kernel/pdc_chassis.c - - percpu_alloc= Select which percpu first chunk allocator to use. - Currently supported values are "embed" and "page". - Archs may support subset or none of the selections. - See comments in mm/percpu.c for details on each - allocator. This parameter is primarily for debugging - and performance comparison. - - pf. [PARIDE] - See Documentation/blockdev/paride.txt. - - pg. [PARIDE] - See Documentation/blockdev/paride.txt. - - pirq= [SMP,APIC] Manual mp-table setup - See Documentation/x86/i386/IO-APIC.txt. - - plip= [PPT,NET] Parallel port network link - Format: { parport | timid | 0 } - See also Documentation/parport.txt. - - pmtmr= [X86] Manual setup of pmtmr I/O Port. - Override pmtimer IOPort with a hex value. - e.g. pmtmr=0x508 - - pnp.debug=1 [PNP] - Enable PNP debug messages (depends on the - CONFIG_PNP_DEBUG_MESSAGES option). Change at run-time - via /sys/module/pnp/parameters/debug. We always show - current resource usage; turning this on also shows - possible settings and some assignment information. - - pnpacpi= [ACPI] - { off } - - pnpbios= [ISAPNP] - { on | off | curr | res | no-curr | no-res } - - pnp_reserve_irq= - [ISAPNP] Exclude IRQs for the autoconfiguration - - pnp_reserve_dma= - [ISAPNP] Exclude DMAs for the autoconfiguration - - pnp_reserve_io= [ISAPNP] Exclude I/O ports for the autoconfiguration - Ranges are in pairs (I/O port base and size). - - pnp_reserve_mem= - [ISAPNP] Exclude memory regions for the - autoconfiguration. - Ranges are in pairs (memory base and size). - - ports= [IP_VS_FTP] IPVS ftp helper module - Default is 21. - Up to 8 (IP_VS_APP_MAX_PORTS) ports - may be specified. - Format: ,.... - - ppc_strict_facility_enable - [PPC] This option catches any kernel floating point, - Altivec, VSX and SPE outside of regions specifically - allowed (eg kernel_enable_fpu()/kernel_disable_fpu()). - There is some performance impact when enabling this. - - print-fatal-signals= - [KNL] debug: print fatal signals - - If enabled, warn about various signal handling - related application anomalies: too many signals, - too many POSIX.1 timers, fatal signals causing a - coredump - etc. - - If you hit the warning due to signal overflow, - you might want to try "ulimit -i unlimited". - - default: off. - - printk.always_kmsg_dump= - Trigger kmsg_dump for cases other than kernel oops or - panics - Format: (1/Y/y=enable, 0/N/n=disable) - default: disabled - - printk.devkmsg={on,off,ratelimit} - Control writing to /dev/kmsg. - on - unlimited logging to /dev/kmsg from userspace - off - logging to /dev/kmsg disabled - ratelimit - ratelimit the logging - Default: ratelimit - - printk.time= Show timing data prefixed to each printk message line - Format: (1/Y/y=enable, 0/N/n=disable) - - processor.max_cstate= [HW,ACPI] - Limit processor to maximum C-state - max_cstate=9 overrides any DMI blacklist limit. - - processor.nocst [HW,ACPI] - Ignore the _CST method to determine C-states, - instead using the legacy FADT method - - profile= [KNL] Enable kernel profiling via /proc/profile - Format: [schedule,] - Param: "schedule" - profile schedule points. - Param: - step/bucket size as a power of 2 for - statistical time based profiling. - Param: "sleep" - profile D-state sleeping (millisecs). - Requires CONFIG_SCHEDSTATS - Param: "kvm" - profile VM exits. - - prompt_ramdisk= [RAM] List of RAM disks to prompt for floppy disk - before loading. - See Documentation/blockdev/ramdisk.txt. - - psmouse.proto= [HW,MOUSE] Highest PS2 mouse protocol extension to - probe for; one of (bare|imps|exps|lifebook|any). - psmouse.rate= [HW,MOUSE] Set desired mouse report rate, in reports - per second. - psmouse.resetafter= [HW,MOUSE] - Try to reset the device after so many bad packets - (0 = never). - psmouse.resolution= - [HW,MOUSE] Set desired mouse resolution, in dpi. - psmouse.smartscroll= - [HW,MOUSE] Controls Logitech smartscroll autorepeat. - 0 = disabled, 1 = enabled (default). - - pstore.backend= Specify the name of the pstore backend to use - - pt. [PARIDE] - See Documentation/blockdev/paride.txt. - - pty.legacy_count= - [KNL] Number of legacy pty's. Overwrites compiled-in - default number. - - quiet [KNL] Disable most log messages - - r128= [HW,DRM] - - raid= [HW,RAID] - See Documentation/md.txt. - - ramdisk_size= [RAM] Sizes of RAM disks in kilobytes - See Documentation/blockdev/ramdisk.txt. - - rcu_nocbs= [KNL] - The argument is a cpu list, as described above. - - In kernels built with CONFIG_RCU_NOCB_CPU=y, set - the specified list of CPUs to be no-callback CPUs. - Invocation of these CPUs' RCU callbacks will - be offloaded to "rcuox/N" kthreads created for - that purpose, where "x" is "b" for RCU-bh, "p" - for RCU-preempt, and "s" for RCU-sched, and "N" - is the CPU number. This reduces OS jitter on the - offloaded CPUs, which can be useful for HPC and - real-time workloads. It can also improve energy - efficiency for asymmetric multiprocessors. - - rcu_nocb_poll [KNL] - Rather than requiring that offloaded CPUs - (specified by rcu_nocbs= above) explicitly - awaken the corresponding "rcuoN" kthreads, - make these kthreads poll for callbacks. - This improves the real-time response for the - offloaded CPUs by relieving them of the need to - wake up the corresponding kthread, but degrades - energy efficiency by requiring that the kthreads - periodically wake up to do the polling. - - rcutree.blimit= [KNL] - Set maximum number of finished RCU callbacks to - process in one batch. - - rcutree.dump_tree= [KNL] - Dump the structure of the rcu_node combining tree - out at early boot. This is used for diagnostic - purposes, to verify correct tree setup. - - rcutree.gp_cleanup_delay= [KNL] - Set the number of jiffies to delay each step of - RCU grace-period cleanup. This only has effect - when CONFIG_RCU_TORTURE_TEST_SLOW_CLEANUP is set. - - rcutree.gp_init_delay= [KNL] - Set the number of jiffies to delay each step of - RCU grace-period initialization. This only has - effect when CONFIG_RCU_TORTURE_TEST_SLOW_INIT - is set. - - rcutree.gp_preinit_delay= [KNL] - Set the number of jiffies to delay each step of - RCU grace-period pre-initialization, that is, - the propagation of recent CPU-hotplug changes up - the rcu_node combining tree. This only has effect - when CONFIG_RCU_TORTURE_TEST_SLOW_PREINIT is set. - - rcutree.rcu_fanout_exact= [KNL] - Disable autobalancing of the rcu_node combining - tree. This is used by rcutorture, and might - possibly be useful for architectures having high - cache-to-cache transfer latencies. - - rcutree.rcu_fanout_leaf= [KNL] - Change the number of CPUs assigned to each - leaf rcu_node structure. Useful for very - large systems, which will choose the value 64, - and for NUMA systems with large remote-access - latencies, which will choose a value aligned - with the appropriate hardware boundaries. - - rcutree.jiffies_till_sched_qs= [KNL] - Set required age in jiffies for a - given grace period before RCU starts - soliciting quiescent-state help from - rcu_note_context_switch(). - - rcutree.jiffies_till_first_fqs= [KNL] - Set delay from grace-period initialization to - first attempt to force quiescent states. - Units are jiffies, minimum value is zero, - and maximum value is HZ. - - rcutree.jiffies_till_next_fqs= [KNL] - Set delay between subsequent attempts to force - quiescent states. Units are jiffies, minimum - value is one, and maximum value is HZ. - - rcutree.kthread_prio= [KNL,BOOT] - Set the SCHED_FIFO priority of the RCU per-CPU - kthreads (rcuc/N). This value is also used for - the priority of the RCU boost threads (rcub/N) - and for the RCU grace-period kthreads (rcu_bh, - rcu_preempt, and rcu_sched). If RCU_BOOST is - set, valid values are 1-99 and the default is 1 - (the least-favored priority). Otherwise, when - RCU_BOOST is not set, valid values are 0-99 and - the default is zero (non-realtime operation). - - rcutree.rcu_nocb_leader_stride= [KNL] - Set the number of NOCB kthread groups, which - defaults to the square root of the number of - CPUs. Larger numbers reduces the wakeup overhead - on the per-CPU grace-period kthreads, but increases - that same overhead on each group's leader. - - rcutree.qhimark= [KNL] - Set threshold of queued RCU callbacks beyond which - batch limiting is disabled. - - rcutree.qlowmark= [KNL] - Set threshold of queued RCU callbacks below which - batch limiting is re-enabled. - - rcutree.rcu_idle_gp_delay= [KNL] - Set wakeup interval for idle CPUs that have - RCU callbacks (RCU_FAST_NO_HZ=y). - - rcutree.rcu_idle_lazy_gp_delay= [KNL] - Set wakeup interval for idle CPUs that have - only "lazy" RCU callbacks (RCU_FAST_NO_HZ=y). - Lazy RCU callbacks are those which RCU can - prove do nothing more than free memory. - - rcuperf.gp_exp= [KNL] - Measure performance of expedited synchronous - grace-period primitives. - - rcuperf.holdoff= [KNL] - Set test-start holdoff period. The purpose of - this parameter is to delay the start of the - test until boot completes in order to avoid - interference. - - rcuperf.nreaders= [KNL] - Set number of RCU readers. The value -1 selects - N, where N is the number of CPUs. A value - "n" less than -1 selects N-n+1, where N is again - the number of CPUs. For example, -2 selects N - (the number of CPUs), -3 selects N+1, and so on. - A value of "n" less than or equal to -N selects - a single reader. - - rcuperf.nwriters= [KNL] - Set number of RCU writers. The values operate - the same as for rcuperf.nreaders. - N, where N is the number of CPUs - - rcuperf.perf_runnable= [BOOT] - Start rcuperf running at boot time. - - rcuperf.shutdown= [KNL] - Shut the system down after performance tests - complete. This is useful for hands-off automated - testing. - - rcuperf.perf_type= [KNL] - Specify the RCU implementation to test. - - rcuperf.verbose= [KNL] - Enable additional printk() statements. - - rcutorture.cbflood_inter_holdoff= [KNL] - Set holdoff time (jiffies) between successive - callback-flood tests. - - rcutorture.cbflood_intra_holdoff= [KNL] - Set holdoff time (jiffies) between successive - bursts of callbacks within a given callback-flood - test. - - rcutorture.cbflood_n_burst= [KNL] - Set the number of bursts making up a given - callback-flood test. Set this to zero to - disable callback-flood testing. - - rcutorture.cbflood_n_per_burst= [KNL] - Set the number of callbacks to be registered - in a given burst of a callback-flood test. - - rcutorture.fqs_duration= [KNL] - Set duration of force_quiescent_state bursts - in microseconds. - - rcutorture.fqs_holdoff= [KNL] - Set holdoff time within force_quiescent_state bursts - in microseconds. - - rcutorture.fqs_stutter= [KNL] - Set wait time between force_quiescent_state bursts - in seconds. - - rcutorture.gp_cond= [KNL] - Use conditional/asynchronous update-side - primitives, if available. - - rcutorture.gp_exp= [KNL] - Use expedited update-side primitives, if available. - - rcutorture.gp_normal= [KNL] - Use normal (non-expedited) asynchronous - update-side primitives, if available. - - rcutorture.gp_sync= [KNL] - Use normal (non-expedited) synchronous - update-side primitives, if available. If all - of rcutorture.gp_cond=, rcutorture.gp_exp=, - rcutorture.gp_normal=, and rcutorture.gp_sync= - are zero, rcutorture acts as if is interpreted - they are all non-zero. - - rcutorture.n_barrier_cbs= [KNL] - Set callbacks/threads for rcu_barrier() testing. - - rcutorture.nfakewriters= [KNL] - Set number of concurrent RCU writers. These just - stress RCU, they don't participate in the actual - test, hence the "fake". - - rcutorture.nreaders= [KNL] - Set number of RCU readers. The value -1 selects - N-1, where N is the number of CPUs. A value - "n" less than -1 selects N-n-2, where N is again - the number of CPUs. For example, -2 selects N - (the number of CPUs), -3 selects N+1, and so on. - - rcutorture.object_debug= [KNL] - Enable debug-object double-call_rcu() testing. - - rcutorture.onoff_holdoff= [KNL] - Set time (s) after boot for CPU-hotplug testing. - - rcutorture.onoff_interval= [KNL] - Set time (s) between CPU-hotplug operations, or - zero to disable CPU-hotplug testing. - - rcutorture.shuffle_interval= [KNL] - Set task-shuffle interval (s). Shuffling tasks - allows some CPUs to go into dyntick-idle mode - during the rcutorture test. - - rcutorture.shutdown_secs= [KNL] - Set time (s) after boot system shutdown. This - is useful for hands-off automated testing. - - rcutorture.stall_cpu= [KNL] - Duration of CPU stall (s) to test RCU CPU stall - warnings, zero to disable. - - rcutorture.stall_cpu_holdoff= [KNL] - Time to wait (s) after boot before inducing stall. - - rcutorture.stat_interval= [KNL] - Time (s) between statistics printk()s. - - rcutorture.stutter= [KNL] - Time (s) to stutter testing, for example, specifying - five seconds causes the test to run for five seconds, - wait for five seconds, and so on. This tests RCU's - ability to transition abruptly to and from idle. - - rcutorture.test_boost= [KNL] - Test RCU priority boosting? 0=no, 1=maybe, 2=yes. - "Maybe" means test if the RCU implementation - under test support RCU priority boosting. - - rcutorture.test_boost_duration= [KNL] - Duration (s) of each individual boost test. - - rcutorture.test_boost_interval= [KNL] - Interval (s) between each boost test. - - rcutorture.test_no_idle_hz= [KNL] - Test RCU's dyntick-idle handling. See also the - rcutorture.shuffle_interval parameter. - - rcutorture.torture_runnable= [BOOT] - Start rcutorture running at boot time. - - rcutorture.torture_type= [KNL] - Specify the RCU implementation to test. - - rcutorture.verbose= [KNL] - Enable additional printk() statements. - - rcupdate.rcu_cpu_stall_suppress= [KNL] - Suppress RCU CPU stall warning messages. - - rcupdate.rcu_cpu_stall_timeout= [KNL] - Set timeout for RCU CPU stall warning messages. - - rcupdate.rcu_expedited= [KNL] - Use expedited grace-period primitives, for - example, synchronize_rcu_expedited() instead - of synchronize_rcu(). This reduces latency, - but can increase CPU utilization, degrade - real-time latency, and degrade energy efficiency. - No effect on CONFIG_TINY_RCU kernels. - - rcupdate.rcu_normal= [KNL] - Use only normal grace-period primitives, - for example, synchronize_rcu() instead of - synchronize_rcu_expedited(). This improves - real-time latency, CPU utilization, and - energy efficiency, but can expose users to - increased grace-period latency. This parameter - overrides rcupdate.rcu_expedited. No effect on - CONFIG_TINY_RCU kernels. - - rcupdate.rcu_normal_after_boot= [KNL] - Once boot has completed (that is, after - rcu_end_inkernel_boot() has been invoked), use - only normal grace-period primitives. No effect - on CONFIG_TINY_RCU kernels. - - rcupdate.rcu_task_stall_timeout= [KNL] - Set timeout in jiffies for RCU task stall warning - messages. Disable with a value less than or equal - to zero. - - rcupdate.rcu_self_test= [KNL] - Run the RCU early boot self tests - - rcupdate.rcu_self_test_bh= [KNL] - Run the RCU bh early boot self tests - - rcupdate.rcu_self_test_sched= [KNL] - Run the RCU sched early boot self tests - - rdinit= [KNL] - Format: - Run specified binary instead of /init from the ramdisk, - used for early userspace startup. See initrd. - - reboot= [KNL] - Format (x86 or x86_64): - [w[arm] | c[old] | h[ard] | s[oft] | g[pio]] \ - [[,]s[mp]#### \ - [[,]b[ios] | a[cpi] | k[bd] | t[riple] | e[fi] | p[ci]] \ - [[,]f[orce] - Where reboot_mode is one of warm (soft) or cold (hard) or gpio, - reboot_type is one of bios, acpi, kbd, triple, efi, or pci, - reboot_force is either force or not specified, - reboot_cpu is s[mp]#### with #### being the processor - to be used for rebooting. - - relax_domain_level= - [KNL, SMP] Set scheduler's default relax_domain_level. - See Documentation/cgroup-v1/cpusets.txt. - - relative_sleep_states= - [SUSPEND] Use sleep state labeling where the deepest - state available other than hibernation is always "mem". - Format: { "0" | "1" } - 0 -- Traditional sleep state labels. - 1 -- Relative sleep state labels. - - reserve= [KNL,BUGS] Force the kernel to ignore some iomem area - - reservetop= [X86-32] - Format: nn[KMG] - Reserves a hole at the top of the kernel virtual - address space. - - reservelow= [X86] - Format: nn[K] - Set the amount of memory to reserve for BIOS at - the bottom of the address space. - - reset_devices [KNL] Force drivers to reset the underlying device - during initialization. - - resume= [SWSUSP] - Specify the partition device for software suspend - Format: - {/dev/ | PARTUUID= | : | } - - resume_offset= [SWSUSP] - Specify the offset from the beginning of the partition - given by "resume=" at which the swap header is located, - in units (needed only for swap files). - See Documentation/power/swsusp-and-swap-files.txt - - resumedelay= [HIBERNATION] Delay (in seconds) to pause before attempting to - read the resume files - - resumewait [HIBERNATION] Wait (indefinitely) for resume device to show up. - Useful for devices that are detected asynchronously - (e.g. USB and MMC devices). - - hibernate= [HIBERNATION] - noresume Don't check if there's a hibernation image - present during boot. - nocompress Don't compress/decompress hibernation images. - no Disable hibernation and resume. - protect_image Turn on image protection during restoration - (that will set all pages holding image data - during restoration read-only). - - retain_initrd [RAM] Keep initrd memory after extraction - - rfkill.default_state= - 0 "airplane mode". All wifi, bluetooth, wimax, gps, fm, - etc. communication is blocked by default. - 1 Unblocked. - - rfkill.master_switch_mode= - 0 The "airplane mode" button does nothing. - 1 The "airplane mode" button toggles between everything - blocked and the previous configuration. - 2 The "airplane mode" button toggles between everything - blocked and everything unblocked. - - rhash_entries= [KNL,NET] - Set number of hash buckets for route cache - - ro [KNL] Mount root device read-only on boot - - rodata= [KNL] - on Mark read-only kernel memory as read-only (default). - off Leave read-only kernel memory writable for debugging. - - rockchip.usb_uart - Enable the uart passthrough on the designated usb port - on Rockchip SoCs. When active, the signals of the - debug-uart get routed to the D+ and D- pins of the usb - port and the regular usb controller gets disabled. - - root= [KNL] Root filesystem - See name_to_dev_t comment in init/do_mounts.c. - - rootdelay= [KNL] Delay (in seconds) to pause before attempting to - mount the root filesystem - - rootflags= [KNL] Set root filesystem mount option string - - rootfstype= [KNL] Set root filesystem type - - rootwait [KNL] Wait (indefinitely) for root device to show up. - Useful for devices that are detected asynchronously - (e.g. USB and MMC devices). - - rproc_mem=nn[KMG][@address] - [KNL,ARM,CMA] Remoteproc physical memory block. - Memory area to be used by remote processor image, - managed by CMA. - - rw [KNL] Mount root device read-write on boot - - S [KNL] Run init in single mode - - s390_iommu= [HW,S390] - Set s390 IOTLB flushing mode - strict - With strict flushing every unmap operation will result in - an IOTLB flush. Default is lazy flushing before reuse, - which is faster. - - sa1100ir [NET] - See drivers/net/irda/sa1100_ir.c. - - sbni= [NET] Granch SBNI12 leased line adapter - - sched_debug [KNL] Enables verbose scheduler debug messages. - - schedstats= [KNL,X86] Enable or disable scheduled statistics. - Allowed values are enable and disable. This feature - incurs a small amount of overhead in the scheduler - but is useful for debugging and performance tuning. - - skew_tick= [KNL] Offset the periodic timer tick per cpu to mitigate - xtime_lock contention on larger systems, and/or RCU lock - contention on all systems with CONFIG_MAXSMP set. - Format: { "0" | "1" } - 0 -- disable. (may be 1 via CONFIG_CMDLINE="skew_tick=1" - 1 -- enable. - Note: increases power consumption, thus should only be - enabled if running jitter sensitive (HPC/RT) workloads. - - security= [SECURITY] Choose a security module to enable at boot. - If this boot parameter is not specified, only the first - security module asking for security registration will be - loaded. An invalid security module name will be treated - as if no module has been chosen. - - selinux= [SELINUX] Disable or enable SELinux at boot time. - Format: { "0" | "1" } - See security/selinux/Kconfig help text. - 0 -- disable. - 1 -- enable. - Default value is set via kernel config option. - If enabled at boot time, /selinux/disable can be used - later to disable prior to initial policy load. - - apparmor= [APPARMOR] Disable or enable AppArmor at boot time - Format: { "0" | "1" } - See security/apparmor/Kconfig help text - 0 -- disable. - 1 -- enable. - Default value is set via kernel config option. - - serialnumber [BUGS=X86-32] - - shapers= [NET] - Maximal number of shapers. - - show_msr= [x86] show boot-time MSR settings - Format: { } - Show boot-time (BIOS-initialized) MSR settings. - The parameter means the number of CPUs to show, - for example 1 means boot CPU only. - - simeth= [IA-64] - simscsi= - - slram= [HW,MTD] - - slab_nomerge [MM] - Disable merging of slabs with similar size. May be - necessary if there is some reason to distinguish - allocs to different slabs. Debug options disable - merging on their own. - For more information see Documentation/vm/slub.txt. - - slab_max_order= [MM, SLAB] - Determines the maximum allowed order for slabs. - A high setting may cause OOMs due to memory - fragmentation. Defaults to 1 for systems with - more than 32MB of RAM, 0 otherwise. - - slub_debug[=options[,slabs]] [MM, SLUB] - Enabling slub_debug allows one to determine the - culprit if slab objects become corrupted. Enabling - slub_debug can create guard zones around objects and - may poison objects when not in use. Also tracks the - last alloc / free. For more information see - Documentation/vm/slub.txt. - - slub_max_order= [MM, SLUB] - Determines the maximum allowed order for slabs. - A high setting may cause OOMs due to memory - fragmentation. For more information see - Documentation/vm/slub.txt. - - slub_min_objects= [MM, SLUB] - The minimum number of objects per slab. SLUB will - increase the slab order up to slub_max_order to - generate a sufficiently large slab able to contain - the number of objects indicated. The higher the number - of objects the smaller the overhead of tracking slabs - and the less frequently locks need to be acquired. - For more information see Documentation/vm/slub.txt. - - slub_min_order= [MM, SLUB] - Determines the minimum page order for slabs. Must be - lower than slub_max_order. - For more information see Documentation/vm/slub.txt. - - slub_nomerge [MM, SLUB] - Same with slab_nomerge. This is supported for legacy. - See slab_nomerge for more information. - - smart2= [HW] - Format: [,[,...,]] - - smsc-ircc2.nopnp [HW] Don't use PNP to discover SMC devices - smsc-ircc2.ircc_cfg= [HW] Device configuration I/O port - smsc-ircc2.ircc_sir= [HW] SIR base I/O port - smsc-ircc2.ircc_fir= [HW] FIR base I/O port - smsc-ircc2.ircc_irq= [HW] IRQ line - smsc-ircc2.ircc_dma= [HW] DMA channel - smsc-ircc2.ircc_transceiver= [HW] Transceiver type: - 0: Toshiba Satellite 1800 (GP data pin select) - 1: Fast pin select (default) - 2: ATC IRMode - - smt [KNL,S390] Set the maximum number of threads (logical - CPUs) to use per physical CPU on systems capable of - symmetric multithreading (SMT). Will be capped to the - actual hardware limit. - Format: - Default: -1 (no limit) - - softlockup_panic= - [KNL] Should the soft-lockup detector generate panics. - Format: - - softlockup_all_cpu_backtrace= - [KNL] Should the soft-lockup detector generate - backtraces on all cpus. - Format: - - sonypi.*= [HW] Sony Programmable I/O Control Device driver - See Documentation/laptops/sonypi.txt - - spia_io_base= [HW,MTD] - spia_fio_base= - spia_pedr= - spia_peddr= - - stacktrace [FTRACE] - Enabled the stack tracer on boot up. - - stacktrace_filter=[function-list] - [FTRACE] Limit the functions that the stack tracer - will trace at boot up. function-list is a comma separated - list of functions. This list can be changed at run - time by the stack_trace_filter file in the debugfs - tracing directory. Note, this enables stack tracing - and the stacktrace above is not needed. - - sti= [PARISC,HW] - Format: - Set the STI (builtin display/keyboard on the HP-PARISC - machines) console (graphic card) which should be used - as the initial boot-console. - See also comment in drivers/video/console/sticore.c. - - sti_font= [HW] - See comment in drivers/video/console/sticore.c. - - stifb= [HW] - Format: bpp:[:[:...]] - - sunrpc.min_resvport= - sunrpc.max_resvport= - [NFS,SUNRPC] - SunRPC servers often require that client requests - originate from a privileged port (i.e. a port in the - range 0 < portnr < 1024). - An administrator who wishes to reserve some of these - ports for other uses may adjust the range that the - kernel's sunrpc client considers to be privileged - using these two parameters to set the minimum and - maximum port values. - - sunrpc.svc_rpc_per_connection_limit= - [NFS,SUNRPC] - Limit the number of requests that the server will - process in parallel from a single connection. - The default value is 0 (no limit). - - sunrpc.pool_mode= - [NFS] - Control how the NFS server code allocates CPUs to - service thread pools. Depending on how many NICs - you have and where their interrupts are bound, this - option will affect which CPUs will do NFS serving. - Note: this parameter cannot be changed while the - NFS server is running. - - auto the server chooses an appropriate mode - automatically using heuristics - global a single global pool contains all CPUs - percpu one pool for each CPU - pernode one pool for each NUMA node (equivalent - to global on non-NUMA machines) - - sunrpc.tcp_slot_table_entries= - sunrpc.udp_slot_table_entries= - [NFS,SUNRPC] - Sets the upper limit on the number of simultaneous - RPC calls that can be sent from the client to a - server. Increasing these values may allow you to - improve throughput, but will also increase the - amount of memory reserved for use by the client. - - suspend.pm_test_delay= - [SUSPEND] - Sets the number of seconds to remain in a suspend test - mode before resuming the system (see - /sys/power/pm_test). Only available when CONFIG_PM_DEBUG - is set. Default value is 5. - - swapaccount=[0|1] - [KNL] Enable accounting of swap in memory resource - controller if no parameter or 1 is given or disable - it if 0 is given (See Documentation/cgroup-v1/memory.txt) - - swiotlb= [ARM,IA-64,PPC,MIPS,X86] - Format: { | force } - -- Number of I/O TLB slabs - force -- force using of bounce buffers even if they - wouldn't be automatically used by the kernel - - switches= [HW,M68k] - - sysfs.deprecated=0|1 [KNL] - Enable/disable old style sysfs layout for old udev - on older distributions. When this option is enabled - very new udev will not work anymore. When this option - is disabled (or CONFIG_SYSFS_DEPRECATED not compiled) - in older udev will not work anymore. - Default depends on CONFIG_SYSFS_DEPRECATED_V2 set in - the kernel configuration. - - sysrq_always_enabled - [KNL] - Ignore sysrq setting - this boot parameter will - neutralize any effect of /proc/sys/kernel/sysrq. - Useful for debugging. - - tcpmhash_entries= [KNL,NET] - Set the number of tcp_metrics_hash slots. - Default value is 8192 or 16384 depending on total - ram pages. This is used to specify the TCP metrics - cache size. See Documentation/networking/ip-sysctl.txt - "tcp_no_metrics_save" section for more details. - - tdfx= [HW,DRM] - - test_suspend= [SUSPEND][,N] - Specify "mem" (for Suspend-to-RAM) or "standby" (for - standby suspend) or "freeze" (for suspend type freeze) - as the system sleep state during system startup with - the optional capability to repeat N number of times. - The system is woken from this state using a - wakeup-capable RTC alarm. - - thash_entries= [KNL,NET] - Set number of hash buckets for TCP connection - - thermal.act= [HW,ACPI] - -1: disable all active trip points in all thermal zones - : override all lowest active trip points - - thermal.crt= [HW,ACPI] - -1: disable all critical trip points in all thermal zones - : override all critical trip points - - thermal.nocrt= [HW,ACPI] - Set to disable actions on ACPI thermal zone - critical and hot trip points. - - thermal.off= [HW,ACPI] - 1: disable ACPI thermal control - - thermal.psv= [HW,ACPI] - -1: disable all passive trip points - : override all passive trip points to this - value - - thermal.tzp= [HW,ACPI] - Specify global default ACPI thermal zone polling rate - : poll all this frequency - 0: no polling (default) - - threadirqs [KNL] - Force threading of all interrupt handlers except those - marked explicitly IRQF_NO_THREAD. - - tmem [KNL,XEN] - Enable the Transcendent memory driver if built-in. - - tmem.cleancache=0|1 [KNL, XEN] - Default is on (1). Disable the usage of the cleancache - API to send anonymous pages to the hypervisor. - - tmem.frontswap=0|1 [KNL, XEN] - Default is on (1). Disable the usage of the frontswap - API to send swap pages to the hypervisor. If disabled - the selfballooning and selfshrinking are force disabled. - - tmem.selfballooning=0|1 [KNL, XEN] - Default is on (1). Disable the driving of swap pages - to the hypervisor. - - tmem.selfshrinking=0|1 [KNL, XEN] - Default is on (1). Partial swapoff that immediately - transfers pages from Xen hypervisor back to the - kernel based on different criteria. - - topology= [S390] - Format: {off | on} - Specify if the kernel should make use of the cpu - topology information if the hardware supports this. - The scheduler will make use of this information and - e.g. base its process migration decisions on it. - Default is on. - - topology_updates= [KNL, PPC, NUMA] - Format: {off} - Specify if the kernel should ignore (off) - topology updates sent by the hypervisor to this - LPAR. - - tp720= [HW,PS2] - - tpm_suspend_pcr=[HW,TPM] - Format: integer pcr id - Specify that at suspend time, the tpm driver - should extend the specified pcr with zeros, - as a workaround for some chips which fail to - flush the last written pcr on TPM_SaveState. - This will guarantee that all the other pcrs - are saved. - - trace_buf_size=nn[KMG] - [FTRACE] will set tracing buffer size on each cpu. - - trace_event=[event-list] - [FTRACE] Set and start specified trace events in order - to facilitate early boot debugging. The event-list is a - comma separated list of trace events to enable. See - also Documentation/trace/events.txt - - trace_options=[option-list] - [FTRACE] Enable or disable tracer options at boot. - The option-list is a comma delimited list of options - that can be enabled or disabled just as if you were - to echo the option name into - - /sys/kernel/debug/tracing/trace_options - - For example, to enable stacktrace option (to dump the - stack trace of each event), add to the command line: - - trace_options=stacktrace - - See also Documentation/trace/ftrace.txt "trace options" - section. - - tp_printk[FTRACE] - Have the tracepoints sent to printk as well as the - tracing ring buffer. This is useful for early boot up - where the system hangs or reboots and does not give the - option for reading the tracing buffer or performing a - ftrace_dump_on_oops. - - To turn off having tracepoints sent to printk, - echo 0 > /proc/sys/kernel/tracepoint_printk - Note, echoing 1 into this file without the - tracepoint_printk kernel cmdline option has no effect. - - ** CAUTION ** - - Having tracepoints sent to printk() and activating high - frequency tracepoints such as irq or sched, can cause - the system to live lock. - - traceoff_on_warning - [FTRACE] enable this option to disable tracing when a - warning is hit. This turns off "tracing_on". Tracing can - be enabled again by echoing '1' into the "tracing_on" - file located in /sys/kernel/debug/tracing/ - - This option is useful, as it disables the trace before - the WARNING dump is called, which prevents the trace to - be filled with content caused by the warning output. - - This option can also be set at run time via the sysctl - option: kernel/traceoff_on_warning - - transparent_hugepage= - [KNL] - Format: [always|madvise|never] - Can be used to control the default behavior of the system - with respect to transparent hugepages. - See Documentation/vm/transhuge.txt for more details. - - tsc= Disable clocksource stability checks for TSC. - Format: - [x86] reliable: mark tsc clocksource as reliable, this - disables clocksource verification at runtime, as well - as the stability checks done at bootup. Used to enable - high-resolution timer mode on older hardware, and in - virtualized environment. - [x86] noirqtime: Do not use TSC to do irq accounting. - Used to run time disable IRQ_TIME_ACCOUNTING on any - platforms where RDTSC is slow and this accounting - can add overhead. - - turbografx.map[2|3]= [HW,JOY] - TurboGraFX parallel port interface - Format: - ,,,,,,, - See also Documentation/input/joystick-parport.txt - - udbg-immortal [PPC] When debugging early kernel crashes that - happen after console_init() and before a proper - console driver takes over, this boot options might - help "seeing" what's going on. - - uhash_entries= [KNL,NET] - Set number of hash buckets for UDP/UDP-Lite connections - - uhci-hcd.ignore_oc= - [USB] Ignore overcurrent events (default N). - Some badly-designed motherboards generate lots of - bogus events, for ports that aren't wired to - anything. Set this parameter to avoid log spamming. - Note that genuine overcurrent events won't be - reported either. - - unknown_nmi_panic - [X86] Cause panic on unknown NMI. - - usbcore.authorized_default= - [USB] Default USB device authorization: - (default -1 = authorized except for wireless USB, - 0 = not authorized, 1 = authorized) - - usbcore.autosuspend= - [USB] The autosuspend time delay (in seconds) used - for newly-detected USB devices (default 2). This - is the time required before an idle device will be - autosuspended. Devices for which the delay is set - to a negative value won't be autosuspended at all. - - usbcore.usbfs_snoop= - [USB] Set to log all usbfs traffic (default 0 = off). - - usbcore.usbfs_snoop_max= - [USB] Maximum number of bytes to snoop in each URB - (default = 65536). - - usbcore.blinkenlights= - [USB] Set to cycle leds on hubs (default 0 = off). - - usbcore.old_scheme_first= - [USB] Start with the old device initialization - scheme (default 0 = off). - - usbcore.usbfs_memory_mb= - [USB] Memory limit (in MB) for buffers allocated by - usbfs (default = 16, 0 = max = 2047). - - usbcore.use_both_schemes= - [USB] Try the other device initialization scheme - if the first one fails (default 1 = enabled). - - usbcore.initial_descriptor_timeout= - [USB] Specifies timeout for the initial 64-byte - USB_REQ_GET_DESCRIPTOR request in milliseconds - (default 5000 = 5.0 seconds). - - usbcore.nousb [USB] Disable the USB subsystem - - usbhid.mousepoll= - [USBHID] The interval which mice are to be polled at. - - usb-storage.delay_use= - [UMS] The delay in seconds before a new device is - scanned for Logical Units (default 1). - - usb-storage.quirks= - [UMS] A list of quirks entries to supplement or - override the built-in unusual_devs list. List - entries are separated by commas. Each entry has - the form VID:PID:Flags where VID and PID are Vendor - and Product ID values (4-digit hex numbers) and - Flags is a set of characters, each corresponding - to a common usb-storage quirk flag as follows: - a = SANE_SENSE (collect more than 18 bytes - of sense data); - b = BAD_SENSE (don't collect more than 18 - bytes of sense data); - c = FIX_CAPACITY (decrease the reported - device capacity by one sector); - d = NO_READ_DISC_INFO (don't use - READ_DISC_INFO command); - e = NO_READ_CAPACITY_16 (don't use - READ_CAPACITY_16 command); - f = NO_REPORT_OPCODES (don't use report opcodes - command, uas only); - g = MAX_SECTORS_240 (don't transfer more than - 240 sectors at a time, uas only); - h = CAPACITY_HEURISTICS (decrease the - reported device capacity by one - sector if the number is odd); - i = IGNORE_DEVICE (don't bind to this - device); - j = NO_REPORT_LUNS (don't use report luns - command, uas only); - l = NOT_LOCKABLE (don't try to lock and - unlock ejectable media); - m = MAX_SECTORS_64 (don't transfer more - than 64 sectors = 32 KB at a time); - n = INITIAL_READ10 (force a retry of the - initial READ(10) command); - o = CAPACITY_OK (accept the capacity - reported by the device); - p = WRITE_CACHE (the device cache is ON - by default); - r = IGNORE_RESIDUE (the device reports - bogus residue values); - s = SINGLE_LUN (the device has only one - Logical Unit); - t = NO_ATA_1X (don't allow ATA(12) and ATA(16) - commands, uas only); - u = IGNORE_UAS (don't bind to the uas driver); - w = NO_WP_DETECT (don't test whether the - medium is write-protected). - y = ALWAYS_SYNC (issue a SYNCHRONIZE_CACHE - even if the device claims no cache) - Example: quirks=0419:aaf5:rl,0421:0433:rc - - user_debug= [KNL,ARM] - Format: - See arch/arm/Kconfig.debug help text. - 1 - undefined instruction events - 2 - system calls - 4 - invalid data aborts - 8 - SIGSEGV faults - 16 - SIGBUS faults - Example: user_debug=31 - - userpte= - [X86] Flags controlling user PTE allocations. - - nohigh = do not allocate PTE pages in - HIGHMEM regardless of setting - of CONFIG_HIGHPTE. - - vdso= [X86,SH] - On X86_32, this is an alias for vdso32=. Otherwise: - - vdso=1: enable VDSO (the default) - vdso=0: disable VDSO mapping - - vdso32= [X86] Control the 32-bit vDSO - vdso32=1: enable 32-bit VDSO - vdso32=0 or vdso32=2: disable 32-bit VDSO - - See the help text for CONFIG_COMPAT_VDSO for more - details. If CONFIG_COMPAT_VDSO is set, the default is - vdso32=0; otherwise, the default is vdso32=1. - - For compatibility with older kernels, vdso32=2 is an - alias for vdso32=0. - - Try vdso32=0 if you encounter an error that says: - dl_main: Assertion `(void *) ph->p_vaddr == _rtld_local._dl_sysinfo_dso' failed! - - vector= [IA-64,SMP] - vector=percpu: enable percpu vector domain - - video= [FB] Frame buffer configuration - See Documentation/fb/modedb.txt. - - video.brightness_switch_enabled= [0,1] - If set to 1, on receiving an ACPI notify event - generated by hotkey, video driver will adjust brightness - level and then send out the event to user space through - the allocated input device; If set to 0, video driver - will only send out the event without touching backlight - brightness level. - default: 1 - - virtio_mmio.device= - [VMMIO] Memory mapped virtio (platform) device. - - @:[:] - where: - := size (can use standard suffixes - like K, M and G) - := physical base address - := interrupt number (as passed to - request_irq()) - := (optional) platform device id - example: - virtio_mmio.device=1K@0x100b0000:48:7 - - Can be used multiple times for multiple devices. - - vga= [BOOT,X86-32] Select a particular video mode - See Documentation/x86/boot.txt and - Documentation/svga.txt. - Use vga=ask for menu. - This is actually a boot loader parameter; the value is - passed to the kernel using a special protocol. - - vmalloc=nn[KMG] [KNL,BOOT] Forces the vmalloc area to have an exact - size of . This can be used to increase the - minimum size (128MB on x86). It can also be used to - decrease the size and leave more room for directly - mapped kernel RAM. - - vmhalt= [KNL,S390] Perform z/VM CP command after system halt. - Format: - - vmpanic= [KNL,S390] Perform z/VM CP command after kernel panic. - Format: - - vmpoff= [KNL,S390] Perform z/VM CP command after power off. - Format: - - vsyscall= [X86-64] - Controls the behavior of vsyscalls (i.e. calls to - fixed addresses of 0xffffffffff600x00 from legacy - code). Most statically-linked binaries and older - versions of glibc use these calls. Because these - functions are at fixed addresses, they make nice - targets for exploits that can control RIP. - - emulate [default] Vsyscalls turn into traps and are - emulated reasonably safely. - - native Vsyscalls are native syscall instructions. - This is a little bit faster than trapping - and makes a few dynamic recompilers work - better than they would in emulation mode. - It also makes exploits much easier to write. - - none Vsyscalls don't work at all. This makes - them quite hard to use for exploits but - might break your system. - - vt.color= [VT] Default text color. - Format: 0xYX, X = foreground, Y = background. - Default: 0x07 = light gray on black. - - vt.cur_default= [VT] Default cursor shape. - Format: 0xCCBBAA, where AA, BB, and CC are the same as - the parameters of the [?A;B;Cc escape sequence; - see VGA-softcursor.txt. Default: 2 = underline. - - vt.default_blu= [VT] - Format: ,,,..., - Change the default blue palette of the console. - This is a 16-member array composed of values - ranging from 0-255. - - vt.default_grn= [VT] - Format: ,,,..., - Change the default green palette of the console. - This is a 16-member array composed of values - ranging from 0-255. - - vt.default_red= [VT] - Format: ,,,..., - Change the default red palette of the console. - This is a 16-member array composed of values - ranging from 0-255. - - vt.default_utf8= - [VT] - Format=<0|1> - Set system-wide default UTF-8 mode for all tty's. - Default is 1, i.e. UTF-8 mode is enabled for all - newly opened terminals. - - vt.global_cursor_default= - [VT] - Format=<-1|0|1> - Set system-wide default for whether a cursor - is shown on new VTs. Default is -1, - i.e. cursors will be created by default unless - overridden by individual drivers. 0 will hide - cursors, 1 will display them. - - vt.italic= [VT] Default color for italic text; 0-15. - Default: 2 = green. - - vt.underline= [VT] Default color for underlined text; 0-15. - Default: 3 = cyan. - - watchdog timers [HW,WDT] For information on watchdog timers, - see Documentation/watchdog/watchdog-parameters.txt - or other driver-specific files in the - Documentation/watchdog/ directory. - - workqueue.watchdog_thresh= - If CONFIG_WQ_WATCHDOG is configured, workqueue can - warn stall conditions and dump internal state to - help debugging. 0 disables workqueue stall - detection; otherwise, it's the stall threshold - duration in seconds. The default value is 30 and - it can be updated at runtime by writing to the - corresponding sysfs file. - - workqueue.disable_numa - By default, all work items queued to unbound - workqueues are affine to the NUMA nodes they're - issued on, which results in better behavior in - general. If NUMA affinity needs to be disabled for - whatever reason, this option can be used. Note - that this also can be controlled per-workqueue for - workqueues visible under /sys/bus/workqueue/. - - workqueue.power_efficient - Per-cpu workqueues are generally preferred because - they show better performance thanks to cache - locality; unfortunately, per-cpu workqueues tend to - be more power hungry than unbound workqueues. - - Enabling this makes the per-cpu workqueues which - were observed to contribute significantly to power - consumption unbound, leading to measurably lower - power usage at the cost of small performance - overhead. - - The default value of this parameter is determined by - the config option CONFIG_WQ_POWER_EFFICIENT_DEFAULT. - - workqueue.debug_force_rr_cpu - Workqueue used to implicitly guarantee that work - items queued without explicit CPU specified are put - on the local CPU. This guarantee is no longer true - and while local CPU is still preferred work items - may be put on foreign CPUs. This debug option - forces round-robin CPU selection to flush out - usages which depend on the now broken guarantee. - When enabled, memory and cache locality will be - impacted. - - x2apic_phys [X86-64,APIC] Use x2apic physical mode instead of - default x2apic cluster mode on platforms - supporting x2apic. - - x86_intel_mid_timer= [X86-32,APBT] - Choose timer option for x86 Intel MID platform. - Two valid options are apbt timer only and lapic timer - plus one apbt timer for broadcast timer. - x86_intel_mid_timer=apbt_only | lapic_and_apbt - - xen_512gb_limit [KNL,X86-64,XEN] - Restricts the kernel running paravirtualized under Xen - to use only up to 512 GB of RAM. The reason to do so is - crash analysis tools and Xen tools for doing domain - save/restore/migration must be enabled to handle larger - domains. - - xen_emul_unplug= [HW,X86,XEN] - Unplug Xen emulated devices - Format: [unplug0,][unplug1] - ide-disks -- unplug primary master IDE devices - aux-ide-disks -- unplug non-primary-master IDE devices - nics -- unplug network devices - all -- unplug all emulated devices (NICs and IDE disks) - unnecessary -- unplugging emulated devices is - unnecessary even if the host did not respond to - the unplug protocol - never -- do not unplug even if version check succeeds - - xen_nopvspin [X86,XEN] - Disables the ticketlock slowpath using Xen PV - optimizations. - - xen_nopv [X86] - Disables the PV optimizations forcing the HVM guest to - run as generic HVM guest with no PV drivers. - - xirc2ps_cs= [NET,PCMCIA] - Format: - ,,,,,[,[,[,]]] - ------------------------- - -Todo ----- - - Add more DRM drivers. diff --git a/Documentation/md.txt b/Documentation/md.txt deleted file mode 100644 index e449fb5f277c..000000000000 --- a/Documentation/md.txt +++ /dev/null @@ -1,727 +0,0 @@ -RAID arrays -=========== - -Boot time assembly of RAID arrays ---------------------------------- - -Tools that manage md devices can be found at - http://www.kernel.org/pub/linux/utils/raid/ - - -You can boot with your md device with the following kernel command -lines: - -for old raid arrays without persistent superblocks:: - - md=,,,,dev0,dev1,...,devn - -for raid arrays with persistent superblocks:: - - md=,dev0,dev1,...,devn - -or, to assemble a partitionable array:: - - md=d,dev0,dev1,...,devn - -``md device no.`` -+++++++++++++++++ - -The number of the md device - -================= ========= -``md device no.`` device -================= ========= - 0 md0 - 1 md1 - 2 md2 - 3 md3 - 4 md4 -================= ========= - -``raid level`` -++++++++++++++ - -level of the RAID array - -=============== ============= -``raid level`` level -=============== ============= --1 linear mode -0 striped mode -=============== ============= - -other modes are only supported with persistent super blocks - -``chunk size factor`` -+++++++++++++++++++++ - -(raid-0 and raid-1 only) - -Set the chunk size as 4k << n. - -``fault level`` -+++++++++++++++ - -Totally ignored - -``dev0`` to ``devn`` -++++++++++++++++++++ - -e.g. ``/dev/hda1``, ``/dev/hdc1``, ``/dev/sda1``, ``/dev/sdb1`` - -A possible loadlin line (Harald Hoyer ) looks like this:: - - e:\loadlin\loadlin e:\zimage root=/dev/md0 md=0,0,4,0,/dev/hdb2,/dev/hdc3 ro - - -Boot time autodetection of RAID arrays --------------------------------------- - -When md is compiled into the kernel (not as module), partitions of -type 0xfd are scanned and automatically assembled into RAID arrays. -This autodetection may be suppressed with the kernel parameter -``raid=noautodetect``. As of kernel 2.6.9, only drives with a type 0 -superblock can be autodetected and run at boot time. - -The kernel parameter ``raid=partitionable`` (or ``raid=part``) means -that all auto-detected arrays are assembled as partitionable. - -Boot time assembly of degraded/dirty arrays -------------------------------------------- - -If a raid5 or raid6 array is both dirty and degraded, it could have -undetectable data corruption. This is because the fact that it is -``dirty`` means that the parity cannot be trusted, and the fact that it -is degraded means that some datablocks are missing and cannot reliably -be reconstructed (due to no parity). - -For this reason, md will normally refuse to start such an array. This -requires the sysadmin to take action to explicitly start the array -despite possible corruption. This is normally done with:: - - mdadm --assemble --force .... - -This option is not really available if the array has the root -filesystem on it. In order to support this booting from such an -array, md supports a module parameter ``start_dirty_degraded`` which, -when set to 1, bypassed the checks and will allows dirty degraded -arrays to be started. - -So, to boot with a root filesystem of a dirty degraded raid 5 or 6, use:: - - md-mod.start_dirty_degraded=1 - - -Superblock formats ------------------- - -The md driver can support a variety of different superblock formats. -Currently, it supports superblock formats ``0.90.0`` and the ``md-1`` format -introduced in the 2.5 development series. - -The kernel will autodetect which format superblock is being used. - -Superblock format ``0`` is treated differently to others for legacy -reasons - it is the original superblock format. - - -General Rules - apply for all superblock formats ------------------------------------------------- - -An array is ``created`` by writing appropriate superblocks to all -devices. - -It is ``assembled`` by associating each of these devices with an -particular md virtual device. Once it is completely assembled, it can -be accessed. - -An array should be created by a user-space tool. This will write -superblocks to all devices. It will usually mark the array as -``unclean``, or with some devices missing so that the kernel md driver -can create appropriate redundancy (copying in raid 1, parity -calculation in raid 4/5). - -When an array is assembled, it is first initialized with the -SET_ARRAY_INFO ioctl. This contains, in particular, a major and minor -version number. The major version number selects which superblock -format is to be used. The minor number might be used to tune handling -of the format, such as suggesting where on each device to look for the -superblock. - -Then each device is added using the ADD_NEW_DISK ioctl. This -provides, in particular, a major and minor number identifying the -device to add. - -The array is started with the RUN_ARRAY ioctl. - -Once started, new devices can be added. They should have an -appropriate superblock written to them, and then be passed in with -ADD_NEW_DISK. - -Devices that have failed or are not yet active can be detached from an -array using HOT_REMOVE_DISK. - - -Specific Rules that apply to format-0 super block arrays, and arrays with no superblock (non-persistent) --------------------------------------------------------------------------------------------------------- - -An array can be ``created`` by describing the array (level, chunksize -etc) in a SET_ARRAY_INFO ioctl. This must have ``major_version==0`` and -``raid_disks != 0``. - -Then uninitialized devices can be added with ADD_NEW_DISK. The -structure passed to ADD_NEW_DISK must specify the state of the device -and its role in the array. - -Once started with RUN_ARRAY, uninitialized spares can be added with -HOT_ADD_DISK. - - -MD devices in sysfs -------------------- - -md devices appear in sysfs (``/sys``) as regular block devices, -e.g.:: - - /sys/block/md0 - -Each ``md`` device will contain a subdirectory called ``md`` which -contains further md-specific information about the device. - -All md devices contain: - - level - a text file indicating the ``raid level``. e.g. raid0, raid1, - raid5, linear, multipath, faulty. - If no raid level has been set yet (array is still being - assembled), the value will reflect whatever has been written - to it, which may be a name like the above, or may be a number - such as ``0``, ``5``, etc. - - raid_disks - a text file with a simple number indicating the number of devices - in a fully functional array. If this is not yet known, the file - will be empty. If an array is being resized this will contain - the new number of devices. - Some raid levels allow this value to be set while the array is - active. This will reconfigure the array. Otherwise it can only - be set while assembling an array. - A change to this attribute will not be permitted if it would - reduce the size of the array. To reduce the number of drives - in an e.g. raid5, the array size must first be reduced by - setting the ``array_size`` attribute. - - chunk_size - This is the size in bytes for ``chunks`` and is only relevant to - raid levels that involve striping (0,4,5,6,10). The address space - of the array is conceptually divided into chunks and consecutive - chunks are striped onto neighbouring devices. - The size should be at least PAGE_SIZE (4k) and should be a power - of 2. This can only be set while assembling an array - - layout - The ``layout`` for the array for the particular level. This is - simply a number that is interpretted differently by different - levels. It can be written while assembling an array. - - array_size - This can be used to artificially constrain the available space in - the array to be less than is actually available on the combined - devices. Writing a number (in Kilobytes) which is less than - the available size will set the size. Any reconfiguration of the - array (e.g. adding devices) will not cause the size to change. - Writing the word ``default`` will cause the effective size of the - array to be whatever size is actually available based on - ``level``, ``chunk_size`` and ``component_size``. - - This can be used to reduce the size of the array before reducing - the number of devices in a raid4/5/6, or to support external - metadata formats which mandate such clipping. - - reshape_position - This is either ``none`` or a sector number within the devices of - the array where ``reshape`` is up to. If this is set, the three - attributes mentioned above (raid_disks, chunk_size, layout) can - potentially have 2 values, an old and a new value. If these - values differ, reading the attribute returns:: - - new (old) - - and writing will effect the ``new`` value, leaving the ``old`` - unchanged. - - component_size - For arrays with data redundancy (i.e. not raid0, linear, faulty, - multipath), all components must be the same size - or at least - there must a size that they all provide space for. This is a key - part or the geometry of the array. It is measured in sectors - and can be read from here. Writing to this value may resize - the array if the personality supports it (raid1, raid5, raid6), - and if the component drives are large enough. - - metadata_version - This indicates the format that is being used to record metadata - about the array. It can be 0.90 (traditional format), 1.0, 1.1, - 1.2 (newer format in varying locations) or ``none`` indicating that - the kernel isn't managing metadata at all. - Alternately it can be ``external:`` followed by a string which - is set by user-space. This indicates that metadata is managed - by a user-space program. Any device failure or other event that - requires a metadata update will cause array activity to be - suspended until the event is acknowledged. - - resync_start - The point at which resync should start. If no resync is needed, - this will be a very large number (or ``none`` since 2.6.30-rc1). At - array creation it will default to 0, though starting the array as - ``clean`` will set it much larger. - - new_dev - This file can be written but not read. The value written should - be a block device number as major:minor. e.g. 8:0 - This will cause that device to be attached to the array, if it is - available. It will then appear at md/dev-XXX (depending on the - name of the device) and further configuration is then possible. - - safe_mode_delay - When an md array has seen no write requests for a certain period - of time, it will be marked as ``clean``. When another write - request arrives, the array is marked as ``dirty`` before the write - commences. This is known as ``safe_mode``. - The ``certain period`` is controlled by this file which stores the - period as a number of seconds. The default is 200msec (0.200). - Writing a value of 0 disables safemode. - - array_state - This file contains a single word which describes the current - state of the array. In many cases, the state can be set by - writing the word for the desired state, however some states - cannot be explicitly set, and some transitions are not allowed. - - Select/poll works on this file. All changes except between - Active_idle and active (which can be frequent and are not - very interesting) are notified. active->active_idle is - reported if the metadata is externally managed. - - clear - No devices, no size, no level - - Writing is equivalent to STOP_ARRAY ioctl - - inactive - May have some settings, but array is not active - all IO results in error - - When written, doesn't tear down array, but just stops it - - suspended (not supported yet) - All IO requests will block. The array can be reconfigured. - - Writing this, if accepted, will block until array is quiessent - - readonly - no resync can happen. no superblocks get written. - - Write requests fail - - read-auto - like readonly, but behaves like ``clean`` on a write request. - - clean - no pending writes, but otherwise active. - - When written to inactive array, starts without resync - - If a write request arrives then - if metadata is known, mark ``dirty`` and switch to ``active``. - if not known, block and switch to write-pending - - If written to an active array that has pending writes, then fails. - active - fully active: IO and resync can be happening. - When written to inactive array, starts with resync - - write-pending - clean, but writes are blocked waiting for ``active`` to be written. - - active-idle - like active, but no writes have been seen for a while (safe_mode_delay). - - bitmap/location - This indicates where the write-intent bitmap for the array is - stored. - - It can be one of ``none``, ``file`` or ``[+-]N``. - ``file`` may later be extended to ``file:/file/name`` - ``[+-]N`` means that many sectors from the start of the metadata. - - This is replicated on all devices. For arrays with externally - managed metadata, the offset is from the beginning of the - device. - - bitmap/chunksize - The size, in bytes, of the chunk which will be represented by a - single bit. For RAID456, it is a portion of an individual - device. For RAID10, it is a portion of the array. For RAID1, it - is both (they come to the same thing). - - bitmap/time_base - The time, in seconds, between looking for bits in the bitmap to - be cleared. In the current implementation, a bit will be cleared - between 2 and 3 times ``time_base`` after all the covered blocks - are known to be in-sync. - - bitmap/backlog - When write-mostly devices are active in a RAID1, write requests - to those devices proceed in the background - the filesystem (or - other user of the device) does not have to wait for them. - ``backlog`` sets a limit on the number of concurrent background - writes. If there are more than this, new writes will by - synchronous. - - bitmap/metadata - This can be either ``internal`` or ``external``. - - ``internal`` - is the default and means the metadata for the bitmap - is stored in the first 256 bytes of the allocated space and is - managed by the md module. - - ``external`` - means that bitmap metadata is managed externally to - the kernel (i.e. by some userspace program) - - bitmap/can_clear - This is either ``true`` or ``false``. If ``true``, then bits in the - bitmap will be cleared when the corresponding blocks are thought - to be in-sync. If ``false``, bits will never be cleared. - This is automatically set to ``false`` if a write happens on a - degraded array, or if the array becomes degraded during a write. - When metadata is managed externally, it should be set to true - once the array becomes non-degraded, and this fact has been - recorded in the metadata. - - - - -As component devices are added to an md array, they appear in the ``md`` -directory as new directories named:: - - dev-XXX - -where ``XXX`` is a name that the kernel knows for the device, e.g. hdb1. -Each directory contains: - - block - a symlink to the block device in /sys/block, e.g.:: - - /sys/block/md0/md/dev-hdb1/block -> ../../../../block/hdb/hdb1 - - super - A file containing an image of the superblock read from, or - written to, that device. - - state - A file recording the current state of the device in the array - which can be a comma separated list of: - - faulty - device has been kicked from active use due to - a detected fault, or it has unacknowledged bad - blocks - - in_sync - device is a fully in-sync member of the array - - writemostly - device will only be subject to read - requests if there are no other options. - - This applies only to raid1 arrays. - - blocked - device has failed, and the failure hasn't been - acknowledged yet by the metadata handler. - - Writes that would write to this device if - it were not faulty are blocked. - - spare - device is working, but not a full member. - - This includes spares that are in the process - of being recovered to - - write_error - device has ever seen a write error. - - want_replacement - device is (mostly) working but probably - should be replaced, either due to errors or - due to user request. - - replacement - device is a replacement for another active - device with same raid_disk. - - - This list may grow in future. - - This can be written to. - - Writing ``faulty`` simulates a failure on the device. - - Writing ``remove`` removes the device from the array. - - Writing ``writemostly`` sets the writemostly flag. - - Writing ``-writemostly`` clears the writemostly flag. - - Writing ``blocked`` sets the ``blocked`` flag. - - Writing ``-blocked`` clears the ``blocked`` flags and allows writes - to complete and possibly simulates an error. - - Writing ``in_sync`` sets the in_sync flag. - - Writing ``write_error`` sets writeerrorseen flag. - - Writing ``-write_error`` clears writeerrorseen flag. - - Writing ``want_replacement`` is allowed at any time except to a - replacement device or a spare. It sets the flag. - - Writing ``-want_replacement`` is allowed at any time. It clears - the flag. - - Writing ``replacement`` or ``-replacement`` is only allowed before - starting the array. It sets or clears the flag. - - - This file responds to select/poll. Any change to ``faulty`` - or ``blocked`` causes an event. - - errors - An approximate count of read errors that have been detected on - this device but have not caused the device to be evicted from - the array (either because they were corrected or because they - happened while the array was read-only). When using version-1 - metadata, this value persists across restarts of the array. - - This value can be written while assembling an array thus - providing an ongoing count for arrays with metadata managed by - userspace. - - slot - This gives the role that the device has in the array. It will - either be ``none`` if the device is not active in the array - (i.e. is a spare or has failed) or an integer less than the - ``raid_disks`` number for the array indicating which position - it currently fills. This can only be set while assembling an - array. A device for which this is set is assumed to be working. - - offset - This gives the location in the device (in sectors from the - start) where data from the array will be stored. Any part of - the device before this offset is not touched, unless it is - used for storing metadata (Formats 1.1 and 1.2). - - size - The amount of the device, after the offset, that can be used - for storage of data. This will normally be the same as the - component_size. This can be written while assembling an - array. If a value less than the current component_size is - written, it will be rejected. - - recovery_start - When the device is not ``in_sync``, this records the number of - sectors from the start of the device which are known to be - correct. This is normally zero, but during a recovery - operation it will steadily increase, and if the recovery is - interrupted, restoring this value can cause recovery to - avoid repeating the earlier blocks. With v1.x metadata, this - value is saved and restored automatically. - - This can be set whenever the device is not an active member of - the array, either before the array is activated, or before - the ``slot`` is set. - - Setting this to ``none`` is equivalent to setting ``in_sync``. - Setting to any other value also clears the ``in_sync`` flag. - - bad_blocks - This gives the list of all known bad blocks in the form of - start address and length (in sectors respectively). If output - is too big to fit in a page, it will be truncated. Writing - ``sector length`` to this file adds new acknowledged (i.e. - recorded to disk safely) bad blocks. - - unacknowledged_bad_blocks - This gives the list of known-but-not-yet-saved-to-disk bad - blocks in the same form of ``bad_blocks``. If output is too big - to fit in a page, it will be truncated. Writing to this file - adds bad blocks without acknowledging them. This is largely - for testing. - - - -An active md device will also contain an entry for each active device -in the array. These are named:: - - rdNN - -where ``NN`` is the position in the array, starting from 0. -So for a 3 drive array there will be rd0, rd1, rd2. -These are symbolic links to the appropriate ``dev-XXX`` entry. -Thus, for example:: - - cat /sys/block/md*/md/rd*/state - -will show ``in_sync`` on every line. - - - -Active md devices for levels that support data redundancy (1,4,5,6,10) -also have - - sync_action - a text file that can be used to monitor and control the rebuild - process. It contains one word which can be one of: - - resync - redundancy is being recalculated after unclean - shutdown or creation - - recover - a hot spare is being built to replace a - failed/missing device - - idle - nothing is happening - check - A full check of redundancy was requested and is - happening. This reads all blocks and checks - them. A repair may also happen for some raid - levels. - - repair - A full check and repair is happening. This is - similar to ``resync``, but was requested by the - user, and the write-intent bitmap is NOT used to - optimise the process. - - This file is writable, and each of the strings that could be - read are meaningful for writing. - - ``idle`` will stop an active resync/recovery etc. There is no - guarantee that another resync/recovery may not be automatically - started again, though some event will be needed to trigger - this. - - ``resync`` or ``recovery`` can be used to restart the - corresponding operation if it was stopped with ``idle``. - - ``check`` and ``repair`` will start the appropriate process - providing the current state is ``idle``. - - This file responds to select/poll. Any important change in the value - triggers a poll event. Sometimes the value will briefly be - ``recover`` if a recovery seems to be needed, but cannot be - achieved. In that case, the transition to ``recover`` isn't - notified, but the transition away is. - - degraded - This contains a count of the number of devices by which the - arrays is degraded. So an optimal array will show ``0``. A - single failed/missing drive will show ``1``, etc. - - This file responds to select/poll, any increase or decrease - in the count of missing devices will trigger an event. - - mismatch_count - When performing ``check`` and ``repair``, and possibly when - performing ``resync``, md will count the number of errors that are - found. The count in ``mismatch_cnt`` is the number of sectors - that were re-written, or (for ``check``) would have been - re-written. As most raid levels work in units of pages rather - than sectors, this may be larger than the number of actual errors - by a factor of the number of sectors in a page. - - bitmap_set_bits - If the array has a write-intent bitmap, then writing to this - attribute can set bits in the bitmap, indicating that a resync - would need to check the corresponding blocks. Either individual - numbers or start-end pairs can be written. Multiple numbers - can be separated by a space. - - Note that the numbers are ``bit`` numbers, not ``block`` numbers. - They should be scaled by the bitmap_chunksize. - - sync_speed_min, sync_speed_max - This are similar to ``/proc/sys/dev/raid/speed_limit_{min,max}`` - however they only apply to the particular array. - - If no value has been written to these, or if the word ``system`` - is written, then the system-wide value is used. If a value, - in kibibytes-per-second is written, then it is used. - - When the files are read, they show the currently active value - followed by ``(local)`` or ``(system)`` depending on whether it is - a locally set or system-wide value. - - sync_completed - This shows the number of sectors that have been completed of - whatever the current sync_action is, followed by the number of - sectors in total that could need to be processed. The two - numbers are separated by a ``/`` thus effectively showing one - value, a fraction of the process that is complete. - - A ``select`` on this attribute will return when resync completes, - when it reaches the current sync_max (below) and possibly at - other times. - - sync_speed - This shows the current actual speed, in K/sec, of the current - sync_action. It is averaged over the last 30 seconds. - - suspend_lo, suspend_hi - The two values, given as numbers of sectors, indicate a range - within the array where IO will be blocked. This is currently - only supported for raid4/5/6. - - sync_min, sync_max - The two values, given as numbers of sectors, indicate a range - within the array where ``check``/``repair`` will operate. Must be - a multiple of chunk_size. When it reaches ``sync_max`` it will - pause, rather than complete. - You can use ``select`` or ``poll`` on ``sync_completed`` to wait for - that number to reach sync_max. Then you can either increase - ``sync_max``, or can write ``idle`` to ``sync_action``. - - The value of ``max`` for ``sync_max`` effectively disables the limit. - When a resync is active, the value can only ever be increased, - never decreased. - The value of ``0`` is the minimum for ``sync_min``. - - - -Each active md device may also have attributes specific to the -personality module that manages it. -These are specific to the implementation of the module and could -change substantially if the implementation changes. - -These currently include: - - stripe_cache_size (currently raid5 only) - number of entries in the stripe cache. This is writable, but - there are upper and lower limits (32768, 17). Default is 256. - - strip_cache_active (currently raid5 only) - number of active entries in the stripe cache - - preread_bypass_threshold (currently raid5 only) - number of times a stripe requiring preread will be bypassed by - a stripe that does not require preread. For fairness defaults - to 1. Setting this to 0 disables bypass accounting and - requires preread stripes to wait until all full-width stripe- - writes are complete. Valid values are 0 to stripe_cache_size. diff --git a/Documentation/mono.txt b/Documentation/mono.txt deleted file mode 100644 index 9a9744ca0cf3..000000000000 --- a/Documentation/mono.txt +++ /dev/null @@ -1,68 +0,0 @@ -Mono(tm) Binary Kernel Support for Linux ------------------------------------------ - -To configure Linux to automatically execute Mono-based .NET binaries -(in the form of .exe files) without the need to use the mono CLR -wrapper, you can use the BINFMT_MISC kernel support. - -This will allow you to execute Mono-based .NET binaries just like any -other program after you have done the following: - -1) You MUST FIRST install the Mono CLR support, either by downloading - a binary package, a source tarball or by installing from CVS. Binary - packages for several distributions can be found at: - - http://go-mono.com/download.html - - Instructions for compiling Mono can be found at: - - http://www.go-mono.com/compiling.html - - Once the Mono CLR support has been installed, just check that - ``/usr/bin/mono`` (which could be located elsewhere, for example - ``/usr/local/bin/mono``) is working. - -2) You have to compile BINFMT_MISC either as a module or into - the kernel (``CONFIG_BINFMT_MISC``) and set it up properly. - If you choose to compile it as a module, you will have - to insert it manually with modprobe/insmod, as kmod - cannot be easily supported with binfmt_misc. - Read the file ``binfmt_misc.txt`` in this directory to know - more about the configuration process. - -3) Add the following entries to ``/etc/rc.local`` or similar script - to be run at system startup:: - - # Insert BINFMT_MISC module into the kernel - if [ ! -e /proc/sys/fs/binfmt_misc/register ]; then - /sbin/modprobe binfmt_misc - # Some distributions, like Fedora Core, perform - # the following command automatically when the - # binfmt_misc module is loaded into the kernel - # or during normal boot up (systemd-based systems). - # Thus, it is possible that the following line - # is not needed at all. - mount -t binfmt_misc none /proc/sys/fs/binfmt_misc - fi - - # Register support for .NET CLR binaries - if [ -e /proc/sys/fs/binfmt_misc/register ]; then - # Replace /usr/bin/mono with the correct pathname to - # the Mono CLR runtime (usually /usr/local/bin/mono - # when compiling from sources or CVS). - echo ':CLR:M::MZ::/usr/bin/mono:' > /proc/sys/fs/binfmt_misc/register - else - echo "No binfmt_misc support" - exit 1 - fi - -4) Check that ``.exe`` binaries can be ran without the need of a - wrapper script, simply by launching the ``.exe`` file directly - from a command prompt, for example:: - - /usr/bin/xsd.exe - - .. note:: - - If this fails with a permission denied error, check - that the ``.exe`` file has execute permissions. diff --git a/Documentation/oops-tracing.txt b/Documentation/oops-tracing.txt deleted file mode 100644 index 3e25ea7349ee..000000000000 --- a/Documentation/oops-tracing.txt +++ /dev/null @@ -1,300 +0,0 @@ -OOPS tracing -============ - -.. note:: - - ``ksymoops`` is useless on 2.6 or upper. Please use the Oops in its original - format (from ``dmesg``, etc). Ignore any references in this or other docs to - "decoding the Oops" or "running it through ksymoops". - If you post an Oops from 2.6+ that has been run through ``ksymoops``, - people will just tell you to repost it. - -Quick Summary -------------- - -Find the Oops and send it to the maintainer of the kernel area that seems to be -involved with the problem. Don't worry too much about getting the wrong person. -If you are unsure send it to the person responsible for the code relevant to -what you were doing. If it occurs repeatably try and describe how to recreate -it. That's worth even more than the oops. - -If you are totally stumped as to whom to send the report, send it to -linux-kernel@vger.kernel.org. Thanks for your help in making Linux as -stable as humanly possible. - -Where is the Oops? ----------------------- - -Normally the Oops text is read from the kernel buffers by klogd and -handed to ``syslogd`` which writes it to a syslog file, typically -``/var/log/messages`` (depends on ``/etc/syslog.conf``). Sometimes ``klogd`` -dies, in which case you can run ``dmesg > file`` to read the data from the -kernel buffers and save it. Or you can ``cat /proc/kmsg > file``, however you -have to break in to stop the transfer, ``kmsg`` is a "never ending file". -If the machine has crashed so badly that you cannot enter commands or -the disk is not available then you have three options : - -(1) Hand copy the text from the screen and type it in after the machine - has restarted. Messy but it is the only option if you have not - planned for a crash. Alternatively, you can take a picture of - the screen with a digital camera - not nice, but better than - nothing. If the messages scroll off the top of the console, you - may find that booting with a higher resolution (eg, ``vga=791``) - will allow you to read more of the text. (Caveat: This needs ``vesafb``, - so won't help for 'early' oopses) - -(2) Boot with a serial console (see - :ref:`Documentation/serial-console.txt `), - run a null modem to a second machine and capture the output there - using your favourite communication program. Minicom works well. - -(3) Use Kdump (see Documentation/kdump/kdump.txt), - extract the kernel ring buffer from old memory with using dmesg - gdbmacro in Documentation/kdump/gdbmacros.txt. - - -Full Information ----------------- - -.. note:: - - the message from Linus below applies to 2.4 kernel. I have preserved it - for historical reasons, and because some of the information in it still - applies. Especially, please ignore any references to ksymoops. - - :: - - From: Linus Torvalds - - How to track down an Oops.. [originally a mail to linux-kernel] - - The main trick is having 5 years of experience with those pesky oops - messages ;-) - -Actually, there are things you can do that make this easier. I have two -separate approaches:: - - gdb /usr/src/linux/vmlinux - gdb> disassemble - -That's the easy way to find the problem, at least if the bug-report is -well made (like this one was - run through ``ksymoops`` to get the -information of which function and the offset in the function that it -happened in). - -Oh, it helps if the report happens on a kernel that is compiled with the -same compiler and similar setups. - -The other thing to do is disassemble the "Code:" part of the bug report: -ksymoops will do this too with the correct tools, but if you don't have -the tools you can just do a silly program:: - - char str[] = "\xXX\xXX\xXX..."; - main(){} - -and compile it with ``gcc -g`` and then do ``disassemble str`` (where the ``XX`` -stuff are the values reported by the Oops - you can just cut-and-paste -and do a replace of spaces to ``\x`` - that's what I do, as I'm too lazy -to write a program to automate this all). - -Alternatively, you can use the shell script in ``scripts/decodecode``. -Its usage is:: - - decodecode < oops.txt - -The hex bytes that follow "Code:" may (in some architectures) have a series -of bytes that precede the current instruction pointer as well as bytes at and -following the current instruction pointer. In some cases, one instruction -byte or word is surrounded by ``<>`` or ``()``, as in ``<86>`` or ``(f00d)``. -These ``<>`` or ``()`` markings indicate the current instruction pointer. - -Example from i386, split into multiple lines for readability:: - - Code: f9 0f 8d f9 00 00 00 8d 42 0c e8 dd 26 11 c7 a1 60 ea 2b f9 8b 50 08 a1 - 64 ea 2b f9 8d 34 82 8b 1e 85 db 74 6d 8b 15 60 ea 2b f9 <8b> 43 04 39 42 54 - 7e 04 40 89 42 54 8b 43 04 3b 05 00 f6 52 c0 - -Finally, if you want to see where the code comes from, you can do:: - - cd /usr/src/linux - make fs/buffer.s # or whatever file the bug happened in - -and then you get a better idea of what happens than with the gdb -disassembly. - -Now, the trick is just then to combine all the data you have: the C -sources (and general knowledge of what it **should** do), the assembly -listing and the code disassembly (and additionally the register dump you -also get from the "oops" message - that can be useful to see **what** the -corrupted pointers were, and when you have the assembler listing you can -also match the other registers to whatever C expressions they were used -for). - -Essentially, you just look at what doesn't match (in this case it was the -"Code" disassembly that didn't match with what the compiler generated). -Then you need to find out **why** they don't match. Often it's simple - you -see that the code uses a NULL pointer and then you look at the code and -wonder how the NULL pointer got there, and if it's a valid thing to do -you just check against it.. - -Now, if somebody gets the idea that this is time-consuming and requires -some small amount of concentration, you're right. Which is why I will -mostly just ignore any panic reports that don't have the symbol table -info etc looked up: it simply gets too hard to look it up (I have some -programs to search for specific patterns in the kernel code segment, and -sometimes I have been able to look up those kinds of panics too, but -that really requires pretty good knowledge of the kernel just to be able -to pick out the right sequences etc..) - -**Sometimes** it happens that I just see the disassembled code sequence -from the panic, and I know immediately where it's coming from. That's when -I get worried that I've been doing this for too long ;-) - - Linus - - ---------------------------------------------------------------------------- - -Notes on Oops tracing with ``klogd`` ------------------------------------- - -In order to help Linus and the other kernel developers there has been -substantial support incorporated into ``klogd`` for processing protection -faults. In order to have full support for address resolution at least -version 1.3-pl3 of the ``sysklogd`` package should be used. - -When a protection fault occurs the ``klogd`` daemon automatically -translates important addresses in the kernel log messages to their -symbolic equivalents. This translated kernel message is then -forwarded through whatever reporting mechanism ``klogd`` is using. The -protection fault message can be simply cut out of the message files -and forwarded to the kernel developers. - -Two types of address resolution are performed by ``klogd``. The first is -static translation and the second is dynamic translation. Static -translation uses the System.map file in much the same manner that -ksymoops does. In order to do static translation the ``klogd`` daemon -must be able to find a system map file at daemon initialization time. -See the klogd man page for information on how ``klogd`` searches for map -files. - -Dynamic address translation is important when kernel loadable modules -are being used. Since memory for kernel modules is allocated from the -kernel's dynamic memory pools there are no fixed locations for either -the start of the module or for functions and symbols in the module. - -The kernel supports system calls which allow a program to determine -which modules are loaded and their location in memory. Using these -system calls the klogd daemon builds a symbol table which can be used -to debug a protection fault which occurs in a loadable kernel module. - -At the very minimum klogd will provide the name of the module which -generated the protection fault. There may be additional symbolic -information available if the developer of the loadable module chose to -export symbol information from the module. - -Since the kernel module environment can be dynamic there must be a -mechanism for notifying the ``klogd`` daemon when a change in module -environment occurs. There are command line options available which -allow klogd to signal the currently executing daemon that symbol -information should be refreshed. See the ``klogd`` manual page for more -information. - -A patch is included with the sysklogd distribution which modifies the -``modules-2.0.0`` package to automatically signal klogd whenever a module -is loaded or unloaded. Applying this patch provides essentially -seamless support for debugging protection faults which occur with -kernel loadable modules. - -The following is an example of a protection fault in a loadable module -processed by ``klogd``:: - - Aug 29 09:51:01 blizard kernel: Unable to handle kernel paging request at virtual address f15e97cc - Aug 29 09:51:01 blizard kernel: current->tss.cr3 = 0062d000, %cr3 = 0062d000 - Aug 29 09:51:01 blizard kernel: *pde = 00000000 - Aug 29 09:51:01 blizard kernel: Oops: 0002 - Aug 29 09:51:01 blizard kernel: CPU: 0 - Aug 29 09:51:01 blizard kernel: EIP: 0010:[oops:_oops+16/3868] - Aug 29 09:51:01 blizard kernel: EFLAGS: 00010212 - Aug 29 09:51:01 blizard kernel: eax: 315e97cc ebx: 003a6f80 ecx: 001be77b edx: 00237c0c - Aug 29 09:51:01 blizard kernel: esi: 00000000 edi: bffffdb3 ebp: 00589f90 esp: 00589f8c - Aug 29 09:51:01 blizard kernel: ds: 0018 es: 0018 fs: 002b gs: 002b ss: 0018 - Aug 29 09:51:01 blizard kernel: Process oops_test (pid: 3374, process nr: 21, stackpage=00589000) - Aug 29 09:51:01 blizard kernel: Stack: 315e97cc 00589f98 0100b0b4 bffffed4 0012e38e 00240c64 003a6f80 00000001 - Aug 29 09:51:01 blizard kernel: 00000000 00237810 bfffff00 0010a7fa 00000003 00000001 00000000 bfffff00 - Aug 29 09:51:01 blizard kernel: bffffdb3 bffffed4 ffffffda 0000002b 0007002b 0000002b 0000002b 00000036 - Aug 29 09:51:01 blizard kernel: Call Trace: [oops:_oops_ioctl+48/80] [_sys_ioctl+254/272] [_system_call+82/128] - Aug 29 09:51:01 blizard kernel: Code: c7 00 05 00 00 00 eb 08 90 90 90 90 90 90 90 90 89 ec 5d c3 - ---------------------------------------------------------------------------- - -:: - - Dr. G.W. Wettstein Oncology Research Div. Computing Facility - Roger Maris Cancer Center INTERNET: greg@wind.rmcc.com - 820 4th St. N. - Fargo, ND 58122 - Phone: 701-234-7556 - - ---------------------------------------------------------------------------- - -Tainted kernels ---------------- - -Some oops reports contain the string **'Tainted: '** after the program -counter. This indicates that the kernel has been tainted by some -mechanism. The string is followed by a series of position-sensitive -characters, each representing a particular tainted value. - - 1) 'G' if all modules loaded have a GPL or compatible license, 'P' if - any proprietary module has been loaded. Modules without a - MODULE_LICENSE or with a MODULE_LICENSE that is not recognised by - insmod as GPL compatible are assumed to be proprietary. - - 2) ``F`` if any module was force loaded by ``insmod -f``, ``' '`` if all - modules were loaded normally. - - 3) ``S`` if the oops occurred on an SMP kernel running on hardware that - hasn't been certified as safe to run multiprocessor. - Currently this occurs only on various Athlons that are not - SMP capable. - - 4) ``R`` if a module was force unloaded by ``rmmod -f``, ``' '`` if all - modules were unloaded normally. - - 5) ``M`` if any processor has reported a Machine Check Exception, - ``' '`` if no Machine Check Exceptions have occurred. - - 6) ``B`` if a page-release function has found a bad page reference or - some unexpected page flags. - - 7) ``U`` if a user or user application specifically requested that the - Tainted flag be set, ``' '`` otherwise. - - 8) ``D`` if the kernel has died recently, i.e. there was an OOPS or BUG. - - 9) ``A`` if the ACPI table has been overridden. - - 10) ``W`` if a warning has previously been issued by the kernel. - (Though some warnings may set more specific taint flags.) - - 11) ``C`` if a staging driver has been loaded. - - 12) ``I`` if the kernel is working around a severe bug in the platform - firmware (BIOS or similar). - - 13) ``O`` if an externally-built ("out-of-tree") module has been loaded. - - 14) ``E`` if an unsigned module has been loaded in a kernel supporting - module signature. - - 15) ``L`` if a soft lockup has previously occurred on the system. - - 16) ``K`` if the kernel has been live patched. - -The primary reason for the **'Tainted: '** string is to tell kernel -debuggers if this is a clean kernel or if anything unusual has -occurred. Tainting is permanent: even if an offending module is -unloaded, the tainted value remains to indicate that the kernel is not -trustworthy. diff --git a/Documentation/parport.txt b/Documentation/parport.txt deleted file mode 100644 index ad3f9b8a11e1..000000000000 --- a/Documentation/parport.txt +++ /dev/null @@ -1,286 +0,0 @@ -Parport -+++++++ - -The ``parport`` code provides parallel-port support under Linux. This -includes the ability to share one port between multiple device -drivers. - -You can pass parameters to the ``parport`` code to override its automatic -detection of your hardware. This is particularly useful if you want -to use IRQs, since in general these can't be autoprobed successfully. -By default IRQs are not used even if they **can** be probed. This is -because there are a lot of people using the same IRQ for their -parallel port and a sound card or network card. - -The ``parport`` code is split into two parts: generic (which deals with -port-sharing) and architecture-dependent (which deals with actually -using the port). - - -Parport as modules -================== - -If you load the `parport`` code as a module, say:: - - # insmod parport - -to load the generic ``parport`` code. You then must load the -architecture-dependent code with (for example):: - - # insmod parport_pc io=0x3bc,0x378,0x278 irq=none,7,auto - -to tell the ``parport`` code that you want three PC-style ports, one at -0x3bc with no IRQ, one at 0x378 using IRQ 7, and one at 0x278 with an -auto-detected IRQ. Currently, PC-style (``parport_pc``), Sun ``bpp``, -Amiga, Atari, and MFC3 hardware is supported. - -PCI parallel I/O card support comes from ``parport_pc``. Base I/O -addresses should not be specified for supported PCI cards since they -are automatically detected. - - -modprobe --------- - -If you use modprobe , you will find it useful to add lines as below to a -configuration file in /etc/modprobe.d/ directory:: - - alias parport_lowlevel parport_pc - options parport_pc io=0x378,0x278 irq=7,auto - -modprobe will load ``parport_pc`` (with the options ``io=0x378,0x278 irq=7,auto``) -whenever a parallel port device driver (such as ``lp``) is loaded. - -Note that these are example lines only! You shouldn't in general need -to specify any options to ``parport_pc`` in order to be able to use a -parallel port. - - -Parport probe [optional] ------------------------- - -In 2.2 kernels there was a module called ``parport_probe``, which was used -for collecting IEEE 1284 device ID information. This has now been -enhanced and now lives with the IEEE 1284 support. When a parallel -port is detected, the devices that are connected to it are analysed, -and information is logged like this:: - - parport0: Printer, BJC-210 (Canon) - -The probe information is available from files in ``/proc/sys/dev/parport/``. - - -Parport linked into the kernel statically -========================================= - -If you compile the ``parport`` code into the kernel, then you can use -kernel boot parameters to get the same effect. Add something like the -following to your LILO command line:: - - parport=0x3bc parport=0x378,7 parport=0x278,auto,nofifo - -You can have many ``parport=...`` statements, one for each port you want -to add. Adding ``parport=0`` to the kernel command-line will disable -parport support entirely. Adding ``parport=auto`` to the kernel -command-line will make ``parport`` use any IRQ lines or DMA channels that -it auto-detects. - - -Files in /proc -============== - -If you have configured the ``/proc`` filesystem into your kernel, you will -see a new directory entry: ``/proc/sys/dev/parport``. In there will be a -directory entry for each parallel port for which parport is -configured. In each of those directories are a collection of files -describing that parallel port. - -The ``/proc/sys/dev/parport`` directory tree looks like:: - - parport - |-- default - | |-- spintime - | `-- timeslice - |-- parport0 - | |-- autoprobe - | |-- autoprobe0 - | |-- autoprobe1 - | |-- autoprobe2 - | |-- autoprobe3 - | |-- devices - | | |-- active - | | `-- lp - | | `-- timeslice - | |-- base-addr - | |-- irq - | |-- dma - | |-- modes - | `-- spintime - `-- parport1 - |-- autoprobe - |-- autoprobe0 - |-- autoprobe1 - |-- autoprobe2 - |-- autoprobe3 - |-- devices - | |-- active - | `-- ppa - | `-- timeslice - |-- base-addr - |-- irq - |-- dma - |-- modes - `-- spintime - -.. tabularcolumns:: |p{4.0cm}|p{13.5cm}| - -======================= ======================================================= -File Contents -======================= ======================================================= -``devices/active`` A list of the device drivers using that port. A "+" - will appear by the name of the device currently using - the port (it might not appear against any). The - string "none" means that there are no device drivers - using that port. - -``base-addr`` Parallel port's base address, or addresses if the port - has more than one in which case they are separated - with tabs. These values might not have any sensible - meaning for some ports. - -``irq`` Parallel port's IRQ, or -1 if none is being used. - -``dma`` Parallel port's DMA channel, or -1 if none is being - used. - -``modes`` Parallel port's hardware modes, comma-separated, - meaning: - - - PCSPP - PC-style SPP registers are available. - - - TRISTATE - Port is bidirectional. - - - COMPAT - Hardware acceleration for printers is - available and will be used. - - - EPP - Hardware acceleration for EPP protocol - is available and will be used. - - - ECP - Hardware acceleration for ECP protocol - is available and will be used. - - - DMA - DMA is available and will be used. - - Note that the current implementation will only take - advantage of COMPAT and ECP modes if it has an IRQ - line to use. - -``autoprobe`` Any IEEE-1284 device ID information that has been - acquired from the (non-IEEE 1284.3) device. - -``autoprobe[0-3]`` IEEE 1284 device ID information retrieved from - daisy-chain devices that conform to IEEE 1284.3. - -``spintime`` The number of microseconds to busy-loop while waiting - for the peripheral to respond. You might find that - adjusting this improves performance, depending on your - peripherals. This is a port-wide setting, i.e. it - applies to all devices on a particular port. - -``timeslice`` The number of milliseconds that a device driver is - allowed to keep a port claimed for. This is advisory, - and driver can ignore it if it must. - -``default/*`` The defaults for spintime and timeslice. When a new - port is registered, it picks up the default spintime. - When a new device is registered, it picks up the - default timeslice. -======================= ======================================================= - -Device drivers -============== - -Once the parport code is initialised, you can attach device drivers to -specific ports. Normally this happens automatically; if the lp driver -is loaded it will create one lp device for each port found. You can -override this, though, by using parameters either when you load the lp -driver:: - - # insmod lp parport=0,2 - -or on the LILO command line:: - - lp=parport0 lp=parport2 - -Both the above examples would inform lp that you want ``/dev/lp0`` to be -the first parallel port, and /dev/lp1 to be the **third** parallel port, -with no lp device associated with the second port (parport1). Note -that this is different to the way older kernels worked; there used to -be a static association between the I/O port address and the device -name, so ``/dev/lp0`` was always the port at 0x3bc. This is no longer the -case - if you only have one port, it will default to being ``/dev/lp0``, -regardless of base address. - -Also: - - * If you selected the IEEE 1284 support at compile time, you can say - ``lp=auto`` on the kernel command line, and lp will create devices - only for those ports that seem to have printers attached. - - * If you give PLIP the ``timid`` parameter, either with ``plip=timid`` on - the command line, or with ``insmod plip timid=1`` when using modules, - it will avoid any ports that seem to be in use by other devices. - - * IRQ autoprobing works only for a few port types at the moment. - -Reporting printer problems with parport -======================================= - -If you are having problems printing, please go through these steps to -try to narrow down where the problem area is. - -When reporting problems with parport, really you need to give all of -the messages that ``parport_pc`` spits out when it initialises. There are -several code paths: - -- polling -- interrupt-driven, protocol in software -- interrupt-driven, protocol in hardware using PIO -- interrupt-driven, protocol in hardware using DMA - -The kernel messages that ``parport_pc`` logs give an indication of which -code path is being used. (They could be a lot better actually..) - -For normal printer protocol, having IEEE 1284 modes enabled or not -should not make a difference. - -To turn off the 'protocol in hardware' code paths, disable -``CONFIG_PARPORT_PC_FIFO``. Note that when they are enabled they are not -necessarily **used**; it depends on whether the hardware is available, -enabled by the BIOS, and detected by the driver. - -So, to start with, disable ``CONFIG_PARPORT_PC_FIFO``, and load ``parport_pc`` -with ``irq=none``. See if printing works then. It really should, -because this is the simplest code path. - -If that works fine, try with ``io=0x378 irq=7`` (adjust for your -hardware), to make it use interrupt-driven in-software protocol. - -If **that** works fine, then one of the hardware modes isn't working -right. Enable ``CONFIG_FIFO`` (no, it isn't a module option, -and yes, it should be), set the port to ECP mode in the BIOS and note -the DMA channel, and try with:: - - io=0x378 irq=7 dma=none (for PIO) - io=0x378 irq=7 dma=3 (for DMA) - ----------- - -philb@gnu.org -tim@cyberelk.net diff --git a/Documentation/ramoops.txt b/Documentation/ramoops.txt deleted file mode 100644 index 7eaf1e71c083..000000000000 --- a/Documentation/ramoops.txt +++ /dev/null @@ -1,154 +0,0 @@ -Ramoops oops/panic logger -========================= - -Sergiu Iordache - -Updated: 17 November 2011 - -Introduction ------------- - -Ramoops is an oops/panic logger that writes its logs to RAM before the system -crashes. It works by logging oopses and panics in a circular buffer. Ramoops -needs a system with persistent RAM so that the content of that area can -survive after a restart. - -Ramoops concepts ----------------- - -Ramoops uses a predefined memory area to store the dump. The start and size -and type of the memory area are set using three variables: - - * ``mem_address`` for the start - * ``mem_size`` for the size. The memory size will be rounded down to a - power of two. - * ``mem_type`` to specifiy if the memory type (default is pgprot_writecombine). - -Typically the default value of ``mem_type=0`` should be used as that sets the pstore -mapping to pgprot_writecombine. Setting ``mem_type=1`` attempts to use -``pgprot_noncached``, which only works on some platforms. This is because pstore -depends on atomic operations. At least on ARM, pgprot_noncached causes the -memory to be mapped strongly ordered, and atomic operations on strongly ordered -memory are implementation defined, and won't work on many ARMs such as omaps. - -The memory area is divided into ``record_size`` chunks (also rounded down to -power of two) and each oops/panic writes a ``record_size`` chunk of -information. - -Dumping both oopses and panics can be done by setting 1 in the ``dump_oops`` -variable while setting 0 in that variable dumps only the panics. - -The module uses a counter to record multiple dumps but the counter gets reset -on restart (i.e. new dumps after the restart will overwrite old ones). - -Ramoops also supports software ECC protection of persistent memory regions. -This might be useful when a hardware reset was used to bring the machine back -to life (i.e. a watchdog triggered). In such cases, RAM may be somewhat -corrupt, but usually it is restorable. - -Setting the parameters ----------------------- - -Setting the ramoops parameters can be done in several different manners: - - A. Use the module parameters (which have the names of the variables described - as before). For quick debugging, you can also reserve parts of memory during - boot and then use the reserved memory for ramoops. For example, assuming a - machine with > 128 MB of memory, the following kernel command line will tell - the kernel to use only the first 128 MB of memory, and place ECC-protected - ramoops region at 128 MB boundary:: - - mem=128M ramoops.mem_address=0x8000000 ramoops.ecc=1 - - B. Use Device Tree bindings, as described in - ``Documentation/device-tree/bindings/reserved-memory/ramoops.txt``. - For example:: - - reserved-memory { - #address-cells = <2>; - #size-cells = <2>; - ranges; - - ramoops@8f000000 { - compatible = "ramoops"; - reg = <0 0x8f000000 0 0x100000>; - record-size = <0x4000>; - console-size = <0x4000>; - }; - }; - - C. Use a platform device and set the platform data. The parameters can then - be set through that platform data. An example of doing that is:: - - #include - [...] - - static struct ramoops_platform_data ramoops_data = { - .mem_size = <...>, - .mem_address = <...>, - .mem_type = <...>, - .record_size = <...>, - .dump_oops = <...>, - .ecc = <...>, - }; - - static struct platform_device ramoops_dev = { - .name = "ramoops", - .dev = { - .platform_data = &ramoops_data, - }, - }; - - [... inside a function ...] - int ret; - - ret = platform_device_register(&ramoops_dev); - if (ret) { - printk(KERN_ERR "unable to register platform device\n"); - return ret; - } - -You can specify either RAM memory or peripheral devices' memory. However, when -specifying RAM, be sure to reserve the memory by issuing memblock_reserve() -very early in the architecture code, e.g.:: - - #include - - memblock_reserve(ramoops_data.mem_address, ramoops_data.mem_size); - -Dump format ------------ - -The data dump begins with a header, currently defined as ``====`` followed by a -timestamp and a new line. The dump then continues with the actual data. - -Reading the data ----------------- - -The dump data can be read from the pstore filesystem. The format for these -files is ``dmesg-ramoops-N``, where N is the record number in memory. To delete -a stored record from RAM, simply unlink the respective pstore file. - -Persistent function tracing ---------------------------- - -Persistent function tracing might be useful for debugging software or hardware -related hangs. The functions call chain log is stored in a ``ftrace-ramoops`` -file. Here is an example of usage:: - - # mount -t debugfs debugfs /sys/kernel/debug/ - # echo 1 > /sys/kernel/debug/pstore/record_ftrace - # reboot -f - [...] - # mount -t pstore pstore /mnt/ - # tail /mnt/ftrace-ramoops - 0 ffffffff8101ea64 ffffffff8101bcda native_apic_mem_read <- disconnect_bsp_APIC+0x6a/0xc0 - 0 ffffffff8101ea44 ffffffff8101bcf6 native_apic_mem_write <- disconnect_bsp_APIC+0x86/0xc0 - 0 ffffffff81020084 ffffffff8101a4b5 hpet_disable <- native_machine_shutdown+0x75/0x90 - 0 ffffffff81005f94 ffffffff8101a4bb iommu_shutdown_noop <- native_machine_shutdown+0x7b/0x90 - 0 ffffffff8101a6a1 ffffffff8101a437 native_machine_emergency_restart <- native_machine_restart+0x37/0x40 - 0 ffffffff811f9876 ffffffff8101a73a acpi_reboot <- native_machine_emergency_restart+0xaa/0x1e0 - 0 ffffffff8101a514 ffffffff8101a772 mach_reboot_fixups <- native_machine_emergency_restart+0xe2/0x1e0 - 0 ffffffff811d9c54 ffffffff8101a7a0 __const_udelay <- native_machine_emergency_restart+0x110/0x1e0 - 0 ffffffff811d9c34 ffffffff811d9c80 __delay <- __const_udelay+0x30/0x40 - 0 ffffffff811d9d14 ffffffff811d9c3f delay_tsc <- __delay+0xf/0x20 diff --git a/Documentation/serial-console.txt b/Documentation/serial-console.txt deleted file mode 100644 index a8d1e36b627a..000000000000 --- a/Documentation/serial-console.txt +++ /dev/null @@ -1,115 +0,0 @@ -.. _serial_console: - -Linux Serial Console -==================== - -To use a serial port as console you need to compile the support into your -kernel - by default it is not compiled in. For PC style serial ports -it's the config option next to menu option: - -:menuselection:`Character devices --> Serial drivers --> 8250/16550 and compatible serial support --> Console on 8250/16550 and compatible serial port` - -You must compile serial support into the kernel and not as a module. - -It is possible to specify multiple devices for console output. You can -define a new kernel command line option to select which device(s) to -use for console output. - -The format of this option is:: - - console=device,options - - device: tty0 for the foreground virtual console - ttyX for any other virtual console - ttySx for a serial port - lp0 for the first parallel port - ttyUSB0 for the first USB serial device - - options: depend on the driver. For the serial port this - defines the baudrate/parity/bits/flow control of - the port, in the format BBBBPNF, where BBBB is the - speed, P is parity (n/o/e), N is number of bits, - and F is flow control ('r' for RTS). Default is - 9600n8. The maximum baudrate is 115200. - -You can specify multiple console= options on the kernel command line. -Output will appear on all of them. The last device will be used when -you open ``/dev/console``. So, for example:: - - console=ttyS1,9600 console=tty0 - -defines that opening ``/dev/console`` will get you the current foreground -virtual console, and kernel messages will appear on both the VGA -console and the 2nd serial port (ttyS1 or COM2) at 9600 baud. - -Note that you can only define one console per device type (serial, video). - -If no console device is specified, the first device found capable of -acting as a system console will be used. At this time, the system -first looks for a VGA card and then for a serial port. So if you don't -have a VGA card in your system the first serial port will automatically -become the console. - -You will need to create a new device to use ``/dev/console``. The official -``/dev/console`` is now character device 5,1. - -(You can also use a network device as a console. See -``Documentation/networking/netconsole.txt`` for information on that.) - -Here's an example that will use ``/dev/ttyS1`` (COM2) as the console. -Replace the sample values as needed. - -1. Create ``/dev/console`` (real console) and ``/dev/tty0`` (master virtual - console):: - - cd /dev - rm -f console tty0 - mknod -m 622 console c 5 1 - mknod -m 622 tty0 c 4 0 - -2. LILO can also take input from a serial device. This is a very - useful option. To tell LILO to use the serial port: - In lilo.conf (global section):: - - serial = 1,9600n8 (ttyS1, 9600 bd, no parity, 8 bits) - -3. Adjust to kernel flags for the new kernel, - again in lilo.conf (kernel section):: - - append = "console=ttyS1,9600" - -4. Make sure a getty runs on the serial port so that you can login to - it once the system is done booting. This is done by adding a line - like this to ``/etc/inittab`` (exact syntax depends on your getty):: - - S1:23:respawn:/sbin/getty -L ttyS1 9600 vt100 - -5. Init and ``/etc/ioctl.save`` - - Sysvinit remembers its stty settings in a file in ``/etc``, called - ``/etc/ioctl.save``. REMOVE THIS FILE before using the serial - console for the first time, because otherwise init will probably - set the baudrate to 38400 (baudrate of the virtual console). - -6. ``/dev/console`` and X - Programs that want to do something with the virtual console usually - open ``/dev/console``. If you have created the new ``/dev/console`` device, - and your console is NOT the virtual console some programs will fail. - Those are programs that want to access the VT interface, and use - ``/dev/console instead of /dev/tty0``. Some of those programs are:: - - Xfree86, svgalib, gpm, SVGATextMode - - It should be fixed in modern versions of these programs though. - - Note that if you boot without a ``console=`` option (or with - ``console=/dev/tty0``), ``/dev/console`` is the same as ``/dev/tty0``. - In that case everything will still work. - -7. Thanks - - Thanks to Geert Uytterhoeven - for porting the patches from 2.1.4x to 2.1.6x for taking care of - the integration of these patches into m68k, ppc and alpha. - -Miquel van Smoorenburg , 11-Jun-2000 diff --git a/Documentation/sysfs-rules.txt b/Documentation/sysfs-rules.txt deleted file mode 100644 index 04bdd52cba1d..000000000000 --- a/Documentation/sysfs-rules.txt +++ /dev/null @@ -1,192 +0,0 @@ -Rules on how to access information in the Linux kernel sysfs -============================================================ - -The kernel-exported sysfs exports internal kernel implementation details -and depends on internal kernel structures and layout. It is agreed upon -by the kernel developers that the Linux kernel does not provide a stable -internal API. Therefore, there are aspects of the sysfs interface that -may not be stable across kernel releases. - -To minimize the risk of breaking users of sysfs, which are in most cases -low-level userspace applications, with a new kernel release, the users -of sysfs must follow some rules to use an as-abstract-as-possible way to -access this filesystem. The current udev and HAL programs already -implement this and users are encouraged to plug, if possible, into the -abstractions these programs provide instead of accessing sysfs directly. - -But if you really do want or need to access sysfs directly, please follow -the following rules and then your programs should work with future -versions of the sysfs interface. - -- Do not use libsysfs - It makes assumptions about sysfs which are not true. Its API does not - offer any abstraction, it exposes all the kernel driver-core - implementation details in its own API. Therefore it is not better than - reading directories and opening the files yourself. - Also, it is not actively maintained, in the sense of reflecting the - current kernel development. The goal of providing a stable interface - to sysfs has failed; it causes more problems than it solves. It - violates many of the rules in this document. - -- sysfs is always at ``/sys`` - Parsing ``/proc/mounts`` is a waste of time. Other mount points are a - system configuration bug you should not try to solve. For test cases, - possibly support a ``SYSFS_PATH`` environment variable to overwrite the - application's behavior, but never try to search for sysfs. Never try - to mount it, if you are not an early boot script. - -- devices are only "devices" - There is no such thing like class-, bus-, physical devices, - interfaces, and such that you can rely on in userspace. Everything is - just simply a "device". Class-, bus-, physical, ... types are just - kernel implementation details which should not be expected by - applications that look for devices in sysfs. - - The properties of a device are: - - - devpath (``/devices/pci0000:00/0000:00:1d.1/usb2/2-2/2-2:1.0``) - - - identical to the DEVPATH value in the event sent from the kernel - at device creation and removal - - the unique key to the device at that point in time - - the kernel's path to the device directory without the leading - ``/sys``, and always starting with a slash - - all elements of a devpath must be real directories. Symlinks - pointing to /sys/devices must always be resolved to their real - target and the target path must be used to access the device. - That way the devpath to the device matches the devpath of the - kernel used at event time. - - using or exposing symlink values as elements in a devpath string - is a bug in the application - - - kernel name (``sda``, ``tty``, ``0000:00:1f.2``, ...) - - - a directory name, identical to the last element of the devpath - - applications need to handle spaces and characters like ``!`` in - the name - - - subsystem (``block``, ``tty``, ``pci``, ...) - - - simple string, never a path or a link - - retrieved by reading the "subsystem"-link and using only the - last element of the target path - - - driver (``tg3``, ``ata_piix``, ``uhci_hcd``) - - - a simple string, which may contain spaces, never a path or a - link - - it is retrieved by reading the "driver"-link and using only the - last element of the target path - - devices which do not have "driver"-link just do not have a - driver; copying the driver value in a child device context is a - bug in the application - - - attributes - - - the files in the device directory or files below subdirectories - of the same device directory - - accessing attributes reached by a symlink pointing to another device, - like the "device"-link, is a bug in the application - - Everything else is just a kernel driver-core implementation detail - that should not be assumed to be stable across kernel releases. - -- Properties of parent devices never belong into a child device. - Always look at the parent devices themselves for determining device - context properties. If the device ``eth0`` or ``sda`` does not have a - "driver"-link, then this device does not have a driver. Its value is empty. - Never copy any property of the parent-device into a child-device. Parent - device properties may change dynamically without any notice to the - child device. - -- Hierarchy in a single device tree - There is only one valid place in sysfs where hierarchy can be examined - and this is below: ``/sys/devices.`` - It is planned that all device directories will end up in the tree - below this directory. - -- Classification by subsystem - There are currently three places for classification of devices: - ``/sys/block,`` ``/sys/class`` and ``/sys/bus.`` It is planned that these will - not contain any device directories themselves, but only flat lists of - symlinks pointing to the unified ``/sys/devices`` tree. - All three places have completely different rules on how to access - device information. It is planned to merge all three - classification directories into one place at ``/sys/subsystem``, - following the layout of the bus directories. All buses and - classes, including the converted block subsystem, will show up - there. - The devices belonging to a subsystem will create a symlink in the - "devices" directory at ``/sys/subsystem//devices``, - - If ``/sys/subsystem`` exists, ``/sys/bus``, ``/sys/class`` and ``/sys/block`` - can be ignored. If it does not exist, you always have to scan all three - places, as the kernel is free to move a subsystem from one place to - the other, as long as the devices are still reachable by the same - subsystem name. - - Assuming ``/sys/class/`` and ``/sys/bus/``, or - ``/sys/block`` and ``/sys/class/block`` are not interchangeable is a bug in - the application. - -- Block - The converted block subsystem at ``/sys/class/block`` or - ``/sys/subsystem/block`` will contain the links for disks and partitions - at the same level, never in a hierarchy. Assuming the block subsystem to - contain only disks and not partition devices in the same flat list is - a bug in the application. - -- "device"-link and :-links - Never depend on the "device"-link. The "device"-link is a workaround - for the old layout, where class devices are not created in - ``/sys/devices/`` like the bus devices. If the link-resolving of a - device directory does not end in ``/sys/devices/``, you can use the - "device"-link to find the parent devices in ``/sys/devices/``, That is the - single valid use of the "device"-link; it must never appear in any - path as an element. Assuming the existence of the "device"-link for - a device in ``/sys/devices/`` is a bug in the application. - Accessing ``/sys/class/net/eth0/device`` is a bug in the application. - - Never depend on the class-specific links back to the ``/sys/class`` - directory. These links are also a workaround for the design mistake - that class devices are not created in ``/sys/devices.`` If a device - directory does not contain directories for child devices, these links - may be used to find the child devices in ``/sys/class.`` That is the single - valid use of these links; they must never appear in any path as an - element. Assuming the existence of these links for devices which are - real child device directories in the ``/sys/devices`` tree is a bug in - the application. - - It is planned to remove all these links when all class device - directories live in ``/sys/devices.`` - -- Position of devices along device chain can change. - Never depend on a specific parent device position in the devpath, - or the chain of parent devices. The kernel is free to insert devices into - the chain. You must always request the parent device you are looking for - by its subsystem value. You need to walk up the chain until you find - the device that matches the expected subsystem. Depending on a specific - position of a parent device or exposing relative paths using ``../`` to - access the chain of parents is a bug in the application. - -- When reading and writing sysfs device attribute files, avoid dependency - on specific error codes wherever possible. This minimizes coupling to - the error handling implementation within the kernel. - - In general, failures to read or write sysfs device attributes shall - propagate errors wherever possible. Common errors include, but are not - limited to: - - ``-EIO``: The read or store operation is not supported, typically - returned by the sysfs system itself if the read or store pointer - is ``NULL``. - - ``-ENXIO``: The read or store operation failed - - Error codes will not be changed without good reason, and should a change - to error codes result in user-space breakage, it will be fixed, or the - the offending change will be reverted. - - Userspace applications can, however, expect the format and contents of - the attribute files to remain consistent in the absence of a version - attribute change in the context of a given attribute. diff --git a/Documentation/sysrq.txt b/Documentation/sysrq.txt deleted file mode 100644 index d1712ea2d314..000000000000 --- a/Documentation/sysrq.txt +++ /dev/null @@ -1,289 +0,0 @@ -Linux Magic System Request Key Hacks -==================================== - -Documentation for sysrq.c - -What is the magic SysRq key? -~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -It is a 'magical' key combo you can hit which the kernel will respond to -regardless of whatever else it is doing, unless it is completely locked up. - -How do I enable the magic SysRq key? -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -You need to say "yes" to 'Magic SysRq key (CONFIG_MAGIC_SYSRQ)' when -configuring the kernel. When running a kernel with SysRq compiled in, -/proc/sys/kernel/sysrq controls the functions allowed to be invoked via -the SysRq key. The default value in this file is set by the -CONFIG_MAGIC_SYSRQ_DEFAULT_ENABLE config symbol, which itself defaults -to 1. Here is the list of possible values in /proc/sys/kernel/sysrq: - - - 0 - disable sysrq completely - - 1 - enable all functions of sysrq - - >1 - bitmask of allowed sysrq functions (see below for detailed function - description):: - - 2 = 0x2 - enable control of console logging level - 4 = 0x4 - enable control of keyboard (SAK, unraw) - 8 = 0x8 - enable debugging dumps of processes etc. - 16 = 0x10 - enable sync command - 32 = 0x20 - enable remount read-only - 64 = 0x40 - enable signalling of processes (term, kill, oom-kill) - 128 = 0x80 - allow reboot/poweroff - 256 = 0x100 - allow nicing of all RT tasks - -You can set the value in the file by the following command:: - - echo "number" >/proc/sys/kernel/sysrq - -The number may be written here either as decimal or as hexadecimal -with the 0x prefix. CONFIG_MAGIC_SYSRQ_DEFAULT_ENABLE must always be -written in hexadecimal. - -Note that the value of ``/proc/sys/kernel/sysrq`` influences only the invocation -via a keyboard. Invocation of any operation via ``/proc/sysrq-trigger`` is -always allowed (by a user with admin privileges). - -How do I use the magic SysRq key? -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -On x86 - You press the key combo :kbd:`ALT-SysRq-`. - -.. note:: - Some - keyboards may not have a key labeled 'SysRq'. The 'SysRq' key is - also known as the 'Print Screen' key. Also some keyboards cannot - handle so many keys being pressed at the same time, so you might - have better luck with press :kbd:`Alt`, press :kbd:`SysRq`, - release :kbd:`SysRq`, press :kbd:``, release everything. - -On SPARC - You press :kbd:`ALT-STOP-`, I believe. - -On the serial console (PC style standard serial ports only) - You send a ``BREAK``, then within 5 seconds a command key. Sending - ``BREAK`` twice is interpreted as a normal BREAK. - -On PowerPC - Press :kbd:`ALT - Print Screen` (or :kbd:`F13`) - :kbd:``, - :kbd:`Print Screen` (or :kbd:`F13`) - :kbd:`` may suffice. - -On other - If you know of the key combos for other architectures, please - let me know so I can add them to this section. - -On all - write a character to /proc/sysrq-trigger. e.g.:: - - echo t > /proc/sysrq-trigger - -What are the 'command' keys? -~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -=========== =================================================================== -Command Function -=========== =================================================================== -``b`` Will immediately reboot the system without syncing or unmounting - your disks. - -``c`` Will perform a system crash by a NULL pointer dereference. - A crashdump will be taken if configured. - -``d`` Shows all locks that are held. - -``e`` Send a SIGTERM to all processes, except for init. - -``f`` Will call the oom killer to kill a memory hog process, but do not - panic if nothing can be killed. - -``g`` Used by kgdb (kernel debugger) - -``h`` Will display help (actually any other key than those listed - here will display help. but ``h`` is easy to remember :-) - -``i`` Send a SIGKILL to all processes, except for init. - -``j`` Forcibly "Just thaw it" - filesystems frozen by the FIFREEZE ioctl. - -``k`` Secure Access Key (SAK) Kills all programs on the current virtual - console. NOTE: See important comments below in SAK section. - -``l`` Shows a stack backtrace for all active CPUs. - -``m`` Will dump current memory info to your console. - -``n`` Used to make RT tasks nice-able - -``o`` Will shut your system off (if configured and supported). - -``p`` Will dump the current registers and flags to your console. - -``q`` Will dump per CPU lists of all armed hrtimers (but NOT regular - timer_list timers) and detailed information about all - clockevent devices. - -``r`` Turns off keyboard raw mode and sets it to XLATE. - -``s`` Will attempt to sync all mounted filesystems. - -``t`` Will dump a list of current tasks and their information to your - console. - -``u`` Will attempt to remount all mounted filesystems read-only. - -``v`` Forcefully restores framebuffer console -``v`` Causes ETM buffer dump [ARM-specific] - -``w`` Dumps tasks that are in uninterruptable (blocked) state. - -``x`` Used by xmon interface on ppc/powerpc platforms. - Show global PMU Registers on sparc64. - Dump all TLB entries on MIPS. - -``y`` Show global CPU Registers [SPARC-64 specific] - -``z`` Dump the ftrace buffer - -``0``-``9`` Sets the console log level, controlling which kernel messages - will be printed to your console. (``0``, for example would make - it so that only emergency messages like PANICs or OOPSes would - make it to your console.) -=========== =================================================================== - -Okay, so what can I use them for? -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -Well, unraw(r) is very handy when your X server or a svgalib program crashes. - -sak(k) (Secure Access Key) is useful when you want to be sure there is no -trojan program running at console which could grab your password -when you would try to login. It will kill all programs on given console, -thus letting you make sure that the login prompt you see is actually -the one from init, not some trojan program. - -.. important:: - - In its true form it is not a true SAK like the one in a - c2 compliant system, and it should not be mistaken as - such. - -It seems others find it useful as (System Attention Key) which is -useful when you want to exit a program that will not let you switch consoles. -(For example, X or a svgalib program.) - -``reboot(b)`` is good when you're unable to shut down. But you should also -``sync(s)`` and ``umount(u)`` first. - -``crash(c)`` can be used to manually trigger a crashdump when the system is hung. -Note that this just triggers a crash if there is no dump mechanism available. - -``sync(s)`` is great when your system is locked up, it allows you to sync your -disks and will certainly lessen the chance of data loss and fscking. Note -that the sync hasn't taken place until you see the "OK" and "Done" appear -on the screen. (If the kernel is really in strife, you may not ever get the -OK or Done message...) - -``umount(u)`` is basically useful in the same ways as ``sync(s)``. I generally -``sync(s)``, ``umount(u)``, then ``reboot(b)`` when my system locks. It's saved -me many a fsck. Again, the unmount (remount read-only) hasn't taken place until -you see the "OK" and "Done" message appear on the screen. - -The loglevels ``0``-``9`` are useful when your console is being flooded with -kernel messages you do not want to see. Selecting ``0`` will prevent all but -the most urgent kernel messages from reaching your console. (They will -still be logged if syslogd/klogd are alive, though.) - -``term(e)`` and ``kill(i)`` are useful if you have some sort of runaway process -you are unable to kill any other way, especially if it's spawning other -processes. - -"just thaw ``it(j)``" is useful if your system becomes unresponsive due to a -frozen (probably root) filesystem via the FIFREEZE ioctl. - -Sometimes SysRq seems to get 'stuck' after using it, what can I do? -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -That happens to me, also. I've found that tapping shift, alt, and control -on both sides of the keyboard, and hitting an invalid sysrq sequence again -will fix the problem. (i.e., something like :kbd:`alt-sysrq-z`). Switching to -another virtual console (:kbd:`ALT+Fn`) and then back again should also help. - -I hit SysRq, but nothing seems to happen, what's wrong? -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -There are some keyboards that produce a different keycode for SysRq than the -pre-defined value of 99 (see ``KEY_SYSRQ`` in ``include/linux/input.h``), or -which don't have a SysRq key at all. In these cases, run ``showkey -s`` to find -an appropriate scancode sequence, and use ``setkeycodes 99`` to map -this sequence to the usual SysRq code (e.g., ``setkeycodes e05b 99``). It's -probably best to put this command in a boot script. Oh, and by the way, you -exit ``showkey`` by not typing anything for ten seconds. - -I want to add SysRQ key events to a module, how does it work? -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -In order to register a basic function with the table, you must first include -the header ``include/linux/sysrq.h``, this will define everything else you need. -Next, you must create a ``sysrq_key_op`` struct, and populate it with A) the key -handler function you will use, B) a help_msg string, that will print when SysRQ -prints help, and C) an action_msg string, that will print right before your -handler is called. Your handler must conform to the prototype in 'sysrq.h'. - -After the ``sysrq_key_op`` is created, you can call the kernel function -``register_sysrq_key(int key, struct sysrq_key_op *op_p);`` this will -register the operation pointed to by ``op_p`` at table key 'key', -if that slot in the table is blank. At module unload time, you must call -the function ``unregister_sysrq_key(int key, struct sysrq_key_op *op_p)``, which -will remove the key op pointed to by 'op_p' from the key 'key', if and only if -it is currently registered in that slot. This is in case the slot has been -overwritten since you registered it. - -The Magic SysRQ system works by registering key operations against a key op -lookup table, which is defined in 'drivers/tty/sysrq.c'. This key table has -a number of operations registered into it at compile time, but is mutable, -and 2 functions are exported for interface to it:: - - register_sysrq_key and unregister_sysrq_key. - -Of course, never ever leave an invalid pointer in the table. I.e., when -your module that called register_sysrq_key() exits, it must call -unregister_sysrq_key() to clean up the sysrq key table entry that it used. -Null pointers in the table are always safe. :) - -If for some reason you feel the need to call the handle_sysrq function from -within a function called by handle_sysrq, you must be aware that you are in -a lock (you are also in an interrupt handler, which means don't sleep!), so -you must call ``__handle_sysrq_nolock`` instead. - -When I hit a SysRq key combination only the header appears on the console? -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -Sysrq output is subject to the same console loglevel control as all -other console output. This means that if the kernel was booted 'quiet' -as is common on distro kernels the output may not appear on the actual -console, even though it will appear in the dmesg buffer, and be accessible -via the dmesg command and to the consumers of ``/proc/kmsg``. As a specific -exception the header line from the sysrq command is passed to all console -consumers as if the current loglevel was maximum. If only the header -is emitted it is almost certain that the kernel loglevel is too low. -Should you require the output on the console channel then you will need -to temporarily up the console loglevel using :kbd:`alt-sysrq-8` or:: - - echo 8 > /proc/sysrq-trigger - -Remember to return the loglevel to normal after triggering the sysrq -command you are interested in. - -I have more questions, who can I ask? -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -Just ask them on the linux-kernel mailing list: - linux-kernel@vger.kernel.org - -Credits -~~~~~~~ - -Written by Mydraal -Updated by Adam Sulmicki -Updated by Jeremy M. Dolan 2001/01/28 10:15:59 -Added to by Crutcher Dunnavant diff --git a/Documentation/unicode.txt b/Documentation/unicode.txt deleted file mode 100644 index 012e8e895842..000000000000 --- a/Documentation/unicode.txt +++ /dev/null @@ -1,189 +0,0 @@ -Unicode support -=============== - - Last update: 2005-01-17, version 1.4 - -This file is maintained by H. Peter Anvin as part -of the Linux Assigned Names And Numbers Authority (LANANA) project. -The current version can be found at: - - http://www.lanana.org/docs/unicode/unicode.txt - -Introdution ------------ - -The Linux kernel code has been rewritten to use Unicode to map -characters to fonts. By downloading a single Unicode-to-font table, -both the eight-bit character sets and UTF-8 mode are changed to use -the font as indicated. - -This changes the semantics of the eight-bit character tables subtly. -The four character tables are now: - -=============== =============================== ================ -Map symbol Map name Escape code (G0) -=============== =============================== ================ -LAT1_MAP Latin-1 (ISO 8859-1) ESC ( B -GRAF_MAP DEC VT100 pseudographics ESC ( 0 -IBMPC_MAP IBM code page 437 ESC ( U -USER_MAP User defined ESC ( K -=============== =============================== ================ - -In particular, ESC ( U is no longer "straight to font", since the font -might be completely different than the IBM character set. This -permits for example the use of block graphics even with a Latin-1 font -loaded. - -Note that although these codes are similar to ISO 2022, neither the -codes nor their uses match ISO 2022; Linux has two 8-bit codes (G0 and -G1), whereas ISO 2022 has four 7-bit codes (G0-G3). - -In accordance with the Unicode standard/ISO 10646 the range U+F000 to -U+F8FF has been reserved for OS-wide allocation (the Unicode Standard -refers to this as a "Corporate Zone", since this is inaccurate for -Linux we call it the "Linux Zone"). U+F000 was picked as the starting -point since it lets the direct-mapping area start on a large power of -two (in case 1024- or 2048-character fonts ever become necessary). -This leaves U+E000 to U+EFFF as End User Zone. - -[v1.2]: The Unicodes range from U+F000 and up to U+F7FF have been -hard-coded to map directly to the loaded font, bypassing the -translation table. The user-defined map now defaults to U+F000 to -U+F0FF, emulating the previous behaviour. In practice, this range -might be shorter; for example, vgacon can only handle 256-character -(U+F000..U+F0FF) or 512-character (U+F000..U+F1FF) fonts. - - -Actual characters assigned in the Linux Zone --------------------------------------------- - -In addition, the following characters not present in Unicode 1.1.4 -have been defined; these are used by the DEC VT graphics map. [v1.2] -THIS USE IS OBSOLETE AND SHOULD NO LONGER BE USED; PLEASE SEE BELOW. - -====== ====================================== -U+F800 DEC VT GRAPHICS HORIZONTAL LINE SCAN 1 -U+F801 DEC VT GRAPHICS HORIZONTAL LINE SCAN 3 -U+F803 DEC VT GRAPHICS HORIZONTAL LINE SCAN 7 -U+F804 DEC VT GRAPHICS HORIZONTAL LINE SCAN 9 -====== ====================================== - -The DEC VT220 uses a 6x10 character matrix, and these characters form -a smooth progression in the DEC VT graphics character set. I have -omitted the scan 5 line, since it is also used as a block-graphics -character, and hence has been coded as U+2500 FORMS LIGHT HORIZONTAL. - -[v1.3]: These characters have been officially added to Unicode 3.2.0; -they are added at U+23BA, U+23BB, U+23BC, U+23BD. Linux now uses the -new values. - -[v1.2]: The following characters have been added to represent common -keyboard symbols that are unlikely to ever be added to Unicode proper -since they are horribly vendor-specific. This, of course, is an -excellent example of horrible design. - -====== ====================================== -U+F810 KEYBOARD SYMBOL FLYING FLAG -U+F811 KEYBOARD SYMBOL PULLDOWN MENU -U+F812 KEYBOARD SYMBOL OPEN APPLE -U+F813 KEYBOARD SYMBOL SOLID APPLE -====== ====================================== - -Klingon language support ------------------------- - -In 1996, Linux was the first operating system in the world to add -support for the artificial language Klingon, created by Marc Okrand -for the "Star Trek" television series. This encoding was later -adopted by the ConScript Unicode Registry and proposed (but ultimately -rejected) for inclusion in Unicode Plane 1. Thus, it remains as a -Linux/CSUR private assignment in the Linux Zone. - -This encoding has been endorsed by the Klingon Language Institute. -For more information, contact them at: - - http://www.kli.org/ - -Since the characters in the beginning of the Linux CZ have been more -of the dingbats/symbols/forms type and this is a language, I have -located it at the end, on a 16-cell boundary in keeping with standard -Unicode practice. - -.. note:: - - This range is now officially managed by the ConScript Unicode - Registry. The normative reference is at: - - http://www.evertype.com/standards/csur/klingon.html - -Klingon has an alphabet of 26 characters, a positional numeric writing -system with 10 digits, and is written left-to-right, top-to-bottom. - -Several glyph forms for the Klingon alphabet have been proposed. -However, since the set of symbols appear to be consistent throughout, -with only the actual shapes being different, in keeping with standard -Unicode practice these differences are considered font variants. - -====== ======================================================= -U+F8D0 KLINGON LETTER A -U+F8D1 KLINGON LETTER B -U+F8D2 KLINGON LETTER CH -U+F8D3 KLINGON LETTER D -U+F8D4 KLINGON LETTER E -U+F8D5 KLINGON LETTER GH -U+F8D6 KLINGON LETTER H -U+F8D7 KLINGON LETTER I -U+F8D8 KLINGON LETTER J -U+F8D9 KLINGON LETTER L -U+F8DA KLINGON LETTER M -U+F8DB KLINGON LETTER N -U+F8DC KLINGON LETTER NG -U+F8DD KLINGON LETTER O -U+F8DE KLINGON LETTER P -U+F8DF KLINGON LETTER Q - - Written in standard Okrand Latin transliteration -U+F8E0 KLINGON LETTER QH - - Written in standard Okrand Latin transliteration -U+F8E1 KLINGON LETTER R -U+F8E2 KLINGON LETTER S -U+F8E3 KLINGON LETTER T -U+F8E4 KLINGON LETTER TLH -U+F8E5 KLINGON LETTER U -U+F8E6 KLINGON LETTER V -U+F8E7 KLINGON LETTER W -U+F8E8 KLINGON LETTER Y -U+F8E9 KLINGON LETTER GLOTTAL STOP - -U+F8F0 KLINGON DIGIT ZERO -U+F8F1 KLINGON DIGIT ONE -U+F8F2 KLINGON DIGIT TWO -U+F8F3 KLINGON DIGIT THREE -U+F8F4 KLINGON DIGIT FOUR -U+F8F5 KLINGON DIGIT FIVE -U+F8F6 KLINGON DIGIT SIX -U+F8F7 KLINGON DIGIT SEVEN -U+F8F8 KLINGON DIGIT EIGHT -U+F8F9 KLINGON DIGIT NINE - -U+F8FD KLINGON COMMA -U+F8FE KLINGON FULL STOP -U+F8FF KLINGON SYMBOL FOR EMPIRE -====== ======================================================= - -Other Fictional and Artificial Scripts --------------------------------------- - -Since the assignment of the Klingon Linux Unicode block, a registry of -fictional and artificial scripts has been established by John Cowan - and Michael Everson . -The ConScript Unicode Registry is accessible at: - - http://www.evertype.com/standards/csur/ - -The ranges used fall at the low end of the End User Zone and can hence -not be normatively assigned, but it is recommended that people who -wish to encode fictional scripts use these codes, in the interest of -interoperability. For Klingon, CSUR has adopted the Linux encoding. -The CSUR people are driving adding Tengwar and Cirth into Unicode -Plane 1; the addition of Klingon to Unicode Plane 1 has been rejected -and so the above encoding remains official. diff --git a/README b/README deleted file mode 100644 index 3335b3b2973a..000000000000 --- a/README +++ /dev/null @@ -1,411 +0,0 @@ -Linux kernel release 4.x -============================================= - -These are the release notes for Linux version 4. Read them carefully, -as they tell you what this is all about, explain how to install the -kernel, and what to do if something goes wrong. - -What is Linux? --------------- - - Linux is a clone of the operating system Unix, written from scratch by - Linus Torvalds with assistance from a loosely-knit team of hackers across - the Net. It aims towards POSIX and Single UNIX Specification compliance. - - It has all the features you would expect in a modern fully-fledged Unix, - including true multitasking, virtual memory, shared libraries, demand - loading, shared copy-on-write executables, proper memory management, - and multistack networking including IPv4 and IPv6. - - It is distributed under the GNU General Public License - see the - accompanying COPYING file for more details. - -On what hardware does it run? ------------------------------ - - Although originally developed first for 32-bit x86-based PCs (386 or higher), - today Linux also runs on (at least) the Compaq Alpha AXP, Sun SPARC and - UltraSPARC, Motorola 68000, PowerPC, PowerPC64, ARM, Hitachi SuperH, Cell, - IBM S/390, MIPS, HP PA-RISC, Intel IA-64, DEC VAX, AMD x86-64, AXIS CRIS, - Xtensa, Tilera TILE, AVR32, ARC and Renesas M32R architectures. - - Linux is easily portable to most general-purpose 32- or 64-bit architectures - as long as they have a paged memory management unit (PMMU) and a port of the - GNU C compiler (gcc) (part of The GNU Compiler Collection, GCC). Linux has - also been ported to a number of architectures without a PMMU, although - functionality is then obviously somewhat limited. - Linux has also been ported to itself. You can now run the kernel as a - userspace application - this is called UserMode Linux (UML). - -Documentation -------------- - - - There is a lot of documentation available both in electronic form on - the Internet and in books, both Linux-specific and pertaining to - general UNIX questions. I'd recommend looking into the documentation - subdirectories on any Linux FTP site for the LDP (Linux Documentation - Project) books. This README is not meant to be documentation on the - system: there are much better sources available. - - - There are various README files in the Documentation/ subdirectory: - these typically contain kernel-specific installation notes for some - drivers for example. See Documentation/00-INDEX for a list of what - is contained in each file. Please read the Changes file, as it - contains information about the problems, which may result by upgrading - your kernel. - - - The Documentation/DocBook/ subdirectory contains several guides for - kernel developers and users. These guides can be rendered in a - number of formats: PostScript (.ps), PDF, HTML, & man-pages, among others. - After installation, ``make psdocs``, ``make pdfdocs``, ``make htmldocs``, - or ``make mandocs`` will render the documentation in the requested format. - -Installing the kernel source ----------------------------- - - - If you install the full sources, put the kernel tarball in a - directory where you have permissions (e.g. your home directory) and - unpack it:: - - xz -cd linux-4.X.tar.xz | tar xvf - - - Replace "X" with the version number of the latest kernel. - - Do NOT use the /usr/src/linux area! This area has a (usually - incomplete) set of kernel headers that are used by the library header - files. They should match the library, and not get messed up by - whatever the kernel-du-jour happens to be. - - - You can also upgrade between 4.x releases by patching. Patches are - distributed in the xz format. To install by patching, get all the - newer patch files, enter the top level directory of the kernel source - (linux-4.X) and execute:: - - xz -cd ../patch-4.x.xz | patch -p1 - - Replace "x" for all versions bigger than the version "X" of your current - source tree, **in_order**, and you should be ok. You may want to remove - the backup files (some-file-name~ or some-file-name.orig), and make sure - that there are no failed patches (some-file-name# or some-file-name.rej). - If there are, either you or I have made a mistake. - - Unlike patches for the 4.x kernels, patches for the 4.x.y kernels - (also known as the -stable kernels) are not incremental but instead apply - directly to the base 4.x kernel. For example, if your base kernel is 4.0 - and you want to apply the 4.0.3 patch, you must not first apply the 4.0.1 - and 4.0.2 patches. Similarly, if you are running kernel version 4.0.2 and - want to jump to 4.0.3, you must first reverse the 4.0.2 patch (that is, - patch -R) **before** applying the 4.0.3 patch. You can read more on this in - :ref:`Documentation/applying-patches.txt `. - - Alternatively, the script patch-kernel can be used to automate this - process. It determines the current kernel version and applies any - patches found:: - - linux/scripts/patch-kernel linux - - The first argument in the command above is the location of the - kernel source. Patches are applied from the current directory, but - an alternative directory can be specified as the second argument. - - - Make sure you have no stale .o files and dependencies lying around:: - - cd linux - make mrproper - - You should now have the sources correctly installed. - -Software requirements ---------------------- - - Compiling and running the 4.x kernels requires up-to-date - versions of various software packages. Consult - :ref:`Documentation/Changes ` for the minimum version numbers - required and how to get updates for these packages. Beware that using - excessively old versions of these packages can cause indirect - errors that are very difficult to track down, so don't assume that - you can just update packages when obvious problems arise during - build or operation. - -Build directory for the kernel ------------------------------- - - When compiling the kernel, all output files will per default be - stored together with the kernel source code. - Using the option ``make O=output/dir`` allows you to specify an alternate - place for the output files (including .config). - Example:: - - kernel source code: /usr/src/linux-4.X - build directory: /home/name/build/kernel - - To configure and build the kernel, use:: - - cd /usr/src/linux-4.X - make O=/home/name/build/kernel menuconfig - make O=/home/name/build/kernel - sudo make O=/home/name/build/kernel modules_install install - - Please note: If the ``O=output/dir`` option is used, then it must be - used for all invocations of make. - -Configuring the kernel ----------------------- - - Do not skip this step even if you are only upgrading one minor - version. New configuration options are added in each release, and - odd problems will turn up if the configuration files are not set up - as expected. If you want to carry your existing configuration to a - new version with minimal work, use ``make oldconfig``, which will - only ask you for the answers to new questions. - - - Alternative configuration commands are:: - - "make config" Plain text interface. - - "make menuconfig" Text based color menus, radiolists & dialogs. - - "make nconfig" Enhanced text based color menus. - - "make xconfig" Qt based configuration tool. - - "make gconfig" GTK+ based configuration tool. - - "make oldconfig" Default all questions based on the contents of - your existing ./.config file and asking about - new config symbols. - - "make silentoldconfig" - Like above, but avoids cluttering the screen - with questions already answered. - Additionally updates the dependencies. - - "make olddefconfig" - Like above, but sets new symbols to their default - values without prompting. - - "make defconfig" Create a ./.config file by using the default - symbol values from either arch/$ARCH/defconfig - or arch/$ARCH/configs/${PLATFORM}_defconfig, - depending on the architecture. - - "make ${PLATFORM}_defconfig" - Create a ./.config file by using the default - symbol values from - arch/$ARCH/configs/${PLATFORM}_defconfig. - Use "make help" to get a list of all available - platforms of your architecture. - - "make allyesconfig" - Create a ./.config file by setting symbol - values to 'y' as much as possible. - - "make allmodconfig" - Create a ./.config file by setting symbol - values to 'm' as much as possible. - - "make allnoconfig" Create a ./.config file by setting symbol - values to 'n' as much as possible. - - "make randconfig" Create a ./.config file by setting symbol - values to random values. - - "make localmodconfig" Create a config based on current config and - loaded modules (lsmod). Disables any module - option that is not needed for the loaded modules. - - To create a localmodconfig for another machine, - store the lsmod of that machine into a file - and pass it in as a LSMOD parameter. - - target$ lsmod > /tmp/mylsmod - target$ scp /tmp/mylsmod host:/tmp - - host$ make LSMOD=/tmp/mylsmod localmodconfig - - The above also works when cross compiling. - - "make localyesconfig" Similar to localmodconfig, except it will convert - all module options to built in (=y) options. - - You can find more information on using the Linux kernel config tools - in Documentation/kbuild/kconfig.txt. - - - NOTES on ``make config``: - - - Having unnecessary drivers will make the kernel bigger, and can - under some circumstances lead to problems: probing for a - nonexistent controller card may confuse your other controllers - - - A kernel with math-emulation compiled in will still use the - coprocessor if one is present: the math emulation will just - never get used in that case. The kernel will be slightly larger, - but will work on different machines regardless of whether they - have a math coprocessor or not. - - - The "kernel hacking" configuration details usually result in a - bigger or slower kernel (or both), and can even make the kernel - less stable by configuring some routines to actively try to - break bad code to find kernel problems (kmalloc()). Thus you - should probably answer 'n' to the questions for "development", - "experimental", or "debugging" features. - -Compiling the kernel --------------------- - - - Make sure you have at least gcc 3.2 available. - For more information, refer to :ref:`Documentation/Changes `. - - Please note that you can still run a.out user programs with this kernel. - - - Do a ``make`` to create a compressed kernel image. It is also - possible to do ``make install`` if you have lilo installed to suit the - kernel makefiles, but you may want to check your particular lilo setup first. - - To do the actual install, you have to be root, but none of the normal - build should require that. Don't take the name of root in vain. - - - If you configured any of the parts of the kernel as ``modules``, you - will also have to do ``make modules_install``. - - - Verbose kernel compile/build output: - - Normally, the kernel build system runs in a fairly quiet mode (but not - totally silent). However, sometimes you or other kernel developers need - to see compile, link, or other commands exactly as they are executed. - For this, use "verbose" build mode. This is done by passing - ``V=1`` to the ``make`` command, e.g.:: - - make V=1 all - - To have the build system also tell the reason for the rebuild of each - target, use ``V=2``. The default is ``V=0``. - - - Keep a backup kernel handy in case something goes wrong. This is - especially true for the development releases, since each new release - contains new code which has not been debugged. Make sure you keep a - backup of the modules corresponding to that kernel, as well. If you - are installing a new kernel with the same version number as your - working kernel, make a backup of your modules directory before you - do a ``make modules_install``. - - Alternatively, before compiling, use the kernel config option - "LOCALVERSION" to append a unique suffix to the regular kernel version. - LOCALVERSION can be set in the "General Setup" menu. - - - In order to boot your new kernel, you'll need to copy the kernel - image (e.g. .../linux/arch/x86/boot/bzImage after compilation) - to the place where your regular bootable kernel is found. - - - Booting a kernel directly from a floppy without the assistance of a - bootloader such as LILO, is no longer supported. - - If you boot Linux from the hard drive, chances are you use LILO, which - uses the kernel image as specified in the file /etc/lilo.conf. The - kernel image file is usually /vmlinuz, /boot/vmlinuz, /bzImage or - /boot/bzImage. To use the new kernel, save a copy of the old image - and copy the new image over the old one. Then, you MUST RERUN LILO - to update the loading map! If you don't, you won't be able to boot - the new kernel image. - - Reinstalling LILO is usually a matter of running /sbin/lilo. - You may wish to edit /etc/lilo.conf to specify an entry for your - old kernel image (say, /vmlinux.old) in case the new one does not - work. See the LILO docs for more information. - - After reinstalling LILO, you should be all set. Shutdown the system, - reboot, and enjoy! - - If you ever need to change the default root device, video mode, - ramdisk size, etc. in the kernel image, use the ``rdev`` program (or - alternatively the LILO boot options when appropriate). No need to - recompile the kernel to change these parameters. - - - Reboot with the new kernel and enjoy. - -If something goes wrong ------------------------ - - - If you have problems that seem to be due to kernel bugs, please check - the file MAINTAINERS to see if there is a particular person associated - with the part of the kernel that you are having trouble with. If there - isn't anyone listed there, then the second best thing is to mail - them to me (torvalds@linux-foundation.org), and possibly to any other - relevant mailing-list or to the newsgroup. - - - In all bug-reports, *please* tell what kernel you are talking about, - how to duplicate the problem, and what your setup is (use your common - sense). If the problem is new, tell me so, and if the problem is - old, please try to tell me when you first noticed it. - - - If the bug results in a message like:: - - unable to handle kernel paging request at address C0000010 - Oops: 0002 - EIP: 0010:XXXXXXXX - eax: xxxxxxxx ebx: xxxxxxxx ecx: xxxxxxxx edx: xxxxxxxx - esi: xxxxxxxx edi: xxxxxxxx ebp: xxxxxxxx - ds: xxxx es: xxxx fs: xxxx gs: xxxx - Pid: xx, process nr: xx - xx xx xx xx xx xx xx xx xx xx - - or similar kernel debugging information on your screen or in your - system log, please duplicate it *exactly*. The dump may look - incomprehensible to you, but it does contain information that may - help debugging the problem. The text above the dump is also - important: it tells something about why the kernel dumped code (in - the above example, it's due to a bad kernel pointer). More information - on making sense of the dump is in Documentation/oops-tracing.txt - - - If you compiled the kernel with CONFIG_KALLSYMS you can send the dump - as is, otherwise you will have to use the ``ksymoops`` program to make - sense of the dump (but compiling with CONFIG_KALLSYMS is usually preferred). - This utility can be downloaded from - ftp://ftp..kernel.org/pub/linux/utils/kernel/ksymoops/ . - Alternatively, you can do the dump lookup by hand: - - - In debugging dumps like the above, it helps enormously if you can - look up what the EIP value means. The hex value as such doesn't help - me or anybody else very much: it will depend on your particular - kernel setup. What you should do is take the hex value from the EIP - line (ignore the ``0010:``), and look it up in the kernel namelist to - see which kernel function contains the offending address. - - To find out the kernel function name, you'll need to find the system - binary associated with the kernel that exhibited the symptom. This is - the file 'linux/vmlinux'. To extract the namelist and match it against - the EIP from the kernel crash, do:: - - nm vmlinux | sort | less - - This will give you a list of kernel addresses sorted in ascending - order, from which it is simple to find the function that contains the - offending address. Note that the address given by the kernel - debugging messages will not necessarily match exactly with the - function addresses (in fact, that is very unlikely), so you can't - just 'grep' the list: the list will, however, give you the starting - point of each kernel function, so by looking for the function that - has a starting address lower than the one you are searching for but - is followed by a function with a higher address you will find the one - you want. In fact, it may be a good idea to include a bit of - "context" in your problem report, giving a few lines around the - interesting one. - - If you for some reason cannot do the above (you have a pre-compiled - kernel image or similar), telling me as much about your setup as - possible will help. Please read the :ref:`REPORTING-BUGS ` - document for details. - - - Alternatively, you can use gdb on a running kernel. (read-only; i.e. you - cannot change values or set break points.) To do this, first compile the - kernel with -g; edit arch/x86/Makefile appropriately, then do a ``make - clean``. You'll also need to enable CONFIG_PROC_FS (via ``make config``). - - After you've rebooted with the new kernel, do ``gdb vmlinux /proc/kcore``. - You can now use all the usual gdb commands. The command to look up the - point where your system crashed is ``l *0xXXXXXXXX``. (Replace the XXXes - with the EIP value.) - - gdb'ing a non-running kernel currently fails because ``gdb`` (wrongly) - disregards the starting offset for which the kernel is compiled. - diff --git a/REPORTING-BUGS b/REPORTING-BUGS deleted file mode 100644 index 05c53ac7fa76..000000000000 --- a/REPORTING-BUGS +++ /dev/null @@ -1,182 +0,0 @@ -.. _reportingbugs: - -Reporting bugs -++++++++++++++ - -Background -========== - -The upstream Linux kernel maintainers only fix bugs for specific kernel -versions. Those versions include the current "release candidate" (or -rc) -kernel, any "stable" kernel versions, and any "long term" kernels. - -Please see https://www.kernel.org/ for a list of supported kernels. Any -kernel marked with [EOL] is "end of life" and will not have any fixes -backported to it. - -If you've found a bug on a kernel version that isn't listed on kernel.org, -contact your Linux distribution or embedded vendor for support. -Alternatively, you can attempt to run one of the supported stable or -rc -kernels, and see if you can reproduce the bug on that. It's preferable -to reproduce the bug on the latest -rc kernel. - - -How to report Linux kernel bugs -=============================== - - -Identify the problematic subsystem ----------------------------------- - -Identifying which part of the Linux kernel might be causing your issue -increases your chances of getting your bug fixed. Simply posting to the -generic linux-kernel mailing list (LKML) may cause your bug report to be -lost in the noise of a mailing list that gets 1000+ emails a day. - -Instead, try to figure out which kernel subsystem is causing the issue, -and email that subsystem's maintainer and mailing list. If the subsystem -maintainer doesn't answer, then expand your scope to mailing lists like -LKML. - - -Identify who to notify ----------------------- - -Once you know the subsystem that is causing the issue, you should send a -bug report. Some maintainers prefer bugs to be reported via bugzilla -(https://bugzilla.kernel.org), while others prefer that bugs be reported -via the subsystem mailing list. - -To find out where to send an emailed bug report, find your subsystem or -device driver in the MAINTAINERS file. Search in the file for relevant -entries, and send your bug report to the person(s) listed in the "M:" -lines, making sure to Cc the mailing list(s) in the "L:" lines. When the -maintainer replies to you, make sure to 'Reply-all' in order to keep the -public mailing list(s) in the email thread. - -If you know which driver is causing issues, you can pass one of the driver -files to the get_maintainer.pl script:: - - perl scripts/get_maintainer.pl -f - -If it is a security bug, please copy the Security Contact listed in the -MAINTAINERS file. They can help coordinate bugfix and disclosure. See -:ref:`Documentation/SecurityBugs ` for more information. - -If you can't figure out which subsystem caused the issue, you should file -a bug in kernel.org bugzilla and send email to -linux-kernel@vger.kernel.org, referencing the bugzilla URL. (For more -information on the linux-kernel mailing list see -http://www.tux.org/lkml/). - - -Tips for reporting bugs ------------------------ - -If you haven't reported a bug before, please read: - - http://www.chiark.greenend.org.uk/~sgtatham/bugs.html - - http://www.catb.org/esr/faqs/smart-questions.html - -It's REALLY important to report bugs that seem unrelated as separate email -threads or separate bugzilla entries. If you report several unrelated -bugs at once, it's difficult for maintainers to tease apart the relevant -data. - - -Gather information ------------------- - -The most important information in a bug report is how to reproduce the -bug. This includes system information, and (most importantly) -step-by-step instructions for how a user can trigger the bug. - -If the failure includes an "OOPS:", take a picture of the screen, capture -a netconsole trace, or type the message from your screen into the bug -report. Please read "Documentation/oops-tracing.txt" before posting your -bug report. This explains what you should do with the "Oops" information -to make it useful to the recipient. - -This is a suggested format for a bug report sent via email or bugzilla. -Having a standardized bug report form makes it easier for you not to -overlook things, and easier for the developers to find the pieces of -information they're really interested in. If some information is not -relevant to your bug, feel free to exclude it. - -First run the ver_linux script included as scripts/ver_linux, which -reports the version of some important subsystems. Run this script with -the command ``sh scripts/ver_linux``. - -Use that information to fill in all fields of the bug report form, and -post it to the mailing list with a subject of "PROBLEM: " for easy identification by the developers:: - - [1.] One line summary of the problem: - [2.] Full description of the problem/report: - [3.] Keywords (i.e., modules, networking, kernel): - [4.] Kernel information - [4.1.] Kernel version (from /proc/version): - [4.2.] Kernel .config file: - [5.] Most recent kernel version which did not have the bug: - [6.] Output of Oops.. message (if applicable) with symbolic information - resolved (see Documentation/oops-tracing.txt) - [7.] A small shell script or example program which triggers the - problem (if possible) - [8.] Environment - [8.1.] Software (add the output of the ver_linux script here) - [8.2.] Processor information (from /proc/cpuinfo): - [8.3.] Module information (from /proc/modules): - [8.4.] Loaded driver and hardware information (/proc/ioports, /proc/iomem) - [8.5.] PCI information ('lspci -vvv' as root) - [8.6.] SCSI information (from /proc/scsi/scsi) - [8.7.] Other information that might be relevant to the problem - (please look in /proc and include all information that you - think to be relevant): - [X.] Other notes, patches, fixes, workarounds: - - -Follow up -========= - -Expectations for bug reporters ------------------------------- - -Linux kernel maintainers expect bug reporters to be able to follow up on -bug reports. That may include running new tests, applying patches, -recompiling your kernel, and/or re-triggering your bug. The most -frustrating thing for maintainers is for someone to report a bug, and then -never follow up on a request to try out a fix. - -That said, it's still useful for a kernel maintainer to know a bug exists -on a supported kernel, even if you can't follow up with retests. Follow -up reports, such as replying to the email thread with "I tried the latest -kernel and I can't reproduce my bug anymore" are also helpful, because -maintainers have to assume silence means things are still broken. - -Expectations for kernel maintainers ------------------------------------ - -Linux kernel maintainers are busy, overworked human beings. Some times -they may not be able to address your bug in a day, a week, or two weeks. -If they don't answer your email, they may be on vacation, or at a Linux -conference. Check the conference schedule at https://LWN.net for more info: - - https://lwn.net/Calendar/ - -In general, kernel maintainers take 1 to 5 business days to respond to -bugs. The majority of kernel maintainers are employed to work on the -kernel, and they may not work on the weekends. Maintainers are scattered -around the world, and they may not work in your time zone. Unless you -have a high priority bug, please wait at least a week after the first bug -report before sending the maintainer a reminder email. - -The exceptions to this rule are regressions, kernel crashes, security holes, -or userspace breakage caused by new kernel behavior. Those bugs should be -addressed by the maintainers ASAP. If you suspect a maintainer is not -responding to these types of bugs in a timely manner (especially during a -merge window), escalate the bug to LKML and Linus Torvalds. - -Thank you! - -[Some of this is taken from Frohwalt Egerer's original linux-kernel FAQ] -- cgit v1.2.3 From 8c27ceff3604b249a9efafbd1bd8b141b79e619d Mon Sep 17 00:00:00 2001 From: Mauro Carvalho Chehab Date: Tue, 18 Oct 2016 10:12:27 -0200 Subject: docs: fix locations of several documents that got moved The previous patch renamed several files that are cross-referenced along the Kernel documentation. Adjust the links to point to the right places. Signed-off-by: Mauro Carvalho Chehab --- Documentation/00-INDEX | 54 +++++++++++----------- Documentation/ABI/README | 2 +- Documentation/ABI/testing/sysfs-kernel-slab | 2 +- Documentation/DocBook/kernel-hacking.tmpl | 4 +- Documentation/acpi/video_extension.txt | 2 +- Documentation/admin-guide/README.rst | 13 +++--- Documentation/admin-guide/bad-memory.rst | 2 +- Documentation/admin-guide/binfmt-misc.rst | 4 +- Documentation/admin-guide/braille-console.rst | 6 +-- Documentation/admin-guide/bug-hunting.rst | 7 +-- Documentation/admin-guide/devices.rst | 2 +- Documentation/admin-guide/kernel-parameters.rst | 6 +-- Documentation/admin-guide/oops-tracing.rst | 2 +- Documentation/admin-guide/ramoops.rst | 2 +- Documentation/admin-guide/reporting-bugs.rst | 6 +-- Documentation/admin-guide/security-bugs.rst | 2 +- Documentation/admin-guide/unicode.rst | 2 +- Documentation/arm/Booting | 2 +- Documentation/atomic_ops.txt | 2 +- Documentation/blockdev/ramdisk.txt | 2 +- Documentation/cgroup-v1/00-INDEX | 2 +- .../devicetree/bindings/rtc/maxim,ds3231.txt | 2 +- Documentation/devicetree/bindings/rtc/pcf8563.txt | 2 +- .../devicetree/bindings/submitting-patches.txt | 2 +- Documentation/filesystems/locks.txt | 2 +- Documentation/filesystems/nfs/nfsroot.txt | 4 +- Documentation/frv/booting.txt | 2 +- Documentation/hwmon/submitting-patches | 8 ++-- Documentation/isdn/README | 2 +- Documentation/ja_JP/HOWTO | 24 +++++----- Documentation/ja_JP/SubmitChecklist | 8 ++-- Documentation/ja_JP/SubmittingPatches | 18 ++++---- Documentation/ja_JP/stable_api_nonsense.txt | 4 +- Documentation/ja_JP/stable_kernel_rules.txt | 6 +-- Documentation/kernel-per-CPU-kthreads.txt | 2 +- Documentation/ko_KR/HOWTO | 30 ++++++------ Documentation/ko_KR/stable_api_nonsense.txt | 4 +- Documentation/lockup-watchdogs.txt | 4 +- Documentation/m68k/kernel-options.txt | 2 +- Documentation/media/uapi/v4l/diff-v4l.rst | 4 +- Documentation/media/v4l-drivers/bttv.rst | 4 +- Documentation/memory-hotplug.txt | 2 +- Documentation/networking/netconsole.txt | 2 +- Documentation/networking/netdev-FAQ.txt | 8 ++-- Documentation/networking/vortex.txt | 2 +- Documentation/power/00-INDEX | 2 +- Documentation/power/pci.txt | 10 ++-- Documentation/power/runtime_pm.txt | 2 +- Documentation/power/swsusp-dmcrypt.txt | 2 +- Documentation/process/4.Coding.rst | 4 +- Documentation/process/5.Posting.rst | 12 ++--- Documentation/process/8.Conclusion.rst | 6 +-- Documentation/process/adding-syscalls.rst | 2 +- Documentation/process/coding-style.rst | 2 +- Documentation/process/howto.rst | 24 +++++----- Documentation/process/management-style.rst | 2 +- Documentation/process/stable-kernel-rules.rst | 4 +- Documentation/process/submit-checklist.rst | 6 +-- Documentation/process/submitting-drivers.rst | 8 ++-- Documentation/process/submitting-patches.rst | 14 +++--- Documentation/rfkill.txt | 2 +- Documentation/scsi/scsi-parameters.txt | 2 +- Documentation/scsi/scsi_mid_low_api.txt | 2 +- Documentation/scsi/sym53c8xx_2.txt | 2 +- Documentation/sound/alsa/alsa-parameters.txt | 2 +- Documentation/sound/oss/oss-parameters.txt | 2 +- Documentation/sysctl/kernel.txt | 4 +- Documentation/virtual/kvm/review-checklist.txt | 4 +- Documentation/vm/numa | 2 +- .../watchdog/convert_drivers_to_kernel_api.txt | 2 +- Documentation/watchdog/watchdog-parameters.txt | 2 +- Documentation/x86/boot.txt | 2 +- Documentation/zh_CN/CodingStyle | 6 +-- Documentation/zh_CN/HOWTO | 30 ++++++------ Documentation/zh_CN/SecurityBugs | 6 +-- Documentation/zh_CN/SubmittingDrivers | 12 ++--- Documentation/zh_CN/SubmittingPatches | 14 +++--- Documentation/zh_CN/arm/Booting | 2 +- Documentation/zh_CN/email-clients.txt | 4 +- Documentation/zh_CN/oops-tracing.txt | 6 +-- Documentation/zh_CN/stable_api_nonsense.txt | 4 +- Documentation/zh_CN/stable_kernel_rules.txt | 6 +-- .../zh_CN/volatile-considered-harmful.txt | 4 +- MAINTAINERS | 10 ++-- arch/x86/Kconfig | 2 +- drivers/acpi/Kconfig | 2 +- drivers/ata/libata-core.c | 2 +- drivers/char/pcmcia/cm4000_cs.c | 4 +- drivers/net/can/grcan.c | 2 +- drivers/nvdimm/Kconfig | 2 +- drivers/staging/vme/devices/vme_user.c | 2 +- drivers/video/fbdev/skeletonfb.c | 8 ++-- drivers/virtio/Kconfig | 2 +- fs/Kconfig.binfmt | 4 +- fs/pstore/Kconfig | 2 +- include/linux/device.h | 2 +- include/linux/pm.h | 2 +- include/uapi/linux/major.h | 2 +- init/Kconfig | 2 +- init/main.c | 2 +- lib/Kconfig.debug | 2 +- scripts/checkpatch.pl | 6 +-- tools/testing/selftests/futex/README | 2 +- 103 files changed, 280 insertions(+), 278 deletions(-) diff --git a/Documentation/00-INDEX b/Documentation/00-INDEX index d07575a8499e..39caa6544d1f 100644 --- a/Documentation/00-INDEX +++ b/Documentation/00-INDEX @@ -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. @@ -154,7 +154,7 @@ 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 @@ -178,7 +178,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 +226,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 +248,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 +256,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 +302,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 +326,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 +340,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 +378,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 +406,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 +420,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 +444,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. @@ -466,7 +466,7 @@ 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. diff --git a/Documentation/ABI/README b/Documentation/ABI/README index 1fafc4b0753b..3121029dce21 100644 --- a/Documentation/ABI/README +++ b/Documentation/ABI/README @@ -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. diff --git a/Documentation/ABI/testing/sysfs-kernel-slab b/Documentation/ABI/testing/sysfs-kernel-slab index 91bd6ca5440f..2cc0a72b64be 100644 --- a/Documentation/ABI/testing/sysfs-kernel-slab +++ b/Documentation/ABI/testing/sysfs-kernel-slab @@ -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. diff --git a/Documentation/DocBook/kernel-hacking.tmpl b/Documentation/DocBook/kernel-hacking.tmpl index 2a272275c81b..da5c087462b1 100644 --- a/Documentation/DocBook/kernel-hacking.tmpl +++ b/Documentation/DocBook/kernel-hacking.tmpl @@ -1208,8 +1208,8 @@ static struct block_device_operations opt_fops = { - Finally, don't forget to read Documentation/SubmittingPatches - and possibly Documentation/SubmittingDrivers. + Finally, don't forget to read Documentation/process/submitting-patches.rst + and possibly Documentation/process/submitting-drivers.rst. diff --git a/Documentation/acpi/video_extension.txt b/Documentation/acpi/video_extension.txt index 78b32ac02466..79bf6a4921be 100644 --- a/Documentation/acpi/video_extension.txt +++ b/Documentation/acpi/video_extension.txt @@ -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. diff --git a/Documentation/admin-guide/README.rst b/Documentation/admin-guide/README.rst index 05aad8543340..1b6dfb2b3adb 100644 --- a/Documentation/admin-guide/README.rst +++ b/Documentation/admin-guide/README.rst @@ -50,7 +50,8 @@ Documentation - There are various README files in the Documentation/ subdirectory: these typically contain kernel-specific installation notes for some drivers for example. See Documentation/00-INDEX for a list of what - is contained in each file. Please read the Changes file, as it + is contained in each file. Please read the + :ref:`Documentation/process/changes.rst ` file, as it contains information about the problems, which may result by upgrading your kernel. @@ -96,7 +97,7 @@ Installing the kernel source and 4.0.2 patches. Similarly, if you are running kernel version 4.0.2 and want to jump to 4.0.3, you must first reverse the 4.0.2 patch (that is, patch -R) **before** applying the 4.0.3 patch. You can read more on this in - :ref:`Documentation/applying-patches.txt `. + :ref:`Documentation/process/applying-patches.rst `. Alternatively, the script patch-kernel can be used to automate this process. It determines the current kernel version and applies any @@ -120,7 +121,7 @@ Software requirements Compiling and running the 4.x kernels requires up-to-date versions of various software packages. Consult - :ref:`Documentation/Changes ` for the minimum version numbers + :ref:`Documentation/process/changes.rst ` 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 @@ -254,7 +255,7 @@ Compiling the kernel -------------------- - Make sure you have at least gcc 3.2 available. - For more information, refer to :ref:`Documentation/Changes `. + For more information, refer to :ref:`Documentation/process/changes.rst `. Please note that you can still run a.out user programs with this kernel. @@ -355,7 +356,7 @@ If something goes wrong help debugging the problem. The text above the dump is also important: it tells something about why the kernel dumped code (in the above example, it's due to a bad kernel pointer). More information - on making sense of the dump is in Documentation/oops-tracing.txt + 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 @@ -393,7 +394,7 @@ If something goes wrong If you for some reason cannot do the above (you have a pre-compiled kernel image or similar), telling me as much about your setup as - possible will help. Please read the :ref:`REPORTING-BUGS ` + possible will help. Please read the :ref:`admin-guide/reporting-bugs.rst ` document for details. - Alternatively, you can use gdb on a running kernel. (read-only; i.e. you diff --git a/Documentation/admin-guide/bad-memory.rst b/Documentation/admin-guide/bad-memory.rst index 017fc86430c3..a5c0e25e496f 100644 --- a/Documentation/admin-guide/bad-memory.rst +++ b/Documentation/admin-guide/bad-memory.rst @@ -33,7 +33,7 @@ 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):: +Syntax to exclude a memory area (see admin-guide/kernel-parameters.rst for details):: memmap=$
diff --git a/Documentation/admin-guide/binfmt-misc.rst b/Documentation/admin-guide/binfmt-misc.rst index 9c5ff8f260bf..97b0d7927078 100644 --- a/Documentation/admin-guide/binfmt-misc.rst +++ b/Documentation/admin-guide/binfmt-misc.rst @@ -124,7 +124,7 @@ A few examples (assumed you are in ``/proc/sys/fs/binfmt_misc``): echo ':DOSWin:M::MZ::/usr/local/bin/wine:' > register -For java support see Documentation/java.txt +For java support see Documentation/admin-guide/java.rst You can enable/disable binfmt_misc or one binary type by echoing 0 (to disable) @@ -140,7 +140,7 @@ Hints ----- If you want to pass special arguments to your interpreter, you can -write a wrapper script for it. See Documentation/java.txt for an +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 diff --git a/Documentation/admin-guide/braille-console.rst b/Documentation/admin-guide/braille-console.rst index fa3702dc04ab..18e79337dcfd 100644 --- a/Documentation/admin-guide/braille-console.rst +++ b/Documentation/admin-guide/braille-console.rst @@ -3,7 +3,7 @@ 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/serial-console.txt `), and +console (see :ref:`Documentation/admin-guide/serial-console.rst `), and for braille device (in :menuselection:`Device Drivers --> Accessibility support --> Console on braille device`). @@ -13,7 +13,7 @@ format is:: console=brl,serial_options... where ``serial_options...`` are the same as described in -:ref:`Documentation/serial-console.txt `. +:ref:`Documentation/admin-guide/serial-console.rst `. 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. @@ -31,7 +31,7 @@ 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/serial-console.txt `. +:ref:`Documentation/admin-guide/serial-console.rst `. For now, only the VisioBraille device is supported. diff --git a/Documentation/admin-guide/bug-hunting.rst b/Documentation/admin-guide/bug-hunting.rst index a8ef794aadae..d35dd9fd1af0 100644 --- a/Documentation/admin-guide/bug-hunting.rst +++ b/Documentation/admin-guide/bug-hunting.rst @@ -15,7 +15,7 @@ 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 -:ref:`Documentation/REPORTING-BUGS `. +:ref:`Documentation/admin-guide/reporting-bugs.rst `. Devices not appearing ===================== @@ -244,5 +244,6 @@ 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 :ref:`Documentation/SubmittingPatches ` -though to help your code get accepted. +Please do read +ref:`Documentation/process/submitting-patches.rst ` though +to help your code get accepted. diff --git a/Documentation/admin-guide/devices.rst b/Documentation/admin-guide/devices.rst index b29555041531..89db341fba7a 100644 --- a/Documentation/admin-guide/devices.rst +++ b/Documentation/admin-guide/devices.rst @@ -10,7 +10,7 @@ The LaTeX version of this document is no longer maintained, nor is the document that used to reside at lanana.org. This version in the mainline Linux kernel is the master document. Updates shall be sent as patches to the kernel maintainers (see the -:ref:`Documentation/SubmittingPatches ` document). +:ref:`Documentation/process/submitting-patches.rst ` document). Specifically explore the sections titled "CHAR and MISC DRIVERS", and "BLOCK LAYER" in the MAINTAINERS file to find the right maintainers to involve for character and block devices. diff --git a/Documentation/admin-guide/kernel-parameters.rst b/Documentation/admin-guide/kernel-parameters.rst index b0804273b6e3..d2f2725f032e 100644 --- a/Documentation/admin-guide/kernel-parameters.rst +++ b/Documentation/admin-guide/kernel-parameters.rst @@ -815,7 +815,7 @@ bytes respectively. Such letter suffixes can also be entirely omitted:: bits, and "f" is flow control ("r" for RTS or omit it). Default is "9600n8". - See Documentation/serial-console.txt for more + See Documentation/admin-guide/serial-console.rst for more information. See Documentation/networking/netconsole.txt for an alternative. @@ -2239,7 +2239,7 @@ bytes respectively. Such letter suffixes can also be entirely omitted:: mce=option [X86-64] See Documentation/x86/x86_64/boot-options.txt md= [HW] RAID subsystems devices and level - See Documentation/md.txt. + See Documentation/admin-guide/md.rst. mdacon= [MDA] Format: , @@ -3322,7 +3322,7 @@ bytes respectively. Such letter suffixes can also be entirely omitted:: r128= [HW,DRM] raid= [HW,RAID] - See Documentation/md.txt. + See Documentation/admin-guide/md.rst. ramdisk_size= [RAM] Sizes of RAM disks in kilobytes See Documentation/blockdev/ramdisk.txt. diff --git a/Documentation/admin-guide/oops-tracing.rst b/Documentation/admin-guide/oops-tracing.rst index 3e25ea7349ee..13be8d7bcfe7 100644 --- a/Documentation/admin-guide/oops-tracing.rst +++ b/Documentation/admin-guide/oops-tracing.rst @@ -44,7 +44,7 @@ the disk is not available then you have three options : so won't help for 'early' oopses) (2) Boot with a serial console (see - :ref:`Documentation/serial-console.txt `), + :ref:`Documentation/admin-guide/serial-console.rst `), run a null modem to a second machine and capture the output there using your favourite communication program. Minicom works well. diff --git a/Documentation/admin-guide/ramoops.rst b/Documentation/admin-guide/ramoops.rst index 7eaf1e71c083..fe95c027e37c 100644 --- a/Documentation/admin-guide/ramoops.rst +++ b/Documentation/admin-guide/ramoops.rst @@ -61,7 +61,7 @@ Setting the ramoops parameters can be done in several different manners: mem=128M ramoops.mem_address=0x8000000 ramoops.ecc=1 B. Use Device Tree bindings, as described in - ``Documentation/device-tree/bindings/reserved-memory/ramoops.txt``. + ``Documentation/device-tree/bindings/reserved-memory/admin-guide/ramoops.rst``. For example:: reserved-memory { diff --git a/Documentation/admin-guide/reporting-bugs.rst b/Documentation/admin-guide/reporting-bugs.rst index 05c53ac7fa76..0c0f2698ec5a 100644 --- a/Documentation/admin-guide/reporting-bugs.rst +++ b/Documentation/admin-guide/reporting-bugs.rst @@ -61,7 +61,7 @@ files to the get_maintainer.pl script:: If it is a security bug, please copy the Security Contact listed in the MAINTAINERS file. They can help coordinate bugfix and disclosure. See -:ref:`Documentation/SecurityBugs ` for more information. +:ref:`Documentation/admin-guide/security-bugs.rst ` for more information. If you can't figure out which subsystem caused the issue, you should file a bug in kernel.org bugzilla and send email to @@ -94,7 +94,7 @@ step-by-step instructions for how a user can trigger the bug. If the failure includes an "OOPS:", take a picture of the screen, capture a netconsole trace, or type the message from your screen into the bug -report. Please read "Documentation/oops-tracing.txt" before posting your +report. Please read "Documentation/admin-guide/oops-tracing.rst" before posting your bug report. This explains what you should do with the "Oops" information to make it useful to the recipient. @@ -120,7 +120,7 @@ summary from [1.]>" for easy identification by the developers:: [4.2.] Kernel .config file: [5.] Most recent kernel version which did not have the bug: [6.] Output of Oops.. message (if applicable) with symbolic information - resolved (see Documentation/oops-tracing.txt) + resolved (see Documentation/admin-guide/oops-tracing.rst) [7.] A small shell script or example program which triggers the problem (if possible) [8.] Environment diff --git a/Documentation/admin-guide/security-bugs.rst b/Documentation/admin-guide/security-bugs.rst index df795e22d08b..4f7414cad586 100644 --- a/Documentation/admin-guide/security-bugs.rst +++ b/Documentation/admin-guide/security-bugs.rst @@ -19,7 +19,7 @@ area maintainers to understand and fix the security vulnerability. As it is with any bug, the more information provided the easier it will be to diagnose and fix. Please review the procedure outlined in -REPORTING-BUGS if you are unclear about what information is helpful. +admin-guide/reporting-bugs.rst if you are unclear about what information is helpful. Any exploit code is very helpful and will not be released without consent from the reporter unless it has already been made public. diff --git a/Documentation/admin-guide/unicode.rst b/Documentation/admin-guide/unicode.rst index 012e8e895842..4e5c3df9d55f 100644 --- a/Documentation/admin-guide/unicode.rst +++ b/Documentation/admin-guide/unicode.rst @@ -7,7 +7,7 @@ This file is maintained by H. Peter Anvin as part of the Linux Assigned Names And Numbers Authority (LANANA) project. The current version can be found at: - http://www.lanana.org/docs/unicode/unicode.txt + http://www.lanana.org/docs/unicode/admin-guide/unicode.rst Introdution ----------- diff --git a/Documentation/arm/Booting b/Documentation/arm/Booting index 83c1df2fc758..259f00af3ab3 100644 --- a/Documentation/arm/Booting +++ b/Documentation/arm/Booting @@ -51,7 +51,7 @@ As an alternative, the boot loader can pass the relevant 'console=' option to the kernel via the tagged lists specifying the port, and serial format options as described in - Documentation/kernel-parameters.txt. + Documentation/admin-guide/kernel-parameters.rst. 3. Detect the machine type diff --git a/Documentation/atomic_ops.txt b/Documentation/atomic_ops.txt index c9d1cacb4395..7281bf939779 100644 --- a/Documentation/atomic_ops.txt +++ b/Documentation/atomic_ops.txt @@ -16,7 +16,7 @@ will fail. Something like the following should suffice: typedef struct { long counter; } atomic_long_t; Historically, counter has been declared volatile. This is now discouraged. -See Documentation/volatile-considered-harmful.txt for the complete rationale. +See Documentation/process/volatile-considered-harmful.rst for the complete rationale. local_t is very similar to atomic_t. If the counter is per CPU and only updated by one CPU, local_t is probably more appropriate. Please see diff --git a/Documentation/blockdev/ramdisk.txt b/Documentation/blockdev/ramdisk.txt index fe2ef978d85a..501e12e0323e 100644 --- a/Documentation/blockdev/ramdisk.txt +++ b/Documentation/blockdev/ramdisk.txt @@ -14,7 +14,7 @@ Contents: The RAM disk driver is a way to use main system memory as a block device. It is required for initrd, an initial filesystem used if you need to load modules -in order to access the root filesystem (see Documentation/initrd.txt). It can +in order to access the root filesystem (see Documentation/admin-guide/initrd.rst). It can also be used for a temporary filesystem for crypto work, since the contents are erased on reboot. diff --git a/Documentation/cgroup-v1/00-INDEX b/Documentation/cgroup-v1/00-INDEX index 106885ad670d..13e0c85e7b35 100644 --- a/Documentation/cgroup-v1/00-INDEX +++ b/Documentation/cgroup-v1/00-INDEX @@ -8,7 +8,7 @@ cpuacct.txt - CPU Accounting Controller; account CPU usage for groups of tasks. cpusets.txt - documents the cpusets feature; assign CPUs and Mem to a set of tasks. -devices.txt +admin-guide/devices.rst - Device Whitelist Controller; description, interface and security. freezer-subsystem.txt - checkpointing; rationale to not use signals, interface. diff --git a/Documentation/devicetree/bindings/rtc/maxim,ds3231.txt b/Documentation/devicetree/bindings/rtc/maxim,ds3231.txt index ddef330d2709..1ad4c1c2b3b3 100644 --- a/Documentation/devicetree/bindings/rtc/maxim,ds3231.txt +++ b/Documentation/devicetree/bindings/rtc/maxim,ds3231.txt @@ -1,7 +1,7 @@ * Maxim DS3231 Real Time Clock Required properties: -see: Documentation/devicetree/bindings/i2c/trivial-devices.txt +see: Documentation/devicetree/bindings/i2c/trivial-admin-guide/devices.rst Optional property: - #clock-cells: Should be 1. diff --git a/Documentation/devicetree/bindings/rtc/pcf8563.txt b/Documentation/devicetree/bindings/rtc/pcf8563.txt index 72f6d2c9665e..086c998c5561 100644 --- a/Documentation/devicetree/bindings/rtc/pcf8563.txt +++ b/Documentation/devicetree/bindings/rtc/pcf8563.txt @@ -3,7 +3,7 @@ Philips PCF8563/Epson RTC8564 Real Time Clock Required properties: -see: Documentation/devicetree/bindings/i2c/trivial-devices.txt +see: Documentation/devicetree/bindings/i2c/trivial-admin-guide/devices.rst Optional property: - #clock-cells: Should be 0. diff --git a/Documentation/devicetree/bindings/submitting-patches.txt b/Documentation/devicetree/bindings/submitting-patches.txt index 7d44eae7ab0b..274058c583dd 100644 --- a/Documentation/devicetree/bindings/submitting-patches.txt +++ b/Documentation/devicetree/bindings/submitting-patches.txt @@ -3,7 +3,7 @@ I. For patch submitters - 0) Normal patch submission rules from Documentation/SubmittingPatches + 0) Normal patch submission rules from Documentation/process/submitting-patches.rst applies. 1) The Documentation/ portion of the patch should be a separate patch. diff --git a/Documentation/filesystems/locks.txt b/Documentation/filesystems/locks.txt index 2cf81082581d..5368690f412e 100644 --- a/Documentation/filesystems/locks.txt +++ b/Documentation/filesystems/locks.txt @@ -19,7 +19,7 @@ forever. This should not cause problems for anybody, since everybody using a 2.1.x kernel should have updated their C library to a suitable version -anyway (see the file "Documentation/Changes".) +anyway (see the file "Documentation/process/changes.rst".) 1.2 Allow Mixed Locks Again --------------------------- diff --git a/Documentation/filesystems/nfs/nfsroot.txt b/Documentation/filesystems/nfs/nfsroot.txt index 0b2883b17d4c..5efae00f6c7f 100644 --- a/Documentation/filesystems/nfs/nfsroot.txt +++ b/Documentation/filesystems/nfs/nfsroot.txt @@ -11,7 +11,7 @@ Updated 2006 by Horms In order to use a diskless system, such as an X-terminal or printer server for example, it is necessary for the root filesystem to be present on a non-disk device. This may be an initramfs (see Documentation/filesystems/ -ramfs-rootfs-initramfs.txt), a ramdisk (see Documentation/initrd.txt) or a +ramfs-rootfs-initramfs.txt), a ramdisk (see Documentation/admin-guide/initrd.rst) or a filesystem mounted via NFS. The following text describes on how to use NFS for the root filesystem. For the rest of this text 'client' means the diskless system, and 'server' means the NFS server. @@ -284,7 +284,7 @@ They depend on various facilities being available: "kernel ". The nfsroot parameters are passed to the kernel by adding them to the "append" line. It is common to use serial console in conjunction with pxeliunx, - see Documentation/serial-console.txt for more information. + see Documentation/admin-guide/serial-console.rst for more information. For more information on isolinux, including how to create bootdisks for prebuilt kernels, see http://syslinux.zytor.com/ diff --git a/Documentation/frv/booting.txt b/Documentation/frv/booting.txt index 9bdf4b46e741..cd9dc1dfb144 100644 --- a/Documentation/frv/booting.txt +++ b/Documentation/frv/booting.txt @@ -119,7 +119,7 @@ separated by spaces: 253:0 Device with major 253 and minor 0 Authoritative information can be found in - "Documentation/kernel-parameters.txt". + "Documentation/admin-guide/kernel-parameters.rst". (*) rw diff --git a/Documentation/hwmon/submitting-patches b/Documentation/hwmon/submitting-patches index 57f60307accc..f88221b46153 100644 --- a/Documentation/hwmon/submitting-patches +++ b/Documentation/hwmon/submitting-patches @@ -10,10 +10,10 @@ increase the chances of your change being accepted. ---------- * It should be unnecessary to mention, but please read and follow - Documentation/SubmitChecklist - Documentation/SubmittingDrivers - Documentation/SubmittingPatches - Documentation/CodingStyle + Documentation/process/submit-checklist.rst + Documentation/process/submitting-drivers.rst + Documentation/process/submitting-patches.rst + Documentation/process/coding-style.rst * Please run your patch through 'checkpatch --strict'. There should be no errors, no warnings, and few if any check messages. If there are any diff --git a/Documentation/isdn/README b/Documentation/isdn/README index cfb1884342ee..32d4e80c2c03 100644 --- a/Documentation/isdn/README +++ b/Documentation/isdn/README @@ -332,7 +332,7 @@ README for the ISDN-subsystem 4. Device-inodes The major and minor numbers and their names are described in - Documentation/devices.txt. The major numbers are: + Documentation/admin-guide/devices.rst. The major numbers are: 43 for the ISDN-tty's. 44 for the ISDN-callout-tty's. diff --git a/Documentation/ja_JP/HOWTO b/Documentation/ja_JP/HOWTO index 581c14bdd7be..b03fc8047f03 100644 --- a/Documentation/ja_JP/HOWTO +++ b/Documentation/ja_JP/HOWTO @@ -127,15 +127,15 @@ linux-api@ver.kernel.org に送ることを勧めます。 小限のレベルで必要な数々のソフトウェアパッケージの一覧を示してい ます。 - Documentation/CodingStyle + Documentation/process/coding-style.rst これは Linux カーネルのコーディングスタイルと背景にある理由を記述 しています。全ての新しいコードはこのドキュメントにあるガイドライン に従っていることを期待されています。大部分のメンテナはこれらのルー ルに従っているものだけを受け付け、多くの人は正しいスタイルのコード だけをレビューします。 - Documentation/SubmittingPatches - Documentation/SubmittingDrivers + Documentation/process/submitting-patches.rst + Documentation/process/submitting-drivers.rst これらのファイルには、どうやってうまくパッチを作って投稿するかに ついて非常に詳しく書かれており、以下を含みます(これだけに限らない けれども) @@ -153,7 +153,7 @@ linux-api@ver.kernel.org に送ることを勧めます。 "Linux kernel patch submission format" http://linux.yyz.us/patch-format.html - Documentation/stable_api_nonsense.txt + Documentation/process/stable-api-nonsense.rst このファイルはカーネルの中に不変のAPIを持たないことにした意識的な 決断の背景にある理由について書かれています。以下のようなことを含 んでいます- @@ -164,29 +164,29 @@ linux-api@ver.kernel.org に送ることを勧めます。 このドキュメントは Linux 開発の思想を理解するのに非常に重要です。 そして、他のOSでの開発者が Linux に移る時にとても重要です。 - Documentation/SecurityBugs + Documentation/admin-guide/security-bugs.rst もし Linux カーネルでセキュリティ問題を発見したように思ったら、こ のドキュメントのステップに従ってカーネル開発者に連絡し、問題解決を 支援してください。 - Documentation/ManagementStyle + Documentation/process/management-style.rst このドキュメントは Linux カーネルのメンテナ達がどう行動するか、 彼らの手法の背景にある共有されている精神について記述しています。こ れはカーネル開発の初心者なら（もしくは、単に興味があるだけの人でも） 重要です。なぜならこのドキュメントは、カーネルメンテナ達の独特な 行動についての多くの誤解や混乱を解消するからです。 - Documentation/stable_kernel_rules.txt + Documentation/process/stable-kernel-rules.rst このファイルはどのように stable カーネルのリリースが行われるかのルー ルが記述されています。そしてこれらのリリースの中のどこかで変更を取 り入れてもらいたい場合に何をすれば良いかが示されています。 - Documentation/kernel-docs.txt + Documentation/process/kernel-docs.rst 　　カーネル開発に付随する外部ドキュメントのリストです。もしあなたが 探しているものがカーネル内のドキュメントでみつからなかった場合、 このリストをあたってみてください。 - Documentation/applying-patches.txt + Documentation/process/applying-patches.rst パッチとはなにか、パッチをどうやって様々なカーネルの開発ブランチに 適用するのかについて正確に記述した良い入門書です。 @@ -314,7 +314,7 @@ Andrew Morton が Linux-kernel メーリングリストにカーネルリリー た問題がなければもう少し長くなることもあります。セキュリティ関連の問題 の場合はこれに対してだいたいの場合、すぐにリリースがされます。 -カーネルツリーに入っている、Documentation/stable_kernel_rules.txt ファ +カーネルツリーに入っている、Documentation/process/stable-kernel-rules.rst ファ イルにはどのような種類の変更が -stable ツリーに受け入れ可能か、またリ リースプロセスがどう動くかが記述されています。 @@ -372,7 +372,7 @@ bugzilla.kernel.org は Linux カーネル開発者がカーネルのバグを 場所です。ユーザは見つけたバグの全てをこのツールで報告すべきです。 どう kernel bugzilla を使うかの詳細は、以下を参照してください- http://bugzilla.kernel.org/page.cgi?id=faq.html -メインカーネルソースディレクトリにあるファイル REPORTING-BUGS はカーネ +メインカーネルソースディレクトリにあるファイル admin-guide/reporting-bugs.rst はカーネ ルバグらしいものについてどうレポートするかの良いテンプレートであり、問 題の追跡を助けるためにカーネル開発者にとってどんな情報が必要なのかの詳 細が書かれています。 @@ -438,7 +438,7 @@ MAINTAINERS ファイルにリストがありますので参照してくださ メールの先頭でなく、各引用行の間にあなたの言いたいことを追加するべきで す。 -もしパッチをメールに付ける場合は、Documentation/SubmittingPatches に提 +もしパッチをメールに付ける場合は、Documentation/process/submitting-patches.rst に提 示されているように、それは プレーンな可読テキストにすることを忘れない ようにしましょう。カーネル開発者は 添付や圧縮したパッチを扱いたがりま せん- diff --git a/Documentation/ja_JP/SubmitChecklist b/Documentation/ja_JP/SubmitChecklist index cb5507b1ac81..60c7c35ac517 100644 --- a/Documentation/ja_JP/SubmitChecklist +++ b/Documentation/ja_JP/SubmitChecklist @@ -1,5 +1,5 @@ NOTE: -This is a version of Documentation/SubmitChecklist into Japanese. +This is a version of Documentation/process/submit-checklist.rst into Japanese. This document is maintained by Takenori Nagano and the JF Project team . If you find any difference between this document and the original file @@ -14,7 +14,7 @@ to update the original English file first. Last Updated: 2008/07/14 ================================== これは、 -linux-2.6.26/Documentation/SubmitChecklist の和訳です。 +linux-2.6.26/Documentation/process/submit-checklist.rst の和訳です。 翻訳団体： JF プロジェクト < http://www.linux.or.jp/JF/ > 翻訳日： 2008/07/14 @@ -27,7 +27,7 @@ Linux カーネルパッチ投稿者向けチェックリスト ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 本書では、パッチをより素早く取り込んでもらいたい開発者が実践すべき基本的な事柄 -をいくつか紹介します。ここにある全ての事柄は、Documentation/SubmittingPatches +をいくつか紹介します。ここにある全ての事柄は、Documentation/process/submitting-patches.rst などのLinuxカーネルパッチ投稿に際しての心得を補足するものです。 1: 妥当なCONFIGオプションや変更されたCONFIGオプション、つまり =y, =m, =n @@ -84,7 +84,7 @@ Linux カーネルパッチ投稿者向けチェックリスト 必ずドキュメントを追加してください。 17: 新しいブートパラメータを追加した場合には、 - 必ずDocumentation/kernel-parameters.txt に説明を追加してください。 + 必ずDocumentation/admin-guide/kernel-parameters.rst に説明を追加してください。 18: 新しくmoduleにパラメータを追加した場合には、MODULE_PARM_DESC()を 利用して必ずその説明を記述してください。 diff --git a/Documentation/ja_JP/SubmittingPatches b/Documentation/ja_JP/SubmittingPatches index 5d6ae639bfa0..02139656463e 100644 --- a/Documentation/ja_JP/SubmittingPatches +++ b/Documentation/ja_JP/SubmittingPatches @@ -1,5 +1,5 @@ NOTE: -This is a version of Documentation/SubmittingPatches into Japanese. +This is a version of Documentation/process/submitting-patches.rst into Japanese. This document is maintained by Keiichi KII and the JF Project team . If you find any difference between this document and the original file @@ -15,7 +15,7 @@ Last Updated: 2011/06/09 ================================== これは、 -linux-2.6.39/Documentation/SubmittingPatches の和訳 +linux-2.6.39/Documentation/process/submitting-patches.rst の和訳 です。 翻訳団体： JF プロジェクト < http://www.linux.or.jp/JF/ > 翻訳日： 2011/06/09 @@ -34,9 +34,9 @@ Linux カーネルに変更を加えたいと思っている個人又は会社 おじけづかせることもあります。この文章はあなたの変更を大いに受け入れ てもらえやすくする提案を集めたものです。 -コードを投稿する前に、Documentation/SubmitChecklist の項目リストに目 +コードを投稿する前に、Documentation/process/submit-checklist.rst の項目リストに目 を通してチェックしてください。もしあなたがドライバーを投稿しようとし -ているなら、Documentation/SubmittingDrivers にも目を通してください。 +ているなら、Documentation/process/submitting-drivers.rst にも目を通してください。 -------------------------------------------- セクション1 パッチの作り方と送り方 @@ -148,7 +148,7 @@ http://savannah.nongnu.org/projects/quilt 4) パッチのスタイルチェック あなたのパッチが基本的な( Linux カーネルの)コーディングスタイルに違反し -ていないかをチェックして下さい。その詳細を Documentation/CodingStyle で +ていないかをチェックして下さい。その詳細を Documentation/process/coding-style.rst で 見つけることができます。コーディングスタイルの違反はレビューする人の 時間を無駄にするだけなので、恐らくあなたのパッチは読まれることすらなく 拒否されるでしょう。 @@ -246,7 +246,7 @@ MIME 形式の添付ファイルは Linus に手間を取らせることにな あれば、誰かが MIME 形式のパッチを再送するよう求めるかもしれません。 余計な変更を加えずにあなたのパッチを送信するための電子メールクライアントの設定 -のヒントについては Documentation/email-clients.txt を参照してください。 +のヒントについては Documentation/process/email-clients.rst を参照してください。 8) 電子メールのサイズ @@ -609,7 +609,7 @@ diffstat の結果を生成するために「 git diff -M --stat --summary 」 し例外を適用するには、本当に妥当な理由が不可欠です。あなたは恐らくこの セクションを Linus のコンピュータ・サイエンス101と呼ぶでしょう。 -1) Documentation/CodingStyleを参照 +1) Documentation/process/coding-style.rstを参照 言うまでもなく、あなたのコードがこのコーディングスタイルからあまりに も逸脱していると、レビューやコメントなしに受け取ってもらえないかもし @@ -704,8 +704,8 @@ Greg Kroah-Hartman, "How to piss off a kernel subsystem maintainer". NO!!!! No more huge patch bombs to linux-kernel@vger.kernel.org people! -Kernel Documentation/CodingStyle: - +Kernel Documentation/process/coding-style.rst: + Linus Torvalds's mail on the canonical patch format: diff --git a/Documentation/ja_JP/stable_api_nonsense.txt b/Documentation/ja_JP/stable_api_nonsense.txt index 7653b5cbfed2..a3b40a4bdcfd 100644 --- a/Documentation/ja_JP/stable_api_nonsense.txt +++ b/Documentation/ja_JP/stable_api_nonsense.txt @@ -1,5 +1,5 @@ NOTE: -This is a version of Documentation/stable_api_nonsense.txt into Japanese. +This is a version of Documentation/process/stable-api-nonsense.rst into Japanese. This document is maintained by IKEDA, Munehiro and the JF Project team . If you find any difference between this document and the original file @@ -14,7 +14,7 @@ to update the original English file first. Last Updated: 2007/07/18 ================================== これは、 -linux-2.6.22-rc4/Documentation/stable_api_nonsense.txt の和訳 +linux-2.6.22-rc4/Documentation/process/stable-api-nonsense.rst の和訳 です。 翻訳団体： JF プロジェクト < http://www.linux.or.jp/JF/ > 翻訳日 ： 2007/06/11 diff --git a/Documentation/ja_JP/stable_kernel_rules.txt b/Documentation/ja_JP/stable_kernel_rules.txt index 9dbda9b5d21e..f9249aecba64 100644 --- a/Documentation/ja_JP/stable_kernel_rules.txt +++ b/Documentation/ja_JP/stable_kernel_rules.txt @@ -1,5 +1,5 @@ NOTE: -This is Japanese translated version of "Documentation/stable_kernel_rules.txt". +This is Japanese translated version of "Documentation/process/stable-kernel-rules.rst". This one is maintained by Tsugikazu Shibata and JF Project team . If you find difference with original file or problem in translation, @@ -12,7 +12,7 @@ file at first. ================================== これは、 -linux-2.6.29/Documentation/stable_kernel_rules.txt +linux-2.6.29/Documentation/process/stable-kernel-rules.rst の和訳です。 翻訳団体： JF プロジェクト < http://www.linux.or.jp/JF/ > @@ -43,7 +43,7 @@ linux-2.6.29/Documentation/stable_kernel_rules.txt "理論的には競合状態になる"ようなものは不可。 - いかなる些細な修正も含めることはできない。(スペルの修正、空白のクリー ンアップなど) - - Documentation/SubmittingPatches の規則に従ったものでなければならない。 + - Documentation/process/submitting-patches.rst の規則に従ったものでなければならない。 - パッチ自体か同等の修正が Linus のツリーに既に存在しなければならない。 　 Linus のツリーでのコミットID を -stable へのパッチ投稿の際に引用す ること。 diff --git a/Documentation/kernel-per-CPU-kthreads.txt b/Documentation/kernel-per-CPU-kthreads.txt index bbc3a8b8cff4..df31e30b6a02 100644 --- a/Documentation/kernel-per-CPU-kthreads.txt +++ b/Documentation/kernel-per-CPU-kthreads.txt @@ -264,7 +264,7 @@ To reduce its OS jitter, do at least one of the following: kthreads from being created in the first place. 2. Boot with "nosoftlockup=0", which will also prevent these kthreads from being created. Other related watchdog and softlockup boot - parameters may be found in Documentation/kernel-parameters.txt + parameters may be found in Documentation/admin-guide/kernel-parameters.rst and Documentation/watchdog/watchdog-parameters.txt. 3. Echo a zero to /proc/sys/kernel/watchdog to disable the watchdog timer. diff --git a/Documentation/ko_KR/HOWTO b/Documentation/ko_KR/HOWTO index 9a3e65924d54..025252731af5 100644 --- a/Documentation/ko_KR/HOWTO +++ b/Documentation/ko_KR/HOWTO @@ -1,5 +1,5 @@ NOTE: -This is a version of Documentation/HOWTO translated into korean +This is a version of Documentation/process/howto.rst translated into korean This document is maintained by Minchan Kim If you find any difference between this document and the original file or a problem with the translation, please contact the maintainer of this file. @@ -11,7 +11,7 @@ try to update the original English file first. ================================== 이 문서는 -Documentation/HOWTO +Documentation/process/howto.rst 의 한글 번역입니다. 역자： 김민찬 @@ -98,18 +98,18 @@ mtk.manpages@gmail.com의 메인테이너에게 보낼 것을 권장한다. 빌드하기 위해 필요한 것을 설명한다. 커널에 입문하는 사람들은 여기서 시작해야 한다. - Documentation/Changes + Documentation/process/changes.rst 이 파일은 커널을 성공적으로 빌드하고 실행시키기 위해 필요한 다양한 소프트웨어 패키지들의 최소 버젼을 나열한다. - Documentation/CodingStyle + Documentation/process/coding-style.rst 이 문서는 리눅스 커널 코딩 스타일과 그렇게 한 몇몇 이유를 설명한다. 모든 새로운 코드는 이 문서에 가이드라인들을 따라야 한다. 대부분의 메인테이너들은 이 규칙을 따르는 패치들만을 받아들일 것이고 많은 사람들이 그 패치가 올바른 스타일일 경우만 코드를 검토할 것이다. - Documentation/SubmittingPatches - Documentation/SubmittingDrivers + Documentation/process/submitting-patches.rst + Documentation/process/submitting-drivers.rst 이 파일들은 성공적으로 패치를 만들고 보내는 법을 다음의 내용들로 굉장히 상세히 설명하고 있다(그러나 다음으로 한정되진 않는다). - Email 내용들 @@ -126,7 +126,7 @@ mtk.manpages@gmail.com의 메인테이너에게 보낼 것을 권장한다. "Linux kernel patch submission format" http://linux.yyz.us/patch-format.html - Documentation/stable_api_nonsense.txt + Documentation/process/stable-api-nonsense.rst 이 문서는 의도적으로 커널이 불변하는 API를 갖지 않도록 결정한 이유를 설명하며 다음과 같은 것들을 포함한다. - 서브시스템 shim-layer(호환성을 위해?) @@ -136,12 +136,12 @@ mtk.manpages@gmail.com의 메인테이너에게 보낼 것을 권장한다. 리눅스로 전향하는 사람들에게는 매우 중요하다. - Documentation/SecurityBugs + Documentation/admin-guide/security-bugs.rst 여러분들이 리눅스 커널의 보안 문제를 발견했다고 생각한다면 이 문서에 나온 단계에 따라서 커널 개발자들에게 알리고 그 문제를 해결할 수 있도록 도와 달라. - Documentation/ManagementStyle + Documentation/process/management-style.rst 이 문서는 리눅스 커널 메인테이너들이 그들의 방법론에 녹아 있는 정신을 어떻게 공유하고 운영하는지를 설명한다. 이것은 커널 개발에 입문하는 모든 사람들(또는 커널 개발에 작은 호기심이라도 있는 사람들)이 @@ -149,17 +149,17 @@ mtk.manpages@gmail.com의 메인테이너에게 보낼 것을 권장한다. 독특한 행동에 관하여 흔히 있는 오해들과 혼란들을 해소하고 있기 때문이다. - Documentation/stable_kernel_rules.txt + Documentation/process/stable-kernel-rules.rst 이 문서는 안정적인 커널 배포가 이루어지는 규칙을 설명하고 있으며 여러분들이 이러한 배포들 중 하나에 변경을 하길 원한다면 무엇을 해야 하는지를 설명한다. - Documentation/kernel-docs.txt + Documentation/process/kernel-docs.rst 커널 개발에 관계된 외부 문서의 리스트이다. 커널 내의 포함된 문서들 중에 여러분이 찾고 싶은 문서를 발견하지 못할 경우 이 리스트를 살펴보라. - Documentation/applying-patches.txt + Documentation/process/applying-patches.rst 패치가 무엇이며 그것을 커널의 다른 개발 브랜치들에 어떻게 적용하는지에 관하여 자세히 설명하고 있는 좋은 입문서이다. @@ -276,7 +276,7 @@ Andrew Morton의 글이 있다. 4.x.y는 "stable" 팀에 의해 관리되며 거의 매번 격주로 배포된다. -커널 트리 문서들 내에 Documentation/stable_kernel_rules.txt 파일은 어떤 +커널 트리 문서들 내에 Documentation/process/stable-kernel-rules.rst 파일은 어떤 종류의 변경들이 -stable 트리로 들어왔는지와 배포 프로세스가 어떻게 진행되는지를 설명한다. @@ -328,7 +328,7 @@ bugzilla.kernel.org는 리눅스 커널 개발자들이 커널의 버그를 추 kernel bugzilla를 사용하는 자세한 방법은 다음을 참조하라. http://test.kernel.org/bugzilla/faq.html -메인 커널 소스 디렉토리에 있는 REPORTING-BUGS 파일은 커널 버그라고 생각되는 +메인 커널 소스 디렉토리에 있는 admin-guide/reporting-bugs.rst 파일은 커널 버그라고 생각되는 것을 보고하는 방법에 관한 좋은 템플릿이며 문제를 추적하기 위해서 커널 개발자들이 필요로 하는 정보가 무엇들인지를 상세히 설명하고 있다. @@ -391,7 +391,7 @@ bugme-janitor 메일링 리스트(bugzilla에 모든 변화들이 여기서 메 "John 커널해커는 작성했다...."를 유지하며 여러분들의 의견을 그 메일의 윗부분에 작성하지 말고 각 인용한 단락들 사이에 넣어라. -여러분들이 패치들을 메일에 넣는다면 그것들은 Documentation/SubmittingPatches에 +여러분들이 패치들을 메일에 넣는다면 그것들은 Documentation/process/submitting-patches.rst에 나와있는데로 명백히(plain) 읽을 수 있는 텍스트여야 한다. 커널 개발자들은 첨부파일이나 압축된 패치들을 원하지 않는다. 그들은 여러분들의 패치의 각 라인 단위로 코멘트를 하길 원하며 압축하거나 첨부하지 않고 보내는 것이 diff --git a/Documentation/ko_KR/stable_api_nonsense.txt b/Documentation/ko_KR/stable_api_nonsense.txt index 3ba10b11d556..4d93af1efd61 100644 --- a/Documentation/ko_KR/stable_api_nonsense.txt +++ b/Documentation/ko_KR/stable_api_nonsense.txt @@ -1,5 +1,5 @@ NOTE: -This is a version of Documentation/stable_api_nonsense.txt translated +This is a version of Documentation/process/stable-api-nonsense.rst translated into korean This document is maintained by Minchan Kim If you find any difference between this document and the original file or @@ -12,7 +12,7 @@ try to update the original English file first. ================================== 이 문서는 -Documentation/stable_api_nonsense.txt +Documentation/process/stable-api-nonsense.rst 의 한글 번역입니다. 역자： 김민찬 diff --git a/Documentation/lockup-watchdogs.txt b/Documentation/lockup-watchdogs.txt index 4a6e33e1af61..c8b8378513d6 100644 --- a/Documentation/lockup-watchdogs.txt +++ b/Documentation/lockup-watchdogs.txt @@ -11,7 +11,7 @@ details), without giving other tasks a chance to run. The current stack trace is displayed upon detection and, by default, the system will stay locked up. Alternatively, the kernel can be configured to panic; a sysctl, "kernel.softlockup_panic", a kernel parameter, -"softlockup_panic" (see "Documentation/kernel-parameters.txt" for +"softlockup_panic" (see "Documentation/admin-guide/kernel-parameters.rst" for details), and a compile option, "BOOTPARAM_SOFTLOCKUP_PANIC", are provided for this. @@ -23,7 +23,7 @@ upon detection and the system will stay locked up unless the default behavior is changed, which can be done through a sysctl, 'hardlockup_panic', a compile time knob, "BOOTPARAM_HARDLOCKUP_PANIC", and a kernel parameter, "nmi_watchdog" -(see "Documentation/kernel-parameters.txt" for details). +(see "Documentation/admin-guide/kernel-parameters.rst" for details). The panic option can be used in combination with panic_timeout (this timeout is set through the confusingly named "kernel.panic" sysctl), diff --git a/Documentation/m68k/kernel-options.txt b/Documentation/m68k/kernel-options.txt index eaf32a1fd0b1..79d21246c75a 100644 --- a/Documentation/m68k/kernel-options.txt +++ b/Documentation/m68k/kernel-options.txt @@ -139,7 +139,7 @@ follows: PARTUUID=00112233-4455-6677-8899-AABBCCDDEEFF/PARTNROFF=-2 Authoritative information can be found in -"Documentation/kernel-parameters.txt". +"Documentation/admin-guide/kernel-parameters.rst". 2.2) ro, rw diff --git a/Documentation/media/uapi/v4l/diff-v4l.rst b/Documentation/media/uapi/v4l/diff-v4l.rst index 76b2ecab8657..8209eeb63dd2 100644 --- a/Documentation/media/uapi/v4l/diff-v4l.rst +++ b/Documentation/media/uapi/v4l/diff-v4l.rst @@ -648,12 +648,12 @@ microcode programming. A new interface for MPEG compression and playback devices is documented in :ref:`extended-controls`. .. [#f1] - According to Documentation/devices.txt these should be symbolic links + According to Documentation/admin-guide/devices.rst these should be symbolic links to ``/dev/video0``. Note the original bttv interface is not compatible with V4L or V4L2. .. [#f2] - According to ``Documentation/devices.txt`` a symbolic link to + According to ``Documentation/admin-guide/devices.rst`` a symbolic link to ``/dev/radio0``. .. [#f3] diff --git a/Documentation/media/v4l-drivers/bttv.rst b/Documentation/media/v4l-drivers/bttv.rst index 7abc1c9a261b..bc63b12efafd 100644 --- a/Documentation/media/v4l-drivers/bttv.rst +++ b/Documentation/media/v4l-drivers/bttv.rst @@ -304,10 +304,10 @@ bug. It is very helpful if you can tell where exactly it broke With a hard freeze you probably doesn't find anything in the logfiles. The only way to capture any kernel messages is to hook up a serial console and let some terminal application log the messages. /me uses -screen. See Documentation/serial-console.txt for details on setting +screen. See Documentation/admin-guide/serial-console.rst for details on setting up a serial console. -Read Documentation/oops-tracing.txt to learn how to get any useful +Read Documentation/admin-guide/oops-tracing.rst to learn how to get any useful information out of a register+stack dump printed by the kernel on protection faults (so-called "kernel oops"). diff --git a/Documentation/memory-hotplug.txt b/Documentation/memory-hotplug.txt index 0d7cb955aa01..5de846d3ecc0 100644 --- a/Documentation/memory-hotplug.txt +++ b/Documentation/memory-hotplug.txt @@ -324,7 +324,7 @@ guarantee that the memory block contains only migratable pages. Now, a boot option for making a memory block which consists of migratable pages is supported. By specifying "kernelcore=" or "movablecore=" boot option, you can create ZONE_MOVABLE...a zone which is just used for movable pages. -(See also Documentation/kernel-parameters.txt) +(See also Documentation/admin-guide/kernel-parameters.rst) Assume the system has "TOTAL" amount of memory at boot time, this boot option creates ZONE_MOVABLE as following. diff --git a/Documentation/networking/netconsole.txt b/Documentation/networking/netconsole.txt index 30409a36e95d..296ea00fd3eb 100644 --- a/Documentation/networking/netconsole.txt +++ b/Documentation/networking/netconsole.txt @@ -200,7 +200,7 @@ priority messages to the console. You can change this at runtime using: or by specifying "debug" on the kernel command line at boot, to send all kernel messages to the console. A specific value for this parameter can also be set using the "loglevel" kernel boot option. See the -dmesg(8) man page and Documentation/kernel-parameters.txt for details. +dmesg(8) man page and Documentation/admin-guide/kernel-parameters.rst for details. Netconsole was designed to be as instantaneous as possible, to enable the logging of even the most critical kernel bugs. It works diff --git a/Documentation/networking/netdev-FAQ.txt b/Documentation/networking/netdev-FAQ.txt index 0fe1c6e0dbcd..cdebc5c8705f 100644 --- a/Documentation/networking/netdev-FAQ.txt +++ b/Documentation/networking/netdev-FAQ.txt @@ -136,14 +136,14 @@ A: Normally Greg Kroah-Hartman collects stable commits himself, but Q: I see a network patch and I think it should be backported to stable. Should I request it via "stable@vger.kernel.org" like the references in - the kernel's Documentation/stable_kernel_rules.txt file say? + the kernel's Documentation/process/stable-kernel-rules.rst file say? A: No, not for networking. Check the stable queues as per above 1st to see if it is already queued. If not, then send a mail to netdev, listing the upstream commit ID and why you think it should be a stable candidate. Before you jump to go do the above, do note that the normal stable rules - in Documentation/stable_kernel_rules.txt still apply. So you need to + in Documentation/process/stable-kernel-rules.rst still apply. So you need to explicitly indicate why it is a critical fix and exactly what users are impacted. In addition, you need to convince yourself that you _really_ think it has been overlooked, vs. having been considered and rejected. @@ -165,7 +165,7 @@ A: No. See above answer. In short, if you think it really belongs in If you think there is some valid information relating to it being in stable that does _not_ belong in the commit log, then use the three - dash marker line as described in Documentation/SubmittingPatches to + dash marker line as described in Documentation/process/submitting-patches.rst to temporarily embed that information into the patch that you send. Q: Someone said that the comment style and coding convention is different @@ -220,5 +220,5 @@ A: Attention to detail. Re-read your own work as if you were the If it is your first patch, mail it to yourself so you can test apply it to an unpatched tree to confirm infrastructure didn't mangle it. - Finally, go back and read Documentation/SubmittingPatches to be + Finally, go back and read Documentation/process/submitting-patches.rst to be sure you are not repeating some common mistake documented there. diff --git a/Documentation/networking/vortex.txt b/Documentation/networking/vortex.txt index 97282da82b75..ad3dead052a4 100644 --- a/Documentation/networking/vortex.txt +++ b/Documentation/networking/vortex.txt @@ -364,7 +364,7 @@ steps you should take: - The contents of your report will vary a lot depending upon the problem. If it's a kernel crash then you should refer to the - REPORTING-BUGS file. + admin-guide/reporting-bugs.rst file. But for most problems it is useful to provide the following: diff --git a/Documentation/power/00-INDEX b/Documentation/power/00-INDEX index ad04cc8097ed..7cb6085839f3 100644 --- a/Documentation/power/00-INDEX +++ b/Documentation/power/00-INDEX @@ -6,7 +6,7 @@ basic-pm-debugging.txt - Debugging suspend and resume charger-manager.txt - Battery charger management. -devices.txt +admin-guide/devices.rst - How drivers interact with system-wide power management drivers-testing.txt - Testing suspend and resume support in device drivers diff --git a/Documentation/power/pci.txt b/Documentation/power/pci.txt index 44558882aa60..85c746cbab2c 100644 --- a/Documentation/power/pci.txt +++ b/Documentation/power/pci.txt @@ -8,7 +8,7 @@ management. Based on previous work by Patrick Mochel This document only covers the aspects of power management specific to PCI devices. For general description of the kernel's interfaces related to device -power management refer to Documentation/power/devices.txt and +power management refer to Documentation/power/admin-guide/devices.rst and Documentation/power/runtime_pm.txt. --------------------------------------------------------------------------- @@ -417,7 +417,7 @@ pm->runtime_idle() callback. 2.4. System-Wide Power Transitions ---------------------------------- There are a few different types of system-wide power transitions, described in -Documentation/power/devices.txt. Each of them requires devices to be handled +Documentation/power/admin-guide/devices.rst. Each of them requires devices to be handled in a specific way and the PM core executes subsystem-level power management callbacks for this purpose. They are executed in phases such that each phase involves executing the same subsystem-level callback for every device belonging @@ -623,7 +623,7 @@ System restore requires a hibernation image to be loaded into memory and the pre-hibernation memory contents to be restored before the pre-hibernation system activity can be resumed. -As described in Documentation/power/devices.txt, the hibernation image is loaded +As described in Documentation/power/admin-guide/devices.rst, the hibernation image is loaded into memory by a fresh instance of the kernel, called the boot kernel, which in turn is loaded and run by a boot loader in the usual way. After the boot kernel has loaded the image, it needs to replace its own code and data with the code @@ -677,7 +677,7 @@ controlling the runtime power management of their devices. At the time of this writing there are two ways to define power management callbacks for a PCI device driver, the recommended one, based on using a -dev_pm_ops structure described in Documentation/power/devices.txt, and the +dev_pm_ops structure described in Documentation/power/admin-guide/devices.rst, and the "legacy" one, in which the .suspend(), .suspend_late(), .resume_early(), and .resume() callbacks from struct pci_driver are used. The legacy approach, however, doesn't allow one to define runtime power management callbacks and is @@ -1046,5 +1046,5 @@ PCI Local Bus Specification, Rev. 3.0 PCI Bus Power Management Interface Specification, Rev. 1.2 Advanced Configuration and Power Interface (ACPI) Specification, Rev. 3.0b PCI Express Base Specification, Rev. 2.0 -Documentation/power/devices.txt +Documentation/power/admin-guide/devices.rst Documentation/power/runtime_pm.txt diff --git a/Documentation/power/runtime_pm.txt b/Documentation/power/runtime_pm.txt index 1fd1fbe9ce95..4870980e967e 100644 --- a/Documentation/power/runtime_pm.txt +++ b/Documentation/power/runtime_pm.txt @@ -674,7 +674,7 @@ left in runtime suspend. If that happens, the PM core will not execute any system suspend and resume callbacks for all of those devices, except for the complete callback, which is then entirely responsible for handling the device as appropriate. This only applies to system suspend transitions that are not -related to hibernation (see Documentation/power/devices.txt for more +related to hibernation (see Documentation/power/admin-guide/devices.rst for more information). The PM core does its best to reduce the probability of race conditions between diff --git a/Documentation/power/swsusp-dmcrypt.txt b/Documentation/power/swsusp-dmcrypt.txt index 59931b46ff7e..b802fbfd95ef 100644 --- a/Documentation/power/swsusp-dmcrypt.txt +++ b/Documentation/power/swsusp-dmcrypt.txt @@ -8,7 +8,7 @@ Some prerequisites: You know how dm-crypt works. If not, visit the following web page: http://www.saout.de/misc/dm-crypt/ You have read Documentation/power/swsusp.txt and understand it. -You did read Documentation/initrd.txt and know how an initrd works. +You did read Documentation/admin-guide/initrd.rst and know how an initrd works. You know how to create or how to modify an initrd. Now your system is properly set up, your disk is encrypted except for diff --git a/Documentation/process/4.Coding.rst b/Documentation/process/4.Coding.rst index 9d5cef996f7f..983d628c1112 100644 --- a/Documentation/process/4.Coding.rst +++ b/Documentation/process/4.Coding.rst @@ -22,7 +22,7 @@ Coding style ************ The kernel has long had a standard coding style, described in -Documentation/CodingStyle. For much of that time, the policies described +Documentation/process/coding-style.rst. For much of that time, the policies described in that file were taken as being, at most, advisory. As a result, there is a substantial amount of code in the kernel which does not meet the coding style guidelines. The presence of that code leads to two independent @@ -343,7 +343,7 @@ user-space developers to know what they are working with. See Documentation/ABI/README for a description of how this documentation should be formatted and what information needs to be provided. -The file Documentation/kernel-parameters.txt describes all of the kernel's +The file Documentation/admin-guide/kernel-parameters.rst describes all of the kernel's boot-time parameters. Any patch which adds new parameters should add the appropriate entries to this file. diff --git a/Documentation/process/5.Posting.rst b/Documentation/process/5.Posting.rst index b511ddf7e82a..1b7728b19ea7 100644 --- a/Documentation/process/5.Posting.rst +++ b/Documentation/process/5.Posting.rst @@ -9,8 +9,8 @@ kernel. Unsurprisingly, the kernel development community has evolved a set of conventions and procedures which are used in the posting of patches; following them will make life much easier for everybody involved. This document will attempt to cover these expectations in reasonable detail; -more information can also be found in the files SubmittingPatches, -SubmittingDrivers, and SubmitChecklist in the kernel documentation +more information can also be found in the files process/submitting-patches.rst, +process/submitting-drivers.rst, and process/submit-checklist.rst in the kernel documentation directory. @@ -198,7 +198,7 @@ pass it to diff with the "-X" option. The tags mentioned above are used to describe how various developers have been associated with the development of this patch. They are described in -detail in the SubmittingPatches document; what follows here is a brief +detail in the process/submitting-patches.rst document; what follows here is a brief summary. Each of these lines has the format: :: @@ -210,7 +210,7 @@ The tags in common use are: - Signed-off-by: this is a developer's certification that he or she has the right to submit the patch for inclusion into the kernel. It is an agreement to the Developer's Certificate of Origin, the full text of - which can be found in Documentation/SubmittingPatches. Code without a + which can be found in Documentation/process/submitting-patches.rst. Code without a proper signoff cannot be merged into the mainline. - Acked-by: indicates an agreement by another developer (often a @@ -221,7 +221,7 @@ The tags in common use are: it to work. - Reviewed-by: the named developer has reviewed the patch for correctness; - see the reviewer's statement in Documentation/SubmittingPatches for more + see the reviewer's statement in Documentation/process/submitting-patches.rst for more detail. - Reported-by: names a user who reported a problem which is fixed by this @@ -248,7 +248,7 @@ take care of: be examined in any detail. If there is any doubt at all, mail the patch to yourself and convince yourself that it shows up intact. - Documentation/email-clients.txt has some helpful hints on making + Documentation/process/email-clients.rst has some helpful hints on making specific mail clients work for sending patches. - Are you sure your patch is free of silly mistakes? You should always diff --git a/Documentation/process/8.Conclusion.rst b/Documentation/process/8.Conclusion.rst index 23ec7cbc2d2b..1c7f54cd0261 100644 --- a/Documentation/process/8.Conclusion.rst +++ b/Documentation/process/8.Conclusion.rst @@ -5,9 +5,9 @@ For more information There are numerous sources of information on Linux kernel development and related topics. First among those will always be the Documentation -directory found in the kernel source distribution. The top-level HOWTO -file is an important starting point; SubmittingPatches and -SubmittingDrivers are also something which all kernel developers should +directory found in the kernel source distribution. The top-level process/howto.rst +file is an important starting point; process/submitting-patches.rst and +process/submitting-drivers.rst are also something which all kernel developers should read. Many internal kernel APIs are documented using the kerneldoc mechanism; "make htmldocs" or "make pdfdocs" can be used to generate those documents in HTML or PDF format (though the version of TeX shipped by some diff --git a/Documentation/process/adding-syscalls.rst b/Documentation/process/adding-syscalls.rst index f5b5b1aa51b3..8cc25a06f353 100644 --- a/Documentation/process/adding-syscalls.rst +++ b/Documentation/process/adding-syscalls.rst @@ -3,7 +3,7 @@ Adding a New System Call This document describes what's involved in adding a new system call to the Linux kernel, over and above the normal submission advice in -:ref:`Documentation/SubmittingPatches `. +:ref:`Documentation/process/submitting-patches.rst `. System Call Alternatives diff --git a/Documentation/process/coding-style.rst b/Documentation/process/coding-style.rst index 9c61c039ccd9..968808bec407 100644 --- a/Documentation/process/coding-style.rst +++ b/Documentation/process/coding-style.rst @@ -1058,5 +1058,5 @@ gcc internals and indent, all available from http://www.gnu.org/manual/ WG14 is the international standardization working group for the programming language C, URL: http://www.open-std.org/JTC1/SC22/WG14/ -Kernel CodingStyle, by greg@kroah.com at OLS 2002: +Kernel process/coding-style.rst, by greg@kroah.com at OLS 2002: http://www.kroah.com/linux/talks/ols_2002_kernel_codingstyle_talk/html/ diff --git a/Documentation/process/howto.rst b/Documentation/process/howto.rst index 5f042349f987..3f66a1980726 100644 --- a/Documentation/process/howto.rst +++ b/Documentation/process/howto.rst @@ -90,19 +90,19 @@ required reading: what is necessary to do to configure and build the kernel. People who are new to the kernel should start here. - :ref:`Documentation/Changes ` + :ref:`Documentation/process/changes.rst ` This file gives a list of the minimum levels of various software packages that are necessary to build and run the kernel successfully. - :ref:`Documentation/CodingStyle ` + :ref:`Documentation/process/coding-style.rst ` This describes the Linux kernel coding style, and some of the rationale behind it. All new code is expected to follow the guidelines in this document. Most maintainers will only accept patches if these rules are followed, and many people will only review code if it is in the proper style. - :ref:`Documentation/SubmittingPatches ` and :ref:`Documentation/SubmittingDrivers ` + :ref:`Documentation/process/submitting-patches.rst ` and :ref:`Documentation/process/submitting-drivers.rst ` These files describe in explicit detail how to successfully create and send a patch, including (but not limited to): @@ -122,7 +122,7 @@ required reading: "Linux kernel patch submission format" http://linux.yyz.us/patch-format.html - :ref:`Documentation/stable_api_nonsense.txt ` + :ref:`Documentation/process/stable-api-nonsense.rst ` This file describes the rationale behind the conscious decision to not have a stable API within the kernel, including things like: @@ -135,29 +135,29 @@ required reading: philosophy and is very important for people moving to Linux from development on other Operating Systems. - :ref:`Documentation/SecurityBugs ` + :ref:`Documentation/admin-guide/security-bugs.rst ` If you feel you have found a security problem in the Linux kernel, please follow the steps in this document to help notify the kernel developers, and help solve the issue. - :ref:`Documentation/ManagementStyle ` + :ref:`Documentation/process/management-style.rst ` This document describes how Linux kernel maintainers operate and the shared ethos behind their methodologies. This is important reading for anyone new to kernel development (or anyone simply curious about it), as it resolves a lot of common misconceptions and confusion about the unique behavior of kernel maintainers. - :ref:`Documentation/stable_kernel_rules.txt ` + :ref:`Documentation/process/stable-kernel-rules.rst ` This file describes the rules on how the stable kernel releases happen, and what to do if you want to get a change into one of these releases. - :ref:`Documentation/kernel-docs.txt ` + :ref:`Documentation/process/kernel-docs.rst ` A list of external documentation that pertains to kernel development. Please consult this list if you do not find what you are looking for within the in-kernel documentation. - :ref:`Documentation/applying-patches.txt ` + :ref:`Documentation/process/applying-patches.rst ` A good introduction describing exactly what a patch is and how to apply it to the different development branches of the kernel. @@ -307,7 +307,7 @@ two weeks, but it can be longer if there are no pressing problems. A security-related problem, instead, can cause a release to happen almost instantly. -The file Documentation/stable_kernel_rules.txt in the kernel tree +The file Documentation/process/stable-kernel-rules.rst in the kernel tree documents what kinds of changes are acceptable for the -stable tree, and how the release process works. @@ -366,7 +366,7 @@ tool. For details on how to use the kernel bugzilla, please see: https://bugzilla.kernel.org/page.cgi?id=faq.html -The file REPORTING-BUGS in the main kernel source directory has a good +The file admin-guide/reporting-bugs.rst in the main kernel source directory has a good template for how to report a possible kernel bug, and details what kind of information is needed by the kernel developers to help track down the problem. @@ -440,7 +440,7 @@ add your statements between the individual quoted sections instead of writing at the top of the mail. If you add patches to your mail, make sure they are plain readable text -as stated in Documentation/SubmittingPatches. +as stated in Documentation/process/submitting-patches.rst. Kernel developers don't want to deal with attachments or compressed patches; they may want to comment on individual lines of your patch, which works only that way. Make sure you diff --git a/Documentation/process/management-style.rst b/Documentation/process/management-style.rst index dea2e66c9a10..45595fd8a66b 100644 --- a/Documentation/process/management-style.rst +++ b/Documentation/process/management-style.rst @@ -5,7 +5,7 @@ Linux kernel management style This is a short document describing the preferred (or made up, depending on who you ask) management style for the linux kernel. It's meant to -mirror the CodingStyle document to some degree, and mainly written to +mirror the process/coding-style.rst document to some degree, and mainly written to avoid answering [#f1]_ the same (or similar) questions over and over again. Management style is very personal and much harder to quantify than diff --git a/Documentation/process/stable-kernel-rules.rst b/Documentation/process/stable-kernel-rules.rst index 4d82e31b7958..11ec2d93a5e0 100644 --- a/Documentation/process/stable-kernel-rules.rst +++ b/Documentation/process/stable-kernel-rules.rst @@ -27,7 +27,7 @@ Rules on what kind of patches are accepted, and which ones are not, into the - It cannot contain any "trivial" fixes in it (spelling changes, whitespace cleanups, etc). - It must follow the - :ref:`Documentation/SubmittingPatches ` + :ref:`Documentation/process/submitting-patches.rst ` rules. - It or an equivalent fix must already exist in Linus' tree (upstream). @@ -40,7 +40,7 @@ Procedure for submitting patches to the -stable tree Documentation/networking/netdev-FAQ.txt - Security patches should not be handled (solely) by the -stable review process but should follow the procedures in - :ref:`Documentation/SecurityBugs `. + :ref:`Documentation/admin-guide/security-bugs.rst `. For all other submissions, choose one of the following procedures ----------------------------------------------------------------- diff --git a/Documentation/process/submit-checklist.rst b/Documentation/process/submit-checklist.rst index 894289b22b15..a0d9d34bfb6d 100644 --- a/Documentation/process/submit-checklist.rst +++ b/Documentation/process/submit-checklist.rst @@ -7,7 +7,7 @@ Here are some basic things that developers should do if they want to see their kernel patch submissions accepted more quickly. These are all above and beyond the documentation that is provided in -:ref:`Documentation/SubmittingPatches ` +:ref:`Documentation/process/submitting-patches.rst ` and elsewhere regarding submitting Linux kernel patches. @@ -31,7 +31,7 @@ and elsewhere regarding submitting Linux kernel patches. tends to use ``unsigned long`` for 64-bit quantities. 5) Check your patch for general style as detailed in - :ref:`Documentation/CodingStyle `. + :ref:`Documentation/process/coding-style.rst `. Check for trivial violations with the patch style checker prior to submission (``scripts/checkpatch.pl``). You should be able to justify all violations that remain in @@ -78,7 +78,7 @@ and elsewhere regarding submitting Linux kernel patches. 16) All new ``/proc`` entries are documented under ``Documentation/`` 17) All new kernel boot parameters are documented in - ``Documentation/kernel-parameters.txt``. + ``Documentation/admin-guide/kernel-parameters.rst``. 18) All new module parameters are documented with ``MODULE_PARM_DESC()`` diff --git a/Documentation/process/submitting-drivers.rst b/Documentation/process/submitting-drivers.rst index 252b77a23fad..0939d018c289 100644 --- a/Documentation/process/submitting-drivers.rst +++ b/Documentation/process/submitting-drivers.rst @@ -8,7 +8,7 @@ various kernel trees. Note that if you are interested in video card drivers you should probably talk to XFree86 (http://www.xfree86.org/) and/or X.Org (http://x.org/) instead. -Also read the Documentation/SubmittingPatches document. +Also read the Documentation/process/submitting-patches.rst document. Allocating Device Numbers @@ -19,7 +19,7 @@ by the Linux assigned name and number authority (currently this is Torben Mathiasen). The site is http://www.lanana.org/. This also deals with allocating numbers for devices that are not going to be submitted to the mainstream kernel. -See Documentation/devices.txt for more information on this. +See Documentation/admin-guide/devices.rst for more information on this. If you don't use assigned numbers then when your device is submitted it will be given an assigned number even if that is different from values you may @@ -73,7 +73,7 @@ Interfaces: Code: Please use the Linux style of code formatting as documented - in :ref:`Documentation/CodingStyle `. + in :ref:`Documentation/process/coding-style.rst `. If you have sections of code that need to be in other formats, for example because they are shared with a windows driver kit and you want to @@ -109,7 +109,7 @@ PM support: anything. For the driver testing instructions see Documentation/power/drivers-testing.txt and for a relatively complete overview of the power management issues related to - drivers see Documentation/power/devices.txt . + drivers see Documentation/power/admin-guide/devices.rst . Control: In general if there is active maintenance of a driver by diff --git a/Documentation/process/submitting-patches.rst b/Documentation/process/submitting-patches.rst index 4cc20b2c6df3..b4cf8f375184 100644 --- a/Documentation/process/submitting-patches.rst +++ b/Documentation/process/submitting-patches.rst @@ -11,10 +11,10 @@ can greatly increase the chances of your change being accepted. This document contains a large number of suggestions in a relatively terse format. For detailed information on how the kernel development process works, see :ref:`Documentation/process `. -Also, read :ref:`Documentation/SubmitChecklist ` +Also, read :ref:`Documentation/process/submit-checklist.rst ` for a list of items to check before submitting code. If you are submitting a driver, also read -:ref:`Documentation/SubmittingDrivers `; +:ref:`Documentation/process/submitting-drivers.rst `; for device tree binding patches, read Documentation/devicetree/bindings/submitting-patches.txt. @@ -238,7 +238,7 @@ then only post say 15 or so at a time and wait for review and integration. Check your patch for basic style violations, details of which can be found in -:ref:`Documentation/CodingStyle `. +:ref:`Documentation/process/coding-style.rst `. Failure to do so simply wastes the reviewers time and will get your patch rejected, probably without even being read. @@ -305,7 +305,7 @@ toward the stable maintainers by putting a line like this:: into the sign-off area of your patch (note, NOT an email recipient). You should also read -:ref:`Documentation/stable_kernel_rules.txt ` +:ref:`Documentation/process/stable-kernel-rules.rst ` in addition to this file. Note, however, that some subsystem maintainers want to come to their own @@ -363,7 +363,7 @@ decreasing the likelihood of your MIME-attached change being accepted. Exception: If your mailer is mangling patches then someone may ask you to re-send them using MIME. -See :ref:`Documentation/email-clients.txt ` +See :ref:`Documentation/process/email-clients.rst ` for hints about configuring your e-mail client so that it sends your patches untouched. @@ -828,8 +828,8 @@ Greg Kroah-Hartman, "How to piss off a kernel subsystem maintainer". NO!!!! No more huge patch bombs to linux-kernel@vger.kernel.org people! -Kernel Documentation/CodingStyle: - :ref:`Documentation/CodingStyle ` +Kernel Documentation/process/coding-style.rst: + :ref:`Documentation/process/coding-style.rst ` Linus Torvalds's mail on the canonical patch format: diff --git a/Documentation/rfkill.txt b/Documentation/rfkill.txt index 1f0c27049340..8c174063b3f0 100644 --- a/Documentation/rfkill.txt +++ b/Documentation/rfkill.txt @@ -26,7 +26,7 @@ whether they can be changed or not: the system software. The rfkill subsystem has two parameters, rfkill.default_state and -rfkill.master_switch_mode, which are documented in kernel-parameters.txt. +rfkill.master_switch_mode, which are documented in admin-guide/kernel-parameters.rst. 2. Implementation details diff --git a/Documentation/scsi/scsi-parameters.txt b/Documentation/scsi/scsi-parameters.txt index 8e66dafa41e1..8477655c0e46 100644 --- a/Documentation/scsi/scsi-parameters.txt +++ b/Documentation/scsi/scsi-parameters.txt @@ -1,7 +1,7 @@ SCSI Kernel Parameters ~~~~~~~~~~~~~~~~~~~~~~ -See Documentation/kernel-parameters.txt for general information on +See Documentation/admin-guide/kernel-parameters.rst for general information on specifying module parameters. This document may not be entirely up to date and comprehensive. The command diff --git a/Documentation/scsi/scsi_mid_low_api.txt b/Documentation/scsi/scsi_mid_low_api.txt index 255075157511..6338400eed73 100644 --- a/Documentation/scsi/scsi_mid_low_api.txt +++ b/Documentation/scsi/scsi_mid_low_api.txt @@ -336,7 +336,7 @@ in parallel by these functions. Conventions =========== First, Linus Torvalds's thoughts on C coding style can be found in the -Documentation/CodingStyle file. +Documentation/process/coding-style.rst file. Next, there is a movement to "outlaw" typedefs introducing synonyms for struct tags. Both can be still found in the SCSI subsystem, but diff --git a/Documentation/scsi/sym53c8xx_2.txt b/Documentation/scsi/sym53c8xx_2.txt index 6af8f7a7770f..d28186553fb0 100644 --- a/Documentation/scsi/sym53c8xx_2.txt +++ b/Documentation/scsi/sym53c8xx_2.txt @@ -427,7 +427,7 @@ Synchronous transfers frequency (default answer: 80) 10.1 Syntax Setup commands can be passed to the driver either at boot time or as -parameters to modprobe, as described in Documentation/kernel-parameters.txt +parameters to modprobe, as described in Documentation/admin-guide/kernel-parameters.rst Example of boot setup command under lilo prompt: diff --git a/Documentation/sound/alsa/alsa-parameters.txt b/Documentation/sound/alsa/alsa-parameters.txt index 0fa40679b080..72eced86f035 100644 --- a/Documentation/sound/alsa/alsa-parameters.txt +++ b/Documentation/sound/alsa/alsa-parameters.txt @@ -1,7 +1,7 @@ ALSA Kernel Parameters ~~~~~~~~~~~~~~~~~~~~~~ -See Documentation/kernel-parameters.txt for general information on +See Documentation/admin-guide/kernel-parameters.rst for general information on specifying module parameters. This document may not be entirely up to date and comprehensive. The command diff --git a/Documentation/sound/oss/oss-parameters.txt b/Documentation/sound/oss/oss-parameters.txt index 3ab391e7c295..cc675f25eee4 100644 --- a/Documentation/sound/oss/oss-parameters.txt +++ b/Documentation/sound/oss/oss-parameters.txt @@ -1,7 +1,7 @@ OSS Kernel Parameters ~~~~~~~~~~~~~~~~~~~~~ -See Documentation/kernel-parameters.txt for general information on +See Documentation/admin-guide/kernel-parameters.rst for general information on specifying module parameters. This document may not be entirely up to date and comprehensive. The command diff --git a/Documentation/sysctl/kernel.txt b/Documentation/sysctl/kernel.txt index ffab8b5caa60..6bb78f872929 100644 --- a/Documentation/sysctl/kernel.txt +++ b/Documentation/sysctl/kernel.txt @@ -71,7 +71,7 @@ show up in /proc/sys/kernel: - printk_ratelimit_burst - pty ==> Documentation/filesystems/devpts.txt - randomize_va_space -- real-root-dev ==> Documentation/initrd.txt +- real-root-dev ==> Documentation/admin-guide/initrd.rst - reboot-cmd [ SPARC only ] - rtsig-max - rtsig-nr @@ -453,7 +453,7 @@ in a KVM virtual machine. This default can be overridden by adding nmi_watchdog=1 -to the guest kernel command line (see Documentation/kernel-parameters.txt). +to the guest kernel command line (see Documentation/admin-guide/kernel-parameters.rst). ============================================================== diff --git a/Documentation/virtual/kvm/review-checklist.txt b/Documentation/virtual/kvm/review-checklist.txt index a850986ed684..a83b27635fdd 100644 --- a/Documentation/virtual/kvm/review-checklist.txt +++ b/Documentation/virtual/kvm/review-checklist.txt @@ -1,8 +1,8 @@ Review checklist for kvm patches ================================ -1. The patch must follow Documentation/CodingStyle and - Documentation/SubmittingPatches. +1. The patch must follow Documentation/process/coding-style.rst and + Documentation/process/submitting-patches.rst. 2. Patches should be against kvm.git master branch. diff --git a/Documentation/vm/numa b/Documentation/vm/numa index e0b58c0e6b49..a08f71647714 100644 --- a/Documentation/vm/numa +++ b/Documentation/vm/numa @@ -82,7 +82,7 @@ such as DMA or DMA32, represent relatively scarce resources. Linux chooses a default zonelist order based on the sizes of the various zone types relative to the total memory of the node and the total memory of the system. The default zonelist order may be overridden using the numa_zonelist_order kernel -boot parameter or sysctl. [see Documentation/kernel-parameters.txt and +boot parameter or sysctl. [see Documentation/admin-guide/kernel-parameters.rst and Documentation/sysctl/vm.txt] By default, Linux will attempt to satisfy memory allocation requests from the diff --git a/Documentation/watchdog/convert_drivers_to_kernel_api.txt b/Documentation/watchdog/convert_drivers_to_kernel_api.txt index 271b8850dde7..9fffb2958d13 100644 --- a/Documentation/watchdog/convert_drivers_to_kernel_api.txt +++ b/Documentation/watchdog/convert_drivers_to_kernel_api.txt @@ -213,6 +213,6 @@ The entry for the driver now needs to select WATCHDOG_CORE: Create a patch and send it to upstream -------------------------------------- -Make sure you understood Documentation/SubmittingPatches and send your patch to +Make sure you understood Documentation/process/submitting-patches.rst and send your patch to linux-watchdog@vger.kernel.org. We are looking forward to it :) diff --git a/Documentation/watchdog/watchdog-parameters.txt b/Documentation/watchdog/watchdog-parameters.txt index a8d364227a77..e21850e270a0 100644 --- a/Documentation/watchdog/watchdog-parameters.txt +++ b/Documentation/watchdog/watchdog-parameters.txt @@ -4,7 +4,7 @@ be listed here unless the driver has its own driver-specific information file. -See Documentation/kernel-parameters.txt for information on +See Documentation/admin-guide/kernel-parameters.rst for information on providing kernel parameters for builtin drivers versus loadable modules. diff --git a/Documentation/x86/boot.txt b/Documentation/x86/boot.txt index 9da6f3512249..5e9b826b5f62 100644 --- a/Documentation/x86/boot.txt +++ b/Documentation/x86/boot.txt @@ -921,7 +921,7 @@ They should normally not be deleted from the kernel command line even though not all of them are actually meaningful to the kernel. Boot loader authors who need additional command line options for the boot loader itself should get them registered in -Documentation/kernel-parameters.txt to make sure they will not +Documentation/admin-guide/kernel-parameters.rst to make sure they will not conflict with actual kernel options now or in the future. vga= diff --git a/Documentation/zh_CN/CodingStyle b/Documentation/zh_CN/CodingStyle index 12717791baac..b02738042799 100644 --- a/Documentation/zh_CN/CodingStyle +++ b/Documentation/zh_CN/CodingStyle @@ -1,4 +1,4 @@ -Chinese translated version of Documentation/CodingStyle +Chinese translated version of Documentation/process/coding-style.rst If you have any comment or update to the content, please post to LKML directly. However, if you have problem communicating in English you can also ask the @@ -7,7 +7,7 @@ translation is outdated or there is problem with translation. Chinese maintainer: Zhang Le --------------------------------------------------------------------- -Documentation/CodingStyle的中文翻译 +Documentation/process/coding-style.rst的中文翻译 如果想评论或更新本文的内容，请直接发信到LKML。如果你使用英文交流有困难的话，也可 以向中文版维护者求助。如果本翻译更新不及时或者翻译存在问题，请联系中文版维护者。 @@ -809,5 +809,5 @@ GNU 手册 - 遵循 K&R 标准和此文本 - cpp, gcc, gcc internals and indent, WG14是C语言的国际标准化工作组，URL: http://www.open-std.org/JTC1/SC22/WG14/ -Kernel CodingStyle，作者 greg@kroah.com 发表于OLS 2002： +Kernel process/coding-style.rst，作者 greg@kroah.com 发表于OLS 2002： http://www.kroah.com/linux/talks/ols_2002_kernel_codingstyle_talk/html/ diff --git a/Documentation/zh_CN/HOWTO b/Documentation/zh_CN/HOWTO index f0613b92e0be..11be075ba5fa 100644 --- a/Documentation/zh_CN/HOWTO +++ b/Documentation/zh_CN/HOWTO @@ -1,4 +1,4 @@ -Chinese translated version of Documentation/HOWTO +Chinese translated version of Documentation/process/howto.rst If you have any comment or update to the content, please contact the original document maintainer directly. However, if you have a problem @@ -9,7 +9,7 @@ or if there is a problem with the translation. Maintainer: Greg Kroah-Hartman Chinese maintainer: Li Yang --------------------------------------------------------------------- -Documentation/HOWTO 的中文翻译 +Documentation/process/howto.rst 的中文翻译 如果想评论或更新本文的内容，请直接联系原文档的维护者。如果你使用英文 交流有困难的话，也可以向中文版维护者求助。如果本翻译更新不及时或者翻 @@ -93,16 +93,16 @@ Linux内核代码中包含有大量的文档。这些文档对于学习如何与 文件简要介绍了Linux内核的背景，并且描述了如何配置和编译内核。内核的 新用户应该从这里开始。 - Documentation/Changes + Documentation/process/changes.rst 文件给出了用来编译和使用内核所需要的最小软件包列表。 - Documentation/CodingStyle + Documentation/process/coding-style.rst 描述Linux内核的代码风格和理由。所有新代码需要遵守这篇文档中定义的规 范。大多数维护者只会接收符合规定的补丁，很多人也只会帮忙检查符合风格 的代码。 - Documentation/SubmittingPatches - Documentation/SubmittingDrivers + Documentation/process/submitting-patches.rst + Documentation/process/submitting-drivers.rst 这两份文档明确描述如何创建和发送补丁，其中包括（但不仅限于)： - 邮件内容 - 邮件格式 @@ -116,7 +116,7 @@ Linux内核代码中包含有大量的文档。这些文档对于学习如何与 "Linux kernel patch submission format" http://linux.yyz.us/patch-format.html - Documentation/stable_api_nonsense.txt + Documentation/process/stable-api-nonsense.rst 论证内核为什么特意不包括稳定的内核内部API，也就是说不包括像这样的特 性： - 子系统中间层（为了兼容性？） @@ -125,23 +125,23 @@ Linux内核代码中包含有大量的文档。这些文档对于学习如何与 这篇文档对于理解Linux的开发哲学至关重要。对于将开发平台从其他操作系 统转移到Linux的人来说也很重要。 - Documentation/SecurityBugs + Documentation/admin-guide/security-bugs.rst 如果你认为自己发现了Linux内核的安全性问题，请根据这篇文档中的步骤来 提醒其他内核开发者并帮助解决这个问题。 - Documentation/ManagementStyle + Documentation/process/management-style.rst 描述内核维护者的工作方法及其共有特点。这对于刚刚接触内核开发（或者对 它感到好奇）的人来说很重要，因为它解释了很多对于内核维护者独特行为的 普遍误解与迷惑。 - Documentation/stable_kernel_rules.txt + Documentation/process/stable-kernel-rules.rst 解释了稳定版内核发布的规则，以及如何将改动放入这些版本的步骤。 - Documentation/kernel-docs.txt + Documentation/process/kernel-docs.rst 有助于内核开发的外部文档列表。如果你在内核自带的文档中没有找到你想找 的内容，可以查看这些文档。 - Documentation/applying-patches.txt + Documentation/process/applying-patches.rst 关于补丁是什么以及如何将它打在不同内核开发分支上的好介绍 内核还拥有大量从代码自动生成的文档。它包含内核内部API的全面介绍以及如何 @@ -238,7 +238,7 @@ kernel.org网站的pub/linux/kernel/v2.6/目录下找到它。它的开发遵循 2.6.x.y版本由“稳定版”小组（邮件地址）维护，一般隔周发 布新版本。 -内核源码中的Documentation/stable_kernel_rules.txt文件具体描述了可被稳定 +内核源码中的Documentation/process/stable-kernel-rules.rst文件具体描述了可被稳定 版内核接受的修改类型以及发布的流程。 @@ -329,7 +329,7 @@ bugzilla.kernel.org是Linux内核开发者们用来跟踪内核Bug的网站。 户在这个工具中报告找到的所有bug。如何使用内核bugzilla的细节请访问： http://test.kernel.org/bugzilla/faq.html -内核源码主目录中的REPORTING-BUGS文件里有一个很好的模板。它指导用户如何报 +内核源码主目录中的admin-guide/reporting-bugs.rst文件里有一个很好的模板。它指导用户如何报 告可能的内核bug以及需要提供哪些信息来帮助内核开发者们找到问题的根源。 @@ -380,7 +380,7 @@ MAINTAINERS文件中可以找到不同话题对应的邮件列表。 这几行。将你的评论加在被引用的段落之间而不要放在邮件的顶部。 如果你在邮件中附带补丁，请确认它们是可以直接阅读的纯文本（如 -Documentation/SubmittingPatches文档中所述）。内核开发者们不希望遇到附件 +Documentation/process/submitting-patches.rst文档中所述）。内核开发者们不希望遇到附件 或者被压缩了的补丁。只有这样才能保证他们可以直接评论你的每行代码。请确保 你使用的邮件发送程序不会修改空格和制表符。一个防范性的测试方法是先将邮件 发送给自己，然后自己尝试是否可以顺利地打上收到的补丁。如果测试不成功，请 diff --git a/Documentation/zh_CN/SecurityBugs b/Documentation/zh_CN/SecurityBugs index d21eb07fe943..2d0fffd122ce 100644 --- a/Documentation/zh_CN/SecurityBugs +++ b/Documentation/zh_CN/SecurityBugs @@ -1,4 +1,4 @@ -Chinese translated version of Documentation/SecurityBugs +Chinese translated version of Documentation/admin-guide/security-bugs.rst If you have any comment or update to the content, please contact the original document maintainer directly. However, if you have a problem @@ -8,7 +8,7 @@ or if there is a problem with the translation. Chinese maintainer: Harry Wei --------------------------------------------------------------------- -Documentation/SecurityBugs 的中文翻译 +Documentation/admin-guide/security-bugs.rst 的中文翻译 如果想评论或更新本文的内容，请直接联系原文档的维护者。如果你使用英文 交流有困难的话，也可以向中文版维护者求助。如果本翻译更新不及时或者翻 @@ -31,7 +31,7 @@ linux内核安全团队可以通过email来联系。这是 一组独立的安全工作人员，可以帮助改善漏洞报告并且公布和取消一个修复。安 全团队有可能会从部分的维护者那里引进额外的帮助来了解并且修复安全漏洞。 当遇到任何漏洞，所能提供的信息越多就越能诊断和修复。如果你不清楚什么 -是有帮助的信息，那就请重温一下REPORTING-BUGS文件中的概述过程。任 +是有帮助的信息，那就请重温一下admin-guide/reporting-bugs.rst文件中的概述过程。任 何攻击性的代码都是非常有用的，未经报告者的同意不会被取消，除非它已经 被公布于众。 diff --git a/Documentation/zh_CN/SubmittingDrivers b/Documentation/zh_CN/SubmittingDrivers index d313f5d8448d..929385e4b194 100644 --- a/Documentation/zh_CN/SubmittingDrivers +++ b/Documentation/zh_CN/SubmittingDrivers @@ -1,4 +1,4 @@ -Chinese translated version of Documentation/SubmittingDrivers +Chinese translated version of Documentation/process/submitting-drivers.rst If you have any comment or update to the content, please contact the original document maintainer directly. However, if you have a problem @@ -8,7 +8,7 @@ or if there is a problem with the translation. Chinese maintainer: Li Yang --------------------------------------------------------------------- -Documentation/SubmittingDrivers 的中文翻译 +Documentation/process/submitting-drivers.rst 的中文翻译 如果想评论或更新本文的内容，请直接联系原文档的维护者。如果你使用英文 交流有困难的话，也可以向中文版维护者求助。如果本翻译更新不及时或者翻 @@ -30,7 +30,7 @@ Documentation/SubmittingDrivers 的中文翻译 兴趣的是显卡驱动程序，你也许应该访问 XFree86 项目(http://www.xfree86.org/) 和／或 X.org 项目 (http://x.org)。 -另请参阅 Documentation/SubmittingPatches 文档。 +另请参阅 Documentation/process/submitting-patches.rst 文档。 分配设备号 @@ -39,7 +39,7 @@ Documentation/SubmittingDrivers 的中文翻译 块设备和字符设备的主设备号与从设备号是由 Linux 命名编号分配权威 LANANA（ 现在是 Torben Mathiasen）负责分配。申请的网址是 http://www.lanana.org/。 即使不准备提交到主流内核的设备驱动也需要在这里分配设备号。有关详细信息， -请参阅 Documentation/devices.txt。 +请参阅 Documentation/admin-guide/devices.rst。 如果你使用的不是已经分配的设备号，那么当你提交设备驱动的时候，它将会被强 制分配一个新的设备号，即便这个设备号和你之前发给客户的截然不同。 @@ -81,7 +81,7 @@ Linux 2.6: 如果你需要一个 Linux 和 NT 的通用驱动接口，那么请在用 户空间实现它。 -代码： 请使用 Documentation/CodingStyle 中所描述的 Linux 代码风 +代码： 请使用 Documentation/process/coding-style.rst 中所描述的 Linux 代码风 格。如果你的某些代码段（例如那些与 Windows 驱动程序包共 享的代码段）需要使用其他格式，而你却只希望维护一份代码， 那么请将它们很好地区分出来，并且注明原因。 @@ -107,7 +107,7 @@ Linux 2.6: 程序测试的指导，请参阅 Documentation/power/drivers-testing.txt。有关驱动程序电 源管理问题相对全面的概述，请参阅 - Documentation/power/devices.txt。 + Documentation/power/admin-guide/devices.rst。 管理： 如果一个驱动程序的作者还在进行有效的维护，那么通常除了那 些明显正确且不需要任何检查的补丁以外，其他所有的补丁都会 diff --git a/Documentation/zh_CN/SubmittingPatches b/Documentation/zh_CN/SubmittingPatches index 1d3a10f8746b..e9098da8f1a4 100644 --- a/Documentation/zh_CN/SubmittingPatches +++ b/Documentation/zh_CN/SubmittingPatches @@ -1,4 +1,4 @@ -Chinese translated version of Documentation/SubmittingPatches +Chinese translated version of Documentation/process/submitting-patches.rst If you have any comment or update to the content, please contact the original document maintainer directly. However, if you have a problem @@ -8,7 +8,7 @@ or if there is a problem with the translation. Chinese maintainer: TripleX Chung --------------------------------------------------------------------- -Documentation/SubmittingPatches 的中文翻译 +Documentation/process/submitting-patches.rst 的中文翻译 如果想评论或更新本文的内容，请直接联系原文档的维护者。如果你使用英文 交流有困难的话，也可以向中文版维护者求助。如果本翻译更新不及时或者翻 @@ -30,9 +30,9 @@ Documentation/SubmittingPatches 的中文翻译 对于想要将改动提交到 Linux 内核的个人或者公司来说，如果不熟悉“规矩”， 提交的流程会让人畏惧。本文档收集了一系列建议，这些建议可以大大的提高你 的改动被接受的机会。 -阅读 Documentation/SubmitChecklist 来获得在提交代码前需要检查的项目的列 +阅读 Documentation/process/submit-checklist.rst 来获得在提交代码前需要检查的项目的列 表。如果你在提交一个驱动程序，那么同时阅读一下 -Documentation/SubmittingDrivers 。 +Documentation/process/submitting-drivers.rst 。 -------------------------- @@ -338,7 +338,7 @@ e-mail 标题中的“一句话概述”扼要的描述 e-mail 中的补丁。 本节包含很多和提交到内核的代码有关的通常的"规则"。事情永远有例外...但是 你必须真的有好的理由这样做。你可以把本节叫做Linus的计算机科学入门课。 -1) 读 Document/CodingStyle +1) 读 Document/process/coding-style.rst Nuff 说过，如果你的代码和这个偏离太多，那么它有可能会被拒绝，没有更多的 审查，没有更多的评价。 @@ -404,8 +404,8 @@ Greg Kroah-Hartman, "How to piss off a kernel subsystem maintainer". NO!!!! No more huge patch bombs to linux-kernel@vger.kernel.org people! -Kernel Documentation/CodingStyle: - +Kernel Documentation/process/coding-style.rst: + Linus Torvalds's mail on the canonical patch format: diff --git a/Documentation/zh_CN/arm/Booting b/Documentation/zh_CN/arm/Booting index 6158a64df80c..1fe866f8218f 100644 --- a/Documentation/zh_CN/arm/Booting +++ b/Documentation/zh_CN/arm/Booting @@ -68,7 +68,7 @@ RAM，或可能使用对这个设备已知的 RAM 信息，还可能使用任何 作为替代方案，引导加载程序也可以通过标签列表传递相关的'console=' 选项给内核以指定某个串口，而串口数据格式的选项在以下文档中描述： - Documentation/kernel-parameters.txt。 + Documentation/admin-guide/kernel-parameters.rst。 3、检测机器类型 diff --git a/Documentation/zh_CN/email-clients.txt b/Documentation/zh_CN/email-clients.txt index b9a1a3e6c78d..ec31d97e8d0e 100644 --- a/Documentation/zh_CN/email-clients.txt +++ b/Documentation/zh_CN/email-clients.txt @@ -1,4 +1,4 @@ -Chinese translated version of Documentation/email-clients.txt +Chinese translated version of Documentation/process/email-clients.rst If you have any comment or update to the content, please contact the original document maintainer directly. However, if you have a problem @@ -8,7 +8,7 @@ or if there is a problem with the translation. Chinese maintainer: Harry Wei --------------------------------------------------------------------- -Documentation/email-clients.txt 的中文翻译 +Documentation/process/email-clients.rst 的中文翻译 如果想评论或更新本文的内容，请直接联系原文档的维护者。如果你使用英文 交流有困难的话，也可以向中文版维护者求助。如果本翻译更新不及时或者翻 diff --git a/Documentation/zh_CN/oops-tracing.txt b/Documentation/zh_CN/oops-tracing.txt index 9312608ffb8d..41ab53cc0e83 100644 --- a/Documentation/zh_CN/oops-tracing.txt +++ b/Documentation/zh_CN/oops-tracing.txt @@ -1,4 +1,4 @@ -Chinese translated version of Documentation/oops-tracing.txt +Chinese translated version of Documentation/admin-guide/oops-tracing.rst If you have any comment or update to the content, please contact the original document maintainer directly. However, if you have a problem @@ -8,7 +8,7 @@ or if there is a problem with the translation. Chinese maintainer: Dave Young --------------------------------------------------------------------- -Documentation/oops-tracing.txt 的中文翻译 +Documentation/admin-guide/oops-tracing.rst 的中文翻译 如果想评论或更新本文的内容，请直接联系原文档的维护者。如果你使用英文 交流有困难的话，也可以向中文版维护者求助。如果本翻译更新不及时或者翻 @@ -50,7 +50,7 @@ cat /proc/kmsg > file， 然而你必须介入中止传输， kmsg是一个“ 息滚动到了终端的上面，你会发现以高分辩率启动（比如，vga=791）会让你读到更多的文 本。（注意：这需要vesafb，所以对‘早期’的oops没有帮助） -（2）用串口终端启动（请参看Documentation/serial-console.txt），运行一个null +（2）用串口终端启动（请参看Documentation/admin-guide/serial-console.rst），运行一个null modem到另一台机器并用你喜欢的通讯工具获取输出。Minicom工作地很好。 （3）使用Kdump（请参看Documentation/kdump/kdump.txt）， diff --git a/Documentation/zh_CN/stable_api_nonsense.txt b/Documentation/zh_CN/stable_api_nonsense.txt index c26a27d1ee7d..a2b27fab382c 100644 --- a/Documentation/zh_CN/stable_api_nonsense.txt +++ b/Documentation/zh_CN/stable_api_nonsense.txt @@ -1,4 +1,4 @@ -Chinese translated version of Documentation/stable_api_nonsense.txt +Chinese translated version of Documentation/process/stable-api-nonsense.rst If you have any comment or update to the content, please contact the original document maintainer directly. However, if you have problem @@ -9,7 +9,7 @@ is problem with translation. Maintainer: Greg Kroah-Hartman Chinese maintainer: TripleX Chung --------------------------------------------------------------------- -Documentation/stable_api_nonsense.txt 的中文翻译 +Documentation/process/stable-api-nonsense.rst 的中文翻译 如果想评论或更新本文的内容，请直接联系原文档的维护者。如果你使用英文 交流有困难的话，也可以向中文版维护者求助。如果本翻译更新不及时或者翻 diff --git a/Documentation/zh_CN/stable_kernel_rules.txt b/Documentation/zh_CN/stable_kernel_rules.txt index 26ea5ed7cd9c..db4ba5a0c39a 100644 --- a/Documentation/zh_CN/stable_kernel_rules.txt +++ b/Documentation/zh_CN/stable_kernel_rules.txt @@ -1,4 +1,4 @@ -Chinese translated version of Documentation/stable_kernel_rules.txt +Chinese translated version of Documentation/process/stable-kernel-rules.rst If you have any comment or update to the content, please contact the original document maintainer directly. However, if you have a problem @@ -8,7 +8,7 @@ or if there is a problem with the translation. Chinese maintainer: TripleX Chung --------------------------------------------------------------------- -Documentation/stable_kernel_rules.txt 的中文翻译 +Documentation/process/stable-kernel-rules.rst 的中文翻译 如果想评论或更新本文的内容，请直接联系原文档的维护者。如果你使用英文 交流有困难的话，也可以向中文版维护者求助。如果本翻译更新不及时或者翻 @@ -38,7 +38,7 @@ Documentation/stable_kernel_rules.txt 的中文翻译 - 没有“理论上的竞争条件”，除非能给出竞争条件如何被利用的解释。 - 不能存在任何的“琐碎的”修正（拼写修正，去掉多余空格之类的）。 - 必须被相关子系统的维护者接受。 - - 必须遵循Documentation/SubmittingPatches里的规则。 + - 必须遵循Documentation/process/submitting-patches.rst里的规则。 向稳定版代码树提交补丁的过程： diff --git a/Documentation/zh_CN/volatile-considered-harmful.txt b/Documentation/zh_CN/volatile-considered-harmful.txt index ba8149d2233a..475125967197 100644 --- a/Documentation/zh_CN/volatile-considered-harmful.txt +++ b/Documentation/zh_CN/volatile-considered-harmful.txt @@ -1,4 +1,4 @@ -Chinese translated version of Documentation/volatile-considered-harmful.txt +Chinese translated version of Documentation/process/volatile-considered-harmful.rst If you have any comment or update to the content, please contact the original document maintainer directly. However, if you have a problem @@ -9,7 +9,7 @@ or if there is a problem with the translation. Maintainer: Jonathan Corbet Chinese maintainer: Bryan Wu --------------------------------------------------------------------- -Documentation/volatile-considered-harmful.txt 的中文翻译 +Documentation/process/volatile-considered-harmful.rst 的中文翻译 如果想评论或更新本文的内容，请直接联系原文档的维护者。如果你使用英文 交流有困难的话，也可以向中文版维护者求助。如果本翻译更新不及时或者翻 diff --git a/MAINTAINERS b/MAINTAINERS index de0451df542f..69820b75b2e0 100644 --- a/MAINTAINERS +++ b/MAINTAINERS @@ -35,13 +35,13 @@ trivial patch so apply some common sense. PLEASE check your patch with the automated style checker (scripts/checkpatch.pl) to catch trivial style violations. - See Documentation/CodingStyle for guidance here. + See Documentation/process/coding-style.rst for guidance here. PLEASE CC: the maintainers and mailing lists that are generated by scripts/get_maintainer.pl. The results returned by the script will be best if you have git installed and are making your changes in a branch derived from Linus' latest git tree. - See Documentation/SubmittingPatches for details. + See Documentation/process/submitting-patches.rst for details. PLEASE try to include any credit lines you want added with the patch. It avoids people being missed off by mistake and makes @@ -54,7 +54,7 @@ trivial patch so apply some common sense. of the Linux Foundation certificate of contribution and should include a Signed-off-by: line. The current version of this "Developer's Certificate of Origin" (DCO) is listed in the file - Documentation/SubmittingPatches. + Documentation/process/submitting-patches.rst. 6. Make sure you have the right to send any changes you make. If you do changes at work you may find your employer owns the patch @@ -2924,7 +2924,7 @@ CAPELLA MICROSYSTEMS LIGHT SENSOR DRIVER M: Kevin Tsai S: Maintained F: drivers/iio/light/cm* -F: Documentation/devicetree/bindings/i2c/trivial-devices.txt +F: Documentation/devicetree/bindings/i2c/trivial-admin-guide/devices.rst CAVIUM I2C DRIVER M: Jan Glauber @@ -11438,7 +11438,7 @@ STABLE BRANCH M: Greg Kroah-Hartman L: stable@vger.kernel.org S: Supported -F: Documentation/stable_kernel_rules.txt +F: Documentation/process/stable-kernel-rules.rst STAGING SUBSYSTEM M: Greg Kroah-Hartman diff --git a/arch/x86/Kconfig b/arch/x86/Kconfig index bada636d1065..19d237b0737d 100644 --- a/arch/x86/Kconfig +++ b/arch/x86/Kconfig @@ -1525,7 +1525,7 @@ config X86_CHECK_BIOS_CORRUPTION line. By default it scans the low 64k of memory every 60 seconds; see the memory_corruption_check_size and memory_corruption_check_period parameters in - Documentation/kernel-parameters.txt to adjust this. + Documentation/admin-guide/kernel-parameters.rst to adjust this. When enabled with the default parameters, this option has almost no overhead, as it reserves a relatively small amount diff --git a/drivers/acpi/Kconfig b/drivers/acpi/Kconfig index 535e7828445a..c5f9cbe0ae21 100644 --- a/drivers/acpi/Kconfig +++ b/drivers/acpi/Kconfig @@ -342,7 +342,7 @@ config ACPI_DEBUG Use the acpi.debug_layer and acpi.debug_level kernel command-line parameters documented in Documentation/acpi/debug.txt and - Documentation/kernel-parameters.txt to control the type and + Documentation/admin-guide/kernel-parameters.rst to control the type and amount of debug output. config ACPI_PCI_SLOT diff --git a/drivers/ata/libata-core.c b/drivers/ata/libata-core.c index 223a770f78f3..59ce0dd50701 100644 --- a/drivers/ata/libata-core.c +++ b/drivers/ata/libata-core.c @@ -129,7 +129,7 @@ static int ata_force_tbl_size; static char ata_force_param_buf[PAGE_SIZE] __initdata; /* param_buf is thrown away after initialization, disallow read */ module_param_string(force, ata_force_param_buf, sizeof(ata_force_param_buf), 0); -MODULE_PARM_DESC(force, "Force ATA configurations including cable type, link speed and transfer mode (see Documentation/kernel-parameters.txt for details)"); +MODULE_PARM_DESC(force, "Force ATA configurations including cable type, link speed and transfer mode (see Documentation/admin-guide/kernel-parameters.rst for details)"); static int atapi_enabled = 1; module_param(atapi_enabled, int, 0444); diff --git a/drivers/char/pcmcia/cm4000_cs.c b/drivers/char/pcmcia/cm4000_cs.c index c115217c79ae..e051fc8aa7d7 100644 --- a/drivers/char/pcmcia/cm4000_cs.c +++ b/drivers/char/pcmcia/cm4000_cs.c @@ -14,7 +14,7 @@ * (C) 2000,2001,2002,2003,2004 Omnikey AG * * (C) 2005-2006 Harald Welte - * - Adhere to Kernel CodingStyle + * - Adhere to Kernel process/coding-style.rst * - Port to 2.6.13 "new" style PCMCIA * - Check for copy_{from,to}_user return values * - Use nonseekable_open() @@ -151,7 +151,7 @@ static struct pcmcia_device *dev_table[CM4000_MAX_DEV]; static struct class *cmm_class; /* This table doesn't use spaces after the comma between fields and thus - * violates CodingStyle. However, I don't really think wrapping it around will + * violates process/coding-style.rst. However, I don't really think wrapping it around will * make it any clearer to read -HW */ static unsigned char fi_di_table[10][14] = { /*FI 00 01 02 03 04 05 06 07 08 09 10 11 12 13 */ diff --git a/drivers/net/can/grcan.c b/drivers/net/can/grcan.c index db9538d4b358..a7be12d9a139 100644 --- a/drivers/net/can/grcan.c +++ b/drivers/net/can/grcan.c @@ -15,7 +15,7 @@ * See "Documentation/ABI/testing/sysfs-class-net-grcan" for information on the * sysfs interface. * - * See "Documentation/kernel-parameters.txt" for information on the module + * See "Documentation/admin-guide/kernel-parameters.rst" for information on the module * parameters. * * This program is free software; you can redistribute it and/or modify it diff --git a/drivers/nvdimm/Kconfig b/drivers/nvdimm/Kconfig index 8b2b740d6679..b20ce7da1ee4 100644 --- a/drivers/nvdimm/Kconfig +++ b/drivers/nvdimm/Kconfig @@ -28,7 +28,7 @@ config BLK_DEV_PMEM non-standard OEM-specific E820 memory type (type-12, see CONFIG_X86_PMEM_LEGACY), or it is manually specified by the 'memmap=nn[KMG]!ss[KMG]' kernel command line (see - Documentation/kernel-parameters.txt). This driver converts + Documentation/admin-guide/kernel-parameters.rst). This driver converts these persistent memory ranges into block devices that are capable of DAX (direct-access) file system mappings. See Documentation/nvdimm/nvdimm.txt for more details. diff --git a/drivers/staging/vme/devices/vme_user.c b/drivers/staging/vme/devices/vme_user.c index 5dd430f8f921..d84dffb894f4 100644 --- a/drivers/staging/vme/devices/vme_user.c +++ b/drivers/staging/vme/devices/vme_user.c @@ -47,7 +47,7 @@ static const char driver_name[] = "vme_user"; static int bus[VME_USER_BUS_MAX]; static unsigned int bus_num; -/* Currently Documentation/devices.txt defines the following for VME: +/* Currently Documentation/admin-guide/devices.rst defines the following for VME: * * 221 char VME bus * 0 = /dev/bus/vme/m0 First master image diff --git a/drivers/video/fbdev/skeletonfb.c b/drivers/video/fbdev/skeletonfb.c index f948baa16d82..e219a0a22077 100644 --- a/drivers/video/fbdev/skeletonfb.c +++ b/drivers/video/fbdev/skeletonfb.c @@ -836,7 +836,7 @@ static void xxxfb_remove(struct pci_dev *dev) * @dev: PCI device * @msg: the suspend event code. * - * See Documentation/power/devices.txt for more information + * See Documentation/power/admin-guide/devices.rst for more information */ static int xxxfb_suspend(struct pci_dev *dev, pm_message_t msg) { @@ -851,7 +851,7 @@ static int xxxfb_suspend(struct pci_dev *dev, pm_message_t msg) * xxxfb_resume - Optional but recommended function. Resume the device. * @dev: PCI device * - * See Documentation/power/devices.txt for more information + * See Documentation/power/admin-guide/devices.rst for more information */ static int xxxfb_resume(struct pci_dev *dev) { @@ -915,7 +915,7 @@ static void __exit xxxfb_exit(void) * @dev: platform device * @msg: the suspend event code. * - * See Documentation/power/devices.txt for more information + * See Documentation/power/admin-guide/devices.rst for more information */ static int xxxfb_suspend(struct platform_device *dev, pm_message_t msg) { @@ -930,7 +930,7 @@ static int xxxfb_suspend(struct platform_device *dev, pm_message_t msg) * xxxfb_resume - Optional but recommended function. Resume the device. * @dev: platform device * - * See Documentation/power/devices.txt for more information + * See Documentation/power/admin-guide/devices.rst for more information */ static int xxxfb_resume(struct platform_dev *dev) { diff --git a/drivers/virtio/Kconfig b/drivers/virtio/Kconfig index 77590320d44c..623f72334fa5 100644 --- a/drivers/virtio/Kconfig +++ b/drivers/virtio/Kconfig @@ -75,7 +75,7 @@ config VIRTIO_MMIO_CMDLINE_DEVICES Allow virtio-mmio devices instantiation via the kernel command line or module parameters. Be aware that using incorrect parameters (base address in particular) can crash your system - you have been warned. - See Documentation/kernel-parameters.txt for details. + See Documentation/admin-guide/kernel-parameters.rst for details. If unsure, say 'N'. diff --git a/fs/Kconfig.binfmt b/fs/Kconfig.binfmt index 4c09d93d9569..b2f82cf6bf86 100644 --- a/fs/Kconfig.binfmt +++ b/fs/Kconfig.binfmt @@ -170,8 +170,8 @@ config BINFMT_MISC You can do other nice things, too. Read the file to learn how to use this - feature, for information about how - to include Java support. and for + feature, for information about how + to include Java support. and for information about how to include Mono-based .NET support. To use binfmt_misc, you will need to mount it: diff --git a/fs/pstore/Kconfig b/fs/pstore/Kconfig index be40813eff52..b42e5bd6d8ff 100644 --- a/fs/pstore/Kconfig +++ b/fs/pstore/Kconfig @@ -86,4 +86,4 @@ config PSTORE_RAM Note that for historical reasons, the module will be named "ramoops.ko". - For more information, see Documentation/ramoops.txt. + For more information, see Documentation/admin-guide/ramoops.rst. diff --git a/include/linux/device.h b/include/linux/device.h index bc41e87a969b..36d3a9867da9 100644 --- a/include/linux/device.h +++ b/include/linux/device.h @@ -733,7 +733,7 @@ struct device_dma_parameters { * minimizes board-specific #ifdefs in drivers. * @driver_data: Private pointer for driver specific info. * @power: For device power management. - * See Documentation/power/devices.txt for details. + * See Documentation/power/admin-guide/devices.rst for details. * @pm_domain: Provide callbacks that are executed during system suspend, * hibernation, system resume and during runtime PM transitions * along with subsystem-level and driver-level callbacks. diff --git a/include/linux/pm.h b/include/linux/pm.h index 06eb353182ab..efa67b2dfee9 100644 --- a/include/linux/pm.h +++ b/include/linux/pm.h @@ -258,7 +258,7 @@ typedef struct pm_message { * example, if it detects that a child was unplugged while the system was * asleep). * - * Refer to Documentation/power/devices.txt for more information about the role + * Refer to Documentation/power/admin-guide/devices.rst for more information about the role * of the above callbacks in the system suspend process. * * There also are callbacks related to runtime power management of devices. diff --git a/include/uapi/linux/major.h b/include/uapi/linux/major.h index 620252e69b44..19e195bee990 100644 --- a/include/uapi/linux/major.h +++ b/include/uapi/linux/major.h @@ -3,7 +3,7 @@ /* * This file has definitions for major device numbers. - * For the device number assignments, see Documentation/devices.txt. + * For the device number assignments, see Documentation/admin-guide/devices.rst. */ #define UNNAMED_MAJOR 0 diff --git a/init/Kconfig b/init/Kconfig index 34407f15e6d3..172f80ea0d58 100644 --- a/init/Kconfig +++ b/init/Kconfig @@ -1306,7 +1306,7 @@ config BLK_DEV_INITRD boot loader (loadlin or lilo) and that is mounted as root before the normal boot procedure. It is typically used to load modules needed to mount the "real" root file system, - etc. See for details. + etc. See for details. If RAM disk support (BLK_DEV_RAM) is also included, this also enables initial RAM disk (initrd) support and adds diff --git a/init/main.c b/init/main.c index 2858be732f6d..691eb9351a83 100644 --- a/init/main.c +++ b/init/main.c @@ -980,7 +980,7 @@ static int __ref kernel_init(void *unused) return 0; panic("No working init found. Try passing init= option to kernel. " - "See Linux Documentation/init.txt for guidance."); + "See Linux Documentation/admin-guide/init.rst for guidance."); } static noinline void __init kernel_init_freeable(void) diff --git a/lib/Kconfig.debug b/lib/Kconfig.debug index 33bc56cf60d7..d2df3a93284b 100644 --- a/lib/Kconfig.debug +++ b/lib/Kconfig.debug @@ -13,7 +13,7 @@ config PRINTK_TIME be included, not that the timestamp is recorded. The behavior is also controlled by the kernel command line - parameter printk.time=1. See Documentation/kernel-parameters.txt + parameter printk.time=1. See Documentation/admin-guide/kernel-parameters.rst config MESSAGE_LOGLEVEL_DEFAULT int "Default message log level (1-7)" diff --git a/scripts/checkpatch.pl b/scripts/checkpatch.pl index a8368d1c4348..d0c729ccec20 100755 --- a/scripts/checkpatch.pl +++ b/scripts/checkpatch.pl @@ -2187,7 +2187,7 @@ sub process { if ($rawline=~/^\+\+\+\s+(\S+)/) { $setup_docs = 0; - if ($1 =~ m@Documentation/kernel-parameters.txt$@) { + if ($1 =~ m@Documentation/admin-guide/kernel-parameters.rst$@) { $setup_docs = 1; } #next; @@ -5102,7 +5102,7 @@ sub process { my $asm_volatile = qr{\b(__asm__|asm)\s+(__volatile__|volatile)\b}; if ($line =~ /\bvolatile\b/ && $line !~ /$asm_volatile/) { WARN("VOLATILE", - "Use of volatile is usually wrong: see Documentation/volatile-considered-harmful.txt\n" . $herecurr); + "Use of volatile is usually wrong: see Documentation/process/volatile-considered-harmful.rst\n" . $herecurr); } # Check for user-visible strings broken across lines, which breaks the ability @@ -5817,7 +5817,7 @@ sub process { if (!grep(/$name/, @setup_docs)) { CHK("UNDOCUMENTED_SETUP", - "__setup appears un-documented -- check Documentation/kernel-parameters.txt\n" . $herecurr); + "__setup appears un-documented -- check Documentation/admin-guide/kernel-parameters.rst\n" . $herecurr); } } diff --git a/tools/testing/selftests/futex/README b/tools/testing/selftests/futex/README index 0558bb9ce0a6..f3926c33ed4c 100644 --- a/tools/testing/selftests/futex/README +++ b/tools/testing/selftests/futex/README @@ -59,4 +59,4 @@ o FIXME: decide on a sane test naming scheme. Currently the tests are named Coding Style ------------ o The Futex Test project adheres to the coding standards set forth by Linux - kernel as defined in the Linux source Documentation/CodingStyle. + kernel as defined in the Linux source Documentation/process/coding-style.rst. -- cgit v1.2.3 From 08a9a8d44c1c0e1b6d765a627b6f895dc6202e9b Mon Sep 17 00:00:00 2001 From: Mauro Carvalho Chehab Date: Tue, 18 Oct 2016 09:22:55 -0200 Subject: doc: re-add CodingStyle and SubmittingPatches Those files got moved to Documentation/process, but as they're very well known files, add pointers to their new locations. PS.: I opted to not merge this patch with the previous one in order to make the diff of the previous one more consistent, as it will show only renames. Signed-off-by: Mauro Carvalho Chehab --- Documentation/CodingStyle | 1 + Documentation/SubmittingPatches | 1 + 2 files changed, 2 insertions(+) create mode 100644 Documentation/CodingStyle create mode 100644 Documentation/SubmittingPatches diff --git a/Documentation/CodingStyle b/Documentation/CodingStyle new file mode 100644 index 000000000000..320983ca114e --- /dev/null +++ b/Documentation/CodingStyle @@ -0,0 +1 @@ +This file has moved to process/coding-style.rst diff --git a/Documentation/SubmittingPatches b/Documentation/SubmittingPatches new file mode 100644 index 000000000000..81455705e4a6 --- /dev/null +++ b/Documentation/SubmittingPatches @@ -0,0 +1 @@ +This file has moved to process/submitting-patches.rst -- cgit v1.2.3 From 6bef44b9b969a8bcf49f28a3079400ab1dac5769 Mon Sep 17 00:00:00 2001 From: Mauro Carvalho Chehab Date: Tue, 18 Oct 2016 10:46:38 -0200 Subject: README: add a new README file, pointing to the Documentation/ As we moved the real README file to Documentation/admin-guide/README.rst, let's add a replacement, pointing to it, and giving the main directions about documentation. In the future, perhaps it would be worth to move the contents of Documentation/00-Index into this README. Signed-off-by: Mauro Carvalho Chehab --- README | 18 ++++++++++++++++++ 1 file changed, 18 insertions(+) create mode 100644 README diff --git a/README b/README new file mode 100644 index 000000000000..b2ba4aaa3a71 --- /dev/null +++ b/README @@ -0,0 +1,18 @@ +Linux kernel +============ + +This file was moved to Documentation/admin-guide/README.rst + +Please notice that there are several guides for kernel developers and users. +These guides can be rendered in a number of formats, like HTML and PDF. + +In order to build the documentation, use ``make htmldocs`` or +``make pdfdocs``. + +There are various text files in the Documentation/ subdirectory, +several of them using the Restructured Text markup notation. +See Documentation/00-INDEX for a list of what is contained in each file. + +Please read the Documentation/process/changes.rst file, as it contains the +requirements for building and running the kernel, and information about +the problems which may result by upgrading your kernel. -- cgit v1.2.3 From 3cbd4b543bef00c638fd63f6f043006c0c432f23 Mon Sep 17 00:00:00 2001 From: Mauro Carvalho Chehab Date: Tue, 18 Oct 2016 12:31:12 -0200 Subject: Documentation/00-INDEX: remove legacy media directories The dvb/ and video4linux/ dirs were removed, as now, all media documentation is under media/. Signed-off-by: Mauro Carvalho Chehab --- Documentation/00-INDEX | 4 ---- 1 file changed, 4 deletions(-) diff --git a/Documentation/00-INDEX b/Documentation/00-INDEX index 39caa6544d1f..903ebc494f29 100644 --- a/Documentation/00-INDEX +++ b/Documentation/00-INDEX @@ -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/ @@ -458,8 +456,6 @@ 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/ -- cgit v1.2.3