Merge tag 'docs-for-linus' of git://git.lwn.net/linux-2.6

Pull documentation updates from Jonathan Corbet: "There's been a fair amount going on in the docs tree this time around, including: - Support for reproducible document builds, from Ben Hutchings and company. - The ability to automatically generate cross-reference links within a single DocBook book and embedded descriptions for large structures. From Danilo Cesar Lemes de Paula. - A new document on how to add a system call from David Drysdale. - Chameleon bus documentation from Johannes Thumshirn. ...plus the usual collection of improvements, typo fixes, and more" * tag 'docs-for-linus' of git://git.lwn.net/linux-2.6: (39 commits) Documentation, add kernel-parameters.txt entry for dis_ucode_ldr Documentation/x86: Rename IRQSTACKSIZE to IRQ_STACK_SIZE Documentation/Intel-IOMMU.txt: Modify definition of DRHD docs: update HOWTO for 3.x -> 4.x versioning kernel-doc: ignore unneeded attribute information scripts/kernel-doc: Adding cross-reference links to html documentation. DocBook: Fix non-determinstic installation of duplicate man pages Documentation: minor typo fix in mailbox.txt Documentation: describe how to add a system call doc: Add more workqueue functions to the documentation ARM: keystone: add documentation for SoCs and EVMs scripts/kernel-doc Allow struct arguments documentation in struct body SubmittingPatches: remove stray quote character Revert "DocBook: Avoid building man pages repeatedly and inconsistently" Documentation: Minor changes to men-chameleon-bus.txt Doc: fix trivial typo in SubmittingPatches MAINTAINERS: Direct Documentation/DocBook/media properly Documentation: installed man pages don't need to be executable fix Evolution submenu name in email-clients.txt Documentation: Add MCB documentation ...

Linus Torvalds committed 11 years ago

Commit e2701602 parents 22629b6 ce14c5828 files · +1195 −76Browse files

Unified · Split

28 files

Documentation/CodingStyle +0 −2
Documentation/DocBook/Makefile +36 −17
Documentation/DocBook/device-drivers.tmpl +1 −0
Documentation/DocBook/stylesheet.xsl +1 −0
Documentation/HOWTO +14 −14
Documentation/Intel-IOMMU.txt +1 −1
Documentation/SubmittingPatches +6 −6
Documentation/adding-syscalls.txt +527 −0
Documentation/arm/Samsung/Bootloader-interface.txt +14 −1
Documentation/arm/keystone/Overview.txt +73 −0
Documentation/email-clients.txt +1 −1
Documentation/filesystems/btrfs.txt +8 −8
Documentation/filesystems/debugfs.txt +40 −0
Documentation/kernel-doc-nano-HOWTO.txt +1 −1
Documentation/kernel-parameters.txt +2 −0
Documentation/mailbox.txt +2 −4
Documentation/men-chameleon-bus.txt +163 −0
Documentation/networking/can.txt +2 −2
Documentation/powerpc/cxl.txt +1 −1
Documentation/powerpc/dscr.txt +3 −3
Documentation/powerpc/qe_firmware.txt +1 −1
Documentation/pps/pps.txt +1 −1
Documentation/sysctl/vm.txt +5 −5
Documentation/x86/kernel-stacks +1 −1
MAINTAINERS +2 −0
README +1 −1
scripts/kernel-doc +90 −6
scripts/kernel-doc-xml-ref +198 −0

Documentation/CodingStyle+0−2

@@ -929,13 +929,11 @@ The C Programming Language, Second Edition · 928 unmodified lines
929	929	by Brian W. Kernighan and Dennis M. Ritchie.
930	930	Prentice Hall, Inc., 1988.
931	931	ISBN 0-13-110362-8 (paperback), 0-13-110370-9 (hardback).
932		−URL: http://cm.bell-labs.com/cm/cs/cbook/
933	932
934	933	The Practice of Programming
935	934	by Brian W. Kernighan and Rob Pike.
936	935	Addison-Wesley, Inc., 1999.
937	936	ISBN 0-201-61586-X.
938		−URL: http://cm.bell-labs.com/cm/cs/tpop/
939	937
940	938	GNU manuals - where in compliance with K&R and this text - for cpp, gcc,
941	939	gcc internals and indent, all available from http://www.gnu.org/manual/

Documentation/DocBook/Makefile+36−17

@@ -56,16 +56,19 @@ htmldocs: $(HTML) · 55 unmodified lines
56	56
57	57	MAN := $(patsubst %.xml, %.9, $(BOOKS))
58	58	mandocs: $(MAN)
59		− find $(obj)/man -name '*.9' \| xargs gzip -f
	59	+ find $(obj)/man -name '*.9' \| xargs gzip -nf
60	60
61	61	installmandocs: mandocs
62	62	mkdir -p /usr/local/man/man9/
63		− install $(obj)/man/*.9.gz /usr/local/man/man9/
	63	+ find $(obj)/man -name '*.9.gz' -printf '%h %f\n' \| \
	64	+ sort -k 2 -k 1 \| uniq -f 1 \| sed -e 's: :/:' \| \
	65	+ xargs install -m 644 -t /usr/local/man/man9/
64	66
65	67	###
66	68	#External programs used
67		−KERNELDOC = $(srctree)/scripts/kernel-doc
68		−DOCPROC = $(objtree)/scripts/docproc
	69	+KERNELDOCXMLREF = $(srctree)/scripts/kernel-doc-xml-ref
	70	+KERNELDOC = $(srctree)/scripts/kernel-doc
	71	+DOCPROC = $(objtree)/scripts/docproc
69	72
70	73	XMLTOFLAGS = -m $(srctree)/$(src)/stylesheet.xsl
71	74	XMLTOFLAGS += --skip-validation
@@ -89,7 +92,7 @@ define rule_docproc · 17 unmodified lines
89	92	) > $(dir $@).$(notdir $@).cmd
90	93	endef
91	94
92		−%.xml: %.tmpl $(KERNELDOC) $(DOCPROC) FORCE
	95	+%.xml: %.tmpl $(KERNELDOC) $(DOCPROC) $(KERNELDOCXMLREF) FORCE
93	96	$(call if_changed_rule,docproc)
94	97
95	98	# Tell kbuild to always build the programs
@@ -140,7 +143,20 @@ quiet_cmd_db2html = HTML $@ · 44 unmodified lines
140	143	echo '<a HREF="$(patsubst %.html,%,$(notdir $@))/index.html"> \
141	144	$(patsubst %.html,%,$(notdir $@))</a><p>' > $@
142	145
143		−%.html: %.xml
	146	+###
	147	+# Rules to create an aux XML and .db, and use them to re-process the DocBook XML
	148	+# to fill internal hyperlinks
	149	+ gen_aux_xml = :
	150	+ quiet_gen_aux_xml = echo ' XMLREF $@'
	151	+silent_gen_aux_xml = :
	152	+%.aux.xml: %.xml
	153	+ @$($(quiet)gen_aux_xml)
	154	+ @rm -rf $@
	155	+ @(cat $< \| egrep "^<refentry id" \| egrep -o "\".*\"" \| cut -f 2 -d \" > $<.db)
	156	+ @$(KERNELDOCXMLREF) -db $<.db $< > $@
	157	+.PRECIOUS: %.aux.xml
	158	+
	159	+%.html: %.aux.xml
144	160	@(which xmlto > /dev/null 2>&1) \|\| \
145	161	(echo "* You need to install xmlto *"; \
146	162	exit 1)
@@ -150,12 +166,12 @@ quiet_cmd_db2html = HTML $@ · 3 unmodified lines
150	166	cp $(PNG-$(basename $(notdir $@))) $(patsubst %.html,%,$@); fi
151	167
152	168	quiet_cmd_db2man = MAN $@
153		− cmd_db2man = if grep -q refentry $<; then xmlto man $(XMLTOFLAGS) -o $(obj)/man $< ; fi
	169	+ cmd_db2man = if grep -q refentry $<; then xmlto man $(XMLTOFLAGS) -o $(obj)/man/$(*F) $< ; fi
154	170	%.9 : %.xml
155	171	@(which xmlto > /dev/null 2>&1) \|\| \
156	172	(echo "* You need to install xmlto *"; \
157	173	exit 1)
158		− $(Q)mkdir -p $(obj)/man
	174	+ $(Q)mkdir -p $(obj)/man/$(*F)
159	175	$(call cmd,db2man)
160	176	@touch $@
161	177
@@ -209,15 +225,18 @@ dochelp: · 47 unmodified lines
209	225	###
210	226	# Temporary files left by various tools
211	227	clean-files := $(DOCBOOKS) \
212		− $(patsubst %.xml, %.dvi, $(DOCBOOKS)) \
213		− $(patsubst %.xml, %.aux, $(DOCBOOKS)) \
214		− $(patsubst %.xml, %.tex, $(DOCBOOKS)) \
215		− $(patsubst %.xml, %.log, $(DOCBOOKS)) \
216		− $(patsubst %.xml, %.out, $(DOCBOOKS)) \
217		− $(patsubst %.xml, %.ps, $(DOCBOOKS)) \
218		− $(patsubst %.xml, %.pdf, $(DOCBOOKS)) \
219		− $(patsubst %.xml, %.html, $(DOCBOOKS)) \
220		− $(patsubst %.xml, %.9, $(DOCBOOKS)) \
	228	+ $(patsubst %.xml, %.dvi, $(DOCBOOKS)) \
	229	+ $(patsubst %.xml, %.aux, $(DOCBOOKS)) \
	230	+ $(patsubst %.xml, %.tex, $(DOCBOOKS)) \
	231	+ $(patsubst %.xml, %.log, $(DOCBOOKS)) \
	232	+ $(patsubst %.xml, %.out, $(DOCBOOKS)) \
	233	+ $(patsubst %.xml, %.ps, $(DOCBOOKS)) \
	234	+ $(patsubst %.xml, %.pdf, $(DOCBOOKS)) \
	235	+ $(patsubst %.xml, %.html, $(DOCBOOKS)) \
	236	+ $(patsubst %.xml, %.9, $(DOCBOOKS)) \
	237	+ $(patsubst %.xml, %.aux.xml, $(DOCBOOKS)) \
	238	+ $(patsubst %.xml, %.xml.db, $(DOCBOOKS)) \
	239	+ $(patsubst %.xml, %.xml, $(DOCBOOKS)) \
221	240	$(index)
222	241
223	242	clean-dirs := $(patsubst %.xml,%,$(DOCBOOKS)) man

Documentation/DocBook/device-drivers.tmpl+1−0

@@ -66,6 +66,7 @@ · 65 unmodified lines
66	66	!Ekernel/time/hrtimer.c
67	67	</sect1>
68	68	<sect1><title>Workqueues and Kevents</title>
	69	+!Iinclude/linux/workqueue.h
69	70	!Ekernel/workqueue.c
70	71	</sect1>
71	72	<sect1><title>Internal Functions</title>

Documentation/DocBook/stylesheet.xsl+1−0

@@ -5,6 +5,7 @@ · 4 unmodified lines
5	5	<param name="funcsynopsis.tabular.threshold">80</param>
6	6	<param name="callout.graphics">0</param>
7	7	<!-- <param name="paper.type">A4</param> -->
	8	+<param name="generate.consistent.ids">1</param>
8	9	<param name="generate.section.toc.level">2</param>
9	10	<param name="use.id.as.filename">1</param>
10	11	</stylesheet>

Documentation/HOWTO+14−14

@@ -218,16 +218,16 @@ The development process · 217 unmodified lines
218	218	Linux kernel development process currently consists of a few different
219	219	main kernel "branches" and lots of different subsystem-specific kernel
220	220	branches. These different branches are:
221		− - main 3.x kernel tree
222		− - 3.x.y -stable kernel tree
223		− - 3.x -git kernel patches
	221	+ - main 4.x kernel tree
	222	+ - 4.x.y -stable kernel tree
	223	+ - 4.x -git kernel patches
224	224	- subsystem specific kernel trees and patches
225		− - the 3.x -next kernel tree for integration tests
	225	+ - the 4.x -next kernel tree for integration tests
226	226
227		−3.x kernel tree
	227	+4.x kernel tree
228	228	-----------------
229		−3.x kernels are maintained by Linus Torvalds, and can be found on
230		−kernel.org in the pub/linux/kernel/v3.x/ directory. Its development
	229	+4.x kernels are maintained by Linus Torvalds, and can be found on
	230	+kernel.org in the pub/linux/kernel/v4.x/ directory. Its development
231	231	process is as follows:
232	232	- As soon as a new kernel is released a two weeks window is open,
233	233	during this period of time maintainers can submit big diffs to
@@ -262,20 +262,20 @@ mailing list about kernel releases: · 28 unmodified lines
262	262	released according to perceived bug status, not according to a
263	263	preconceived timeline."
264	264
265		−3.x.y -stable kernel tree
	265	+4.x.y -stable kernel tree
266	266	---------------------------
267	267	Kernels with 3-part versions are -stable kernels. They contain
268	268	relatively small and critical fixes for security problems or significant
269		−regressions discovered in a given 3.x kernel.
	269	+regressions discovered in a given 4.x kernel.
270	270
271	271	This is the recommended branch for users who want the most recent stable
272	272	kernel and are not interested in helping test development/experimental
273	273	versions.
274	274
275		−If no 3.x.y kernel is available, then the highest numbered 3.x
	275	+If no 4.x.y kernel is available, then the highest numbered 4.x
276	276	kernel is the current stable kernel.
277	277
278		−3.x.y are maintained by the "stable" team <stable@vger.kernel.org>, and
	278	+4.x.y are maintained by the "stable" team <stable@vger.kernel.org>, and
279	279	are released as needs dictate. The normal release period is approximately
280	280	two weeks, but it can be longer if there are no pressing problems. A
281	281	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 · 3 unmodified lines
285	285	documents what kinds of changes are acceptable for the -stable tree, and
286	286	how the release process works.
287	287
288		−3.x -git patches
	288	+4.x -git patches
289	289	------------------
290	290	These are daily snapshots of Linus' kernel tree which are managed in a
291	291	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, · 25 unmodified lines
317	317	accepted, or rejected. Most of these patchwork sites are listed at
318	318	http://patchwork.kernel.org/.
319	319
320		−3.x -next kernel tree for integration tests
	320	+4.x -next kernel tree for integration tests
321	321	---------------------------------------------
322		−Before updates from subsystem trees are merged into the mainline 3.x
	322	+Before updates from subsystem trees are merged into the mainline 4.x
323	323	tree, they need to be integration-tested. For this purpose, a special
324	324	testing repository exists into which virtually all subsystem trees are
325	325	pulled on an almost daily basis:

Documentation/Intel-IOMMU.txt+1−1

@@ -10,7 +10,7 @@ This guide gives a quick cheat sheet for some basic understanding. · 9 unmodified lines
10	10	Some Keywords
11	11
12	12	DMAR - DMA remapping
13		−DRHD - DMA Engine Reporting Structure
	13	+DRHD - DMA Remapping Hardware Unit Definition
14	14	RMRR - Reserved memory Region Reporting Structure
15	15	ZLR - Zero length reads from PCI devices
16	16	IOVA - IO Virtual address.

Documentation/SubmittingPatches+6−6

@@ -90,11 +90,11 @@ patch. · 89 unmodified lines
90	90
91	91	Make sure your patch does not include any extra files which do not
92	92	belong in a patch submission. Make sure to review your patch -after-
93		−generated it with diff(1), to ensure accuracy.
	93	+generating it with diff(1), to ensure accuracy.
94	94
95	95	If your changes produce a lot of deltas, you need to split them into
96	96	individual patches which modify things in logical stages; see section
97		−#3. This will facilitate easier reviewing by other kernel developers,
	97	+#3. This will facilitate review by other kernel developers,
98	98	very important if you want your patch accepted.
99	99
100	100	If you're using git, "git rebase -i" can help you with this process. If
@@ -267,7 +267,7 @@ You should always copy the appropriate subsystem maintainer(s) on any patch · 166 unmodified lines
267	267	to code that they maintain; look through the MAINTAINERS file and the
268	268	source code revision history to see who those maintainers are. The
269	269	script scripts/get_maintainer.pl can be very useful at this step. If you
270		−cannot find a maintainer for the subsystem your are working on, Andrew
	270	+cannot find a maintainer for the subsystem you are working on, Andrew
271	271	Morton (akpm@linux-foundation.org) serves as a maintainer of last resort.
272	272
273	273	You should also normally choose at least one mailing list to receive a copy
@@ -340,7 +340,7 @@ on the changes you are submitting. It is important for a kernel · 66 unmodified lines
340	340	developer to be able to "quote" your changes, using standard e-mail
341	341	tools, so that they may comment on specific portions of your code.
342	342
343		−For this reason, all patches should be submitting e-mail "inline".
	343	+For this reason, all patches should be submitted by e-mail "inline".
344	344	WARNING: Be wary of your editor's word-wrap corrupting your patch,
345	345	if you choose to cut-n-paste your patch.
346	346
@@ -739,7 +739,7 @@ interest on a single line; it should look something like: · 392 unmodified lines
739	739
740	740	git://jdelvare.pck.nerim.net/jdelvare-2.6 i2c-for-linus
741	741
742		− to get these changes:"
	742	+ to get these changes:
743	743
744	744	A pull request should also include an overall message saying what will be
745	745	included in the request, a "git shortlog" listing of the patches
@@ -796,7 +796,7 @@ NO!!!! No more huge patch bombs to linux-kernel@vger.kernel.org people! · 50 unmodified lines
796	796	<https://lkml.org/lkml/2005/7/11/336>
797	797
798	798	Kernel Documentation/CodingStyle:
799		− <http://users.sosdg.org/~qiyong/lxr/source/Documentation/CodingStyle>
	799	+ <Documentation/CodingStyle>
800	800
801	801	Linus Torvalds's mail on the canonical patch format:
802	802	<http://lkml.org/lkml/2005/4/7/183>

Documentation/adding-syscalls.txt+527−0

@@ -0,0 +1,527 @@
	1	+Adding a New System Call
	2	+========================
	3	+
	4	+This document describes what's involved in adding a new system call to the
	5	+Linux kernel, over and above the normal submission advice in
	6	+Documentation/SubmittingPatches.
	7	+
	8	+
	9	+System Call Alternatives
	10	+------------------------
	11	+
	12	+The first thing to consider when adding a new system call is whether one of
	13	+the alternatives might be suitable instead. Although system calls are the
	14	+most traditional and most obvious interaction points between userspace and the
	15	+kernel, there are other possibilities -- choose what fits best for your
	16	+interface.
	17	+
	18	+ - If the operations involved can be made to look like a filesystem-like
	19	+ object, it may make more sense to create a new filesystem or device. This
	20	+ also makes it easier to encapsulate the new functionality in a kernel module
	21	+ rather than requiring it to be built into the main kernel.
	22	+ - If the new functionality involves operations where the kernel notifies
	23	+ userspace that something has happened, then returning a new file
	24	+ descriptor for the relevant object allows userspace to use
	25	+ poll/select/epoll to receive that notification.
	26	+ - However, operations that don't map to read(2)/write(2)-like operations
	27	+ have to be implemented as ioctl(2) requests, which can lead to a
	28	+ somewhat opaque API.
	29	+ - If you're just exposing runtime system information, a new node in sysfs
	30	+ (see Documentation/filesystems/sysfs.txt) or the /proc filesystem may be
	31	+ more appropriate. However, access to these mechanisms requires that the
	32	+ relevant filesystem is mounted, which might not always be the case (e.g.
	33	+ in a namespaced/sandboxed/chrooted environment). Avoid adding any API to
	34	+ debugfs, as this is not considered a 'production' interface to userspace.
	35	+ - If the operation is specific to a particular file or file descriptor, then
	36	+ an additional fcntl(2) command option may be more appropriate. However,
	37	+ fcntl(2) is a multiplexing system call that hides a lot of complexity, so
	38	+ this option is best for when the new function is closely analogous to
	39	+ existing fcntl(2) functionality, or the new functionality is very simple
	40	+ (for example, getting/setting a simple flag related to a file descriptor).
	41	+ - If the operation is specific to a particular task or process, then an
	42	+ additional prctl(2) command option may be more appropriate. As with
	43	+ fcntl(2), this system call is a complicated multiplexor so is best reserved
	44	+ for near-analogs of existing prctl() commands or getting/setting a simple
	45	+ flag related to a process.
	46	+
	47	+
	48	+Designing the API: Planning for Extension
	49	+-----------------------------------------
	50	+
	51	+A new system call forms part of the API of the kernel, and has to be supported
	52	+indefinitely. As such, it's a very good idea to explicitly discuss the
	53	+interface on the kernel mailing list, and it's important to plan for future
	54	+extensions of the interface.
	55	+
	56	+(The syscall table is littered with historical examples where this wasn't done,
	57	+together with the corresponding follow-up system calls -- eventfd/eventfd2,
	58	+dup2/dup3, inotify_init/inotify_init1, pipe/pipe2, renameat/renameat2 -- so
	59	+learn from the history of the kernel and plan for extensions from the start.)
	60	+
	61	+For simpler system calls that only take a couple of arguments, the preferred
	62	+way to allow for future extensibility is to include a flags argument to the
	63	+system call. To make sure that userspace programs can safely use flags
	64	+between kernel versions, check whether the flags value holds any unknown
	65	+flags, and reject the system call (with EINVAL) if it does:
	66	+
	67	+ if (flags & ~(THING_FLAG1 \| THING_FLAG2 \| THING_FLAG3))
	68	+ return -EINVAL;
	69	+
	70	+(If no flags values are used yet, check that the flags argument is zero.)
	71	+
	72	+For more sophisticated system calls that involve a larger number of arguments,
	73	+it's preferred to encapsulate the majority of the arguments into a structure
	74	+that is passed in by pointer. Such a structure can cope with future extension
	75	+by including a size argument in the structure:
	76	+
	77	+ struct xyzzy_params {
	78	+ u32 size; /* userspace sets p->size = sizeof(struct xyzzy_params) */
	79	+ u32 param_1;
	80	+ u64 param_2;
	81	+ u64 param_3;
	82	+ };
	83	+
	84	+As long as any subsequently added field, say param_4, is designed so that a
	85	+zero value gives the previous behaviour, then this allows both directions of
	86	+version mismatch:
	87	+
	88	+ - To cope with a later userspace program calling an older kernel, the kernel
	89	+ code should check that any memory beyond the size of the structure that it
	90	+ expects is zero (effectively checking that param_4 == 0).
	91	+ - To cope with an older userspace program calling a newer kernel, the kernel
	92	+ code can zero-extend a smaller instance of the structure (effectively
	93	+ setting param_4 = 0).
	94	+
	95	+See perf_event_open(2) and the perf_copy_attr() function (in
	96	+kernel/events/core.c) for an example of this approach.
	97	+
	98	+
	99	+Designing the API: Other Considerations
	100	+---------------------------------------
	101	+
	102	+If your new system call allows userspace to refer to a kernel object, it
	103	+should use a file descriptor as the handle for that object -- don't invent a
	104	+new type of userspace object handle when the kernel already has mechanisms and
	105	+well-defined semantics for using file descriptors.
	106	+
	107	+If your new xyzzy(2) system call does return a new file descriptor, then the
	108	+flags argument should include a value that is equivalent to setting O_CLOEXEC
	109	+on the new FD. This makes it possible for userspace to close the timing
	110	+window between xyzzy() and calling fcntl(fd, F_SETFD, FD_CLOEXEC), where an
	111	+unexpected fork() and execve() in another thread could leak a descriptor to
	112	+the exec'ed program. (However, resist the temptation to re-use the actual value
	113	+of the O_CLOEXEC constant, as it is architecture-specific and is part of a
	114	+numbering space of O_* flags that is fairly full.)
	115	+
	116	+If your system call returns a new file descriptor, you should also consider
	117	+what it means to use the poll(2) family of system calls on that file
	118	+descriptor. Making a file descriptor ready for reading or writing is the
	119	+normal way for the kernel to indicate to userspace that an event has
	120	+occurred on the corresponding kernel object.
	121	+
	122	+If your new xyzzy(2) system call involves a filename argument:
	123	+
	124	+ int sys_xyzzy(const char __user *path, ..., unsigned int flags);
	125	+
	126	+you should also consider whether an xyzzyat(2) version is more appropriate:
	127	+
	128	+ int sys_xyzzyat(int dfd, const char __user *path, ..., unsigned int flags);
	129	+
	130	+This allows more flexibility for how userspace specifies the file in question;
	131	+in particular it allows userspace to request the functionality for an
	132	+already-opened file descriptor using the AT_EMPTY_PATH flag, effectively giving
	133	+an fxyzzy(3) operation for free:
	134	+
	135	+ - xyzzyat(AT_FDCWD, path, ..., 0) is equivalent to xyzzy(path,...)
	136	+ - xyzzyat(fd, "", ..., AT_EMPTY_PATH) is equivalent to fxyzzy(fd, ...)
	137	+
	138	+(For more details on the rationale of the *at() calls, see the openat(2) man
	139	+page; for an example of AT_EMPTY_PATH, see the statat(2) man page.)
	140	+
	141	+If your new xyzzy(2) system call involves a parameter describing an offset
	142	+within a file, make its type loff_t so that 64-bit offsets can be supported
	143	+even on 32-bit architectures.
	144	+
	145	+If your new xyzzy(2) system call involves privileged functionality, it needs
	146	+to be governed by the appropriate Linux capability bit (checked with a call to
	147	+capable()), as described in the capabilities(7) man page. Choose an existing
	148	+capability bit that governs related functionality, but try to avoid combining
	149	+lots of only vaguely related functions together under the same bit, as this
	150	+goes against capabilities' purpose of splitting the power of root. In
	151	+particular, avoid adding new uses of the already overly-general CAP_SYS_ADMIN
	152	+capability.
	153	+
	154	+If your new xyzzy(2) system call manipulates a process other than the calling
	155	+process, it should be restricted (using a call to ptrace_may_access()) so that
	156	+only a calling process with the same permissions as the target process, or
	157	+with the necessary capabilities, can manipulate the target process.
	158	+
	159	+Finally, be aware that some non-x86 architectures have an easier time if
	160	+system call parameters that are explicitly 64-bit fall on odd-numbered
	161	+arguments (i.e. parameter 1, 3, 5), to allow use of contiguous pairs of 32-bit
	162	+registers. (This concern does not apply if the arguments are part of a
	163	+structure that's passed in by pointer.)
	164	+
	165	+
	166	+Proposing the API
	167	+-----------------
	168	+
	169	+To make new system calls easy to review, it's best to divide up the patchset
	170	+into separate chunks. These should include at least the following items as
	171	+distinct commits (each of which is described further below):
	172	+
	173	+ - The core implementation of the system call, together with prototypes,
	174	+ generic numbering, Kconfig changes and fallback stub implementation.
	175	+ - Wiring up of the new system call for one particular architecture, usually
	176	+ x86 (including all of x86_64, x86_32 and x32).
	177	+ - A demonstration of the use of the new system call in userspace via a
	178	+ selftest in tools/testing/selftests/.
	179	+ - A draft man-page for the new system call, either as plain text in the
	180	+ cover letter, or as a patch to the (separate) man-pages repository.
	181	+
	182	+New system call proposals, like any change to the kernel's API, should always
	183	+be cc'ed to linux-api@vger.kernel.org.
	184	+
	185	+
	186	+Generic System Call Implementation
	187	+----------------------------------
	188	+
	189	+The main entry point for your new xyzzy(2) system call will be called
	190	+sys_xyzzy(), but you add this entry point with the appropriate
	191	+SYSCALL_DEFINEn() macro rather than explicitly. The 'n' indicates the number
	192	+of arguments to the system call, and the macro takes the system call name
	193	+followed by the (type, name) pairs for the parameters as arguments. Using
	194	+this macro allows metadata about the new system call to be made available for
	195	+other tools.
	196	+
	197	+The new entry point also needs a corresponding function prototype, in
	198	+include/linux/syscalls.h, marked as asmlinkage to match the way that system
	199	+calls are invoked:
	200	+
	201	+ asmlinkage long sys_xyzzy(...);
	202	+
	203	+Some architectures (e.g. x86) have their own architecture-specific syscall
	204	+tables, but several other architectures share a generic syscall table. Add your
	205	+new system call to the generic list by adding an entry to the list in
	206	+include/uapi/asm-generic/unistd.h:
	207	+
	208	+ #define __NR_xyzzy 292
	209	+ __SYSCALL(__NR_xyzzy, sys_xyzzy)
	210	+
	211	+Also update the __NR_syscalls count to reflect the additional system call, and
	212	+note that if multiple new system calls are added in the same merge window,
	213	+your new syscall number may get adjusted to resolve conflicts.
	214	+
	215	+The file kernel/sys_ni.c provides a fallback stub implementation of each system
	216	+call, returning -ENOSYS. Add your new system call here too:
	217	+
	218	+ cond_syscall(sys_xyzzy);
	219	+
	220	+Your new kernel functionality, and the system call that controls it, should
	221	+normally be optional, so add a CONFIG option (typically to init/Kconfig) for
	222	+it. As usual for new CONFIG options:
	223	+
	224	+ - Include a description of the new functionality and system call controlled
	225	+ by the option.
	226	+ - Make the option depend on EXPERT if it should be hidden from normal users.
	227	+ - Make any new source files implementing the function dependent on the CONFIG
	228	+ option in the Makefile (e.g. "obj-$(CONFIG_XYZZY_SYSCALL) += xyzzy.c").
	229	+ - Double check that the kernel still builds with the new CONFIG option turned
	230	+ off.
	231	+
	232	+To summarize, you need a commit that includes:
	233	+
	234	+ - CONFIG option for the new function, normally in init/Kconfig
	235	+ - SYSCALL_DEFINEn(xyzzy, ...) for the entry point
	236	+ - corresponding prototype in include/linux/syscalls.h
	237	+ - generic table entry in include/uapi/asm-generic/unistd.h
	238	+ - fallback stub in kernel/sys_ni.c
	239	+
	240	+
	241	+x86 System Call Implementation
	242	+------------------------------
	243	+
	244	+To wire up your new system call for x86 platforms, you need to update the
	245	+master syscall tables. Assuming your new system call isn't special in some
	246	+way (see below), this involves a "common" entry (for x86_64 and x32) in
	247	+arch/x86/entry/syscalls/syscall_64.tbl:
	248	+
	249	+ 333 common xyzzy sys_xyzzy
	250	+
	251	+and an "i386" entry in arch/x86/entry/syscalls/syscall_32.tbl:
	252	+
	253	+ 380 i386 xyzzy sys_xyzzy
	254	+
	255	+Again, these numbers are liable to be changed if there are conflicts in the
	256	+relevant merge window.
	257	+
	258	+
	259	+Compatibility System Calls (Generic)
	260	+------------------------------------
	261	+
	262	+For most system calls the same 64-bit implementation can be invoked even when
	263	+the userspace program is itself 32-bit; even if the system call's parameters
	264	+include an explicit pointer, this is handled transparently.
	265	+
	266	+However, there are a couple of situations where a compatibility layer is
	267	+needed to cope with size differences between 32-bit and 64-bit.
	268	+
	269	+The first is if the 64-bit kernel also supports 32-bit userspace programs, and
	270	+so needs to parse areas of (__user) memory that could hold either 32-bit or
	271	+64-bit values. In particular, this is needed whenever a system call argument
	272	+is:
	273	+
	274	+ - a pointer to a pointer
	275	+ - a pointer to a struct containing a pointer (e.g. struct iovec __user *)
	276	+ - a pointer to a varying sized integral type (time_t, off_t, long, ...)
	277	+ - a pointer to a struct containing a varying sized integral type.
	278	+
	279	+The second situation that requires a compatibility layer is if one of the
	280	+system call's arguments has a type that is explicitly 64-bit even on a 32-bit
	281	+architecture, for example loff_t or __u64. In this case, a value that arrives
	282	+at a 64-bit kernel from a 32-bit application will be split into two 32-bit
	283	+values, which then need to be re-assembled in the compatibility layer.
	284	+
	285	+(Note that a system call argument that's a pointer to an explicit 64-bit type
	286	+does not need a compatibility layer; for example, splice(2)'s arguments of
	287	+type loff_t __user * do not trigger the need for a compat_ system call.)
	288	+
	289	+The compatibility version of the system call is called compat_sys_xyzzy(), and
	290	+is added with the COMPAT_SYSCALL_DEFINEn() macro, analogously to
	291	+SYSCALL_DEFINEn. This version of the implementation runs as part of a 64-bit
	292	+kernel, but expects to receive 32-bit parameter values and does whatever is
	293	+needed to deal with them. (Typically, the compat_sys_ version converts the
	294	+values to 64-bit versions and either calls on to the sys_ version, or both of
	295	+them call a common inner implementation function.)
	296	+
	297	+The compat entry point also needs a corresponding function prototype, in
	298	+include/linux/compat.h, marked as asmlinkage to match the way that system
	299	+calls are invoked:
	300	+
	301	+ asmlinkage long compat_sys_xyzzy(...);
	302	+
	303	+If the system call involves a structure that is laid out differently on 32-bit
	304	+and 64-bit systems, say struct xyzzy_args, then the include/linux/compat.h
	305	+header file should also include a compat version of the structure (struct
	306	+compat_xyzzy_args) where each variable-size field has the appropriate compat_
	307	+type that corresponds to the type in struct xyzzy_args. The
	308	+compat_sys_xyzzy() routine can then use this compat_ structure to parse the
	309	+arguments from a 32-bit invocation.
	310	+
	311	+For example, if there are fields:
	312	+
	313	+ struct xyzzy_args {
	314	+ const char __user *ptr;
	315	+ __kernel_long_t varying_val;
	316	+ u64 fixed_val;
	317	+ /* ... */
	318	+ };
	319	+
	320	+in struct xyzzy_args, then struct compat_xyzzy_args would have:
	321	+
	322	+ struct compat_xyzzy_args {
	323	+ compat_uptr_t ptr;
	324	+ compat_long_t varying_val;
	325	+ u64 fixed_val;
	326	+ /* ... */
	327	+ };
	328	+
	329	+The generic system call list also needs adjusting to allow for the compat
	330	+version; the entry in include/uapi/asm-generic/unistd.h should use
	331	+__SC_COMP rather than __SYSCALL:
	332	+
	333	+ #define __NR_xyzzy 292
	334	+ __SC_COMP(__NR_xyzzy, sys_xyzzy, compat_sys_xyzzy)
	335	+
	336	+To summarize, you need:
	337	+
	338	+ - a COMPAT_SYSCALL_DEFINEn(xyzzy, ...) for the compat entry point
	339	+ - corresponding prototype in include/linux/compat.h
	340	+ - (if needed) 32-bit mapping struct in include/linux/compat.h
	341	+ - instance of __SC_COMP not __SYSCALL in include/uapi/asm-generic/unistd.h
	342	+
	343	+
	344	+Compatibility System Calls (x86)
	345	+--------------------------------
	346	+
	347	+To wire up the x86 architecture of a system call with a compatibility version,
	348	+the entries in the syscall tables need to be adjusted.
	349	+
	350	+First, the entry in arch/x86/entry/syscalls/syscall_32.tbl gets an extra
	351	+column to indicate that a 32-bit userspace program running on a 64-bit kernel
	352	+should hit the compat entry point:
	353	+
	354	+ 380 i386 xyzzy sys_xyzzy compat_sys_xyzzy
	355	+
	356	+Second, you need to figure out what should happen for the x32 ABI version of
	357	+the new system call. There's a choice here: the layout of the arguments
	358	+should either match the 64-bit version or the 32-bit version.
	359	+
	360	+If there's a pointer-to-a-pointer involved, the decision is easy: x32 is
	361	+ILP32, so the layout should match the 32-bit version, and the entry in
	362	+arch/x86/entry/syscalls/syscall_64.tbl is split so that x32 programs hit the
	363	+compatibility wrapper:
	364	+
	365	+ 333 64 xyzzy sys_xyzzy
	366	+ ...
	367	+ 555 x32 xyzzy compat_sys_xyzzy
	368	+
	369	+If no pointers are involved, then it is preferable to re-use the 64-bit system
	370	+call for the x32 ABI (and consequently the entry in
	371	+arch/x86/entry/syscalls/syscall_64.tbl is unchanged).
	372	+
	373	+In either case, you should check that the types involved in your argument
	374	+layout do indeed map exactly from x32 (-mx32) to either the 32-bit (-m32) or
	375	+64-bit (-m64) equivalents.
	376	+
	377	+
	378	+System Calls Returning Elsewhere
	379	+--------------------------------
	380	+
	381	+For most system calls, once the system call is complete the user program
	382	+continues exactly where it left off -- at the next instruction, with the
	383	+stack the same and most of the registers the same as before the system call,
	384	+and with the same virtual memory space.
	385	+
	386	+However, a few system calls do things differently. They might return to a
	387	+different location (rt_sigreturn) or change the memory space (fork/vfork/clone)
	388	+or even architecture (execve/execveat) of the program.
	389	+
	390	+To allow for this, the kernel implementation of the system call may need to
	391	+save and restore additional registers to the kernel stack, allowing complete
	392	+control of where and how execution continues after the system call.
	393	+
	394	+This is arch-specific, but typically involves defining assembly entry points
	395	+that save/restore additional registers and invoke the real system call entry
	396	+point.
	397	+
	398	+For x86_64, this is implemented as a stub_xyzzy entry point in
	399	+arch/x86/entry/entry_64.S, and the entry in the syscall table
	400	+(arch/x86/entry/syscalls/syscall_64.tbl) is adjusted to match:
	401	+
	402	+ 333 common xyzzy stub_xyzzy
	403	+
	404	+The equivalent for 32-bit programs running on a 64-bit kernel is normally
	405	+called stub32_xyzzy and implemented in arch/x86/entry/entry_64_compat.S,
	406	+with the corresponding syscall table adjustment in
	407	+arch/x86/entry/syscalls/syscall_32.tbl:
	408	+
	409	+ 380 i386 xyzzy sys_xyzzy stub32_xyzzy
	410	+
	411	+If the system call needs a compatibility layer (as in the previous section)
	412	+then the stub32_ version needs to call on to the compat_sys_ version of the
	413	+system call rather than the native 64-bit version. Also, if the x32 ABI
	414	+implementation is not common with the x86_64 version, then its syscall
	415	+table will also need to invoke a stub that calls on to the compat_sys_
	416	+version.
	417	+
	418	+For completeness, it's also nice to set up a mapping so that user-mode Linux
	419	+still works -- its syscall table will reference stub_xyzzy, but the UML build
	420	+doesn't include arch/x86/entry/entry_64.S implementation (because UML
	421	+simulates registers etc). Fixing this is as simple as adding a #define to
	422	+arch/x86/um/sys_call_table_64.c:
	423	+
	424	+ #define stub_xyzzy sys_xyzzy
	425	+
	426	+
	427	+Other Details
	428	+-------------
	429	+
	430	+Most of the kernel treats system calls in a generic way, but there is the
	431	+occasional exception that may need updating for your particular system call.
	432	+
	433	+The audit subsystem is one such special case; it includes (arch-specific)
	434	+functions that classify some special types of system call -- specifically
	435	+file open (open/openat), program execution (execve/exeveat) or socket
	436	+multiplexor (socketcall) operations. If your new system call is analogous to
	437	+one of these, then the audit system should be updated.
	438	+
	439	+More generally, if there is an existing system call that is analogous to your
	440	+new system call, it's worth doing a kernel-wide grep for the existing system
	441	+call to check there are no other special cases.
	442	+
	443	+
	444	+Testing
	445	+-------
	446	+
	447	+A new system call should obviously be tested; it is also useful to provide
	448	+reviewers with a demonstration of how user space programs will use the system
	449	+call. A good way to combine these aims is to include a simple self-test
	450	+program in a new directory under tools/testing/selftests/.
	451	+
	452	+For a new system call, there will obviously be no libc wrapper function and so
	453	+the test will need to invoke it using syscall(); also, if the system call
	454	+involves a new userspace-visible structure, the corresponding header will need
	455	+to be installed to compile the test.
	456	+
	457	+Make sure the selftest runs successfully on all supported architectures. For
	458	+example, check that it works when compiled as an x86_64 (-m64), x86_32 (-m32)
	459	+and x32 (-mx32) ABI program.
	460	+
	461	+For more extensive and thorough testing of new functionality, you should also
	462	+consider adding tests to the Linux Test Project, or to the xfstests project
	463	+for filesystem-related changes.
	464	+ - https://linux-test-project.github.io/
	465	+ - git://git.kernel.org/pub/scm/fs/xfs/xfstests-dev.git
	466	+
	467	+
	468	+Man Page
	469	+--------
	470	+
	471	+All new system calls should come with a complete man page, ideally using groff
	472	+markup, but plain text will do. If groff is used, it's helpful to include a
	473	+pre-rendered ASCII version of the man page in the cover email for the
	474	+patchset, for the convenience of reviewers.
	475	+
	476	+The man page should be cc'ed to linux-man@vger.kernel.org
	477	+For more details, see https://www.kernel.org/doc/man-pages/patches.html
	478	+
	479	+References and Sources
	480	+----------------------
	481	+
	482	+ - LWN article from Michael Kerrisk on use of flags argument in system calls:
	483	+ https://lwn.net/Articles/585415/
	484	+ - LWN article from Michael Kerrisk on how to handle unknown flags in a system
	485	+ call: https://lwn.net/Articles/588444/
	486	+ - LWN article from Jake Edge describing constraints on 64-bit system call
	487	+ arguments: https://lwn.net/Articles/311630/
	488	+ - Pair of LWN articles from David Drysdale that describe the system call
	489	+ implementation paths in detail for v3.14:
	490	+ - https://lwn.net/Articles/604287/
	491	+ - https://lwn.net/Articles/604515/
	492	+ - Architecture-specific requirements for system calls are discussed in the
	493	+ syscall(2) man-page:
	494	+ http://man7.org/linux/man-pages/man2/syscall.2.html#NOTES
	495	+ - Collated emails from Linus Torvalds discussing the problems with ioctl():
	496	+ http://yarchive.net/comp/linux/ioctl.html
	497	+ - "How to not invent kernel interfaces", Arnd Bergmann,
	498	+ http://www.ukuug.org/events/linux2007/2007/papers/Bergmann.pdf
	499	+ - LWN article from Michael Kerrisk on avoiding new uses of CAP_SYS_ADMIN:
	500	+ https://lwn.net/Articles/486306/
	501	+ - Recommendation from Andrew Morton that all related information for a new
	502	+ system call should come in the same email thread:
	503	+ https://lkml.org/lkml/2014/7/24/641
	504	+ - Recommendation from Michael Kerrisk that a new system call should come with
	505	+ a man page: https://lkml.org/lkml/2014/6/13/309
	506	+ - Suggestion from Thomas Gleixner that x86 wire-up should be in a separate
	507	+ commit: https://lkml.org/lkml/2014/11/19/254
	508	+ - Suggestion from Greg Kroah-Hartman that it's good for new system calls to
	509	+ come with a man-page & selftest: https://lkml.org/lkml/2014/3/19/710
	510	+ - Discussion from Michael Kerrisk of new system call vs. prctl(2) extension:
	511	+ https://lkml.org/lkml/2014/6/3/411
	512	+ - Suggestion from Ingo Molnar that system calls that involve multiple
	513	+ arguments should encapsulate those arguments in a struct, which includes a
	514	+ size field for future extensibility: https://lkml.org/lkml/2015/7/30/117
	515	+ - Numbering oddities arising from (re-)use of O_* numbering space flags:
	516	+ - commit 75069f2b5bfb ("vfs: renumber FMODE_NONOTIFY and add to uniqueness
	517	+ check")
	518	+ - commit 12ed2e36c98a ("fanotify: FMODE_NONOTIFY and __O_SYNC in sparc
	519	+ conflict")
	520	+ - commit bb458c644a59 ("Safer ABI for O_TMPFILE")
	521	+ - Discussion from Matthew Wilcox about restrictions on 64-bit arguments:
	522	+ https://lkml.org/lkml/2008/12/12/187
	523	+ - Recommendation from Greg Kroah-Hartman that unknown flags should be
	524	+ policed: https://lkml.org/lkml/2014/7/17/577
	525	+ - Recommendation from Linus Torvalds that x32 system calls should prefer
	526	+ compatibility with 64-bit versions rather than 32-bit versions:
	527	+ https://lkml.org/lkml/2011/8/31/244

Documentation/arm/Samsung/Bootloader-interface.txt+14−1

@@ -15,6 +15,7 @@ executing kernel. · 14 unmodified lines
15	15
16	16
17	17	1. Non-Secure mode
	18	+
18	19	Address: sysram_ns_base_addr
19	20	Offset Value Purpose
20	21	=============================================================================
@@ -28,6 +29,7 @@ Offset Value Purpose · 7 unmodified lines
28	29
29	30
30	31	2. Secure mode
	32	+
31	33	Address: sysram_base_addr
32	34	Offset Value Purpose
33	35	=============================================================================
@@ -40,14 +42,25 @@ Offset Value Purpose · 6 unmodified lines
40	42	Address: pmu_base_addr
41	43	Offset Value Purpose
42	44	=============================================================================
43		−0x0800 exynos_cpu_resume AFTR
	45	+0x0800 exynos_cpu_resume AFTR, suspend
	46	+0x0800 mcpm_entry_point (Exynos542x with MCPM) AFTR, suspend
	47	+0x0804 0xfcba0d10 (Magic cookie) AFTR
	48	+0x0804 0x00000bad (Magic cookie) System suspend
44	49	0x0814 exynos4_secondary_startup (Exynos4210 r1.1) Secondary CPU boot
45	50	0x0818 0xfcba0d10 (Magic cookie, Exynos4210 r1.1) AFTR
46	51	0x081C exynos_cpu_resume (Exynos4210 r1.1) AFTR
47	52
48	53
49	54	3. Other (regardless of secure/non-secure mode)
	55	+
50	56	Address: pmu_base_addr
51	57	Offset Value Purpose
52	58	=============================================================================
53	59	0x0908 Non-zero (only Exynos3250) Secondary CPU boot up indicator
	60	+
	61	+
	62	+4. Glossary
	63	+
	64	+AFTR - ARM Off Top Running, a low power mode, Cortex cores and many other
	65	+modules are power gated, except the TOP modules
	66	+MCPM - Multi-Cluster Power Management

Documentation/arm/keystone/Overview.txt+73−0

@@ -0,0 +1,73 @@
	1	+ TI Keystone Linux Overview
	2	+ --------------------------
	3	+
	4	+Introduction
	5	+------------
	6	+Keystone range of SoCs are based on ARM Cortex-A15 MPCore Processors
	7	+and c66x DSP cores. This document describes essential information required
	8	+for users to run Linux on Keystone based EVMs from Texas Instruments.
	9	+
	10	+Following SoCs & EVMs are currently supported:-
	11	+
	12	+------------ K2HK SoC and EVM --------------------------------------------------
	13	+
	14	+a.k.a Keystone 2 Hawking/Kepler SoC
	15	+TCI6636K2H & TCI6636K2K: See documentation at
	16	+ http://www.ti.com/product/tci6638k2k
	17	+ http://www.ti.com/product/tci6638k2h
	18	+
	19	+EVM:
	20	+http://www.advantech.com/Support/TI-EVM/EVMK2HX_sd.aspx
	21	+
	22	+------------ K2E SoC and EVM ---------------------------------------------------
	23	+
	24	+a.k.a Keystone 2 Edison SoC
	25	+K2E - 66AK2E05: See documentation at
	26	+ http://www.ti.com/product/66AK2E05/technicaldocuments
	27	+
	28	+EVM:
	29	+https://www.einfochips.com/index.php/partnerships/texas-instruments/k2e-evm.html
	30	+
	31	+------------ K2L SoC and EVM ---------------------------------------------------
	32	+
	33	+a.k.a Keystone 2 Lamarr SoC
	34	+K2L - TCI6630K2L: See documentation at
	35	+ http://www.ti.com/product/TCI6630K2L/technicaldocuments
	36	+EVM:
	37	+https://www.einfochips.com/index.php/partnerships/texas-instruments/k2l-evm.html
	38	+
	39	+Configuration
	40	+-------------
	41	+
	42	+All of the K2 SoCs/EVMs share a common defconfig, keystone_defconfig and same
	43	+image is used to boot on individual EVMs. The platform configuration is
	44	+specified through DTS. Following are the DTS used:-
	45	+ K2HK EVM : k2hk-evm.dts
	46	+ K2E EVM : k2e-evm.dts
	47	+ K2L EVM : k2l-evm.dts
	48	+
	49	+The device tree documentation for the keystone machines are located at
	50	+ Documentation/devicetree/bindings/arm/keystone/keystone.txt
	51	+
	52	+Known issues & workaround
	53	+-------------------------
	54	+
	55	+Some of the device drivers used on keystone are re-used from that from
	56	+DaVinci and other TI SoCs. These device drivers may use clock APIs directly.
	57	+Some of the keystone specific drivers such as netcp uses run time power
	58	+management API instead to enable clock. As this API has limitations on
	59	+keystone, following workaround is needed to boot Linux.
	60	+
	61	+ Add 'clk_ignore_unused' to the bootargs env variable in u-boot. Otherwise
	62	+ clock frameworks will try to disable clocks that are unused and disable
	63	+ the hardware. This is because netcp related power domain and clock
	64	+ domains are enabled in u-boot as run time power management API currently
	65	+ doesn't enable clocks for netcp due to a limitation. This workaround is
	66	+ expected to be removed in the future when proper API support becomes
	67	+ available. Until then, this work around is needed.
	68	+
	69	+
	70	+Document Author
	71	+---------------
	72	+Murali Karicheri <m-karicheri2@ti.com>
	73	+Copyright 2015 Texas Instruments

Documentation/email-clients.txt+1−1

@@ -93,7 +93,7 @@ Evolution (GUI) · 92 unmodified lines
93	93	Some people use this successfully for patches.
94	94
95	95	When composing mail select: Preformat
96		− from Format->Heading->Preformatted (Ctrl-7)
	96	+ from Format->Paragraph Style->Preformatted (Ctrl-7)
97	97	or the toolbar
98	98
99	99	Then use:

Documentation/filesystems/btrfs.txt+8−8

@@ -61,7 +61,7 @@ Options with (*) are default options and will not show in the mount options. · 60 unmodified lines
61	61
62	62	check_int enables the integrity checker module, which examines all
63	63	block write requests to ensure on-disk consistency, at a large
64		− memory and CPU cost.
	64	+ memory and CPU cost.
65	65
66	66	check_int_data includes extent data in the integrity checks, and
67	67	implies the check_int option.
@@ -113,7 +113,7 @@ Options with (*) are default options and will not show in the mount options. · 45 unmodified lines
113	113	Disable/enable debugging option to be more verbose in some ENOSPC conditions.
114	114
115	115	fatal_errors=<action>
116		− Action to take when encountering a fatal error:
	116	+ Action to take when encountering a fatal error:
117	117	"bug" - BUG() on a fatal error. This is the default.
118	118	"panic" - panic() on a fatal error.
119	119
@@ -132,10 +132,10 @@ Options with (*) are default options and will not show in the mount options. · 12 unmodified lines
132	132
133	133	max_inline=<bytes>
134	134	Specify the maximum amount of space, in bytes, that can be inlined in
135		− a metadata B-tree leaf. The value is specified in bytes, optionally
	135	+ a metadata B-tree leaf. The value is specified in bytes, optionally
136	136	with a K, M, or G suffix, case insensitive. In practice, this value
137	137	is limited by the root sector size, with some space unavailable due
138		− to leaf headers. For a 4k sectorsize, max inline data is ~3900 bytes.
	138	+ to leaf headers. For a 4k sector size, max inline data is ~3900 bytes.
139	139
140	140	metadata_ratio=<value>
141	141	Specify that 1 metadata chunk should be allocated after every <value>
@@ -170,7 +170,7 @@ Options with (*) are default options and will not show in the mount options. · 28 unmodified lines
170	170
171	171	recovery
172	172	Enable autorecovery attempts if a bad tree root is found at mount time.
173		− Currently this scans a list of several previous tree roots and tries to
	173	+ Currently this scans a list of several previous tree roots and tries to
174	174	use the first readable.
175	175
176	176	rescan_uuid_tree
@@ -194,7 +194,7 @@ Options with (*) are default options and will not show in the mount options. · 17 unmodified lines
194	194	ssd_spread
195	195	Options to control ssd allocation schemes. By default, BTRFS will
196	196	enable or disable ssd allocation heuristics depending on whether a
197		− rotational or nonrotational disk is in use. The ssd and nossd options
	197	+ rotational or non-rotational disk is in use. The ssd and nossd options
198	198	can override this autodetection.
199	199
200	200	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. · 15 unmodified lines
216	216	This allows mounting of subvolumes which are not in the root of the mounted
217	217	filesystem.
218	218	You can use "btrfs subvolume show " to see the object ID for a subvolume.
219		−
	219	+
220	220	thread_pool=<number>
221	221	The number of worker threads to allocate. The default number is equal
222	222	to the number of CPUs + 2, or 8, whichever is smaller.
223	223
224	224	user_subvol_rm_allowed
225		− Allow subvolumes to be deleted by a non-root user. Use with caution.
	225	+ Allow subvolumes to be deleted by a non-root user. Use with caution.
226	226
227	227	MAILING LIST
228	228	============

Documentation/filesystems/debugfs.txt+40−0

@@ -51,6 +51,17 @@ operations should be provided; others can be included as needed. Again, · 50 unmodified lines
51	51	the return value will be a dentry pointer to the created file, NULL for
52	52	error, or ERR_PTR(-ENODEV) if debugfs support is missing.
53	53
	54	+Create a file with an initial size, the following function can be used
	55	+instead:
	56	+
	57	+ struct dentry debugfs_create_file_size(const char name, umode_t mode,
	58	+ struct dentry parent, void data,
	59	+ const struct file_operations *fops,
	60	+ loff_t file_size);
	61	+
	62	+file_size is the initial file size. The other parameters are the same
	63	+as the function debugfs_create_file.
	64	+
54	65	In a number of cases, the creation of a set of file operations is not
55	66	actually necessary; the debugfs code provides a number of helper functions
56	67	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 · 43 unmodified lines
100	111	N, followed by a newline. If written to, it will accept either upper- or
101	112	lower-case values, or 1 or 0. Any other input will be silently ignored.
102	113
	114	+Also, atomic_t values can be placed in debugfs with:
	115	+
	116	+ struct dentry debugfs_create_atomic_t(const char name, umode_t mode,
	117	+ struct dentry parent, atomic_t value)
	118	+
	119	+A read of this file will get atomic_t values, and a write of this file
	120	+will set atomic_t values.
	121	+
103	122	Another option is exporting a block of arbitrary binary data, with
104	123	this structure and function:
105	124
@@ -147,6 +166,27 @@ The "base" argument may be 0, but you may want to build the reg32 array · 41 unmodified lines
147	166	using __stringify, and a number of register names (macros) are actually
148	167	byte offsets over a base for the register block.
149	168
	169	+If you want to dump an u32 array in debugfs, you can create file with:
	170	+
	171	+ struct dentry debugfs_create_u32_array(const char name, umode_t mode,
	172	+ struct dentry *parent,
	173	+ u32 *array, u32 elements);
	174	+
	175	+The "array" argument provides data, and the "elements" argument is
	176	+the number of elements in the array. Note: Once array is created its
	177	+size can not be changed.
	178	+
	179	+There is a helper function to create device related seq_file:
	180	+
	181	+ struct dentry debugfs_create_devm_seqfile(struct device dev,
	182	+ const char *name,
	183	+ struct dentry *parent,
	184	+ int (read_fn)(struct seq_file s,
	185	+ void *data));
	186	+
	187	+The "dev" argument is the device related to this debugfs file, and
	188	+the "read_fn" is a function pointer which to be called to print the
	189	+seq_file content.
150	190
151	191	There are a couple of other directory-oriented helper functions:
152	192

Documentation/kernel-doc-nano-HOWTO.txt+1−1

@@ -128,7 +128,7 @@ are: · 127 unmodified lines
128	128	special place-holders for where the extracted documentation should
129	129	go.
130	130
131		−- scripts/basic/docproc.c
	131	+- scripts/docproc.c
132	132
133	133	This is a program for converting SGML template files into SGML
134	134	files. When a file is referenced it is searched for symbols

Documentation/kernel-parameters.txt+2−0

@@ -910,6 +910,8 @@ bytes respectively. Such letter suffixes can also be entirely omitted. · 909 unmodified lines
910	910	Disable PIN 1 of APIC timer
911	911	Can be useful to work around chipset bugs.
912	912
	913	+ dis_ucode_ldr [X86] Disable the microcode loader.
	914	+
913	915	dma_debug=off If the kernel is compiled with DMA_API_DEBUG support,
914	916	this option disables the debugging code at boot.
915	917

Documentation/mailbox.txt+2−4

@@ -51,8 +51,7 @@ struct demo_client { · 50 unmodified lines
51	51	*/
52	52	static void message_from_remote(struct mbox_client cl, void mssg)
53	53	{
54		− struct demo_client *dc = container_of(mbox_client,
55		− struct demo_client, cl);
	54	+ struct demo_client *dc = container_of(cl, struct demo_client, cl);
56	55	if (dc->async) {
57	56	if (is_an_ack(mssg)) {
58	57	/* An ACK to our last sample sent */
@@ -68,8 +67,7 @@ static void message_from_remote(struct mbox_client cl, void mssg) · 9 unmodified lines
68	67
69	68	static void sample_sent(struct mbox_client cl, void mssg, int r)
70	69	{
71		− struct demo_client *dc = container_of(mbox_client,
72		− struct demo_client, cl);
	70	+ struct demo_client *dc = container_of(cl, struct demo_client, cl);
73	71	complete(&dc->c);
74	72	}
75	73

Documentation/men-chameleon-bus.txt+163−0

@@ -0,0 +1,163 @@
	1	+ MEN Chameleon Bus
	2	+ =================
	3	+
	4	+Table of Contents
	5	+=================
	6	+1 Introduction
	7	+ 1.1 Scope of this Document
	8	+ 1.2 Limitations of the current implementation
	9	+2 Architecture
	10	+ 2.1 MEN Chameleon Bus
	11	+ 2.2 Carrier Devices
	12	+ 2.3 Parser
	13	+3 Resource handling
	14	+ 3.1 Memory Resources
	15	+ 3.2 IRQs
	16	+4 Writing an MCB driver
	17	+ 4.1 The driver structure
	18	+ 4.2 Probing and attaching
	19	+ 4.3 Initializing the driver
	20	+
	21	+
	22	+1 Introduction
	23	+===============
	24	+ This document describes the architecture and implementation of the MEN
	25	+ Chameleon Bus (called MCB throughout this document).
	26	+
	27	+1.1 Scope of this Document
	28	+---------------------------
	29	+ This document is intended to be a short overview of the current
	30	+ implementation and does by no means describe the complete possibilities of MCB
	31	+ based devices.
	32	+
	33	+1.2 Limitations of the current implementation
	34	+----------------------------------------------
	35	+ The current implementation is limited to PCI and PCIe based carrier devices
	36	+ that only use a single memory resource and share the PCI legacy IRQ. Not
	37	+ implemented are:
	38	+ - Multi-resource MCB devices like the VME Controller or M-Module carrier.
	39	+ - MCB devices that need another MCB device, like SRAM for a DMA Controller's
	40	+ buffer descriptors or a video controller's video memory.
	41	+ - A per-carrier IRQ domain for carrier devices that have one (or more) IRQs
	42	+ per MCB device like PCIe based carriers with MSI or MSI-X support.
	43	+
	44	+2 Architecture
	45	+===============
	46	+ MCB is divided into 3 functional blocks:
	47	+ - The MEN Chameleon Bus itself,
	48	+ - drivers for MCB Carrier Devices and
	49	+ - the parser for the Chameleon table.
	50	+
	51	+2.1 MEN Chameleon Bus
	52	+----------------------
	53	+ The MEN Chameleon Bus is an artificial bus system that attaches to a so
	54	+ called Chameleon FPGA device found on some hardware produced my MEN Mikro
	55	+ Elektronik GmbH. These devices are multi-function devices implemented in a
	56	+ single FPGA and usually attached via some sort of PCI or PCIe link. Each
	57	+ FPGA contains a header section describing the content of the FPGA. The
	58	+ header lists the device id, PCI BAR, offset from the beginning of the PCI
	59	+ BAR, size in the FPGA, interrupt number and some other properties currently
	60	+ not handled by the MCB implementation.
	61	+
	62	+2.2 Carrier Devices
	63	+--------------------
	64	+ A carrier device is just an abstraction for the real world physical bus the
	65	+ Chameleon FPGA is attached to. Some IP Core drivers may need to interact with
	66	+ properties of the carrier device (like querying the IRQ number of a PCI
	67	+ device). To provide abstraction from the real hardware bus, an MCB carrier
	68	+ device provides callback methods to translate the driver's MCB function calls
	69	+ to hardware related function calls. For example a carrier device may
	70	+ implement the get_irq() method which can be translated into a hardware bus
	71	+ query for the IRQ number the device should use.
	72	+
	73	+2.3 Parser
	74	+-----------
	75	+ The parser reads the first 512 bytes of a Chameleon device and parses the
	76	+ Chameleon table. Currently the parser only supports the Chameleon v2 variant
	77	+ of the Chameleon table but can easily be adopted to support an older or
	78	+ possible future variant. While parsing the table's entries new MCB devices
	79	+ are allocated and their resources are assigned according to the resource
	80	+ assignment in the Chameleon table. After resource assignment is finished, the
	81	+ MCB devices are registered at the MCB and thus at the driver core of the
	82	+ Linux kernel.
	83	+
	84	+3 Resource handling
	85	+====================
	86	+ The current implementation assigns exactly one memory and one IRQ resource
	87	+ per MCB device. But this is likely going to change in the future.
	88	+
	89	+3.1 Memory Resources
	90	+---------------------
	91	+ Each MCB device has exactly one memory resource, which can be requested from
	92	+ the MCB bus. This memory resource is the physical address of the MCB device
	93	+ inside the carrier and is intended to be passed to ioremap() and friends. It
	94	+ is already requested from the kernel by calling request_mem_region().
	95	+
	96	+3.2 IRQs
	97	+---------
	98	+ Each MCB device has exactly one IRQ resource, which can be requested from the
	99	+ MCB bus. If a carrier device driver implements the ->get_irq() callback
	100	+ method, the IRQ number assigned by the carrier device will be returned,
	101	+ otherwise the IRQ number inside the Chameleon table will be returned. This
	102	+ number is suitable to be passed to request_irq().
	103	+
	104	+4 Writing an MCB driver
	105	+=======================
	106	+
	107	+4.1 The driver structure
	108	+-------------------------
	109	+ Each MCB driver has a structure to identify the device driver as well as
	110	+ device ids which identify the IP Core inside the FPGA. The driver structure
	111	+ also contains callback methods which get executed on driver probe and
	112	+ removal from the system.
	113	+
	114	+
	115	+ static const struct mcb_device_id foo_ids[] = {
	116	+ { .device = 0x123 },
	117	+ { }
	118	+ };
	119	+ MODULE_DEVICE_TABLE(mcb, foo_ids);
	120	+
	121	+ static struct mcb_driver foo_driver = {
	122	+ driver = {
	123	+ .name = "foo-bar",
	124	+ .owner = THIS_MODULE,
	125	+ },
	126	+ .probe = foo_probe,
	127	+ .remove = foo_remove,
	128	+ .id_table = foo_ids,
	129	+ };
	130	+
	131	+4.2 Probing and attaching
	132	+--------------------------
	133	+ When a driver is loaded and the MCB devices it services are found, the MCB
	134	+ core will call the driver's probe callback method. When the driver is removed
	135	+ from the system, the MCB core will call the driver's remove callback method.
	136	+
	137	+
	138	+ static init foo_probe(struct mcb_device mdev, const struct mcb_device_id id);
	139	+ static void foo_remove(struct mcb_device *mdev);
	140	+
	141	+4.3 Initializing the driver
	142	+----------------------------
	143	+ When the kernel is booted or your foo driver module is inserted, you have to
	144	+ perform driver initialization. Usually it is enough to register your driver
	145	+ module at the MCB core.
	146	+
	147	+
	148	+ static int __init foo_init(void)
	149	+ {
	150	+ return mcb_register_driver(&foo_driver);
	151	+ }
	152	+ module_init(foo_init);
	153	+
	154	+ static void __exit foo_exit(void)
	155	+ {
	156	+ mcb_unregister_driver(&foo_driver);
	157	+ }
	158	+ module_exit(foo_exit);
	159	+
	160	+ The module_mcb_driver() macro can be used to reduce the above code.
	161	+
	162	+
	163	+ module_mcb_driver(foo_driver);

Documentation/networking/can.txt+2−2

@@ -510,7 +510,7 @@ solution for a couple of reasons: · 509 unmodified lines
510	510
511	511	4.1.2 RAW socket option CAN_RAW_ERR_FILTER
512	512
513		− As described in chapter 3.4 the CAN interface driver can generate so
	513	+ As described in chapter 3.3 the CAN interface driver can generate so
514	514	called Error Message Frames that can optionally be passed to the user
515	515	application in the same way as other CAN frames. The possible
516	516	errors are divided into different error classes that may be filtered
@@ -1152,7 +1152,7 @@ solution for a couple of reasons: · 635 unmodified lines
1152	1152	$ ip link set canX type can restart
1153	1153
1154	1154	Note that a restart will also create a CAN error message frame (see
1155		− also chapter 3.4).
	1155	+ also chapter 3.3).
1156	1156
1157	1157	6.6 CAN FD (flexible data rate) driver support
1158	1158

Documentation/powerpc/cxl.txt+1−1

@@ -133,7 +133,7 @@ User API · 132 unmodified lines
133	133	The following file operations are supported on both slave and
134	134	master devices.
135	135
136		− A userspace library libcxl is avaliable here:
	136	+ A userspace library libcxl is available here:
137	137	https://github.com/ibm-capi/libcxl
138	138	This provides a C interface to this kernel API.
139	139

Documentation/powerpc/dscr.txt+3−3

@@ -4,7 +4,7 @@ · 3 unmodified lines
4	4	DSCR register in powerpc allows user to have some control of prefetch of data
5	5	stream in the processor. Please refer to the ISA documents or related manual
6	6	for more detailed information regarding how to use this DSCR to attain this
7		−control of the pefetches . This document here provides an overview of kernel
	7	+control of the prefetches . This document here provides an overview of kernel
8	8	support for DSCR, related kernel objects, it's functionalities and exported
9	9	user interface.
10	10
@@ -44,7 +44,7 @@ user interface. · 33 unmodified lines
44	44	value into every CPU's DSCR register right away and updates the current
45	45	thread's DSCR value as well.
46	46
47		− Changing the CPU specif DSCR default value in the sysfs does exactly
	47	+ Changing the CPU specific DSCR default value in the sysfs does exactly
48	48	the same thing as above but unlike the global one above, it just changes
49	49	stuff for that particular CPU instead for all the CPUs on the system.
50	50
@@ -62,7 +62,7 @@ user interface. · 11 unmodified lines
62	62
63	63	Accessing DSCR through user level SPR (0x03) from user space will first
64	64	create a facility unavailable exception. Inside this exception handler
65		− all mfspr isntruction based read attempts will get emulated and returned
	65	+ all mfspr instruction based read attempts will get emulated and returned
66	66	where as the first mtspr instruction based write attempts will enable
67	67	the DSCR facility for the next time around (both for read and write) by
68	68	setting DSCR facility in the FSCR register.

Documentation/powerpc/qe_firmware.txt+1−1

@@ -117,7 +117,7 @@ specific been defined. This table describes the structure. · 116 unmodified lines
117	117	Extended Modes
118	118
119	119	This is a double word bit array (64 bits) that defines special functionality
120		−which has an impact on the softwarew drivers. Each bit has its own impact
	120	+which has an impact on the software drivers. Each bit has its own impact
121	121	and has special instructions for the s/w associated with it. This structure is
122	122	described in this table:
123	123

Documentation/pps/pps.txt+1−1

@@ -125,7 +125,7 @@ The same function may also run the defined echo function · 124 unmodified lines
125	125	(pps_ktimer_echo(), passing to it the "ptr" pointer) if the user
126	126	asked for that... etc..
127	127
128		−Please see the file drivers/pps/clients/ktimer.c for example code.
	128	+Please see the file drivers/pps/clients/pps-ktimer.c for example code.
129	129
130	130
131	131	SYSFS support

Documentation/sysctl/vm.txt+5−5

@@ -225,11 +225,11 @@ with your system. To disable them, echo 4 (bit 3) into drop_caches. · 224 unmodified lines
225	225	extfrag_threshold
226	226
227	227	This parameter affects whether the kernel will compact memory or direct
228		−reclaim to satisfy a high-order allocation. /proc/extfrag_index shows what
229		−the fragmentation index for each order is in each zone in the system. Values
230		−tending towards 0 imply allocations would fail due to lack of memory,
231		−values towards 1000 imply failures are due to fragmentation and -1 implies
232		−that the allocation will succeed as long as watermarks are met.
	228	+reclaim to satisfy a high-order allocation. The extfrag/extfrag_index file in
	229	+debugfs shows what the fragmentation index for each order is in each zone in
	230	+the system. Values tending towards 0 imply allocations would fail due to lack
	231	+of memory, values towards 1000 imply failures are due to fragmentation and -1
	232	+implies that the allocation will succeed as long as watermarks are met.
233	233
234	234	The kernel will not compact memory in a zone if the
235	235	fragmentation index is <= extfrag_threshold. The default value is 500.

Documentation/x86/kernel-stacks+1−1

@@ -16,7 +16,7 @@ associated with each CPU. These stacks are only used while the kernel · 15 unmodified lines
16	16	is in control on that CPU; when a CPU returns to user space the
17	17	specialized stacks contain no useful data. The main CPU stacks are:
18	18
19		−* Interrupt stack. IRQSTACKSIZE
	19	+* Interrupt stack. IRQ_STACK_SIZE
20	20
21	21	Used for external hardware interrupts. If this is the first external
22	22	hardware interrupt (i.e. not a nested hardware interrupt) then the

MAINTAINERS+2−0

@@ -3454,6 +3454,7 @@ X: Documentation/devicetree/ · 3453 unmodified lines
3454	3454	X: Documentation/acpi
3455	3455	X: Documentation/power
3456	3456	X: Documentation/spi
	3457	+X: Documentation/DocBook/media
3457	3458	T: git git://git.lwn.net/linux-2.6.git docs-next
3458	3459
3459	3460	DOUBLETALK DRIVER
@@ -6700,6 +6701,7 @@ M: Johannes Thumshirn <morbidrsa@gmail.com> · 3240 unmodified lines
6700	6701	S: Maintained
6701	6702	F: drivers/mcb/
6702	6703	F: include/linux/mcb.h
	6704	+F: Documentation/men-chameleon-bus.txt
6703	6705
6704	6706	MEN F21BMC (Board Management Controller)
6705	6707	M: Andreas Werner <andreas.werner@men.de>

README+1−1

@@ -161,7 +161,7 @@ CONFIGURING the kernel: · 160 unmodified lines
161	161
162	162	"make xconfig" X windows (Qt) based configuration tool.
163	163
164		− "make gconfig" X windows (Gtk) based configuration tool.
	164	+ "make gconfig" X windows (GTK+) based configuration tool.
165	165
166	166	"make oldconfig" Default all questions based on the contents of
167	167	your existing ./.config file and asking about

scripts/kernel-doc+90−6

@@ -133,6 +133,30 @@ use strict; · 132 unmodified lines
133	133	#
134	134	# All descriptions can be multiline, except the short function description.
135	135	#
	136	+# For really longs structs, you can also describe arguments inside the
	137	+# body of the struct.
	138	+# eg.
	139	+# /**
	140	+# * struct my_struct - short description
	141	+# * @a: first member
	142	+# * @b: second member
	143	+# *
	144	+# * Longer description
	145	+# */
	146	+# struct my_struct {
	147	+# int a;
	148	+# int b;
	149	+# /**
	150	+# * @c: This is longer description of C
	151	+# *
	152	+# * You can use paragraphs to describe arguments
	153	+# * using this method.
	154	+# */
	155	+# int c;
	156	+# };
	157	+#
	158	+# This should be use only for struct/enum members.
	159	+#
136	160	# You can also add additional sections. When documenting kernel functions you
137	161	# should document the "Context:" of the function, e.g. whether the functions
138	162	# can be called form interrupts. Unlike other sections you can end it with an
@@ -253,11 +277,20 @@ my %highlights = %highlights_man; · 114 unmodified lines
253	277	my $blankline = $blankline_man;
254	278	my $modulename = "Kernel API";
255	279	my $function_only = 0;
	280	+my $show_not_found = 0;
	281	+
	282	+my @build_time;
	283	+if (defined($ENV{'KBUILD_BUILD_TIMESTAMP'}) &&
	284	+ (my $seconds = `date -d"${ENV{'KBUILD_BUILD_TIMESTAMP'}}" +%s`) ne '') {
	285	+ @build_time = gmtime($seconds);
	286	+} else {
	287	+ @build_time = localtime;
	288	+}
	289	+
256	290	my $man_date = ('January', 'February', 'March', 'April', 'May', 'June',
257	291	'July', 'August', 'September', 'October',
258		− 'November', 'December')[(localtime)[4]] .
259		− " " . ((localtime)[5]+1900);
260		−my $show_not_found = 0;
	292	+ 'November', 'December')[$build_time[4]] .
	293	+ " " . ($build_time[5]+1900);
261	294
262	295	# Essentially these are globals.
263	296	# They probably want to be tidied up, made more localised or something.
@@ -287,9 +320,19 @@ my $lineprefix=""; · 23 unmodified lines
287	320	# 2 - scanning field start.
288	321	# 3 - scanning prototype.
289	322	# 4 - documentation block
	323	+# 5 - gathering documentation outside main block
290	324	my $state;
291	325	my $in_doc_sect;
292	326
	327	+# Split Doc State
	328	+# 0 - Invalid (Before start or after finish)
	329	+# 1 - Is started (the /** was found inside a struct)
	330	+# 2 - The @parameter header was found, start accepting multi paragraph text.
	331	+# 3 - Finished (the */ was found)
	332	+# 4 - Error - Comment without header was found. Spit a warning as it's not
	333	+# proper kernel-doc and ignore the rest.
	334	+my $split_doc_state;
	335	+
293	336	#declaration types: can be
294	337	# 'function', 'struct', 'union', 'enum', 'typedef'
295	338	my $decl_type;
@@ -304,6 +347,9 @@ my $doc_decl = $doc_com . '(\w+)'; · 8 unmodified lines
304	347	my $doc_sect = $doc_com . '([' . $doc_special . ']?[\w\s]+):(.*)';
305	348	my $doc_content = $doc_com_body . '(.*)';
306	349	my $doc_block = $doc_com . 'DOC:\s(.)?';
	350	+my $doc_split_start = '^\s/\\\s$';
	351	+my $doc_split_sect = '\s\\s(@[\w\s]+):(.)';
	352	+my $doc_split_end = '^\s\/\s*$';
307	353
308	354	my %constants;
309	355	my %parameterdescs;
@@ -1753,7 +1799,9 @@ sub dump_struct($$) { · 1443 unmodified lines
1753	1799	# strip kmemcheck_bitfield_{begin,end}.*;
1754	1800	$members =~ s/kmemcheck_bitfield_.*?;//gos;
1755	1801	# strip attributes
	1802	+ $members =~ s/__attribute__\s$\([a-z,_\\s\($]*\)\)//i;
1756	1803	$members =~ s/__aligned\s$[^;]$//gos;
	1804	+ $members =~ s/\s*CRYPTO_MINALIGN_ATTR//gos;
1757	1805
1758	1806	create_parameterlist($members, ';', $file);
1759	1807	check_sections($file, $declaration_name, "struct", $sectcheck, $struct_actual, $nested);
@@ -2181,6 +2229,7 @@ sub reset_state { · 421 unmodified lines
2181	2229	$prototype = "";
2182	2230
2183	2231	$state = 0;
	2232	+ $split_doc_state = 0;
2184	2233	}
2185	2234
2186	2235	sub tracepoint_munge($) {
@@ -2453,7 +2502,6 @@ sub process_file($) { · 266 unmodified lines
2453	2502	}
2454	2503	$section = $newsection;
2455	2504	} elsif (/$doc_end/) {
2456		−
2457	2505	if (($contents ne "") && ($contents ne "\n")) {
2458	2506	dump_section($file, $section, xml_escape($contents));
2459	2507	$section = $section_default;
@@ -2494,8 +2542,44 @@ sub process_file($) { · 34 unmodified lines
2494	2542	print STDERR "Warning(${file}:$.): bad line: $_";
2495	2543	++$warnings;
2496	2544	}
	2545	+ } elsif ($state == 5) { # scanning for split parameters
	2546	+ # First line (state 1) needs to be a @parameter
	2547	+ if ($split_doc_state == 1 && /$doc_split_sect/o) {
	2548	+ $section = $1;
	2549	+ $contents = $2;
	2550	+ if ($contents ne "") {
	2551	+ while ((substr($contents, 0, 1) eq " ") \|\|
	2552	+ substr($contents, 0, 1) eq "\t") {
	2553	+ $contents = substr($contents, 1);
	2554	+ }
	2555	+ $contents .= "\n";
	2556	+ }
	2557	+ $split_doc_state = 2;
	2558	+ # Documentation block end */
	2559	+ } elsif (/$doc_split_end/) {
	2560	+ if (($contents ne "") && ($contents ne "\n")) {
	2561	+ dump_section($file, $section, xml_escape($contents));
	2562	+ $section = $section_default;
	2563	+ $contents = "";
	2564	+ }
	2565	+ $state = 3;
	2566	+ $split_doc_state = 0;
	2567	+ # Regular text
	2568	+ } elsif (/$doc_content/) {
	2569	+ if ($split_doc_state == 2) {
	2570	+ $contents .= $1 . "\n";
	2571	+ } elsif ($split_doc_state == 1) {
	2572	+ $split_doc_state = 4;
	2573	+ print STDERR "Warning(${file}:$.): ";
	2574	+ print STDERR "Incorrect use of kernel-doc format: $_";
	2575	+ ++$warnings;
	2576	+ }
	2577	+ }
2497	2578	} elsif ($state == 3) { # scanning for function '{' (end of prototype)
2498		− if ($decl_type eq 'function') {
	2579	+ if (/$doc_split_start/) {
	2580	+ $state = 5;
	2581	+ $split_doc_state = 1;
	2582	+ } elsif ($decl_type eq 'function') {
2499	2583	process_state3_function($_, $file);
2500	2584	} else {
2501	2585	process_state3_type($_, $file);
@@ -2587,7 +2671,7 @@ $kernelversion = get_kernel_version(); · 85 unmodified lines
2587	2671
2588	2672	# generate a sequence of code that will splice in highlighting information
2589	2673	# using the s// operator.
2590		−foreach my $pattern (keys %highlights) {
	2674	+foreach my $pattern (sort keys %highlights) {
2591	2675	# print STDERR "scanning pattern:$pattern, highlight:($highlights{$pattern})\n";
2592	2676	$dohighlight .= "\$contents =~ s:$pattern:$highlights{$pattern}:gs;\n";
2593	2677	}

scripts/kernel-doc-xml-ref+198−0

@@ -0,0 +1,198 @@
	1	+#!/usr/bin/perl -w
	2	+
	3	+use strict;
	4	+
	5	+## Copyright (C) 2015 Intel Corporation ##
	6	+# ##
	7	+## This software falls under the GNU General Public License. ##
	8	+## Please read the COPYING file for more information ##
	9	+#
	10	+#
	11	+# This software reads a XML file and a list of valid interal
	12	+# references to replace Docbook tags with links.
	13	+#
	14	+# The list of "valid internal references" must be one-per-line in the following format:
	15	+# API-struct-foo
	16	+# API-enum-bar
	17	+# API-my-function
	18	+#
	19	+# The software walks over the XML file looking for xml tags representing possible references
	20	+# to the Document. Each reference will be cross checked against the "Valid Internal Reference" list. If
	21	+# the referece is found it replaces its content by a <link> tag.
	22	+#
	23	+# usage:
	24	+# kernel-doc-xml-ref -db filename
	25	+# xml filename > outputfile
	26	+
	27	+# read arguments
	28	+if ($#ARGV != 2) {
	29	+ usage();
	30	+}
	31	+
	32	+#Holds the database filename
	33	+my $databasefile;
	34	+my @database;
	35	+
	36	+#holds the inputfile
	37	+my $inputfile;
	38	+my $errors = 0;
	39	+
	40	+my %highlights = (
	41	+ "<function>(.*?)</function>",
	42	+ "\"<function>\" . convert_function(\$1, \$line) . \"</function>\"",
	43	+ "<structname>(.*?)</structname>",
	44	+ "\"<structname>\" . convert_struct(\$1) . \"</structname>\"",
	45	+ "<funcdef>(.?)<function>(.?)</function></funcdef>",
	46	+ "\"<funcdef>\" . convert_param(\$1) . \"<function>\$2</function></funcdef>\"",
	47	+ "<paramdef>(.?)<parameter>(.?)</parameter></paramdef>",
	48	+ "\"<paramdef>\" . convert_param(\$1) . \"<parameter>\$2</parameter></paramdef>\"");
	49	+
	50	+while($ARGV[0] =~ m/^-(.*)/) {
	51	+ my $cmd = shift @ARGV;
	52	+ if ($cmd eq "-db") {
	53	+ $databasefile = shift @ARGV
	54	+ } else {
	55	+ usage();
	56	+ }
	57	+}
	58	+$inputfile = shift @ARGV;
	59	+
	60	+sub open_database {
	61	+ open (my $handle, '<', $databasefile) or die "Cannot open $databasefile";
	62	+ chomp(my @lines = <$handle>);
	63	+ close $handle;
	64	+
	65	+ @database = @lines;
	66	+}
	67	+
	68	+sub process_file {
	69	+ open_database();
	70	+
	71	+ my $dohighlight;
	72	+ foreach my $pattern (keys %highlights) {
	73	+ $dohighlight .= "\$line =~ s:$pattern:$highlights{$pattern}:eg;\n";
	74	+ }
	75	+
	76	+ open(FILE, $inputfile) or die("Could not open $inputfile") or die ("Cannot open $inputfile");
	77	+ foreach my $line (<FILE>) {
	78	+ eval $dohighlight;
	79	+ print $line;
	80	+ }
	81	+}
	82	+
	83	+sub trim($_)
	84	+{
	85	+ my $str = $_[0];
	86	+ $str =~ s/^\s+\|\s+$//g;
	87	+ return $str
	88	+}
	89	+
	90	+sub has_key_defined($_)
	91	+{
	92	+ if ( grep( /^$_[0]$/, @database)) {
	93	+ return 1;
	94	+ }
	95	+ return 0;
	96	+}
	97	+
	98	+# Gets a <function> content and add it a hyperlink if possible.
	99	+sub convert_function($_)
	100	+{
	101	+ my $arg = $_[0];
	102	+ my $key = $_[0];
	103	+
	104	+ my $line = $_[1];
	105	+
	106	+ $key = trim($key);
	107	+
	108	+ $key =~ s/[^A-Za-z0-9]/-/g;
	109	+ $key = "API-" . $key;
	110	+
	111	+ # We shouldn't add links to <funcdef> prototype
	112	+ if (!has_key_defined($key) \|\| $line =~ m/\s+<funcdef/i) {
	113	+ return $arg;
	114	+ }
	115	+
	116	+ my $head = $arg;
	117	+ my $tail = "";
	118	+ if ($arg =~ /(.*?)( ?)$/) {
	119	+ $head = $1;
	120	+ $tail = $2;
	121	+ }
	122	+ return "<link linkend=\"$key\">$head</link>$tail";
	123	+}
	124	+
	125	+# Converting a struct text to link
	126	+sub convert_struct($_)
	127	+{
	128	+ my $arg = $_[0];
	129	+ my $key = $_[0];
	130	+ $key =~ s/(struct )?(\w)/$2/g;
	131	+ $key =~ s/[^A-Za-z0-9]/-/g;
	132	+ $key = "API-struct-" . $key;
	133	+
	134	+ if (!has_key_defined($key)) {
	135	+ return $arg;
	136	+ }
	137	+
	138	+ my ($head, $tail) = split_pointer($arg);
	139	+ return "<link linkend=\"$key\">$head</link>$tail";
	140	+}
	141	+
	142	+# Identify "object *" elements
	143	+sub split_pointer($_)
	144	+{
	145	+ my $arg = $_[0];
	146	+ if ($arg =~ /(.?)( ?\ ?)/) {
	147	+ return ($1, $2);
	148	+ }
	149	+ return ($arg, "");
	150	+}
	151	+
	152	+sub convert_param($_)
	153	+{
	154	+ my $type = $_[0];
	155	+ my $keyname = convert_key_name($type);
	156	+
	157	+ if (!has_key_defined($keyname)) {
	158	+ return $type;
	159	+ }
	160	+
	161	+ my ($head, $tail) = split_pointer($type);
	162	+ return "<link linkend=\"$keyname\">$head</link>$tail";
	163	+
	164	+}
	165	+
	166	+# DocBook links are in the API-<TYPE>-<STRUCT-NAME> format
	167	+# This method gets an element and returns a valid DocBook reference for it.
	168	+sub convert_key_name($_)
	169	+{
	170	+ #Pattern $2 is optional and might be uninitialized
	171	+ no warnings 'uninitialized';
	172	+
	173	+ my $str = $_[0];
	174	+ $str =~ s/(const\|static)? ?(struct)? ?([a-zA-Z0-9_]+) ?(\*\|&)?/$2 $3/g ;
	175	+
	176	+ # trim
	177	+ $str =~ s/^\s+\|\s+$//g;
	178	+
	179	+ # spaces and _ to -
	180	+ $str =~ s/[^A-Za-z0-9]/-/g;
	181	+
	182	+ return "API-" . $str;
	183	+}
	184	+
	185	+sub usage {
	186	+ print "Usage: $0 -db database filename\n";
	187	+ print " xml source file(s) > outputfile\n";
	188	+ exit 1;
	189	+}
	190	+
	191	+# starting point
	192	+process_file();
	193	+
	194	+if ($errors) {
	195	+ print STDERR "$errors errors\n";
	196	+}
	197	+
	198	+exit($errors);