From 83d26b63268faf9137878e34f7e8cfda8a089124 Mon Sep 17 00:00:00 2001 From: Dave Anderson Date: Mon, 28 Mar 2016 14:56:47 -0700 Subject: [PATCH 01/55] bpf: doc: "neg" opcode has no operands Fixes a copy-paste-o in the BPF opcode table: "neg" takes no arguments and thus has no addressing modes. Signed-off-by: Dave Anderson Signed-off-by: Kees Cook Acked-by: Alexei Starovoitov Acked-by: Daniel Borkmann Signed-off-by: Jonathan Corbet --- Documentation/networking/filter.txt | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Documentation/networking/filter.txt b/Documentation/networking/filter.txt index 96da119a47e70f..11f67f181d39e7 100644 --- a/Documentation/networking/filter.txt +++ b/Documentation/networking/filter.txt @@ -230,7 +230,7 @@ opcodes as defined in linux/filter.h stand for: mul 0, 4 A * div 0, 4 A / mod 0, 4 A % - neg 0, 4 !A + neg !A and 0, 4 A & or 0, 4 A | xor 0, 4 A ^ From dbe7fcdaf94052faf65172bb91d4266d20b5458b Mon Sep 17 00:00:00 2001 From: Jianyu Zhan Date: Sun, 27 Mar 2016 11:51:20 +0800 Subject: [PATCH 02/55] Documentation/IRQ-domain.txt: Document irq_domain_create_{linear, tree} They have the same functionalities as irq_domain_add_{linear, tree}, except fro accepting different first argument. Signed-off-by: Jianyu Zhan Acked-by: Marc Zyngier Signed-off-by: Jonathan Corbet --- Documentation/IRQ-domain.txt | 12 ++++++++++++ 1 file changed, 12 insertions(+) diff --git a/Documentation/IRQ-domain.txt b/Documentation/IRQ-domain.txt index 8d990bde8693fd..82001a25a14bd7 100644 --- a/Documentation/IRQ-domain.txt +++ b/Documentation/IRQ-domain.txt @@ -70,6 +70,7 @@ of the reverse map types are described below: ==== Linear ==== irq_domain_add_linear() +irq_domain_create_linear() The linear reverse map maintains a fixed size table indexed by the hwirq number. When a hwirq is mapped, an irq_desc is allocated for @@ -81,10 +82,16 @@ map are fixed time lookup for IRQ numbers, and irq_descs are only allocated for in-use IRQs. The disadvantage is that the table must be as large as the largest possible hwirq number. +irq_domain_add_linear() and irq_domain_create_linear() are functionally +equivalent, except for the first argument is different - the former +accepts an Open Firmware specific 'struct device_node', while the latter +accepts a more general abstraction 'struct fwnode_handle'. + The majority of drivers should use the linear map. ==== Tree ==== irq_domain_add_tree() +irq_domain_create_tree() The irq_domain maintains a radix tree map from hwirq numbers to Linux IRQs. When an hwirq is mapped, an irq_desc is allocated and the @@ -95,6 +102,11 @@ since it doesn't need to allocate a table as large as the largest hwirq number. The disadvantage is that hwirq to IRQ number lookup is dependent on how many entries are in the table. +irq_domain_add_tree() and irq_domain_create_tree() are functionally +equivalent, except for the first argument is different - the former +accepts an Open Firmware specific 'struct device_node', while the latter +accepts a more general abstraction 'struct fwnode_handle'. + Very few drivers should need this mapping. ==== No Map ===- From 5408e5a4552b8e33a65127944bec21dd3d9258c1 Mon Sep 17 00:00:00 2001 From: Wei Fang Date: Mon, 21 Mar 2016 19:42:19 +0800 Subject: [PATCH 03/55] Documentation: update missing index files in block/00-INDEX Update missing index files in block/00-INDEX. Signed-off-by: Wei Fang Signed-off-by: Jonathan Corbet --- Documentation/block/00-INDEX | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/Documentation/block/00-INDEX b/Documentation/block/00-INDEX index e840b47613f78f..e55103ace382a0 100644 --- a/Documentation/block/00-INDEX +++ b/Documentation/block/00-INDEX @@ -2,6 +2,8 @@ - This file biodoc.txt - Notes on the Generic Block Layer Rewrite in Linux 2.5 +biovecs.txt + - Immutable biovecs and biovec iterators capability.txt - Generic Block Device Capability (/sys/block//capability) cfq-iosched.txt @@ -14,6 +16,8 @@ deadline-iosched.txt - Deadline IO scheduler tunables ioprio.txt - Block io priorities (in CFQ scheduler) +pr.txt + - Block layer support for Persistent Reservations null_blk.txt - Null block for block-layer benchmarking. queue-sysfs.txt From a06bdd49c98c6a538890650bac9a0173cbc644b2 Mon Sep 17 00:00:00 2001 From: Luis de Bethencourt Date: Sat, 19 Mar 2016 12:51:20 +0000 Subject: [PATCH 04/55] Documentation: add Linux Kernel Development book The Linux Kernel Development book by Robert Love has been recommended to me by multiple kernel hackers. Worth having in the list of books in kernel-docs.txt for newbies looking for good learning resources. Signed-off-by: Luis de Bethencourt Signed-off-by: Jonathan Corbet --- Documentation/kernel-docs.txt | 7 +++++++ 1 file changed, 7 insertions(+) diff --git a/Documentation/kernel-docs.txt b/Documentation/kernel-docs.txt index fe217c1c2f7fb2..b2503602134fe6 100644 --- a/Documentation/kernel-docs.txt +++ b/Documentation/kernel-docs.txt @@ -609,6 +609,13 @@ Pages: 432. ISBN: 0-201-63338-8 + * Title: "Linux Kernel Development, 3rd Edition" + Author: Robert Love + Publisher: Addison-Wesley. + Date: July, 2010 + Pages: 440 + ISBN: 978-0672329463 + MISCELLANEOUS: * Name: linux/Documentation From dc831ab3cc7f22ae500872e54cd85317e766c156 Mon Sep 17 00:00:00 2001 From: Luis de Bethencourt Date: Sat, 19 Mar 2016 12:51:22 +0000 Subject: [PATCH 05/55] Documentation: update URL of Analysis of the Ext2fs structure The current URL has been down for some time, updating it to a working one. Signed-off-by: Luis de Bethencourt Signed-off-by: Jonathan Corbet --- Documentation/kernel-docs.txt | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Documentation/kernel-docs.txt b/Documentation/kernel-docs.txt index b2503602134fe6..b92449feea235d 100644 --- a/Documentation/kernel-docs.txt +++ b/Documentation/kernel-docs.txt @@ -250,7 +250,7 @@ * Title: "Analysis of the Ext2fs structure" Author: Louis-Dominique Dubeau. - URL: http://www.nondot.org/sabre/os/files/FileSystems/ext2fs/ + URL: http://teaching.csse.uwa.edu.au/units/CITS2002/fs-ext2/ Keywords: ext2, filesystem, ext2fs. Description: Description of ext2's blocks, directories, inodes, bitmaps, invariants... From f7ca20deee2b2eac0a43e1dcf75d5d3ee2c6c81e Mon Sep 17 00:00:00 2001 From: Luis de Bethencourt Date: Sat, 19 Mar 2016 12:51:23 +0000 Subject: [PATCH 06/55] Documentation: update URLs for Richard Gooch's articles Current URL for "Kernel API changes from 2.0 to 2.2" hasn't been available for some time, updating. The second article about changes from 2.2 to 2.4 is missing a URL, adding it. Signed-off-by: Luis de Bethencourt Signed-off-by: Jonathan Corbet --- Documentation/kernel-docs.txt | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/Documentation/kernel-docs.txt b/Documentation/kernel-docs.txt index b92449feea235d..3aecbac1cb0175 100644 --- a/Documentation/kernel-docs.txt +++ b/Documentation/kernel-docs.txt @@ -266,14 +266,14 @@ * Title: "Kernel API changes from 2.0 to 2.2" Author: Richard Gooch. - URL: - http://www.linuxhq.com/guides/LKMPG/node28.html + URL: http://www.safe-mbox.com/~rgooch/linux/docs/porting-to-2.2.html Keywords: 2.2, changes. Description: Kernel functions/structures/variables which changed from 2.0.x to 2.2.x. * Title: "Kernel API changes from 2.2 to 2.4" Author: Richard Gooch. + URL: http://www.safe-mbox.com/~rgooch/linux/docs/porting-to-2.4.html Keywords: 2.4, changes. Description: Kernel functions/structures/variables which changed from 2.2.x to 2.4.x. From f3e27a80b782b9b9857157e0a104a8757e72d166 Mon Sep 17 00:00:00 2001 From: Baolin Wang Date: Wed, 16 Mar 2016 20:02:49 +0800 Subject: [PATCH 07/55] Documentation: mmc: Add the introduction for mmc-utils This patch introduces one mmc test tools called mmc-utils, which is convenient if someone wants to exercise and test MMC/SD devices from userspace. Signed-off-by: Baolin Wang Signed-off-by: Jonathan Corbet --- Documentation/mmc/00-INDEX | 2 ++ Documentation/mmc/mmc-tools.txt | 34 +++++++++++++++++++++++++++++++++ 2 files changed, 36 insertions(+) create mode 100644 Documentation/mmc/mmc-tools.txt diff --git a/Documentation/mmc/00-INDEX b/Documentation/mmc/00-INDEX index a9ba6720ffdf2f..4623bc0aa0bb49 100644 --- a/Documentation/mmc/00-INDEX +++ b/Documentation/mmc/00-INDEX @@ -6,3 +6,5 @@ mmc-dev-parts.txt - info on SD and MMC device partitions mmc-async-req.txt - info on mmc asynchronous requests +mmc-tools.txt + - info on mmc-utils tools diff --git a/Documentation/mmc/mmc-tools.txt b/Documentation/mmc/mmc-tools.txt new file mode 100644 index 00000000000000..735509c165d567 --- /dev/null +++ b/Documentation/mmc/mmc-tools.txt @@ -0,0 +1,34 @@ +MMC tools introduction +====================== + +There is one MMC test tools called mmc-utils, which is maintained by Chris Ball, +you can find it at the below public git repository: +http://git.kernel.org/cgit/linux/kernel/git/cjb/mmc-utils.git/ + +Functions +========= + +The mmc-utils tools can do the following: + - Print and parse extcsd data. + - Determine the eMMC writeprotect status. + - Set the eMMC writeprotect status. + - Set the eMMC data sector size to 4KB by disabling emulation. + - Create general purpose partition. + - Enable the enhanced user area. + - Enable write reliability per partition. + - Print the response to STATUS_SEND (CMD13). + - Enable the boot partition. + - Set Boot Bus Conditions. + - Enable the eMMC BKOPS feature. + - Permanently enable the eMMC H/W Reset feature. + - Permanently disable the eMMC H/W Reset feature. + - Send Sanitize command. + - Program authentication key for the device. + - Counter value for the rpmb device will be read to stdout. + - Read from rpmb device to output. + - Write to rpmb device from data file. + - Enable the eMMC cache feature. + - Disable the eMMC cache feature. + - Print and parse CID data. + - Print and parse CSD data. + - Print and parse SCR data. From 834392a7d92677ff2bdc1c709b1171ee585b55c9 Mon Sep 17 00:00:00 2001 From: Geert Uytterhoeven Date: Mon, 14 Mar 2016 16:16:09 +0100 Subject: [PATCH 08/55] serial: doc: Un-document non-existing uart_write_console() uart_write_console() never existed, not even when the "new uart_write_console function" was documented. Fixes: 67ab7f596b6adbae ("[SERIAL] Update serial driver documentation") Signed-off-by: Geert Uytterhoeven Signed-off-by: Jonathan Corbet --- Documentation/serial/driver | 5 ----- 1 file changed, 5 deletions(-) diff --git a/Documentation/serial/driver b/Documentation/serial/driver index 379468e12680db..e7c6f86ee06f99 100644 --- a/Documentation/serial/driver +++ b/Documentation/serial/driver @@ -28,11 +28,6 @@ The serial core provides a few helper functions. This includes identifing the correct port structure (via uart_get_console) and decoding command line arguments (uart_parse_options). -There is also a helper function (uart_write_console) which performs a -character by character write, translating newlines to CRLF sequences. -Driver writers are recommended to use this function rather than implementing -their own version. - Locking ------- From 4895b1d72117efea48ff51e94a26ce3cbde4d1a1 Mon Sep 17 00:00:00 2001 From: Geert Uytterhoeven Date: Mon, 14 Mar 2016 16:16:10 +0100 Subject: [PATCH 09/55] serial: doc: Un-document obsolete tmpbuf_sem uart_info.tmpbuf and uart_info.tmpbuf_sem were removed in v2.6.10, in full-history-linux commit a797ad7e3ae9cad4 ("[SERIAL] Clean up serial_core.c write functions."). Signed-off-by: Geert Uytterhoeven Signed-off-by: Jonathan Corbet --- Documentation/serial/driver | 6 +----- 1 file changed, 1 insertion(+), 5 deletions(-) diff --git a/Documentation/serial/driver b/Documentation/serial/driver index e7c6f86ee06f99..61d520dea4c6e1 100644 --- a/Documentation/serial/driver +++ b/Documentation/serial/driver @@ -36,8 +36,7 @@ It is the responsibility of the low level hardware driver to perform the necessary locking using port->lock. There are some exceptions (which are described in the uart_ops listing below.) -There are three locks. A per-port spinlock, a per-port tmpbuf semaphore, -and an overall semaphore. +There are two locks. A per-port spinlock, and an overall semaphore. From the core driver perspective, the port->lock locks the following data: @@ -50,9 +49,6 @@ data: The low level driver is free to use this lock to provide any additional locking. -The core driver uses the info->tmpbuf_sem lock to prevent multi-threaded -access to the info->tmpbuf bouncebuffer used for port writes. - The port_sem semaphore is used to protect against ports being added/ removed or reconfigured at inappropriate times. Since v2.6.27, this semaphore has been the 'mutex' member of the tty_port struct, and From 39c5144e5f0bc2dec9ebe3613d5f9c0f0b0bdc72 Mon Sep 17 00:00:00 2001 From: Geert Uytterhoeven Date: Mon, 14 Mar 2016 16:16:11 +0100 Subject: [PATCH 10/55] serial: doc: Document .throttle() Signed-off-by: Geert Uytterhoeven Signed-off-by: Jonathan Corbet --- Documentation/serial/driver | 7 +++++++ 1 file changed, 7 insertions(+) diff --git a/Documentation/serial/driver b/Documentation/serial/driver index 61d520dea4c6e1..50f3d94ed50b34 100644 --- a/Documentation/serial/driver +++ b/Documentation/serial/driver @@ -126,6 +126,13 @@ hardware. Interrupts: locally disabled. This call must not sleep + throttle(port) + Notify the serial driver that input buffers for the line discipline are + close to full, and it should somehow signal that no more characters + should be sent to the serial port. + + Locking: none. + send_xchar(port,ch) Transmit a high priority character, even if the port is stopped. This is used to implement XON/XOFF flow control and tcflow(). If From e27585c7970decd26113ca036a1cb5678d88ee5a Mon Sep 17 00:00:00 2001 From: Geert Uytterhoeven Date: Mon, 14 Mar 2016 16:16:12 +0100 Subject: [PATCH 11/55] serial: doc: Document .unthrottle() Signed-off-by: Geert Uytterhoeven Signed-off-by: Jonathan Corbet --- Documentation/serial/driver | 7 +++++++ 1 file changed, 7 insertions(+) diff --git a/Documentation/serial/driver b/Documentation/serial/driver index 50f3d94ed50b34..3b2a97d5ecc794 100644 --- a/Documentation/serial/driver +++ b/Documentation/serial/driver @@ -133,6 +133,13 @@ hardware. Locking: none. + unthrottle(port) + Notify the serial driver that characters can now be sent to the serial + port without fear of overrunning the input buffers of the line + disciplines. + + Locking: none. + send_xchar(port,ch) Transmit a high priority character, even if the port is stopped. This is used to implement XON/XOFF flow control and tcflow(). If From 0adc301e7b3c098744d0098008b1aa31041e220b Mon Sep 17 00:00:00 2001 From: Geert Uytterhoeven Date: Mon, 14 Mar 2016 16:16:13 +0100 Subject: [PATCH 12/55] serial: doc: Document .set_ldisc() Signed-off-by: Geert Uytterhoeven Signed-off-by: Jonathan Corbet --- Documentation/serial/driver | 5 +++++ 1 file changed, 5 insertions(+) diff --git a/Documentation/serial/driver b/Documentation/serial/driver index 3b2a97d5ecc794..3b08df5bcc17e9 100644 --- a/Documentation/serial/driver +++ b/Documentation/serial/driver @@ -259,6 +259,11 @@ hardware. Interrupts: caller dependent. This call must not sleep + set_ldisc(port,termios) + Notifier for discipline change. See Documentation/serial/tty.txt. + + Locking: caller holds port->mutex + pm(port,state,oldstate) Perform any power management related activities on the specified port. State indicates the new state (defined by From fbe3128bcf87723bbbaa2de26f5d1c1122c66b54 Mon Sep 17 00:00:00 2001 From: Geert Uytterhoeven Date: Mon, 14 Mar 2016 16:16:14 +0100 Subject: [PATCH 13/55] serial: doc: .break_ctl() is called with port->mutex() held Note that mutex_lock() should not be called with interrupts disabled. Signed-off-by: Geert Uytterhoeven Signed-off-by: Jonathan Corbet --- Documentation/serial/driver | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/Documentation/serial/driver b/Documentation/serial/driver index 3b08df5bcc17e9..09e73e061fcf79 100644 --- a/Documentation/serial/driver +++ b/Documentation/serial/driver @@ -177,8 +177,7 @@ hardware. should be terminated when another call is made with a zero ctl. - Locking: none. - Interrupts: caller dependent. + Locking: caller holds port->mutex This call must not sleep startup(port) From 93a2f6329f40d951101ab8ab160f24680f1c122a Mon Sep 17 00:00:00 2001 From: Geert Uytterhoeven Date: Mon, 14 Mar 2016 16:16:15 +0100 Subject: [PATCH 14/55] serial: doc: Spelling s/divsor/divisor/ Signed-off-by: Geert Uytterhoeven Signed-off-by: Jonathan Corbet --- Documentation/serial/driver | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Documentation/serial/driver b/Documentation/serial/driver index 09e73e061fcf79..3706a465fe2d74 100644 --- a/Documentation/serial/driver +++ b/Documentation/serial/driver @@ -380,7 +380,7 @@ uart_get_baud_rate(port,termios,old,min,max) Interrupts: n/a uart_get_divisor(port,baud) - Return the divsor (baud_base / baud) for the specified baud + Return the divisor (baud_base / baud) for the specified baud rate, appropriately rounded. If 38400 baud and custom divisor is selected, return the From d886e7ce157373773254f5c1e7f011cd9d3ec558 Mon Sep 17 00:00:00 2001 From: Geert Uytterhoeven Date: Mon, 14 Mar 2016 16:16:16 +0100 Subject: [PATCH 15/55] serial: doc: Grammar s/function are/functions are/ Signed-off-by: Geert Uytterhoeven Signed-off-by: Jonathan Corbet --- Documentation/serial/driver | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Documentation/serial/driver b/Documentation/serial/driver index 3706a465fe2d74..ba84d1f38ca1d1 100644 --- a/Documentation/serial/driver +++ b/Documentation/serial/driver @@ -458,7 +458,7 @@ mctrl_gpio_init(port, idx): mctrl_gpio_free(dev, gpios): This will free the requested gpios in mctrl_gpio_init(). - As devm_* function are used, there's generally no need to call + As devm_* functions are used, there's generally no need to call this function. mctrl_gpio_to_gpiod(gpios, gidx) From 4817ebb144ffa5a1a2bc84b89ed9655dbe6c4502 Mon Sep 17 00:00:00 2001 From: Geert Uytterhoeven Date: Mon, 14 Mar 2016 16:16:17 +0100 Subject: [PATCH 16/55] serial: doc: Correct return type of mctrl_gpio_to_gpiod() Signed-off-by: Geert Uytterhoeven Signed-off-by: Jonathan Corbet --- Documentation/serial/driver | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/Documentation/serial/driver b/Documentation/serial/driver index ba84d1f38ca1d1..65de49a4b39e5b 100644 --- a/Documentation/serial/driver +++ b/Documentation/serial/driver @@ -462,7 +462,8 @@ mctrl_gpio_free(dev, gpios): this function. mctrl_gpio_to_gpiod(gpios, gidx) - This returns the gpio structure associated to the modem line index. + This returns the gpio_desc structure associated to the modem line + index. mctrl_gpio_set(gpios, mctrl): This will sets the gpios according to the mctrl state. From 4f2651e1d838c4db656170bddfcabdf67a8d7f9b Mon Sep 17 00:00:00 2001 From: Luis de Bethencourt Date: Thu, 31 Mar 2016 12:10:30 +0100 Subject: [PATCH 17/55] Documentation: update Michael K. Johnson's work The URL for "Writing Linux Device Drivers" hasn't been available in some time. Updating the entry to Michael K. Johnson's "Linux Kernel Hackers' Guide" Signed-off-by: Luis de Bethencourt Signed-off-by: Jonathan Corbet --- Documentation/kernel-docs.txt | 16 ++++++++-------- 1 file changed, 8 insertions(+), 8 deletions(-) diff --git a/Documentation/kernel-docs.txt b/Documentation/kernel-docs.txt index 3aecbac1cb0175..1dafc52167b001 100644 --- a/Documentation/kernel-docs.txt +++ b/Documentation/kernel-docs.txt @@ -194,15 +194,15 @@ simple---most of the complexity (other than talking to the hardware) involves managing network packets in memory". - * Title: "Writing Linux Device Drivers" + * Title: "Linux Kernel Hackers' Guide" Author: Michael K. Johnson. - URL: http://users.evitech.fi/~tk/rtos/writing_linux_device_d.html - Keywords: files, VFS, file operations, kernel interface, character - vs block devices, I/O access, hardware interrupts, DMA, access to - user memory, memory allocation, timers. - Description: Introductory 50-minutes (sic) tutorial on writing - device drivers. 12 pages written by the same author of the "Kernel - Hackers' Guide" which give a very good overview of the topic. + URL: http://www.tldp.org/LDP/khg/HyperNews/get/khg.html + 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: "The Venus kernel interface" Author: Peter J. Braam. From cfaf790f932beae903a5fc5b19039d7b3842a3b3 Mon Sep 17 00:00:00 2001 From: Diego Viola Date: Sun, 3 Apr 2016 04:34:48 -0300 Subject: [PATCH 18/55] README: remove trailing whitespace Signed-off-by: Diego Viola Signed-off-by: Jonathan Corbet --- README | 20 ++++++++++---------- 1 file changed, 10 insertions(+), 10 deletions(-) diff --git a/README b/README index afc4f0d81ee179..e8c8a6dc1c2bc9 100644 --- a/README +++ b/README @@ -2,7 +2,7 @@ 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. +kernel, and what to do if something goes wrong. WHAT IS LINUX? @@ -16,7 +16,7 @@ WHAT IS LINUX? and multistack networking including IPv4 and IPv6. It is distributed under the GNU General Public License - see the - accompanying COPYING file for more details. + accompanying COPYING file for more details. ON WHAT HARDWARE DOES IT RUN? @@ -44,7 +44,7 @@ DOCUMENTATION: 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 + 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 @@ -276,7 +276,7 @@ COMPILING the kernel: 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 + - 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 @@ -290,7 +290,7 @@ COMPILING the kernel: - In order to boot your new kernel, you'll need to copy the kernel image (e.g. .../linux/arch/i386/boot/bzImage after compilation) - to the place where your regular bootable kernel is found. + 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. @@ -303,10 +303,10 @@ COMPILING the kernel: 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. + 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. + work. See the LILO docs for more information. After reinstalling LILO, you should be all set. Shutdown the system, reboot, and enjoy! @@ -314,9 +314,9 @@ COMPILING the kernel: 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. + recompile the kernel to change these parameters. - - Reboot with the new kernel and enjoy. + - Reboot with the new kernel and enjoy. IF SOMETHING GOES WRONG: @@ -383,7 +383,7 @@ IF SOMETHING GOES WRONG: 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. + 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 From 2dd723fdbb61fbc4ee0125401f04f5431f61268d Mon Sep 17 00:00:00 2001 From: Diego Herranz Date: Tue, 12 Apr 2016 18:13:27 +0100 Subject: [PATCH 19/55] doc: usb: Fix typo in gadget_multi documentation It tries to "match" drivers for each interface (not "much"). Signed-off-by: Diego Herranz Signed-off-by: Jonathan Corbet --- Documentation/usb/gadget_multi.txt | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Documentation/usb/gadget_multi.txt b/Documentation/usb/gadget_multi.txt index 7d66a8636cb5d1..5faf514047e9f8 100644 --- a/Documentation/usb/gadget_multi.txt +++ b/Documentation/usb/gadget_multi.txt @@ -43,7 +43,7 @@ For the gadget two work under Windows two conditions have to be met: First of all, Windows need to detect the gadget as an USB composite gadget which on its own have some conditions[4]. If they are met, Windows lets USB Generic Parent Driver[5] handle the device which then -tries to much drivers for each individual interface (sort of, don't +tries to match drivers for each individual interface (sort of, don't get into too many details). The good news is: you do not have to worry about most of the From 63f8e8d2a575ef62e5b705516b491a98a60517ff Mon Sep 17 00:00:00 2001 From: Doug Hoyte Date: Wed, 13 Apr 2016 11:09:21 -0400 Subject: [PATCH 20/55] Documentation typo: wrong page flag bit for KPF_HUGE The correct value 17 can be found later in this document and in the kernel-page-flags.h header (KPF_HUGE). I noticed this while implementing vmprobe's kpageflags support. Signed-off-by: Jonathan Corbet --- Documentation/vm/pagemap.txt | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Documentation/vm/pagemap.txt b/Documentation/vm/pagemap.txt index 0e1e55588b598b..eafcefa1526113 100644 --- a/Documentation/vm/pagemap.txt +++ b/Documentation/vm/pagemap.txt @@ -62,7 +62,7 @@ There are four components to pagemap: 14. SWAPBACKED 15. COMPOUND_HEAD 16. COMPOUND_TAIL - 16. HUGE + 17. HUGE 18. UNEVICTABLE 19. HWPOISON 20. NOPAGE From d124fd3bb36ceb40438f10c897ce642386b74b72 Mon Sep 17 00:00:00 2001 From: Geert Uytterhoeven Date: Thu, 14 Apr 2016 11:08:08 +0200 Subject: [PATCH 21/55] serial: doc: Re-add paragraph documenting uart_console_write() Commit 834392a7d92677ff ("serial: doc: Un-document non-existing uart_write_console()") removed a paragraph about a helper function that seemed to never exist. Peter Hurley pointed out that the function does exist, but is called differently. Re-add the paragraph, with the function name corrected. Fixes: 834392a7d92677ff ("serial: doc: Un-document non-existing uart_write_console()") Signed-off-by: Geert Uytterhoeven Signed-off-by: Jonathan Corbet --- Documentation/serial/driver | 5 +++++ 1 file changed, 5 insertions(+) diff --git a/Documentation/serial/driver b/Documentation/serial/driver index 65de49a4b39e5b..03369d076ca20a 100644 --- a/Documentation/serial/driver +++ b/Documentation/serial/driver @@ -28,6 +28,11 @@ The serial core provides a few helper functions. This includes identifing the correct port structure (via uart_get_console) and decoding command line arguments (uart_parse_options). +There is also a helper function (uart_console_write) which performs a +character by character write, translating newlines to CRLF sequences. +Driver writers are recommended to use this function rather than implementing +their own version. + Locking ------- From a3bedc3bdc6e640141157636e253d63279860e23 Mon Sep 17 00:00:00 2001 From: Geert Uytterhoeven Date: Thu, 14 Apr 2016 11:08:09 +0200 Subject: [PATCH 22/55] serial: doc: .(un)throttle() depends on hardware assisted flow control Document that .throttle() and .unthrottle() are relevant only if hardware assisted flow control is enabled. Signed-off-by: Geert Uytterhoeven Signed-off-by: Jonathan Corbet --- Documentation/serial/driver | 2 ++ 1 file changed, 2 insertions(+) diff --git a/Documentation/serial/driver b/Documentation/serial/driver index 03369d076ca20a..03b703cf931822 100644 --- a/Documentation/serial/driver +++ b/Documentation/serial/driver @@ -135,6 +135,7 @@ hardware. Notify the serial driver that input buffers for the line discipline are close to full, and it should somehow signal that no more characters should be sent to the serial port. + This will be called only if hardware assisted flow control is enabled. Locking: none. @@ -142,6 +143,7 @@ hardware. Notify the serial driver that characters can now be sent to the serial port without fear of overrunning the input buffers of the line disciplines. + This will be called only if hardware assisted flow control is enabled. Locking: none. From 18717b06ee4897c2cc5e92783386c4b304b9fce9 Mon Sep 17 00:00:00 2001 From: Geert Uytterhoeven Date: Thu, 14 Apr 2016 11:08:10 +0200 Subject: [PATCH 23/55] serial: doc: .(un)throttle() are serialized by the tty layer Document that .(un)throttle() are serialized with each other, and with termios modification by the tty layer. Reported-by: Peter Hurley Signed-off-by: Geert Uytterhoeven Signed-off-by: Jonathan Corbet --- Documentation/serial/driver | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/Documentation/serial/driver b/Documentation/serial/driver index 03b703cf931822..7fb80682e394eb 100644 --- a/Documentation/serial/driver +++ b/Documentation/serial/driver @@ -137,7 +137,8 @@ hardware. should be sent to the serial port. This will be called only if hardware assisted flow control is enabled. - Locking: none. + Locking: serialized with .unthrottle() and termios modification by the + tty layer. unthrottle(port) Notify the serial driver that characters can now be sent to the serial @@ -145,7 +146,8 @@ hardware. disciplines. This will be called only if hardware assisted flow control is enabled. - Locking: none. + Locking: serialized with .throttle() and termios modification by the + tty layer. send_xchar(port,ch) Transmit a high priority character, even if the port is stopped. From 101ca9ccdd30c46afc5c9a30e7acdcbeaa330fa1 Mon Sep 17 00:00:00 2001 From: Geert Uytterhoeven Date: Thu, 14 Apr 2016 11:08:11 +0200 Subject: [PATCH 24/55] serial: doc: .break_ctl() may sleep break_ctl() is not called from any sort of atomic context, so there is no problem with it sleeping. Reported-by: Peter Hurley Signed-off-by: Geert Uytterhoeven Signed-off-by: Jonathan Corbet --- Documentation/serial/driver | 1 - 1 file changed, 1 deletion(-) diff --git a/Documentation/serial/driver b/Documentation/serial/driver index 7fb80682e394eb..39701515832b70 100644 --- a/Documentation/serial/driver +++ b/Documentation/serial/driver @@ -187,7 +187,6 @@ hardware. ctl. Locking: caller holds port->mutex - This call must not sleep startup(port) Grab any interrupt resources and initialise any low level driver From ad0de1e3fe9aacbf110052bcc1765c877e69858f Mon Sep 17 00:00:00 2001 From: SeongJae Park Date: Sat, 16 Apr 2016 09:18:46 +0900 Subject: [PATCH 25/55] Documentatio: HOWTO: remove regression postings info from translations Obsolete info about regression postings were removed by commit 5645a717c6ee61e67d38aa9f15cb9db074e1e99d ("Documentation: HOWTO: remove obsolete info about regression postings") but not applied to translations. This commit applies the change to translations. Signed-off-by: SeongJae Park Signed-off-by: Jonathan Corbet --- Documentation/ja_JP/HOWTO | 6 ------ Documentation/ko_KR/HOWTO | 2 -- Documentation/zh_CN/HOWTO | 2 -- 3 files changed, 10 deletions(-) diff --git a/Documentation/ja_JP/HOWTO b/Documentation/ja_JP/HOWTO index 52ef02b33da9cd..581c14bdd7be2f 100644 --- a/Documentation/ja_JP/HOWTO +++ b/Documentation/ja_JP/HOWTO @@ -290,12 +290,6 @@ Linux カーネルの開発プロセスは現在幾つかの異なるメイン - このプロセスはカーネルが 「準備ができた」と考えられるまで継続しま す。このプロセスはだいたい 6週間継続します。 - - 各リリースでの既知の後戻り問題(regression: このリリースの中で新規 - に作り込まれた問題を指す) はその都度 Linux-kernel メーリングリスト - に投稿されます。ゴールとしては、カーネルが 「準備ができた」と宣言 - する前にこのリストの長さをゼロに減らすことですが、現実には、数個の - 後戻り問題がリリース時にたびたび残ってしまいます。 - Andrew Morton が Linux-kernel メーリングリストにカーネルリリースについ て書いたことをここで言っておくことは価値があります- 「カーネルがいつリリースされるかは誰も知りません。なぜなら、これは現 diff --git a/Documentation/ko_KR/HOWTO b/Documentation/ko_KR/HOWTO index 5a81b394b3b58b..46b22395748d5d 100644 --- a/Documentation/ko_KR/HOWTO +++ b/Documentation/ko_KR/HOWTO @@ -253,8 +253,6 @@ Documentation/DocBook/ 디렉토리 내에서 만들어지며 PDF, Postscript, H 것이다. - 이러한 프로세스는 커널이 "준비(ready)"되었다고 여겨질때까지 계속된다. 프로세스는 대체로 6주간 지속된다. - - 각 -rc 배포에 있는 알려진 회귀의 목록들은 다음 URI에 남겨진다. - http://kernelnewbies.org/known_regressions 커널 배포에 있어서 언급할만한 가치가 있는 리눅스 커널 메일링 리스트의 Andrew Morton의 글이 있다. diff --git a/Documentation/zh_CN/HOWTO b/Documentation/zh_CN/HOWTO index 54ea24ff63c7ce..56ca786e584253 100644 --- a/Documentation/zh_CN/HOWTO +++ b/Documentation/zh_CN/HOWTO @@ -218,8 +218,6 @@ kernel.org网站的pub/linux/kernel/v2.6/目录下找到它。它的开发遵循 时，一个新的-rc版本就会被发布。计划是每周都发布新的-rc版本。 - 这个过程一直持续下去直到内核被认为达到足够稳定的状态，持续时间大概是 6个星期。 - - 以下地址跟踪了在每个-rc发布中发现的退步列表： - http://kernelnewbies.org/known_regressions 关于内核发布，值得一提的是Andrew Morton在linux-kernel邮件列表中如是说： “没有人知道新内核何时会被发布，因为发布是根据已知bug的情况来决定 From 78f3873decadde42da6edf419635b5972ae61e00 Mon Sep 17 00:00:00 2001 From: SeongJae Park Date: Sat, 16 Apr 2016 09:32:30 +0900 Subject: [PATCH 26/55] Documentation: HOWTO: update git home URL in translations Homepage url of git in HOWTO document was updated by commit e234ebf7881c013b654113f0a208977ac3ce1d01 ("Documentation/HOWTO: update git home URL") but not applied to several translations. This commit updates them. Signed-off-by: SeongJae Park Signed-off-by: Jonathan Corbet --- Documentation/ko_KR/HOWTO | 6 +++--- Documentation/zh_CN/HOWTO | 2 +- 2 files changed, 4 insertions(+), 4 deletions(-) diff --git a/Documentation/ko_KR/HOWTO b/Documentation/ko_KR/HOWTO index 46b22395748d5d..9a3e65924d5499 100644 --- a/Documentation/ko_KR/HOWTO +++ b/Documentation/ko_KR/HOWTO @@ -236,9 +236,9 @@ Documentation/DocBook/ 디렉토리 내에서 만들어지며 PDF, Postscript, H - 새로운 커널이 배포되자마자 2주의 시간이 주어진다. 이 기간동은 메인테이너들은 큰 diff들을 Linus에게 제출할 수 있다. 대개 이 패치들은 몇 주 동안 -next 커널내에 이미 있었던 것들이다. 큰 변경들을 제출하는 데 - 선호되는 방법은 git(커널의 소스 관리 툴, 더 많은 정보들은 http://git.or.cz/ - 에서 참조할 수 있다)를 사용하는 것이지만 순수한 패치파일의 형식으로 보내는 - 것도 무관하다. + 선호되는 방법은 git(커널의 소스 관리 툴, 더 많은 정보들은 + http://git-scm.com/ 에서 참조할 수 있다)를 사용하는 것이지만 순수한 + 패치파일의 형식으로 보내는 것도 무관하다. - 2주 후에 -rc1 커널이 배포되며 지금부터는 전체 커널의 안정성에 영향을 미칠수 있는 새로운 기능들을 포함하지 않는 패치들만이 추가될 수 있다. 완전히 새로운 드라이버(혹은 파일시스템)는 -rc1 이후에만 받아들여진다는 diff --git a/Documentation/zh_CN/HOWTO b/Documentation/zh_CN/HOWTO index 56ca786e584253..f0613b92e0bedf 100644 --- a/Documentation/zh_CN/HOWTO +++ b/Documentation/zh_CN/HOWTO @@ -207,7 +207,7 @@ kernel.org网站的pub/linux/kernel/v2.6/目录下找到它。它的开发遵循 - 每当一个新版本的内核被发布，为期两周的集成窗口将被打开。在这段时间里 维护者可以向Linus提交大段的修改，通常这些修改已经被放到-mm内核中几个 星期了。提交大量修改的首选方式是使用git工具（内核的代码版本管理工具 - ，更多的信息可以在http://git.or.cz/获取），不过使用普通补丁也是可以 + ，更多的信息可以在http://git-scm.com/获取），不过使用普通补丁也是可以 的。 - 两个星期以后-rc1版本内核发布。之后只有不包含可能影响整个内核稳定性的 新功能的补丁才可能被接受。请注意一个全新的驱动程序（或者文件系统）有 From 2c30322c4795bf26a74b6049bbea6267a19036a4 Mon Sep 17 00:00:00 2001 From: Askar Safin Date: Mon, 18 Apr 2016 20:30:56 +0300 Subject: [PATCH 27/55] documentation: trivial typo: adding-syscalls.txt: s/statat/fstatat/ Signed-off-by: Askar Safin Signed-off-by: Jonathan Corbet --- Documentation/adding-syscalls.txt | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Documentation/adding-syscalls.txt b/Documentation/adding-syscalls.txt index cc2d4ac4f4042b..bbb31e091b2825 100644 --- a/Documentation/adding-syscalls.txt +++ b/Documentation/adding-syscalls.txt @@ -136,7 +136,7 @@ an fxyzzy(3) operation for free: - 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 statat(2) man page.) +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 From ac86db349e2df2e2d6b786cbacefa3037126f3bc Mon Sep 17 00:00:00 2001 From: Cao jin Date: Thu, 21 Apr 2016 21:39:15 +0800 Subject: [PATCH 28/55] hrtimers: doc cleanup It has: a tense correction(led->leads); a typo(unevitably->inevitably); Signed-off-by: Cao jin Signed-off-by: Jonathan Corbet --- Documentation/timers/hrtimers.txt | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/Documentation/timers/hrtimers.txt b/Documentation/timers/hrtimers.txt index ce31f65e12e736..492f1affb0e580 100644 --- a/Documentation/timers/hrtimers.txt +++ b/Documentation/timers/hrtimers.txt @@ -28,9 +28,9 @@ several reasons why such integration is hard/impossible: - the unpredictable [O(N)] overhead of cascading leads to delays which necessitate a more complex handling of high resolution timers, which - in turn decreases robustness. Such a design still led to rather large + in turn decreases robustness. Such a design still leads to rather large timing inaccuracies. Cascading is a fundamental property of the timer - wheel concept, it cannot be 'designed out' without unevitably + wheel concept, it cannot be 'designed out' without inevitably degrading other portions of the timers.c code in an unacceptable way. - the implementation of the current posix-timer subsystem on top of From e0a37712819cb0e942f165a3f88d85f7c6388219 Mon Sep 17 00:00:00 2001 From: Fu Wei Date: Thu, 21 Apr 2016 21:45:40 +0800 Subject: [PATCH 29/55] Documentation:Update Documentation/zh_CN/arm64/booting.txt This is a update of Chinese documentation: Documentation/zh_CN/arm64/booting.txt It is based on the modifications of Documentation/arm64/booting.txt in submission: "a7f8de16". Signed-off-by: Fu Wei Signed-off-by: Jonathan Corbet --- Documentation/zh_CN/arm64/booting.txt | 20 ++++++++++++-------- 1 file changed, 12 insertions(+), 8 deletions(-) diff --git a/Documentation/zh_CN/arm64/booting.txt b/Documentation/zh_CN/arm64/booting.txt index 1145bf86408282..c1dd968c5ee927 100644 --- a/Documentation/zh_CN/arm64/booting.txt +++ b/Documentation/zh_CN/arm64/booting.txt @@ -8,7 +8,7 @@ or if there is a problem with the translation. M: Will Deacon zh_CN: Fu Wei -C: 1926e54f115725a9248d0c4c65c22acaf94de4c4 +C: 55f058e7574c3615dea4615573a19bdb258696c6 --------------------------------------------------------------------- Documentation/arm64/booting.txt 的中文翻译 @@ -20,7 +20,7 @@ Documentation/arm64/booting.txt 的中文翻译 中文版维护者： 傅炜 Fu Wei 中文版翻译者： 傅炜 Fu Wei 中文版校译者： 傅炜 Fu Wei -本文翻译提交时的 Git 检出点为： 1926e54f115725a9248d0c4c65c22acaf94de4c4 +本文翻译提交时的 Git 检出点为： 55f058e7574c3615dea4615573a19bdb258696c6 以下为正文 --------------------------------------------------------------------- @@ -125,18 +125,22 @@ AArch64 内核当前没有提供自解压代码，因此如果使用了压缩内 1 - 4K 2 - 16K 3 - 64K - 位 3-63: 保留。 + 位 3: 内核物理位置 + 0 - 2MB 对齐基址应尽量靠近内存起始处，因为 + 其基址以下的内存无法通过线性映射访问 + 1 - 2MB 对齐基址可以在物理内存的任意位置 + 位 4-63: 保留。 - 当 image_size 为零时，引导装载程序应试图在内核映像末尾之后尽可能 多地保留空闲内存供内核直接使用。对内存空间的需求量因所选定的内核 特性而异, 并无实际限制。 -内核映像必须被放置在靠近可用系统内存起始的 2MB 对齐为基址的 -text_offset 字节处，并从该处被调用。当前，对 Linux 来说在此基址以下的 -内存是无法使用的，因此强烈建议将系统内存的起始作为这个基址。2MB 对齐 -基址和内核映像起始地址之间的区域对于内核来说没有特殊意义，且可能被 -用于其他目的。 +内核映像必须被放置在任意一个可用系统内存 2MB 对齐基址的 text_offset +字节处，并从该处被调用。2MB 对齐基址和内核映像起始地址之间的区域对于 +内核来说没有特殊意义，且可能被用于其他目的。 从映像起始地址算起，最少必须准备 image_size 字节的空闲内存供内核使用。 +注： v4.6 之前的版本无法使用内核映像物理偏移以下的内存，所以当时建议 +将映像尽量放置在靠近系统内存起始的地方。 任何提供给内核的内存（甚至在映像起始地址之前），若未从内核中标记为保留 (如在设备树（dtb）的 memreserve 区域），都将被认为对内核是可用。 From 2ea2dc87feb5778f6a4f58dec4ddce695e58e482 Mon Sep 17 00:00:00 2001 From: Alexander Kurz Date: Thu, 21 Apr 2016 19:02:04 +0200 Subject: [PATCH 30/55] Documentation: devres: Add missing INPUT function devm_input_allocate_device() got introduced with commit 2be975c6d920 ("Input: introduce managed input devices (add devres support)"). Add this function to the list of managed interfaces within the devres documentation. Signed-off-by: Alexander Kurz Acked-by: Tejun Heo Signed-off-by: Jonathan Corbet --- Documentation/driver-model/devres.txt | 3 +++ 1 file changed, 3 insertions(+) diff --git a/Documentation/driver-model/devres.txt b/Documentation/driver-model/devres.txt index 73b98dfbcea49a..25e8f3ea3b80b1 100644 --- a/Documentation/driver-model/devres.txt +++ b/Documentation/driver-model/devres.txt @@ -268,6 +268,9 @@ IIO devm_iio_trigger_alloc() devm_iio_trigger_free() +INPUT + devm_input_allocate_device() + IO region devm_release_mem_region() devm_release_region() From 2b4f4f3da6a04ba0f7a4e132a7e646aac3346dbc Mon Sep 17 00:00:00 2001 From: Eric Engestrom Date: Mon, 25 Apr 2016 07:36:53 +0100 Subject: [PATCH 31/55] Documentation: laptops: fix spelling mistake Signed-off-by: Eric Engestrom Signed-off-by: Jonathan Corbet --- Documentation/laptops/toshiba_haps.txt | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Documentation/laptops/toshiba_haps.txt b/Documentation/laptops/toshiba_haps.txt index 11dbcfdc9e7a8a..0c1d88dedbde52 100644 --- a/Documentation/laptops/toshiba_haps.txt +++ b/Documentation/laptops/toshiba_haps.txt @@ -19,7 +19,7 @@ Author: Azael Avalos -------------- This driver provides support for the accelerometer found in various Toshiba -laptops, being called "Toshiba HDD Protection - Shock Sensor" officialy, +laptops, being called "Toshiba HDD Protection - Shock Sensor" officially, and detects laptops automatically with this device. On Windows, Toshiba provided software monitors this device and provides automatic HDD protection (head unload) on sudden moves or harsh vibrations, From 62e153c46f699efa13f5fa4445c2ecc4c5de1ec1 Mon Sep 17 00:00:00 2001 From: Eric Engestrom Date: Mon, 25 Apr 2016 07:36:55 +0100 Subject: [PATCH 32/55] Documentation: lzo: fix spelling mistakes Signed-off-by: Eric Engestrom Signed-off-by: Jonathan Corbet --- Documentation/lzo.txt | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/Documentation/lzo.txt b/Documentation/lzo.txt index ea45dd3901e3bf..285c54f6677913 100644 --- a/Documentation/lzo.txt +++ b/Documentation/lzo.txt @@ -69,9 +69,9 @@ Description IMPORTANT NOTE : in the code some length checks are missing because certain instructions are called under the assumption that a certain number of bytes - follow because it has already been garanteed before parsing the instructions. + follow because it has already been guaranteed before parsing the instructions. They just have to "refill" this credit if they consume extra bytes. This is - an implementation design choice independant on the algorithm or encoding. + an implementation design choice independent on the algorithm or encoding. Byte sequences From c0270efc510e53afd99f35aff0d0251672ae07c3 Mon Sep 17 00:00:00 2001 From: Eric Engestrom Date: Mon, 25 Apr 2016 07:36:58 +0100 Subject: [PATCH 33/55] Documentation: pps: fix spelling mistake Signed-off-by: Eric Engestrom Signed-off-by: Jonathan Corbet --- Documentation/pps/pps.txt | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Documentation/pps/pps.txt b/Documentation/pps/pps.txt index 7cb7264ad59886..50022b3c8ebf99 100644 --- a/Documentation/pps/pps.txt +++ b/Documentation/pps/pps.txt @@ -98,7 +98,7 @@ pps_source_info_s as follows: }; and then calling the function pps_register_source() in your -intialization routine as follows: +initialization routine as follows: source = pps_register_source(&pps_ktimer_info, PPS_CAPTUREASSERT | PPS_OFFSETASSERT); From 86cbbe24b4120aa4813c8519eb2b1506147fe0a0 Mon Sep 17 00:00:00 2001 From: Eric Engestrom Date: Mon, 25 Apr 2016 07:37:00 +0100 Subject: [PATCH 34/55] Documentation: robust-futexes: fix spelling mistakes Signed-off-by: Eric Engestrom Signed-off-by: Jonathan Corbet --- Documentation/robust-futexes.txt | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/Documentation/robust-futexes.txt b/Documentation/robust-futexes.txt index af6fce23e48477..61c22d608759ee 100644 --- a/Documentation/robust-futexes.txt +++ b/Documentation/robust-futexes.txt @@ -126,9 +126,9 @@ vma based method: - no VM changes are needed - 'struct address_space' is left alone. - - no registration of individual locks is needed: robust mutexes dont + - no registration of individual locks is needed: robust mutexes don't need any extra per-lock syscalls. Robust mutexes thus become a very - lightweight primitive - so they dont force the application designer + lightweight primitive - so they don't force the application designer to do a hard choice between performance and robustness - robust mutexes are just as fast. @@ -202,7 +202,7 @@ and the remaining bits are for the TID. Testing, architecture support ----------------------------- -i've tested the new syscalls on x86 and x86_64, and have made sure the +I've tested the new syscalls on x86 and x86_64, and have made sure the parsing of the userspace list is robust [ ;-) ] even if the list is deliberately corrupted. From 1248562b8cd8d6cc2950e165cb426b4f36d29f64 Mon Sep 17 00:00:00 2001 From: Eric Engestrom Date: Mon, 25 Apr 2016 07:37:01 +0100 Subject: [PATCH 35/55] Documentation: scsi: fix spelling mistakes Signed-off-by: Eric Engestrom [jc: fixed trailing whitespace errors] Signed-off-by: Jonathan Corbet --- Documentation/scsi/ChangeLog.megaraid_sas | 48 +++++++++++------------ 1 file changed, 24 insertions(+), 24 deletions(-) diff --git a/Documentation/scsi/ChangeLog.megaraid_sas b/Documentation/scsi/ChangeLog.megaraid_sas index 18b5709900408d..00ffdf187f0b3e 100644 --- a/Documentation/scsi/ChangeLog.megaraid_sas +++ b/Documentation/scsi/ChangeLog.megaraid_sas @@ -63,7 +63,7 @@ Release Date : Sat. Feb 9, 2013 17:00:00 PST 2013 - Current Version : 06.506.00.00-rc1 Old Version : 06.504.01.00-rc1 1. Add 4k FastPath DIF support. - 2. Dont load DevHandle unless FastPath enabled. + 2. Don't load DevHandle unless FastPath enabled. 3. Version and Changelog update. ------------------------------------------------------------------------------- Release Date : Mon. Oct 1, 2012 17:00:00 PST 2012 - @@ -105,7 +105,7 @@ Old Version : 00.00.06.12-rc1 1. Fix reglockFlags for degraded raid5/6 for MR 9360/9380. 2. Mask off flags in ioctl path to prevent memory scribble with older MegaCLI versions. - 3. Remove poll_mode_io module paramater, sysfs node, and associated code. + 3. Remove poll_mode_io module parameter, sysfs node, and associated code. ------------------------------------------------------------------------------- Release Date : Wed. Oct 5, 2011 17:00:00 PST 2010 - (emaild-id:megaraidlinux@lsi.com) @@ -199,7 +199,7 @@ Old Version : 00.00.04.31-rc1 1. Add the Online Controller Reset (OCR) to the Driver. OCR is the new feature for megaraid_sas driver which will allow the fw to do the chip reset which will not - affact the OS behavious. + affect the OS behavior. To add the OCR support, driver need to do: a). reset the controller chips -- Xscale and Gen2 which @@ -233,7 +233,7 @@ Old Version : 00.00.04.31-rc1 failed state. Driver will kill adapter if can't bring back FW after the this three times reset. 4. Add the input parameter max_sectors to 1MB support to our GEN2 controller. - customer can use the input paramenter max_sectors to add 1MB support to GEN2 + customer can use the input parameter max_sectors to add 1MB support to GEN2 controller. 1 Release Date : Thur. Oct 29, 2009 09:12:45 PST 2009 - @@ -582,11 +582,11 @@ ii. Bug fix : Disable controller interrupt before firing INIT cmd to FW. 1 Release Date : Wed Feb 03 14:31:44 PST 2006 - Sumant Patro 2 Current Version : 00.00.02.04 -3 Older Version : 00.00.02.04 +3 Older Version : 00.00.02.04 -i. Remove superflous instance_lock +i. Remove superfluous instance_lock - gets rid of the otherwise superflous instance_lock and avoids an unsave + gets rid of the otherwise superfluous instance_lock and avoids an unsafe unsynchronized access in the error handler. - Christoph Hellwig @@ -594,43 +594,43 @@ i. Remove superflous instance_lock 1 Release Date : Wed Feb 03 14:31:44 PST 2006 - Sumant Patro 2 Current Version : 00.00.02.04 -3 Older Version : 00.00.02.04 +3 Older Version : 00.00.02.04 i. Support for 1078 type (ppc IOP) controller, device id : 0x60 added. - During initialization, depending on the device id, the template members - are initialized with function pointers specific to the ppc or - xscale controllers. + During initialization, depending on the device id, the template members + are initialized with function pointers specific to the ppc or + xscale controllers. -Sumant Patro -1 Release Date : Fri Feb 03 14:16:25 PST 2006 - Sumant Patro +1 Release Date : Fri Feb 03 14:16:25 PST 2006 - Sumant Patro 2 Current Version : 00.00.02.04 -3 Older Version : 00.00.02.02 -i. Register 16 byte CDB capability with scsi midlayer +3 Older Version : 00.00.02.02 +i. Register 16 byte CDB capability with scsi midlayer - "This patch properly registers the 16 byte command length capability of the - megaraid_sas controlled hardware with the scsi midlayer. All megaraid_sas + "This patch properly registers the 16 byte command length capability of the + megaraid_sas controlled hardware with the scsi midlayer. All megaraid_sas hardware supports 16 byte CDB's." - -Joshua Giles + -Joshua Giles 1 Release Date : Mon Jan 23 14:09:01 PST 2006 - Sumant Patro 2 Current Version : 00.00.02.02 -3 Older Version : 00.00.02.01 +3 Older Version : 00.00.02.01 -i. New template defined to represent each family of controllers (identified by processor used). - The template will have defintions that will be initialised to appropritae values for a specific family of controllers. The template definition has four function pointers. During driver initialisation the function pointers will be set based on the controller family type. This change is done to support new controllers that has different processors and thus different register set. +i. New template defined to represent each family of controllers (identified by processor used). + The template will have definitions that will be initialised to appropriate values for a specific family of controllers. The template definition has four function pointers. During driver initialisation the function pointers will be set based on the controller family type. This change is done to support new controllers that has different processors and thus different register set. -Sumant Patro 1 Release Date : Mon Dec 19 14:36:26 PST 2005 - Sumant Patro -2 Current Version : 00.00.02.00-rc4 -3 Older Version : 00.00.02.01 +2 Current Version : 00.00.02.00-rc4 +3 Older Version : 00.00.02.01 -i. Code reorganized to remove code duplication in megasas_build_cmd. +i. Code reorganized to remove code duplication in megasas_build_cmd. - "There's a lot of duplicate code megasas_build_cmd. Move that out of the different codepathes and merge the reminder of megasas_build_cmd into megasas_queue_command" + "There's a lot of duplicate code megasas_build_cmd. Move that out of the different codepaths and merge the reminder of megasas_build_cmd into megasas_queue_command" - Christoph Hellwig From c8e84d2f9bc0021200a11721df0dc987d6191193 Mon Sep 17 00:00:00 2001 From: Eric Engestrom Date: Mon, 25 Apr 2016 07:37:06 +0100 Subject: [PATCH 36/55] Documentation: x86: fix spelling mistakes Signed-off-by: Eric Engestrom Signed-off-by: Jonathan Corbet --- Documentation/x86/intel_mpx.txt | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/Documentation/x86/intel_mpx.txt b/Documentation/x86/intel_mpx.txt index 818518a3ff01a1..1a5a12184a358d 100644 --- a/Documentation/x86/intel_mpx.txt +++ b/Documentation/x86/intel_mpx.txt @@ -136,7 +136,7 @@ A: MPX-enabled application will possibly create a lot of bounds tables in If we were to preallocate them for the 128TB of user virtual address space, we would need to reserve 512TB+2GB, which is larger than the entire virtual address space today. This means they can not be reserved - ahead of time. Also, a single process's pre-popualated bounds directory + ahead of time. Also, a single process's pre-populated bounds directory consumes 2GB of virtual *AND* physical memory. IOW, it's completely infeasible to prepopulate bounds directories. @@ -151,7 +151,7 @@ A: This would work if we could hook the site of each and every memory these calls. Q: Could a bounds fault be handed to userspace and the tables allocated - there in a signal handler intead of in the kernel? + there in a signal handler instead of in the kernel? A: mmap() is not on the list of safe async handler functions and even if mmap() would work it still requires locking or nasty tricks to keep track of the allocation state there. From 715cda787c47458c94b2d012e6e9ab0988409f22 Mon Sep 17 00:00:00 2001 From: Eric Engestrom Date: Mon, 25 Apr 2016 07:37:07 +0100 Subject: [PATCH 37/55] Documentation: xillybus: fix spelling mistake Signed-off-by: Eric Engestrom Signed-off-by: Jonathan Corbet --- Documentation/xillybus.txt | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Documentation/xillybus.txt b/Documentation/xillybus.txt index 81d111b4dc28e1..1660145b9969f3 100644 --- a/Documentation/xillybus.txt +++ b/Documentation/xillybus.txt @@ -215,7 +215,7 @@ in xillybus_core.c as follows: choice is a non-zero value, to match standard UNIX behavior. * synchronous: A non-zero value means that the pipe is synchronous. See - Syncronization above. + Synchronization above. * bufsize: Each DMA buffer's size. Always a power of two. From 14fbff6b4e48a529c90e771598ac12bffd445ff4 Mon Sep 17 00:00:00 2001 From: Arnd Bergmann Date: Mon, 25 Apr 2016 18:03:08 +0200 Subject: [PATCH 38/55] samples: connector: from Documentation to samples directory A small bug with the new autoksyms support showed that there are two kernel modules in the Documentation directory that qualify as samples, while all other samples are in the samples/ directory. This patch was originally meant as a workaround for that bug, but it has now been solved in a different way. However, I still think it makes sense as a cleanup to consolidate all sample code in one place. Signed-off-by: Arnd Bergmann Signed-off-by: Jonathan Corbet --- Documentation/Makefile | 2 +- Documentation/connector/connector.txt | 8 ++++++++ samples/Kconfig | 9 +++++++++ samples/Makefile | 2 +- {Documentation => samples}/connector/.gitignore | 0 {Documentation => samples}/connector/Makefile | 6 +++--- {Documentation => samples}/connector/cn_test.c | 0 {Documentation => samples}/connector/ucon.c | 0 8 files changed, 22 insertions(+), 5 deletions(-) rename {Documentation => samples}/connector/.gitignore (100%) rename {Documentation => samples}/connector/Makefile (76%) rename {Documentation => samples}/connector/cn_test.c (100%) rename {Documentation => samples}/connector/ucon.c (100%) diff --git a/Documentation/Makefile b/Documentation/Makefile index 1207d790765002..13b5ae1b87aa50 100644 --- a/Documentation/Makefile +++ b/Documentation/Makefile @@ -1,4 +1,4 @@ -subdir-y := accounting auxdisplay blackfin connector \ +subdir-y := accounting auxdisplay blackfin \ filesystems filesystems ia64 laptops mic misc-devices \ networking pcmcia prctl ptp timers vDSO video4linux \ watchdog diff --git a/Documentation/connector/connector.txt b/Documentation/connector/connector.txt index f6215f95149b4d..ab7ca897fab7ee 100644 --- a/Documentation/connector/connector.txt +++ b/Documentation/connector/connector.txt @@ -186,3 +186,11 @@ only cn_test.c test module used it. Some work in netlink area is still being done, so things can be changed in 2.6.15 timeframe, if it will happen, documentation will be updated for that kernel. + +/*****************************************/ +Code samples +/*****************************************/ + +Sample code for a connector test module and user space can be found +in samples/connector/. To build this code, enable CONFIG_CONNECTOR +and CONFIG_SAMPLES. diff --git a/samples/Kconfig b/samples/Kconfig index d54f28c6dc5e54..559a58baff6ea5 100644 --- a/samples/Kconfig +++ b/samples/Kconfig @@ -76,4 +76,13 @@ config SAMPLE_CONFIGFS help Builds a sample configfs interface. +config SAMPLE_CONNECTOR + tristate "Build connector sample -- loadable modules only" + depends on CONNECTOR && m + help + When enabled, this builds both a sample kernel module for + the connector interface and a user space tool to communicate + with it. + See also Documentation/connector/connector.txt + endif # SAMPLES diff --git a/samples/Makefile b/samples/Makefile index 48001d7e23f042..594ef7d9fa2ade 100644 --- a/samples/Makefile +++ b/samples/Makefile @@ -2,4 +2,4 @@ obj-$(CONFIG_SAMPLES) += kobject/ kprobes/ trace_events/ livepatch/ \ hw_breakpoint/ kfifo/ kdb/ hidraw/ rpmsg/ seccomp/ \ - configfs/ + configfs/ connector/ diff --git a/Documentation/connector/.gitignore b/samples/connector/.gitignore similarity index 100% rename from Documentation/connector/.gitignore rename to samples/connector/.gitignore diff --git a/Documentation/connector/Makefile b/samples/connector/Makefile similarity index 76% rename from Documentation/connector/Makefile rename to samples/connector/Makefile index d98e4df98e2497..04b9622b6f5150 100644 --- a/Documentation/connector/Makefile +++ b/samples/connector/Makefile @@ -1,9 +1,9 @@ -ifneq ($(CONFIG_CONNECTOR),) -obj-m += cn_test.o -endif +obj-$(CONFIG_SAMPLE_CONNECTOR) += cn_test.o # List of programs to build +ifdef CONFIG_SAMPLE_CONNECTOR hostprogs-y := ucon +endif # Tell kbuild to always build the programs always := $(hostprogs-y) diff --git a/Documentation/connector/cn_test.c b/samples/connector/cn_test.c similarity index 100% rename from Documentation/connector/cn_test.c rename to samples/connector/cn_test.c diff --git a/Documentation/connector/ucon.c b/samples/connector/ucon.c similarity index 100% rename from Documentation/connector/ucon.c rename to samples/connector/ucon.c From 934275c4805ce0bbb0df633bd6015dd455ff6cad Mon Sep 17 00:00:00 2001 From: Arnd Bergmann Date: Mon, 25 Apr 2016 18:03:09 +0200 Subject: [PATCH 39/55] samples: v4l: from Documentation to samples directory A small bug with the new autoksyms support showed that there are two kernel modules in the Documentation directory that qualify as samples, while all other samples are in the samples/ directory. This patch was originally meant as a workaround for that bug, but it has now been solved in a different way. However, I still think it makes sense as a cleanup to consolidate all sample code in one place. Signed-off-by: Arnd Bergmann Acked-by: Hans Verkuil Acked-by: Mauro Carvalho Chehab Signed-off-by: Jonathan Corbet --- Documentation/Makefile | 3 +-- Documentation/video4linux/v4l2-framework.txt | 2 +- samples/Makefile | 2 +- {Documentation/video4linux => samples/v4l}/Makefile | 0 {Documentation/video4linux => samples/v4l}/v4l2-pci-skeleton.c | 0 5 files changed, 3 insertions(+), 4 deletions(-) rename {Documentation/video4linux => samples/v4l}/Makefile (100%) rename {Documentation/video4linux => samples/v4l}/v4l2-pci-skeleton.c (100%) diff --git a/Documentation/Makefile b/Documentation/Makefile index 13b5ae1b87aa50..de955e151af8ee 100644 --- a/Documentation/Makefile +++ b/Documentation/Makefile @@ -1,4 +1,3 @@ subdir-y := accounting auxdisplay blackfin \ filesystems filesystems ia64 laptops mic misc-devices \ - networking pcmcia prctl ptp timers vDSO video4linux \ - watchdog + networking pcmcia prctl ptp timers vDSO watchdog diff --git a/Documentation/video4linux/v4l2-framework.txt b/Documentation/video4linux/v4l2-framework.txt index fa41608ab2b4f4..cbefc7902f5f0e 100644 --- a/Documentation/video4linux/v4l2-framework.txt +++ b/Documentation/video4linux/v4l2-framework.txt @@ -35,7 +35,7 @@ need and this same framework should make it much easier to refactor common code into utility functions shared by all drivers. A good example to look at as a reference is the v4l2-pci-skeleton.c -source that is available in this directory. It is a skeleton driver for +source that is available in samples/v4l/. It is a skeleton driver for a PCI capture card, and demonstrates how to use the V4L2 driver framework. It can be used as a template for real PCI video capture driver. diff --git a/samples/Makefile b/samples/Makefile index 594ef7d9fa2ade..2e3b523d7097cb 100644 --- a/samples/Makefile +++ b/samples/Makefile @@ -2,4 +2,4 @@ obj-$(CONFIG_SAMPLES) += kobject/ kprobes/ trace_events/ livepatch/ \ hw_breakpoint/ kfifo/ kdb/ hidraw/ rpmsg/ seccomp/ \ - configfs/ connector/ + configfs/ connector/ v4l/ diff --git a/Documentation/video4linux/Makefile b/samples/v4l/Makefile similarity index 100% rename from Documentation/video4linux/Makefile rename to samples/v4l/Makefile diff --git a/Documentation/video4linux/v4l2-pci-skeleton.c b/samples/v4l/v4l2-pci-skeleton.c similarity index 100% rename from Documentation/video4linux/v4l2-pci-skeleton.c rename to samples/v4l/v4l2-pci-skeleton.c From 08559657b21522d642331f9dc455a3917d85ab00 Mon Sep 17 00:00:00 2001 From: Kees Cook Date: Tue, 26 Apr 2016 16:41:21 -0700 Subject: [PATCH 40/55] Documentation: fix common spelling mistakes This fixes several spelling mistakes in the Documentation/ tree, which are caught by checkpatch.pl's spell checking. Signed-off-by: Kees Cook Reviewed-by: Paul E. McKenney Acked-by: Randy Dunlap Signed-off-by: Jonathan Corbet --- .../ABI/obsolete/sysfs-driver-hid-roccat-savu | 11 ++++++----- .../testing/sysfs-bus-event_source-devices-hv_24x7 | 2 +- Documentation/ABI/testing/sysfs-driver-hid-picolcd | 2 +- Documentation/ABI/testing/sysfs-firmware-acpi | 2 +- Documentation/DocBook/media/v4l/controls.xml | 2 +- Documentation/DocBook/media/v4l/dev-raw-vbi.xml | 2 +- .../DocBook/media/v4l/vidioc-g-selection.xml | 2 +- Documentation/RCU/RTFP.txt | 6 +++--- Documentation/arm/SA1100/Assabet | 2 +- Documentation/devicetree/bindings/mfd/arizona.txt | 2 +- Documentation/filesystems/cifs/README | 2 +- Documentation/filesystems/pohmelfs/design_notes.txt | 2 +- Documentation/filesystems/qnx6.txt | 2 +- Documentation/firmware_class/README | 2 +- Documentation/hwmon/abituguru | 2 +- Documentation/infiniband/ipoib.txt | 2 +- Documentation/networking/altera_tse.txt | 2 +- Documentation/networking/can.txt | 2 +- Documentation/scsi/bfa.txt | 2 +- Documentation/timers/hrtimers.txt | 2 +- Documentation/video4linux/README.cx88 | 2 +- Documentation/video4linux/bttv/Sound-FAQ | 2 +- Documentation/vm/hugetlbpage.txt | 2 +- 23 files changed, 30 insertions(+), 29 deletions(-) diff --git a/Documentation/ABI/obsolete/sysfs-driver-hid-roccat-savu b/Documentation/ABI/obsolete/sysfs-driver-hid-roccat-savu index f1e02a98bd9ddb..99fda67fce18df 100644 --- a/Documentation/ABI/obsolete/sysfs-driver-hid-roccat-savu +++ b/Documentation/ABI/obsolete/sysfs-driver-hid-roccat-savu @@ -3,9 +3,10 @@ Date: Mai 2012 Contact: Stefan Achatz Description: The mouse can store 5 profiles which can be switched by the press of a button. A profile is split into general settings and - button settings. buttons holds informations about button layout. - When written, this file lets one write the respective profile - buttons to the mouse. The data has to be 47 bytes long. + button settings. The buttons variable holds information about + button layout. When written, this file lets one write the + respective profile buttons to the mouse. The data has to be + 47 bytes long. The mouse will reject invalid data. Which profile to write is determined by the profile number contained in the data. @@ -26,8 +27,8 @@ Date: Mai 2012 Contact: Stefan Achatz Description: The mouse can store 5 profiles which can be switched by the press of a button. A profile is split into general settings and - button settings. profile holds informations like resolution, sensitivity - and light effects. + button settings. A profile holds information like resolution, + sensitivity and light effects. When written, this file lets one write the respective profile settings back to the mouse. The data has to be 43 bytes long. The mouse will reject invalid data. diff --git a/Documentation/ABI/testing/sysfs-bus-event_source-devices-hv_24x7 b/Documentation/ABI/testing/sysfs-bus-event_source-devices-hv_24x7 index f893337570c1b4..ec27c6c9e7377a 100644 --- a/Documentation/ABI/testing/sysfs-bus-event_source-devices-hv_24x7 +++ b/Documentation/ABI/testing/sysfs-bus-event_source-devices-hv_24x7 @@ -4,7 +4,7 @@ Contact: Linux on PowerPC Developer List Description: Provides access to the binary "24x7 catalog" provided by the hypervisor on POWER7 and 8 systems. This catalog lists events - avaliable from the powerpc "hv_24x7" pmu. Its format is + available from the powerpc "hv_24x7" pmu. Its format is documented here: https://raw.githubusercontent.com/jmesmon/catalog-24x7/master/hv-24x7-catalog.h diff --git a/Documentation/ABI/testing/sysfs-driver-hid-picolcd b/Documentation/ABI/testing/sysfs-driver-hid-picolcd index 08579e7e1e8943..98fd81ad76a17a 100644 --- a/Documentation/ABI/testing/sysfs-driver-hid-picolcd +++ b/Documentation/ABI/testing/sysfs-driver-hid-picolcd @@ -39,5 +39,5 @@ Description: Make it possible to adjust defio refresh rate. Note: As device can barely do 2 complete refreshes a second it only makes sense to adjust this value if only one or two tiles get changed and it's not appropriate to expect the application - to flush it's tiny changes explicitely at higher than default rate. + to flush its tiny changes explicitly at higher than default rate. diff --git a/Documentation/ABI/testing/sysfs-firmware-acpi b/Documentation/ABI/testing/sysfs-firmware-acpi index b4436cca97a836..c7fc72d4495ca0 100644 --- a/Documentation/ABI/testing/sysfs-firmware-acpi +++ b/Documentation/ABI/testing/sysfs-firmware-acpi @@ -169,7 +169,7 @@ Description: to enable/disable/clear ACPI interrupts in user space, which can be used to debug some ACPI interrupt storm issues. - Note that only writting to VALID GPE/Fixed Event is allowed, + Note that only writing to VALID GPE/Fixed Event is allowed, i.e. user can only change the status of runtime GPE and Fixed Event with event handler installed. diff --git a/Documentation/DocBook/media/v4l/controls.xml b/Documentation/DocBook/media/v4l/controls.xml index 361040e6b0f41a..f5f5ce8badac63 100644 --- a/Documentation/DocBook/media/v4l/controls.xml +++ b/Documentation/DocBook/media/v4l/controls.xml @@ -2841,7 +2841,7 @@ for a GOP and keep it below or equal the set bitrate target. Otherwise the rate overall average bitrate for the stream and keeps it below or equal to the set bitrate. In the first case the average bitrate for the whole stream will be smaller then the set bitrate. This is caused because the average is calculated for smaller number of frames, on the other hand enabling this setting will ensure that -the stream will meet tight bandwidth contraints. Applicable to encoders. +the stream will meet tight bandwidth constraints. Applicable to encoders. diff --git a/Documentation/DocBook/media/v4l/dev-raw-vbi.xml b/Documentation/DocBook/media/v4l/dev-raw-vbi.xml index f4b61b6ce3c25c..78599bbd58f7bf 100644 --- a/Documentation/DocBook/media/v4l/dev-raw-vbi.xml +++ b/Documentation/DocBook/media/v4l/dev-raw-vbi.xml @@ -85,7 +85,7 @@ initialize all fields of the &v4l2-vbi-format; results of VIDIOC_G_FMT, and call the &VIDIOC-S-FMT; ioctl with a pointer to this structure. Drivers return an &EINVAL; only when the given parameters are ambiguous, otherwise -they modify the parameters according to the hardware capabilites and +they modify the parameters according to the hardware capabilities and return the actual parameters. When the driver allocates resources at this point, it may return an &EBUSY; to indicate the returned parameters are valid but the required resources are currently not diff --git a/Documentation/DocBook/media/v4l/vidioc-g-selection.xml b/Documentation/DocBook/media/v4l/vidioc-g-selection.xml index 7865351688dab0..a9c0d1dc209a06 100644 --- a/Documentation/DocBook/media/v4l/vidioc-g-selection.xml +++ b/Documentation/DocBook/media/v4l/vidioc-g-selection.xml @@ -222,7 +222,7 @@ or the flags argument is not valid. ERANGE It is not possible to adjust &v4l2-rect; -r rectangle to satisfy all contraints given in the +r rectangle to satisfy all constraints given in the flags argument. diff --git a/Documentation/RCU/RTFP.txt b/Documentation/RCU/RTFP.txt index 370ca006db7a05..9bccf16736f78d 100644 --- a/Documentation/RCU/RTFP.txt +++ b/Documentation/RCU/RTFP.txt @@ -176,13 +176,13 @@ a history of how Linux changed RCU more than RCU changed Linux which Mathieu Desnoyers is now maintaining [MathieuDesnoyers2009URCU] [MathieuDesnoyersPhD]. TINY_RCU [PaulEMcKenney2009BloatWatchRCU] made its appearance, as did expedited RCU [PaulEMcKenney2009expeditedRCU]. -The problem of resizeable RCU-protected hash tables may now be on a path +The problem of resizable RCU-protected hash tables may now be on a path to a solution [JoshTriplett2009RPHash]. A few academic researchers are now using RCU to solve their parallel problems [HariKannan2009DynamicAnalysisRCU]. 2010 produced a simpler preemptible-RCU implementation based on TREE_RCU [PaulEMcKenney2010SimpleOptRCU], lockdep-RCU -[PaulEMcKenney2010LockdepRCU], another resizeable RCU-protected hash +[PaulEMcKenney2010LockdepRCU], another resizable RCU-protected hash table [HerbertXu2010RCUResizeHash] (this one consuming more memory, but allowing arbitrary changes in hash function, as required for DoS avoidance in the networking code), realization of the 2009 RCU-protected @@ -193,7 +193,7 @@ the RCU API [PaulEMcKenney2010RCUAPI]. [LinusTorvalds2011Linux2:6:38:rc1:NPigginVFS], an RCU-protected red-black tree using software transactional memory to protect concurrent updates (strange, but true!) [PhilHoward2011RCUTMRBTree], yet another variant of -RCU-protected resizeable hash tables [Triplett:2011:RPHash], the 3.0 RCU +RCU-protected resizable hash tables [Triplett:2011:RPHash], the 3.0 RCU trainwreck [PaulEMcKenney2011RCU3.0trainwreck], and Neil Brown's "Meet the Lockers" LWN article [NeilBrown2011MeetTheLockers]. Some academic work looked at debugging uses of RCU [Seyster:2011:RFA:2075416.2075425]. diff --git a/Documentation/arm/SA1100/Assabet b/Documentation/arm/SA1100/Assabet index 08b885d35674aa..e08a6739e72c6e 100644 --- a/Documentation/arm/SA1100/Assabet +++ b/Documentation/arm/SA1100/Assabet @@ -214,7 +214,7 @@ RedBoot scripting ----------------- All the commands above aren't so useful if they have to be typed in every -time the Assabet is rebooted. Therefore it's possible to automatize the boot +time the Assabet is rebooted. Therefore it's possible to automate the boot process using RedBoot's scripting capability. For example, I use this to boot Linux with both the kernel and the ramdisk diff --git a/Documentation/devicetree/bindings/mfd/arizona.txt b/Documentation/devicetree/bindings/mfd/arizona.txt index 9b30011ecabe76..a6e2ea41160cf2 100644 --- a/Documentation/devicetree/bindings/mfd/arizona.txt +++ b/Documentation/devicetree/bindings/mfd/arizona.txt @@ -1,6 +1,6 @@ Cirrus Logic/Wolfson Microelectronics Arizona class audio SoCs -These devices are audio SoCs with extensive digital capabilites and a range +These devices are audio SoCs with extensive digital capabilities and a range of analogue I/O. Required properties: diff --git a/Documentation/filesystems/cifs/README b/Documentation/filesystems/cifs/README index 2d5622f60e1121..a54788405429dc 100644 --- a/Documentation/filesystems/cifs/README +++ b/Documentation/filesystems/cifs/README @@ -272,7 +272,7 @@ A partial list of the supported mount options follows: same domain (e.g. running winbind or nss_ldap) and the server supports the Unix Extensions then the uid and gid can be retrieved from the server (and uid - and gid would not have to be specifed on the mount. + and gid would not have to be specified on the mount. For servers which do not support the CIFS Unix extensions, the default uid (and gid) returned on lookup of existing files will be the uid (gid) of the person diff --git a/Documentation/filesystems/pohmelfs/design_notes.txt b/Documentation/filesystems/pohmelfs/design_notes.txt index 8aef91335701ce..106d17fbb05fd0 100644 --- a/Documentation/filesystems/pohmelfs/design_notes.txt +++ b/Documentation/filesystems/pohmelfs/design_notes.txt @@ -29,7 +29,7 @@ Main features of this FS include: * Read request (data read, directory listing, lookup requests) balancing between multiple servers. * Write requests are replicated to multiple servers and completed only when all of them are acked. * Ability to add and/or remove servers from the working set at run-time. - * Strong authentification and possible data encryption in network channel. + * Strong authentication and possible data encryption in network channel. * Extended attributes support. POHMELFS is based on transactions, which are potentially long-standing objects that live diff --git a/Documentation/filesystems/qnx6.txt b/Documentation/filesystems/qnx6.txt index 408679789136c1..4f3d6a882bdc0d 100644 --- a/Documentation/filesystems/qnx6.txt +++ b/Documentation/filesystems/qnx6.txt @@ -16,7 +16,7 @@ qnx6fs shares many properties with traditional Unix filesystems. It has the concepts of blocks, inodes and directories. On QNX it is possible to create little endian and big endian qnx6 filesystems. This feature makes it possible to create and use a different endianness fs -for the target (QNX is used on quite a range of embedded systems) plattform +for the target (QNX is used on quite a range of embedded systems) platform running on a different endianness. The Linux driver handles endianness transparently. (LE and BE) diff --git a/Documentation/firmware_class/README b/Documentation/firmware_class/README index 71f86859d7d849..cafdca8b3b1596 100644 --- a/Documentation/firmware_class/README +++ b/Documentation/firmware_class/README @@ -20,7 +20,7 @@ 1), kernel(driver): - calls request_firmware(&fw_entry, $FIRMWARE, device) - - kernel searchs the fimware image with name $FIRMWARE directly + - kernel searches the firmware image with name $FIRMWARE directly in the below search path of root filesystem: User customized search path by module parameter 'path'[1] "/lib/firmware/updates/" UTS_RELEASE, diff --git a/Documentation/hwmon/abituguru b/Documentation/hwmon/abituguru index 915f32063a261f..f1d4fe4c366c48 100644 --- a/Documentation/hwmon/abituguru +++ b/Documentation/hwmon/abituguru @@ -25,7 +25,7 @@ Supported chips: 1) For revisions 2 and 3 uGuru's the driver can autodetect the sensortype (Volt or Temp) for bank1 sensors, for revision 1 uGuru's this doesnot always work. For these uGuru's the autodection can - be overriden with the bank1_types module param. For all 3 known + be overridden with the bank1_types module param. For all 3 known revison 1 motherboards the correct use of this param is: bank1_types=1,1,0,0,0,0,0,2,0,0,0,0,2,0,0,1 You may also need to specify the fan_sensors option for these boards diff --git a/Documentation/infiniband/ipoib.txt b/Documentation/infiniband/ipoib.txt index f2cfe265e836e0..47c1dd9818f2e5 100644 --- a/Documentation/infiniband/ipoib.txt +++ b/Documentation/infiniband/ipoib.txt @@ -25,7 +25,7 @@ Partitions and P_Keys main interface for a subinterface is in "parent." Child interface create/delete can also be done using IPoIB's - rtnl_link_ops, where childs created using either way behave the same. + rtnl_link_ops, where children created using either way behave the same. Datagram vs Connected modes diff --git a/Documentation/networking/altera_tse.txt b/Documentation/networking/altera_tse.txt index 3f24df8c6e6557..cd417d7b5bd440 100644 --- a/Documentation/networking/altera_tse.txt +++ b/Documentation/networking/altera_tse.txt @@ -6,7 +6,7 @@ This is the driver for the Altera Triple-Speed Ethernet (TSE) controllers using the SGDMA and MSGDMA soft DMA IP components. The driver uses the platform bus to obtain component resources. The designs used to test this driver were built for a Cyclone(R) V SOC FPGA board, a Cyclone(R) V FPGA board, -and tested with ARM and NIOS processor hosts seperately. The anticipated use +and tested with ARM and NIOS processor hosts separately. The anticipated use cases are simple communications between an embedded system and an external peer for status and simple configuration of the embedded system. diff --git a/Documentation/networking/can.txt b/Documentation/networking/can.txt index 6ab619fcc5175a..d58ff8467953a2 100644 --- a/Documentation/networking/can.txt +++ b/Documentation/networking/can.txt @@ -1256,7 +1256,7 @@ solution for a couple of reasons: 7. SocketCAN resources ----------------------- - The Linux CAN / SocketCAN project ressources (project site / mailing list) + The Linux CAN / SocketCAN project resources (project site / mailing list) are referenced in the MAINTAINERS file in the Linux source tree. Search for CAN NETWORK [LAYERS|DRIVERS]. diff --git a/Documentation/scsi/bfa.txt b/Documentation/scsi/bfa.txt index f2d6e9d1791ed9..3cc4d80d6092da 100644 --- a/Documentation/scsi/bfa.txt +++ b/Documentation/scsi/bfa.txt @@ -50,7 +50,7 @@ be found at: http://www.brocade.com/services-support/drivers-downloads/adapters/Linux.page -and then click following respective util pacakge link +and then click following respective util package link Version Link diff --git a/Documentation/timers/hrtimers.txt b/Documentation/timers/hrtimers.txt index 492f1affb0e580..588d85724f1088 100644 --- a/Documentation/timers/hrtimers.txt +++ b/Documentation/timers/hrtimers.txt @@ -119,7 +119,7 @@ was not really a win, due to the different data structures. Also, the hrtimer functions now have clearer behavior and clearer names - such as hrtimer_try_to_cancel() and hrtimer_cancel() [which are roughly equivalent to del_timer() and del_timer_sync()] - so there's no direct -1:1 mapping between them on the algorithmical level, and thus no real +1:1 mapping between them on the algorithmic level, and thus no real potential for code sharing either. Basic data types: every time value, absolute or relative, is in a diff --git a/Documentation/video4linux/README.cx88 b/Documentation/video4linux/README.cx88 index 35fae23f883b60..b09ce36b921e58 100644 --- a/Documentation/video4linux/README.cx88 +++ b/Documentation/video4linux/README.cx88 @@ -50,7 +50,7 @@ the driver. What to do then? cx88-cards.c. If that worked, mail me your changes as unified diff ("diff -u"). (3) Or you can mail me the config information. I need at least the - following informations to add the card: + following information to add the card: * the PCI Subsystem ID ("0070:3400" from the line above, "lspci -v" output is fine too). diff --git a/Documentation/video4linux/bttv/Sound-FAQ b/Documentation/video4linux/bttv/Sound-FAQ index d3f1d7783d1ccd..646a47de001642 100644 --- a/Documentation/video4linux/bttv/Sound-FAQ +++ b/Documentation/video4linux/bttv/Sound-FAQ @@ -55,7 +55,7 @@ receiver chips. Some boards use the i2c bus instead of the gpio pins to connect the mux chip. As mentioned above, there is a array which holds the required -informations for each known board. You basically have to create a new +information for each known board. You basically have to create a new line for your board. The important fields are these two: struct tvcard diff --git a/Documentation/vm/hugetlbpage.txt b/Documentation/vm/hugetlbpage.txt index 54dd9b9c6c31ae..b7a3f6d6cfc1cc 100644 --- a/Documentation/vm/hugetlbpage.txt +++ b/Documentation/vm/hugetlbpage.txt @@ -220,7 +220,7 @@ resulting effect on persistent huge page allocation is as follows: node list of "all" with numactl --interleave or --membind [-m] to achieve interleaving over all nodes in the system or cpuset. -4) Any task mempolicy specifed--e.g., using numactl--will be constrained by +4) Any task mempolicy specified--e.g., using numactl--will be constrained by the resource limits of any cpuset in which the task runs. Thus, there will be no way for a task with non-default policy running in a cpuset with a subset of the system nodes to allocate huge pages outside the cpuset From 2fd872bd84b3aa1a177a66a8d14bd25f68f373f0 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Ren=C3=A9=20Nyffenegger?= Date: Thu, 28 Apr 2016 10:15:24 +0200 Subject: [PATCH 41/55] Doc: correct the location of sysrq.c MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit sysrq.c moved to drivers/tty in 2010; update the documentation to match. Signed-off-by: René Nyffenegger Signed-off-by: Jonathan Corbet --- Documentation/sysrq.txt | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Documentation/sysrq.txt b/Documentation/sysrq.txt index 13f5619b2203e6..3a3b30ac2a755d 100644 --- a/Documentation/sysrq.txt +++ b/Documentation/sysrq.txt @@ -212,7 +212,7 @@ 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/char/sysrq.c'. This key table has +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. From fadc0b31cba0bb56bce1a3259cc60e4d7ee67333 Mon Sep 17 00:00:00 2001 From: Jani Nikula Date: Thu, 12 May 2016 16:15:36 +0300 Subject: [PATCH 42/55] kernel-doc: rewrite usage description, remove duplicated comments Instead of having the kernel-doc usage in both comments and in output to the user, merge them all to one here document. While at it, imrove the text and make it pretty. Give shoemaker's children some shoes. Signed-off-by: Jani Nikula Signed-off-by: Jonathan Corbet --- scripts/kernel-doc | 83 +++++++++++++++++++++------------------------- 1 file changed, 37 insertions(+), 46 deletions(-) diff --git a/scripts/kernel-doc b/scripts/kernel-doc index c37255bb620d40..29fd5cabb6576a 100755 --- a/scripts/kernel-doc +++ b/scripts/kernel-doc @@ -39,41 +39,43 @@ use strict; # 25/07/2012 - Added support for HTML5 # -- Dan Luedtke -# -# This will read a 'c' file and scan for embedded comments in the -# style of gnome comments (+minor extensions - see below). -# - -# Note: This only supports 'c'. - -# usage: -# kernel-doc [ -docbook | -html | -html5 | -text | -man | -list ] -# [ -no-doc-sections ] -# [ -function funcname [ -function funcname ...] ] -# c file(s)s > outputfile -# or -# [ -nofunction funcname [ -function funcname ...] ] -# c file(s)s > outputfile -# -# Set output format using one of -docbook -html -html5 -text or -man. -# Default is man. -# The -list format is for internal use by docproc. -# -# -no-doc-sections -# Do not output DOC: sections -# -# -function funcname -# If set, then only generate documentation for the given function(s) or -# DOC: section titles. All other functions and DOC: sections are ignored. -# -# -nofunction funcname -# If set, then only generate documentation for the other function(s)/DOC: -# sections. Cannot be used together with -function (yes, that's a bug -- -# perl hackers can fix it 8)) -# -# c files - list of 'c' files to process -# -# All output goes to stdout, with errors to stderr. +sub usage { + my $message = <<"EOF"; +Usage: $0 [OPTION ...] FILE ... + +Read C language source or header FILEs, extract embedded documentation comments, +and print formatted documentation to standard output. + +The documentation comments are identified by "/**" opening comment mark. See +Documentation/kernel-doc-nano-HOWTO.txt for the documentation comment syntax. + +Output format selection (mutually exclusive): + -docbook Output DocBook format. + -html Output HTML format. + -html5 Output HTML5 format. + -list Output symbol list format. This is for use by docproc. + -man Output troff manual page format. This is the default. + -text Output plain text format. + +Output selection (mutually exclusive): + -function NAME Only output documentation for the given function(s) + or DOC: section title(s). All other functions and DOC: + sections are ignored. May be specified multiple times. + -nofunction NAME Do NOT output documentation for the given function(s); + only output documentation for the other functions and + DOC: sections. May be specified multiple times. + +Output selection modifiers: + -no-doc-sections Do not output DOC: sections. + +Other parameters: + -v Verbose output, more warnings and other information. + -h Print this help. + +EOF + print $message; + exit 1; +} # # format of comments. @@ -437,17 +439,6 @@ while ($ARGV[0] =~ m/^-(.*)/) { # continue execution near EOF; -sub usage { - print "Usage: $0 [ -docbook | -html | -html5 | -text | -man | -list ]\n"; - print " [ -no-doc-sections ]\n"; - print " [ -function funcname [ -function funcname ...] ]\n"; - print " [ -nofunction funcname [ -nofunction funcname ...] ]\n"; - print " [ -v ]\n"; - print " c source file(s) > outputfile\n"; - print " -v : verbose output, more warnings & other info listed\n"; - exit 1; -} - # get kernel version from env sub get_kernel_version() { my $version = 'unknown kernel version'; From c0d1b6ee780ab16f16cdbe046aa9c83a2a31f9e2 Mon Sep 17 00:00:00 2001 From: Jonathan Corbet Date: Thu, 12 May 2016 16:15:37 +0300 Subject: [PATCH 43/55] kernel-doc: produce RestructuredText output If given the -rst flag, output will now be in RestructuredText. Various glitches to be worked out yet. In the end I decided not to use RST section headings within the kerneldoc comments. gpu.tmpl already has headings five levels deep; adding more is not going to bring clarity. This is really just Jani Nikula's asciidoc change with the serial numbers filed off. It's a hack job that doubtless needs a lot of cleaning up. Signed-off-by: Jonathan Corbet Signed-off-by: Jani Nikula Signed-off-by: Jonathan Corbet --- scripts/kernel-doc | 233 +++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 233 insertions(+) diff --git a/scripts/kernel-doc b/scripts/kernel-doc index 29fd5cabb6576a..0ad1fb0e30313b 100755 --- a/scripts/kernel-doc +++ b/scripts/kernel-doc @@ -55,6 +55,7 @@ Output format selection (mutually exclusive): -html5 Output HTML5 format. -list Output symbol list format. This is for use by docproc. -man Output troff manual page format. This is the default. + -rst Output reStructuredText format. -text Output plain text format. Output selection (mutually exclusive): @@ -203,6 +204,8 @@ my $type_param = '\@(\w+)'; my $type_struct = '\&((struct\s*)*[_\w]+)'; my $type_struct_xml = '\\&((struct\s*)*[_\w]+)'; my $type_env = '(\$\w+)'; +my $type_enum_full = '\&(enum)\s*([_\w]+)'; +my $type_struct_full = '\&(struct)\s*([_\w]+)'; # Output conversion substitutions. # One for each output format @@ -268,6 +271,17 @@ my @highlights_text = ( ); my $blankline_text = ""; +# rst-mode +my @highlights_rst = ( + [$type_constant, "``\$1``"], + [$type_func, "\\:c\\:func\\:`\$1`"], + [$type_struct_full, "\\:ref\\:`\$1 \$2`"], + [$type_enum_full, "\\:ref\\:`\$1 \$2`"], + [$type_struct, "\\:ref\\:`struct \$1`"], + [$type_param, "**\$1**"] + ); +my $blankline_rst = "\n"; + # list mode my @highlights_list = ( [$type_constant, "\$1"], @@ -404,6 +418,10 @@ while ($ARGV[0] =~ m/^-(.*)/) { $output_mode = "text"; @highlights = @highlights_text; $blankline = $blankline_text; + } elsif ($cmd eq "-rst") { + $output_mode = "rst"; + @highlights = @highlights_rst; + $blankline = $blankline_rst; } elsif ($cmd eq "-docbook") { $output_mode = "xml"; @highlights = @highlights_xml; @@ -1704,6 +1722,209 @@ sub output_blockhead_text(%) { } } +## +# output in restructured text +# + +# +# This could use some work; it's used to output the DOC: sections, and +# starts by putting out the name of the doc section itself, but that tends +# to duplicate a header already in the template file. +# +sub output_blockhead_rst(%) { + my %args = %{$_[0]}; + my ($parameter, $section); + + foreach $section (@{$args{'sectionlist'}}) { + print "**$section**\n\n"; + output_highlight_rst($args{'sections'}{$section}); + print "\n"; + } +} + +sub output_highlight_rst { + my $contents = join "\n",@_; + my $line; + + # undo the evil effects of xml_escape() earlier + $contents = xml_unescape($contents); + + eval $dohighlight; + die $@ if $@; + + foreach $line (split "\n", $contents) { + if ($line eq "") { + print $lineprefix, $blankline; + } else { + $line =~ s/\\\\\\/\&/g; + print $lineprefix, $line; + } + print "\n"; + } +} + +sub output_function_rst(%) { + my %args = %{$_[0]}; + my ($parameter, $section); + my $start; + + print ".. c:function:: "; + if ($args{'functiontype'} ne "") { + $start = $args{'functiontype'} . " " . $args{'function'} . " ("; + } else { + $start = $args{'function'} . " ("; + } + print $start; + + my $count = 0; + foreach my $parameter (@{$args{'parameterlist'}}) { + if ($count ne 0) { + print ", "; + } + $count++; + $type = $args{'parametertypes'}{$parameter}; + if ($type =~ m/([^\(]*\(\*)\s*\)\s*\(([^\)]*)\)/) { + # pointer-to-function + print $1 . $parameter . ") (" . $2; + } else { + print $type . " " . $parameter; + } + } + print ")\n\n " . $args{'purpose'} . "\n\n"; + + print ":Parameters:\n\n"; + foreach $parameter (@{$args{'parameterlist'}}) { + my $parameter_name = $parameter; + #$parameter_name =~ s/\[.*//; + $type = $args{'parametertypes'}{$parameter}; + + if ($type ne "") { + print " ``$type $parameter``\n"; + } else { + print " ``$parameter``\n"; + } + if ($args{'parameterdescs'}{$parameter_name} ne $undescribed) { + my $oldprefix = $lineprefix; + $lineprefix = " "; + output_highlight_rst($args{'parameterdescs'}{$parameter_name}); + $lineprefix = $oldprefix; + } else { + print "\n _undescribed_\n"; + } + print "\n"; + } + output_section_rst(@_); +} + +sub output_section_rst(%) { + my %args = %{$_[0]}; + my $section; + my $oldprefix = $lineprefix; + $lineprefix = " "; + + foreach $section (@{$args{'sectionlist'}}) { + print ":$section:\n\n"; + output_highlight_rst($args{'sections'}{$section}); + print "\n"; + } + print "\n"; + $lineprefix = $oldprefix; +} + +sub output_enum_rst(%) { + my %args = %{$_[0]}; + my ($parameter); + my $count; + + my $name = "enum " . $args{'enum'}; + print ".. _" . $name . ":\n\n"; + print "**$name**\n\n"; + print " " . $args{'purpose'} . "\n\n"; + + print "..\n\n:Constants:\n\n"; + my $oldprefix = $lineprefix; + $lineprefix = " "; + foreach $parameter (@{$args{'parameterlist'}}) { + print " `$parameter`\n"; + if ($args{'parameterdescs'}{$parameter} ne $undescribed) { + output_highlight_rst($args{'parameterdescs'}{$parameter}); + } else { + print " undescribed\n"; + } + print "\n"; + } + $lineprefix = $oldprefix; + output_section_rst(@_); +} + +sub output_typedef_rst(%) { + my %args = %{$_[0]}; + my ($parameter); + my $count; + my $name = "typedef " . $args{'typedef'}; + + print "**$name**\n\n"; + print $args{'purpose'} . "\n\n"; + + output_section_rst(@_); +} + +sub output_struct_rst(%) { + my %args = %{$_[0]}; + my ($parameter); + my $name = $args{'type'} . " " . $args{'struct'}; + + print ".. _" . $name . ":\n\n"; + print "**$name**\n\n"; + print " " . $args{'purpose'} . "\n\n"; + + print ":Definition:\n\n"; + print " ::\n\n"; + print " " . $args{'type'} . " " . $args{'struct'} . " {\n"; + foreach $parameter (@{$args{'parameterlist'}}) { + if ($parameter =~ /^#/) { + print " " . "$parameter\n"; + next; + } + + my $parameter_name = $parameter; + $parameter_name =~ s/\[.*//; + + ($args{'parameterdescs'}{$parameter_name} ne $undescribed) || next; + $type = $args{'parametertypes'}{$parameter}; + if ($type =~ m/([^\(]*\(\*)\s*\)\s*\(([^\)]*)\)/) { + # pointer-to-function + print " $1 $parameter) ($2);\n"; + } elsif ($type =~ m/^(.*?)\s*(:.*)/) { + # bitfield + print " $1 $parameter$2;\n"; + } else { + print " " . $type . " " . $parameter . ";\n"; + } + } + print " };\n\n"; + + print ":Members:\n\n"; + foreach $parameter (@{$args{'parameterlist'}}) { + ($parameter =~ /^#/) && next; + + my $parameter_name = $parameter; + $parameter_name =~ s/\[.*//; + + ($args{'parameterdescs'}{$parameter_name} ne $undescribed) || next; + $type = $args{'parametertypes'}{$parameter}; + print " `$type $parameter`" . "\n"; + my $oldprefix = $lineprefix; + $lineprefix = " "; + output_highlight_rst($args{'parameterdescs'}{$parameter_name}); + $lineprefix = $oldprefix; + print "\n"; + } + print "\n"; + output_section_rst(@_); +} + + ## list mode output functions sub output_function_list(%) { @@ -2405,6 +2626,18 @@ sub xml_escape($) { return $text; } +# xml_unescape: reverse the effects of xml_escape +sub xml_unescape($) { + my $text = shift; + if (($output_mode eq "text") || ($output_mode eq "man")) { + return $text; + } + $text =~ s/\\\\\\amp;/\&/g; + $text =~ s/\\\\\\lt;//g; + return $text; +} + # convert local escape strings to html # local escape strings look like: '\\\\menmonic:' (that's 4 backslashes) sub local_unescape($) { From 6285097654725f39357527b553d03b70bfbaf4d2 Mon Sep 17 00:00:00 2001 From: Jani Nikula Date: Thu, 12 May 2016 16:15:38 +0300 Subject: [PATCH 44/55] kernel-doc: use rst C domain directives and references for types First, the headings for structs, enums and typedefs will be similar to functions. Second, this provides a kind of namespace for cross references. Third, and most importantly, the return and parameter types from .. c:function:: definitions will automagically become cross references to the documented types. Signed-off-by: Jani Nikula Signed-off-by: Jonathan Corbet --- scripts/kernel-doc | 19 +++++++++---------- 1 file changed, 9 insertions(+), 10 deletions(-) diff --git a/scripts/kernel-doc b/scripts/kernel-doc index 0ad1fb0e30313b..2fc8fad5195e89 100755 --- a/scripts/kernel-doc +++ b/scripts/kernel-doc @@ -275,9 +275,9 @@ my $blankline_text = ""; my @highlights_rst = ( [$type_constant, "``\$1``"], [$type_func, "\\:c\\:func\\:`\$1`"], - [$type_struct_full, "\\:ref\\:`\$1 \$2`"], - [$type_enum_full, "\\:ref\\:`\$1 \$2`"], - [$type_struct, "\\:ref\\:`struct \$1`"], + [$type_struct_full, "\\:c\\:type\\:`\$1 \$2 <\$2>`"], + [$type_enum_full, "\\:c\\:type\\:`\$1 \$2 <\$2>`"], + [$type_struct, "\\:c\\:type\\:`struct \$1 <\$1>`"], [$type_param, "**\$1**"] ); my $blankline_rst = "\n"; @@ -1835,10 +1835,9 @@ sub output_enum_rst(%) { my %args = %{$_[0]}; my ($parameter); my $count; - my $name = "enum " . $args{'enum'}; - print ".. _" . $name . ":\n\n"; - print "**$name**\n\n"; + + print "\n\n.. c:type:: " . $name . "\n\n"; print " " . $args{'purpose'} . "\n\n"; print "..\n\n:Constants:\n\n"; @@ -1863,8 +1862,9 @@ sub output_typedef_rst(%) { my $count; my $name = "typedef " . $args{'typedef'}; - print "**$name**\n\n"; - print $args{'purpose'} . "\n\n"; + ### FIXME: should the name below contain "typedef" or not? + print "\n\n.. c:type:: " . $name . "\n\n"; + print " " . $args{'purpose'} . "\n\n"; output_section_rst(@_); } @@ -1874,8 +1874,7 @@ sub output_struct_rst(%) { my ($parameter); my $name = $args{'type'} . " " . $args{'struct'}; - print ".. _" . $name . ":\n\n"; - print "**$name**\n\n"; + print "\n\n.. c:type:: " . $name . "\n\n"; print " " . $args{'purpose'} . "\n\n"; print ":Definition:\n\n"; From 568fb2dec9c68bb38c2a1ad01fb3d4dd41488115 Mon Sep 17 00:00:00 2001 From: Jani Nikula Date: Thu, 12 May 2016 16:15:39 +0300 Subject: [PATCH 45/55] docproc: add variables for subcommand and filename Improves clarity. No functional changes. Signed-off-by: Jani Nikula Signed-off-by: Jonathan Corbet --- scripts/docproc.c | 17 +++++++++++------ 1 file changed, 11 insertions(+), 6 deletions(-) diff --git a/scripts/docproc.c b/scripts/docproc.c index e267e621431a6b..48abc01a920e0c 100644 --- a/scripts/docproc.c +++ b/scripts/docproc.c @@ -500,6 +500,7 @@ static void parse_file(FILE *infile) int main(int argc, char *argv[]) { + const char *subcommand, *filename; FILE * infile; int i; @@ -513,15 +514,19 @@ int main(int argc, char *argv[]) usage(); exit(1); } + + subcommand = argv[1]; + filename = argv[2]; + /* Open file, exit on error */ - infile = fopen(argv[2], "r"); + infile = fopen(filename, "r"); if (infile == NULL) { fprintf(stderr, "docproc: "); - perror(argv[2]); + perror(filename); exit(2); } - if (strcmp("doc", argv[1]) == 0) { + if (strcmp("doc", subcommand) == 0) { /* Need to do this in two passes. * First pass is used to collect all symbols exported * in the various files; @@ -557,10 +562,10 @@ int main(int argc, char *argv[]) fprintf(stderr, "Warning: didn't use docs for %s\n", all_list[i]); } - } else if (strcmp("depend", argv[1]) == 0) { + } else if (strcmp("depend", subcommand) == 0) { /* Create first part of dependency chain * file.tmpl */ - printf("%s\t", argv[2]); + printf("%s\t", filename); defaultline = noaction; internalfunctions = adddep; externalfunctions = adddep; @@ -571,7 +576,7 @@ int main(int argc, char *argv[]) parse_file(infile); printf("\n"); } else { - fprintf(stderr, "Unknown option: %s\n", argv[1]); + fprintf(stderr, "Unknown option: %s\n", subcommand); exit(1); } fclose(infile); From 868fb19212ca5bdbfa765a97a4bf6d2439b89056 Mon Sep 17 00:00:00 2001 From: Jani Nikula Date: Thu, 12 May 2016 16:15:40 +0300 Subject: [PATCH 46/55] docproc: reduce unnecessary indentation Improves clarity. No functional changes. Signed-off-by: Jani Nikula Signed-off-by: Jonathan Corbet --- scripts/docproc.c | 93 ++++++++++++++++++++++++----------------------- 1 file changed, 47 insertions(+), 46 deletions(-) diff --git a/scripts/docproc.c b/scripts/docproc.c index 48abc01a920e0c..fb195f0ed0ef38 100644 --- a/scripts/docproc.c +++ b/scripts/docproc.c @@ -445,52 +445,53 @@ static void parse_file(FILE *infile) char line[MAXLINESZ]; char * s; while (fgets(line, MAXLINESZ, infile)) { - if (line[0] == '!') { - s = line + 2; - switch (line[1]) { - case 'E': - while (*s && !isspace(*s)) s++; - *s = '\0'; - externalfunctions(line+2); - break; - case 'I': - while (*s && !isspace(*s)) s++; - *s = '\0'; - internalfunctions(line+2); - break; - case 'D': - while (*s && !isspace(*s)) s++; - *s = '\0'; - symbolsonly(line+2); - break; - case 'F': - /* filename */ - while (*s && !isspace(*s)) s++; - *s++ = '\0'; - /* function names */ - while (isspace(*s)) - s++; - singlefunctions(line +2, s); - break; - case 'P': - /* filename */ - while (*s && !isspace(*s)) s++; - *s++ = '\0'; - /* DOC: section name */ - while (isspace(*s)) - s++; - docsection(line + 2, s); - break; - case 'C': - while (*s && !isspace(*s)) s++; - *s = '\0'; - if (findall) - findall(line+2); - break; - default: - defaultline(line); - } - } else { + if (line[0] != '!') { + defaultline(line); + continue; + } + + s = line + 2; + switch (line[1]) { + case 'E': + while (*s && !isspace(*s)) s++; + *s = '\0'; + externalfunctions(line+2); + break; + case 'I': + while (*s && !isspace(*s)) s++; + *s = '\0'; + internalfunctions(line+2); + break; + case 'D': + while (*s && !isspace(*s)) s++; + *s = '\0'; + symbolsonly(line+2); + break; + case 'F': + /* filename */ + while (*s && !isspace(*s)) s++; + *s++ = '\0'; + /* function names */ + while (isspace(*s)) + s++; + singlefunctions(line +2, s); + break; + case 'P': + /* filename */ + while (*s && !isspace(*s)) s++; + *s++ = '\0'; + /* DOC: section name */ + while (isspace(*s)) + s++; + docsection(line + 2, s); + break; + case 'C': + while (*s && !isspace(*s)) s++; + *s = '\0'; + if (findall) + findall(line+2); + break; + default: defaultline(line); } } From a48dc45e9c02ebaebc79de5b3fec8e4f59a9fe9f Mon Sep 17 00:00:00 2001 From: Jani Nikula Date: Thu, 12 May 2016 16:15:41 +0300 Subject: [PATCH 47/55] docproc: abstract docproc directive detection Helps follow-up work. No functional changes. Signed-off-by: Jani Nikula Signed-off-by: Jonathan Corbet --- scripts/docproc.c | 30 ++++++++++++++++++++---------- 1 file changed, 20 insertions(+), 10 deletions(-) diff --git a/scripts/docproc.c b/scripts/docproc.c index fb195f0ed0ef38..bc900310b4318e 100644 --- a/scripts/docproc.c +++ b/scripts/docproc.c @@ -430,6 +430,15 @@ static void find_all_symbols(char *filename) } } +/* Return pointer to directive content, or NULL if not a directive. */ +static char *is_directive(char *line) +{ + if (line[0] == '!') + return line + 1; + + return NULL; +} + /* * Parse file, calling action specific functions for: * 1) Lines containing !E @@ -443,29 +452,30 @@ static void find_all_symbols(char *filename) static void parse_file(FILE *infile) { char line[MAXLINESZ]; - char * s; + char *p, *s; while (fgets(line, MAXLINESZ, infile)) { - if (line[0] != '!') { + p = is_directive(line); + if (!p) { defaultline(line); continue; } - s = line + 2; - switch (line[1]) { + s = p + 1; + switch (*p++) { case 'E': while (*s && !isspace(*s)) s++; *s = '\0'; - externalfunctions(line+2); + externalfunctions(p); break; case 'I': while (*s && !isspace(*s)) s++; *s = '\0'; - internalfunctions(line+2); + internalfunctions(p); break; case 'D': while (*s && !isspace(*s)) s++; *s = '\0'; - symbolsonly(line+2); + symbolsonly(p); break; case 'F': /* filename */ @@ -474,7 +484,7 @@ static void parse_file(FILE *infile) /* function names */ while (isspace(*s)) s++; - singlefunctions(line +2, s); + singlefunctions(p, s); break; case 'P': /* filename */ @@ -483,13 +493,13 @@ static void parse_file(FILE *infile) /* DOC: section name */ while (isspace(*s)) s++; - docsection(line + 2, s); + docsection(p, s); break; case 'C': while (*s && !isspace(*s)) s++; *s = '\0'; if (findall) - findall(line+2); + findall(p); break; default: defaultline(line); From 1dcdad0aacb6d762b77f3e17167d131a14c0dbce Mon Sep 17 00:00:00 2001 From: Jani Nikula Date: Thu, 12 May 2016 16:15:42 +0300 Subject: [PATCH 48/55] docproc: abstract terminating lines at first space Cleaner code. Also fixes a bug when F or P directives didn't in fact have space. Signed-off-by: Jani Nikula Signed-off-by: Jonathan Corbet --- scripts/docproc.c | 34 +++++++++++++++++++++------------- 1 file changed, 21 insertions(+), 13 deletions(-) diff --git a/scripts/docproc.c b/scripts/docproc.c index bc900310b4318e..a933e054402d50 100644 --- a/scripts/docproc.c +++ b/scripts/docproc.c @@ -430,6 +430,21 @@ static void find_all_symbols(char *filename) } } +/* + * Terminate s at first space, if any. If there was a space, return pointer to + * the character after that. Otherwise, return pointer to the terminating NUL. + */ +static char *chomp(char *s) +{ + while (*s && !isspace(*s)) + s++; + + if (*s) + *s++ = '\0'; + + return s; +} + /* Return pointer to directive content, or NULL if not a directive. */ static char *is_directive(char *line) { @@ -460,27 +475,22 @@ static void parse_file(FILE *infile) continue; } - s = p + 1; switch (*p++) { case 'E': - while (*s && !isspace(*s)) s++; - *s = '\0'; + chomp(p); externalfunctions(p); break; case 'I': - while (*s && !isspace(*s)) s++; - *s = '\0'; + chomp(p); internalfunctions(p); break; case 'D': - while (*s && !isspace(*s)) s++; - *s = '\0'; + chomp(p); symbolsonly(p); break; case 'F': /* filename */ - while (*s && !isspace(*s)) s++; - *s++ = '\0'; + s = chomp(p); /* function names */ while (isspace(*s)) s++; @@ -488,16 +498,14 @@ static void parse_file(FILE *infile) break; case 'P': /* filename */ - while (*s && !isspace(*s)) s++; - *s++ = '\0'; + s = chomp(p); /* DOC: section name */ while (isspace(*s)) s++; docsection(p, s); break; case 'C': - while (*s && !isspace(*s)) s++; - *s = '\0'; + chomp(p); if (findall) findall(p); break; From 064669b43baa4b74b262c49db3ce69118e2f0f2d Mon Sep 17 00:00:00 2001 From: Jani Nikula Date: Thu, 12 May 2016 16:15:43 +0300 Subject: [PATCH 49/55] docproc: add support for reStructuredText format via --rst option Expect reStructuredText input and have kernel-doc produce reStructuredText output with the new --rst option. Also add --docbook option for completeness. If no option is given, default to reStructuredText if the input file has ".rst" extension, DocBook otherwise. Directives for reStructuredText use .. ! instead of just !, to make them reStructuredText comments. Signed-off-by: Jani Nikula Signed-off-by: Jonathan Corbet --- scripts/docproc.c | 90 +++++++++++++++++++++++++++++++++++++++++------ 1 file changed, 80 insertions(+), 10 deletions(-) diff --git a/scripts/docproc.c b/scripts/docproc.c index a933e054402d50..9babfd108d2ea5 100644 --- a/scripts/docproc.c +++ b/scripts/docproc.c @@ -42,6 +42,7 @@ #include #include #include +#include #include #include @@ -68,12 +69,23 @@ FILELINE * docsection; #define KERNELDOCPATH "scripts/" #define KERNELDOC "kernel-doc" #define DOCBOOK "-docbook" +#define RST "-rst" #define LIST "-list" #define FUNCTION "-function" #define NOFUNCTION "-nofunction" #define NODOCSECTIONS "-no-doc-sections" #define SHOWNOTFOUND "-show-not-found" +enum file_format { + FORMAT_AUTO, + FORMAT_DOCBOOK, + FORMAT_RST, +}; + +static enum file_format file_format = FORMAT_AUTO; + +#define KERNELDOC_FORMAT (file_format == FORMAT_RST ? RST : DOCBOOK) + static char *srctree, *kernsrctree; static char **all_list = NULL; @@ -95,7 +107,7 @@ static void consume_symbol(const char *sym) static void usage (void) { - fprintf(stderr, "Usage: docproc {doc|depend} file\n"); + fprintf(stderr, "Usage: docproc [{--docbook|--rst}] {doc|depend} file\n"); fprintf(stderr, "Input is read from file.tmpl. Output is sent to stdout\n"); fprintf(stderr, "doc: frontend when generating kernel documentation\n"); fprintf(stderr, "depend: generate list of files referenced within file\n"); @@ -242,7 +254,7 @@ static void find_export_symbols(char * filename) /* * Document all external or internal functions in a file. * Call kernel-doc with following parameters: - * kernel-doc -docbook -nofunction function_name1 filename + * kernel-doc [-docbook|-rst] -nofunction function_name1 filename * Function names are obtained from all the src files * by find_export_symbols. * intfunc uses -nofunction @@ -263,7 +275,7 @@ static void docfunctions(char * filename, char * type) exit(1); } vec[idx++] = KERNELDOC; - vec[idx++] = DOCBOOK; + vec[idx++] = KERNELDOC_FORMAT; vec[idx++] = NODOCSECTIONS; for (i=0; i < symfilecnt; i++) { struct symfile * sym = &symfilelist[i]; @@ -275,7 +287,10 @@ static void docfunctions(char * filename, char * type) } vec[idx++] = filename; vec[idx] = NULL; - printf("\n", filename); + if (file_format == FORMAT_RST) + printf(".. %s\n", filename); + else + printf("\n", filename); exec_kernel_doc(vec); fflush(stdout); free(vec); @@ -294,7 +309,7 @@ static void singfunc(char * filename, char * line) int i, idx = 0; int startofsym = 1; vec[idx++] = KERNELDOC; - vec[idx++] = DOCBOOK; + vec[idx++] = KERNELDOC_FORMAT; vec[idx++] = SHOWNOTFOUND; /* Split line up in individual parameters preceded by FUNCTION */ @@ -343,7 +358,7 @@ static void docsect(char *filename, char *line) free(s); vec[0] = KERNELDOC; - vec[1] = DOCBOOK; + vec[1] = KERNELDOC_FORMAT; vec[2] = SHOWNOTFOUND; vec[3] = FUNCTION; vec[4] = line; @@ -448,8 +463,10 @@ static char *chomp(char *s) /* Return pointer to directive content, or NULL if not a directive. */ static char *is_directive(char *line) { - if (line[0] == '!') + if (file_format == FORMAT_DOCBOOK && line[0] == '!') return line + 1; + else if (file_format == FORMAT_RST && !strncmp(line, ".. !", 4)) + return line + 4; return NULL; } @@ -516,6 +533,22 @@ static void parse_file(FILE *infile) fflush(stdout); } +/* + * Is this a RestructuredText template? Answer the question by seeing if its + * name ends in ".rst". + */ +static int is_rst(const char *file) +{ + char *dot = strrchr(file, '.'); + + return dot && !strcmp(dot + 1, "rst"); +} + +enum opts { + OPT_DOCBOOK, + OPT_RST, + OPT_HELP, +}; int main(int argc, char *argv[]) { @@ -529,13 +562,50 @@ int main(int argc, char *argv[]) kernsrctree = getenv("KBUILD_SRC"); if (!kernsrctree || !*kernsrctree) kernsrctree = srctree; - if (argc != 3) { + + for (;;) { + int c; + struct option opts[] = { + { "docbook", no_argument, NULL, OPT_DOCBOOK }, + { "rst", no_argument, NULL, OPT_RST }, + { "help", no_argument, NULL, OPT_HELP }, + {} + }; + + c = getopt_long_only(argc, argv, "", opts, NULL); + if (c == -1) + break; + + switch (c) { + case OPT_DOCBOOK: + file_format = FORMAT_DOCBOOK; + break; + case OPT_RST: + file_format = FORMAT_RST; + break; + case OPT_HELP: + usage(); + return 0; + default: + case '?': + usage(); + return 1; + } + } + + argc -= optind; + argv += optind; + + if (argc != 2) { usage(); exit(1); } - subcommand = argv[1]; - filename = argv[2]; + subcommand = argv[0]; + filename = argv[1]; + + if (file_format == FORMAT_AUTO) + file_format = is_rst(filename) ? FORMAT_RST : FORMAT_DOCBOOK; /* Open file, exit on error */ infile = fopen(filename, "r"); From 0e95abf9be3108498128458ffb087209e0a1b5fa Mon Sep 17 00:00:00 2001 From: Jani Nikula Date: Thu, 12 May 2016 16:15:44 +0300 Subject: [PATCH 50/55] docproc: print a comment about autogeneration for rst output Leave a hint to folks which file to edit instead. Signed-off-by: Jani Nikula Signed-off-by: Jonathan Corbet --- scripts/docproc.c | 7 +++++++ 1 file changed, 7 insertions(+) diff --git a/scripts/docproc.c b/scripts/docproc.c index 9babfd108d2ea5..0a12593b90414b 100644 --- a/scripts/docproc.c +++ b/scripts/docproc.c @@ -45,6 +45,7 @@ #include #include #include +#include /* exitstatus is used to keep track of any failing calls to kernel-doc, * but execution continues. */ @@ -616,6 +617,12 @@ int main(int argc, char *argv[]) } if (strcmp("doc", subcommand) == 0) { + if (file_format == FORMAT_RST) { + time_t t = time(NULL); + printf(".. generated from %s by docproc %s\n", + filename, ctime(&t)); + } + /* Need to do this in two passes. * First pass is used to collect all symbols exported * in the various files; From 2bdbc5bc16c338a43c9ac7ef93c1a60a8b17ee7d Mon Sep 17 00:00:00 2001 From: Qiang Huang Date: Wed, 11 May 2016 14:07:31 +0800 Subject: [PATCH 51/55] Documentation/memcg: update kmem limit doc as codes behavior The restriction of kmem setting is not there anymore because the accounting is enabled by default even in the cgroup v1 - see b313aeee2509 ("mm: memcontrol: enable kmem accounting for all cgroups in the legacy hierarchy"). Update docs accordingly. Signed-off-by: Qiang Huang Acked-by: Michal Hocko Signed-off-by: Jonathan Corbet --- Documentation/cgroup-v1/memory.txt | 14 +++----------- 1 file changed, 3 insertions(+), 11 deletions(-) diff --git a/Documentation/cgroup-v1/memory.txt b/Documentation/cgroup-v1/memory.txt index ff71e16cc75248..b14abf217239e8 100644 --- a/Documentation/cgroup-v1/memory.txt +++ b/Documentation/cgroup-v1/memory.txt @@ -280,17 +280,9 @@ the amount of kernel memory used by the system. Kernel memory is fundamentally different than user memory, since it can't be swapped out, which makes it possible to DoS the system by consuming too much of this precious resource. -Kernel memory won't be accounted at all until limit on a group is set. This -allows for existing setups to continue working without disruption. The limit -cannot be set if the cgroup have children, or if there are already tasks in the -cgroup. Attempting to set the limit under those conditions will return -EBUSY. -When use_hierarchy == 1 and a group is accounted, its children will -automatically be accounted regardless of their limit value. - -After a group is first limited, it will be kept being accounted until it -is removed. The memory limitation itself, can of course be removed by writing --1 to memory.kmem.limit_in_bytes. In this case, kmem will be accounted, but not -limited. +Kernel memory accounting is enabled for all memory cgroups by default. But +it can be disabled system-wide by passing cgroup.memory=nokmem to the kernel +at boot time. In this case, kernel memory will not be accounted at all. Kernel memory limits are not imposed for the root cgroup. Usage for the root cgroup may or may not be accounted. The memory used is accumulated into From 30955e71fc2bd1b966ce6531285ac59ae653819f Mon Sep 17 00:00:00 2001 From: Geert Uytterhoeven Date: Tue, 10 May 2016 20:59:56 +0200 Subject: [PATCH 52/55] Documentation: vm: Spelling s/paltform/platform/g Signed-off-by: Geert Uytterhoeven Signed-off-by: Jonathan Corbet --- Documentation/vm/hugetlbpage.txt | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/Documentation/vm/hugetlbpage.txt b/Documentation/vm/hugetlbpage.txt index b7a3f6d6cfc1cc..59cbc803aad66e 100644 --- a/Documentation/vm/hugetlbpage.txt +++ b/Documentation/vm/hugetlbpage.txt @@ -275,10 +275,10 @@ This command mounts a (pseudo) filesystem of type hugetlbfs on the directory options sets the owner and group of the root of the file system. By default the uid and gid of the current process are taken. The mode option sets the mode of root of file system to value & 01777. This value is given in octal. -By default the value 0755 is picked. If the paltform supports multiple huge +By default the value 0755 is picked. If the platform supports multiple huge page sizes, the pagesize option can be used to specify the huge page size and associated pool. pagesize is specified in bytes. If pagesize is not specified -the paltform's default huge page size and associated pool will be used. The +the platform's default huge page size and associated pool will be used. The size option sets the maximum value of memory (huge pages) allowed for that filesystem (/mnt/huge). The size option can be specified in bytes, or as a percentage of the specified huge page pool (nr_hugepages). The size is From 95f981f2e3b9a27ea2eb744b6861a3b9c81a1fde Mon Sep 17 00:00:00 2001 From: Geert Uytterhoeven Date: Wed, 11 May 2016 13:56:04 +0200 Subject: [PATCH 53/55] serial: doc: Always refer to tty_port->mutex Stop referring to the mutex member of the tty_port struct as 'port->mutex', as 'port' is ambiguous, and usually refers to the uart_port struct in this document. Use 'tty_port->mutex' instead, following the single existing use. Signed-off-by: Geert Uytterhoeven Signed-off-by: Jonathan Corbet --- Documentation/serial/driver | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/Documentation/serial/driver b/Documentation/serial/driver index 39701515832b70..90889c785809cd 100644 --- a/Documentation/serial/driver +++ b/Documentation/serial/driver @@ -57,7 +57,7 @@ locking. The port_sem semaphore is used to protect against ports being added/ removed or reconfigured at inappropriate times. Since v2.6.27, this semaphore has been the 'mutex' member of the tty_port struct, and -commonly referred to as the port mutex (or port->mutex). +commonly referred to as the port mutex. uart_ops @@ -186,7 +186,7 @@ hardware. should be terminated when another call is made with a zero ctl. - Locking: caller holds port->mutex + Locking: caller holds tty_port->mutex startup(port) Grab any interrupt resources and initialise any low level driver @@ -262,14 +262,14 @@ hardware. Other flags may be used (eg, xon/xoff characters) if your hardware supports hardware "soft" flow control. - Locking: caller holds port->mutex + Locking: caller holds tty_port->mutex Interrupts: caller dependent. This call must not sleep set_ldisc(port,termios) Notifier for discipline change. See Documentation/serial/tty.txt. - Locking: caller holds port->mutex + Locking: caller holds tty_port->mutex pm(port,state,oldstate) Perform any power management related activities on the specified From b79ef07d205c6504e701b48380d33fe2bab78ec5 Mon Sep 17 00:00:00 2001 From: Geert Uytterhoeven Date: Wed, 11 May 2016 13:56:05 +0200 Subject: [PATCH 54/55] serial: doc: Use port->state instead of info As of commit ebd2c8f6d2ec4012 ("serial: kill off uart_info"), the circular transmission buffer is part of struct uart_state instead of struct uart_info. Make it clear this structure is pointed to from struct uart_port. Change 'circ' to 'circ_buf' to match the structure name while we're at it. Signed-off-by: Geert Uytterhoeven Signed-off-by: Jonathan Corbet --- Documentation/serial/driver | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/Documentation/serial/driver b/Documentation/serial/driver index 90889c785809cd..da193e092fc3d5 100644 --- a/Documentation/serial/driver +++ b/Documentation/serial/driver @@ -48,8 +48,8 @@ data: port->mctrl port->icount - info->xmit.head (circ->head) - info->xmit.tail (circ->tail) + port->state->xmit.head (circ_buf->head) + port->state->xmit.tail (circ_buf->tail) The low level driver is free to use this lock to provide any additional locking. @@ -204,7 +204,7 @@ hardware. RTS nor DTR; this will have already been done via a separate call to set_mctrl. - Drivers must not access port->info once this call has completed. + Drivers must not access port->state once this call has completed. This method will only be called when there are no more users of this port. @@ -216,7 +216,7 @@ hardware. Flush any write buffers, reset any DMA state and stop any ongoing DMA transfers. - This will be called whenever the port->info->xmit circular + This will be called whenever the port->state->xmit circular buffer is cleared. Locking: port->lock taken. From 9f8036643dd9609b329aa1b89c9a95981e9ba62f Mon Sep 17 00:00:00 2001 From: Kees Cook Date: Mon, 16 May 2016 19:27:28 -0700 Subject: [PATCH 55/55] doc: self-protection: provide initial details This document attempts to codify the intent around kernel self-protection along with discussion of both existing and desired technologies, with attention given to the rationale behind them, and the expectations of their usage. Signed-off-by: Kees Cook Reviewed-by: Randy Dunlap [jc: applied fixes suggested by Randy] Reviewed-by: Greg Kroah-Hartman Signed-off-by: Jonathan Corbet --- Documentation/security/self-protection.txt | 261 +++++++++++++++++++++ 1 file changed, 261 insertions(+) create mode 100644 Documentation/security/self-protection.txt diff --git a/Documentation/security/self-protection.txt b/Documentation/security/self-protection.txt new file mode 100644 index 00000000000000..babd6378ec0573 --- /dev/null +++ b/Documentation/security/self-protection.txt @@ -0,0 +1,261 @@ +# Kernel Self-Protection + +Kernel self-protection is the design and implementation of systems and +structures within the Linux kernel to protect against security flaws in +the kernel itself. This covers a wide range of issues, including removing +entire classes of bugs, blocking security flaw exploitation methods, +and actively detecting attack attempts. Not all topics are explored in +this document, but it should serve as a reasonable starting point and +answer any frequently asked questions. (Patches welcome, of course!) + +In the worst-case scenario, we assume an unprivileged local attacker +has arbitrary read and write access to the kernel's memory. In many +cases, bugs being exploited will not provide this level of access, +but with systems in place that defend against the worst case we'll +cover the more limited cases as well. A higher bar, and one that should +still be kept in mind, is protecting the kernel against a _privileged_ +local attacker, since the root user has access to a vastly increased +attack surface. (Especially when they have the ability to load arbitrary +kernel modules.) + +The goals for successful self-protection systems would be that they +are effective, on by default, require no opt-in by developers, have no +performance impact, do not impede kernel debugging, and have tests. It +is uncommon that all these goals can be met, but it is worth explicitly +mentioning them, since these aspects need to be explored, dealt with, +and/or accepted. + + +## Attack Surface Reduction + +The most fundamental defense against security exploits is to reduce the +areas of the kernel that can be used to redirect execution. This ranges +from limiting the exposed APIs available to userspace, making in-kernel +APIs hard to use incorrectly, minimizing the areas of writable kernel +memory, etc. + +### Strict kernel memory permissions + +When all of kernel memory is writable, it becomes trivial for attacks +to redirect execution flow. To reduce the availability of these targets +the kernel needs to protect its memory with a tight set of permissions. + +#### Executable code and read-only data must not be writable + +Any areas of the kernel with executable memory must not be writable. +While this obviously includes the kernel text itself, we must consider +all additional places too: kernel modules, JIT memory, etc. (There are +temporary exceptions to this rule to support things like instruction +alternatives, breakpoints, kprobes, etc. If these must exist in a +kernel, they are implemented in a way where the memory is temporarily +made writable during the update, and then returned to the original +permissions.) + +In support of this are (the poorly named) CONFIG_DEBUG_RODATA and +CONFIG_DEBUG_SET_MODULE_RONX, which seek to make sure that code is not +writable, data is not executable, and read-only data is neither writable +nor executable. + +#### Function pointers and sensitive variables must not be writable + +Vast areas of kernel memory contain function pointers that are looked +up by the kernel and used to continue execution (e.g. descriptor/vector +tables, file/network/etc operation structures, etc). The number of these +variables must be reduced to an absolute minimum. + +Many such variables can be made read-only by setting them "const" +so that they live in the .rodata section instead of the .data section +of the kernel, gaining the protection of the kernel's strict memory +permissions as described above. + +For variables that are initialized once at __init time, these can +be marked with the (new and under development) __ro_after_init +attribute. + +What remains are variables that are updated rarely (e.g. GDT). These +will need another infrastructure (similar to the temporary exceptions +made to kernel code mentioned above) that allow them to spend the rest +of their lifetime read-only. (For example, when being updated, only the +CPU thread performing the update would be given uninterruptible write +access to the memory.) + +#### Segregation of kernel memory from userspace memory + +The kernel must never execute userspace memory. The kernel must also never +access userspace memory without explicit expectation to do so. These +rules can be enforced either by support of hardware-based restrictions +(x86's SMEP/SMAP, ARM's PXN/PAN) or via emulation (ARM's Memory Domains). +By blocking userspace memory in this way, execution and data parsing +cannot be passed to trivially-controlled userspace memory, forcing +attacks to operate entirely in kernel memory. + +### Reduced access to syscalls + +One trivial way to eliminate many syscalls for 64-bit systems is building +without CONFIG_COMPAT. However, this is rarely a feasible scenario. + +The "seccomp" system provides an opt-in feature made available to +userspace, which provides a way to reduce the number of kernel entry +points available to a running process. This limits the breadth of kernel +code that can be reached, possibly reducing the availability of a given +bug to an attack. + +An area of improvement would be creating viable ways to keep access to +things like compat, user namespaces, BPF creation, and perf limited only +to trusted processes. This would keep the scope of kernel entry points +restricted to the more regular set of normally available to unprivileged +userspace. + +### Restricting access to kernel modules + +The kernel should never allow an unprivileged user the ability to +load specific kernel modules, since that would provide a facility to +unexpectedly extend the available attack surface. (The on-demand loading +of modules via their predefined subsystems, e.g. MODULE_ALIAS_*, is +considered "expected" here, though additional consideration should be +given even to these.) For example, loading a filesystem module via an +unprivileged socket API is nonsense: only the root or physically local +user should trigger filesystem module loading. (And even this can be up +for debate in some scenarios.) + +To protect against even privileged users, systems may need to either +disable module loading entirely (e.g. monolithic kernel builds or +modules_disabled sysctl), or provide signed modules (e.g. +CONFIG_MODULE_SIG_FORCE, or dm-crypt with LoadPin), to keep from having +root load arbitrary kernel code via the module loader interface. + + +## Memory integrity + +There are many memory structures in the kernel that are regularly abused +to gain execution control during an attack, By far the most commonly +understood is that of the stack buffer overflow in which the return +address stored on the stack is overwritten. Many other examples of this +kind of attack exist, and protections exist to defend against them. + +### Stack buffer overflow + +The classic stack buffer overflow involves writing past the expected end +of a variable stored on the stack, ultimately writing a controlled value +to the stack frame's stored return address. The most widely used defense +is the presence of a stack canary between the stack variables and the +return address (CONFIG_CC_STACKPROTECTOR), which is verified just before +the function returns. Other defenses include things like shadow stacks. + +### Stack depth overflow + +A less well understood attack is using a bug that triggers the +kernel to consume stack memory with deep function calls or large stack +allocations. With this attack it is possible to write beyond the end of +the kernel's preallocated stack space and into sensitive structures. Two +important changes need to be made for better protections: moving the +sensitive thread_info structure elsewhere, and adding a faulting memory +hole at the bottom of the stack to catch these overflows. + +### Heap memory integrity + +The structures used to track heap free lists can be sanity-checked during +allocation and freeing to make sure they aren't being used to manipulate +other memory areas. + +### Counter integrity + +Many places in the kernel use atomic counters to track object references +or perform similar lifetime management. When these counters can be made +to wrap (over or under) this traditionally exposes a use-after-free +flaw. By trapping atomic wrapping, this class of bug vanishes. + +### Size calculation overflow detection + +Similar to counter overflow, integer overflows (usually size calculations) +need to be detected at runtime to kill this class of bug, which +traditionally leads to being able to write past the end of kernel buffers. + + +## Statistical defenses + +While many protections can be considered deterministic (e.g. read-only +memory cannot be written to), some protections provide only statistical +defense, in that an attack must gather enough information about a +running system to overcome the defense. While not perfect, these do +provide meaningful defenses. + +### Canaries, blinding, and other secrets + +It should be noted that things like the stack canary discussed earlier +are technically statistical defenses, since they rely on a (leakable) +secret value. + +Blinding literal values for things like JITs, where the executable +contents may be partially under the control of userspace, need a similar +secret value. + +It is critical that the secret values used must be separate (e.g. +different canary per stack) and high entropy (e.g. is the RNG actually +working?) in order to maximize their success. + +### Kernel Address Space Layout Randomization (KASLR) + +Since the location of kernel memory is almost always instrumental in +mounting a successful attack, making the location non-deterministic +raises the difficulty of an exploit. (Note that this in turn makes +the value of leaks higher, since they may be used to discover desired +memory locations.) + +#### Text and module base + +By relocating the physical and virtual base address of the kernel at +boot-time (CONFIG_RANDOMIZE_BASE), attacks needing kernel code will be +frustrated. Additionally, offsetting the module loading base address +means that even systems that load the same set of modules in the same +order every boot will not share a common base address with the rest of +the kernel text. + +#### Stack base + +If the base address of the kernel stack is not the same between processes, +or even not the same between syscalls, targets on or beyond the stack +become more difficult to locate. + +#### Dynamic memory base + +Much of the kernel's dynamic memory (e.g. kmalloc, vmalloc, etc) ends up +being relatively deterministic in layout due to the order of early-boot +initializations. If the base address of these areas is not the same +between boots, targeting them is frustrated, requiring a leak specific +to the region. + + +## Preventing Leaks + +Since the locations of sensitive structures are the primary target for +attacks, it is important to defend against leaks of both kernel memory +addresses and kernel memory contents (since they may contain kernel +addresses or other sensitive things like canary values). + +### Unique identifiers + +Kernel memory addresses must never be used as identifiers exposed to +userspace. Instead, use an atomic counter, an idr, or similar unique +identifier. + +### Memory initialization + +Memory copied to userspace must always be fully initialized. If not +explicitly memset(), this will require changes to the compiler to make +sure structure holes are cleared. + +### Memory poisoning + +When releasing memory, it is best to poison the contents (clear stack on +syscall return, wipe heap memory on a free), to avoid reuse attacks that +rely on the old contents of memory. This frustrates many uninitialized +variable attacks, stack info leaks, heap info leaks, and use-after-free +attacks. + +### Destination tracking + +To help kill classes of bugs that result in kernel addresses being +written to userspace, the destination of writes needs to be tracked. If +the buffer is destined for userspace (e.g. seq_file backed /proc files), +it should automatically censor sensitive values.