History

Merge tag 'v5.3-rc3' into drm-next-5.4

Linux 5.3-rc3

Alex Deucher committed 7 years ago

Commit 3f61fd42 parents 6ca523d e21a71216417 files · +552707 −428013Browse files

Unified · Split

1594 files
  1. .gitignore +4 −0
  2. .mailmap +5 −0
  3. CREDITS +2 −3
  4. Documentation/ABI/obsolete/sysfs-driver-hid-roccat-pyra +1 −1
  5. Documentation/ABI/obsolete/sysfs-gpio +1 −1
  6. Documentation/ABI/removed/sysfs-class-rfkill +1 −1
  7. Documentation/ABI/stable/sysfs-class-infiniband +0 −17
  8. Documentation/ABI/stable/sysfs-class-rfkill +1 −1
  9. Documentation/ABI/stable/sysfs-devices-node +1 −1
  10. Documentation/ABI/stable/sysfs-driver-mlxreg-io +39 −26
  11. Documentation/ABI/testing/debugfs-cec-error-inj +1 −1
  12. Documentation/ABI/testing/debugfs-cros-ec +56 −0
  13. Documentation/ABI/testing/debugfs-driver-habanalabs +15 −3
  14. Documentation/ABI/testing/debugfs-wilco-ec +7 −9
  15. Documentation/ABI/testing/ima_policy +4 −2
  16. Documentation/ABI/testing/procfs-diskstats +1 −1
  17. Documentation/ABI/testing/procfs-smaps_rollup +12 −2
  18. Documentation/ABI/testing/pstore +2 −2
  19. Documentation/ABI/testing/sysfs-block +1 −1
  20. Documentation/ABI/testing/sysfs-block-device +1 −1
  21. Documentation/ABI/testing/sysfs-bus-css +23 −0
  22. Documentation/ABI/testing/sysfs-bus-event_source-devices-format +2 −2
  23. Documentation/ABI/testing/sysfs-bus-i2c-devices-hm6352 +6 −6
  24. Documentation/ABI/testing/sysfs-bus-iio +5 −2
  25. Documentation/ABI/testing/sysfs-bus-iio-cros-ec +5 −5
  26. Documentation/ABI/testing/sysfs-bus-iio-distance-srf08 +2 −2
  27. Documentation/ABI/testing/sysfs-bus-iio-frequency-adf4371 +44 −0
  28. Documentation/ABI/testing/sysfs-bus-iio-proximity-as3935 +2 −2
  29. Documentation/ABI/testing/sysfs-bus-pci-devices-aer_stats +12 −12
  30. Documentation/ABI/testing/sysfs-bus-pci-devices-cciss +22 −22
  31. Documentation/ABI/testing/sysfs-bus-siox +11 −11
  32. Documentation/ABI/testing/sysfs-bus-usb-devices-usbsevseg +11 −11
  33. Documentation/ABI/testing/sysfs-class-backlight-driver-lm3533 +3 −3
  34. Documentation/ABI/testing/sysfs-class-cxl +3 −3
  35. Documentation/ABI/testing/sysfs-class-devfreq +1 −1
  36. Documentation/ABI/testing/sysfs-class-led-driver-lm3533 +4 −4
  37. Documentation/ABI/testing/sysfs-class-leds-gt683r +2 −2
  38. Documentation/ABI/testing/sysfs-class-net-phydev +8 −0
  39. Documentation/ABI/testing/sysfs-class-net-qmi +2 −2
  40. Documentation/ABI/testing/sysfs-class-power +32 −0
  41. Documentation/ABI/testing/sysfs-class-power-wilco +30 −0
  42. Documentation/ABI/testing/sysfs-class-powercap +2 −2
  43. Documentation/ABI/testing/sysfs-class-switchtec +1 −1
  44. Documentation/ABI/testing/sysfs-class-uwb_rc +0 −6
  45. Documentation/ABI/testing/sysfs-devices-system-cpu +27 −3
  46. Documentation/ABI/testing/sysfs-driver-altera-cvp +1 −1
  47. Documentation/ABI/testing/sysfs-driver-habanalabs +24 −18
  48. Documentation/ABI/testing/sysfs-driver-hid +6 −6
  49. Documentation/ABI/testing/sysfs-driver-hid-roccat-kone +1 −1
  50. Documentation/ABI/testing/sysfs-driver-ppi +1 −1
  51. Documentation/ABI/testing/sysfs-driver-st +1 −1
  52. Documentation/ABI/testing/sysfs-driver-wacom +1 −1
  53. Documentation/ABI/testing/sysfs-fs-f2fs +8 −0
  54. Documentation/ABI/testing/sysfs-kernel-fscaps +1 −1
  55. Documentation/ABI/testing/sysfs-kernel-iommu_groups +9 −0
  56. Documentation/ABI/testing/sysfs-kernel-uids +1 −1
  57. Documentation/ABI/testing/sysfs-kernel-vmcoreinfo +1 −1
  58. Documentation/ABI/testing/sysfs-platform-asus-laptop +1 −1
  59. Documentation/ABI/testing/sysfs-platform-asus-wmi +10 −0
  60. Documentation/ABI/testing/sysfs-platform-i2c-demux-pinctrl +2 −2
  61. Documentation/ABI/testing/sysfs-platform-wilco-ec +40 −0
  62. Documentation/ABI/testing/sysfs-power +1 −1
  63. Documentation/COPYING-logo +0 −0
  64. Documentation/DMA-API-HOWTO.txt +1 −1
  65. Documentation/DMA-API.txt +1 −1
  66. Documentation/EDID/HOWTO.txt +0 −49
  67. Documentation/Kconfig +13 −0
  68. Documentation/Makefile +13 −1
  69. Documentation/PCI/MSI-HOWTO.txt +0 −270
  70. Documentation/PCI/PCIEBUS-HOWTO.txt +0 −198
  71. Documentation/PCI/acpi-info.rst +192 −0
  72. Documentation/PCI/acpi-info.txt +0 −187
  73. Documentation/PCI/endpoint/index.rst +13 −0
  74. Documentation/PCI/endpoint/pci-endpoint-cfs.rst +118 −0
  75. Documentation/PCI/endpoint/pci-endpoint-cfs.txt +0 −105
  76. Documentation/PCI/endpoint/pci-endpoint.rst +231 −0
  77. Documentation/PCI/endpoint/pci-endpoint.txt +0 −215
  78. Documentation/PCI/endpoint/pci-test-function.rst +103 −0
  79. Documentation/PCI/endpoint/pci-test-function.txt +0 −87
  80. Documentation/PCI/endpoint/pci-test-howto.rst +235 −0
  81. Documentation/PCI/endpoint/pci-test-howto.txt +0 −206
  82. Documentation/PCI/index.rst +18 −0
  83. Documentation/PCI/msi-howto.rst +287 −0
  84. Documentation/PCI/pci-error-recovery.rst +427 −0
  85. Documentation/PCI/pci-error-recovery.txt +0 −413
  86. Documentation/PCI/pci-iov-howto.rst +172 −0
  87. Documentation/PCI/pci-iov-howto.txt +0 −147
  88. Documentation/PCI/pci.rst +578 −0
  89. Documentation/PCI/pci.txt +0 −636
  90. Documentation/PCI/pcieaer-howto.rst +311 −0
  91. Documentation/PCI/pcieaer-howto.txt +0 −267
  92. Documentation/PCI/picebus-howto.rst +220 −0
  93. Documentation/RCU/UP.rst +143 −0
  94. Documentation/RCU/UP.txt +0 −133
  95. Documentation/RCU/index.rst +19 −0
  96. Documentation/RCU/listRCU.rst +321 −0
  97. Documentation/RCU/listRCU.txt +0 −315
  98. Documentation/RCU/rcu.rst +92 −0
  99. Documentation/RCU/rcu.txt +0 −89
  100. Documentation/RCU/rculist_nulls.txt +1 −1
  101. Documentation/RCU/rcuref.txt +20 −1
  102. Documentation/RCU/stallwarn.txt +1 −1
  103. Documentation/RCU/whatisRCU.txt +4 −4
  104. Documentation/accounting/cgroupstats.rst +31 −0
  105. Documentation/accounting/cgroupstats.txt +0 −27
  106. Documentation/accounting/delay-accounting.rst +126 −0
  107. Documentation/accounting/delay-accounting.txt +0 −117
  108. Documentation/accounting/index.rst +14 −0
  109. Documentation/accounting/psi.rst +182 −0
  110. Documentation/accounting/psi.txt +0 −180
  111. Documentation/accounting/taskstats-struct.rst +199 −0
  112. Documentation/accounting/taskstats-struct.txt +0 −180
  113. Documentation/accounting/taskstats.rst +180 −0
  114. Documentation/accounting/taskstats.txt +0 −181
  115. Documentation/acpi/dsd/leds.txt +1 −1
  116. Documentation/admin-guide/LSM/LoadPin.rst +10 −0
  117. Documentation/admin-guide/README.rst +1 −1
  118. Documentation/admin-guide/aoe/aoe.rst +150 −0
  119. Documentation/admin-guide/aoe/autoload.sh +0 −0
  120. Documentation/admin-guide/aoe/examples.rst +23 −0
  121. Documentation/admin-guide/aoe/index.rst +17 −0
  122. Documentation/admin-guide/aoe/status.sh +0 −0
  123. Documentation/admin-guide/aoe/todo.rst +17 −0
  124. Documentation/admin-guide/aoe/udev-install.sh +0 −0
  125. Documentation/admin-guide/aoe/udev.txt +1 −1
  126. Documentation/admin-guide/binderfs.rst +0 −0
  127. Documentation/admin-guide/blockdev/drbd/DRBD-8.3-data-packets.svg +0 −0
  128. Documentation/admin-guide/blockdev/drbd/DRBD-data-packets.svg +0 −0
  129. Documentation/admin-guide/blockdev/drbd/conn-states-8.dot +0 −0
  130. Documentation/admin-guide/blockdev/drbd/data-structure-v9.rst +42 −0
  131. Documentation/admin-guide/blockdev/drbd/disk-states-8.dot +0 −0
  132. Documentation/admin-guide/blockdev/drbd/drbd-connection-state-overview.dot +0 −0
  133. Documentation/admin-guide/blockdev/drbd/figures.rst +30 −0
  134. Documentation/admin-guide/blockdev/drbd/index.rst +19 −0
  135. Documentation/admin-guide/blockdev/drbd/node-states-8.dot +0 −1
  136. Documentation/admin-guide/blockdev/floppy.rst +255 −0
  137. Documentation/admin-guide/blockdev/index.rst +16 −0
  138. Documentation/admin-guide/blockdev/nbd.rst +31 −0
  139. Documentation/admin-guide/blockdev/paride.rst +439 −0
  140. Documentation/admin-guide/blockdev/ramdisk.rst +177 −0
  141. Documentation/admin-guide/blockdev/zram.rst +422 −0
  142. Documentation/admin-guide/btmrvl.rst +0 −0
  143. Documentation/admin-guide/bug-hunting.rst +2 −2
  144. Documentation/admin-guide/cgroup-v1/blkio-controller.rst +302 −0
  145. Documentation/admin-guide/cgroup-v1/cgroups.rst +695 −0
  146. Documentation/admin-guide/cgroup-v1/cpuacct.rst +50 −0
  147. Documentation/admin-guide/cgroup-v1/cpusets.rst +866 −0
  148. Documentation/admin-guide/cgroup-v1/devices.rst +132 −0
  149. Documentation/admin-guide/cgroup-v1/freezer-subsystem.rst +127 −0
  150. Documentation/admin-guide/cgroup-v1/hugetlb.rst +50 −0
  151. Documentation/admin-guide/cgroup-v1/index.rst +28 −0
  152. Documentation/admin-guide/cgroup-v1/memcg_test.rst +355 −0
  153. Documentation/admin-guide/cgroup-v1/memory.rst +1003 −0
  154. Documentation/admin-guide/cgroup-v1/net_cls.rst +44 −0
  155. Documentation/admin-guide/cgroup-v1/net_prio.rst +57 −0
  156. Documentation/admin-guide/cgroup-v1/pids.rst +92 −0
  157. Documentation/admin-guide/cgroup-v1/rdma.rst +117 −0
  158. Documentation/admin-guide/cgroup-v2.rst +21 −5
  159. Documentation/admin-guide/clearing-warn-once.rst +0 −0
  160. Documentation/admin-guide/conf.py +0 −10
  161. Documentation/admin-guide/cpu-load.rst +0 −0
  162. Documentation/admin-guide/cputopology.rst +177 −0
  163. Documentation/admin-guide/device-mapper/cache-policies.rst +131 −0
  164. Documentation/admin-guide/device-mapper/cache.rst +337 −0
  165. Documentation/admin-guide/device-mapper/delay.rst +31 −0
  166. Documentation/admin-guide/device-mapper/dm-crypt.rst +173 −0
  167. Documentation/admin-guide/device-mapper/dm-dust.txt +0 −0
  168. Documentation/admin-guide/device-mapper/dm-flakey.rst +74 −0
  169. Documentation/admin-guide/device-mapper/dm-init.rst +125 −0
  170. Documentation/admin-guide/device-mapper/dm-integrity.rst +259 −0
  171. Documentation/admin-guide/device-mapper/dm-io.rst +75 −0
  172. Documentation/admin-guide/device-mapper/dm-log.rst +57 −0
  173. Documentation/admin-guide/device-mapper/dm-queue-length.rst +48 −0
  174. Documentation/admin-guide/device-mapper/dm-raid.rst +419 −0
  175. Documentation/admin-guide/device-mapper/dm-service-time.rst +101 −0
  176. Documentation/admin-guide/device-mapper/dm-uevent.rst +110 −0
  177. Documentation/admin-guide/device-mapper/dm-zoned.rst +146 −0
  178. Documentation/admin-guide/device-mapper/era.rst +116 −0
  179. Documentation/admin-guide/device-mapper/index.rst +42 −0
  180. Documentation/admin-guide/device-mapper/kcopyd.rst +47 −0
  181. Documentation/admin-guide/device-mapper/linear.rst +63 −0
  182. Documentation/admin-guide/device-mapper/log-writes.rst +145 −0
  183. Documentation/admin-guide/device-mapper/persistent-data.rst +88 −0
  184. Documentation/admin-guide/device-mapper/snapshot.rst +196 −0
  185. Documentation/admin-guide/device-mapper/statistics.rst +225 −0
  186. Documentation/admin-guide/device-mapper/striped.rst +61 −0
  187. Documentation/admin-guide/device-mapper/switch.rst +141 −0
  188. Documentation/admin-guide/device-mapper/thin-provisioning.rst +427 −0
  189. Documentation/admin-guide/device-mapper/unstriped.rst +135 −0
  190. Documentation/admin-guide/device-mapper/verity.rst +229 −0
  191. Documentation/admin-guide/device-mapper/writecache.rst +79 −0
  192. Documentation/admin-guide/device-mapper/zero.rst +37 −0
  193. Documentation/admin-guide/devices.txt +2 −2
  194. Documentation/admin-guide/efi-stub.rst +0 −0
  195. Documentation/admin-guide/gpio/index.rst +17 −0
  196. Documentation/admin-guide/gpio/sysfs.rst +0 −0
  197. Documentation/admin-guide/highuid.rst +0 −0
  198. Documentation/admin-guide/hw-vuln/index.rst +1 −0
  199. Documentation/admin-guide/hw-vuln/l1tf.rst +1 −1
  200. Documentation/admin-guide/hw-vuln/spectre.rst +697 −0
  201. Documentation/admin-guide/hw_random.rst +0 −0
  202. Documentation/admin-guide/index.rst +30 −0
  203. Documentation/admin-guide/iostats.rst +197 −0
  204. Documentation/admin-guide/kdump/gdbmacros.txt +0 −0
  205. Documentation/admin-guide/kdump/index.rst +20 −0
  206. Documentation/admin-guide/kdump/kdump.rst +534 −0
  207. Documentation/admin-guide/kdump/vmcoreinfo.rst +488 −0
  208. Documentation/admin-guide/kernel-parameters.rst +6 −6
  209. Documentation/admin-guide/kernel-parameters.txt +106 −77
  210. Documentation/admin-guide/kernel-per-CPU-kthreads.rst +356 −0
  211. Documentation/admin-guide/laptops/asus-laptop.rst +271 −0
  212. Documentation/admin-guide/laptops/disk-shock-protection.rst +151 −0
  213. Documentation/admin-guide/laptops/index.rst +17 −0
  214. Documentation/admin-guide/laptops/laptop-mode.rst +781 −0
  215. Documentation/admin-guide/laptops/lg-laptop.rst +1 −0
  216. Documentation/admin-guide/laptops/sony-laptop.rst +174 −0
  217. Documentation/admin-guide/laptops/sonypi.rst +158 −0
  218. Documentation/admin-guide/laptops/thinkpad-acpi.rst +1562 −0
  219. Documentation/admin-guide/laptops/toshiba_haps.rst +87 −0
  220. Documentation/admin-guide/lcd-panel-cgram.rst +27 −0
  221. Documentation/admin-guide/ldm.rst +0 −0
  222. Documentation/admin-guide/lockup-watchdogs.rst +0 −0
  223. Documentation/admin-guide/mm/cma_debugfs.rst +25 −0
  224. Documentation/admin-guide/mm/index.rst +2 −1
  225. Documentation/admin-guide/mm/ksm.rst +1 −1
  226. Documentation/admin-guide/mm/numa_memory_policy.rst +1 −1
  227. Documentation/admin-guide/mm/numaperf.rst +3 −2
  228. Documentation/admin-guide/mm/transhuge.rst +1 −1
  229. Documentation/admin-guide/namespaces/compatibility-list.rst +43 −0
  230. Documentation/admin-guide/namespaces/index.rst +11 −0
  231. Documentation/admin-guide/namespaces/resource-control.rst +18 −0
  232. Documentation/admin-guide/numastat.rst +0 −0
  233. Documentation/admin-guide/perf/arm-ccn.rst +61 −0
  234. Documentation/admin-guide/perf/arm_dsu_pmu.rst +29 −0
  235. Documentation/admin-guide/perf/hisi-pmu.rst +60 −0
  236. Documentation/admin-guide/perf/index.rst +16 −0
  237. Documentation/admin-guide/perf/qcom_l2_pmu.rst +39 −0
  238. Documentation/admin-guide/perf/qcom_l3_pmu.rst +26 −0
  239. Documentation/admin-guide/perf/thunderx2-pmu.rst +42 −0
  240. Documentation/admin-guide/perf/xgene-pmu.rst +49 −0
  241. Documentation/admin-guide/pnp.rst +0 −0
  242. Documentation/admin-guide/rapidio.rst +0 −0
  243. Documentation/admin-guide/ras.rst +1 −1
  244. Documentation/admin-guide/rtc.rst +0 −0
  245. Documentation/admin-guide/svga.rst +0 −0
  246. Documentation/admin-guide/sysctl/abi.rst +67 −0
  247. Documentation/admin-guide/sysctl/fs.rst +384 −0
  248. Documentation/admin-guide/sysctl/index.rst +98 −0
  249. Documentation/admin-guide/sysctl/kernel.rst +1177 −0
  250. Documentation/admin-guide/sysctl/net.rst +461 −0
  251. Documentation/admin-guide/sysctl/sunrpc.rst +25 −0
  252. Documentation/admin-guide/sysctl/user.rst +78 −0
  253. Documentation/admin-guide/sysctl/vm.rst +964 −0
  254. Documentation/admin-guide/video-output.rst +0 −0
  255. Documentation/admin-guide/xfs.rst +466 −0
  256. Documentation/aoe/aoe.txt +0 −143
  257. Documentation/aoe/todo.txt +0 −14
  258. Documentation/arm/Booting +0 −218
  259. Documentation/arm/IXP4xx +0 −172
  260. Documentation/arm/Interrupts +0 −167
  261. Documentation/arm/Marvell/README +0 −395
  262. Documentation/arm/Microchip/README +0 −169
  263. Documentation/arm/Netwinder +0 −78
  264. Documentation/arm/OMAP/DSS +0 −362
  265. Documentation/arm/OMAP/README +0 −11
  266. Documentation/arm/OMAP/omap_pm +0 −154
  267. Documentation/arm/Porting +0 −135
  268. Documentation/arm/README +0 −204
  269. Documentation/arm/SA1100/ADSBitsy +0 −43
  270. Documentation/arm/SA1100/Assabet +0 −300
  271. Documentation/arm/SA1100/Brutus +0 −66
  272. Documentation/arm/SA1100/CERF +0 −29
  273. Documentation/arm/SA1100/FreeBird +0 −21
  274. Documentation/arm/SA1100/GraphicsClient +0 −98
  275. Documentation/arm/SA1100/GraphicsMaster +0 −53
  276. Documentation/arm/SA1100/HUW_WEBPANEL +0 −17
  277. Documentation/arm/SA1100/Itsy +0 −39
  278. Documentation/arm/SA1100/LART +0 −14
  279. Documentation/arm/SA1100/PLEB +0 −11
  280. Documentation/arm/SA1100/Pangolin +0 −23
  281. Documentation/arm/SA1100/Tifon +0 −7
  282. Documentation/arm/SA1100/Yopy +0 −2
  283. Documentation/arm/SA1100/empeg +0 −2
  284. Documentation/arm/SA1100/nanoEngine +0 −11
  285. Documentation/arm/SA1100/serial_UART +0 −47
  286. Documentation/arm/SPEAr/overview.txt +0 −63
  287. Documentation/arm/Samsung-S3C24XX/CPUfreq.txt +0 −75
  288. Documentation/arm/Samsung-S3C24XX/EB2410ITX.txt +0 −58
  289. Documentation/arm/Samsung-S3C24XX/GPIO.txt +0 −171
  290. Documentation/arm/Samsung-S3C24XX/H1940.txt +0 −40
  291. Documentation/arm/Samsung-S3C24XX/NAND.txt +0 −30
  292. Documentation/arm/Samsung-S3C24XX/Overview.txt +0 −318
  293. Documentation/arm/Samsung-S3C24XX/S3C2412.txt +0 −120
  294. Documentation/arm/Samsung-S3C24XX/S3C2413.txt +0 −21
  295. Documentation/arm/Samsung-S3C24XX/SMDK2440.txt +0 −56
  296. Documentation/arm/Samsung-S3C24XX/Suspend.txt +0 −137
  297. Documentation/arm/Samsung-S3C24XX/USB-Host.txt +0 −93
  298. Documentation/arm/Samsung/Bootloader-interface.txt +0 −68
  299. Documentation/arm/Samsung/GPIO.txt +0 −40
  300. Documentation/arm/Samsung/Overview.txt +0 −86
  301. Documentation/arm/Setup +0 −129
  302. Documentation/arm/VFP/release-notes.txt +0 −55
  303. Documentation/arm/arm.rst +214 −0
  304. Documentation/arm/booting.rst +237 −0
  305. Documentation/arm/cluster-pm-race-avoidance.rst +533 −0
  306. Documentation/arm/cluster-pm-race-avoidance.txt +0 −498
  307. Documentation/arm/firmware.rst +72 −0
  308. Documentation/arm/firmware.txt +0 −70
  309. Documentation/arm/index.rst +80 −0
  310. Documentation/arm/interrupts.rst +169 −0
  311. Documentation/arm/ixp4xx.rst +173 −0
  312. Documentation/arm/kernel_mode_neon.rst +124 −0
  313. Documentation/arm/kernel_mode_neon.txt +0 −121
  314. Documentation/arm/kernel_user_helpers.rst +268 −0
  315. Documentation/arm/kernel_user_helpers.txt +0 −267
  316. Documentation/arm/keystone/Overview.txt +0 −55
  317. Documentation/arm/keystone/knav-qmss.rst +60 −0
  318. Documentation/arm/keystone/knav-qmss.txt +0 −56
  319. Documentation/arm/keystone/overview.rst +74 −0
  320. Documentation/arm/marvel.rst +488 −0
  321. Documentation/arm/mem_alignment +0 −58
  322. Documentation/arm/mem_alignment.rst +63 −0
  323. Documentation/arm/memory.rst +93 −0
  324. Documentation/arm/memory.txt +0 −88
  325. Documentation/arm/microchip.rst +204 −0
  326. Documentation/arm/netwinder.rst +85 −0
  327. Documentation/arm/nwfpe/NOTES +0 −29
  328. Documentation/arm/nwfpe/README +0 −70
  329. Documentation/arm/nwfpe/README.FPE +0 −156
  330. Documentation/arm/nwfpe/TODO +0 −67
  331. Documentation/arm/nwfpe/index.rst +13 −0
  332. Documentation/arm/nwfpe/netwinder-fpe.rst +162 −0
  333. Documentation/arm/nwfpe/notes.rst +32 −0
  334. Documentation/arm/nwfpe/nwfpe.rst +74 −0
  335. Documentation/arm/nwfpe/todo.rst +72 −0
  336. Documentation/arm/omap/dss.rst +372 −0
  337. Documentation/arm/omap/index.rst +12 −0
  338. Documentation/arm/omap/omap.rst +18 −0
  339. Documentation/arm/omap/omap_pm.rst +165 −0
  340. Documentation/arm/porting.rst +137 −0
  341. Documentation/arm/pxa/mfp.rst +288 −0
  342. Documentation/arm/pxa/mfp.txt +0 −286
  343. Documentation/arm/sa1100/adsbitsy.rst +51 −0
  344. Documentation/arm/sa1100/assabet.rst +301 −0
  345. Documentation/arm/sa1100/brutus.rst +69 −0
  346. Documentation/arm/sa1100/cerf.rst +35 −0
  347. Documentation/arm/sa1100/freebird.rst +25 −0
  348. Documentation/arm/sa1100/graphicsclient.rst +102 −0
  349. Documentation/arm/sa1100/graphicsmaster.rst +60 −0
  350. Documentation/arm/sa1100/huw_webpanel.rst +21 −0
  351. Documentation/arm/sa1100/index.rst +25 −0
  352. Documentation/arm/sa1100/itsy.rst +47 −0
  353. Documentation/arm/sa1100/lart.rst +15 −0
  354. Documentation/arm/sa1100/nanoengine.rst +11 −0
  355. Documentation/arm/sa1100/pangolin.rst +29 −0
  356. Documentation/arm/sa1100/pleb.rst +13 −0
  357. Documentation/arm/sa1100/serial_uart.rst +51 −0
  358. Documentation/arm/sa1100/tifon.rst +7 −0
  359. Documentation/arm/sa1100/yopy.rst +5 −0
  360. Documentation/arm/samsung-s3c24xx/cpufreq.rst +76 −0
  361. Documentation/arm/samsung-s3c24xx/eb2410itx.rst +59 −0
  362. Documentation/arm/samsung-s3c24xx/gpio.rst +172 −0
  363. Documentation/arm/samsung-s3c24xx/h1940.rst +41 −0
  364. Documentation/arm/samsung-s3c24xx/index.rst +20 −0
  365. Documentation/arm/samsung-s3c24xx/nand.rst +30 −0
  366. Documentation/arm/samsung-s3c24xx/overview.rst +319 −0
  367. Documentation/arm/samsung-s3c24xx/s3c2412.rst +121 −0
  368. Documentation/arm/samsung-s3c24xx/s3c2413.rst +22 −0
  369. Documentation/arm/samsung-s3c24xx/smdk2440.rst +57 −0
  370. Documentation/arm/samsung-s3c24xx/suspend.rst +137 −0
  371. Documentation/arm/samsung-s3c24xx/usb-host.rst +91 −0
  372. Documentation/arm/samsung/bootloader-interface.rst +81 −0
  373. Documentation/arm/samsung/clksrc-change-registers.awk +0 −0
  374. Documentation/arm/samsung/gpio.rst +41 −0
  375. Documentation/arm/samsung/index.rst +12 −0
  376. Documentation/arm/samsung/overview.rst +89 −0
  377. Documentation/arm/setup.rst +108 −0
  378. Documentation/arm/sh-mobile/.gitignore +0 −0
  379. Documentation/arm/spear/overview.rst +66 −0
  380. Documentation/arm/sti/overview.rst +36 −0
  381. Documentation/arm/sti/overview.txt +0 −33
  382. Documentation/arm/sti/stih407-overview.rst +19 −0
  383. Documentation/arm/sti/stih407-overview.txt +0 −18
  384. Documentation/arm/sti/stih415-overview.rst +14 −0
  385. Documentation/arm/sti/stih415-overview.txt +0 −12
  386. Documentation/arm/sti/stih416-overview.rst +13 −0
  387. Documentation/arm/sti/stih416-overview.txt +0 −12
  388. Documentation/arm/sti/stih418-overview.rst +21 −0
  389. Documentation/arm/sti/stih418-overview.txt +0 −20
  390. Documentation/arm/stm32/stm32f429-overview.rst +2 −3
  391. Documentation/arm/stm32/stm32f746-overview.rst +2 −3
  392. Documentation/arm/stm32/stm32f769-overview.rst +2 −3
  393. Documentation/arm/stm32/stm32h743-overview.rst +2 −3
  394. Documentation/arm/stm32/stm32mp157-overview.rst +1 −0
  395. Documentation/arm/sunxi.rst +150 −0
  396. Documentation/arm/sunxi/README +0 −102
  397. Documentation/arm/sunxi/clocks.rst +57 −0
  398. Documentation/arm/sunxi/clocks.txt +0 −56
  399. Documentation/arm/swp_emulation +0 −27
  400. Documentation/arm/swp_emulation.rst +27 −0
  401. Documentation/arm/tcm.rst +161 −0
  402. Documentation/arm/tcm.txt +0 −155
  403. Documentation/arm/uefi.rst +67 −0
  404. Documentation/arm/uefi.txt +0 −60
  405. Documentation/arm/vfp/release-notes.rst +57 −0
  406. Documentation/arm/vlocks.rst +212 −0
  407. Documentation/arm/vlocks.txt +0 −211
  408. Documentation/arm64/acpi_object_usage.rst +738 −0
  409. Documentation/arm64/acpi_object_usage.txt +0 −622
  410. Documentation/arm64/arm-acpi.rst +528 −0
  411. Documentation/arm64/arm-acpi.txt +0 −519
  412. Documentation/arm64/booting.rst +293 −0
  413. Documentation/arm64/booting.txt +0 −266
  414. Documentation/arm64/cpu-feature-registers.rst +304 −0
  415. Documentation/arm64/cpu-feature-registers.txt +0 −296
  416. Documentation/arm64/elf_hwcaps.rst +209 −0
  417. Documentation/arm64/elf_hwcaps.txt +0 −231
  418. Documentation/arm64/hugetlbpage.rst +41 −0
  419. Documentation/arm64/hugetlbpage.txt +0 −38
  420. Documentation/arm64/index.rst +26 −0
  421. Documentation/arm64/legacy_instructions.rst +68 −0
  422. Documentation/arm64/legacy_instructions.txt +0 −57
  423. Documentation/arm64/memory.rst +98 −0
  424. Documentation/arm64/memory.txt +0 −97
  425. Documentation/arm64/pointer-authentication.rst +109 −0
  426. Documentation/arm64/pointer-authentication.txt +0 −107
  427. Documentation/arm64/silicon-errata.rst +133 −0
  428. Documentation/arm64/silicon-errata.txt +0 −88
  429. Documentation/arm64/sve.rst +545 −0
  430. Documentation/arm64/sve.txt +0 −541
  431. Documentation/arm64/tagged-pointers.rst +68 −0
  432. Documentation/arm64/tagged-pointers.txt +0 −66
  433. Documentation/atomic_t.txt +20 −6
  434. Documentation/auxdisplay/lcd-panel-cgram.txt +0 −24
  435. Documentation/backlight/lp855x-driver.txt +0 −66
  436. Documentation/block/bfq-iosched.rst +597 −0
  437. Documentation/block/bfq-iosched.txt +0 −583
  438. Documentation/block/biodoc.rst +1164 −0
  439. Documentation/block/biodoc.txt +0 −1077
  440. Documentation/block/biovecs.rst +146 −0
  441. Documentation/block/biovecs.txt +0 −144
  442. Documentation/block/capability.rst +18 −0
  443. Documentation/block/capability.txt +0 −15
  444. Documentation/block/cmdline-partition.rst +53 −0
  445. Documentation/block/cmdline-partition.txt +0 −46
  446. Documentation/block/data-integrity.rst +291 −0
  447. Documentation/block/data-integrity.txt +0 −281
  448. Documentation/block/deadline-iosched.rst +72 −0
  449. Documentation/block/deadline-iosched.txt +0 −75
  450. Documentation/block/index.rst +25 −0
  451. Documentation/block/ioprio.rst +182 −0
  452. Documentation/block/ioprio.txt +0 −183
  453. Documentation/block/kyber-iosched.rst +15 −0
  454. Documentation/block/kyber-iosched.txt +0 −14
  455. Documentation/block/null_blk.rst +126 −0
  456. Documentation/block/null_blk.txt +0 −99
  457. Documentation/block/pr.rst +119 −0
  458. Documentation/block/pr.txt +0 −119
  459. Documentation/block/queue-sysfs.rst +254 −0
  460. Documentation/block/queue-sysfs.txt +0 −231
  461. Documentation/block/request.rst +99 −0
  462. Documentation/block/request.txt +0 −88
  463. Documentation/block/stat.rst +93 −0
  464. Documentation/block/stat.txt +0 −86
  465. Documentation/block/switching-sched.rst +39 −0
  466. Documentation/block/switching-sched.txt +0 −35
  467. Documentation/block/writeback_cache_control.rst +86 −0
  468. Documentation/block/writeback_cache_control.txt +0 −86
  469. Documentation/blockdev/drbd/README.txt +0 −16
  470. Documentation/blockdev/drbd/data-structure-v9.txt +0 −38
  471. Documentation/blockdev/floppy.txt +0 −245
  472. Documentation/blockdev/nbd.txt +0 −31
  473. Documentation/blockdev/paride.txt +0 −417
  474. Documentation/blockdev/ramdisk.txt +0 −174
  475. Documentation/blockdev/zram.txt +0 −355
  476. Documentation/bpf/bpf_design_QA.rst +25 −5
  477. Documentation/bpf/btf.rst +2 −0
  478. Documentation/bpf/index.rst +1 −0
  479. Documentation/bpf/prog_cgroup_sockopt.rst +93 −0
  480. Documentation/bus-devices/ti-gpmc.txt +0 −122
  481. Documentation/cdrom/Makefile +0 −21
  482. Documentation/cdrom/cdrom-standard.rst +1063 −0
  483. Documentation/cdrom/cdrom-standard.tex +0 −1026
  484. Documentation/cdrom/ide-cd +0 −534
  485. Documentation/cdrom/ide-cd.rst +538 −0
  486. Documentation/cdrom/index.rst +19 −0
  487. Documentation/cdrom/packet-writing.rst +139 −0
  488. Documentation/cdrom/packet-writing.txt +0 −132
  489. Documentation/cgroup-v1/blkio-controller.txt +0 −293
  490. Documentation/cgroup-v1/cgroups.txt +0 −677
  491. Documentation/cgroup-v1/cpuacct.txt +0 −49
  492. Documentation/cgroup-v1/cpusets.txt +0 −839
  493. Documentation/cgroup-v1/devices.txt +0 −116
  494. Documentation/cgroup-v1/freezer-subsystem.txt +0 −123
  495. Documentation/cgroup-v1/hugetlb.txt +0 −49
  496. Documentation/cgroup-v1/memcg_test.txt +0 −280
  497. Documentation/cgroup-v1/memory.txt +0 −892
  498. Documentation/cgroup-v1/net_cls.txt +0 −39
  499. Documentation/cgroup-v1/net_prio.txt +0 −55
  500. Documentation/cgroup-v1/pids.txt +0 −88
  501. Documentation/cgroup-v1/rdma.txt +0 −109
  502. Documentation/cma/debugfs.txt +0 −21
  503. Documentation/conf.py +32 −3
  504. Documentation/connector/connector.txt +0 −196
  505. Documentation/console/console.txt +0 −145
  506. Documentation/core-api/circular-buffers.rst +1 −1
  507. Documentation/core-api/conf.py +0 −10
  508. Documentation/core-api/gcc-plugins.rst +0 −0
  509. Documentation/core-api/index.rst +3 −0
  510. Documentation/core-api/kernel-api.rst +13 −3
  511. Documentation/core-api/printk-formats.rst +1 −1
  512. Documentation/core-api/protection-keys.rst +0 −0
  513. Documentation/core-api/timekeeping.rst +9 −5
  514. Documentation/core-api/xarray.rst +135 −135
  515. Documentation/cpu-freq/core.txt +1 −1
  516. Documentation/cputopology.txt +0 −159
  517. Documentation/crypto/api-samples.rst +77 −99
  518. Documentation/crypto/api-skcipher.rst +1 −1
  519. Documentation/crypto/architecture.rst +1 −3
  520. Documentation/crypto/conf.py +0 −10
  521. Documentation/crypto/crypto_engine.rst +73 −38
  522. Documentation/dev-tools/conf.py +0 −10
  523. Documentation/dev-tools/kmemleak.rst +44 −4
  524. Documentation/dev-tools/sparse.rst +0 −5
  525. Documentation/device-mapper/cache-policies.txt +0 −121
  526. Documentation/device-mapper/cache.txt +0 −311
  527. Documentation/device-mapper/delay.txt +0 −28
  528. Documentation/device-mapper/dm-crypt.txt +0 −162
  529. Documentation/device-mapper/dm-flakey.txt +0 −57
  530. Documentation/device-mapper/dm-init.txt +0 −114
  531. Documentation/device-mapper/dm-integrity.txt +0 −233
  532. Documentation/device-mapper/dm-io.txt +0 −75
  533. Documentation/device-mapper/dm-log.txt +0 −54
  534. Documentation/device-mapper/dm-queue-length.txt +0 −39
  535. Documentation/device-mapper/dm-raid.txt +0 −354
  536. Documentation/device-mapper/dm-service-time.txt +0 −91
  537. Documentation/device-mapper/dm-uevent.txt +0 −97
  538. Documentation/device-mapper/dm-zoned.txt +0 −144
  539. Documentation/device-mapper/era.txt +0 −108
  540. Documentation/device-mapper/kcopyd.txt +0 −47
  541. Documentation/device-mapper/linear.txt +0 −61
  542. Documentation/device-mapper/log-writes.txt +0 −140
  543. Documentation/device-mapper/persistent-data.txt +0 −84
  544. Documentation/device-mapper/snapshot.txt +0 −176
  545. Documentation/device-mapper/statistics.txt +0 −223
  546. Documentation/device-mapper/striped.txt +0 −57
  547. Documentation/device-mapper/switch.txt +0 −138
  548. Documentation/device-mapper/thin-provisioning.txt +0 −411
  549. Documentation/device-mapper/unstriped.txt +0 −124
  550. Documentation/device-mapper/verity.txt +0 −219
  551. Documentation/device-mapper/writecache.txt +0 −70
  552. Documentation/device-mapper/zero.txt +0 −37
  553. Documentation/devicetree/bindings/Makefile +1 −1
  554. Documentation/devicetree/bindings/arm/al,alpine.txt +0 −16
  555. Documentation/devicetree/bindings/arm/al,alpine.yaml +21 −0
  556. Documentation/devicetree/bindings/arm/amlogic.txt +0 −142
  557. Documentation/devicetree/bindings/arm/amlogic.yaml +144 −0
  558. Documentation/devicetree/bindings/arm/amlogic/amlogic,meson-gx-ao-secure.txt +28 −0
  559. Documentation/devicetree/bindings/arm/arm,scmi.txt +1 −1
  560. Documentation/devicetree/bindings/arm/arm-boards +1 −1
  561. Documentation/devicetree/bindings/arm/atmel-at91.txt +0 −73
  562. Documentation/devicetree/bindings/arm/atmel-at91.yaml +134 −0
  563. Documentation/devicetree/bindings/arm/axxia.txt +0 −12
  564. Documentation/devicetree/bindings/arm/axxia.yaml +19 −0
  565. Documentation/devicetree/bindings/arm/coresight-cpu-debug.txt +2 −2
  566. Documentation/devicetree/bindings/arm/coresight.txt +5 −3
  567. Documentation/devicetree/bindings/arm/cpus.yaml +224 −263
  568. Documentation/devicetree/bindings/arm/digicolor.txt +0 −6
  569. Documentation/devicetree/bindings/arm/digicolor.yaml +16 −0
  570. Documentation/devicetree/bindings/arm/emtrion.txt +0 −12
  571. Documentation/devicetree/bindings/arm/freescale/fsl,scu.txt +37 −0
  572. Documentation/devicetree/bindings/arm/fsl.yaml +44 −0
  573. Documentation/devicetree/bindings/arm/idle-states.txt +11 −4
  574. Documentation/devicetree/bindings/arm/mediatek.txt +0 −89
  575. Documentation/devicetree/bindings/arm/mediatek.yaml +91 −0
  576. Documentation/devicetree/bindings/arm/mediatek/mediatek,audsys.txt +1 −0
  577. Documentation/devicetree/bindings/arm/mediatek/mediatek,sgmiisys.txt +2 −0
  578. Documentation/devicetree/bindings/arm/moxart.txt +0 −12
  579. Documentation/devicetree/bindings/arm/moxart.yaml +19 −0
  580. Documentation/devicetree/bindings/arm/nxp/lpc32xx.txt +0 −8
  581. Documentation/devicetree/bindings/arm/nxp/lpc32xx.yaml +25 −0
  582. Documentation/devicetree/bindings/arm/omap/omap.txt +3 −0
  583. Documentation/devicetree/bindings/arm/psci.txt +0 −111
  584. Documentation/devicetree/bindings/arm/psci.yaml +163 −0
  585. Documentation/devicetree/bindings/arm/qcom.yaml +14 −0
  586. Documentation/devicetree/bindings/arm/rda.txt +0 −17
  587. Documentation/devicetree/bindings/arm/rda.yaml +20 −0
  588. Documentation/devicetree/bindings/arm/renesas.yaml +9 −1
  589. Documentation/devicetree/bindings/arm/rockchip.yaml +13 −0
  590. Documentation/devicetree/bindings/arm/socionext/milbeaut.yaml +1 −1
  591. Documentation/devicetree/bindings/arm/stm32/mlahb.txt +37 −0
  592. Documentation/devicetree/bindings/arm/stm32/stm32.txt +0 −10
  593. Documentation/devicetree/bindings/arm/stm32/stm32.yaml +31 −0
  594. Documentation/devicetree/bindings/arm/sunxi.yaml +1 −1
  595. Documentation/devicetree/bindings/arm/ti/k3.txt +3 −0
  596. Documentation/devicetree/bindings/arm/ti/ti,davinci.yaml +1 −1
  597. Documentation/devicetree/bindings/arm/xen.txt +1 −1
  598. Documentation/devicetree/bindings/bus/allwinner,sun8i-a23-rsb.yaml +80 −0
  599. Documentation/devicetree/bindings/bus/sunxi-rsb.txt +0 −47
  600. Documentation/devicetree/bindings/clock/allwinner,sun4i-a10-ccu.yaml +141 −0
  601. Documentation/devicetree/bindings/clock/amlogic,gxbb-clkc.txt +1 −0
  602. Documentation/devicetree/bindings/clock/at91-clock.txt +4 −3
  603. Documentation/devicetree/bindings/clock/brcm,bcm63xx-clocks.txt +22 −0
  604. Documentation/devicetree/bindings/clock/cirrus,lochnagar.txt +1 −0
  605. Documentation/devicetree/bindings/clock/mvebu-core-clock.txt +1 −0
  606. Documentation/devicetree/bindings/clock/qcom,gpucc.txt +3 −1
  607. Documentation/devicetree/bindings/clock/renesas,r9a06g032-sysctrl.txt +5 −2
  608. Documentation/devicetree/bindings/clock/silabs,si5341.txt +162 −0
  609. Documentation/devicetree/bindings/clock/sunxi-ccu.txt +0 −62
  610. Documentation/devicetree/bindings/common-properties.txt +8 −9
  611. Documentation/devicetree/bindings/cpufreq/imx-cpufreq-dt.txt +37 −0
  612. Documentation/devicetree/bindings/crypto/atmel-crypto.txt +0 −13
  613. Documentation/devicetree/bindings/csky/pmu.txt +38 −0
  614. Documentation/devicetree/bindings/display/bridge/renesas,dw-hdmi.txt +3 −1
  615. Documentation/devicetree/bindings/display/msm/dpu.txt +10 −0
  616. Documentation/devicetree/bindings/display/msm/dsi.txt +1 −0
  617. Documentation/devicetree/bindings/display/simple-framebuffer.yaml +24 −1
  618. Documentation/devicetree/bindings/dma/8250_mtk_dma.txt +0 −33
  619. Documentation/devicetree/bindings/dma/arm-pl330.txt +3 −0
  620. Documentation/devicetree/bindings/dma/fsl-edma.txt +39 −5
  621. Documentation/devicetree/bindings/dma/fsl-qdma.txt +1 −0
  622. Documentation/devicetree/bindings/dma/mtk-uart-apdma.txt +54 −0
  623. Documentation/devicetree/bindings/dma/sun6i-dma.txt +7 −2
  624. Documentation/devicetree/bindings/extcon/extcon-fsa9480.txt +19 −0
  625. Documentation/devicetree/bindings/firmware/intel,ixp4xx-network-processing-engine.yaml +1 −1
  626. Documentation/devicetree/bindings/gpio/gpio-davinci.txt +18 −0
  627. Documentation/devicetree/bindings/gpio/pl061-gpio.txt +0 −10
  628. Documentation/devicetree/bindings/gpio/pl061-gpio.yaml +69 −0
  629. Documentation/devicetree/bindings/gpu/arm,mali-midgard.txt +1 −0
  630. Documentation/devicetree/bindings/gpu/arm,mali-utgard.txt +1 −0
  631. Documentation/devicetree/bindings/hwlock/omap-hwspinlock.txt +20 −5
  632. Documentation/devicetree/bindings/i2c/allwinner,sun6i-a31-p2wi.yaml +65 −0
  633. Documentation/devicetree/bindings/i2c/i2c-mt7621.txt +25 −0
  634. Documentation/devicetree/bindings/i2c/i2c-mv64xxx.txt +0 −64
  635. Documentation/devicetree/bindings/i2c/i2c-ocores.txt +7 −2
  636. Documentation/devicetree/bindings/i2c/i2c-omap.txt +1 −0
  637. Documentation/devicetree/bindings/i2c/i2c-stm32.txt +2 −0
  638. Documentation/devicetree/bindings/i2c/i2c-sun6i-p2wi.txt +0 −41
  639. Documentation/devicetree/bindings/i2c/marvell,mv64xxx-i2c.yaml +124 −0
  640. Documentation/devicetree/bindings/i3c/cdns,i3c-master.txt +1 −1
  641. Documentation/devicetree/bindings/i3c/i3c.txt +3 −1
  642. Documentation/devicetree/bindings/iio/accel/adi,adxl345.yaml +72 −0
  643. Documentation/devicetree/bindings/iio/accel/adi,adxl372.yaml +63 −0
  644. Documentation/devicetree/bindings/iio/accel/adxl345.txt +0 −39
  645. Documentation/devicetree/bindings/iio/accel/adxl372.txt +0 −33
  646. Documentation/devicetree/bindings/iio/adc/adi,ad7124.txt +0 −75
  647. Documentation/devicetree/bindings/iio/adc/adi,ad7124.yaml +160 −0
  648. Documentation/devicetree/bindings/iio/adc/adi,ad7780.txt +0 −48
  649. Documentation/devicetree/bindings/iio/adc/adi,ad7780.yaml +87 −0
  650. Documentation/devicetree/bindings/iio/adc/avia-hx711.yaml +1 −1
  651. Documentation/devicetree/bindings/iio/adc/mt6577_auxadc.txt +2 −0
  652. Documentation/devicetree/bindings/iio/adc/st,stm32-adc.txt +1 −0
  653. Documentation/devicetree/bindings/iio/chemical/sensirion,sps30.txt +0 −12
  654. Documentation/devicetree/bindings/iio/chemical/sensirion,sps30.yaml +39 −0
  655. Documentation/devicetree/bindings/iio/frequency/adf4371.yaml +63 −0
  656. Documentation/devicetree/bindings/iio/light/isl29018.txt +0 −27
  657. Documentation/devicetree/bindings/iio/light/isl29018.yaml +56 −0
  658. Documentation/devicetree/bindings/iio/light/tsl2583.txt +0 −25
  659. Documentation/devicetree/bindings/iio/light/tsl2583.yaml +46 −0
  660. Documentation/devicetree/bindings/iio/light/tsl2772.txt +0 −42
  661. Documentation/devicetree/bindings/iio/light/tsl2772.yaml +83 −0
  662. Documentation/devicetree/bindings/input/elan_i2c.txt +11 −0
  663. Documentation/devicetree/bindings/input/sun4i-lradc-keys.txt +1 −0
  664. Documentation/devicetree/bindings/interrupt-controller/amazon,al-fic.txt +27 −0
  665. Documentation/devicetree/bindings/interrupt-controller/amlogic,meson-gpio-intc.txt +1 −0
  666. Documentation/devicetree/bindings/interrupt-controller/csky,mpintc.txt +16 −4
  667. Documentation/devicetree/bindings/interrupt-controller/intel,ixp4xx-interrupt.yaml +1 −1
  668. Documentation/devicetree/bindings/interrupt-controller/renesas,rza1-irqc.txt +43 −0
  669. Documentation/devicetree/bindings/ipmi/npcm7xx-kcs-bmc.txt +1 −1
  670. Documentation/devicetree/bindings/leds/backlight/lm3630a-backlight.yaml +14 −7
  671. Documentation/devicetree/bindings/leds/leds-lm36274.txt +85 −0
  672. Documentation/devicetree/bindings/leds/leds-lm3697.txt +73 −0
  673. Documentation/devicetree/bindings/leds/leds-spi-byte.txt +44 −0
  674. Documentation/devicetree/bindings/mailbox/omap-mailbox.txt +50 −9
  675. Documentation/devicetree/bindings/media/allegro.txt +43 −0
  676. Documentation/devicetree/bindings/media/amlogic,vdec.txt +71 −0
  677. Documentation/devicetree/bindings/media/imx7-csi.txt +3 −6
  678. Documentation/devicetree/bindings/media/marvell,mmp2-ccic.txt +50 −0
  679. Documentation/devicetree/bindings/media/st,stm32-dcmi.txt +1 −1
  680. Documentation/devicetree/bindings/media/sun6i-csi.txt +1 −0
  681. Documentation/devicetree/bindings/memory-controllers/ingenic,jz4780-nemc.txt +1 −0
  682. Documentation/devicetree/bindings/mfd/atmel-usart.txt +15 −5
  683. Documentation/devicetree/bindings/mfd/cros-ec.txt +4 −1
  684. Documentation/devicetree/bindings/mfd/lp87565.txt +36 −0
  685. Documentation/devicetree/bindings/mfd/madera.txt +6 −2
  686. Documentation/devicetree/bindings/mfd/rk808.txt +44 −0
  687. Documentation/devicetree/bindings/mfd/rohm,bd70528-pmic.txt +102 −0
  688. Documentation/devicetree/bindings/mfd/rohm,bd71837-pmic.txt +10 −0
  689. Documentation/devicetree/bindings/mfd/ti-lmu.txt +67 −21
  690. Documentation/devicetree/bindings/misc/fsl,dpaa2-console.txt +11 −0
  691. Documentation/devicetree/bindings/misc/intel,ixp4xx-ahb-queue-manager.yaml +49 −0
  692. Documentation/devicetree/bindings/misc/intel,ixp4xx-queue-manager.yaml +0 −49
  693. Documentation/devicetree/bindings/misc/olpc,xo1.75-ec.txt +23 −0
  694. Documentation/devicetree/bindings/misc/xlnx,sd-fec.txt +58 −0
  695. Documentation/devicetree/bindings/mmc/allwinner,sun4i-a10-mmc.yaml +98 −0
  696. Documentation/devicetree/bindings/mmc/amlogic,meson-gx.txt +4 −0
  697. Documentation/devicetree/bindings/mmc/mmc-controller.yaml +374 −0
  698. Documentation/devicetree/bindings/mmc/mmc.txt +1 −177
  699. Documentation/devicetree/bindings/mmc/renesas,sdhi.txt +111 −0
  700. Documentation/devicetree/bindings/mmc/sdhci-am654.txt +8 −1
  701. Documentation/devicetree/bindings/mmc/sdhci-sprd.txt +26 −0
  702. Documentation/devicetree/bindings/mmc/sunxi-mmc.txt +0 −52
  703. Documentation/devicetree/bindings/mmc/tmio_mmc.txt +0 −120
  704. Documentation/devicetree/bindings/mtd/allwinner,sun4i-a10-nand.yaml +1 −1
  705. Documentation/devicetree/bindings/mtd/brcm,brcmnand.txt +3 −2
  706. Documentation/devicetree/bindings/mtd/cadence-quadspi.txt +5 −0
  707. Documentation/devicetree/bindings/mtd/cypress,hyperflash.txt +13 −0
  708. Documentation/devicetree/bindings/mtd/nand-controller.yaml +1 −0
  709. Documentation/devicetree/bindings/mtd/stm32-quadspi.txt +0 −43
  710. Documentation/devicetree/bindings/mtd/ti,am654-hbmc.txt +51 −0
  711. Documentation/devicetree/bindings/mux/mmio-mux.txt +0 −60
  712. Documentation/devicetree/bindings/mux/reg-mux.txt +129 −0
  713. Documentation/devicetree/bindings/net/allwinner,sun4i-a10-emac.yaml +56 −0
  714. Documentation/devicetree/bindings/net/allwinner,sun4i-a10-mdio.yaml +70 −0
  715. Documentation/devicetree/bindings/net/allwinner,sun4i-emac.txt +0 −19
  716. Documentation/devicetree/bindings/net/allwinner,sun4i-mdio.txt +0 −27
  717. Documentation/devicetree/bindings/net/allwinner,sun7i-a20-gmac.txt +0 −27
  718. Documentation/devicetree/bindings/net/allwinner,sun7i-a20-gmac.yaml +65 −0
  719. Documentation/devicetree/bindings/net/allwinner,sun8i-a83t-emac.yaml +321 −0
  720. Documentation/devicetree/bindings/net/can/microchip,mcp251x.txt +1 −0
  721. Documentation/devicetree/bindings/net/can/rcar_can.txt +4 −9
  722. Documentation/devicetree/bindings/net/can/rcar_canfd.txt +10 −6
  723. Documentation/devicetree/bindings/net/dsa/ksz.txt +2 −0
  724. Documentation/devicetree/bindings/net/dsa/marvell.txt +5 −2
  725. Documentation/devicetree/bindings/net/dsa/qca8k.txt +6 −0
  726. Documentation/devicetree/bindings/net/dsa/vitesse,vsc73xx.txt +54 −4
  727. Documentation/devicetree/bindings/net/dwmac-sun8i.txt +0 −201
  728. Documentation/devicetree/bindings/net/ethernet-controller.yaml +206 −0
  729. Documentation/devicetree/bindings/net/ethernet-phy.yaml +177 −0
  730. Documentation/devicetree/bindings/net/ethernet.txt +1 −67
  731. Documentation/devicetree/bindings/net/fixed-link.txt +1 −54
  732. Documentation/devicetree/bindings/net/fsl-enetc.txt +3 −4
  733. Documentation/devicetree/bindings/net/hisilicon-hip04-net.txt +4 −3
  734. Documentation/devicetree/bindings/net/keystone-netcp.txt +44 −0
  735. Documentation/devicetree/bindings/net/macb.txt +3 −0
  736. Documentation/devicetree/bindings/net/marvell-bluetooth.txt +25 −0
  737. Documentation/devicetree/bindings/net/marvell-orion-mdio.txt +1 −1
  738. Documentation/devicetree/bindings/net/mdio.txt +1 −37
  739. Documentation/devicetree/bindings/net/mdio.yaml +74 −0
  740. Documentation/devicetree/bindings/net/mediatek-bluetooth.txt +17 −0
  741. Documentation/devicetree/bindings/net/mediatek-net.txt +12 −2
  742. Documentation/devicetree/bindings/net/phy.txt +1 −79
  743. Documentation/devicetree/bindings/net/qca,ar71xx.txt +45 −0
  744. Documentation/devicetree/bindings/net/qualcomm-bluetooth.txt +4 −0
  745. Documentation/devicetree/bindings/net/snps,dwmac.yaml +411 −0
  746. Documentation/devicetree/bindings/net/socfpga-dwmac.txt +8 −2
  747. Documentation/devicetree/bindings/net/stmmac.txt +1 −178
  748. Documentation/devicetree/bindings/net/ti,dp83867.txt +12 −2
  749. Documentation/devicetree/bindings/net/wiznet,w5x00.txt +50 −0
  750. Documentation/devicetree/bindings/net/xilinx_axienet.txt +25 −4
  751. Documentation/devicetree/bindings/nvmem/allwinner,sun4i-a10-sid.yaml +51 −0
  752. Documentation/devicetree/bindings/nvmem/allwinner,sunxi-sid.txt +0 −29
  753. Documentation/devicetree/bindings/nvmem/imx-ocotp.txt +1 −0
  754. Documentation/devicetree/bindings/nvmem/nvmem-consumer.yaml +45 −0
  755. Documentation/devicetree/bindings/nvmem/nvmem.txt +1 −80
  756. Documentation/devicetree/bindings/nvmem/nvmem.yaml +93 −0
  757. Documentation/devicetree/bindings/pci/83xx-512x-pci.txt +0 −1
  758. Documentation/devicetree/bindings/pci/amlogic,meson-pcie.txt +1 −1
  759. Documentation/devicetree/bindings/pci/mobiveil-pcie.txt +2 −0
  760. Documentation/devicetree/bindings/pci/nvidia,tegra20-pcie.txt +8 −0
  761. Documentation/devicetree/bindings/pci/pci.txt +3 −0
  762. Documentation/devicetree/bindings/pci/qcom,pcie.txt +23 −2
  763. Documentation/devicetree/bindings/pci/rcar-pci.txt +1 −0
  764. Documentation/devicetree/bindings/perf/fsl-imx-ddr.txt +21 −0
  765. Documentation/devicetree/bindings/phy/allwinner,sun6i-a31-mipi-dphy.yaml +1 −1
  766. Documentation/devicetree/bindings/phy/mixel,mipi-dsi-phy.txt +29 −0
  767. Documentation/devicetree/bindings/phy/mxs-usb-phy.txt +2 −1
  768. Documentation/devicetree/bindings/phy/nvidia,tegra124-xusb-padctl.txt +12 −0
  769. Documentation/devicetree/bindings/phy/phy-bindings.txt +1 −1
  770. Documentation/devicetree/bindings/phy/phy-pxa-usb.txt +18 −0
  771. Documentation/devicetree/bindings/phy/qcom-pcie2-phy.txt +42 −0
  772. Documentation/devicetree/bindings/phy/rcar-gen3-phy-usb2.txt +9 −4
  773. Documentation/devicetree/bindings/pinctrl/allwinner,sunxi-pinctrl.txt +2 −0
  774. Documentation/devicetree/bindings/pinctrl/aspeed,ast2400-pinctrl.yaml +83 −0
  775. Documentation/devicetree/bindings/pinctrl/aspeed,ast2500-pinctrl.yaml +133 −0
  776. Documentation/devicetree/bindings/pinctrl/bitmain,bm1880-pinctrl.txt +31 −3
  777. Documentation/devicetree/bindings/pinctrl/brcm,bcm2835-gpio.txt +3 −0
  778. Documentation/devicetree/bindings/pinctrl/fsl,imx8mm-pinctrl.txt +1 −1
  779. Documentation/devicetree/bindings/pinctrl/fsl,imx8mn-pinctrl.txt +39 −0
  780. Documentation/devicetree/bindings/pinctrl/marvell,kirkwood-pinctrl.txt +42 −2
  781. Documentation/devicetree/bindings/pinctrl/meson,pinctrl.txt +13 −3
  782. Documentation/devicetree/bindings/pinctrl/microchip,pic32-pinctrl.txt +1 −1
  783. Documentation/devicetree/bindings/pinctrl/nuvoton,npcm7xx-pinctrl.txt +1 −1
  784. Documentation/devicetree/bindings/pinctrl/nvidia,tegra194-pinmux.txt +107 −0
  785. Documentation/devicetree/bindings/pinctrl/pinctrl-aspeed.txt +0 −172
  786. Documentation/devicetree/bindings/pinctrl/pinctrl-bindings.txt +3 −0
  787. Documentation/devicetree/bindings/pinctrl/qcom,apq8084-pinctrl.txt +3 −3
  788. Documentation/devicetree/bindings/pinctrl/qcom,ipq8074-pinctrl.txt +3 −3
  789. Documentation/devicetree/bindings/pinctrl/qcom,mdm9615-pinctrl.txt +3 −3
  790. Documentation/devicetree/bindings/pinctrl/qcom,msm8916-pinctrl.txt +3 −3
  791. Documentation/devicetree/bindings/pinctrl/qcom,msm8960-pinctrl.txt +3 −3
  792. Documentation/devicetree/bindings/pinctrl/qcom,msm8994-pinctrl.txt +3 −3
  793. Documentation/devicetree/bindings/pinctrl/qcom,msm8996-pinctrl.txt +3 −3
  794. Documentation/devicetree/bindings/pinctrl/qcom,msm8998-pinctrl.txt +13 −3
  795. Documentation/devicetree/bindings/pinctrl/qcom,qcs404-pinctrl.txt +3 −3
  796. Documentation/devicetree/bindings/pinctrl/qcom,sdm660-pinctrl.txt +3 −3
  797. Documentation/devicetree/bindings/pinctrl/qcom,sdm845-pinctrl.txt +4 −4
  798. Documentation/devicetree/bindings/pinctrl/qcom,sm8150-pinctrl.txt +190 −0
  799. Documentation/devicetree/bindings/pinctrl/st,stm32-pinctrl.txt +0 −208
  800. Documentation/devicetree/bindings/pinctrl/st,stm32-pinctrl.yaml +271 −0
  801. Documentation/devicetree/bindings/power/qcom,rpmpd.txt +2 −0
  802. Documentation/devicetree/bindings/power/reset/nvmem-reboot-mode.txt +26 −0
  803. Documentation/devicetree/bindings/power/reset/qcom,pon.txt +1 −0
  804. Documentation/devicetree/bindings/property-units.txt +17 −17
  805. Documentation/devicetree/bindings/ptp/ptp-qoriq.txt +2 −0
  806. Documentation/devicetree/bindings/pwm/allwinner,sun4i-a10-pwm.yaml +57 −0
  807. Documentation/devicetree/bindings/pwm/ingenic,jz47xx-pwm.txt +1 −4
  808. Documentation/devicetree/bindings/pwm/pwm-sifive.txt +33 −0
  809. Documentation/devicetree/bindings/pwm/pwm-stm32-lp.txt +6 −3
  810. Documentation/devicetree/bindings/pwm/pwm-stm32.txt +3 −0
  811. Documentation/devicetree/bindings/pwm/pwm-sun4i.txt +0 −24
  812. Documentation/devicetree/bindings/regulator/arizona-regulator.txt +2 −1
  813. Documentation/devicetree/bindings/regulator/fixed-regulator.yaml +4 −1
  814. Documentation/devicetree/bindings/regulator/gpio-regulator.txt +0 −57
  815. Documentation/devicetree/bindings/regulator/gpio-regulator.yaml +118 −0
  816. Documentation/devicetree/bindings/regulator/max8660.txt +0 −47
  817. Documentation/devicetree/bindings/regulator/max8660.yaml +77 −0
  818. Documentation/devicetree/bindings/regulator/pv88060.txt +1 −1
  819. Documentation/devicetree/bindings/regulator/qcom,rpmh-regulator.txt +1 −1
  820. Documentation/devicetree/bindings/regulator/qcom,spmi-regulator.txt +22 −0
  821. Documentation/devicetree/bindings/regulator/regulator.txt +1 −139
  822. Documentation/devicetree/bindings/regulator/regulator.yaml +200 −0
  823. Documentation/devicetree/bindings/regulator/slg51000.txt +88 −0
  824. Documentation/devicetree/bindings/regulator/st,stm32-booster.txt +18 −0
  825. Documentation/devicetree/bindings/remoteproc/qcom,adsp-pil.txt +0 −125
  826. Documentation/devicetree/bindings/remoteproc/qcom,hexagon-v56.txt +140 −0
  827. Documentation/devicetree/bindings/remoteproc/stm32-rproc.txt +63 −0
  828. Documentation/devicetree/bindings/reset/bitmain,bm1880-reset.txt +18 −0
  829. Documentation/devicetree/bindings/reset/fsl,imx7-src.txt +1 −1
  830. Documentation/devicetree/bindings/riscv/cpus.yaml +149 −0
  831. Documentation/devicetree/bindings/riscv/sifive.yaml +25 −0
  832. Documentation/devicetree/bindings/rng/brcm,iproc-rng200.txt +1 −0
  833. Documentation/devicetree/bindings/rtc/allwinner,sun4i-a10-rtc.yaml +43 −0
  834. Documentation/devicetree/bindings/rtc/allwinner,sun6i-a31-rtc.yaml +134 −0
  835. Documentation/devicetree/bindings/rtc/rtc.txt +1 −72
  836. Documentation/devicetree/bindings/rtc/rtc.yaml +50 −0
  837. Documentation/devicetree/bindings/rtc/sun6i-rtc.txt +0 −46
  838. Documentation/devicetree/bindings/rtc/sunxi-rtc.txt +0 −17
  839. Documentation/devicetree/bindings/rtc/trivial-rtc.yaml +92 −0
  840. Documentation/devicetree/bindings/serial/8250.txt +19 −0
  841. Documentation/devicetree/bindings/serial/mtk-uart.txt +11 −2
  842. Documentation/devicetree/bindings/serial/omap_serial.txt +1 −0
  843. Documentation/devicetree/bindings/serial/st,stm32-usart.txt +1 −0
  844. Documentation/devicetree/bindings/soc/amlogic/amlogic,canvas.txt +7 −3
  845. Documentation/devicetree/bindings/soc/qcom/qcom,aoss-qmp.txt +81 −0
  846. Documentation/devicetree/bindings/soc/qcom/qcom,apr.txt +3 −3
  847. Documentation/devicetree/bindings/soc/qcom/qcom,glink.txt +5 −0
  848. Documentation/devicetree/bindings/sound/allwinner,sun4i-a10-i2s.yaml +132 −0
  849. Documentation/devicetree/bindings/sound/allwinner,sun4i-a10-spdif.yaml +120 −0
  850. Documentation/devicetree/bindings/sound/amlogic,axg-tdm-formatters.txt +5 −1
  851. Documentation/devicetree/bindings/sound/amlogic,g12a-tohdmitx.txt +55 −0
  852. Documentation/devicetree/bindings/sound/cs42l73.txt +1 −1
  853. Documentation/devicetree/bindings/sound/cs42xx8.txt +6 −0
  854. Documentation/devicetree/bindings/sound/davinci-mcasp-audio.txt +3 −0
  855. Documentation/devicetree/bindings/sound/madera.txt +67 −0
  856. Documentation/devicetree/bindings/sound/max98357a.txt +4 −0
  857. Documentation/devicetree/bindings/sound/rt1011.txt +32 −0
  858. Documentation/devicetree/bindings/sound/rt1308.txt +17 −0
  859. Documentation/devicetree/bindings/sound/st,stm32-i2s.txt +1 −1
  860. Documentation/devicetree/bindings/sound/st,stm32-sai.txt +1 −1
  861. Documentation/devicetree/bindings/sound/sun4i-i2s.txt +0 −45
  862. Documentation/devicetree/bindings/sound/sunxi,sun4i-spdif.txt +0 −42
  863. Documentation/devicetree/bindings/spi/allwinner,sun4i-a10-spi.yaml +87 −0
  864. Documentation/devicetree/bindings/spi/allwinner,sun6i-a31-spi.yaml +107 −0
  865. Documentation/devicetree/bindings/spi/spi-bus.txt +1 −111
  866. Documentation/devicetree/bindings/spi/spi-controller.yaml +161 −0
  867. Documentation/devicetree/bindings/spi/spi-gpio.txt +0 −43
  868. Documentation/devicetree/bindings/spi/spi-gpio.yaml +72 −0
  869. Documentation/devicetree/bindings/spi/spi-pl022.yaml +165 −0
  870. Documentation/devicetree/bindings/spi/spi-stm32-qspi.txt +4 −1
  871. Documentation/devicetree/bindings/spi/spi-sun4i.txt +0 −23
  872. Documentation/devicetree/bindings/spi/spi-sun6i.txt +0 −44
  873. Documentation/devicetree/bindings/spi/spi-synquacer.txt +27 −0
  874. Documentation/devicetree/bindings/spi/spi_pl022.txt +0 −70
  875. Documentation/devicetree/bindings/timer/intel,ixp4xx-timer.yaml +1 −1
  876. Documentation/devicetree/bindings/timer/nxp,sysctr-timer.txt +25 −0
  877. Documentation/devicetree/bindings/timer/renesas,cmt.txt +6 −0
  878. Documentation/devicetree/bindings/trivial-devices.yaml +4 −0
  879. Documentation/devicetree/bindings/usb/dwc2.txt +3 −0
  880. Documentation/devicetree/bindings/usb/dwc3.txt +2 −0
  881. Documentation/devicetree/bindings/usb/generic-ehci.yaml +1 −2
  882. Documentation/devicetree/bindings/usb/renesas,usb3.txt +0 −0
  883. Documentation/devicetree/bindings/usb/renesas,usbhs.txt +57 −0
  884. Documentation/devicetree/bindings/usb/renesas_usbhs.txt +0 −55
  885. Documentation/devicetree/bindings/usb/s3c2410-usb.txt +1 −1
  886. Documentation/devicetree/bindings/usb/usb251xb.txt +2 −4
  887. Documentation/devicetree/bindings/vendor-prefixes.yaml +80 −4
  888. Documentation/devicetree/bindings/virtio/iommu.txt +66 −0
  889. Documentation/devicetree/bindings/virtio/mmio.txt +30 −0
  890. Documentation/devicetree/bindings/watchdog/fsl-imx-sc-wdt.txt +0 −24
  891. Documentation/devicetree/bindings/watchdog/renesas,wdt.txt +0 −0
  892. Documentation/devicetree/bindings/watchdog/sunxi-wdt.txt +1 −0
  893. Documentation/devicetree/booting-without-of.txt +3 −3
  894. Documentation/doc-guide/conf.py +0 −10
  895. Documentation/doc-guide/kernel-doc.rst +1 −1
  896. Documentation/doc-guide/sphinx.rst +17 −15
  897. Documentation/docutils.conf +1 −1
  898. Documentation/dontdiff +1 −0
  899. Documentation/driver-api/80211/conf.py +0 −10
  900. Documentation/driver-api/80211/mac80211-advanced.rst +0 −3
  901. Documentation/driver-api/backlight/lp855x-driver.rst +81 −0
  902. Documentation/driver-api/basics.rst +0 −3
  903. Documentation/driver-api/bt8xxgpio.rst +0 −0
  904. Documentation/driver-api/clk.rst +3 −3
  905. Documentation/driver-api/conf.py +0 −10
  906. Documentation/driver-api/connector.rst +156 −0
  907. Documentation/driver-api/console.rst +152 −0
  908. Documentation/driver-api/dcdbas.rst +0 −0
  909. Documentation/driver-api/dell_rbu.rst +0 −0
  910. Documentation/driver-api/dmaengine/dmatest.rst +13 −8
  911. Documentation/driver-api/driver-model/binding.rst +98 −0
  912. Documentation/driver-api/driver-model/bus.rst +146 −0
  913. Documentation/driver-api/driver-model/class.rst +149 −0
  914. Documentation/driver-api/driver-model/design-patterns.rst +116 −0
  915. Documentation/driver-api/driver-model/device.rst +109 −0
  916. Documentation/driver-api/driver-model/devres.rst +418 −0
  917. Documentation/driver-api/driver-model/driver.rst +223 −0
  918. Documentation/driver-api/driver-model/index.rst +24 −0
  919. Documentation/driver-api/driver-model/overview.rst +124 −0
  920. Documentation/driver-api/driver-model/platform.rst +246 −0
  921. Documentation/driver-api/driver-model/porting.rst +448 −0
  922. Documentation/driver-api/early-userspace/buffer-format.rst +119 −0
  923. Documentation/driver-api/early-userspace/early_userspace_support.rst +154 −0
  924. Documentation/driver-api/early-userspace/index.rst +18 −0
  925. Documentation/driver-api/edid.rst +58 −0
  926. Documentation/driver-api/eisa.rst +230 −0
  927. Documentation/driver-api/firmware/other_interfaces.rst +1 −1
  928. Documentation/driver-api/generic-counter.rst +2 −2
  929. Documentation/driver-api/gpio/board.rst +1 −1
  930. Documentation/driver-api/gpio/consumer.rst +2 −4
  931. Documentation/driver-api/gpio/driver.rst +9 −9
  932. Documentation/driver-api/iio/hw-consumer.rst +0 −1
  933. Documentation/driver-api/index.rst +44 −1
  934. Documentation/driver-api/interconnect.rst +2 −3
  935. Documentation/driver-api/ipmb.rst +105 −0
  936. Documentation/driver-api/isa.rst +0 −0
  937. Documentation/driver-api/isapnp.rst +0 −0
  938. Documentation/driver-api/lightnvm-pblk.rst +0 −0
  939. Documentation/driver-api/md/index.rst +12 −0
  940. Documentation/driver-api/md/md-cluster.rst +385 −0
  941. Documentation/driver-api/md/raid5-cache.rst +111 −0
  942. Documentation/driver-api/md/raid5-ppl.rst +47 −0
  943. Documentation/driver-api/mei/hdcp.rst +32 −0
  944. Documentation/driver-api/mei/iamt.rst +101 −0
  945. Documentation/driver-api/mei/index.rst +23 −0
  946. Documentation/driver-api/mei/mei-client-bus.rst +168 −0
  947. Documentation/driver-api/mei/mei.rst +176 −0
  948. Documentation/driver-api/mei/nfc.rst +28 −0
  949. Documentation/driver-api/memory-devices/index.rst +18 −0
  950. Documentation/driver-api/memory-devices/ti-emif.rst +64 −0
  951. Documentation/driver-api/memory-devices/ti-gpmc.rst +179 −0
  952. Documentation/driver-api/men-chameleon-bus.rst +0 −0
  953. Documentation/driver-api/mmc/index.rst +13 −0
  954. Documentation/driver-api/mmc/mmc-async-req.rst +98 −0
  955. Documentation/driver-api/mmc/mmc-dev-attrs.rst +91 −0
  956. Documentation/driver-api/mmc/mmc-dev-parts.rst +41 −0
  957. Documentation/driver-api/mmc/mmc-tools.rst +37 −0
  958. Documentation/driver-api/mtd/index.rst +12 −0
  959. Documentation/driver-api/mtd/intel-spi.rst +90 −0
  960. Documentation/driver-api/mtd/nand_ecc.rst +763 −0
  961. Documentation/driver-api/mtd/spi-nor.rst +66 −0
  962. Documentation/driver-api/nfc/index.rst +11 −0
  963. Documentation/driver-api/nfc/nfc-hci.rst +311 −0
  964. Documentation/driver-api/nfc/nfc-pn544.rst +34 −0
  965. Documentation/driver-api/ntb.rst +263 −0
  966. Documentation/driver-api/nvdimm/btt.rst +285 −0
  967. Documentation/driver-api/nvdimm/index.rst +12 −0
  968. Documentation/driver-api/nvdimm/nvdimm.rst +887 −0
  969. Documentation/driver-api/nvdimm/security.rst +143 −0
  970. Documentation/driver-api/nvmem.rst +189 −0
  971. Documentation/driver-api/parport-lowlevel.rst +0 −0
  972. Documentation/driver-api/phy/index.rst +18 −0
  973. Documentation/driver-api/phy/phy.rst +197 −0
  974. Documentation/driver-api/phy/samsung-usb2.rst +137 −0
  975. Documentation/driver-api/pm/conf.py +0 −10
  976. Documentation/driver-api/pm/devices.rst +3 −3
  977. Documentation/driver-api/pps.rst +242 −0
  978. Documentation/driver-api/pti_intel_mid.rst +106 −0
  979. Documentation/driver-api/ptp.rst +96 −0
  980. Documentation/driver-api/pwm.rst +165 −0
  981. Documentation/driver-api/rapidio/index.rst +15 −0
  982. Documentation/driver-api/rapidio/mport_cdev.rst +110 −0
  983. Documentation/driver-api/rapidio/rapidio.rst +362 −0
  984. Documentation/driver-api/rapidio/rio_cm.rst +135 −0
  985. Documentation/driver-api/rapidio/sysfs.rst +7 −0
  986. Documentation/driver-api/rapidio/tsi721.rst +112 −0
  987. Documentation/driver-api/rfkill.rst +0 −0
  988. Documentation/driver-api/s390-drivers.rst +2 −2
  989. Documentation/driver-api/serial/cyclades_z.rst +0 −0
  990. Documentation/driver-api/serial/driver.rst +549 −0
  991. Documentation/driver-api/serial/index.rst +32 −0
  992. Documentation/driver-api/serial/moxa-smartio.rst +0 −0
  993. Documentation/driver-api/serial/n_gsm.rst +0 −0
  994. Documentation/driver-api/serial/rocket.rst +0 −0
  995. Documentation/driver-api/serial/serial-iso7816.rst +0 −0
  996. Documentation/driver-api/serial/serial-rs485.rst +0 −0
  997. Documentation/driver-api/serial/tty.rst +0 −0
  998. Documentation/driver-api/sgi-ioc4.rst +0 −0
  999. Documentation/driver-api/sm501.rst +0 −0
  1000. Documentation/driver-api/smsc_ece1099.rst +0 −0
  1001. Documentation/driver-api/soundwire/locking.rst +3 −1
  1002. Documentation/driver-api/switchtec.rst +102 −0
  1003. Documentation/driver-api/sync_file.rst +0 −0
  1004. Documentation/driver-api/target.rst +2 −2
  1005. Documentation/driver-api/uio-howto.rst +2 −2
  1006. Documentation/driver-api/usb/power-management.rst +1 −1
  1007. Documentation/driver-api/vfio-mediated-device.rst +414 −0
  1008. Documentation/driver-api/vfio.rst +0 −0
  1009. Documentation/driver-api/xilinx/eemi.rst +67 −0
  1010. Documentation/driver-api/xilinx/index.rst +16 −0
  1011. Documentation/driver-api/xillybus.rst +0 −0
  1012. Documentation/driver-api/zorro.rst +0 −0
  1013. Documentation/driver-model/binding.txt +0 −98
  1014. Documentation/driver-model/bus.txt +0 −143
  1015. Documentation/driver-model/class.txt +0 −147
  1016. Documentation/driver-model/design-patterns.txt +0 −116
  1017. Documentation/driver-model/device.txt +0 −106
  1018. Documentation/driver-model/devres.txt +0 −412
  1019. Documentation/driver-model/driver.txt +0 −215
  1020. Documentation/driver-model/overview.txt +0 −123
  1021. Documentation/driver-model/platform.txt +0 −244
  1022. Documentation/driver-model/porting.txt +0 −447
  1023. Documentation/early-userspace/README +0 −151
  1024. Documentation/early-userspace/buffer-format.txt +0 −112
  1025. Documentation/eisa.txt +0 −230
  1026. Documentation/extcon/intel-int3496.txt +0 −27
  1027. Documentation/fault-injection/fault-injection.rst +446 −0
  1028. Documentation/fault-injection/fault-injection.txt +0 −435
  1029. Documentation/fault-injection/index.rst +20 −0
  1030. Documentation/fault-injection/notifier-error-inject.rst +98 −0
  1031. Documentation/fault-injection/notifier-error-inject.txt +0 −94
  1032. Documentation/fault-injection/nvme-fault-injection.rst +178 −0
  1033. Documentation/fault-injection/nvme-fault-injection.txt +0 −116
  1034. Documentation/fault-injection/provoke-crashes.rst +48 −0
  1035. Documentation/fault-injection/provoke-crashes.txt +0 −38
  1036. Documentation/fb/api.rst +307 −0
  1037. Documentation/fb/api.txt +0 −306
  1038. Documentation/fb/arkfb.rst +68 −0
  1039. Documentation/fb/arkfb.txt +0 −68
  1040. Documentation/fb/aty128fb.rst +75 −0
  1041. Documentation/fb/aty128fb.txt +0 −72
  1042. Documentation/fb/cirrusfb.rst +94 −0
  1043. Documentation/fb/cirrusfb.txt +0 −97
  1044. Documentation/fb/cmap_xfbdev.rst +56 −0
  1045. Documentation/fb/cmap_xfbdev.txt +0 −53
  1046. Documentation/fb/deferred_io.rst +79 −0
  1047. Documentation/fb/deferred_io.txt +0 −75
  1048. Documentation/fb/efifb.rst +39 −0
  1049. Documentation/fb/efifb.txt +0 −37
  1050. Documentation/fb/ep93xx-fb.rst +140 −0
  1051. Documentation/fb/ep93xx-fb.txt +0 −135
  1052. Documentation/fb/fbcon.rst +350 −0
  1053. Documentation/fb/fbcon.txt +0 −347
  1054. Documentation/fb/framebuffer.rst +353 −0
  1055. Documentation/fb/framebuffer.txt +0 −343
  1056. Documentation/fb/gxfb.rst +54 −0
  1057. Documentation/fb/gxfb.txt +0 −52
  1058. Documentation/fb/index.rst +50 −0
  1059. Documentation/fb/intel810.rst +287 −0
  1060. Documentation/fb/intel810.txt +0 −278
  1061. Documentation/fb/intelfb.rst +155 −0
  1062. Documentation/fb/intelfb.txt +0 −149
  1063. Documentation/fb/internals.rst +86 −0
  1064. Documentation/fb/internals.txt +0 −82
  1065. Documentation/fb/lxfb.rst +55 −0
  1066. Documentation/fb/lxfb.txt +0 −52
  1067. Documentation/fb/matroxfb.rst +443 −0
  1068. Documentation/fb/matroxfb.txt +0 −413
  1069. Documentation/fb/metronomefb.rst +38 −0
  1070. Documentation/fb/metronomefb.txt +0 −36
  1071. Documentation/fb/modedb.rst +169 −0
  1072. Documentation/fb/modedb.txt +0 −165
  1073. Documentation/fb/pvr2fb.rst +66 −0
  1074. Documentation/fb/pvr2fb.txt +0 −65
  1075. Documentation/fb/pxafb.rst +173 −0
  1076. Documentation/fb/pxafb.txt +0 −142
  1077. Documentation/fb/s3fb.rst +82 −0
  1078. Documentation/fb/s3fb.txt +0 −82
  1079. Documentation/fb/sa1100fb.rst +40 −0
  1080. Documentation/fb/sa1100fb.txt +0 −39
  1081. Documentation/fb/sh7760fb.rst +130 −0
  1082. Documentation/fb/sh7760fb.txt +0 −131
  1083. Documentation/fb/sisfb.rst +160 −0
  1084. Documentation/fb/sisfb.txt +0 −158
  1085. Documentation/fb/sm501.rst +15 −0
  1086. Documentation/fb/sm501.txt +0 −10
  1087. Documentation/fb/sm712fb.rst +35 −0
  1088. Documentation/fb/sm712fb.txt +0 −31
  1089. Documentation/fb/sstfb.rst +207 −0
  1090. Documentation/fb/sstfb.txt +0 −174
  1091. Documentation/fb/tgafb.rst +71 −0
  1092. Documentation/fb/tgafb.txt +0 −69
  1093. Documentation/fb/tridentfb.rst +78 −0
  1094. Documentation/fb/tridentfb.txt +0 −70
  1095. Documentation/fb/udlfb.rst +162 −0
  1096. Documentation/fb/udlfb.txt +0 −159
  1097. Documentation/fb/uvesafb.rst +188 −0
  1098. Documentation/fb/uvesafb.txt +0 −184
  1099. Documentation/fb/vesafb.rst +192 −0
  1100. Documentation/fb/vesafb.txt +0 −181
  1101. Documentation/fb/viafb.rst +297 −0
  1102. Documentation/fb/viafb.txt +0 −252
  1103. Documentation/fb/vt8623fb.rst +64 −0
  1104. Documentation/fb/vt8623fb.txt +0 −64
  1105. Documentation/features/debug/stackprotector/arch-support.txt +1 −1
  1106. Documentation/filesystems/Locking +0 −14
  1107. Documentation/filesystems/api-summary.rst +0 −3
  1108. Documentation/filesystems/coda.txt +7 −4
  1109. Documentation/filesystems/conf.py +0 −10
  1110. Documentation/filesystems/dax.txt +1 −1
  1111. Documentation/filesystems/debugfs.txt +1 −1
  1112. Documentation/filesystems/ext2.txt +7 −1
  1113. Documentation/filesystems/ext4/index.rst +4 −4
  1114. Documentation/filesystems/f2fs.txt +123 −10
  1115. Documentation/filesystems/fscrypt.rst +42 −1
  1116. Documentation/filesystems/index.rst +2 −11
  1117. Documentation/filesystems/nfs/nfsroot.txt +1 −1
  1118. Documentation/filesystems/porting +18 −7
  1119. Documentation/filesystems/proc.txt +74 −13
  1120. Documentation/filesystems/ramfs-rootfs-initramfs.txt +2 −2
  1121. Documentation/filesystems/sysfs.txt +1 −1
  1122. Documentation/filesystems/tmpfs.txt +1 −1
  1123. Documentation/filesystems/ubifs-authentication.md +2 −2
  1124. Documentation/filesystems/vfs.rst +1428 −0
  1125. Documentation/filesystems/vfs.txt +0 −1268
  1126. Documentation/filesystems/xfs-delayed-logging-design.txt +1 −1
  1127. Documentation/filesystems/xfs-self-describing-metadata.txt +4 −4
  1128. Documentation/filesystems/xfs.txt +0 −470
  1129. Documentation/firmware-guide/acpi/enumeration.rst +2 −2
  1130. Documentation/firmware-guide/acpi/extcon-intel-int3496.rst +33 −0
  1131. Documentation/firmware-guide/acpi/index.rst +1 −0
  1132. Documentation/firmware-guide/acpi/method-tracing.rst +1 −1
  1133. Documentation/fmc/API.txt +0 −47
  1134. Documentation/fmc/FMC-and-SDB.txt +0 −88
  1135. Documentation/fmc/carrier.txt +0 −311
  1136. Documentation/fmc/fmc-chardev.txt +0 −64
  1137. Documentation/fmc/fmc-fakedev.txt +0 −36
  1138. Documentation/fmc/fmc-trivial.txt +0 −17
  1139. Documentation/fmc/fmc-write-eeprom.txt +0 −98
  1140. Documentation/fmc/identifiers.txt +0 −168
  1141. Documentation/fmc/mezzanine.txt +0 −123
  1142. Documentation/fmc/parameters.txt +0 −56
  1143. Documentation/fpga/dfl.rst +291 −0
  1144. Documentation/fpga/dfl.txt +0 −285
  1145. Documentation/fpga/index.rst +17 −0
  1146. Documentation/gpio/index.rst +0 −17
  1147. Documentation/gpu/conf.py +0 −10
  1148. Documentation/gpu/msm-crash-dump.rst +2 −0
  1149. Documentation/hid/hid-alps.rst +180 −0
  1150. Documentation/hid/hid-alps.txt +0 −139
  1151. Documentation/hid/hid-sensor.rst +242 −0
  1152. Documentation/hid/hid-sensor.txt +0 −224
  1153. Documentation/hid/hid-transport.rst +359 −0
  1154. Documentation/hid/hid-transport.txt +0 −317
  1155. Documentation/hid/hiddev.rst +251 −0
  1156. Documentation/hid/hiddev.txt +0 −205
  1157. Documentation/hid/hidraw.rst +138 −0
  1158. Documentation/hid/hidraw.txt +0 −119
  1159. Documentation/hid/index.rst +18 −0
  1160. Documentation/hid/intel-ish-hid.rst +485 −0
  1161. Documentation/hid/intel-ish-hid.txt +0 −454
  1162. Documentation/hid/uhid.rst +193 −0
  1163. Documentation/hid/uhid.txt +0 −187
  1164. Documentation/hwmon/k8temp.rst +1 −1
  1165. Documentation/hwmon/pxe1610 +90 −0
  1166. Documentation/hwmon/submitting-patches.rst +1 −1
  1167. Documentation/hwspinlock.txt +81 −0
  1168. Documentation/i2c/busses/i2c-i801 +11 −9
  1169. Documentation/i2c/instantiating-devices +2 −2
  1170. Documentation/i2c/upgrading-clients +2 −2
  1171. Documentation/ia64/IRQ-redir.txt +0 −69
  1172. Documentation/ia64/README +0 −43
  1173. Documentation/ia64/aliasing.rst +246 −0
  1174. Documentation/ia64/aliasing.txt +0 −221
  1175. Documentation/ia64/efirtc.rst +144 −0
  1176. Documentation/ia64/efirtc.txt +0 −128
  1177. Documentation/ia64/err_inject.rst +1067 −0
  1178. Documentation/ia64/err_inject.txt +0 −1068
  1179. Documentation/ia64/fsys.rst +303 −0
  1180. Documentation/ia64/fsys.txt +0 −286
  1181. Documentation/ia64/ia64.rst +49 −0
  1182. Documentation/ia64/index.rst +18 −0
  1183. Documentation/ia64/irq-redir.rst +80 −0
  1184. Documentation/ia64/mca.rst +198 −0
  1185. Documentation/ia64/mca.txt +0 −194
  1186. Documentation/ia64/serial.rst +165 −0
  1187. Documentation/ia64/serial.txt +0 −151
  1188. Documentation/ia64/xen.rst +206 −0
  1189. Documentation/ia64/xen.txt +0 −183
  1190. Documentation/ide/changelogs.rst +17 −0
  1191. Documentation/ide/ide-tape.rst +68 −0
  1192. Documentation/ide/ide-tape.txt +0 −65
  1193. Documentation/ide/ide.rst +265 −0
  1194. Documentation/ide/ide.txt +0 −256
  1195. Documentation/ide/index.rst +21 −0
  1196. Documentation/ide/warm-plug-howto.rst +18 −0
  1197. Documentation/ide/warm-plug-howto.txt +0 −18
  1198. Documentation/iio/ep93xx_adc.rst +40 −0
  1199. Documentation/iio/ep93xx_adc.txt +0 −29
  1200. Documentation/iio/iio_configfs.rst +101 −0
  1201. Documentation/iio/iio_configfs.txt +0 −93
  1202. Documentation/iio/index.rst +12 −0
  1203. Documentation/index.rst +38 −1
  1204. Documentation/infiniband/core_locking.rst +118 −0
  1205. Documentation/infiniband/core_locking.txt +0 −112
  1206. Documentation/infiniband/index.rst +23 −0
  1207. Documentation/infiniband/ipoib.rst +115 −0
  1208. Documentation/infiniband/ipoib.txt +0 −105
  1209. Documentation/infiniband/opa_vnic.rst +159 −0
  1210. Documentation/infiniband/opa_vnic.txt +0 −153
  1211. Documentation/infiniband/sysfs.rst +6 −0
  1212. Documentation/infiniband/sysfs.txt +0 −4
  1213. Documentation/infiniband/tag_matching.rst +69 −0
  1214. Documentation/infiniband/tag_matching.txt +0 −64
  1215. Documentation/infiniband/user_mad.rst +166 −0
  1216. Documentation/infiniband/user_mad.txt +0 −153
  1217. Documentation/infiniband/user_verbs.rst +75 −0
  1218. Documentation/infiniband/user_verbs.txt +0 −69
  1219. Documentation/input/conf.py +0 −10
  1220. Documentation/input/input.rst +1 −1
  1221. Documentation/ioctl/botching-up-ioctls.rst +225 −0
  1222. Documentation/ioctl/botching-up-ioctls.txt +0 −224
  1223. Documentation/ioctl/cdrom.rst +1233 −0
  1224. Documentation/ioctl/cdrom.txt +0 −967
  1225. Documentation/ioctl/hdio.rst +1342 −0
  1226. Documentation/ioctl/hdio.txt +0 −1071
  1227. Documentation/ioctl/index.rst +16 −0
  1228. Documentation/ioctl/ioctl-decoding.rst +31 −0
  1229. Documentation/ioctl/ioctl-decoding.txt +0 −24
  1230. Documentation/ioctl/ioctl-number.rst +361 −0
  1231. Documentation/ioctl/ioctl-number.txt +0 −350
  1232. Documentation/iostats.txt +0 −193
  1233. Documentation/isdn/HiSax.cert +0 −96
  1234. Documentation/isdn/INTERFACE +0 −759
  1235. Documentation/isdn/INTERFACE.fax +0 −163
  1236. Documentation/isdn/README +0 −599
  1237. Documentation/isdn/README.FAQ +0 −26
  1238. Documentation/isdn/README.HiSax +0 −659
  1239. Documentation/isdn/README.audio +0 −138
  1240. Documentation/isdn/README.concap +0 −259
  1241. Documentation/isdn/README.diversion +0 −127
  1242. Documentation/isdn/README.fax +0 −45
  1243. Documentation/isdn/README.gigaset +8 −28
  1244. Documentation/isdn/README.hfc-pci +0 −41
  1245. Documentation/isdn/README.syncppp +0 −58
  1246. Documentation/isdn/README.x25 +0 −184
  1247. Documentation/isdn/syncPPP.FAQ +0 −224
  1248. Documentation/kbuild/headers_install.rst +44 −0
  1249. Documentation/kbuild/headers_install.txt +0 −50
  1250. Documentation/kbuild/index.rst +27 −0
  1251. Documentation/kbuild/issues.rst +15 −0
  1252. Documentation/kbuild/kbuild.rst +274 −0
  1253. Documentation/kbuild/kbuild.txt +0 −248
  1254. Documentation/kbuild/kconfig-language.rst +701 −0
  1255. Documentation/kbuild/kconfig-language.txt +0 −669
  1256. Documentation/kbuild/kconfig-macro-language.rst +247 −0
  1257. Documentation/kbuild/kconfig-macro-language.txt +0 −242
  1258. Documentation/kbuild/kconfig.rst +304 −0
  1259. Documentation/kbuild/kconfig.txt +0 −272
  1260. Documentation/kbuild/makefiles.rst +1522 −0
  1261. Documentation/kbuild/makefiles.txt +0 −1369
  1262. Documentation/kbuild/modules.rst +571 −0
  1263. Documentation/kbuild/modules.txt +0 −541
  1264. Documentation/kdump/kdump.txt +0 −509
  1265. Documentation/kdump/vmcoreinfo.txt +0 −495
  1266. Documentation/kernel-hacking/conf.py +0 −10
  1267. Documentation/kernel-hacking/hacking.rst +2 −2
  1268. Documentation/kernel-hacking/locking.rst +4 −4
  1269. Documentation/kernel-per-CPU-kthreads.txt +0 −356
  1270. Documentation/laptops/asus-laptop.txt +0 −257
  1271. Documentation/laptops/disk-shock-protection.txt +0 −149
  1272. Documentation/laptops/laptop-mode.txt +0 −782
  1273. Documentation/laptops/sony-laptop.txt +0 −144
  1274. Documentation/laptops/sonypi.txt +0 −152
  1275. Documentation/laptops/thinkpad-acpi.txt +0 −1487
  1276. Documentation/laptops/toshiba_haps.txt +0 −76
  1277. Documentation/leds/index.rst +25 −0
  1278. Documentation/leds/leds-blinkm.rst +84 −0
  1279. Documentation/leds/leds-blinkm.txt +0 −80
  1280. Documentation/leds/leds-class-flash.rst +90 −0
  1281. Documentation/leds/leds-class-flash.txt +0 −73
  1282. Documentation/leds/leds-class.rst +125 −0
  1283. Documentation/leds/leds-class.txt +0 −122
  1284. Documentation/leds/leds-lm3556.rst +137 −0
  1285. Documentation/leds/leds-lm3556.txt +0 −85
  1286. Documentation/leds/leds-lp3944.rst +59 −0
  1287. Documentation/leds/leds-lp3944.txt +0 −50
  1288. Documentation/leds/leds-lp5521.rst +115 −0
  1289. Documentation/leds/leds-lp5521.txt +0 −101
  1290. Documentation/leds/leds-lp5523.rst +147 −0
  1291. Documentation/leds/leds-lp5523.txt +0 −130
  1292. Documentation/leds/leds-lp5562.rst +137 −0
  1293. Documentation/leds/leds-lp5562.txt +0 −120
  1294. Documentation/leds/leds-lp55xx.rst +224 −0
  1295. Documentation/leds/leds-lp55xx.txt +0 −194
  1296. Documentation/leds/leds-mlxcpld.rst +118 −0
  1297. Documentation/leds/leds-mlxcpld.txt +0 −110
  1298. Documentation/leds/ledtrig-oneshot.rst +44 −0
  1299. Documentation/leds/ledtrig-oneshot.txt +0 −43
  1300. Documentation/leds/ledtrig-transient.rst +167 −0
  1301. Documentation/leds/ledtrig-transient.txt +0 −152
  1302. Documentation/leds/ledtrig-usbport.rst +46 −0
  1303. Documentation/leds/ledtrig-usbport.txt +0 −41
  1304. Documentation/leds/uleds.rst +37 −0
  1305. Documentation/leds/uleds.txt +0 −36
  1306. Documentation/livepatch/index.rst +1 −1
  1307. Documentation/locking/index.rst +24 −0
  1308. Documentation/locking/lockdep-design.rst +394 −0
  1309. Documentation/locking/lockdep-design.txt +0 −333
  1310. Documentation/locking/lockstat.rst +204 −0
  1311. Documentation/locking/lockstat.txt +0 −183
  1312. Documentation/locking/locktorture.rst +170 −0
  1313. Documentation/locking/locktorture.txt +0 −145
  1314. Documentation/locking/mutex-design.rst +152 −0
  1315. Documentation/locking/mutex-design.txt +0 −142
  1316. Documentation/locking/rt-mutex-design.rst +574 −0
  1317. Documentation/locking/rt-mutex-design.txt +0 −559
  1318. Documentation/locking/rt-mutex.rst +77 −0
  1319. Documentation/locking/rt-mutex.txt +0 −73
  1320. Documentation/locking/spinlocks.rst +177 −0
  1321. Documentation/locking/spinlocks.txt +0 −167
  1322. Documentation/locking/ww-mutex-design.rst +393 −0
  1323. Documentation/locking/ww-mutex-design.txt +0 −383
  1324. Documentation/m68k/index.rst +17 −0
  1325. Documentation/m68k/kernel-options.rst +911 −0
  1326. Documentation/m68k/kernel-options.txt +0 −884
  1327. Documentation/maintainer/conf.py +0 −10
  1328. Documentation/maintainer/index.rst +1 −0
  1329. Documentation/maintainer/rebasing-and-merging.rst +226 −0
  1330. Documentation/md/md-cluster.txt +0 −325
  1331. Documentation/md/raid5-cache.txt +0 −109
  1332. Documentation/md/raid5-ppl.txt +0 −45
  1333. Documentation/media/conf.py +0 −12
  1334. Documentation/media/kapi/dtv-core.rst +3 −3
  1335. Documentation/media/kapi/v4l2-controls.rst +102 −104
  1336. Documentation/media/uapi/cec/cec-api.rst +1 −1
  1337. Documentation/media/uapi/cec/cec-ioc-g-mode.rst +2 −1
  1338. Documentation/media/uapi/cec/cec-ioc-receive.rst +14 −1
  1339. Documentation/media/uapi/mediactl/media-ioc-enum-links.rst +6 −1
  1340. Documentation/media/uapi/rc/rc-tables.rst +15 −15
  1341. Documentation/media/uapi/v4l/biblio.rst +9 −0
  1342. Documentation/media/uapi/v4l/ext-ctrls-codec.rst +625 −0
  1343. Documentation/media/uapi/v4l/extended-controls.rst +6 −9
  1344. Documentation/media/uapi/v4l/field-order.rst +11 −6
  1345. Documentation/media/uapi/v4l/pixfmt-compressed.rst +25 −0
  1346. Documentation/media/uapi/v4l/pixfmt-v4l2-mplane.rst +14 −1
  1347. Documentation/media/uapi/v4l/pixfmt-v4l2.rst +12 −1
  1348. Documentation/media/uapi/v4l/vidioc-qbuf.rst +8 −0
  1349. Documentation/media/uapi/v4l/vidioc-queryctrl.rst +30 −0
  1350. Documentation/media/v4l-drivers/index.rst +1 −0
  1351. Documentation/media/v4l-drivers/vimc.dot +22 −0
  1352. Documentation/media/v4l-drivers/vimc.rst +98 −0
  1353. Documentation/media/v4l-drivers/vivid.rst +5 −0
  1354. Documentation/media/videodev2.h.rst.exceptions +5 −0
  1355. Documentation/memory-barriers.txt +2 −2
  1356. Documentation/memory-devices/ti-emif.txt +0 −57
  1357. Documentation/mic/index.rst +16 −0
  1358. Documentation/mic/mic_overview.rst +85 −0
  1359. Documentation/mic/mic_overview.txt +0 −81
  1360. Documentation/mic/scif_overview.rst +108 −0
  1361. Documentation/mic/scif_overview.txt +0 −98
  1362. Documentation/misc-devices/eeprom +0 −96
  1363. Documentation/misc-devices/eeprom.rst +107 −0
  1364. Documentation/misc-devices/ics932s401 +0 −31
  1365. Documentation/misc-devices/ics932s401.rst +36 −0
  1366. Documentation/misc-devices/index.rst +5 −0
  1367. Documentation/misc-devices/isl29003 +0 −62
  1368. Documentation/misc-devices/isl29003.rst +75 −0
  1369. Documentation/misc-devices/lis3lv02d +0 −93
  1370. Documentation/misc-devices/lis3lv02d.rst +99 −0
  1371. Documentation/misc-devices/max6875 +0 −110
  1372. Documentation/misc-devices/max6875.rst +136 −0
  1373. Documentation/misc-devices/mei/mei-client-bus.txt +0 −141
  1374. Documentation/misc-devices/mei/mei.txt +0 −266
  1375. Documentation/mmc/mmc-async-req.txt +0 −87
  1376. Documentation/mmc/mmc-dev-attrs.txt +0 −77
  1377. Documentation/mmc/mmc-dev-parts.txt +0 −40
  1378. Documentation/mmc/mmc-tools.txt +0 −34
  1379. Documentation/mtd/intel-spi.txt +0 −88
  1380. Documentation/mtd/nand_ecc.txt +0 −714
  1381. Documentation/mtd/spi-nor.txt +0 −65
  1382. Documentation/namespaces/compatibility-list.txt +0 −39
  1383. Documentation/namespaces/resource-control.txt +0 −14
  1384. Documentation/netlabel/cipso_ipv4.rst +56 −0
  1385. Documentation/netlabel/cipso_ipv4.txt +0 −49
  1386. Documentation/netlabel/draft_ietf.rst +5 −0
  1387. Documentation/netlabel/index.rst +21 −0
  1388. Documentation/netlabel/introduction.rst +52 −0
  1389. Documentation/netlabel/introduction.txt +0 −46
  1390. Documentation/netlabel/lsm_interface.rst +53 −0
  1391. Documentation/netlabel/lsm_interface.txt +0 −47
  1392. Documentation/networking/af_xdp.rst +19 −5
  1393. Documentation/networking/bonding.txt +13 −3
  1394. Documentation/networking/conf.py +0 −10
  1395. Documentation/networking/device_drivers/amazon/ena.txt +4 −1
  1396. Documentation/networking/device_drivers/aquantia/atlantic.txt +439 −0
  1397. Documentation/networking/device_drivers/freescale/dpaa2/dpio-driver.rst +2 −2
  1398. Documentation/networking/device_drivers/google/gve.rst +123 −0
  1399. Documentation/networking/device_drivers/index.rst +2 −0
  1400. Documentation/networking/device_drivers/mellanox/mlx5.rst +192 −0
  1401. Documentation/networking/dsa/b53.rst +183 −0
  1402. Documentation/networking/dsa/configuration.rst +292 −0
  1403. Documentation/networking/dsa/dsa.rst +2 −2
  1404. Documentation/networking/dsa/index.rst +2 −0
  1405. Documentation/networking/dsa/sja1105.rst +3 −3
  1406. Documentation/networking/ip-sysctl.txt +56 −6
  1407. Documentation/networking/mpls-sysctl.txt +1 −1
  1408. Documentation/networking/phy.rst +44 −1
  1409. Documentation/networking/rds.txt +1 −1
  1410. Documentation/networking/sfp-phylink.rst +4 −1
  1411. Documentation/networking/timestamping.txt +1 −1
  1412. Documentation/networking/tls-offload.rst +53 −20
  1413. Documentation/nfc/nfc-hci.txt +0 −290
  1414. Documentation/nfc/nfc-pn544.txt +0 −32
  1415. Documentation/ntb.txt +0 −236
  1416. Documentation/nvdimm/btt.txt +0 −273
  1417. Documentation/nvdimm/nvdimm.txt +0 −815
  1418. Documentation/nvdimm/security.txt +0 −141
  1419. Documentation/nvmem/nvmem.txt +0 −183
  1420. Documentation/pcmcia/devicetable.rst +37 −0
  1421. Documentation/pcmcia/devicetable.txt +0 −33
  1422. Documentation/pcmcia/driver-changes.rst +160 −0
  1423. Documentation/pcmcia/driver-changes.txt +0 −149
  1424. Documentation/pcmcia/driver.rst +30 −0
  1425. Documentation/pcmcia/driver.txt +0 −30
  1426. Documentation/pcmcia/index.rst +20 −0
  1427. Documentation/pcmcia/locking.rst +133 −0
  1428. Documentation/pcmcia/locking.txt +0 −118
  1429. Documentation/perf/arm-ccn.txt +0 −59
  1430. Documentation/perf/arm_dsu_pmu.txt +0 −28
  1431. Documentation/perf/hisi-pmu.txt +0 −53
  1432. Documentation/perf/qcom_l2_pmu.txt +0 −38
  1433. Documentation/perf/qcom_l3_pmu.txt +0 −25
  1434. Documentation/perf/thunderx2-pmu.txt +0 −41
  1435. Documentation/perf/xgene-pmu.txt +0 −48
  1436. Documentation/phy.txt +0 −197
  1437. Documentation/phy/samsung-usb2.txt +0 −135
  1438. Documentation/pi-futex.txt +1 −1
  1439. Documentation/platform/x86-laptop-drivers.txt +0 −18
  1440. Documentation/power/apm-acpi.rst +36 −0
  1441. Documentation/power/apm-acpi.txt +0 −32
  1442. Documentation/power/basic-pm-debugging.rst +269 −0
  1443. Documentation/power/basic-pm-debugging.txt +0 −254
  1444. Documentation/power/charger-manager.rst +205 −0
  1445. Documentation/power/charger-manager.txt +0 −200
  1446. Documentation/power/drivers-testing.rst +51 −0
  1447. Documentation/power/drivers-testing.txt +0 −46
  1448. Documentation/power/energy-model.rst +147 −0
  1449. Documentation/power/energy-model.txt +0 −144
  1450. Documentation/power/freezing-of-tasks.rst +244 −0
  1451. Documentation/power/freezing-of-tasks.txt +0 −231
  1452. Documentation/power/index.rst +46 −0
  1453. Documentation/power/interface.rst +79 −0
  1454. Documentation/power/interface.txt +0 −77
  1455. Documentation/power/opp.rst +379 −0
  1456. Documentation/power/opp.txt +0 −342
  1457. Documentation/power/pci.rst +1135 −0
  1458. Documentation/power/pci.txt +0 −1094
  1459. Documentation/power/pm_qos_interface.rst +227 −0
  1460. Documentation/power/pm_qos_interface.txt +0 −212
  1461. Documentation/power/power_supply_class.rst +288 −0
  1462. Documentation/power/power_supply_class.txt +0 −231
  1463. Documentation/power/powercap/powercap.rst +257 −0
  1464. Documentation/power/powercap/powercap.txt +0 −236
  1465. Documentation/power/regulator/consumer.rst +229 −0
  1466. Documentation/power/regulator/consumer.txt +0 −218
  1467. Documentation/power/regulator/design.rst +38 −0
  1468. Documentation/power/regulator/design.txt +0 −33
  1469. Documentation/power/regulator/machine.rst +97 −0
  1470. Documentation/power/regulator/machine.txt +0 −96
  1471. Documentation/power/regulator/overview.rst +178 −0
  1472. Documentation/power/regulator/overview.txt +0 −171
  1473. Documentation/power/regulator/regulator.rst +32 −0
  1474. Documentation/power/regulator/regulator.txt +0 −30
  1475. Documentation/power/runtime_pm.rst +940 −0
  1476. Documentation/power/runtime_pm.txt +0 −928
  1477. Documentation/power/s2ram.rst +87 −0
  1478. Documentation/power/s2ram.txt +0 −85
  1479. Documentation/power/suspend-and-cpuhotplug.rst +286 −0
  1480. Documentation/power/suspend-and-cpuhotplug.txt +0 −274
  1481. Documentation/power/suspend-and-interrupts.rst +137 −0
  1482. Documentation/power/suspend-and-interrupts.txt +0 −135
  1483. Documentation/power/swsusp-and-swap-files.rst +63 −0
  1484. Documentation/power/swsusp-and-swap-files.txt +0 −60
  1485. Documentation/power/swsusp-dmcrypt.rst +140 −0
  1486. Documentation/power/swsusp-dmcrypt.txt +0 −138
  1487. Documentation/power/swsusp.rst +501 −0
  1488. Documentation/power/swsusp.txt +0 −446
  1489. Documentation/power/tricks.rst +29 −0
  1490. Documentation/power/tricks.txt +0 −27
  1491. Documentation/power/userland-swsusp.rst +191 −0
  1492. Documentation/power/userland-swsusp.txt +0 −170
  1493. Documentation/power/video.rst +213 −0
  1494. Documentation/power/video.txt +0 −185
  1495. Documentation/powerpc/DAWR-POWER9.txt +0 −90
  1496. Documentation/powerpc/bootwrapper.rst +155 −0
  1497. Documentation/powerpc/bootwrapper.txt +0 −141
  1498. Documentation/powerpc/cpu_families.rst +222 −0
  1499. Documentation/powerpc/cpu_families.txt +0 −221
  1500. Documentation/powerpc/cpu_features.rst +60 −0
  1501. Documentation/powerpc/cpu_features.txt +0 −56
  1502. Documentation/powerpc/cxl.rst +467 −0
  1503. Documentation/powerpc/cxl.txt +0 −449
  1504. Documentation/powerpc/cxlflash.rst +433 −0
  1505. Documentation/powerpc/cxlflash.txt +0 −429
  1506. Documentation/powerpc/dawr-power9.rst +93 −0
  1507. Documentation/powerpc/dscr.rst +87 −0
  1508. Documentation/powerpc/dscr.txt +0 −83
  1509. Documentation/powerpc/eeh-pci-error-recovery.rst +336 −0
  1510. Documentation/powerpc/eeh-pci-error-recovery.txt +0 −334
  1511. Documentation/powerpc/firmware-assisted-dump.rst +301 −0
  1512. Documentation/powerpc/firmware-assisted-dump.txt +0 −292
  1513. Documentation/powerpc/hvcs.rst +581 −0
  1514. Documentation/powerpc/hvcs.txt +0 −567
  1515. Documentation/powerpc/index.rst +34 −0
  1516. Documentation/powerpc/isa-versions.rst +7 −6
  1517. Documentation/powerpc/mpc52xx.rst +43 −0
  1518. Documentation/powerpc/mpc52xx.txt +0 −39
  1519. Documentation/powerpc/pci_iov_resource_on_powernv.rst +312 −0
  1520. Documentation/powerpc/pci_iov_resource_on_powernv.txt +0 −301
  1521. Documentation/powerpc/pmu-ebb.rst +138 −0
  1522. Documentation/powerpc/pmu-ebb.txt +0 −137
  1523. Documentation/powerpc/ptrace.rst +156 −0
  1524. Documentation/powerpc/ptrace.txt +0 −151
  1525. Documentation/powerpc/qe_firmware.rst +296 −0
  1526. Documentation/powerpc/qe_firmware.txt +0 −295
  1527. Documentation/powerpc/syscall64-abi.rst +110 −0
  1528. Documentation/powerpc/syscall64-abi.txt +0 −105
  1529. Documentation/powerpc/transactional_memory.rst +247 −0
  1530. Documentation/powerpc/transactional_memory.txt +0 −244
  1531. Documentation/powerpc/vcpudispatch_stats.txt +68 −0
  1532. Documentation/pps/pps.txt +0 −239
  1533. Documentation/process/4.Coding.rst +1 −1
  1534. Documentation/process/changes.rst +4 −18
  1535. Documentation/process/coding-style.rst +1 −1
  1536. Documentation/process/conf.py +0 −10
  1537. Documentation/process/deprecated.rst +14 −0
  1538. Documentation/process/maintainer-pgp-guide.rst +17 −14
  1539. Documentation/process/submit-checklist.rst +2 −2
  1540. Documentation/process/submitting-drivers.rst +1 −1
  1541. Documentation/pti/pti_intel_mid.txt +0 −99
  1542. Documentation/ptp/ptp.txt +0 −86
  1543. Documentation/pwm.txt +0 −158
  1544. Documentation/rapidio/mport_cdev.txt +0 −107
  1545. Documentation/rapidio/rapidio.txt +0 −351
  1546. Documentation/rapidio/rio_cm.txt +0 −119
  1547. Documentation/rapidio/sysfs.txt +0 −3
  1548. Documentation/rapidio/tsi721.txt +0 −97
  1549. Documentation/rbtree.txt +3 −3
  1550. Documentation/remoteproc.txt +9 −5
  1551. Documentation/riscv/boot-image-header.txt +50 −0
  1552. Documentation/riscv/index.rst +15 −0
  1553. Documentation/riscv/pmu.rst +255 −0
  1554. Documentation/riscv/pmu.txt +0 −249
  1555. Documentation/s390/3270.rst +298 −0
  1556. Documentation/s390/3270.txt +0 −271
  1557. Documentation/s390/CommonIO +0 −125
  1558. Documentation/s390/DASD +0 −73
  1559. Documentation/s390/Debugging390.txt +0 −2142
  1560. Documentation/s390/cds.rst +530 −0
  1561. Documentation/s390/cds.txt +0 −472
  1562. Documentation/s390/common_io.rst +140 −0
  1563. Documentation/s390/dasd.rst +84 −0
  1564. Documentation/s390/debugging390.rst +2613 −0
  1565. Documentation/s390/driver-model.rst +328 −0
  1566. Documentation/s390/driver-model.txt +0 −287
  1567. Documentation/s390/index.rst +28 −0
  1568. Documentation/s390/monreader.rst +212 −0
  1569. Documentation/s390/monreader.txt +0 −197
  1570. Documentation/s390/qeth.rst +64 −0
  1571. Documentation/s390/qeth.txt +0 −50
  1572. Documentation/s390/s390dbf.rst +487 −0
  1573. Documentation/s390/s390dbf.txt +0 −667
  1574. Documentation/s390/text_files.rst +11 −0
  1575. Documentation/s390/vfio-ap.rst +866 −0
  1576. Documentation/s390/vfio-ap.txt +0 −837
  1577. Documentation/s390/vfio-ccw.rst +351 −0
  1578. Documentation/s390/vfio-ccw.txt +0 −300
  1579. Documentation/s390/zfcpdump.rst +50 −0
  1580. Documentation/s390/zfcpdump.txt +0 −48
  1581. Documentation/scheduler/completion.rst +293 −0
  1582. Documentation/scheduler/completion.txt +0 −291
  1583. Documentation/scheduler/index.rst +27 −0
  1584. Documentation/scheduler/sched-arch.rst +76 −0
  1585. Documentation/scheduler/sched-arch.txt +0 −74
  1586. Documentation/scheduler/sched-bwc.rst +128 −0
  1587. Documentation/scheduler/sched-bwc.txt +0 −122
  1588. Documentation/scheduler/sched-deadline.rst +888 −0
  1589. Documentation/scheduler/sched-deadline.txt +0 −871
  1590. Documentation/scheduler/sched-design-CFS.rst +249 −0
  1591. Documentation/scheduler/sched-design-CFS.txt +0 −242
  1592. Documentation/scheduler/sched-domains.rst +83 −0
  1593. Documentation/scheduler/sched-domains.txt +0 −77
  1594. Documentation/scheduler/sched-energy.rst +430 −0
.gitignore+4−0
@@ -30,6 +30,7 @@ · 29 unmodified lines
3030 *.lz4
3131 *.lzma
3232 *.lzo
33+*.mod
3334 *.mod.c
3435 *.o
3536 *.o.*
@@ -141,3 +142,6 @@ x509.genkey · 105 unmodified lines
141142
142143 # Kdevelop4
143144 *.kdev4
145+
146+# Clang's compilation database file
147+/compile_commands.json
.mailmap+5−0
@@ -81,6 +81,7 @@ Greg Kroah-Hartman <greg@echidna.(none)> · 80 unmodified lines
8181 Greg Kroah-Hartman <gregkh@suse.de>
8282 Greg Kroah-Hartman <greg@kroah.com>
8383 Gregory CLEMENT <gregory.clement@bootlin.com> <gregory.clement@free-electrons.com>
84+Hanjun Guo <guohanjun@huawei.com> <hanjun.guo@linaro.org>
8485 Henk Vergonet <Henk.Vergonet@gmail.com>
8586 Henrik Kretzschmar <henne@nachtwindheim.de>
8687 Henrik Rydberg <rydberg@bitmath.org>
@@ -97,6 +98,7 @@ Jason Gunthorpe <jgg@ziepe.ca> <jgunthorpe@obsidianresearch.com> · 10 unmodified lines
9798 Javi Merino <javi.merino@kernel.org> <javi.merino@arm.com>
9899 <javier@osg.samsung.com> <javier.martinez@collabora.co.uk>
99100 Jean Tourrilhes <jt@hpl.hp.com>
101+<jean-philippe@linaro.org> <jean-philippe.brucker@arm.com>
100102 Jeff Garzik <jgarzik@pretzel.yyz.us>
101103 Jeff Layton <jlayton@kernel.org> <jlayton@redhat.com>
102104 Jeff Layton <jlayton@kernel.org> <jlayton@poochiereds.net>
@@ -115,6 +117,7 @@ John Stultz <johnstul@us.ibm.com> · 12 unmodified lines
115117 Juha Yrjola <at solidboot.com>
116118 Juha Yrjola <juha.yrjola@nokia.com>
117119 Juha Yrjola <juha.yrjola@solidboot.com>
120+Julien Thierry <julien.thierry.kdev@gmail.com> <julien.thierry@arm.com>
118121 Kay Sievers <kay.sievers@vrfy.org>
119122 Kenneth W Chen <kenneth.w.chen@intel.com>
120123 Konstantin Khlebnikov <koct9i@gmail.com> <k.khlebnikov@samsung.com>
@@ -131,6 +134,7 @@ Linus Lüssing <linus.luessing@c0d3.blue> <linus.luessing@ascom.ch> · 10 unmodified lines
131134 Li Yang <leoyang.li@nxp.com> <leo@zh-kernel.org>
132135 Li Yang <leoyang.li@nxp.com> <leoli@freescale.com>
133136 Maciej W. Rozycki <macro@mips.com> <macro@imgtec.com>
137+Marc Zyngier <maz@kernel.org> <marc.zyngier@arm.com>
134138 Marcin Nowakowski <marcin.nowakowski@mips.com> <marcin.nowakowski@imgtec.com>
135139 Mark Brown <broonie@sirena.org.uk>
136140 Mark Yao <markyao0591@gmail.com> <mark.yao@rock-chips.com>
@@ -238,6 +242,7 @@ Vlad Dogaru <ddvlad@gmail.com> <vlad.dogaru@intel.com> · 101 unmodified lines
238242 Vladimir Davydov <vdavydov.dev@gmail.com> <vdavydov@virtuozzo.com>
239243 Vladimir Davydov <vdavydov.dev@gmail.com> <vdavydov@parallels.com>
240244 Takashi YOSHII <takashi.yoshii.zj@renesas.com>
245+Will Deacon <will@kernel.org> <will.deacon@arm.com>
241246 Yakir Yang <kuankuan.y@gmail.com> <ykk@rock-chips.com>
242247 Yusuke Goda <goda.yusuke@renesas.com>
243248 Gustavo Padovan <gustavo@las.ic.unicamp.br>
CREDITS+2−3
@@ -1770,7 +1770,6 @@ S: USA · 1769 unmodified lines
17701770
17711771 N: Dave Jones
17721772 E: davej@codemonkey.org.uk
1773−W: http://www.codemonkey.org.uk
17741773 D: Assorted VIA x86 support.
17751774 D: 2.5 AGPGART overhaul.
17761775 D: CPUFREQ maintenance.
@@ -1800,7 +1799,7 @@ S: 2300 Copenhagen S. · 23 unmodified lines
18001799 S: Denmark
18011800
18021801 N: Jozsef Kadlecsik
1803−E: kadlec@blackhole.kfki.hu
1802+E: kadlec@netfilter.org
18041803 P: 1024D/470DB964 4CB3 1A05 713E 9BF7 FAC5 5809 DD8C B7B1 470D B964
18051804 D: netfilter: TCP window tracking code
18061805 D: netfilter: raw table
@@ -3120,7 +3119,7 @@ S: France · 1313 unmodified lines
31203119 N: Rik van Riel
31213120 E: riel@redhat.com
31223121 W: http://www.surriel.com/
3123−D: Linux-MM site, Documentation/sysctl/*, swap/mm readaround
3122+D: Linux-MM site, Documentation/admin-guide/sysctl/*, swap/mm readaround
31243123 D: kswapd fixes, random kernel hacker, rmap VM,
31253124 D: nl.linux.org administrator, minor scheduler additions
31263125 S: Red Hat Boston
Documentation/ABI/obsolete/sysfs-driver-hid-roccat-pyra+1−1
@@ -5,7 +5,7 @@ Description: It is possible to switch the cpi setting of the mouse with the · 4 unmodified lines
55 press of a button.
66 When read, this file returns the raw number of the actual cpi
77 setting reported by the mouse. This number has to be further
8− processed to receive the real dpi value.
8+ processed to receive the real dpi value:
99
1010 VALUE DPI
1111 1 400
Documentation/ABI/obsolete/sysfs-gpio+1−1
@@ -11,7 +11,7 @@ Description: · 10 unmodified lines
1111 Kernel code may export it for complete or partial access.
1212
1313 GPIOs are identified as they are inside the kernel, using integers in
14− the range 0..INT_MAX. See Documentation/gpio for more information.
14+ the range 0..INT_MAX. See Documentation/admin-guide/gpio for more information.
1515
1616 /sys/class/gpio
1717 /export ... asks the kernel to export a GPIO to userspace
Documentation/ABI/removed/sysfs-class-rfkill+1−1
@@ -1,6 +1,6 @@
11 rfkill - radio frequency (RF) connector kill switch support
22
3−For details to this subsystem look at Documentation/rfkill.txt.
3+For details to this subsystem look at Documentation/driver-api/rfkill.rst.
44
55 What: /sys/class/rfkill/rfkill[0-9]+/claim
66 Date: 09-Jul-2007
Documentation/ABI/stable/sysfs-class-infiniband+0−17
@@ -423,23 +423,6 @@ Description: · 422 unmodified lines
423423 (e.g. driver restart on the VM which owns the VF).
424424
425425
426−sysfs interface for NetEffect RNIC Low-Level iWARP driver (nes)
427−---------------------------------------------------------------
428−
429−What: /sys/class/infiniband/nesX/hw_rev
430−What: /sys/class/infiniband/nesX/hca_type
431−What: /sys/class/infiniband/nesX/board_id
432−Date: Feb, 2008
433−KernelVersion: v2.6.25
434−Contact: linux-rdma@vger.kernel.org
435−Description:
436− hw_rev: (RO) Hardware revision number
437−
438− hca_type: (RO) Host Channel Adapter type (NEX020)
439−
440− board_id: (RO) Manufacturing board id
441−
442−
443426 sysfs interface for Chelsio T4/T5 RDMA driver (cxgb4)
444427 -----------------------------------------------------
445428
Documentation/ABI/stable/sysfs-class-rfkill+1−1
@@ -1,6 +1,6 @@
11 rfkill - radio frequency (RF) connector kill switch support
22
3−For details to this subsystem look at Documentation/rfkill.txt.
3+For details to this subsystem look at Documentation/driver-api/rfkill.rst.
44
55 For the deprecated /sys/class/rfkill/*/claim knobs of this interface look in
66 Documentation/ABI/removed/sysfs-class-rfkill.
Documentation/ABI/stable/sysfs-devices-node+1−1
@@ -61,7 +61,7 @@ Date: October 2002 · 60 unmodified lines
6161 Contact: Linux Memory Management list <linux-mm@kvack.org>
6262 Description:
6363 The node's hit/miss statistics, in units of pages.
64− See Documentation/numastat.txt
64+ See Documentation/admin-guide/numastat.rst
6565
6666 What: /sys/devices/system/node/nodeX/distance
6767 Date: October 2002
Documentation/ABI/stable/sysfs-driver-mlxreg-io+39−26
@@ -1,5 +1,4 @@
1−What: /sys/devices/platform/mlxplat/mlxreg-io/hwmon/hwmon*/
2− asic_health
1+What: /sys/devices/platform/mlxplat/mlxreg-io/hwmon/hwmon*/asic_health
32
43 Date: June 2018
54 KernelVersion: 4.19
@@ -9,9 +8,8 @@ Description: This file shows ASIC health status. The possible values are: · 3 unmodified lines
98
109 The files are read only.
1110
12−What: /sys/devices/platform/mlxplat/mlxreg-io/hwmon/hwmon*/
13− cpld1_version
14− cpld2_version
11+What: /sys/devices/platform/mlxplat/mlxreg-io/hwmon/hwmon*/cpld1_version
12+What: /sys/devices/platform/mlxplat/mlxreg-io/hwmon/hwmon*/cpld2_version
1513 Date: June 2018
1614 KernelVersion: 4.19
1715 Contact: Vadim Pasternak <vadimpmellanox.com>
@@ -20,8 +18,7 @@ Description: These files show with which CPLD versions have been burned · 2 unmodified lines
2018
2119 The files are read only.
2220
23−What: /sys/devices/platform/mlxplat/mlxreg-io/hwmon/hwmon*/
24− fan_dir
21+What: /sys/devices/platform/mlxplat/mlxreg-io/hwmon/hwmon*/fan_dir
2522
2623 Date: December 2018
2724 KernelVersion: 5.0
@@ -32,8 +29,7 @@ Description: This file shows the system fans direction: · 4 unmodified lines
3229
3330 The files are read only.
3431
35−What: /sys/devices/platform/mlxplat/mlxreg-io/hwmon/hwmon*/
36− jtag_enable
32+What: /sys/devices/platform/mlxplat/mlxreg-io/hwmon/hwmon*/jtag_enable
3733
3834 Date: November 2018
3935 KernelVersion: 5.0
@@ -43,8 +39,7 @@ Description: These files show with which CPLD versions have been burned · 3 unmodified lines
4339
4440 The files are read only.
4541
46−What: /sys/devices/platform/mlxplat/mlxreg-io/hwmon/hwmon*/
47− jtag_enable
42+What: /sys/devices/platform/mlxplat/mlxreg-io/hwmon/hwmon*/jtag_enable
4843
4944 Date: November 2018
5045 KernelVersion: 5.0
@@ -87,16 +82,15 @@ Description: These files allow asserting system power cycling, switching · 36 unmodified lines
8782
8883 The files are write only.
8984
90−What: /sys/devices/platform/mlxplat/mlxreg-io/hwmon/hwmon*/
91− reset_aux_pwr_or_ref
92− reset_asic_thermal
93− reset_hotswap_or_halt
94− reset_hotswap_or_wd
95− reset_fw_reset
96− reset_long_pb
97− reset_main_pwr_fail
98− reset_short_pb
99− reset_sw_reset
85+What: /sys/devices/platform/mlxplat/mlxreg-io/hwmon/hwmon*/reset_aux_pwr_or_ref
86+What: /sys/devices/platform/mlxplat/mlxreg-io/hwmon/hwmon*/reset_asic_thermal
87+What: /sys/devices/platform/mlxplat/mlxreg-io/hwmon/hwmon*/reset_hotswap_or_halt
88+What: /sys/devices/platform/mlxplat/mlxreg-io/hwmon/hwmon*/reset_hotswap_or_wd
89+What: /sys/devices/platform/mlxplat/mlxreg-io/hwmon/hwmon*/reset_fw_reset
90+What: /sys/devices/platform/mlxplat/mlxreg-io/hwmon/hwmon*/reset_long_pb
91+What: /sys/devices/platform/mlxplat/mlxreg-io/hwmon/hwmon*/reset_main_pwr_fail
92+What: /sys/devices/platform/mlxplat/mlxreg-io/hwmon/hwmon*/reset_short_pb
93+What: /sys/devices/platform/mlxplat/mlxreg-io/hwmon/hwmon*/reset_sw_reset
10094 Date: June 2018
10195 KernelVersion: 4.19
10296 Contact: Vadim Pasternak <vadimpmellanox.com>
@@ -110,11 +104,10 @@ Description: These files show the system reset cause, as following: power · 7 unmodified lines
110104
111105 The files are read only.
112106
113−What: /sys/devices/platform/mlxplat/mlxreg-io/hwmon/hwmon*/
114− reset_comex_pwr_fail
115− reset_from_comex
116− reset_system
117− reset_voltmon_upgrade_fail
107+What: /sys/devices/platform/mlxplat/mlxreg-io/hwmon/hwmon*/reset_comex_pwr_fail
108+What: /sys/devices/platform/mlxplat/mlxreg-io/hwmon/hwmon*/reset_from_comex
109+What: /sys/devices/platform/mlxplat/mlxreg-io/hwmon/hwmon*/reset_system
110+What: /sys/devices/platform/mlxplat/mlxreg-io/hwmon/hwmon*/reset_voltmon_upgrade_fail
118111
119112 Date: November 2018
120113 KernelVersion: 5.0
@@ -127,3 +120,23 @@ Description: These files show the system reset cause, as following: ComEx · 6 unmodified lines
127120 the last reset cause.
128121
129122 The files are read only.
123+
124+Date: June 2019
125+KernelVersion: 5.3
126+Contact: Vadim Pasternak <vadimpmellanox.com>
127+Description: These files show the system reset cause, as following:
128+ COMEX thermal shutdown; wathchdog power off or reset was derived
129+ by one of the next components: COMEX, switch board or by Small Form
130+ Factor mezzanine, reset requested from ASIC, reset cuased by BIOS
131+ reload. Value 1 in file means this is reset cause, 0 - otherwise.
132+ Only one of the above causes could be 1 at the same time, representing
133+ only last reset cause.
134+
135+ The files are read only.
136+
137+What: /sys/devices/platform/mlxplat/mlxreg-io/hwmon/hwmon*/reset_comex_thermal
138+What: /sys/devices/platform/mlxplat/mlxreg-io/hwmon/hwmon*/reset_comex_wd
139+What: /sys/devices/platform/mlxplat/mlxreg-io/hwmon/hwmon*/reset_from_asic
140+What: /sys/devices/platform/mlxplat/mlxreg-io/hwmon/hwmon*/reset_reload_bios
141+What: /sys/devices/platform/mlxplat/mlxreg-io/hwmon/hwmon*/reset_sff_wd
142+What: /sys/devices/platform/mlxplat/mlxreg-io/hwmon/hwmon*/reset_swb_wd
Documentation/ABI/testing/debugfs-cec-error-inj+1−1
@@ -1,6 +1,6 @@
11 What: /sys/kernel/debug/cec/*/error-inj
22 Date: March 2018
3−Contact: Hans Verkuil <hans.verkuil@cisco.com>
3+Contact: Hans Verkuil <hverkuil-cisco@xs4all.nl>
44 Description:
55
66 The CEC Framework allows for CEC error injection commands through
Documentation/ABI/testing/debugfs-cros-ec+56−0
@@ -0,0 +1,56 @@
1+What: /sys/kernel/debug/<cros-ec-device>/console_log
2+Date: September 2017
3+KernelVersion: 4.13
4+Description:
5+ If the EC supports the CONSOLE_READ command type, this file
6+ can be used to grab the EC logs. The kernel polls for the log
7+ and keeps its own buffer but userspace should grab this and
8+ write it out to some logs.
9+
10+What: /sys/kernel/debug/<cros-ec-device>/panicinfo
11+Date: September 2017
12+KernelVersion: 4.13
13+Description:
14+ This file dumps the EC panic information from the previous
15+ reboot. This file will only exist if the PANIC_INFO command
16+ type is supported by the EC.
17+
18+What: /sys/kernel/debug/<cros-ec-device>/pdinfo
19+Date: June 2018
20+KernelVersion: 4.17
21+Description:
22+ This file provides the port role, muxes and power debug
23+ information for all the USB PD/type-C ports available. If
24+ the are no ports available, this file will be just an empty
25+ file.
26+
27+What: /sys/kernel/debug/<cros-ec-device>/uptime
28+Date: June 2019
29+KernelVersion: 5.3
30+Description:
31+ A u32 providing the time since EC booted in ms. This is
32+ is used for synchronizing the AP host time with the EC
33+ log. An error is returned if the command is not supported
34+ by the EC or there is a communication problem.
35+
36+What: /sys/kernel/debug/<cros-ec-device>/last_resume_result
37+Date: June 2019
38+KernelVersion: 5.3
39+Description:
40+ Some ECs have a feature where they will track transitions to
41+ the (Intel) processor's SLP_S0 line, in order to detect cases
42+ where a system failed to go into S0ix. When the system resumes,
43+ an EC with this feature will return a summary of SLP_S0
44+ transitions that occurred. The last_resume_result file returns
45+ the most recent response from the AP's resume message to the EC.
46+
47+ The bottom 31 bits contain a count of the number of SLP_S0
48+ transitions that occurred since the suspend message was
49+ received. Bit 31 is set if the EC attempted to wake the
50+ system due to a timeout when watching for SLP_S0 transitions.
51+ Callers can use this to detect a wake from the EC due to
52+ S0ix timeouts. The result will be zero if no suspend
53+ transitions have been attempted, or the EC does not support
54+ this feature.
55+
56+ Output will be in the format: "0x%08x\n".
Documentation/ABI/testing/debugfs-driver-habanalabs+15−3
@@ -3,7 +3,10 @@ Date: Jan 2019 · 2 unmodified lines
33 KernelVersion: 5.1
44 Contact: oded.gabbay@gmail.com
55 Description: Sets the device address to be used for read or write through
6− PCI bar. The acceptable value is a string that starts with "0x"
6+ PCI bar, or the device VA of a host mapped memory to be read or
7+ written directly from the host. The latter option is allowed
8+ only when the IOMMU is disabled.
9+ The acceptable value is a string that starts with "0x"
710
811 What: /sys/kernel/debug/habanalabs/hl<n>/command_buffers
912 Date: Jan 2019
@@ -33,10 +36,12 @@ Contact: oded.gabbay@gmail.com · 23 unmodified lines
3336 Description: Allows the root user to read or write directly through the
3437 device's PCI bar. Writing to this file generates a write
3538 transaction while reading from the file generates a read
36− transcation. This custom interface is needed (instead of using
39+ transaction. This custom interface is needed (instead of using
3740 the generic Linux user-space PCI mapping) because the DDR bar
3841 is very small compared to the DDR memory and only the driver can
39− move the bar before and after the transaction
42+ move the bar before and after the transaction.
43+ If the IOMMU is disabled, it also allows the root user to read
44+ or write from the host a device VA of a host mapped memory
4045
4146 What: /sys/kernel/debug/habanalabs/hl<n>/device
4247 Date: Jan 2019
@@ -46,6 +51,13 @@ Description: Enables the root user to set the device to specific state. · 3 unmodified lines
4651 Valid values are "disable", "enable", "suspend", "resume".
4752 User can read this property to see the valid values
4853
54+What: /sys/kernel/debug/habanalabs/hl<n>/engines
55+Date: Jul 2019
56+KernelVersion: 5.3
57+Contact: oded.gabbay@gmail.com
58+Description: Displays the status registers values of the device engines and
59+ their derived idle status
60+
4961 What: /sys/kernel/debug/habanalabs/hl<n>/i2c_addr
5062 Date: Jan 2019
5163 KernelVersion: 5.1
Documentation/ABI/testing/debugfs-wilco-ec+7−9
@@ -23,11 +23,9 @@ Description: · 22 unmodified lines
2323
2424 For writing, bytes 0-1 indicate the message type, one of enum
2525 wilco_ec_msg_type. Byte 2+ consist of the data passed in the
26− request, starting at MBOX[0]
27−
28− At least three bytes are required for writing, two for the type
29− and at least a single byte of data. Only the first
30− EC_MAILBOX_DATA_SIZE bytes of MBOX will be used.
26+ request, starting at MBOX[0]. At least three bytes are required
27+ for writing, two for the type and at least a single byte of
28+ data.
3129
3230 Example:
3331 // Request EC info type 3 (EC firmware build date)
@@ -40,7 +38,7 @@ Description: · 6 unmodified lines
4038 $ cat /sys/kernel/debug/wilco_ec/raw
4139 00 00 31 32 2f 32 31 2f 31 38 00 38 00 01 00 2f 00 ..12/21/18.8...
4240
43− Note that the first 32 bytes of the received MBOX[] will be
44− printed, even if some of the data is junk. It is up to you to
45− know how many of the first bytes of data are the actual
46− response.
41+ Note that the first 16 bytes of the received MBOX[] will be
42+ printed, even if some of the data is junk, and skipping bytes
43+ 17 to 32. It is up to you to know how many of the first bytes of
44+ data are the actual response.
Documentation/ABI/testing/ima_policy+4−2
@@ -24,11 +24,11 @@ Description: · 23 unmodified lines
2424 [euid=] [fowner=] [fsname=]]
2525 lsm: [[subj_user=] [subj_role=] [subj_type=]
2626 [obj_user=] [obj_role=] [obj_type=]]
27− option: [[appraise_type=]] [permit_directio]
28−
27+ option: [[appraise_type=]] [template=] [permit_directio]
2928 base: func:= [BPRM_CHECK][MMAP_CHECK][CREDS_CHECK][FILE_CHECK][MODULE_CHECK]
3029 [FIRMWARE_CHECK]
3130 [KEXEC_KERNEL_CHECK] [KEXEC_INITRAMFS_CHECK]
31+ [KEXEC_CMDLINE]
3232 mask:= [[^]MAY_READ] [[^]MAY_WRITE] [[^]MAY_APPEND]
3333 [[^]MAY_EXEC]
3434 fsmagic:= hex value
@@ -38,6 +38,8 @@ Description: · 3 unmodified lines
3838 fowner:= decimal value
3939 lsm: are LSM specific
4040 option: appraise_type:= [imasig]
41+ template:= name of a defined IMA template type
42+ (eg, ima-ng). Only valid when action is "measure".
4143 pcr:= decimal value
4244
4345 default policy:
Documentation/ABI/testing/procfs-diskstats+1−1
@@ -29,4 +29,4 @@ Description: · 28 unmodified lines
2929 17 - sectors discarded
3030 18 - time spent discarding
3131
32− For more details refer to Documentation/iostats.txt
32+ For more details refer to Documentation/admin-guide/iostats.rst
Documentation/ABI/testing/procfs-smaps_rollup+12−2
@@ -3,18 +3,28 @@ Date: August 2017 · 2 unmodified lines
33 Contact: Daniel Colascione <dancol@google.com>
44 Description:
55 This file provides pre-summed memory information for a
6− process. The format is identical to /proc/pid/smaps,
6+ process. The format is almost identical to /proc/pid/smaps,
77 except instead of an entry for each VMA in a process,
88 smaps_rollup has a single entry (tagged "[rollup]")
99 for which each field is the sum of the corresponding
1010 fields from all the maps in /proc/pid/smaps.
11− For more details, see the procfs man page.
11+ Additionally, the fields Pss_Anon, Pss_File and Pss_Shmem
12+ are not present in /proc/pid/smaps. These fields represent
13+ the sum of the Pss field of each type (anon, file, shmem).
14+ For more details, see Documentation/filesystems/proc.txt
15+ and the procfs man page.
1216
1317 Typical output looks like this:
1418
1519 00100000-ff709000 ---p 00000000 00:00 0 [rollup]
20+ Size: 1192 kB
21+ KernelPageSize: 4 kB
22+ MMUPageSize: 4 kB
1623 Rss: 884 kB
1724 Pss: 385 kB
25+ Pss_Anon: 301 kB
26+ Pss_File: 80 kB
27+ Pss_Shmem: 4 kB
1828 Shared_Clean: 696 kB
1929 Shared_Dirty: 0 kB
2030 Private_Clean: 120 kB
Documentation/ABI/testing/pstore+2−2
@@ -1,6 +1,6 @@
1−Where: /sys/fs/pstore/... (or /dev/pstore/...)
1+What: /sys/fs/pstore/... (or /dev/pstore/...)
22 Date: March 2011
3−Kernel Version: 2.6.39
3+KernelVersion: 2.6.39
44 Contact: tony.luck@intel.com
55 Description: Generic interface to platform dependent persistent storage.
66
Documentation/ABI/testing/sysfs-block+1−1
@@ -15,7 +15,7 @@ Description: · 14 unmodified lines
1515 9 - I/Os currently in progress
1616 10 - time spent doing I/Os (ms)
1717 11 - weighted time spent doing I/Os (ms)
18− For more details refer Documentation/iostats.txt
18+ For more details refer Documentation/admin-guide/iostats.rst
1919
2020
2121 What: /sys/block/<disk>/<part>/stat
Documentation/ABI/testing/sysfs-block-device+1−1
@@ -45,7 +45,7 @@ Description: · 44 unmodified lines
4545 - Values below -2 are rejected with -EINVAL
4646
4747 For more information, see
48− Documentation/laptops/disk-shock-protection.txt
48+ Documentation/admin-guide/laptops/disk-shock-protection.rst
4949
5050
5151 What: /sys/block/*/device/ncq_prio_enable
Documentation/ABI/testing/sysfs-bus-css+23−0
@@ -33,3 +33,26 @@ Description: Contains the PIM/PAM/POM values, as reported by the · 32 unmodified lines
3333 in sync with the values current in the channel subsystem).
3434 Note: This is an I/O-subchannel specific attribute.
3535 Users: s390-tools, HAL
36+
37+What: /sys/bus/css/devices/.../driver_override
38+Date: June 2019
39+Contact: Cornelia Huck <cohuck@redhat.com>
40+ linux-s390@vger.kernel.org
41+Description: This file allows the driver for a device to be specified. When
42+ specified, only a driver with a name matching the value written
43+ to driver_override will have an opportunity to bind to the
44+ device. The override is specified by writing a string to the
45+ driver_override file (echo vfio-ccw > driver_override) and
46+ may be cleared with an empty string (echo > driver_override).
47+ This returns the device to standard matching rules binding.
48+ Writing to driver_override does not automatically unbind the
49+ device from its current driver or make any attempt to
50+ automatically load the specified driver. If no driver with a
51+ matching name is currently loaded in the kernel, the device
52+ will not bind to any driver. This also allows devices to
53+ opt-out of driver binding using a driver_override name such as
54+ "none". Only a single driver may be specified in the override,
55+ there is no support for parsing delimiters.
56+ Note that unlike the mechanism of the same name for pci, this
57+ file does not allow to override basic matching rules. I.e.,
58+ the driver must still match the subchannel type of the device.
Documentation/ABI/testing/sysfs-bus-event_source-devices-format+2−2
@@ -1,6 +1,6 @@
1−Where: /sys/bus/event_source/devices/<dev>/format
1+What: /sys/bus/event_source/devices/<dev>/format
22 Date: January 2012
3−Kernel Version: 3.3
3+KernelVersion: 3.3
44 Contact: Jiri Olsa <jolsa@redhat.com>
55 Description:
66 Attribute group to describe the magic bits that go into
Documentation/ABI/testing/sysfs-bus-i2c-devices-hm6352+6−6
@@ -1,20 +1,20 @@
1−Where: /sys/bus/i2c/devices/.../heading0_input
1+What: /sys/bus/i2c/devices/.../heading0_input
22 Date: April 2010
3−Kernel Version: 2.6.36?
3+KernelVersion: 2.6.36?
44 Contact: alan.cox@intel.com
55 Description: Reports the current heading from the compass as a floating
66 point value in degrees.
77
8−Where: /sys/bus/i2c/devices/.../power_state
8+What: /sys/bus/i2c/devices/.../power_state
99 Date: April 2010
10−Kernel Version: 2.6.36?
10+KernelVersion: 2.6.36?
1111 Contact: alan.cox@intel.com
1212 Description: Sets the power state of the device. 0 sets the device into
1313 sleep mode, 1 wakes it up.
1414
15−Where: /sys/bus/i2c/devices/.../calibration
15+What: /sys/bus/i2c/devices/.../calibration
1616 Date: April 2010
17−Kernel Version: 2.6.36?
17+KernelVersion: 2.6.36?
1818 Contact: alan.cox@intel.com
1919 Description: Sets the calibration on or off (1 = on, 0 = off). See the
2020 chip data sheet.
Documentation/ABI/testing/sysfs-bus-iio+5−2
@@ -61,8 +61,11 @@ What: /sys/bus/iio/devices/triggerX/sampling_frequency_available · 60 unmodified lines
6161 KernelVersion: 2.6.35
6262 Contact: linux-iio@vger.kernel.org
6363 Description:
64− When the internal sampling clock can only take a small
65− discrete set of values, this file lists those available.
64+ When the internal sampling clock can only take a specific set of
65+ frequencies, we can specify the available values with:
66+ - a small discrete set of values like "0 2 4 6 8"
67+ - a range with minimum, step and maximum frequencies like
68+ "[min step max]"
6669
6770 What: /sys/bus/iio/devices/iio:deviceX/oversampling_ratio
6871 KernelVersion: 2.6.38
Documentation/ABI/testing/sysfs-bus-iio-cros-ec+5−5
@@ -18,11 +18,11 @@ Description: · 17 unmodified lines
1818 values are 'base' and 'lid'.
1919
2020 What: /sys/bus/iio/devices/iio:deviceX/id
21−Date: Septembre 2017
21+Date: September 2017
2222 KernelVersion: 4.14
2323 Contact: linux-iio@vger.kernel.org
2424 Description:
25− This attribute is exposed by the CrOS EC legacy accelerometer
26− driver and represents the sensor ID as exposed by the EC. This
27− ID is used by the Android sensor service hardware abstraction
28− layer (sensor HAL) through the Android container on ChromeOS.
25+ This attribute is exposed by the CrOS EC sensors driver and
26+ represents the sensor ID as exposed by the EC. This ID is used
27+ by the Android sensor service hardware abstraction layer (sensor
28+ HAL) through the Android container on ChromeOS.
Documentation/ABI/testing/sysfs-bus-iio-distance-srf08+2−2
@@ -1,4 +1,4 @@
1−What /sys/bus/iio/devices/iio:deviceX/sensor_sensitivity
1+What: /sys/bus/iio/devices/iio:deviceX/sensor_sensitivity
22 Date: January 2017
33 KernelVersion: 4.11
44 Contact: linux-iio@vger.kernel.org
@@ -6,7 +6,7 @@ Description: · 1 unmodified line
66 Show or set the gain boost of the amp, from 0-31 range.
77 default 31
88
9−What /sys/bus/iio/devices/iio:deviceX/sensor_max_range
9+What: /sys/bus/iio/devices/iio:deviceX/sensor_max_range
1010 Date: January 2017
1111 KernelVersion: 4.11
1212 Contact: linux-iio@vger.kernel.org
Documentation/ABI/testing/sysfs-bus-iio-frequency-adf4371+44−0
@@ -0,0 +1,44 @@
1+What: /sys/bus/iio/devices/iio:deviceX/out_altvoltageY_frequency
2+KernelVersion:
3+Contact: linux-iio@vger.kernel.org
4+Description:
5+ Stores the PLL frequency in Hz for channel Y.
6+ Reading returns the actual frequency in Hz.
7+ The ADF4371 has an integrated VCO with fundamendal output
8+ frequency ranging from 4000000000 Hz 8000000000 Hz.
9+
10+ out_altvoltage0_frequency:
11+ A divide by 1, 2, 4, 8, 16, 32 or circuit generates
12+ frequencies from 62500000 Hz to 8000000000 Hz.
13+ out_altvoltage1_frequency:
14+ This channel duplicates the channel 0 frequency
15+ out_altvoltage2_frequency:
16+ A frequency doubler generates frequencies from
17+ 8000000000 Hz to 16000000000 Hz.
18+ out_altvoltage3_frequency:
19+ A frequency quadrupler generates frequencies from
20+ 16000000000 Hz to 32000000000 Hz.
21+
22+ Note: writes to one of the channels will affect the frequency of
23+ all the other channels, since it involves changing the VCO
24+ fundamental output frequency.
25+
26+What: /sys/bus/iio/devices/iio:deviceX/out_altvoltageY_name
27+KernelVersion:
28+Contact: linux-iio@vger.kernel.org
29+Description:
30+ Reading returns the datasheet name for channel Y:
31+
32+ out_altvoltage0_name: RF8x
33+ out_altvoltage1_name: RFAUX8x
34+ out_altvoltage2_name: RF16x
35+ out_altvoltage3_name: RF32x
36+
37+What: /sys/bus/iio/devices/iio:deviceX/out_altvoltageY_powerdown
38+KernelVersion:
39+Contact: linux-iio@vger.kernel.org
40+Description:
41+ This attribute allows the user to power down the PLL and it's
42+ RFOut buffers.
43+ Writing 1 causes the specified channel to power down.
44+ Clearing returns to normal operation.
Documentation/ABI/testing/sysfs-bus-iio-proximity-as3935+2−2
@@ -1,4 +1,4 @@
1−What /sys/bus/iio/devices/iio:deviceX/in_proximity_input
1+What: /sys/bus/iio/devices/iio:deviceX/in_proximity_input
22 Date: March 2014
33 KernelVersion: 3.15
44 Contact: Matt Ranostay <matt.ranostay@konsulko.com>
@@ -6,7 +6,7 @@ Description: · 1 unmodified line
66 Get the current distance in meters of storm (1km steps)
77 1000-40000 = distance in meters
88
9−What /sys/bus/iio/devices/iio:deviceX/sensor_sensitivity
9+What: /sys/bus/iio/devices/iio:deviceX/sensor_sensitivity
1010 Date: March 2014
1111 KernelVersion: 3.15
1212 Contact: Matt Ranostay <matt.ranostay@konsulko.com>
Documentation/ABI/testing/sysfs-bus-pci-devices-aer_stats+12−12
@@ -9,9 +9,9 @@ errors may be "seen" / reported by the link partner and not the · 8 unmodified lines
99 problematic endpoint itself (which may report all counters as 0 as it never
1010 saw any problems).
1111
12−Where: /sys/bus/pci/devices/<dev>/aer_dev_correctable
12+What: /sys/bus/pci/devices/<dev>/aer_dev_correctable
1313 Date: July 2018
14−Kernel Version: 4.19.0
14+KernelVersion: 4.19.0
1515 Contact: linux-pci@vger.kernel.org, rajatja@google.com
1616 Description: List of correctable errors seen and reported by this
1717 PCI device using ERR_COR. Note that since multiple errors may
@@ -31,9 +31,9 @@ Header Log Overflow 0 · 13 unmodified lines
3131 TOTAL_ERR_COR 2
3232 -------------------------------------------------------------------------
3333
34−Where: /sys/bus/pci/devices/<dev>/aer_dev_fatal
34+What: /sys/bus/pci/devices/<dev>/aer_dev_fatal
3535 Date: July 2018
36−Kernel Version: 4.19.0
36+KernelVersion: 4.19.0
3737 Contact: linux-pci@vger.kernel.org, rajatja@google.com
3838 Description: List of uncorrectable fatal errors seen and reported by this
3939 PCI device using ERR_FATAL. Note that since multiple errors may
@@ -62,9 +62,9 @@ TLP Prefix Blocked Error 0 · 22 unmodified lines
6262 TOTAL_ERR_FATAL 0
6363 -------------------------------------------------------------------------
6464
65−Where: /sys/bus/pci/devices/<dev>/aer_dev_nonfatal
65+What: /sys/bus/pci/devices/<dev>/aer_dev_nonfatal
6666 Date: July 2018
67−Kernel Version: 4.19.0
67+KernelVersion: 4.19.0
6868 Contact: linux-pci@vger.kernel.org, rajatja@google.com
6969 Description: List of uncorrectable nonfatal errors seen and reported by this
7070 PCI device using ERR_NONFATAL. Note that since multiple errors
@@ -103,20 +103,20 @@ collectors) that are AER capable. These indicate the number of error messages as · 32 unmodified lines
103103 device, so these counters include them and are thus cumulative of all the error
104104 messages on the PCI hierarchy originating at that root port.
105105
106−Where: /sys/bus/pci/devices/<dev>/aer_stats/aer_rootport_total_err_cor
106+What: /sys/bus/pci/devices/<dev>/aer_stats/aer_rootport_total_err_cor
107107 Date: July 2018
108−Kernel Version: 4.19.0
108+KernelVersion: 4.19.0
109109 Contact: linux-pci@vger.kernel.org, rajatja@google.com
110110 Description: Total number of ERR_COR messages reported to rootport.
111111
112−Where: /sys/bus/pci/devices/<dev>/aer_stats/aer_rootport_total_err_fatal
112+What: /sys/bus/pci/devices/<dev>/aer_stats/aer_rootport_total_err_fatal
113113 Date: July 2018
114−Kernel Version: 4.19.0
114+KernelVersion: 4.19.0
115115 Contact: linux-pci@vger.kernel.org, rajatja@google.com
116116 Description: Total number of ERR_FATAL messages reported to rootport.
117117
118−Where: /sys/bus/pci/devices/<dev>/aer_stats/aer_rootport_total_err_nonfatal
118+What: /sys/bus/pci/devices/<dev>/aer_stats/aer_rootport_total_err_nonfatal
119119 Date: July 2018
120−Kernel Version: 4.19.0
120+KernelVersion: 4.19.0
121121 Contact: linux-pci@vger.kernel.org, rajatja@google.com
122122 Description: Total number of ERR_NONFATAL messages reported to rootport.
Documentation/ABI/testing/sysfs-bus-pci-devices-cciss+22−22
@@ -1,68 +1,68 @@
1−Where: /sys/bus/pci/devices/<dev>/ccissX/cXdY/model
1+What: /sys/bus/pci/devices/<dev>/ccissX/cXdY/model
22 Date: March 2009
3−Kernel Version: 2.6.30
3+KernelVersion: 2.6.30
44 Contact: iss_storagedev@hp.com
55 Description: Displays the SCSI INQUIRY page 0 model for logical drive
66 Y of controller X.
77
8−Where: /sys/bus/pci/devices/<dev>/ccissX/cXdY/rev
8+What: /sys/bus/pci/devices/<dev>/ccissX/cXdY/rev
99 Date: March 2009
10−Kernel Version: 2.6.30
10+KernelVersion: 2.6.30
1111 Contact: iss_storagedev@hp.com
1212 Description: Displays the SCSI INQUIRY page 0 revision for logical
1313 drive Y of controller X.
1414
15−Where: /sys/bus/pci/devices/<dev>/ccissX/cXdY/unique_id
15+What: /sys/bus/pci/devices/<dev>/ccissX/cXdY/unique_id
1616 Date: March 2009
17−Kernel Version: 2.6.30
17+KernelVersion: 2.6.30
1818 Contact: iss_storagedev@hp.com
1919 Description: Displays the SCSI INQUIRY page 83 serial number for logical
2020 drive Y of controller X.
2121
22−Where: /sys/bus/pci/devices/<dev>/ccissX/cXdY/vendor
22+What: /sys/bus/pci/devices/<dev>/ccissX/cXdY/vendor
2323 Date: March 2009
24−Kernel Version: 2.6.30
24+KernelVersion: 2.6.30
2525 Contact: iss_storagedev@hp.com
2626 Description: Displays the SCSI INQUIRY page 0 vendor for logical drive
2727 Y of controller X.
2828
29−Where: /sys/bus/pci/devices/<dev>/ccissX/cXdY/block:cciss!cXdY
29+What: /sys/bus/pci/devices/<dev>/ccissX/cXdY/block:cciss!cXdY
3030 Date: March 2009
31−Kernel Version: 2.6.30
31+KernelVersion: 2.6.30
3232 Contact: iss_storagedev@hp.com
3333 Description: A symbolic link to /sys/block/cciss!cXdY
3434
35−Where: /sys/bus/pci/devices/<dev>/ccissX/rescan
35+What: /sys/bus/pci/devices/<dev>/ccissX/rescan
3636 Date: August 2009
37−Kernel Version: 2.6.31
37+KernelVersion: 2.6.31
3838 Contact: iss_storagedev@hp.com
3939 Description: Kicks of a rescan of the controller to discover logical
4040 drive topology changes.
4141
42−Where: /sys/bus/pci/devices/<dev>/ccissX/cXdY/lunid
42+What: /sys/bus/pci/devices/<dev>/ccissX/cXdY/lunid
4343 Date: August 2009
44−Kernel Version: 2.6.31
44+KernelVersion: 2.6.31
4545 Contact: iss_storagedev@hp.com
4646 Description: Displays the 8-byte LUN ID used to address logical
4747 drive Y of controller X.
4848
49−Where: /sys/bus/pci/devices/<dev>/ccissX/cXdY/raid_level
49+What: /sys/bus/pci/devices/<dev>/ccissX/cXdY/raid_level
5050 Date: August 2009
51−Kernel Version: 2.6.31
51+KernelVersion: 2.6.31
5252 Contact: iss_storagedev@hp.com
5353 Description: Displays the RAID level of logical drive Y of
5454 controller X.
5555
56−Where: /sys/bus/pci/devices/<dev>/ccissX/cXdY/usage_count
56+What: /sys/bus/pci/devices/<dev>/ccissX/cXdY/usage_count
5757 Date: August 2009
58−Kernel Version: 2.6.31
58+KernelVersion: 2.6.31
5959 Contact: iss_storagedev@hp.com
6060 Description: Displays the usage count (number of opens) of logical drive Y
6161 of controller X.
6262
63−Where: /sys/bus/pci/devices/<dev>/ccissX/resettable
63+What: /sys/bus/pci/devices/<dev>/ccissX/resettable
6464 Date: February 2011
65−Kernel Version: 2.6.38
65+KernelVersion: 2.6.38
6666 Contact: iss_storagedev@hp.com
6767 Description: Value of 1 indicates the controller can honor the reset_devices
6868 kernel parameter. Value of 0 indicates reset_devices cannot be
@@ -71,9 +71,9 @@ Description: Value of 1 indicates the controller can honor the reset_devices · 2 unmodified lines
7171 a dump device, as kdump requires resetting the device in order
7272 to work reliably.
7373
74−Where: /sys/bus/pci/devices/<dev>/ccissX/transport_mode
74+What: /sys/bus/pci/devices/<dev>/ccissX/transport_mode
7575 Date: July 2011
76−Kernel Version: 3.0
76+KernelVersion: 3.0
7777 Contact: iss_storagedev@hp.com
7878 Description: Value of "simple" indicates that the controller has been placed
7979 in "simple mode". Value of "performant" indicates that the
Documentation/ABI/testing/sysfs-bus-siox+11−11
@@ -1,6 +1,6 @@
11 What: /sys/bus/siox/devices/siox-X/active
22 KernelVersion: 4.16
3−Contact: Gavin Schenk <g.schenk@eckelmann.de>, Uwe Kleine-König <u.kleine-koenig@pengutronix.de>
3+Contact: Thorsten Scherer <t.scherer@eckelmann.de>, Uwe Kleine-König <u.kleine-koenig@pengutronix.de>
44 Description:
55 On reading represents the current state of the bus. If it
66 contains a "0" the bus is stopped and connected devices are
@@ -12,7 +12,7 @@ Description: · 5 unmodified lines
1212
1313 What: /sys/bus/siox/devices/siox-X/device_add
1414 KernelVersion: 4.16
15−Contact: Gavin Schenk <g.schenk@eckelmann.de>, Uwe Kleine-König <u.kleine-koenig@pengutronix.de>
15+Contact: Thorsten Scherer <t.scherer@eckelmann.de>, Uwe Kleine-König <u.kleine-koenig@pengutronix.de>
1616 Description:
1717 Write-only file. Write
1818
@@ -27,13 +27,13 @@ Description: · 8 unmodified lines
2727
2828 What: /sys/bus/siox/devices/siox-X/device_remove
2929 KernelVersion: 4.16
30−Contact: Gavin Schenk <g.schenk@eckelmann.de>, Uwe Kleine-König <u.kleine-koenig@pengutronix.de>
30+Contact: Thorsten Scherer <t.scherer@eckelmann.de>, Uwe Kleine-König <u.kleine-koenig@pengutronix.de>
3131 Description:
3232 Write-only file. A single write removes the last device in the siox chain.
3333
3434 What: /sys/bus/siox/devices/siox-X/poll_interval_ns
3535 KernelVersion: 4.16
36−Contact: Gavin Schenk <g.schenk@eckelmann.de>, Uwe Kleine-König <u.kleine-koenig@pengutronix.de>
36+Contact: Thorsten Scherer <t.scherer@eckelmann.de>, Uwe Kleine-König <u.kleine-koenig@pengutronix.de>
3737 Description:
3838 Defines the interval between two poll cycles in nano seconds.
3939 Note this is rounded to jiffies on writing. On reading the current value
@@ -41,33 +41,33 @@ Description: · 1 unmodified line
4141
4242 What: /sys/bus/siox/devices/siox-X-Y/connected
4343 KernelVersion: 4.16
44−Contact: Gavin Schenk <g.schenk@eckelmann.de>, Uwe Kleine-König <u.kleine-koenig@pengutronix.de>
44+Contact: Thorsten Scherer <t.scherer@eckelmann.de>, Uwe Kleine-König <u.kleine-koenig@pengutronix.de>
4545 Description:
4646 Read-only value. "0" means the Yth device on siox bus X isn't "connected" i.e.
4747 communication with it is not ensured. "1" signals a working connection.
4848
4949 What: /sys/bus/siox/devices/siox-X-Y/inbytes
5050 KernelVersion: 4.16
51−Contact: Gavin Schenk <g.schenk@eckelmann.de>, Uwe Kleine-König <u.kleine-koenig@pengutronix.de>
51+Contact: Thorsten Scherer <t.scherer@eckelmann.de>, Uwe Kleine-König <u.kleine-koenig@pengutronix.de>
5252 Description:
5353 Read-only value reporting the inbytes value provided to siox-X/device_add
5454
5555 What: /sys/bus/siox/devices/siox-X-Y/status_errors
5656 KernelVersion: 4.16
57−Contact: Gavin Schenk <g.schenk@eckelmann.de>, Uwe Kleine-König <u.kleine-koenig@pengutronix.de>
57+Contact: Thorsten Scherer <t.scherer@eckelmann.de>, Uwe Kleine-König <u.kleine-koenig@pengutronix.de>
5858 Description:
5959 Counts the number of time intervals when the read status byte doesn't yield the
6060 expected value.
6161
6262 What: /sys/bus/siox/devices/siox-X-Y/type
6363 KernelVersion: 4.16
64−Contact: Gavin Schenk <g.schenk@eckelmann.de>, Uwe Kleine-König <u.kleine-koenig@pengutronix.de>
64+Contact: Thorsten Scherer <t.scherer@eckelmann.de>, Uwe Kleine-König <u.kleine-koenig@pengutronix.de>
6565 Description:
6666 Read-only value reporting the type value provided to siox-X/device_add.
6767
6868 What: /sys/bus/siox/devices/siox-X-Y/watchdog
6969 KernelVersion: 4.16
70−Contact: Gavin Schenk <g.schenk@eckelmann.de>, Uwe Kleine-König <u.kleine-koenig@pengutronix.de>
70+Contact: Thorsten Scherer <t.scherer@eckelmann.de>, Uwe Kleine-König <u.kleine-koenig@pengutronix.de>
7171 Description:
7272 Read-only value reporting if the watchdog of the siox device is
7373 active. "0" means the watchdog is not active and the device is expected to
@@ -75,13 +75,13 @@ Description: · 1 unmodified line
7575
7676 What: /sys/bus/siox/devices/siox-X-Y/watchdog_errors
7777 KernelVersion: 4.16
78−Contact: Gavin Schenk <g.schenk@eckelmann.de>, Uwe Kleine-König <u.kleine-koenig@pengutronix.de>
78+Contact: Thorsten Scherer <t.scherer@eckelmann.de>, Uwe Kleine-König <u.kleine-koenig@pengutronix.de>
7979 Description:
8080 Read-only value reporting the number to time intervals when the
8181 watchdog was active.
8282
8383 What: /sys/bus/siox/devices/siox-X-Y/outbytes
8484 KernelVersion: 4.16
85−Contact: Gavin Schenk <g.schenk@eckelmann.de>, Uwe Kleine-König <u.kleine-koenig@pengutronix.de>
85+Contact: Thorsten Scherer <t.scherer@eckelmann.de>, Uwe Kleine-König <u.kleine-koenig@pengutronix.de>
8686 Description:
8787 Read-only value reporting the outbytes value provided to siox-X/device_add.
Documentation/ABI/testing/sysfs-bus-usb-devices-usbsevseg+11−11
@@ -1,14 +1,14 @@
1−Where: /sys/bus/usb/.../powered
1+What: /sys/bus/usb/.../powered
22 Date: August 2008
3−Kernel Version: 2.6.26
3+KernelVersion: 2.6.26
44 Contact: Harrison Metzger <harrisonmetz@gmail.com>
55 Description: Controls whether the device's display will powered.
66 A value of 0 is off and a non-zero value is on.
77
8−Where: /sys/bus/usb/.../mode_msb
9−Where: /sys/bus/usb/.../mode_lsb
8+What: /sys/bus/usb/.../mode_msb
9+What: /sys/bus/usb/.../mode_lsb
1010 Date: August 2008
11−Kernel Version: 2.6.26
11+KernelVersion: 2.6.26
1212 Contact: Harrison Metzger <harrisonmetz@gmail.com>
1313 Description: Controls the devices display mode.
1414 For a 6 character display the values are
@@ -16,24 +16,24 @@ Description: Controls the devices display mode. · 1 unmodified line
1616 for an 8 character display the values are
1717 MSB 0x08; LSB 0xFF.
1818
19−Where: /sys/bus/usb/.../textmode
19+What: /sys/bus/usb/.../textmode
2020 Date: August 2008
21−Kernel Version: 2.6.26
21+KernelVersion: 2.6.26
2222 Contact: Harrison Metzger <harrisonmetz@gmail.com>
2323 Description: Controls the way the device interprets its text buffer.
2424 raw: each character controls its segment manually
2525 hex: each character is between 0-15
2626 ascii: each character is between '0'-'9' and 'A'-'F'.
2727
28−Where: /sys/bus/usb/.../text
28+What: /sys/bus/usb/.../text
2929 Date: August 2008
30−Kernel Version: 2.6.26
30+KernelVersion: 2.6.26
3131 Contact: Harrison Metzger <harrisonmetz@gmail.com>
3232 Description: The text (or data) for the device to display
3333
34−Where: /sys/bus/usb/.../decimals
34+What: /sys/bus/usb/.../decimals
3535 Date: August 2008
36−Kernel Version: 2.6.26
36+KernelVersion: 2.6.26
3737 Contact: Harrison Metzger <harrisonmetz@gmail.com>
3838 Description: Controls the decimal places on the device.
3939 To set the nth decimal place, give this field
Documentation/ABI/testing/sysfs-class-backlight-driver-lm3533+3−3
@@ -4,7 +4,7 @@ KernelVersion: 3.5 · 3 unmodified lines
44 Contact: Johan Hovold <jhovold@gmail.com>
55 Description:
66 Get the ALS output channel used as input in
7− ALS-current-control mode (0, 1), where
7+ ALS-current-control mode (0, 1), where:
88
99 0 - out_current0 (backlight 0)
1010 1 - out_current1 (backlight 1)
@@ -28,7 +28,7 @@ Date: April 2012 · 17 unmodified lines
2828 KernelVersion: 3.5
2929 Contact: Johan Hovold <jhovold@gmail.com>
3030 Description:
31− Set the brightness-mapping mode (0, 1), where
31+ Set the brightness-mapping mode (0, 1), where:
3232
3333 0 - exponential mode
3434 1 - linear mode
@@ -38,7 +38,7 @@ Date: April 2012 · 3 unmodified lines
3838 KernelVersion: 3.5
3939 Contact: Johan Hovold <jhovold@gmail.com>
4040 Description:
41− Set the PWM-input control mask (5 bits), where
41+ Set the PWM-input control mask (5 bits), where:
4242
4343 bit 5 - PWM-input enabled in Zone 4
4444 bit 4 - PWM-input enabled in Zone 3
Documentation/ABI/testing/sysfs-class-cxl+3−3
@@ -1,6 +1,6 @@
1−Note: Attributes that are shared between devices are stored in the directory
2−pointed to by the symlink device/.
3−Example: The real path of the attribute /sys/class/cxl/afu0.0s/irqs_max is
1+Please note that attributes that are shared between devices are stored in
2+the directory pointed to by the symlink device/.
3+For example, the real path of the attribute /sys/class/cxl/afu0.0s/irqs_max is
44 /sys/class/cxl/afu0.0s/device/irqs_max, i.e. /sys/class/cxl/afu0.0/irqs_max.
55
66
Documentation/ABI/testing/sysfs-class-devfreq+1−1
@@ -47,7 +47,7 @@ Description: · 46 unmodified lines
4747 What: /sys/class/devfreq/.../trans_stat
4848 Date: October 2012
4949 Contact: MyungJoo Ham <myungjoo.ham@samsung.com>
50−Descrtiption:
50+Description:
5151 This ABI shows the statistics of devfreq behavior on a
5252 specific device. It shows the time spent in each state and
5353 the number of transitions between states.
Documentation/ABI/testing/sysfs-class-led-driver-lm3533+4−4
@@ -4,7 +4,7 @@ KernelVersion: 3.5 · 3 unmodified lines
44 Contact: Johan Hovold <jhovold@gmail.com>
55 Description:
66 Set the ALS output channel to use as input in
7− ALS-current-control mode (1, 2), where
7+ ALS-current-control mode (1, 2), where:
88
99 1 - out_current1
1010 2 - out_current2
@@ -22,7 +22,7 @@ Date: April 2012 · 11 unmodified lines
2222 KernelVersion: 3.5
2323 Contact: Johan Hovold <jhovold@gmail.com>
2424 Description:
25− Set the pattern generator fall and rise times (0..7), where
25+ Set the pattern generator fall and rise times (0..7), where:
2626
2727 0 - 2048 us
2828 1 - 262 ms
@@ -45,7 +45,7 @@ Date: April 2012 · 16 unmodified lines
4545 KernelVersion: 3.5
4646 Contact: Johan Hovold <jhovold@gmail.com>
4747 Description:
48− Set the brightness-mapping mode (0, 1), where
48+ Set the brightness-mapping mode (0, 1), where:
4949
5050 0 - exponential mode
5151 1 - linear mode
@@ -55,7 +55,7 @@ Date: April 2012 · 3 unmodified lines
5555 KernelVersion: 3.5
5656 Contact: Johan Hovold <jhovold@gmail.com>
5757 Description:
58− Set the PWM-input control mask (5 bits), where
58+ Set the PWM-input control mask (5 bits), where:
5959
6060 bit 5 - PWM-input enabled in Zone 4
6161 bit 4 - PWM-input enabled in Zone 3
Documentation/ABI/testing/sysfs-class-leds-gt683r+2−2
@@ -5,7 +5,7 @@ Contact: Janne Kanniainen <janne.kanniainen@gmail.com> · 4 unmodified lines
55 Description:
66 Set the mode of LEDs. You should notice that changing the mode
77 of one LED will update the mode of its two sibling devices as
8− well.
8+ well. Possible values are:
99
1010 0 - normal
1111 1 - audio
@@ -13,4 +13,4 @@ Description: · 1 unmodified line
1313
1414 Normal: LEDs are fully on when enabled
1515 Audio: LEDs brightness depends on sound level
16− Breathing: LEDs brightness varies at human breathing rate
16+ Breathing: LEDs brightness varies at human breathing rate
Documentation/ABI/testing/sysfs-class-net-phydev+8−0
@@ -41,3 +41,11 @@ Description: · 40 unmodified lines
4141 xgmii, moca, qsgmii, trgmii, 1000base-x, 2500base-x, rxaui,
4242 xaui, 10gbase-kr, unknown
4343
44+What: /sys/class/mdio_bus/<bus>/<device>/phy_standalone
45+Date: May 2019
46+KernelVersion: 5.3
47+Contact: netdev@vger.kernel.org
48+Description:
49+ Boolean value indicating whether the PHY device is used in
50+ standalone mode, without a net_device associated, by PHYLINK.
51+ Attribute created only when this is the case.
Documentation/ABI/testing/sysfs-class-net-qmi+2−2
@@ -29,7 +29,7 @@ Contact: Bjørn Mork <bjorn@mork.no> · 28 unmodified lines
2929 Description:
3030 Unsigned integer.
3131
32− Write a number ranging from 1 to 127 to add a qmap mux
32+ Write a number ranging from 1 to 254 to add a qmap mux
3333 based network device, supported by recent Qualcomm based
3434 modems.
3535
@@ -46,5 +46,5 @@ Contact: Bjørn Mork <bjorn@mork.no> · 10 unmodified lines
4646 Description:
4747 Unsigned integer.
4848
49− Write a number ranging from 1 to 127 to delete a previously
49+ Write a number ranging from 1 to 254 to delete a previously
5050 created qmap mux based network device.
Documentation/ABI/testing/sysfs-class-power+32−0
@@ -376,10 +376,42 @@ Description: · 375 unmodified lines
376376 supply. Normally this is configured based on the type of
377377 connection made (e.g. A configured SDP should output a maximum
378378 of 500mA so the input current limit is set to the same value).
379+ Use preferably input_power_limit, and for problems that can be
380+ solved using power limit use input_current_limit.
379381
380382 Access: Read, Write
381383 Valid values: Represented in microamps
382384
385+What: /sys/class/power_supply/<supply_name>/input_voltage_limit
386+Date: May 2019
387+Contact: linux-pm@vger.kernel.org
388+Description:
389+ This entry configures the incoming VBUS voltage limit currently
390+ set in the supply. Normally this is configured based on
391+ system-level knowledge or user input (e.g. This is part of the
392+ Pixel C's thermal management strategy to effectively limit the
393+ input power to 5V when the screen is on to meet Google's skin
394+ temperature targets). Note that this feature should not be
395+ used for safety critical things.
396+ Use preferably input_power_limit, and for problems that can be
397+ solved using power limit use input_voltage_limit.
398+
399+ Access: Read, Write
400+ Valid values: Represented in microvolts
401+
402+What: /sys/class/power_supply/<supply_name>/input_power_limit
403+Date: May 2019
404+Contact: linux-pm@vger.kernel.org
405+Description:
406+ This entry configures the incoming power limit currently set
407+ in the supply. Normally this is configured based on
408+ system-level knowledge or user input. Use preferably this
409+ feature to limit the incoming power and use current/voltage
410+ limit only for problems that can be solved using power limit.
411+
412+ Access: Read, Write
413+ Valid values: Represented in microwatts
414+
383415 What: /sys/class/power_supply/<supply_name>/online,
384416 Date: May 2007
385417 Contact: linux-pm@vger.kernel.org
Documentation/ABI/testing/sysfs-class-power-wilco+30−0
@@ -0,0 +1,30 @@
1+What: /sys/class/power_supply/wilco-charger/charge_type
2+Date: April 2019
3+KernelVersion: 5.2
4+Description:
5+ What charging algorithm to use:
6+
7+ Standard: Fully charges battery at a standard rate.
8+ Adaptive: Battery settings adaptively optimized based on
9+ typical battery usage pattern.
10+ Fast: Battery charges over a shorter period.
11+ Trickle: Extends battery lifespan, intended for users who
12+ primarily use their Chromebook while connected to AC.
13+ Custom: A low and high threshold percentage is specified.
14+ Charging begins when level drops below
15+ charge_control_start_threshold, and ceases when
16+ level is above charge_control_end_threshold.
17+
18+What: /sys/class/power_supply/wilco-charger/charge_control_start_threshold
19+Date: April 2019
20+KernelVersion: 5.2
21+Description:
22+ Used when charge_type="Custom", as described above. Measured in
23+ percentages. The valid range is [50, 95].
24+
25+What: /sys/class/power_supply/wilco-charger/charge_control_end_threshold
26+Date: April 2019
27+KernelVersion: 5.2
28+Description:
29+ Used when charge_type="Custom", as described above. Measured in
30+ percentages. The valid range is [55, 100].
Documentation/ABI/testing/sysfs-class-powercap+2−2
@@ -5,7 +5,7 @@ Contact: linux-pm@vger.kernel.org · 4 unmodified lines
55 Description:
66 The powercap/ class sub directory belongs to the power cap
77 subsystem. Refer to
8− Documentation/power/powercap/powercap.txt for details.
8+ Documentation/power/powercap/powercap.rst for details.
99
1010 What: /sys/class/powercap/<control type>
1111 Date: September 2013
@@ -147,6 +147,6 @@ What: /sys/class/powercap/.../<power zone>/enabled · 135 unmodified lines
147147 Date: September 2013
148148 KernelVersion: 3.13
149149 Contact: linux-pm@vger.kernel.org
150−Description
150+Description:
151151 This allows to enable/disable power capping at power zone level.
152152 This applies to current power zone and its children.
Documentation/ABI/testing/sysfs-class-switchtec+1−1
@@ -1,6 +1,6 @@
11 switchtec - Microsemi Switchtec PCI Switch Management Endpoint
22
3−For details on this subsystem look at Documentation/switchtec.txt.
3+For details on this subsystem look at Documentation/driver-api/switchtec.rst.
44
55 What: /sys/class/switchtec
66 Date: 05-Jan-2017
Documentation/ABI/testing/sysfs-class-uwb_rc+0−6
@@ -125,12 +125,6 @@ Description: · 124 unmodified lines
125125 The EUI-48 of this device in colon separated hex
126126 octets.
127127
128−What: /sys/class/uwb_rc/uwbN/<EUI-48>/BPST
129−Date: July 2008
130−KernelVersion: 2.6.27
131−Contact: linux-usb@vger.kernel.org
132−Description:
133−
134128 What: /sys/class/uwb_rc/uwbN/<EUI-48>/IEs
135129 Date: July 2008
136130 KernelVersion: 2.6.27
Documentation/ABI/testing/sysfs-devices-system-cpu+27−3
@@ -34,7 +34,7 @@ Description: CPU topology files that describe kernel limits related to · 33 unmodified lines
3434 present: cpus that have been identified as being present in
3535 the system.
3636
37− See Documentation/cputopology.txt for more information.
37+ See Documentation/admin-guide/cputopology.rst for more information.
3838
3939
4040 What: /sys/devices/system/cpu/probe
@@ -103,7 +103,7 @@ Description: CPU topology files that describe a logical CPU's relationship · 62 unmodified lines
103103 thread_siblings_list: human-readable list of cpu#'s hardware
104104 threads within the same core as cpu#
105105
106− See Documentation/cputopology.txt for more information.
106+ See Documentation/admin-guide/cputopology.rst for more information.
107107
108108
109109 What: /sys/devices/system/cpu/cpuidle/current_driver
@@ -137,7 +137,8 @@ Description: Discover cpuidle policy and mechanism · 27 unmodified lines
137137 current_governor: (RW) displays current idle policy. Users can
138138 switch the governor at runtime by writing to this file.
139139
140− See files in Documentation/cpuidle/ for more information.
140+ See Documentation/admin-guide/pm/cpuidle.rst and
141+ Documentation/driver-api/pm/cpuidle.rst for more information.
141142
142143
143144 What: /sys/devices/system/cpu/cpuX/cpuidle/stateN/name
@@ -538,3 +539,26 @@ Description: Intel Energy and Performance Bias Hint (EPB) · 394 unmodified lines
538539
539540 This attribute is present for all online CPUs supporting the
540541 Intel EPB feature.
542+
543+What: /sys/devices/system/cpu/umwait_control
544+ /sys/devices/system/cpu/umwait_control/enable_c02
545+ /sys/devices/system/cpu/umwait_control/max_time
546+Date: May 2019
547+Contact: Linux kernel mailing list <linux-kernel@vger.kernel.org>
548+Description: Umwait control
549+
550+ enable_c02: Read/write interface to control umwait C0.2 state
551+ Read returns C0.2 state status:
552+ 0: C0.2 is disabled
553+ 1: C0.2 is enabled
554+
555+ Write 'y' or '1' or 'on' to enable C0.2 state.
556+ Write 'n' or '0' or 'off' to disable C0.2 state.
557+
558+ The interface is case insensitive.
559+
560+ max_time: Read/write interface to control umwait maximum time
561+ in TSC-quanta that the CPU can reside in either C0.1
562+ or C0.2 state. The time is an unsigned 32-bit number.
563+ Note that a value of zero means there is no limit.
564+ Low order two bits must be zero.
Documentation/ABI/testing/sysfs-driver-altera-cvp+1−1
@@ -1,6 +1,6 @@
11 What: /sys/bus/pci/drivers/altera-cvp/chkcfg
22 Date: May 2017
3−Kernel Version: 4.13
3+KernelVersion: 4.13
44 Contact: Anatolij Gustschin <agust@denx.de>
55 Description:
66 Contains either 1 or 0 and controls if configuration
Documentation/ABI/testing/sysfs-driver-habanalabs+24−18
@@ -62,18 +62,20 @@ What: /sys/class/habanalabs/hl<n>/ic_clk · 61 unmodified lines
6262 Date: Jan 2019
6363 KernelVersion: 5.1
6464 Contact: oded.gabbay@gmail.com
65−Description: Allows the user to set the maximum clock frequency of the
66− Interconnect fabric. Writes to this parameter affect the device
67− only when the power management profile is set to "manual" mode.
68− The device IC clock might be set to lower value then the
65+Description: Allows the user to set the maximum clock frequency, in Hz, of
66+ the Interconnect fabric. Writes to this parameter affect the
67+ device only when the power management profile is set to "manual"
68+ mode. The device IC clock might be set to lower value than the
6969 maximum. The user should read the ic_clk_curr to see the actual
70− frequency value of the IC
70+ frequency value of the IC. This property is valid only for the
71+ Goya ASIC family
7172
7273 What: /sys/class/habanalabs/hl<n>/ic_clk_curr
7374 Date: Jan 2019
7475 KernelVersion: 5.1
7576 Contact: oded.gabbay@gmail.com
76−Description: Displays the current clock frequency of the Interconnect fabric
77+Description: Displays the current clock frequency, in Hz, of the Interconnect
78+ fabric. This property is valid only for the Goya ASIC family
7779
7880 What: /sys/class/habanalabs/hl<n>/infineon_ver
7981 Date: Jan 2019
@@ -92,18 +94,20 @@ What: /sys/class/habanalabs/hl<n>/mme_clk · 12 unmodified lines
9294 Date: Jan 2019
9395 KernelVersion: 5.1
9496 Contact: oded.gabbay@gmail.com
95−Description: Allows the user to set the maximum clock frequency of the
96− MME compute engine. Writes to this parameter affect the device
97− only when the power management profile is set to "manual" mode.
98− The device MME clock might be set to lower value then the
97+Description: Allows the user to set the maximum clock frequency, in Hz, of
98+ the MME compute engine. Writes to this parameter affect the
99+ device only when the power management profile is set to "manual"
100+ mode. The device MME clock might be set to lower value than the
99101 maximum. The user should read the mme_clk_curr to see the actual
100− frequency value of the MME
102+ frequency value of the MME. This property is valid only for the
103+ Goya ASIC family
101104
102105 What: /sys/class/habanalabs/hl<n>/mme_clk_curr
103106 Date: Jan 2019
104107 KernelVersion: 5.1
105108 Contact: oded.gabbay@gmail.com
106−Description: Displays the current clock frequency of the MME compute engine
109+Description: Displays the current clock frequency, in Hz, of the MME compute
110+ engine. This property is valid only for the Goya ASIC family
107111
108112 What: /sys/class/habanalabs/hl<n>/pci_addr
109113 Date: Jan 2019
@@ -163,18 +167,20 @@ What: /sys/class/habanalabs/hl<n>/tpc_clk · 53 unmodified lines
163167 Date: Jan 2019
164168 KernelVersion: 5.1
165169 Contact: oded.gabbay@gmail.com
166−Description: Allows the user to set the maximum clock frequency of the
167− TPC compute engines. Writes to this parameter affect the device
168− only when the power management profile is set to "manual" mode.
169− The device TPC clock might be set to lower value then the
170+Description: Allows the user to set the maximum clock frequency, in Hz, of
171+ the TPC compute engines. Writes to this parameter affect the
172+ device only when the power management profile is set to "manual"
173+ mode. The device TPC clock might be set to lower value than the
170174 maximum. The user should read the tpc_clk_curr to see the actual
171− frequency value of the TPC
175+ frequency value of the TPC. This property is valid only for
176+ Goya ASIC family
172177
173178 What: /sys/class/habanalabs/hl<n>/tpc_clk_curr
174179 Date: Jan 2019
175180 KernelVersion: 5.1
176181 Contact: oded.gabbay@gmail.com
177−Description: Displays the current clock frequency of the TPC compute engines
182+Description: Displays the current clock frequency, in Hz, of the TPC compute
183+ engines. This property is valid only for the Goya ASIC family
178184
179185 What: /sys/class/habanalabs/hl<n>/uboot_ver
180186 Date: Jan 2019
Documentation/ABI/testing/sysfs-driver-hid+6−6
@@ -1,6 +1,6 @@
1−What: For USB devices : /sys/bus/usb/devices/<busnum>-<devnum>:<config num>.<interface num>/<hid-bus>:<vendor-id>:<product-id>.<num>/report_descriptor
2− For BT devices : /sys/class/bluetooth/hci<addr>/<hid-bus>:<vendor-id>:<product-id>.<num>/report_descriptor
3− Symlink : /sys/class/hidraw/hidraw<num>/device/report_descriptor
1+What: /sys/bus/usb/devices/<busnum>-<devnum>:<config num>.<interface num>/<hid-bus>:<vendor-id>:<product-id>.<num>/report_descriptor
2+What: /sys/class/bluetooth/hci<addr>/<hid-bus>:<vendor-id>:<product-id>.<num>/report_descriptor
3+What: /sys/class/hidraw/hidraw<num>/device/report_descriptor
44 Date: Jan 2011
55 KernelVersion: 2.0.39
66 Contact: Alan Ott <alan@signal11.us>
@@ -9,9 +9,9 @@ Description: When read, this file returns the device's raw binary HID · 2 unmodified lines
99 This file cannot be written.
1010 Users: HIDAPI library (http://www.signal11.us/oss/hidapi)
1111
12−What: For USB devices : /sys/bus/usb/devices/<busnum>-<devnum>:<config num>.<interface num>/<hid-bus>:<vendor-id>:<product-id>.<num>/country
13− For BT devices : /sys/class/bluetooth/hci<addr>/<hid-bus>:<vendor-id>:<product-id>.<num>/country
14− Symlink : /sys/class/hidraw/hidraw<num>/device/country
12+What: /sys/bus/usb/devices/<busnum>-<devnum>:<config num>.<interface num>/<hid-bus>:<vendor-id>:<product-id>.<num>/country
13+What: /sys/class/bluetooth/hci<addr>/<hid-bus>:<vendor-id>:<product-id>.<num>/country
14+What: /sys/class/hidraw/hidraw<num>/device/country
1515 Date: February 2015
1616 KernelVersion: 3.19
1717 Contact: Olivier Gay <ogay@logitech.com>
Documentation/ABI/testing/sysfs-driver-hid-roccat-kone+1−1
@@ -5,7 +5,7 @@ Description: It is possible to switch the dpi setting of the mouse with the · 4 unmodified lines
55 press of a button.
66 When read, this file returns the raw number of the actual dpi
77 setting reported by the mouse. This number has to be further
8− processed to receive the real dpi value.
8+ processed to receive the real dpi value:
99
1010 VALUE DPI
1111 1 800
Documentation/ABI/testing/sysfs-driver-ppi+1−1
@@ -1,6 +1,6 @@
11 What: /sys/class/tpm/tpmX/ppi/
22 Date: August 2012
3−Kernel Version: 3.6
3+KernelVersion: 3.6
44 Contact: xiaoyan.zhang@intel.com
55 Description:
66 This folder includes the attributes related with PPI (Physical
Documentation/ABI/testing/sysfs-driver-st+1−1
@@ -1,6 +1,6 @@
11 What: /sys/bus/scsi/drivers/st/debug_flag
22 Date: October 2015
3−Kernel Version: ?.?
3+KernelVersion: ?.?
44 Contact: shane.seymour@hpe.com
55 Description:
66 This file allows you to turn debug output from the st driver
Documentation/ABI/testing/sysfs-driver-wacom+1−1
@@ -1,6 +1,6 @@
11 What: /sys/bus/hid/devices/<bus>:<vid>:<pid>.<n>/speed
22 Date: April 2010
3−Kernel Version: 2.6.35
3+KernelVersion: 2.6.35
44 Contact: linux-bluetooth@vger.kernel.org
55 Description:
66 The /sys/bus/hid/devices/<bus>:<vid>:<pid>.<n>/speed file
Documentation/ABI/testing/sysfs-fs-f2fs+8−0
@@ -243,3 +243,11 @@ Description: · 242 unmodified lines
243243 - Del: echo '[h/c]!extension' > /sys/fs/f2fs/<disk>/extension_list
244244 - [h] means add/del hot file extension
245245 - [c] means add/del cold file extension
246+
247+What: /sys/fs/f2fs/<disk>/unusable
248+Date April 2019
249+Contact: "Daniel Rosenberg" <drosen@google.com>
250+Description:
251+ If checkpoint=disable, it displays the number of blocks that are unusable.
252+ If checkpoint=enable it displays the enumber of blocks that would be unusable
253+ if checkpoint=disable were to be set.
Documentation/ABI/testing/sysfs-kernel-fscaps+1−1
@@ -2,7 +2,7 @@ What: /sys/kernel/fscaps · 1 unmodified line
22 Date: February 2011
33 KernelVersion: 2.6.38
44 Contact: Ludwig Nussel <ludwig.nussel@suse.de>
5−Description
5+Description:
66 Shows whether file system capabilities are honored
77 when executing a binary
88
Documentation/ABI/testing/sysfs-kernel-iommu_groups+9−0
@@ -24,3 +24,12 @@ Description: /sys/kernel/iommu_groups/reserved_regions list IOVA · 23 unmodified lines
2424 region is described on a single line: the 1st field is
2525 the base IOVA, the second is the end IOVA and the third
2626 field describes the type of the region.
27+
28+What: /sys/kernel/iommu_groups/reserved_regions
29+Date: June 2019
30+KernelVersion: v5.3
31+Contact: Eric Auger <eric.auger@redhat.com>
32+Description: In case an RMRR is used only by graphics or USB devices
33+ it is now exposed as "direct-relaxable" instead of "direct".
34+ In device assignment use case, for instance, those RMRR
35+ are considered to be relaxable and safe.
Documentation/ABI/testing/sysfs-kernel-uids+1−1
@@ -11,4 +11,4 @@ Description: · 10 unmodified lines
1111 example would be, if User A has shares = 1024 and user
1212 B has shares = 2048, User B will get twice the CPU
1313 bandwidth user A will. For more details refer
14− Documentation/scheduler/sched-design-CFS.txt
14+ Documentation/scheduler/sched-design-CFS.rst
Documentation/ABI/testing/sysfs-kernel-vmcoreinfo+1−1
@@ -4,7 +4,7 @@ KernelVersion: 2.6.24 · 3 unmodified lines
44 Contact: Ken'ichi Ohmichi <oomichi@mxs.nes.nec.co.jp>
55 Kexec Mailing List <kexec@lists.infradead.org>
66 Vivek Goyal <vgoyal@redhat.com>
7−Description
7+Description:
88 Shows physical address and size of vmcoreinfo ELF note.
99 First value contains physical address of note in hex and
1010 second value contains the size of note in hex. This ELF
Documentation/ABI/testing/sysfs-platform-asus-laptop+1−1
@@ -31,7 +31,7 @@ Description: · 30 unmodified lines
3131 To control the LED display, use the following :
3232 echo 0x0T000DDD > /sys/devices/platform/asus_laptop/
3333 where T control the 3 letters display, and DDD the 3 digits display.
34− The DDD table can be found in Documentation/laptops/asus-laptop.txt
34+ The DDD table can be found in Documentation/admin-guide/laptops/asus-laptop.rst
3535
3636 What: /sys/devices/platform/asus_laptop/bluetooth
3737 Date: January 2007
Documentation/ABI/testing/sysfs-platform-asus-wmi+10−0
@@ -36,3 +36,13 @@ KernelVersion: 3.5 · 35 unmodified lines
3636 Contact: "AceLan Kao" <acelan.kao@canonical.com>
3737 Description:
3838 Resume on lid open. 1 means on, 0 means off.
39+
40+What: /sys/devices/platform/<platform>/fan_boost_mode
41+Date: Sep 2019
42+KernelVersion: 5.3
43+Contact: "Yurii Pavlovskyi" <yurii.pavlovskyi@gmail.com>
44+Description:
45+ Fan boost mode:
46+ * 0 - normal,
47+ * 1 - overboost,
48+ * 2 - silent
Documentation/ABI/testing/sysfs-platform-i2c-demux-pinctrl+2−2
@@ -1,7 +1,7 @@
11 What: /sys/devices/platform/<i2c-demux-name>/available_masters
22 Date: January 2016
33 KernelVersion: 4.6
4−Contact: Wolfram Sang <wsa@the-dreams.de>
4+Contact: Wolfram Sang <wsa+renesas@sang-engineering.com>
55 Description:
66 Reading the file will give you a list of masters which can be
77 selected for a demultiplexed bus. The format is
@@ -12,7 +12,7 @@ Description: · 4 unmodified lines
1212 What: /sys/devices/platform/<i2c-demux-name>/current_master
1313 Date: January 2016
1414 KernelVersion: 4.6
15−Contact: Wolfram Sang <wsa@the-dreams.de>
15+Contact: Wolfram Sang <wsa+renesas@sang-engineering.com>
1616 Description:
1717 This file selects/shows the active I2C master for a demultiplexed
1818 bus. It uses the <index> value from the file 'available_masters'.
Documentation/ABI/testing/sysfs-platform-wilco-ec+40−0
@@ -0,0 +1,40 @@
1+What: /sys/bus/platform/devices/GOOG000C\:00/boot_on_ac
2+Date: April 2019
3+KernelVersion: 5.3
4+Description:
5+ Boot on AC is a policy which makes the device boot from S5
6+ when AC power is connected. This is useful for users who
7+ want to run their device headless or with a dock.
8+
9+ Input should be parseable by kstrtou8() to 0 or 1.
10+
11+What: /sys/bus/platform/devices/GOOG000C\:00/build_date
12+Date: May 2019
13+KernelVersion: 5.3
14+Description:
15+ Display Wilco Embedded Controller firmware build date.
16+ Output will a MM/DD/YY string.
17+
18+What: /sys/bus/platform/devices/GOOG000C\:00/build_revision
19+Date: May 2019
20+KernelVersion: 5.3
21+Description:
22+ Display Wilco Embedded Controller build revision.
23+ Output will a version string be similar to the example below:
24+ d2592cae0
25+
26+What: /sys/bus/platform/devices/GOOG000C\:00/model_number
27+Date: May 2019
28+KernelVersion: 5.3
29+Description:
30+ Display Wilco Embedded Controller model number.
31+ Output will a version string be similar to the example below:
32+ 08B6
33+
34+What: /sys/bus/platform/devices/GOOG000C\:00/version
35+Date: May 2019
36+KernelVersion: 5.3
37+Description:
38+ Display Wilco Embedded Controller firmware version.
39+ The format of the string is x.y.z. Where x is major, y is minor
40+ and z is the build number. For example: 95.00.06
Documentation/ABI/testing/sysfs-power+1−1
@@ -300,4 +300,4 @@ Description: · 299 unmodified lines
300300 attempt.
301301
302302 Using this sysfs file will override any values that were
303− set using the kernel command line for disk offset.
303+ set using the kernel command line for disk offset.
Documentation/COPYING-logorenamed from Documentation/logo.txt+0−0

File renamed without changes.

Documentation/DMA-API-HOWTO.txt+1−1
@@ -212,7 +212,7 @@ The standard 64-bit addressing device would do something like this:: · 211 unmodified lines
212212
213213 If the device only supports 32-bit addressing for descriptors in the
214214 coherent allocations, but supports full 64-bits for streaming mappings
215−it would look like this:
215+it would look like this::
216216
217217 if (dma_set_mask(dev, DMA_BIT_MASK(64))) {
218218 dev_warn(dev, "mydev: No suitable DMA available\n");
Documentation/DMA-API.txt+1−1
@@ -198,7 +198,7 @@ call to set the mask to the value returned. · 197 unmodified lines
198198 ::
199199
200200 size_t
201− dma_direct_max_mapping_size(struct device *dev);
201+ dma_max_mapping_size(struct device *dev);
202202
203203 Returns the maximum size of a mapping for the device. The size parameter
204204 of the mapping functions like dma_map_single(), dma_map_page() and
Documentation/EDID/HOWTO.txt+0−49
@@ -1,49 +0,0 @@
1−In the good old days when graphics parameters were configured explicitly
2−in a file called xorg.conf, even broken hardware could be managed.
3−
4−Today, with the advent of Kernel Mode Setting, a graphics board is
5−either correctly working because all components follow the standards -
6−or the computer is unusable, because the screen remains dark after
7−booting or it displays the wrong area. Cases when this happens are:
8−- The graphics board does not recognize the monitor.
9−- The graphics board is unable to detect any EDID data.
10−- The graphics board incorrectly forwards EDID data to the driver.
11−- The monitor sends no or bogus EDID data.
12−- A KVM sends its own EDID data instead of querying the connected monitor.
13−Adding the kernel parameter "nomodeset" helps in most cases, but causes
14−restrictions later on.
15−
16−As a remedy for such situations, the kernel configuration item
17−CONFIG_DRM_LOAD_EDID_FIRMWARE was introduced. It allows to provide an
18−individually prepared or corrected EDID data set in the /lib/firmware
19−directory from where it is loaded via the firmware interface. The code
20−(see drivers/gpu/drm/drm_edid_load.c) contains built-in data sets for
21−commonly used screen resolutions (800x600, 1024x768, 1280x1024, 1600x1200,
22−1680x1050, 1920x1080) as binary blobs, but the kernel source tree does
23−not contain code to create these data. In order to elucidate the origin
24−of the built-in binary EDID blobs and to facilitate the creation of
25−individual data for a specific misbehaving monitor, commented sources
26−and a Makefile environment are given here.
27−
28−To create binary EDID and C source code files from the existing data
29−material, simply type "make".
30−
31−If you want to create your own EDID file, copy the file 1024x768.S,
32−replace the settings with your own data and add a new target to the
33−Makefile. Please note that the EDID data structure expects the timing
34−values in a different way as compared to the standard X11 format.
35−
36−X11:
37−HTimings: hdisp hsyncstart hsyncend htotal
38−VTimings: vdisp vsyncstart vsyncend vtotal
39−
40−EDID:
41−#define XPIX hdisp
42−#define XBLANK htotal-hdisp
43−#define XOFFSET hsyncstart-hdisp
44−#define XPULSE hsyncend-hsyncstart
45−
46−#define YPIX vdisp
47−#define YBLANK vtotal-vdisp
48−#define YOFFSET vsyncstart-vdisp
49−#define YPULSE vsyncend-vsyncstart
Documentation/Kconfig+13−0
@@ -0,0 +1,13 @@
1+config WARN_MISSING_DOCUMENTS
2+
3+ bool "Warn if there's a missing documentation file"
4+ depends on COMPILE_TEST
5+ help
6+ It is not uncommon that a document gets renamed.
7+ This option makes the Kernel to check for missing dependencies,
8+ warning when something is missing. Works only if the Kernel
9+ is built from a git tree.
10+
11+ If unsure, select 'N'.
12+
13+
Documentation/Makefile+13−1
@@ -4,6 +4,11 @@ · 3 unmodified lines
44
55 subdir-y := devicetree/bindings/
66
7+# Check for broken documentation file references
8+ifeq ($(CONFIG_WARN_MISSING_DOCUMENTS),y)
9+$(shell $(srctree)/scripts/documentation-file-ref-check --warn)
10+endif
11+
712 # You can set these variables from the command line.
813 SPHINXBUILD = sphinx-build
914 SPHINXOPTS =
@@ -23,11 +28,13 @@ ifeq ($(HAVE_SPHINX),0) · 13 unmodified lines
2328 .DEFAULT:
2429 $(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.)
2530 @echo
26− @./scripts/sphinx-pre-install
31+ @$(srctree)/scripts/sphinx-pre-install
2732 @echo " SKIP Sphinx $@ target."
2833
2934 else # HAVE_SPHINX
3035
36+export SPHINXOPTS = $(shell perl -e 'open IN,"sphinx-build --version 2>&1 |"; while (<IN>) { if (m/([\d\.]+)/) { print "-jauto" if ($$1 >= "1.7") } ;} close IN')
37+
3138 # User-friendly check for pdflatex and latexmk
3239 HAVE_PDFLATEX := $(shell if which $(PDFLATEX) >/dev/null 2>&1; then echo 1; else echo 0; fi)
3340 HAVE_LATEXMK := $(shell if which latexmk >/dev/null 2>&1; then echo 1; else echo 0; fi)
@@ -70,12 +77,14 @@ quiet_cmd_sphinx = SPHINX $@ --> file://$(abspath $(BUILDDIR)/$3/$4) · 36 unmodified lines
7077 $(abspath $(BUILDDIR)/$3/$4)
7178
7279 htmldocs:
80+ @$(srctree)/scripts/sphinx-pre-install --version-check
7381 @+$(foreach var,$(SPHINXDIRS),$(call loop_cmd,sphinx,html,$(var),,$(var)))
7482
7583 linkcheckdocs:
7684 @$(foreach var,$(SPHINXDIRS),$(call loop_cmd,sphinx,linkcheck,$(var),,$(var)))
7785
7886 latexdocs:
87+ @$(srctree)/scripts/sphinx-pre-install --version-check
7988 @+$(foreach var,$(SPHINXDIRS),$(call loop_cmd,sphinx,latex,$(var),latex,$(var)))
8089
8190 ifeq ($(HAVE_PDFLATEX),0)
@@ -87,14 +96,17 @@ pdfdocs: · 5 unmodified lines
8796 else # HAVE_PDFLATEX
8897
8998 pdfdocs: latexdocs
99+ @$(srctree)/scripts/sphinx-pre-install --version-check
90100 $(foreach var,$(SPHINXDIRS), $(MAKE) PDFLATEX="$(PDFLATEX)" LATEXOPTS="$(LATEXOPTS)" -C $(BUILDDIR)/$(var)/latex || exit;)
91101
92102 endif # HAVE_PDFLATEX
93103
94104 epubdocs:
105+ @$(srctree)/scripts/sphinx-pre-install --version-check
95106 @+$(foreach var,$(SPHINXDIRS),$(call loop_cmd,sphinx,epub,$(var),epub,$(var)))
96107
97108 xmldocs:
109+ @$(srctree)/scripts/sphinx-pre-install --version-check
98110 @+$(foreach var,$(SPHINXDIRS),$(call loop_cmd,sphinx,xml,$(var),xml,$(var)))
99111
100112 endif # HAVE_SPHINX
Documentation/PCI/MSI-HOWTO.txt+0−270
@@ -1,270 +0,0 @@
1− The MSI Driver Guide HOWTO
2− Tom L Nguyen tom.l.nguyen@intel.com
3− 10/03/2003
4− Revised Feb 12, 2004 by Martine Silbermann
5− email: Martine.Silbermann@hp.com
6− Revised Jun 25, 2004 by Tom L Nguyen
7− Revised Jul 9, 2008 by Matthew Wilcox <willy@linux.intel.com>
8− Copyright 2003, 2008 Intel Corporation
9−
10−1. About this guide
11−
12−This guide describes the basics of Message Signaled Interrupts (MSIs),
13−the advantages of using MSI over traditional interrupt mechanisms, how
14−to change your driver to use MSI or MSI-X and some basic diagnostics to
15−try if a device doesn't support MSIs.
16−
17−
18−2. What are MSIs?
19−
20−A Message Signaled Interrupt is a write from the device to a special
21−address which causes an interrupt to be received by the CPU.
22−
23−The MSI capability was first specified in PCI 2.2 and was later enhanced
24−in PCI 3.0 to allow each interrupt to be masked individually. The MSI-X
25−capability was also introduced with PCI 3.0. It supports more interrupts
26−per device than MSI and allows interrupts to be independently configured.
27−
28−Devices may support both MSI and MSI-X, but only one can be enabled at
29−a time.
30−
31−
32−3. Why use MSIs?
33−
34−There are three reasons why using MSIs can give an advantage over
35−traditional pin-based interrupts.
36−
37−Pin-based PCI interrupts are often shared amongst several devices.
38−To support this, the kernel must call each interrupt handler associated
39−with an interrupt, which leads to reduced performance for the system as
40−a whole. MSIs are never shared, so this problem cannot arise.
41−
42−When a device writes data to memory, then raises a pin-based interrupt,
43−it is possible that the interrupt may arrive before all the data has
44−arrived in memory (this becomes more likely with devices behind PCI-PCI
45−bridges). In order to ensure that all the data has arrived in memory,
46−the interrupt handler must read a register on the device which raised
47−the interrupt. PCI transaction ordering rules require that all the data
48−arrive in memory before the value may be returned from the register.
49−Using MSIs avoids this problem as the interrupt-generating write cannot
50−pass the data writes, so by the time the interrupt is raised, the driver
51−knows that all the data has arrived in memory.
52−
53−PCI devices can only support a single pin-based interrupt per function.
54−Often drivers have to query the device to find out what event has
55−occurred, slowing down interrupt handling for the common case. With
56−MSIs, a device can support more interrupts, allowing each interrupt
57−to be specialised to a different purpose. One possible design gives
58−infrequent conditions (such as errors) their own interrupt which allows
59−the driver to handle the normal interrupt handling path more efficiently.
60−Other possible designs include giving one interrupt to each packet queue
61−in a network card or each port in a storage controller.
62−
63−
64−4. How to use MSIs
65−
66−PCI devices are initialised to use pin-based interrupts. The device
67−driver has to set up the device to use MSI or MSI-X. Not all machines
68−support MSIs correctly, and for those machines, the APIs described below
69−will simply fail and the device will continue to use pin-based interrupts.
70−
71−4.1 Include kernel support for MSIs
72−
73−To support MSI or MSI-X, the kernel must be built with the CONFIG_PCI_MSI
74−option enabled. This option is only available on some architectures,
75−and it may depend on some other options also being set. For example,
76−on x86, you must also enable X86_UP_APIC or SMP in order to see the
77−CONFIG_PCI_MSI option.
78−
79−4.2 Using MSI
80−
81−Most of the hard work is done for the driver in the PCI layer. The driver
82−simply has to request that the PCI layer set up the MSI capability for this
83−device.
84−
85−To automatically use MSI or MSI-X interrupt vectors, use the following
86−function:
87−
88− int pci_alloc_irq_vectors(struct pci_dev *dev, unsigned int min_vecs,
89− unsigned int max_vecs, unsigned int flags);
90−
91−which allocates up to max_vecs interrupt vectors for a PCI device. It
92−returns the number of vectors allocated or a negative error. If the device
93−has a requirements for a minimum number of vectors the driver can pass a
94−min_vecs argument set to this limit, and the PCI core will return -ENOSPC
95−if it can't meet the minimum number of vectors.
96−
97−The flags argument is used to specify which type of interrupt can be used
98−by the device and the driver (PCI_IRQ_LEGACY, PCI_IRQ_MSI, PCI_IRQ_MSIX).
99−A convenient short-hand (PCI_IRQ_ALL_TYPES) is also available to ask for
100−any possible kind of interrupt. If the PCI_IRQ_AFFINITY flag is set,
101−pci_alloc_irq_vectors() will spread the interrupts around the available CPUs.
102−
103−To get the Linux IRQ numbers passed to request_irq() and free_irq() and the
104−vectors, use the following function:
105−
106− int pci_irq_vector(struct pci_dev *dev, unsigned int nr);
107−
108−Any allocated resources should be freed before removing the device using
109−the following function:
110−
111− void pci_free_irq_vectors(struct pci_dev *dev);
112−
113−If a device supports both MSI-X and MSI capabilities, this API will use the
114−MSI-X facilities in preference to the MSI facilities. MSI-X supports any
115−number of interrupts between 1 and 2048. In contrast, MSI is restricted to
116−a maximum of 32 interrupts (and must be a power of two). In addition, the
117−MSI interrupt vectors must be allocated consecutively, so the system might
118−not be able to allocate as many vectors for MSI as it could for MSI-X. On
119−some platforms, MSI interrupts must all be targeted at the same set of CPUs
120−whereas MSI-X interrupts can all be targeted at different CPUs.
121−
122−If a device supports neither MSI-X or MSI it will fall back to a single
123−legacy IRQ vector.
124−
125−The typical usage of MSI or MSI-X interrupts is to allocate as many vectors
126−as possible, likely up to the limit supported by the device. If nvec is
127−larger than the number supported by the device it will automatically be
128−capped to the supported limit, so there is no need to query the number of
129−vectors supported beforehand:
130−
131− nvec = pci_alloc_irq_vectors(pdev, 1, nvec, PCI_IRQ_ALL_TYPES)
132− if (nvec < 0)
133− goto out_err;
134−
135−If a driver is unable or unwilling to deal with a variable number of MSI
136−interrupts it can request a particular number of interrupts by passing that
137−number to pci_alloc_irq_vectors() function as both 'min_vecs' and
138−'max_vecs' parameters:
139−
140− ret = pci_alloc_irq_vectors(pdev, nvec, nvec, PCI_IRQ_ALL_TYPES);
141− if (ret < 0)
142− goto out_err;
143−
144−The most notorious example of the request type described above is enabling
145−the single MSI mode for a device. It could be done by passing two 1s as
146−'min_vecs' and 'max_vecs':
147−
148− ret = pci_alloc_irq_vectors(pdev, 1, 1, PCI_IRQ_ALL_TYPES);
149− if (ret < 0)
150− goto out_err;
151−
152−Some devices might not support using legacy line interrupts, in which case
153−the driver can specify that only MSI or MSI-X is acceptable:
154−
155− nvec = pci_alloc_irq_vectors(pdev, 1, nvec, PCI_IRQ_MSI | PCI_IRQ_MSIX);
156− if (nvec < 0)
157− goto out_err;
158−
159−4.3 Legacy APIs
160−
161−The following old APIs to enable and disable MSI or MSI-X interrupts should
162−not be used in new code:
163−
164− pci_enable_msi() /* deprecated */
165− pci_disable_msi() /* deprecated */
166− pci_enable_msix_range() /* deprecated */
167− pci_enable_msix_exact() /* deprecated */
168− pci_disable_msix() /* deprecated */
169−
170−Additionally there are APIs to provide the number of supported MSI or MSI-X
171−vectors: pci_msi_vec_count() and pci_msix_vec_count(). In general these
172−should be avoided in favor of letting pci_alloc_irq_vectors() cap the
173−number of vectors. If you have a legitimate special use case for the count
174−of vectors we might have to revisit that decision and add a
175−pci_nr_irq_vectors() helper that handles MSI and MSI-X transparently.
176−
177−4.4 Considerations when using MSIs
178−
179−4.4.1 Spinlocks
180−
181−Most device drivers have a per-device spinlock which is taken in the
182−interrupt handler. With pin-based interrupts or a single MSI, it is not
183−necessary to disable interrupts (Linux guarantees the same interrupt will
184−not be re-entered). If a device uses multiple interrupts, the driver
185−must disable interrupts while the lock is held. If the device sends
186−a different interrupt, the driver will deadlock trying to recursively
187−acquire the spinlock. Such deadlocks can be avoided by using
188−spin_lock_irqsave() or spin_lock_irq() which disable local interrupts
189−and acquire the lock (see Documentation/kernel-hacking/locking.rst).
190−
191−4.5 How to tell whether MSI/MSI-X is enabled on a device
192−
193−Using 'lspci -v' (as root) may show some devices with "MSI", "Message
194−Signalled Interrupts" or "MSI-X" capabilities. Each of these capabilities
195−has an 'Enable' flag which is followed with either "+" (enabled)
196−or "-" (disabled).
197−
198−
199−5. MSI quirks
200−
201−Several PCI chipsets or devices are known not to support MSIs.
202−The PCI stack provides three ways to disable MSIs:
203−
204−1. globally
205−2. on all devices behind a specific bridge
206−3. on a single device
207−
208−5.1. Disabling MSIs globally
209−
210−Some host chipsets simply don't support MSIs properly. If we're
211−lucky, the manufacturer knows this and has indicated it in the ACPI
212−FADT table. In this case, Linux automatically disables MSIs.
213−Some boards don't include this information in the table and so we have
214−to detect them ourselves. The complete list of these is found near the
215−quirk_disable_all_msi() function in drivers/pci/quirks.c.
216−
217−If you have a board which has problems with MSIs, you can pass pci=nomsi
218−on the kernel command line to disable MSIs on all devices. It would be
219−in your best interests to report the problem to linux-pci@vger.kernel.org
220−including a full 'lspci -v' so we can add the quirks to the kernel.
221−
222−5.2. Disabling MSIs below a bridge
223−
224−Some PCI bridges are not able to route MSIs between busses properly.
225−In this case, MSIs must be disabled on all devices behind the bridge.
226−
227−Some bridges allow you to enable MSIs by changing some bits in their
228−PCI configuration space (especially the Hypertransport chipsets such
229−as the nVidia nForce and Serverworks HT2000). As with host chipsets,
230−Linux mostly knows about them and automatically enables MSIs if it can.
231−If you have a bridge unknown to Linux, you can enable
232−MSIs in configuration space using whatever method you know works, then
233−enable MSIs on that bridge by doing:
234−
235− echo 1 > /sys/bus/pci/devices/$bridge/msi_bus
236−
237−where $bridge is the PCI address of the bridge you've enabled (eg
238−0000:00:0e.0).
239−
240−To disable MSIs, echo 0 instead of 1. Changing this value should be
241−done with caution as it could break interrupt handling for all devices
242−below this bridge.
243−
244−Again, please notify linux-pci@vger.kernel.org of any bridges that need
245−special handling.
246−
247−5.3. Disabling MSIs on a single device
248−
249−Some devices are known to have faulty MSI implementations. Usually this
250−is handled in the individual device driver, but occasionally it's necessary
251−to handle this with a quirk. Some drivers have an option to disable use
252−of MSI. While this is a convenient workaround for the driver author,
253−it is not good practice, and should not be emulated.
254−
255−5.4. Finding why MSIs are disabled on a device
256−
257−From the above three sections, you can see that there are many reasons
258−why MSIs may not be enabled for a given device. Your first step should
259−be to examine your dmesg carefully to determine whether MSIs are enabled
260−for your machine. You should also check your .config to be sure you
261−have enabled CONFIG_PCI_MSI.
262−
263−Then, 'lspci -t' gives the list of bridges above a device. Reading
264−/sys/bus/pci/devices/*/msi_bus will tell you whether MSIs are enabled (1)
265−or disabled (0). If 0 is found in any of the msi_bus files belonging
266−to bridges between the PCI root and the device, MSIs are disabled.
267−
268−It is also worth checking the device driver to see whether it supports MSIs.
269−For example, it may contain calls to pci_irq_alloc_vectors() with the
270−PCI_IRQ_MSI or PCI_IRQ_MSIX flags.
Documentation/PCI/PCIEBUS-HOWTO.txt+0−198
@@ -1,198 +0,0 @@
1− The PCI Express Port Bus Driver Guide HOWTO
2− Tom L Nguyen tom.l.nguyen@intel.com
3− 11/03/2004
4−
5−1. About this guide
6−
7−This guide describes the basics of the PCI Express Port Bus driver
8−and provides information on how to enable the service drivers to
9−register/unregister with the PCI Express Port Bus Driver.
10−
11−2. Copyright 2004 Intel Corporation
12−
13−3. What is the PCI Express Port Bus Driver
14−
15−A PCI Express Port is a logical PCI-PCI Bridge structure. There
16−are two types of PCI Express Port: the Root Port and the Switch
17−Port. The Root Port originates a PCI Express link from a PCI Express
18−Root Complex and the Switch Port connects PCI Express links to
19−internal logical PCI buses. The Switch Port, which has its secondary
20−bus representing the switch's internal routing logic, is called the
21−switch's Upstream Port. The switch's Downstream Port is bridging from
22−switch's internal routing bus to a bus representing the downstream
23−PCI Express link from the PCI Express Switch.
24−
25−A PCI Express Port can provide up to four distinct functions,
26−referred to in this document as services, depending on its port type.
27−PCI Express Port's services include native hotplug support (HP),
28−power management event support (PME), advanced error reporting
29−support (AER), and virtual channel support (VC). These services may
30−be handled by a single complex driver or be individually distributed
31−and handled by corresponding service drivers.
32−
33−4. Why use the PCI Express Port Bus Driver?
34−
35−In existing Linux kernels, the Linux Device Driver Model allows a
36−physical device to be handled by only a single driver. The PCI
37−Express Port is a PCI-PCI Bridge device with multiple distinct
38−services. To maintain a clean and simple solution each service
39−may have its own software service driver. In this case several
40−service drivers will compete for a single PCI-PCI Bridge device.
41−For example, if the PCI Express Root Port native hotplug service
42−driver is loaded first, it claims a PCI-PCI Bridge Root Port. The
43−kernel therefore does not load other service drivers for that Root
44−Port. In other words, it is impossible to have multiple service
45−drivers load and run on a PCI-PCI Bridge device simultaneously
46−using the current driver model.
47−
48−To enable multiple service drivers running simultaneously requires
49−having a PCI Express Port Bus driver, which manages all populated
50−PCI Express Ports and distributes all provided service requests
51−to the corresponding service drivers as required. Some key
52−advantages of using the PCI Express Port Bus driver are listed below:
53−
54− - Allow multiple service drivers to run simultaneously on
55− a PCI-PCI Bridge Port device.
56−
57− - Allow service drivers implemented in an independent
58− staged approach.
59−
60− - Allow one service driver to run on multiple PCI-PCI Bridge
61− Port devices.
62−
63− - Manage and distribute resources of a PCI-PCI Bridge Port
64− device to requested service drivers.
65−
66−5. Configuring the PCI Express Port Bus Driver vs. Service Drivers
67−
68−5.1 Including the PCI Express Port Bus Driver Support into the Kernel
69−
70−Including the PCI Express Port Bus driver depends on whether the PCI
71−Express support is included in the kernel config. The kernel will
72−automatically include the PCI Express Port Bus driver as a kernel
73−driver when the PCI Express support is enabled in the kernel.
74−
75−5.2 Enabling Service Driver Support
76−
77−PCI device drivers are implemented based on Linux Device Driver Model.
78−All service drivers are PCI device drivers. As discussed above, it is
79−impossible to load any service driver once the kernel has loaded the
80−PCI Express Port Bus Driver. To meet the PCI Express Port Bus Driver
81−Model requires some minimal changes on existing service drivers that
82−imposes no impact on the functionality of existing service drivers.
83−
84−A service driver is required to use the two APIs shown below to
85−register its service with the PCI Express Port Bus driver (see
86−section 5.2.1 & 5.2.2). It is important that a service driver
87−initializes the pcie_port_service_driver data structure, included in
88−header file /include/linux/pcieport_if.h, before calling these APIs.
89−Failure to do so will result an identity mismatch, which prevents
90−the PCI Express Port Bus driver from loading a service driver.
91−
92−5.2.1 pcie_port_service_register
93−
94−int pcie_port_service_register(struct pcie_port_service_driver *new)
95−
96−This API replaces the Linux Driver Model's pci_register_driver API. A
97−service driver should always calls pcie_port_service_register at
98−module init. Note that after service driver being loaded, calls
99−such as pci_enable_device(dev) and pci_set_master(dev) are no longer
100−necessary since these calls are executed by the PCI Port Bus driver.
101−
102−5.2.2 pcie_port_service_unregister
103−
104−void pcie_port_service_unregister(struct pcie_port_service_driver *new)
105−
106−pcie_port_service_unregister replaces the Linux Driver Model's
107−pci_unregister_driver. It's always called by service driver when a
108−module exits.
109−
110−5.2.3 Sample Code
111−
112−Below is sample service driver code to initialize the port service
113−driver data structure.
114−
115−static struct pcie_port_service_id service_id[] = { {
116− .vendor = PCI_ANY_ID,
117− .device = PCI_ANY_ID,
118− .port_type = PCIE_RC_PORT,
119− .service_type = PCIE_PORT_SERVICE_AER,
120− }, { /* end: all zeroes */ }
121−};
122−
123−static struct pcie_port_service_driver root_aerdrv = {
124− .name = (char *)device_name,
125− .id_table = &service_id[0],
126−
127− .probe = aerdrv_load,
128− .remove = aerdrv_unload,
129−
130− .suspend = aerdrv_suspend,
131− .resume = aerdrv_resume,
132−};
133−
134−Below is a sample code for registering/unregistering a service
135−driver.
136−
137−static int __init aerdrv_service_init(void)
138−{
139− int retval = 0;
140−
141− retval = pcie_port_service_register(&root_aerdrv);
142− if (!retval) {
143− /*
144− * FIX ME
145− */
146− }
147− return retval;
148−}
149−
150−static void __exit aerdrv_service_exit(void)
151−{
152− pcie_port_service_unregister(&root_aerdrv);
153−}
154−
155−module_init(aerdrv_service_init);
156−module_exit(aerdrv_service_exit);
157−
158−6. Possible Resource Conflicts
159−
160−Since all service drivers of a PCI-PCI Bridge Port device are
161−allowed to run simultaneously, below lists a few of possible resource
162−conflicts with proposed solutions.
163−
164−6.1 MSI and MSI-X Vector Resource
165−
166−Once MSI or MSI-X interrupts are enabled on a device, it stays in this
167−mode until they are disabled again. Since service drivers of the same
168−PCI-PCI Bridge port share the same physical device, if an individual
169−service driver enables or disables MSI/MSI-X mode it may result
170−unpredictable behavior.
171−
172−To avoid this situation all service drivers are not permitted to
173−switch interrupt mode on its device. The PCI Express Port Bus driver
174−is responsible for determining the interrupt mode and this should be
175−transparent to service drivers. Service drivers need to know only
176−the vector IRQ assigned to the field irq of struct pcie_device, which
177−is passed in when the PCI Express Port Bus driver probes each service
178−driver. Service drivers should use (struct pcie_device*)dev->irq to
179−call request_irq/free_irq. In addition, the interrupt mode is stored
180−in the field interrupt_mode of struct pcie_device.
181−
182−6.3 PCI Memory/IO Mapped Regions
183−
184−Service drivers for PCI Express Power Management (PME), Advanced
185−Error Reporting (AER), Hot-Plug (HP) and Virtual Channel (VC) access
186−PCI configuration space on the PCI Express port. In all cases the
187−registers accessed are independent of each other. This patch assumes
188−that all service drivers will be well behaved and not overwrite
189−other service driver's configuration settings.
190−
191−6.4 PCI Config Registers
192−
193−Each service driver runs its PCI config operations on its own
194−capability structure except the PCI Express capability structure, in
195−which Root Control register and Device Control register are shared
196−between PME and AER. This patch assumes that all service drivers
197−will be well behaved and not overwrite other service driver's
198−configuration settings.
Documentation/PCI/acpi-info.rst+192−0
@@ -0,0 +1,192 @@
1+.. SPDX-License-Identifier: GPL-2.0
2+
3+========================================
4+ACPI considerations for PCI host bridges
5+========================================
6+
7+The general rule is that the ACPI namespace should describe everything the
8+OS might use unless there's another way for the OS to find it [1, 2].
9+
10+For example, there's no standard hardware mechanism for enumerating PCI
11+host bridges, so the ACPI namespace must describe each host bridge, the
12+method for accessing PCI config space below it, the address space windows
13+the host bridge forwards to PCI (using _CRS), and the routing of legacy
14+INTx interrupts (using _PRT).
15+
16+PCI devices, which are below the host bridge, generally do not need to be
17+described via ACPI. The OS can discover them via the standard PCI
18+enumeration mechanism, using config accesses to discover and identify
19+devices and read and size their BARs. However, ACPI may describe PCI
20+devices if it provides power management or hotplug functionality for them
21+or if the device has INTx interrupts connected by platform interrupt
22+controllers and a _PRT is needed to describe those connections.
23+
24+ACPI resource description is done via _CRS objects of devices in the ACPI
25+namespace [2].   The _CRS is like a generalized PCI BAR: the OS can read
26+_CRS and figure out what resource is being consumed even if it doesn't have
27+a driver for the device [3].  That's important because it means an old OS
28+can work correctly even on a system with new devices unknown to the OS.
29+The new devices might not do anything, but the OS can at least make sure no
30+resources conflict with them.
31+
32+Static tables like MCFG, HPET, ECDT, etc., are *not* mechanisms for
33+reserving address space. The static tables are for things the OS needs to
34+know early in boot, before it can parse the ACPI namespace. If a new table
35+is defined, an old OS needs to operate correctly even though it ignores the
36+table. _CRS allows that because it is generic and understood by the old
37+OS; a static table does not.
38+
39+If the OS is expected to manage a non-discoverable device described via
40+ACPI, that device will have a specific _HID/_CID that tells the OS what
41+driver to bind to it, and the _CRS tells the OS and the driver where the
42+device's registers are.
43+
44+PCI host bridges are PNP0A03 or PNP0A08 devices.  Their _CRS should
45+describe all the address space they consume.  This includes all the windows
46+they forward down to the PCI bus, as well as registers of the host bridge
47+itself that are not forwarded to PCI.  The host bridge registers include
48+things like secondary/subordinate bus registers that determine the bus
49+range below the bridge, window registers that describe the apertures, etc.
50+These are all device-specific, non-architected things, so the only way a
51+PNP0A03/PNP0A08 driver can manage them is via _PRS/_CRS/_SRS, which contain
52+the device-specific details.  The host bridge registers also include ECAM
53+space, since it is consumed by the host bridge.
54+
55+ACPI defines a Consumer/Producer bit to distinguish the bridge registers
56+("Consumer") from the bridge apertures ("Producer") [4, 5], but early
57+BIOSes didn't use that bit correctly. The result is that the current ACPI
58+spec defines Consumer/Producer only for the Extended Address Space
59+descriptors; the bit should be ignored in the older QWord/DWord/Word
60+Address Space descriptors. Consequently, OSes have to assume all
61+QWord/DWord/Word descriptors are windows.
62+
63+Prior to the addition of Extended Address Space descriptors, the failure of
64+Consumer/Producer meant there was no way to describe bridge registers in
65+the PNP0A03/PNP0A08 device itself. The workaround was to describe the
66+bridge registers (including ECAM space) in PNP0C02 catch-all devices [6].
67+With the exception of ECAM, the bridge register space is device-specific
68+anyway, so the generic PNP0A03/PNP0A08 driver (pci_root.c) has no need to
69+know about it.  
70+
71+New architectures should be able to use "Consumer" Extended Address Space
72+descriptors in the PNP0A03 device for bridge registers, including ECAM,
73+although a strict interpretation of [6] might prohibit this. Old x86 and
74+ia64 kernels assume all address space descriptors, including "Consumer"
75+Extended Address Space ones, are windows, so it would not be safe to
76+describe bridge registers this way on those architectures.
77+
78+PNP0C02 "motherboard" devices are basically a catch-all.  There's no
79+programming model for them other than "don't use these resources for
80+anything else."  So a PNP0C02 _CRS should claim any address space that is
81+(1) not claimed by _CRS under any other device object in the ACPI namespace
82+and (2) should not be assigned by the OS to something else.
83+
84+The PCIe spec requires the Enhanced Configuration Access Method (ECAM)
85+unless there's a standard firmware interface for config access, e.g., the
86+ia64 SAL interface [7]. A host bridge consumes ECAM memory address space
87+and converts memory accesses into PCI configuration accesses. The spec
88+defines the ECAM address space layout and functionality; only the base of
89+the address space is device-specific. An ACPI OS learns the base address
90+from either the static MCFG table or a _CBA method in the PNP0A03 device.
91+
92+The MCFG table must describe the ECAM space of non-hot pluggable host
93+bridges [8]. Since MCFG is a static table and can't be updated by hotplug,
94+a _CBA method in the PNP0A03 device describes the ECAM space of a
95+hot-pluggable host bridge [9]. Note that for both MCFG and _CBA, the base
96+address always corresponds to bus 0, even if the bus range below the bridge
97+(which is reported via _CRS) doesn't start at 0.
98+
99+
100+[1] ACPI 6.2, sec 6.1:
101+ For any device that is on a non-enumerable type of bus (for example, an
102+ ISA bus), OSPM enumerates the devices' identifier(s) and the ACPI
103+ system firmware must supply an _HID object ... for each device to
104+ enable OSPM to do that.
105+
106+[2] ACPI 6.2, sec 3.7:
107+ The OS enumerates motherboard devices simply by reading through the
108+ ACPI Namespace looking for devices with hardware IDs.
109+
110+ Each device enumerated by ACPI includes ACPI-defined objects in the
111+ ACPI Namespace that report the hardware resources the device could
112+ occupy [_PRS], an object that reports the resources that are currently
113+ used by the device [_CRS], and objects for configuring those resources
114+ [_SRS]. The information is used by the Plug and Play OS (OSPM) to
115+ configure the devices.
116+
117+[3] ACPI 6.2, sec 6.2:
118+ OSPM uses device configuration objects to configure hardware resources
119+ for devices enumerated via ACPI. Device configuration objects provide
120+ information about current and possible resource requirements, the
121+ relationship between shared resources, and methods for configuring
122+ hardware resources.
123+
124+ When OSPM enumerates a device, it calls _PRS to determine the resource
125+ requirements of the device. It may also call _CRS to find the current
126+ resource settings for the device. Using this information, the Plug and
127+ Play system determines what resources the device should consume and
128+ sets those resources by calling the device’s _SRS control method.
129+
130+ In ACPI, devices can consume resources (for example, legacy keyboards),
131+ provide resources (for example, a proprietary PCI bridge), or do both.
132+ Unless otherwise specified, resources for a device are assumed to be
133+ taken from the nearest matching resource above the device in the device
134+ hierarchy.
135+
136+[4] ACPI 6.2, sec 6.4.3.5.1, 2, 3, 4:
137+ QWord/DWord/Word Address Space Descriptor (.1, .2, .3)
138+ General Flags: Bit [0] Ignored
139+
140+ Extended Address Space Descriptor (.4)
141+ General Flags: Bit [0] Consumer/Producer:
142+
143+ * 1 – This device consumes this resource
144+ * 0 – This device produces and consumes this resource
145+
146+[5] ACPI 6.2, sec 19.6.43:
147+ ResourceUsage specifies whether the Memory range is consumed by
148+ this device (ResourceConsumer) or passed on to child devices
149+ (ResourceProducer). If nothing is specified, then
150+ ResourceConsumer is assumed.
151+
152+[6] PCI Firmware 3.2, sec 4.1.2:
153+ If the operating system does not natively comprehend reserving the
154+ MMCFG region, the MMCFG region must be reserved by firmware. The
155+ address range reported in the MCFG table or by _CBA method (see Section
156+ 4.1.3) must be reserved by declaring a motherboard resource. For most
157+ systems, the motherboard resource would appear at the root of the ACPI
158+ namespace (under \_SB) in a node with a _HID of EISAID (PNP0C02), and
159+ the resources in this case should not be claimed in the root PCI bus’s
160+ _CRS. The resources can optionally be returned in Int15 E820 or
161+ EFIGetMemoryMap as reserved memory but must always be reported through
162+ ACPI as a motherboard resource.
163+
164+[7] PCI Express 4.0, sec 7.2.2:
165+ For systems that are PC-compatible, or that do not implement a
166+ processor-architecture-specific firmware interface standard that allows
167+ access to the Configuration Space, the ECAM is required as defined in
168+ this section.
169+
170+[8] PCI Firmware 3.2, sec 4.1.2:
171+ The MCFG table is an ACPI table that is used to communicate the base
172+ addresses corresponding to the non-hot removable PCI Segment Groups
173+ range within a PCI Segment Group available to the operating system at
174+ boot. This is required for the PC-compatible systems.
175+
176+ The MCFG table is only used to communicate the base addresses
177+ corresponding to the PCI Segment Groups available to the system at
178+ boot.
179+
180+[9] PCI Firmware 3.2, sec 4.1.3:
181+ The _CBA (Memory mapped Configuration Base Address) control method is
182+ an optional ACPI object that returns the 64-bit memory mapped
183+ configuration base address for the hot plug capable host bridge. The
184+ base address returned by _CBA is processor-relative address. The _CBA
185+ control method evaluates to an Integer.
186+
187+ This control method appears under a host bridge object. When the _CBA
188+ method appears under an active host bridge object, the operating system
189+ evaluates this structure to identify the memory mapped configuration
190+ base address corresponding to the PCI Segment Group for the bus number
191+ range specified in _CRS method. An ACPI name space object that contains
192+ the _CBA method must also contain a corresponding _SEG method.
Documentation/PCI/acpi-info.txt+0−187
@@ -1,187 +0,0 @@
1− ACPI considerations for PCI host bridges
2−
3−The general rule is that the ACPI namespace should describe everything the
4−OS might use unless there's another way for the OS to find it [1, 2].
5−
6−For example, there's no standard hardware mechanism for enumerating PCI
7−host bridges, so the ACPI namespace must describe each host bridge, the
8−method for accessing PCI config space below it, the address space windows
9−the host bridge forwards to PCI (using _CRS), and the routing of legacy
10−INTx interrupts (using _PRT).
11−
12−PCI devices, which are below the host bridge, generally do not need to be
13−described via ACPI. The OS can discover them via the standard PCI
14−enumeration mechanism, using config accesses to discover and identify
15−devices and read and size their BARs. However, ACPI may describe PCI
16−devices if it provides power management or hotplug functionality for them
17−or if the device has INTx interrupts connected by platform interrupt
18−controllers and a _PRT is needed to describe those connections.
19−
20−ACPI resource description is done via _CRS objects of devices in the ACPI
21−namespace [2].   The _CRS is like a generalized PCI BAR: the OS can read
22−_CRS and figure out what resource is being consumed even if it doesn't have
23−a driver for the device [3].  That's important because it means an old OS
24−can work correctly even on a system with new devices unknown to the OS.
25−The new devices might not do anything, but the OS can at least make sure no
26−resources conflict with them.
27−
28−Static tables like MCFG, HPET, ECDT, etc., are *not* mechanisms for
29−reserving address space. The static tables are for things the OS needs to
30−know early in boot, before it can parse the ACPI namespace. If a new table
31−is defined, an old OS needs to operate correctly even though it ignores the
32−table. _CRS allows that because it is generic and understood by the old
33−OS; a static table does not.
34−
35−If the OS is expected to manage a non-discoverable device described via
36−ACPI, that device will have a specific _HID/_CID that tells the OS what
37−driver to bind to it, and the _CRS tells the OS and the driver where the
38−device's registers are.
39−
40−PCI host bridges are PNP0A03 or PNP0A08 devices.  Their _CRS should
41−describe all the address space they consume.  This includes all the windows
42−they forward down to the PCI bus, as well as registers of the host bridge
43−itself that are not forwarded to PCI.  The host bridge registers include
44−things like secondary/subordinate bus registers that determine the bus
45−range below the bridge, window registers that describe the apertures, etc.
46−These are all device-specific, non-architected things, so the only way a
47−PNP0A03/PNP0A08 driver can manage them is via _PRS/_CRS/_SRS, which contain
48−the device-specific details.  The host bridge registers also include ECAM
49−space, since it is consumed by the host bridge.
50−
51−ACPI defines a Consumer/Producer bit to distinguish the bridge registers
52−("Consumer") from the bridge apertures ("Producer") [4, 5], but early
53−BIOSes didn't use that bit correctly. The result is that the current ACPI
54−spec defines Consumer/Producer only for the Extended Address Space
55−descriptors; the bit should be ignored in the older QWord/DWord/Word
56−Address Space descriptors. Consequently, OSes have to assume all
57−QWord/DWord/Word descriptors are windows.
58−
59−Prior to the addition of Extended Address Space descriptors, the failure of
60−Consumer/Producer meant there was no way to describe bridge registers in
61−the PNP0A03/PNP0A08 device itself. The workaround was to describe the
62−bridge registers (including ECAM space) in PNP0C02 catch-all devices [6].
63−With the exception of ECAM, the bridge register space is device-specific
64−anyway, so the generic PNP0A03/PNP0A08 driver (pci_root.c) has no need to
65−know about it.  
66−
67−New architectures should be able to use "Consumer" Extended Address Space
68−descriptors in the PNP0A03 device for bridge registers, including ECAM,
69−although a strict interpretation of [6] might prohibit this. Old x86 and
70−ia64 kernels assume all address space descriptors, including "Consumer"
71−Extended Address Space ones, are windows, so it would not be safe to
72−describe bridge registers this way on those architectures.
73−
74−PNP0C02 "motherboard" devices are basically a catch-all.  There's no
75−programming model for them other than "don't use these resources for
76−anything else."  So a PNP0C02 _CRS should claim any address space that is
77−(1) not claimed by _CRS under any other device object in the ACPI namespace
78−and (2) should not be assigned by the OS to something else.
79−
80−The PCIe spec requires the Enhanced Configuration Access Method (ECAM)
81−unless there's a standard firmware interface for config access, e.g., the
82−ia64 SAL interface [7]. A host bridge consumes ECAM memory address space
83−and converts memory accesses into PCI configuration accesses. The spec
84−defines the ECAM address space layout and functionality; only the base of
85−the address space is device-specific. An ACPI OS learns the base address
86−from either the static MCFG table or a _CBA method in the PNP0A03 device.
87−
88−The MCFG table must describe the ECAM space of non-hot pluggable host
89−bridges [8]. Since MCFG is a static table and can't be updated by hotplug,
90−a _CBA method in the PNP0A03 device describes the ECAM space of a
91−hot-pluggable host bridge [9]. Note that for both MCFG and _CBA, the base
92−address always corresponds to bus 0, even if the bus range below the bridge
93−(which is reported via _CRS) doesn't start at 0.
94−
95−
96−[1] ACPI 6.2, sec 6.1:
97− For any device that is on a non-enumerable type of bus (for example, an
98− ISA bus), OSPM enumerates the devices' identifier(s) and the ACPI
99− system firmware must supply an _HID object ... for each device to
100− enable OSPM to do that.
101−
102−[2] ACPI 6.2, sec 3.7:
103− The OS enumerates motherboard devices simply by reading through the
104− ACPI Namespace looking for devices with hardware IDs.
105−
106− Each device enumerated by ACPI includes ACPI-defined objects in the
107− ACPI Namespace that report the hardware resources the device could
108− occupy [_PRS], an object that reports the resources that are currently
109− used by the device [_CRS], and objects for configuring those resources
110− [_SRS]. The information is used by the Plug and Play OS (OSPM) to
111− configure the devices.
112−
113−[3] ACPI 6.2, sec 6.2:
114− OSPM uses device configuration objects to configure hardware resources
115− for devices enumerated via ACPI. Device configuration objects provide
116− information about current and possible resource requirements, the
117− relationship between shared resources, and methods for configuring
118− hardware resources.
119−
120− When OSPM enumerates a device, it calls _PRS to determine the resource
121− requirements of the device. It may also call _CRS to find the current
122− resource settings for the device. Using this information, the Plug and
123− Play system determines what resources the device should consume and
124− sets those resources by calling the device’s _SRS control method.
125−
126− In ACPI, devices can consume resources (for example, legacy keyboards),
127− provide resources (for example, a proprietary PCI bridge), or do both.
128− Unless otherwise specified, resources for a device are assumed to be
129− taken from the nearest matching resource above the device in the device
130− hierarchy.
131−
132−[4] ACPI 6.2, sec 6.4.3.5.1, 2, 3, 4:
133− QWord/DWord/Word Address Space Descriptor (.1, .2, .3)
134− General Flags: Bit [0] Ignored
135−
136− Extended Address Space Descriptor (.4)
137− General Flags: Bit [0] Consumer/Producer:
138− 1–This device consumes this resource
139− 0–This device produces and consumes this resource
140−
141−[5] ACPI 6.2, sec 19.6.43:
142− ResourceUsage specifies whether the Memory range is consumed by
143− this device (ResourceConsumer) or passed on to child devices
144− (ResourceProducer). If nothing is specified, then
145− ResourceConsumer is assumed.
146−
147−[6] PCI Firmware 3.2, sec 4.1.2:
148− If the operating system does not natively comprehend reserving the
149− MMCFG region, the MMCFG region must be reserved by firmware. The
150− address range reported in the MCFG table or by _CBA method (see Section
151− 4.1.3) must be reserved by declaring a motherboard resource. For most
152− systems, the motherboard resource would appear at the root of the ACPI
153− namespace (under \_SB) in a node with a _HID of EISAID (PNP0C02), and
154− the resources in this case should not be claimed in the root PCI bus’s
155− _CRS. The resources can optionally be returned in Int15 E820 or
156− EFIGetMemoryMap as reserved memory but must always be reported through
157− ACPI as a motherboard resource.
158−
159−[7] PCI Express 4.0, sec 7.2.2:
160− For systems that are PC-compatible, or that do not implement a
161− processor-architecture-specific firmware interface standard that allows
162− access to the Configuration Space, the ECAM is required as defined in
163− this section.
164−
165−[8] PCI Firmware 3.2, sec 4.1.2:
166− The MCFG table is an ACPI table that is used to communicate the base
167− addresses corresponding to the non-hot removable PCI Segment Groups
168− range within a PCI Segment Group available to the operating system at
169− boot. This is required for the PC-compatible systems.
170−
171− The MCFG table is only used to communicate the base addresses
172− corresponding to the PCI Segment Groups available to the system at
173− boot.
174−
175−[9] PCI Firmware 3.2, sec 4.1.3:
176− The _CBA (Memory mapped Configuration Base Address) control method is
177− an optional ACPI object that returns the 64-bit memory mapped
178− configuration base address for the hot plug capable host bridge. The
179− base address returned by _CBA is processor-relative address. The _CBA
180− control method evaluates to an Integer.
181−
182− This control method appears under a host bridge object. When the _CBA
183− method appears under an active host bridge object, the operating system
184− evaluates this structure to identify the memory mapped configuration
185− base address corresponding to the PCI Segment Group for the bus number
186− range specified in _CRS method. An ACPI name space object that contains
187− the _CBA method must also contain a corresponding _SEG method.
Documentation/PCI/endpoint/index.rst+13−0
@@ -0,0 +1,13 @@
1+.. SPDX-License-Identifier: GPL-2.0
2+
3+======================
4+PCI Endpoint Framework
5+======================
6+
7+.. toctree::
8+ :maxdepth: 2
9+
10+ pci-endpoint
11+ pci-endpoint-cfs
12+ pci-test-function
13+ pci-test-howto
Documentation/PCI/endpoint/pci-endpoint-cfs.rst+118−0
@@ -0,0 +1,118 @@
1+.. SPDX-License-Identifier: GPL-2.0
2+
3+=======================================
4+Configuring PCI Endpoint Using CONFIGFS
5+=======================================
6+
7+:Author: Kishon Vijay Abraham I <kishon@ti.com>
8+
9+The PCI Endpoint Core exposes configfs entry (pci_ep) to configure the
10+PCI endpoint function and to bind the endpoint function
11+with the endpoint controller. (For introducing other mechanisms to
12+configure the PCI Endpoint Function refer to [1]).
13+
14+Mounting configfs
15+=================
16+
17+The PCI Endpoint Core layer creates pci_ep directory in the mounted configfs
18+directory. configfs can be mounted using the following command::
19+
20+ mount -t configfs none /sys/kernel/config
21+
22+Directory Structure
23+===================
24+
25+The pci_ep configfs has two directories at its root: controllers and
26+functions. Every EPC device present in the system will have an entry in
27+the *controllers* directory and and every EPF driver present in the system
28+will have an entry in the *functions* directory.
29+::
30+
31+ /sys/kernel/config/pci_ep/
32+ .. controllers/
33+ .. functions/
34+
35+Creating EPF Device
36+===================
37+
38+Every registered EPF driver will be listed in controllers directory. The
39+entries corresponding to EPF driver will be created by the EPF core.
40+::
41+
42+ /sys/kernel/config/pci_ep/functions/
43+ .. <EPF Driver1>/
44+ ... <EPF Device 11>/
45+ ... <EPF Device 21>/
46+ .. <EPF Driver2>/
47+ ... <EPF Device 12>/
48+ ... <EPF Device 22>/
49+
50+In order to create a <EPF device> of the type probed by <EPF Driver>, the
51+user has to create a directory inside <EPF DriverN>.
52+
53+Every <EPF device> directory consists of the following entries that can be
54+used to configure the standard configuration header of the endpoint function.
55+(These entries are created by the framework when any new <EPF Device> is
56+created)
57+::
58+
59+ .. <EPF Driver1>/
60+ ... <EPF Device 11>/
61+ ... vendorid
62+ ... deviceid
63+ ... revid
64+ ... progif_code
65+ ... subclass_code
66+ ... baseclass_code
67+ ... cache_line_size
68+ ... subsys_vendor_id
69+ ... subsys_id
70+ ... interrupt_pin
71+
72+EPC Device
73+==========
74+
75+Every registered EPC device will be listed in controllers directory. The
76+entries corresponding to EPC device will be created by the EPC core.
77+::
78+
79+ /sys/kernel/config/pci_ep/controllers/
80+ .. <EPC Device1>/
81+ ... <Symlink EPF Device11>/
82+ ... <Symlink EPF Device12>/
83+ ... start
84+ .. <EPC Device2>/
85+ ... <Symlink EPF Device21>/
86+ ... <Symlink EPF Device22>/
87+ ... start
88+
89+The <EPC Device> directory will have a list of symbolic links to
90+<EPF Device>. These symbolic links should be created by the user to
91+represent the functions present in the endpoint device.
92+
93+The <EPC Device> directory will also have a *start* field. Once
94+"1" is written to this field, the endpoint device will be ready to
95+establish the link with the host. This is usually done after
96+all the EPF devices are created and linked with the EPC device.
97+::
98+
99+ | controllers/
100+ | <Directory: EPC name>/
101+ | <Symbolic Link: Function>
102+ | start
103+ | functions/
104+ | <Directory: EPF driver>/
105+ | <Directory: EPF device>/
106+ | vendorid
107+ | deviceid
108+ | revid
109+ | progif_code
110+ | subclass_code
111+ | baseclass_code
112+ | cache_line_size
113+ | subsys_vendor_id
114+ | subsys_id
115+ | interrupt_pin
116+ | function
117+
118+[1] :doc:`pci-endpoint`
Documentation/PCI/endpoint/pci-endpoint-cfs.txt+0−105
@@ -1,105 +0,0 @@
1− CONFIGURING PCI ENDPOINT USING CONFIGFS
2− Kishon Vijay Abraham I <kishon@ti.com>
3−
4−The PCI Endpoint Core exposes configfs entry (pci_ep) to configure the
5−PCI endpoint function and to bind the endpoint function
6−with the endpoint controller. (For introducing other mechanisms to
7−configure the PCI Endpoint Function refer to [1]).
8−
9−*) Mounting configfs
10−
11−The PCI Endpoint Core layer creates pci_ep directory in the mounted configfs
12−directory. configfs can be mounted using the following command.
13−
14− mount -t configfs none /sys/kernel/config
15−
16−*) Directory Structure
17−
18−The pci_ep configfs has two directories at its root: controllers and
19−functions. Every EPC device present in the system will have an entry in
20−the *controllers* directory and and every EPF driver present in the system
21−will have an entry in the *functions* directory.
22−
23−/sys/kernel/config/pci_ep/
24− .. controllers/
25− .. functions/
26−
27−*) Creating EPF Device
28−
29−Every registered EPF driver will be listed in controllers directory. The
30−entries corresponding to EPF driver will be created by the EPF core.
31−
32−/sys/kernel/config/pci_ep/functions/
33− .. <EPF Driver1>/
34− ... <EPF Device 11>/
35− ... <EPF Device 21>/
36− .. <EPF Driver2>/
37− ... <EPF Device 12>/
38− ... <EPF Device 22>/
39−
40−In order to create a <EPF device> of the type probed by <EPF Driver>, the
41−user has to create a directory inside <EPF DriverN>.
42−
43−Every <EPF device> directory consists of the following entries that can be
44−used to configure the standard configuration header of the endpoint function.
45−(These entries are created by the framework when any new <EPF Device> is
46−created)
47−
48− .. <EPF Driver1>/
49− ... <EPF Device 11>/
50− ... vendorid
51− ... deviceid
52− ... revid
53− ... progif_code
54− ... subclass_code
55− ... baseclass_code
56− ... cache_line_size
57− ... subsys_vendor_id
58− ... subsys_id
59− ... interrupt_pin
60−
61−*) EPC Device
62−
63−Every registered EPC device will be listed in controllers directory. The
64−entries corresponding to EPC device will be created by the EPC core.
65−
66−/sys/kernel/config/pci_ep/controllers/
67− .. <EPC Device1>/
68− ... <Symlink EPF Device11>/
69− ... <Symlink EPF Device12>/
70− ... start
71− .. <EPC Device2>/
72− ... <Symlink EPF Device21>/
73− ... <Symlink EPF Device22>/
74− ... start
75−
76−The <EPC Device> directory will have a list of symbolic links to
77−<EPF Device>. These symbolic links should be created by the user to
78−represent the functions present in the endpoint device.
79−
80−The <EPC Device> directory will also have a *start* field. Once
81−"1" is written to this field, the endpoint device will be ready to
82−establish the link with the host. This is usually done after
83−all the EPF devices are created and linked with the EPC device.
84−
85−
86− | controllers/
87− | <Directory: EPC name>/
88− | <Symbolic Link: Function>
89− | start
90− | functions/
91− | <Directory: EPF driver>/
92− | <Directory: EPF device>/
93− | vendorid
94− | deviceid
95− | revid
96− | progif_code
97− | subclass_code
98− | baseclass_code
99− | cache_line_size
100− | subsys_vendor_id
101− | subsys_id
102− | interrupt_pin
103− | function
104−
105−[1] -> Documentation/PCI/endpoint/pci-endpoint.txt
Documentation/PCI/endpoint/pci-endpoint.rst+231−0
@@ -0,0 +1,231 @@
1+.. SPDX-License-Identifier: GPL-2.0
2+
3+:Author: Kishon Vijay Abraham I <kishon@ti.com>
4+
5+This document is a guide to use the PCI Endpoint Framework in order to create
6+endpoint controller driver, endpoint function driver, and using configfs
7+interface to bind the function driver to the controller driver.
8+
9+Introduction
10+============
11+
12+Linux has a comprehensive PCI subsystem to support PCI controllers that
13+operates in Root Complex mode. The subsystem has capability to scan PCI bus,
14+assign memory resources and IRQ resources, load PCI driver (based on
15+vendor ID, device ID), support other services like hot-plug, power management,
16+advanced error reporting and virtual channels.
17+
18+However the PCI controller IP integrated in some SoCs is capable of operating
19+either in Root Complex mode or Endpoint mode. PCI Endpoint Framework will
20+add endpoint mode support in Linux. This will help to run Linux in an
21+EP system which can have a wide variety of use cases from testing or
22+validation, co-processor accelerator, etc.
23+
24+PCI Endpoint Core
25+=================
26+
27+The PCI Endpoint Core layer comprises 3 components: the Endpoint Controller
28+library, the Endpoint Function library, and the configfs layer to bind the
29+endpoint function with the endpoint controller.
30+
31+PCI Endpoint Controller(EPC) Library
32+------------------------------------
33+
34+The EPC library provides APIs to be used by the controller that can operate
35+in endpoint mode. It also provides APIs to be used by function driver/library
36+in order to implement a particular endpoint function.
37+
38+APIs for the PCI controller Driver
39+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
40+
41+This section lists the APIs that the PCI Endpoint core provides to be used
42+by the PCI controller driver.
43+
44+* devm_pci_epc_create()/pci_epc_create()
45+
46+ The PCI controller driver should implement the following ops:
47+
48+ * write_header: ops to populate configuration space header
49+ * set_bar: ops to configure the BAR
50+ * clear_bar: ops to reset the BAR
51+ * alloc_addr_space: ops to allocate in PCI controller address space
52+ * free_addr_space: ops to free the allocated address space
53+ * raise_irq: ops to raise a legacy, MSI or MSI-X interrupt
54+ * start: ops to start the PCI link
55+ * stop: ops to stop the PCI link
56+
57+ The PCI controller driver can then create a new EPC device by invoking
58+ devm_pci_epc_create()/pci_epc_create().
59+
60+* devm_pci_epc_destroy()/pci_epc_destroy()
61+
62+ The PCI controller driver can destroy the EPC device created by either
63+ devm_pci_epc_create() or pci_epc_create() using devm_pci_epc_destroy() or
64+ pci_epc_destroy().
65+
66+* pci_epc_linkup()
67+
68+ In order to notify all the function devices that the EPC device to which
69+ they are linked has established a link with the host, the PCI controller
70+ driver should invoke pci_epc_linkup().
71+
72+* pci_epc_mem_init()
73+
74+ Initialize the pci_epc_mem structure used for allocating EPC addr space.
75+
76+* pci_epc_mem_exit()
77+
78+ Cleanup the pci_epc_mem structure allocated during pci_epc_mem_init().
79+
80+
81+APIs for the PCI Endpoint Function Driver
82+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
83+
84+This section lists the APIs that the PCI Endpoint core provides to be used
85+by the PCI endpoint function driver.
86+
87+* pci_epc_write_header()
88+
89+ The PCI endpoint function driver should use pci_epc_write_header() to
90+ write the standard configuration header to the endpoint controller.
91+
92+* pci_epc_set_bar()
93+
94+ The PCI endpoint function driver should use pci_epc_set_bar() to configure
95+ the Base Address Register in order for the host to assign PCI addr space.
96+ Register space of the function driver is usually configured
97+ using this API.
98+
99+* pci_epc_clear_bar()
100+
101+ The PCI endpoint function driver should use pci_epc_clear_bar() to reset
102+ the BAR.
103+
104+* pci_epc_raise_irq()
105+
106+ The PCI endpoint function driver should use pci_epc_raise_irq() to raise
107+ Legacy Interrupt, MSI or MSI-X Interrupt.
108+
109+* pci_epc_mem_alloc_addr()
110+
111+ The PCI endpoint function driver should use pci_epc_mem_alloc_addr(), to
112+ allocate memory address from EPC addr space which is required to access
113+ RC's buffer
114+
115+* pci_epc_mem_free_addr()
116+
117+ The PCI endpoint function driver should use pci_epc_mem_free_addr() to
118+ free the memory space allocated using pci_epc_mem_alloc_addr().
119+
120+Other APIs
121+~~~~~~~~~~
122+
123+There are other APIs provided by the EPC library. These are used for binding
124+the EPF device with EPC device. pci-ep-cfs.c can be used as reference for
125+using these APIs.
126+
127+* pci_epc_get()
128+
129+ Get a reference to the PCI endpoint controller based on the device name of
130+ the controller.
131+
132+* pci_epc_put()
133+
134+ Release the reference to the PCI endpoint controller obtained using
135+ pci_epc_get()
136+
137+* pci_epc_add_epf()
138+
139+ Add a PCI endpoint function to a PCI endpoint controller. A PCIe device
140+ can have up to 8 functions according to the specification.
141+
142+* pci_epc_remove_epf()
143+
144+ Remove the PCI endpoint function from PCI endpoint controller.
145+
146+* pci_epc_start()
147+
148+ The PCI endpoint function driver should invoke pci_epc_start() once it
149+ has configured the endpoint function and wants to start the PCI link.
150+
151+* pci_epc_stop()
152+
153+ The PCI endpoint function driver should invoke pci_epc_stop() to stop
154+ the PCI LINK.
155+
156+
157+PCI Endpoint Function(EPF) Library
158+----------------------------------
159+
160+The EPF library provides APIs to be used by the function driver and the EPC
161+library to provide endpoint mode functionality.
162+
163+APIs for the PCI Endpoint Function Driver
164+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
165+
166+This section lists the APIs that the PCI Endpoint core provides to be used
167+by the PCI endpoint function driver.
168+
169+* pci_epf_register_driver()
170+
171+ The PCI Endpoint Function driver should implement the following ops:
172+ * bind: ops to perform when a EPC device has been bound to EPF device
173+ * unbind: ops to perform when a binding has been lost between a EPC
174+ device and EPF device
175+ * linkup: ops to perform when the EPC device has established a
176+ connection with a host system
177+
178+ The PCI Function driver can then register the PCI EPF driver by using
179+ pci_epf_register_driver().
180+
181+* pci_epf_unregister_driver()
182+
183+ The PCI Function driver can unregister the PCI EPF driver by using
184+ pci_epf_unregister_driver().
185+
186+* pci_epf_alloc_space()
187+
188+ The PCI Function driver can allocate space for a particular BAR using
189+ pci_epf_alloc_space().
190+
191+* pci_epf_free_space()
192+
193+ The PCI Function driver can free the allocated space
194+ (using pci_epf_alloc_space) by invoking pci_epf_free_space().
195+
196+APIs for the PCI Endpoint Controller Library
197+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
198+
199+This section lists the APIs that the PCI Endpoint core provides to be used
200+by the PCI endpoint controller library.
201+
202+* pci_epf_linkup()
203+
204+ The PCI endpoint controller library invokes pci_epf_linkup() when the
205+ EPC device has established the connection to the host.
206+
207+Other APIs
208+~~~~~~~~~~
209+
210+There are other APIs provided by the EPF library. These are used to notify
211+the function driver when the EPF device is bound to the EPC device.
212+pci-ep-cfs.c can be used as reference for using these APIs.
213+
214+* pci_epf_create()
215+
216+ Create a new PCI EPF device by passing the name of the PCI EPF device.
217+ This name will be used to bind the the EPF device to a EPF driver.
218+
219+* pci_epf_destroy()
220+
221+ Destroy the created PCI EPF device.
222+
223+* pci_epf_bind()
224+
225+ pci_epf_bind() should be invoked when the EPF device has been bound to
226+ a EPC device.
227+
228+* pci_epf_unbind()
229+
230+ pci_epf_unbind() should be invoked when the binding between EPC device
231+ and EPF device is lost.
Documentation/PCI/endpoint/pci-endpoint.txt+0−215
@@ -1,215 +0,0 @@
1− PCI ENDPOINT FRAMEWORK
2− Kishon Vijay Abraham I <kishon@ti.com>
3−
4−This document is a guide to use the PCI Endpoint Framework in order to create
5−endpoint controller driver, endpoint function driver, and using configfs
6−interface to bind the function driver to the controller driver.
7−
8−1. Introduction
9−
10−Linux has a comprehensive PCI subsystem to support PCI controllers that
11−operates in Root Complex mode. The subsystem has capability to scan PCI bus,
12−assign memory resources and IRQ resources, load PCI driver (based on
13−vendor ID, device ID), support other services like hot-plug, power management,
14−advanced error reporting and virtual channels.
15−
16−However the PCI controller IP integrated in some SoCs is capable of operating
17−either in Root Complex mode or Endpoint mode. PCI Endpoint Framework will
18−add endpoint mode support in Linux. This will help to run Linux in an
19−EP system which can have a wide variety of use cases from testing or
20−validation, co-processor accelerator, etc.
21−
22−2. PCI Endpoint Core
23−
24−The PCI Endpoint Core layer comprises 3 components: the Endpoint Controller
25−library, the Endpoint Function library, and the configfs layer to bind the
26−endpoint function with the endpoint controller.
27−
28−2.1 PCI Endpoint Controller(EPC) Library
29−
30−The EPC library provides APIs to be used by the controller that can operate
31−in endpoint mode. It also provides APIs to be used by function driver/library
32−in order to implement a particular endpoint function.
33−
34−2.1.1 APIs for the PCI controller Driver
35−
36−This section lists the APIs that the PCI Endpoint core provides to be used
37−by the PCI controller driver.
38−
39−*) devm_pci_epc_create()/pci_epc_create()
40−
41− The PCI controller driver should implement the following ops:
42− * write_header: ops to populate configuration space header
43− * set_bar: ops to configure the BAR
44− * clear_bar: ops to reset the BAR
45− * alloc_addr_space: ops to allocate in PCI controller address space
46− * free_addr_space: ops to free the allocated address space
47− * raise_irq: ops to raise a legacy, MSI or MSI-X interrupt
48− * start: ops to start the PCI link
49− * stop: ops to stop the PCI link
50−
51− The PCI controller driver can then create a new EPC device by invoking
52− devm_pci_epc_create()/pci_epc_create().
53−
54−*) devm_pci_epc_destroy()/pci_epc_destroy()
55−
56− The PCI controller driver can destroy the EPC device created by either
57− devm_pci_epc_create() or pci_epc_create() using devm_pci_epc_destroy() or
58− pci_epc_destroy().
59−
60−*) pci_epc_linkup()
61−
62− In order to notify all the function devices that the EPC device to which
63− they are linked has established a link with the host, the PCI controller
64− driver should invoke pci_epc_linkup().
65−
66−*) pci_epc_mem_init()
67−
68− Initialize the pci_epc_mem structure used for allocating EPC addr space.
69−
70−*) pci_epc_mem_exit()
71−
72− Cleanup the pci_epc_mem structure allocated during pci_epc_mem_init().
73−
74−2.1.2 APIs for the PCI Endpoint Function Driver
75−
76−This section lists the APIs that the PCI Endpoint core provides to be used
77−by the PCI endpoint function driver.
78−
79−*) pci_epc_write_header()
80−
81− The PCI endpoint function driver should use pci_epc_write_header() to
82− write the standard configuration header to the endpoint controller.
83−
84−*) pci_epc_set_bar()
85−
86− The PCI endpoint function driver should use pci_epc_set_bar() to configure
87− the Base Address Register in order for the host to assign PCI addr space.
88− Register space of the function driver is usually configured
89− using this API.
90−
91−*) pci_epc_clear_bar()
92−
93− The PCI endpoint function driver should use pci_epc_clear_bar() to reset
94− the BAR.
95−
96−*) pci_epc_raise_irq()
97−
98− The PCI endpoint function driver should use pci_epc_raise_irq() to raise
99− Legacy Interrupt, MSI or MSI-X Interrupt.
100−
101−*) pci_epc_mem_alloc_addr()
102−
103− The PCI endpoint function driver should use pci_epc_mem_alloc_addr(), to
104− allocate memory address from EPC addr space which is required to access
105− RC's buffer
106−
107−*) pci_epc_mem_free_addr()
108−
109− The PCI endpoint function driver should use pci_epc_mem_free_addr() to
110− free the memory space allocated using pci_epc_mem_alloc_addr().
111−
112−2.1.3 Other APIs
113−
114−There are other APIs provided by the EPC library. These are used for binding
115−the EPF device with EPC device. pci-ep-cfs.c can be used as reference for
116−using these APIs.
117−
118−*) pci_epc_get()
119−
120− Get a reference to the PCI endpoint controller based on the device name of
121− the controller.
122−
123−*) pci_epc_put()
124−
125− Release the reference to the PCI endpoint controller obtained using
126− pci_epc_get()
127−
128−*) pci_epc_add_epf()
129−
130− Add a PCI endpoint function to a PCI endpoint controller. A PCIe device
131− can have up to 8 functions according to the specification.
132−
133−*) pci_epc_remove_epf()
134−
135− Remove the PCI endpoint function from PCI endpoint controller.
136−
137−*) pci_epc_start()
138−
139− The PCI endpoint function driver should invoke pci_epc_start() once it
140− has configured the endpoint function and wants to start the PCI link.
141−
142−*) pci_epc_stop()
143−
144− The PCI endpoint function driver should invoke pci_epc_stop() to stop
145− the PCI LINK.
146−
147−2.2 PCI Endpoint Function(EPF) Library
148−
149−The EPF library provides APIs to be used by the function driver and the EPC
150−library to provide endpoint mode functionality.
151−
152−2.2.1 APIs for the PCI Endpoint Function Driver
153−
154−This section lists the APIs that the PCI Endpoint core provides to be used
155−by the PCI endpoint function driver.
156−
157−*) pci_epf_register_driver()
158−
159− The PCI Endpoint Function driver should implement the following ops:
160− * bind: ops to perform when a EPC device has been bound to EPF device
161− * unbind: ops to perform when a binding has been lost between a EPC
162− device and EPF device
163− * linkup: ops to perform when the EPC device has established a
164− connection with a host system
165−
166− The PCI Function driver can then register the PCI EPF driver by using
167− pci_epf_register_driver().
168−
169−*) pci_epf_unregister_driver()
170−
171− The PCI Function driver can unregister the PCI EPF driver by using
172− pci_epf_unregister_driver().
173−
174−*) pci_epf_alloc_space()
175−
176− The PCI Function driver can allocate space for a particular BAR using
177− pci_epf_alloc_space().
178−
179−*) pci_epf_free_space()
180−
181− The PCI Function driver can free the allocated space
182− (using pci_epf_alloc_space) by invoking pci_epf_free_space().
183−
184−2.2.2 APIs for the PCI Endpoint Controller Library
185−This section lists the APIs that the PCI Endpoint core provides to be used
186−by the PCI endpoint controller library.
187−
188−*) pci_epf_linkup()
189−
190− The PCI endpoint controller library invokes pci_epf_linkup() when the
191− EPC device has established the connection to the host.
192−
193−2.2.2 Other APIs
194−There are other APIs provided by the EPF library. These are used to notify
195−the function driver when the EPF device is bound to the EPC device.
196−pci-ep-cfs.c can be used as reference for using these APIs.
197−
198−*) pci_epf_create()
199−
200− Create a new PCI EPF device by passing the name of the PCI EPF device.
201− This name will be used to bind the the EPF device to a EPF driver.
202−
203−*) pci_epf_destroy()
204−
205− Destroy the created PCI EPF device.
206−
207−*) pci_epf_bind()
208−
209− pci_epf_bind() should be invoked when the EPF device has been bound to
210− a EPC device.
211−
212−*) pci_epf_unbind()
213−
214− pci_epf_unbind() should be invoked when the binding between EPC device
215− and EPF device is lost.
Documentation/PCI/endpoint/pci-test-function.rst+103−0
@@ -0,0 +1,103 @@
1+.. SPDX-License-Identifier: GPL-2.0
2+
3+=================
4+PCI Test Function
5+=================
6+
7+:Author: Kishon Vijay Abraham I <kishon@ti.com>
8+
9+Traditionally PCI RC has always been validated by using standard
10+PCI cards like ethernet PCI cards or USB PCI cards or SATA PCI cards.
11+However with the addition of EP-core in linux kernel, it is possible
12+to configure a PCI controller that can operate in EP mode to work as
13+a test device.
14+
15+The PCI endpoint test device is a virtual device (defined in software)
16+used to test the endpoint functionality and serve as a sample driver
17+for other PCI endpoint devices (to use the EP framework).
18+
19+The PCI endpoint test device has the following registers:
20+
21+ 1) PCI_ENDPOINT_TEST_MAGIC
22+ 2) PCI_ENDPOINT_TEST_COMMAND
23+ 3) PCI_ENDPOINT_TEST_STATUS
24+ 4) PCI_ENDPOINT_TEST_SRC_ADDR
25+ 5) PCI_ENDPOINT_TEST_DST_ADDR
26+ 6) PCI_ENDPOINT_TEST_SIZE
27+ 7) PCI_ENDPOINT_TEST_CHECKSUM
28+ 8) PCI_ENDPOINT_TEST_IRQ_TYPE
29+ 9) PCI_ENDPOINT_TEST_IRQ_NUMBER
30+
31+* PCI_ENDPOINT_TEST_MAGIC
32+
33+This register will be used to test BAR0. A known pattern will be written
34+and read back from MAGIC register to verify BAR0.
35+
36+* PCI_ENDPOINT_TEST_COMMAND
37+
38+This register will be used by the host driver to indicate the function
39+that the endpoint device must perform.
40+
41+======== ================================================================
42+Bitfield Description
43+======== ================================================================
44+Bit 0 raise legacy IRQ
45+Bit 1 raise MSI IRQ
46+Bit 2 raise MSI-X IRQ
47+Bit 3 read command (read data from RC buffer)
48+Bit 4 write command (write data to RC buffer)
49+Bit 5 copy command (copy data from one RC buffer to another RC buffer)
50+======== ================================================================
51+
52+* PCI_ENDPOINT_TEST_STATUS
53+
54+This register reflects the status of the PCI endpoint device.
55+
56+======== ==============================
57+Bitfield Description
58+======== ==============================
59+Bit 0 read success
60+Bit 1 read fail
61+Bit 2 write success
62+Bit 3 write fail
63+Bit 4 copy success
64+Bit 5 copy fail
65+Bit 6 IRQ raised
66+Bit 7 source address is invalid
67+Bit 8 destination address is invalid
68+======== ==============================
69+
70+* PCI_ENDPOINT_TEST_SRC_ADDR
71+
72+This register contains the source address (RC buffer address) for the
73+COPY/READ command.
74+
75+* PCI_ENDPOINT_TEST_DST_ADDR
76+
77+This register contains the destination address (RC buffer address) for
78+the COPY/WRITE command.
79+
80+* PCI_ENDPOINT_TEST_IRQ_TYPE
81+
82+This register contains the interrupt type (Legacy/MSI) triggered
83+for the READ/WRITE/COPY and raise IRQ (Legacy/MSI) commands.
84+
85+Possible types:
86+
87+====== ==
88+Legacy 0
89+MSI 1
90+MSI-X 2
91+====== ==
92+
93+* PCI_ENDPOINT_TEST_IRQ_NUMBER
94+
95+This register contains the triggered ID interrupt.
96+
97+Admissible values:
98+
99+====== ===========
100+Legacy 0
101+MSI [1 .. 32]
102+MSI-X [1 .. 2048]
103+====== ===========
Documentation/PCI/endpoint/pci-test-function.txt+0−87
@@ -1,87 +0,0 @@
1− PCI TEST
2− Kishon Vijay Abraham I <kishon@ti.com>
3−
4−Traditionally PCI RC has always been validated by using standard
5−PCI cards like ethernet PCI cards or USB PCI cards or SATA PCI cards.
6−However with the addition of EP-core in linux kernel, it is possible
7−to configure a PCI controller that can operate in EP mode to work as
8−a test device.
9−
10−The PCI endpoint test device is a virtual device (defined in software)
11−used to test the endpoint functionality and serve as a sample driver
12−for other PCI endpoint devices (to use the EP framework).
13−
14−The PCI endpoint test device has the following registers:
15−
16− 1) PCI_ENDPOINT_TEST_MAGIC
17− 2) PCI_ENDPOINT_TEST_COMMAND
18− 3) PCI_ENDPOINT_TEST_STATUS
19− 4) PCI_ENDPOINT_TEST_SRC_ADDR
20− 5) PCI_ENDPOINT_TEST_DST_ADDR
21− 6) PCI_ENDPOINT_TEST_SIZE
22− 7) PCI_ENDPOINT_TEST_CHECKSUM
23− 8) PCI_ENDPOINT_TEST_IRQ_TYPE
24− 9) PCI_ENDPOINT_TEST_IRQ_NUMBER
25−
26−*) PCI_ENDPOINT_TEST_MAGIC
27−
28−This register will be used to test BAR0. A known pattern will be written
29−and read back from MAGIC register to verify BAR0.
30−
31−*) PCI_ENDPOINT_TEST_COMMAND:
32−
33−This register will be used by the host driver to indicate the function
34−that the endpoint device must perform.
35−
36−Bitfield Description:
37− Bit 0 : raise legacy IRQ
38− Bit 1 : raise MSI IRQ
39− Bit 2 : raise MSI-X IRQ
40− Bit 3 : read command (read data from RC buffer)
41− Bit 4 : write command (write data to RC buffer)
42− Bit 5 : copy command (copy data from one RC buffer to another
43− RC buffer)
44−
45−*) PCI_ENDPOINT_TEST_STATUS
46−
47−This register reflects the status of the PCI endpoint device.
48−
49−Bitfield Description:
50− Bit 0 : read success
51− Bit 1 : read fail
52− Bit 2 : write success
53− Bit 3 : write fail
54− Bit 4 : copy success
55− Bit 5 : copy fail
56− Bit 6 : IRQ raised
57− Bit 7 : source address is invalid
58− Bit 8 : destination address is invalid
59−
60−*) PCI_ENDPOINT_TEST_SRC_ADDR
61−
62−This register contains the source address (RC buffer address) for the
63−COPY/READ command.
64−
65−*) PCI_ENDPOINT_TEST_DST_ADDR
66−
67−This register contains the destination address (RC buffer address) for
68−the COPY/WRITE command.
69−
70−*) PCI_ENDPOINT_TEST_IRQ_TYPE
71−
72−This register contains the interrupt type (Legacy/MSI) triggered
73−for the READ/WRITE/COPY and raise IRQ (Legacy/MSI) commands.
74−
75−Possible types:
76− - Legacy : 0
77− - MSI : 1
78− - MSI-X : 2
79−
80−*) PCI_ENDPOINT_TEST_IRQ_NUMBER
81−
82−This register contains the triggered ID interrupt.
83−
84−Admissible values:
85− - Legacy : 0
86− - MSI : [1 .. 32]
87− - MSI-X : [1 .. 2048]
Documentation/PCI/endpoint/pci-test-howto.rst+235−0
@@ -0,0 +1,235 @@
1+.. SPDX-License-Identifier: GPL-2.0
2+
3+===================
4+PCI Test User Guide
5+===================
6+
7+:Author: Kishon Vijay Abraham I <kishon@ti.com>
8+
9+This document is a guide to help users use pci-epf-test function driver
10+and pci_endpoint_test host driver for testing PCI. The list of steps to
11+be followed in the host side and EP side is given below.
12+
13+Endpoint Device
14+===============
15+
16+Endpoint Controller Devices
17+---------------------------
18+
19+To find the list of endpoint controller devices in the system::
20+
21+ # ls /sys/class/pci_epc/
22+ 51000000.pcie_ep
23+
24+If PCI_ENDPOINT_CONFIGFS is enabled::
25+
26+ # ls /sys/kernel/config/pci_ep/controllers
27+ 51000000.pcie_ep
28+
29+
30+Endpoint Function Drivers
31+-------------------------
32+
33+To find the list of endpoint function drivers in the system::
34+
35+ # ls /sys/bus/pci-epf/drivers
36+ pci_epf_test
37+
38+If PCI_ENDPOINT_CONFIGFS is enabled::
39+
40+ # ls /sys/kernel/config/pci_ep/functions
41+ pci_epf_test
42+
43+
44+Creating pci-epf-test Device
45+----------------------------
46+
47+PCI endpoint function device can be created using the configfs. To create
48+pci-epf-test device, the following commands can be used::
49+
50+ # mount -t configfs none /sys/kernel/config
51+ # cd /sys/kernel/config/pci_ep/
52+ # mkdir functions/pci_epf_test/func1
53+
54+The "mkdir func1" above creates the pci-epf-test function device that will
55+be probed by pci_epf_test driver.
56+
57+The PCI endpoint framework populates the directory with the following
58+configurable fields::
59+
60+ # ls functions/pci_epf_test/func1
61+ baseclass_code interrupt_pin progif_code subsys_id
62+ cache_line_size msi_interrupts revid subsys_vendorid
63+ deviceid msix_interrupts subclass_code vendorid
64+
65+The PCI endpoint function driver populates these entries with default values
66+when the device is bound to the driver. The pci-epf-test driver populates
67+vendorid with 0xffff and interrupt_pin with 0x0001::
68+
69+ # cat functions/pci_epf_test/func1/vendorid
70+ 0xffff
71+ # cat functions/pci_epf_test/func1/interrupt_pin
72+ 0x0001
73+
74+
75+Configuring pci-epf-test Device
76+-------------------------------
77+
78+The user can configure the pci-epf-test device using configfs entry. In order
79+to change the vendorid and the number of MSI interrupts used by the function
80+device, the following commands can be used::
81+
82+ # echo 0x104c > functions/pci_epf_test/func1/vendorid
83+ # echo 0xb500 > functions/pci_epf_test/func1/deviceid
84+ # echo 16 > functions/pci_epf_test/func1/msi_interrupts
85+ # echo 8 > functions/pci_epf_test/func1/msix_interrupts
86+
87+
88+Binding pci-epf-test Device to EP Controller
89+--------------------------------------------
90+
91+In order for the endpoint function device to be useful, it has to be bound to
92+a PCI endpoint controller driver. Use the configfs to bind the function
93+device to one of the controller driver present in the system::
94+
95+ # ln -s functions/pci_epf_test/func1 controllers/51000000.pcie_ep/
96+
97+Once the above step is completed, the PCI endpoint is ready to establish a link
98+with the host.
99+
100+
101+Start the Link
102+--------------
103+
104+In order for the endpoint device to establish a link with the host, the _start_
105+field should be populated with '1'::
106+
107+ # echo 1 > controllers/51000000.pcie_ep/start
108+
109+
110+RootComplex Device
111+==================
112+
113+lspci Output
114+------------
115+
116+Note that the devices listed here correspond to the value populated in 1.4
117+above::
118+
119+ 00:00.0 PCI bridge: Texas Instruments Device 8888 (rev 01)
120+ 01:00.0 Unassigned class [ff00]: Texas Instruments Device b500
121+
122+
123+Using Endpoint Test function Device
124+-----------------------------------
125+
126+pcitest.sh added in tools/pci/ can be used to run all the default PCI endpoint
127+tests. To compile this tool the following commands should be used::
128+
129+ # cd <kernel-dir>
130+ # make -C tools/pci
131+
132+or if you desire to compile and install in your system::
133+
134+ # cd <kernel-dir>
135+ # make -C tools/pci install
136+
137+The tool and script will be located in <rootfs>/usr/bin/
138+
139+
140+pcitest.sh Output
141+~~~~~~~~~~~~~~~~~
142+::
143+
144+ # pcitest.sh
145+ BAR tests
146+
147+ BAR0: OKAY
148+ BAR1: OKAY
149+ BAR2: OKAY
150+ BAR3: OKAY
151+ BAR4: NOT OKAY
152+ BAR5: NOT OKAY
153+
154+ Interrupt tests
155+
156+ SET IRQ TYPE TO LEGACY: OKAY
157+ LEGACY IRQ: NOT OKAY
158+ SET IRQ TYPE TO MSI: OKAY
159+ MSI1: OKAY
160+ MSI2: OKAY
161+ MSI3: OKAY
162+ MSI4: OKAY
163+ MSI5: OKAY
164+ MSI6: OKAY
165+ MSI7: OKAY
166+ MSI8: OKAY
167+ MSI9: OKAY
168+ MSI10: OKAY
169+ MSI11: OKAY
170+ MSI12: OKAY
171+ MSI13: OKAY
172+ MSI14: OKAY
173+ MSI15: OKAY
174+ MSI16: OKAY
175+ MSI17: NOT OKAY
176+ MSI18: NOT OKAY
177+ MSI19: NOT OKAY
178+ MSI20: NOT OKAY
179+ MSI21: NOT OKAY
180+ MSI22: NOT OKAY
181+ MSI23: NOT OKAY
182+ MSI24: NOT OKAY
183+ MSI25: NOT OKAY
184+ MSI26: NOT OKAY
185+ MSI27: NOT OKAY
186+ MSI28: NOT OKAY
187+ MSI29: NOT OKAY
188+ MSI30: NOT OKAY
189+ MSI31: NOT OKAY
190+ MSI32: NOT OKAY
191+ SET IRQ TYPE TO MSI-X: OKAY
192+ MSI-X1: OKAY
193+ MSI-X2: OKAY
194+ MSI-X3: OKAY
195+ MSI-X4: OKAY
196+ MSI-X5: OKAY
197+ MSI-X6: OKAY
198+ MSI-X7: OKAY
199+ MSI-X8: OKAY
200+ MSI-X9: NOT OKAY
201+ MSI-X10: NOT OKAY
202+ MSI-X11: NOT OKAY
203+ MSI-X12: NOT OKAY
204+ MSI-X13: NOT OKAY
205+ MSI-X14: NOT OKAY
206+ MSI-X15: NOT OKAY
207+ MSI-X16: NOT OKAY
208+ [...]
209+ MSI-X2047: NOT OKAY
210+ MSI-X2048: NOT OKAY
211+
212+ Read Tests
213+
214+ SET IRQ TYPE TO MSI: OKAY
215+ READ ( 1 bytes): OKAY
216+ READ ( 1024 bytes): OKAY
217+ READ ( 1025 bytes): OKAY
218+ READ (1024000 bytes): OKAY
219+ READ (1024001 bytes): OKAY
220+
221+ Write Tests
222+
223+ WRITE ( 1 bytes): OKAY
224+ WRITE ( 1024 bytes): OKAY
225+ WRITE ( 1025 bytes): OKAY
226+ WRITE (1024000 bytes): OKAY
227+ WRITE (1024001 bytes): OKAY
228+
229+ Copy Tests
230+
231+ COPY ( 1 bytes): OKAY
232+ COPY ( 1024 bytes): OKAY
233+ COPY ( 1025 bytes): OKAY
234+ COPY (1024000 bytes): OKAY
235+ COPY (1024001 bytes): OKAY
Documentation/PCI/endpoint/pci-test-howto.txt+0−206
@@ -1,206 +0,0 @@
1− PCI TEST USERGUIDE
2− Kishon Vijay Abraham I <kishon@ti.com>
3−
4−This document is a guide to help users use pci-epf-test function driver
5−and pci_endpoint_test host driver for testing PCI. The list of steps to
6−be followed in the host side and EP side is given below.
7−
8−1. Endpoint Device
9−
10−1.1 Endpoint Controller Devices
11−
12−To find the list of endpoint controller devices in the system:
13−
14− # ls /sys/class/pci_epc/
15− 51000000.pcie_ep
16−
17−If PCI_ENDPOINT_CONFIGFS is enabled
18− # ls /sys/kernel/config/pci_ep/controllers
19− 51000000.pcie_ep
20−
21−1.2 Endpoint Function Drivers
22−
23−To find the list of endpoint function drivers in the system:
24−
25− # ls /sys/bus/pci-epf/drivers
26− pci_epf_test
27−
28−If PCI_ENDPOINT_CONFIGFS is enabled
29− # ls /sys/kernel/config/pci_ep/functions
30− pci_epf_test
31−
32−1.3 Creating pci-epf-test Device
33−
34−PCI endpoint function device can be created using the configfs. To create
35−pci-epf-test device, the following commands can be used
36−
37− # mount -t configfs none /sys/kernel/config
38− # cd /sys/kernel/config/pci_ep/
39− # mkdir functions/pci_epf_test/func1
40−
41−The "mkdir func1" above creates the pci-epf-test function device that will
42−be probed by pci_epf_test driver.
43−
44−The PCI endpoint framework populates the directory with the following
45−configurable fields.
46−
47− # ls functions/pci_epf_test/func1
48− baseclass_code interrupt_pin progif_code subsys_id
49− cache_line_size msi_interrupts revid subsys_vendorid
50− deviceid msix_interrupts subclass_code vendorid
51−
52−The PCI endpoint function driver populates these entries with default values
53−when the device is bound to the driver. The pci-epf-test driver populates
54−vendorid with 0xffff and interrupt_pin with 0x0001
55−
56− # cat functions/pci_epf_test/func1/vendorid
57− 0xffff
58− # cat functions/pci_epf_test/func1/interrupt_pin
59− 0x0001
60−
61−1.4 Configuring pci-epf-test Device
62−
63−The user can configure the pci-epf-test device using configfs entry. In order
64−to change the vendorid and the number of MSI interrupts used by the function
65−device, the following commands can be used.
66−
67− # echo 0x104c > functions/pci_epf_test/func1/vendorid
68− # echo 0xb500 > functions/pci_epf_test/func1/deviceid
69− # echo 16 > functions/pci_epf_test/func1/msi_interrupts
70− # echo 8 > functions/pci_epf_test/func1/msix_interrupts
71−
72−1.5 Binding pci-epf-test Device to EP Controller
73−
74−In order for the endpoint function device to be useful, it has to be bound to
75−a PCI endpoint controller driver. Use the configfs to bind the function
76−device to one of the controller driver present in the system.
77−
78− # ln -s functions/pci_epf_test/func1 controllers/51000000.pcie_ep/
79−
80−Once the above step is completed, the PCI endpoint is ready to establish a link
81−with the host.
82−
83−1.6 Start the Link
84−
85−In order for the endpoint device to establish a link with the host, the _start_
86−field should be populated with '1'.
87−
88− # echo 1 > controllers/51000000.pcie_ep/start
89−
90−2. RootComplex Device
91−
92−2.1 lspci Output
93−
94−Note that the devices listed here correspond to the value populated in 1.4 above
95−
96− 00:00.0 PCI bridge: Texas Instruments Device 8888 (rev 01)
97− 01:00.0 Unassigned class [ff00]: Texas Instruments Device b500
98−
99−2.2 Using Endpoint Test function Device
100−
101−pcitest.sh added in tools/pci/ can be used to run all the default PCI endpoint
102−tests. To compile this tool the following commands should be used:
103−
104− # cd <kernel-dir>
105− # make -C tools/pci
106−
107−or if you desire to compile and install in your system:
108−
109− # cd <kernel-dir>
110− # make -C tools/pci install
111−
112−The tool and script will be located in <rootfs>/usr/bin/
113−
114−2.2.1 pcitest.sh Output
115− # pcitest.sh
116− BAR tests
117−
118− BAR0: OKAY
119− BAR1: OKAY
120− BAR2: OKAY
121− BAR3: OKAY
122− BAR4: NOT OKAY
123− BAR5: NOT OKAY
124−
125− Interrupt tests
126−
127− SET IRQ TYPE TO LEGACY: OKAY
128− LEGACY IRQ: NOT OKAY
129− SET IRQ TYPE TO MSI: OKAY
130− MSI1: OKAY
131− MSI2: OKAY
132− MSI3: OKAY
133− MSI4: OKAY
134− MSI5: OKAY
135− MSI6: OKAY
136− MSI7: OKAY
137− MSI8: OKAY
138− MSI9: OKAY
139− MSI10: OKAY
140− MSI11: OKAY
141− MSI12: OKAY
142− MSI13: OKAY
143− MSI14: OKAY
144− MSI15: OKAY
145− MSI16: OKAY
146− MSI17: NOT OKAY
147− MSI18: NOT OKAY
148− MSI19: NOT OKAY
149− MSI20: NOT OKAY
150− MSI21: NOT OKAY
151− MSI22: NOT OKAY
152− MSI23: NOT OKAY
153− MSI24: NOT OKAY
154− MSI25: NOT OKAY
155− MSI26: NOT OKAY
156− MSI27: NOT OKAY
157− MSI28: NOT OKAY
158− MSI29: NOT OKAY
159− MSI30: NOT OKAY
160− MSI31: NOT OKAY
161− MSI32: NOT OKAY
162− SET IRQ TYPE TO MSI-X: OKAY
163− MSI-X1: OKAY
164− MSI-X2: OKAY
165− MSI-X3: OKAY
166− MSI-X4: OKAY
167− MSI-X5: OKAY
168− MSI-X6: OKAY
169− MSI-X7: OKAY
170− MSI-X8: OKAY
171− MSI-X9: NOT OKAY
172− MSI-X10: NOT OKAY
173− MSI-X11: NOT OKAY
174− MSI-X12: NOT OKAY
175− MSI-X13: NOT OKAY
176− MSI-X14: NOT OKAY
177− MSI-X15: NOT OKAY
178− MSI-X16: NOT OKAY
179− [...]
180− MSI-X2047: NOT OKAY
181− MSI-X2048: NOT OKAY
182−
183− Read Tests
184−
185− SET IRQ TYPE TO MSI: OKAY
186− READ ( 1 bytes): OKAY
187− READ ( 1024 bytes): OKAY
188− READ ( 1025 bytes): OKAY
189− READ (1024000 bytes): OKAY
190− READ (1024001 bytes): OKAY
191−
192− Write Tests
193−
194− WRITE ( 1 bytes): OKAY
195− WRITE ( 1024 bytes): OKAY
196− WRITE ( 1025 bytes): OKAY
197− WRITE (1024000 bytes): OKAY
198− WRITE (1024001 bytes): OKAY
199−
200− Copy Tests
201−
202− COPY ( 1 bytes): OKAY
203− COPY ( 1024 bytes): OKAY
204− COPY ( 1025 bytes): OKAY
205− COPY (1024000 bytes): OKAY
206− COPY (1024001 bytes): OKAY
Documentation/PCI/index.rst+18−0
@@ -0,0 +1,18 @@
1+.. SPDX-License-Identifier: GPL-2.0
2+
3+=======================
4+Linux PCI Bus Subsystem
5+=======================
6+
7+.. toctree::
8+ :maxdepth: 2
9+ :numbered:
10+
11+ pci
12+ picebus-howto
13+ pci-iov-howto
14+ msi-howto
15+ acpi-info
16+ pci-error-recovery
17+ pcieaer-howto
18+ endpoint/index
Documentation/PCI/msi-howto.rst+287−0
@@ -0,0 +1,287 @@
1+.. SPDX-License-Identifier: GPL-2.0
2+.. include:: <isonum.txt>
3+
4+==========================
5+The MSI Driver Guide HOWTO
6+==========================
7+
8+:Authors: Tom L Nguyen; Martine Silbermann; Matthew Wilcox
9+
10+:Copyright: 2003, 2008 Intel Corporation
11+
12+About this guide
13+================
14+
15+This guide describes the basics of Message Signaled Interrupts (MSIs),
16+the advantages of using MSI over traditional interrupt mechanisms, how
17+to change your driver to use MSI or MSI-X and some basic diagnostics to
18+try if a device doesn't support MSIs.
19+
20+
21+What are MSIs?
22+==============
23+
24+A Message Signaled Interrupt is a write from the device to a special
25+address which causes an interrupt to be received by the CPU.
26+
27+The MSI capability was first specified in PCI 2.2 and was later enhanced
28+in PCI 3.0 to allow each interrupt to be masked individually. The MSI-X
29+capability was also introduced with PCI 3.0. It supports more interrupts
30+per device than MSI and allows interrupts to be independently configured.
31+
32+Devices may support both MSI and MSI-X, but only one can be enabled at
33+a time.
34+
35+
36+Why use MSIs?
37+=============
38+
39+There are three reasons why using MSIs can give an advantage over
40+traditional pin-based interrupts.
41+
42+Pin-based PCI interrupts are often shared amongst several devices.
43+To support this, the kernel must call each interrupt handler associated
44+with an interrupt, which leads to reduced performance for the system as
45+a whole. MSIs are never shared, so this problem cannot arise.
46+
47+When a device writes data to memory, then raises a pin-based interrupt,
48+it is possible that the interrupt may arrive before all the data has
49+arrived in memory (this becomes more likely with devices behind PCI-PCI
50+bridges). In order to ensure that all the data has arrived in memory,
51+the interrupt handler must read a register on the device which raised
52+the interrupt. PCI transaction ordering rules require that all the data
53+arrive in memory before the value may be returned from the register.
54+Using MSIs avoids this problem as the interrupt-generating write cannot
55+pass the data writes, so by the time the interrupt is raised, the driver
56+knows that all the data has arrived in memory.
57+
58+PCI devices can only support a single pin-based interrupt per function.
59+Often drivers have to query the device to find out what event has
60+occurred, slowing down interrupt handling for the common case. With
61+MSIs, a device can support more interrupts, allowing each interrupt
62+to be specialised to a different purpose. One possible design gives
63+infrequent conditions (such as errors) their own interrupt which allows
64+the driver to handle the normal interrupt handling path more efficiently.
65+Other possible designs include giving one interrupt to each packet queue
66+in a network card or each port in a storage controller.
67+
68+
69+How to use MSIs
70+===============
71+
72+PCI devices are initialised to use pin-based interrupts. The device
73+driver has to set up the device to use MSI or MSI-X. Not all machines
74+support MSIs correctly, and for those machines, the APIs described below
75+will simply fail and the device will continue to use pin-based interrupts.
76+
77+Include kernel support for MSIs
78+-------------------------------
79+
80+To support MSI or MSI-X, the kernel must be built with the CONFIG_PCI_MSI
81+option enabled. This option is only available on some architectures,
82+and it may depend on some other options also being set. For example,
83+on x86, you must also enable X86_UP_APIC or SMP in order to see the
84+CONFIG_PCI_MSI option.
85+
86+Using MSI
87+---------
88+
89+Most of the hard work is done for the driver in the PCI layer. The driver
90+simply has to request that the PCI layer set up the MSI capability for this
91+device.
92+
93+To automatically use MSI or MSI-X interrupt vectors, use the following
94+function::
95+
96+ int pci_alloc_irq_vectors(struct pci_dev *dev, unsigned int min_vecs,
97+ unsigned int max_vecs, unsigned int flags);
98+
99+which allocates up to max_vecs interrupt vectors for a PCI device. It
100+returns the number of vectors allocated or a negative error. If the device
101+has a requirements for a minimum number of vectors the driver can pass a
102+min_vecs argument set to this limit, and the PCI core will return -ENOSPC
103+if it can't meet the minimum number of vectors.
104+
105+The flags argument is used to specify which type of interrupt can be used
106+by the device and the driver (PCI_IRQ_LEGACY, PCI_IRQ_MSI, PCI_IRQ_MSIX).
107+A convenient short-hand (PCI_IRQ_ALL_TYPES) is also available to ask for
108+any possible kind of interrupt. If the PCI_IRQ_AFFINITY flag is set,
109+pci_alloc_irq_vectors() will spread the interrupts around the available CPUs.
110+
111+To get the Linux IRQ numbers passed to request_irq() and free_irq() and the
112+vectors, use the following function::
113+
114+ int pci_irq_vector(struct pci_dev *dev, unsigned int nr);
115+
116+Any allocated resources should be freed before removing the device using
117+the following function::
118+
119+ void pci_free_irq_vectors(struct pci_dev *dev);
120+
121+If a device supports both MSI-X and MSI capabilities, this API will use the
122+MSI-X facilities in preference to the MSI facilities. MSI-X supports any
123+number of interrupts between 1 and 2048. In contrast, MSI is restricted to
124+a maximum of 32 interrupts (and must be a power of two). In addition, the
125+MSI interrupt vectors must be allocated consecutively, so the system might
126+not be able to allocate as many vectors for MSI as it could for MSI-X. On
127+some platforms, MSI interrupts must all be targeted at the same set of CPUs
128+whereas MSI-X interrupts can all be targeted at different CPUs.
129+
130+If a device supports neither MSI-X or MSI it will fall back to a single
131+legacy IRQ vector.
132+
133+The typical usage of MSI or MSI-X interrupts is to allocate as many vectors
134+as possible, likely up to the limit supported by the device. If nvec is
135+larger than the number supported by the device it will automatically be
136+capped to the supported limit, so there is no need to query the number of
137+vectors supported beforehand::
138+
139+ nvec = pci_alloc_irq_vectors(pdev, 1, nvec, PCI_IRQ_ALL_TYPES)
140+ if (nvec < 0)
141+ goto out_err;
142+
143+If a driver is unable or unwilling to deal with a variable number of MSI
144+interrupts it can request a particular number of interrupts by passing that
145+number to pci_alloc_irq_vectors() function as both 'min_vecs' and
146+'max_vecs' parameters::
147+
148+ ret = pci_alloc_irq_vectors(pdev, nvec, nvec, PCI_IRQ_ALL_TYPES);
149+ if (ret < 0)
150+ goto out_err;
151+
152+The most notorious example of the request type described above is enabling
153+the single MSI mode for a device. It could be done by passing two 1s as
154+'min_vecs' and 'max_vecs'::
155+
156+ ret = pci_alloc_irq_vectors(pdev, 1, 1, PCI_IRQ_ALL_TYPES);
157+ if (ret < 0)
158+ goto out_err;
159+
160+Some devices might not support using legacy line interrupts, in which case
161+the driver can specify that only MSI or MSI-X is acceptable::
162+
163+ nvec = pci_alloc_irq_vectors(pdev, 1, nvec, PCI_IRQ_MSI | PCI_IRQ_MSIX);
164+ if (nvec < 0)
165+ goto out_err;
166+
167+Legacy APIs
168+-----------
169+
170+The following old APIs to enable and disable MSI or MSI-X interrupts should
171+not be used in new code::
172+
173+ pci_enable_msi() /* deprecated */
174+ pci_disable_msi() /* deprecated */
175+ pci_enable_msix_range() /* deprecated */
176+ pci_enable_msix_exact() /* deprecated */
177+ pci_disable_msix() /* deprecated */
178+
179+Additionally there are APIs to provide the number of supported MSI or MSI-X
180+vectors: pci_msi_vec_count() and pci_msix_vec_count(). In general these
181+should be avoided in favor of letting pci_alloc_irq_vectors() cap the
182+number of vectors. If you have a legitimate special use case for the count
183+of vectors we might have to revisit that decision and add a
184+pci_nr_irq_vectors() helper that handles MSI and MSI-X transparently.
185+
186+Considerations when using MSIs
187+------------------------------
188+
189+Spinlocks
190+~~~~~~~~~
191+
192+Most device drivers have a per-device spinlock which is taken in the
193+interrupt handler. With pin-based interrupts or a single MSI, it is not
194+necessary to disable interrupts (Linux guarantees the same interrupt will
195+not be re-entered). If a device uses multiple interrupts, the driver
196+must disable interrupts while the lock is held. If the device sends
197+a different interrupt, the driver will deadlock trying to recursively
198+acquire the spinlock. Such deadlocks can be avoided by using
199+spin_lock_irqsave() or spin_lock_irq() which disable local interrupts
200+and acquire the lock (see Documentation/kernel-hacking/locking.rst).
201+
202+How to tell whether MSI/MSI-X is enabled on a device
203+----------------------------------------------------
204+
205+Using 'lspci -v' (as root) may show some devices with "MSI", "Message
206+Signalled Interrupts" or "MSI-X" capabilities. Each of these capabilities
207+has an 'Enable' flag which is followed with either "+" (enabled)
208+or "-" (disabled).
209+
210+
211+MSI quirks
212+==========
213+
214+Several PCI chipsets or devices are known not to support MSIs.
215+The PCI stack provides three ways to disable MSIs:
216+
217+1. globally
218+2. on all devices behind a specific bridge
219+3. on a single device
220+
221+Disabling MSIs globally
222+-----------------------
223+
224+Some host chipsets simply don't support MSIs properly. If we're
225+lucky, the manufacturer knows this and has indicated it in the ACPI
226+FADT table. In this case, Linux automatically disables MSIs.
227+Some boards don't include this information in the table and so we have
228+to detect them ourselves. The complete list of these is found near the
229+quirk_disable_all_msi() function in drivers/pci/quirks.c.
230+
231+If you have a board which has problems with MSIs, you can pass pci=nomsi
232+on the kernel command line to disable MSIs on all devices. It would be
233+in your best interests to report the problem to linux-pci@vger.kernel.org
234+including a full 'lspci -v' so we can add the quirks to the kernel.
235+
236+Disabling MSIs below a bridge
237+-----------------------------
238+
239+Some PCI bridges are not able to route MSIs between busses properly.
240+In this case, MSIs must be disabled on all devices behind the bridge.
241+
242+Some bridges allow you to enable MSIs by changing some bits in their
243+PCI configuration space (especially the Hypertransport chipsets such
244+as the nVidia nForce and Serverworks HT2000). As with host chipsets,
245+Linux mostly knows about them and automatically enables MSIs if it can.
246+If you have a bridge unknown to Linux, you can enable
247+MSIs in configuration space using whatever method you know works, then
248+enable MSIs on that bridge by doing::
249+
250+ echo 1 > /sys/bus/pci/devices/$bridge/msi_bus
251+
252+where $bridge is the PCI address of the bridge you've enabled (eg
253+0000:00:0e.0).
254+
255+To disable MSIs, echo 0 instead of 1. Changing this value should be
256+done with caution as it could break interrupt handling for all devices
257+below this bridge.
258+
259+Again, please notify linux-pci@vger.kernel.org of any bridges that need
260+special handling.
261+
262+Disabling MSIs on a single device
263+---------------------------------
264+
265+Some devices are known to have faulty MSI implementations. Usually this
266+is handled in the individual device driver, but occasionally it's necessary
267+to handle this with a quirk. Some drivers have an option to disable use
268+of MSI. While this is a convenient workaround for the driver author,
269+it is not good practice, and should not be emulated.
270+
271+Finding why MSIs are disabled on a device
272+-----------------------------------------
273+
274+From the above three sections, you can see that there are many reasons
275+why MSIs may not be enabled for a given device. Your first step should
276+be to examine your dmesg carefully to determine whether MSIs are enabled
277+for your machine. You should also check your .config to be sure you
278+have enabled CONFIG_PCI_MSI.
279+
280+Then, 'lspci -t' gives the list of bridges above a device. Reading
281+`/sys/bus/pci/devices/*/msi_bus` will tell you whether MSIs are enabled (1)
282+or disabled (0). If 0 is found in any of the msi_bus files belonging
283+to bridges between the PCI root and the device, MSIs are disabled.
284+
285+It is also worth checking the device driver to see whether it supports MSIs.
286+For example, it may contain calls to pci_irq_alloc_vectors() with the
287+PCI_IRQ_MSI or PCI_IRQ_MSIX flags.
Documentation/PCI/pci-error-recovery.rst+427−0
@@ -0,0 +1,427 @@
1+.. SPDX-License-Identifier: GPL-2.0
2+
3+==================
4+PCI Error Recovery
5+==================
6+
7+
8+:Authors: - Linas Vepstas <linasvepstas@gmail.com>
9+ - Richard Lary <rlary@us.ibm.com>
10+ - Mike Mason <mmlnx@us.ibm.com>
11+
12+
13+Many PCI bus controllers are able to detect a variety of hardware
14+PCI errors on the bus, such as parity errors on the data and address
15+buses, as well as SERR and PERR errors. Some of the more advanced
16+chipsets are able to deal with these errors; these include PCI-E chipsets,
17+and the PCI-host bridges found on IBM Power4, Power5 and Power6-based
18+pSeries boxes. A typical action taken is to disconnect the affected device,
19+halting all I/O to it. The goal of a disconnection is to avoid system
20+corruption; for example, to halt system memory corruption due to DMA's
21+to "wild" addresses. Typically, a reconnection mechanism is also
22+offered, so that the affected PCI device(s) are reset and put back
23+into working condition. The reset phase requires coordination
24+between the affected device drivers and the PCI controller chip.
25+This document describes a generic API for notifying device drivers
26+of a bus disconnection, and then performing error recovery.
27+This API is currently implemented in the 2.6.16 and later kernels.
28+
29+Reporting and recovery is performed in several steps. First, when
30+a PCI hardware error has resulted in a bus disconnect, that event
31+is reported as soon as possible to all affected device drivers,
32+including multiple instances of a device driver on multi-function
33+cards. This allows device drivers to avoid deadlocking in spinloops,
34+waiting for some i/o-space register to change, when it never will.
35+It also gives the drivers a chance to defer incoming I/O as
36+needed.
37+
38+Next, recovery is performed in several stages. Most of the complexity
39+is forced by the need to handle multi-function devices, that is,
40+devices that have multiple device drivers associated with them.
41+In the first stage, each driver is allowed to indicate what type
42+of reset it desires, the choices being a simple re-enabling of I/O
43+or requesting a slot reset.
44+
45+If any driver requests a slot reset, that is what will be done.
46+
47+After a reset and/or a re-enabling of I/O, all drivers are
48+again notified, so that they may then perform any device setup/config
49+that may be required. After these have all completed, a final
50+"resume normal operations" event is sent out.
51+
52+The biggest reason for choosing a kernel-based implementation rather
53+than a user-space implementation was the need to deal with bus
54+disconnects of PCI devices attached to storage media, and, in particular,
55+disconnects from devices holding the root file system. If the root
56+file system is disconnected, a user-space mechanism would have to go
57+through a large number of contortions to complete recovery. Almost all
58+of the current Linux file systems are not tolerant of disconnection
59+from/reconnection to their underlying block device. By contrast,
60+bus errors are easy to manage in the device driver. Indeed, most
61+device drivers already handle very similar recovery procedures;
62+for example, the SCSI-generic layer already provides significant
63+mechanisms for dealing with SCSI bus errors and SCSI bus resets.
64+
65+
66+Detailed Design
67+===============
68+
69+Design and implementation details below, based on a chain of
70+public email discussions with Ben Herrenschmidt, circa 5 April 2005.
71+
72+The error recovery API support is exposed to the driver in the form of
73+a structure of function pointers pointed to by a new field in struct
74+pci_driver. A driver that fails to provide the structure is "non-aware",
75+and the actual recovery steps taken are platform dependent. The
76+arch/powerpc implementation will simulate a PCI hotplug remove/add.
77+
78+This structure has the form::
79+
80+ struct pci_error_handlers
81+ {
82+ int (*error_detected)(struct pci_dev *dev, enum pci_channel_state);
83+ int (*mmio_enabled)(struct pci_dev *dev);
84+ int (*slot_reset)(struct pci_dev *dev);
85+ void (*resume)(struct pci_dev *dev);
86+ };
87+
88+The possible channel states are::
89+
90+ enum pci_channel_state {
91+ pci_channel_io_normal, /* I/O channel is in normal state */
92+ pci_channel_io_frozen, /* I/O to channel is blocked */
93+ pci_channel_io_perm_failure, /* PCI card is dead */
94+ };
95+
96+Possible return values are::
97+
98+ enum pci_ers_result {
99+ PCI_ERS_RESULT_NONE, /* no result/none/not supported in device driver */
100+ PCI_ERS_RESULT_CAN_RECOVER, /* Device driver can recover without slot reset */
101+ PCI_ERS_RESULT_NEED_RESET, /* Device driver wants slot to be reset. */
102+ PCI_ERS_RESULT_DISCONNECT, /* Device has completely failed, is unrecoverable */
103+ PCI_ERS_RESULT_RECOVERED, /* Device driver is fully recovered and operational */
104+ };
105+
106+A driver does not have to implement all of these callbacks; however,
107+if it implements any, it must implement error_detected(). If a callback
108+is not implemented, the corresponding feature is considered unsupported.
109+For example, if mmio_enabled() and resume() aren't there, then it
110+is assumed that the driver is not doing any direct recovery and requires
111+a slot reset. Typically a driver will want to know about
112+a slot_reset().
113+
114+The actual steps taken by a platform to recover from a PCI error
115+event will be platform-dependent, but will follow the general
116+sequence described below.
117+
118+STEP 0: Error Event
119+-------------------
120+A PCI bus error is detected by the PCI hardware. On powerpc, the slot
121+is isolated, in that all I/O is blocked: all reads return 0xffffffff,
122+all writes are ignored.
123+
124+
125+STEP 1: Notification
126+--------------------
127+Platform calls the error_detected() callback on every instance of
128+every driver affected by the error.
129+
130+At this point, the device might not be accessible anymore, depending on
131+the platform (the slot will be isolated on powerpc). The driver may
132+already have "noticed" the error because of a failing I/O, but this
133+is the proper "synchronization point", that is, it gives the driver
134+a chance to cleanup, waiting for pending stuff (timers, whatever, etc...)
135+to complete; it can take semaphores, schedule, etc... everything but
136+touch the device. Within this function and after it returns, the driver
137+shouldn't do any new IOs. Called in task context. This is sort of a
138+"quiesce" point. See note about interrupts at the end of this doc.
139+
140+All drivers participating in this system must implement this call.
141+The driver must return one of the following result codes:
142+
143+ - PCI_ERS_RESULT_CAN_RECOVER
144+ Driver returns this if it thinks it might be able to recover
145+ the HW by just banging IOs or if it wants to be given
146+ a chance to extract some diagnostic information (see
147+ mmio_enable, below).
148+ - PCI_ERS_RESULT_NEED_RESET
149+ Driver returns this if it can't recover without a
150+ slot reset.
151+ - PCI_ERS_RESULT_DISCONNECT
152+ Driver returns this if it doesn't want to recover at all.
153+
154+The next step taken will depend on the result codes returned by the
155+drivers.
156+
157+If all drivers on the segment/slot return PCI_ERS_RESULT_CAN_RECOVER,
158+then the platform should re-enable IOs on the slot (or do nothing in
159+particular, if the platform doesn't isolate slots), and recovery
160+proceeds to STEP 2 (MMIO Enable).
161+
162+If any driver requested a slot reset (by returning PCI_ERS_RESULT_NEED_RESET),
163+then recovery proceeds to STEP 4 (Slot Reset).
164+
165+If the platform is unable to recover the slot, the next step
166+is STEP 6 (Permanent Failure).
167+
168+.. note::
169+
170+ The current powerpc implementation assumes that a device driver will
171+ *not* schedule or semaphore in this routine; the current powerpc
172+ implementation uses one kernel thread to notify all devices;
173+ thus, if one device sleeps/schedules, all devices are affected.
174+ Doing better requires complex multi-threaded logic in the error
175+ recovery implementation (e.g. waiting for all notification threads
176+ to "join" before proceeding with recovery.) This seems excessively
177+ complex and not worth implementing.
178+
179+ The current powerpc implementation doesn't much care if the device
180+ attempts I/O at this point, or not. I/O's will fail, returning
181+ a value of 0xff on read, and writes will be dropped. If more than
182+ EEH_MAX_FAILS I/O's are attempted to a frozen adapter, EEH
183+ assumes that the device driver has gone into an infinite loop
184+ and prints an error to syslog. A reboot is then required to
185+ get the device working again.
186+
187+STEP 2: MMIO Enabled
188+--------------------
189+The platform re-enables MMIO to the device (but typically not the
190+DMA), and then calls the mmio_enabled() callback on all affected
191+device drivers.
192+
193+This is the "early recovery" call. IOs are allowed again, but DMA is
194+not, with some restrictions. This is NOT a callback for the driver to
195+start operations again, only to peek/poke at the device, extract diagnostic
196+information, if any, and eventually do things like trigger a device local
197+reset or some such, but not restart operations. This callback is made if
198+all drivers on a segment agree that they can try to recover and if no automatic
199+link reset was performed by the HW. If the platform can't just re-enable IOs
200+without a slot reset or a link reset, it will not call this callback, and
201+instead will have gone directly to STEP 3 (Link Reset) or STEP 4 (Slot Reset)
202+
203+.. note::
204+
205+ The following is proposed; no platform implements this yet:
206+ Proposal: All I/O's should be done _synchronously_ from within
207+ this callback, errors triggered by them will be returned via
208+ the normal pci_check_whatever() API, no new error_detected()
209+ callback will be issued due to an error happening here. However,
210+ such an error might cause IOs to be re-blocked for the whole
211+ segment, and thus invalidate the recovery that other devices
212+ on the same segment might have done, forcing the whole segment
213+ into one of the next states, that is, link reset or slot reset.
214+
215+The driver should return one of the following result codes:
216+ - PCI_ERS_RESULT_RECOVERED
217+ Driver returns this if it thinks the device is fully
218+ functional and thinks it is ready to start
219+ normal driver operations again. There is no
220+ guarantee that the driver will actually be
221+ allowed to proceed, as another driver on the
222+ same segment might have failed and thus triggered a
223+ slot reset on platforms that support it.
224+
225+ - PCI_ERS_RESULT_NEED_RESET
226+ Driver returns this if it thinks the device is not
227+ recoverable in its current state and it needs a slot
228+ reset to proceed.
229+
230+ - PCI_ERS_RESULT_DISCONNECT
231+ Same as above. Total failure, no recovery even after
232+ reset driver dead. (To be defined more precisely)
233+
234+The next step taken depends on the results returned by the drivers.
235+If all drivers returned PCI_ERS_RESULT_RECOVERED, then the platform
236+proceeds to either STEP3 (Link Reset) or to STEP 5 (Resume Operations).
237+
238+If any driver returned PCI_ERS_RESULT_NEED_RESET, then the platform
239+proceeds to STEP 4 (Slot Reset)
240+
241+STEP 3: Link Reset
242+------------------
243+The platform resets the link. This is a PCI-Express specific step
244+and is done whenever a fatal error has been detected that can be
245+"solved" by resetting the link.
246+
247+STEP 4: Slot Reset
248+------------------
249+
250+In response to a return value of PCI_ERS_RESULT_NEED_RESET, the
251+the platform will perform a slot reset on the requesting PCI device(s).
252+The actual steps taken by a platform to perform a slot reset
253+will be platform-dependent. Upon completion of slot reset, the
254+platform will call the device slot_reset() callback.
255+
256+Powerpc platforms implement two levels of slot reset:
257+soft reset(default) and fundamental(optional) reset.
258+
259+Powerpc soft reset consists of asserting the adapter #RST line and then
260+restoring the PCI BAR's and PCI configuration header to a state
261+that is equivalent to what it would be after a fresh system
262+power-on followed by power-on BIOS/system firmware initialization.
263+Soft reset is also known as hot-reset.
264+
265+Powerpc fundamental reset is supported by PCI Express cards only
266+and results in device's state machines, hardware logic, port states and
267+configuration registers to initialize to their default conditions.
268+
269+For most PCI devices, a soft reset will be sufficient for recovery.
270+Optional fundamental reset is provided to support a limited number
271+of PCI Express devices for which a soft reset is not sufficient
272+for recovery.
273+
274+If the platform supports PCI hotplug, then the reset might be
275+performed by toggling the slot electrical power off/on.
276+
277+It is important for the platform to restore the PCI config space
278+to the "fresh poweron" state, rather than the "last state". After
279+a slot reset, the device driver will almost always use its standard
280+device initialization routines, and an unusual config space setup
281+may result in hung devices, kernel panics, or silent data corruption.
282+
283+This call gives drivers the chance to re-initialize the hardware
284+(re-download firmware, etc.). At this point, the driver may assume
285+that the card is in a fresh state and is fully functional. The slot
286+is unfrozen and the driver has full access to PCI config space,
287+memory mapped I/O space and DMA. Interrupts (Legacy, MSI, or MSI-X)
288+will also be available.
289+
290+Drivers should not restart normal I/O processing operations
291+at this point. If all device drivers report success on this
292+callback, the platform will call resume() to complete the sequence,
293+and let the driver restart normal I/O processing.
294+
295+A driver can still return a critical failure for this function if
296+it can't get the device operational after reset. If the platform
297+previously tried a soft reset, it might now try a hard reset (power
298+cycle) and then call slot_reset() again. It the device still can't
299+be recovered, there is nothing more that can be done; the platform
300+will typically report a "permanent failure" in such a case. The
301+device will be considered "dead" in this case.
302+
303+Drivers for multi-function cards will need to coordinate among
304+themselves as to which driver instance will perform any "one-shot"
305+or global device initialization. For example, the Symbios sym53cxx2
306+driver performs device init only from PCI function 0::
307+
308+ + if (PCI_FUNC(pdev->devfn) == 0)
309+ + sym_reset_scsi_bus(np, 0);
310+
311+Result codes:
312+ - PCI_ERS_RESULT_DISCONNECT
313+ Same as above.
314+
315+Drivers for PCI Express cards that require a fundamental reset must
316+set the needs_freset bit in the pci_dev structure in their probe function.
317+For example, the QLogic qla2xxx driver sets the needs_freset bit for certain
318+PCI card types::
319+
320+ + /* Set EEH reset type to fundamental if required by hba */
321+ + if (IS_QLA24XX(ha) || IS_QLA25XX(ha) || IS_QLA81XX(ha))
322+ + pdev->needs_freset = 1;
323+ +
324+
325+Platform proceeds either to STEP 5 (Resume Operations) or STEP 6 (Permanent
326+Failure).
327+
328+.. note::
329+
330+ The current powerpc implementation does not try a power-cycle
331+ reset if the driver returned PCI_ERS_RESULT_DISCONNECT.
332+ However, it probably should.
333+
334+
335+STEP 5: Resume Operations
336+-------------------------
337+The platform will call the resume() callback on all affected device
338+drivers if all drivers on the segment have returned
339+PCI_ERS_RESULT_RECOVERED from one of the 3 previous callbacks.
340+The goal of this callback is to tell the driver to restart activity,
341+that everything is back and running. This callback does not return
342+a result code.
343+
344+At this point, if a new error happens, the platform will restart
345+a new error recovery sequence.
346+
347+STEP 6: Permanent Failure
348+-------------------------
349+A "permanent failure" has occurred, and the platform cannot recover
350+the device. The platform will call error_detected() with a
351+pci_channel_state value of pci_channel_io_perm_failure.
352+
353+The device driver should, at this point, assume the worst. It should
354+cancel all pending I/O, refuse all new I/O, returning -EIO to
355+higher layers. The device driver should then clean up all of its
356+memory and remove itself from kernel operations, much as it would
357+during system shutdown.
358+
359+The platform will typically notify the system operator of the
360+permanent failure in some way. If the device is hotplug-capable,
361+the operator will probably want to remove and replace the device.
362+Note, however, not all failures are truly "permanent". Some are
363+caused by over-heating, some by a poorly seated card. Many
364+PCI error events are caused by software bugs, e.g. DMA's to
365+wild addresses or bogus split transactions due to programming
366+errors. See the discussion in powerpc/eeh-pci-error-recovery.txt
367+for additional detail on real-life experience of the causes of
368+software errors.
369+
370+
371+Conclusion; General Remarks
372+---------------------------
373+The way the callbacks are called is platform policy. A platform with
374+no slot reset capability may want to just "ignore" drivers that can't
375+recover (disconnect them) and try to let other cards on the same segment
376+recover. Keep in mind that in most real life cases, though, there will
377+be only one driver per segment.
378+
379+Now, a note about interrupts. If you get an interrupt and your
380+device is dead or has been isolated, there is a problem :)
381+The current policy is to turn this into a platform policy.
382+That is, the recovery API only requires that:
383+
384+ - There is no guarantee that interrupt delivery can proceed from any
385+ device on the segment starting from the error detection and until the
386+ slot_reset callback is called, at which point interrupts are expected
387+ to be fully operational.
388+
389+ - There is no guarantee that interrupt delivery is stopped, that is,
390+ a driver that gets an interrupt after detecting an error, or that detects
391+ an error within the interrupt handler such that it prevents proper
392+ ack'ing of the interrupt (and thus removal of the source) should just
393+ return IRQ_NOTHANDLED. It's up to the platform to deal with that
394+ condition, typically by masking the IRQ source during the duration of
395+ the error handling. It is expected that the platform "knows" which
396+ interrupts are routed to error-management capable slots and can deal
397+ with temporarily disabling that IRQ number during error processing (this
398+ isn't terribly complex). That means some IRQ latency for other devices
399+ sharing the interrupt, but there is simply no other way. High end
400+ platforms aren't supposed to share interrupts between many devices
401+ anyway :)
402+
403+.. note::
404+
405+ Implementation details for the powerpc platform are discussed in
406+ the file Documentation/powerpc/eeh-pci-error-recovery.rst
407+
408+ As of this writing, there is a growing list of device drivers with
409+ patches implementing error recovery. Not all of these patches are in
410+ mainline yet. These may be used as "examples":
411+
412+ - drivers/scsi/ipr
413+ - drivers/scsi/sym53c8xx_2
414+ - drivers/scsi/qla2xxx
415+ - drivers/scsi/lpfc
416+ - drivers/next/bnx2.c
417+ - drivers/next/e100.c
418+ - drivers/net/e1000
419+ - drivers/net/e1000e
420+ - drivers/net/ixgb
421+ - drivers/net/ixgbe
422+ - drivers/net/cxgb3
423+ - drivers/net/s2io.c
424+ - drivers/net/qlge
425+
426+The End
427+-------
Documentation/PCI/pci-error-recovery.txt+0−413
@@ -1,413 +0,0 @@
1−
2− PCI Error Recovery
3− ------------------
4− February 2, 2006
5−
6− Current document maintainer:
7− Linas Vepstas <linasvepstas@gmail.com>
8− updated by Richard Lary <rlary@us.ibm.com>
9− and Mike Mason <mmlnx@us.ibm.com> on 27-Jul-2009
10−
11−
12−Many PCI bus controllers are able to detect a variety of hardware
13−PCI errors on the bus, such as parity errors on the data and address
14−buses, as well as SERR and PERR errors. Some of the more advanced
15−chipsets are able to deal with these errors; these include PCI-E chipsets,
16−and the PCI-host bridges found on IBM Power4, Power5 and Power6-based
17−pSeries boxes. A typical action taken is to disconnect the affected device,
18−halting all I/O to it. The goal of a disconnection is to avoid system
19−corruption; for example, to halt system memory corruption due to DMA's
20−to "wild" addresses. Typically, a reconnection mechanism is also
21−offered, so that the affected PCI device(s) are reset and put back
22−into working condition. The reset phase requires coordination
23−between the affected device drivers and the PCI controller chip.
24−This document describes a generic API for notifying device drivers
25−of a bus disconnection, and then performing error recovery.
26−This API is currently implemented in the 2.6.16 and later kernels.
27−
28−Reporting and recovery is performed in several steps. First, when
29−a PCI hardware error has resulted in a bus disconnect, that event
30−is reported as soon as possible to all affected device drivers,
31−including multiple instances of a device driver on multi-function
32−cards. This allows device drivers to avoid deadlocking in spinloops,
33−waiting for some i/o-space register to change, when it never will.
34−It also gives the drivers a chance to defer incoming I/O as
35−needed.
36−
37−Next, recovery is performed in several stages. Most of the complexity
38−is forced by the need to handle multi-function devices, that is,
39−devices that have multiple device drivers associated with them.
40−In the first stage, each driver is allowed to indicate what type
41−of reset it desires, the choices being a simple re-enabling of I/O
42−or requesting a slot reset.
43−
44−If any driver requests a slot reset, that is what will be done.
45−
46−After a reset and/or a re-enabling of I/O, all drivers are
47−again notified, so that they may then perform any device setup/config
48−that may be required. After these have all completed, a final
49−"resume normal operations" event is sent out.
50−
51−The biggest reason for choosing a kernel-based implementation rather
52−than a user-space implementation was the need to deal with bus
53−disconnects of PCI devices attached to storage media, and, in particular,
54−disconnects from devices holding the root file system. If the root
55−file system is disconnected, a user-space mechanism would have to go
56−through a large number of contortions to complete recovery. Almost all
57−of the current Linux file systems are not tolerant of disconnection
58−from/reconnection to their underlying block device. By contrast,
59−bus errors are easy to manage in the device driver. Indeed, most
60−device drivers already handle very similar recovery procedures;
61−for example, the SCSI-generic layer already provides significant
62−mechanisms for dealing with SCSI bus errors and SCSI bus resets.
63−
64−
65−Detailed Design
66−---------------
67−Design and implementation details below, based on a chain of
68−public email discussions with Ben Herrenschmidt, circa 5 April 2005.
69−
70−The error recovery API support is exposed to the driver in the form of
71−a structure of function pointers pointed to by a new field in struct
72−pci_driver. A driver that fails to provide the structure is "non-aware",
73−and the actual recovery steps taken are platform dependent. The
74−arch/powerpc implementation will simulate a PCI hotplug remove/add.
75−
76−This structure has the form:
77−struct pci_error_handlers
78−{
79− int (*error_detected)(struct pci_dev *dev, enum pci_channel_state);
80− int (*mmio_enabled)(struct pci_dev *dev);
81− int (*slot_reset)(struct pci_dev *dev);
82− void (*resume)(struct pci_dev *dev);
83−};
84−
85−The possible channel states are:
86−enum pci_channel_state {
87− pci_channel_io_normal, /* I/O channel is in normal state */
88− pci_channel_io_frozen, /* I/O to channel is blocked */
89− pci_channel_io_perm_failure, /* PCI card is dead */
90−};
91−
92−Possible return values are:
93−enum pci_ers_result {
94− PCI_ERS_RESULT_NONE, /* no result/none/not supported in device driver */
95− PCI_ERS_RESULT_CAN_RECOVER, /* Device driver can recover without slot reset */
96− PCI_ERS_RESULT_NEED_RESET, /* Device driver wants slot to be reset. */
97− PCI_ERS_RESULT_DISCONNECT, /* Device has completely failed, is unrecoverable */
98− PCI_ERS_RESULT_RECOVERED, /* Device driver is fully recovered and operational */
99−};
100−
101−A driver does not have to implement all of these callbacks; however,
102−if it implements any, it must implement error_detected(). If a callback
103−is not implemented, the corresponding feature is considered unsupported.
104−For example, if mmio_enabled() and resume() aren't there, then it
105−is assumed that the driver is not doing any direct recovery and requires
106−a slot reset. Typically a driver will want to know about
107−a slot_reset().
108−
109−The actual steps taken by a platform to recover from a PCI error
110−event will be platform-dependent, but will follow the general
111−sequence described below.
112−
113−STEP 0: Error Event
114−-------------------
115−A PCI bus error is detected by the PCI hardware. On powerpc, the slot
116−is isolated, in that all I/O is blocked: all reads return 0xffffffff,
117−all writes are ignored.
118−
119−
120−STEP 1: Notification
121−--------------------
122−Platform calls the error_detected() callback on every instance of
123−every driver affected by the error.
124−
125−At this point, the device might not be accessible anymore, depending on
126−the platform (the slot will be isolated on powerpc). The driver may
127−already have "noticed" the error because of a failing I/O, but this
128−is the proper "synchronization point", that is, it gives the driver
129−a chance to cleanup, waiting for pending stuff (timers, whatever, etc...)
130−to complete; it can take semaphores, schedule, etc... everything but
131−touch the device. Within this function and after it returns, the driver
132−shouldn't do any new IOs. Called in task context. This is sort of a
133−"quiesce" point. See note about interrupts at the end of this doc.
134−
135−All drivers participating in this system must implement this call.
136−The driver must return one of the following result codes:
137− - PCI_ERS_RESULT_CAN_RECOVER:
138− Driver returns this if it thinks it might be able to recover
139− the HW by just banging IOs or if it wants to be given
140− a chance to extract some diagnostic information (see
141− mmio_enable, below).
142− - PCI_ERS_RESULT_NEED_RESET:
143− Driver returns this if it can't recover without a
144− slot reset.
145− - PCI_ERS_RESULT_DISCONNECT:
146− Driver returns this if it doesn't want to recover at all.
147−
148−The next step taken will depend on the result codes returned by the
149−drivers.
150−
151−If all drivers on the segment/slot return PCI_ERS_RESULT_CAN_RECOVER,
152−then the platform should re-enable IOs on the slot (or do nothing in
153−particular, if the platform doesn't isolate slots), and recovery
154−proceeds to STEP 2 (MMIO Enable).
155−
156−If any driver requested a slot reset (by returning PCI_ERS_RESULT_NEED_RESET),
157−then recovery proceeds to STEP 4 (Slot Reset).
158−
159−If the platform is unable to recover the slot, the next step
160−is STEP 6 (Permanent Failure).
161−
162−>>> The current powerpc implementation assumes that a device driver will
163−>>> *not* schedule or semaphore in this routine; the current powerpc
164−>>> implementation uses one kernel thread to notify all devices;
165−>>> thus, if one device sleeps/schedules, all devices are affected.
166−>>> Doing better requires complex multi-threaded logic in the error
167−>>> recovery implementation (e.g. waiting for all notification threads
168−>>> to "join" before proceeding with recovery.) This seems excessively
169−>>> complex and not worth implementing.
170−
171−>>> The current powerpc implementation doesn't much care if the device
172−>>> attempts I/O at this point, or not. I/O's will fail, returning
173−>>> a value of 0xff on read, and writes will be dropped. If more than
174−>>> EEH_MAX_FAILS I/O's are attempted to a frozen adapter, EEH
175−>>> assumes that the device driver has gone into an infinite loop
176−>>> and prints an error to syslog. A reboot is then required to
177−>>> get the device working again.
178−
179−STEP 2: MMIO Enabled
180−-------------------
181−The platform re-enables MMIO to the device (but typically not the
182−DMA), and then calls the mmio_enabled() callback on all affected
183−device drivers.
184−
185−This is the "early recovery" call. IOs are allowed again, but DMA is
186−not, with some restrictions. This is NOT a callback for the driver to
187−start operations again, only to peek/poke at the device, extract diagnostic
188−information, if any, and eventually do things like trigger a device local
189−reset or some such, but not restart operations. This callback is made if
190−all drivers on a segment agree that they can try to recover and if no automatic
191−link reset was performed by the HW. If the platform can't just re-enable IOs
192−without a slot reset or a link reset, it will not call this callback, and
193−instead will have gone directly to STEP 3 (Link Reset) or STEP 4 (Slot Reset)
194−
195−>>> The following is proposed; no platform implements this yet:
196−>>> Proposal: All I/O's should be done _synchronously_ from within
197−>>> this callback, errors triggered by them will be returned via
198−>>> the normal pci_check_whatever() API, no new error_detected()
199−>>> callback will be issued due to an error happening here. However,
200−>>> such an error might cause IOs to be re-blocked for the whole
201−>>> segment, and thus invalidate the recovery that other devices
202−>>> on the same segment might have done, forcing the whole segment
203−>>> into one of the next states, that is, link reset or slot reset.
204−
205−The driver should return one of the following result codes:
206− - PCI_ERS_RESULT_RECOVERED
207− Driver returns this if it thinks the device is fully
208− functional and thinks it is ready to start
209− normal driver operations again. There is no
210− guarantee that the driver will actually be
211− allowed to proceed, as another driver on the
212− same segment might have failed and thus triggered a
213− slot reset on platforms that support it.
214−
215− - PCI_ERS_RESULT_NEED_RESET
216− Driver returns this if it thinks the device is not
217− recoverable in its current state and it needs a slot
218− reset to proceed.
219−
220− - PCI_ERS_RESULT_DISCONNECT
221− Same as above. Total failure, no recovery even after
222− reset driver dead. (To be defined more precisely)
223−
224−The next step taken depends on the results returned by the drivers.
225−If all drivers returned PCI_ERS_RESULT_RECOVERED, then the platform
226−proceeds to either STEP3 (Link Reset) or to STEP 5 (Resume Operations).
227−
228−If any driver returned PCI_ERS_RESULT_NEED_RESET, then the platform
229−proceeds to STEP 4 (Slot Reset)
230−
231−STEP 3: Link Reset
232−------------------
233−The platform resets the link. This is a PCI-Express specific step
234−and is done whenever a fatal error has been detected that can be
235−"solved" by resetting the link.
236−
237−STEP 4: Slot Reset
238−------------------
239−
240−In response to a return value of PCI_ERS_RESULT_NEED_RESET, the
241−the platform will perform a slot reset on the requesting PCI device(s).
242−The actual steps taken by a platform to perform a slot reset
243−will be platform-dependent. Upon completion of slot reset, the
244−platform will call the device slot_reset() callback.
245−
246−Powerpc platforms implement two levels of slot reset:
247−soft reset(default) and fundamental(optional) reset.
248−
249−Powerpc soft reset consists of asserting the adapter #RST line and then
250−restoring the PCI BAR's and PCI configuration header to a state
251−that is equivalent to what it would be after a fresh system
252−power-on followed by power-on BIOS/system firmware initialization.
253−Soft reset is also known as hot-reset.
254−
255−Powerpc fundamental reset is supported by PCI Express cards only
256−and results in device's state machines, hardware logic, port states and
257−configuration registers to initialize to their default conditions.
258−
259−For most PCI devices, a soft reset will be sufficient for recovery.
260−Optional fundamental reset is provided to support a limited number
261−of PCI Express devices for which a soft reset is not sufficient
262−for recovery.
263−
264−If the platform supports PCI hotplug, then the reset might be
265−performed by toggling the slot electrical power off/on.
266−
267−It is important for the platform to restore the PCI config space
268−to the "fresh poweron" state, rather than the "last state". After
269−a slot reset, the device driver will almost always use its standard
270−device initialization routines, and an unusual config space setup
271−may result in hung devices, kernel panics, or silent data corruption.
272−
273−This call gives drivers the chance to re-initialize the hardware
274−(re-download firmware, etc.). At this point, the driver may assume
275−that the card is in a fresh state and is fully functional. The slot
276−is unfrozen and the driver has full access to PCI config space,
277−memory mapped I/O space and DMA. Interrupts (Legacy, MSI, or MSI-X)
278−will also be available.
279−
280−Drivers should not restart normal I/O processing operations
281−at this point. If all device drivers report success on this
282−callback, the platform will call resume() to complete the sequence,
283−and let the driver restart normal I/O processing.
284−
285−A driver can still return a critical failure for this function if
286−it can't get the device operational after reset. If the platform
287−previously tried a soft reset, it might now try a hard reset (power
288−cycle) and then call slot_reset() again. It the device still can't
289−be recovered, there is nothing more that can be done; the platform
290−will typically report a "permanent failure" in such a case. The
291−device will be considered "dead" in this case.
292−
293−Drivers for multi-function cards will need to coordinate among
294−themselves as to which driver instance will perform any "one-shot"
295−or global device initialization. For example, the Symbios sym53cxx2
296−driver performs device init only from PCI function 0:
297−
298−+ if (PCI_FUNC(pdev->devfn) == 0)
299−+ sym_reset_scsi_bus(np, 0);
300−
301− Result codes:
302− - PCI_ERS_RESULT_DISCONNECT
303− Same as above.
304−
305−Drivers for PCI Express cards that require a fundamental reset must
306−set the needs_freset bit in the pci_dev structure in their probe function.
307−For example, the QLogic qla2xxx driver sets the needs_freset bit for certain
308−PCI card types:
309−
310−+ /* Set EEH reset type to fundamental if required by hba */
311−+ if (IS_QLA24XX(ha) || IS_QLA25XX(ha) || IS_QLA81XX(ha))
312−+ pdev->needs_freset = 1;
313−+
314−
315−Platform proceeds either to STEP 5 (Resume Operations) or STEP 6 (Permanent
316−Failure).
317−
318−>>> The current powerpc implementation does not try a power-cycle
319−>>> reset if the driver returned PCI_ERS_RESULT_DISCONNECT.
320−>>> However, it probably should.
321−
322−
323−STEP 5: Resume Operations
324−-------------------------
325−The platform will call the resume() callback on all affected device
326−drivers if all drivers on the segment have returned
327−PCI_ERS_RESULT_RECOVERED from one of the 3 previous callbacks.
328−The goal of this callback is to tell the driver to restart activity,
329−that everything is back and running. This callback does not return
330−a result code.
331−
332−At this point, if a new error happens, the platform will restart
333−a new error recovery sequence.
334−
335−STEP 6: Permanent Failure
336−-------------------------
337−A "permanent failure" has occurred, and the platform cannot recover
338−the device. The platform will call error_detected() with a
339−pci_channel_state value of pci_channel_io_perm_failure.
340−
341−The device driver should, at this point, assume the worst. It should
342−cancel all pending I/O, refuse all new I/O, returning -EIO to
343−higher layers. The device driver should then clean up all of its
344−memory and remove itself from kernel operations, much as it would
345−during system shutdown.
346−
347−The platform will typically notify the system operator of the
348−permanent failure in some way. If the device is hotplug-capable,
349−the operator will probably want to remove and replace the device.
350−Note, however, not all failures are truly "permanent". Some are
351−caused by over-heating, some by a poorly seated card. Many
352−PCI error events are caused by software bugs, e.g. DMA's to
353−wild addresses or bogus split transactions due to programming
354−errors. See the discussion in powerpc/eeh-pci-error-recovery.txt
355−for additional detail on real-life experience of the causes of
356−software errors.
357−
358−
359−Conclusion; General Remarks
360−---------------------------
361−The way the callbacks are called is platform policy. A platform with
362−no slot reset capability may want to just "ignore" drivers that can't
363−recover (disconnect them) and try to let other cards on the same segment
364−recover. Keep in mind that in most real life cases, though, there will
365−be only one driver per segment.
366−
367−Now, a note about interrupts. If you get an interrupt and your
368−device is dead or has been isolated, there is a problem :)
369−The current policy is to turn this into a platform policy.
370−That is, the recovery API only requires that:
371−
372− - There is no guarantee that interrupt delivery can proceed from any
373−device on the segment starting from the error detection and until the
374−slot_reset callback is called, at which point interrupts are expected
375−to be fully operational.
376−
377− - There is no guarantee that interrupt delivery is stopped, that is,
378−a driver that gets an interrupt after detecting an error, or that detects
379−an error within the interrupt handler such that it prevents proper
380−ack'ing of the interrupt (and thus removal of the source) should just
381−return IRQ_NOTHANDLED. It's up to the platform to deal with that
382−condition, typically by masking the IRQ source during the duration of
383−the error handling. It is expected that the platform "knows" which
384−interrupts are routed to error-management capable slots and can deal
385−with temporarily disabling that IRQ number during error processing (this
386−isn't terribly complex). That means some IRQ latency for other devices
387−sharing the interrupt, but there is simply no other way. High end
388−platforms aren't supposed to share interrupts between many devices
389−anyway :)
390−
391−>>> Implementation details for the powerpc platform are discussed in
392−>>> the file Documentation/powerpc/eeh-pci-error-recovery.txt
393−
394−>>> As of this writing, there is a growing list of device drivers with
395−>>> patches implementing error recovery. Not all of these patches are in
396−>>> mainline yet. These may be used as "examples":
397−>>>
398−>>> drivers/scsi/ipr
399−>>> drivers/scsi/sym53c8xx_2
400−>>> drivers/scsi/qla2xxx
401−>>> drivers/scsi/lpfc
402−>>> drivers/next/bnx2.c
403−>>> drivers/next/e100.c
404−>>> drivers/net/e1000
405−>>> drivers/net/e1000e
406−>>> drivers/net/ixgb
407−>>> drivers/net/ixgbe
408−>>> drivers/net/cxgb3
409−>>> drivers/net/s2io.c
410−>>> drivers/net/qlge
411−
412−The End
413−-------
Documentation/PCI/pci-iov-howto.rst+172−0
@@ -0,0 +1,172 @@
1+.. SPDX-License-Identifier: GPL-2.0
2+.. include:: <isonum.txt>
3+
4+====================================
5+PCI Express I/O Virtualization Howto
6+====================================
7+
8+:Copyright: |copy| 2009 Intel Corporation
9+:Authors: - Yu Zhao <yu.zhao@intel.com>
10+ - Donald Dutile <ddutile@redhat.com>
11+
12+Overview
13+========
14+
15+What is SR-IOV
16+--------------
17+
18+Single Root I/O Virtualization (SR-IOV) is a PCI Express Extended
19+capability which makes one physical device appear as multiple virtual
20+devices. The physical device is referred to as Physical Function (PF)
21+while the virtual devices are referred to as Virtual Functions (VF).
22+Allocation of the VF can be dynamically controlled by the PF via
23+registers encapsulated in the capability. By default, this feature is
24+not enabled and the PF behaves as traditional PCIe device. Once it's
25+turned on, each VF's PCI configuration space can be accessed by its own
26+Bus, Device and Function Number (Routing ID). And each VF also has PCI
27+Memory Space, which is used to map its register set. VF device driver
28+operates on the register set so it can be functional and appear as a
29+real existing PCI device.
30+
31+User Guide
32+==========
33+
34+How can I enable SR-IOV capability
35+----------------------------------
36+
37+Multiple methods are available for SR-IOV enablement.
38+In the first method, the device driver (PF driver) will control the
39+enabling and disabling of the capability via API provided by SR-IOV core.
40+If the hardware has SR-IOV capability, loading its PF driver would
41+enable it and all VFs associated with the PF. Some PF drivers require
42+a module parameter to be set to determine the number of VFs to enable.
43+In the second method, a write to the sysfs file sriov_numvfs will
44+enable and disable the VFs associated with a PCIe PF. This method
45+enables per-PF, VF enable/disable values versus the first method,
46+which applies to all PFs of the same device. Additionally, the
47+PCI SRIOV core support ensures that enable/disable operations are
48+valid to reduce duplication in multiple drivers for the same
49+checks, e.g., check numvfs == 0 if enabling VFs, ensure
50+numvfs <= totalvfs.
51+The second method is the recommended method for new/future VF devices.
52+
53+How can I use the Virtual Functions
54+-----------------------------------
55+
56+The VF is treated as hot-plugged PCI devices in the kernel, so they
57+should be able to work in the same way as real PCI devices. The VF
58+requires device driver that is same as a normal PCI device's.
59+
60+Developer Guide
61+===============
62+
63+SR-IOV API
64+----------
65+
66+To enable SR-IOV capability:
67+
68+(a) For the first method, in the driver::
69+
70+ int pci_enable_sriov(struct pci_dev *dev, int nr_virtfn);
71+
72+'nr_virtfn' is number of VFs to be enabled.
73+
74+(b) For the second method, from sysfs::
75+
76+ echo 'nr_virtfn' > \
77+ /sys/bus/pci/devices/<DOMAIN:BUS:DEVICE.FUNCTION>/sriov_numvfs
78+
79+To disable SR-IOV capability:
80+
81+(a) For the first method, in the driver::
82+
83+ void pci_disable_sriov(struct pci_dev *dev);
84+
85+(b) For the second method, from sysfs::
86+
87+ echo 0 > \
88+ /sys/bus/pci/devices/<DOMAIN:BUS:DEVICE.FUNCTION>/sriov_numvfs
89+
90+To enable auto probing VFs by a compatible driver on the host, run
91+command below before enabling SR-IOV capabilities. This is the
92+default behavior.
93+::
94+
95+ echo 1 > \
96+ /sys/bus/pci/devices/<DOMAIN:BUS:DEVICE.FUNCTION>/sriov_drivers_autoprobe
97+
98+To disable auto probing VFs by a compatible driver on the host, run
99+command below before enabling SR-IOV capabilities. Updating this
100+entry will not affect VFs which are already probed.
101+::
102+
103+ echo 0 > \
104+ /sys/bus/pci/devices/<DOMAIN:BUS:DEVICE.FUNCTION>/sriov_drivers_autoprobe
105+
106+Usage example
107+-------------
108+
109+Following piece of code illustrates the usage of the SR-IOV API.
110+::
111+
112+ static int dev_probe(struct pci_dev *dev, const struct pci_device_id *id)
113+ {
114+ pci_enable_sriov(dev, NR_VIRTFN);
115+
116+ ...
117+
118+ return 0;
119+ }
120+
121+ static void dev_remove(struct pci_dev *dev)
122+ {
123+ pci_disable_sriov(dev);
124+
125+ ...
126+ }
127+
128+ static int dev_suspend(struct pci_dev *dev, pm_message_t state)
129+ {
130+ ...
131+
132+ return 0;
133+ }
134+
135+ static int dev_resume(struct pci_dev *dev)
136+ {
137+ ...
138+
139+ return 0;
140+ }
141+
142+ static void dev_shutdown(struct pci_dev *dev)
143+ {
144+ ...
145+ }
146+
147+ static int dev_sriov_configure(struct pci_dev *dev, int numvfs)
148+ {
149+ if (numvfs > 0) {
150+ ...
151+ pci_enable_sriov(dev, numvfs);
152+ ...
153+ return numvfs;
154+ }
155+ if (numvfs == 0) {
156+ ....
157+ pci_disable_sriov(dev);
158+ ...
159+ return 0;
160+ }
161+ }
162+
163+ static struct pci_driver dev_driver = {
164+ .name = "SR-IOV Physical Function driver",
165+ .id_table = dev_id_table,
166+ .probe = dev_probe,
167+ .remove = dev_remove,
168+ .suspend = dev_suspend,
169+ .resume = dev_resume,
170+ .shutdown = dev_shutdown,
171+ .sriov_configure = dev_sriov_configure,
172+ };
Documentation/PCI/pci-iov-howto.txt+0−147
@@ -1,147 +0,0 @@
1− PCI Express I/O Virtualization Howto
2− Copyright (C) 2009 Intel Corporation
3− Yu Zhao <yu.zhao@intel.com>
4−
5− Update: November 2012
6− -- sysfs-based SRIOV enable-/disable-ment
7− Donald Dutile <ddutile@redhat.com>
8−
9−1. Overview
10−
11−1.1 What is SR-IOV
12−
13−Single Root I/O Virtualization (SR-IOV) is a PCI Express Extended
14−capability which makes one physical device appear as multiple virtual
15−devices. The physical device is referred to as Physical Function (PF)
16−while the virtual devices are referred to as Virtual Functions (VF).
17−Allocation of the VF can be dynamically controlled by the PF via
18−registers encapsulated in the capability. By default, this feature is
19−not enabled and the PF behaves as traditional PCIe device. Once it's
20−turned on, each VF's PCI configuration space can be accessed by its own
21−Bus, Device and Function Number (Routing ID). And each VF also has PCI
22−Memory Space, which is used to map its register set. VF device driver
23−operates on the register set so it can be functional and appear as a
24−real existing PCI device.
25−
26−2. User Guide
27−
28−2.1 How can I enable SR-IOV capability
29−
30−Multiple methods are available for SR-IOV enablement.
31−In the first method, the device driver (PF driver) will control the
32−enabling and disabling of the capability via API provided by SR-IOV core.
33−If the hardware has SR-IOV capability, loading its PF driver would
34−enable it and all VFs associated with the PF. Some PF drivers require
35−a module parameter to be set to determine the number of VFs to enable.
36−In the second method, a write to the sysfs file sriov_numvfs will
37−enable and disable the VFs associated with a PCIe PF. This method
38−enables per-PF, VF enable/disable values versus the first method,
39−which applies to all PFs of the same device. Additionally, the
40−PCI SRIOV core support ensures that enable/disable operations are
41−valid to reduce duplication in multiple drivers for the same
42−checks, e.g., check numvfs == 0 if enabling VFs, ensure
43−numvfs <= totalvfs.
44−The second method is the recommended method for new/future VF devices.
45−
46−2.2 How can I use the Virtual Functions
47−
48−The VF is treated as hot-plugged PCI devices in the kernel, so they
49−should be able to work in the same way as real PCI devices. The VF
50−requires device driver that is same as a normal PCI device's.
51−
52−3. Developer Guide
53−
54−3.1 SR-IOV API
55−
56−To enable SR-IOV capability:
57−(a) For the first method, in the driver:
58− int pci_enable_sriov(struct pci_dev *dev, int nr_virtfn);
59− 'nr_virtfn' is number of VFs to be enabled.
60−(b) For the second method, from sysfs:
61− echo 'nr_virtfn' > \
62− /sys/bus/pci/devices/<DOMAIN:BUS:DEVICE.FUNCTION>/sriov_numvfs
63−
64−To disable SR-IOV capability:
65−(a) For the first method, in the driver:
66− void pci_disable_sriov(struct pci_dev *dev);
67−(b) For the second method, from sysfs:
68− echo 0 > \
69− /sys/bus/pci/devices/<DOMAIN:BUS:DEVICE.FUNCTION>/sriov_numvfs
70−
71−To enable auto probing VFs by a compatible driver on the host, run
72−command below before enabling SR-IOV capabilities. This is the
73−default behavior.
74− echo 1 > \
75− /sys/bus/pci/devices/<DOMAIN:BUS:DEVICE.FUNCTION>/sriov_drivers_autoprobe
76−
77−To disable auto probing VFs by a compatible driver on the host, run
78−command below before enabling SR-IOV capabilities. Updating this
79−entry will not affect VFs which are already probed.
80− echo 0 > \
81− /sys/bus/pci/devices/<DOMAIN:BUS:DEVICE.FUNCTION>/sriov_drivers_autoprobe
82−
83−3.2 Usage example
84−
85−Following piece of code illustrates the usage of the SR-IOV API.
86−
87−static int dev_probe(struct pci_dev *dev, const struct pci_device_id *id)
88−{
89− pci_enable_sriov(dev, NR_VIRTFN);
90−
91− ...
92−
93− return 0;
94−}
95−
96−static void dev_remove(struct pci_dev *dev)
97−{
98− pci_disable_sriov(dev);
99−
100− ...
101−}
102−
103−static int dev_suspend(struct pci_dev *dev, pm_message_t state)
104−{
105− ...
106−
107− return 0;
108−}
109−
110−static int dev_resume(struct pci_dev *dev)
111−{
112− ...
113−
114− return 0;
115−}
116−
117−static void dev_shutdown(struct pci_dev *dev)
118−{
119− ...
120−}
121−
122−static int dev_sriov_configure(struct pci_dev *dev, int numvfs)
123−{
124− if (numvfs > 0) {
125− ...
126− pci_enable_sriov(dev, numvfs);
127− ...
128− return numvfs;
129− }
130− if (numvfs == 0) {
131− ....
132− pci_disable_sriov(dev);
133− ...
134− return 0;
135− }
136−}
137−
138−static struct pci_driver dev_driver = {
139− .name = "SR-IOV Physical Function driver",
140− .id_table = dev_id_table,
141− .probe = dev_probe,
142− .remove = dev_remove,
143− .suspend = dev_suspend,
144− .resume = dev_resume,
145− .shutdown = dev_shutdown,
146− .sriov_configure = dev_sriov_configure,
147−};
Documentation/PCI/pci.rst+578−0
@@ -0,0 +1,578 @@
1+.. SPDX-License-Identifier: GPL-2.0
2+
3+==============================
4+How To Write Linux PCI Drivers
5+==============================
6+
7+:Authors: - Martin Mares <mj@ucw.cz>
8+ - Grant Grundler <grundler@parisc-linux.org>
9+
10+The world of PCI is vast and full of (mostly unpleasant) surprises.
11+Since each CPU architecture implements different chip-sets and PCI devices
12+have different requirements (erm, "features"), the result is the PCI support
13+in the Linux kernel is not as trivial as one would wish. This short paper
14+tries to introduce all potential driver authors to Linux APIs for
15+PCI device drivers.
16+
17+A more complete resource is the third edition of "Linux Device Drivers"
18+by Jonathan Corbet, Alessandro Rubini, and Greg Kroah-Hartman.
19+LDD3 is available for free (under Creative Commons License) from:
20+http://lwn.net/Kernel/LDD3/.
21+
22+However, keep in mind that all documents are subject to "bit rot".
23+Refer to the source code if things are not working as described here.
24+
25+Please send questions/comments/patches about Linux PCI API to the
26+"Linux PCI" <linux-pci@atrey.karlin.mff.cuni.cz> mailing list.
27+
28+
29+Structure of PCI drivers
30+========================
31+PCI drivers "discover" PCI devices in a system via pci_register_driver().
32+Actually, it's the other way around. When the PCI generic code discovers
33+a new device, the driver with a matching "description" will be notified.
34+Details on this below.
35+
36+pci_register_driver() leaves most of the probing for devices to
37+the PCI layer and supports online insertion/removal of devices [thus
38+supporting hot-pluggable PCI, CardBus, and Express-Card in a single driver].
39+pci_register_driver() call requires passing in a table of function
40+pointers and thus dictates the high level structure of a driver.
41+
42+Once the driver knows about a PCI device and takes ownership, the
43+driver generally needs to perform the following initialization:
44+
45+ - Enable the device
46+ - Request MMIO/IOP resources
47+ - Set the DMA mask size (for both coherent and streaming DMA)
48+ - Allocate and initialize shared control data (pci_allocate_coherent())
49+ - Access device configuration space (if needed)
50+ - Register IRQ handler (request_irq())
51+ - Initialize non-PCI (i.e. LAN/SCSI/etc parts of the chip)
52+ - Enable DMA/processing engines
53+
54+When done using the device, and perhaps the module needs to be unloaded,
55+the driver needs to take the follow steps:
56+
57+ - Disable the device from generating IRQs
58+ - Release the IRQ (free_irq())
59+ - Stop all DMA activity
60+ - Release DMA buffers (both streaming and coherent)
61+ - Unregister from other subsystems (e.g. scsi or netdev)
62+ - Release MMIO/IOP resources
63+ - Disable the device
64+
65+Most of these topics are covered in the following sections.
66+For the rest look at LDD3 or <linux/pci.h> .
67+
68+If the PCI subsystem is not configured (CONFIG_PCI is not set), most of
69+the PCI functions described below are defined as inline functions either
70+completely empty or just returning an appropriate error codes to avoid
71+lots of ifdefs in the drivers.
72+
73+
74+pci_register_driver() call
75+==========================
76+
77+PCI device drivers call ``pci_register_driver()`` during their
78+initialization with a pointer to a structure describing the driver
79+(``struct pci_driver``):
80+
81+.. kernel-doc:: include/linux/pci.h
82+ :functions: pci_driver
83+
84+The ID table is an array of ``struct pci_device_id`` entries ending with an
85+all-zero entry. Definitions with static const are generally preferred.
86+
87+.. kernel-doc:: include/linux/mod_devicetable.h
88+ :functions: pci_device_id
89+
90+Most drivers only need ``PCI_DEVICE()`` or ``PCI_DEVICE_CLASS()`` to set up
91+a pci_device_id table.
92+
93+New PCI IDs may be added to a device driver pci_ids table at runtime
94+as shown below::
95+
96+ echo "vendor device subvendor subdevice class class_mask driver_data" > \
97+ /sys/bus/pci/drivers/{driver}/new_id
98+
99+All fields are passed in as hexadecimal values (no leading 0x).
100+The vendor and device fields are mandatory, the others are optional. Users
101+need pass only as many optional fields as necessary:
102+
103+ - subvendor and subdevice fields default to PCI_ANY_ID (FFFFFFFF)
104+ - class and classmask fields default to 0
105+ - driver_data defaults to 0UL.
106+
107+Note that driver_data must match the value used by any of the pci_device_id
108+entries defined in the driver. This makes the driver_data field mandatory
109+if all the pci_device_id entries have a non-zero driver_data value.
110+
111+Once added, the driver probe routine will be invoked for any unclaimed
112+PCI devices listed in its (newly updated) pci_ids list.
113+
114+When the driver exits, it just calls pci_unregister_driver() and the PCI layer
115+automatically calls the remove hook for all devices handled by the driver.
116+
117+
118+"Attributes" for driver functions/data
119+--------------------------------------
120+
121+Please mark the initialization and cleanup functions where appropriate
122+(the corresponding macros are defined in <linux/init.h>):
123+
124+ ====== =================================================
125+ __init Initialization code. Thrown away after the driver
126+ initializes.
127+ __exit Exit code. Ignored for non-modular drivers.
128+ ====== =================================================
129+
130+Tips on when/where to use the above attributes:
131+ - The module_init()/module_exit() functions (and all
132+ initialization functions called _only_ from these)
133+ should be marked __init/__exit.
134+
135+ - Do not mark the struct pci_driver.
136+
137+ - Do NOT mark a function if you are not sure which mark to use.
138+ Better to not mark the function than mark the function wrong.
139+
140+
141+How to find PCI devices manually
142+================================
143+
144+PCI drivers should have a really good reason for not using the
145+pci_register_driver() interface to search for PCI devices.
146+The main reason PCI devices are controlled by multiple drivers
147+is because one PCI device implements several different HW services.
148+E.g. combined serial/parallel port/floppy controller.
149+
150+A manual search may be performed using the following constructs:
151+
152+Searching by vendor and device ID::
153+
154+ struct pci_dev *dev = NULL;
155+ while (dev = pci_get_device(VENDOR_ID, DEVICE_ID, dev))
156+ configure_device(dev);
157+
158+Searching by class ID (iterate in a similar way)::
159+
160+ pci_get_class(CLASS_ID, dev)
161+
162+Searching by both vendor/device and subsystem vendor/device ID::
163+
164+ pci_get_subsys(VENDOR_ID,DEVICE_ID, SUBSYS_VENDOR_ID, SUBSYS_DEVICE_ID, dev).
165+
166+You can use the constant PCI_ANY_ID as a wildcard replacement for
167+VENDOR_ID or DEVICE_ID. This allows searching for any device from a
168+specific vendor, for example.
169+
170+These functions are hotplug-safe. They increment the reference count on
171+the pci_dev that they return. You must eventually (possibly at module unload)
172+decrement the reference count on these devices by calling pci_dev_put().
173+
174+
175+Device Initialization Steps
176+===========================
177+
178+As noted in the introduction, most PCI drivers need the following steps
179+for device initialization:
180+
181+ - Enable the device
182+ - Request MMIO/IOP resources
183+ - Set the DMA mask size (for both coherent and streaming DMA)
184+ - Allocate and initialize shared control data (pci_allocate_coherent())
185+ - Access device configuration space (if needed)
186+ - Register IRQ handler (request_irq())
187+ - Initialize non-PCI (i.e. LAN/SCSI/etc parts of the chip)
188+ - Enable DMA/processing engines.
189+
190+The driver can access PCI config space registers at any time.
191+(Well, almost. When running BIST, config space can go away...but
192+that will just result in a PCI Bus Master Abort and config reads
193+will return garbage).
194+
195+
196+Enable the PCI device
197+---------------------
198+Before touching any device registers, the driver needs to enable
199+the PCI device by calling pci_enable_device(). This will:
200+
201+ - wake up the device if it was in suspended state,
202+ - allocate I/O and memory regions of the device (if BIOS did not),
203+ - allocate an IRQ (if BIOS did not).
204+
205+.. note::
206+ pci_enable_device() can fail! Check the return value.
207+
208+.. warning::
209+ OS BUG: we don't check resource allocations before enabling those
210+ resources. The sequence would make more sense if we called
211+ pci_request_resources() before calling pci_enable_device().
212+ Currently, the device drivers can't detect the bug when when two
213+ devices have been allocated the same range. This is not a common
214+ problem and unlikely to get fixed soon.
215+
216+ This has been discussed before but not changed as of 2.6.19:
217+ http://lkml.org/lkml/2006/3/2/194
218+
219+
220+pci_set_master() will enable DMA by setting the bus master bit
221+in the PCI_COMMAND register. It also fixes the latency timer value if
222+it's set to something bogus by the BIOS. pci_clear_master() will
223+disable DMA by clearing the bus master bit.
224+
225+If the PCI device can use the PCI Memory-Write-Invalidate transaction,
226+call pci_set_mwi(). This enables the PCI_COMMAND bit for Mem-Wr-Inval
227+and also ensures that the cache line size register is set correctly.
228+Check the return value of pci_set_mwi() as not all architectures
229+or chip-sets may support Memory-Write-Invalidate. Alternatively,
230+if Mem-Wr-Inval would be nice to have but is not required, call
231+pci_try_set_mwi() to have the system do its best effort at enabling
232+Mem-Wr-Inval.
233+
234+
235+Request MMIO/IOP resources
236+--------------------------
237+Memory (MMIO), and I/O port addresses should NOT be read directly
238+from the PCI device config space. Use the values in the pci_dev structure
239+as the PCI "bus address" might have been remapped to a "host physical"
240+address by the arch/chip-set specific kernel support.
241+
242+See Documentation/io-mapping.txt for how to access device registers
243+or device memory.
244+
245+The device driver needs to call pci_request_region() to verify
246+no other device is already using the same address resource.
247+Conversely, drivers should call pci_release_region() AFTER
248+calling pci_disable_device().
249+The idea is to prevent two devices colliding on the same address range.
250+
251+.. tip::
252+ See OS BUG comment above. Currently (2.6.19), The driver can only
253+ determine MMIO and IO Port resource availability _after_ calling
254+ pci_enable_device().
255+
256+Generic flavors of pci_request_region() are request_mem_region()
257+(for MMIO ranges) and request_region() (for IO Port ranges).
258+Use these for address resources that are not described by "normal" PCI
259+BARs.
260+
261+Also see pci_request_selected_regions() below.
262+
263+
264+Set the DMA mask size
265+---------------------
266+.. note::
267+ If anything below doesn't make sense, please refer to
268+ Documentation/DMA-API.txt. This section is just a reminder that
269+ drivers need to indicate DMA capabilities of the device and is not
270+ an authoritative source for DMA interfaces.
271+
272+While all drivers should explicitly indicate the DMA capability
273+(e.g. 32 or 64 bit) of the PCI bus master, devices with more than
274+32-bit bus master capability for streaming data need the driver
275+to "register" this capability by calling pci_set_dma_mask() with
276+appropriate parameters. In general this allows more efficient DMA
277+on systems where System RAM exists above 4G _physical_ address.
278+
279+Drivers for all PCI-X and PCIe compliant devices must call
280+pci_set_dma_mask() as they are 64-bit DMA devices.
281+
282+Similarly, drivers must also "register" this capability if the device
283+can directly address "consistent memory" in System RAM above 4G physical
284+address by calling pci_set_consistent_dma_mask().
285+Again, this includes drivers for all PCI-X and PCIe compliant devices.
286+Many 64-bit "PCI" devices (before PCI-X) and some PCI-X devices are
287+64-bit DMA capable for payload ("streaming") data but not control
288+("consistent") data.
289+
290+
291+Setup shared control data
292+-------------------------
293+Once the DMA masks are set, the driver can allocate "consistent" (a.k.a. shared)
294+memory. See Documentation/DMA-API.txt for a full description of
295+the DMA APIs. This section is just a reminder that it needs to be done
296+before enabling DMA on the device.
297+
298+
299+Initialize device registers
300+---------------------------
301+Some drivers will need specific "capability" fields programmed
302+or other "vendor specific" register initialized or reset.
303+E.g. clearing pending interrupts.
304+
305+
306+Register IRQ handler
307+--------------------
308+While calling request_irq() is the last step described here,
309+this is often just another intermediate step to initialize a device.
310+This step can often be deferred until the device is opened for use.
311+
312+All interrupt handlers for IRQ lines should be registered with IRQF_SHARED
313+and use the devid to map IRQs to devices (remember that all PCI IRQ lines
314+can be shared).
315+
316+request_irq() will associate an interrupt handler and device handle
317+with an interrupt number. Historically interrupt numbers represent
318+IRQ lines which run from the PCI device to the Interrupt controller.
319+With MSI and MSI-X (more below) the interrupt number is a CPU "vector".
320+
321+request_irq() also enables the interrupt. Make sure the device is
322+quiesced and does not have any interrupts pending before registering
323+the interrupt handler.
324+
325+MSI and MSI-X are PCI capabilities. Both are "Message Signaled Interrupts"
326+which deliver interrupts to the CPU via a DMA write to a Local APIC.
327+The fundamental difference between MSI and MSI-X is how multiple
328+"vectors" get allocated. MSI requires contiguous blocks of vectors
329+while MSI-X can allocate several individual ones.
330+
331+MSI capability can be enabled by calling pci_alloc_irq_vectors() with the
332+PCI_IRQ_MSI and/or PCI_IRQ_MSIX flags before calling request_irq(). This
333+causes the PCI support to program CPU vector data into the PCI device
334+capability registers. Many architectures, chip-sets, or BIOSes do NOT
335+support MSI or MSI-X and a call to pci_alloc_irq_vectors with just
336+the PCI_IRQ_MSI and PCI_IRQ_MSIX flags will fail, so try to always
337+specify PCI_IRQ_LEGACY as well.
338+
339+Drivers that have different interrupt handlers for MSI/MSI-X and
340+legacy INTx should chose the right one based on the msi_enabled
341+and msix_enabled flags in the pci_dev structure after calling
342+pci_alloc_irq_vectors.
343+
344+There are (at least) two really good reasons for using MSI:
345+
346+1) MSI is an exclusive interrupt vector by definition.
347+ This means the interrupt handler doesn't have to verify
348+ its device caused the interrupt.
349+
350+2) MSI avoids DMA/IRQ race conditions. DMA to host memory is guaranteed
351+ to be visible to the host CPU(s) when the MSI is delivered. This
352+ is important for both data coherency and avoiding stale control data.
353+ This guarantee allows the driver to omit MMIO reads to flush
354+ the DMA stream.
355+
356+See drivers/infiniband/hw/mthca/ or drivers/net/tg3.c for examples
357+of MSI/MSI-X usage.
358+
359+
360+PCI device shutdown
361+===================
362+
363+When a PCI device driver is being unloaded, most of the following
364+steps need to be performed:
365+
366+ - Disable the device from generating IRQs
367+ - Release the IRQ (free_irq())
368+ - Stop all DMA activity
369+ - Release DMA buffers (both streaming and consistent)
370+ - Unregister from other subsystems (e.g. scsi or netdev)
371+ - Disable device from responding to MMIO/IO Port addresses
372+ - Release MMIO/IO Port resource(s)
373+
374+
375+Stop IRQs on the device
376+-----------------------
377+How to do this is chip/device specific. If it's not done, it opens
378+the possibility of a "screaming interrupt" if (and only if)
379+the IRQ is shared with another device.
380+
381+When the shared IRQ handler is "unhooked", the remaining devices
382+using the same IRQ line will still need the IRQ enabled. Thus if the
383+"unhooked" device asserts IRQ line, the system will respond assuming
384+it was one of the remaining devices asserted the IRQ line. Since none
385+of the other devices will handle the IRQ, the system will "hang" until
386+it decides the IRQ isn't going to get handled and masks the IRQ (100,000
387+iterations later). Once the shared IRQ is masked, the remaining devices
388+will stop functioning properly. Not a nice situation.
389+
390+This is another reason to use MSI or MSI-X if it's available.
391+MSI and MSI-X are defined to be exclusive interrupts and thus
392+are not susceptible to the "screaming interrupt" problem.
393+
394+
395+Release the IRQ
396+---------------
397+Once the device is quiesced (no more IRQs), one can call free_irq().
398+This function will return control once any pending IRQs are handled,
399+"unhook" the drivers IRQ handler from that IRQ, and finally release
400+the IRQ if no one else is using it.
401+
402+
403+Stop all DMA activity
404+---------------------
405+It's extremely important to stop all DMA operations BEFORE attempting
406+to deallocate DMA control data. Failure to do so can result in memory
407+corruption, hangs, and on some chip-sets a hard crash.
408+
409+Stopping DMA after stopping the IRQs can avoid races where the
410+IRQ handler might restart DMA engines.
411+
412+While this step sounds obvious and trivial, several "mature" drivers
413+didn't get this step right in the past.
414+
415+
416+Release DMA buffers
417+-------------------
418+Once DMA is stopped, clean up streaming DMA first.
419+I.e. unmap data buffers and return buffers to "upstream"
420+owners if there is one.
421+
422+Then clean up "consistent" buffers which contain the control data.
423+
424+See Documentation/DMA-API.txt for details on unmapping interfaces.
425+
426+
427+Unregister from other subsystems
428+--------------------------------
429+Most low level PCI device drivers support some other subsystem
430+like USB, ALSA, SCSI, NetDev, Infiniband, etc. Make sure your
431+driver isn't losing resources from that other subsystem.
432+If this happens, typically the symptom is an Oops (panic) when
433+the subsystem attempts to call into a driver that has been unloaded.
434+
435+
436+Disable Device from responding to MMIO/IO Port addresses
437+--------------------------------------------------------
438+io_unmap() MMIO or IO Port resources and then call pci_disable_device().
439+This is the symmetric opposite of pci_enable_device().
440+Do not access device registers after calling pci_disable_device().
441+
442+
443+Release MMIO/IO Port Resource(s)
444+--------------------------------
445+Call pci_release_region() to mark the MMIO or IO Port range as available.
446+Failure to do so usually results in the inability to reload the driver.
447+
448+
449+How to access PCI config space
450+==============================
451+
452+You can use `pci_(read|write)_config_(byte|word|dword)` to access the config
453+space of a device represented by `struct pci_dev *`. All these functions return
454+0 when successful or an error code (`PCIBIOS_...`) which can be translated to a
455+text string by pcibios_strerror. Most drivers expect that accesses to valid PCI
456+devices don't fail.
457+
458+If you don't have a struct pci_dev available, you can call
459+`pci_bus_(read|write)_config_(byte|word|dword)` to access a given device
460+and function on that bus.
461+
462+If you access fields in the standard portion of the config header, please
463+use symbolic names of locations and bits declared in <linux/pci.h>.
464+
465+If you need to access Extended PCI Capability registers, just call
466+pci_find_capability() for the particular capability and it will find the
467+corresponding register block for you.
468+
469+
470+Other interesting functions
471+===========================
472+
473+============================= ================================================
474+pci_get_domain_bus_and_slot() Find pci_dev corresponding to given domain,
475+ bus and slot and number. If the device is
476+ found, its reference count is increased.
477+pci_set_power_state() Set PCI Power Management state (0=D0 ... 3=D3)
478+pci_find_capability() Find specified capability in device's capability
479+ list.
480+pci_resource_start() Returns bus start address for a given PCI region
481+pci_resource_end() Returns bus end address for a given PCI region
482+pci_resource_len() Returns the byte length of a PCI region
483+pci_set_drvdata() Set private driver data pointer for a pci_dev
484+pci_get_drvdata() Return private driver data pointer for a pci_dev
485+pci_set_mwi() Enable Memory-Write-Invalidate transactions.
486+pci_clear_mwi() Disable Memory-Write-Invalidate transactions.
487+============================= ================================================
488+
489+
490+Miscellaneous hints
491+===================
492+
493+When displaying PCI device names to the user (for example when a driver wants
494+to tell the user what card has it found), please use pci_name(pci_dev).
495+
496+Always refer to the PCI devices by a pointer to the pci_dev structure.
497+All PCI layer functions use this identification and it's the only
498+reasonable one. Don't use bus/slot/function numbers except for very
499+special purposes -- on systems with multiple primary buses their semantics
500+can be pretty complex.
501+
502+Don't try to turn on Fast Back to Back writes in your driver. All devices
503+on the bus need to be capable of doing it, so this is something which needs
504+to be handled by platform and generic code, not individual drivers.
505+
506+
507+Vendor and device identifications
508+=================================
509+
510+Do not add new device or vendor IDs to include/linux/pci_ids.h unless they
511+are shared across multiple drivers. You can add private definitions in
512+your driver if they're helpful, or just use plain hex constants.
513+
514+The device IDs are arbitrary hex numbers (vendor controlled) and normally used
515+only in a single location, the pci_device_id table.
516+
517+Please DO submit new vendor/device IDs to http://pci-ids.ucw.cz/.
518+There are mirrors of the pci.ids file at http://pciids.sourceforge.net/
519+and https://github.com/pciutils/pciids.
520+
521+
522+Obsolete functions
523+==================
524+
525+There are several functions which you might come across when trying to
526+port an old driver to the new PCI interface. They are no longer present
527+in the kernel as they aren't compatible with hotplug or PCI domains or
528+having sane locking.
529+
530+================= ===========================================
531+pci_find_device() Superseded by pci_get_device()
532+pci_find_subsys() Superseded by pci_get_subsys()
533+pci_find_slot() Superseded by pci_get_domain_bus_and_slot()
534+pci_get_slot() Superseded by pci_get_domain_bus_and_slot()
535+================= ===========================================
536+
537+The alternative is the traditional PCI device driver that walks PCI
538+device lists. This is still possible but discouraged.
539+
540+
541+MMIO Space and "Write Posting"
542+==============================
543+
544+Converting a driver from using I/O Port space to using MMIO space
545+often requires some additional changes. Specifically, "write posting"
546+needs to be handled. Many drivers (e.g. tg3, acenic, sym53c8xx_2)
547+already do this. I/O Port space guarantees write transactions reach the PCI
548+device before the CPU can continue. Writes to MMIO space allow the CPU
549+to continue before the transaction reaches the PCI device. HW weenies
550+call this "Write Posting" because the write completion is "posted" to
551+the CPU before the transaction has reached its destination.
552+
553+Thus, timing sensitive code should add readl() where the CPU is
554+expected to wait before doing other work. The classic "bit banging"
555+sequence works fine for I/O Port space::
556+
557+ for (i = 8; --i; val >>= 1) {
558+ outb(val & 1, ioport_reg); /* write bit */
559+ udelay(10);
560+ }
561+
562+The same sequence for MMIO space should be::
563+
564+ for (i = 8; --i; val >>= 1) {
565+ writeb(val & 1, mmio_reg); /* write bit */
566+ readb(safe_mmio_reg); /* flush posted write */
567+ udelay(10);
568+ }
569+
570+It is important that "safe_mmio_reg" not have any side effects that
571+interferes with the correct operation of the device.
572+
573+Another case to watch out for is when resetting a PCI device. Use PCI
574+Configuration space reads to flush the writel(). This will gracefully
575+handle the PCI master abort on all platforms if the PCI device is
576+expected to not respond to a readl(). Most x86 platforms will allow
577+MMIO reads to master abort (a.k.a. "Soft Fail") and return garbage
578+(e.g. ~0). But many RISC platforms will crash (a.k.a."Hard Fail").
Documentation/PCI/pci.txt+0−636
@@ -1,636 +0,0 @@
1−
2− How To Write Linux PCI Drivers
3−
4− by Martin Mares <mj@ucw.cz> on 07-Feb-2000
5− updated by Grant Grundler <grundler@parisc-linux.org> on 23-Dec-2006
6−
7−~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
8−The world of PCI is vast and full of (mostly unpleasant) surprises.
9−Since each CPU architecture implements different chip-sets and PCI devices
10−have different requirements (erm, "features"), the result is the PCI support
11−in the Linux kernel is not as trivial as one would wish. This short paper
12−tries to introduce all potential driver authors to Linux APIs for
13−PCI device drivers.
14−
15−A more complete resource is the third edition of "Linux Device Drivers"
16−by Jonathan Corbet, Alessandro Rubini, and Greg Kroah-Hartman.
17−LDD3 is available for free (under Creative Commons License) from:
18−
19− http://lwn.net/Kernel/LDD3/
20−
21−However, keep in mind that all documents are subject to "bit rot".
22−Refer to the source code if things are not working as described here.
23−
24−Please send questions/comments/patches about Linux PCI API to the
25−"Linux PCI" <linux-pci@atrey.karlin.mff.cuni.cz> mailing list.
26−
27−
28−
29−0. Structure of PCI drivers
30−~~~~~~~~~~~~~~~~~~~~~~~~~~~
31−PCI drivers "discover" PCI devices in a system via pci_register_driver().
32−Actually, it's the other way around. When the PCI generic code discovers
33−a new device, the driver with a matching "description" will be notified.
34−Details on this below.
35−
36−pci_register_driver() leaves most of the probing for devices to
37−the PCI layer and supports online insertion/removal of devices [thus
38−supporting hot-pluggable PCI, CardBus, and Express-Card in a single driver].
39−pci_register_driver() call requires passing in a table of function
40−pointers and thus dictates the high level structure of a driver.
41−
42−Once the driver knows about a PCI device and takes ownership, the
43−driver generally needs to perform the following initialization:
44−
45− Enable the device
46− Request MMIO/IOP resources
47− Set the DMA mask size (for both coherent and streaming DMA)
48− Allocate and initialize shared control data (pci_allocate_coherent())
49− Access device configuration space (if needed)
50− Register IRQ handler (request_irq())
51− Initialize non-PCI (i.e. LAN/SCSI/etc parts of the chip)
52− Enable DMA/processing engines
53−
54−When done using the device, and perhaps the module needs to be unloaded,
55−the driver needs to take the follow steps:
56− Disable the device from generating IRQs
57− Release the IRQ (free_irq())
58− Stop all DMA activity
59− Release DMA buffers (both streaming and coherent)
60− Unregister from other subsystems (e.g. scsi or netdev)
61− Release MMIO/IOP resources
62− Disable the device
63−
64−Most of these topics are covered in the following sections.
65−For the rest look at LDD3 or <linux/pci.h> .
66−
67−If the PCI subsystem is not configured (CONFIG_PCI is not set), most of
68−the PCI functions described below are defined as inline functions either
69−completely empty or just returning an appropriate error codes to avoid
70−lots of ifdefs in the drivers.
71−
72−
73−
74−1. pci_register_driver() call
75−~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
76−
77−PCI device drivers call pci_register_driver() during their
78−initialization with a pointer to a structure describing the driver
79−(struct pci_driver):
80−
81− field name Description
82− ---------- ------------------------------------------------------
83− id_table Pointer to table of device ID's the driver is
84− interested in. Most drivers should export this
85− table using MODULE_DEVICE_TABLE(pci,...).
86−
87− probe This probing function gets called (during execution
88− of pci_register_driver() for already existing
89− devices or later if a new device gets inserted) for
90− all PCI devices which match the ID table and are not
91− "owned" by the other drivers yet. This function gets
92− passed a "struct pci_dev *" for each device whose
93− entry in the ID table matches the device. The probe
94− function returns zero when the driver chooses to
95− take "ownership" of the device or an error code
96− (negative number) otherwise.
97− The probe function always gets called from process
98− context, so it can sleep.
99−
100− remove The remove() function gets called whenever a device
101− being handled by this driver is removed (either during
102− deregistration of the driver or when it's manually
103− pulled out of a hot-pluggable slot).
104− The remove function always gets called from process
105− context, so it can sleep.
106−
107− suspend Put device into low power state.
108− suspend_late Put device into low power state.
109−
110− resume_early Wake device from low power state.
111− resume Wake device from low power state.
112−
113− (Please see Documentation/power/pci.txt for descriptions
114− of PCI Power Management and the related functions.)
115−
116− shutdown Hook into reboot_notifier_list (kernel/sys.c).
117− Intended to stop any idling DMA operations.
118− Useful for enabling wake-on-lan (NIC) or changing
119− the power state of a device before reboot.
120− e.g. drivers/net/e100.c.
121−
122− err_handler See Documentation/PCI/pci-error-recovery.txt
123−
124−
125−The ID table is an array of struct pci_device_id entries ending with an
126−all-zero entry. Definitions with static const are generally preferred.
127−
128−Each entry consists of:
129−
130− vendor,device Vendor and device ID to match (or PCI_ANY_ID)
131−
132− subvendor, Subsystem vendor and device ID to match (or PCI_ANY_ID)
133− subdevice,
134−
135− class Device class, subclass, and "interface" to match.
136− See Appendix D of the PCI Local Bus Spec or
137− include/linux/pci_ids.h for a full list of classes.
138− Most drivers do not need to specify class/class_mask
139− as vendor/device is normally sufficient.
140−
141− class_mask limit which sub-fields of the class field are compared.
142− See drivers/scsi/sym53c8xx_2/ for example of usage.
143−
144− driver_data Data private to the driver.
145− Most drivers don't need to use driver_data field.
146− Best practice is to use driver_data as an index
147− into a static list of equivalent device types,
148− instead of using it as a pointer.
149−
150−
151−Most drivers only need PCI_DEVICE() or PCI_DEVICE_CLASS() to set up
152−a pci_device_id table.
153−
154−New PCI IDs may be added to a device driver pci_ids table at runtime
155−as shown below:
156−
157−echo "vendor device subvendor subdevice class class_mask driver_data" > \
158−/sys/bus/pci/drivers/{driver}/new_id
159−
160−All fields are passed in as hexadecimal values (no leading 0x).
161−The vendor and device fields are mandatory, the others are optional. Users
162−need pass only as many optional fields as necessary:
163− o subvendor and subdevice fields default to PCI_ANY_ID (FFFFFFFF)
164− o class and classmask fields default to 0
165− o driver_data defaults to 0UL.
166−
167−Note that driver_data must match the value used by any of the pci_device_id
168−entries defined in the driver. This makes the driver_data field mandatory
169−if all the pci_device_id entries have a non-zero driver_data value.
170−
171−Once added, the driver probe routine will be invoked for any unclaimed
172−PCI devices listed in its (newly updated) pci_ids list.
173−
174−When the driver exits, it just calls pci_unregister_driver() and the PCI layer
175−automatically calls the remove hook for all devices handled by the driver.
176−
177−
178−1.1 "Attributes" for driver functions/data
179−
180−Please mark the initialization and cleanup functions where appropriate
181−(the corresponding macros are defined in <linux/init.h>):
182−
183− __init Initialization code. Thrown away after the driver
184− initializes.
185− __exit Exit code. Ignored for non-modular drivers.
186−
187−Tips on when/where to use the above attributes:
188− o The module_init()/module_exit() functions (and all
189− initialization functions called _only_ from these)
190− should be marked __init/__exit.
191−
192− o Do not mark the struct pci_driver.
193−
194− o Do NOT mark a function if you are not sure which mark to use.
195− Better to not mark the function than mark the function wrong.
196−
197−
198−
199−2. How to find PCI devices manually
200−~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
201−
202−PCI drivers should have a really good reason for not using the
203−pci_register_driver() interface to search for PCI devices.
204−The main reason PCI devices are controlled by multiple drivers
205−is because one PCI device implements several different HW services.
206−E.g. combined serial/parallel port/floppy controller.
207−
208−A manual search may be performed using the following constructs:
209−
210−Searching by vendor and device ID:
211−
212− struct pci_dev *dev = NULL;
213− while (dev = pci_get_device(VENDOR_ID, DEVICE_ID, dev))
214− configure_device(dev);
215−
216−Searching by class ID (iterate in a similar way):
217−
218− pci_get_class(CLASS_ID, dev)
219−
220−Searching by both vendor/device and subsystem vendor/device ID:
221−
222− pci_get_subsys(VENDOR_ID,DEVICE_ID, SUBSYS_VENDOR_ID, SUBSYS_DEVICE_ID, dev).
223−
224−You can use the constant PCI_ANY_ID as a wildcard replacement for
225−VENDOR_ID or DEVICE_ID. This allows searching for any device from a
226−specific vendor, for example.
227−
228−These functions are hotplug-safe. They increment the reference count on
229−the pci_dev that they return. You must eventually (possibly at module unload)
230−decrement the reference count on these devices by calling pci_dev_put().
231−
232−
233−
234−3. Device Initialization Steps
235−~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
236−
237−As noted in the introduction, most PCI drivers need the following steps
238−for device initialization:
239−
240− Enable the device
241− Request MMIO/IOP resources
242− Set the DMA mask size (for both coherent and streaming DMA)
243− Allocate and initialize shared control data (pci_allocate_coherent())
244− Access device configuration space (if needed)
245− Register IRQ handler (request_irq())
246− Initialize non-PCI (i.e. LAN/SCSI/etc parts of the chip)
247− Enable DMA/processing engines.
248−
249−The driver can access PCI config space registers at any time.
250−(Well, almost. When running BIST, config space can go away...but
251−that will just result in a PCI Bus Master Abort and config reads
252−will return garbage).
253−
254−
255−3.1 Enable the PCI device
256−~~~~~~~~~~~~~~~~~~~~~~~~~
257−Before touching any device registers, the driver needs to enable
258−the PCI device by calling pci_enable_device(). This will:
259− o wake up the device if it was in suspended state,
260− o allocate I/O and memory regions of the device (if BIOS did not),
261− o allocate an IRQ (if BIOS did not).
262−
263−NOTE: pci_enable_device() can fail! Check the return value.
264−
265−[ OS BUG: we don't check resource allocations before enabling those
266− resources. The sequence would make more sense if we called
267− pci_request_resources() before calling pci_enable_device().
268− Currently, the device drivers can't detect the bug when when two
269− devices have been allocated the same range. This is not a common
270− problem and unlikely to get fixed soon.
271−
272− This has been discussed before but not changed as of 2.6.19:
273− http://lkml.org/lkml/2006/3/2/194
274−]
275−
276−pci_set_master() will enable DMA by setting the bus master bit
277−in the PCI_COMMAND register. It also fixes the latency timer value if
278−it's set to something bogus by the BIOS. pci_clear_master() will
279−disable DMA by clearing the bus master bit.
280−
281−If the PCI device can use the PCI Memory-Write-Invalidate transaction,
282−call pci_set_mwi(). This enables the PCI_COMMAND bit for Mem-Wr-Inval
283−and also ensures that the cache line size register is set correctly.
284−Check the return value of pci_set_mwi() as not all architectures
285−or chip-sets may support Memory-Write-Invalidate. Alternatively,
286−if Mem-Wr-Inval would be nice to have but is not required, call
287−pci_try_set_mwi() to have the system do its best effort at enabling
288−Mem-Wr-Inval.
289−
290−
291−3.2 Request MMIO/IOP resources
292−~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
293−Memory (MMIO), and I/O port addresses should NOT be read directly
294−from the PCI device config space. Use the values in the pci_dev structure
295−as the PCI "bus address" might have been remapped to a "host physical"
296−address by the arch/chip-set specific kernel support.
297−
298−See Documentation/io-mapping.txt for how to access device registers
299−or device memory.
300−
301−The device driver needs to call pci_request_region() to verify
302−no other device is already using the same address resource.
303−Conversely, drivers should call pci_release_region() AFTER
304−calling pci_disable_device().
305−The idea is to prevent two devices colliding on the same address range.
306−
307−[ See OS BUG comment above. Currently (2.6.19), The driver can only
308− determine MMIO and IO Port resource availability _after_ calling
309− pci_enable_device(). ]
310−
311−Generic flavors of pci_request_region() are request_mem_region()
312−(for MMIO ranges) and request_region() (for IO Port ranges).
313−Use these for address resources that are not described by "normal" PCI
314−BARs.
315−
316−Also see pci_request_selected_regions() below.
317−
318−
319−3.3 Set the DMA mask size
320−~~~~~~~~~~~~~~~~~~~~~~~~~
321−[ If anything below doesn't make sense, please refer to
322− Documentation/DMA-API.txt. This section is just a reminder that
323− drivers need to indicate DMA capabilities of the device and is not
324− an authoritative source for DMA interfaces. ]
325−
326−While all drivers should explicitly indicate the DMA capability
327−(e.g. 32 or 64 bit) of the PCI bus master, devices with more than
328−32-bit bus master capability for streaming data need the driver
329−to "register" this capability by calling pci_set_dma_mask() with
330−appropriate parameters. In general this allows more efficient DMA
331−on systems where System RAM exists above 4G _physical_ address.
332−
333−Drivers for all PCI-X and PCIe compliant devices must call
334−pci_set_dma_mask() as they are 64-bit DMA devices.
335−
336−Similarly, drivers must also "register" this capability if the device
337−can directly address "consistent memory" in System RAM above 4G physical
338−address by calling pci_set_consistent_dma_mask().
339−Again, this includes drivers for all PCI-X and PCIe compliant devices.
340−Many 64-bit "PCI" devices (before PCI-X) and some PCI-X devices are
341−64-bit DMA capable for payload ("streaming") data but not control
342−("consistent") data.
343−
344−
345−3.4 Setup shared control data
346−~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
347−Once the DMA masks are set, the driver can allocate "consistent" (a.k.a. shared)
348−memory. See Documentation/DMA-API.txt for a full description of
349−the DMA APIs. This section is just a reminder that it needs to be done
350−before enabling DMA on the device.
351−
352−
353−3.5 Initialize device registers
354−~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
355−Some drivers will need specific "capability" fields programmed
356−or other "vendor specific" register initialized or reset.
357−E.g. clearing pending interrupts.
358−
359−
360−3.6 Register IRQ handler
361−~~~~~~~~~~~~~~~~~~~~~~~~
362−While calling request_irq() is the last step described here,
363−this is often just another intermediate step to initialize a device.
364−This step can often be deferred until the device is opened for use.
365−
366−All interrupt handlers for IRQ lines should be registered with IRQF_SHARED
367−and use the devid to map IRQs to devices (remember that all PCI IRQ lines
368−can be shared).
369−
370−request_irq() will associate an interrupt handler and device handle
371−with an interrupt number. Historically interrupt numbers represent
372−IRQ lines which run from the PCI device to the Interrupt controller.
373−With MSI and MSI-X (more below) the interrupt number is a CPU "vector".
374−
375−request_irq() also enables the interrupt. Make sure the device is
376−quiesced and does not have any interrupts pending before registering
377−the interrupt handler.
378−
379−MSI and MSI-X are PCI capabilities. Both are "Message Signaled Interrupts"
380−which deliver interrupts to the CPU via a DMA write to a Local APIC.
381−The fundamental difference between MSI and MSI-X is how multiple
382−"vectors" get allocated. MSI requires contiguous blocks of vectors
383−while MSI-X can allocate several individual ones.
384−
385−MSI capability can be enabled by calling pci_alloc_irq_vectors() with the
386−PCI_IRQ_MSI and/or PCI_IRQ_MSIX flags before calling request_irq(). This
387−causes the PCI support to program CPU vector data into the PCI device
388−capability registers. Many architectures, chip-sets, or BIOSes do NOT
389−support MSI or MSI-X and a call to pci_alloc_irq_vectors with just
390−the PCI_IRQ_MSI and PCI_IRQ_MSIX flags will fail, so try to always
391−specify PCI_IRQ_LEGACY as well.
392−
393−Drivers that have different interrupt handlers for MSI/MSI-X and
394−legacy INTx should chose the right one based on the msi_enabled
395−and msix_enabled flags in the pci_dev structure after calling
396−pci_alloc_irq_vectors.
397−
398−There are (at least) two really good reasons for using MSI:
399−1) MSI is an exclusive interrupt vector by definition.
400− This means the interrupt handler doesn't have to verify
401− its device caused the interrupt.
402−
403−2) MSI avoids DMA/IRQ race conditions. DMA to host memory is guaranteed
404− to be visible to the host CPU(s) when the MSI is delivered. This
405− is important for both data coherency and avoiding stale control data.
406− This guarantee allows the driver to omit MMIO reads to flush
407− the DMA stream.
408−
409−See drivers/infiniband/hw/mthca/ or drivers/net/tg3.c for examples
410−of MSI/MSI-X usage.
411−
412−
413−
414−4. PCI device shutdown
415−~~~~~~~~~~~~~~~~~~~~~~~
416−
417−When a PCI device driver is being unloaded, most of the following
418−steps need to be performed:
419−
420− Disable the device from generating IRQs
421− Release the IRQ (free_irq())
422− Stop all DMA activity
423− Release DMA buffers (both streaming and consistent)
424− Unregister from other subsystems (e.g. scsi or netdev)
425− Disable device from responding to MMIO/IO Port addresses
426− Release MMIO/IO Port resource(s)
427−
428−
429−4.1 Stop IRQs on the device
430−~~~~~~~~~~~~~~~~~~~~~~~~~~~
431−How to do this is chip/device specific. If it's not done, it opens
432−the possibility of a "screaming interrupt" if (and only if)
433−the IRQ is shared with another device.
434−
435−When the shared IRQ handler is "unhooked", the remaining devices
436−using the same IRQ line will still need the IRQ enabled. Thus if the
437−"unhooked" device asserts IRQ line, the system will respond assuming
438−it was one of the remaining devices asserted the IRQ line. Since none
439−of the other devices will handle the IRQ, the system will "hang" until
440−it decides the IRQ isn't going to get handled and masks the IRQ (100,000
441−iterations later). Once the shared IRQ is masked, the remaining devices
442−will stop functioning properly. Not a nice situation.
443−
444−This is another reason to use MSI or MSI-X if it's available.
445−MSI and MSI-X are defined to be exclusive interrupts and thus
446−are not susceptible to the "screaming interrupt" problem.
447−
448−
449−4.2 Release the IRQ
450−~~~~~~~~~~~~~~~~~~~
451−Once the device is quiesced (no more IRQs), one can call free_irq().
452−This function will return control once any pending IRQs are handled,
453−"unhook" the drivers IRQ handler from that IRQ, and finally release
454−the IRQ if no one else is using it.
455−
456−
457−4.3 Stop all DMA activity
458−~~~~~~~~~~~~~~~~~~~~~~~~~
459−It's extremely important to stop all DMA operations BEFORE attempting
460−to deallocate DMA control data. Failure to do so can result in memory
461−corruption, hangs, and on some chip-sets a hard crash.
462−
463−Stopping DMA after stopping the IRQs can avoid races where the
464−IRQ handler might restart DMA engines.
465−
466−While this step sounds obvious and trivial, several "mature" drivers
467−didn't get this step right in the past.
468−
469−
470−4.4 Release DMA buffers
471−~~~~~~~~~~~~~~~~~~~~~~~
472−Once DMA is stopped, clean up streaming DMA first.
473−I.e. unmap data buffers and return buffers to "upstream"
474−owners if there is one.
475−
476−Then clean up "consistent" buffers which contain the control data.
477−
478−See Documentation/DMA-API.txt for details on unmapping interfaces.
479−
480−
481−4.5 Unregister from other subsystems
482−~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
483−Most low level PCI device drivers support some other subsystem
484−like USB, ALSA, SCSI, NetDev, Infiniband, etc. Make sure your
485−driver isn't losing resources from that other subsystem.
486−If this happens, typically the symptom is an Oops (panic) when
487−the subsystem attempts to call into a driver that has been unloaded.
488−
489−
490−4.6 Disable Device from responding to MMIO/IO Port addresses
491−~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
492−io_unmap() MMIO or IO Port resources and then call pci_disable_device().
493−This is the symmetric opposite of pci_enable_device().
494−Do not access device registers after calling pci_disable_device().
495−
496−
497−4.7 Release MMIO/IO Port Resource(s)
498−~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
499−Call pci_release_region() to mark the MMIO or IO Port range as available.
500−Failure to do so usually results in the inability to reload the driver.
501−
502−
503−
504−5. How to access PCI config space
505−~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
506−
507−You can use pci_(read|write)_config_(byte|word|dword) to access the config
508−space of a device represented by struct pci_dev *. All these functions return 0
509−when successful or an error code (PCIBIOS_...) which can be translated to a text
510−string by pcibios_strerror. Most drivers expect that accesses to valid PCI
511−devices don't fail.
512−
513−If you don't have a struct pci_dev available, you can call
514−pci_bus_(read|write)_config_(byte|word|dword) to access a given device
515−and function on that bus.
516−
517−If you access fields in the standard portion of the config header, please
518−use symbolic names of locations and bits declared in <linux/pci.h>.
519−
520−If you need to access Extended PCI Capability registers, just call
521−pci_find_capability() for the particular capability and it will find the
522−corresponding register block for you.
523−
524−
525−
526−6. Other interesting functions
527−~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
528−
529−pci_get_domain_bus_and_slot() Find pci_dev corresponding to given domain,
530− bus and slot and number. If the device is
531− found, its reference count is increased.
532−pci_set_power_state() Set PCI Power Management state (0=D0 ... 3=D3)
533−pci_find_capability() Find specified capability in device's capability
534− list.
535−pci_resource_start() Returns bus start address for a given PCI region
536−pci_resource_end() Returns bus end address for a given PCI region
537−pci_resource_len() Returns the byte length of a PCI region
538−pci_set_drvdata() Set private driver data pointer for a pci_dev
539−pci_get_drvdata() Return private driver data pointer for a pci_dev
540−pci_set_mwi() Enable Memory-Write-Invalidate transactions.
541−pci_clear_mwi() Disable Memory-Write-Invalidate transactions.
542−
543−
544−
545−7. Miscellaneous hints
546−~~~~~~~~~~~~~~~~~~~~~~
547−
548−When displaying PCI device names to the user (for example when a driver wants
549−to tell the user what card has it found), please use pci_name(pci_dev).
550−
551−Always refer to the PCI devices by a pointer to the pci_dev structure.
552−All PCI layer functions use this identification and it's the only
553−reasonable one. Don't use bus/slot/function numbers except for very
554−special purposes -- on systems with multiple primary buses their semantics
555−can be pretty complex.
556−
557−Don't try to turn on Fast Back to Back writes in your driver. All devices
558−on the bus need to be capable of doing it, so this is something which needs
559−to be handled by platform and generic code, not individual drivers.
560−
561−
562−
563−8. Vendor and device identifications
564−~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
565−
566−Do not add new device or vendor IDs to include/linux/pci_ids.h unless they
567−are shared across multiple drivers. You can add private definitions in
568−your driver if they're helpful, or just use plain hex constants.
569−
570−The device IDs are arbitrary hex numbers (vendor controlled) and normally used
571−only in a single location, the pci_device_id table.
572−
573−Please DO submit new vendor/device IDs to http://pci-ids.ucw.cz/.
574−There are mirrors of the pci.ids file at http://pciids.sourceforge.net/
575−and https://github.com/pciutils/pciids.
576−
577−
578−
579−9. Obsolete functions
580−~~~~~~~~~~~~~~~~~~~~~
581−
582−There are several functions which you might come across when trying to
583−port an old driver to the new PCI interface. They are no longer present
584−in the kernel as they aren't compatible with hotplug or PCI domains or
585−having sane locking.
586−
587−pci_find_device() Superseded by pci_get_device()
588−pci_find_subsys() Superseded by pci_get_subsys()
589−pci_find_slot() Superseded by pci_get_domain_bus_and_slot()
590−pci_get_slot() Superseded by pci_get_domain_bus_and_slot()
591−
592−
593−The alternative is the traditional PCI device driver that walks PCI
594−device lists. This is still possible but discouraged.
595−
596−
597−
598−10. MMIO Space and "Write Posting"
599−~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
600−
601−Converting a driver from using I/O Port space to using MMIO space
602−often requires some additional changes. Specifically, "write posting"
603−needs to be handled. Many drivers (e.g. tg3, acenic, sym53c8xx_2)
604−already do this. I/O Port space guarantees write transactions reach the PCI
605−device before the CPU can continue. Writes to MMIO space allow the CPU
606−to continue before the transaction reaches the PCI device. HW weenies
607−call this "Write Posting" because the write completion is "posted" to
608−the CPU before the transaction has reached its destination.
609−
610−Thus, timing sensitive code should add readl() where the CPU is
611−expected to wait before doing other work. The classic "bit banging"
612−sequence works fine for I/O Port space:
613−
614− for (i = 8; --i; val >>= 1) {
615− outb(val & 1, ioport_reg); /* write bit */
616− udelay(10);
617− }
618−
619−The same sequence for MMIO space should be:
620−
621− for (i = 8; --i; val >>= 1) {
622− writeb(val & 1, mmio_reg); /* write bit */
623− readb(safe_mmio_reg); /* flush posted write */
624− udelay(10);
625− }
626−
627−It is important that "safe_mmio_reg" not have any side effects that
628−interferes with the correct operation of the device.
629−
630−Another case to watch out for is when resetting a PCI device. Use PCI
631−Configuration space reads to flush the writel(). This will gracefully
632−handle the PCI master abort on all platforms if the PCI device is
633−expected to not respond to a readl(). Most x86 platforms will allow
634−MMIO reads to master abort (a.k.a. "Soft Fail") and return garbage
635−(e.g. ~0). But many RISC platforms will crash (a.k.a."Hard Fail").
636−
Documentation/PCI/pcieaer-howto.rst+311−0
@@ -0,0 +1,311 @@
1+.. SPDX-License-Identifier: GPL-2.0
2+.. include:: <isonum.txt>
3+
4+===========================================================
5+The PCI Express Advanced Error Reporting Driver Guide HOWTO
6+===========================================================
7+
8+:Authors: - T. Long Nguyen <tom.l.nguyen@intel.com>
9+ - Yanmin Zhang <yanmin.zhang@intel.com>
10+
11+:Copyright: |copy| 2006 Intel Corporation
12+
13+Overview
14+===========
15+
16+About this guide
17+----------------
18+
19+This guide describes the basics of the PCI Express Advanced Error
20+Reporting (AER) driver and provides information on how to use it, as
21+well as how to enable the drivers of endpoint devices to conform with
22+PCI Express AER driver.
23+
24+
25+What is the PCI Express AER Driver?
26+-----------------------------------
27+
28+PCI Express error signaling can occur on the PCI Express link itself
29+or on behalf of transactions initiated on the link. PCI Express
30+defines two error reporting paradigms: the baseline capability and
31+the Advanced Error Reporting capability. The baseline capability is
32+required of all PCI Express components providing a minimum defined
33+set of error reporting requirements. Advanced Error Reporting
34+capability is implemented with a PCI Express advanced error reporting
35+extended capability structure providing more robust error reporting.
36+
37+The PCI Express AER driver provides the infrastructure to support PCI
38+Express Advanced Error Reporting capability. The PCI Express AER
39+driver provides three basic functions:
40+
41+ - Gathers the comprehensive error information if errors occurred.
42+ - Reports error to the users.
43+ - Performs error recovery actions.
44+
45+AER driver only attaches root ports which support PCI-Express AER
46+capability.
47+
48+
49+User Guide
50+==========
51+
52+Include the PCI Express AER Root Driver into the Linux Kernel
53+-------------------------------------------------------------
54+
55+The PCI Express AER Root driver is a Root Port service driver attached
56+to the PCI Express Port Bus driver. If a user wants to use it, the driver
57+has to be compiled. Option CONFIG_PCIEAER supports this capability. It
58+depends on CONFIG_PCIEPORTBUS, so pls. set CONFIG_PCIEPORTBUS=y and
59+CONFIG_PCIEAER = y.
60+
61+Load PCI Express AER Root Driver
62+--------------------------------
63+
64+Some systems have AER support in firmware. Enabling Linux AER support at
65+the same time the firmware handles AER may result in unpredictable
66+behavior. Therefore, Linux does not handle AER events unless the firmware
67+grants AER control to the OS via the ACPI _OSC method. See the PCI FW 3.0
68+Specification for details regarding _OSC usage.
69+
70+AER error output
71+----------------
72+
73+When a PCIe AER error is captured, an error message will be output to
74+console. If it's a correctable error, it is output as a warning.
75+Otherwise, it is printed as an error. So users could choose different
76+log level to filter out correctable error messages.
77+
78+Below shows an example::
79+
80+ 0000:50:00.0: PCIe Bus Error: severity=Uncorrected (Fatal), type=Transaction Layer, id=0500(Requester ID)
81+ 0000:50:00.0: device [8086:0329] error status/mask=00100000/00000000
82+ 0000:50:00.0: [20] Unsupported Request (First)
83+ 0000:50:00.0: TLP Header: 04000001 00200a03 05010000 00050100
84+
85+In the example, 'Requester ID' means the ID of the device who sends
86+the error message to root port. Pls. refer to pci express specs for
87+other fields.
88+
89+AER Statistics / Counters
90+-------------------------
91+
92+When PCIe AER errors are captured, the counters / statistics are also exposed
93+in the form of sysfs attributes which are documented at
94+Documentation/ABI/testing/sysfs-bus-pci-devices-aer_stats
95+
96+Developer Guide
97+===============
98+
99+To enable AER aware support requires a software driver to configure
100+the AER capability structure within its device and to provide callbacks.
101+
102+To support AER better, developers need understand how AER does work
103+firstly.
104+
105+PCI Express errors are classified into two types: correctable errors
106+and uncorrectable errors. This classification is based on the impacts
107+of those errors, which may result in degraded performance or function
108+failure.
109+
110+Correctable errors pose no impacts on the functionality of the
111+interface. The PCI Express protocol can recover without any software
112+intervention or any loss of data. These errors are detected and
113+corrected by hardware. Unlike correctable errors, uncorrectable
114+errors impact functionality of the interface. Uncorrectable errors
115+can cause a particular transaction or a particular PCI Express link
116+to be unreliable. Depending on those error conditions, uncorrectable
117+errors are further classified into non-fatal errors and fatal errors.
118+Non-fatal errors cause the particular transaction to be unreliable,
119+but the PCI Express link itself is fully functional. Fatal errors, on
120+the other hand, cause the link to be unreliable.
121+
122+When AER is enabled, a PCI Express device will automatically send an
123+error message to the PCIe root port above it when the device captures
124+an error. The Root Port, upon receiving an error reporting message,
125+internally processes and logs the error message in its PCI Express
126+capability structure. Error information being logged includes storing
127+the error reporting agent's requestor ID into the Error Source
128+Identification Registers and setting the error bits of the Root Error
129+Status Register accordingly. If AER error reporting is enabled in Root
130+Error Command Register, the Root Port generates an interrupt if an
131+error is detected.
132+
133+Note that the errors as described above are related to the PCI Express
134+hierarchy and links. These errors do not include any device specific
135+errors because device specific errors will still get sent directly to
136+the device driver.
137+
138+Configure the AER capability structure
139+--------------------------------------
140+
141+AER aware drivers of PCI Express component need change the device
142+control registers to enable AER. They also could change AER registers,
143+including mask and severity registers. Helper function
144+pci_enable_pcie_error_reporting could be used to enable AER. See
145+section 3.3.
146+
147+Provide callbacks
148+-----------------
149+
150+callback reset_link to reset pci express link
151+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
152+
153+This callback is used to reset the pci express physical link when a
154+fatal error happens. The root port aer service driver provides a
155+default reset_link function, but different upstream ports might
156+have different specifications to reset pci express link, so all
157+upstream ports should provide their own reset_link functions.
158+
159+In struct pcie_port_service_driver, a new pointer, reset_link, is
160+added.
161+::
162+
163+ pci_ers_result_t (*reset_link) (struct pci_dev *dev);
164+
165+Section 3.2.2.2 provides more detailed info on when to call
166+reset_link.
167+
168+PCI error-recovery callbacks
169+~~~~~~~~~~~~~~~~~~~~~~~~~~~~
170+
171+The PCI Express AER Root driver uses error callbacks to coordinate
172+with downstream device drivers associated with a hierarchy in question
173+when performing error recovery actions.
174+
175+Data struct pci_driver has a pointer, err_handler, to point to
176+pci_error_handlers who consists of a couple of callback function
177+pointers. AER driver follows the rules defined in
178+pci-error-recovery.txt except pci express specific parts (e.g.
179+reset_link). Pls. refer to pci-error-recovery.txt for detailed
180+definitions of the callbacks.
181+
182+Below sections specify when to call the error callback functions.
183+
184+Correctable errors
185+~~~~~~~~~~~~~~~~~~
186+
187+Correctable errors pose no impacts on the functionality of
188+the interface. The PCI Express protocol can recover without any
189+software intervention or any loss of data. These errors do not
190+require any recovery actions. The AER driver clears the device's
191+correctable error status register accordingly and logs these errors.
192+
193+Non-correctable (non-fatal and fatal) errors
194+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
195+
196+If an error message indicates a non-fatal error, performing link reset
197+at upstream is not required. The AER driver calls error_detected(dev,
198+pci_channel_io_normal) to all drivers associated within a hierarchy in
199+question. for example::
200+
201+ EndPoint<==>DownstreamPort B<==>UpstreamPort A<==>RootPort
202+
203+If Upstream port A captures an AER error, the hierarchy consists of
204+Downstream port B and EndPoint.
205+
206+A driver may return PCI_ERS_RESULT_CAN_RECOVER,
207+PCI_ERS_RESULT_DISCONNECT, or PCI_ERS_RESULT_NEED_RESET, depending on
208+whether it can recover or the AER driver calls mmio_enabled as next.
209+
210+If an error message indicates a fatal error, kernel will broadcast
211+error_detected(dev, pci_channel_io_frozen) to all drivers within
212+a hierarchy in question. Then, performing link reset at upstream is
213+necessary. As different kinds of devices might use different approaches
214+to reset link, AER port service driver is required to provide the
215+function to reset link. Firstly, kernel looks for if the upstream
216+component has an aer driver. If it has, kernel uses the reset_link
217+callback of the aer driver. If the upstream component has no aer driver
218+and the port is downstream port, we will perform a hot reset as the
219+default by setting the Secondary Bus Reset bit of the Bridge Control
220+register associated with the downstream port. As for upstream ports,
221+they should provide their own aer service drivers with reset_link
222+function. If error_detected returns PCI_ERS_RESULT_CAN_RECOVER and
223+reset_link returns PCI_ERS_RESULT_RECOVERED, the error handling goes
224+to mmio_enabled.
225+
226+helper functions
227+----------------
228+::
229+
230+ int pci_enable_pcie_error_reporting(struct pci_dev *dev);
231+
232+pci_enable_pcie_error_reporting enables the device to send error
233+messages to root port when an error is detected. Note that devices
234+don't enable the error reporting by default, so device drivers need
235+call this function to enable it.
236+
237+::
238+
239+ int pci_disable_pcie_error_reporting(struct pci_dev *dev);
240+
241+pci_disable_pcie_error_reporting disables the device to send error
242+messages to root port when an error is detected.
243+
244+::
245+
246+ int pci_cleanup_aer_uncorrect_error_status(struct pci_dev *dev);`
247+
248+pci_cleanup_aer_uncorrect_error_status cleanups the uncorrectable
249+error status register.
250+
251+Frequent Asked Questions
252+------------------------
253+
254+Q:
255+ What happens if a PCI Express device driver does not provide an
256+ error recovery handler (pci_driver->err_handler is equal to NULL)?
257+
258+A:
259+ The devices attached with the driver won't be recovered. If the
260+ error is fatal, kernel will print out warning messages. Please refer
261+ to section 3 for more information.
262+
263+Q:
264+ What happens if an upstream port service driver does not provide
265+ callback reset_link?
266+
267+A:
268+ Fatal error recovery will fail if the errors are reported by the
269+ upstream ports who are attached by the service driver.
270+
271+Q:
272+ How does this infrastructure deal with driver that is not PCI
273+ Express aware?
274+
275+A:
276+ This infrastructure calls the error callback functions of the
277+ driver when an error happens. But if the driver is not aware of
278+ PCI Express, the device might not report its own errors to root
279+ port.
280+
281+Q:
282+ What modifications will that driver need to make it compatible
283+ with the PCI Express AER Root driver?
284+
285+A:
286+ It could call the helper functions to enable AER in devices and
287+ cleanup uncorrectable status register. Pls. refer to section 3.3.
288+
289+
290+Software error injection
291+========================
292+
293+Debugging PCIe AER error recovery code is quite difficult because it
294+is hard to trigger real hardware errors. Software based error
295+injection can be used to fake various kinds of PCIe errors.
296+
297+First you should enable PCIe AER software error injection in kernel
298+configuration, that is, following item should be in your .config.
299+
300+CONFIG_PCIEAER_INJECT=y or CONFIG_PCIEAER_INJECT=m
301+
302+After reboot with new kernel or insert the module, a device file named
303+/dev/aer_inject should be created.
304+
305+Then, you need a user space tool named aer-inject, which can be gotten
306+from:
307+
308+ https://git.kernel.org/cgit/linux/kernel/git/gong.chen/aer-inject.git/
309+
310+More information about aer-inject can be found in the document comes
311+with its source code.
Documentation/PCI/pcieaer-howto.txt+0−267
@@ -1,267 +0,0 @@
1− The PCI Express Advanced Error Reporting Driver Guide HOWTO
2− T. Long Nguyen <tom.l.nguyen@intel.com>
3− Yanmin Zhang <yanmin.zhang@intel.com>
4− 07/29/2006
5−
6−
7−1. Overview
8−
9−1.1 About this guide
10−
11−This guide describes the basics of the PCI Express Advanced Error
12−Reporting (AER) driver and provides information on how to use it, as
13−well as how to enable the drivers of endpoint devices to conform with
14−PCI Express AER driver.
15−
16−1.2 Copyright (C) Intel Corporation 2006.
17−
18−1.3 What is the PCI Express AER Driver?
19−
20−PCI Express error signaling can occur on the PCI Express link itself
21−or on behalf of transactions initiated on the link. PCI Express
22−defines two error reporting paradigms: the baseline capability and
23−the Advanced Error Reporting capability. The baseline capability is
24−required of all PCI Express components providing a minimum defined
25−set of error reporting requirements. Advanced Error Reporting
26−capability is implemented with a PCI Express advanced error reporting
27−extended capability structure providing more robust error reporting.
28−
29−The PCI Express AER driver provides the infrastructure to support PCI
30−Express Advanced Error Reporting capability. The PCI Express AER
31−driver provides three basic functions:
32−
33−- Gathers the comprehensive error information if errors occurred.
34−- Reports error to the users.
35−- Performs error recovery actions.
36−
37−AER driver only attaches root ports which support PCI-Express AER
38−capability.
39−
40−
41−2. User Guide
42−
43−2.1 Include the PCI Express AER Root Driver into the Linux Kernel
44−
45−The PCI Express AER Root driver is a Root Port service driver attached
46−to the PCI Express Port Bus driver. If a user wants to use it, the driver
47−has to be compiled. Option CONFIG_PCIEAER supports this capability. It
48−depends on CONFIG_PCIEPORTBUS, so pls. set CONFIG_PCIEPORTBUS=y and
49−CONFIG_PCIEAER = y.
50−
51−2.2 Load PCI Express AER Root Driver
52−
53−Some systems have AER support in firmware. Enabling Linux AER support at
54−the same time the firmware handles AER may result in unpredictable
55−behavior. Therefore, Linux does not handle AER events unless the firmware
56−grants AER control to the OS via the ACPI _OSC method. See the PCI FW 3.0
57−Specification for details regarding _OSC usage.
58−
59−2.3 AER error output
60−
61−When a PCIe AER error is captured, an error message will be output to
62−console. If it's a correctable error, it is output as a warning.
63−Otherwise, it is printed as an error. So users could choose different
64−log level to filter out correctable error messages.
65−
66−Below shows an example:
67−0000:50:00.0: PCIe Bus Error: severity=Uncorrected (Fatal), type=Transaction Layer, id=0500(Requester ID)
68−0000:50:00.0: device [8086:0329] error status/mask=00100000/00000000
69−0000:50:00.0: [20] Unsupported Request (First)
70−0000:50:00.0: TLP Header: 04000001 00200a03 05010000 00050100
71−
72−In the example, 'Requester ID' means the ID of the device who sends
73−the error message to root port. Pls. refer to pci express specs for
74−other fields.
75−
76−2.4 AER Statistics / Counters
77−
78−When PCIe AER errors are captured, the counters / statistics are also exposed
79−in the form of sysfs attributes which are documented at
80−Documentation/ABI/testing/sysfs-bus-pci-devices-aer_stats
81−
82−3. Developer Guide
83−
84−To enable AER aware support requires a software driver to configure
85−the AER capability structure within its device and to provide callbacks.
86−
87−To support AER better, developers need understand how AER does work
88−firstly.
89−
90−PCI Express errors are classified into two types: correctable errors
91−and uncorrectable errors. This classification is based on the impacts
92−of those errors, which may result in degraded performance or function
93−failure.
94−
95−Correctable errors pose no impacts on the functionality of the
96−interface. The PCI Express protocol can recover without any software
97−intervention or any loss of data. These errors are detected and
98−corrected by hardware. Unlike correctable errors, uncorrectable
99−errors impact functionality of the interface. Uncorrectable errors
100−can cause a particular transaction or a particular PCI Express link
101−to be unreliable. Depending on those error conditions, uncorrectable
102−errors are further classified into non-fatal errors and fatal errors.
103−Non-fatal errors cause the particular transaction to be unreliable,
104−but the PCI Express link itself is fully functional. Fatal errors, on
105−the other hand, cause the link to be unreliable.
106−
107−When AER is enabled, a PCI Express device will automatically send an
108−error message to the PCIe root port above it when the device captures
109−an error. The Root Port, upon receiving an error reporting message,
110−internally processes and logs the error message in its PCI Express
111−capability structure. Error information being logged includes storing
112−the error reporting agent's requestor ID into the Error Source
113−Identification Registers and setting the error bits of the Root Error
114−Status Register accordingly. If AER error reporting is enabled in Root
115−Error Command Register, the Root Port generates an interrupt if an
116−error is detected.
117−
118−Note that the errors as described above are related to the PCI Express
119−hierarchy and links. These errors do not include any device specific
120−errors because device specific errors will still get sent directly to
121−the device driver.
122−
123−3.1 Configure the AER capability structure
124−
125−AER aware drivers of PCI Express component need change the device
126−control registers to enable AER. They also could change AER registers,
127−including mask and severity registers. Helper function
128−pci_enable_pcie_error_reporting could be used to enable AER. See
129−section 3.3.
130−
131−3.2. Provide callbacks
132−
133−3.2.1 callback reset_link to reset pci express link
134−
135−This callback is used to reset the pci express physical link when a
136−fatal error happens. The root port aer service driver provides a
137−default reset_link function, but different upstream ports might
138−have different specifications to reset pci express link, so all
139−upstream ports should provide their own reset_link functions.
140−
141−In struct pcie_port_service_driver, a new pointer, reset_link, is
142−added.
143−
144−pci_ers_result_t (*reset_link) (struct pci_dev *dev);
145−
146−Section 3.2.2.2 provides more detailed info on when to call
147−reset_link.
148−
149−3.2.2 PCI error-recovery callbacks
150−
151−The PCI Express AER Root driver uses error callbacks to coordinate
152−with downstream device drivers associated with a hierarchy in question
153−when performing error recovery actions.
154−
155−Data struct pci_driver has a pointer, err_handler, to point to
156−pci_error_handlers who consists of a couple of callback function
157−pointers. AER driver follows the rules defined in
158−pci-error-recovery.txt except pci express specific parts (e.g.
159−reset_link). Pls. refer to pci-error-recovery.txt for detailed
160−definitions of the callbacks.
161−
162−Below sections specify when to call the error callback functions.
163−
164−3.2.2.1 Correctable errors
165−
166−Correctable errors pose no impacts on the functionality of
167−the interface. The PCI Express protocol can recover without any
168−software intervention or any loss of data. These errors do not
169−require any recovery actions. The AER driver clears the device's
170−correctable error status register accordingly and logs these errors.
171−
172−3.2.2.2 Non-correctable (non-fatal and fatal) errors
173−
174−If an error message indicates a non-fatal error, performing link reset
175−at upstream is not required. The AER driver calls error_detected(dev,
176−pci_channel_io_normal) to all drivers associated within a hierarchy in
177−question. for example,
178−EndPoint<==>DownstreamPort B<==>UpstreamPort A<==>RootPort.
179−If Upstream port A captures an AER error, the hierarchy consists of
180−Downstream port B and EndPoint.
181−
182−A driver may return PCI_ERS_RESULT_CAN_RECOVER,
183−PCI_ERS_RESULT_DISCONNECT, or PCI_ERS_RESULT_NEED_RESET, depending on
184−whether it can recover or the AER driver calls mmio_enabled as next.
185−
186−If an error message indicates a fatal error, kernel will broadcast
187−error_detected(dev, pci_channel_io_frozen) to all drivers within
188−a hierarchy in question. Then, performing link reset at upstream is
189−necessary. As different kinds of devices might use different approaches
190−to reset link, AER port service driver is required to provide the
191−function to reset link. Firstly, kernel looks for if the upstream
192−component has an aer driver. If it has, kernel uses the reset_link
193−callback of the aer driver. If the upstream component has no aer driver
194−and the port is downstream port, we will perform a hot reset as the
195−default by setting the Secondary Bus Reset bit of the Bridge Control
196−register associated with the downstream port. As for upstream ports,
197−they should provide their own aer service drivers with reset_link
198−function. If error_detected returns PCI_ERS_RESULT_CAN_RECOVER and
199−reset_link returns PCI_ERS_RESULT_RECOVERED, the error handling goes
200−to mmio_enabled.
201−
202−3.3 helper functions
203−
204−3.3.1 int pci_enable_pcie_error_reporting(struct pci_dev *dev);
205−pci_enable_pcie_error_reporting enables the device to send error
206−messages to root port when an error is detected. Note that devices
207−don't enable the error reporting by default, so device drivers need
208−call this function to enable it.
209−
210−3.3.2 int pci_disable_pcie_error_reporting(struct pci_dev *dev);
211−pci_disable_pcie_error_reporting disables the device to send error
212−messages to root port when an error is detected.
213−
214−3.3.3 int pci_cleanup_aer_uncorrect_error_status(struct pci_dev *dev);
215−pci_cleanup_aer_uncorrect_error_status cleanups the uncorrectable
216−error status register.
217−
218−3.4 Frequent Asked Questions
219−
220−Q: What happens if a PCI Express device driver does not provide an
221−error recovery handler (pci_driver->err_handler is equal to NULL)?
222−
223−A: The devices attached with the driver won't be recovered. If the
224−error is fatal, kernel will print out warning messages. Please refer
225−to section 3 for more information.
226−
227−Q: What happens if an upstream port service driver does not provide
228−callback reset_link?
229−
230−A: Fatal error recovery will fail if the errors are reported by the
231−upstream ports who are attached by the service driver.
232−
233−Q: How does this infrastructure deal with driver that is not PCI
234−Express aware?
235−
236−A: This infrastructure calls the error callback functions of the
237−driver when an error happens. But if the driver is not aware of
238−PCI Express, the device might not report its own errors to root
239−port.
240−
241−Q: What modifications will that driver need to make it compatible
242−with the PCI Express AER Root driver?
243−
244−A: It could call the helper functions to enable AER in devices and
245−cleanup uncorrectable status register. Pls. refer to section 3.3.
246−
247−
248−4. Software error injection
249−
250−Debugging PCIe AER error recovery code is quite difficult because it
251−is hard to trigger real hardware errors. Software based error
252−injection can be used to fake various kinds of PCIe errors.
253−
254−First you should enable PCIe AER software error injection in kernel
255−configuration, that is, following item should be in your .config.
256−
257−CONFIG_PCIEAER_INJECT=y or CONFIG_PCIEAER_INJECT=m
258−
259−After reboot with new kernel or insert the module, a device file named
260−/dev/aer_inject should be created.
261−
262−Then, you need a user space tool named aer-inject, which can be gotten
263−from:
264− https://git.kernel.org/cgit/linux/kernel/git/gong.chen/aer-inject.git/
265−
266−More information about aer-inject can be found in the document comes
267−with its source code.
Documentation/PCI/picebus-howto.rst+220−0
@@ -0,0 +1,220 @@
1+.. SPDX-License-Identifier: GPL-2.0
2+.. include:: <isonum.txt>
3+
4+===========================================
5+The PCI Express Port Bus Driver Guide HOWTO
6+===========================================
7+
8+:Author: Tom L Nguyen tom.l.nguyen@intel.com 11/03/2004
9+:Copyright: |copy| 2004 Intel Corporation
10+
11+About this guide
12+================
13+
14+This guide describes the basics of the PCI Express Port Bus driver
15+and provides information on how to enable the service drivers to
16+register/unregister with the PCI Express Port Bus Driver.
17+
18+
19+What is the PCI Express Port Bus Driver
20+=======================================
21+
22+A PCI Express Port is a logical PCI-PCI Bridge structure. There
23+are two types of PCI Express Port: the Root Port and the Switch
24+Port. The Root Port originates a PCI Express link from a PCI Express
25+Root Complex and the Switch Port connects PCI Express links to
26+internal logical PCI buses. The Switch Port, which has its secondary
27+bus representing the switch's internal routing logic, is called the
28+switch's Upstream Port. The switch's Downstream Port is bridging from
29+switch's internal routing bus to a bus representing the downstream
30+PCI Express link from the PCI Express Switch.
31+
32+A PCI Express Port can provide up to four distinct functions,
33+referred to in this document as services, depending on its port type.
34+PCI Express Port's services include native hotplug support (HP),
35+power management event support (PME), advanced error reporting
36+support (AER), and virtual channel support (VC). These services may
37+be handled by a single complex driver or be individually distributed
38+and handled by corresponding service drivers.
39+
40+Why use the PCI Express Port Bus Driver?
41+========================================
42+
43+In existing Linux kernels, the Linux Device Driver Model allows a
44+physical device to be handled by only a single driver. The PCI
45+Express Port is a PCI-PCI Bridge device with multiple distinct
46+services. To maintain a clean and simple solution each service
47+may have its own software service driver. In this case several
48+service drivers will compete for a single PCI-PCI Bridge device.
49+For example, if the PCI Express Root Port native hotplug service
50+driver is loaded first, it claims a PCI-PCI Bridge Root Port. The
51+kernel therefore does not load other service drivers for that Root
52+Port. In other words, it is impossible to have multiple service
53+drivers load and run on a PCI-PCI Bridge device simultaneously
54+using the current driver model.
55+
56+To enable multiple service drivers running simultaneously requires
57+having a PCI Express Port Bus driver, which manages all populated
58+PCI Express Ports and distributes all provided service requests
59+to the corresponding service drivers as required. Some key
60+advantages of using the PCI Express Port Bus driver are listed below:
61+
62+ - Allow multiple service drivers to run simultaneously on
63+ a PCI-PCI Bridge Port device.
64+
65+ - Allow service drivers implemented in an independent
66+ staged approach.
67+
68+ - Allow one service driver to run on multiple PCI-PCI Bridge
69+ Port devices.
70+
71+ - Manage and distribute resources of a PCI-PCI Bridge Port
72+ device to requested service drivers.
73+
74+Configuring the PCI Express Port Bus Driver vs. Service Drivers
75+===============================================================
76+
77+Including the PCI Express Port Bus Driver Support into the Kernel
78+-----------------------------------------------------------------
79+
80+Including the PCI Express Port Bus driver depends on whether the PCI
81+Express support is included in the kernel config. The kernel will
82+automatically include the PCI Express Port Bus driver as a kernel
83+driver when the PCI Express support is enabled in the kernel.
84+
85+Enabling Service Driver Support
86+-------------------------------
87+
88+PCI device drivers are implemented based on Linux Device Driver Model.
89+All service drivers are PCI device drivers. As discussed above, it is
90+impossible to load any service driver once the kernel has loaded the
91+PCI Express Port Bus Driver. To meet the PCI Express Port Bus Driver
92+Model requires some minimal changes on existing service drivers that
93+imposes no impact on the functionality of existing service drivers.
94+
95+A service driver is required to use the two APIs shown below to
96+register its service with the PCI Express Port Bus driver (see
97+section 5.2.1 & 5.2.2). It is important that a service driver
98+initializes the pcie_port_service_driver data structure, included in
99+header file /include/linux/pcieport_if.h, before calling these APIs.
100+Failure to do so will result an identity mismatch, which prevents
101+the PCI Express Port Bus driver from loading a service driver.
102+
103+pcie_port_service_register
104+~~~~~~~~~~~~~~~~~~~~~~~~~~
105+::
106+
107+ int pcie_port_service_register(struct pcie_port_service_driver *new)
108+
109+This API replaces the Linux Driver Model's pci_register_driver API. A
110+service driver should always calls pcie_port_service_register at
111+module init. Note that after service driver being loaded, calls
112+such as pci_enable_device(dev) and pci_set_master(dev) are no longer
113+necessary since these calls are executed by the PCI Port Bus driver.
114+
115+pcie_port_service_unregister
116+~~~~~~~~~~~~~~~~~~~~~~~~~~~~
117+::
118+
119+ void pcie_port_service_unregister(struct pcie_port_service_driver *new)
120+
121+pcie_port_service_unregister replaces the Linux Driver Model's
122+pci_unregister_driver. It's always called by service driver when a
123+module exits.
124+
125+Sample Code
126+~~~~~~~~~~~
127+
128+Below is sample service driver code to initialize the port service
129+driver data structure.
130+::
131+
132+ static struct pcie_port_service_id service_id[] = { {
133+ .vendor = PCI_ANY_ID,
134+ .device = PCI_ANY_ID,
135+ .port_type = PCIE_RC_PORT,
136+ .service_type = PCIE_PORT_SERVICE_AER,
137+ }, { /* end: all zeroes */ }
138+ };
139+
140+ static struct pcie_port_service_driver root_aerdrv = {
141+ .name = (char *)device_name,
142+ .id_table = &service_id[0],
143+
144+ .probe = aerdrv_load,
145+ .remove = aerdrv_unload,
146+
147+ .suspend = aerdrv_suspend,
148+ .resume = aerdrv_resume,
149+ };
150+
151+Below is a sample code for registering/unregistering a service
152+driver.
153+::
154+
155+ static int __init aerdrv_service_init(void)
156+ {
157+ int retval = 0;
158+
159+ retval = pcie_port_service_register(&root_aerdrv);
160+ if (!retval) {
161+ /*
162+ * FIX ME
163+ */
164+ }
165+ return retval;
166+ }
167+
168+ static void __exit aerdrv_service_exit(void)
169+ {
170+ pcie_port_service_unregister(&root_aerdrv);
171+ }
172+
173+ module_init(aerdrv_service_init);
174+ module_exit(aerdrv_service_exit);
175+
176+Possible Resource Conflicts
177+===========================
178+
179+Since all service drivers of a PCI-PCI Bridge Port device are
180+allowed to run simultaneously, below lists a few of possible resource
181+conflicts with proposed solutions.
182+
183+MSI and MSI-X Vector Resource
184+-----------------------------
185+
186+Once MSI or MSI-X interrupts are enabled on a device, it stays in this
187+mode until they are disabled again. Since service drivers of the same
188+PCI-PCI Bridge port share the same physical device, if an individual
189+service driver enables or disables MSI/MSI-X mode it may result
190+unpredictable behavior.
191+
192+To avoid this situation all service drivers are not permitted to
193+switch interrupt mode on its device. The PCI Express Port Bus driver
194+is responsible for determining the interrupt mode and this should be
195+transparent to service drivers. Service drivers need to know only
196+the vector IRQ assigned to the field irq of struct pcie_device, which
197+is passed in when the PCI Express Port Bus driver probes each service
198+driver. Service drivers should use (struct pcie_device*)dev->irq to
199+call request_irq/free_irq. In addition, the interrupt mode is stored
200+in the field interrupt_mode of struct pcie_device.
201+
202+PCI Memory/IO Mapped Regions
203+----------------------------
204+
205+Service drivers for PCI Express Power Management (PME), Advanced
206+Error Reporting (AER), Hot-Plug (HP) and Virtual Channel (VC) access
207+PCI configuration space on the PCI Express port. In all cases the
208+registers accessed are independent of each other. This patch assumes
209+that all service drivers will be well behaved and not overwrite
210+other service driver's configuration settings.
211+
212+PCI Config Registers
213+--------------------
214+
215+Each service driver runs its PCI config operations on its own
216+capability structure except the PCI Express capability structure, in
217+which Root Control register and Device Control register are shared
218+between PME and AER. This patch assumes that all service drivers
219+will be well behaved and not overwrite other service driver's
220+configuration settings.
Documentation/RCU/UP.rst+143−0
@@ -0,0 +1,143 @@
1+.. _up_doc:
2+
3+RCU on Uniprocessor Systems
4+===========================
5+
6+A common misconception is that, on UP systems, the call_rcu() primitive
7+may immediately invoke its function. The basis of this misconception
8+is that since there is only one CPU, it should not be necessary to
9+wait for anything else to get done, since there are no other CPUs for
10+anything else to be happening on. Although this approach will *sort of*
11+work a surprising amount of the time, it is a very bad idea in general.
12+This document presents three examples that demonstrate exactly how bad
13+an idea this is.
14+
15+Example 1: softirq Suicide
16+--------------------------
17+
18+Suppose that an RCU-based algorithm scans a linked list containing
19+elements A, B, and C in process context, and can delete elements from
20+this same list in softirq context. Suppose that the process-context scan
21+is referencing element B when it is interrupted by softirq processing,
22+which deletes element B, and then invokes call_rcu() to free element B
23+after a grace period.
24+
25+Now, if call_rcu() were to directly invoke its arguments, then upon return
26+from softirq, the list scan would find itself referencing a newly freed
27+element B. This situation can greatly decrease the life expectancy of
28+your kernel.
29+
30+This same problem can occur if call_rcu() is invoked from a hardware
31+interrupt handler.
32+
33+Example 2: Function-Call Fatality
34+---------------------------------
35+
36+Of course, one could avert the suicide described in the preceding example
37+by having call_rcu() directly invoke its arguments only if it was called
38+from process context. However, this can fail in a similar manner.
39+
40+Suppose that an RCU-based algorithm again scans a linked list containing
41+elements A, B, and C in process contexts, but that it invokes a function
42+on each element as it is scanned. Suppose further that this function
43+deletes element B from the list, then passes it to call_rcu() for deferred
44+freeing. This may be a bit unconventional, but it is perfectly legal
45+RCU usage, since call_rcu() must wait for a grace period to elapse.
46+Therefore, in this case, allowing call_rcu() to immediately invoke
47+its arguments would cause it to fail to make the fundamental guarantee
48+underlying RCU, namely that call_rcu() defers invoking its arguments until
49+all RCU read-side critical sections currently executing have completed.
50+
51+Quick Quiz #1:
52+ Why is it *not* legal to invoke synchronize_rcu() in this case?
53+
54+:ref:`Answers to Quick Quiz <answer_quick_quiz_up>`
55+
56+Example 3: Death by Deadlock
57+----------------------------
58+
59+Suppose that call_rcu() is invoked while holding a lock, and that the
60+callback function must acquire this same lock. In this case, if
61+call_rcu() were to directly invoke the callback, the result would
62+be self-deadlock.
63+
64+In some cases, it would possible to restructure to code so that
65+the call_rcu() is delayed until after the lock is released. However,
66+there are cases where this can be quite ugly:
67+
68+1. If a number of items need to be passed to call_rcu() within
69+ the same critical section, then the code would need to create
70+ a list of them, then traverse the list once the lock was
71+ released.
72+
73+2. In some cases, the lock will be held across some kernel API,
74+ so that delaying the call_rcu() until the lock is released
75+ requires that the data item be passed up via a common API.
76+ It is far better to guarantee that callbacks are invoked
77+ with no locks held than to have to modify such APIs to allow
78+ arbitrary data items to be passed back up through them.
79+
80+If call_rcu() directly invokes the callback, painful locking restrictions
81+or API changes would be required.
82+
83+Quick Quiz #2:
84+ What locking restriction must RCU callbacks respect?
85+
86+:ref:`Answers to Quick Quiz <answer_quick_quiz_up>`
87+
88+Summary
89+-------
90+
91+Permitting call_rcu() to immediately invoke its arguments breaks RCU,
92+even on a UP system. So do not do it! Even on a UP system, the RCU
93+infrastructure *must* respect grace periods, and *must* invoke callbacks
94+from a known environment in which no locks are held.
95+
96+Note that it *is* safe for synchronize_rcu() to return immediately on
97+UP systems, including PREEMPT SMP builds running on UP systems.
98+
99+Quick Quiz #3:
100+ Why can't synchronize_rcu() return immediately on UP systems running
101+ preemptable RCU?
102+
103+.. _answer_quick_quiz_up:
104+
105+Answer to Quick Quiz #1:
106+ Why is it *not* legal to invoke synchronize_rcu() in this case?
107+
108+ Because the calling function is scanning an RCU-protected linked
109+ list, and is therefore within an RCU read-side critical section.
110+ Therefore, the called function has been invoked within an RCU
111+ read-side critical section, and is not permitted to block.
112+
113+Answer to Quick Quiz #2:
114+ What locking restriction must RCU callbacks respect?
115+
116+ Any lock that is acquired within an RCU callback must be acquired
117+ elsewhere using an _bh variant of the spinlock primitive.
118+ For example, if "mylock" is acquired by an RCU callback, then
119+ a process-context acquisition of this lock must use something
120+ like spin_lock_bh() to acquire the lock. Please note that
121+ it is also OK to use _irq variants of spinlocks, for example,
122+ spin_lock_irqsave().
123+
124+ If the process-context code were to simply use spin_lock(),
125+ then, since RCU callbacks can be invoked from softirq context,
126+ the callback might be called from a softirq that interrupted
127+ the process-context critical section. This would result in
128+ self-deadlock.
129+
130+ This restriction might seem gratuitous, since very few RCU
131+ callbacks acquire locks directly. However, a great many RCU
132+ callbacks do acquire locks *indirectly*, for example, via
133+ the kfree() primitive.
134+
135+Answer to Quick Quiz #3:
136+ Why can't synchronize_rcu() return immediately on UP systems
137+ running preemptable RCU?
138+
139+ Because some other task might have been preempted in the middle
140+ of an RCU read-side critical section. If synchronize_rcu()
141+ simply immediately returned, it would prematurely signal the
142+ end of the grace period, which would come as a nasty shock to
143+ that other thread when it started running again.
Documentation/RCU/UP.txt+0−133
@@ -1,133 +0,0 @@
1−RCU on Uniprocessor Systems
2−
3−
4−A common misconception is that, on UP systems, the call_rcu() primitive
5−may immediately invoke its function. The basis of this misconception
6−is that since there is only one CPU, it should not be necessary to
7−wait for anything else to get done, since there are no other CPUs for
8−anything else to be happening on. Although this approach will -sort- -of-
9−work a surprising amount of the time, it is a very bad idea in general.
10−This document presents three examples that demonstrate exactly how bad
11−an idea this is.
12−
13−
14−Example 1: softirq Suicide
15−
16−Suppose that an RCU-based algorithm scans a linked list containing
17−elements A, B, and C in process context, and can delete elements from
18−this same list in softirq context. Suppose that the process-context scan
19−is referencing element B when it is interrupted by softirq processing,
20−which deletes element B, and then invokes call_rcu() to free element B
21−after a grace period.
22−
23−Now, if call_rcu() were to directly invoke its arguments, then upon return
24−from softirq, the list scan would find itself referencing a newly freed
25−element B. This situation can greatly decrease the life expectancy of
26−your kernel.
27−
28−This same problem can occur if call_rcu() is invoked from a hardware
29−interrupt handler.
30−
31−
32−Example 2: Function-Call Fatality
33−
34−Of course, one could avert the suicide described in the preceding example
35−by having call_rcu() directly invoke its arguments only if it was called
36−from process context. However, this can fail in a similar manner.
37−
38−Suppose that an RCU-based algorithm again scans a linked list containing
39−elements A, B, and C in process contexts, but that it invokes a function
40−on each element as it is scanned. Suppose further that this function
41−deletes element B from the list, then passes it to call_rcu() for deferred
42−freeing. This may be a bit unconventional, but it is perfectly legal
43−RCU usage, since call_rcu() must wait for a grace period to elapse.
44−Therefore, in this case, allowing call_rcu() to immediately invoke
45−its arguments would cause it to fail to make the fundamental guarantee
46−underlying RCU, namely that call_rcu() defers invoking its arguments until
47−all RCU read-side critical sections currently executing have completed.
48−
49−Quick Quiz #1: why is it -not- legal to invoke synchronize_rcu() in
50− this case?
51−
52−
53−Example 3: Death by Deadlock
54−
55−Suppose that call_rcu() is invoked while holding a lock, and that the
56−callback function must acquire this same lock. In this case, if
57−call_rcu() were to directly invoke the callback, the result would
58−be self-deadlock.
59−
60−In some cases, it would possible to restructure to code so that
61−the call_rcu() is delayed until after the lock is released. However,
62−there are cases where this can be quite ugly:
63−
64−1. If a number of items need to be passed to call_rcu() within
65− the same critical section, then the code would need to create
66− a list of them, then traverse the list once the lock was
67− released.
68−
69−2. In some cases, the lock will be held across some kernel API,
70− so that delaying the call_rcu() until the lock is released
71− requires that the data item be passed up via a common API.
72− It is far better to guarantee that callbacks are invoked
73− with no locks held than to have to modify such APIs to allow
74− arbitrary data items to be passed back up through them.
75−
76−If call_rcu() directly invokes the callback, painful locking restrictions
77−or API changes would be required.
78−
79−Quick Quiz #2: What locking restriction must RCU callbacks respect?
80−
81−
82−Summary
83−
84−Permitting call_rcu() to immediately invoke its arguments breaks RCU,
85−even on a UP system. So do not do it! Even on a UP system, the RCU
86−infrastructure -must- respect grace periods, and -must- invoke callbacks
87−from a known environment in which no locks are held.
88−
89−Note that it -is- safe for synchronize_rcu() to return immediately on
90−UP systems, including !PREEMPT SMP builds running on UP systems.
91−
92−Quick Quiz #3: Why can't synchronize_rcu() return immediately on
93− UP systems running preemptable RCU?
94−
95−
96−Answer to Quick Quiz #1:
97− Why is it -not- legal to invoke synchronize_rcu() in this case?
98−
99− Because the calling function is scanning an RCU-protected linked
100− list, and is therefore within an RCU read-side critical section.
101− Therefore, the called function has been invoked within an RCU
102− read-side critical section, and is not permitted to block.
103−
104−Answer to Quick Quiz #2:
105− What locking restriction must RCU callbacks respect?
106−
107− Any lock that is acquired within an RCU callback must be
108− acquired elsewhere using an _irq variant of the spinlock
109− primitive. For example, if "mylock" is acquired by an
110− RCU callback, then a process-context acquisition of this
111− lock must use something like spin_lock_irqsave() to
112− acquire the lock.
113−
114− If the process-context code were to simply use spin_lock(),
115− then, since RCU callbacks can be invoked from softirq context,
116− the callback might be called from a softirq that interrupted
117− the process-context critical section. This would result in
118− self-deadlock.
119−
120− This restriction might seem gratuitous, since very few RCU
121− callbacks acquire locks directly. However, a great many RCU
122− callbacks do acquire locks -indirectly-, for example, via
123− the kfree() primitive.
124−
125−Answer to Quick Quiz #3:
126− Why can't synchronize_rcu() return immediately on UP systems
127− running preemptable RCU?
128−
129− Because some other task might have been preempted in the middle
130− of an RCU read-side critical section. If synchronize_rcu()
131− simply immediately returned, it would prematurely signal the
132− end of the grace period, which would come as a nasty shock to
133− that other thread when it started running again.
Documentation/RCU/index.rst+19−0
@@ -0,0 +1,19 @@
1+.. _rcu_concepts:
2+
3+============
4+RCU concepts
5+============
6+
7+.. toctree::
8+ :maxdepth: 1
9+
10+ rcu
11+ listRCU
12+ UP
13+
14+.. only:: subproject and html
15+
16+ Indices
17+ =======
18+
19+ * :ref:`genindex`
Documentation/RCU/listRCU.rst+321−0
@@ -0,0 +1,321 @@
1+.. _list_rcu_doc:
2+
3+Using RCU to Protect Read-Mostly Linked Lists
4+=============================================
5+
6+One of the best applications of RCU is to protect read-mostly linked lists
7+("struct list_head" in list.h). One big advantage of this approach
8+is that all of the required memory barriers are included for you in
9+the list macros. This document describes several applications of RCU,
10+with the best fits first.
11+
12+Example 1: Read-Side Action Taken Outside of Lock, No In-Place Updates
13+----------------------------------------------------------------------
14+
15+The best applications are cases where, if reader-writer locking were
16+used, the read-side lock would be dropped before taking any action
17+based on the results of the search. The most celebrated example is
18+the routing table. Because the routing table is tracking the state of
19+equipment outside of the computer, it will at times contain stale data.
20+Therefore, once the route has been computed, there is no need to hold
21+the routing table static during transmission of the packet. After all,
22+you can hold the routing table static all you want, but that won't keep
23+the external Internet from changing, and it is the state of the external
24+Internet that really matters. In addition, routing entries are typically
25+added or deleted, rather than being modified in place.
26+
27+A straightforward example of this use of RCU may be found in the
28+system-call auditing support. For example, a reader-writer locked
29+implementation of audit_filter_task() might be as follows::
30+
31+ static enum audit_state audit_filter_task(struct task_struct *tsk)
32+ {
33+ struct audit_entry *e;
34+ enum audit_state state;
35+
36+ read_lock(&auditsc_lock);
37+ /* Note: audit_netlink_sem held by caller. */
38+ list_for_each_entry(e, &audit_tsklist, list) {
39+ if (audit_filter_rules(tsk, &e->rule, NULL, &state)) {
40+ read_unlock(&auditsc_lock);
41+ return state;
42+ }
43+ }
44+ read_unlock(&auditsc_lock);
45+ return AUDIT_BUILD_CONTEXT;
46+ }
47+
48+Here the list is searched under the lock, but the lock is dropped before
49+the corresponding value is returned. By the time that this value is acted
50+on, the list may well have been modified. This makes sense, since if
51+you are turning auditing off, it is OK to audit a few extra system calls.
52+
53+This means that RCU can be easily applied to the read side, as follows::
54+
55+ static enum audit_state audit_filter_task(struct task_struct *tsk)
56+ {
57+ struct audit_entry *e;
58+ enum audit_state state;
59+
60+ rcu_read_lock();
61+ /* Note: audit_netlink_sem held by caller. */
62+ list_for_each_entry_rcu(e, &audit_tsklist, list) {
63+ if (audit_filter_rules(tsk, &e->rule, NULL, &state)) {
64+ rcu_read_unlock();
65+ return state;
66+ }
67+ }
68+ rcu_read_unlock();
69+ return AUDIT_BUILD_CONTEXT;
70+ }
71+
72+The read_lock() and read_unlock() calls have become rcu_read_lock()
73+and rcu_read_unlock(), respectively, and the list_for_each_entry() has
74+become list_for_each_entry_rcu(). The _rcu() list-traversal primitives
75+insert the read-side memory barriers that are required on DEC Alpha CPUs.
76+
77+The changes to the update side are also straightforward. A reader-writer
78+lock might be used as follows for deletion and insertion::
79+
80+ static inline int audit_del_rule(struct audit_rule *rule,
81+ struct list_head *list)
82+ {
83+ struct audit_entry *e;
84+
85+ write_lock(&auditsc_lock);
86+ list_for_each_entry(e, list, list) {
87+ if (!audit_compare_rule(rule, &e->rule)) {
88+ list_del(&e->list);
89+ write_unlock(&auditsc_lock);
90+ return 0;
91+ }
92+ }
93+ write_unlock(&auditsc_lock);
94+ return -EFAULT; /* No matching rule */
95+ }
96+
97+ static inline int audit_add_rule(struct audit_entry *entry,
98+ struct list_head *list)
99+ {
100+ write_lock(&auditsc_lock);
101+ if (entry->rule.flags & AUDIT_PREPEND) {
102+ entry->rule.flags &= ~AUDIT_PREPEND;
103+ list_add(&entry->list, list);
104+ } else {
105+ list_add_tail(&entry->list, list);
106+ }
107+ write_unlock(&auditsc_lock);
108+ return 0;
109+ }
110+
111+Following are the RCU equivalents for these two functions::
112+
113+ static inline int audit_del_rule(struct audit_rule *rule,
114+ struct list_head *list)
115+ {
116+ struct audit_entry *e;
117+
118+ /* Do not use the _rcu iterator here, since this is the only
119+ * deletion routine. */
120+ list_for_each_entry(e, list, list) {
121+ if (!audit_compare_rule(rule, &e->rule)) {
122+ list_del_rcu(&e->list);
123+ call_rcu(&e->rcu, audit_free_rule);
124+ return 0;
125+ }
126+ }
127+ return -EFAULT; /* No matching rule */
128+ }
129+
130+ static inline int audit_add_rule(struct audit_entry *entry,
131+ struct list_head *list)
132+ {
133+ if (entry->rule.flags & AUDIT_PREPEND) {
134+ entry->rule.flags &= ~AUDIT_PREPEND;
135+ list_add_rcu(&entry->list, list);
136+ } else {
137+ list_add_tail_rcu(&entry->list, list);
138+ }
139+ return 0;
140+ }
141+
142+Normally, the write_lock() and write_unlock() would be replaced by
143+a spin_lock() and a spin_unlock(), but in this case, all callers hold
144+audit_netlink_sem, so no additional locking is required. The auditsc_lock
145+can therefore be eliminated, since use of RCU eliminates the need for
146+writers to exclude readers. Normally, the write_lock() calls would
147+be converted into spin_lock() calls.
148+
149+The list_del(), list_add(), and list_add_tail() primitives have been
150+replaced by list_del_rcu(), list_add_rcu(), and list_add_tail_rcu().
151+The _rcu() list-manipulation primitives add memory barriers that are
152+needed on weakly ordered CPUs (most of them!). The list_del_rcu()
153+primitive omits the pointer poisoning debug-assist code that would
154+otherwise cause concurrent readers to fail spectacularly.
155+
156+So, when readers can tolerate stale data and when entries are either added
157+or deleted, without in-place modification, it is very easy to use RCU!
158+
159+Example 2: Handling In-Place Updates
160+------------------------------------
161+
162+The system-call auditing code does not update auditing rules in place.
163+However, if it did, reader-writer-locked code to do so might look as
164+follows (presumably, the field_count is only permitted to decrease,
165+otherwise, the added fields would need to be filled in)::
166+
167+ static inline int audit_upd_rule(struct audit_rule *rule,
168+ struct list_head *list,
169+ __u32 newaction,
170+ __u32 newfield_count)
171+ {
172+ struct audit_entry *e;
173+ struct audit_newentry *ne;
174+
175+ write_lock(&auditsc_lock);
176+ /* Note: audit_netlink_sem held by caller. */
177+ list_for_each_entry(e, list, list) {
178+ if (!audit_compare_rule(rule, &e->rule)) {
179+ e->rule.action = newaction;
180+ e->rule.file_count = newfield_count;
181+ write_unlock(&auditsc_lock);
182+ return 0;
183+ }
184+ }
185+ write_unlock(&auditsc_lock);
186+ return -EFAULT; /* No matching rule */
187+ }
188+
189+The RCU version creates a copy, updates the copy, then replaces the old
190+entry with the newly updated entry. This sequence of actions, allowing
191+concurrent reads while doing a copy to perform an update, is what gives
192+RCU ("read-copy update") its name. The RCU code is as follows::
193+
194+ static inline int audit_upd_rule(struct audit_rule *rule,
195+ struct list_head *list,
196+ __u32 newaction,
197+ __u32 newfield_count)
198+ {
199+ struct audit_entry *e;
200+ struct audit_newentry *ne;
201+
202+ list_for_each_entry(e, list, list) {
203+ if (!audit_compare_rule(rule, &e->rule)) {
204+ ne = kmalloc(sizeof(*entry), GFP_ATOMIC);
205+ if (ne == NULL)
206+ return -ENOMEM;
207+ audit_copy_rule(&ne->rule, &e->rule);
208+ ne->rule.action = newaction;
209+ ne->rule.file_count = newfield_count;
210+ list_replace_rcu(&e->list, &ne->list);
211+ call_rcu(&e->rcu, audit_free_rule);
212+ return 0;
213+ }
214+ }
215+ return -EFAULT; /* No matching rule */
216+ }
217+
218+Again, this assumes that the caller holds audit_netlink_sem. Normally,
219+the reader-writer lock would become a spinlock in this sort of code.
220+
221+Example 3: Eliminating Stale Data
222+---------------------------------
223+
224+The auditing examples above tolerate stale data, as do most algorithms
225+that are tracking external state. Because there is a delay from the
226+time the external state changes before Linux becomes aware of the change,
227+additional RCU-induced staleness is normally not a problem.
228+
229+However, there are many examples where stale data cannot be tolerated.
230+One example in the Linux kernel is the System V IPC (see the ipc_lock()
231+function in ipc/util.c). This code checks a "deleted" flag under a
232+per-entry spinlock, and, if the "deleted" flag is set, pretends that the
233+entry does not exist. For this to be helpful, the search function must
234+return holding the per-entry spinlock, as ipc_lock() does in fact do.
235+
236+Quick Quiz:
237+ Why does the search function need to return holding the per-entry lock for
238+ this deleted-flag technique to be helpful?
239+
240+:ref:`Answer to Quick Quiz <answer_quick_quiz_list>`
241+
242+If the system-call audit module were to ever need to reject stale data,
243+one way to accomplish this would be to add a "deleted" flag and a "lock"
244+spinlock to the audit_entry structure, and modify audit_filter_task()
245+as follows::
246+
247+ static enum audit_state audit_filter_task(struct task_struct *tsk)
248+ {
249+ struct audit_entry *e;
250+ enum audit_state state;
251+
252+ rcu_read_lock();
253+ list_for_each_entry_rcu(e, &audit_tsklist, list) {
254+ if (audit_filter_rules(tsk, &e->rule, NULL, &state)) {
255+ spin_lock(&e->lock);
256+ if (e->deleted) {
257+ spin_unlock(&e->lock);
258+ rcu_read_unlock();
259+ return AUDIT_BUILD_CONTEXT;
260+ }
261+ rcu_read_unlock();
262+ return state;
263+ }
264+ }
265+ rcu_read_unlock();
266+ return AUDIT_BUILD_CONTEXT;
267+ }
268+
269+Note that this example assumes that entries are only added and deleted.
270+Additional mechanism is required to deal correctly with the
271+update-in-place performed by audit_upd_rule(). For one thing,
272+audit_upd_rule() would need additional memory barriers to ensure
273+that the list_add_rcu() was really executed before the list_del_rcu().
274+
275+The audit_del_rule() function would need to set the "deleted"
276+flag under the spinlock as follows::
277+
278+ static inline int audit_del_rule(struct audit_rule *rule,
279+ struct list_head *list)
280+ {
281+ struct audit_entry *e;
282+
283+ /* Do not need to use the _rcu iterator here, since this
284+ * is the only deletion routine. */
285+ list_for_each_entry(e, list, list) {
286+ if (!audit_compare_rule(rule, &e->rule)) {
287+ spin_lock(&e->lock);
288+ list_del_rcu(&e->list);
289+ e->deleted = 1;
290+ spin_unlock(&e->lock);
291+ call_rcu(&e->rcu, audit_free_rule);
292+ return 0;
293+ }
294+ }
295+ return -EFAULT; /* No matching rule */
296+ }
297+
298+Summary
299+-------
300+
301+Read-mostly list-based data structures that can tolerate stale data are
302+the most amenable to use of RCU. The simplest case is where entries are
303+either added or deleted from the data structure (or atomically modified
304+in place), but non-atomic in-place modifications can be handled by making
305+a copy, updating the copy, then replacing the original with the copy.
306+If stale data cannot be tolerated, then a "deleted" flag may be used
307+in conjunction with a per-entry spinlock in order to allow the search
308+function to reject newly deleted data.
309+
310+.. _answer_quick_quiz_list:
311+
312+Answer to Quick Quiz:
313+ Why does the search function need to return holding the per-entry
314+ lock for this deleted-flag technique to be helpful?
315+
316+ If the search function drops the per-entry lock before returning,
317+ then the caller will be processing stale data in any case. If it
318+ is really OK to be processing stale data, then you don't need a
319+ "deleted" flag. If processing stale data really is a problem,
320+ then you need to hold the per-entry lock across all of the code
321+ that uses the value that was returned.
Documentation/RCU/listRCU.txt+0−315
@@ -1,315 +0,0 @@
1−Using RCU to Protect Read-Mostly Linked Lists
2−
3−
4−One of the best applications of RCU is to protect read-mostly linked lists
5−("struct list_head" in list.h). One big advantage of this approach
6−is that all of the required memory barriers are included for you in
7−the list macros. This document describes several applications of RCU,
8−with the best fits first.
9−
10−
11−Example 1: Read-Side Action Taken Outside of Lock, No In-Place Updates
12−
13−The best applications are cases where, if reader-writer locking were
14−used, the read-side lock would be dropped before taking any action
15−based on the results of the search. The most celebrated example is
16−the routing table. Because the routing table is tracking the state of
17−equipment outside of the computer, it will at times contain stale data.
18−Therefore, once the route has been computed, there is no need to hold
19−the routing table static during transmission of the packet. After all,
20−you can hold the routing table static all you want, but that won't keep
21−the external Internet from changing, and it is the state of the external
22−Internet that really matters. In addition, routing entries are typically
23−added or deleted, rather than being modified in place.
24−
25−A straightforward example of this use of RCU may be found in the
26−system-call auditing support. For example, a reader-writer locked
27−implementation of audit_filter_task() might be as follows:
28−
29− static enum audit_state audit_filter_task(struct task_struct *tsk)
30− {
31− struct audit_entry *e;
32− enum audit_state state;
33−
34− read_lock(&auditsc_lock);
35− /* Note: audit_netlink_sem held by caller. */
36− list_for_each_entry(e, &audit_tsklist, list) {
37− if (audit_filter_rules(tsk, &e->rule, NULL, &state)) {
38− read_unlock(&auditsc_lock);
39− return state;
40− }
41− }
42− read_unlock(&auditsc_lock);
43− return AUDIT_BUILD_CONTEXT;
44− }
45−
46−Here the list is searched under the lock, but the lock is dropped before
47−the corresponding value is returned. By the time that this value is acted
48−on, the list may well have been modified. This makes sense, since if
49−you are turning auditing off, it is OK to audit a few extra system calls.
50−
51−This means that RCU can be easily applied to the read side, as follows:
52−
53− static enum audit_state audit_filter_task(struct task_struct *tsk)
54− {
55− struct audit_entry *e;
56− enum audit_state state;
57−
58− rcu_read_lock();
59− /* Note: audit_netlink_sem held by caller. */
60− list_for_each_entry_rcu(e, &audit_tsklist, list) {
61− if (audit_filter_rules(tsk, &e->rule, NULL, &state)) {
62− rcu_read_unlock();
63− return state;
64− }
65− }
66− rcu_read_unlock();
67− return AUDIT_BUILD_CONTEXT;
68− }
69−
70−The read_lock() and read_unlock() calls have become rcu_read_lock()
71−and rcu_read_unlock(), respectively, and the list_for_each_entry() has
72−become list_for_each_entry_rcu(). The _rcu() list-traversal primitives
73−insert the read-side memory barriers that are required on DEC Alpha CPUs.
74−
75−The changes to the update side are also straightforward. A reader-writer
76−lock might be used as follows for deletion and insertion:
77−
78− static inline int audit_del_rule(struct audit_rule *rule,
79− struct list_head *list)
80− {
81− struct audit_entry *e;
82−
83− write_lock(&auditsc_lock);
84− list_for_each_entry(e, list, list) {
85− if (!audit_compare_rule(rule, &e->rule)) {
86− list_del(&e->list);
87− write_unlock(&auditsc_lock);
88− return 0;
89− }
90− }
91− write_unlock(&auditsc_lock);
92− return -EFAULT; /* No matching rule */
93− }
94−
95− static inline int audit_add_rule(struct audit_entry *entry,
96− struct list_head *list)
97− {
98− write_lock(&auditsc_lock);
99− if (entry->rule.flags & AUDIT_PREPEND) {
100− entry->rule.flags &= ~AUDIT_PREPEND;
101− list_add(&entry->list, list);
102− } else {
103− list_add_tail(&entry->list, list);
104− }
105− write_unlock(&auditsc_lock);
106− return 0;
107− }
108−
109−Following are the RCU equivalents for these two functions:
110−
111− static inline int audit_del_rule(struct audit_rule *rule,
112− struct list_head *list)
113− {
114− struct audit_entry *e;
115−
116− /* Do not use the _rcu iterator here, since this is the only
117− * deletion routine. */
118− list_for_each_entry(e, list, list) {
119− if (!audit_compare_rule(rule, &e->rule)) {
120− list_del_rcu(&e->list);
121− call_rcu(&e->rcu, audit_free_rule);
122− return 0;
123− }
124− }
125− return -EFAULT; /* No matching rule */
126− }
127−
128− static inline int audit_add_rule(struct audit_entry *entry,
129− struct list_head *list)
130− {
131− if (entry->rule.flags & AUDIT_PREPEND) {
132− entry->rule.flags &= ~AUDIT_PREPEND;
133− list_add_rcu(&entry->list, list);
134− } else {
135− list_add_tail_rcu(&entry->list, list);
136− }
137− return 0;
138− }
139−
140−Normally, the write_lock() and write_unlock() would be replaced by
141−a spin_lock() and a spin_unlock(), but in this case, all callers hold
142−audit_netlink_sem, so no additional locking is required. The auditsc_lock
143−can therefore be eliminated, since use of RCU eliminates the need for
144−writers to exclude readers. Normally, the write_lock() calls would
145−be converted into spin_lock() calls.
146−
147−The list_del(), list_add(), and list_add_tail() primitives have been
148−replaced by list_del_rcu(), list_add_rcu(), and list_add_tail_rcu().
149−The _rcu() list-manipulation primitives add memory barriers that are
150−needed on weakly ordered CPUs (most of them!). The list_del_rcu()
151−primitive omits the pointer poisoning debug-assist code that would
152−otherwise cause concurrent readers to fail spectacularly.
153−
154−So, when readers can tolerate stale data and when entries are either added
155−or deleted, without in-place modification, it is very easy to use RCU!
156−
157−
158−Example 2: Handling In-Place Updates
159−
160−The system-call auditing code does not update auditing rules in place.
161−However, if it did, reader-writer-locked code to do so might look as
162−follows (presumably, the field_count is only permitted to decrease,
163−otherwise, the added fields would need to be filled in):
164−
165− static inline int audit_upd_rule(struct audit_rule *rule,
166− struct list_head *list,
167− __u32 newaction,
168− __u32 newfield_count)
169− {
170− struct audit_entry *e;
171− struct audit_newentry *ne;
172−
173− write_lock(&auditsc_lock);
174− /* Note: audit_netlink_sem held by caller. */
175− list_for_each_entry(e, list, list) {
176− if (!audit_compare_rule(rule, &e->rule)) {
177− e->rule.action = newaction;
178− e->rule.file_count = newfield_count;
179− write_unlock(&auditsc_lock);
180− return 0;
181− }
182− }
183− write_unlock(&auditsc_lock);
184− return -EFAULT; /* No matching rule */
185− }
186−
187−The RCU version creates a copy, updates the copy, then replaces the old
188−entry with the newly updated entry. This sequence of actions, allowing
189−concurrent reads while doing a copy to perform an update, is what gives
190−RCU ("read-copy update") its name. The RCU code is as follows:
191−
192− static inline int audit_upd_rule(struct audit_rule *rule,
193− struct list_head *list,
194− __u32 newaction,
195− __u32 newfield_count)
196− {
197− struct audit_entry *e;
198− struct audit_newentry *ne;
199−
200− list_for_each_entry(e, list, list) {
201− if (!audit_compare_rule(rule, &e->rule)) {
202− ne = kmalloc(sizeof(*entry), GFP_ATOMIC);
203− if (ne == NULL)
204− return -ENOMEM;
205− audit_copy_rule(&ne->rule, &e->rule);
206− ne->rule.action = newaction;
207− ne->rule.file_count = newfield_count;
208− list_replace_rcu(&e->list, &ne->list);
209− call_rcu(&e->rcu, audit_free_rule);
210− return 0;
211− }
212− }
213− return -EFAULT; /* No matching rule */
214− }
215−
216−Again, this assumes that the caller holds audit_netlink_sem. Normally,
217−the reader-writer lock would become a spinlock in this sort of code.
218−
219−
220−Example 3: Eliminating Stale Data
221−
222−The auditing examples above tolerate stale data, as do most algorithms
223−that are tracking external state. Because there is a delay from the
224−time the external state changes before Linux becomes aware of the change,
225−additional RCU-induced staleness is normally not a problem.
226−
227−However, there are many examples where stale data cannot be tolerated.
228−One example in the Linux kernel is the System V IPC (see the ipc_lock()
229−function in ipc/util.c). This code checks a "deleted" flag under a
230−per-entry spinlock, and, if the "deleted" flag is set, pretends that the
231−entry does not exist. For this to be helpful, the search function must
232−return holding the per-entry spinlock, as ipc_lock() does in fact do.
233−
234−Quick Quiz: Why does the search function need to return holding the
235− per-entry lock for this deleted-flag technique to be helpful?
236−
237−If the system-call audit module were to ever need to reject stale data,
238−one way to accomplish this would be to add a "deleted" flag and a "lock"
239−spinlock to the audit_entry structure, and modify audit_filter_task()
240−as follows:
241−
242− static enum audit_state audit_filter_task(struct task_struct *tsk)
243− {
244− struct audit_entry *e;
245− enum audit_state state;
246−
247− rcu_read_lock();
248− list_for_each_entry_rcu(e, &audit_tsklist, list) {
249− if (audit_filter_rules(tsk, &e->rule, NULL, &state)) {
250− spin_lock(&e->lock);
251− if (e->deleted) {
252− spin_unlock(&e->lock);
253− rcu_read_unlock();
254− return AUDIT_BUILD_CONTEXT;
255− }
256− rcu_read_unlock();
257− return state;
258− }
259− }
260− rcu_read_unlock();
261− return AUDIT_BUILD_CONTEXT;
262− }
263−
264−Note that this example assumes that entries are only added and deleted.
265−Additional mechanism is required to deal correctly with the
266−update-in-place performed by audit_upd_rule(). For one thing,
267−audit_upd_rule() would need additional memory barriers to ensure
268−that the list_add_rcu() was really executed before the list_del_rcu().
269−
270−The audit_del_rule() function would need to set the "deleted"
271−flag under the spinlock as follows:
272−
273− static inline int audit_del_rule(struct audit_rule *rule,
274− struct list_head *list)
275− {
276− struct audit_entry *e;
277−
278− /* Do not need to use the _rcu iterator here, since this
279− * is the only deletion routine. */
280− list_for_each_entry(e, list, list) {
281− if (!audit_compare_rule(rule, &e->rule)) {
282− spin_lock(&e->lock);
283− list_del_rcu(&e->list);
284− e->deleted = 1;
285− spin_unlock(&e->lock);
286− call_rcu(&e->rcu, audit_free_rule);
287− return 0;
288− }
289− }
290− return -EFAULT; /* No matching rule */
291− }
292−
293−
294−Summary
295−
296−Read-mostly list-based data structures that can tolerate stale data are
297−the most amenable to use of RCU. The simplest case is where entries are
298−either added or deleted from the data structure (or atomically modified
299−in place), but non-atomic in-place modifications can be handled by making
300−a copy, updating the copy, then replacing the original with the copy.
301−If stale data cannot be tolerated, then a "deleted" flag may be used
302−in conjunction with a per-entry spinlock in order to allow the search
303−function to reject newly deleted data.
304−
305−
306−Answer to Quick Quiz
307− Why does the search function need to return holding the per-entry
308− lock for this deleted-flag technique to be helpful?
309−
310− If the search function drops the per-entry lock before returning,
311− then the caller will be processing stale data in any case. If it
312− is really OK to be processing stale data, then you don't need a
313− "deleted" flag. If processing stale data really is a problem,
314− then you need to hold the per-entry lock across all of the code
315− that uses the value that was returned.
Documentation/RCU/rcu.rst+92−0
@@ -0,0 +1,92 @@
1+.. _rcu_doc:
2+
3+RCU Concepts
4+============
5+
6+The basic idea behind RCU (read-copy update) is to split destructive
7+operations into two parts, one that prevents anyone from seeing the data
8+item being destroyed, and one that actually carries out the destruction.
9+A "grace period" must elapse between the two parts, and this grace period
10+must be long enough that any readers accessing the item being deleted have
11+since dropped their references. For example, an RCU-protected deletion
12+from a linked list would first remove the item from the list, wait for
13+a grace period to elapse, then free the element. See the
14+Documentation/RCU/listRCU.rst file for more information on using RCU with
15+linked lists.
16+
17+Frequently Asked Questions
18+--------------------------
19+
20+- Why would anyone want to use RCU?
21+
22+ The advantage of RCU's two-part approach is that RCU readers need
23+ not acquire any locks, perform any atomic instructions, write to
24+ shared memory, or (on CPUs other than Alpha) execute any memory
25+ barriers. The fact that these operations are quite expensive
26+ on modern CPUs is what gives RCU its performance advantages
27+ in read-mostly situations. The fact that RCU readers need not
28+ acquire locks can also greatly simplify deadlock-avoidance code.
29+
30+- How can the updater tell when a grace period has completed
31+ if the RCU readers give no indication when they are done?
32+
33+ Just as with spinlocks, RCU readers are not permitted to
34+ block, switch to user-mode execution, or enter the idle loop.
35+ Therefore, as soon as a CPU is seen passing through any of these
36+ three states, we know that that CPU has exited any previous RCU
37+ read-side critical sections. So, if we remove an item from a
38+ linked list, and then wait until all CPUs have switched context,
39+ executed in user mode, or executed in the idle loop, we can
40+ safely free up that item.
41+
42+ Preemptible variants of RCU (CONFIG_PREEMPT_RCU) get the
43+ same effect, but require that the readers manipulate CPU-local
44+ counters. These counters allow limited types of blocking within
45+ RCU read-side critical sections. SRCU also uses CPU-local
46+ counters, and permits general blocking within RCU read-side
47+ critical sections. These variants of RCU detect grace periods
48+ by sampling these counters.
49+
50+- If I am running on a uniprocessor kernel, which can only do one
51+ thing at a time, why should I wait for a grace period?
52+
53+ See the Documentation/RCU/UP.rst file for more information.
54+
55+- How can I see where RCU is currently used in the Linux kernel?
56+
57+ Search for "rcu_read_lock", "rcu_read_unlock", "call_rcu",
58+ "rcu_read_lock_bh", "rcu_read_unlock_bh", "srcu_read_lock",
59+ "srcu_read_unlock", "synchronize_rcu", "synchronize_net",
60+ "synchronize_srcu", and the other RCU primitives. Or grab one
61+ of the cscope databases from:
62+
63+ (http://www.rdrop.com/users/paulmck/RCU/linuxusage/rculocktab.html).
64+
65+- What guidelines should I follow when writing code that uses RCU?
66+
67+ See the checklist.txt file in this directory.
68+
69+- Why the name "RCU"?
70+
71+ "RCU" stands for "read-copy update". The file Documentation/RCU/listRCU.rst
72+ has more information on where this name came from, search for
73+ "read-copy update" to find it.
74+
75+- I hear that RCU is patented? What is with that?
76+
77+ Yes, it is. There are several known patents related to RCU,
78+ search for the string "Patent" in RTFP.txt to find them.
79+ Of these, one was allowed to lapse by the assignee, and the
80+ others have been contributed to the Linux kernel under GPL.
81+ There are now also LGPL implementations of user-level RCU
82+ available (http://liburcu.org/).
83+
84+- I hear that RCU needs work in order to support realtime kernels?
85+
86+ Realtime-friendly RCU can be enabled via the CONFIG_PREEMPT_RCU
87+ kernel configuration parameter.
88+
89+- Where can I find more information on RCU?
90+
91+ See the RTFP.txt file in this directory.
92+ Or point your browser at (http://www.rdrop.com/users/paulmck/RCU/).
Documentation/RCU/rcu.txt+0−89
@@ -1,89 +0,0 @@
1−RCU Concepts
2−
3−
4−The basic idea behind RCU (read-copy update) is to split destructive
5−operations into two parts, one that prevents anyone from seeing the data
6−item being destroyed, and one that actually carries out the destruction.
7−A "grace period" must elapse between the two parts, and this grace period
8−must be long enough that any readers accessing the item being deleted have
9−since dropped their references. For example, an RCU-protected deletion
10−from a linked list would first remove the item from the list, wait for
11−a grace period to elapse, then free the element. See the listRCU.txt
12−file for more information on using RCU with linked lists.
13−
14−
15−Frequently Asked Questions
16−
17−o Why would anyone want to use RCU?
18−
19− The advantage of RCU's two-part approach is that RCU readers need
20− not acquire any locks, perform any atomic instructions, write to
21− shared memory, or (on CPUs other than Alpha) execute any memory
22− barriers. The fact that these operations are quite expensive
23− on modern CPUs is what gives RCU its performance advantages
24− in read-mostly situations. The fact that RCU readers need not
25− acquire locks can also greatly simplify deadlock-avoidance code.
26−
27−o How can the updater tell when a grace period has completed
28− if the RCU readers give no indication when they are done?
29−
30− Just as with spinlocks, RCU readers are not permitted to
31− block, switch to user-mode execution, or enter the idle loop.
32− Therefore, as soon as a CPU is seen passing through any of these
33− three states, we know that that CPU has exited any previous RCU
34− read-side critical sections. So, if we remove an item from a
35− linked list, and then wait until all CPUs have switched context,
36− executed in user mode, or executed in the idle loop, we can
37− safely free up that item.
38−
39− Preemptible variants of RCU (CONFIG_PREEMPT_RCU) get the
40− same effect, but require that the readers manipulate CPU-local
41− counters. These counters allow limited types of blocking within
42− RCU read-side critical sections. SRCU also uses CPU-local
43− counters, and permits general blocking within RCU read-side
44− critical sections. These variants of RCU detect grace periods
45− by sampling these counters.
46−
47−o If I am running on a uniprocessor kernel, which can only do one
48− thing at a time, why should I wait for a grace period?
49−
50− See the UP.txt file in this directory.
51−
52−o How can I see where RCU is currently used in the Linux kernel?
53−
54− Search for "rcu_read_lock", "rcu_read_unlock", "call_rcu",
55− "rcu_read_lock_bh", "rcu_read_unlock_bh", "srcu_read_lock",
56− "srcu_read_unlock", "synchronize_rcu", "synchronize_net",
57− "synchronize_srcu", and the other RCU primitives. Or grab one
58− of the cscope databases from:
59−
60− http://www.rdrop.com/users/paulmck/RCU/linuxusage/rculocktab.html
61−
62−o What guidelines should I follow when writing code that uses RCU?
63−
64− See the checklist.txt file in this directory.
65−
66−o Why the name "RCU"?
67−
68− "RCU" stands for "read-copy update". The file listRCU.txt has
69− more information on where this name came from, search for
70− "read-copy update" to find it.
71−
72−o I hear that RCU is patented? What is with that?
73−
74− Yes, it is. There are several known patents related to RCU,
75− search for the string "Patent" in RTFP.txt to find them.
76− Of these, one was allowed to lapse by the assignee, and the
77− others have been contributed to the Linux kernel under GPL.
78− There are now also LGPL implementations of user-level RCU
79− available (http://liburcu.org/).
80−
81−o I hear that RCU needs work in order to support realtime kernels?
82−
83− Realtime-friendly RCU can be enabled via the CONFIG_PREEMPT_RCU
84− kernel configuration parameter.
85−
86−o Where can I find more information on RCU?
87−
88− See the RTFP.txt file in this directory.
89− Or point your browser at http://www.rdrop.com/users/paulmck/RCU/.
Documentation/RCU/rculist_nulls.txt+1−1
@@ -1,7 +1,7 @@
11 Using hlist_nulls to protect read-mostly linked lists and
22 objects using SLAB_TYPESAFE_BY_RCU allocations.
33
4−Please read the basics in Documentation/RCU/listRCU.txt
4+Please read the basics in Documentation/RCU/listRCU.rst
55
66 Using special makers (called 'nulls') is a convenient way
77 to solve following problem :
Documentation/RCU/rcuref.txt+20−1
@@ -12,6 +12,7 @@ please read on. · 11 unmodified lines
1212 Reference counting on elements of lists which are protected by traditional
1313 reader/writer spinlocks or semaphores are straightforward:
1414
15+CODE LISTING A:
1516 1. 2.
1617 add() search_and_reference()
1718 { {
@@ -28,7 +29,8 @@ add() search_and_reference() · 10 unmodified lines
2829 release_referenced() delete()
2930 { {
3031 ... write_lock(&list_lock);
31− atomic_dec(&el->rc, relfunc) ...
32+ if(atomic_dec_and_test(&el->rc)) ...
33+ kfree(el);
3234 ... remove_element
3335 } write_unlock(&list_lock);
3436 ...
@@ -44,6 +46,7 @@ search_and_reference() could potentially hold reference to an element which · 9 unmodified lines
4446 has already been deleted from the list/array. Use atomic_inc_not_zero()
4547 in this scenario as follows:
4648
49+CODE LISTING B:
4750 1. 2.
4851 add() search_and_reference()
4952 { {
@@ -79,6 +82,7 @@ search_and_reference() code path. In such cases, the · 29 unmodified lines
7982 atomic_dec_and_test() may be moved from delete() to el_free()
8083 as follows:
8184
85+CODE LISTING C:
8286 1. 2.
8387 add() search_and_reference()
8488 { {
@@ -114,6 +118,17 @@ element can therefore safely be freed. This in turn guarantees that if · 29 unmodified lines
114118 any reader finds the element, that reader may safely acquire a reference
115119 without checking the value of the reference counter.
116120
121+A clear advantage of the RCU-based pattern in listing C over the one
122+in listing B is that any call to search_and_reference() that locates
123+a given object will succeed in obtaining a reference to that object,
124+even given a concurrent invocation of delete() for that same object.
125+Similarly, a clear advantage of both listings B and C over listing A is
126+that a call to delete() is not delayed even if there are an arbitrarily
127+large number of calls to search_and_reference() searching for the same
128+object that delete() was invoked on. Instead, all that is delayed is
129+the eventual invocation of kfree(), which is usually not a problem on
130+modern computer systems, even the small ones.
131+
117132 In cases where delete() can sleep, synchronize_rcu() can be called from
118133 delete(), so that el_free() can be subsumed into delete as follows:
119134
@@ -130,3 +145,7 @@ delete() · 10 unmodified lines
130145 kfree(el);
131146 ...
132147 }
148+
149+As additional examples in the kernel, the pattern in listing C is used by
150+reference counting of struct pid, while the pattern in listing B is used by
151+struct posix_acl.
Documentation/RCU/stallwarn.txt+1−1
@@ -153,7 +153,7 @@ rcupdate.rcu_task_stall_timeout · 152 unmodified lines
153153 This boot/sysfs parameter controls the RCU-tasks stall warning
154154 interval. A value of zero or less suppresses RCU-tasks stall
155155 warnings. A positive value sets the stall-warning interval
156− in jiffies. An RCU-tasks stall warning starts with the line:
156+ in seconds. An RCU-tasks stall warning starts with the line:
157157
158158 INFO: rcu_tasks detected stalls on tasks:
159159
Documentation/RCU/whatisRCU.txt+4−4
@@ -212,7 +212,7 @@ synchronize_rcu() · 211 unmodified lines
212212
213213 rcu_assign_pointer()
214214
215− typeof(p) rcu_assign_pointer(p, typeof(p) v);
215+ void rcu_assign_pointer(p, typeof(p) v);
216216
217217 Yes, rcu_assign_pointer() -is- implemented as a macro, though it
218218 would be cool to be able to declare a function in this manner.
@@ -220,9 +220,9 @@ rcu_assign_pointer() · 1 unmodified line
220220
221221 The updater uses this function to assign a new value to an
222222 RCU-protected pointer, in order to safely communicate the change
223− in value from the updater to the reader. This function returns
224− the new value, and also executes any memory-barrier instructions
225− required for a given CPU architecture.
223+ in value from the updater to the reader. This macro does not
224+ evaluate to an rvalue, but it does execute any memory-barrier
225+ instructions required for a given CPU architecture.
226226
227227 Perhaps just as important, it serves to document (1) which
228228 pointers are protected by RCU and (2) the point at which a
Documentation/accounting/cgroupstats.rst+31−0
@@ -0,0 +1,31 @@
1+==================
2+Control Groupstats
3+==================
4+
5+Control Groupstats is inspired by the discussion at
6+http://lkml.org/lkml/2007/4/11/187 and implements per cgroup statistics as
7+suggested by Andrew Morton in http://lkml.org/lkml/2007/4/11/263.
8+
9+Per cgroup statistics infrastructure re-uses code from the taskstats
10+interface. A new set of cgroup operations are registered with commands
11+and attributes specific to cgroups. It should be very easy to
12+extend per cgroup statistics, by adding members to the cgroupstats
13+structure.
14+
15+The current model for cgroupstats is a pull, a push model (to post
16+statistics on interesting events), should be very easy to add. Currently
17+user space requests for statistics by passing the cgroup path.
18+Statistics about the state of all the tasks in the cgroup is returned to
19+user space.
20+
21+NOTE: We currently rely on delay accounting for extracting information
22+about tasks blocked on I/O. If CONFIG_TASK_DELAY_ACCT is disabled, this
23+information will not be available.
24+
25+To extract cgroup statistics a utility very similar to getdelays.c
26+has been developed, the sample output of the utility is shown below::
27+
28+ ~/balbir/cgroupstats # ./getdelays -C "/sys/fs/cgroup/a"
29+ sleeping 1, blocked 0, running 1, stopped 0, uninterruptible 0
30+ ~/balbir/cgroupstats # ./getdelays -C "/sys/fs/cgroup"
31+ sleeping 155, blocked 0, running 1, stopped 0, uninterruptible 2
Documentation/accounting/cgroupstats.txt+0−27
@@ -1,27 +0,0 @@
1−Control Groupstats is inspired by the discussion at
2−http://lkml.org/lkml/2007/4/11/187 and implements per cgroup statistics as
3−suggested by Andrew Morton in http://lkml.org/lkml/2007/4/11/263.
4−
5−Per cgroup statistics infrastructure re-uses code from the taskstats
6−interface. A new set of cgroup operations are registered with commands
7−and attributes specific to cgroups. It should be very easy to
8−extend per cgroup statistics, by adding members to the cgroupstats
9−structure.
10−
11−The current model for cgroupstats is a pull, a push model (to post
12−statistics on interesting events), should be very easy to add. Currently
13−user space requests for statistics by passing the cgroup path.
14−Statistics about the state of all the tasks in the cgroup is returned to
15−user space.
16−
17−NOTE: We currently rely on delay accounting for extracting information
18−about tasks blocked on I/O. If CONFIG_TASK_DELAY_ACCT is disabled, this
19−information will not be available.
20−
21−To extract cgroup statistics a utility very similar to getdelays.c
22−has been developed, the sample output of the utility is shown below
23−
24−~/balbir/cgroupstats # ./getdelays -C "/sys/fs/cgroup/a"
25−sleeping 1, blocked 0, running 1, stopped 0, uninterruptible 0
26−~/balbir/cgroupstats # ./getdelays -C "/sys/fs/cgroup"
27−sleeping 155, blocked 0, running 1, stopped 0, uninterruptible 2
Documentation/accounting/delay-accounting.rst+126−0
@@ -0,0 +1,126 @@
1+================
2+Delay accounting
3+================
4+
5+Tasks encounter delays in execution when they wait
6+for some kernel resource to become available e.g. a
7+runnable task may wait for a free CPU to run on.
8+
9+The per-task delay accounting functionality measures
10+the delays experienced by a task while
11+
12+a) waiting for a CPU (while being runnable)
13+b) completion of synchronous block I/O initiated by the task
14+c) swapping in pages
15+d) memory reclaim
16+
17+and makes these statistics available to userspace through
18+the taskstats interface.
19+
20+Such delays provide feedback for setting a task's cpu priority,
21+io priority and rss limit values appropriately. Long delays for
22+important tasks could be a trigger for raising its corresponding priority.
23+
24+The functionality, through its use of the taskstats interface, also provides
25+delay statistics aggregated for all tasks (or threads) belonging to a
26+thread group (corresponding to a traditional Unix process). This is a commonly
27+needed aggregation that is more efficiently done by the kernel.
28+
29+Userspace utilities, particularly resource management applications, can also
30+aggregate delay statistics into arbitrary groups. To enable this, delay
31+statistics of a task are available both during its lifetime as well as on its
32+exit, ensuring continuous and complete monitoring can be done.
33+
34+
35+Interface
36+---------
37+
38+Delay accounting uses the taskstats interface which is described
39+in detail in a separate document in this directory. Taskstats returns a
40+generic data structure to userspace corresponding to per-pid and per-tgid
41+statistics. The delay accounting functionality populates specific fields of
42+this structure. See
43+
44+ include/linux/taskstats.h
45+
46+for a description of the fields pertaining to delay accounting.
47+It will generally be in the form of counters returning the cumulative
48+delay seen for cpu, sync block I/O, swapin, memory reclaim etc.
49+
50+Taking the difference of two successive readings of a given
51+counter (say cpu_delay_total) for a task will give the delay
52+experienced by the task waiting for the corresponding resource
53+in that interval.
54+
55+When a task exits, records containing the per-task statistics
56+are sent to userspace without requiring a command. If it is the last exiting
57+task of a thread group, the per-tgid statistics are also sent. More details
58+are given in the taskstats interface description.
59+
60+The getdelays.c userspace utility in tools/accounting directory allows simple
61+commands to be run and the corresponding delay statistics to be displayed. It
62+also serves as an example of using the taskstats interface.
63+
64+Usage
65+-----
66+
67+Compile the kernel with::
68+
69+ CONFIG_TASK_DELAY_ACCT=y
70+ CONFIG_TASKSTATS=y
71+
72+Delay accounting is enabled by default at boot up.
73+To disable, add::
74+
75+ nodelayacct
76+
77+to the kernel boot options. The rest of the instructions
78+below assume this has not been done.
79+
80+After the system has booted up, use a utility
81+similar to getdelays.c to access the delays
82+seen by a given task or a task group (tgid).
83+The utility also allows a given command to be
84+executed and the corresponding delays to be
85+seen.
86+
87+General format of the getdelays command::
88+
89+ getdelays [-t tgid] [-p pid] [-c cmd...]
90+
91+
92+Get delays, since system boot, for pid 10::
93+
94+ # ./getdelays -p 10
95+ (output similar to next case)
96+
97+Get sum of delays, since system boot, for all pids with tgid 5::
98+
99+ # ./getdelays -t 5
100+
101+
102+ CPU count real total virtual total delay total
103+ 7876 92005750 100000000 24001500
104+ IO count delay total
105+ 0 0
106+ SWAP count delay total
107+ 0 0
108+ RECLAIM count delay total
109+ 0 0
110+
111+Get delays seen in executing a given simple command::
112+
113+ # ./getdelays -c ls /
114+
115+ bin data1 data3 data5 dev home media opt root srv sys usr
116+ boot data2 data4 data6 etc lib mnt proc sbin subdomain tmp var
117+
118+
119+ CPU count real total virtual total delay total
120+ 6 4000250 4000000 0
121+ IO count delay total
122+ 0 0
123+ SWAP count delay total
124+ 0 0
125+ RECLAIM count delay total
126+ 0 0
Documentation/accounting/delay-accounting.txt+0−117
@@ -1,117 +0,0 @@
1−Delay accounting
2−----------------
3−
4−Tasks encounter delays in execution when they wait
5−for some kernel resource to become available e.g. a
6−runnable task may wait for a free CPU to run on.
7−
8−The per-task delay accounting functionality measures
9−the delays experienced by a task while
10−
11−a) waiting for a CPU (while being runnable)
12−b) completion of synchronous block I/O initiated by the task
13−c) swapping in pages
14−d) memory reclaim
15−
16−and makes these statistics available to userspace through
17−the taskstats interface.
18−
19−Such delays provide feedback for setting a task's cpu priority,
20−io priority and rss limit values appropriately. Long delays for
21−important tasks could be a trigger for raising its corresponding priority.
22−
23−The functionality, through its use of the taskstats interface, also provides
24−delay statistics aggregated for all tasks (or threads) belonging to a
25−thread group (corresponding to a traditional Unix process). This is a commonly
26−needed aggregation that is more efficiently done by the kernel.
27−
28−Userspace utilities, particularly resource management applications, can also
29−aggregate delay statistics into arbitrary groups. To enable this, delay
30−statistics of a task are available both during its lifetime as well as on its
31−exit, ensuring continuous and complete monitoring can be done.
32−
33−
34−Interface
35−---------
36−
37−Delay accounting uses the taskstats interface which is described
38−in detail in a separate document in this directory. Taskstats returns a
39−generic data structure to userspace corresponding to per-pid and per-tgid
40−statistics. The delay accounting functionality populates specific fields of
41−this structure. See
42− include/linux/taskstats.h
43−for a description of the fields pertaining to delay accounting.
44−It will generally be in the form of counters returning the cumulative
45−delay seen for cpu, sync block I/O, swapin, memory reclaim etc.
46−
47−Taking the difference of two successive readings of a given
48−counter (say cpu_delay_total) for a task will give the delay
49−experienced by the task waiting for the corresponding resource
50−in that interval.
51−
52−When a task exits, records containing the per-task statistics
53−are sent to userspace without requiring a command. If it is the last exiting
54−task of a thread group, the per-tgid statistics are also sent. More details
55−are given in the taskstats interface description.
56−
57−The getdelays.c userspace utility in tools/accounting directory allows simple
58−commands to be run and the corresponding delay statistics to be displayed. It
59−also serves as an example of using the taskstats interface.
60−
61−Usage
62−-----
63−
64−Compile the kernel with
65− CONFIG_TASK_DELAY_ACCT=y
66− CONFIG_TASKSTATS=y
67−
68−Delay accounting is enabled by default at boot up.
69−To disable, add
70− nodelayacct
71−to the kernel boot options. The rest of the instructions
72−below assume this has not been done.
73−
74−After the system has booted up, use a utility
75−similar to getdelays.c to access the delays
76−seen by a given task or a task group (tgid).
77−The utility also allows a given command to be
78−executed and the corresponding delays to be
79−seen.
80−
81−General format of the getdelays command
82−
83−getdelays [-t tgid] [-p pid] [-c cmd...]
84−
85−
86−Get delays, since system boot, for pid 10
87−# ./getdelays -p 10
88−(output similar to next case)
89−
90−Get sum of delays, since system boot, for all pids with tgid 5
91−# ./getdelays -t 5
92−
93−
94−CPU count real total virtual total delay total
95− 7876 92005750 100000000 24001500
96−IO count delay total
97− 0 0
98−SWAP count delay total
99− 0 0
100−RECLAIM count delay total
101− 0 0
102−
103−Get delays seen in executing a given simple command
104−# ./getdelays -c ls /
105−
106−bin data1 data3 data5 dev home media opt root srv sys usr
107−boot data2 data4 data6 etc lib mnt proc sbin subdomain tmp var
108−
109−
110−CPU count real total virtual total delay total
111− 6 4000250 4000000 0
112−IO count delay total
113− 0 0
114−SWAP count delay total
115− 0 0
116−RECLAIM count delay total
117− 0 0
Documentation/accounting/index.rst+14−0
@@ -0,0 +1,14 @@
1+.. SPDX-License-Identifier: GPL-2.0
2+
3+==========
4+Accounting
5+==========
6+
7+.. toctree::
8+ :maxdepth: 1
9+
10+ cgroupstats
11+ delay-accounting
12+ psi
13+ taskstats
14+ taskstats-struct
Documentation/accounting/psi.rst+182−0
@@ -0,0 +1,182 @@
1+================================
2+PSI - Pressure Stall Information
3+================================
4+
5+:Date: April, 2018
6+:Author: Johannes Weiner <hannes@cmpxchg.org>
7+
8+When CPU, memory or IO devices are contended, workloads experience
9+latency spikes, throughput losses, and run the risk of OOM kills.
10+
11+Without an accurate measure of such contention, users are forced to
12+either play it safe and under-utilize their hardware resources, or
13+roll the dice and frequently suffer the disruptions resulting from
14+excessive overcommit.
15+
16+The psi feature identifies and quantifies the disruptions caused by
17+such resource crunches and the time impact it has on complex workloads
18+or even entire systems.
19+
20+Having an accurate measure of productivity losses caused by resource
21+scarcity aids users in sizing workloads to hardware--or provisioning
22+hardware according to workload demand.
23+
24+As psi aggregates this information in realtime, systems can be managed
25+dynamically using techniques such as load shedding, migrating jobs to
26+other systems or data centers, or strategically pausing or killing low
27+priority or restartable batch jobs.
28+
29+This allows maximizing hardware utilization without sacrificing
30+workload health or risking major disruptions such as OOM kills.
31+
32+Pressure interface
33+==================
34+
35+Pressure information for each resource is exported through the
36+respective file in /proc/pressure/ -- cpu, memory, and io.
37+
38+The format for CPU is as such::
39+
40+ some avg10=0.00 avg60=0.00 avg300=0.00 total=0
41+
42+and for memory and IO::
43+
44+ some avg10=0.00 avg60=0.00 avg300=0.00 total=0
45+ full avg10=0.00 avg60=0.00 avg300=0.00 total=0
46+
47+The "some" line indicates the share of time in which at least some
48+tasks are stalled on a given resource.
49+
50+The "full" line indicates the share of time in which all non-idle
51+tasks are stalled on a given resource simultaneously. In this state
52+actual CPU cycles are going to waste, and a workload that spends
53+extended time in this state is considered to be thrashing. This has
54+severe impact on performance, and it's useful to distinguish this
55+situation from a state where some tasks are stalled but the CPU is
56+still doing productive work. As such, time spent in this subset of the
57+stall state is tracked separately and exported in the "full" averages.
58+
59+The ratios (in %) are tracked as recent trends over ten, sixty, and
60+three hundred second windows, which gives insight into short term events
61+as well as medium and long term trends. The total absolute stall time
62+(in us) is tracked and exported as well, to allow detection of latency
63+spikes which wouldn't necessarily make a dent in the time averages,
64+or to average trends over custom time frames.
65+
66+Monitoring for pressure thresholds
67+==================================
68+
69+Users can register triggers and use poll() to be woken up when resource
70+pressure exceeds certain thresholds.
71+
72+A trigger describes the maximum cumulative stall time over a specific
73+time window, e.g. 100ms of total stall time within any 500ms window to
74+generate a wakeup event.
75+
76+To register a trigger user has to open psi interface file under
77+/proc/pressure/ representing the resource to be monitored and write the
78+desired threshold and time window. The open file descriptor should be
79+used to wait for trigger events using select(), poll() or epoll().
80+The following format is used::
81+
82+ <some|full> <stall amount in us> <time window in us>
83+
84+For example writing "some 150000 1000000" into /proc/pressure/memory
85+would add 150ms threshold for partial memory stall measured within
86+1sec time window. Writing "full 50000 1000000" into /proc/pressure/io
87+would add 50ms threshold for full io stall measured within 1sec time window.
88+
89+Triggers can be set on more than one psi metric and more than one trigger
90+for the same psi metric can be specified. However for each trigger a separate
91+file descriptor is required to be able to poll it separately from others,
92+therefore for each trigger a separate open() syscall should be made even
93+when opening the same psi interface file.
94+
95+Monitors activate only when system enters stall state for the monitored
96+psi metric and deactivates upon exit from the stall state. While system is
97+in the stall state psi signal growth is monitored at a rate of 10 times per
98+tracking window.
99+
100+The kernel accepts window sizes ranging from 500ms to 10s, therefore min
101+monitoring update interval is 50ms and max is 1s. Min limit is set to
102+prevent overly frequent polling. Max limit is chosen as a high enough number
103+after which monitors are most likely not needed and psi averages can be used
104+instead.
105+
106+When activated, psi monitor stays active for at least the duration of one
107+tracking window to avoid repeated activations/deactivations when system is
108+bouncing in and out of the stall state.
109+
110+Notifications to the userspace are rate-limited to one per tracking window.
111+
112+The trigger will de-register when the file descriptor used to define the
113+trigger is closed.
114+
115+Userspace monitor usage example
116+===============================
117+
118+::
119+
120+ #include <errno.h>
121+ #include <fcntl.h>
122+ #include <stdio.h>
123+ #include <poll.h>
124+ #include <string.h>
125+ #include <unistd.h>
126+
127+ /*
128+ * Monitor memory partial stall with 1s tracking window size
129+ * and 150ms threshold.
130+ */
131+ int main() {
132+ const char trig[] = "some 150000 1000000";
133+ struct pollfd fds;
134+ int n;
135+
136+ fds.fd = open("/proc/pressure/memory", O_RDWR | O_NONBLOCK);
137+ if (fds.fd < 0) {
138+ printf("/proc/pressure/memory open error: %s\n",
139+ strerror(errno));
140+ return 1;
141+ }
142+ fds.events = POLLPRI;
143+
144+ if (write(fds.fd, trig, strlen(trig) + 1) < 0) {
145+ printf("/proc/pressure/memory write error: %s\n",
146+ strerror(errno));
147+ return 1;
148+ }
149+
150+ printf("waiting for events...\n");
151+ while (1) {
152+ n = poll(&fds, 1, -1);
153+ if (n < 0) {
154+ printf("poll error: %s\n", strerror(errno));
155+ return 1;
156+ }
157+ if (fds.revents & POLLERR) {
158+ printf("got POLLERR, event source is gone\n");
159+ return 0;
160+ }
161+ if (fds.revents & POLLPRI) {
162+ printf("event triggered!\n");
163+ } else {
164+ printf("unknown event received: 0x%x\n", fds.revents);
165+ return 1;
166+ }
167+ }
168+
169+ return 0;
170+ }
171+
172+Cgroup2 interface
173+=================
174+
175+In a system with a CONFIG_CGROUP=y kernel and the cgroup2 filesystem
176+mounted, pressure stall information is also tracked for tasks grouped
177+into cgroups. Each subdirectory in the cgroupfs mountpoint contains
178+cpu.pressure, memory.pressure, and io.pressure files; the format is
179+the same as the /proc/pressure/ files.
180+
181+Per-cgroup psi monitors can be specified and used the same way as
182+system-wide ones.
Documentation/accounting/psi.txt+0−180
@@ -1,180 +0,0 @@
1−================================
2−PSI - Pressure Stall Information
3−================================
4−
5−:Date: April, 2018
6−:Author: Johannes Weiner <hannes@cmpxchg.org>
7−
8−When CPU, memory or IO devices are contended, workloads experience
9−latency spikes, throughput losses, and run the risk of OOM kills.
10−
11−Without an accurate measure of such contention, users are forced to
12−either play it safe and under-utilize their hardware resources, or
13−roll the dice and frequently suffer the disruptions resulting from
14−excessive overcommit.
15−
16−The psi feature identifies and quantifies the disruptions caused by
17−such resource crunches and the time impact it has on complex workloads
18−or even entire systems.
19−
20−Having an accurate measure of productivity losses caused by resource
21−scarcity aids users in sizing workloads to hardware--or provisioning
22−hardware according to workload demand.
23−
24−As psi aggregates this information in realtime, systems can be managed
25−dynamically using techniques such as load shedding, migrating jobs to
26−other systems or data centers, or strategically pausing or killing low
27−priority or restartable batch jobs.
28−
29−This allows maximizing hardware utilization without sacrificing
30−workload health or risking major disruptions such as OOM kills.
31−
32−Pressure interface
33−==================
34−
35−Pressure information for each resource is exported through the
36−respective file in /proc/pressure/ -- cpu, memory, and io.
37−
38−The format for CPU is as such:
39−
40−some avg10=0.00 avg60=0.00 avg300=0.00 total=0
41−
42−and for memory and IO:
43−
44−some avg10=0.00 avg60=0.00 avg300=0.00 total=0
45−full avg10=0.00 avg60=0.00 avg300=0.00 total=0
46−
47−The "some" line indicates the share of time in which at least some
48−tasks are stalled on a given resource.
49−
50−The "full" line indicates the share of time in which all non-idle
51−tasks are stalled on a given resource simultaneously. In this state
52−actual CPU cycles are going to waste, and a workload that spends
53−extended time in this state is considered to be thrashing. This has
54−severe impact on performance, and it's useful to distinguish this
55−situation from a state where some tasks are stalled but the CPU is
56−still doing productive work. As such, time spent in this subset of the
57−stall state is tracked separately and exported in the "full" averages.
58−
59−The ratios (in %) are tracked as recent trends over ten, sixty, and
60−three hundred second windows, which gives insight into short term events
61−as well as medium and long term trends. The total absolute stall time
62−(in us) is tracked and exported as well, to allow detection of latency
63−spikes which wouldn't necessarily make a dent in the time averages,
64−or to average trends over custom time frames.
65−
66−Monitoring for pressure thresholds
67−==================================
68−
69−Users can register triggers and use poll() to be woken up when resource
70−pressure exceeds certain thresholds.
71−
72−A trigger describes the maximum cumulative stall time over a specific
73−time window, e.g. 100ms of total stall time within any 500ms window to
74−generate a wakeup event.
75−
76−To register a trigger user has to open psi interface file under
77−/proc/pressure/ representing the resource to be monitored and write the
78−desired threshold and time window. The open file descriptor should be
79−used to wait for trigger events using select(), poll() or epoll().
80−The following format is used:
81−
82−<some|full> <stall amount in us> <time window in us>
83−
84−For example writing "some 150000 1000000" into /proc/pressure/memory
85−would add 150ms threshold for partial memory stall measured within
86−1sec time window. Writing "full 50000 1000000" into /proc/pressure/io
87−would add 50ms threshold for full io stall measured within 1sec time window.
88−
89−Triggers can be set on more than one psi metric and more than one trigger
90−for the same psi metric can be specified. However for each trigger a separate
91−file descriptor is required to be able to poll it separately from others,
92−therefore for each trigger a separate open() syscall should be made even
93−when opening the same psi interface file.
94−
95−Monitors activate only when system enters stall state for the monitored
96−psi metric and deactivates upon exit from the stall state. While system is
97−in the stall state psi signal growth is monitored at a rate of 10 times per
98−tracking window.
99−
100−The kernel accepts window sizes ranging from 500ms to 10s, therefore min
101−monitoring update interval is 50ms and max is 1s. Min limit is set to
102−prevent overly frequent polling. Max limit is chosen as a high enough number
103−after which monitors are most likely not needed and psi averages can be used
104−instead.
105−
106−When activated, psi monitor stays active for at least the duration of one
107−tracking window to avoid repeated activations/deactivations when system is
108−bouncing in and out of the stall state.
109−
110−Notifications to the userspace are rate-limited to one per tracking window.
111−
112−The trigger will de-register when the file descriptor used to define the
113−trigger is closed.
114−
115−Userspace monitor usage example
116−===============================
117−
118−#include <errno.h>
119−#include <fcntl.h>
120−#include <stdio.h>
121−#include <poll.h>
122−#include <string.h>
123−#include <unistd.h>
124−
125−/*
126− * Monitor memory partial stall with 1s tracking window size
127− * and 150ms threshold.
128− */
129−int main() {
130− const char trig[] = "some 150000 1000000";
131− struct pollfd fds;
132− int n;
133−
134− fds.fd = open("/proc/pressure/memory", O_RDWR | O_NONBLOCK);
135− if (fds.fd < 0) {
136− printf("/proc/pressure/memory open error: %s\n",
137− strerror(errno));
138− return 1;
139− }
140− fds.events = POLLPRI;
141−
142− if (write(fds.fd, trig, strlen(trig) + 1) < 0) {
143− printf("/proc/pressure/memory write error: %s\n",
144− strerror(errno));
145− return 1;
146− }
147−
148− printf("waiting for events...\n");
149− while (1) {
150− n = poll(&fds, 1, -1);
151− if (n < 0) {
152− printf("poll error: %s\n", strerror(errno));
153− return 1;
154− }
155− if (fds.revents & POLLERR) {
156− printf("got POLLERR, event source is gone\n");
157− return 0;
158− }
159− if (fds.revents & POLLPRI) {
160− printf("event triggered!\n");
161− } else {
162− printf("unknown event received: 0x%x\n", fds.revents);
163− return 1;
164− }
165− }
166−
167− return 0;
168−}
169−
170−Cgroup2 interface
171−=================
172−
173−In a system with a CONFIG_CGROUP=y kernel and the cgroup2 filesystem
174−mounted, pressure stall information is also tracked for tasks grouped
175−into cgroups. Each subdirectory in the cgroupfs mountpoint contains
176−cpu.pressure, memory.pressure, and io.pressure files; the format is
177−the same as the /proc/pressure/ files.
178−
179−Per-cgroup psi monitors can be specified and used the same way as
180−system-wide ones.
Documentation/accounting/taskstats-struct.rst+199−0
@@ -0,0 +1,199 @@
1+====================
2+The struct taskstats
3+====================
4+
5+This document contains an explanation of the struct taskstats fields.
6+
7+There are three different groups of fields in the struct taskstats:
8+
9+1) Common and basic accounting fields
10+ If CONFIG_TASKSTATS is set, the taskstats interface is enabled and
11+ the common fields and basic accounting fields are collected for
12+ delivery at do_exit() of a task.
13+2) Delay accounting fields
14+ These fields are placed between::
15+
16+ /* Delay accounting fields start */
17+
18+ and::
19+
20+ /* Delay accounting fields end */
21+
22+ Their values are collected if CONFIG_TASK_DELAY_ACCT is set.
23+3) Extended accounting fields
24+ These fields are placed between::
25+
26+ /* Extended accounting fields start */
27+
28+ and::
29+
30+ /* Extended accounting fields end */
31+
32+ Their values are collected if CONFIG_TASK_XACCT is set.
33+
34+4) Per-task and per-thread context switch count statistics
35+
36+5) Time accounting for SMT machines
37+
38+6) Extended delay accounting fields for memory reclaim
39+
40+Future extension should add fields to the end of the taskstats struct, and
41+should not change the relative position of each field within the struct.
42+
43+::
44+
45+ struct taskstats {
46+
47+1) Common and basic accounting fields::
48+
49+ /* The version number of this struct. This field is always set to
50+ * TAKSTATS_VERSION, which is defined in <linux/taskstats.h>.
51+ * Each time the struct is changed, the value should be incremented.
52+ */
53+ __u16 version;
54+
55+ /* The exit code of a task. */
56+ __u32 ac_exitcode; /* Exit status */
57+
58+ /* The accounting flags of a task as defined in <linux/acct.h>
59+ * Defined values are AFORK, ASU, ACOMPAT, ACORE, and AXSIG.
60+ */
61+ __u8 ac_flag; /* Record flags */
62+
63+ /* The value of task_nice() of a task. */
64+ __u8 ac_nice; /* task_nice */
65+
66+ /* The name of the command that started this task. */
67+ char ac_comm[TS_COMM_LEN]; /* Command name */
68+
69+ /* The scheduling discipline as set in task->policy field. */
70+ __u8 ac_sched; /* Scheduling discipline */
71+
72+ __u8 ac_pad[3];
73+ __u32 ac_uid; /* User ID */
74+ __u32 ac_gid; /* Group ID */
75+ __u32 ac_pid; /* Process ID */
76+ __u32 ac_ppid; /* Parent process ID */
77+
78+ /* The time when a task begins, in [secs] since 1970. */
79+ __u32 ac_btime; /* Begin time [sec since 1970] */
80+
81+ /* The elapsed time of a task, in [usec]. */
82+ __u64 ac_etime; /* Elapsed time [usec] */
83+
84+ /* The user CPU time of a task, in [usec]. */
85+ __u64 ac_utime; /* User CPU time [usec] */
86+
87+ /* The system CPU time of a task, in [usec]. */
88+ __u64 ac_stime; /* System CPU time [usec] */
89+
90+ /* The minor page fault count of a task, as set in task->min_flt. */
91+ __u64 ac_minflt; /* Minor Page Fault Count */
92+
93+ /* The major page fault count of a task, as set in task->maj_flt. */
94+ __u64 ac_majflt; /* Major Page Fault Count */
95+
96+
97+2) Delay accounting fields::
98+
99+ /* Delay accounting fields start
100+ *
101+ * All values, until the comment "Delay accounting fields end" are
102+ * available only if delay accounting is enabled, even though the last
103+ * few fields are not delays
104+ *
105+ * xxx_count is the number of delay values recorded
106+ * xxx_delay_total is the corresponding cumulative delay in nanoseconds
107+ *
108+ * xxx_delay_total wraps around to zero on overflow
109+ * xxx_count incremented regardless of overflow
110+ */
111+
112+ /* Delay waiting for cpu, while runnable
113+ * count, delay_total NOT updated atomically
114+ */
115+ __u64 cpu_count;
116+ __u64 cpu_delay_total;
117+
118+ /* Following four fields atomically updated using task->delays->lock */
119+
120+ /* Delay waiting for synchronous block I/O to complete
121+ * does not account for delays in I/O submission
122+ */
123+ __u64 blkio_count;
124+ __u64 blkio_delay_total;
125+
126+ /* Delay waiting for page fault I/O (swap in only) */
127+ __u64 swapin_count;
128+ __u64 swapin_delay_total;
129+
130+ /* cpu "wall-clock" running time
131+ * On some architectures, value will adjust for cpu time stolen
132+ * from the kernel in involuntary waits due to virtualization.
133+ * Value is cumulative, in nanoseconds, without a corresponding count
134+ * and wraps around to zero silently on overflow
135+ */
136+ __u64 cpu_run_real_total;
137+
138+ /* cpu "virtual" running time
139+ * Uses time intervals seen by the kernel i.e. no adjustment
140+ * for kernel's involuntary waits due to virtualization.
141+ * Value is cumulative, in nanoseconds, without a corresponding count
142+ * and wraps around to zero silently on overflow
143+ */
144+ __u64 cpu_run_virtual_total;
145+ /* Delay accounting fields end */
146+ /* version 1 ends here */
147+
148+
149+3) Extended accounting fields::
150+
151+ /* Extended accounting fields start */
152+
153+ /* Accumulated RSS usage in duration of a task, in MBytes-usecs.
154+ * The current rss usage is added to this counter every time
155+ * a tick is charged to a task's system time. So, at the end we
156+ * will have memory usage multiplied by system time. Thus an
157+ * average usage per system time unit can be calculated.
158+ */
159+ __u64 coremem; /* accumulated RSS usage in MB-usec */
160+
161+ /* Accumulated virtual memory usage in duration of a task.
162+ * Same as acct_rss_mem1 above except that we keep track of VM usage.
163+ */
164+ __u64 virtmem; /* accumulated VM usage in MB-usec */
165+
166+ /* High watermark of RSS usage in duration of a task, in KBytes. */
167+ __u64 hiwater_rss; /* High-watermark of RSS usage */
168+
169+ /* High watermark of VM usage in duration of a task, in KBytes. */
170+ __u64 hiwater_vm; /* High-water virtual memory usage */
171+
172+ /* The following four fields are I/O statistics of a task. */
173+ __u64 read_char; /* bytes read */
174+ __u64 write_char; /* bytes written */
175+ __u64 read_syscalls; /* read syscalls */
176+ __u64 write_syscalls; /* write syscalls */
177+
178+ /* Extended accounting fields end */
179+
180+4) Per-task and per-thread statistics::
181+
182+ __u64 nvcsw; /* Context voluntary switch counter */
183+ __u64 nivcsw; /* Context involuntary switch counter */
184+
185+5) Time accounting for SMT machines::
186+
187+ __u64 ac_utimescaled; /* utime scaled on frequency etc */
188+ __u64 ac_stimescaled; /* stime scaled on frequency etc */
189+ __u64 cpu_scaled_run_real_total; /* scaled cpu_run_real_total */
190+
191+6) Extended delay accounting fields for memory reclaim::
192+
193+ /* Delay waiting for memory reclaim */
194+ __u64 freepages_count;
195+ __u64 freepages_delay_total;
196+
197+::
198+
199+ }
Documentation/accounting/taskstats-struct.txt+0−180
@@ -1,180 +0,0 @@
1−The struct taskstats
2−--------------------
3−
4−This document contains an explanation of the struct taskstats fields.
5−
6−There are three different groups of fields in the struct taskstats:
7−
8−1) Common and basic accounting fields
9− If CONFIG_TASKSTATS is set, the taskstats interface is enabled and
10− the common fields and basic accounting fields are collected for
11− delivery at do_exit() of a task.
12−2) Delay accounting fields
13− These fields are placed between
14− /* Delay accounting fields start */
15− and
16− /* Delay accounting fields end */
17− Their values are collected if CONFIG_TASK_DELAY_ACCT is set.
18−3) Extended accounting fields
19− These fields are placed between
20− /* Extended accounting fields start */
21− and
22− /* Extended accounting fields end */
23− Their values are collected if CONFIG_TASK_XACCT is set.
24−
25−4) Per-task and per-thread context switch count statistics
26−
27−5) Time accounting for SMT machines
28−
29−6) Extended delay accounting fields for memory reclaim
30−
31−Future extension should add fields to the end of the taskstats struct, and
32−should not change the relative position of each field within the struct.
33−
34−
35−struct taskstats {
36−
37−1) Common and basic accounting fields:
38− /* The version number of this struct. This field is always set to
39− * TAKSTATS_VERSION, which is defined in <linux/taskstats.h>.
40− * Each time the struct is changed, the value should be incremented.
41− */
42− __u16 version;
43−
44− /* The exit code of a task. */
45− __u32 ac_exitcode; /* Exit status */
46−
47− /* The accounting flags of a task as defined in <linux/acct.h>
48− * Defined values are AFORK, ASU, ACOMPAT, ACORE, and AXSIG.
49− */
50− __u8 ac_flag; /* Record flags */
51−
52− /* The value of task_nice() of a task. */
53− __u8 ac_nice; /* task_nice */
54−
55− /* The name of the command that started this task. */
56− char ac_comm[TS_COMM_LEN]; /* Command name */
57−
58− /* The scheduling discipline as set in task->policy field. */
59− __u8 ac_sched; /* Scheduling discipline */
60−
61− __u8 ac_pad[3];
62− __u32 ac_uid; /* User ID */
63− __u32 ac_gid; /* Group ID */
64− __u32 ac_pid; /* Process ID */
65− __u32 ac_ppid; /* Parent process ID */
66−
67− /* The time when a task begins, in [secs] since 1970. */
68− __u32 ac_btime; /* Begin time [sec since 1970] */
69−
70− /* The elapsed time of a task, in [usec]. */
71− __u64 ac_etime; /* Elapsed time [usec] */
72−
73− /* The user CPU time of a task, in [usec]. */
74− __u64 ac_utime; /* User CPU time [usec] */
75−
76− /* The system CPU time of a task, in [usec]. */
77− __u64 ac_stime; /* System CPU time [usec] */
78−
79− /* The minor page fault count of a task, as set in task->min_flt. */
80− __u64 ac_minflt; /* Minor Page Fault Count */
81−
82− /* The major page fault count of a task, as set in task->maj_flt. */
83− __u64 ac_majflt; /* Major Page Fault Count */
84−
85−
86−2) Delay accounting fields:
87− /* Delay accounting fields start
88− *
89− * All values, until the comment "Delay accounting fields end" are
90− * available only if delay accounting is enabled, even though the last
91− * few fields are not delays
92− *
93− * xxx_count is the number of delay values recorded
94− * xxx_delay_total is the corresponding cumulative delay in nanoseconds
95− *
96− * xxx_delay_total wraps around to zero on overflow
97− * xxx_count incremented regardless of overflow
98− */
99−
100− /* Delay waiting for cpu, while runnable
101− * count, delay_total NOT updated atomically
102− */
103− __u64 cpu_count;
104− __u64 cpu_delay_total;
105−
106− /* Following four fields atomically updated using task->delays->lock */
107−
108− /* Delay waiting for synchronous block I/O to complete
109− * does not account for delays in I/O submission
110− */
111− __u64 blkio_count;
112− __u64 blkio_delay_total;
113−
114− /* Delay waiting for page fault I/O (swap in only) */
115− __u64 swapin_count;
116− __u64 swapin_delay_total;
117−
118− /* cpu "wall-clock" running time
119− * On some architectures, value will adjust for cpu time stolen
120− * from the kernel in involuntary waits due to virtualization.
121− * Value is cumulative, in nanoseconds, without a corresponding count
122− * and wraps around to zero silently on overflow
123− */
124− __u64 cpu_run_real_total;
125−
126− /* cpu "virtual" running time
127− * Uses time intervals seen by the kernel i.e. no adjustment
128− * for kernel's involuntary waits due to virtualization.
129− * Value is cumulative, in nanoseconds, without a corresponding count
130− * and wraps around to zero silently on overflow
131− */
132− __u64 cpu_run_virtual_total;
133− /* Delay accounting fields end */
134− /* version 1 ends here */
135−
136−
137−3) Extended accounting fields
138− /* Extended accounting fields start */
139−
140− /* Accumulated RSS usage in duration of a task, in MBytes-usecs.
141− * The current rss usage is added to this counter every time
142− * a tick is charged to a task's system time. So, at the end we
143− * will have memory usage multiplied by system time. Thus an
144− * average usage per system time unit can be calculated.
145− */
146− __u64 coremem; /* accumulated RSS usage in MB-usec */
147−
148− /* Accumulated virtual memory usage in duration of a task.
149− * Same as acct_rss_mem1 above except that we keep track of VM usage.
150− */
151− __u64 virtmem; /* accumulated VM usage in MB-usec */
152−
153− /* High watermark of RSS usage in duration of a task, in KBytes. */
154− __u64 hiwater_rss; /* High-watermark of RSS usage */
155−
156− /* High watermark of VM usage in duration of a task, in KBytes. */
157− __u64 hiwater_vm; /* High-water virtual memory usage */
158−
159− /* The following four fields are I/O statistics of a task. */
160− __u64 read_char; /* bytes read */
161− __u64 write_char; /* bytes written */
162− __u64 read_syscalls; /* read syscalls */
163− __u64 write_syscalls; /* write syscalls */
164−
165− /* Extended accounting fields end */
166−
167−4) Per-task and per-thread statistics
168− __u64 nvcsw; /* Context voluntary switch counter */
169− __u64 nivcsw; /* Context involuntary switch counter */
170−
171−5) Time accounting for SMT machines
172− __u64 ac_utimescaled; /* utime scaled on frequency etc */
173− __u64 ac_stimescaled; /* stime scaled on frequency etc */
174− __u64 cpu_scaled_run_real_total; /* scaled cpu_run_real_total */
175−
176−6) Extended delay accounting fields for memory reclaim
177− /* Delay waiting for memory reclaim */
178− __u64 freepages_count;
179− __u64 freepages_delay_total;
180−}
Documentation/accounting/taskstats.rst+180−0
@@ -0,0 +1,180 @@
1+=============================
2+Per-task statistics interface
3+=============================
4+
5+
6+Taskstats is a netlink-based interface for sending per-task and
7+per-process statistics from the kernel to userspace.
8+
9+Taskstats was designed for the following benefits:
10+
11+- efficiently provide statistics during lifetime of a task and on its exit
12+- unified interface for multiple accounting subsystems
13+- extensibility for use by future accounting patches
14+
15+Terminology
16+-----------
17+
18+"pid", "tid" and "task" are used interchangeably and refer to the standard
19+Linux task defined by struct task_struct. per-pid stats are the same as
20+per-task stats.
21+
22+"tgid", "process" and "thread group" are used interchangeably and refer to the
23+tasks that share an mm_struct i.e. the traditional Unix process. Despite the
24+use of tgid, there is no special treatment for the task that is thread group
25+leader - a process is deemed alive as long as it has any task belonging to it.
26+
27+Usage
28+-----
29+
30+To get statistics during a task's lifetime, userspace opens a unicast netlink
31+socket (NETLINK_GENERIC family) and sends commands specifying a pid or a tgid.
32+The response contains statistics for a task (if pid is specified) or the sum of
33+statistics for all tasks of the process (if tgid is specified).
34+
35+To obtain statistics for tasks which are exiting, the userspace listener
36+sends a register command and specifies a cpumask. Whenever a task exits on
37+one of the cpus in the cpumask, its per-pid statistics are sent to the
38+registered listener. Using cpumasks allows the data received by one listener
39+to be limited and assists in flow control over the netlink interface and is
40+explained in more detail below.
41+
42+If the exiting task is the last thread exiting its thread group,
43+an additional record containing the per-tgid stats is also sent to userspace.
44+The latter contains the sum of per-pid stats for all threads in the thread
45+group, both past and present.
46+
47+getdelays.c is a simple utility demonstrating usage of the taskstats interface
48+for reporting delay accounting statistics. Users can register cpumasks,
49+send commands and process responses, listen for per-tid/tgid exit data,
50+write the data received to a file and do basic flow control by increasing
51+receive buffer sizes.
52+
53+Interface
54+---------
55+
56+The user-kernel interface is encapsulated in include/linux/taskstats.h
57+
58+To avoid this documentation becoming obsolete as the interface evolves, only
59+an outline of the current version is given. taskstats.h always overrides the
60+description here.
61+
62+struct taskstats is the common accounting structure for both per-pid and
63+per-tgid data. It is versioned and can be extended by each accounting subsystem
64+that is added to the kernel. The fields and their semantics are defined in the
65+taskstats.h file.
66+
67+The data exchanged between user and kernel space is a netlink message belonging
68+to the NETLINK_GENERIC family and using the netlink attributes interface.
69+The messages are in the format::
70+
71+ +----------+- - -+-------------+-------------------+
72+ | nlmsghdr | Pad | genlmsghdr | taskstats payload |
73+ +----------+- - -+-------------+-------------------+
74+
75+
76+The taskstats payload is one of the following three kinds:
77+
78+1. Commands: Sent from user to kernel. Commands to get data on
79+a pid/tgid consist of one attribute, of type TASKSTATS_CMD_ATTR_PID/TGID,
80+containing a u32 pid or tgid in the attribute payload. The pid/tgid denotes
81+the task/process for which userspace wants statistics.
82+
83+Commands to register/deregister interest in exit data from a set of cpus
84+consist of one attribute, of type
85+TASKSTATS_CMD_ATTR_REGISTER/DEREGISTER_CPUMASK and contain a cpumask in the
86+attribute payload. The cpumask is specified as an ascii string of
87+comma-separated cpu ranges e.g. to listen to exit data from cpus 1,2,3,5,7,8
88+the cpumask would be "1-3,5,7-8". If userspace forgets to deregister interest
89+in cpus before closing the listening socket, the kernel cleans up its interest
90+set over time. However, for the sake of efficiency, an explicit deregistration
91+is advisable.
92+
93+2. Response for a command: sent from the kernel in response to a userspace
94+command. The payload is a series of three attributes of type:
95+
96+a) TASKSTATS_TYPE_AGGR_PID/TGID : attribute containing no payload but indicates
97+a pid/tgid will be followed by some stats.
98+
99+b) TASKSTATS_TYPE_PID/TGID: attribute whose payload is the pid/tgid whose stats
100+are being returned.
101+
102+c) TASKSTATS_TYPE_STATS: attribute with a struct taskstats as payload. The
103+same structure is used for both per-pid and per-tgid stats.
104+
105+3. New message sent by kernel whenever a task exits. The payload consists of a
106+ series of attributes of the following type:
107+
108+a) TASKSTATS_TYPE_AGGR_PID: indicates next two attributes will be pid+stats
109+b) TASKSTATS_TYPE_PID: contains exiting task's pid
110+c) TASKSTATS_TYPE_STATS: contains the exiting task's per-pid stats
111+d) TASKSTATS_TYPE_AGGR_TGID: indicates next two attributes will be tgid+stats
112+e) TASKSTATS_TYPE_TGID: contains tgid of process to which task belongs
113+f) TASKSTATS_TYPE_STATS: contains the per-tgid stats for exiting task's process
114+
115+
116+per-tgid stats
117+--------------
118+
119+Taskstats provides per-process stats, in addition to per-task stats, since
120+resource management is often done at a process granularity and aggregating task
121+stats in userspace alone is inefficient and potentially inaccurate (due to lack
122+of atomicity).
123+
124+However, maintaining per-process, in addition to per-task stats, within the
125+kernel has space and time overheads. To address this, the taskstats code
126+accumulates each exiting task's statistics into a process-wide data structure.
127+When the last task of a process exits, the process level data accumulated also
128+gets sent to userspace (along with the per-task data).
129+
130+When a user queries to get per-tgid data, the sum of all other live threads in
131+the group is added up and added to the accumulated total for previously exited
132+threads of the same thread group.
133+
134+Extending taskstats
135+-------------------
136+
137+There are two ways to extend the taskstats interface to export more
138+per-task/process stats as patches to collect them get added to the kernel
139+in future:
140+
141+1. Adding more fields to the end of the existing struct taskstats. Backward
142+ compatibility is ensured by the version number within the
143+ structure. Userspace will use only the fields of the struct that correspond
144+ to the version its using.
145+
146+2. Defining separate statistic structs and using the netlink attributes
147+ interface to return them. Since userspace processes each netlink attribute
148+ independently, it can always ignore attributes whose type it does not
149+ understand (because it is using an older version of the interface).
150+
151+
152+Choosing between 1. and 2. is a matter of trading off flexibility and
153+overhead. If only a few fields need to be added, then 1. is the preferable
154+path since the kernel and userspace don't need to incur the overhead of
155+processing new netlink attributes. But if the new fields expand the existing
156+struct too much, requiring disparate userspace accounting utilities to
157+unnecessarily receive large structures whose fields are of no interest, then
158+extending the attributes structure would be worthwhile.
159+
160+Flow control for taskstats
161+--------------------------
162+
163+When the rate of task exits becomes large, a listener may not be able to keep
164+up with the kernel's rate of sending per-tid/tgid exit data leading to data
165+loss. This possibility gets compounded when the taskstats structure gets
166+extended and the number of cpus grows large.
167+
168+To avoid losing statistics, userspace should do one or more of the following:
169+
170+- increase the receive buffer sizes for the netlink sockets opened by
171+ listeners to receive exit data.
172+
173+- create more listeners and reduce the number of cpus being listened to by
174+ each listener. In the extreme case, there could be one listener for each cpu.
175+ Users may also consider setting the cpu affinity of the listener to the subset
176+ of cpus to which it listens, especially if they are listening to just one cpu.
177+
178+Despite these measures, if the userspace receives ENOBUFS error messages
179+indicated overflow of receive buffers, it should take measures to handle the
180+loss of data.
Documentation/accounting/taskstats.txt+0−181
@@ -1,181 +0,0 @@
1−Per-task statistics interface
2−-----------------------------
3−
4−
5−Taskstats is a netlink-based interface for sending per-task and
6−per-process statistics from the kernel to userspace.
7−
8−Taskstats was designed for the following benefits:
9−
10−- efficiently provide statistics during lifetime of a task and on its exit
11−- unified interface for multiple accounting subsystems
12−- extensibility for use by future accounting patches
13−
14−Terminology
15−-----------
16−
17−"pid", "tid" and "task" are used interchangeably and refer to the standard
18−Linux task defined by struct task_struct. per-pid stats are the same as
19−per-task stats.
20−
21−"tgid", "process" and "thread group" are used interchangeably and refer to the
22−tasks that share an mm_struct i.e. the traditional Unix process. Despite the
23−use of tgid, there is no special treatment for the task that is thread group
24−leader - a process is deemed alive as long as it has any task belonging to it.
25−
26−Usage
27−-----
28−
29−To get statistics during a task's lifetime, userspace opens a unicast netlink
30−socket (NETLINK_GENERIC family) and sends commands specifying a pid or a tgid.
31−The response contains statistics for a task (if pid is specified) or the sum of
32−statistics for all tasks of the process (if tgid is specified).
33−
34−To obtain statistics for tasks which are exiting, the userspace listener
35−sends a register command and specifies a cpumask. Whenever a task exits on
36−one of the cpus in the cpumask, its per-pid statistics are sent to the
37−registered listener. Using cpumasks allows the data received by one listener
38−to be limited and assists in flow control over the netlink interface and is
39−explained in more detail below.
40−
41−If the exiting task is the last thread exiting its thread group,
42−an additional record containing the per-tgid stats is also sent to userspace.
43−The latter contains the sum of per-pid stats for all threads in the thread
44−group, both past and present.
45−
46−getdelays.c is a simple utility demonstrating usage of the taskstats interface
47−for reporting delay accounting statistics. Users can register cpumasks,
48−send commands and process responses, listen for per-tid/tgid exit data,
49−write the data received to a file and do basic flow control by increasing
50−receive buffer sizes.
51−
52−Interface
53−---------
54−
55−The user-kernel interface is encapsulated in include/linux/taskstats.h
56−
57−To avoid this documentation becoming obsolete as the interface evolves, only
58−an outline of the current version is given. taskstats.h always overrides the
59−description here.
60−
61−struct taskstats is the common accounting structure for both per-pid and
62−per-tgid data. It is versioned and can be extended by each accounting subsystem
63−that is added to the kernel. The fields and their semantics are defined in the
64−taskstats.h file.
65−
66−The data exchanged between user and kernel space is a netlink message belonging
67−to the NETLINK_GENERIC family and using the netlink attributes interface.
68−The messages are in the format
69−
70− +----------+- - -+-------------+-------------------+
71− | nlmsghdr | Pad | genlmsghdr | taskstats payload |
72− +----------+- - -+-------------+-------------------+
73−
74−
75−The taskstats payload is one of the following three kinds:
76−
77−1. Commands: Sent from user to kernel. Commands to get data on
78−a pid/tgid consist of one attribute, of type TASKSTATS_CMD_ATTR_PID/TGID,
79−containing a u32 pid or tgid in the attribute payload. The pid/tgid denotes
80−the task/process for which userspace wants statistics.
81−
82−Commands to register/deregister interest in exit data from a set of cpus
83−consist of one attribute, of type
84−TASKSTATS_CMD_ATTR_REGISTER/DEREGISTER_CPUMASK and contain a cpumask in the
85−attribute payload. The cpumask is specified as an ascii string of
86−comma-separated cpu ranges e.g. to listen to exit data from cpus 1,2,3,5,7,8
87−the cpumask would be "1-3,5,7-8". If userspace forgets to deregister interest
88−in cpus before closing the listening socket, the kernel cleans up its interest
89−set over time. However, for the sake of efficiency, an explicit deregistration
90−is advisable.
91−
92−2. Response for a command: sent from the kernel in response to a userspace
93−command. The payload is a series of three attributes of type:
94−
95−a) TASKSTATS_TYPE_AGGR_PID/TGID : attribute containing no payload but indicates
96−a pid/tgid will be followed by some stats.
97−
98−b) TASKSTATS_TYPE_PID/TGID: attribute whose payload is the pid/tgid whose stats
99−are being returned.
100−
101−c) TASKSTATS_TYPE_STATS: attribute with a struct taskstats as payload. The
102−same structure is used for both per-pid and per-tgid stats.
103−
104−3. New message sent by kernel whenever a task exits. The payload consists of a
105− series of attributes of the following type:
106−
107−a) TASKSTATS_TYPE_AGGR_PID: indicates next two attributes will be pid+stats
108−b) TASKSTATS_TYPE_PID: contains exiting task's pid
109−c) TASKSTATS_TYPE_STATS: contains the exiting task's per-pid stats
110−d) TASKSTATS_TYPE_AGGR_TGID: indicates next two attributes will be tgid+stats
111−e) TASKSTATS_TYPE_TGID: contains tgid of process to which task belongs
112−f) TASKSTATS_TYPE_STATS: contains the per-tgid stats for exiting task's process
113−
114−
115−per-tgid stats
116−--------------
117−
118−Taskstats provides per-process stats, in addition to per-task stats, since
119−resource management is often done at a process granularity and aggregating task
120−stats in userspace alone is inefficient and potentially inaccurate (due to lack
121−of atomicity).
122−
123−However, maintaining per-process, in addition to per-task stats, within the
124−kernel has space and time overheads. To address this, the taskstats code
125−accumulates each exiting task's statistics into a process-wide data structure.
126−When the last task of a process exits, the process level data accumulated also
127−gets sent to userspace (along with the per-task data).
128−
129−When a user queries to get per-tgid data, the sum of all other live threads in
130−the group is added up and added to the accumulated total for previously exited
131−threads of the same thread group.
132−
133−Extending taskstats
134−-------------------
135−
136−There are two ways to extend the taskstats interface to export more
137−per-task/process stats as patches to collect them get added to the kernel
138−in future:
139−
140−1. Adding more fields to the end of the existing struct taskstats. Backward
141− compatibility is ensured by the version number within the
142− structure. Userspace will use only the fields of the struct that correspond
143− to the version its using.
144−
145−2. Defining separate statistic structs and using the netlink attributes
146− interface to return them. Since userspace processes each netlink attribute
147− independently, it can always ignore attributes whose type it does not
148− understand (because it is using an older version of the interface).
149−
150−
151−Choosing between 1. and 2. is a matter of trading off flexibility and
152−overhead. If only a few fields need to be added, then 1. is the preferable
153−path since the kernel and userspace don't need to incur the overhead of
154−processing new netlink attributes. But if the new fields expand the existing
155−struct too much, requiring disparate userspace accounting utilities to
156−unnecessarily receive large structures whose fields are of no interest, then
157−extending the attributes structure would be worthwhile.
158−
159−Flow control for taskstats
160−--------------------------
161−
162−When the rate of task exits becomes large, a listener may not be able to keep
163−up with the kernel's rate of sending per-tid/tgid exit data leading to data
164−loss. This possibility gets compounded when the taskstats structure gets
165−extended and the number of cpus grows large.
166−
167−To avoid losing statistics, userspace should do one or more of the following:
168−
169−- increase the receive buffer sizes for the netlink sockets opened by
170−listeners to receive exit data.
171−
172−- create more listeners and reduce the number of cpus being listened to by
173−each listener. In the extreme case, there could be one listener for each cpu.
174−Users may also consider setting the cpu affinity of the listener to the subset
175−of cpus to which it listens, especially if they are listening to just one cpu.
176−
177−Despite these measures, if the userspace receives ENOBUFS error messages
178−indicated overflow of receive buffers, it should take measures to handle the
179−loss of data.
180−
181−----
Documentation/acpi/dsd/leds.txt+1−1
@@ -96,4 +96,4 @@ where · 95 unmodified lines
9696 <URL:http://www.uefi.org/sites/default/files/resources/_DSD-hierarchical-data-extension-UUID-v1.1.pdf>,
9797 referenced 2019-02-21.
9898
99−[7] Documentation/acpi/dsd/data-node-reference.txt
99+[7] Documentation/firmware-guide/acpi/dsd/data-node-references.rst
Documentation/admin-guide/LSM/LoadPin.rst+10−0
@@ -19,3 +19,13 @@ block device backing the filesystem is not read-only, a sysctl is · 18 unmodified lines
1919 created to toggle pinning: ``/proc/sys/kernel/loadpin/enabled``. (Having
2020 a mutable filesystem means pinning is mutable too, but having the
2121 sysctl allows for easy testing on systems with a mutable filesystem.)
22+
23+It's also possible to exclude specific file types from LoadPin using kernel
24+command line option "``loadpin.exclude``". By default, all files are
25+included, but they can be excluded using kernel command line option such
26+as "``loadpin.exclude=kernel-module,kexec-image``". This allows to use
27+different mechanisms such as ``CONFIG_MODULE_SIG`` and
28+``CONFIG_KEXEC_VERIFY_SIG`` to verify kernel module and kernel image while
29+still use LoadPin to protect the integrity of other files kernel loads. The
30+full list of valid file types can be found in ``kernel_read_file_str``
31+defined in ``include/linux/fs.h``.
Documentation/admin-guide/README.rst+1−1
@@ -227,7 +227,7 @@ Configuring the kernel · 226 unmodified lines
227227 "make tinyconfig" Configure the tiniest possible kernel.
228228
229229 You can find more information on using the Linux kernel config tools
230− in Documentation/kbuild/kconfig.txt.
230+ in Documentation/kbuild/kconfig.rst.
231231
232232 - NOTES on ``make config``:
233233
Documentation/admin-guide/aoe/aoe.rst+150−0
@@ -0,0 +1,150 @@
1+Introduction
2+============
3+
4+ATA over Ethernet is a network protocol that provides simple access to
5+block storage on the LAN.
6+
7+ http://support.coraid.com/documents/AoEr11.txt
8+
9+The EtherDrive (R) HOWTO for 2.6 and 3.x kernels is found at ...
10+
11+ http://support.coraid.com/support/linux/EtherDrive-2.6-HOWTO.html
12+
13+It has many tips and hints! Please see, especially, recommended
14+tunings for virtual memory:
15+
16+ http://support.coraid.com/support/linux/EtherDrive-2.6-HOWTO-5.html#ss5.19
17+
18+The aoetools are userland programs that are designed to work with this
19+driver. The aoetools are on sourceforge.
20+
21+ http://aoetools.sourceforge.net/
22+
23+The scripts in this Documentation/admin-guide/aoe directory are intended to
24+document the use of the driver and are not necessary if you install
25+the aoetools.
26+
27+
28+Creating Device Nodes
29+=====================
30+
31+ Users of udev should find the block device nodes created
32+ automatically, but to create all the necessary device nodes, use the
33+ udev configuration rules provided in udev.txt (in this directory).
34+
35+ There is a udev-install.sh script that shows how to install these
36+ rules on your system.
37+
38+ There is also an autoload script that shows how to edit
39+ /etc/modprobe.d/aoe.conf to ensure that the aoe module is loaded when
40+ necessary. Preloading the aoe module is preferable to autoloading,
41+ however, because AoE discovery takes a few seconds. It can be
42+ confusing when an AoE device is not present the first time the a
43+ command is run but appears a second later.
44+
45+Using Device Nodes
46+==================
47+
48+ "cat /dev/etherd/err" blocks, waiting for error diagnostic output,
49+ like any retransmitted packets.
50+
51+ "echo eth2 eth4 > /dev/etherd/interfaces" tells the aoe driver to
52+ limit ATA over Ethernet traffic to eth2 and eth4. AoE traffic from
53+ untrusted networks should be ignored as a matter of security. See
54+ also the aoe_iflist driver option described below.
55+
56+ "echo > /dev/etherd/discover" tells the driver to find out what AoE
57+ devices are available.
58+
59+ In the future these character devices may disappear and be replaced
60+ by sysfs counterparts. Using the commands in aoetools insulates
61+ users from these implementation details.
62+
63+ The block devices are named like this::
64+
65+ e{shelf}.{slot}
66+ e{shelf}.{slot}p{part}
67+
68+ ... so that "e0.2" is the third blade from the left (slot 2) in the
69+ first shelf (shelf address zero). That's the whole disk. The first
70+ partition on that disk would be "e0.2p1".
71+
72+Using sysfs
73+===========
74+
75+ Each aoe block device in /sys/block has the extra attributes of
76+ state, mac, and netif. The state attribute is "up" when the device
77+ is ready for I/O and "down" if detected but unusable. The
78+ "down,closewait" state shows that the device is still open and
79+ cannot come up again until it has been closed.
80+
81+ The mac attribute is the ethernet address of the remote AoE device.
82+ The netif attribute is the network interface on the localhost
83+ through which we are communicating with the remote AoE device.
84+
85+ There is a script in this directory that formats this information in
86+ a convenient way. Users with aoetools should use the aoe-stat
87+ command::
88+
89+ root@makki root# sh Documentation/admin-guide/aoe/status.sh
90+ e10.0 eth3 up
91+ e10.1 eth3 up
92+ e10.2 eth3 up
93+ e10.3 eth3 up
94+ e10.4 eth3 up
95+ e10.5 eth3 up
96+ e10.6 eth3 up
97+ e10.7 eth3 up
98+ e10.8 eth3 up
99+ e10.9 eth3 up
100+ e4.0 eth1 up
101+ e4.1 eth1 up
102+ e4.2 eth1 up
103+ e4.3 eth1 up
104+ e4.4 eth1 up
105+ e4.5 eth1 up
106+ e4.6 eth1 up
107+ e4.7 eth1 up
108+ e4.8 eth1 up
109+ e4.9 eth1 up
110+
111+ Use /sys/module/aoe/parameters/aoe_iflist (or better, the driver
112+ option discussed below) instead of /dev/etherd/interfaces to limit
113+ AoE traffic to the network interfaces in the given
114+ whitespace-separated list. Unlike the old character device, the
115+ sysfs entry can be read from as well as written to.
116+
117+ It's helpful to trigger discovery after setting the list of allowed
118+ interfaces. The aoetools package provides an aoe-discover script
119+ for this purpose. You can also directly use the
120+ /dev/etherd/discover special file described above.
121+
122+Driver Options
123+==============
124+
125+ There is a boot option for the built-in aoe driver and a
126+ corresponding module parameter, aoe_iflist. Without this option,
127+ all network interfaces may be used for ATA over Ethernet. Here is a
128+ usage example for the module parameter::
129+
130+ modprobe aoe_iflist="eth1 eth3"
131+
132+ The aoe_deadsecs module parameter determines the maximum number of
133+ seconds that the driver will wait for an AoE device to provide a
134+ response to an AoE command. After aoe_deadsecs seconds have
135+ elapsed, the AoE device will be marked as "down". A value of zero
136+ is supported for testing purposes and makes the aoe driver keep
137+ trying AoE commands forever.
138+
139+ The aoe_maxout module parameter has a default of 128. This is the
140+ maximum number of unresponded packets that will be sent to an AoE
141+ target at one time.
142+
143+ The aoe_dyndevs module parameter defaults to 1, meaning that the
144+ driver will assign a block device minor number to a discovered AoE
145+ target based on the order of its discovery. With dynamic minor
146+ device numbers in use, a greater range of AoE shelf and slot
147+ addresses can be supported. Users with udev will never have to
148+ think about minor numbers. Using aoe_dyndevs=0 allows device nodes
149+ to be pre-created using a static minor-number scheme with the
150+ aoe-mkshelf script in the aoetools.
Documentation/admin-guide/aoe/autoload.shrenamed from Documentation/aoe/autoload.sh+0−0

File renamed without changes.

Documentation/admin-guide/aoe/examples.rst+23−0
@@ -0,0 +1,23 @@
1+Example of udev rules
2+---------------------
3+
4+ .. include:: udev.txt
5+ :literal:
6+
7+Example of udev install rules script
8+------------------------------------
9+
10+ .. literalinclude:: udev-install.sh
11+ :language: shell
12+
13+Example script to get status
14+----------------------------
15+
16+ .. literalinclude:: status.sh
17+ :language: shell
18+
19+Example of AoE autoload script
20+------------------------------
21+
22+ .. literalinclude:: autoload.sh
23+ :language: shell
Documentation/admin-guide/aoe/index.rst+17−0
@@ -0,0 +1,17 @@
1+=======================
2+ATA over Ethernet (AoE)
3+=======================
4+
5+.. toctree::
6+ :maxdepth: 1
7+
8+ aoe
9+ todo
10+ examples
11+
12+.. only:: subproject and html
13+
14+ Indices
15+ =======
16+
17+ * :ref:`genindex`
Documentation/admin-guide/aoe/status.shrenamed from Documentation/aoe/status.sh+0−0

File renamed without changes.

Documentation/admin-guide/aoe/todo.rst+17−0
@@ -0,0 +1,17 @@
1+TODO
2+====
3+
4+There is a potential for deadlock when allocating a struct sk_buff for
5+data that needs to be written out to aoe storage. If the data is
6+being written from a dirty page in order to free that page, and if
7+there are no other pages available, then deadlock may occur when a
8+free page is needed for the sk_buff allocation. This situation has
9+not been observed, but it would be nice to eliminate any potential for
10+deadlock under memory pressure.
11+
12+Because ATA over Ethernet is not fragmented by the kernel's IP code,
13+the destructor member of the struct sk_buff is available to the aoe
14+driver. By using a mempool for allocating all but the first few
15+sk_buffs, and by registering a destructor, we should be able to
16+efficiently allocate sk_buffs without introducing any potential for
17+deadlock.
Documentation/admin-guide/aoe/udev-install.shrenamed from Documentation/aoe/udev-install.sh+0−0

File renamed without changes.

Documentation/admin-guide/aoe/udev.txtrenamed from Documentation/aoe/udev.txt+1−1
@@ -11,7 +11,7 @@ · 10 unmodified lines
1111 # udev_rules="/etc/udev/rules.d/"
1212 # bash# ls /etc/udev/rules.d/
1313 # 10-wacom.rules 50-udev.rules
14−# bash# cp /path/to/linux-2.6.xx/Documentation/aoe/udev.txt \
14+# bash# cp /path/to/linux/Documentation/admin-guide/aoe/udev.txt \
1515 # /etc/udev/rules.d/60-aoe.rules
1616 #
1717
Documentation/admin-guide/binderfs.rstrenamed from Documentation/filesystems/binderfs.rst+0−0

File renamed without changes.

Documentation/admin-guide/blockdev/drbd/DRBD-8.3-data-packets.svgrenamed from Documentation/blockdev/drbd/DRBD-8.3-data-packets.svg+0−0

File renamed without changes.

Documentation/admin-guide/blockdev/drbd/DRBD-data-packets.svgrenamed from Documentation/blockdev/drbd/DRBD-data-packets.svg+0−0

File renamed without changes.

Documentation/admin-guide/blockdev/drbd/conn-states-8.dotrenamed from Documentation/blockdev/drbd/conn-states-8.dot+0−0

File renamed without changes.

Documentation/admin-guide/blockdev/drbd/data-structure-v9.rst+42−0
@@ -0,0 +1,42 @@
1+================================
2+kernel data structure for DRBD-9
3+================================
4+
5+This describes the in kernel data structure for DRBD-9. Starting with
6+Linux v3.14 we are reorganizing DRBD to use this data structure.
7+
8+Basic Data Structure
9+====================
10+
11+A node has a number of DRBD resources. Each such resource has a number of
12+devices (aka volumes) and connections to other nodes ("peer nodes"). Each DRBD
13+device is represented by a block device locally.
14+
15+The DRBD objects are interconnected to form a matrix as depicted below; a
16+drbd_peer_device object sits at each intersection between a drbd_device and a
17+drbd_connection::
18+
19+ /--------------+---------------+.....+---------------\
20+ | resource | device | | device |
21+ +--------------+---------------+.....+---------------+
22+ | connection | peer_device | | peer_device |
23+ +--------------+---------------+.....+---------------+
24+ : : : : :
25+ : : : : :
26+ +--------------+---------------+.....+---------------+
27+ | connection | peer_device | | peer_device |
28+ \--------------+---------------+.....+---------------/
29+
30+In this table, horizontally, devices can be accessed from resources by their
31+volume number. Likewise, peer_devices can be accessed from connections by
32+their volume number. Objects in the vertical direction are connected by double
33+linked lists. There are back pointers from peer_devices to their connections a
34+devices, and from connections and devices to their resource.
35+
36+All resources are in the drbd_resources double-linked list. In addition, all
37+devices can be accessed by their minor device number via the drbd_devices idr.
38+
39+The drbd_resource, drbd_connection, and drbd_device objects are reference
40+counted. The peer_device objects only serve to establish the links between
41+devices and connections; their lifetime is determined by the lifetime of the
42+device and connection which they reference.
Documentation/admin-guide/blockdev/drbd/disk-states-8.dotrenamed from Documentation/blockdev/drbd/disk-states-8.dot+0−0

File renamed without changes.

Documentation/admin-guide/blockdev/drbd/drbd-connection-state-overview.dotrenamed from Documentation/blockdev/drbd/drbd-connection-state-overview.dot+0−0

File renamed without changes.

Documentation/admin-guide/blockdev/drbd/figures.rst+30−0
@@ -0,0 +1,30 @@
1+.. SPDX-License-Identifier: GPL-2.0
2+
3+.. The here included files are intended to help understand the implementation
4+
5+Data flows that Relate some functions, and write packets
6+========================================================
7+
8+.. kernel-figure:: DRBD-8.3-data-packets.svg
9+ :alt: DRBD-8.3-data-packets.svg
10+ :align: center
11+
12+.. kernel-figure:: DRBD-data-packets.svg
13+ :alt: DRBD-data-packets.svg
14+ :align: center
15+
16+
17+Sub graphs of DRBD's state transitions
18+======================================
19+
20+.. kernel-figure:: conn-states-8.dot
21+ :alt: conn-states-8.dot
22+ :align: center
23+
24+.. kernel-figure:: disk-states-8.dot
25+ :alt: disk-states-8.dot
26+ :align: center
27+
28+.. kernel-figure:: node-states-8.dot
29+ :alt: node-states-8.dot
30+ :align: center
Documentation/admin-guide/blockdev/drbd/index.rst+19−0
@@ -0,0 +1,19 @@
1+==========================================
2+Distributed Replicated Block Device - DRBD
3+==========================================
4+
5+Description
6+===========
7+
8+ DRBD is a shared-nothing, synchronously replicated block device. It
9+ is designed to serve as a building block for high availability
10+ clusters and in this context, is a "drop-in" replacement for shared
11+ storage. Simplistically, you could see it as a network RAID 1.
12+
13+ Please visit http://www.drbd.org to find out more.
14+
15+.. toctree::
16+ :maxdepth: 1
17+
18+ data-structure-v9
19+ figures
Documentation/admin-guide/blockdev/drbd/node-states-8.dotrenamed from Documentation/blockdev/drbd/node-states-8.dot+0−1
@@ -11,4 +11,3 @@ digraph peer_states { · 10 unmodified lines
1111 Unknown -> Primary [ label = "connected" ]
1212 Unknown -> Secondary [ label = "connected" ]
1313 }
14−
Documentation/admin-guide/blockdev/floppy.rst+255−0
@@ -0,0 +1,255 @@
1+=============
2+Floppy Driver
3+=============
4+
5+FAQ list:
6+=========
7+
8+A FAQ list may be found in the fdutils package (see below), and also
9+at <http://fdutils.linux.lu/faq.html>.
10+
11+
12+LILO configuration options (Thinkpad users, read this)
13+======================================================
14+
15+The floppy driver is configured using the 'floppy=' option in
16+lilo. This option can be typed at the boot prompt, or entered in the
17+lilo configuration file.
18+
19+Example: If your kernel is called linux-2.6.9, type the following line
20+at the lilo boot prompt (if you have a thinkpad)::
21+
22+ linux-2.6.9 floppy=thinkpad
23+
24+You may also enter the following line in /etc/lilo.conf, in the description
25+of linux-2.6.9::
26+
27+ append = "floppy=thinkpad"
28+
29+Several floppy related options may be given, example::
30+
31+ linux-2.6.9 floppy=daring floppy=two_fdc
32+ append = "floppy=daring floppy=two_fdc"
33+
34+If you give options both in the lilo config file and on the boot
35+prompt, the option strings of both places are concatenated, the boot
36+prompt options coming last. That's why there are also options to
37+restore the default behavior.
38+
39+
40+Module configuration options
41+============================
42+
43+If you use the floppy driver as a module, use the following syntax::
44+
45+ modprobe floppy floppy="<options>"
46+
47+Example::
48+
49+ modprobe floppy floppy="omnibook messages"
50+
51+If you need certain options enabled every time you load the floppy driver,
52+you can put::
53+
54+ options floppy floppy="omnibook messages"
55+
56+in a configuration file in /etc/modprobe.d/.
57+
58+
59+The floppy driver related options are:
60+
61+ floppy=asus_pci
62+ Sets the bit mask to allow only units 0 and 1. (default)
63+
64+ floppy=daring
65+ Tells the floppy driver that you have a well behaved floppy controller.
66+ This allows more efficient and smoother operation, but may fail on
67+ certain controllers. This may speed up certain operations.
68+
69+ floppy=0,daring
70+ Tells the floppy driver that your floppy controller should be used
71+ with caution.
72+
73+ floppy=one_fdc
74+ Tells the floppy driver that you have only one floppy controller.
75+ (default)
76+
77+ floppy=two_fdc / floppy=<address>,two_fdc
78+ Tells the floppy driver that you have two floppy controllers.
79+ The second floppy controller is assumed to be at <address>.
80+ This option is not needed if the second controller is at address
81+ 0x370, and if you use the 'cmos' option.
82+
83+ floppy=thinkpad
84+ Tells the floppy driver that you have a Thinkpad. Thinkpads use an
85+ inverted convention for the disk change line.
86+
87+ floppy=0,thinkpad
88+ Tells the floppy driver that you don't have a Thinkpad.
89+
90+ floppy=omnibook / floppy=nodma
91+ Tells the floppy driver not to use Dma for data transfers.
92+ This is needed on HP Omnibooks, which don't have a workable
93+ DMA channel for the floppy driver. This option is also useful
94+ if you frequently get "Unable to allocate DMA memory" messages.
95+ Indeed, dma memory needs to be continuous in physical memory,
96+ and is thus harder to find, whereas non-dma buffers may be
97+ allocated in virtual memory. However, I advise against this if
98+ you have an FDC without a FIFO (8272A or 82072). 82072A and
99+ later are OK. You also need at least a 486 to use nodma.
100+ If you use nodma mode, I suggest you also set the FIFO
101+ threshold to 10 or lower, in order to limit the number of data
102+ transfer interrupts.
103+
104+ If you have a FIFO-able FDC, the floppy driver automatically
105+ falls back on non DMA mode if no DMA-able memory can be found.
106+ If you want to avoid this, explicitly ask for 'yesdma'.
107+
108+ floppy=yesdma
109+ Tells the floppy driver that a workable DMA channel is available.
110+ (default)
111+
112+ floppy=nofifo
113+ Disables the FIFO entirely. This is needed if you get "Bus
114+ master arbitration error" messages from your Ethernet card (or
115+ from other devices) while accessing the floppy.
116+
117+ floppy=usefifo
118+ Enables the FIFO. (default)
119+
120+ floppy=<threshold>,fifo_depth
121+ Sets the FIFO threshold. This is mostly relevant in DMA
122+ mode. If this is higher, the floppy driver tolerates more
123+ interrupt latency, but it triggers more interrupts (i.e. it
124+ imposes more load on the rest of the system). If this is
125+ lower, the interrupt latency should be lower too (faster
126+ processor). The benefit of a lower threshold is less
127+ interrupts.
128+
129+ To tune the fifo threshold, switch on over/underrun messages
130+ using 'floppycontrol --messages'. Then access a floppy
131+ disk. If you get a huge amount of "Over/Underrun - retrying"
132+ messages, then the fifo threshold is too low. Try with a
133+ higher value, until you only get an occasional Over/Underrun.
134+ It is a good idea to compile the floppy driver as a module
135+ when doing this tuning. Indeed, it allows to try different
136+ fifo values without rebooting the machine for each test. Note
137+ that you need to do 'floppycontrol --messages' every time you
138+ re-insert the module.
139+
140+ Usually, tuning the fifo threshold should not be needed, as
141+ the default (0xa) is reasonable.
142+
143+ floppy=<drive>,<type>,cmos
144+ Sets the CMOS type of <drive> to <type>. This is mandatory if
145+ you have more than two floppy drives (only two can be
146+ described in the physical CMOS), or if your BIOS uses
147+ non-standard CMOS types. The CMOS types are:
148+
149+ == ==================================
150+ 0 Use the value of the physical CMOS
151+ 1 5 1/4 DD
152+ 2 5 1/4 HD
153+ 3 3 1/2 DD
154+ 4 3 1/2 HD
155+ 5 3 1/2 ED
156+ 6 3 1/2 ED
157+ 16 unknown or not installed
158+ == ==================================
159+
160+ (Note: there are two valid types for ED drives. This is because 5 was
161+ initially chosen to represent floppy *tapes*, and 6 for ED drives.
162+ AMI ignored this, and used 5 for ED drives. That's why the floppy
163+ driver handles both.)
164+
165+ floppy=unexpected_interrupts
166+ Print a warning message when an unexpected interrupt is received.
167+ (default)
168+
169+ floppy=no_unexpected_interrupts / floppy=L40SX
170+ Don't print a message when an unexpected interrupt is received. This
171+ is needed on IBM L40SX laptops in certain video modes. (There seems
172+ to be an interaction between video and floppy. The unexpected
173+ interrupts affect only performance, and can be safely ignored.)
174+
175+ floppy=broken_dcl
176+ Don't use the disk change line, but assume that the disk was
177+ changed whenever the device node is reopened. Needed on some
178+ boxes where the disk change line is broken or unsupported.
179+ This should be regarded as a stopgap measure, indeed it makes
180+ floppy operation less efficient due to unneeded cache
181+ flushings, and slightly more unreliable. Please verify your
182+ cable, connection and jumper settings if you have any DCL
183+ problems. However, some older drives, and also some laptops
184+ are known not to have a DCL.
185+
186+ floppy=debug
187+ Print debugging messages.
188+
189+ floppy=messages
190+ Print informational messages for some operations (disk change
191+ notifications, warnings about over and underruns, and about
192+ autodetection).
193+
194+ floppy=silent_dcl_clear
195+ Uses a less noisy way to clear the disk change line (which
196+ doesn't involve seeks). Implied by 'daring' option.
197+
198+ floppy=<nr>,irq
199+ Sets the floppy IRQ to <nr> instead of 6.
200+
201+ floppy=<nr>,dma
202+ Sets the floppy DMA channel to <nr> instead of 2.
203+
204+ floppy=slow
205+ Use PS/2 stepping rate::
206+
207+ PS/2 floppies have much slower step rates than regular floppies.
208+ It's been recommended that take about 1/4 of the default speed
209+ in some more extreme cases.
210+
211+
212+Supporting utilities and additional documentation:
213+==================================================
214+
215+Additional parameters of the floppy driver can be configured at
216+runtime. Utilities which do this can be found in the fdutils package.
217+This package also contains a new version of mtools which allows to
218+access high capacity disks (up to 1992K on a high density 3 1/2 disk!).
219+It also contains additional documentation about the floppy driver.
220+
221+The latest version can be found at fdutils homepage:
222+
223+ http://fdutils.linux.lu
224+
225+The fdutils releases can be found at:
226+
227+ http://fdutils.linux.lu/download.html
228+
229+ http://www.tux.org/pub/knaff/fdutils/
230+
231+ ftp://metalab.unc.edu/pub/Linux/utils/disk-management/
232+
233+Reporting problems about the floppy driver
234+==========================================
235+
236+If you have a question or a bug report about the floppy driver, mail
237+me at Alain.Knaff@poboxes.com . If you post to Usenet, preferably use
238+comp.os.linux.hardware. As the volume in these groups is rather high,
239+be sure to include the word "floppy" (or "FLOPPY") in the subject
240+line. If the reported problem happens when mounting floppy disks, be
241+sure to mention also the type of the filesystem in the subject line.
242+
243+Be sure to read the FAQ before mailing/posting any bug reports!
244+
245+Alain
246+
247+Changelog
248+=========
249+
250+10-30-2004 :
251+ Cleanup, updating, add reference to module configuration.
252+ James Nelson <james4765@gmail.com>
253+
254+6-3-2000 :
255+ Original Document
Documentation/admin-guide/blockdev/index.rst+16−0
@@ -0,0 +1,16 @@
1+.. SPDX-License-Identifier: GPL-2.0
2+
3+===========================
4+The Linux RapidIO Subsystem
5+===========================
6+
7+.. toctree::
8+ :maxdepth: 1
9+
10+ floppy
11+ nbd
12+ paride
13+ ramdisk
14+ zram
15+
16+ drbd/index
Documentation/admin-guide/blockdev/nbd.rst+31−0
@@ -0,0 +1,31 @@
1+==================================
2+Network Block Device (TCP version)
3+==================================
4+
5+1) Overview
6+-----------
7+
8+What is it: With this compiled in the kernel (or as a module), Linux
9+can use a remote server as one of its block devices. So every time
10+the client computer wants to read, e.g., /dev/nb0, it sends a
11+request over TCP to the server, which will reply with the data read.
12+This can be used for stations with low disk space (or even diskless)
13+to borrow disk space from another computer.
14+Unlike NFS, it is possible to put any filesystem on it, etc.
15+
16+For more information, or to download the nbd-client and nbd-server
17+tools, go to http://nbd.sf.net/.
18+
19+The nbd kernel module need only be installed on the client
20+system, as the nbd-server is completely in userspace. In fact,
21+the nbd-server has been successfully ported to other operating
22+systems, including Windows.
23+
24+A) NBD parameters
25+-----------------
26+
27+max_part
28+ Number of partitions per device (default: 0).
29+
30+nbds_max
31+ Number of block devices that should be initialized (default: 16).
Documentation/admin-guide/blockdev/paride.rst+439−0
@@ -0,0 +1,439 @@
1+===================================
2+Linux and parallel port IDE devices
3+===================================
4+
5+PARIDE v1.03 (c) 1997-8 Grant Guenther <grant@torque.net>
6+
7+1. Introduction
8+===============
9+
10+Owing to the simplicity and near universality of the parallel port interface
11+to personal computers, many external devices such as portable hard-disk,
12+CD-ROM, LS-120 and tape drives use the parallel port to connect to their
13+host computer. While some devices (notably scanners) use ad-hoc methods
14+to pass commands and data through the parallel port interface, most
15+external devices are actually identical to an internal model, but with
16+a parallel-port adapter chip added in. Some of the original parallel port
17+adapters were little more than mechanisms for multiplexing a SCSI bus.
18+(The Iomega PPA-3 adapter used in the ZIP drives is an example of this
19+approach). Most current designs, however, take a different approach.
20+The adapter chip reproduces a small ISA or IDE bus in the external device
21+and the communication protocol provides operations for reading and writing
22+device registers, as well as data block transfer functions. Sometimes,
23+the device being addressed via the parallel cable is a standard SCSI
24+controller like an NCR 5380. The "ditto" family of external tape
25+drives use the ISA replicator to interface a floppy disk controller,
26+which is then connected to a floppy-tape mechanism. The vast majority
27+of external parallel port devices, however, are now based on standard
28+IDE type devices, which require no intermediate controller. If one
29+were to open up a parallel port CD-ROM drive, for instance, one would
30+find a standard ATAPI CD-ROM drive, a power supply, and a single adapter
31+that interconnected a standard PC parallel port cable and a standard
32+IDE cable. It is usually possible to exchange the CD-ROM device with
33+any other device using the IDE interface.
34+
35+The document describes the support in Linux for parallel port IDE
36+devices. It does not cover parallel port SCSI devices, "ditto" tape
37+drives or scanners. Many different devices are supported by the
38+parallel port IDE subsystem, including:
39+
40+ - MicroSolutions backpack CD-ROM
41+ - MicroSolutions backpack PD/CD
42+ - MicroSolutions backpack hard-drives
43+ - MicroSolutions backpack 8000t tape drive
44+ - SyQuest EZ-135, EZ-230 & SparQ drives
45+ - Avatar Shark
46+ - Imation Superdisk LS-120
47+ - Maxell Superdisk LS-120
48+ - FreeCom Power CD
49+ - Hewlett-Packard 5GB and 8GB tape drives
50+ - Hewlett-Packard 7100 and 7200 CD-RW drives
51+
52+as well as most of the clone and no-name products on the market.
53+
54+To support such a wide range of devices, PARIDE, the parallel port IDE
55+subsystem, is actually structured in three parts. There is a base
56+paride module which provides a registry and some common methods for
57+accessing the parallel ports. The second component is a set of
58+high-level drivers for each of the different types of supported devices:
59+
60+ === =============
61+ pd IDE disk
62+ pcd ATAPI CD-ROM
63+ pf ATAPI disk
64+ pt ATAPI tape
65+ pg ATAPI generic
66+ === =============
67+
68+(Currently, the pg driver is only used with CD-R drives).
69+
70+The high-level drivers function according to the relevant standards.
71+The third component of PARIDE is a set of low-level protocol drivers
72+for each of the parallel port IDE adapter chips. Thanks to the interest
73+and encouragement of Linux users from many parts of the world,
74+support is available for almost all known adapter protocols:
75+
76+ ==== ====================================== ====
77+ aten ATEN EH-100 (HK)
78+ bpck Microsolutions backpack (US)
79+ comm DataStor (old-type) "commuter" adapter (TW)
80+ dstr DataStor EP-2000 (TW)
81+ epat Shuttle EPAT (UK)
82+ epia Shuttle EPIA (UK)
83+ fit2 FIT TD-2000 (US)
84+ fit3 FIT TD-3000 (US)
85+ friq Freecom IQ cable (DE)
86+ frpw Freecom Power (DE)
87+ kbic KingByte KBIC-951A and KBIC-971A (TW)
88+ ktti KT Technology PHd adapter (SG)
89+ on20 OnSpec 90c20 (US)
90+ on26 OnSpec 90c26 (US)
91+ ==== ====================================== ====
92+
93+
94+2. Using the PARIDE subsystem
95+=============================
96+
97+While configuring the Linux kernel, you may choose either to build
98+the PARIDE drivers into your kernel, or to build them as modules.
99+
100+In either case, you will need to select "Parallel port IDE device support"
101+as well as at least one of the high-level drivers and at least one
102+of the parallel port communication protocols. If you do not know
103+what kind of parallel port adapter is used in your drive, you could
104+begin by checking the file names and any text files on your DOS
105+installation floppy. Alternatively, you can look at the markings on
106+the adapter chip itself. That's usually sufficient to identify the
107+correct device.
108+
109+You can actually select all the protocol modules, and allow the PARIDE
110+subsystem to try them all for you.
111+
112+For the "brand-name" products listed above, here are the protocol
113+and high-level drivers that you would use:
114+
115+ ================ ============ ====== ========
116+ Manufacturer Model Driver Protocol
117+ ================ ============ ====== ========
118+ MicroSolutions CD-ROM pcd bpck
119+ MicroSolutions PD drive pf bpck
120+ MicroSolutions hard-drive pd bpck
121+ MicroSolutions 8000t tape pt bpck
122+ SyQuest EZ, SparQ pd epat
123+ Imation Superdisk pf epat
124+ Maxell Superdisk pf friq
125+ Avatar Shark pd epat
126+ FreeCom CD-ROM pcd frpw
127+ Hewlett-Packard 5GB Tape pt epat
128+ Hewlett-Packard 7200e (CD) pcd epat
129+ Hewlett-Packard 7200e (CD-R) pg epat
130+ ================ ============ ====== ========
131+
132+2.1 Configuring built-in drivers
133+---------------------------------
134+
135+We recommend that you get to know how the drivers work and how to
136+configure them as loadable modules, before attempting to compile a
137+kernel with the drivers built-in.
138+
139+If you built all of your PARIDE support directly into your kernel,
140+and you have just a single parallel port IDE device, your kernel should
141+locate it automatically for you. If you have more than one device,
142+you may need to give some command line options to your bootloader
143+(eg: LILO), how to do that is beyond the scope of this document.
144+
145+The high-level drivers accept a number of command line parameters, all
146+of which are documented in the source files in linux/drivers/block/paride.
147+By default, each driver will automatically try all parallel ports it
148+can find, and all protocol types that have been installed, until it finds
149+a parallel port IDE adapter. Once it finds one, the probe stops. So,
150+if you have more than one device, you will need to tell the drivers
151+how to identify them. This requires specifying the port address, the
152+protocol identification number and, for some devices, the drive's
153+chain ID. While your system is booting, a number of messages are
154+displayed on the console. Like all such messages, they can be
155+reviewed with the 'dmesg' command. Among those messages will be
156+some lines like::
157+
158+ paride: bpck registered as protocol 0
159+ paride: epat registered as protocol 1
160+
161+The numbers will always be the same until you build a new kernel with
162+different protocol selections. You should note these numbers as you
163+will need them to identify the devices.
164+
165+If you happen to be using a MicroSolutions backpack device, you will
166+also need to know the unit ID number for each drive. This is usually
167+the last two digits of the drive's serial number (but read MicroSolutions'
168+documentation about this).
169+
170+As an example, let's assume that you have a MicroSolutions PD/CD drive
171+with unit ID number 36 connected to the parallel port at 0x378, a SyQuest
172+EZ-135 connected to the chained port on the PD/CD drive and also an
173+Imation Superdisk connected to port 0x278. You could give the following
174+options on your boot command::
175+
176+ pd.drive0=0x378,1 pf.drive0=0x278,1 pf.drive1=0x378,0,36
177+
178+In the last option, pf.drive1 configures device /dev/pf1, the 0x378
179+is the parallel port base address, the 0 is the protocol registration
180+number and 36 is the chain ID.
181+
182+Please note: while PARIDE will work both with and without the
183+PARPORT parallel port sharing system that is included by the
184+"Parallel port support" option, PARPORT must be included and enabled
185+if you want to use chains of devices on the same parallel port.
186+
187+2.2 Loading and configuring PARIDE as modules
188+----------------------------------------------
189+
190+It is much faster and simpler to get to understand the PARIDE drivers
191+if you use them as loadable kernel modules.
192+
193+Note 1:
194+ using these drivers with the "kerneld" automatic module loading
195+ system is not recommended for beginners, and is not documented here.
196+
197+Note 2:
198+ if you build PARPORT support as a loadable module, PARIDE must
199+ also be built as loadable modules, and PARPORT must be loaded before
200+ the PARIDE modules.
201+
202+To use PARIDE, you must begin by::
203+
204+ insmod paride
205+
206+this loads a base module which provides a registry for the protocols,
207+among other tasks.
208+
209+Then, load as many of the protocol modules as you think you might need.
210+As you load each module, it will register the protocols that it supports,
211+and print a log message to your kernel log file and your console. For
212+example::
213+
214+ # insmod epat
215+ paride: epat registered as protocol 0
216+ # insmod kbic
217+ paride: k951 registered as protocol 1
218+ paride: k971 registered as protocol 2
219+
220+Finally, you can load high-level drivers for each kind of device that
221+you have connected. By default, each driver will autoprobe for a single
222+device, but you can support up to four similar devices by giving their
223+individual co-ordinates when you load the driver.
224+
225+For example, if you had two no-name CD-ROM drives both using the
226+KingByte KBIC-951A adapter, one on port 0x378 and the other on 0x3bc
227+you could give the following command::
228+
229+ # insmod pcd drive0=0x378,1 drive1=0x3bc,1
230+
231+For most adapters, giving a port address and protocol number is sufficient,
232+but check the source files in linux/drivers/block/paride for more
233+information. (Hopefully someone will write some man pages one day !).
234+
235+As another example, here's what happens when PARPORT is installed, and
236+a SyQuest EZ-135 is attached to port 0x378::
237+
238+ # insmod paride
239+ paride: version 1.0 installed
240+ # insmod epat
241+ paride: epat registered as protocol 0
242+ # insmod pd
243+ pd: pd version 1.0, major 45, cluster 64, nice 0
244+ pda: Sharing parport1 at 0x378
245+ pda: epat 1.0, Shuttle EPAT chip c3 at 0x378, mode 5 (EPP-32), delay 1
246+ pda: SyQuest EZ135A, 262144 blocks [128M], (512/16/32), removable media
247+ pda: pda1
248+
249+Note that the last line is the output from the generic partition table
250+scanner - in this case it reports that it has found a disk with one partition.
251+
252+2.3 Using a PARIDE device
253+--------------------------
254+
255+Once the drivers have been loaded, you can access PARIDE devices in the
256+same way as their traditional counterparts. You will probably need to
257+create the device "special files". Here is a simple script that you can
258+cut to a file and execute::
259+
260+ #!/bin/bash
261+ #
262+ # mkd -- a script to create the device special files for the PARIDE subsystem
263+ #
264+ function mkdev {
265+ mknod $1 $2 $3 $4 ; chmod 0660 $1 ; chown root:disk $1
266+ }
267+ #
268+ function pd {
269+ D=$( printf \\$( printf "x%03x" $[ $1 + 97 ] ) )
270+ mkdev pd$D b 45 $[ $1 * 16 ]
271+ for P in 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15
272+ do mkdev pd$D$P b 45 $[ $1 * 16 + $P ]
273+ done
274+ }
275+ #
276+ cd /dev
277+ #
278+ for u in 0 1 2 3 ; do pd $u ; done
279+ for u in 0 1 2 3 ; do mkdev pcd$u b 46 $u ; done
280+ for u in 0 1 2 3 ; do mkdev pf$u b 47 $u ; done
281+ for u in 0 1 2 3 ; do mkdev pt$u c 96 $u ; done
282+ for u in 0 1 2 3 ; do mkdev npt$u c 96 $[ $u + 128 ] ; done
283+ for u in 0 1 2 3 ; do mkdev pg$u c 97 $u ; done
284+ #
285+ # end of mkd
286+
287+With the device files and drivers in place, you can access PARIDE devices
288+like any other Linux device. For example, to mount a CD-ROM in pcd0, use::
289+
290+ mount /dev/pcd0 /cdrom
291+
292+If you have a fresh Avatar Shark cartridge, and the drive is pda, you
293+might do something like::
294+
295+ fdisk /dev/pda -- make a new partition table with
296+ partition 1 of type 83
297+
298+ mke2fs /dev/pda1 -- to build the file system
299+
300+ mkdir /shark -- make a place to mount the disk
301+
302+ mount /dev/pda1 /shark
303+
304+Devices like the Imation superdisk work in the same way, except that
305+they do not have a partition table. For example to make a 120MB
306+floppy that you could share with a DOS system::
307+
308+ mkdosfs /dev/pf0
309+ mount /dev/pf0 /mnt
310+
311+
312+2.4 The pf driver
313+------------------
314+
315+The pf driver is intended for use with parallel port ATAPI disk
316+devices. The most common devices in this category are PD drives
317+and LS-120 drives. Traditionally, media for these devices are not
318+partitioned. Consequently, the pf driver does not support partitioned
319+media. This may be changed in a future version of the driver.
320+
321+2.5 Using the pt driver
322+------------------------
323+
324+The pt driver for parallel port ATAPI tape drives is a minimal driver.
325+It does not yet support many of the standard tape ioctl operations.
326+For best performance, a block size of 32KB should be used. You will
327+probably want to set the parallel port delay to 0, if you can.
328+
329+2.6 Using the pg driver
330+------------------------
331+
332+The pg driver can be used in conjunction with the cdrecord program
333+to create CD-ROMs. Please get cdrecord version 1.6.1 or later
334+from ftp://ftp.fokus.gmd.de/pub/unix/cdrecord/ . To record CD-R media
335+your parallel port should ideally be set to EPP mode, and the "port delay"
336+should be set to 0. With those settings it is possible to record at 2x
337+speed without any buffer underruns. If you cannot get the driver to work
338+in EPP mode, try to use "bidirectional" or "PS/2" mode and 1x speeds only.
339+
340+
341+3. Troubleshooting
342+==================
343+
344+3.1 Use EPP mode if you can
345+----------------------------
346+
347+The most common problems that people report with the PARIDE drivers
348+concern the parallel port CMOS settings. At this time, none of the
349+PARIDE protocol modules support ECP mode, or any ECP combination modes.
350+If you are able to do so, please set your parallel port into EPP mode
351+using your CMOS setup procedure.
352+
353+3.2 Check the port delay
354+-------------------------
355+
356+Some parallel ports cannot reliably transfer data at full speed. To
357+offset the errors, the PARIDE protocol modules introduce a "port
358+delay" between each access to the i/o ports. Each protocol sets
359+a default value for this delay. In most cases, the user can override
360+the default and set it to 0 - resulting in somewhat higher transfer
361+rates. In some rare cases (especially with older 486 systems) the
362+default delays are not long enough. if you experience corrupt data
363+transfers, or unexpected failures, you may wish to increase the
364+port delay. The delay can be programmed using the "driveN" parameters
365+to each of the high-level drivers. Please see the notes above, or
366+read the comments at the beginning of the driver source files in
367+linux/drivers/block/paride.
368+
369+3.3 Some drives need a printer reset
370+-------------------------------------
371+
372+There appear to be a number of "noname" external drives on the market
373+that do not always power up correctly. We have noticed this with some
374+drives based on OnSpec and older Freecom adapters. In these rare cases,
375+the adapter can often be reinitialised by issuing a "printer reset" on
376+the parallel port. As the reset operation is potentially disruptive in
377+multiple device environments, the PARIDE drivers will not do it
378+automatically. You can however, force a printer reset by doing::
379+
380+ insmod lp reset=1
381+ rmmod lp
382+
383+If you have one of these marginal cases, you should probably build
384+your paride drivers as modules, and arrange to do the printer reset
385+before loading the PARIDE drivers.
386+
387+3.4 Use the verbose option and dmesg if you need help
388+------------------------------------------------------
389+
390+While a lot of testing has gone into these drivers to make them work
391+as smoothly as possible, problems will arise. If you do have problems,
392+please check all the obvious things first: does the drive work in
393+DOS with the manufacturer's drivers ? If that doesn't yield any useful
394+clues, then please make sure that only one drive is hooked to your system,
395+and that either (a) PARPORT is enabled or (b) no other device driver
396+is using your parallel port (check in /proc/ioports). Then, load the
397+appropriate drivers (you can load several protocol modules if you want)
398+as in::
399+
400+ # insmod paride
401+ # insmod epat
402+ # insmod bpck
403+ # insmod kbic
404+ ...
405+ # insmod pd verbose=1
406+
407+(using the correct driver for the type of device you have, of course).
408+The verbose=1 parameter will cause the drivers to log a trace of their
409+activity as they attempt to locate your drive.
410+
411+Use 'dmesg' to capture a log of all the PARIDE messages (any messages
412+beginning with paride:, a protocol module's name or a driver's name) and
413+include that with your bug report. You can submit a bug report in one
414+of two ways. Either send it directly to the author of the PARIDE suite,
415+by e-mail to grant@torque.net, or join the linux-parport mailing list
416+and post your report there.
417+
418+3.5 For more information or help
419+---------------------------------
420+
421+You can join the linux-parport mailing list by sending a mail message
422+to:
423+
424+ linux-parport-request@torque.net
425+
426+with the single word::
427+
428+ subscribe
429+
430+in the body of the mail message (not in the subject line). Please be
431+sure that your mail program is correctly set up when you do this, as
432+the list manager is a robot that will subscribe you using the reply
433+address in your mail headers. REMOVE any anti-spam gimmicks you may
434+have in your mail headers, when sending mail to the list server.
435+
436+You might also find some useful information on the linux-parport
437+web pages (although they are not always up to date) at
438+
439+ http://web.archive.org/web/%2E/http://www.torque.net/parport/
Documentation/admin-guide/blockdev/ramdisk.rst+177−0
@@ -0,0 +1,177 @@
1+==========================================
2+Using the RAM disk block device with Linux
3+==========================================
4+
5+.. Contents:
6+
7+ 1) Overview
8+ 2) Kernel Command Line Parameters
9+ 3) Using "rdev -r"
10+ 4) An Example of Creating a Compressed RAM Disk
11+
12+
13+1) Overview
14+-----------
15+
16+The RAM disk driver is a way to use main system memory as a block device. It
17+is required for initrd, an initial filesystem used if you need to load modules
18+in order to access the root filesystem (see Documentation/admin-guide/initrd.rst). It can
19+also be used for a temporary filesystem for crypto work, since the contents
20+are erased on reboot.
21+
22+The RAM disk dynamically grows as more space is required. It does this by using
23+RAM from the buffer cache. The driver marks the buffers it is using as dirty
24+so that the VM subsystem does not try to reclaim them later.
25+
26+The RAM disk supports up to 16 RAM disks by default, and can be reconfigured
27+to support an unlimited number of RAM disks (at your own risk). Just change
28+the configuration symbol BLK_DEV_RAM_COUNT in the Block drivers config menu
29+and (re)build the kernel.
30+
31+To use RAM disk support with your system, run './MAKEDEV ram' from the /dev
32+directory. RAM disks are all major number 1, and start with minor number 0
33+for /dev/ram0, etc. If used, modern kernels use /dev/ram0 for an initrd.
34+
35+The new RAM disk also has the ability to load compressed RAM disk images,
36+allowing one to squeeze more programs onto an average installation or
37+rescue floppy disk.
38+
39+
40+2) Parameters
41+---------------------------------
42+
43+2a) Kernel Command Line Parameters
44+
45+ ramdisk_size=N
46+ Size of the ramdisk.
47+
48+This parameter tells the RAM disk driver to set up RAM disks of N k size. The
49+default is 4096 (4 MB).
50+
51+2b) Module parameters
52+
53+ rd_nr
54+ /dev/ramX devices created.
55+
56+ max_part
57+ Maximum partition number.
58+
59+ rd_size
60+ See ramdisk_size.
61+
62+3) Using "rdev -r"
63+------------------
64+
65+The usage of the word (two bytes) that "rdev -r" sets in the kernel image is
66+as follows. The low 11 bits (0 -> 10) specify an offset (in 1 k blocks) of up
67+to 2 MB (2^11) of where to find the RAM disk (this used to be the size). Bit
68+14 indicates that a RAM disk is to be loaded, and bit 15 indicates whether a
69+prompt/wait sequence is to be given before trying to read the RAM disk. Since
70+the RAM disk dynamically grows as data is being written into it, a size field
71+is not required. Bits 11 to 13 are not currently used and may as well be zero.
72+These numbers are no magical secrets, as seen below::
73+
74+ ./arch/x86/kernel/setup.c:#define RAMDISK_IMAGE_START_MASK 0x07FF
75+ ./arch/x86/kernel/setup.c:#define RAMDISK_PROMPT_FLAG 0x8000
76+ ./arch/x86/kernel/setup.c:#define RAMDISK_LOAD_FLAG 0x4000
77+
78+Consider a typical two floppy disk setup, where you will have the
79+kernel on disk one, and have already put a RAM disk image onto disk #2.
80+
81+Hence you want to set bits 0 to 13 as 0, meaning that your RAM disk
82+starts at an offset of 0 kB from the beginning of the floppy.
83+The command line equivalent is: "ramdisk_start=0"
84+
85+You want bit 14 as one, indicating that a RAM disk is to be loaded.
86+The command line equivalent is: "load_ramdisk=1"
87+
88+You want bit 15 as one, indicating that you want a prompt/keypress
89+sequence so that you have a chance to switch floppy disks.
90+The command line equivalent is: "prompt_ramdisk=1"
91+
92+Putting that together gives 2^15 + 2^14 + 0 = 49152 for an rdev word.
93+So to create disk one of the set, you would do::
94+
95+ /usr/src/linux# cat arch/x86/boot/zImage > /dev/fd0
96+ /usr/src/linux# rdev /dev/fd0 /dev/fd0
97+ /usr/src/linux# rdev -r /dev/fd0 49152
98+
99+If you make a boot disk that has LILO, then for the above, you would use::
100+
101+ append = "ramdisk_start=0 load_ramdisk=1 prompt_ramdisk=1"
102+
103+Since the default start = 0 and the default prompt = 1, you could use::
104+
105+ append = "load_ramdisk=1"
106+
107+
108+4) An Example of Creating a Compressed RAM Disk
109+-----------------------------------------------
110+
111+To create a RAM disk image, you will need a spare block device to
112+construct it on. This can be the RAM disk device itself, or an
113+unused disk partition (such as an unmounted swap partition). For this
114+example, we will use the RAM disk device, "/dev/ram0".
115+
116+Note: This technique should not be done on a machine with less than 8 MB
117+of RAM. If using a spare disk partition instead of /dev/ram0, then this
118+restriction does not apply.
119+
120+a) Decide on the RAM disk size that you want. Say 2 MB for this example.
121+ Create it by writing to the RAM disk device. (This step is not currently
122+ required, but may be in the future.) It is wise to zero out the
123+ area (esp. for disks) so that maximal compression is achieved for
124+ the unused blocks of the image that you are about to create::
125+
126+ dd if=/dev/zero of=/dev/ram0 bs=1k count=2048
127+
128+b) Make a filesystem on it. Say ext2fs for this example::
129+
130+ mke2fs -vm0 /dev/ram0 2048
131+
132+c) Mount it, copy the files you want to it (eg: /etc/* /dev/* ...)
133+ and unmount it again.
134+
135+d) Compress the contents of the RAM disk. The level of compression
136+ will be approximately 50% of the space used by the files. Unused
137+ space on the RAM disk will compress to almost nothing::
138+
139+ dd if=/dev/ram0 bs=1k count=2048 | gzip -v9 > /tmp/ram_image.gz
140+
141+e) Put the kernel onto the floppy::
142+
143+ dd if=zImage of=/dev/fd0 bs=1k
144+
145+f) Put the RAM disk image onto the floppy, after the kernel. Use an offset
146+ that is slightly larger than the kernel, so that you can put another
147+ (possibly larger) kernel onto the same floppy later without overlapping
148+ the RAM disk image. An offset of 400 kB for kernels about 350 kB in
149+ size would be reasonable. Make sure offset+size of ram_image.gz is
150+ not larger than the total space on your floppy (usually 1440 kB)::
151+
152+ dd if=/tmp/ram_image.gz of=/dev/fd0 bs=1k seek=400
153+
154+g) Use "rdev" to set the boot device, RAM disk offset, prompt flag, etc.
155+ For prompt_ramdisk=1, load_ramdisk=1, ramdisk_start=400, one would
156+ have 2^15 + 2^14 + 400 = 49552::
157+
158+ rdev /dev/fd0 /dev/fd0
159+ rdev -r /dev/fd0 49552
160+
161+That is it. You now have your boot/root compressed RAM disk floppy. Some
162+users may wish to combine steps (d) and (f) by using a pipe.
163+
164+
165+ Paul Gortmaker 12/95
166+
167+Changelog:
168+----------
169+
170+10-22-04 :
171+ Updated to reflect changes in command line options, remove
172+ obsolete references, general cleanup.
173+ James Nelson (james4765@gmail.com)
174+
175+
176+12-95 :
177+ Original Document
Documentation/admin-guide/blockdev/zram.rst+422−0
@@ -0,0 +1,422 @@
1+========================================
2+zram: Compressed RAM based block devices
3+========================================
4+
5+Introduction
6+============
7+
8+The zram module creates RAM based block devices named /dev/zram<id>
9+(<id> = 0, 1, ...). Pages written to these disks are compressed and stored
10+in memory itself. These disks allow very fast I/O and compression provides
11+good amounts of memory savings. Some of the usecases include /tmp storage,
12+use as swap disks, various caches under /var and maybe many more :)
13+
14+Statistics for individual zram devices are exported through sysfs nodes at
15+/sys/block/zram<id>/
16+
17+Usage
18+=====
19+
20+There are several ways to configure and manage zram device(-s):
21+
22+a) using zram and zram_control sysfs attributes
23+b) using zramctl utility, provided by util-linux (util-linux@vger.kernel.org).
24+
25+In this document we will describe only 'manual' zram configuration steps,
26+IOW, zram and zram_control sysfs attributes.
27+
28+In order to get a better idea about zramctl please consult util-linux
29+documentation, zramctl man-page or `zramctl --help`. Please be informed
30+that zram maintainers do not develop/maintain util-linux or zramctl, should
31+you have any questions please contact util-linux@vger.kernel.org
32+
33+Following shows a typical sequence of steps for using zram.
34+
35+WARNING
36+=======
37+
38+For the sake of simplicity we skip error checking parts in most of the
39+examples below. However, it is your sole responsibility to handle errors.
40+
41+zram sysfs attributes always return negative values in case of errors.
42+The list of possible return codes:
43+
44+======== =============================================================
45+-EBUSY an attempt to modify an attribute that cannot be changed once
46+ the device has been initialised. Please reset device first;
47+-ENOMEM zram was not able to allocate enough memory to fulfil your
48+ needs;
49+-EINVAL invalid input has been provided.
50+======== =============================================================
51+
52+If you use 'echo', the returned value that is changed by 'echo' utility,
53+and, in general case, something like::
54+
55+ echo 3 > /sys/block/zram0/max_comp_streams
56+ if [ $? -ne 0 ];
57+ handle_error
58+ fi
59+
60+should suffice.
61+
62+1) Load Module
63+==============
64+
65+::
66+
67+ modprobe zram num_devices=4
68+ This creates 4 devices: /dev/zram{0,1,2,3}
69+
70+num_devices parameter is optional and tells zram how many devices should be
71+pre-created. Default: 1.
72+
73+2) Set max number of compression streams
74+========================================
75+
76+Regardless the value passed to this attribute, ZRAM will always
77+allocate multiple compression streams - one per online CPUs - thus
78+allowing several concurrent compression operations. The number of
79+allocated compression streams goes down when some of the CPUs
80+become offline. There is no single-compression-stream mode anymore,
81+unless you are running a UP system or has only 1 CPU online.
82+
83+To find out how many streams are currently available::
84+
85+ cat /sys/block/zram0/max_comp_streams
86+
87+3) Select compression algorithm
88+===============================
89+
90+Using comp_algorithm device attribute one can see available and
91+currently selected (shown in square brackets) compression algorithms,
92+change selected compression algorithm (once the device is initialised
93+there is no way to change compression algorithm).
94+
95+Examples::
96+
97+ #show supported compression algorithms
98+ cat /sys/block/zram0/comp_algorithm
99+ lzo [lz4]
100+
101+ #select lzo compression algorithm
102+ echo lzo > /sys/block/zram0/comp_algorithm
103+
104+For the time being, the `comp_algorithm` content does not necessarily
105+show every compression algorithm supported by the kernel. We keep this
106+list primarily to simplify device configuration and one can configure
107+a new device with a compression algorithm that is not listed in
108+`comp_algorithm`. The thing is that, internally, ZRAM uses Crypto API
109+and, if some of the algorithms were built as modules, it's impossible
110+to list all of them using, for instance, /proc/crypto or any other
111+method. This, however, has an advantage of permitting the usage of
112+custom crypto compression modules (implementing S/W or H/W compression).
113+
114+4) Set Disksize
115+===============
116+
117+Set disk size by writing the value to sysfs node 'disksize'.
118+The value can be either in bytes or you can use mem suffixes.
119+Examples::
120+
121+ # Initialize /dev/zram0 with 50MB disksize
122+ echo $((50*1024*1024)) > /sys/block/zram0/disksize
123+
124+ # Using mem suffixes
125+ echo 256K > /sys/block/zram0/disksize
126+ echo 512M > /sys/block/zram0/disksize
127+ echo 1G > /sys/block/zram0/disksize
128+
129+Note:
130+There is little point creating a zram of greater than twice the size of memory
131+since we expect a 2:1 compression ratio. Note that zram uses about 0.1% of the
132+size of the disk when not in use so a huge zram is wasteful.
133+
134+5) Set memory limit: Optional
135+=============================
136+
137+Set memory limit by writing the value to sysfs node 'mem_limit'.
138+The value can be either in bytes or you can use mem suffixes.
139+In addition, you could change the value in runtime.
140+Examples::
141+
142+ # limit /dev/zram0 with 50MB memory
143+ echo $((50*1024*1024)) > /sys/block/zram0/mem_limit
144+
145+ # Using mem suffixes
146+ echo 256K > /sys/block/zram0/mem_limit
147+ echo 512M > /sys/block/zram0/mem_limit
148+ echo 1G > /sys/block/zram0/mem_limit
149+
150+ # To disable memory limit
151+ echo 0 > /sys/block/zram0/mem_limit
152+
153+6) Activate
154+===========
155+
156+::
157+
158+ mkswap /dev/zram0
159+ swapon /dev/zram0
160+
161+ mkfs.ext4 /dev/zram1
162+ mount /dev/zram1 /tmp
163+
164+7) Add/remove zram devices
165+==========================
166+
167+zram provides a control interface, which enables dynamic (on-demand) device
168+addition and removal.
169+
170+In order to add a new /dev/zramX device, perform read operation on hot_add
171+attribute. This will return either new device's device id (meaning that you
172+can use /dev/zram<id>) or error code.
173+
174+Example::
175+
176+ cat /sys/class/zram-control/hot_add
177+ 1
178+
179+To remove the existing /dev/zramX device (where X is a device id)
180+execute::
181+
182+ echo X > /sys/class/zram-control/hot_remove
183+
184+8) Stats
185+========
186+
187+Per-device statistics are exported as various nodes under /sys/block/zram<id>/
188+
189+A brief description of exported device attributes. For more details please
190+read Documentation/ABI/testing/sysfs-block-zram.
191+
192+====================== ====== ===============================================
193+Name access description
194+====================== ====== ===============================================
195+disksize RW show and set the device's disk size
196+initstate RO shows the initialization state of the device
197+reset WO trigger device reset
198+mem_used_max WO reset the `mem_used_max` counter (see later)
199+mem_limit WO specifies the maximum amount of memory ZRAM can
200+ use to store the compressed data
201+writeback_limit WO specifies the maximum amount of write IO zram
202+ can write out to backing device as 4KB unit
203+writeback_limit_enable RW show and set writeback_limit feature
204+max_comp_streams RW the number of possible concurrent compress
205+ operations
206+comp_algorithm RW show and change the compression algorithm
207+compact WO trigger memory compaction
208+debug_stat RO this file is used for zram debugging purposes
209+backing_dev RW set up backend storage for zram to write out
210+idle WO mark allocated slot as idle
211+====================== ====== ===============================================
212+
213+
214+User space is advised to use the following files to read the device statistics.
215+
216+File /sys/block/zram<id>/stat
217+
218+Represents block layer statistics. Read Documentation/block/stat.rst for
219+details.
220+
221+File /sys/block/zram<id>/io_stat
222+
223+The stat file represents device's I/O statistics not accounted by block
224+layer and, thus, not available in zram<id>/stat file. It consists of a
225+single line of text and contains the following stats separated by
226+whitespace:
227+
228+ ============= =============================================================
229+ failed_reads The number of failed reads
230+ failed_writes The number of failed writes
231+ invalid_io The number of non-page-size-aligned I/O requests
232+ notify_free Depending on device usage scenario it may account
233+
234+ a) the number of pages freed because of swap slot free
235+ notifications
236+ b) the number of pages freed because of
237+ REQ_OP_DISCARD requests sent by bio. The former ones are
238+ sent to a swap block device when a swap slot is freed,
239+ which implies that this disk is being used as a swap disk.
240+
241+ The latter ones are sent by filesystem mounted with
242+ discard option, whenever some data blocks are getting
243+ discarded.
244+ ============= =============================================================
245+
246+File /sys/block/zram<id>/mm_stat
247+
248+The stat file represents device's mm statistics. It consists of a single
249+line of text and contains the following stats separated by whitespace:
250+
251+ ================ =============================================================
252+ orig_data_size uncompressed size of data stored in this disk.
253+ This excludes same-element-filled pages (same_pages) since
254+ no memory is allocated for them.
255+ Unit: bytes
256+ compr_data_size compressed size of data stored in this disk
257+ mem_used_total the amount of memory allocated for this disk. This
258+ includes allocator fragmentation and metadata overhead,
259+ allocated for this disk. So, allocator space efficiency
260+ can be calculated using compr_data_size and this statistic.
261+ Unit: bytes
262+ mem_limit the maximum amount of memory ZRAM can use to store
263+ the compressed data
264+ mem_used_max the maximum amount of memory zram have consumed to
265+ store the data
266+ same_pages the number of same element filled pages written to this disk.
267+ No memory is allocated for such pages.
268+ pages_compacted the number of pages freed during compaction
269+ huge_pages the number of incompressible pages
270+ ================ =============================================================
271+
272+File /sys/block/zram<id>/bd_stat
273+
274+The stat file represents device's backing device statistics. It consists of
275+a single line of text and contains the following stats separated by whitespace:
276+
277+ ============== =============================================================
278+ bd_count size of data written in backing device.
279+ Unit: 4K bytes
280+ bd_reads the number of reads from backing device
281+ Unit: 4K bytes
282+ bd_writes the number of writes to backing device
283+ Unit: 4K bytes
284+ ============== =============================================================
285+
286+9) Deactivate
287+=============
288+
289+::
290+
291+ swapoff /dev/zram0
292+ umount /dev/zram1
293+
294+10) Reset
295+=========
296+
297+ Write any positive value to 'reset' sysfs node::
298+
299+ echo 1 > /sys/block/zram0/reset
300+ echo 1 > /sys/block/zram1/reset
301+
302+ This frees all the memory allocated for the given device and
303+ resets the disksize to zero. You must set the disksize again
304+ before reusing the device.
305+
306+Optional Feature
307+================
308+
309+writeback
310+---------
311+
312+With CONFIG_ZRAM_WRITEBACK, zram can write idle/incompressible page
313+to backing storage rather than keeping it in memory.
314+To use the feature, admin should set up backing device via::
315+
316+ echo /dev/sda5 > /sys/block/zramX/backing_dev
317+
318+before disksize setting. It supports only partition at this moment.
319+If admin want to use incompressible page writeback, they could do via::
320+
321+ echo huge > /sys/block/zramX/write
322+
323+To use idle page writeback, first, user need to declare zram pages
324+as idle::
325+
326+ echo all > /sys/block/zramX/idle
327+
328+From now on, any pages on zram are idle pages. The idle mark
329+will be removed until someone request access of the block.
330+IOW, unless there is access request, those pages are still idle pages.
331+
332+Admin can request writeback of those idle pages at right timing via::
333+
334+ echo idle > /sys/block/zramX/writeback
335+
336+With the command, zram writeback idle pages from memory to the storage.
337+
338+If there are lots of write IO with flash device, potentially, it has
339+flash wearout problem so that admin needs to design write limitation
340+to guarantee storage health for entire product life.
341+
342+To overcome the concern, zram supports "writeback_limit" feature.
343+The "writeback_limit_enable"'s default value is 0 so that it doesn't limit
344+any writeback. IOW, if admin want to apply writeback budget, he should
345+enable writeback_limit_enable via::
346+
347+ $ echo 1 > /sys/block/zramX/writeback_limit_enable
348+
349+Once writeback_limit_enable is set, zram doesn't allow any writeback
350+until admin set the budget via /sys/block/zramX/writeback_limit.
351+
352+(If admin doesn't enable writeback_limit_enable, writeback_limit's value
353+assigned via /sys/block/zramX/writeback_limit is meaninless.)
354+
355+If admin want to limit writeback as per-day 400M, he could do it
356+like below::
357+
358+ $ MB_SHIFT=20
359+ $ 4K_SHIFT=12
360+ $ echo $((400<<MB_SHIFT>>4K_SHIFT)) > \
361+ /sys/block/zram0/writeback_limit.
362+ $ echo 1 > /sys/block/zram0/writeback_limit_enable
363+
364+If admin want to allow further write again once the bugdet is exausted,
365+he could do it like below::
366+
367+ $ echo $((400<<MB_SHIFT>>4K_SHIFT)) > \
368+ /sys/block/zram0/writeback_limit
369+
370+If admin want to see remaining writeback budget since he set::
371+
372+ $ cat /sys/block/zramX/writeback_limit
373+
374+If admin want to disable writeback limit, he could do::
375+
376+ $ echo 0 > /sys/block/zramX/writeback_limit_enable
377+
378+The writeback_limit count will reset whenever you reset zram(e.g.,
379+system reboot, echo 1 > /sys/block/zramX/reset) so keeping how many of
380+writeback happened until you reset the zram to allocate extra writeback
381+budget in next setting is user's job.
382+
383+If admin want to measure writeback count in a certain period, he could
384+know it via /sys/block/zram0/bd_stat's 3rd column.
385+
386+memory tracking
387+===============
388+
389+With CONFIG_ZRAM_MEMORY_TRACKING, user can know information of the
390+zram block. It could be useful to catch cold or incompressible
391+pages of the process with*pagemap.
392+
393+If you enable the feature, you could see block state via
394+/sys/kernel/debug/zram/zram0/block_state". The output is as follows::
395+
396+ 300 75.033841 .wh.
397+ 301 63.806904 s...
398+ 302 63.806919 ..hi
399+
400+First column
401+ zram's block index.
402+Second column
403+ access time since the system was booted
404+Third column
405+ state of the block:
406+
407+ s:
408+ same page
409+ w:
410+ written page to backing store
411+ h:
412+ huge page
413+ i:
414+ idle page
415+
416+First line of above example says 300th block is accessed at 75.033841sec
417+and the block's state is huge so it is written back to the backing
418+storage. It's a debugging feature so anyone shouldn't rely on it to work
419+properly.
420+
421+Nitin Gupta
422+ngupta@vflare.org
Documentation/admin-guide/btmrvl.rstrenamed from Documentation/btmrvl.txt+0−0

File renamed without changes.

Documentation/admin-guide/bug-hunting.rst+2−2
@@ -90,9 +90,9 @@ the disk is not available then you have three options: · 89 unmodified lines
9090 run a null modem to a second machine and capture the output there
9191 using your favourite communication program. Minicom works well.
9292
93−(3) Use Kdump (see Documentation/kdump/kdump.txt),
93+(3) Use Kdump (see Documentation/admin-guide/kdump/kdump.rst),
9494 extract the kernel ring buffer from old memory with using dmesg
95− gdbmacro in Documentation/kdump/gdbmacros.txt.
95+ gdbmacro in Documentation/admin-guide/kdump/gdbmacros.txt.
9696
9797 Finding the bug's location
9898 --------------------------
Documentation/admin-guide/cgroup-v1/blkio-controller.rst+302−0
@@ -0,0 +1,302 @@
1+===================
2+Block IO Controller
3+===================
4+
5+Overview
6+========
7+cgroup subsys "blkio" implements the block io controller. There seems to be
8+a need of various kinds of IO control policies (like proportional BW, max BW)
9+both at leaf nodes as well as at intermediate nodes in a storage hierarchy.
10+Plan is to use the same cgroup based management interface for blkio controller
11+and based on user options switch IO policies in the background.
12+
13+One IO control policy is throttling policy which can be used to
14+specify upper IO rate limits on devices. This policy is implemented in
15+generic block layer and can be used on leaf nodes as well as higher
16+level logical devices like device mapper.
17+
18+HOWTO
19+=====
20+Throttling/Upper Limit policy
21+-----------------------------
22+- Enable Block IO controller::
23+
24+ CONFIG_BLK_CGROUP=y
25+
26+- Enable throttling in block layer::
27+
28+ CONFIG_BLK_DEV_THROTTLING=y
29+
30+- Mount blkio controller (see cgroups.txt, Why are cgroups needed?)::
31+
32+ mount -t cgroup -o blkio none /sys/fs/cgroup/blkio
33+
34+- Specify a bandwidth rate on particular device for root group. The format
35+ for policy is "<major>:<minor> <bytes_per_second>"::
36+
37+ echo "8:16 1048576" > /sys/fs/cgroup/blkio/blkio.throttle.read_bps_device
38+
39+ Above will put a limit of 1MB/second on reads happening for root group
40+ on device having major/minor number 8:16.
41+
42+- Run dd to read a file and see if rate is throttled to 1MB/s or not::
43+
44+ # dd iflag=direct if=/mnt/common/zerofile of=/dev/null bs=4K count=1024
45+ 1024+0 records in
46+ 1024+0 records out
47+ 4194304 bytes (4.2 MB) copied, 4.0001 s, 1.0 MB/s
48+
49+ Limits for writes can be put using blkio.throttle.write_bps_device file.
50+
51+Hierarchical Cgroups
52+====================
53+
54+Throttling implements hierarchy support; however,
55+throttling's hierarchy support is enabled iff "sane_behavior" is
56+enabled from cgroup side, which currently is a development option and
57+not publicly available.
58+
59+If somebody created a hierarchy like as follows::
60+
61+ root
62+ / \
63+ test1 test2
64+ |
65+ test3
66+
67+Throttling with "sane_behavior" will handle the
68+hierarchy correctly. For throttling, all limits apply
69+to the whole subtree while all statistics are local to the IOs
70+directly generated by tasks in that cgroup.
71+
72+Throttling without "sane_behavior" enabled from cgroup side will
73+practically treat all groups at same level as if it looks like the
74+following::
75+
76+ pivot
77+ / / \ \
78+ root test1 test2 test3
79+
80+Various user visible config options
81+===================================
82+CONFIG_BLK_CGROUP
83+ - Block IO controller.
84+
85+CONFIG_BFQ_CGROUP_DEBUG
86+ - Debug help. Right now some additional stats file show up in cgroup
87+ if this option is enabled.
88+
89+CONFIG_BLK_DEV_THROTTLING
90+ - Enable block device throttling support in block layer.
91+
92+Details of cgroup files
93+=======================
94+Proportional weight policy files
95+--------------------------------
96+- blkio.weight
97+ - Specifies per cgroup weight. This is default weight of the group
98+ on all the devices until and unless overridden by per device rule.
99+ (See blkio.weight_device).
100+ Currently allowed range of weights is from 10 to 1000.
101+
102+- blkio.weight_device
103+ - One can specify per cgroup per device rules using this interface.
104+ These rules override the default value of group weight as specified
105+ by blkio.weight.
106+
107+ Following is the format::
108+
109+ # echo dev_maj:dev_minor weight > blkio.weight_device
110+
111+ Configure weight=300 on /dev/sdb (8:16) in this cgroup::
112+
113+ # echo 8:16 300 > blkio.weight_device
114+ # cat blkio.weight_device
115+ dev weight
116+ 8:16 300
117+
118+ Configure weight=500 on /dev/sda (8:0) in this cgroup::
119+
120+ # echo 8:0 500 > blkio.weight_device
121+ # cat blkio.weight_device
122+ dev weight
123+ 8:0 500
124+ 8:16 300
125+
126+ Remove specific weight for /dev/sda in this cgroup::
127+
128+ # echo 8:0 0 > blkio.weight_device
129+ # cat blkio.weight_device
130+ dev weight
131+ 8:16 300
132+
133+- blkio.leaf_weight[_device]
134+ - Equivalents of blkio.weight[_device] for the purpose of
135+ deciding how much weight tasks in the given cgroup has while
136+ competing with the cgroup's child cgroups. For details,
137+ please refer to Documentation/block/cfq-iosched.txt.
138+
139+- blkio.time
140+ - disk time allocated to cgroup per device in milliseconds. First
141+ two fields specify the major and minor number of the device and
142+ third field specifies the disk time allocated to group in
143+ milliseconds.
144+
145+- blkio.sectors
146+ - number of sectors transferred to/from disk by the group. First
147+ two fields specify the major and minor number of the device and
148+ third field specifies the number of sectors transferred by the
149+ group to/from the device.
150+
151+- blkio.io_service_bytes
152+ - Number of bytes transferred to/from the disk by the group. These
153+ are further divided by the type of operation - read or write, sync
154+ or async. First two fields specify the major and minor number of the
155+ device, third field specifies the operation type and the fourth field
156+ specifies the number of bytes.
157+
158+- blkio.io_serviced
159+ - Number of IOs (bio) issued to the disk by the group. These
160+ are further divided by the type of operation - read or write, sync
161+ or async. First two fields specify the major and minor number of the
162+ device, third field specifies the operation type and the fourth field
163+ specifies the number of IOs.
164+
165+- blkio.io_service_time
166+ - Total amount of time between request dispatch and request completion
167+ for the IOs done by this cgroup. This is in nanoseconds to make it
168+ meaningful for flash devices too. For devices with queue depth of 1,
169+ this time represents the actual service time. When queue_depth > 1,
170+ that is no longer true as requests may be served out of order. This
171+ may cause the service time for a given IO to include the service time
172+ of multiple IOs when served out of order which may result in total
173+ io_service_time > actual time elapsed. This time is further divided by
174+ the type of operation - read or write, sync or async. First two fields
175+ specify the major and minor number of the device, third field
176+ specifies the operation type and the fourth field specifies the
177+ io_service_time in ns.
178+
179+- blkio.io_wait_time
180+ - Total amount of time the IOs for this cgroup spent waiting in the
181+ scheduler queues for service. This can be greater than the total time
182+ elapsed since it is cumulative io_wait_time for all IOs. It is not a
183+ measure of total time the cgroup spent waiting but rather a measure of
184+ the wait_time for its individual IOs. For devices with queue_depth > 1
185+ this metric does not include the time spent waiting for service once
186+ the IO is dispatched to the device but till it actually gets serviced
187+ (there might be a time lag here due to re-ordering of requests by the
188+ device). This is in nanoseconds to make it meaningful for flash
189+ devices too. This time is further divided by the type of operation -
190+ read or write, sync or async. First two fields specify the major and
191+ minor number of the device, third field specifies the operation type
192+ and the fourth field specifies the io_wait_time in ns.
193+
194+- blkio.io_merged
195+ - Total number of bios/requests merged into requests belonging to this
196+ cgroup. This is further divided by the type of operation - read or
197+ write, sync or async.
198+
199+- blkio.io_queued
200+ - Total number of requests queued up at any given instant for this
201+ cgroup. This is further divided by the type of operation - read or
202+ write, sync or async.
203+
204+- blkio.avg_queue_size
205+ - Debugging aid only enabled if CONFIG_BFQ_CGROUP_DEBUG=y.
206+ The average queue size for this cgroup over the entire time of this
207+ cgroup's existence. Queue size samples are taken each time one of the
208+ queues of this cgroup gets a timeslice.
209+
210+- blkio.group_wait_time
211+ - Debugging aid only enabled if CONFIG_BFQ_CGROUP_DEBUG=y.
212+ This is the amount of time the cgroup had to wait since it became busy
213+ (i.e., went from 0 to 1 request queued) to get a timeslice for one of
214+ its queues. This is different from the io_wait_time which is the
215+ cumulative total of the amount of time spent by each IO in that cgroup
216+ waiting in the scheduler queue. This is in nanoseconds. If this is
217+ read when the cgroup is in a waiting (for timeslice) state, the stat
218+ will only report the group_wait_time accumulated till the last time it
219+ got a timeslice and will not include the current delta.
220+
221+- blkio.empty_time
222+ - Debugging aid only enabled if CONFIG_BFQ_CGROUP_DEBUG=y.
223+ This is the amount of time a cgroup spends without any pending
224+ requests when not being served, i.e., it does not include any time
225+ spent idling for one of the queues of the cgroup. This is in
226+ nanoseconds. If this is read when the cgroup is in an empty state,
227+ the stat will only report the empty_time accumulated till the last
228+ time it had a pending request and will not include the current delta.
229+
230+- blkio.idle_time
231+ - Debugging aid only enabled if CONFIG_BFQ_CGROUP_DEBUG=y.
232+ This is the amount of time spent by the IO scheduler idling for a
233+ given cgroup in anticipation of a better request than the existing ones
234+ from other queues/cgroups. This is in nanoseconds. If this is read
235+ when the cgroup is in an idling state, the stat will only report the
236+ idle_time accumulated till the last idle period and will not include
237+ the current delta.
238+
239+- blkio.dequeue
240+ - Debugging aid only enabled if CONFIG_BFQ_CGROUP_DEBUG=y. This
241+ gives the statistics about how many a times a group was dequeued
242+ from service tree of the device. First two fields specify the major
243+ and minor number of the device and third field specifies the number
244+ of times a group was dequeued from a particular device.
245+
246+- blkio.*_recursive
247+ - Recursive version of various stats. These files show the
248+ same information as their non-recursive counterparts but
249+ include stats from all the descendant cgroups.
250+
251+Throttling/Upper limit policy files
252+-----------------------------------
253+- blkio.throttle.read_bps_device
254+ - Specifies upper limit on READ rate from the device. IO rate is
255+ specified in bytes per second. Rules are per device. Following is
256+ the format::
257+
258+ echo "<major>:<minor> <rate_bytes_per_second>" > /cgrp/blkio.throttle.read_bps_device
259+
260+- blkio.throttle.write_bps_device
261+ - Specifies upper limit on WRITE rate to the device. IO rate is
262+ specified in bytes per second. Rules are per device. Following is
263+ the format::
264+
265+ echo "<major>:<minor> <rate_bytes_per_second>" > /cgrp/blkio.throttle.write_bps_device
266+
267+- blkio.throttle.read_iops_device
268+ - Specifies upper limit on READ rate from the device. IO rate is
269+ specified in IO per second. Rules are per device. Following is
270+ the format::
271+
272+ echo "<major>:<minor> <rate_io_per_second>" > /cgrp/blkio.throttle.read_iops_device
273+
274+- blkio.throttle.write_iops_device
275+ - Specifies upper limit on WRITE rate to the device. IO rate is
276+ specified in io per second. Rules are per device. Following is
277+ the format::
278+
279+ echo "<major>:<minor> <rate_io_per_second>" > /cgrp/blkio.throttle.write_iops_device
280+
281+Note: If both BW and IOPS rules are specified for a device, then IO is
282+ subjected to both the constraints.
283+
284+- blkio.throttle.io_serviced
285+ - Number of IOs (bio) issued to the disk by the group. These
286+ are further divided by the type of operation - read or write, sync
287+ or async. First two fields specify the major and minor number of the
288+ device, third field specifies the operation type and the fourth field
289+ specifies the number of IOs.
290+
291+- blkio.throttle.io_service_bytes
292+ - Number of bytes transferred to/from the disk by the group. These
293+ are further divided by the type of operation - read or write, sync
294+ or async. First two fields specify the major and minor number of the
295+ device, third field specifies the operation type and the fourth field
296+ specifies the number of bytes.
297+
298+Common files among various policies
299+-----------------------------------
300+- blkio.reset_stats
301+ - Writing an int to this file will result in resetting all the stats
302+ for that cgroup.
Documentation/admin-guide/cgroup-v1/cgroups.rst+695−0
@@ -0,0 +1,695 @@
1+==============
2+Control Groups
3+==============
4+
5+Written by Paul Menage <menage@google.com> based on
6+Documentation/admin-guide/cgroup-v1/cpusets.rst
7+
8+Original copyright statements from cpusets.txt:
9+
10+Portions Copyright (C) 2004 BULL SA.
11+
12+Portions Copyright (c) 2004-2006 Silicon Graphics, Inc.
13+
14+Modified by Paul Jackson <pj@sgi.com>
15+
16+Modified by Christoph Lameter <cl@linux.com>
17+
18+.. CONTENTS:
19+
20+ 1. Control Groups
21+ 1.1 What are cgroups ?
22+ 1.2 Why are cgroups needed ?
23+ 1.3 How are cgroups implemented ?
24+ 1.4 What does notify_on_release do ?
25+ 1.5 What does clone_children do ?
26+ 1.6 How do I use cgroups ?
27+ 2. Usage Examples and Syntax
28+ 2.1 Basic Usage
29+ 2.2 Attaching processes
30+ 2.3 Mounting hierarchies by name
31+ 3. Kernel API
32+ 3.1 Overview
33+ 3.2 Synchronization
34+ 3.3 Subsystem API
35+ 4. Extended attributes usage
36+ 5. Questions
37+
38+1. Control Groups
39+=================
40+
41+1.1 What are cgroups ?
42+----------------------
43+
44+Control Groups provide a mechanism for aggregating/partitioning sets of
45+tasks, and all their future children, into hierarchical groups with
46+specialized behaviour.
47+
48+Definitions:
49+
50+A *cgroup* associates a set of tasks with a set of parameters for one
51+or more subsystems.
52+
53+A *subsystem* is a module that makes use of the task grouping
54+facilities provided by cgroups to treat groups of tasks in
55+particular ways. A subsystem is typically a "resource controller" that
56+schedules a resource or applies per-cgroup limits, but it may be
57+anything that wants to act on a group of processes, e.g. a
58+virtualization subsystem.
59+
60+A *hierarchy* is a set of cgroups arranged in a tree, such that
61+every task in the system is in exactly one of the cgroups in the
62+hierarchy, and a set of subsystems; each subsystem has system-specific
63+state attached to each cgroup in the hierarchy. Each hierarchy has
64+an instance of the cgroup virtual filesystem associated with it.
65+
66+At any one time there may be multiple active hierarchies of task
67+cgroups. Each hierarchy is a partition of all tasks in the system.
68+
69+User-level code may create and destroy cgroups by name in an
70+instance of the cgroup virtual file system, specify and query to
71+which cgroup a task is assigned, and list the task PIDs assigned to
72+a cgroup. Those creations and assignments only affect the hierarchy
73+associated with that instance of the cgroup file system.
74+
75+On their own, the only use for cgroups is for simple job
76+tracking. The intention is that other subsystems hook into the generic
77+cgroup support to provide new attributes for cgroups, such as
78+accounting/limiting the resources which processes in a cgroup can
79+access. For example, cpusets (see Documentation/admin-guide/cgroup-v1/cpusets.rst) allow
80+you to associate a set of CPUs and a set of memory nodes with the
81+tasks in each cgroup.
82+
83+1.2 Why are cgroups needed ?
84+----------------------------
85+
86+There are multiple efforts to provide process aggregations in the
87+Linux kernel, mainly for resource-tracking purposes. Such efforts
88+include cpusets, CKRM/ResGroups, UserBeanCounters, and virtual server
89+namespaces. These all require the basic notion of a
90+grouping/partitioning of processes, with newly forked processes ending
91+up in the same group (cgroup) as their parent process.
92+
93+The kernel cgroup patch provides the minimum essential kernel
94+mechanisms required to efficiently implement such groups. It has
95+minimal impact on the system fast paths, and provides hooks for
96+specific subsystems such as cpusets to provide additional behaviour as
97+desired.
98+
99+Multiple hierarchy support is provided to allow for situations where
100+the division of tasks into cgroups is distinctly different for
101+different subsystems - having parallel hierarchies allows each
102+hierarchy to be a natural division of tasks, without having to handle
103+complex combinations of tasks that would be present if several
104+unrelated subsystems needed to be forced into the same tree of
105+cgroups.
106+
107+At one extreme, each resource controller or subsystem could be in a
108+separate hierarchy; at the other extreme, all subsystems
109+would be attached to the same hierarchy.
110+
111+As an example of a scenario (originally proposed by vatsa@in.ibm.com)
112+that can benefit from multiple hierarchies, consider a large
113+university server with various users - students, professors, system
114+tasks etc. The resource planning for this server could be along the
115+following lines::
116+
117+ CPU : "Top cpuset"
118+ / \
119+ CPUSet1 CPUSet2
120+ | |
121+ (Professors) (Students)
122+
123+ In addition (system tasks) are attached to topcpuset (so
124+ that they can run anywhere) with a limit of 20%
125+
126+ Memory : Professors (50%), Students (30%), system (20%)
127+
128+ Disk : Professors (50%), Students (30%), system (20%)
129+
130+ Network : WWW browsing (20%), Network File System (60%), others (20%)
131+ / \
132+ Professors (15%) students (5%)
133+
134+Browsers like Firefox/Lynx go into the WWW network class, while (k)nfsd goes
135+into the NFS network class.
136+
137+At the same time Firefox/Lynx will share an appropriate CPU/Memory class
138+depending on who launched it (prof/student).
139+
140+With the ability to classify tasks differently for different resources
141+(by putting those resource subsystems in different hierarchies),
142+the admin can easily set up a script which receives exec notifications
143+and depending on who is launching the browser he can::
144+
145+ # echo browser_pid > /sys/fs/cgroup/<restype>/<userclass>/tasks
146+
147+With only a single hierarchy, he now would potentially have to create
148+a separate cgroup for every browser launched and associate it with
149+appropriate network and other resource class. This may lead to
150+proliferation of such cgroups.
151+
152+Also let's say that the administrator would like to give enhanced network
153+access temporarily to a student's browser (since it is night and the user
154+wants to do online gaming :)) OR give one of the student's simulation
155+apps enhanced CPU power.
156+
157+With ability to write PIDs directly to resource classes, it's just a
158+matter of::
159+
160+ # echo pid > /sys/fs/cgroup/network/<new_class>/tasks
161+ (after some time)
162+ # echo pid > /sys/fs/cgroup/network/<orig_class>/tasks
163+
164+Without this ability, the administrator would have to split the cgroup into
165+multiple separate ones and then associate the new cgroups with the
166+new resource classes.
167+
168+
169+
170+1.3 How are cgroups implemented ?
171+---------------------------------
172+
173+Control Groups extends the kernel as follows:
174+
175+ - Each task in the system has a reference-counted pointer to a
176+ css_set.
177+
178+ - A css_set contains a set of reference-counted pointers to
179+ cgroup_subsys_state objects, one for each cgroup subsystem
180+ registered in the system. There is no direct link from a task to
181+ the cgroup of which it's a member in each hierarchy, but this
182+ can be determined by following pointers through the
183+ cgroup_subsys_state objects. This is because accessing the
184+ subsystem state is something that's expected to happen frequently
185+ and in performance-critical code, whereas operations that require a
186+ task's actual cgroup assignments (in particular, moving between
187+ cgroups) are less common. A linked list runs through the cg_list
188+ field of each task_struct using the css_set, anchored at
189+ css_set->tasks.
190+
191+ - A cgroup hierarchy filesystem can be mounted for browsing and
192+ manipulation from user space.
193+
194+ - You can list all the tasks (by PID) attached to any cgroup.
195+
196+The implementation of cgroups requires a few, simple hooks
197+into the rest of the kernel, none in performance-critical paths:
198+
199+ - in init/main.c, to initialize the root cgroups and initial
200+ css_set at system boot.
201+
202+ - in fork and exit, to attach and detach a task from its css_set.
203+
204+In addition, a new file system of type "cgroup" may be mounted, to
205+enable browsing and modifying the cgroups presently known to the
206+kernel. When mounting a cgroup hierarchy, you may specify a
207+comma-separated list of subsystems to mount as the filesystem mount
208+options. By default, mounting the cgroup filesystem attempts to
209+mount a hierarchy containing all registered subsystems.
210+
211+If an active hierarchy with exactly the same set of subsystems already
212+exists, it will be reused for the new mount. If no existing hierarchy
213+matches, and any of the requested subsystems are in use in an existing
214+hierarchy, the mount will fail with -EBUSY. Otherwise, a new hierarchy
215+is activated, associated with the requested subsystems.
216+
217+It's not currently possible to bind a new subsystem to an active
218+cgroup hierarchy, or to unbind a subsystem from an active cgroup
219+hierarchy. This may be possible in future, but is fraught with nasty
220+error-recovery issues.
221+
222+When a cgroup filesystem is unmounted, if there are any
223+child cgroups created below the top-level cgroup, that hierarchy
224+will remain active even though unmounted; if there are no
225+child cgroups then the hierarchy will be deactivated.
226+
227+No new system calls are added for cgroups - all support for
228+querying and modifying cgroups is via this cgroup file system.
229+
230+Each task under /proc has an added file named 'cgroup' displaying,
231+for each active hierarchy, the subsystem names and the cgroup name
232+as the path relative to the root of the cgroup file system.
233+
234+Each cgroup is represented by a directory in the cgroup file system
235+containing the following files describing that cgroup:
236+
237+ - tasks: list of tasks (by PID) attached to that cgroup. This list
238+ is not guaranteed to be sorted. Writing a thread ID into this file
239+ moves the thread into this cgroup.
240+ - cgroup.procs: list of thread group IDs in the cgroup. This list is
241+ not guaranteed to be sorted or free of duplicate TGIDs, and userspace
242+ should sort/uniquify the list if this property is required.
243+ Writing a thread group ID into this file moves all threads in that
244+ group into this cgroup.
245+ - notify_on_release flag: run the release agent on exit?
246+ - release_agent: the path to use for release notifications (this file
247+ exists in the top cgroup only)
248+
249+Other subsystems such as cpusets may add additional files in each
250+cgroup dir.
251+
252+New cgroups are created using the mkdir system call or shell
253+command. The properties of a cgroup, such as its flags, are
254+modified by writing to the appropriate file in that cgroups
255+directory, as listed above.
256+
257+The named hierarchical structure of nested cgroups allows partitioning
258+a large system into nested, dynamically changeable, "soft-partitions".
259+
260+The attachment of each task, automatically inherited at fork by any
261+children of that task, to a cgroup allows organizing the work load
262+on a system into related sets of tasks. A task may be re-attached to
263+any other cgroup, if allowed by the permissions on the necessary
264+cgroup file system directories.
265+
266+When a task is moved from one cgroup to another, it gets a new
267+css_set pointer - if there's an already existing css_set with the
268+desired collection of cgroups then that group is reused, otherwise a new
269+css_set is allocated. The appropriate existing css_set is located by
270+looking into a hash table.
271+
272+To allow access from a cgroup to the css_sets (and hence tasks)
273+that comprise it, a set of cg_cgroup_link objects form a lattice;
274+each cg_cgroup_link is linked into a list of cg_cgroup_links for
275+a single cgroup on its cgrp_link_list field, and a list of
276+cg_cgroup_links for a single css_set on its cg_link_list.
277+
278+Thus the set of tasks in a cgroup can be listed by iterating over
279+each css_set that references the cgroup, and sub-iterating over
280+each css_set's task set.
281+
282+The use of a Linux virtual file system (vfs) to represent the
283+cgroup hierarchy provides for a familiar permission and name space
284+for cgroups, with a minimum of additional kernel code.
285+
286+1.4 What does notify_on_release do ?
287+------------------------------------
288+
289+If the notify_on_release flag is enabled (1) in a cgroup, then
290+whenever the last task in the cgroup leaves (exits or attaches to
291+some other cgroup) and the last child cgroup of that cgroup
292+is removed, then the kernel runs the command specified by the contents
293+of the "release_agent" file in that hierarchy's root directory,
294+supplying the pathname (relative to the mount point of the cgroup
295+file system) of the abandoned cgroup. This enables automatic
296+removal of abandoned cgroups. The default value of
297+notify_on_release in the root cgroup at system boot is disabled
298+(0). The default value of other cgroups at creation is the current
299+value of their parents' notify_on_release settings. The default value of
300+a cgroup hierarchy's release_agent path is empty.
301+
302+1.5 What does clone_children do ?
303+---------------------------------
304+
305+This flag only affects the cpuset controller. If the clone_children
306+flag is enabled (1) in a cgroup, a new cpuset cgroup will copy its
307+configuration from the parent during initialization.
308+
309+1.6 How do I use cgroups ?
310+--------------------------
311+
312+To start a new job that is to be contained within a cgroup, using
313+the "cpuset" cgroup subsystem, the steps are something like::
314+
315+ 1) mount -t tmpfs cgroup_root /sys/fs/cgroup
316+ 2) mkdir /sys/fs/cgroup/cpuset
317+ 3) mount -t cgroup -ocpuset cpuset /sys/fs/cgroup/cpuset
318+ 4) Create the new cgroup by doing mkdir's and write's (or echo's) in
319+ the /sys/fs/cgroup/cpuset virtual file system.
320+ 5) Start a task that will be the "founding father" of the new job.
321+ 6) Attach that task to the new cgroup by writing its PID to the
322+ /sys/fs/cgroup/cpuset tasks file for that cgroup.
323+ 7) fork, exec or clone the job tasks from this founding father task.
324+
325+For example, the following sequence of commands will setup a cgroup
326+named "Charlie", containing just CPUs 2 and 3, and Memory Node 1,
327+and then start a subshell 'sh' in that cgroup::
328+
329+ mount -t tmpfs cgroup_root /sys/fs/cgroup
330+ mkdir /sys/fs/cgroup/cpuset
331+ mount -t cgroup cpuset -ocpuset /sys/fs/cgroup/cpuset
332+ cd /sys/fs/cgroup/cpuset
333+ mkdir Charlie
334+ cd Charlie
335+ /bin/echo 2-3 > cpuset.cpus
336+ /bin/echo 1 > cpuset.mems
337+ /bin/echo $$ > tasks
338+ sh
339+ # The subshell 'sh' is now running in cgroup Charlie
340+ # The next line should display '/Charlie'
341+ cat /proc/self/cgroup
342+
343+2. Usage Examples and Syntax
344+============================
345+
346+2.1 Basic Usage
347+---------------
348+
349+Creating, modifying, using cgroups can be done through the cgroup
350+virtual filesystem.
351+
352+To mount a cgroup hierarchy with all available subsystems, type::
353+
354+ # mount -t cgroup xxx /sys/fs/cgroup
355+
356+The "xxx" is not interpreted by the cgroup code, but will appear in
357+/proc/mounts so may be any useful identifying string that you like.
358+
359+Note: Some subsystems do not work without some user input first. For instance,
360+if cpusets are enabled the user will have to populate the cpus and mems files
361+for each new cgroup created before that group can be used.
362+
363+As explained in section `1.2 Why are cgroups needed?` you should create
364+different hierarchies of cgroups for each single resource or group of
365+resources you want to control. Therefore, you should mount a tmpfs on
366+/sys/fs/cgroup and create directories for each cgroup resource or resource
367+group::
368+
369+ # mount -t tmpfs cgroup_root /sys/fs/cgroup
370+ # mkdir /sys/fs/cgroup/rg1
371+
372+To mount a cgroup hierarchy with just the cpuset and memory
373+subsystems, type::
374+
375+ # mount -t cgroup -o cpuset,memory hier1 /sys/fs/cgroup/rg1
376+
377+While remounting cgroups is currently supported, it is not recommend
378+to use it. Remounting allows changing bound subsystems and
379+release_agent. Rebinding is hardly useful as it only works when the
380+hierarchy is empty and release_agent itself should be replaced with
381+conventional fsnotify. The support for remounting will be removed in
382+the future.
383+
384+To Specify a hierarchy's release_agent::
385+
386+ # mount -t cgroup -o cpuset,release_agent="/sbin/cpuset_release_agent" \
387+ xxx /sys/fs/cgroup/rg1
388+
389+Note that specifying 'release_agent' more than once will return failure.
390+
391+Note that changing the set of subsystems is currently only supported
392+when the hierarchy consists of a single (root) cgroup. Supporting
393+the ability to arbitrarily bind/unbind subsystems from an existing
394+cgroup hierarchy is intended to be implemented in the future.
395+
396+Then under /sys/fs/cgroup/rg1 you can find a tree that corresponds to the
397+tree of the cgroups in the system. For instance, /sys/fs/cgroup/rg1
398+is the cgroup that holds the whole system.
399+
400+If you want to change the value of release_agent::
401+
402+ # echo "/sbin/new_release_agent" > /sys/fs/cgroup/rg1/release_agent
403+
404+It can also be changed via remount.
405+
406+If you want to create a new cgroup under /sys/fs/cgroup/rg1::
407+
408+ # cd /sys/fs/cgroup/rg1
409+ # mkdir my_cgroup
410+
411+Now you want to do something with this cgroup:
412+
413+ # cd my_cgroup
414+
415+In this directory you can find several files::
416+
417+ # ls
418+ cgroup.procs notify_on_release tasks
419+ (plus whatever files added by the attached subsystems)
420+
421+Now attach your shell to this cgroup::
422+
423+ # /bin/echo $$ > tasks
424+
425+You can also create cgroups inside your cgroup by using mkdir in this
426+directory::
427+
428+ # mkdir my_sub_cs
429+
430+To remove a cgroup, just use rmdir::
431+
432+ # rmdir my_sub_cs
433+
434+This will fail if the cgroup is in use (has cgroups inside, or
435+has processes attached, or is held alive by other subsystem-specific
436+reference).
437+
438+2.2 Attaching processes
439+-----------------------
440+
441+::
442+
443+ # /bin/echo PID > tasks
444+
445+Note that it is PID, not PIDs. You can only attach ONE task at a time.
446+If you have several tasks to attach, you have to do it one after another::
447+
448+ # /bin/echo PID1 > tasks
449+ # /bin/echo PID2 > tasks
450+ ...
451+ # /bin/echo PIDn > tasks
452+
453+You can attach the current shell task by echoing 0::
454+
455+ # echo 0 > tasks
456+
457+You can use the cgroup.procs file instead of the tasks file to move all
458+threads in a threadgroup at once. Echoing the PID of any task in a
459+threadgroup to cgroup.procs causes all tasks in that threadgroup to be
460+attached to the cgroup. Writing 0 to cgroup.procs moves all tasks
461+in the writing task's threadgroup.
462+
463+Note: Since every task is always a member of exactly one cgroup in each
464+mounted hierarchy, to remove a task from its current cgroup you must
465+move it into a new cgroup (possibly the root cgroup) by writing to the
466+new cgroup's tasks file.
467+
468+Note: Due to some restrictions enforced by some cgroup subsystems, moving
469+a process to another cgroup can fail.
470+
471+2.3 Mounting hierarchies by name
472+--------------------------------
473+
474+Passing the name=<x> option when mounting a cgroups hierarchy
475+associates the given name with the hierarchy. This can be used when
476+mounting a pre-existing hierarchy, in order to refer to it by name
477+rather than by its set of active subsystems. Each hierarchy is either
478+nameless, or has a unique name.
479+
480+The name should match [\w.-]+
481+
482+When passing a name=<x> option for a new hierarchy, you need to
483+specify subsystems manually; the legacy behaviour of mounting all
484+subsystems when none are explicitly specified is not supported when
485+you give a subsystem a name.
486+
487+The name of the subsystem appears as part of the hierarchy description
488+in /proc/mounts and /proc/<pid>/cgroups.
489+
490+
491+3. Kernel API
492+=============
493+
494+3.1 Overview
495+------------
496+
497+Each kernel subsystem that wants to hook into the generic cgroup
498+system needs to create a cgroup_subsys object. This contains
499+various methods, which are callbacks from the cgroup system, along
500+with a subsystem ID which will be assigned by the cgroup system.
501+
502+Other fields in the cgroup_subsys object include:
503+
504+- subsys_id: a unique array index for the subsystem, indicating which
505+ entry in cgroup->subsys[] this subsystem should be managing.
506+
507+- name: should be initialized to a unique subsystem name. Should be
508+ no longer than MAX_CGROUP_TYPE_NAMELEN.
509+
510+- early_init: indicate if the subsystem needs early initialization
511+ at system boot.
512+
513+Each cgroup object created by the system has an array of pointers,
514+indexed by subsystem ID; this pointer is entirely managed by the
515+subsystem; the generic cgroup code will never touch this pointer.
516+
517+3.2 Synchronization
518+-------------------
519+
520+There is a global mutex, cgroup_mutex, used by the cgroup
521+system. This should be taken by anything that wants to modify a
522+cgroup. It may also be taken to prevent cgroups from being
523+modified, but more specific locks may be more appropriate in that
524+situation.
525+
526+See kernel/cgroup.c for more details.
527+
528+Subsystems can take/release the cgroup_mutex via the functions
529+cgroup_lock()/cgroup_unlock().
530+
531+Accessing a task's cgroup pointer may be done in the following ways:
532+- while holding cgroup_mutex
533+- while holding the task's alloc_lock (via task_lock())
534+- inside an rcu_read_lock() section via rcu_dereference()
535+
536+3.3 Subsystem API
537+-----------------
538+
539+Each subsystem should:
540+
541+- add an entry in linux/cgroup_subsys.h
542+- define a cgroup_subsys object called <name>_cgrp_subsys
543+
544+Each subsystem may export the following methods. The only mandatory
545+methods are css_alloc/free. Any others that are null are presumed to
546+be successful no-ops.
547+
548+``struct cgroup_subsys_state *css_alloc(struct cgroup *cgrp)``
549+(cgroup_mutex held by caller)
550+
551+Called to allocate a subsystem state object for a cgroup. The
552+subsystem should allocate its subsystem state object for the passed
553+cgroup, returning a pointer to the new object on success or a
554+ERR_PTR() value. On success, the subsystem pointer should point to
555+a structure of type cgroup_subsys_state (typically embedded in a
556+larger subsystem-specific object), which will be initialized by the
557+cgroup system. Note that this will be called at initialization to
558+create the root subsystem state for this subsystem; this case can be
559+identified by the passed cgroup object having a NULL parent (since
560+it's the root of the hierarchy) and may be an appropriate place for
561+initialization code.
562+
563+``int css_online(struct cgroup *cgrp)``
564+(cgroup_mutex held by caller)
565+
566+Called after @cgrp successfully completed all allocations and made
567+visible to cgroup_for_each_child/descendant_*() iterators. The
568+subsystem may choose to fail creation by returning -errno. This
569+callback can be used to implement reliable state sharing and
570+propagation along the hierarchy. See the comment on
571+cgroup_for_each_descendant_pre() for details.
572+
573+``void css_offline(struct cgroup *cgrp);``
574+(cgroup_mutex held by caller)
575+
576+This is the counterpart of css_online() and called iff css_online()
577+has succeeded on @cgrp. This signifies the beginning of the end of
578+@cgrp. @cgrp is being removed and the subsystem should start dropping
579+all references it's holding on @cgrp. When all references are dropped,
580+cgroup removal will proceed to the next step - css_free(). After this
581+callback, @cgrp should be considered dead to the subsystem.
582+
583+``void css_free(struct cgroup *cgrp)``
584+(cgroup_mutex held by caller)
585+
586+The cgroup system is about to free @cgrp; the subsystem should free
587+its subsystem state object. By the time this method is called, @cgrp
588+is completely unused; @cgrp->parent is still valid. (Note - can also
589+be called for a newly-created cgroup if an error occurs after this
590+subsystem's create() method has been called for the new cgroup).
591+
592+``int can_attach(struct cgroup *cgrp, struct cgroup_taskset *tset)``
593+(cgroup_mutex held by caller)
594+
595+Called prior to moving one or more tasks into a cgroup; if the
596+subsystem returns an error, this will abort the attach operation.
597+@tset contains the tasks to be attached and is guaranteed to have at
598+least one task in it.
599+
600+If there are multiple tasks in the taskset, then:
601+ - it's guaranteed that all are from the same thread group
602+ - @tset contains all tasks from the thread group whether or not
603+ they're switching cgroups
604+ - the first task is the leader
605+
606+Each @tset entry also contains the task's old cgroup and tasks which
607+aren't switching cgroup can be skipped easily using the
608+cgroup_taskset_for_each() iterator. Note that this isn't called on a
609+fork. If this method returns 0 (success) then this should remain valid
610+while the caller holds cgroup_mutex and it is ensured that either
611+attach() or cancel_attach() will be called in future.
612+
613+``void css_reset(struct cgroup_subsys_state *css)``
614+(cgroup_mutex held by caller)
615+
616+An optional operation which should restore @css's configuration to the
617+initial state. This is currently only used on the unified hierarchy
618+when a subsystem is disabled on a cgroup through
619+"cgroup.subtree_control" but should remain enabled because other
620+subsystems depend on it. cgroup core makes such a css invisible by
621+removing the associated interface files and invokes this callback so
622+that the hidden subsystem can return to the initial neutral state.
623+This prevents unexpected resource control from a hidden css and
624+ensures that the configuration is in the initial state when it is made
625+visible again later.
626+
627+``void cancel_attach(struct cgroup *cgrp, struct cgroup_taskset *tset)``
628+(cgroup_mutex held by caller)
629+
630+Called when a task attach operation has failed after can_attach() has succeeded.
631+A subsystem whose can_attach() has some side-effects should provide this
632+function, so that the subsystem can implement a rollback. If not, not necessary.
633+This will be called only about subsystems whose can_attach() operation have
634+succeeded. The parameters are identical to can_attach().
635+
636+``void attach(struct cgroup *cgrp, struct cgroup_taskset *tset)``
637+(cgroup_mutex held by caller)
638+
639+Called after the task has been attached to the cgroup, to allow any
640+post-attachment activity that requires memory allocations or blocking.
641+The parameters are identical to can_attach().
642+
643+``void fork(struct task_struct *task)``
644+
645+Called when a task is forked into a cgroup.
646+
647+``void exit(struct task_struct *task)``
648+
649+Called during task exit.
650+
651+``void free(struct task_struct *task)``
652+
653+Called when the task_struct is freed.
654+
655+``void bind(struct cgroup *root)``
656+(cgroup_mutex held by caller)
657+
658+Called when a cgroup subsystem is rebound to a different hierarchy
659+and root cgroup. Currently this will only involve movement between
660+the default hierarchy (which never has sub-cgroups) and a hierarchy
661+that is being created/destroyed (and hence has no sub-cgroups).
662+
663+4. Extended attribute usage
664+===========================
665+
666+cgroup filesystem supports certain types of extended attributes in its
667+directories and files. The current supported types are:
668+
669+ - Trusted (XATTR_TRUSTED)
670+ - Security (XATTR_SECURITY)
671+
672+Both require CAP_SYS_ADMIN capability to set.
673+
674+Like in tmpfs, the extended attributes in cgroup filesystem are stored
675+using kernel memory and it's advised to keep the usage at minimum. This
676+is the reason why user defined extended attributes are not supported, since
677+any user can do it and there's no limit in the value size.
678+
679+The current known users for this feature are SELinux to limit cgroup usage
680+in containers and systemd for assorted meta data like main PID in a cgroup
681+(systemd creates a cgroup per service).
682+
683+5. Questions
684+============
685+
686+::
687+
688+ Q: what's up with this '/bin/echo' ?
689+ A: bash's builtin 'echo' command does not check calls to write() against
690+ errors. If you use it in the cgroup file system, you won't be
691+ able to tell whether a command succeeded or failed.
692+
693+ Q: When I attach processes, only the first of the line gets really attached !
694+ A: We can only return one error code per call to write(). So you should also
695+ put only ONE PID.
Documentation/admin-guide/cgroup-v1/cpuacct.rst+50−0
@@ -0,0 +1,50 @@
1+=========================
2+CPU Accounting Controller
3+=========================
4+
5+The CPU accounting controller is used to group tasks using cgroups and
6+account the CPU usage of these groups of tasks.
7+
8+The CPU accounting controller supports multi-hierarchy groups. An accounting
9+group accumulates the CPU usage of all of its child groups and the tasks
10+directly present in its group.
11+
12+Accounting groups can be created by first mounting the cgroup filesystem::
13+
14+ # mount -t cgroup -ocpuacct none /sys/fs/cgroup
15+
16+With the above step, the initial or the parent accounting group becomes
17+visible at /sys/fs/cgroup. At bootup, this group includes all the tasks in
18+the system. /sys/fs/cgroup/tasks lists the tasks in this cgroup.
19+/sys/fs/cgroup/cpuacct.usage gives the CPU time (in nanoseconds) obtained
20+by this group which is essentially the CPU time obtained by all the tasks
21+in the system.
22+
23+New accounting groups can be created under the parent group /sys/fs/cgroup::
24+
25+ # cd /sys/fs/cgroup
26+ # mkdir g1
27+ # echo $$ > g1/tasks
28+
29+The above steps create a new group g1 and move the current shell
30+process (bash) into it. CPU time consumed by this bash and its children
31+can be obtained from g1/cpuacct.usage and the same is accumulated in
32+/sys/fs/cgroup/cpuacct.usage also.
33+
34+cpuacct.stat file lists a few statistics which further divide the
35+CPU time obtained by the cgroup into user and system times. Currently
36+the following statistics are supported:
37+
38+user: Time spent by tasks of the cgroup in user mode.
39+system: Time spent by tasks of the cgroup in kernel mode.
40+
41+user and system are in USER_HZ unit.
42+
43+cpuacct controller uses percpu_counter interface to collect user and
44+system times. This has two side effects:
45+
46+- It is theoretically possible to see wrong values for user and system times.
47+ This is because percpu_counter_read() on 32bit systems isn't safe
48+ against concurrent writes.
49+- It is possible to see slightly outdated values for user and system times
50+ due to the batch processing nature of percpu_counter.
Documentation/admin-guide/cgroup-v1/cpusets.rst+866−0
@@ -0,0 +1,866 @@
1+=======
2+CPUSETS
3+=======
4+
5+Copyright (C) 2004 BULL SA.
6+
7+Written by Simon.Derr@bull.net
8+
9+- Portions Copyright (c) 2004-2006 Silicon Graphics, Inc.
10+- Modified by Paul Jackson <pj@sgi.com>
11+- Modified by Christoph Lameter <cl@linux.com>
12+- Modified by Paul Menage <menage@google.com>
13+- Modified by Hidetoshi Seto <seto.hidetoshi@jp.fujitsu.com>
14+
15+.. CONTENTS:
16+
17+ 1. Cpusets
18+ 1.1 What are cpusets ?
19+ 1.2 Why are cpusets needed ?
20+ 1.3 How are cpusets implemented ?
21+ 1.4 What are exclusive cpusets ?
22+ 1.5 What is memory_pressure ?
23+ 1.6 What is memory spread ?
24+ 1.7 What is sched_load_balance ?
25+ 1.8 What is sched_relax_domain_level ?
26+ 1.9 How do I use cpusets ?
27+ 2. Usage Examples and Syntax
28+ 2.1 Basic Usage
29+ 2.2 Adding/removing cpus
30+ 2.3 Setting flags
31+ 2.4 Attaching processes
32+ 3. Questions
33+ 4. Contact
34+
35+1. Cpusets
36+==========
37+
38+1.1 What are cpusets ?
39+----------------------
40+
41+Cpusets provide a mechanism for assigning a set of CPUs and Memory
42+Nodes to a set of tasks. In this document "Memory Node" refers to
43+an on-line node that contains memory.
44+
45+Cpusets constrain the CPU and Memory placement of tasks to only
46+the resources within a task's current cpuset. They form a nested
47+hierarchy visible in a virtual file system. These are the essential
48+hooks, beyond what is already present, required to manage dynamic
49+job placement on large systems.
50+
51+Cpusets use the generic cgroup subsystem described in
52+Documentation/admin-guide/cgroup-v1/cgroups.rst.
53+
54+Requests by a task, using the sched_setaffinity(2) system call to
55+include CPUs in its CPU affinity mask, and using the mbind(2) and
56+set_mempolicy(2) system calls to include Memory Nodes in its memory
57+policy, are both filtered through that task's cpuset, filtering out any
58+CPUs or Memory Nodes not in that cpuset. The scheduler will not
59+schedule a task on a CPU that is not allowed in its cpus_allowed
60+vector, and the kernel page allocator will not allocate a page on a
61+node that is not allowed in the requesting task's mems_allowed vector.
62+
63+User level code may create and destroy cpusets by name in the cgroup
64+virtual file system, manage the attributes and permissions of these
65+cpusets and which CPUs and Memory Nodes are assigned to each cpuset,
66+specify and query to which cpuset a task is assigned, and list the
67+task pids assigned to a cpuset.
68+
69+
70+1.2 Why are cpusets needed ?
71+----------------------------
72+
73+The management of large computer systems, with many processors (CPUs),
74+complex memory cache hierarchies and multiple Memory Nodes having
75+non-uniform access times (NUMA) presents additional challenges for
76+the efficient scheduling and memory placement of processes.
77+
78+Frequently more modest sized systems can be operated with adequate
79+efficiency just by letting the operating system automatically share
80+the available CPU and Memory resources amongst the requesting tasks.
81+
82+But larger systems, which benefit more from careful processor and
83+memory placement to reduce memory access times and contention,
84+and which typically represent a larger investment for the customer,
85+can benefit from explicitly placing jobs on properly sized subsets of
86+the system.
87+
88+This can be especially valuable on:
89+
90+ * Web Servers running multiple instances of the same web application,
91+ * Servers running different applications (for instance, a web server
92+ and a database), or
93+ * NUMA systems running large HPC applications with demanding
94+ performance characteristics.
95+
96+These subsets, or "soft partitions" must be able to be dynamically
97+adjusted, as the job mix changes, without impacting other concurrently
98+executing jobs. The location of the running jobs pages may also be moved
99+when the memory locations are changed.
100+
101+The kernel cpuset patch provides the minimum essential kernel
102+mechanisms required to efficiently implement such subsets. It
103+leverages existing CPU and Memory Placement facilities in the Linux
104+kernel to avoid any additional impact on the critical scheduler or
105+memory allocator code.
106+
107+
108+1.3 How are cpusets implemented ?
109+---------------------------------
110+
111+Cpusets provide a Linux kernel mechanism to constrain which CPUs and
112+Memory Nodes are used by a process or set of processes.
113+
114+The Linux kernel already has a pair of mechanisms to specify on which
115+CPUs a task may be scheduled (sched_setaffinity) and on which Memory
116+Nodes it may obtain memory (mbind, set_mempolicy).
117+
118+Cpusets extends these two mechanisms as follows:
119+
120+ - Cpusets are sets of allowed CPUs and Memory Nodes, known to the
121+ kernel.
122+ - Each task in the system is attached to a cpuset, via a pointer
123+ in the task structure to a reference counted cgroup structure.
124+ - Calls to sched_setaffinity are filtered to just those CPUs
125+ allowed in that task's cpuset.
126+ - Calls to mbind and set_mempolicy are filtered to just
127+ those Memory Nodes allowed in that task's cpuset.
128+ - The root cpuset contains all the systems CPUs and Memory
129+ Nodes.
130+ - For any cpuset, one can define child cpusets containing a subset
131+ of the parents CPU and Memory Node resources.
132+ - The hierarchy of cpusets can be mounted at /dev/cpuset, for
133+ browsing and manipulation from user space.
134+ - A cpuset may be marked exclusive, which ensures that no other
135+ cpuset (except direct ancestors and descendants) may contain
136+ any overlapping CPUs or Memory Nodes.
137+ - You can list all the tasks (by pid) attached to any cpuset.
138+
139+The implementation of cpusets requires a few, simple hooks
140+into the rest of the kernel, none in performance critical paths:
141+
142+ - in init/main.c, to initialize the root cpuset at system boot.
143+ - in fork and exit, to attach and detach a task from its cpuset.
144+ - in sched_setaffinity, to mask the requested CPUs by what's
145+ allowed in that task's cpuset.
146+ - in sched.c migrate_live_tasks(), to keep migrating tasks within
147+ the CPUs allowed by their cpuset, if possible.
148+ - in the mbind and set_mempolicy system calls, to mask the requested
149+ Memory Nodes by what's allowed in that task's cpuset.
150+ - in page_alloc.c, to restrict memory to allowed nodes.
151+ - in vmscan.c, to restrict page recovery to the current cpuset.
152+
153+You should mount the "cgroup" filesystem type in order to enable
154+browsing and modifying the cpusets presently known to the kernel. No
155+new system calls are added for cpusets - all support for querying and
156+modifying cpusets is via this cpuset file system.
157+
158+The /proc/<pid>/status file for each task has four added lines,
159+displaying the task's cpus_allowed (on which CPUs it may be scheduled)
160+and mems_allowed (on which Memory Nodes it may obtain memory),
161+in the two formats seen in the following example::
162+
163+ Cpus_allowed: ffffffff,ffffffff,ffffffff,ffffffff
164+ Cpus_allowed_list: 0-127
165+ Mems_allowed: ffffffff,ffffffff
166+ Mems_allowed_list: 0-63
167+
168+Each cpuset is represented by a directory in the cgroup file system
169+containing (on top of the standard cgroup files) the following
170+files describing that cpuset:
171+
172+ - cpuset.cpus: list of CPUs in that cpuset
173+ - cpuset.mems: list of Memory Nodes in that cpuset
174+ - cpuset.memory_migrate flag: if set, move pages to cpusets nodes
175+ - cpuset.cpu_exclusive flag: is cpu placement exclusive?
176+ - cpuset.mem_exclusive flag: is memory placement exclusive?
177+ - cpuset.mem_hardwall flag: is memory allocation hardwalled
178+ - cpuset.memory_pressure: measure of how much paging pressure in cpuset
179+ - cpuset.memory_spread_page flag: if set, spread page cache evenly on allowed nodes
180+ - cpuset.memory_spread_slab flag: if set, spread slab cache evenly on allowed nodes
181+ - cpuset.sched_load_balance flag: if set, load balance within CPUs on that cpuset
182+ - cpuset.sched_relax_domain_level: the searching range when migrating tasks
183+
184+In addition, only the root cpuset has the following file:
185+
186+ - cpuset.memory_pressure_enabled flag: compute memory_pressure?
187+
188+New cpusets are created using the mkdir system call or shell
189+command. The properties of a cpuset, such as its flags, allowed
190+CPUs and Memory Nodes, and attached tasks, are modified by writing
191+to the appropriate file in that cpusets directory, as listed above.
192+
193+The named hierarchical structure of nested cpusets allows partitioning
194+a large system into nested, dynamically changeable, "soft-partitions".
195+
196+The attachment of each task, automatically inherited at fork by any
197+children of that task, to a cpuset allows organizing the work load
198+on a system into related sets of tasks such that each set is constrained
199+to using the CPUs and Memory Nodes of a particular cpuset. A task
200+may be re-attached to any other cpuset, if allowed by the permissions
201+on the necessary cpuset file system directories.
202+
203+Such management of a system "in the large" integrates smoothly with
204+the detailed placement done on individual tasks and memory regions
205+using the sched_setaffinity, mbind and set_mempolicy system calls.
206+
207+The following rules apply to each cpuset:
208+
209+ - Its CPUs and Memory Nodes must be a subset of its parents.
210+ - It can't be marked exclusive unless its parent is.
211+ - If its cpu or memory is exclusive, they may not overlap any sibling.
212+
213+These rules, and the natural hierarchy of cpusets, enable efficient
214+enforcement of the exclusive guarantee, without having to scan all
215+cpusets every time any of them change to ensure nothing overlaps a
216+exclusive cpuset. Also, the use of a Linux virtual file system (vfs)
217+to represent the cpuset hierarchy provides for a familiar permission
218+and name space for cpusets, with a minimum of additional kernel code.
219+
220+The cpus and mems files in the root (top_cpuset) cpuset are
221+read-only. The cpus file automatically tracks the value of
222+cpu_online_mask using a CPU hotplug notifier, and the mems file
223+automatically tracks the value of node_states[N_MEMORY]--i.e.,
224+nodes with memory--using the cpuset_track_online_nodes() hook.
225+
226+
227+1.4 What are exclusive cpusets ?
228+--------------------------------
229+
230+If a cpuset is cpu or mem exclusive, no other cpuset, other than
231+a direct ancestor or descendant, may share any of the same CPUs or
232+Memory Nodes.
233+
234+A cpuset that is cpuset.mem_exclusive *or* cpuset.mem_hardwall is "hardwalled",
235+i.e. it restricts kernel allocations for page, buffer and other data
236+commonly shared by the kernel across multiple users. All cpusets,
237+whether hardwalled or not, restrict allocations of memory for user
238+space. This enables configuring a system so that several independent
239+jobs can share common kernel data, such as file system pages, while
240+isolating each job's user allocation in its own cpuset. To do this,
241+construct a large mem_exclusive cpuset to hold all the jobs, and
242+construct child, non-mem_exclusive cpusets for each individual job.
243+Only a small amount of typical kernel memory, such as requests from
244+interrupt handlers, is allowed to be taken outside even a
245+mem_exclusive cpuset.
246+
247+
248+1.5 What is memory_pressure ?
249+-----------------------------
250+The memory_pressure of a cpuset provides a simple per-cpuset metric
251+of the rate that the tasks in a cpuset are attempting to free up in
252+use memory on the nodes of the cpuset to satisfy additional memory
253+requests.
254+
255+This enables batch managers monitoring jobs running in dedicated
256+cpusets to efficiently detect what level of memory pressure that job
257+is causing.
258+
259+This is useful both on tightly managed systems running a wide mix of
260+submitted jobs, which may choose to terminate or re-prioritize jobs that
261+are trying to use more memory than allowed on the nodes assigned to them,
262+and with tightly coupled, long running, massively parallel scientific
263+computing jobs that will dramatically fail to meet required performance
264+goals if they start to use more memory than allowed to them.
265+
266+This mechanism provides a very economical way for the batch manager
267+to monitor a cpuset for signs of memory pressure. It's up to the
268+batch manager or other user code to decide what to do about it and
269+take action.
270+
271+==>
272+ Unless this feature is enabled by writing "1" to the special file
273+ /dev/cpuset/memory_pressure_enabled, the hook in the rebalance
274+ code of __alloc_pages() for this metric reduces to simply noticing
275+ that the cpuset_memory_pressure_enabled flag is zero. So only
276+ systems that enable this feature will compute the metric.
277+
278+Why a per-cpuset, running average:
279+
280+ Because this meter is per-cpuset, rather than per-task or mm,
281+ the system load imposed by a batch scheduler monitoring this
282+ metric is sharply reduced on large systems, because a scan of
283+ the tasklist can be avoided on each set of queries.
284+
285+ Because this meter is a running average, instead of an accumulating
286+ counter, a batch scheduler can detect memory pressure with a
287+ single read, instead of having to read and accumulate results
288+ for a period of time.
289+
290+ Because this meter is per-cpuset rather than per-task or mm,
291+ the batch scheduler can obtain the key information, memory
292+ pressure in a cpuset, with a single read, rather than having to
293+ query and accumulate results over all the (dynamically changing)
294+ set of tasks in the cpuset.
295+
296+A per-cpuset simple digital filter (requires a spinlock and 3 words
297+of data per-cpuset) is kept, and updated by any task attached to that
298+cpuset, if it enters the synchronous (direct) page reclaim code.
299+
300+A per-cpuset file provides an integer number representing the recent
301+(half-life of 10 seconds) rate of direct page reclaims caused by
302+the tasks in the cpuset, in units of reclaims attempted per second,
303+times 1000.
304+
305+
306+1.6 What is memory spread ?
307+---------------------------
308+There are two boolean flag files per cpuset that control where the
309+kernel allocates pages for the file system buffers and related in
310+kernel data structures. They are called 'cpuset.memory_spread_page' and
311+'cpuset.memory_spread_slab'.
312+
313+If the per-cpuset boolean flag file 'cpuset.memory_spread_page' is set, then
314+the kernel will spread the file system buffers (page cache) evenly
315+over all the nodes that the faulting task is allowed to use, instead
316+of preferring to put those pages on the node where the task is running.
317+
318+If the per-cpuset boolean flag file 'cpuset.memory_spread_slab' is set,
319+then the kernel will spread some file system related slab caches,
320+such as for inodes and dentries evenly over all the nodes that the
321+faulting task is allowed to use, instead of preferring to put those
322+pages on the node where the task is running.
323+
324+The setting of these flags does not affect anonymous data segment or
325+stack segment pages of a task.
326+
327+By default, both kinds of memory spreading are off, and memory
328+pages are allocated on the node local to where the task is running,
329+except perhaps as modified by the task's NUMA mempolicy or cpuset
330+configuration, so long as sufficient free memory pages are available.
331+
332+When new cpusets are created, they inherit the memory spread settings
333+of their parent.
334+
335+Setting memory spreading causes allocations for the affected page
336+or slab caches to ignore the task's NUMA mempolicy and be spread
337+instead. Tasks using mbind() or set_mempolicy() calls to set NUMA
338+mempolicies will not notice any change in these calls as a result of
339+their containing task's memory spread settings. If memory spreading
340+is turned off, then the currently specified NUMA mempolicy once again
341+applies to memory page allocations.
342+
343+Both 'cpuset.memory_spread_page' and 'cpuset.memory_spread_slab' are boolean flag
344+files. By default they contain "0", meaning that the feature is off
345+for that cpuset. If a "1" is written to that file, then that turns
346+the named feature on.
347+
348+The implementation is simple.
349+
350+Setting the flag 'cpuset.memory_spread_page' turns on a per-process flag
351+PFA_SPREAD_PAGE for each task that is in that cpuset or subsequently
352+joins that cpuset. The page allocation calls for the page cache
353+is modified to perform an inline check for this PFA_SPREAD_PAGE task
354+flag, and if set, a call to a new routine cpuset_mem_spread_node()
355+returns the node to prefer for the allocation.
356+
357+Similarly, setting 'cpuset.memory_spread_slab' turns on the flag
358+PFA_SPREAD_SLAB, and appropriately marked slab caches will allocate
359+pages from the node returned by cpuset_mem_spread_node().
360+
361+The cpuset_mem_spread_node() routine is also simple. It uses the
362+value of a per-task rotor cpuset_mem_spread_rotor to select the next
363+node in the current task's mems_allowed to prefer for the allocation.
364+
365+This memory placement policy is also known (in other contexts) as
366+round-robin or interleave.
367+
368+This policy can provide substantial improvements for jobs that need
369+to place thread local data on the corresponding node, but that need
370+to access large file system data sets that need to be spread across
371+the several nodes in the jobs cpuset in order to fit. Without this
372+policy, especially for jobs that might have one thread reading in the
373+data set, the memory allocation across the nodes in the jobs cpuset
374+can become very uneven.
375+
376+1.7 What is sched_load_balance ?
377+--------------------------------
378+
379+The kernel scheduler (kernel/sched/core.c) automatically load balances
380+tasks. If one CPU is underutilized, kernel code running on that
381+CPU will look for tasks on other more overloaded CPUs and move those
382+tasks to itself, within the constraints of such placement mechanisms
383+as cpusets and sched_setaffinity.
384+
385+The algorithmic cost of load balancing and its impact on key shared
386+kernel data structures such as the task list increases more than
387+linearly with the number of CPUs being balanced. So the scheduler
388+has support to partition the systems CPUs into a number of sched
389+domains such that it only load balances within each sched domain.
390+Each sched domain covers some subset of the CPUs in the system;
391+no two sched domains overlap; some CPUs might not be in any sched
392+domain and hence won't be load balanced.
393+
394+Put simply, it costs less to balance between two smaller sched domains
395+than one big one, but doing so means that overloads in one of the
396+two domains won't be load balanced to the other one.
397+
398+By default, there is one sched domain covering all CPUs, including those
399+marked isolated using the kernel boot time "isolcpus=" argument. However,
400+the isolated CPUs will not participate in load balancing, and will not
401+have tasks running on them unless explicitly assigned.
402+
403+This default load balancing across all CPUs is not well suited for
404+the following two situations:
405+
406+ 1) On large systems, load balancing across many CPUs is expensive.
407+ If the system is managed using cpusets to place independent jobs
408+ on separate sets of CPUs, full load balancing is unnecessary.
409+ 2) Systems supporting realtime on some CPUs need to minimize
410+ system overhead on those CPUs, including avoiding task load
411+ balancing if that is not needed.
412+
413+When the per-cpuset flag "cpuset.sched_load_balance" is enabled (the default
414+setting), it requests that all the CPUs in that cpusets allowed 'cpuset.cpus'
415+be contained in a single sched domain, ensuring that load balancing
416+can move a task (not otherwised pinned, as by sched_setaffinity)
417+from any CPU in that cpuset to any other.
418+
419+When the per-cpuset flag "cpuset.sched_load_balance" is disabled, then the
420+scheduler will avoid load balancing across the CPUs in that cpuset,
421+--except-- in so far as is necessary because some overlapping cpuset
422+has "sched_load_balance" enabled.
423+
424+So, for example, if the top cpuset has the flag "cpuset.sched_load_balance"
425+enabled, then the scheduler will have one sched domain covering all
426+CPUs, and the setting of the "cpuset.sched_load_balance" flag in any other
427+cpusets won't matter, as we're already fully load balancing.
428+
429+Therefore in the above two situations, the top cpuset flag
430+"cpuset.sched_load_balance" should be disabled, and only some of the smaller,
431+child cpusets have this flag enabled.
432+
433+When doing this, you don't usually want to leave any unpinned tasks in
434+the top cpuset that might use non-trivial amounts of CPU, as such tasks
435+may be artificially constrained to some subset of CPUs, depending on
436+the particulars of this flag setting in descendant cpusets. Even if
437+such a task could use spare CPU cycles in some other CPUs, the kernel
438+scheduler might not consider the possibility of load balancing that
439+task to that underused CPU.
440+
441+Of course, tasks pinned to a particular CPU can be left in a cpuset
442+that disables "cpuset.sched_load_balance" as those tasks aren't going anywhere
443+else anyway.
444+
445+There is an impedance mismatch here, between cpusets and sched domains.
446+Cpusets are hierarchical and nest. Sched domains are flat; they don't
447+overlap and each CPU is in at most one sched domain.
448+
449+It is necessary for sched domains to be flat because load balancing
450+across partially overlapping sets of CPUs would risk unstable dynamics
451+that would be beyond our understanding. So if each of two partially
452+overlapping cpusets enables the flag 'cpuset.sched_load_balance', then we
453+form a single sched domain that is a superset of both. We won't move
454+a task to a CPU outside its cpuset, but the scheduler load balancing
455+code might waste some compute cycles considering that possibility.
456+
457+This mismatch is why there is not a simple one-to-one relation
458+between which cpusets have the flag "cpuset.sched_load_balance" enabled,
459+and the sched domain configuration. If a cpuset enables the flag, it
460+will get balancing across all its CPUs, but if it disables the flag,
461+it will only be assured of no load balancing if no other overlapping
462+cpuset enables the flag.
463+
464+If two cpusets have partially overlapping 'cpuset.cpus' allowed, and only
465+one of them has this flag enabled, then the other may find its
466+tasks only partially load balanced, just on the overlapping CPUs.
467+This is just the general case of the top_cpuset example given a few
468+paragraphs above. In the general case, as in the top cpuset case,
469+don't leave tasks that might use non-trivial amounts of CPU in
470+such partially load balanced cpusets, as they may be artificially
471+constrained to some subset of the CPUs allowed to them, for lack of
472+load balancing to the other CPUs.
473+
474+CPUs in "cpuset.isolcpus" were excluded from load balancing by the
475+isolcpus= kernel boot option, and will never be load balanced regardless
476+of the value of "cpuset.sched_load_balance" in any cpuset.
477+
478+1.7.1 sched_load_balance implementation details.
479+------------------------------------------------
480+
481+The per-cpuset flag 'cpuset.sched_load_balance' defaults to enabled (contrary
482+to most cpuset flags.) When enabled for a cpuset, the kernel will
483+ensure that it can load balance across all the CPUs in that cpuset
484+(makes sure that all the CPUs in the cpus_allowed of that cpuset are
485+in the same sched domain.)
486+
487+If two overlapping cpusets both have 'cpuset.sched_load_balance' enabled,
488+then they will be (must be) both in the same sched domain.
489+
490+If, as is the default, the top cpuset has 'cpuset.sched_load_balance' enabled,
491+then by the above that means there is a single sched domain covering
492+the whole system, regardless of any other cpuset settings.
493+
494+The kernel commits to user space that it will avoid load balancing
495+where it can. It will pick as fine a granularity partition of sched
496+domains as it can while still providing load balancing for any set
497+of CPUs allowed to a cpuset having 'cpuset.sched_load_balance' enabled.
498+
499+The internal kernel cpuset to scheduler interface passes from the
500+cpuset code to the scheduler code a partition of the load balanced
501+CPUs in the system. This partition is a set of subsets (represented
502+as an array of struct cpumask) of CPUs, pairwise disjoint, that cover
503+all the CPUs that must be load balanced.
504+
505+The cpuset code builds a new such partition and passes it to the
506+scheduler sched domain setup code, to have the sched domains rebuilt
507+as necessary, whenever:
508+
509+ - the 'cpuset.sched_load_balance' flag of a cpuset with non-empty CPUs changes,
510+ - or CPUs come or go from a cpuset with this flag enabled,
511+ - or 'cpuset.sched_relax_domain_level' value of a cpuset with non-empty CPUs
512+ and with this flag enabled changes,
513+ - or a cpuset with non-empty CPUs and with this flag enabled is removed,
514+ - or a cpu is offlined/onlined.
515+
516+This partition exactly defines what sched domains the scheduler should
517+setup - one sched domain for each element (struct cpumask) in the
518+partition.
519+
520+The scheduler remembers the currently active sched domain partitions.
521+When the scheduler routine partition_sched_domains() is invoked from
522+the cpuset code to update these sched domains, it compares the new
523+partition requested with the current, and updates its sched domains,
524+removing the old and adding the new, for each change.
525+
526+
527+1.8 What is sched_relax_domain_level ?
528+--------------------------------------
529+
530+In sched domain, the scheduler migrates tasks in 2 ways; periodic load
531+balance on tick, and at time of some schedule events.
532+
533+When a task is woken up, scheduler try to move the task on idle CPU.
534+For example, if a task A running on CPU X activates another task B
535+on the same CPU X, and if CPU Y is X's sibling and performing idle,
536+then scheduler migrate task B to CPU Y so that task B can start on
537+CPU Y without waiting task A on CPU X.
538+
539+And if a CPU run out of tasks in its runqueue, the CPU try to pull
540+extra tasks from other busy CPUs to help them before it is going to
541+be idle.
542+
543+Of course it takes some searching cost to find movable tasks and/or
544+idle CPUs, the scheduler might not search all CPUs in the domain
545+every time. In fact, in some architectures, the searching ranges on
546+events are limited in the same socket or node where the CPU locates,
547+while the load balance on tick searches all.
548+
549+For example, assume CPU Z is relatively far from CPU X. Even if CPU Z
550+is idle while CPU X and the siblings are busy, scheduler can't migrate
551+woken task B from X to Z since it is out of its searching range.
552+As the result, task B on CPU X need to wait task A or wait load balance
553+on the next tick. For some applications in special situation, waiting
554+1 tick may be too long.
555+
556+The 'cpuset.sched_relax_domain_level' file allows you to request changing
557+this searching range as you like. This file takes int value which
558+indicates size of searching range in levels ideally as follows,
559+otherwise initial value -1 that indicates the cpuset has no request.
560+
561+====== ===========================================================
562+ -1 no request. use system default or follow request of others.
563+ 0 no search.
564+ 1 search siblings (hyperthreads in a core).
565+ 2 search cores in a package.
566+ 3 search cpus in a node [= system wide on non-NUMA system]
567+ 4 search nodes in a chunk of node [on NUMA system]
568+ 5 search system wide [on NUMA system]
569+====== ===========================================================
570+
571+The system default is architecture dependent. The system default
572+can be changed using the relax_domain_level= boot parameter.
573+
574+This file is per-cpuset and affect the sched domain where the cpuset
575+belongs to. Therefore if the flag 'cpuset.sched_load_balance' of a cpuset
576+is disabled, then 'cpuset.sched_relax_domain_level' have no effect since
577+there is no sched domain belonging the cpuset.
578+
579+If multiple cpusets are overlapping and hence they form a single sched
580+domain, the largest value among those is used. Be careful, if one
581+requests 0 and others are -1 then 0 is used.
582+
583+Note that modifying this file will have both good and bad effects,
584+and whether it is acceptable or not depends on your situation.
585+Don't modify this file if you are not sure.
586+
587+If your situation is:
588+
589+ - The migration costs between each cpu can be assumed considerably
590+ small(for you) due to your special application's behavior or
591+ special hardware support for CPU cache etc.
592+ - The searching cost doesn't have impact(for you) or you can make
593+ the searching cost enough small by managing cpuset to compact etc.
594+ - The latency is required even it sacrifices cache hit rate etc.
595+ then increasing 'sched_relax_domain_level' would benefit you.
596+
597+
598+1.9 How do I use cpusets ?
599+--------------------------
600+
601+In order to minimize the impact of cpusets on critical kernel
602+code, such as the scheduler, and due to the fact that the kernel
603+does not support one task updating the memory placement of another
604+task directly, the impact on a task of changing its cpuset CPU
605+or Memory Node placement, or of changing to which cpuset a task
606+is attached, is subtle.
607+
608+If a cpuset has its Memory Nodes modified, then for each task attached
609+to that cpuset, the next time that the kernel attempts to allocate
610+a page of memory for that task, the kernel will notice the change
611+in the task's cpuset, and update its per-task memory placement to
612+remain within the new cpusets memory placement. If the task was using
613+mempolicy MPOL_BIND, and the nodes to which it was bound overlap with
614+its new cpuset, then the task will continue to use whatever subset
615+of MPOL_BIND nodes are still allowed in the new cpuset. If the task
616+was using MPOL_BIND and now none of its MPOL_BIND nodes are allowed
617+in the new cpuset, then the task will be essentially treated as if it
618+was MPOL_BIND bound to the new cpuset (even though its NUMA placement,
619+as queried by get_mempolicy(), doesn't change). If a task is moved
620+from one cpuset to another, then the kernel will adjust the task's
621+memory placement, as above, the next time that the kernel attempts
622+to allocate a page of memory for that task.
623+
624+If a cpuset has its 'cpuset.cpus' modified, then each task in that cpuset
625+will have its allowed CPU placement changed immediately. Similarly,
626+if a task's pid is written to another cpuset's 'tasks' file, then its
627+allowed CPU placement is changed immediately. If such a task had been
628+bound to some subset of its cpuset using the sched_setaffinity() call,
629+the task will be allowed to run on any CPU allowed in its new cpuset,
630+negating the effect of the prior sched_setaffinity() call.
631+
632+In summary, the memory placement of a task whose cpuset is changed is
633+updated by the kernel, on the next allocation of a page for that task,
634+and the processor placement is updated immediately.
635+
636+Normally, once a page is allocated (given a physical page
637+of main memory) then that page stays on whatever node it
638+was allocated, so long as it remains allocated, even if the
639+cpusets memory placement policy 'cpuset.mems' subsequently changes.
640+If the cpuset flag file 'cpuset.memory_migrate' is set true, then when
641+tasks are attached to that cpuset, any pages that task had
642+allocated to it on nodes in its previous cpuset are migrated
643+to the task's new cpuset. The relative placement of the page within
644+the cpuset is preserved during these migration operations if possible.
645+For example if the page was on the second valid node of the prior cpuset
646+then the page will be placed on the second valid node of the new cpuset.
647+
648+Also if 'cpuset.memory_migrate' is set true, then if that cpuset's
649+'cpuset.mems' file is modified, pages allocated to tasks in that
650+cpuset, that were on nodes in the previous setting of 'cpuset.mems',
651+will be moved to nodes in the new setting of 'mems.'
652+Pages that were not in the task's prior cpuset, or in the cpuset's
653+prior 'cpuset.mems' setting, will not be moved.
654+
655+There is an exception to the above. If hotplug functionality is used
656+to remove all the CPUs that are currently assigned to a cpuset,
657+then all the tasks in that cpuset will be moved to the nearest ancestor
658+with non-empty cpus. But the moving of some (or all) tasks might fail if
659+cpuset is bound with another cgroup subsystem which has some restrictions
660+on task attaching. In this failing case, those tasks will stay
661+in the original cpuset, and the kernel will automatically update
662+their cpus_allowed to allow all online CPUs. When memory hotplug
663+functionality for removing Memory Nodes is available, a similar exception
664+is expected to apply there as well. In general, the kernel prefers to
665+violate cpuset placement, over starving a task that has had all
666+its allowed CPUs or Memory Nodes taken offline.
667+
668+There is a second exception to the above. GFP_ATOMIC requests are
669+kernel internal allocations that must be satisfied, immediately.
670+The kernel may drop some request, in rare cases even panic, if a
671+GFP_ATOMIC alloc fails. If the request cannot be satisfied within
672+the current task's cpuset, then we relax the cpuset, and look for
673+memory anywhere we can find it. It's better to violate the cpuset
674+than stress the kernel.
675+
676+To start a new job that is to be contained within a cpuset, the steps are:
677+
678+ 1) mkdir /sys/fs/cgroup/cpuset
679+ 2) mount -t cgroup -ocpuset cpuset /sys/fs/cgroup/cpuset
680+ 3) Create the new cpuset by doing mkdir's and write's (or echo's) in
681+ the /sys/fs/cgroup/cpuset virtual file system.
682+ 4) Start a task that will be the "founding father" of the new job.
683+ 5) Attach that task to the new cpuset by writing its pid to the
684+ /sys/fs/cgroup/cpuset tasks file for that cpuset.
685+ 6) fork, exec or clone the job tasks from this founding father task.
686+
687+For example, the following sequence of commands will setup a cpuset
688+named "Charlie", containing just CPUs 2 and 3, and Memory Node 1,
689+and then start a subshell 'sh' in that cpuset::
690+
691+ mount -t cgroup -ocpuset cpuset /sys/fs/cgroup/cpuset
692+ cd /sys/fs/cgroup/cpuset
693+ mkdir Charlie
694+ cd Charlie
695+ /bin/echo 2-3 > cpuset.cpus
696+ /bin/echo 1 > cpuset.mems
697+ /bin/echo $$ > tasks
698+ sh
699+ # The subshell 'sh' is now running in cpuset Charlie
700+ # The next line should display '/Charlie'
701+ cat /proc/self/cpuset
702+
703+There are ways to query or modify cpusets:
704+
705+ - via the cpuset file system directly, using the various cd, mkdir, echo,
706+ cat, rmdir commands from the shell, or their equivalent from C.
707+ - via the C library libcpuset.
708+ - via the C library libcgroup.
709+ (http://sourceforge.net/projects/libcg/)
710+ - via the python application cset.
711+ (http://code.google.com/p/cpuset/)
712+
713+The sched_setaffinity calls can also be done at the shell prompt using
714+SGI's runon or Robert Love's taskset. The mbind and set_mempolicy
715+calls can be done at the shell prompt using the numactl command
716+(part of Andi Kleen's numa package).
717+
718+2. Usage Examples and Syntax
719+============================
720+
721+2.1 Basic Usage
722+---------------
723+
724+Creating, modifying, using the cpusets can be done through the cpuset
725+virtual filesystem.
726+
727+To mount it, type:
728+# mount -t cgroup -o cpuset cpuset /sys/fs/cgroup/cpuset
729+
730+Then under /sys/fs/cgroup/cpuset you can find a tree that corresponds to the
731+tree of the cpusets in the system. For instance, /sys/fs/cgroup/cpuset
732+is the cpuset that holds the whole system.
733+
734+If you want to create a new cpuset under /sys/fs/cgroup/cpuset::
735+
736+ # cd /sys/fs/cgroup/cpuset
737+ # mkdir my_cpuset
738+
739+Now you want to do something with this cpuset::
740+
741+ # cd my_cpuset
742+
743+In this directory you can find several files::
744+
745+ # ls
746+ cgroup.clone_children cpuset.memory_pressure
747+ cgroup.event_control cpuset.memory_spread_page
748+ cgroup.procs cpuset.memory_spread_slab
749+ cpuset.cpu_exclusive cpuset.mems
750+ cpuset.cpus cpuset.sched_load_balance
751+ cpuset.mem_exclusive cpuset.sched_relax_domain_level
752+ cpuset.mem_hardwall notify_on_release
753+ cpuset.memory_migrate tasks
754+
755+Reading them will give you information about the state of this cpuset:
756+the CPUs and Memory Nodes it can use, the processes that are using
757+it, its properties. By writing to these files you can manipulate
758+the cpuset.
759+
760+Set some flags::
761+
762+ # /bin/echo 1 > cpuset.cpu_exclusive
763+
764+Add some cpus::
765+
766+ # /bin/echo 0-7 > cpuset.cpus
767+
768+Add some mems::
769+
770+ # /bin/echo 0-7 > cpuset.mems
771+
772+Now attach your shell to this cpuset::
773+
774+ # /bin/echo $$ > tasks
775+
776+You can also create cpusets inside your cpuset by using mkdir in this
777+directory::
778+
779+ # mkdir my_sub_cs
780+
781+To remove a cpuset, just use rmdir::
782+
783+ # rmdir my_sub_cs
784+
785+This will fail if the cpuset is in use (has cpusets inside, or has
786+processes attached).
787+
788+Note that for legacy reasons, the "cpuset" filesystem exists as a
789+wrapper around the cgroup filesystem.
790+
791+The command::
792+
793+ mount -t cpuset X /sys/fs/cgroup/cpuset
794+
795+is equivalent to::
796+
797+ mount -t cgroup -ocpuset,noprefix X /sys/fs/cgroup/cpuset
798+ echo "/sbin/cpuset_release_agent" > /sys/fs/cgroup/cpuset/release_agent
799+
800+2.2 Adding/removing cpus
801+------------------------
802+
803+This is the syntax to use when writing in the cpus or mems files
804+in cpuset directories::
805+
806+ # /bin/echo 1-4 > cpuset.cpus -> set cpus list to cpus 1,2,3,4
807+ # /bin/echo 1,2,3,4 > cpuset.cpus -> set cpus list to cpus 1,2,3,4
808+
809+To add a CPU to a cpuset, write the new list of CPUs including the
810+CPU to be added. To add 6 to the above cpuset::
811+
812+ # /bin/echo 1-4,6 > cpuset.cpus -> set cpus list to cpus 1,2,3,4,6
813+
814+Similarly to remove a CPU from a cpuset, write the new list of CPUs
815+without the CPU to be removed.
816+
817+To remove all the CPUs::
818+
819+ # /bin/echo "" > cpuset.cpus -> clear cpus list
820+
821+2.3 Setting flags
822+-----------------
823+
824+The syntax is very simple::
825+
826+ # /bin/echo 1 > cpuset.cpu_exclusive -> set flag 'cpuset.cpu_exclusive'
827+ # /bin/echo 0 > cpuset.cpu_exclusive -> unset flag 'cpuset.cpu_exclusive'
828+
829+2.4 Attaching processes
830+-----------------------
831+
832+::
833+
834+ # /bin/echo PID > tasks
835+
836+Note that it is PID, not PIDs. You can only attach ONE task at a time.
837+If you have several tasks to attach, you have to do it one after another::
838+
839+ # /bin/echo PID1 > tasks
840+ # /bin/echo PID2 > tasks
841+ ...
842+ # /bin/echo PIDn > tasks
843+
844+
845+3. Questions
846+============
847+
848+Q:
849+ what's up with this '/bin/echo' ?
850+
851+A:
852+ bash's builtin 'echo' command does not check calls to write() against
853+ errors. If you use it in the cpuset file system, you won't be
854+ able to tell whether a command succeeded or failed.
855+
856+Q:
857+ When I attach processes, only the first of the line gets really attached !
858+
859+A:
860+ We can only return one error code per call to write(). So you should also
861+ put only ONE pid.
862+
863+4. Contact
864+==========
865+
866+Web: http://www.bullopensource.org/cpuset
Documentation/admin-guide/cgroup-v1/devices.rst+132−0
@@ -0,0 +1,132 @@
1+===========================
2+Device Whitelist Controller
3+===========================
4+
5+1. Description
6+==============
7+
8+Implement a cgroup to track and enforce open and mknod restrictions
9+on device files. A device cgroup associates a device access
10+whitelist with each cgroup. A whitelist entry has 4 fields.
11+'type' is a (all), c (char), or b (block). 'all' means it applies
12+to all types and all major and minor numbers. Major and minor are
13+either an integer or * for all. Access is a composition of r
14+(read), w (write), and m (mknod).
15+
16+The root device cgroup starts with rwm to 'all'. A child device
17+cgroup gets a copy of the parent. Administrators can then remove
18+devices from the whitelist or add new entries. A child cgroup can
19+never receive a device access which is denied by its parent.
20+
21+2. User Interface
22+=================
23+
24+An entry is added using devices.allow, and removed using
25+devices.deny. For instance::
26+
27+ echo 'c 1:3 mr' > /sys/fs/cgroup/1/devices.allow
28+
29+allows cgroup 1 to read and mknod the device usually known as
30+/dev/null. Doing::
31+
32+ echo a > /sys/fs/cgroup/1/devices.deny
33+
34+will remove the default 'a *:* rwm' entry. Doing::
35+
36+ echo a > /sys/fs/cgroup/1/devices.allow
37+
38+will add the 'a *:* rwm' entry to the whitelist.
39+
40+3. Security
41+===========
42+
43+Any task can move itself between cgroups. This clearly won't
44+suffice, but we can decide the best way to adequately restrict
45+movement as people get some experience with this. We may just want
46+to require CAP_SYS_ADMIN, which at least is a separate bit from
47+CAP_MKNOD. We may want to just refuse moving to a cgroup which
48+isn't a descendant of the current one. Or we may want to use
49+CAP_MAC_ADMIN, since we really are trying to lock down root.
50+
51+CAP_SYS_ADMIN is needed to modify the whitelist or move another
52+task to a new cgroup. (Again we'll probably want to change that).
53+
54+A cgroup may not be granted more permissions than the cgroup's
55+parent has.
56+
57+4. Hierarchy
58+============
59+
60+device cgroups maintain hierarchy by making sure a cgroup never has more
61+access permissions than its parent. Every time an entry is written to
62+a cgroup's devices.deny file, all its children will have that entry removed
63+from their whitelist and all the locally set whitelist entries will be
64+re-evaluated. In case one of the locally set whitelist entries would provide
65+more access than the cgroup's parent, it'll be removed from the whitelist.
66+
67+Example::
68+
69+ A
70+ / \
71+ B
72+
73+ group behavior exceptions
74+ A allow "b 8:* rwm", "c 116:1 rw"
75+ B deny "c 1:3 rwm", "c 116:2 rwm", "b 3:* rwm"
76+
77+If a device is denied in group A::
78+
79+ # echo "c 116:* r" > A/devices.deny
80+
81+it'll propagate down and after revalidating B's entries, the whitelist entry
82+"c 116:2 rwm" will be removed::
83+
84+ group whitelist entries denied devices
85+ A all "b 8:* rwm", "c 116:* rw"
86+ B "c 1:3 rwm", "b 3:* rwm" all the rest
87+
88+In case parent's exceptions change and local exceptions are not allowed
89+anymore, they'll be deleted.
90+
91+Notice that new whitelist entries will not be propagated::
92+
93+ A
94+ / \
95+ B
96+
97+ group whitelist entries denied devices
98+ A "c 1:3 rwm", "c 1:5 r" all the rest
99+ B "c 1:3 rwm", "c 1:5 r" all the rest
100+
101+when adding ``c *:3 rwm``::
102+
103+ # echo "c *:3 rwm" >A/devices.allow
104+
105+the result::
106+
107+ group whitelist entries denied devices
108+ A "c *:3 rwm", "c 1:5 r" all the rest
109+ B "c 1:3 rwm", "c 1:5 r" all the rest
110+
111+but now it'll be possible to add new entries to B::
112+
113+ # echo "c 2:3 rwm" >B/devices.allow
114+ # echo "c 50:3 r" >B/devices.allow
115+
116+or even::
117+
118+ # echo "c *:3 rwm" >B/devices.allow
119+
120+Allowing or denying all by writing 'a' to devices.allow or devices.deny will
121+not be possible once the device cgroups has children.
122+
123+4.1 Hierarchy (internal implementation)
124+---------------------------------------
125+
126+device cgroups is implemented internally using a behavior (ALLOW, DENY) and a
127+list of exceptions. The internal state is controlled using the same user
128+interface to preserve compatibility with the previous whitelist-only
129+implementation. Removal or addition of exceptions that will reduce the access
130+to devices will be propagated down the hierarchy.
131+For every propagated exception, the effective rules will be re-evaluated based
132+on current parent's access rules.
Documentation/admin-guide/cgroup-v1/freezer-subsystem.rst+127−0
@@ -0,0 +1,127 @@
1+==============
2+Cgroup Freezer
3+==============
4+
5+The cgroup freezer is useful to batch job management system which start
6+and stop sets of tasks in order to schedule the resources of a machine
7+according to the desires of a system administrator. This sort of program
8+is often used on HPC clusters to schedule access to the cluster as a
9+whole. The cgroup freezer uses cgroups to describe the set of tasks to
10+be started/stopped by the batch job management system. It also provides
11+a means to start and stop the tasks composing the job.
12+
13+The cgroup freezer will also be useful for checkpointing running groups
14+of tasks. The freezer allows the checkpoint code to obtain a consistent
15+image of the tasks by attempting to force the tasks in a cgroup into a
16+quiescent state. Once the tasks are quiescent another task can
17+walk /proc or invoke a kernel interface to gather information about the
18+quiesced tasks. Checkpointed tasks can be restarted later should a
19+recoverable error occur. This also allows the checkpointed tasks to be
20+migrated between nodes in a cluster by copying the gathered information
21+to another node and restarting the tasks there.
22+
23+Sequences of SIGSTOP and SIGCONT are not always sufficient for stopping
24+and resuming tasks in userspace. Both of these signals are observable
25+from within the tasks we wish to freeze. While SIGSTOP cannot be caught,
26+blocked, or ignored it can be seen by waiting or ptracing parent tasks.
27+SIGCONT is especially unsuitable since it can be caught by the task. Any
28+programs designed to watch for SIGSTOP and SIGCONT could be broken by
29+attempting to use SIGSTOP and SIGCONT to stop and resume tasks. We can
30+demonstrate this problem using nested bash shells::
31+
32+ $ echo $$
33+ 16644
34+ $ bash
35+ $ echo $$
36+ 16690
37+
38+ From a second, unrelated bash shell:
39+ $ kill -SIGSTOP 16690
40+ $ kill -SIGCONT 16690
41+
42+ <at this point 16690 exits and causes 16644 to exit too>
43+
44+This happens because bash can observe both signals and choose how it
45+responds to them.
46+
47+Another example of a program which catches and responds to these
48+signals is gdb. In fact any program designed to use ptrace is likely to
49+have a problem with this method of stopping and resuming tasks.
50+
51+In contrast, the cgroup freezer uses the kernel freezer code to
52+prevent the freeze/unfreeze cycle from becoming visible to the tasks
53+being frozen. This allows the bash example above and gdb to run as
54+expected.
55+
56+The cgroup freezer is hierarchical. Freezing a cgroup freezes all
57+tasks belonging to the cgroup and all its descendant cgroups. Each
58+cgroup has its own state (self-state) and the state inherited from the
59+parent (parent-state). Iff both states are THAWED, the cgroup is
60+THAWED.
61+
62+The following cgroupfs files are created by cgroup freezer.
63+
64+* freezer.state: Read-write.
65+
66+ When read, returns the effective state of the cgroup - "THAWED",
67+ "FREEZING" or "FROZEN". This is the combined self and parent-states.
68+ If any is freezing, the cgroup is freezing (FREEZING or FROZEN).
69+
70+ FREEZING cgroup transitions into FROZEN state when all tasks
71+ belonging to the cgroup and its descendants become frozen. Note that
72+ a cgroup reverts to FREEZING from FROZEN after a new task is added
73+ to the cgroup or one of its descendant cgroups until the new task is
74+ frozen.
75+
76+ When written, sets the self-state of the cgroup. Two values are
77+ allowed - "FROZEN" and "THAWED". If FROZEN is written, the cgroup,
78+ if not already freezing, enters FREEZING state along with all its
79+ descendant cgroups.
80+
81+ If THAWED is written, the self-state of the cgroup is changed to
82+ THAWED. Note that the effective state may not change to THAWED if
83+ the parent-state is still freezing. If a cgroup's effective state
84+ becomes THAWED, all its descendants which are freezing because of
85+ the cgroup also leave the freezing state.
86+
87+* freezer.self_freezing: Read only.
88+
89+ Shows the self-state. 0 if the self-state is THAWED; otherwise, 1.
90+ This value is 1 iff the last write to freezer.state was "FROZEN".
91+
92+* freezer.parent_freezing: Read only.
93+
94+ Shows the parent-state. 0 if none of the cgroup's ancestors is
95+ frozen; otherwise, 1.
96+
97+The root cgroup is non-freezable and the above interface files don't
98+exist.
99+
100+* Examples of usage::
101+
102+ # mkdir /sys/fs/cgroup/freezer
103+ # mount -t cgroup -ofreezer freezer /sys/fs/cgroup/freezer
104+ # mkdir /sys/fs/cgroup/freezer/0
105+ # echo $some_pid > /sys/fs/cgroup/freezer/0/tasks
106+
107+to get status of the freezer subsystem::
108+
109+ # cat /sys/fs/cgroup/freezer/0/freezer.state
110+ THAWED
111+
112+to freeze all tasks in the container::
113+
114+ # echo FROZEN > /sys/fs/cgroup/freezer/0/freezer.state
115+ # cat /sys/fs/cgroup/freezer/0/freezer.state
116+ FREEZING
117+ # cat /sys/fs/cgroup/freezer/0/freezer.state
118+ FROZEN
119+
120+to unfreeze all tasks in the container::
121+
122+ # echo THAWED > /sys/fs/cgroup/freezer/0/freezer.state
123+ # cat /sys/fs/cgroup/freezer/0/freezer.state
124+ THAWED
125+
126+This is the basic mechanism which should do the right thing for user space task
127+in a simple scenario.
Documentation/admin-guide/cgroup-v1/hugetlb.rst+50−0
@@ -0,0 +1,50 @@
1+==================
2+HugeTLB Controller
3+==================
4+
5+The HugeTLB controller allows to limit the HugeTLB usage per control group and
6+enforces the controller limit during page fault. Since HugeTLB doesn't
7+support page reclaim, enforcing the limit at page fault time implies that,
8+the application will get SIGBUS signal if it tries to access HugeTLB pages
9+beyond its limit. This requires the application to know beforehand how much
10+HugeTLB pages it would require for its use.
11+
12+HugeTLB controller can be created by first mounting the cgroup filesystem.
13+
14+# mount -t cgroup -o hugetlb none /sys/fs/cgroup
15+
16+With the above step, the initial or the parent HugeTLB group becomes
17+visible at /sys/fs/cgroup. At bootup, this group includes all the tasks in
18+the system. /sys/fs/cgroup/tasks lists the tasks in this cgroup.
19+
20+New groups can be created under the parent group /sys/fs/cgroup::
21+
22+ # cd /sys/fs/cgroup
23+ # mkdir g1
24+ # echo $$ > g1/tasks
25+
26+The above steps create a new group g1 and move the current shell
27+process (bash) into it.
28+
29+Brief summary of control files::
30+
31+ hugetlb.<hugepagesize>.limit_in_bytes # set/show limit of "hugepagesize" hugetlb usage
32+ hugetlb.<hugepagesize>.max_usage_in_bytes # show max "hugepagesize" hugetlb usage recorded
33+ hugetlb.<hugepagesize>.usage_in_bytes # show current usage for "hugepagesize" hugetlb
34+ hugetlb.<hugepagesize>.failcnt # show the number of allocation failure due to HugeTLB limit
35+
36+For a system supporting three hugepage sizes (64k, 32M and 1G), the control
37+files include::
38+
39+ hugetlb.1GB.limit_in_bytes
40+ hugetlb.1GB.max_usage_in_bytes
41+ hugetlb.1GB.usage_in_bytes
42+ hugetlb.1GB.failcnt
43+ hugetlb.64KB.limit_in_bytes
44+ hugetlb.64KB.max_usage_in_bytes
45+ hugetlb.64KB.usage_in_bytes
46+ hugetlb.64KB.failcnt
47+ hugetlb.32MB.limit_in_bytes
48+ hugetlb.32MB.max_usage_in_bytes
49+ hugetlb.32MB.usage_in_bytes
50+ hugetlb.32MB.failcnt
Documentation/admin-guide/cgroup-v1/index.rst+28−0
@@ -0,0 +1,28 @@
1+========================
2+Control Groups version 1
3+========================
4+
5+.. toctree::
6+ :maxdepth: 1
7+
8+ cgroups
9+
10+ blkio-controller
11+ cpuacct
12+ cpusets
13+ devices
14+ freezer-subsystem
15+ hugetlb
16+ memcg_test
17+ memory
18+ net_cls
19+ net_prio
20+ pids
21+ rdma
22+
23+.. only:: subproject and html
24+
25+ Indices
26+ =======
27+
28+ * :ref:`genindex`
Documentation/admin-guide/cgroup-v1/memcg_test.rst+355−0
@@ -0,0 +1,355 @@
1+=====================================================
2+Memory Resource Controller(Memcg) Implementation Memo
3+=====================================================
4+
5+Last Updated: 2010/2
6+
7+Base Kernel Version: based on 2.6.33-rc7-mm(candidate for 34).
8+
9+Because VM is getting complex (one of reasons is memcg...), memcg's behavior
10+is complex. This is a document for memcg's internal behavior.
11+Please note that implementation details can be changed.
12+
13+(*) Topics on API should be in Documentation/admin-guide/cgroup-v1/memory.rst)
14+
15+0. How to record usage ?
16+========================
17+
18+ 2 objects are used.
19+
20+ page_cgroup ....an object per page.
21+
22+ Allocated at boot or memory hotplug. Freed at memory hot removal.
23+
24+ swap_cgroup ... an entry per swp_entry.
25+
26+ Allocated at swapon(). Freed at swapoff().
27+
28+ The page_cgroup has USED bit and double count against a page_cgroup never
29+ occurs. swap_cgroup is used only when a charged page is swapped-out.
30+
31+1. Charge
32+=========
33+
34+ a page/swp_entry may be charged (usage += PAGE_SIZE) at
35+
36+ mem_cgroup_try_charge()
37+
38+2. Uncharge
39+===========
40+
41+ a page/swp_entry may be uncharged (usage -= PAGE_SIZE) by
42+
43+ mem_cgroup_uncharge()
44+ Called when a page's refcount goes down to 0.
45+
46+ mem_cgroup_uncharge_swap()
47+ Called when swp_entry's refcnt goes down to 0. A charge against swap
48+ disappears.
49+
50+3. charge-commit-cancel
51+=======================
52+
53+ Memcg pages are charged in two steps:
54+
55+ - mem_cgroup_try_charge()
56+ - mem_cgroup_commit_charge() or mem_cgroup_cancel_charge()
57+
58+ At try_charge(), there are no flags to say "this page is charged".
59+ at this point, usage += PAGE_SIZE.
60+
61+ At commit(), the page is associated with the memcg.
62+
63+ At cancel(), simply usage -= PAGE_SIZE.
64+
65+Under below explanation, we assume CONFIG_MEM_RES_CTRL_SWAP=y.
66+
67+4. Anonymous
68+============
69+
70+ Anonymous page is newly allocated at
71+ - page fault into MAP_ANONYMOUS mapping.
72+ - Copy-On-Write.
73+
74+ 4.1 Swap-in.
75+ At swap-in, the page is taken from swap-cache. There are 2 cases.
76+
77+ (a) If the SwapCache is newly allocated and read, it has no charges.
78+ (b) If the SwapCache has been mapped by processes, it has been
79+ charged already.
80+
81+ 4.2 Swap-out.
82+ At swap-out, typical state transition is below.
83+
84+ (a) add to swap cache. (marked as SwapCache)
85+ swp_entry's refcnt += 1.
86+ (b) fully unmapped.
87+ swp_entry's refcnt += # of ptes.
88+ (c) write back to swap.
89+ (d) delete from swap cache. (remove from SwapCache)
90+ swp_entry's refcnt -= 1.
91+
92+
93+ Finally, at task exit,
94+ (e) zap_pte() is called and swp_entry's refcnt -=1 -> 0.
95+
96+5. Page Cache
97+=============
98+
99+ Page Cache is charged at
100+ - add_to_page_cache_locked().
101+
102+ The logic is very clear. (About migration, see below)
103+
104+ Note:
105+ __remove_from_page_cache() is called by remove_from_page_cache()
106+ and __remove_mapping().
107+
108+6. Shmem(tmpfs) Page Cache
109+===========================
110+
111+ The best way to understand shmem's page state transition is to read
112+ mm/shmem.c.
113+
114+ But brief explanation of the behavior of memcg around shmem will be
115+ helpful to understand the logic.
116+
117+ Shmem's page (just leaf page, not direct/indirect block) can be on
118+
119+ - radix-tree of shmem's inode.
120+ - SwapCache.
121+ - Both on radix-tree and SwapCache. This happens at swap-in
122+ and swap-out,
123+
124+ It's charged when...
125+
126+ - A new page is added to shmem's radix-tree.
127+ - A swp page is read. (move a charge from swap_cgroup to page_cgroup)
128+
129+7. Page Migration
130+=================
131+
132+ mem_cgroup_migrate()
133+
134+8. LRU
135+======
136+ Each memcg has its own private LRU. Now, its handling is under global
137+ VM's control (means that it's handled under global pgdat->lru_lock).
138+ Almost all routines around memcg's LRU is called by global LRU's
139+ list management functions under pgdat->lru_lock.
140+
141+ A special function is mem_cgroup_isolate_pages(). This scans
142+ memcg's private LRU and call __isolate_lru_page() to extract a page
143+ from LRU.
144+
145+ (By __isolate_lru_page(), the page is removed from both of global and
146+ private LRU.)
147+
148+
149+9. Typical Tests.
150+=================
151+
152+ Tests for racy cases.
153+
154+9.1 Small limit to memcg.
155+-------------------------
156+
157+ When you do test to do racy case, it's good test to set memcg's limit
158+ to be very small rather than GB. Many races found in the test under
159+ xKB or xxMB limits.
160+
161+ (Memory behavior under GB and Memory behavior under MB shows very
162+ different situation.)
163+
164+9.2 Shmem
165+---------
166+
167+ Historically, memcg's shmem handling was poor and we saw some amount
168+ of troubles here. This is because shmem is page-cache but can be
169+ SwapCache. Test with shmem/tmpfs is always good test.
170+
171+9.3 Migration
172+-------------
173+
174+ For NUMA, migration is an another special case. To do easy test, cpuset
175+ is useful. Following is a sample script to do migration::
176+
177+ mount -t cgroup -o cpuset none /opt/cpuset
178+
179+ mkdir /opt/cpuset/01
180+ echo 1 > /opt/cpuset/01/cpuset.cpus
181+ echo 0 > /opt/cpuset/01/cpuset.mems
182+ echo 1 > /opt/cpuset/01/cpuset.memory_migrate
183+ mkdir /opt/cpuset/02
184+ echo 1 > /opt/cpuset/02/cpuset.cpus
185+ echo 1 > /opt/cpuset/02/cpuset.mems
186+ echo 1 > /opt/cpuset/02/cpuset.memory_migrate
187+
188+ In above set, when you moves a task from 01 to 02, page migration to
189+ node 0 to node 1 will occur. Following is a script to migrate all
190+ under cpuset.::
191+
192+ --
193+ move_task()
194+ {
195+ for pid in $1
196+ do
197+ /bin/echo $pid >$2/tasks 2>/dev/null
198+ echo -n $pid
199+ echo -n " "
200+ done
201+ echo END
202+ }
203+
204+ G1_TASK=`cat ${G1}/tasks`
205+ G2_TASK=`cat ${G2}/tasks`
206+ move_task "${G1_TASK}" ${G2} &
207+ --
208+
209+9.4 Memory hotplug
210+------------------
211+
212+ memory hotplug test is one of good test.
213+
214+ to offline memory, do following::
215+
216+ # echo offline > /sys/devices/system/memory/memoryXXX/state
217+
218+ (XXX is the place of memory)
219+
220+ This is an easy way to test page migration, too.
221+
222+9.5 mkdir/rmdir
223+---------------
224+
225+ When using hierarchy, mkdir/rmdir test should be done.
226+ Use tests like the following::
227+
228+ echo 1 >/opt/cgroup/01/memory/use_hierarchy
229+ mkdir /opt/cgroup/01/child_a
230+ mkdir /opt/cgroup/01/child_b
231+
232+ set limit to 01.
233+ add limit to 01/child_b
234+ run jobs under child_a and child_b
235+
236+ create/delete following groups at random while jobs are running::
237+
238+ /opt/cgroup/01/child_a/child_aa
239+ /opt/cgroup/01/child_b/child_bb
240+ /opt/cgroup/01/child_c
241+
242+ running new jobs in new group is also good.
243+
244+9.6 Mount with other subsystems
245+-------------------------------
246+
247+ Mounting with other subsystems is a good test because there is a
248+ race and lock dependency with other cgroup subsystems.
249+
250+ example::
251+
252+ # mount -t cgroup none /cgroup -o cpuset,memory,cpu,devices
253+
254+ and do task move, mkdir, rmdir etc...under this.
255+
256+9.7 swapoff
257+-----------
258+
259+ Besides management of swap is one of complicated parts of memcg,
260+ call path of swap-in at swapoff is not same as usual swap-in path..
261+ It's worth to be tested explicitly.
262+
263+ For example, test like following is good:
264+
265+ (Shell-A)::
266+
267+ # mount -t cgroup none /cgroup -o memory
268+ # mkdir /cgroup/test
269+ # echo 40M > /cgroup/test/memory.limit_in_bytes
270+ # echo 0 > /cgroup/test/tasks
271+
272+ Run malloc(100M) program under this. You'll see 60M of swaps.
273+
274+ (Shell-B)::
275+
276+ # move all tasks in /cgroup/test to /cgroup
277+ # /sbin/swapoff -a
278+ # rmdir /cgroup/test
279+ # kill malloc task.
280+
281+ Of course, tmpfs v.s. swapoff test should be tested, too.
282+
283+9.8 OOM-Killer
284+--------------
285+
286+ Out-of-memory caused by memcg's limit will kill tasks under
287+ the memcg. When hierarchy is used, a task under hierarchy
288+ will be killed by the kernel.
289+
290+ In this case, panic_on_oom shouldn't be invoked and tasks
291+ in other groups shouldn't be killed.
292+
293+ It's not difficult to cause OOM under memcg as following.
294+
295+ Case A) when you can swapoff::
296+
297+ #swapoff -a
298+ #echo 50M > /memory.limit_in_bytes
299+
300+ run 51M of malloc
301+
302+ Case B) when you use mem+swap limitation::
303+
304+ #echo 50M > memory.limit_in_bytes
305+ #echo 50M > memory.memsw.limit_in_bytes
306+
307+ run 51M of malloc
308+
309+9.9 Move charges at task migration
310+----------------------------------
311+
312+ Charges associated with a task can be moved along with task migration.
313+
314+ (Shell-A)::
315+
316+ #mkdir /cgroup/A
317+ #echo $$ >/cgroup/A/tasks
318+
319+ run some programs which uses some amount of memory in /cgroup/A.
320+
321+ (Shell-B)::
322+
323+ #mkdir /cgroup/B
324+ #echo 1 >/cgroup/B/memory.move_charge_at_immigrate
325+ #echo "pid of the program running in group A" >/cgroup/B/tasks
326+
327+ You can see charges have been moved by reading ``*.usage_in_bytes`` or
328+ memory.stat of both A and B.
329+
330+ See 8.2 of Documentation/admin-guide/cgroup-v1/memory.rst to see what value should
331+ be written to move_charge_at_immigrate.
332+
333+9.10 Memory thresholds
334+----------------------
335+
336+ Memory controller implements memory thresholds using cgroups notification
337+ API. You can use tools/cgroup/cgroup_event_listener.c to test it.
338+
339+ (Shell-A) Create cgroup and run event listener::
340+
341+ # mkdir /cgroup/A
342+ # ./cgroup_event_listener /cgroup/A/memory.usage_in_bytes 5M
343+
344+ (Shell-B) Add task to cgroup and try to allocate and free memory::
345+
346+ # echo $$ >/cgroup/A/tasks
347+ # a="$(dd if=/dev/zero bs=1M count=10)"
348+ # a=
349+
350+ You will see message from cgroup_event_listener every time you cross
351+ the thresholds.
352+
353+ Use /cgroup/A/memory.memsw.usage_in_bytes to test memsw thresholds.
354+
355+ It's good idea to test root cgroup as well.
Documentation/admin-guide/cgroup-v1/memory.rst+1003−0
@@ -0,0 +1,1003 @@
1+==========================
2+Memory Resource Controller
3+==========================
4+
5+NOTE:
6+ This document is hopelessly outdated and it asks for a complete
7+ rewrite. It still contains a useful information so we are keeping it
8+ here but make sure to check the current code if you need a deeper
9+ understanding.
10+
11+NOTE:
12+ The Memory Resource Controller has generically been referred to as the
13+ memory controller in this document. Do not confuse memory controller
14+ used here with the memory controller that is used in hardware.
15+
16+(For editors) In this document:
17+ When we mention a cgroup (cgroupfs's directory) with memory controller,
18+ we call it "memory cgroup". When you see git-log and source code, you'll
19+ see patch's title and function names tend to use "memcg".
20+ In this document, we avoid using it.
21+
22+Benefits and Purpose of the memory controller
23+=============================================
24+
25+The memory controller isolates the memory behaviour of a group of tasks
26+from the rest of the system. The article on LWN [12] mentions some probable
27+uses of the memory controller. The memory controller can be used to
28+
29+a. Isolate an application or a group of applications
30+ Memory-hungry applications can be isolated and limited to a smaller
31+ amount of memory.
32+b. Create a cgroup with a limited amount of memory; this can be used
33+ as a good alternative to booting with mem=XXXX.
34+c. Virtualization solutions can control the amount of memory they want
35+ to assign to a virtual machine instance.
36+d. A CD/DVD burner could control the amount of memory used by the
37+ rest of the system to ensure that burning does not fail due to lack
38+ of available memory.
39+e. There are several other use cases; find one or use the controller just
40+ for fun (to learn and hack on the VM subsystem).
41+
42+Current Status: linux-2.6.34-mmotm(development version of 2010/April)
43+
44+Features:
45+
46+ - accounting anonymous pages, file caches, swap caches usage and limiting them.
47+ - pages are linked to per-memcg LRU exclusively, and there is no global LRU.
48+ - optionally, memory+swap usage can be accounted and limited.
49+ - hierarchical accounting
50+ - soft limit
51+ - moving (recharging) account at moving a task is selectable.
52+ - usage threshold notifier
53+ - memory pressure notifier
54+ - oom-killer disable knob and oom-notifier
55+ - Root cgroup has no limit controls.
56+
57+ Kernel memory support is a work in progress, and the current version provides
58+ basically functionality. (See Section 2.7)
59+
60+Brief summary of control files.
61+
62+==================================== ==========================================
63+ tasks attach a task(thread) and show list of
64+ threads
65+ cgroup.procs show list of processes
66+ cgroup.event_control an interface for event_fd()
67+ memory.usage_in_bytes show current usage for memory
68+ (See 5.5 for details)
69+ memory.memsw.usage_in_bytes show current usage for memory+Swap
70+ (See 5.5 for details)
71+ memory.limit_in_bytes set/show limit of memory usage
72+ memory.memsw.limit_in_bytes set/show limit of memory+Swap usage
73+ memory.failcnt show the number of memory usage hits limits
74+ memory.memsw.failcnt show the number of memory+Swap hits limits
75+ memory.max_usage_in_bytes show max memory usage recorded
76+ memory.memsw.max_usage_in_bytes show max memory+Swap usage recorded
77+ memory.soft_limit_in_bytes set/show soft limit of memory usage
78+ memory.stat show various statistics
79+ memory.use_hierarchy set/show hierarchical account enabled
80+ memory.force_empty trigger forced page reclaim
81+ memory.pressure_level set memory pressure notifications
82+ memory.swappiness set/show swappiness parameter of vmscan
83+ (See sysctl's vm.swappiness)
84+ memory.move_charge_at_immigrate set/show controls of moving charges
85+ memory.oom_control set/show oom controls.
86+ memory.numa_stat show the number of memory usage per numa
87+ node
88+
89+ memory.kmem.limit_in_bytes set/show hard limit for kernel memory
90+ memory.kmem.usage_in_bytes show current kernel memory allocation
91+ memory.kmem.failcnt show the number of kernel memory usage
92+ hits limits
93+ memory.kmem.max_usage_in_bytes show max kernel memory usage recorded
94+
95+ memory.kmem.tcp.limit_in_bytes set/show hard limit for tcp buf memory
96+ memory.kmem.tcp.usage_in_bytes show current tcp buf memory allocation
97+ memory.kmem.tcp.failcnt show the number of tcp buf memory usage
98+ hits limits
99+ memory.kmem.tcp.max_usage_in_bytes show max tcp buf memory usage recorded
100+==================================== ==========================================
101+
102+1. History
103+==========
104+
105+The memory controller has a long history. A request for comments for the memory
106+controller was posted by Balbir Singh [1]. At the time the RFC was posted
107+there were several implementations for memory control. The goal of the
108+RFC was to build consensus and agreement for the minimal features required
109+for memory control. The first RSS controller was posted by Balbir Singh[2]
110+in Feb 2007. Pavel Emelianov [3][4][5] has since posted three versions of the
111+RSS controller. At OLS, at the resource management BoF, everyone suggested
112+that we handle both page cache and RSS together. Another request was raised
113+to allow user space handling of OOM. The current memory controller is
114+at version 6; it combines both mapped (RSS) and unmapped Page
115+Cache Control [11].
116+
117+2. Memory Control
118+=================
119+
120+Memory is a unique resource in the sense that it is present in a limited
121+amount. If a task requires a lot of CPU processing, the task can spread
122+its processing over a period of hours, days, months or years, but with
123+memory, the same physical memory needs to be reused to accomplish the task.
124+
125+The memory controller implementation has been divided into phases. These
126+are:
127+
128+1. Memory controller
129+2. mlock(2) controller
130+3. Kernel user memory accounting and slab control
131+4. user mappings length controller
132+
133+The memory controller is the first controller developed.
134+
135+2.1. Design
136+-----------
137+
138+The core of the design is a counter called the page_counter. The
139+page_counter tracks the current memory usage and limit of the group of
140+processes associated with the controller. Each cgroup has a memory controller
141+specific data structure (mem_cgroup) associated with it.
142+
143+2.2. Accounting
144+---------------
145+
146+::
147+
148+ +--------------------+
149+ | mem_cgroup |
150+ | (page_counter) |
151+ +--------------------+
152+ / ^ \
153+ / | \
154+ +---------------+ | +---------------+
155+ | mm_struct | |.... | mm_struct |
156+ | | | | |
157+ +---------------+ | +---------------+
158+ |
159+ + --------------+
160+ |
161+ +---------------+ +------+--------+
162+ | page +----------> page_cgroup|
163+ | | | |
164+ +---------------+ +---------------+
165+
166+ (Figure 1: Hierarchy of Accounting)
167+
168+
169+Figure 1 shows the important aspects of the controller
170+
171+1. Accounting happens per cgroup
172+2. Each mm_struct knows about which cgroup it belongs to
173+3. Each page has a pointer to the page_cgroup, which in turn knows the
174+ cgroup it belongs to
175+
176+The accounting is done as follows: mem_cgroup_charge_common() is invoked to
177+set up the necessary data structures and check if the cgroup that is being
178+charged is over its limit. If it is, then reclaim is invoked on the cgroup.
179+More details can be found in the reclaim section of this document.
180+If everything goes well, a page meta-data-structure called page_cgroup is
181+updated. page_cgroup has its own LRU on cgroup.
182+(*) page_cgroup structure is allocated at boot/memory-hotplug time.
183+
184+2.2.1 Accounting details
185+------------------------
186+
187+All mapped anon pages (RSS) and cache pages (Page Cache) are accounted.
188+Some pages which are never reclaimable and will not be on the LRU
189+are not accounted. We just account pages under usual VM management.
190+
191+RSS pages are accounted at page_fault unless they've already been accounted
192+for earlier. A file page will be accounted for as Page Cache when it's
193+inserted into inode (radix-tree). While it's mapped into the page tables of
194+processes, duplicate accounting is carefully avoided.
195+
196+An RSS page is unaccounted when it's fully unmapped. A PageCache page is
197+unaccounted when it's removed from radix-tree. Even if RSS pages are fully
198+unmapped (by kswapd), they may exist as SwapCache in the system until they
199+are really freed. Such SwapCaches are also accounted.
200+A swapped-in page is not accounted until it's mapped.
201+
202+Note: The kernel does swapin-readahead and reads multiple swaps at once.
203+This means swapped-in pages may contain pages for other tasks than a task
204+causing page fault. So, we avoid accounting at swap-in I/O.
205+
206+At page migration, accounting information is kept.
207+
208+Note: we just account pages-on-LRU because our purpose is to control amount
209+of used pages; not-on-LRU pages tend to be out-of-control from VM view.
210+
211+2.3 Shared Page Accounting
212+--------------------------
213+
214+Shared pages are accounted on the basis of the first touch approach. The
215+cgroup that first touches a page is accounted for the page. The principle
216+behind this approach is that a cgroup that aggressively uses a shared
217+page will eventually get charged for it (once it is uncharged from
218+the cgroup that brought it in -- this will happen on memory pressure).
219+
220+But see section 8.2: when moving a task to another cgroup, its pages may
221+be recharged to the new cgroup, if move_charge_at_immigrate has been chosen.
222+
223+Exception: If CONFIG_MEMCG_SWAP is not used.
224+When you do swapoff and make swapped-out pages of shmem(tmpfs) to
225+be backed into memory in force, charges for pages are accounted against the
226+caller of swapoff rather than the users of shmem.
227+
228+2.4 Swap Extension (CONFIG_MEMCG_SWAP)
229+--------------------------------------
230+
231+Swap Extension allows you to record charge for swap. A swapped-in page is
232+charged back to original page allocator if possible.
233+
234+When swap is accounted, following files are added.
235+
236+ - memory.memsw.usage_in_bytes.
237+ - memory.memsw.limit_in_bytes.
238+
239+memsw means memory+swap. Usage of memory+swap is limited by
240+memsw.limit_in_bytes.
241+
242+Example: Assume a system with 4G of swap. A task which allocates 6G of memory
243+(by mistake) under 2G memory limitation will use all swap.
244+In this case, setting memsw.limit_in_bytes=3G will prevent bad use of swap.
245+By using the memsw limit, you can avoid system OOM which can be caused by swap
246+shortage.
247+
248+**why 'memory+swap' rather than swap**
249+
250+The global LRU(kswapd) can swap out arbitrary pages. Swap-out means
251+to move account from memory to swap...there is no change in usage of
252+memory+swap. In other words, when we want to limit the usage of swap without
253+affecting global LRU, memory+swap limit is better than just limiting swap from
254+an OS point of view.
255+
256+**What happens when a cgroup hits memory.memsw.limit_in_bytes**
257+
258+When a cgroup hits memory.memsw.limit_in_bytes, it's useless to do swap-out
259+in this cgroup. Then, swap-out will not be done by cgroup routine and file
260+caches are dropped. But as mentioned above, global LRU can do swapout memory
261+from it for sanity of the system's memory management state. You can't forbid
262+it by cgroup.
263+
264+2.5 Reclaim
265+-----------
266+
267+Each cgroup maintains a per cgroup LRU which has the same structure as
268+global VM. When a cgroup goes over its limit, we first try
269+to reclaim memory from the cgroup so as to make space for the new
270+pages that the cgroup has touched. If the reclaim is unsuccessful,
271+an OOM routine is invoked to select and kill the bulkiest task in the
272+cgroup. (See 10. OOM Control below.)
273+
274+The reclaim algorithm has not been modified for cgroups, except that
275+pages that are selected for reclaiming come from the per-cgroup LRU
276+list.
277+
278+NOTE:
279+ Reclaim does not work for the root cgroup, since we cannot set any
280+ limits on the root cgroup.
281+
282+Note2:
283+ When panic_on_oom is set to "2", the whole system will panic.
284+
285+When oom event notifier is registered, event will be delivered.
286+(See oom_control section)
287+
288+2.6 Locking
289+-----------
290+
291+ lock_page_cgroup()/unlock_page_cgroup() should not be called under
292+ the i_pages lock.
293+
294+ Other lock order is following:
295+
296+ PG_locked.
297+ mm->page_table_lock
298+ pgdat->lru_lock
299+ lock_page_cgroup.
300+
301+ In many cases, just lock_page_cgroup() is called.
302+
303+ per-zone-per-cgroup LRU (cgroup's private LRU) is just guarded by
304+ pgdat->lru_lock, it has no lock of its own.
305+
306+2.7 Kernel Memory Extension (CONFIG_MEMCG_KMEM)
307+-----------------------------------------------
308+
309+With the Kernel memory extension, the Memory Controller is able to limit
310+the amount of kernel memory used by the system. Kernel memory is fundamentally
311+different than user memory, since it can't be swapped out, which makes it
312+possible to DoS the system by consuming too much of this precious resource.
313+
314+Kernel memory accounting is enabled for all memory cgroups by default. But
315+it can be disabled system-wide by passing cgroup.memory=nokmem to the kernel
316+at boot time. In this case, kernel memory will not be accounted at all.
317+
318+Kernel memory limits are not imposed for the root cgroup. Usage for the root
319+cgroup may or may not be accounted. The memory used is accumulated into
320+memory.kmem.usage_in_bytes, or in a separate counter when it makes sense.
321+(currently only for tcp).
322+
323+The main "kmem" counter is fed into the main counter, so kmem charges will
324+also be visible from the user counter.
325+
326+Currently no soft limit is implemented for kernel memory. It is future work
327+to trigger slab reclaim when those limits are reached.
328+
329+2.7.1 Current Kernel Memory resources accounted
330+-----------------------------------------------
331+
332+stack pages:
333+ every process consumes some stack pages. By accounting into
334+ kernel memory, we prevent new processes from being created when the kernel
335+ memory usage is too high.
336+
337+slab pages:
338+ pages allocated by the SLAB or SLUB allocator are tracked. A copy
339+ of each kmem_cache is created every time the cache is touched by the first time
340+ from inside the memcg. The creation is done lazily, so some objects can still be
341+ skipped while the cache is being created. All objects in a slab page should
342+ belong to the same memcg. This only fails to hold when a task is migrated to a
343+ different memcg during the page allocation by the cache.
344+
345+sockets memory pressure:
346+ some sockets protocols have memory pressure
347+ thresholds. The Memory Controller allows them to be controlled individually
348+ per cgroup, instead of globally.
349+
350+tcp memory pressure:
351+ sockets memory pressure for the tcp protocol.
352+
353+2.7.2 Common use cases
354+----------------------
355+
356+Because the "kmem" counter is fed to the main user counter, kernel memory can
357+never be limited completely independently of user memory. Say "U" is the user
358+limit, and "K" the kernel limit. There are three possible ways limits can be
359+set:
360+
361+U != 0, K = unlimited:
362+ This is the standard memcg limitation mechanism already present before kmem
363+ accounting. Kernel memory is completely ignored.
364+
365+U != 0, K < U:
366+ Kernel memory is a subset of the user memory. This setup is useful in
367+ deployments where the total amount of memory per-cgroup is overcommited.
368+ Overcommiting kernel memory limits is definitely not recommended, since the
369+ box can still run out of non-reclaimable memory.
370+ In this case, the admin could set up K so that the sum of all groups is
371+ never greater than the total memory, and freely set U at the cost of his
372+ QoS.
373+
374+WARNING:
375+ In the current implementation, memory reclaim will NOT be
376+ triggered for a cgroup when it hits K while staying below U, which makes
377+ this setup impractical.
378+
379+U != 0, K >= U:
380+ Since kmem charges will also be fed to the user counter and reclaim will be
381+ triggered for the cgroup for both kinds of memory. This setup gives the
382+ admin a unified view of memory, and it is also useful for people who just
383+ want to track kernel memory usage.
384+
385+3. User Interface
386+=================
387+
388+3.0. Configuration
389+------------------
390+
391+a. Enable CONFIG_CGROUPS
392+b. Enable CONFIG_MEMCG
393+c. Enable CONFIG_MEMCG_SWAP (to use swap extension)
394+d. Enable CONFIG_MEMCG_KMEM (to use kmem extension)
395+
396+3.1. Prepare the cgroups (see cgroups.txt, Why are cgroups needed?)
397+-------------------------------------------------------------------
398+
399+::
400+
401+ # mount -t tmpfs none /sys/fs/cgroup
402+ # mkdir /sys/fs/cgroup/memory
403+ # mount -t cgroup none /sys/fs/cgroup/memory -o memory
404+
405+3.2. Make the new group and move bash into it::
406+
407+ # mkdir /sys/fs/cgroup/memory/0
408+ # echo $$ > /sys/fs/cgroup/memory/0/tasks
409+
410+Since now we're in the 0 cgroup, we can alter the memory limit::
411+
412+ # echo 4M > /sys/fs/cgroup/memory/0/memory.limit_in_bytes
413+
414+NOTE:
415+ We can use a suffix (k, K, m, M, g or G) to indicate values in kilo,
416+ mega or gigabytes. (Here, Kilo, Mega, Giga are Kibibytes, Mebibytes,
417+ Gibibytes.)
418+
419+NOTE:
420+ We can write "-1" to reset the ``*.limit_in_bytes(unlimited)``.
421+
422+NOTE:
423+ We cannot set limits on the root cgroup any more.
424+
425+::
426+
427+ # cat /sys/fs/cgroup/memory/0/memory.limit_in_bytes
428+ 4194304
429+
430+We can check the usage::
431+
432+ # cat /sys/fs/cgroup/memory/0/memory.usage_in_bytes
433+ 1216512
434+
435+A successful write to this file does not guarantee a successful setting of
436+this limit to the value written into the file. This can be due to a
437+number of factors, such as rounding up to page boundaries or the total
438+availability of memory on the system. The user is required to re-read
439+this file after a write to guarantee the value committed by the kernel::
440+
441+ # echo 1 > memory.limit_in_bytes
442+ # cat memory.limit_in_bytes
443+ 4096
444+
445+The memory.failcnt field gives the number of times that the cgroup limit was
446+exceeded.
447+
448+The memory.stat file gives accounting information. Now, the number of
449+caches, RSS and Active pages/Inactive pages are shown.
450+
451+4. Testing
452+==========
453+
454+For testing features and implementation, see memcg_test.txt.
455+
456+Performance test is also important. To see pure memory controller's overhead,
457+testing on tmpfs will give you good numbers of small overheads.
458+Example: do kernel make on tmpfs.
459+
460+Page-fault scalability is also important. At measuring parallel
461+page fault test, multi-process test may be better than multi-thread
462+test because it has noise of shared objects/status.
463+
464+But the above two are testing extreme situations.
465+Trying usual test under memory controller is always helpful.
466+
467+4.1 Troubleshooting
468+-------------------
469+
470+Sometimes a user might find that the application under a cgroup is
471+terminated by the OOM killer. There are several causes for this:
472+
473+1. The cgroup limit is too low (just too low to do anything useful)
474+2. The user is using anonymous memory and swap is turned off or too low
475+
476+A sync followed by echo 1 > /proc/sys/vm/drop_caches will help get rid of
477+some of the pages cached in the cgroup (page cache pages).
478+
479+To know what happens, disabling OOM_Kill as per "10. OOM Control" (below) and
480+seeing what happens will be helpful.
481+
482+4.2 Task migration
483+------------------
484+
485+When a task migrates from one cgroup to another, its charge is not
486+carried forward by default. The pages allocated from the original cgroup still
487+remain charged to it, the charge is dropped when the page is freed or
488+reclaimed.
489+
490+You can move charges of a task along with task migration.
491+See 8. "Move charges at task migration"
492+
493+4.3 Removing a cgroup
494+---------------------
495+
496+A cgroup can be removed by rmdir, but as discussed in sections 4.1 and 4.2, a
497+cgroup might have some charge associated with it, even though all
498+tasks have migrated away from it. (because we charge against pages, not
499+against tasks.)
500+
501+We move the stats to root (if use_hierarchy==0) or parent (if
502+use_hierarchy==1), and no change on the charge except uncharging
503+from the child.
504+
505+Charges recorded in swap information is not updated at removal of cgroup.
506+Recorded information is discarded and a cgroup which uses swap (swapcache)
507+will be charged as a new owner of it.
508+
509+About use_hierarchy, see Section 6.
510+
511+5. Misc. interfaces
512+===================
513+
514+5.1 force_empty
515+---------------
516+ memory.force_empty interface is provided to make cgroup's memory usage empty.
517+ When writing anything to this::
518+
519+ # echo 0 > memory.force_empty
520+
521+ the cgroup will be reclaimed and as many pages reclaimed as possible.
522+
523+ The typical use case for this interface is before calling rmdir().
524+ Though rmdir() offlines memcg, but the memcg may still stay there due to
525+ charged file caches. Some out-of-use page caches may keep charged until
526+ memory pressure happens. If you want to avoid that, force_empty will be useful.
527+
528+ Also, note that when memory.kmem.limit_in_bytes is set the charges due to
529+ kernel pages will still be seen. This is not considered a failure and the
530+ write will still return success. In this case, it is expected that
531+ memory.kmem.usage_in_bytes == memory.usage_in_bytes.
532+
533+ About use_hierarchy, see Section 6.
534+
535+5.2 stat file
536+-------------
537+
538+memory.stat file includes following statistics
539+
540+per-memory cgroup local status
541+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
542+
543+=============== ===============================================================
544+cache # of bytes of page cache memory.
545+rss # of bytes of anonymous and swap cache memory (includes
546+ transparent hugepages).
547+rss_huge # of bytes of anonymous transparent hugepages.
548+mapped_file # of bytes of mapped file (includes tmpfs/shmem)
549+pgpgin # of charging events to the memory cgroup. The charging
550+ event happens each time a page is accounted as either mapped
551+ anon page(RSS) or cache page(Page Cache) to the cgroup.
552+pgpgout # of uncharging events to the memory cgroup. The uncharging
553+ event happens each time a page is unaccounted from the cgroup.
554+swap # of bytes of swap usage
555+dirty # of bytes that are waiting to get written back to the disk.
556+writeback # of bytes of file/anon cache that are queued for syncing to
557+ disk.
558+inactive_anon # of bytes of anonymous and swap cache memory on inactive
559+ LRU list.
560+active_anon # of bytes of anonymous and swap cache memory on active
561+ LRU list.
562+inactive_file # of bytes of file-backed memory on inactive LRU list.
563+active_file # of bytes of file-backed memory on active LRU list.
564+unevictable # of bytes of memory that cannot be reclaimed (mlocked etc).
565+=============== ===============================================================
566+
567+status considering hierarchy (see memory.use_hierarchy settings)
568+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
569+
570+========================= ===================================================
571+hierarchical_memory_limit # of bytes of memory limit with regard to hierarchy
572+ under which the memory cgroup is
573+hierarchical_memsw_limit # of bytes of memory+swap limit with regard to
574+ hierarchy under which memory cgroup is.
575+
576+total_<counter> # hierarchical version of <counter>, which in
577+ addition to the cgroup's own value includes the
578+ sum of all hierarchical children's values of
579+ <counter>, i.e. total_cache
580+========================= ===================================================
581+
582+The following additional stats are dependent on CONFIG_DEBUG_VM
583+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
584+
585+========================= ========================================
586+recent_rotated_anon VM internal parameter. (see mm/vmscan.c)
587+recent_rotated_file VM internal parameter. (see mm/vmscan.c)
588+recent_scanned_anon VM internal parameter. (see mm/vmscan.c)
589+recent_scanned_file VM internal parameter. (see mm/vmscan.c)
590+========================= ========================================
591+
592+Memo:
593+ recent_rotated means recent frequency of LRU rotation.
594+ recent_scanned means recent # of scans to LRU.
595+ showing for better debug please see the code for meanings.
596+
597+Note:
598+ Only anonymous and swap cache memory is listed as part of 'rss' stat.
599+ This should not be confused with the true 'resident set size' or the
600+ amount of physical memory used by the cgroup.
601+
602+ 'rss + mapped_file" will give you resident set size of cgroup.
603+
604+ (Note: file and shmem may be shared among other cgroups. In that case,
605+ mapped_file is accounted only when the memory cgroup is owner of page
606+ cache.)
607+
608+5.3 swappiness
609+--------------
610+
611+Overrides /proc/sys/vm/swappiness for the particular group. The tunable
612+in the root cgroup corresponds to the global swappiness setting.
613+
614+Please note that unlike during the global reclaim, limit reclaim
615+enforces that 0 swappiness really prevents from any swapping even if
616+there is a swap storage available. This might lead to memcg OOM killer
617+if there are no file pages to reclaim.
618+
619+5.4 failcnt
620+-----------
621+
622+A memory cgroup provides memory.failcnt and memory.memsw.failcnt files.
623+This failcnt(== failure count) shows the number of times that a usage counter
624+hit its limit. When a memory cgroup hits a limit, failcnt increases and
625+memory under it will be reclaimed.
626+
627+You can reset failcnt by writing 0 to failcnt file::
628+
629+ # echo 0 > .../memory.failcnt
630+
631+5.5 usage_in_bytes
632+------------------
633+
634+For efficiency, as other kernel components, memory cgroup uses some optimization
635+to avoid unnecessary cacheline false sharing. usage_in_bytes is affected by the
636+method and doesn't show 'exact' value of memory (and swap) usage, it's a fuzz
637+value for efficient access. (Of course, when necessary, it's synchronized.)
638+If you want to know more exact memory usage, you should use RSS+CACHE(+SWAP)
639+value in memory.stat(see 5.2).
640+
641+5.6 numa_stat
642+-------------
643+
644+This is similar to numa_maps but operates on a per-memcg basis. This is
645+useful for providing visibility into the numa locality information within
646+an memcg since the pages are allowed to be allocated from any physical
647+node. One of the use cases is evaluating application performance by
648+combining this information with the application's CPU allocation.
649+
650+Each memcg's numa_stat file includes "total", "file", "anon" and "unevictable"
651+per-node page counts including "hierarchical_<counter>" which sums up all
652+hierarchical children's values in addition to the memcg's own value.
653+
654+The output format of memory.numa_stat is::
655+
656+ total=<total pages> N0=<node 0 pages> N1=<node 1 pages> ...
657+ file=<total file pages> N0=<node 0 pages> N1=<node 1 pages> ...
658+ anon=<total anon pages> N0=<node 0 pages> N1=<node 1 pages> ...
659+ unevictable=<total anon pages> N0=<node 0 pages> N1=<node 1 pages> ...
660+ hierarchical_<counter>=<counter pages> N0=<node 0 pages> N1=<node 1 pages> ...
661+
662+The "total" count is sum of file + anon + unevictable.
663+
664+6. Hierarchy support
665+====================
666+
667+The memory controller supports a deep hierarchy and hierarchical accounting.
668+The hierarchy is created by creating the appropriate cgroups in the
669+cgroup filesystem. Consider for example, the following cgroup filesystem
670+hierarchy::
671+
672+ root
673+ / | \
674+ / | \
675+ a b c
676+ | \
677+ | \
678+ d e
679+
680+In the diagram above, with hierarchical accounting enabled, all memory
681+usage of e, is accounted to its ancestors up until the root (i.e, c and root),
682+that has memory.use_hierarchy enabled. If one of the ancestors goes over its
683+limit, the reclaim algorithm reclaims from the tasks in the ancestor and the
684+children of the ancestor.
685+
686+6.1 Enabling hierarchical accounting and reclaim
687+------------------------------------------------
688+
689+A memory cgroup by default disables the hierarchy feature. Support
690+can be enabled by writing 1 to memory.use_hierarchy file of the root cgroup::
691+
692+ # echo 1 > memory.use_hierarchy
693+
694+The feature can be disabled by::
695+
696+ # echo 0 > memory.use_hierarchy
697+
698+NOTE1:
699+ Enabling/disabling will fail if either the cgroup already has other
700+ cgroups created below it, or if the parent cgroup has use_hierarchy
701+ enabled.
702+
703+NOTE2:
704+ When panic_on_oom is set to "2", the whole system will panic in
705+ case of an OOM event in any cgroup.
706+
707+7. Soft limits
708+==============
709+
710+Soft limits allow for greater sharing of memory. The idea behind soft limits
711+is to allow control groups to use as much of the memory as needed, provided
712+
713+a. There is no memory contention
714+b. They do not exceed their hard limit
715+
716+When the system detects memory contention or low memory, control groups
717+are pushed back to their soft limits. If the soft limit of each control
718+group is very high, they are pushed back as much as possible to make
719+sure that one control group does not starve the others of memory.
720+
721+Please note that soft limits is a best-effort feature; it comes with
722+no guarantees, but it does its best to make sure that when memory is
723+heavily contended for, memory is allocated based on the soft limit
724+hints/setup. Currently soft limit based reclaim is set up such that
725+it gets invoked from balance_pgdat (kswapd).
726+
727+7.1 Interface
728+-------------
729+
730+Soft limits can be setup by using the following commands (in this example we
731+assume a soft limit of 256 MiB)::
732+
733+ # echo 256M > memory.soft_limit_in_bytes
734+
735+If we want to change this to 1G, we can at any time use::
736+
737+ # echo 1G > memory.soft_limit_in_bytes
738+
739+NOTE1:
740+ Soft limits take effect over a long period of time, since they involve
741+ reclaiming memory for balancing between memory cgroups
742+NOTE2:
743+ It is recommended to set the soft limit always below the hard limit,
744+ otherwise the hard limit will take precedence.
745+
746+8. Move charges at task migration
747+=================================
748+
749+Users can move charges associated with a task along with task migration, that
750+is, uncharge task's pages from the old cgroup and charge them to the new cgroup.
751+This feature is not supported in !CONFIG_MMU environments because of lack of
752+page tables.
753+
754+8.1 Interface
755+-------------
756+
757+This feature is disabled by default. It can be enabled (and disabled again) by
758+writing to memory.move_charge_at_immigrate of the destination cgroup.
759+
760+If you want to enable it::
761+
762+ # echo (some positive value) > memory.move_charge_at_immigrate
763+
764+Note:
765+ Each bits of move_charge_at_immigrate has its own meaning about what type
766+ of charges should be moved. See 8.2 for details.
767+Note:
768+ Charges are moved only when you move mm->owner, in other words,
769+ a leader of a thread group.
770+Note:
771+ If we cannot find enough space for the task in the destination cgroup, we
772+ try to make space by reclaiming memory. Task migration may fail if we
773+ cannot make enough space.
774+Note:
775+ It can take several seconds if you move charges much.
776+
777+And if you want disable it again::
778+
779+ # echo 0 > memory.move_charge_at_immigrate
780+
781+8.2 Type of charges which can be moved
782+--------------------------------------
783+
784+Each bit in move_charge_at_immigrate has its own meaning about what type of
785+charges should be moved. But in any case, it must be noted that an account of
786+a page or a swap can be moved only when it is charged to the task's current
787+(old) memory cgroup.
788+
789++---+--------------------------------------------------------------------------+
790+|bit| what type of charges would be moved ? |
791++===+==========================================================================+
792+| 0 | A charge of an anonymous page (or swap of it) used by the target task. |
793+| | You must enable Swap Extension (see 2.4) to enable move of swap charges. |
794++---+--------------------------------------------------------------------------+
795+| 1 | A charge of file pages (normal file, tmpfs file (e.g. ipc shared memory) |
796+| | and swaps of tmpfs file) mmapped by the target task. Unlike the case of |
797+| | anonymous pages, file pages (and swaps) in the range mmapped by the task |
798+| | will be moved even if the task hasn't done page fault, i.e. they might |
799+| | not be the task's "RSS", but other task's "RSS" that maps the same file. |
800+| | And mapcount of the page is ignored (the page can be moved even if |
801+| | page_mapcount(page) > 1). You must enable Swap Extension (see 2.4) to |
802+| | enable move of swap charges. |
803++---+--------------------------------------------------------------------------+
804+
805+8.3 TODO
806+--------
807+
808+- All of moving charge operations are done under cgroup_mutex. It's not good
809+ behavior to hold the mutex too long, so we may need some trick.
810+
811+9. Memory thresholds
812+====================
813+
814+Memory cgroup implements memory thresholds using the cgroups notification
815+API (see cgroups.txt). It allows to register multiple memory and memsw
816+thresholds and gets notifications when it crosses.
817+
818+To register a threshold, an application must:
819+
820+- create an eventfd using eventfd(2);
821+- open memory.usage_in_bytes or memory.memsw.usage_in_bytes;
822+- write string like "<event_fd> <fd of memory.usage_in_bytes> <threshold>" to
823+ cgroup.event_control.
824+
825+Application will be notified through eventfd when memory usage crosses
826+threshold in any direction.
827+
828+It's applicable for root and non-root cgroup.
829+
830+10. OOM Control
831+===============
832+
833+memory.oom_control file is for OOM notification and other controls.
834+
835+Memory cgroup implements OOM notifier using the cgroup notification
836+API (See cgroups.txt). It allows to register multiple OOM notification
837+delivery and gets notification when OOM happens.
838+
839+To register a notifier, an application must:
840+
841+ - create an eventfd using eventfd(2)
842+ - open memory.oom_control file
843+ - write string like "<event_fd> <fd of memory.oom_control>" to
844+ cgroup.event_control
845+
846+The application will be notified through eventfd when OOM happens.
847+OOM notification doesn't work for the root cgroup.
848+
849+You can disable the OOM-killer by writing "1" to memory.oom_control file, as:
850+
851+ #echo 1 > memory.oom_control
852+
853+If OOM-killer is disabled, tasks under cgroup will hang/sleep
854+in memory cgroup's OOM-waitqueue when they request accountable memory.
855+
856+For running them, you have to relax the memory cgroup's OOM status by
857+
858+ * enlarge limit or reduce usage.
859+
860+To reduce usage,
861+
862+ * kill some tasks.
863+ * move some tasks to other group with account migration.
864+ * remove some files (on tmpfs?)
865+
866+Then, stopped tasks will work again.
867+
868+At reading, current status of OOM is shown.
869+
870+ - oom_kill_disable 0 or 1
871+ (if 1, oom-killer is disabled)
872+ - under_oom 0 or 1
873+ (if 1, the memory cgroup is under OOM, tasks may be stopped.)
874+
875+11. Memory Pressure
876+===================
877+
878+The pressure level notifications can be used to monitor the memory
879+allocation cost; based on the pressure, applications can implement
880+different strategies of managing their memory resources. The pressure
881+levels are defined as following:
882+
883+The "low" level means that the system is reclaiming memory for new
884+allocations. Monitoring this reclaiming activity might be useful for
885+maintaining cache level. Upon notification, the program (typically
886+"Activity Manager") might analyze vmstat and act in advance (i.e.
887+prematurely shutdown unimportant services).
888+
889+The "medium" level means that the system is experiencing medium memory
890+pressure, the system might be making swap, paging out active file caches,
891+etc. Upon this event applications may decide to further analyze
892+vmstat/zoneinfo/memcg or internal memory usage statistics and free any
893+resources that can be easily reconstructed or re-read from a disk.
894+
895+The "critical" level means that the system is actively thrashing, it is
896+about to out of memory (OOM) or even the in-kernel OOM killer is on its
897+way to trigger. Applications should do whatever they can to help the
898+system. It might be too late to consult with vmstat or any other
899+statistics, so it's advisable to take an immediate action.
900+
901+By default, events are propagated upward until the event is handled, i.e. the
902+events are not pass-through. For example, you have three cgroups: A->B->C. Now
903+you set up an event listener on cgroups A, B and C, and suppose group C
904+experiences some pressure. In this situation, only group C will receive the
905+notification, i.e. groups A and B will not receive it. This is done to avoid
906+excessive "broadcasting" of messages, which disturbs the system and which is
907+especially bad if we are low on memory or thrashing. Group B, will receive
908+notification only if there are no event listers for group C.
909+
910+There are three optional modes that specify different propagation behavior:
911+
912+ - "default": this is the default behavior specified above. This mode is the
913+ same as omitting the optional mode parameter, preserved by backwards
914+ compatibility.
915+
916+ - "hierarchy": events always propagate up to the root, similar to the default
917+ behavior, except that propagation continues regardless of whether there are
918+ event listeners at each level, with the "hierarchy" mode. In the above
919+ example, groups A, B, and C will receive notification of memory pressure.
920+
921+ - "local": events are pass-through, i.e. they only receive notifications when
922+ memory pressure is experienced in the memcg for which the notification is
923+ registered. In the above example, group C will receive notification if
924+ registered for "local" notification and the group experiences memory
925+ pressure. However, group B will never receive notification, regardless if
926+ there is an event listener for group C or not, if group B is registered for
927+ local notification.
928+
929+The level and event notification mode ("hierarchy" or "local", if necessary) are
930+specified by a comma-delimited string, i.e. "low,hierarchy" specifies
931+hierarchical, pass-through, notification for all ancestor memcgs. Notification
932+that is the default, non pass-through behavior, does not specify a mode.
933+"medium,local" specifies pass-through notification for the medium level.
934+
935+The file memory.pressure_level is only used to setup an eventfd. To
936+register a notification, an application must:
937+
938+- create an eventfd using eventfd(2);
939+- open memory.pressure_level;
940+- write string as "<event_fd> <fd of memory.pressure_level> <level[,mode]>"
941+ to cgroup.event_control.
942+
943+Application will be notified through eventfd when memory pressure is at
944+the specific level (or higher). Read/write operations to
945+memory.pressure_level are no implemented.
946+
947+Test:
948+
949+ Here is a small script example that makes a new cgroup, sets up a
950+ memory limit, sets up a notification in the cgroup and then makes child
951+ cgroup experience a critical pressure::
952+
953+ # cd /sys/fs/cgroup/memory/
954+ # mkdir foo
955+ # cd foo
956+ # cgroup_event_listener memory.pressure_level low,hierarchy &
957+ # echo 8000000 > memory.limit_in_bytes
958+ # echo 8000000 > memory.memsw.limit_in_bytes
959+ # echo $$ > tasks
960+ # dd if=/dev/zero | read x
961+
962+ (Expect a bunch of notifications, and eventually, the oom-killer will
963+ trigger.)
964+
965+12. TODO
966+========
967+
968+1. Make per-cgroup scanner reclaim not-shared pages first
969+2. Teach controller to account for shared-pages
970+3. Start reclamation in the background when the limit is
971+ not yet hit but the usage is getting closer
972+
973+Summary
974+=======
975+
976+Overall, the memory controller has been a stable controller and has been
977+commented and discussed quite extensively in the community.
978+
979+References
980+==========
981+
982+1. Singh, Balbir. RFC: Memory Controller, http://lwn.net/Articles/206697/
983+2. Singh, Balbir. Memory Controller (RSS Control),
984+ http://lwn.net/Articles/222762/
985+3. Emelianov, Pavel. Resource controllers based on process cgroups
986+ http://lkml.org/lkml/2007/3/6/198
987+4. Emelianov, Pavel. RSS controller based on process cgroups (v2)
988+ http://lkml.org/lkml/2007/4/9/78
989+5. Emelianov, Pavel. RSS controller based on process cgroups (v3)
990+ http://lkml.org/lkml/2007/5/30/244
991+6. Menage, Paul. Control Groups v10, http://lwn.net/Articles/236032/
992+7. Vaidyanathan, Srinivasan, Control Groups: Pagecache accounting and control
993+ subsystem (v3), http://lwn.net/Articles/235534/
994+8. Singh, Balbir. RSS controller v2 test results (lmbench),
995+ http://lkml.org/lkml/2007/5/17/232
996+9. Singh, Balbir. RSS controller v2 AIM9 results
997+ http://lkml.org/lkml/2007/5/18/1
998+10. Singh, Balbir. Memory controller v6 test results,
999+ http://lkml.org/lkml/2007/8/19/36
1000+11. Singh, Balbir. Memory controller introduction (v6),
1001+ http://lkml.org/lkml/2007/8/17/69
1002+12. Corbet, Jonathan, Controlling memory use in cgroups,
1003+ http://lwn.net/Articles/243795/
Documentation/admin-guide/cgroup-v1/net_cls.rst+44−0
@@ -0,0 +1,44 @@
1+=========================
2+Network classifier cgroup
3+=========================
4+
5+The Network classifier cgroup provides an interface to
6+tag network packets with a class identifier (classid).
7+
8+The Traffic Controller (tc) can be used to assign
9+different priorities to packets from different cgroups.
10+Also, Netfilter (iptables) can use this tag to perform
11+actions on such packets.
12+
13+Creating a net_cls cgroups instance creates a net_cls.classid file.
14+This net_cls.classid value is initialized to 0.
15+
16+You can write hexadecimal values to net_cls.classid; the format for these
17+values is 0xAAAABBBB; AAAA is the major handle number and BBBB
18+is the minor handle number.
19+Reading net_cls.classid yields a decimal result.
20+
21+Example::
22+
23+ mkdir /sys/fs/cgroup/net_cls
24+ mount -t cgroup -onet_cls net_cls /sys/fs/cgroup/net_cls
25+ mkdir /sys/fs/cgroup/net_cls/0
26+ echo 0x100001 > /sys/fs/cgroup/net_cls/0/net_cls.classid
27+
28+- setting a 10:1 handle::
29+
30+ cat /sys/fs/cgroup/net_cls/0/net_cls.classid
31+ 1048577
32+
33+- configuring tc::
34+
35+ tc qdisc add dev eth0 root handle 10: htb
36+ tc class add dev eth0 parent 10: classid 10:1 htb rate 40mbit
37+
38+- creating traffic class 10:1::
39+
40+ tc filter add dev eth0 parent 10: protocol ip prio 10 handle 1: cgroup
41+
42+configuring iptables, basic example::
43+
44+ iptables -A OUTPUT -m cgroup ! --cgroup 0x100001 -j DROP
Documentation/admin-guide/cgroup-v1/net_prio.rst+57−0
@@ -0,0 +1,57 @@
1+=======================
2+Network priority cgroup
3+=======================
4+
5+The Network priority cgroup provides an interface to allow an administrator to
6+dynamically set the priority of network traffic generated by various
7+applications
8+
9+Nominally, an application would set the priority of its traffic via the
10+SO_PRIORITY socket option. This however, is not always possible because:
11+
12+1) The application may not have been coded to set this value
13+2) The priority of application traffic is often a site-specific administrative
14+ decision rather than an application defined one.
15+
16+This cgroup allows an administrator to assign a process to a group which defines
17+the priority of egress traffic on a given interface. Network priority groups can
18+be created by first mounting the cgroup filesystem::
19+
20+ # mount -t cgroup -onet_prio none /sys/fs/cgroup/net_prio
21+
22+With the above step, the initial group acting as the parent accounting group
23+becomes visible at '/sys/fs/cgroup/net_prio'. This group includes all tasks in
24+the system. '/sys/fs/cgroup/net_prio/tasks' lists the tasks in this cgroup.
25+
26+Each net_prio cgroup contains two files that are subsystem specific
27+
28+net_prio.prioidx
29+ This file is read-only, and is simply informative. It contains a unique
30+ integer value that the kernel uses as an internal representation of this
31+ cgroup.
32+
33+net_prio.ifpriomap
34+ This file contains a map of the priorities assigned to traffic originating
35+ from processes in this group and egressing the system on various interfaces.
36+ It contains a list of tuples in the form <ifname priority>. Contents of this
37+ file can be modified by echoing a string into the file using the same tuple
38+ format. For example::
39+
40+ echo "eth0 5" > /sys/fs/cgroups/net_prio/iscsi/net_prio.ifpriomap
41+
42+This command would force any traffic originating from processes belonging to the
43+iscsi net_prio cgroup and egressing on interface eth0 to have the priority of
44+said traffic set to the value 5. The parent accounting group also has a
45+writeable 'net_prio.ifpriomap' file that can be used to set a system default
46+priority.
47+
48+Priorities are set immediately prior to queueing a frame to the device
49+queueing discipline (qdisc) so priorities will be assigned prior to the hardware
50+queue selection being made.
51+
52+One usage for the net_prio cgroup is with mqprio qdisc allowing application
53+traffic to be steered to hardware/driver based traffic classes. These mappings
54+can then be managed by administrators or other networking protocols such as
55+DCBX.
56+
57+A new net_prio cgroup inherits the parent's configuration.
Documentation/admin-guide/cgroup-v1/pids.rst+92−0
@@ -0,0 +1,92 @@
1+=========================
2+Process Number Controller
3+=========================
4+
5+Abstract
6+--------
7+
8+The process number controller is used to allow a cgroup hierarchy to stop any
9+new tasks from being fork()'d or clone()'d after a certain limit is reached.
10+
11+Since it is trivial to hit the task limit without hitting any kmemcg limits in
12+place, PIDs are a fundamental resource. As such, PID exhaustion must be
13+preventable in the scope of a cgroup hierarchy by allowing resource limiting of
14+the number of tasks in a cgroup.
15+
16+Usage
17+-----
18+
19+In order to use the `pids` controller, set the maximum number of tasks in
20+pids.max (this is not available in the root cgroup for obvious reasons). The
21+number of processes currently in the cgroup is given by pids.current.
22+
23+Organisational operations are not blocked by cgroup policies, so it is possible
24+to have pids.current > pids.max. This can be done by either setting the limit to
25+be smaller than pids.current, or attaching enough processes to the cgroup such
26+that pids.current > pids.max. However, it is not possible to violate a cgroup
27+policy through fork() or clone(). fork() and clone() will return -EAGAIN if the
28+creation of a new process would cause a cgroup policy to be violated.
29+
30+To set a cgroup to have no limit, set pids.max to "max". This is the default for
31+all new cgroups (N.B. that PID limits are hierarchical, so the most stringent
32+limit in the hierarchy is followed).
33+
34+pids.current tracks all child cgroup hierarchies, so parent/pids.current is a
35+superset of parent/child/pids.current.
36+
37+The pids.events file contains event counters:
38+
39+ - max: Number of times fork failed because limit was hit.
40+
41+Example
42+-------
43+
44+First, we mount the pids controller::
45+
46+ # mkdir -p /sys/fs/cgroup/pids
47+ # mount -t cgroup -o pids none /sys/fs/cgroup/pids
48+
49+Then we create a hierarchy, set limits and attach processes to it::
50+
51+ # mkdir -p /sys/fs/cgroup/pids/parent/child
52+ # echo 2 > /sys/fs/cgroup/pids/parent/pids.max
53+ # echo $$ > /sys/fs/cgroup/pids/parent/cgroup.procs
54+ # cat /sys/fs/cgroup/pids/parent/pids.current
55+ 2
56+ #
57+
58+It should be noted that attempts to overcome the set limit (2 in this case) will
59+fail::
60+
61+ # cat /sys/fs/cgroup/pids/parent/pids.current
62+ 2
63+ # ( /bin/echo "Here's some processes for you." | cat )
64+ sh: fork: Resource temporary unavailable
65+ #
66+
67+Even if we migrate to a child cgroup (which doesn't have a set limit), we will
68+not be able to overcome the most stringent limit in the hierarchy (in this case,
69+parent's)::
70+
71+ # echo $$ > /sys/fs/cgroup/pids/parent/child/cgroup.procs
72+ # cat /sys/fs/cgroup/pids/parent/pids.current
73+ 2
74+ # cat /sys/fs/cgroup/pids/parent/child/pids.current
75+ 2
76+ # cat /sys/fs/cgroup/pids/parent/child/pids.max
77+ max
78+ # ( /bin/echo "Here's some processes for you." | cat )
79+ sh: fork: Resource temporary unavailable
80+ #
81+
82+We can set a limit that is smaller than pids.current, which will stop any new
83+processes from being forked at all (note that the shell itself counts towards
84+pids.current)::
85+
86+ # echo 1 > /sys/fs/cgroup/pids/parent/pids.max
87+ # /bin/echo "We can't even spawn a single process now."
88+ sh: fork: Resource temporary unavailable
89+ # echo 0 > /sys/fs/cgroup/pids/parent/pids.max
90+ # /bin/echo "We can't even spawn a single process now."
91+ sh: fork: Resource temporary unavailable
92+ #
Documentation/admin-guide/cgroup-v1/rdma.rst+117−0
@@ -0,0 +1,117 @@
1+===============
2+RDMA Controller
3+===============
4+
5+.. Contents
6+
7+ 1. Overview
8+ 1-1. What is RDMA controller?
9+ 1-2. Why RDMA controller needed?
10+ 1-3. How is RDMA controller implemented?
11+ 2. Usage Examples
12+
13+1. Overview
14+===========
15+
16+1-1. What is RDMA controller?
17+-----------------------------
18+
19+RDMA controller allows user to limit RDMA/IB specific resources that a given
20+set of processes can use. These processes are grouped using RDMA controller.
21+
22+RDMA controller defines two resources which can be limited for processes of a
23+cgroup.
24+
25+1-2. Why RDMA controller needed?
26+--------------------------------
27+
28+Currently user space applications can easily take away all the rdma verb
29+specific resources such as AH, CQ, QP, MR etc. Due to which other applications
30+in other cgroup or kernel space ULPs may not even get chance to allocate any
31+rdma resources. This can lead to service unavailability.
32+
33+Therefore RDMA controller is needed through which resource consumption
34+of processes can be limited. Through this controller different rdma
35+resources can be accounted.
36+
37+1-3. How is RDMA controller implemented?
38+----------------------------------------
39+
40+RDMA cgroup allows limit configuration of resources. Rdma cgroup maintains
41+resource accounting per cgroup, per device using resource pool structure.
42+Each such resource pool is limited up to 64 resources in given resource pool
43+by rdma cgroup, which can be extended later if required.
44+
45+This resource pool object is linked to the cgroup css. Typically there
46+are 0 to 4 resource pool instances per cgroup, per device in most use cases.
47+But nothing limits to have it more. At present hundreds of RDMA devices per
48+single cgroup may not be handled optimally, however there is no
49+known use case or requirement for such configuration either.
50+
51+Since RDMA resources can be allocated from any process and can be freed by any
52+of the child processes which shares the address space, rdma resources are
53+always owned by the creator cgroup css. This allows process migration from one
54+to other cgroup without major complexity of transferring resource ownership;
55+because such ownership is not really present due to shared nature of
56+rdma resources. Linking resources around css also ensures that cgroups can be
57+deleted after processes migrated. This allow progress migration as well with
58+active resources, even though that is not a primary use case.
59+
60+Whenever RDMA resource charging occurs, owner rdma cgroup is returned to
61+the caller. Same rdma cgroup should be passed while uncharging the resource.
62+This also allows process migrated with active RDMA resource to charge
63+to new owner cgroup for new resource. It also allows to uncharge resource of
64+a process from previously charged cgroup which is migrated to new cgroup,
65+even though that is not a primary use case.
66+
67+Resource pool object is created in following situations.
68+(a) User sets the limit and no previous resource pool exist for the device
69+of interest for the cgroup.
70+(b) No resource limits were configured, but IB/RDMA stack tries to
71+charge the resource. So that it correctly uncharge them when applications are
72+running without limits and later on when limits are enforced during uncharging,
73+otherwise usage count will drop to negative.
74+
75+Resource pool is destroyed if all the resource limits are set to max and
76+it is the last resource getting deallocated.
77+
78+User should set all the limit to max value if it intents to remove/unconfigure
79+the resource pool for a particular device.
80+
81+IB stack honors limits enforced by the rdma controller. When application
82+query about maximum resource limits of IB device, it returns minimum of
83+what is configured by user for a given cgroup and what is supported by
84+IB device.
85+
86+Following resources can be accounted by rdma controller.
87+
88+ ========== =============================
89+ hca_handle Maximum number of HCA Handles
90+ hca_object Maximum number of HCA Objects
91+ ========== =============================
92+
93+2. Usage Examples
94+=================
95+
96+(a) Configure resource limit::
97+
98+ echo mlx4_0 hca_handle=2 hca_object=2000 > /sys/fs/cgroup/rdma/1/rdma.max
99+ echo ocrdma1 hca_handle=3 > /sys/fs/cgroup/rdma/2/rdma.max
100+
101+(b) Query resource limit::
102+
103+ cat /sys/fs/cgroup/rdma/2/rdma.max
104+ #Output:
105+ mlx4_0 hca_handle=2 hca_object=2000
106+ ocrdma1 hca_handle=3 hca_object=max
107+
108+(c) Query current usage::
109+
110+ cat /sys/fs/cgroup/rdma/2/rdma.current
111+ #Output:
112+ mlx4_0 hca_handle=1 hca_object=20
113+ ocrdma1 hca_handle=1 hca_object=23
114+
115+(d) Delete resource limit::
116+
117+ echo echo mlx4_0 hca_handle=max hca_object=max > /sys/fs/cgroup/rdma/1/rdma.max
Documentation/admin-guide/cgroup-v2.rst+21−5
@@ -9,7 +9,7 @@ This is the authoritative documentation on the design, interface and · 8 unmodified lines
99 conventions of cgroup v2. It describes all userland-visible aspects
1010 of cgroup including core and specific controller behaviors. All
1111 future changes must be reflected in this document. Documentation for
12−v1 is available under Documentation/cgroup-v1/.
12+v1 is available under Documentation/admin-guide/cgroup-v1/.
1313
1414 .. CONTENTS
1515
@@ -705,6 +705,12 @@ Conventions · 689 unmodified lines
705705 informational files on the root cgroup which end up showing global
706706 information available elsewhere shouldn't exist.
707707
708+- The default time unit is microseconds. If a different unit is ever
709+ used, an explicit unit suffix must be present.
710+
711+- A parts-per quantity should use a percentage decimal with at least
712+ two digit fractional part - e.g. 13.40.
713+
708714 - If a controller implements weight based resource distribution, its
709715 interface file should be named "weight" and have the range [1,
710716 10000] with 100 as the default. The values are chosen to allow
@@ -1008,7 +1014,7 @@ All time durations are in microseconds. · 297 unmodified lines
10081014 A read-only nested-key file which exists on non-root cgroups.
10091015
10101016 Shows pressure stall information for CPU. See
1011− Documentation/accounting/psi.txt for details.
1017+ Documentation/accounting/psi.rst for details.
10121018
10131019
10141020 Memory
@@ -1140,6 +1146,11 @@ PAGE_SIZE multiple when read back. · 125 unmodified lines
11401146 otherwise, a value change in this file generates a file
11411147 modified event.
11421148
1149+ Note that all fields in this file are hierarchical and the
1150+ file modified event can be generated due to an event down the
1151+ hierarchy. For for the local events at the cgroup level see
1152+ memory.events.local.
1153+
11431154 low
11441155 The number of times the cgroup is reclaimed due to
11451156 high memory pressure even though its usage is under
@@ -1179,6 +1190,11 @@ PAGE_SIZE multiple when read back. · 33 unmodified lines
11791190 The number of processes belonging to this cgroup
11801191 killed by any kind of OOM killer.
11811192
1193+ memory.events.local
1194+ Similar to memory.events but the fields in the file are local
1195+ to the cgroup i.e. not hierarchical. The file modified event
1196+ generated on this file reflects only the local events.
1197+
11821198 memory.stat
11831199 A read-only flat-keyed file which exists on non-root cgroups.
11841200
@@ -1339,7 +1355,7 @@ PAGE_SIZE multiple when read back. · 154 unmodified lines
13391355 A read-only nested-key file which exists on non-root cgroups.
13401356
13411357 Shows pressure stall information for memory. See
1342− Documentation/accounting/psi.txt for details.
1358+ Documentation/accounting/psi.rst for details.
13431359
13441360
13451361 Usage Guidelines
@@ -1482,7 +1498,7 @@ IO Interface Files · 136 unmodified lines
14821498 A read-only nested-key file which exists on non-root cgroups.
14831499
14841500 Shows pressure stall information for IO. See
1485− Documentation/accounting/psi.txt for details.
1501+ Documentation/accounting/psi.rst for details.
14861502
14871503
14881504 Writeback
@@ -2108,7 +2124,7 @@ following two functions. · 619 unmodified lines
21082124 a queue (device) has been associated with the bio and
21092125 before submission.
21102126
2111− wbc_account_io(@wbc, @page, @bytes)
2127+ wbc_account_cgroup_owner(@wbc, @page, @bytes)
21122128 Should be called for each data segment being written out.
21132129 While this function doesn't care exactly when it's called
21142130 during the writeback session, it's the easiest and most
Documentation/admin-guide/clearing-warn-once.rstrenamed from Documentation/clearing-warn-once.txt+0−0

File renamed without changes.

Documentation/admin-guide/conf.py+0−10
@@ -1,10 +0,0 @@
1−# -*- coding: utf-8; mode: python -*-
2−
3−project = 'Linux Kernel User Documentation'
4−
5−tags.add("subproject")
6−
7−latex_documents = [
8− ('index', 'linux-user.tex', 'Linux Kernel User Documentation',
9− 'The kernel development community', 'manual'),
10−]
Documentation/admin-guide/cpu-load.rstrenamed from Documentation/cpu-load.txt+0−0

File renamed without changes.

Documentation/admin-guide/cputopology.rst+177−0
@@ -0,0 +1,177 @@
1+===========================================
2+How CPU topology info is exported via sysfs
3+===========================================
4+
5+Export CPU topology info via sysfs. Items (attributes) are similar
6+to /proc/cpuinfo output of some architectures. They reside in
7+/sys/devices/system/cpu/cpuX/topology/:
8+
9+physical_package_id:
10+
11+ physical package id of cpuX. Typically corresponds to a physical
12+ socket number, but the actual value is architecture and platform
13+ dependent.
14+
15+die_id:
16+
17+ the CPU die ID of cpuX. Typically it is the hardware platform's
18+ identifier (rather than the kernel's). The actual value is
19+ architecture and platform dependent.
20+
21+core_id:
22+
23+ the CPU core ID of cpuX. Typically it is the hardware platform's
24+ identifier (rather than the kernel's). The actual value is
25+ architecture and platform dependent.
26+
27+book_id:
28+
29+ the book ID of cpuX. Typically it is the hardware platform's
30+ identifier (rather than the kernel's). The actual value is
31+ architecture and platform dependent.
32+
33+drawer_id:
34+
35+ the drawer ID of cpuX. Typically it is the hardware platform's
36+ identifier (rather than the kernel's). The actual value is
37+ architecture and platform dependent.
38+
39+core_cpus:
40+
41+ internal kernel map of CPUs within the same core.
42+ (deprecated name: "thread_siblings")
43+
44+core_cpus_list:
45+
46+ human-readable list of CPUs within the same core.
47+ (deprecated name: "thread_siblings_list");
48+
49+package_cpus:
50+
51+ internal kernel map of the CPUs sharing the same physical_package_id.
52+ (deprecated name: "core_siblings")
53+
54+package_cpus_list:
55+
56+ human-readable list of CPUs sharing the same physical_package_id.
57+ (deprecated name: "core_siblings_list")
58+
59+die_cpus:
60+
61+ internal kernel map of CPUs within the same die.
62+
63+die_cpus_list:
64+
65+ human-readable list of CPUs within the same die.
66+
67+book_siblings:
68+
69+ internal kernel map of cpuX's hardware threads within the same
70+ book_id.
71+
72+book_siblings_list:
73+
74+ human-readable list of cpuX's hardware threads within the same
75+ book_id.
76+
77+drawer_siblings:
78+
79+ internal kernel map of cpuX's hardware threads within the same
80+ drawer_id.
81+
82+drawer_siblings_list:
83+
84+ human-readable list of cpuX's hardware threads within the same
85+ drawer_id.
86+
87+Architecture-neutral, drivers/base/topology.c, exports these attributes.
88+However, the book and drawer related sysfs files will only be created if
89+CONFIG_SCHED_BOOK and CONFIG_SCHED_DRAWER are selected, respectively.
90+
91+CONFIG_SCHED_BOOK and CONFIG_SCHED_DRAWER are currently only used on s390,
92+where they reflect the cpu and cache hierarchy.
93+
94+For an architecture to support this feature, it must define some of
95+these macros in include/asm-XXX/topology.h::
96+
97+ #define topology_physical_package_id(cpu)
98+ #define topology_die_id(cpu)
99+ #define topology_core_id(cpu)
100+ #define topology_book_id(cpu)
101+ #define topology_drawer_id(cpu)
102+ #define topology_sibling_cpumask(cpu)
103+ #define topology_core_cpumask(cpu)
104+ #define topology_die_cpumask(cpu)
105+ #define topology_book_cpumask(cpu)
106+ #define topology_drawer_cpumask(cpu)
107+
108+The type of ``**_id macros`` is int.
109+The type of ``**_cpumask macros`` is ``(const) struct cpumask *``. The latter
110+correspond with appropriate ``**_siblings`` sysfs attributes (except for
111+topology_sibling_cpumask() which corresponds with thread_siblings).
112+
113+To be consistent on all architectures, include/linux/topology.h
114+provides default definitions for any of the above macros that are
115+not defined by include/asm-XXX/topology.h:
116+
117+1) topology_physical_package_id: -1
118+2) topology_die_id: -1
119+3) topology_core_id: 0
120+4) topology_sibling_cpumask: just the given CPU
121+5) topology_core_cpumask: just the given CPU
122+6) topology_die_cpumask: just the given CPU
123+
124+For architectures that don't support books (CONFIG_SCHED_BOOK) there are no
125+default definitions for topology_book_id() and topology_book_cpumask().
126+For architectures that don't support drawers (CONFIG_SCHED_DRAWER) there are
127+no default definitions for topology_drawer_id() and topology_drawer_cpumask().
128+
129+Additionally, CPU topology information is provided under
130+/sys/devices/system/cpu and includes these files. The internal
131+source for the output is in brackets ("[]").
132+
133+ =========== ==========================================================
134+ kernel_max: the maximum CPU index allowed by the kernel configuration.
135+ [NR_CPUS-1]
136+
137+ offline: CPUs that are not online because they have been
138+ HOTPLUGGED off (see cpu-hotplug.txt) or exceed the limit
139+ of CPUs allowed by the kernel configuration (kernel_max
140+ above). [~cpu_online_mask + cpus >= NR_CPUS]
141+
142+ online: CPUs that are online and being scheduled [cpu_online_mask]
143+
144+ possible: CPUs that have been allocated resources and can be
145+ brought online if they are present. [cpu_possible_mask]
146+
147+ present: CPUs that have been identified as being present in the
148+ system. [cpu_present_mask]
149+ =========== ==========================================================
150+
151+The format for the above output is compatible with cpulist_parse()
152+[see <linux/cpumask.h>]. Some examples follow.
153+
154+In this example, there are 64 CPUs in the system but cpus 32-63 exceed
155+the kernel max which is limited to 0..31 by the NR_CPUS config option
156+being 32. Note also that CPUs 2 and 4-31 are not online but could be
157+brought online as they are both present and possible::
158+
159+ kernel_max: 31
160+ offline: 2,4-31,32-63
161+ online: 0-1,3
162+ possible: 0-31
163+ present: 0-31
164+
165+In this example, the NR_CPUS config option is 128, but the kernel was
166+started with possible_cpus=144. There are 4 CPUs in the system and cpu2
167+was manually taken offline (and is the only CPU that can be brought
168+online.)::
169+
170+ kernel_max: 127
171+ offline: 2,4-127,128-143
172+ online: 0-1,3
173+ possible: 0-127
174+ present: 0-3
175+
176+See cpu-hotplug.txt for the possible_cpus=NUM kernel start parameter
177+as well as more information on the various cpumasks.
Documentation/admin-guide/device-mapper/cache-policies.rst+131−0
@@ -0,0 +1,131 @@
1+=============================
2+Guidance for writing policies
3+=============================
4+
5+Try to keep transactionality out of it. The core is careful to
6+avoid asking about anything that is migrating. This is a pain, but
7+makes it easier to write the policies.
8+
9+Mappings are loaded into the policy at construction time.
10+
11+Every bio that is mapped by the target is referred to the policy.
12+The policy can return a simple HIT or MISS or issue a migration.
13+
14+Currently there's no way for the policy to issue background work,
15+e.g. to start writing back dirty blocks that are going to be evicted
16+soon.
17+
18+Because we map bios, rather than requests it's easy for the policy
19+to get fooled by many small bios. For this reason the core target
20+issues periodic ticks to the policy. It's suggested that the policy
21+doesn't update states (eg, hit counts) for a block more than once
22+for each tick. The core ticks by watching bios complete, and so
23+trying to see when the io scheduler has let the ios run.
24+
25+
26+Overview of supplied cache replacement policies
27+===============================================
28+
29+multiqueue (mq)
30+---------------
31+
32+This policy is now an alias for smq (see below).
33+
34+The following tunables are accepted, but have no effect::
35+
36+ 'sequential_threshold <#nr_sequential_ios>'
37+ 'random_threshold <#nr_random_ios>'
38+ 'read_promote_adjustment <value>'
39+ 'write_promote_adjustment <value>'
40+ 'discard_promote_adjustment <value>'
41+
42+Stochastic multiqueue (smq)
43+---------------------------
44+
45+This policy is the default.
46+
47+The stochastic multi-queue (smq) policy addresses some of the problems
48+with the multiqueue (mq) policy.
49+
50+The smq policy (vs mq) offers the promise of less memory utilization,
51+improved performance and increased adaptability in the face of changing
52+workloads. smq also does not have any cumbersome tuning knobs.
53+
54+Users may switch from "mq" to "smq" simply by appropriately reloading a
55+DM table that is using the cache target. Doing so will cause all of the
56+mq policy's hints to be dropped. Also, performance of the cache may
57+degrade slightly until smq recalculates the origin device's hotspots
58+that should be cached.
59+
60+Memory usage
61+^^^^^^^^^^^^
62+
63+The mq policy used a lot of memory; 88 bytes per cache block on a 64
64+bit machine.
65+
66+smq uses 28bit indexes to implement its data structures rather than
67+pointers. It avoids storing an explicit hit count for each block. It
68+has a 'hotspot' queue, rather than a pre-cache, which uses a quarter of
69+the entries (each hotspot block covers a larger area than a single
70+cache block).
71+
72+All this means smq uses ~25bytes per cache block. Still a lot of
73+memory, but a substantial improvement nontheless.
74+
75+Level balancing
76+^^^^^^^^^^^^^^^
77+
78+mq placed entries in different levels of the multiqueue structures
79+based on their hit count (~ln(hit count)). This meant the bottom
80+levels generally had the most entries, and the top ones had very
81+few. Having unbalanced levels like this reduced the efficacy of the
82+multiqueue.
83+
84+smq does not maintain a hit count, instead it swaps hit entries with
85+the least recently used entry from the level above. The overall
86+ordering being a side effect of this stochastic process. With this
87+scheme we can decide how many entries occupy each multiqueue level,
88+resulting in better promotion/demotion decisions.
89+
90+Adaptability:
91+The mq policy maintained a hit count for each cache block. For a
92+different block to get promoted to the cache its hit count has to
93+exceed the lowest currently in the cache. This meant it could take a
94+long time for the cache to adapt between varying IO patterns.
95+
96+smq doesn't maintain hit counts, so a lot of this problem just goes
97+away. In addition it tracks performance of the hotspot queue, which
98+is used to decide which blocks to promote. If the hotspot queue is
99+performing badly then it starts moving entries more quickly between
100+levels. This lets it adapt to new IO patterns very quickly.
101+
102+Performance
103+^^^^^^^^^^^
104+
105+Testing smq shows substantially better performance than mq.
106+
107+cleaner
108+-------
109+
110+The cleaner writes back all dirty blocks in a cache to decommission it.
111+
112+Examples
113+========
114+
115+The syntax for a table is::
116+
117+ cache <metadata dev> <cache dev> <origin dev> <block size>
118+ <#feature_args> [<feature arg>]*
119+ <policy> <#policy_args> [<policy arg>]*
120+
121+The syntax to send a message using the dmsetup command is::
122+
123+ dmsetup message <mapped device> 0 sequential_threshold 1024
124+ dmsetup message <mapped device> 0 random_threshold 8
125+
126+Using dmsetup::
127+
128+ dmsetup create blah --table "0 268435456 cache /dev/sdb /dev/sdc \
129+ /dev/sdd 512 0 mq 4 sequential_threshold 1024 random_threshold 8"
130+ creates a 128GB large mapped device named 'blah' with the
131+ sequential threshold set to 1024 and the random_threshold set to 8.
Documentation/admin-guide/device-mapper/cache.rst+337−0
@@ -0,0 +1,337 @@
1+=====
2+Cache
3+=====
4+
5+Introduction
6+============
7+
8+dm-cache is a device mapper target written by Joe Thornber, Heinz
9+Mauelshagen, and Mike Snitzer.
10+
11+It aims to improve performance of a block device (eg, a spindle) by
12+dynamically migrating some of its data to a faster, smaller device
13+(eg, an SSD).
14+
15+This device-mapper solution allows us to insert this caching at
16+different levels of the dm stack, for instance above the data device for
17+a thin-provisioning pool. Caching solutions that are integrated more
18+closely with the virtual memory system should give better performance.
19+
20+The target reuses the metadata library used in the thin-provisioning
21+library.
22+
23+The decision as to what data to migrate and when is left to a plug-in
24+policy module. Several of these have been written as we experiment,
25+and we hope other people will contribute others for specific io
26+scenarios (eg. a vm image server).
27+
28+Glossary
29+========
30+
31+ Migration
32+ Movement of the primary copy of a logical block from one
33+ device to the other.
34+ Promotion
35+ Migration from slow device to fast device.
36+ Demotion
37+ Migration from fast device to slow device.
38+
39+The origin device always contains a copy of the logical block, which
40+may be out of date or kept in sync with the copy on the cache device
41+(depending on policy).
42+
43+Design
44+======
45+
46+Sub-devices
47+-----------
48+
49+The target is constructed by passing three devices to it (along with
50+other parameters detailed later):
51+
52+1. An origin device - the big, slow one.
53+
54+2. A cache device - the small, fast one.
55+
56+3. A small metadata device - records which blocks are in the cache,
57+ which are dirty, and extra hints for use by the policy object.
58+ This information could be put on the cache device, but having it
59+ separate allows the volume manager to configure it differently,
60+ e.g. as a mirror for extra robustness. This metadata device may only
61+ be used by a single cache device.
62+
63+Fixed block size
64+----------------
65+
66+The origin is divided up into blocks of a fixed size. This block size
67+is configurable when you first create the cache. Typically we've been
68+using block sizes of 256KB - 1024KB. The block size must be between 64
69+sectors (32KB) and 2097152 sectors (1GB) and a multiple of 64 sectors (32KB).
70+
71+Having a fixed block size simplifies the target a lot. But it is
72+something of a compromise. For instance, a small part of a block may be
73+getting hit a lot, yet the whole block will be promoted to the cache.
74+So large block sizes are bad because they waste cache space. And small
75+block sizes are bad because they increase the amount of metadata (both
76+in core and on disk).
77+
78+Cache operating modes
79+---------------------
80+
81+The cache has three operating modes: writeback, writethrough and
82+passthrough.
83+
84+If writeback, the default, is selected then a write to a block that is
85+cached will go only to the cache and the block will be marked dirty in
86+the metadata.
87+
88+If writethrough is selected then a write to a cached block will not
89+complete until it has hit both the origin and cache devices. Clean
90+blocks should remain clean.
91+
92+If passthrough is selected, useful when the cache contents are not known
93+to be coherent with the origin device, then all reads are served from
94+the origin device (all reads miss the cache) and all writes are
95+forwarded to the origin device; additionally, write hits cause cache
96+block invalidates. To enable passthrough mode the cache must be clean.
97+Passthrough mode allows a cache device to be activated without having to
98+worry about coherency. Coherency that exists is maintained, although
99+the cache will gradually cool as writes take place. If the coherency of
100+the cache can later be verified, or established through use of the
101+"invalidate_cblocks" message, the cache device can be transitioned to
102+writethrough or writeback mode while still warm. Otherwise, the cache
103+contents can be discarded prior to transitioning to the desired
104+operating mode.
105+
106+A simple cleaner policy is provided, which will clean (write back) all
107+dirty blocks in a cache. Useful for decommissioning a cache or when
108+shrinking a cache. Shrinking the cache's fast device requires all cache
109+blocks, in the area of the cache being removed, to be clean. If the
110+area being removed from the cache still contains dirty blocks the resize
111+will fail. Care must be taken to never reduce the volume used for the
112+cache's fast device until the cache is clean. This is of particular
113+importance if writeback mode is used. Writethrough and passthrough
114+modes already maintain a clean cache. Future support to partially clean
115+the cache, above a specified threshold, will allow for keeping the cache
116+warm and in writeback mode during resize.
117+
118+Migration throttling
119+--------------------
120+
121+Migrating data between the origin and cache device uses bandwidth.
122+The user can set a throttle to prevent more than a certain amount of
123+migration occurring at any one time. Currently we're not taking any
124+account of normal io traffic going to the devices. More work needs
125+doing here to avoid migrating during those peak io moments.
126+
127+For the time being, a message "migration_threshold <#sectors>"
128+can be used to set the maximum number of sectors being migrated,
129+the default being 2048 sectors (1MB).
130+
131+Updating on-disk metadata
132+-------------------------
133+
134+On-disk metadata is committed every time a FLUSH or FUA bio is written.
135+If no such requests are made then commits will occur every second. This
136+means the cache behaves like a physical disk that has a volatile write
137+cache. If power is lost you may lose some recent writes. The metadata
138+should always be consistent in spite of any crash.
139+
140+The 'dirty' state for a cache block changes far too frequently for us
141+to keep updating it on the fly. So we treat it as a hint. In normal
142+operation it will be written when the dm device is suspended. If the
143+system crashes all cache blocks will be assumed dirty when restarted.
144+
145+Per-block policy hints
146+----------------------
147+
148+Policy plug-ins can store a chunk of data per cache block. It's up to
149+the policy how big this chunk is, but it should be kept small. Like the
150+dirty flags this data is lost if there's a crash so a safe fallback
151+value should always be possible.
152+
153+Policy hints affect performance, not correctness.
154+
155+Policy messaging
156+----------------
157+
158+Policies will have different tunables, specific to each one, so we
159+need a generic way of getting and setting these. Device-mapper
160+messages are used. Refer to cache-policies.txt.
161+
162+Discard bitset resolution
163+-------------------------
164+
165+We can avoid copying data during migration if we know the block has
166+been discarded. A prime example of this is when mkfs discards the
167+whole block device. We store a bitset tracking the discard state of
168+blocks. However, we allow this bitset to have a different block size
169+from the cache blocks. This is because we need to track the discard
170+state for all of the origin device (compare with the dirty bitset
171+which is just for the smaller cache device).
172+
173+Target interface
174+================
175+
176+Constructor
177+-----------
178+
179+ ::
180+
181+ cache <metadata dev> <cache dev> <origin dev> <block size>
182+ <#feature args> [<feature arg>]*
183+ <policy> <#policy args> [policy args]*
184+
185+ ================ =======================================================
186+ metadata dev fast device holding the persistent metadata
187+ cache dev fast device holding cached data blocks
188+ origin dev slow device holding original data blocks
189+ block size cache unit size in sectors
190+
191+ #feature args number of feature arguments passed
192+ feature args writethrough or passthrough (The default is writeback.)
193+
194+ policy the replacement policy to use
195+ #policy args an even number of arguments corresponding to
196+ key/value pairs passed to the policy
197+ policy args key/value pairs passed to the policy
198+ E.g. 'sequential_threshold 1024'
199+ See cache-policies.txt for details.
200+ ================ =======================================================
201+
202+Optional feature arguments are:
203+
204+
205+ ==================== ========================================================
206+ writethrough write through caching that prohibits cache block
207+ content from being different from origin block content.
208+ Without this argument, the default behaviour is to write
209+ back cache block contents later for performance reasons,
210+ so they may differ from the corresponding origin blocks.
211+
212+ passthrough a degraded mode useful for various cache coherency
213+ situations (e.g., rolling back snapshots of
214+ underlying storage). Reads and writes always go to
215+ the origin. If a write goes to a cached origin
216+ block, then the cache block is invalidated.
217+ To enable passthrough mode the cache must be clean.
218+
219+ metadata2 use version 2 of the metadata. This stores the dirty
220+ bits in a separate btree, which improves speed of
221+ shutting down the cache.
222+
223+ no_discard_passdown disable passing down discards from the cache
224+ to the origin's data device.
225+ ==================== ========================================================
226+
227+A policy called 'default' is always registered. This is an alias for
228+the policy we currently think is giving best all round performance.
229+
230+As the default policy could vary between kernels, if you are relying on
231+the characteristics of a specific policy, always request it by name.
232+
233+Status
234+------
235+
236+::
237+
238+ <metadata block size> <#used metadata blocks>/<#total metadata blocks>
239+ <cache block size> <#used cache blocks>/<#total cache blocks>
240+ <#read hits> <#read misses> <#write hits> <#write misses>
241+ <#demotions> <#promotions> <#dirty> <#features> <features>*
242+ <#core args> <core args>* <policy name> <#policy args> <policy args>*
243+ <cache metadata mode>
244+
245+
246+========================= =====================================================
247+metadata block size Fixed block size for each metadata block in
248+ sectors
249+#used metadata blocks Number of metadata blocks used
250+#total metadata blocks Total number of metadata blocks
251+cache block size Configurable block size for the cache device
252+ in sectors
253+#used cache blocks Number of blocks resident in the cache
254+#total cache blocks Total number of cache blocks
255+#read hits Number of times a READ bio has been mapped
256+ to the cache
257+#read misses Number of times a READ bio has been mapped
258+ to the origin
259+#write hits Number of times a WRITE bio has been mapped
260+ to the cache
261+#write misses Number of times a WRITE bio has been
262+ mapped to the origin
263+#demotions Number of times a block has been removed
264+ from the cache
265+#promotions Number of times a block has been moved to
266+ the cache
267+#dirty Number of blocks in the cache that differ
268+ from the origin
269+#feature args Number of feature args to follow
270+feature args 'writethrough' (optional)
271+#core args Number of core arguments (must be even)
272+core args Key/value pairs for tuning the core
273+ e.g. migration_threshold
274+policy name Name of the policy
275+#policy args Number of policy arguments to follow (must be even)
276+policy args Key/value pairs e.g. sequential_threshold
277+cache metadata mode ro if read-only, rw if read-write
278+
279+ In serious cases where even a read-only mode is
280+ deemed unsafe no further I/O will be permitted and
281+ the status will just contain the string 'Fail'.
282+ The userspace recovery tools should then be used.
283+needs_check 'needs_check' if set, '-' if not set
284+ A metadata operation has failed, resulting in the
285+ needs_check flag being set in the metadata's
286+ superblock. The metadata device must be
287+ deactivated and checked/repaired before the
288+ cache can be made fully operational again.
289+ '-' indicates needs_check is not set.
290+========================= =====================================================
291+
292+Messages
293+--------
294+
295+Policies will have different tunables, specific to each one, so we
296+need a generic way of getting and setting these. Device-mapper
297+messages are used. (A sysfs interface would also be possible.)
298+
299+The message format is::
300+
301+ <key> <value>
302+
303+E.g.::
304+
305+ dmsetup message my_cache 0 sequential_threshold 1024
306+
307+
308+Invalidation is removing an entry from the cache without writing it
309+back. Cache blocks can be invalidated via the invalidate_cblocks
310+message, which takes an arbitrary number of cblock ranges. Each cblock
311+range's end value is "one past the end", meaning 5-10 expresses a range
312+of values from 5 to 9. Each cblock must be expressed as a decimal
313+value, in the future a variant message that takes cblock ranges
314+expressed in hexadecimal may be needed to better support efficient
315+invalidation of larger caches. The cache must be in passthrough mode
316+when invalidate_cblocks is used::
317+
318+ invalidate_cblocks [<cblock>|<cblock begin>-<cblock end>]*
319+
320+E.g.::
321+
322+ dmsetup message my_cache 0 invalidate_cblocks 2345 3456-4567 5678-6789
323+
324+Examples
325+========
326+
327+The test suite can be found here:
328+
329+https://github.com/jthornber/device-mapper-test-suite
330+
331+::
332+
333+ dmsetup create my_cache --table '0 41943040 cache /dev/mapper/metadata \
334+ /dev/mapper/ssd /dev/mapper/origin 512 1 writeback default 0'
335+ dmsetup create my_cache --table '0 41943040 cache /dev/mapper/metadata \
336+ /dev/mapper/ssd /dev/mapper/origin 1024 1 writeback \
337+ mq 4 sequential_threshold 1024 random_threshold 8'
Documentation/admin-guide/device-mapper/delay.rst+31−0
@@ -0,0 +1,31 @@
1+========
2+dm-delay
3+========
4+
5+Device-Mapper's "delay" target delays reads and/or writes
6+and maps them to different devices.
7+
8+Parameters::
9+
10+ <device> <offset> <delay> [<write_device> <write_offset> <write_delay>
11+ [<flush_device> <flush_offset> <flush_delay>]]
12+
13+With separate write parameters, the first set is only used for reads.
14+Offsets are specified in sectors.
15+Delays are specified in milliseconds.
16+
17+Example scripts
18+===============
19+
20+::
21+
22+ #!/bin/sh
23+ # Create device delaying rw operation for 500ms
24+ echo "0 `blockdev --getsz $1` delay $1 0 500" | dmsetup create delayed
25+
26+::
27+
28+ #!/bin/sh
29+ # Create device delaying only write operation for 500ms and
30+ # splitting reads and writes to different devices $1 $2
31+ echo "0 `blockdev --getsz $1` delay $1 0 0 $2 0 500" | dmsetup create delayed
Documentation/admin-guide/device-mapper/dm-crypt.rst+173−0
@@ -0,0 +1,173 @@
1+========
2+dm-crypt
3+========
4+
5+Device-Mapper's "crypt" target provides transparent encryption of block devices
6+using the kernel crypto API.
7+
8+For a more detailed description of supported parameters see:
9+https://gitlab.com/cryptsetup/cryptsetup/wikis/DMCrypt
10+
11+Parameters::
12+
13+ <cipher> <key> <iv_offset> <device path> \
14+ <offset> [<#opt_params> <opt_params>]
15+
16+<cipher>
17+ Encryption cipher, encryption mode and Initial Vector (IV) generator.
18+
19+ The cipher specifications format is::
20+
21+ cipher[:keycount]-chainmode-ivmode[:ivopts]
22+
23+ Examples::
24+
25+ aes-cbc-essiv:sha256
26+ aes-xts-plain64
27+ serpent-xts-plain64
28+
29+ Cipher format also supports direct specification with kernel crypt API
30+ format (selected by capi: prefix). The IV specification is the same
31+ as for the first format type.
32+ This format is mainly used for specification of authenticated modes.
33+
34+ The crypto API cipher specifications format is::
35+
36+ capi:cipher_api_spec-ivmode[:ivopts]
37+
38+ Examples::
39+
40+ capi:cbc(aes)-essiv:sha256
41+ capi:xts(aes)-plain64
42+
43+ Examples of authenticated modes::
44+
45+ capi:gcm(aes)-random
46+ capi:authenc(hmac(sha256),xts(aes))-random
47+ capi:rfc7539(chacha20,poly1305)-random
48+
49+ The /proc/crypto contains a list of curently loaded crypto modes.
50+
51+<key>
52+ Key used for encryption. It is encoded either as a hexadecimal number
53+ or it can be passed as <key_string> prefixed with single colon
54+ character (':') for keys residing in kernel keyring service.
55+ You can only use key sizes that are valid for the selected cipher
56+ in combination with the selected iv mode.
57+ Note that for some iv modes the key string can contain additional
58+ keys (for example IV seed) so the key contains more parts concatenated
59+ into a single string.
60+
61+<key_string>
62+ The kernel keyring key is identified by string in following format:
63+ <key_size>:<key_type>:<key_description>.
64+
65+<key_size>
66+ The encryption key size in bytes. The kernel key payload size must match
67+ the value passed in <key_size>.
68+
69+<key_type>
70+ Either 'logon' or 'user' kernel key type.
71+
72+<key_description>
73+ The kernel keyring key description crypt target should look for
74+ when loading key of <key_type>.
75+
76+<keycount>
77+ Multi-key compatibility mode. You can define <keycount> keys and
78+ then sectors are encrypted according to their offsets (sector 0 uses key0;
79+ sector 1 uses key1 etc.). <keycount> must be a power of two.
80+
81+<iv_offset>
82+ The IV offset is a sector count that is added to the sector number
83+ before creating the IV.
84+
85+<device path>
86+ This is the device that is going to be used as backend and contains the
87+ encrypted data. You can specify it as a path like /dev/xxx or a device
88+ number <major>:<minor>.
89+
90+<offset>
91+ Starting sector within the device where the encrypted data begins.
92+
93+<#opt_params>
94+ Number of optional parameters. If there are no optional parameters,
95+ the optional paramaters section can be skipped or #opt_params can be zero.
96+ Otherwise #opt_params is the number of following arguments.
97+
98+ Example of optional parameters section:
99+ 3 allow_discards same_cpu_crypt submit_from_crypt_cpus
100+
101+allow_discards
102+ Block discard requests (a.k.a. TRIM) are passed through the crypt device.
103+ The default is to ignore discard requests.
104+
105+ WARNING: Assess the specific security risks carefully before enabling this
106+ option. For example, allowing discards on encrypted devices may lead to
107+ the leak of information about the ciphertext device (filesystem type,
108+ used space etc.) if the discarded blocks can be located easily on the
109+ device later.
110+
111+same_cpu_crypt
112+ Perform encryption using the same cpu that IO was submitted on.
113+ The default is to use an unbound workqueue so that encryption work
114+ is automatically balanced between available CPUs.
115+
116+submit_from_crypt_cpus
117+ Disable offloading writes to a separate thread after encryption.
118+ There are some situations where offloading write bios from the
119+ encryption threads to a single thread degrades performance
120+ significantly. The default is to offload write bios to the same
121+ thread because it benefits CFQ to have writes submitted using the
122+ same context.
123+
124+integrity:<bytes>:<type>
125+ The device requires additional <bytes> metadata per-sector stored
126+ in per-bio integrity structure. This metadata must by provided
127+ by underlying dm-integrity target.
128+
129+ The <type> can be "none" if metadata is used only for persistent IV.
130+
131+ For Authenticated Encryption with Additional Data (AEAD)
132+ the <type> is "aead". An AEAD mode additionally calculates and verifies
133+ integrity for the encrypted device. The additional space is then
134+ used for storing authentication tag (and persistent IV if needed).
135+
136+sector_size:<bytes>
137+ Use <bytes> as the encryption unit instead of 512 bytes sectors.
138+ This option can be in range 512 - 4096 bytes and must be power of two.
139+ Virtual device will announce this size as a minimal IO and logical sector.
140+
141+iv_large_sectors
142+ IV generators will use sector number counted in <sector_size> units
143+ instead of default 512 bytes sectors.
144+
145+ For example, if <sector_size> is 4096 bytes, plain64 IV for the second
146+ sector will be 8 (without flag) and 1 if iv_large_sectors is present.
147+ The <iv_offset> must be multiple of <sector_size> (in 512 bytes units)
148+ if this flag is specified.
149+
150+Example scripts
151+===============
152+LUKS (Linux Unified Key Setup) is now the preferred way to set up disk
153+encryption with dm-crypt using the 'cryptsetup' utility, see
154+https://gitlab.com/cryptsetup/cryptsetup
155+
156+::
157+
158+ #!/bin/sh
159+ # Create a crypt device using dmsetup
160+ dmsetup create crypt1 --table "0 `blockdev --getsz $1` crypt aes-cbc-essiv:sha256 babebabebabebabebabebabebabebabe 0 $1 0"
161+
162+::
163+
164+ #!/bin/sh
165+ # Create a crypt device using dmsetup when encryption key is stored in keyring service
166+ dmsetup create crypt2 --table "0 `blockdev --getsize $1` crypt aes-cbc-essiv:sha256 :32:logon:my_prefix:my_key 0 $1 0"
167+
168+::
169+
170+ #!/bin/sh
171+ # Create a crypt device using cryptsetup and LUKS header with default cipher
172+ cryptsetup luksFormat $1
173+ cryptsetup luksOpen $1 crypt1
Documentation/admin-guide/device-mapper/dm-dust.txtrenamed from Documentation/device-mapper/dm-dust.txt+0−0

File renamed without changes.

Documentation/admin-guide/device-mapper/dm-flakey.rst+74−0
@@ -0,0 +1,74 @@
1+=========
2+dm-flakey
3+=========
4+
5+This target is the same as the linear target except that it exhibits
6+unreliable behaviour periodically. It's been found useful in simulating
7+failing devices for testing purposes.
8+
9+Starting from the time the table is loaded, the device is available for
10+<up interval> seconds, then exhibits unreliable behaviour for <down
11+interval> seconds, and then this cycle repeats.
12+
13+Also, consider using this in combination with the dm-delay target too,
14+which can delay reads and writes and/or send them to different
15+underlying devices.
16+
17+Table parameters
18+----------------
19+
20+::
21+
22+ <dev path> <offset> <up interval> <down interval> \
23+ [<num_features> [<feature arguments>]]
24+
25+Mandatory parameters:
26+
27+ <dev path>:
28+ Full pathname to the underlying block-device, or a
29+ "major:minor" device-number.
30+ <offset>:
31+ Starting sector within the device.
32+ <up interval>:
33+ Number of seconds device is available.
34+ <down interval>:
35+ Number of seconds device returns errors.
36+
37+Optional feature parameters:
38+
39+ If no feature parameters are present, during the periods of
40+ unreliability, all I/O returns errors.
41+
42+ drop_writes:
43+ All write I/O is silently ignored.
44+ Read I/O is handled correctly.
45+
46+ error_writes:
47+ All write I/O is failed with an error signalled.
48+ Read I/O is handled correctly.
49+
50+ corrupt_bio_byte <Nth_byte> <direction> <value> <flags>:
51+ During <down interval>, replace <Nth_byte> of the data of
52+ each matching bio with <value>.
53+
54+ <Nth_byte>:
55+ The offset of the byte to replace.
56+ Counting starts at 1, to replace the first byte.
57+ <direction>:
58+ Either 'r' to corrupt reads or 'w' to corrupt writes.
59+ 'w' is incompatible with drop_writes.
60+ <value>:
61+ The value (from 0-255) to write.
62+ <flags>:
63+ Perform the replacement only if bio->bi_opf has all the
64+ selected flags set.
65+
66+Examples:
67+
68+Replaces the 32nd byte of READ bios with the value 1::
69+
70+ corrupt_bio_byte 32 r 1 0
71+
72+Replaces the 224th byte of REQ_META (=32) bios with the value 0::
73+
74+ corrupt_bio_byte 224 w 0 32
Documentation/admin-guide/device-mapper/dm-init.rst+125−0
@@ -0,0 +1,125 @@
1+================================
2+Early creation of mapped devices
3+================================
4+
5+It is possible to configure a device-mapper device to act as the root device for
6+your system in two ways.
7+
8+The first is to build an initial ramdisk which boots to a minimal userspace
9+which configures the device, then pivot_root(8) in to it.
10+
11+The second is to create one or more device-mappers using the module parameter
12+"dm-mod.create=" through the kernel boot command line argument.
13+
14+The format is specified as a string of data separated by commas and optionally
15+semi-colons, where:
16+
17+ - a comma is used to separate fields like name, uuid, flags and table
18+ (specifies one device)
19+ - a semi-colon is used to separate devices.
20+
21+So the format will look like this::
22+
23+ dm-mod.create=<name>,<uuid>,<minor>,<flags>,<table>[,<table>+][;<name>,<uuid>,<minor>,<flags>,<table>[,<table>+]+]
24+
25+Where::
26+
27+ <name> ::= The device name.
28+ <uuid> ::= xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx | ""
29+ <minor> ::= The device minor number | ""
30+ <flags> ::= "ro" | "rw"
31+ <table> ::= <start_sector> <num_sectors> <target_type> <target_args>
32+ <target_type> ::= "verity" | "linear" | ... (see list below)
33+
34+The dm line should be equivalent to the one used by the dmsetup tool with the
35+`--concise` argument.
36+
37+Target types
38+============
39+
40+Not all target types are available as there are serious risks in allowing
41+activation of certain DM targets without first using userspace tools to check
42+the validity of associated metadata.
43+
44+======================= =======================================================
45+`cache` constrained, userspace should verify cache device
46+`crypt` allowed
47+`delay` allowed
48+`era` constrained, userspace should verify metadata device
49+`flakey` constrained, meant for test
50+`linear` allowed
51+`log-writes` constrained, userspace should verify metadata device
52+`mirror` constrained, userspace should verify main/mirror device
53+`raid` constrained, userspace should verify metadata device
54+`snapshot` constrained, userspace should verify src/dst device
55+`snapshot-origin` allowed
56+`snapshot-merge` constrained, userspace should verify src/dst device
57+`striped` allowed
58+`switch` constrained, userspace should verify dev path
59+`thin` constrained, requires dm target message from userspace
60+`thin-pool` constrained, requires dm target message from userspace
61+`verity` allowed
62+`writecache` constrained, userspace should verify cache device
63+`zero` constrained, not meant for rootfs
64+======================= =======================================================
65+
66+If the target is not listed above, it is constrained by default (not tested).
67+
68+Examples
69+========
70+An example of booting to a linear array made up of user-mode linux block
71+devices::
72+
73+ dm-mod.create="lroot,,,rw, 0 4096 linear 98:16 0, 4096 4096 linear 98:32 0" root=/dev/dm-0
74+
75+This will boot to a rw dm-linear target of 8192 sectors split across two block
76+devices identified by their major:minor numbers. After boot, udev will rename
77+this target to /dev/mapper/lroot (depending on the rules). No uuid was assigned.
78+
79+An example of multiple device-mappers, with the dm-mod.create="..." contents
80+is shown here split on multiple lines for readability::
81+
82+ dm-linear,,1,rw,
83+ 0 32768 linear 8:1 0,
84+ 32768 1024000 linear 8:2 0;
85+ dm-verity,,3,ro,
86+ 0 1638400 verity 1 /dev/sdc1 /dev/sdc2 4096 4096 204800 1 sha256
87+ ac87db56303c9c1da433d7209b5a6ef3e4779df141200cbd7c157dcb8dd89c42
88+ 5ebfe87f7df3235b80a117ebc4078e44f55045487ad4a96581d1adb564615b51
89+
90+Other examples (per target):
91+
92+"crypt"::
93+
94+ dm-crypt,,8,ro,
95+ 0 1048576 crypt aes-xts-plain64
96+ babebabebabebabebabebabebabebabebabebabebabebabebabebabebabebabe 0
97+ /dev/sda 0 1 allow_discards
98+
99+"delay"::
100+
101+ dm-delay,,4,ro,0 409600 delay /dev/sda1 0 500
102+
103+"linear"::
104+
105+ dm-linear,,,rw,
106+ 0 32768 linear /dev/sda1 0,
107+ 32768 1024000 linear /dev/sda2 0,
108+ 1056768 204800 linear /dev/sda3 0,
109+ 1261568 512000 linear /dev/sda4 0
110+
111+"snapshot-origin"::
112+
113+ dm-snap-orig,,4,ro,0 409600 snapshot-origin 8:2
114+
115+"striped"::
116+
117+ dm-striped,,4,ro,0 1638400 striped 4 4096
118+ /dev/sda1 0 /dev/sda2 0 /dev/sda3 0 /dev/sda4 0
119+
120+"verity"::
121+
122+ dm-verity,,4,ro,
123+ 0 1638400 verity 1 8:1 8:2 4096 4096 204800 1 sha256
124+ fb1a5a0f00deb908d8b53cb270858975e76cf64105d412ce764225d53b8f3cfd
125+ 51934789604d1b92399c52e7cb149d1b3a1b74bbbcb103b2a0aaacbed5c08584
Documentation/admin-guide/device-mapper/dm-integrity.rst+259−0
@@ -0,0 +1,259 @@
1+============
2+dm-integrity
3+============
4+
5+The dm-integrity target emulates a block device that has additional
6+per-sector tags that can be used for storing integrity information.
7+
8+A general problem with storing integrity tags with every sector is that
9+writing the sector and the integrity tag must be atomic - i.e. in case of
10+crash, either both sector and integrity tag or none of them is written.
11+
12+To guarantee write atomicity, the dm-integrity target uses journal, it
13+writes sector data and integrity tags into a journal, commits the journal
14+and then copies the data and integrity tags to their respective location.
15+
16+The dm-integrity target can be used with the dm-crypt target - in this
17+situation the dm-crypt target creates the integrity data and passes them
18+to the dm-integrity target via bio_integrity_payload attached to the bio.
19+In this mode, the dm-crypt and dm-integrity targets provide authenticated
20+disk encryption - if the attacker modifies the encrypted device, an I/O
21+error is returned instead of random data.
22+
23+The dm-integrity target can also be used as a standalone target, in this
24+mode it calculates and verifies the integrity tag internally. In this
25+mode, the dm-integrity target can be used to detect silent data
26+corruption on the disk or in the I/O path.
27+
28+There's an alternate mode of operation where dm-integrity uses bitmap
29+instead of a journal. If a bit in the bitmap is 1, the corresponding
30+region's data and integrity tags are not synchronized - if the machine
31+crashes, the unsynchronized regions will be recalculated. The bitmap mode
32+is faster than the journal mode, because we don't have to write the data
33+twice, but it is also less reliable, because if data corruption happens
34+when the machine crashes, it may not be detected.
35+
36+When loading the target for the first time, the kernel driver will format
37+the device. But it will only format the device if the superblock contains
38+zeroes. If the superblock is neither valid nor zeroed, the dm-integrity
39+target can't be loaded.
40+
41+To use the target for the first time:
42+
43+1. overwrite the superblock with zeroes
44+2. load the dm-integrity target with one-sector size, the kernel driver
45+ will format the device
46+3. unload the dm-integrity target
47+4. read the "provided_data_sectors" value from the superblock
48+5. load the dm-integrity target with the the target size
49+ "provided_data_sectors"
50+6. if you want to use dm-integrity with dm-crypt, load the dm-crypt target
51+ with the size "provided_data_sectors"
52+
53+
54+Target arguments:
55+
56+1. the underlying block device
57+
58+2. the number of reserved sector at the beginning of the device - the
59+ dm-integrity won't read of write these sectors
60+
61+3. the size of the integrity tag (if "-" is used, the size is taken from
62+ the internal-hash algorithm)
63+
64+4. mode:
65+
66+ D - direct writes (without journal)
67+ in this mode, journaling is
68+ not used and data sectors and integrity tags are written
69+ separately. In case of crash, it is possible that the data
70+ and integrity tag doesn't match.
71+ J - journaled writes
72+ data and integrity tags are written to the
73+ journal and atomicity is guaranteed. In case of crash,
74+ either both data and tag or none of them are written. The
75+ journaled mode degrades write throughput twice because the
76+ data have to be written twice.
77+ B - bitmap mode - data and metadata are written without any
78+ synchronization, the driver maintains a bitmap of dirty
79+ regions where data and metadata don't match. This mode can
80+ only be used with internal hash.
81+ R - recovery mode - in this mode, journal is not replayed,
82+ checksums are not checked and writes to the device are not
83+ allowed. This mode is useful for data recovery if the
84+ device cannot be activated in any of the other standard
85+ modes.
86+
87+5. the number of additional arguments
88+
89+Additional arguments:
90+
91+journal_sectors:number
92+ The size of journal, this argument is used only if formatting the
93+ device. If the device is already formatted, the value from the
94+ superblock is used.
95+
96+interleave_sectors:number
97+ The number of interleaved sectors. This values is rounded down to
98+ a power of two. If the device is already formatted, the value from
99+ the superblock is used.
100+
101+meta_device:device
102+ Don't interleave the data and metadata on on device. Use a
103+ separate device for metadata.
104+
105+buffer_sectors:number
106+ The number of sectors in one buffer. The value is rounded down to
107+ a power of two.
108+
109+ The tag area is accessed using buffers, the buffer size is
110+ configurable. The large buffer size means that the I/O size will
111+ be larger, but there could be less I/Os issued.
112+
113+journal_watermark:number
114+ The journal watermark in percents. When the size of the journal
115+ exceeds this watermark, the thread that flushes the journal will
116+ be started.
117+
118+commit_time:number
119+ Commit time in milliseconds. When this time passes, the journal is
120+ written. The journal is also written immediatelly if the FLUSH
121+ request is received.
122+
123+internal_hash:algorithm(:key) (the key is optional)
124+ Use internal hash or crc.
125+ When this argument is used, the dm-integrity target won't accept
126+ integrity tags from the upper target, but it will automatically
127+ generate and verify the integrity tags.
128+
129+ You can use a crc algorithm (such as crc32), then integrity target
130+ will protect the data against accidental corruption.
131+ You can also use a hmac algorithm (for example
132+ "hmac(sha256):0123456789abcdef"), in this mode it will provide
133+ cryptographic authentication of the data without encryption.
134+
135+ When this argument is not used, the integrity tags are accepted
136+ from an upper layer target, such as dm-crypt. The upper layer
137+ target should check the validity of the integrity tags.
138+
139+recalculate
140+ Recalculate the integrity tags automatically. It is only valid
141+ when using internal hash.
142+
143+journal_crypt:algorithm(:key) (the key is optional)
144+ Encrypt the journal using given algorithm to make sure that the
145+ attacker can't read the journal. You can use a block cipher here
146+ (such as "cbc(aes)") or a stream cipher (for example "chacha20",
147+ "salsa20", "ctr(aes)" or "ecb(arc4)").
148+
149+ The journal contains history of last writes to the block device,
150+ an attacker reading the journal could see the last sector nubmers
151+ that were written. From the sector numbers, the attacker can infer
152+ the size of files that were written. To protect against this
153+ situation, you can encrypt the journal.
154+
155+journal_mac:algorithm(:key) (the key is optional)
156+ Protect sector numbers in the journal from accidental or malicious
157+ modification. To protect against accidental modification, use a
158+ crc algorithm, to protect against malicious modification, use a
159+ hmac algorithm with a key.
160+
161+ This option is not needed when using internal-hash because in this
162+ mode, the integrity of journal entries is checked when replaying
163+ the journal. Thus, modified sector number would be detected at
164+ this stage.
165+
166+block_size:number
167+ The size of a data block in bytes. The larger the block size the
168+ less overhead there is for per-block integrity metadata.
169+ Supported values are 512, 1024, 2048 and 4096 bytes. If not
170+ specified the default block size is 512 bytes.
171+
172+sectors_per_bit:number
173+ In the bitmap mode, this parameter specifies the number of
174+ 512-byte sectors that corresponds to one bitmap bit.
175+
176+bitmap_flush_interval:number
177+ The bitmap flush interval in milliseconds. The metadata buffers
178+ are synchronized when this interval expires.
179+
180+
181+The journal mode (D/J), buffer_sectors, journal_watermark, commit_time can
182+be changed when reloading the target (load an inactive table and swap the
183+tables with suspend and resume). The other arguments should not be changed
184+when reloading the target because the layout of disk data depend on them
185+and the reloaded target would be non-functional.
186+
187+
188+The layout of the formatted block device:
189+
190+* reserved sectors
191+ (they are not used by this target, they can be used for
192+ storing LUKS metadata or for other purpose), the size of the reserved
193+ area is specified in the target arguments
194+
195+* superblock (4kiB)
196+ * magic string - identifies that the device was formatted
197+ * version
198+ * log2(interleave sectors)
199+ * integrity tag size
200+ * the number of journal sections
201+ * provided data sectors - the number of sectors that this target
202+ provides (i.e. the size of the device minus the size of all
203+ metadata and padding). The user of this target should not send
204+ bios that access data beyond the "provided data sectors" limit.
205+ * flags
206+ SB_FLAG_HAVE_JOURNAL_MAC
207+ - a flag is set if journal_mac is used
208+ SB_FLAG_RECALCULATING
209+ - recalculating is in progress
210+ SB_FLAG_DIRTY_BITMAP
211+ - journal area contains the bitmap of dirty
212+ blocks
213+ * log2(sectors per block)
214+ * a position where recalculating finished
215+* journal
216+ The journal is divided into sections, each section contains:
217+
218+ * metadata area (4kiB), it contains journal entries
219+
220+ - every journal entry contains:
221+
222+ * logical sector (specifies where the data and tag should
223+ be written)
224+ * last 8 bytes of data
225+ * integrity tag (the size is specified in the superblock)
226+
227+ - every metadata sector ends with
228+
229+ * mac (8-bytes), all the macs in 8 metadata sectors form a
230+ 64-byte value. It is used to store hmac of sector
231+ numbers in the journal section, to protect against a
232+ possibility that the attacker tampers with sector
233+ numbers in the journal.
234+ * commit id
235+
236+ * data area (the size is variable; it depends on how many journal
237+ entries fit into the metadata area)
238+
239+ - every sector in the data area contains:
240+
241+ * data (504 bytes of data, the last 8 bytes are stored in
242+ the journal entry)
243+ * commit id
244+
245+ To test if the whole journal section was written correctly, every
246+ 512-byte sector of the journal ends with 8-byte commit id. If the
247+ commit id matches on all sectors in a journal section, then it is
248+ assumed that the section was written correctly. If the commit id
249+ doesn't match, the section was written partially and it should not
250+ be replayed.
251+
252+* one or more runs of interleaved tags and data.
253+ Each run contains:
254+
255+ * tag area - it contains integrity tags. There is one tag for each
256+ sector in the data area
257+ * data area - it contains data sectors. The number of data sectors
258+ in one run must be a power of two. log2 of this value is stored
259+ in the superblock.
Documentation/admin-guide/device-mapper/dm-io.rst+75−0
@@ -0,0 +1,75 @@
1+=====
2+dm-io
3+=====
4+
5+Dm-io provides synchronous and asynchronous I/O services. There are three
6+types of I/O services available, and each type has a sync and an async
7+version.
8+
9+The user must set up an io_region structure to describe the desired location
10+of the I/O. Each io_region indicates a block-device along with the starting
11+sector and size of the region::
12+
13+ struct io_region {
14+ struct block_device *bdev;
15+ sector_t sector;
16+ sector_t count;
17+ };
18+
19+Dm-io can read from one io_region or write to one or more io_regions. Writes
20+to multiple regions are specified by an array of io_region structures.
21+
22+The first I/O service type takes a list of memory pages as the data buffer for
23+the I/O, along with an offset into the first page::
24+
25+ struct page_list {
26+ struct page_list *next;
27+ struct page *page;
28+ };
29+
30+ int dm_io_sync(unsigned int num_regions, struct io_region *where, int rw,
31+ struct page_list *pl, unsigned int offset,
32+ unsigned long *error_bits);
33+ int dm_io_async(unsigned int num_regions, struct io_region *where, int rw,
34+ struct page_list *pl, unsigned int offset,
35+ io_notify_fn fn, void *context);
36+
37+The second I/O service type takes an array of bio vectors as the data buffer
38+for the I/O. This service can be handy if the caller has a pre-assembled bio,
39+but wants to direct different portions of the bio to different devices::
40+
41+ int dm_io_sync_bvec(unsigned int num_regions, struct io_region *where,
42+ int rw, struct bio_vec *bvec,
43+ unsigned long *error_bits);
44+ int dm_io_async_bvec(unsigned int num_regions, struct io_region *where,
45+ int rw, struct bio_vec *bvec,
46+ io_notify_fn fn, void *context);
47+
48+The third I/O service type takes a pointer to a vmalloc'd memory buffer as the
49+data buffer for the I/O. This service can be handy if the caller needs to do
50+I/O to a large region but doesn't want to allocate a large number of individual
51+memory pages::
52+
53+ int dm_io_sync_vm(unsigned int num_regions, struct io_region *where, int rw,
54+ void *data, unsigned long *error_bits);
55+ int dm_io_async_vm(unsigned int num_regions, struct io_region *where, int rw,
56+ void *data, io_notify_fn fn, void *context);
57+
58+Callers of the asynchronous I/O services must include the name of a completion
59+callback routine and a pointer to some context data for the I/O::
60+
61+ typedef void (*io_notify_fn)(unsigned long error, void *context);
62+
63+The "error" parameter in this callback, as well as the `*error` parameter in
64+all of the synchronous versions, is a bitset (instead of a simple error value).
65+In the case of an write-I/O to multiple regions, this bitset allows dm-io to
66+indicate success or failure on each individual region.
67+
68+Before using any of the dm-io services, the user should call dm_io_get()
69+and specify the number of pages they expect to perform I/O on concurrently.
70+Dm-io will attempt to resize its mempool to make sure enough pages are
71+always available in order to avoid unnecessary waiting while performing I/O.
72+
73+When the user is finished using the dm-io services, they should call
74+dm_io_put() and specify the same number of pages that were given on the
75+dm_io_get() call.
Documentation/admin-guide/device-mapper/dm-log.rst+57−0
@@ -0,0 +1,57 @@
1+=====================
2+Device-Mapper Logging
3+=====================
4+The device-mapper logging code is used by some of the device-mapper
5+RAID targets to track regions of the disk that are not consistent.
6+A region (or portion of the address space) of the disk may be
7+inconsistent because a RAID stripe is currently being operated on or
8+a machine died while the region was being altered. In the case of
9+mirrors, a region would be considered dirty/inconsistent while you
10+are writing to it because the writes need to be replicated for all
11+the legs of the mirror and may not reach the legs at the same time.
12+Once all writes are complete, the region is considered clean again.
13+
14+There is a generic logging interface that the device-mapper RAID
15+implementations use to perform logging operations (see
16+dm_dirty_log_type in include/linux/dm-dirty-log.h). Various different
17+logging implementations are available and provide different
18+capabilities. The list includes:
19+
20+============== ==============================================================
21+Type Files
22+============== ==============================================================
23+disk drivers/md/dm-log.c
24+core drivers/md/dm-log.c
25+userspace drivers/md/dm-log-userspace* include/linux/dm-log-userspace.h
26+============== ==============================================================
27+
28+The "disk" log type
29+-------------------
30+This log implementation commits the log state to disk. This way, the
31+logging state survives reboots/crashes.
32+
33+The "core" log type
34+-------------------
35+This log implementation keeps the log state in memory. The log state
36+will not survive a reboot or crash, but there may be a small boost in
37+performance. This method can also be used if no storage device is
38+available for storing log state.
39+
40+The "userspace" log type
41+------------------------
42+This log type simply provides a way to export the log API to userspace,
43+so log implementations can be done there. This is done by forwarding most
44+logging requests to userspace, where a daemon receives and processes the
45+request.
46+
47+The structure used for communication between kernel and userspace are
48+located in include/linux/dm-log-userspace.h. Due to the frequency,
49+diversity, and 2-way communication nature of the exchanges between
50+kernel and userspace, 'connector' is used as the interface for
51+communication.
52+
53+There are currently two userspace log implementations that leverage this
54+framework - "clustered-disk" and "clustered-core". These implementations
55+provide a cluster-coherent log for shared-storage. Device-mapper mirroring
56+can be used in a shared-storage environment when the cluster log implementations
57+are employed.
Documentation/admin-guide/device-mapper/dm-queue-length.rst+48−0
@@ -0,0 +1,48 @@
1+===============
2+dm-queue-length
3+===============
4+
5+dm-queue-length is a path selector module for device-mapper targets,
6+which selects a path with the least number of in-flight I/Os.
7+The path selector name is 'queue-length'.
8+
9+Table parameters for each path: [<repeat_count>]
10+
11+::
12+
13+ <repeat_count>: The number of I/Os to dispatch using the selected
14+ path before switching to the next path.
15+ If not given, internal default is used. To check
16+ the default value, see the activated table.
17+
18+Status for each path: <status> <fail-count> <in-flight>
19+
20+::
21+
22+ <status>: 'A' if the path is active, 'F' if the path is failed.
23+ <fail-count>: The number of path failures.
24+ <in-flight>: The number of in-flight I/Os on the path.
25+
26+
27+Algorithm
28+=========
29+
30+dm-queue-length increments/decrements 'in-flight' when an I/O is
31+dispatched/completed respectively.
32+dm-queue-length selects a path with the minimum 'in-flight'.
33+
34+
35+Examples
36+========
37+In case that 2 paths (sda and sdb) are used with repeat_count == 128.
38+
39+::
40+
41+ # echo "0 10 multipath 0 0 1 1 queue-length 0 2 1 8:0 128 8:16 128" \
42+ dmsetup create test
43+ #
44+ # dmsetup table
45+ test: 0 10 multipath 0 0 1 1 queue-length 0 2 1 8:0 128 8:16 128
46+ #
47+ # dmsetup status
48+ test: 0 10 multipath 2 0 0 0 1 1 E 0 2 1 8:0 A 0 0 8:16 A 0 0
Documentation/admin-guide/device-mapper/dm-raid.rst+419−0
@@ -0,0 +1,419 @@
1+=======
2+dm-raid
3+=======
4+
5+The device-mapper RAID (dm-raid) target provides a bridge from DM to MD.
6+It allows the MD RAID drivers to be accessed using a device-mapper
7+interface.
8+
9+
10+Mapping Table Interface
11+-----------------------
12+The target is named "raid" and it accepts the following parameters::
13+
14+ <raid_type> <#raid_params> <raid_params> \
15+ <#raid_devs> <metadata_dev0> <dev0> [.. <metadata_devN> <devN>]
16+
17+<raid_type>:
18+
19+ ============= ===============================================================
20+ raid0 RAID0 striping (no resilience)
21+ raid1 RAID1 mirroring
22+ raid4 RAID4 with dedicated last parity disk
23+ raid5_n RAID5 with dedicated last parity disk supporting takeover
24+ Same as raid4
25+
26+ - Transitory layout
27+ raid5_la RAID5 left asymmetric
28+
29+ - rotating parity 0 with data continuation
30+ raid5_ra RAID5 right asymmetric
31+
32+ - rotating parity N with data continuation
33+ raid5_ls RAID5 left symmetric
34+
35+ - rotating parity 0 with data restart
36+ raid5_rs RAID5 right symmetric
37+
38+ - rotating parity N with data restart
39+ raid6_zr RAID6 zero restart
40+
41+ - rotating parity zero (left-to-right) with data restart
42+ raid6_nr RAID6 N restart
43+
44+ - rotating parity N (right-to-left) with data restart
45+ raid6_nc RAID6 N continue
46+
47+ - rotating parity N (right-to-left) with data continuation
48+ raid6_n_6 RAID6 with dedicate parity disks
49+
50+ - parity and Q-syndrome on the last 2 disks;
51+ layout for takeover from/to raid4/raid5_n
52+ raid6_la_6 Same as "raid_la" plus dedicated last Q-syndrome disk
53+
54+ - layout for takeover from raid5_la from/to raid6
55+ raid6_ra_6 Same as "raid5_ra" dedicated last Q-syndrome disk
56+
57+ - layout for takeover from raid5_ra from/to raid6
58+ raid6_ls_6 Same as "raid5_ls" dedicated last Q-syndrome disk
59+
60+ - layout for takeover from raid5_ls from/to raid6
61+ raid6_rs_6 Same as "raid5_rs" dedicated last Q-syndrome disk
62+
63+ - layout for takeover from raid5_rs from/to raid6
64+ raid10 Various RAID10 inspired algorithms chosen by additional params
65+ (see raid10_format and raid10_copies below)
66+
67+ - RAID10: Striped Mirrors (aka 'Striping on top of mirrors')
68+ - RAID1E: Integrated Adjacent Stripe Mirroring
69+ - RAID1E: Integrated Offset Stripe Mirroring
70+ - and other similar RAID10 variants
71+ ============= ===============================================================
72+
73+ Reference: Chapter 4 of
74+ http://www.snia.org/sites/default/files/SNIA_DDF_Technical_Position_v2.0.pdf
75+
76+<#raid_params>: The number of parameters that follow.
77+
78+<raid_params> consists of
79+
80+ Mandatory parameters:
81+ <chunk_size>:
82+ Chunk size in sectors. This parameter is often known as
83+ "stripe size". It is the only mandatory parameter and
84+ is placed first.
85+
86+ followed by optional parameters (in any order):
87+ [sync|nosync]
88+ Force or prevent RAID initialization.
89+
90+ [rebuild <idx>]
91+ Rebuild drive number 'idx' (first drive is 0).
92+
93+ [daemon_sleep <ms>]
94+ Interval between runs of the bitmap daemon that
95+ clear bits. A longer interval means less bitmap I/O but
96+ resyncing after a failure is likely to take longer.
97+
98+ [min_recovery_rate <kB/sec/disk>]
99+ Throttle RAID initialization
100+ [max_recovery_rate <kB/sec/disk>]
101+ Throttle RAID initialization
102+ [write_mostly <idx>]
103+ Mark drive index 'idx' write-mostly.
104+ [max_write_behind <sectors>]
105+ See '--write-behind=' (man mdadm)
106+ [stripe_cache <sectors>]
107+ Stripe cache size (RAID 4/5/6 only)
108+ [region_size <sectors>]
109+ The region_size multiplied by the number of regions is the
110+ logical size of the array. The bitmap records the device
111+ synchronisation state for each region.
112+
113+ [raid10_copies <# copies>], [raid10_format <near|far|offset>]
114+ These two options are used to alter the default layout of
115+ a RAID10 configuration. The number of copies is can be
116+ specified, but the default is 2. There are also three
117+ variations to how the copies are laid down - the default
118+ is "near". Near copies are what most people think of with
119+ respect to mirroring. If these options are left unspecified,
120+ or 'raid10_copies 2' and/or 'raid10_format near' are given,
121+ then the layouts for 2, 3 and 4 devices are:
122+
123+ ======== ========== ==============
124+ 2 drives 3 drives 4 drives
125+ ======== ========== ==============
126+ A1 A1 A1 A1 A2 A1 A1 A2 A2
127+ A2 A2 A2 A3 A3 A3 A3 A4 A4
128+ A3 A3 A4 A4 A5 A5 A5 A6 A6
129+ A4 A4 A5 A6 A6 A7 A7 A8 A8
130+ .. .. .. .. .. .. .. .. ..
131+ ======== ========== ==============
132+
133+ The 2-device layout is equivalent 2-way RAID1. The 4-device
134+ layout is what a traditional RAID10 would look like. The
135+ 3-device layout is what might be called a 'RAID1E - Integrated
136+ Adjacent Stripe Mirroring'.
137+
138+ If 'raid10_copies 2' and 'raid10_format far', then the layouts
139+ for 2, 3 and 4 devices are:
140+
141+ ======== ============ ===================
142+ 2 drives 3 drives 4 drives
143+ ======== ============ ===================
144+ A1 A2 A1 A2 A3 A1 A2 A3 A4
145+ A3 A4 A4 A5 A6 A5 A6 A7 A8
146+ A5 A6 A7 A8 A9 A9 A10 A11 A12
147+ .. .. .. .. .. .. .. .. ..
148+ A2 A1 A3 A1 A2 A2 A1 A4 A3
149+ A4 A3 A6 A4 A5 A6 A5 A8 A7
150+ A6 A5 A9 A7 A8 A10 A9 A12 A11
151+ .. .. .. .. .. .. .. .. ..
152+ ======== ============ ===================
153+
154+ If 'raid10_copies 2' and 'raid10_format offset', then the
155+ layouts for 2, 3 and 4 devices are:
156+
157+ ======== ========== ================
158+ 2 drives 3 drives 4 drives
159+ ======== ========== ================
160+ A1 A2 A1 A2 A3 A1 A2 A3 A4
161+ A2 A1 A3 A1 A2 A2 A1 A4 A3
162+ A3 A4 A4 A5 A6 A5 A6 A7 A8
163+ A4 A3 A6 A4 A5 A6 A5 A8 A7
164+ A5 A6 A7 A8 A9 A9 A10 A11 A12
165+ A6 A5 A9 A7 A8 A10 A9 A12 A11
166+ .. .. .. .. .. .. .. .. ..
167+ ======== ========== ================
168+
169+ Here we see layouts closely akin to 'RAID1E - Integrated
170+ Offset Stripe Mirroring'.
171+
172+ [delta_disks <N>]
173+ The delta_disks option value (-251 < N < +251) triggers
174+ device removal (negative value) or device addition (positive
175+ value) to any reshape supporting raid levels 4/5/6 and 10.
176+ RAID levels 4/5/6 allow for addition of devices (metadata
177+ and data device tuple), raid10_near and raid10_offset only
178+ allow for device addition. raid10_far does not support any
179+ reshaping at all.
180+ A minimum of devices have to be kept to enforce resilience,
181+ which is 3 devices for raid4/5 and 4 devices for raid6.
182+
183+ [data_offset <sectors>]
184+ This option value defines the offset into each data device
185+ where the data starts. This is used to provide out-of-place
186+ reshaping space to avoid writing over data while
187+ changing the layout of stripes, hence an interruption/crash
188+ may happen at any time without the risk of losing data.
189+ E.g. when adding devices to an existing raid set during
190+ forward reshaping, the out-of-place space will be allocated
191+ at the beginning of each raid device. The kernel raid4/5/6/10
192+ MD personalities supporting such device addition will read the data from
193+ the existing first stripes (those with smaller number of stripes)
194+ starting at data_offset to fill up a new stripe with the larger
195+ number of stripes, calculate the redundancy blocks (CRC/Q-syndrome)
196+ and write that new stripe to offset 0. Same will be applied to all
197+ N-1 other new stripes. This out-of-place scheme is used to change
198+ the RAID type (i.e. the allocation algorithm) as well, e.g.
199+ changing from raid5_ls to raid5_n.
200+
201+ [journal_dev <dev>]
202+ This option adds a journal device to raid4/5/6 raid sets and
203+ uses it to close the 'write hole' caused by the non-atomic updates
204+ to the component devices which can cause data loss during recovery.
205+ The journal device is used as writethrough thus causing writes to
206+ be throttled versus non-journaled raid4/5/6 sets.
207+ Takeover/reshape is not possible with a raid4/5/6 journal device;
208+ it has to be deconfigured before requesting these.
209+
210+ [journal_mode <mode>]
211+ This option sets the caching mode on journaled raid4/5/6 raid sets
212+ (see 'journal_dev <dev>' above) to 'writethrough' or 'writeback'.
213+ If 'writeback' is selected the journal device has to be resilient
214+ and must not suffer from the 'write hole' problem itself (e.g. use
215+ raid1 or raid10) to avoid a single point of failure.
216+
217+<#raid_devs>: The number of devices composing the array.
218+ Each device consists of two entries. The first is the device
219+ containing the metadata (if any); the second is the one containing the
220+ data. A Maximum of 64 metadata/data device entries are supported
221+ up to target version 1.8.0.
222+ 1.9.0 supports up to 253 which is enforced by the used MD kernel runtime.
223+
224+ If a drive has failed or is missing at creation time, a '-' can be
225+ given for both the metadata and data drives for a given position.
226+
227+
228+Example Tables
229+--------------
230+
231+::
232+
233+ # RAID4 - 4 data drives, 1 parity (no metadata devices)
234+ # No metadata devices specified to hold superblock/bitmap info
235+ # Chunk size of 1MiB
236+ # (Lines separated for easy reading)
237+
238+ 0 1960893648 raid \
239+ raid4 1 2048 \
240+ 5 - 8:17 - 8:33 - 8:49 - 8:65 - 8:81
241+
242+ # RAID4 - 4 data drives, 1 parity (with metadata devices)
243+ # Chunk size of 1MiB, force RAID initialization,
244+ # min recovery rate at 20 kiB/sec/disk
245+
246+ 0 1960893648 raid \
247+ raid4 4 2048 sync min_recovery_rate 20 \
248+ 5 8:17 8:18 8:33 8:34 8:49 8:50 8:65 8:66 8:81 8:82
249+
250+
251+Status Output
252+-------------
253+'dmsetup table' displays the table used to construct the mapping.
254+The optional parameters are always printed in the order listed
255+above with "sync" or "nosync" always output ahead of the other
256+arguments, regardless of the order used when originally loading the table.
257+Arguments that can be repeated are ordered by value.
258+
259+
260+'dmsetup status' yields information on the state and health of the array.
261+The output is as follows (normally a single line, but expanded here for
262+clarity)::
263+
264+ 1: <s> <l> raid \
265+ 2: <raid_type> <#devices> <health_chars> \
266+ 3: <sync_ratio> <sync_action> <mismatch_cnt>
267+
268+Line 1 is the standard output produced by device-mapper.
269+
270+Line 2 & 3 are produced by the raid target and are best explained by example::
271+
272+ 0 1960893648 raid raid4 5 AAAAA 2/490221568 init 0
273+
274+Here we can see the RAID type is raid4, there are 5 devices - all of
275+which are 'A'live, and the array is 2/490221568 complete with its initial
276+recovery. Here is a fuller description of the individual fields:
277+
278+ =============== =========================================================
279+ <raid_type> Same as the <raid_type> used to create the array.
280+ <health_chars> One char for each device, indicating:
281+
282+ - 'A' = alive and in-sync
283+ - 'a' = alive but not in-sync
284+ - 'D' = dead/failed.
285+ <sync_ratio> The ratio indicating how much of the array has undergone
286+ the process described by 'sync_action'. If the
287+ 'sync_action' is "check" or "repair", then the process
288+ of "resync" or "recover" can be considered complete.
289+ <sync_action> One of the following possible states:
290+
291+ idle
292+ - No synchronization action is being performed.
293+ frozen
294+ - The current action has been halted.
295+ resync
296+ - Array is undergoing its initial synchronization
297+ or is resynchronizing after an unclean shutdown
298+ (possibly aided by a bitmap).
299+ recover
300+ - A device in the array is being rebuilt or
301+ replaced.
302+ check
303+ - A user-initiated full check of the array is
304+ being performed. All blocks are read and
305+ checked for consistency. The number of
306+ discrepancies found are recorded in
307+ <mismatch_cnt>. No changes are made to the
308+ array by this action.
309+ repair
310+ - The same as "check", but discrepancies are
311+ corrected.
312+ reshape
313+ - The array is undergoing a reshape.
314+ <mismatch_cnt> The number of discrepancies found between mirror copies
315+ in RAID1/10 or wrong parity values found in RAID4/5/6.
316+ This value is valid only after a "check" of the array
317+ is performed. A healthy array has a 'mismatch_cnt' of 0.
318+ <data_offset> The current data offset to the start of the user data on
319+ each component device of a raid set (see the respective
320+ raid parameter to support out-of-place reshaping).
321+ <journal_char> - 'A' - active write-through journal device.
322+ - 'a' - active write-back journal device.
323+ - 'D' - dead journal device.
324+ - '-' - no journal device.
325+ =============== =========================================================
326+
327+
328+Message Interface
329+-----------------
330+The dm-raid target will accept certain actions through the 'message' interface.
331+('man dmsetup' for more information on the message interface.) These actions
332+include:
333+
334+ ========= ================================================
335+ "idle" Halt the current sync action.
336+ "frozen" Freeze the current sync action.
337+ "resync" Initiate/continue a resync.
338+ "recover" Initiate/continue a recover process.
339+ "check" Initiate a check (i.e. a "scrub") of the array.
340+ "repair" Initiate a repair of the array.
341+ ========= ================================================
342+
343+
344+Discard Support
345+---------------
346+The implementation of discard support among hardware vendors varies.
347+When a block is discarded, some storage devices will return zeroes when
348+the block is read. These devices set the 'discard_zeroes_data'
349+attribute. Other devices will return random data. Confusingly, some
350+devices that advertise 'discard_zeroes_data' will not reliably return
351+zeroes when discarded blocks are read! Since RAID 4/5/6 uses blocks
352+from a number of devices to calculate parity blocks and (for performance
353+reasons) relies on 'discard_zeroes_data' being reliable, it is important
354+that the devices be consistent. Blocks may be discarded in the middle
355+of a RAID 4/5/6 stripe and if subsequent read results are not
356+consistent, the parity blocks may be calculated differently at any time;
357+making the parity blocks useless for redundancy. It is important to
358+understand how your hardware behaves with discards if you are going to
359+enable discards with RAID 4/5/6.
360+
361+Since the behavior of storage devices is unreliable in this respect,
362+even when reporting 'discard_zeroes_data', by default RAID 4/5/6
363+discard support is disabled -- this ensures data integrity at the
364+expense of losing some performance.
365+
366+Storage devices that properly support 'discard_zeroes_data' are
367+increasingly whitelisted in the kernel and can thus be trusted.
368+
369+For trusted devices, the following dm-raid module parameter can be set
370+to safely enable discard support for RAID 4/5/6:
371+
372+ 'devices_handle_discards_safely'
373+
374+
375+Version History
376+---------------
377+
378+::
379+
380+ 1.0.0 Initial version. Support for RAID 4/5/6
381+ 1.1.0 Added support for RAID 1
382+ 1.2.0 Handle creation of arrays that contain failed devices.
383+ 1.3.0 Added support for RAID 10
384+ 1.3.1 Allow device replacement/rebuild for RAID 10
385+ 1.3.2 Fix/improve redundancy checking for RAID10
386+ 1.4.0 Non-functional change. Removes arg from mapping function.
387+ 1.4.1 RAID10 fix redundancy validation checks (commit 55ebbb5).
388+ 1.4.2 Add RAID10 "far" and "offset" algorithm support.
389+ 1.5.0 Add message interface to allow manipulation of the sync_action.
390+ New status (STATUSTYPE_INFO) fields: sync_action and mismatch_cnt.
391+ 1.5.1 Add ability to restore transiently failed devices on resume.
392+ 1.5.2 'mismatch_cnt' is zero unless [last_]sync_action is "check".
393+ 1.6.0 Add discard support (and devices_handle_discard_safely module param).
394+ 1.7.0 Add support for MD RAID0 mappings.
395+ 1.8.0 Explicitly check for compatible flags in the superblock metadata
396+ and reject to start the raid set if any are set by a newer
397+ target version, thus avoiding data corruption on a raid set
398+ with a reshape in progress.
399+ 1.9.0 Add support for RAID level takeover/reshape/region size
400+ and set size reduction.
401+ 1.9.1 Fix activation of existing RAID 4/10 mapped devices
402+ 1.9.2 Don't emit '- -' on the status table line in case the constructor
403+ fails reading a superblock. Correctly emit 'maj:min1 maj:min2' and
404+ 'D' on the status line. If '- -' is passed into the constructor, emit
405+ '- -' on the table line and '-' as the status line health character.
406+ 1.10.0 Add support for raid4/5/6 journal device
407+ 1.10.1 Fix data corruption on reshape request
408+ 1.11.0 Fix table line argument order
409+ (wrong raid10_copies/raid10_format sequence)
410+ 1.11.1 Add raid4/5/6 journal write-back support via journal_mode option
411+ 1.12.1 Fix for MD deadlock between mddev_suspend() and md_write_start() available
412+ 1.13.0 Fix dev_health status at end of "recover" (was 'a', now 'A')
413+ 1.13.1 Fix deadlock caused by early md_stop_writes(). Also fix size an
414+ state races.
415+ 1.13.2 Fix raid redundancy validation and avoid keeping raid set frozen
416+ 1.14.0 Fix reshape race on small devices. Fix stripe adding reshape
417+ deadlock/potential data corruption. Update superblock when
418+ specific devices are requested via rebuild. Fix RAID leg
419+ rebuild errors.
Documentation/admin-guide/device-mapper/dm-service-time.rst+101−0
@@ -0,0 +1,101 @@
1+===============
2+dm-service-time
3+===============
4+
5+dm-service-time is a path selector module for device-mapper targets,
6+which selects a path with the shortest estimated service time for
7+the incoming I/O.
8+
9+The service time for each path is estimated by dividing the total size
10+of in-flight I/Os on a path with the performance value of the path.
11+The performance value is a relative throughput value among all paths
12+in a path-group, and it can be specified as a table argument.
13+
14+The path selector name is 'service-time'.
15+
16+Table parameters for each path:
17+
18+ [<repeat_count> [<relative_throughput>]]
19+ <repeat_count>:
20+ The number of I/Os to dispatch using the selected
21+ path before switching to the next path.
22+ If not given, internal default is used. To check
23+ the default value, see the activated table.
24+ <relative_throughput>:
25+ The relative throughput value of the path
26+ among all paths in the path-group.
27+ The valid range is 0-100.
28+ If not given, minimum value '1' is used.
29+ If '0' is given, the path isn't selected while
30+ other paths having a positive value are available.
31+
32+Status for each path:
33+
34+ <status> <fail-count> <in-flight-size> <relative_throughput>
35+ <status>:
36+ 'A' if the path is active, 'F' if the path is failed.
37+ <fail-count>:
38+ The number of path failures.
39+ <in-flight-size>:
40+ The size of in-flight I/Os on the path.
41+ <relative_throughput>:
42+ The relative throughput value of the path
43+ among all paths in the path-group.
44+
45+
46+Algorithm
47+=========
48+
49+dm-service-time adds the I/O size to 'in-flight-size' when the I/O is
50+dispatched and subtracts when completed.
51+Basically, dm-service-time selects a path having minimum service time
52+which is calculated by::
53+
54+ ('in-flight-size' + 'size-of-incoming-io') / 'relative_throughput'
55+
56+However, some optimizations below are used to reduce the calculation
57+as much as possible.
58+
59+ 1. If the paths have the same 'relative_throughput', skip
60+ the division and just compare the 'in-flight-size'.
61+
62+ 2. If the paths have the same 'in-flight-size', skip the division
63+ and just compare the 'relative_throughput'.
64+
65+ 3. If some paths have non-zero 'relative_throughput' and others
66+ have zero 'relative_throughput', ignore those paths with zero
67+ 'relative_throughput'.
68+
69+If such optimizations can't be applied, calculate service time, and
70+compare service time.
71+If calculated service time is equal, the path having maximum
72+'relative_throughput' may be better. So compare 'relative_throughput'
73+then.
74+
75+
76+Examples
77+========
78+In case that 2 paths (sda and sdb) are used with repeat_count == 128
79+and sda has an average throughput 1GB/s and sdb has 4GB/s,
80+'relative_throughput' value may be '1' for sda and '4' for sdb::
81+
82+ # echo "0 10 multipath 0 0 1 1 service-time 0 2 2 8:0 128 1 8:16 128 4" \
83+ dmsetup create test
84+ #
85+ # dmsetup table
86+ test: 0 10 multipath 0 0 1 1 service-time 0 2 2 8:0 128 1 8:16 128 4
87+ #
88+ # dmsetup status
89+ test: 0 10 multipath 2 0 0 0 1 1 E 0 2 2 8:0 A 0 0 1 8:16 A 0 0 4
90+
91+
92+Or '2' for sda and '8' for sdb would be also true::
93+
94+ # echo "0 10 multipath 0 0 1 1 service-time 0 2 2 8:0 128 2 8:16 128 8" \
95+ dmsetup create test
96+ #
97+ # dmsetup table
98+ test: 0 10 multipath 0 0 1 1 service-time 0 2 2 8:0 128 2 8:16 128 8
99+ #
100+ # dmsetup status
101+ test: 0 10 multipath 2 0 0 0 1 1 E 0 2 2 8:0 A 0 0 2 8:16 A 0 0 8
Documentation/admin-guide/device-mapper/dm-uevent.rst+110−0
@@ -0,0 +1,110 @@
1+====================
2+device-mapper uevent
3+====================
4+
5+The device-mapper uevent code adds the capability to device-mapper to create
6+and send kobject uevents (uevents). Previously device-mapper events were only
7+available through the ioctl interface. The advantage of the uevents interface
8+is the event contains environment attributes providing increased context for
9+the event avoiding the need to query the state of the device-mapper device after
10+the event is received.
11+
12+There are two functions currently for device-mapper events. The first function
13+listed creates the event and the second function sends the event(s)::
14+
15+ void dm_path_uevent(enum dm_uevent_type event_type, struct dm_target *ti,
16+ const char *path, unsigned nr_valid_paths)
17+
18+ void dm_send_uevents(struct list_head *events, struct kobject *kobj)
19+
20+
21+The variables added to the uevent environment are:
22+
23+Variable Name: DM_TARGET
24+------------------------
25+:Uevent Action(s): KOBJ_CHANGE
26+:Type: string
27+:Description:
28+:Value: Name of device-mapper target that generated the event.
29+
30+Variable Name: DM_ACTION
31+------------------------
32+:Uevent Action(s): KOBJ_CHANGE
33+:Type: string
34+:Description:
35+:Value: Device-mapper specific action that caused the uevent action.
36+ PATH_FAILED - A path has failed;
37+ PATH_REINSTATED - A path has been reinstated.
38+
39+Variable Name: DM_SEQNUM
40+------------------------
41+:Uevent Action(s): KOBJ_CHANGE
42+:Type: unsigned integer
43+:Description: A sequence number for this specific device-mapper device.
44+:Value: Valid unsigned integer range.
45+
46+Variable Name: DM_PATH
47+----------------------
48+:Uevent Action(s): KOBJ_CHANGE
49+:Type: string
50+:Description: Major and minor number of the path device pertaining to this
51+ event.
52+:Value: Path name in the form of "Major:Minor"
53+
54+Variable Name: DM_NR_VALID_PATHS
55+--------------------------------
56+:Uevent Action(s): KOBJ_CHANGE
57+:Type: unsigned integer
58+:Description:
59+:Value: Valid unsigned integer range.
60+
61+Variable Name: DM_NAME
62+----------------------
63+:Uevent Action(s): KOBJ_CHANGE
64+:Type: string
65+:Description: Name of the device-mapper device.
66+:Value: Name
67+
68+Variable Name: DM_UUID
69+----------------------
70+:Uevent Action(s): KOBJ_CHANGE
71+:Type: string
72+:Description: UUID of the device-mapper device.
73+:Value: UUID. (Empty string if there isn't one.)
74+
75+An example of the uevents generated as captured by udevmonitor is shown
76+below
77+
78+1.) Path failure::
79+
80+ UEVENT[1192521009.711215] change@/block/dm-3
81+ ACTION=change
82+ DEVPATH=/block/dm-3
83+ SUBSYSTEM=block
84+ DM_TARGET=multipath
85+ DM_ACTION=PATH_FAILED
86+ DM_SEQNUM=1
87+ DM_PATH=8:32
88+ DM_NR_VALID_PATHS=0
89+ DM_NAME=mpath2
90+ DM_UUID=mpath-35333333000002328
91+ MINOR=3
92+ MAJOR=253
93+ SEQNUM=1130
94+
95+2.) Path reinstate::
96+
97+ UEVENT[1192521132.989927] change@/block/dm-3
98+ ACTION=change
99+ DEVPATH=/block/dm-3
100+ SUBSYSTEM=block
101+ DM_TARGET=multipath
102+ DM_ACTION=PATH_REINSTATED
103+ DM_SEQNUM=2
104+ DM_PATH=8:32
105+ DM_NR_VALID_PATHS=1
106+ DM_NAME=mpath2
107+ DM_UUID=mpath-35333333000002328
108+ MINOR=3
109+ MAJOR=253
110+ SEQNUM=1131
Documentation/admin-guide/device-mapper/dm-zoned.rst+146−0
@@ -0,0 +1,146 @@
1+========
2+dm-zoned
3+========
4+
5+The dm-zoned device mapper target exposes a zoned block device (ZBC and
6+ZAC compliant devices) as a regular block device without any write
7+pattern constraints. In effect, it implements a drive-managed zoned
8+block device which hides from the user (a file system or an application
9+doing raw block device accesses) the sequential write constraints of
10+host-managed zoned block devices and can mitigate the potential
11+device-side performance degradation due to excessive random writes on
12+host-aware zoned block devices.
13+
14+For a more detailed description of the zoned block device models and
15+their constraints see (for SCSI devices):
16+
17+http://www.t10.org/drafts.htm#ZBC_Family
18+
19+and (for ATA devices):
20+
21+http://www.t13.org/Documents/UploadedDocuments/docs2015/di537r05-Zoned_Device_ATA_Command_Set_ZAC.pdf
22+
23+The dm-zoned implementation is simple and minimizes system overhead (CPU
24+and memory usage as well as storage capacity loss). For a 10TB
25+host-managed disk with 256 MB zones, dm-zoned memory usage per disk
26+instance is at most 4.5 MB and as little as 5 zones will be used
27+internally for storing metadata and performaing reclaim operations.
28+
29+dm-zoned target devices are formatted and checked using the dmzadm
30+utility available at:
31+
32+https://github.com/hgst/dm-zoned-tools
33+
34+Algorithm
35+=========
36+
37+dm-zoned implements an on-disk buffering scheme to handle non-sequential
38+write accesses to the sequential zones of a zoned block device.
39+Conventional zones are used for caching as well as for storing internal
40+metadata.
41+
42+The zones of the device are separated into 2 types:
43+
44+1) Metadata zones: these are conventional zones used to store metadata.
45+Metadata zones are not reported as useable capacity to the user.
46+
47+2) Data zones: all remaining zones, the vast majority of which will be
48+sequential zones used exclusively to store user data. The conventional
49+zones of the device may be used also for buffering user random writes.
50+Data in these zones may be directly mapped to the conventional zone, but
51+later moved to a sequential zone so that the conventional zone can be
52+reused for buffering incoming random writes.
53+
54+dm-zoned exposes a logical device with a sector size of 4096 bytes,
55+irrespective of the physical sector size of the backend zoned block
56+device being used. This allows reducing the amount of metadata needed to
57+manage valid blocks (blocks written).
58+
59+The on-disk metadata format is as follows:
60+
61+1) The first block of the first conventional zone found contains the
62+super block which describes the on disk amount and position of metadata
63+blocks.
64+
65+2) Following the super block, a set of blocks is used to describe the
66+mapping of the logical device blocks. The mapping is done per chunk of
67+blocks, with the chunk size equal to the zoned block device size. The
68+mapping table is indexed by chunk number and each mapping entry
69+indicates the zone number of the device storing the chunk of data. Each
70+mapping entry may also indicate if the zone number of a conventional
71+zone used to buffer random modification to the data zone.
72+
73+3) A set of blocks used to store bitmaps indicating the validity of
74+blocks in the data zones follows the mapping table. A valid block is
75+defined as a block that was written and not discarded. For a buffered
76+data chunk, a block is always valid only in the data zone mapping the
77+chunk or in the buffer zone of the chunk.
78+
79+For a logical chunk mapped to a conventional zone, all write operations
80+are processed by directly writing to the zone. If the mapping zone is a
81+sequential zone, the write operation is processed directly only if the
82+write offset within the logical chunk is equal to the write pointer
83+offset within of the sequential data zone (i.e. the write operation is
84+aligned on the zone write pointer). Otherwise, write operations are
85+processed indirectly using a buffer zone. In that case, an unused
86+conventional zone is allocated and assigned to the chunk being
87+accessed. Writing a block to the buffer zone of a chunk will
88+automatically invalidate the same block in the sequential zone mapping
89+the chunk. If all blocks of the sequential zone become invalid, the zone
90+is freed and the chunk buffer zone becomes the primary zone mapping the
91+chunk, resulting in native random write performance similar to a regular
92+block device.
93+
94+Read operations are processed according to the block validity
95+information provided by the bitmaps. Valid blocks are read either from
96+the sequential zone mapping a chunk, or if the chunk is buffered, from
97+the buffer zone assigned. If the accessed chunk has no mapping, or the
98+accessed blocks are invalid, the read buffer is zeroed and the read
99+operation terminated.
100+
101+After some time, the limited number of convnetional zones available may
102+be exhausted (all used to map chunks or buffer sequential zones) and
103+unaligned writes to unbuffered chunks become impossible. To avoid this
104+situation, a reclaim process regularly scans used conventional zones and
105+tries to reclaim the least recently used zones by copying the valid
106+blocks of the buffer zone to a free sequential zone. Once the copy
107+completes, the chunk mapping is updated to point to the sequential zone
108+and the buffer zone freed for reuse.
109+
110+Metadata Protection
111+===================
112+
113+To protect metadata against corruption in case of sudden power loss or
114+system crash, 2 sets of metadata zones are used. One set, the primary
115+set, is used as the main metadata region, while the secondary set is
116+used as a staging area. Modified metadata is first written to the
117+secondary set and validated by updating the super block in the secondary
118+set, a generation counter is used to indicate that this set contains the
119+newest metadata. Once this operation completes, in place of metadata
120+block updates can be done in the primary metadata set. This ensures that
121+one of the set is always consistent (all modifications committed or none
122+at all). Flush operations are used as a commit point. Upon reception of
123+a flush request, metadata modification activity is temporarily blocked
124+(for both incoming BIO processing and reclaim process) and all dirty
125+metadata blocks are staged and updated. Normal operation is then
126+resumed. Flushing metadata thus only temporarily delays write and
127+discard requests. Read requests can be processed concurrently while
128+metadata flush is being executed.
129+
130+Usage
131+=====
132+
133+A zoned block device must first be formatted using the dmzadm tool. This
134+will analyze the device zone configuration, determine where to place the
135+metadata sets on the device and initialize the metadata sets.
136+
137+Ex::
138+
139+ dmzadm --format /dev/sdxx
140+
141+For a formatted device, the target can be created normally with the
142+dmsetup utility. The only parameter that dm-zoned requires is the
143+underlying zoned block device name. Ex::
144+
145+ echo "0 `blockdev --getsize ${dev}` zoned ${dev}" | \
146+ dmsetup create dmz-`basename ${dev}`
Documentation/admin-guide/device-mapper/era.rst+116−0
@@ -0,0 +1,116 @@
1+======
2+dm-era
3+======
4+
5+Introduction
6+============
7+
8+dm-era is a target that behaves similar to the linear target. In
9+addition it keeps track of which blocks were written within a user
10+defined period of time called an 'era'. Each era target instance
11+maintains the current era as a monotonically increasing 32-bit
12+counter.
13+
14+Use cases include tracking changed blocks for backup software, and
15+partially invalidating the contents of a cache to restore cache
16+coherency after rolling back a vendor snapshot.
17+
18+Constructor
19+===========
20+
21+era <metadata dev> <origin dev> <block size>
22+
23+ ================ ======================================================
24+ metadata dev fast device holding the persistent metadata
25+ origin dev device holding data blocks that may change
26+ block size block size of origin data device, granularity that is
27+ tracked by the target
28+ ================ ======================================================
29+
30+Messages
31+========
32+
33+None of the dm messages take any arguments.
34+
35+checkpoint
36+----------
37+
38+Possibly move to a new era. You shouldn't assume the era has
39+incremented. After sending this message, you should check the
40+current era via the status line.
41+
42+take_metadata_snap
43+------------------
44+
45+Create a clone of the metadata, to allow a userland process to read it.
46+
47+drop_metadata_snap
48+------------------
49+
50+Drop the metadata snapshot.
51+
52+Status
53+======
54+
55+<metadata block size> <#used metadata blocks>/<#total metadata blocks>
56+<current era> <held metadata root | '-'>
57+
58+========================= ==============================================
59+metadata block size Fixed block size for each metadata block in
60+ sectors
61+#used metadata blocks Number of metadata blocks used
62+#total metadata blocks Total number of metadata blocks
63+current era The current era
64+held metadata root The location, in blocks, of the metadata root
65+ that has been 'held' for userspace read
66+ access. '-' indicates there is no held root
67+========================= ==============================================
68+
69+Detailed use case
70+=================
71+
72+The scenario of invalidating a cache when rolling back a vendor
73+snapshot was the primary use case when developing this target:
74+
75+Taking a vendor snapshot
76+------------------------
77+
78+- Send a checkpoint message to the era target
79+- Make a note of the current era in its status line
80+- Take vendor snapshot (the era and snapshot should be forever
81+ associated now).
82+
83+Rolling back to an vendor snapshot
84+----------------------------------
85+
86+- Cache enters passthrough mode (see: dm-cache's docs in cache.txt)
87+- Rollback vendor storage
88+- Take metadata snapshot
89+- Ascertain which blocks have been written since the snapshot was taken
90+ by checking each block's era
91+- Invalidate those blocks in the caching software
92+- Cache returns to writeback/writethrough mode
93+
94+Memory usage
95+============
96+
97+The target uses a bitset to record writes in the current era. It also
98+has a spare bitset ready for switching over to a new era. Other than
99+that it uses a few 4k blocks for updating metadata::
100+
101+ (4 * nr_blocks) bytes + buffers
102+
103+Resilience
104+==========
105+
106+Metadata is updated on disk before a write to a previously unwritten
107+block is performed. As such dm-era should not be effected by a hard
108+crash such as power failure.
109+
110+Userland tools
111+==============
112+
113+Userland tools are found in the increasingly poorly named
114+thin-provisioning-tools project:
115+
116+ https://github.com/jthornber/thin-provisioning-tools
Documentation/admin-guide/device-mapper/index.rst+42−0
@@ -0,0 +1,42 @@
1+=============
2+Device Mapper
3+=============
4+
5+.. toctree::
6+ :maxdepth: 1
7+
8+ cache-policies
9+ cache
10+ delay
11+ dm-crypt
12+ dm-flakey
13+ dm-init
14+ dm-integrity
15+ dm-io
16+ dm-log
17+ dm-queue-length
18+ dm-raid
19+ dm-service-time
20+ dm-uevent
21+ dm-zoned
22+ era
23+ kcopyd
24+ linear
25+ log-writes
26+ persistent-data
27+ snapshot
28+ statistics
29+ striped
30+ switch
31+ thin-provisioning
32+ unstriped
33+ verity
34+ writecache
35+ zero
36+
37+.. only:: subproject and html
38+
39+ Indices
40+ =======
41+
42+ * :ref:`genindex`
Documentation/admin-guide/device-mapper/kcopyd.rst+47−0
@@ -0,0 +1,47 @@
1+======
2+kcopyd
3+======
4+
5+Kcopyd provides the ability to copy a range of sectors from one block-device
6+to one or more other block-devices, with an asynchronous completion
7+notification. It is used by dm-snapshot and dm-mirror.
8+
9+Users of kcopyd must first create a client and indicate how many memory pages
10+to set aside for their copy jobs. This is done with a call to
11+kcopyd_client_create()::
12+
13+ int kcopyd_client_create(unsigned int num_pages,
14+ struct kcopyd_client **result);
15+
16+To start a copy job, the user must set up io_region structures to describe
17+the source and destinations of the copy. Each io_region indicates a
18+block-device along with the starting sector and size of the region. The source
19+of the copy is given as one io_region structure, and the destinations of the
20+copy are given as an array of io_region structures::
21+
22+ struct io_region {
23+ struct block_device *bdev;
24+ sector_t sector;
25+ sector_t count;
26+ };
27+
28+To start the copy, the user calls kcopyd_copy(), passing in the client
29+pointer, pointers to the source and destination io_regions, the name of a
30+completion callback routine, and a pointer to some context data for the copy::
31+
32+ int kcopyd_copy(struct kcopyd_client *kc, struct io_region *from,
33+ unsigned int num_dests, struct io_region *dests,
34+ unsigned int flags, kcopyd_notify_fn fn, void *context);
35+
36+ typedef void (*kcopyd_notify_fn)(int read_err, unsigned int write_err,
37+ void *context);
38+
39+When the copy completes, kcopyd will call the user's completion routine,
40+passing back the user's context pointer. It will also indicate if a read or
41+write error occurred during the copy.
42+
43+When a user is done with all their copy jobs, they should call
44+kcopyd_client_destroy() to delete the kcopyd client, which will release the
45+associated memory pages::
46+
47+ void kcopyd_client_destroy(struct kcopyd_client *kc);
Documentation/admin-guide/device-mapper/linear.rst+63−0
@@ -0,0 +1,63 @@
1+=========
2+dm-linear
3+=========
4+
5+Device-Mapper's "linear" target maps a linear range of the Device-Mapper
6+device onto a linear range of another device. This is the basic building
7+block of logical volume managers.
8+
9+Parameters: <dev path> <offset>
10+ <dev path>:
11+ Full pathname to the underlying block-device, or a
12+ "major:minor" device-number.
13+ <offset>:
14+ Starting sector within the device.
15+
16+
17+Example scripts
18+===============
19+
20+::
21+
22+ #!/bin/sh
23+ # Create an identity mapping for a device
24+ echo "0 `blockdev --getsz $1` linear $1 0" | dmsetup create identity
25+
26+::
27+
28+ #!/bin/sh
29+ # Join 2 devices together
30+ size1=`blockdev --getsz $1`
31+ size2=`blockdev --getsz $2`
32+ echo "0 $size1 linear $1 0
33+ $size1 $size2 linear $2 0" | dmsetup create joined
34+
35+::
36+
37+ #!/usr/bin/perl -w
38+ # Split a device into 4M chunks and then join them together in reverse order.
39+
40+ my $name = "reverse";
41+ my $extent_size = 4 * 1024 * 2;
42+ my $dev = $ARGV[0];
43+ my $table = "";
44+ my $count = 0;
45+
46+ if (!defined($dev)) {
47+ die("Please specify a device.\n");
48+ }
49+
50+ my $dev_size = `blockdev --getsz $dev`;
51+ my $extents = int($dev_size / $extent_size) -
52+ (($dev_size % $extent_size) ? 1 : 0);
53+
54+ while ($extents > 0) {
55+ my $this_start = $count * $extent_size;
56+ $extents--;
57+ $count++;
58+ my $this_offset = $extents * $extent_size;
59+
60+ $table .= "$this_start $extent_size linear $dev $this_offset\n";
61+ }
62+
63+ `echo \"$table\" | dmsetup create $name`;
Documentation/admin-guide/device-mapper/log-writes.rst+145−0
@@ -0,0 +1,145 @@
1+=============
2+dm-log-writes
3+=============
4+
5+This target takes 2 devices, one to pass all IO to normally, and one to log all
6+of the write operations to. This is intended for file system developers wishing
7+to verify the integrity of metadata or data as the file system is written to.
8+There is a log_write_entry written for every WRITE request and the target is
9+able to take arbitrary data from userspace to insert into the log. The data
10+that is in the WRITE requests is copied into the log to make the replay happen
11+exactly as it happened originally.
12+
13+Log Ordering
14+============
15+
16+We log things in order of completion once we are sure the write is no longer in
17+cache. This means that normal WRITE requests are not actually logged until the
18+next REQ_PREFLUSH request. This is to make it easier for userspace to replay
19+the log in a way that correlates to what is on disk and not what is in cache,
20+to make it easier to detect improper waiting/flushing.
21+
22+This works by attaching all WRITE requests to a list once the write completes.
23+Once we see a REQ_PREFLUSH request we splice this list onto the request and once
24+the FLUSH request completes we log all of the WRITEs and then the FLUSH. Only
25+completed WRITEs, at the time the REQ_PREFLUSH is issued, are added in order to
26+simulate the worst case scenario with regard to power failures. Consider the
27+following example (W means write, C means complete):
28+
29+ W1,W2,W3,C3,C2,Wflush,C1,Cflush
30+
31+The log would show the following:
32+
33+ W3,W2,flush,W1....
34+
35+Again this is to simulate what is actually on disk, this allows us to detect
36+cases where a power failure at a particular point in time would create an
37+inconsistent file system.
38+
39+Any REQ_FUA requests bypass this flushing mechanism and are logged as soon as
40+they complete as those requests will obviously bypass the device cache.
41+
42+Any REQ_OP_DISCARD requests are treated like WRITE requests. Otherwise we would
43+have all the DISCARD requests, and then the WRITE requests and then the FLUSH
44+request. Consider the following example:
45+
46+ WRITE block 1, DISCARD block 1, FLUSH
47+
48+If we logged DISCARD when it completed, the replay would look like this:
49+
50+ DISCARD 1, WRITE 1, FLUSH
51+
52+which isn't quite what happened and wouldn't be caught during the log replay.
53+
54+Target interface
55+================
56+
57+i) Constructor
58+
59+ log-writes <dev_path> <log_dev_path>
60+
61+ ============= ==============================================
62+ dev_path Device that all of the IO will go to normally.
63+ log_dev_path Device where the log entries are written to.
64+ ============= ==============================================
65+
66+ii) Status
67+
68+ <#logged entries> <highest allocated sector>
69+
70+ =========================== ========================
71+ #logged entries Number of logged entries
72+ highest allocated sector Highest allocated sector
73+ =========================== ========================
74+
75+iii) Messages
76+
77+ mark <description>
78+
79+ You can use a dmsetup message to set an arbitrary mark in a log.
80+ For example say you want to fsck a file system after every
81+ write, but first you need to replay up to the mkfs to make sure
82+ we're fsck'ing something reasonable, you would do something like
83+ this::
84+
85+ mkfs.btrfs -f /dev/mapper/log
86+ dmsetup message log 0 mark mkfs
87+ <run test>
88+
89+ This would allow you to replay the log up to the mkfs mark and
90+ then replay from that point on doing the fsck check in the
91+ interval that you want.
92+
93+ Every log has a mark at the end labeled "dm-log-writes-end".
94+
95+Userspace component
96+===================
97+
98+There is a userspace tool that will replay the log for you in various ways.
99+It can be found here: https://github.com/josefbacik/log-writes
100+
101+Example usage
102+=============
103+
104+Say you want to test fsync on your file system. You would do something like
105+this::
106+
107+ TABLE="0 $(blockdev --getsz /dev/sdb) log-writes /dev/sdb /dev/sdc"
108+ dmsetup create log --table "$TABLE"
109+ mkfs.btrfs -f /dev/mapper/log
110+ dmsetup message log 0 mark mkfs
111+
112+ mount /dev/mapper/log /mnt/btrfs-test
113+ <some test that does fsync at the end>
114+ dmsetup message log 0 mark fsync
115+ md5sum /mnt/btrfs-test/foo
116+ umount /mnt/btrfs-test
117+
118+ dmsetup remove log
119+ replay-log --log /dev/sdc --replay /dev/sdb --end-mark fsync
120+ mount /dev/sdb /mnt/btrfs-test
121+ md5sum /mnt/btrfs-test/foo
122+ <verify md5sum's are correct>
123+
124+ Another option is to do a complicated file system operation and verify the file
125+ system is consistent during the entire operation. You could do this with:
126+
127+ TABLE="0 $(blockdev --getsz /dev/sdb) log-writes /dev/sdb /dev/sdc"
128+ dmsetup create log --table "$TABLE"
129+ mkfs.btrfs -f /dev/mapper/log
130+ dmsetup message log 0 mark mkfs
131+
132+ mount /dev/mapper/log /mnt/btrfs-test
133+ <fsstress to dirty the fs>
134+ btrfs filesystem balance /mnt/btrfs-test
135+ umount /mnt/btrfs-test
136+ dmsetup remove log
137+
138+ replay-log --log /dev/sdc --replay /dev/sdb --end-mark mkfs
139+ btrfsck /dev/sdb
140+ replay-log --log /dev/sdc --replay /dev/sdb --start-mark mkfs \
141+ --fsck "btrfsck /dev/sdb" --check fua
142+
143+And that will replay the log until it sees a FUA request, run the fsck command
144+and if the fsck passes it will replay to the next FUA, until it is completed or
145+the fsck command exists abnormally.
Documentation/admin-guide/device-mapper/persistent-data.rst+88−0
@@ -0,0 +1,88 @@
1+===============
2+Persistent data
3+===============
4+
5+Introduction
6+============
7+
8+The more-sophisticated device-mapper targets require complex metadata
9+that is managed in kernel. In late 2010 we were seeing that various
10+different targets were rolling their own data structures, for example:
11+
12+- Mikulas Patocka's multisnap implementation
13+- Heinz Mauelshagen's thin provisioning target
14+- Another btree-based caching target posted to dm-devel
15+- Another multi-snapshot target based on a design of Daniel Phillips
16+
17+Maintaining these data structures takes a lot of work, so if possible
18+we'd like to reduce the number.
19+
20+The persistent-data library is an attempt to provide a re-usable
21+framework for people who want to store metadata in device-mapper
22+targets. It's currently used by the thin-provisioning target and an
23+upcoming hierarchical storage target.
24+
25+Overview
26+========
27+
28+The main documentation is in the header files which can all be found
29+under drivers/md/persistent-data.
30+
31+The block manager
32+-----------------
33+
34+dm-block-manager.[hc]
35+
36+This provides access to the data on disk in fixed sized-blocks. There
37+is a read/write locking interface to prevent concurrent accesses, and
38+keep data that is being used in the cache.
39+
40+Clients of persistent-data are unlikely to use this directly.
41+
42+The transaction manager
43+-----------------------
44+
45+dm-transaction-manager.[hc]
46+
47+This restricts access to blocks and enforces copy-on-write semantics.
48+The only way you can get hold of a writable block through the
49+transaction manager is by shadowing an existing block (ie. doing
50+copy-on-write) or allocating a fresh one. Shadowing is elided within
51+the same transaction so performance is reasonable. The commit method
52+ensures that all data is flushed before it writes the superblock.
53+On power failure your metadata will be as it was when last committed.
54+
55+The Space Maps
56+--------------
57+
58+dm-space-map.h
59+dm-space-map-metadata.[hc]
60+dm-space-map-disk.[hc]
61+
62+On-disk data structures that keep track of reference counts of blocks.
63+Also acts as the allocator of new blocks. Currently two
64+implementations: a simpler one for managing blocks on a different
65+device (eg. thinly-provisioned data blocks); and one for managing
66+the metadata space. The latter is complicated by the need to store
67+its own data within the space it's managing.
68+
69+The data structures
70+-------------------
71+
72+dm-btree.[hc]
73+dm-btree-remove.c
74+dm-btree-spine.c
75+dm-btree-internal.h
76+
77+Currently there is only one data structure, a hierarchical btree.
78+There are plans to add more. For example, something with an
79+array-like interface would see a lot of use.
80+
81+The btree is 'hierarchical' in that you can define it to be composed
82+of nested btrees, and take multiple keys. For example, the
83+thin-provisioning target uses a btree with two levels of nesting.
84+The first maps a device id to a mapping tree, and that in turn maps a
85+virtual block to a physical block.
86+
87+Values stored in the btrees can have arbitrary size. Keys are always
88+64bits, although nesting allows you to use multiple keys.
Documentation/admin-guide/device-mapper/snapshot.rst+196−0
@@ -0,0 +1,196 @@
1+==============================
2+Device-mapper snapshot support
3+==============================
4+
5+Device-mapper allows you, without massive data copying:
6+
7+- To create snapshots of any block device i.e. mountable, saved states of
8+ the block device which are also writable without interfering with the
9+ original content;
10+- To create device "forks", i.e. multiple different versions of the
11+ same data stream.
12+- To merge a snapshot of a block device back into the snapshot's origin
13+ device.
14+
15+In the first two cases, dm copies only the chunks of data that get
16+changed and uses a separate copy-on-write (COW) block device for
17+storage.
18+
19+For snapshot merge the contents of the COW storage are merged back into
20+the origin device.
21+
22+
23+There are three dm targets available:
24+snapshot, snapshot-origin, and snapshot-merge.
25+
26+- snapshot-origin <origin>
27+
28+which will normally have one or more snapshots based on it.
29+Reads will be mapped directly to the backing device. For each write, the
30+original data will be saved in the <COW device> of each snapshot to keep
31+its visible content unchanged, at least until the <COW device> fills up.
32+
33+
34+- snapshot <origin> <COW device> <persistent?> <chunksize>
35+ [<# feature args> [<arg>]*]
36+
37+A snapshot of the <origin> block device is created. Changed chunks of
38+<chunksize> sectors will be stored on the <COW device>. Writes will
39+only go to the <COW device>. Reads will come from the <COW device> or
40+from <origin> for unchanged data. <COW device> will often be
41+smaller than the origin and if it fills up the snapshot will become
42+useless and be disabled, returning errors. So it is important to monitor
43+the amount of free space and expand the <COW device> before it fills up.
44+
45+<persistent?> is P (Persistent) or N (Not persistent - will not survive
46+after reboot). O (Overflow) can be added as a persistent store option
47+to allow userspace to advertise its support for seeing "Overflow" in the
48+snapshot status. So supported store types are "P", "PO" and "N".
49+
50+The difference between persistent and transient is with transient
51+snapshots less metadata must be saved on disk - they can be kept in
52+memory by the kernel.
53+
54+When loading or unloading the snapshot target, the corresponding
55+snapshot-origin or snapshot-merge target must be suspended. A failure to
56+suspend the origin target could result in data corruption.
57+
58+Optional features:
59+
60+ discard_zeroes_cow - a discard issued to the snapshot device that
61+ maps to entire chunks to will zero the corresponding exception(s) in
62+ the snapshot's exception store.
63+
64+ discard_passdown_origin - a discard to the snapshot device is passed
65+ down to the snapshot-origin's underlying device. This doesn't cause
66+ copy-out to the snapshot exception store because the snapshot-origin
67+ target is bypassed.
68+
69+ The discard_passdown_origin feature depends on the discard_zeroes_cow
70+ feature being enabled.
71+
72+
73+- snapshot-merge <origin> <COW device> <persistent> <chunksize>
74+ [<# feature args> [<arg>]*]
75+
76+takes the same table arguments as the snapshot target except it only
77+works with persistent snapshots. This target assumes the role of the
78+"snapshot-origin" target and must not be loaded if the "snapshot-origin"
79+is still present for <origin>.
80+
81+Creates a merging snapshot that takes control of the changed chunks
82+stored in the <COW device> of an existing snapshot, through a handover
83+procedure, and merges these chunks back into the <origin>. Once merging
84+has started (in the background) the <origin> may be opened and the merge
85+will continue while I/O is flowing to it. Changes to the <origin> are
86+deferred until the merging snapshot's corresponding chunk(s) have been
87+merged. Once merging has started the snapshot device, associated with
88+the "snapshot" target, will return -EIO when accessed.
89+
90+
91+How snapshot is used by LVM2
92+============================
93+When you create the first LVM2 snapshot of a volume, four dm devices are used:
94+
95+1) a device containing the original mapping table of the source volume;
96+2) a device used as the <COW device>;
97+3) a "snapshot" device, combining #1 and #2, which is the visible snapshot
98+ volume;
99+4) the "original" volume (which uses the device number used by the original
100+ source volume), whose table is replaced by a "snapshot-origin" mapping
101+ from device #1.
102+
103+A fixed naming scheme is used, so with the following commands::
104+
105+ lvcreate -L 1G -n base volumeGroup
106+ lvcreate -L 100M --snapshot -n snap volumeGroup/base
107+
108+we'll have this situation (with volumes in above order)::
109+
110+ # dmsetup table|grep volumeGroup
111+
112+ volumeGroup-base-real: 0 2097152 linear 8:19 384
113+ volumeGroup-snap-cow: 0 204800 linear 8:19 2097536
114+ volumeGroup-snap: 0 2097152 snapshot 254:11 254:12 P 16
115+ volumeGroup-base: 0 2097152 snapshot-origin 254:11
116+
117+ # ls -lL /dev/mapper/volumeGroup-*
118+ brw------- 1 root root 254, 11 29 ago 18:15 /dev/mapper/volumeGroup-base-real
119+ brw------- 1 root root 254, 12 29 ago 18:15 /dev/mapper/volumeGroup-snap-cow
120+ brw------- 1 root root 254, 13 29 ago 18:15 /dev/mapper/volumeGroup-snap
121+ brw------- 1 root root 254, 10 29 ago 18:14 /dev/mapper/volumeGroup-base
122+
123+
124+How snapshot-merge is used by LVM2
125+==================================
126+A merging snapshot assumes the role of the "snapshot-origin" while
127+merging. As such the "snapshot-origin" is replaced with
128+"snapshot-merge". The "-real" device is not changed and the "-cow"
129+device is renamed to <origin name>-cow to aid LVM2's cleanup of the
130+merging snapshot after it completes. The "snapshot" that hands over its
131+COW device to the "snapshot-merge" is deactivated (unless using lvchange
132+--refresh); but if it is left active it will simply return I/O errors.
133+
134+A snapshot will merge into its origin with the following command::
135+
136+ lvconvert --merge volumeGroup/snap
137+
138+we'll now have this situation::
139+
140+ # dmsetup table|grep volumeGroup
141+
142+ volumeGroup-base-real: 0 2097152 linear 8:19 384
143+ volumeGroup-base-cow: 0 204800 linear 8:19 2097536
144+ volumeGroup-base: 0 2097152 snapshot-merge 254:11 254:12 P 16
145+
146+ # ls -lL /dev/mapper/volumeGroup-*
147+ brw------- 1 root root 254, 11 29 ago 18:15 /dev/mapper/volumeGroup-base-real
148+ brw------- 1 root root 254, 12 29 ago 18:16 /dev/mapper/volumeGroup-base-cow
149+ brw------- 1 root root 254, 10 29 ago 18:16 /dev/mapper/volumeGroup-base
150+
151+
152+How to determine when a merging is complete
153+===========================================
154+The snapshot-merge and snapshot status lines end with:
155+
156+ <sectors_allocated>/<total_sectors> <metadata_sectors>
157+
158+Both <sectors_allocated> and <total_sectors> include both data and metadata.
159+During merging, the number of sectors allocated gets smaller and
160+smaller. Merging has finished when the number of sectors holding data
161+is zero, in other words <sectors_allocated> == <metadata_sectors>.
162+
163+Here is a practical example (using a hybrid of lvm and dmsetup commands)::
164+
165+ # lvs
166+ LV VG Attr LSize Origin Snap% Move Log Copy% Convert
167+ base volumeGroup owi-a- 4.00g
168+ snap volumeGroup swi-a- 1.00g base 18.97
169+
170+ # dmsetup status volumeGroup-snap
171+ 0 8388608 snapshot 397896/2097152 1560
172+ ^^^^ metadata sectors
173+
174+ # lvconvert --merge -b volumeGroup/snap
175+ Merging of volume snap started.
176+
177+ # lvs volumeGroup/snap
178+ LV VG Attr LSize Origin Snap% Move Log Copy% Convert
179+ base volumeGroup Owi-a- 4.00g 17.23
180+
181+ # dmsetup status volumeGroup-base
182+ 0 8388608 snapshot-merge 281688/2097152 1104
183+
184+ # dmsetup status volumeGroup-base
185+ 0 8388608 snapshot-merge 180480/2097152 712
186+
187+ # dmsetup status volumeGroup-base
188+ 0 8388608 snapshot-merge 16/2097152 16
189+
190+Merging has finished.
191+
192+::
193+
194+ # lvs
195+ LV VG Attr LSize Origin Snap% Move Log Copy% Convert
196+ base volumeGroup owi-a- 4.00g
Documentation/admin-guide/device-mapper/statistics.rst+225−0
@@ -0,0 +1,225 @@
1+=============
2+DM statistics
3+=============
4+
5+Device Mapper supports the collection of I/O statistics on user-defined
6+regions of a DM device. If no regions are defined no statistics are
7+collected so there isn't any performance impact. Only bio-based DM
8+devices are currently supported.
9+
10+Each user-defined region specifies a starting sector, length and step.
11+Individual statistics will be collected for each step-sized area within
12+the range specified.
13+
14+The I/O statistics counters for each step-sized area of a region are
15+in the same format as `/sys/block/*/stat` or `/proc/diskstats` (see:
16+Documentation/admin-guide/iostats.rst). But two extra counters (12 and 13) are
17+provided: total time spent reading and writing. When the histogram
18+argument is used, the 14th parameter is reported that represents the
19+histogram of latencies. All these counters may be accessed by sending
20+the @stats_print message to the appropriate DM device via dmsetup.
21+
22+The reported times are in milliseconds and the granularity depends on
23+the kernel ticks. When the option precise_timestamps is used, the
24+reported times are in nanoseconds.
25+
26+Each region has a corresponding unique identifier, which we call a
27+region_id, that is assigned when the region is created. The region_id
28+must be supplied when querying statistics about the region, deleting the
29+region, etc. Unique region_ids enable multiple userspace programs to
30+request and process statistics for the same DM device without stepping
31+on each other's data.
32+
33+The creation of DM statistics will allocate memory via kmalloc or
34+fallback to using vmalloc space. At most, 1/4 of the overall system
35+memory may be allocated by DM statistics. The admin can see how much
36+memory is used by reading:
37+
38+ /sys/module/dm_mod/parameters/stats_current_allocated_bytes
39+
40+Messages
41+========
42+
43+ @stats_create <range> <step> [<number_of_optional_arguments> <optional_arguments>...] [<program_id> [<aux_data>]]
44+ Create a new region and return the region_id.
45+
46+ <range>
47+ "-"
48+ whole device
49+ "<start_sector>+<length>"
50+ a range of <length> 512-byte sectors
51+ starting with <start_sector>.
52+
53+ <step>
54+ "<area_size>"
55+ the range is subdivided into areas each containing
56+ <area_size> sectors.
57+ "/<number_of_areas>"
58+ the range is subdivided into the specified
59+ number of areas.
60+
61+ <number_of_optional_arguments>
62+ The number of optional arguments
63+
64+ <optional_arguments>
65+ The following optional arguments are supported:
66+
67+ precise_timestamps
68+ use precise timer with nanosecond resolution
69+ instead of the "jiffies" variable. When this argument is
70+ used, the resulting times are in nanoseconds instead of
71+ milliseconds. Precise timestamps are a little bit slower
72+ to obtain than jiffies-based timestamps.
73+ histogram:n1,n2,n3,n4,...
74+ collect histogram of latencies. The
75+ numbers n1, n2, etc are times that represent the boundaries
76+ of the histogram. If precise_timestamps is not used, the
77+ times are in milliseconds, otherwise they are in
78+ nanoseconds. For each range, the kernel will report the
79+ number of requests that completed within this range. For
80+ example, if we use "histogram:10,20,30", the kernel will
81+ report four numbers a:b:c:d. a is the number of requests
82+ that took 0-10 ms to complete, b is the number of requests
83+ that took 10-20 ms to complete, c is the number of requests
84+ that took 20-30 ms to complete and d is the number of
85+ requests that took more than 30 ms to complete.
86+
87+ <program_id>
88+ An optional parameter. A name that uniquely identifies
89+ the userspace owner of the range. This groups ranges together
90+ so that userspace programs can identify the ranges they
91+ created and ignore those created by others.
92+ The kernel returns this string back in the output of
93+ @stats_list message, but it doesn't use it for anything else.
94+ If we omit the number of optional arguments, program id must not
95+ be a number, otherwise it would be interpreted as the number of
96+ optional arguments.
97+
98+ <aux_data>
99+ An optional parameter. A word that provides auxiliary data
100+ that is useful to the client program that created the range.
101+ The kernel returns this string back in the output of
102+ @stats_list message, but it doesn't use this value for anything.
103+
104+ @stats_delete <region_id>
105+ Delete the region with the specified id.
106+
107+ <region_id>
108+ region_id returned from @stats_create
109+
110+ @stats_clear <region_id>
111+ Clear all the counters except the in-flight i/o counters.
112+
113+ <region_id>
114+ region_id returned from @stats_create
115+
116+ @stats_list [<program_id>]
117+ List all regions registered with @stats_create.
118+
119+ <program_id>
120+ An optional parameter.
121+ If this parameter is specified, only matching regions
122+ are returned.
123+ If it is not specified, all regions are returned.
124+
125+ Output format:
126+ <region_id>: <start_sector>+<length> <step> <program_id> <aux_data>
127+ precise_timestamps histogram:n1,n2,n3,...
128+
129+ The strings "precise_timestamps" and "histogram" are printed only
130+ if they were specified when creating the region.
131+
132+ @stats_print <region_id> [<starting_line> <number_of_lines>]
133+ Print counters for each step-sized area of a region.
134+
135+ <region_id>
136+ region_id returned from @stats_create
137+
138+ <starting_line>
139+ The index of the starting line in the output.
140+ If omitted, all lines are returned.
141+
142+ <number_of_lines>
143+ The number of lines to include in the output.
144+ If omitted, all lines are returned.
145+
146+ Output format for each step-sized area of a region:
147+
148+ <start_sector>+<length>
149+ counters
150+
151+ The first 11 counters have the same meaning as
152+ `/sys/block/*/stat or /proc/diskstats`.
153+
154+ Please refer to Documentation/admin-guide/iostats.rst for details.
155+
156+ 1. the number of reads completed
157+ 2. the number of reads merged
158+ 3. the number of sectors read
159+ 4. the number of milliseconds spent reading
160+ 5. the number of writes completed
161+ 6. the number of writes merged
162+ 7. the number of sectors written
163+ 8. the number of milliseconds spent writing
164+ 9. the number of I/Os currently in progress
165+ 10. the number of milliseconds spent doing I/Os
166+ 11. the weighted number of milliseconds spent doing I/Os
167+
168+ Additional counters:
169+
170+ 12. the total time spent reading in milliseconds
171+ 13. the total time spent writing in milliseconds
172+
173+ @stats_print_clear <region_id> [<starting_line> <number_of_lines>]
174+ Atomically print and then clear all the counters except the
175+ in-flight i/o counters. Useful when the client consuming the
176+ statistics does not want to lose any statistics (those updated
177+ between printing and clearing).
178+
179+ <region_id>
180+ region_id returned from @stats_create
181+
182+ <starting_line>
183+ The index of the starting line in the output.
184+ If omitted, all lines are printed and then cleared.
185+
186+ <number_of_lines>
187+ The number of lines to process.
188+ If omitted, all lines are printed and then cleared.
189+
190+ @stats_set_aux <region_id> <aux_data>
191+ Store auxiliary data aux_data for the specified region.
192+
193+ <region_id>
194+ region_id returned from @stats_create
195+
196+ <aux_data>
197+ The string that identifies data which is useful to the client
198+ program that created the range. The kernel returns this
199+ string back in the output of @stats_list message, but it
200+ doesn't use this value for anything.
201+
202+Examples
203+========
204+
205+Subdivide the DM device 'vol' into 100 pieces and start collecting
206+statistics on them::
207+
208+ dmsetup message vol 0 @stats_create - /100
209+
210+Set the auxiliary data string to "foo bar baz" (the escape for each
211+space must also be escaped, otherwise the shell will consume them)::
212+
213+ dmsetup message vol 0 @stats_set_aux 0 foo\\ bar\\ baz
214+
215+List the statistics::
216+
217+ dmsetup message vol 0 @stats_list
218+
219+Print the statistics::
220+
221+ dmsetup message vol 0 @stats_print 0
222+
223+Delete the statistics::
224+
225+ dmsetup message vol 0 @stats_delete 0
Documentation/admin-guide/device-mapper/striped.rst+61−0
@@ -0,0 +1,61 @@
1+=========
2+dm-stripe
3+=========
4+
5+Device-Mapper's "striped" target is used to create a striped (i.e. RAID-0)
6+device across one or more underlying devices. Data is written in "chunks",
7+with consecutive chunks rotating among the underlying devices. This can
8+potentially provide improved I/O throughput by utilizing several physical
9+devices in parallel.
10+
11+Parameters: <num devs> <chunk size> [<dev path> <offset>]+
12+ <num devs>:
13+ Number of underlying devices.
14+ <chunk size>:
15+ Size of each chunk of data. Must be at least as
16+ large as the system's PAGE_SIZE.
17+ <dev path>:
18+ Full pathname to the underlying block-device, or a
19+ "major:minor" device-number.
20+ <offset>:
21+ Starting sector within the device.
22+
23+One or more underlying devices can be specified. The striped device size must
24+be a multiple of the chunk size multiplied by the number of underlying devices.
25+
26+
27+Example scripts
28+===============
29+
30+::
31+
32+ #!/usr/bin/perl -w
33+ # Create a striped device across any number of underlying devices. The device
34+ # will be called "stripe_dev" and have a chunk-size of 128k.
35+
36+ my $chunk_size = 128 * 2;
37+ my $dev_name = "stripe_dev";
38+ my $num_devs = @ARGV;
39+ my @devs = @ARGV;
40+ my ($min_dev_size, $stripe_dev_size, $i);
41+
42+ if (!$num_devs) {
43+ die("Specify at least one device\n");
44+ }
45+
46+ $min_dev_size = `blockdev --getsz $devs[0]`;
47+ for ($i = 1; $i < $num_devs; $i++) {
48+ my $this_size = `blockdev --getsz $devs[$i]`;
49+ $min_dev_size = ($min_dev_size < $this_size) ?
50+ $min_dev_size : $this_size;
51+ }
52+
53+ $stripe_dev_size = $min_dev_size * $num_devs;
54+ $stripe_dev_size -= $stripe_dev_size % ($chunk_size * $num_devs);
55+
56+ $table = "0 $stripe_dev_size striped $num_devs $chunk_size";
57+ for ($i = 0; $i < $num_devs; $i++) {
58+ $table .= " $devs[$i] 0";
59+ }
60+
61+ `echo $table | dmsetup create $dev_name`;
Documentation/admin-guide/device-mapper/switch.rst+141−0
@@ -0,0 +1,141 @@
1+=========
2+dm-switch
3+=========
4+
5+The device-mapper switch target creates a device that supports an
6+arbitrary mapping of fixed-size regions of I/O across a fixed set of
7+paths. The path used for any specific region can be switched
8+dynamically by sending the target a message.
9+
10+It maps I/O to underlying block devices efficiently when there is a large
11+number of fixed-sized address regions but there is no simple pattern
12+that would allow for a compact representation of the mapping such as
13+dm-stripe.
14+
15+Background
16+----------
17+
18+Dell EqualLogic and some other iSCSI storage arrays use a distributed
19+frameless architecture. In this architecture, the storage group
20+consists of a number of distinct storage arrays ("members") each having
21+independent controllers, disk storage and network adapters. When a LUN
22+is created it is spread across multiple members. The details of the
23+spreading are hidden from initiators connected to this storage system.
24+The storage group exposes a single target discovery portal, no matter
25+how many members are being used. When iSCSI sessions are created, each
26+session is connected to an eth port on a single member. Data to a LUN
27+can be sent on any iSCSI session, and if the blocks being accessed are
28+stored on another member the I/O will be forwarded as required. This
29+forwarding is invisible to the initiator. The storage layout is also
30+dynamic, and the blocks stored on disk may be moved from member to
31+member as needed to balance the load.
32+
33+This architecture simplifies the management and configuration of both
34+the storage group and initiators. In a multipathing configuration, it
35+is possible to set up multiple iSCSI sessions to use multiple network
36+interfaces on both the host and target to take advantage of the
37+increased network bandwidth. An initiator could use a simple round
38+robin algorithm to send I/O across all paths and let the storage array
39+members forward it as necessary, but there is a performance advantage to
40+sending data directly to the correct member.
41+
42+A device-mapper table already lets you map different regions of a
43+device onto different targets. However in this architecture the LUN is
44+spread with an address region size on the order of 10s of MBs, which
45+means the resulting table could have more than a million entries and
46+consume far too much memory.
47+
48+Using this device-mapper switch target we can now build a two-layer
49+device hierarchy:
50+
51+ Upper Tier - Determine which array member the I/O should be sent to.
52+ Lower Tier - Load balance amongst paths to a particular member.
53+
54+The lower tier consists of a single dm multipath device for each member.
55+Each of these multipath devices contains the set of paths directly to
56+the array member in one priority group, and leverages existing path
57+selectors to load balance amongst these paths. We also build a
58+non-preferred priority group containing paths to other array members for
59+failover reasons.
60+
61+The upper tier consists of a single dm-switch device. This device uses
62+a bitmap to look up the location of the I/O and choose the appropriate
63+lower tier device to route the I/O. By using a bitmap we are able to
64+use 4 bits for each address range in a 16 member group (which is very
65+large for us). This is a much denser representation than the dm table
66+b-tree can achieve.
67+
68+Construction Parameters
69+=======================
70+
71+ <num_paths> <region_size> <num_optional_args> [<optional_args>...] [<dev_path> <offset>]+
72+ <num_paths>
73+ The number of paths across which to distribute the I/O.
74+
75+ <region_size>
76+ The number of 512-byte sectors in a region. Each region can be redirected
77+ to any of the available paths.
78+
79+ <num_optional_args>
80+ The number of optional arguments. Currently, no optional arguments
81+ are supported and so this must be zero.
82+
83+ <dev_path>
84+ The block device that represents a specific path to the device.
85+
86+ <offset>
87+ The offset of the start of data on the specific <dev_path> (in units
88+ of 512-byte sectors). This number is added to the sector number when
89+ forwarding the request to the specific path. Typically it is zero.
90+
91+Messages
92+========
93+
94+set_region_mappings <index>:<path_nr> [<index>]:<path_nr> [<index>]:<path_nr>...
95+
96+Modify the region table by specifying which regions are redirected to
97+which paths.
98+
99+<index>
100+ The region number (region size was specified in constructor parameters).
101+ If index is omitted, the next region (previous index + 1) is used.
102+ Expressed in hexadecimal (WITHOUT any prefix like 0x).
103+
104+<path_nr>
105+ The path number in the range 0 ... (<num_paths> - 1).
106+ Expressed in hexadecimal (WITHOUT any prefix like 0x).
107+
108+R<n>,<m>
109+ This parameter allows repetitive patterns to be loaded quickly. <n> and <m>
110+ are hexadecimal numbers. The last <n> mappings are repeated in the next <m>
111+ slots.
112+
113+Status
114+======
115+
116+No status line is reported.
117+
118+Example
119+=======
120+
121+Assume that you have volumes vg1/switch0 vg1/switch1 vg1/switch2 with
122+the same size.
123+
124+Create a switch device with 64kB region size::
125+
126+ dmsetup create switch --table "0 `blockdev --getsz /dev/vg1/switch0`
127+ switch 3 128 0 /dev/vg1/switch0 0 /dev/vg1/switch1 0 /dev/vg1/switch2 0"
128+
129+Set mappings for the first 7 entries to point to devices switch0, switch1,
130+switch2, switch0, switch1, switch2, switch1::
131+
132+ dmsetup message switch 0 set_region_mappings 0:0 :1 :2 :0 :1 :2 :1
133+
134+Set repetitive mapping. This command::
135+
136+ dmsetup message switch 0 set_region_mappings 1000:1 :2 R2,10
137+
138+is equivalent to::
139+
140+ dmsetup message switch 0 set_region_mappings 1000:1 :2 :1 :2 :1 :2 :1 :2 \
141+ :1 :2 :1 :2 :1 :2 :1 :2 :1 :2
Documentation/admin-guide/device-mapper/thin-provisioning.rst+427−0
@@ -0,0 +1,427 @@
1+=================
2+Thin provisioning
3+=================
4+
5+Introduction
6+============
7+
8+This document describes a collection of device-mapper targets that
9+between them implement thin-provisioning and snapshots.
10+
11+The main highlight of this implementation, compared to the previous
12+implementation of snapshots, is that it allows many virtual devices to
13+be stored on the same data volume. This simplifies administration and
14+allows the sharing of data between volumes, thus reducing disk usage.
15+
16+Another significant feature is support for an arbitrary depth of
17+recursive snapshots (snapshots of snapshots of snapshots ...). The
18+previous implementation of snapshots did this by chaining together
19+lookup tables, and so performance was O(depth). This new
20+implementation uses a single data structure to avoid this degradation
21+with depth. Fragmentation may still be an issue, however, in some
22+scenarios.
23+
24+Metadata is stored on a separate device from data, giving the
25+administrator some freedom, for example to:
26+
27+- Improve metadata resilience by storing metadata on a mirrored volume
28+ but data on a non-mirrored one.
29+
30+- Improve performance by storing the metadata on SSD.
31+
32+Status
33+======
34+
35+These targets are considered safe for production use. But different use
36+cases will have different performance characteristics, for example due
37+to fragmentation of the data volume.
38+
39+If you find this software is not performing as expected please mail
40+dm-devel@redhat.com with details and we'll try our best to improve
41+things for you.
42+
43+Userspace tools for checking and repairing the metadata have been fully
44+developed and are available as 'thin_check' and 'thin_repair'. The name
45+of the package that provides these utilities varies by distribution (on
46+a Red Hat distribution it is named 'device-mapper-persistent-data').
47+
48+Cookbook
49+========
50+
51+This section describes some quick recipes for using thin provisioning.
52+They use the dmsetup program to control the device-mapper driver
53+directly. End users will be advised to use a higher-level volume
54+manager such as LVM2 once support has been added.
55+
56+Pool device
57+-----------
58+
59+The pool device ties together the metadata volume and the data volume.
60+It maps I/O linearly to the data volume and updates the metadata via
61+two mechanisms:
62+
63+- Function calls from the thin targets
64+
65+- Device-mapper 'messages' from userspace which control the creation of new
66+ virtual devices amongst other things.
67+
68+Setting up a fresh pool device
69+------------------------------
70+
71+Setting up a pool device requires a valid metadata device, and a
72+data device. If you do not have an existing metadata device you can
73+make one by zeroing the first 4k to indicate empty metadata.
74+
75+ dd if=/dev/zero of=$metadata_dev bs=4096 count=1
76+
77+The amount of metadata you need will vary according to how many blocks
78+are shared between thin devices (i.e. through snapshots). If you have
79+less sharing than average you'll need a larger-than-average metadata device.
80+
81+As a guide, we suggest you calculate the number of bytes to use in the
82+metadata device as 48 * $data_dev_size / $data_block_size but round it up
83+to 2MB if the answer is smaller. If you're creating large numbers of
84+snapshots which are recording large amounts of change, you may find you
85+need to increase this.
86+
87+The largest size supported is 16GB: If the device is larger,
88+a warning will be issued and the excess space will not be used.
89+
90+Reloading a pool table
91+----------------------
92+
93+You may reload a pool's table, indeed this is how the pool is resized
94+if it runs out of space. (N.B. While specifying a different metadata
95+device when reloading is not forbidden at the moment, things will go
96+wrong if it does not route I/O to exactly the same on-disk location as
97+previously.)
98+
99+Using an existing pool device
100+-----------------------------
101+
102+::
103+
104+ dmsetup create pool \
105+ --table "0 20971520 thin-pool $metadata_dev $data_dev \
106+ $data_block_size $low_water_mark"
107+
108+$data_block_size gives the smallest unit of disk space that can be
109+allocated at a time expressed in units of 512-byte sectors.
110+$data_block_size must be between 128 (64KB) and 2097152 (1GB) and a
111+multiple of 128 (64KB). $data_block_size cannot be changed after the
112+thin-pool is created. People primarily interested in thin provisioning
113+may want to use a value such as 1024 (512KB). People doing lots of
114+snapshotting may want a smaller value such as 128 (64KB). If you are
115+not zeroing newly-allocated data, a larger $data_block_size in the
116+region of 256000 (128MB) is suggested.
117+
118+$low_water_mark is expressed in blocks of size $data_block_size. If
119+free space on the data device drops below this level then a dm event
120+will be triggered which a userspace daemon should catch allowing it to
121+extend the pool device. Only one such event will be sent.
122+
123+No special event is triggered if a just resumed device's free space is below
124+the low water mark. However, resuming a device always triggers an
125+event; a userspace daemon should verify that free space exceeds the low
126+water mark when handling this event.
127+
128+A low water mark for the metadata device is maintained in the kernel and
129+will trigger a dm event if free space on the metadata device drops below
130+it.
131+
132+Updating on-disk metadata
133+-------------------------
134+
135+On-disk metadata is committed every time a FLUSH or FUA bio is written.
136+If no such requests are made then commits will occur every second. This
137+means the thin-provisioning target behaves like a physical disk that has
138+a volatile write cache. If power is lost you may lose some recent
139+writes. The metadata should always be consistent in spite of any crash.
140+
141+If data space is exhausted the pool will either error or queue IO
142+according to the configuration (see: error_if_no_space). If metadata
143+space is exhausted or a metadata operation fails: the pool will error IO
144+until the pool is taken offline and repair is performed to 1) fix any
145+potential inconsistencies and 2) clear the flag that imposes repair.
146+Once the pool's metadata device is repaired it may be resized, which
147+will allow the pool to return to normal operation. Note that if a pool
148+is flagged as needing repair, the pool's data and metadata devices
149+cannot be resized until repair is performed. It should also be noted
150+that when the pool's metadata space is exhausted the current metadata
151+transaction is aborted. Given that the pool will cache IO whose
152+completion may have already been acknowledged to upper IO layers
153+(e.g. filesystem) it is strongly suggested that consistency checks
154+(e.g. fsck) be performed on those layers when repair of the pool is
155+required.
156+
157+Thin provisioning
158+-----------------
159+
160+i) Creating a new thinly-provisioned volume.
161+
162+ To create a new thinly- provisioned volume you must send a message to an
163+ active pool device, /dev/mapper/pool in this example::
164+
165+ dmsetup message /dev/mapper/pool 0 "create_thin 0"
166+
167+ Here '0' is an identifier for the volume, a 24-bit number. It's up
168+ to the caller to allocate and manage these identifiers. If the
169+ identifier is already in use, the message will fail with -EEXIST.
170+
171+ii) Using a thinly-provisioned volume.
172+
173+ Thinly-provisioned volumes are activated using the 'thin' target::
174+
175+ dmsetup create thin --table "0 2097152 thin /dev/mapper/pool 0"
176+
177+ The last parameter is the identifier for the thinp device.
178+
179+Internal snapshots
180+------------------
181+
182+i) Creating an internal snapshot.
183+
184+ Snapshots are created with another message to the pool.
185+
186+ N.B. If the origin device that you wish to snapshot is active, you
187+ must suspend it before creating the snapshot to avoid corruption.
188+ This is NOT enforced at the moment, so please be careful!
189+
190+ ::
191+
192+ dmsetup suspend /dev/mapper/thin
193+ dmsetup message /dev/mapper/pool 0 "create_snap 1 0"
194+ dmsetup resume /dev/mapper/thin
195+
196+ Here '1' is the identifier for the volume, a 24-bit number. '0' is the
197+ identifier for the origin device.
198+
199+ii) Using an internal snapshot.
200+
201+ Once created, the user doesn't have to worry about any connection
202+ between the origin and the snapshot. Indeed the snapshot is no
203+ different from any other thinly-provisioned device and can be
204+ snapshotted itself via the same method. It's perfectly legal to
205+ have only one of them active, and there's no ordering requirement on
206+ activating or removing them both. (This differs from conventional
207+ device-mapper snapshots.)
208+
209+ Activate it exactly the same way as any other thinly-provisioned volume::
210+
211+ dmsetup create snap --table "0 2097152 thin /dev/mapper/pool 1"
212+
213+External snapshots
214+------------------
215+
216+You can use an external **read only** device as an origin for a
217+thinly-provisioned volume. Any read to an unprovisioned area of the
218+thin device will be passed through to the origin. Writes trigger
219+the allocation of new blocks as usual.
220+
221+One use case for this is VM hosts that want to run guests on
222+thinly-provisioned volumes but have the base image on another device
223+(possibly shared between many VMs).
224+
225+You must not write to the origin device if you use this technique!
226+Of course, you may write to the thin device and take internal snapshots
227+of the thin volume.
228+
229+i) Creating a snapshot of an external device
230+
231+ This is the same as creating a thin device.
232+ You don't mention the origin at this stage.
233+
234+ ::
235+
236+ dmsetup message /dev/mapper/pool 0 "create_thin 0"
237+
238+ii) Using a snapshot of an external device.
239+
240+ Append an extra parameter to the thin target specifying the origin::
241+
242+ dmsetup create snap --table "0 2097152 thin /dev/mapper/pool 0 /dev/image"
243+
244+ N.B. All descendants (internal snapshots) of this snapshot require the
245+ same extra origin parameter.
246+
247+Deactivation
248+------------
249+
250+All devices using a pool must be deactivated before the pool itself
251+can be.
252+
253+::
254+
255+ dmsetup remove thin
256+ dmsetup remove snap
257+ dmsetup remove pool
258+
259+Reference
260+=========
261+
262+'thin-pool' target
263+------------------
264+
265+i) Constructor
266+
267+ ::
268+
269+ thin-pool <metadata dev> <data dev> <data block size (sectors)> \
270+ <low water mark (blocks)> [<number of feature args> [<arg>]*]
271+
272+ Optional feature arguments:
273+
274+ skip_block_zeroing:
275+ Skip the zeroing of newly-provisioned blocks.
276+
277+ ignore_discard:
278+ Disable discard support.
279+
280+ no_discard_passdown:
281+ Don't pass discards down to the underlying
282+ data device, but just remove the mapping.
283+
284+ read_only:
285+ Don't allow any changes to be made to the pool
286+ metadata. This mode is only available after the
287+ thin-pool has been created and first used in full
288+ read/write mode. It cannot be specified on initial
289+ thin-pool creation.
290+
291+ error_if_no_space:
292+ Error IOs, instead of queueing, if no space.
293+
294+ Data block size must be between 64KB (128 sectors) and 1GB
295+ (2097152 sectors) inclusive.
296+
297+
298+ii) Status
299+
300+ ::
301+
302+ <transaction id> <used metadata blocks>/<total metadata blocks>
303+ <used data blocks>/<total data blocks> <held metadata root>
304+ ro|rw|out_of_data_space [no_]discard_passdown [error|queue]_if_no_space
305+ needs_check|- metadata_low_watermark
306+
307+ transaction id:
308+ A 64-bit number used by userspace to help synchronise with metadata
309+ from volume managers.
310+
311+ used data blocks / total data blocks
312+ If the number of free blocks drops below the pool's low water mark a
313+ dm event will be sent to userspace. This event is edge-triggered and
314+ it will occur only once after each resume so volume manager writers
315+ should register for the event and then check the target's status.
316+
317+ held metadata root:
318+ The location, in blocks, of the metadata root that has been
319+ 'held' for userspace read access. '-' indicates there is no
320+ held root.
321+
322+ discard_passdown|no_discard_passdown
323+ Whether or not discards are actually being passed down to the
324+ underlying device. When this is enabled when loading the table,
325+ it can get disabled if the underlying device doesn't support it.
326+
327+ ro|rw|out_of_data_space
328+ If the pool encounters certain types of device failures it will
329+ drop into a read-only metadata mode in which no changes to
330+ the pool metadata (like allocating new blocks) are permitted.
331+
332+ In serious cases where even a read-only mode is deemed unsafe
333+ no further I/O will be permitted and the status will just
334+ contain the string 'Fail'. The userspace recovery tools
335+ should then be used.
336+
337+ error_if_no_space|queue_if_no_space
338+ If the pool runs out of data or metadata space, the pool will
339+ either queue or error the IO destined to the data device. The
340+ default is to queue the IO until more space is added or the
341+ 'no_space_timeout' expires. The 'no_space_timeout' dm-thin-pool
342+ module parameter can be used to change this timeout -- it
343+ defaults to 60 seconds but may be disabled using a value of 0.
344+
345+ needs_check
346+ A metadata operation has failed, resulting in the needs_check
347+ flag being set in the metadata's superblock. The metadata
348+ device must be deactivated and checked/repaired before the
349+ thin-pool can be made fully operational again. '-' indicates
350+ needs_check is not set.
351+
352+ metadata_low_watermark:
353+ Value of metadata low watermark in blocks. The kernel sets this
354+ value internally but userspace needs to know this value to
355+ determine if an event was caused by crossing this threshold.
356+
357+iii) Messages
358+
359+ create_thin <dev id>
360+ Create a new thinly-provisioned device.
361+ <dev id> is an arbitrary unique 24-bit identifier chosen by
362+ the caller.
363+
364+ create_snap <dev id> <origin id>
365+ Create a new snapshot of another thinly-provisioned device.
366+ <dev id> is an arbitrary unique 24-bit identifier chosen by
367+ the caller.
368+ <origin id> is the identifier of the thinly-provisioned device
369+ of which the new device will be a snapshot.
370+
371+ delete <dev id>
372+ Deletes a thin device. Irreversible.
373+
374+ set_transaction_id <current id> <new id>
375+ Userland volume managers, such as LVM, need a way to
376+ synchronise their external metadata with the internal metadata of the
377+ pool target. The thin-pool target offers to store an
378+ arbitrary 64-bit transaction id and return it on the target's
379+ status line. To avoid races you must provide what you think
380+ the current transaction id is when you change it with this
381+ compare-and-swap message.
382+
383+ reserve_metadata_snap
384+ Reserve a copy of the data mapping btree for use by userland.
385+ This allows userland to inspect the mappings as they were when
386+ this message was executed. Use the pool's status command to
387+ get the root block associated with the metadata snapshot.
388+
389+ release_metadata_snap
390+ Release a previously reserved copy of the data mapping btree.
391+
392+'thin' target
393+-------------
394+
395+i) Constructor
396+
397+ ::
398+
399+ thin <pool dev> <dev id> [<external origin dev>]
400+
401+ pool dev:
402+ the thin-pool device, e.g. /dev/mapper/my_pool or 253:0
403+
404+ dev id:
405+ the internal device identifier of the device to be
406+ activated.
407+
408+ external origin dev:
409+ an optional block device outside the pool to be treated as a
410+ read-only snapshot origin: reads to unprovisioned areas of the
411+ thin target will be mapped to this device.
412+
413+The pool doesn't store any size against the thin devices. If you
414+load a thin target that is smaller than you've been using previously,
415+then you'll have no access to blocks mapped beyond the end. If you
416+load a target that is bigger than before, then extra blocks will be
417+provisioned as and when needed.
418+
419+ii) Status
420+
421+ <nr mapped sectors> <highest mapped sector>
422+ If the pool has encountered device errors and failed, the status
423+ will just contain the string 'Fail'. The userspace recovery
424+ tools should then be used.
425+
426+ In the case where <nr mapped sectors> is 0, there is no highest
427+ mapped sector and the value of <highest mapped sector> is unspecified.
Documentation/admin-guide/device-mapper/unstriped.rst+135−0
@@ -0,0 +1,135 @@
1+================================
2+Device-mapper "unstriped" target
3+================================
4+
5+Introduction
6+============
7+
8+The device-mapper "unstriped" target provides a transparent mechanism to
9+unstripe a device-mapper "striped" target to access the underlying disks
10+without having to touch the true backing block-device. It can also be
11+used to unstripe a hardware RAID-0 to access backing disks.
12+
13+Parameters:
14+<number of stripes> <chunk size> <stripe #> <dev_path> <offset>
15+
16+<number of stripes>
17+ The number of stripes in the RAID 0.
18+
19+<chunk size>
20+ The amount of 512B sectors in the chunk striping.
21+
22+<dev_path>
23+ The block device you wish to unstripe.
24+
25+<stripe #>
26+ The stripe number within the device that corresponds to physical
27+ drive you wish to unstripe. This must be 0 indexed.
28+
29+
30+Why use this module?
31+====================
32+
33+An example of undoing an existing dm-stripe
34+-------------------------------------------
35+
36+This small bash script will setup 4 loop devices and use the existing
37+striped target to combine the 4 devices into one. It then will use
38+the unstriped target ontop of the striped device to access the
39+individual backing loop devices. We write data to the newly exposed
40+unstriped devices and verify the data written matches the correct
41+underlying device on the striped array::
42+
43+ #!/bin/bash
44+
45+ MEMBER_SIZE=$((128 * 1024 * 1024))
46+ NUM=4
47+ SEQ_END=$((${NUM}-1))
48+ CHUNK=256
49+ BS=4096
50+
51+ RAID_SIZE=$((${MEMBER_SIZE}*${NUM}/512))
52+ DM_PARMS="0 ${RAID_SIZE} striped ${NUM} ${CHUNK}"
53+ COUNT=$((${MEMBER_SIZE} / ${BS}))
54+
55+ for i in $(seq 0 ${SEQ_END}); do
56+ dd if=/dev/zero of=member-${i} bs=${MEMBER_SIZE} count=1 oflag=direct
57+ losetup /dev/loop${i} member-${i}
58+ DM_PARMS+=" /dev/loop${i} 0"
59+ done
60+
61+ echo $DM_PARMS | dmsetup create raid0
62+ for i in $(seq 0 ${SEQ_END}); do
63+ echo "0 1 unstriped ${NUM} ${CHUNK} ${i} /dev/mapper/raid0 0" | dmsetup create set-${i}
64+ done;
65+
66+ for i in $(seq 0 ${SEQ_END}); do
67+ dd if=/dev/urandom of=/dev/mapper/set-${i} bs=${BS} count=${COUNT} oflag=direct
68+ diff /dev/mapper/set-${i} member-${i}
69+ done;
70+
71+ for i in $(seq 0 ${SEQ_END}); do
72+ dmsetup remove set-${i}
73+ done
74+
75+ dmsetup remove raid0
76+
77+ for i in $(seq 0 ${SEQ_END}); do
78+ losetup -d /dev/loop${i}
79+ rm -f member-${i}
80+ done
81+
82+Another example
83+---------------
84+
85+Intel NVMe drives contain two cores on the physical device.
86+Each core of the drive has segregated access to its LBA range.
87+The current LBA model has a RAID 0 128k chunk on each core, resulting
88+in a 256k stripe across the two cores::
89+
90+ Core 0: Core 1:
91+ __________ __________
92+ | LBA 512| | LBA 768|
93+ | LBA 0 | | LBA 256|
94+ ---------- ----------
95+
96+The purpose of this unstriping is to provide better QoS in noisy
97+neighbor environments. When two partitions are created on the
98+aggregate drive without this unstriping, reads on one partition
99+can affect writes on another partition. This is because the partitions
100+are striped across the two cores. When we unstripe this hardware RAID 0
101+and make partitions on each new exposed device the two partitions are now
102+physically separated.
103+
104+With the dm-unstriped target we're able to segregate an fio script that
105+has read and write jobs that are independent of each other. Compared to
106+when we run the test on a combined drive with partitions, we were able
107+to get a 92% reduction in read latency using this device mapper target.
108+
109+
110+Example dmsetup usage
111+=====================
112+
113+unstriped ontop of Intel NVMe device that has 2 cores
114+-----------------------------------------------------
115+
116+::
117+
118+ dmsetup create nvmset0 --table '0 512 unstriped 2 256 0 /dev/nvme0n1 0'
119+ dmsetup create nvmset1 --table '0 512 unstriped 2 256 1 /dev/nvme0n1 0'
120+
121+There will now be two devices that expose Intel NVMe core 0 and 1
122+respectively::
123+
124+ /dev/mapper/nvmset0
125+ /dev/mapper/nvmset1
126+
127+unstriped ontop of striped with 4 drives using 128K chunk size
128+--------------------------------------------------------------
129+
130+::
131+
132+ dmsetup create raid_disk0 --table '0 512 unstriped 4 256 0 /dev/mapper/striped 0'
133+ dmsetup create raid_disk1 --table '0 512 unstriped 4 256 1 /dev/mapper/striped 0'
134+ dmsetup create raid_disk2 --table '0 512 unstriped 4 256 2 /dev/mapper/striped 0'
135+ dmsetup create raid_disk3 --table '0 512 unstriped 4 256 3 /dev/mapper/striped 0'
Documentation/admin-guide/device-mapper/verity.rst+229−0
@@ -0,0 +1,229 @@
1+=========
2+dm-verity
3+=========
4+
5+Device-Mapper's "verity" target provides transparent integrity checking of
6+block devices using a cryptographic digest provided by the kernel crypto API.
7+This target is read-only.
8+
9+Construction Parameters
10+=======================
11+
12+::
13+
14+ <version> <dev> <hash_dev>
15+ <data_block_size> <hash_block_size>
16+ <num_data_blocks> <hash_start_block>
17+ <algorithm> <digest> <salt>
18+ [<#opt_params> <opt_params>]
19+
20+<version>
21+ This is the type of the on-disk hash format.
22+
23+ 0 is the original format used in the Chromium OS.
24+ The salt is appended when hashing, digests are stored continuously and
25+ the rest of the block is padded with zeroes.
26+
27+ 1 is the current format that should be used for new devices.
28+ The salt is prepended when hashing and each digest is
29+ padded with zeroes to the power of two.
30+
31+<dev>
32+ This is the device containing data, the integrity of which needs to be
33+ checked. It may be specified as a path, like /dev/sdaX, or a device number,
34+ <major>:<minor>.
35+
36+<hash_dev>
37+ This is the device that supplies the hash tree data. It may be
38+ specified similarly to the device path and may be the same device. If the
39+ same device is used, the hash_start should be outside the configured
40+ dm-verity device.
41+
42+<data_block_size>
43+ The block size on a data device in bytes.
44+ Each block corresponds to one digest on the hash device.
45+
46+<hash_block_size>
47+ The size of a hash block in bytes.
48+
49+<num_data_blocks>
50+ The number of data blocks on the data device. Additional blocks are
51+ inaccessible. You can place hashes to the same partition as data, in this
52+ case hashes are placed after <num_data_blocks>.
53+
54+<hash_start_block>
55+ This is the offset, in <hash_block_size>-blocks, from the start of hash_dev
56+ to the root block of the hash tree.
57+
58+<algorithm>
59+ The cryptographic hash algorithm used for this device. This should
60+ be the name of the algorithm, like "sha1".
61+
62+<digest>
63+ The hexadecimal encoding of the cryptographic hash of the root hash block
64+ and the salt. This hash should be trusted as there is no other authenticity
65+ beyond this point.
66+
67+<salt>
68+ The hexadecimal encoding of the salt value.
69+
70+<#opt_params>
71+ Number of optional parameters. If there are no optional parameters,
72+ the optional paramaters section can be skipped or #opt_params can be zero.
73+ Otherwise #opt_params is the number of following arguments.
74+
75+ Example of optional parameters section:
76+ 1 ignore_corruption
77+
78+ignore_corruption
79+ Log corrupted blocks, but allow read operations to proceed normally.
80+
81+restart_on_corruption
82+ Restart the system when a corrupted block is discovered. This option is
83+ not compatible with ignore_corruption and requires user space support to
84+ avoid restart loops.
85+
86+ignore_zero_blocks
87+ Do not verify blocks that are expected to contain zeroes and always return
88+ zeroes instead. This may be useful if the partition contains unused blocks
89+ that are not guaranteed to contain zeroes.
90+
91+use_fec_from_device <fec_dev>
92+ Use forward error correction (FEC) to recover from corruption if hash
93+ verification fails. Use encoding data from the specified device. This
94+ may be the same device where data and hash blocks reside, in which case
95+ fec_start must be outside data and hash areas.
96+
97+ If the encoding data covers additional metadata, it must be accessible
98+ on the hash device after the hash blocks.
99+
100+ Note: block sizes for data and hash devices must match. Also, if the
101+ verity <dev> is encrypted the <fec_dev> should be too.
102+
103+fec_roots <num>
104+ Number of generator roots. This equals to the number of parity bytes in
105+ the encoding data. For example, in RS(M, N) encoding, the number of roots
106+ is M-N.
107+
108+fec_blocks <num>
109+ The number of encoding data blocks on the FEC device. The block size for
110+ the FEC device is <data_block_size>.
111+
112+fec_start <offset>
113+ This is the offset, in <data_block_size> blocks, from the start of the
114+ FEC device to the beginning of the encoding data.
115+
116+check_at_most_once
117+ Verify data blocks only the first time they are read from the data device,
118+ rather than every time. This reduces the overhead of dm-verity so that it
119+ can be used on systems that are memory and/or CPU constrained. However, it
120+ provides a reduced level of security because only offline tampering of the
121+ data device's content will be detected, not online tampering.
122+
123+ Hash blocks are still verified each time they are read from the hash device,
124+ since verification of hash blocks is less performance critical than data
125+ blocks, and a hash block will not be verified any more after all the data
126+ blocks it covers have been verified anyway.
127+
128+Theory of operation
129+===================
130+
131+dm-verity is meant to be set up as part of a verified boot path. This
132+may be anything ranging from a boot using tboot or trustedgrub to just
133+booting from a known-good device (like a USB drive or CD).
134+
135+When a dm-verity device is configured, it is expected that the caller
136+has been authenticated in some way (cryptographic signatures, etc).
137+After instantiation, all hashes will be verified on-demand during
138+disk access. If they cannot be verified up to the root node of the
139+tree, the root hash, then the I/O will fail. This should detect
140+tampering with any data on the device and the hash data.
141+
142+Cryptographic hashes are used to assert the integrity of the device on a
143+per-block basis. This allows for a lightweight hash computation on first read
144+into the page cache. Block hashes are stored linearly, aligned to the nearest
145+block size.
146+
147+If forward error correction (FEC) support is enabled any recovery of
148+corrupted data will be verified using the cryptographic hash of the
149+corresponding data. This is why combining error correction with
150+integrity checking is essential.
151+
152+Hash Tree
153+---------
154+
155+Each node in the tree is a cryptographic hash. If it is a leaf node, the hash
156+of some data block on disk is calculated. If it is an intermediary node,
157+the hash of a number of child nodes is calculated.
158+
159+Each entry in the tree is a collection of neighboring nodes that fit in one
160+block. The number is determined based on block_size and the size of the
161+selected cryptographic digest algorithm. The hashes are linearly-ordered in
162+this entry and any unaligned trailing space is ignored but included when
163+calculating the parent node.
164+
165+The tree looks something like:
166+
167+ alg = sha256, num_blocks = 32768, block_size = 4096
168+
169+::
170+
171+ [ root ]
172+ / . . . \
173+ [entry_0] [entry_1]
174+ / . . . \ . . . \
175+ [entry_0_0] . . . [entry_0_127] . . . . [entry_1_127]
176+ / ... \ / . . . \ / \
177+ blk_0 ... blk_127 blk_16256 blk_16383 blk_32640 . . . blk_32767
178+
179+
180+On-disk format
181+==============
182+
183+The verity kernel code does not read the verity metadata on-disk header.
184+It only reads the hash blocks which directly follow the header.
185+It is expected that a user-space tool will verify the integrity of the
186+verity header.
187+
188+Alternatively, the header can be omitted and the dmsetup parameters can
189+be passed via the kernel command-line in a rooted chain of trust where
190+the command-line is verified.
191+
192+Directly following the header (and with sector number padded to the next hash
193+block boundary) are the hash blocks which are stored a depth at a time
194+(starting from the root), sorted in order of increasing index.
195+
196+The full specification of kernel parameters and on-disk metadata format
197+is available at the cryptsetup project's wiki page
198+
199+ https://gitlab.com/cryptsetup/cryptsetup/wikis/DMVerity
200+
201+Status
202+======
203+V (for Valid) is returned if every check performed so far was valid.
204+If any check failed, C (for Corruption) is returned.
205+
206+Example
207+=======
208+Set up a device::
209+
210+ # dmsetup create vroot --readonly --table \
211+ "0 2097152 verity 1 /dev/sda1 /dev/sda2 4096 4096 262144 1 sha256 "\
212+ "4392712ba01368efdf14b05c76f9e4df0d53664630b5d48632ed17a137f39076 "\
213+ "1234000000000000000000000000000000000000000000000000000000000000"
214+
215+A command line tool veritysetup is available to compute or verify
216+the hash tree or activate the kernel device. This is available from
217+the cryptsetup upstream repository https://gitlab.com/cryptsetup/cryptsetup/
218+(as a libcryptsetup extension).
219+
220+Create hash on the device::
221+
222+ # veritysetup format /dev/sda1 /dev/sda2
223+ ...
224+ Root hash: 4392712ba01368efdf14b05c76f9e4df0d53664630b5d48632ed17a137f39076
225+
226+Activate the device::
227+
228+ # veritysetup create vroot /dev/sda1 /dev/sda2 \
229+ 4392712ba01368efdf14b05c76f9e4df0d53664630b5d48632ed17a137f39076
Documentation/admin-guide/device-mapper/writecache.rst+79−0
@@ -0,0 +1,79 @@
1+=================
2+Writecache target
3+=================
4+
5+The writecache target caches writes on persistent memory or on SSD. It
6+doesn't cache reads because reads are supposed to be cached in page cache
7+in normal RAM.
8+
9+When the device is constructed, the first sector should be zeroed or the
10+first sector should contain valid superblock from previous invocation.
11+
12+Constructor parameters:
13+
14+1. type of the cache device - "p" or "s"
15+
16+ - p - persistent memory
17+ - s - SSD
18+2. the underlying device that will be cached
19+3. the cache device
20+4. block size (4096 is recommended; the maximum block size is the page
21+ size)
22+5. the number of optional parameters (the parameters with an argument
23+ count as two)
24+
25+ start_sector n (default: 0)
26+ offset from the start of cache device in 512-byte sectors
27+ high_watermark n (default: 50)
28+ start writeback when the number of used blocks reach this
29+ watermark
30+ low_watermark x (default: 45)
31+ stop writeback when the number of used blocks drops below
32+ this watermark
33+ writeback_jobs n (default: unlimited)
34+ limit the number of blocks that are in flight during
35+ writeback. Setting this value reduces writeback
36+ throughput, but it may improve latency of read requests
37+ autocommit_blocks n (default: 64 for pmem, 65536 for ssd)
38+ when the application writes this amount of blocks without
39+ issuing the FLUSH request, the blocks are automatically
40+ commited
41+ autocommit_time ms (default: 1000)
42+ autocommit time in milliseconds. The data is automatically
43+ commited if this time passes and no FLUSH request is
44+ received
45+ fua (by default on)
46+ applicable only to persistent memory - use the FUA flag
47+ when writing data from persistent memory back to the
48+ underlying device
49+ nofua
50+ applicable only to persistent memory - don't use the FUA
51+ flag when writing back data and send the FLUSH request
52+ afterwards
53+
54+ - some underlying devices perform better with fua, some
55+ with nofua. The user should test it
56+
57+Status:
58+1. error indicator - 0 if there was no error, otherwise error number
59+2. the number of blocks
60+3. the number of free blocks
61+4. the number of blocks under writeback
62+
63+Messages:
64+ flush
65+ flush the cache device. The message returns successfully
66+ if the cache device was flushed without an error
67+ flush_on_suspend
68+ flush the cache device on next suspend. Use this message
69+ when you are going to remove the cache device. The proper
70+ sequence for removing the cache device is:
71+
72+ 1. send the "flush_on_suspend" message
73+ 2. load an inactive table with a linear target that maps
74+ to the underlying device
75+ 3. suspend the device
76+ 4. ask for status and verify that there are no errors
77+ 5. resume the device, so that it will use the linear
78+ target
79+ 6. the cache device is now inactive and it can be deleted
Documentation/admin-guide/device-mapper/zero.rst+37−0
@@ -0,0 +1,37 @@
1+=======
2+dm-zero
3+=======
4+

33 more lines aren’t shown here.

Documentation/admin-guide/devices.txt+2−2

This diff is large: its 11 lines aren’t shown here.

Documentation/admin-guide/efi-stub.rstrenamed from Documentation/efi-stub.txt+0−0

File renamed without changes.

Documentation/admin-guide/gpio/index.rst+17−0

This diff is large: its 18 lines aren’t shown here.

Documentation/admin-guide/gpio/sysfs.rstrenamed from Documentation/gpio/sysfs.rst+0−0

File renamed without changes.

Documentation/admin-guide/highuid.rstrenamed from Documentation/highuid.txt+0−0

File renamed without changes.

Documentation/admin-guide/hw-vuln/index.rst+1−0

This diff is large: its 7 lines aren’t shown here.

Documentation/admin-guide/hw-vuln/l1tf.rst+1−1

This diff is large: its 9 lines aren’t shown here.

Documentation/admin-guide/hw-vuln/spectre.rst+697−0

This diff is large: its 698 lines aren’t shown here.

Documentation/admin-guide/hw_random.rstrenamed from Documentation/hw_random.txt+0−0

File renamed without changes.

Documentation/admin-guide/index.rst+30−0

This diff is large: its 70 lines aren’t shown here.

Documentation/admin-guide/iostats.rst+197−0

This diff is large: its 198 lines aren’t shown here.

Documentation/admin-guide/kdump/gdbmacros.txtrenamed from Documentation/kdump/gdbmacros.txt+0−0

File renamed without changes.

Documentation/admin-guide/kdump/index.rst+20−0

This diff is large: its 21 lines aren’t shown here.

Documentation/admin-guide/kdump/kdump.rst+534−0

This diff is large: its 535 lines aren’t shown here.

Documentation/admin-guide/kdump/vmcoreinfo.rst+488−0

This diff is large: its 489 lines aren’t shown here.

Documentation/admin-guide/kernel-parameters.rst+6−6

This diff is large: its 45 lines aren’t shown here.

Documentation/admin-guide/kernel-parameters.txt+106−77

This diff is large: its 504 lines aren’t shown here.

Documentation/admin-guide/kernel-per-CPU-kthreads.rst+356−0

This diff is large: its 357 lines aren’t shown here.

Documentation/admin-guide/laptops/asus-laptop.rst+271−0

This diff is large: its 272 lines aren’t shown here.

Documentation/admin-guide/laptops/disk-shock-protection.rst+151−0

This diff is large: its 152 lines aren’t shown here.

Documentation/admin-guide/laptops/index.rst+17−0

This diff is large: its 18 lines aren’t shown here.

Documentation/admin-guide/laptops/laptop-mode.rst+781−0

This diff is large: its 782 lines aren’t shown here.

Documentation/admin-guide/laptops/lg-laptop.rstrenamed from Documentation/laptops/lg-laptop.rst+1−0

This diff is large: its 7 lines aren’t shown here.

Documentation/admin-guide/laptops/sony-laptop.rst+174−0

This diff is large: its 175 lines aren’t shown here.

Documentation/admin-guide/laptops/sonypi.rst+158−0

This diff is large: its 159 lines aren’t shown here.

Documentation/admin-guide/laptops/thinkpad-acpi.rst+1562−0

This diff is large: its 1563 lines aren’t shown here.

Documentation/admin-guide/laptops/toshiba_haps.rst+87−0

This diff is large: its 88 lines aren’t shown here.

Documentation/admin-guide/lcd-panel-cgram.rst+27−0

This diff is large: its 28 lines aren’t shown here.

Documentation/admin-guide/ldm.rstrenamed from Documentation/ldm.txt+0−0

File renamed without changes.

Documentation/admin-guide/lockup-watchdogs.rstrenamed from Documentation/lockup-watchdogs.txt+0−0

File renamed without changes.

Documentation/admin-guide/mm/cma_debugfs.rst+25−0

This diff is large: its 26 lines aren’t shown here.

Documentation/admin-guide/mm/index.rst+2−1

This diff is large: its 17 lines aren’t shown here.

Documentation/admin-guide/mm/ksm.rst+1−1

This diff is large: its 9 lines aren’t shown here.

Documentation/admin-guide/mm/numa_memory_policy.rst+1−1

This diff is large: its 9 lines aren’t shown here.

Documentation/admin-guide/mm/numaperf.rst+3−2

This diff is large: its 9 lines aren’t shown here.

Documentation/admin-guide/mm/transhuge.rst+1−1

This diff is large: its 9 lines aren’t shown here.

Documentation/admin-guide/namespaces/compatibility-list.rst+43−0

This diff is large: its 44 lines aren’t shown here.

Documentation/admin-guide/namespaces/index.rst+11−0

This diff is large: its 12 lines aren’t shown here.

Documentation/admin-guide/namespaces/resource-control.rst+18−0

This diff is large: its 19 lines aren’t shown here.

Documentation/admin-guide/numastat.rstrenamed from Documentation/numastat.txt+0−0

File renamed without changes.

Documentation/admin-guide/perf/arm-ccn.rst+61−0

This diff is large: its 62 lines aren’t shown here.

Documentation/admin-guide/perf/arm_dsu_pmu.rst+29−0

This diff is large: its 30 lines aren’t shown here.

Documentation/admin-guide/perf/hisi-pmu.rst+60−0

This diff is large: its 61 lines aren’t shown here.

Documentation/admin-guide/perf/index.rst+16−0

This diff is large: its 17 lines aren’t shown here.

Documentation/admin-guide/perf/qcom_l2_pmu.rst+39−0

This diff is large: its 40 lines aren’t shown here.

Documentation/admin-guide/perf/qcom_l3_pmu.rst+26−0

This diff is large: its 27 lines aren’t shown here.

Documentation/admin-guide/perf/thunderx2-pmu.rst+42−0

This diff is large: its 43 lines aren’t shown here.

Documentation/admin-guide/perf/xgene-pmu.rst+49−0

This diff is large: its 50 lines aren’t shown here.

Documentation/admin-guide/pnp.rstrenamed from Documentation/pnp.txt+0−0

File renamed without changes.

Documentation/admin-guide/rapidio.rstrenamed from Documentation/driver-api/rapidio.rst+0−0

File renamed without changes.

Documentation/admin-guide/ras.rst+1−1

This diff is large: its 9 lines aren’t shown here.

Documentation/admin-guide/rtc.rstrenamed from Documentation/rtc.txt+0−0

File renamed without changes.

Documentation/admin-guide/svga.rstrenamed from Documentation/svga.txt+0−0

File renamed without changes.

Documentation/admin-guide/sysctl/abi.rst+67−0

This diff is large: its 68 lines aren’t shown here.

Documentation/admin-guide/sysctl/fs.rst+384−0

This diff is large: its 385 lines aren’t shown here.

Documentation/admin-guide/sysctl/index.rst+98−0

This diff is large: its 99 lines aren’t shown here.

Documentation/admin-guide/sysctl/kernel.rst+1177−0

This diff is large: its 1178 lines aren’t shown here.

Documentation/admin-guide/sysctl/net.rst+461−0

This diff is large: its 462 lines aren’t shown here.

Documentation/admin-guide/sysctl/sunrpc.rst+25−0

This diff is large: its 26 lines aren’t shown here.

Documentation/admin-guide/sysctl/user.rst+78−0

This diff is large: its 79 lines aren’t shown here.

Documentation/admin-guide/sysctl/vm.rst+964−0

This diff is large: its 965 lines aren’t shown here.

Documentation/admin-guide/video-output.rstrenamed from Documentation/video-output.txt+0−0

File renamed without changes.

Documentation/admin-guide/xfs.rst+466−0

This diff is large: its 467 lines aren’t shown here.

Documentation/aoe/aoe.txt+0−143

This diff is large: its 144 lines aren’t shown here.

Documentation/aoe/todo.txt+0−14

This diff is large: its 15 lines aren’t shown here.

Documentation/arm/Booting+0−218

This diff is large: its 219 lines aren’t shown here.

Documentation/arm/IXP4xx+0−172

This diff is large: its 173 lines aren’t shown here.

Documentation/arm/Interrupts+0−167

This diff is large: its 168 lines aren’t shown here.

Documentation/arm/Marvell/README+0−395

This diff is large: its 396 lines aren’t shown here.

Documentation/arm/Microchip/README+0−169

This diff is large: its 170 lines aren’t shown here.

Documentation/arm/Netwinder+0−78

This diff is large: its 79 lines aren’t shown here.

Documentation/arm/OMAP/DSS+0−362

This diff is large: its 363 lines aren’t shown here.

Documentation/arm/OMAP/README+0−11

This diff is large: its 12 lines aren’t shown here.

Documentation/arm/OMAP/omap_pm+0−154

This diff is large: its 155 lines aren’t shown here.

Documentation/arm/Porting+0−135

This diff is large: its 136 lines aren’t shown here.

Documentation/arm/README+0−204

This diff is large: its 205 lines aren’t shown here.

Documentation/arm/SA1100/ADSBitsy+0−43

This diff is large: its 44 lines aren’t shown here.

Documentation/arm/SA1100/Assabet+0−300

This diff is large: its 301 lines aren’t shown here.

Documentation/arm/SA1100/Brutus+0−66

This diff is large: its 67 lines aren’t shown here.

Documentation/arm/SA1100/CERF+0−29

This diff is large: its 30 lines aren’t shown here.

Documentation/arm/SA1100/FreeBird+0−21

This diff is large: its 22 lines aren’t shown here.

Documentation/arm/SA1100/GraphicsClient+0−98

This diff is large: its 99 lines aren’t shown here.

Documentation/arm/SA1100/GraphicsMaster+0−53

This diff is large: its 54 lines aren’t shown here.

Documentation/arm/SA1100/HUW_WEBPANEL+0−17

This diff is large: its 18 lines aren’t shown here.

Documentation/arm/SA1100/Itsy+0−39

This diff is large: its 40 lines aren’t shown here.

Documentation/arm/SA1100/LART+0−14

This diff is large: its 15 lines aren’t shown here.

Documentation/arm/SA1100/PLEB+0−11

This diff is large: its 12 lines aren’t shown here.

Documentation/arm/SA1100/Pangolin+0−23

This diff is large: its 24 lines aren’t shown here.

Documentation/arm/SA1100/Tifon+0−7

This diff is large: its 8 lines aren’t shown here.

Documentation/arm/SA1100/Yopy+0−2

This diff is large: its 3 lines aren’t shown here.

Documentation/arm/SA1100/empeg+0−2

This diff is large: its 3 lines aren’t shown here.

Documentation/arm/SA1100/nanoEngine+0−11

This diff is large: its 12 lines aren’t shown here.

Documentation/arm/SA1100/serial_UART+0−47

This diff is large: its 48 lines aren’t shown here.

Documentation/arm/SPEAr/overview.txt+0−63

This diff is large: its 64 lines aren’t shown here.

Documentation/arm/Samsung-S3C24XX/CPUfreq.txt+0−75

This diff is large: its 76 lines aren’t shown here.

Documentation/arm/Samsung-S3C24XX/EB2410ITX.txt+0−58

This diff is large: its 59 lines aren’t shown here.

Documentation/arm/Samsung-S3C24XX/GPIO.txt+0−171

This diff is large: its 172 lines aren’t shown here.

Documentation/arm/Samsung-S3C24XX/H1940.txt+0−40

This diff is large: its 41 lines aren’t shown here.

Documentation/arm/Samsung-S3C24XX/NAND.txt+0−30

This diff is large: its 31 lines aren’t shown here.

Documentation/arm/Samsung-S3C24XX/Overview.txt+0−318

This diff is large: its 319 lines aren’t shown here.

Documentation/arm/Samsung-S3C24XX/S3C2412.txt+0−120

This diff is large: its 121 lines aren’t shown here.

Documentation/arm/Samsung-S3C24XX/S3C2413.txt+0−21

This diff is large: its 22 lines aren’t shown here.

Documentation/arm/Samsung-S3C24XX/SMDK2440.txt+0−56

This diff is large: its 57 lines aren’t shown here.

Documentation/arm/Samsung-S3C24XX/Suspend.txt+0−137

This diff is large: its 138 lines aren’t shown here.

Documentation/arm/Samsung-S3C24XX/USB-Host.txt+0−93

This diff is large: its 94 lines aren’t shown here.

Documentation/arm/Samsung/Bootloader-interface.txt+0−68

This diff is large: its 69 lines aren’t shown here.

Documentation/arm/Samsung/GPIO.txt+0−40

This diff is large: its 41 lines aren’t shown here.

Documentation/arm/Samsung/Overview.txt+0−86

This diff is large: its 87 lines aren’t shown here.

Documentation/arm/Setup+0−129

This diff is large: its 130 lines aren’t shown here.

Documentation/arm/VFP/release-notes.txt+0−55

This diff is large: its 56 lines aren’t shown here.

Documentation/arm/arm.rst+214−0

This diff is large: its 215 lines aren’t shown here.

Documentation/arm/booting.rst+237−0

This diff is large: its 238 lines aren’t shown here.

Documentation/arm/cluster-pm-race-avoidance.rst+533−0

This diff is large: its 534 lines aren’t shown here.

Documentation/arm/cluster-pm-race-avoidance.txt+0−498

This diff is large: its 499 lines aren’t shown here.

Documentation/arm/firmware.rst+72−0

This diff is large: its 73 lines aren’t shown here.

Documentation/arm/firmware.txt+0−70

This diff is large: its 71 lines aren’t shown here.

Documentation/arm/index.rst+80−0

This diff is large: its 81 lines aren’t shown here.

Documentation/arm/interrupts.rst+169−0

This diff is large: its 170 lines aren’t shown here.

Documentation/arm/ixp4xx.rst+173−0

This diff is large: its 174 lines aren’t shown here.

Documentation/arm/kernel_mode_neon.rst+124−0

This diff is large: its 125 lines aren’t shown here.

Documentation/arm/kernel_mode_neon.txt+0−121

This diff is large: its 122 lines aren’t shown here.

Documentation/arm/kernel_user_helpers.rst+268−0

This diff is large: its 269 lines aren’t shown here.

Documentation/arm/kernel_user_helpers.txt+0−267

This diff is large: its 268 lines aren’t shown here.

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

This diff is large: its 56 lines aren’t shown here.

Documentation/arm/keystone/knav-qmss.rst+60−0

This diff is large: its 61 lines aren’t shown here.

Documentation/arm/keystone/knav-qmss.txt+0−56

This diff is large: its 57 lines aren’t shown here.

Documentation/arm/keystone/overview.rst+74−0

This diff is large: its 75 lines aren’t shown here.

Documentation/arm/marvel.rst+488−0

This diff is large: its 489 lines aren’t shown here.

Documentation/arm/mem_alignment+0−58

This diff is large: its 59 lines aren’t shown here.

Documentation/arm/mem_alignment.rst+63−0

This diff is large: its 64 lines aren’t shown here.

Documentation/arm/memory.rst+93−0

This diff is large: its 94 lines aren’t shown here.

Documentation/arm/memory.txt+0−88

This diff is large: its 89 lines aren’t shown here.

Documentation/arm/microchip.rst+204−0

This diff is large: its 205 lines aren’t shown here.

Documentation/arm/netwinder.rst+85−0

This diff is large: its 86 lines aren’t shown here.

Documentation/arm/nwfpe/NOTES+0−29

This diff is large: its 30 lines aren’t shown here.

Documentation/arm/nwfpe/README+0−70

This diff is large: its 71 lines aren’t shown here.

Documentation/arm/nwfpe/README.FPE+0−156

This diff is large: its 157 lines aren’t shown here.

Documentation/arm/nwfpe/TODO+0−67

This diff is large: its 68 lines aren’t shown here.

Documentation/arm/nwfpe/index.rst+13−0

This diff is large: its 14 lines aren’t shown here.

Documentation/arm/nwfpe/netwinder-fpe.rst+162−0

This diff is large: its 163 lines aren’t shown here.

Documentation/arm/nwfpe/notes.rst+32−0

This diff is large: its 33 lines aren’t shown here.

Documentation/arm/nwfpe/nwfpe.rst+74−0

This diff is large: its 75 lines aren’t shown here.

Documentation/arm/nwfpe/todo.rst+72−0

This diff is large: its 73 lines aren’t shown here.

Documentation/arm/omap/dss.rst+372−0

This diff is large: its 373 lines aren’t shown here.

Documentation/arm/omap/index.rst+12−0

This diff is large: its 13 lines aren’t shown here.

Documentation/arm/omap/omap.rst+18−0

This diff is large: its 19 lines aren’t shown here.

Documentation/arm/omap/omap_pm.rst+165−0

This diff is large: its 166 lines aren’t shown here.

Documentation/arm/porting.rst+137−0

This diff is large: its 138 lines aren’t shown here.

Documentation/arm/pxa/mfp.rst+288−0

This diff is large: its 289 lines aren’t shown here.

Documentation/arm/pxa/mfp.txt+0−286

This diff is large: its 287 lines aren’t shown here.

Documentation/arm/sa1100/adsbitsy.rst+51−0

This diff is large: its 52 lines aren’t shown here.

Documentation/arm/sa1100/assabet.rst+301−0

This diff is large: its 302 lines aren’t shown here.

Documentation/arm/sa1100/brutus.rst+69−0

This diff is large: its 70 lines aren’t shown here.

Documentation/arm/sa1100/cerf.rst+35−0

This diff is large: its 36 lines aren’t shown here.

Documentation/arm/sa1100/freebird.rst+25−0

This diff is large: its 26 lines aren’t shown here.

Documentation/arm/sa1100/graphicsclient.rst+102−0

This diff is large: its 103 lines aren’t shown here.

Documentation/arm/sa1100/graphicsmaster.rst+60−0

This diff is large: its 61 lines aren’t shown here.

Documentation/arm/sa1100/huw_webpanel.rst+21−0

This diff is large: its 22 lines aren’t shown here.

Documentation/arm/sa1100/index.rst+25−0

This diff is large: its 26 lines aren’t shown here.

Documentation/arm/sa1100/itsy.rst+47−0

This diff is large: its 48 lines aren’t shown here.

Documentation/arm/sa1100/lart.rst+15−0

This diff is large: its 16 lines aren’t shown here.

Documentation/arm/sa1100/nanoengine.rst+11−0

This diff is large: its 12 lines aren’t shown here.

Documentation/arm/sa1100/pangolin.rst+29−0

This diff is large: its 30 lines aren’t shown here.

Documentation/arm/sa1100/pleb.rst+13−0

This diff is large: its 14 lines aren’t shown here.

Documentation/arm/sa1100/serial_uart.rst+51−0

This diff is large: its 52 lines aren’t shown here.

Documentation/arm/sa1100/tifon.rst+7−0

This diff is large: its 8 lines aren’t shown here.

Documentation/arm/sa1100/yopy.rst+5−0

This diff is large: its 6 lines aren’t shown here.

Documentation/arm/samsung-s3c24xx/cpufreq.rst+76−0

This diff is large: its 77 lines aren’t shown here.

Documentation/arm/samsung-s3c24xx/eb2410itx.rst+59−0

This diff is large: its 60 lines aren’t shown here.

Documentation/arm/samsung-s3c24xx/gpio.rst+172−0

This diff is large: its 173 lines aren’t shown here.

Documentation/arm/samsung-s3c24xx/h1940.rst+41−0

This diff is large: its 42 lines aren’t shown here.

Documentation/arm/samsung-s3c24xx/index.rst+20−0

This diff is large: its 21 lines aren’t shown here.

Documentation/arm/samsung-s3c24xx/nand.rst+30−0

This diff is large: its 31 lines aren’t shown here.

Documentation/arm/samsung-s3c24xx/overview.rst+319−0

This diff is large: its 320 lines aren’t shown here.

Documentation/arm/samsung-s3c24xx/s3c2412.rst+121−0

This diff is large: its 122 lines aren’t shown here.

Documentation/arm/samsung-s3c24xx/s3c2413.rst+22−0

This diff is large: its 23 lines aren’t shown here.

Documentation/arm/samsung-s3c24xx/smdk2440.rst+57−0

This diff is large: its 58 lines aren’t shown here.

Documentation/arm/samsung-s3c24xx/suspend.rst+137−0

This diff is large: its 138 lines aren’t shown here.

Documentation/arm/samsung-s3c24xx/usb-host.rst+91−0

This diff is large: its 92 lines aren’t shown here.

Documentation/arm/samsung/bootloader-interface.rst+81−0

This diff is large: its 82 lines aren’t shown here.

Documentation/arm/samsung/clksrc-change-registers.awkrenamed from Documentation/arm/Samsung/clksrc-change-registers.awk+0−0

File renamed without changes.

Documentation/arm/samsung/gpio.rst+41−0

This diff is large: its 42 lines aren’t shown here.

Documentation/arm/samsung/index.rst+12−0

This diff is large: its 13 lines aren’t shown here.

Documentation/arm/samsung/overview.rst+89−0

This diff is large: its 90 lines aren’t shown here.

Documentation/arm/setup.rst+108−0

This diff is large: its 109 lines aren’t shown here.

Documentation/arm/sh-mobile/.gitignorerenamed from Documentation/arm/SH-Mobile/.gitignore+0−0

File renamed without changes.

Documentation/arm/spear/overview.rst+66−0

This diff is large: its 67 lines aren’t shown here.

Documentation/arm/sti/overview.rst+36−0

This diff is large: its 37 lines aren’t shown here.

Documentation/arm/sti/overview.txt+0−33

This diff is large: its 34 lines aren’t shown here.

Documentation/arm/sti/stih407-overview.rst+19−0

This diff is large: its 20 lines aren’t shown here.

Documentation/arm/sti/stih407-overview.txt+0−18

This diff is large: its 19 lines aren’t shown here.

Documentation/arm/sti/stih415-overview.rst+14−0

This diff is large: its 15 lines aren’t shown here.

Documentation/arm/sti/stih415-overview.txt+0−12

This diff is large: its 13 lines aren’t shown here.

Documentation/arm/sti/stih416-overview.rst+13−0

This diff is large: its 14 lines aren’t shown here.

Documentation/arm/sti/stih416-overview.txt+0−12

This diff is large: its 13 lines aren’t shown here.

Documentation/arm/sti/stih418-overview.rst+21−0

This diff is large: its 22 lines aren’t shown here.

Documentation/arm/sti/stih418-overview.txt+0−20

This diff is large: its 21 lines aren’t shown here.

Documentation/arm/stm32/stm32f429-overview.rst+2−3

This diff is large: its 13 lines aren’t shown here.

Documentation/arm/stm32/stm32f746-overview.rst+2−3

This diff is large: its 13 lines aren’t shown here.

Documentation/arm/stm32/stm32f769-overview.rst+2−3

This diff is large: its 13 lines aren’t shown here.

Documentation/arm/stm32/stm32h743-overview.rst+2−3

This diff is large: its 13 lines aren’t shown here.

Documentation/arm/stm32/stm32mp157-overview.rst+1−0

This diff is large: its 5 lines aren’t shown here.

Documentation/arm/sunxi.rst+150−0

This diff is large: its 151 lines aren’t shown here.

Documentation/arm/sunxi/README+0−102

This diff is large: its 103 lines aren’t shown here.

Documentation/arm/sunxi/clocks.rst+57−0

This diff is large: its 58 lines aren’t shown here.

Documentation/arm/sunxi/clocks.txt+0−56

This diff is large: its 57 lines aren’t shown here.

Documentation/arm/swp_emulation+0−27

This diff is large: its 28 lines aren’t shown here.

Documentation/arm/swp_emulation.rst+27−0

This diff is large: its 28 lines aren’t shown here.

Documentation/arm/tcm.rst+161−0

This diff is large: its 162 lines aren’t shown here.

Documentation/arm/tcm.txt+0−155

This diff is large: its 156 lines aren’t shown here.

Documentation/arm/uefi.rst+67−0

This diff is large: its 68 lines aren’t shown here.

Documentation/arm/uefi.txt+0−60

This diff is large: its 61 lines aren’t shown here.

Documentation/arm/vfp/release-notes.rst+57−0

This diff is large: its 58 lines aren’t shown here.

Documentation/arm/vlocks.rst+212−0

This diff is large: its 213 lines aren’t shown here.

Documentation/arm/vlocks.txt+0−211

This diff is large: its 212 lines aren’t shown here.

Documentation/arm64/acpi_object_usage.rst+738−0

This diff is large: its 739 lines aren’t shown here.

Documentation/arm64/acpi_object_usage.txt+0−622

This diff is large: its 623 lines aren’t shown here.

Documentation/arm64/arm-acpi.rst+528−0

This diff is large: its 529 lines aren’t shown here.

Documentation/arm64/arm-acpi.txt+0−519

This diff is large: its 520 lines aren’t shown here.

Documentation/arm64/booting.rst+293−0

This diff is large: its 294 lines aren’t shown here.

Documentation/arm64/booting.txt+0−266

This diff is large: its 267 lines aren’t shown here.

Documentation/arm64/cpu-feature-registers.rst+304−0

This diff is large: its 305 lines aren’t shown here.

Documentation/arm64/cpu-feature-registers.txt+0−296

This diff is large: its 297 lines aren’t shown here.

Documentation/arm64/elf_hwcaps.rst+209−0

This diff is large: its 210 lines aren’t shown here.

Documentation/arm64/elf_hwcaps.txt+0−231

This diff is large: its 232 lines aren’t shown here.

Documentation/arm64/hugetlbpage.rst+41−0

This diff is large: its 42 lines aren’t shown here.

Documentation/arm64/hugetlbpage.txt+0−38

This diff is large: its 39 lines aren’t shown here.

Documentation/arm64/index.rst+26−0

This diff is large: its 27 lines aren’t shown here.

Documentation/arm64/legacy_instructions.rst+68−0

This diff is large: its 69 lines aren’t shown here.

Documentation/arm64/legacy_instructions.txt+0−57

This diff is large: its 58 lines aren’t shown here.

Documentation/arm64/memory.rst+98−0

This diff is large: its 99 lines aren’t shown here.

Documentation/arm64/memory.txt+0−97

This diff is large: its 98 lines aren’t shown here.

Documentation/arm64/pointer-authentication.rst+109−0

This diff is large: its 110 lines aren’t shown here.

Documentation/arm64/pointer-authentication.txt+0−107

This diff is large: its 108 lines aren’t shown here.

Documentation/arm64/silicon-errata.rst+133−0

This diff is large: its 134 lines aren’t shown here.

Documentation/arm64/silicon-errata.txt+0−88

This diff is large: its 89 lines aren’t shown here.

Documentation/arm64/sve.rst+545−0

This diff is large: its 546 lines aren’t shown here.

Documentation/arm64/sve.txt+0−541

This diff is large: its 542 lines aren’t shown here.

Documentation/arm64/tagged-pointers.rst+68−0

This diff is large: its 69 lines aren’t shown here.

Documentation/arm64/tagged-pointers.txt+0−66

This diff is large: its 67 lines aren’t shown here.

Documentation/atomic_t.txt+20−6

This diff is large: its 60 lines aren’t shown here.

Documentation/auxdisplay/lcd-panel-cgram.txt+0−24

This diff is large: its 25 lines aren’t shown here.

Documentation/backlight/lp855x-driver.txt+0−66

This diff is large: its 67 lines aren’t shown here.

Documentation/block/bfq-iosched.rst+597−0

This diff is large: its 598 lines aren’t shown here.

Documentation/block/bfq-iosched.txt+0−583

This diff is large: its 584 lines aren’t shown here.

Documentation/block/biodoc.rst+1164−0

This diff is large: its 1165 lines aren’t shown here.

Documentation/block/biodoc.txt+0−1077

This diff is large: its 1078 lines aren’t shown here.

Documentation/block/biovecs.rst+146−0

This diff is large: its 147 lines aren’t shown here.

Documentation/block/biovecs.txt+0−144

This diff is large: its 145 lines aren’t shown here.

Documentation/block/capability.rst+18−0

This diff is large: its 19 lines aren’t shown here.

Documentation/block/capability.txt+0−15

This diff is large: its 16 lines aren’t shown here.

Documentation/block/cmdline-partition.rst+53−0

This diff is large: its 54 lines aren’t shown here.

Documentation/block/cmdline-partition.txt+0−46

This diff is large: its 47 lines aren’t shown here.

Documentation/block/data-integrity.rst+291−0

This diff is large: its 292 lines aren’t shown here.

Documentation/block/data-integrity.txt+0−281

This diff is large: its 282 lines aren’t shown here.

Documentation/block/deadline-iosched.rst+72−0

This diff is large: its 73 lines aren’t shown here.

Documentation/block/deadline-iosched.txt+0−75

This diff is large: its 76 lines aren’t shown here.

Documentation/block/index.rst+25−0

This diff is large: its 26 lines aren’t shown here.

Documentation/block/ioprio.rst+182−0

This diff is large: its 183 lines aren’t shown here.

Documentation/block/ioprio.txt+0−183

This diff is large: its 184 lines aren’t shown here.

Documentation/block/kyber-iosched.rst+15−0

This diff is large: its 16 lines aren’t shown here.

Documentation/block/kyber-iosched.txt+0−14

This diff is large: its 15 lines aren’t shown here.

Documentation/block/null_blk.rst+126−0

This diff is large: its 127 lines aren’t shown here.

Documentation/block/null_blk.txt+0−99

This diff is large: its 100 lines aren’t shown here.

Documentation/block/pr.rst+119−0

This diff is large: its 120 lines aren’t shown here.

Documentation/block/pr.txt+0−119

This diff is large: its 120 lines aren’t shown here.

Documentation/block/queue-sysfs.rst+254−0

This diff is large: its 255 lines aren’t shown here.

Documentation/block/queue-sysfs.txt+0−231

This diff is large: its 232 lines aren’t shown here.

Documentation/block/request.rst+99−0

This diff is large: its 100 lines aren’t shown here.

Documentation/block/request.txt+0−88

This diff is large: its 89 lines aren’t shown here.

Documentation/block/stat.rst+93−0

This diff is large: its 94 lines aren’t shown here.

Documentation/block/stat.txt+0−86

This diff is large: its 87 lines aren’t shown here.

Documentation/block/switching-sched.rst+39−0

This diff is large: its 40 lines aren’t shown here.

Documentation/block/switching-sched.txt+0−35

This diff is large: its 36 lines aren’t shown here.

Documentation/block/writeback_cache_control.rst+86−0

This diff is large: its 87 lines aren’t shown here.

Documentation/block/writeback_cache_control.txt+0−86

This diff is large: its 87 lines aren’t shown here.

Documentation/blockdev/drbd/README.txt+0−16

This diff is large: its 17 lines aren’t shown here.

Documentation/blockdev/drbd/data-structure-v9.txt+0−38

This diff is large: its 39 lines aren’t shown here.

Documentation/blockdev/floppy.txt+0−245

This diff is large: its 246 lines aren’t shown here.

Documentation/blockdev/nbd.txt+0−31

This diff is large: its 32 lines aren’t shown here.

Documentation/blockdev/paride.txt+0−417

This diff is large: its 418 lines aren’t shown here.

Documentation/blockdev/ramdisk.txt+0−174

This diff is large: its 175 lines aren’t shown here.

Documentation/blockdev/zram.txt+0−355

This diff is large: its 356 lines aren’t shown here.

Documentation/bpf/bpf_design_QA.rst+25−5

This diff is large: its 37 lines aren’t shown here.

Documentation/bpf/btf.rst+2−0

This diff is large: its 16 lines aren’t shown here.

Documentation/bpf/index.rst+1−0

This diff is large: its 8 lines aren’t shown here.

Documentation/bpf/prog_cgroup_sockopt.rst+93−0

This diff is large: its 94 lines aren’t shown here.

Documentation/bus-devices/ti-gpmc.txt+0−122

This diff is large: its 123 lines aren’t shown here.

Documentation/cdrom/Makefile+0−21

This diff is large: its 22 lines aren’t shown here.

Documentation/cdrom/cdrom-standard.rst+1063−0

This diff is large: its 1064 lines aren’t shown here.

Documentation/cdrom/cdrom-standard.tex+0−1026

This diff is large: its 1027 lines aren’t shown here.

Documentation/cdrom/ide-cd+0−534

This diff is large: its 535 lines aren’t shown here.

Documentation/cdrom/ide-cd.rst+538−0

This diff is large: its 539 lines aren’t shown here.

Documentation/cdrom/index.rst+19−0

This diff is large: its 20 lines aren’t shown here.

Documentation/cdrom/packet-writing.rst+139−0

This diff is large: its 140 lines aren’t shown here.

Documentation/cdrom/packet-writing.txt+0−132

This diff is large: its 133 lines aren’t shown here.

Documentation/cgroup-v1/blkio-controller.txt+0−293

This diff is large: its 294 lines aren’t shown here.

Documentation/cgroup-v1/cgroups.txt+0−677

This diff is large: its 678 lines aren’t shown here.

Documentation/cgroup-v1/cpuacct.txt+0−49

This diff is large: its 50 lines aren’t shown here.

Documentation/cgroup-v1/cpusets.txt+0−839

This diff is large: its 840 lines aren’t shown here.

Documentation/cgroup-v1/devices.txt+0−116

This diff is large: its 117 lines aren’t shown here.

Documentation/cgroup-v1/freezer-subsystem.txt+0−123

This diff is large: its 124 lines aren’t shown here.

Documentation/cgroup-v1/hugetlb.txt+0−49

This diff is large: its 50 lines aren’t shown here.

Documentation/cgroup-v1/memcg_test.txt+0−280

This diff is large: its 281 lines aren’t shown here.

Documentation/cgroup-v1/memory.txt+0−892

This diff is large: its 893 lines aren’t shown here.

Documentation/cgroup-v1/net_cls.txt+0−39

This diff is large: its 40 lines aren’t shown here.

Documentation/cgroup-v1/net_prio.txt+0−55

This diff is large: its 56 lines aren’t shown here.

Documentation/cgroup-v1/pids.txt+0−88

This diff is large: its 89 lines aren’t shown here.

Documentation/cgroup-v1/rdma.txt+0−109

This diff is large: its 110 lines aren’t shown here.

Documentation/cma/debugfs.txt+0−21

This diff is large: its 22 lines aren’t shown here.

Documentation/conf.py+32−3

This diff is large: its 73 lines aren’t shown here.

Documentation/connector/connector.txt+0−196

This diff is large: its 197 lines aren’t shown here.

Documentation/console/console.txt+0−145

This diff is large: its 146 lines aren’t shown here.

Documentation/core-api/circular-buffers.rst+1−1

This diff is large: its 9 lines aren’t shown here.

Documentation/core-api/conf.py+0−10

This diff is large: its 11 lines aren’t shown here.

Documentation/core-api/gcc-plugins.rstrenamed from Documentation/gcc-plugins.txt+0−0

File renamed without changes.

Documentation/core-api/index.rst+3−0

This diff is large: its 10 lines aren’t shown here.

Documentation/core-api/kernel-api.rst+13−3

This diff is large: its 44 lines aren’t shown here.

Documentation/core-api/printk-formats.rst+1−1

This diff is large: its 9 lines aren’t shown here.

Documentation/core-api/protection-keys.rstrenamed from Documentation/x86/protection-keys.rst+0−0

File renamed without changes.

Documentation/core-api/timekeeping.rst+9−5

This diff is large: its 37 lines aren’t shown here.

Documentation/core-api/xarray.rst+135−135

This diff is large: its 507 lines aren’t shown here.

Documentation/cpu-freq/core.txt+1−1

This diff is large: its 9 lines aren’t shown here.

Documentation/cputopology.txt+0−159

This diff is large: its 160 lines aren’t shown here.

Documentation/crypto/api-samples.rst+77−99

This diff is large: its 189 lines aren’t shown here.

Documentation/crypto/api-skcipher.rst+1−1

This diff is large: its 9 lines aren’t shown here.

Documentation/crypto/architecture.rst+1−3

This diff is large: its 11 lines aren’t shown here.

Documentation/crypto/conf.py+0−10

This diff is large: its 11 lines aren’t shown here.

Documentation/crypto/crypto_engine.rst+73−38

This diff is large: its 124 lines aren’t shown here.

Documentation/dev-tools/conf.py+0−10

This diff is large: its 11 lines aren’t shown here.

Documentation/dev-tools/kmemleak.rst+44−4

This diff is large: its 75 lines aren’t shown here.

Documentation/dev-tools/sparse.rst+0−5

This diff is large: its 12 lines aren’t shown here.

Documentation/device-mapper/cache-policies.txt+0−121

This diff is large: its 122 lines aren’t shown here.

Documentation/device-mapper/cache.txt+0−311

This diff is large: its 312 lines aren’t shown here.

Documentation/device-mapper/delay.txt+0−28

This diff is large: its 29 lines aren’t shown here.

Documentation/device-mapper/dm-crypt.txt+0−162

This diff is large: its 163 lines aren’t shown here.

Documentation/device-mapper/dm-flakey.txt+0−57

This diff is large: its 58 lines aren’t shown here.

Documentation/device-mapper/dm-init.txt+0−114

This diff is large: its 115 lines aren’t shown here.

Documentation/device-mapper/dm-integrity.txt+0−233

This diff is large: its 234 lines aren’t shown here.

Documentation/device-mapper/dm-io.txt+0−75

This diff is large: its 76 lines aren’t shown here.

Documentation/device-mapper/dm-log.txt+0−54

This diff is large: its 55 lines aren’t shown here.

Documentation/device-mapper/dm-queue-length.txt+0−39

This diff is large: its 40 lines aren’t shown here.

Documentation/device-mapper/dm-raid.txt+0−354

This diff is large: its 355 lines aren’t shown here.

Documentation/device-mapper/dm-service-time.txt+0−91

This diff is large: its 92 lines aren’t shown here.

Documentation/device-mapper/dm-uevent.txt+0−97

This diff is large: its 98 lines aren’t shown here.

Documentation/device-mapper/dm-zoned.txt+0−144

This diff is large: its 145 lines aren’t shown here.

Documentation/device-mapper/era.txt+0−108

This diff is large: its 109 lines aren’t shown here.

Documentation/device-mapper/kcopyd.txt+0−47

This diff is large: its 48 lines aren’t shown here.

Documentation/device-mapper/linear.txt+0−61

This diff is large: its 62 lines aren’t shown here.

Documentation/device-mapper/log-writes.txt+0−140

This diff is large: its 141 lines aren’t shown here.

Documentation/device-mapper/persistent-data.txt+0−84

This diff is large: its 85 lines aren’t shown here.

Documentation/device-mapper/snapshot.txt+0−176

This diff is large: its 177 lines aren’t shown here.

Documentation/device-mapper/statistics.txt+0−223

This diff is large: its 224 lines aren’t shown here.

Documentation/device-mapper/striped.txt+0−57

This diff is large: its 58 lines aren’t shown here.

Documentation/device-mapper/switch.txt+0−138

This diff is large: its 139 lines aren’t shown here.

Documentation/device-mapper/thin-provisioning.txt+0−411

This diff is large: its 412 lines aren’t shown here.

Documentation/device-mapper/unstriped.txt+0−124

This diff is large: its 125 lines aren’t shown here.

Documentation/device-mapper/verity.txt+0−219

This diff is large: its 220 lines aren’t shown here.

Documentation/device-mapper/writecache.txt+0−70

This diff is large: its 71 lines aren’t shown here.

Documentation/device-mapper/zero.txt+0−37

This diff is large: its 38 lines aren’t shown here.

Documentation/devicetree/bindings/Makefile+1−1

This diff is large: its 9 lines aren’t shown here.

Documentation/devicetree/bindings/arm/al,alpine.txt+0−16

This diff is large: its 17 lines aren’t shown here.

Documentation/devicetree/bindings/arm/al,alpine.yaml+21−0

This diff is large: its 22 lines aren’t shown here.

Documentation/devicetree/bindings/arm/amlogic.txt+0−142

This diff is large: its 143 lines aren’t shown here.

Documentation/devicetree/bindings/arm/amlogic.yaml+144−0

This diff is large: its 145 lines aren’t shown here.

Documentation/devicetree/bindings/arm/amlogic/amlogic,meson-gx-ao-secure.txt+28−0

This diff is large: its 29 lines aren’t shown here.

Documentation/devicetree/bindings/arm/arm,scmi.txt+1−1

This diff is large: its 9 lines aren’t shown here.

Documentation/devicetree/bindings/arm/arm-boards+1−1

This diff is large: its 9 lines aren’t shown here.

Documentation/devicetree/bindings/arm/atmel-at91.txt+0−73

This diff is large: its 74 lines aren’t shown here.

Documentation/devicetree/bindings/arm/atmel-at91.yaml+134−0

This diff is large: its 135 lines aren’t shown here.

Documentation/devicetree/bindings/arm/axxia.txt+0−12

This diff is large: its 13 lines aren’t shown here.

Documentation/devicetree/bindings/arm/axxia.yaml+19−0

This diff is large: its 20 lines aren’t shown here.

Documentation/devicetree/bindings/arm/coresight-cpu-debug.txt+2−2

This diff is large: its 11 lines aren’t shown here.

Documentation/devicetree/bindings/arm/coresight.txt+5−3

This diff is large: its 22 lines aren’t shown here.

Documentation/devicetree/bindings/arm/cpus.yaml+224−263

This diff is large: its 506 lines aren’t shown here.

Documentation/devicetree/bindings/arm/digicolor.txt+0−6

This diff is large: its 7 lines aren’t shown here.

Documentation/devicetree/bindings/arm/digicolor.yaml+16−0

This diff is large: its 17 lines aren’t shown here.

Documentation/devicetree/bindings/arm/emtrion.txt+0−12

This diff is large: its 13 lines aren’t shown here.

Documentation/devicetree/bindings/arm/freescale/fsl,scu.txt+37−0

This diff is large: its 58 lines aren’t shown here.

Documentation/devicetree/bindings/arm/fsl.yaml+44−0

This diff is large: its 92 lines aren’t shown here.

Documentation/devicetree/bindings/arm/idle-states.txt+11−4

This diff is large: its 33 lines aren’t shown here.

Documentation/devicetree/bindings/arm/mediatek.txt+0−89

This diff is large: its 90 lines aren’t shown here.

Documentation/devicetree/bindings/arm/mediatek.yaml+91−0

This diff is large: its 92 lines aren’t shown here.

Documentation/devicetree/bindings/arm/mediatek/mediatek,audsys.txt+1−0

This diff is large: its 8 lines aren’t shown here.

Documentation/devicetree/bindings/arm/mediatek/mediatek,sgmiisys.txt+2−0

This diff is large: its 9 lines aren’t shown here.

Documentation/devicetree/bindings/arm/moxart.txt+0−12

This diff is large: its 13 lines aren’t shown here.

Documentation/devicetree/bindings/arm/moxart.yaml+19−0

This diff is large: its 20 lines aren’t shown here.

Documentation/devicetree/bindings/arm/nxp/lpc32xx.txt+0−8

This diff is large: its 9 lines aren’t shown here.

Documentation/devicetree/bindings/arm/nxp/lpc32xx.yaml+25−0

This diff is large: its 26 lines aren’t shown here.

Documentation/devicetree/bindings/arm/omap/omap.txt+3−0

This diff is large: its 10 lines aren’t shown here.

Documentation/devicetree/bindings/arm/psci.txt+0−111

This diff is large: its 112 lines aren’t shown here.

Documentation/devicetree/bindings/arm/psci.yaml+163−0

This diff is large: its 164 lines aren’t shown here.

Documentation/devicetree/bindings/arm/qcom.yaml+14−0

This diff is large: its 28 lines aren’t shown here.

Documentation/devicetree/bindings/arm/rda.txt+0−17

This diff is large: its 18 lines aren’t shown here.

Documentation/devicetree/bindings/arm/rda.yaml+20−0

This diff is large: its 21 lines aren’t shown here.

Documentation/devicetree/bindings/arm/renesas.yaml+9−1

This diff is large: its 24 lines aren’t shown here.

Documentation/devicetree/bindings/arm/rockchip.yaml+13−0

This diff is large: its 20 lines aren’t shown here.

Documentation/devicetree/bindings/arm/socionext/milbeaut.yaml+1−1

This diff is large: its 9 lines aren’t shown here.

Documentation/devicetree/bindings/arm/stm32/mlahb.txt+37−0

This diff is large: its 38 lines aren’t shown here.

Documentation/devicetree/bindings/arm/stm32/stm32.txt+0−10

This diff is large: its 11 lines aren’t shown here.

Documentation/devicetree/bindings/arm/stm32/stm32.yaml+31−0

This diff is large: its 32 lines aren’t shown here.

Documentation/devicetree/bindings/arm/sunxi.yaml+1−1

This diff is large: its 9 lines aren’t shown here.

Documentation/devicetree/bindings/arm/ti/k3.txt+3−0

This diff is large: its 10 lines aren’t shown here.

Documentation/devicetree/bindings/arm/ti/ti,davinci.yaml+1−1

This diff is large: its 9 lines aren’t shown here.

Documentation/devicetree/bindings/arm/xen.txt+1−1

This diff is large: its 9 lines aren’t shown here.

Documentation/devicetree/bindings/bus/allwinner,sun8i-a23-rsb.yaml+80−0

This diff is large: its 81 lines aren’t shown here.

Documentation/devicetree/bindings/bus/sunxi-rsb.txt+0−47

This diff is large: its 48 lines aren’t shown here.

Documentation/devicetree/bindings/clock/allwinner,sun4i-a10-ccu.yaml+141−0

This diff is large: its 142 lines aren’t shown here.

Documentation/devicetree/bindings/clock/amlogic,gxbb-clkc.txt+1−0

This diff is large: its 8 lines aren’t shown here.

Documentation/devicetree/bindings/clock/at91-clock.txt+4−3

This diff is large: its 15 lines aren’t shown here.

Documentation/devicetree/bindings/clock/brcm,bcm63xx-clocks.txt+22−0

This diff is large: its 23 lines aren’t shown here.

Documentation/devicetree/bindings/clock/cirrus,lochnagar.txt+1−0

This diff is large: its 8 lines aren’t shown here.

Documentation/devicetree/bindings/clock/mvebu-core-clock.txt+1−0

This diff is large: its 8 lines aren’t shown here.

Documentation/devicetree/bindings/clock/qcom,gpucc.txt+3−1

This diff is large: its 17 lines aren’t shown here.

Documentation/devicetree/bindings/clock/renesas,r9a06g032-sysctrl.txt+5−2

This diff is large: its 26 lines aren’t shown here.

Documentation/devicetree/bindings/clock/silabs,si5341.txt+162−0

This diff is large: its 163 lines aren’t shown here.

Documentation/devicetree/bindings/clock/sunxi-ccu.txt+0−62

This diff is large: its 63 lines aren’t shown here.

Documentation/devicetree/bindings/common-properties.txt+8−9

This diff is large: its 39 lines aren’t shown here.

Documentation/devicetree/bindings/cpufreq/imx-cpufreq-dt.txt+37−0

This diff is large: its 38 lines aren’t shown here.

Documentation/devicetree/bindings/crypto/atmel-crypto.txt+0−13

This diff is large: its 17 lines aren’t shown here.

Documentation/devicetree/bindings/csky/pmu.txt+38−0

This diff is large: its 39 lines aren’t shown here.

Documentation/devicetree/bindings/display/bridge/renesas,dw-hdmi.txt+3−1

This diff is large: its 14 lines aren’t shown here.

Documentation/devicetree/bindings/display/msm/dpu.txt+10−0

This diff is large: its 24 lines aren’t shown here.

Documentation/devicetree/bindings/display/msm/dsi.txt+1−0

This diff is large: its 8 lines aren’t shown here.

Documentation/devicetree/bindings/display/simple-framebuffer.yaml+24−1

This diff is large: its 39 lines aren’t shown here.

Documentation/devicetree/bindings/dma/8250_mtk_dma.txt+0−33

This diff is large: its 34 lines aren’t shown here.

Documentation/devicetree/bindings/dma/arm-pl330.txt+3−0

This diff is large: its 10 lines aren’t shown here.

Documentation/devicetree/bindings/dma/fsl-edma.txt+39−5

This diff is large: its 78 lines aren’t shown here.

Documentation/devicetree/bindings/dma/fsl-qdma.txt+1−0

This diff is large: its 8 lines aren’t shown here.

Documentation/devicetree/bindings/dma/mtk-uart-apdma.txt+54−0

This diff is large: its 55 lines aren’t shown here.

Documentation/devicetree/bindings/dma/sun6i-dma.txt+7−2

This diff is large: its 20 lines aren’t shown here.

Documentation/devicetree/bindings/extcon/extcon-fsa9480.txt+19−0

This diff is large: its 20 lines aren’t shown here.

Documentation/devicetree/bindings/firmware/intel,ixp4xx-network-processing-engine.yaml+1−1

This diff is large: its 9 lines aren’t shown here.

Documentation/devicetree/bindings/gpio/gpio-davinci.txt+18−0

This diff is large: its 29 lines aren’t shown here.

Documentation/devicetree/bindings/gpio/pl061-gpio.txt+0−10

This diff is large: its 11 lines aren’t shown here.

Documentation/devicetree/bindings/gpio/pl061-gpio.yaml+69−0

This diff is large: its 70 lines aren’t shown here.

Documentation/devicetree/bindings/gpu/arm,mali-midgard.txt+1−0

This diff is large: its 8 lines aren’t shown here.

Documentation/devicetree/bindings/gpu/arm,mali-utgard.txt+1−0

This diff is large: its 8 lines aren’t shown here.

Documentation/devicetree/bindings/hwlock/omap-hwspinlock.txt+20−5

This diff is large: its 44 lines aren’t shown here.

Documentation/devicetree/bindings/i2c/allwinner,sun6i-a31-p2wi.yaml+65−0

This diff is large: its 66 lines aren’t shown here.

Documentation/devicetree/bindings/i2c/i2c-mt7621.txt+25−0

This diff is large: its 26 lines aren’t shown here.

Documentation/devicetree/bindings/i2c/i2c-mv64xxx.txt+0−64

This diff is large: its 65 lines aren’t shown here.

Documentation/devicetree/bindings/i2c/i2c-ocores.txt+7−2

This diff is large: its 24 lines aren’t shown here.

Documentation/devicetree/bindings/i2c/i2c-omap.txt+1−0

This diff is large: its 8 lines aren’t shown here.

Documentation/devicetree/bindings/i2c/i2c-stm32.txt+2−0

This diff is large: its 9 lines aren’t shown here.

Documentation/devicetree/bindings/i2c/i2c-sun6i-p2wi.txt+0−41

This diff is large: its 42 lines aren’t shown here.

Documentation/devicetree/bindings/i2c/marvell,mv64xxx-i2c.yaml+124−0

This diff is large: its 125 lines aren’t shown here.

Documentation/devicetree/bindings/i3c/cdns,i3c-master.txt+1−1

This diff is large: its 8 lines aren’t shown here.

Documentation/devicetree/bindings/i3c/i3c.txt+3−1

This diff is large: its 11 lines aren’t shown here.

Documentation/devicetree/bindings/iio/accel/adi,adxl345.yaml+72−0

This diff is large: its 73 lines aren’t shown here.

Documentation/devicetree/bindings/iio/accel/adi,adxl372.yaml+63−0

This diff is large: its 64 lines aren’t shown here.

Documentation/devicetree/bindings/iio/accel/adxl345.txt+0−39

This diff is large: its 40 lines aren’t shown here.

Documentation/devicetree/bindings/iio/accel/adxl372.txt+0−33

This diff is large: its 34 lines aren’t shown here.

Documentation/devicetree/bindings/iio/adc/adi,ad7124.txt+0−75

This diff is large: its 76 lines aren’t shown here.

Documentation/devicetree/bindings/iio/adc/adi,ad7124.yaml+160−0

This diff is large: its 161 lines aren’t shown here.

Documentation/devicetree/bindings/iio/adc/adi,ad7780.txt+0−48

This diff is large: its 49 lines aren’t shown here.

Documentation/devicetree/bindings/iio/adc/adi,ad7780.yaml+87−0

This diff is large: its 88 lines aren’t shown here.

Documentation/devicetree/bindings/iio/adc/avia-hx711.yaml+1−1

This diff is large: its 8 lines aren’t shown here.

Documentation/devicetree/bindings/iio/adc/mt6577_auxadc.txt+2−0

This diff is large: its 11 lines aren’t shown here.

Documentation/devicetree/bindings/iio/adc/st,stm32-adc.txt+1−0

This diff is large: its 8 lines aren’t shown here.

Documentation/devicetree/bindings/iio/chemical/sensirion,sps30.txt+0−12

This diff is large: its 13 lines aren’t shown here.

Documentation/devicetree/bindings/iio/chemical/sensirion,sps30.yaml+39−0

This diff is large: its 40 lines aren’t shown here.

Documentation/devicetree/bindings/iio/frequency/adf4371.yaml+63−0

This diff is large: its 64 lines aren’t shown here.

Documentation/devicetree/bindings/iio/light/isl29018.txt+0−27

This diff is large: its 28 lines aren’t shown here.

Documentation/devicetree/bindings/iio/light/isl29018.yaml+56−0

This diff is large: its 57 lines aren’t shown here.

Documentation/devicetree/bindings/iio/light/tsl2583.txt+0−25

This diff is large: its 26 lines aren’t shown here.

Documentation/devicetree/bindings/iio/light/tsl2583.yaml+46−0

This diff is large: its 47 lines aren’t shown here.

Documentation/devicetree/bindings/iio/light/tsl2772.txt+0−42

This diff is large: its 43 lines aren’t shown here.

Documentation/devicetree/bindings/iio/light/tsl2772.yaml+83−0

This diff is large: its 84 lines aren’t shown here.

Documentation/devicetree/bindings/input/elan_i2c.txt+11−0

This diff is large: its 21 lines aren’t shown here.

Documentation/devicetree/bindings/input/sun4i-lradc-keys.txt+1−0

This diff is large: its 8 lines aren’t shown here.

Documentation/devicetree/bindings/interrupt-controller/amazon,al-fic.txt+27−0

This diff is large: its 28 lines aren’t shown here.

Documentation/devicetree/bindings/interrupt-controller/amlogic,meson-gpio-intc.txt+1−0

This diff is large: its 8 lines aren’t shown here.

Documentation/devicetree/bindings/interrupt-controller/csky,mpintc.txt+16−4

This diff is large: its 44 lines aren’t shown here.

Documentation/devicetree/bindings/interrupt-controller/intel,ixp4xx-interrupt.yaml+1−1

This diff is large: its 9 lines aren’t shown here.

Documentation/devicetree/bindings/interrupt-controller/renesas,rza1-irqc.txt+43−0

This diff is large: its 44 lines aren’t shown here.

Documentation/devicetree/bindings/ipmi/npcm7xx-kcs-bmc.txt+1−1

This diff is large: its 6 lines aren’t shown here.

Documentation/devicetree/bindings/leds/backlight/lm3630a-backlight.yaml+14−7

This diff is large: its 46 lines aren’t shown here.

Documentation/devicetree/bindings/leds/leds-lm36274.txt+85−0

This diff is large: its 86 lines aren’t shown here.

Documentation/devicetree/bindings/leds/leds-lm3697.txt+73−0

This diff is large: its 74 lines aren’t shown here.

Documentation/devicetree/bindings/leds/leds-spi-byte.txt+44−0

This diff is large: its 45 lines aren’t shown here.

Documentation/devicetree/bindings/mailbox/omap-mailbox.txt+50−9

This diff is large: its 116 lines aren’t shown here.

Documentation/devicetree/bindings/media/allegro.txt+43−0

This diff is large: its 44 lines aren’t shown here.

Documentation/devicetree/bindings/media/amlogic,vdec.txt+71−0

This diff is large: its 72 lines aren’t shown here.

Documentation/devicetree/bindings/media/imx7-csi.txt+3−6

This diff is large: its 23 lines aren’t shown here.

Documentation/devicetree/bindings/media/marvell,mmp2-ccic.txt+50−0

This diff is large: its 51 lines aren’t shown here.

Documentation/devicetree/bindings/media/st,stm32-dcmi.txt+1−1

This diff is large: its 9 lines aren’t shown here.

Documentation/devicetree/bindings/media/sun6i-csi.txt+1−0

This diff is large: its 8 lines aren’t shown here.

Documentation/devicetree/bindings/memory-controllers/ingenic,jz4780-nemc.txt+1−0

This diff is large: its 8 lines aren’t shown here.

Documentation/devicetree/bindings/mfd/atmel-usart.txt+15−5

This diff is large: its 39 lines aren’t shown here.

Documentation/devicetree/bindings/mfd/cros-ec.txt+4−1

This diff is large: its 19 lines aren’t shown here.

Documentation/devicetree/bindings/mfd/lp87565.txt+36−0

This diff is large: its 40 lines aren’t shown here.

Documentation/devicetree/bindings/mfd/madera.txt+6−2

This diff is large: its 33 lines aren’t shown here.

Documentation/devicetree/bindings/mfd/rk808.txt+44−0

This diff is large: its 77 lines aren’t shown here.

Documentation/devicetree/bindings/mfd/rohm,bd70528-pmic.txt+102−0

This diff is large: its 103 lines aren’t shown here.

Documentation/devicetree/bindings/mfd/rohm,bd71837-pmic.txt+10−0

This diff is large: its 24 lines aren’t shown here.

Documentation/devicetree/bindings/mfd/ti-lmu.txt+67−21

This diff is large: its 154 lines aren’t shown here.

Documentation/devicetree/bindings/misc/fsl,dpaa2-console.txt+11−0

This diff is large: its 12 lines aren’t shown here.

Documentation/devicetree/bindings/misc/intel,ixp4xx-ahb-queue-manager.yaml+49−0

This diff is large: its 50 lines aren’t shown here.

Documentation/devicetree/bindings/misc/intel,ixp4xx-queue-manager.yaml+0−49

This diff is large: its 50 lines aren’t shown here.

Documentation/devicetree/bindings/misc/olpc,xo1.75-ec.txt+23−0

This diff is large: its 24 lines aren’t shown here.

Documentation/devicetree/bindings/misc/xlnx,sd-fec.txt+58−0

This diff is large: its 59 lines aren’t shown here.

Documentation/devicetree/bindings/mmc/allwinner,sun4i-a10-mmc.yaml+98−0

This diff is large: its 99 lines aren’t shown here.

Documentation/devicetree/bindings/mmc/amlogic,meson-gx.txt+4−0

This diff is large: its 11 lines aren’t shown here.

Documentation/devicetree/bindings/mmc/mmc-controller.yaml+374−0

This diff is large: its 375 lines aren’t shown here.

Documentation/devicetree/bindings/mmc/mmc.txt+1−177

This diff is large: its 179 lines aren’t shown here.

Documentation/devicetree/bindings/mmc/renesas,sdhi.txt+111−0

This diff is large: its 112 lines aren’t shown here.

Documentation/devicetree/bindings/mmc/sdhci-am654.txt+8−1

This diff is large: its 26 lines aren’t shown here.

Documentation/devicetree/bindings/mmc/sdhci-sprd.txt+26−0

This diff is large: its 44 lines aren’t shown here.

Documentation/devicetree/bindings/mmc/sunxi-mmc.txt+0−52

This diff is large: its 53 lines aren’t shown here.

Documentation/devicetree/bindings/mmc/tmio_mmc.txt+0−120

This diff is large: its 121 lines aren’t shown here.

Documentation/devicetree/bindings/mtd/allwinner,sun4i-a10-nand.yaml+1−1

This diff is large: its 11 lines aren’t shown here.

Documentation/devicetree/bindings/mtd/brcm,brcmnand.txt+3−2

This diff is large: its 21 lines aren’t shown here.

Documentation/devicetree/bindings/mtd/cadence-quadspi.txt+5−0

This diff is large: its 19 lines aren’t shown here.

Documentation/devicetree/bindings/mtd/cypress,hyperflash.txt+13−0

This diff is large: its 14 lines aren’t shown here.

Documentation/devicetree/bindings/mtd/nand-controller.yaml+1−0

This diff is large: its 8 lines aren’t shown here.

Documentation/devicetree/bindings/mtd/stm32-quadspi.txt+0−43

This diff is large: its 44 lines aren’t shown here.

Documentation/devicetree/bindings/mtd/ti,am654-hbmc.txt+51−0

This diff is large: its 52 lines aren’t shown here.

Documentation/devicetree/bindings/mux/mmio-mux.txt+0−60

This diff is large: its 61 lines aren’t shown here.

Documentation/devicetree/bindings/mux/reg-mux.txt+129−0

This diff is large: its 130 lines aren’t shown here.

Documentation/devicetree/bindings/net/allwinner,sun4i-a10-emac.yaml+56−0

This diff is large: its 57 lines aren’t shown here.

Documentation/devicetree/bindings/net/allwinner,sun4i-a10-mdio.yaml+70−0

This diff is large: its 71 lines aren’t shown here.

Documentation/devicetree/bindings/net/allwinner,sun4i-emac.txt+0−19

This diff is large: its 20 lines aren’t shown here.

Documentation/devicetree/bindings/net/allwinner,sun4i-mdio.txt+0−27

This diff is large: its 28 lines aren’t shown here.

Documentation/devicetree/bindings/net/allwinner,sun7i-a20-gmac.txt+0−27

This diff is large: its 28 lines aren’t shown here.

Documentation/devicetree/bindings/net/allwinner,sun7i-a20-gmac.yaml+65−0

This diff is large: its 66 lines aren’t shown here.

Documentation/devicetree/bindings/net/allwinner,sun8i-a83t-emac.yaml+321−0

This diff is large: its 322 lines aren’t shown here.

Documentation/devicetree/bindings/net/can/microchip,mcp251x.txt+1−0

This diff is large: its 8 lines aren’t shown here.

Documentation/devicetree/bindings/net/can/rcar_can.txt+4−9

This diff is large: its 34 lines aren’t shown here.

Documentation/devicetree/bindings/net/can/rcar_canfd.txt+10−6

This diff is large: its 35 lines aren’t shown here.

Documentation/devicetree/bindings/net/dsa/ksz.txt+2−0

This diff is large: its 9 lines aren’t shown here.

Documentation/devicetree/bindings/net/dsa/marvell.txt+5−2

This diff is large: its 16 lines aren’t shown here.

Documentation/devicetree/bindings/net/dsa/qca8k.txt+6−0

This diff is large: its 27 lines aren’t shown here.

Documentation/devicetree/bindings/net/dsa/vitesse,vsc73xx.txt+54−4

This diff is large: its 83 lines aren’t shown here.

Documentation/devicetree/bindings/net/dwmac-sun8i.txt+0−201

This diff is large: its 202 lines aren’t shown here.

Documentation/devicetree/bindings/net/ethernet-controller.yaml+206−0

This diff is large: its 207 lines aren’t shown here.

Documentation/devicetree/bindings/net/ethernet-phy.yaml+177−0

This diff is large: its 178 lines aren’t shown here.

Documentation/devicetree/bindings/net/ethernet.txt+1−67

This diff is large: its 69 lines aren’t shown here.

Documentation/devicetree/bindings/net/fixed-link.txt+1−54

This diff is large: its 56 lines aren’t shown here.

Documentation/devicetree/bindings/net/fsl-enetc.txt+3−4

This diff is large: its 21 lines aren’t shown here.

Documentation/devicetree/bindings/net/hisilicon-hip04-net.txt+4−3

This diff is large: its 34 lines aren’t shown here.

Documentation/devicetree/bindings/net/keystone-netcp.txt+44−0

This diff is large: its 62 lines aren’t shown here.

Documentation/devicetree/bindings/net/macb.txt+3−0

This diff is large: its 12 lines aren’t shown here.

Documentation/devicetree/bindings/net/marvell-bluetooth.txt+25−0

This diff is large: its 26 lines aren’t shown here.

Documentation/devicetree/bindings/net/marvell-orion-mdio.txt+1−1

This diff is large: its 9 lines aren’t shown here.

Documentation/devicetree/bindings/net/mdio.txt+1−37

This diff is large: its 39 lines aren’t shown here.

Documentation/devicetree/bindings/net/mdio.yaml+74−0

This diff is large: its 75 lines aren’t shown here.

Documentation/devicetree/bindings/net/mediatek-bluetooth.txt+17−0

This diff is large: its 34 lines aren’t shown here.

Documentation/devicetree/bindings/net/mediatek-net.txt+12−2

This diff is large: its 34 lines aren’t shown here.

Documentation/devicetree/bindings/net/phy.txt+1−79

This diff is large: its 81 lines aren’t shown here.

Documentation/devicetree/bindings/net/qca,ar71xx.txt+45−0

This diff is large: its 46 lines aren’t shown here.

Documentation/devicetree/bindings/net/qualcomm-bluetooth.txt+4−0

This diff is large: its 31 lines aren’t shown here.

Documentation/devicetree/bindings/net/snps,dwmac.yaml+411−0

This diff is large: its 412 lines aren’t shown here.

Documentation/devicetree/bindings/net/socfpga-dwmac.txt+8−2

This diff is large: its 20 lines aren’t shown here.

Documentation/devicetree/bindings/net/stmmac.txt+1−178

This diff is large: its 180 lines aren’t shown here.

Documentation/devicetree/bindings/net/ti,dp83867.txt+12−2

This diff is large: its 28 lines aren’t shown here.

Documentation/devicetree/bindings/net/wiznet,w5x00.txt+50−0

This diff is large: its 51 lines aren’t shown here.

Documentation/devicetree/bindings/net/xilinx_axienet.txt+25−4

This diff is large: its 50 lines aren’t shown here.

Documentation/devicetree/bindings/nvmem/allwinner,sun4i-a10-sid.yaml+51−0

This diff is large: its 52 lines aren’t shown here.

Documentation/devicetree/bindings/nvmem/allwinner,sunxi-sid.txt+0−29

This diff is large: its 30 lines aren’t shown here.

Documentation/devicetree/bindings/nvmem/imx-ocotp.txt+1−0

This diff is large: its 8 lines aren’t shown here.

Documentation/devicetree/bindings/nvmem/nvmem-consumer.yaml+45−0

This diff is large: its 46 lines aren’t shown here.

Documentation/devicetree/bindings/nvmem/nvmem.txt+1−80

This diff is large: its 82 lines aren’t shown here.

Documentation/devicetree/bindings/nvmem/nvmem.yaml+93−0

This diff is large: its 94 lines aren’t shown here.

Documentation/devicetree/bindings/pci/83xx-512x-pci.txt+0−1

This diff is large: its 8 lines aren’t shown here.

Documentation/devicetree/bindings/pci/amlogic,meson-pcie.txt+1−1

This diff is large: its 9 lines aren’t shown here.

Documentation/devicetree/bindings/pci/mobiveil-pcie.txt+2−0

This diff is large: its 11 lines aren’t shown here.

Documentation/devicetree/bindings/pci/nvidia,tegra20-pcie.txt+8−0

This diff is large: its 15 lines aren’t shown here.

Documentation/devicetree/bindings/pci/pci.txt+3−0

This diff is large: its 10 lines aren’t shown here.

Documentation/devicetree/bindings/pci/qcom,pcie.txt+23−2

This diff is large: its 57 lines aren’t shown here.

Documentation/devicetree/bindings/pci/rcar-pci.txt+1−0

This diff is large: its 8 lines aren’t shown here.

Documentation/devicetree/bindings/perf/fsl-imx-ddr.txt+21−0

This diff is large: its 22 lines aren’t shown here.

Documentation/devicetree/bindings/phy/allwinner,sun6i-a31-mipi-dphy.yaml+1−1

This diff is large: its 9 lines aren’t shown here.

Documentation/devicetree/bindings/phy/mixel,mipi-dsi-phy.txt+29−0

This diff is large: its 30 lines aren’t shown here.

Documentation/devicetree/bindings/phy/mxs-usb-phy.txt+2−1

This diff is large: its 17 lines aren’t shown here.

Documentation/devicetree/bindings/phy/nvidia,tegra124-xusb-padctl.txt+12−0

This diff is large: its 19 lines aren’t shown here.

Documentation/devicetree/bindings/phy/phy-bindings.txt+1−1

This diff is large: its 7 lines aren’t shown here.

Documentation/devicetree/bindings/phy/phy-pxa-usb.txt+18−0

This diff is large: its 19 lines aren’t shown here.

Documentation/devicetree/bindings/phy/qcom-pcie2-phy.txt+42−0

This diff is large: its 43 lines aren’t shown here.

Documentation/devicetree/bindings/phy/rcar-gen3-phy-usb2.txt+9−4

This diff is large: its 36 lines aren’t shown here.

Documentation/devicetree/bindings/pinctrl/allwinner,sunxi-pinctrl.txt+2−0

This diff is large: its 9 lines aren’t shown here.

Documentation/devicetree/bindings/pinctrl/aspeed,ast2400-pinctrl.yaml+83−0

This diff is large: its 84 lines aren’t shown here.

Documentation/devicetree/bindings/pinctrl/aspeed,ast2500-pinctrl.yaml+133−0

This diff is large: its 134 lines aren’t shown here.

Documentation/devicetree/bindings/pinctrl/bitmain,bm1880-pinctrl.txt+31−3

This diff is large: its 50 lines aren’t shown here.

Documentation/devicetree/bindings/pinctrl/brcm,bcm2835-gpio.txt+3−0

This diff is large: its 10 lines aren’t shown here.

Documentation/devicetree/bindings/pinctrl/fsl,imx8mm-pinctrl.txt+1−1

This diff is large: its 9 lines aren’t shown here.

Documentation/devicetree/bindings/pinctrl/fsl,imx8mn-pinctrl.txt+39−0

This diff is large: its 40 lines aren’t shown here.

Documentation/devicetree/bindings/pinctrl/marvell,kirkwood-pinctrl.txt+42−2

This diff is large: its 55 lines aren’t shown here.

Documentation/devicetree/bindings/pinctrl/meson,pinctrl.txt+13−3

This diff is large: its 23 lines aren’t shown here.

Documentation/devicetree/bindings/pinctrl/microchip,pic32-pinctrl.txt+1−1

This diff is large: its 9 lines aren’t shown here.

Documentation/devicetree/bindings/pinctrl/nuvoton,npcm7xx-pinctrl.txt+1−1

This diff is large: its 6 lines aren’t shown here.

Documentation/devicetree/bindings/pinctrl/nvidia,tegra194-pinmux.txt+107−0

This diff is large: its 108 lines aren’t shown here.

Documentation/devicetree/bindings/pinctrl/pinctrl-aspeed.txt+0−172

This diff is large: its 173 lines aren’t shown here.

Documentation/devicetree/bindings/pinctrl/pinctrl-bindings.txt+3−0

This diff is large: its 17 lines aren’t shown here.

Documentation/devicetree/bindings/pinctrl/qcom,apq8084-pinctrl.txt+3−3

This diff is large: its 21 lines aren’t shown here.

Documentation/devicetree/bindings/pinctrl/qcom,ipq8074-pinctrl.txt+3−3

This diff is large: its 21 lines aren’t shown here.

Documentation/devicetree/bindings/pinctrl/qcom,mdm9615-pinctrl.txt+3−3

This diff is large: its 21 lines aren’t shown here.

Documentation/devicetree/bindings/pinctrl/qcom,msm8916-pinctrl.txt+3−3

This diff is large: its 21 lines aren’t shown here.

Documentation/devicetree/bindings/pinctrl/qcom,msm8960-pinctrl.txt+3−3

This diff is large: its 21 lines aren’t shown here.

Documentation/devicetree/bindings/pinctrl/qcom,msm8994-pinctrl.txt+3−3

This diff is large: its 21 lines aren’t shown here.

Documentation/devicetree/bindings/pinctrl/qcom,msm8996-pinctrl.txt+3−3

This diff is large: its 21 lines aren’t shown here.

Documentation/devicetree/bindings/pinctrl/qcom,msm8998-pinctrl.txt+13−3

This diff is large: its 45 lines aren’t shown here.

Documentation/devicetree/bindings/pinctrl/qcom,qcs404-pinctrl.txt+3−3

This diff is large: its 21 lines aren’t shown here.

Documentation/devicetree/bindings/pinctrl/qcom,sdm660-pinctrl.txt+3−3

This diff is large: its 21 lines aren’t shown here.

Documentation/devicetree/bindings/pinctrl/qcom,sdm845-pinctrl.txt+4−4

This diff is large: its 30 lines aren’t shown here.

Documentation/devicetree/bindings/pinctrl/qcom,sm8150-pinctrl.txt+190−0

This diff is large: its 191 lines aren’t shown here.

Documentation/devicetree/bindings/pinctrl/st,stm32-pinctrl.txt+0−208

This diff is large: its 209 lines aren’t shown here.

Documentation/devicetree/bindings/pinctrl/st,stm32-pinctrl.yaml+271−0

This diff is large: its 272 lines aren’t shown here.

Documentation/devicetree/bindings/power/qcom,rpmpd.txt+2−0

This diff is large: its 9 lines aren’t shown here.

Documentation/devicetree/bindings/power/reset/nvmem-reboot-mode.txt+26−0

This diff is large: its 27 lines aren’t shown here.

Documentation/devicetree/bindings/power/reset/qcom,pon.txt+1−0

This diff is large: its 8 lines aren’t shown here.

Documentation/devicetree/bindings/property-units.txt+17−17

This diff is large: its 50 lines aren’t shown here.

Documentation/devicetree/bindings/ptp/ptp-qoriq.txt+2−0

This diff is large: its 9 lines aren’t shown here.

Documentation/devicetree/bindings/pwm/allwinner,sun4i-a10-pwm.yaml+57−0

This diff is large: its 58 lines aren’t shown here.

Documentation/devicetree/bindings/pwm/ingenic,jz47xx-pwm.txt+1−4

This diff is large: its 12 lines aren’t shown here.

Documentation/devicetree/bindings/pwm/pwm-sifive.txt+33−0

This diff is large: its 34 lines aren’t shown here.

Documentation/devicetree/bindings/pwm/pwm-stm32-lp.txt+6−3

This diff is large: its 23 lines aren’t shown here.

Documentation/devicetree/bindings/pwm/pwm-stm32.txt+3−0

This diff is large: its 17 lines aren’t shown here.

Documentation/devicetree/bindings/pwm/pwm-sun4i.txt+0−24

This diff is large: its 25 lines aren’t shown here.

Documentation/devicetree/bindings/regulator/arizona-regulator.txt+2−1

This diff is large: its 10 lines aren’t shown here.

Documentation/devicetree/bindings/regulator/fixed-regulator.yaml+4−1

This diff is large: its 15 lines aren’t shown here.

Documentation/devicetree/bindings/regulator/gpio-regulator.txt+0−57

This diff is large: its 58 lines aren’t shown here.

Documentation/devicetree/bindings/regulator/gpio-regulator.yaml+118−0

This diff is large: its 119 lines aren’t shown here.

Documentation/devicetree/bindings/regulator/max8660.txt+0−47

This diff is large: its 48 lines aren’t shown here.

Documentation/devicetree/bindings/regulator/max8660.yaml+77−0

This diff is large: its 78 lines aren’t shown here.

Documentation/devicetree/bindings/regulator/pv88060.txt+1−1

This diff is large: its 6 lines aren’t shown here.

Documentation/devicetree/bindings/regulator/qcom,rpmh-regulator.txt+1−1

This diff is large: its 9 lines aren’t shown here.

Documentation/devicetree/bindings/regulator/qcom,spmi-regulator.txt+22−0

This diff is large: its 48 lines aren’t shown here.

Documentation/devicetree/bindings/regulator/regulator.txt+1−139

This diff is large: its 141 lines aren’t shown here.

Documentation/devicetree/bindings/regulator/regulator.yaml+200−0

This diff is large: its 201 lines aren’t shown here.

Documentation/devicetree/bindings/regulator/slg51000.txt+88−0

This diff is large: its 89 lines aren’t shown here.

Documentation/devicetree/bindings/regulator/st,stm32-booster.txt+18−0

This diff is large: its 19 lines aren’t shown here.

Documentation/devicetree/bindings/remoteproc/qcom,adsp-pil.txt+0−125

This diff is large: its 126 lines aren’t shown here.

Documentation/devicetree/bindings/remoteproc/qcom,hexagon-v56.txt+140−0

This diff is large: its 141 lines aren’t shown here.

Documentation/devicetree/bindings/remoteproc/stm32-rproc.txt+63−0

This diff is large: its 64 lines aren’t shown here.

Documentation/devicetree/bindings/reset/bitmain,bm1880-reset.txt+18−0

This diff is large: its 19 lines aren’t shown here.

Documentation/devicetree/bindings/reset/fsl,imx7-src.txt+1−1

This diff is large: its 8 lines aren’t shown here.

Documentation/devicetree/bindings/riscv/cpus.yaml+149−0

This diff is large: its 150 lines aren’t shown here.

Documentation/devicetree/bindings/riscv/sifive.yaml+25−0

This diff is large: its 26 lines aren’t shown here.

Documentation/devicetree/bindings/rng/brcm,iproc-rng200.txt+1−0

This diff is large: its 8 lines aren’t shown here.

Documentation/devicetree/bindings/rtc/allwinner,sun4i-a10-rtc.yaml+43−0

This diff is large: its 44 lines aren’t shown here.

Documentation/devicetree/bindings/rtc/allwinner,sun6i-a31-rtc.yaml+134−0

This diff is large: its 135 lines aren’t shown here.

Documentation/devicetree/bindings/rtc/rtc.txt+1−72

This diff is large: its 74 lines aren’t shown here.

Documentation/devicetree/bindings/rtc/rtc.yaml+50−0

This diff is large: its 51 lines aren’t shown here.

Documentation/devicetree/bindings/rtc/sun6i-rtc.txt+0−46

This diff is large: its 47 lines aren’t shown here.

Documentation/devicetree/bindings/rtc/sunxi-rtc.txt+0−17

This diff is large: its 18 lines aren’t shown here.

Documentation/devicetree/bindings/rtc/trivial-rtc.yaml+92−0

This diff is large: its 93 lines aren’t shown here.

Documentation/devicetree/bindings/serial/8250.txt+19−0

This diff is large: its 30 lines aren’t shown here.

Documentation/devicetree/bindings/serial/mtk-uart.txt+11−2

This diff is large: its 27 lines aren’t shown here.

Documentation/devicetree/bindings/serial/omap_serial.txt+1−0

This diff is large: its 8 lines aren’t shown here.

Documentation/devicetree/bindings/serial/st,stm32-usart.txt+1−0

This diff is large: its 8 lines aren’t shown here.

Documentation/devicetree/bindings/soc/amlogic/amlogic,canvas.txt+7−3

This diff is large: its 24 lines aren’t shown here.

Documentation/devicetree/bindings/soc/qcom/qcom,aoss-qmp.txt+81−0

This diff is large: its 82 lines aren’t shown here.

Documentation/devicetree/bindings/soc/qcom/qcom,apr.txt+3−3

This diff is large: its 21 lines aren’t shown here.

Documentation/devicetree/bindings/soc/qcom/qcom,glink.txt+5−0

This diff is large: its 12 lines aren’t shown here.

Documentation/devicetree/bindings/sound/allwinner,sun4i-a10-i2s.yaml+132−0

This diff is large: its 133 lines aren’t shown here.

Documentation/devicetree/bindings/sound/allwinner,sun4i-a10-spdif.yaml+120−0

This diff is large: its 121 lines aren’t shown here.

Documentation/devicetree/bindings/sound/amlogic,axg-tdm-formatters.txt+5−1

This diff is large: its 17 lines aren’t shown here.

Documentation/devicetree/bindings/sound/amlogic,g12a-tohdmitx.txt+55−0

This diff is large: its 56 lines aren’t shown here.

Documentation/devicetree/bindings/sound/cs42l73.txt+1−1

This diff is large: its 6 lines aren’t shown here.

Documentation/devicetree/bindings/sound/cs42xx8.txt+6−0

This diff is large: its 18 lines aren’t shown here.

Documentation/devicetree/bindings/sound/davinci-mcasp-audio.txt+3−0

This diff is large: its 10 lines aren’t shown here.

Documentation/devicetree/bindings/sound/madera.txt+67−0

This diff is large: its 68 lines aren’t shown here.

Documentation/devicetree/bindings/sound/max98357a.txt+4−0

This diff is large: its 11 lines aren’t shown here.

Documentation/devicetree/bindings/sound/rt1011.txt+32−0

This diff is large: its 33 lines aren’t shown here.

Documentation/devicetree/bindings/sound/rt1308.txt+17−0

This diff is large: its 18 lines aren’t shown here.

Documentation/devicetree/bindings/sound/st,stm32-i2s.txt+1−1

This diff is large: its 9 lines aren’t shown here.

Documentation/devicetree/bindings/sound/st,stm32-sai.txt+1−1

This diff is large: its 9 lines aren’t shown here.

Documentation/devicetree/bindings/sound/sun4i-i2s.txt+0−45

This diff is large: its 46 lines aren’t shown here.

Documentation/devicetree/bindings/sound/sunxi,sun4i-spdif.txt+0−42

This diff is large: its 43 lines aren’t shown here.

Documentation/devicetree/bindings/spi/allwinner,sun4i-a10-spi.yaml+87−0

This diff is large: its 88 lines aren’t shown here.

Documentation/devicetree/bindings/spi/allwinner,sun6i-a31-spi.yaml+107−0

This diff is large: its 108 lines aren’t shown here.

Documentation/devicetree/bindings/spi/spi-bus.txt+1−111

This diff is large: its 113 lines aren’t shown here.

Documentation/devicetree/bindings/spi/spi-controller.yaml+161−0

This diff is large: its 162 lines aren’t shown here.

Documentation/devicetree/bindings/spi/spi-gpio.txt+0−43

This diff is large: its 44 lines aren’t shown here.

Documentation/devicetree/bindings/spi/spi-gpio.yaml+72−0

This diff is large: its 73 lines aren’t shown here.

Documentation/devicetree/bindings/spi/spi-pl022.yaml+165−0

This diff is large: its 166 lines aren’t shown here.

Documentation/devicetree/bindings/spi/spi-stm32-qspi.txt+4−1

This diff is large: its 13 lines aren’t shown here.

Documentation/devicetree/bindings/spi/spi-sun4i.txt+0−23

This diff is large: its 24 lines aren’t shown here.

Documentation/devicetree/bindings/spi/spi-sun6i.txt+0−44

This diff is large: its 45 lines aren’t shown here.

Documentation/devicetree/bindings/spi/spi-synquacer.txt+27−0

This diff is large: its 28 lines aren’t shown here.

Documentation/devicetree/bindings/spi/spi_pl022.txt+0−70

This diff is large: its 71 lines aren’t shown here.

Documentation/devicetree/bindings/timer/intel,ixp4xx-timer.yaml+1−1

This diff is large: its 9 lines aren’t shown here.

Documentation/devicetree/bindings/timer/nxp,sysctr-timer.txt+25−0

This diff is large: its 26 lines aren’t shown here.

Documentation/devicetree/bindings/timer/renesas,cmt.txt+6−0

This diff is large: its 19 lines aren’t shown here.

Documentation/devicetree/bindings/trivial-devices.yaml+4−0

This diff is large: its 11 lines aren’t shown here.

Documentation/devicetree/bindings/usb/dwc2.txt+3−0

This diff is large: its 15 lines aren’t shown here.

Documentation/devicetree/bindings/usb/dwc3.txt+2−0

This diff is large: its 9 lines aren’t shown here.

Documentation/devicetree/bindings/usb/generic-ehci.yaml+1−2

This diff is large: its 17 lines aren’t shown here.

Documentation/devicetree/bindings/usb/renesas,usb3.txtrenamed from Documentation/devicetree/bindings/usb/renesas_usb3.txt+0−0

File renamed without changes.

Documentation/devicetree/bindings/usb/renesas,usbhs.txt+57−0

This diff is large: its 58 lines aren’t shown here.

Documentation/devicetree/bindings/usb/renesas_usbhs.txt+0−55

This diff is large: its 56 lines aren’t shown here.

Documentation/devicetree/bindings/usb/s3c2410-usb.txt+1−1

This diff is large: its 9 lines aren’t shown here.

Documentation/devicetree/bindings/usb/usb251xb.txt+2−4

This diff is large: its 13 lines aren’t shown here.

Documentation/devicetree/bindings/vendor-prefixes.yaml+80−4

This diff is large: its 306 lines aren’t shown here.

Documentation/devicetree/bindings/virtio/iommu.txt+66−0

This diff is large: its 67 lines aren’t shown here.

Documentation/devicetree/bindings/virtio/mmio.txt+30−0

This diff is large: its 41 lines aren’t shown here.

Documentation/devicetree/bindings/watchdog/fsl-imx-sc-wdt.txt+0−24

This diff is large: its 25 lines aren’t shown here.

Documentation/devicetree/bindings/watchdog/renesas,wdt.txtrenamed from Documentation/devicetree/bindings/watchdog/renesas-wdt.txt+0−0

File renamed without changes.

Documentation/devicetree/bindings/watchdog/sunxi-wdt.txt+1−0

This diff is large: its 8 lines aren’t shown here.

Documentation/devicetree/booting-without-of.txt+3−3

This diff is large: its 27 lines aren’t shown here.

Documentation/doc-guide/conf.py+0−10

This diff is large: its 11 lines aren’t shown here.

Documentation/doc-guide/kernel-doc.rst+1−1

This diff is large: its 9 lines aren’t shown here.

Documentation/doc-guide/sphinx.rst+17−15

This diff is large: its 69 lines aren’t shown here.

Documentation/docutils.conf+1−1

This diff is large: its 6 lines aren’t shown here.

Documentation/dontdiff+1−0

This diff is large: its 8 lines aren’t shown here.

Documentation/driver-api/80211/conf.py+0−10

This diff is large: its 11 lines aren’t shown here.

Documentation/driver-api/80211/mac80211-advanced.rst+0−3

This diff is large: its 10 lines aren’t shown here.

Documentation/driver-api/backlight/lp855x-driver.rst+81−0

This diff is large: its 82 lines aren’t shown here.

Documentation/driver-api/basics.rst+0−3

This diff is large: its 10 lines aren’t shown here.

Documentation/driver-api/bt8xxgpio.rstrenamed from Documentation/bt8xxgpio.txt+0−0

File renamed without changes.

Documentation/driver-api/clk.rst+3−3

This diff is large: its 13 lines aren’t shown here.

Documentation/driver-api/conf.py+0−10

This diff is large: its 11 lines aren’t shown here.

Documentation/driver-api/connector.rst+156−0

This diff is large: its 157 lines aren’t shown here.

Documentation/driver-api/console.rst+152−0

This diff is large: its 153 lines aren’t shown here.

Documentation/driver-api/dcdbas.rstrenamed from Documentation/dcdbas.txt+0−0

File renamed without changes.

Documentation/driver-api/dell_rbu.rstrenamed from Documentation/dell_rbu.txt+0−0

File renamed without changes.

Documentation/driver-api/dmaengine/dmatest.rst+13−8

This diff is large: its 44 lines aren’t shown here.

Documentation/driver-api/driver-model/binding.rst+98−0

This diff is large: its 99 lines aren’t shown here.

Documentation/driver-api/driver-model/bus.rst+146−0

This diff is large: its 147 lines aren’t shown here.

Documentation/driver-api/driver-model/class.rst+149−0

This diff is large: its 150 lines aren’t shown here.

Documentation/driver-api/driver-model/design-patterns.rst+116−0

This diff is large: its 117 lines aren’t shown here.

Documentation/driver-api/driver-model/device.rst+109−0

This diff is large: its 110 lines aren’t shown here.

Documentation/driver-api/driver-model/devres.rst+418−0

This diff is large: its 419 lines aren’t shown here.

Documentation/driver-api/driver-model/driver.rst+223−0

This diff is large: its 224 lines aren’t shown here.

Documentation/driver-api/driver-model/index.rst+24−0

This diff is large: its 25 lines aren’t shown here.

Documentation/driver-api/driver-model/overview.rst+124−0

This diff is large: its 125 lines aren’t shown here.

Documentation/driver-api/driver-model/platform.rst+246−0

This diff is large: its 247 lines aren’t shown here.

Documentation/driver-api/driver-model/porting.rst+448−0

This diff is large: its 449 lines aren’t shown here.

Documentation/driver-api/early-userspace/buffer-format.rst+119−0

This diff is large: its 120 lines aren’t shown here.

Documentation/driver-api/early-userspace/early_userspace_support.rst+154−0

This diff is large: its 155 lines aren’t shown here.

Documentation/driver-api/early-userspace/index.rst+18−0

This diff is large: its 19 lines aren’t shown here.

Documentation/driver-api/edid.rst+58−0

This diff is large: its 59 lines aren’t shown here.

Documentation/driver-api/eisa.rst+230−0

This diff is large: its 231 lines aren’t shown here.

Documentation/driver-api/firmware/other_interfaces.rst+1−1

This diff is large: its 9 lines aren’t shown here.

Documentation/driver-api/generic-counter.rst+2−2

This diff is large: its 18 lines aren’t shown here.

Documentation/driver-api/gpio/board.rst+1−1

This diff is large: its 9 lines aren’t shown here.

Documentation/driver-api/gpio/consumer.rst+2−4

This diff is large: its 27 lines aren’t shown here.

Documentation/driver-api/gpio/driver.rst+9−9

This diff is large: its 60 lines aren’t shown here.

Documentation/driver-api/iio/hw-consumer.rst+0−1

This diff is large: its 8 lines aren’t shown here.

Documentation/driver-api/index.rst+44−1

This diff is large: its 84 lines aren’t shown here.

Documentation/driver-api/interconnect.rstrenamed from Documentation/interconnect/interconnect.rst+2−3

This diff is large: its 9 lines aren’t shown here.

Documentation/driver-api/ipmb.rst+105−0

This diff is large: its 106 lines aren’t shown here.

Documentation/driver-api/isa.rstrenamed from Documentation/isa.txt+0−0

File renamed without changes.

Documentation/driver-api/isapnp.rstrenamed from Documentation/isapnp.txt+0−0

File renamed without changes.

Documentation/driver-api/lightnvm-pblk.rstrenamed from Documentation/lightnvm/pblk.txt+0−0

File renamed without changes.

Documentation/driver-api/md/index.rst+12−0

This diff is large: its 13 lines aren’t shown here.

Documentation/driver-api/md/md-cluster.rst+385−0

This diff is large: its 386 lines aren’t shown here.

Documentation/driver-api/md/raid5-cache.rst+111−0

This diff is large: its 112 lines aren’t shown here.

Documentation/driver-api/md/raid5-ppl.rst+47−0

This diff is large: its 48 lines aren’t shown here.

Documentation/driver-api/mei/hdcp.rst+32−0

This diff is large: its 33 lines aren’t shown here.

Documentation/driver-api/mei/iamt.rst+101−0

This diff is large: its 102 lines aren’t shown here.

Documentation/driver-api/mei/index.rst+23−0

This diff is large: its 24 lines aren’t shown here.

Documentation/driver-api/mei/mei-client-bus.rst+168−0

This diff is large: its 169 lines aren’t shown here.

Documentation/driver-api/mei/mei.rst+176−0

This diff is large: its 177 lines aren’t shown here.

Documentation/driver-api/mei/nfc.rst+28−0

This diff is large: its 29 lines aren’t shown here.

Documentation/driver-api/memory-devices/index.rst+18−0

This diff is large: its 19 lines aren’t shown here.

Documentation/driver-api/memory-devices/ti-emif.rst+64−0

This diff is large: its 65 lines aren’t shown here.

Documentation/driver-api/memory-devices/ti-gpmc.rst+179−0

This diff is large: its 180 lines aren’t shown here.

Documentation/driver-api/men-chameleon-bus.rstrenamed from Documentation/men-chameleon-bus.txt+0−0

File renamed without changes.

Documentation/driver-api/mmc/index.rst+13−0

This diff is large: its 14 lines aren’t shown here.

Documentation/driver-api/mmc/mmc-async-req.rst+98−0

This diff is large: its 99 lines aren’t shown here.

Documentation/driver-api/mmc/mmc-dev-attrs.rst+91−0

This diff is large: its 92 lines aren’t shown here.

Documentation/driver-api/mmc/mmc-dev-parts.rst+41−0

This diff is large: its 42 lines aren’t shown here.

Documentation/driver-api/mmc/mmc-tools.rst+37−0

This diff is large: its 38 lines aren’t shown here.

Documentation/driver-api/mtd/index.rst+12−0

This diff is large: its 13 lines aren’t shown here.

Documentation/driver-api/mtd/intel-spi.rst+90−0

This diff is large: its 91 lines aren’t shown here.

Documentation/driver-api/mtd/nand_ecc.rst+763−0

This diff is large: its 764 lines aren’t shown here.

Documentation/driver-api/mtd/spi-nor.rst+66−0

This diff is large: its 67 lines aren’t shown here.

Documentation/driver-api/nfc/index.rst+11−0

This diff is large: its 12 lines aren’t shown here.

Documentation/driver-api/nfc/nfc-hci.rst+311−0

This diff is large: its 312 lines aren’t shown here.

Documentation/driver-api/nfc/nfc-pn544.rst+34−0

This diff is large: its 35 lines aren’t shown here.

Documentation/driver-api/ntb.rst+263−0

This diff is large: its 264 lines aren’t shown here.

Documentation/driver-api/nvdimm/btt.rst+285−0

This diff is large: its 286 lines aren’t shown here.

Documentation/driver-api/nvdimm/index.rst+12−0

This diff is large: its 13 lines aren’t shown here.

Documentation/driver-api/nvdimm/nvdimm.rst+887−0

This diff is large: its 888 lines aren’t shown here.

Documentation/driver-api/nvdimm/security.rst+143−0

This diff is large: its 144 lines aren’t shown here.

Documentation/driver-api/nvmem.rst+189−0

This diff is large: its 190 lines aren’t shown here.

Documentation/driver-api/parport-lowlevel.rstrenamed from Documentation/parport-lowlevel.txt+0−0

File renamed without changes.

Documentation/driver-api/phy/index.rst+18−0

This diff is large: its 19 lines aren’t shown here.

Documentation/driver-api/phy/phy.rst+197−0

This diff is large: its 198 lines aren’t shown here.

Documentation/driver-api/phy/samsung-usb2.rst+137−0

This diff is large: its 138 lines aren’t shown here.

Documentation/driver-api/pm/conf.py+0−10

This diff is large: its 11 lines aren’t shown here.

Documentation/driver-api/pm/devices.rst+3−3

This diff is large: its 27 lines aren’t shown here.

Documentation/driver-api/pps.rst+242−0

This diff is large: its 243 lines aren’t shown here.

Documentation/driver-api/pti_intel_mid.rst+106−0

This diff is large: its 107 lines aren’t shown here.

Documentation/driver-api/ptp.rst+96−0

This diff is large: its 97 lines aren’t shown here.

Documentation/driver-api/pwm.rst+165−0

This diff is large: its 166 lines aren’t shown here.

Documentation/driver-api/rapidio/index.rst+15−0

This diff is large: its 16 lines aren’t shown here.

Documentation/driver-api/rapidio/mport_cdev.rst+110−0

This diff is large: its 111 lines aren’t shown here.

Documentation/driver-api/rapidio/rapidio.rst+362−0

This diff is large: its 363 lines aren’t shown here.

Documentation/driver-api/rapidio/rio_cm.rst+135−0

This diff is large: its 136 lines aren’t shown here.

Documentation/driver-api/rapidio/sysfs.rst+7−0

This diff is large: its 8 lines aren’t shown here.

Documentation/driver-api/rapidio/tsi721.rst+112−0

This diff is large: its 113 lines aren’t shown here.

Documentation/driver-api/rfkill.rstrenamed from Documentation/rfkill.txt+0−0

File renamed without changes.

Documentation/driver-api/s390-drivers.rst+2−2

This diff is large: its 18 lines aren’t shown here.

Documentation/driver-api/serial/cyclades_z.rstrenamed from Documentation/serial/cyclades_z.rst+0−0

File renamed without changes.

Documentation/driver-api/serial/driver.rst+549−0

This diff is large: its 550 lines aren’t shown here.

Documentation/driver-api/serial/index.rst+32−0

This diff is large: its 33 lines aren’t shown here.

Documentation/driver-api/serial/moxa-smartio.rstrenamed from Documentation/serial/moxa-smartio.rst+0−0

File renamed without changes.

Documentation/driver-api/serial/n_gsm.rstrenamed from Documentation/serial/n_gsm.rst+0−0

File renamed without changes.

Documentation/driver-api/serial/rocket.rstrenamed from Documentation/serial/rocket.rst+0−0

File renamed without changes.

Documentation/driver-api/serial/serial-iso7816.rstrenamed from Documentation/serial/serial-iso7816.rst+0−0

File renamed without changes.

Documentation/driver-api/serial/serial-rs485.rstrenamed from Documentation/serial/serial-rs485.rst+0−0

File renamed without changes.

Documentation/driver-api/serial/tty.rstrenamed from Documentation/serial/tty.rst+0−0

File renamed without changes.

Documentation/driver-api/sgi-ioc4.rstrenamed from Documentation/sgi-ioc4.txt+0−0

File renamed without changes.

Documentation/driver-api/sm501.rstrenamed from Documentation/SM501.txt+0−0

File renamed without changes.

Documentation/driver-api/smsc_ece1099.rstrenamed from Documentation/smsc_ece1099.txt+0−0

File renamed without changes.

Documentation/driver-api/soundwire/locking.rst+3−1

This diff is large: its 11 lines aren’t shown here.

Documentation/driver-api/switchtec.rst+102−0

This diff is large: its 103 lines aren’t shown here.

Documentation/driver-api/sync_file.rstrenamed from Documentation/sync_file.txt+0−0

File renamed without changes.

Documentation/driver-api/target.rst+2−2

This diff is large: its 11 lines aren’t shown here.

Documentation/driver-api/uio-howto.rst+2−2

This diff is large: its 11 lines aren’t shown here.

Documentation/driver-api/usb/power-management.rst+1−1

This diff is large: its 9 lines aren’t shown here.

Documentation/driver-api/vfio-mediated-device.rst+414−0

This diff is large: its 415 lines aren’t shown here.

Documentation/driver-api/vfio.rstrenamed from Documentation/vfio.txt+0−0

File renamed without changes.

Documentation/driver-api/xilinx/eemi.rst+67−0

This diff is large: its 68 lines aren’t shown here.

Documentation/driver-api/xilinx/index.rst+16−0

This diff is large: its 17 lines aren’t shown here.

Documentation/driver-api/xillybus.rstrenamed from Documentation/xillybus.txt+0−0

File renamed without changes.

Documentation/driver-api/zorro.rstrenamed from Documentation/zorro.txt+0−0

File renamed without changes.

Documentation/driver-model/binding.txt+0−98

This diff is large: its 99 lines aren’t shown here.

Documentation/driver-model/bus.txt+0−143

This diff is large: its 144 lines aren’t shown here.

Documentation/driver-model/class.txt+0−147

This diff is large: its 148 lines aren’t shown here.

Documentation/driver-model/design-patterns.txt+0−116

This diff is large: its 117 lines aren’t shown here.

Documentation/driver-model/device.txt+0−106

This diff is large: its 107 lines aren’t shown here.

Documentation/driver-model/devres.txt+0−412

This diff is large: its 413 lines aren’t shown here.

Documentation/driver-model/driver.txt+0−215

This diff is large: its 216 lines aren’t shown here.

Documentation/driver-model/overview.txt+0−123

This diff is large: its 124 lines aren’t shown here.

Documentation/driver-model/platform.txt+0−244

This diff is large: its 245 lines aren’t shown here.

Documentation/driver-model/porting.txt+0−447

This diff is large: its 448 lines aren’t shown here.

Documentation/early-userspace/README+0−151

This diff is large: its 152 lines aren’t shown here.

Documentation/early-userspace/buffer-format.txt+0−112

This diff is large: its 113 lines aren’t shown here.

Documentation/eisa.txt+0−230

This diff is large: its 231 lines aren’t shown here.

Documentation/extcon/intel-int3496.txt+0−27

This diff is large: its 28 lines aren’t shown here.

Documentation/fault-injection/fault-injection.rst+446−0

This diff is large: its 447 lines aren’t shown here.

Documentation/fault-injection/fault-injection.txt+0−435

This diff is large: its 436 lines aren’t shown here.

Documentation/fault-injection/index.rst+20−0

This diff is large: its 21 lines aren’t shown here.

Documentation/fault-injection/notifier-error-inject.rst+98−0

This diff is large: its 99 lines aren’t shown here.

Documentation/fault-injection/notifier-error-inject.txt+0−94

This diff is large: its 95 lines aren’t shown here.

Documentation/fault-injection/nvme-fault-injection.rst+178−0

This diff is large: its 179 lines aren’t shown here.

Documentation/fault-injection/nvme-fault-injection.txt+0−116

This diff is large: its 117 lines aren’t shown here.

Documentation/fault-injection/provoke-crashes.rst+48−0

This diff is large: its 49 lines aren’t shown here.

Documentation/fault-injection/provoke-crashes.txt+0−38

This diff is large: its 39 lines aren’t shown here.

Documentation/fb/api.rst+307−0

This diff is large: its 308 lines aren’t shown here.

Documentation/fb/api.txt+0−306

This diff is large: its 307 lines aren’t shown here.

Documentation/fb/arkfb.rst+68−0

This diff is large: its 69 lines aren’t shown here.

Documentation/fb/arkfb.txt+0−68

This diff is large: its 69 lines aren’t shown here.

Documentation/fb/aty128fb.rst+75−0

This diff is large: its 76 lines aren’t shown here.

Documentation/fb/aty128fb.txt+0−72

This diff is large: its 73 lines aren’t shown here.

Documentation/fb/cirrusfb.rst+94−0

This diff is large: its 95 lines aren’t shown here.

Documentation/fb/cirrusfb.txt+0−97

This diff is large: its 98 lines aren’t shown here.

Documentation/fb/cmap_xfbdev.rst+56−0

This diff is large: its 57 lines aren’t shown here.

Documentation/fb/cmap_xfbdev.txt+0−53

This diff is large: its 54 lines aren’t shown here.

Documentation/fb/deferred_io.rst+79−0

This diff is large: its 80 lines aren’t shown here.

Documentation/fb/deferred_io.txt+0−75

This diff is large: its 76 lines aren’t shown here.

Documentation/fb/efifb.rst+39−0

This diff is large: its 40 lines aren’t shown here.

Documentation/fb/efifb.txt+0−37

This diff is large: its 38 lines aren’t shown here.

Documentation/fb/ep93xx-fb.rst+140−0

This diff is large: its 141 lines aren’t shown here.

Documentation/fb/ep93xx-fb.txt+0−135

This diff is large: its 136 lines aren’t shown here.

Documentation/fb/fbcon.rst+350−0

This diff is large: its 351 lines aren’t shown here.

Documentation/fb/fbcon.txt+0−347

This diff is large: its 348 lines aren’t shown here.

Documentation/fb/framebuffer.rst+353−0

This diff is large: its 354 lines aren’t shown here.

Documentation/fb/framebuffer.txt+0−343

This diff is large: its 344 lines aren’t shown here.

Documentation/fb/gxfb.rst+54−0

This diff is large: its 55 lines aren’t shown here.

Documentation/fb/gxfb.txt+0−52

This diff is large: its 53 lines aren’t shown here.

Documentation/fb/index.rst+50−0

This diff is large: its 51 lines aren’t shown here.

Documentation/fb/intel810.rst+287−0

This diff is large: its 288 lines aren’t shown here.

Documentation/fb/intel810.txt+0−278

This diff is large: its 279 lines aren’t shown here.

Documentation/fb/intelfb.rst+155−0

This diff is large: its 156 lines aren’t shown here.

Documentation/fb/intelfb.txt+0−149

This diff is large: its 150 lines aren’t shown here.

Documentation/fb/internals.rst+86−0

This diff is large: its 87 lines aren’t shown here.

Documentation/fb/internals.txt+0−82

This diff is large: its 83 lines aren’t shown here.

Documentation/fb/lxfb.rst+55−0

This diff is large: its 56 lines aren’t shown here.

Documentation/fb/lxfb.txt+0−52

This diff is large: its 53 lines aren’t shown here.

Documentation/fb/matroxfb.rst+443−0

This diff is large: its 444 lines aren’t shown here.

Documentation/fb/matroxfb.txt+0−413

This diff is large: its 414 lines aren’t shown here.

Documentation/fb/metronomefb.rst+38−0

This diff is large: its 39 lines aren’t shown here.

Documentation/fb/metronomefb.txt+0−36

This diff is large: its 37 lines aren’t shown here.

Documentation/fb/modedb.rst+169−0

This diff is large: its 170 lines aren’t shown here.

Documentation/fb/modedb.txt+0−165

This diff is large: its 166 lines aren’t shown here.

Documentation/fb/pvr2fb.rst+66−0

This diff is large: its 67 lines aren’t shown here.

Documentation/fb/pvr2fb.txt+0−65

This diff is large: its 66 lines aren’t shown here.

Documentation/fb/pxafb.rst+173−0

This diff is large: its 174 lines aren’t shown here.

Documentation/fb/pxafb.txt+0−142

This diff is large: its 143 lines aren’t shown here.

Documentation/fb/s3fb.rst+82−0

This diff is large: its 83 lines aren’t shown here.

Documentation/fb/s3fb.txt+0−82

This diff is large: its 83 lines aren’t shown here.

Documentation/fb/sa1100fb.rst+40−0

This diff is large: its 41 lines aren’t shown here.

Documentation/fb/sa1100fb.txt+0−39

This diff is large: its 40 lines aren’t shown here.

Documentation/fb/sh7760fb.rst+130−0

This diff is large: its 131 lines aren’t shown here.

Documentation/fb/sh7760fb.txt+0−131

This diff is large: its 132 lines aren’t shown here.

Documentation/fb/sisfb.rst+160−0

This diff is large: its 161 lines aren’t shown here.

Documentation/fb/sisfb.txt+0−158

This diff is large: its 159 lines aren’t shown here.

Documentation/fb/sm501.rst+15−0

This diff is large: its 16 lines aren’t shown here.

Documentation/fb/sm501.txt+0−10

This diff is large: its 11 lines aren’t shown here.

Documentation/fb/sm712fb.rst+35−0

This diff is large: its 36 lines aren’t shown here.

Documentation/fb/sm712fb.txt+0−31

This diff is large: its 32 lines aren’t shown here.

Documentation/fb/sstfb.rst+207−0

This diff is large: its 208 lines aren’t shown here.

Documentation/fb/sstfb.txt+0−174

This diff is large: its 175 lines aren’t shown here.

Documentation/fb/tgafb.rst+71−0

This diff is large: its 72 lines aren’t shown here.

Documentation/fb/tgafb.txt+0−69

This diff is large: its 70 lines aren’t shown here.

Documentation/fb/tridentfb.rst+78−0

This diff is large: its 79 lines aren’t shown here.

Documentation/fb/tridentfb.txt+0−70

This diff is large: its 71 lines aren’t shown here.

Documentation/fb/udlfb.rst+162−0

This diff is large: its 163 lines aren’t shown here.

Documentation/fb/udlfb.txt+0−159

This diff is large: its 160 lines aren’t shown here.

Documentation/fb/uvesafb.rst+188−0

This diff is large: its 189 lines aren’t shown here.

Documentation/fb/uvesafb.txt+0−184

This diff is large: its 185 lines aren’t shown here.

Documentation/fb/vesafb.rst+192−0

This diff is large: its 193 lines aren’t shown here.

Documentation/fb/vesafb.txt+0−181

This diff is large: its 182 lines aren’t shown here.

Documentation/fb/viafb.rst+297−0

This diff is large: its 298 lines aren’t shown here.

Documentation/fb/viafb.txt+0−252

This diff is large: its 253 lines aren’t shown here.

Documentation/fb/vt8623fb.rst+64−0

This diff is large: its 65 lines aren’t shown here.

Documentation/fb/vt8623fb.txt+0−64

This diff is large: its 65 lines aren’t shown here.

Documentation/features/debug/stackprotector/arch-support.txt+1−1

This diff is large: its 9 lines aren’t shown here.

Documentation/filesystems/Locking+0−14

This diff is large: its 33 lines aren’t shown here.

Documentation/filesystems/api-summary.rst+0−3

This diff is large: its 10 lines aren’t shown here.

Documentation/filesystems/coda.txt+7−4

This diff is large: its 25 lines aren’t shown here.

Documentation/filesystems/conf.py+0−10

This diff is large: its 11 lines aren’t shown here.

Documentation/filesystems/dax.txt+1−1

This diff is large: its 9 lines aren’t shown here.

Documentation/filesystems/debugfs.txt+1−1

This diff is large: its 9 lines aren’t shown here.

Documentation/filesystems/ext2.txt+7−1

This diff is large: its 15 lines aren’t shown here.

Documentation/filesystems/ext4/index.rst+4−4

This diff is large: its 12 lines aren’t shown here.

Documentation/filesystems/f2fs.txt+123−10

This diff is large: its 191 lines aren’t shown here.

Documentation/filesystems/fscrypt.rst+42−1

This diff is large: its 54 lines aren’t shown here.

Documentation/filesystems/index.rst+2−11

This diff is large: its 24 lines aren’t shown here.

Documentation/filesystems/nfs/nfsroot.txt+1−1

This diff is large: its 9 lines aren’t shown here.

Documentation/filesystems/porting+18−7

This diff is large: its 63 lines aren’t shown here.

Documentation/filesystems/proc.txt+74−13

This diff is large: its 154 lines aren’t shown here.

Documentation/filesystems/ramfs-rootfs-initramfs.txt+2−2

This diff is large: its 18 lines aren’t shown here.

Documentation/filesystems/sysfs.txt+1−1

This diff is large: its 9 lines aren’t shown here.

Documentation/filesystems/tmpfs.txt+1−1

This diff is large: its 9 lines aren’t shown here.

Documentation/filesystems/ubifs-authentication.md+2−2

This diff is large: its 12 lines aren’t shown here.

Documentation/filesystems/vfs.rst+1428−0

This diff is large: its 1429 lines aren’t shown here.

Documentation/filesystems/vfs.txt+0−1268

This diff is large: its 1269 lines aren’t shown here.

Documentation/filesystems/xfs-delayed-logging-design.txt+1−1

This diff is large: its 9 lines aren’t shown here.

Documentation/filesystems/xfs-self-describing-metadata.txt+4−4

This diff is large: its 36 lines aren’t shown here.

Documentation/filesystems/xfs.txt+0−470

This diff is large: its 471 lines aren’t shown here.

Documentation/firmware-guide/acpi/enumeration.rst+2−2

This diff is large: its 18 lines aren’t shown here.

Documentation/firmware-guide/acpi/extcon-intel-int3496.rst+33−0

This diff is large: its 34 lines aren’t shown here.

Documentation/firmware-guide/acpi/index.rst+1−0

This diff is large: its 5 lines aren’t shown here.

Documentation/firmware-guide/acpi/method-tracing.rst+1−1

This diff is large: its 9 lines aren’t shown here.

Documentation/fmc/API.txt+0−47

This diff is large: its 48 lines aren’t shown here.

Documentation/fmc/FMC-and-SDB.txt+0−88

This diff is large: its 89 lines aren’t shown here.

Documentation/fmc/carrier.txt+0−311

This diff is large: its 312 lines aren’t shown here.

Documentation/fmc/fmc-chardev.txt+0−64

This diff is large: its 65 lines aren’t shown here.

Documentation/fmc/fmc-fakedev.txt+0−36

This diff is large: its 37 lines aren’t shown here.

Documentation/fmc/fmc-trivial.txt+0−17

This diff is large: its 18 lines aren’t shown here.

Documentation/fmc/fmc-write-eeprom.txt+0−98

This diff is large: its 99 lines aren’t shown here.

Documentation/fmc/identifiers.txt+0−168

This diff is large: its 169 lines aren’t shown here.

Documentation/fmc/mezzanine.txt+0−123

This diff is large: its 124 lines aren’t shown here.

Documentation/fmc/parameters.txt+0−56

This diff is large: its 57 lines aren’t shown here.

Documentation/fpga/dfl.rst+291−0

This diff is large: its 292 lines aren’t shown here.

Documentation/fpga/dfl.txt+0−285

This diff is large: its 286 lines aren’t shown here.

Documentation/fpga/index.rst+17−0

This diff is large: its 18 lines aren’t shown here.

Documentation/gpio/index.rst+0−17

This diff is large: its 18 lines aren’t shown here.

Documentation/gpu/conf.py+0−10

This diff is large: its 11 lines aren’t shown here.

Documentation/gpu/msm-crash-dump.rst+2−0

This diff is large: its 6 lines aren’t shown here.

Documentation/hid/hid-alps.rst+180−0

This diff is large: its 181 lines aren’t shown here.

Documentation/hid/hid-alps.txt+0−139

This diff is large: its 140 lines aren’t shown here.

Documentation/hid/hid-sensor.rst+242−0

This diff is large: its 243 lines aren’t shown here.

Documentation/hid/hid-sensor.txt+0−224

This diff is large: its 225 lines aren’t shown here.

Documentation/hid/hid-transport.rst+359−0

This diff is large: its 360 lines aren’t shown here.

Documentation/hid/hid-transport.txt+0−317

This diff is large: its 318 lines aren’t shown here.

Documentation/hid/hiddev.rst+251−0

This diff is large: its 252 lines aren’t shown here.

Documentation/hid/hiddev.txt+0−205

This diff is large: its 206 lines aren’t shown here.

Documentation/hid/hidraw.rst+138−0

This diff is large: its 139 lines aren’t shown here.

Documentation/hid/hidraw.txt+0−119

This diff is large: its 120 lines aren’t shown here.

Documentation/hid/index.rst+18−0

This diff is large: its 19 lines aren’t shown here.

Documentation/hid/intel-ish-hid.rst+485−0

This diff is large: its 486 lines aren’t shown here.

Documentation/hid/intel-ish-hid.txt+0−454

This diff is large: its 455 lines aren’t shown here.

Documentation/hid/uhid.rst+193−0

This diff is large: its 194 lines aren’t shown here.

Documentation/hid/uhid.txt+0−187

This diff is large: its 188 lines aren’t shown here.

Documentation/hwmon/k8temp.rst+1−1

This diff is large: its 9 lines aren’t shown here.

Documentation/hwmon/pxe1610+90−0

This diff is large: its 91 lines aren’t shown here.

Documentation/hwmon/submitting-patches.rst+1−1

This diff is large: its 9 lines aren’t shown here.

Documentation/hwspinlock.txt+81−0

This diff is large: its 102 lines aren’t shown here.

Documentation/i2c/busses/i2c-i801+11−9

This diff is large: its 50 lines aren’t shown here.

Documentation/i2c/instantiating-devices+2−2

This diff is large: its 18 lines aren’t shown here.

Documentation/i2c/upgrading-clients+2−2

This diff is large: its 18 lines aren’t shown here.

Documentation/ia64/IRQ-redir.txt+0−69

This diff is large: its 70 lines aren’t shown here.

Documentation/ia64/README+0−43

This diff is large: its 44 lines aren’t shown here.

Documentation/ia64/aliasing.rst+246−0

This diff is large: its 247 lines aren’t shown here.

Documentation/ia64/aliasing.txt+0−221

This diff is large: its 222 lines aren’t shown here.

Documentation/ia64/efirtc.rst+144−0

This diff is large: its 145 lines aren’t shown here.

Documentation/ia64/efirtc.txt+0−128

This diff is large: its 129 lines aren’t shown here.

Documentation/ia64/err_inject.rst+1067−0

This diff is large: its 1068 lines aren’t shown here.

Documentation/ia64/err_inject.txt+0−1068

This diff is large: its 1069 lines aren’t shown here.

Documentation/ia64/fsys.rst+303−0

This diff is large: its 304 lines aren’t shown here.

Documentation/ia64/fsys.txt+0−286

This diff is large: its 287 lines aren’t shown here.

Documentation/ia64/ia64.rst+49−0

This diff is large: its 50 lines aren’t shown here.

Documentation/ia64/index.rst+18−0

This diff is large: its 19 lines aren’t shown here.

Documentation/ia64/irq-redir.rst+80−0

This diff is large: its 81 lines aren’t shown here.

Documentation/ia64/mca.rst+198−0

This diff is large: its 199 lines aren’t shown here.

Documentation/ia64/mca.txt+0−194

This diff is large: its 195 lines aren’t shown here.

Documentation/ia64/serial.rst+165−0

This diff is large: its 166 lines aren’t shown here.

Documentation/ia64/serial.txt+0−151

This diff is large: its 152 lines aren’t shown here.

Documentation/ia64/xen.rst+206−0

This diff is large: its 207 lines aren’t shown here.

Documentation/ia64/xen.txt+0−183

This diff is large: its 184 lines aren’t shown here.

Documentation/ide/changelogs.rst+17−0

This diff is large: its 18 lines aren’t shown here.

Documentation/ide/ide-tape.rst+68−0

This diff is large: its 69 lines aren’t shown here.

Documentation/ide/ide-tape.txt+0−65

This diff is large: its 66 lines aren’t shown here.

Documentation/ide/ide.rst+265−0

This diff is large: its 266 lines aren’t shown here.

Documentation/ide/ide.txt+0−256

This diff is large: its 257 lines aren’t shown here.

Documentation/ide/index.rst+21−0

This diff is large: its 22 lines aren’t shown here.

Documentation/ide/warm-plug-howto.rst+18−0

This diff is large: its 19 lines aren’t shown here.

Documentation/ide/warm-plug-howto.txt+0−18

This diff is large: its 19 lines aren’t shown here.

Documentation/iio/ep93xx_adc.rst+40−0

This diff is large: its 41 lines aren’t shown here.

Documentation/iio/ep93xx_adc.txt+0−29

This diff is large: its 30 lines aren’t shown here.

Documentation/iio/iio_configfs.rst+101−0

This diff is large: its 102 lines aren’t shown here.

Documentation/iio/iio_configfs.txt+0−93

This diff is large: its 94 lines aren’t shown here.

Documentation/iio/index.rst+12−0

This diff is large: its 13 lines aren’t shown here.

Documentation/index.rst+38−1

This diff is large: its 90 lines aren’t shown here.

Documentation/infiniband/core_locking.rst+118−0

This diff is large: its 119 lines aren’t shown here.

Documentation/infiniband/core_locking.txt+0−112

This diff is large: its 113 lines aren’t shown here.

Documentation/infiniband/index.rst+23−0

This diff is large: its 24 lines aren’t shown here.

Documentation/infiniband/ipoib.rst+115−0

This diff is large: its 116 lines aren’t shown here.

Documentation/infiniband/ipoib.txt+0−105

This diff is large: its 106 lines aren’t shown here.

Documentation/infiniband/opa_vnic.rst+159−0

This diff is large: its 160 lines aren’t shown here.

Documentation/infiniband/opa_vnic.txt+0−153

This diff is large: its 154 lines aren’t shown here.

Documentation/infiniband/sysfs.rst+6−0

This diff is large: its 7 lines aren’t shown here.

Documentation/infiniband/sysfs.txt+0−4

This diff is large: its 5 lines aren’t shown here.

Documentation/infiniband/tag_matching.rst+69−0

This diff is large: its 70 lines aren’t shown here.

Documentation/infiniband/tag_matching.txt+0−64

This diff is large: its 65 lines aren’t shown here.

Documentation/infiniband/user_mad.rst+166−0

This diff is large: its 167 lines aren’t shown here.

Documentation/infiniband/user_mad.txt+0−153

This diff is large: its 154 lines aren’t shown here.

Documentation/infiniband/user_verbs.rst+75−0

This diff is large: its 76 lines aren’t shown here.

Documentation/infiniband/user_verbs.txt+0−69

This diff is large: its 70 lines aren’t shown here.

Documentation/input/conf.py+0−10

This diff is large: its 11 lines aren’t shown here.

Documentation/input/input.rst+1−1

This diff is large: its 9 lines aren’t shown here.

Documentation/ioctl/botching-up-ioctls.rst+225−0

This diff is large: its 226 lines aren’t shown here.

Documentation/ioctl/botching-up-ioctls.txt+0−224

This diff is large: its 225 lines aren’t shown here.

Documentation/ioctl/cdrom.rst+1233−0

This diff is large: its 1234 lines aren’t shown here.

Documentation/ioctl/cdrom.txt+0−967

This diff is large: its 968 lines aren’t shown here.

Documentation/ioctl/hdio.rst+1342−0

This diff is large: its 1343 lines aren’t shown here.

Documentation/ioctl/hdio.txt+0−1071

This diff is large: its 1072 lines aren’t shown here.

Documentation/ioctl/index.rst+16−0

This diff is large: its 17 lines aren’t shown here.

Documentation/ioctl/ioctl-decoding.rst+31−0

This diff is large: its 32 lines aren’t shown here.

Documentation/ioctl/ioctl-decoding.txt+0−24

This diff is large: its 25 lines aren’t shown here.

Documentation/ioctl/ioctl-number.rst+361−0

This diff is large: its 362 lines aren’t shown here.

Documentation/ioctl/ioctl-number.txt+0−350

This diff is large: its 351 lines aren’t shown here.

Documentation/iostats.txt+0−193

This diff is large: its 194 lines aren’t shown here.

Documentation/isdn/HiSax.cert+0−96

This diff is large: its 97 lines aren’t shown here.

Documentation/isdn/INTERFACE+0−759

This diff is large: its 760 lines aren’t shown here.

Documentation/isdn/INTERFACE.fax+0−163

This diff is large: its 164 lines aren’t shown here.

Documentation/isdn/README+0−599

This diff is large: its 600 lines aren’t shown here.

Documentation/isdn/README.FAQ+0−26

This diff is large: its 27 lines aren’t shown here.

Documentation/isdn/README.HiSax+0−659

This diff is large: its 660 lines aren’t shown here.

Documentation/isdn/README.audio+0−138

This diff is large: its 139 lines aren’t shown here.

Documentation/isdn/README.concap+0−259

This diff is large: its 260 lines aren’t shown here.

Documentation/isdn/README.diversion+0−127

This diff is large: its 128 lines aren’t shown here.

Documentation/isdn/README.fax+0−45

This diff is large: its 46 lines aren’t shown here.

Documentation/isdn/README.gigaset+8−28

This diff is large: its 71 lines aren’t shown here.

Documentation/isdn/README.hfc-pci+0−41

This diff is large: its 42 lines aren’t shown here.

Documentation/isdn/README.syncppp+0−58

This diff is large: its 59 lines aren’t shown here.

Documentation/isdn/README.x25+0−184

This diff is large: its 185 lines aren’t shown here.

Documentation/isdn/syncPPP.FAQ+0−224

This diff is large: its 225 lines aren’t shown here.

Documentation/kbuild/headers_install.rst+44−0

This diff is large: its 45 lines aren’t shown here.

Documentation/kbuild/headers_install.txt+0−50

This diff is large: its 51 lines aren’t shown here.

Documentation/kbuild/index.rst+27−0

This diff is large: its 28 lines aren’t shown here.

Documentation/kbuild/issues.rst+15−0

This diff is large: its 16 lines aren’t shown here.

Documentation/kbuild/kbuild.rst+274−0

This diff is large: its 275 lines aren’t shown here.

Documentation/kbuild/kbuild.txt+0−248

This diff is large: its 249 lines aren’t shown here.

Documentation/kbuild/kconfig-language.rst+701−0

This diff is large: its 702 lines aren’t shown here.

Documentation/kbuild/kconfig-language.txt+0−669

This diff is large: its 670 lines aren’t shown here.

Documentation/kbuild/kconfig-macro-language.rst+247−0

This diff is large: its 248 lines aren’t shown here.

Documentation/kbuild/kconfig-macro-language.txt+0−242

This diff is large: its 243 lines aren’t shown here.

Documentation/kbuild/kconfig.rst+304−0

This diff is large: its 305 lines aren’t shown here.

Documentation/kbuild/kconfig.txt+0−272

This diff is large: its 273 lines aren’t shown here.

Documentation/kbuild/makefiles.rst+1522−0

This diff is large: its 1523 lines aren’t shown here.

Documentation/kbuild/makefiles.txt+0−1369

This diff is large: its 1370 lines aren’t shown here.

Documentation/kbuild/modules.rst+571−0

This diff is large: its 572 lines aren’t shown here.

Documentation/kbuild/modules.txt+0−541

This diff is large: its 542 lines aren’t shown here.

Documentation/kdump/kdump.txt+0−509

This diff is large: its 510 lines aren’t shown here.

Documentation/kdump/vmcoreinfo.txt+0−495

This diff is large: its 496 lines aren’t shown here.

Documentation/kernel-hacking/conf.py+0−10

This diff is large: its 11 lines aren’t shown here.

Documentation/kernel-hacking/hacking.rst+2−2

This diff is large: its 18 lines aren’t shown here.

Documentation/kernel-hacking/locking.rst+4−4

This diff is large: its 36 lines aren’t shown here.

Documentation/kernel-per-CPU-kthreads.txt+0−356

This diff is large: its 357 lines aren’t shown here.

Documentation/laptops/asus-laptop.txt+0−257

This diff is large: its 258 lines aren’t shown here.

Documentation/laptops/disk-shock-protection.txt+0−149

This diff is large: its 150 lines aren’t shown here.

Documentation/laptops/laptop-mode.txt+0−782

This diff is large: its 783 lines aren’t shown here.

Documentation/laptops/sony-laptop.txt+0−144

This diff is large: its 145 lines aren’t shown here.

Documentation/laptops/sonypi.txt+0−152

This diff is large: its 153 lines aren’t shown here.

Documentation/laptops/thinkpad-acpi.txt+0−1487

This diff is large: its 1488 lines aren’t shown here.

Documentation/laptops/toshiba_haps.txt+0−76

This diff is large: its 77 lines aren’t shown here.

Documentation/leds/index.rst+25−0

This diff is large: its 26 lines aren’t shown here.

Documentation/leds/leds-blinkm.rst+84−0

This diff is large: its 85 lines aren’t shown here.

Documentation/leds/leds-blinkm.txt+0−80

This diff is large: its 81 lines aren’t shown here.

Documentation/leds/leds-class-flash.rst+90−0

This diff is large: its 91 lines aren’t shown here.

Documentation/leds/leds-class-flash.txt+0−73

This diff is large: its 74 lines aren’t shown here.

Documentation/leds/leds-class.rst+125−0

This diff is large: its 126 lines aren’t shown here.

Documentation/leds/leds-class.txt+0−122

This diff is large: its 123 lines aren’t shown here.

Documentation/leds/leds-lm3556.rst+137−0

This diff is large: its 138 lines aren’t shown here.

Documentation/leds/leds-lm3556.txt+0−85

This diff is large: its 86 lines aren’t shown here.

Documentation/leds/leds-lp3944.rst+59−0

This diff is large: its 60 lines aren’t shown here.

Documentation/leds/leds-lp3944.txt+0−50

This diff is large: its 51 lines aren’t shown here.

Documentation/leds/leds-lp5521.rst+115−0

This diff is large: its 116 lines aren’t shown here.

Documentation/leds/leds-lp5521.txt+0−101

This diff is large: its 102 lines aren’t shown here.

Documentation/leds/leds-lp5523.rst+147−0

This diff is large: its 148 lines aren’t shown here.

Documentation/leds/leds-lp5523.txt+0−130

This diff is large: its 131 lines aren’t shown here.

Documentation/leds/leds-lp5562.rst+137−0

This diff is large: its 138 lines aren’t shown here.

Documentation/leds/leds-lp5562.txt+0−120

This diff is large: its 121 lines aren’t shown here.

Documentation/leds/leds-lp55xx.rst+224−0

This diff is large: its 225 lines aren’t shown here.

Documentation/leds/leds-lp55xx.txt+0−194

This diff is large: its 195 lines aren’t shown here.

Documentation/leds/leds-mlxcpld.rst+118−0

This diff is large: its 119 lines aren’t shown here.

Documentation/leds/leds-mlxcpld.txt+0−110

This diff is large: its 111 lines aren’t shown here.

Documentation/leds/ledtrig-oneshot.rst+44−0

This diff is large: its 45 lines aren’t shown here.

Documentation/leds/ledtrig-oneshot.txt+0−43

This diff is large: its 44 lines aren’t shown here.

Documentation/leds/ledtrig-transient.rst+167−0

This diff is large: its 168 lines aren’t shown here.

Documentation/leds/ledtrig-transient.txt+0−152

This diff is large: its 153 lines aren’t shown here.

Documentation/leds/ledtrig-usbport.rst+46−0

This diff is large: its 47 lines aren’t shown here.

Documentation/leds/ledtrig-usbport.txt+0−41

This diff is large: its 42 lines aren’t shown here.

Documentation/leds/uleds.rst+37−0

This diff is large: its 38 lines aren’t shown here.

Documentation/leds/uleds.txt+0−36

This diff is large: its 37 lines aren’t shown here.

Documentation/livepatch/index.rst+1−1

This diff is large: its 6 lines aren’t shown here.

Documentation/locking/index.rst+24−0

This diff is large: its 25 lines aren’t shown here.

Documentation/locking/lockdep-design.rst+394−0

This diff is large: its 395 lines aren’t shown here.

Documentation/locking/lockdep-design.txt+0−333

This diff is large: its 334 lines aren’t shown here.

Documentation/locking/lockstat.rst+204−0

This diff is large: its 205 lines aren’t shown here.

Documentation/locking/lockstat.txt+0−183

This diff is large: its 184 lines aren’t shown here.

Documentation/locking/locktorture.rst+170−0

This diff is large: its 171 lines aren’t shown here.

Documentation/locking/locktorture.txt+0−145

This diff is large: its 146 lines aren’t shown here.

Documentation/locking/mutex-design.rst+152−0

This diff is large: its 153 lines aren’t shown here.

Documentation/locking/mutex-design.txt+0−142

This diff is large: its 143 lines aren’t shown here.

Documentation/locking/rt-mutex-design.rst+574−0

This diff is large: its 575 lines aren’t shown here.

Documentation/locking/rt-mutex-design.txt+0−559

This diff is large: its 560 lines aren’t shown here.

Documentation/locking/rt-mutex.rst+77−0

This diff is large: its 78 lines aren’t shown here.

Documentation/locking/rt-mutex.txt+0−73

This diff is large: its 74 lines aren’t shown here.

Documentation/locking/spinlocks.rst+177−0

This diff is large: its 178 lines aren’t shown here.

Documentation/locking/spinlocks.txt+0−167

This diff is large: its 168 lines aren’t shown here.

Documentation/locking/ww-mutex-design.rst+393−0

This diff is large: its 394 lines aren’t shown here.

Documentation/locking/ww-mutex-design.txt+0−383

This diff is large: its 384 lines aren’t shown here.

Documentation/m68k/index.rst+17−0

This diff is large: its 18 lines aren’t shown here.

Documentation/m68k/kernel-options.rst+911−0

This diff is large: its 912 lines aren’t shown here.

Documentation/m68k/kernel-options.txt+0−884

This diff is large: its 885 lines aren’t shown here.

Documentation/maintainer/conf.py+0−10

This diff is large: its 11 lines aren’t shown here.

Documentation/maintainer/index.rst+1−0

This diff is large: its 7 lines aren’t shown here.

Documentation/maintainer/rebasing-and-merging.rst+226−0

This diff is large: its 227 lines aren’t shown here.

Documentation/md/md-cluster.txt+0−325

This diff is large: its 326 lines aren’t shown here.

Documentation/md/raid5-cache.txt+0−109

This diff is large: its 110 lines aren’t shown here.

Documentation/md/raid5-ppl.txt+0−45

This diff is large: its 46 lines aren’t shown here.

Documentation/media/conf.py+0−12

This diff is large: its 13 lines aren’t shown here.

Documentation/media/kapi/dtv-core.rst+3−3

This diff is large: its 16 lines aren’t shown here.

Documentation/media/kapi/v4l2-controls.rst+102−104

This diff is large: its 481 lines aren’t shown here.

Documentation/media/uapi/cec/cec-api.rst+1−1

This diff is large: its 9 lines aren’t shown here.

Documentation/media/uapi/cec/cec-ioc-g-mode.rst+2−1

This diff is large: its 10 lines aren’t shown here.

Documentation/media/uapi/cec/cec-ioc-receive.rst+14−1

This diff is large: its 29 lines aren’t shown here.

Documentation/media/uapi/mediactl/media-ioc-enum-links.rst+6−1

This diff is large: its 21 lines aren’t shown here.

Documentation/media/uapi/rc/rc-tables.rst+15−15

This diff is large: its 135 lines aren’t shown here.

Documentation/media/uapi/v4l/biblio.rst+9−0

This diff is large: its 16 lines aren’t shown here.

Documentation/media/uapi/v4l/ext-ctrls-codec.rst+625−0

This diff is large: its 646 lines aren’t shown here.

Documentation/media/uapi/v4l/extended-controls.rst+6−9

This diff is large: its 35 lines aren’t shown here.

Documentation/media/uapi/v4l/field-order.rst+11−6

This diff is large: its 41 lines aren’t shown here.

Documentation/media/uapi/v4l/pixfmt-compressed.rst+25−0

This diff is large: its 32 lines aren’t shown here.

Documentation/media/uapi/v4l/pixfmt-v4l2-mplane.rst+14−1

This diff is large: its 22 lines aren’t shown here.

Documentation/media/uapi/v4l/pixfmt-v4l2.rst+12−1

This diff is large: its 20 lines aren’t shown here.

Documentation/media/uapi/v4l/vidioc-qbuf.rst+8−0

This diff is large: its 15 lines aren’t shown here.

Documentation/media/uapi/v4l/vidioc-queryctrl.rst+30−0

This diff is large: its 37 lines aren’t shown here.

Documentation/media/v4l-drivers/index.rst+1−0

This diff is large: its 7 lines aren’t shown here.

Documentation/media/v4l-drivers/vimc.dot+22−0

This diff is large: its 23 lines aren’t shown here.

Documentation/media/v4l-drivers/vimc.rst+98−0

This diff is large: its 99 lines aren’t shown here.

Documentation/media/v4l-drivers/vivid.rst+5−0

This diff is large: its 12 lines aren’t shown here.

Documentation/media/videodev2.h.rst.exceptions+5−0

This diff is large: its 12 lines aren’t shown here.

Documentation/memory-barriers.txt+2−2

This diff is large: its 18 lines aren’t shown here.

Documentation/memory-devices/ti-emif.txt+0−57

This diff is large: its 58 lines aren’t shown here.

Documentation/mic/index.rst+16−0

This diff is large: its 17 lines aren’t shown here.

Documentation/mic/mic_overview.rst+85−0

This diff is large: its 86 lines aren’t shown here.

Documentation/mic/mic_overview.txt+0−81

This diff is large: its 82 lines aren’t shown here.

Documentation/mic/scif_overview.rst+108−0

This diff is large: its 109 lines aren’t shown here.

Documentation/mic/scif_overview.txt+0−98

This diff is large: its 99 lines aren’t shown here.

Documentation/misc-devices/eeprom+0−96

This diff is large: its 97 lines aren’t shown here.

Documentation/misc-devices/eeprom.rst+107−0

This diff is large: its 108 lines aren’t shown here.

Documentation/misc-devices/ics932s401+0−31

This diff is large: its 32 lines aren’t shown here.

Documentation/misc-devices/ics932s401.rst+36−0

This diff is large: its 37 lines aren’t shown here.

Documentation/misc-devices/index.rst+5−0

This diff is large: its 10 lines aren’t shown here.

Documentation/misc-devices/isl29003+0−62

This diff is large: its 63 lines aren’t shown here.

Documentation/misc-devices/isl29003.rst+75−0

This diff is large: its 76 lines aren’t shown here.

Documentation/misc-devices/lis3lv02d+0−93

This diff is large: its 94 lines aren’t shown here.

Documentation/misc-devices/lis3lv02d.rst+99−0

This diff is large: its 100 lines aren’t shown here.

Documentation/misc-devices/max6875+0−110

This diff is large: its 111 lines aren’t shown here.

Documentation/misc-devices/max6875.rst+136−0

This diff is large: its 137 lines aren’t shown here.

Documentation/misc-devices/mei/mei-client-bus.txt+0−141

This diff is large: its 142 lines aren’t shown here.

Documentation/misc-devices/mei/mei.txt+0−266

This diff is large: its 267 lines aren’t shown here.

Documentation/mmc/mmc-async-req.txt+0−87

This diff is large: its 88 lines aren’t shown here.

Documentation/mmc/mmc-dev-attrs.txt+0−77

This diff is large: its 78 lines aren’t shown here.

Documentation/mmc/mmc-dev-parts.txt+0−40

This diff is large: its 41 lines aren’t shown here.

Documentation/mmc/mmc-tools.txt+0−34

This diff is large: its 35 lines aren’t shown here.

Documentation/mtd/intel-spi.txt+0−88

This diff is large: its 89 lines aren’t shown here.

Documentation/mtd/nand_ecc.txt+0−714

This diff is large: its 715 lines aren’t shown here.

Documentation/mtd/spi-nor.txt+0−65

This diff is large: its 66 lines aren’t shown here.

Documentation/namespaces/compatibility-list.txt+0−39

This diff is large: its 40 lines aren’t shown here.

Documentation/namespaces/resource-control.txt+0−14

This diff is large: its 15 lines aren’t shown here.

Documentation/netlabel/cipso_ipv4.rst+56−0

This diff is large: its 57 lines aren’t shown here.

Documentation/netlabel/cipso_ipv4.txt+0−49

This diff is large: its 50 lines aren’t shown here.

Documentation/netlabel/draft_ietf.rst+5−0

This diff is large: its 6 lines aren’t shown here.

Documentation/netlabel/index.rst+21−0

This diff is large: its 22 lines aren’t shown here.

Documentation/netlabel/introduction.rst+52−0

This diff is large: its 53 lines aren’t shown here.

Documentation/netlabel/introduction.txt+0−46

This diff is large: its 47 lines aren’t shown here.

Documentation/netlabel/lsm_interface.rst+53−0

This diff is large: its 54 lines aren’t shown here.

Documentation/netlabel/lsm_interface.txt+0−47

This diff is large: its 48 lines aren’t shown here.

Documentation/networking/af_xdp.rst+19−5

This diff is large: its 44 lines aren’t shown here.

Documentation/networking/bonding.txt+13−3

This diff is large: its 30 lines aren’t shown here.

Documentation/networking/conf.py+0−10

This diff is large: its 11 lines aren’t shown here.

Documentation/networking/device_drivers/amazon/ena.txt+4−1

This diff is large: its 24 lines aren’t shown here.

Documentation/networking/device_drivers/aquantia/atlantic.txt+439−0

This diff is large: its 440 lines aren’t shown here.

Documentation/networking/device_drivers/freescale/dpaa2/dpio-driver.rst+2−2

This diff is large: its 18 lines aren’t shown here.

Documentation/networking/device_drivers/google/gve.rst+123−0

This diff is large: its 124 lines aren’t shown here.

Documentation/networking/device_drivers/index.rst+2−0

This diff is large: its 9 lines aren’t shown here.

Documentation/networking/device_drivers/mellanox/mlx5.rst+192−0

This diff is large: its 193 lines aren’t shown here.

Documentation/networking/dsa/b53.rst+183−0

This diff is large: its 184 lines aren’t shown here.

Documentation/networking/dsa/configuration.rst+292−0

This diff is large: its 293 lines aren’t shown here.

Documentation/networking/dsa/dsa.rst+2−2

This diff is large: its 18 lines aren’t shown here.

Documentation/networking/dsa/index.rst+2−0

This diff is large: its 9 lines aren’t shown here.

Documentation/networking/dsa/sja1105.rst+3−3

This diff is large: its 17 lines aren’t shown here.

Documentation/networking/ip-sysctl.txt+56−6

This diff is large: its 114 lines aren’t shown here.

Documentation/networking/mpls-sysctl.txt+1−1

This diff is large: its 9 lines aren’t shown here.

Documentation/networking/phy.rst+44−1

This diff is large: its 59 lines aren’t shown here.

Documentation/networking/rds.txt+1−1

This diff is large: its 9 lines aren’t shown here.

Documentation/networking/sfp-phylink.rst+4−1

This diff is large: its 20 lines aren’t shown here.

Documentation/networking/timestamping.txt+1−1

This diff is large: its 9 lines aren’t shown here.

Documentation/networking/tls-offload.rst+53−20

This diff is large: its 112 lines aren’t shown here.

Documentation/nfc/nfc-hci.txt+0−290

This diff is large: its 291 lines aren’t shown here.

Documentation/nfc/nfc-pn544.txt+0−32

This diff is large: its 33 lines aren’t shown here.

Documentation/ntb.txt+0−236

This diff is large: its 237 lines aren’t shown here.

Documentation/nvdimm/btt.txt+0−273

This diff is large: its 274 lines aren’t shown here.

Documentation/nvdimm/nvdimm.txt+0−815

This diff is large: its 816 lines aren’t shown here.

Documentation/nvdimm/security.txt+0−141

This diff is large: its 142 lines aren’t shown here.

Documentation/nvmem/nvmem.txt+0−183

This diff is large: its 184 lines aren’t shown here.

Documentation/pcmcia/devicetable.rst+37−0

This diff is large: its 38 lines aren’t shown here.

Documentation/pcmcia/devicetable.txt+0−33

This diff is large: its 34 lines aren’t shown here.

Documentation/pcmcia/driver-changes.rst+160−0

This diff is large: its 161 lines aren’t shown here.

Documentation/pcmcia/driver-changes.txt+0−149

This diff is large: its 150 lines aren’t shown here.

Documentation/pcmcia/driver.rst+30−0

This diff is large: its 31 lines aren’t shown here.

Documentation/pcmcia/driver.txt+0−30

This diff is large: its 31 lines aren’t shown here.

Documentation/pcmcia/index.rst+20−0

This diff is large: its 21 lines aren’t shown here.

Documentation/pcmcia/locking.rst+133−0

This diff is large: its 134 lines aren’t shown here.

Documentation/pcmcia/locking.txt+0−118

This diff is large: its 119 lines aren’t shown here.

Documentation/perf/arm-ccn.txt+0−59

This diff is large: its 60 lines aren’t shown here.

Documentation/perf/arm_dsu_pmu.txt+0−28

This diff is large: its 29 lines aren’t shown here.

Documentation/perf/hisi-pmu.txt+0−53

This diff is large: its 54 lines aren’t shown here.

Documentation/perf/qcom_l2_pmu.txt+0−38

This diff is large: its 39 lines aren’t shown here.

Documentation/perf/qcom_l3_pmu.txt+0−25

This diff is large: its 26 lines aren’t shown here.

Documentation/perf/thunderx2-pmu.txt+0−41

This diff is large: its 42 lines aren’t shown here.

Documentation/perf/xgene-pmu.txt+0−48

This diff is large: its 49 lines aren’t shown here.

Documentation/phy.txt+0−197

This diff is large: its 198 lines aren’t shown here.

Documentation/phy/samsung-usb2.txt+0−135

This diff is large: its 136 lines aren’t shown here.

Documentation/pi-futex.txt+1−1

This diff is large: its 6 lines aren’t shown here.

Documentation/platform/x86-laptop-drivers.txt+0−18

This diff is large: its 19 lines aren’t shown here.

Documentation/power/apm-acpi.rst+36−0

This diff is large: its 37 lines aren’t shown here.

Documentation/power/apm-acpi.txt+0−32

This diff is large: its 33 lines aren’t shown here.

Documentation/power/basic-pm-debugging.rst+269−0

This diff is large: its 270 lines aren’t shown here.

Documentation/power/basic-pm-debugging.txt+0−254

This diff is large: its 255 lines aren’t shown here.

Documentation/power/charger-manager.rst+205−0

This diff is large: its 206 lines aren’t shown here.

Documentation/power/charger-manager.txt+0−200

This diff is large: its 201 lines aren’t shown here.

Documentation/power/drivers-testing.rst+51−0

This diff is large: its 52 lines aren’t shown here.

Documentation/power/drivers-testing.txt+0−46

This diff is large: its 47 lines aren’t shown here.

Documentation/power/energy-model.rst+147−0

This diff is large: its 148 lines aren’t shown here.

Documentation/power/energy-model.txt+0−144

This diff is large: its 145 lines aren’t shown here.

Documentation/power/freezing-of-tasks.rst+244−0

This diff is large: its 245 lines aren’t shown here.

Documentation/power/freezing-of-tasks.txt+0−231

This diff is large: its 232 lines aren’t shown here.

Documentation/power/index.rst+46−0

This diff is large: its 47 lines aren’t shown here.

Documentation/power/interface.rst+79−0

This diff is large: its 80 lines aren’t shown here.

Documentation/power/interface.txt+0−77

This diff is large: its 78 lines aren’t shown here.

Documentation/power/opp.rst+379−0

This diff is large: its 380 lines aren’t shown here.

Documentation/power/opp.txt+0−342

This diff is large: its 343 lines aren’t shown here.

Documentation/power/pci.rst+1135−0

This diff is large: its 1136 lines aren’t shown here.

Documentation/power/pci.txt+0−1094

This diff is large: its 1095 lines aren’t shown here.

Documentation/power/pm_qos_interface.rst+227−0

This diff is large: its 228 lines aren’t shown here.

Documentation/power/pm_qos_interface.txt+0−212

This diff is large: its 213 lines aren’t shown here.

Documentation/power/power_supply_class.rst+288−0

This diff is large: its 289 lines aren’t shown here.

Documentation/power/power_supply_class.txt+0−231

This diff is large: its 232 lines aren’t shown here.

Documentation/power/powercap/powercap.rst+257−0

This diff is large: its 258 lines aren’t shown here.

Documentation/power/powercap/powercap.txt+0−236

This diff is large: its 237 lines aren’t shown here.

Documentation/power/regulator/consumer.rst+229−0

This diff is large: its 230 lines aren’t shown here.

Documentation/power/regulator/consumer.txt+0−218

This diff is large: its 219 lines aren’t shown here.

Documentation/power/regulator/design.rst+38−0

This diff is large: its 39 lines aren’t shown here.

Documentation/power/regulator/design.txt+0−33

This diff is large: its 34 lines aren’t shown here.

Documentation/power/regulator/machine.rst+97−0

This diff is large: its 98 lines aren’t shown here.

Documentation/power/regulator/machine.txt+0−96

This diff is large: its 97 lines aren’t shown here.

Documentation/power/regulator/overview.rst+178−0

This diff is large: its 179 lines aren’t shown here.

Documentation/power/regulator/overview.txt+0−171

This diff is large: its 172 lines aren’t shown here.

Documentation/power/regulator/regulator.rst+32−0

This diff is large: its 33 lines aren’t shown here.

Documentation/power/regulator/regulator.txt+0−30

This diff is large: its 31 lines aren’t shown here.

Documentation/power/runtime_pm.rst+940−0

This diff is large: its 941 lines aren’t shown here.

Documentation/power/runtime_pm.txt+0−928

This diff is large: its 929 lines aren’t shown here.

Documentation/power/s2ram.rst+87−0

This diff is large: its 88 lines aren’t shown here.

Documentation/power/s2ram.txt+0−85

This diff is large: its 86 lines aren’t shown here.

Documentation/power/suspend-and-cpuhotplug.rst+286−0

This diff is large: its 287 lines aren’t shown here.

Documentation/power/suspend-and-cpuhotplug.txt+0−274

This diff is large: its 275 lines aren’t shown here.

Documentation/power/suspend-and-interrupts.rst+137−0

This diff is large: its 138 lines aren’t shown here.

Documentation/power/suspend-and-interrupts.txt+0−135

This diff is large: its 136 lines aren’t shown here.

Documentation/power/swsusp-and-swap-files.rst+63−0

This diff is large: its 64 lines aren’t shown here.

Documentation/power/swsusp-and-swap-files.txt+0−60

This diff is large: its 61 lines aren’t shown here.

Documentation/power/swsusp-dmcrypt.rst+140−0

This diff is large: its 141 lines aren’t shown here.

Documentation/power/swsusp-dmcrypt.txt+0−138

This diff is large: its 139 lines aren’t shown here.

Documentation/power/swsusp.rst+501−0

This diff is large: its 502 lines aren’t shown here.

Documentation/power/swsusp.txt+0−446

This diff is large: its 447 lines aren’t shown here.

Documentation/power/tricks.rst+29−0

This diff is large: its 30 lines aren’t shown here.

Documentation/power/tricks.txt+0−27

This diff is large: its 28 lines aren’t shown here.

Documentation/power/userland-swsusp.rst+191−0

This diff is large: its 192 lines aren’t shown here.

Documentation/power/userland-swsusp.txt+0−170

This diff is large: its 171 lines aren’t shown here.

Documentation/power/video.rst+213−0

This diff is large: its 214 lines aren’t shown here.

Documentation/power/video.txt+0−185

This diff is large: its 186 lines aren’t shown here.

Documentation/powerpc/DAWR-POWER9.txt+0−90

This diff is large: its 91 lines aren’t shown here.

Documentation/powerpc/bootwrapper.rst+155−0

This diff is large: its 156 lines aren’t shown here.

Documentation/powerpc/bootwrapper.txt+0−141

This diff is large: its 142 lines aren’t shown here.

Documentation/powerpc/cpu_families.rst+222−0

This diff is large: its 223 lines aren’t shown here.

Documentation/powerpc/cpu_families.txt+0−221

This diff is large: its 222 lines aren’t shown here.

Documentation/powerpc/cpu_features.rst+60−0

This diff is large: its 61 lines aren’t shown here.

Documentation/powerpc/cpu_features.txt+0−56

This diff is large: its 57 lines aren’t shown here.

Documentation/powerpc/cxl.rst+467−0

This diff is large: its 468 lines aren’t shown here.

Documentation/powerpc/cxl.txt+0−449

This diff is large: its 450 lines aren’t shown here.

Documentation/powerpc/cxlflash.rst+433−0

This diff is large: its 434 lines aren’t shown here.

Documentation/powerpc/cxlflash.txt+0−429

This diff is large: its 430 lines aren’t shown here.

Documentation/powerpc/dawr-power9.rst+93−0

This diff is large: its 94 lines aren’t shown here.

Documentation/powerpc/dscr.rst+87−0

This diff is large: its 88 lines aren’t shown here.

Documentation/powerpc/dscr.txt+0−83

This diff is large: its 84 lines aren’t shown here.

Documentation/powerpc/eeh-pci-error-recovery.rst+336−0

This diff is large: its 337 lines aren’t shown here.

Documentation/powerpc/eeh-pci-error-recovery.txt+0−334

This diff is large: its 335 lines aren’t shown here.

Documentation/powerpc/firmware-assisted-dump.rst+301−0

This diff is large: its 302 lines aren’t shown here.

Documentation/powerpc/firmware-assisted-dump.txt+0−292

This diff is large: its 293 lines aren’t shown here.

Documentation/powerpc/hvcs.rst+581−0

This diff is large: its 582 lines aren’t shown here.

Documentation/powerpc/hvcs.txt+0−567

This diff is large: its 568 lines aren’t shown here.

Documentation/powerpc/index.rst+34−0

This diff is large: its 35 lines aren’t shown here.

Documentation/powerpc/isa-versions.rst+7−6

This diff is large: its 42 lines aren’t shown here.

Documentation/powerpc/mpc52xx.rst+43−0

This diff is large: its 44 lines aren’t shown here.

Documentation/powerpc/mpc52xx.txt+0−39

This diff is large: its 40 lines aren’t shown here.

Documentation/powerpc/pci_iov_resource_on_powernv.rst+312−0

This diff is large: its 313 lines aren’t shown here.

Documentation/powerpc/pci_iov_resource_on_powernv.txt+0−301

This diff is large: its 302 lines aren’t shown here.

Documentation/powerpc/pmu-ebb.rst+138−0

This diff is large: its 139 lines aren’t shown here.

Documentation/powerpc/pmu-ebb.txt+0−137

This diff is large: its 138 lines aren’t shown here.

Documentation/powerpc/ptrace.rst+156−0

This diff is large: its 157 lines aren’t shown here.

Documentation/powerpc/ptrace.txt+0−151

This diff is large: its 152 lines aren’t shown here.

Documentation/powerpc/qe_firmware.rst+296−0

This diff is large: its 297 lines aren’t shown here.

Documentation/powerpc/qe_firmware.txt+0−295

This diff is large: its 296 lines aren’t shown here.

Documentation/powerpc/syscall64-abi.rst+110−0

This diff is large: its 111 lines aren’t shown here.

Documentation/powerpc/syscall64-abi.txt+0−105

This diff is large: its 106 lines aren’t shown here.

Documentation/powerpc/transactional_memory.rst+247−0

This diff is large: its 248 lines aren’t shown here.

Documentation/powerpc/transactional_memory.txt+0−244

This diff is large: its 245 lines aren’t shown here.

Documentation/powerpc/vcpudispatch_stats.txt+68−0

This diff is large: its 69 lines aren’t shown here.

Documentation/pps/pps.txt+0−239

This diff is large: its 240 lines aren’t shown here.

Documentation/process/4.Coding.rst+1−1

This diff is large: its 9 lines aren’t shown here.

Documentation/process/changes.rst+4−18

This diff is large: its 63 lines aren’t shown here.

Documentation/process/coding-style.rst+1−1

This diff is large: its 9 lines aren’t shown here.

Documentation/process/conf.py+0−10

This diff is large: its 11 lines aren’t shown here.

Documentation/process/deprecated.rst+14−0

This diff is large: its 18 lines aren’t shown here.

Documentation/process/maintainer-pgp-guide.rst+17−14

This diff is large: its 58 lines aren’t shown here.

Documentation/process/submit-checklist.rst+2−2

This diff is large: its 18 lines aren’t shown here.

Documentation/process/submitting-drivers.rst+1−1

This diff is large: its 9 lines aren’t shown here.

Documentation/pti/pti_intel_mid.txt+0−99

This diff is large: its 100 lines aren’t shown here.

Documentation/ptp/ptp.txt+0−86

This diff is large: its 87 lines aren’t shown here.

Documentation/pwm.txt+0−158

This diff is large: its 159 lines aren’t shown here.

Documentation/rapidio/mport_cdev.txt+0−107

This diff is large: its 108 lines aren’t shown here.

Documentation/rapidio/rapidio.txt+0−351

This diff is large: its 352 lines aren’t shown here.

Documentation/rapidio/rio_cm.txt+0−119

This diff is large: its 120 lines aren’t shown here.

Documentation/rapidio/sysfs.txt+0−3

This diff is large: its 4 lines aren’t shown here.

Documentation/rapidio/tsi721.txt+0−97

This diff is large: its 98 lines aren’t shown here.

Documentation/rbtree.txt+3−3

This diff is large: its 25 lines aren’t shown here.

Documentation/remoteproc.txt+9−5

This diff is large: its 28 lines aren’t shown here.

Documentation/riscv/boot-image-header.txt+50−0

This diff is large: its 51 lines aren’t shown here.

Documentation/riscv/index.rst+15−0

This diff is large: its 16 lines aren’t shown here.

Documentation/riscv/pmu.rst+255−0

This diff is large: its 256 lines aren’t shown here.

Documentation/riscv/pmu.txt+0−249

This diff is large: its 250 lines aren’t shown here.

Documentation/s390/3270.rst+298−0

This diff is large: its 299 lines aren’t shown here.

Documentation/s390/3270.txt+0−271

This diff is large: its 272 lines aren’t shown here.

Documentation/s390/CommonIO+0−125

This diff is large: its 126 lines aren’t shown here.

Documentation/s390/DASD+0−73

This diff is large: its 74 lines aren’t shown here.

Documentation/s390/Debugging390.txt+0−2142

This diff is large: its 2143 lines aren’t shown here.

Documentation/s390/cds.rst+530−0

This diff is large: its 531 lines aren’t shown here.

Documentation/s390/cds.txt+0−472

This diff is large: its 473 lines aren’t shown here.

Documentation/s390/common_io.rst+140−0

This diff is large: its 141 lines aren’t shown here.

Documentation/s390/dasd.rst+84−0

This diff is large: its 85 lines aren’t shown here.

Documentation/s390/debugging390.rst+2613−0

This diff is large: its 2614 lines aren’t shown here.

Documentation/s390/driver-model.rst+328−0

This diff is large: its 329 lines aren’t shown here.

Documentation/s390/driver-model.txt+0−287

This diff is large: its 288 lines aren’t shown here.

Documentation/s390/index.rst+28−0

This diff is large: its 29 lines aren’t shown here.

Documentation/s390/monreader.rst+212−0

This diff is large: its 213 lines aren’t shown here.

Documentation/s390/monreader.txt+0−197

This diff is large: its 198 lines aren’t shown here.

Documentation/s390/qeth.rst+64−0

This diff is large: its 65 lines aren’t shown here.

Documentation/s390/qeth.txt+0−50

This diff is large: its 51 lines aren’t shown here.

Documentation/s390/s390dbf.rst+487−0

This diff is large: its 488 lines aren’t shown here.

Documentation/s390/s390dbf.txt+0−667

This diff is large: its 668 lines aren’t shown here.

Documentation/s390/text_files.rst+11−0

This diff is large: its 12 lines aren’t shown here.

Documentation/s390/vfio-ap.rst+866−0

This diff is large: its 867 lines aren’t shown here.

Documentation/s390/vfio-ap.txt+0−837

This diff is large: its 838 lines aren’t shown here.

Documentation/s390/vfio-ccw.rst+351−0

This diff is large: its 352 lines aren’t shown here.

Documentation/s390/vfio-ccw.txt+0−300

This diff is large: its 301 lines aren’t shown here.

Documentation/s390/zfcpdump.rst+50−0

This diff is large: its 51 lines aren’t shown here.

Documentation/s390/zfcpdump.txt+0−48

This diff is large: its 49 lines aren’t shown here.

Documentation/scheduler/completion.rst+293−0

This diff is large: its 294 lines aren’t shown here.

Documentation/scheduler/completion.txt+0−291

This diff is large: its 292 lines aren’t shown here.

Documentation/scheduler/index.rst+27−0

This diff is large: its 28 lines aren’t shown here.

Documentation/scheduler/sched-arch.rst+76−0

This diff is large: its 77 lines aren’t shown here.

Documentation/scheduler/sched-arch.txt+0−74

This diff is large: its 75 lines aren’t shown here.

Documentation/scheduler/sched-bwc.rst+128−0

This diff is large: its 129 lines aren’t shown here.

Documentation/scheduler/sched-bwc.txt+0−122

This diff is large: its 123 lines aren’t shown here.

Documentation/scheduler/sched-deadline.rst+888−0

This diff is large: its 889 lines aren’t shown here.

Documentation/scheduler/sched-deadline.txt+0−871

This diff is large: its 872 lines aren’t shown here.

Documentation/scheduler/sched-design-CFS.rst+249−0

This diff is large: its 250 lines aren’t shown here.

Documentation/scheduler/sched-design-CFS.txt+0−242

This diff is large: its 243 lines aren’t shown here.

Documentation/scheduler/sched-domains.rst+83−0

This diff is large: its 84 lines aren’t shown here.

Documentation/scheduler/sched-domains.txt+0−77

This diff is large: its 78 lines aren’t shown here.

Documentation/scheduler/sched-energy.rst+430−0

This diff is large: its 431 lines aren’t shown here.

This diff is larger than a page shows: the files after these aren’t listed. Clone the repository to see all of it.

Keyboard shortcuts

General

Show keyboard shortcuts
?
Focus the current search
/

Issues and pull requests

Open filters
f

Issues, pull requests and Inbox

Select next item
j↓
Select previous item
k↑
Open selected item
Enter
Dismiss filters or clear selection
Esc

Repository code

Go to file
t