From 83d26b63268faf9137878e34f7e8cfda8a089124 Mon Sep 17 00:00:00 2001 From: Dave Anderson Date: Mon, 28 Mar 2016 14:56:47 -0700 Subject: 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 96da119a47e7..11f67f181d39 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 ^ -- cgit v1.2.3 From dbe7fcdaf94052faf65172bb91d4266d20b5458b Mon Sep 17 00:00:00 2001 From: Jianyu Zhan Date: Sun, 27 Mar 2016 11:51:20 +0800 Subject: 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 8d990bde8693..82001a25a14b 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 ===- -- cgit v1.2.3 From 5408e5a4552b8e33a65127944bec21dd3d9258c1 Mon Sep 17 00:00:00 2001 From: Wei Fang Date: Mon, 21 Mar 2016 19:42:19 +0800 Subject: 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 e840b47613f7..e55103ace382 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 -- cgit v1.2.3 From a06bdd49c98c6a538890650bac9a0173cbc644b2 Mon Sep 17 00:00:00 2001 From: Luis de Bethencourt Date: Sat, 19 Mar 2016 12:51:20 +0000 Subject: 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 fe217c1c2f7f..b2503602134f 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 -- cgit v1.2.3 From dc831ab3cc7f22ae500872e54cd85317e766c156 Mon Sep 17 00:00:00 2001 From: Luis de Bethencourt Date: Sat, 19 Mar 2016 12:51:22 +0000 Subject: 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 b2503602134f..b92449feea23 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... -- cgit v1.2.3 From f7ca20deee2b2eac0a43e1dcf75d5d3ee2c6c81e Mon Sep 17 00:00:00 2001 From: Luis de Bethencourt Date: Sat, 19 Mar 2016 12:51:23 +0000 Subject: 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 b92449feea23..3aecbac1cb01 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. -- cgit v1.2.3 From f3e27a80b782b9b9857157e0a104a8757e72d166 Mon Sep 17 00:00:00 2001 From: Baolin Wang Date: Wed, 16 Mar 2016 20:02:49 +0800 Subject: 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 a9ba6720ffdf..4623bc0aa0bb 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 000000000000..735509c165d5 --- /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. -- cgit v1.2.3 From 834392a7d92677ff2bdc1c709b1171ee585b55c9 Mon Sep 17 00:00:00 2001 From: Geert Uytterhoeven Date: Mon, 14 Mar 2016 16:16:09 +0100 Subject: 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 379468e12680..e7c6f86ee06f 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 ------- -- cgit v1.2.3 From 4895b1d72117efea48ff51e94a26ce3cbde4d1a1 Mon Sep 17 00:00:00 2001 From: Geert Uytterhoeven Date: Mon, 14 Mar 2016 16:16:10 +0100 Subject: 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 e7c6f86ee06f..61d520dea4c6 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 -- cgit v1.2.3 From 39c5144e5f0bc2dec9ebe3613d5f9c0f0b0bdc72 Mon Sep 17 00:00:00 2001 From: Geert Uytterhoeven Date: Mon, 14 Mar 2016 16:16:11 +0100 Subject: 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 61d520dea4c6..50f3d94ed50b 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 -- cgit v1.2.3 From e27585c7970decd26113ca036a1cb5678d88ee5a Mon Sep 17 00:00:00 2001 From: Geert Uytterhoeven Date: Mon, 14 Mar 2016 16:16:12 +0100 Subject: 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 50f3d94ed50b..3b2a97d5ecc7 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 -- cgit v1.2.3 From 0adc301e7b3c098744d0098008b1aa31041e220b Mon Sep 17 00:00:00 2001 From: Geert Uytterhoeven Date: Mon, 14 Mar 2016 16:16:13 +0100 Subject: 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 3b2a97d5ecc7..3b08df5bcc17 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 -- cgit v1.2.3 From fbe3128bcf87723bbbaa2de26f5d1c1122c66b54 Mon Sep 17 00:00:00 2001 From: Geert Uytterhoeven Date: Mon, 14 Mar 2016 16:16:14 +0100 Subject: 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 3b08df5bcc17..09e73e061fcf 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) -- cgit v1.2.3 From 93a2f6329f40d951101ab8ab160f24680f1c122a Mon Sep 17 00:00:00 2001 From: Geert Uytterhoeven Date: Mon, 14 Mar 2016 16:16:15 +0100 Subject: 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 09e73e061fcf..3706a465fe2d 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 -- cgit v1.2.3 From d886e7ce157373773254f5c1e7f011cd9d3ec558 Mon Sep 17 00:00:00 2001 From: Geert Uytterhoeven Date: Mon, 14 Mar 2016 16:16:16 +0100 Subject: 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 3706a465fe2d..ba84d1f38ca1 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) -- cgit v1.2.3 From 4817ebb144ffa5a1a2bc84b89ed9655dbe6c4502 Mon Sep 17 00:00:00 2001 From: Geert Uytterhoeven Date: Mon, 14 Mar 2016 16:16:17 +0100 Subject: 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 ba84d1f38ca1..65de49a4b39e 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. -- cgit v1.2.3 From 4f2651e1d838c4db656170bddfcabdf67a8d7f9b Mon Sep 17 00:00:00 2001 From: Luis de Bethencourt Date: Thu, 31 Mar 2016 12:10:30 +0100 Subject: 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 3aecbac1cb01..1dafc52167b0 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. -- cgit v1.2.3 From cfaf790f932beae903a5fc5b19039d7b3842a3b3 Mon Sep 17 00:00:00 2001 From: Diego Viola Date: Sun, 3 Apr 2016 04:34:48 -0300 Subject: 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 afc4f0d81ee1..e8c8a6dc1c2b 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 -- cgit v1.2.3 From 2dd723fdbb61fbc4ee0125401f04f5431f61268d Mon Sep 17 00:00:00 2001 From: Diego Herranz Date: Tue, 12 Apr 2016 18:13:27 +0100 Subject: 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 7d66a8636cb5..5faf514047e9 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 -- cgit v1.2.3 From 63f8e8d2a575ef62e5b705516b491a98a60517ff Mon Sep 17 00:00:00 2001 From: Doug Hoyte Date: Wed, 13 Apr 2016 11:09:21 -0400 Subject: 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 0e1e55588b59..eafcefa15261 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 -- cgit v1.2.3 From d124fd3bb36ceb40438f10c897ce642386b74b72 Mon Sep 17 00:00:00 2001 From: Geert Uytterhoeven Date: Thu, 14 Apr 2016 11:08:08 +0200 Subject: 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 65de49a4b39e..03369d076ca2 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 ------- -- cgit v1.2.3 From a3bedc3bdc6e640141157636e253d63279860e23 Mon Sep 17 00:00:00 2001 From: Geert Uytterhoeven Date: Thu, 14 Apr 2016 11:08:09 +0200 Subject: 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 03369d076ca2..03b703cf9318 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. -- cgit v1.2.3 From 18717b06ee4897c2cc5e92783386c4b304b9fce9 Mon Sep 17 00:00:00 2001 From: Geert Uytterhoeven Date: Thu, 14 Apr 2016 11:08:10 +0200 Subject: 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 03b703cf9318..7fb80682e394 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. -- cgit v1.2.3 From 101ca9ccdd30c46afc5c9a30e7acdcbeaa330fa1 Mon Sep 17 00:00:00 2001 From: Geert Uytterhoeven Date: Thu, 14 Apr 2016 11:08:11 +0200 Subject: 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 7fb80682e394..39701515832b 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 -- cgit v1.2.3 From ad0de1e3fe9aacbf110052bcc1765c877e69858f Mon Sep 17 00:00:00 2001 From: SeongJae Park Date: Sat, 16 Apr 2016 09:18:46 +0900 Subject: 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 52ef02b33da9..581c14bdd7be 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 5a81b394b3b5..46b22395748d 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 54ea24ff63c7..56ca786e5842 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的情况来决定 -- cgit v1.2.3 From 78f3873decadde42da6edf419635b5972ae61e00 Mon Sep 17 00:00:00 2001 From: SeongJae Park Date: Sat, 16 Apr 2016 09:32:30 +0900 Subject: 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 46b22395748d..9a3e65924d54 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 56ca786e5842..f0613b92e0be 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版本内核发布。之后只有不包含可能影响整个内核稳定性的 新功能的补丁才可能被接受。请注意一个全新的驱动程序（或者文件系统）有 -- cgit v1.2.3 From 2c30322c4795bf26a74b6049bbea6267a19036a4 Mon Sep 17 00:00:00 2001 From: Askar Safin Date: Mon, 18 Apr 2016 20:30:56 +0300 Subject: 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 cc2d4ac4f404..bbb31e091b28 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 -- cgit v1.2.3 From ac86db349e2df2e2d6b786cbacefa3037126f3bc Mon Sep 17 00:00:00 2001 From: Cao jin Date: Thu, 21 Apr 2016 21:39:15 +0800 Subject: 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 ce31f65e12e7..492f1affb0e5 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 -- cgit v1.2.3 From e0a37712819cb0e942f165a3f88d85f7c6388219 Mon Sep 17 00:00:00 2001 From: Fu Wei Date: Thu, 21 Apr 2016 21:45:40 +0800 Subject: 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 1145bf864082..c1dd968c5ee9 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 区域），都将被认为对内核是可用。 -- cgit v1.2.3 From 2ea2dc87feb5778f6a4f58dec4ddce695e58e482 Mon Sep 17 00:00:00 2001 From: Alexander Kurz Date: Thu, 21 Apr 2016 19:02:04 +0200 Subject: 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 73b98dfbcea4..25e8f3ea3b80 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() -- cgit v1.2.3 From 2b4f4f3da6a04ba0f7a4e132a7e646aac3346dbc Mon Sep 17 00:00:00 2001 From: Eric Engestrom Date: Mon, 25 Apr 2016 07:36:53 +0100 Subject: 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 11dbcfdc9e7a..0c1d88dedbde 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, -- cgit v1.2.3 From 62e153c46f699efa13f5fa4445c2ecc4c5de1ec1 Mon Sep 17 00:00:00 2001 From: Eric Engestrom Date: Mon, 25 Apr 2016 07:36:55 +0100 Subject: 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 ea45dd3901e3..285c54f66779 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 -- cgit v1.2.3 From c0270efc510e53afd99f35aff0d0251672ae07c3 Mon Sep 17 00:00:00 2001 From: Eric Engestrom Date: Mon, 25 Apr 2016 07:36:58 +0100 Subject: 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 7cb7264ad598..50022b3c8ebf 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); -- cgit v1.2.3 From 86cbbe24b4120aa4813c8519eb2b1506147fe0a0 Mon Sep 17 00:00:00 2001 From: Eric Engestrom Date: Mon, 25 Apr 2016 07:37:00 +0100 Subject: 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 af6fce23e484..61c22d608759 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. -- cgit v1.2.3 From 1248562b8cd8d6cc2950e165cb426b4f36d29f64 Mon Sep 17 00:00:00 2001 From: Eric Engestrom Date: Mon, 25 Apr 2016 07:37:01 +0100 Subject: 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 18b570990040..00ffdf187f0b 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 -- cgit v1.2.3 From c8e84d2f9bc0021200a11721df0dc987d6191193 Mon Sep 17 00:00:00 2001 From: Eric Engestrom Date: Mon, 25 Apr 2016 07:37:06 +0100 Subject: 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 818518a3ff01..1a5a12184a35 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. -- cgit v1.2.3 From 715cda787c47458c94b2d012e6e9ab0988409f22 Mon Sep 17 00:00:00 2001 From: Eric Engestrom Date: Mon, 25 Apr 2016 07:37:07 +0100 Subject: 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 81d111b4dc28..1660145b9969 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. -- cgit v1.2.3 From 14fbff6b4e48a529c90e771598ac12bffd445ff4 Mon Sep 17 00:00:00 2001 From: Arnd Bergmann Date: Mon, 25 Apr 2016 18:03:08 +0200 Subject: 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/.gitignore | 1 - Documentation/connector/Makefile | 16 --- Documentation/connector/cn_test.c | 201 --------------------------- Documentation/connector/connector.txt | 8 ++ Documentation/connector/ucon.c | 250 ---------------------------------- samples/Kconfig | 9 ++ samples/Makefile | 2 +- samples/connector/.gitignore | 1 + samples/connector/Makefile | 16 +++ samples/connector/cn_test.c | 201 +++++++++++++++++++++++++++ samples/connector/ucon.c | 250 ++++++++++++++++++++++++++++++++++ 12 files changed, 487 insertions(+), 470 deletions(-) delete mode 100644 Documentation/connector/.gitignore delete mode 100644 Documentation/connector/Makefile delete mode 100644 Documentation/connector/cn_test.c delete mode 100644 Documentation/connector/ucon.c create mode 100644 samples/connector/.gitignore create mode 100644 samples/connector/Makefile create mode 100644 samples/connector/cn_test.c create mode 100644 samples/connector/ucon.c diff --git a/Documentation/Makefile b/Documentation/Makefile index 1207d7907650..13b5ae1b87aa 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/.gitignore b/Documentation/connector/.gitignore deleted file mode 100644 index d2b9c32accd4..000000000000 --- a/Documentation/connector/.gitignore +++ /dev/null @@ -1 +0,0 @@ -ucon diff --git a/Documentation/connector/Makefile b/Documentation/connector/Makefile deleted file mode 100644 index d98e4df98e24..000000000000 --- a/Documentation/connector/Makefile +++ /dev/null @@ -1,16 +0,0 @@ -ifneq ($(CONFIG_CONNECTOR),) -obj-m += cn_test.o -endif - -# List of programs to build -hostprogs-y := ucon - -# Tell kbuild to always build the programs -always := $(hostprogs-y) - -HOSTCFLAGS_ucon.o += -I$(objtree)/usr/include - -all: modules - -modules clean: - $(MAKE) -C ../.. SUBDIRS=$(PWD) $@ diff --git a/Documentation/connector/cn_test.c b/Documentation/connector/cn_test.c deleted file mode 100644 index d12cc944b696..000000000000 --- a/Documentation/connector/cn_test.c +++ /dev/null @@ -1,201 +0,0 @@ -/* - * cn_test.c - * - * 2004+ Copyright (c) Evgeniy Polyakov - * All rights reserved. - * - * This program is free software; you can redistribute it and/or modify - * it under the terms of the GNU General Public License as published by - * the Free Software Foundation; either version 2 of the License, or - * (at your option) any later version. - * - * This program is distributed in the hope that it will be useful, - * but WITHOUT ANY WARRANTY; without even the implied warranty of - * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the - * GNU General Public License for more details. - * - * You should have received a copy of the GNU General Public License - * along with this program; if not, write to the Free Software - * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA - */ - -#define pr_fmt(fmt) "cn_test: " fmt - -#include -#include -#include -#include -#include -#include - -#include - -static struct cb_id cn_test_id = { CN_NETLINK_USERS + 3, 0x456 }; -static char cn_test_name[] = "cn_test"; -static struct sock *nls; -static struct timer_list cn_test_timer; - -static void cn_test_callback(struct cn_msg *msg, struct netlink_skb_parms *nsp) -{ - pr_info("%s: %lu: idx=%x, val=%x, seq=%u, ack=%u, len=%d: %s.\n", - __func__, jiffies, msg->id.idx, msg->id.val, - msg->seq, msg->ack, msg->len, - msg->len ? (char *)msg->data : ""); -} - -/* - * Do not remove this function even if no one is using it as - * this is an example of how to get notifications about new - * connector user registration - */ -#if 0 -static int cn_test_want_notify(void) -{ - struct cn_ctl_msg *ctl; - struct cn_notify_req *req; - struct cn_msg *msg = NULL; - int size, size0; - struct sk_buff *skb; - struct nlmsghdr *nlh; - u32 group = 1; - - size0 = sizeof(*msg) + sizeof(*ctl) + 3 * sizeof(*req); - - size = NLMSG_SPACE(size0); - - skb = alloc_skb(size, GFP_ATOMIC); - if (!skb) { - pr_err("failed to allocate new skb with size=%u\n", size); - return -ENOMEM; - } - - nlh = nlmsg_put(skb, 0, 0x123, NLMSG_DONE, size - sizeof(*nlh), 0); - if (!nlh) { - kfree_skb(skb); - return -EMSGSIZE; - } - - msg = nlmsg_data(nlh); - - memset(msg, 0, size0); - - msg->id.idx = -1; - msg->id.val = -1; - msg->seq = 0x123; - msg->ack = 0x345; - msg->len = size0 - sizeof(*msg); - - ctl = (struct cn_ctl_msg *)(msg + 1); - - ctl->idx_notify_num = 1; - ctl->val_notify_num = 2; - ctl->group = group; - ctl->len = msg->len - sizeof(*ctl); - - req = (struct cn_notify_req *)(ctl + 1); - - /* - * Idx. - */ - req->first = cn_test_id.idx; - req->range = 10; - - /* - * Val 0. - */ - req++; - req->first = cn_test_id.val; - req->range = 10; - - /* - * Val 1. - */ - req++; - req->first = cn_test_id.val + 20; - req->range = 10; - - NETLINK_CB(skb).dst_group = ctl->group; - //netlink_broadcast(nls, skb, 0, ctl->group, GFP_ATOMIC); - netlink_unicast(nls, skb, 0, 0); - - pr_info("request was sent: group=0x%x\n", ctl->group); - - return 0; -} -#endif - -static u32 cn_test_timer_counter; -static void cn_test_timer_func(unsigned long __data) -{ - struct cn_msg *m; - char data[32]; - - pr_debug("%s: timer fired with data %lu\n", __func__, __data); - - m = kzalloc(sizeof(*m) + sizeof(data), GFP_ATOMIC); - if (m) { - - memcpy(&m->id, &cn_test_id, sizeof(m->id)); - m->seq = cn_test_timer_counter; - m->len = sizeof(data); - - m->len = - scnprintf(data, sizeof(data), "counter = %u", - cn_test_timer_counter) + 1; - - memcpy(m + 1, data, m->len); - - cn_netlink_send(m, 0, 0, GFP_ATOMIC); - kfree(m); - } - - cn_test_timer_counter++; - - mod_timer(&cn_test_timer, jiffies + msecs_to_jiffies(1000)); -} - -static int cn_test_init(void) -{ - int err; - - err = cn_add_callback(&cn_test_id, cn_test_name, cn_test_callback); - if (err) - goto err_out; - cn_test_id.val++; - err = cn_add_callback(&cn_test_id, cn_test_name, cn_test_callback); - if (err) { - cn_del_callback(&cn_test_id); - goto err_out; - } - - setup_timer(&cn_test_timer, cn_test_timer_func, 0); - mod_timer(&cn_test_timer, jiffies + msecs_to_jiffies(1000)); - - pr_info("initialized with id={%u.%u}\n", - cn_test_id.idx, cn_test_id.val); - - return 0; - - err_out: - if (nls && nls->sk_socket) - sock_release(nls->sk_socket); - - return err; -} - -static void cn_test_fini(void) -{ - del_timer_sync(&cn_test_timer); - cn_del_callback(&cn_test_id); - cn_test_id.val--; - cn_del_callback(&cn_test_id); - if (nls && nls->sk_socket) - sock_release(nls->sk_socket); -} - -module_init(cn_test_init); -module_exit(cn_test_fini); - -MODULE_LICENSE("GPL"); -MODULE_AUTHOR("Evgeniy Polyakov "); -MODULE_DESCRIPTION("Connector's test module"); diff --git a/Documentation/connector/connector.txt b/Documentation/connector/connector.txt index f6215f95149b..ab7ca897fab7 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/Documentation/connector/ucon.c b/Documentation/connector/ucon.c deleted file mode 100644 index 8a4da64e02a8..000000000000 --- a/Documentation/connector/ucon.c +++ /dev/null @@ -1,250 +0,0 @@ -/* - * ucon.c - * - * Copyright (c) 2004+ Evgeniy Polyakov - * - * - * This program is free software; you can redistribute it and/or modify - * it under the terms of the GNU General Public License as published by - * the Free Software Foundation; either version 2 of the License, or - * (at your option) any later version. - * - * This program is distributed in the hope that it will be useful, - * but WITHOUT ANY WARRANTY; without even the implied warranty of - * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the - * GNU General Public License for more details. - * - * You should have received a copy of the GNU General Public License - * along with this program; if not, write to the Free Software - * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA - */ - -#include - -#include -#include -#include - -#include -#include - -#include - -#include -#include -#include -#include -#include -#include -#include -#include - -#include - -#define DEBUG -#define NETLINK_CONNECTOR 11 - -/* Hopefully your userspace connector.h matches this kernel */ -#define CN_TEST_IDX CN_NETLINK_USERS + 3 -#define CN_TEST_VAL 0x456 - -#ifdef DEBUG -#define ulog(f, a...) fprintf(stdout, f, ##a) -#else -#define ulog(f, a...) do {} while (0) -#endif - -static int need_exit; -static __u32 seq; - -static int netlink_send(int s, struct cn_msg *msg) -{ - struct nlmsghdr *nlh; - unsigned int size; - int err; - char buf[128]; - struct cn_msg *m; - - size = NLMSG_SPACE(sizeof(struct cn_msg) + msg->len); - - nlh = (struct nlmsghdr *)buf; - nlh->nlmsg_seq = seq++; - nlh->nlmsg_pid = getpid(); - nlh->nlmsg_type = NLMSG_DONE; - nlh->nlmsg_len = size; - nlh->nlmsg_flags = 0; - - m = NLMSG_DATA(nlh); -#if 0 - ulog("%s: [%08x.%08x] len=%u, seq=%u, ack=%u.\n", - __func__, msg->id.idx, msg->id.val, msg->len, msg->seq, msg->ack); -#endif - memcpy(m, msg, sizeof(*m) + msg->len); - - err = send(s, nlh, size, 0); - if (err == -1) - ulog("Failed to send: %s [%d].\n", - strerror(errno), errno); - - return err; -} - -static void usage(void) -{ - printf( - "Usage: ucon [options] [output file]\n" - "\n" - "\t-h\tthis help screen\n" - "\t-s\tsend buffers to the test module\n" - "\n" - "The default behavior of ucon is to subscribe to the test module\n" - "and wait for state messages. Any ones received are dumped to the\n" - "specified output file (or stdout). The test module is assumed to\n" - "have an id of {%u.%u}\n" - "\n" - "If you get no output, then verify the cn_test module id matches\n" - "the expected id above.\n" - , CN_TEST_IDX, CN_TEST_VAL - ); -} - -int main(int argc, char *argv[]) -{ - int s; - char buf[1024]; - int len; - struct nlmsghdr *reply; - struct sockaddr_nl l_local; - struct cn_msg *data; - FILE *out; - time_t tm; - struct pollfd pfd; - bool send_msgs = false; - - while ((s = getopt(argc, argv, "hs")) != -1) { - switch (s) { - case 's': - send_msgs = true; - break; - - case 'h': - usage(); - return 0; - - default: - /* getopt() outputs an error for us */ - usage(); - return 1; - } - } - - if (argc != optind) { - out = fopen(argv[optind], "a+"); - if (!out) { - ulog("Unable to open %s for writing: %s\n", - argv[1], strerror(errno)); - out = stdout; - } - } else - out = stdout; - - memset(buf, 0, sizeof(buf)); - - s = socket(PF_NETLINK, SOCK_DGRAM, NETLINK_CONNECTOR); - if (s == -1) { - perror("socket"); - return -1; - } - - l_local.nl_family = AF_NETLINK; - l_local.nl_groups = -1; /* bitmask of requested groups */ - l_local.nl_pid = 0; - - ulog("subscribing to %u.%u\n", CN_TEST_IDX, CN_TEST_VAL); - - if (bind(s, (struct sockaddr *)&l_local, sizeof(struct sockaddr_nl)) == -1) { - perror("bind"); - close(s); - return -1; - } - -#if 0 - { - int on = 0x57; /* Additional group number */ - setsockopt(s, SOL_NETLINK, NETLINK_ADD_MEMBERSHIP, &on, sizeof(on)); - } -#endif - if (send_msgs) { - int i, j; - - memset(buf, 0, sizeof(buf)); - - data = (struct cn_msg *)buf; - - data->id.idx = CN_TEST_IDX; - data->id.val = CN_TEST_VAL; - data->seq = seq++; - data->ack = 0; - data->len = 0; - - for (j=0; j<10; ++j) { - for (i=0; i<1000; ++i) { - len = netlink_send(s, data); - } - - ulog("%d messages have been sent to %08x.%08x.\n", i, data->id.idx, data->id.val); - } - - return 0; - } - - - pfd.fd = s; - - while (!need_exit) { - pfd.events = POLLIN; - pfd.revents = 0; - switch (poll(&pfd, 1, -1)) { - case 0: - need_exit = 1; - break; - case -1: - if (errno != EINTR) { - need_exit = 1; - break; - } - continue; - } - if (need_exit) - break; - - memset(buf, 0, sizeof(buf)); - len = recv(s, buf, sizeof(buf), 0); - if (len == -1) { - perror("recv buf"); - close(s); - return -1; - } - reply = (struct nlmsghdr *)buf; - - switch (reply->nlmsg_type) { - case NLMSG_ERROR: - fprintf(out, "Error message received.\n"); - fflush(out); - break; - case NLMSG_DONE: - data = (struct cn_msg *)NLMSG_DATA(reply); - - time(&tm); - fprintf(out, "%.24s : [%x.%x] [%08u.%08u].\n", - ctime(&tm), data->id.idx, data->id.val, data->seq, data->ack); - fflush(out); - break; - default: - break; - } - } - - close(s); - return 0; -} diff --git a/samples/Kconfig b/samples/Kconfig index d54f28c6dc5e..559a58baff6e 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 48001d7e23f0..594ef7d9fa2a 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/samples/connector/.gitignore b/samples/connector/.gitignore new file mode 100644 index 000000000000..d2b9c32accd4 --- /dev/null +++ b/samples/connector/.gitignore @@ -0,0 +1 @@ +ucon diff --git a/samples/connector/Makefile b/samples/connector/Makefile new file mode 100644 index 000000000000..04b9622b6f51 --- /dev/null +++ b/samples/connector/Makefile @@ -0,0 +1,16 @@ +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) + +HOSTCFLAGS_ucon.o += -I$(objtree)/usr/include + +all: modules + +modules clean: + $(MAKE) -C ../.. SUBDIRS=$(PWD) $@ diff --git a/samples/connector/cn_test.c b/samples/connector/cn_test.c new file mode 100644 index 000000000000..d12cc944b696 --- /dev/null +++ b/samples/connector/cn_test.c @@ -0,0 +1,201 @@ +/* + * cn_test.c + * + * 2004+ Copyright (c) Evgeniy Polyakov + * All rights reserved. + * + * This program is free software; you can redistribute it and/or modify + * it under the terms of the GNU General Public License as published by + * the Free Software Foundation; either version 2 of the License, or + * (at your option) any later version. + * + * This program is distributed in the hope that it will be useful, + * but WITHOUT ANY WARRANTY; without even the implied warranty of + * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the + * GNU General Public License for more details. + * + * You should have received a copy of the GNU General Public License + * along with this program; if not, write to the Free Software + * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA + */ + +#define pr_fmt(fmt) "cn_test: " fmt + +#include +#include +#include +#include +#include +#include + +#include + +static struct cb_id cn_test_id = { CN_NETLINK_USERS + 3, 0x456 }; +static char cn_test_name[] = "cn_test"; +static struct sock *nls; +static struct timer_list cn_test_timer; + +static void cn_test_callback(struct cn_msg *msg, struct netlink_skb_parms *nsp) +{ + pr_info("%s: %lu: idx=%x, val=%x, seq=%u, ack=%u, len=%d: %s.\n", + __func__, jiffies, msg->id.idx, msg->id.val, + msg->seq, msg->ack, msg->len, + msg->len ? (char *)msg->data : ""); +} + +/* + * Do not remove this function even if no one is using it as + * this is an example of how to get notifications about new + * connector user registration + */ +#if 0 +static int cn_test_want_notify(void) +{ + struct cn_ctl_msg *ctl; + struct cn_notify_req *req; + struct cn_msg *msg = NULL; + int size, size0; + struct sk_buff *skb; + struct nlmsghdr *nlh; + u32 group = 1; + + size0 = sizeof(*msg) + sizeof(*ctl) + 3 * sizeof(*req); + + size = NLMSG_SPACE(size0); + + skb = alloc_skb(size, GFP_ATOMIC); + if (!skb) { + pr_err("failed to allocate new skb with size=%u\n", size); + return -ENOMEM; + } + + nlh = nlmsg_put(skb, 0, 0x123, NLMSG_DONE, size - sizeof(*nlh), 0); + if (!nlh) { + kfree_skb(skb); + return -EMSGSIZE; + } + + msg = nlmsg_data(nlh); + + memset(msg, 0, size0); + + msg->id.idx = -1; + msg->id.val = -1; + msg->seq = 0x123; + msg->ack = 0x345; + msg->len = size0 - sizeof(*msg); + + ctl = (struct cn_ctl_msg *)(msg + 1); + + ctl->idx_notify_num = 1; + ctl->val_notify_num = 2; + ctl->group = group; + ctl->len = msg->len - sizeof(*ctl); + + req = (struct cn_notify_req *)(ctl + 1); + + /* + * Idx. + */ + req->first = cn_test_id.idx; + req->range = 10; + + /* + * Val 0. + */ + req++; + req->first = cn_test_id.val; + req->range = 10; + + /* + * Val 1. + */ + req++; + req->first = cn_test_id.val + 20; + req->range = 10; + + NETLINK_CB(skb).dst_group = ctl->group; + //netlink_broadcast(nls, skb, 0, ctl->group, GFP_ATOMIC); + netlink_unicast(nls, skb, 0, 0); + + pr_info("request was sent: group=0x%x\n", ctl->group); + + return 0; +} +#endif + +static u32 cn_test_timer_counter; +static void cn_test_timer_func(unsigned long __data) +{ + struct cn_msg *m; + char data[32]; + + pr_debug("%s: timer fired with data %lu\n", __func__, __data); + + m = kzalloc(sizeof(*m) + sizeof(data), GFP_ATOMIC); + if (m) { + + memcpy(&m->id, &cn_test_id, sizeof(m->id)); + m->seq = cn_test_timer_counter; + m->len = sizeof(data); + + m->len = + scnprintf(data, sizeof(data), "counter = %u", + cn_test_timer_counter) + 1; + + memcpy(m + 1, data, m->len); + + cn_netlink_send(m, 0, 0, GFP_ATOMIC); + kfree(m); + } + + cn_test_timer_counter++; + + mod_timer(&cn_test_timer, jiffies + msecs_to_jiffies(1000)); +} + +static int cn_test_init(void) +{ + int err; + + err = cn_add_callback(&cn_test_id, cn_test_name, cn_test_callback); + if (err) + goto err_out; + cn_test_id.val++; + err = cn_add_callback(&cn_test_id, cn_test_name, cn_test_callback); + if (err) { + cn_del_callback(&cn_test_id); + goto err_out; + } + + setup_timer(&cn_test_timer, cn_test_timer_func, 0); + mod_timer(&cn_test_timer, jiffies + msecs_to_jiffies(1000)); + + pr_info("initialized with id={%u.%u}\n", + cn_test_id.idx, cn_test_id.val); + + return 0; + + err_out: + if (nls && nls->sk_socket) + sock_release(nls->sk_socket); + + return err; +} + +static void cn_test_fini(void) +{ + del_timer_sync(&cn_test_timer); + cn_del_callback(&cn_test_id); + cn_test_id.val--; + cn_del_callback(&cn_test_id); + if (nls && nls->sk_socket) + sock_release(nls->sk_socket); +} + +module_init(cn_test_init); +module_exit(cn_test_fini); + +MODULE_LICENSE("GPL"); +MODULE_AUTHOR("Evgeniy Polyakov "); +MODULE_DESCRIPTION("Connector's test module"); diff --git a/samples/connector/ucon.c b/samples/connector/ucon.c new file mode 100644 index 000000000000..8a4da64e02a8 --- /dev/null +++ b/samples/connector/ucon.c @@ -0,0 +1,250 @@ +/* + * ucon.c + * + * Copyright (c) 2004+ Evgeniy Polyakov + * + * + * This program is free software; you can redistribute it and/or modify + * it under the terms of the GNU General Public License as published by + * the Free Software Foundation; either version 2 of the License, or + * (at your option) any later version. + * + * This program is distributed in the hope that it will be useful, + * but WITHOUT ANY WARRANTY; without even the implied warranty of + * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the + * GNU General Public License for more details. + * + * You should have received a copy of the GNU General Public License + * along with this program; if not, write to the Free Software + * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA + */ + +#include + +#include +#include +#include + +#include +#include + +#include + +#include +#include +#include +#include +#include +#include +#include +#include + +#include + +#define DEBUG +#define NETLINK_CONNECTOR 11 + +/* Hopefully your userspace connector.h matches this kernel */ +#define CN_TEST_IDX CN_NETLINK_USERS + 3 +#define CN_TEST_VAL 0x456 + +#ifdef DEBUG +#define ulog(f, a...) fprintf(stdout, f, ##a) +#else +#define ulog(f, a...) do {} while (0) +#endif + +static int need_exit; +static __u32 seq; + +static int netlink_send(int s, struct cn_msg *msg) +{ + struct nlmsghdr *nlh; + unsigned int size; + int err; + char buf[128]; + struct cn_msg *m; + + size = NLMSG_SPACE(sizeof(struct cn_msg) + msg->len); + + nlh = (struct nlmsghdr *)buf; + nlh->nlmsg_seq = seq++; + nlh->nlmsg_pid = getpid(); + nlh->nlmsg_type = NLMSG_DONE; + nlh->nlmsg_len = size; + nlh->nlmsg_flags = 0; + + m = NLMSG_DATA(nlh); +#if 0 + ulog("%s: [%08x.%08x] len=%u, seq=%u, ack=%u.\n", + __func__, msg->id.idx, msg->id.val, msg->len, msg->seq, msg->ack); +#endif + memcpy(m, msg, sizeof(*m) + msg->len); + + err = send(s, nlh, size, 0); + if (err == -1) + ulog("Failed to send: %s [%d].\n", + strerror(errno), errno); + + return err; +} + +static void usage(void) +{ + printf( + "Usage: ucon [options] [output file]\n" + "\n" + "\t-h\tthis help screen\n" + "\t-s\tsend buffers to the test module\n" + "\n" + "The default behavior of ucon is to subscribe to the test module\n" + "and wait for state messages. Any ones received are dumped to the\n" + "specified output file (or stdout). The test module is assumed to\n" + "have an id of {%u.%u}\n" + "\n" + "If you get no output, then verify the cn_test module id matches\n" + "the expected id above.\n" + , CN_TEST_IDX, CN_TEST_VAL + ); +} + +int main(int argc, char *argv[]) +{ + int s; + char buf[1024]; + int len; + struct nlmsghdr *reply; + struct sockaddr_nl l_local; + struct cn_msg *data; + FILE *out; + time_t tm; + struct pollfd pfd; + bool send_msgs = false; + + while ((s = getopt(argc, argv, "hs")) != -1) { + switch (s) { + case 's': + send_msgs = true; + break; + + case 'h': + usage(); + return 0; + + default: + /* getopt() outputs an error for us */ + usage(); + return 1; + } + } + + if (argc != optind) { + out = fopen(argv[optind], "a+"); + if (!out) { + ulog("Unable to open %s for writing: %s\n", + argv[1], strerror(errno)); + out = stdout; + } + } else + out = stdout; + + memset(buf, 0, sizeof(buf)); + + s = socket(PF_NETLINK, SOCK_DGRAM, NETLINK_CONNECTOR); + if (s == -1) { + perror("socket"); + return -1; + } + + l_local.nl_family = AF_NETLINK; + l_local.nl_groups = -1; /* bitmask of requested groups */ + l_local.nl_pid = 0; + + ulog("subscribing to %u.%u\n", CN_TEST_IDX, CN_TEST_VAL); + + if (bind(s, (struct sockaddr *)&l_local, sizeof(struct sockaddr_nl)) == -1) { + perror("bind"); + close(s); + return -1; + } + +#if 0 + { + int on = 0x57; /* Additional group number */ + setsockopt(s, SOL_NETLINK, NETLINK_ADD_MEMBERSHIP, &on, sizeof(on)); + } +#endif + if (send_msgs) { + int i, j; + + memset(buf, 0, sizeof(buf)); + + data = (struct cn_msg *)buf; + + data->id.idx = CN_TEST_IDX; + data->id.val = CN_TEST_VAL; + data->seq = seq++; + data->ack = 0; + data->len = 0; + + for (j=0; j<10; ++j) { + for (i=0; i<1000; ++i) { + len = netlink_send(s, data); + } + + ulog("%d messages have been sent to %08x.%08x.\n", i, data->id.idx, data->id.val); + } + + return 0; + } + + + pfd.fd = s; + + while (!need_exit) { + pfd.events = POLLIN; + pfd.revents = 0; + switch (poll(&pfd, 1, -1)) { + case 0: + need_exit = 1; + break; + case -1: + if (errno != EINTR) { + need_exit = 1; + break; + } + continue; + } + if (need_exit) + break; + + memset(buf, 0, sizeof(buf)); + len = recv(s, buf, sizeof(buf), 0); + if (len == -1) { + perror("recv buf"); + close(s); + return -1; + } + reply = (struct nlmsghdr *)buf; + + switch (reply->nlmsg_type) { + case NLMSG_ERROR: + fprintf(out, "Error message received.\n"); + fflush(out); + break; + case NLMSG_DONE: + data = (struct cn_msg *)NLMSG_DATA(reply); + + time(&tm); + fprintf(out, "%.24s : [%x.%x] [%08u.%08u].\n", + ctime(&tm), data->id.idx, data->id.val, data->seq, data->ack); + fflush(out); + break; + default: + break; + } + } + + close(s); + return 0; +} -- cgit v1.2.3 From 934275c4805ce0bbb0df633bd6015dd455ff6cad Mon Sep 17 00:00:00 2001 From: Arnd Bergmann Date: Mon, 25 Apr 2016 18:03:09 +0200 Subject: 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/Makefile | 1 - Documentation/video4linux/v4l2-framework.txt | 2 +- Documentation/video4linux/v4l2-pci-skeleton.c | 923 -------------------------- samples/Makefile | 2 +- samples/v4l/Makefile | 1 + samples/v4l/v4l2-pci-skeleton.c | 923 ++++++++++++++++++++++++++ 7 files changed, 927 insertions(+), 928 deletions(-) delete mode 100644 Documentation/video4linux/Makefile delete mode 100644 Documentation/video4linux/v4l2-pci-skeleton.c create mode 100644 samples/v4l/Makefile create mode 100644 samples/v4l/v4l2-pci-skeleton.c diff --git a/Documentation/Makefile b/Documentation/Makefile index 13b5ae1b87aa..de955e151af8 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/Makefile b/Documentation/video4linux/Makefile deleted file mode 100644 index 65a351d75c95..000000000000 --- a/Documentation/video4linux/Makefile +++ /dev/null @@ -1 +0,0 @@ -obj-$(CONFIG_VIDEO_PCI_SKELETON) := v4l2-pci-skeleton.o diff --git a/Documentation/video4linux/v4l2-framework.txt b/Documentation/video4linux/v4l2-framework.txt index fa41608ab2b4..cbefc7902f5f 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/Documentation/video4linux/v4l2-pci-skeleton.c b/Documentation/video4linux/v4l2-pci-skeleton.c deleted file mode 100644 index 79af0c041056..000000000000 --- a/Documentation/video4linux/v4l2-pci-skeleton.c +++ /dev/null @@ -1,923 +0,0 @@ -/* - * This is a V4L2 PCI Skeleton Driver. It gives an initial skeleton source - * for use with other PCI drivers. - * - * This skeleton PCI driver assumes that the card has an S-Video connector as - * input 0 and an HDMI connector as input 1. - * - * Copyright 2014 Cisco Systems, Inc. and/or its affiliates. All rights reserved. - * - * This program is free software; you may redistribute it and/or modify - * it under the terms of the GNU General Public License as published by - * the Free Software Foundation; version 2 of the License. - * - * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, - * EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF - * MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND - * NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS - * BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN - * ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN - * CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE - * SOFTWARE. - */ - -#include -#include -#include -#include -#include -#include -#include -#include -#include -#include -#include -#include -#include -#include -#include -#include -#include -#include - -MODULE_DESCRIPTION("V4L2 PCI Skeleton Driver"); -MODULE_AUTHOR("Hans Verkuil"); -MODULE_LICENSE("GPL v2"); - -/** - * struct skeleton - All internal data for one instance of device - * @pdev: PCI device - * @v4l2_dev: top-level v4l2 device struct - * @vdev: video node structure - * @ctrl_handler: control handler structure - * @lock: ioctl serialization mutex - * @std: current SDTV standard - * @timings: current HDTV timings - * @format: current pix format - * @input: current video input (0 = SDTV, 1 = HDTV) - * @queue: vb2 video capture queue - * @alloc_ctx: vb2 contiguous DMA context - * @qlock: spinlock controlling access to buf_list and sequence - * @buf_list: list of buffers queued for DMA - * @sequence: frame sequence counter - */ -struct skeleton { - struct pci_dev *pdev; - struct v4l2_device v4l2_dev; - struct video_device vdev; - struct v4l2_ctrl_handler ctrl_handler; - struct mutex lock; - v4l2_std_id std; - struct v4l2_dv_timings timings; - struct v4l2_pix_format format; - unsigned input; - - struct vb2_queue queue; - struct vb2_alloc_ctx *alloc_ctx; - - spinlock_t qlock; - struct list_head buf_list; - unsigned field; - unsigned sequence; -}; - -struct skel_buffer { - struct vb2_buffer vb; - struct list_head list; -}; - -static inline struct skel_buffer *to_skel_buffer(struct vb2_buffer *vb2) -{ - return container_of(vb2, struct skel_buffer, vb); -} - -static const struct pci_device_id skeleton_pci_tbl[] = { - /* { PCI_DEVICE(PCI_VENDOR_ID_, PCI_DEVICE_ID_) }, */ - { 0, } -}; -MODULE_DEVICE_TABLE(pci, skeleton_pci_tbl); - -/* - * HDTV: this structure has the capabilities of the HDTV receiver. - * It is used to constrain the huge list of possible formats based - * upon the hardware capabilities. - */ -static const struct v4l2_dv_timings_cap skel_timings_cap = { - .type = V4L2_DV_BT_656_1120, - /* keep this initialization for compatibility with GCC < 4.4.6 */ - .reserved = { 0 }, - V4L2_INIT_BT_TIMINGS( - 720, 1920, /* min/max width */ - 480, 1080, /* min/max height */ - 27000000, 74250000, /* min/max pixelclock*/ - V4L2_DV_BT_STD_CEA861, /* Supported standards */ - /* capabilities */ - V4L2_DV_BT_CAP_INTERLACED | V4L2_DV_BT_CAP_PROGRESSIVE - ) -}; - -/* - * Supported SDTV standards. This does the same job as skel_timings_cap, but - * for standard TV formats. - */ -#define SKEL_TVNORMS V4L2_STD_ALL - -/* - * Interrupt handler: typically interrupts happen after a new frame has been - * captured. It is the job of the handler to remove the new frame from the - * internal list and give it back to the vb2 framework, updating the sequence - * counter, field and timestamp at the same time. - */ -static irqreturn_t skeleton_irq(int irq, void *dev_id) -{ -#ifdef TODO - struct skeleton *skel = dev_id; - - /* handle interrupt */ - - /* Once a new frame has been captured, mark it as done like this: */ - if (captured_new_frame) { - ... - spin_lock(&skel->qlock); - list_del(&new_buf->list); - spin_unlock(&skel->qlock); - v4l2_get_timestamp(&new_buf->vb.v4l2_buf.timestamp); - new_buf->vb.v4l2_buf.sequence = skel->sequence++; - new_buf->vb.v4l2_buf.field = skel->field; - if (skel->format.field == V4L2_FIELD_ALTERNATE) { - if (skel->field == V4L2_FIELD_BOTTOM) - skel->field = V4L2_FIELD_TOP; - else if (skel->field == V4L2_FIELD_TOP) - skel->field = V4L2_FIELD_BOTTOM; - } - vb2_buffer_done(&new_buf->vb, VB2_BUF_STATE_DONE); - } -#endif - return IRQ_HANDLED; -} - -/* - * Setup the constraints of the queue: besides setting the number of planes - * per buffer and the size and allocation context of each plane, it also - * checks if sufficient buffers have been allocated. Usually 3 is a good - * minimum number: many DMA engines need a minimum of 2 buffers in the - * queue and you need to have another available for userspace processing. - */ -static int queue_setup(struct vb2_queue *vq, - unsigned int *nbuffers, unsigned int *nplanes, - unsigned int sizes[], void *alloc_ctxs[]) -{ - struct skeleton *skel = vb2_get_drv_priv(vq); - - skel->field = skel->format.field; - if (skel->field == V4L2_FIELD_ALTERNATE) { - /* - * You cannot use read() with FIELD_ALTERNATE since the field - * information (TOP/BOTTOM) cannot be passed back to the user. - */ - if (vb2_fileio_is_active(vq)) - return -EINVAL; - skel->field = V4L2_FIELD_TOP; - } - - if (vq->num_buffers + *nbuffers < 3) - *nbuffers = 3 - vq->num_buffers; - alloc_ctxs[0] = skel->alloc_ctx; - - if (*nplanes) - return sizes[0] < skel->format.sizeimage ? -EINVAL : 0; - *nplanes = 1; - sizes[0] = skel->format.sizeimage; - return 0; -} - -/* - * Prepare the buffer for queueing to the DMA engine: check and set the - * payload size. - */ -static int buffer_prepare(struct vb2_buffer *vb) -{ - struct skeleton *skel = vb2_get_drv_priv(vb->vb2_queue); - unsigned long size = skel->format.sizeimage; - - if (vb2_plane_size(vb, 0) < size) { - dev_err(&skel->pdev->dev, "buffer too small (%lu < %lu)\n", - vb2_plane_size(vb, 0), size); - return -EINVAL; - } - - vb2_set_plane_payload(vb, 0, size); - return 0; -} - -/* - * Queue this buffer to the DMA engine. - */ -static void buffer_queue(struct vb2_buffer *vb) -{ - struct skeleton *skel = vb2_get_drv_priv(vb->vb2_queue); - struct skel_buffer *buf = to_skel_buffer(vb); - unsigned long flags; - - spin_lock_irqsave(&skel->qlock, flags); - list_add_tail(&buf->list, &skel->buf_list); - - /* TODO: Update any DMA pointers if necessary */ - - spin_unlock_irqrestore(&skel->qlock, flags); -} - -static void return_all_buffers(struct skeleton *skel, - enum vb2_buffer_state state) -{ - struct skel_buffer *buf, *node; - unsigned long flags; - - spin_lock_irqsave(&skel->qlock, flags); - list_for_each_entry_safe(buf, node, &skel->buf_list, list) { - vb2_buffer_done(&buf->vb, state); - list_del(&buf->list); - } - spin_unlock_irqrestore(&skel->qlock, flags); -} - -/* - * Start streaming. First check if the minimum number of buffers have been - * queued. If not, then return -ENOBUFS and the vb2 framework will call - * this function again the next time a buffer has been queued until enough - * buffers are available to actually start the DMA engine. - */ -static int start_streaming(struct vb2_queue *vq, unsigned int count) -{ - struct skeleton *skel = vb2_get_drv_priv(vq); - int ret = 0; - - skel->sequence = 0; - - /* TODO: start DMA */ - - if (ret) { - /* - * In case of an error, return all active buffers to the - * QUEUED state - */ - return_all_buffers(skel, VB2_BUF_STATE_QUEUED); - } - return ret; -} - -/* - * Stop the DMA engine. Any remaining buffers in the DMA queue are dequeued - * and passed on to the vb2 framework marked as STATE_ERROR. - */ -static void stop_streaming(struct vb2_queue *vq) -{ - struct skeleton *skel = vb2_get_drv_priv(vq); - - /* TODO: stop DMA */ - - /* Release all active buffers */ - return_all_buffers(skel, VB2_BUF_STATE_ERROR); -} - -/* - * The vb2 queue ops. Note that since q->lock is set we can use the standard - * vb2_ops_wait_prepare/finish helper functions. If q->lock would be NULL, - * then this driver would have to provide these ops. - */ -static struct vb2_ops skel_qops = { - .queue_setup = queue_setup, - .buf_prepare = buffer_prepare, - .buf_queue = buffer_queue, - .start_streaming = start_streaming, - .stop_streaming = stop_streaming, - .wait_prepare = vb2_ops_wait_prepare, - .wait_finish = vb2_ops_wait_finish, -}; - -/* - * Required ioctl querycap. Note that the version field is prefilled with - * the version of the kernel. - */ -static int skeleton_querycap(struct file *file, void *priv, - struct v4l2_capability *cap) -{ - struct skeleton *skel = video_drvdata(file); - - strlcpy(cap->driver, KBUILD_MODNAME, sizeof(cap->driver)); - strlcpy(cap->card, "V4L2 PCI Skeleton", sizeof(cap->card)); - snprintf(cap->bus_info, sizeof(cap->bus_info), "PCI:%s", - pci_name(skel->pdev)); - cap->device_caps = V4L2_CAP_VIDEO_CAPTURE | V4L2_CAP_READWRITE | - V4L2_CAP_STREAMING; - cap->capabilities = cap->device_caps | V4L2_CAP_DEVICE_CAPS; - return 0; -} - -/* - * Helper function to check and correct struct v4l2_pix_format. It's used - * not only in VIDIOC_TRY/S_FMT, but also elsewhere if changes to the SDTV - * standard, HDTV timings or the video input would require updating the - * current format. - */ -static void skeleton_fill_pix_format(struct skeleton *skel, - struct v4l2_pix_format *pix) -{ - pix->pixelformat = V4L2_PIX_FMT_YUYV; - if (skel->input == 0) { - /* S-Video input */ - pix->width = 720; - pix->height = (skel->std & V4L2_STD_525_60) ? 480 : 576; - pix->field = V4L2_FIELD_INTERLACED; - pix->colorspace = V4L2_COLORSPACE_SMPTE170M; - } else { - /* HDMI input */ - pix->width = skel->timings.bt.width; - pix->height = skel->timings.bt.height; - if (skel->timings.bt.interlaced) { - pix->field = V4L2_FIELD_ALTERNATE; - pix->height /= 2; - } else { - pix->field = V4L2_FIELD_NONE; - } - pix->colorspace = V4L2_COLORSPACE_REC709; - } - - /* - * The YUYV format is four bytes for every two pixels, so bytesperline - * is width * 2. - */ - pix->bytesperline = pix->width * 2; - pix->sizeimage = pix->bytesperline * pix->height; - pix->priv = 0; -} - -static int skeleton_try_fmt_vid_cap(struct file *file, void *priv, - struct v4l2_format *f) -{ - struct skeleton *skel = video_drvdata(file); - struct v4l2_pix_format *pix = &f->fmt.pix; - - /* - * Due to historical reasons providing try_fmt with an unsupported - * pixelformat will return -EINVAL for video receivers. Webcam drivers, - * however, will silently correct the pixelformat. Some video capture - * applications rely on this behavior... - */ - if (pix->pixelformat != V4L2_PIX_FMT_YUYV) - return -EINVAL; - skeleton_fill_pix_format(skel, pix); - return 0; -} - -static int skeleton_s_fmt_vid_cap(struct file *file, void *priv, - struct v4l2_format *f) -{ - struct skeleton *skel = video_drvdata(file); - int ret; - - ret = skeleton_try_fmt_vid_cap(file, priv, f); - if (ret) - return ret; - - /* - * It is not allowed to change the format while buffers for use with - * streaming have already been allocated. - */ - if (vb2_is_busy(&skel->queue)) - return -EBUSY; - - /* TODO: change format */ - skel->format = f->fmt.pix; - return 0; -} - -static int skeleton_g_fmt_vid_cap(struct file *file, void *priv, - struct v4l2_format *f) -{ - struct skeleton *skel = video_drvdata(file); - - f->fmt.pix = skel->format; - return 0; -} - -static int skeleton_enum_fmt_vid_cap(struct file *file, void *priv, - struct v4l2_fmtdesc *f) -{ - if (f->index != 0) - return -EINVAL; - - f->pixelformat = V4L2_PIX_FMT_YUYV; - return 0; -} - -static int skeleton_s_std(struct file *file, void *priv, v4l2_std_id std) -{ - struct skeleton *skel = video_drvdata(file); - - /* S_STD is not supported on the HDMI input */ - if (skel->input) - return -ENODATA; - - /* - * No change, so just return. Some applications call S_STD again after - * the buffers for streaming have been set up, so we have to allow for - * this behavior. - */ - if (std == skel->std) - return 0; - - /* - * Changing the standard implies a format change, which is not allowed - * while buffers for use with streaming have already been allocated. - */ - if (vb2_is_busy(&skel->queue)) - return -EBUSY; - - /* TODO: handle changing std */ - - skel->std = std; - - /* Update the internal format */ - skeleton_fill_pix_format(skel, &skel->format); - return 0; -} - -static int skeleton_g_std(struct file *file, void *priv, v4l2_std_id *std) -{ - struct skeleton *skel = video_drvdata(file); - - /* G_STD is not supported on the HDMI input */ - if (skel->input) - return -ENODATA; - - *std = skel->std; - return 0; -} - -/* - * Query the current standard as seen by the hardware. This function shall - * never actually change the standard, it just detects and reports. - * The framework will initially set *std to tvnorms (i.e. the set of - * supported standards by this input), and this function should just AND - * this value. If there is no signal, then *std should be set to 0. - */ -static int skeleton_querystd(struct file *file, void *priv, v4l2_std_id *std) -{ - struct skeleton *skel = video_drvdata(file); - - /* QUERY_STD is not supported on the HDMI input */ - if (skel->input) - return -ENODATA; - -#ifdef TODO - /* - * Query currently seen standard. Initial value of *std is - * V4L2_STD_ALL. This function should look something like this: - */ - get_signal_info(); - if (no_signal) { - *std = 0; - return 0; - } - /* Use signal information to reduce the number of possible standards */ - if (signal_has_525_lines) - *std &= V4L2_STD_525_60; - else - *std &= V4L2_STD_625_50; -#endif - return 0; -} - -static int skeleton_s_dv_timings(struct file *file, void *_fh, - struct v4l2_dv_timings *timings) -{ - struct skeleton *skel = video_drvdata(file); - - /* S_DV_TIMINGS is not supported on the S-Video input */ - if (skel->input == 0) - return -ENODATA; - - /* Quick sanity check */ - if (!v4l2_valid_dv_timings(timings, &skel_timings_cap, NULL, NULL)) - return -EINVAL; - - /* Check if the timings are part of the CEA-861 timings. */ - if (!v4l2_find_dv_timings_cap(timings, &skel_timings_cap, - 0, NULL, NULL)) - return -EINVAL; - - /* Return 0 if the new timings are the same as the current timings. */ - if (v4l2_match_dv_timings(timings, &skel->timings, 0, false)) - return 0; - - /* - * Changing the timings implies a format change, which is not allowed - * while buffers for use with streaming have already been allocated. - */ - if (vb2_is_busy(&skel->queue)) - return -EBUSY; - - /* TODO: Configure new timings */ - - /* Save timings */ - skel->timings = *timings; - - /* Update the internal format */ - skeleton_fill_pix_format(skel, &skel->format); - return 0; -} - -static int skeleton_g_dv_timings(struct file *file, void *_fh, - struct v4l2_dv_timings *timings) -{ - struct skeleton *skel = video_drvdata(file); - - /* G_DV_TIMINGS is not supported on the S-Video input */ - if (skel->input == 0) - return -ENODATA; - - *timings = skel->timings; - return 0; -} - -static int skeleton_enum_dv_timings(struct file *file, void *_fh, - struct v4l2_enum_dv_timings *timings) -{ - struct skeleton *skel = video_drvdata(file); - - /* ENUM_DV_TIMINGS is not supported on the S-Video input */ - if (skel->input == 0) - return -ENODATA; - - return v4l2_enum_dv_timings_cap(timings, &skel_timings_cap, - NULL, NULL); -} - -/* - * Query the current timings as seen by the hardware. This function shall - * never actually change the timings, it just detects and reports. - * If no signal is detected, then return -ENOLINK. If the hardware cannot - * lock to the signal, then return -ENOLCK. If the signal is out of range - * of the capabilities of the system (e.g., it is possible that the receiver - * can lock but that the DMA engine it is connected to cannot handle - * pixelclocks above a certain frequency), then -ERANGE is returned. - */ -static int skeleton_query_dv_timings(struct file *file, void *_fh, - struct v4l2_dv_timings *timings) -{ - struct skeleton *skel = video_drvdata(file); - - /* QUERY_DV_TIMINGS is not supported on the S-Video input */ - if (skel->input == 0) - return -ENODATA; - -#ifdef TODO - /* - * Query currently seen timings. This function should look - * something like this: - */ - detect_timings(); - if (no_signal) - return -ENOLINK; - if (cannot_lock_to_signal) - return -ENOLCK; - if (signal_out_of_range_of_capabilities) - return -ERANGE; - - /* Useful for debugging */ - v4l2_print_dv_timings(skel->v4l2_dev.name, "query_dv_timings:", - timings, true); -#endif - return 0; -} - -static int skeleton_dv_timings_cap(struct file *file, void *fh, - struct v4l2_dv_timings_cap *cap) -{ - struct skeleton *skel = video_drvdata(file); - - /* DV_TIMINGS_CAP is not supported on the S-Video input */ - if (skel->input == 0) - return -ENODATA; - *cap = skel_timings_cap; - return 0; -} - -static int skeleton_enum_input(struct file *file, void *priv, - struct v4l2_input *i) -{ - if (i->index > 1) - return -EINVAL; - - i->type = V4L2_INPUT_TYPE_CAMERA; - if (i->index == 0) { - i->std = SKEL_TVNORMS; - strlcpy(i->name, "S-Video", sizeof(i->name)); - i->capabilities = V4L2_IN_CAP_STD; - } else { - i->std = 0; - strlcpy(i->name, "HDMI", sizeof(i->name)); - i->capabilities = V4L2_IN_CAP_DV_TIMINGS; - } - return 0; -} - -static int skeleton_s_input(struct file *file, void *priv, unsigned int i) -{ - struct skeleton *skel = video_drvdata(file); - - if (i > 1) - return -EINVAL; - - /* - * Changing the input implies a format change, which is not allowed - * while buffers for use with streaming have already been allocated. - */ - if (vb2_is_busy(&skel->queue)) - return -EBUSY; - - skel->input = i; - /* - * Update tvnorms. The tvnorms value is used by the core to implement - * VIDIOC_ENUMSTD so it has to be correct. If tvnorms == 0, then - * ENUMSTD will return -ENODATA. - */ - skel->vdev.tvnorms = i ? 0 : SKEL_TVNORMS; - - /* Update the internal format */ - skeleton_fill_pix_format(skel, &skel->format); - return 0; -} - -static int skeleton_g_input(struct file *file, void *priv, unsigned int *i) -{ - struct skeleton *skel = video_drvdata(file); - - *i = skel->input; - return 0; -} - -/* The control handler. */ -static int skeleton_s_ctrl(struct v4l2_ctrl *ctrl) -{ - /*struct skeleton *skel = - container_of(ctrl->handler, struct skeleton, ctrl_handler);*/ - - switch (ctrl->id) { - case V4L2_CID_BRIGHTNESS: - /* TODO: set brightness to ctrl->val */ - break; - case V4L2_CID_CONTRAST: - /* TODO: set contrast to ctrl->val */ - break; - case V4L2_CID_SATURATION: - /* TODO: set saturation to ctrl->val */ - break; - case V4L2_CID_HUE: - /* TODO: set hue to ctrl->val */ - break; - default: - return -EINVAL; - } - return 0; -} - -/* ------------------------------------------------------------------ - File operations for the device - ------------------------------------------------------------------*/ - -static const struct v4l2_ctrl_ops skel_ctrl_ops = { - .s_ctrl = skeleton_s_ctrl, -}; - -/* - * The set of all supported ioctls. Note that all the streaming ioctls - * use the vb2 helper functions that take care of all the locking and - * that also do ownership tracking (i.e. only the filehandle that requested - * the buffers can call the streaming ioctls, all other filehandles will - * receive -EBUSY if they attempt to call the same streaming ioctls). - * - * The last three ioctls also use standard helper functions: these implement - * standard behavior for drivers with controls. - */ -static const struct v4l2_ioctl_ops skel_ioctl_ops = { - .vidioc_querycap = skeleton_querycap, - .vidioc_try_fmt_vid_cap = skeleton_try_fmt_vid_cap, - .vidioc_s_fmt_vid_cap = skeleton_s_fmt_vid_cap, - .vidioc_g_fmt_vid_cap = skeleton_g_fmt_vid_cap, - .vidioc_enum_fmt_vid_cap = skeleton_enum_fmt_vid_cap, - - .vidioc_g_std = skeleton_g_std, - .vidioc_s_std = skeleton_s_std, - .vidioc_querystd = skeleton_querystd, - - .vidioc_s_dv_timings = skeleton_s_dv_timings, - .vidioc_g_dv_timings = skeleton_g_dv_timings, - .vidioc_enum_dv_timings = skeleton_enum_dv_timings, - .vidioc_query_dv_timings = skeleton_query_dv_timings, - .vidioc_dv_timings_cap = skeleton_dv_timings_cap, - - .vidioc_enum_input = skeleton_enum_input, - .vidioc_g_input = skeleton_g_input, - .vidioc_s_input = skeleton_s_input, - - .vidioc_reqbufs = vb2_ioctl_reqbufs, - .vidioc_create_bufs = vb2_ioctl_create_bufs, - .vidioc_querybuf = vb2_ioctl_querybuf, - .vidioc_qbuf = vb2_ioctl_qbuf, - .vidioc_dqbuf = vb2_ioctl_dqbuf, - .vidioc_expbuf = vb2_ioctl_expbuf, - .vidioc_streamon = vb2_ioctl_streamon, - .vidioc_streamoff = vb2_ioctl_streamoff, - - .vidioc_log_status = v4l2_ctrl_log_status, - .vidioc_subscribe_event = v4l2_ctrl_subscribe_event, - .vidioc_unsubscribe_event = v4l2_event_unsubscribe, -}; - -/* - * The set of file operations. Note that all these ops are standard core - * helper functions. - */ -static const struct v4l2_file_operations skel_fops = { - .owner = THIS_MODULE, - .open = v4l2_fh_open, - .release = vb2_fop_release, - .unlocked_ioctl = video_ioctl2, - .read = vb2_fop_read, - .mmap = vb2_fop_mmap, - .poll = vb2_fop_poll, -}; - -/* - * The initial setup of this device instance. Note that the initial state of - * the driver should be complete. So the initial format, standard, timings - * and video input should all be initialized to some reasonable value. - */ -static int skeleton_probe(struct pci_dev *pdev, const struct pci_device_id *ent) -{ - /* The initial timings are chosen to be 720p60. */ - static const struct v4l2_dv_timings timings_def = - V4L2_DV_BT_CEA_1280X720P60; - struct skeleton *skel; - struct video_device *vdev; - struct v4l2_ctrl_handler *hdl; - struct vb2_queue *q; - int ret; - - /* Enable PCI */ - ret = pci_enable_device(pdev); - if (ret) - return ret; - ret = pci_set_dma_mask(pdev, DMA_BIT_MASK(32)); - if (ret) { - dev_err(&pdev->dev, "no suitable DMA available.\n"); - goto disable_pci; - } - - /* Allocate a new instance */ - skel = devm_kzalloc(&pdev->dev, sizeof(struct skeleton), GFP_KERNEL); - if (!skel) - return -ENOMEM; - - /* Allocate the interrupt */ - ret = devm_request_irq(&pdev->dev, pdev->irq, - skeleton_irq, 0, KBUILD_MODNAME, skel); - if (ret) { - dev_err(&pdev->dev, "request_irq failed\n"); - goto disable_pci; - } - skel->pdev = pdev; - - /* Fill in the initial format-related settings */ - skel->timings = timings_def; - skel->std = V4L2_STD_625_50; - skeleton_fill_pix_format(skel, &skel->format); - - /* Initialize the top-level structure */ - ret = v4l2_device_register(&pdev->dev, &skel->v4l2_dev); - if (ret) - goto disable_pci; - - mutex_init(&skel->lock); - - /* Add the controls */ - hdl = &skel->ctrl_handler; - v4l2_ctrl_handler_init(hdl, 4); - v4l2_ctrl_new_std(hdl, &skel_ctrl_ops, - V4L2_CID_BRIGHTNESS, 0, 255, 1, 127); - v4l2_ctrl_new_std(hdl, &skel_ctrl_ops, - V4L2_CID_CONTRAST, 0, 255, 1, 16); - v4l2_ctrl_new_std(hdl, &skel_ctrl_ops, - V4L2_CID_SATURATION, 0, 255, 1, 127); - v4l2_ctrl_new_std(hdl, &skel_ctrl_ops, - V4L2_CID_HUE, -128, 127, 1, 0); - if (hdl->error) { - ret = hdl->error; - goto free_hdl; - } - skel->v4l2_dev.ctrl_handler = hdl; - - /* Initialize the vb2 queue */ - q = &skel->queue; - q->type = V4L2_BUF_TYPE_VIDEO_CAPTURE; - q->io_modes = VB2_MMAP | VB2_DMABUF | VB2_READ; - q->drv_priv = skel; - q->buf_struct_size = sizeof(struct skel_buffer); - q->ops = &skel_qops; - q->mem_ops = &vb2_dma_contig_memops; - q->timestamp_flags = V4L2_BUF_FLAG_TIMESTAMP_MONOTONIC; - /* - * Assume that this DMA engine needs to have at least two buffers - * available before it can be started. The start_streaming() op - * won't be called until at least this many buffers are queued up. - */ - q->min_buffers_needed = 2; - /* - * The serialization lock for the streaming ioctls. This is the same - * as the main serialization lock, but if some of the non-streaming - * ioctls could take a long time to execute, then you might want to - * have a different lock here to prevent VIDIOC_DQBUF from being - * blocked while waiting for another action to finish. This is - * generally not needed for PCI devices, but USB devices usually do - * want a separate lock here. - */ - q->lock = &skel->lock; - /* - * Since this driver can only do 32-bit DMA we must make sure that - * the vb2 core will allocate the buffers in 32-bit DMA memory. - */ - q->gfp_flags = GFP_DMA32; - ret = vb2_queue_init(q); - if (ret) - goto free_hdl; - - skel->alloc_ctx = vb2_dma_contig_init_ctx(&pdev->dev); - if (IS_ERR(skel->alloc_ctx)) { - dev_err(&pdev->dev, "Can't allocate buffer context"); - ret = PTR_ERR(skel->alloc_ctx); - goto free_hdl; - } - INIT_LIST_HEAD(&skel->buf_list); - spin_lock_init(&skel->qlock); - - /* Initialize the video_device structure */ - vdev = &skel->vdev; - strlcpy(vdev->name, KBUILD_MODNAME, sizeof(vdev->name)); - /* - * There is nothing to clean up, so release is set to an empty release - * function. The release callback must be non-NULL. - */ - vdev->release = video_device_release_empty; - vdev->fops = &skel_fops, - vdev->ioctl_ops = &skel_ioctl_ops, - /* - * The main serialization lock. All ioctls are serialized by this - * lock. Exception: if q->lock is set, then the streaming ioctls - * are serialized by that separate lock. - */ - vdev->lock = &skel->lock; - vdev->queue = q; - vdev->v4l2_dev = &skel->v4l2_dev; - /* Supported SDTV standards, if any */ - vdev->tvnorms = SKEL_TVNORMS; - video_set_drvdata(vdev, skel); - - ret = video_register_device(vdev, VFL_TYPE_GRABBER, -1); - if (ret) - goto free_ctx; - - dev_info(&pdev->dev, "V4L2 PCI Skeleton Driver loaded\n"); - return 0; - -free_ctx: - vb2_dma_contig_cleanup_ctx(skel->alloc_ctx); -free_hdl: - v4l2_ctrl_handler_free(&skel->ctrl_handler); - v4l2_device_unregister(&skel->v4l2_dev); -disable_pci: - pci_disable_device(pdev); - return ret; -} - -static void skeleton_remove(struct pci_dev *pdev) -{ - struct v4l2_device *v4l2_dev = pci_get_drvdata(pdev); - struct skeleton *skel = container_of(v4l2_dev, struct skeleton, v4l2_dev); - - video_unregister_device(&skel->vdev); - v4l2_ctrl_handler_free(&skel->ctrl_handler); - vb2_dma_contig_cleanup_ctx(skel->alloc_ctx); - v4l2_device_unregister(&skel->v4l2_dev); - pci_disable_device(skel->pdev); -} - -static struct pci_driver skeleton_driver = { - .name = KBUILD_MODNAME, - .probe = skeleton_probe, - .remove = skeleton_remove, - .id_table = skeleton_pci_tbl, -}; - -module_pci_driver(skeleton_driver); diff --git a/samples/Makefile b/samples/Makefile index 594ef7d9fa2a..2e3b523d7097 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/samples/v4l/Makefile b/samples/v4l/Makefile new file mode 100644 index 000000000000..65a351d75c95 --- /dev/null +++ b/samples/v4l/Makefile @@ -0,0 +1 @@ +obj-$(CONFIG_VIDEO_PCI_SKELETON) := v4l2-pci-skeleton.o diff --git a/samples/v4l/v4l2-pci-skeleton.c b/samples/v4l/v4l2-pci-skeleton.c new file mode 100644 index 000000000000..79af0c041056 --- /dev/null +++ b/samples/v4l/v4l2-pci-skeleton.c @@ -0,0 +1,923 @@ +/* + * This is a V4L2 PCI Skeleton Driver. It gives an initial skeleton source + * for use with other PCI drivers. + * + * This skeleton PCI driver assumes that the card has an S-Video connector as + * input 0 and an HDMI connector as input 1. + * + * Copyright 2014 Cisco Systems, Inc. and/or its affiliates. All rights reserved. + * + * This program is free software; you may redistribute it and/or modify + * it under the terms of the GNU General Public License as published by + * the Free Software Foundation; version 2 of the License. + * + * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, + * EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF + * MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND + * NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS + * BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN + * ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN + * CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE + * SOFTWARE. + */ + +#include +#include +#include +#include +#include +#include +#include +#include +#include +#include +#include +#include +#include +#include +#include +#include +#include +#include + +MODULE_DESCRIPTION("V4L2 PCI Skeleton Driver"); +MODULE_AUTHOR("Hans Verkuil"); +MODULE_LICENSE("GPL v2"); + +/** + * struct skeleton - All internal data for one instance of device + * @pdev: PCI device + * @v4l2_dev: top-level v4l2 device struct + * @vdev: video node structure + * @ctrl_handler: control handler structure + * @lock: ioctl serialization mutex + * @std: current SDTV standard + * @timings: current HDTV timings + * @format: current pix format + * @input: current video input (0 = SDTV, 1 = HDTV) + * @queue: vb2 video capture queue + * @alloc_ctx: vb2 contiguous DMA context + * @qlock: spinlock controlling access to buf_list and sequence + * @buf_list: list of buffers queued for DMA + * @sequence: frame sequence counter + */ +struct skeleton { + struct pci_dev *pdev; + struct v4l2_device v4l2_dev; + struct video_device vdev; + struct v4l2_ctrl_handler ctrl_handler; + struct mutex lock; + v4l2_std_id std; + struct v4l2_dv_timings timings; + struct v4l2_pix_format format; + unsigned input; + + struct vb2_queue queue; + struct vb2_alloc_ctx *alloc_ctx; + + spinlock_t qlock; + struct list_head buf_list; + unsigned field; + unsigned sequence; +}; + +struct skel_buffer { + struct vb2_buffer vb; + struct list_head list; +}; + +static inline struct skel_buffer *to_skel_buffer(struct vb2_buffer *vb2) +{ + return container_of(vb2, struct skel_buffer, vb); +} + +static const struct pci_device_id skeleton_pci_tbl[] = { + /* { PCI_DEVICE(PCI_VENDOR_ID_, PCI_DEVICE_ID_) }, */ + { 0, } +}; +MODULE_DEVICE_TABLE(pci, skeleton_pci_tbl); + +/* + * HDTV: this structure has the capabilities of the HDTV receiver. + * It is used to constrain the huge list of possible formats based + * upon the hardware capabilities. + */ +static const struct v4l2_dv_timings_cap skel_timings_cap = { + .type = V4L2_DV_BT_656_1120, + /* keep this initialization for compatibility with GCC < 4.4.6 */ + .reserved = { 0 }, + V4L2_INIT_BT_TIMINGS( + 720, 1920, /* min/max width */ + 480, 1080, /* min/max height */ + 27000000, 74250000, /* min/max pixelclock*/ + V4L2_DV_BT_STD_CEA861, /* Supported standards */ + /* capabilities */ + V4L2_DV_BT_CAP_INTERLACED | V4L2_DV_BT_CAP_PROGRESSIVE + ) +}; + +/* + * Supported SDTV standards. This does the same job as skel_timings_cap, but + * for standard TV formats. + */ +#define SKEL_TVNORMS V4L2_STD_ALL + +/* + * Interrupt handler: typically interrupts happen after a new frame has been + * captured. It is the job of the handler to remove the new frame from the + * internal list and give it back to the vb2 framework, updating the sequence + * counter, field and timestamp at the same time. + */ +static irqreturn_t skeleton_irq(int irq, void *dev_id) +{ +#ifdef TODO + struct skeleton *skel = dev_id; + + /* handle interrupt */ + + /* Once a new frame has been captured, mark it as done like this: */ + if (captured_new_frame) { + ... + spin_lock(&skel->qlock); + list_del(&new_buf->list); + spin_unlock(&skel->qlock); + v4l2_get_timestamp(&new_buf->vb.v4l2_buf.timestamp); + new_buf->vb.v4l2_buf.sequence = skel->sequence++; + new_buf->vb.v4l2_buf.field = skel->field; + if (skel->format.field == V4L2_FIELD_ALTERNATE) { + if (skel->field == V4L2_FIELD_BOTTOM) + skel->field = V4L2_FIELD_TOP; + else if (skel->field == V4L2_FIELD_TOP) + skel->field = V4L2_FIELD_BOTTOM; + } + vb2_buffer_done(&new_buf->vb, VB2_BUF_STATE_DONE); + } +#endif + return IRQ_HANDLED; +} + +/* + * Setup the constraints of the queue: besides setting the number of planes + * per buffer and the size and allocation context of each plane, it also + * checks if sufficient buffers have been allocated. Usually 3 is a good + * minimum number: many DMA engines need a minimum of 2 buffers in the + * queue and you need to have another available for userspace processing. + */ +static int queue_setup(struct vb2_queue *vq, + unsigned int *nbuffers, unsigned int *nplanes, + unsigned int sizes[], void *alloc_ctxs[]) +{ + struct skeleton *skel = vb2_get_drv_priv(vq); + + skel->field = skel->format.field; + if (skel->field == V4L2_FIELD_ALTERNATE) { + /* + * You cannot use read() with FIELD_ALTERNATE since the field + * information (TOP/BOTTOM) cannot be passed back to the user. + */ + if (vb2_fileio_is_active(vq)) + return -EINVAL; + skel->field = V4L2_FIELD_TOP; + } + + if (vq->num_buffers + *nbuffers < 3) + *nbuffers = 3 - vq->num_buffers; + alloc_ctxs[0] = skel->alloc_ctx; + + if (*nplanes) + return sizes[0] < skel->format.sizeimage ? -EINVAL : 0; + *nplanes = 1; + sizes[0] = skel->format.sizeimage; + return 0; +} + +/* + * Prepare the buffer for queueing to the DMA engine: check and set the + * payload size. + */ +static int buffer_prepare(struct vb2_buffer *vb) +{ + struct skeleton *skel = vb2_get_drv_priv(vb->vb2_queue); + unsigned long size = skel->format.sizeimage; + + if (vb2_plane_size(vb, 0) < size) { + dev_err(&skel->pdev->dev, "buffer too small (%lu < %lu)\n", + vb2_plane_size(vb, 0), size); + return -EINVAL; + } + + vb2_set_plane_payload(vb, 0, size); + return 0; +} + +/* + * Queue this buffer to the DMA engine. + */ +static void buffer_queue(struct vb2_buffer *vb) +{ + struct skeleton *skel = vb2_get_drv_priv(vb->vb2_queue); + struct skel_buffer *buf = to_skel_buffer(vb); + unsigned long flags; + + spin_lock_irqsave(&skel->qlock, flags); + list_add_tail(&buf->list, &skel->buf_list); + + /* TODO: Update any DMA pointers if necessary */ + + spin_unlock_irqrestore(&skel->qlock, flags); +} + +static void return_all_buffers(struct skeleton *skel, + enum vb2_buffer_state state) +{ + struct skel_buffer *buf, *node; + unsigned long flags; + + spin_lock_irqsave(&skel->qlock, flags); + list_for_each_entry_safe(buf, node, &skel->buf_list, list) { + vb2_buffer_done(&buf->vb, state); + list_del(&buf->list); + } + spin_unlock_irqrestore(&skel->qlock, flags); +} + +/* + * Start streaming. First check if the minimum number of buffers have been + * queued. If not, then return -ENOBUFS and the vb2 framework will call + * this function again the next time a buffer has been queued until enough + * buffers are available to actually start the DMA engine. + */ +static int start_streaming(struct vb2_queue *vq, unsigned int count) +{ + struct skeleton *skel = vb2_get_drv_priv(vq); + int ret = 0; + + skel->sequence = 0; + + /* TODO: start DMA */ + + if (ret) { + /* + * In case of an error, return all active buffers to the + * QUEUED state + */ + return_all_buffers(skel, VB2_BUF_STATE_QUEUED); + } + return ret; +} + +/* + * Stop the DMA engine. Any remaining buffers in the DMA queue are dequeued + * and passed on to the vb2 framework marked as STATE_ERROR. + */ +static void stop_streaming(struct vb2_queue *vq) +{ + struct skeleton *skel = vb2_get_drv_priv(vq); + + /* TODO: stop DMA */ + + /* Release all active buffers */ + return_all_buffers(skel, VB2_BUF_STATE_ERROR); +} + +/* + * The vb2 queue ops. Note that since q->lock is set we can use the standard + * vb2_ops_wait_prepare/finish helper functions. If q->lock would be NULL, + * then this driver would have to provide these ops. + */ +static struct vb2_ops skel_qops = { + .queue_setup = queue_setup, + .buf_prepare = buffer_prepare, + .buf_queue = buffer_queue, + .start_streaming = start_streaming, + .stop_streaming = stop_streaming, + .wait_prepare = vb2_ops_wait_prepare, + .wait_finish = vb2_ops_wait_finish, +}; + +/* + * Required ioctl querycap. Note that the version field is prefilled with + * the version of the kernel. + */ +static int skeleton_querycap(struct file *file, void *priv, + struct v4l2_capability *cap) +{ + struct skeleton *skel = video_drvdata(file); + + strlcpy(cap->driver, KBUILD_MODNAME, sizeof(cap->driver)); + strlcpy(cap->card, "V4L2 PCI Skeleton", sizeof(cap->card)); + snprintf(cap->bus_info, sizeof(cap->bus_info), "PCI:%s", + pci_name(skel->pdev)); + cap->device_caps = V4L2_CAP_VIDEO_CAPTURE | V4L2_CAP_READWRITE | + V4L2_CAP_STREAMING; + cap->capabilities = cap->device_caps | V4L2_CAP_DEVICE_CAPS; + return 0; +} + +/* + * Helper function to check and correct struct v4l2_pix_format. It's used + * not only in VIDIOC_TRY/S_FMT, but also elsewhere if changes to the SDTV + * standard, HDTV timings or the video input would require updating the + * current format. + */ +static void skeleton_fill_pix_format(struct skeleton *skel, + struct v4l2_pix_format *pix) +{ + pix->pixelformat = V4L2_PIX_FMT_YUYV; + if (skel->input == 0) { + /* S-Video input */ + pix->width = 720; + pix->height = (skel->std & V4L2_STD_525_60) ? 480 : 576; + pix->field = V4L2_FIELD_INTERLACED; + pix->colorspace = V4L2_COLORSPACE_SMPTE170M; + } else { + /* HDMI input */ + pix->width = skel->timings.bt.width; + pix->height = skel->timings.bt.height; + if (skel->timings.bt.interlaced) { + pix->field = V4L2_FIELD_ALTERNATE; + pix->height /= 2; + } else { + pix->field = V4L2_FIELD_NONE; + } + pix->colorspace = V4L2_COLORSPACE_REC709; + } + + /* + * The YUYV format is four bytes for every two pixels, so bytesperline + * is width * 2. + */ + pix->bytesperline = pix->width * 2; + pix->sizeimage = pix->bytesperline * pix->height; + pix->priv = 0; +} + +static int skeleton_try_fmt_vid_cap(struct file *file, void *priv, + struct v4l2_format *f) +{ + struct skeleton *skel = video_drvdata(file); + struct v4l2_pix_format *pix = &f->fmt.pix; + + /* + * Due to historical reasons providing try_fmt with an unsupported + * pixelformat will return -EINVAL for video receivers. Webcam drivers, + * however, will silently correct the pixelformat. Some video capture + * applications rely on this behavior... + */ + if (pix->pixelformat != V4L2_PIX_FMT_YUYV) + return -EINVAL; + skeleton_fill_pix_format(skel, pix); + return 0; +} + +static int skeleton_s_fmt_vid_cap(struct file *file, void *priv, + struct v4l2_format *f) +{ + struct skeleton *skel = video_drvdata(file); + int ret; + + ret = skeleton_try_fmt_vid_cap(file, priv, f); + if (ret) + return ret; + + /* + * It is not allowed to change the format while buffers for use with + * streaming have already been allocated. + */ + if (vb2_is_busy(&skel->queue)) + return -EBUSY; + + /* TODO: change format */ + skel->format = f->fmt.pix; + return 0; +} + +static int skeleton_g_fmt_vid_cap(struct file *file, void *priv, + struct v4l2_format *f) +{ + struct skeleton *skel = video_drvdata(file); + + f->fmt.pix = skel->format; + return 0; +} + +static int skeleton_enum_fmt_vid_cap(struct file *file, void *priv, + struct v4l2_fmtdesc *f) +{ + if (f->index != 0) + return -EINVAL; + + f->pixelformat = V4L2_PIX_FMT_YUYV; + return 0; +} + +static int skeleton_s_std(struct file *file, void *priv, v4l2_std_id std) +{ + struct skeleton *skel = video_drvdata(file); + + /* S_STD is not supported on the HDMI input */ + if (skel->input) + return -ENODATA; + + /* + * No change, so just return. Some applications call S_STD again after + * the buffers for streaming have been set up, so we have to allow for + * this behavior. + */ + if (std == skel->std) + return 0; + + /* + * Changing the standard implies a format change, which is not allowed + * while buffers for use with streaming have already been allocated. + */ + if (vb2_is_busy(&skel->queue)) + return -EBUSY; + + /* TODO: handle changing std */ + + skel->std = std; + + /* Update the internal format */ + skeleton_fill_pix_format(skel, &skel->format); + return 0; +} + +static int skeleton_g_std(struct file *file, void *priv, v4l2_std_id *std) +{ + struct skeleton *skel = video_drvdata(file); + + /* G_STD is not supported on the HDMI input */ + if (skel->input) + return -ENODATA; + + *std = skel->std; + return 0; +} + +/* + * Query the current standard as seen by the hardware. This function shall + * never actually change the standard, it just detects and reports. + * The framework will initially set *std to tvnorms (i.e. the set of + * supported standards by this input), and this function should just AND + * this value. If there is no signal, then *std should be set to 0. + */ +static int skeleton_querystd(struct file *file, void *priv, v4l2_std_id *std) +{ + struct skeleton *skel = video_drvdata(file); + + /* QUERY_STD is not supported on the HDMI input */ + if (skel->input) + return -ENODATA; + +#ifdef TODO + /* + * Query currently seen standard. Initial value of *std is + * V4L2_STD_ALL. This function should look something like this: + */ + get_signal_info(); + if (no_signal) { + *std = 0; + return 0; + } + /* Use signal information to reduce the number of possible standards */ + if (signal_has_525_lines) + *std &= V4L2_STD_525_60; + else + *std &= V4L2_STD_625_50; +#endif + return 0; +} + +static int skeleton_s_dv_timings(struct file *file, void *_fh, + struct v4l2_dv_timings *timings) +{ + struct skeleton *skel = video_drvdata(file); + + /* S_DV_TIMINGS is not supported on the S-Video input */ + if (skel->input == 0) + return -ENODATA; + + /* Quick sanity check */ + if (!v4l2_valid_dv_timings(timings, &skel_timings_cap, NULL, NULL)) + return -EINVAL; + + /* Check if the timings are part of the CEA-861 timings. */ + if (!v4l2_find_dv_timings_cap(timings, &skel_timings_cap, + 0, NULL, NULL)) + return -EINVAL; + + /* Return 0 if the new timings are the same as the current timings. */ + if (v4l2_match_dv_timings(timings, &skel->timings, 0, false)) + return 0; + + /* + * Changing the timings implies a format change, which is not allowed + * while buffers for use with streaming have already been allocated. + */ + if (vb2_is_busy(&skel->queue)) + return -EBUSY; + + /* TODO: Configure new timings */ + + /* Save timings */ + skel->timings = *timings; + + /* Update the internal format */ + skeleton_fill_pix_format(skel, &skel->format); + return 0; +} + +static int skeleton_g_dv_timings(struct file *file, void *_fh, + struct v4l2_dv_timings *timings) +{ + struct skeleton *skel = video_drvdata(file); + + /* G_DV_TIMINGS is not supported on the S-Video input */ + if (skel->input == 0) + return -ENODATA; + + *timings = skel->timings; + return 0; +} + +static int skeleton_enum_dv_timings(struct file *file, void *_fh, + struct v4l2_enum_dv_timings *timings) +{ + struct skeleton *skel = video_drvdata(file); + + /* ENUM_DV_TIMINGS is not supported on the S-Video input */ + if (skel->input == 0) + return -ENODATA; + + return v4l2_enum_dv_timings_cap(timings, &skel_timings_cap, + NULL, NULL); +} + +/* + * Query the current timings as seen by the hardware. This function shall + * never actually change the timings, it just detects and reports. + * If no signal is detected, then return -ENOLINK. If the hardware cannot + * lock to the signal, then return -ENOLCK. If the signal is out of range + * of the capabilities of the system (e.g., it is possible that the receiver + * can lock but that the DMA engine it is connected to cannot handle + * pixelclocks above a certain frequency), then -ERANGE is returned. + */ +static int skeleton_query_dv_timings(struct file *file, void *_fh, + struct v4l2_dv_timings *timings) +{ + struct skeleton *skel = video_drvdata(file); + + /* QUERY_DV_TIMINGS is not supported on the S-Video input */ + if (skel->input == 0) + return -ENODATA; + +#ifdef TODO + /* + * Query currently seen timings. This function should look + * something like this: + */ + detect_timings(); + if (no_signal) + return -ENOLINK; + if (cannot_lock_to_signal) + return -ENOLCK; + if (signal_out_of_range_of_capabilities) + return -ERANGE; + + /* Useful for debugging */ + v4l2_print_dv_timings(skel->v4l2_dev.name, "query_dv_timings:", + timings, true); +#endif + return 0; +} + +static int skeleton_dv_timings_cap(struct file *file, void *fh, + struct v4l2_dv_timings_cap *cap) +{ + struct skeleton *skel = video_drvdata(file); + + /* DV_TIMINGS_CAP is not supported on the S-Video input */ + if (skel->input == 0) + return -ENODATA; + *cap = skel_timings_cap; + return 0; +} + +static int skeleton_enum_input(struct file *file, void *priv, + struct v4l2_input *i) +{ + if (i->index > 1) + return -EINVAL; + + i->type = V4L2_INPUT_TYPE_CAMERA; + if (i->index == 0) { + i->std = SKEL_TVNORMS; + strlcpy(i->name, "S-Video", sizeof(i->name)); + i->capabilities = V4L2_IN_CAP_STD; + } else { + i->std = 0; + strlcpy(i->name, "HDMI", sizeof(i->name)); + i->capabilities = V4L2_IN_CAP_DV_TIMINGS; + } + return 0; +} + +static int skeleton_s_input(struct file *file, void *priv, unsigned int i) +{ + struct skeleton *skel = video_drvdata(file); + + if (i > 1) + return -EINVAL; + + /* + * Changing the input implies a format change, which is not allowed + * while buffers for use with streaming have already been allocated. + */ + if (vb2_is_busy(&skel->queue)) + return -EBUSY; + + skel->input = i; + /* + * Update tvnorms. The tvnorms value is used by the core to implement + * VIDIOC_ENUMSTD so it has to be correct. If tvnorms == 0, then + * ENUMSTD will return -ENODATA. + */ + skel->vdev.tvnorms = i ? 0 : SKEL_TVNORMS; + + /* Update the internal format */ + skeleton_fill_pix_format(skel, &skel->format); + return 0; +} + +static int skeleton_g_input(struct file *file, void *priv, unsigned int *i) +{ + struct skeleton *skel = video_drvdata(file); + + *i = skel->input; + return 0; +} + +/* The control handler. */ +static int skeleton_s_ctrl(struct v4l2_ctrl *ctrl) +{ + /*struct skeleton *skel = + container_of(ctrl->handler, struct skeleton, ctrl_handler);*/ + + switch (ctrl->id) { + case V4L2_CID_BRIGHTNESS: + /* TODO: set brightness to ctrl->val */ + break; + case V4L2_CID_CONTRAST: + /* TODO: set contrast to ctrl->val */ + break; + case V4L2_CID_SATURATION: + /* TODO: set saturation to ctrl->val */ + break; + case V4L2_CID_HUE: + /* TODO: set hue to ctrl->val */ + break; + default: + return -EINVAL; + } + return 0; +} + +/* ------------------------------------------------------------------ + File operations for the device + ------------------------------------------------------------------*/ + +static const struct v4l2_ctrl_ops skel_ctrl_ops = { + .s_ctrl = skeleton_s_ctrl, +}; + +/* + * The set of all supported ioctls. Note that all the streaming ioctls + * use the vb2 helper functions that take care of all the locking and + * that also do ownership tracking (i.e. only the filehandle that requested + * the buffers can call the streaming ioctls, all other filehandles will + * receive -EBUSY if they attempt to call the same streaming ioctls). + * + * The last three ioctls also use standard helper functions: these implement + * standard behavior for drivers with controls. + */ +static const struct v4l2_ioctl_ops skel_ioctl_ops = { + .vidioc_querycap = skeleton_querycap, + .vidioc_try_fmt_vid_cap = skeleton_try_fmt_vid_cap, + .vidioc_s_fmt_vid_cap = skeleton_s_fmt_vid_cap, + .vidioc_g_fmt_vid_cap = skeleton_g_fmt_vid_cap, + .vidioc_enum_fmt_vid_cap = skeleton_enum_fmt_vid_cap, + + .vidioc_g_std = skeleton_g_std, + .vidioc_s_std = skeleton_s_std, + .vidioc_querystd = skeleton_querystd, + + .vidioc_s_dv_timings = skeleton_s_dv_timings, + .vidioc_g_dv_timings = skeleton_g_dv_timings, + .vidioc_enum_dv_timings = skeleton_enum_dv_timings, + .vidioc_query_dv_timings = skeleton_query_dv_timings, + .vidioc_dv_timings_cap = skeleton_dv_timings_cap, + + .vidioc_enum_input = skeleton_enum_input, + .vidioc_g_input = skeleton_g_input, + .vidioc_s_input = skeleton_s_input, + + .vidioc_reqbufs = vb2_ioctl_reqbufs, + .vidioc_create_bufs = vb2_ioctl_create_bufs, + .vidioc_querybuf = vb2_ioctl_querybuf, + .vidioc_qbuf = vb2_ioctl_qbuf, + .vidioc_dqbuf = vb2_ioctl_dqbuf, + .vidioc_expbuf = vb2_ioctl_expbuf, + .vidioc_streamon = vb2_ioctl_streamon, + .vidioc_streamoff = vb2_ioctl_streamoff, + + .vidioc_log_status = v4l2_ctrl_log_status, + .vidioc_subscribe_event = v4l2_ctrl_subscribe_event, + .vidioc_unsubscribe_event = v4l2_event_unsubscribe, +}; + +/* + * The set of file operations. Note that all these ops are standard core + * helper functions. + */ +static const struct v4l2_file_operations skel_fops = { + .owner = THIS_MODULE, + .open = v4l2_fh_open, + .release = vb2_fop_release, + .unlocked_ioctl = video_ioctl2, + .read = vb2_fop_read, + .mmap = vb2_fop_mmap, + .poll = vb2_fop_poll, +}; + +/* + * The initial setup of this device instance. Note that the initial state of + * the driver should be complete. So the initial format, standard, timings + * and video input should all be initialized to some reasonable value. + */ +static int skeleton_probe(struct pci_dev *pdev, const struct pci_device_id *ent) +{ + /* The initial timings are chosen to be 720p60. */ + static const struct v4l2_dv_timings timings_def = + V4L2_DV_BT_CEA_1280X720P60; + struct skeleton *skel; + struct video_device *vdev; + struct v4l2_ctrl_handler *hdl; + struct vb2_queue *q; + int ret; + + /* Enable PCI */ + ret = pci_enable_device(pdev); + if (ret) + return ret; + ret = pci_set_dma_mask(pdev, DMA_BIT_MASK(32)); + if (ret) { + dev_err(&pdev->dev, "no suitable DMA available.\n"); + goto disable_pci; + } + + /* Allocate a new instance */ + skel = devm_kzalloc(&pdev->dev, sizeof(struct skeleton), GFP_KERNEL); + if (!skel) + return -ENOMEM; + + /* Allocate the interrupt */ + ret = devm_request_irq(&pdev->dev, pdev->irq, + skeleton_irq, 0, KBUILD_MODNAME, skel); + if (ret) { + dev_err(&pdev->dev, "request_irq failed\n"); + goto disable_pci; + } + skel->pdev = pdev; + + /* Fill in the initial format-related settings */ + skel->timings = timings_def; + skel->std = V4L2_STD_625_50; + skeleton_fill_pix_format(skel, &skel->format); + + /* Initialize the top-level structure */ + ret = v4l2_device_register(&pdev->dev, &skel->v4l2_dev); + if (ret) + goto disable_pci; + + mutex_init(&skel->lock); + + /* Add the controls */ + hdl = &skel->ctrl_handler; + v4l2_ctrl_handler_init(hdl, 4); + v4l2_ctrl_new_std(hdl, &skel_ctrl_ops, + V4L2_CID_BRIGHTNESS, 0, 255, 1, 127); + v4l2_ctrl_new_std(hdl, &skel_ctrl_ops, + V4L2_CID_CONTRAST, 0, 255, 1, 16); + v4l2_ctrl_new_std(hdl, &skel_ctrl_ops, + V4L2_CID_SATURATION, 0, 255, 1, 127); + v4l2_ctrl_new_std(hdl, &skel_ctrl_ops, + V4L2_CID_HUE, -128, 127, 1, 0); + if (hdl->error) { + ret = hdl->error; + goto free_hdl; + } + skel->v4l2_dev.ctrl_handler = hdl; + + /* Initialize the vb2 queue */ + q = &skel->queue; + q->type = V4L2_BUF_TYPE_VIDEO_CAPTURE; + q->io_modes = VB2_MMAP | VB2_DMABUF | VB2_READ; + q->drv_priv = skel; + q->buf_struct_size = sizeof(struct skel_buffer); + q->ops = &skel_qops; + q->mem_ops = &vb2_dma_contig_memops; + q->timestamp_flags = V4L2_BUF_FLAG_TIMESTAMP_MONOTONIC; + /* + * Assume that this DMA engine needs to have at least two buffers + * available before it can be started. The start_streaming() op + * won't be called until at least this many buffers are queued up. + */ + q->min_buffers_needed = 2; + /* + * The serialization lock for the streaming ioctls. This is the same + * as the main serialization lock, but if some of the non-streaming + * ioctls could take a long time to execute, then you might want to + * have a different lock here to prevent VIDIOC_DQBUF from being + * blocked while waiting for another action to finish. This is + * generally not needed for PCI devices, but USB devices usually do + * want a separate lock here. + */ + q->lock = &skel->lock; + /* + * Since this driver can only do 32-bit DMA we must make sure that + * the vb2 core will allocate the buffers in 32-bit DMA memory. + */ + q->gfp_flags = GFP_DMA32; + ret = vb2_queue_init(q); + if (ret) + goto free_hdl; + + skel->alloc_ctx = vb2_dma_contig_init_ctx(&pdev->dev); + if (IS_ERR(skel->alloc_ctx)) { + dev_err(&pdev->dev, "Can't allocate buffer context"); + ret = PTR_ERR(skel->alloc_ctx); + goto free_hdl; + } + INIT_LIST_HEAD(&skel->buf_list); + spin_lock_init(&skel->qlock); + + /* Initialize the video_device structure */ + vdev = &skel->vdev; + strlcpy(vdev->name, KBUILD_MODNAME, sizeof(vdev->name)); + /* + * There is nothing to clean up, so release is set to an empty release + * function. The release callback must be non-NULL. + */ + vdev->release = video_device_release_empty; + vdev->fops = &skel_fops, + vdev->ioctl_ops = &skel_ioctl_ops, + /* + * The main serialization lock. All ioctls are serialized by this + * lock. Exception: if q->lock is set, then the streaming ioctls + * are serialized by that separate lock. + */ + vdev->lock = &skel->lock; + vdev->queue = q; + vdev->v4l2_dev = &skel->v4l2_dev; + /* Supported SDTV standards, if any */ + vdev->tvnorms = SKEL_TVNORMS; + video_set_drvdata(vdev, skel); + + ret = video_register_device(vdev, VFL_TYPE_GRABBER, -1); + if (ret) + goto free_ctx; + + dev_info(&pdev->dev, "V4L2 PCI Skeleton Driver loaded\n"); + return 0; + +free_ctx: + vb2_dma_contig_cleanup_ctx(skel->alloc_ctx); +free_hdl: + v4l2_ctrl_handler_free(&skel->ctrl_handler); + v4l2_device_unregister(&skel->v4l2_dev); +disable_pci: + pci_disable_device(pdev); + return ret; +} + +static void skeleton_remove(struct pci_dev *pdev) +{ + struct v4l2_device *v4l2_dev = pci_get_drvdata(pdev); + struct skeleton *skel = container_of(v4l2_dev, struct skeleton, v4l2_dev); + + video_unregister_device(&skel->vdev); + v4l2_ctrl_handler_free(&skel->ctrl_handler); + vb2_dma_contig_cleanup_ctx(skel->alloc_ctx); + v4l2_device_unregister(&skel->v4l2_dev); + pci_disable_device(skel->pdev); +} + +static struct pci_driver skeleton_driver = { + .name = KBUILD_MODNAME, + .probe = skeleton_probe, + .remove = skeleton_remove, + .id_table = skeleton_pci_tbl, +}; + +module_pci_driver(skeleton_driver); -- cgit v1.2.3 From 08559657b21522d642331f9dc455a3917d85ab00 Mon Sep 17 00:00:00 2001 From: Kees Cook Date: Tue, 26 Apr 2016 16:41:21 -0700 Subject: 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 --- Documentation/ABI/obsolete/sysfs-driver-hid-roccat-savu | 11 ++++++----- .../ABI/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 +- Documentation/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 f1e02a98bd9d..99fda67fce18 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 f893337570c1..ec27c6c9e737 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 08579e7e1e89..98fd81ad76a1 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 b4436cca97a8..c7fc72d4495c 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 361040e6b0f4..f5f5ce8badac 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 f4b61b6ce3c2..78599bbd58f7 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 7865351688da..a9c0d1dc209a 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 370ca006db7a..9bccf16736f7 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 08b885d35674..e08a6739e72c 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 9b30011ecabe..a6e2ea41160c 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 2d5622f60e11..a54788405429 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 8aef91335701..106d17fbb05f 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 408679789136..4f3d6a882bdc 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 71f86859d7d8..cafdca8b3b15 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 915f32063a26..f1d4fe4c366c 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 f2cfe265e836..47c1dd9818f2 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 3f24df8c6e65..cd417d7b5bd4 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 6ab619fcc517..d58ff8467953 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 f2d6e9d1791e..3cc4d80d6092 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 492f1affb0e5..588d85724f10 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 35fae23f883b..b09ce36b921e 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 d3f1d7783d1c..646a47de0016 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 54dd9b9c6c31..b7a3f6d6cfc1 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 -- cgit v1.2.3 From 2fd872bd84b3aa1a177a66a8d14bd25f68f373f0 Mon Sep 17 00:00:00 2001 From: René Nyffenegger Date: Thu, 28 Apr 2016 10:15:24 +0200 Subject: 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 13f5619b2203..3a3b30ac2a75 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. -- cgit v1.2.3 From fadc0b31cba0bb56bce1a3259cc60e4d7ee67333 Mon Sep 17 00:00:00 2001 From: Jani Nikula Date: Thu, 12 May 2016 16:15:36 +0300 Subject: 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 c37255bb620d..29fd5cabb657 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'; -- cgit v1.2.3 From c0d1b6ee780ab16f16cdbe046aa9c83a2a31f9e2 Mon Sep 17 00:00:00 2001 From: Jonathan Corbet Date: Thu, 12 May 2016 16:15:37 +0300 Subject: 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 29fd5cabb657..0ad1fb0e3031 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($) { -- cgit v1.2.3 From 6285097654725f39357527b553d03b70bfbaf4d2 Mon Sep 17 00:00:00 2001 From: Jani Nikula Date: Thu, 12 May 2016 16:15:38 +0300 Subject: 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 0ad1fb0e3031..2fc8fad5195e 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"; -- cgit v1.2.3 From 568fb2dec9c68bb38c2a1ad01fb3d4dd41488115 Mon Sep 17 00:00:00 2001 From: Jani Nikula Date: Thu, 12 May 2016 16:15:39 +0300 Subject: 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 e267e621431a..48abc01a920e 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); -- cgit v1.2.3 From 868fb19212ca5bdbfa765a97a4bf6d2439b89056 Mon Sep 17 00:00:00 2001 From: Jani Nikula Date: Thu, 12 May 2016 16:15:40 +0300 Subject: 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 48abc01a920e..fb195f0ed0ef 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); } } -- cgit v1.2.3 From a48dc45e9c02ebaebc79de5b3fec8e4f59a9fe9f Mon Sep 17 00:00:00 2001 From: Jani Nikula Date: Thu, 12 May 2016 16:15:41 +0300 Subject: 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 fb195f0ed0ef..bc900310b431 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); -- cgit v1.2.3 From 1dcdad0aacb6d762b77f3e17167d131a14c0dbce Mon Sep 17 00:00:00 2001 From: Jani Nikula Date: Thu, 12 May 2016 16:15:42 +0300 Subject: 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 bc900310b431..a933e054402d 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; -- cgit v1.2.3 From 064669b43baa4b74b262c49db3ce69118e2f0f2d Mon Sep 17 00:00:00 2001 From: Jani Nikula Date: Thu, 12 May 2016 16:15:43 +0300 Subject: 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 a933e054402d..9babfd108d2e 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"); -- cgit v1.2.3 From 0e95abf9be3108498128458ffb087209e0a1b5fa Mon Sep 17 00:00:00 2001 From: Jani Nikula Date: Thu, 12 May 2016 16:15:44 +0300 Subject: 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 9babfd108d2e..0a12593b9041 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; -- cgit v1.2.3 From 2bdbc5bc16c338a43c9ac7ef93c1a60a8b17ee7d Mon Sep 17 00:00:00 2001 From: Qiang Huang Date: Wed, 11 May 2016 14:07:31 +0800 Subject: 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 ff71e16cc752..b14abf217239 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 -- cgit v1.2.3 From 30955e71fc2bd1b966ce6531285ac59ae653819f Mon Sep 17 00:00:00 2001 From: Geert Uytterhoeven Date: Tue, 10 May 2016 20:59:56 +0200 Subject: 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 b7a3f6d6cfc1..59cbc803aad6 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 -- cgit v1.2.3 From 95f981f2e3b9a27ea2eb744b6861a3b9c81a1fde Mon Sep 17 00:00:00 2001 From: Geert Uytterhoeven Date: Wed, 11 May 2016 13:56:04 +0200 Subject: 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 39701515832b..90889c785809 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 -- cgit v1.2.3 From b79ef07d205c6504e701b48380d33fe2bab78ec5 Mon Sep 17 00:00:00 2001 From: Geert Uytterhoeven Date: Wed, 11 May 2016 13:56:05 +0200 Subject: 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 90889c785809..da193e092fc3 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. -- cgit v1.2.3 From 9f8036643dd9609b329aa1b89c9a95981e9ba62f Mon Sep 17 00:00:00 2001 From: Kees Cook Date: Mon, 16 May 2016 19:27:28 -0700 Subject: 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 000000000000..babd6378ec05 --- /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. -- cgit v1.2.3