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

Pull documentation updates from Jonathan Corbet: "Some big changes this month, headlined by the addition of a new formatted documentation mechanism based on the Sphinx system. The objectives here are to make it easier to create better-integrated (and more attractive) documents while (eventually) dumping our one-of-a-kind, cobbled-together system for something that is widely used and maintained by others. There's a fair amount of information what's being done, why, and how to use it in: https://lwn.net/Articles/692704/ https://lwn.net/Articles/692705/ Closer to home, Documentation/kernel-documentation.rst describes how it works. For now, the new system exists alongside the old one; you should soon see the GPU documentation converted over in the DRM pull and some significant media conversion work as well. Once all the docs have been moved over and we're convinced that the rough edges (of which are are a few) have been smoothed over, the DocBook-based stuff should go away. Primary credit is to Jani Nikula for doing the heavy lifting to make this stuff actually work; there has also been notable effort from Markus Heiser, Daniel Vetter, and Mauro Carvalho Chehab. Expect a couple of conflicts on the new index.rst file over the course of the merge window; they are trivially resolvable. That file may be a bit of a conflict magnet in the short term, but I don't expect that situation to last for any real length of time. Beyond that, of course, we have the usual collection of tweaks, updates, and typo fixes" * tag 'docs-for-linus' of git://git.lwn.net/linux: (77 commits) doc-rst: kernel-doc: fix handling of address_space tags Revert "doc/sphinx: Enable keep_warnings" doc-rst: kernel-doc directive, fix state machine reporter docs: deprecate kernel-doc-nano-HOWTO.txt doc/sphinx: Enable keep_warnings Documentation: add watermark_scale_factor to the list of vm systcl file kernel-doc: Fix up warning output docs: Get rid of some kernel-documentation warnings doc-rst: add an option to ignore DocBooks when generating docs workqueue: Fix a typo in workqueue.txt Doc: ocfs: Fix typo in filesystems/ocfs2-online-filecheck.txt Documentation/sphinx: skip build if user requested specific DOCBOOKS Documentation: add cleanmediadocs to the documentation targets Add .pyc files to .gitignore Doc: PM: Fix a typo in intel_powerclamp.txt doc-rst: flat-table directive - initial implementation Documentation: add meta-documentation for Sphinx and kernel-doc Documentation: tiny typo fix in usb/gadget_multi.txt Documentation: fix wrong value in md.txt bcache: documentation formatting, edited for clarity, stripe alignment notes ...

Linus Torvalds committed 10 years ago

Commit 0f776dc2 parents 015cd86 a88b16730 files · +2653 −430Browse files

Unified · Split

30 files

Documentation/.gitignore +2 −0
Documentation/00-INDEX +2 −2
Documentation/CodingStyle +1 −1
Documentation/DocBook/Makefile +24 −6
Documentation/Makefile.sphinx +78 −0
Documentation/bcache.txt +187 −10
Documentation/conf.py +414 −0
Documentation/development-process/4.Coding +1 −1
Documentation/dmaengine/provider.txt +1 −1
Documentation/filesystems/ocfs2-online-filecheck.txt +5 −5
Documentation/index.rst +22 −0
Documentation/kernel-doc-nano-HOWTO.txt +3 −0
Documentation/kernel-documentation.rst +654 −0
Documentation/kernel-parameters.txt +3 −2
Documentation/md.txt +1 −1
Documentation/mic/mpssd/mpssd.c +2 −2
Documentation/security/self-protection.txt +18 −10
Documentation/sphinx/convert_template.sed +18 −0
Documentation/sphinx/kernel-doc.py +141 −0
Documentation/sphinx/post_convert.sed +23 −0
Documentation/sphinx/rstFlatTable.py +365 −0
Documentation/sphinx/tmplcvt +19 −0
Documentation/sync_file.txt +3 −3
Documentation/sysctl/vm.txt +1 −0
Documentation/thermal/intel_powerclamp.txt +1 −1
Documentation/usb/gadget_multi.txt +1 −1
Documentation/workqueue.txt +1 −1
Documentation/zh_CN/CodingStyle +350 −231
Makefile +6 −1
scripts/kernel-doc +306 −151

Documentation/.gitignore+2−0

@@ -0,0 +1,2 @@
	1	+output
	2	+*.pyc

Documentation/00-INDEX+2−2

@@ -255,10 +255,10 @@ kbuild/ · 254 unmodified lines
255	255	- directory with info about the kernel build process.
256	256	kdump/
257	257	- directory with mini HowTo on getting the crash dump code to work.
258		−kernel-doc-nano-HOWTO.txt
259		− - mini HowTo on generation and location of kernel documentation files.
260	258	kernel-docs.txt
261	259	- listing of various WWW + books that document kernel internals.
	260	+kernel-documentation.rst
	261	+ - how to write and format reStructuredText kernel documentation
262	262	kernel-parameters.txt
263	263	- summary listing of command line / boot prompt args for the kernel.
264	264	kernel-per-CPU-kthreads.txt

Documentation/CodingStyle+1−1

@@ -458,7 +458,7 @@ of the function, telling people what it does, and possibly WHY it does · 457 unmodified lines
458	458	it.
459	459
460	460	When commenting the kernel API functions, please use the kernel-doc format.
461		−See the files Documentation/kernel-doc-nano-HOWTO.txt and scripts/kernel-doc
	461	+See the files Documentation/kernel-documentation.rst and scripts/kernel-doc
462	462	for details.
463	463
464	464	Linux style for comments is the C89 "/* ... */" style.

Documentation/DocBook/Makefile+24−6

@@ -6,6 +6,8 @@ · 5 unmodified lines
6	6	# To add a new book the only step required is to add the book to the
7	7	# list of DOCBOOKS.
8	8
	9	+ifeq ($(IGNORE_DOCBOOKS),)
	10	+
9	11	DOCBOOKS := z8530book.xml device-drivers.xml \
10	12	kernel-hacking.xml kernel-locking.xml deviceiobook.xml \
11	13	writing_usb_driver.xml networking.xml \
@@ -33,10 +35,6 @@ PDF_METHOD = $(prefer-db2x) · 21 unmodified lines
33	35	PS_METHOD = $(prefer-db2x)
34	36
35	37
36		−###
37		−# The targets that may be used.
38		−PHONY += xmldocs sgmldocs psdocs pdfdocs htmldocs mandocs installmandocs cleandocs
39		−
40	38	targets += $(DOCBOOKS)
41	39	BOOKS := $(addprefix $(obj)/,$(DOCBOOKS))
42	40	xmldocs: $(BOOKS)
@@ -63,6 +61,9 @@ installmandocs: mandocs · 20 unmodified lines
63	61	sort -k 2 -k 1 \| uniq -f 1 \| sed -e 's: :/:' \| \
64	62	xargs install -m 644 -t /usr/local/man/man9/
65	63
	64	+# no-op for the DocBook toolchain
	65	+epubdocs:
	66	+
66	67	###
67	68	#External programs used
68	69	KERNELDOCXMLREF = $(srctree)/scripts/kernel-doc-xml-ref
@@ -216,10 +217,24 @@ silent_gen_xml = : · 147 unmodified lines
216	217	-e "s/>/\\>/g"; \
217	218	echo "</programlisting>") > $@
218	219
	220	+else
	221	+
	222	+# Needed, due to cleanmediadocs
	223	+include Documentation/DocBook/media/Makefile
	224	+
	225	+htmldocs:
	226	+pdfdocs:
	227	+psdocs:
	228	+xmldocs:
	229	+installmandocs:
	230	+
	231	+endif # IGNORE_DOCBOOKS
	232	+
	233	+
219	234	###
220	235	# Help targets as used by the top-level makefile
221	236	dochelp:
222		− @echo ' Linux kernel internal documentation in different formats:'
	237	+ @echo ' Linux kernel internal documentation in different formats (DocBook):'
223	238	@echo ' htmldocs - HTML'
224	239	@echo ' pdfdocs - PDF'
225	240	@echo ' psdocs - Postscript'
@@ -228,8 +243,11 @@ dochelp: · 2 unmodified lines
228	243	@echo ' installmandocs - install man pages generated by mandocs'
229	244	@echo ' cleandocs - clean all generated DocBook files'
230	245	@echo
231		− @echo 'make DOCBOOKS="s1.xml s2.xml" [target] Generate only docs s1.xml s2.xml'
	246	+ @echo ' make DOCBOOKS="s1.xml s2.xml" [target] Generate only docs s1.xml s2.xml'
232	247	@echo ' valid values for DOCBOOKS are: $(DOCBOOKS)'
	248	+ @echo
	249	+ @echo " make IGNORE_DOCBOOKS=1 [target] Don't generate docs from Docbook"
	250	+ @echo ' This is useful to generate only the ReST docs (Sphinx)'
233	251
234	252
235	253	###

Documentation/Makefile.sphinx+78−0

@@ -0,0 +1,78 @@
	1	+# -- makefile --
	2	+# Makefile for Sphinx documentation
	3	+#
	4	+
	5	+# You can set these variables from the command line.
	6	+SPHINXBUILD = sphinx-build
	7	+SPHINXOPTS =
	8	+PAPER =
	9	+BUILDDIR = $(obj)/output
	10	+
	11	+# User-friendly check for sphinx-build
	12	+HAVE_SPHINX := $(shell if which $(SPHINXBUILD) >/dev/null 2>&1; then echo 1; else echo 0; fi)
	13	+
	14	+ifeq ($(HAVE_SPHINX),0)
	15	+
	16	+.DEFAULT:
	17	+ $(warning The '$(SPHINXBUILD)' command was not found. Make sure you have Sphinx installed and in PATH, or set the SPHINXBUILD make variable to point to the full path of the '$(SPHINXBUILD)' executable.)
	18	+ @echo " SKIP Sphinx $@ target."
	19	+
	20	+else ifneq ($(DOCBOOKS),)
	21	+
	22	+# Skip Sphinx build if the user explicitly requested DOCBOOKS.
	23	+.DEFAULT:
	24	+ @echo " SKIP Sphinx $@ target (DOCBOOKS specified)."
	25	+
	26	+else # HAVE_SPHINX
	27	+
	28	+# User-friendly check for rst2pdf
	29	+HAVE_RST2PDF := $(shell if python -c "import rst2pdf" >/dev/null 2>&1; then echo 1; else echo 0; fi)
	30	+
	31	+# Internal variables.
	32	+PAPEROPT_a4 = -D latex_paper_size=a4
	33	+PAPEROPT_letter = -D latex_paper_size=letter
	34	+KERNELDOC = $(srctree)/scripts/kernel-doc
	35	+KERNELDOC_CONF = -D kerneldoc_srctree=$(srctree) -D kerneldoc_bin=$(KERNELDOC)
	36	+ALLSPHINXOPTS = -D version=$(KERNELVERSION) -D release=$(KERNELRELEASE) -d $(BUILDDIR)/.doctrees $(KERNELDOC_CONF) $(PAPEROPT_$(PAPER)) -c $(srctree)/$(src) $(SPHINXOPTS) $(srctree)/$(src)
	37	+# the i18n builder cannot share the environment and doctrees with the others
	38	+I18NSPHINXOPTS = $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) .
	39	+
	40	+quiet_cmd_sphinx = SPHINX $@
	41	+ cmd_sphinx = $(SPHINXBUILD) -b $2 $(ALLSPHINXOPTS) $(BUILDDIR)/$2
	42	+
	43	+htmldocs:
	44	+ $(call cmd,sphinx,html)
	45	+
	46	+pdfdocs:
	47	+ifeq ($(HAVE_RST2PDF),0)
	48	+ $(warning The Python 'rst2pdf' module was not found. Make sure you have the module installed to produce PDF output.)
	49	+ @echo " SKIP Sphinx $@ target."
	50	+else # HAVE_RST2PDF
	51	+ $(call cmd,sphinx,pdf)
	52	+endif # HAVE_RST2PDF
	53	+
	54	+epubdocs:
	55	+ $(call cmd,sphinx,epub)
	56	+
	57	+xmldocs:
	58	+ $(call cmd,sphinx,xml)
	59	+
	60	+# no-ops for the Sphinx toolchain
	61	+sgmldocs:
	62	+psdocs:
	63	+mandocs:
	64	+installmandocs:
	65	+cleanmediadocs:
	66	+
	67	+cleandocs:
	68	+ $(Q)rm -rf $(BUILDDIR)
	69	+
	70	+dochelp:
	71	+ @echo ' Linux kernel internal documentation in different formats (Sphinx):'
	72	+ @echo ' htmldocs - HTML'
	73	+ @echo ' pdfdocs - PDF'
	74	+ @echo ' epubdocs - EPUB'
	75	+ @echo ' xmldocs - XML'
	76	+ @echo ' cleandocs - clean all generated files'
	77	+
	78	+endif # HAVE_SPHINX

Documentation/bcache.txt+187−10

@@ -1,4 +1,4 @@
1		−Say you've got a big slow raid 6, and an X-25E or three. Wouldn't it be
	1	+Say you've got a big slow raid 6, and an ssd or three. Wouldn't it be
2	2	nice if you could use them as cache... Hence bcache.
3	3
4	4	Wiki and git repositories are at:
@@ -8,7 +8,7 @@ Wiki and git repositories are at: · 3 unmodified lines
8	8
9	9	It's designed around the performance characteristics of SSDs - it only allocates
10	10	in erase block sized buckets, and it uses a hybrid btree/log to track cached
11		−extants (which can be anywhere from a single sector to the bucket size). It's
	11	+extents (which can be anywhere from a single sector to the bucket size). It's
12	12	designed to avoid random writes at all costs; it fills up an erase block
13	13	sequentially, then issues a discard before reusing it.
14	14
@@ -55,7 +55,10 @@ immediately. Without udev, you can manually register devices like this: · 40 unmodified lines
55	55	Registering the backing device makes the bcache device show up in /dev; you can
56	56	now format it and use it as normal. But the first time using a new bcache
57	57	device, it'll be running in passthrough mode until you attach it to a cache.
58		−See the section on attaching.
	58	+If you are thinking about using bcache later, it is recommended to setup all your
	59	+slow devices as bcache backing devices without a cache, and you can choose to add
	60	+a caching device later.
	61	+See 'ATTACHING' section below.
59	62
60	63	The devices show up as:
61	64
@@ -72,12 +75,14 @@ To get started: · 10 unmodified lines
72	75	mount /dev/bcache0 /mnt
73	76
74	77	You can control bcache devices through sysfs at /sys/block/bcache<N>/bcache .
	78	+You can also control them through /sys/fs//bcache/<cset-uuid>/ .
75	79
76	80	Cache devices are managed as sets; multiple caches per set isn't supported yet
77	81	but will allow for mirroring of metadata and dirty data in the future. Your new
78	82	cache set shows up as /sys/fs/bcache/<UUID>
79	83
80		−ATTACHING:
	84	+ATTACHING
	85	+---------
81	86
82	87	After your cache device and backing device are registered, the backing device
83	88	must be attached to your cache set to enable caching. Attaching a backing
@@ -105,7 +110,8 @@ but all the cached data will be invalidated. If there was dirty data in the · 21 unmodified lines
105	110	cache, don't expect the filesystem to be recoverable - you will have massive
106	111	filesystem corruption, though ext4's fsck does work miracles.
107	112
108		−ERROR HANDLING:
	113	+ERROR HANDLING
	114	+--------------
109	115
110	116	Bcache tries to transparently handle IO errors to/from the cache device without
111	117	affecting normal operation; if it sees too many errors (the threshold is
@@ -127,12 +133,181 @@ the backing devices to passthrough mode. · 15 unmodified lines
127	133	writeback mode). It currently doesn't do anything intelligent if it fails to
128	134	read some of the dirty data, though.
129	135
130		−TROUBLESHOOTING PERFORMANCE:
	136	+
	137	+HOWTO/COOKBOOK
	138	+--------------
	139	+
	140	+A) Starting a bcache with a missing caching device
	141	+
	142	+If registering the backing device doesn't help, it's already there, you just need
	143	+to force it to run without the cache:
	144	+ host:~# echo /dev/sdb1 > /sys/fs/bcache/register
	145	+ [ 119.844831] bcache: register_bcache() error opening /dev/sdb1: device already registered
	146	+
	147	+Next, you try to register your caching device if it's present. However
	148	+if it's absent, or registration fails for some reason, you can still
	149	+start your bcache without its cache, like so:
	150	+ host:/sys/block/sdb/sdb1/bcache# echo 1 > running
	151	+
	152	+Note that this may cause data loss if you were running in writeback mode.
	153	+
	154	+
	155	+B) Bcache does not find its cache
	156	+
	157	+ host:/sys/block/md5/bcache# echo 0226553a-37cf-41d5-b3ce-8b1e944543a8 > attach
	158	+ [ 1933.455082] bcache: bch_cached_dev_attach() Couldn't find uuid for md5 in set
	159	+ [ 1933.478179] bcache: __cached_dev_store() Can't attach 0226553a-37cf-41d5-b3ce-8b1e944543a8
	160	+ [ 1933.478179] : cache set not found
	161	+
	162	+In this case, the caching device was simply not registered at boot
	163	+or disappeared and came back, and needs to be (re-)registered:
	164	+ host:/sys/block/md5/bcache# echo /dev/sdh2 > /sys/fs/bcache/register
	165	+
	166	+
	167	+C) Corrupt bcache crashes the kernel at device registration time:
	168	+
	169	+This should never happen. If it does happen, then you have found a bug!
	170	+Please report it to the bcache development list: linux-bcache@vger.kernel.org
	171	+
	172	+Be sure to provide as much information that you can including kernel dmesg
	173	+output if available so that we may assist.
	174	+
	175	+
	176	+D) Recovering data without bcache:
	177	+
	178	+If bcache is not available in the kernel, a filesystem on the backing
	179	+device is still available at an 8KiB offset. So either via a loopdev
	180	+of the backing device created with --offset 8K, or any value defined by
	181	+--data-offset when you originally formatted bcache with `make-bcache`.
	182	+
	183	+For example:
	184	+ losetup -o 8192 /dev/loop0 /dev/your_bcache_backing_dev
	185	+
	186	+This should present your unmodified backing device data in /dev/loop0
	187	+
	188	+If your cache is in writethrough mode, then you can safely discard the
	189	+cache device without loosing data.
	190	+
	191	+
	192	+E) Wiping a cache device
	193	+
	194	+host:~# wipefs -a /dev/sdh2
	195	+16 bytes were erased at offset 0x1018 (bcache)
	196	+they were: c6 85 73 f6 4e 1a 45 ca 82 65 f5 7f 48 ba 6d 81
	197	+
	198	+After you boot back with bcache enabled, you recreate the cache and attach it:
	199	+host:~# make-bcache -C /dev/sdh2
	200	+UUID: 7be7e175-8f4c-4f99-94b2-9c904d227045
	201	+Set UUID: 5bc072a8-ab17-446d-9744-e247949913c1
	202	+version: 0
	203	+nbuckets: 106874
	204	+block_size: 1
	205	+bucket_size: 1024
	206	+nr_in_set: 1
	207	+nr_this_dev: 0
	208	+first_bucket: 1
	209	+[ 650.511912] bcache: run_cache_set() invalidating existing data
	210	+[ 650.549228] bcache: register_cache() registered cache device sdh2
	211	+
	212	+start backing device with missing cache:
	213	+host:/sys/block/md5/bcache# echo 1 > running
	214	+
	215	+attach new cache:
	216	+host:/sys/block/md5/bcache# echo 5bc072a8-ab17-446d-9744-e247949913c1 > attach
	217	+[ 865.276616] bcache: bch_cached_dev_attach() Caching md5 as bcache0 on set 5bc072a8-ab17-446d-9744-e247949913c1
	218	+
	219	+
	220	+F) Remove or replace a caching device
	221	+
	222	+ host:/sys/block/sda/sda7/bcache# echo 1 > detach
	223	+ [ 695.872542] bcache: cached_dev_detach_finish() Caching disabled for sda7
	224	+
	225	+ host:~# wipefs -a /dev/nvme0n1p4
	226	+ wipefs: error: /dev/nvme0n1p4: probing initialization failed: Device or resource busy
	227	+ Ooops, it's disabled, but not unregistered, so it's still protected
	228	+
	229	+We need to go and unregister it:
	230	+ host:/sys/fs/bcache/b7ba27a1-2398-4649-8ae3-0959f57ba128# ls -l cache0
	231	+ lrwxrwxrwx 1 root root 0 Feb 25 18:33 cache0 -> ../../../devices/pci0000:00/0000:00:1d.0/0000:70:00.0/nvme/nvme0/nvme0n1/nvme0n1p4/bcache/
	232	+ host:/sys/fs/bcache/b7ba27a1-2398-4649-8ae3-0959f57ba128# echo 1 > stop
	233	+ kernel: [ 917.041908] bcache: cache_set_free() Cache set b7ba27a1-2398-4649-8ae3-0959f57ba128 unregistered
	234	+
	235	+Now we can wipe it:
	236	+ host:~# wipefs -a /dev/nvme0n1p4
	237	+ /dev/nvme0n1p4: 16 bytes were erased at offset 0x00001018 (bcache): c6 85 73 f6 4e 1a 45 ca 82 65 f5 7f 48 ba 6d 81
	238	+
	239	+
	240	+G) dm-crypt and bcache
	241	+
	242	+First setup bcache unencrypted and then install dmcrypt on top of
	243	+/dev/bcache<N> This will work faster than if you dmcrypt both the backing
	244	+and caching devices and then install bcache on top. [benchmarks?]
	245	+
	246	+
	247	+H) Stop/free a registered bcache to wipe and/or recreate it
	248	+
	249	+Suppose that you need to free up all bcache references so that you can
	250	+fdisk run and re-register a changed partition table, which won't work
	251	+if there are any active backing or caching devices left on it:
	252	+
	253	+1) Is it present in /dev/bcache* ? (there are times where it won't be)
	254	+
	255	+If so, it's easy:
	256	+ host:/sys/block/bcache0/bcache# echo 1 > stop
	257	+
	258	+2) But if your backing device is gone, this won't work:
	259	+ host:/sys/block/bcache0# cd bcache
	260	+ bash: cd: bcache: No such file or directory
	261	+
	262	+In this case, you may have to unregister the dmcrypt block device that
	263	+references this bcache to free it up:
	264	+ host:~# dmsetup remove oldds1
	265	+ bcache: bcache_device_free() bcache0 stopped
	266	+ bcache: cache_set_free() Cache set 5bc072a8-ab17-446d-9744-e247949913c1 unregistered
	267	+
	268	+This causes the backing bcache to be removed from /sys/fs/bcache and
	269	+then it can be reused. This would be true of any block device stacking
	270	+where bcache is a lower device.
	271	+
	272	+3) In other cases, you can also look in /sys/fs/bcache/:
	273	+
	274	+host:/sys/fs/bcache# ls -l */{cache?,bdev?}
	275	+lrwxrwxrwx 1 root root 0 Mar 5 09:39 0226553a-37cf-41d5-b3ce-8b1e944543a8/bdev1 -> ../../../devices/virtual/block/dm-1/bcache/
	276	+lrwxrwxrwx 1 root root 0 Mar 5 09:39 0226553a-37cf-41d5-b3ce-8b1e944543a8/cache0 -> ../../../devices/virtual/block/dm-4/bcache/
	277	+lrwxrwxrwx 1 root root 0 Mar 5 09:39 5bc072a8-ab17-446d-9744-e247949913c1/cache0 -> ../../../devices/pci0000:00/0000:00:01.0/0000:01:00.0/ata10/host9/target9:0:0/9:0:0:0/block/sdl/sdl2/bcache/
	278	+
	279	+The device names will show which UUID is relevant, cd in that directory
	280	+and stop the cache:
	281	+ host:/sys/fs/bcache/5bc072a8-ab17-446d-9744-e247949913c1# echo 1 > stop
	282	+
	283	+This will free up bcache references and let you reuse the partition for
	284	+other purposes.
	285	+
	286	+
	287	+
	288	+TROUBLESHOOTING PERFORMANCE
	289	+---------------------------
131	290
132	291	Bcache has a bunch of config options and tunables. The defaults are intended to
133	292	be reasonable for typical desktop and server workloads, but they're not what you
134	293	want for getting the best possible numbers when benchmarking.
135	294
	295	+ - Backing device alignment
	296	+
	297	+ The default metadata size in bcache is 8k. If your backing device is
	298	+ RAID based, then be sure to align this by a multiple of your stride
	299	+ width using `make-bcache --data-offset`. If you intend to expand your
	300	+ disk array in the future, then multiply a series of primes by your
	301	+ raid stripe size to get the disk multiples that you would like.
	302	+
	303	+ For example: If you have a 64k stripe size, then the following offset
	304	+ would provide alignment for many common RAID5 data spindle counts:
	305	+ 64k * 2223357 bytes = 161280k
	306	+
	307	+ That space is wasted, but for only 157.5MB you can grow your RAID 5
	308	+ volume to the following data-spindle counts without re-aligning:
	309	+ 3,4,5,6,7,8,9,10,12,14,15,18,20,21 ...
	310	+
136	311	- Bad write performance
137	312
138	313	If write performance is not what you expected, you probably wanted to be
@@ -140,7 +315,7 @@ want for getting the best possible numbers when benchmarking. · 1 unmodified line
140	315	maturity, but simply because in writeback mode you'll lose data if something
141	316	happens to your SSD)
142	317
143		− # echo writeback > /sys/block/bcache0/cache_mode
	318	+ # echo writeback > /sys/block/bcache0/bcache/cache_mode
144	319
145	320	- Bad performance, or traffic not going to the SSD that you'd expect
146	321
@@ -193,7 +368,9 @@ want for getting the best possible numbers when benchmarking. · 46 unmodified lines
193	368	Solution: warm the cache by doing writes, or use the testing branch (there's
194	369	a fix for the issue there).
195	370
196		−SYSFS - BACKING DEVICE:
	371	+
	372	+SYSFS - BACKING DEVICE
	373	+----------------------
197	374
198	375	Available at /sys/block/<bdev>/bcache, /sys/block/bcache*/bcache and
199	376	(if attached) /sys/fs/bcache/<cset-uuid>/bdev*
@@ -238,7 +415,7 @@ sequential_merge · 38 unmodified lines
238	415	against all new requests to determine which new requests are sequential
239	416	continuations of previous requests for the purpose of determining sequential
240	417	cutoff. This is necessary if the sequential cutoff value is greater than the
241		− maximum acceptable sequential size for any single request.
	418	+ maximum acceptable sequential size for any single request.
242	419
243	420	state
244	421	The backing device can be in one of four different states:
@@ -325,7 +502,7 @@ bucket_size · 80 unmodified lines
325	502	Size of buckets
326	503
327	504	cache<0..n>
328		− Symlink to each of the cache devices comprising this cache set.
	505	+ Symlink to each of the cache devices comprising this cache set.
329	506
330	507	cache_available_percent
331	508	Percentage of cache device which doesn't contain dirty data, and could

Documentation/conf.py+414−0

@@ -0,0 +1,414 @@
	1	+# -- coding: utf-8 --
	2	+#
	3	+# The Linux Kernel documentation build configuration file, created by
	4	+# sphinx-quickstart on Fri Feb 12 13:51:46 2016.
	5	+#
	6	+# This file is execfile()d with the current directory set to its
	7	+# containing dir.
	8	+#
	9	+# Note that not all possible configuration values are present in this
	10	+# autogenerated file.
	11	+#
	12	+# All configuration values have a default; values that are commented out
	13	+# serve to show the default.
	14	+
	15	+import sys
	16	+import os
	17	+
	18	+# If extensions (or modules to document with autodoc) are in another directory,
	19	+# add these directories to sys.path here. If the directory is relative to the
	20	+# documentation root, use os.path.abspath to make it absolute, like shown here.
	21	+sys.path.insert(0, os.path.abspath('sphinx'))
	22	+
	23	+# -- General configuration ------------------------------------------------
	24	+
	25	+# If your documentation needs a minimal Sphinx version, state it here.
	26	+#needs_sphinx = '1.0'
	27	+
	28	+# Add any Sphinx extension module names here, as strings. They can be
	29	+# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
	30	+# ones.
	31	+extensions = ['kernel-doc', 'rstFlatTable']
	32	+
	33	+# Gracefully handle missing rst2pdf.
	34	+try:
	35	+ import rst2pdf
	36	+ extensions += ['rst2pdf.pdfbuilder']
	37	+except ImportError:
	38	+ pass
	39	+
	40	+# Add any paths that contain templates here, relative to this directory.
	41	+templates_path = ['_templates']
	42	+
	43	+# The suffix(es) of source filenames.
	44	+# You can specify multiple suffix as a list of string:
	45	+# source_suffix = ['.rst', '.md']
	46	+source_suffix = '.rst'
	47	+
	48	+# The encoding of source files.
	49	+#source_encoding = 'utf-8-sig'
	50	+
	51	+# The master toctree document.
	52	+master_doc = 'index'
	53	+
	54	+# General information about the project.
	55	+project = 'The Linux Kernel'
	56	+copyright = '2016, The kernel development community'
	57	+author = 'The kernel development community'
	58	+
	59	+# The version info for the project you're documenting, acts as replacement for
	60	+# \|version\| and \|release\|, also used in various other places throughout the
	61	+# built documents.
	62	+#
	63	+# In a normal build, version and release are are set to KERNELVERSION and
	64	+# KERNELRELEASE, respectively, from the Makefile via Sphinx command line
	65	+# arguments.
	66	+#
	67	+# The following code tries to extract the information by reading the Makefile,
	68	+# when Sphinx is run directly (e.g. by Read the Docs).
	69	+try:
	70	+ makefile_version = None
	71	+ makefile_patchlevel = None
	72	+ for line in open('../Makefile'):
	73	+ key, val = [x.strip() for x in line.split('=', 2)]
	74	+ if key == 'VERSION':
	75	+ makefile_version = val
	76	+ elif key == 'PATCHLEVEL':
	77	+ makefile_patchlevel = val
	78	+ if makefile_version and makefile_patchlevel:
	79	+ break
	80	+except:
	81	+ pass
	82	+finally:
	83	+ if makefile_version and makefile_patchlevel:
	84	+ version = release = makefile_version + '.' + makefile_patchlevel
	85	+ else:
	86	+ sys.stderr.write('Warning: Could not extract kernel version\n')
	87	+ version = release = "unknown version"
	88	+
	89	+# The language for content autogenerated by Sphinx. Refer to documentation
	90	+# for a list of supported languages.
	91	+#
	92	+# This is also used if you do content translation via gettext catalogs.
	93	+# Usually you set "language" from the command line for these cases.
	94	+language = None
	95	+
	96	+# There are two options for replacing \|today\|: either, you set today to some
	97	+# non-false value, then it is used:
	98	+#today = ''
	99	+# Else, today_fmt is used as the format for a strftime call.
	100	+#today_fmt = '%B %d, %Y'
	101	+
	102	+# List of patterns, relative to source directory, that match files and
	103	+# directories to ignore when looking for source files.
	104	+exclude_patterns = ['output']
	105	+
	106	+# The reST default role (used for this markup: `text`) to use for all
	107	+# documents.
	108	+#default_role = None
	109	+
	110	+# If true, '()' will be appended to :func: etc. cross-reference text.
	111	+#add_function_parentheses = True
	112	+
	113	+# If true, the current module name will be prepended to all description
	114	+# unit titles (such as .. function::).
	115	+#add_module_names = True
	116	+
	117	+# If true, sectionauthor and moduleauthor directives will be shown in the
	118	+# output. They are ignored by default.
	119	+#show_authors = False
	120	+
	121	+# The name of the Pygments (syntax highlighting) style to use.
	122	+pygments_style = 'sphinx'
	123	+
	124	+# A list of ignored prefixes for module index sorting.
	125	+#modindex_common_prefix = []
	126	+
	127	+# If true, keep warnings as "system message" paragraphs in the built documents.
	128	+#keep_warnings = False
	129	+
	130	+# If true, `todo` and `todoList` produce output, else they produce nothing.
	131	+todo_include_todos = False
	132	+
	133	+primary_domain = 'C'
	134	+highlight_language = 'C'
	135	+
	136	+# -- Options for HTML output ----------------------------------------------
	137	+
	138	+# The theme to use for HTML and HTML Help pages. See the documentation for
	139	+# a list of builtin themes.
	140	+
	141	+# The Read the Docs theme is available from
	142	+# - https://github.com/snide/sphinx_rtd_theme
	143	+# - https://pypi.python.org/pypi/sphinx_rtd_theme
	144	+# - python-sphinx-rtd-theme package (on Debian)
	145	+try:
	146	+ import sphinx_rtd_theme
	147	+ html_theme = 'sphinx_rtd_theme'
	148	+ html_theme_path = [sphinx_rtd_theme.get_html_theme_path()]
	149	+except ImportError:
	150	+ sys.stderr.write('Warning: The Sphinx \'sphinx_rtd_theme\' HTML theme was not found. Make sure you have the theme installed to produce pretty HTML output. Falling back to the default theme.\n')
	151	+
	152	+# Theme options are theme-specific and customize the look and feel of a theme
	153	+# further. For a list of options available for each theme, see the
	154	+# documentation.
	155	+#html_theme_options = {}
	156	+
	157	+# Add any paths that contain custom themes here, relative to this directory.
	158	+#html_theme_path = []
	159	+
	160	+# The name for this set of Sphinx documents. If None, it defaults to
	161	+# "<project> v<release> documentation".
	162	+#html_title = None
	163	+
	164	+# A shorter title for the navigation bar. Default is the same as html_title.
	165	+#html_short_title = None
	166	+
	167	+# The name of an image file (relative to this directory) to place at the top
	168	+# of the sidebar.
	169	+#html_logo = None
	170	+
	171	+# The name of an image file (within the static path) to use as favicon of the
	172	+# docs. This file should be a Windows icon file (.ico) being 16x16 or 32x32
	173	+# pixels large.
	174	+#html_favicon = None
	175	+
	176	+# Add any paths that contain custom static files (such as style sheets) here,
	177	+# relative to this directory. They are copied after the builtin static files,
	178	+# so a file named "default.css" will overwrite the builtin "default.css".
	179	+#html_static_path = ['_static']
	180	+
	181	+# Add any extra paths that contain custom files (such as robots.txt or
	182	+# .htaccess) here, relative to this directory. These files are copied
	183	+# directly to the root of the documentation.
	184	+#html_extra_path = []
	185	+
	186	+# If not '', a 'Last updated on:' timestamp is inserted at every page bottom,
	187	+# using the given strftime format.
	188	+#html_last_updated_fmt = '%b %d, %Y'
	189	+
	190	+# If true, SmartyPants will be used to convert quotes and dashes to
	191	+# typographically correct entities.
	192	+#html_use_smartypants = True
	193	+
	194	+# Custom sidebar templates, maps document names to template names.
	195	+#html_sidebars = {}
	196	+
	197	+# Additional templates that should be rendered to pages, maps page names to
	198	+# template names.
	199	+#html_additional_pages = {}
	200	+
	201	+# If false, no module index is generated.
	202	+#html_domain_indices = True
	203	+
	204	+# If false, no index is generated.
	205	+#html_use_index = True
	206	+
	207	+# If true, the index is split into individual pages for each letter.
	208	+#html_split_index = False
	209	+
	210	+# If true, links to the reST sources are added to the pages.
	211	+#html_show_sourcelink = True
	212	+
	213	+# If true, "Created using Sphinx" is shown in the HTML footer. Default is True.
	214	+#html_show_sphinx = True
	215	+
	216	+# If true, "(C) Copyright ..." is shown in the HTML footer. Default is True.
	217	+#html_show_copyright = True
	218	+
	219	+# If true, an OpenSearch description file will be output, and all pages will
	220	+# contain a <link> tag referring to it. The value of this option must be the
	221	+# base URL from which the finished HTML is served.
	222	+#html_use_opensearch = ''
	223	+
	224	+# This is the file name suffix for HTML files (e.g. ".xhtml").
	225	+#html_file_suffix = None
	226	+
	227	+# Language to be used for generating the HTML full-text search index.
	228	+# Sphinx supports the following languages:
	229	+# 'da', 'de', 'en', 'es', 'fi', 'fr', 'h', 'it', 'ja'
	230	+# 'nl', 'no', 'pt', 'ro', 'r', 'sv', 'tr'
	231	+#html_search_language = 'en'
	232	+
	233	+# A dictionary with options for the search language support, empty by default.
	234	+# Now only 'ja' uses this config value
	235	+#html_search_options = {'type': 'default'}
	236	+
	237	+# The name of a javascript file (relative to the configuration directory) that
	238	+# implements a search results scorer. If empty, the default will be used.
	239	+#html_search_scorer = 'scorer.js'
	240	+
	241	+# Output file base name for HTML help builder.
	242	+htmlhelp_basename = 'TheLinuxKerneldoc'
	243	+
	244	+# -- Options for LaTeX output ---------------------------------------------
	245	+
	246	+latex_elements = {
	247	+# The paper size ('letterpaper' or 'a4paper').
	248	+#'papersize': 'letterpaper',
	249	+
	250	+# The font size ('10pt', '11pt' or '12pt').
	251	+#'pointsize': '10pt',
	252	+
	253	+# Additional stuff for the LaTeX preamble.
	254	+#'preamble': '',
	255	+
	256	+# Latex figure (float) alignment
	257	+#'figure_align': 'htbp',
	258	+}
	259	+
	260	+# Grouping the document tree into LaTeX files. List of tuples
	261	+# (source start file, target name, title,
	262	+# author, documentclass [howto, manual, or own class]).
	263	+latex_documents = [
	264	+ (master_doc, 'TheLinuxKernel.tex', 'The Linux Kernel Documentation',
	265	+ 'The kernel development community', 'manual'),
	266	+]
	267	+
	268	+# The name of an image file (relative to this directory) to place at the top of
	269	+# the title page.
	270	+#latex_logo = None
	271	+
	272	+# For "manual" documents, if this is true, then toplevel headings are parts,
	273	+# not chapters.
	274	+#latex_use_parts = False
	275	+
	276	+# If true, show page references after internal links.
	277	+#latex_show_pagerefs = False
	278	+
	279	+# If true, show URL addresses after external links.
	280	+#latex_show_urls = False
	281	+
	282	+# Documents to append as an appendix to all manuals.
	283	+#latex_appendices = []
	284	+
	285	+# If false, no module index is generated.
	286	+#latex_domain_indices = True
	287	+
	288	+
	289	+# -- Options for manual page output ---------------------------------------
	290	+
	291	+# One entry per manual page. List of tuples
	292	+# (source start file, name, description, authors, manual section).
	293	+man_pages = [
	294	+ (master_doc, 'thelinuxkernel', 'The Linux Kernel Documentation',
	295	+ [author], 1)
	296	+]
	297	+
	298	+# If true, show URL addresses after external links.
	299	+#man_show_urls = False
	300	+
	301	+
	302	+# -- Options for Texinfo output -------------------------------------------
	303	+
	304	+# Grouping the document tree into Texinfo files. List of tuples
	305	+# (source start file, target name, title, author,
	306	+# dir menu entry, description, category)
	307	+texinfo_documents = [
	308	+ (master_doc, 'TheLinuxKernel', 'The Linux Kernel Documentation',
	309	+ author, 'TheLinuxKernel', 'One line description of project.',
	310	+ 'Miscellaneous'),
	311	+]
	312	+
	313	+# Documents to append as an appendix to all manuals.
	314	+#texinfo_appendices = []
	315	+
	316	+# If false, no module index is generated.
	317	+#texinfo_domain_indices = True
	318	+
	319	+# How to display URL addresses: 'footnote', 'no', or 'inline'.
	320	+#texinfo_show_urls = 'footnote'
	321	+
	322	+# If true, do not generate a @detailmenu in the "Top" node's menu.
	323	+#texinfo_no_detailmenu = False
	324	+
	325	+
	326	+# -- Options for Epub output ----------------------------------------------
	327	+
	328	+# Bibliographic Dublin Core info.
	329	+epub_title = project
	330	+epub_author = author
	331	+epub_publisher = author
	332	+epub_copyright = copyright
	333	+
	334	+# The basename for the epub file. It defaults to the project name.
	335	+#epub_basename = project
	336	+
	337	+# The HTML theme for the epub output. Since the default themes are not
	338	+# optimized for small screen space, using the same theme for HTML and epub
	339	+# output is usually not wise. This defaults to 'epub', a theme designed to save
	340	+# visual space.
	341	+#epub_theme = 'epub'
	342	+
	343	+# The language of the text. It defaults to the language option
	344	+# or 'en' if the language is not set.
	345	+#epub_language = ''
	346	+
	347	+# The scheme of the identifier. Typical schemes are ISBN or URL.
	348	+#epub_scheme = ''
	349	+
	350	+# The unique identifier of the text. This can be a ISBN number
	351	+# or the project homepage.
	352	+#epub_identifier = ''
	353	+
	354	+# A unique identification for the text.
	355	+#epub_uid = ''
	356	+
	357	+# A tuple containing the cover image and cover page html template filenames.
	358	+#epub_cover = ()
	359	+
	360	+# A sequence of (type, uri, title) tuples for the guide element of content.opf.
	361	+#epub_guide = ()
	362	+
	363	+# HTML files that should be inserted before the pages created by sphinx.
	364	+# The format is a list of tuples containing the path and title.
	365	+#epub_pre_files = []
	366	+
	367	+# HTML files that should be inserted after the pages created by sphinx.
	368	+# The format is a list of tuples containing the path and title.
	369	+#epub_post_files = []
	370	+
	371	+# A list of files that should not be packed into the epub file.
	372	+epub_exclude_files = ['search.html']
	373	+
	374	+# The depth of the table of contents in toc.ncx.
	375	+#epub_tocdepth = 3
	376	+
	377	+# Allow duplicate toc entries.
	378	+#epub_tocdup = True
	379	+
	380	+# Choose between 'default' and 'includehidden'.
	381	+#epub_tocscope = 'default'
	382	+
	383	+# Fix unsupported image types using the Pillow.
	384	+#epub_fix_images = False
	385	+
	386	+# Scale large images.
	387	+#epub_max_image_width = 0
	388	+
	389	+# How to display URL addresses: 'footnote', 'no', or 'inline'.
	390	+#epub_show_urls = 'inline'
	391	+
	392	+# If false, no index is generated.
	393	+#epub_use_index = True
	394	+
	395	+#=======
	396	+# rst2pdf
	397	+#
	398	+# Grouping the document tree into PDF files. List of tuples
	399	+# (source start file, target name, title, author, options).
	400	+#
	401	+# See the Sphinx chapter of http://ralsina.me/static/manual.pdf
	402	+#
	403	+# FIXME: Do not add the index file here; the result will be too big. Adding
	404	+# multiple PDF files here actually tries to get the cross-referencing right
	405	+# between PDF files.
	406	+pdf_documents = [
	407	+ ('index', u'Kernel', u'Kernel', u'J. Random Bozo'),
	408	+]
	409	+
	410	+# kernel-doc extension configuration for running Sphinx directly (e.g. by Read
	411	+# the Docs). In a normal build, these are supplied from the Makefile via command
	412	+# line arguments.
	413	+kerneldoc_bin = '../scripts/kernel-doc'
	414	+kerneldoc_srctree = '..'

Documentation/development-process/4.Coding+1−1

@@ -346,7 +346,7 @@ which have not been so documented, there is no harm in adding kerneldoc · 345 unmodified lines
346	346	comments for the future; indeed, this can be a useful activity for
347	347	beginning kernel developers. The format of these comments, along with some
348	348	information on how to create kerneldoc templates can be found in the file
349		−Documentation/kernel-doc-nano-HOWTO.txt.
	349	+Documentation/kernel-documentation.rst.
350	350
351	351	Anybody who reads through a significant amount of existing kernel code will
352	352	note that, often, comments are most notable by their absence. Once again,

Documentation/dmaengine/provider.txt+1−1

@@ -323,7 +323,7 @@ supported. · 322 unmodified lines
323	323	* device_resume
324	324	- Resumes a transfer on the channel
325	325	- This command should operate synchronously on the channel,
326		− pausing right away the work of the given channel
	326	+ resuming right away the work of the given channel
327	327
328	328	* device_terminate_all
329	329	- Aborts all the pending and ongoing transfers on the channel

Documentation/filesystems/ocfs2-online-filecheck.txt+5−5

@@ -5,12 +5,12 @@ This document will describe OCFS2 online file check feature. · 4 unmodified lines
5	5
6	6	Introduction
7	7	============
8		−OCFS2 is often used in high-availaibility systems. However, OCFS2 usually
	8	+OCFS2 is often used in high-availability systems. However, OCFS2 usually
9	9	converts the filesystem to read-only when encounters an error. This may not be
10	10	necessary, since turning the filesystem read-only would affect other running
11	11	processes as well, decreasing availability.
12	12	Then, a mount option (errors=continue) is introduced, which would return the
13		−-EIO errno to the calling process and terminate furhter processing so that the
	13	+-EIO errno to the calling process and terminate further processing so that the
14	14	filesystem is not corrupted further. The filesystem is not converted to
15	15	read-only, and the problematic file's inode number is reported in the kernel
16	16	log. The user can try to check/fix this file via online filecheck feature.
@@ -44,7 +44,7 @@ There is a sysfs directory for each OCFS2 file system mounting: · 27 unmodified lines
44	44
45	45	/sys/fs/ocfs2/<devname>/filecheck
46	46
47		−Here, <devname> indicates the name of OCFS2 volumn device which has been already
	47	+Here, <devname> indicates the name of OCFS2 volume device which has been already
48	48	mounted. The file above would accept inode numbers. This could be used to
49	49	communicate with kernel space, tell which file(inode number) will be checked or
50	50	fixed. Currently, three operations are supported, which includes checking
@@ -76,14 +76,14 @@ The output is like this: · 25 unmodified lines
76	76	This time, the <ERROR> column indicates whether this fix is successful or not.
77	77
78	78	3. The record cache is used to store the history of check/fix results. It's
79		−defalut size is 10, and can be adjust between the range of 10 ~ 100. You can
	79	+default size is 10, and can be adjust between the range of 10 ~ 100. You can
80	80	adjust the size like this:
81	81
82	82	# echo "<size>" > /sys/fs/ocfs2/<devname>/filecheck/set
83	83
84	84	Fixing stuff
85	85	============
86		−On receivng the inode, the filesystem would read the inode and the
	86	+On receiving the inode, the filesystem would read the inode and the
87	87	file metadata. In case of errors, the filesystem would fix the errors
88	88	and report the problems it fixed in the kernel log. As a precautionary measure,
89	89	the inode must first be checked for errors before performing a final fix.

Documentation/index.rst+22−0

@@ -0,0 +1,22 @@
	1	+.. The Linux Kernel documentation master file, created by
	2	+ sphinx-quickstart on Fri Feb 12 13:51:46 2016.
	3	+ You can adapt this file completely to your liking, but it should at least
	4	+ contain the root `toctree` directive.
	5	+
	6	+Welcome to The Linux Kernel's documentation!
	7	+============================================
	8	+
	9	+Nothing for you to see here yet. Please move along.
	10	+
	11	+Contents:
	12	+
	13	+.. toctree::
	14	+ :maxdepth: 2
	15	+
	16	+ kernel-documentation
	17	+
	18	+Indices and tables
	19	+==================
	20	+
	21	+* :ref:`genindex`
	22	+* :ref:`search`

Documentation/kernel-doc-nano-HOWTO.txt+3−0

@@ -1,3 +1,6 @@
	1	+NOTE: this document is outdated and will eventually be removed. See
	2	+Documentation/kernel-documentation.rst for current information.
	3	+
1	4	kernel-doc nano-HOWTO
2	5	=====================
3	6

Documentation/kernel-documentation.rst+654−0

@@ -0,0 +1,654 @@
	1	+==========================
	2	+Linux Kernel Documentation
	3	+==========================
	4	+
	5	+Introduction
	6	+============
	7	+
	8	+The Linux kernel uses `Sphinx`_ to generate pretty documentation from
	9	+`reStructuredText`_ files under ``Documentation``. To build the documentation in
	10	+HTML or PDF formats, use ``make htmldocs`` or ``make pdfdocs``. The generated
	11	+documentation is placed in ``Documentation/output``.
	12	+
	13	+.. _Sphinx: http://www.sphinx-doc.org/
	14	+.. _reStructuredText: http://docutils.sourceforge.net/rst.html
	15	+
	16	+The reStructuredText files may contain directives to include structured
	17	+documentation comments, or kernel-doc comments, from source files. Usually these
	18	+are used to describe the functions and types and design of the code. The
	19	+kernel-doc comments have some special structure and formatting, but beyond that
	20	+they are also treated as reStructuredText.
	21	+
	22	+There is also the deprecated DocBook toolchain to generate documentation from
	23	+DocBook XML template files under ``Documentation/DocBook``. The DocBook files
	24	+are to be converted to reStructuredText, and the toolchain is slated to be
	25	+removed.
	26	+
	27	+Finally, there are thousands of plain text documentation files scattered around
	28	+``Documentation``. Some of these will likely be converted to reStructuredText
	29	+over time, but the bulk of them will remain in plain text.
	30	+
	31	+Sphinx Build
	32	+============
	33	+
	34	+The usual way to generate the documentation is to run ``make htmldocs`` or
	35	+``make pdfdocs``. There are also other formats available, see the documentation
	36	+section of ``make help``. The generated documentation is placed in
	37	+format-specific subdirectories under ``Documentation/output``.
	38	+
	39	+To generate documentation, Sphinx (``sphinx-build``) must obviously be
	40	+installed. For prettier HTML output, the Read the Docs Sphinx theme
	41	+(``sphinx_rtd_theme``) is used if available. For PDF output, ``rst2pdf`` is also
	42	+needed. All of these are widely available and packaged in distributions.
	43	+
	44	+To pass extra options to Sphinx, you can use the ``SPHINXOPTS`` make
	45	+variable. For example, use ``make SPHINXOPTS=-v htmldocs`` to get more verbose
	46	+output.
	47	+
	48	+To remove the generated documentation, run ``make cleandocs``.
	49	+
	50	+Writing Documentation
	51	+=====================
	52	+
	53	+Adding new documentation can be as simple as:
	54	+
	55	+1. Add a new ``.rst`` file somewhere under ``Documentation``.
	56	+2. Refer to it from the Sphinx main `TOC tree`_ in ``Documentation/index.rst``.
	57	+
	58	+.. _TOC tree: http://www.sphinx-doc.org/en/stable/markup/toctree.html
	59	+
	60	+This is usually good enough for simple documentation (like the one you're
	61	+reading right now), but for larger documents it may be advisable to create a
	62	+subdirectory (or use an existing one). For example, the graphics subsystem
	63	+documentation is under ``Documentation/gpu``, split to several ``.rst`` files,
	64	+and has a separate ``index.rst`` (with a ``toctree`` of its own) referenced from
	65	+the main index.
	66	+
	67	+See the documentation for `Sphinx`_ and `reStructuredText`_ on what you can do
	68	+with them. In particular, the Sphinx `reStructuredText Primer`_ is a good place
	69	+to get started with reStructuredText. There are also some `Sphinx specific
	70	+markup constructs`_.
	71	+
	72	+.. _reStructuredText Primer: http://www.sphinx-doc.org/en/stable/rest.html
	73	+.. _Sphinx specific markup constructs: http://www.sphinx-doc.org/en/stable/markup/index.html
	74	+
	75	+Specific guidelines for the kernel documentation
	76	+------------------------------------------------
	77	+
	78	+Here are some specific guidelines for the kernel documentation:
	79	+
	80	+* Please don't go overboard with reStructuredText markup. Keep it simple.
	81	+
	82	+* Please stick to this order of heading adornments:
	83	+
	84	+ 1. ``=`` with overline for document title::
	85	+
	86	+ ==============
	87	+ Document title
	88	+ ==============
	89	+
	90	+ 2. ``=`` for chapters::
	91	+
	92	+ Chapters
	93	+ ========
	94	+
	95	+ 3. ``-`` for sections::
	96	+
	97	+ Section
	98	+ -------
	99	+
	100	+ 4. ``~`` for subsections::
	101	+
	102	+ Subsection
	103	+ ~~~~~~~~~~
	104	+
	105	+ Although RST doesn't mandate a specific order ("Rather than imposing a fixed
	106	+ number and order of section title adornment styles, the order enforced will be
	107	+ the order as encountered."), having the higher levels the same overall makes
	108	+ it easier to follow the documents.
	109	+
	110	+list tables
	111	+-----------
	112	+
	113	+We recommend the use of list table formats. The list table formats are
	114	+double-stage lists. Compared to the ASCII-art they might not be as
	115	+comfortable for
	116	+readers of the text files. Their advantage is that they are easy to
	117	+create or modify and that the diff of a modification is much more meaningful,
	118	+because it is limited to the modified content.
	119	+
	120	+The ``flat-table`` is a double-stage list similar to the ``list-table`` with
	121	+some additional features:
	122	+
	123	+* column-span: with the role ``cspan`` a cell can be extended through
	124	+ additional columns
	125	+
	126	+* row-span: with the role ``rspan`` a cell can be extended through
	127	+ additional rows
	128	+
	129	+* auto span rightmost cell of a table row over the missing cells on the right
	130	+ side of that table-row. With Option ``:fill-cells:`` this behavior can
	131	+ changed from auto span to auto fill, which automatically inserts (empty)
	132	+ cells instead of spanning the last cell.
	133	+
	134	+options:
	135	+
	136	+* ``:header-rows:`` [int] count of header rows
	137	+* ``:stub-columns:`` [int] count of stub columns
	138	+* ``:widths:`` [[int] [int] ... ] widths of columns
	139	+* ``:fill-cells:`` instead of auto-spanning missing cells, insert missing cells
	140	+
	141	+roles:
	142	+
	143	+* ``:cspan:`` [int] additional columns (morecols)
	144	+* ``:rspan:`` [int] additional rows (morerows)
	145	+
	146	+The example below shows how to use this markup. The first level of the staged
	147	+list is the table-row. In the table-row there is only one markup allowed,
	148	+the list of the cells in this table-row. Exceptions are comments ( ``..`` )
	149	+and targets (e.g. a ref to ``:ref:`last row <last row>``` / :ref:`last row
	150	+<last row>`).
	151	+
	152	+.. code-block:: rst
	153	+
	154	+ .. flat-table:: table title
	155	+ :widths: 2 1 1 3
	156	+
	157	+ * - head col 1
	158	+ - head col 2
	159	+ - head col 3
	160	+ - head col 4
	161	+
	162	+ * - column 1
	163	+ - field 1.1
	164	+ - field 1.2 with autospan
	165	+
	166	+ * - column 2
	167	+ - field 2.1
	168	+ - :rspan:`1` :cspan:`1` field 2.2 - 3.3
	169	+
	170	+ * .. _`last row`:
	171	+
	172	+ - column 3
	173	+
	174	+Rendered as:
	175	+
	176	+ .. flat-table:: table title
	177	+ :widths: 2 1 1 3
	178	+
	179	+ * - head col 1
	180	+ - head col 2
	181	+ - head col 3
	182	+ - head col 4
	183	+
	184	+ * - column 1
	185	+ - field 1.1
	186	+ - field 1.2 with autospan
	187	+
	188	+ * - column 2
	189	+ - field 2.1
	190	+ - :rspan:`1` :cspan:`1` field 2.2 - 3.3
	191	+
	192	+ * .. _`last row`:
	193	+
	194	+ - column 3
	195	+
	196	+
	197	+Including kernel-doc comments
	198	+=============================
	199	+
	200	+The Linux kernel source files may contain structured documentation comments, or
	201	+kernel-doc comments to describe the functions and types and design of the
	202	+code. The documentation comments may be included to any of the reStructuredText
	203	+documents using a dedicated kernel-doc Sphinx directive extension.
	204	+
	205	+The kernel-doc directive is of the format::
	206	+
	207	+ .. kernel-doc:: source
	208	+ :option:
	209	+
	210	+The source is the path to a source file, relative to the kernel source
	211	+tree. The following directive options are supported:
	212	+
	213	+export: [source-pattern ...]
	214	+ Include documentation for all functions in source that have been exported
	215	+ using ``EXPORT_SYMBOL`` or ``EXPORT_SYMBOL_GPL`` either in source or in any
	216	+ of the files specified by source-pattern.
	217	+
	218	+ The source-pattern is useful when the kernel-doc comments have been placed
	219	+ in header files, while ``EXPORT_SYMBOL`` and ``EXPORT_SYMBOL_GPL`` are next to
	220	+ the function definitions.
	221	+
	222	+ Examples::
	223	+
	224	+ .. kernel-doc:: lib/bitmap.c
	225	+ :export:
	226	+
	227	+ .. kernel-doc:: include/net/mac80211.h
	228	+ :export: net/mac80211/*.c
	229	+
	230	+internal: [source-pattern ...]
	231	+ Include documentation for all functions and types in source that have
	232	+ not been exported using ``EXPORT_SYMBOL`` or ``EXPORT_SYMBOL_GPL`` either
	233	+ in source or in any of the files specified by source-pattern.
	234	+
	235	+ Example::
	236	+
	237	+ .. kernel-doc:: drivers/gpu/drm/i915/intel_audio.c
	238	+ :internal:
	239	+
	240	+doc: title
	241	+ Include documentation for the ``DOC:`` paragraph identified by title in
	242	+ source. Spaces are allowed in title; do not quote the title. The title
	243	+ is only used as an identifier for the paragraph, and is not included in the
	244	+ output. Please make sure to have an appropriate heading in the enclosing
	245	+ reStructuredText document.
	246	+
	247	+ Example::
	248	+
	249	+ .. kernel-doc:: drivers/gpu/drm/i915/intel_audio.c
	250	+ :doc: High Definition Audio over HDMI and Display Port
	251	+
	252	+functions: function [...]
	253	+ Include documentation for each function in source.
	254	+
	255	+ Example::
	256	+
	257	+ .. kernel-doc:: lib/bitmap.c
	258	+ :functions: bitmap_parselist bitmap_parselist_user
	259	+
	260	+Without options, the kernel-doc directive includes all documentation comments
	261	+from the source file.
	262	+
	263	+The kernel-doc extension is included in the kernel source tree, at
	264	+``Documentation/sphinx/kernel-doc.py``. Internally, it uses the
	265	+``scripts/kernel-doc`` script to extract the documentation comments from the
	266	+source.
	267	+
	268	+Writing kernel-doc comments
	269	+===========================
	270	+
	271	+In order to provide embedded, "C" friendly, easy to maintain, but consistent and
	272	+extractable overview, function and type documentation, the Linux kernel has
	273	+adopted a consistent style for documentation comments. The format for this
	274	+documentation is called the kernel-doc format, described below. This style
	275	+embeds the documentation within the source files, using a few simple conventions
	276	+for adding documentation paragraphs and documenting functions and their
	277	+parameters, structures and unions and their members, enumerations, and typedefs.
	278	+
	279	+.. note:: The kernel-doc format is deceptively similar to gtk-doc or Doxygen,
	280	+ yet distinctively different, for historical reasons. The kernel source
	281	+ contains tens of thousands of kernel-doc comments. Please stick to the style
	282	+ described here.
	283	+
	284	+The ``scripts/kernel-doc`` script is used by the Sphinx kernel-doc extension in
	285	+the documentation build to extract this embedded documentation into the various
	286	+HTML, PDF, and other format documents.
	287	+
	288	+In order to provide good documentation of kernel functions and data structures,
	289	+please use the following conventions to format your kernel-doc comments in the
	290	+Linux kernel source.
	291	+
	292	+How to format kernel-doc comments
	293	+---------------------------------
	294	+
	295	+The opening comment mark ``/**`` is reserved for kernel-doc comments. Only
	296	+comments so marked will be considered by the ``kernel-doc`` tool. Use it only
	297	+for comment blocks that contain kernel-doc formatted comments. The usual ``*/``
	298	+should be used as the closing comment marker. The lines in between should be
	299	+prefixed by `` * `` (space star space).
	300	+
	301	+The function and type kernel-doc comments should be placed just before the
	302	+function or type being described. The overview kernel-doc comments may be freely
	303	+placed at the top indentation level.
	304	+
	305	+Example kernel-doc function comment::
	306	+
	307	+ /**
	308	+ * foobar() - Brief description of foobar.
	309	+ * @arg: Description of argument of foobar.
	310	+ *
	311	+ * Longer description of foobar.
	312	+ *
	313	+ * Return: Description of return value of foobar.
	314	+ */
	315	+ int foobar(int arg)
	316	+
	317	+The format is similar for documentation for structures, enums, paragraphs,
	318	+etc. See the sections below for details.
	319	+
	320	+The kernel-doc structure is extracted from the comments, and proper `Sphinx C
	321	+Domain`_ function and type descriptions with anchors are generated for them. The
	322	+descriptions are filtered for special kernel-doc highlights and
	323	+cross-references. See below for details.
	324	+
	325	+.. _Sphinx C Domain: http://www.sphinx-doc.org/en/stable/domains.html
	326	+
	327	+Highlights and cross-references
	328	+-------------------------------
	329	+
	330	+The following special patterns are recognized in the kernel-doc comment
	331	+descriptive text and converted to proper reStructuredText markup and `Sphinx C
	332	+Domain`_ references.
	333	+
	334	+.. attention:: The below are only recognized within kernel-doc comments,
	335	+ not within normal reStructuredText documents.
	336	+
	337	+``funcname()``
	338	+ Function reference.
	339	+
	340	+``@parameter``
	341	+ Name of a function parameter. (No cross-referencing, just formatting.)
	342	+
	343	+``%CONST``
	344	+ Name of a constant. (No cross-referencing, just formatting.)
	345	+
	346	+``$ENVVAR``
	347	+ Name of an environment variable. (No cross-referencing, just formatting.)
	348	+
	349	+``&struct name``
	350	+ Structure reference.
	351	+
	352	+``&enum name``
	353	+ Enum reference.
	354	+
	355	+``&typedef name``
	356	+ Typedef reference.
	357	+
	358	+``&struct_name->member`` or ``&struct_name.member``
	359	+ Structure or union member reference. The cross-reference will be to the struct
	360	+ or union definition, not the member directly.
	361	+
	362	+``&name``
	363	+ A generic type reference. Prefer using the full reference described above
	364	+ instead. This is mostly for legacy comments.
	365	+
	366	+Cross-referencing from reStructuredText
	367	+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
	368	+
	369	+.. highlight:: none
	370	+
	371	+To cross-reference the functions and types defined in the kernel-doc comments
	372	+from reStructuredText documents, please use the `Sphinx C Domain`_
	373	+references. For example::
	374	+
	375	+ See function :c:func:`foo` and struct/union/enum/typedef :c:type:`bar`.
	376	+
	377	+While the type reference works with just the type name, without the
	378	+struct/union/enum/typedef part in front, you may want to use::
	379	+
	380	+ See :c:type:`struct foo <foo>`.
	381	+ See :c:type:`union bar <bar>`.
	382	+ See :c:type:`enum baz <baz>`.
	383	+ See :c:type:`typedef meh <meh>`.
	384	+
	385	+This will produce prettier links, and is in line with how kernel-doc does the
	386	+cross-references.
	387	+
	388	+For further details, please refer to the `Sphinx C Domain`_ documentation.
	389	+
	390	+Function documentation
	391	+----------------------
	392	+
	393	+.. highlight:: c
	394	+
	395	+The general format of a function and function-like macro kernel-doc comment is::
	396	+
	397	+ /**
	398	+ * function_name() - Brief description of function.
	399	+ * @arg1: Describe the first argument.
	400	+ * @arg2: Describe the second argument.
	401	+ * One can provide multiple line descriptions
	402	+ * for arguments.
	403	+ *
	404	+ * A longer description, with more discussion of the function function_name()
	405	+ * that might be useful to those using or modifying it. Begins with an
	406	+ * empty comment line, and may include additional embedded empty
	407	+ * comment lines.
	408	+ *
	409	+ * The longer description may have multiple paragraphs.
	410	+ *
	411	+ * Return: Describe the return value of foobar.
	412	+ *
	413	+ * The return value description can also have multiple paragraphs, and should
	414	+ * be placed at the end of the comment block.
	415	+ */
	416	+
	417	+The brief description following the function name may span multiple lines, and
	418	+ends with an ``@argument:`` description, a blank comment line, or the end of the
	419	+comment block.
	420	+
	421	+The kernel-doc function comments describe each parameter to the function, in
	422	+order, with the ``@argument:`` descriptions. The ``@argument:`` descriptions
	423	+must begin on the very next line following the opening brief function
	424	+description line, with no intervening blank comment lines. The ``@argument:``
	425	+descriptions may span multiple lines. The continuation lines may contain
	426	+indentation. If a function parameter is ``...`` (varargs), it should be listed
	427	+in kernel-doc notation as: ``@...:``.
	428	+
	429	+The return value, if any, should be described in a dedicated section at the end
	430	+of the comment starting with "Return:".
	431	+
	432	+Structure, union, and enumeration documentation
	433	+-----------------------------------------------
	434	+
	435	+The general format of a struct, union, and enum kernel-doc comment is::
	436	+
	437	+ /**
	438	+ * struct struct_name - Brief description.
	439	+ * @member_name: Description of member member_name.
	440	+ *
	441	+ * Description of the structure.
	442	+ */
	443	+
	444	+Below, "struct" is used to mean structs, unions and enums, and "member" is used
	445	+to mean struct and union members as well as enumerations in an enum.
	446	+
	447	+The brief description following the structure name may span multiple lines, and
	448	+ends with a ``@member:`` description, a blank comment line, or the end of the
	449	+comment block.
	450	+
	451	+The kernel-doc data structure comments describe each member of the structure, in
	452	+order, with the ``@member:`` descriptions. The ``@member:`` descriptions must
	453	+begin on the very next line following the opening brief function description
	454	+line, with no intervening blank comment lines. The ``@member:`` descriptions may
	455	+span multiple lines. The continuation lines may contain indentation.
	456	+
	457	+In-line member documentation comments
	458	+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
	459	+
	460	+The structure members may also be documented in-line within the definition::
	461	+
	462	+ /**
	463	+ * struct foo - Brief description.
	464	+ * @foo: The Foo member.
	465	+ */
	466	+ struct foo {
	467	+ int foo;
	468	+ /**
	469	+ * @bar: The Bar member.
	470	+ */
	471	+ int bar;
	472	+ /**
	473	+ * @baz: The Baz member.
	474	+ *
	475	+ * Here, the member description may contain several paragraphs.
	476	+ */
	477	+ int baz;
	478	+ }
	479	+
	480	+Private members
	481	+~~~~~~~~~~~~~~~
	482	+
	483	+Inside a struct description, you can use the "private:" and "public:" comment
	484	+tags. Structure fields that are inside a "private:" area are not listed in the
	485	+generated output documentation. The "private:" and "public:" tags must begin
	486	+immediately following a ``/*`` comment marker. They may optionally include
	487	+comments between the ``:`` and the ending ``*/`` marker.
	488	+
	489	+Example::
	490	+
	491	+ /**
	492	+ * struct my_struct - short description
	493	+ * @a: first member
	494	+ * @b: second member
	495	+ *
	496	+ * Longer description
	497	+ */
	498	+ struct my_struct {
	499	+ int a;
	500	+ int b;
	501	+ /* private: internal use only */
	502	+ int c;
	503	+ };
	504	+
	505	+
	506	+Typedef documentation
	507	+---------------------
	508	+
	509	+The general format of a typedef kernel-doc comment is::
	510	+
	511	+ /**
	512	+ * typedef type_name - Brief description.
	513	+ *
	514	+ * Description of the type.
	515	+ */
	516	+
	517	+Overview documentation comments
	518	+-------------------------------
	519	+
	520	+To facilitate having source code and comments close together, you can include
	521	+kernel-doc documentation blocks that are free-form comments instead of being
	522	+kernel-doc for functions, structures, unions, enums, or typedefs. This could be
	523	+used for something like a theory of operation for a driver or library code, for
	524	+example.
	525	+
	526	+This is done by using a ``DOC:`` section keyword with a section title.
	527	+
	528	+The general format of an overview or high-level documentation comment is::
	529	+
	530	+ /**
	531	+ * DOC: Theory of Operation
	532	+ *
	533	+ * The whizbang foobar is a dilly of a gizmo. It can do whatever you
	534	+ * want it to do, at any time. It reads your mind. Here's how it works.
	535	+ *
	536	+ * foo bar splat
	537	+ *
	538	+ * The only drawback to this gizmo is that is can sometimes damage
	539	+ * hardware, software, or its subject(s).
	540	+ */
	541	+
	542	+The title following ``DOC:`` acts as a heading within the source file, but also
	543	+as an identifier for extracting the documentation comment. Thus, the title must
	544	+be unique within the file.
	545	+
	546	+Recommendations
	547	+---------------
	548	+
	549	+We definitely need kernel-doc formatted documentation for functions that are
	550	+exported to loadable modules using ``EXPORT_SYMBOL`` or ``EXPORT_SYMBOL_GPL``.
	551	+
	552	+We also look to provide kernel-doc formatted documentation for functions
	553	+externally visible to other kernel files (not marked "static").
	554	+
	555	+We also recommend providing kernel-doc formatted documentation for private (file
	556	+"static") routines, for consistency of kernel source code layout. But this is
	557	+lower priority and at the discretion of the MAINTAINER of that kernel source
	558	+file.
	559	+
	560	+Data structures visible in kernel include files should also be documented using
	561	+kernel-doc formatted comments.
	562	+
	563	+DocBook XML [DEPRECATED]
	564	+========================
	565	+
	566	+.. attention::
	567	+
	568	+ This section describes the deprecated DocBook XML toolchain. Please do not
	569	+ create new DocBook XML template files. Please consider converting existing
	570	+ DocBook XML templates files to Sphinx/reStructuredText.
	571	+
	572	+Converting DocBook to Sphinx
	573	+----------------------------
	574	+
	575	+.. highlight:: none
	576	+
	577	+Over time, we expect all of the documents under ``Documentation/DocBook`` to be
	578	+converted to Sphinx and reStructuredText. For most DocBook XML documents, a good
	579	+enough solution is to use the simple ``Documentation/sphinx/tmplcvt`` script,
	580	+which uses ``pandoc`` under the hood. For example::
	581	+
	582	+ $ cd Documentation/sphinx
	583	+ $ ./tmplcvt ../DocBook/in.tmpl ../out.rst
	584	+
	585	+Then edit the resulting rst files to fix any remaining issues, and add the
	586	+document in the ``toctree`` in ``Documentation/index.rst``.
	587	+
	588	+Components of the kernel-doc system
	589	+-----------------------------------
	590	+
	591	+Many places in the source tree have extractable documentation in the form of
	592	+block comments above functions. The components of this system are:
	593	+
	594	+- ``scripts/kernel-doc``
	595	+
	596	+ This is a perl script that hunts for the block comments and can mark them up
	597	+ directly into reStructuredText, DocBook, man, text, and HTML. (No, not
	598	+ texinfo.)
	599	+
	600	+- ``Documentation/DocBook/*.tmpl``
	601	+
	602	+ These are XML template files, which are normal XML files with special
	603	+ place-holders for where the extracted documentation should go.
	604	+
	605	+- ``scripts/docproc.c``
	606	+
	607	+ This is a program for converting XML template files into XML files. When a
	608	+ file is referenced it is searched for symbols exported (EXPORT_SYMBOL), to be
	609	+ able to distinguish between internal and external functions.
	610	+
	611	+ It invokes kernel-doc, giving it the list of functions that are to be
	612	+ documented.
	613	+
	614	+ Additionally it is used to scan the XML template files to locate all the files
	615	+ referenced herein. This is used to generate dependency information as used by
	616	+ make.
	617	+
	618	+- ``Makefile``
	619	+
	620	+ The targets 'xmldocs', 'psdocs', 'pdfdocs', and 'htmldocs' are used to build
	621	+ DocBook XML files, PostScript files, PDF files, and html files in
	622	+ Documentation/DocBook. The older target 'sgmldocs' is equivalent to 'xmldocs'.
	623	+
	624	+- ``Documentation/DocBook/Makefile``
	625	+
	626	+ This is where C files are associated with SGML templates.
	627	+
	628	+How to use kernel-doc comments in DocBook XML template files
	629	+------------------------------------------------------------
	630	+
	631	+DocBook XML template files (\*.tmpl) are like normal XML files, except that they
	632	+can contain escape sequences where extracted documentation should be inserted.
	633	+
	634	+``!E<filename>`` is replaced by the documentation, in ``<filename>``, for
	635	+functions that are exported using ``EXPORT_SYMBOL``: the function list is
	636	+collected from files listed in ``Documentation/DocBook/Makefile``.
	637	+
	638	+``!I<filename>`` is replaced by the documentation for functions that are not
	639	+exported using ``EXPORT_SYMBOL``.
	640	+
	641	+``!D<filename>`` is used to name additional files to search for functions
	642	+exported using ``EXPORT_SYMBOL``.
	643	+
	644	+``!F<filename> <function [functions...]>`` is replaced by the documentation, in
	645	+``<filename>``, for the functions listed.
	646	+
	647	+``!P<filename> <section title>`` is replaced by the contents of the ``DOC:``
	648	+section titled ``<section title>`` from ``<filename>``. Spaces are allowed in
	649	+``<section title>``; do not quote the ``<section title>``.
	650	+
	651	+``!C<filename>`` is replaced by nothing, but makes the tools check that all DOC:
	652	+sections and documented functions, symbols, etc. are used. This makes sense to
	653	+use when you use ``!F`` or ``!P`` only and want to verify that all documentation
	654	+is included.

Documentation/kernel-parameters.txt+3−2

@@ -3996,8 +3996,9 @@ bytes respectively. Such letter suffixes can also be entirely omitted. · 3995 unmodified lines
3996	3996
3997	3997	trace_event=[event-list]
3998	3998	[FTRACE] Set and start specified trace events in order
3999		− to facilitate early boot debugging.
4000		− See also Documentation/trace/events.txt
	3999	+ to facilitate early boot debugging. The event-list is a
	4000	+ comma separated list of trace events to enable. See
	4001	+ also Documentation/trace/events.txt
4001	4002
4002	4003	trace_options=[option-list]
4003	4004	[FTRACE] Enable or disable tracer options at boot.

Documentation/md.txt+1−1

@@ -602,7 +602,7 @@ These currently include · 601 unmodified lines
602	602
603	603	stripe_cache_size (currently raid5 only)
604	604	number of entries in the stripe cache. This is writable, but
605		− there are upper and lower limits (32768, 16). Default is 128.
	605	+ there are upper and lower limits (32768, 17). Default is 256.
606	606	strip_cache_active (currently raid5 only)
607	607	number of active entries in the stripe cache
608	608	preread_bypass_threshold (currently raid5 only)

Documentation/mic/mpssd/mpssd.c+2−2

@@ -1538,9 +1538,9 @@ set_cmdline(struct mic_info *mic) · 1537 unmodified lines
1538	1538
1539	1539	len = snprintf(buffer, PATH_MAX,
1540	1540	"clocksource=tsc highres=off nohz=off ");
1541		− len += snprintf(buffer + len, PATH_MAX,
	1541	+ len += snprintf(buffer + len, PATH_MAX - len,
1542	1542	"cpufreq_on;corec6_off;pc3_off;pc6_off ");
1543		− len += snprintf(buffer + len, PATH_MAX,
	1543	+ len += snprintf(buffer + len, PATH_MAX - len,
1544	1544	"ifcfg=static;address,172.31.%d.1;netmask,255.255.255.0",
1545	1545	mic->id + 1);
1546	1546

Documentation/security/self-protection.txt+18−10

@@ -183,8 +183,9 @@ provide meaningful defenses. · 182 unmodified lines
183	183	### Canaries, blinding, and other secrets
184	184
185	185	It should be noted that things like the stack canary discussed earlier
186		−are technically statistical defenses, since they rely on a (leakable)
187		−secret value.
	186	+are technically statistical defenses, since they rely on a secret value,
	187	+and such values may become discoverable through an information exposure
	188	+flaw.
188	189
189	190	Blinding literal values for things like JITs, where the executable
190	191	contents may be partially under the control of userspace, need a similar
@@ -199,8 +200,8 @@ working?) in order to maximize their success. · 8 unmodified lines
199	200	Since the location of kernel memory is almost always instrumental in
200	201	mounting a successful attack, making the location non-deterministic
201	202	raises the difficulty of an exploit. (Note that this in turn makes
202		−the value of leaks higher, since they may be used to discover desired
203		−memory locations.)
	203	+the value of information exposures higher, since they may be used to
	204	+discover desired memory locations.)
204	205
205	206	#### Text and module base
206	207
@@ -222,14 +223,21 @@ become more difficult to locate. · 15 unmodified lines
222	223	Much of the kernel's dynamic memory (e.g. kmalloc, vmalloc, etc) ends up
223	224	being relatively deterministic in layout due to the order of early-boot
224	225	initializations. If the base address of these areas is not the same
225		−between boots, targeting them is frustrated, requiring a leak specific
226		−to the region.
	226	+between boots, targeting them is frustrated, requiring an information
	227	+exposure specific to the region.
	228	+
	229	+#### Structure layout
	230	+
	231	+By performing a per-build randomization of the layout of sensitive
	232	+structures, attacks must either be tuned to known kernel builds or expose
	233	+enough kernel memory to determine structure layouts before manipulating
	234	+them.
227	235
228	236
229		−## Preventing Leaks
	237	+## Preventing Information Exposures
230	238
231	239	Since the locations of sensitive structures are the primary target for
232		−attacks, it is important to defend against leaks of both kernel memory
	240	+attacks, it is important to defend against exposure of both kernel memory
233	241	addresses and kernel memory contents (since they may contain kernel
234	242	addresses or other sensitive things like canary values).
235	243
@@ -250,8 +258,8 @@ sure structure holes are cleared. · 14 unmodified lines
250	258	When releasing memory, it is best to poison the contents (clear stack on
251	259	syscall return, wipe heap memory on a free), to avoid reuse attacks that
252	260	rely on the old contents of memory. This frustrates many uninitialized
253		−variable attacks, stack info leaks, heap info leaks, and use-after-free
254		−attacks.
	261	+variable attacks, stack content exposures, heap content exposures, and
	262	+use-after-free attacks.
255	263
256	264	### Destination tracking
257	265

Documentation/sphinx/convert_template.sed+18−0

@@ -0,0 +1,18 @@
	1	+#
	2	+# Pandoc doesn't grok <function> or <structname>, so convert them
	3	+# ahead of time.
	4	+#
	5	+# Use the following escapes to pass through pandoc:
	6	+# $bq = "`"
	7	+# $lt = "<"
	8	+# $gt = ">"
	9	+#
	10	+s%<function>$[^<(]\+$()</function>%:c:func:$bq\1()$bq%g
	11	+s%<function>$[^<(]\+$</function>%:c:func:$bq\1()$bq%g
	12	+s%<structname>struct *$[^<]\+$</structname>%:c:type:$bqstruct \1 $lt\1$gt$bq%g
	13	+s%struct <structname>$[^<]\+$</structname>%:c:type:$bqstruct \1 $lt\1$gt$bq%g
	14	+s%<structname>$[^<]\+$</structname>%:c:type:$bqstruct \1 $lt\1$gt$bq%g
	15	+#
	16	+# Wrap docproc directives in para and code blocks.
	17	+#
	18	+s%^$!.*$$%<para><code>DOCPROC: \1</code></para>%

Documentation/sphinx/kernel-doc.py+141−0

@@ -0,0 +1,141 @@
	1	+# coding=utf-8
	2	+#
	3	+# Copyright © 2016 Intel Corporation
	4	+#
	5	+# Permission is hereby granted, free of charge, to any person obtaining a
	6	+# copy of this software and associated documentation files (the "Software"),
	7	+# to deal in the Software without restriction, including without limitation
	8	+# the rights to use, copy, modify, merge, publish, distribute, sublicense,
	9	+# and/or sell copies of the Software, and to permit persons to whom the
	10	+# Software is furnished to do so, subject to the following conditions:
	11	+#
	12	+# The above copyright notice and this permission notice (including the next
	13	+# paragraph) shall be included in all copies or substantial portions of the
	14	+# Software.
	15	+#
	16	+# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
	17	+# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
	18	+# FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL
	19	+# THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
	20	+# LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
	21	+# FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS
	22	+# IN THE SOFTWARE.
	23	+#
	24	+# Authors:
	25	+# Jani Nikula <jani.nikula@intel.com>
	26	+#
	27	+# Please make sure this works on both python2 and python3.
	28	+#
	29	+
	30	+import os
	31	+import subprocess
	32	+import sys
	33	+import re
	34	+import glob
	35	+
	36	+from docutils import nodes, statemachine
	37	+from docutils.statemachine import ViewList
	38	+from docutils.parsers.rst import directives
	39	+from sphinx.util.compat import Directive
	40	+from sphinx.ext.autodoc import AutodocReporter
	41	+
	42	+class KernelDocDirective(Directive):
	43	+ """Extract kernel-doc comments from the specified file"""
	44	+ required_argument = 1
	45	+ optional_arguments = 4
	46	+ option_spec = {
	47	+ 'doc': directives.unchanged_required,
	48	+ 'functions': directives.unchanged_required,
	49	+ 'export': directives.unchanged,
	50	+ 'internal': directives.unchanged,
	51	+ }
	52	+ has_content = False
	53	+
	54	+ def run(self):
	55	+ env = self.state.document.settings.env
	56	+ cmd = [env.config.kerneldoc_bin, '-rst', '-enable-lineno']
	57	+
	58	+ filename = env.config.kerneldoc_srctree + '/' + self.arguments[0]
	59	+ export_file_patterns = []
	60	+
	61	+ # Tell sphinx of the dependency
	62	+ env.note_dependency(os.path.abspath(filename))
	63	+
	64	+ tab_width = self.options.get('tab-width', self.state.document.settings.tab_width)
	65	+
	66	+ # FIXME: make this nicer and more robust against errors
	67	+ if 'export' in self.options:
	68	+ cmd += ['-export']
	69	+ export_file_patterns = str(self.options.get('export')).split()
	70	+ elif 'internal' in self.options:
	71	+ cmd += ['-internal']
	72	+ export_file_patterns = str(self.options.get('internal')).split()
	73	+ elif 'doc' in self.options:
	74	+ cmd += ['-function', str(self.options.get('doc'))]
	75	+ elif 'functions' in self.options:
	76	+ for f in str(self.options.get('functions')).split():
	77	+ cmd += ['-function', f]
	78	+
	79	+ for pattern in export_file_patterns:
	80	+ for f in glob.glob(env.config.kerneldoc_srctree + '/' + pattern):
	81	+ env.note_dependency(os.path.abspath(f))
	82	+ cmd += ['-export-file', f]
	83	+
	84	+ cmd += [filename]
	85	+
	86	+ try:
	87	+ env.app.verbose('calling kernel-doc \'%s\'' % (" ".join(cmd)))
	88	+
	89	+ p = subprocess.Popen(cmd, stdout=subprocess.PIPE, stderr=subprocess.PIPE, universal_newlines=True)
	90	+ out, err = p.communicate()
	91	+
	92	+ # python2 needs conversion to unicode.
	93	+ # python3 with universal_newlines=True returns strings.
	94	+ if sys.version_info.major < 3:
	95	+ out, err = unicode(out, 'utf-8'), unicode(err, 'utf-8')
	96	+
	97	+ if p.returncode != 0:
	98	+ sys.stderr.write(err)
	99	+
	100	+ env.app.warn('kernel-doc \'%s\' failed with return code %d' % (" ".join(cmd), p.returncode))
	101	+ return [nodes.error(None, nodes.paragraph(text = "kernel-doc missing"))]
	102	+ elif env.config.kerneldoc_verbosity > 0:
	103	+ sys.stderr.write(err)
	104	+
	105	+ lines = statemachine.string2lines(out, tab_width, convert_whitespace=True)
	106	+ result = ViewList()
	107	+
	108	+ lineoffset = 0;
	109	+ line_regex = re.compile("^#define LINENO ([0-9]+)$")
	110	+ for line in lines:
	111	+ match = line_regex.search(line)
	112	+ if match:
	113	+ # sphinx counts lines from 0
	114	+ lineoffset = int(match.group(1)) - 1
	115	+ # we must eat our comments since the upset the markup
	116	+ else:
	117	+ result.append(line, filename, lineoffset)
	118	+ lineoffset += 1
	119	+
	120	+ node = nodes.section()
	121	+ buf = self.state.memo.title_styles, self.state.memo.section_level, self.state.memo.reporter
	122	+ self.state.memo.reporter = AutodocReporter(result, self.state.memo.reporter)
	123	+ self.state.memo.title_styles, self.state.memo.section_level = [], 0
	124	+ try:
	125	+ self.state.nested_parse(result, 0, node, match_titles=1)
	126	+ finally:
	127	+ self.state.memo.title_styles, self.state.memo.section_level, self.state.memo.reporter = buf
	128	+
	129	+ return node.children
	130	+
	131	+ except Exception as e: # pylint: disable=W0703
	132	+ env.app.warn('kernel-doc \'%s\' processing failed with: %s' %
	133	+ (" ".join(cmd), str(e)))
	134	+ return [nodes.error(None, nodes.paragraph(text = "kernel-doc missing"))]
	135	+
	136	+def setup(app):
	137	+ app.add_config_value('kerneldoc_bin', None, 'env')
	138	+ app.add_config_value('kerneldoc_srctree', None, 'env')
	139	+ app.add_config_value('kerneldoc_verbosity', 1, 'env')
	140	+
	141	+ app.add_directive('kernel-doc', KernelDocDirective)

Documentation/sphinx/post_convert.sed+23−0

@@ -0,0 +1,23 @@
	1	+#
	2	+# Unescape.
	3	+#
	4	+s/$bq/`/g
	5	+s/$lt/</g
	6	+s/$gt/>/g
	7	+#
	8	+# pandoc thinks that both "_" needs to be escaped. Remove the extra
	9	+# backslashes.
	10	+#
	11	+s/\\_/_/g
	12	+#
	13	+# Unwrap docproc directives.
	14	+#
	15	+s/^``DOCPROC: !E$.*$``$/.. kernel-doc:: \1\n :export:/
	16	+s/^``DOCPROC: !I$.*$``$/.. kernel-doc:: \1\n :internal:/
	17	+s/^``DOCPROC: !F$[^ ]$ $.$``$/.. kernel-doc:: \1\n :functions: \2/
	18	+s/^``DOCPROC: !P$[^ ]$ $.$``$/.. kernel-doc:: \1\n :doc: \2/
	19	+s/^``DOCPROC: $!.*$``$/.. WARNING: DOCPROC directive not supported: \1/
	20	+#
	21	+# Trim trailing whitespace.
	22	+#
	23	+s/[[:space:]]*$//

Documentation/sphinx/rstFlatTable.py+365−0

@@ -0,0 +1,365 @@
	1	+#!/usr/bin/env python3
	2	+# -- coding: utf-8; mode: python --
	3	+# pylint: disable=C0330, R0903, R0912
	4	+
	5	+u"""
	6	+ flat-table
	7	+ ~~~~~~~~~~
	8	+
	9	+ Implementation of the ``flat-table`` reST-directive.
	10	+
	11	+ :copyright: Copyright (C) 2016 Markus Heiser
	12	+ :license: GPL Version 2, June 1991 see linux/COPYING for details.
	13	+
	14	+ The ``flat-table`` (:py:class:`FlatTable`) is a double-stage list similar to
	15	+ the ``list-table`` with some additional features:
	16	+
	17	+ * column-span: with the role ``cspan`` a cell can be extended through
	18	+ additional columns
	19	+
	20	+ * row-span: with the role ``rspan`` a cell can be extended through
	21	+ additional rows
	22	+
	23	+ * auto span rightmost cell of a table row over the missing cells on the
	24	+ right side of that table-row. With Option ``:fill-cells:`` this behavior
	25	+ can changed from auto span to auto fill, which automaticly inserts
	26	+ (empty) cells instead of spanning the last cell.
	27	+
	28	+ Options:
	29	+
	30	+ * header-rows: [int] count of header rows
	31	+ * stub-columns: [int] count of stub columns
	32	+ * widths: [[int] [int] ... ] widths of columns
	33	+ * fill-cells: instead of autospann missing cells, insert missing cells
	34	+
	35	+ roles:
	36	+
	37	+ * cspan: [int] additionale columns (morecols)
	38	+ * rspan: [int] additionale rows (morerows)
	39	+"""
	40	+
	41	+# ==============================================================================
	42	+# imports
	43	+# ==============================================================================
	44	+
	45	+import sys
	46	+
	47	+from docutils import nodes
	48	+from docutils.parsers.rst import directives, roles
	49	+from docutils.parsers.rst.directives.tables import Table
	50	+from docutils.utils import SystemMessagePropagation
	51	+
	52	+# ==============================================================================
	53	+# common globals
	54	+# ==============================================================================
	55	+
	56	+# The version numbering follows numbering of the specification
	57	+# (Documentation/books/kernel-doc-HOWTO).
	58	+__version__ = '1.0'
	59	+
	60	+PY3 = sys.version_info[0] == 3
	61	+PY2 = sys.version_info[0] == 2
	62	+
	63	+if PY3:
	64	+ # pylint: disable=C0103, W0622
	65	+ unicode = str
	66	+ basestring = str
	67	+
	68	+# ==============================================================================
	69	+def setup(app):
	70	+# ==============================================================================
	71	+
	72	+ app.add_directive("flat-table", FlatTable)
	73	+ roles.register_local_role('cspan', c_span)
	74	+ roles.register_local_role('rspan', r_span)
	75	+
	76	+# ==============================================================================
	77	+def c_span(name, rawtext, text, lineno, inliner, options=None, content=None):
	78	+# ==============================================================================
	79	+ # pylint: disable=W0613
	80	+
	81	+ options = options if options is not None else {}
	82	+ content = content if content is not None else []
	83	+ nodelist = [colSpan(span=int(text))]
	84	+ msglist = []
	85	+ return nodelist, msglist
	86	+
	87	+# ==============================================================================
	88	+def r_span(name, rawtext, text, lineno, inliner, options=None, content=None):
	89	+# ==============================================================================
	90	+ # pylint: disable=W0613
	91	+
	92	+ options = options if options is not None else {}
	93	+ content = content if content is not None else []
	94	+ nodelist = [rowSpan(span=int(text))]
	95	+ msglist = []
	96	+ return nodelist, msglist
	97	+
	98	+
	99	+# ==============================================================================
	100	+class rowSpan(nodes.General, nodes.Element): pass # pylint: disable=C0103,C0321
	101	+class colSpan(nodes.General, nodes.Element): pass # pylint: disable=C0103,C0321
	102	+# ==============================================================================
	103	+
	104	+# ==============================================================================
	105	+class FlatTable(Table):
	106	+# ==============================================================================
	107	+
	108	+ u"""FlatTable (``flat-table``) directive"""
	109	+
	110	+ option_spec = {
	111	+ 'name': directives.unchanged
	112	+ , 'class': directives.class_option
	113	+ , 'header-rows': directives.nonnegative_int
	114	+ , 'stub-columns': directives.nonnegative_int
	115	+ , 'widths': directives.positive_int_list
	116	+ , 'fill-cells' : directives.flag }
	117	+
	118	+ def run(self):
	119	+
	120	+ if not self.content:
	121	+ error = self.state_machine.reporter.error(
	122	+ 'The "%s" directive is empty; content required.' % self.name,
	123	+ nodes.literal_block(self.block_text, self.block_text),
	124	+ line=self.lineno)
	125	+ return [error]
	126	+
	127	+ title, messages = self.make_title()
	128	+ node = nodes.Element() # anonymous container for parsing
	129	+ self.state.nested_parse(self.content, self.content_offset, node)
	130	+
	131	+ tableBuilder = ListTableBuilder(self)
	132	+ tableBuilder.parseFlatTableNode(node)
	133	+ tableNode = tableBuilder.buildTableNode()
	134	+ # SDK.CONSOLE() # print --> tableNode.asdom().toprettyxml()
	135	+ if title:
	136	+ tableNode.insert(0, title)
	137	+ return [tableNode] + messages
	138	+
	139	+
	140	+# ==============================================================================
	141	+class ListTableBuilder(object):
	142	+# ==============================================================================
	143	+
	144	+ u"""Builds a table from a double-stage list"""
	145	+
	146	+ def __init__(self, directive):
	147	+ self.directive = directive
	148	+ self.rows = []
	149	+ self.max_cols = 0
	150	+
	151	+ def buildTableNode(self):
	152	+
	153	+ colwidths = self.directive.get_column_widths(self.max_cols)
	154	+ stub_columns = self.directive.options.get('stub-columns', 0)
	155	+ header_rows = self.directive.options.get('header-rows', 0)
	156	+
	157	+ table = nodes.table()
	158	+ tgroup = nodes.tgroup(cols=len(colwidths))
	159	+ table += tgroup
	160	+
	161	+
	162	+ for colwidth in colwidths:
	163	+ colspec = nodes.colspec(colwidth=colwidth)
	164	+ # FIXME: It seems, that the stub method only works well in the
	165	+ # absence of rowspan (observed by the html buidler, the docutils-xml
	166	+ # build seems OK). This is not extraordinary, because there exists
	167	+ # no table directive (except this flat-table) which allows to
	168	+ # define coexistent of rowspan and stubs (there was no use-case
	169	+ # before flat-table). This should be reviewed (later).
	170	+ if stub_columns:
	171	+ colspec.attributes['stub'] = 1
	172	+ stub_columns -= 1
	173	+ tgroup += colspec
	174	+ stub_columns = self.directive.options.get('stub-columns', 0)
	175	+
	176	+ if header_rows:
	177	+ thead = nodes.thead()
	178	+ tgroup += thead
	179	+ for row in self.rows[:header_rows]:
	180	+ thead += self.buildTableRowNode(row)
	181	+
	182	+ tbody = nodes.tbody()
	183	+ tgroup += tbody
	184	+
	185	+ for row in self.rows[header_rows:]:
	186	+ tbody += self.buildTableRowNode(row)
	187	+ return table
	188	+
	189	+ def buildTableRowNode(self, row_data, classes=None):
	190	+ classes = [] if classes is None else classes
	191	+ row = nodes.row()
	192	+ for cell in row_data:
	193	+ if cell is None:
	194	+ continue
	195	+ cspan, rspan, cellElements = cell
	196	+
	197	+ attributes = {"classes" : classes}
	198	+ if rspan:
	199	+ attributes['morerows'] = rspan
	200	+ if cspan:
	201	+ attributes['morecols'] = cspan
	202	+ entry = nodes.entry(**attributes)
	203	+ entry.extend(cellElements)
	204	+ row += entry
	205	+ return row
	206	+
	207	+ def raiseError(self, msg):
	208	+ error = self.directive.state_machine.reporter.error(
	209	+ msg
	210	+ , nodes.literal_block(self.directive.block_text
	211	+ , self.directive.block_text)
	212	+ , line = self.directive.lineno )
	213	+ raise SystemMessagePropagation(error)
	214	+
	215	+ def parseFlatTableNode(self, node):
	216	+ u"""parses the node from a :py:class:`FlatTable` directive's body"""
	217	+
	218	+ if len(node) != 1 or not isinstance(node[0], nodes.bullet_list):
	219	+ self.raiseError(
	220	+ 'Error parsing content block for the "%s" directive: '
	221	+ 'exactly one bullet list expected.' % self.directive.name )
	222	+
	223	+ for rowNum, rowItem in enumerate(node[0]):
	224	+ row = self.parseRowItem(rowItem, rowNum)
	225	+ self.rows.append(row)
	226	+ self.roundOffTableDefinition()
	227	+
	228	+ def roundOffTableDefinition(self):
	229	+ u"""Round off the table definition.
	230	+
	231	+ This method rounds off the table definition in :py:member:`rows`.
	232	+
	233	+ * This method inserts the needed ``None`` values for the missing cells
	234	+ arising from spanning cells over rows and/or columns.
	235	+
	236	+ * recount the :py:member:`max_cols`
	237	+
	238	+ * Autospan or fill (option ``fill-cells``) missing cells on the right
	239	+ side of the table-row
	240	+ """
	241	+
	242	+ y = 0
	243	+ while y < len(self.rows):
	244	+ x = 0
	245	+
	246	+ while x < len(self.rows[y]):
	247	+ cell = self.rows[y][x]
	248	+ if cell is None:
	249	+ x += 1
	250	+ continue
	251	+ cspan, rspan = cell[:2]
	252	+ # handle colspan in current row
	253	+ for c in range(cspan):
	254	+ try:
	255	+ self.rows[y].insert(x+c+1, None)
	256	+ except: # pylint: disable=W0702
	257	+ # the user sets ambiguous rowspans
	258	+ pass # SDK.CONSOLE()
	259	+ # handle colspan in spanned rows
	260	+ for r in range(rspan):
	261	+ for c in range(cspan + 1):
	262	+ try:
	263	+ self.rows[y+r+1].insert(x+c, None)
	264	+ except: # pylint: disable=W0702
	265	+ # the user sets ambiguous rowspans
	266	+ pass # SDK.CONSOLE()
	267	+ x += 1
	268	+ y += 1
	269	+
	270	+ # Insert the missing cells on the right side. For this, first
	271	+ # re-calculate the max columns.
	272	+
	273	+ for row in self.rows:
	274	+ if self.max_cols < len(row):
	275	+ self.max_cols = len(row)
	276	+
	277	+ # fill with empty cells or cellspan?
	278	+
	279	+ fill_cells = False
	280	+ if 'fill-cells' in self.directive.options:
	281	+ fill_cells = True
	282	+
	283	+ for row in self.rows:
	284	+ x = self.max_cols - len(row)
	285	+ if x and not fill_cells:
	286	+ if row[-1] is None:
	287	+ row.append( ( x - 1, 0, []) )
	288	+ else:
	289	+ cspan, rspan, content = row[-1]
	290	+ row[-1] = (cspan + x, rspan, content)
	291	+ elif x and fill_cells:
	292	+ for i in range(x):
	293	+ row.append( (0, 0, nodes.comment()) )
	294	+
	295	+ def pprint(self):
	296	+ # for debugging
	297	+ retVal = "[ "
	298	+ for row in self.rows:
	299	+ retVal += "[ "
	300	+ for col in row:
	301	+ if col is None:
	302	+ retVal += ('%r' % col)
	303	+ retVal += "\n , "
	304	+ else:
	305	+ content = col[2][0].astext()
	306	+ if len (content) > 30:
	307	+ content = content[:30] + "..."
	308	+ retVal += ('(cspan=%s, rspan=%s, %r)'
	309	+ % (col[0], col[1], content))
	310	+ retVal += "]\n , "
	311	+ retVal = retVal[:-2]
	312	+ retVal += "]\n , "
	313	+ retVal = retVal[:-2]
	314	+ return retVal + "]"
	315	+
	316	+ def parseRowItem(self, rowItem, rowNum):
	317	+ row = []
	318	+ childNo = 0
	319	+ error = False
	320	+ cell = None
	321	+ target = None
	322	+
	323	+ for child in rowItem:
	324	+ if (isinstance(child , nodes.comment)
	325	+ or isinstance(child, nodes.system_message)):
	326	+ pass
	327	+ elif isinstance(child , nodes.target):
	328	+ target = child
	329	+ elif isinstance(child, nodes.bullet_list):
	330	+ childNo += 1
	331	+ cell = child
	332	+ else:
	333	+ error = True
	334	+ break
	335	+
	336	+ if childNo != 1 or error:
	337	+ self.raiseError(
	338	+ 'Error parsing content block for the "%s" directive: '
	339	+ 'two-level bullet list expected, but row %s does not '
	340	+ 'contain a second-level bullet list.'
	341	+ % (self.directive.name, rowNum + 1))
	342	+
	343	+ for cellItem in cell:
	344	+ cspan, rspan, cellElements = self.parseCellItem(cellItem)
	345	+ if target is not None:
	346	+ cellElements.insert(0, target)
	347	+ row.append( (cspan, rspan, cellElements) )
	348	+ return row
	349	+
	350	+ def parseCellItem(self, cellItem):
	351	+ # search and remove cspan, rspan colspec from the first element in
	352	+ # this listItem (field).
	353	+ cspan = rspan = 0
	354	+ if not len(cellItem):
	355	+ return cspan, rspan, []
	356	+ for elem in cellItem[0]:
	357	+ if isinstance(elem, colSpan):
	358	+ cspan = elem.get("span")
	359	+ elem.parent.remove(elem)
	360	+ continue
	361	+ if isinstance(elem, rowSpan):
	362	+ rspan = elem.get("span")
	363	+ elem.parent.remove(elem)
	364	+ continue
	365	+ return cspan, rspan, cellItem[:]

Documentation/sphinx/tmplcvt+19−0

@@ -0,0 +1,19 @@
	1	+#!/bin/bash
	2	+#
	3	+# Convert a template file into something like RST
	4	+#
	5	+# fix <function>
	6	+# feed to pandoc
	7	+# fix \_
	8	+# title line?
	9	+#
	10	+
	11	+in=$1
	12	+rst=$2
	13	+tmp=$rst.tmp
	14	+
	15	+cp $in $tmp
	16	+sed --in-place -f convert_template.sed $tmp
	17	+pandoc -s -S -f docbook -t rst -o $rst $tmp
	18	+sed --in-place -f post_convert.sed $rst
	19	+rm $tmp

Documentation/sync_file.txt+3−3

@@ -6,8 +6,8 @@ · 5 unmodified lines
6	6
7	7	This document serves as a guide for device drivers writers on what the
8	8	sync_file API is, and how drivers can support it. Sync file is the carrier of
9		−the fences(struct fence) that needs to synchronized between drivers or across
10		−process boundaries.
	9	+the fences(struct fence) that are needed to synchronize between drivers or
	10	+across process boundaries.
11	11
12	12	The sync_file API is meant to be used to send and receive fence information
13	13	to/from userspace. It enables userspace to do explicit fencing, where instead
@@ -32,7 +32,7 @@ in-fences and out-fences · 18 unmodified lines
32	32	Sync files can go either to or from userspace. When a sync_file is sent from
33	33	the driver to userspace we call the fences it contains 'out-fences'. They are
34	34	related to a buffer that the driver is processing or is going to process, so
35		−the driver an create out-fence to be able to notify, through fence_signal(),
	35	+the driver creates an out-fence to be able to notify, through fence_signal(),
36	36	when it has finished using (or processing) that buffer. Out-fences are fences
37	37	that the driver creates.
38	38

Documentation/sysctl/vm.txt+1−0

@@ -61,6 +61,7 @@ Currently, these files are in /proc/sys/vm: · 60 unmodified lines
61	61	- swappiness
62	62	- user_reserve_kbytes
63	63	- vfs_cache_pressure
	64	+- watermark_scale_factor
64	65	- zone_reclaim_mode
65	66
66	67	==============================================================

Documentation/thermal/intel_powerclamp.txt+1−1

@@ -121,7 +121,7 @@ time is considered largely as a non-causal system where its behavior · 120 unmodified lines
121	121	cannot be based on the past or current input. Therefore, the
122	122	intel_powerclamp driver attempts to enforce the desired idle time
123	123	instantly as given input (target idle ratio). After injection,
124		−powerclamp moniors the actual idle for a given time window and adjust
	124	+powerclamp monitors the actual idle for a given time window and adjust
125	125	the next injection accordingly to avoid over/under correction.
126	126
127	127	When used in a causal control system, such as a temperature control,

Documentation/usb/gadget_multi.txt+1−1

@@ -36,7 +36,7 @@ configuration with CDC ECM which should work better under Linux. · 35 unmodified lines
36	36
37	37	** Windows host drivers
38	38
39		−For the gadget two work under Windows two conditions have to be met:
	39	+For the gadget to work under Windows two conditions have to be met:
40	40
41	41	*** Detecting as composite gadget
42	42

Documentation/workqueue.txt+1−1

@@ -169,7 +169,7 @@ resources, scheduled and executed. · 168 unmodified lines
169	169	WQ_UNBOUND
170	170
171	171	Work items queued to an unbound wq are served by the special
172		− woker-pools which host workers which are not bound to any
	172	+ worker-pools which host workers which are not bound to any
173	173	specific CPU. This makes the wq behave as a simple execution
174	174	context provider without concurrency management. The unbound
175	175	worker-pools try to start execution of work items as soon as

Documentation/zh_CN/CodingStyle+350−231

@@ -24,34 +24,33 @@ Documentation/CodingStyle的中文翻译 · 23 unmodified lines
24	24
25	25	Linux内核代码风格
26	26
27		−这是一个简短的文档，描述了linux内核的首选代码风格。代码风格是因人而异的，而且我
28		−不愿意把我的观点强加给任何人，不过这里所讲述的是我必须要维护的代码所遵守的风格，
29		−并且我也希望绝大多数其他代码也能遵守这个风格。请在写代码时至少考虑一下本文所述的
30		−风格。
	27	+这是一个简短的文档，描述了 linux 内核的首选代码风格。代码风格是因人而异的，而且我
	28	+不愿意把自己的观点强加给任何人，但这就像我去做任何事情都必须遵循的原则那样，我也
	29	+希望在绝大多数事上保持这种的态度。请（在写代码时）至少考虑一下这里的代码风格。
31	30
32		−首先，我建议你打印一份GNU代码规范，然后不要读它。烧了它，这是一个具有重大象征性
33		−意义的动作。
	31	+首先，我建议你打印一份 GNU 代码规范，然后不要读。烧了它，这是一个具有重大象征性意义
	32	+的动作。
34	33
35	34	不管怎样，现在我们开始：
36	35
37	36
38		− 第一章：缩进
	37	+ 第一章：缩进
39	38
40		−制表符是8个字符，所以缩进也是8个字符。有些异端运动试图将缩进变为4（乃至2）个字符
41		−深，这几乎相当于尝试将圆周率的值定义为3。
	39	+制表符是 8 个字符，所以缩进也是 8 个字符。有些异端运动试图将缩进变为 4（甚至 2！）
	40	+个字符深，这几乎相当于尝试将圆周率的值定义为 3。
42	41
43	42	理由：缩进的全部意义就在于清楚的定义一个控制块起止于何处。尤其是当你盯着你的屏幕
44		−连续看了20小时之后，你将会发现大一点的缩进会使你更容易分辨缩进。
	43	+连续看了 20 小时之后，你将会发现大一点的缩进会使你更容易分辨缩进。
45	44
46		−现在，有些人会抱怨8个字符的缩进会使代码向右边移动的太远，在80个字符的终端屏幕上
47		−就很难读这样的代码。这个问题的答案是，如果你需要3级以上的缩进，不管用何种方式你
	45	+现在，有些人会抱怨 8 个字符的缩进会使代码向右边移动的太远，在 80 个字符的终端屏幕上
	46	+就很难读这样的代码。这个问题的答案是，如果你需要 3 级以上的缩进，不管用何种方式你
48	47	的代码已经有问题了，应该修正你的程序。
49	48
50		−简而言之，8个字符的缩进可以让代码更容易阅读，还有一个好处是当你的函数嵌套太深的
	49	+简而言之，8 个字符的缩进可以让代码更容易阅读，还有一个好处是当你的函数嵌套太深的
51	50	时候可以给你警告。留心这个警告。
52	51
53		−在switch语句中消除多级缩进的首选的方式是让“switch”和从属于它的“case”标签对齐于同
54		−一列，而不要“两次缩进”“case”标签。比如：
	52	+在 switch 语句中消除多级缩进的首选的方式是让 “switch” 和从属于它的 “case” 标签
	53	+对齐于同一列，而不要 “两次缩进” “case” 标签。比如：
55	54
56	55	switch (suffix) {
57	56	case 'G':
@@ -70,7 +69,6 @@ Documentation/CodingStyle的中文翻译 · 12 unmodified lines
70	69	break;
71	70	}
72	71
73		−
74	72	不要把多个语句放在一行里，除非你有什么东西要隐藏：
75	73
76	74	if (condition) do_this;
@@ -79,7 +77,7 @@ Documentation/CodingStyle的中文翻译 · 2 unmodified lines
79	77	也不要在一行里放多个赋值语句。内核代码风格超级简单。就是避免可能导致别人误读的表
80	78	达式。
81	79
82		−除了注释、文档和Kconfig之外，不要使用空格来缩进，前面的例子是例外，是有意为之。
	80	+除了注释、文档和 Kconfig 之外，不要使用空格来缩进，前面的例子是例外，是有意为之。
83	81
84	82	选用一个好的编辑器，不要在行尾留空格。
85	83
@@ -88,27 +86,18 @@ Documentation/CodingStyle的中文翻译 · 2 unmodified lines
88	86
89	87	代码风格的意义就在于使用平常使用的工具来维持代码的可读性和可维护性。
90	88
91		−每一行的长度的限制是80列，我们强烈建议您遵守这个惯例。
	89	+每一行的长度的限制是 80 列，我们强烈建议您遵守这个惯例。
92	90
93		−长于80列的语句要打散成有意义的片段。每个片段要明显短于原来的语句，而且放置的位置
94		−也明显的靠右。同样的规则也适用于有很长参数列表的函数头。长字符串也要打散成较短的
95		−字符串。唯一的例外是超过80列可以大幅度提高可读性并且不会隐藏信息的情况。
96		−
97		−void fun(int a, int b, int c)
98		−{
99		− if (condition)
100		− printk(KERN_WARNING "Warning this is a long printk with "
101		− "3 parameters a: %u b: %u "
102		− "c: %u \n", a, b, c);
103		− else
104		− next_statement;
105		−}
	91	+长于 80 列的语句要打散成有意义的片段。除非超过 80 列能显著增加可读性，并且不会隐藏
	92	+信息。子片段要明显短于母片段，并明显靠右。这同样适用于有着很长参数列表的函数头。
	93	+然而，绝对不要打散对用户可见的字符串，例如 printk 信息，因为这将导致无法 grep 这些
	94	+信息。
106	95
107	96	第三章：大括号和空格的放置
108	97
109	98	C语言风格中另外一个常见问题是大括号的放置。和缩进大小不同，选择或弃用某种放置策
110		−略并没有多少技术上的原因，不过首选的方式，就像Kernighan和Ritchie展示给我们的，是
111		−把起始大括号放在行尾，而把结束大括号放在行首，所以：
	99	+略并没有多少技术上的原因，不过首选的方式，就像 Kernighan 和 Ritchie 展示给我们的，
	100	+是把起始大括号放在行尾，而把结束大括号放在行首，所以：
112	101
113	102	if (x is true) {
114	103	we do y
@@ -134,12 +123,12 @@ C语言风格中另外一个常见问题是大括号的放置。和缩进大小 · 19 unmodified lines
134	123	body of function
135	124	}
136	125
137		−全世界的异端可能会抱怨这个不一致性是……呃……不一致的，不过所有思维健全的人都知道（
138		−a）K&R是_正确的_，并且（b）K&R是正确的。此外，不管怎样函数都是特殊的（在C语言中
139		−，函数是不能嵌套的）。
	126	+全世界的异端可能会抱怨这个不一致性是……呃……不一致的，不过所有思维健全的人都知道
	127	+(a) K&R 是 _正确的_，并且 (b) K&R 是正确的。此外，不管怎样函数都是特殊的（C
	128	+函数是不能嵌套的）。
140	129
141		−注意结束大括号独自占据一行，除非它后面跟着同一个语句的剩余部分，也就是do语句中的
142		−“while”或者if语句中的“else”，像这样：
	130	+注意结束大括号独自占据一行，除非它后面跟着同一个语句的剩余部分，也就是 do 语句中的
	131	+“while” 或者 if 语句中的 “else”，像这样：
143	132
144	133	do {
145	134	body of do-loop
@@ -158,41 +147,50 @@ a）K&R是_正确的_，并且（b）K&R是正确的。此外，不管怎样函 · 12 unmodified lines
158	147	理由：K&R。
159	148
160	149	也请注意这种大括号的放置方式也能使空（或者差不多空的）行的数量最小化，同时不失可
161		−读性。因此，由于你的屏幕上的新行是不可再生资源（想想25行的终端屏幕），你将会有更
	150	+读性。因此，由于你的屏幕上的新行是不可再生资源（想想 25 行的终端屏幕），你将会有更
162	151	多的空行来放置注释。
163	152
164	153	当只有一个单独的语句的时候，不用加不必要的大括号。
165	154
166		−if (condition)
167		− action();
	155	+ if (condition)
	156	+ action();
	157	+
	158	+和
	159	+
	160	+ if (condition)
	161	+ do_this();
	162	+ else
	163	+ do_that();
168	164
169		−这点不适用于本身为某个条件语句的一个分支的单独语句。这时需要在两个分支里都使用大
170		−括号。
	165	+这并不适用于只有一个条件分支是单语句的情况；这时所有分支都要使用大括号：
171	166
172		−if (condition) {
173		− do_this();
174		− do_that();
175		−} else {
176		− otherwise();
177		−}
	167	+ if (condition) {
	168	+ do_this();
	169	+ do_that();
	170	+ } else {
	171	+ otherwise();
	172	+ }
178	173
179	174	3.1：空格
180	175
181		−Linux内核的空格使用方式（主要）取决于它是用于函数还是关键字。（大多数）关键字后
182		−要加一个空格。值得注意的例外是sizeof、typeof、alignof和__attribute__，这些关键字
183		−某些程度上看起来更像函数（它们在Linux里也常常伴随小括号而使用，尽管在C语言里这样
184		−的小括号不是必需的，就像“struct fileinfo info”声明过后的“sizeof info”）。
	176	+Linux 内核的空格使用方式（主要）取决于它是用于函数还是关键字。（大多数）关键字后
	177	+要加一个空格。值得注意的例外是 sizeof、typeof、alignof 和 __attribute__，这些
	178	+关键字某些程度上看起来更像函数（它们在 Linux 里也常常伴随小括号而使用，尽管在 C 里
	179	+这样的小括号不是必需的，就像 “struct fileinfo info” 声明过后的 “sizeof info”）。
185	180
186	181	所以在这些关键字之后放一个空格：
	182	+
187	183	if, switch, case, for, do, while
188		−但是不要在sizeof、typeof、alignof或者__attribute__这些关键字之后放空格。例如，
	184	+
	185	+但是不要在 sizeof、typeof、alignof 或者 __attribute__ 这些关键字之后放空格。例如，
	186	+
189	187	s = sizeof(struct file);
190	188
191	189	不要在小括号里的表达式两侧加空格。这是一个反例：
192	190
193	191	s = sizeof( struct file );
194	192
195		−当声明指针类型或者返回指针类型的函数时，“*”的首选使用方式是使之靠近变量名或者函
	193	+当声明指针类型或者返回指针类型的函数时，“*” 的首选使用方式是使之靠近变量名或者函
196	194	数名，而不是靠近类型名。例子：
197	195
198	196	char *linux_banner;
@@ -204,15 +202,18 @@ Linux内核的空格使用方式（主要）取决于它是用于函数还是关 · 5 unmodified lines
204	202	= + - < > * / % \| & ^ <= >= == != ? :
205	203
206	204	但是一元操作符后不要加空格：
	205	+
207	206	& * + - ~ ! sizeof typeof alignof __attribute__ defined
208	207
209	208	后缀自加和自减一元操作符前不加空格：
	209	+
210	210	++ --
211	211
212	212	前缀自加和自减一元操作符后不加空格：
	213	+
213	214	++ --
214	215
215		−“.”和“->”结构体成员操作符前后不加空格。
	216	+‘.’ 和 “->” 结构体成员操作符前后不加空格。
216	217
217	218	不要在行尾留空白。有些可以自动缩进的编辑器会在新行的行首加入适量的空白，然后你
218	219	就可以直接在那一行输入代码。不过假如你最后没有在那一行输入代码，有些编辑器就不
@@ -225,23 +226,23 @@ Linux内核的空格使用方式（主要）取决于它是用于函数还是关 · 6 unmodified lines
225	226
226	227	第四章：命名
227	228
228		−C是一个简朴的语言，你的命名也应该这样。和Modula-2和Pascal程序员不同，C程序员不使
229		−用类似ThisVariableIsATemporaryCounter这样华丽的名字。C程序员会称那个变量为“tmp”
230		−，这样写起来会更容易，而且至少不会令其难于理解。
	229	+C是一个简朴的语言，你的命名也应该这样。和 Modula-2 和 Pascal 程序员不同，C 程序员
	230	+不使用类似 ThisVariableIsATemporaryCounter 这样华丽的名字。C 程序员会称那个变量
	231	+为 “tmp”，这样写起来会更容易，而且至少不会令其难于理解。
231	232
232	233	不过，虽然混用大小写的名字是不提倡使用的，但是全局变量还是需要一个具描述性的名字
233		−。称一个全局函数为“foo”是一个难以饶恕的错误。
	234	+。称一个全局函数为 “foo” 是一个难以饶恕的错误。
234	235
235	236	全局变量（只有当你真正需要它们的时候再用它）需要有一个具描述性的名字，就像全局函
236		−数。如果你有一个可以计算活动用户数量的函数，你应该叫它“count_active_users()”或者
237		−类似的名字，你不应该叫它“cntuser()”。
	237	+数。如果你有一个可以计算活动用户数量的函数，你应该叫它 “count_active_users()”
	238	+或者类似的名字，你不应该叫它 “cntuser()”。
238	239
239	240	在函数名中包含函数类型（所谓的匈牙利命名法）是脑子出了问题——编译器知道那些类型而
240	241	且能够检查那些类型，这样做只能把程序员弄糊涂了。难怪微软总是制造出有问题的程序。
241	242
242	243	本地变量名应该简短，而且能够表达相关的含义。如果你有一些随机的整数型的循环计数器
243		−，它应该被称为“i”。叫它“loop_counter”并无益处，如果它没有被误解的可能的话。类似
244		−的，“tmp”可以用来称呼任意类型的临时变量。
	244	+，它应该被称为 “i”。叫它 “loop_counter” 并无益处，如果它没有被误解的可能的话。
	245	+类似的，“tmp” 可以用来称呼任意类型的临时变量。
245	246
246	247	如果你怕混淆了你的本地变量名，你就遇到另一个问题了，叫做函数增长荷尔蒙失衡综合症
247	248	。请看第六章（函数）。
@@ -249,9 +250,9 @@ C是一个简朴的语言，你的命名也应该这样。和Modula-2和Pascal · 1 unmodified line
249	250
250	251	第五章：Typedef
251	252
252		−不要使用类似“vps_t”之类的东西。
	253	+不要使用类似 “vps_t” 之类的东西。
253	254
254		−对结构体和指针使用typedef是一个错误。当你在代码里看到：
	255	+对结构体和指针使用 typedef 是一个错误。当你在代码里看到：
255	256
256	257	vps_t a;
257	258
@@ -261,91 +262,91 @@ C是一个简朴的语言，你的命名也应该这样。和Modula-2和Pascal · 3 unmodified lines
261	262
262	263	struct virtual_container *a;
263	264
264		−你就知道“a”是什么了。
	265	+你就知道 “a” 是什么了。
265	266
266		−很多人认为typedef“能提高可读性”。实际不是这样的。它们只在下列情况下有用：
	267	+很多人认为 typedef “能提高可读性”。实际不是这样的。它们只在下列情况下有用：
267	268
268		− (a) 完全不透明的对象（这种情况下要主动使用typedef来隐藏这个对象实际上是什么）。
	269	+ (a) 完全不透明的对象（这种情况下要主动使用 typedef 来隐藏这个对象实际上是什么）。
269	270
270		− 例如：“pte_t”等不透明对象，你只能用合适的访问函数来访问它们。
	271	+ 例如：“pte_t” 等不透明对象，你只能用合适的访问函数来访问它们。
271	272
272		− 注意！不透明性和“访问函数”本身是不好的。我们使用pte_t等类型的原因在于真的是
	273	+ 注意！不透明性和“访问函数”本身是不好的。我们使用 pte_t 等类型的原因在于真的是
273	274	完全没有任何共用的可访问信息。
274	275
275		− (b) 清楚的整数类型，如此，这层抽象就可以帮助消除到底是“int”还是“long”的混淆。
	276	+ (b) 清楚的整数类型，如此，这层抽象就可以帮助消除到底是 “int” 还是 “long” 的混淆。
276	277
277		− u8/u16/u32是完全没有问题的typedef，不过它们更符合类别(d)而不是这里。
	278	+ u8/u16/u32 是完全没有问题的 typedef，不过它们更符合类别 (d) 而不是这里。
278	279
279		− 再次注意！要这样做，必须事出有因。如果某个变量是“unsigned long“，那么没有必要
	280	+ 再次注意！要这样做，必须事出有因。如果某个变量是 “unsigned long“，那么没有必要
280	281
281	282	typedef unsigned long myflags_t;
282	283
283		− 不过如果有一个明确的原因，比如它在某种情况下可能会是一个“unsigned int”而在
284		− 其他情况下可能为“unsigned long”，那么就不要犹豫，请务必使用typedef。
	284	+ 不过如果有一个明确的原因，比如它在某种情况下可能会是一个 “unsigned int” 而在
	285	+ 其他情况下可能为 “unsigned long”，那么就不要犹豫，请务必使用 typedef。
285	286
286	287	(c) 当你使用sparse按字面的创建一个新类型来做类型检查的时候。
287	288
288	289	(d) 和标准C99类型相同的类型，在某些例外的情况下。
289	290
290		− 虽然让眼睛和脑筋来适应新的标准类型比如“uint32_t”不需要花很多时间，可是有些
	291	+ 虽然让眼睛和脑筋来适应新的标准类型比如 “uint32_t” 不需要花很多时间，可是有些
291	292	人仍然拒绝使用它们。
292	293
293		− 因此，Linux特有的等同于标准类型的“u8/u16/u32/u64”类型和它们的有符号类型是被
	294	+ 因此，Linux 特有的等同于标准类型的 “u8/u16/u32/u64” 类型和它们的有符号类型是被
294	295	允许的——尽管在你自己的新代码中，它们不是强制要求要使用的。
295	296
296	297	当编辑已经使用了某个类型集的已有代码时，你应该遵循那些代码中已经做出的选择。
297	298
298	299	(e) 可以在用户空间安全使用的类型。
299	300
300		− 在某些用户空间可见的结构体里，我们不能要求C99类型而且不能用上面提到的“u32”
301		− 类型。因此，我们在与用户空间共享的所有结构体中使用__u32和类似的类型。
	301	+ 在某些用户空间可见的结构体里，我们不能要求C99类型而且不能用上面提到的 “u32”
	302	+ 类型。因此，我们在与用户空间共享的所有结构体中使用 __u32 和类似的类型。
302	303
303		−可能还有其他的情况，不过基本的规则是永远不要使用typedef，除非你可以明确的应用上
	304	+可能还有其他的情况，不过基本的规则是永远不要使用 typedef，除非你可以明确的应用上
304	305	述某个规则中的一个。
305	306
306	307	总的来说，如果一个指针或者一个结构体里的元素可以合理的被直接访问到，那么它们就不
307		−应该是一个typedef。
	308	+应该是一个 typedef。
308	309
309	310
310	311	第六章：函数
311	312
312	313	函数应该简短而漂亮，并且只完成一件事情。函数应该可以一屏或者两屏显示完（我们都知
313		−道ISO/ANSI屏幕大小是80x24），只做一件事情，而且把它做好。
	314	+道 ISO/ANSI 屏幕大小是 80x24），只做一件事情，而且把它做好。
314	315
315	316	一个函数的最大长度是和该函数的复杂度和缩进级数成反比的。所以，如果你有一个理论上
316		−很简单的只有一个很长（但是简单）的case语句的函数，而且你需要在每个case里做很多很
317		−小的事情，这样的函数尽管很长，但也是可以的。
	317	+很简单的只有一个很长（但是简单）的 case 语句的函数，而且你需要在每个 case 里做
	318	+很多很小的事情，这样的函数尽管很长，但也是可以的。
318	319
319	320	不过，如果你有一个复杂的函数，而且你怀疑一个天分不是很高的高中一年级学生可能甚至
320	321	搞不清楚这个函数的目的，你应该严格的遵守前面提到的长度限制。使用辅助函数，并为之
321	322	取个具描述性的名字（如果你觉得它们的性能很重要的话，可以让编译器内联它们，这样的
322	323	效果往往会比你写一个复杂函数的效果要好。）
323	324
324		−函数的另外一个衡量标准是本地变量的数量。此数量不应超过5－10个，否则你的函数就有
	325	+函数的另外一个衡量标准是本地变量的数量。此数量不应超过 5－10 个，否则你的函数就有
325	326	问题了。重新考虑一下你的函数，把它分拆成更小的函数。人的大脑一般可以轻松的同时跟
326		−踪7个不同的事物，如果再增多的话，就会糊涂了。即便你聪颖过人，你也可能会记不清你2
327		−个星期前做过的事情。
	327	+踪 7 个不同的事物，如果再增多的话，就会糊涂了。即便你聪颖过人，你也可能会记不清你
	328	+2 个星期前做过的事情。
328	329
329		−在源文件里，使用空行隔开不同的函数。如果该函数需要被导出，它的EXPORT*宏应该紧贴
	330	+在源文件里，使用空行隔开不同的函数。如果该函数需要被导出，它的 EXPORT* 宏应该紧贴
330	331	在它的结束大括号之下。比如：
331	332
332		−int system_is_up(void)
333		−{
334		− return system_state == SYSTEM_RUNNING;
335		−}
336		−EXPORT_SYMBOL(system_is_up);
	333	+ int system_is_up(void)
	334	+ {
	335	+ return system_state == SYSTEM_RUNNING;
	336	+ }
	337	+ EXPORT_SYMBOL(system_is_up);
337	338
338		−在函数原型中，包含函数名和它们的数据类型。虽然C语言里没有这样的要求，在Linux里这
	339	+在函数原型中，包含函数名和它们的数据类型。虽然C语言里没有这样的要求，在 Linux 里这
339	340	是提倡的做法，因为这样可以很简单的给读者提供更多的有价值的信息。
340	341
341	342
342	343	第七章：集中的函数退出途径
343	344
344		−虽然被某些人声称已经过时，但是goto语句的等价物还是经常被编译器所使用，具体形式是
	345	+虽然被某些人声称已经过时，但是 goto 语句的等价物还是经常被编译器所使用，具体形式是
345	346	无条件跳转指令。
346	347
347		−当一个函数从多个位置退出并且需要做一些通用的清理工作的时候，goto的好处就显现出来
348		−了。
	348	+当一个函数从多个位置退出，并且需要做一些类似清理的常见操作时，goto 语句就很方便了。
	349	+如果并不需要清理操作，那么直接 return 即可。
349	350
350	351	理由是：
351	352
@@ -354,26 +355,37 @@ EXPORT_SYMBOL(system_is_up); · 2 unmodified lines
354	355	- 可以避免由于修改时忘记更新某个单独的退出点而导致的错误
355	356	- 减轻了编译器的工作，无需删除冗余代码;)
356	357
357		−int fun(int a)
358		−{
359		− int result = 0;
360		− char *buffer = kmalloc(SIZE);
361		−
362		− if (buffer == NULL)
363		− return -ENOMEM;
364		−
365		− if (condition1) {
366		− while (loop1) {
367		− ...
	358	+ int fun(int a)
	359	+ {
	360	+ int result = 0;
	361	+ char *buffer;
	362	+
	363	+ buffer = kmalloc(SIZE, GFP_KERNEL);
	364	+ if (!buffer)
	365	+ return -ENOMEM;
	366	+
	367	+ if (condition1) {
	368	+ while (loop1) {
	369	+ ...
	370	+ }
	371	+ result = 1;
	372	+ goto out_buffer;
368	373	}
369		− result = 1;
370		− goto out;
	374	+ ...
	375	+ out_buffer:
	376	+ kfree(buffer);
	377	+ return result;
371	378	}
372		− ...
373		−out:
374		− kfree(buffer);
375		− return result;
376		−}
	379	+
	380	+一个需要注意的常见错误是“一个 err 错误”，就像这样：
	381	+
	382	+ err:
	383	+ kfree(foo->bar);
	384	+ kfree(foo);
	385	+ return ret;
	386	+
	387	+这段代码的错误是，在某些退出路径上 “foo” 是 NULL。通常情况下，通过把它分离成两个
	388	+错误标签 “err_bar:” 和 “err_foo:” 来修复这个错误。
377	389
378	390	第八章：注释
379	391
@@ -386,10 +398,10 @@ out: · 6 unmodified lines
386	398	加太多。你应该做的，是把注释放在函数的头部，告诉人们它做了什么，也可以加上它做这
387	399	些事情的原因。
388	400
389		−当注释内核API函数时，请使用kernel-doc格式。请看
390		−Documentation/kernel-doc-nano-HOWTO.txt和scripts/kernel-doc以获得详细信息。
	401	+当注释内核API函数时，请使用 kernel-doc 格式。请看
	402	+Documentation/kernel-documentation.rst和scripts/kernel-doc 以获得详细信息。
391	403
392		−Linux的注释风格是C89“/* ... */”风格。不要使用C99风格“// ...”注释。
	404	+Linux的注释风格是 C89 “/* ... */” 风格。不要使用 C99 风格 “// ...” 注释。
393	405
394	406	长（多行）的首选注释风格是：
395	407
@@ -402,6 +414,15 @@ Linux的注释风格是C89“/* ... */”风格。不要使用C99风格“// ... · 6 unmodified lines
402	414	* with beginning and ending almost-blank lines.
403	415	*/
404	416
	417	+对于在 net/ 和 drivers/net/ 的文件，首选的长（多行）注释风格有些不同。
	418	+
	419	+ /* The preferred comment style for files in net/ and drivers/net
	420	+ * looks like this.
	421	+ *
	422	+ * It is nearly the same as the generally preferred comment style,
	423	+ * but there is no initial almost-blank line.
	424	+ */
	425	+
405	426	注释数据也是很重要的，不管是基本类型还是衍生类型。为了方便实现这一点，每一行应只
406	427	声明一个数据（不要使用逗号来一次声明多个数据）。这样你就有空间来为每个数据写一段
407	428	小注释来解释它们的用途了。
@@ -409,49 +430,63 @@ Linux的注释风格是C89“/* ... */”风格。不要使用C99风格“// ... · 1 unmodified line
409	430
410	431	第九章：你已经把事情弄糟了
411	432
412		−这没什么，我们都是这样。可能你的使用了很长时间Unix的朋友已经告诉你“GNU emacs”能
413		−自动帮你格式化C源代码，而且你也注意到了，确实是这样，不过它所使用的默认值和我们
414		−想要的相去甚远（实际上，甚至比随机打的还要差——无数个猴子在GNU emacs里打字永远不
415		−会创造出一个好程序）（译注：请参考Infinite Monkey Theorem）
416		−
417		−所以你要么放弃GNU emacs，要么改变它让它使用更合理的设定。要采用后一个方案，你可
418		−以把下面这段粘贴到你的.emacs文件里。
419		−
420		−(defun linux-c-mode ()
421		− "C mode with adjusted defaults for use with the Linux kernel."
422		− (interactive)
423		− (c-mode)
424		− (c-set-style "K&R")
425		− (setq tab-width 8)
426		− (setq indent-tabs-mode t)
427		− (setq c-basic-offset 8))
428		−
429		−这样就定义了M-x linux-c-mode命令。当你hack一个模块的时候，如果你把字符串
430		−-- linux-c --放在头两行的某个位置，这个模式将会被自动调用。如果你希望在你修改
431		−/usr/src/linux里的文件时魔术般自动打开linux-c-mode的话，你也可能需要添加
432		−
433		−(setq auto-mode-alist (cons '("/usr/src/linux./.\\.[ch]$" . linux-c-mode)
434		− auto-mode-alist))
435		−
436		−到你的.emacs文件里。
437		−
438		−不过就算你尝试让emacs正确的格式化代码失败了，也并不意味着你失去了一切：还可以用“
439		−indent”。
440		−
441		−不过，GNU indent也有和GNU emacs一样有问题的设定，所以你需要给它一些命令选项。不
442		−过，这还不算太糟糕，因为就算是GNU indent的作者也认同K&R的权威性（GNU的人并不是坏
443		−人，他们只是在这个问题上被严重的误导了），所以你只要给indent指定选项“-kr -i8”
444		−（代表“K&R，8个字符缩进”），或者使用“scripts/Lindent”，这样就可以以最时髦的方式
	433	+这没什么，我们都是这样。可能你的使用了很长时间 Unix 的朋友已经告诉你 “GNU emacs” 能
	434	+自动帮你格式化 C 源代码，而且你也注意到了，确实是这样，不过它所使用的默认值和我们
	435	+想要的相去甚远（实际上，甚至比随机打的还要差——无数个猴子在 GNU emacs 里打字永远不
	436	+会创造出一个好程序）（译注：请参考 Infinite Monkey Theorem）
	437	+
	438	+所以你要么放弃 GNU emacs，要么改变它让它使用更合理的设定。要采用后一个方案，你可
	439	+以把下面这段粘贴到你的 .emacs 文件里。
	440	+
	441	+(defun c-lineup-arglist-tabs-only (ignored)
	442	+ "Line up argument lists by tabs, not spaces"
	443	+ (let* ((anchor (c-langelem-pos c-syntactic-element))
	444	+ (column (c-langelem-2nd-pos c-syntactic-element))
	445	+ (offset (- (1+ column) anchor))
	446	+ (steps (floor offset c-basic-offset)))
	447	+ (* (max steps 1)
	448	+ c-basic-offset)))
	449	+
	450	+(add-hook 'c-mode-common-hook
	451	+ (lambda ()
	452	+ ;; Add kernel style
	453	+ (c-add-style
	454	+ "linux-tabs-only"
	455	+ '("linux" (c-offsets-alist
	456	+ (arglist-cont-nonempty
	457	+ c-lineup-gcc-asm-reg
	458	+ c-lineup-arglist-tabs-only))))))
	459	+
	460	+(add-hook 'c-mode-hook
	461	+ (lambda ()
	462	+ (let ((filename (buffer-file-name)))
	463	+ ;; Enable kernel mode for the appropriate files
	464	+ (when (and filename
	465	+ (string-match (expand-file-name "~/src/linux-trees")
	466	+ filename))
	467	+ (setq indent-tabs-mode t)
	468	+ (setq show-trailing-whitespace t)
	469	+ (c-set-style "linux-tabs-only")))))
	470	+
	471	+这会让 emacs 在 ~/src/linux-trees 目录下的 C 源文件获得更好的内核代码风格。
	472	+
	473	+不过就算你尝试让 emacs 正确的格式化代码失败了，也并不意味着你失去了一切：还可以用
	474	+“indent”。
	475	+
	476	+不过，GNU indent 也有和 GNU emacs 一样有问题的设定，所以你需要给它一些命令选项。不
	477	+过，这还不算太糟糕，因为就算是 GNU indent 的作者也认同 K&R 的权威性（GNU 的人并不是
	478	+坏人，他们只是在这个问题上被严重的误导了），所以你只要给 indent 指定选项 “-kr -i8”
	479	+（代表 “K&R，8 个字符缩进”），或者使用 “scripts/Lindent”，这样就可以以最时髦的方式
445	480	缩进源代码。
446	481
447		−“indent”有很多选项，特别是重新格式化注释的时候，你可能需要看一下它的手册页。不过
448		−记住：“indent”不能修正坏的编程习惯。
	482	+“indent” 有很多选项，特别是重新格式化注释的时候，你可能需要看一下它的手册页。不过
	483	+记住：“indent” 不能修正坏的编程习惯。
449	484
450	485
451		− 第十章：Kconfig配置文件
	486	+ 第十章：Kconfig 配置文件
452	487
453		−对于遍布源码树的所有Kconfig*配置文件来说，它们缩进方式与C代码相比有所不同。紧挨
454		−在“config”定义下面的行缩进一个制表符，帮助信息则再多缩进2个空格。比如：
	488	+对于遍布源码树的所有 Kconfig* 配置文件来说，它们缩进方式与 C 代码相比有所不同。紧挨
	489	+在 “config” 定义下面的行缩进一个制表符，帮助信息则再多缩进 2 个空格。比如：
455	490
456	491	config AUDIT
457	492	bool "Auditing support"
@@ -470,7 +505,7 @@ config ADFS_FS_RW · 12 unmodified lines
470	505	depends on ADFS_FS
471	506	...
472	507
473		−要查看配置文件的完整文档，请看Documentation/kbuild/kconfig-language.txt。
	508	+要查看配置文件的完整文档，请看 Documentation/kbuild/kconfig-language.txt。
474	509
475	510
476	511	第十一章：数据结构
@@ -489,11 +524,11 @@ config ADFS_FS_RW · 12 unmodified lines
489	524	很多数据结构实际上有2级引用计数，它们通常有不同“类”的用户。子类计数器统计子类用
490	525	户的数量，每当子类计数器减至零时，全局计数器减一。
491	526
492		−这种“多级引用计数”的例子可以在内存管理（“struct mm_struct”：mm_users和mm_count）
	527	+这种“多级引用计数”的例子可以在内存管理（“struct mm_struct”：mm_users 和 mm_count）
493	528	和文件系统（“struct super_block”：s_count和s_active）中找到。
494	529
495	530	记住：如果另一个执行线索可以找到你的数据结构，但是这个数据结构没有引用计数器，这
496		−里几乎肯定是一个bug。
	531	+里几乎肯定是一个 bug。
497	532
498	533
499	534	第十二章：宏，枚举和RTL
@@ -508,102 +543,128 @@ config ADFS_FS_RW · 8 unmodified lines
508	543
509	544	一般的，如果能写成内联函数就不要写成像函数的宏。
510	545
511		−含有多个语句的宏应该被包含在一个do-while代码块里：
	546	+含有多个语句的宏应该被包含在一个 do-while 代码块里：
512	547
513		−#define macrofun(a, b, c) \
514		− do { \
515		− if (a == 5) \
516		− do_this(b, c); \
517		− } while (0)
	548	+ #define macrofun(a, b, c) \
	549	+ do { \
	550	+ if (a == 5) \
	551	+ do_this(b, c); \
	552	+ } while (0)
518	553
519	554	使用宏的时候应避免的事情：
520	555
521	556	1) 影响控制流程的宏：
522	557
523		−#define FOO(x) \
524		− do { \
525		− if (blah(x) < 0) \
526		− return -EBUGGERED; \
527		− } while(0)
	558	+ #define FOO(x) \
	559	+ do { \
	560	+ if (blah(x) < 0) \
	561	+ return -EBUGGERED; \
	562	+ } while (0)
528	563
529	564	非常不好。它看起来像一个函数，不过却能导致“调用”它的函数退出；不要打乱读者大脑里
530	565	的语法分析器。
531	566
532	567	2) 依赖于一个固定名字的本地变量的宏：
533	568
534		−#define FOO(val) bar(index, val)
	569	+ #define FOO(val) bar(index, val)
535	570
536	571	可能看起来像是个不错的东西，不过它非常容易把读代码的人搞糊涂，而且容易导致看起来
537	572	不相关的改动带来错误。
538	573
539		−3) 作为左值的带参数的宏： FOO(x) = y；如果有人把FOO变成一个内联函数的话，这种用
	574	+3) 作为左值的带参数的宏： FOO(x) = y；如果有人把 FOO 变成一个内联函数的话，这种用
540	575	法就会出错了。
541	576
542	577	4) 忘记了优先级：使用表达式定义常量的宏必须将表达式置于一对小括号之内。带参数的
543	578	宏也要注意此类问题。
544	579
545		−#define CONSTANT 0x4000
546		−#define CONSTEXP (CONSTANT \| 3)
	580	+ #define CONSTANT 0x4000
	581	+ #define CONSTEXP (CONSTANT \| 3)
	582	+
	583	+5) 在宏里定义类似函数的本地变量时命名冲突：
547	584
548		−cpp手册对宏的讲解很详细。Gcc internals手册也详细讲解了RTL（译注：register
	585	+ #define FOO(x) \
	586	+ ({ \
	587	+ typeof(x) ret; \
	588	+ ret = calc_ret(x); \
	589	+ (ret); \
	590	+ })
	591	+
	592	+ret 是本地变量的通用名字 - __foo_ret 更不容易与一个已存在的变量冲突。
	593	+
	594	+cpp 手册对宏的讲解很详细。gcc internals 手册也详细讲解了 RTL（译注：register
549	595	transfer language），内核里的汇编语言经常用到它。
550	596
551	597
552	598	第十三章：打印内核消息
553	599
554	600	内核开发者应该是受过良好教育的。请一定注意内核信息的拼写，以给人以好的印象。不要
555		−用不规范的单词比如“dont”，而要用“do not”或者“don't”。保证这些信息简单、明了、无
556		−歧义。
	601	+用不规范的单词比如 “dont”，而要用 “do not”或者 “don't”。保证这些信息简单、明了、
	602	+无歧义。
557	603
558	604	内核信息不必以句号（译注：英文句号，即点）结束。
559	605
560		−在小括号里打印数字(%d)没有任何价值，应该避免这样做。
	606	+在小括号里打印数字 (%d) 没有任何价值，应该避免这样做。
561	607
562		−<linux/device.h>里有一些驱动模型诊断宏，你应该使用它们，以确保信息对应于正确的
563		−设备和驱动，并且被标记了正确的消息级别。这些宏有：dev_err(), dev_warn(),
564		−dev_info()等等。对于那些不和某个特定设备相关连的信息，<linux/kernel.h>定义了
565		−pr_debug()和pr_info()。
	608	+<linux/device.h> 里有一些驱动模型诊断宏，你应该使用它们，以确保信息对应于正确的
	609	+设备和驱动，并且被标记了正确的消息级别。这些宏有：dev_err()，dev_warn()，
	610	+dev_info() 等等。对于那些不和某个特定设备相关连的信息，<linux/printk.h> 定义了
	611	+pr_notice()，pr_info()，pr_warn()，pr_err() 和其他。
566	612
567		−写出好的调试信息可以是一个很大的挑战；当你写出来之后，这些信息在远程除错的时候
568		−就会成为极大的帮助。当DEBUG符号没有被定义的时候，这些信息不应该被编译进内核里
569		−（也就是说，默认地，它们不应该被包含在内）。如果你使用dev_dbg()或者pr_debug()，
570		−就能自动达到这个效果。很多子系统拥有Kconfig选项来启用-DDEBUG。还有一个相关的惯例
571		−是使用VERBOSE_DEBUG来添加dev_vdbg()消息到那些已经由DEBUG启用的消息之上。
	613	+写出好的调试信息可以是一个很大的挑战；一旦你写出后，这些信息在远程除错时能提供极大
	614	+的帮助。然而打印调试信息的处理方式同打印非调试信息不同。其他 pr_XXX() 函数能无条件地
	615	+打印，pr_debug() 却不；默认情况下它不会被编译，除非定义了 DEBUG 或设定了
	616	+CONFIG_DYNAMIC_DEBUG。实际这同样是为了 dev_dbg()，一个相关约定是在一个已经开启了
	617	+DEBUG 时，使用 VERBOSE_DEBUG 来添加 dev_vdbg()。
	618	+
	619	+许多子系统拥有 Kconfig 调试选项来开启 -DDEBUG 在对应的 Makefile 里面；在其他
	620	+情况下，特殊文件使用 #define DEBUG。当一条调试信息需要被无条件打印时，例如，如果
	621	+已经包含一个调试相关的 #ifdef 条件，printk(KERN_DEBUG ...) 就可被使用。
572	622
573	623
574	624	第十四章：分配内存
575	625
576		−内核提供了下面的一般用途的内存分配函数：kmalloc()，kzalloc()，kcalloc()和
577		−vmalloc()。请参考API文档以获取有关它们的详细信息。
	626	+内核提供了下面的一般用途的内存分配函数：
	627	+kmalloc()，kzalloc()，kmalloc_array()，kcalloc()，vmalloc() 和 vzalloc()。
	628	+请参考 API 文档以获取有关它们的详细信息。
578	629
579	630	传递结构体大小的首选形式是这样的：
580	631
581	632	p = kmalloc(sizeof(*p), ...);
582	633
583		−另外一种传递方式中，sizeof的操作数是结构体的名字，这样会降低可读性，并且可能会引
584		−入bug。有可能指针变量类型被改变时，而对应的传递给内存分配函数的sizeof的结果不变。
	634	+另外一种传递方式中，sizeof 的操作数是结构体的名字，这样会降低可读性，并且可能会引
	635	+入 bug。有可能指针变量类型被改变时，而对应的传递给内存分配函数的 sizeof 的结果不变。
585	636
586		−强制转换一个void指针返回值是多余的。C语言本身保证了从void指针到其他任何指针类型
	637	+强制转换一个 void 指针返回值是多余的。C 语言本身保证了从 void 指针到其他任何指针类型
587	638	的转换是没有问题的。
588	639
	640	+分配一个数组的首选形式是这样的：
	641	+
	642	+ p = kmalloc_array(n, sizeof(...), ...);
	643	+
	644	+分配一个零长数组的首选形式是这样的：
	645	+
	646	+ p = kcalloc(n, sizeof(...), ...);
	647	+
	648	+两种形式检查分配大小 n * sizeof(...) 的溢出，如果溢出返回 NULL。
	649	+
589	650
590	651	第十五章：内联弊病
591	652
592		−有一个常见的误解是内联函数是gcc提供的可以让代码运行更快的一个选项。虽然使用内联
	653	+有一个常见的误解是内联函数是 gcc 提供的可以让代码运行更快的一个选项。虽然使用内联
593	654	函数有时候是恰当的（比如作为一种替代宏的方式，请看第十二章），不过很多情况下不是
594		−这样。inline关键字的过度使用会使内核变大，从而使整个系统运行速度变慢。因为大内核
	655	+这样。inline 关键字的过度使用会使内核变大，从而使整个系统运行速度变慢。因为大内核
595	656	会占用更多的指令高速缓存（译注：一级缓存通常是指令缓存和数据缓存分开的）而且会导
596		−致pagecache的可用内存减少。想象一下，一次pagecache未命中就会导致一次磁盘寻址，将
597		−耗时5毫秒。5毫秒的时间内CPU能执行很多很多指令。
	657	+致 pagecache 的可用内存减少。想象一下，一次pagecache未命中就会导致一次磁盘寻址，
	658	+将耗时 5 毫秒。5 毫秒的时间内 CPU 能执行很多很多指令。
598	659
599		−一个基本的原则是如果一个函数有3行以上，就不要把它变成内联函数。这个原则的一个例
	660	+一个基本的原则是如果一个函数有 3 行以上，就不要把它变成内联函数。这个原则的一个例
600	661	外是，如果你知道某个参数是一个编译时常量，而且因为这个常量你确定编译器在编译时能
601		−优化掉你的函数的大部分代码，那仍然可以给它加上inline关键字。kmalloc()内联函数就
	662	+优化掉你的函数的大部分代码，那仍然可以给它加上 inline 关键字。kmalloc() 内联函数就
602	663	是一个很好的例子。
603	664
604		−人们经常主张给static的而且只用了一次的函数加上inline，如此不会有任何损失，因为没
605		−有什么好权衡的。虽然从技术上说这是正确的，但是实际上这种情况下即使不加inline gcc
606		−也可以自动使其内联。而且其他用户可能会要求移除inline，由此而来的争论会抵消inline
	665	+人们经常主张给 static 的而且只用了一次的函数加上 inline，如此不会有任何损失，因为没
	666	+有什么好权衡的。虽然从技术上说这是正确的，但是实际上这种情况下即使不加 inline gcc
	667	+也可以自动使其内联。而且其他用户可能会要求移除 inline，由此而来的争论会抵消 inline
607	668	自身的潜在价值，得不偿失。
608	669
609	670
@@ -613,37 +674,37 @@ vmalloc()。请参考API文档以获取有关它们的详细信息。 · 3 unmodified lines
613	674	的一个值可以表示为一个错误代码整数（-Exxx＝失败，0＝成功）或者一个“成功”布尔值（
614	675	0＝失败，非0＝成功）。
615	676
616		−混合使用这两种表达方式是难于发现的bug的来源。如果C语言本身严格区分整形和布尔型变
617		−量，那么编译器就能够帮我们发现这些错误……不过C语言不区分。为了避免产生这种bug，请
	677	+混合使用这两种表达方式是难于发现的 bug 的来源。如果 C 语言本身严格区分整形和布尔型变
	678	+量，那么编译器就能够帮我们发现这些错误……不过 C 语言不区分。为了避免产生这种 bug，请
618	679	遵循下面的惯例：
619	680
620	681	如果函数的名字是一个动作或者强制性的命令，那么这个函数应该返回错误代码整
621	682	数。如果是一个判断，那么函数应该返回一个“成功”布尔值。
622	683
623		−比如，“add work”是一个命令，所以add_work()函数在成功时返回0，在失败时返回-EBUSY。
624		−类似的，因为“PCI device present”是一个判断，所以pci_dev_present()函数在成功找到
625		−一个匹配的设备时应该返回1，如果找不到时应该返回0。
	684	+比如，“add work” 是一个命令，所以 add_work() 函数在成功时返回 0，在失败时返回 -EBUSY。
	685	+类似的，因为 “PCI device present” 是一个判断，所以 pci_dev_present() 函数在成功找到
	686	+一个匹配的设备时应该返回 1，如果找不到时应该返回 0。
626	687
627	688	所有导出（译注：EXPORT）的函数都必须遵守这个惯例，所有的公共函数也都应该如此。私
628	689	有（static）函数不需要如此，但是我们也推荐这样做。
629	690
630	691	返回值是实际计算结果而不是计算是否成功的标志的函数不受此惯例的限制。一般的，他们
631	692	通过返回一些正常值范围之外的结果来表示出错。典型的例子是返回指针的函数，他们使用
632		−NULL或者ERR_PTR机制来报告错误。
	693	+NULL 或者 ERR_PTR 机制来报告错误。
633	694
634	695
635	696	第十七章：不要重新发明内核宏
636	697
637		−头文件include/linux/kernel.h包含了一些宏，你应该使用它们，而不要自己写一些它们的
	698	+头文件 include/linux/kernel.h 包含了一些宏，你应该使用它们，而不要自己写一些它们的
638	699	变种。比如，如果你需要计算一个数组的长度，使用这个宏
639	700
640		− #define ARRAY_SIZE(x) (sizeof(x) / sizeof((x)[0]))
	701	+ #define ARRAY_SIZE(x) (sizeof(x) / sizeof((x)[0]))
641	702
642	703	类似的，如果你要计算某结构体成员的大小，使用
643	704
644		− #define FIELD_SIZEOF(t, f) (sizeof(((t*)0)->f))
	705	+ #define FIELD_SIZEOF(t, f) (sizeof(((t*)0)->f))
645	706
646		−还有可以做严格的类型检查的min()和max()宏，如果你需要可以使用它们。你可以自己看看
	707	+还有可以做严格的类型检查的 min() 和 max() 宏，如果你需要可以使用它们。你可以自己看看
647	708	那个头文件里还定义了什么你可以拿来用的东西，如果有定义的话，你就不应在你的代码里
648	709	自己重新定义。
649	710
@@ -653,42 +714,100 @@ NULL或者ERR_PTR机制来报告错误。 · 3 unmodified lines
653	714	有一些编辑器可以解释嵌入在源文件里的由一些特殊标记标明的配置信息。比如，emacs
654	715	能够解释被标记成这样的行：
655	716
656		−-- mode: c --
	717	+ -- mode: c --
657	718
658	719	或者这样的：
659	720
660		−/*
661		−Local Variables:
662		−compile-command: "gcc -DMAGIC_DEBUG_FLAG foo.c"
663		−End:
664		−*/
	721	+ /*
	722	+ Local Variables:
	723	+ compile-command: "gcc -DMAGIC_DEBUG_FLAG foo.c"
	724	+ End:
	725	+ */
665	726
666		−Vim能够解释这样的标记：
	727	+Vim 能够解释这样的标记：
667	728
668		−/* vim:set sw=8 noet */
	729	+ /* vim:set sw=8 noet */
669	730
670	731	不要在源代码中包含任何这样的内容。每个人都有他自己的编辑器配置，你的源文件不应
671	732	该覆盖别人的配置。这包括有关缩进和模式配置的标记。人们可以使用他们自己定制的模
672	733	式，或者使用其他可以产生正确的缩进的巧妙方法。
673	734
674	735
	736	+ 第十九章：内联汇编
	737	+
	738	+在特定架构的代码中，你也许需要内联汇编来使用 CPU 接口和平台相关功能。在需要
	739	+这么做时，不要犹豫。然而，当 C 可以完成工作时，不要无端地使用内联汇编。如果
	740	+可能，你可以并且应该用 C 和硬件交互。
	741	+
	742	+考虑去写通用一点的内联汇编作为简明的辅助函数，而不是重复写下它们的细节。记住
	743	+内联汇编可以使用 C 参数。
	744	+
	745	+大而特殊的汇编函数应该放在 .S 文件中，对应 C 的原型定义在 C 头文件中。汇编
	746	+函数的 C 原型应该使用 “asmlinkage”。
	747	+
	748	+你可能需要将你的汇编语句标记为 volatile，来阻止 GCC 在没发现任何副作用后就
	749	+移除了它。你不必总是这样做，虽然，这样可以限制不必要的优化。
	750	+
	751	+在写一个包含多条指令的单个内联汇编语句时，把每条指令用引号字符串分离，并写在
	752	+单独一行，在每个字符串结尾，除了 \n\t 结尾之外，在汇编输出中适当地缩进下
	753	+一条指令：
	754	+
	755	+ asm ("magic %reg1, #42\n\t"
	756	+ "more_magic %reg2, %reg3"
	757	+ : /* outputs / : / inputs / : / clobbers */);
	758	+
	759	+
	760	+ 第二十章：条件编译
	761	+
	762	+只要可能，就不要在 .c 文件里面使用预处理条件；这样做让代码更难阅读并且逻辑难以
	763	+跟踪。替代方案是，在头文件定义函数在这些 .c 文件中使用这类的条件表达式，提供空
	764	+操作的桩版本（译注：桩程序，是指用来替换一部分功能的程序段）在 #else 情况下，
	765	+再从 .c 文件中无条件地调用这些函数。编译器会避免生成任何桩调用的代码，产生一致
	766	+的结果，但逻辑将更加清晰。
	767	+
	768	+宁可编译整个函数，而不是部分函数或部分表达式。而不是在一个表达式添加 ifdef，
	769	+解析部分或全部表达式到一个单独的辅助函数，并应用条件到该函数内。
	770	+
	771	+如果你有一个在特定配置中可能是未使用的函数或变量，编译器将警告它定义了但未使用，
	772	+标记这个定义为 __maybe_unused 而不是将它包含在一个预处理条件中。（然而，如果
	773	+一个函数或变量总是未使用的，就直接删除它。）
	774	+
	775	+在代码中，可能的情况下，使用 IS_ENABLED 宏来转化某个 Kconfig 标记为 C 的布尔
	776	+表达式，并在正常的 C 条件中使用它：
	777	+
	778	+ if (IS_ENABLED(CONFIG_SOMETHING)) {
	779	+ ...
	780	+ }
	781	+
	782	+编译器会无条件地做常数合并，就像使用 #ifdef 那样，包含或排除代码块，所以这不会
	783	+带来任何运行时开销。然而，这种方法依旧允许 C 编译器查看块内的代码，并检查它的正确
	784	+性（语法，类型，符号引用，等等）。因此，如果条件不满足，代码块内的引用符号将不存在，
	785	+你必须继续使用 #ifdef。
	786	+
	787	+在任何有意义的 #if 或 #ifdef 块的末尾（超过几行），在 #endif 同一行的后面写下
	788	+注释，指出该条件表达式被使用。例如：
	789	+
	790	+ #ifdef CONFIG_SOMETHING
	791	+ ...
	792	+ #endif /* CONFIG_SOMETHING */
	793	+
675	794
676	795	附录 I：参考
677	796
678		−The C Programming Language, 第二版, 作者Brian W. Kernighan和Denni
679		−M. Ritchie. Prentice Hall, Inc., 1988. ISBN 0-13-110362-8 (软皮),
680		−0-13-110370-9 (硬皮). URL: http://cm.bell-labs.com/cm/cs/cbook/
	797	+The C Programming Language, 第二版
	798	+作者：Brian W. Kernighan 和 Denni M. Ritchie.
	799	+Prentice Hall, Inc., 1988.
	800	+ISBN 0-13-110362-8 (软皮), 0-13-110370-9 (硬皮).
681	801
682		−The Practice of Programming 作者Brian W. Kernighan和Rob Pike. Addison-Wesley,
683		−Inc., 1999. ISBN 0-201-61586-X. URL: http://cm.bell-labs.com/cm/cs/tpop/
	802	+The Practice of Programming
	803	+作者：Brian W. Kernighan 和 Rob Pike.
	804	+Addison-Wesley, Inc., 1999.
	805	+ISBN 0-201-61586-X.
684	806
685		−cpp，gcc，gcc internals和indent的GNU手册——和K&R及本文相符合的部分，全部可以在
686		−http://www.gnu.org/manual/找到
	807	+GNU 手册 - 遵循 K&R 标准和此文本 - cpp, gcc, gcc internals and indent,
	808	+都可以从 http://www.gnu.org/manual/ 找到
687	809
688	810	WG14是C语言的国际标准化工作组，URL: http://www.open-std.org/JTC1/SC22/WG14/
689	811
690		−Kernel CodingStyle，作者greg@kroah.com发表于OLS 2002：
	812	+Kernel CodingStyle，作者 greg@kroah.com 发表于OLS 2002：
691	813	http://www.kroah.com/linux/talks/ols_2002_kernel_codingstyle_talk/html/
692		−
693		−--
694		−最后更新于2007年7月13日。

Makefile+6−1

@@ -1366,6 +1366,8 @@ help: · 1365 unmodified lines
1366	1366	@$(MAKE) $(build)=$(package-dir) help
1367	1367	@echo ''
1368	1368	@echo 'Documentation targets:'
	1369	+ @$(MAKE) -f $(srctree)/Documentation/Makefile.sphinx dochelp
	1370	+ @echo ''
1369	1371	@$(MAKE) -f $(srctree)/Documentation/DocBook/Makefile dochelp
1370	1372	@echo ''
1371	1373	@echo 'Architecture specific targets ($(SRCARCH)):'
@@ -1414,8 +1416,11 @@ $(help-board-dirs): help-%: · 42 unmodified lines
1414	1416
1415	1417	# Documentation targets
1416	1418	# ---------------------------------------------------------------------------
1417		−%docs: scripts_basic FORCE
	1419	+DOC_TARGETS := xmldocs sgmldocs psdocs pdfdocs htmldocs mandocs installmandocs epubdocs cleandocs cleanmediadocs
	1420	+PHONY += $(DOC_TARGETS)
	1421	+$(DOC_TARGETS): scripts_basic FORCE
1418	1422	$(Q)$(MAKE) $(build)=scripts build_docproc build_check-lc_ctype
	1423	+ $(Q)$(MAKE) $(build)=Documentation -f $(srctree)/Documentation/Makefile.sphinx $@
1419	1424	$(Q)$(MAKE) $(build)=Documentation/DocBook $@
1420	1425
1421	1426	else # KBUILD_EXTMOD

scripts/kernel-doc+306−151

@@ -59,6 +59,12 @@ Output format selection (mutually exclusive): · 58 unmodified lines
59	59	-text Output plain text format.
60	60
61	61	Output selection (mutually exclusive):
	62	+ -export Only output documentation for symbols that have been
	63	+ exported using EXPORT_SYMBOL() or EXPORT_SYMBOL_GPL()
	64	+ in any input FILE or -export-file FILE.
	65	+ -internal Only output documentation for symbols that have NOT been
	66	+ exported using EXPORT_SYMBOL() or EXPORT_SYMBOL_GPL()
	67	+ in any input FILE or -export-file FILE.
62	68	-function NAME Only output documentation for the given function(s)
63	69	or DOC: section title(s). All other functions and DOC:
64	70	sections are ignored. May be specified multiple times.
@@ -68,6 +74,11 @@ Output selection (mutually exclusive): · 3 unmodified lines
68	74
69	75	Output selection modifiers:
70	76	-no-doc-sections Do not output DOC: sections.
	77	+ -enable-lineno Enable output of #define LINENO lines. Only works with
	78	+ reStructuredText format.
	79	+ -export-file FILE Specify an additional FILE in which to look for
	80	+ EXPORT_SYMBOL() and EXPORT_SYMBOL_GPL(). To be used with
	81	+ -export or -internal. May be specified multiple times.
71	82
72	83	Other parameters:
73	84	-v Verbose output, more warnings and other information.
@@ -206,6 +217,10 @@ my $type_struct_xml = '\\&((struct\s)[_\w]+)'; · 132 unmodified lines
206	217	my $type_env = '(\$\w+)';
207	218	my $type_enum_full = '\&(enum)\s*([_\w]+)';
208	219	my $type_struct_full = '\&(struct)\s*([_\w]+)';
	220	+my $type_typedef_full = '\&(typedef)\s*([_\w]+)';
	221	+my $type_union_full = '\&(union)\s*([_\w]+)';
	222	+my $type_member = '\&([_\w]+)((\.\|->)[_\w]+)';
	223	+my $type_member_func = $type_member . '';
209	224
210	225	# Output conversion substitutions.
211	226	# One for each output format
@@ -274,10 +289,16 @@ my $blankline_text = ""; · 62 unmodified lines
274	289	# rst-mode
275	290	my @highlights_rst = (
276	291	[$type_constant, "``\$1``"],
277		− [$type_func, "\\:c\\:func\\:`\$1`"],
	292	+ # Note: need to escape () to avoid func matching later
	293	+ [$type_member_func, "\\:c\\:type\\:`\$1\$2\\\$\\\$ <\$1>`"],
	294	+ [$type_member, "\\:c\\:type\\:`\$1\$2 <\$1>`"],
	295	+ [$type_func, "\\:c\\:func\\:`\$1()`"],
278	296	[$type_struct_full, "\\:c\\:type\\:`\$1 \$2 <\$2>`"],
279	297	[$type_enum_full, "\\:c\\:type\\:`\$1 \$2 <\$2>`"],
280		− [$type_struct, "\\:c\\:type\\:`struct \$1 <\$1>`"],
	298	+ [$type_typedef_full, "\\:c\\:type\\:`\$1 \$2 <\$2>`"],
	299	+ [$type_union_full, "\\:c\\:type\\:`\$1 \$2 <\$2>`"],
	300	+ # in rst this can refer to any type
	301	+ [$type_struct, "\\:c\\:type\\:`\$1`"],
281	302	[$type_param, "\$1"]
282	303	);
283	304	my $blankline_rst = "\n";
@@ -303,12 +324,23 @@ my $verbose = 0; · 19 unmodified lines
303	324	my $output_mode = "man";
304	325	my $output_preformatted = 0;
305	326	my $no_doc_sections = 0;
	327	+my $enable_lineno = 0;
306	328	my @highlights = @highlights_man;
307	329	my $blankline = $blankline_man;
308	330	my $modulename = "Kernel API";
309		−my $function_only = 0;
	331	+
	332	+use constant {
	333	+ OUTPUT_ALL => 0, # output all symbols and doc sections
	334	+ OUTPUT_INCLUDE => 1, # output only specified symbols
	335	+ OUTPUT_EXCLUDE => 2, # output everything except specified symbols
	336	+ OUTPUT_EXPORTED => 3, # output exported symbols
	337	+ OUTPUT_INTERNAL => 4, # output non-exported symbols
	338	+};
	339	+my $output_selection = OUTPUT_ALL;
310	340	my $show_not_found = 0;
311	341
	342	+my @export_file_list;
	343	+
312	344	my @build_time;
313	345	if (defined($ENV{'KBUILD_BUILD_TIMESTAMP'}) &&
314	346	(my $seconds = `date -d"${ENV{'KBUILD_BUILD_TIMESTAMP'}}" +%s`) ne '') {
@@ -327,6 +359,7 @@ my $man_date = ('January', 'February', 'March', 'April', 'May', 'June', · 12 unmodified lines
327	359	# CAVEAT EMPTOR! Some of the others I localised may not want to be, which
328	360	# could cause "use of undefined value" or other bugs.
329	361	my ($function, %function_table, %parametertypes, $declaration_purpose);
	362	+my $declaration_start_line;
330	363	my ($type, $declaration_name, $return_type);
331	364	my ($newsection, $newcontents, $prototype, $brcount, %source_map);
332	365
@@ -344,52 +377,62 @@ my $section_counter = 0; · 11 unmodified lines
344	377
345	378	my $lineprefix="";
346	379
347		−# states
348		−# 0 - normal code
349		−# 1 - looking for function name
350		−# 2 - scanning field start.
351		−# 3 - scanning prototype.
352		−# 4 - documentation block
353		−# 5 - gathering documentation outside main block
	380	+# Parser states
	381	+use constant {
	382	+ STATE_NORMAL => 0, # normal code
	383	+ STATE_NAME => 1, # looking for function name
	384	+ STATE_FIELD => 2, # scanning field start
	385	+ STATE_PROTO => 3, # scanning prototype
	386	+ STATE_DOCBLOCK => 4, # documentation block
	387	+ STATE_INLINE => 5, # gathering documentation outside main block
	388	+};
354	389	my $state;
355	390	my $in_doc_sect;
356	391
357		−# Split Doc State
358		−# 0 - Invalid (Before start or after finish)
359		−# 1 - Is started (the /** was found inside a struct)
360		−# 2 - The @parameter header was found, start accepting multi paragraph text.
361		−# 3 - Finished (the */ was found)
362		−# 4 - Error - Comment without header was found. Spit a warning as it's not
363		−# proper kernel-doc and ignore the rest.
364		−my $split_doc_state;
	392	+# Inline documentation state
	393	+use constant {
	394	+ STATE_INLINE_NA => 0, # not applicable ($state != STATE_INLINE)
	395	+ STATE_INLINE_NAME => 1, # looking for member name (@foo:)
	396	+ STATE_INLINE_TEXT => 2, # looking for member documentation
	397	+ STATE_INLINE_END => 3, # done
	398	+ STATE_INLINE_ERROR => 4, # error - Comment without header was found.
	399	+ # Spit a warning as it's not
	400	+ # proper kernel-doc and ignore the rest.
	401	+};
	402	+my $inline_doc_state;
365	403
366	404	#declaration types: can be
367	405	# 'function', 'struct', 'union', 'enum', 'typedef'
368	406	my $decl_type;
369	407
370		−my $doc_special = "\@\%\$\&";
371		−
372	408	my $doc_start = '^/\\\s*$'; # Allow whitespace at end of comment start.
373	409	my $doc_end = '\*/';
374	410	my $doc_com = '\s\\s*';
375	411	my $doc_com_body = '\s\ ?';
376	412	my $doc_decl = $doc_com . '(\w+)';
377		−my $doc_sect = $doc_com . '([' . $doc_special . ']?[\w\s]+):(.*)';
	413	+# @params and a strictly limited set of supported section names
	414	+my $doc_sect = $doc_com .
	415	+ '\s(\@\w+\|description\|context\|returns?\|notes?\|examples?)\s:(.*)';
378	416	my $doc_content = $doc_com_body . '(.*)';
379	417	my $doc_block = $doc_com . 'DOC:\s(.)?';
380		−my $doc_split_start = '^\s/\\\s$';
381		−my $doc_split_sect = '\s\\s(@[\w\s]+):(.)';
382		−my $doc_split_end = '^\s\/\s*$';
	418	+my $doc_inline_start = '^\s/\\\s$';
	419	+my $doc_inline_sect = '\s\\s(@[\w\s]+):(.)';
	420	+my $doc_inline_end = '^\s\/\s*$';
	421	+my $export_symbol = '^\sEXPORT_SYMBOL(_GPL)?\s$\s(\w+)\s$\s*;';
383	422
384		−my %constants;
385	423	my %parameterdescs;
	424	+my %parameterdesc_start_lines;
386	425	my @parameterlist;
387	426	my %sections;
388	427	my @sectionlist;
	428	+my %section_start_lines;
389	429	my $sectcheck;
390	430	my $struct_actual;
391	431
392	432	my $contents = "";
	433	+my $new_start_line = 0;
	434	+
	435	+# the canonical section names. see also $doc_sect above.
393	436	my $section_default = "Description"; # default section
394	437	my $section_intro = "Introduction";
395	438	my $section = $section_default;
@@ -437,19 +480,30 @@ while ($ARGV[0] =~ m/^-(.*)/) { · 41 unmodified lines
437	480	} elsif ($cmd eq "-module") { # not needed for XML, inherits from calling document
438	481	$modulename = shift @ARGV;
439	482	} elsif ($cmd eq "-function") { # to only output specific functions
440		− $function_only = 1;
	483	+ $output_selection = OUTPUT_INCLUDE;
441	484	$function = shift @ARGV;
442	485	$function_table{$function} = 1;
443		− } elsif ($cmd eq "-nofunction") { # to only output specific functions
444		− $function_only = 2;
	486	+ } elsif ($cmd eq "-nofunction") { # output all except specific functions
	487	+ $output_selection = OUTPUT_EXCLUDE;
445	488	$function = shift @ARGV;
446	489	$function_table{$function} = 1;
	490	+ } elsif ($cmd eq "-export") { # only exported symbols
	491	+ $output_selection = OUTPUT_EXPORTED;
	492	+ %function_table = ();
	493	+ } elsif ($cmd eq "-internal") { # only non-exported symbols
	494	+ $output_selection = OUTPUT_INTERNAL;
	495	+ %function_table = ();
	496	+ } elsif ($cmd eq "-export-file") {
	497	+ my $file = shift @ARGV;
	498	+ push(@export_file_list, $file);
447	499	} elsif ($cmd eq "-v") {
448	500	$verbose = 1;
449	501	} elsif (($cmd eq "-h") \|\| ($cmd eq "--help")) {
450	502	usage();
451	503	} elsif ($cmd eq '-no-doc-sections') {
452	504	$no_doc_sections = 1;
	505	+ } elsif ($cmd eq '-enable-lineno') {
	506	+ $enable_lineno = 1;
453	507	} elsif ($cmd eq '-show-not-found') {
454	508	$show_not_found = 1;
455	509	}
@@ -467,6 +521,13 @@ sub get_kernel_version() { · 11 unmodified lines
467	521	return $version;
468	522	}
469	523
	524	+#
	525	+sub print_lineno {
	526	+ my $lineno = shift;
	527	+ if ($enable_lineno && defined($lineno)) {
	528	+ print "#define LINENO " . $lineno . "\n";
	529	+ }
	530	+}
470	531	##
471	532	# dumps section contents to arrays/hashes intended for that purpose.
472	533	#
@@ -475,28 +536,32 @@ sub dump_section { · 2 unmodified lines
475	536	my $name = shift;
476	537	my $contents = join "\n", @_;
477	538
478		− if ($name =~ m/$type_constant/) {
479		− $name = $1;
480		−# print STDERR "constant section '$1' = '$contents'\n";
481		− $constants{$name} = $contents;
482		− } elsif ($name =~ m/$type_param/) {
483		−# print STDERR "parameter def '$1' = '$contents'\n";
	539	+ if ($name =~ m/$type_param/) {
484	540	$name = $1;
485	541	$parameterdescs{$name} = $contents;
486	542	$sectcheck = $sectcheck . $name . " ";
	543	+ $parameterdesc_start_lines{$name} = $new_start_line;
	544	+ $new_start_line = 0;
487	545	} elsif ($name eq "@\.\.\.") {
488		−# print STDERR "parameter def '...' = '$contents'\n";
489	546	$name = "...";
490	547	$parameterdescs{$name} = $contents;
491	548	$sectcheck = $sectcheck . $name . " ";
	549	+ $parameterdesc_start_lines{$name} = $new_start_line;
	550	+ $new_start_line = 0;
492	551	} else {
493		−# print STDERR "other section '$name' = '$contents'\n";
494	552	if (defined($sections{$name}) && ($sections{$name} ne "")) {
495		− print STDERR "${file}:$.: error: duplicate section name '$name'\n";
496		− ++$errors;
	553	+ # Only warn on user specified duplicate section names.
	554	+ if ($name ne $section_default) {
	555	+ print STDERR "${file}:$.: warning: duplicate section name '$name'\n";
	556	+ ++$warnings;
	557	+ }
	558	+ $sections{$name} .= $contents;
	559	+ } else {
	560	+ $sections{$name} = $contents;
	561	+ push @sectionlist, $name;
	562	+ $section_start_lines{$name} = $new_start_line;
	563	+ $new_start_line = 0;
497	564	}
498		− $sections{$name} = $contents;
499		− push @sectionlist, $name;
500	565	}
501	566	}
502	567
@@ -512,15 +577,17 @@ sub dump_doc_section { · 9 unmodified lines
512	577	return;
513	578	}
514	579
515		− if (($function_only == 0) \|\|
516		− ( $function_only == 1 && defined($function_table{$name})) \|\|
517		− ( $function_only == 2 && !defined($function_table{$name})))
	580	+ if (($output_selection == OUTPUT_ALL) \|\|
	581	+ ($output_selection == OUTPUT_INCLUDE &&
	582	+ defined($function_table{$name})) \|\|
	583	+ ($output_selection == OUTPUT_EXCLUDE &&
	584	+ !defined($function_table{$name})))
518	585	{
519	586	dump_section($file, $name, $contents);
520	587	output_blockhead({'sectionlist' => \@sectionlist,
521	588	'sections' => \%sections,
522	589	'module' => $modulename,
523		− 'content-only' => ($function_only != 0), });
	590	+ 'content-only' => ($output_selection != OUTPUT_ALL), });
524	591	}
525	592	}
526	593
@@ -1736,7 +1803,10 @@ sub output_blockhead_rst(%) { · 1209 unmodified lines
1736	1803	my ($parameter, $section);
1737	1804
1738	1805	foreach $section (@{$args{'sectionlist'}}) {
1739		− print "$section\n\n";
	1806	+ if ($output_selection != OUTPUT_INCLUDE) {
	1807	+ print "$section\n\n";
	1808	+ }
	1809	+ print_lineno($section_start_lines{$section});
1740	1810	output_highlight_rst($args{'sections'}{$section});
1741	1811	print "\n";
1742	1812	}
@@ -1753,19 +1823,14 @@ sub output_highlight_rst { · 10 unmodified lines
1753	1823	die $@ if $@;
1754	1824
1755	1825	foreach $line (split "\n", $contents) {
1756		− if ($line eq "") {
1757		− print $lineprefix, $blankline;
1758		− } else {
1759		− $line =~ s/\\\\\\/\&/g;
1760		− print $lineprefix, $line;
1761		− }
1762		− print "\n";
	1826	+ print $lineprefix . $line . "\n";
1763	1827	}
1764	1828	}
1765	1829
1766	1830	sub output_function_rst(%) {
1767	1831	my %args = %{$_[0]};
1768	1832	my ($parameter, $section);
	1833	+ my $oldprefix = $lineprefix;
1769	1834	my $start;
1770	1835
1771	1836	print ".. c:function:: ";
@@ -1783,6 +1848,10 @@ sub output_function_rst(%) { · 11 unmodified lines
1783	1848	}
1784	1849	$count++;
1785	1850	$type = $args{'parametertypes'}{$parameter};
	1851	+
	1852	+ # RST doesn't like address_space tags at function prototypes
	1853	+ $type =~ s/__(user\|kernel\|iomem\|percpu\|pmem\|rcu)\s*//;
	1854	+
1786	1855	if ($type =~ m/([^$]\(\)\s$\s$([^$]*)\)/) {
1787	1856	# pointer-to-function
1788	1857	print $1 . $parameter . ") (" . $2;
@@ -1790,29 +1859,37 @@ sub output_function_rst(%) { · 1 unmodified line
1790	1859	print $type . " " . $parameter;
1791	1860	}
1792	1861	}
1793		− print ")\n\n " . $args{'purpose'} . "\n\n";
	1862	+ print ")\n\n";
	1863	+ print_lineno($declaration_start_line);
	1864	+ $lineprefix = " ";
	1865	+ output_highlight_rst($args{'purpose'});
	1866	+ print "\n";
1794	1867
1795		− print ":Parameters:\n\n";
	1868	+ print "Parameters\n\n";
	1869	+ $lineprefix = " ";
1796	1870	foreach $parameter (@{$args{'parameterlist'}}) {
1797	1871	my $parameter_name = $parameter;
1798	1872	#$parameter_name =~ s/\[.*//;
1799	1873	$type = $args{'parametertypes'}{$parameter};
1800	1874
1801	1875	if ($type ne "") {
1802		− print " ``$type $parameter``\n";
	1876	+ print "``$type $parameter``\n";
1803	1877	} else {
1804		− print " ``$parameter``\n";
	1878	+ print "``$parameter``\n";
1805	1879	}
1806		− if ($args{'parameterdescs'}{$parameter_name} ne $undescribed) {
1807		− my $oldprefix = $lineprefix;
1808		− $lineprefix = " ";
	1880	+
	1881	+ print_lineno($parameterdesc_start_lines{$parameter_name});
	1882	+
	1883	+ if (defined($args{'parameterdescs'}{$parameter_name}) &&
	1884	+ $args{'parameterdescs'}{$parameter_name} ne $undescribed) {
1809	1885	output_highlight_rst($args{'parameterdescs'}{$parameter_name});
1810		− $lineprefix = $oldprefix;
1811	1886	} else {
1812		− print "\n _undescribed_\n";
	1887	+ print " undescribed\n";
1813	1888	}
1814	1889	print "\n";
1815	1890	}
	1891	+
	1892	+ $lineprefix = $oldprefix;
1816	1893	output_section_rst(@_);
1817	1894	}
1818	1895
@@ -1820,10 +1897,11 @@ sub output_section_rst(%) { · 1 unmodified line
1820	1897	my %args = %{$_[0]};
1821	1898	my $section;
1822	1899	my $oldprefix = $lineprefix;
1823		− $lineprefix = " ";
	1900	+ $lineprefix = "";
1824	1901
1825	1902	foreach $section (@{$args{'sectionlist'}}) {
1826		− print ":$section:\n\n";
	1903	+ print "$section\n\n";
	1904	+ print_lineno($section_start_lines{$section});
1827	1905	output_highlight_rst($args{'sections'}{$section});
1828	1906	print "\n";
1829	1907	}
@@ -1834,24 +1912,28 @@ sub output_section_rst(%) { · 4 unmodified lines
1834	1912	sub output_enum_rst(%) {
1835	1913	my %args = %{$_[0]};
1836	1914	my ($parameter);
	1915	+ my $oldprefix = $lineprefix;
1837	1916	my $count;
1838	1917	my $name = "enum " . $args{'enum'};
1839	1918
1840	1919	print "\n\n.. c:type:: " . $name . "\n\n";
1841		− print " " . $args{'purpose'} . "\n\n";
	1920	+ print_lineno($declaration_start_line);
	1921	+ $lineprefix = " ";
	1922	+ output_highlight_rst($args{'purpose'});
	1923	+ print "\n";
1842	1924
1843		− print "..\n\n:Constants:\n\n";
1844		− my $oldprefix = $lineprefix;
1845		− $lineprefix = " ";
	1925	+ print "Constants\n\n";
	1926	+ $lineprefix = " ";
1846	1927	foreach $parameter (@{$args{'parameterlist'}}) {
1847		− print " `$parameter`\n";
	1928	+ print "``$parameter``\n";
1848	1929	if ($args{'parameterdescs'}{$parameter} ne $undescribed) {
1849	1930	output_highlight_rst($args{'parameterdescs'}{$parameter});
1850	1931	} else {
1851		− print " undescribed\n";
	1932	+ print " undescribed\n";
1852	1933	}
1853	1934	print "\n";
1854	1935	}
	1936	+
1855	1937	$lineprefix = $oldprefix;
1856	1938	output_section_rst(@_);
1857	1939	}
@@ -1859,30 +1941,37 @@ sub output_enum_rst(%) { · 1 unmodified line
1859	1941	sub output_typedef_rst(%) {
1860	1942	my %args = %{$_[0]};
1861	1943	my ($parameter);
1862		− my $count;
	1944	+ my $oldprefix = $lineprefix;
1863	1945	my $name = "typedef " . $args{'typedef'};
1864	1946
1865		− ### FIXME: should the name below contain "typedef" or not?
1866	1947	print "\n\n.. c:type:: " . $name . "\n\n";
1867		− print " " . $args{'purpose'} . "\n\n";
	1948	+ print_lineno($declaration_start_line);
	1949	+ $lineprefix = " ";
	1950	+ output_highlight_rst($args{'purpose'});
	1951	+ print "\n";
1868	1952
	1953	+ $lineprefix = $oldprefix;
1869	1954	output_section_rst(@_);
1870	1955	}
1871	1956
1872	1957	sub output_struct_rst(%) {
1873	1958	my %args = %{$_[0]};
1874	1959	my ($parameter);
	1960	+ my $oldprefix = $lineprefix;
1875	1961	my $name = $args{'type'} . " " . $args{'struct'};
1876	1962
1877	1963	print "\n\n.. c:type:: " . $name . "\n\n";
1878		− print " " . $args{'purpose'} . "\n\n";
	1964	+ print_lineno($declaration_start_line);
	1965	+ $lineprefix = " ";
	1966	+ output_highlight_rst($args{'purpose'});
	1967	+ print "\n";
1879	1968
1880		− print ":Definition:\n\n";
1881		− print " ::\n\n";
	1969	+ print "Definition\n\n";
	1970	+ print "::\n\n";
1882	1971	print " " . $args{'type'} . " " . $args{'struct'} . " {\n";
1883	1972	foreach $parameter (@{$args{'parameterlist'}}) {
1884	1973	if ($parameter =~ /^#/) {
1885		− print " " . "$parameter\n";
	1974	+ print " " . "$parameter\n";
1886	1975	next;
1887	1976	}
1888	1977
@@ -1903,7 +1992,8 @@ sub output_struct_rst(%) { · 14 unmodified lines
1903	1992	}
1904	1993	print " };\n\n";
1905	1994
1906		− print ":Members:\n\n";
	1995	+ print "Members\n\n";
	1996	+ $lineprefix = " ";
1907	1997	foreach $parameter (@{$args{'parameterlist'}}) {
1908	1998	($parameter =~ /^#/) && next;
1909	1999
@@ -1912,14 +2002,14 @@ sub output_struct_rst(%) { · 2 unmodified lines
1912	2002
1913	2003	($args{'parameterdescs'}{$parameter_name} ne $undescribed) \|\| next;
1914	2004	$type = $args{'parametertypes'}{$parameter};
1915		− print " `$type $parameter`" . "\n";
1916		− my $oldprefix = $lineprefix;
1917		− $lineprefix = " ";
	2005	+ print_lineno($parameterdesc_start_lines{$parameter_name});
	2006	+ print "``$type $parameter``\n";
1918	2007	output_highlight_rst($args{'parameterdescs'}{$parameter_name});
1919		− $lineprefix = $oldprefix;
1920	2008	print "\n";
1921	2009	}
1922	2010	print "\n";
	2011	+
	2012	+ $lineprefix = $oldprefix;
1923	2013	output_section_rst(@_);
1924	2014	}
1925	2015
@@ -1969,9 +2059,13 @@ sub output_declaration { · 43 unmodified lines
1969	2059	my $name = shift;
1970	2060	my $functype = shift;
1971	2061	my $func = "output_${functype}_$output_mode";
1972		− if (($function_only==0) \|\|
1973		− ( $function_only == 1 && defined($function_table{$name})) \|\|
1974		− ( $function_only == 2 && !($functype eq "function" && defined($function_table{$name}))))
	2062	+ if (($output_selection == OUTPUT_ALL) \|\|
	2063	+ (($output_selection == OUTPUT_INCLUDE \|\|
	2064	+ $output_selection == OUTPUT_EXPORTED) &&
	2065	+ defined($function_table{$name})) \|\|
	2066	+ (($output_selection == OUTPUT_EXCLUDE \|\|
	2067	+ $output_selection == OUTPUT_INTERNAL) &&
	2068	+ !($functype eq "function" && defined($function_table{$name}))))
1975	2069	{
1976	2070	&$func(@_);
1977	2071	$section_counter++;
@@ -2471,7 +2565,6 @@ sub dump_function($$) { · 493 unmodified lines
2471	2565
2472	2566	sub reset_state {
2473	2567	$function = "";
2474		− %constants = ();
2475	2568	%parameterdescs = ();
2476	2569	%parametertypes = ();
2477	2570	@parameterlist = ();
@@ -2481,8 +2574,8 @@ sub reset_state { · 3 unmodified lines
2481	2574	$struct_actual = "";
2482	2575	$prototype = "";
2483	2576
2484		− $state = 0;
2485		− $split_doc_state = 0;
	2577	+ $state = STATE_NORMAL;
	2578	+ $inline_doc_state = STATE_INLINE_NA;
2486	2579	}
2487	2580
2488	2581	sub tracepoint_munge($) {
@@ -2545,7 +2638,7 @@ sub syscall_munge() { · 56 unmodified lines
2545	2638	}
2546	2639	}
2547	2640
2548		−sub process_state3_function($$) {
	2641	+sub process_proto_function($$) {
2549	2642	my $x = shift;
2550	2643	my $file = shift;
2551	2644
@@ -2575,7 +2668,7 @@ sub process_state3_function($$) { · 23 unmodified lines
2575	2668	}
2576	2669	}
2577	2670
2578		−sub process_state3_type($$) {
	2671	+sub process_proto_type($$) {
2579	2672	my $x = shift;
2580	2673	my $file = shift;
2581	2674
@@ -2649,25 +2742,54 @@ sub local_unescape($) { · 67 unmodified lines
2649	2742	return $text;
2650	2743	}
2651	2744
2652		−sub process_file($) {
	2745	+sub map_filename($) {
2653	2746	my $file;
2654		− my $identifier;
2655		− my $func;
2656		− my $descr;
2657		− my $in_purpose = 0;
2658		− my $initial_section_counter = $section_counter;
2659	2747	my ($orig_file) = @_;
2660	2748
2661	2749	if (defined($ENV{'SRCTREE'})) {
2662	2750	$file = "$ENV{'SRCTREE'}" . "/" . $orig_file;
2663		− }
2664		− else {
	2751	+ } else {
2665	2752	$file = $orig_file;
2666	2753	}
	2754	+
2667	2755	if (defined($source_map{$file})) {
2668	2756	$file = $source_map{$file};
2669	2757	}
2670	2758
	2759	+ return $file;
	2760	+}
	2761	+
	2762	+sub process_export_file($) {
	2763	+ my ($orig_file) = @_;
	2764	+ my $file = map_filename($orig_file);
	2765	+
	2766	+ if (!open(IN,"<$file")) {
	2767	+ print STDERR "Error: Cannot open file $file\n";
	2768	+ ++$errors;
	2769	+ return;
	2770	+ }
	2771	+
	2772	+ while (<IN>) {
	2773	+ if (/$export_symbol/) {
	2774	+ $function_table{$2} = 1;
	2775	+ }
	2776	+ }
	2777	+
	2778	+ close(IN);
	2779	+}
	2780	+
	2781	+sub process_file($) {
	2782	+ my $file;
	2783	+ my $identifier;
	2784	+ my $func;
	2785	+ my $descr;
	2786	+ my $in_purpose = 0;
	2787	+ my $initial_section_counter = $section_counter;
	2788	+ my ($orig_file) = @_;
	2789	+ my $leading_space;
	2790	+
	2791	+ $file = map_filename($orig_file);
	2792	+
2671	2793	if (!open(IN,"<$file")) {
2672	2794	print STDERR "Error: Cannot open file $file\n";
2673	2795	++$errors;
@@ -2681,15 +2803,18 @@ sub process_file($) { · 7 unmodified lines
2681	2803	while (s/\\\s*$//) {
2682	2804	$_ .= <IN>;
2683	2805	}
2684		− if ($state == 0) {
	2806	+ if ($state == STATE_NORMAL) {
2685	2807	if (/$doc_start/o) {
2686		− $state = 1; # next line is always the function name
	2808	+ $state = STATE_NAME; # next line is always the function name
2687	2809	$in_doc_sect = 0;
	2810	+ $declaration_start_line = $. + 1;
2688	2811	}
2689		− } elsif ($state == 1) { # this line is the function name (always)
	2812	+ } elsif ($state == STATE_NAME) {# this line is the function name (always)
2690	2813	if (/$doc_block/o) {
2691		− $state = 4;
	2814	+ $state = STATE_DOCBLOCK;
2692	2815	$contents = "";
	2816	+ $new_start_line = $. + 1;
	2817	+
2693	2818	if ( $1 eq "" ) {
2694	2819	$section = $section_intro;
2695	2820	} else {
@@ -2702,7 +2827,12 @@ sub process_file($) { · 6 unmodified lines
2702	2827	$identifier = $1;
2703	2828	}
2704	2829
2705		− $state = 2;
	2830	+ $state = STATE_FIELD;
	2831	+ # if there's no @param blocks need to set up default section
	2832	+ # here
	2833	+ $contents = "";
	2834	+ $section = $section_default;
	2835	+ $new_start_line = $. + 1;
2706	2836	if (/-(.*)/) {
2707	2837	# strip leading/trailing/multiple spaces
2708	2838	$descr= $1;
@@ -2740,13 +2870,25 @@ sub process_file($) { · 31 unmodified lines
2740	2870	print STDERR "${file}:$.: warning: Cannot understand $_ on line $.",
2741	2871	" - I thought it was a doc line\n";
2742	2872	++$warnings;
2743		− $state = 0;
	2873	+ $state = STATE_NORMAL;
2744	2874	}
2745		− } elsif ($state == 2) { # look for head: lines, and include content
2746		− if (/$doc_sect/o) {
	2875	+ } elsif ($state == STATE_FIELD) { # look for head: lines, and include content
	2876	+ if (/$doc_sect/i) { # case insensitive for supported section names
2747	2877	$newsection = $1;
2748	2878	$newcontents = $2;
2749	2879
	2880	+ # map the supported section names to the canonical names
	2881	+ if ($newsection =~ m/^description$/i) {
	2882	+ $newsection = $section_default;
	2883	+ } elsif ($newsection =~ m/^context$/i) {
	2884	+ $newsection = $section_context;
	2885	+ } elsif ($newsection =~ m/^returns?$/i) {
	2886	+ $newsection = $section_return;
	2887	+ } elsif ($newsection =~ m/^\@return$/) {
	2888	+ # special: @return is a section, not a param description
	2889	+ $newsection = $section_return;
	2890	+ }
	2891	+
2750	2892	if (($contents ne "") && ($contents ne "\n")) {
2751	2893	if (!$in_doc_sect && $verbose) {
2752	2894	print STDERR "${file}:$.: warning: contents before sections\n";
@@ -2759,14 +2901,16 @@ sub process_file($) { · 6 unmodified lines
2759	2901	$in_doc_sect = 1;
2760	2902	$in_purpose = 0;
2761	2903	$contents = $newcontents;
	2904	+ $new_start_line = $.;
	2905	+ while ((substr($contents, 0, 1) eq " ") \|\|
	2906	+ substr($contents, 0, 1) eq "\t") {
	2907	+ $contents = substr($contents, 1);
	2908	+ }
2762	2909	if ($contents ne "") {
2763		− while ((substr($contents, 0, 1) eq " ") \|\|
2764		− substr($contents, 0, 1) eq "\t") {
2765		− $contents = substr($contents, 1);
2766		− }
2767	2910	$contents .= "\n";
2768	2911	}
2769	2912	$section = $newsection;
	2913	+ $leading_space = undef;
2770	2914	} elsif (/$doc_end/) {
2771	2915	if (($contents ne "") && ($contents ne "\n")) {
2772	2916	dump_section($file, $section, xml_escape($contents));
@@ -2780,7 +2924,7 @@ sub process_file($) { · 7 unmodified lines
2780	2924	}
2781	2925
2782	2926	$prototype = "";
2783		− $state = 3;
	2927	+ $state = STATE_PROTO;
2784	2928	$brcount = 0;
2785	2929	# print STDERR "end of doc comment, looking for prototype\n";
2786	2930	} elsif (/$doc_content/) {
@@ -2791,6 +2935,7 @@ sub process_file($) { · 4 unmodified lines
2791	2935	dump_section($file, $section, xml_escape($contents));
2792	2936	$section = $section_default;
2793	2937	$contents = "";
	2938	+ $new_start_line = $.;
2794	2939	} else {
2795	2940	$contents .= "\n";
2796	2941	}
@@ -2801,87 +2946,86 @@ sub process_file($) { · 4 unmodified lines
2801	2946	$declaration_purpose .= " " . xml_escape($1);
2802	2947	$declaration_purpose =~ s/\s+/ /g;
2803	2948	} else {
2804		− $contents .= $1 . "\n";
	2949	+ my $cont = $1;
	2950	+ if ($section =~ m/^@/ \|\| $section eq $section_context) {
	2951	+ if (!defined $leading_space) {
	2952	+ if ($cont =~ m/^(\s+)/) {
	2953	+ $leading_space = $1;
	2954	+ } else {
	2955	+ $leading_space = "";
	2956	+ }
	2957	+ }
	2958	+
	2959	+ $cont =~ s/^$leading_space//;
	2960	+ }
	2961	+ $contents .= $cont . "\n";
2805	2962	}
2806	2963	} else {
2807	2964	# i dont know - bad line? ignore.
2808	2965	print STDERR "${file}:$.: warning: bad line: $_";
2809	2966	++$warnings;
2810	2967	}
2811		− } elsif ($state == 5) { # scanning for split parameters
	2968	+ } elsif ($state == STATE_INLINE) { # scanning for inline parameters
2812	2969	# First line (state 1) needs to be a @parameter
2813		− if ($split_doc_state == 1 && /$doc_split_sect/o) {
	2970	+ if ($inline_doc_state == STATE_INLINE_NAME && /$doc_inline_sect/o) {
2814	2971	$section = $1;
2815	2972	$contents = $2;
	2973	+ $new_start_line = $.;
2816	2974	if ($contents ne "") {
2817	2975	while ((substr($contents, 0, 1) eq " ") \|\|
2818	2976	substr($contents, 0, 1) eq "\t") {
2819	2977	$contents = substr($contents, 1);
2820	2978	}
2821		− $contents .= "\n";
	2979	+ $contents .= "\n";
2822	2980	}
2823		− $split_doc_state = 2;
	2981	+ $inline_doc_state = STATE_INLINE_TEXT;
2824	2982	# Documentation block end */
2825		− } elsif (/$doc_split_end/) {
	2983	+ } elsif (/$doc_inline_end/) {
2826	2984	if (($contents ne "") && ($contents ne "\n")) {
2827	2985	dump_section($file, $section, xml_escape($contents));
2828	2986	$section = $section_default;
2829	2987	$contents = "";
2830	2988	}
2831		− $state = 3;
2832		− $split_doc_state = 0;
	2989	+ $state = STATE_PROTO;
	2990	+ $inline_doc_state = STATE_INLINE_NA;
2833	2991	# Regular text
2834	2992	} elsif (/$doc_content/) {
2835		− if ($split_doc_state == 2) {
	2993	+ if ($inline_doc_state == STATE_INLINE_TEXT) {
2836	2994	$contents .= $1 . "\n";
2837		− } elsif ($split_doc_state == 1) {
2838		− $split_doc_state = 4;
2839		− print STDERR "Warning(${file}:$.): ";
	2995	+ # nuke leading blank lines
	2996	+ if ($contents =~ /^\s*$/) {
	2997	+ $contents = "";
	2998	+ }
	2999	+ } elsif ($inline_doc_state == STATE_INLINE_NAME) {
	3000	+ $inline_doc_state = STATE_INLINE_ERROR;
	3001	+ print STDERR "${file}:$.: warning: ";
2840	3002	print STDERR "Incorrect use of kernel-doc format: $_";
2841	3003	++$warnings;
2842	3004	}
2843	3005	}
2844		− } elsif ($state == 3) { # scanning for function '{' (end of prototype)
2845		− if (/$doc_split_start/) {
2846		− $state = 5;
2847		− $split_doc_state = 1;
	3006	+ } elsif ($state == STATE_PROTO) { # scanning for function '{' (end of prototype)
	3007	+ if (/$doc_inline_start/) {
	3008	+ $state = STATE_INLINE;
	3009	+ $inline_doc_state = STATE_INLINE_NAME;
2848	3010	} elsif ($decl_type eq 'function') {
2849		− process_state3_function($_, $file);
	3011	+ process_proto_function($_, $file);
2850	3012	} else {
2851		− process_state3_type($_, $file);
	3013	+ process_proto_type($_, $file);
2852	3014	}
2853		− } elsif ($state == 4) {
2854		− # Documentation block
2855		− if (/$doc_block/) {
2856		− dump_doc_section($file, $section, xml_escape($contents));
2857		− $contents = "";
2858		− $function = "";
2859		− %constants = ();
2860		− %parameterdescs = ();
2861		− %parametertypes = ();
2862		− @parameterlist = ();
2863		− %sections = ();
2864		− @sectionlist = ();
2865		− $prototype = "";
2866		− if ( $1 eq "" ) {
2867		− $section = $section_intro;
2868		− } else {
2869		− $section = $1;
2870		− }
2871		− }
2872		− elsif (/$doc_end/)
	3015	+ } elsif ($state == STATE_DOCBLOCK) {
	3016	+ if (/$doc_end/)
2873	3017	{
2874	3018	dump_doc_section($file, $section, xml_escape($contents));
	3019	+ $section = $section_default;
2875	3020	$contents = "";
2876	3021	$function = "";
2877		− %constants = ();
2878	3022	%parameterdescs = ();
2879	3023	%parametertypes = ();
2880	3024	@parameterlist = ();
2881	3025	%sections = ();
2882	3026	@sectionlist = ();
2883	3027	$prototype = "";
2884		− $state = 0;
	3028	+ $state = STATE_NORMAL;
2885	3029	}
2886	3030	elsif (/$doc_content/)
2887	3031	{
@@ -2898,7 +3042,7 @@ sub process_file($) { · 10 unmodified lines
2898	3042	}
2899	3043	if ($initial_section_counter == $section_counter) {
2900	3044	print STDERR "${file}:1: warning: no structured comments found\n";
2901		− if (($function_only == 1) && ($show_not_found == 1)) {
	3045	+ if (($output_selection == OUTPUT_INCLUDE) && ($show_not_found == 1)) {
2902	3046	print STDERR " Was looking for '$_'.\n" for keys %function_table;
2903	3047	}
2904	3048	if ($output_mode eq "xml") {
@@ -2957,6 +3101,17 @@ if (open(SOURCE_MAP, "<.tmp_filelist.txt")) { · 52 unmodified lines
2957	3101	close(SOURCE_MAP);
2958	3102	}
2959	3103
	3104	+if ($output_selection == OUTPUT_EXPORTED \|\|
	3105	+ $output_selection == OUTPUT_INTERNAL) {
	3106	+
	3107	+ push(@export_file_list, @ARGV);
	3108	+
	3109	+ foreach (@export_file_list) {
	3110	+ chomp;
	3111	+ process_export_file($_);
	3112	+ }
	3113	+}
	3114	+
2960	3115	foreach (@ARGV) {
2961	3116	chomp;
2962	3117	process_file($_);