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

Pull documentation updates from Jon Corbet:
"A relatively boring cycle in the docs tree. There's a few kernel-doc
fixes and various document tweaks.

One patch reaches out of the documentation subtree to fix a comment in
init/do_mounts_rd.c. There didn't seem to be anybody more appropriate
to take that one, so I accepted it"

* tag 'docs-4.5' of git://git.lwn.net/linux: (29 commits)
thermal: add description for integral_cutoff unit
Documentation: update libhugetlbfs site url
Documentation: Explain pci=conf1,conf2 more verbosely
DMA-API: fix confusing sentence in Documentation/DMA-API.txt
Documentation: translations: update linux cross reference link
Documentation: fix typo in CodingStyle
init, Documentation: Remove ramdisk_blocksize mentions
Documentation-getdelays: Apply a recommendation from "checkpatch.pl" in main()
Documentation: HOWTO: update versions from 3.x to 4.x
Documentation: remove outdated references from translations
Doc: treewide: Fix grammar "a" to "an"
Documentation: cpu-hotplug: Fix sysfs mount instructions
can-doc: Add hint about getting timestamps
Fix CFQ I/O scheduler parameter name in documentation
Documentation: arm: remove dead links from Marvell Berlin docs
Documentation: HOWTO: update code cross reference link
Doc: Docbook/iio: Fix typo in iio.tmpl
DocBook: make index.html generation less verbose by default
DocBook: Cleanup: remove an unused $(call) line
DocBook: Add a help message for DOCBOOKS env var
...

Documentation/CodingStyle

···
 		return result;
 	}
 
-A common type of bug to be aware of it "one err bugs" which look like this:
+A common type of bug to be aware of is "one err bugs" which look like this:
 
 	err:
 		kfree(foo->bar);

Documentation/DMA-API.txt

···
 
 DMA_TO_DEVICE synchronisation must be done after the last modification
 of the memory region by the software and before it is handed off to
-the driver.  Once this primitive is used, memory covered by this
+the device.  Once this primitive is used, memory covered by this
 primitive should be treated as read-only by the device.  If the device
 may write to it at any point, it should be DMA_BIDIRECTIONAL (see
 below).

Documentation/DocBook/Makefile

···
 
 HTML := $(sort $(patsubst %.xml, %.html, $(BOOKS)))
 htmldocs: $(HTML)
-	$(call build_main_index)
-	$(call build_images)
+	$(call cmd,build_main_index)
 	$(call install_media_images)
 
 MAN := $(patsubst %.xml, %.9, $(BOOKS))
···
 
 index = index.html
 main_idx = $(obj)/$(index)
-build_main_index = rm -rf $(main_idx); \
+quiet_cmd_build_main_index = HTML    $(main_idx)
+      cmd_build_main_index = rm -rf $(main_idx); \
 		   echo '<h1>Linux Kernel HTML Documentation</h1>' >> $(main_idx) && \
 		   echo '<h2>Kernel Version: $(KERNELVERSION)</h2>' >> $(main_idx) && \
 		   cat $(HTML) >> $(main_idx)
···
 	@echo  '  mandocs         - man pages'
 	@echo  '  installmandocs  - install man pages generated by mandocs'
 	@echo  '  cleandocs       - clean all generated DocBook files'
+	@echo
+	@echo  'make DOCBOOKS="s1.xml s2.xml" [target] Generate only docs s1.xml s2.xml'
+	@echo  '  valid values for DOCBOOKS are: $(DOCBOOKS)'
+
 
 ###
 # Temporary files left by various tools

Documentation/DocBook/iio.tmpl

···
             .scan_type = {
               .sign = 's',
               .realbits = 12,
-              .storgebits = 16,
+              .storagebits = 16,
               .shift = 4,
               .endianness = IIO_LE,
             },

Documentation/HOWTO

···
 Cross-Reference project, which is able to present source code in a
 self-referential, indexed webpage format. An excellent up-to-date
 repository of the kernel code may be found at:
-	http://lxr.linux.no/+trees
+	http://lxr.free-electrons.com/
 
 
 The development process

Documentation/accounting/getdelays.c

···
 		}
 	}
 
-	if ((nl_sd = create_nl_socket(NETLINK_GENERIC)) < 0)
+	nl_sd = create_nl_socket(NETLINK_GENERIC);
+	if (nl_sd < 0)
 		err(1, "error creating Netlink socket\n");
 
 

Documentation/arm/Marvell/README

···
    Linux kernel mach directory: arch/arm/mach-mmp
    Linux kernel plat directory: arch/arm/plat-pxa
 
-Berlin family (Digital Entertainment)
+Berlin family (Multimedia Solutions)
 -------------------------------------
 
   Flavors:
-	88DE3005, Armada 1500-mini
+	88DE3005, Armada 1500 Mini
 		Design name:	BG2CD
 		Core:		ARM Cortex-A9, PL310 L2CC
-		Homepage:	http://www.marvell.com/digital-entertainment/armada-1500-mini/
+		Homepage:	http://www.marvell.com/multimedia-solutions/armada-1500-mini/
+        88DE3006, Armada 1500 Mini Plus
+                Design name:    BG2CDP
+                Core:           Dual Core ARM Cortex-A7
+                Homepage:       http://www.marvell.com/multimedia-solutions/armada-1500-mini-plus/
 	88DE3100, Armada 1500
 		Design name:	BG2
 		Core:		Marvell PJ4B (ARMv7), Tauros3 L2CC
-		Homepage:	http://www.marvell.com/digital-entertainment/armada-1500/
-		Product Brief:	http://www.marvell.com/digital-entertainment/armada-1500/assets/Marvell-ARMADA-1500-Product-Brief.pdf
+		Product Brief:	http://www.marvell.com/multimedia-solutions/armada-1500/assets/Marvell-ARMADA-1500-Product-Brief.pdf
 	88DE3114, Armada 1500 Pro
-		Design name:	BG2-Q
+		Design name:	BG2Q
 		Core:		Quad Core ARM Cortex-A9, PL310 L2CC
-		Homepage:	http://www.marvell.com/digital-entertainment/armada-1500-pro/
-		Product Brief:	http://www.marvell.com/digital-entertainment/armada-1500-pro/assets/Marvell_ARMADA_1500_PRO-01_product_brief.pdf
 	88DE????
 		Design name:	BG3
 		Core:		ARM Cortex-A15, CA15 integrated L2CC
 
-  Homepage: http://www.marvell.com/digital-entertainment/
+  Homepage: http://www.marvell.com/multimedia-solutions/
   Directory: arch/arm/mach-berlin
 
   Comments:

Documentation/block/cfq-iosched.txt

···
 
 Default value for this parameter is 8ms.
 
-latency
--------
-This parameter is used to enable/disable the latency mode of the CFQ
-scheduler. If latency mode (called low_latency) is enabled, CFQ tries
-to recompute the slice time for each process based on the target_latency set
-for the system. This favors fairness over throughput. Disabling low
-latency (setting it to 0) ignores target latency, allowing each process in the
-system to get a full time slice.
+low_latency
+-----------
+This parameter is used to enable/disable the low latency mode of the CFQ
+scheduler. If enabled, CFQ tries to recompute the slice time for each process
+based on the target_latency set for the system. This favors fairness over
+throughput. Disabling low latency (setting it to 0) ignores target latency,
+allowing each process in the system to get a full time slice.
 
 By default low latency mode is enabled.
 

Documentation/cpu-hotplug.txt

···
 
 If this is not mounted, do the following.
 
-	 #mkdir /sysfs
+	#mkdir /sys
 	#mount -t sysfs sys /sys
 
 Now you should see entries for all present cpu, the following is an example

Documentation/filesystems/proc.txt

···
 type exist.
 
 If min_free_kbytes has been tuned correctly (recommendations made by hugeadm
-from libhugetlbfs http://sourceforge.net/projects/libhugetlbfs/), one can
+from libhugetlbfs https://github.com/libhugetlbfs/libhugetlbfs/), one can
 make an estimate of the likely number of huge pages that can be allocated
 at a given point in time. All the "Movable" blocks should be allocatable
 unless memory has been mlock()'d. Some of the Reclaimable blocks should

Documentation/filesystems/sharedsubtree.txt

···
 		if one rbind mounts a tree within the same subtree 'n' times
 		the number of mounts created is an exponential function of 'n'.
 		Having unbindable mount can help prune the unneeded bind
-		mounts. Here is a example.
+		mounts. Here is an example.
 
 		step 1:
 		   let's say the root tree has just two directories with

Documentation/gpio/consumer.txt

···
 
 To summarize:
 
-Function (example)               active-low proporty  physical line
+Function (example)               active-low property  physical line
 gpiod_set_raw_value(desc, 0);        don't care           low
 gpiod_set_raw_value(desc, 1);        don't care           high
 gpiod_set_value(desc, 0);       default (active-high)     low

Documentation/gpio/driver.txt

···
   it will be threaded IRQ handler on -RT and hard IRQ handler on non-RT
   (for example, see [3]).
   Know W/A: The generic_handle_irq() is expected to be called with IRQ disabled,
-  so IRQ core will complain if it will be called from IRQ handler wich is forced
-  thread. The "fake?" raw lock can be used to W/A this problem:
+  so IRQ core will complain if it will be called from IRQ handler which is
+  forced thread. The "fake?" raw lock can be used to W/A this problem:
 
 	raw_spinlock_t wa_lock;
 	static irqreturn_t omap_gpio_irq_handler(int irq, void *gpiobank)
···
 ---------------------------------------
 
 Any provider of irqchips needs to be carefully tailored to support Real Time
-preemption. It is desireable that all irqchips in the GPIO subsystem keep this
+preemption. It is desirable that all irqchips in the GPIO subsystem keep this
 in mind and does the proper testing to assure they are real time-enabled.
 So, pay attention on above " RT_FULL:" notes, please.
 The following is a checklist to follow when preparing a driver for real

Documentation/gpio/drivers-on-gpio.txt

···
   drivers for the I2C devices on the bus like any other I2C bus driver.
 
 - spi_gpio: drivers/spi/spi-gpio.c is used to drive an SPI bus (variable number
-  of wires, atleast SCK and optionally MISO, MOSI and chip select lines) using
+  of wires, at least SCK and optionally MISO, MOSI and chip select lines) using
   GPIO hammering (bitbang). It will appear as any other SPI bus on the system
   and makes it possible to connect drivers for SPI devices on the bus like
   any other SPI bus driver. For example any MMC/SD card can then be connected
···
 
 - gpio-wdt: drivers/watchdog/gpio_wdt.c is used to provide a watchdog timer
   that will periodically "ping" a hardware connected to a GPIO line by toggling
-  it from 1-to-0-to-1. If that hardware does not recieve its "ping"
+  it from 1-to-0-to-1. If that hardware does not receive its "ping"
   periodically, it will reset the system.
 
 - gpio-nand: drivers/mtd/nand/gpio.c is used to connect a NAND flash chip to
···
 
 Use those instead of talking directly to the GPIOs using sysfs; they integrate
 with kernel frameworks better than your userspace code could. Needless to say,
-just using the apropriate kernel drivers will simplify and speed up your
+just using the appropriate kernel drivers will simplify and speed up your
 embedded hacking in particular by providing ready-made components.

Documentation/ioctl/botching-up-ioctls.txt

···
 ----------------------------
 
 GPUs do most everything asynchronously, so we have a need to time operations and
-wait for oustanding ones. This is really tricky business; at the moment none of
+wait for outstanding ones. This is really tricky business; at the moment none of
 the ioctls supported by the drm/i915 get this fully right, which means there's
 still tons more lessons to learn here.
 
···
    ioctl restartable relative timeouts tend to be too coarse and can
    indefinitely extend your wait time due to rounding on each restart.
    Especially if your reference clock is something really slow like the display
-   frame counter. With a spec laywer hat on this isn't a bug since timeouts can
+   frame counter. With a spec lawyer hat on this isn't a bug since timeouts can
    always be extended - but users will surely hate you if their neat animations
    starts to stutter due to this.
 
···
 
  * Ensure that you have sufficient insulation between different clients. By
    default pick a private per-fd namespace which forces any sharing to be done
-   explictly. Only go with a more global per-device namespace if the objects
+   explicitly. Only go with a more global per-device namespace if the objects
    are truly device-unique. One counterexample in the drm modeset interfaces is
    that the per-device modeset objects like connectors share a namespace with
    framebuffer objects, which mostly are not shared at all. A separate

Documentation/ja_JP/HOWTO

···
 自己参照方式で、索引がついた web 形式で、ソースコードを参照することが
 できます。この最新の素晴しいカーネルコードのリポジトリは以下で見つかり
 ます-
-	http://lxr.linux.no/+trees
+	http://lxr.free-electrons.com/
 
 開発プロセス
 -----------------------
···
 に全サブシステムツリーからほぼ毎日プルされてできる特別なテスト用のリ
 ポジトリが存在します-
        http://git.kernel.org/?p=linux/kernel/git/next/linux-next.git
-       http://linux.f-seidel.de/linux-next/pmwiki/
 
 このやり方によって、-next カーネルは次のマージ機会でどんなものがメイン
 ラインカーネルにマージされるか、おおまかなの展望を提供します。-next 

Documentation/kernel-docs.txt

···
        between two versions of a file".
 
      * Name: "Cross-Referencing Linux"
-       URL: http://lxr.linux.no/source/
+       URL: http://lxr.free-electrons.com/
        Keywords: Browsing source code.
        Description: Another web-based Linux kernel source code browser.
        Lots of cross references to variables and functions. You can see

Documentation/kernel-parameters.txt

···
 				hardware access methods are allowed. Use this
 				if you experience crashes upon bootup and you
 				suspect they are caused by the BIOS.
-		conf1		[X86] Force use of PCI Configuration
-				Mechanism 1.
-		conf2		[X86] Force use of PCI Configuration
-				Mechanism 2.
+		conf1		[X86] Force use of PCI Configuration Access
+				Mechanism 1 (config address in IO port 0xCF8,
+				data in IO port 0xCFC, both 32-bit).
+		conf2		[X86] Force use of PCI Configuration Access
+				Mechanism 2 (IO port 0xCF8 is an 8-bit port for
+				the function, IO port 0xCFA, also 8-bit, sets
+				bus number. The config space is then accessed
+				through ports 0xC000-0xCFFF).
+				See http://wiki.osdev.org/PCI for more info
+				on the configuration access mechanisms.
 		noaer		[PCIE] If the PCIEAER kernel config parameter is
 				enabled, this kernel boot option can be used to
 				disable the use of PCIE advanced error reporting.
···
 
 	raid=		[HW,RAID]
 			See Documentation/md.txt.
-
-	ramdisk_blocksize=	[RAM]
-			See Documentation/blockdev/ramdisk.txt.
 
 	ramdisk_size=	[RAM] Sizes of RAM disks in kilobytes
 			See Documentation/blockdev/ramdisk.txt.

Documentation/ko_KR/HOWTO

···
 것은 Linux Cross-Reference project이며 그것은 자기 참조 방식이며
 소스코드를 인덱스된 웹 페이지들의 형태로 보여준다. 최신의 멋진 커널
 코드 저장소는 다음을 통하여 참조할 수 있다.
-      http://lxr.linux.no/+trees
+      http://lxr.free-electrons.com/
 
 
 개발 프로세스
···
 리눅스 커널 개발 프로세스는 현재 몇몇 다른 메인 커널 "브랜치들"과
 서브시스템에 특화된 커널 브랜치들로 구성된다. 몇몇 다른 메인
 브랜치들은 다음과 같다.
-  - main 3.x 커널 트리
-  - 3.x.y - 안정된 커널 트리
-  - 3.x -git 커널 패치들
+  - main 4.x 커널 트리
+  - 4.x.y - 안정된 커널 트리
+  - 4.x -git 커널 패치들
   - 서브시스템을 위한 커널 트리들과 패치들
-  - 3.x - 통합 테스트를 위한 next 커널 트리
+  - 4.x - 통합 테스트를 위한 next 커널 트리
 
-3.x 커널 트리
+4.x 커널 트리
 ---------------
 
-3.x 커널들은 Linux Torvalds가 관리하며 kernel.org의 pub/linux/kernel/v3.x/
+4.x 커널들은 Linux Torvalds가 관리하며 kernel.org의 pub/linux/kernel/v4.x/
 디렉토리에서 참조될 수 있다.개발 프로세스는 다음과 같다.
   - 새로운 커널이 배포되자마자 2주의 시간이 주어진다. 이 기간동은
     메인테이너들은 큰 diff들을 Linus에게 제출할 수 있다. 대개 이 패치들은
···
          버그의 상황에 따라 배포되는 것이지 미리정해 놓은 시간에 따라
          배포되는 것은 아니기 때문이다."
 
-3.x.y - 안정 커널 트리
+4.x.y - 안정 커널 트리
 ------------------------
 
-3 자리 숫자로 이루어진 버젼의 커널들은 -stable 커널들이다. 그것들은 3.x
+3 자리 숫자로 이루어진 버젼의 커널들은 -stable 커널들이다. 그것들은 4.x
 커널에서 발견된 큰 회귀들이나 보안 문제들 중 비교적 작고 중요한 수정들을
 포함한다.
 
 이것은 가장 최근의 안정적인 커널을 원하는 사용자에게 추천되는 브랜치이며,
 개발/실험적 버젼을 테스트하는 것을 돕고자 하는 사용자들과는 별로 관련이 없다.
 
-어떤 3.x.y 커널도 사용할 수 없다면 그때는 가장 높은 숫자의 3.x
+어떤 4.x.y 커널도 사용할 수 없다면 그때는 가장 높은 숫자의 4.x
 커널이 현재의 안정 커널이다.
 
-3.x.y는 "stable" 팀<[e-mail]>에 의해 관리되며 거의 매번 격주로
+4.x.y는 "stable" 팀<[e-mail]>에 의해 관리되며 거의 매번 격주로
 배포된다.
 
 커널 트리 문서들 내에 Documentation/stable_kernel_rules.txt 파일은 어떤
···
 진행되는지를 설명한다.
 
 
-3.x -git 패치들
+4.x -git 패치들
 ------------------
 git 저장소(그러므로 -git이라는 이름이 붙음)에는 날마다 관리되는 Linus의
 커널 트리의 snapshot 들이 있다. 이 패치들은 일반적으로 날마다 배포되며
···
 대부분의 이러한 patchwork 사이트는 http://patchwork.kernel.org/ 또는
 http://patchwork.ozlabs.org/ 에 나열되어 있다.
 
-3.x - 통합 테스트를 위한 next 커널 트리
+4.x - 통합 테스트를 위한 next 커널 트리
 -----------------------------------------
-서브시스템 트리들의 변경사항들은 mainline 3.x 트리로 들어오기 전에 통합
+서브시스템 트리들의 변경사항들은 mainline 4.x 트리로 들어오기 전에 통합
 테스트를 거쳐야 한다. 이런 목적으로, 모든 서브시스템 트리의 변경사항을 거의
 매일 받아가는 특수한 테스트 저장소가 존재한다:
        http://git.kernel.org/?p=linux/kernel/git/sfr/linux-next.git
-       http://linux.f-seidel.de/linux-next/pmwiki/
 
 이런 식으로, -next 커널을 통해 다음 머지 기간에 메인라인 커널에 어떤 변경이
 가해질 것인지 간략히 알 수 있다. 모험심 강한 테스터라면 -next 커널에서 테스트를

Documentation/networking/can.txt

···
     nbytes = sendto(s, &frame, sizeof(struct can_frame),
                     0, (struct sockaddr*)&addr, sizeof(addr));
 
+  An accurate timestamp can be obtained with an ioctl(2) call after reading
+  a message from the socket:
+
+    struct timeval tv;
+    ioctl(s, SIOCGSTAMP, &tv);
+
+  The timestamp has a resolution of one microsecond and is set automatically
+  at the reception of a CAN frame.
+
   Remark about CAN FD (flexible data rate) support:
 
   Generally the handling of CAN FD is very similar to the formerly described

Documentation/stable_kernel_rules.txt

···
 Also, some patches may have kernel version prerequisites.  This can be
 specified in the following format in the sign-off area:
 
-     Cc:  <[e-mail]> # 3.3.x-
+     Cc: <[e-mail]> # 3.3.x-
 
    The tag has the meaning of:
      git cherry-pick <this commit>

Documentation/thermal/sysfs-api.txt

···
 	accumulates error when temperature is above the desired
 	temperature trip point. For more information see
 	Documentation/thermal/power_allocator.txt
+	Unit: millidegree Celsius
 	RW, Optional
 
 slope

Documentation/vm/slub.txt

···
 an impact on overall system performance which may make a bug more
 difficult to find.
 
-In order to switch debugging on one can add a option "slub_debug"
+In order to switch debugging on one can add an option "slub_debug"
 to the kernel command line. That will enable full debugging for
 all slabs.
 

init/do_mounts_rd.c

···
 	/*
 	 * NOTE NOTE: nblocks is not actually blocks but
 	 * the number of kibibytes of data to load into a ramdisk.
-	 * So any ramdisk block size that is a multiple of 1KiB should
-	 * work when the appropriate ramdisk_blocksize is specified
-	 * on the command line.
-	 *
-	 * The default ramdisk_blocksize is 1KiB and it is generally
-	 * silly to use anything else, so make sure to use 1KiB
-	 * blocksize while generating ext2fs ramdisk-images.
 	 */
 	if (sys_ioctl(out_fd, BLKGETSIZE, (unsigned long)&rd_blocks) < 0)
 		rd_blocks = 0;

scripts/kernel-doc

···
 	$members =~ s/__attribute__\s*\(\([a-z,_\*\s\(\)]*\)\)//i;
 	$members =~ s/__aligned\s*\([^;]*\)//gos;
 	$members =~ s/\s*CRYPTO_MINALIGN_ATTR//gos;
+	# replace DECLARE_BITMAP
+	$members =~ s/DECLARE_BITMAP\s*\(([^,)]+), ([^,)]+)\)/unsigned long $1\[BITS_TO_LONGS($2)\]/gos;
 
 	create_parameterlist($members, ';', $file);
 	check_sections($file, $declaration_name, "struct", $sectcheck, $struct_actual, $nested);
···
     my $file = shift;
 
     $x =~ s@/\*.*?\*/@@gos;	# strip comments.
-    $x =~ s/^#\s*define\s+.*$//; # strip #define macros inside enums
+    # strip #define macros inside enums
+    $x =~ s@#\s*((define|ifdef)\s+|endif)[^;]*;@@gos;
 
     if ($x =~ /enum\s+(\w+)\s*{(.*)}/) {
 	$declaration_name = $1;