From d6eff078e0bf9f24dcc2c7fcdbdf26b57148b197 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?S=C3=A9bastien=20Hinderer?= Date: Wed, 8 Jul 2015 21:12:32 +0200 Subject: SubmittingPatches: fix typo MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit From 7e0befc8e48a49e2ddf86bbd861027b14ea5a53d Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?S=C3=A9bastien=20Hinderer?= Date: Wed, 8 Jul 2015 21:10:18 +0200 Subject: [PATCH] SubmittingPatches: fix typo MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Content-Type: text/plain; charset="utf-8" Signed-off-by: Sébastien Hinderer Signed-off-by: Jonathan Corbet --- Documentation/SubmittingPatches | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Documentation/SubmittingPatches b/Documentation/SubmittingPatches index 27e7e5e..e9395df 100644 --- a/Documentation/SubmittingPatches +++ b/Documentation/SubmittingPatches @@ -267,7 +267,7 @@ You should always copy the appropriate subsystem maintainer(s) on any patch to code that they maintain; look through the MAINTAINERS file and the source code revision history to see who those maintainers are. The script scripts/get_maintainer.pl can be very useful at this step. If you -cannot find a maintainer for the subsystem your are working on, Andrew +cannot find a maintainer for the subsystem you are working on, Andrew Morton (akpm@linux-foundation.org) serves as a maintainer of last resort. You should also normally choose at least one mailing list to receive a copy -- cgit v1.1 From bd760c498f009e2a6795952469af6f8e6edac05a Mon Sep 17 00:00:00 2001 From: Daniel Grimshaw Date: Wed, 8 Jul 2015 10:44:51 -0700 Subject: Documentation: filesystems: btrfs: Fixed typos and whitespace I am a high school student trying to become familiar with Linux kernel development. The btrfs documentation in Documentation/filesystems had a few typos and errors in whitespace. This patch corrects both of these. Signed-off-by: Daniel Grimshaw Signed-off-by: Jonathan Corbet --- Documentation/filesystems/btrfs.txt | 16 ++++++++-------- 1 file changed, 8 insertions(+), 8 deletions(-) diff --git a/Documentation/filesystems/btrfs.txt b/Documentation/filesystems/btrfs.txt index d11cc2f..c772b47 100644 --- a/Documentation/filesystems/btrfs.txt +++ b/Documentation/filesystems/btrfs.txt @@ -61,7 +61,7 @@ Options with (*) are default options and will not show in the mount options. check_int enables the integrity checker module, which examines all block write requests to ensure on-disk consistency, at a large - memory and CPU cost. + memory and CPU cost. check_int_data includes extent data in the integrity checks, and implies the check_int option. @@ -113,7 +113,7 @@ Options with (*) are default options and will not show in the mount options. Disable/enable debugging option to be more verbose in some ENOSPC conditions. fatal_errors= - Action to take when encountering a fatal error: + Action to take when encountering a fatal error: "bug" - BUG() on a fatal error. This is the default. "panic" - panic() on a fatal error. @@ -132,10 +132,10 @@ Options with (*) are default options and will not show in the mount options. max_inline= Specify the maximum amount of space, in bytes, that can be inlined in - a metadata B-tree leaf. The value is specified in bytes, optionally + a metadata B-tree leaf. The value is specified in bytes, optionally with a K, M, or G suffix, case insensitive. In practice, this value is limited by the root sector size, with some space unavailable due - to leaf headers. For a 4k sectorsize, max inline data is ~3900 bytes. + to leaf headers. For a 4k sector size, max inline data is ~3900 bytes. metadata_ratio= Specify that 1 metadata chunk should be allocated after every @@ -170,7 +170,7 @@ Options with (*) are default options and will not show in the mount options. recovery Enable autorecovery attempts if a bad tree root is found at mount time. - Currently this scans a list of several previous tree roots and tries to + Currently this scans a list of several previous tree roots and tries to use the first readable. rescan_uuid_tree @@ -194,7 +194,7 @@ Options with (*) are default options and will not show in the mount options. ssd_spread Options to control ssd allocation schemes. By default, BTRFS will enable or disable ssd allocation heuristics depending on whether a - rotational or nonrotational disk is in use. The ssd and nossd options + rotational or non-rotational disk is in use. The ssd and nossd options can override this autodetection. The ssd_spread mount option attempts to allocate into big chunks @@ -216,13 +216,13 @@ Options with (*) are default options and will not show in the mount options. This allows mounting of subvolumes which are not in the root of the mounted filesystem. You can use "btrfs subvolume show " to see the object ID for a subvolume. - + thread_pool= The number of worker threads to allocate. The default number is equal to the number of CPUs + 2, or 8, whichever is smaller. user_subvol_rm_allowed - Allow subvolumes to be deleted by a non-root user. Use with caution. + Allow subvolumes to be deleted by a non-root user. Use with caution. MAILING LIST ============ -- cgit v1.1 From 2e106e4df28aa264f9ded7e5be3733224f2e4f93 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?J=C3=A9r=C3=A9my=20Bobbio?= Date: Wed, 8 Jul 2015 20:06:33 +0100 Subject: scripts/kernel-doc: parse kernel-doc deterministically MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Regular expressions for highlights in kernel-doc are stored in a Perl hash. These hashes are ordered differently for each Perl run. This will prevent kernel-doc to behave deterministically when parsing “@foo()” as in some runs it will be interpreted as a parameter and in the others it will be interpreted as a function. We now sort the %highlights hash to get the same behavior on every run. Signed-off-by: Jérémy Bobbio Signed-off-by: Ben Hutchings Signed-off-by: Jonathan Corbet --- scripts/kernel-doc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/scripts/kernel-doc b/scripts/kernel-doc index 9922e66..71ada00 100755 --- a/scripts/kernel-doc +++ b/scripts/kernel-doc @@ -2587,7 +2587,7 @@ $kernelversion = get_kernel_version(); # generate a sequence of code that will splice in highlighting information # using the s// operator. -foreach my $pattern (keys %highlights) { +foreach my $pattern (sort keys %highlights) { # print STDERR "scanning pattern:$pattern, highlight:($highlights{$pattern})\n"; $dohighlight .= "\$contents =~ s:$pattern:$highlights{$pattern}:gs;\n"; } -- cgit v1.1 From 32c1735c4091ef0de8e39f68a9d83a07450b959b Mon Sep 17 00:00:00 2001 From: Ben Hutchings Date: Wed, 8 Jul 2015 20:06:44 +0100 Subject: DocBook: Don't store mtime (or name) in compressed man pages MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The mtime on a man page is the build time. As gzip stores the mtime and original name in the compressed file by default, this makes compressed man pages unreproducible. Neither of these are important metadata in this case, so turn this off. Reported-by: Jérémy Bobbio Signed-off-by: Ben Hutchings Signed-off-by: Jonathan Corbet --- Documentation/DocBook/Makefile | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Documentation/DocBook/Makefile b/Documentation/DocBook/Makefile index b6a6a2e..11a4145 100644 --- a/Documentation/DocBook/Makefile +++ b/Documentation/DocBook/Makefile @@ -56,7 +56,7 @@ htmldocs: $(HTML) MAN := $(patsubst %.xml, %.9, $(BOOKS)) mandocs: $(MAN) - find $(obj)/man -name '*.9' | xargs gzip -f + find $(obj)/man -name '*.9' | xargs gzip -nf installmandocs: mandocs mkdir -p /usr/local/man/man9/ -- cgit v1.1 From b48ed85145711b28f9024dcdaf6c0238d7b5042c Mon Sep 17 00:00:00 2001 From: Ben Hutchings Date: Wed, 8 Jul 2015 20:06:51 +0100 Subject: DocBook: Generate consistent IDs MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit By default, DocBook XSL uses a non-deterministic function to generate IDs for HTML elements where it can't take a name from the input document. However, it has the option to generate 'consistent' (deterministic) IDs instead. Enable this to make the HTML pages reproducible. Reported-by: Jérémy Bobbio Signed-off-by: Ben Hutchings Signed-off-by: Jonathan Corbet --- Documentation/DocBook/stylesheet.xsl | 1 + 1 file changed, 1 insertion(+) diff --git a/Documentation/DocBook/stylesheet.xsl b/Documentation/DocBook/stylesheet.xsl index 85b2527..3bf4ecf 100644 --- a/Documentation/DocBook/stylesheet.xsl +++ b/Documentation/DocBook/stylesheet.xsl @@ -5,6 +5,7 @@ 80 0 +1 2 1 -- cgit v1.1 From b44158b17099ed5c7c8f4bfb7029942adbfbc318 Mon Sep 17 00:00:00 2001 From: Ben Hutchings Date: Wed, 8 Jul 2015 20:07:05 +0100 Subject: DocBook: Avoid building man pages repeatedly and inconsistently MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Some kernel-doc sections are included in multiple DocBook files. This means the mandocs target will generate the same manual page multiple times with different metadata (author name/address and manual title, taken from the including DocBook file). If it's invoked in a parallel build, the output is nondeterminstic. For each section that is duplicated, mark the less specific manual's inclusion as 'extra' and exclude it during conversion to manual pages. Use xmlif for this, as that is bundled with xmlto which we already use. I would have preferred to use more conventional markup for this, but each of the following approaches failed: 1. Wrap the extra inclusions with a new element and add a template to the stylesheet to include/exclude them. Unfortunately DocBook XSL doesn't seem to support foreign elements at an intermediate level in the document tree. 2. Use DocBook profiling. This works but requires passing an absolute path to the profile stylesheet to xmlto, so it's not portable. 3. Use SGML marked sections. docbook2x can handle these but xmlto chokes on them. Reported-by: Jérémy Bobbio Signed-off-by: Ben Hutchings Signed-off-by: Jonathan Corbet --- Documentation/DocBook/Makefile | 10 +++++++++- Documentation/DocBook/device-drivers.tmpl | 6 ++++++ Documentation/DocBook/gadget.tmpl | 3 +++ Documentation/DocBook/kernel-api.tmpl | 6 ++++++ 4 files changed, 24 insertions(+), 1 deletion(-) diff --git a/Documentation/DocBook/Makefile b/Documentation/DocBook/Makefile index 11a4145..83fcb6c 100644 --- a/Documentation/DocBook/Makefile +++ b/Documentation/DocBook/Makefile @@ -56,6 +56,13 @@ htmldocs: $(HTML) MAN := $(patsubst %.xml, %.9, $(BOOKS)) mandocs: $(MAN) + @dups=$$(sed -n 's/.*\([^<]*\)<\/refname>.*/\1/p' \ + $(obj)/*.xml.noextra | sort | uniq -d); \ + if [ -n "$$dups" ]; then \ + echo >&2 "The following manual pages are generated more than once:"; \ + printf >&2 '%s\n' "$$dups"; \ + exit 1; \ + fi find $(obj)/man -name '*.9' | xargs gzip -nf installmandocs: mandocs @@ -150,7 +157,7 @@ quiet_cmd_db2html = HTML $@ cp $(PNG-$(basename $(notdir $@))) $(patsubst %.html,%,$@); fi quiet_cmd_db2man = MAN $@ - cmd_db2man = if grep -q refentry $<; then xmlto man $(XMLTOFLAGS) -o $(obj)/man $< ; fi + cmd_db2man = if grep -q refentry $<; then xmlif excludeextra=1 <$< >$<.noextra && xmlto man $(XMLTOFLAGS) -o $(obj)/man $<.noextra ; fi %.9 : %.xml @(which xmlto > /dev/null 2>&1) || \ (echo "*** You need to install xmlto ***"; \ @@ -217,6 +224,7 @@ clean-files := $(DOCBOOKS) \ $(patsubst %.xml, %.ps, $(DOCBOOKS)) \ $(patsubst %.xml, %.pdf, $(DOCBOOKS)) \ $(patsubst %.xml, %.html, $(DOCBOOKS)) \ + $(patsubst %, %.noextra, $(DOCBOOKS)) \ $(patsubst %.xml, %.9, $(DOCBOOKS)) \ $(index) diff --git a/Documentation/DocBook/device-drivers.tmpl b/Documentation/DocBook/device-drivers.tmpl index faf09d4..87853ea 100644 --- a/Documentation/DocBook/device-drivers.tmpl +++ b/Documentation/DocBook/device-drivers.tmpl @@ -194,8 +194,13 @@ X!Edrivers/pnp/system.c Sound Devices + + !Iinclude/sound/core.h + !Esound/sound_core.c + + !Iinclude/sound/pcm.h !Esound/core/pcm.c !Esound/core/device.c @@ -211,6 +216,7 @@ X!Edrivers/pnp/system.c !Esound/core/hwdep.c !Esound/core/pcm_native.c !Esound/core/memalloc.c + diff --git a/Documentation/DocBook/gadget.tmpl b/Documentation/DocBook/gadget.tmpl index 6416292..e1b87bd 100644 --- a/Documentation/DocBook/gadget.tmpl +++ b/Documentation/DocBook/gadget.tmpl @@ -488,7 +488,10 @@ These are the same types and constants used by host side drivers (and usbcore). + + !Iinclude/linux/usb/ch9.h + Core Objects and Methods diff --git a/Documentation/DocBook/kernel-api.tmpl b/Documentation/DocBook/kernel-api.tmpl index ecfd0ea..722249a 100644 --- a/Documentation/DocBook/kernel-api.tmpl +++ b/Documentation/DocBook/kernel-api.tmpl @@ -58,8 +58,11 @@ String Conversions !Elib/vsprintf.c + + !Finclude/linux/kernel.h kstrtol !Finclude/linux/kernel.h kstrtoul + !Elib/kstrtox.c String Manipulation @@ -178,7 +181,10 @@ X!Ekernel/module.c Hardware Interfaces Interrupt Handling + + !Ekernel/irq/manage.c + DMA Channels -- cgit v1.1 From b2c4105b080fb26d8fc9b89c846f5966137c6d40 Mon Sep 17 00:00:00 2001 From: Ben Hutchings Date: Wed, 8 Jul 2015 20:07:16 +0100 Subject: scripts/kernel-doc: Use $KBUILD_BUILD_TIMESTAMP as man page date Together with the preceding changes, this allows man pages to be built reproducibly. Signed-off-by: Ben Hutchings Signed-off-by: Jonathan Corbet --- scripts/kernel-doc | 15 ++++++++++++--- 1 file changed, 12 insertions(+), 3 deletions(-) diff --git a/scripts/kernel-doc b/scripts/kernel-doc index 71ada00..0ac1a07 100755 --- a/scripts/kernel-doc +++ b/scripts/kernel-doc @@ -253,11 +253,20 @@ my %highlights = %highlights_man; my $blankline = $blankline_man; my $modulename = "Kernel API"; my $function_only = 0; +my $show_not_found = 0; + +my @build_time; +if (defined($ENV{'KBUILD_BUILD_TIMESTAMP'}) && + (my $seconds = `date -d"${ENV{'KBUILD_BUILD_TIMESTAMP'}}" +%s`) ne '') { + @build_time = gmtime($seconds); +} else { + @build_time = localtime; +} + my $man_date = ('January', 'February', 'March', 'April', 'May', 'June', 'July', 'August', 'September', 'October', - 'November', 'December')[(localtime)[4]] . - " " . ((localtime)[5]+1900); -my $show_not_found = 0; + 'November', 'December')[$build_time[4]] . + " " . ($build_time[5]+1900); # Essentially these are globals. # They probably want to be tidied up, made more localised or something. -- cgit v1.1 From 4b10df7f2c8b3c6de12375b85456c6fd275af6d0 Mon Sep 17 00:00:00 2001 From: "Olivier C. Larocque" Date: Thu, 2 Jul 2015 21:33:23 -0400 Subject: Documentation: CodingStyle: remove broken links in the References section Remove 2 broken links for programming reference books in Appendix I. After a lookup on an Internet archives web site, it seems that these links have been broken for around 3 months. We can then assume that they will not be back up and safely remove them from the documentation. Signed-off-by: Olivier C. Larocque Signed-off-by: Jonathan Corbet --- Documentation/CodingStyle | 2 -- 1 file changed, 2 deletions(-) diff --git a/Documentation/CodingStyle b/Documentation/CodingStyle index b713c35..c06f817 100644 --- a/Documentation/CodingStyle +++ b/Documentation/CodingStyle @@ -929,13 +929,11 @@ The C Programming Language, Second Edition by Brian W. Kernighan and Dennis M. Ritchie. Prentice Hall, Inc., 1988. ISBN 0-13-110362-8 (paperback), 0-13-110370-9 (hardback). -URL: http://cm.bell-labs.com/cm/cs/cbook/ The Practice of Programming by Brian W. Kernighan and Rob Pike. Addison-Wesley, Inc., 1999. ISBN 0-201-61586-X. -URL: http://cm.bell-labs.com/cm/cs/tpop/ GNU manuals - where in compliance with K&R and this text - for cpp, gcc, gcc internals and indent, all available from http://www.gnu.org/manual/ -- cgit v1.1 From 60498bb58e9a614b9706f250667033f30632a25c Mon Sep 17 00:00:00 2001 From: Luis de Bethencourt Date: Fri, 3 Jul 2015 16:22:11 +0100 Subject: SubmittingPatches: update CodingStyle reference Link to the internal up to date Coding Style document inside the Kernel sources instead of an external one. Signed-off-by: Luis de Bethencourt Signed-off-by: Jonathan Corbet --- Documentation/SubmittingPatches | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Documentation/SubmittingPatches b/Documentation/SubmittingPatches index e9395df..67cf509 100644 --- a/Documentation/SubmittingPatches +++ b/Documentation/SubmittingPatches @@ -796,7 +796,7 @@ NO!!!! No more huge patch bombs to linux-kernel@vger.kernel.org people! Kernel Documentation/CodingStyle: - + Linus Torvalds's mail on the canonical patch format: -- cgit v1.1 From 9ba6e988c7208e3cb1f71862cc578397ae938159 Mon Sep 17 00:00:00 2001 From: Krzysztof Kozlowski Date: Sun, 5 Jul 2015 11:56:51 +0900 Subject: Documentation: ARM: EXYNOS: Extend boot loader interface documentation Extend the kernel-bootloader interface documentation with usage of register INFORM1 (0x0804) and different CPU resume address on Exynos542x family (with Multi-Cluster Power Management enabled). Additionally add glossary and reformat section titles. Signed-off-by: Krzysztof Kozlowski Signed-off-by: Jonathan Corbet --- Documentation/arm/Samsung/Bootloader-interface.txt | 15 ++++++++++++++- 1 file changed, 14 insertions(+), 1 deletion(-) diff --git a/Documentation/arm/Samsung/Bootloader-interface.txt b/Documentation/arm/Samsung/Bootloader-interface.txt index b96ead9..df8d4fb 100644 --- a/Documentation/arm/Samsung/Bootloader-interface.txt +++ b/Documentation/arm/Samsung/Bootloader-interface.txt @@ -15,6 +15,7 @@ executing kernel. 1. Non-Secure mode + Address: sysram_ns_base_addr Offset Value Purpose ============================================================================= @@ -28,6 +29,7 @@ Offset Value Purpose 2. Secure mode + Address: sysram_base_addr Offset Value Purpose ============================================================================= @@ -40,14 +42,25 @@ Offset Value Purpose Address: pmu_base_addr Offset Value Purpose ============================================================================= -0x0800 exynos_cpu_resume AFTR +0x0800 exynos_cpu_resume AFTR, suspend +0x0800 mcpm_entry_point (Exynos542x with MCPM) AFTR, suspend +0x0804 0xfcba0d10 (Magic cookie) AFTR +0x0804 0x00000bad (Magic cookie) System suspend 0x0814 exynos4_secondary_startup (Exynos4210 r1.1) Secondary CPU boot 0x0818 0xfcba0d10 (Magic cookie, Exynos4210 r1.1) AFTR 0x081C exynos_cpu_resume (Exynos4210 r1.1) AFTR 3. Other (regardless of secure/non-secure mode) + Address: pmu_base_addr Offset Value Purpose ============================================================================= 0x0908 Non-zero (only Exynos3250) Secondary CPU boot up indicator + + +4. Glossary + +AFTR - ARM Off Top Running, a low power mode, Cortex cores and many other +modules are power gated, except the TOP modules +MCPM - Multi-Cluster Power Management -- cgit v1.1 From dc12f20ba06f89bc60d4dfadaf2b03404858e205 Mon Sep 17 00:00:00 2001 From: Masanari Iida Date: Mon, 6 Jul 2015 23:41:57 +0900 Subject: Doc: powerpc: Fix typos in Documentation/powerpc This patch fix some spelling typo found in Documentation/powerpc. Signed-off-by: Masanari Iida Acked-by: Ian Munsie Signed-off-by: Jonathan Corbet --- Documentation/powerpc/cxl.txt | 2 +- Documentation/powerpc/dscr.txt | 6 +++--- Documentation/powerpc/qe_firmware.txt | 2 +- 3 files changed, 5 insertions(+), 5 deletions(-) diff --git a/Documentation/powerpc/cxl.txt b/Documentation/powerpc/cxl.txt index 2a230d01..205c1b8 100644 --- a/Documentation/powerpc/cxl.txt +++ b/Documentation/powerpc/cxl.txt @@ -133,7 +133,7 @@ User API The following file operations are supported on both slave and master devices. - A userspace library libcxl is avaliable here: + A userspace library libcxl is available here: https://github.com/ibm-capi/libcxl This provides a C interface to this kernel API. diff --git a/Documentation/powerpc/dscr.txt b/Documentation/powerpc/dscr.txt index 1ff4400..ece300c 100644 --- a/Documentation/powerpc/dscr.txt +++ b/Documentation/powerpc/dscr.txt @@ -4,7 +4,7 @@ DSCR register in powerpc allows user to have some control of prefetch of data stream in the processor. Please refer to the ISA documents or related manual for more detailed information regarding how to use this DSCR to attain this -control of the pefetches . This document here provides an overview of kernel +control of the prefetches . This document here provides an overview of kernel support for DSCR, related kernel objects, it's functionalities and exported user interface. @@ -44,7 +44,7 @@ user interface. value into every CPU's DSCR register right away and updates the current thread's DSCR value as well. - Changing the CPU specif DSCR default value in the sysfs does exactly + Changing the CPU specific DSCR default value in the sysfs does exactly the same thing as above but unlike the global one above, it just changes stuff for that particular CPU instead for all the CPUs on the system. @@ -62,7 +62,7 @@ user interface. Accessing DSCR through user level SPR (0x03) from user space will first create a facility unavailable exception. Inside this exception handler - all mfspr isntruction based read attempts will get emulated and returned + all mfspr instruction based read attempts will get emulated and returned where as the first mtspr instruction based write attempts will enable the DSCR facility for the next time around (both for read and write) by setting DSCR facility in the FSCR register. diff --git a/Documentation/powerpc/qe_firmware.txt b/Documentation/powerpc/qe_firmware.txt index 2031ddb..e7ac24a 100644 --- a/Documentation/powerpc/qe_firmware.txt +++ b/Documentation/powerpc/qe_firmware.txt @@ -117,7 +117,7 @@ specific been defined. This table describes the structure. Extended Modes This is a double word bit array (64 bits) that defines special functionality -which has an impact on the softwarew drivers. Each bit has its own impact +which has an impact on the software drivers. Each bit has its own impact and has special instructions for the s/w associated with it. This structure is described in this table: -- cgit v1.1 From 6609b638353c99c5736e05abd17197f1cb776e0e Mon Sep 17 00:00:00 2001 From: Diego Viola Date: Mon, 6 Jul 2015 14:33:21 -0300 Subject: README: GTK+ is a acronym Signed-off-by: Diego Viola Signed-off-by: Jonathan Corbet --- README | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README b/README index 69c68fb..a326a6a 100644 --- a/README +++ b/README @@ -161,7 +161,7 @@ CONFIGURING the kernel: "make xconfig" X windows (Qt) based configuration tool. - "make gconfig" X windows (Gtk) based configuration tool. + "make gconfig" X windows (GTK+) based configuration tool. "make oldconfig" Default all questions based on the contents of your existing ./.config file and asking about -- cgit v1.1 From 03bc7523cb4241a7f4ad67d7ae38027d1884a3ee Mon Sep 17 00:00:00 2001 From: Stefan Tatschner Date: Wed, 8 Jul 2015 10:41:07 +0200 Subject: can-doc: Fix wrong chapter reference In f35f6c8f7 (can: update MAINTAINERS and Documentation) chapter 3.3 was removed. This patch fixes some old references to chapter 3.4 which no longer exists. Signed-off-by: Stefan Tatschner Signed-off-by: Jonathan Corbet --- Documentation/networking/can.txt | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/Documentation/networking/can.txt b/Documentation/networking/can.txt index b48d4a1..fd1a1aa 100644 --- a/Documentation/networking/can.txt +++ b/Documentation/networking/can.txt @@ -510,7 +510,7 @@ solution for a couple of reasons: 4.1.2 RAW socket option CAN_RAW_ERR_FILTER - As described in chapter 3.4 the CAN interface driver can generate so + As described in chapter 3.3 the CAN interface driver can generate so called Error Message Frames that can optionally be passed to the user application in the same way as other CAN frames. The possible errors are divided into different error classes that may be filtered @@ -1152,7 +1152,7 @@ solution for a couple of reasons: $ ip link set canX type can restart Note that a restart will also create a CAN error message frame (see - also chapter 3.4). + also chapter 3.3). 6.6 CAN FD (flexible data rate) driver support -- cgit v1.1 From bdc89213710250d75fcbb86c2e623d1bbe8e3bb2 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?S=C3=A9bastien=20Hinderer?= Date: Sun, 12 Jul 2015 17:44:15 +0200 Subject: SubmittingPatches: fix wrong wording MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Signed-off-by: Sébastien Hinderer Signed-off-by: Jonathan Corbet --- Documentation/SubmittingPatches | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Documentation/SubmittingPatches b/Documentation/SubmittingPatches index 67cf509..918c972 100644 --- a/Documentation/SubmittingPatches +++ b/Documentation/SubmittingPatches @@ -340,7 +340,7 @@ on the changes you are submitting. It is important for a kernel developer to be able to "quote" your changes, using standard e-mail tools, so that they may comment on specific portions of your code. -For this reason, all patches should be submitting e-mail "inline". +For this reason, all patches should be submitted by e-mail "inline". WARNING: Be wary of your editor's word-wrap corrupting your patch, if you choose to cut-n-paste your patch. -- cgit v1.1 From 6e7ac7b4ab4d7b4486b4680ebbffbff3b1b0d775 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?S=C3=A9bastien=20Hinderer?= Date: Sun, 12 Jul 2015 17:49:55 +0200 Subject: SubmittingPatches: fix wrong wording MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit "facilitate easier reviewing" says the same thing twice. Signed-off-by: Sébastien Hinderer [jc: made it "easier review"] Signed-off-by: Jonathan Corbet --- Documentation/SubmittingPatches | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Documentation/SubmittingPatches b/Documentation/SubmittingPatches index 918c972..56ef2e6 100644 --- a/Documentation/SubmittingPatches +++ b/Documentation/SubmittingPatches @@ -94,7 +94,7 @@ generated it with diff(1), to ensure accuracy. If your changes produce a lot of deltas, you need to split them into individual patches which modify things in logical stages; see section -#3. This will facilitate easier reviewing by other kernel developers, +#3. This will facilitate review by other kernel developers, very important if you want your patch accepted. If you're using git, "git rebase -i" can help you with this process. If -- cgit v1.1 From 5d250eeb9d9d2237d49cd284ad35a6707694b88e Mon Sep 17 00:00:00 2001 From: Masanari Iida Date: Mon, 13 Jul 2015 12:29:11 +0900 Subject: Doc: pps: Fix file name in pps.txt This patch fix a file name of example code. Signed-off-by: Masanari Iida Acked-by: Rodolfo Giometti 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 c508cce..7cb7264 100644 --- a/Documentation/pps/pps.txt +++ b/Documentation/pps/pps.txt @@ -125,7 +125,7 @@ The same function may also run the defined echo function (pps_ktimer_echo(), passing to it the "ptr" pointer) if the user asked for that... etc.. -Please see the file drivers/pps/clients/ktimer.c for example code. +Please see the file drivers/pps/clients/pps-ktimer.c for example code. SYSFS support -- cgit v1.1 From acc068d967a63aef163167a66a02966f42052b80 Mon Sep 17 00:00:00 2001 From: Peter Huewe Date: Mon, 13 Jul 2015 22:02:48 +0200 Subject: Documenation: Update location of docproc.c docproc.c was moved in 2011 from scripts/basic to scripts -> updated the references accordingly Signed-off-by: Peter Huewe Signed-off-by: Jonathan Corbet --- Documentation/kernel-doc-nano-HOWTO.txt | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Documentation/kernel-doc-nano-HOWTO.txt b/Documentation/kernel-doc-nano-HOWTO.txt index acbc1a3..78f69cd 100644 --- a/Documentation/kernel-doc-nano-HOWTO.txt +++ b/Documentation/kernel-doc-nano-HOWTO.txt @@ -128,7 +128,7 @@ are: special place-holders for where the extracted documentation should go. -- scripts/basic/docproc.c +- scripts/docproc.c This is a program for converting SGML template files into SGML files. When a file is referenced it is searched for symbols -- cgit v1.1 From a10726bb5472ff2ed95180cfb5e82091c45d7b19 Mon Sep 17 00:00:00 2001 From: Rabin Vincent Date: Tue, 14 Jul 2015 07:35:11 +0200 Subject: Documentation: mm: fix location of extfrag_index /proc/extfrag_index does not exist. This file is in debugfs. Fix the description of extfrag_threshold to reflect this. Signed-off-by: Rabin Vincent Signed-off-by: Jonathan Corbet --- Documentation/sysctl/vm.txt | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/Documentation/sysctl/vm.txt b/Documentation/sysctl/vm.txt index 9832ec5..9c3f2f8 100644 --- a/Documentation/sysctl/vm.txt +++ b/Documentation/sysctl/vm.txt @@ -225,11 +225,11 @@ with your system. To disable them, echo 4 (bit 3) into drop_caches. extfrag_threshold This parameter affects whether the kernel will compact memory or direct -reclaim to satisfy a high-order allocation. /proc/extfrag_index shows what -the fragmentation index for each order is in each zone in the system. Values -tending towards 0 imply allocations would fail due to lack of memory, -values towards 1000 imply failures are due to fragmentation and -1 implies -that the allocation will succeed as long as watermarks are met. +reclaim to satisfy a high-order allocation. The extfrag/extfrag_index file in +debugfs shows what the fragmentation index for each order is in each zone in +the system. Values tending towards 0 imply allocations would fail due to lack +of memory, values towards 1000 imply failures are due to fragmentation and -1 +implies that the allocation will succeed as long as watermarks are met. The kernel will not compact memory in a zone if the fragmentation index is <= extfrag_threshold. The default value is 500. -- cgit v1.1 From 9e1aa7c8882050577c9223ba85c4ee49cd1da469 Mon Sep 17 00:00:00 2001 From: Wang Long Date: Thu, 16 Jul 2015 06:31:16 +0000 Subject: Documentation: Update filesystems/debugfs.txt This patch update the Documentation/filesystems/debugfs.txt file. The main work is to add the description of the following functions: debugfs_create_atomic_t debugfs_create_u32_array debugfs_create_devm_seqfile debugfs_create_file_size Signed-off-by: Wang Long Signed-off-by: Jonathan Corbet --- Documentation/filesystems/debugfs.txt | 40 +++++++++++++++++++++++++++++++++++ 1 file changed, 40 insertions(+) diff --git a/Documentation/filesystems/debugfs.txt b/Documentation/filesystems/debugfs.txt index 88ab81c..463f595 100644 --- a/Documentation/filesystems/debugfs.txt +++ b/Documentation/filesystems/debugfs.txt @@ -51,6 +51,17 @@ operations should be provided; others can be included as needed. Again, the return value will be a dentry pointer to the created file, NULL for error, or ERR_PTR(-ENODEV) if debugfs support is missing. +Create a file with an initial size, the following function can be used +instead: + + struct dentry *debugfs_create_file_size(const char *name, umode_t mode, + struct dentry *parent, void *data, + const struct file_operations *fops, + loff_t file_size); + +file_size is the initial file size. The other parameters are the same +as the function debugfs_create_file. + In a number of cases, the creation of a set of file operations is not actually necessary; the debugfs code provides a number of helper functions for simple situations. Files containing a single integer value can be @@ -100,6 +111,14 @@ A read on the resulting file will yield either Y (for non-zero values) or N, followed by a newline. If written to, it will accept either upper- or lower-case values, or 1 or 0. Any other input will be silently ignored. +Also, atomic_t values can be placed in debugfs with: + + struct dentry *debugfs_create_atomic_t(const char *name, umode_t mode, + struct dentry *parent, atomic_t *value) + +A read of this file will get atomic_t values, and a write of this file +will set atomic_t values. + Another option is exporting a block of arbitrary binary data, with this structure and function: @@ -147,6 +166,27 @@ The "base" argument may be 0, but you may want to build the reg32 array using __stringify, and a number of register names (macros) are actually byte offsets over a base for the register block. +If you want to dump an u32 array in debugfs, you can create file with: + + struct dentry *debugfs_create_u32_array(const char *name, umode_t mode, + struct dentry *parent, + u32 *array, u32 elements); + +The "array" argument provides data, and the "elements" argument is +the number of elements in the array. Note: Once array is created its +size can not be changed. + +There is a helper function to create device related seq_file: + + struct dentry *debugfs_create_devm_seqfile(struct device *dev, + const char *name, + struct dentry *parent, + int (*read_fn)(struct seq_file *s, + void *data)); + +The "dev" argument is the device related to this debugfs file, and +the "read_fn" is a function pointer which to be called to print the +seq_file content. There are a couple of other directory-oriented helper functions: -- cgit v1.1 From b9f2f4594c77073ca306ef345e9f9c1cde292dd3 Mon Sep 17 00:00:00 2001 From: Johannes Thumshirn Date: Fri, 17 Jul 2015 12:23:01 +0200 Subject: Documentation: Add MCB documentation Add basic introductory documentation for the MEN Chameleon Bus. Signed-off-by: Johannes Thumshirn Signed-off-by: Jonathan Corbet --- Documentation/men-chameleon-bus.txt | 162 ++++++++++++++++++++++++++++++++++++ MAINTAINERS | 1 + 2 files changed, 163 insertions(+) create mode 100644 Documentation/men-chameleon-bus.txt diff --git a/Documentation/men-chameleon-bus.txt b/Documentation/men-chameleon-bus.txt new file mode 100644 index 0000000..6d7bdb5 --- /dev/null +++ b/Documentation/men-chameleon-bus.txt @@ -0,0 +1,162 @@ + MEN Chameleon Bus + ================= + +Table of Contents +================= +1 Introduction + 1.1 Scope of this Document + 1.2 Limitations of the current implementation +2 Architecture + 2.1 MEN Chameleon Bus + 2.2 Carrier Devices + 2.3 Parser +3 Resource handling + 3.1 Memory Resources + 3.2 IRQs +4 Writing a MCB driver + 4.1 The driver structure + 4.2 Probing and attaching + 4.3 Initializing the driver + + +1 Introduction +=============== + This document describes the architecture and implementation of the MEN + Chameleon Bus (called MCB throughout this document). + +1.1 Scope of this Document +--------------------------- + This document is intended to be a short overview of the current + implementation and does by no means describe to complete possibilities of MCB + based devices. + +1.2 Limitations of the current implementation +---------------------------------------------- + The current implementation is limited to PCI and PCIe based carrier devices + that only use a single memory resource and share the PCI legacy IRQ. Not + implemented are: + - Multi-resource MCB devices like the VME Controller or M-Module carrier. + - MCB devices that need another MCB device, like SRAM for a DMA Controller's + buffer descriptors or a video controller's video memory. + - A per-carrier IRQ domain for carrier devices that have one (or more) IRQs + per MCB device like PCIe based carriers with MSI or MSI-X support. + +2 Architecture +=============== + MCB is divided in 3 functional blocks: + - The MEN Chameleon Bus itself, + - drivers for MCB Carrier Devices and + - the parser for the Chameleon table. + +2.1 MEN Chameleon Bus +---------------------- + The MEN Chameleon Bus is an artificial bus system that attaches to an MEN + Chameleon FPGA device. These devices are multi-function devices implemented + in a single FPGA and usually attached via some sort of PCI or PCIe link. Each + FPGA contains a header section describing the content of the FPGA. The header + lists the device id, PCI BAR, offset from the beginning of the PCI BAR, size + in the FPGA, interrupt number and some other properties currently not handled + by the MCB implementation. + +2.2 Carrier Devices +-------------------- + A carrier device is just an abstraction for the real world physical bus the + chameleon FPGA is attached to. Some IP Core drivers may need to interact with + properties of the carrier device (like querying the IRQ number of a PCI + device). To provide abstraction from the real hardware bus, an MCB carrier + device provides callback methods to translate the driver's MCB function calls + to hardware related function calls. For example a carrier device may + implement the get_irq() method which can be translate into a hardware bus + query for the IRQ number the device should use. + +2.3 Parser +----------- + The parser reads the 1st 512 bytes of a chameleon device and parses the + chameleon table. Currently the parser only supports the Chameleon v2 variant + of the chameleon table but can easily be adopted to support an older or + possible future variant. While parsing the table's entries new MCB devices + are allocated and their resources are assigned according to the resource + assignment in the chameleon table. After resource assignment is finished, the + MCB devices are registered at the MCB and thus at the driver core of the + Linux kernel. + +3 Resource handling +==================== + The current implementation assigns exactly one memory and one IRQ resource + per MCB device. But this is likely going to change in the future. + +3.1 Memory Resources +--------------------- + Each MCB device has exactly one memory resource, which can be requested from + the MCB bus. This memory resource is the physical address of the MCB device + inside the carrier and is intended to be passed to ioremap() and friends. It + is already requested from the kernel by calling request_mem_region(). + +3.2 IRQs +--------- + Each MCB device has exactly one IRQ resource, which can be requested from the + MCB bus. If a carrier device driver implements the ->get_irq() callback + method, the IRQ number assigned by the carrier device will be returned, + otherwise the IRQ number inside the chameleon table will be returned. This + number is suitable to be passed to request_irq(). + +4 Writing a MCB driver +======================= + +4.1 The driver structure +------------------------- + Each MCB driver has a structure to identify the device driver as well as + device ids which identify the IP Core inside the FPGA. The driver structure + also contaings callback methods which get executed on driver probe and + removal from the system. + + + static const struct mcb_device_id foo_ids[] = { + { .device = 0x123 }, + { } + }; + MODULE_DEVICE_TABLE(mcb, foo_ids); + + static struct mcb_driver foo_driver = { + driver = { + .name = "foo-bar", + .owner = THIS_MODULE, + }, + .probe = foo_probe, + .remove = foo_remove, + .id_table = foo_ids, + }; + +4.2 Probing and attaching +-------------------------- + When a driver is loaded and the MCB devices it services are found, the MCB + core will call the driver's probe callback method. When the driver is removed + from the system, the MCB core will call the driver's remove callback method. + + + static init foo_probe(struct mcb_device *mdev, const struct mcb_device_id *id); + static void foo_remove(struct mcb_device *mdev); + +4.3 Initializing the driver +---------------------------- + When the kernel is booted or your foo driver module is inserted, you have to + perform driver initialization. Usually it is enough to register your driver + module at the MCB core. + + + static int __init foo_init(void) + { + return mcb_register_driver(&foo_driver); + } + module_init(foo_init); + + static void __exit foo_exit(void) + { + mcb_unregister_driver(&foo_driver); + } + module_exit(foo_exit); + + The module_mcb_driver() macro can be used to reduce the above code. + + + module_mcb_driver(foo_driver); diff --git a/MAINTAINERS b/MAINTAINERS index 8133cef..b9b9156 100644 --- a/MAINTAINERS +++ b/MAINTAINERS @@ -6665,6 +6665,7 @@ M: Johannes Thumshirn S: Maintained F: drivers/mcb/ F: include/linux/mcb.h +F: Documentation/men-chameleon-bus.txt MEN F21BMC (Board Management Controller) M: Andreas Werner -- cgit v1.1 From 3d5583cc82e9d505e4b9a37615f7a28c7ea465b9 Mon Sep 17 00:00:00 2001 From: Ahmed Mohamed Abd EL Mawgood Date: Thu, 16 Jul 2015 23:17:36 +0200 Subject: fix Evolution submenu name in email-clients.txt I have noticed that there is no submenu in Evolution called Heading instead there is Paragraph style Signed-off-by: Ahmed Mohamed Signed-off-by: Jonathan Corbet --- Documentation/email-clients.txt | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Documentation/email-clients.txt b/Documentation/email-clients.txt index c7d49b8..3fa4508 100644 --- a/Documentation/email-clients.txt +++ b/Documentation/email-clients.txt @@ -93,7 +93,7 @@ Evolution (GUI) Some people use this successfully for patches. When composing mail select: Preformat - from Format->Heading->Preformatted (Ctrl-7) + from Format->Paragraph Style->Preformatted (Ctrl-7) or the toolbar Then use: -- cgit v1.1 From fce96568f314d0fb72f5ca4bba2f64e7164a7817 Mon Sep 17 00:00:00 2001 From: Jim Davis Date: Thu, 16 Jul 2015 12:50:50 -0700 Subject: Documentation: installed man pages don't need to be executable Install the man pages with mode 644 instead of 755 Signed-off-by: Jim Davis Signed-off-by: Jonathan Corbet --- Documentation/DocBook/Makefile | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Documentation/DocBook/Makefile b/Documentation/DocBook/Makefile index b6a6a2e..170042a 100644 --- a/Documentation/DocBook/Makefile +++ b/Documentation/DocBook/Makefile @@ -60,7 +60,7 @@ mandocs: $(MAN) installmandocs: mandocs mkdir -p /usr/local/man/man9/ - install $(obj)/man/*.9.gz /usr/local/man/man9/ + install -m 644 $(obj)/man/*.9.gz /usr/local/man/man9/ ### #External programs used -- cgit v1.1 From 6c121170115e9b6bb9dbe3e1daa8039976450bcf Mon Sep 17 00:00:00 2001 From: Jonathan Corbet Date: Fri, 24 Jul 2015 15:08:14 +0200 Subject: MAINTAINERS: Direct Documentation/DocBook/media properly The media maintainers want DocBook changes to go through their tree; document that wish accordingly. --- MAINTAINERS | 1 + 1 file changed, 1 insertion(+) diff --git a/MAINTAINERS b/MAINTAINERS index b9b9156..11e2516 100644 --- a/MAINTAINERS +++ b/MAINTAINERS @@ -3440,6 +3440,7 @@ X: Documentation/devicetree/ X: Documentation/acpi X: Documentation/power X: Documentation/spi +X: Documentation/DocBook/media T: git git://git.lwn.net/linux-2.6.git docs-next DOUBLETALK DRIVER -- cgit v1.1 From 013542caa898289f37695bea849f1e368254ec8b Mon Sep 17 00:00:00 2001 From: Benjamin Herr Date: Sat, 18 Jul 2015 14:31:40 +0200 Subject: Doc: fix trivial typo in SubmittingPatches This patch changes the tense of a verb in SubmittingPatches to ensure grammatical validity of the containing sentence. Signed-off-by: Benjamin Herr Signed-off-by: Jonathan Corbet --- Documentation/SubmittingPatches | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Documentation/SubmittingPatches b/Documentation/SubmittingPatches index 56ef2e6..80b9f54 100644 --- a/Documentation/SubmittingPatches +++ b/Documentation/SubmittingPatches @@ -90,7 +90,7 @@ patch. Make sure your patch does not include any extra files which do not belong in a patch submission. Make sure to review your patch -after- -generated it with diff(1), to ensure accuracy. +generating it with diff(1), to ensure accuracy. If your changes produce a lot of deltas, you need to split them into individual patches which modify things in logical stages; see section -- cgit v1.1 From 7c97211b61d8b91b8f88237e4bbb3a8959ecb18a Mon Sep 17 00:00:00 2001 From: Johannes Thumshirn Date: Thu, 23 Jul 2015 11:17:26 +0200 Subject: Documentation: Minor changes to men-chameleon-bus.txt Change men-chameleon-bus.txt according to the comments made by Randy Dunlap in https://lkml.org/lkml/2015/7/17/691. These are: * Some minor gramatical changes * Spelling fixes * Write the word "Chameleon" capitalized throughout the whole document * Explain MEN as MEN Mikro Elektronik GmbH. Signed-off-by: Johannes Thumshirn Signed-off-by: Jonathan Corbet --- Documentation/men-chameleon-bus.txt | 39 +++++++++++++++++++------------------ 1 file changed, 20 insertions(+), 19 deletions(-) diff --git a/Documentation/men-chameleon-bus.txt b/Documentation/men-chameleon-bus.txt index 6d7bdb5..30ded73 100644 --- a/Documentation/men-chameleon-bus.txt +++ b/Documentation/men-chameleon-bus.txt @@ -13,7 +13,7 @@ Table of Contents 3 Resource handling 3.1 Memory Resources 3.2 IRQs -4 Writing a MCB driver +4 Writing an MCB driver 4.1 The driver structure 4.2 Probing and attaching 4.3 Initializing the driver @@ -27,7 +27,7 @@ Table of Contents 1.1 Scope of this Document --------------------------- This document is intended to be a short overview of the current - implementation and does by no means describe to complete possibilities of MCB + implementation and does by no means describe the complete possibilities of MCB based devices. 1.2 Limitations of the current implementation @@ -43,40 +43,41 @@ Table of Contents 2 Architecture =============== - MCB is divided in 3 functional blocks: + MCB is divided into 3 functional blocks: - The MEN Chameleon Bus itself, - drivers for MCB Carrier Devices and - the parser for the Chameleon table. 2.1 MEN Chameleon Bus ---------------------- - The MEN Chameleon Bus is an artificial bus system that attaches to an MEN - Chameleon FPGA device. These devices are multi-function devices implemented - in a single FPGA and usually attached via some sort of PCI or PCIe link. Each - FPGA contains a header section describing the content of the FPGA. The header - lists the device id, PCI BAR, offset from the beginning of the PCI BAR, size - in the FPGA, interrupt number and some other properties currently not handled - by the MCB implementation. + The MEN Chameleon Bus is an artificial bus system that attaches to a so + called Chameleon FPGA device found on some hardware produced my MEN Mikro + Elektronik GmbH. These devices are multi-function devices implemented in a + single FPGA and usually attached via some sort of PCI or PCIe link. Each + FPGA contains a header section describing the content of the FPGA. The + header lists the device id, PCI BAR, offset from the beginning of the PCI + BAR, size in the FPGA, interrupt number and some other properties currently + not handled by the MCB implementation. 2.2 Carrier Devices -------------------- A carrier device is just an abstraction for the real world physical bus the - chameleon FPGA is attached to. Some IP Core drivers may need to interact with + Chameleon FPGA is attached to. Some IP Core drivers may need to interact with properties of the carrier device (like querying the IRQ number of a PCI device). To provide abstraction from the real hardware bus, an MCB carrier device provides callback methods to translate the driver's MCB function calls to hardware related function calls. For example a carrier device may - implement the get_irq() method which can be translate into a hardware bus + implement the get_irq() method which can be translated into a hardware bus query for the IRQ number the device should use. 2.3 Parser ----------- - The parser reads the 1st 512 bytes of a chameleon device and parses the - chameleon table. Currently the parser only supports the Chameleon v2 variant - of the chameleon table but can easily be adopted to support an older or + The parser reads the first 512 bytes of a Chameleon device and parses the + Chameleon table. Currently the parser only supports the Chameleon v2 variant + of the Chameleon table but can easily be adopted to support an older or possible future variant. While parsing the table's entries new MCB devices are allocated and their resources are assigned according to the resource - assignment in the chameleon table. After resource assignment is finished, the + assignment in the Chameleon table. After resource assignment is finished, the MCB devices are registered at the MCB and thus at the driver core of the Linux kernel. @@ -97,17 +98,17 @@ Table of Contents Each MCB device has exactly one IRQ resource, which can be requested from the MCB bus. If a carrier device driver implements the ->get_irq() callback method, the IRQ number assigned by the carrier device will be returned, - otherwise the IRQ number inside the chameleon table will be returned. This + otherwise the IRQ number inside the Chameleon table will be returned. This number is suitable to be passed to request_irq(). -4 Writing a MCB driver +4 Writing an MCB driver ======================= 4.1 The driver structure ------------------------- Each MCB driver has a structure to identify the device driver as well as device ids which identify the IP Core inside the FPGA. The driver structure - also contaings callback methods which get executed on driver probe and + also contains callback methods which get executed on driver probe and removal from the system. -- cgit v1.1 From e9c9963b439db734e9705f96909c5a3388dd81bb Mon Sep 17 00:00:00 2001 From: Jonathan Corbet Date: Thu, 6 Aug 2015 12:44:23 -0600 Subject: Revert "DocBook: Avoid building man pages repeatedly and inconsistently" This reverts commit b44158b17099ed5c7c8f4bfb7029942adbfbc318. This commit introduced warnings and possibly inconsistent results into the doc build process. The goal is good but it will need to be achieved another way. Reported-by: Masanari Iida Signed-off-by: Jonathan Corbet --- Documentation/DocBook/Makefile | 10 +--------- Documentation/DocBook/device-drivers.tmpl | 6 ------ Documentation/DocBook/gadget.tmpl | 3 --- Documentation/DocBook/kernel-api.tmpl | 6 ------ 4 files changed, 1 insertion(+), 24 deletions(-) diff --git a/Documentation/DocBook/Makefile b/Documentation/DocBook/Makefile index 83fcb6c..11a4145 100644 --- a/Documentation/DocBook/Makefile +++ b/Documentation/DocBook/Makefile @@ -56,13 +56,6 @@ htmldocs: $(HTML) MAN := $(patsubst %.xml, %.9, $(BOOKS)) mandocs: $(MAN) - @dups=$$(sed -n 's/.*\([^<]*\)<\/refname>.*/\1/p' \ - $(obj)/*.xml.noextra | sort | uniq -d); \ - if [ -n "$$dups" ]; then \ - echo >&2 "The following manual pages are generated more than once:"; \ - printf >&2 '%s\n' "$$dups"; \ - exit 1; \ - fi find $(obj)/man -name '*.9' | xargs gzip -nf installmandocs: mandocs @@ -157,7 +150,7 @@ quiet_cmd_db2html = HTML $@ cp $(PNG-$(basename $(notdir $@))) $(patsubst %.html,%,$@); fi quiet_cmd_db2man = MAN $@ - cmd_db2man = if grep -q refentry $<; then xmlif excludeextra=1 <$< >$<.noextra && xmlto man $(XMLTOFLAGS) -o $(obj)/man $<.noextra ; fi + cmd_db2man = if grep -q refentry $<; then xmlto man $(XMLTOFLAGS) -o $(obj)/man $< ; fi %.9 : %.xml @(which xmlto > /dev/null 2>&1) || \ (echo "*** You need to install xmlto ***"; \ @@ -224,7 +217,6 @@ clean-files := $(DOCBOOKS) \ $(patsubst %.xml, %.ps, $(DOCBOOKS)) \ $(patsubst %.xml, %.pdf, $(DOCBOOKS)) \ $(patsubst %.xml, %.html, $(DOCBOOKS)) \ - $(patsubst %, %.noextra, $(DOCBOOKS)) \ $(patsubst %.xml, %.9, $(DOCBOOKS)) \ $(index) diff --git a/Documentation/DocBook/device-drivers.tmpl b/Documentation/DocBook/device-drivers.tmpl index 87853ea..faf09d4 100644 --- a/Documentation/DocBook/device-drivers.tmpl +++ b/Documentation/DocBook/device-drivers.tmpl @@ -194,13 +194,8 @@ X!Edrivers/pnp/system.c Sound Devices - - !Iinclude/sound/core.h - !Esound/sound_core.c - - !Iinclude/sound/pcm.h !Esound/core/pcm.c !Esound/core/device.c @@ -216,7 +211,6 @@ X!Edrivers/pnp/system.c !Esound/core/hwdep.c !Esound/core/pcm_native.c !Esound/core/memalloc.c - diff --git a/Documentation/DocBook/gadget.tmpl b/Documentation/DocBook/gadget.tmpl index e1b87bd..6416292 100644 --- a/Documentation/DocBook/gadget.tmpl +++ b/Documentation/DocBook/gadget.tmpl @@ -488,10 +488,7 @@ These are the same types and constants used by host side drivers (and usbcore). - - !Iinclude/linux/usb/ch9.h - Core Objects and Methods diff --git a/Documentation/DocBook/kernel-api.tmpl b/Documentation/DocBook/kernel-api.tmpl index 722249a..ecfd0ea 100644 --- a/Documentation/DocBook/kernel-api.tmpl +++ b/Documentation/DocBook/kernel-api.tmpl @@ -58,11 +58,8 @@ String Conversions !Elib/vsprintf.c - - !Finclude/linux/kernel.h kstrtol !Finclude/linux/kernel.h kstrtoul - !Elib/kstrtox.c String Manipulation @@ -181,10 +178,7 @@ X!Ekernel/module.c Hardware Interfaces Interrupt Handling - - !Ekernel/irq/manage.c - DMA Channels -- cgit v1.1 From 64e32895f9d87aaa0842c07d0b17f4895955db20 Mon Sep 17 00:00:00 2001 From: Jakub Wilk Date: Mon, 27 Jul 2015 10:15:18 +0200 Subject: SubmittingPatches: remove stray quote character Signed-off-by: Jakub Wilk Signed-off-by: Jonathan Corbet --- Documentation/SubmittingPatches | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Documentation/SubmittingPatches b/Documentation/SubmittingPatches index 80b9f54..fa596d8 100644 --- a/Documentation/SubmittingPatches +++ b/Documentation/SubmittingPatches @@ -739,7 +739,7 @@ interest on a single line; it should look something like: git://jdelvare.pck.nerim.net/jdelvare-2.6 i2c-for-linus - to get these changes:" + to get these changes: A pull request should also include an overall message saying what will be included in the request, a "git shortlog" listing of the patches -- cgit v1.1 From a4c6ebede2f99fc3aaa5a42228a16747d0aa2504 Mon Sep 17 00:00:00 2001 From: Danilo Cesar Lemes de Paula Date: Tue, 4 Aug 2015 09:04:08 -0300 Subject: scripts/kernel-doc Allow struct arguments documentation in struct body Describing arguments at top of a struct definition works fine for small/medium size structs, but it definitely doesn't work well for struct with a huge list of elements. Keeping the arguments list inside the struct body makes it easier to maintain the documentation. ie: /** * struct my_struct - short description * @a: first member * @b: second member * * Longer description */ struct my_struct { int a; int b; /** * @c: This is longer description of C * * You can use paragraphs to describe arguments * using this method. */ int c; }; This patch allows the use of this kind of syntax. Only one argument per comment and user can use how many paragraphs he needs. It should start with /**, which is already being used by kernel-doc. If those comment doesn't follow those rules, it will be ignored. Signed-off-by: Danilo Cesar Lemes de Paula Cc: Randy Dunlap Cc: Daniel Vetter Cc: Laurent Pinchart Cc: Jonathan Corbet Cc: Herbert Xu Cc: Stephan Mueller Cc: Michal Marek Cc: linux-kernel@vger.kernel.org Cc: linux-doc@vger.kernel.org Cc: intel-gfx Cc: dri-devel Signed-off-by: Jonathan Corbet --- scripts/kernel-doc | 77 ++++++++++++++++++++++++++++++++++++++++++++++++++++-- 1 file changed, 75 insertions(+), 2 deletions(-) diff --git a/scripts/kernel-doc b/scripts/kernel-doc index 0ac1a07..3a4d895 100755 --- a/scripts/kernel-doc +++ b/scripts/kernel-doc @@ -133,6 +133,30 @@ use strict; # # All descriptions can be multiline, except the short function description. # +# For really longs structs, you can also describe arguments inside the +# body of the struct. +# eg. +# /** +# * struct my_struct - short description +# * @a: first member +# * @b: second member +# * +# * Longer description +# */ +# struct my_struct { +# int a; +# int b; +# /** +# * @c: This is longer description of C +# * +# * You can use paragraphs to describe arguments +# * using this method. +# */ +# int c; +# }; +# +# This should be use only for struct/enum members. +# # You can also add additional sections. When documenting kernel functions you # should document the "Context:" of the function, e.g. whether the functions # can be called form interrupts. Unlike other sections you can end it with an @@ -296,9 +320,19 @@ my $lineprefix=""; # 2 - scanning field start. # 3 - scanning prototype. # 4 - documentation block +# 5 - gathering documentation outside main block my $state; my $in_doc_sect; +# Split Doc State +# 0 - Invalid (Before start or after finish) +# 1 - Is started (the /** was found inside a struct) +# 2 - The @parameter header was found, start accepting multi paragraph text. +# 3 - Finished (the */ was found) +# 4 - Error - Comment without header was found. Spit a warning as it's not +# proper kernel-doc and ignore the rest. +my $split_doc_state; + #declaration types: can be # 'function', 'struct', 'union', 'enum', 'typedef' my $decl_type; @@ -313,6 +347,9 @@ my $doc_decl = $doc_com . '(\w+)'; my $doc_sect = $doc_com . '([' . $doc_special . ']?[\w\s]+):(.*)'; my $doc_content = $doc_com_body . '(.*)'; my $doc_block = $doc_com . 'DOC:\s*(.*)?'; +my $doc_split_start = '^\s*/\*\*\s*$'; +my $doc_split_sect = '\s*\*\s*(@[\w\s]+):(.*)'; +my $doc_split_end = '^\s*\*/\s*$'; my %constants; my %parameterdescs; @@ -2190,6 +2227,7 @@ sub reset_state { $prototype = ""; $state = 0; + $split_doc_state = 0; } sub tracepoint_munge($) { @@ -2462,7 +2500,6 @@ sub process_file($) { } $section = $newsection; } elsif (/$doc_end/) { - if (($contents ne "") && ($contents ne "\n")) { dump_section($file, $section, xml_escape($contents)); $section = $section_default; @@ -2503,8 +2540,44 @@ sub process_file($) { print STDERR "Warning(${file}:$.): bad line: $_"; ++$warnings; } + } elsif ($state == 5) { # scanning for split parameters + # First line (state 1) needs to be a @parameter + if ($split_doc_state == 1 && /$doc_split_sect/o) { + $section = $1; + $contents = $2; + if ($contents ne "") { + while ((substr($contents, 0, 1) eq " ") || + substr($contents, 0, 1) eq "\t") { + $contents = substr($contents, 1); + } + $contents .= "\n"; + } + $split_doc_state = 2; + # Documentation block end */ + } elsif (/$doc_split_end/) { + if (($contents ne "") && ($contents ne "\n")) { + dump_section($file, $section, xml_escape($contents)); + $section = $section_default; + $contents = ""; + } + $state = 3; + $split_doc_state = 0; + # Regular text + } elsif (/$doc_content/) { + if ($split_doc_state == 2) { + $contents .= $1 . "\n"; + } elsif ($split_doc_state == 1) { + $split_doc_state = 4; + print STDERR "Warning(${file}:$.): "; + print STDERR "Incorrect use of kernel-doc format: $_"; + ++$warnings; + } + } } elsif ($state == 3) { # scanning for function '{' (end of prototype) - if ($decl_type eq 'function') { + if (/$doc_split_start/) { + $state = 5; + $split_doc_state = 1; + } elsif ($decl_type eq 'function') { process_state3_function($_, $file); } else { process_state3_type($_, $file); -- cgit v1.1 From b325e832e9478b920c1b8366623fe456a3527513 Mon Sep 17 00:00:00 2001 From: Murali Karicheri Date: Tue, 4 Aug 2015 12:36:43 -0400 Subject: ARM: keystone: add documentation for SoCs and EVMs Currently there is no general documentation on Keystone SoCs in the Linux Documentation folder of the source tree. This patch adds some essential documentation with links to help users of Keystone Linux and also provide links to existing documents where necessary. Signed-off-by: Murali Karicheri Signed-off-by: Jonathan Corbet --- Documentation/arm/keystone/Overview.txt | 73 +++++++++++++++++++++++++++++++++ 1 file changed, 73 insertions(+) create mode 100644 Documentation/arm/keystone/Overview.txt diff --git a/Documentation/arm/keystone/Overview.txt b/Documentation/arm/keystone/Overview.txt new file mode 100644 index 0000000..f17bc4c --- /dev/null +++ b/Documentation/arm/keystone/Overview.txt @@ -0,0 +1,73 @@ + TI Keystone Linux Overview + -------------------------- + +Introduction +------------ +Keystone range of SoCs are based on ARM Cortex-A15 MPCore Processors +and c66x DSP cores. This document describes essential information required +for users to run Linux on Keystone based EVMs from Texas Instruments. + +Following SoCs & EVMs are currently supported:- + +------------ K2HK SoC and EVM -------------------------------------------------- + +a.k.a Keystone 2 Hawking/Kepler SoC +TCI6636K2H & TCI6636K2K: See documentation at + http://www.ti.com/product/tci6638k2k + http://www.ti.com/product/tci6638k2h + +EVM: +http://www.advantech.com/Support/TI-EVM/EVMK2HX_sd.aspx + +------------ K2E SoC and EVM --------------------------------------------------- + +a.k.a Keystone 2 Edison SoC +K2E - 66AK2E05: See documentation at + http://www.ti.com/product/66AK2E05/technicaldocuments + +EVM: +https://www.einfochips.com/index.php/partnerships/texas-instruments/k2e-evm.html + +------------ K2L SoC and EVM --------------------------------------------------- + +a.k.a Keystone 2 Lamarr SoC +K2L - TCI6630K2L: See documentation at + http://www.ti.com/product/TCI6630K2L/technicaldocuments +EVM: +https://www.einfochips.com/index.php/partnerships/texas-instruments/k2l-evm.html + +Configuration +------------- + +All of the K2 SoCs/EVMs share a common defconfig, keystone_defconfig and same +image is used to boot on individual EVMs. The platform configuration is +specified through DTS. Following are the DTS used:- + K2HK EVM : k2hk-evm.dts + K2E EVM : k2e-evm.dts + K2L EVM : k2l-evm.dts + +The device tree documentation for the keystone machines are located at + Documentation/devicetree/bindings/arm/keystone/keystone.txt + +Known issues & workaround +------------------------- + +Some of the device drivers used on keystone are re-used from that from +DaVinci and other TI SoCs. These device drivers may use clock APIs directly. +Some of the keystone specific drivers such as netcp uses run time power +management API instead to enable clock. As this API has limitations on +keystone, following workaround is needed to boot Linux. + + Add 'clk_ignore_unused' to the bootargs env variable in u-boot. Otherwise + clock frameworks will try to disable clocks that are unused and disable + the hardware. This is because netcp related power domain and clock + domains are enabled in u-boot as run time power management API currently + doesn't enable clocks for netcp due to a limitation. This workaround is + expected to be removed in the future when proper API support becomes + available. Until then, this work around is needed. + + +Document Author +--------------- +Murali Karicheri +Copyright 2015 Texas Instruments -- cgit v1.1 From 81db32a3c4627605a0e950d27a403ea02447ab60 Mon Sep 17 00:00:00 2001 From: Tim Bird Date: Mon, 10 Aug 2015 15:16:16 -0700 Subject: doc: Add more workqueue functions to the documentation There are some workqueue functions declared in workqueue.h, so include that in the workqueue section of the DocBook docs. Signed-off-by: Tim Bird Acked-by: Randy Dunlap Signed-off-by: Jonathan Corbet --- Documentation/DocBook/device-drivers.tmpl | 1 + 1 file changed, 1 insertion(+) diff --git a/Documentation/DocBook/device-drivers.tmpl b/Documentation/DocBook/device-drivers.tmpl index faf09d4..bbc1d7e 100644 --- a/Documentation/DocBook/device-drivers.tmpl +++ b/Documentation/DocBook/device-drivers.tmpl @@ -66,6 +66,7 @@ !Ekernel/time/hrtimer.c Workqueues and Kevents +!Iinclude/linux/workqueue.h !Ekernel/workqueue.c Internal Functions -- cgit v1.1 From 4983953dbd038fd720e7e16eb9bad5d8ea059ccf Mon Sep 17 00:00:00 2001 From: David Drysdale Date: Mon, 10 Aug 2015 09:00:44 +0100 Subject: Documentation: describe how to add a system call Add a document describing the process of adding a new system call, including the need for a flags argument for future compatibility, and covering 32-bit/64-bit concerns (albeit in an x86-centric way). Signed-off-by: David Drysdale Reviewed-by: Michael Kerrisk Reviewed-by: Eric B Munson Reviewed-by: Kees Cook Reviewed-by: Randy Dunlap Reviewed-by: Josh Triplett Signed-off-by: Jonathan Corbet --- Documentation/adding-syscalls.txt | 527 ++++++++++++++++++++++++++++++++++++++ 1 file changed, 527 insertions(+) create mode 100644 Documentation/adding-syscalls.txt diff --git a/Documentation/adding-syscalls.txt b/Documentation/adding-syscalls.txt new file mode 100644 index 0000000..cc2d4ac --- /dev/null +++ b/Documentation/adding-syscalls.txt @@ -0,0 +1,527 @@ +Adding a New System Call +======================== + +This document describes what's involved in adding a new system call to the +Linux kernel, over and above the normal submission advice in +Documentation/SubmittingPatches. + + +System Call Alternatives +------------------------ + +The first thing to consider when adding a new system call is whether one of +the alternatives might be suitable instead. Although system calls are the +most traditional and most obvious interaction points between userspace and the +kernel, there are other possibilities -- choose what fits best for your +interface. + + - If the operations involved can be made to look like a filesystem-like + object, it may make more sense to create a new filesystem or device. This + also makes it easier to encapsulate the new functionality in a kernel module + rather than requiring it to be built into the main kernel. + - If the new functionality involves operations where the kernel notifies + userspace that something has happened, then returning a new file + descriptor for the relevant object allows userspace to use + poll/select/epoll to receive that notification. + - However, operations that don't map to read(2)/write(2)-like operations + have to be implemented as ioctl(2) requests, which can lead to a + somewhat opaque API. + - If you're just exposing runtime system information, a new node in sysfs + (see Documentation/filesystems/sysfs.txt) or the /proc filesystem may be + more appropriate. However, access to these mechanisms requires that the + relevant filesystem is mounted, which might not always be the case (e.g. + in a namespaced/sandboxed/chrooted environment). Avoid adding any API to + debugfs, as this is not considered a 'production' interface to userspace. + - If the operation is specific to a particular file or file descriptor, then + an additional fcntl(2) command option may be more appropriate. However, + fcntl(2) is a multiplexing system call that hides a lot of complexity, so + this option is best for when the new function is closely analogous to + existing fcntl(2) functionality, or the new functionality is very simple + (for example, getting/setting a simple flag related to a file descriptor). + - If the operation is specific to a particular task or process, then an + additional prctl(2) command option may be more appropriate. As with + fcntl(2), this system call is a complicated multiplexor so is best reserved + for near-analogs of existing prctl() commands or getting/setting a simple + flag related to a process. + + +Designing the API: Planning for Extension +----------------------------------------- + +A new system call forms part of the API of the kernel, and has to be supported +indefinitely. As such, it's a very good idea to explicitly discuss the +interface on the kernel mailing list, and it's important to plan for future +extensions of the interface. + +(The syscall table is littered with historical examples where this wasn't done, +together with the corresponding follow-up system calls -- eventfd/eventfd2, +dup2/dup3, inotify_init/inotify_init1, pipe/pipe2, renameat/renameat2 -- so +learn from the history of the kernel and plan for extensions from the start.) + +For simpler system calls that only take a couple of arguments, the preferred +way to allow for future extensibility is to include a flags argument to the +system call. To make sure that userspace programs can safely use flags +between kernel versions, check whether the flags value holds any unknown +flags, and reject the system call (with EINVAL) if it does: + + if (flags & ~(THING_FLAG1 | THING_FLAG2 | THING_FLAG3)) + return -EINVAL; + +(If no flags values are used yet, check that the flags argument is zero.) + +For more sophisticated system calls that involve a larger number of arguments, +it's preferred to encapsulate the majority of the arguments into a structure +that is passed in by pointer. Such a structure can cope with future extension +by including a size argument in the structure: + + struct xyzzy_params { + u32 size; /* userspace sets p->size = sizeof(struct xyzzy_params) */ + u32 param_1; + u64 param_2; + u64 param_3; + }; + +As long as any subsequently added field, say param_4, is designed so that a +zero value gives the previous behaviour, then this allows both directions of +version mismatch: + + - To cope with a later userspace program calling an older kernel, the kernel + code should check that any memory beyond the size of the structure that it + expects is zero (effectively checking that param_4 == 0). + - To cope with an older userspace program calling a newer kernel, the kernel + code can zero-extend a smaller instance of the structure (effectively + setting param_4 = 0). + +See perf_event_open(2) and the perf_copy_attr() function (in +kernel/events/core.c) for an example of this approach. + + +Designing the API: Other Considerations +--------------------------------------- + +If your new system call allows userspace to refer to a kernel object, it +should use a file descriptor as the handle for that object -- don't invent a +new type of userspace object handle when the kernel already has mechanisms and +well-defined semantics for using file descriptors. + +If your new xyzzy(2) system call does return a new file descriptor, then the +flags argument should include a value that is equivalent to setting O_CLOEXEC +on the new FD. This makes it possible for userspace to close the timing +window between xyzzy() and calling fcntl(fd, F_SETFD, FD_CLOEXEC), where an +unexpected fork() and execve() in another thread could leak a descriptor to +the exec'ed program. (However, resist the temptation to re-use the actual value +of the O_CLOEXEC constant, as it is architecture-specific and is part of a +numbering space of O_* flags that is fairly full.) + +If your system call returns a new file descriptor, you should also consider +what it means to use the poll(2) family of system calls on that file +descriptor. Making a file descriptor ready for reading or writing is the +normal way for the kernel to indicate to userspace that an event has +occurred on the corresponding kernel object. + +If your new xyzzy(2) system call involves a filename argument: + + int sys_xyzzy(const char __user *path, ..., unsigned int flags); + +you should also consider whether an xyzzyat(2) version is more appropriate: + + int sys_xyzzyat(int dfd, const char __user *path, ..., unsigned int flags); + +This allows more flexibility for how userspace specifies the file in question; +in particular it allows userspace to request the functionality for an +already-opened file descriptor using the AT_EMPTY_PATH flag, effectively giving +an fxyzzy(3) operation for free: + + - xyzzyat(AT_FDCWD, path, ..., 0) is equivalent to xyzzy(path,...) + - xyzzyat(fd, "", ..., AT_EMPTY_PATH) is equivalent to fxyzzy(fd, ...) + +(For more details on the rationale of the *at() calls, see the openat(2) man +page; for an example of AT_EMPTY_PATH, see the statat(2) man page.) + +If your new xyzzy(2) system call involves a parameter describing an offset +within a file, make its type loff_t so that 64-bit offsets can be supported +even on 32-bit architectures. + +If your new xyzzy(2) system call involves privileged functionality, it needs +to be governed by the appropriate Linux capability bit (checked with a call to +capable()), as described in the capabilities(7) man page. Choose an existing +capability bit that governs related functionality, but try to avoid combining +lots of only vaguely related functions together under the same bit, as this +goes against capabilities' purpose of splitting the power of root. In +particular, avoid adding new uses of the already overly-general CAP_SYS_ADMIN +capability. + +If your new xyzzy(2) system call manipulates a process other than the calling +process, it should be restricted (using a call to ptrace_may_access()) so that +only a calling process with the same permissions as the target process, or +with the necessary capabilities, can manipulate the target process. + +Finally, be aware that some non-x86 architectures have an easier time if +system call parameters that are explicitly 64-bit fall on odd-numbered +arguments (i.e. parameter 1, 3, 5), to allow use of contiguous pairs of 32-bit +registers. (This concern does not apply if the arguments are part of a +structure that's passed in by pointer.) + + +Proposing the API +----------------- + +To make new system calls easy to review, it's best to divide up the patchset +into separate chunks. These should include at least the following items as +distinct commits (each of which is described further below): + + - The core implementation of the system call, together with prototypes, + generic numbering, Kconfig changes and fallback stub implementation. + - Wiring up of the new system call for one particular architecture, usually + x86 (including all of x86_64, x86_32 and x32). + - A demonstration of the use of the new system call in userspace via a + selftest in tools/testing/selftests/. + - A draft man-page for the new system call, either as plain text in the + cover letter, or as a patch to the (separate) man-pages repository. + +New system call proposals, like any change to the kernel's API, should always +be cc'ed to linux-api@vger.kernel.org. + + +Generic System Call Implementation +---------------------------------- + +The main entry point for your new xyzzy(2) system call will be called +sys_xyzzy(), but you add this entry point with the appropriate +SYSCALL_DEFINEn() macro rather than explicitly. The 'n' indicates the number +of arguments to the system call, and the macro takes the system call name +followed by the (type, name) pairs for the parameters as arguments. Using +this macro allows metadata about the new system call to be made available for +other tools. + +The new entry point also needs a corresponding function prototype, in +include/linux/syscalls.h, marked as asmlinkage to match the way that system +calls are invoked: + + asmlinkage long sys_xyzzy(...); + +Some architectures (e.g. x86) have their own architecture-specific syscall +tables, but several other architectures share a generic syscall table. Add your +new system call to the generic list by adding an entry to the list in +include/uapi/asm-generic/unistd.h: + + #define __NR_xyzzy 292 + __SYSCALL(__NR_xyzzy, sys_xyzzy) + +Also update the __NR_syscalls count to reflect the additional system call, and +note that if multiple new system calls are added in the same merge window, +your new syscall number may get adjusted to resolve conflicts. + +The file kernel/sys_ni.c provides a fallback stub implementation of each system +call, returning -ENOSYS. Add your new system call here too: + + cond_syscall(sys_xyzzy); + +Your new kernel functionality, and the system call that controls it, should +normally be optional, so add a CONFIG option (typically to init/Kconfig) for +it. As usual for new CONFIG options: + + - Include a description of the new functionality and system call controlled + by the option. + - Make the option depend on EXPERT if it should be hidden from normal users. + - Make any new source files implementing the function dependent on the CONFIG + option in the Makefile (e.g. "obj-$(CONFIG_XYZZY_SYSCALL) += xyzzy.c"). + - Double check that the kernel still builds with the new CONFIG option turned + off. + +To summarize, you need a commit that includes: + + - CONFIG option for the new function, normally in init/Kconfig + - SYSCALL_DEFINEn(xyzzy, ...) for the entry point + - corresponding prototype in include/linux/syscalls.h + - generic table entry in include/uapi/asm-generic/unistd.h + - fallback stub in kernel/sys_ni.c + + +x86 System Call Implementation +------------------------------ + +To wire up your new system call for x86 platforms, you need to update the +master syscall tables. Assuming your new system call isn't special in some +way (see below), this involves a "common" entry (for x86_64 and x32) in +arch/x86/entry/syscalls/syscall_64.tbl: + + 333 common xyzzy sys_xyzzy + +and an "i386" entry in arch/x86/entry/syscalls/syscall_32.tbl: + + 380 i386 xyzzy sys_xyzzy + +Again, these numbers are liable to be changed if there are conflicts in the +relevant merge window. + + +Compatibility System Calls (Generic) +------------------------------------ + +For most system calls the same 64-bit implementation can be invoked even when +the userspace program is itself 32-bit; even if the system call's parameters +include an explicit pointer, this is handled transparently. + +However, there are a couple of situations where a compatibility layer is +needed to cope with size differences between 32-bit and 64-bit. + +The first is if the 64-bit kernel also supports 32-bit userspace programs, and +so needs to parse areas of (__user) memory that could hold either 32-bit or +64-bit values. In particular, this is needed whenever a system call argument +is: + + - a pointer to a pointer + - a pointer to a struct containing a pointer (e.g. struct iovec __user *) + - a pointer to a varying sized integral type (time_t, off_t, long, ...) + - a pointer to a struct containing a varying sized integral type. + +The second situation that requires a compatibility layer is if one of the +system call's arguments has a type that is explicitly 64-bit even on a 32-bit +architecture, for example loff_t or __u64. In this case, a value that arrives +at a 64-bit kernel from a 32-bit application will be split into two 32-bit +values, which then need to be re-assembled in the compatibility layer. + +(Note that a system call argument that's a pointer to an explicit 64-bit type +does *not* need a compatibility layer; for example, splice(2)'s arguments of +type loff_t __user * do not trigger the need for a compat_ system call.) + +The compatibility version of the system call is called compat_sys_xyzzy(), and +is added with the COMPAT_SYSCALL_DEFINEn() macro, analogously to +SYSCALL_DEFINEn. This version of the implementation runs as part of a 64-bit +kernel, but expects to receive 32-bit parameter values and does whatever is +needed to deal with them. (Typically, the compat_sys_ version converts the +values to 64-bit versions and either calls on to the sys_ version, or both of +them call a common inner implementation function.) + +The compat entry point also needs a corresponding function prototype, in +include/linux/compat.h, marked as asmlinkage to match the way that system +calls are invoked: + + asmlinkage long compat_sys_xyzzy(...); + +If the system call involves a structure that is laid out differently on 32-bit +and 64-bit systems, say struct xyzzy_args, then the include/linux/compat.h +header file should also include a compat version of the structure (struct +compat_xyzzy_args) where each variable-size field has the appropriate compat_ +type that corresponds to the type in struct xyzzy_args. The +compat_sys_xyzzy() routine can then use this compat_ structure to parse the +arguments from a 32-bit invocation. + +For example, if there are fields: + + struct xyzzy_args { + const char __user *ptr; + __kernel_long_t varying_val; + u64 fixed_val; + /* ... */ + }; + +in struct xyzzy_args, then struct compat_xyzzy_args would have: + + struct compat_xyzzy_args { + compat_uptr_t ptr; + compat_long_t varying_val; + u64 fixed_val; + /* ... */ + }; + +The generic system call list also needs adjusting to allow for the compat +version; the entry in include/uapi/asm-generic/unistd.h should use +__SC_COMP rather than __SYSCALL: + + #define __NR_xyzzy 292 + __SC_COMP(__NR_xyzzy, sys_xyzzy, compat_sys_xyzzy) + +To summarize, you need: + + - a COMPAT_SYSCALL_DEFINEn(xyzzy, ...) for the compat entry point + - corresponding prototype in include/linux/compat.h + - (if needed) 32-bit mapping struct in include/linux/compat.h + - instance of __SC_COMP not __SYSCALL in include/uapi/asm-generic/unistd.h + + +Compatibility System Calls (x86) +-------------------------------- + +To wire up the x86 architecture of a system call with a compatibility version, +the entries in the syscall tables need to be adjusted. + +First, the entry in arch/x86/entry/syscalls/syscall_32.tbl gets an extra +column to indicate that a 32-bit userspace program running on a 64-bit kernel +should hit the compat entry point: + + 380 i386 xyzzy sys_xyzzy compat_sys_xyzzy + +Second, you need to figure out what should happen for the x32 ABI version of +the new system call. There's a choice here: the layout of the arguments +should either match the 64-bit version or the 32-bit version. + +If there's a pointer-to-a-pointer involved, the decision is easy: x32 is +ILP32, so the layout should match the 32-bit version, and the entry in +arch/x86/entry/syscalls/syscall_64.tbl is split so that x32 programs hit the +compatibility wrapper: + + 333 64 xyzzy sys_xyzzy + ... + 555 x32 xyzzy compat_sys_xyzzy + +If no pointers are involved, then it is preferable to re-use the 64-bit system +call for the x32 ABI (and consequently the entry in +arch/x86/entry/syscalls/syscall_64.tbl is unchanged). + +In either case, you should check that the types involved in your argument +layout do indeed map exactly from x32 (-mx32) to either the 32-bit (-m32) or +64-bit (-m64) equivalents. + + +System Calls Returning Elsewhere +-------------------------------- + +For most system calls, once the system call is complete the user program +continues exactly where it left off -- at the next instruction, with the +stack the same and most of the registers the same as before the system call, +and with the same virtual memory space. + +However, a few system calls do things differently. They might return to a +different location (rt_sigreturn) or change the memory space (fork/vfork/clone) +or even architecture (execve/execveat) of the program. + +To allow for this, the kernel implementation of the system call may need to +save and restore additional registers to the kernel stack, allowing complete +control of where and how execution continues after the system call. + +This is arch-specific, but typically involves defining assembly entry points +that save/restore additional registers and invoke the real system call entry +point. + +For x86_64, this is implemented as a stub_xyzzy entry point in +arch/x86/entry/entry_64.S, and the entry in the syscall table +(arch/x86/entry/syscalls/syscall_64.tbl) is adjusted to match: + + 333 common xyzzy stub_xyzzy + +The equivalent for 32-bit programs running on a 64-bit kernel is normally +called stub32_xyzzy and implemented in arch/x86/entry/entry_64_compat.S, +with the corresponding syscall table adjustment in +arch/x86/entry/syscalls/syscall_32.tbl: + + 380 i386 xyzzy sys_xyzzy stub32_xyzzy + +If the system call needs a compatibility layer (as in the previous section) +then the stub32_ version needs to call on to the compat_sys_ version of the +system call rather than the native 64-bit version. Also, if the x32 ABI +implementation is not common with the x86_64 version, then its syscall +table will also need to invoke a stub that calls on to the compat_sys_ +version. + +For completeness, it's also nice to set up a mapping so that user-mode Linux +still works -- its syscall table will reference stub_xyzzy, but the UML build +doesn't include arch/x86/entry/entry_64.S implementation (because UML +simulates registers etc). Fixing this is as simple as adding a #define to +arch/x86/um/sys_call_table_64.c: + + #define stub_xyzzy sys_xyzzy + + +Other Details +------------- + +Most of the kernel treats system calls in a generic way, but there is the +occasional exception that may need updating for your particular system call. + +The audit subsystem is one such special case; it includes (arch-specific) +functions that classify some special types of system call -- specifically +file open (open/openat), program execution (execve/exeveat) or socket +multiplexor (socketcall) operations. If your new system call is analogous to +one of these, then the audit system should be updated. + +More generally, if there is an existing system call that is analogous to your +new system call, it's worth doing a kernel-wide grep for the existing system +call to check there are no other special cases. + + +Testing +------- + +A new system call should obviously be tested; it is also useful to provide +reviewers with a demonstration of how user space programs will use the system +call. A good way to combine these aims is to include a simple self-test +program in a new directory under tools/testing/selftests/. + +For a new system call, there will obviously be no libc wrapper function and so +the test will need to invoke it using syscall(); also, if the system call +involves a new userspace-visible structure, the corresponding header will need +to be installed to compile the test. + +Make sure the selftest runs successfully on all supported architectures. For +example, check that it works when compiled as an x86_64 (-m64), x86_32 (-m32) +and x32 (-mx32) ABI program. + +For more extensive and thorough testing of new functionality, you should also +consider adding tests to the Linux Test Project, or to the xfstests project +for filesystem-related changes. + - https://linux-test-project.github.io/ + - git://git.kernel.org/pub/scm/fs/xfs/xfstests-dev.git + + +Man Page +-------- + +All new system calls should come with a complete man page, ideally using groff +markup, but plain text will do. If groff is used, it's helpful to include a +pre-rendered ASCII version of the man page in the cover email for the +patchset, for the convenience of reviewers. + +The man page should be cc'ed to linux-man@vger.kernel.org +For more details, see https://www.kernel.org/doc/man-pages/patches.html + +References and Sources +---------------------- + + - LWN article from Michael Kerrisk on use of flags argument in system calls: + https://lwn.net/Articles/585415/ + - LWN article from Michael Kerrisk on how to handle unknown flags in a system + call: https://lwn.net/Articles/588444/ + - LWN article from Jake Edge describing constraints on 64-bit system call + arguments: https://lwn.net/Articles/311630/ + - Pair of LWN articles from David Drysdale that describe the system call + implementation paths in detail for v3.14: + - https://lwn.net/Articles/604287/ + - https://lwn.net/Articles/604515/ + - Architecture-specific requirements for system calls are discussed in the + syscall(2) man-page: + http://man7.org/linux/man-pages/man2/syscall.2.html#NOTES + - Collated emails from Linus Torvalds discussing the problems with ioctl(): + http://yarchive.net/comp/linux/ioctl.html + - "How to not invent kernel interfaces", Arnd Bergmann, + http://www.ukuug.org/events/linux2007/2007/papers/Bergmann.pdf + - LWN article from Michael Kerrisk on avoiding new uses of CAP_SYS_ADMIN: + https://lwn.net/Articles/486306/ + - Recommendation from Andrew Morton that all related information for a new + system call should come in the same email thread: + https://lkml.org/lkml/2014/7/24/641 + - Recommendation from Michael Kerrisk that a new system call should come with + a man page: https://lkml.org/lkml/2014/6/13/309 + - Suggestion from Thomas Gleixner that x86 wire-up should be in a separate + commit: https://lkml.org/lkml/2014/11/19/254 + - Suggestion from Greg Kroah-Hartman that it's good for new system calls to + come with a man-page & selftest: https://lkml.org/lkml/2014/3/19/710 + - Discussion from Michael Kerrisk of new system call vs. prctl(2) extension: + https://lkml.org/lkml/2014/6/3/411 + - Suggestion from Ingo Molnar that system calls that involve multiple + arguments should encapsulate those arguments in a struct, which includes a + size field for future extensibility: https://lkml.org/lkml/2015/7/30/117 + - Numbering oddities arising from (re-)use of O_* numbering space flags: + - commit 75069f2b5bfb ("vfs: renumber FMODE_NONOTIFY and add to uniqueness + check") + - commit 12ed2e36c98a ("fanotify: FMODE_NONOTIFY and __O_SYNC in sparc + conflict") + - commit bb458c644a59 ("Safer ABI for O_TMPFILE") + - Discussion from Matthew Wilcox about restrictions on 64-bit arguments: + https://lkml.org/lkml/2008/12/12/187 + - Recommendation from Greg Kroah-Hartman that unknown flags should be + policed: https://lkml.org/lkml/2014/7/17/577 + - Recommendation from Linus Torvalds that x32 system calls should prefer + compatibility with 64-bit versions rather than 32-bit versions: + https://lkml.org/lkml/2011/8/31/244 -- cgit v1.1 From 7bbac697e4a6e64cc4bae26d57310c916aa0da7a Mon Sep 17 00:00:00 2001 From: Leo Yan Date: Mon, 3 Aug 2015 09:30:25 +0800 Subject: Documentation: minor typo fix in mailbox.txt Fix minor typo so that can pass correct pointer variable for container_of(). Signed-off-by: Leo Yan [jc: tweaked formatting] Signed-off-by: Jonathan Corbet --- Documentation/mailbox.txt | 6 ++---- 1 file changed, 2 insertions(+), 4 deletions(-) diff --git a/Documentation/mailbox.txt b/Documentation/mailbox.txt index 1092ad9..7ed371c 100644 --- a/Documentation/mailbox.txt +++ b/Documentation/mailbox.txt @@ -51,8 +51,7 @@ struct demo_client { */ static void message_from_remote(struct mbox_client *cl, void *mssg) { - struct demo_client *dc = container_of(mbox_client, - struct demo_client, cl); + struct demo_client *dc = container_of(cl, struct demo_client, cl); if (dc->async) { if (is_an_ack(mssg)) { /* An ACK to our last sample sent */ @@ -68,8 +67,7 @@ static void message_from_remote(struct mbox_client *cl, void *mssg) static void sample_sent(struct mbox_client *cl, void *mssg, int r) { - struct demo_client *dc = container_of(mbox_client, - struct demo_client, cl); + struct demo_client *dc = container_of(cl, struct demo_client, cl); complete(&dc->c); } -- cgit v1.1 From 9ed71e7ad95eb9885420e8d33f33bd4d49e1b775 Mon Sep 17 00:00:00 2001 From: Ben Hutchings Date: Thu, 6 Aug 2015 23:36:52 +0100 Subject: DocBook: Fix non-determinstic installation of duplicate man pages Some kernel-doc sections are included in multiple DocBook files. This means the mandocs target will generate the same manual page multiple times with different metadata (author name/address and manual title, taken from the including DocBook file). If it's invoked in a parallel build, the output is non-determinstic. Build the manual pages in a separate subdirectory per DocBook file, then sort and de-duplicate when installing them (which is serialised). Signed-off-by: Ben Hutchings [jc: fixed conflicts with the docs tree] Signed-off-by: Jonathan Corbet --- Documentation/DocBook/Makefile | 8 +++++--- 1 file changed, 5 insertions(+), 3 deletions(-) diff --git a/Documentation/DocBook/Makefile b/Documentation/DocBook/Makefile index b7d2110..5e97021 100644 --- a/Documentation/DocBook/Makefile +++ b/Documentation/DocBook/Makefile @@ -60,7 +60,9 @@ mandocs: $(MAN) installmandocs: mandocs mkdir -p /usr/local/man/man9/ - install -m 644 $(obj)/man/*.9.gz /usr/local/man/man9/ + find $(obj)/man -name '*.9.gz' -printf '%h %f\n' | \ + sort -k 2 -k 1 | uniq -f 1 | sed -e 's: :/:' | \ + xargs install -m 644 -t /usr/local/man/man9/ ### #External programs used @@ -150,12 +152,12 @@ quiet_cmd_db2html = HTML $@ cp $(PNG-$(basename $(notdir $@))) $(patsubst %.html,%,$@); fi quiet_cmd_db2man = MAN $@ - cmd_db2man = if grep -q refentry $<; then xmlto man $(XMLTOFLAGS) -o $(obj)/man $< ; fi + cmd_db2man = if grep -q refentry $<; then xmlto man $(XMLTOFLAGS) -o $(obj)/man/$(*F) $< ; fi %.9 : %.xml @(which xmlto > /dev/null 2>&1) || \ (echo "*** You need to install xmlto ***"; \ exit 1) - $(Q)mkdir -p $(obj)/man + $(Q)mkdir -p $(obj)/man/$(*F) $(call cmd,db2man) @touch $@ -- cgit v1.1 From 5699f871d2d51ce40012501378670613d4d49214 Mon Sep 17 00:00:00 2001 From: Danilo Cesar Lemes de Paula Date: Tue, 28 Jul 2015 16:45:15 -0300 Subject: scripts/kernel-doc: Adding cross-reference links to html documentation. Functions, Structs and Parameters definitions on kernel documentation are pure cosmetic, it only highlights the element. To ease the navigation in the documentation we should use inside those tags so readers can easily jump between methods directly. This was discussed in 2014[1] and is implemented by getting a list of from the DocBook XML to generate a database. Then it looks for , and tags that matches the ones in the database. As it only links existent references, no broken links are added. [1] - lists.freedesktop.org/archives/dri-devel/2014-August/065404.html Signed-off-by: Danilo Cesar Lemes de Paula Cc: Randy Dunlap Cc: Daniel Vetter Cc: Laurent Pinchart Cc: Herbert Xu Cc: Stephan Mueller Cc: Michal Marek Cc: intel-gfx Cc: dri-devel Signed-off-by: Jonathan Corbet --- Documentation/DocBook/Makefile | 43 ++++++--- scripts/kernel-doc-xml-ref | 198 +++++++++++++++++++++++++++++++++++++++++ 2 files changed, 228 insertions(+), 13 deletions(-) create mode 100755 scripts/kernel-doc-xml-ref diff --git a/Documentation/DocBook/Makefile b/Documentation/DocBook/Makefile index 5e97021..b1d6c95 100644 --- a/Documentation/DocBook/Makefile +++ b/Documentation/DocBook/Makefile @@ -66,8 +66,9 @@ installmandocs: mandocs ### #External programs used -KERNELDOC = $(srctree)/scripts/kernel-doc -DOCPROC = $(objtree)/scripts/docproc +KERNELDOCXMLREF = $(srctree)/scripts/kernel-doc-xml-ref +KERNELDOC = $(srctree)/scripts/kernel-doc +DOCPROC = $(objtree)/scripts/docproc XMLTOFLAGS = -m $(srctree)/$(src)/stylesheet.xsl XMLTOFLAGS += --skip-validation @@ -91,7 +92,7 @@ define rule_docproc ) > $(dir $@).$(notdir $@).cmd endef -%.xml: %.tmpl $(KERNELDOC) $(DOCPROC) FORCE +%.xml: %.tmpl $(KERNELDOC) $(DOCPROC) $(KERNELDOCXMLREF) FORCE $(call if_changed_rule,docproc) # Tell kbuild to always build the programs @@ -142,7 +143,20 @@ quiet_cmd_db2html = HTML $@ echo ' \ $(patsubst %.html,%,$(notdir $@))

' > $@ -%.html: %.xml +### +# Rules to create an aux XML and .db, and use them to re-process the DocBook XML +# to fill internal hyperlinks + gen_aux_xml = : + quiet_gen_aux_xml = echo ' XMLREF $@' +silent_gen_aux_xml = : +%.aux.xml: %.xml + @$($(quiet)gen_aux_xml) + @rm -rf $@ + @(cat $< | egrep "^ $<.db) + @$(KERNELDOCXMLREF) -db $<.db $< > $@ +.PRECIOUS: %.aux.xml + +%.html: %.aux.xml @(which xmlto > /dev/null 2>&1) || \ (echo "*** You need to install xmlto ***"; \ exit 1) @@ -211,15 +225,18 @@ dochelp: ### # Temporary files left by various tools clean-files := $(DOCBOOKS) \ - $(patsubst %.xml, %.dvi, $(DOCBOOKS)) \ - $(patsubst %.xml, %.aux, $(DOCBOOKS)) \ - $(patsubst %.xml, %.tex, $(DOCBOOKS)) \ - $(patsubst %.xml, %.log, $(DOCBOOKS)) \ - $(patsubst %.xml, %.out, $(DOCBOOKS)) \ - $(patsubst %.xml, %.ps, $(DOCBOOKS)) \ - $(patsubst %.xml, %.pdf, $(DOCBOOKS)) \ - $(patsubst %.xml, %.html, $(DOCBOOKS)) \ - $(patsubst %.xml, %.9, $(DOCBOOKS)) \ + $(patsubst %.xml, %.dvi, $(DOCBOOKS)) \ + $(patsubst %.xml, %.aux, $(DOCBOOKS)) \ + $(patsubst %.xml, %.tex, $(DOCBOOKS)) \ + $(patsubst %.xml, %.log, $(DOCBOOKS)) \ + $(patsubst %.xml, %.out, $(DOCBOOKS)) \ + $(patsubst %.xml, %.ps, $(DOCBOOKS)) \ + $(patsubst %.xml, %.pdf, $(DOCBOOKS)) \ + $(patsubst %.xml, %.html, $(DOCBOOKS)) \ + $(patsubst %.xml, %.9, $(DOCBOOKS)) \ + $(patsubst %.xml, %.aux.xml, $(DOCBOOKS)) \ + $(patsubst %.xml, %.xml.db, $(DOCBOOKS)) \ + $(patsubst %.xml, %.xml, $(DOCBOOKS)) \ $(index) clean-dirs := $(patsubst %.xml,%,$(DOCBOOKS)) man diff --git a/scripts/kernel-doc-xml-ref b/scripts/kernel-doc-xml-ref new file mode 100755 index 0000000..104a5a5 --- /dev/null +++ b/scripts/kernel-doc-xml-ref @@ -0,0 +1,198 @@ +#!/usr/bin/perl -w + +use strict; + +## Copyright (C) 2015 Intel Corporation ## +# ## +## This software falls under the GNU General Public License. ## +## Please read the COPYING file for more information ## +# +# +# This software reads a XML file and a list of valid interal +# references to replace Docbook tags with links. +# +# The list of "valid internal references" must be one-per-line in the following format: +# API-struct-foo +# API-enum-bar +# API-my-function +# +# The software walks over the XML file looking for xml tags representing possible references +# to the Document. Each reference will be cross checked against the "Valid Internal Reference" list. If +# the referece is found it replaces its content by a tag. +# +# usage: +# kernel-doc-xml-ref -db filename +# xml filename > outputfile + +# read arguments +if ($#ARGV != 2) { + usage(); +} + +#Holds the database filename +my $databasefile; +my @database; + +#holds the inputfile +my $inputfile; +my $errors = 0; + +my %highlights = ( + "(.*?)", + "\"\" . convert_function(\$1, \$line) . \"\"", + "(.*?)", + "\"\" . convert_struct(\$1) . \"\"", + "(.*?)(.*?)", + "\"\" . convert_param(\$1) . \"\$2\"", + "(.*?)(.*?)", + "\"\" . convert_param(\$1) . \"\$2\""); + +while($ARGV[0] =~ m/^-(.*)/) { + my $cmd = shift @ARGV; + if ($cmd eq "-db") { + $databasefile = shift @ARGV + } else { + usage(); + } +} +$inputfile = shift @ARGV; + +sub open_database { + open (my $handle, '<', $databasefile) or die "Cannot open $databasefile"; + chomp(my @lines = <$handle>); + close $handle; + + @database = @lines; +} + +sub process_file { + open_database(); + + my $dohighlight; + foreach my $pattern (keys %highlights) { + $dohighlight .= "\$line =~ s:$pattern:$highlights{$pattern}:eg;\n"; + } + + open(FILE, $inputfile) or die("Could not open $inputfile") or die ("Cannot open $inputfile"); + foreach my $line () { + eval $dohighlight; + print $line; + } +} + +sub trim($_) +{ + my $str = $_[0]; + $str =~ s/^\s+|\s+$//g; + return $str +} + +sub has_key_defined($_) +{ + if ( grep( /^$_[0]$/, @database)) { + return 1; + } + return 0; +} + +# Gets a content and add it a hyperlink if possible. +sub convert_function($_) +{ + my $arg = $_[0]; + my $key = $_[0]; + + my $line = $_[1]; + + $key = trim($key); + + $key =~ s/[^A-Za-z0-9]/-/g; + $key = "API-" . $key; + + # We shouldn't add links to prototype + if (!has_key_defined($key) || $line =~ m/\s+$head$tail"; +} + +# Converting a struct text to link +sub convert_struct($_) +{ + my $arg = $_[0]; + my $key = $_[0]; + $key =~ s/(struct )?(\w)/$2/g; + $key =~ s/[^A-Za-z0-9]/-/g; + $key = "API-struct-" . $key; + + if (!has_key_defined($key)) { + return $arg; + } + + my ($head, $tail) = split_pointer($arg); + return "$head$tail"; +} + +# Identify "object *" elements +sub split_pointer($_) +{ + my $arg = $_[0]; + if ($arg =~ /(.*?)( ?\* ?)/) { + return ($1, $2); + } + return ($arg, ""); +} + +sub convert_param($_) +{ + my $type = $_[0]; + my $keyname = convert_key_name($type); + + if (!has_key_defined($keyname)) { + return $type; + } + + my ($head, $tail) = split_pointer($type); + return "$head$tail"; + +} + +# DocBook links are in the API-- format +# This method gets an element and returns a valid DocBook reference for it. +sub convert_key_name($_) +{ + #Pattern $2 is optional and might be uninitialized + no warnings 'uninitialized'; + + my $str = $_[0]; + $str =~ s/(const|static)? ?(struct)? ?([a-zA-Z0-9_]+) ?(\*|&)?/$2 $3/g ; + + # trim + $str =~ s/^\s+|\s+$//g; + + # spaces and _ to - + $str =~ s/[^A-Za-z0-9]/-/g; + + return "API-" . $str; +} + +sub usage { + print "Usage: $0 -db database filename\n"; + print " xml source file(s) > outputfile\n"; + exit 1; +} + +# starting point +process_file(); + +if ($errors) { + print STDERR "$errors errors\n"; +} + +exit($errors); -- cgit v1.1 From f007492964c125cb3e88a51ba2e50c3b44d33ae0 Mon Sep 17 00:00:00 2001 From: Jonathan Corbet Date: Sun, 23 Aug 2015 13:35:23 -0600 Subject: kernel-doc: ignore unneeded attribute information The kernel-doc script gets confused by __attribute__(()) strings in structures, so just clean the out. Also ignore the CRYPTO_MINALIGN_ATTR macro used in the crypto subsystem. Signed-off-by: Jonathan Corbet --- scripts/kernel-doc | 2 ++ 1 file changed, 2 insertions(+) diff --git a/scripts/kernel-doc b/scripts/kernel-doc index 3a4d895..a7bf5f6 100755 --- a/scripts/kernel-doc +++ b/scripts/kernel-doc @@ -1799,7 +1799,9 @@ sub dump_struct($$) { # strip kmemcheck_bitfield_{begin,end}.*; $members =~ s/kmemcheck_bitfield_.*?;//gos; # strip attributes + $members =~ s/__attribute__\s*\(\([a-z,_\*\s\(\)]*\)\)//i; $members =~ s/__aligned\s*\([^;]*\)//gos; + $members =~ s/\s*CRYPTO_MINALIGN_ATTR//gos; create_parameterlist($members, ';', $file); check_sections($file, $declaration_name, "struct", $sectcheck, $struct_actual, $nested); -- cgit v1.1 From e4144fe5d47c91c92d36cdbd5f31ed8d6e3a57ab Mon Sep 17 00:00:00 2001 From: Mario Carrillo Date: Mon, 24 Aug 2015 09:33:09 -0500 Subject: docs: update HOWTO for 3.x -> 4.x versioning The HOWTO document needed updating for the new kernel versioning. Signed-off-by: Mario Carrillo Signed-off-by: Jonathan Corbet --- Documentation/HOWTO | 28 ++++++++++++++-------------- 1 file changed, 14 insertions(+), 14 deletions(-) diff --git a/Documentation/HOWTO b/Documentation/HOWTO index 93aa860..21152d3 100644 --- a/Documentation/HOWTO +++ b/Documentation/HOWTO @@ -218,16 +218,16 @@ The development process Linux kernel development process currently consists of a few different main kernel "branches" and lots of different subsystem-specific kernel branches. These different branches are: - - main 3.x kernel tree - - 3.x.y -stable kernel tree - - 3.x -git kernel patches + - main 4.x kernel tree + - 4.x.y -stable kernel tree + - 4.x -git kernel patches - subsystem specific kernel trees and patches - - the 3.x -next kernel tree for integration tests + - the 4.x -next kernel tree for integration tests -3.x kernel tree +4.x kernel tree ----------------- -3.x kernels are maintained by Linus Torvalds, and can be found on -kernel.org in the pub/linux/kernel/v3.x/ directory. Its development +4.x kernels are maintained by Linus Torvalds, and can be found on +kernel.org in the pub/linux/kernel/v4.x/ directory. Its development process is as follows: - As soon as a new kernel is released a two weeks window is open, during this period of time maintainers can submit big diffs to @@ -262,20 +262,20 @@ mailing list about kernel releases: released according to perceived bug status, not according to a preconceived timeline." -3.x.y -stable kernel tree +4.x.y -stable kernel tree --------------------------- Kernels with 3-part versions are -stable kernels. They contain relatively small and critical fixes for security problems or significant -regressions discovered in a given 3.x kernel. +regressions discovered in a given 4.x kernel. This is the recommended branch for users who want the most recent stable kernel and are not interested in helping test development/experimental versions. -If no 3.x.y kernel is available, then the highest numbered 3.x +If no 4.x.y kernel is available, then the highest numbered 4.x kernel is the current stable kernel. -3.x.y are maintained by the "stable" team , and +4.x.y are maintained by the "stable" team , and are released as needs dictate. The normal release period is approximately two weeks, but it can be longer if there are no pressing problems. A security-related problem, instead, can cause a release to happen almost @@ -285,7 +285,7 @@ The file Documentation/stable_kernel_rules.txt in the kernel tree documents what kinds of changes are acceptable for the -stable tree, and how the release process works. -3.x -git patches +4.x -git patches ------------------ These are daily snapshots of Linus' kernel tree which are managed in a git repository (hence the name.) These patches are usually released @@ -317,9 +317,9 @@ revisions to it, and maintainers can mark patches as under review, accepted, or rejected. Most of these patchwork sites are listed at http://patchwork.kernel.org/. -3.x -next kernel tree for integration tests +4.x -next kernel tree for integration tests --------------------------------------------- -Before updates from subsystem trees are merged into the mainline 3.x +Before updates from subsystem trees are merged into the mainline 4.x tree, they need to be integration-tested. For this purpose, a special testing repository exists into which virtually all subsystem trees are pulled on an almost daily basis: -- cgit v1.1 From 61a88a76b43ce35254415821047aeefde3f656a9 Mon Sep 17 00:00:00 2001 From: Nan Xiao Date: Thu, 20 Aug 2015 18:17:10 +0800 Subject: Documentation/Intel-IOMMU.txt: Modify definition of DRHD Hi all, According to "Intel Virtualization Technology for Directed I/O" specification, DRHD stands for "DMA Remapping Hardware Unit Definition" , not "DMA Engine Reporting Structure". Signed-off-by: Nan Xiao --- Documentation/Intel-IOMMU.txt | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Documentation/Intel-IOMMU.txt b/Documentation/Intel-IOMMU.txt index cf9431d..7b57fc0 100644 --- a/Documentation/Intel-IOMMU.txt +++ b/Documentation/Intel-IOMMU.txt @@ -10,7 +10,7 @@ This guide gives a quick cheat sheet for some basic understanding. Some Keywords DMAR - DMA remapping -DRHD - DMA Engine Reporting Structure +DRHD - DMA Remapping Hardware Unit Definition RMRR - Reserved memory Region Reporting Structure ZLR - Zero length reads from PCI devices IOVA - IO Virtual address. -- cgit v1.1 From 0fe0965e63c80dbc4bb005253ecff3494cbefc04 Mon Sep 17 00:00:00 2001 From: Alexander Kuleshov Date: Fri, 21 Aug 2015 15:19:06 +0600 Subject: Documentation/x86: Rename IRQSTACKSIZE to IRQ_STACK_SIZE The IRQSTACKSIZE was renamed to the IRQ_STACK_SIZE in the (26f80bd6a9 x86-64: Convert irqstacks to per-cpu) commit, but it still named IRQSTACKSIZE in the documentation. This patch fixes this. Signed-off-by: Alexander Kuleshov Signed-off-by: Jonathan Corbet --- Documentation/x86/kernel-stacks | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Documentation/x86/kernel-stacks b/Documentation/x86/kernel-stacks index 0f3a6c2..9a0aa4d 100644 --- a/Documentation/x86/kernel-stacks +++ b/Documentation/x86/kernel-stacks @@ -16,7 +16,7 @@ associated with each CPU. These stacks are only used while the kernel is in control on that CPU; when a CPU returns to user space the specialized stacks contain no useful data. The main CPU stacks are: -* Interrupt stack. IRQSTACKSIZE +* Interrupt stack. IRQ_STACK_SIZE Used for external hardware interrupts. If this is the first external hardware interrupt (i.e. not a nested hardware interrupt) then the -- cgit v1.1 From ce14c5831364118324b10c0355dead062b9ddd40 Mon Sep 17 00:00:00 2001 From: Prarit Bhargava Date: Tue, 25 Aug 2015 13:34:53 -0400 Subject: Documentation, add kernel-parameters.txt entry for dis_ucode_ldr dis_ucode_ldr was introduced in 65cef13 ("x86, microcode: Add a disable chicken bit") and will disable microcode loading on x86. This kernel parameter is buried in the code and should be added to the Documentation. Signed-off-by: Prarit Bhargava Signed-off-by: Jonathan Corbet --- Documentation/kernel-parameters.txt | 2 ++ 1 file changed, 2 insertions(+) diff --git a/Documentation/kernel-parameters.txt b/Documentation/kernel-parameters.txt index 1d6f045..34f2afb 100644 --- a/Documentation/kernel-parameters.txt +++ b/Documentation/kernel-parameters.txt @@ -910,6 +910,8 @@ bytes respectively. Such letter suffixes can also be entirely omitted. Disable PIN 1 of APIC timer Can be useful to work around chipset bugs. + dis_ucode_ldr [X86] Disable the microcode loader. + dma_debug=off If the kernel is compiled with DMA_API_DEBUG support, this option disables the debugging code at boot. -- cgit v1.1