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
30*.lz430*.lz4
31*.lzma31*.lzma
32*.lzo32*.lzo
33*.mod
33*.mod.c34*.mod.c
34*.o35*.o
35*.o.*36*.o.*
@@ -141,3 +142,6 @@ x509.genkey · 105 unmodified lines
141 142
142# Kdevelop4143# Kdevelop4
143*.kdev4144*.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
81Greg Kroah-Hartman <gregkh@suse.de>81Greg Kroah-Hartman <gregkh@suse.de>
82Greg Kroah-Hartman <greg@kroah.com>82Greg Kroah-Hartman <greg@kroah.com>
83Gregory CLEMENT <gregory.clement@bootlin.com> <gregory.clement@free-electrons.com>83Gregory CLEMENT <gregory.clement@bootlin.com> <gregory.clement@free-electrons.com>
84Hanjun Guo <guohanjun@huawei.com> <hanjun.guo@linaro.org>
84Henk Vergonet <Henk.Vergonet@gmail.com>85Henk Vergonet <Henk.Vergonet@gmail.com>
85Henrik Kretzschmar <henne@nachtwindheim.de>86Henrik Kretzschmar <henne@nachtwindheim.de>
86Henrik Rydberg <rydberg@bitmath.org>87Henrik Rydberg <rydberg@bitmath.org>
@@ -97,6 +98,7 @@ Jason Gunthorpe <jgg@ziepe.ca> <jgunthorpe@obsidianresearch.com> · 10 unmodified lines
97Javi Merino <javi.merino@kernel.org> <javi.merino@arm.com>98Javi Merino <javi.merino@kernel.org> <javi.merino@arm.com>
98<javier@osg.samsung.com> <javier.martinez@collabora.co.uk>99<javier@osg.samsung.com> <javier.martinez@collabora.co.uk>
99Jean Tourrilhes <jt@hpl.hp.com>100Jean Tourrilhes <jt@hpl.hp.com>
101<jean-philippe@linaro.org> <jean-philippe.brucker@arm.com>
100Jeff Garzik <jgarzik@pretzel.yyz.us>102Jeff Garzik <jgarzik@pretzel.yyz.us>
101Jeff Layton <jlayton@kernel.org> <jlayton@redhat.com>103Jeff Layton <jlayton@kernel.org> <jlayton@redhat.com>
102Jeff Layton <jlayton@kernel.org> <jlayton@poochiereds.net>104Jeff Layton <jlayton@kernel.org> <jlayton@poochiereds.net>
@@ -115,6 +117,7 @@ John Stultz <johnstul@us.ibm.com> · 12 unmodified lines
115Juha Yrjola <at solidboot.com>117Juha Yrjola <at solidboot.com>
116Juha Yrjola <juha.yrjola@nokia.com>118Juha Yrjola <juha.yrjola@nokia.com>
117Juha Yrjola <juha.yrjola@solidboot.com>119Juha Yrjola <juha.yrjola@solidboot.com>
120Julien Thierry <julien.thierry.kdev@gmail.com> <julien.thierry@arm.com>
118Kay Sievers <kay.sievers@vrfy.org>121Kay Sievers <kay.sievers@vrfy.org>
119Kenneth W Chen <kenneth.w.chen@intel.com>122Kenneth W Chen <kenneth.w.chen@intel.com>
120Konstantin Khlebnikov <koct9i@gmail.com> <k.khlebnikov@samsung.com>123Konstantin 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
131Li Yang <leoyang.li@nxp.com> <leo@zh-kernel.org>134Li Yang <leoyang.li@nxp.com> <leo@zh-kernel.org>
132Li Yang <leoyang.li@nxp.com> <leoli@freescale.com>135Li Yang <leoyang.li@nxp.com> <leoli@freescale.com>
133Maciej W. Rozycki <macro@mips.com> <macro@imgtec.com>136Maciej W. Rozycki <macro@mips.com> <macro@imgtec.com>
137Marc Zyngier <maz@kernel.org> <marc.zyngier@arm.com>
134Marcin Nowakowski <marcin.nowakowski@mips.com> <marcin.nowakowski@imgtec.com>138Marcin Nowakowski <marcin.nowakowski@mips.com> <marcin.nowakowski@imgtec.com>
135Mark Brown <broonie@sirena.org.uk>139Mark Brown <broonie@sirena.org.uk>
136Mark Yao <markyao0591@gmail.com> <mark.yao@rock-chips.com>140Mark 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
238Vladimir Davydov <vdavydov.dev@gmail.com> <vdavydov@virtuozzo.com>242Vladimir Davydov <vdavydov.dev@gmail.com> <vdavydov@virtuozzo.com>
239Vladimir Davydov <vdavydov.dev@gmail.com> <vdavydov@parallels.com>243Vladimir Davydov <vdavydov.dev@gmail.com> <vdavydov@parallels.com>
240Takashi YOSHII <takashi.yoshii.zj@renesas.com>244Takashi YOSHII <takashi.yoshii.zj@renesas.com>
245Will Deacon <will@kernel.org> <will.deacon@arm.com>
241Yakir Yang <kuankuan.y@gmail.com> <ykk@rock-chips.com>246Yakir Yang <kuankuan.y@gmail.com> <ykk@rock-chips.com>
242Yusuke Goda <goda.yusuke@renesas.com>247Yusuke Goda <goda.yusuke@renesas.com>
243Gustavo Padovan <gustavo@las.ic.unicamp.br>248Gustavo Padovan <gustavo@las.ic.unicamp.br>
CREDITS+2−3
@@ -1770,7 +1770,6 @@ S: USA · 1769 unmodified lines
1770 1770
1771N: Dave Jones1771N: Dave Jones
1772E: davej@codemonkey.org.uk1772E: davej@codemonkey.org.uk
1773W: http://www.codemonkey.org.uk
1774D: Assorted VIA x86 support.1773D: Assorted VIA x86 support.
1775D: 2.5 AGPGART overhaul.1774D: 2.5 AGPGART overhaul.
1776D: CPUFREQ maintenance.1775D: CPUFREQ maintenance.
@@ -1800,7 +1799,7 @@ S: 2300 Copenhagen S. · 23 unmodified lines
1800S: Denmark1799S: Denmark
1801 1800
1802N: Jozsef Kadlecsik1801N: Jozsef Kadlecsik
1803E: kadlec@blackhole.kfki.hu1802E: kadlec@netfilter.org
1804P: 1024D/470DB964 4CB3 1A05 713E 9BF7 FAC5 5809 DD8C B7B1 470D B9641803P: 1024D/470DB964 4CB3 1A05 713E 9BF7 FAC5 5809 DD8C B7B1 470D B964
1805D: netfilter: TCP window tracking code1804D: netfilter: TCP window tracking code
1806D: netfilter: raw table1805D: netfilter: raw table
@@ -3120,7 +3119,7 @@ S: France · 1313 unmodified lines
3120N: Rik van Riel3119N: Rik van Riel
3121E: riel@redhat.com3120E: riel@redhat.com
3122W: http://www.surriel.com/3121W: http://www.surriel.com/
3123D: Linux-MM site, Documentation/sysctl/*, swap/mm readaround3122D: Linux-MM site, Documentation/admin-guide/sysctl/*, swap/mm readaround
3124D: kswapd fixes, random kernel hacker, rmap VM,3123D: kswapd fixes, random kernel hacker, rmap VM,
3125D: nl.linux.org administrator, minor scheduler additions3124D: nl.linux.org administrator, minor scheduler additions
3126S: Red Hat Boston3125S: 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
5 press of a button.5 press of a button.
6 When read, this file returns the raw number of the actual cpi6 When read, this file returns the raw number of the actual cpi
7 setting reported by the mouse. This number has to be further7 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:
9 9
10 VALUE DPI10 VALUE DPI
11 1 40011 1 400
Documentation/ABI/obsolete/sysfs-gpio+1−1
@@ -11,7 +11,7 @@ Description: · 10 unmodified lines
11 Kernel code may export it for complete or partial access.11 Kernel code may export it for complete or partial access.
12 12
13 GPIOs are identified as they are inside the kernel, using integers in13 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.
15 15
16 /sys/class/gpio16 /sys/class/gpio
17 /export ... asks the kernel to export a GPIO to userspace17 /export ... asks the kernel to export a GPIO to userspace
Documentation/ABI/removed/sysfs-class-rfkill+1−1
@@ -1,6 +1,6 @@
1rfkill - radio frequency (RF) connector kill switch support1rfkill - radio frequency (RF) connector kill switch support
2 2
3For details to this subsystem look at Documentation/rfkill.txt.3For details to this subsystem look at Documentation/driver-api/rfkill.rst.
4 4
5What: /sys/class/rfkill/rfkill[0-9]+/claim5What: /sys/class/rfkill/rfkill[0-9]+/claim
6Date: 09-Jul-20076Date: 09-Jul-2007
Documentation/ABI/stable/sysfs-class-infiniband+0−17
@@ -423,23 +423,6 @@ Description: · 422 unmodified lines
423 (e.g. driver restart on the VM which owns the VF).423 (e.g. driver restart on the VM which owns the VF).
424 424
425 425
426sysfs interface for NetEffect RNIC Low-Level iWARP driver (nes)
427---------------------------------------------------------------
428
429What: /sys/class/infiniband/nesX/hw_rev
430What: /sys/class/infiniband/nesX/hca_type
431What: /sys/class/infiniband/nesX/board_id
432Date: Feb, 2008
433KernelVersion: v2.6.25
434Contact: linux-rdma@vger.kernel.org
435Description:
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
443sysfs interface for Chelsio T4/T5 RDMA driver (cxgb4)426sysfs interface for Chelsio T4/T5 RDMA driver (cxgb4)
444-----------------------------------------------------427-----------------------------------------------------
445 428
Documentation/ABI/stable/sysfs-class-rfkill+1−1
@@ -1,6 +1,6 @@
1rfkill - radio frequency (RF) connector kill switch support1rfkill - radio frequency (RF) connector kill switch support
2 2
3For details to this subsystem look at Documentation/rfkill.txt.3For details to this subsystem look at Documentation/driver-api/rfkill.rst.
4 4
5For the deprecated /sys/class/rfkill/*/claim knobs of this interface look in5For the deprecated /sys/class/rfkill/*/claim knobs of this interface look in
6Documentation/ABI/removed/sysfs-class-rfkill.6Documentation/ABI/removed/sysfs-class-rfkill.
Documentation/ABI/stable/sysfs-devices-node+1−1
@@ -61,7 +61,7 @@ Date: October 2002 · 60 unmodified lines
61Contact: Linux Memory Management list <linux-mm@kvack.org>61Contact: Linux Memory Management list <linux-mm@kvack.org>
62Description:62Description:
63 The node's hit/miss statistics, in units of pages.63 The node's hit/miss statistics, in units of pages.
64 See Documentation/numastat.txt64 See Documentation/admin-guide/numastat.rst
65 65
66What: /sys/devices/system/node/nodeX/distance66What: /sys/devices/system/node/nodeX/distance
67Date: October 200267Date: October 2002
Documentation/ABI/stable/sysfs-driver-mlxreg-io+39−26
@@ -1,5 +1,4 @@
1What: /sys/devices/platform/mlxplat/mlxreg-io/hwmon/hwmon*/1What: /sys/devices/platform/mlxplat/mlxreg-io/hwmon/hwmon*/asic_health
2 asic_health
3 2
4Date: June 20183Date: June 2018
5KernelVersion: 4.194KernelVersion: 4.19
@@ -9,9 +8,8 @@ Description: This file shows ASIC health status. The possible values are: · 3 unmodified lines
9 8
10 The files are read only.9 The files are read only.
11 10
12What: /sys/devices/platform/mlxplat/mlxreg-io/hwmon/hwmon*/11What: /sys/devices/platform/mlxplat/mlxreg-io/hwmon/hwmon*/cpld1_version
13 cpld1_version12What: /sys/devices/platform/mlxplat/mlxreg-io/hwmon/hwmon*/cpld2_version
14 cpld2_version
15Date: June 201813Date: June 2018
16KernelVersion: 4.1914KernelVersion: 4.19
17Contact: Vadim Pasternak <vadimpmellanox.com>15Contact: Vadim Pasternak <vadimpmellanox.com>
@@ -20,8 +18,7 @@ Description: These files show with which CPLD versions have been burned · 2 unmodified lines
20 18
21 The files are read only.19 The files are read only.
22 20
23What: /sys/devices/platform/mlxplat/mlxreg-io/hwmon/hwmon*/21What: /sys/devices/platform/mlxplat/mlxreg-io/hwmon/hwmon*/fan_dir
24 fan_dir
25 22
26Date: December 201823Date: December 2018
27KernelVersion: 5.024KernelVersion: 5.0
@@ -32,8 +29,7 @@ Description: This file shows the system fans direction: · 4 unmodified lines
32 29
33 The files are read only.30 The files are read only.
34 31
35What: /sys/devices/platform/mlxplat/mlxreg-io/hwmon/hwmon*/32What: /sys/devices/platform/mlxplat/mlxreg-io/hwmon/hwmon*/jtag_enable
36 jtag_enable
37 33
38Date: November 201834Date: November 2018
39KernelVersion: 5.035KernelVersion: 5.0
@@ -43,8 +39,7 @@ Description: These files show with which CPLD versions have been burned · 3 unmodified lines
43 39
44 The files are read only.40 The files are read only.
45 41
46What: /sys/devices/platform/mlxplat/mlxreg-io/hwmon/hwmon*/42What: /sys/devices/platform/mlxplat/mlxreg-io/hwmon/hwmon*/jtag_enable
47 jtag_enable
48 43
49Date: November 201844Date: November 2018
50KernelVersion: 5.045KernelVersion: 5.0
@@ -87,16 +82,15 @@ Description: These files allow asserting system power cycling, switching · 36 unmodified lines
87 82
88 The files are write only.83 The files are write only.
89 84
90What: /sys/devices/platform/mlxplat/mlxreg-io/hwmon/hwmon*/85What: /sys/devices/platform/mlxplat/mlxreg-io/hwmon/hwmon*/reset_aux_pwr_or_ref
91 reset_aux_pwr_or_ref86What: /sys/devices/platform/mlxplat/mlxreg-io/hwmon/hwmon*/reset_asic_thermal
92 reset_asic_thermal87What: /sys/devices/platform/mlxplat/mlxreg-io/hwmon/hwmon*/reset_hotswap_or_halt
93 reset_hotswap_or_halt88What: /sys/devices/platform/mlxplat/mlxreg-io/hwmon/hwmon*/reset_hotswap_or_wd
94 reset_hotswap_or_wd89What: /sys/devices/platform/mlxplat/mlxreg-io/hwmon/hwmon*/reset_fw_reset
95 reset_fw_reset90What: /sys/devices/platform/mlxplat/mlxreg-io/hwmon/hwmon*/reset_long_pb
96 reset_long_pb91What: /sys/devices/platform/mlxplat/mlxreg-io/hwmon/hwmon*/reset_main_pwr_fail
97 reset_main_pwr_fail92What: /sys/devices/platform/mlxplat/mlxreg-io/hwmon/hwmon*/reset_short_pb
98 reset_short_pb93What: /sys/devices/platform/mlxplat/mlxreg-io/hwmon/hwmon*/reset_sw_reset
99 reset_sw_reset
100Date: June 201894Date: June 2018
101KernelVersion: 4.1995KernelVersion: 4.19
102Contact: Vadim Pasternak <vadimpmellanox.com>96Contact: Vadim Pasternak <vadimpmellanox.com>
@@ -110,11 +104,10 @@ Description: These files show the system reset cause, as following: power · 7 unmodified lines
110 104
111 The files are read only.105 The files are read only.
112 106
113What: /sys/devices/platform/mlxplat/mlxreg-io/hwmon/hwmon*/107What: /sys/devices/platform/mlxplat/mlxreg-io/hwmon/hwmon*/reset_comex_pwr_fail
114 reset_comex_pwr_fail108What: /sys/devices/platform/mlxplat/mlxreg-io/hwmon/hwmon*/reset_from_comex
115 reset_from_comex109What: /sys/devices/platform/mlxplat/mlxreg-io/hwmon/hwmon*/reset_system
116 reset_system110What: /sys/devices/platform/mlxplat/mlxreg-io/hwmon/hwmon*/reset_voltmon_upgrade_fail
117 reset_voltmon_upgrade_fail
118 111
119Date: November 2018112Date: November 2018
120KernelVersion: 5.0113KernelVersion: 5.0
@@ -127,3 +120,23 @@ Description: These files show the system reset cause, as following: ComEx · 6 unmodified lines
127 the last reset cause.120 the last reset cause.
128 121
129 The files are read only.122 The files are read only.
123
124Date: June 2019
125KernelVersion: 5.3
126Contact: Vadim Pasternak <vadimpmellanox.com>
127Description: 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
137What: /sys/devices/platform/mlxplat/mlxreg-io/hwmon/hwmon*/reset_comex_thermal
138What: /sys/devices/platform/mlxplat/mlxreg-io/hwmon/hwmon*/reset_comex_wd
139What: /sys/devices/platform/mlxplat/mlxreg-io/hwmon/hwmon*/reset_from_asic
140What: /sys/devices/platform/mlxplat/mlxreg-io/hwmon/hwmon*/reset_reload_bios
141What: /sys/devices/platform/mlxplat/mlxreg-io/hwmon/hwmon*/reset_sff_wd
142What: /sys/devices/platform/mlxplat/mlxreg-io/hwmon/hwmon*/reset_swb_wd
Documentation/ABI/testing/debugfs-cec-error-inj+1−1
@@ -1,6 +1,6 @@
1What: /sys/kernel/debug/cec/*/error-inj1What: /sys/kernel/debug/cec/*/error-inj
2Date: March 20182Date: March 2018
3Contact: Hans Verkuil <hans.verkuil@cisco.com>3Contact: Hans Verkuil <hverkuil-cisco@xs4all.nl>
4Description:4Description:
5 5
6The CEC Framework allows for CEC error injection commands through6The CEC Framework allows for CEC error injection commands through
Documentation/ABI/testing/debugfs-cros-ec+56−0
@@ -0,0 +1,56 @@
1What: /sys/kernel/debug/<cros-ec-device>/console_log
2Date: September 2017
3KernelVersion: 4.13
4Description:
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
10What: /sys/kernel/debug/<cros-ec-device>/panicinfo
11Date: September 2017
12KernelVersion: 4.13
13Description:
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
18What: /sys/kernel/debug/<cros-ec-device>/pdinfo
19Date: June 2018
20KernelVersion: 4.17
21Description:
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
27What: /sys/kernel/debug/<cros-ec-device>/uptime
28Date: June 2019
29KernelVersion: 5.3
30Description:
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
36What: /sys/kernel/debug/<cros-ec-device>/last_resume_result
37Date: June 2019
38KernelVersion: 5.3
39Description:
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
3KernelVersion: 5.13KernelVersion: 5.1
4Contact: oded.gabbay@gmail.com4Contact: oded.gabbay@gmail.com
5Description: Sets the device address to be used for read or write through5Description: 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"
7 10
8What: /sys/kernel/debug/habanalabs/hl<n>/command_buffers11What: /sys/kernel/debug/habanalabs/hl<n>/command_buffers
9Date: Jan 201912Date: Jan 2019
@@ -33,10 +36,12 @@ Contact: oded.gabbay@gmail.com · 23 unmodified lines
33Description: Allows the root user to read or write directly through the36Description: Allows the root user to read or write directly through the
34 device's PCI bar. Writing to this file generates a write37 device's PCI bar. Writing to this file generates a write
35 transaction while reading from the file generates a read38 transaction while reading from the file generates a read
36 transcation. This custom interface is needed (instead of using39 transaction. This custom interface is needed (instead of using
37 the generic Linux user-space PCI mapping) because the DDR bar40 the generic Linux user-space PCI mapping) because the DDR bar
38 is very small compared to the DDR memory and only the driver can41 is very small compared to the DDR memory and only the driver can
39 move the bar before and after the transaction42 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
40 45
41What: /sys/kernel/debug/habanalabs/hl<n>/device46What: /sys/kernel/debug/habanalabs/hl<n>/device
42Date: Jan 201947Date: Jan 2019
@@ -46,6 +51,13 @@ Description: Enables the root user to set the device to specific state. · 3 unmodified lines
46 Valid values are "disable", "enable", "suspend", "resume".51 Valid values are "disable", "enable", "suspend", "resume".
47 User can read this property to see the valid values52 User can read this property to see the valid values
48 53
54What: /sys/kernel/debug/habanalabs/hl<n>/engines
55Date: Jul 2019
56KernelVersion: 5.3
57Contact: oded.gabbay@gmail.com
58Description: Displays the status registers values of the device engines and
59 their derived idle status
60
49What: /sys/kernel/debug/habanalabs/hl<n>/i2c_addr61What: /sys/kernel/debug/habanalabs/hl<n>/i2c_addr
50Date: Jan 201962Date: Jan 2019
51KernelVersion: 5.163KernelVersion: 5.1
Documentation/ABI/testing/debugfs-wilco-ec+7−9
@@ -23,11 +23,9 @@ Description: · 22 unmodified lines
23 23
24 For writing, bytes 0-1 indicate the message type, one of enum24 For writing, bytes 0-1 indicate the message type, one of enum
25 wilco_ec_msg_type. Byte 2+ consist of the data passed in the25 wilco_ec_msg_type. Byte 2+ consist of the data passed in the
26 request, starting at MBOX[0]26 request, starting at MBOX[0]. At least three bytes are required
27 27 for writing, two for the type and at least a single byte of
28 At least three bytes are required for writing, two for the type28 data.
29 and at least a single byte of data. Only the first
30 EC_MAILBOX_DATA_SIZE bytes of MBOX will be used.
31 29
32 Example:30 Example:
33 // Request EC info type 3 (EC firmware build date)31 // Request EC info type 3 (EC firmware build date)
@@ -40,7 +38,7 @@ Description: · 6 unmodified lines
40 $ cat /sys/kernel/debug/wilco_ec/raw38 $ cat /sys/kernel/debug/wilco_ec/raw
41 00 00 31 32 2f 32 31 2f 31 38 00 38 00 01 00 2f 00 ..12/21/18.8...39 00 00 31 32 2f 32 31 2f 31 38 00 38 00 01 00 2f 00 ..12/21/18.8...
42 40
43 Note that the first 32 bytes of the received MBOX[] will be41 Note that the first 16 bytes of the received MBOX[] will be
44 printed, even if some of the data is junk. It is up to you to42 printed, even if some of the data is junk, and skipping bytes
45 know how many of the first bytes of data are the actual43 17 to 32. It is up to you to know how many of the first bytes of
46 response.44 data are the actual response.
Documentation/ABI/testing/ima_policy+4−2
@@ -24,11 +24,11 @@ Description: · 23 unmodified lines
24 [euid=] [fowner=] [fsname=]]24 [euid=] [fowner=] [fsname=]]
25 lsm: [[subj_user=] [subj_role=] [subj_type=]25 lsm: [[subj_user=] [subj_role=] [subj_type=]
26 [obj_user=] [obj_role=] [obj_type=]]26 [obj_user=] [obj_role=] [obj_type=]]
27 option: [[appraise_type=]] [permit_directio]27 option: [[appraise_type=]] [template=] [permit_directio]
28
29 base: func:= [BPRM_CHECK][MMAP_CHECK][CREDS_CHECK][FILE_CHECK][MODULE_CHECK]28 base: func:= [BPRM_CHECK][MMAP_CHECK][CREDS_CHECK][FILE_CHECK][MODULE_CHECK]
30 [FIRMWARE_CHECK]29 [FIRMWARE_CHECK]
31 [KEXEC_KERNEL_CHECK] [KEXEC_INITRAMFS_CHECK]30 [KEXEC_KERNEL_CHECK] [KEXEC_INITRAMFS_CHECK]
31 [KEXEC_CMDLINE]
32 mask:= [[^]MAY_READ] [[^]MAY_WRITE] [[^]MAY_APPEND]32 mask:= [[^]MAY_READ] [[^]MAY_WRITE] [[^]MAY_APPEND]
33 [[^]MAY_EXEC]33 [[^]MAY_EXEC]
34 fsmagic:= hex value34 fsmagic:= hex value
@@ -38,6 +38,8 @@ Description: · 3 unmodified lines
38 fowner:= decimal value38 fowner:= decimal value
39 lsm: are LSM specific39 lsm: are LSM specific
40 option: appraise_type:= [imasig]40 option: appraise_type:= [imasig]
41 template:= name of a defined IMA template type
42 (eg, ima-ng). Only valid when action is "measure".
41 pcr:= decimal value43 pcr:= decimal value
42 44
43 default policy:45 default policy:
Documentation/ABI/testing/procfs-diskstats+1−1
@@ -29,4 +29,4 @@ Description: · 28 unmodified lines
29 17 - sectors discarded29 17 - sectors discarded
30 18 - time spent discarding30 18 - time spent discarding
31 31
32 For more details refer to Documentation/iostats.txt32 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
3Contact: Daniel Colascione <dancol@google.com>3Contact: Daniel Colascione <dancol@google.com>
4Description:4Description:
5 This file provides pre-summed memory information for a5 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,
7 except instead of an entry for each VMA in a process,7 except instead of an entry for each VMA in a process,
8 smaps_rollup has a single entry (tagged "[rollup]")8 smaps_rollup has a single entry (tagged "[rollup]")
9 for which each field is the sum of the corresponding9 for which each field is the sum of the corresponding
10 fields from all the maps in /proc/pid/smaps.10 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.
12 16
13 Typical output looks like this:17 Typical output looks like this:
14 18
15 00100000-ff709000 ---p 00000000 00:00 0 [rollup]19 00100000-ff709000 ---p 00000000 00:00 0 [rollup]
20 Size: 1192 kB
21 KernelPageSize: 4 kB
22 MMUPageSize: 4 kB
16 Rss: 884 kB23 Rss: 884 kB
17 Pss: 385 kB24 Pss: 385 kB
25 Pss_Anon: 301 kB
26 Pss_File: 80 kB
27 Pss_Shmem: 4 kB
18 Shared_Clean: 696 kB28 Shared_Clean: 696 kB
19 Shared_Dirty: 0 kB29 Shared_Dirty: 0 kB
20 Private_Clean: 120 kB30 Private_Clean: 120 kB
Documentation/ABI/testing/pstore+2−2
@@ -1,6 +1,6 @@
1Where: /sys/fs/pstore/... (or /dev/pstore/...)1What: /sys/fs/pstore/... (or /dev/pstore/...)
2Date: March 20112Date: March 2011
3Kernel Version: 2.6.393KernelVersion: 2.6.39
4Contact: tony.luck@intel.com4Contact: tony.luck@intel.com
5Description: Generic interface to platform dependent persistent storage.5Description: Generic interface to platform dependent persistent storage.
6 6
Documentation/ABI/testing/sysfs-block+1−1
@@ -15,7 +15,7 @@ Description: · 14 unmodified lines
15 9 - I/Os currently in progress15 9 - I/Os currently in progress
16 10 - time spent doing I/Os (ms)16 10 - time spent doing I/Os (ms)
17 11 - weighted time spent doing I/Os (ms)17 11 - weighted time spent doing I/Os (ms)
18 For more details refer Documentation/iostats.txt18 For more details refer Documentation/admin-guide/iostats.rst
19 19
20 20
21What: /sys/block/<disk>/<part>/stat21What: /sys/block/<disk>/<part>/stat
Documentation/ABI/testing/sysfs-block-device+1−1
@@ -45,7 +45,7 @@ Description: · 44 unmodified lines
45 - Values below -2 are rejected with -EINVAL45 - Values below -2 are rejected with -EINVAL
46 46
47 For more information, see47 For more information, see
48 Documentation/laptops/disk-shock-protection.txt48 Documentation/admin-guide/laptops/disk-shock-protection.rst
49 49
50 50
51What: /sys/block/*/device/ncq_prio_enable51What: /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
33 in sync with the values current in the channel subsystem).33 in sync with the values current in the channel subsystem).
34 Note: This is an I/O-subchannel specific attribute.34 Note: This is an I/O-subchannel specific attribute.
35Users: s390-tools, HAL35Users: s390-tools, HAL
36
37What: /sys/bus/css/devices/.../driver_override
38Date: June 2019
39Contact: Cornelia Huck <cohuck@redhat.com>
40 linux-s390@vger.kernel.org
41Description: 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 @@
1Where: /sys/bus/event_source/devices/<dev>/format1What: /sys/bus/event_source/devices/<dev>/format
2Date: January 20122Date: January 2012
3Kernel Version: 3.33KernelVersion: 3.3
4Contact: Jiri Olsa <jolsa@redhat.com>4Contact: Jiri Olsa <jolsa@redhat.com>
5Description:5Description:
6 Attribute group to describe the magic bits that go into6 Attribute group to describe the magic bits that go into
Documentation/ABI/testing/sysfs-bus-i2c-devices-hm6352+6−6
@@ -1,20 +1,20 @@
1Where: /sys/bus/i2c/devices/.../heading0_input1What: /sys/bus/i2c/devices/.../heading0_input
2Date: April 20102Date: April 2010
3Kernel Version: 2.6.36?3KernelVersion: 2.6.36?
4Contact: alan.cox@intel.com4Contact: alan.cox@intel.com
5Description: Reports the current heading from the compass as a floating5Description: Reports the current heading from the compass as a floating
6 point value in degrees.6 point value in degrees.
7 7
8Where: /sys/bus/i2c/devices/.../power_state8What: /sys/bus/i2c/devices/.../power_state
9Date: April 20109Date: April 2010
10Kernel Version: 2.6.36?10KernelVersion: 2.6.36?
11Contact: alan.cox@intel.com11Contact: alan.cox@intel.com
12Description: Sets the power state of the device. 0 sets the device into12Description: Sets the power state of the device. 0 sets the device into
13 sleep mode, 1 wakes it up.13 sleep mode, 1 wakes it up.
14 14
15Where: /sys/bus/i2c/devices/.../calibration15What: /sys/bus/i2c/devices/.../calibration
16Date: April 201016Date: April 2010
17Kernel Version: 2.6.36?17KernelVersion: 2.6.36?
18Contact: alan.cox@intel.com18Contact: alan.cox@intel.com
19Description: Sets the calibration on or off (1 = on, 0 = off). See the19Description: Sets the calibration on or off (1 = on, 0 = off). See the
20 chip data sheet.20 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
61KernelVersion: 2.6.3561KernelVersion: 2.6.35
62Contact: linux-iio@vger.kernel.org62Contact: linux-iio@vger.kernel.org
63Description:63Description:
64 When the internal sampling clock can only take a small64 When the internal sampling clock can only take a specific set of
65 discrete set of values, this file lists those available.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]"
66 69
67What: /sys/bus/iio/devices/iio:deviceX/oversampling_ratio70What: /sys/bus/iio/devices/iio:deviceX/oversampling_ratio
68KernelVersion: 2.6.3871KernelVersion: 2.6.38
Documentation/ABI/testing/sysfs-bus-iio-cros-ec+5−5
@@ -18,11 +18,11 @@ Description: · 17 unmodified lines
18 values are 'base' and 'lid'.18 values are 'base' and 'lid'.
19 19
20What: /sys/bus/iio/devices/iio:deviceX/id20What: /sys/bus/iio/devices/iio:deviceX/id
21Date: Septembre 201721Date: September 2017
22KernelVersion: 4.1422KernelVersion: 4.14
23Contact: linux-iio@vger.kernel.org23Contact: linux-iio@vger.kernel.org
24Description:24Description:
25 This attribute is exposed by the CrOS EC legacy accelerometer25 This attribute is exposed by the CrOS EC sensors driver and
26 driver and represents the sensor ID as exposed by the EC. This26 represents the sensor ID as exposed by the EC. This ID is used
27 ID is used by the Android sensor service hardware abstraction27 by the Android sensor service hardware abstraction layer (sensor
28 layer (sensor HAL) through the Android container on ChromeOS.28 HAL) through the Android container on ChromeOS.
Documentation/ABI/testing/sysfs-bus-iio-distance-srf08+2−2
@@ -1,4 +1,4 @@
1What /sys/bus/iio/devices/iio:deviceX/sensor_sensitivity1What: /sys/bus/iio/devices/iio:deviceX/sensor_sensitivity
2Date: January 20172Date: January 2017
3KernelVersion: 4.113KernelVersion: 4.11
4Contact: linux-iio@vger.kernel.org4Contact: linux-iio@vger.kernel.org
@@ -6,7 +6,7 @@ Description: · 1 unmodified line
6 Show or set the gain boost of the amp, from 0-31 range.6 Show or set the gain boost of the amp, from 0-31 range.
7 default 317 default 31
8 8
9What /sys/bus/iio/devices/iio:deviceX/sensor_max_range9What: /sys/bus/iio/devices/iio:deviceX/sensor_max_range
10Date: January 201710Date: January 2017
11KernelVersion: 4.1111KernelVersion: 4.11
12Contact: linux-iio@vger.kernel.org12Contact: linux-iio@vger.kernel.org
Documentation/ABI/testing/sysfs-bus-iio-frequency-adf4371+44−0
@@ -0,0 +1,44 @@
1What: /sys/bus/iio/devices/iio:deviceX/out_altvoltageY_frequency
2KernelVersion:
3Contact: linux-iio@vger.kernel.org
4Description:
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
26What: /sys/bus/iio/devices/iio:deviceX/out_altvoltageY_name
27KernelVersion:
28Contact: linux-iio@vger.kernel.org
29Description:
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
37What: /sys/bus/iio/devices/iio:deviceX/out_altvoltageY_powerdown
38KernelVersion:
39Contact: linux-iio@vger.kernel.org
40Description:
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 @@
1What /sys/bus/iio/devices/iio:deviceX/in_proximity_input1What: /sys/bus/iio/devices/iio:deviceX/in_proximity_input
2Date: March 20142Date: March 2014
3KernelVersion: 3.153KernelVersion: 3.15
4Contact: Matt Ranostay <matt.ranostay@konsulko.com>4Contact: Matt Ranostay <matt.ranostay@konsulko.com>
@@ -6,7 +6,7 @@ Description: · 1 unmodified line
6 Get the current distance in meters of storm (1km steps)6 Get the current distance in meters of storm (1km steps)
7 1000-40000 = distance in meters7 1000-40000 = distance in meters
8 8
9What /sys/bus/iio/devices/iio:deviceX/sensor_sensitivity9What: /sys/bus/iio/devices/iio:deviceX/sensor_sensitivity
10Date: March 201410Date: March 2014
11KernelVersion: 3.1511KernelVersion: 3.15
12Contact: Matt Ranostay <matt.ranostay@konsulko.com>12Contact: 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
9problematic endpoint itself (which may report all counters as 0 as it never9problematic endpoint itself (which may report all counters as 0 as it never
10saw any problems).10saw any problems).
11 11
12Where: /sys/bus/pci/devices/<dev>/aer_dev_correctable12What: /sys/bus/pci/devices/<dev>/aer_dev_correctable
13Date: July 201813Date: July 2018
14Kernel Version: 4.19.014KernelVersion: 4.19.0
15Contact: linux-pci@vger.kernel.org, rajatja@google.com15Contact: linux-pci@vger.kernel.org, rajatja@google.com
16Description: List of correctable errors seen and reported by this16Description: List of correctable errors seen and reported by this
17 PCI device using ERR_COR. Note that since multiple errors may17 PCI device using ERR_COR. Note that since multiple errors may
@@ -31,9 +31,9 @@ Header Log Overflow 0 · 13 unmodified lines
31TOTAL_ERR_COR 231TOTAL_ERR_COR 2
32-------------------------------------------------------------------------32-------------------------------------------------------------------------
33 33
34Where: /sys/bus/pci/devices/<dev>/aer_dev_fatal34What: /sys/bus/pci/devices/<dev>/aer_dev_fatal
35Date: July 201835Date: July 2018
36Kernel Version: 4.19.036KernelVersion: 4.19.0
37Contact: linux-pci@vger.kernel.org, rajatja@google.com37Contact: linux-pci@vger.kernel.org, rajatja@google.com
38Description: List of uncorrectable fatal errors seen and reported by this38Description: List of uncorrectable fatal errors seen and reported by this
39 PCI device using ERR_FATAL. Note that since multiple errors may39 PCI device using ERR_FATAL. Note that since multiple errors may
@@ -62,9 +62,9 @@ TLP Prefix Blocked Error 0 · 22 unmodified lines
62TOTAL_ERR_FATAL 062TOTAL_ERR_FATAL 0
63-------------------------------------------------------------------------63-------------------------------------------------------------------------
64 64
65Where: /sys/bus/pci/devices/<dev>/aer_dev_nonfatal65What: /sys/bus/pci/devices/<dev>/aer_dev_nonfatal
66Date: July 201866Date: July 2018
67Kernel Version: 4.19.067KernelVersion: 4.19.0
68Contact: linux-pci@vger.kernel.org, rajatja@google.com68Contact: linux-pci@vger.kernel.org, rajatja@google.com
69Description: List of uncorrectable nonfatal errors seen and reported by this69Description: List of uncorrectable nonfatal errors seen and reported by this
70 PCI device using ERR_NONFATAL. Note that since multiple errors70 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
103device, so these counters include them and are thus cumulative of all the error103device, so these counters include them and are thus cumulative of all the error
104messages on the PCI hierarchy originating at that root port.104messages on the PCI hierarchy originating at that root port.
105 105
106Where: /sys/bus/pci/devices/<dev>/aer_stats/aer_rootport_total_err_cor106What: /sys/bus/pci/devices/<dev>/aer_stats/aer_rootport_total_err_cor
107Date: July 2018107Date: July 2018
108Kernel Version: 4.19.0108KernelVersion: 4.19.0
109Contact: linux-pci@vger.kernel.org, rajatja@google.com109Contact: linux-pci@vger.kernel.org, rajatja@google.com
110Description: Total number of ERR_COR messages reported to rootport.110Description: Total number of ERR_COR messages reported to rootport.
111 111
112Where: /sys/bus/pci/devices/<dev>/aer_stats/aer_rootport_total_err_fatal112What: /sys/bus/pci/devices/<dev>/aer_stats/aer_rootport_total_err_fatal
113Date: July 2018113Date: July 2018
114Kernel Version: 4.19.0114KernelVersion: 4.19.0
115Contact: linux-pci@vger.kernel.org, rajatja@google.com115Contact: linux-pci@vger.kernel.org, rajatja@google.com
116Description: Total number of ERR_FATAL messages reported to rootport.116Description: Total number of ERR_FATAL messages reported to rootport.
117 117
118Where: /sys/bus/pci/devices/<dev>/aer_stats/aer_rootport_total_err_nonfatal118What: /sys/bus/pci/devices/<dev>/aer_stats/aer_rootport_total_err_nonfatal
119Date: July 2018119Date: July 2018
120Kernel Version: 4.19.0120KernelVersion: 4.19.0
121Contact: linux-pci@vger.kernel.org, rajatja@google.com121Contact: linux-pci@vger.kernel.org, rajatja@google.com
122Description: Total number of ERR_NONFATAL messages reported to rootport.122Description: Total number of ERR_NONFATAL messages reported to rootport.
Documentation/ABI/testing/sysfs-bus-pci-devices-cciss+22−22
@@ -1,68 +1,68 @@
1Where: /sys/bus/pci/devices/<dev>/ccissX/cXdY/model1What: /sys/bus/pci/devices/<dev>/ccissX/cXdY/model
2Date: March 20092Date: March 2009
3Kernel Version: 2.6.303KernelVersion: 2.6.30
4Contact: iss_storagedev@hp.com4Contact: iss_storagedev@hp.com
5Description: Displays the SCSI INQUIRY page 0 model for logical drive5Description: Displays the SCSI INQUIRY page 0 model for logical drive
6 Y of controller X.6 Y of controller X.
7 7
8Where: /sys/bus/pci/devices/<dev>/ccissX/cXdY/rev8What: /sys/bus/pci/devices/<dev>/ccissX/cXdY/rev
9Date: March 20099Date: March 2009
10Kernel Version: 2.6.3010KernelVersion: 2.6.30
11Contact: iss_storagedev@hp.com11Contact: iss_storagedev@hp.com
12Description: Displays the SCSI INQUIRY page 0 revision for logical12Description: Displays the SCSI INQUIRY page 0 revision for logical
13 drive Y of controller X.13 drive Y of controller X.
14 14
15Where: /sys/bus/pci/devices/<dev>/ccissX/cXdY/unique_id15What: /sys/bus/pci/devices/<dev>/ccissX/cXdY/unique_id
16Date: March 200916Date: March 2009
17Kernel Version: 2.6.3017KernelVersion: 2.6.30
18Contact: iss_storagedev@hp.com18Contact: iss_storagedev@hp.com
19Description: Displays the SCSI INQUIRY page 83 serial number for logical19Description: Displays the SCSI INQUIRY page 83 serial number for logical
20 drive Y of controller X.20 drive Y of controller X.
21 21
22Where: /sys/bus/pci/devices/<dev>/ccissX/cXdY/vendor22What: /sys/bus/pci/devices/<dev>/ccissX/cXdY/vendor
23Date: March 200923Date: March 2009
24Kernel Version: 2.6.3024KernelVersion: 2.6.30
25Contact: iss_storagedev@hp.com25Contact: iss_storagedev@hp.com
26Description: Displays the SCSI INQUIRY page 0 vendor for logical drive26Description: Displays the SCSI INQUIRY page 0 vendor for logical drive
27 Y of controller X.27 Y of controller X.
28 28
29Where: /sys/bus/pci/devices/<dev>/ccissX/cXdY/block:cciss!cXdY29What: /sys/bus/pci/devices/<dev>/ccissX/cXdY/block:cciss!cXdY
30Date: March 200930Date: March 2009
31Kernel Version: 2.6.3031KernelVersion: 2.6.30
32Contact: iss_storagedev@hp.com32Contact: iss_storagedev@hp.com
33Description: A symbolic link to /sys/block/cciss!cXdY33Description: A symbolic link to /sys/block/cciss!cXdY
34 34
35Where: /sys/bus/pci/devices/<dev>/ccissX/rescan35What: /sys/bus/pci/devices/<dev>/ccissX/rescan
36Date: August 200936Date: August 2009
37Kernel Version: 2.6.3137KernelVersion: 2.6.31
38Contact: iss_storagedev@hp.com38Contact: iss_storagedev@hp.com
39Description: Kicks of a rescan of the controller to discover logical39Description: Kicks of a rescan of the controller to discover logical
40 drive topology changes.40 drive topology changes.
41 41
42Where: /sys/bus/pci/devices/<dev>/ccissX/cXdY/lunid42What: /sys/bus/pci/devices/<dev>/ccissX/cXdY/lunid
43Date: August 200943Date: August 2009
44Kernel Version: 2.6.3144KernelVersion: 2.6.31
45Contact: iss_storagedev@hp.com45Contact: iss_storagedev@hp.com
46Description: Displays the 8-byte LUN ID used to address logical46Description: Displays the 8-byte LUN ID used to address logical
47 drive Y of controller X.47 drive Y of controller X.
48 48
49Where: /sys/bus/pci/devices/<dev>/ccissX/cXdY/raid_level49What: /sys/bus/pci/devices/<dev>/ccissX/cXdY/raid_level
50Date: August 200950Date: August 2009
51Kernel Version: 2.6.3151KernelVersion: 2.6.31
52Contact: iss_storagedev@hp.com52Contact: iss_storagedev@hp.com
53Description: Displays the RAID level of logical drive Y of53Description: Displays the RAID level of logical drive Y of
54 controller X.54 controller X.
55 55
56Where: /sys/bus/pci/devices/<dev>/ccissX/cXdY/usage_count56What: /sys/bus/pci/devices/<dev>/ccissX/cXdY/usage_count
57Date: August 200957Date: August 2009
58Kernel Version: 2.6.3158KernelVersion: 2.6.31
59Contact: iss_storagedev@hp.com59Contact: iss_storagedev@hp.com
60Description: Displays the usage count (number of opens) of logical drive Y60Description: Displays the usage count (number of opens) of logical drive Y
61 of controller X.61 of controller X.
62 62
63Where: /sys/bus/pci/devices/<dev>/ccissX/resettable63What: /sys/bus/pci/devices/<dev>/ccissX/resettable
64Date: February 201164Date: February 2011
65Kernel Version: 2.6.3865KernelVersion: 2.6.38
66Contact: iss_storagedev@hp.com66Contact: iss_storagedev@hp.com
67Description: Value of 1 indicates the controller can honor the reset_devices67Description: Value of 1 indicates the controller can honor the reset_devices
68 kernel parameter. Value of 0 indicates reset_devices cannot be68 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
71 a dump device, as kdump requires resetting the device in order71 a dump device, as kdump requires resetting the device in order
72 to work reliably.72 to work reliably.
73 73
74Where: /sys/bus/pci/devices/<dev>/ccissX/transport_mode74What: /sys/bus/pci/devices/<dev>/ccissX/transport_mode
75Date: July 201175Date: July 2011
76Kernel Version: 3.076KernelVersion: 3.0
77Contact: iss_storagedev@hp.com77Contact: iss_storagedev@hp.com
78Description: Value of "simple" indicates that the controller has been placed78Description: Value of "simple" indicates that the controller has been placed
79 in "simple mode". Value of "performant" indicates that the79 in "simple mode". Value of "performant" indicates that the
Documentation/ABI/testing/sysfs-bus-siox+11−11
@@ -1,6 +1,6 @@
1What: /sys/bus/siox/devices/siox-X/active1What: /sys/bus/siox/devices/siox-X/active
2KernelVersion: 4.162KernelVersion: 4.16
3Contact: Gavin Schenk <g.schenk@eckelmann.de>, Uwe Kleine-König <u.kleine-koenig@pengutronix.de>3Contact: Thorsten Scherer <t.scherer@eckelmann.de>, Uwe Kleine-König <u.kleine-koenig@pengutronix.de>
4Description:4Description:
5 On reading represents the current state of the bus. If it5 On reading represents the current state of the bus. If it
6 contains a "0" the bus is stopped and connected devices are6 contains a "0" the bus is stopped and connected devices are
@@ -12,7 +12,7 @@ Description: · 5 unmodified lines
12 12
13What: /sys/bus/siox/devices/siox-X/device_add13What: /sys/bus/siox/devices/siox-X/device_add
14KernelVersion: 4.1614KernelVersion: 4.16
15Contact: Gavin Schenk <g.schenk@eckelmann.de>, Uwe Kleine-König <u.kleine-koenig@pengutronix.de>15Contact: Thorsten Scherer <t.scherer@eckelmann.de>, Uwe Kleine-König <u.kleine-koenig@pengutronix.de>
16Description:16Description:
17 Write-only file. Write17 Write-only file. Write
18 18
@@ -27,13 +27,13 @@ Description: · 8 unmodified lines
27 27
28What: /sys/bus/siox/devices/siox-X/device_remove28What: /sys/bus/siox/devices/siox-X/device_remove
29KernelVersion: 4.1629KernelVersion: 4.16
30Contact: Gavin Schenk <g.schenk@eckelmann.de>, Uwe Kleine-König <u.kleine-koenig@pengutronix.de>30Contact: Thorsten Scherer <t.scherer@eckelmann.de>, Uwe Kleine-König <u.kleine-koenig@pengutronix.de>
31Description:31Description:
32 Write-only file. A single write removes the last device in the siox chain.32 Write-only file. A single write removes the last device in the siox chain.
33 33
34What: /sys/bus/siox/devices/siox-X/poll_interval_ns34What: /sys/bus/siox/devices/siox-X/poll_interval_ns
35KernelVersion: 4.1635KernelVersion: 4.16
36Contact: Gavin Schenk <g.schenk@eckelmann.de>, Uwe Kleine-König <u.kleine-koenig@pengutronix.de>36Contact: Thorsten Scherer <t.scherer@eckelmann.de>, Uwe Kleine-König <u.kleine-koenig@pengutronix.de>
37Description:37Description:
38 Defines the interval between two poll cycles in nano seconds.38 Defines the interval between two poll cycles in nano seconds.
39 Note this is rounded to jiffies on writing. On reading the current value39 Note this is rounded to jiffies on writing. On reading the current value
@@ -41,33 +41,33 @@ Description: · 1 unmodified line
41 41
42What: /sys/bus/siox/devices/siox-X-Y/connected42What: /sys/bus/siox/devices/siox-X-Y/connected
43KernelVersion: 4.1643KernelVersion: 4.16
44Contact: Gavin Schenk <g.schenk@eckelmann.de>, Uwe Kleine-König <u.kleine-koenig@pengutronix.de>44Contact: Thorsten Scherer <t.scherer@eckelmann.de>, Uwe Kleine-König <u.kleine-koenig@pengutronix.de>
45Description:45Description:
46 Read-only value. "0" means the Yth device on siox bus X isn't "connected" i.e.46 Read-only value. "0" means the Yth device on siox bus X isn't "connected" i.e.
47 communication with it is not ensured. "1" signals a working connection.47 communication with it is not ensured. "1" signals a working connection.
48 48
49What: /sys/bus/siox/devices/siox-X-Y/inbytes49What: /sys/bus/siox/devices/siox-X-Y/inbytes
50KernelVersion: 4.1650KernelVersion: 4.16
51Contact: Gavin Schenk <g.schenk@eckelmann.de>, Uwe Kleine-König <u.kleine-koenig@pengutronix.de>51Contact: Thorsten Scherer <t.scherer@eckelmann.de>, Uwe Kleine-König <u.kleine-koenig@pengutronix.de>
52Description:52Description:
53 Read-only value reporting the inbytes value provided to siox-X/device_add53 Read-only value reporting the inbytes value provided to siox-X/device_add
54 54
55What: /sys/bus/siox/devices/siox-X-Y/status_errors55What: /sys/bus/siox/devices/siox-X-Y/status_errors
56KernelVersion: 4.1656KernelVersion: 4.16
57Contact: Gavin Schenk <g.schenk@eckelmann.de>, Uwe Kleine-König <u.kleine-koenig@pengutronix.de>57Contact: Thorsten Scherer <t.scherer@eckelmann.de>, Uwe Kleine-König <u.kleine-koenig@pengutronix.de>
58Description:58Description:
59 Counts the number of time intervals when the read status byte doesn't yield the59 Counts the number of time intervals when the read status byte doesn't yield the
60 expected value.60 expected value.
61 61
62What: /sys/bus/siox/devices/siox-X-Y/type62What: /sys/bus/siox/devices/siox-X-Y/type
63KernelVersion: 4.1663KernelVersion: 4.16
64Contact: Gavin Schenk <g.schenk@eckelmann.de>, Uwe Kleine-König <u.kleine-koenig@pengutronix.de>64Contact: Thorsten Scherer <t.scherer@eckelmann.de>, Uwe Kleine-König <u.kleine-koenig@pengutronix.de>
65Description:65Description:
66 Read-only value reporting the type value provided to siox-X/device_add.66 Read-only value reporting the type value provided to siox-X/device_add.
67 67
68What: /sys/bus/siox/devices/siox-X-Y/watchdog68What: /sys/bus/siox/devices/siox-X-Y/watchdog
69KernelVersion: 4.1669KernelVersion: 4.16
70Contact: Gavin Schenk <g.schenk@eckelmann.de>, Uwe Kleine-König <u.kleine-koenig@pengutronix.de>70Contact: Thorsten Scherer <t.scherer@eckelmann.de>, Uwe Kleine-König <u.kleine-koenig@pengutronix.de>
71Description:71Description:
72 Read-only value reporting if the watchdog of the siox device is72 Read-only value reporting if the watchdog of the siox device is
73 active. "0" means the watchdog is not active and the device is expected to73 active. "0" means the watchdog is not active and the device is expected to
@@ -75,13 +75,13 @@ Description: · 1 unmodified line
75 75
76What: /sys/bus/siox/devices/siox-X-Y/watchdog_errors76What: /sys/bus/siox/devices/siox-X-Y/watchdog_errors
77KernelVersion: 4.1677KernelVersion: 4.16
78Contact: Gavin Schenk <g.schenk@eckelmann.de>, Uwe Kleine-König <u.kleine-koenig@pengutronix.de>78Contact: Thorsten Scherer <t.scherer@eckelmann.de>, Uwe Kleine-König <u.kleine-koenig@pengutronix.de>
79Description:79Description:
80 Read-only value reporting the number to time intervals when the80 Read-only value reporting the number to time intervals when the
81 watchdog was active.81 watchdog was active.
82 82
83What: /sys/bus/siox/devices/siox-X-Y/outbytes83What: /sys/bus/siox/devices/siox-X-Y/outbytes
84KernelVersion: 4.1684KernelVersion: 4.16
85Contact: Gavin Schenk <g.schenk@eckelmann.de>, Uwe Kleine-König <u.kleine-koenig@pengutronix.de>85Contact: Thorsten Scherer <t.scherer@eckelmann.de>, Uwe Kleine-König <u.kleine-koenig@pengutronix.de>
86Description:86Description:
87 Read-only value reporting the outbytes value provided to siox-X/device_add.87 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 @@
1Where: /sys/bus/usb/.../powered1What: /sys/bus/usb/.../powered
2Date: August 20082Date: August 2008
3Kernel Version: 2.6.263KernelVersion: 2.6.26
4Contact: Harrison Metzger <harrisonmetz@gmail.com>4Contact: Harrison Metzger <harrisonmetz@gmail.com>
5Description: Controls whether the device's display will powered.5Description: Controls whether the device's display will powered.
6 A value of 0 is off and a non-zero value is on.6 A value of 0 is off and a non-zero value is on.
7 7
8Where: /sys/bus/usb/.../mode_msb8What: /sys/bus/usb/.../mode_msb
9Where: /sys/bus/usb/.../mode_lsb9What: /sys/bus/usb/.../mode_lsb
10Date: August 200810Date: August 2008
11Kernel Version: 2.6.2611KernelVersion: 2.6.26
12Contact: Harrison Metzger <harrisonmetz@gmail.com>12Contact: Harrison Metzger <harrisonmetz@gmail.com>
13Description: Controls the devices display mode.13Description: Controls the devices display mode.
14 For a 6 character display the values are14 For a 6 character display the values are
@@ -16,24 +16,24 @@ Description: Controls the devices display mode. · 1 unmodified line
16 for an 8 character display the values are16 for an 8 character display the values are
17 MSB 0x08; LSB 0xFF.17 MSB 0x08; LSB 0xFF.
18 18
19Where: /sys/bus/usb/.../textmode19What: /sys/bus/usb/.../textmode
20Date: August 200820Date: August 2008
21Kernel Version: 2.6.2621KernelVersion: 2.6.26
22Contact: Harrison Metzger <harrisonmetz@gmail.com>22Contact: Harrison Metzger <harrisonmetz@gmail.com>
23Description: Controls the way the device interprets its text buffer.23Description: Controls the way the device interprets its text buffer.
24 raw: each character controls its segment manually24 raw: each character controls its segment manually
25 hex: each character is between 0-1525 hex: each character is between 0-15
26 ascii: each character is between '0'-'9' and 'A'-'F'.26 ascii: each character is between '0'-'9' and 'A'-'F'.
27 27
28Where: /sys/bus/usb/.../text28What: /sys/bus/usb/.../text
29Date: August 200829Date: August 2008
30Kernel Version: 2.6.2630KernelVersion: 2.6.26
31Contact: Harrison Metzger <harrisonmetz@gmail.com>31Contact: Harrison Metzger <harrisonmetz@gmail.com>
32Description: The text (or data) for the device to display32Description: The text (or data) for the device to display
33 33
34Where: /sys/bus/usb/.../decimals34What: /sys/bus/usb/.../decimals
35Date: August 200835Date: August 2008
36Kernel Version: 2.6.2636KernelVersion: 2.6.26
37Contact: Harrison Metzger <harrisonmetz@gmail.com>37Contact: Harrison Metzger <harrisonmetz@gmail.com>
38Description: Controls the decimal places on the device.38Description: Controls the decimal places on the device.
39 To set the nth decimal place, give this field39 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
4Contact: Johan Hovold <jhovold@gmail.com>4Contact: Johan Hovold <jhovold@gmail.com>
5Description:5Description:
6 Get the ALS output channel used as input in6 Get the ALS output channel used as input in
7 ALS-current-control mode (0, 1), where7 ALS-current-control mode (0, 1), where:
8 8
9 0 - out_current0 (backlight 0)9 0 - out_current0 (backlight 0)
10 1 - out_current1 (backlight 1)10 1 - out_current1 (backlight 1)
@@ -28,7 +28,7 @@ Date: April 2012 · 17 unmodified lines
28KernelVersion: 3.528KernelVersion: 3.5
29Contact: Johan Hovold <jhovold@gmail.com>29Contact: Johan Hovold <jhovold@gmail.com>
30Description:30Description:
31 Set the brightness-mapping mode (0, 1), where31 Set the brightness-mapping mode (0, 1), where:
32 32
33 0 - exponential mode33 0 - exponential mode
34 1 - linear mode34 1 - linear mode
@@ -38,7 +38,7 @@ Date: April 2012 · 3 unmodified lines
38KernelVersion: 3.538KernelVersion: 3.5
39Contact: Johan Hovold <jhovold@gmail.com>39Contact: Johan Hovold <jhovold@gmail.com>
40Description:40Description:
41 Set the PWM-input control mask (5 bits), where41 Set the PWM-input control mask (5 bits), where:
42 42
43 bit 5 - PWM-input enabled in Zone 443 bit 5 - PWM-input enabled in Zone 4
44 bit 4 - PWM-input enabled in Zone 344 bit 4 - PWM-input enabled in Zone 3
Documentation/ABI/testing/sysfs-class-cxl+3−3
@@ -1,6 +1,6 @@
1Note: Attributes that are shared between devices are stored in the directory1Please note that attributes that are shared between devices are stored in
2pointed to by the symlink device/.2the directory pointed to by the symlink device/.
3Example: The real path of the attribute /sys/class/cxl/afu0.0s/irqs_max is3For example, the real path of the attribute /sys/class/cxl/afu0.0s/irqs_max is
4/sys/class/cxl/afu0.0s/device/irqs_max, i.e. /sys/class/cxl/afu0.0/irqs_max.4/sys/class/cxl/afu0.0s/device/irqs_max, i.e. /sys/class/cxl/afu0.0/irqs_max.
5 5
6 6
Documentation/ABI/testing/sysfs-class-devfreq+1−1
@@ -47,7 +47,7 @@ Description: · 46 unmodified lines
47What: /sys/class/devfreq/.../trans_stat47What: /sys/class/devfreq/.../trans_stat
48Date: October 201248Date: October 2012
49Contact: MyungJoo Ham <myungjoo.ham@samsung.com>49Contact: MyungJoo Ham <myungjoo.ham@samsung.com>
50Descrtiption:50Description:
51 This ABI shows the statistics of devfreq behavior on a51 This ABI shows the statistics of devfreq behavior on a
52 specific device. It shows the time spent in each state and52 specific device. It shows the time spent in each state and
53 the number of transitions between states.53 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
4Contact: Johan Hovold <jhovold@gmail.com>4Contact: Johan Hovold <jhovold@gmail.com>
5Description:5Description:
6 Set the ALS output channel to use as input in6 Set the ALS output channel to use as input in
7 ALS-current-control mode (1, 2), where7 ALS-current-control mode (1, 2), where:
8 8
9 1 - out_current19 1 - out_current1
10 2 - out_current210 2 - out_current2
@@ -22,7 +22,7 @@ Date: April 2012 · 11 unmodified lines
22KernelVersion: 3.522KernelVersion: 3.5
23Contact: Johan Hovold <jhovold@gmail.com>23Contact: Johan Hovold <jhovold@gmail.com>
24Description:24Description:
25 Set the pattern generator fall and rise times (0..7), where25 Set the pattern generator fall and rise times (0..7), where:
26 26
27 0 - 2048 us27 0 - 2048 us
28 1 - 262 ms28 1 - 262 ms
@@ -45,7 +45,7 @@ Date: April 2012 · 16 unmodified lines
45KernelVersion: 3.545KernelVersion: 3.5
46Contact: Johan Hovold <jhovold@gmail.com>46Contact: Johan Hovold <jhovold@gmail.com>
47Description:47Description:
48 Set the brightness-mapping mode (0, 1), where48 Set the brightness-mapping mode (0, 1), where:
49 49
50 0 - exponential mode50 0 - exponential mode
51 1 - linear mode51 1 - linear mode
@@ -55,7 +55,7 @@ Date: April 2012 · 3 unmodified lines
55KernelVersion: 3.555KernelVersion: 3.5
56Contact: Johan Hovold <jhovold@gmail.com>56Contact: Johan Hovold <jhovold@gmail.com>
57Description:57Description:
58 Set the PWM-input control mask (5 bits), where58 Set the PWM-input control mask (5 bits), where:
59 59
60 bit 5 - PWM-input enabled in Zone 460 bit 5 - PWM-input enabled in Zone 4
61 bit 4 - PWM-input enabled in Zone 361 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
5Description:5Description:
6 Set the mode of LEDs. You should notice that changing the mode6 Set the mode of LEDs. You should notice that changing the mode
7 of one LED will update the mode of its two sibling devices as7 of one LED will update the mode of its two sibling devices as
8 well.8 well. Possible values are:
9 9
10 0 - normal10 0 - normal
11 1 - audio11 1 - audio
@@ -13,4 +13,4 @@ Description: · 1 unmodified line
13 13
14 Normal: LEDs are fully on when enabled14 Normal: LEDs are fully on when enabled
15 Audio: LEDs brightness depends on sound level15 Audio: LEDs brightness depends on sound level
16 Breathing: LEDs brightness varies at human breathing rate16 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
41 xgmii, moca, qsgmii, trgmii, 1000base-x, 2500base-x, rxaui,41 xgmii, moca, qsgmii, trgmii, 1000base-x, 2500base-x, rxaui,
42 xaui, 10gbase-kr, unknown42 xaui, 10gbase-kr, unknown
43 43
44What: /sys/class/mdio_bus/<bus>/<device>/phy_standalone
45Date: May 2019
46KernelVersion: 5.3
47Contact: netdev@vger.kernel.org
48Description:
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
29Description:29Description:
30 Unsigned integer.30 Unsigned integer.
31 31
32 Write a number ranging from 1 to 127 to add a qmap mux32 Write a number ranging from 1 to 254 to add a qmap mux
33 based network device, supported by recent Qualcomm based33 based network device, supported by recent Qualcomm based
34 modems.34 modems.
35 35
@@ -46,5 +46,5 @@ Contact: Bjørn Mork <bjorn@mork.no> · 10 unmodified lines
46Description:46Description:
47 Unsigned integer.47 Unsigned integer.
48 48
49 Write a number ranging from 1 to 127 to delete a previously49 Write a number ranging from 1 to 254 to delete a previously
50 created qmap mux based network device.50 created qmap mux based network device.
Documentation/ABI/testing/sysfs-class-power+32−0
@@ -376,10 +376,42 @@ Description: · 375 unmodified lines
376 supply. Normally this is configured based on the type of376 supply. Normally this is configured based on the type of
377 connection made (e.g. A configured SDP should output a maximum377 connection made (e.g. A configured SDP should output a maximum
378 of 500mA so the input current limit is set to the same value).378 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.
379 381
380 Access: Read, Write382 Access: Read, Write
381 Valid values: Represented in microamps383 Valid values: Represented in microamps
382 384
385What: /sys/class/power_supply/<supply_name>/input_voltage_limit
386Date: May 2019
387Contact: linux-pm@vger.kernel.org
388Description:
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
402What: /sys/class/power_supply/<supply_name>/input_power_limit
403Date: May 2019
404Contact: linux-pm@vger.kernel.org
405Description:
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
383What: /sys/class/power_supply/<supply_name>/online,415What: /sys/class/power_supply/<supply_name>/online,
384Date: May 2007416Date: May 2007
385Contact: linux-pm@vger.kernel.org417Contact: linux-pm@vger.kernel.org
Documentation/ABI/testing/sysfs-class-power-wilco+30−0
@@ -0,0 +1,30 @@
1What: /sys/class/power_supply/wilco-charger/charge_type
2Date: April 2019
3KernelVersion: 5.2
4Description:
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
18What: /sys/class/power_supply/wilco-charger/charge_control_start_threshold
19Date: April 2019
20KernelVersion: 5.2
21Description:
22 Used when charge_type="Custom", as described above. Measured in
23 percentages. The valid range is [50, 95].
24
25What: /sys/class/power_supply/wilco-charger/charge_control_end_threshold
26Date: April 2019
27KernelVersion: 5.2
28Description:
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
5Description:5Description:
6 The powercap/ class sub directory belongs to the power cap6 The powercap/ class sub directory belongs to the power cap
7 subsystem. Refer to7 subsystem. Refer to
8 Documentation/power/powercap/powercap.txt for details.8 Documentation/power/powercap/powercap.rst for details.
9 9
10What: /sys/class/powercap/<control type>10What: /sys/class/powercap/<control type>
11Date: September 201311Date: September 2013
@@ -147,6 +147,6 @@ What: /sys/class/powercap/.../<power zone>/enabled · 135 unmodified lines
147Date: September 2013147Date: September 2013
148KernelVersion: 3.13148KernelVersion: 3.13
149Contact: linux-pm@vger.kernel.org149Contact: linux-pm@vger.kernel.org
150Description150Description:
151 This allows to enable/disable power capping at power zone level.151 This allows to enable/disable power capping at power zone level.
152 This applies to current power zone and its children.152 This applies to current power zone and its children.
Documentation/ABI/testing/sysfs-class-switchtec+1−1
@@ -1,6 +1,6 @@
1switchtec - Microsemi Switchtec PCI Switch Management Endpoint1switchtec - Microsemi Switchtec PCI Switch Management Endpoint
2 2
3For details on this subsystem look at Documentation/switchtec.txt.3For details on this subsystem look at Documentation/driver-api/switchtec.rst.
4 4
5What: /sys/class/switchtec5What: /sys/class/switchtec
6Date: 05-Jan-20176Date: 05-Jan-2017
Documentation/ABI/testing/sysfs-class-uwb_rc+0−6
@@ -125,12 +125,6 @@ Description: · 124 unmodified lines
125 The EUI-48 of this device in colon separated hex125 The EUI-48 of this device in colon separated hex
126 octets.126 octets.
127 127
128What: /sys/class/uwb_rc/uwbN/<EUI-48>/BPST
129Date: July 2008
130KernelVersion: 2.6.27
131Contact: linux-usb@vger.kernel.org
132Description:
133
134What: /sys/class/uwb_rc/uwbN/<EUI-48>/IEs128What: /sys/class/uwb_rc/uwbN/<EUI-48>/IEs
135Date: July 2008129Date: July 2008
136KernelVersion: 2.6.27130KernelVersion: 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
34 present: cpus that have been identified as being present in34 present: cpus that have been identified as being present in
35 the system.35 the system.
36 36
37 See Documentation/cputopology.txt for more information.37 See Documentation/admin-guide/cputopology.rst for more information.
38 38
39 39
40What: /sys/devices/system/cpu/probe40What: /sys/devices/system/cpu/probe
@@ -103,7 +103,7 @@ Description: CPU topology files that describe a logical CPU's relationship · 62 unmodified lines
103 thread_siblings_list: human-readable list of cpu#'s hardware103 thread_siblings_list: human-readable list of cpu#'s hardware
104 threads within the same core as cpu#104 threads within the same core as cpu#
105 105
106 See Documentation/cputopology.txt for more information.106 See Documentation/admin-guide/cputopology.rst for more information.
107 107
108 108
109What: /sys/devices/system/cpu/cpuidle/current_driver109What: /sys/devices/system/cpu/cpuidle/current_driver
@@ -137,7 +137,8 @@ Description: Discover cpuidle policy and mechanism · 27 unmodified lines
137 current_governor: (RW) displays current idle policy. Users can137 current_governor: (RW) displays current idle policy. Users can
138 switch the governor at runtime by writing to this file.138 switch the governor at runtime by writing to this file.
139 139
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.
141 142
142 143
143What: /sys/devices/system/cpu/cpuX/cpuidle/stateN/name144What: /sys/devices/system/cpu/cpuX/cpuidle/stateN/name
@@ -538,3 +539,26 @@ Description: Intel Energy and Performance Bias Hint (EPB) · 394 unmodified lines
538 539
539 This attribute is present for all online CPUs supporting the540 This attribute is present for all online CPUs supporting the
540 Intel EPB feature.541 Intel EPB feature.
542
543What: /sys/devices/system/cpu/umwait_control
544 /sys/devices/system/cpu/umwait_control/enable_c02
545 /sys/devices/system/cpu/umwait_control/max_time
546Date: May 2019
547Contact: Linux kernel mailing list <linux-kernel@vger.kernel.org>
548Description: 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 @@
1What: /sys/bus/pci/drivers/altera-cvp/chkcfg1What: /sys/bus/pci/drivers/altera-cvp/chkcfg
2Date: May 20172Date: May 2017
3Kernel Version: 4.133KernelVersion: 4.13
4Contact: Anatolij Gustschin <agust@denx.de>4Contact: Anatolij Gustschin <agust@denx.de>
5Description:5Description:
6 Contains either 1 or 0 and controls if configuration6 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
62Date: Jan 201962Date: Jan 2019
63KernelVersion: 5.163KernelVersion: 5.1
64Contact: oded.gabbay@gmail.com64Contact: oded.gabbay@gmail.com
65Description: Allows the user to set the maximum clock frequency of the65Description: Allows the user to set the maximum clock frequency, in Hz, of
66 Interconnect fabric. Writes to this parameter affect the device66 the Interconnect fabric. Writes to this parameter affect the
67 only when the power management profile is set to "manual" mode.67 device only when the power management profile is set to "manual"
68 The device IC clock might be set to lower value then the68 mode. The device IC clock might be set to lower value than the
69 maximum. The user should read the ic_clk_curr to see the actual69 maximum. The user should read the ic_clk_curr to see the actual
70 frequency value of the IC70 frequency value of the IC. This property is valid only for the
71 Goya ASIC family
71 72
72What: /sys/class/habanalabs/hl<n>/ic_clk_curr73What: /sys/class/habanalabs/hl<n>/ic_clk_curr
73Date: Jan 201974Date: Jan 2019
74KernelVersion: 5.175KernelVersion: 5.1
75Contact: oded.gabbay@gmail.com76Contact: oded.gabbay@gmail.com
76Description: Displays the current clock frequency of the Interconnect fabric77Description: Displays the current clock frequency, in Hz, of the Interconnect
78 fabric. This property is valid only for the Goya ASIC family
77 79
78What: /sys/class/habanalabs/hl<n>/infineon_ver80What: /sys/class/habanalabs/hl<n>/infineon_ver
79Date: Jan 201981Date: Jan 2019
@@ -92,18 +94,20 @@ What: /sys/class/habanalabs/hl<n>/mme_clk · 12 unmodified lines
92Date: Jan 201994Date: Jan 2019
93KernelVersion: 5.195KernelVersion: 5.1
94Contact: oded.gabbay@gmail.com96Contact: oded.gabbay@gmail.com
95Description: Allows the user to set the maximum clock frequency of the97Description: Allows the user to set the maximum clock frequency, in Hz, of
96 MME compute engine. Writes to this parameter affect the device98 the MME compute engine. Writes to this parameter affect the
97 only when the power management profile is set to "manual" mode.99 device only when the power management profile is set to "manual"
98 The device MME clock might be set to lower value then the100 mode. The device MME clock might be set to lower value than the
99 maximum. The user should read the mme_clk_curr to see the actual101 maximum. The user should read the mme_clk_curr to see the actual
100 frequency value of the MME102 frequency value of the MME. This property is valid only for the
103 Goya ASIC family
101 104
102What: /sys/class/habanalabs/hl<n>/mme_clk_curr105What: /sys/class/habanalabs/hl<n>/mme_clk_curr
103Date: Jan 2019106Date: Jan 2019
104KernelVersion: 5.1107KernelVersion: 5.1
105Contact: oded.gabbay@gmail.com108Contact: oded.gabbay@gmail.com
106Description: Displays the current clock frequency of the MME compute engine109Description: Displays the current clock frequency, in Hz, of the MME compute
110 engine. This property is valid only for the Goya ASIC family
107 111
108What: /sys/class/habanalabs/hl<n>/pci_addr112What: /sys/class/habanalabs/hl<n>/pci_addr
109Date: Jan 2019113Date: Jan 2019
@@ -163,18 +167,20 @@ What: /sys/class/habanalabs/hl<n>/tpc_clk · 53 unmodified lines
163Date: Jan 2019167Date: Jan 2019
164KernelVersion: 5.1168KernelVersion: 5.1
165Contact: oded.gabbay@gmail.com169Contact: oded.gabbay@gmail.com
166Description: Allows the user to set the maximum clock frequency of the170Description: Allows the user to set the maximum clock frequency, in Hz, of
167 TPC compute engines. Writes to this parameter affect the device171 the TPC compute engines. Writes to this parameter affect the
168 only when the power management profile is set to "manual" mode.172 device only when the power management profile is set to "manual"
169 The device TPC clock might be set to lower value then the173 mode. The device TPC clock might be set to lower value than the
170 maximum. The user should read the tpc_clk_curr to see the actual174 maximum. The user should read the tpc_clk_curr to see the actual
171 frequency value of the TPC175 frequency value of the TPC. This property is valid only for
176 Goya ASIC family
172 177
173What: /sys/class/habanalabs/hl<n>/tpc_clk_curr178What: /sys/class/habanalabs/hl<n>/tpc_clk_curr
174Date: Jan 2019179Date: Jan 2019
175KernelVersion: 5.1180KernelVersion: 5.1
176Contact: oded.gabbay@gmail.com181Contact: oded.gabbay@gmail.com
177Description: Displays the current clock frequency of the TPC compute engines182Description: Displays the current clock frequency, in Hz, of the TPC compute
183 engines. This property is valid only for the Goya ASIC family
178 184
179What: /sys/class/habanalabs/hl<n>/uboot_ver185What: /sys/class/habanalabs/hl<n>/uboot_ver
180Date: Jan 2019186Date: Jan 2019
Documentation/ABI/testing/sysfs-driver-hid+6−6
@@ -1,6 +1,6 @@
1What: For USB devices : /sys/bus/usb/devices/<busnum>-<devnum>:<config num>.<interface num>/<hid-bus>:<vendor-id>:<product-id>.<num>/report_descriptor1What: /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_descriptor2What: /sys/class/bluetooth/hci<addr>/<hid-bus>:<vendor-id>:<product-id>.<num>/report_descriptor
3 Symlink : /sys/class/hidraw/hidraw<num>/device/report_descriptor3What: /sys/class/hidraw/hidraw<num>/device/report_descriptor
4Date: Jan 20114Date: Jan 2011
5KernelVersion: 2.0.395KernelVersion: 2.0.39
6Contact: Alan Ott <alan@signal11.us>6Contact: Alan Ott <alan@signal11.us>
@@ -9,9 +9,9 @@ Description: When read, this file returns the device's raw binary HID · 2 unmodified lines
9 This file cannot be written.9 This file cannot be written.
10Users: HIDAPI library (http://www.signal11.us/oss/hidapi)10Users: HIDAPI library (http://www.signal11.us/oss/hidapi)
11 11
12What: For USB devices : /sys/bus/usb/devices/<busnum>-<devnum>:<config num>.<interface num>/<hid-bus>:<vendor-id>:<product-id>.<num>/country12What: /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>/country13What: /sys/class/bluetooth/hci<addr>/<hid-bus>:<vendor-id>:<product-id>.<num>/country
14 Symlink : /sys/class/hidraw/hidraw<num>/device/country14What: /sys/class/hidraw/hidraw<num>/device/country
15Date: February 201515Date: February 2015
16KernelVersion: 3.1916KernelVersion: 3.19
17Contact: Olivier Gay <ogay@logitech.com>17Contact: 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
5 press of a button.5 press of a button.
6 When read, this file returns the raw number of the actual dpi6 When read, this file returns the raw number of the actual dpi
7 setting reported by the mouse. This number has to be further7 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:
9 9
10 VALUE DPI10 VALUE DPI
11 1 80011 1 800
Documentation/ABI/testing/sysfs-driver-ppi+1−1
@@ -1,6 +1,6 @@
1What: /sys/class/tpm/tpmX/ppi/1What: /sys/class/tpm/tpmX/ppi/
2Date: August 20122Date: August 2012
3Kernel Version: 3.63KernelVersion: 3.6
4Contact: xiaoyan.zhang@intel.com4Contact: xiaoyan.zhang@intel.com
5Description:5Description:
6 This folder includes the attributes related with PPI (Physical6 This folder includes the attributes related with PPI (Physical
Documentation/ABI/testing/sysfs-driver-st+1−1
@@ -1,6 +1,6 @@
1What: /sys/bus/scsi/drivers/st/debug_flag1What: /sys/bus/scsi/drivers/st/debug_flag
2Date: October 20152Date: October 2015
3Kernel Version: ?.?3KernelVersion: ?.?
4Contact: shane.seymour@hpe.com4Contact: shane.seymour@hpe.com
5Description:5Description:
6 This file allows you to turn debug output from the st driver6 This file allows you to turn debug output from the st driver
Documentation/ABI/testing/sysfs-driver-wacom+1−1
@@ -1,6 +1,6 @@
1What: /sys/bus/hid/devices/<bus>:<vid>:<pid>.<n>/speed1What: /sys/bus/hid/devices/<bus>:<vid>:<pid>.<n>/speed
2Date: April 20102Date: April 2010
3Kernel Version: 2.6.353KernelVersion: 2.6.35
4Contact: linux-bluetooth@vger.kernel.org4Contact: linux-bluetooth@vger.kernel.org
5Description:5Description:
6 The /sys/bus/hid/devices/<bus>:<vid>:<pid>.<n>/speed file6 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
243 - Del: echo '[h/c]!extension' > /sys/fs/f2fs/<disk>/extension_list243 - Del: echo '[h/c]!extension' > /sys/fs/f2fs/<disk>/extension_list
244 - [h] means add/del hot file extension244 - [h] means add/del hot file extension
245 - [c] means add/del cold file extension245 - [c] means add/del cold file extension
246
247What: /sys/fs/f2fs/<disk>/unusable
248Date April 2019
249Contact: "Daniel Rosenberg" <drosen@google.com>
250Description:
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
2Date: February 20112Date: February 2011
3KernelVersion: 2.6.383KernelVersion: 2.6.38
4Contact: Ludwig Nussel <ludwig.nussel@suse.de>4Contact: Ludwig Nussel <ludwig.nussel@suse.de>
5Description5Description:
6 Shows whether file system capabilities are honored6 Shows whether file system capabilities are honored
7 when executing a binary7 when executing a binary
8 8
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
24 region is described on a single line: the 1st field is24 region is described on a single line: the 1st field is
25 the base IOVA, the second is the end IOVA and the third25 the base IOVA, the second is the end IOVA and the third
26 field describes the type of the region.26 field describes the type of the region.
27
28What: /sys/kernel/iommu_groups/reserved_regions
29Date: June 2019
30KernelVersion: v5.3
31Contact: Eric Auger <eric.auger@redhat.com>
32Description: 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
11 example would be, if User A has shares = 1024 and user11 example would be, if User A has shares = 1024 and user
12 B has shares = 2048, User B will get twice the CPU12 B has shares = 2048, User B will get twice the CPU
13 bandwidth user A will. For more details refer13 bandwidth user A will. For more details refer
14 Documentation/scheduler/sched-design-CFS.txt14 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
4Contact: Ken'ichi Ohmichi <oomichi@mxs.nes.nec.co.jp>4Contact: Ken'ichi Ohmichi <oomichi@mxs.nes.nec.co.jp>
5 Kexec Mailing List <kexec@lists.infradead.org>5 Kexec Mailing List <kexec@lists.infradead.org>
6 Vivek Goyal <vgoyal@redhat.com>6 Vivek Goyal <vgoyal@redhat.com>
7Description7Description:
8 Shows physical address and size of vmcoreinfo ELF note.8 Shows physical address and size of vmcoreinfo ELF note.
9 First value contains physical address of note in hex and9 First value contains physical address of note in hex and
10 second value contains the size of note in hex. This ELF10 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
31 To control the LED display, use the following :31 To control the LED display, use the following :
32 echo 0x0T000DDD > /sys/devices/platform/asus_laptop/32 echo 0x0T000DDD > /sys/devices/platform/asus_laptop/
33 where T control the 3 letters display, and DDD the 3 digits display.33 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.txt34 The DDD table can be found in Documentation/admin-guide/laptops/asus-laptop.rst
35 35
36What: /sys/devices/platform/asus_laptop/bluetooth36What: /sys/devices/platform/asus_laptop/bluetooth
37Date: January 200737Date: January 2007
Documentation/ABI/testing/sysfs-platform-asus-wmi+10−0
@@ -36,3 +36,13 @@ KernelVersion: 3.5 · 35 unmodified lines
36Contact: "AceLan Kao" <acelan.kao@canonical.com>36Contact: "AceLan Kao" <acelan.kao@canonical.com>
37Description:37Description:
38 Resume on lid open. 1 means on, 0 means off.38 Resume on lid open. 1 means on, 0 means off.
39
40What: /sys/devices/platform/<platform>/fan_boost_mode
41Date: Sep 2019
42KernelVersion: 5.3
43Contact: "Yurii Pavlovskyi" <yurii.pavlovskyi@gmail.com>
44Description:
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 @@
1What: /sys/devices/platform/<i2c-demux-name>/available_masters1What: /sys/devices/platform/<i2c-demux-name>/available_masters
2Date: January 20162Date: January 2016
3KernelVersion: 4.63KernelVersion: 4.6
4Contact: Wolfram Sang <wsa@the-dreams.de>4Contact: Wolfram Sang <wsa+renesas@sang-engineering.com>
5Description:5Description:
6 Reading the file will give you a list of masters which can be6 Reading the file will give you a list of masters which can be
7 selected for a demultiplexed bus. The format is7 selected for a demultiplexed bus. The format is
@@ -12,7 +12,7 @@ Description: · 4 unmodified lines
12What: /sys/devices/platform/<i2c-demux-name>/current_master12What: /sys/devices/platform/<i2c-demux-name>/current_master
13Date: January 201613Date: January 2016
14KernelVersion: 4.614KernelVersion: 4.6
15Contact: Wolfram Sang <wsa@the-dreams.de>15Contact: Wolfram Sang <wsa+renesas@sang-engineering.com>
16Description:16Description:
17 This file selects/shows the active I2C master for a demultiplexed17 This file selects/shows the active I2C master for a demultiplexed
18 bus. It uses the <index> value from the file 'available_masters'.18 bus. It uses the <index> value from the file 'available_masters'.
Documentation/ABI/testing/sysfs-platform-wilco-ec+40−0
@@ -0,0 +1,40 @@
1What: /sys/bus/platform/devices/GOOG000C\:00/boot_on_ac
2Date: April 2019
3KernelVersion: 5.3
4Description:
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
11What: /sys/bus/platform/devices/GOOG000C\:00/build_date
12Date: May 2019
13KernelVersion: 5.3
14Description:
15 Display Wilco Embedded Controller firmware build date.
16 Output will a MM/DD/YY string.
17
18What: /sys/bus/platform/devices/GOOG000C\:00/build_revision
19Date: May 2019
20KernelVersion: 5.3
21Description:
22 Display Wilco Embedded Controller build revision.
23 Output will a version string be similar to the example below:
24 d2592cae0
25
26What: /sys/bus/platform/devices/GOOG000C\:00/model_number
27Date: May 2019
28KernelVersion: 5.3
29Description:
30 Display Wilco Embedded Controller model number.
31 Output will a version string be similar to the example below:
32 08B6
33
34What: /sys/bus/platform/devices/GOOG000C\:00/version
35Date: May 2019
36KernelVersion: 5.3
37Description:
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
300 attempt.300 attempt.
301 301
302 Using this sysfs file will override any values that were302 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
212 212
213If the device only supports 32-bit addressing for descriptors in the213If the device only supports 32-bit addressing for descriptors in the
214coherent allocations, but supports full 64-bits for streaming mappings214coherent allocations, but supports full 64-bits for streaming mappings
215it would look like this:215it would look like this::
216 216
217 if (dma_set_mask(dev, DMA_BIT_MASK(64))) {217 if (dma_set_mask(dev, DMA_BIT_MASK(64))) {
218 dev_warn(dev, "mydev: No suitable DMA available\n");218 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
198::198::
199 199
200 size_t200 size_t
201 dma_direct_max_mapping_size(struct device *dev);201 dma_max_mapping_size(struct device *dev);
202 202
203Returns the maximum size of a mapping for the device. The size parameter203Returns the maximum size of a mapping for the device. The size parameter
204of the mapping functions like dma_map_single(), dma_map_page() and204of the mapping functions like dma_map_single(), dma_map_page() and
Documentation/EDID/HOWTO.txt+0−49
@@ -1,49 +0,0 @@
1In the good old days when graphics parameters were configured explicitly
2in a file called xorg.conf, even broken hardware could be managed.
3
4Today, with the advent of Kernel Mode Setting, a graphics board is
5either correctly working because all components follow the standards -
6or the computer is unusable, because the screen remains dark after
7booting 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.
13Adding the kernel parameter "nomodeset" helps in most cases, but causes
14restrictions later on.
15
16As a remedy for such situations, the kernel configuration item
17CONFIG_DRM_LOAD_EDID_FIRMWARE was introduced. It allows to provide an
18individually prepared or corrected EDID data set in the /lib/firmware
19directory 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
21commonly used screen resolutions (800x600, 1024x768, 1280x1024, 1600x1200,
221680x1050, 1920x1080) as binary blobs, but the kernel source tree does
23not contain code to create these data. In order to elucidate the origin
24of the built-in binary EDID blobs and to facilitate the creation of
25individual data for a specific misbehaving monitor, commented sources
26and a Makefile environment are given here.
27
28To create binary EDID and C source code files from the existing data
29material, simply type "make".
30
31If you want to create your own EDID file, copy the file 1024x768.S,
32replace the settings with your own data and add a new target to the
33Makefile. Please note that the EDID data structure expects the timing
34values in a different way as compared to the standard X11 format.
35
36X11:
37HTimings: hdisp hsyncstart hsyncend htotal
38VTimings: vdisp vsyncstart vsyncend vtotal
39
40EDID:
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 @@
1config 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
4 4
5subdir-y := devicetree/bindings/5subdir-y := devicetree/bindings/
6 6
7# Check for broken documentation file references
8ifeq ($(CONFIG_WARN_MISSING_DOCUMENTS),y)
9$(shell $(srctree)/scripts/documentation-file-ref-check --warn)
10endif
11
7# You can set these variables from the command line.12# You can set these variables from the command line.
8SPHINXBUILD = sphinx-build13SPHINXBUILD = sphinx-build
9SPHINXOPTS =14SPHINXOPTS =
@@ -23,11 +28,13 @@ ifeq ($(HAVE_SPHINX),0) · 13 unmodified lines
23.DEFAULT:28.DEFAULT:
24 $(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.)29 $(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.)
25 @echo30 @echo
26 @./scripts/sphinx-pre-install31 @$(srctree)/scripts/sphinx-pre-install
27 @echo " SKIP Sphinx $@ target."32 @echo " SKIP Sphinx $@ target."
28 33
29else # HAVE_SPHINX34else # HAVE_SPHINX
30 35
36export 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
31# User-friendly check for pdflatex and latexmk38# User-friendly check for pdflatex and latexmk
32HAVE_PDFLATEX := $(shell if which $(PDFLATEX) >/dev/null 2>&1; then echo 1; else echo 0; fi)39HAVE_PDFLATEX := $(shell if which $(PDFLATEX) >/dev/null 2>&1; then echo 1; else echo 0; fi)
33HAVE_LATEXMK := $(shell if which latexmk >/dev/null 2>&1; then echo 1; else echo 0; fi)40HAVE_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
70 $(abspath $(BUILDDIR)/$3/$4)77 $(abspath $(BUILDDIR)/$3/$4)
71 78
72htmldocs:79htmldocs:
80 @$(srctree)/scripts/sphinx-pre-install --version-check
73 @+$(foreach var,$(SPHINXDIRS),$(call loop_cmd,sphinx,html,$(var),,$(var)))81 @+$(foreach var,$(SPHINXDIRS),$(call loop_cmd,sphinx,html,$(var),,$(var)))
74 82
75linkcheckdocs:83linkcheckdocs:
76 @$(foreach var,$(SPHINXDIRS),$(call loop_cmd,sphinx,linkcheck,$(var),,$(var)))84 @$(foreach var,$(SPHINXDIRS),$(call loop_cmd,sphinx,linkcheck,$(var),,$(var)))
77 85
78latexdocs:86latexdocs:
87 @$(srctree)/scripts/sphinx-pre-install --version-check
79 @+$(foreach var,$(SPHINXDIRS),$(call loop_cmd,sphinx,latex,$(var),latex,$(var)))88 @+$(foreach var,$(SPHINXDIRS),$(call loop_cmd,sphinx,latex,$(var),latex,$(var)))
80 89
81ifeq ($(HAVE_PDFLATEX),0)90ifeq ($(HAVE_PDFLATEX),0)
@@ -87,14 +96,17 @@ pdfdocs: · 5 unmodified lines
87else # HAVE_PDFLATEX96else # HAVE_PDFLATEX
88 97
89pdfdocs: latexdocs98pdfdocs: latexdocs
99 @$(srctree)/scripts/sphinx-pre-install --version-check
90 $(foreach var,$(SPHINXDIRS), $(MAKE) PDFLATEX="$(PDFLATEX)" LATEXOPTS="$(LATEXOPTS)" -C $(BUILDDIR)/$(var)/latex || exit;)100 $(foreach var,$(SPHINXDIRS), $(MAKE) PDFLATEX="$(PDFLATEX)" LATEXOPTS="$(LATEXOPTS)" -C $(BUILDDIR)/$(var)/latex || exit;)
91 101
92endif # HAVE_PDFLATEX102endif # HAVE_PDFLATEX
93 103
94epubdocs:104epubdocs:
105 @$(srctree)/scripts/sphinx-pre-install --version-check
95 @+$(foreach var,$(SPHINXDIRS),$(call loop_cmd,sphinx,epub,$(var),epub,$(var)))106 @+$(foreach var,$(SPHINXDIRS),$(call loop_cmd,sphinx,epub,$(var),epub,$(var)))
96 107
97xmldocs:108xmldocs:
109 @$(srctree)/scripts/sphinx-pre-install --version-check
98 @+$(foreach var,$(SPHINXDIRS),$(call loop_cmd,sphinx,xml,$(var),xml,$(var)))110 @+$(foreach var,$(SPHINXDIRS),$(call loop_cmd,sphinx,xml,$(var),xml,$(var)))
99 111
100endif # HAVE_SPHINX112endif # 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
101. About this guide
11
12This guide describes the basics of Message Signaled Interrupts (MSIs),
13the advantages of using MSI over traditional interrupt mechanisms, how
14to change your driver to use MSI or MSI-X and some basic diagnostics to
15try if a device doesn't support MSIs.
16
17
182. What are MSIs?
19
20A Message Signaled Interrupt is a write from the device to a special
21address which causes an interrupt to be received by the CPU.
22
23The MSI capability was first specified in PCI 2.2 and was later enhanced
24in PCI 3.0 to allow each interrupt to be masked individually. The MSI-X
25capability was also introduced with PCI 3.0. It supports more interrupts
26per device than MSI and allows interrupts to be independently configured.
27
28Devices may support both MSI and MSI-X, but only one can be enabled at
29a time.
30
31
323. Why use MSIs?
33
34There are three reasons why using MSIs can give an advantage over
35traditional pin-based interrupts.
36
37Pin-based PCI interrupts are often shared amongst several devices.
38To support this, the kernel must call each interrupt handler associated
39with an interrupt, which leads to reduced performance for the system as
40a whole. MSIs are never shared, so this problem cannot arise.
41
42When a device writes data to memory, then raises a pin-based interrupt,
43it is possible that the interrupt may arrive before all the data has
44arrived in memory (this becomes more likely with devices behind PCI-PCI
45bridges). In order to ensure that all the data has arrived in memory,
46the interrupt handler must read a register on the device which raised
47the interrupt. PCI transaction ordering rules require that all the data
48arrive in memory before the value may be returned from the register.
49Using MSIs avoids this problem as the interrupt-generating write cannot
50pass the data writes, so by the time the interrupt is raised, the driver
51knows that all the data has arrived in memory.
52
53PCI devices can only support a single pin-based interrupt per function.
54Often drivers have to query the device to find out what event has
55occurred, slowing down interrupt handling for the common case. With
56MSIs, a device can support more interrupts, allowing each interrupt
57to be specialised to a different purpose. One possible design gives
58infrequent conditions (such as errors) their own interrupt which allows
59the driver to handle the normal interrupt handling path more efficiently.
60Other possible designs include giving one interrupt to each packet queue
61in a network card or each port in a storage controller.
62
63
644. How to use MSIs
65
66PCI devices are initialised to use pin-based interrupts. The device
67driver has to set up the device to use MSI or MSI-X. Not all machines
68support MSIs correctly, and for those machines, the APIs described below
69will simply fail and the device will continue to use pin-based interrupts.
70
714.1 Include kernel support for MSIs
72
73To support MSI or MSI-X, the kernel must be built with the CONFIG_PCI_MSI
74option enabled. This option is only available on some architectures,
75and it may depend on some other options also being set. For example,
76on x86, you must also enable X86_UP_APIC or SMP in order to see the
77CONFIG_PCI_MSI option.
78
794.2 Using MSI
80
81Most of the hard work is done for the driver in the PCI layer. The driver
82simply has to request that the PCI layer set up the MSI capability for this
83device.
84
85To automatically use MSI or MSI-X interrupt vectors, use the following
86function:
87
88 int pci_alloc_irq_vectors(struct pci_dev *dev, unsigned int min_vecs,
89 unsigned int max_vecs, unsigned int flags);
90
91which allocates up to max_vecs interrupt vectors for a PCI device. It
92returns the number of vectors allocated or a negative error. If the device
93has a requirements for a minimum number of vectors the driver can pass a
94min_vecs argument set to this limit, and the PCI core will return -ENOSPC
95if it can't meet the minimum number of vectors.
96
97The flags argument is used to specify which type of interrupt can be used
98by the device and the driver (PCI_IRQ_LEGACY, PCI_IRQ_MSI, PCI_IRQ_MSIX).
99A convenient short-hand (PCI_IRQ_ALL_TYPES) is also available to ask for
100any possible kind of interrupt. If the PCI_IRQ_AFFINITY flag is set,
101pci_alloc_irq_vectors() will spread the interrupts around the available CPUs.
102
103To get the Linux IRQ numbers passed to request_irq() and free_irq() and the
104vectors, use the following function:
105
106 int pci_irq_vector(struct pci_dev *dev, unsigned int nr);
107
108Any allocated resources should be freed before removing the device using
109the following function:
110
111 void pci_free_irq_vectors(struct pci_dev *dev);
112
113If a device supports both MSI-X and MSI capabilities, this API will use the
114MSI-X facilities in preference to the MSI facilities. MSI-X supports any
115number of interrupts between 1 and 2048. In contrast, MSI is restricted to
116a maximum of 32 interrupts (and must be a power of two). In addition, the
117MSI interrupt vectors must be allocated consecutively, so the system might
118not be able to allocate as many vectors for MSI as it could for MSI-X. On
119some platforms, MSI interrupts must all be targeted at the same set of CPUs
120whereas MSI-X interrupts can all be targeted at different CPUs.
121
122If a device supports neither MSI-X or MSI it will fall back to a single
123legacy IRQ vector.
124
125The typical usage of MSI or MSI-X interrupts is to allocate as many vectors
126as possible, likely up to the limit supported by the device. If nvec is
127larger than the number supported by the device it will automatically be
128capped to the supported limit, so there is no need to query the number of
129vectors 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
135If a driver is unable or unwilling to deal with a variable number of MSI
136interrupts it can request a particular number of interrupts by passing that
137number 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
144The most notorious example of the request type described above is enabling
145the 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
152Some devices might not support using legacy line interrupts, in which case
153the 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
1594.3 Legacy APIs
160
161The following old APIs to enable and disable MSI or MSI-X interrupts should
162not 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
170Additionally there are APIs to provide the number of supported MSI or MSI-X
171vectors: pci_msi_vec_count() and pci_msix_vec_count(). In general these
172should be avoided in favor of letting pci_alloc_irq_vectors() cap the
173number of vectors. If you have a legitimate special use case for the count
174of vectors we might have to revisit that decision and add a
175pci_nr_irq_vectors() helper that handles MSI and MSI-X transparently.
176
1774.4 Considerations when using MSIs
178
1794.4.1 Spinlocks
180
181Most device drivers have a per-device spinlock which is taken in the
182interrupt handler. With pin-based interrupts or a single MSI, it is not
183necessary to disable interrupts (Linux guarantees the same interrupt will
184not be re-entered). If a device uses multiple interrupts, the driver
185must disable interrupts while the lock is held. If the device sends
186a different interrupt, the driver will deadlock trying to recursively
187acquire the spinlock. Such deadlocks can be avoided by using
188spin_lock_irqsave() or spin_lock_irq() which disable local interrupts
189and acquire the lock (see Documentation/kernel-hacking/locking.rst).
190
1914.5 How to tell whether MSI/MSI-X is enabled on a device
192
193Using 'lspci -v' (as root) may show some devices with "MSI", "Message
194Signalled Interrupts" or "MSI-X" capabilities. Each of these capabilities
195has an 'Enable' flag which is followed with either "+" (enabled)
196or "-" (disabled).
197
198
1995. MSI quirks
200
201Several PCI chipsets or devices are known not to support MSIs.
202The PCI stack provides three ways to disable MSIs:
203
2041. globally
2052. on all devices behind a specific bridge
2063. on a single device
207
2085.1. Disabling MSIs globally
209
210Some host chipsets simply don't support MSIs properly. If we're
211lucky, the manufacturer knows this and has indicated it in the ACPI
212FADT table. In this case, Linux automatically disables MSIs.
213Some boards don't include this information in the table and so we have
214to detect them ourselves. The complete list of these is found near the
215quirk_disable_all_msi() function in drivers/pci/quirks.c.
216
217If you have a board which has problems with MSIs, you can pass pci=nomsi
218on the kernel command line to disable MSIs on all devices. It would be
219in your best interests to report the problem to linux-pci@vger.kernel.org
220including a full 'lspci -v' so we can add the quirks to the kernel.
221
2225.2. Disabling MSIs below a bridge
223
224Some PCI bridges are not able to route MSIs between busses properly.
225In this case, MSIs must be disabled on all devices behind the bridge.
226
227Some bridges allow you to enable MSIs by changing some bits in their
228PCI configuration space (especially the Hypertransport chipsets such
229as the nVidia nForce and Serverworks HT2000). As with host chipsets,
230Linux mostly knows about them and automatically enables MSIs if it can.
231If you have a bridge unknown to Linux, you can enable
232MSIs in configuration space using whatever method you know works, then
233enable MSIs on that bridge by doing:
234
235 echo 1 > /sys/bus/pci/devices/$bridge/msi_bus
236
237where $bridge is the PCI address of the bridge you've enabled (eg
2380000:00:0e.0).
239
240To disable MSIs, echo 0 instead of 1. Changing this value should be
241done with caution as it could break interrupt handling for all devices
242below this bridge.
243
244Again, please notify linux-pci@vger.kernel.org of any bridges that need
245special handling.
246
2475.3. Disabling MSIs on a single device
248
249Some devices are known to have faulty MSI implementations. Usually this
250is handled in the individual device driver, but occasionally it's necessary
251to handle this with a quirk. Some drivers have an option to disable use
252of MSI. While this is a convenient workaround for the driver author,
253it is not good practice, and should not be emulated.
254
2555.4. Finding why MSIs are disabled on a device
256
257From the above three sections, you can see that there are many reasons
258why MSIs may not be enabled for a given device. Your first step should
259be to examine your dmesg carefully to determine whether MSIs are enabled
260for your machine. You should also check your .config to be sure you
261have enabled CONFIG_PCI_MSI.
262
263Then, '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)
265or disabled (0). If 0 is found in any of the msi_bus files belonging
266to bridges between the PCI root and the device, MSIs are disabled.
267
268It is also worth checking the device driver to see whether it supports MSIs.
269For example, it may contain calls to pci_irq_alloc_vectors() with the
270PCI_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
51. About this guide
6
7This guide describes the basics of the PCI Express Port Bus driver
8and provides information on how to enable the service drivers to
9register/unregister with the PCI Express Port Bus Driver.
10
112. Copyright 2004 Intel Corporation
12
133. What is the PCI Express Port Bus Driver
14
15A PCI Express Port is a logical PCI-PCI Bridge structure. There
16are two types of PCI Express Port: the Root Port and the Switch
17Port. The Root Port originates a PCI Express link from a PCI Express
18Root Complex and the Switch Port connects PCI Express links to
19internal logical PCI buses. The Switch Port, which has its secondary
20bus representing the switch's internal routing logic, is called the
21switch's Upstream Port. The switch's Downstream Port is bridging from
22switch's internal routing bus to a bus representing the downstream
23PCI Express link from the PCI Express Switch.
24
25A PCI Express Port can provide up to four distinct functions,
26referred to in this document as services, depending on its port type.
27PCI Express Port's services include native hotplug support (HP),
28power management event support (PME), advanced error reporting
29support (AER), and virtual channel support (VC). These services may
30be handled by a single complex driver or be individually distributed
31and handled by corresponding service drivers.
32
334. Why use the PCI Express Port Bus Driver?
34
35In existing Linux kernels, the Linux Device Driver Model allows a
36physical device to be handled by only a single driver. The PCI
37Express Port is a PCI-PCI Bridge device with multiple distinct
38services. To maintain a clean and simple solution each service
39may have its own software service driver. In this case several
40service drivers will compete for a single PCI-PCI Bridge device.
41For example, if the PCI Express Root Port native hotplug service
42driver is loaded first, it claims a PCI-PCI Bridge Root Port. The
43kernel therefore does not load other service drivers for that Root
44Port. In other words, it is impossible to have multiple service
45drivers load and run on a PCI-PCI Bridge device simultaneously
46using the current driver model.
47
48To enable multiple service drivers running simultaneously requires
49having a PCI Express Port Bus driver, which manages all populated
50PCI Express Ports and distributes all provided service requests
51to the corresponding service drivers as required. Some key
52advantages 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
665. Configuring the PCI Express Port Bus Driver vs. Service Drivers
67
685.1 Including the PCI Express Port Bus Driver Support into the Kernel
69
70Including the PCI Express Port Bus driver depends on whether the PCI
71Express support is included in the kernel config. The kernel will
72automatically include the PCI Express Port Bus driver as a kernel
73driver when the PCI Express support is enabled in the kernel.
74
755.2 Enabling Service Driver Support
76
77PCI device drivers are implemented based on Linux Device Driver Model.
78All service drivers are PCI device drivers. As discussed above, it is
79impossible to load any service driver once the kernel has loaded the
80PCI Express Port Bus Driver. To meet the PCI Express Port Bus Driver
81Model requires some minimal changes on existing service drivers that
82imposes no impact on the functionality of existing service drivers.
83
84A service driver is required to use the two APIs shown below to
85register its service with the PCI Express Port Bus driver (see
86section 5.2.1 & 5.2.2). It is important that a service driver
87initializes the pcie_port_service_driver data structure, included in
88header file /include/linux/pcieport_if.h, before calling these APIs.
89Failure to do so will result an identity mismatch, which prevents
90the PCI Express Port Bus driver from loading a service driver.
91
925.2.1 pcie_port_service_register
93
94int pcie_port_service_register(struct pcie_port_service_driver *new)
95
96This API replaces the Linux Driver Model's pci_register_driver API. A
97service driver should always calls pcie_port_service_register at
98module init. Note that after service driver being loaded, calls
99such as pci_enable_device(dev) and pci_set_master(dev) are no longer
100necessary since these calls are executed by the PCI Port Bus driver.
101
1025.2.2 pcie_port_service_unregister
103
104void pcie_port_service_unregister(struct pcie_port_service_driver *new)
105
106pcie_port_service_unregister replaces the Linux Driver Model's
107pci_unregister_driver. It's always called by service driver when a
108module exits.
109
1105.2.3 Sample Code
111
112Below is sample service driver code to initialize the port service
113driver data structure.
114
115static 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
123static 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
134Below is a sample code for registering/unregistering a service
135driver.
136
137static 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
150static void __exit aerdrv_service_exit(void)
151{
152 pcie_port_service_unregister(&root_aerdrv);
153}
154
155module_init(aerdrv_service_init);
156module_exit(aerdrv_service_exit);
157
1586. Possible Resource Conflicts
159
160Since all service drivers of a PCI-PCI Bridge Port device are
161allowed to run simultaneously, below lists a few of possible resource
162conflicts with proposed solutions.
163
1646.1 MSI and MSI-X Vector Resource
165
166Once MSI or MSI-X interrupts are enabled on a device, it stays in this
167mode until they are disabled again. Since service drivers of the same
168PCI-PCI Bridge port share the same physical device, if an individual
169service driver enables or disables MSI/MSI-X mode it may result
170unpredictable behavior.
171
172To avoid this situation all service drivers are not permitted to
173switch interrupt mode on its device. The PCI Express Port Bus driver
174is responsible for determining the interrupt mode and this should be
175transparent to service drivers. Service drivers need to know only
176the vector IRQ assigned to the field irq of struct pcie_device, which
177is passed in when the PCI Express Port Bus driver probes each service
178driver. Service drivers should use (struct pcie_device*)dev->irq to
179call request_irq/free_irq. In addition, the interrupt mode is stored
180in the field interrupt_mode of struct pcie_device.
181
1826.3 PCI Memory/IO Mapped Regions
183
184Service drivers for PCI Express Power Management (PME), Advanced
185Error Reporting (AER), Hot-Plug (HP) and Virtual Channel (VC) access
186PCI configuration space on the PCI Express port. In all cases the
187registers accessed are independent of each other. This patch assumes
188that all service drivers will be well behaved and not overwrite
189other service driver's configuration settings.
190
1916.4 PCI Config Registers
192
193Each service driver runs its PCI config operations on its own
194capability structure except the PCI Express capability structure, in
195which Root Control register and Device Control register are shared
196between PME and AER. This patch assumes that all service drivers
197will be well behaved and not overwrite other service driver's
198configuration settings.
Documentation/PCI/acpi-info.rst+192−0
@@ -0,0 +1,192 @@
1.. SPDX-License-Identifier: GPL-2.0
2
3========================================
4ACPI considerations for PCI host bridges
5========================================
6
7The general rule is that the ACPI namespace should describe everything the
8OS might use unless there's another way for the OS to find it [1, 2].
9
10For example, there's no standard hardware mechanism for enumerating PCI
11host bridges, so the ACPI namespace must describe each host bridge, the
12method for accessing PCI config space below it, the address space windows
13the host bridge forwards to PCI (using _CRS), and the routing of legacy
14INTx interrupts (using _PRT).
15
16PCI devices, which are below the host bridge, generally do not need to be
17described via ACPI. The OS can discover them via the standard PCI
18enumeration mechanism, using config accesses to discover and identify
19devices and read and size their BARs. However, ACPI may describe PCI
20devices if it provides power management or hotplug functionality for them
21or if the device has INTx interrupts connected by platform interrupt
22controllers and a _PRT is needed to describe those connections.
23
24ACPI resource description is done via _CRS objects of devices in the ACPI
25namespace [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
27a driver for the device [3].  That's important because it means an old OS
28can work correctly even on a system with new devices unknown to the OS.
29The new devices might not do anything, but the OS can at least make sure no
30resources conflict with them.
31
32Static tables like MCFG, HPET, ECDT, etc., are *not* mechanisms for
33reserving address space. The static tables are for things the OS needs to
34know early in boot, before it can parse the ACPI namespace. If a new table
35is defined, an old OS needs to operate correctly even though it ignores the
36table. _CRS allows that because it is generic and understood by the old
37OS; a static table does not.
38
39If the OS is expected to manage a non-discoverable device described via
40ACPI, that device will have a specific _HID/_CID that tells the OS what
41driver to bind to it, and the _CRS tells the OS and the driver where the
42device's registers are.
43
44PCI host bridges are PNP0A03 or PNP0A08 devices.  Their _CRS should
45describe all the address space they consume.  This includes all the windows
46they forward down to the PCI bus, as well as registers of the host bridge
47itself that are not forwarded to PCI.  The host bridge registers include
48things like secondary/subordinate bus registers that determine the bus
49range below the bridge, window registers that describe the apertures, etc.
50These are all device-specific, non-architected things, so the only way a
51PNP0A03/PNP0A08 driver can manage them is via _PRS/_CRS/_SRS, which contain
52the device-specific details.  The host bridge registers also include ECAM
53space, since it is consumed by the host bridge.
54
55ACPI defines a Consumer/Producer bit to distinguish the bridge registers
56("Consumer") from the bridge apertures ("Producer") [4, 5], but early
57BIOSes didn't use that bit correctly. The result is that the current ACPI
58spec defines Consumer/Producer only for the Extended Address Space
59descriptors; the bit should be ignored in the older QWord/DWord/Word
60Address Space descriptors. Consequently, OSes have to assume all
61QWord/DWord/Word descriptors are windows.
62
63Prior to the addition of Extended Address Space descriptors, the failure of
64Consumer/Producer meant there was no way to describe bridge registers in
65the PNP0A03/PNP0A08 device itself. The workaround was to describe the
66bridge registers (including ECAM space) in PNP0C02 catch-all devices [6].
67With the exception of ECAM, the bridge register space is device-specific
68anyway, so the generic PNP0A03/PNP0A08 driver (pci_root.c) has no need to
69know about it.  
70
71New architectures should be able to use "Consumer" Extended Address Space
72descriptors in the PNP0A03 device for bridge registers, including ECAM,
73although a strict interpretation of [6] might prohibit this. Old x86 and
74ia64 kernels assume all address space descriptors, including "Consumer"
75Extended Address Space ones, are windows, so it would not be safe to
76describe bridge registers this way on those architectures.
77
78PNP0C02 "motherboard" devices are basically a catch-all.  There's no
79programming model for them other than "don't use these resources for
80anything 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
82and (2) should not be assigned by the OS to something else.
83
84The PCIe spec requires the Enhanced Configuration Access Method (ECAM)
85unless there's a standard firmware interface for config access, e.g., the
86ia64 SAL interface [7]. A host bridge consumes ECAM memory address space
87and converts memory accesses into PCI configuration accesses. The spec
88defines the ECAM address space layout and functionality; only the base of
89the address space is device-specific. An ACPI OS learns the base address
90from either the static MCFG table or a _CBA method in the PNP0A03 device.
91
92The MCFG table must describe the ECAM space of non-hot pluggable host
93bridges [8]. Since MCFG is a static table and can't be updated by hotplug,
94a _CBA method in the PNP0A03 device describes the ECAM space of a
95hot-pluggable host bridge [9]. Note that for both MCFG and _CBA, the base
96address 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
3The general rule is that the ACPI namespace should describe everything the
4OS might use unless there's another way for the OS to find it [1, 2].
5
6For example, there's no standard hardware mechanism for enumerating PCI
7host bridges, so the ACPI namespace must describe each host bridge, the
8method for accessing PCI config space below it, the address space windows
9the host bridge forwards to PCI (using _CRS), and the routing of legacy
10INTx interrupts (using _PRT).
11
12PCI devices, which are below the host bridge, generally do not need to be
13described via ACPI. The OS can discover them via the standard PCI
14enumeration mechanism, using config accesses to discover and identify
15devices and read and size their BARs. However, ACPI may describe PCI
16devices if it provides power management or hotplug functionality for them
17or if the device has INTx interrupts connected by platform interrupt
18controllers and a _PRT is needed to describe those connections.
19
20ACPI resource description is done via _CRS objects of devices in the ACPI
21namespace [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
23a driver for the device [3].  That's important because it means an old OS
24can work correctly even on a system with new devices unknown to the OS.
25The new devices might not do anything, but the OS can at least make sure no
26resources conflict with them.
27
28Static tables like MCFG, HPET, ECDT, etc., are *not* mechanisms for
29reserving address space. The static tables are for things the OS needs to
30know early in boot, before it can parse the ACPI namespace. If a new table
31is defined, an old OS needs to operate correctly even though it ignores the
32table. _CRS allows that because it is generic and understood by the old
33OS; a static table does not.
34
35If the OS is expected to manage a non-discoverable device described via
36ACPI, that device will have a specific _HID/_CID that tells the OS what
37driver to bind to it, and the _CRS tells the OS and the driver where the
38device's registers are.
39
40PCI host bridges are PNP0A03 or PNP0A08 devices.  Their _CRS should
41describe all the address space they consume.  This includes all the windows
42they forward down to the PCI bus, as well as registers of the host bridge
43itself that are not forwarded to PCI.  The host bridge registers include
44things like secondary/subordinate bus registers that determine the bus
45range below the bridge, window registers that describe the apertures, etc.
46These are all device-specific, non-architected things, so the only way a
47PNP0A03/PNP0A08 driver can manage them is via _PRS/_CRS/_SRS, which contain
48the device-specific details.  The host bridge registers also include ECAM
49space, since it is consumed by the host bridge.
50
51ACPI defines a Consumer/Producer bit to distinguish the bridge registers
52("Consumer") from the bridge apertures ("Producer") [4, 5], but early
53BIOSes didn't use that bit correctly. The result is that the current ACPI
54spec defines Consumer/Producer only for the Extended Address Space
55descriptors; the bit should be ignored in the older QWord/DWord/Word
56Address Space descriptors. Consequently, OSes have to assume all
57QWord/DWord/Word descriptors are windows.
58
59Prior to the addition of Extended Address Space descriptors, the failure of
60Consumer/Producer meant there was no way to describe bridge registers in
61the PNP0A03/PNP0A08 device itself. The workaround was to describe the
62bridge registers (including ECAM space) in PNP0C02 catch-all devices [6].
63With the exception of ECAM, the bridge register space is device-specific
64anyway, so the generic PNP0A03/PNP0A08 driver (pci_root.c) has no need to
65know about it.  
66
67New architectures should be able to use "Consumer" Extended Address Space
68descriptors in the PNP0A03 device for bridge registers, including ECAM,
69although a strict interpretation of [6] might prohibit this. Old x86 and
70ia64 kernels assume all address space descriptors, including "Consumer"
71Extended Address Space ones, are windows, so it would not be safe to
72describe bridge registers this way on those architectures.
73
74PNP0C02 "motherboard" devices are basically a catch-all.  There's no
75programming model for them other than "don't use these resources for
76anything 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
78and (2) should not be assigned by the OS to something else.
79
80The PCIe spec requires the Enhanced Configuration Access Method (ECAM)
81unless there's a standard firmware interface for config access, e.g., the
82ia64 SAL interface [7]. A host bridge consumes ECAM memory address space
83and converts memory accesses into PCI configuration accesses. The spec
84defines the ECAM address space layout and functionality; only the base of
85the address space is device-specific. An ACPI OS learns the base address
86from either the static MCFG table or a _CBA method in the PNP0A03 device.
87
88The MCFG table must describe the ECAM space of non-hot pluggable host
89bridges [8]. Since MCFG is a static table and can't be updated by hotplug,
90a _CBA method in the PNP0A03 device describes the ECAM space of a
91hot-pluggable host bridge [9]. Note that for both MCFG and _CBA, the base
92address 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======================
4PCI 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=======================================
4Configuring PCI Endpoint Using CONFIGFS
5=======================================
6
7:Author: Kishon Vijay Abraham I <kishon@ti.com>
8
9The PCI Endpoint Core exposes configfs entry (pci_ep) to configure the
10PCI endpoint function and to bind the endpoint function
11with the endpoint controller. (For introducing other mechanisms to
12configure the PCI Endpoint Function refer to [1]).
13
14Mounting configfs
15=================
16
17The PCI Endpoint Core layer creates pci_ep directory in the mounted configfs
18directory. configfs can be mounted using the following command::
19
20 mount -t configfs none /sys/kernel/config
21
22Directory Structure
23===================
24
25The pci_ep configfs has two directories at its root: controllers and
26functions. Every EPC device present in the system will have an entry in
27the *controllers* directory and and every EPF driver present in the system
28will have an entry in the *functions* directory.
29::
30
31 /sys/kernel/config/pci_ep/
32 .. controllers/
33 .. functions/
34
35Creating EPF Device
36===================
37
38Every registered EPF driver will be listed in controllers directory. The
39entries 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
50In order to create a <EPF device> of the type probed by <EPF Driver>, the
51user has to create a directory inside <EPF DriverN>.
52
53Every <EPF device> directory consists of the following entries that can be
54used to configure the standard configuration header of the endpoint function.
55(These entries are created by the framework when any new <EPF Device> is
56created)
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
72EPC Device
73==========
74
75Every registered EPC device will be listed in controllers directory. The
76entries 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
89The <EPC Device> directory will have a list of symbolic links to
90<EPF Device>. These symbolic links should be created by the user to
91represent the functions present in the endpoint device.
92
93The <EPC Device> directory will also have a *start* field. Once
94"1" is written to this field, the endpoint device will be ready to
95establish the link with the host. This is usually done after
96all 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
4The PCI Endpoint Core exposes configfs entry (pci_ep) to configure the
5PCI endpoint function and to bind the endpoint function
6with the endpoint controller. (For introducing other mechanisms to
7configure the PCI Endpoint Function refer to [1]).
8
9*) Mounting configfs
10
11The PCI Endpoint Core layer creates pci_ep directory in the mounted configfs
12directory. configfs can be mounted using the following command.
13
14 mount -t configfs none /sys/kernel/config
15
16*) Directory Structure
17
18The pci_ep configfs has two directories at its root: controllers and
19functions. Every EPC device present in the system will have an entry in
20the *controllers* directory and and every EPF driver present in the system
21will have an entry in the *functions* directory.
22
23/sys/kernel/config/pci_ep/
24 .. controllers/
25 .. functions/
26
27*) Creating EPF Device
28
29Every registered EPF driver will be listed in controllers directory. The
30entries 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
40In order to create a <EPF device> of the type probed by <EPF Driver>, the
41user has to create a directory inside <EPF DriverN>.
42
43Every <EPF device> directory consists of the following entries that can be
44used to configure the standard configuration header of the endpoint function.
45(These entries are created by the framework when any new <EPF Device> is
46created)
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
63Every registered EPC device will be listed in controllers directory. The
64entries 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
76The <EPC Device> directory will have a list of symbolic links to
77<EPF Device>. These symbolic links should be created by the user to
78represent the functions present in the endpoint device.
79
80The <EPC Device> directory will also have a *start* field. Once
81"1" is written to this field, the endpoint device will be ready to
82establish the link with the host. This is usually done after
83all 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
5This document is a guide to use the PCI Endpoint Framework in order to create
6endpoint controller driver, endpoint function driver, and using configfs
7interface to bind the function driver to the controller driver.
8
9Introduction
10============
11
12Linux has a comprehensive PCI subsystem to support PCI controllers that
13operates in Root Complex mode. The subsystem has capability to scan PCI bus,
14assign memory resources and IRQ resources, load PCI driver (based on
15vendor ID, device ID), support other services like hot-plug, power management,
16advanced error reporting and virtual channels.
17
18However the PCI controller IP integrated in some SoCs is capable of operating
19either in Root Complex mode or Endpoint mode. PCI Endpoint Framework will
20add endpoint mode support in Linux. This will help to run Linux in an
21EP system which can have a wide variety of use cases from testing or
22validation, co-processor accelerator, etc.
23
24PCI Endpoint Core
25=================
26
27The PCI Endpoint Core layer comprises 3 components: the Endpoint Controller
28library, the Endpoint Function library, and the configfs layer to bind the
29endpoint function with the endpoint controller.
30
31PCI Endpoint Controller(EPC) Library
32------------------------------------
33
34The EPC library provides APIs to be used by the controller that can operate
35in endpoint mode. It also provides APIs to be used by function driver/library
36in order to implement a particular endpoint function.
37
38APIs for the PCI controller Driver
39~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
40
41This section lists the APIs that the PCI Endpoint core provides to be used
42by 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
81APIs for the PCI Endpoint Function Driver
82~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
83
84This section lists the APIs that the PCI Endpoint core provides to be used
85by 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
120Other APIs
121~~~~~~~~~~
122
123There are other APIs provided by the EPC library. These are used for binding
124the EPF device with EPC device. pci-ep-cfs.c can be used as reference for
125using 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
157PCI Endpoint Function(EPF) Library
158----------------------------------
159
160The EPF library provides APIs to be used by the function driver and the EPC
161library to provide endpoint mode functionality.
162
163APIs for the PCI Endpoint Function Driver
164~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
165
166This section lists the APIs that the PCI Endpoint core provides to be used
167by 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
196APIs for the PCI Endpoint Controller Library
197~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
198
199This section lists the APIs that the PCI Endpoint core provides to be used
200by 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
207Other APIs
208~~~~~~~~~~
209
210There are other APIs provided by the EPF library. These are used to notify
211the function driver when the EPF device is bound to the EPC device.
212pci-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
4This document is a guide to use the PCI Endpoint Framework in order to create
5endpoint controller driver, endpoint function driver, and using configfs
6interface to bind the function driver to the controller driver.
7
81. Introduction
9
10Linux has a comprehensive PCI subsystem to support PCI controllers that
11operates in Root Complex mode. The subsystem has capability to scan PCI bus,
12assign memory resources and IRQ resources, load PCI driver (based on
13vendor ID, device ID), support other services like hot-plug, power management,
14advanced error reporting and virtual channels.
15
16However the PCI controller IP integrated in some SoCs is capable of operating
17either in Root Complex mode or Endpoint mode. PCI Endpoint Framework will
18add endpoint mode support in Linux. This will help to run Linux in an
19EP system which can have a wide variety of use cases from testing or
20validation, co-processor accelerator, etc.
21
222. PCI Endpoint Core
23
24The PCI Endpoint Core layer comprises 3 components: the Endpoint Controller
25library, the Endpoint Function library, and the configfs layer to bind the
26endpoint function with the endpoint controller.
27
282.1 PCI Endpoint Controller(EPC) Library
29
30The EPC library provides APIs to be used by the controller that can operate
31in endpoint mode. It also provides APIs to be used by function driver/library
32in order to implement a particular endpoint function.
33
342.1.1 APIs for the PCI controller Driver
35
36This section lists the APIs that the PCI Endpoint core provides to be used
37by 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
742.1.2 APIs for the PCI Endpoint Function Driver
75
76This section lists the APIs that the PCI Endpoint core provides to be used
77by 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
1122.1.3 Other APIs
113
114There are other APIs provided by the EPC library. These are used for binding
115the EPF device with EPC device. pci-ep-cfs.c can be used as reference for
116using 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
1472.2 PCI Endpoint Function(EPF) Library
148
149The EPF library provides APIs to be used by the function driver and the EPC
150library to provide endpoint mode functionality.
151
1522.2.1 APIs for the PCI Endpoint Function Driver
153
154This section lists the APIs that the PCI Endpoint core provides to be used
155by 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
1842.2.2 APIs for the PCI Endpoint Controller Library
185This section lists the APIs that the PCI Endpoint core provides to be used
186by 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
1932.2.2 Other APIs
194There are other APIs provided by the EPF library. These are used to notify
195the function driver when the EPF device is bound to the EPC device.
196pci-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=================
4PCI Test Function
5=================
6
7:Author: Kishon Vijay Abraham I <kishon@ti.com>
8
9Traditionally PCI RC has always been validated by using standard
10PCI cards like ethernet PCI cards or USB PCI cards or SATA PCI cards.
11However with the addition of EP-core in linux kernel, it is possible
12to configure a PCI controller that can operate in EP mode to work as
13a test device.
14
15The PCI endpoint test device is a virtual device (defined in software)
16used to test the endpoint functionality and serve as a sample driver
17for other PCI endpoint devices (to use the EP framework).
18
19The 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
33This register will be used to test BAR0. A known pattern will be written
34and read back from MAGIC register to verify BAR0.
35
36* PCI_ENDPOINT_TEST_COMMAND
37
38This register will be used by the host driver to indicate the function
39that the endpoint device must perform.
40
41======== ================================================================
42Bitfield Description
43======== ================================================================
44Bit 0 raise legacy IRQ
45Bit 1 raise MSI IRQ
46Bit 2 raise MSI-X IRQ
47Bit 3 read command (read data from RC buffer)
48Bit 4 write command (write data to RC buffer)
49Bit 5 copy command (copy data from one RC buffer to another RC buffer)
50======== ================================================================
51
52* PCI_ENDPOINT_TEST_STATUS
53
54This register reflects the status of the PCI endpoint device.
55
56======== ==============================
57Bitfield Description
58======== ==============================
59Bit 0 read success
60Bit 1 read fail
61Bit 2 write success
62Bit 3 write fail
63Bit 4 copy success
64Bit 5 copy fail
65Bit 6 IRQ raised
66Bit 7 source address is invalid
67Bit 8 destination address is invalid
68======== ==============================
69
70* PCI_ENDPOINT_TEST_SRC_ADDR
71
72This register contains the source address (RC buffer address) for the
73COPY/READ command.
74
75* PCI_ENDPOINT_TEST_DST_ADDR
76
77This register contains the destination address (RC buffer address) for
78the COPY/WRITE command.
79
80* PCI_ENDPOINT_TEST_IRQ_TYPE
81
82This register contains the interrupt type (Legacy/MSI) triggered
83for the READ/WRITE/COPY and raise IRQ (Legacy/MSI) commands.
84
85Possible types:
86
87====== ==
88Legacy 0
89MSI 1
90MSI-X 2
91====== ==
92
93* PCI_ENDPOINT_TEST_IRQ_NUMBER
94
95This register contains the triggered ID interrupt.
96
97Admissible values:
98
99====== ===========
100Legacy 0
101MSI [1 .. 32]
102MSI-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
4Traditionally PCI RC has always been validated by using standard
5PCI cards like ethernet PCI cards or USB PCI cards or SATA PCI cards.
6However with the addition of EP-core in linux kernel, it is possible
7to configure a PCI controller that can operate in EP mode to work as
8a test device.
9
10The PCI endpoint test device is a virtual device (defined in software)
11used to test the endpoint functionality and serve as a sample driver
12for other PCI endpoint devices (to use the EP framework).
13
14The 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
28This register will be used to test BAR0. A known pattern will be written
29and read back from MAGIC register to verify BAR0.
30
31*) PCI_ENDPOINT_TEST_COMMAND:
32
33This register will be used by the host driver to indicate the function
34that the endpoint device must perform.
35
36Bitfield 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
47This register reflects the status of the PCI endpoint device.
48
49Bitfield 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
62This register contains the source address (RC buffer address) for the
63COPY/READ command.
64
65*) PCI_ENDPOINT_TEST_DST_ADDR
66
67This register contains the destination address (RC buffer address) for
68the COPY/WRITE command.
69
70*) PCI_ENDPOINT_TEST_IRQ_TYPE
71
72This register contains the interrupt type (Legacy/MSI) triggered
73for the READ/WRITE/COPY and raise IRQ (Legacy/MSI) commands.
74
75Possible types:
76 - Legacy : 0
77 - MSI : 1
78 - MSI-X : 2
79
80*) PCI_ENDPOINT_TEST_IRQ_NUMBER
81
82This register contains the triggered ID interrupt.
83
84Admissible 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===================
4PCI Test User Guide
5===================
6
7:Author: Kishon Vijay Abraham I <kishon@ti.com>
8
9This document is a guide to help users use pci-epf-test function driver
10and pci_endpoint_test host driver for testing PCI. The list of steps to
11be followed in the host side and EP side is given below.
12
13Endpoint Device
14===============
15
16Endpoint Controller Devices
17---------------------------
18
19To find the list of endpoint controller devices in the system::
20
21 # ls /sys/class/pci_epc/
22 51000000.pcie_ep
23
24If PCI_ENDPOINT_CONFIGFS is enabled::
25
26 # ls /sys/kernel/config/pci_ep/controllers
27 51000000.pcie_ep
28
29
30Endpoint Function Drivers
31-------------------------
32
33To find the list of endpoint function drivers in the system::
34
35 # ls /sys/bus/pci-epf/drivers
36 pci_epf_test
37
38If PCI_ENDPOINT_CONFIGFS is enabled::
39
40 # ls /sys/kernel/config/pci_ep/functions
41 pci_epf_test
42
43
44Creating pci-epf-test Device
45----------------------------
46
47PCI endpoint function device can be created using the configfs. To create
48pci-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
54The "mkdir func1" above creates the pci-epf-test function device that will
55be probed by pci_epf_test driver.
56
57The PCI endpoint framework populates the directory with the following
58configurable 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
65The PCI endpoint function driver populates these entries with default values
66when the device is bound to the driver. The pci-epf-test driver populates
67vendorid 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
75Configuring pci-epf-test Device
76-------------------------------
77
78The user can configure the pci-epf-test device using configfs entry. In order
79to change the vendorid and the number of MSI interrupts used by the function
80device, 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
88Binding pci-epf-test Device to EP Controller
89--------------------------------------------
90
91In order for the endpoint function device to be useful, it has to be bound to
92a PCI endpoint controller driver. Use the configfs to bind the function
93device to one of the controller driver present in the system::
94
95 # ln -s functions/pci_epf_test/func1 controllers/51000000.pcie_ep/
96
97Once the above step is completed, the PCI endpoint is ready to establish a link
98with the host.
99
100
101Start the Link
102--------------
103
104In order for the endpoint device to establish a link with the host, the _start_
105field should be populated with '1'::
106
107 # echo 1 > controllers/51000000.pcie_ep/start
108
109
110RootComplex Device
111==================
112
113lspci Output
114------------
115
116Note that the devices listed here correspond to the value populated in 1.4
117above::
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
123Using Endpoint Test function Device
124-----------------------------------
125
126pcitest.sh added in tools/pci/ can be used to run all the default PCI endpoint
127tests. To compile this tool the following commands should be used::
128
129 # cd <kernel-dir>
130 # make -C tools/pci
131
132or if you desire to compile and install in your system::
133
134 # cd <kernel-dir>
135 # make -C tools/pci install
136
137The tool and script will be located in <rootfs>/usr/bin/
138
139
140pcitest.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
4This document is a guide to help users use pci-epf-test function driver
5and pci_endpoint_test host driver for testing PCI. The list of steps to
6be followed in the host side and EP side is given below.
7
81. Endpoint Device
9
101.1 Endpoint Controller Devices
11
12To find the list of endpoint controller devices in the system:
13
14 # ls /sys/class/pci_epc/
15 51000000.pcie_ep
16
17If PCI_ENDPOINT_CONFIGFS is enabled
18 # ls /sys/kernel/config/pci_ep/controllers
19 51000000.pcie_ep
20
211.2 Endpoint Function Drivers
22
23To find the list of endpoint function drivers in the system:
24
25 # ls /sys/bus/pci-epf/drivers
26 pci_epf_test
27
28If PCI_ENDPOINT_CONFIGFS is enabled
29 # ls /sys/kernel/config/pci_ep/functions
30 pci_epf_test
31
321.3 Creating pci-epf-test Device
33
34PCI endpoint function device can be created using the configfs. To create
35pci-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
41The "mkdir func1" above creates the pci-epf-test function device that will
42be probed by pci_epf_test driver.
43
44The PCI endpoint framework populates the directory with the following
45configurable 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
52The PCI endpoint function driver populates these entries with default values
53when the device is bound to the driver. The pci-epf-test driver populates
54vendorid 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
611.4 Configuring pci-epf-test Device
62
63The user can configure the pci-epf-test device using configfs entry. In order
64to change the vendorid and the number of MSI interrupts used by the function
65device, 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
721.5 Binding pci-epf-test Device to EP Controller
73
74In order for the endpoint function device to be useful, it has to be bound to
75a PCI endpoint controller driver. Use the configfs to bind the function
76device to one of the controller driver present in the system.
77
78 # ln -s functions/pci_epf_test/func1 controllers/51000000.pcie_ep/
79
80Once the above step is completed, the PCI endpoint is ready to establish a link
81with the host.
82
831.6 Start the Link
84
85In order for the endpoint device to establish a link with the host, the _start_
86field should be populated with '1'.
87
88 # echo 1 > controllers/51000000.pcie_ep/start
89
902. RootComplex Device
91
922.1 lspci Output
93
94Note 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
992.2 Using Endpoint Test function Device
100
101pcitest.sh added in tools/pci/ can be used to run all the default PCI endpoint
102tests. To compile this tool the following commands should be used:
103
104 # cd <kernel-dir>
105 # make -C tools/pci
106
107or if you desire to compile and install in your system:
108
109 # cd <kernel-dir>
110 # make -C tools/pci install
111
112The tool and script will be located in <rootfs>/usr/bin/
113
1142.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=======================
4Linux 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==========================
5The MSI Driver Guide HOWTO
6==========================
7
8:Authors: Tom L Nguyen; Martine Silbermann; Matthew Wilcox
9
10:Copyright: 2003, 2008 Intel Corporation
11
12About this guide
13================
14
15This guide describes the basics of Message Signaled Interrupts (MSIs),
16the advantages of using MSI over traditional interrupt mechanisms, how
17to change your driver to use MSI or MSI-X and some basic diagnostics to
18try if a device doesn't support MSIs.
19
20
21What are MSIs?
22==============
23
24A Message Signaled Interrupt is a write from the device to a special
25address which causes an interrupt to be received by the CPU.
26
27The MSI capability was first specified in PCI 2.2 and was later enhanced
28in PCI 3.0 to allow each interrupt to be masked individually. The MSI-X
29capability was also introduced with PCI 3.0. It supports more interrupts
30per device than MSI and allows interrupts to be independently configured.
31
32Devices may support both MSI and MSI-X, but only one can be enabled at
33a time.
34
35
36Why use MSIs?
37=============
38
39There are three reasons why using MSIs can give an advantage over
40traditional pin-based interrupts.
41
42Pin-based PCI interrupts are often shared amongst several devices.
43To support this, the kernel must call each interrupt handler associated
44with an interrupt, which leads to reduced performance for the system as
45a whole. MSIs are never shared, so this problem cannot arise.
46
47When a device writes data to memory, then raises a pin-based interrupt,
48it is possible that the interrupt may arrive before all the data has
49arrived in memory (this becomes more likely with devices behind PCI-PCI
50bridges). In order to ensure that all the data has arrived in memory,
51the interrupt handler must read a register on the device which raised
52the interrupt. PCI transaction ordering rules require that all the data
53arrive in memory before the value may be returned from the register.
54Using MSIs avoids this problem as the interrupt-generating write cannot
55pass the data writes, so by the time the interrupt is raised, the driver
56knows that all the data has arrived in memory.
57
58PCI devices can only support a single pin-based interrupt per function.
59Often drivers have to query the device to find out what event has
60occurred, slowing down interrupt handling for the common case. With
61MSIs, a device can support more interrupts, allowing each interrupt
62to be specialised to a different purpose. One possible design gives
63infrequent conditions (such as errors) their own interrupt which allows
64the driver to handle the normal interrupt handling path more efficiently.
65Other possible designs include giving one interrupt to each packet queue
66in a network card or each port in a storage controller.
67
68
69How to use MSIs
70===============
71
72PCI devices are initialised to use pin-based interrupts. The device
73driver has to set up the device to use MSI or MSI-X. Not all machines
74support MSIs correctly, and for those machines, the APIs described below
75will simply fail and the device will continue to use pin-based interrupts.
76
77Include kernel support for MSIs
78-------------------------------
79
80To support MSI or MSI-X, the kernel must be built with the CONFIG_PCI_MSI
81option enabled. This option is only available on some architectures,
82and it may depend on some other options also being set. For example,
83on x86, you must also enable X86_UP_APIC or SMP in order to see the
84CONFIG_PCI_MSI option.
85
86Using MSI
87---------
88
89Most of the hard work is done for the driver in the PCI layer. The driver
90simply has to request that the PCI layer set up the MSI capability for this
91device.
92
93To automatically use MSI or MSI-X interrupt vectors, use the following
94function::
95
96 int pci_alloc_irq_vectors(struct pci_dev *dev, unsigned int min_vecs,
97 unsigned int max_vecs, unsigned int flags);
98
99which allocates up to max_vecs interrupt vectors for a PCI device. It
100returns the number of vectors allocated or a negative error. If the device
101has a requirements for a minimum number of vectors the driver can pass a
102min_vecs argument set to this limit, and the PCI core will return -ENOSPC
103if it can't meet the minimum number of vectors.
104
105The flags argument is used to specify which type of interrupt can be used
106by the device and the driver (PCI_IRQ_LEGACY, PCI_IRQ_MSI, PCI_IRQ_MSIX).
107A convenient short-hand (PCI_IRQ_ALL_TYPES) is also available to ask for
108any possible kind of interrupt. If the PCI_IRQ_AFFINITY flag is set,
109pci_alloc_irq_vectors() will spread the interrupts around the available CPUs.
110
111To get the Linux IRQ numbers passed to request_irq() and free_irq() and the
112vectors, use the following function::
113
114 int pci_irq_vector(struct pci_dev *dev, unsigned int nr);
115
116Any allocated resources should be freed before removing the device using
117the following function::
118
119 void pci_free_irq_vectors(struct pci_dev *dev);
120
121If a device supports both MSI-X and MSI capabilities, this API will use the
122MSI-X facilities in preference to the MSI facilities. MSI-X supports any
123number of interrupts between 1 and 2048. In contrast, MSI is restricted to
124a maximum of 32 interrupts (and must be a power of two). In addition, the
125MSI interrupt vectors must be allocated consecutively, so the system might
126not be able to allocate as many vectors for MSI as it could for MSI-X. On
127some platforms, MSI interrupts must all be targeted at the same set of CPUs
128whereas MSI-X interrupts can all be targeted at different CPUs.
129
130If a device supports neither MSI-X or MSI it will fall back to a single
131legacy IRQ vector.
132
133The typical usage of MSI or MSI-X interrupts is to allocate as many vectors
134as possible, likely up to the limit supported by the device. If nvec is
135larger than the number supported by the device it will automatically be
136capped to the supported limit, so there is no need to query the number of
137vectors 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
143If a driver is unable or unwilling to deal with a variable number of MSI
144interrupts it can request a particular number of interrupts by passing that
145number 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
152The most notorious example of the request type described above is enabling
153the 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
160Some devices might not support using legacy line interrupts, in which case
161the 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
167Legacy APIs
168-----------
169
170The following old APIs to enable and disable MSI or MSI-X interrupts should
171not 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
179Additionally there are APIs to provide the number of supported MSI or MSI-X
180vectors: pci_msi_vec_count() and pci_msix_vec_count(). In general these
181should be avoided in favor of letting pci_alloc_irq_vectors() cap the
182number of vectors. If you have a legitimate special use case for the count
183of vectors we might have to revisit that decision and add a
184pci_nr_irq_vectors() helper that handles MSI and MSI-X transparently.
185
186Considerations when using MSIs
187------------------------------
188
189Spinlocks
190~~~~~~~~~
191
192Most device drivers have a per-device spinlock which is taken in the
193interrupt handler. With pin-based interrupts or a single MSI, it is not
194necessary to disable interrupts (Linux guarantees the same interrupt will
195not be re-entered). If a device uses multiple interrupts, the driver
196must disable interrupts while the lock is held. If the device sends
197a different interrupt, the driver will deadlock trying to recursively
198acquire the spinlock. Such deadlocks can be avoided by using
199spin_lock_irqsave() or spin_lock_irq() which disable local interrupts
200and acquire the lock (see Documentation/kernel-hacking/locking.rst).
201
202How to tell whether MSI/MSI-X is enabled on a device
203----------------------------------------------------
204
205Using 'lspci -v' (as root) may show some devices with "MSI", "Message
206Signalled Interrupts" or "MSI-X" capabilities. Each of these capabilities
207has an 'Enable' flag which is followed with either "+" (enabled)
208or "-" (disabled).
209
210
211MSI quirks
212==========
213
214Several PCI chipsets or devices are known not to support MSIs.
215The PCI stack provides three ways to disable MSIs:
216
2171. globally
2182. on all devices behind a specific bridge
2193. on a single device
220
221Disabling MSIs globally
222-----------------------
223
224Some host chipsets simply don't support MSIs properly. If we're
225lucky, the manufacturer knows this and has indicated it in the ACPI
226FADT table. In this case, Linux automatically disables MSIs.
227Some boards don't include this information in the table and so we have
228to detect them ourselves. The complete list of these is found near the
229quirk_disable_all_msi() function in drivers/pci/quirks.c.
230
231If you have a board which has problems with MSIs, you can pass pci=nomsi
232on the kernel command line to disable MSIs on all devices. It would be
233in your best interests to report the problem to linux-pci@vger.kernel.org
234including a full 'lspci -v' so we can add the quirks to the kernel.
235
236Disabling MSIs below a bridge
237-----------------------------
238
239Some PCI bridges are not able to route MSIs between busses properly.
240In this case, MSIs must be disabled on all devices behind the bridge.
241
242Some bridges allow you to enable MSIs by changing some bits in their
243PCI configuration space (especially the Hypertransport chipsets such
244as the nVidia nForce and Serverworks HT2000). As with host chipsets,
245Linux mostly knows about them and automatically enables MSIs if it can.
246If you have a bridge unknown to Linux, you can enable
247MSIs in configuration space using whatever method you know works, then
248enable MSIs on that bridge by doing::
249
250 echo 1 > /sys/bus/pci/devices/$bridge/msi_bus
251
252where $bridge is the PCI address of the bridge you've enabled (eg
2530000:00:0e.0).
254
255To disable MSIs, echo 0 instead of 1. Changing this value should be
256done with caution as it could break interrupt handling for all devices
257below this bridge.
258
259Again, please notify linux-pci@vger.kernel.org of any bridges that need
260special handling.
261
262Disabling MSIs on a single device
263---------------------------------
264
265Some devices are known to have faulty MSI implementations. Usually this
266is handled in the individual device driver, but occasionally it's necessary
267to handle this with a quirk. Some drivers have an option to disable use
268of MSI. While this is a convenient workaround for the driver author,
269it is not good practice, and should not be emulated.
270
271Finding why MSIs are disabled on a device
272-----------------------------------------
273
274From the above three sections, you can see that there are many reasons
275why MSIs may not be enabled for a given device. Your first step should
276be to examine your dmesg carefully to determine whether MSIs are enabled
277for your machine. You should also check your .config to be sure you
278have enabled CONFIG_PCI_MSI.
279
280Then, '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)
282or disabled (0). If 0 is found in any of the msi_bus files belonging
283to bridges between the PCI root and the device, MSIs are disabled.
284
285It is also worth checking the device driver to see whether it supports MSIs.
286For example, it may contain calls to pci_irq_alloc_vectors() with the
287PCI_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==================
4PCI 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
13Many PCI bus controllers are able to detect a variety of hardware
14PCI errors on the bus, such as parity errors on the data and address
15buses, as well as SERR and PERR errors. Some of the more advanced
16chipsets are able to deal with these errors; these include PCI-E chipsets,
17and the PCI-host bridges found on IBM Power4, Power5 and Power6-based
18pSeries boxes. A typical action taken is to disconnect the affected device,
19halting all I/O to it. The goal of a disconnection is to avoid system
20corruption; for example, to halt system memory corruption due to DMA's
21to "wild" addresses. Typically, a reconnection mechanism is also
22offered, so that the affected PCI device(s) are reset and put back
23into working condition. The reset phase requires coordination
24between the affected device drivers and the PCI controller chip.
25This document describes a generic API for notifying device drivers
26of a bus disconnection, and then performing error recovery.
27This API is currently implemented in the 2.6.16 and later kernels.
28
29Reporting and recovery is performed in several steps. First, when
30a PCI hardware error has resulted in a bus disconnect, that event
31is reported as soon as possible to all affected device drivers,
32including multiple instances of a device driver on multi-function
33cards. This allows device drivers to avoid deadlocking in spinloops,
34waiting for some i/o-space register to change, when it never will.
35It also gives the drivers a chance to defer incoming I/O as
36needed.
37
38Next, recovery is performed in several stages. Most of the complexity
39is forced by the need to handle multi-function devices, that is,
40devices that have multiple device drivers associated with them.
41In the first stage, each driver is allowed to indicate what type
42of reset it desires, the choices being a simple re-enabling of I/O
43or requesting a slot reset.
44
45If any driver requests a slot reset, that is what will be done.
46
47After a reset and/or a re-enabling of I/O, all drivers are
48again notified, so that they may then perform any device setup/config
49that may be required. After these have all completed, a final
50"resume normal operations" event is sent out.
51
52The biggest reason for choosing a kernel-based implementation rather
53than a user-space implementation was the need to deal with bus
54disconnects of PCI devices attached to storage media, and, in particular,
55disconnects from devices holding the root file system. If the root
56file system is disconnected, a user-space mechanism would have to go
57through a large number of contortions to complete recovery. Almost all
58of the current Linux file systems are not tolerant of disconnection
59from/reconnection to their underlying block device. By contrast,
60bus errors are easy to manage in the device driver. Indeed, most
61device drivers already handle very similar recovery procedures;
62for example, the SCSI-generic layer already provides significant
63mechanisms for dealing with SCSI bus errors and SCSI bus resets.
64
65
66Detailed Design
67===============
68
69Design and implementation details below, based on a chain of
70public email discussions with Ben Herrenschmidt, circa 5 April 2005.
71
72The error recovery API support is exposed to the driver in the form of
73a structure of function pointers pointed to by a new field in struct
74pci_driver. A driver that fails to provide the structure is "non-aware",
75and the actual recovery steps taken are platform dependent. The
76arch/powerpc implementation will simulate a PCI hotplug remove/add.
77
78This 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
88The 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
96Possible 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
106A driver does not have to implement all of these callbacks; however,
107if it implements any, it must implement error_detected(). If a callback
108is not implemented, the corresponding feature is considered unsupported.
109For example, if mmio_enabled() and resume() aren't there, then it
110is assumed that the driver is not doing any direct recovery and requires
111a slot reset. Typically a driver will want to know about
112a slot_reset().
113
114The actual steps taken by a platform to recover from a PCI error
115event will be platform-dependent, but will follow the general
116sequence described below.
117
118STEP 0: Error Event
119-------------------
120A PCI bus error is detected by the PCI hardware. On powerpc, the slot
121is isolated, in that all I/O is blocked: all reads return 0xffffffff,
122all writes are ignored.
123
124
125STEP 1: Notification
126--------------------
127Platform calls the error_detected() callback on every instance of
128every driver affected by the error.
129
130At this point, the device might not be accessible anymore, depending on
131the platform (the slot will be isolated on powerpc). The driver may
132already have "noticed" the error because of a failing I/O, but this
133is the proper "synchronization point", that is, it gives the driver
134a chance to cleanup, waiting for pending stuff (timers, whatever, etc...)
135to complete; it can take semaphores, schedule, etc... everything but
136touch the device. Within this function and after it returns, the driver
137shouldn'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
140All drivers participating in this system must implement this call.
141The 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
154The next step taken will depend on the result codes returned by the
155drivers.
156
157If all drivers on the segment/slot return PCI_ERS_RESULT_CAN_RECOVER,
158then the platform should re-enable IOs on the slot (or do nothing in
159particular, if the platform doesn't isolate slots), and recovery
160proceeds to STEP 2 (MMIO Enable).
161
162If any driver requested a slot reset (by returning PCI_ERS_RESULT_NEED_RESET),
163then recovery proceeds to STEP 4 (Slot Reset).
164
165If the platform is unable to recover the slot, the next step
166is 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
187STEP 2: MMIO Enabled
188--------------------
189The platform re-enables MMIO to the device (but typically not the
190DMA), and then calls the mmio_enabled() callback on all affected
191device drivers.
192
193This is the "early recovery" call. IOs are allowed again, but DMA is
194not, with some restrictions. This is NOT a callback for the driver to
195start operations again, only to peek/poke at the device, extract diagnostic
196information, if any, and eventually do things like trigger a device local
197reset or some such, but not restart operations. This callback is made if
198all drivers on a segment agree that they can try to recover and if no automatic
199link reset was performed by the HW. If the platform can't just re-enable IOs
200without a slot reset or a link reset, it will not call this callback, and
201instead 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
215The 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
234The next step taken depends on the results returned by the drivers.
235If all drivers returned PCI_ERS_RESULT_RECOVERED, then the platform
236proceeds to either STEP3 (Link Reset) or to STEP 5 (Resume Operations).
237
238If any driver returned PCI_ERS_RESULT_NEED_RESET, then the platform
239proceeds to STEP 4 (Slot Reset)
240
241STEP 3: Link Reset
242------------------
243The platform resets the link. This is a PCI-Express specific step
244and is done whenever a fatal error has been detected that can be
245"solved" by resetting the link.
246
247STEP 4: Slot Reset
248------------------
249
250In response to a return value of PCI_ERS_RESULT_NEED_RESET, the
251the platform will perform a slot reset on the requesting PCI device(s).
252The actual steps taken by a platform to perform a slot reset
253will be platform-dependent. Upon completion of slot reset, the
254platform will call the device slot_reset() callback.
255
256Powerpc platforms implement two levels of slot reset:
257soft reset(default) and fundamental(optional) reset.
258
259Powerpc soft reset consists of asserting the adapter #RST line and then
260restoring the PCI BAR's and PCI configuration header to a state
261that is equivalent to what it would be after a fresh system
262power-on followed by power-on BIOS/system firmware initialization.
263Soft reset is also known as hot-reset.
264
265Powerpc fundamental reset is supported by PCI Express cards only
266and results in device's state machines, hardware logic, port states and
267configuration registers to initialize to their default conditions.
268
269For most PCI devices, a soft reset will be sufficient for recovery.
270Optional fundamental reset is provided to support a limited number
271of PCI Express devices for which a soft reset is not sufficient
272for recovery.
273
274If the platform supports PCI hotplug, then the reset might be
275performed by toggling the slot electrical power off/on.
276
277It is important for the platform to restore the PCI config space
278to the "fresh poweron" state, rather than the "last state". After
279a slot reset, the device driver will almost always use its standard
280device initialization routines, and an unusual config space setup
281may result in hung devices, kernel panics, or silent data corruption.
282
283This call gives drivers the chance to re-initialize the hardware
284(re-download firmware, etc.). At this point, the driver may assume
285that the card is in a fresh state and is fully functional. The slot
286is unfrozen and the driver has full access to PCI config space,
287memory mapped I/O space and DMA. Interrupts (Legacy, MSI, or MSI-X)
288will also be available.
289
290Drivers should not restart normal I/O processing operations
291at this point. If all device drivers report success on this
292callback, the platform will call resume() to complete the sequence,
293and let the driver restart normal I/O processing.
294
295A driver can still return a critical failure for this function if
296it can't get the device operational after reset. If the platform
297previously tried a soft reset, it might now try a hard reset (power
298cycle) and then call slot_reset() again. It the device still can't
299be recovered, there is nothing more that can be done; the platform
300will typically report a "permanent failure" in such a case. The
301device will be considered "dead" in this case.
302
303Drivers for multi-function cards will need to coordinate among
304themselves as to which driver instance will perform any "one-shot"
305or global device initialization. For example, the Symbios sym53cxx2
306driver performs device init only from PCI function 0::
307
308 + if (PCI_FUNC(pdev->devfn) == 0)
309 + sym_reset_scsi_bus(np, 0);
310
311Result codes:
312 - PCI_ERS_RESULT_DISCONNECT
313 Same as above.
314
315Drivers for PCI Express cards that require a fundamental reset must
316set the needs_freset bit in the pci_dev structure in their probe function.
317For example, the QLogic qla2xxx driver sets the needs_freset bit for certain
318PCI 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
325Platform proceeds either to STEP 5 (Resume Operations) or STEP 6 (Permanent
326Failure).
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
335STEP 5: Resume Operations
336-------------------------
337The platform will call the resume() callback on all affected device
338drivers if all drivers on the segment have returned
339PCI_ERS_RESULT_RECOVERED from one of the 3 previous callbacks.
340The goal of this callback is to tell the driver to restart activity,
341that everything is back and running. This callback does not return
342a result code.
343
344At this point, if a new error happens, the platform will restart
345a new error recovery sequence.
346
347STEP 6: Permanent Failure
348-------------------------
349A "permanent failure" has occurred, and the platform cannot recover
350the device. The platform will call error_detected() with a
351pci_channel_state value of pci_channel_io_perm_failure.
352
353The device driver should, at this point, assume the worst. It should
354cancel all pending I/O, refuse all new I/O, returning -EIO to
355higher layers. The device driver should then clean up all of its
356memory and remove itself from kernel operations, much as it would
357during system shutdown.
358
359The platform will typically notify the system operator of the
360permanent failure in some way. If the device is hotplug-capable,
361the operator will probably want to remove and replace the device.
362Note, however, not all failures are truly "permanent". Some are
363caused by over-heating, some by a poorly seated card. Many
364PCI error events are caused by software bugs, e.g. DMA's to
365wild addresses or bogus split transactions due to programming
366errors. See the discussion in powerpc/eeh-pci-error-recovery.txt
367for additional detail on real-life experience of the causes of
368software errors.
369
370
371Conclusion; General Remarks
372---------------------------
373The way the callbacks are called is platform policy. A platform with
374no slot reset capability may want to just "ignore" drivers that can't
375recover (disconnect them) and try to let other cards on the same segment
376recover. Keep in mind that in most real life cases, though, there will
377be only one driver per segment.
378
379Now, a note about interrupts. If you get an interrupt and your
380device is dead or has been isolated, there is a problem :)
381The current policy is to turn this into a platform policy.
382That 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
426The 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
12Many PCI bus controllers are able to detect a variety of hardware
13PCI errors on the bus, such as parity errors on the data and address
14buses, as well as SERR and PERR errors. Some of the more advanced
15chipsets are able to deal with these errors; these include PCI-E chipsets,
16and the PCI-host bridges found on IBM Power4, Power5 and Power6-based
17pSeries boxes. A typical action taken is to disconnect the affected device,
18halting all I/O to it. The goal of a disconnection is to avoid system
19corruption; for example, to halt system memory corruption due to DMA's
20to "wild" addresses. Typically, a reconnection mechanism is also
21offered, so that the affected PCI device(s) are reset and put back
22into working condition. The reset phase requires coordination
23between the affected device drivers and the PCI controller chip.
24This document describes a generic API for notifying device drivers
25of a bus disconnection, and then performing error recovery.
26This API is currently implemented in the 2.6.16 and later kernels.
27
28Reporting and recovery is performed in several steps. First, when
29a PCI hardware error has resulted in a bus disconnect, that event
30is reported as soon as possible to all affected device drivers,
31including multiple instances of a device driver on multi-function
32cards. This allows device drivers to avoid deadlocking in spinloops,
33waiting for some i/o-space register to change, when it never will.
34It also gives the drivers a chance to defer incoming I/O as
35needed.
36
37Next, recovery is performed in several stages. Most of the complexity
38is forced by the need to handle multi-function devices, that is,
39devices that have multiple device drivers associated with them.
40In the first stage, each driver is allowed to indicate what type
41of reset it desires, the choices being a simple re-enabling of I/O
42or requesting a slot reset.
43
44If any driver requests a slot reset, that is what will be done.
45
46After a reset and/or a re-enabling of I/O, all drivers are
47again notified, so that they may then perform any device setup/config
48that may be required. After these have all completed, a final
49"resume normal operations" event is sent out.
50
51The biggest reason for choosing a kernel-based implementation rather
52than a user-space implementation was the need to deal with bus
53disconnects of PCI devices attached to storage media, and, in particular,
54disconnects from devices holding the root file system. If the root
55file system is disconnected, a user-space mechanism would have to go
56through a large number of contortions to complete recovery. Almost all
57of the current Linux file systems are not tolerant of disconnection
58from/reconnection to their underlying block device. By contrast,
59bus errors are easy to manage in the device driver. Indeed, most
60device drivers already handle very similar recovery procedures;
61for example, the SCSI-generic layer already provides significant
62mechanisms for dealing with SCSI bus errors and SCSI bus resets.
63
64
65Detailed Design
66---------------
67Design and implementation details below, based on a chain of
68public email discussions with Ben Herrenschmidt, circa 5 April 2005.
69
70The error recovery API support is exposed to the driver in the form of
71a structure of function pointers pointed to by a new field in struct
72pci_driver. A driver that fails to provide the structure is "non-aware",
73and the actual recovery steps taken are platform dependent. The
74arch/powerpc implementation will simulate a PCI hotplug remove/add.
75
76This structure has the form:
77struct 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
85The possible channel states are:
86enum 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
92Possible return values are:
93enum 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
101A driver does not have to implement all of these callbacks; however,
102if it implements any, it must implement error_detected(). If a callback
103is not implemented, the corresponding feature is considered unsupported.
104For example, if mmio_enabled() and resume() aren't there, then it
105is assumed that the driver is not doing any direct recovery and requires
106a slot reset. Typically a driver will want to know about
107a slot_reset().
108
109The actual steps taken by a platform to recover from a PCI error
110event will be platform-dependent, but will follow the general
111sequence described below.
112
113STEP 0: Error Event
114-------------------
115A PCI bus error is detected by the PCI hardware. On powerpc, the slot
116is isolated, in that all I/O is blocked: all reads return 0xffffffff,
117all writes are ignored.
118
119
120STEP 1: Notification
121--------------------
122Platform calls the error_detected() callback on every instance of
123every driver affected by the error.
124
125At this point, the device might not be accessible anymore, depending on
126the platform (the slot will be isolated on powerpc). The driver may
127already have "noticed" the error because of a failing I/O, but this
128is the proper "synchronization point", that is, it gives the driver
129a chance to cleanup, waiting for pending stuff (timers, whatever, etc...)
130to complete; it can take semaphores, schedule, etc... everything but
131touch the device. Within this function and after it returns, the driver
132shouldn'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
135All drivers participating in this system must implement this call.
136The 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
148The next step taken will depend on the result codes returned by the
149drivers.
150
151If all drivers on the segment/slot return PCI_ERS_RESULT_CAN_RECOVER,
152then the platform should re-enable IOs on the slot (or do nothing in
153particular, if the platform doesn't isolate slots), and recovery
154proceeds to STEP 2 (MMIO Enable).
155
156If any driver requested a slot reset (by returning PCI_ERS_RESULT_NEED_RESET),
157then recovery proceeds to STEP 4 (Slot Reset).
158
159If the platform is unable to recover the slot, the next step
160is 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
179STEP 2: MMIO Enabled
180-------------------
181The platform re-enables MMIO to the device (but typically not the
182DMA), and then calls the mmio_enabled() callback on all affected
183device drivers.
184
185This is the "early recovery" call. IOs are allowed again, but DMA is
186not, with some restrictions. This is NOT a callback for the driver to
187start operations again, only to peek/poke at the device, extract diagnostic
188information, if any, and eventually do things like trigger a device local
189reset or some such, but not restart operations. This callback is made if
190all drivers on a segment agree that they can try to recover and if no automatic
191link reset was performed by the HW. If the platform can't just re-enable IOs
192without a slot reset or a link reset, it will not call this callback, and
193instead 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
205The 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
224The next step taken depends on the results returned by the drivers.
225If all drivers returned PCI_ERS_RESULT_RECOVERED, then the platform
226proceeds to either STEP3 (Link Reset) or to STEP 5 (Resume Operations).
227
228If any driver returned PCI_ERS_RESULT_NEED_RESET, then the platform
229proceeds to STEP 4 (Slot Reset)
230
231STEP 3: Link Reset
232------------------
233The platform resets the link. This is a PCI-Express specific step
234and is done whenever a fatal error has been detected that can be
235"solved" by resetting the link.
236
237STEP 4: Slot Reset
238------------------
239
240In response to a return value of PCI_ERS_RESULT_NEED_RESET, the
241the platform will perform a slot reset on the requesting PCI device(s).
242The actual steps taken by a platform to perform a slot reset
243will be platform-dependent. Upon completion of slot reset, the
244platform will call the device slot_reset() callback.
245
246Powerpc platforms implement two levels of slot reset:
247soft reset(default) and fundamental(optional) reset.
248
249Powerpc soft reset consists of asserting the adapter #RST line and then
250restoring the PCI BAR's and PCI configuration header to a state
251that is equivalent to what it would be after a fresh system
252power-on followed by power-on BIOS/system firmware initialization.
253Soft reset is also known as hot-reset.
254
255Powerpc fundamental reset is supported by PCI Express cards only
256and results in device's state machines, hardware logic, port states and
257configuration registers to initialize to their default conditions.
258
259For most PCI devices, a soft reset will be sufficient for recovery.
260Optional fundamental reset is provided to support a limited number
261of PCI Express devices for which a soft reset is not sufficient
262for recovery.
263
264If the platform supports PCI hotplug, then the reset might be
265performed by toggling the slot electrical power off/on.
266
267It is important for the platform to restore the PCI config space
268to the "fresh poweron" state, rather than the "last state". After
269a slot reset, the device driver will almost always use its standard
270device initialization routines, and an unusual config space setup
271may result in hung devices, kernel panics, or silent data corruption.
272
273This call gives drivers the chance to re-initialize the hardware
274(re-download firmware, etc.). At this point, the driver may assume
275that the card is in a fresh state and is fully functional. The slot
276is unfrozen and the driver has full access to PCI config space,
277memory mapped I/O space and DMA. Interrupts (Legacy, MSI, or MSI-X)
278will also be available.
279
280Drivers should not restart normal I/O processing operations
281at this point. If all device drivers report success on this
282callback, the platform will call resume() to complete the sequence,
283and let the driver restart normal I/O processing.
284
285A driver can still return a critical failure for this function if
286it can't get the device operational after reset. If the platform
287previously tried a soft reset, it might now try a hard reset (power
288cycle) and then call slot_reset() again. It the device still can't
289be recovered, there is nothing more that can be done; the platform
290will typically report a "permanent failure" in such a case. The
291device will be considered "dead" in this case.
292
293Drivers for multi-function cards will need to coordinate among
294themselves as to which driver instance will perform any "one-shot"
295or global device initialization. For example, the Symbios sym53cxx2
296driver 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
305Drivers for PCI Express cards that require a fundamental reset must
306set the needs_freset bit in the pci_dev structure in their probe function.
307For example, the QLogic qla2xxx driver sets the needs_freset bit for certain
308PCI 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
315Platform proceeds either to STEP 5 (Resume Operations) or STEP 6 (Permanent
316Failure).
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
323STEP 5: Resume Operations
324-------------------------
325The platform will call the resume() callback on all affected device
326drivers if all drivers on the segment have returned
327PCI_ERS_RESULT_RECOVERED from one of the 3 previous callbacks.
328The goal of this callback is to tell the driver to restart activity,
329that everything is back and running. This callback does not return
330a result code.
331
332At this point, if a new error happens, the platform will restart
333a new error recovery sequence.
334
335STEP 6: Permanent Failure
336-------------------------
337A "permanent failure" has occurred, and the platform cannot recover
338the device. The platform will call error_detected() with a
339pci_channel_state value of pci_channel_io_perm_failure.
340
341The device driver should, at this point, assume the worst. It should
342cancel all pending I/O, refuse all new I/O, returning -EIO to
343higher layers. The device driver should then clean up all of its
344memory and remove itself from kernel operations, much as it would
345during system shutdown.
346
347The platform will typically notify the system operator of the
348permanent failure in some way. If the device is hotplug-capable,
349the operator will probably want to remove and replace the device.
350Note, however, not all failures are truly "permanent". Some are
351caused by over-heating, some by a poorly seated card. Many
352PCI error events are caused by software bugs, e.g. DMA's to
353wild addresses or bogus split transactions due to programming
354errors. See the discussion in powerpc/eeh-pci-error-recovery.txt
355for additional detail on real-life experience of the causes of
356software errors.
357
358
359Conclusion; General Remarks
360---------------------------
361The way the callbacks are called is platform policy. A platform with
362no slot reset capability may want to just "ignore" drivers that can't
363recover (disconnect them) and try to let other cards on the same segment
364recover. Keep in mind that in most real life cases, though, there will
365be only one driver per segment.
366
367Now, a note about interrupts. If you get an interrupt and your
368device is dead or has been isolated, there is a problem :)
369The current policy is to turn this into a platform policy.
370That is, the recovery API only requires that:
371
372 - There is no guarantee that interrupt delivery can proceed from any
373device on the segment starting from the error detection and until the
374slot_reset callback is called, at which point interrupts are expected
375to be fully operational.
376
377 - There is no guarantee that interrupt delivery is stopped, that is,
378a driver that gets an interrupt after detecting an error, or that detects
379an error within the interrupt handler such that it prevents proper
380ack'ing of the interrupt (and thus removal of the source) should just
381return IRQ_NOTHANDLED. It's up to the platform to deal with that
382condition, typically by masking the IRQ source during the duration of
383the error handling. It is expected that the platform "knows" which
384interrupts are routed to error-management capable slots and can deal
385with temporarily disabling that IRQ number during error processing (this
386isn't terribly complex). That means some IRQ latency for other devices
387sharing the interrupt, but there is simply no other way. High end
388platforms aren't supposed to share interrupts between many devices
389anyway :)
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
412The 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====================================
5PCI 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
12Overview
13========
14
15What is SR-IOV
16--------------
17
18Single Root I/O Virtualization (SR-IOV) is a PCI Express Extended
19capability which makes one physical device appear as multiple virtual
20devices. The physical device is referred to as Physical Function (PF)
21while the virtual devices are referred to as Virtual Functions (VF).
22Allocation of the VF can be dynamically controlled by the PF via
23registers encapsulated in the capability. By default, this feature is
24not enabled and the PF behaves as traditional PCIe device. Once it's
25turned on, each VF's PCI configuration space can be accessed by its own
26Bus, Device and Function Number (Routing ID). And each VF also has PCI
27Memory Space, which is used to map its register set. VF device driver
28operates on the register set so it can be functional and appear as a
29real existing PCI device.
30
31User Guide
32==========
33
34How can I enable SR-IOV capability
35----------------------------------
36
37Multiple methods are available for SR-IOV enablement.
38In the first method, the device driver (PF driver) will control the
39enabling and disabling of the capability via API provided by SR-IOV core.
40If the hardware has SR-IOV capability, loading its PF driver would
41enable it and all VFs associated with the PF. Some PF drivers require
42a module parameter to be set to determine the number of VFs to enable.
43In the second method, a write to the sysfs file sriov_numvfs will
44enable and disable the VFs associated with a PCIe PF. This method
45enables per-PF, VF enable/disable values versus the first method,
46which applies to all PFs of the same device. Additionally, the
47PCI SRIOV core support ensures that enable/disable operations are
48valid to reduce duplication in multiple drivers for the same
49checks, e.g., check numvfs == 0 if enabling VFs, ensure
50numvfs <= totalvfs.
51The second method is the recommended method for new/future VF devices.
52
53How can I use the Virtual Functions
54-----------------------------------
55
56The VF is treated as hot-plugged PCI devices in the kernel, so they
57should be able to work in the same way as real PCI devices. The VF
58requires device driver that is same as a normal PCI device's.
59
60Developer Guide
61===============
62
63SR-IOV API
64----------
65
66To 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
79To 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
90To enable auto probing VFs by a compatible driver on the host, run
91command below before enabling SR-IOV capabilities. This is the
92default behavior.
93::
94
95 echo 1 > \
96 /sys/bus/pci/devices/<DOMAIN:BUS:DEVICE.FUNCTION>/sriov_drivers_autoprobe
97
98To disable auto probing VFs by a compatible driver on the host, run
99command below before enabling SR-IOV capabilities. Updating this
100entry 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
106Usage example
107-------------
108
109Following 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
91. Overview
10
111.1 What is SR-IOV
12
13Single Root I/O Virtualization (SR-IOV) is a PCI Express Extended
14capability which makes one physical device appear as multiple virtual
15devices. The physical device is referred to as Physical Function (PF)
16while the virtual devices are referred to as Virtual Functions (VF).
17Allocation of the VF can be dynamically controlled by the PF via
18registers encapsulated in the capability. By default, this feature is
19not enabled and the PF behaves as traditional PCIe device. Once it's
20turned on, each VF's PCI configuration space can be accessed by its own
21Bus, Device and Function Number (Routing ID). And each VF also has PCI
22Memory Space, which is used to map its register set. VF device driver
23operates on the register set so it can be functional and appear as a
24real existing PCI device.
25
262. User Guide
27
282.1 How can I enable SR-IOV capability
29
30Multiple methods are available for SR-IOV enablement.
31In the first method, the device driver (PF driver) will control the
32enabling and disabling of the capability via API provided by SR-IOV core.
33If the hardware has SR-IOV capability, loading its PF driver would
34enable it and all VFs associated with the PF. Some PF drivers require
35a module parameter to be set to determine the number of VFs to enable.
36In the second method, a write to the sysfs file sriov_numvfs will
37enable and disable the VFs associated with a PCIe PF. This method
38enables per-PF, VF enable/disable values versus the first method,
39which applies to all PFs of the same device. Additionally, the
40PCI SRIOV core support ensures that enable/disable operations are
41valid to reduce duplication in multiple drivers for the same
42checks, e.g., check numvfs == 0 if enabling VFs, ensure
43numvfs <= totalvfs.
44The second method is the recommended method for new/future VF devices.
45
462.2 How can I use the Virtual Functions
47
48The VF is treated as hot-plugged PCI devices in the kernel, so they
49should be able to work in the same way as real PCI devices. The VF
50requires device driver that is same as a normal PCI device's.
51
523. Developer Guide
53
543.1 SR-IOV API
55
56To 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
64To 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
71To enable auto probing VFs by a compatible driver on the host, run
72command below before enabling SR-IOV capabilities. This is the
73default behavior.
74 echo 1 > \
75 /sys/bus/pci/devices/<DOMAIN:BUS:DEVICE.FUNCTION>/sriov_drivers_autoprobe
76
77To disable auto probing VFs by a compatible driver on the host, run
78command below before enabling SR-IOV capabilities. Updating this
79entry will not affect VFs which are already probed.
80 echo 0 > \
81 /sys/bus/pci/devices/<DOMAIN:BUS:DEVICE.FUNCTION>/sriov_drivers_autoprobe
82
833.2 Usage example
84
85Following piece of code illustrates the usage of the SR-IOV API.
86
87static 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
96static void dev_remove(struct pci_dev *dev)
97{
98 pci_disable_sriov(dev);
99
100 ...
101}
102
103static int dev_suspend(struct pci_dev *dev, pm_message_t state)
104{
105 ...
106
107 return 0;
108}
109
110static int dev_resume(struct pci_dev *dev)
111{
112 ...
113
114 return 0;
115}
116
117static void dev_shutdown(struct pci_dev *dev)
118{
119 ...
120}
121
122static 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
138static 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==============================
4How To Write Linux PCI Drivers
5==============================
6
7:Authors: - Martin Mares <mj@ucw.cz>
8 - Grant Grundler <grundler@parisc-linux.org>
9
10The world of PCI is vast and full of (mostly unpleasant) surprises.
11Since each CPU architecture implements different chip-sets and PCI devices
12have different requirements (erm, "features"), the result is the PCI support
13in the Linux kernel is not as trivial as one would wish. This short paper
14tries to introduce all potential driver authors to Linux APIs for
15PCI device drivers.
16
17A more complete resource is the third edition of "Linux Device Drivers"
18by Jonathan Corbet, Alessandro Rubini, and Greg Kroah-Hartman.
19LDD3 is available for free (under Creative Commons License) from:
20http://lwn.net/Kernel/LDD3/.
21
22However, keep in mind that all documents are subject to "bit rot".
23Refer to the source code if things are not working as described here.
24
25Please send questions/comments/patches about Linux PCI API to the
26"Linux PCI" <linux-pci@atrey.karlin.mff.cuni.cz> mailing list.
27
28
29Structure of PCI drivers
30========================
31PCI drivers "discover" PCI devices in a system via pci_register_driver().
32Actually, it's the other way around. When the PCI generic code discovers
33a new device, the driver with a matching "description" will be notified.
34Details on this below.
35
36pci_register_driver() leaves most of the probing for devices to
37the PCI layer and supports online insertion/removal of devices [thus
38supporting hot-pluggable PCI, CardBus, and Express-Card in a single driver].
39pci_register_driver() call requires passing in a table of function
40pointers and thus dictates the high level structure of a driver.
41
42Once the driver knows about a PCI device and takes ownership, the
43driver 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
54When done using the device, and perhaps the module needs to be unloaded,
55the 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
65Most of these topics are covered in the following sections.
66For the rest look at LDD3 or <linux/pci.h> .
67
68If the PCI subsystem is not configured (CONFIG_PCI is not set), most of
69the PCI functions described below are defined as inline functions either
70completely empty or just returning an appropriate error codes to avoid
71lots of ifdefs in the drivers.
72
73
74pci_register_driver() call
75==========================
76
77PCI device drivers call ``pci_register_driver()`` during their
78initialization 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
84The ID table is an array of ``struct pci_device_id`` entries ending with an
85all-zero entry. Definitions with static const are generally preferred.
86
87.. kernel-doc:: include/linux/mod_devicetable.h
88 :functions: pci_device_id
89
90Most drivers only need ``PCI_DEVICE()`` or ``PCI_DEVICE_CLASS()`` to set up
91a pci_device_id table.
92
93New PCI IDs may be added to a device driver pci_ids table at runtime
94as shown below::
95
96 echo "vendor device subvendor subdevice class class_mask driver_data" > \
97 /sys/bus/pci/drivers/{driver}/new_id
98
99All fields are passed in as hexadecimal values (no leading 0x).
100The vendor and device fields are mandatory, the others are optional. Users
101need 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
107Note that driver_data must match the value used by any of the pci_device_id
108entries defined in the driver. This makes the driver_data field mandatory
109if all the pci_device_id entries have a non-zero driver_data value.
110
111Once added, the driver probe routine will be invoked for any unclaimed
112PCI devices listed in its (newly updated) pci_ids list.
113
114When the driver exits, it just calls pci_unregister_driver() and the PCI layer
115automatically calls the remove hook for all devices handled by the driver.
116
117
118"Attributes" for driver functions/data
119--------------------------------------
120
121Please 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
130Tips 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
141How to find PCI devices manually
142================================
143
144PCI drivers should have a really good reason for not using the
145pci_register_driver() interface to search for PCI devices.
146The main reason PCI devices are controlled by multiple drivers
147is because one PCI device implements several different HW services.
148E.g. combined serial/parallel port/floppy controller.
149
150A manual search may be performed using the following constructs:
151
152Searching 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
158Searching by class ID (iterate in a similar way)::
159
160 pci_get_class(CLASS_ID, dev)
161
162Searching 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
166You can use the constant PCI_ANY_ID as a wildcard replacement for
167VENDOR_ID or DEVICE_ID. This allows searching for any device from a
168specific vendor, for example.
169
170These functions are hotplug-safe. They increment the reference count on
171the pci_dev that they return. You must eventually (possibly at module unload)
172decrement the reference count on these devices by calling pci_dev_put().
173
174
175Device Initialization Steps
176===========================
177
178As noted in the introduction, most PCI drivers need the following steps
179for 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
190The driver can access PCI config space registers at any time.
191(Well, almost. When running BIST, config space can go away...but
192that will just result in a PCI Bus Master Abort and config reads
193will return garbage).
194
195
196Enable the PCI device
197---------------------
198Before touching any device registers, the driver needs to enable
199the 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
220pci_set_master() will enable DMA by setting the bus master bit
221in the PCI_COMMAND register. It also fixes the latency timer value if
222it's set to something bogus by the BIOS. pci_clear_master() will
223disable DMA by clearing the bus master bit.
224
225If the PCI device can use the PCI Memory-Write-Invalidate transaction,
226call pci_set_mwi(). This enables the PCI_COMMAND bit for Mem-Wr-Inval
227and also ensures that the cache line size register is set correctly.
228Check the return value of pci_set_mwi() as not all architectures
229or chip-sets may support Memory-Write-Invalidate. Alternatively,
230if Mem-Wr-Inval would be nice to have but is not required, call
231pci_try_set_mwi() to have the system do its best effort at enabling
232Mem-Wr-Inval.
233
234
235Request MMIO/IOP resources
236--------------------------
237Memory (MMIO), and I/O port addresses should NOT be read directly
238from the PCI device config space. Use the values in the pci_dev structure
239as the PCI "bus address" might have been remapped to a "host physical"
240address by the arch/chip-set specific kernel support.
241
242See Documentation/io-mapping.txt for how to access device registers
243or device memory.
244
245The device driver needs to call pci_request_region() to verify
246no other device is already using the same address resource.
247Conversely, drivers should call pci_release_region() AFTER
248calling pci_disable_device().
249The 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
256Generic flavors of pci_request_region() are request_mem_region()
257(for MMIO ranges) and request_region() (for IO Port ranges).
258Use these for address resources that are not described by "normal" PCI
259BARs.
260
261Also see pci_request_selected_regions() below.
262
263
264Set 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
272While all drivers should explicitly indicate the DMA capability
273(e.g. 32 or 64 bit) of the PCI bus master, devices with more than
27432-bit bus master capability for streaming data need the driver
275to "register" this capability by calling pci_set_dma_mask() with
276appropriate parameters. In general this allows more efficient DMA
277on systems where System RAM exists above 4G _physical_ address.
278
279Drivers for all PCI-X and PCIe compliant devices must call
280pci_set_dma_mask() as they are 64-bit DMA devices.
281
282Similarly, drivers must also "register" this capability if the device
283can directly address "consistent memory" in System RAM above 4G physical
284address by calling pci_set_consistent_dma_mask().
285Again, this includes drivers for all PCI-X and PCIe compliant devices.
286Many 64-bit "PCI" devices (before PCI-X) and some PCI-X devices are
28764-bit DMA capable for payload ("streaming") data but not control
288("consistent") data.
289
290
291Setup shared control data
292-------------------------
293Once the DMA masks are set, the driver can allocate "consistent" (a.k.a. shared)
294memory. See Documentation/DMA-API.txt for a full description of
295the DMA APIs. This section is just a reminder that it needs to be done
296before enabling DMA on the device.
297
298
299Initialize device registers
300---------------------------
301Some drivers will need specific "capability" fields programmed
302or other "vendor specific" register initialized or reset.
303E.g. clearing pending interrupts.
304
305
306Register IRQ handler
307--------------------
308While calling request_irq() is the last step described here,
309this is often just another intermediate step to initialize a device.
310This step can often be deferred until the device is opened for use.
311
312All interrupt handlers for IRQ lines should be registered with IRQF_SHARED
313and use the devid to map IRQs to devices (remember that all PCI IRQ lines
314can be shared).
315
316request_irq() will associate an interrupt handler and device handle
317with an interrupt number. Historically interrupt numbers represent
318IRQ lines which run from the PCI device to the Interrupt controller.
319With MSI and MSI-X (more below) the interrupt number is a CPU "vector".
320
321request_irq() also enables the interrupt. Make sure the device is
322quiesced and does not have any interrupts pending before registering
323the interrupt handler.
324
325MSI and MSI-X are PCI capabilities. Both are "Message Signaled Interrupts"
326which deliver interrupts to the CPU via a DMA write to a Local APIC.
327The fundamental difference between MSI and MSI-X is how multiple
328"vectors" get allocated. MSI requires contiguous blocks of vectors
329while MSI-X can allocate several individual ones.
330
331MSI capability can be enabled by calling pci_alloc_irq_vectors() with the
332PCI_IRQ_MSI and/or PCI_IRQ_MSIX flags before calling request_irq(). This
333causes the PCI support to program CPU vector data into the PCI device
334capability registers. Many architectures, chip-sets, or BIOSes do NOT
335support MSI or MSI-X and a call to pci_alloc_irq_vectors with just
336the PCI_IRQ_MSI and PCI_IRQ_MSIX flags will fail, so try to always
337specify PCI_IRQ_LEGACY as well.
338
339Drivers that have different interrupt handlers for MSI/MSI-X and
340legacy INTx should chose the right one based on the msi_enabled
341and msix_enabled flags in the pci_dev structure after calling
342pci_alloc_irq_vectors.
343
344There are (at least) two really good reasons for using MSI:
345
3461) 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
3502) 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
356See drivers/infiniband/hw/mthca/ or drivers/net/tg3.c for examples
357of MSI/MSI-X usage.
358
359
360PCI device shutdown
361===================
362
363When a PCI device driver is being unloaded, most of the following
364steps 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
375Stop IRQs on the device
376-----------------------
377How to do this is chip/device specific. If it's not done, it opens
378the possibility of a "screaming interrupt" if (and only if)
379the IRQ is shared with another device.
380
381When the shared IRQ handler is "unhooked", the remaining devices
382using the same IRQ line will still need the IRQ enabled. Thus if the
383"unhooked" device asserts IRQ line, the system will respond assuming
384it was one of the remaining devices asserted the IRQ line. Since none
385of the other devices will handle the IRQ, the system will "hang" until
386it decides the IRQ isn't going to get handled and masks the IRQ (100,000
387iterations later). Once the shared IRQ is masked, the remaining devices
388will stop functioning properly. Not a nice situation.
389
390This is another reason to use MSI or MSI-X if it's available.
391MSI and MSI-X are defined to be exclusive interrupts and thus
392are not susceptible to the "screaming interrupt" problem.
393
394
395Release the IRQ
396---------------
397Once the device is quiesced (no more IRQs), one can call free_irq().
398This function will return control once any pending IRQs are handled,
399"unhook" the drivers IRQ handler from that IRQ, and finally release
400the IRQ if no one else is using it.
401
402
403Stop all DMA activity
404---------------------
405It's extremely important to stop all DMA operations BEFORE attempting
406to deallocate DMA control data. Failure to do so can result in memory
407corruption, hangs, and on some chip-sets a hard crash.
408
409Stopping DMA after stopping the IRQs can avoid races where the
410IRQ handler might restart DMA engines.
411
412While this step sounds obvious and trivial, several "mature" drivers
413didn't get this step right in the past.
414
415
416Release DMA buffers
417-------------------
418Once DMA is stopped, clean up streaming DMA first.
419I.e. unmap data buffers and return buffers to "upstream"
420owners if there is one.
421
422Then clean up "consistent" buffers which contain the control data.
423
424See Documentation/DMA-API.txt for details on unmapping interfaces.
425
426
427Unregister from other subsystems
428--------------------------------
429Most low level PCI device drivers support some other subsystem
430like USB, ALSA, SCSI, NetDev, Infiniband, etc. Make sure your
431driver isn't losing resources from that other subsystem.
432If this happens, typically the symptom is an Oops (panic) when
433the subsystem attempts to call into a driver that has been unloaded.
434
435
436Disable Device from responding to MMIO/IO Port addresses
437--------------------------------------------------------
438io_unmap() MMIO or IO Port resources and then call pci_disable_device().
439This is the symmetric opposite of pci_enable_device().
440Do not access device registers after calling pci_disable_device().
441
442
443Release MMIO/IO Port Resource(s)
444--------------------------------
445Call pci_release_region() to mark the MMIO or IO Port range as available.
446Failure to do so usually results in the inability to reload the driver.
447
448
449How to access PCI config space
450==============================
451
452You can use `pci_(read|write)_config_(byte|word|dword)` to access the config
453space of a device represented by `struct pci_dev *`. All these functions return
4540 when successful or an error code (`PCIBIOS_...`) which can be translated to a
455text string by pcibios_strerror. Most drivers expect that accesses to valid PCI
456devices don't fail.
457
458If 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
460and function on that bus.
461
462If you access fields in the standard portion of the config header, please
463use symbolic names of locations and bits declared in <linux/pci.h>.
464
465If you need to access Extended PCI Capability registers, just call
466pci_find_capability() for the particular capability and it will find the
467corresponding register block for you.
468
469
470Other interesting functions
471===========================
472
473============================= ================================================
474pci_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.
477pci_set_power_state() Set PCI Power Management state (0=D0 ... 3=D3)
478pci_find_capability() Find specified capability in device's capability
479 list.
480pci_resource_start() Returns bus start address for a given PCI region
481pci_resource_end() Returns bus end address for a given PCI region
482pci_resource_len() Returns the byte length of a PCI region
483pci_set_drvdata() Set private driver data pointer for a pci_dev
484pci_get_drvdata() Return private driver data pointer for a pci_dev
485pci_set_mwi() Enable Memory-Write-Invalidate transactions.
486pci_clear_mwi() Disable Memory-Write-Invalidate transactions.
487============================= ================================================
488
489
490Miscellaneous hints
491===================
492
493When displaying PCI device names to the user (for example when a driver wants
494to tell the user what card has it found), please use pci_name(pci_dev).
495
496Always refer to the PCI devices by a pointer to the pci_dev structure.
497All PCI layer functions use this identification and it's the only
498reasonable one. Don't use bus/slot/function numbers except for very
499special purposes -- on systems with multiple primary buses their semantics
500can be pretty complex.
501
502Don't try to turn on Fast Back to Back writes in your driver. All devices
503on the bus need to be capable of doing it, so this is something which needs
504to be handled by platform and generic code, not individual drivers.
505
506
507Vendor and device identifications
508=================================
509
510Do not add new device or vendor IDs to include/linux/pci_ids.h unless they
511are shared across multiple drivers. You can add private definitions in
512your driver if they're helpful, or just use plain hex constants.
513
514The device IDs are arbitrary hex numbers (vendor controlled) and normally used
515only in a single location, the pci_device_id table.
516
517Please DO submit new vendor/device IDs to http://pci-ids.ucw.cz/.
518There are mirrors of the pci.ids file at http://pciids.sourceforge.net/
519and https://github.com/pciutils/pciids.
520
521
522Obsolete functions
523==================
524
525There are several functions which you might come across when trying to
526port an old driver to the new PCI interface. They are no longer present
527in the kernel as they aren't compatible with hotplug or PCI domains or
528having sane locking.
529
530================= ===========================================
531pci_find_device() Superseded by pci_get_device()
532pci_find_subsys() Superseded by pci_get_subsys()
533pci_find_slot() Superseded by pci_get_domain_bus_and_slot()
534pci_get_slot() Superseded by pci_get_domain_bus_and_slot()
535================= ===========================================
536
537The alternative is the traditional PCI device driver that walks PCI
538device lists. This is still possible but discouraged.
539
540
541MMIO Space and "Write Posting"
542==============================
543
544Converting a driver from using I/O Port space to using MMIO space
545often requires some additional changes. Specifically, "write posting"
546needs to be handled. Many drivers (e.g. tg3, acenic, sym53c8xx_2)
547already do this. I/O Port space guarantees write transactions reach the PCI
548device before the CPU can continue. Writes to MMIO space allow the CPU
549to continue before the transaction reaches the PCI device. HW weenies
550call this "Write Posting" because the write completion is "posted" to
551the CPU before the transaction has reached its destination.
552
553Thus, timing sensitive code should add readl() where the CPU is
554expected to wait before doing other work. The classic "bit banging"
555sequence 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
562The 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
570It is important that "safe_mmio_reg" not have any side effects that
571interferes with the correct operation of the device.
572
573Another case to watch out for is when resetting a PCI device. Use PCI
574Configuration space reads to flush the writel(). This will gracefully
575handle the PCI master abort on all platforms if the PCI device is
576expected to not respond to a readl(). Most x86 platforms will allow
577MMIO 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~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
8The world of PCI is vast and full of (mostly unpleasant) surprises.
9Since each CPU architecture implements different chip-sets and PCI devices
10have different requirements (erm, "features"), the result is the PCI support
11in the Linux kernel is not as trivial as one would wish. This short paper
12tries to introduce all potential driver authors to Linux APIs for
13PCI device drivers.
14
15A more complete resource is the third edition of "Linux Device Drivers"
16by Jonathan Corbet, Alessandro Rubini, and Greg Kroah-Hartman.
17LDD3 is available for free (under Creative Commons License) from:
18
19 http://lwn.net/Kernel/LDD3/
20
21However, keep in mind that all documents are subject to "bit rot".
22Refer to the source code if things are not working as described here.
23
24Please 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
290. Structure of PCI drivers
30~~~~~~~~~~~~~~~~~~~~~~~~~~~
31PCI drivers "discover" PCI devices in a system via pci_register_driver().
32Actually, it's the other way around. When the PCI generic code discovers
33a new device, the driver with a matching "description" will be notified.
34Details on this below.
35
36pci_register_driver() leaves most of the probing for devices to
37the PCI layer and supports online insertion/removal of devices [thus
38supporting hot-pluggable PCI, CardBus, and Express-Card in a single driver].
39pci_register_driver() call requires passing in a table of function
40pointers and thus dictates the high level structure of a driver.
41
42Once the driver knows about a PCI device and takes ownership, the
43driver 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
54When done using the device, and perhaps the module needs to be unloaded,
55the 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
64Most of these topics are covered in the following sections.
65For the rest look at LDD3 or <linux/pci.h> .
66
67If the PCI subsystem is not configured (CONFIG_PCI is not set), most of
68the PCI functions described below are defined as inline functions either
69completely empty or just returning an appropriate error codes to avoid
70lots of ifdefs in the drivers.
71
72
73
741. pci_register_driver() call
75~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
76
77PCI device drivers call pci_register_driver() during their
78initialization 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
125The ID table is an array of struct pci_device_id entries ending with an
126all-zero entry. Definitions with static const are generally preferred.
127
128Each 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
151Most drivers only need PCI_DEVICE() or PCI_DEVICE_CLASS() to set up
152a pci_device_id table.
153
154New PCI IDs may be added to a device driver pci_ids table at runtime
155as shown below:
156
157echo "vendor device subvendor subdevice class class_mask driver_data" > \
158/sys/bus/pci/drivers/{driver}/new_id
159
160All fields are passed in as hexadecimal values (no leading 0x).
161The vendor and device fields are mandatory, the others are optional. Users
162need 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
167Note that driver_data must match the value used by any of the pci_device_id
168entries defined in the driver. This makes the driver_data field mandatory
169if all the pci_device_id entries have a non-zero driver_data value.
170
171Once added, the driver probe routine will be invoked for any unclaimed
172PCI devices listed in its (newly updated) pci_ids list.
173
174When the driver exits, it just calls pci_unregister_driver() and the PCI layer
175automatically calls the remove hook for all devices handled by the driver.
176
177
1781.1 "Attributes" for driver functions/data
179
180Please 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
187Tips 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
1992. How to find PCI devices manually
200~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
201
202PCI drivers should have a really good reason for not using the
203pci_register_driver() interface to search for PCI devices.
204The main reason PCI devices are controlled by multiple drivers
205is because one PCI device implements several different HW services.
206E.g. combined serial/parallel port/floppy controller.
207
208A manual search may be performed using the following constructs:
209
210Searching 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
216Searching by class ID (iterate in a similar way):
217
218 pci_get_class(CLASS_ID, dev)
219
220Searching 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
224You can use the constant PCI_ANY_ID as a wildcard replacement for
225VENDOR_ID or DEVICE_ID. This allows searching for any device from a
226specific vendor, for example.
227
228These functions are hotplug-safe. They increment the reference count on
229the pci_dev that they return. You must eventually (possibly at module unload)
230decrement the reference count on these devices by calling pci_dev_put().
231
232
233
2343. Device Initialization Steps
235~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
236
237As noted in the introduction, most PCI drivers need the following steps
238for 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
249The driver can access PCI config space registers at any time.
250(Well, almost. When running BIST, config space can go away...but
251that will just result in a PCI Bus Master Abort and config reads
252will return garbage).
253
254
2553.1 Enable the PCI device
256~~~~~~~~~~~~~~~~~~~~~~~~~
257Before touching any device registers, the driver needs to enable
258the 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
263NOTE: 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
276pci_set_master() will enable DMA by setting the bus master bit
277in the PCI_COMMAND register. It also fixes the latency timer value if
278it's set to something bogus by the BIOS. pci_clear_master() will
279disable DMA by clearing the bus master bit.
280
281If the PCI device can use the PCI Memory-Write-Invalidate transaction,
282call pci_set_mwi(). This enables the PCI_COMMAND bit for Mem-Wr-Inval
283and also ensures that the cache line size register is set correctly.
284Check the return value of pci_set_mwi() as not all architectures
285or chip-sets may support Memory-Write-Invalidate. Alternatively,
286if Mem-Wr-Inval would be nice to have but is not required, call
287pci_try_set_mwi() to have the system do its best effort at enabling
288Mem-Wr-Inval.
289
290
2913.2 Request MMIO/IOP resources
292~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
293Memory (MMIO), and I/O port addresses should NOT be read directly
294from the PCI device config space. Use the values in the pci_dev structure
295as the PCI "bus address" might have been remapped to a "host physical"
296address by the arch/chip-set specific kernel support.
297
298See Documentation/io-mapping.txt for how to access device registers
299or device memory.
300
301The device driver needs to call pci_request_region() to verify
302no other device is already using the same address resource.
303Conversely, drivers should call pci_release_region() AFTER
304calling pci_disable_device().
305The 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
311Generic flavors of pci_request_region() are request_mem_region()
312(for MMIO ranges) and request_region() (for IO Port ranges).
313Use these for address resources that are not described by "normal" PCI
314BARs.
315
316Also see pci_request_selected_regions() below.
317
318
3193.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
326While all drivers should explicitly indicate the DMA capability
327(e.g. 32 or 64 bit) of the PCI bus master, devices with more than
32832-bit bus master capability for streaming data need the driver
329to "register" this capability by calling pci_set_dma_mask() with
330appropriate parameters. In general this allows more efficient DMA
331on systems where System RAM exists above 4G _physical_ address.
332
333Drivers for all PCI-X and PCIe compliant devices must call
334pci_set_dma_mask() as they are 64-bit DMA devices.
335
336Similarly, drivers must also "register" this capability if the device
337can directly address "consistent memory" in System RAM above 4G physical
338address by calling pci_set_consistent_dma_mask().
339Again, this includes drivers for all PCI-X and PCIe compliant devices.
340Many 64-bit "PCI" devices (before PCI-X) and some PCI-X devices are
34164-bit DMA capable for payload ("streaming") data but not control
342("consistent") data.
343
344
3453.4 Setup shared control data
346~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
347Once the DMA masks are set, the driver can allocate "consistent" (a.k.a. shared)
348memory. See Documentation/DMA-API.txt for a full description of
349the DMA APIs. This section is just a reminder that it needs to be done
350before enabling DMA on the device.
351
352
3533.5 Initialize device registers
354~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
355Some drivers will need specific "capability" fields programmed
356or other "vendor specific" register initialized or reset.
357E.g. clearing pending interrupts.
358
359
3603.6 Register IRQ handler
361~~~~~~~~~~~~~~~~~~~~~~~~
362While calling request_irq() is the last step described here,
363this is often just another intermediate step to initialize a device.
364This step can often be deferred until the device is opened for use.
365
366All interrupt handlers for IRQ lines should be registered with IRQF_SHARED
367and use the devid to map IRQs to devices (remember that all PCI IRQ lines
368can be shared).
369
370request_irq() will associate an interrupt handler and device handle
371with an interrupt number. Historically interrupt numbers represent
372IRQ lines which run from the PCI device to the Interrupt controller.
373With MSI and MSI-X (more below) the interrupt number is a CPU "vector".
374
375request_irq() also enables the interrupt. Make sure the device is
376quiesced and does not have any interrupts pending before registering
377the interrupt handler.
378
379MSI and MSI-X are PCI capabilities. Both are "Message Signaled Interrupts"
380which deliver interrupts to the CPU via a DMA write to a Local APIC.
381The fundamental difference between MSI and MSI-X is how multiple
382"vectors" get allocated. MSI requires contiguous blocks of vectors
383while MSI-X can allocate several individual ones.
384
385MSI capability can be enabled by calling pci_alloc_irq_vectors() with the
386PCI_IRQ_MSI and/or PCI_IRQ_MSIX flags before calling request_irq(). This
387causes the PCI support to program CPU vector data into the PCI device
388capability registers. Many architectures, chip-sets, or BIOSes do NOT
389support MSI or MSI-X and a call to pci_alloc_irq_vectors with just
390the PCI_IRQ_MSI and PCI_IRQ_MSIX flags will fail, so try to always
391specify PCI_IRQ_LEGACY as well.
392
393Drivers that have different interrupt handlers for MSI/MSI-X and
394legacy INTx should chose the right one based on the msi_enabled
395and msix_enabled flags in the pci_dev structure after calling
396pci_alloc_irq_vectors.
397
398There are (at least) two really good reasons for using MSI:
3991) 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
4032) 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
409See drivers/infiniband/hw/mthca/ or drivers/net/tg3.c for examples
410of MSI/MSI-X usage.
411
412
413
4144. PCI device shutdown
415~~~~~~~~~~~~~~~~~~~~~~~
416
417When a PCI device driver is being unloaded, most of the following
418steps 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
4294.1 Stop IRQs on the device
430~~~~~~~~~~~~~~~~~~~~~~~~~~~
431How to do this is chip/device specific. If it's not done, it opens
432the possibility of a "screaming interrupt" if (and only if)
433the IRQ is shared with another device.
434
435When the shared IRQ handler is "unhooked", the remaining devices
436using the same IRQ line will still need the IRQ enabled. Thus if the
437"unhooked" device asserts IRQ line, the system will respond assuming
438it was one of the remaining devices asserted the IRQ line. Since none
439of the other devices will handle the IRQ, the system will "hang" until
440it decides the IRQ isn't going to get handled and masks the IRQ (100,000
441iterations later). Once the shared IRQ is masked, the remaining devices
442will stop functioning properly. Not a nice situation.
443
444This is another reason to use MSI or MSI-X if it's available.
445MSI and MSI-X are defined to be exclusive interrupts and thus
446are not susceptible to the "screaming interrupt" problem.
447
448
4494.2 Release the IRQ
450~~~~~~~~~~~~~~~~~~~
451Once the device is quiesced (no more IRQs), one can call free_irq().
452This function will return control once any pending IRQs are handled,
453"unhook" the drivers IRQ handler from that IRQ, and finally release
454the IRQ if no one else is using it.
455
456
4574.3 Stop all DMA activity
458~~~~~~~~~~~~~~~~~~~~~~~~~
459It's extremely important to stop all DMA operations BEFORE attempting
460to deallocate DMA control data. Failure to do so can result in memory
461corruption, hangs, and on some chip-sets a hard crash.
462
463Stopping DMA after stopping the IRQs can avoid races where the
464IRQ handler might restart DMA engines.
465
466While this step sounds obvious and trivial, several "mature" drivers
467didn't get this step right in the past.
468
469
4704.4 Release DMA buffers
471~~~~~~~~~~~~~~~~~~~~~~~
472Once DMA is stopped, clean up streaming DMA first.
473I.e. unmap data buffers and return buffers to "upstream"
474owners if there is one.
475
476Then clean up "consistent" buffers which contain the control data.
477
478See Documentation/DMA-API.txt for details on unmapping interfaces.
479
480
4814.5 Unregister from other subsystems
482~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
483Most low level PCI device drivers support some other subsystem
484like USB, ALSA, SCSI, NetDev, Infiniband, etc. Make sure your
485driver isn't losing resources from that other subsystem.
486If this happens, typically the symptom is an Oops (panic) when
487the subsystem attempts to call into a driver that has been unloaded.
488
489
4904.6 Disable Device from responding to MMIO/IO Port addresses
491~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
492io_unmap() MMIO or IO Port resources and then call pci_disable_device().
493This is the symmetric opposite of pci_enable_device().
494Do not access device registers after calling pci_disable_device().
495
496
4974.7 Release MMIO/IO Port Resource(s)
498~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
499Call pci_release_region() to mark the MMIO or IO Port range as available.
500Failure to do so usually results in the inability to reload the driver.
501
502
503
5045. How to access PCI config space
505~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
506
507You can use pci_(read|write)_config_(byte|word|dword) to access the config
508space of a device represented by struct pci_dev *. All these functions return 0
509when successful or an error code (PCIBIOS_...) which can be translated to a text
510string by pcibios_strerror. Most drivers expect that accesses to valid PCI
511devices don't fail.
512
513If you don't have a struct pci_dev available, you can call
514pci_bus_(read|write)_config_(byte|word|dword) to access a given device
515and function on that bus.
516
517If you access fields in the standard portion of the config header, please
518use symbolic names of locations and bits declared in <linux/pci.h>.
519
520If you need to access Extended PCI Capability registers, just call
521pci_find_capability() for the particular capability and it will find the
522corresponding register block for you.
523
524
525
5266. Other interesting functions
527~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
528
529pci_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.
532pci_set_power_state() Set PCI Power Management state (0=D0 ... 3=D3)
533pci_find_capability() Find specified capability in device's capability
534 list.
535pci_resource_start() Returns bus start address for a given PCI region
536pci_resource_end() Returns bus end address for a given PCI region
537pci_resource_len() Returns the byte length of a PCI region
538pci_set_drvdata() Set private driver data pointer for a pci_dev
539pci_get_drvdata() Return private driver data pointer for a pci_dev
540pci_set_mwi() Enable Memory-Write-Invalidate transactions.
541pci_clear_mwi() Disable Memory-Write-Invalidate transactions.
542
543
544
5457. Miscellaneous hints
546~~~~~~~~~~~~~~~~~~~~~~
547
548When displaying PCI device names to the user (for example when a driver wants
549to tell the user what card has it found), please use pci_name(pci_dev).
550
551Always refer to the PCI devices by a pointer to the pci_dev structure.
552All PCI layer functions use this identification and it's the only
553reasonable one. Don't use bus/slot/function numbers except for very
554special purposes -- on systems with multiple primary buses their semantics
555can be pretty complex.
556
557Don't try to turn on Fast Back to Back writes in your driver. All devices
558on the bus need to be capable of doing it, so this is something which needs
559to be handled by platform and generic code, not individual drivers.
560
561
562
5638. Vendor and device identifications
564~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
565
566Do not add new device or vendor IDs to include/linux/pci_ids.h unless they
567are shared across multiple drivers. You can add private definitions in
568your driver if they're helpful, or just use plain hex constants.
569
570The device IDs are arbitrary hex numbers (vendor controlled) and normally used
571only in a single location, the pci_device_id table.
572
573Please DO submit new vendor/device IDs to http://pci-ids.ucw.cz/.
574There are mirrors of the pci.ids file at http://pciids.sourceforge.net/
575and https://github.com/pciutils/pciids.
576
577
578
5799. Obsolete functions
580~~~~~~~~~~~~~~~~~~~~~
581
582There are several functions which you might come across when trying to
583port an old driver to the new PCI interface. They are no longer present
584in the kernel as they aren't compatible with hotplug or PCI domains or
585having sane locking.
586
587pci_find_device() Superseded by pci_get_device()
588pci_find_subsys() Superseded by pci_get_subsys()
589pci_find_slot() Superseded by pci_get_domain_bus_and_slot()
590pci_get_slot() Superseded by pci_get_domain_bus_and_slot()
591
592
593The alternative is the traditional PCI device driver that walks PCI
594device lists. This is still possible but discouraged.
595
596
597
59810. MMIO Space and "Write Posting"
599~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
600
601Converting a driver from using I/O Port space to using MMIO space
602often requires some additional changes. Specifically, "write posting"
603needs to be handled. Many drivers (e.g. tg3, acenic, sym53c8xx_2)
604already do this. I/O Port space guarantees write transactions reach the PCI
605device before the CPU can continue. Writes to MMIO space allow the CPU
606to continue before the transaction reaches the PCI device. HW weenies
607call this "Write Posting" because the write completion is "posted" to
608the CPU before the transaction has reached its destination.
609
610Thus, timing sensitive code should add readl() where the CPU is
611expected to wait before doing other work. The classic "bit banging"
612sequence 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
619The 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
627It is important that "safe_mmio_reg" not have any side effects that
628interferes with the correct operation of the device.
629
630Another case to watch out for is when resetting a PCI device. Use PCI
631Configuration space reads to flush the writel(). This will gracefully
632handle the PCI master abort on all platforms if the PCI device is
633expected to not respond to a readl(). Most x86 platforms will allow
634MMIO 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===========================================================
5The 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
13Overview
14===========
15
16About this guide
17----------------
18
19This guide describes the basics of the PCI Express Advanced Error
20Reporting (AER) driver and provides information on how to use it, as
21well as how to enable the drivers of endpoint devices to conform with
22PCI Express AER driver.
23
24
25What is the PCI Express AER Driver?
26-----------------------------------
27
28PCI Express error signaling can occur on the PCI Express link itself
29or on behalf of transactions initiated on the link. PCI Express
30defines two error reporting paradigms: the baseline capability and
31the Advanced Error Reporting capability. The baseline capability is
32required of all PCI Express components providing a minimum defined
33set of error reporting requirements. Advanced Error Reporting
34capability is implemented with a PCI Express advanced error reporting
35extended capability structure providing more robust error reporting.
36
37The PCI Express AER driver provides the infrastructure to support PCI
38Express Advanced Error Reporting capability. The PCI Express AER
39driver 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
45AER driver only attaches root ports which support PCI-Express AER
46capability.
47
48
49User Guide
50==========
51
52Include the PCI Express AER Root Driver into the Linux Kernel
53-------------------------------------------------------------
54
55The PCI Express AER Root driver is a Root Port service driver attached
56to the PCI Express Port Bus driver. If a user wants to use it, the driver
57has to be compiled. Option CONFIG_PCIEAER supports this capability. It
58depends on CONFIG_PCIEPORTBUS, so pls. set CONFIG_PCIEPORTBUS=y and
59CONFIG_PCIEAER = y.
60
61Load PCI Express AER Root Driver
62--------------------------------
63
64Some systems have AER support in firmware. Enabling Linux AER support at
65the same time the firmware handles AER may result in unpredictable
66behavior. Therefore, Linux does not handle AER events unless the firmware
67grants AER control to the OS via the ACPI _OSC method. See the PCI FW 3.0
68Specification for details regarding _OSC usage.
69
70AER error output
71----------------
72
73When a PCIe AER error is captured, an error message will be output to
74console. If it's a correctable error, it is output as a warning.
75Otherwise, it is printed as an error. So users could choose different
76log level to filter out correctable error messages.
77
78Below 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
85In the example, 'Requester ID' means the ID of the device who sends
86the error message to root port. Pls. refer to pci express specs for
87other fields.
88
89AER Statistics / Counters
90-------------------------
91
92When PCIe AER errors are captured, the counters / statistics are also exposed
93in the form of sysfs attributes which are documented at
94Documentation/ABI/testing/sysfs-bus-pci-devices-aer_stats
95
96Developer Guide
97===============
98
99To enable AER aware support requires a software driver to configure
100the AER capability structure within its device and to provide callbacks.
101
102To support AER better, developers need understand how AER does work
103firstly.
104
105PCI Express errors are classified into two types: correctable errors
106and uncorrectable errors. This classification is based on the impacts
107of those errors, which may result in degraded performance or function
108failure.
109
110Correctable errors pose no impacts on the functionality of the
111interface. The PCI Express protocol can recover without any software
112intervention or any loss of data. These errors are detected and
113corrected by hardware. Unlike correctable errors, uncorrectable
114errors impact functionality of the interface. Uncorrectable errors
115can cause a particular transaction or a particular PCI Express link
116to be unreliable. Depending on those error conditions, uncorrectable
117errors are further classified into non-fatal errors and fatal errors.
118Non-fatal errors cause the particular transaction to be unreliable,
119but the PCI Express link itself is fully functional. Fatal errors, on
120the other hand, cause the link to be unreliable.
121
122When AER is enabled, a PCI Express device will automatically send an
123error message to the PCIe root port above it when the device captures
124an error. The Root Port, upon receiving an error reporting message,
125internally processes and logs the error message in its PCI Express
126capability structure. Error information being logged includes storing
127the error reporting agent's requestor ID into the Error Source
128Identification Registers and setting the error bits of the Root Error
129Status Register accordingly. If AER error reporting is enabled in Root
130Error Command Register, the Root Port generates an interrupt if an
131error is detected.
132
133Note that the errors as described above are related to the PCI Express
134hierarchy and links. These errors do not include any device specific
135errors because device specific errors will still get sent directly to
136the device driver.
137
138Configure the AER capability structure
139--------------------------------------
140
141AER aware drivers of PCI Express component need change the device
142control registers to enable AER. They also could change AER registers,
143including mask and severity registers. Helper function
144pci_enable_pcie_error_reporting could be used to enable AER. See
145section 3.3.
146
147Provide callbacks
148-----------------
149
150callback reset_link to reset pci express link
151~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
152
153This callback is used to reset the pci express physical link when a
154fatal error happens. The root port aer service driver provides a
155default reset_link function, but different upstream ports might
156have different specifications to reset pci express link, so all
157upstream ports should provide their own reset_link functions.
158
159In struct pcie_port_service_driver, a new pointer, reset_link, is
160added.
161::
162
163 pci_ers_result_t (*reset_link) (struct pci_dev *dev);
164
165Section 3.2.2.2 provides more detailed info on when to call
166reset_link.
167
168PCI error-recovery callbacks
169~~~~~~~~~~~~~~~~~~~~~~~~~~~~
170
171The PCI Express AER Root driver uses error callbacks to coordinate
172with downstream device drivers associated with a hierarchy in question
173when performing error recovery actions.
174
175Data struct pci_driver has a pointer, err_handler, to point to
176pci_error_handlers who consists of a couple of callback function
177pointers. AER driver follows the rules defined in
178pci-error-recovery.txt except pci express specific parts (e.g.
179reset_link). Pls. refer to pci-error-recovery.txt for detailed
180definitions of the callbacks.
181
182Below sections specify when to call the error callback functions.
183
184Correctable errors
185~~~~~~~~~~~~~~~~~~
186
187Correctable errors pose no impacts on the functionality of
188the interface. The PCI Express protocol can recover without any
189software intervention or any loss of data. These errors do not
190require any recovery actions. The AER driver clears the device's
191correctable error status register accordingly and logs these errors.
192
193Non-correctable (non-fatal and fatal) errors
194~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
195
196If an error message indicates a non-fatal error, performing link reset
197at upstream is not required. The AER driver calls error_detected(dev,
198pci_channel_io_normal) to all drivers associated within a hierarchy in
199question. for example::
200
201 EndPoint<==>DownstreamPort B<==>UpstreamPort A<==>RootPort
202
203If Upstream port A captures an AER error, the hierarchy consists of
204Downstream port B and EndPoint.
205
206A driver may return PCI_ERS_RESULT_CAN_RECOVER,
207PCI_ERS_RESULT_DISCONNECT, or PCI_ERS_RESULT_NEED_RESET, depending on
208whether it can recover or the AER driver calls mmio_enabled as next.
209
210If an error message indicates a fatal error, kernel will broadcast
211error_detected(dev, pci_channel_io_frozen) to all drivers within
212a hierarchy in question. Then, performing link reset at upstream is
213necessary. As different kinds of devices might use different approaches
214to reset link, AER port service driver is required to provide the
215function to reset link. Firstly, kernel looks for if the upstream
216component has an aer driver. If it has, kernel uses the reset_link
217callback of the aer driver. If the upstream component has no aer driver
218and the port is downstream port, we will perform a hot reset as the
219default by setting the Secondary Bus Reset bit of the Bridge Control
220register associated with the downstream port. As for upstream ports,
221they should provide their own aer service drivers with reset_link
222function. If error_detected returns PCI_ERS_RESULT_CAN_RECOVER and
223reset_link returns PCI_ERS_RESULT_RECOVERED, the error handling goes
224to mmio_enabled.
225
226helper functions
227----------------
228::
229
230 int pci_enable_pcie_error_reporting(struct pci_dev *dev);
231
232pci_enable_pcie_error_reporting enables the device to send error
233messages to root port when an error is detected. Note that devices
234don't enable the error reporting by default, so device drivers need
235call this function to enable it.
236
237::
238
239 int pci_disable_pcie_error_reporting(struct pci_dev *dev);
240
241pci_disable_pcie_error_reporting disables the device to send error
242messages to root port when an error is detected.
243
244::
245
246 int pci_cleanup_aer_uncorrect_error_status(struct pci_dev *dev);`
247
248pci_cleanup_aer_uncorrect_error_status cleanups the uncorrectable
249error status register.
250
251Frequent Asked Questions
252------------------------
253
254Q:
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
258A:
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
263Q:
264 What happens if an upstream port service driver does not provide
265 callback reset_link?
266
267A:
268 Fatal error recovery will fail if the errors are reported by the
269 upstream ports who are attached by the service driver.
270
271Q:
272 How does this infrastructure deal with driver that is not PCI
273 Express aware?
274
275A:
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
281Q:
282 What modifications will that driver need to make it compatible
283 with the PCI Express AER Root driver?
284
285A:
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
290Software error injection
291========================
292
293Debugging PCIe AER error recovery code is quite difficult because it
294is hard to trigger real hardware errors. Software based error
295injection can be used to fake various kinds of PCIe errors.
296
297First you should enable PCIe AER software error injection in kernel
298configuration, that is, following item should be in your .config.
299
300CONFIG_PCIEAER_INJECT=y or CONFIG_PCIEAER_INJECT=m
301
302After reboot with new kernel or insert the module, a device file named
303/dev/aer_inject should be created.
304
305Then, you need a user space tool named aer-inject, which can be gotten
306from:
307
308 https://git.kernel.org/cgit/linux/kernel/git/gong.chen/aer-inject.git/
309
310More information about aer-inject can be found in the document comes
311with 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
71. Overview
8
91.1 About this guide
10
11This guide describes the basics of the PCI Express Advanced Error
12Reporting (AER) driver and provides information on how to use it, as
13well as how to enable the drivers of endpoint devices to conform with
14PCI Express AER driver.
15
161.2 Copyright (C) Intel Corporation 2006.
17
181.3 What is the PCI Express AER Driver?
19
20PCI Express error signaling can occur on the PCI Express link itself
21or on behalf of transactions initiated on the link. PCI Express
22defines two error reporting paradigms: the baseline capability and
23the Advanced Error Reporting capability. The baseline capability is
24required of all PCI Express components providing a minimum defined
25set of error reporting requirements. Advanced Error Reporting
26capability is implemented with a PCI Express advanced error reporting
27extended capability structure providing more robust error reporting.
28
29The PCI Express AER driver provides the infrastructure to support PCI
30Express Advanced Error Reporting capability. The PCI Express AER
31driver 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
37AER driver only attaches root ports which support PCI-Express AER
38capability.
39
40
412. User Guide
42
432.1 Include the PCI Express AER Root Driver into the Linux Kernel
44
45The PCI Express AER Root driver is a Root Port service driver attached
46to the PCI Express Port Bus driver. If a user wants to use it, the driver
47has to be compiled. Option CONFIG_PCIEAER supports this capability. It
48depends on CONFIG_PCIEPORTBUS, so pls. set CONFIG_PCIEPORTBUS=y and
49CONFIG_PCIEAER = y.
50
512.2 Load PCI Express AER Root Driver
52
53Some systems have AER support in firmware. Enabling Linux AER support at
54the same time the firmware handles AER may result in unpredictable
55behavior. Therefore, Linux does not handle AER events unless the firmware
56grants AER control to the OS via the ACPI _OSC method. See the PCI FW 3.0
57Specification for details regarding _OSC usage.
58
592.3 AER error output
60
61When a PCIe AER error is captured, an error message will be output to
62console. If it's a correctable error, it is output as a warning.
63Otherwise, it is printed as an error. So users could choose different
64log level to filter out correctable error messages.
65
66Below shows an example:
670000:50:00.0: PCIe Bus Error: severity=Uncorrected (Fatal), type=Transaction Layer, id=0500(Requester ID)
680000:50:00.0: device [8086:0329] error status/mask=00100000/00000000
690000:50:00.0: [20] Unsupported Request (First)
700000:50:00.0: TLP Header: 04000001 00200a03 05010000 00050100
71
72In the example, 'Requester ID' means the ID of the device who sends
73the error message to root port. Pls. refer to pci express specs for
74other fields.
75
762.4 AER Statistics / Counters
77
78When PCIe AER errors are captured, the counters / statistics are also exposed
79in the form of sysfs attributes which are documented at
80Documentation/ABI/testing/sysfs-bus-pci-devices-aer_stats
81
823. Developer Guide
83
84To enable AER aware support requires a software driver to configure
85the AER capability structure within its device and to provide callbacks.
86
87To support AER better, developers need understand how AER does work
88firstly.
89
90PCI Express errors are classified into two types: correctable errors
91and uncorrectable errors. This classification is based on the impacts
92of those errors, which may result in degraded performance or function
93failure.
94
95Correctable errors pose no impacts on the functionality of the
96interface. The PCI Express protocol can recover without any software
97intervention or any loss of data. These errors are detected and
98corrected by hardware. Unlike correctable errors, uncorrectable
99errors impact functionality of the interface. Uncorrectable errors
100can cause a particular transaction or a particular PCI Express link
101to be unreliable. Depending on those error conditions, uncorrectable
102errors are further classified into non-fatal errors and fatal errors.
103Non-fatal errors cause the particular transaction to be unreliable,
104but the PCI Express link itself is fully functional. Fatal errors, on
105the other hand, cause the link to be unreliable.
106
107When AER is enabled, a PCI Express device will automatically send an
108error message to the PCIe root port above it when the device captures
109an error. The Root Port, upon receiving an error reporting message,
110internally processes and logs the error message in its PCI Express
111capability structure. Error information being logged includes storing
112the error reporting agent's requestor ID into the Error Source
113Identification Registers and setting the error bits of the Root Error
114Status Register accordingly. If AER error reporting is enabled in Root
115Error Command Register, the Root Port generates an interrupt if an
116error is detected.
117
118Note that the errors as described above are related to the PCI Express
119hierarchy and links. These errors do not include any device specific
120errors because device specific errors will still get sent directly to
121the device driver.
122
1233.1 Configure the AER capability structure
124
125AER aware drivers of PCI Express component need change the device
126control registers to enable AER. They also could change AER registers,
127including mask and severity registers. Helper function
128pci_enable_pcie_error_reporting could be used to enable AER. See
129section 3.3.
130
1313.2. Provide callbacks
132
1333.2.1 callback reset_link to reset pci express link
134
135This callback is used to reset the pci express physical link when a
136fatal error happens. The root port aer service driver provides a
137default reset_link function, but different upstream ports might
138have different specifications to reset pci express link, so all
139upstream ports should provide their own reset_link functions.
140
141In struct pcie_port_service_driver, a new pointer, reset_link, is
142added.
143
144pci_ers_result_t (*reset_link) (struct pci_dev *dev);
145
146Section 3.2.2.2 provides more detailed info on when to call
147reset_link.
148
1493.2.2 PCI error-recovery callbacks
150
151The PCI Express AER Root driver uses error callbacks to coordinate
152with downstream device drivers associated with a hierarchy in question
153when performing error recovery actions.
154
155Data struct pci_driver has a pointer, err_handler, to point to
156pci_error_handlers who consists of a couple of callback function
157pointers. AER driver follows the rules defined in
158pci-error-recovery.txt except pci express specific parts (e.g.
159reset_link). Pls. refer to pci-error-recovery.txt for detailed
160definitions of the callbacks.
161
162Below sections specify when to call the error callback functions.
163
1643.2.2.1 Correctable errors
165
166Correctable errors pose no impacts on the functionality of
167the interface. The PCI Express protocol can recover without any
168software intervention or any loss of data. These errors do not
169require any recovery actions. The AER driver clears the device's
170correctable error status register accordingly and logs these errors.
171
1723.2.2.2 Non-correctable (non-fatal and fatal) errors
173
174If an error message indicates a non-fatal error, performing link reset
175at upstream is not required. The AER driver calls error_detected(dev,
176pci_channel_io_normal) to all drivers associated within a hierarchy in
177question. for example,
178EndPoint<==>DownstreamPort B<==>UpstreamPort A<==>RootPort.
179If Upstream port A captures an AER error, the hierarchy consists of
180Downstream port B and EndPoint.
181
182A driver may return PCI_ERS_RESULT_CAN_RECOVER,
183PCI_ERS_RESULT_DISCONNECT, or PCI_ERS_RESULT_NEED_RESET, depending on
184whether it can recover or the AER driver calls mmio_enabled as next.
185
186If an error message indicates a fatal error, kernel will broadcast
187error_detected(dev, pci_channel_io_frozen) to all drivers within
188a hierarchy in question. Then, performing link reset at upstream is
189necessary. As different kinds of devices might use different approaches
190to reset link, AER port service driver is required to provide the
191function to reset link. Firstly, kernel looks for if the upstream
192component has an aer driver. If it has, kernel uses the reset_link
193callback of the aer driver. If the upstream component has no aer driver
194and the port is downstream port, we will perform a hot reset as the
195default by setting the Secondary Bus Reset bit of the Bridge Control
196register associated with the downstream port. As for upstream ports,
197they should provide their own aer service drivers with reset_link
198function. If error_detected returns PCI_ERS_RESULT_CAN_RECOVER and
199reset_link returns PCI_ERS_RESULT_RECOVERED, the error handling goes
200to mmio_enabled.
201
2023.3 helper functions
203
2043.3.1 int pci_enable_pcie_error_reporting(struct pci_dev *dev);
205pci_enable_pcie_error_reporting enables the device to send error
206messages to root port when an error is detected. Note that devices
207don't enable the error reporting by default, so device drivers need
208call this function to enable it.
209
2103.3.2 int pci_disable_pcie_error_reporting(struct pci_dev *dev);
211pci_disable_pcie_error_reporting disables the device to send error
212messages to root port when an error is detected.
213
2143.3.3 int pci_cleanup_aer_uncorrect_error_status(struct pci_dev *dev);
215pci_cleanup_aer_uncorrect_error_status cleanups the uncorrectable
216error status register.
217
2183.4 Frequent Asked Questions
219
220Q: What happens if a PCI Express device driver does not provide an
221error recovery handler (pci_driver->err_handler is equal to NULL)?
222
223A: The devices attached with the driver won't be recovered. If the
224error is fatal, kernel will print out warning messages. Please refer
225to section 3 for more information.
226
227Q: What happens if an upstream port service driver does not provide
228callback reset_link?
229
230A: Fatal error recovery will fail if the errors are reported by the
231upstream ports who are attached by the service driver.
232
233Q: How does this infrastructure deal with driver that is not PCI
234Express aware?
235
236A: This infrastructure calls the error callback functions of the
237driver when an error happens. But if the driver is not aware of
238PCI Express, the device might not report its own errors to root
239port.
240
241Q: What modifications will that driver need to make it compatible
242with the PCI Express AER Root driver?
243
244A: It could call the helper functions to enable AER in devices and
245cleanup uncorrectable status register. Pls. refer to section 3.3.
246
247
2484. Software error injection
249
250Debugging PCIe AER error recovery code is quite difficult because it
251is hard to trigger real hardware errors. Software based error
252injection can be used to fake various kinds of PCIe errors.
253
254First you should enable PCIe AER software error injection in kernel
255configuration, that is, following item should be in your .config.
256
257CONFIG_PCIEAER_INJECT=y or CONFIG_PCIEAER_INJECT=m
258
259After reboot with new kernel or insert the module, a device file named
260/dev/aer_inject should be created.
261
262Then, you need a user space tool named aer-inject, which can be gotten
263from:
264 https://git.kernel.org/cgit/linux/kernel/git/gong.chen/aer-inject.git/
265
266More information about aer-inject can be found in the document comes
267with 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===========================================
5The 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
11About this guide
12================
13
14This guide describes the basics of the PCI Express Port Bus driver
15and provides information on how to enable the service drivers to
16register/unregister with the PCI Express Port Bus Driver.
17
18
19What is the PCI Express Port Bus Driver
20=======================================
21
22A PCI Express Port is a logical PCI-PCI Bridge structure. There
23are two types of PCI Express Port: the Root Port and the Switch
24Port. The Root Port originates a PCI Express link from a PCI Express
25Root Complex and the Switch Port connects PCI Express links to
26internal logical PCI buses. The Switch Port, which has its secondary
27bus representing the switch's internal routing logic, is called the
28switch's Upstream Port. The switch's Downstream Port is bridging from
29switch's internal routing bus to a bus representing the downstream
30PCI Express link from the PCI Express Switch.
31
32A PCI Express Port can provide up to four distinct functions,
33referred to in this document as services, depending on its port type.
34PCI Express Port's services include native hotplug support (HP),
35power management event support (PME), advanced error reporting
36support (AER), and virtual channel support (VC). These services may
37be handled by a single complex driver or be individually distributed
38and handled by corresponding service drivers.
39
40Why use the PCI Express Port Bus Driver?
41========================================
42
43In existing Linux kernels, the Linux Device Driver Model allows a
44physical device to be handled by only a single driver. The PCI
45Express Port is a PCI-PCI Bridge device with multiple distinct
46services. To maintain a clean and simple solution each service
47may have its own software service driver. In this case several
48service drivers will compete for a single PCI-PCI Bridge device.
49For example, if the PCI Express Root Port native hotplug service
50driver is loaded first, it claims a PCI-PCI Bridge Root Port. The
51kernel therefore does not load other service drivers for that Root
52Port. In other words, it is impossible to have multiple service
53drivers load and run on a PCI-PCI Bridge device simultaneously
54using the current driver model.
55
56To enable multiple service drivers running simultaneously requires
57having a PCI Express Port Bus driver, which manages all populated
58PCI Express Ports and distributes all provided service requests
59to the corresponding service drivers as required. Some key
60advantages 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
74Configuring the PCI Express Port Bus Driver vs. Service Drivers
75===============================================================
76
77Including the PCI Express Port Bus Driver Support into the Kernel
78-----------------------------------------------------------------
79
80Including the PCI Express Port Bus driver depends on whether the PCI
81Express support is included in the kernel config. The kernel will
82automatically include the PCI Express Port Bus driver as a kernel
83driver when the PCI Express support is enabled in the kernel.
84
85Enabling Service Driver Support
86-------------------------------
87
88PCI device drivers are implemented based on Linux Device Driver Model.
89All service drivers are PCI device drivers. As discussed above, it is
90impossible to load any service driver once the kernel has loaded the
91PCI Express Port Bus Driver. To meet the PCI Express Port Bus Driver
92Model requires some minimal changes on existing service drivers that
93imposes no impact on the functionality of existing service drivers.
94
95A service driver is required to use the two APIs shown below to
96register its service with the PCI Express Port Bus driver (see
97section 5.2.1 & 5.2.2). It is important that a service driver
98initializes the pcie_port_service_driver data structure, included in
99header file /include/linux/pcieport_if.h, before calling these APIs.
100Failure to do so will result an identity mismatch, which prevents
101the PCI Express Port Bus driver from loading a service driver.
102
103pcie_port_service_register
104~~~~~~~~~~~~~~~~~~~~~~~~~~
105::
106
107 int pcie_port_service_register(struct pcie_port_service_driver *new)
108
109This API replaces the Linux Driver Model's pci_register_driver API. A
110service driver should always calls pcie_port_service_register at
111module init. Note that after service driver being loaded, calls
112such as pci_enable_device(dev) and pci_set_master(dev) are no longer
113necessary since these calls are executed by the PCI Port Bus driver.
114
115pcie_port_service_unregister
116~~~~~~~~~~~~~~~~~~~~~~~~~~~~
117::
118
119 void pcie_port_service_unregister(struct pcie_port_service_driver *new)
120
121pcie_port_service_unregister replaces the Linux Driver Model's
122pci_unregister_driver. It's always called by service driver when a
123module exits.
124
125Sample Code
126~~~~~~~~~~~
127
128Below is sample service driver code to initialize the port service
129driver 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
151Below is a sample code for registering/unregistering a service
152driver.
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
176Possible Resource Conflicts
177===========================
178
179Since all service drivers of a PCI-PCI Bridge Port device are
180allowed to run simultaneously, below lists a few of possible resource
181conflicts with proposed solutions.
182
183MSI and MSI-X Vector Resource
184-----------------------------
185
186Once MSI or MSI-X interrupts are enabled on a device, it stays in this
187mode until they are disabled again. Since service drivers of the same
188PCI-PCI Bridge port share the same physical device, if an individual
189service driver enables or disables MSI/MSI-X mode it may result
190unpredictable behavior.
191
192To avoid this situation all service drivers are not permitted to
193switch interrupt mode on its device. The PCI Express Port Bus driver
194is responsible for determining the interrupt mode and this should be
195transparent to service drivers. Service drivers need to know only
196the vector IRQ assigned to the field irq of struct pcie_device, which
197is passed in when the PCI Express Port Bus driver probes each service
198driver. Service drivers should use (struct pcie_device*)dev->irq to
199call request_irq/free_irq. In addition, the interrupt mode is stored
200in the field interrupt_mode of struct pcie_device.
201
202PCI Memory/IO Mapped Regions
203----------------------------
204
205Service drivers for PCI Express Power Management (PME), Advanced
206Error Reporting (AER), Hot-Plug (HP) and Virtual Channel (VC) access
207PCI configuration space on the PCI Express port. In all cases the
208registers accessed are independent of each other. This patch assumes
209that all service drivers will be well behaved and not overwrite
210other service driver's configuration settings.
211
212PCI Config Registers
213--------------------
214
215Each service driver runs its PCI config operations on its own
216capability structure except the PCI Express capability structure, in
217which Root Control register and Device Control register are shared
218between PME and AER. This patch assumes that all service drivers
219will be well behaved and not overwrite other service driver's
220configuration settings.
Documentation/RCU/UP.rst+143−0
@@ -0,0 +1,143 @@
1.. _up_doc:
2
3RCU on Uniprocessor Systems
4===========================
5
6A common misconception is that, on UP systems, the call_rcu() primitive
7may immediately invoke its function. The basis of this misconception
8is that since there is only one CPU, it should not be necessary to
9wait for anything else to get done, since there are no other CPUs for
10anything else to be happening on. Although this approach will *sort of*
11work a surprising amount of the time, it is a very bad idea in general.
12This document presents three examples that demonstrate exactly how bad
13an idea this is.
14
15Example 1: softirq Suicide
16--------------------------
17
18Suppose that an RCU-based algorithm scans a linked list containing
19elements A, B, and C in process context, and can delete elements from
20this same list in softirq context. Suppose that the process-context scan
21is referencing element B when it is interrupted by softirq processing,
22which deletes element B, and then invokes call_rcu() to free element B
23after a grace period.
24
25Now, if call_rcu() were to directly invoke its arguments, then upon return
26from softirq, the list scan would find itself referencing a newly freed
27element B. This situation can greatly decrease the life expectancy of
28your kernel.
29
30This same problem can occur if call_rcu() is invoked from a hardware
31interrupt handler.
32
33Example 2: Function-Call Fatality
34---------------------------------
35
36Of course, one could avert the suicide described in the preceding example
37by having call_rcu() directly invoke its arguments only if it was called
38from process context. However, this can fail in a similar manner.
39
40Suppose that an RCU-based algorithm again scans a linked list containing
41elements A, B, and C in process contexts, but that it invokes a function
42on each element as it is scanned. Suppose further that this function
43deletes element B from the list, then passes it to call_rcu() for deferred
44freeing. This may be a bit unconventional, but it is perfectly legal
45RCU usage, since call_rcu() must wait for a grace period to elapse.
46Therefore, in this case, allowing call_rcu() to immediately invoke
47its arguments would cause it to fail to make the fundamental guarantee
48underlying RCU, namely that call_rcu() defers invoking its arguments until
49all RCU read-side critical sections currently executing have completed.
50
51Quick 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
56Example 3: Death by Deadlock
57----------------------------
58
59Suppose that call_rcu() is invoked while holding a lock, and that the
60callback function must acquire this same lock. In this case, if
61call_rcu() were to directly invoke the callback, the result would
62be self-deadlock.
63
64In some cases, it would possible to restructure to code so that
65the call_rcu() is delayed until after the lock is released. However,
66there are cases where this can be quite ugly:
67
681. 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
732. 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
80If call_rcu() directly invokes the callback, painful locking restrictions
81or API changes would be required.
82
83Quick Quiz #2:
84 What locking restriction must RCU callbacks respect?
85
86:ref:`Answers to Quick Quiz <answer_quick_quiz_up>`
87
88Summary
89-------
90
91Permitting call_rcu() to immediately invoke its arguments breaks RCU,
92even on a UP system. So do not do it! Even on a UP system, the RCU
93infrastructure *must* respect grace periods, and *must* invoke callbacks
94from a known environment in which no locks are held.
95
96Note that it *is* safe for synchronize_rcu() to return immediately on
97UP systems, including PREEMPT SMP builds running on UP systems.
98
99Quick Quiz #3:
100 Why can't synchronize_rcu() return immediately on UP systems running
101 preemptable RCU?
102
103.. _answer_quick_quiz_up:
104
105Answer 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
113Answer 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
135Answer 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 @@
1RCU on Uniprocessor Systems
2
3
4A common misconception is that, on UP systems, the call_rcu() primitive
5may immediately invoke its function. The basis of this misconception
6is that since there is only one CPU, it should not be necessary to
7wait for anything else to get done, since there are no other CPUs for
8anything else to be happening on. Although this approach will -sort- -of-
9work a surprising amount of the time, it is a very bad idea in general.
10This document presents three examples that demonstrate exactly how bad
11an idea this is.
12
13
14Example 1: softirq Suicide
15
16Suppose that an RCU-based algorithm scans a linked list containing
17elements A, B, and C in process context, and can delete elements from
18this same list in softirq context. Suppose that the process-context scan
19is referencing element B when it is interrupted by softirq processing,
20which deletes element B, and then invokes call_rcu() to free element B
21after a grace period.
22
23Now, if call_rcu() were to directly invoke its arguments, then upon return
24from softirq, the list scan would find itself referencing a newly freed
25element B. This situation can greatly decrease the life expectancy of
26your kernel.
27
28This same problem can occur if call_rcu() is invoked from a hardware
29interrupt handler.
30
31
32Example 2: Function-Call Fatality
33
34Of course, one could avert the suicide described in the preceding example
35by having call_rcu() directly invoke its arguments only if it was called
36from process context. However, this can fail in a similar manner.
37
38Suppose that an RCU-based algorithm again scans a linked list containing
39elements A, B, and C in process contexts, but that it invokes a function
40on each element as it is scanned. Suppose further that this function
41deletes element B from the list, then passes it to call_rcu() for deferred
42freeing. This may be a bit unconventional, but it is perfectly legal
43RCU usage, since call_rcu() must wait for a grace period to elapse.
44Therefore, in this case, allowing call_rcu() to immediately invoke
45its arguments would cause it to fail to make the fundamental guarantee
46underlying RCU, namely that call_rcu() defers invoking its arguments until
47all RCU read-side critical sections currently executing have completed.
48
49Quick Quiz #1: why is it -not- legal to invoke synchronize_rcu() in
50 this case?
51
52
53Example 3: Death by Deadlock
54
55Suppose that call_rcu() is invoked while holding a lock, and that the
56callback function must acquire this same lock. In this case, if
57call_rcu() were to directly invoke the callback, the result would
58be self-deadlock.
59
60In some cases, it would possible to restructure to code so that
61the call_rcu() is delayed until after the lock is released. However,
62there are cases where this can be quite ugly:
63
641. 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
692. 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
76If call_rcu() directly invokes the callback, painful locking restrictions
77or API changes would be required.
78
79Quick Quiz #2: What locking restriction must RCU callbacks respect?
80
81
82Summary
83
84Permitting call_rcu() to immediately invoke its arguments breaks RCU,
85even on a UP system. So do not do it! Even on a UP system, the RCU
86infrastructure -must- respect grace periods, and -must- invoke callbacks
87from a known environment in which no locks are held.
88
89Note that it -is- safe for synchronize_rcu() to return immediately on
90UP systems, including !PREEMPT SMP builds running on UP systems.
91
92Quick Quiz #3: Why can't synchronize_rcu() return immediately on
93 UP systems running preemptable RCU?
94
95
96Answer 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
104Answer 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
125Answer 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============
4RCU 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
3Using RCU to Protect Read-Mostly Linked Lists
4=============================================
5
6One 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
8is that all of the required memory barriers are included for you in
9the list macros. This document describes several applications of RCU,
10with the best fits first.
11
12Example 1: Read-Side Action Taken Outside of Lock, No In-Place Updates
13----------------------------------------------------------------------
14
15The best applications are cases where, if reader-writer locking were
16used, the read-side lock would be dropped before taking any action
17based on the results of the search. The most celebrated example is
18the routing table. Because the routing table is tracking the state of
19equipment outside of the computer, it will at times contain stale data.
20Therefore, once the route has been computed, there is no need to hold
21the routing table static during transmission of the packet. After all,
22you can hold the routing table static all you want, but that won't keep
23the external Internet from changing, and it is the state of the external
24Internet that really matters. In addition, routing entries are typically
25added or deleted, rather than being modified in place.
26
27A straightforward example of this use of RCU may be found in the
28system-call auditing support. For example, a reader-writer locked
29implementation 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
48Here the list is searched under the lock, but the lock is dropped before
49the corresponding value is returned. By the time that this value is acted
50on, the list may well have been modified. This makes sense, since if
51you are turning auditing off, it is OK to audit a few extra system calls.
52
53This 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
72The read_lock() and read_unlock() calls have become rcu_read_lock()
73and rcu_read_unlock(), respectively, and the list_for_each_entry() has
74become list_for_each_entry_rcu(). The _rcu() list-traversal primitives
75insert the read-side memory barriers that are required on DEC Alpha CPUs.
76
77The changes to the update side are also straightforward. A reader-writer
78lock 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
111Following 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
142Normally, the write_lock() and write_unlock() would be replaced by
143a spin_lock() and a spin_unlock(), but in this case, all callers hold
144audit_netlink_sem, so no additional locking is required. The auditsc_lock
145can therefore be eliminated, since use of RCU eliminates the need for
146writers to exclude readers. Normally, the write_lock() calls would
147be converted into spin_lock() calls.
148
149The list_del(), list_add(), and list_add_tail() primitives have been
150replaced by list_del_rcu(), list_add_rcu(), and list_add_tail_rcu().
151The _rcu() list-manipulation primitives add memory barriers that are
152needed on weakly ordered CPUs (most of them!). The list_del_rcu()
153primitive omits the pointer poisoning debug-assist code that would
154otherwise cause concurrent readers to fail spectacularly.
155
156So, when readers can tolerate stale data and when entries are either added
157or deleted, without in-place modification, it is very easy to use RCU!
158
159Example 2: Handling In-Place Updates
160------------------------------------
161
162The system-call auditing code does not update auditing rules in place.
163However, if it did, reader-writer-locked code to do so might look as
164follows (presumably, the field_count is only permitted to decrease,
165otherwise, 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
189The RCU version creates a copy, updates the copy, then replaces the old
190entry with the newly updated entry. This sequence of actions, allowing
191concurrent reads while doing a copy to perform an update, is what gives
192RCU ("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
218Again, this assumes that the caller holds audit_netlink_sem. Normally,
219the reader-writer lock would become a spinlock in this sort of code.
220
221Example 3: Eliminating Stale Data
222---------------------------------
223
224The auditing examples above tolerate stale data, as do most algorithms
225that are tracking external state. Because there is a delay from the
226time the external state changes before Linux becomes aware of the change,
227additional RCU-induced staleness is normally not a problem.
228
229However, there are many examples where stale data cannot be tolerated.
230One example in the Linux kernel is the System V IPC (see the ipc_lock()
231function in ipc/util.c). This code checks a "deleted" flag under a
232per-entry spinlock, and, if the "deleted" flag is set, pretends that the
233entry does not exist. For this to be helpful, the search function must
234return holding the per-entry spinlock, as ipc_lock() does in fact do.
235
236Quick 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
242If the system-call audit module were to ever need to reject stale data,
243one way to accomplish this would be to add a "deleted" flag and a "lock"
244spinlock to the audit_entry structure, and modify audit_filter_task()
245as 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
269Note that this example assumes that entries are only added and deleted.
270Additional mechanism is required to deal correctly with the
271update-in-place performed by audit_upd_rule(). For one thing,
272audit_upd_rule() would need additional memory barriers to ensure
273that the list_add_rcu() was really executed before the list_del_rcu().
274
275The audit_del_rule() function would need to set the "deleted"
276flag 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
298Summary
299-------
300
301Read-mostly list-based data structures that can tolerate stale data are
302the most amenable to use of RCU. The simplest case is where entries are
303either added or deleted from the data structure (or atomically modified
304in place), but non-atomic in-place modifications can be handled by making
305a copy, updating the copy, then replacing the original with the copy.
306If stale data cannot be tolerated, then a "deleted" flag may be used
307in conjunction with a per-entry spinlock in order to allow the search
308function to reject newly deleted data.
309
310.. _answer_quick_quiz_list:
311
312Answer 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 @@
1Using RCU to Protect Read-Mostly Linked Lists
2
3
4One 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
6is that all of the required memory barriers are included for you in
7the list macros. This document describes several applications of RCU,
8with the best fits first.
9
10
11Example 1: Read-Side Action Taken Outside of Lock, No In-Place Updates
12
13The best applications are cases where, if reader-writer locking were
14used, the read-side lock would be dropped before taking any action
15based on the results of the search. The most celebrated example is
16the routing table. Because the routing table is tracking the state of
17equipment outside of the computer, it will at times contain stale data.
18Therefore, once the route has been computed, there is no need to hold
19the routing table static during transmission of the packet. After all,
20you can hold the routing table static all you want, but that won't keep
21the external Internet from changing, and it is the state of the external
22Internet that really matters. In addition, routing entries are typically
23added or deleted, rather than being modified in place.
24
25A straightforward example of this use of RCU may be found in the
26system-call auditing support. For example, a reader-writer locked
27implementation 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
46Here the list is searched under the lock, but the lock is dropped before
47the corresponding value is returned. By the time that this value is acted
48on, the list may well have been modified. This makes sense, since if
49you are turning auditing off, it is OK to audit a few extra system calls.
50
51This 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
70The read_lock() and read_unlock() calls have become rcu_read_lock()
71and rcu_read_unlock(), respectively, and the list_for_each_entry() has
72become list_for_each_entry_rcu(). The _rcu() list-traversal primitives
73insert the read-side memory barriers that are required on DEC Alpha CPUs.
74
75The changes to the update side are also straightforward. A reader-writer
76lock 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
109Following 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
140Normally, the write_lock() and write_unlock() would be replaced by
141a spin_lock() and a spin_unlock(), but in this case, all callers hold
142audit_netlink_sem, so no additional locking is required. The auditsc_lock
143can therefore be eliminated, since use of RCU eliminates the need for
144writers to exclude readers. Normally, the write_lock() calls would
145be converted into spin_lock() calls.
146
147The list_del(), list_add(), and list_add_tail() primitives have been
148replaced by list_del_rcu(), list_add_rcu(), and list_add_tail_rcu().
149The _rcu() list-manipulation primitives add memory barriers that are
150needed on weakly ordered CPUs (most of them!). The list_del_rcu()
151primitive omits the pointer poisoning debug-assist code that would
152otherwise cause concurrent readers to fail spectacularly.
153
154So, when readers can tolerate stale data and when entries are either added
155or deleted, without in-place modification, it is very easy to use RCU!
156
157
158Example 2: Handling In-Place Updates
159
160The system-call auditing code does not update auditing rules in place.
161However, if it did, reader-writer-locked code to do so might look as
162follows (presumably, the field_count is only permitted to decrease,
163otherwise, 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
187The RCU version creates a copy, updates the copy, then replaces the old
188entry with the newly updated entry. This sequence of actions, allowing
189concurrent reads while doing a copy to perform an update, is what gives
190RCU ("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
216Again, this assumes that the caller holds audit_netlink_sem. Normally,
217the reader-writer lock would become a spinlock in this sort of code.
218
219
220Example 3: Eliminating Stale Data
221
222The auditing examples above tolerate stale data, as do most algorithms
223that are tracking external state. Because there is a delay from the
224time the external state changes before Linux becomes aware of the change,
225additional RCU-induced staleness is normally not a problem.
226
227However, there are many examples where stale data cannot be tolerated.
228One example in the Linux kernel is the System V IPC (see the ipc_lock()
229function in ipc/util.c). This code checks a "deleted" flag under a
230per-entry spinlock, and, if the "deleted" flag is set, pretends that the
231entry does not exist. For this to be helpful, the search function must
232return holding the per-entry spinlock, as ipc_lock() does in fact do.
233
234Quick Quiz: Why does the search function need to return holding the
235 per-entry lock for this deleted-flag technique to be helpful?
236
237If the system-call audit module were to ever need to reject stale data,
238one way to accomplish this would be to add a "deleted" flag and a "lock"
239spinlock to the audit_entry structure, and modify audit_filter_task()
240as 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
264Note that this example assumes that entries are only added and deleted.
265Additional mechanism is required to deal correctly with the
266update-in-place performed by audit_upd_rule(). For one thing,
267audit_upd_rule() would need additional memory barriers to ensure
268that the list_add_rcu() was really executed before the list_del_rcu().
269
270The audit_del_rule() function would need to set the "deleted"
271flag 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
294Summary
295
296Read-mostly list-based data structures that can tolerate stale data are
297the most amenable to use of RCU. The simplest case is where entries are
298either added or deleted from the data structure (or atomically modified
299in place), but non-atomic in-place modifications can be handled by making
300a copy, updating the copy, then replacing the original with the copy.
301If stale data cannot be tolerated, then a "deleted" flag may be used
302in conjunction with a per-entry spinlock in order to allow the search
303function to reject newly deleted data.
304
305
306Answer 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
3RCU Concepts
4============
5
6The basic idea behind RCU (read-copy update) is to split destructive
7operations into two parts, one that prevents anyone from seeing the data
8item being destroyed, and one that actually carries out the destruction.
9A "grace period" must elapse between the two parts, and this grace period
10must be long enough that any readers accessing the item being deleted have
11since dropped their references. For example, an RCU-protected deletion
12from a linked list would first remove the item from the list, wait for
13a grace period to elapse, then free the element. See the
14Documentation/RCU/listRCU.rst file for more information on using RCU with
15linked lists.
16
17Frequently 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 @@
1RCU Concepts
2
3
4The basic idea behind RCU (read-copy update) is to split destructive
5operations into two parts, one that prevents anyone from seeing the data
6item being destroyed, and one that actually carries out the destruction.
7A "grace period" must elapse between the two parts, and this grace period
8must be long enough that any readers accessing the item being deleted have
9since dropped their references. For example, an RCU-protected deletion
10from a linked list would first remove the item from the list, wait for
11a grace period to elapse, then free the element. See the listRCU.txt
12file for more information on using RCU with linked lists.
13
14
15Frequently Asked Questions
16
17o 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
27o 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
47o 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
52o 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
62o What guidelines should I follow when writing code that uses RCU?
63
64 See the checklist.txt file in this directory.
65
66o 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
72o 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
81o 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
86o 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 @@
1Using hlist_nulls to protect read-mostly linked lists and1Using hlist_nulls to protect read-mostly linked lists and
2objects using SLAB_TYPESAFE_BY_RCU allocations.2objects using SLAB_TYPESAFE_BY_RCU allocations.
3 3
4Please read the basics in Documentation/RCU/listRCU.txt4Please read the basics in Documentation/RCU/listRCU.rst
5 5
6Using special makers (called 'nulls') is a convenient way6Using special makers (called 'nulls') is a convenient way
7to solve following problem :7to solve following problem :
Documentation/RCU/rcuref.txt+20−1
@@ -12,6 +12,7 @@ please read on. · 11 unmodified lines
12Reference counting on elements of lists which are protected by traditional12Reference counting on elements of lists which are protected by traditional
13reader/writer spinlocks or semaphores are straightforward:13reader/writer spinlocks or semaphores are straightforward:
14 14
15CODE LISTING A:
151. 2.161. 2.
16add() search_and_reference()17add() search_and_reference()
17{ {18{ {
@@ -28,7 +29,8 @@ add() search_and_reference() · 10 unmodified lines
28release_referenced() delete()29release_referenced() delete()
29{ {30{ {
30 ... write_lock(&list_lock);31 ... write_lock(&list_lock);
31 atomic_dec(&el->rc, relfunc) ...32 if(atomic_dec_and_test(&el->rc)) ...
33 kfree(el);
32 ... remove_element34 ... remove_element
33} write_unlock(&list_lock);35} write_unlock(&list_lock);
34 ...36 ...
@@ -44,6 +46,7 @@ search_and_reference() could potentially hold reference to an element which · 9 unmodified lines
44has already been deleted from the list/array. Use atomic_inc_not_zero()46has already been deleted from the list/array. Use atomic_inc_not_zero()
45in this scenario as follows:47in this scenario as follows:
46 48
49CODE LISTING B:
471. 2.501. 2.
48add() search_and_reference()51add() search_and_reference()
49{ {52{ {
@@ -79,6 +82,7 @@ search_and_reference() code path. In such cases, the · 29 unmodified lines
79atomic_dec_and_test() may be moved from delete() to el_free()82atomic_dec_and_test() may be moved from delete() to el_free()
80as follows:83as follows:
81 84
85CODE LISTING C:
821. 2.861. 2.
83add() search_and_reference()87add() search_and_reference()
84{ {88{ {
@@ -114,6 +118,17 @@ element can therefore safely be freed. This in turn guarantees that if · 29 unmodified lines
114any reader finds the element, that reader may safely acquire a reference118any reader finds the element, that reader may safely acquire a reference
115without checking the value of the reference counter.119without checking the value of the reference counter.
116 120
121A clear advantage of the RCU-based pattern in listing C over the one
122in listing B is that any call to search_and_reference() that locates
123a given object will succeed in obtaining a reference to that object,
124even given a concurrent invocation of delete() for that same object.
125Similarly, a clear advantage of both listings B and C over listing A is
126that a call to delete() is not delayed even if there are an arbitrarily
127large number of calls to search_and_reference() searching for the same
128object that delete() was invoked on. Instead, all that is delayed is
129the eventual invocation of kfree(), which is usually not a problem on
130modern computer systems, even the small ones.
131
117In cases where delete() can sleep, synchronize_rcu() can be called from132In cases where delete() can sleep, synchronize_rcu() can be called from
118delete(), so that el_free() can be subsumed into delete as follows:133delete(), so that el_free() can be subsumed into delete as follows:
119 134
@@ -130,3 +145,7 @@ delete() · 10 unmodified lines
130 kfree(el);145 kfree(el);
131 ...146 ...
132}147}
148
149As additional examples in the kernel, the pattern in listing C is used by
150reference counting of struct pid, while the pattern in listing B is used by
151struct posix_acl.
Documentation/RCU/stallwarn.txt+1−1
@@ -153,7 +153,7 @@ rcupdate.rcu_task_stall_timeout · 152 unmodified lines
153 This boot/sysfs parameter controls the RCU-tasks stall warning153 This boot/sysfs parameter controls the RCU-tasks stall warning
154 interval. A value of zero or less suppresses RCU-tasks stall154 interval. A value of zero or less suppresses RCU-tasks stall
155 warnings. A positive value sets the stall-warning interval155 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:
157 157
158 INFO: rcu_tasks detected stalls on tasks:158 INFO: rcu_tasks detected stalls on tasks:
159 159
Documentation/RCU/whatisRCU.txt+4−4
@@ -212,7 +212,7 @@ synchronize_rcu() · 211 unmodified lines
212 212
213rcu_assign_pointer()213rcu_assign_pointer()
214 214
215 typeof(p) rcu_assign_pointer(p, typeof(p) v);215 void rcu_assign_pointer(p, typeof(p) v);
216 216
217 Yes, rcu_assign_pointer() -is- implemented as a macro, though it217 Yes, rcu_assign_pointer() -is- implemented as a macro, though it
218 would be cool to be able to declare a function in this manner.218 would be cool to be able to declare a function in this manner.
@@ -220,9 +220,9 @@ rcu_assign_pointer() · 1 unmodified line
220 220
221 The updater uses this function to assign a new value to an221 The updater uses this function to assign a new value to an
222 RCU-protected pointer, in order to safely communicate the change222 RCU-protected pointer, in order to safely communicate the change
223 in value from the updater to the reader. This function returns223 in value from the updater to the reader. This macro does not
224 the new value, and also executes any memory-barrier instructions224 evaluate to an rvalue, but it does execute any memory-barrier
225 required for a given CPU architecture.225 instructions required for a given CPU architecture.
226 226
227 Perhaps just as important, it serves to document (1) which227 Perhaps just as important, it serves to document (1) which
228 pointers are protected by RCU and (2) the point at which a228 pointers are protected by RCU and (2) the point at which a
Documentation/accounting/cgroupstats.rst+31−0
@@ -0,0 +1,31 @@
1==================
2Control Groupstats
3==================
4
5Control Groupstats is inspired by the discussion at
6http://lkml.org/lkml/2007/4/11/187 and implements per cgroup statistics as
7suggested by Andrew Morton in http://lkml.org/lkml/2007/4/11/263.
8
9Per cgroup statistics infrastructure re-uses code from the taskstats
10interface. A new set of cgroup operations are registered with commands
11and attributes specific to cgroups. It should be very easy to
12extend per cgroup statistics, by adding members to the cgroupstats
13structure.
14
15The current model for cgroupstats is a pull, a push model (to post
16statistics on interesting events), should be very easy to add. Currently
17user space requests for statistics by passing the cgroup path.
18Statistics about the state of all the tasks in the cgroup is returned to
19user space.
20
21NOTE: We currently rely on delay accounting for extracting information
22about tasks blocked on I/O. If CONFIG_TASK_DELAY_ACCT is disabled, this
23information will not be available.
24
25To extract cgroup statistics a utility very similar to getdelays.c
26has 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 @@
1Control Groupstats is inspired by the discussion at
2http://lkml.org/lkml/2007/4/11/187 and implements per cgroup statistics as
3suggested by Andrew Morton in http://lkml.org/lkml/2007/4/11/263.
4
5Per cgroup statistics infrastructure re-uses code from the taskstats
6interface. A new set of cgroup operations are registered with commands
7and attributes specific to cgroups. It should be very easy to
8extend per cgroup statistics, by adding members to the cgroupstats
9structure.
10
11The current model for cgroupstats is a pull, a push model (to post
12statistics on interesting events), should be very easy to add. Currently
13user space requests for statistics by passing the cgroup path.
14Statistics about the state of all the tasks in the cgroup is returned to
15user space.
16
17NOTE: We currently rely on delay accounting for extracting information
18about tasks blocked on I/O. If CONFIG_TASK_DELAY_ACCT is disabled, this
19information will not be available.
20
21To extract cgroup statistics a utility very similar to getdelays.c
22has been developed, the sample output of the utility is shown below
23
24~/balbir/cgroupstats # ./getdelays -C "/sys/fs/cgroup/a"
25sleeping 1, blocked 0, running 1, stopped 0, uninterruptible 0
26~/balbir/cgroupstats # ./getdelays -C "/sys/fs/cgroup"
27sleeping 155, blocked 0, running 1, stopped 0, uninterruptible 2
Documentation/accounting/delay-accounting.rst+126−0
@@ -0,0 +1,126 @@
1================
2Delay accounting
3================
4
5Tasks encounter delays in execution when they wait
6for some kernel resource to become available e.g. a
7runnable task may wait for a free CPU to run on.
8
9The per-task delay accounting functionality measures
10the delays experienced by a task while
11
12a) waiting for a CPU (while being runnable)
13b) completion of synchronous block I/O initiated by the task
14c) swapping in pages
15d) memory reclaim
16
17and makes these statistics available to userspace through
18the taskstats interface.
19
20Such delays provide feedback for setting a task's cpu priority,
21io priority and rss limit values appropriately. Long delays for
22important tasks could be a trigger for raising its corresponding priority.
23
24The functionality, through its use of the taskstats interface, also provides
25delay statistics aggregated for all tasks (or threads) belonging to a
26thread group (corresponding to a traditional Unix process). This is a commonly
27needed aggregation that is more efficiently done by the kernel.
28
29Userspace utilities, particularly resource management applications, can also
30aggregate delay statistics into arbitrary groups. To enable this, delay
31statistics of a task are available both during its lifetime as well as on its
32exit, ensuring continuous and complete monitoring can be done.
33
34
35Interface
36---------
37
38Delay accounting uses the taskstats interface which is described
39in detail in a separate document in this directory. Taskstats returns a
40generic data structure to userspace corresponding to per-pid and per-tgid
41statistics. The delay accounting functionality populates specific fields of
42this structure. See
43
44 include/linux/taskstats.h
45
46for a description of the fields pertaining to delay accounting.
47It will generally be in the form of counters returning the cumulative
48delay seen for cpu, sync block I/O, swapin, memory reclaim etc.
49
50Taking the difference of two successive readings of a given
51counter (say cpu_delay_total) for a task will give the delay
52experienced by the task waiting for the corresponding resource
53in that interval.
54
55When a task exits, records containing the per-task statistics
56are sent to userspace without requiring a command. If it is the last exiting
57task of a thread group, the per-tgid statistics are also sent. More details
58are given in the taskstats interface description.
59
60The getdelays.c userspace utility in tools/accounting directory allows simple
61commands to be run and the corresponding delay statistics to be displayed. It
62also serves as an example of using the taskstats interface.
63
64Usage
65-----
66
67Compile the kernel with::
68
69 CONFIG_TASK_DELAY_ACCT=y
70 CONFIG_TASKSTATS=y
71
72Delay accounting is enabled by default at boot up.
73To disable, add::
74
75 nodelayacct
76
77to the kernel boot options. The rest of the instructions
78below assume this has not been done.
79
80After the system has booted up, use a utility
81similar to getdelays.c to access the delays
82seen by a given task or a task group (tgid).
83The utility also allows a given command to be
84executed and the corresponding delays to be
85seen.
86
87General format of the getdelays command::
88
89 getdelays [-t tgid] [-p pid] [-c cmd...]
90
91
92Get delays, since system boot, for pid 10::
93
94 # ./getdelays -p 10
95 (output similar to next case)
96
97Get 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
111Get 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 @@
1Delay accounting
2----------------
3
4Tasks encounter delays in execution when they wait
5for some kernel resource to become available e.g. a
6runnable task may wait for a free CPU to run on.
7
8The per-task delay accounting functionality measures
9the delays experienced by a task while
10
11a) waiting for a CPU (while being runnable)
12b) completion of synchronous block I/O initiated by the task
13c) swapping in pages
14d) memory reclaim
15
16and makes these statistics available to userspace through
17the taskstats interface.
18
19Such delays provide feedback for setting a task's cpu priority,
20io priority and rss limit values appropriately. Long delays for
21important tasks could be a trigger for raising its corresponding priority.
22
23The functionality, through its use of the taskstats interface, also provides
24delay statistics aggregated for all tasks (or threads) belonging to a
25thread group (corresponding to a traditional Unix process). This is a commonly
26needed aggregation that is more efficiently done by the kernel.
27
28Userspace utilities, particularly resource management applications, can also
29aggregate delay statistics into arbitrary groups. To enable this, delay
30statistics of a task are available both during its lifetime as well as on its
31exit, ensuring continuous and complete monitoring can be done.
32
33
34Interface
35---------
36
37Delay accounting uses the taskstats interface which is described
38in detail in a separate document in this directory. Taskstats returns a
39generic data structure to userspace corresponding to per-pid and per-tgid
40statistics. The delay accounting functionality populates specific fields of
41this structure. See
42 include/linux/taskstats.h
43for a description of the fields pertaining to delay accounting.
44It will generally be in the form of counters returning the cumulative
45delay seen for cpu, sync block I/O, swapin, memory reclaim etc.
46
47Taking the difference of two successive readings of a given
48counter (say cpu_delay_total) for a task will give the delay
49experienced by the task waiting for the corresponding resource
50in that interval.
51
52When a task exits, records containing the per-task statistics
53are sent to userspace without requiring a command. If it is the last exiting
54task of a thread group, the per-tgid statistics are also sent. More details
55are given in the taskstats interface description.
56
57The getdelays.c userspace utility in tools/accounting directory allows simple
58commands to be run and the corresponding delay statistics to be displayed. It
59also serves as an example of using the taskstats interface.
60
61Usage
62-----
63
64Compile the kernel with
65 CONFIG_TASK_DELAY_ACCT=y
66 CONFIG_TASKSTATS=y
67
68Delay accounting is enabled by default at boot up.
69To disable, add
70 nodelayacct
71to the kernel boot options. The rest of the instructions
72below assume this has not been done.
73
74After the system has booted up, use a utility
75similar to getdelays.c to access the delays
76seen by a given task or a task group (tgid).
77The utility also allows a given command to be
78executed and the corresponding delays to be
79seen.
80
81General format of the getdelays command
82
83getdelays [-t tgid] [-p pid] [-c cmd...]
84
85
86Get delays, since system boot, for pid 10
87# ./getdelays -p 10
88(output similar to next case)
89
90Get sum of delays, since system boot, for all pids with tgid 5
91# ./getdelays -t 5
92
93
94CPU count real total virtual total delay total
95 7876 92005750 100000000 24001500
96IO count delay total
97 0 0
98SWAP count delay total
99 0 0
100RECLAIM count delay total
101 0 0
102
103Get delays seen in executing a given simple command
104# ./getdelays -c ls /
105
106bin data1 data3 data5 dev home media opt root srv sys usr
107boot data2 data4 data6 etc lib mnt proc sbin subdomain tmp var
108
109
110CPU count real total virtual total delay total
111 6 4000250 4000000 0
112IO count delay total
113 0 0
114SWAP count delay total
115 0 0
116RECLAIM 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==========
4Accounting
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================================
2PSI - Pressure Stall Information
3================================
4
5:Date: April, 2018
6:Author: Johannes Weiner <hannes@cmpxchg.org>
7
8When CPU, memory or IO devices are contended, workloads experience
9latency spikes, throughput losses, and run the risk of OOM kills.
10
11Without an accurate measure of such contention, users are forced to
12either play it safe and under-utilize their hardware resources, or
13roll the dice and frequently suffer the disruptions resulting from
14excessive overcommit.
15
16The psi feature identifies and quantifies the disruptions caused by
17such resource crunches and the time impact it has on complex workloads
18or even entire systems.
19
20Having an accurate measure of productivity losses caused by resource
21scarcity aids users in sizing workloads to hardware--or provisioning
22hardware according to workload demand.
23
24As psi aggregates this information in realtime, systems can be managed
25dynamically using techniques such as load shedding, migrating jobs to
26other systems or data centers, or strategically pausing or killing low
27priority or restartable batch jobs.
28
29This allows maximizing hardware utilization without sacrificing
30workload health or risking major disruptions such as OOM kills.
31
32Pressure interface
33==================
34
35Pressure information for each resource is exported through the
36respective file in /proc/pressure/ -- cpu, memory, and io.
37
38The format for CPU is as such::
39
40 some avg10=0.00 avg60=0.00 avg300=0.00 total=0
41
42and 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
47The "some" line indicates the share of time in which at least some
48tasks are stalled on a given resource.
49
50The "full" line indicates the share of time in which all non-idle
51tasks are stalled on a given resource simultaneously. In this state
52actual CPU cycles are going to waste, and a workload that spends
53extended time in this state is considered to be thrashing. This has
54severe impact on performance, and it's useful to distinguish this
55situation from a state where some tasks are stalled but the CPU is
56still doing productive work. As such, time spent in this subset of the
57stall state is tracked separately and exported in the "full" averages.
58
59The ratios (in %) are tracked as recent trends over ten, sixty, and
60three hundred second windows, which gives insight into short term events
61as 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
63spikes which wouldn't necessarily make a dent in the time averages,
64or to average trends over custom time frames.
65
66Monitoring for pressure thresholds
67==================================
68
69Users can register triggers and use poll() to be woken up when resource
70pressure exceeds certain thresholds.
71
72A trigger describes the maximum cumulative stall time over a specific
73time window, e.g. 100ms of total stall time within any 500ms window to
74generate a wakeup event.
75
76To register a trigger user has to open psi interface file under
77/proc/pressure/ representing the resource to be monitored and write the
78desired threshold and time window. The open file descriptor should be
79used to wait for trigger events using select(), poll() or epoll().
80The following format is used::
81
82 <some|full> <stall amount in us> <time window in us>
83
84For example writing "some 150000 1000000" into /proc/pressure/memory
85would add 150ms threshold for partial memory stall measured within
861sec time window. Writing "full 50000 1000000" into /proc/pressure/io
87would add 50ms threshold for full io stall measured within 1sec time window.
88
89Triggers can be set on more than one psi metric and more than one trigger
90for the same psi metric can be specified. However for each trigger a separate
91file descriptor is required to be able to poll it separately from others,
92therefore for each trigger a separate open() syscall should be made even
93when opening the same psi interface file.
94
95Monitors activate only when system enters stall state for the monitored
96psi metric and deactivates upon exit from the stall state. While system is
97in the stall state psi signal growth is monitored at a rate of 10 times per
98tracking window.
99
100The kernel accepts window sizes ranging from 500ms to 10s, therefore min
101monitoring update interval is 50ms and max is 1s. Min limit is set to
102prevent overly frequent polling. Max limit is chosen as a high enough number
103after which monitors are most likely not needed and psi averages can be used
104instead.
105
106When activated, psi monitor stays active for at least the duration of one
107tracking window to avoid repeated activations/deactivations when system is
108bouncing in and out of the stall state.
109
110Notifications to the userspace are rate-limited to one per tracking window.
111
112The trigger will de-register when the file descriptor used to define the
113trigger is closed.
114
115Userspace 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
172Cgroup2 interface
173=================
174
175In a system with a CONFIG_CGROUP=y kernel and the cgroup2 filesystem
176mounted, pressure stall information is also tracked for tasks grouped
177into cgroups. Each subdirectory in the cgroupfs mountpoint contains
178cpu.pressure, memory.pressure, and io.pressure files; the format is
179the same as the /proc/pressure/ files.
180
181Per-cgroup psi monitors can be specified and used the same way as
182system-wide ones.
Documentation/accounting/psi.txt+0−180
@@ -1,180 +0,0 @@
1================================
2PSI - Pressure Stall Information
3================================
4
5:Date: April, 2018
6:Author: Johannes Weiner <hannes@cmpxchg.org>
7
8When CPU, memory or IO devices are contended, workloads experience
9latency spikes, throughput losses, and run the risk of OOM kills.
10
11Without an accurate measure of such contention, users are forced to
12either play it safe and under-utilize their hardware resources, or
13roll the dice and frequently suffer the disruptions resulting from
14excessive overcommit.
15
16The psi feature identifies and quantifies the disruptions caused by
17such resource crunches and the time impact it has on complex workloads
18or even entire systems.
19
20Having an accurate measure of productivity losses caused by resource
21scarcity aids users in sizing workloads to hardware--or provisioning
22hardware according to workload demand.
23
24As psi aggregates this information in realtime, systems can be managed
25dynamically using techniques such as load shedding, migrating jobs to
26other systems or data centers, or strategically pausing or killing low
27priority or restartable batch jobs.
28
29This allows maximizing hardware utilization without sacrificing
30workload health or risking major disruptions such as OOM kills.
31
32Pressure interface
33==================
34
35Pressure information for each resource is exported through the
36respective file in /proc/pressure/ -- cpu, memory, and io.
37
38The format for CPU is as such:
39
40some avg10=0.00 avg60=0.00 avg300=0.00 total=0
41
42and for memory and IO:
43
44some avg10=0.00 avg60=0.00 avg300=0.00 total=0
45full avg10=0.00 avg60=0.00 avg300=0.00 total=0
46
47The "some" line indicates the share of time in which at least some
48tasks are stalled on a given resource.
49
50The "full" line indicates the share of time in which all non-idle
51tasks are stalled on a given resource simultaneously. In this state
52actual CPU cycles are going to waste, and a workload that spends
53extended time in this state is considered to be thrashing. This has
54severe impact on performance, and it's useful to distinguish this
55situation from a state where some tasks are stalled but the CPU is
56still doing productive work. As such, time spent in this subset of the
57stall state is tracked separately and exported in the "full" averages.
58
59The ratios (in %) are tracked as recent trends over ten, sixty, and
60three hundred second windows, which gives insight into short term events
61as 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
63spikes which wouldn't necessarily make a dent in the time averages,
64or to average trends over custom time frames.
65
66Monitoring for pressure thresholds
67==================================
68
69Users can register triggers and use poll() to be woken up when resource
70pressure exceeds certain thresholds.
71
72A trigger describes the maximum cumulative stall time over a specific
73time window, e.g. 100ms of total stall time within any 500ms window to
74generate a wakeup event.
75
76To register a trigger user has to open psi interface file under
77/proc/pressure/ representing the resource to be monitored and write the
78desired threshold and time window. The open file descriptor should be
79used to wait for trigger events using select(), poll() or epoll().
80The following format is used:
81
82<some|full> <stall amount in us> <time window in us>
83
84For example writing "some 150000 1000000" into /proc/pressure/memory
85would add 150ms threshold for partial memory stall measured within
861sec time window. Writing "full 50000 1000000" into /proc/pressure/io
87would add 50ms threshold for full io stall measured within 1sec time window.
88
89Triggers can be set on more than one psi metric and more than one trigger
90for the same psi metric can be specified. However for each trigger a separate
91file descriptor is required to be able to poll it separately from others,
92therefore for each trigger a separate open() syscall should be made even
93when opening the same psi interface file.
94
95Monitors activate only when system enters stall state for the monitored
96psi metric and deactivates upon exit from the stall state. While system is
97in the stall state psi signal growth is monitored at a rate of 10 times per
98tracking window.
99
100The kernel accepts window sizes ranging from 500ms to 10s, therefore min
101monitoring update interval is 50ms and max is 1s. Min limit is set to
102prevent overly frequent polling. Max limit is chosen as a high enough number
103after which monitors are most likely not needed and psi averages can be used
104instead.
105
106When activated, psi monitor stays active for at least the duration of one
107tracking window to avoid repeated activations/deactivations when system is
108bouncing in and out of the stall state.
109
110Notifications to the userspace are rate-limited to one per tracking window.
111
112The trigger will de-register when the file descriptor used to define the
113trigger is closed.
114
115Userspace 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 */
129int 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
170Cgroup2 interface
171=================
172
173In a system with a CONFIG_CGROUP=y kernel and the cgroup2 filesystem
174mounted, pressure stall information is also tracked for tasks grouped
175into cgroups. Each subdirectory in the cgroupfs mountpoint contains
176cpu.pressure, memory.pressure, and io.pressure files; the format is
177the same as the /proc/pressure/ files.
178
179Per-cgroup psi monitors can be specified and used the same way as
180system-wide ones.
Documentation/accounting/taskstats-struct.rst+199−0
@@ -0,0 +1,199 @@
1====================
2The struct taskstats
3====================
4
5This document contains an explanation of the struct taskstats fields.
6
7There are three different groups of fields in the struct taskstats:
8
91) 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.
132) 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.
233) 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
344) Per-task and per-thread context switch count statistics
35
365) Time accounting for SMT machines
37
386) Extended delay accounting fields for memory reclaim
39
40Future extension should add fields to the end of the taskstats struct, and
41should not change the relative position of each field within the struct.
42
43::
44
45 struct taskstats {
46
471) 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
972) 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
1493) 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
1804) Per-task and per-thread statistics::
181
182 __u64 nvcsw; /* Context voluntary switch counter */
183 __u64 nivcsw; /* Context involuntary switch counter */
184
1855) 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
1916) 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 @@
1The struct taskstats
2--------------------
3
4This document contains an explanation of the struct taskstats fields.
5
6There are three different groups of fields in the struct taskstats:
7
81) 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.
122) 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.
183) 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
254) Per-task and per-thread context switch count statistics
26
275) Time accounting for SMT machines
28
296) Extended delay accounting fields for memory reclaim
30
31Future extension should add fields to the end of the taskstats struct, and
32should not change the relative position of each field within the struct.
33
34
35struct taskstats {
36
371) 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
862) 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
1373) 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
1674) Per-task and per-thread statistics
168 __u64 nvcsw; /* Context voluntary switch counter */
169 __u64 nivcsw; /* Context involuntary switch counter */
170
1715) 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
1766) 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=============================
2Per-task statistics interface
3=============================
4
5
6Taskstats is a netlink-based interface for sending per-task and
7per-process statistics from the kernel to userspace.
8
9Taskstats 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
15Terminology
16-----------
17
18"pid", "tid" and "task" are used interchangeably and refer to the standard
19Linux task defined by struct task_struct. per-pid stats are the same as
20per-task stats.
21
22"tgid", "process" and "thread group" are used interchangeably and refer to the
23tasks that share an mm_struct i.e. the traditional Unix process. Despite the
24use of tgid, there is no special treatment for the task that is thread group
25leader - a process is deemed alive as long as it has any task belonging to it.
26
27Usage
28-----
29
30To get statistics during a task's lifetime, userspace opens a unicast netlink
31socket (NETLINK_GENERIC family) and sends commands specifying a pid or a tgid.
32The response contains statistics for a task (if pid is specified) or the sum of
33statistics for all tasks of the process (if tgid is specified).
34
35To obtain statistics for tasks which are exiting, the userspace listener
36sends a register command and specifies a cpumask. Whenever a task exits on
37one of the cpus in the cpumask, its per-pid statistics are sent to the
38registered listener. Using cpumasks allows the data received by one listener
39to be limited and assists in flow control over the netlink interface and is
40explained in more detail below.
41
42If the exiting task is the last thread exiting its thread group,
43an additional record containing the per-tgid stats is also sent to userspace.
44The latter contains the sum of per-pid stats for all threads in the thread
45group, both past and present.
46
47getdelays.c is a simple utility demonstrating usage of the taskstats interface
48for reporting delay accounting statistics. Users can register cpumasks,
49send commands and process responses, listen for per-tid/tgid exit data,
50write the data received to a file and do basic flow control by increasing
51receive buffer sizes.
52
53Interface
54---------
55
56The user-kernel interface is encapsulated in include/linux/taskstats.h
57
58To avoid this documentation becoming obsolete as the interface evolves, only
59an outline of the current version is given. taskstats.h always overrides the
60description here.
61
62struct taskstats is the common accounting structure for both per-pid and
63per-tgid data. It is versioned and can be extended by each accounting subsystem
64that is added to the kernel. The fields and their semantics are defined in the
65taskstats.h file.
66
67The data exchanged between user and kernel space is a netlink message belonging
68to the NETLINK_GENERIC family and using the netlink attributes interface.
69The messages are in the format::
70
71 +----------+- - -+-------------+-------------------+
72 | nlmsghdr | Pad | genlmsghdr | taskstats payload |
73 +----------+- - -+-------------+-------------------+
74
75
76The taskstats payload is one of the following three kinds:
77
781. Commands: Sent from user to kernel. Commands to get data on
79a pid/tgid consist of one attribute, of type TASKSTATS_CMD_ATTR_PID/TGID,
80containing a u32 pid or tgid in the attribute payload. The pid/tgid denotes
81the task/process for which userspace wants statistics.
82
83Commands to register/deregister interest in exit data from a set of cpus
84consist of one attribute, of type
85TASKSTATS_CMD_ATTR_REGISTER/DEREGISTER_CPUMASK and contain a cpumask in the
86attribute payload. The cpumask is specified as an ascii string of
87comma-separated cpu ranges e.g. to listen to exit data from cpus 1,2,3,5,7,8
88the cpumask would be "1-3,5,7-8". If userspace forgets to deregister interest
89in cpus before closing the listening socket, the kernel cleans up its interest
90set over time. However, for the sake of efficiency, an explicit deregistration
91is advisable.
92
932. Response for a command: sent from the kernel in response to a userspace
94command. The payload is a series of three attributes of type:
95
96a) TASKSTATS_TYPE_AGGR_PID/TGID : attribute containing no payload but indicates
97a pid/tgid will be followed by some stats.
98
99b) TASKSTATS_TYPE_PID/TGID: attribute whose payload is the pid/tgid whose stats
100are being returned.
101
102c) TASKSTATS_TYPE_STATS: attribute with a struct taskstats as payload. The
103same structure is used for both per-pid and per-tgid stats.
104
1053. New message sent by kernel whenever a task exits. The payload consists of a
106 series of attributes of the following type:
107
108a) TASKSTATS_TYPE_AGGR_PID: indicates next two attributes will be pid+stats
109b) TASKSTATS_TYPE_PID: contains exiting task's pid
110c) TASKSTATS_TYPE_STATS: contains the exiting task's per-pid stats
111d) TASKSTATS_TYPE_AGGR_TGID: indicates next two attributes will be tgid+stats
112e) TASKSTATS_TYPE_TGID: contains tgid of process to which task belongs
113f) TASKSTATS_TYPE_STATS: contains the per-tgid stats for exiting task's process
114
115
116per-tgid stats
117--------------
118
119Taskstats provides per-process stats, in addition to per-task stats, since
120resource management is often done at a process granularity and aggregating task
121stats in userspace alone is inefficient and potentially inaccurate (due to lack
122of atomicity).
123
124However, maintaining per-process, in addition to per-task stats, within the
125kernel has space and time overheads. To address this, the taskstats code
126accumulates each exiting task's statistics into a process-wide data structure.
127When the last task of a process exits, the process level data accumulated also
128gets sent to userspace (along with the per-task data).
129
130When a user queries to get per-tgid data, the sum of all other live threads in
131the group is added up and added to the accumulated total for previously exited
132threads of the same thread group.
133
134Extending taskstats
135-------------------
136
137There are two ways to extend the taskstats interface to export more
138per-task/process stats as patches to collect them get added to the kernel
139in future:
140
1411. 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
1462. 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
152Choosing between 1. and 2. is a matter of trading off flexibility and
153overhead. If only a few fields need to be added, then 1. is the preferable
154path since the kernel and userspace don't need to incur the overhead of
155processing new netlink attributes. But if the new fields expand the existing
156struct too much, requiring disparate userspace accounting utilities to
157unnecessarily receive large structures whose fields are of no interest, then
158extending the attributes structure would be worthwhile.
159
160Flow control for taskstats
161--------------------------
162
163When the rate of task exits becomes large, a listener may not be able to keep
164up with the kernel's rate of sending per-tid/tgid exit data leading to data
165loss. This possibility gets compounded when the taskstats structure gets
166extended and the number of cpus grows large.
167
168To 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
178Despite these measures, if the userspace receives ENOBUFS error messages
179indicated overflow of receive buffers, it should take measures to handle the
180loss of data.
Documentation/accounting/taskstats.txt+0−181
@@ -1,181 +0,0 @@
1Per-task statistics interface
2-----------------------------
3
4
5Taskstats is a netlink-based interface for sending per-task and
6per-process statistics from the kernel to userspace.
7
8Taskstats 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
14Terminology
15-----------
16
17"pid", "tid" and "task" are used interchangeably and refer to the standard
18Linux task defined by struct task_struct. per-pid stats are the same as
19per-task stats.
20
21"tgid", "process" and "thread group" are used interchangeably and refer to the
22tasks that share an mm_struct i.e. the traditional Unix process. Despite the
23use of tgid, there is no special treatment for the task that is thread group
24leader - a process is deemed alive as long as it has any task belonging to it.
25
26Usage
27-----
28
29To get statistics during a task's lifetime, userspace opens a unicast netlink
30socket (NETLINK_GENERIC family) and sends commands specifying a pid or a tgid.
31The response contains statistics for a task (if pid is specified) or the sum of
32statistics for all tasks of the process (if tgid is specified).
33
34To obtain statistics for tasks which are exiting, the userspace listener
35sends a register command and specifies a cpumask. Whenever a task exits on
36one of the cpus in the cpumask, its per-pid statistics are sent to the
37registered listener. Using cpumasks allows the data received by one listener
38to be limited and assists in flow control over the netlink interface and is
39explained in more detail below.
40
41If the exiting task is the last thread exiting its thread group,
42an additional record containing the per-tgid stats is also sent to userspace.
43The latter contains the sum of per-pid stats for all threads in the thread
44group, both past and present.
45
46getdelays.c is a simple utility demonstrating usage of the taskstats interface
47for reporting delay accounting statistics. Users can register cpumasks,
48send commands and process responses, listen for per-tid/tgid exit data,
49write the data received to a file and do basic flow control by increasing
50receive buffer sizes.
51
52Interface
53---------
54
55The user-kernel interface is encapsulated in include/linux/taskstats.h
56
57To avoid this documentation becoming obsolete as the interface evolves, only
58an outline of the current version is given. taskstats.h always overrides the
59description here.
60
61struct taskstats is the common accounting structure for both per-pid and
62per-tgid data. It is versioned and can be extended by each accounting subsystem
63that is added to the kernel. The fields and their semantics are defined in the
64taskstats.h file.
65
66The data exchanged between user and kernel space is a netlink message belonging
67to the NETLINK_GENERIC family and using the netlink attributes interface.
68The messages are in the format
69
70 +----------+- - -+-------------+-------------------+
71 | nlmsghdr | Pad | genlmsghdr | taskstats payload |
72 +----------+- - -+-------------+-------------------+
73
74
75The taskstats payload is one of the following three kinds:
76
771. Commands: Sent from user to kernel. Commands to get data on
78a pid/tgid consist of one attribute, of type TASKSTATS_CMD_ATTR_PID/TGID,
79containing a u32 pid or tgid in the attribute payload. The pid/tgid denotes
80the task/process for which userspace wants statistics.
81
82Commands to register/deregister interest in exit data from a set of cpus
83consist of one attribute, of type
84TASKSTATS_CMD_ATTR_REGISTER/DEREGISTER_CPUMASK and contain a cpumask in the
85attribute payload. The cpumask is specified as an ascii string of
86comma-separated cpu ranges e.g. to listen to exit data from cpus 1,2,3,5,7,8
87the cpumask would be "1-3,5,7-8". If userspace forgets to deregister interest
88in cpus before closing the listening socket, the kernel cleans up its interest
89set over time. However, for the sake of efficiency, an explicit deregistration
90is advisable.
91
922. Response for a command: sent from the kernel in response to a userspace
93command. The payload is a series of three attributes of type:
94
95a) TASKSTATS_TYPE_AGGR_PID/TGID : attribute containing no payload but indicates
96a pid/tgid will be followed by some stats.
97
98b) TASKSTATS_TYPE_PID/TGID: attribute whose payload is the pid/tgid whose stats
99are being returned.
100
101c) TASKSTATS_TYPE_STATS: attribute with a struct taskstats as payload. The
102same structure is used for both per-pid and per-tgid stats.
103
1043. New message sent by kernel whenever a task exits. The payload consists of a
105 series of attributes of the following type:
106
107a) TASKSTATS_TYPE_AGGR_PID: indicates next two attributes will be pid+stats
108b) TASKSTATS_TYPE_PID: contains exiting task's pid
109c) TASKSTATS_TYPE_STATS: contains the exiting task's per-pid stats
110d) TASKSTATS_TYPE_AGGR_TGID: indicates next two attributes will be tgid+stats
111e) TASKSTATS_TYPE_TGID: contains tgid of process to which task belongs
112f) TASKSTATS_TYPE_STATS: contains the per-tgid stats for exiting task's process
113
114
115per-tgid stats
116--------------
117
118Taskstats provides per-process stats, in addition to per-task stats, since
119resource management is often done at a process granularity and aggregating task
120stats in userspace alone is inefficient and potentially inaccurate (due to lack
121of atomicity).
122
123However, maintaining per-process, in addition to per-task stats, within the
124kernel has space and time overheads. To address this, the taskstats code
125accumulates each exiting task's statistics into a process-wide data structure.
126When the last task of a process exits, the process level data accumulated also
127gets sent to userspace (along with the per-task data).
128
129When a user queries to get per-tgid data, the sum of all other live threads in
130the group is added up and added to the accumulated total for previously exited
131threads of the same thread group.
132
133Extending taskstats
134-------------------
135
136There are two ways to extend the taskstats interface to export more
137per-task/process stats as patches to collect them get added to the kernel
138in future:
139
1401. 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
1452. 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
151Choosing between 1. and 2. is a matter of trading off flexibility and
152overhead. If only a few fields need to be added, then 1. is the preferable
153path since the kernel and userspace don't need to incur the overhead of
154processing new netlink attributes. But if the new fields expand the existing
155struct too much, requiring disparate userspace accounting utilities to
156unnecessarily receive large structures whose fields are of no interest, then
157extending the attributes structure would be worthwhile.
158
159Flow control for taskstats
160--------------------------
161
162When the rate of task exits becomes large, a listener may not be able to keep
163up with the kernel's rate of sending per-tid/tgid exit data leading to data
164loss. This possibility gets compounded when the taskstats structure gets
165extended and the number of cpus grows large.
166
167To 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
170listeners to receive exit data.
171
172- create more listeners and reduce the number of cpus being listened to by
173each listener. In the extreme case, there could be one listener for each cpu.
174Users may also consider setting the cpu affinity of the listener to the subset
175of cpus to which it listens, especially if they are listening to just one cpu.
176
177Despite these measures, if the userspace receives ENOBUFS error messages
178indicated overflow of receive buffers, it should take measures to handle the
179loss of data.
180
181----
Documentation/acpi/dsd/leds.txt+1−1
@@ -96,4 +96,4 @@ where · 95 unmodified lines
96 <URL:http://www.uefi.org/sites/default/files/resources/_DSD-hierarchical-data-extension-UUID-v1.1.pdf>,96 <URL:http://www.uefi.org/sites/default/files/resources/_DSD-hierarchical-data-extension-UUID-v1.1.pdf>,
97 referenced 2019-02-21.97 referenced 2019-02-21.
98 98
99[7] Documentation/acpi/dsd/data-node-reference.txt99[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
19created to toggle pinning: ``/proc/sys/kernel/loadpin/enabled``. (Having19created to toggle pinning: ``/proc/sys/kernel/loadpin/enabled``. (Having
20a mutable filesystem means pinning is mutable too, but having the20a mutable filesystem means pinning is mutable too, but having the
21sysctl allows for easy testing on systems with a mutable filesystem.)21sysctl allows for easy testing on systems with a mutable filesystem.)
22
23It's also possible to exclude specific file types from LoadPin using kernel
24command line option "``loadpin.exclude``". By default, all files are
25included, but they can be excluded using kernel command line option such
26as "``loadpin.exclude=kernel-module,kexec-image``". This allows to use
27different mechanisms such as ``CONFIG_MODULE_SIG`` and
28``CONFIG_KEXEC_VERIFY_SIG`` to verify kernel module and kernel image while
29still use LoadPin to protect the integrity of other files kernel loads. The
30full list of valid file types can be found in ``kernel_read_file_str``
31defined in ``include/linux/fs.h``.
Documentation/admin-guide/README.rst+1−1
@@ -227,7 +227,7 @@ Configuring the kernel · 226 unmodified lines
227 "make tinyconfig" Configure the tiniest possible kernel.227 "make tinyconfig" Configure the tiniest possible kernel.
228 228
229 You can find more information on using the Linux kernel config tools229 You can find more information on using the Linux kernel config tools
230 in Documentation/kbuild/kconfig.txt.230 in Documentation/kbuild/kconfig.rst.
231 231
232 - NOTES on ``make config``:232 - NOTES on ``make config``:
233 233
Documentation/admin-guide/aoe/aoe.rst+150−0
@@ -0,0 +1,150 @@
1Introduction
2============
3
4ATA over Ethernet is a network protocol that provides simple access to
5block storage on the LAN.
6
7 http://support.coraid.com/documents/AoEr11.txt
8
9The 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
13It has many tips and hints! Please see, especially, recommended
14tunings for virtual memory:
15
16 http://support.coraid.com/support/linux/EtherDrive-2.6-HOWTO-5.html#ss5.19
17
18The aoetools are userland programs that are designed to work with this
19driver. The aoetools are on sourceforge.
20
21 http://aoetools.sourceforge.net/
22
23The scripts in this Documentation/admin-guide/aoe directory are intended to
24document the use of the driver and are not necessary if you install
25the aoetools.
26
27
28Creating 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
45Using 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
72Using 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
122Driver 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 @@
1Example of udev rules
2---------------------
3
4 .. include:: udev.txt
5 :literal:
6
7Example of udev install rules script
8------------------------------------
9
10 .. literalinclude:: udev-install.sh
11 :language: shell
12
13Example script to get status
14----------------------------
15
16 .. literalinclude:: status.sh
17 :language: shell
18
19Example 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=======================
2ATA 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 @@
1TODO
2====
3
4There is a potential for deadlock when allocating a struct sk_buff for
5data that needs to be written out to aoe storage. If the data is
6being written from a dirty page in order to free that page, and if
7there are no other pages available, then deadlock may occur when a
8free page is needed for the sk_buff allocation. This situation has
9not been observed, but it would be nice to eliminate any potential for
10deadlock under memory pressure.
11
12Because ATA over Ethernet is not fragmented by the kernel's IP code,
13the destructor member of the struct sk_buff is available to the aoe
14driver. By using a mempool for allocating all but the first few
15sk_buffs, and by registering a destructor, we should be able to
16efficiently allocate sk_buffs without introducing any potential for
17deadlock.
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
11# udev_rules="/etc/udev/rules.d/"11# udev_rules="/etc/udev/rules.d/"
12# bash# ls /etc/udev/rules.d/12# bash# ls /etc/udev/rules.d/
13# 10-wacom.rules 50-udev.rules13# 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 \
15# /etc/udev/rules.d/60-aoe.rules15# /etc/udev/rules.d/60-aoe.rules
16# 16#
17 17
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================================
2kernel data structure for DRBD-9
3================================
4
5This describes the in kernel data structure for DRBD-9. Starting with
6Linux v3.14 we are reorganizing DRBD to use this data structure.
7
8Basic Data Structure
9====================
10
11A node has a number of DRBD resources. Each such resource has a number of
12devices (aka volumes) and connections to other nodes ("peer nodes"). Each DRBD
13device is represented by a block device locally.
14
15The DRBD objects are interconnected to form a matrix as depicted below; a
16drbd_peer_device object sits at each intersection between a drbd_device and a
17drbd_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
30In this table, horizontally, devices can be accessed from resources by their
31volume number. Likewise, peer_devices can be accessed from connections by
32their volume number. Objects in the vertical direction are connected by double
33linked lists. There are back pointers from peer_devices to their connections a
34devices, and from connections and devices to their resource.
35
36All resources are in the drbd_resources double-linked list. In addition, all
37devices can be accessed by their minor device number via the drbd_devices idr.
38
39The drbd_resource, drbd_connection, and drbd_device objects are reference
40counted. The peer_device objects only serve to establish the links between
41devices and connections; their lifetime is determined by the lifetime of the
42device 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
5Data 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
17Sub 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==========================================
2Distributed Replicated Block Device - DRBD
3==========================================
4
5Description
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
11 Unknown -> Primary [ label = "connected" ]11 Unknown -> Primary [ label = "connected" ]
12 Unknown -> Secondary [ label = "connected" ]12 Unknown -> Secondary [ label = "connected" ]
13}13}
14
Documentation/admin-guide/blockdev/floppy.rst+255−0
@@ -0,0 +1,255 @@
1=============
2Floppy Driver
3=============
4
5FAQ list:
6=========
7
8A FAQ list may be found in the fdutils package (see below), and also
9at <http://fdutils.linux.lu/faq.html>.
10
11
12LILO configuration options (Thinkpad users, read this)
13======================================================
14
15The floppy driver is configured using the 'floppy=' option in
16lilo. This option can be typed at the boot prompt, or entered in the
17lilo configuration file.
18
19Example: If your kernel is called linux-2.6.9, type the following line
20at the lilo boot prompt (if you have a thinkpad)::
21
22 linux-2.6.9 floppy=thinkpad
23
24You may also enter the following line in /etc/lilo.conf, in the description
25of linux-2.6.9::
26
27 append = "floppy=thinkpad"
28
29Several 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
34If you give options both in the lilo config file and on the boot
35prompt, the option strings of both places are concatenated, the boot
36prompt options coming last. That's why there are also options to
37restore the default behavior.
38
39
40Module configuration options
41============================
42
43If you use the floppy driver as a module, use the following syntax::
44
45 modprobe floppy floppy="<options>"
46
47Example::
48
49 modprobe floppy floppy="omnibook messages"
50
51If you need certain options enabled every time you load the floppy driver,
52you can put::
53
54 options floppy floppy="omnibook messages"
55
56in a configuration file in /etc/modprobe.d/.
57
58
59The 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
212Supporting utilities and additional documentation:
213==================================================
214
215Additional parameters of the floppy driver can be configured at
216runtime. Utilities which do this can be found in the fdutils package.
217This package also contains a new version of mtools which allows to
218access high capacity disks (up to 1992K on a high density 3 1/2 disk!).
219It also contains additional documentation about the floppy driver.
220
221The latest version can be found at fdutils homepage:
222
223 http://fdutils.linux.lu
224
225The 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
233Reporting problems about the floppy driver
234==========================================
235
236If you have a question or a bug report about the floppy driver, mail
237me at Alain.Knaff@poboxes.com . If you post to Usenet, preferably use
238comp.os.linux.hardware. As the volume in these groups is rather high,
239be sure to include the word "floppy" (or "FLOPPY") in the subject
240line. If the reported problem happens when mounting floppy disks, be
241sure to mention also the type of the filesystem in the subject line.
242
243Be sure to read the FAQ before mailing/posting any bug reports!
244
245Alain
246
247Changelog
248=========
249
25010-30-2004 :
251 Cleanup, updating, add reference to module configuration.
252 James Nelson <james4765@gmail.com>
253
2546-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===========================
4The 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==================================
2Network Block Device (TCP version)
3==================================
4
51) Overview
6-----------
7
8What is it: With this compiled in the kernel (or as a module), Linux
9can use a remote server as one of its block devices. So every time
10the client computer wants to read, e.g., /dev/nb0, it sends a
11request over TCP to the server, which will reply with the data read.
12This can be used for stations with low disk space (or even diskless)
13to borrow disk space from another computer.
14Unlike NFS, it is possible to put any filesystem on it, etc.
15
16For more information, or to download the nbd-client and nbd-server
17tools, go to http://nbd.sf.net/.
18
19The nbd kernel module need only be installed on the client
20system, as the nbd-server is completely in userspace. In fact,
21the nbd-server has been successfully ported to other operating
22systems, including Windows.
23
24A) NBD parameters
25-----------------
26
27max_part
28 Number of partitions per device (default: 0).
29
30nbds_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===================================
2Linux and parallel port IDE devices
3===================================
4
5PARIDE v1.03 (c) 1997-8 Grant Guenther <grant@torque.net>
6
71. Introduction
8===============
9
10Owing to the simplicity and near universality of the parallel port interface
11to personal computers, many external devices such as portable hard-disk,
12CD-ROM, LS-120 and tape drives use the parallel port to connect to their
13host computer. While some devices (notably scanners) use ad-hoc methods
14to pass commands and data through the parallel port interface, most
15external devices are actually identical to an internal model, but with
16a parallel-port adapter chip added in. Some of the original parallel port
17adapters 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
19approach). Most current designs, however, take a different approach.
20The adapter chip reproduces a small ISA or IDE bus in the external device
21and the communication protocol provides operations for reading and writing
22device registers, as well as data block transfer functions. Sometimes,
23the device being addressed via the parallel cable is a standard SCSI
24controller like an NCR 5380. The "ditto" family of external tape
25drives use the ISA replicator to interface a floppy disk controller,
26which is then connected to a floppy-tape mechanism. The vast majority
27of external parallel port devices, however, are now based on standard
28IDE type devices, which require no intermediate controller. If one
29were to open up a parallel port CD-ROM drive, for instance, one would
30find a standard ATAPI CD-ROM drive, a power supply, and a single adapter
31that interconnected a standard PC parallel port cable and a standard
32IDE cable. It is usually possible to exchange the CD-ROM device with
33any other device using the IDE interface.
34
35The document describes the support in Linux for parallel port IDE
36devices. It does not cover parallel port SCSI devices, "ditto" tape
37drives or scanners. Many different devices are supported by the
38parallel 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
52as well as most of the clone and no-name products on the market.
53
54To support such a wide range of devices, PARIDE, the parallel port IDE
55subsystem, is actually structured in three parts. There is a base
56paride module which provides a registry and some common methods for
57accessing the parallel ports. The second component is a set of
58high-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
70The high-level drivers function according to the relevant standards.
71The third component of PARIDE is a set of low-level protocol drivers
72for each of the parallel port IDE adapter chips. Thanks to the interest
73and encouragement of Linux users from many parts of the world,
74support 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
942. Using the PARIDE subsystem
95=============================
96
97While configuring the Linux kernel, you may choose either to build
98the PARIDE drivers into your kernel, or to build them as modules.
99
100In either case, you will need to select "Parallel port IDE device support"
101as well as at least one of the high-level drivers and at least one
102of the parallel port communication protocols. If you do not know
103what kind of parallel port adapter is used in your drive, you could
104begin by checking the file names and any text files on your DOS
105installation floppy. Alternatively, you can look at the markings on
106the adapter chip itself. That's usually sufficient to identify the
107correct device.
108
109You can actually select all the protocol modules, and allow the PARIDE
110subsystem to try them all for you.
111
112For the "brand-name" products listed above, here are the protocol
113and 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
1322.1 Configuring built-in drivers
133---------------------------------
134
135We recommend that you get to know how the drivers work and how to
136configure them as loadable modules, before attempting to compile a
137kernel with the drivers built-in.
138
139If you built all of your PARIDE support directly into your kernel,
140and you have just a single parallel port IDE device, your kernel should
141locate it automatically for you. If you have more than one device,
142you 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
145The high-level drivers accept a number of command line parameters, all
146of which are documented in the source files in linux/drivers/block/paride.
147By default, each driver will automatically try all parallel ports it
148can find, and all protocol types that have been installed, until it finds
149a parallel port IDE adapter. Once it finds one, the probe stops. So,
150if you have more than one device, you will need to tell the drivers
151how to identify them. This requires specifying the port address, the
152protocol identification number and, for some devices, the drive's
153chain ID. While your system is booting, a number of messages are
154displayed on the console. Like all such messages, they can be
155reviewed with the 'dmesg' command. Among those messages will be
156some lines like::
157
158 paride: bpck registered as protocol 0
159 paride: epat registered as protocol 1
160
161The numbers will always be the same until you build a new kernel with
162different protocol selections. You should note these numbers as you
163will need them to identify the devices.
164
165If you happen to be using a MicroSolutions backpack device, you will
166also need to know the unit ID number for each drive. This is usually
167the last two digits of the drive's serial number (but read MicroSolutions'
168documentation about this).
169
170As an example, let's assume that you have a MicroSolutions PD/CD drive
171with unit ID number 36 connected to the parallel port at 0x378, a SyQuest
172EZ-135 connected to the chained port on the PD/CD drive and also an
173Imation Superdisk connected to port 0x278. You could give the following
174options on your boot command::
175
176 pd.drive0=0x378,1 pf.drive0=0x278,1 pf.drive1=0x378,0,36
177
178In the last option, pf.drive1 configures device /dev/pf1, the 0x378
179is the parallel port base address, the 0 is the protocol registration
180number and 36 is the chain ID.
181
182Please note: while PARIDE will work both with and without the
183PARPORT parallel port sharing system that is included by the
184"Parallel port support" option, PARPORT must be included and enabled
185if you want to use chains of devices on the same parallel port.
186
1872.2 Loading and configuring PARIDE as modules
188----------------------------------------------
189
190It is much faster and simpler to get to understand the PARIDE drivers
191if you use them as loadable kernel modules.
192
193Note 1:
194 using these drivers with the "kerneld" automatic module loading
195 system is not recommended for beginners, and is not documented here.
196
197Note 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
202To use PARIDE, you must begin by::
203
204 insmod paride
205
206this loads a base module which provides a registry for the protocols,
207among other tasks.
208
209Then, load as many of the protocol modules as you think you might need.
210As you load each module, it will register the protocols that it supports,
211and print a log message to your kernel log file and your console. For
212example::
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
220Finally, you can load high-level drivers for each kind of device that
221you have connected. By default, each driver will autoprobe for a single
222device, but you can support up to four similar devices by giving their
223individual co-ordinates when you load the driver.
224
225For example, if you had two no-name CD-ROM drives both using the
226KingByte KBIC-951A adapter, one on port 0x378 and the other on 0x3bc
227you could give the following command::
228
229 # insmod pcd drive0=0x378,1 drive1=0x3bc,1
230
231For most adapters, giving a port address and protocol number is sufficient,
232but check the source files in linux/drivers/block/paride for more
233information. (Hopefully someone will write some man pages one day !).
234
235As another example, here's what happens when PARPORT is installed, and
236a 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
249Note that the last line is the output from the generic partition table
250scanner - in this case it reports that it has found a disk with one partition.
251
2522.3 Using a PARIDE device
253--------------------------
254
255Once the drivers have been loaded, you can access PARIDE devices in the
256same way as their traditional counterparts. You will probably need to
257create the device "special files". Here is a simple script that you can
258cut 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
287With the device files and drivers in place, you can access PARIDE devices
288like any other Linux device. For example, to mount a CD-ROM in pcd0, use::
289
290 mount /dev/pcd0 /cdrom
291
292If you have a fresh Avatar Shark cartridge, and the drive is pda, you
293might 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
304Devices like the Imation superdisk work in the same way, except that
305they do not have a partition table. For example to make a 120MB
306floppy that you could share with a DOS system::
307
308 mkdosfs /dev/pf0
309 mount /dev/pf0 /mnt
310
311
3122.4 The pf driver
313------------------
314
315The pf driver is intended for use with parallel port ATAPI disk
316devices. The most common devices in this category are PD drives
317and LS-120 drives. Traditionally, media for these devices are not
318partitioned. Consequently, the pf driver does not support partitioned
319media. This may be changed in a future version of the driver.
320
3212.5 Using the pt driver
322------------------------
323
324The pt driver for parallel port ATAPI tape drives is a minimal driver.
325It does not yet support many of the standard tape ioctl operations.
326For best performance, a block size of 32KB should be used. You will
327probably want to set the parallel port delay to 0, if you can.
328
3292.6 Using the pg driver
330------------------------
331
332The pg driver can be used in conjunction with the cdrecord program
333to create CD-ROMs. Please get cdrecord version 1.6.1 or later
334from ftp://ftp.fokus.gmd.de/pub/unix/cdrecord/ . To record CD-R media
335your parallel port should ideally be set to EPP mode, and the "port delay"
336should be set to 0. With those settings it is possible to record at 2x
337speed without any buffer underruns. If you cannot get the driver to work
338in EPP mode, try to use "bidirectional" or "PS/2" mode and 1x speeds only.
339
340
3413. Troubleshooting
342==================
343
3443.1 Use EPP mode if you can
345----------------------------
346
347The most common problems that people report with the PARIDE drivers
348concern the parallel port CMOS settings. At this time, none of the
349PARIDE protocol modules support ECP mode, or any ECP combination modes.
350If you are able to do so, please set your parallel port into EPP mode
351using your CMOS setup procedure.
352
3533.2 Check the port delay
354-------------------------
355
356Some parallel ports cannot reliably transfer data at full speed. To
357offset the errors, the PARIDE protocol modules introduce a "port
358delay" between each access to the i/o ports. Each protocol sets
359a default value for this delay. In most cases, the user can override
360the default and set it to 0 - resulting in somewhat higher transfer
361rates. In some rare cases (especially with older 486 systems) the
362default delays are not long enough. if you experience corrupt data
363transfers, or unexpected failures, you may wish to increase the
364port delay. The delay can be programmed using the "driveN" parameters
365to each of the high-level drivers. Please see the notes above, or
366read the comments at the beginning of the driver source files in
367linux/drivers/block/paride.
368
3693.3 Some drives need a printer reset
370-------------------------------------
371
372There appear to be a number of "noname" external drives on the market
373that do not always power up correctly. We have noticed this with some
374drives based on OnSpec and older Freecom adapters. In these rare cases,
375the adapter can often be reinitialised by issuing a "printer reset" on
376the parallel port. As the reset operation is potentially disruptive in
377multiple device environments, the PARIDE drivers will not do it
378automatically. You can however, force a printer reset by doing::
379
380 insmod lp reset=1
381 rmmod lp
382
383If you have one of these marginal cases, you should probably build
384your paride drivers as modules, and arrange to do the printer reset
385before loading the PARIDE drivers.
386
3873.4 Use the verbose option and dmesg if you need help
388------------------------------------------------------
389
390While a lot of testing has gone into these drivers to make them work
391as smoothly as possible, problems will arise. If you do have problems,
392please check all the obvious things first: does the drive work in
393DOS with the manufacturer's drivers ? If that doesn't yield any useful
394clues, then please make sure that only one drive is hooked to your system,
395and that either (a) PARPORT is enabled or (b) no other device driver
396is using your parallel port (check in /proc/ioports). Then, load the
397appropriate drivers (you can load several protocol modules if you want)
398as 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).
408The verbose=1 parameter will cause the drivers to log a trace of their
409activity as they attempt to locate your drive.
410
411Use 'dmesg' to capture a log of all the PARIDE messages (any messages
412beginning with paride:, a protocol module's name or a driver's name) and
413include that with your bug report. You can submit a bug report in one
414of two ways. Either send it directly to the author of the PARIDE suite,
415by e-mail to grant@torque.net, or join the linux-parport mailing list
416and post your report there.
417
4183.5 For more information or help
419---------------------------------
420
421You can join the linux-parport mailing list by sending a mail message
422to:
423
424 linux-parport-request@torque.net
425
426with the single word::
427
428 subscribe
429
430in the body of the mail message (not in the subject line). Please be
431sure that your mail program is correctly set up when you do this, as
432the list manager is a robot that will subscribe you using the reply
433address in your mail headers. REMOVE any anti-spam gimmicks you may
434have in your mail headers, when sending mail to the list server.
435
436You might also find some useful information on the linux-parport
437web 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==========================================
2Using 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
131) Overview
14-----------
15
16The RAM disk driver is a way to use main system memory as a block device. It
17is required for initrd, an initial filesystem used if you need to load modules
18in order to access the root filesystem (see Documentation/admin-guide/initrd.rst). It can
19also be used for a temporary filesystem for crypto work, since the contents
20are erased on reboot.
21
22The RAM disk dynamically grows as more space is required. It does this by using
23RAM from the buffer cache. The driver marks the buffers it is using as dirty
24so that the VM subsystem does not try to reclaim them later.
25
26The RAM disk supports up to 16 RAM disks by default, and can be reconfigured
27to support an unlimited number of RAM disks (at your own risk). Just change
28the configuration symbol BLK_DEV_RAM_COUNT in the Block drivers config menu
29and (re)build the kernel.
30
31To use RAM disk support with your system, run './MAKEDEV ram' from the /dev
32directory. RAM disks are all major number 1, and start with minor number 0
33for /dev/ram0, etc. If used, modern kernels use /dev/ram0 for an initrd.
34
35The new RAM disk also has the ability to load compressed RAM disk images,
36allowing one to squeeze more programs onto an average installation or
37rescue floppy disk.
38
39
402) Parameters
41---------------------------------
42
432a) Kernel Command Line Parameters
44
45 ramdisk_size=N
46 Size of the ramdisk.
47
48This parameter tells the RAM disk driver to set up RAM disks of N k size. The
49default is 4096 (4 MB).
50
512b) 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
623) Using "rdev -r"
63------------------
64
65The usage of the word (two bytes) that "rdev -r" sets in the kernel image is
66as follows. The low 11 bits (0 -> 10) specify an offset (in 1 k blocks) of up
67to 2 MB (2^11) of where to find the RAM disk (this used to be the size). Bit
6814 indicates that a RAM disk is to be loaded, and bit 15 indicates whether a
69prompt/wait sequence is to be given before trying to read the RAM disk. Since
70the RAM disk dynamically grows as data is being written into it, a size field
71is not required. Bits 11 to 13 are not currently used and may as well be zero.
72These 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
78Consider a typical two floppy disk setup, where you will have the
79kernel on disk one, and have already put a RAM disk image onto disk #2.
80
81Hence you want to set bits 0 to 13 as 0, meaning that your RAM disk
82starts at an offset of 0 kB from the beginning of the floppy.
83The command line equivalent is: "ramdisk_start=0"
84
85You want bit 14 as one, indicating that a RAM disk is to be loaded.
86The command line equivalent is: "load_ramdisk=1"
87
88You want bit 15 as one, indicating that you want a prompt/keypress
89sequence so that you have a chance to switch floppy disks.
90The command line equivalent is: "prompt_ramdisk=1"
91
92Putting that together gives 2^15 + 2^14 + 0 = 49152 for an rdev word.
93So 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
99If 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
103Since the default start = 0 and the default prompt = 1, you could use::
104
105 append = "load_ramdisk=1"
106
107
1084) An Example of Creating a Compressed RAM Disk
109-----------------------------------------------
110
111To create a RAM disk image, you will need a spare block device to
112construct it on. This can be the RAM disk device itself, or an
113unused disk partition (such as an unmounted swap partition). For this
114example, we will use the RAM disk device, "/dev/ram0".
115
116Note: This technique should not be done on a machine with less than 8 MB
117of RAM. If using a spare disk partition instead of /dev/ram0, then this
118restriction does not apply.
119
120a) 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
128b) Make a filesystem on it. Say ext2fs for this example::
129
130 mke2fs -vm0 /dev/ram0 2048
131
132c) Mount it, copy the files you want to it (eg: /etc/* /dev/* ...)
133 and unmount it again.
134
135d) 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
141e) Put the kernel onto the floppy::
142
143 dd if=zImage of=/dev/fd0 bs=1k
144
145f) 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
154g) 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
161That is it. You now have your boot/root compressed RAM disk floppy. Some
162users may wish to combine steps (d) and (f) by using a pipe.
163
164
165 Paul Gortmaker 12/95
166
167Changelog:
168----------
169
17010-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
17612-95 :
177 Original Document
Documentation/admin-guide/blockdev/zram.rst+422−0
@@ -0,0 +1,422 @@
1========================================
2zram: Compressed RAM based block devices
3========================================
4
5Introduction
6============
7
8The zram module creates RAM based block devices named /dev/zram<id>
9(<id> = 0, 1, ...). Pages written to these disks are compressed and stored
10in memory itself. These disks allow very fast I/O and compression provides
11good amounts of memory savings. Some of the usecases include /tmp storage,
12use as swap disks, various caches under /var and maybe many more :)
13
14Statistics for individual zram devices are exported through sysfs nodes at
15/sys/block/zram<id>/
16
17Usage
18=====
19
20There are several ways to configure and manage zram device(-s):
21
22a) using zram and zram_control sysfs attributes
23b) using zramctl utility, provided by util-linux (util-linux@vger.kernel.org).
24
25In this document we will describe only 'manual' zram configuration steps,
26IOW, zram and zram_control sysfs attributes.
27
28In order to get a better idea about zramctl please consult util-linux
29documentation, zramctl man-page or `zramctl --help`. Please be informed
30that zram maintainers do not develop/maintain util-linux or zramctl, should
31you have any questions please contact util-linux@vger.kernel.org
32
33Following shows a typical sequence of steps for using zram.
34
35WARNING
36=======
37
38For the sake of simplicity we skip error checking parts in most of the
39examples below. However, it is your sole responsibility to handle errors.
40
41zram sysfs attributes always return negative values in case of errors.
42The 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
52If you use 'echo', the returned value that is changed by 'echo' utility,
53and, 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
60should suffice.
61
621) Load Module
63==============
64
65::
66
67 modprobe zram num_devices=4
68 This creates 4 devices: /dev/zram{0,1,2,3}
69
70num_devices parameter is optional and tells zram how many devices should be
71pre-created. Default: 1.
72
732) Set max number of compression streams
74========================================
75
76Regardless the value passed to this attribute, ZRAM will always
77allocate multiple compression streams - one per online CPUs - thus
78allowing several concurrent compression operations. The number of
79allocated compression streams goes down when some of the CPUs
80become offline. There is no single-compression-stream mode anymore,
81unless you are running a UP system or has only 1 CPU online.
82
83To find out how many streams are currently available::
84
85 cat /sys/block/zram0/max_comp_streams
86
873) Select compression algorithm
88===============================
89
90Using comp_algorithm device attribute one can see available and
91currently selected (shown in square brackets) compression algorithms,
92change selected compression algorithm (once the device is initialised
93there is no way to change compression algorithm).
94
95Examples::
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
104For the time being, the `comp_algorithm` content does not necessarily
105show every compression algorithm supported by the kernel. We keep this
106list primarily to simplify device configuration and one can configure
107a new device with a compression algorithm that is not listed in
108`comp_algorithm`. The thing is that, internally, ZRAM uses Crypto API
109and, if some of the algorithms were built as modules, it's impossible
110to list all of them using, for instance, /proc/crypto or any other
111method. This, however, has an advantage of permitting the usage of
112custom crypto compression modules (implementing S/W or H/W compression).
113
1144) Set Disksize
115===============
116
117Set disk size by writing the value to sysfs node 'disksize'.
118The value can be either in bytes or you can use mem suffixes.
119Examples::
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
129Note:
130There is little point creating a zram of greater than twice the size of memory
131since we expect a 2:1 compression ratio. Note that zram uses about 0.1% of the
132size of the disk when not in use so a huge zram is wasteful.
133
1345) Set memory limit: Optional
135=============================
136
137Set memory limit by writing the value to sysfs node 'mem_limit'.
138The value can be either in bytes or you can use mem suffixes.
139In addition, you could change the value in runtime.
140Examples::
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
1536) 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
1647) Add/remove zram devices
165==========================
166
167zram provides a control interface, which enables dynamic (on-demand) device
168addition and removal.
169
170In order to add a new /dev/zramX device, perform read operation on hot_add
171attribute. This will return either new device's device id (meaning that you
172can use /dev/zram<id>) or error code.
173
174Example::
175
176 cat /sys/class/zram-control/hot_add
177 1
178
179To remove the existing /dev/zramX device (where X is a device id)
180execute::
181
182 echo X > /sys/class/zram-control/hot_remove
183
1848) Stats
185========
186
187Per-device statistics are exported as various nodes under /sys/block/zram<id>/
188
189A brief description of exported device attributes. For more details please
190read Documentation/ABI/testing/sysfs-block-zram.
191
192====================== ====== ===============================================
193Name access description
194====================== ====== ===============================================
195disksize RW show and set the device's disk size
196initstate RO shows the initialization state of the device
197reset WO trigger device reset
198mem_used_max WO reset the `mem_used_max` counter (see later)
199mem_limit WO specifies the maximum amount of memory ZRAM can
200 use to store the compressed data
201writeback_limit WO specifies the maximum amount of write IO zram
202 can write out to backing device as 4KB unit
203writeback_limit_enable RW show and set writeback_limit feature
204max_comp_streams RW the number of possible concurrent compress
205 operations
206comp_algorithm RW show and change the compression algorithm
207compact WO trigger memory compaction
208debug_stat RO this file is used for zram debugging purposes
209backing_dev RW set up backend storage for zram to write out
210idle WO mark allocated slot as idle
211====================== ====== ===============================================
212
213
214User space is advised to use the following files to read the device statistics.
215
216File /sys/block/zram<id>/stat
217
218Represents block layer statistics. Read Documentation/block/stat.rst for
219details.
220
221File /sys/block/zram<id>/io_stat
222
223The stat file represents device's I/O statistics not accounted by block
224layer and, thus, not available in zram<id>/stat file. It consists of a
225single line of text and contains the following stats separated by
226whitespace:
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
246File /sys/block/zram<id>/mm_stat
247
248The stat file represents device's mm statistics. It consists of a single
249line 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
272File /sys/block/zram<id>/bd_stat
273
274The stat file represents device's backing device statistics. It consists of
275a 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
2869) Deactivate
287=============
288
289::
290
291 swapoff /dev/zram0
292 umount /dev/zram1
293
29410) 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
306Optional Feature
307================
308
309writeback
310---------
311
312With CONFIG_ZRAM_WRITEBACK, zram can write idle/incompressible page
313to backing storage rather than keeping it in memory.
314To use the feature, admin should set up backing device via::
315
316 echo /dev/sda5 > /sys/block/zramX/backing_dev
317
318before disksize setting. It supports only partition at this moment.
319If admin want to use incompressible page writeback, they could do via::
320
321 echo huge > /sys/block/zramX/write
322
323To use idle page writeback, first, user need to declare zram pages
324as idle::
325
326 echo all > /sys/block/zramX/idle
327
328From now on, any pages on zram are idle pages. The idle mark
329will be removed until someone request access of the block.
330IOW, unless there is access request, those pages are still idle pages.
331
332Admin can request writeback of those idle pages at right timing via::
333
334 echo idle > /sys/block/zramX/writeback
335
336With the command, zram writeback idle pages from memory to the storage.
337
338If there are lots of write IO with flash device, potentially, it has
339flash wearout problem so that admin needs to design write limitation
340to guarantee storage health for entire product life.
341
342To overcome the concern, zram supports "writeback_limit" feature.
343The "writeback_limit_enable"'s default value is 0 so that it doesn't limit
344any writeback. IOW, if admin want to apply writeback budget, he should
345enable writeback_limit_enable via::
346
347 $ echo 1 > /sys/block/zramX/writeback_limit_enable
348
349Once writeback_limit_enable is set, zram doesn't allow any writeback
350until admin set the budget via /sys/block/zramX/writeback_limit.
351
352(If admin doesn't enable writeback_limit_enable, writeback_limit's value
353assigned via /sys/block/zramX/writeback_limit is meaninless.)
354
355If admin want to limit writeback as per-day 400M, he could do it
356like 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
364If admin want to allow further write again once the bugdet is exausted,
365he could do it like below::
366
367 $ echo $((400<<MB_SHIFT>>4K_SHIFT)) > \
368 /sys/block/zram0/writeback_limit
369
370If admin want to see remaining writeback budget since he set::
371
372 $ cat /sys/block/zramX/writeback_limit
373
374If admin want to disable writeback limit, he could do::
375
376 $ echo 0 > /sys/block/zramX/writeback_limit_enable
377
378The writeback_limit count will reset whenever you reset zram(e.g.,
379system reboot, echo 1 > /sys/block/zramX/reset) so keeping how many of
380writeback happened until you reset the zram to allocate extra writeback
381budget in next setting is user's job.
382
383If admin want to measure writeback count in a certain period, he could
384know it via /sys/block/zram0/bd_stat's 3rd column.
385
386memory tracking
387===============
388
389With CONFIG_ZRAM_MEMORY_TRACKING, user can know information of the
390zram block. It could be useful to catch cold or incompressible
391pages of the process with*pagemap.
392
393If 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
400First column
401 zram's block index.
402Second column
403 access time since the system was booted
404Third 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
416First line of above example says 300th block is accessed at 75.033841sec
417and the block's state is huge so it is written back to the backing
418storage. It's a debugging feature so anyone shouldn't rely on it to work
419properly.
420
421Nitin Gupta
422ngupta@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
90 run a null modem to a second machine and capture the output there90 run a null modem to a second machine and capture the output there
91 using your favourite communication program. Minicom works well.91 using your favourite communication program. Minicom works well.
92 92
93(3) Use Kdump (see Documentation/kdump/kdump.txt),93(3) Use Kdump (see Documentation/admin-guide/kdump/kdump.rst),
94 extract the kernel ring buffer from old memory with using dmesg94 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.
96 96
97Finding the bug's location97Finding the bug's location
98--------------------------98--------------------------
Documentation/admin-guide/cgroup-v1/blkio-controller.rst+302−0
@@ -0,0 +1,302 @@
1===================
2Block IO Controller
3===================
4
5Overview
6========
7cgroup subsys "blkio" implements the block io controller. There seems to be
8a need of various kinds of IO control policies (like proportional BW, max BW)
9both at leaf nodes as well as at intermediate nodes in a storage hierarchy.
10Plan is to use the same cgroup based management interface for blkio controller
11and based on user options switch IO policies in the background.
12
13One IO control policy is throttling policy which can be used to
14specify upper IO rate limits on devices. This policy is implemented in
15generic block layer and can be used on leaf nodes as well as higher
16level logical devices like device mapper.
17
18HOWTO
19=====
20Throttling/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
51Hierarchical Cgroups
52====================
53
54Throttling implements hierarchy support; however,
55throttling's hierarchy support is enabled iff "sane_behavior" is
56enabled from cgroup side, which currently is a development option and
57not publicly available.
58
59If somebody created a hierarchy like as follows::
60
61 root
62 / \
63 test1 test2
64 |
65 test3
66
67Throttling with "sane_behavior" will handle the
68hierarchy correctly. For throttling, all limits apply
69to the whole subtree while all statistics are local to the IOs
70directly generated by tasks in that cgroup.
71
72Throttling without "sane_behavior" enabled from cgroup side will
73practically treat all groups at same level as if it looks like the
74following::
75
76 pivot
77 / / \ \
78 root test1 test2 test3
79
80Various user visible config options
81===================================
82CONFIG_BLK_CGROUP
83 - Block IO controller.
84
85CONFIG_BFQ_CGROUP_DEBUG
86 - Debug help. Right now some additional stats file show up in cgroup
87 if this option is enabled.
88
89CONFIG_BLK_DEV_THROTTLING
90 - Enable block device throttling support in block layer.
91
92Details of cgroup files
93=======================
94Proportional 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
251Throttling/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
281Note: 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
298Common 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==============
2Control Groups
3==============
4
5Written by Paul Menage <menage@google.com> based on
6Documentation/admin-guide/cgroup-v1/cpusets.rst
7
8Original copyright statements from cpusets.txt:
9
10Portions Copyright (C) 2004 BULL SA.
11
12Portions Copyright (c) 2004-2006 Silicon Graphics, Inc.
13
14Modified by Paul Jackson <pj@sgi.com>
15
16Modified 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
381. Control Groups
39=================
40
411.1 What are cgroups ?
42----------------------
43
44Control Groups provide a mechanism for aggregating/partitioning sets of
45tasks, and all their future children, into hierarchical groups with
46specialized behaviour.
47
48Definitions:
49
50A *cgroup* associates a set of tasks with a set of parameters for one
51or more subsystems.
52
53A *subsystem* is a module that makes use of the task grouping
54facilities provided by cgroups to treat groups of tasks in
55particular ways. A subsystem is typically a "resource controller" that
56schedules a resource or applies per-cgroup limits, but it may be
57anything that wants to act on a group of processes, e.g. a
58virtualization subsystem.
59
60A *hierarchy* is a set of cgroups arranged in a tree, such that
61every task in the system is in exactly one of the cgroups in the
62hierarchy, and a set of subsystems; each subsystem has system-specific
63state attached to each cgroup in the hierarchy. Each hierarchy has
64an instance of the cgroup virtual filesystem associated with it.
65
66At any one time there may be multiple active hierarchies of task
67cgroups. Each hierarchy is a partition of all tasks in the system.
68
69User-level code may create and destroy cgroups by name in an
70instance of the cgroup virtual file system, specify and query to
71which cgroup a task is assigned, and list the task PIDs assigned to
72a cgroup. Those creations and assignments only affect the hierarchy
73associated with that instance of the cgroup file system.
74
75On their own, the only use for cgroups is for simple job
76tracking. The intention is that other subsystems hook into the generic
77cgroup support to provide new attributes for cgroups, such as
78accounting/limiting the resources which processes in a cgroup can
79access. For example, cpusets (see Documentation/admin-guide/cgroup-v1/cpusets.rst) allow
80you to associate a set of CPUs and a set of memory nodes with the
81tasks in each cgroup.
82
831.2 Why are cgroups needed ?
84----------------------------
85
86There are multiple efforts to provide process aggregations in the
87Linux kernel, mainly for resource-tracking purposes. Such efforts
88include cpusets, CKRM/ResGroups, UserBeanCounters, and virtual server
89namespaces. These all require the basic notion of a
90grouping/partitioning of processes, with newly forked processes ending
91up in the same group (cgroup) as their parent process.
92
93The kernel cgroup patch provides the minimum essential kernel
94mechanisms required to efficiently implement such groups. It has
95minimal impact on the system fast paths, and provides hooks for
96specific subsystems such as cpusets to provide additional behaviour as
97desired.
98
99Multiple hierarchy support is provided to allow for situations where
100the division of tasks into cgroups is distinctly different for
101different subsystems - having parallel hierarchies allows each
102hierarchy to be a natural division of tasks, without having to handle
103complex combinations of tasks that would be present if several
104unrelated subsystems needed to be forced into the same tree of
105cgroups.
106
107At one extreme, each resource controller or subsystem could be in a
108separate hierarchy; at the other extreme, all subsystems
109would be attached to the same hierarchy.
110
111As an example of a scenario (originally proposed by vatsa@in.ibm.com)
112that can benefit from multiple hierarchies, consider a large
113university server with various users - students, professors, system
114tasks etc. The resource planning for this server could be along the
115following 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
134Browsers like Firefox/Lynx go into the WWW network class, while (k)nfsd goes
135into the NFS network class.
136
137At the same time Firefox/Lynx will share an appropriate CPU/Memory class
138depending on who launched it (prof/student).
139
140With the ability to classify tasks differently for different resources
141(by putting those resource subsystems in different hierarchies),
142the admin can easily set up a script which receives exec notifications
143and depending on who is launching the browser he can::
144
145 # echo browser_pid > /sys/fs/cgroup/<restype>/<userclass>/tasks
146
147With only a single hierarchy, he now would potentially have to create
148a separate cgroup for every browser launched and associate it with
149appropriate network and other resource class. This may lead to
150proliferation of such cgroups.
151
152Also let's say that the administrator would like to give enhanced network
153access temporarily to a student's browser (since it is night and the user
154wants to do online gaming :)) OR give one of the student's simulation
155apps enhanced CPU power.
156
157With ability to write PIDs directly to resource classes, it's just a
158matter 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
164Without this ability, the administrator would have to split the cgroup into
165multiple separate ones and then associate the new cgroups with the
166new resource classes.
167
168
169
1701.3 How are cgroups implemented ?
171---------------------------------
172
173Control 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
196The implementation of cgroups requires a few, simple hooks
197into 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
204In addition, a new file system of type "cgroup" may be mounted, to
205enable browsing and modifying the cgroups presently known to the
206kernel. When mounting a cgroup hierarchy, you may specify a
207comma-separated list of subsystems to mount as the filesystem mount
208options. By default, mounting the cgroup filesystem attempts to
209mount a hierarchy containing all registered subsystems.
210
211If an active hierarchy with exactly the same set of subsystems already
212exists, it will be reused for the new mount. If no existing hierarchy
213matches, and any of the requested subsystems are in use in an existing
214hierarchy, the mount will fail with -EBUSY. Otherwise, a new hierarchy
215is activated, associated with the requested subsystems.
216
217It's not currently possible to bind a new subsystem to an active
218cgroup hierarchy, or to unbind a subsystem from an active cgroup
219hierarchy. This may be possible in future, but is fraught with nasty
220error-recovery issues.
221
222When a cgroup filesystem is unmounted, if there are any
223child cgroups created below the top-level cgroup, that hierarchy
224will remain active even though unmounted; if there are no
225child cgroups then the hierarchy will be deactivated.
226
227No new system calls are added for cgroups - all support for
228querying and modifying cgroups is via this cgroup file system.
229
230Each task under /proc has an added file named 'cgroup' displaying,
231for each active hierarchy, the subsystem names and the cgroup name
232as the path relative to the root of the cgroup file system.
233
234Each cgroup is represented by a directory in the cgroup file system
235containing 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
249Other subsystems such as cpusets may add additional files in each
250cgroup dir.
251
252New cgroups are created using the mkdir system call or shell
253command. The properties of a cgroup, such as its flags, are
254modified by writing to the appropriate file in that cgroups
255directory, as listed above.
256
257The named hierarchical structure of nested cgroups allows partitioning
258a large system into nested, dynamically changeable, "soft-partitions".
259
260The attachment of each task, automatically inherited at fork by any
261children of that task, to a cgroup allows organizing the work load
262on a system into related sets of tasks. A task may be re-attached to
263any other cgroup, if allowed by the permissions on the necessary
264cgroup file system directories.
265
266When a task is moved from one cgroup to another, it gets a new
267css_set pointer - if there's an already existing css_set with the
268desired collection of cgroups then that group is reused, otherwise a new
269css_set is allocated. The appropriate existing css_set is located by
270looking into a hash table.
271
272To allow access from a cgroup to the css_sets (and hence tasks)
273that comprise it, a set of cg_cgroup_link objects form a lattice;
274each cg_cgroup_link is linked into a list of cg_cgroup_links for
275a single cgroup on its cgrp_link_list field, and a list of
276cg_cgroup_links for a single css_set on its cg_link_list.
277
278Thus the set of tasks in a cgroup can be listed by iterating over
279each css_set that references the cgroup, and sub-iterating over
280each css_set's task set.
281
282The use of a Linux virtual file system (vfs) to represent the
283cgroup hierarchy provides for a familiar permission and name space
284for cgroups, with a minimum of additional kernel code.
285
2861.4 What does notify_on_release do ?
287------------------------------------
288
289If the notify_on_release flag is enabled (1) in a cgroup, then
290whenever the last task in the cgroup leaves (exits or attaches to
291some other cgroup) and the last child cgroup of that cgroup
292is removed, then the kernel runs the command specified by the contents
293of the "release_agent" file in that hierarchy's root directory,
294supplying the pathname (relative to the mount point of the cgroup
295file system) of the abandoned cgroup. This enables automatic
296removal of abandoned cgroups. The default value of
297notify_on_release in the root cgroup at system boot is disabled
298(0). The default value of other cgroups at creation is the current
299value of their parents' notify_on_release settings. The default value of
300a cgroup hierarchy's release_agent path is empty.
301
3021.5 What does clone_children do ?
303---------------------------------
304
305This flag only affects the cpuset controller. If the clone_children
306flag is enabled (1) in a cgroup, a new cpuset cgroup will copy its
307configuration from the parent during initialization.
308
3091.6 How do I use cgroups ?
310--------------------------
311
312To start a new job that is to be contained within a cgroup, using
313the "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
325For example, the following sequence of commands will setup a cgroup
326named "Charlie", containing just CPUs 2 and 3, and Memory Node 1,
327and 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
3432. Usage Examples and Syntax
344============================
345
3462.1 Basic Usage
347---------------
348
349Creating, modifying, using cgroups can be done through the cgroup
350virtual filesystem.
351
352To mount a cgroup hierarchy with all available subsystems, type::
353
354 # mount -t cgroup xxx /sys/fs/cgroup
355
356The "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
359Note: Some subsystems do not work without some user input first. For instance,
360if cpusets are enabled the user will have to populate the cpus and mems files
361for each new cgroup created before that group can be used.
362
363As explained in section `1.2 Why are cgroups needed?` you should create
364different hierarchies of cgroups for each single resource or group of
365resources you want to control. Therefore, you should mount a tmpfs on
366/sys/fs/cgroup and create directories for each cgroup resource or resource
367group::
368
369 # mount -t tmpfs cgroup_root /sys/fs/cgroup
370 # mkdir /sys/fs/cgroup/rg1
371
372To mount a cgroup hierarchy with just the cpuset and memory
373subsystems, type::
374
375 # mount -t cgroup -o cpuset,memory hier1 /sys/fs/cgroup/rg1
376
377While remounting cgroups is currently supported, it is not recommend
378to use it. Remounting allows changing bound subsystems and
379release_agent. Rebinding is hardly useful as it only works when the
380hierarchy is empty and release_agent itself should be replaced with
381conventional fsnotify. The support for remounting will be removed in
382the future.
383
384To 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
389Note that specifying 'release_agent' more than once will return failure.
390
391Note that changing the set of subsystems is currently only supported
392when the hierarchy consists of a single (root) cgroup. Supporting
393the ability to arbitrarily bind/unbind subsystems from an existing
394cgroup hierarchy is intended to be implemented in the future.
395
396Then under /sys/fs/cgroup/rg1 you can find a tree that corresponds to the
397tree of the cgroups in the system. For instance, /sys/fs/cgroup/rg1
398is the cgroup that holds the whole system.
399
400If you want to change the value of release_agent::
401
402 # echo "/sbin/new_release_agent" > /sys/fs/cgroup/rg1/release_agent
403
404It can also be changed via remount.
405
406If you want to create a new cgroup under /sys/fs/cgroup/rg1::
407
408 # cd /sys/fs/cgroup/rg1
409 # mkdir my_cgroup
410
411Now you want to do something with this cgroup:
412
413 # cd my_cgroup
414
415In 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
421Now attach your shell to this cgroup::
422
423 # /bin/echo $$ > tasks
424
425You can also create cgroups inside your cgroup by using mkdir in this
426directory::
427
428 # mkdir my_sub_cs
429
430To remove a cgroup, just use rmdir::
431
432 # rmdir my_sub_cs
433
434This will fail if the cgroup is in use (has cgroups inside, or
435has processes attached, or is held alive by other subsystem-specific
436reference).
437
4382.2 Attaching processes
439-----------------------
440
441::
442
443 # /bin/echo PID > tasks
444
445Note that it is PID, not PIDs. You can only attach ONE task at a time.
446If 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
453You can attach the current shell task by echoing 0::
454
455 # echo 0 > tasks
456
457You can use the cgroup.procs file instead of the tasks file to move all
458threads in a threadgroup at once. Echoing the PID of any task in a
459threadgroup to cgroup.procs causes all tasks in that threadgroup to be
460attached to the cgroup. Writing 0 to cgroup.procs moves all tasks
461in the writing task's threadgroup.
462
463Note: Since every task is always a member of exactly one cgroup in each
464mounted hierarchy, to remove a task from its current cgroup you must
465move it into a new cgroup (possibly the root cgroup) by writing to the
466new cgroup's tasks file.
467
468Note: Due to some restrictions enforced by some cgroup subsystems, moving
469a process to another cgroup can fail.
470
4712.3 Mounting hierarchies by name
472--------------------------------
473
474Passing the name=<x> option when mounting a cgroups hierarchy
475associates the given name with the hierarchy. This can be used when
476mounting a pre-existing hierarchy, in order to refer to it by name
477rather than by its set of active subsystems. Each hierarchy is either
478nameless, or has a unique name.
479
480The name should match [\w.-]+
481
482When passing a name=<x> option for a new hierarchy, you need to
483specify subsystems manually; the legacy behaviour of mounting all
484subsystems when none are explicitly specified is not supported when
485you give a subsystem a name.
486
487The name of the subsystem appears as part of the hierarchy description
488in /proc/mounts and /proc/<pid>/cgroups.
489
490
4913. Kernel API
492=============
493
4943.1 Overview
495------------
496
497Each kernel subsystem that wants to hook into the generic cgroup
498system needs to create a cgroup_subsys object. This contains
499various methods, which are callbacks from the cgroup system, along
500with a subsystem ID which will be assigned by the cgroup system.
501
502Other 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
513Each cgroup object created by the system has an array of pointers,
514indexed by subsystem ID; this pointer is entirely managed by the
515subsystem; the generic cgroup code will never touch this pointer.
516
5173.2 Synchronization
518-------------------
519
520There is a global mutex, cgroup_mutex, used by the cgroup
521system. This should be taken by anything that wants to modify a
522cgroup. It may also be taken to prevent cgroups from being
523modified, but more specific locks may be more appropriate in that
524situation.
525
526See kernel/cgroup.c for more details.
527
528Subsystems can take/release the cgroup_mutex via the functions
529cgroup_lock()/cgroup_unlock().
530
531Accessing 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
5363.3 Subsystem API
537-----------------
538
539Each subsystem should:
540
541- add an entry in linux/cgroup_subsys.h
542- define a cgroup_subsys object called <name>_cgrp_subsys
543
544Each subsystem may export the following methods. The only mandatory
545methods are css_alloc/free. Any others that are null are presumed to
546be successful no-ops.
547
548``struct cgroup_subsys_state *css_alloc(struct cgroup *cgrp)``
549(cgroup_mutex held by caller)
550
551Called to allocate a subsystem state object for a cgroup. The
552subsystem should allocate its subsystem state object for the passed
553cgroup, returning a pointer to the new object on success or a
554ERR_PTR() value. On success, the subsystem pointer should point to
555a structure of type cgroup_subsys_state (typically embedded in a
556larger subsystem-specific object), which will be initialized by the
557cgroup system. Note that this will be called at initialization to
558create the root subsystem state for this subsystem; this case can be
559identified by the passed cgroup object having a NULL parent (since
560it's the root of the hierarchy) and may be an appropriate place for
561initialization code.
562
563``int css_online(struct cgroup *cgrp)``
564(cgroup_mutex held by caller)
565
566Called after @cgrp successfully completed all allocations and made
567visible to cgroup_for_each_child/descendant_*() iterators. The
568subsystem may choose to fail creation by returning -errno. This
569callback can be used to implement reliable state sharing and
570propagation along the hierarchy. See the comment on
571cgroup_for_each_descendant_pre() for details.
572
573``void css_offline(struct cgroup *cgrp);``
574(cgroup_mutex held by caller)
575
576This is the counterpart of css_online() and called iff css_online()
577has succeeded on @cgrp. This signifies the beginning of the end of
578@cgrp. @cgrp is being removed and the subsystem should start dropping
579all references it's holding on @cgrp. When all references are dropped,
580cgroup removal will proceed to the next step - css_free(). After this
581callback, @cgrp should be considered dead to the subsystem.
582
583``void css_free(struct cgroup *cgrp)``
584(cgroup_mutex held by caller)
585
586The cgroup system is about to free @cgrp; the subsystem should free
587its subsystem state object. By the time this method is called, @cgrp
588is completely unused; @cgrp->parent is still valid. (Note - can also
589be called for a newly-created cgroup if an error occurs after this
590subsystem'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
595Called prior to moving one or more tasks into a cgroup; if the
596subsystem returns an error, this will abort the attach operation.
597@tset contains the tasks to be attached and is guaranteed to have at
598least one task in it.
599
600If 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
606Each @tset entry also contains the task's old cgroup and tasks which
607aren't switching cgroup can be skipped easily using the
608cgroup_taskset_for_each() iterator. Note that this isn't called on a
609fork. If this method returns 0 (success) then this should remain valid
610while the caller holds cgroup_mutex and it is ensured that either
611attach() 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
616An optional operation which should restore @css's configuration to the
617initial state. This is currently only used on the unified hierarchy
618when a subsystem is disabled on a cgroup through
619"cgroup.subtree_control" but should remain enabled because other
620subsystems depend on it. cgroup core makes such a css invisible by
621removing the associated interface files and invokes this callback so
622that the hidden subsystem can return to the initial neutral state.
623This prevents unexpected resource control from a hidden css and
624ensures that the configuration is in the initial state when it is made
625visible again later.
626
627``void cancel_attach(struct cgroup *cgrp, struct cgroup_taskset *tset)``
628(cgroup_mutex held by caller)
629
630Called when a task attach operation has failed after can_attach() has succeeded.
631A subsystem whose can_attach() has some side-effects should provide this
632function, so that the subsystem can implement a rollback. If not, not necessary.
633This will be called only about subsystems whose can_attach() operation have
634succeeded. 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
639Called after the task has been attached to the cgroup, to allow any
640post-attachment activity that requires memory allocations or blocking.
641The parameters are identical to can_attach().
642
643``void fork(struct task_struct *task)``
644
645Called when a task is forked into a cgroup.
646
647``void exit(struct task_struct *task)``
648
649Called during task exit.
650
651``void free(struct task_struct *task)``
652
653Called when the task_struct is freed.
654
655``void bind(struct cgroup *root)``
656(cgroup_mutex held by caller)
657
658Called when a cgroup subsystem is rebound to a different hierarchy
659and root cgroup. Currently this will only involve movement between
660the default hierarchy (which never has sub-cgroups) and a hierarchy
661that is being created/destroyed (and hence has no sub-cgroups).
662
6634. Extended attribute usage
664===========================
665
666cgroup filesystem supports certain types of extended attributes in its
667directories and files. The current supported types are:
668
669 - Trusted (XATTR_TRUSTED)
670 - Security (XATTR_SECURITY)
671
672Both require CAP_SYS_ADMIN capability to set.
673
674Like in tmpfs, the extended attributes in cgroup filesystem are stored
675using kernel memory and it's advised to keep the usage at minimum. This
676is the reason why user defined extended attributes are not supported, since
677any user can do it and there's no limit in the value size.
678
679The current known users for this feature are SELinux to limit cgroup usage
680in containers and systemd for assorted meta data like main PID in a cgroup
681(systemd creates a cgroup per service).
682
6835. 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=========================
2CPU Accounting Controller
3=========================
4
5The CPU accounting controller is used to group tasks using cgroups and
6account the CPU usage of these groups of tasks.
7
8The CPU accounting controller supports multi-hierarchy groups. An accounting
9group accumulates the CPU usage of all of its child groups and the tasks
10directly present in its group.
11
12Accounting groups can be created by first mounting the cgroup filesystem::
13
14 # mount -t cgroup -ocpuacct none /sys/fs/cgroup
15
16With the above step, the initial or the parent accounting group becomes
17visible at /sys/fs/cgroup. At bootup, this group includes all the tasks in
18the system. /sys/fs/cgroup/tasks lists the tasks in this cgroup.
19/sys/fs/cgroup/cpuacct.usage gives the CPU time (in nanoseconds) obtained
20by this group which is essentially the CPU time obtained by all the tasks
21in the system.
22
23New 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
29The above steps create a new group g1 and move the current shell
30process (bash) into it. CPU time consumed by this bash and its children
31can be obtained from g1/cpuacct.usage and the same is accumulated in
32/sys/fs/cgroup/cpuacct.usage also.
33
34cpuacct.stat file lists a few statistics which further divide the
35CPU time obtained by the cgroup into user and system times. Currently
36the following statistics are supported:
37
38user: Time spent by tasks of the cgroup in user mode.
39system: Time spent by tasks of the cgroup in kernel mode.
40
41user and system are in USER_HZ unit.
42
43cpuacct controller uses percpu_counter interface to collect user and
44system 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=======
2CPUSETS
3=======
4
5Copyright (C) 2004 BULL SA.
6
7Written 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
351. Cpusets
36==========
37
381.1 What are cpusets ?
39----------------------
40
41Cpusets provide a mechanism for assigning a set of CPUs and Memory
42Nodes to a set of tasks. In this document "Memory Node" refers to
43an on-line node that contains memory.
44
45Cpusets constrain the CPU and Memory placement of tasks to only
46the resources within a task's current cpuset. They form a nested
47hierarchy visible in a virtual file system. These are the essential
48hooks, beyond what is already present, required to manage dynamic
49job placement on large systems.
50
51Cpusets use the generic cgroup subsystem described in
52Documentation/admin-guide/cgroup-v1/cgroups.rst.
53
54Requests by a task, using the sched_setaffinity(2) system call to
55include CPUs in its CPU affinity mask, and using the mbind(2) and
56set_mempolicy(2) system calls to include Memory Nodes in its memory
57policy, are both filtered through that task's cpuset, filtering out any
58CPUs or Memory Nodes not in that cpuset. The scheduler will not
59schedule a task on a CPU that is not allowed in its cpus_allowed
60vector, and the kernel page allocator will not allocate a page on a
61node that is not allowed in the requesting task's mems_allowed vector.
62
63User level code may create and destroy cpusets by name in the cgroup
64virtual file system, manage the attributes and permissions of these
65cpusets and which CPUs and Memory Nodes are assigned to each cpuset,
66specify and query to which cpuset a task is assigned, and list the
67task pids assigned to a cpuset.
68
69
701.2 Why are cpusets needed ?
71----------------------------
72
73The management of large computer systems, with many processors (CPUs),
74complex memory cache hierarchies and multiple Memory Nodes having
75non-uniform access times (NUMA) presents additional challenges for
76the efficient scheduling and memory placement of processes.
77
78Frequently more modest sized systems can be operated with adequate
79efficiency just by letting the operating system automatically share
80the available CPU and Memory resources amongst the requesting tasks.
81
82But larger systems, which benefit more from careful processor and
83memory placement to reduce memory access times and contention,
84and which typically represent a larger investment for the customer,
85can benefit from explicitly placing jobs on properly sized subsets of
86the system.
87
88This 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
96These subsets, or "soft partitions" must be able to be dynamically
97adjusted, as the job mix changes, without impacting other concurrently
98executing jobs. The location of the running jobs pages may also be moved
99when the memory locations are changed.
100
101The kernel cpuset patch provides the minimum essential kernel
102mechanisms required to efficiently implement such subsets. It
103leverages existing CPU and Memory Placement facilities in the Linux
104kernel to avoid any additional impact on the critical scheduler or
105memory allocator code.
106
107
1081.3 How are cpusets implemented ?
109---------------------------------
110
111Cpusets provide a Linux kernel mechanism to constrain which CPUs and
112Memory Nodes are used by a process or set of processes.
113
114The Linux kernel already has a pair of mechanisms to specify on which
115CPUs a task may be scheduled (sched_setaffinity) and on which Memory
116Nodes it may obtain memory (mbind, set_mempolicy).
117
118Cpusets 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
139The implementation of cpusets requires a few, simple hooks
140into 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
153You should mount the "cgroup" filesystem type in order to enable
154browsing and modifying the cpusets presently known to the kernel. No
155new system calls are added for cpusets - all support for querying and
156modifying cpusets is via this cpuset file system.
157
158The /proc/<pid>/status file for each task has four added lines,
159displaying the task's cpus_allowed (on which CPUs it may be scheduled)
160and mems_allowed (on which Memory Nodes it may obtain memory),
161in 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
168Each cpuset is represented by a directory in the cgroup file system
169containing (on top of the standard cgroup files) the following
170files 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
184In addition, only the root cpuset has the following file:
185
186 - cpuset.memory_pressure_enabled flag: compute memory_pressure?
187
188New cpusets are created using the mkdir system call or shell
189command. The properties of a cpuset, such as its flags, allowed
190CPUs and Memory Nodes, and attached tasks, are modified by writing
191to the appropriate file in that cpusets directory, as listed above.
192
193The named hierarchical structure of nested cpusets allows partitioning
194a large system into nested, dynamically changeable, "soft-partitions".
195
196The attachment of each task, automatically inherited at fork by any
197children of that task, to a cpuset allows organizing the work load
198on a system into related sets of tasks such that each set is constrained
199to using the CPUs and Memory Nodes of a particular cpuset. A task
200may be re-attached to any other cpuset, if allowed by the permissions
201on the necessary cpuset file system directories.
202
203Such management of a system "in the large" integrates smoothly with
204the detailed placement done on individual tasks and memory regions
205using the sched_setaffinity, mbind and set_mempolicy system calls.
206
207The 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
213These rules, and the natural hierarchy of cpusets, enable efficient
214enforcement of the exclusive guarantee, without having to scan all
215cpusets every time any of them change to ensure nothing overlaps a
216exclusive cpuset. Also, the use of a Linux virtual file system (vfs)
217to represent the cpuset hierarchy provides for a familiar permission
218and name space for cpusets, with a minimum of additional kernel code.
219
220The cpus and mems files in the root (top_cpuset) cpuset are
221read-only. The cpus file automatically tracks the value of
222cpu_online_mask using a CPU hotplug notifier, and the mems file
223automatically tracks the value of node_states[N_MEMORY]--i.e.,
224nodes with memory--using the cpuset_track_online_nodes() hook.
225
226
2271.4 What are exclusive cpusets ?
228--------------------------------
229
230If a cpuset is cpu or mem exclusive, no other cpuset, other than
231a direct ancestor or descendant, may share any of the same CPUs or
232Memory Nodes.
233
234A cpuset that is cpuset.mem_exclusive *or* cpuset.mem_hardwall is "hardwalled",
235i.e. it restricts kernel allocations for page, buffer and other data
236commonly shared by the kernel across multiple users. All cpusets,
237whether hardwalled or not, restrict allocations of memory for user
238space. This enables configuring a system so that several independent
239jobs can share common kernel data, such as file system pages, while
240isolating each job's user allocation in its own cpuset. To do this,
241construct a large mem_exclusive cpuset to hold all the jobs, and
242construct child, non-mem_exclusive cpusets for each individual job.
243Only a small amount of typical kernel memory, such as requests from
244interrupt handlers, is allowed to be taken outside even a
245mem_exclusive cpuset.
246
247
2481.5 What is memory_pressure ?
249-----------------------------
250The memory_pressure of a cpuset provides a simple per-cpuset metric
251of the rate that the tasks in a cpuset are attempting to free up in
252use memory on the nodes of the cpuset to satisfy additional memory
253requests.
254
255This enables batch managers monitoring jobs running in dedicated
256cpusets to efficiently detect what level of memory pressure that job
257is causing.
258
259This is useful both on tightly managed systems running a wide mix of
260submitted jobs, which may choose to terminate or re-prioritize jobs that
261are trying to use more memory than allowed on the nodes assigned to them,
262and with tightly coupled, long running, massively parallel scientific
263computing jobs that will dramatically fail to meet required performance
264goals if they start to use more memory than allowed to them.
265
266This mechanism provides a very economical way for the batch manager
267to monitor a cpuset for signs of memory pressure. It's up to the
268batch manager or other user code to decide what to do about it and
269take 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
278Why 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
296A per-cpuset simple digital filter (requires a spinlock and 3 words
297of data per-cpuset) is kept, and updated by any task attached to that
298cpuset, if it enters the synchronous (direct) page reclaim code.
299
300A per-cpuset file provides an integer number representing the recent
301(half-life of 10 seconds) rate of direct page reclaims caused by
302the tasks in the cpuset, in units of reclaims attempted per second,
303times 1000.
304
305
3061.6 What is memory spread ?
307---------------------------
308There are two boolean flag files per cpuset that control where the
309kernel allocates pages for the file system buffers and related in
310kernel data structures. They are called 'cpuset.memory_spread_page' and
311'cpuset.memory_spread_slab'.
312
313If the per-cpuset boolean flag file 'cpuset.memory_spread_page' is set, then
314the kernel will spread the file system buffers (page cache) evenly
315over all the nodes that the faulting task is allowed to use, instead
316of preferring to put those pages on the node where the task is running.
317
318If the per-cpuset boolean flag file 'cpuset.memory_spread_slab' is set,
319then the kernel will spread some file system related slab caches,
320such as for inodes and dentries evenly over all the nodes that the
321faulting task is allowed to use, instead of preferring to put those
322pages on the node where the task is running.
323
324The setting of these flags does not affect anonymous data segment or
325stack segment pages of a task.
326
327By default, both kinds of memory spreading are off, and memory
328pages are allocated on the node local to where the task is running,
329except perhaps as modified by the task's NUMA mempolicy or cpuset
330configuration, so long as sufficient free memory pages are available.
331
332When new cpusets are created, they inherit the memory spread settings
333of their parent.
334
335Setting memory spreading causes allocations for the affected page
336or slab caches to ignore the task's NUMA mempolicy and be spread
337instead. Tasks using mbind() or set_mempolicy() calls to set NUMA
338mempolicies will not notice any change in these calls as a result of
339their containing task's memory spread settings. If memory spreading
340is turned off, then the currently specified NUMA mempolicy once again
341applies to memory page allocations.
342
343Both 'cpuset.memory_spread_page' and 'cpuset.memory_spread_slab' are boolean flag
344files. By default they contain "0", meaning that the feature is off
345for that cpuset. If a "1" is written to that file, then that turns
346the named feature on.
347
348The implementation is simple.
349
350Setting the flag 'cpuset.memory_spread_page' turns on a per-process flag
351PFA_SPREAD_PAGE for each task that is in that cpuset or subsequently
352joins that cpuset. The page allocation calls for the page cache
353is modified to perform an inline check for this PFA_SPREAD_PAGE task
354flag, and if set, a call to a new routine cpuset_mem_spread_node()
355returns the node to prefer for the allocation.
356
357Similarly, setting 'cpuset.memory_spread_slab' turns on the flag
358PFA_SPREAD_SLAB, and appropriately marked slab caches will allocate
359pages from the node returned by cpuset_mem_spread_node().
360
361The cpuset_mem_spread_node() routine is also simple. It uses the
362value of a per-task rotor cpuset_mem_spread_rotor to select the next
363node in the current task's mems_allowed to prefer for the allocation.
364
365This memory placement policy is also known (in other contexts) as
366round-robin or interleave.
367
368This policy can provide substantial improvements for jobs that need
369to place thread local data on the corresponding node, but that need
370to access large file system data sets that need to be spread across
371the several nodes in the jobs cpuset in order to fit. Without this
372policy, especially for jobs that might have one thread reading in the
373data set, the memory allocation across the nodes in the jobs cpuset
374can become very uneven.
375
3761.7 What is sched_load_balance ?
377--------------------------------
378
379The kernel scheduler (kernel/sched/core.c) automatically load balances
380tasks. If one CPU is underutilized, kernel code running on that
381CPU will look for tasks on other more overloaded CPUs and move those
382tasks to itself, within the constraints of such placement mechanisms
383as cpusets and sched_setaffinity.
384
385The algorithmic cost of load balancing and its impact on key shared
386kernel data structures such as the task list increases more than
387linearly with the number of CPUs being balanced. So the scheduler
388has support to partition the systems CPUs into a number of sched
389domains such that it only load balances within each sched domain.
390Each sched domain covers some subset of the CPUs in the system;
391no two sched domains overlap; some CPUs might not be in any sched
392domain and hence won't be load balanced.
393
394Put simply, it costs less to balance between two smaller sched domains
395than one big one, but doing so means that overloads in one of the
396two domains won't be load balanced to the other one.
397
398By default, there is one sched domain covering all CPUs, including those
399marked isolated using the kernel boot time "isolcpus=" argument. However,
400the isolated CPUs will not participate in load balancing, and will not
401have tasks running on them unless explicitly assigned.
402
403This default load balancing across all CPUs is not well suited for
404the 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
413When the per-cpuset flag "cpuset.sched_load_balance" is enabled (the default
414setting), it requests that all the CPUs in that cpusets allowed 'cpuset.cpus'
415be contained in a single sched domain, ensuring that load balancing
416can move a task (not otherwised pinned, as by sched_setaffinity)
417from any CPU in that cpuset to any other.
418
419When the per-cpuset flag "cpuset.sched_load_balance" is disabled, then the
420scheduler will avoid load balancing across the CPUs in that cpuset,
421--except-- in so far as is necessary because some overlapping cpuset
422has "sched_load_balance" enabled.
423
424So, for example, if the top cpuset has the flag "cpuset.sched_load_balance"
425enabled, then the scheduler will have one sched domain covering all
426CPUs, and the setting of the "cpuset.sched_load_balance" flag in any other
427cpusets won't matter, as we're already fully load balancing.
428
429Therefore in the above two situations, the top cpuset flag
430"cpuset.sched_load_balance" should be disabled, and only some of the smaller,
431child cpusets have this flag enabled.
432
433When doing this, you don't usually want to leave any unpinned tasks in
434the top cpuset that might use non-trivial amounts of CPU, as such tasks
435may be artificially constrained to some subset of CPUs, depending on
436the particulars of this flag setting in descendant cpusets. Even if
437such a task could use spare CPU cycles in some other CPUs, the kernel
438scheduler might not consider the possibility of load balancing that
439task to that underused CPU.
440
441Of course, tasks pinned to a particular CPU can be left in a cpuset
442that disables "cpuset.sched_load_balance" as those tasks aren't going anywhere
443else anyway.
444
445There is an impedance mismatch here, between cpusets and sched domains.
446Cpusets are hierarchical and nest. Sched domains are flat; they don't
447overlap and each CPU is in at most one sched domain.
448
449It is necessary for sched domains to be flat because load balancing
450across partially overlapping sets of CPUs would risk unstable dynamics
451that would be beyond our understanding. So if each of two partially
452overlapping cpusets enables the flag 'cpuset.sched_load_balance', then we
453form a single sched domain that is a superset of both. We won't move
454a task to a CPU outside its cpuset, but the scheduler load balancing
455code might waste some compute cycles considering that possibility.
456
457This mismatch is why there is not a simple one-to-one relation
458between which cpusets have the flag "cpuset.sched_load_balance" enabled,
459and the sched domain configuration. If a cpuset enables the flag, it
460will get balancing across all its CPUs, but if it disables the flag,
461it will only be assured of no load balancing if no other overlapping
462cpuset enables the flag.
463
464If two cpusets have partially overlapping 'cpuset.cpus' allowed, and only
465one of them has this flag enabled, then the other may find its
466tasks only partially load balanced, just on the overlapping CPUs.
467This is just the general case of the top_cpuset example given a few
468paragraphs above. In the general case, as in the top cpuset case,
469don't leave tasks that might use non-trivial amounts of CPU in
470such partially load balanced cpusets, as they may be artificially
471constrained to some subset of the CPUs allowed to them, for lack of
472load balancing to the other CPUs.
473
474CPUs in "cpuset.isolcpus" were excluded from load balancing by the
475isolcpus= kernel boot option, and will never be load balanced regardless
476of the value of "cpuset.sched_load_balance" in any cpuset.
477
4781.7.1 sched_load_balance implementation details.
479------------------------------------------------
480
481The per-cpuset flag 'cpuset.sched_load_balance' defaults to enabled (contrary
482to most cpuset flags.) When enabled for a cpuset, the kernel will
483ensure 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
485in the same sched domain.)
486
487If two overlapping cpusets both have 'cpuset.sched_load_balance' enabled,
488then they will be (must be) both in the same sched domain.
489
490If, as is the default, the top cpuset has 'cpuset.sched_load_balance' enabled,
491then by the above that means there is a single sched domain covering
492the whole system, regardless of any other cpuset settings.
493
494The kernel commits to user space that it will avoid load balancing
495where it can. It will pick as fine a granularity partition of sched
496domains as it can while still providing load balancing for any set
497of CPUs allowed to a cpuset having 'cpuset.sched_load_balance' enabled.
498
499The internal kernel cpuset to scheduler interface passes from the
500cpuset code to the scheduler code a partition of the load balanced
501CPUs in the system. This partition is a set of subsets (represented
502as an array of struct cpumask) of CPUs, pairwise disjoint, that cover
503all the CPUs that must be load balanced.
504
505The cpuset code builds a new such partition and passes it to the
506scheduler sched domain setup code, to have the sched domains rebuilt
507as 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
516This partition exactly defines what sched domains the scheduler should
517setup - one sched domain for each element (struct cpumask) in the
518partition.
519
520The scheduler remembers the currently active sched domain partitions.
521When the scheduler routine partition_sched_domains() is invoked from
522the cpuset code to update these sched domains, it compares the new
523partition requested with the current, and updates its sched domains,
524removing the old and adding the new, for each change.
525
526
5271.8 What is sched_relax_domain_level ?
528--------------------------------------
529
530In sched domain, the scheduler migrates tasks in 2 ways; periodic load
531balance on tick, and at time of some schedule events.
532
533When a task is woken up, scheduler try to move the task on idle CPU.
534For example, if a task A running on CPU X activates another task B
535on the same CPU X, and if CPU Y is X's sibling and performing idle,
536then scheduler migrate task B to CPU Y so that task B can start on
537CPU Y without waiting task A on CPU X.
538
539And if a CPU run out of tasks in its runqueue, the CPU try to pull
540extra tasks from other busy CPUs to help them before it is going to
541be idle.
542
543Of course it takes some searching cost to find movable tasks and/or
544idle CPUs, the scheduler might not search all CPUs in the domain
545every time. In fact, in some architectures, the searching ranges on
546events are limited in the same socket or node where the CPU locates,
547while the load balance on tick searches all.
548
549For example, assume CPU Z is relatively far from CPU X. Even if CPU Z
550is idle while CPU X and the siblings are busy, scheduler can't migrate
551woken task B from X to Z since it is out of its searching range.
552As the result, task B on CPU X need to wait task A or wait load balance
553on the next tick. For some applications in special situation, waiting
5541 tick may be too long.
555
556The 'cpuset.sched_relax_domain_level' file allows you to request changing
557this searching range as you like. This file takes int value which
558indicates size of searching range in levels ideally as follows,
559otherwise 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
571The system default is architecture dependent. The system default
572can be changed using the relax_domain_level= boot parameter.
573
574This file is per-cpuset and affect the sched domain where the cpuset
575belongs to. Therefore if the flag 'cpuset.sched_load_balance' of a cpuset
576is disabled, then 'cpuset.sched_relax_domain_level' have no effect since
577there is no sched domain belonging the cpuset.
578
579If multiple cpusets are overlapping and hence they form a single sched
580domain, the largest value among those is used. Be careful, if one
581requests 0 and others are -1 then 0 is used.
582
583Note that modifying this file will have both good and bad effects,
584and whether it is acceptable or not depends on your situation.
585Don't modify this file if you are not sure.
586
587If 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
5981.9 How do I use cpusets ?
599--------------------------
600
601In order to minimize the impact of cpusets on critical kernel
602code, such as the scheduler, and due to the fact that the kernel
603does not support one task updating the memory placement of another
604task directly, the impact on a task of changing its cpuset CPU
605or Memory Node placement, or of changing to which cpuset a task
606is attached, is subtle.
607
608If a cpuset has its Memory Nodes modified, then for each task attached
609to that cpuset, the next time that the kernel attempts to allocate
610a page of memory for that task, the kernel will notice the change
611in the task's cpuset, and update its per-task memory placement to
612remain within the new cpusets memory placement. If the task was using
613mempolicy MPOL_BIND, and the nodes to which it was bound overlap with
614its new cpuset, then the task will continue to use whatever subset
615of MPOL_BIND nodes are still allowed in the new cpuset. If the task
616was using MPOL_BIND and now none of its MPOL_BIND nodes are allowed
617in the new cpuset, then the task will be essentially treated as if it
618was MPOL_BIND bound to the new cpuset (even though its NUMA placement,
619as queried by get_mempolicy(), doesn't change). If a task is moved
620from one cpuset to another, then the kernel will adjust the task's
621memory placement, as above, the next time that the kernel attempts
622to allocate a page of memory for that task.
623
624If a cpuset has its 'cpuset.cpus' modified, then each task in that cpuset
625will have its allowed CPU placement changed immediately. Similarly,
626if a task's pid is written to another cpuset's 'tasks' file, then its
627allowed CPU placement is changed immediately. If such a task had been
628bound to some subset of its cpuset using the sched_setaffinity() call,
629the task will be allowed to run on any CPU allowed in its new cpuset,
630negating the effect of the prior sched_setaffinity() call.
631
632In summary, the memory placement of a task whose cpuset is changed is
633updated by the kernel, on the next allocation of a page for that task,
634and the processor placement is updated immediately.
635
636Normally, once a page is allocated (given a physical page
637of main memory) then that page stays on whatever node it
638was allocated, so long as it remains allocated, even if the
639cpusets memory placement policy 'cpuset.mems' subsequently changes.
640If the cpuset flag file 'cpuset.memory_migrate' is set true, then when
641tasks are attached to that cpuset, any pages that task had
642allocated to it on nodes in its previous cpuset are migrated
643to the task's new cpuset. The relative placement of the page within
644the cpuset is preserved during these migration operations if possible.
645For example if the page was on the second valid node of the prior cpuset
646then the page will be placed on the second valid node of the new cpuset.
647
648Also if 'cpuset.memory_migrate' is set true, then if that cpuset's
649'cpuset.mems' file is modified, pages allocated to tasks in that
650cpuset, that were on nodes in the previous setting of 'cpuset.mems',
651will be moved to nodes in the new setting of 'mems.'
652Pages that were not in the task's prior cpuset, or in the cpuset's
653prior 'cpuset.mems' setting, will not be moved.
654
655There is an exception to the above. If hotplug functionality is used
656to remove all the CPUs that are currently assigned to a cpuset,
657then all the tasks in that cpuset will be moved to the nearest ancestor
658with non-empty cpus. But the moving of some (or all) tasks might fail if
659cpuset is bound with another cgroup subsystem which has some restrictions
660on task attaching. In this failing case, those tasks will stay
661in the original cpuset, and the kernel will automatically update
662their cpus_allowed to allow all online CPUs. When memory hotplug
663functionality for removing Memory Nodes is available, a similar exception
664is expected to apply there as well. In general, the kernel prefers to
665violate cpuset placement, over starving a task that has had all
666its allowed CPUs or Memory Nodes taken offline.
667
668There is a second exception to the above. GFP_ATOMIC requests are
669kernel internal allocations that must be satisfied, immediately.
670The kernel may drop some request, in rare cases even panic, if a
671GFP_ATOMIC alloc fails. If the request cannot be satisfied within
672the current task's cpuset, then we relax the cpuset, and look for
673memory anywhere we can find it. It's better to violate the cpuset
674than stress the kernel.
675
676To 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
687For example, the following sequence of commands will setup a cpuset
688named "Charlie", containing just CPUs 2 and 3, and Memory Node 1,
689and 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
703There 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
713The sched_setaffinity calls can also be done at the shell prompt using
714SGI's runon or Robert Love's taskset. The mbind and set_mempolicy
715calls can be done at the shell prompt using the numactl command
716(part of Andi Kleen's numa package).
717
7182. Usage Examples and Syntax
719============================
720
7212.1 Basic Usage
722---------------
723
724Creating, modifying, using the cpusets can be done through the cpuset
725virtual filesystem.
726
727To mount it, type:
728# mount -t cgroup -o cpuset cpuset /sys/fs/cgroup/cpuset
729
730Then under /sys/fs/cgroup/cpuset you can find a tree that corresponds to the
731tree of the cpusets in the system. For instance, /sys/fs/cgroup/cpuset
732is the cpuset that holds the whole system.
733
734If you want to create a new cpuset under /sys/fs/cgroup/cpuset::
735
736 # cd /sys/fs/cgroup/cpuset
737 # mkdir my_cpuset
738
739Now you want to do something with this cpuset::
740
741 # cd my_cpuset
742
743In 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
755Reading them will give you information about the state of this cpuset:
756the CPUs and Memory Nodes it can use, the processes that are using
757it, its properties. By writing to these files you can manipulate
758the cpuset.
759
760Set some flags::
761
762 # /bin/echo 1 > cpuset.cpu_exclusive
763
764Add some cpus::
765
766 # /bin/echo 0-7 > cpuset.cpus
767
768Add some mems::
769
770 # /bin/echo 0-7 > cpuset.mems
771
772Now attach your shell to this cpuset::
773
774 # /bin/echo $$ > tasks
775
776You can also create cpusets inside your cpuset by using mkdir in this
777directory::
778
779 # mkdir my_sub_cs
780
781To remove a cpuset, just use rmdir::
782
783 # rmdir my_sub_cs
784
785This will fail if the cpuset is in use (has cpusets inside, or has
786processes attached).
787
788Note that for legacy reasons, the "cpuset" filesystem exists as a
789wrapper around the cgroup filesystem.
790
791The command::
792
793 mount -t cpuset X /sys/fs/cgroup/cpuset
794
795is 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
8002.2 Adding/removing cpus
801------------------------
802
803This is the syntax to use when writing in the cpus or mems files
804in 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
809To add a CPU to a cpuset, write the new list of CPUs including the
810CPU 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
814Similarly to remove a CPU from a cpuset, write the new list of CPUs
815without the CPU to be removed.
816
817To remove all the CPUs::
818
819 # /bin/echo "" > cpuset.cpus -> clear cpus list
820
8212.3 Setting flags
822-----------------
823
824The 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
8292.4 Attaching processes
830-----------------------
831
832::
833
834 # /bin/echo PID > tasks
835
836Note that it is PID, not PIDs. You can only attach ONE task at a time.
837If 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
8453. Questions
846============
847
848Q:
849 what's up with this '/bin/echo' ?
850
851A:
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
856Q:
857 When I attach processes, only the first of the line gets really attached !
858
859A:
860 We can only return one error code per call to write(). So you should also
861 put only ONE pid.
862
8634. Contact
864==========
865
866Web: http://www.bullopensource.org/cpuset
Documentation/admin-guide/cgroup-v1/devices.rst+132−0
@@ -0,0 +1,132 @@
1===========================
2Device Whitelist Controller
3===========================
4
51. Description
6==============
7
8Implement a cgroup to track and enforce open and mknod restrictions
9on device files. A device cgroup associates a device access
10whitelist with each cgroup. A whitelist entry has 4 fields.
11'type' is a (all), c (char), or b (block). 'all' means it applies
12to all types and all major and minor numbers. Major and minor are
13either an integer or * for all. Access is a composition of r
14(read), w (write), and m (mknod).
15
16The root device cgroup starts with rwm to 'all'. A child device
17cgroup gets a copy of the parent. Administrators can then remove
18devices from the whitelist or add new entries. A child cgroup can
19never receive a device access which is denied by its parent.
20
212. User Interface
22=================
23
24An entry is added using devices.allow, and removed using
25devices.deny. For instance::
26
27 echo 'c 1:3 mr' > /sys/fs/cgroup/1/devices.allow
28
29allows 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
34will remove the default 'a *:* rwm' entry. Doing::
35
36 echo a > /sys/fs/cgroup/1/devices.allow
37
38will add the 'a *:* rwm' entry to the whitelist.
39
403. Security
41===========
42
43Any task can move itself between cgroups. This clearly won't
44suffice, but we can decide the best way to adequately restrict
45movement as people get some experience with this. We may just want
46to require CAP_SYS_ADMIN, which at least is a separate bit from
47CAP_MKNOD. We may want to just refuse moving to a cgroup which
48isn't a descendant of the current one. Or we may want to use
49CAP_MAC_ADMIN, since we really are trying to lock down root.
50
51CAP_SYS_ADMIN is needed to modify the whitelist or move another
52task to a new cgroup. (Again we'll probably want to change that).
53
54A cgroup may not be granted more permissions than the cgroup's
55parent has.
56
574. Hierarchy
58============
59
60device cgroups maintain hierarchy by making sure a cgroup never has more
61access permissions than its parent. Every time an entry is written to
62a cgroup's devices.deny file, all its children will have that entry removed
63from their whitelist and all the locally set whitelist entries will be
64re-evaluated. In case one of the locally set whitelist entries would provide
65more access than the cgroup's parent, it'll be removed from the whitelist.
66
67Example::
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
77If a device is denied in group A::
78
79 # echo "c 116:* r" > A/devices.deny
80
81it'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
88In case parent's exceptions change and local exceptions are not allowed
89anymore, they'll be deleted.
90
91Notice 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
101when adding ``c *:3 rwm``::
102
103 # echo "c *:3 rwm" >A/devices.allow
104
105the 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
111but 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
116or even::
117
118 # echo "c *:3 rwm" >B/devices.allow
119
120Allowing or denying all by writing 'a' to devices.allow or devices.deny will
121not be possible once the device cgroups has children.
122
1234.1 Hierarchy (internal implementation)
124---------------------------------------
125
126device cgroups is implemented internally using a behavior (ALLOW, DENY) and a
127list of exceptions. The internal state is controlled using the same user
128interface to preserve compatibility with the previous whitelist-only
129implementation. Removal or addition of exceptions that will reduce the access
130to devices will be propagated down the hierarchy.
131For every propagated exception, the effective rules will be re-evaluated based
132on current parent's access rules.
Documentation/admin-guide/cgroup-v1/freezer-subsystem.rst+127−0
@@ -0,0 +1,127 @@
1==============
2Cgroup Freezer
3==============
4
5The cgroup freezer is useful to batch job management system which start
6and stop sets of tasks in order to schedule the resources of a machine
7according to the desires of a system administrator. This sort of program
8is often used on HPC clusters to schedule access to the cluster as a
9whole. The cgroup freezer uses cgroups to describe the set of tasks to
10be started/stopped by the batch job management system. It also provides
11a means to start and stop the tasks composing the job.
12
13The cgroup freezer will also be useful for checkpointing running groups
14of tasks. The freezer allows the checkpoint code to obtain a consistent
15image of the tasks by attempting to force the tasks in a cgroup into a
16quiescent state. Once the tasks are quiescent another task can
17walk /proc or invoke a kernel interface to gather information about the
18quiesced tasks. Checkpointed tasks can be restarted later should a
19recoverable error occur. This also allows the checkpointed tasks to be
20migrated between nodes in a cluster by copying the gathered information
21to another node and restarting the tasks there.
22
23Sequences of SIGSTOP and SIGCONT are not always sufficient for stopping
24and resuming tasks in userspace. Both of these signals are observable
25from within the tasks we wish to freeze. While SIGSTOP cannot be caught,
26blocked, or ignored it can be seen by waiting or ptracing parent tasks.
27SIGCONT is especially unsuitable since it can be caught by the task. Any
28programs designed to watch for SIGSTOP and SIGCONT could be broken by
29attempting to use SIGSTOP and SIGCONT to stop and resume tasks. We can
30demonstrate 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
44This happens because bash can observe both signals and choose how it
45responds to them.
46
47Another example of a program which catches and responds to these
48signals is gdb. In fact any program designed to use ptrace is likely to
49have a problem with this method of stopping and resuming tasks.
50
51In contrast, the cgroup freezer uses the kernel freezer code to
52prevent the freeze/unfreeze cycle from becoming visible to the tasks
53being frozen. This allows the bash example above and gdb to run as
54expected.
55
56The cgroup freezer is hierarchical. Freezing a cgroup freezes all
57tasks belonging to the cgroup and all its descendant cgroups. Each
58cgroup has its own state (self-state) and the state inherited from the
59parent (parent-state). Iff both states are THAWED, the cgroup is
60THAWED.
61
62The 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
97The root cgroup is non-freezable and the above interface files don't
98exist.
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
107to get status of the freezer subsystem::
108
109 # cat /sys/fs/cgroup/freezer/0/freezer.state
110 THAWED
111
112to 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
120to 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
126This is the basic mechanism which should do the right thing for user space task
127in a simple scenario.
Documentation/admin-guide/cgroup-v1/hugetlb.rst+50−0
@@ -0,0 +1,50 @@
1==================
2HugeTLB Controller
3==================
4
5The HugeTLB controller allows to limit the HugeTLB usage per control group and
6enforces the controller limit during page fault. Since HugeTLB doesn't
7support page reclaim, enforcing the limit at page fault time implies that,
8the application will get SIGBUS signal if it tries to access HugeTLB pages
9beyond its limit. This requires the application to know beforehand how much
10HugeTLB pages it would require for its use.
11
12HugeTLB controller can be created by first mounting the cgroup filesystem.
13
14# mount -t cgroup -o hugetlb none /sys/fs/cgroup
15
16With the above step, the initial or the parent HugeTLB group becomes
17visible at /sys/fs/cgroup. At bootup, this group includes all the tasks in
18the system. /sys/fs/cgroup/tasks lists the tasks in this cgroup.
19
20New 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
26The above steps create a new group g1 and move the current shell
27process (bash) into it.
28
29Brief 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
36For a system supporting three hugepage sizes (64k, 32M and 1G), the control
37files 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========================
2Control 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=====================================================
2Memory Resource Controller(Memcg) Implementation Memo
3=====================================================
4
5Last Updated: 2010/2
6
7Base Kernel Version: based on 2.6.33-rc7-mm(candidate for 34).
8
9Because VM is getting complex (one of reasons is memcg...), memcg's behavior
10is complex. This is a document for memcg's internal behavior.
11Please note that implementation details can be changed.
12
13(*) Topics on API should be in Documentation/admin-guide/cgroup-v1/memory.rst)
14
150. 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
311. Charge
32=========
33
34 a page/swp_entry may be charged (usage += PAGE_SIZE) at
35
36 mem_cgroup_try_charge()
37
382. 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
503. 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
65Under below explanation, we assume CONFIG_MEM_RES_CTRL_SWAP=y.
66
674. 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
965. 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
1086. 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
1297. Page Migration
130=================
131
132 mem_cgroup_migrate()
133
1348. 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
1499. Typical Tests.
150=================
151
152 Tests for racy cases.
153
1549.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
1649.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
1719.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
2099.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
2229.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
2449.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
2569.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
2839.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
3099.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
3339.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==========================
2Memory Resource Controller
3==========================
4
5NOTE:
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
11NOTE:
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
22Benefits and Purpose of the memory controller
23=============================================
24
25The memory controller isolates the memory behaviour of a group of tasks
26from the rest of the system. The article on LWN [12] mentions some probable
27uses of the memory controller. The memory controller can be used to
28
29a. Isolate an application or a group of applications
30 Memory-hungry applications can be isolated and limited to a smaller
31 amount of memory.
32b. Create a cgroup with a limited amount of memory; this can be used
33 as a good alternative to booting with mem=XXXX.
34c. Virtualization solutions can control the amount of memory they want
35 to assign to a virtual machine instance.
36d. 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.
39e. 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
42Current Status: linux-2.6.34-mmotm(development version of 2010/April)
43
44Features:
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
60Brief 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
1021. History
103==========
104
105The memory controller has a long history. A request for comments for the memory
106controller was posted by Balbir Singh [1]. At the time the RFC was posted
107there were several implementations for memory control. The goal of the
108RFC was to build consensus and agreement for the minimal features required
109for memory control. The first RSS controller was posted by Balbir Singh[2]
110in Feb 2007. Pavel Emelianov [3][4][5] has since posted three versions of the
111RSS controller. At OLS, at the resource management BoF, everyone suggested
112that we handle both page cache and RSS together. Another request was raised
113to allow user space handling of OOM. The current memory controller is
114at version 6; it combines both mapped (RSS) and unmapped Page
115Cache Control [11].
116
1172. Memory Control
118=================
119
120Memory is a unique resource in the sense that it is present in a limited
121amount. If a task requires a lot of CPU processing, the task can spread
122its processing over a period of hours, days, months or years, but with
123memory, the same physical memory needs to be reused to accomplish the task.
124
125The memory controller implementation has been divided into phases. These
126are:
127
1281. Memory controller
1292. mlock(2) controller
1303. Kernel user memory accounting and slab control
1314. user mappings length controller
132
133The memory controller is the first controller developed.
134
1352.1. Design
136-----------
137
138The core of the design is a counter called the page_counter. The
139page_counter tracks the current memory usage and limit of the group of
140processes associated with the controller. Each cgroup has a memory controller
141specific data structure (mem_cgroup) associated with it.
142
1432.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
169Figure 1 shows the important aspects of the controller
170
1711. Accounting happens per cgroup
1722. Each mm_struct knows about which cgroup it belongs to
1733. Each page has a pointer to the page_cgroup, which in turn knows the
174 cgroup it belongs to
175
176The accounting is done as follows: mem_cgroup_charge_common() is invoked to
177set up the necessary data structures and check if the cgroup that is being
178charged is over its limit. If it is, then reclaim is invoked on the cgroup.
179More details can be found in the reclaim section of this document.
180If everything goes well, a page meta-data-structure called page_cgroup is
181updated. page_cgroup has its own LRU on cgroup.
182(*) page_cgroup structure is allocated at boot/memory-hotplug time.
183
1842.2.1 Accounting details
185------------------------
186
187All mapped anon pages (RSS) and cache pages (Page Cache) are accounted.
188Some pages which are never reclaimable and will not be on the LRU
189are not accounted. We just account pages under usual VM management.
190
191RSS pages are accounted at page_fault unless they've already been accounted
192for earlier. A file page will be accounted for as Page Cache when it's
193inserted into inode (radix-tree). While it's mapped into the page tables of
194processes, duplicate accounting is carefully avoided.
195
196An RSS page is unaccounted when it's fully unmapped. A PageCache page is
197unaccounted when it's removed from radix-tree. Even if RSS pages are fully
198unmapped (by kswapd), they may exist as SwapCache in the system until they
199are really freed. Such SwapCaches are also accounted.
200A swapped-in page is not accounted until it's mapped.
201
202Note: The kernel does swapin-readahead and reads multiple swaps at once.
203This means swapped-in pages may contain pages for other tasks than a task
204causing page fault. So, we avoid accounting at swap-in I/O.
205
206At page migration, accounting information is kept.
207
208Note: we just account pages-on-LRU because our purpose is to control amount
209of used pages; not-on-LRU pages tend to be out-of-control from VM view.
210
2112.3 Shared Page Accounting
212--------------------------
213
214Shared pages are accounted on the basis of the first touch approach. The
215cgroup that first touches a page is accounted for the page. The principle
216behind this approach is that a cgroup that aggressively uses a shared
217page will eventually get charged for it (once it is uncharged from
218the cgroup that brought it in -- this will happen on memory pressure).
219
220But see section 8.2: when moving a task to another cgroup, its pages may
221be recharged to the new cgroup, if move_charge_at_immigrate has been chosen.
222
223Exception: If CONFIG_MEMCG_SWAP is not used.
224When you do swapoff and make swapped-out pages of shmem(tmpfs) to
225be backed into memory in force, charges for pages are accounted against the
226caller of swapoff rather than the users of shmem.
227
2282.4 Swap Extension (CONFIG_MEMCG_SWAP)
229--------------------------------------
230
231Swap Extension allows you to record charge for swap. A swapped-in page is
232charged back to original page allocator if possible.
233
234When swap is accounted, following files are added.
235
236 - memory.memsw.usage_in_bytes.
237 - memory.memsw.limit_in_bytes.
238
239memsw means memory+swap. Usage of memory+swap is limited by
240memsw.limit_in_bytes.
241
242Example: 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.
244In this case, setting memsw.limit_in_bytes=3G will prevent bad use of swap.
245By using the memsw limit, you can avoid system OOM which can be caused by swap
246shortage.
247
248**why 'memory+swap' rather than swap**
249
250The global LRU(kswapd) can swap out arbitrary pages. Swap-out means
251to move account from memory to swap...there is no change in usage of
252memory+swap. In other words, when we want to limit the usage of swap without
253affecting global LRU, memory+swap limit is better than just limiting swap from
254an OS point of view.
255
256**What happens when a cgroup hits memory.memsw.limit_in_bytes**
257
258When a cgroup hits memory.memsw.limit_in_bytes, it's useless to do swap-out
259in this cgroup. Then, swap-out will not be done by cgroup routine and file
260caches are dropped. But as mentioned above, global LRU can do swapout memory
261from it for sanity of the system's memory management state. You can't forbid
262it by cgroup.
263
2642.5 Reclaim
265-----------
266
267Each cgroup maintains a per cgroup LRU which has the same structure as
268global VM. When a cgroup goes over its limit, we first try
269to reclaim memory from the cgroup so as to make space for the new
270pages that the cgroup has touched. If the reclaim is unsuccessful,
271an OOM routine is invoked to select and kill the bulkiest task in the
272cgroup. (See 10. OOM Control below.)
273
274The reclaim algorithm has not been modified for cgroups, except that
275pages that are selected for reclaiming come from the per-cgroup LRU
276list.
277
278NOTE:
279 Reclaim does not work for the root cgroup, since we cannot set any
280 limits on the root cgroup.
281
282Note2:
283 When panic_on_oom is set to "2", the whole system will panic.
284
285When oom event notifier is registered, event will be delivered.
286(See oom_control section)
287
2882.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
3062.7 Kernel Memory Extension (CONFIG_MEMCG_KMEM)
307-----------------------------------------------
308
309With the Kernel memory extension, the Memory Controller is able to limit
310the amount of kernel memory used by the system. Kernel memory is fundamentally
311different than user memory, since it can't be swapped out, which makes it
312possible to DoS the system by consuming too much of this precious resource.
313
314Kernel memory accounting is enabled for all memory cgroups by default. But
315it can be disabled system-wide by passing cgroup.memory=nokmem to the kernel
316at boot time. In this case, kernel memory will not be accounted at all.
317
318Kernel memory limits are not imposed for the root cgroup. Usage for the root
319cgroup may or may not be accounted. The memory used is accumulated into
320memory.kmem.usage_in_bytes, or in a separate counter when it makes sense.
321(currently only for tcp).
322
323The main "kmem" counter is fed into the main counter, so kmem charges will
324also be visible from the user counter.
325
326Currently no soft limit is implemented for kernel memory. It is future work
327to trigger slab reclaim when those limits are reached.
328
3292.7.1 Current Kernel Memory resources accounted
330-----------------------------------------------
331
332stack 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
337slab 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
345sockets 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
350tcp memory pressure:
351 sockets memory pressure for the tcp protocol.
352
3532.7.2 Common use cases
354----------------------
355
356Because the "kmem" counter is fed to the main user counter, kernel memory can
357never be limited completely independently of user memory. Say "U" is the user
358limit, and "K" the kernel limit. There are three possible ways limits can be
359set:
360
361U != 0, K = unlimited:
362 This is the standard memcg limitation mechanism already present before kmem
363 accounting. Kernel memory is completely ignored.
364
365U != 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
374WARNING:
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
379U != 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
3853. User Interface
386=================
387
3883.0. Configuration
389------------------
390
391a. Enable CONFIG_CGROUPS
392b. Enable CONFIG_MEMCG
393c. Enable CONFIG_MEMCG_SWAP (to use swap extension)
394d. Enable CONFIG_MEMCG_KMEM (to use kmem extension)
395
3963.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
4053.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
410Since 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
414NOTE:
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
419NOTE:
420 We can write "-1" to reset the ``*.limit_in_bytes(unlimited)``.
421
422NOTE:
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
430We can check the usage::
431
432 # cat /sys/fs/cgroup/memory/0/memory.usage_in_bytes
433 1216512
434
435A successful write to this file does not guarantee a successful setting of
436this limit to the value written into the file. This can be due to a
437number of factors, such as rounding up to page boundaries or the total
438availability of memory on the system. The user is required to re-read
439this 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
445The memory.failcnt field gives the number of times that the cgroup limit was
446exceeded.
447
448The memory.stat file gives accounting information. Now, the number of
449caches, RSS and Active pages/Inactive pages are shown.
450
4514. Testing
452==========
453
454For testing features and implementation, see memcg_test.txt.
455
456Performance test is also important. To see pure memory controller's overhead,
457testing on tmpfs will give you good numbers of small overheads.
458Example: do kernel make on tmpfs.
459
460Page-fault scalability is also important. At measuring parallel
461page fault test, multi-process test may be better than multi-thread
462test because it has noise of shared objects/status.
463
464But the above two are testing extreme situations.
465Trying usual test under memory controller is always helpful.
466
4674.1 Troubleshooting
468-------------------
469
470Sometimes a user might find that the application under a cgroup is
471terminated by the OOM killer. There are several causes for this:
472
4731. The cgroup limit is too low (just too low to do anything useful)
4742. The user is using anonymous memory and swap is turned off or too low
475
476A sync followed by echo 1 > /proc/sys/vm/drop_caches will help get rid of
477some of the pages cached in the cgroup (page cache pages).
478
479To know what happens, disabling OOM_Kill as per "10. OOM Control" (below) and
480seeing what happens will be helpful.
481
4824.2 Task migration
483------------------
484
485When a task migrates from one cgroup to another, its charge is not
486carried forward by default. The pages allocated from the original cgroup still
487remain charged to it, the charge is dropped when the page is freed or
488reclaimed.
489
490You can move charges of a task along with task migration.
491See 8. "Move charges at task migration"
492
4934.3 Removing a cgroup
494---------------------
495
496A cgroup can be removed by rmdir, but as discussed in sections 4.1 and 4.2, a
497cgroup might have some charge associated with it, even though all
498tasks have migrated away from it. (because we charge against pages, not
499against tasks.)
500
501We move the stats to root (if use_hierarchy==0) or parent (if
502use_hierarchy==1), and no change on the charge except uncharging
503from the child.
504
505Charges recorded in swap information is not updated at removal of cgroup.
506Recorded information is discarded and a cgroup which uses swap (swapcache)
507will be charged as a new owner of it.
508
509About use_hierarchy, see Section 6.
510
5115. Misc. interfaces
512===================
513
5145.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
5355.2 stat file
536-------------
537
538memory.stat file includes following statistics
539
540per-memory cgroup local status
541^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
542
543=============== ===============================================================
544cache # of bytes of page cache memory.
545rss # of bytes of anonymous and swap cache memory (includes
546 transparent hugepages).
547rss_huge # of bytes of anonymous transparent hugepages.
548mapped_file # of bytes of mapped file (includes tmpfs/shmem)
549pgpgin # 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.
552pgpgout # of uncharging events to the memory cgroup. The uncharging
553 event happens each time a page is unaccounted from the cgroup.
554swap # of bytes of swap usage
555dirty # of bytes that are waiting to get written back to the disk.
556writeback # of bytes of file/anon cache that are queued for syncing to
557 disk.
558inactive_anon # of bytes of anonymous and swap cache memory on inactive
559 LRU list.
560active_anon # of bytes of anonymous and swap cache memory on active
561 LRU list.
562inactive_file # of bytes of file-backed memory on inactive LRU list.
563active_file # of bytes of file-backed memory on active LRU list.
564unevictable # of bytes of memory that cannot be reclaimed (mlocked etc).
565=============== ===============================================================
566
567status considering hierarchy (see memory.use_hierarchy settings)
568^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
569
570========================= ===================================================
571hierarchical_memory_limit # of bytes of memory limit with regard to hierarchy
572 under which the memory cgroup is
573hierarchical_memsw_limit # of bytes of memory+swap limit with regard to
574 hierarchy under which memory cgroup is.
575
576total_<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
582The following additional stats are dependent on CONFIG_DEBUG_VM
583^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
584
585========================= ========================================
586recent_rotated_anon VM internal parameter. (see mm/vmscan.c)
587recent_rotated_file VM internal parameter. (see mm/vmscan.c)
588recent_scanned_anon VM internal parameter. (see mm/vmscan.c)
589recent_scanned_file VM internal parameter. (see mm/vmscan.c)
590========================= ========================================
591
592Memo:
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
597Note:
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
6085.3 swappiness
609--------------
610
611Overrides /proc/sys/vm/swappiness for the particular group. The tunable
612in the root cgroup corresponds to the global swappiness setting.
613
614Please note that unlike during the global reclaim, limit reclaim
615enforces that 0 swappiness really prevents from any swapping even if
616there is a swap storage available. This might lead to memcg OOM killer
617if there are no file pages to reclaim.
618
6195.4 failcnt
620-----------
621
622A memory cgroup provides memory.failcnt and memory.memsw.failcnt files.
623This failcnt(== failure count) shows the number of times that a usage counter
624hit its limit. When a memory cgroup hits a limit, failcnt increases and
625memory under it will be reclaimed.
626
627You can reset failcnt by writing 0 to failcnt file::
628
629 # echo 0 > .../memory.failcnt
630
6315.5 usage_in_bytes
632------------------
633
634For efficiency, as other kernel components, memory cgroup uses some optimization
635to avoid unnecessary cacheline false sharing. usage_in_bytes is affected by the
636method and doesn't show 'exact' value of memory (and swap) usage, it's a fuzz
637value for efficient access. (Of course, when necessary, it's synchronized.)
638If you want to know more exact memory usage, you should use RSS+CACHE(+SWAP)
639value in memory.stat(see 5.2).
640
6415.6 numa_stat
642-------------
643
644This is similar to numa_maps but operates on a per-memcg basis. This is
645useful for providing visibility into the numa locality information within
646an memcg since the pages are allowed to be allocated from any physical
647node. One of the use cases is evaluating application performance by
648combining this information with the application's CPU allocation.
649
650Each memcg's numa_stat file includes "total", "file", "anon" and "unevictable"
651per-node page counts including "hierarchical_<counter>" which sums up all
652hierarchical children's values in addition to the memcg's own value.
653
654The 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
662The "total" count is sum of file + anon + unevictable.
663
6646. Hierarchy support
665====================
666
667The memory controller supports a deep hierarchy and hierarchical accounting.
668The hierarchy is created by creating the appropriate cgroups in the
669cgroup filesystem. Consider for example, the following cgroup filesystem
670hierarchy::
671
672 root
673 / | \
674 / | \
675 a b c
676 | \
677 | \
678 d e
679
680In the diagram above, with hierarchical accounting enabled, all memory
681usage of e, is accounted to its ancestors up until the root (i.e, c and root),
682that has memory.use_hierarchy enabled. If one of the ancestors goes over its
683limit, the reclaim algorithm reclaims from the tasks in the ancestor and the
684children of the ancestor.
685
6866.1 Enabling hierarchical accounting and reclaim
687------------------------------------------------
688
689A memory cgroup by default disables the hierarchy feature. Support
690can be enabled by writing 1 to memory.use_hierarchy file of the root cgroup::
691
692 # echo 1 > memory.use_hierarchy
693
694The feature can be disabled by::
695
696 # echo 0 > memory.use_hierarchy
697
698NOTE1:
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
703NOTE2:
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
7077. Soft limits
708==============
709
710Soft limits allow for greater sharing of memory. The idea behind soft limits
711is to allow control groups to use as much of the memory as needed, provided
712
713a. There is no memory contention
714b. They do not exceed their hard limit
715
716When the system detects memory contention or low memory, control groups
717are pushed back to their soft limits. If the soft limit of each control
718group is very high, they are pushed back as much as possible to make
719sure that one control group does not starve the others of memory.
720
721Please note that soft limits is a best-effort feature; it comes with
722no guarantees, but it does its best to make sure that when memory is
723heavily contended for, memory is allocated based on the soft limit
724hints/setup. Currently soft limit based reclaim is set up such that
725it gets invoked from balance_pgdat (kswapd).
726
7277.1 Interface
728-------------
729
730Soft limits can be setup by using the following commands (in this example we
731assume a soft limit of 256 MiB)::
732
733 # echo 256M > memory.soft_limit_in_bytes
734
735If we want to change this to 1G, we can at any time use::
736
737 # echo 1G > memory.soft_limit_in_bytes
738
739NOTE1:
740 Soft limits take effect over a long period of time, since they involve
741 reclaiming memory for balancing between memory cgroups
742NOTE2:
743 It is recommended to set the soft limit always below the hard limit,
744 otherwise the hard limit will take precedence.
745
7468. Move charges at task migration
747=================================
748
749Users can move charges associated with a task along with task migration, that
750is, uncharge task's pages from the old cgroup and charge them to the new cgroup.
751This feature is not supported in !CONFIG_MMU environments because of lack of
752page tables.
753
7548.1 Interface
755-------------
756
757This feature is disabled by default. It can be enabled (and disabled again) by
758writing to memory.move_charge_at_immigrate of the destination cgroup.
759
760If you want to enable it::
761
762 # echo (some positive value) > memory.move_charge_at_immigrate
763
764Note:
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.
767Note:
768 Charges are moved only when you move mm->owner, in other words,
769 a leader of a thread group.
770Note:
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.
774Note:
775 It can take several seconds if you move charges much.
776
777And if you want disable it again::
778
779 # echo 0 > memory.move_charge_at_immigrate
780
7818.2 Type of charges which can be moved
782--------------------------------------
783
784Each bit in move_charge_at_immigrate has its own meaning about what type of
785charges should be moved. But in any case, it must be noted that an account of
786a 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
8058.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
8119. Memory thresholds
812====================
813
814Memory cgroup implements memory thresholds using the cgroups notification
815API (see cgroups.txt). It allows to register multiple memory and memsw
816thresholds and gets notifications when it crosses.
817
818To 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
825Application will be notified through eventfd when memory usage crosses
826threshold in any direction.
827
828It's applicable for root and non-root cgroup.
829
83010. OOM Control
831===============
832
833memory.oom_control file is for OOM notification and other controls.
834
835Memory cgroup implements OOM notifier using the cgroup notification
836API (See cgroups.txt). It allows to register multiple OOM notification
837delivery and gets notification when OOM happens.
838
839To 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
846The application will be notified through eventfd when OOM happens.
847OOM notification doesn't work for the root cgroup.
848
849You can disable the OOM-killer by writing "1" to memory.oom_control file, as:
850
851 #echo 1 > memory.oom_control
852
853If OOM-killer is disabled, tasks under cgroup will hang/sleep
854in memory cgroup's OOM-waitqueue when they request accountable memory.
855
856For running them, you have to relax the memory cgroup's OOM status by
857
858 * enlarge limit or reduce usage.
859
860To reduce usage,
861
862 * kill some tasks.
863 * move some tasks to other group with account migration.
864 * remove some files (on tmpfs?)
865
866Then, stopped tasks will work again.
867
868At 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
87511. Memory Pressure
876===================
877
878The pressure level notifications can be used to monitor the memory
879allocation cost; based on the pressure, applications can implement
880different strategies of managing their memory resources. The pressure
881levels are defined as following:
882
883The "low" level means that the system is reclaiming memory for new
884allocations. Monitoring this reclaiming activity might be useful for
885maintaining cache level. Upon notification, the program (typically
886"Activity Manager") might analyze vmstat and act in advance (i.e.
887prematurely shutdown unimportant services).
888
889The "medium" level means that the system is experiencing medium memory
890pressure, the system might be making swap, paging out active file caches,
891etc. Upon this event applications may decide to further analyze
892vmstat/zoneinfo/memcg or internal memory usage statistics and free any
893resources that can be easily reconstructed or re-read from a disk.
894
895The "critical" level means that the system is actively thrashing, it is
896about to out of memory (OOM) or even the in-kernel OOM killer is on its
897way to trigger. Applications should do whatever they can to help the
898system. It might be too late to consult with vmstat or any other
899statistics, so it's advisable to take an immediate action.
900
901By default, events are propagated upward until the event is handled, i.e. the
902events are not pass-through. For example, you have three cgroups: A->B->C. Now
903you set up an event listener on cgroups A, B and C, and suppose group C
904experiences some pressure. In this situation, only group C will receive the
905notification, i.e. groups A and B will not receive it. This is done to avoid
906excessive "broadcasting" of messages, which disturbs the system and which is
907especially bad if we are low on memory or thrashing. Group B, will receive
908notification only if there are no event listers for group C.
909
910There 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
929The level and event notification mode ("hierarchy" or "local", if necessary) are
930specified by a comma-delimited string, i.e. "low,hierarchy" specifies
931hierarchical, pass-through, notification for all ancestor memcgs. Notification
932that is the default, non pass-through behavior, does not specify a mode.
933"medium,local" specifies pass-through notification for the medium level.
934
935The file memory.pressure_level is only used to setup an eventfd. To
936register 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
943Application will be notified through eventfd when memory pressure is at
944the specific level (or higher). Read/write operations to
945memory.pressure_level are no implemented.
946
947Test:
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
96512. TODO
966========
967
9681. Make per-cgroup scanner reclaim not-shared pages first
9692. Teach controller to account for shared-pages
9703. Start reclamation in the background when the limit is
971 not yet hit but the usage is getting closer
972
973Summary
974=======
975
976Overall, the memory controller has been a stable controller and has been
977commented and discussed quite extensively in the community.
978
979References
980==========
981
9821. Singh, Balbir. RFC: Memory Controller, http://lwn.net/Articles/206697/
9832. Singh, Balbir. Memory Controller (RSS Control),
984 http://lwn.net/Articles/222762/
9853. Emelianov, Pavel. Resource controllers based on process cgroups
986 http://lkml.org/lkml/2007/3/6/198
9874. Emelianov, Pavel. RSS controller based on process cgroups (v2)
988 http://lkml.org/lkml/2007/4/9/78
9895. Emelianov, Pavel. RSS controller based on process cgroups (v3)
990 http://lkml.org/lkml/2007/5/30/244
9916. Menage, Paul. Control Groups v10, http://lwn.net/Articles/236032/
9927. Vaidyanathan, Srinivasan, Control Groups: Pagecache accounting and control
993 subsystem (v3), http://lwn.net/Articles/235534/
9948. Singh, Balbir. RSS controller v2 test results (lmbench),
995 http://lkml.org/lkml/2007/5/17/232
9969. Singh, Balbir. RSS controller v2 AIM9 results
997 http://lkml.org/lkml/2007/5/18/1
99810. Singh, Balbir. Memory controller v6 test results,
999 http://lkml.org/lkml/2007/8/19/36
100011. Singh, Balbir. Memory controller introduction (v6),
1001 http://lkml.org/lkml/2007/8/17/69
100212. 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=========================
2Network classifier cgroup
3=========================
4
5The Network classifier cgroup provides an interface to
6tag network packets with a class identifier (classid).
7
8The Traffic Controller (tc) can be used to assign
9different priorities to packets from different cgroups.
10Also, Netfilter (iptables) can use this tag to perform
11actions on such packets.
12
13Creating a net_cls cgroups instance creates a net_cls.classid file.
14This net_cls.classid value is initialized to 0.
15
16You can write hexadecimal values to net_cls.classid; the format for these
17values is 0xAAAABBBB; AAAA is the major handle number and BBBB
18is the minor handle number.
19Reading net_cls.classid yields a decimal result.
20
21Example::
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
42configuring 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=======================
2Network priority cgroup
3=======================
4
5The Network priority cgroup provides an interface to allow an administrator to
6dynamically set the priority of network traffic generated by various
7applications
8
9Nominally, an application would set the priority of its traffic via the
10SO_PRIORITY socket option. This however, is not always possible because:
11
121) The application may not have been coded to set this value
132) The priority of application traffic is often a site-specific administrative
14 decision rather than an application defined one.
15
16This cgroup allows an administrator to assign a process to a group which defines
17the priority of egress traffic on a given interface. Network priority groups can
18be created by first mounting the cgroup filesystem::
19
20 # mount -t cgroup -onet_prio none /sys/fs/cgroup/net_prio
21
22With the above step, the initial group acting as the parent accounting group
23becomes visible at '/sys/fs/cgroup/net_prio'. This group includes all tasks in
24the system. '/sys/fs/cgroup/net_prio/tasks' lists the tasks in this cgroup.
25
26Each net_prio cgroup contains two files that are subsystem specific
27
28net_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
33net_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
42This command would force any traffic originating from processes belonging to the
43iscsi net_prio cgroup and egressing on interface eth0 to have the priority of
44said traffic set to the value 5. The parent accounting group also has a
45writeable 'net_prio.ifpriomap' file that can be used to set a system default
46priority.
47
48Priorities are set immediately prior to queueing a frame to the device
49queueing discipline (qdisc) so priorities will be assigned prior to the hardware
50queue selection being made.
51
52One usage for the net_prio cgroup is with mqprio qdisc allowing application
53traffic to be steered to hardware/driver based traffic classes. These mappings
54can then be managed by administrators or other networking protocols such as
55DCBX.
56
57A new net_prio cgroup inherits the parent's configuration.
Documentation/admin-guide/cgroup-v1/pids.rst+92−0
@@ -0,0 +1,92 @@
1=========================
2Process Number Controller
3=========================
4
5Abstract
6--------
7
8The process number controller is used to allow a cgroup hierarchy to stop any
9new tasks from being fork()'d or clone()'d after a certain limit is reached.
10
11Since it is trivial to hit the task limit without hitting any kmemcg limits in
12place, PIDs are a fundamental resource. As such, PID exhaustion must be
13preventable in the scope of a cgroup hierarchy by allowing resource limiting of
14the number of tasks in a cgroup.
15
16Usage
17-----
18
19In order to use the `pids` controller, set the maximum number of tasks in
20pids.max (this is not available in the root cgroup for obvious reasons). The
21number of processes currently in the cgroup is given by pids.current.
22
23Organisational operations are not blocked by cgroup policies, so it is possible
24to have pids.current > pids.max. This can be done by either setting the limit to
25be smaller than pids.current, or attaching enough processes to the cgroup such
26that pids.current > pids.max. However, it is not possible to violate a cgroup
27policy through fork() or clone(). fork() and clone() will return -EAGAIN if the
28creation of a new process would cause a cgroup policy to be violated.
29
30To set a cgroup to have no limit, set pids.max to "max". This is the default for
31all new cgroups (N.B. that PID limits are hierarchical, so the most stringent
32limit in the hierarchy is followed).
33
34pids.current tracks all child cgroup hierarchies, so parent/pids.current is a
35superset of parent/child/pids.current.
36
37The pids.events file contains event counters:
38
39 - max: Number of times fork failed because limit was hit.
40
41Example
42-------
43
44First, 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
49Then 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
58It should be noted that attempts to overcome the set limit (2 in this case) will
59fail::
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
67Even if we migrate to a child cgroup (which doesn't have a set limit), we will
68not be able to overcome the most stringent limit in the hierarchy (in this case,
69parent'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
82We can set a limit that is smaller than pids.current, which will stop any new
83processes from being forked at all (note that the shell itself counts towards
84pids.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===============
2RDMA 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
131. Overview
14===========
15
161-1. What is RDMA controller?
17-----------------------------
18
19RDMA controller allows user to limit RDMA/IB specific resources that a given
20set of processes can use. These processes are grouped using RDMA controller.
21
22RDMA controller defines two resources which can be limited for processes of a
23cgroup.
24
251-2. Why RDMA controller needed?
26--------------------------------
27
28Currently user space applications can easily take away all the rdma verb
29specific resources such as AH, CQ, QP, MR etc. Due to which other applications
30in other cgroup or kernel space ULPs may not even get chance to allocate any
31rdma resources. This can lead to service unavailability.
32
33Therefore RDMA controller is needed through which resource consumption
34of processes can be limited. Through this controller different rdma
35resources can be accounted.
36
371-3. How is RDMA controller implemented?
38----------------------------------------
39
40RDMA cgroup allows limit configuration of resources. Rdma cgroup maintains
41resource accounting per cgroup, per device using resource pool structure.
42Each such resource pool is limited up to 64 resources in given resource pool
43by rdma cgroup, which can be extended later if required.
44
45This resource pool object is linked to the cgroup css. Typically there
46are 0 to 4 resource pool instances per cgroup, per device in most use cases.
47But nothing limits to have it more. At present hundreds of RDMA devices per
48single cgroup may not be handled optimally, however there is no
49known use case or requirement for such configuration either.
50
51Since RDMA resources can be allocated from any process and can be freed by any
52of the child processes which shares the address space, rdma resources are
53always owned by the creator cgroup css. This allows process migration from one
54to other cgroup without major complexity of transferring resource ownership;
55because such ownership is not really present due to shared nature of
56rdma resources. Linking resources around css also ensures that cgroups can be
57deleted after processes migrated. This allow progress migration as well with
58active resources, even though that is not a primary use case.
59
60Whenever RDMA resource charging occurs, owner rdma cgroup is returned to
61the caller. Same rdma cgroup should be passed while uncharging the resource.
62This also allows process migrated with active RDMA resource to charge
63to new owner cgroup for new resource. It also allows to uncharge resource of
64a process from previously charged cgroup which is migrated to new cgroup,
65even though that is not a primary use case.
66
67Resource pool object is created in following situations.
68(a) User sets the limit and no previous resource pool exist for the device
69of interest for the cgroup.
70(b) No resource limits were configured, but IB/RDMA stack tries to
71charge the resource. So that it correctly uncharge them when applications are
72running without limits and later on when limits are enforced during uncharging,
73otherwise usage count will drop to negative.
74
75Resource pool is destroyed if all the resource limits are set to max and
76it is the last resource getting deallocated.
77
78User should set all the limit to max value if it intents to remove/unconfigure
79the resource pool for a particular device.
80
81IB stack honors limits enforced by the rdma controller. When application
82query about maximum resource limits of IB device, it returns minimum of
83what is configured by user for a given cgroup and what is supported by
84IB device.
85
86Following 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
932. 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
9conventions of cgroup v2. It describes all userland-visible aspects9conventions of cgroup v2. It describes all userland-visible aspects
10of cgroup including core and specific controller behaviors. All10of cgroup including core and specific controller behaviors. All
11future changes must be reflected in this document. Documentation for11future changes must be reflected in this document. Documentation for
12v1 is available under Documentation/cgroup-v1/.12v1 is available under Documentation/admin-guide/cgroup-v1/.
13 13
14.. CONTENTS14.. CONTENTS
15 15
@@ -705,6 +705,12 @@ Conventions · 689 unmodified lines
705 informational files on the root cgroup which end up showing global705 informational files on the root cgroup which end up showing global
706 information available elsewhere shouldn't exist.706 information available elsewhere shouldn't exist.
707 707
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
708- If a controller implements weight based resource distribution, its714- If a controller implements weight based resource distribution, its
709 interface file should be named "weight" and have the range [1,715 interface file should be named "weight" and have the range [1,
710 10000] with 100 as the default. The values are chosen to allow716 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
1008 A read-only nested-key file which exists on non-root cgroups.1014 A read-only nested-key file which exists on non-root cgroups.
1009 1015
1010 Shows pressure stall information for CPU. See1016 Shows pressure stall information for CPU. See
1011 Documentation/accounting/psi.txt for details.1017 Documentation/accounting/psi.rst for details.
1012 1018
1013 1019
1014Memory1020Memory
@@ -1140,6 +1146,11 @@ PAGE_SIZE multiple when read back. · 125 unmodified lines
1140 otherwise, a value change in this file generates a file1146 otherwise, a value change in this file generates a file
1141 modified event.1147 modified event.
1142 1148
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
1143 low1154 low
1144 The number of times the cgroup is reclaimed due to1155 The number of times the cgroup is reclaimed due to
1145 high memory pressure even though its usage is under1156 high memory pressure even though its usage is under
@@ -1179,6 +1190,11 @@ PAGE_SIZE multiple when read back. · 33 unmodified lines
1179 The number of processes belonging to this cgroup1190 The number of processes belonging to this cgroup
1180 killed by any kind of OOM killer.1191 killed by any kind of OOM killer.
1181 1192
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
1182 memory.stat1198 memory.stat
1183 A read-only flat-keyed file which exists on non-root cgroups.1199 A read-only flat-keyed file which exists on non-root cgroups.
1184 1200
@@ -1339,7 +1355,7 @@ PAGE_SIZE multiple when read back. · 154 unmodified lines
1339 A read-only nested-key file which exists on non-root cgroups.1355 A read-only nested-key file which exists on non-root cgroups.
1340 1356
1341 Shows pressure stall information for memory. See1357 Shows pressure stall information for memory. See
1342 Documentation/accounting/psi.txt for details.1358 Documentation/accounting/psi.rst for details.
1343 1359
1344 1360
1345Usage Guidelines1361Usage Guidelines
@@ -1482,7 +1498,7 @@ IO Interface Files · 136 unmodified lines
1482 A read-only nested-key file which exists on non-root cgroups.1498 A read-only nested-key file which exists on non-root cgroups.
1483 1499
1484 Shows pressure stall information for IO. See1500 Shows pressure stall information for IO. See
1485 Documentation/accounting/psi.txt for details.1501 Documentation/accounting/psi.rst for details.
1486 1502
1487 1503
1488Writeback1504Writeback
@@ -2108,7 +2124,7 @@ following two functions. · 619 unmodified lines
2108 a queue (device) has been associated with the bio and2124 a queue (device) has been associated with the bio and
2109 before submission.2125 before submission.
2110 2126
2111 wbc_account_io(@wbc, @page, @bytes)2127 wbc_account_cgroup_owner(@wbc, @page, @bytes)
2112 Should be called for each data segment being written out.2128 Should be called for each data segment being written out.
2113 While this function doesn't care exactly when it's called2129 While this function doesn't care exactly when it's called
2114 during the writeback session, it's the easiest and most2130 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
3project = 'Linux Kernel User Documentation'
4
5tags.add("subproject")
6
7latex_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===========================================
2How CPU topology info is exported via sysfs
3===========================================
4
5Export CPU topology info via sysfs. Items (attributes) are similar
6to /proc/cpuinfo output of some architectures. They reside in
7/sys/devices/system/cpu/cpuX/topology/:
8
9physical_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
15die_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
21core_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
27book_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
33drawer_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
39core_cpus:
40
41 internal kernel map of CPUs within the same core.
42 (deprecated name: "thread_siblings")
43
44core_cpus_list:
45
46 human-readable list of CPUs within the same core.
47 (deprecated name: "thread_siblings_list");
48
49package_cpus:
50
51 internal kernel map of the CPUs sharing the same physical_package_id.
52 (deprecated name: "core_siblings")
53
54package_cpus_list:
55
56 human-readable list of CPUs sharing the same physical_package_id.
57 (deprecated name: "core_siblings_list")
58
59die_cpus:
60
61 internal kernel map of CPUs within the same die.
62
63die_cpus_list:
64
65 human-readable list of CPUs within the same die.
66
67book_siblings:
68
69 internal kernel map of cpuX's hardware threads within the same
70 book_id.
71
72book_siblings_list:
73
74 human-readable list of cpuX's hardware threads within the same
75 book_id.
76
77drawer_siblings:
78
79 internal kernel map of cpuX's hardware threads within the same
80 drawer_id.
81
82drawer_siblings_list:
83
84 human-readable list of cpuX's hardware threads within the same
85 drawer_id.
86
87Architecture-neutral, drivers/base/topology.c, exports these attributes.
88However, the book and drawer related sysfs files will only be created if
89CONFIG_SCHED_BOOK and CONFIG_SCHED_DRAWER are selected, respectively.
90
91CONFIG_SCHED_BOOK and CONFIG_SCHED_DRAWER are currently only used on s390,
92where they reflect the cpu and cache hierarchy.
93
94For an architecture to support this feature, it must define some of
95these 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
108The type of ``**_id macros`` is int.
109The type of ``**_cpumask macros`` is ``(const) struct cpumask *``. The latter
110correspond with appropriate ``**_siblings`` sysfs attributes (except for
111topology_sibling_cpumask() which corresponds with thread_siblings).
112
113To be consistent on all architectures, include/linux/topology.h
114provides default definitions for any of the above macros that are
115not defined by include/asm-XXX/topology.h:
116
1171) topology_physical_package_id: -1
1182) topology_die_id: -1
1193) topology_core_id: 0
1204) topology_sibling_cpumask: just the given CPU
1215) topology_core_cpumask: just the given CPU
1226) topology_die_cpumask: just the given CPU
123
124For architectures that don't support books (CONFIG_SCHED_BOOK) there are no
125default definitions for topology_book_id() and topology_book_cpumask().
126For architectures that don't support drawers (CONFIG_SCHED_DRAWER) there are
127no default definitions for topology_drawer_id() and topology_drawer_cpumask().
128
129Additionally, CPU topology information is provided under
130/sys/devices/system/cpu and includes these files. The internal
131source 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
151The format for the above output is compatible with cpulist_parse()
152[see <linux/cpumask.h>]. Some examples follow.
153
154In this example, there are 64 CPUs in the system but cpus 32-63 exceed
155the kernel max which is limited to 0..31 by the NR_CPUS config option
156being 32. Note also that CPUs 2 and 4-31 are not online but could be
157brought 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
165In this example, the NR_CPUS config option is 128, but the kernel was
166started with possible_cpus=144. There are 4 CPUs in the system and cpu2
167was manually taken offline (and is the only CPU that can be brought
168online.)::
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
176See cpu-hotplug.txt for the possible_cpus=NUM kernel start parameter
177as well as more information on the various cpumasks.
Documentation/admin-guide/device-mapper/cache-policies.rst+131−0
@@ -0,0 +1,131 @@
1=============================
2Guidance for writing policies
3=============================
4
5Try to keep transactionality out of it. The core is careful to
6avoid asking about anything that is migrating. This is a pain, but
7makes it easier to write the policies.
8
9Mappings are loaded into the policy at construction time.
10
11Every bio that is mapped by the target is referred to the policy.
12The policy can return a simple HIT or MISS or issue a migration.
13
14Currently there's no way for the policy to issue background work,
15e.g. to start writing back dirty blocks that are going to be evicted
16soon.
17
18Because we map bios, rather than requests it's easy for the policy
19to get fooled by many small bios. For this reason the core target
20issues periodic ticks to the policy. It's suggested that the policy
21doesn't update states (eg, hit counts) for a block more than once
22for each tick. The core ticks by watching bios complete, and so
23trying to see when the io scheduler has let the ios run.
24
25
26Overview of supplied cache replacement policies
27===============================================
28
29multiqueue (mq)
30---------------
31
32This policy is now an alias for smq (see below).
33
34The 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
42Stochastic multiqueue (smq)
43---------------------------
44
45This policy is the default.
46
47The stochastic multi-queue (smq) policy addresses some of the problems
48with the multiqueue (mq) policy.
49
50The smq policy (vs mq) offers the promise of less memory utilization,
51improved performance and increased adaptability in the face of changing
52workloads. smq also does not have any cumbersome tuning knobs.
53
54Users may switch from "mq" to "smq" simply by appropriately reloading a
55DM table that is using the cache target. Doing so will cause all of the
56mq policy's hints to be dropped. Also, performance of the cache may
57degrade slightly until smq recalculates the origin device's hotspots
58that should be cached.
59
60Memory usage
61^^^^^^^^^^^^
62
63The mq policy used a lot of memory; 88 bytes per cache block on a 64
64bit machine.
65
66smq uses 28bit indexes to implement its data structures rather than
67pointers. It avoids storing an explicit hit count for each block. It
68has a 'hotspot' queue, rather than a pre-cache, which uses a quarter of
69the entries (each hotspot block covers a larger area than a single
70cache block).
71
72All this means smq uses ~25bytes per cache block. Still a lot of
73memory, but a substantial improvement nontheless.
74
75Level balancing
76^^^^^^^^^^^^^^^
77
78mq placed entries in different levels of the multiqueue structures
79based on their hit count (~ln(hit count)). This meant the bottom
80levels generally had the most entries, and the top ones had very
81few. Having unbalanced levels like this reduced the efficacy of the
82multiqueue.
83
84smq does not maintain a hit count, instead it swaps hit entries with
85the least recently used entry from the level above. The overall
86ordering being a side effect of this stochastic process. With this
87scheme we can decide how many entries occupy each multiqueue level,
88resulting in better promotion/demotion decisions.
89
90Adaptability:
91The mq policy maintained a hit count for each cache block. For a
92different block to get promoted to the cache its hit count has to
93exceed the lowest currently in the cache. This meant it could take a
94long time for the cache to adapt between varying IO patterns.
95
96smq doesn't maintain hit counts, so a lot of this problem just goes
97away. In addition it tracks performance of the hotspot queue, which
98is used to decide which blocks to promote. If the hotspot queue is
99performing badly then it starts moving entries more quickly between
100levels. This lets it adapt to new IO patterns very quickly.
101
102Performance
103^^^^^^^^^^^
104
105Testing smq shows substantially better performance than mq.
106
107cleaner
108-------
109
110The cleaner writes back all dirty blocks in a cache to decommission it.
111
112Examples
113========
114
115The 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
121The 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
126Using 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=====
2Cache
3=====
4
5Introduction
6============
7
8dm-cache is a device mapper target written by Joe Thornber, Heinz
9Mauelshagen, and Mike Snitzer.
10
11It aims to improve performance of a block device (eg, a spindle) by
12dynamically migrating some of its data to a faster, smaller device
13(eg, an SSD).
14
15This device-mapper solution allows us to insert this caching at
16different levels of the dm stack, for instance above the data device for
17a thin-provisioning pool. Caching solutions that are integrated more
18closely with the virtual memory system should give better performance.
19
20The target reuses the metadata library used in the thin-provisioning
21library.
22
23The decision as to what data to migrate and when is left to a plug-in
24policy module. Several of these have been written as we experiment,
25and we hope other people will contribute others for specific io
26scenarios (eg. a vm image server).
27
28Glossary
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
39The origin device always contains a copy of the logical block, which
40may be out of date or kept in sync with the copy on the cache device
41(depending on policy).
42
43Design
44======
45
46Sub-devices
47-----------
48
49The target is constructed by passing three devices to it (along with
50other parameters detailed later):
51
521. An origin device - the big, slow one.
53
542. A cache device - the small, fast one.
55
563. 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
63Fixed block size
64----------------
65
66The origin is divided up into blocks of a fixed size. This block size
67is configurable when you first create the cache. Typically we've been
68using block sizes of 256KB - 1024KB. The block size must be between 64
69sectors (32KB) and 2097152 sectors (1GB) and a multiple of 64 sectors (32KB).
70
71Having a fixed block size simplifies the target a lot. But it is
72something of a compromise. For instance, a small part of a block may be
73getting hit a lot, yet the whole block will be promoted to the cache.
74So large block sizes are bad because they waste cache space. And small
75block sizes are bad because they increase the amount of metadata (both
76in core and on disk).
77
78Cache operating modes
79---------------------
80
81The cache has three operating modes: writeback, writethrough and
82passthrough.
83
84If writeback, the default, is selected then a write to a block that is
85cached will go only to the cache and the block will be marked dirty in
86the metadata.
87
88If writethrough is selected then a write to a cached block will not
89complete until it has hit both the origin and cache devices. Clean
90blocks should remain clean.
91
92If passthrough is selected, useful when the cache contents are not known
93to be coherent with the origin device, then all reads are served from
94the origin device (all reads miss the cache) and all writes are
95forwarded to the origin device; additionally, write hits cause cache
96block invalidates. To enable passthrough mode the cache must be clean.
97Passthrough mode allows a cache device to be activated without having to
98worry about coherency. Coherency that exists is maintained, although
99the cache will gradually cool as writes take place. If the coherency of
100the cache can later be verified, or established through use of the
101"invalidate_cblocks" message, the cache device can be transitioned to
102writethrough or writeback mode while still warm. Otherwise, the cache
103contents can be discarded prior to transitioning to the desired
104operating mode.
105
106A simple cleaner policy is provided, which will clean (write back) all
107dirty blocks in a cache. Useful for decommissioning a cache or when
108shrinking a cache. Shrinking the cache's fast device requires all cache
109blocks, in the area of the cache being removed, to be clean. If the
110area being removed from the cache still contains dirty blocks the resize
111will fail. Care must be taken to never reduce the volume used for the
112cache's fast device until the cache is clean. This is of particular
113importance if writeback mode is used. Writethrough and passthrough
114modes already maintain a clean cache. Future support to partially clean
115the cache, above a specified threshold, will allow for keeping the cache
116warm and in writeback mode during resize.
117
118Migration throttling
119--------------------
120
121Migrating data between the origin and cache device uses bandwidth.
122The user can set a throttle to prevent more than a certain amount of
123migration occurring at any one time. Currently we're not taking any
124account of normal io traffic going to the devices. More work needs
125doing here to avoid migrating during those peak io moments.
126
127For the time being, a message "migration_threshold <#sectors>"
128can be used to set the maximum number of sectors being migrated,
129the default being 2048 sectors (1MB).
130
131Updating on-disk metadata
132-------------------------
133
134On-disk metadata is committed every time a FLUSH or FUA bio is written.
135If no such requests are made then commits will occur every second. This
136means the cache behaves like a physical disk that has a volatile write
137cache. If power is lost you may lose some recent writes. The metadata
138should always be consistent in spite of any crash.
139
140The 'dirty' state for a cache block changes far too frequently for us
141to keep updating it on the fly. So we treat it as a hint. In normal
142operation it will be written when the dm device is suspended. If the
143system crashes all cache blocks will be assumed dirty when restarted.
144
145Per-block policy hints
146----------------------
147
148Policy plug-ins can store a chunk of data per cache block. It's up to
149the policy how big this chunk is, but it should be kept small. Like the
150dirty flags this data is lost if there's a crash so a safe fallback
151value should always be possible.
152
153Policy hints affect performance, not correctness.
154
155Policy messaging
156----------------
157
158Policies will have different tunables, specific to each one, so we
159need a generic way of getting and setting these. Device-mapper
160messages are used. Refer to cache-policies.txt.
161
162Discard bitset resolution
163-------------------------
164
165We can avoid copying data during migration if we know the block has
166been discarded. A prime example of this is when mkfs discards the
167whole block device. We store a bitset tracking the discard state of
168blocks. However, we allow this bitset to have a different block size
169from the cache blocks. This is because we need to track the discard
170state for all of the origin device (compare with the dirty bitset
171which is just for the smaller cache device).
172
173Target interface
174================
175
176Constructor
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
202Optional 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
227A policy called 'default' is always registered. This is an alias for
228the policy we currently think is giving best all round performance.
229
230As the default policy could vary between kernels, if you are relying on
231the characteristics of a specific policy, always request it by name.
232
233Status
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========================= =====================================================
247metadata 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
251cache 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
270feature args 'writethrough' (optional)
271#core args Number of core arguments (must be even)
272core args Key/value pairs for tuning the core
273 e.g. migration_threshold
274policy name Name of the policy
275#policy args Number of policy arguments to follow (must be even)
276policy args Key/value pairs e.g. sequential_threshold
277cache 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.
283needs_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
292Messages
293--------
294
295Policies will have different tunables, specific to each one, so we
296need a generic way of getting and setting these. Device-mapper
297messages are used. (A sysfs interface would also be possible.)
298
299The message format is::
300
301 <key> <value>
302
303E.g.::
304
305 dmsetup message my_cache 0 sequential_threshold 1024
306
307
308Invalidation is removing an entry from the cache without writing it
309back. Cache blocks can be invalidated via the invalidate_cblocks
310message, which takes an arbitrary number of cblock ranges. Each cblock
311range's end value is "one past the end", meaning 5-10 expresses a range
312of values from 5 to 9. Each cblock must be expressed as a decimal
313value, in the future a variant message that takes cblock ranges
314expressed in hexadecimal may be needed to better support efficient
315invalidation of larger caches. The cache must be in passthrough mode
316when invalidate_cblocks is used::
317
318 invalidate_cblocks [<cblock>|<cblock begin>-<cblock end>]*
319
320E.g.::
321
322 dmsetup message my_cache 0 invalidate_cblocks 2345 3456-4567 5678-6789
323
324Examples
325========
326
327The test suite can be found here:
328
329https://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========
2dm-delay
3========
4
5Device-Mapper's "delay" target delays reads and/or writes
6and maps them to different devices.
7
8Parameters::
9
10 <device> <offset> <delay> [<write_device> <write_offset> <write_delay>
11 [<flush_device> <flush_offset> <flush_delay>]]
12
13With separate write parameters, the first set is only used for reads.
14Offsets are specified in sectors.
15Delays are specified in milliseconds.
16
17Example 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========
2dm-crypt
3========
4
5Device-Mapper's "crypt" target provides transparent encryption of block devices
6using the kernel crypto API.
7
8For a more detailed description of supported parameters see:
9https://gitlab.com/cryptsetup/cryptsetup/wikis/DMCrypt
10
11Parameters::
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
101allow_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
111same_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
116submit_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
124integrity:<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
136sector_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
141iv_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
150Example scripts
151===============
152LUKS (Linux Unified Key Setup) is now the preferred way to set up disk
153encryption with dm-crypt using the 'cryptsetup' utility, see
154https://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=========
2dm-flakey
3=========
4
5This target is the same as the linear target except that it exhibits
6unreliable behaviour periodically. It's been found useful in simulating
7failing devices for testing purposes.
8
9Starting from the time the table is loaded, the device is available for
10<up interval> seconds, then exhibits unreliable behaviour for <down
11interval> seconds, and then this cycle repeats.
12
13Also, consider using this in combination with the dm-delay target too,
14which can delay reads and writes and/or send them to different
15underlying devices.
16
17Table parameters
18----------------
19
20::
21
22 <dev path> <offset> <up interval> <down interval> \
23 [<num_features> [<feature arguments>]]
24
25Mandatory 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
37Optional 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
66Examples:
67
68Replaces the 32nd byte of READ bios with the value 1::
69
70 corrupt_bio_byte 32 r 1 0
71
72Replaces 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================================
2Early creation of mapped devices
3================================
4
5It is possible to configure a device-mapper device to act as the root device for
6your system in two ways.
7
8The first is to build an initial ramdisk which boots to a minimal userspace
9which configures the device, then pivot_root(8) in to it.
10
11The 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
14The format is specified as a string of data separated by commas and optionally
15semi-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
21So the format will look like this::
22
23 dm-mod.create=<name>,<uuid>,<minor>,<flags>,<table>[,<table>+][;<name>,<uuid>,<minor>,<flags>,<table>[,<table>+]+]
24
25Where::
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
34The dm line should be equivalent to the one used by the dmsetup tool with the
35`--concise` argument.
36
37Target types
38============
39
40Not all target types are available as there are serious risks in allowing
41activation of certain DM targets without first using userspace tools to check
42the 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
66If the target is not listed above, it is constrained by default (not tested).
67
68Examples
69========
70An example of booting to a linear array made up of user-mode linux block
71devices::
72
73 dm-mod.create="lroot,,,rw, 0 4096 linear 98:16 0, 4096 4096 linear 98:32 0" root=/dev/dm-0
74
75This will boot to a rw dm-linear target of 8192 sectors split across two block
76devices identified by their major:minor numbers. After boot, udev will rename
77this target to /dev/mapper/lroot (depending on the rules). No uuid was assigned.
78
79An example of multiple device-mappers, with the dm-mod.create="..." contents
80is 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
90Other 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============
2dm-integrity
3============
4
5The dm-integrity target emulates a block device that has additional
6per-sector tags that can be used for storing integrity information.
7
8A general problem with storing integrity tags with every sector is that
9writing the sector and the integrity tag must be atomic - i.e. in case of
10crash, either both sector and integrity tag or none of them is written.
11
12To guarantee write atomicity, the dm-integrity target uses journal, it
13writes sector data and integrity tags into a journal, commits the journal
14and then copies the data and integrity tags to their respective location.
15
16The dm-integrity target can be used with the dm-crypt target - in this
17situation the dm-crypt target creates the integrity data and passes them
18to the dm-integrity target via bio_integrity_payload attached to the bio.
19In this mode, the dm-crypt and dm-integrity targets provide authenticated
20disk encryption - if the attacker modifies the encrypted device, an I/O
21error is returned instead of random data.
22
23The dm-integrity target can also be used as a standalone target, in this
24mode it calculates and verifies the integrity tag internally. In this
25mode, the dm-integrity target can be used to detect silent data
26corruption on the disk or in the I/O path.
27
28There's an alternate mode of operation where dm-integrity uses bitmap
29instead of a journal. If a bit in the bitmap is 1, the corresponding
30region's data and integrity tags are not synchronized - if the machine
31crashes, the unsynchronized regions will be recalculated. The bitmap mode
32is faster than the journal mode, because we don't have to write the data
33twice, but it is also less reliable, because if data corruption happens
34when the machine crashes, it may not be detected.
35
36When loading the target for the first time, the kernel driver will format
37the device. But it will only format the device if the superblock contains
38zeroes. If the superblock is neither valid nor zeroed, the dm-integrity
39target can't be loaded.
40
41To use the target for the first time:
42
431. overwrite the superblock with zeroes
442. load the dm-integrity target with one-sector size, the kernel driver
45 will format the device
463. unload the dm-integrity target
474. read the "provided_data_sectors" value from the superblock
485. load the dm-integrity target with the the target size
49 "provided_data_sectors"
506. if you want to use dm-integrity with dm-crypt, load the dm-crypt target
51 with the size "provided_data_sectors"
52
53
54Target arguments:
55
561. the underlying block device
57
582. the number of reserved sector at the beginning of the device - the
59 dm-integrity won't read of write these sectors
60
613. the size of the integrity tag (if "-" is used, the size is taken from
62 the internal-hash algorithm)
63
644. 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
875. the number of additional arguments
88
89Additional arguments:
90
91journal_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
96interleave_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
101meta_device:device
102 Don't interleave the data and metadata on on device. Use a
103 separate device for metadata.
104
105buffer_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
113journal_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
118commit_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
123internal_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
139recalculate
140 Recalculate the integrity tags automatically. It is only valid
141 when using internal hash.
142
143journal_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
155journal_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
166block_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
172sectors_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
176bitmap_flush_interval:number
177 The bitmap flush interval in milliseconds. The metadata buffers
178 are synchronized when this interval expires.
179
180
181The journal mode (D/J), buffer_sectors, journal_watermark, commit_time can
182be changed when reloading the target (load an inactive table and swap the
183tables with suspend and resume). The other arguments should not be changed
184when reloading the target because the layout of disk data depend on them
185and the reloaded target would be non-functional.
186
187
188The 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=====
2dm-io
3=====
4
5Dm-io provides synchronous and asynchronous I/O services. There are three
6types of I/O services available, and each type has a sync and an async
7version.
8
9The user must set up an io_region structure to describe the desired location
10of the I/O. Each io_region indicates a block-device along with the starting
11sector 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
19Dm-io can read from one io_region or write to one or more io_regions. Writes
20to multiple regions are specified by an array of io_region structures.
21
22The first I/O service type takes a list of memory pages as the data buffer for
23the 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
37The second I/O service type takes an array of bio vectors as the data buffer
38for the I/O. This service can be handy if the caller has a pre-assembled bio,
39but 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
48The third I/O service type takes a pointer to a vmalloc'd memory buffer as the
49data buffer for the I/O. This service can be handy if the caller needs to do
50I/O to a large region but doesn't want to allocate a large number of individual
51memory 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
58Callers of the asynchronous I/O services must include the name of a completion
59callback 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
63The "error" parameter in this callback, as well as the `*error` parameter in
64all of the synchronous versions, is a bitset (instead of a simple error value).
65In the case of an write-I/O to multiple regions, this bitset allows dm-io to
66indicate success or failure on each individual region.
67
68Before using any of the dm-io services, the user should call dm_io_get()
69and specify the number of pages they expect to perform I/O on concurrently.
70Dm-io will attempt to resize its mempool to make sure enough pages are
71always available in order to avoid unnecessary waiting while performing I/O.
72
73When the user is finished using the dm-io services, they should call
74dm_io_put() and specify the same number of pages that were given on the
75dm_io_get() call.
Documentation/admin-guide/device-mapper/dm-log.rst+57−0
@@ -0,0 +1,57 @@
1=====================
2Device-Mapper Logging
3=====================
4The device-mapper logging code is used by some of the device-mapper
5RAID targets to track regions of the disk that are not consistent.
6A region (or portion of the address space) of the disk may be
7inconsistent because a RAID stripe is currently being operated on or
8a machine died while the region was being altered. In the case of
9mirrors, a region would be considered dirty/inconsistent while you
10are writing to it because the writes need to be replicated for all
11the legs of the mirror and may not reach the legs at the same time.
12Once all writes are complete, the region is considered clean again.
13
14There is a generic logging interface that the device-mapper RAID
15implementations use to perform logging operations (see
16dm_dirty_log_type in include/linux/dm-dirty-log.h). Various different
17logging implementations are available and provide different
18capabilities. The list includes:
19
20============== ==============================================================
21Type Files
22============== ==============================================================
23disk drivers/md/dm-log.c
24core drivers/md/dm-log.c
25userspace drivers/md/dm-log-userspace* include/linux/dm-log-userspace.h
26============== ==============================================================
27
28The "disk" log type
29-------------------
30This log implementation commits the log state to disk. This way, the
31logging state survives reboots/crashes.
32
33The "core" log type
34-------------------
35This log implementation keeps the log state in memory. The log state
36will not survive a reboot or crash, but there may be a small boost in
37performance. This method can also be used if no storage device is
38available for storing log state.
39
40The "userspace" log type
41------------------------
42This log type simply provides a way to export the log API to userspace,
43so log implementations can be done there. This is done by forwarding most
44logging requests to userspace, where a daemon receives and processes the
45request.
46
47The structure used for communication between kernel and userspace are
48located in include/linux/dm-log-userspace.h. Due to the frequency,
49diversity, and 2-way communication nature of the exchanges between
50kernel and userspace, 'connector' is used as the interface for
51communication.
52
53There are currently two userspace log implementations that leverage this
54framework - "clustered-disk" and "clustered-core". These implementations
55provide a cluster-coherent log for shared-storage. Device-mapper mirroring
56can be used in a shared-storage environment when the cluster log implementations
57are employed.
Documentation/admin-guide/device-mapper/dm-queue-length.rst+48−0
@@ -0,0 +1,48 @@
1===============
2dm-queue-length
3===============
4
5dm-queue-length is a path selector module for device-mapper targets,
6which selects a path with the least number of in-flight I/Os.
7The path selector name is 'queue-length'.
8
9Table 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
18Status 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
27Algorithm
28=========
29
30dm-queue-length increments/decrements 'in-flight' when an I/O is
31dispatched/completed respectively.
32dm-queue-length selects a path with the minimum 'in-flight'.
33
34
35Examples
36========
37In 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=======
2dm-raid
3=======
4
5The device-mapper RAID (dm-raid) target provides a bridge from DM to MD.
6It allows the MD RAID drivers to be accessed using a device-mapper
7interface.
8
9
10Mapping Table Interface
11-----------------------
12The 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
228Example 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
251Status Output
252-------------
253'dmsetup table' displays the table used to construct the mapping.
254The optional parameters are always printed in the order listed
255above with "sync" or "nosync" always output ahead of the other
256arguments, regardless of the order used when originally loading the table.
257Arguments that can be repeated are ordered by value.
258
259
260'dmsetup status' yields information on the state and health of the array.
261The output is as follows (normally a single line, but expanded here for
262clarity)::
263
264 1: <s> <l> raid \
265 2: <raid_type> <#devices> <health_chars> \
266 3: <sync_ratio> <sync_action> <mismatch_cnt>
267
268Line 1 is the standard output produced by device-mapper.
269
270Line 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
274Here we can see the RAID type is raid4, there are 5 devices - all of
275which are 'A'live, and the array is 2/490221568 complete with its initial
276recovery. 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
328Message Interface
329-----------------
330The dm-raid target will accept certain actions through the 'message' interface.
331('man dmsetup' for more information on the message interface.) These actions
332include:
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
344Discard Support
345---------------
346The implementation of discard support among hardware vendors varies.
347When a block is discarded, some storage devices will return zeroes when
348the block is read. These devices set the 'discard_zeroes_data'
349attribute. Other devices will return random data. Confusingly, some
350devices that advertise 'discard_zeroes_data' will not reliably return
351zeroes when discarded blocks are read! Since RAID 4/5/6 uses blocks
352from a number of devices to calculate parity blocks and (for performance
353reasons) relies on 'discard_zeroes_data' being reliable, it is important
354that the devices be consistent. Blocks may be discarded in the middle
355of a RAID 4/5/6 stripe and if subsequent read results are not
356consistent, the parity blocks may be calculated differently at any time;
357making the parity blocks useless for redundancy. It is important to
358understand how your hardware behaves with discards if you are going to
359enable discards with RAID 4/5/6.
360
361Since the behavior of storage devices is unreliable in this respect,
362even when reporting 'discard_zeroes_data', by default RAID 4/5/6
363discard support is disabled -- this ensures data integrity at the
364expense of losing some performance.
365
366Storage devices that properly support 'discard_zeroes_data' are
367increasingly whitelisted in the kernel and can thus be trusted.
368
369For trusted devices, the following dm-raid module parameter can be set
370to safely enable discard support for RAID 4/5/6:
371
372 'devices_handle_discards_safely'
373
374
375Version 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===============
2dm-service-time
3===============
4
5dm-service-time is a path selector module for device-mapper targets,
6which selects a path with the shortest estimated service time for
7the incoming I/O.
8
9The service time for each path is estimated by dividing the total size
10of in-flight I/Os on a path with the performance value of the path.
11The performance value is a relative throughput value among all paths
12in a path-group, and it can be specified as a table argument.
13
14The path selector name is 'service-time'.
15
16Table 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
32Status 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
46Algorithm
47=========
48
49dm-service-time adds the I/O size to 'in-flight-size' when the I/O is
50dispatched and subtracts when completed.
51Basically, dm-service-time selects a path having minimum service time
52which is calculated by::
53
54 ('in-flight-size' + 'size-of-incoming-io') / 'relative_throughput'
55
56However, some optimizations below are used to reduce the calculation
57as 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
69If such optimizations can't be applied, calculate service time, and
70compare service time.
71If calculated service time is equal, the path having maximum
72'relative_throughput' may be better. So compare 'relative_throughput'
73then.
74
75
76Examples
77========
78In case that 2 paths (sda and sdb) are used with repeat_count == 128
79and 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
92Or '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====================
2device-mapper uevent
3====================
4
5The device-mapper uevent code adds the capability to device-mapper to create
6and send kobject uevents (uevents). Previously device-mapper events were only
7available through the ioctl interface. The advantage of the uevents interface
8is the event contains environment attributes providing increased context for
9the event avoiding the need to query the state of the device-mapper device after
10the event is received.
11
12There are two functions currently for device-mapper events. The first function
13listed 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
21The variables added to the uevent environment are:
22
23Variable 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
30Variable 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
39Variable 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
46Variable 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
54Variable 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
61Variable 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
68Variable 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
75An example of the uevents generated as captured by udevmonitor is shown
76below
77
781.) 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
952.) 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========
2dm-zoned
3========
4
5The dm-zoned device mapper target exposes a zoned block device (ZBC and
6ZAC compliant devices) as a regular block device without any write
7pattern constraints. In effect, it implements a drive-managed zoned
8block device which hides from the user (a file system or an application
9doing raw block device accesses) the sequential write constraints of
10host-managed zoned block devices and can mitigate the potential
11device-side performance degradation due to excessive random writes on
12host-aware zoned block devices.
13
14For a more detailed description of the zoned block device models and
15their constraints see (for SCSI devices):
16
17http://www.t10.org/drafts.htm#ZBC_Family
18
19and (for ATA devices):
20
21http://www.t13.org/Documents/UploadedDocuments/docs2015/di537r05-Zoned_Device_ATA_Command_Set_ZAC.pdf
22
23The dm-zoned implementation is simple and minimizes system overhead (CPU
24and memory usage as well as storage capacity loss). For a 10TB
25host-managed disk with 256 MB zones, dm-zoned memory usage per disk
26instance is at most 4.5 MB and as little as 5 zones will be used
27internally for storing metadata and performaing reclaim operations.
28
29dm-zoned target devices are formatted and checked using the dmzadm
30utility available at:
31
32https://github.com/hgst/dm-zoned-tools
33
34Algorithm
35=========
36
37dm-zoned implements an on-disk buffering scheme to handle non-sequential
38write accesses to the sequential zones of a zoned block device.
39Conventional zones are used for caching as well as for storing internal
40metadata.
41
42The zones of the device are separated into 2 types:
43
441) Metadata zones: these are conventional zones used to store metadata.
45Metadata zones are not reported as useable capacity to the user.
46
472) Data zones: all remaining zones, the vast majority of which will be
48sequential zones used exclusively to store user data. The conventional
49zones of the device may be used also for buffering user random writes.
50Data in these zones may be directly mapped to the conventional zone, but
51later moved to a sequential zone so that the conventional zone can be
52reused for buffering incoming random writes.
53
54dm-zoned exposes a logical device with a sector size of 4096 bytes,
55irrespective of the physical sector size of the backend zoned block
56device being used. This allows reducing the amount of metadata needed to
57manage valid blocks (blocks written).
58
59The on-disk metadata format is as follows:
60
611) The first block of the first conventional zone found contains the
62super block which describes the on disk amount and position of metadata
63blocks.
64
652) Following the super block, a set of blocks is used to describe the
66mapping of the logical device blocks. The mapping is done per chunk of
67blocks, with the chunk size equal to the zoned block device size. The
68mapping table is indexed by chunk number and each mapping entry
69indicates the zone number of the device storing the chunk of data. Each
70mapping entry may also indicate if the zone number of a conventional
71zone used to buffer random modification to the data zone.
72
733) A set of blocks used to store bitmaps indicating the validity of
74blocks in the data zones follows the mapping table. A valid block is
75defined as a block that was written and not discarded. For a buffered
76data chunk, a block is always valid only in the data zone mapping the
77chunk or in the buffer zone of the chunk.
78
79For a logical chunk mapped to a conventional zone, all write operations
80are processed by directly writing to the zone. If the mapping zone is a
81sequential zone, the write operation is processed directly only if the
82write offset within the logical chunk is equal to the write pointer
83offset within of the sequential data zone (i.e. the write operation is
84aligned on the zone write pointer). Otherwise, write operations are
85processed indirectly using a buffer zone. In that case, an unused
86conventional zone is allocated and assigned to the chunk being
87accessed. Writing a block to the buffer zone of a chunk will
88automatically invalidate the same block in the sequential zone mapping
89the chunk. If all blocks of the sequential zone become invalid, the zone
90is freed and the chunk buffer zone becomes the primary zone mapping the
91chunk, resulting in native random write performance similar to a regular
92block device.
93
94Read operations are processed according to the block validity
95information provided by the bitmaps. Valid blocks are read either from
96the sequential zone mapping a chunk, or if the chunk is buffered, from
97the buffer zone assigned. If the accessed chunk has no mapping, or the
98accessed blocks are invalid, the read buffer is zeroed and the read
99operation terminated.
100
101After some time, the limited number of convnetional zones available may
102be exhausted (all used to map chunks or buffer sequential zones) and
103unaligned writes to unbuffered chunks become impossible. To avoid this
104situation, a reclaim process regularly scans used conventional zones and
105tries to reclaim the least recently used zones by copying the valid
106blocks of the buffer zone to a free sequential zone. Once the copy
107completes, the chunk mapping is updated to point to the sequential zone
108and the buffer zone freed for reuse.
109
110Metadata Protection
111===================
112
113To protect metadata against corruption in case of sudden power loss or
114system crash, 2 sets of metadata zones are used. One set, the primary
115set, is used as the main metadata region, while the secondary set is
116used as a staging area. Modified metadata is first written to the
117secondary set and validated by updating the super block in the secondary
118set, a generation counter is used to indicate that this set contains the
119newest metadata. Once this operation completes, in place of metadata
120block updates can be done in the primary metadata set. This ensures that
121one of the set is always consistent (all modifications committed or none
122at all). Flush operations are used as a commit point. Upon reception of
123a flush request, metadata modification activity is temporarily blocked
124(for both incoming BIO processing and reclaim process) and all dirty
125metadata blocks are staged and updated. Normal operation is then
126resumed. Flushing metadata thus only temporarily delays write and
127discard requests. Read requests can be processed concurrently while
128metadata flush is being executed.
129
130Usage
131=====
132
133A zoned block device must first be formatted using the dmzadm tool. This
134will analyze the device zone configuration, determine where to place the
135metadata sets on the device and initialize the metadata sets.
136
137Ex::
138
139 dmzadm --format /dev/sdxx
140
141For a formatted device, the target can be created normally with the
142dmsetup utility. The only parameter that dm-zoned requires is the
143underlying 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======
2dm-era
3======
4
5Introduction
6============
7
8dm-era is a target that behaves similar to the linear target. In
9addition it keeps track of which blocks were written within a user
10defined period of time called an 'era'. Each era target instance
11maintains the current era as a monotonically increasing 32-bit
12counter.
13
14Use cases include tracking changed blocks for backup software, and
15partially invalidating the contents of a cache to restore cache
16coherency after rolling back a vendor snapshot.
17
18Constructor
19===========
20
21era <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
30Messages
31========
32
33None of the dm messages take any arguments.
34
35checkpoint
36----------
37
38Possibly move to a new era. You shouldn't assume the era has
39incremented. After sending this message, you should check the
40current era via the status line.
41
42take_metadata_snap
43------------------
44
45Create a clone of the metadata, to allow a userland process to read it.
46
47drop_metadata_snap
48------------------
49
50Drop the metadata snapshot.
51
52Status
53======
54
55<metadata block size> <#used metadata blocks>/<#total metadata blocks>
56<current era> <held metadata root | '-'>
57
58========================= ==============================================
59metadata 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
63current era The current era
64held 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
69Detailed use case
70=================
71
72The scenario of invalidating a cache when rolling back a vendor
73snapshot was the primary use case when developing this target:
74
75Taking 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
83Rolling 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
94Memory usage
95============
96
97The target uses a bitset to record writes in the current era. It also
98has a spare bitset ready for switching over to a new era. Other than
99that it uses a few 4k blocks for updating metadata::
100
101 (4 * nr_blocks) bytes + buffers
102
103Resilience
104==========
105
106Metadata is updated on disk before a write to a previously unwritten
107block is performed. As such dm-era should not be effected by a hard
108crash such as power failure.
109
110Userland tools
111==============
112
113Userland tools are found in the increasingly poorly named
114thin-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=============
2Device 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======
2kcopyd
3======
4
5Kcopyd provides the ability to copy a range of sectors from one block-device
6to one or more other block-devices, with an asynchronous completion
7notification. It is used by dm-snapshot and dm-mirror.
8
9Users of kcopyd must first create a client and indicate how many memory pages
10to set aside for their copy jobs. This is done with a call to
11kcopyd_client_create()::
12
13 int kcopyd_client_create(unsigned int num_pages,
14 struct kcopyd_client **result);
15
16To start a copy job, the user must set up io_region structures to describe
17the source and destinations of the copy. Each io_region indicates a
18block-device along with the starting sector and size of the region. The source
19of the copy is given as one io_region structure, and the destinations of the
20copy 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
28To start the copy, the user calls kcopyd_copy(), passing in the client
29pointer, pointers to the source and destination io_regions, the name of a
30completion 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
39When the copy completes, kcopyd will call the user's completion routine,
40passing back the user's context pointer. It will also indicate if a read or
41write error occurred during the copy.
42
43When a user is done with all their copy jobs, they should call
44kcopyd_client_destroy() to delete the kcopyd client, which will release the
45associated 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=========
2dm-linear
3=========
4
5Device-Mapper's "linear" target maps a linear range of the Device-Mapper
6device onto a linear range of another device. This is the basic building
7block of logical volume managers.
8
9Parameters: <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
17Example 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=============
2dm-log-writes
3=============
4
5This target takes 2 devices, one to pass all IO to normally, and one to log all
6of the write operations to. This is intended for file system developers wishing
7to verify the integrity of metadata or data as the file system is written to.
8There is a log_write_entry written for every WRITE request and the target is
9able to take arbitrary data from userspace to insert into the log. The data
10that is in the WRITE requests is copied into the log to make the replay happen
11exactly as it happened originally.
12
13Log Ordering
14============
15
16We log things in order of completion once we are sure the write is no longer in
17cache. This means that normal WRITE requests are not actually logged until the
18next REQ_PREFLUSH request. This is to make it easier for userspace to replay
19the log in a way that correlates to what is on disk and not what is in cache,
20to make it easier to detect improper waiting/flushing.
21
22This works by attaching all WRITE requests to a list once the write completes.
23Once we see a REQ_PREFLUSH request we splice this list onto the request and once
24the FLUSH request completes we log all of the WRITEs and then the FLUSH. Only
25completed WRITEs, at the time the REQ_PREFLUSH is issued, are added in order to
26simulate the worst case scenario with regard to power failures. Consider the
27following example (W means write, C means complete):
28
29 W1,W2,W3,C3,C2,Wflush,C1,Cflush
30
31The log would show the following:
32
33 W3,W2,flush,W1....
34
35Again this is to simulate what is actually on disk, this allows us to detect
36cases where a power failure at a particular point in time would create an
37inconsistent file system.
38
39Any REQ_FUA requests bypass this flushing mechanism and are logged as soon as
40they complete as those requests will obviously bypass the device cache.
41
42Any REQ_OP_DISCARD requests are treated like WRITE requests. Otherwise we would
43have all the DISCARD requests, and then the WRITE requests and then the FLUSH
44request. Consider the following example:
45
46 WRITE block 1, DISCARD block 1, FLUSH
47
48If we logged DISCARD when it completed, the replay would look like this:
49
50 DISCARD 1, WRITE 1, FLUSH
51
52which isn't quite what happened and wouldn't be caught during the log replay.
53
54Target interface
55================
56
57i) 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
66ii) 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
75iii) 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
95Userspace component
96===================
97
98There is a userspace tool that will replay the log for you in various ways.
99It can be found here: https://github.com/josefbacik/log-writes
100
101Example usage
102=============
103
104Say you want to test fsync on your file system. You would do something like
105this::
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
143And that will replay the log until it sees a FUA request, run the fsck command
144and if the fsck passes it will replay to the next FUA, until it is completed or
145the fsck command exists abnormally.
Documentation/admin-guide/device-mapper/persistent-data.rst+88−0
@@ -0,0 +1,88 @@
1===============
2Persistent data
3===============
4
5Introduction
6============
7
8The more-sophisticated device-mapper targets require complex metadata
9that is managed in kernel. In late 2010 we were seeing that various
10different 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
17Maintaining these data structures takes a lot of work, so if possible
18we'd like to reduce the number.
19
20The persistent-data library is an attempt to provide a re-usable
21framework for people who want to store metadata in device-mapper
22targets. It's currently used by the thin-provisioning target and an
23upcoming hierarchical storage target.
24
25Overview
26========
27
28The main documentation is in the header files which can all be found
29under drivers/md/persistent-data.
30
31The block manager
32-----------------
33
34dm-block-manager.[hc]
35
36This provides access to the data on disk in fixed sized-blocks. There
37is a read/write locking interface to prevent concurrent accesses, and
38keep data that is being used in the cache.
39
40Clients of persistent-data are unlikely to use this directly.
41
42The transaction manager
43-----------------------
44
45dm-transaction-manager.[hc]
46
47This restricts access to blocks and enforces copy-on-write semantics.
48The only way you can get hold of a writable block through the
49transaction manager is by shadowing an existing block (ie. doing
50copy-on-write) or allocating a fresh one. Shadowing is elided within
51the same transaction so performance is reasonable. The commit method
52ensures that all data is flushed before it writes the superblock.
53On power failure your metadata will be as it was when last committed.
54
55The Space Maps
56--------------
57
58dm-space-map.h
59dm-space-map-metadata.[hc]
60dm-space-map-disk.[hc]
61
62On-disk data structures that keep track of reference counts of blocks.
63Also acts as the allocator of new blocks. Currently two
64implementations: a simpler one for managing blocks on a different
65device (eg. thinly-provisioned data blocks); and one for managing
66the metadata space. The latter is complicated by the need to store
67its own data within the space it's managing.
68
69The data structures
70-------------------
71
72dm-btree.[hc]
73dm-btree-remove.c
74dm-btree-spine.c
75dm-btree-internal.h
76
77Currently there is only one data structure, a hierarchical btree.
78There are plans to add more. For example, something with an
79array-like interface would see a lot of use.
80
81The btree is 'hierarchical' in that you can define it to be composed
82of nested btrees, and take multiple keys. For example, the
83thin-provisioning target uses a btree with two levels of nesting.
84The first maps a device id to a mapping tree, and that in turn maps a
85virtual block to a physical block.
86
87Values stored in the btrees can have arbitrary size. Keys are always
8864bits, although nesting allows you to use multiple keys.
Documentation/admin-guide/device-mapper/snapshot.rst+196−0
@@ -0,0 +1,196 @@
1==============================
2Device-mapper snapshot support
3==============================
4
5Device-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
15In the first two cases, dm copies only the chunks of data that get
16changed and uses a separate copy-on-write (COW) block device for
17storage.
18
19For snapshot merge the contents of the COW storage are merged back into
20the origin device.
21
22
23There are three dm targets available:
24snapshot, snapshot-origin, and snapshot-merge.
25
26- snapshot-origin <origin>
27
28which will normally have one or more snapshots based on it.
29Reads will be mapped directly to the backing device. For each write, the
30original data will be saved in the <COW device> of each snapshot to keep
31its 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
37A snapshot of the <origin> block device is created. Changed chunks of
38<chunksize> sectors will be stored on the <COW device>. Writes will
39only go to the <COW device>. Reads will come from the <COW device> or
40from <origin> for unchanged data. <COW device> will often be
41smaller than the origin and if it fills up the snapshot will become
42useless and be disabled, returning errors. So it is important to monitor
43the 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
46after reboot). O (Overflow) can be added as a persistent store option
47to allow userspace to advertise its support for seeing "Overflow" in the
48snapshot status. So supported store types are "P", "PO" and "N".
49
50The difference between persistent and transient is with transient
51snapshots less metadata must be saved on disk - they can be kept in
52memory by the kernel.
53
54When loading or unloading the snapshot target, the corresponding
55snapshot-origin or snapshot-merge target must be suspended. A failure to
56suspend the origin target could result in data corruption.
57
58Optional 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
76takes the same table arguments as the snapshot target except it only
77works with persistent snapshots. This target assumes the role of the
78"snapshot-origin" target and must not be loaded if the "snapshot-origin"
79is still present for <origin>.
80
81Creates a merging snapshot that takes control of the changed chunks
82stored in the <COW device> of an existing snapshot, through a handover
83procedure, and merges these chunks back into the <origin>. Once merging
84has started (in the background) the <origin> may be opened and the merge
85will continue while I/O is flowing to it. Changes to the <origin> are
86deferred until the merging snapshot's corresponding chunk(s) have been
87merged. Once merging has started the snapshot device, associated with
88the "snapshot" target, will return -EIO when accessed.
89
90
91How snapshot is used by LVM2
92============================
93When you create the first LVM2 snapshot of a volume, four dm devices are used:
94
951) a device containing the original mapping table of the source volume;
962) a device used as the <COW device>;
973) a "snapshot" device, combining #1 and #2, which is the visible snapshot
98 volume;
994) 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
103A 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
108we'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
124How snapshot-merge is used by LVM2
125==================================
126A merging snapshot assumes the role of the "snapshot-origin" while
127merging. As such the "snapshot-origin" is replaced with
128"snapshot-merge". The "-real" device is not changed and the "-cow"
129device is renamed to <origin name>-cow to aid LVM2's cleanup of the
130merging snapshot after it completes. The "snapshot" that hands over its
131COW 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
134A snapshot will merge into its origin with the following command::
135
136 lvconvert --merge volumeGroup/snap
137
138we'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
152How to determine when a merging is complete
153===========================================
154The snapshot-merge and snapshot status lines end with:
155
156 <sectors_allocated>/<total_sectors> <metadata_sectors>
157
158Both <sectors_allocated> and <total_sectors> include both data and metadata.
159During merging, the number of sectors allocated gets smaller and
160smaller. Merging has finished when the number of sectors holding data
161is zero, in other words <sectors_allocated> == <metadata_sectors>.
162
163Here 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
190Merging 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=============
2DM statistics
3=============
4
5Device Mapper supports the collection of I/O statistics on user-defined
6regions of a DM device. If no regions are defined no statistics are
7collected so there isn't any performance impact. Only bio-based DM
8devices are currently supported.
9
10Each user-defined region specifies a starting sector, length and step.
11Individual statistics will be collected for each step-sized area within
12the range specified.
13
14The I/O statistics counters for each step-sized area of a region are
15in the same format as `/sys/block/*/stat` or `/proc/diskstats` (see:
16Documentation/admin-guide/iostats.rst). But two extra counters (12 and 13) are
17provided: total time spent reading and writing. When the histogram
18argument is used, the 14th parameter is reported that represents the
19histogram of latencies. All these counters may be accessed by sending
20the @stats_print message to the appropriate DM device via dmsetup.
21
22The reported times are in milliseconds and the granularity depends on
23the kernel ticks. When the option precise_timestamps is used, the
24reported times are in nanoseconds.
25
26Each region has a corresponding unique identifier, which we call a
27region_id, that is assigned when the region is created. The region_id
28must be supplied when querying statistics about the region, deleting the
29region, etc. Unique region_ids enable multiple userspace programs to
30request and process statistics for the same DM device without stepping
31on each other's data.
32
33The creation of DM statistics will allocate memory via kmalloc or
34fallback to using vmalloc space. At most, 1/4 of the overall system
35memory may be allocated by DM statistics. The admin can see how much
36memory is used by reading:
37
38 /sys/module/dm_mod/parameters/stats_current_allocated_bytes
39
40Messages
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
202Examples
203========
204
205Subdivide the DM device 'vol' into 100 pieces and start collecting
206statistics on them::
207
208 dmsetup message vol 0 @stats_create - /100
209
210Set the auxiliary data string to "foo bar baz" (the escape for each
211space must also be escaped, otherwise the shell will consume them)::
212
213 dmsetup message vol 0 @stats_set_aux 0 foo\\ bar\\ baz
214
215List the statistics::
216
217 dmsetup message vol 0 @stats_list
218
219Print the statistics::
220
221 dmsetup message vol 0 @stats_print 0
222
223Delete 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=========
2dm-stripe
3=========
4
5Device-Mapper's "striped" target is used to create a striped (i.e. RAID-0)
6device across one or more underlying devices. Data is written in "chunks",
7with consecutive chunks rotating among the underlying devices. This can
8potentially provide improved I/O throughput by utilizing several physical
9devices in parallel.
10
11Parameters: <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
23One or more underlying devices can be specified. The striped device size must
24be a multiple of the chunk size multiplied by the number of underlying devices.
25
26
27Example 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=========
2dm-switch
3=========
4
5The device-mapper switch target creates a device that supports an
6arbitrary mapping of fixed-size regions of I/O across a fixed set of
7paths. The path used for any specific region can be switched
8dynamically by sending the target a message.
9
10It maps I/O to underlying block devices efficiently when there is a large
11number of fixed-sized address regions but there is no simple pattern
12that would allow for a compact representation of the mapping such as
13dm-stripe.
14
15Background
16----------
17
18Dell EqualLogic and some other iSCSI storage arrays use a distributed
19frameless architecture. In this architecture, the storage group
20consists of a number of distinct storage arrays ("members") each having
21independent controllers, disk storage and network adapters. When a LUN
22is created it is spread across multiple members. The details of the
23spreading are hidden from initiators connected to this storage system.
24The storage group exposes a single target discovery portal, no matter
25how many members are being used. When iSCSI sessions are created, each
26session is connected to an eth port on a single member. Data to a LUN
27can be sent on any iSCSI session, and if the blocks being accessed are
28stored on another member the I/O will be forwarded as required. This
29forwarding is invisible to the initiator. The storage layout is also
30dynamic, and the blocks stored on disk may be moved from member to
31member as needed to balance the load.
32
33This architecture simplifies the management and configuration of both
34the storage group and initiators. In a multipathing configuration, it
35is possible to set up multiple iSCSI sessions to use multiple network
36interfaces on both the host and target to take advantage of the
37increased network bandwidth. An initiator could use a simple round
38robin algorithm to send I/O across all paths and let the storage array
39members forward it as necessary, but there is a performance advantage to
40sending data directly to the correct member.
41
42A device-mapper table already lets you map different regions of a
43device onto different targets. However in this architecture the LUN is
44spread with an address region size on the order of 10s of MBs, which
45means the resulting table could have more than a million entries and
46consume far too much memory.
47
48Using this device-mapper switch target we can now build a two-layer
49device 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
54The lower tier consists of a single dm multipath device for each member.
55Each of these multipath devices contains the set of paths directly to
56the array member in one priority group, and leverages existing path
57selectors to load balance amongst these paths. We also build a
58non-preferred priority group containing paths to other array members for
59failover reasons.
60
61The upper tier consists of a single dm-switch device. This device uses
62a bitmap to look up the location of the I/O and choose the appropriate
63lower tier device to route the I/O. By using a bitmap we are able to
64use 4 bits for each address range in a 16 member group (which is very
65large for us). This is a much denser representation than the dm table
66b-tree can achieve.
67
68Construction 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
91Messages
92========
93
94set_region_mappings <index>:<path_nr> [<index>]:<path_nr> [<index>]:<path_nr>...
95
96Modify the region table by specifying which regions are redirected to
97which 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
108R<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
113Status
114======
115
116No status line is reported.
117
118Example
119=======
120
121Assume that you have volumes vg1/switch0 vg1/switch1 vg1/switch2 with
122the same size.
123
124Create 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
129Set mappings for the first 7 entries to point to devices switch0, switch1,
130switch2, switch0, switch1, switch2, switch1::
131
132 dmsetup message switch 0 set_region_mappings 0:0 :1 :2 :0 :1 :2 :1
133
134Set repetitive mapping. This command::
135
136 dmsetup message switch 0 set_region_mappings 1000:1 :2 R2,10
137
138is 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=================
2Thin provisioning
3=================
4
5Introduction
6============
7
8This document describes a collection of device-mapper targets that
9between them implement thin-provisioning and snapshots.
10
11The main highlight of this implementation, compared to the previous
12implementation of snapshots, is that it allows many virtual devices to
13be stored on the same data volume. This simplifies administration and
14allows the sharing of data between volumes, thus reducing disk usage.
15
16Another significant feature is support for an arbitrary depth of
17recursive snapshots (snapshots of snapshots of snapshots ...). The
18previous implementation of snapshots did this by chaining together
19lookup tables, and so performance was O(depth). This new
20implementation uses a single data structure to avoid this degradation
21with depth. Fragmentation may still be an issue, however, in some
22scenarios.
23
24Metadata is stored on a separate device from data, giving the
25administrator 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
32Status
33======
34
35These targets are considered safe for production use. But different use
36cases will have different performance characteristics, for example due
37to fragmentation of the data volume.
38
39If you find this software is not performing as expected please mail
40dm-devel@redhat.com with details and we'll try our best to improve
41things for you.
42
43Userspace tools for checking and repairing the metadata have been fully
44developed and are available as 'thin_check' and 'thin_repair'. The name
45of the package that provides these utilities varies by distribution (on
46a Red Hat distribution it is named 'device-mapper-persistent-data').
47
48Cookbook
49========
50
51This section describes some quick recipes for using thin provisioning.
52They use the dmsetup program to control the device-mapper driver
53directly. End users will be advised to use a higher-level volume
54manager such as LVM2 once support has been added.
55
56Pool device
57-----------
58
59The pool device ties together the metadata volume and the data volume.
60It maps I/O linearly to the data volume and updates the metadata via
61two 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
68Setting up a fresh pool device
69------------------------------
70
71Setting up a pool device requires a valid metadata device, and a
72data device. If you do not have an existing metadata device you can
73make one by zeroing the first 4k to indicate empty metadata.
74
75 dd if=/dev/zero of=$metadata_dev bs=4096 count=1
76
77The amount of metadata you need will vary according to how many blocks
78are shared between thin devices (i.e. through snapshots). If you have
79less sharing than average you'll need a larger-than-average metadata device.
80
81As a guide, we suggest you calculate the number of bytes to use in the
82metadata device as 48 * $data_dev_size / $data_block_size but round it up
83to 2MB if the answer is smaller. If you're creating large numbers of
84snapshots which are recording large amounts of change, you may find you
85need to increase this.
86
87The largest size supported is 16GB: If the device is larger,
88a warning will be issued and the excess space will not be used.
89
90Reloading a pool table
91----------------------
92
93You may reload a pool's table, indeed this is how the pool is resized
94if it runs out of space. (N.B. While specifying a different metadata
95device when reloading is not forbidden at the moment, things will go
96wrong if it does not route I/O to exactly the same on-disk location as
97previously.)
98
99Using 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
109allocated at a time expressed in units of 512-byte sectors.
110$data_block_size must be between 128 (64KB) and 2097152 (1GB) and a
111multiple of 128 (64KB). $data_block_size cannot be changed after the
112thin-pool is created. People primarily interested in thin provisioning
113may want to use a value such as 1024 (512KB). People doing lots of
114snapshotting may want a smaller value such as 128 (64KB). If you are
115not zeroing newly-allocated data, a larger $data_block_size in the
116region of 256000 (128MB) is suggested.
117
118$low_water_mark is expressed in blocks of size $data_block_size. If
119free space on the data device drops below this level then a dm event
120will be triggered which a userspace daemon should catch allowing it to
121extend the pool device. Only one such event will be sent.
122
123No special event is triggered if a just resumed device's free space is below
124the low water mark. However, resuming a device always triggers an
125event; a userspace daemon should verify that free space exceeds the low
126water mark when handling this event.
127
128A low water mark for the metadata device is maintained in the kernel and
129will trigger a dm event if free space on the metadata device drops below
130it.
131
132Updating on-disk metadata
133-------------------------
134
135On-disk metadata is committed every time a FLUSH or FUA bio is written.
136If no such requests are made then commits will occur every second. This
137means the thin-provisioning target behaves like a physical disk that has
138a volatile write cache. If power is lost you may lose some recent
139writes. The metadata should always be consistent in spite of any crash.
140
141If data space is exhausted the pool will either error or queue IO
142according to the configuration (see: error_if_no_space). If metadata
143space is exhausted or a metadata operation fails: the pool will error IO
144until the pool is taken offline and repair is performed to 1) fix any
145potential inconsistencies and 2) clear the flag that imposes repair.
146Once the pool's metadata device is repaired it may be resized, which
147will allow the pool to return to normal operation. Note that if a pool
148is flagged as needing repair, the pool's data and metadata devices
149cannot be resized until repair is performed. It should also be noted
150that when the pool's metadata space is exhausted the current metadata
151transaction is aborted. Given that the pool will cache IO whose
152completion 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
155required.
156
157Thin provisioning
158-----------------
159
160i) 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
171ii) 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
179Internal snapshots
180------------------
181
182i) 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
199ii) 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
213External snapshots
214------------------
215
216You can use an external **read only** device as an origin for a
217thinly-provisioned volume. Any read to an unprovisioned area of the
218thin device will be passed through to the origin. Writes trigger
219the allocation of new blocks as usual.
220
221One use case for this is VM hosts that want to run guests on
222thinly-provisioned volumes but have the base image on another device
223(possibly shared between many VMs).
224
225You must not write to the origin device if you use this technique!
226Of course, you may write to the thin device and take internal snapshots
227of the thin volume.
228
229i) 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
238ii) 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
247Deactivation
248------------
249
250All devices using a pool must be deactivated before the pool itself
251can be.
252
253::
254
255 dmsetup remove thin
256 dmsetup remove snap
257 dmsetup remove pool
258
259Reference
260=========
261
262'thin-pool' target
263------------------
264
265i) 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
298ii) 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
357iii) 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
395i) 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
413The pool doesn't store any size against the thin devices. If you
414load a thin target that is smaller than you've been using previously,
415then you'll have no access to blocks mapped beyond the end. If you
416load a target that is bigger than before, then extra blocks will be
417provisioned as and when needed.
418
419ii) 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================================
2Device-mapper "unstriped" target
3================================
4
5Introduction
6============
7
8The device-mapper "unstriped" target provides a transparent mechanism to
9unstripe a device-mapper "striped" target to access the underlying disks
10without having to touch the true backing block-device. It can also be
11used to unstripe a hardware RAID-0 to access backing disks.
12
13Parameters:
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
30Why use this module?
31====================
32
33An example of undoing an existing dm-stripe
34-------------------------------------------
35
36This small bash script will setup 4 loop devices and use the existing
37striped target to combine the 4 devices into one. It then will use
38the unstriped target ontop of the striped device to access the
39individual backing loop devices. We write data to the newly exposed
40unstriped devices and verify the data written matches the correct
41underlying 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
82Another example
83---------------
84
85Intel NVMe drives contain two cores on the physical device.
86Each core of the drive has segregated access to its LBA range.
87The current LBA model has a RAID 0 128k chunk on each core, resulting
88in 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
96The purpose of this unstriping is to provide better QoS in noisy
97neighbor environments. When two partitions are created on the
98aggregate drive without this unstriping, reads on one partition
99can affect writes on another partition. This is because the partitions
100are striped across the two cores. When we unstripe this hardware RAID 0
101and make partitions on each new exposed device the two partitions are now
102physically separated.
103
104With the dm-unstriped target we're able to segregate an fio script that
105has read and write jobs that are independent of each other. Compared to
106when we run the test on a combined drive with partitions, we were able
107to get a 92% reduction in read latency using this device mapper target.
108
109
110Example dmsetup usage
111=====================
112
113unstriped 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
121There will now be two devices that expose Intel NVMe core 0 and 1
122respectively::
123
124 /dev/mapper/nvmset0
125 /dev/mapper/nvmset1
126
127unstriped 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=========
2dm-verity
3=========
4
5Device-Mapper's "verity" target provides transparent integrity checking of
6block devices using a cryptographic digest provided by the kernel crypto API.
7This target is read-only.
8
9Construction 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
78ignore_corruption
79 Log corrupted blocks, but allow read operations to proceed normally.
80
81restart_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
86ignore_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
91use_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
103fec_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
108fec_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
112fec_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
116check_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
128Theory of operation
129===================
130
131dm-verity is meant to be set up as part of a verified boot path. This
132may be anything ranging from a boot using tboot or trustedgrub to just
133booting from a known-good device (like a USB drive or CD).
134
135When a dm-verity device is configured, it is expected that the caller
136has been authenticated in some way (cryptographic signatures, etc).
137After instantiation, all hashes will be verified on-demand during
138disk access. If they cannot be verified up to the root node of the
139tree, the root hash, then the I/O will fail. This should detect
140tampering with any data on the device and the hash data.
141
142Cryptographic hashes are used to assert the integrity of the device on a
143per-block basis. This allows for a lightweight hash computation on first read
144into the page cache. Block hashes are stored linearly, aligned to the nearest
145block size.
146
147If forward error correction (FEC) support is enabled any recovery of
148corrupted data will be verified using the cryptographic hash of the
149corresponding data. This is why combining error correction with
150integrity checking is essential.
151
152Hash Tree
153---------
154
155Each node in the tree is a cryptographic hash. If it is a leaf node, the hash
156of some data block on disk is calculated. If it is an intermediary node,
157the hash of a number of child nodes is calculated.
158
159Each entry in the tree is a collection of neighboring nodes that fit in one
160block. The number is determined based on block_size and the size of the
161selected cryptographic digest algorithm. The hashes are linearly-ordered in
162this entry and any unaligned trailing space is ignored but included when
163calculating the parent node.
164
165The 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
180On-disk format
181==============
182
183The verity kernel code does not read the verity metadata on-disk header.
184It only reads the hash blocks which directly follow the header.
185It is expected that a user-space tool will verify the integrity of the
186verity header.
187
188Alternatively, the header can be omitted and the dmsetup parameters can
189be passed via the kernel command-line in a rooted chain of trust where
190the command-line is verified.
191
192Directly following the header (and with sector number padded to the next hash
193block 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
196The full specification of kernel parameters and on-disk metadata format
197is available at the cryptsetup project's wiki page
198
199 https://gitlab.com/cryptsetup/cryptsetup/wikis/DMVerity
200
201Status
202======
203V (for Valid) is returned if every check performed so far was valid.
204If any check failed, C (for Corruption) is returned.
205
206Example
207=======
208Set 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
215A command line tool veritysetup is available to compute or verify
216the hash tree or activate the kernel device. This is available from
217the cryptsetup upstream repository https://gitlab.com/cryptsetup/cryptsetup/
218(as a libcryptsetup extension).
219
220Create hash on the device::
221
222 # veritysetup format /dev/sda1 /dev/sda2
223 ...
224 Root hash: 4392712ba01368efdf14b05c76f9e4df0d53664630b5d48632ed17a137f39076
225
226Activate 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=================
2Writecache target
3=================
4
5The writecache target caches writes on persistent memory or on SSD. It
6doesn't cache reads because reads are supposed to be cached in page cache
7in normal RAM.
8
9When the device is constructed, the first sector should be zeroed or the
10first sector should contain valid superblock from previous invocation.
11
12Constructor parameters:
13
141. type of the cache device - "p" or "s"
15
16 - p - persistent memory
17 - s - SSD
182. the underlying device that will be cached
193. the cache device
204. block size (4096 is recommended; the maximum block size is the page
21 size)
225. 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
57Status:
581. error indicator - 0 if there was no error, otherwise error number
592. the number of blocks
603. the number of free blocks
614. the number of blocks under writeback
62
63Messages:
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=======
2dm-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