Linux 5.3-rc3
Unified · Split
| @@ -30,6 +30,7 @@ · 29 unmodified lines | ||
| 30 | 30 | *.lz4 |
| 31 | 31 | *.lzma |
| 32 | 32 | *.lzo |
| 33 | +*.mod | |
| 33 | 34 | *.mod.c |
| 34 | 35 | *.o |
| 35 | 36 | *.o.* |
| @@ -141,3 +142,6 @@ x509.genkey · 105 unmodified lines | ||
| 141 | 142 | |
| 142 | 143 | # Kdevelop4 |
| 143 | 144 | *.kdev4 |
| 145 | + | |
| 146 | +# Clang's compilation database file | |
| 147 | +/compile_commands.json | |
| @@ -81,6 +81,7 @@ Greg Kroah-Hartman <greg@echidna.(none)> · 80 unmodified lines | ||
| 81 | 81 | Greg Kroah-Hartman <gregkh@suse.de> |
| 82 | 82 | Greg Kroah-Hartman <greg@kroah.com> |
| 83 | 83 | Gregory CLEMENT <gregory.clement@bootlin.com> <gregory.clement@free-electrons.com> |
| 84 | +Hanjun Guo <guohanjun@huawei.com> <hanjun.guo@linaro.org> | |
| 84 | 85 | Henk Vergonet <Henk.Vergonet@gmail.com> |
| 85 | 86 | Henrik Kretzschmar <henne@nachtwindheim.de> |
| 86 | 87 | Henrik Rydberg <rydberg@bitmath.org> |
| @@ -97,6 +98,7 @@ Jason Gunthorpe <jgg@ziepe.ca> <jgunthorpe@obsidianresearch.com> · 10 unmodified lines | ||
| 97 | 98 | Javi Merino <javi.merino@kernel.org> <javi.merino@arm.com> |
| 98 | 99 | <javier@osg.samsung.com> <javier.martinez@collabora.co.uk> |
| 99 | 100 | Jean Tourrilhes <jt@hpl.hp.com> |
| 101 | +<jean-philippe@linaro.org> <jean-philippe.brucker@arm.com> | |
| 100 | 102 | Jeff Garzik <jgarzik@pretzel.yyz.us> |
| 101 | 103 | Jeff Layton <jlayton@kernel.org> <jlayton@redhat.com> |
| 102 | 104 | Jeff Layton <jlayton@kernel.org> <jlayton@poochiereds.net> |
| @@ -115,6 +117,7 @@ John Stultz <johnstul@us.ibm.com> · 12 unmodified lines | ||
| 115 | 117 | Juha Yrjola <at solidboot.com> |
| 116 | 118 | Juha Yrjola <juha.yrjola@nokia.com> |
| 117 | 119 | Juha Yrjola <juha.yrjola@solidboot.com> |
| 120 | +Julien Thierry <julien.thierry.kdev@gmail.com> <julien.thierry@arm.com> | |
| 118 | 121 | Kay Sievers <kay.sievers@vrfy.org> |
| 119 | 122 | Kenneth W Chen <kenneth.w.chen@intel.com> |
| 120 | 123 | Konstantin Khlebnikov <koct9i@gmail.com> <k.khlebnikov@samsung.com> |
| @@ -131,6 +134,7 @@ Linus Lüssing <linus.luessing@c0d3.blue> <linus.luessing@ascom.ch> · 10 unmodified lines | ||
| 131 | 134 | Li Yang <leoyang.li@nxp.com> <leo@zh-kernel.org> |
| 132 | 135 | Li Yang <leoyang.li@nxp.com> <leoli@freescale.com> |
| 133 | 136 | Maciej W. Rozycki <macro@mips.com> <macro@imgtec.com> |
| 137 | +Marc Zyngier <maz@kernel.org> <marc.zyngier@arm.com> | |
| 134 | 138 | Marcin Nowakowski <marcin.nowakowski@mips.com> <marcin.nowakowski@imgtec.com> |
| 135 | 139 | Mark Brown <broonie@sirena.org.uk> |
| 136 | 140 | Mark Yao <markyao0591@gmail.com> <mark.yao@rock-chips.com> |
| @@ -238,6 +242,7 @@ Vlad Dogaru <ddvlad@gmail.com> <vlad.dogaru@intel.com> · 101 unmodified lines | ||
| 238 | 242 | Vladimir Davydov <vdavydov.dev@gmail.com> <vdavydov@virtuozzo.com> |
| 239 | 243 | Vladimir Davydov <vdavydov.dev@gmail.com> <vdavydov@parallels.com> |
| 240 | 244 | Takashi YOSHII <takashi.yoshii.zj@renesas.com> |
| 245 | +Will Deacon <will@kernel.org> <will.deacon@arm.com> | |
| 241 | 246 | Yakir Yang <kuankuan.y@gmail.com> <ykk@rock-chips.com> |
| 242 | 247 | Yusuke Goda <goda.yusuke@renesas.com> |
| 243 | 248 | Gustavo Padovan <gustavo@las.ic.unicamp.br> |
| @@ -1770,7 +1770,6 @@ S: USA · 1769 unmodified lines | ||
| 1770 | 1770 | |
| 1771 | 1771 | N: Dave Jones |
| 1772 | 1772 | E: davej@codemonkey.org.uk |
| 1773 | −W: http://www.codemonkey.org.uk | |
| 1774 | 1773 | D: Assorted VIA x86 support. |
| 1775 | 1774 | D: 2.5 AGPGART overhaul. |
| 1776 | 1775 | D: CPUFREQ maintenance. |
| @@ -1800,7 +1799,7 @@ S: 2300 Copenhagen S. · 23 unmodified lines | ||
| 1800 | 1799 | S: Denmark |
| 1801 | 1800 | |
| 1802 | 1801 | N: Jozsef Kadlecsik |
| 1803 | −E: kadlec@blackhole.kfki.hu | |
| 1802 | +E: kadlec@netfilter.org | |
| 1804 | 1803 | P: 1024D/470DB964 4CB3 1A05 713E 9BF7 FAC5 5809 DD8C B7B1 470D B964 |
| 1805 | 1804 | D: netfilter: TCP window tracking code |
| 1806 | 1805 | D: netfilter: raw table |
| @@ -3120,7 +3119,7 @@ S: France · 1313 unmodified lines | ||
| 3120 | 3119 | N: Rik van Riel |
| 3121 | 3120 | E: riel@redhat.com |
| 3122 | 3121 | W: http://www.surriel.com/ |
| 3123 | −D: Linux-MM site, Documentation/sysctl/*, swap/mm readaround | |
| 3122 | +D: Linux-MM site, Documentation/admin-guide/sysctl/*, swap/mm readaround | |
| 3124 | 3123 | D: kswapd fixes, random kernel hacker, rmap VM, |
| 3125 | 3124 | D: nl.linux.org administrator, minor scheduler additions |
| 3126 | 3125 | S: Red Hat Boston |
| @@ -5,7 +5,7 @@ Description: It is possible to switch the cpi setting of the mouse with the · 4 unmodified lines | ||
| 5 | 5 | press of a button. |
| 6 | 6 | When read, this file returns the raw number of the actual cpi |
| 7 | 7 | 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 | 10 | VALUE DPI |
| 11 | 11 | 1 400 |
| @@ -11,7 +11,7 @@ Description: · 10 unmodified lines | ||
| 11 | 11 | Kernel code may export it for complete or partial access. |
| 12 | 12 | |
| 13 | 13 | 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 | 16 | /sys/class/gpio |
| 17 | 17 | /export ... asks the kernel to export a GPIO to userspace |
| @@ -1,6 +1,6 @@ | ||
| 1 | 1 | rfkill - radio frequency (RF) connector kill switch support |
| 2 | 2 | |
| 3 | −For details to this subsystem look at Documentation/rfkill.txt. | |
| 3 | +For details to this subsystem look at Documentation/driver-api/rfkill.rst. | |
| 4 | 4 | |
| 5 | 5 | What: /sys/class/rfkill/rfkill[0-9]+/claim |
| 6 | 6 | Date: 09-Jul-2007 |
| @@ -423,23 +423,6 @@ Description: · 422 unmodified lines | ||
| 423 | 423 | (e.g. driver restart on the VM which owns the VF). |
| 424 | 424 | |
| 425 | 425 | |
| 426 | −sysfs interface for NetEffect RNIC Low-Level iWARP driver (nes) | |
| 427 | −--------------------------------------------------------------- | |
| 428 | − | |
| 429 | −What: /sys/class/infiniband/nesX/hw_rev | |
| 430 | −What: /sys/class/infiniband/nesX/hca_type | |
| 431 | −What: /sys/class/infiniband/nesX/board_id | |
| 432 | −Date: Feb, 2008 | |
| 433 | −KernelVersion: v2.6.25 | |
| 434 | −Contact: linux-rdma@vger.kernel.org | |
| 435 | −Description: | |
| 436 | − hw_rev: (RO) Hardware revision number | |
| 437 | − | |
| 438 | − hca_type: (RO) Host Channel Adapter type (NEX020) | |
| 439 | − | |
| 440 | − board_id: (RO) Manufacturing board id | |
| 441 | − | |
| 442 | − | |
| 443 | 426 | sysfs interface for Chelsio T4/T5 RDMA driver (cxgb4) |
| 444 | 427 | ----------------------------------------------------- |
| 445 | 428 | |
| @@ -1,6 +1,6 @@ | ||
| 1 | 1 | rfkill - radio frequency (RF) connector kill switch support |
| 2 | 2 | |
| 3 | −For details to this subsystem look at Documentation/rfkill.txt. | |
| 3 | +For details to this subsystem look at Documentation/driver-api/rfkill.rst. | |
| 4 | 4 | |
| 5 | 5 | For the deprecated /sys/class/rfkill/*/claim knobs of this interface look in |
| 6 | 6 | Documentation/ABI/removed/sysfs-class-rfkill. |
| @@ -61,7 +61,7 @@ Date: October 2002 · 60 unmodified lines | ||
| 61 | 61 | Contact: Linux Memory Management list <linux-mm@kvack.org> |
| 62 | 62 | Description: |
| 63 | 63 | The node's hit/miss statistics, in units of pages. |
| 64 | − See Documentation/numastat.txt | |
| 64 | + See Documentation/admin-guide/numastat.rst | |
| 65 | 65 | |
| 66 | 66 | What: /sys/devices/system/node/nodeX/distance |
| 67 | 67 | Date: October 2002 |
| @@ -1,5 +1,4 @@ | ||
| 1 | −What: /sys/devices/platform/mlxplat/mlxreg-io/hwmon/hwmon*/ | |
| 2 | − asic_health | |
| 1 | +What: /sys/devices/platform/mlxplat/mlxreg-io/hwmon/hwmon*/asic_health | |
| 3 | 2 | |
| 4 | 3 | Date: June 2018 |
| 5 | 4 | KernelVersion: 4.19 |
| @@ -9,9 +8,8 @@ Description: This file shows ASIC health status. The possible values are: · 3 unmodified lines | ||
| 9 | 8 | |
| 10 | 9 | The files are read only. |
| 11 | 10 | |
| 12 | −What: /sys/devices/platform/mlxplat/mlxreg-io/hwmon/hwmon*/ | |
| 13 | − cpld1_version | |
| 14 | − cpld2_version | |
| 11 | +What: /sys/devices/platform/mlxplat/mlxreg-io/hwmon/hwmon*/cpld1_version | |
| 12 | +What: /sys/devices/platform/mlxplat/mlxreg-io/hwmon/hwmon*/cpld2_version | |
| 15 | 13 | Date: June 2018 |
| 16 | 14 | KernelVersion: 4.19 |
| 17 | 15 | Contact: 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 | 19 | The files are read only. |
| 22 | 20 | |
| 23 | −What: /sys/devices/platform/mlxplat/mlxreg-io/hwmon/hwmon*/ | |
| 24 | − fan_dir | |
| 21 | +What: /sys/devices/platform/mlxplat/mlxreg-io/hwmon/hwmon*/fan_dir | |
| 25 | 22 | |
| 26 | 23 | Date: December 2018 |
| 27 | 24 | KernelVersion: 5.0 |
| @@ -32,8 +29,7 @@ Description: This file shows the system fans direction: · 4 unmodified lines | ||
| 32 | 29 | |
| 33 | 30 | The files are read only. |
| 34 | 31 | |
| 35 | −What: /sys/devices/platform/mlxplat/mlxreg-io/hwmon/hwmon*/ | |
| 36 | − jtag_enable | |
| 32 | +What: /sys/devices/platform/mlxplat/mlxreg-io/hwmon/hwmon*/jtag_enable | |
| 37 | 33 | |
| 38 | 34 | Date: November 2018 |
| 39 | 35 | KernelVersion: 5.0 |
| @@ -43,8 +39,7 @@ Description: These files show with which CPLD versions have been burned · 3 unmodified lines | ||
| 43 | 39 | |
| 44 | 40 | The files are read only. |
| 45 | 41 | |
| 46 | −What: /sys/devices/platform/mlxplat/mlxreg-io/hwmon/hwmon*/ | |
| 47 | − jtag_enable | |
| 42 | +What: /sys/devices/platform/mlxplat/mlxreg-io/hwmon/hwmon*/jtag_enable | |
| 48 | 43 | |
| 49 | 44 | Date: November 2018 |
| 50 | 45 | KernelVersion: 5.0 |
| @@ -87,16 +82,15 @@ Description: These files allow asserting system power cycling, switching · 36 unmodified lines | ||
| 87 | 82 | |
| 88 | 83 | The files are write only. |
| 89 | 84 | |
| 90 | −What: /sys/devices/platform/mlxplat/mlxreg-io/hwmon/hwmon*/ | |
| 91 | − reset_aux_pwr_or_ref | |
| 92 | − reset_asic_thermal | |
| 93 | − reset_hotswap_or_halt | |
| 94 | − reset_hotswap_or_wd | |
| 95 | − reset_fw_reset | |
| 96 | − reset_long_pb | |
| 97 | − reset_main_pwr_fail | |
| 98 | − reset_short_pb | |
| 99 | − reset_sw_reset | |
| 85 | +What: /sys/devices/platform/mlxplat/mlxreg-io/hwmon/hwmon*/reset_aux_pwr_or_ref | |
| 86 | +What: /sys/devices/platform/mlxplat/mlxreg-io/hwmon/hwmon*/reset_asic_thermal | |
| 87 | +What: /sys/devices/platform/mlxplat/mlxreg-io/hwmon/hwmon*/reset_hotswap_or_halt | |
| 88 | +What: /sys/devices/platform/mlxplat/mlxreg-io/hwmon/hwmon*/reset_hotswap_or_wd | |
| 89 | +What: /sys/devices/platform/mlxplat/mlxreg-io/hwmon/hwmon*/reset_fw_reset | |
| 90 | +What: /sys/devices/platform/mlxplat/mlxreg-io/hwmon/hwmon*/reset_long_pb | |
| 91 | +What: /sys/devices/platform/mlxplat/mlxreg-io/hwmon/hwmon*/reset_main_pwr_fail | |
| 92 | +What: /sys/devices/platform/mlxplat/mlxreg-io/hwmon/hwmon*/reset_short_pb | |
| 93 | +What: /sys/devices/platform/mlxplat/mlxreg-io/hwmon/hwmon*/reset_sw_reset | |
| 100 | 94 | Date: June 2018 |
| 101 | 95 | KernelVersion: 4.19 |
| 102 | 96 | Contact: 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 | 105 | The files are read only. |
| 112 | 106 | |
| 113 | −What: /sys/devices/platform/mlxplat/mlxreg-io/hwmon/hwmon*/ | |
| 114 | − reset_comex_pwr_fail | |
| 115 | − reset_from_comex | |
| 116 | − reset_system | |
| 117 | − reset_voltmon_upgrade_fail | |
| 107 | +What: /sys/devices/platform/mlxplat/mlxreg-io/hwmon/hwmon*/reset_comex_pwr_fail | |
| 108 | +What: /sys/devices/platform/mlxplat/mlxreg-io/hwmon/hwmon*/reset_from_comex | |
| 109 | +What: /sys/devices/platform/mlxplat/mlxreg-io/hwmon/hwmon*/reset_system | |
| 110 | +What: /sys/devices/platform/mlxplat/mlxreg-io/hwmon/hwmon*/reset_voltmon_upgrade_fail | |
| 118 | 111 | |
| 119 | 112 | Date: November 2018 |
| 120 | 113 | KernelVersion: 5.0 |
| @@ -127,3 +120,23 @@ Description: These files show the system reset cause, as following: ComEx · 6 unmodified lines | ||
| 127 | 120 | the last reset cause. |
| 128 | 121 | |
| 129 | 122 | The files are read only. |
| 123 | + | |
| 124 | +Date: June 2019 | |
| 125 | +KernelVersion: 5.3 | |
| 126 | +Contact: Vadim Pasternak <vadimpmellanox.com> | |
| 127 | +Description: These files show the system reset cause, as following: | |
| 128 | + COMEX thermal shutdown; wathchdog power off or reset was derived | |
| 129 | + by one of the next components: COMEX, switch board or by Small Form | |
| 130 | + Factor mezzanine, reset requested from ASIC, reset cuased by BIOS | |
| 131 | + reload. Value 1 in file means this is reset cause, 0 - otherwise. | |
| 132 | + Only one of the above causes could be 1 at the same time, representing | |
| 133 | + only last reset cause. | |
| 134 | + | |
| 135 | + The files are read only. | |
| 136 | + | |
| 137 | +What: /sys/devices/platform/mlxplat/mlxreg-io/hwmon/hwmon*/reset_comex_thermal | |
| 138 | +What: /sys/devices/platform/mlxplat/mlxreg-io/hwmon/hwmon*/reset_comex_wd | |
| 139 | +What: /sys/devices/platform/mlxplat/mlxreg-io/hwmon/hwmon*/reset_from_asic | |
| 140 | +What: /sys/devices/platform/mlxplat/mlxreg-io/hwmon/hwmon*/reset_reload_bios | |
| 141 | +What: /sys/devices/platform/mlxplat/mlxreg-io/hwmon/hwmon*/reset_sff_wd | |
| 142 | +What: /sys/devices/platform/mlxplat/mlxreg-io/hwmon/hwmon*/reset_swb_wd | |
| @@ -1,6 +1,6 @@ | ||
| 1 | 1 | What: /sys/kernel/debug/cec/*/error-inj |
| 2 | 2 | Date: March 2018 |
| 3 | −Contact: Hans Verkuil <hans.verkuil@cisco.com> | |
| 3 | +Contact: Hans Verkuil <hverkuil-cisco@xs4all.nl> | |
| 4 | 4 | Description: |
| 5 | 5 | |
| 6 | 6 | The CEC Framework allows for CEC error injection commands through |
| @@ -0,0 +1,56 @@ | ||
| 1 | +What: /sys/kernel/debug/<cros-ec-device>/console_log | |
| 2 | +Date: September 2017 | |
| 3 | +KernelVersion: 4.13 | |
| 4 | +Description: | |
| 5 | + If the EC supports the CONSOLE_READ command type, this file | |
| 6 | + can be used to grab the EC logs. The kernel polls for the log | |
| 7 | + and keeps its own buffer but userspace should grab this and | |
| 8 | + write it out to some logs. | |
| 9 | + | |
| 10 | +What: /sys/kernel/debug/<cros-ec-device>/panicinfo | |
| 11 | +Date: September 2017 | |
| 12 | +KernelVersion: 4.13 | |
| 13 | +Description: | |
| 14 | + This file dumps the EC panic information from the previous | |
| 15 | + reboot. This file will only exist if the PANIC_INFO command | |
| 16 | + type is supported by the EC. | |
| 17 | + | |
| 18 | +What: /sys/kernel/debug/<cros-ec-device>/pdinfo | |
| 19 | +Date: June 2018 | |
| 20 | +KernelVersion: 4.17 | |
| 21 | +Description: | |
| 22 | + This file provides the port role, muxes and power debug | |
| 23 | + information for all the USB PD/type-C ports available. If | |
| 24 | + the are no ports available, this file will be just an empty | |
| 25 | + file. | |
| 26 | + | |
| 27 | +What: /sys/kernel/debug/<cros-ec-device>/uptime | |
| 28 | +Date: June 2019 | |
| 29 | +KernelVersion: 5.3 | |
| 30 | +Description: | |
| 31 | + A u32 providing the time since EC booted in ms. This is | |
| 32 | + is used for synchronizing the AP host time with the EC | |
| 33 | + log. An error is returned if the command is not supported | |
| 34 | + by the EC or there is a communication problem. | |
| 35 | + | |
| 36 | +What: /sys/kernel/debug/<cros-ec-device>/last_resume_result | |
| 37 | +Date: June 2019 | |
| 38 | +KernelVersion: 5.3 | |
| 39 | +Description: | |
| 40 | + Some ECs have a feature where they will track transitions to | |
| 41 | + the (Intel) processor's SLP_S0 line, in order to detect cases | |
| 42 | + where a system failed to go into S0ix. When the system resumes, | |
| 43 | + an EC with this feature will return a summary of SLP_S0 | |
| 44 | + transitions that occurred. The last_resume_result file returns | |
| 45 | + the most recent response from the AP's resume message to the EC. | |
| 46 | + | |
| 47 | + The bottom 31 bits contain a count of the number of SLP_S0 | |
| 48 | + transitions that occurred since the suspend message was | |
| 49 | + received. Bit 31 is set if the EC attempted to wake the | |
| 50 | + system due to a timeout when watching for SLP_S0 transitions. | |
| 51 | + Callers can use this to detect a wake from the EC due to | |
| 52 | + S0ix timeouts. The result will be zero if no suspend | |
| 53 | + transitions have been attempted, or the EC does not support | |
| 54 | + this feature. | |
| 55 | + | |
| 56 | + Output will be in the format: "0x%08x\n". | |
| @@ -3,7 +3,10 @@ Date: Jan 2019 · 2 unmodified lines | ||
| 3 | 3 | KernelVersion: 5.1 |
| 4 | 4 | Contact: oded.gabbay@gmail.com |
| 5 | 5 | Description: Sets the device address to be used for read or write through |
| 6 | − PCI bar. The acceptable value is a string that starts with "0x" | |
| 6 | + PCI bar, or the device VA of a host mapped memory to be read or | |
| 7 | + written directly from the host. The latter option is allowed | |
| 8 | + only when the IOMMU is disabled. | |
| 9 | + The acceptable value is a string that starts with "0x" | |
| 7 | 10 | |
| 8 | 11 | What: /sys/kernel/debug/habanalabs/hl<n>/command_buffers |
| 9 | 12 | Date: Jan 2019 |
| @@ -33,10 +36,12 @@ Contact: oded.gabbay@gmail.com · 23 unmodified lines | ||
| 33 | 36 | Description: Allows the root user to read or write directly through the |
| 34 | 37 | device's PCI bar. Writing to this file generates a write |
| 35 | 38 | transaction while reading from the file generates a read |
| 36 | − transcation. This custom interface is needed (instead of using | |
| 39 | + transaction. This custom interface is needed (instead of using | |
| 37 | 40 | the generic Linux user-space PCI mapping) because the DDR bar |
| 38 | 41 | is very small compared to the DDR memory and only the driver can |
| 39 | − move the bar before and after the transaction | |
| 42 | + move the bar before and after the transaction. | |
| 43 | + If the IOMMU is disabled, it also allows the root user to read | |
| 44 | + or write from the host a device VA of a host mapped memory | |
| 40 | 45 | |
| 41 | 46 | What: /sys/kernel/debug/habanalabs/hl<n>/device |
| 42 | 47 | Date: Jan 2019 |
| @@ -46,6 +51,13 @@ Description: Enables the root user to set the device to specific state. · 3 unmodified lines | ||
| 46 | 51 | Valid values are "disable", "enable", "suspend", "resume". |
| 47 | 52 | User can read this property to see the valid values |
| 48 | 53 | |
| 54 | +What: /sys/kernel/debug/habanalabs/hl<n>/engines | |
| 55 | +Date: Jul 2019 | |
| 56 | +KernelVersion: 5.3 | |
| 57 | +Contact: oded.gabbay@gmail.com | |
| 58 | +Description: Displays the status registers values of the device engines and | |
| 59 | + their derived idle status | |
| 60 | + | |
| 49 | 61 | What: /sys/kernel/debug/habanalabs/hl<n>/i2c_addr |
| 50 | 62 | Date: Jan 2019 |
| 51 | 63 | KernelVersion: 5.1 |
| @@ -23,11 +23,9 @@ Description: · 22 unmodified lines | ||
| 23 | 23 | |
| 24 | 24 | For writing, bytes 0-1 indicate the message type, one of enum |
| 25 | 25 | wilco_ec_msg_type. Byte 2+ consist of the data passed in the |
| 26 | − request, starting at MBOX[0] | |
| 27 | − | |
| 28 | − At least three bytes are required for writing, two for the type | |
| 29 | − and at least a single byte of data. Only the first | |
| 30 | − EC_MAILBOX_DATA_SIZE bytes of MBOX will be used. | |
| 26 | + request, starting at MBOX[0]. At least three bytes are required | |
| 27 | + for writing, two for the type and at least a single byte of | |
| 28 | + data. | |
| 31 | 29 | |
| 32 | 30 | Example: |
| 33 | 31 | // Request EC info type 3 (EC firmware build date) |
| @@ -40,7 +38,7 @@ Description: · 6 unmodified lines | ||
| 40 | 38 | $ cat /sys/kernel/debug/wilco_ec/raw |
| 41 | 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 be | |
| 44 | − printed, even if some of the data is junk. It is up to you to | |
| 45 | − know how many of the first bytes of data are the actual | |
| 46 | − response. | |
| 41 | + Note that the first 16 bytes of the received MBOX[] will be | |
| 42 | + printed, even if some of the data is junk, and skipping bytes | |
| 43 | + 17 to 32. It is up to you to know how many of the first bytes of | |
| 44 | + data are the actual response. | |
| @@ -24,11 +24,11 @@ Description: · 23 unmodified lines | ||
| 24 | 24 | [euid=] [fowner=] [fsname=]] |
| 25 | 25 | lsm: [[subj_user=] [subj_role=] [subj_type=] |
| 26 | 26 | [obj_user=] [obj_role=] [obj_type=]] |
| 27 | − option: [[appraise_type=]] [permit_directio] | |
| 28 | − | |
| 27 | + option: [[appraise_type=]] [template=] [permit_directio] | |
| 29 | 28 | base: func:= [BPRM_CHECK][MMAP_CHECK][CREDS_CHECK][FILE_CHECK][MODULE_CHECK] |
| 30 | 29 | [FIRMWARE_CHECK] |
| 31 | 30 | [KEXEC_KERNEL_CHECK] [KEXEC_INITRAMFS_CHECK] |
| 31 | + [KEXEC_CMDLINE] | |
| 32 | 32 | mask:= [[^]MAY_READ] [[^]MAY_WRITE] [[^]MAY_APPEND] |
| 33 | 33 | [[^]MAY_EXEC] |
| 34 | 34 | fsmagic:= hex value |
| @@ -38,6 +38,8 @@ Description: · 3 unmodified lines | ||
| 38 | 38 | fowner:= decimal value |
| 39 | 39 | lsm: are LSM specific |
| 40 | 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 | 43 | pcr:= decimal value |
| 42 | 44 | |
| 43 | 45 | default policy: |
| @@ -29,4 +29,4 @@ Description: · 28 unmodified lines | ||
| 29 | 29 | 17 - sectors discarded |
| 30 | 30 | 18 - time spent discarding |
| 31 | 31 | |
| 32 | − For more details refer to Documentation/iostats.txt | |
| 32 | + For more details refer to Documentation/admin-guide/iostats.rst | |
| @@ -3,18 +3,28 @@ Date: August 2017 · 2 unmodified lines | ||
| 3 | 3 | Contact: Daniel Colascione <dancol@google.com> |
| 4 | 4 | Description: |
| 5 | 5 | 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 | 7 | except instead of an entry for each VMA in a process, |
| 8 | 8 | smaps_rollup has a single entry (tagged "[rollup]") |
| 9 | 9 | for which each field is the sum of the corresponding |
| 10 | 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 | 17 | Typical output looks like this: |
| 14 | 18 | |
| 15 | 19 | 00100000-ff709000 ---p 00000000 00:00 0 [rollup] |
| 20 | + Size: 1192 kB | |
| 21 | + KernelPageSize: 4 kB | |
| 22 | + MMUPageSize: 4 kB | |
| 16 | 23 | Rss: 884 kB |
| 17 | 24 | Pss: 385 kB |
| 25 | + Pss_Anon: 301 kB | |
| 26 | + Pss_File: 80 kB | |
| 27 | + Pss_Shmem: 4 kB | |
| 18 | 28 | Shared_Clean: 696 kB |
| 19 | 29 | Shared_Dirty: 0 kB |
| 20 | 30 | Private_Clean: 120 kB |
| @@ -1,6 +1,6 @@ | ||
| 1 | −Where: /sys/fs/pstore/... (or /dev/pstore/...) | |
| 1 | +What: /sys/fs/pstore/... (or /dev/pstore/...) | |
| 2 | 2 | Date: March 2011 |
| 3 | −Kernel Version: 2.6.39 | |
| 3 | +KernelVersion: 2.6.39 | |
| 4 | 4 | Contact: tony.luck@intel.com |
| 5 | 5 | Description: Generic interface to platform dependent persistent storage. |
| 6 | 6 | |
| @@ -15,7 +15,7 @@ Description: · 14 unmodified lines | ||
| 15 | 15 | 9 - I/Os currently in progress |
| 16 | 16 | 10 - time spent doing I/Os (ms) |
| 17 | 17 | 11 - weighted time spent doing I/Os (ms) |
| 18 | − For more details refer Documentation/iostats.txt | |
| 18 | + For more details refer Documentation/admin-guide/iostats.rst | |
| 19 | 19 | |
| 20 | 20 | |
| 21 | 21 | What: /sys/block/<disk>/<part>/stat |
| @@ -45,7 +45,7 @@ Description: · 44 unmodified lines | ||
| 45 | 45 | - Values below -2 are rejected with -EINVAL |
| 46 | 46 | |
| 47 | 47 | For more information, see |
| 48 | − Documentation/laptops/disk-shock-protection.txt | |
| 48 | + Documentation/admin-guide/laptops/disk-shock-protection.rst | |
| 49 | 49 | |
| 50 | 50 | |
| 51 | 51 | What: /sys/block/*/device/ncq_prio_enable |
| @@ -33,3 +33,26 @@ Description: Contains the PIM/PAM/POM values, as reported by the · 32 unmodified lines | ||
| 33 | 33 | in sync with the values current in the channel subsystem). |
| 34 | 34 | Note: This is an I/O-subchannel specific attribute. |
| 35 | 35 | Users: s390-tools, HAL |
| 36 | + | |
| 37 | +What: /sys/bus/css/devices/.../driver_override | |
| 38 | +Date: June 2019 | |
| 39 | +Contact: Cornelia Huck <cohuck@redhat.com> | |
| 40 | + linux-s390@vger.kernel.org | |
| 41 | +Description: This file allows the driver for a device to be specified. When | |
| 42 | + specified, only a driver with a name matching the value written | |
| 43 | + to driver_override will have an opportunity to bind to the | |
| 44 | + device. The override is specified by writing a string to the | |
| 45 | + driver_override file (echo vfio-ccw > driver_override) and | |
| 46 | + may be cleared with an empty string (echo > driver_override). | |
| 47 | + This returns the device to standard matching rules binding. | |
| 48 | + Writing to driver_override does not automatically unbind the | |
| 49 | + device from its current driver or make any attempt to | |
| 50 | + automatically load the specified driver. If no driver with a | |
| 51 | + matching name is currently loaded in the kernel, the device | |
| 52 | + will not bind to any driver. This also allows devices to | |
| 53 | + opt-out of driver binding using a driver_override name such as | |
| 54 | + "none". Only a single driver may be specified in the override, | |
| 55 | + there is no support for parsing delimiters. | |
| 56 | + Note that unlike the mechanism of the same name for pci, this | |
| 57 | + file does not allow to override basic matching rules. I.e., | |
| 58 | + the driver must still match the subchannel type of the device. | |
| @@ -1,6 +1,6 @@ | ||
| 1 | −Where: /sys/bus/event_source/devices/<dev>/format | |
| 1 | +What: /sys/bus/event_source/devices/<dev>/format | |
| 2 | 2 | Date: January 2012 |
| 3 | −Kernel Version: 3.3 | |
| 3 | +KernelVersion: 3.3 | |
| 4 | 4 | Contact: Jiri Olsa <jolsa@redhat.com> |
| 5 | 5 | Description: |
| 6 | 6 | Attribute group to describe the magic bits that go into |
| @@ -1,20 +1,20 @@ | ||
| 1 | −Where: /sys/bus/i2c/devices/.../heading0_input | |
| 1 | +What: /sys/bus/i2c/devices/.../heading0_input | |
| 2 | 2 | Date: April 2010 |
| 3 | −Kernel Version: 2.6.36? | |
| 3 | +KernelVersion: 2.6.36? | |
| 4 | 4 | Contact: alan.cox@intel.com |
| 5 | 5 | Description: Reports the current heading from the compass as a floating |
| 6 | 6 | point value in degrees. |
| 7 | 7 | |
| 8 | −Where: /sys/bus/i2c/devices/.../power_state | |
| 8 | +What: /sys/bus/i2c/devices/.../power_state | |
| 9 | 9 | Date: April 2010 |
| 10 | −Kernel Version: 2.6.36? | |
| 10 | +KernelVersion: 2.6.36? | |
| 11 | 11 | Contact: alan.cox@intel.com |
| 12 | 12 | Description: Sets the power state of the device. 0 sets the device into |
| 13 | 13 | sleep mode, 1 wakes it up. |
| 14 | 14 | |
| 15 | −Where: /sys/bus/i2c/devices/.../calibration | |
| 15 | +What: /sys/bus/i2c/devices/.../calibration | |
| 16 | 16 | Date: April 2010 |
| 17 | −Kernel Version: 2.6.36? | |
| 17 | +KernelVersion: 2.6.36? | |
| 18 | 18 | Contact: alan.cox@intel.com |
| 19 | 19 | Description: Sets the calibration on or off (1 = on, 0 = off). See the |
| 20 | 20 | chip data sheet. |
| @@ -61,8 +61,11 @@ What: /sys/bus/iio/devices/triggerX/sampling_frequency_available · 60 unmodified lines | ||
| 61 | 61 | KernelVersion: 2.6.35 |
| 62 | 62 | Contact: linux-iio@vger.kernel.org |
| 63 | 63 | Description: |
| 64 | − When the internal sampling clock can only take a small | |
| 65 | − discrete set of values, this file lists those available. | |
| 64 | + When the internal sampling clock can only take a specific set of | |
| 65 | + frequencies, we can specify the available values with: | |
| 66 | + - a small discrete set of values like "0 2 4 6 8" | |
| 67 | + - a range with minimum, step and maximum frequencies like | |
| 68 | + "[min step max]" | |
| 66 | 69 | |
| 67 | 70 | What: /sys/bus/iio/devices/iio:deviceX/oversampling_ratio |
| 68 | 71 | KernelVersion: 2.6.38 |
| @@ -18,11 +18,11 @@ Description: · 17 unmodified lines | ||
| 18 | 18 | values are 'base' and 'lid'. |
| 19 | 19 | |
| 20 | 20 | What: /sys/bus/iio/devices/iio:deviceX/id |
| 21 | −Date: Septembre 2017 | |
| 21 | +Date: September 2017 | |
| 22 | 22 | KernelVersion: 4.14 |
| 23 | 23 | Contact: linux-iio@vger.kernel.org |
| 24 | 24 | Description: |
| 25 | − This attribute is exposed by the CrOS EC legacy accelerometer | |
| 26 | − driver and represents the sensor ID as exposed by the EC. This | |
| 27 | − ID is used by the Android sensor service hardware abstraction | |
| 28 | − layer (sensor HAL) through the Android container on ChromeOS. | |
| 25 | + This attribute is exposed by the CrOS EC sensors driver and | |
| 26 | + represents the sensor ID as exposed by the EC. This ID is used | |
| 27 | + by the Android sensor service hardware abstraction layer (sensor | |
| 28 | + HAL) through the Android container on ChromeOS. | |
| @@ -1,4 +1,4 @@ | ||
| 1 | −What /sys/bus/iio/devices/iio:deviceX/sensor_sensitivity | |
| 1 | +What: /sys/bus/iio/devices/iio:deviceX/sensor_sensitivity | |
| 2 | 2 | Date: January 2017 |
| 3 | 3 | KernelVersion: 4.11 |
| 4 | 4 | Contact: linux-iio@vger.kernel.org |
| @@ -6,7 +6,7 @@ Description: · 1 unmodified line | ||
| 6 | 6 | Show or set the gain boost of the amp, from 0-31 range. |
| 7 | 7 | default 31 |
| 8 | 8 | |
| 9 | −What /sys/bus/iio/devices/iio:deviceX/sensor_max_range | |
| 9 | +What: /sys/bus/iio/devices/iio:deviceX/sensor_max_range | |
| 10 | 10 | Date: January 2017 |
| 11 | 11 | KernelVersion: 4.11 |
| 12 | 12 | Contact: linux-iio@vger.kernel.org |
| @@ -0,0 +1,44 @@ | ||
| 1 | +What: /sys/bus/iio/devices/iio:deviceX/out_altvoltageY_frequency | |
| 2 | +KernelVersion: | |
| 3 | +Contact: linux-iio@vger.kernel.org | |
| 4 | +Description: | |
| 5 | + Stores the PLL frequency in Hz for channel Y. | |
| 6 | + Reading returns the actual frequency in Hz. | |
| 7 | + The ADF4371 has an integrated VCO with fundamendal output | |
| 8 | + frequency ranging from 4000000000 Hz 8000000000 Hz. | |
| 9 | + | |
| 10 | + out_altvoltage0_frequency: | |
| 11 | + A divide by 1, 2, 4, 8, 16, 32 or circuit generates | |
| 12 | + frequencies from 62500000 Hz to 8000000000 Hz. | |
| 13 | + out_altvoltage1_frequency: | |
| 14 | + This channel duplicates the channel 0 frequency | |
| 15 | + out_altvoltage2_frequency: | |
| 16 | + A frequency doubler generates frequencies from | |
| 17 | + 8000000000 Hz to 16000000000 Hz. | |
| 18 | + out_altvoltage3_frequency: | |
| 19 | + A frequency quadrupler generates frequencies from | |
| 20 | + 16000000000 Hz to 32000000000 Hz. | |
| 21 | + | |
| 22 | + Note: writes to one of the channels will affect the frequency of | |
| 23 | + all the other channels, since it involves changing the VCO | |
| 24 | + fundamental output frequency. | |
| 25 | + | |
| 26 | +What: /sys/bus/iio/devices/iio:deviceX/out_altvoltageY_name | |
| 27 | +KernelVersion: | |
| 28 | +Contact: linux-iio@vger.kernel.org | |
| 29 | +Description: | |
| 30 | + Reading returns the datasheet name for channel Y: | |
| 31 | + | |
| 32 | + out_altvoltage0_name: RF8x | |
| 33 | + out_altvoltage1_name: RFAUX8x | |
| 34 | + out_altvoltage2_name: RF16x | |
| 35 | + out_altvoltage3_name: RF32x | |
| 36 | + | |
| 37 | +What: /sys/bus/iio/devices/iio:deviceX/out_altvoltageY_powerdown | |
| 38 | +KernelVersion: | |
| 39 | +Contact: linux-iio@vger.kernel.org | |
| 40 | +Description: | |
| 41 | + This attribute allows the user to power down the PLL and it's | |
| 42 | + RFOut buffers. | |
| 43 | + Writing 1 causes the specified channel to power down. | |
| 44 | + Clearing returns to normal operation. | |
| @@ -1,4 +1,4 @@ | ||
| 1 | −What /sys/bus/iio/devices/iio:deviceX/in_proximity_input | |
| 1 | +What: /sys/bus/iio/devices/iio:deviceX/in_proximity_input | |
| 2 | 2 | Date: March 2014 |
| 3 | 3 | KernelVersion: 3.15 |
| 4 | 4 | Contact: Matt Ranostay <matt.ranostay@konsulko.com> |
| @@ -6,7 +6,7 @@ Description: · 1 unmodified line | ||
| 6 | 6 | Get the current distance in meters of storm (1km steps) |
| 7 | 7 | 1000-40000 = distance in meters |
| 8 | 8 | |
| 9 | −What /sys/bus/iio/devices/iio:deviceX/sensor_sensitivity | |
| 9 | +What: /sys/bus/iio/devices/iio:deviceX/sensor_sensitivity | |
| 10 | 10 | Date: March 2014 |
| 11 | 11 | KernelVersion: 3.15 |
| 12 | 12 | Contact: Matt Ranostay <matt.ranostay@konsulko.com> |
| @@ -9,9 +9,9 @@ errors may be "seen" / reported by the link partner and not the · 8 unmodified lines | ||
| 9 | 9 | problematic endpoint itself (which may report all counters as 0 as it never |
| 10 | 10 | saw any problems). |
| 11 | 11 | |
| 12 | −Where: /sys/bus/pci/devices/<dev>/aer_dev_correctable | |
| 12 | +What: /sys/bus/pci/devices/<dev>/aer_dev_correctable | |
| 13 | 13 | Date: July 2018 |
| 14 | −Kernel Version: 4.19.0 | |
| 14 | +KernelVersion: 4.19.0 | |
| 15 | 15 | Contact: linux-pci@vger.kernel.org, rajatja@google.com |
| 16 | 16 | Description: List of correctable errors seen and reported by this |
| 17 | 17 | PCI device using ERR_COR. Note that since multiple errors may |
| @@ -31,9 +31,9 @@ Header Log Overflow 0 · 13 unmodified lines | ||
| 31 | 31 | TOTAL_ERR_COR 2 |
| 32 | 32 | ------------------------------------------------------------------------- |
| 33 | 33 | |
| 34 | −Where: /sys/bus/pci/devices/<dev>/aer_dev_fatal | |
| 34 | +What: /sys/bus/pci/devices/<dev>/aer_dev_fatal | |
| 35 | 35 | Date: July 2018 |
| 36 | −Kernel Version: 4.19.0 | |
| 36 | +KernelVersion: 4.19.0 | |
| 37 | 37 | Contact: linux-pci@vger.kernel.org, rajatja@google.com |
| 38 | 38 | Description: List of uncorrectable fatal errors seen and reported by this |
| 39 | 39 | PCI device using ERR_FATAL. Note that since multiple errors may |
| @@ -62,9 +62,9 @@ TLP Prefix Blocked Error 0 · 22 unmodified lines | ||
| 62 | 62 | TOTAL_ERR_FATAL 0 |
| 63 | 63 | ------------------------------------------------------------------------- |
| 64 | 64 | |
| 65 | −Where: /sys/bus/pci/devices/<dev>/aer_dev_nonfatal | |
| 65 | +What: /sys/bus/pci/devices/<dev>/aer_dev_nonfatal | |
| 66 | 66 | Date: July 2018 |
| 67 | −Kernel Version: 4.19.0 | |
| 67 | +KernelVersion: 4.19.0 | |
| 68 | 68 | Contact: linux-pci@vger.kernel.org, rajatja@google.com |
| 69 | 69 | Description: List of uncorrectable nonfatal errors seen and reported by this |
| 70 | 70 | 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 | ||
| 103 | 103 | device, so these counters include them and are thus cumulative of all the error |
| 104 | 104 | messages on the PCI hierarchy originating at that root port. |
| 105 | 105 | |
| 106 | −Where: /sys/bus/pci/devices/<dev>/aer_stats/aer_rootport_total_err_cor | |
| 106 | +What: /sys/bus/pci/devices/<dev>/aer_stats/aer_rootport_total_err_cor | |
| 107 | 107 | Date: July 2018 |
| 108 | −Kernel Version: 4.19.0 | |
| 108 | +KernelVersion: 4.19.0 | |
| 109 | 109 | Contact: linux-pci@vger.kernel.org, rajatja@google.com |
| 110 | 110 | Description: Total number of ERR_COR messages reported to rootport. |
| 111 | 111 | |
| 112 | −Where: /sys/bus/pci/devices/<dev>/aer_stats/aer_rootport_total_err_fatal | |
| 112 | +What: /sys/bus/pci/devices/<dev>/aer_stats/aer_rootport_total_err_fatal | |
| 113 | 113 | Date: July 2018 |
| 114 | −Kernel Version: 4.19.0 | |
| 114 | +KernelVersion: 4.19.0 | |
| 115 | 115 | Contact: linux-pci@vger.kernel.org, rajatja@google.com |
| 116 | 116 | Description: Total number of ERR_FATAL messages reported to rootport. |
| 117 | 117 | |
| 118 | −Where: /sys/bus/pci/devices/<dev>/aer_stats/aer_rootport_total_err_nonfatal | |
| 118 | +What: /sys/bus/pci/devices/<dev>/aer_stats/aer_rootport_total_err_nonfatal | |
| 119 | 119 | Date: July 2018 |
| 120 | −Kernel Version: 4.19.0 | |
| 120 | +KernelVersion: 4.19.0 | |
| 121 | 121 | Contact: linux-pci@vger.kernel.org, rajatja@google.com |
| 122 | 122 | Description: Total number of ERR_NONFATAL messages reported to rootport. |
| @@ -1,68 +1,68 @@ | ||
| 1 | −Where: /sys/bus/pci/devices/<dev>/ccissX/cXdY/model | |
| 1 | +What: /sys/bus/pci/devices/<dev>/ccissX/cXdY/model | |
| 2 | 2 | Date: March 2009 |
| 3 | −Kernel Version: 2.6.30 | |
| 3 | +KernelVersion: 2.6.30 | |
| 4 | 4 | Contact: iss_storagedev@hp.com |
| 5 | 5 | Description: Displays the SCSI INQUIRY page 0 model for logical drive |
| 6 | 6 | Y of controller X. |
| 7 | 7 | |
| 8 | −Where: /sys/bus/pci/devices/<dev>/ccissX/cXdY/rev | |
| 8 | +What: /sys/bus/pci/devices/<dev>/ccissX/cXdY/rev | |
| 9 | 9 | Date: March 2009 |
| 10 | −Kernel Version: 2.6.30 | |
| 10 | +KernelVersion: 2.6.30 | |
| 11 | 11 | Contact: iss_storagedev@hp.com |
| 12 | 12 | Description: Displays the SCSI INQUIRY page 0 revision for logical |
| 13 | 13 | drive Y of controller X. |
| 14 | 14 | |
| 15 | −Where: /sys/bus/pci/devices/<dev>/ccissX/cXdY/unique_id | |
| 15 | +What: /sys/bus/pci/devices/<dev>/ccissX/cXdY/unique_id | |
| 16 | 16 | Date: March 2009 |
| 17 | −Kernel Version: 2.6.30 | |
| 17 | +KernelVersion: 2.6.30 | |
| 18 | 18 | Contact: iss_storagedev@hp.com |
| 19 | 19 | Description: Displays the SCSI INQUIRY page 83 serial number for logical |
| 20 | 20 | drive Y of controller X. |
| 21 | 21 | |
| 22 | −Where: /sys/bus/pci/devices/<dev>/ccissX/cXdY/vendor | |
| 22 | +What: /sys/bus/pci/devices/<dev>/ccissX/cXdY/vendor | |
| 23 | 23 | Date: March 2009 |
| 24 | −Kernel Version: 2.6.30 | |
| 24 | +KernelVersion: 2.6.30 | |
| 25 | 25 | Contact: iss_storagedev@hp.com |
| 26 | 26 | Description: Displays the SCSI INQUIRY page 0 vendor for logical drive |
| 27 | 27 | Y of controller X. |
| 28 | 28 | |
| 29 | −Where: /sys/bus/pci/devices/<dev>/ccissX/cXdY/block:cciss!cXdY | |
| 29 | +What: /sys/bus/pci/devices/<dev>/ccissX/cXdY/block:cciss!cXdY | |
| 30 | 30 | Date: March 2009 |
| 31 | −Kernel Version: 2.6.30 | |
| 31 | +KernelVersion: 2.6.30 | |
| 32 | 32 | Contact: iss_storagedev@hp.com |
| 33 | 33 | Description: A symbolic link to /sys/block/cciss!cXdY |
| 34 | 34 | |
| 35 | −Where: /sys/bus/pci/devices/<dev>/ccissX/rescan | |
| 35 | +What: /sys/bus/pci/devices/<dev>/ccissX/rescan | |
| 36 | 36 | Date: August 2009 |
| 37 | −Kernel Version: 2.6.31 | |
| 37 | +KernelVersion: 2.6.31 | |
| 38 | 38 | Contact: iss_storagedev@hp.com |
| 39 | 39 | Description: Kicks of a rescan of the controller to discover logical |
| 40 | 40 | drive topology changes. |
| 41 | 41 | |
| 42 | −Where: /sys/bus/pci/devices/<dev>/ccissX/cXdY/lunid | |
| 42 | +What: /sys/bus/pci/devices/<dev>/ccissX/cXdY/lunid | |
| 43 | 43 | Date: August 2009 |
| 44 | −Kernel Version: 2.6.31 | |
| 44 | +KernelVersion: 2.6.31 | |
| 45 | 45 | Contact: iss_storagedev@hp.com |
| 46 | 46 | Description: Displays the 8-byte LUN ID used to address logical |
| 47 | 47 | drive Y of controller X. |
| 48 | 48 | |
| 49 | −Where: /sys/bus/pci/devices/<dev>/ccissX/cXdY/raid_level | |
| 49 | +What: /sys/bus/pci/devices/<dev>/ccissX/cXdY/raid_level | |
| 50 | 50 | Date: August 2009 |
| 51 | −Kernel Version: 2.6.31 | |
| 51 | +KernelVersion: 2.6.31 | |
| 52 | 52 | Contact: iss_storagedev@hp.com |
| 53 | 53 | Description: Displays the RAID level of logical drive Y of |
| 54 | 54 | controller X. |
| 55 | 55 | |
| 56 | −Where: /sys/bus/pci/devices/<dev>/ccissX/cXdY/usage_count | |
| 56 | +What: /sys/bus/pci/devices/<dev>/ccissX/cXdY/usage_count | |
| 57 | 57 | Date: August 2009 |
| 58 | −Kernel Version: 2.6.31 | |
| 58 | +KernelVersion: 2.6.31 | |
| 59 | 59 | Contact: iss_storagedev@hp.com |
| 60 | 60 | Description: Displays the usage count (number of opens) of logical drive Y |
| 61 | 61 | of controller X. |
| 62 | 62 | |
| 63 | −Where: /sys/bus/pci/devices/<dev>/ccissX/resettable | |
| 63 | +What: /sys/bus/pci/devices/<dev>/ccissX/resettable | |
| 64 | 64 | Date: February 2011 |
| 65 | −Kernel Version: 2.6.38 | |
| 65 | +KernelVersion: 2.6.38 | |
| 66 | 66 | Contact: iss_storagedev@hp.com |
| 67 | 67 | Description: Value of 1 indicates the controller can honor the reset_devices |
| 68 | 68 | 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 | 71 | a dump device, as kdump requires resetting the device in order |
| 72 | 72 | to work reliably. |
| 73 | 73 | |
| 74 | −Where: /sys/bus/pci/devices/<dev>/ccissX/transport_mode | |
| 74 | +What: /sys/bus/pci/devices/<dev>/ccissX/transport_mode | |
| 75 | 75 | Date: July 2011 |
| 76 | −Kernel Version: 3.0 | |
| 76 | +KernelVersion: 3.0 | |
| 77 | 77 | Contact: iss_storagedev@hp.com |
| 78 | 78 | Description: Value of "simple" indicates that the controller has been placed |
| 79 | 79 | in "simple mode". Value of "performant" indicates that the |
| @@ -1,6 +1,6 @@ | ||
| 1 | 1 | What: /sys/bus/siox/devices/siox-X/active |
| 2 | 2 | KernelVersion: 4.16 |
| 3 | −Contact: Gavin Schenk <g.schenk@eckelmann.de>, Uwe Kleine-König <u.kleine-koenig@pengutronix.de> | |
| 3 | +Contact: Thorsten Scherer <t.scherer@eckelmann.de>, Uwe Kleine-König <u.kleine-koenig@pengutronix.de> | |
| 4 | 4 | Description: |
| 5 | 5 | On reading represents the current state of the bus. If it |
| 6 | 6 | contains a "0" the bus is stopped and connected devices are |
| @@ -12,7 +12,7 @@ Description: · 5 unmodified lines | ||
| 12 | 12 | |
| 13 | 13 | What: /sys/bus/siox/devices/siox-X/device_add |
| 14 | 14 | KernelVersion: 4.16 |
| 15 | −Contact: Gavin Schenk <g.schenk@eckelmann.de>, Uwe Kleine-König <u.kleine-koenig@pengutronix.de> | |
| 15 | +Contact: Thorsten Scherer <t.scherer@eckelmann.de>, Uwe Kleine-König <u.kleine-koenig@pengutronix.de> | |
| 16 | 16 | Description: |
| 17 | 17 | Write-only file. Write |
| 18 | 18 | |
| @@ -27,13 +27,13 @@ Description: · 8 unmodified lines | ||
| 27 | 27 | |
| 28 | 28 | What: /sys/bus/siox/devices/siox-X/device_remove |
| 29 | 29 | KernelVersion: 4.16 |
| 30 | −Contact: Gavin Schenk <g.schenk@eckelmann.de>, Uwe Kleine-König <u.kleine-koenig@pengutronix.de> | |
| 30 | +Contact: Thorsten Scherer <t.scherer@eckelmann.de>, Uwe Kleine-König <u.kleine-koenig@pengutronix.de> | |
| 31 | 31 | Description: |
| 32 | 32 | Write-only file. A single write removes the last device in the siox chain. |
| 33 | 33 | |
| 34 | 34 | What: /sys/bus/siox/devices/siox-X/poll_interval_ns |
| 35 | 35 | KernelVersion: 4.16 |
| 36 | −Contact: Gavin Schenk <g.schenk@eckelmann.de>, Uwe Kleine-König <u.kleine-koenig@pengutronix.de> | |
| 36 | +Contact: Thorsten Scherer <t.scherer@eckelmann.de>, Uwe Kleine-König <u.kleine-koenig@pengutronix.de> | |
| 37 | 37 | Description: |
| 38 | 38 | Defines the interval between two poll cycles in nano seconds. |
| 39 | 39 | Note this is rounded to jiffies on writing. On reading the current value |
| @@ -41,33 +41,33 @@ Description: · 1 unmodified line | ||
| 41 | 41 | |
| 42 | 42 | What: /sys/bus/siox/devices/siox-X-Y/connected |
| 43 | 43 | KernelVersion: 4.16 |
| 44 | −Contact: Gavin Schenk <g.schenk@eckelmann.de>, Uwe Kleine-König <u.kleine-koenig@pengutronix.de> | |
| 44 | +Contact: Thorsten Scherer <t.scherer@eckelmann.de>, Uwe Kleine-König <u.kleine-koenig@pengutronix.de> | |
| 45 | 45 | Description: |
| 46 | 46 | Read-only value. "0" means the Yth device on siox bus X isn't "connected" i.e. |
| 47 | 47 | communication with it is not ensured. "1" signals a working connection. |
| 48 | 48 | |
| 49 | 49 | What: /sys/bus/siox/devices/siox-X-Y/inbytes |
| 50 | 50 | KernelVersion: 4.16 |
| 51 | −Contact: Gavin Schenk <g.schenk@eckelmann.de>, Uwe Kleine-König <u.kleine-koenig@pengutronix.de> | |
| 51 | +Contact: Thorsten Scherer <t.scherer@eckelmann.de>, Uwe Kleine-König <u.kleine-koenig@pengutronix.de> | |
| 52 | 52 | Description: |
| 53 | 53 | Read-only value reporting the inbytes value provided to siox-X/device_add |
| 54 | 54 | |
| 55 | 55 | What: /sys/bus/siox/devices/siox-X-Y/status_errors |
| 56 | 56 | KernelVersion: 4.16 |
| 57 | −Contact: Gavin Schenk <g.schenk@eckelmann.de>, Uwe Kleine-König <u.kleine-koenig@pengutronix.de> | |
| 57 | +Contact: Thorsten Scherer <t.scherer@eckelmann.de>, Uwe Kleine-König <u.kleine-koenig@pengutronix.de> | |
| 58 | 58 | Description: |
| 59 | 59 | Counts the number of time intervals when the read status byte doesn't yield the |
| 60 | 60 | expected value. |
| 61 | 61 | |
| 62 | 62 | What: /sys/bus/siox/devices/siox-X-Y/type |
| 63 | 63 | KernelVersion: 4.16 |
| 64 | −Contact: Gavin Schenk <g.schenk@eckelmann.de>, Uwe Kleine-König <u.kleine-koenig@pengutronix.de> | |
| 64 | +Contact: Thorsten Scherer <t.scherer@eckelmann.de>, Uwe Kleine-König <u.kleine-koenig@pengutronix.de> | |
| 65 | 65 | Description: |
| 66 | 66 | Read-only value reporting the type value provided to siox-X/device_add. |
| 67 | 67 | |
| 68 | 68 | What: /sys/bus/siox/devices/siox-X-Y/watchdog |
| 69 | 69 | KernelVersion: 4.16 |
| 70 | −Contact: Gavin Schenk <g.schenk@eckelmann.de>, Uwe Kleine-König <u.kleine-koenig@pengutronix.de> | |
| 70 | +Contact: Thorsten Scherer <t.scherer@eckelmann.de>, Uwe Kleine-König <u.kleine-koenig@pengutronix.de> | |
| 71 | 71 | Description: |
| 72 | 72 | Read-only value reporting if the watchdog of the siox device is |
| 73 | 73 | active. "0" means the watchdog is not active and the device is expected to |
| @@ -75,13 +75,13 @@ Description: · 1 unmodified line | ||
| 75 | 75 | |
| 76 | 76 | What: /sys/bus/siox/devices/siox-X-Y/watchdog_errors |
| 77 | 77 | KernelVersion: 4.16 |
| 78 | −Contact: Gavin Schenk <g.schenk@eckelmann.de>, Uwe Kleine-König <u.kleine-koenig@pengutronix.de> | |
| 78 | +Contact: Thorsten Scherer <t.scherer@eckelmann.de>, Uwe Kleine-König <u.kleine-koenig@pengutronix.de> | |
| 79 | 79 | Description: |
| 80 | 80 | Read-only value reporting the number to time intervals when the |
| 81 | 81 | watchdog was active. |
| 82 | 82 | |
| 83 | 83 | What: /sys/bus/siox/devices/siox-X-Y/outbytes |
| 84 | 84 | KernelVersion: 4.16 |
| 85 | −Contact: Gavin Schenk <g.schenk@eckelmann.de>, Uwe Kleine-König <u.kleine-koenig@pengutronix.de> | |
| 85 | +Contact: Thorsten Scherer <t.scherer@eckelmann.de>, Uwe Kleine-König <u.kleine-koenig@pengutronix.de> | |
| 86 | 86 | Description: |
| 87 | 87 | Read-only value reporting the outbytes value provided to siox-X/device_add. |
| @@ -1,14 +1,14 @@ | ||
| 1 | −Where: /sys/bus/usb/.../powered | |
| 1 | +What: /sys/bus/usb/.../powered | |
| 2 | 2 | Date: August 2008 |
| 3 | −Kernel Version: 2.6.26 | |
| 3 | +KernelVersion: 2.6.26 | |
| 4 | 4 | Contact: Harrison Metzger <harrisonmetz@gmail.com> |
| 5 | 5 | Description: Controls whether the device's display will powered. |
| 6 | 6 | A value of 0 is off and a non-zero value is on. |
| 7 | 7 | |
| 8 | −Where: /sys/bus/usb/.../mode_msb | |
| 9 | −Where: /sys/bus/usb/.../mode_lsb | |
| 8 | +What: /sys/bus/usb/.../mode_msb | |
| 9 | +What: /sys/bus/usb/.../mode_lsb | |
| 10 | 10 | Date: August 2008 |
| 11 | −Kernel Version: 2.6.26 | |
| 11 | +KernelVersion: 2.6.26 | |
| 12 | 12 | Contact: Harrison Metzger <harrisonmetz@gmail.com> |
| 13 | 13 | Description: Controls the devices display mode. |
| 14 | 14 | For a 6 character display the values are |
| @@ -16,24 +16,24 @@ Description: Controls the devices display mode. · 1 unmodified line | ||
| 16 | 16 | for an 8 character display the values are |
| 17 | 17 | MSB 0x08; LSB 0xFF. |
| 18 | 18 | |
| 19 | −Where: /sys/bus/usb/.../textmode | |
| 19 | +What: /sys/bus/usb/.../textmode | |
| 20 | 20 | Date: August 2008 |
| 21 | −Kernel Version: 2.6.26 | |
| 21 | +KernelVersion: 2.6.26 | |
| 22 | 22 | Contact: Harrison Metzger <harrisonmetz@gmail.com> |
| 23 | 23 | Description: Controls the way the device interprets its text buffer. |
| 24 | 24 | raw: each character controls its segment manually |
| 25 | 25 | hex: each character is between 0-15 |
| 26 | 26 | ascii: each character is between '0'-'9' and 'A'-'F'. |
| 27 | 27 | |
| 28 | −Where: /sys/bus/usb/.../text | |
| 28 | +What: /sys/bus/usb/.../text | |
| 29 | 29 | Date: August 2008 |
| 30 | −Kernel Version: 2.6.26 | |
| 30 | +KernelVersion: 2.6.26 | |
| 31 | 31 | Contact: Harrison Metzger <harrisonmetz@gmail.com> |
| 32 | 32 | Description: The text (or data) for the device to display |
| 33 | 33 | |
| 34 | −Where: /sys/bus/usb/.../decimals | |
| 34 | +What: /sys/bus/usb/.../decimals | |
| 35 | 35 | Date: August 2008 |
| 36 | −Kernel Version: 2.6.26 | |
| 36 | +KernelVersion: 2.6.26 | |
| 37 | 37 | Contact: Harrison Metzger <harrisonmetz@gmail.com> |
| 38 | 38 | Description: Controls the decimal places on the device. |
| 39 | 39 | To set the nth decimal place, give this field |
| @@ -4,7 +4,7 @@ KernelVersion: 3.5 · 3 unmodified lines | ||
| 4 | 4 | Contact: Johan Hovold <jhovold@gmail.com> |
| 5 | 5 | Description: |
| 6 | 6 | Get the ALS output channel used as input in |
| 7 | − ALS-current-control mode (0, 1), where | |
| 7 | + ALS-current-control mode (0, 1), where: | |
| 8 | 8 | |
| 9 | 9 | 0 - out_current0 (backlight 0) |
| 10 | 10 | 1 - out_current1 (backlight 1) |
| @@ -28,7 +28,7 @@ Date: April 2012 · 17 unmodified lines | ||
| 28 | 28 | KernelVersion: 3.5 |
| 29 | 29 | Contact: Johan Hovold <jhovold@gmail.com> |
| 30 | 30 | Description: |
| 31 | − Set the brightness-mapping mode (0, 1), where | |
| 31 | + Set the brightness-mapping mode (0, 1), where: | |
| 32 | 32 | |
| 33 | 33 | 0 - exponential mode |
| 34 | 34 | 1 - linear mode |
| @@ -38,7 +38,7 @@ Date: April 2012 · 3 unmodified lines | ||
| 38 | 38 | KernelVersion: 3.5 |
| 39 | 39 | Contact: Johan Hovold <jhovold@gmail.com> |
| 40 | 40 | Description: |
| 41 | − Set the PWM-input control mask (5 bits), where | |
| 41 | + Set the PWM-input control mask (5 bits), where: | |
| 42 | 42 | |
| 43 | 43 | bit 5 - PWM-input enabled in Zone 4 |
| 44 | 44 | bit 4 - PWM-input enabled in Zone 3 |
| @@ -1,6 +1,6 @@ | ||
| 1 | −Note: Attributes that are shared between devices are stored in the directory | |
| 2 | −pointed to by the symlink device/. | |
| 3 | −Example: The real path of the attribute /sys/class/cxl/afu0.0s/irqs_max is | |
| 1 | +Please note that attributes that are shared between devices are stored in | |
| 2 | +the directory pointed to by the symlink device/. | |
| 3 | +For example, the real path of the attribute /sys/class/cxl/afu0.0s/irqs_max is | |
| 4 | 4 | /sys/class/cxl/afu0.0s/device/irqs_max, i.e. /sys/class/cxl/afu0.0/irqs_max. |
| 5 | 5 | |
| 6 | 6 | |
| @@ -47,7 +47,7 @@ Description: · 46 unmodified lines | ||
| 47 | 47 | What: /sys/class/devfreq/.../trans_stat |
| 48 | 48 | Date: October 2012 |
| 49 | 49 | Contact: MyungJoo Ham <myungjoo.ham@samsung.com> |
| 50 | −Descrtiption: | |
| 50 | +Description: | |
| 51 | 51 | This ABI shows the statistics of devfreq behavior on a |
| 52 | 52 | specific device. It shows the time spent in each state and |
| 53 | 53 | the number of transitions between states. |
| @@ -4,7 +4,7 @@ KernelVersion: 3.5 · 3 unmodified lines | ||
| 4 | 4 | Contact: Johan Hovold <jhovold@gmail.com> |
| 5 | 5 | Description: |
| 6 | 6 | Set the ALS output channel to use as input in |
| 7 | − ALS-current-control mode (1, 2), where | |
| 7 | + ALS-current-control mode (1, 2), where: | |
| 8 | 8 | |
| 9 | 9 | 1 - out_current1 |
| 10 | 10 | 2 - out_current2 |
| @@ -22,7 +22,7 @@ Date: April 2012 · 11 unmodified lines | ||
| 22 | 22 | KernelVersion: 3.5 |
| 23 | 23 | Contact: Johan Hovold <jhovold@gmail.com> |
| 24 | 24 | Description: |
| 25 | − Set the pattern generator fall and rise times (0..7), where | |
| 25 | + Set the pattern generator fall and rise times (0..7), where: | |
| 26 | 26 | |
| 27 | 27 | 0 - 2048 us |
| 28 | 28 | 1 - 262 ms |
| @@ -45,7 +45,7 @@ Date: April 2012 · 16 unmodified lines | ||
| 45 | 45 | KernelVersion: 3.5 |
| 46 | 46 | Contact: Johan Hovold <jhovold@gmail.com> |
| 47 | 47 | Description: |
| 48 | − Set the brightness-mapping mode (0, 1), where | |
| 48 | + Set the brightness-mapping mode (0, 1), where: | |
| 49 | 49 | |
| 50 | 50 | 0 - exponential mode |
| 51 | 51 | 1 - linear mode |
| @@ -55,7 +55,7 @@ Date: April 2012 · 3 unmodified lines | ||
| 55 | 55 | KernelVersion: 3.5 |
| 56 | 56 | Contact: Johan Hovold <jhovold@gmail.com> |
| 57 | 57 | Description: |
| 58 | − Set the PWM-input control mask (5 bits), where | |
| 58 | + Set the PWM-input control mask (5 bits), where: | |
| 59 | 59 | |
| 60 | 60 | bit 5 - PWM-input enabled in Zone 4 |
| 61 | 61 | bit 4 - PWM-input enabled in Zone 3 |
| @@ -5,7 +5,7 @@ Contact: Janne Kanniainen <janne.kanniainen@gmail.com> · 4 unmodified lines | ||
| 5 | 5 | Description: |
| 6 | 6 | Set the mode of LEDs. You should notice that changing the mode |
| 7 | 7 | of one LED will update the mode of its two sibling devices as |
| 8 | − well. | |
| 8 | + well. Possible values are: | |
| 9 | 9 | |
| 10 | 10 | 0 - normal |
| 11 | 11 | 1 - audio |
| @@ -13,4 +13,4 @@ Description: · 1 unmodified line | ||
| 13 | 13 | |
| 14 | 14 | Normal: LEDs are fully on when enabled |
| 15 | 15 | Audio: LEDs brightness depends on sound level |
| 16 | − Breathing: LEDs brightness varies at human breathing rate | |
| 16 | + Breathing: LEDs brightness varies at human breathing rate | |
| @@ -41,3 +41,11 @@ Description: · 40 unmodified lines | ||
| 41 | 41 | xgmii, moca, qsgmii, trgmii, 1000base-x, 2500base-x, rxaui, |
| 42 | 42 | xaui, 10gbase-kr, unknown |
| 43 | 43 | |
| 44 | +What: /sys/class/mdio_bus/<bus>/<device>/phy_standalone | |
| 45 | +Date: May 2019 | |
| 46 | +KernelVersion: 5.3 | |
| 47 | +Contact: netdev@vger.kernel.org | |
| 48 | +Description: | |
| 49 | + Boolean value indicating whether the PHY device is used in | |
| 50 | + standalone mode, without a net_device associated, by PHYLINK. | |
| 51 | + Attribute created only when this is the case. | |
| @@ -29,7 +29,7 @@ Contact: Bjørn Mork <bjorn@mork.no> · 28 unmodified lines | ||
| 29 | 29 | Description: |
| 30 | 30 | Unsigned integer. |
| 31 | 31 | |
| 32 | − Write a number ranging from 1 to 127 to add a qmap mux | |
| 32 | + Write a number ranging from 1 to 254 to add a qmap mux | |
| 33 | 33 | based network device, supported by recent Qualcomm based |
| 34 | 34 | modems. |
| 35 | 35 | |
| @@ -46,5 +46,5 @@ Contact: Bjørn Mork <bjorn@mork.no> · 10 unmodified lines | ||
| 46 | 46 | Description: |
| 47 | 47 | Unsigned integer. |
| 48 | 48 | |
| 49 | − Write a number ranging from 1 to 127 to delete a previously | |
| 49 | + Write a number ranging from 1 to 254 to delete a previously | |
| 50 | 50 | created qmap mux based network device. |
| @@ -376,10 +376,42 @@ Description: · 375 unmodified lines | ||
| 376 | 376 | supply. Normally this is configured based on the type of |
| 377 | 377 | connection made (e.g. A configured SDP should output a maximum |
| 378 | 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 | 382 | Access: Read, Write |
| 381 | 383 | Valid values: Represented in microamps |
| 382 | 384 | |
| 385 | +What: /sys/class/power_supply/<supply_name>/input_voltage_limit | |
| 386 | +Date: May 2019 | |
| 387 | +Contact: linux-pm@vger.kernel.org | |
| 388 | +Description: | |
| 389 | + This entry configures the incoming VBUS voltage limit currently | |
| 390 | + set in the supply. Normally this is configured based on | |
| 391 | + system-level knowledge or user input (e.g. This is part of the | |
| 392 | + Pixel C's thermal management strategy to effectively limit the | |
| 393 | + input power to 5V when the screen is on to meet Google's skin | |
| 394 | + temperature targets). Note that this feature should not be | |
| 395 | + used for safety critical things. | |
| 396 | + Use preferably input_power_limit, and for problems that can be | |
| 397 | + solved using power limit use input_voltage_limit. | |
| 398 | + | |
| 399 | + Access: Read, Write | |
| 400 | + Valid values: Represented in microvolts | |
| 401 | + | |
| 402 | +What: /sys/class/power_supply/<supply_name>/input_power_limit | |
| 403 | +Date: May 2019 | |
| 404 | +Contact: linux-pm@vger.kernel.org | |
| 405 | +Description: | |
| 406 | + This entry configures the incoming power limit currently set | |
| 407 | + in the supply. Normally this is configured based on | |
| 408 | + system-level knowledge or user input. Use preferably this | |
| 409 | + feature to limit the incoming power and use current/voltage | |
| 410 | + limit only for problems that can be solved using power limit. | |
| 411 | + | |
| 412 | + Access: Read, Write | |
| 413 | + Valid values: Represented in microwatts | |
| 414 | + | |
| 383 | 415 | What: /sys/class/power_supply/<supply_name>/online, |
| 384 | 416 | Date: May 2007 |
| 385 | 417 | Contact: linux-pm@vger.kernel.org |
| @@ -0,0 +1,30 @@ | ||
| 1 | +What: /sys/class/power_supply/wilco-charger/charge_type | |
| 2 | +Date: April 2019 | |
| 3 | +KernelVersion: 5.2 | |
| 4 | +Description: | |
| 5 | + What charging algorithm to use: | |
| 6 | + | |
| 7 | + Standard: Fully charges battery at a standard rate. | |
| 8 | + Adaptive: Battery settings adaptively optimized based on | |
| 9 | + typical battery usage pattern. | |
| 10 | + Fast: Battery charges over a shorter period. | |
| 11 | + Trickle: Extends battery lifespan, intended for users who | |
| 12 | + primarily use their Chromebook while connected to AC. | |
| 13 | + Custom: A low and high threshold percentage is specified. | |
| 14 | + Charging begins when level drops below | |
| 15 | + charge_control_start_threshold, and ceases when | |
| 16 | + level is above charge_control_end_threshold. | |
| 17 | + | |
| 18 | +What: /sys/class/power_supply/wilco-charger/charge_control_start_threshold | |
| 19 | +Date: April 2019 | |
| 20 | +KernelVersion: 5.2 | |
| 21 | +Description: | |
| 22 | + Used when charge_type="Custom", as described above. Measured in | |
| 23 | + percentages. The valid range is [50, 95]. | |
| 24 | + | |
| 25 | +What: /sys/class/power_supply/wilco-charger/charge_control_end_threshold | |
| 26 | +Date: April 2019 | |
| 27 | +KernelVersion: 5.2 | |
| 28 | +Description: | |
| 29 | + Used when charge_type="Custom", as described above. Measured in | |
| 30 | + percentages. The valid range is [55, 100]. | |
| @@ -5,7 +5,7 @@ Contact: linux-pm@vger.kernel.org · 4 unmodified lines | ||
| 5 | 5 | Description: |
| 6 | 6 | The powercap/ class sub directory belongs to the power cap |
| 7 | 7 | subsystem. Refer to |
| 8 | − Documentation/power/powercap/powercap.txt for details. | |
| 8 | + Documentation/power/powercap/powercap.rst for details. | |
| 9 | 9 | |
| 10 | 10 | What: /sys/class/powercap/<control type> |
| 11 | 11 | Date: September 2013 |
| @@ -147,6 +147,6 @@ What: /sys/class/powercap/.../<power zone>/enabled · 135 unmodified lines | ||
| 147 | 147 | Date: September 2013 |
| 148 | 148 | KernelVersion: 3.13 |
| 149 | 149 | Contact: linux-pm@vger.kernel.org |
| 150 | −Description | |
| 150 | +Description: | |
| 151 | 151 | This allows to enable/disable power capping at power zone level. |
| 152 | 152 | This applies to current power zone and its children. |
| @@ -1,6 +1,6 @@ | ||
| 1 | 1 | switchtec - Microsemi Switchtec PCI Switch Management Endpoint |
| 2 | 2 | |
| 3 | −For details on this subsystem look at Documentation/switchtec.txt. | |
| 3 | +For details on this subsystem look at Documentation/driver-api/switchtec.rst. | |
| 4 | 4 | |
| 5 | 5 | What: /sys/class/switchtec |
| 6 | 6 | Date: 05-Jan-2017 |
| @@ -125,12 +125,6 @@ Description: · 124 unmodified lines | ||
| 125 | 125 | The EUI-48 of this device in colon separated hex |
| 126 | 126 | octets. |
| 127 | 127 | |
| 128 | −What: /sys/class/uwb_rc/uwbN/<EUI-48>/BPST | |
| 129 | −Date: July 2008 | |
| 130 | −KernelVersion: 2.6.27 | |
| 131 | −Contact: linux-usb@vger.kernel.org | |
| 132 | −Description: | |
| 133 | − | |
| 134 | 128 | What: /sys/class/uwb_rc/uwbN/<EUI-48>/IEs |
| 135 | 129 | Date: July 2008 |
| 136 | 130 | KernelVersion: 2.6.27 |
| @@ -34,7 +34,7 @@ Description: CPU topology files that describe kernel limits related to · 33 unmodified lines | ||
| 34 | 34 | present: cpus that have been identified as being present in |
| 35 | 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 | |
| 40 | 40 | What: /sys/devices/system/cpu/probe |
| @@ -103,7 +103,7 @@ Description: CPU topology files that describe a logical CPU's relationship · 62 unmodified lines | ||
| 103 | 103 | thread_siblings_list: human-readable list of cpu#'s hardware |
| 104 | 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 | |
| 109 | 109 | What: /sys/devices/system/cpu/cpuidle/current_driver |
| @@ -137,7 +137,8 @@ Description: Discover cpuidle policy and mechanism · 27 unmodified lines | ||
| 137 | 137 | current_governor: (RW) displays current idle policy. Users can |
| 138 | 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 | |
| 143 | 144 | What: /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 | 540 | This attribute is present for all online CPUs supporting the |
| 540 | 541 | Intel EPB feature. |
| 542 | + | |
| 543 | +What: /sys/devices/system/cpu/umwait_control | |
| 544 | + /sys/devices/system/cpu/umwait_control/enable_c02 | |
| 545 | + /sys/devices/system/cpu/umwait_control/max_time | |
| 546 | +Date: May 2019 | |
| 547 | +Contact: Linux kernel mailing list <linux-kernel@vger.kernel.org> | |
| 548 | +Description: Umwait control | |
| 549 | + | |
| 550 | + enable_c02: Read/write interface to control umwait C0.2 state | |
| 551 | + Read returns C0.2 state status: | |
| 552 | + 0: C0.2 is disabled | |
| 553 | + 1: C0.2 is enabled | |
| 554 | + | |
| 555 | + Write 'y' or '1' or 'on' to enable C0.2 state. | |
| 556 | + Write 'n' or '0' or 'off' to disable C0.2 state. | |
| 557 | + | |
| 558 | + The interface is case insensitive. | |
| 559 | + | |
| 560 | + max_time: Read/write interface to control umwait maximum time | |
| 561 | + in TSC-quanta that the CPU can reside in either C0.1 | |
| 562 | + or C0.2 state. The time is an unsigned 32-bit number. | |
| 563 | + Note that a value of zero means there is no limit. | |
| 564 | + Low order two bits must be zero. | |
| @@ -1,6 +1,6 @@ | ||
| 1 | 1 | What: /sys/bus/pci/drivers/altera-cvp/chkcfg |
| 2 | 2 | Date: May 2017 |
| 3 | −Kernel Version: 4.13 | |
| 3 | +KernelVersion: 4.13 | |
| 4 | 4 | Contact: Anatolij Gustschin <agust@denx.de> |
| 5 | 5 | Description: |
| 6 | 6 | Contains either 1 or 0 and controls if configuration |
| @@ -62,18 +62,20 @@ What: /sys/class/habanalabs/hl<n>/ic_clk · 61 unmodified lines | ||
| 62 | 62 | Date: Jan 2019 |
| 63 | 63 | KernelVersion: 5.1 |
| 64 | 64 | Contact: oded.gabbay@gmail.com |
| 65 | −Description: Allows the user to set the maximum clock frequency of the | |
| 66 | − Interconnect fabric. Writes to this parameter affect the device | |
| 67 | − only when the power management profile is set to "manual" mode. | |
| 68 | − The device IC clock might be set to lower value then the | |
| 65 | +Description: Allows the user to set the maximum clock frequency, in Hz, of | |
| 66 | + the Interconnect fabric. Writes to this parameter affect the | |
| 67 | + device only when the power management profile is set to "manual" | |
| 68 | + mode. The device IC clock might be set to lower value than the | |
| 69 | 69 | maximum. The user should read the ic_clk_curr to see the actual |
| 70 | − frequency value of the IC | |
| 70 | + frequency value of the IC. This property is valid only for the | |
| 71 | + Goya ASIC family | |
| 71 | 72 | |
| 72 | 73 | What: /sys/class/habanalabs/hl<n>/ic_clk_curr |
| 73 | 74 | Date: Jan 2019 |
| 74 | 75 | KernelVersion: 5.1 |
| 75 | 76 | Contact: oded.gabbay@gmail.com |
| 76 | −Description: Displays the current clock frequency of the Interconnect fabric | |
| 77 | +Description: Displays the current clock frequency, in Hz, of the Interconnect | |
| 78 | + fabric. This property is valid only for the Goya ASIC family | |
| 77 | 79 | |
| 78 | 80 | What: /sys/class/habanalabs/hl<n>/infineon_ver |
| 79 | 81 | Date: Jan 2019 |
| @@ -92,18 +94,20 @@ What: /sys/class/habanalabs/hl<n>/mme_clk · 12 unmodified lines | ||
| 92 | 94 | Date: Jan 2019 |
| 93 | 95 | KernelVersion: 5.1 |
| 94 | 96 | Contact: oded.gabbay@gmail.com |
| 95 | −Description: Allows the user to set the maximum clock frequency of the | |
| 96 | − MME compute engine. Writes to this parameter affect the device | |
| 97 | − only when the power management profile is set to "manual" mode. | |
| 98 | − The device MME clock might be set to lower value then the | |
| 97 | +Description: Allows the user to set the maximum clock frequency, in Hz, of | |
| 98 | + the MME compute engine. Writes to this parameter affect the | |
| 99 | + device only when the power management profile is set to "manual" | |
| 100 | + mode. The device MME clock might be set to lower value than the | |
| 99 | 101 | maximum. The user should read the mme_clk_curr to see the actual |
| 100 | − frequency value of the MME | |
| 102 | + frequency value of the MME. This property is valid only for the | |
| 103 | + Goya ASIC family | |
| 101 | 104 | |
| 102 | 105 | What: /sys/class/habanalabs/hl<n>/mme_clk_curr |
| 103 | 106 | Date: Jan 2019 |
| 104 | 107 | KernelVersion: 5.1 |
| 105 | 108 | Contact: oded.gabbay@gmail.com |
| 106 | −Description: Displays the current clock frequency of the MME compute engine | |
| 109 | +Description: Displays the current clock frequency, in Hz, of the MME compute | |
| 110 | + engine. This property is valid only for the Goya ASIC family | |
| 107 | 111 | |
| 108 | 112 | What: /sys/class/habanalabs/hl<n>/pci_addr |
| 109 | 113 | Date: Jan 2019 |
| @@ -163,18 +167,20 @@ What: /sys/class/habanalabs/hl<n>/tpc_clk · 53 unmodified lines | ||
| 163 | 167 | Date: Jan 2019 |
| 164 | 168 | KernelVersion: 5.1 |
| 165 | 169 | Contact: oded.gabbay@gmail.com |
| 166 | −Description: Allows the user to set the maximum clock frequency of the | |
| 167 | − TPC compute engines. Writes to this parameter affect the device | |
| 168 | − only when the power management profile is set to "manual" mode. | |
| 169 | − The device TPC clock might be set to lower value then the | |
| 170 | +Description: Allows the user to set the maximum clock frequency, in Hz, of | |
| 171 | + the TPC compute engines. Writes to this parameter affect the | |
| 172 | + device only when the power management profile is set to "manual" | |
| 173 | + mode. The device TPC clock might be set to lower value than the | |
| 170 | 174 | maximum. The user should read the tpc_clk_curr to see the actual |
| 171 | − frequency value of the TPC | |
| 175 | + frequency value of the TPC. This property is valid only for | |
| 176 | + Goya ASIC family | |
| 172 | 177 | |
| 173 | 178 | What: /sys/class/habanalabs/hl<n>/tpc_clk_curr |
| 174 | 179 | Date: Jan 2019 |
| 175 | 180 | KernelVersion: 5.1 |
| 176 | 181 | Contact: oded.gabbay@gmail.com |
| 177 | −Description: Displays the current clock frequency of the TPC compute engines | |
| 182 | +Description: Displays the current clock frequency, in Hz, of the TPC compute | |
| 183 | + engines. This property is valid only for the Goya ASIC family | |
| 178 | 184 | |
| 179 | 185 | What: /sys/class/habanalabs/hl<n>/uboot_ver |
| 180 | 186 | Date: Jan 2019 |
| @@ -1,6 +1,6 @@ | ||
| 1 | −What: For USB devices : /sys/bus/usb/devices/<busnum>-<devnum>:<config num>.<interface num>/<hid-bus>:<vendor-id>:<product-id>.<num>/report_descriptor | |
| 2 | − For BT devices : /sys/class/bluetooth/hci<addr>/<hid-bus>:<vendor-id>:<product-id>.<num>/report_descriptor | |
| 3 | − Symlink : /sys/class/hidraw/hidraw<num>/device/report_descriptor | |
| 1 | +What: /sys/bus/usb/devices/<busnum>-<devnum>:<config num>.<interface num>/<hid-bus>:<vendor-id>:<product-id>.<num>/report_descriptor | |
| 2 | +What: /sys/class/bluetooth/hci<addr>/<hid-bus>:<vendor-id>:<product-id>.<num>/report_descriptor | |
| 3 | +What: /sys/class/hidraw/hidraw<num>/device/report_descriptor | |
| 4 | 4 | Date: Jan 2011 |
| 5 | 5 | KernelVersion: 2.0.39 |
| 6 | 6 | Contact: Alan Ott <alan@signal11.us> |
| @@ -9,9 +9,9 @@ Description: When read, this file returns the device's raw binary HID · 2 unmodified lines | ||
| 9 | 9 | This file cannot be written. |
| 10 | 10 | Users: HIDAPI library (http://www.signal11.us/oss/hidapi) |
| 11 | 11 | |
| 12 | −What: For USB devices : /sys/bus/usb/devices/<busnum>-<devnum>:<config num>.<interface num>/<hid-bus>:<vendor-id>:<product-id>.<num>/country | |
| 13 | − For BT devices : /sys/class/bluetooth/hci<addr>/<hid-bus>:<vendor-id>:<product-id>.<num>/country | |
| 14 | − Symlink : /sys/class/hidraw/hidraw<num>/device/country | |
| 12 | +What: /sys/bus/usb/devices/<busnum>-<devnum>:<config num>.<interface num>/<hid-bus>:<vendor-id>:<product-id>.<num>/country | |
| 13 | +What: /sys/class/bluetooth/hci<addr>/<hid-bus>:<vendor-id>:<product-id>.<num>/country | |
| 14 | +What: /sys/class/hidraw/hidraw<num>/device/country | |
| 15 | 15 | Date: February 2015 |
| 16 | 16 | KernelVersion: 3.19 |
| 17 | 17 | Contact: Olivier Gay <ogay@logitech.com> |
| @@ -5,7 +5,7 @@ Description: It is possible to switch the dpi setting of the mouse with the · 4 unmodified lines | ||
| 5 | 5 | press of a button. |
| 6 | 6 | When read, this file returns the raw number of the actual dpi |
| 7 | 7 | 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 | 10 | VALUE DPI |
| 11 | 11 | 1 800 |
| @@ -1,6 +1,6 @@ | ||
| 1 | 1 | What: /sys/class/tpm/tpmX/ppi/ |
| 2 | 2 | Date: August 2012 |
| 3 | −Kernel Version: 3.6 | |
| 3 | +KernelVersion: 3.6 | |
| 4 | 4 | Contact: xiaoyan.zhang@intel.com |
| 5 | 5 | Description: |
| 6 | 6 | This folder includes the attributes related with PPI (Physical |
| @@ -1,6 +1,6 @@ | ||
| 1 | 1 | What: /sys/bus/scsi/drivers/st/debug_flag |
| 2 | 2 | Date: October 2015 |
| 3 | −Kernel Version: ?.? | |
| 3 | +KernelVersion: ?.? | |
| 4 | 4 | Contact: shane.seymour@hpe.com |
| 5 | 5 | Description: |
| 6 | 6 | This file allows you to turn debug output from the st driver |
| @@ -1,6 +1,6 @@ | ||
| 1 | 1 | What: /sys/bus/hid/devices/<bus>:<vid>:<pid>.<n>/speed |
| 2 | 2 | Date: April 2010 |
| 3 | −Kernel Version: 2.6.35 | |
| 3 | +KernelVersion: 2.6.35 | |
| 4 | 4 | Contact: linux-bluetooth@vger.kernel.org |
| 5 | 5 | Description: |
| 6 | 6 | The /sys/bus/hid/devices/<bus>:<vid>:<pid>.<n>/speed file |
| @@ -243,3 +243,11 @@ Description: · 242 unmodified lines | ||
| 243 | 243 | - Del: echo '[h/c]!extension' > /sys/fs/f2fs/<disk>/extension_list |
| 244 | 244 | - [h] means add/del hot file extension |
| 245 | 245 | - [c] means add/del cold file extension |
| 246 | + | |
| 247 | +What: /sys/fs/f2fs/<disk>/unusable | |
| 248 | +Date April 2019 | |
| 249 | +Contact: "Daniel Rosenberg" <drosen@google.com> | |
| 250 | +Description: | |
| 251 | + If checkpoint=disable, it displays the number of blocks that are unusable. | |
| 252 | + If checkpoint=enable it displays the enumber of blocks that would be unusable | |
| 253 | + if checkpoint=disable were to be set. | |
| @@ -2,7 +2,7 @@ What: /sys/kernel/fscaps · 1 unmodified line | ||
| 2 | 2 | Date: February 2011 |
| 3 | 3 | KernelVersion: 2.6.38 |
| 4 | 4 | Contact: Ludwig Nussel <ludwig.nussel@suse.de> |
| 5 | −Description | |
| 5 | +Description: | |
| 6 | 6 | Shows whether file system capabilities are honored |
| 7 | 7 | when executing a binary |
| 8 | 8 | |
| @@ -24,3 +24,12 @@ Description: /sys/kernel/iommu_groups/reserved_regions list IOVA · 23 unmodified lines | ||
| 24 | 24 | region is described on a single line: the 1st field is |
| 25 | 25 | the base IOVA, the second is the end IOVA and the third |
| 26 | 26 | field describes the type of the region. |
| 27 | + | |
| 28 | +What: /sys/kernel/iommu_groups/reserved_regions | |
| 29 | +Date: June 2019 | |
| 30 | +KernelVersion: v5.3 | |
| 31 | +Contact: Eric Auger <eric.auger@redhat.com> | |
| 32 | +Description: In case an RMRR is used only by graphics or USB devices | |
| 33 | + it is now exposed as "direct-relaxable" instead of "direct". | |
| 34 | + In device assignment use case, for instance, those RMRR | |
| 35 | + are considered to be relaxable and safe. | |
| @@ -11,4 +11,4 @@ Description: · 10 unmodified lines | ||
| 11 | 11 | example would be, if User A has shares = 1024 and user |
| 12 | 12 | B has shares = 2048, User B will get twice the CPU |
| 13 | 13 | bandwidth user A will. For more details refer |
| 14 | − Documentation/scheduler/sched-design-CFS.txt | |
| 14 | + Documentation/scheduler/sched-design-CFS.rst | |
| @@ -4,7 +4,7 @@ KernelVersion: 2.6.24 · 3 unmodified lines | ||
| 4 | 4 | Contact: Ken'ichi Ohmichi <oomichi@mxs.nes.nec.co.jp> |
| 5 | 5 | Kexec Mailing List <kexec@lists.infradead.org> |
| 6 | 6 | Vivek Goyal <vgoyal@redhat.com> |
| 7 | −Description | |
| 7 | +Description: | |
| 8 | 8 | Shows physical address and size of vmcoreinfo ELF note. |
| 9 | 9 | First value contains physical address of note in hex and |
| 10 | 10 | second value contains the size of note in hex. This ELF |
| @@ -31,7 +31,7 @@ Description: · 30 unmodified lines | ||
| 31 | 31 | To control the LED display, use the following : |
| 32 | 32 | echo 0x0T000DDD > /sys/devices/platform/asus_laptop/ |
| 33 | 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.txt | |
| 34 | + The DDD table can be found in Documentation/admin-guide/laptops/asus-laptop.rst | |
| 35 | 35 | |
| 36 | 36 | What: /sys/devices/platform/asus_laptop/bluetooth |
| 37 | 37 | Date: January 2007 |
| @@ -36,3 +36,13 @@ KernelVersion: 3.5 · 35 unmodified lines | ||
| 36 | 36 | Contact: "AceLan Kao" <acelan.kao@canonical.com> |
| 37 | 37 | Description: |
| 38 | 38 | Resume on lid open. 1 means on, 0 means off. |
| 39 | + | |
| 40 | +What: /sys/devices/platform/<platform>/fan_boost_mode | |
| 41 | +Date: Sep 2019 | |
| 42 | +KernelVersion: 5.3 | |
| 43 | +Contact: "Yurii Pavlovskyi" <yurii.pavlovskyi@gmail.com> | |
| 44 | +Description: | |
| 45 | + Fan boost mode: | |
| 46 | + * 0 - normal, | |
| 47 | + * 1 - overboost, | |
| 48 | + * 2 - silent | |
| @@ -1,7 +1,7 @@ | ||
| 1 | 1 | What: /sys/devices/platform/<i2c-demux-name>/available_masters |
| 2 | 2 | Date: January 2016 |
| 3 | 3 | KernelVersion: 4.6 |
| 4 | −Contact: Wolfram Sang <wsa@the-dreams.de> | |
| 4 | +Contact: Wolfram Sang <wsa+renesas@sang-engineering.com> | |
| 5 | 5 | Description: |
| 6 | 6 | Reading the file will give you a list of masters which can be |
| 7 | 7 | selected for a demultiplexed bus. The format is |
| @@ -12,7 +12,7 @@ Description: · 4 unmodified lines | ||
| 12 | 12 | What: /sys/devices/platform/<i2c-demux-name>/current_master |
| 13 | 13 | Date: January 2016 |
| 14 | 14 | KernelVersion: 4.6 |
| 15 | −Contact: Wolfram Sang <wsa@the-dreams.de> | |
| 15 | +Contact: Wolfram Sang <wsa+renesas@sang-engineering.com> | |
| 16 | 16 | Description: |
| 17 | 17 | This file selects/shows the active I2C master for a demultiplexed |
| 18 | 18 | bus. It uses the <index> value from the file 'available_masters'. |
| @@ -0,0 +1,40 @@ | ||
| 1 | +What: /sys/bus/platform/devices/GOOG000C\:00/boot_on_ac | |
| 2 | +Date: April 2019 | |
| 3 | +KernelVersion: 5.3 | |
| 4 | +Description: | |
| 5 | + Boot on AC is a policy which makes the device boot from S5 | |
| 6 | + when AC power is connected. This is useful for users who | |
| 7 | + want to run their device headless or with a dock. | |
| 8 | + | |
| 9 | + Input should be parseable by kstrtou8() to 0 or 1. | |
| 10 | + | |
| 11 | +What: /sys/bus/platform/devices/GOOG000C\:00/build_date | |
| 12 | +Date: May 2019 | |
| 13 | +KernelVersion: 5.3 | |
| 14 | +Description: | |
| 15 | + Display Wilco Embedded Controller firmware build date. | |
| 16 | + Output will a MM/DD/YY string. | |
| 17 | + | |
| 18 | +What: /sys/bus/platform/devices/GOOG000C\:00/build_revision | |
| 19 | +Date: May 2019 | |
| 20 | +KernelVersion: 5.3 | |
| 21 | +Description: | |
| 22 | + Display Wilco Embedded Controller build revision. | |
| 23 | + Output will a version string be similar to the example below: | |
| 24 | + d2592cae0 | |
| 25 | + | |
| 26 | +What: /sys/bus/platform/devices/GOOG000C\:00/model_number | |
| 27 | +Date: May 2019 | |
| 28 | +KernelVersion: 5.3 | |
| 29 | +Description: | |
| 30 | + Display Wilco Embedded Controller model number. | |
| 31 | + Output will a version string be similar to the example below: | |
| 32 | + 08B6 | |
| 33 | + | |
| 34 | +What: /sys/bus/platform/devices/GOOG000C\:00/version | |
| 35 | +Date: May 2019 | |
| 36 | +KernelVersion: 5.3 | |
| 37 | +Description: | |
| 38 | + Display Wilco Embedded Controller firmware version. | |
| 39 | + The format of the string is x.y.z. Where x is major, y is minor | |
| 40 | + and z is the build number. For example: 95.00.06 | |
| @@ -300,4 +300,4 @@ Description: · 299 unmodified lines | ||
| 300 | 300 | attempt. |
| 301 | 301 | |
| 302 | 302 | 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. | |
File renamed without changes.
| @@ -212,7 +212,7 @@ The standard 64-bit addressing device would do something like this:: · 211 unmodified lines | ||
| 212 | 212 | |
| 213 | 213 | If the device only supports 32-bit addressing for descriptors in the |
| 214 | 214 | coherent allocations, but supports full 64-bits for streaming mappings |
| 215 | −it would look like this: | |
| 215 | +it would look like this:: | |
| 216 | 216 | |
| 217 | 217 | if (dma_set_mask(dev, DMA_BIT_MASK(64))) { |
| 218 | 218 | dev_warn(dev, "mydev: No suitable DMA available\n"); |
| @@ -198,7 +198,7 @@ call to set the mask to the value returned. · 197 unmodified lines | ||
| 198 | 198 | :: |
| 199 | 199 | |
| 200 | 200 | size_t |
| 201 | − dma_direct_max_mapping_size(struct device *dev); | |
| 201 | + dma_max_mapping_size(struct device *dev); | |
| 202 | 202 | |
| 203 | 203 | Returns the maximum size of a mapping for the device. The size parameter |
| 204 | 204 | of the mapping functions like dma_map_single(), dma_map_page() and |
| @@ -1,49 +0,0 @@ | ||
| 1 | −In the good old days when graphics parameters were configured explicitly | |
| 2 | −in a file called xorg.conf, even broken hardware could be managed. | |
| 3 | − | |
| 4 | −Today, with the advent of Kernel Mode Setting, a graphics board is | |
| 5 | −either correctly working because all components follow the standards - | |
| 6 | −or the computer is unusable, because the screen remains dark after | |
| 7 | −booting or it displays the wrong area. Cases when this happens are: | |
| 8 | −- The graphics board does not recognize the monitor. | |
| 9 | −- The graphics board is unable to detect any EDID data. | |
| 10 | −- The graphics board incorrectly forwards EDID data to the driver. | |
| 11 | −- The monitor sends no or bogus EDID data. | |
| 12 | −- A KVM sends its own EDID data instead of querying the connected monitor. | |
| 13 | −Adding the kernel parameter "nomodeset" helps in most cases, but causes | |
| 14 | −restrictions later on. | |
| 15 | − | |
| 16 | −As a remedy for such situations, the kernel configuration item | |
| 17 | −CONFIG_DRM_LOAD_EDID_FIRMWARE was introduced. It allows to provide an | |
| 18 | −individually prepared or corrected EDID data set in the /lib/firmware | |
| 19 | −directory from where it is loaded via the firmware interface. The code | |
| 20 | −(see drivers/gpu/drm/drm_edid_load.c) contains built-in data sets for | |
| 21 | −commonly used screen resolutions (800x600, 1024x768, 1280x1024, 1600x1200, | |
| 22 | −1680x1050, 1920x1080) as binary blobs, but the kernel source tree does | |
| 23 | −not contain code to create these data. In order to elucidate the origin | |
| 24 | −of the built-in binary EDID blobs and to facilitate the creation of | |
| 25 | −individual data for a specific misbehaving monitor, commented sources | |
| 26 | −and a Makefile environment are given here. | |
| 27 | − | |
| 28 | −To create binary EDID and C source code files from the existing data | |
| 29 | −material, simply type "make". | |
| 30 | − | |
| 31 | −If you want to create your own EDID file, copy the file 1024x768.S, | |
| 32 | −replace the settings with your own data and add a new target to the | |
| 33 | −Makefile. Please note that the EDID data structure expects the timing | |
| 34 | −values in a different way as compared to the standard X11 format. | |
| 35 | − | |
| 36 | −X11: | |
| 37 | −HTimings: hdisp hsyncstart hsyncend htotal | |
| 38 | −VTimings: vdisp vsyncstart vsyncend vtotal | |
| 39 | − | |
| 40 | −EDID: | |
| 41 | −#define XPIX hdisp | |
| 42 | −#define XBLANK htotal-hdisp | |
| 43 | −#define XOFFSET hsyncstart-hdisp | |
| 44 | −#define XPULSE hsyncend-hsyncstart | |
| 45 | − | |
| 46 | −#define YPIX vdisp | |
| 47 | −#define YBLANK vtotal-vdisp | |
| 48 | −#define YOFFSET vsyncstart-vdisp | |
| 49 | −#define YPULSE vsyncend-vsyncstart | |
| @@ -0,0 +1,13 @@ | ||
| 1 | +config WARN_MISSING_DOCUMENTS | |
| 2 | + | |
| 3 | + bool "Warn if there's a missing documentation file" | |
| 4 | + depends on COMPILE_TEST | |
| 5 | + help | |
| 6 | + It is not uncommon that a document gets renamed. | |
| 7 | + This option makes the Kernel to check for missing dependencies, | |
| 8 | + warning when something is missing. Works only if the Kernel | |
| 9 | + is built from a git tree. | |
| 10 | + | |
| 11 | + If unsure, select 'N'. | |
| 12 | + | |
| 13 | + | |
| @@ -4,6 +4,11 @@ · 3 unmodified lines | ||
| 4 | 4 | |
| 5 | 5 | subdir-y := devicetree/bindings/ |
| 6 | 6 | |
| 7 | +# Check for broken documentation file references | |
| 8 | +ifeq ($(CONFIG_WARN_MISSING_DOCUMENTS),y) | |
| 9 | +$(shell $(srctree)/scripts/documentation-file-ref-check --warn) | |
| 10 | +endif | |
| 11 | + | |
| 7 | 12 | # You can set these variables from the command line. |
| 8 | 13 | SPHINXBUILD = sphinx-build |
| 9 | 14 | SPHINXOPTS = |
| @@ -23,11 +28,13 @@ ifeq ($(HAVE_SPHINX),0) · 13 unmodified lines | ||
| 23 | 28 | .DEFAULT: |
| 24 | 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 | 30 | @echo |
| 26 | − @./scripts/sphinx-pre-install | |
| 31 | + @$(srctree)/scripts/sphinx-pre-install | |
| 27 | 32 | @echo " SKIP Sphinx $@ target." |
| 28 | 33 | |
| 29 | 34 | else # HAVE_SPHINX |
| 30 | 35 | |
| 36 | +export SPHINXOPTS = $(shell perl -e 'open IN,"sphinx-build --version 2>&1 |"; while (<IN>) { if (m/([\d\.]+)/) { print "-jauto" if ($$1 >= "1.7") } ;} close IN') | |
| 37 | + | |
| 31 | 38 | # User-friendly check for pdflatex and latexmk |
| 32 | 39 | HAVE_PDFLATEX := $(shell if which $(PDFLATEX) >/dev/null 2>&1; then echo 1; else echo 0; fi) |
| 33 | 40 | HAVE_LATEXMK := $(shell if which latexmk >/dev/null 2>&1; then echo 1; else echo 0; fi) |
| @@ -70,12 +77,14 @@ quiet_cmd_sphinx = SPHINX $@ --> file://$(abspath $(BUILDDIR)/$3/$4) · 36 unmodified lines | ||
| 70 | 77 | $(abspath $(BUILDDIR)/$3/$4) |
| 71 | 78 | |
| 72 | 79 | htmldocs: |
| 80 | + @$(srctree)/scripts/sphinx-pre-install --version-check | |
| 73 | 81 | @+$(foreach var,$(SPHINXDIRS),$(call loop_cmd,sphinx,html,$(var),,$(var))) |
| 74 | 82 | |
| 75 | 83 | linkcheckdocs: |
| 76 | 84 | @$(foreach var,$(SPHINXDIRS),$(call loop_cmd,sphinx,linkcheck,$(var),,$(var))) |
| 77 | 85 | |
| 78 | 86 | latexdocs: |
| 87 | + @$(srctree)/scripts/sphinx-pre-install --version-check | |
| 79 | 88 | @+$(foreach var,$(SPHINXDIRS),$(call loop_cmd,sphinx,latex,$(var),latex,$(var))) |
| 80 | 89 | |
| 81 | 90 | ifeq ($(HAVE_PDFLATEX),0) |
| @@ -87,14 +96,17 @@ pdfdocs: · 5 unmodified lines | ||
| 87 | 96 | else # HAVE_PDFLATEX |
| 88 | 97 | |
| 89 | 98 | pdfdocs: latexdocs |
| 99 | + @$(srctree)/scripts/sphinx-pre-install --version-check | |
| 90 | 100 | $(foreach var,$(SPHINXDIRS), $(MAKE) PDFLATEX="$(PDFLATEX)" LATEXOPTS="$(LATEXOPTS)" -C $(BUILDDIR)/$(var)/latex || exit;) |
| 91 | 101 | |
| 92 | 102 | endif # HAVE_PDFLATEX |
| 93 | 103 | |
| 94 | 104 | epubdocs: |
| 105 | + @$(srctree)/scripts/sphinx-pre-install --version-check | |
| 95 | 106 | @+$(foreach var,$(SPHINXDIRS),$(call loop_cmd,sphinx,epub,$(var),epub,$(var))) |
| 96 | 107 | |
| 97 | 108 | xmldocs: |
| 109 | + @$(srctree)/scripts/sphinx-pre-install --version-check | |
| 98 | 110 | @+$(foreach var,$(SPHINXDIRS),$(call loop_cmd,sphinx,xml,$(var),xml,$(var))) |
| 99 | 111 | |
| 100 | 112 | endif # HAVE_SPHINX |
| @@ -1,270 +0,0 @@ | ||
| 1 | − The MSI Driver Guide HOWTO | |
| 2 | − Tom L Nguyen tom.l.nguyen@intel.com | |
| 3 | − 10/03/2003 | |
| 4 | − Revised Feb 12, 2004 by Martine Silbermann | |
| 5 | − email: Martine.Silbermann@hp.com | |
| 6 | − Revised Jun 25, 2004 by Tom L Nguyen | |
| 7 | − Revised Jul 9, 2008 by Matthew Wilcox <willy@linux.intel.com> | |
| 8 | − Copyright 2003, 2008 Intel Corporation | |
| 9 | − | |
| 10 | −1. About this guide | |
| 11 | − | |
| 12 | −This guide describes the basics of Message Signaled Interrupts (MSIs), | |
| 13 | −the advantages of using MSI over traditional interrupt mechanisms, how | |
| 14 | −to change your driver to use MSI or MSI-X and some basic diagnostics to | |
| 15 | −try if a device doesn't support MSIs. | |
| 16 | − | |
| 17 | − | |
| 18 | −2. What are MSIs? | |
| 19 | − | |
| 20 | −A Message Signaled Interrupt is a write from the device to a special | |
| 21 | −address which causes an interrupt to be received by the CPU. | |
| 22 | − | |
| 23 | −The MSI capability was first specified in PCI 2.2 and was later enhanced | |
| 24 | −in PCI 3.0 to allow each interrupt to be masked individually. The MSI-X | |
| 25 | −capability was also introduced with PCI 3.0. It supports more interrupts | |
| 26 | −per device than MSI and allows interrupts to be independently configured. | |
| 27 | − | |
| 28 | −Devices may support both MSI and MSI-X, but only one can be enabled at | |
| 29 | −a time. | |
| 30 | − | |
| 31 | − | |
| 32 | −3. Why use MSIs? | |
| 33 | − | |
| 34 | −There are three reasons why using MSIs can give an advantage over | |
| 35 | −traditional pin-based interrupts. | |
| 36 | − | |
| 37 | −Pin-based PCI interrupts are often shared amongst several devices. | |
| 38 | −To support this, the kernel must call each interrupt handler associated | |
| 39 | −with an interrupt, which leads to reduced performance for the system as | |
| 40 | −a whole. MSIs are never shared, so this problem cannot arise. | |
| 41 | − | |
| 42 | −When a device writes data to memory, then raises a pin-based interrupt, | |
| 43 | −it is possible that the interrupt may arrive before all the data has | |
| 44 | −arrived in memory (this becomes more likely with devices behind PCI-PCI | |
| 45 | −bridges). In order to ensure that all the data has arrived in memory, | |
| 46 | −the interrupt handler must read a register on the device which raised | |
| 47 | −the interrupt. PCI transaction ordering rules require that all the data | |
| 48 | −arrive in memory before the value may be returned from the register. | |
| 49 | −Using MSIs avoids this problem as the interrupt-generating write cannot | |
| 50 | −pass the data writes, so by the time the interrupt is raised, the driver | |
| 51 | −knows that all the data has arrived in memory. | |
| 52 | − | |
| 53 | −PCI devices can only support a single pin-based interrupt per function. | |
| 54 | −Often drivers have to query the device to find out what event has | |
| 55 | −occurred, slowing down interrupt handling for the common case. With | |
| 56 | −MSIs, a device can support more interrupts, allowing each interrupt | |
| 57 | −to be specialised to a different purpose. One possible design gives | |
| 58 | −infrequent conditions (such as errors) their own interrupt which allows | |
| 59 | −the driver to handle the normal interrupt handling path more efficiently. | |
| 60 | −Other possible designs include giving one interrupt to each packet queue | |
| 61 | −in a network card or each port in a storage controller. | |
| 62 | − | |
| 63 | − | |
| 64 | −4. How to use MSIs | |
| 65 | − | |
| 66 | −PCI devices are initialised to use pin-based interrupts. The device | |
| 67 | −driver has to set up the device to use MSI or MSI-X. Not all machines | |
| 68 | −support MSIs correctly, and for those machines, the APIs described below | |
| 69 | −will simply fail and the device will continue to use pin-based interrupts. | |
| 70 | − | |
| 71 | −4.1 Include kernel support for MSIs | |
| 72 | − | |
| 73 | −To support MSI or MSI-X, the kernel must be built with the CONFIG_PCI_MSI | |
| 74 | −option enabled. This option is only available on some architectures, | |
| 75 | −and it may depend on some other options also being set. For example, | |
| 76 | −on x86, you must also enable X86_UP_APIC or SMP in order to see the | |
| 77 | −CONFIG_PCI_MSI option. | |
| 78 | − | |
| 79 | −4.2 Using MSI | |
| 80 | − | |
| 81 | −Most of the hard work is done for the driver in the PCI layer. The driver | |
| 82 | −simply has to request that the PCI layer set up the MSI capability for this | |
| 83 | −device. | |
| 84 | − | |
| 85 | −To automatically use MSI or MSI-X interrupt vectors, use the following | |
| 86 | −function: | |
| 87 | − | |
| 88 | − int pci_alloc_irq_vectors(struct pci_dev *dev, unsigned int min_vecs, | |
| 89 | − unsigned int max_vecs, unsigned int flags); | |
| 90 | − | |
| 91 | −which allocates up to max_vecs interrupt vectors for a PCI device. It | |
| 92 | −returns the number of vectors allocated or a negative error. If the device | |
| 93 | −has a requirements for a minimum number of vectors the driver can pass a | |
| 94 | −min_vecs argument set to this limit, and the PCI core will return -ENOSPC | |
| 95 | −if it can't meet the minimum number of vectors. | |
| 96 | − | |
| 97 | −The flags argument is used to specify which type of interrupt can be used | |
| 98 | −by the device and the driver (PCI_IRQ_LEGACY, PCI_IRQ_MSI, PCI_IRQ_MSIX). | |
| 99 | −A convenient short-hand (PCI_IRQ_ALL_TYPES) is also available to ask for | |
| 100 | −any possible kind of interrupt. If the PCI_IRQ_AFFINITY flag is set, | |
| 101 | −pci_alloc_irq_vectors() will spread the interrupts around the available CPUs. | |
| 102 | − | |
| 103 | −To get the Linux IRQ numbers passed to request_irq() and free_irq() and the | |
| 104 | −vectors, use the following function: | |
| 105 | − | |
| 106 | − int pci_irq_vector(struct pci_dev *dev, unsigned int nr); | |
| 107 | − | |
| 108 | −Any allocated resources should be freed before removing the device using | |
| 109 | −the following function: | |
| 110 | − | |
| 111 | − void pci_free_irq_vectors(struct pci_dev *dev); | |
| 112 | − | |
| 113 | −If a device supports both MSI-X and MSI capabilities, this API will use the | |
| 114 | −MSI-X facilities in preference to the MSI facilities. MSI-X supports any | |
| 115 | −number of interrupts between 1 and 2048. In contrast, MSI is restricted to | |
| 116 | −a maximum of 32 interrupts (and must be a power of two). In addition, the | |
| 117 | −MSI interrupt vectors must be allocated consecutively, so the system might | |
| 118 | −not be able to allocate as many vectors for MSI as it could for MSI-X. On | |
| 119 | −some platforms, MSI interrupts must all be targeted at the same set of CPUs | |
| 120 | −whereas MSI-X interrupts can all be targeted at different CPUs. | |
| 121 | − | |
| 122 | −If a device supports neither MSI-X or MSI it will fall back to a single | |
| 123 | −legacy IRQ vector. | |
| 124 | − | |
| 125 | −The typical usage of MSI or MSI-X interrupts is to allocate as many vectors | |
| 126 | −as possible, likely up to the limit supported by the device. If nvec is | |
| 127 | −larger than the number supported by the device it will automatically be | |
| 128 | −capped to the supported limit, so there is no need to query the number of | |
| 129 | −vectors supported beforehand: | |
| 130 | − | |
| 131 | − nvec = pci_alloc_irq_vectors(pdev, 1, nvec, PCI_IRQ_ALL_TYPES) | |
| 132 | − if (nvec < 0) | |
| 133 | − goto out_err; | |
| 134 | − | |
| 135 | −If a driver is unable or unwilling to deal with a variable number of MSI | |
| 136 | −interrupts it can request a particular number of interrupts by passing that | |
| 137 | −number to pci_alloc_irq_vectors() function as both 'min_vecs' and | |
| 138 | −'max_vecs' parameters: | |
| 139 | − | |
| 140 | − ret = pci_alloc_irq_vectors(pdev, nvec, nvec, PCI_IRQ_ALL_TYPES); | |
| 141 | − if (ret < 0) | |
| 142 | − goto out_err; | |
| 143 | − | |
| 144 | −The most notorious example of the request type described above is enabling | |
| 145 | −the single MSI mode for a device. It could be done by passing two 1s as | |
| 146 | −'min_vecs' and 'max_vecs': | |
| 147 | − | |
| 148 | − ret = pci_alloc_irq_vectors(pdev, 1, 1, PCI_IRQ_ALL_TYPES); | |
| 149 | − if (ret < 0) | |
| 150 | − goto out_err; | |
| 151 | − | |
| 152 | −Some devices might not support using legacy line interrupts, in which case | |
| 153 | −the driver can specify that only MSI or MSI-X is acceptable: | |
| 154 | − | |
| 155 | − nvec = pci_alloc_irq_vectors(pdev, 1, nvec, PCI_IRQ_MSI | PCI_IRQ_MSIX); | |
| 156 | − if (nvec < 0) | |
| 157 | − goto out_err; | |
| 158 | − | |
| 159 | −4.3 Legacy APIs | |
| 160 | − | |
| 161 | −The following old APIs to enable and disable MSI or MSI-X interrupts should | |
| 162 | −not be used in new code: | |
| 163 | − | |
| 164 | − pci_enable_msi() /* deprecated */ | |
| 165 | − pci_disable_msi() /* deprecated */ | |
| 166 | − pci_enable_msix_range() /* deprecated */ | |
| 167 | − pci_enable_msix_exact() /* deprecated */ | |
| 168 | − pci_disable_msix() /* deprecated */ | |
| 169 | − | |
| 170 | −Additionally there are APIs to provide the number of supported MSI or MSI-X | |
| 171 | −vectors: pci_msi_vec_count() and pci_msix_vec_count(). In general these | |
| 172 | −should be avoided in favor of letting pci_alloc_irq_vectors() cap the | |
| 173 | −number of vectors. If you have a legitimate special use case for the count | |
| 174 | −of vectors we might have to revisit that decision and add a | |
| 175 | −pci_nr_irq_vectors() helper that handles MSI and MSI-X transparently. | |
| 176 | − | |
| 177 | −4.4 Considerations when using MSIs | |
| 178 | − | |
| 179 | −4.4.1 Spinlocks | |
| 180 | − | |
| 181 | −Most device drivers have a per-device spinlock which is taken in the | |
| 182 | −interrupt handler. With pin-based interrupts or a single MSI, it is not | |
| 183 | −necessary to disable interrupts (Linux guarantees the same interrupt will | |
| 184 | −not be re-entered). If a device uses multiple interrupts, the driver | |
| 185 | −must disable interrupts while the lock is held. If the device sends | |
| 186 | −a different interrupt, the driver will deadlock trying to recursively | |
| 187 | −acquire the spinlock. Such deadlocks can be avoided by using | |
| 188 | −spin_lock_irqsave() or spin_lock_irq() which disable local interrupts | |
| 189 | −and acquire the lock (see Documentation/kernel-hacking/locking.rst). | |
| 190 | − | |
| 191 | −4.5 How to tell whether MSI/MSI-X is enabled on a device | |
| 192 | − | |
| 193 | −Using 'lspci -v' (as root) may show some devices with "MSI", "Message | |
| 194 | −Signalled Interrupts" or "MSI-X" capabilities. Each of these capabilities | |
| 195 | −has an 'Enable' flag which is followed with either "+" (enabled) | |
| 196 | −or "-" (disabled). | |
| 197 | − | |
| 198 | − | |
| 199 | −5. MSI quirks | |
| 200 | − | |
| 201 | −Several PCI chipsets or devices are known not to support MSIs. | |
| 202 | −The PCI stack provides three ways to disable MSIs: | |
| 203 | − | |
| 204 | −1. globally | |
| 205 | −2. on all devices behind a specific bridge | |
| 206 | −3. on a single device | |
| 207 | − | |
| 208 | −5.1. Disabling MSIs globally | |
| 209 | − | |
| 210 | −Some host chipsets simply don't support MSIs properly. If we're | |
| 211 | −lucky, the manufacturer knows this and has indicated it in the ACPI | |
| 212 | −FADT table. In this case, Linux automatically disables MSIs. | |
| 213 | −Some boards don't include this information in the table and so we have | |
| 214 | −to detect them ourselves. The complete list of these is found near the | |
| 215 | −quirk_disable_all_msi() function in drivers/pci/quirks.c. | |
| 216 | − | |
| 217 | −If you have a board which has problems with MSIs, you can pass pci=nomsi | |
| 218 | −on the kernel command line to disable MSIs on all devices. It would be | |
| 219 | −in your best interests to report the problem to linux-pci@vger.kernel.org | |
| 220 | −including a full 'lspci -v' so we can add the quirks to the kernel. | |
| 221 | − | |
| 222 | −5.2. Disabling MSIs below a bridge | |
| 223 | − | |
| 224 | −Some PCI bridges are not able to route MSIs between busses properly. | |
| 225 | −In this case, MSIs must be disabled on all devices behind the bridge. | |
| 226 | − | |
| 227 | −Some bridges allow you to enable MSIs by changing some bits in their | |
| 228 | −PCI configuration space (especially the Hypertransport chipsets such | |
| 229 | −as the nVidia nForce and Serverworks HT2000). As with host chipsets, | |
| 230 | −Linux mostly knows about them and automatically enables MSIs if it can. | |
| 231 | −If you have a bridge unknown to Linux, you can enable | |
| 232 | −MSIs in configuration space using whatever method you know works, then | |
| 233 | −enable MSIs on that bridge by doing: | |
| 234 | − | |
| 235 | − echo 1 > /sys/bus/pci/devices/$bridge/msi_bus | |
| 236 | − | |
| 237 | −where $bridge is the PCI address of the bridge you've enabled (eg | |
| 238 | −0000:00:0e.0). | |
| 239 | − | |
| 240 | −To disable MSIs, echo 0 instead of 1. Changing this value should be | |
| 241 | −done with caution as it could break interrupt handling for all devices | |
| 242 | −below this bridge. | |
| 243 | − | |
| 244 | −Again, please notify linux-pci@vger.kernel.org of any bridges that need | |
| 245 | −special handling. | |
| 246 | − | |
| 247 | −5.3. Disabling MSIs on a single device | |
| 248 | − | |
| 249 | −Some devices are known to have faulty MSI implementations. Usually this | |
| 250 | −is handled in the individual device driver, but occasionally it's necessary | |
| 251 | −to handle this with a quirk. Some drivers have an option to disable use | |
| 252 | −of MSI. While this is a convenient workaround for the driver author, | |
| 253 | −it is not good practice, and should not be emulated. | |
| 254 | − | |
| 255 | −5.4. Finding why MSIs are disabled on a device | |
| 256 | − | |
| 257 | −From the above three sections, you can see that there are many reasons | |
| 258 | −why MSIs may not be enabled for a given device. Your first step should | |
| 259 | −be to examine your dmesg carefully to determine whether MSIs are enabled | |
| 260 | −for your machine. You should also check your .config to be sure you | |
| 261 | −have enabled CONFIG_PCI_MSI. | |
| 262 | − | |
| 263 | −Then, 'lspci -t' gives the list of bridges above a device. Reading | |
| 264 | −/sys/bus/pci/devices/*/msi_bus will tell you whether MSIs are enabled (1) | |
| 265 | −or disabled (0). If 0 is found in any of the msi_bus files belonging | |
| 266 | −to bridges between the PCI root and the device, MSIs are disabled. | |
| 267 | − | |
| 268 | −It is also worth checking the device driver to see whether it supports MSIs. | |
| 269 | −For example, it may contain calls to pci_irq_alloc_vectors() with the | |
| 270 | −PCI_IRQ_MSI or PCI_IRQ_MSIX flags. | |
| @@ -1,198 +0,0 @@ | ||
| 1 | − The PCI Express Port Bus Driver Guide HOWTO | |
| 2 | − Tom L Nguyen tom.l.nguyen@intel.com | |
| 3 | − 11/03/2004 | |
| 4 | − | |
| 5 | −1. About this guide | |
| 6 | − | |
| 7 | −This guide describes the basics of the PCI Express Port Bus driver | |
| 8 | −and provides information on how to enable the service drivers to | |
| 9 | −register/unregister with the PCI Express Port Bus Driver. | |
| 10 | − | |
| 11 | −2. Copyright 2004 Intel Corporation | |
| 12 | − | |
| 13 | −3. What is the PCI Express Port Bus Driver | |
| 14 | − | |
| 15 | −A PCI Express Port is a logical PCI-PCI Bridge structure. There | |
| 16 | −are two types of PCI Express Port: the Root Port and the Switch | |
| 17 | −Port. The Root Port originates a PCI Express link from a PCI Express | |
| 18 | −Root Complex and the Switch Port connects PCI Express links to | |
| 19 | −internal logical PCI buses. The Switch Port, which has its secondary | |
| 20 | −bus representing the switch's internal routing logic, is called the | |
| 21 | −switch's Upstream Port. The switch's Downstream Port is bridging from | |
| 22 | −switch's internal routing bus to a bus representing the downstream | |
| 23 | −PCI Express link from the PCI Express Switch. | |
| 24 | − | |
| 25 | −A PCI Express Port can provide up to four distinct functions, | |
| 26 | −referred to in this document as services, depending on its port type. | |
| 27 | −PCI Express Port's services include native hotplug support (HP), | |
| 28 | −power management event support (PME), advanced error reporting | |
| 29 | −support (AER), and virtual channel support (VC). These services may | |
| 30 | −be handled by a single complex driver or be individually distributed | |
| 31 | −and handled by corresponding service drivers. | |
| 32 | − | |
| 33 | −4. Why use the PCI Express Port Bus Driver? | |
| 34 | − | |
| 35 | −In existing Linux kernels, the Linux Device Driver Model allows a | |
| 36 | −physical device to be handled by only a single driver. The PCI | |
| 37 | −Express Port is a PCI-PCI Bridge device with multiple distinct | |
| 38 | −services. To maintain a clean and simple solution each service | |
| 39 | −may have its own software service driver. In this case several | |
| 40 | −service drivers will compete for a single PCI-PCI Bridge device. | |
| 41 | −For example, if the PCI Express Root Port native hotplug service | |
| 42 | −driver is loaded first, it claims a PCI-PCI Bridge Root Port. The | |
| 43 | −kernel therefore does not load other service drivers for that Root | |
| 44 | −Port. In other words, it is impossible to have multiple service | |
| 45 | −drivers load and run on a PCI-PCI Bridge device simultaneously | |
| 46 | −using the current driver model. | |
| 47 | − | |
| 48 | −To enable multiple service drivers running simultaneously requires | |
| 49 | −having a PCI Express Port Bus driver, which manages all populated | |
| 50 | −PCI Express Ports and distributes all provided service requests | |
| 51 | −to the corresponding service drivers as required. Some key | |
| 52 | −advantages of using the PCI Express Port Bus driver are listed below: | |
| 53 | − | |
| 54 | − - Allow multiple service drivers to run simultaneously on | |
| 55 | − a PCI-PCI Bridge Port device. | |
| 56 | − | |
| 57 | − - Allow service drivers implemented in an independent | |
| 58 | − staged approach. | |
| 59 | − | |
| 60 | − - Allow one service driver to run on multiple PCI-PCI Bridge | |
| 61 | − Port devices. | |
| 62 | − | |
| 63 | − - Manage and distribute resources of a PCI-PCI Bridge Port | |
| 64 | − device to requested service drivers. | |
| 65 | − | |
| 66 | −5. Configuring the PCI Express Port Bus Driver vs. Service Drivers | |
| 67 | − | |
| 68 | −5.1 Including the PCI Express Port Bus Driver Support into the Kernel | |
| 69 | − | |
| 70 | −Including the PCI Express Port Bus driver depends on whether the PCI | |
| 71 | −Express support is included in the kernel config. The kernel will | |
| 72 | −automatically include the PCI Express Port Bus driver as a kernel | |
| 73 | −driver when the PCI Express support is enabled in the kernel. | |
| 74 | − | |
| 75 | −5.2 Enabling Service Driver Support | |
| 76 | − | |
| 77 | −PCI device drivers are implemented based on Linux Device Driver Model. | |
| 78 | −All service drivers are PCI device drivers. As discussed above, it is | |
| 79 | −impossible to load any service driver once the kernel has loaded the | |
| 80 | −PCI Express Port Bus Driver. To meet the PCI Express Port Bus Driver | |
| 81 | −Model requires some minimal changes on existing service drivers that | |
| 82 | −imposes no impact on the functionality of existing service drivers. | |
| 83 | − | |
| 84 | −A service driver is required to use the two APIs shown below to | |
| 85 | −register its service with the PCI Express Port Bus driver (see | |
| 86 | −section 5.2.1 & 5.2.2). It is important that a service driver | |
| 87 | −initializes the pcie_port_service_driver data structure, included in | |
| 88 | −header file /include/linux/pcieport_if.h, before calling these APIs. | |
| 89 | −Failure to do so will result an identity mismatch, which prevents | |
| 90 | −the PCI Express Port Bus driver from loading a service driver. | |
| 91 | − | |
| 92 | −5.2.1 pcie_port_service_register | |
| 93 | − | |
| 94 | −int pcie_port_service_register(struct pcie_port_service_driver *new) | |
| 95 | − | |
| 96 | −This API replaces the Linux Driver Model's pci_register_driver API. A | |
| 97 | −service driver should always calls pcie_port_service_register at | |
| 98 | −module init. Note that after service driver being loaded, calls | |
| 99 | −such as pci_enable_device(dev) and pci_set_master(dev) are no longer | |
| 100 | −necessary since these calls are executed by the PCI Port Bus driver. | |
| 101 | − | |
| 102 | −5.2.2 pcie_port_service_unregister | |
| 103 | − | |
| 104 | −void pcie_port_service_unregister(struct pcie_port_service_driver *new) | |
| 105 | − | |
| 106 | −pcie_port_service_unregister replaces the Linux Driver Model's | |
| 107 | −pci_unregister_driver. It's always called by service driver when a | |
| 108 | −module exits. | |
| 109 | − | |
| 110 | −5.2.3 Sample Code | |
| 111 | − | |
| 112 | −Below is sample service driver code to initialize the port service | |
| 113 | −driver data structure. | |
| 114 | − | |
| 115 | −static struct pcie_port_service_id service_id[] = { { | |
| 116 | − .vendor = PCI_ANY_ID, | |
| 117 | − .device = PCI_ANY_ID, | |
| 118 | − .port_type = PCIE_RC_PORT, | |
| 119 | − .service_type = PCIE_PORT_SERVICE_AER, | |
| 120 | − }, { /* end: all zeroes */ } | |
| 121 | −}; | |
| 122 | − | |
| 123 | −static struct pcie_port_service_driver root_aerdrv = { | |
| 124 | − .name = (char *)device_name, | |
| 125 | − .id_table = &service_id[0], | |
| 126 | − | |
| 127 | − .probe = aerdrv_load, | |
| 128 | − .remove = aerdrv_unload, | |
| 129 | − | |
| 130 | − .suspend = aerdrv_suspend, | |
| 131 | − .resume = aerdrv_resume, | |
| 132 | −}; | |
| 133 | − | |
| 134 | −Below is a sample code for registering/unregistering a service | |
| 135 | −driver. | |
| 136 | − | |
| 137 | −static int __init aerdrv_service_init(void) | |
| 138 | −{ | |
| 139 | − int retval = 0; | |
| 140 | − | |
| 141 | − retval = pcie_port_service_register(&root_aerdrv); | |
| 142 | − if (!retval) { | |
| 143 | − /* | |
| 144 | − * FIX ME | |
| 145 | − */ | |
| 146 | − } | |
| 147 | − return retval; | |
| 148 | −} | |
| 149 | − | |
| 150 | −static void __exit aerdrv_service_exit(void) | |
| 151 | −{ | |
| 152 | − pcie_port_service_unregister(&root_aerdrv); | |
| 153 | −} | |
| 154 | − | |
| 155 | −module_init(aerdrv_service_init); | |
| 156 | −module_exit(aerdrv_service_exit); | |
| 157 | − | |
| 158 | −6. Possible Resource Conflicts | |
| 159 | − | |
| 160 | −Since all service drivers of a PCI-PCI Bridge Port device are | |
| 161 | −allowed to run simultaneously, below lists a few of possible resource | |
| 162 | −conflicts with proposed solutions. | |
| 163 | − | |
| 164 | −6.1 MSI and MSI-X Vector Resource | |
| 165 | − | |
| 166 | −Once MSI or MSI-X interrupts are enabled on a device, it stays in this | |
| 167 | −mode until they are disabled again. Since service drivers of the same | |
| 168 | −PCI-PCI Bridge port share the same physical device, if an individual | |
| 169 | −service driver enables or disables MSI/MSI-X mode it may result | |
| 170 | −unpredictable behavior. | |
| 171 | − | |
| 172 | −To avoid this situation all service drivers are not permitted to | |
| 173 | −switch interrupt mode on its device. The PCI Express Port Bus driver | |
| 174 | −is responsible for determining the interrupt mode and this should be | |
| 175 | −transparent to service drivers. Service drivers need to know only | |
| 176 | −the vector IRQ assigned to the field irq of struct pcie_device, which | |
| 177 | −is passed in when the PCI Express Port Bus driver probes each service | |
| 178 | −driver. Service drivers should use (struct pcie_device*)dev->irq to | |
| 179 | −call request_irq/free_irq. In addition, the interrupt mode is stored | |
| 180 | −in the field interrupt_mode of struct pcie_device. | |
| 181 | − | |
| 182 | −6.3 PCI Memory/IO Mapped Regions | |
| 183 | − | |
| 184 | −Service drivers for PCI Express Power Management (PME), Advanced | |
| 185 | −Error Reporting (AER), Hot-Plug (HP) and Virtual Channel (VC) access | |
| 186 | −PCI configuration space on the PCI Express port. In all cases the | |
| 187 | −registers accessed are independent of each other. This patch assumes | |
| 188 | −that all service drivers will be well behaved and not overwrite | |
| 189 | −other service driver's configuration settings. | |
| 190 | − | |
| 191 | −6.4 PCI Config Registers | |
| 192 | − | |
| 193 | −Each service driver runs its PCI config operations on its own | |
| 194 | −capability structure except the PCI Express capability structure, in | |
| 195 | −which Root Control register and Device Control register are shared | |
| 196 | −between PME and AER. This patch assumes that all service drivers | |
| 197 | −will be well behaved and not overwrite other service driver's | |
| 198 | −configuration settings. | |
| @@ -0,0 +1,192 @@ | ||
| 1 | +.. SPDX-License-Identifier: GPL-2.0 | |
| 2 | + | |
| 3 | +======================================== | |
| 4 | +ACPI considerations for PCI host bridges | |
| 5 | +======================================== | |
| 6 | + | |
| 7 | +The general rule is that the ACPI namespace should describe everything the | |
| 8 | +OS might use unless there's another way for the OS to find it [1, 2]. | |
| 9 | + | |
| 10 | +For example, there's no standard hardware mechanism for enumerating PCI | |
| 11 | +host bridges, so the ACPI namespace must describe each host bridge, the | |
| 12 | +method for accessing PCI config space below it, the address space windows | |
| 13 | +the host bridge forwards to PCI (using _CRS), and the routing of legacy | |
| 14 | +INTx interrupts (using _PRT). | |
| 15 | + | |
| 16 | +PCI devices, which are below the host bridge, generally do not need to be | |
| 17 | +described via ACPI. The OS can discover them via the standard PCI | |
| 18 | +enumeration mechanism, using config accesses to discover and identify | |
| 19 | +devices and read and size their BARs. However, ACPI may describe PCI | |
| 20 | +devices if it provides power management or hotplug functionality for them | |
| 21 | +or if the device has INTx interrupts connected by platform interrupt | |
| 22 | +controllers and a _PRT is needed to describe those connections. | |
| 23 | + | |
| 24 | +ACPI resource description is done via _CRS objects of devices in the ACPI | |
| 25 | +namespace [2]. The _CRS is like a generalized PCI BAR: the OS can read | |
| 26 | +_CRS and figure out what resource is being consumed even if it doesn't have | |
| 27 | +a driver for the device [3]. That's important because it means an old OS | |
| 28 | +can work correctly even on a system with new devices unknown to the OS. | |
| 29 | +The new devices might not do anything, but the OS can at least make sure no | |
| 30 | +resources conflict with them. | |
| 31 | + | |
| 32 | +Static tables like MCFG, HPET, ECDT, etc., are *not* mechanisms for | |
| 33 | +reserving address space. The static tables are for things the OS needs to | |
| 34 | +know early in boot, before it can parse the ACPI namespace. If a new table | |
| 35 | +is defined, an old OS needs to operate correctly even though it ignores the | |
| 36 | +table. _CRS allows that because it is generic and understood by the old | |
| 37 | +OS; a static table does not. | |
| 38 | + | |
| 39 | +If the OS is expected to manage a non-discoverable device described via | |
| 40 | +ACPI, that device will have a specific _HID/_CID that tells the OS what | |
| 41 | +driver to bind to it, and the _CRS tells the OS and the driver where the | |
| 42 | +device's registers are. | |
| 43 | + | |
| 44 | +PCI host bridges are PNP0A03 or PNP0A08 devices. Their _CRS should | |
| 45 | +describe all the address space they consume. This includes all the windows | |
| 46 | +they forward down to the PCI bus, as well as registers of the host bridge | |
| 47 | +itself that are not forwarded to PCI. The host bridge registers include | |
| 48 | +things like secondary/subordinate bus registers that determine the bus | |
| 49 | +range below the bridge, window registers that describe the apertures, etc. | |
| 50 | +These are all device-specific, non-architected things, so the only way a | |
| 51 | +PNP0A03/PNP0A08 driver can manage them is via _PRS/_CRS/_SRS, which contain | |
| 52 | +the device-specific details. The host bridge registers also include ECAM | |
| 53 | +space, since it is consumed by the host bridge. | |
| 54 | + | |
| 55 | +ACPI defines a Consumer/Producer bit to distinguish the bridge registers | |
| 56 | +("Consumer") from the bridge apertures ("Producer") [4, 5], but early | |
| 57 | +BIOSes didn't use that bit correctly. The result is that the current ACPI | |
| 58 | +spec defines Consumer/Producer only for the Extended Address Space | |
| 59 | +descriptors; the bit should be ignored in the older QWord/DWord/Word | |
| 60 | +Address Space descriptors. Consequently, OSes have to assume all | |
| 61 | +QWord/DWord/Word descriptors are windows. | |
| 62 | + | |
| 63 | +Prior to the addition of Extended Address Space descriptors, the failure of | |
| 64 | +Consumer/Producer meant there was no way to describe bridge registers in | |
| 65 | +the PNP0A03/PNP0A08 device itself. The workaround was to describe the | |
| 66 | +bridge registers (including ECAM space) in PNP0C02 catch-all devices [6]. | |
| 67 | +With the exception of ECAM, the bridge register space is device-specific | |
| 68 | +anyway, so the generic PNP0A03/PNP0A08 driver (pci_root.c) has no need to | |
| 69 | +know about it. | |
| 70 | + | |
| 71 | +New architectures should be able to use "Consumer" Extended Address Space | |
| 72 | +descriptors in the PNP0A03 device for bridge registers, including ECAM, | |
| 73 | +although a strict interpretation of [6] might prohibit this. Old x86 and | |
| 74 | +ia64 kernels assume all address space descriptors, including "Consumer" | |
| 75 | +Extended Address Space ones, are windows, so it would not be safe to | |
| 76 | +describe bridge registers this way on those architectures. | |
| 77 | + | |
| 78 | +PNP0C02 "motherboard" devices are basically a catch-all. There's no | |
| 79 | +programming model for them other than "don't use these resources for | |
| 80 | +anything else." So a PNP0C02 _CRS should claim any address space that is | |
| 81 | +(1) not claimed by _CRS under any other device object in the ACPI namespace | |
| 82 | +and (2) should not be assigned by the OS to something else. | |
| 83 | + | |
| 84 | +The PCIe spec requires the Enhanced Configuration Access Method (ECAM) | |
| 85 | +unless there's a standard firmware interface for config access, e.g., the | |
| 86 | +ia64 SAL interface [7]. A host bridge consumes ECAM memory address space | |
| 87 | +and converts memory accesses into PCI configuration accesses. The spec | |
| 88 | +defines the ECAM address space layout and functionality; only the base of | |
| 89 | +the address space is device-specific. An ACPI OS learns the base address | |
| 90 | +from either the static MCFG table or a _CBA method in the PNP0A03 device. | |
| 91 | + | |
| 92 | +The MCFG table must describe the ECAM space of non-hot pluggable host | |
| 93 | +bridges [8]. Since MCFG is a static table and can't be updated by hotplug, | |
| 94 | +a _CBA method in the PNP0A03 device describes the ECAM space of a | |
| 95 | +hot-pluggable host bridge [9]. Note that for both MCFG and _CBA, the base | |
| 96 | +address always corresponds to bus 0, even if the bus range below the bridge | |
| 97 | +(which is reported via _CRS) doesn't start at 0. | |
| 98 | + | |
| 99 | + | |
| 100 | +[1] ACPI 6.2, sec 6.1: | |
| 101 | + For any device that is on a non-enumerable type of bus (for example, an | |
| 102 | + ISA bus), OSPM enumerates the devices' identifier(s) and the ACPI | |
| 103 | + system firmware must supply an _HID object ... for each device to | |
| 104 | + enable OSPM to do that. | |
| 105 | + | |
| 106 | +[2] ACPI 6.2, sec 3.7: | |
| 107 | + The OS enumerates motherboard devices simply by reading through the | |
| 108 | + ACPI Namespace looking for devices with hardware IDs. | |
| 109 | + | |
| 110 | + Each device enumerated by ACPI includes ACPI-defined objects in the | |
| 111 | + ACPI Namespace that report the hardware resources the device could | |
| 112 | + occupy [_PRS], an object that reports the resources that are currently | |
| 113 | + used by the device [_CRS], and objects for configuring those resources | |
| 114 | + [_SRS]. The information is used by the Plug and Play OS (OSPM) to | |
| 115 | + configure the devices. | |
| 116 | + | |
| 117 | +[3] ACPI 6.2, sec 6.2: | |
| 118 | + OSPM uses device configuration objects to configure hardware resources | |
| 119 | + for devices enumerated via ACPI. Device configuration objects provide | |
| 120 | + information about current and possible resource requirements, the | |
| 121 | + relationship between shared resources, and methods for configuring | |
| 122 | + hardware resources. | |
| 123 | + | |
| 124 | + When OSPM enumerates a device, it calls _PRS to determine the resource | |
| 125 | + requirements of the device. It may also call _CRS to find the current | |
| 126 | + resource settings for the device. Using this information, the Plug and | |
| 127 | + Play system determines what resources the device should consume and | |
| 128 | + sets those resources by calling the device’s _SRS control method. | |
| 129 | + | |
| 130 | + In ACPI, devices can consume resources (for example, legacy keyboards), | |
| 131 | + provide resources (for example, a proprietary PCI bridge), or do both. | |
| 132 | + Unless otherwise specified, resources for a device are assumed to be | |
| 133 | + taken from the nearest matching resource above the device in the device | |
| 134 | + hierarchy. | |
| 135 | + | |
| 136 | +[4] ACPI 6.2, sec 6.4.3.5.1, 2, 3, 4: | |
| 137 | + QWord/DWord/Word Address Space Descriptor (.1, .2, .3) | |
| 138 | + General Flags: Bit [0] Ignored | |
| 139 | + | |
| 140 | + Extended Address Space Descriptor (.4) | |
| 141 | + General Flags: Bit [0] Consumer/Producer: | |
| 142 | + | |
| 143 | + * 1 – This device consumes this resource | |
| 144 | + * 0 – This device produces and consumes this resource | |
| 145 | + | |
| 146 | +[5] ACPI 6.2, sec 19.6.43: | |
| 147 | + ResourceUsage specifies whether the Memory range is consumed by | |
| 148 | + this device (ResourceConsumer) or passed on to child devices | |
| 149 | + (ResourceProducer). If nothing is specified, then | |
| 150 | + ResourceConsumer is assumed. | |
| 151 | + | |
| 152 | +[6] PCI Firmware 3.2, sec 4.1.2: | |
| 153 | + If the operating system does not natively comprehend reserving the | |
| 154 | + MMCFG region, the MMCFG region must be reserved by firmware. The | |
| 155 | + address range reported in the MCFG table or by _CBA method (see Section | |
| 156 | + 4.1.3) must be reserved by declaring a motherboard resource. For most | |
| 157 | + systems, the motherboard resource would appear at the root of the ACPI | |
| 158 | + namespace (under \_SB) in a node with a _HID of EISAID (PNP0C02), and | |
| 159 | + the resources in this case should not be claimed in the root PCI bus’s | |
| 160 | + _CRS. The resources can optionally be returned in Int15 E820 or | |
| 161 | + EFIGetMemoryMap as reserved memory but must always be reported through | |
| 162 | + ACPI as a motherboard resource. | |
| 163 | + | |
| 164 | +[7] PCI Express 4.0, sec 7.2.2: | |
| 165 | + For systems that are PC-compatible, or that do not implement a | |
| 166 | + processor-architecture-specific firmware interface standard that allows | |
| 167 | + access to the Configuration Space, the ECAM is required as defined in | |
| 168 | + this section. | |
| 169 | + | |
| 170 | +[8] PCI Firmware 3.2, sec 4.1.2: | |
| 171 | + The MCFG table is an ACPI table that is used to communicate the base | |
| 172 | + addresses corresponding to the non-hot removable PCI Segment Groups | |
| 173 | + range within a PCI Segment Group available to the operating system at | |
| 174 | + boot. This is required for the PC-compatible systems. | |
| 175 | + | |
| 176 | + The MCFG table is only used to communicate the base addresses | |
| 177 | + corresponding to the PCI Segment Groups available to the system at | |
| 178 | + boot. | |
| 179 | + | |
| 180 | +[9] PCI Firmware 3.2, sec 4.1.3: | |
| 181 | + The _CBA (Memory mapped Configuration Base Address) control method is | |
| 182 | + an optional ACPI object that returns the 64-bit memory mapped | |
| 183 | + configuration base address for the hot plug capable host bridge. The | |
| 184 | + base address returned by _CBA is processor-relative address. The _CBA | |
| 185 | + control method evaluates to an Integer. | |
| 186 | + | |
| 187 | + This control method appears under a host bridge object. When the _CBA | |
| 188 | + method appears under an active host bridge object, the operating system | |
| 189 | + evaluates this structure to identify the memory mapped configuration | |
| 190 | + base address corresponding to the PCI Segment Group for the bus number | |
| 191 | + range specified in _CRS method. An ACPI name space object that contains | |
| 192 | + the _CBA method must also contain a corresponding _SEG method. | |
| @@ -1,187 +0,0 @@ | ||
| 1 | − ACPI considerations for PCI host bridges | |
| 2 | − | |
| 3 | −The general rule is that the ACPI namespace should describe everything the | |
| 4 | −OS might use unless there's another way for the OS to find it [1, 2]. | |
| 5 | − | |
| 6 | −For example, there's no standard hardware mechanism for enumerating PCI | |
| 7 | −host bridges, so the ACPI namespace must describe each host bridge, the | |
| 8 | −method for accessing PCI config space below it, the address space windows | |
| 9 | −the host bridge forwards to PCI (using _CRS), and the routing of legacy | |
| 10 | −INTx interrupts (using _PRT). | |
| 11 | − | |
| 12 | −PCI devices, which are below the host bridge, generally do not need to be | |
| 13 | −described via ACPI. The OS can discover them via the standard PCI | |
| 14 | −enumeration mechanism, using config accesses to discover and identify | |
| 15 | −devices and read and size their BARs. However, ACPI may describe PCI | |
| 16 | −devices if it provides power management or hotplug functionality for them | |
| 17 | −or if the device has INTx interrupts connected by platform interrupt | |
| 18 | −controllers and a _PRT is needed to describe those connections. | |
| 19 | − | |
| 20 | −ACPI resource description is done via _CRS objects of devices in the ACPI | |
| 21 | −namespace [2]. The _CRS is like a generalized PCI BAR: the OS can read | |
| 22 | −_CRS and figure out what resource is being consumed even if it doesn't have | |
| 23 | −a driver for the device [3]. That's important because it means an old OS | |
| 24 | −can work correctly even on a system with new devices unknown to the OS. | |
| 25 | −The new devices might not do anything, but the OS can at least make sure no | |
| 26 | −resources conflict with them. | |
| 27 | − | |
| 28 | −Static tables like MCFG, HPET, ECDT, etc., are *not* mechanisms for | |
| 29 | −reserving address space. The static tables are for things the OS needs to | |
| 30 | −know early in boot, before it can parse the ACPI namespace. If a new table | |
| 31 | −is defined, an old OS needs to operate correctly even though it ignores the | |
| 32 | −table. _CRS allows that because it is generic and understood by the old | |
| 33 | −OS; a static table does not. | |
| 34 | − | |
| 35 | −If the OS is expected to manage a non-discoverable device described via | |
| 36 | −ACPI, that device will have a specific _HID/_CID that tells the OS what | |
| 37 | −driver to bind to it, and the _CRS tells the OS and the driver where the | |
| 38 | −device's registers are. | |
| 39 | − | |
| 40 | −PCI host bridges are PNP0A03 or PNP0A08 devices. Their _CRS should | |
| 41 | −describe all the address space they consume. This includes all the windows | |
| 42 | −they forward down to the PCI bus, as well as registers of the host bridge | |
| 43 | −itself that are not forwarded to PCI. The host bridge registers include | |
| 44 | −things like secondary/subordinate bus registers that determine the bus | |
| 45 | −range below the bridge, window registers that describe the apertures, etc. | |
| 46 | −These are all device-specific, non-architected things, so the only way a | |
| 47 | −PNP0A03/PNP0A08 driver can manage them is via _PRS/_CRS/_SRS, which contain | |
| 48 | −the device-specific details. The host bridge registers also include ECAM | |
| 49 | −space, since it is consumed by the host bridge. | |
| 50 | − | |
| 51 | −ACPI defines a Consumer/Producer bit to distinguish the bridge registers | |
| 52 | −("Consumer") from the bridge apertures ("Producer") [4, 5], but early | |
| 53 | −BIOSes didn't use that bit correctly. The result is that the current ACPI | |
| 54 | −spec defines Consumer/Producer only for the Extended Address Space | |
| 55 | −descriptors; the bit should be ignored in the older QWord/DWord/Word | |
| 56 | −Address Space descriptors. Consequently, OSes have to assume all | |
| 57 | −QWord/DWord/Word descriptors are windows. | |
| 58 | − | |
| 59 | −Prior to the addition of Extended Address Space descriptors, the failure of | |
| 60 | −Consumer/Producer meant there was no way to describe bridge registers in | |
| 61 | −the PNP0A03/PNP0A08 device itself. The workaround was to describe the | |
| 62 | −bridge registers (including ECAM space) in PNP0C02 catch-all devices [6]. | |
| 63 | −With the exception of ECAM, the bridge register space is device-specific | |
| 64 | −anyway, so the generic PNP0A03/PNP0A08 driver (pci_root.c) has no need to | |
| 65 | −know about it. | |
| 66 | − | |
| 67 | −New architectures should be able to use "Consumer" Extended Address Space | |
| 68 | −descriptors in the PNP0A03 device for bridge registers, including ECAM, | |
| 69 | −although a strict interpretation of [6] might prohibit this. Old x86 and | |
| 70 | −ia64 kernels assume all address space descriptors, including "Consumer" | |
| 71 | −Extended Address Space ones, are windows, so it would not be safe to | |
| 72 | −describe bridge registers this way on those architectures. | |
| 73 | − | |
| 74 | −PNP0C02 "motherboard" devices are basically a catch-all. There's no | |
| 75 | −programming model for them other than "don't use these resources for | |
| 76 | −anything else." So a PNP0C02 _CRS should claim any address space that is | |
| 77 | −(1) not claimed by _CRS under any other device object in the ACPI namespace | |
| 78 | −and (2) should not be assigned by the OS to something else. | |
| 79 | − | |
| 80 | −The PCIe spec requires the Enhanced Configuration Access Method (ECAM) | |
| 81 | −unless there's a standard firmware interface for config access, e.g., the | |
| 82 | −ia64 SAL interface [7]. A host bridge consumes ECAM memory address space | |
| 83 | −and converts memory accesses into PCI configuration accesses. The spec | |
| 84 | −defines the ECAM address space layout and functionality; only the base of | |
| 85 | −the address space is device-specific. An ACPI OS learns the base address | |
| 86 | −from either the static MCFG table or a _CBA method in the PNP0A03 device. | |
| 87 | − | |
| 88 | −The MCFG table must describe the ECAM space of non-hot pluggable host | |
| 89 | −bridges [8]. Since MCFG is a static table and can't be updated by hotplug, | |
| 90 | −a _CBA method in the PNP0A03 device describes the ECAM space of a | |
| 91 | −hot-pluggable host bridge [9]. Note that for both MCFG and _CBA, the base | |
| 92 | −address always corresponds to bus 0, even if the bus range below the bridge | |
| 93 | −(which is reported via _CRS) doesn't start at 0. | |
| 94 | − | |
| 95 | − | |
| 96 | −[1] ACPI 6.2, sec 6.1: | |
| 97 | − For any device that is on a non-enumerable type of bus (for example, an | |
| 98 | − ISA bus), OSPM enumerates the devices' identifier(s) and the ACPI | |
| 99 | − system firmware must supply an _HID object ... for each device to | |
| 100 | − enable OSPM to do that. | |
| 101 | − | |
| 102 | −[2] ACPI 6.2, sec 3.7: | |
| 103 | − The OS enumerates motherboard devices simply by reading through the | |
| 104 | − ACPI Namespace looking for devices with hardware IDs. | |
| 105 | − | |
| 106 | − Each device enumerated by ACPI includes ACPI-defined objects in the | |
| 107 | − ACPI Namespace that report the hardware resources the device could | |
| 108 | − occupy [_PRS], an object that reports the resources that are currently | |
| 109 | − used by the device [_CRS], and objects for configuring those resources | |
| 110 | − [_SRS]. The information is used by the Plug and Play OS (OSPM) to | |
| 111 | − configure the devices. | |
| 112 | − | |
| 113 | −[3] ACPI 6.2, sec 6.2: | |
| 114 | − OSPM uses device configuration objects to configure hardware resources | |
| 115 | − for devices enumerated via ACPI. Device configuration objects provide | |
| 116 | − information about current and possible resource requirements, the | |
| 117 | − relationship between shared resources, and methods for configuring | |
| 118 | − hardware resources. | |
| 119 | − | |
| 120 | − When OSPM enumerates a device, it calls _PRS to determine the resource | |
| 121 | − requirements of the device. It may also call _CRS to find the current | |
| 122 | − resource settings for the device. Using this information, the Plug and | |
| 123 | − Play system determines what resources the device should consume and | |
| 124 | − sets those resources by calling the device’s _SRS control method. | |
| 125 | − | |
| 126 | − In ACPI, devices can consume resources (for example, legacy keyboards), | |
| 127 | − provide resources (for example, a proprietary PCI bridge), or do both. | |
| 128 | − Unless otherwise specified, resources for a device are assumed to be | |
| 129 | − taken from the nearest matching resource above the device in the device | |
| 130 | − hierarchy. | |
| 131 | − | |
| 132 | −[4] ACPI 6.2, sec 6.4.3.5.1, 2, 3, 4: | |
| 133 | − QWord/DWord/Word Address Space Descriptor (.1, .2, .3) | |
| 134 | − General Flags: Bit [0] Ignored | |
| 135 | − | |
| 136 | − Extended Address Space Descriptor (.4) | |
| 137 | − General Flags: Bit [0] Consumer/Producer: | |
| 138 | − 1–This device consumes this resource | |
| 139 | − 0–This device produces and consumes this resource | |
| 140 | − | |
| 141 | −[5] ACPI 6.2, sec 19.6.43: | |
| 142 | − ResourceUsage specifies whether the Memory range is consumed by | |
| 143 | − this device (ResourceConsumer) or passed on to child devices | |
| 144 | − (ResourceProducer). If nothing is specified, then | |
| 145 | − ResourceConsumer is assumed. | |
| 146 | − | |
| 147 | −[6] PCI Firmware 3.2, sec 4.1.2: | |
| 148 | − If the operating system does not natively comprehend reserving the | |
| 149 | − MMCFG region, the MMCFG region must be reserved by firmware. The | |
| 150 | − address range reported in the MCFG table or by _CBA method (see Section | |
| 151 | − 4.1.3) must be reserved by declaring a motherboard resource. For most | |
| 152 | − systems, the motherboard resource would appear at the root of the ACPI | |
| 153 | − namespace (under \_SB) in a node with a _HID of EISAID (PNP0C02), and | |
| 154 | − the resources in this case should not be claimed in the root PCI bus’s | |
| 155 | − _CRS. The resources can optionally be returned in Int15 E820 or | |
| 156 | − EFIGetMemoryMap as reserved memory but must always be reported through | |
| 157 | − ACPI as a motherboard resource. | |
| 158 | − | |
| 159 | −[7] PCI Express 4.0, sec 7.2.2: | |
| 160 | − For systems that are PC-compatible, or that do not implement a | |
| 161 | − processor-architecture-specific firmware interface standard that allows | |
| 162 | − access to the Configuration Space, the ECAM is required as defined in | |
| 163 | − this section. | |
| 164 | − | |
| 165 | −[8] PCI Firmware 3.2, sec 4.1.2: | |
| 166 | − The MCFG table is an ACPI table that is used to communicate the base | |
| 167 | − addresses corresponding to the non-hot removable PCI Segment Groups | |
| 168 | − range within a PCI Segment Group available to the operating system at | |
| 169 | − boot. This is required for the PC-compatible systems. | |
| 170 | − | |
| 171 | − The MCFG table is only used to communicate the base addresses | |
| 172 | − corresponding to the PCI Segment Groups available to the system at | |
| 173 | − boot. | |
| 174 | − | |
| 175 | −[9] PCI Firmware 3.2, sec 4.1.3: | |
| 176 | − The _CBA (Memory mapped Configuration Base Address) control method is | |
| 177 | − an optional ACPI object that returns the 64-bit memory mapped | |
| 178 | − configuration base address for the hot plug capable host bridge. The | |
| 179 | − base address returned by _CBA is processor-relative address. The _CBA | |
| 180 | − control method evaluates to an Integer. | |
| 181 | − | |
| 182 | − This control method appears under a host bridge object. When the _CBA | |
| 183 | − method appears under an active host bridge object, the operating system | |
| 184 | − evaluates this structure to identify the memory mapped configuration | |
| 185 | − base address corresponding to the PCI Segment Group for the bus number | |
| 186 | − range specified in _CRS method. An ACPI name space object that contains | |
| 187 | − the _CBA method must also contain a corresponding _SEG method. | |
| @@ -0,0 +1,13 @@ | ||
| 1 | +.. SPDX-License-Identifier: GPL-2.0 | |
| 2 | + | |
| 3 | +====================== | |
| 4 | +PCI Endpoint Framework | |
| 5 | +====================== | |
| 6 | + | |
| 7 | +.. toctree:: | |
| 8 | + :maxdepth: 2 | |
| 9 | + | |
| 10 | + pci-endpoint | |
| 11 | + pci-endpoint-cfs | |
| 12 | + pci-test-function | |
| 13 | + pci-test-howto | |
| @@ -0,0 +1,118 @@ | ||
| 1 | +.. SPDX-License-Identifier: GPL-2.0 | |
| 2 | + | |
| 3 | +======================================= | |
| 4 | +Configuring PCI Endpoint Using CONFIGFS | |
| 5 | +======================================= | |
| 6 | + | |
| 7 | +:Author: Kishon Vijay Abraham I <kishon@ti.com> | |
| 8 | + | |
| 9 | +The PCI Endpoint Core exposes configfs entry (pci_ep) to configure the | |
| 10 | +PCI endpoint function and to bind the endpoint function | |
| 11 | +with the endpoint controller. (For introducing other mechanisms to | |
| 12 | +configure the PCI Endpoint Function refer to [1]). | |
| 13 | + | |
| 14 | +Mounting configfs | |
| 15 | +================= | |
| 16 | + | |
| 17 | +The PCI Endpoint Core layer creates pci_ep directory in the mounted configfs | |
| 18 | +directory. configfs can be mounted using the following command:: | |
| 19 | + | |
| 20 | + mount -t configfs none /sys/kernel/config | |
| 21 | + | |
| 22 | +Directory Structure | |
| 23 | +=================== | |
| 24 | + | |
| 25 | +The pci_ep configfs has two directories at its root: controllers and | |
| 26 | +functions. Every EPC device present in the system will have an entry in | |
| 27 | +the *controllers* directory and and every EPF driver present in the system | |
| 28 | +will have an entry in the *functions* directory. | |
| 29 | +:: | |
| 30 | + | |
| 31 | + /sys/kernel/config/pci_ep/ | |
| 32 | + .. controllers/ | |
| 33 | + .. functions/ | |
| 34 | + | |
| 35 | +Creating EPF Device | |
| 36 | +=================== | |
| 37 | + | |
| 38 | +Every registered EPF driver will be listed in controllers directory. The | |
| 39 | +entries corresponding to EPF driver will be created by the EPF core. | |
| 40 | +:: | |
| 41 | + | |
| 42 | + /sys/kernel/config/pci_ep/functions/ | |
| 43 | + .. <EPF Driver1>/ | |
| 44 | + ... <EPF Device 11>/ | |
| 45 | + ... <EPF Device 21>/ | |
| 46 | + .. <EPF Driver2>/ | |
| 47 | + ... <EPF Device 12>/ | |
| 48 | + ... <EPF Device 22>/ | |
| 49 | + | |
| 50 | +In order to create a <EPF device> of the type probed by <EPF Driver>, the | |
| 51 | +user has to create a directory inside <EPF DriverN>. | |
| 52 | + | |
| 53 | +Every <EPF device> directory consists of the following entries that can be | |
| 54 | +used to configure the standard configuration header of the endpoint function. | |
| 55 | +(These entries are created by the framework when any new <EPF Device> is | |
| 56 | +created) | |
| 57 | +:: | |
| 58 | + | |
| 59 | + .. <EPF Driver1>/ | |
| 60 | + ... <EPF Device 11>/ | |
| 61 | + ... vendorid | |
| 62 | + ... deviceid | |
| 63 | + ... revid | |
| 64 | + ... progif_code | |
| 65 | + ... subclass_code | |
| 66 | + ... baseclass_code | |
| 67 | + ... cache_line_size | |
| 68 | + ... subsys_vendor_id | |
| 69 | + ... subsys_id | |
| 70 | + ... interrupt_pin | |
| 71 | + | |
| 72 | +EPC Device | |
| 73 | +========== | |
| 74 | + | |
| 75 | +Every registered EPC device will be listed in controllers directory. The | |
| 76 | +entries corresponding to EPC device will be created by the EPC core. | |
| 77 | +:: | |
| 78 | + | |
| 79 | + /sys/kernel/config/pci_ep/controllers/ | |
| 80 | + .. <EPC Device1>/ | |
| 81 | + ... <Symlink EPF Device11>/ | |
| 82 | + ... <Symlink EPF Device12>/ | |
| 83 | + ... start | |
| 84 | + .. <EPC Device2>/ | |
| 85 | + ... <Symlink EPF Device21>/ | |
| 86 | + ... <Symlink EPF Device22>/ | |
| 87 | + ... start | |
| 88 | + | |
| 89 | +The <EPC Device> directory will have a list of symbolic links to | |
| 90 | +<EPF Device>. These symbolic links should be created by the user to | |
| 91 | +represent the functions present in the endpoint device. | |
| 92 | + | |
| 93 | +The <EPC Device> directory will also have a *start* field. Once | |
| 94 | +"1" is written to this field, the endpoint device will be ready to | |
| 95 | +establish the link with the host. This is usually done after | |
| 96 | +all the EPF devices are created and linked with the EPC device. | |
| 97 | +:: | |
| 98 | + | |
| 99 | + | controllers/ | |
| 100 | + | <Directory: EPC name>/ | |
| 101 | + | <Symbolic Link: Function> | |
| 102 | + | start | |
| 103 | + | functions/ | |
| 104 | + | <Directory: EPF driver>/ | |
| 105 | + | <Directory: EPF device>/ | |
| 106 | + | vendorid | |
| 107 | + | deviceid | |
| 108 | + | revid | |
| 109 | + | progif_code | |
| 110 | + | subclass_code | |
| 111 | + | baseclass_code | |
| 112 | + | cache_line_size | |
| 113 | + | subsys_vendor_id | |
| 114 | + | subsys_id | |
| 115 | + | interrupt_pin | |
| 116 | + | function | |
| 117 | + | |
| 118 | +[1] :doc:`pci-endpoint` | |
| @@ -1,105 +0,0 @@ | ||
| 1 | − CONFIGURING PCI ENDPOINT USING CONFIGFS | |
| 2 | − Kishon Vijay Abraham I <kishon@ti.com> | |
| 3 | − | |
| 4 | −The PCI Endpoint Core exposes configfs entry (pci_ep) to configure the | |
| 5 | −PCI endpoint function and to bind the endpoint function | |
| 6 | −with the endpoint controller. (For introducing other mechanisms to | |
| 7 | −configure the PCI Endpoint Function refer to [1]). | |
| 8 | − | |
| 9 | −*) Mounting configfs | |
| 10 | − | |
| 11 | −The PCI Endpoint Core layer creates pci_ep directory in the mounted configfs | |
| 12 | −directory. configfs can be mounted using the following command. | |
| 13 | − | |
| 14 | − mount -t configfs none /sys/kernel/config | |
| 15 | − | |
| 16 | −*) Directory Structure | |
| 17 | − | |
| 18 | −The pci_ep configfs has two directories at its root: controllers and | |
| 19 | −functions. Every EPC device present in the system will have an entry in | |
| 20 | −the *controllers* directory and and every EPF driver present in the system | |
| 21 | −will have an entry in the *functions* directory. | |
| 22 | − | |
| 23 | −/sys/kernel/config/pci_ep/ | |
| 24 | − .. controllers/ | |
| 25 | − .. functions/ | |
| 26 | − | |
| 27 | −*) Creating EPF Device | |
| 28 | − | |
| 29 | −Every registered EPF driver will be listed in controllers directory. The | |
| 30 | −entries corresponding to EPF driver will be created by the EPF core. | |
| 31 | − | |
| 32 | −/sys/kernel/config/pci_ep/functions/ | |
| 33 | − .. <EPF Driver1>/ | |
| 34 | − ... <EPF Device 11>/ | |
| 35 | − ... <EPF Device 21>/ | |
| 36 | − .. <EPF Driver2>/ | |
| 37 | − ... <EPF Device 12>/ | |
| 38 | − ... <EPF Device 22>/ | |
| 39 | − | |
| 40 | −In order to create a <EPF device> of the type probed by <EPF Driver>, the | |
| 41 | −user has to create a directory inside <EPF DriverN>. | |
| 42 | − | |
| 43 | −Every <EPF device> directory consists of the following entries that can be | |
| 44 | −used to configure the standard configuration header of the endpoint function. | |
| 45 | −(These entries are created by the framework when any new <EPF Device> is | |
| 46 | −created) | |
| 47 | − | |
| 48 | − .. <EPF Driver1>/ | |
| 49 | − ... <EPF Device 11>/ | |
| 50 | − ... vendorid | |
| 51 | − ... deviceid | |
| 52 | − ... revid | |
| 53 | − ... progif_code | |
| 54 | − ... subclass_code | |
| 55 | − ... baseclass_code | |
| 56 | − ... cache_line_size | |
| 57 | − ... subsys_vendor_id | |
| 58 | − ... subsys_id | |
| 59 | − ... interrupt_pin | |
| 60 | − | |
| 61 | −*) EPC Device | |
| 62 | − | |
| 63 | −Every registered EPC device will be listed in controllers directory. The | |
| 64 | −entries corresponding to EPC device will be created by the EPC core. | |
| 65 | − | |
| 66 | −/sys/kernel/config/pci_ep/controllers/ | |
| 67 | − .. <EPC Device1>/ | |
| 68 | − ... <Symlink EPF Device11>/ | |
| 69 | − ... <Symlink EPF Device12>/ | |
| 70 | − ... start | |
| 71 | − .. <EPC Device2>/ | |
| 72 | − ... <Symlink EPF Device21>/ | |
| 73 | − ... <Symlink EPF Device22>/ | |
| 74 | − ... start | |
| 75 | − | |
| 76 | −The <EPC Device> directory will have a list of symbolic links to | |
| 77 | −<EPF Device>. These symbolic links should be created by the user to | |
| 78 | −represent the functions present in the endpoint device. | |
| 79 | − | |
| 80 | −The <EPC Device> directory will also have a *start* field. Once | |
| 81 | −"1" is written to this field, the endpoint device will be ready to | |
| 82 | −establish the link with the host. This is usually done after | |
| 83 | −all the EPF devices are created and linked with the EPC device. | |
| 84 | − | |
| 85 | − | |
| 86 | − | controllers/ | |
| 87 | − | <Directory: EPC name>/ | |
| 88 | − | <Symbolic Link: Function> | |
| 89 | − | start | |
| 90 | − | functions/ | |
| 91 | − | <Directory: EPF driver>/ | |
| 92 | − | <Directory: EPF device>/ | |
| 93 | − | vendorid | |
| 94 | − | deviceid | |
| 95 | − | revid | |
| 96 | − | progif_code | |
| 97 | − | subclass_code | |
| 98 | − | baseclass_code | |
| 99 | − | cache_line_size | |
| 100 | − | subsys_vendor_id | |
| 101 | − | subsys_id | |
| 102 | − | interrupt_pin | |
| 103 | − | function | |
| 104 | − | |
| 105 | −[1] -> Documentation/PCI/endpoint/pci-endpoint.txt | |
| @@ -0,0 +1,231 @@ | ||
| 1 | +.. SPDX-License-Identifier: GPL-2.0 | |
| 2 | + | |
| 3 | +:Author: Kishon Vijay Abraham I <kishon@ti.com> | |
| 4 | + | |
| 5 | +This document is a guide to use the PCI Endpoint Framework in order to create | |
| 6 | +endpoint controller driver, endpoint function driver, and using configfs | |
| 7 | +interface to bind the function driver to the controller driver. | |
| 8 | + | |
| 9 | +Introduction | |
| 10 | +============ | |
| 11 | + | |
| 12 | +Linux has a comprehensive PCI subsystem to support PCI controllers that | |
| 13 | +operates in Root Complex mode. The subsystem has capability to scan PCI bus, | |
| 14 | +assign memory resources and IRQ resources, load PCI driver (based on | |
| 15 | +vendor ID, device ID), support other services like hot-plug, power management, | |
| 16 | +advanced error reporting and virtual channels. | |
| 17 | + | |
| 18 | +However the PCI controller IP integrated in some SoCs is capable of operating | |
| 19 | +either in Root Complex mode or Endpoint mode. PCI Endpoint Framework will | |
| 20 | +add endpoint mode support in Linux. This will help to run Linux in an | |
| 21 | +EP system which can have a wide variety of use cases from testing or | |
| 22 | +validation, co-processor accelerator, etc. | |
| 23 | + | |
| 24 | +PCI Endpoint Core | |
| 25 | +================= | |
| 26 | + | |
| 27 | +The PCI Endpoint Core layer comprises 3 components: the Endpoint Controller | |
| 28 | +library, the Endpoint Function library, and the configfs layer to bind the | |
| 29 | +endpoint function with the endpoint controller. | |
| 30 | + | |
| 31 | +PCI Endpoint Controller(EPC) Library | |
| 32 | +------------------------------------ | |
| 33 | + | |
| 34 | +The EPC library provides APIs to be used by the controller that can operate | |
| 35 | +in endpoint mode. It also provides APIs to be used by function driver/library | |
| 36 | +in order to implement a particular endpoint function. | |
| 37 | + | |
| 38 | +APIs for the PCI controller Driver | |
| 39 | +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ | |
| 40 | + | |
| 41 | +This section lists the APIs that the PCI Endpoint core provides to be used | |
| 42 | +by the PCI controller driver. | |
| 43 | + | |
| 44 | +* devm_pci_epc_create()/pci_epc_create() | |
| 45 | + | |
| 46 | + The PCI controller driver should implement the following ops: | |
| 47 | + | |
| 48 | + * write_header: ops to populate configuration space header | |
| 49 | + * set_bar: ops to configure the BAR | |
| 50 | + * clear_bar: ops to reset the BAR | |
| 51 | + * alloc_addr_space: ops to allocate in PCI controller address space | |
| 52 | + * free_addr_space: ops to free the allocated address space | |
| 53 | + * raise_irq: ops to raise a legacy, MSI or MSI-X interrupt | |
| 54 | + * start: ops to start the PCI link | |
| 55 | + * stop: ops to stop the PCI link | |
| 56 | + | |
| 57 | + The PCI controller driver can then create a new EPC device by invoking | |
| 58 | + devm_pci_epc_create()/pci_epc_create(). | |
| 59 | + | |
| 60 | +* devm_pci_epc_destroy()/pci_epc_destroy() | |
| 61 | + | |
| 62 | + The PCI controller driver can destroy the EPC device created by either | |
| 63 | + devm_pci_epc_create() or pci_epc_create() using devm_pci_epc_destroy() or | |
| 64 | + pci_epc_destroy(). | |
| 65 | + | |
| 66 | +* pci_epc_linkup() | |
| 67 | + | |
| 68 | + In order to notify all the function devices that the EPC device to which | |
| 69 | + they are linked has established a link with the host, the PCI controller | |
| 70 | + driver should invoke pci_epc_linkup(). | |
| 71 | + | |
| 72 | +* pci_epc_mem_init() | |
| 73 | + | |
| 74 | + Initialize the pci_epc_mem structure used for allocating EPC addr space. | |
| 75 | + | |
| 76 | +* pci_epc_mem_exit() | |
| 77 | + | |
| 78 | + Cleanup the pci_epc_mem structure allocated during pci_epc_mem_init(). | |
| 79 | + | |
| 80 | + | |
| 81 | +APIs for the PCI Endpoint Function Driver | |
| 82 | +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ | |
| 83 | + | |
| 84 | +This section lists the APIs that the PCI Endpoint core provides to be used | |
| 85 | +by the PCI endpoint function driver. | |
| 86 | + | |
| 87 | +* pci_epc_write_header() | |
| 88 | + | |
| 89 | + The PCI endpoint function driver should use pci_epc_write_header() to | |
| 90 | + write the standard configuration header to the endpoint controller. | |
| 91 | + | |
| 92 | +* pci_epc_set_bar() | |
| 93 | + | |
| 94 | + The PCI endpoint function driver should use pci_epc_set_bar() to configure | |
| 95 | + the Base Address Register in order for the host to assign PCI addr space. | |
| 96 | + Register space of the function driver is usually configured | |
| 97 | + using this API. | |
| 98 | + | |
| 99 | +* pci_epc_clear_bar() | |
| 100 | + | |
| 101 | + The PCI endpoint function driver should use pci_epc_clear_bar() to reset | |
| 102 | + the BAR. | |
| 103 | + | |
| 104 | +* pci_epc_raise_irq() | |
| 105 | + | |
| 106 | + The PCI endpoint function driver should use pci_epc_raise_irq() to raise | |
| 107 | + Legacy Interrupt, MSI or MSI-X Interrupt. | |
| 108 | + | |
| 109 | +* pci_epc_mem_alloc_addr() | |
| 110 | + | |
| 111 | + The PCI endpoint function driver should use pci_epc_mem_alloc_addr(), to | |
| 112 | + allocate memory address from EPC addr space which is required to access | |
| 113 | + RC's buffer | |
| 114 | + | |
| 115 | +* pci_epc_mem_free_addr() | |
| 116 | + | |
| 117 | + The PCI endpoint function driver should use pci_epc_mem_free_addr() to | |
| 118 | + free the memory space allocated using pci_epc_mem_alloc_addr(). | |
| 119 | + | |
| 120 | +Other APIs | |
| 121 | +~~~~~~~~~~ | |
| 122 | + | |
| 123 | +There are other APIs provided by the EPC library. These are used for binding | |
| 124 | +the EPF device with EPC device. pci-ep-cfs.c can be used as reference for | |
| 125 | +using these APIs. | |
| 126 | + | |
| 127 | +* pci_epc_get() | |
| 128 | + | |
| 129 | + Get a reference to the PCI endpoint controller based on the device name of | |
| 130 | + the controller. | |
| 131 | + | |
| 132 | +* pci_epc_put() | |
| 133 | + | |
| 134 | + Release the reference to the PCI endpoint controller obtained using | |
| 135 | + pci_epc_get() | |
| 136 | + | |
| 137 | +* pci_epc_add_epf() | |
| 138 | + | |
| 139 | + Add a PCI endpoint function to a PCI endpoint controller. A PCIe device | |
| 140 | + can have up to 8 functions according to the specification. | |
| 141 | + | |
| 142 | +* pci_epc_remove_epf() | |
| 143 | + | |
| 144 | + Remove the PCI endpoint function from PCI endpoint controller. | |
| 145 | + | |
| 146 | +* pci_epc_start() | |
| 147 | + | |
| 148 | + The PCI endpoint function driver should invoke pci_epc_start() once it | |
| 149 | + has configured the endpoint function and wants to start the PCI link. | |
| 150 | + | |
| 151 | +* pci_epc_stop() | |
| 152 | + | |
| 153 | + The PCI endpoint function driver should invoke pci_epc_stop() to stop | |
| 154 | + the PCI LINK. | |
| 155 | + | |
| 156 | + | |
| 157 | +PCI Endpoint Function(EPF) Library | |
| 158 | +---------------------------------- | |
| 159 | + | |
| 160 | +The EPF library provides APIs to be used by the function driver and the EPC | |
| 161 | +library to provide endpoint mode functionality. | |
| 162 | + | |
| 163 | +APIs for the PCI Endpoint Function Driver | |
| 164 | +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ | |
| 165 | + | |
| 166 | +This section lists the APIs that the PCI Endpoint core provides to be used | |
| 167 | +by the PCI endpoint function driver. | |
| 168 | + | |
| 169 | +* pci_epf_register_driver() | |
| 170 | + | |
| 171 | + The PCI Endpoint Function driver should implement the following ops: | |
| 172 | + * bind: ops to perform when a EPC device has been bound to EPF device | |
| 173 | + * unbind: ops to perform when a binding has been lost between a EPC | |
| 174 | + device and EPF device | |
| 175 | + * linkup: ops to perform when the EPC device has established a | |
| 176 | + connection with a host system | |
| 177 | + | |
| 178 | + The PCI Function driver can then register the PCI EPF driver by using | |
| 179 | + pci_epf_register_driver(). | |
| 180 | + | |
| 181 | +* pci_epf_unregister_driver() | |
| 182 | + | |
| 183 | + The PCI Function driver can unregister the PCI EPF driver by using | |
| 184 | + pci_epf_unregister_driver(). | |
| 185 | + | |
| 186 | +* pci_epf_alloc_space() | |
| 187 | + | |
| 188 | + The PCI Function driver can allocate space for a particular BAR using | |
| 189 | + pci_epf_alloc_space(). | |
| 190 | + | |
| 191 | +* pci_epf_free_space() | |
| 192 | + | |
| 193 | + The PCI Function driver can free the allocated space | |
| 194 | + (using pci_epf_alloc_space) by invoking pci_epf_free_space(). | |
| 195 | + | |
| 196 | +APIs for the PCI Endpoint Controller Library | |
| 197 | +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ | |
| 198 | + | |
| 199 | +This section lists the APIs that the PCI Endpoint core provides to be used | |
| 200 | +by the PCI endpoint controller library. | |
| 201 | + | |
| 202 | +* pci_epf_linkup() | |
| 203 | + | |
| 204 | + The PCI endpoint controller library invokes pci_epf_linkup() when the | |
| 205 | + EPC device has established the connection to the host. | |
| 206 | + | |
| 207 | +Other APIs | |
| 208 | +~~~~~~~~~~ | |
| 209 | + | |
| 210 | +There are other APIs provided by the EPF library. These are used to notify | |
| 211 | +the function driver when the EPF device is bound to the EPC device. | |
| 212 | +pci-ep-cfs.c can be used as reference for using these APIs. | |
| 213 | + | |
| 214 | +* pci_epf_create() | |
| 215 | + | |
| 216 | + Create a new PCI EPF device by passing the name of the PCI EPF device. | |
| 217 | + This name will be used to bind the the EPF device to a EPF driver. | |
| 218 | + | |
| 219 | +* pci_epf_destroy() | |
| 220 | + | |
| 221 | + Destroy the created PCI EPF device. | |
| 222 | + | |
| 223 | +* pci_epf_bind() | |
| 224 | + | |
| 225 | + pci_epf_bind() should be invoked when the EPF device has been bound to | |
| 226 | + a EPC device. | |
| 227 | + | |
| 228 | +* pci_epf_unbind() | |
| 229 | + | |
| 230 | + pci_epf_unbind() should be invoked when the binding between EPC device | |
| 231 | + and EPF device is lost. | |
| @@ -1,215 +0,0 @@ | ||
| 1 | − PCI ENDPOINT FRAMEWORK | |
| 2 | − Kishon Vijay Abraham I <kishon@ti.com> | |
| 3 | − | |
| 4 | −This document is a guide to use the PCI Endpoint Framework in order to create | |
| 5 | −endpoint controller driver, endpoint function driver, and using configfs | |
| 6 | −interface to bind the function driver to the controller driver. | |
| 7 | − | |
| 8 | −1. Introduction | |
| 9 | − | |
| 10 | −Linux has a comprehensive PCI subsystem to support PCI controllers that | |
| 11 | −operates in Root Complex mode. The subsystem has capability to scan PCI bus, | |
| 12 | −assign memory resources and IRQ resources, load PCI driver (based on | |
| 13 | −vendor ID, device ID), support other services like hot-plug, power management, | |
| 14 | −advanced error reporting and virtual channels. | |
| 15 | − | |
| 16 | −However the PCI controller IP integrated in some SoCs is capable of operating | |
| 17 | −either in Root Complex mode or Endpoint mode. PCI Endpoint Framework will | |
| 18 | −add endpoint mode support in Linux. This will help to run Linux in an | |
| 19 | −EP system which can have a wide variety of use cases from testing or | |
| 20 | −validation, co-processor accelerator, etc. | |
| 21 | − | |
| 22 | −2. PCI Endpoint Core | |
| 23 | − | |
| 24 | −The PCI Endpoint Core layer comprises 3 components: the Endpoint Controller | |
| 25 | −library, the Endpoint Function library, and the configfs layer to bind the | |
| 26 | −endpoint function with the endpoint controller. | |
| 27 | − | |
| 28 | −2.1 PCI Endpoint Controller(EPC) Library | |
| 29 | − | |
| 30 | −The EPC library provides APIs to be used by the controller that can operate | |
| 31 | −in endpoint mode. It also provides APIs to be used by function driver/library | |
| 32 | −in order to implement a particular endpoint function. | |
| 33 | − | |
| 34 | −2.1.1 APIs for the PCI controller Driver | |
| 35 | − | |
| 36 | −This section lists the APIs that the PCI Endpoint core provides to be used | |
| 37 | −by the PCI controller driver. | |
| 38 | − | |
| 39 | −*) devm_pci_epc_create()/pci_epc_create() | |
| 40 | − | |
| 41 | − The PCI controller driver should implement the following ops: | |
| 42 | − * write_header: ops to populate configuration space header | |
| 43 | − * set_bar: ops to configure the BAR | |
| 44 | − * clear_bar: ops to reset the BAR | |
| 45 | − * alloc_addr_space: ops to allocate in PCI controller address space | |
| 46 | − * free_addr_space: ops to free the allocated address space | |
| 47 | − * raise_irq: ops to raise a legacy, MSI or MSI-X interrupt | |
| 48 | − * start: ops to start the PCI link | |
| 49 | − * stop: ops to stop the PCI link | |
| 50 | − | |
| 51 | − The PCI controller driver can then create a new EPC device by invoking | |
| 52 | − devm_pci_epc_create()/pci_epc_create(). | |
| 53 | − | |
| 54 | −*) devm_pci_epc_destroy()/pci_epc_destroy() | |
| 55 | − | |
| 56 | − The PCI controller driver can destroy the EPC device created by either | |
| 57 | − devm_pci_epc_create() or pci_epc_create() using devm_pci_epc_destroy() or | |
| 58 | − pci_epc_destroy(). | |
| 59 | − | |
| 60 | −*) pci_epc_linkup() | |
| 61 | − | |
| 62 | − In order to notify all the function devices that the EPC device to which | |
| 63 | − they are linked has established a link with the host, the PCI controller | |
| 64 | − driver should invoke pci_epc_linkup(). | |
| 65 | − | |
| 66 | −*) pci_epc_mem_init() | |
| 67 | − | |
| 68 | − Initialize the pci_epc_mem structure used for allocating EPC addr space. | |
| 69 | − | |
| 70 | −*) pci_epc_mem_exit() | |
| 71 | − | |
| 72 | − Cleanup the pci_epc_mem structure allocated during pci_epc_mem_init(). | |
| 73 | − | |
| 74 | −2.1.2 APIs for the PCI Endpoint Function Driver | |
| 75 | − | |
| 76 | −This section lists the APIs that the PCI Endpoint core provides to be used | |
| 77 | −by the PCI endpoint function driver. | |
| 78 | − | |
| 79 | −*) pci_epc_write_header() | |
| 80 | − | |
| 81 | − The PCI endpoint function driver should use pci_epc_write_header() to | |
| 82 | − write the standard configuration header to the endpoint controller. | |
| 83 | − | |
| 84 | −*) pci_epc_set_bar() | |
| 85 | − | |
| 86 | − The PCI endpoint function driver should use pci_epc_set_bar() to configure | |
| 87 | − the Base Address Register in order for the host to assign PCI addr space. | |
| 88 | − Register space of the function driver is usually configured | |
| 89 | − using this API. | |
| 90 | − | |
| 91 | −*) pci_epc_clear_bar() | |
| 92 | − | |
| 93 | − The PCI endpoint function driver should use pci_epc_clear_bar() to reset | |
| 94 | − the BAR. | |
| 95 | − | |
| 96 | −*) pci_epc_raise_irq() | |
| 97 | − | |
| 98 | − The PCI endpoint function driver should use pci_epc_raise_irq() to raise | |
| 99 | − Legacy Interrupt, MSI or MSI-X Interrupt. | |
| 100 | − | |
| 101 | −*) pci_epc_mem_alloc_addr() | |
| 102 | − | |
| 103 | − The PCI endpoint function driver should use pci_epc_mem_alloc_addr(), to | |
| 104 | − allocate memory address from EPC addr space which is required to access | |
| 105 | − RC's buffer | |
| 106 | − | |
| 107 | −*) pci_epc_mem_free_addr() | |
| 108 | − | |
| 109 | − The PCI endpoint function driver should use pci_epc_mem_free_addr() to | |
| 110 | − free the memory space allocated using pci_epc_mem_alloc_addr(). | |
| 111 | − | |
| 112 | −2.1.3 Other APIs | |
| 113 | − | |
| 114 | −There are other APIs provided by the EPC library. These are used for binding | |
| 115 | −the EPF device with EPC device. pci-ep-cfs.c can be used as reference for | |
| 116 | −using these APIs. | |
| 117 | − | |
| 118 | −*) pci_epc_get() | |
| 119 | − | |
| 120 | − Get a reference to the PCI endpoint controller based on the device name of | |
| 121 | − the controller. | |
| 122 | − | |
| 123 | −*) pci_epc_put() | |
| 124 | − | |
| 125 | − Release the reference to the PCI endpoint controller obtained using | |
| 126 | − pci_epc_get() | |
| 127 | − | |
| 128 | −*) pci_epc_add_epf() | |
| 129 | − | |
| 130 | − Add a PCI endpoint function to a PCI endpoint controller. A PCIe device | |
| 131 | − can have up to 8 functions according to the specification. | |
| 132 | − | |
| 133 | −*) pci_epc_remove_epf() | |
| 134 | − | |
| 135 | − Remove the PCI endpoint function from PCI endpoint controller. | |
| 136 | − | |
| 137 | −*) pci_epc_start() | |
| 138 | − | |
| 139 | − The PCI endpoint function driver should invoke pci_epc_start() once it | |
| 140 | − has configured the endpoint function and wants to start the PCI link. | |
| 141 | − | |
| 142 | −*) pci_epc_stop() | |
| 143 | − | |
| 144 | − The PCI endpoint function driver should invoke pci_epc_stop() to stop | |
| 145 | − the PCI LINK. | |
| 146 | − | |
| 147 | −2.2 PCI Endpoint Function(EPF) Library | |
| 148 | − | |
| 149 | −The EPF library provides APIs to be used by the function driver and the EPC | |
| 150 | −library to provide endpoint mode functionality. | |
| 151 | − | |
| 152 | −2.2.1 APIs for the PCI Endpoint Function Driver | |
| 153 | − | |
| 154 | −This section lists the APIs that the PCI Endpoint core provides to be used | |
| 155 | −by the PCI endpoint function driver. | |
| 156 | − | |
| 157 | −*) pci_epf_register_driver() | |
| 158 | − | |
| 159 | − The PCI Endpoint Function driver should implement the following ops: | |
| 160 | − * bind: ops to perform when a EPC device has been bound to EPF device | |
| 161 | − * unbind: ops to perform when a binding has been lost between a EPC | |
| 162 | − device and EPF device | |
| 163 | − * linkup: ops to perform when the EPC device has established a | |
| 164 | − connection with a host system | |
| 165 | − | |
| 166 | − The PCI Function driver can then register the PCI EPF driver by using | |
| 167 | − pci_epf_register_driver(). | |
| 168 | − | |
| 169 | −*) pci_epf_unregister_driver() | |
| 170 | − | |
| 171 | − The PCI Function driver can unregister the PCI EPF driver by using | |
| 172 | − pci_epf_unregister_driver(). | |
| 173 | − | |
| 174 | −*) pci_epf_alloc_space() | |
| 175 | − | |
| 176 | − The PCI Function driver can allocate space for a particular BAR using | |
| 177 | − pci_epf_alloc_space(). | |
| 178 | − | |
| 179 | −*) pci_epf_free_space() | |
| 180 | − | |
| 181 | − The PCI Function driver can free the allocated space | |
| 182 | − (using pci_epf_alloc_space) by invoking pci_epf_free_space(). | |
| 183 | − | |
| 184 | −2.2.2 APIs for the PCI Endpoint Controller Library | |
| 185 | −This section lists the APIs that the PCI Endpoint core provides to be used | |
| 186 | −by the PCI endpoint controller library. | |
| 187 | − | |
| 188 | −*) pci_epf_linkup() | |
| 189 | − | |
| 190 | − The PCI endpoint controller library invokes pci_epf_linkup() when the | |
| 191 | − EPC device has established the connection to the host. | |
| 192 | − | |
| 193 | −2.2.2 Other APIs | |
| 194 | −There are other APIs provided by the EPF library. These are used to notify | |
| 195 | −the function driver when the EPF device is bound to the EPC device. | |
| 196 | −pci-ep-cfs.c can be used as reference for using these APIs. | |
| 197 | − | |
| 198 | −*) pci_epf_create() | |
| 199 | − | |
| 200 | − Create a new PCI EPF device by passing the name of the PCI EPF device. | |
| 201 | − This name will be used to bind the the EPF device to a EPF driver. | |
| 202 | − | |
| 203 | −*) pci_epf_destroy() | |
| 204 | − | |
| 205 | − Destroy the created PCI EPF device. | |
| 206 | − | |
| 207 | −*) pci_epf_bind() | |
| 208 | − | |
| 209 | − pci_epf_bind() should be invoked when the EPF device has been bound to | |
| 210 | − a EPC device. | |
| 211 | − | |
| 212 | −*) pci_epf_unbind() | |
| 213 | − | |
| 214 | − pci_epf_unbind() should be invoked when the binding between EPC device | |
| 215 | − and EPF device is lost. | |
| @@ -0,0 +1,103 @@ | ||
| 1 | +.. SPDX-License-Identifier: GPL-2.0 | |
| 2 | + | |
| 3 | +================= | |
| 4 | +PCI Test Function | |
| 5 | +================= | |
| 6 | + | |
| 7 | +:Author: Kishon Vijay Abraham I <kishon@ti.com> | |
| 8 | + | |
| 9 | +Traditionally PCI RC has always been validated by using standard | |
| 10 | +PCI cards like ethernet PCI cards or USB PCI cards or SATA PCI cards. | |
| 11 | +However with the addition of EP-core in linux kernel, it is possible | |
| 12 | +to configure a PCI controller that can operate in EP mode to work as | |
| 13 | +a test device. | |
| 14 | + | |
| 15 | +The PCI endpoint test device is a virtual device (defined in software) | |
| 16 | +used to test the endpoint functionality and serve as a sample driver | |
| 17 | +for other PCI endpoint devices (to use the EP framework). | |
| 18 | + | |
| 19 | +The PCI endpoint test device has the following registers: | |
| 20 | + | |
| 21 | + 1) PCI_ENDPOINT_TEST_MAGIC | |
| 22 | + 2) PCI_ENDPOINT_TEST_COMMAND | |
| 23 | + 3) PCI_ENDPOINT_TEST_STATUS | |
| 24 | + 4) PCI_ENDPOINT_TEST_SRC_ADDR | |
| 25 | + 5) PCI_ENDPOINT_TEST_DST_ADDR | |
| 26 | + 6) PCI_ENDPOINT_TEST_SIZE | |
| 27 | + 7) PCI_ENDPOINT_TEST_CHECKSUM | |
| 28 | + 8) PCI_ENDPOINT_TEST_IRQ_TYPE | |
| 29 | + 9) PCI_ENDPOINT_TEST_IRQ_NUMBER | |
| 30 | + | |
| 31 | +* PCI_ENDPOINT_TEST_MAGIC | |
| 32 | + | |
| 33 | +This register will be used to test BAR0. A known pattern will be written | |
| 34 | +and read back from MAGIC register to verify BAR0. | |
| 35 | + | |
| 36 | +* PCI_ENDPOINT_TEST_COMMAND | |
| 37 | + | |
| 38 | +This register will be used by the host driver to indicate the function | |
| 39 | +that the endpoint device must perform. | |
| 40 | + | |
| 41 | +======== ================================================================ | |
| 42 | +Bitfield Description | |
| 43 | +======== ================================================================ | |
| 44 | +Bit 0 raise legacy IRQ | |
| 45 | +Bit 1 raise MSI IRQ | |
| 46 | +Bit 2 raise MSI-X IRQ | |
| 47 | +Bit 3 read command (read data from RC buffer) | |
| 48 | +Bit 4 write command (write data to RC buffer) | |
| 49 | +Bit 5 copy command (copy data from one RC buffer to another RC buffer) | |
| 50 | +======== ================================================================ | |
| 51 | + | |
| 52 | +* PCI_ENDPOINT_TEST_STATUS | |
| 53 | + | |
| 54 | +This register reflects the status of the PCI endpoint device. | |
| 55 | + | |
| 56 | +======== ============================== | |
| 57 | +Bitfield Description | |
| 58 | +======== ============================== | |
| 59 | +Bit 0 read success | |
| 60 | +Bit 1 read fail | |
| 61 | +Bit 2 write success | |
| 62 | +Bit 3 write fail | |
| 63 | +Bit 4 copy success | |
| 64 | +Bit 5 copy fail | |
| 65 | +Bit 6 IRQ raised | |
| 66 | +Bit 7 source address is invalid | |
| 67 | +Bit 8 destination address is invalid | |
| 68 | +======== ============================== | |
| 69 | + | |
| 70 | +* PCI_ENDPOINT_TEST_SRC_ADDR | |
| 71 | + | |
| 72 | +This register contains the source address (RC buffer address) for the | |
| 73 | +COPY/READ command. | |
| 74 | + | |
| 75 | +* PCI_ENDPOINT_TEST_DST_ADDR | |
| 76 | + | |
| 77 | +This register contains the destination address (RC buffer address) for | |
| 78 | +the COPY/WRITE command. | |
| 79 | + | |
| 80 | +* PCI_ENDPOINT_TEST_IRQ_TYPE | |
| 81 | + | |
| 82 | +This register contains the interrupt type (Legacy/MSI) triggered | |
| 83 | +for the READ/WRITE/COPY and raise IRQ (Legacy/MSI) commands. | |
| 84 | + | |
| 85 | +Possible types: | |
| 86 | + | |
| 87 | +====== == | |
| 88 | +Legacy 0 | |
| 89 | +MSI 1 | |
| 90 | +MSI-X 2 | |
| 91 | +====== == | |
| 92 | + | |
| 93 | +* PCI_ENDPOINT_TEST_IRQ_NUMBER | |
| 94 | + | |
| 95 | +This register contains the triggered ID interrupt. | |
| 96 | + | |
| 97 | +Admissible values: | |
| 98 | + | |
| 99 | +====== =========== | |
| 100 | +Legacy 0 | |
| 101 | +MSI [1 .. 32] | |
| 102 | +MSI-X [1 .. 2048] | |
| 103 | +====== =========== | |
| @@ -1,87 +0,0 @@ | ||
| 1 | − PCI TEST | |
| 2 | − Kishon Vijay Abraham I <kishon@ti.com> | |
| 3 | − | |
| 4 | −Traditionally PCI RC has always been validated by using standard | |
| 5 | −PCI cards like ethernet PCI cards or USB PCI cards or SATA PCI cards. | |
| 6 | −However with the addition of EP-core in linux kernel, it is possible | |
| 7 | −to configure a PCI controller that can operate in EP mode to work as | |
| 8 | −a test device. | |
| 9 | − | |
| 10 | −The PCI endpoint test device is a virtual device (defined in software) | |
| 11 | −used to test the endpoint functionality and serve as a sample driver | |
| 12 | −for other PCI endpoint devices (to use the EP framework). | |
| 13 | − | |
| 14 | −The PCI endpoint test device has the following registers: | |
| 15 | − | |
| 16 | − 1) PCI_ENDPOINT_TEST_MAGIC | |
| 17 | − 2) PCI_ENDPOINT_TEST_COMMAND | |
| 18 | − 3) PCI_ENDPOINT_TEST_STATUS | |
| 19 | − 4) PCI_ENDPOINT_TEST_SRC_ADDR | |
| 20 | − 5) PCI_ENDPOINT_TEST_DST_ADDR | |
| 21 | − 6) PCI_ENDPOINT_TEST_SIZE | |
| 22 | − 7) PCI_ENDPOINT_TEST_CHECKSUM | |
| 23 | − 8) PCI_ENDPOINT_TEST_IRQ_TYPE | |
| 24 | − 9) PCI_ENDPOINT_TEST_IRQ_NUMBER | |
| 25 | − | |
| 26 | −*) PCI_ENDPOINT_TEST_MAGIC | |
| 27 | − | |
| 28 | −This register will be used to test BAR0. A known pattern will be written | |
| 29 | −and read back from MAGIC register to verify BAR0. | |
| 30 | − | |
| 31 | −*) PCI_ENDPOINT_TEST_COMMAND: | |
| 32 | − | |
| 33 | −This register will be used by the host driver to indicate the function | |
| 34 | −that the endpoint device must perform. | |
| 35 | − | |
| 36 | −Bitfield Description: | |
| 37 | − Bit 0 : raise legacy IRQ | |
| 38 | − Bit 1 : raise MSI IRQ | |
| 39 | − Bit 2 : raise MSI-X IRQ | |
| 40 | − Bit 3 : read command (read data from RC buffer) | |
| 41 | − Bit 4 : write command (write data to RC buffer) | |
| 42 | − Bit 5 : copy command (copy data from one RC buffer to another | |
| 43 | − RC buffer) | |
| 44 | − | |
| 45 | −*) PCI_ENDPOINT_TEST_STATUS | |
| 46 | − | |
| 47 | −This register reflects the status of the PCI endpoint device. | |
| 48 | − | |
| 49 | −Bitfield Description: | |
| 50 | − Bit 0 : read success | |
| 51 | − Bit 1 : read fail | |
| 52 | − Bit 2 : write success | |
| 53 | − Bit 3 : write fail | |
| 54 | − Bit 4 : copy success | |
| 55 | − Bit 5 : copy fail | |
| 56 | − Bit 6 : IRQ raised | |
| 57 | − Bit 7 : source address is invalid | |
| 58 | − Bit 8 : destination address is invalid | |
| 59 | − | |
| 60 | −*) PCI_ENDPOINT_TEST_SRC_ADDR | |
| 61 | − | |
| 62 | −This register contains the source address (RC buffer address) for the | |
| 63 | −COPY/READ command. | |
| 64 | − | |
| 65 | −*) PCI_ENDPOINT_TEST_DST_ADDR | |
| 66 | − | |
| 67 | −This register contains the destination address (RC buffer address) for | |
| 68 | −the COPY/WRITE command. | |
| 69 | − | |
| 70 | −*) PCI_ENDPOINT_TEST_IRQ_TYPE | |
| 71 | − | |
| 72 | −This register contains the interrupt type (Legacy/MSI) triggered | |
| 73 | −for the READ/WRITE/COPY and raise IRQ (Legacy/MSI) commands. | |
| 74 | − | |
| 75 | −Possible types: | |
| 76 | − - Legacy : 0 | |
| 77 | − - MSI : 1 | |
| 78 | − - MSI-X : 2 | |
| 79 | − | |
| 80 | −*) PCI_ENDPOINT_TEST_IRQ_NUMBER | |
| 81 | − | |
| 82 | −This register contains the triggered ID interrupt. | |
| 83 | − | |
| 84 | −Admissible values: | |
| 85 | − - Legacy : 0 | |
| 86 | − - MSI : [1 .. 32] | |
| 87 | − - MSI-X : [1 .. 2048] | |
| @@ -0,0 +1,235 @@ | ||
| 1 | +.. SPDX-License-Identifier: GPL-2.0 | |
| 2 | + | |
| 3 | +=================== | |
| 4 | +PCI Test User Guide | |
| 5 | +=================== | |
| 6 | + | |
| 7 | +:Author: Kishon Vijay Abraham I <kishon@ti.com> | |
| 8 | + | |
| 9 | +This document is a guide to help users use pci-epf-test function driver | |
| 10 | +and pci_endpoint_test host driver for testing PCI. The list of steps to | |
| 11 | +be followed in the host side and EP side is given below. | |
| 12 | + | |
| 13 | +Endpoint Device | |
| 14 | +=============== | |
| 15 | + | |
| 16 | +Endpoint Controller Devices | |
| 17 | +--------------------------- | |
| 18 | + | |
| 19 | +To find the list of endpoint controller devices in the system:: | |
| 20 | + | |
| 21 | + # ls /sys/class/pci_epc/ | |
| 22 | + 51000000.pcie_ep | |
| 23 | + | |
| 24 | +If PCI_ENDPOINT_CONFIGFS is enabled:: | |
| 25 | + | |
| 26 | + # ls /sys/kernel/config/pci_ep/controllers | |
| 27 | + 51000000.pcie_ep | |
| 28 | + | |
| 29 | + | |
| 30 | +Endpoint Function Drivers | |
| 31 | +------------------------- | |
| 32 | + | |
| 33 | +To find the list of endpoint function drivers in the system:: | |
| 34 | + | |
| 35 | + # ls /sys/bus/pci-epf/drivers | |
| 36 | + pci_epf_test | |
| 37 | + | |
| 38 | +If PCI_ENDPOINT_CONFIGFS is enabled:: | |
| 39 | + | |
| 40 | + # ls /sys/kernel/config/pci_ep/functions | |
| 41 | + pci_epf_test | |
| 42 | + | |
| 43 | + | |
| 44 | +Creating pci-epf-test Device | |
| 45 | +---------------------------- | |
| 46 | + | |
| 47 | +PCI endpoint function device can be created using the configfs. To create | |
| 48 | +pci-epf-test device, the following commands can be used:: | |
| 49 | + | |
| 50 | + # mount -t configfs none /sys/kernel/config | |
| 51 | + # cd /sys/kernel/config/pci_ep/ | |
| 52 | + # mkdir functions/pci_epf_test/func1 | |
| 53 | + | |
| 54 | +The "mkdir func1" above creates the pci-epf-test function device that will | |
| 55 | +be probed by pci_epf_test driver. | |
| 56 | + | |
| 57 | +The PCI endpoint framework populates the directory with the following | |
| 58 | +configurable fields:: | |
| 59 | + | |
| 60 | + # ls functions/pci_epf_test/func1 | |
| 61 | + baseclass_code interrupt_pin progif_code subsys_id | |
| 62 | + cache_line_size msi_interrupts revid subsys_vendorid | |
| 63 | + deviceid msix_interrupts subclass_code vendorid | |
| 64 | + | |
| 65 | +The PCI endpoint function driver populates these entries with default values | |
| 66 | +when the device is bound to the driver. The pci-epf-test driver populates | |
| 67 | +vendorid with 0xffff and interrupt_pin with 0x0001:: | |
| 68 | + | |
| 69 | + # cat functions/pci_epf_test/func1/vendorid | |
| 70 | + 0xffff | |
| 71 | + # cat functions/pci_epf_test/func1/interrupt_pin | |
| 72 | + 0x0001 | |
| 73 | + | |
| 74 | + | |
| 75 | +Configuring pci-epf-test Device | |
| 76 | +------------------------------- | |
| 77 | + | |
| 78 | +The user can configure the pci-epf-test device using configfs entry. In order | |
| 79 | +to change the vendorid and the number of MSI interrupts used by the function | |
| 80 | +device, the following commands can be used:: | |
| 81 | + | |
| 82 | + # echo 0x104c > functions/pci_epf_test/func1/vendorid | |
| 83 | + # echo 0xb500 > functions/pci_epf_test/func1/deviceid | |
| 84 | + # echo 16 > functions/pci_epf_test/func1/msi_interrupts | |
| 85 | + # echo 8 > functions/pci_epf_test/func1/msix_interrupts | |
| 86 | + | |
| 87 | + | |
| 88 | +Binding pci-epf-test Device to EP Controller | |
| 89 | +-------------------------------------------- | |
| 90 | + | |
| 91 | +In order for the endpoint function device to be useful, it has to be bound to | |
| 92 | +a PCI endpoint controller driver. Use the configfs to bind the function | |
| 93 | +device to one of the controller driver present in the system:: | |
| 94 | + | |
| 95 | + # ln -s functions/pci_epf_test/func1 controllers/51000000.pcie_ep/ | |
| 96 | + | |
| 97 | +Once the above step is completed, the PCI endpoint is ready to establish a link | |
| 98 | +with the host. | |
| 99 | + | |
| 100 | + | |
| 101 | +Start the Link | |
| 102 | +-------------- | |
| 103 | + | |
| 104 | +In order for the endpoint device to establish a link with the host, the _start_ | |
| 105 | +field should be populated with '1':: | |
| 106 | + | |
| 107 | + # echo 1 > controllers/51000000.pcie_ep/start | |
| 108 | + | |
| 109 | + | |
| 110 | +RootComplex Device | |
| 111 | +================== | |
| 112 | + | |
| 113 | +lspci Output | |
| 114 | +------------ | |
| 115 | + | |
| 116 | +Note that the devices listed here correspond to the value populated in 1.4 | |
| 117 | +above:: | |
| 118 | + | |
| 119 | + 00:00.0 PCI bridge: Texas Instruments Device 8888 (rev 01) | |
| 120 | + 01:00.0 Unassigned class [ff00]: Texas Instruments Device b500 | |
| 121 | + | |
| 122 | + | |
| 123 | +Using Endpoint Test function Device | |
| 124 | +----------------------------------- | |
| 125 | + | |
| 126 | +pcitest.sh added in tools/pci/ can be used to run all the default PCI endpoint | |
| 127 | +tests. To compile this tool the following commands should be used:: | |
| 128 | + | |
| 129 | + # cd <kernel-dir> | |
| 130 | + # make -C tools/pci | |
| 131 | + | |
| 132 | +or if you desire to compile and install in your system:: | |
| 133 | + | |
| 134 | + # cd <kernel-dir> | |
| 135 | + # make -C tools/pci install | |
| 136 | + | |
| 137 | +The tool and script will be located in <rootfs>/usr/bin/ | |
| 138 | + | |
| 139 | + | |
| 140 | +pcitest.sh Output | |
| 141 | +~~~~~~~~~~~~~~~~~ | |
| 142 | +:: | |
| 143 | + | |
| 144 | + # pcitest.sh | |
| 145 | + BAR tests | |
| 146 | + | |
| 147 | + BAR0: OKAY | |
| 148 | + BAR1: OKAY | |
| 149 | + BAR2: OKAY | |
| 150 | + BAR3: OKAY | |
| 151 | + BAR4: NOT OKAY | |
| 152 | + BAR5: NOT OKAY | |
| 153 | + | |
| 154 | + Interrupt tests | |
| 155 | + | |
| 156 | + SET IRQ TYPE TO LEGACY: OKAY | |
| 157 | + LEGACY IRQ: NOT OKAY | |
| 158 | + SET IRQ TYPE TO MSI: OKAY | |
| 159 | + MSI1: OKAY | |
| 160 | + MSI2: OKAY | |
| 161 | + MSI3: OKAY | |
| 162 | + MSI4: OKAY | |
| 163 | + MSI5: OKAY | |
| 164 | + MSI6: OKAY | |
| 165 | + MSI7: OKAY | |
| 166 | + MSI8: OKAY | |
| 167 | + MSI9: OKAY | |
| 168 | + MSI10: OKAY | |
| 169 | + MSI11: OKAY | |
| 170 | + MSI12: OKAY | |
| 171 | + MSI13: OKAY | |
| 172 | + MSI14: OKAY | |
| 173 | + MSI15: OKAY | |
| 174 | + MSI16: OKAY | |
| 175 | + MSI17: NOT OKAY | |
| 176 | + MSI18: NOT OKAY | |
| 177 | + MSI19: NOT OKAY | |
| 178 | + MSI20: NOT OKAY | |
| 179 | + MSI21: NOT OKAY | |
| 180 | + MSI22: NOT OKAY | |
| 181 | + MSI23: NOT OKAY | |
| 182 | + MSI24: NOT OKAY | |
| 183 | + MSI25: NOT OKAY | |
| 184 | + MSI26: NOT OKAY | |
| 185 | + MSI27: NOT OKAY | |
| 186 | + MSI28: NOT OKAY | |
| 187 | + MSI29: NOT OKAY | |
| 188 | + MSI30: NOT OKAY | |
| 189 | + MSI31: NOT OKAY | |
| 190 | + MSI32: NOT OKAY | |
| 191 | + SET IRQ TYPE TO MSI-X: OKAY | |
| 192 | + MSI-X1: OKAY | |
| 193 | + MSI-X2: OKAY | |
| 194 | + MSI-X3: OKAY | |
| 195 | + MSI-X4: OKAY | |
| 196 | + MSI-X5: OKAY | |
| 197 | + MSI-X6: OKAY | |
| 198 | + MSI-X7: OKAY | |
| 199 | + MSI-X8: OKAY | |
| 200 | + MSI-X9: NOT OKAY | |
| 201 | + MSI-X10: NOT OKAY | |
| 202 | + MSI-X11: NOT OKAY | |
| 203 | + MSI-X12: NOT OKAY | |
| 204 | + MSI-X13: NOT OKAY | |
| 205 | + MSI-X14: NOT OKAY | |
| 206 | + MSI-X15: NOT OKAY | |
| 207 | + MSI-X16: NOT OKAY | |
| 208 | + [...] | |
| 209 | + MSI-X2047: NOT OKAY | |
| 210 | + MSI-X2048: NOT OKAY | |
| 211 | + | |
| 212 | + Read Tests | |
| 213 | + | |
| 214 | + SET IRQ TYPE TO MSI: OKAY | |
| 215 | + READ ( 1 bytes): OKAY | |
| 216 | + READ ( 1024 bytes): OKAY | |
| 217 | + READ ( 1025 bytes): OKAY | |
| 218 | + READ (1024000 bytes): OKAY | |
| 219 | + READ (1024001 bytes): OKAY | |
| 220 | + | |
| 221 | + Write Tests | |
| 222 | + | |
| 223 | + WRITE ( 1 bytes): OKAY | |
| 224 | + WRITE ( 1024 bytes): OKAY | |
| 225 | + WRITE ( 1025 bytes): OKAY | |
| 226 | + WRITE (1024000 bytes): OKAY | |
| 227 | + WRITE (1024001 bytes): OKAY | |
| 228 | + | |
| 229 | + Copy Tests | |
| 230 | + | |
| 231 | + COPY ( 1 bytes): OKAY | |
| 232 | + COPY ( 1024 bytes): OKAY | |
| 233 | + COPY ( 1025 bytes): OKAY | |
| 234 | + COPY (1024000 bytes): OKAY | |
| 235 | + COPY (1024001 bytes): OKAY | |
| @@ -1,206 +0,0 @@ | ||
| 1 | − PCI TEST USERGUIDE | |
| 2 | − Kishon Vijay Abraham I <kishon@ti.com> | |
| 3 | − | |
| 4 | −This document is a guide to help users use pci-epf-test function driver | |
| 5 | −and pci_endpoint_test host driver for testing PCI. The list of steps to | |
| 6 | −be followed in the host side and EP side is given below. | |
| 7 | − | |
| 8 | −1. Endpoint Device | |
| 9 | − | |
| 10 | −1.1 Endpoint Controller Devices | |
| 11 | − | |
| 12 | −To find the list of endpoint controller devices in the system: | |
| 13 | − | |
| 14 | − # ls /sys/class/pci_epc/ | |
| 15 | − 51000000.pcie_ep | |
| 16 | − | |
| 17 | −If PCI_ENDPOINT_CONFIGFS is enabled | |
| 18 | − # ls /sys/kernel/config/pci_ep/controllers | |
| 19 | − 51000000.pcie_ep | |
| 20 | − | |
| 21 | −1.2 Endpoint Function Drivers | |
| 22 | − | |
| 23 | −To find the list of endpoint function drivers in the system: | |
| 24 | − | |
| 25 | − # ls /sys/bus/pci-epf/drivers | |
| 26 | − pci_epf_test | |
| 27 | − | |
| 28 | −If PCI_ENDPOINT_CONFIGFS is enabled | |
| 29 | − # ls /sys/kernel/config/pci_ep/functions | |
| 30 | − pci_epf_test | |
| 31 | − | |
| 32 | −1.3 Creating pci-epf-test Device | |
| 33 | − | |
| 34 | −PCI endpoint function device can be created using the configfs. To create | |
| 35 | −pci-epf-test device, the following commands can be used | |
| 36 | − | |
| 37 | − # mount -t configfs none /sys/kernel/config | |
| 38 | − # cd /sys/kernel/config/pci_ep/ | |
| 39 | − # mkdir functions/pci_epf_test/func1 | |
| 40 | − | |
| 41 | −The "mkdir func1" above creates the pci-epf-test function device that will | |
| 42 | −be probed by pci_epf_test driver. | |
| 43 | − | |
| 44 | −The PCI endpoint framework populates the directory with the following | |
| 45 | −configurable fields. | |
| 46 | − | |
| 47 | − # ls functions/pci_epf_test/func1 | |
| 48 | − baseclass_code interrupt_pin progif_code subsys_id | |
| 49 | − cache_line_size msi_interrupts revid subsys_vendorid | |
| 50 | − deviceid msix_interrupts subclass_code vendorid | |
| 51 | − | |
| 52 | −The PCI endpoint function driver populates these entries with default values | |
| 53 | −when the device is bound to the driver. The pci-epf-test driver populates | |
| 54 | −vendorid with 0xffff and interrupt_pin with 0x0001 | |
| 55 | − | |
| 56 | − # cat functions/pci_epf_test/func1/vendorid | |
| 57 | − 0xffff | |
| 58 | − # cat functions/pci_epf_test/func1/interrupt_pin | |
| 59 | − 0x0001 | |
| 60 | − | |
| 61 | −1.4 Configuring pci-epf-test Device | |
| 62 | − | |
| 63 | −The user can configure the pci-epf-test device using configfs entry. In order | |
| 64 | −to change the vendorid and the number of MSI interrupts used by the function | |
| 65 | −device, the following commands can be used. | |
| 66 | − | |
| 67 | − # echo 0x104c > functions/pci_epf_test/func1/vendorid | |
| 68 | − # echo 0xb500 > functions/pci_epf_test/func1/deviceid | |
| 69 | − # echo 16 > functions/pci_epf_test/func1/msi_interrupts | |
| 70 | − # echo 8 > functions/pci_epf_test/func1/msix_interrupts | |
| 71 | − | |
| 72 | −1.5 Binding pci-epf-test Device to EP Controller | |
| 73 | − | |
| 74 | −In order for the endpoint function device to be useful, it has to be bound to | |
| 75 | −a PCI endpoint controller driver. Use the configfs to bind the function | |
| 76 | −device to one of the controller driver present in the system. | |
| 77 | − | |
| 78 | − # ln -s functions/pci_epf_test/func1 controllers/51000000.pcie_ep/ | |
| 79 | − | |
| 80 | −Once the above step is completed, the PCI endpoint is ready to establish a link | |
| 81 | −with the host. | |
| 82 | − | |
| 83 | −1.6 Start the Link | |
| 84 | − | |
| 85 | −In order for the endpoint device to establish a link with the host, the _start_ | |
| 86 | −field should be populated with '1'. | |
| 87 | − | |
| 88 | − # echo 1 > controllers/51000000.pcie_ep/start | |
| 89 | − | |
| 90 | −2. RootComplex Device | |
| 91 | − | |
| 92 | −2.1 lspci Output | |
| 93 | − | |
| 94 | −Note that the devices listed here correspond to the value populated in 1.4 above | |
| 95 | − | |
| 96 | − 00:00.0 PCI bridge: Texas Instruments Device 8888 (rev 01) | |
| 97 | − 01:00.0 Unassigned class [ff00]: Texas Instruments Device b500 | |
| 98 | − | |
| 99 | −2.2 Using Endpoint Test function Device | |
| 100 | − | |
| 101 | −pcitest.sh added in tools/pci/ can be used to run all the default PCI endpoint | |
| 102 | −tests. To compile this tool the following commands should be used: | |
| 103 | − | |
| 104 | − # cd <kernel-dir> | |
| 105 | − # make -C tools/pci | |
| 106 | − | |
| 107 | −or if you desire to compile and install in your system: | |
| 108 | − | |
| 109 | − # cd <kernel-dir> | |
| 110 | − # make -C tools/pci install | |
| 111 | − | |
| 112 | −The tool and script will be located in <rootfs>/usr/bin/ | |
| 113 | − | |
| 114 | −2.2.1 pcitest.sh Output | |
| 115 | − # pcitest.sh | |
| 116 | − BAR tests | |
| 117 | − | |
| 118 | − BAR0: OKAY | |
| 119 | − BAR1: OKAY | |
| 120 | − BAR2: OKAY | |
| 121 | − BAR3: OKAY | |
| 122 | − BAR4: NOT OKAY | |
| 123 | − BAR5: NOT OKAY | |
| 124 | − | |
| 125 | − Interrupt tests | |
| 126 | − | |
| 127 | − SET IRQ TYPE TO LEGACY: OKAY | |
| 128 | − LEGACY IRQ: NOT OKAY | |
| 129 | − SET IRQ TYPE TO MSI: OKAY | |
| 130 | − MSI1: OKAY | |
| 131 | − MSI2: OKAY | |
| 132 | − MSI3: OKAY | |
| 133 | − MSI4: OKAY | |
| 134 | − MSI5: OKAY | |
| 135 | − MSI6: OKAY | |
| 136 | − MSI7: OKAY | |
| 137 | − MSI8: OKAY | |
| 138 | − MSI9: OKAY | |
| 139 | − MSI10: OKAY | |
| 140 | − MSI11: OKAY | |
| 141 | − MSI12: OKAY | |
| 142 | − MSI13: OKAY | |
| 143 | − MSI14: OKAY | |
| 144 | − MSI15: OKAY | |
| 145 | − MSI16: OKAY | |
| 146 | − MSI17: NOT OKAY | |
| 147 | − MSI18: NOT OKAY | |
| 148 | − MSI19: NOT OKAY | |
| 149 | − MSI20: NOT OKAY | |
| 150 | − MSI21: NOT OKAY | |
| 151 | − MSI22: NOT OKAY | |
| 152 | − MSI23: NOT OKAY | |
| 153 | − MSI24: NOT OKAY | |
| 154 | − MSI25: NOT OKAY | |
| 155 | − MSI26: NOT OKAY | |
| 156 | − MSI27: NOT OKAY | |
| 157 | − MSI28: NOT OKAY | |
| 158 | − MSI29: NOT OKAY | |
| 159 | − MSI30: NOT OKAY | |
| 160 | − MSI31: NOT OKAY | |
| 161 | − MSI32: NOT OKAY | |
| 162 | − SET IRQ TYPE TO MSI-X: OKAY | |
| 163 | − MSI-X1: OKAY | |
| 164 | − MSI-X2: OKAY | |
| 165 | − MSI-X3: OKAY | |
| 166 | − MSI-X4: OKAY | |
| 167 | − MSI-X5: OKAY | |
| 168 | − MSI-X6: OKAY | |
| 169 | − MSI-X7: OKAY | |
| 170 | − MSI-X8: OKAY | |
| 171 | − MSI-X9: NOT OKAY | |
| 172 | − MSI-X10: NOT OKAY | |
| 173 | − MSI-X11: NOT OKAY | |
| 174 | − MSI-X12: NOT OKAY | |
| 175 | − MSI-X13: NOT OKAY | |
| 176 | − MSI-X14: NOT OKAY | |
| 177 | − MSI-X15: NOT OKAY | |
| 178 | − MSI-X16: NOT OKAY | |
| 179 | − [...] | |
| 180 | − MSI-X2047: NOT OKAY | |
| 181 | − MSI-X2048: NOT OKAY | |
| 182 | − | |
| 183 | − Read Tests | |
| 184 | − | |
| 185 | − SET IRQ TYPE TO MSI: OKAY | |
| 186 | − READ ( 1 bytes): OKAY | |
| 187 | − READ ( 1024 bytes): OKAY | |
| 188 | − READ ( 1025 bytes): OKAY | |
| 189 | − READ (1024000 bytes): OKAY | |
| 190 | − READ (1024001 bytes): OKAY | |
| 191 | − | |
| 192 | − Write Tests | |
| 193 | − | |
| 194 | − WRITE ( 1 bytes): OKAY | |
| 195 | − WRITE ( 1024 bytes): OKAY | |
| 196 | − WRITE ( 1025 bytes): OKAY | |
| 197 | − WRITE (1024000 bytes): OKAY | |
| 198 | − WRITE (1024001 bytes): OKAY | |
| 199 | − | |
| 200 | − Copy Tests | |
| 201 | − | |
| 202 | − COPY ( 1 bytes): OKAY | |
| 203 | − COPY ( 1024 bytes): OKAY | |
| 204 | − COPY ( 1025 bytes): OKAY | |
| 205 | − COPY (1024000 bytes): OKAY | |
| 206 | − COPY (1024001 bytes): OKAY | |
| @@ -0,0 +1,18 @@ | ||
| 1 | +.. SPDX-License-Identifier: GPL-2.0 | |
| 2 | + | |
| 3 | +======================= | |
| 4 | +Linux PCI Bus Subsystem | |
| 5 | +======================= | |
| 6 | + | |
| 7 | +.. toctree:: | |
| 8 | + :maxdepth: 2 | |
| 9 | + :numbered: | |
| 10 | + | |
| 11 | + pci | |
| 12 | + picebus-howto | |
| 13 | + pci-iov-howto | |
| 14 | + msi-howto | |
| 15 | + acpi-info | |
| 16 | + pci-error-recovery | |
| 17 | + pcieaer-howto | |
| 18 | + endpoint/index | |
| @@ -0,0 +1,287 @@ | ||
| 1 | +.. SPDX-License-Identifier: GPL-2.0 | |
| 2 | +.. include:: <isonum.txt> | |
| 3 | + | |
| 4 | +========================== | |
| 5 | +The MSI Driver Guide HOWTO | |
| 6 | +========================== | |
| 7 | + | |
| 8 | +:Authors: Tom L Nguyen; Martine Silbermann; Matthew Wilcox | |
| 9 | + | |
| 10 | +:Copyright: 2003, 2008 Intel Corporation | |
| 11 | + | |
| 12 | +About this guide | |
| 13 | +================ | |
| 14 | + | |
| 15 | +This guide describes the basics of Message Signaled Interrupts (MSIs), | |
| 16 | +the advantages of using MSI over traditional interrupt mechanisms, how | |
| 17 | +to change your driver to use MSI or MSI-X and some basic diagnostics to | |
| 18 | +try if a device doesn't support MSIs. | |
| 19 | + | |
| 20 | + | |
| 21 | +What are MSIs? | |
| 22 | +============== | |
| 23 | + | |
| 24 | +A Message Signaled Interrupt is a write from the device to a special | |
| 25 | +address which causes an interrupt to be received by the CPU. | |
| 26 | + | |
| 27 | +The MSI capability was first specified in PCI 2.2 and was later enhanced | |
| 28 | +in PCI 3.0 to allow each interrupt to be masked individually. The MSI-X | |
| 29 | +capability was also introduced with PCI 3.0. It supports more interrupts | |
| 30 | +per device than MSI and allows interrupts to be independently configured. | |
| 31 | + | |
| 32 | +Devices may support both MSI and MSI-X, but only one can be enabled at | |
| 33 | +a time. | |
| 34 | + | |
| 35 | + | |
| 36 | +Why use MSIs? | |
| 37 | +============= | |
| 38 | + | |
| 39 | +There are three reasons why using MSIs can give an advantage over | |
| 40 | +traditional pin-based interrupts. | |
| 41 | + | |
| 42 | +Pin-based PCI interrupts are often shared amongst several devices. | |
| 43 | +To support this, the kernel must call each interrupt handler associated | |
| 44 | +with an interrupt, which leads to reduced performance for the system as | |
| 45 | +a whole. MSIs are never shared, so this problem cannot arise. | |
| 46 | + | |
| 47 | +When a device writes data to memory, then raises a pin-based interrupt, | |
| 48 | +it is possible that the interrupt may arrive before all the data has | |
| 49 | +arrived in memory (this becomes more likely with devices behind PCI-PCI | |
| 50 | +bridges). In order to ensure that all the data has arrived in memory, | |
| 51 | +the interrupt handler must read a register on the device which raised | |
| 52 | +the interrupt. PCI transaction ordering rules require that all the data | |
| 53 | +arrive in memory before the value may be returned from the register. | |
| 54 | +Using MSIs avoids this problem as the interrupt-generating write cannot | |
| 55 | +pass the data writes, so by the time the interrupt is raised, the driver | |
| 56 | +knows that all the data has arrived in memory. | |
| 57 | + | |
| 58 | +PCI devices can only support a single pin-based interrupt per function. | |
| 59 | +Often drivers have to query the device to find out what event has | |
| 60 | +occurred, slowing down interrupt handling for the common case. With | |
| 61 | +MSIs, a device can support more interrupts, allowing each interrupt | |
| 62 | +to be specialised to a different purpose. One possible design gives | |
| 63 | +infrequent conditions (such as errors) their own interrupt which allows | |
| 64 | +the driver to handle the normal interrupt handling path more efficiently. | |
| 65 | +Other possible designs include giving one interrupt to each packet queue | |
| 66 | +in a network card or each port in a storage controller. | |
| 67 | + | |
| 68 | + | |
| 69 | +How to use MSIs | |
| 70 | +=============== | |
| 71 | + | |
| 72 | +PCI devices are initialised to use pin-based interrupts. The device | |
| 73 | +driver has to set up the device to use MSI or MSI-X. Not all machines | |
| 74 | +support MSIs correctly, and for those machines, the APIs described below | |
| 75 | +will simply fail and the device will continue to use pin-based interrupts. | |
| 76 | + | |
| 77 | +Include kernel support for MSIs | |
| 78 | +------------------------------- | |
| 79 | + | |
| 80 | +To support MSI or MSI-X, the kernel must be built with the CONFIG_PCI_MSI | |
| 81 | +option enabled. This option is only available on some architectures, | |
| 82 | +and it may depend on some other options also being set. For example, | |
| 83 | +on x86, you must also enable X86_UP_APIC or SMP in order to see the | |
| 84 | +CONFIG_PCI_MSI option. | |
| 85 | + | |
| 86 | +Using MSI | |
| 87 | +--------- | |
| 88 | + | |
| 89 | +Most of the hard work is done for the driver in the PCI layer. The driver | |
| 90 | +simply has to request that the PCI layer set up the MSI capability for this | |
| 91 | +device. | |
| 92 | + | |
| 93 | +To automatically use MSI or MSI-X interrupt vectors, use the following | |
| 94 | +function:: | |
| 95 | + | |
| 96 | + int pci_alloc_irq_vectors(struct pci_dev *dev, unsigned int min_vecs, | |
| 97 | + unsigned int max_vecs, unsigned int flags); | |
| 98 | + | |
| 99 | +which allocates up to max_vecs interrupt vectors for a PCI device. It | |
| 100 | +returns the number of vectors allocated or a negative error. If the device | |
| 101 | +has a requirements for a minimum number of vectors the driver can pass a | |
| 102 | +min_vecs argument set to this limit, and the PCI core will return -ENOSPC | |
| 103 | +if it can't meet the minimum number of vectors. | |
| 104 | + | |
| 105 | +The flags argument is used to specify which type of interrupt can be used | |
| 106 | +by the device and the driver (PCI_IRQ_LEGACY, PCI_IRQ_MSI, PCI_IRQ_MSIX). | |
| 107 | +A convenient short-hand (PCI_IRQ_ALL_TYPES) is also available to ask for | |
| 108 | +any possible kind of interrupt. If the PCI_IRQ_AFFINITY flag is set, | |
| 109 | +pci_alloc_irq_vectors() will spread the interrupts around the available CPUs. | |
| 110 | + | |
| 111 | +To get the Linux IRQ numbers passed to request_irq() and free_irq() and the | |
| 112 | +vectors, use the following function:: | |
| 113 | + | |
| 114 | + int pci_irq_vector(struct pci_dev *dev, unsigned int nr); | |
| 115 | + | |
| 116 | +Any allocated resources should be freed before removing the device using | |
| 117 | +the following function:: | |
| 118 | + | |
| 119 | + void pci_free_irq_vectors(struct pci_dev *dev); | |
| 120 | + | |
| 121 | +If a device supports both MSI-X and MSI capabilities, this API will use the | |
| 122 | +MSI-X facilities in preference to the MSI facilities. MSI-X supports any | |
| 123 | +number of interrupts between 1 and 2048. In contrast, MSI is restricted to | |
| 124 | +a maximum of 32 interrupts (and must be a power of two). In addition, the | |
| 125 | +MSI interrupt vectors must be allocated consecutively, so the system might | |
| 126 | +not be able to allocate as many vectors for MSI as it could for MSI-X. On | |
| 127 | +some platforms, MSI interrupts must all be targeted at the same set of CPUs | |
| 128 | +whereas MSI-X interrupts can all be targeted at different CPUs. | |
| 129 | + | |
| 130 | +If a device supports neither MSI-X or MSI it will fall back to a single | |
| 131 | +legacy IRQ vector. | |
| 132 | + | |
| 133 | +The typical usage of MSI or MSI-X interrupts is to allocate as many vectors | |
| 134 | +as possible, likely up to the limit supported by the device. If nvec is | |
| 135 | +larger than the number supported by the device it will automatically be | |
| 136 | +capped to the supported limit, so there is no need to query the number of | |
| 137 | +vectors supported beforehand:: | |
| 138 | + | |
| 139 | + nvec = pci_alloc_irq_vectors(pdev, 1, nvec, PCI_IRQ_ALL_TYPES) | |
| 140 | + if (nvec < 0) | |
| 141 | + goto out_err; | |
| 142 | + | |
| 143 | +If a driver is unable or unwilling to deal with a variable number of MSI | |
| 144 | +interrupts it can request a particular number of interrupts by passing that | |
| 145 | +number to pci_alloc_irq_vectors() function as both 'min_vecs' and | |
| 146 | +'max_vecs' parameters:: | |
| 147 | + | |
| 148 | + ret = pci_alloc_irq_vectors(pdev, nvec, nvec, PCI_IRQ_ALL_TYPES); | |
| 149 | + if (ret < 0) | |
| 150 | + goto out_err; | |
| 151 | + | |
| 152 | +The most notorious example of the request type described above is enabling | |
| 153 | +the single MSI mode for a device. It could be done by passing two 1s as | |
| 154 | +'min_vecs' and 'max_vecs':: | |
| 155 | + | |
| 156 | + ret = pci_alloc_irq_vectors(pdev, 1, 1, PCI_IRQ_ALL_TYPES); | |
| 157 | + if (ret < 0) | |
| 158 | + goto out_err; | |
| 159 | + | |
| 160 | +Some devices might not support using legacy line interrupts, in which case | |
| 161 | +the driver can specify that only MSI or MSI-X is acceptable:: | |
| 162 | + | |
| 163 | + nvec = pci_alloc_irq_vectors(pdev, 1, nvec, PCI_IRQ_MSI | PCI_IRQ_MSIX); | |
| 164 | + if (nvec < 0) | |
| 165 | + goto out_err; | |
| 166 | + | |
| 167 | +Legacy APIs | |
| 168 | +----------- | |
| 169 | + | |
| 170 | +The following old APIs to enable and disable MSI or MSI-X interrupts should | |
| 171 | +not be used in new code:: | |
| 172 | + | |
| 173 | + pci_enable_msi() /* deprecated */ | |
| 174 | + pci_disable_msi() /* deprecated */ | |
| 175 | + pci_enable_msix_range() /* deprecated */ | |
| 176 | + pci_enable_msix_exact() /* deprecated */ | |
| 177 | + pci_disable_msix() /* deprecated */ | |
| 178 | + | |
| 179 | +Additionally there are APIs to provide the number of supported MSI or MSI-X | |
| 180 | +vectors: pci_msi_vec_count() and pci_msix_vec_count(). In general these | |
| 181 | +should be avoided in favor of letting pci_alloc_irq_vectors() cap the | |
| 182 | +number of vectors. If you have a legitimate special use case for the count | |
| 183 | +of vectors we might have to revisit that decision and add a | |
| 184 | +pci_nr_irq_vectors() helper that handles MSI and MSI-X transparently. | |
| 185 | + | |
| 186 | +Considerations when using MSIs | |
| 187 | +------------------------------ | |
| 188 | + | |
| 189 | +Spinlocks | |
| 190 | +~~~~~~~~~ | |
| 191 | + | |
| 192 | +Most device drivers have a per-device spinlock which is taken in the | |
| 193 | +interrupt handler. With pin-based interrupts or a single MSI, it is not | |
| 194 | +necessary to disable interrupts (Linux guarantees the same interrupt will | |
| 195 | +not be re-entered). If a device uses multiple interrupts, the driver | |
| 196 | +must disable interrupts while the lock is held. If the device sends | |
| 197 | +a different interrupt, the driver will deadlock trying to recursively | |
| 198 | +acquire the spinlock. Such deadlocks can be avoided by using | |
| 199 | +spin_lock_irqsave() or spin_lock_irq() which disable local interrupts | |
| 200 | +and acquire the lock (see Documentation/kernel-hacking/locking.rst). | |
| 201 | + | |
| 202 | +How to tell whether MSI/MSI-X is enabled on a device | |
| 203 | +---------------------------------------------------- | |
| 204 | + | |
| 205 | +Using 'lspci -v' (as root) may show some devices with "MSI", "Message | |
| 206 | +Signalled Interrupts" or "MSI-X" capabilities. Each of these capabilities | |
| 207 | +has an 'Enable' flag which is followed with either "+" (enabled) | |
| 208 | +or "-" (disabled). | |
| 209 | + | |
| 210 | + | |
| 211 | +MSI quirks | |
| 212 | +========== | |
| 213 | + | |
| 214 | +Several PCI chipsets or devices are known not to support MSIs. | |
| 215 | +The PCI stack provides three ways to disable MSIs: | |
| 216 | + | |
| 217 | +1. globally | |
| 218 | +2. on all devices behind a specific bridge | |
| 219 | +3. on a single device | |
| 220 | + | |
| 221 | +Disabling MSIs globally | |
| 222 | +----------------------- | |
| 223 | + | |
| 224 | +Some host chipsets simply don't support MSIs properly. If we're | |
| 225 | +lucky, the manufacturer knows this and has indicated it in the ACPI | |
| 226 | +FADT table. In this case, Linux automatically disables MSIs. | |
| 227 | +Some boards don't include this information in the table and so we have | |
| 228 | +to detect them ourselves. The complete list of these is found near the | |
| 229 | +quirk_disable_all_msi() function in drivers/pci/quirks.c. | |
| 230 | + | |
| 231 | +If you have a board which has problems with MSIs, you can pass pci=nomsi | |
| 232 | +on the kernel command line to disable MSIs on all devices. It would be | |
| 233 | +in your best interests to report the problem to linux-pci@vger.kernel.org | |
| 234 | +including a full 'lspci -v' so we can add the quirks to the kernel. | |
| 235 | + | |
| 236 | +Disabling MSIs below a bridge | |
| 237 | +----------------------------- | |
| 238 | + | |
| 239 | +Some PCI bridges are not able to route MSIs between busses properly. | |
| 240 | +In this case, MSIs must be disabled on all devices behind the bridge. | |
| 241 | + | |
| 242 | +Some bridges allow you to enable MSIs by changing some bits in their | |
| 243 | +PCI configuration space (especially the Hypertransport chipsets such | |
| 244 | +as the nVidia nForce and Serverworks HT2000). As with host chipsets, | |
| 245 | +Linux mostly knows about them and automatically enables MSIs if it can. | |
| 246 | +If you have a bridge unknown to Linux, you can enable | |
| 247 | +MSIs in configuration space using whatever method you know works, then | |
| 248 | +enable MSIs on that bridge by doing:: | |
| 249 | + | |
| 250 | + echo 1 > /sys/bus/pci/devices/$bridge/msi_bus | |
| 251 | + | |
| 252 | +where $bridge is the PCI address of the bridge you've enabled (eg | |
| 253 | +0000:00:0e.0). | |
| 254 | + | |
| 255 | +To disable MSIs, echo 0 instead of 1. Changing this value should be | |
| 256 | +done with caution as it could break interrupt handling for all devices | |
| 257 | +below this bridge. | |
| 258 | + | |
| 259 | +Again, please notify linux-pci@vger.kernel.org of any bridges that need | |
| 260 | +special handling. | |
| 261 | + | |
| 262 | +Disabling MSIs on a single device | |
| 263 | +--------------------------------- | |
| 264 | + | |
| 265 | +Some devices are known to have faulty MSI implementations. Usually this | |
| 266 | +is handled in the individual device driver, but occasionally it's necessary | |
| 267 | +to handle this with a quirk. Some drivers have an option to disable use | |
| 268 | +of MSI. While this is a convenient workaround for the driver author, | |
| 269 | +it is not good practice, and should not be emulated. | |
| 270 | + | |
| 271 | +Finding why MSIs are disabled on a device | |
| 272 | +----------------------------------------- | |
| 273 | + | |
| 274 | +From the above three sections, you can see that there are many reasons | |
| 275 | +why MSIs may not be enabled for a given device. Your first step should | |
| 276 | +be to examine your dmesg carefully to determine whether MSIs are enabled | |
| 277 | +for your machine. You should also check your .config to be sure you | |
| 278 | +have enabled CONFIG_PCI_MSI. | |
| 279 | + | |
| 280 | +Then, 'lspci -t' gives the list of bridges above a device. Reading | |
| 281 | +`/sys/bus/pci/devices/*/msi_bus` will tell you whether MSIs are enabled (1) | |
| 282 | +or disabled (0). If 0 is found in any of the msi_bus files belonging | |
| 283 | +to bridges between the PCI root and the device, MSIs are disabled. | |
| 284 | + | |
| 285 | +It is also worth checking the device driver to see whether it supports MSIs. | |
| 286 | +For example, it may contain calls to pci_irq_alloc_vectors() with the | |
| 287 | +PCI_IRQ_MSI or PCI_IRQ_MSIX flags. | |
| @@ -0,0 +1,427 @@ | ||
| 1 | +.. SPDX-License-Identifier: GPL-2.0 | |
| 2 | + | |
| 3 | +================== | |
| 4 | +PCI Error Recovery | |
| 5 | +================== | |
| 6 | + | |
| 7 | + | |
| 8 | +:Authors: - Linas Vepstas <linasvepstas@gmail.com> | |
| 9 | + - Richard Lary <rlary@us.ibm.com> | |
| 10 | + - Mike Mason <mmlnx@us.ibm.com> | |
| 11 | + | |
| 12 | + | |
| 13 | +Many PCI bus controllers are able to detect a variety of hardware | |
| 14 | +PCI errors on the bus, such as parity errors on the data and address | |
| 15 | +buses, as well as SERR and PERR errors. Some of the more advanced | |
| 16 | +chipsets are able to deal with these errors; these include PCI-E chipsets, | |
| 17 | +and the PCI-host bridges found on IBM Power4, Power5 and Power6-based | |
| 18 | +pSeries boxes. A typical action taken is to disconnect the affected device, | |
| 19 | +halting all I/O to it. The goal of a disconnection is to avoid system | |
| 20 | +corruption; for example, to halt system memory corruption due to DMA's | |
| 21 | +to "wild" addresses. Typically, a reconnection mechanism is also | |
| 22 | +offered, so that the affected PCI device(s) are reset and put back | |
| 23 | +into working condition. The reset phase requires coordination | |
| 24 | +between the affected device drivers and the PCI controller chip. | |
| 25 | +This document describes a generic API for notifying device drivers | |
| 26 | +of a bus disconnection, and then performing error recovery. | |
| 27 | +This API is currently implemented in the 2.6.16 and later kernels. | |
| 28 | + | |
| 29 | +Reporting and recovery is performed in several steps. First, when | |
| 30 | +a PCI hardware error has resulted in a bus disconnect, that event | |
| 31 | +is reported as soon as possible to all affected device drivers, | |
| 32 | +including multiple instances of a device driver on multi-function | |
| 33 | +cards. This allows device drivers to avoid deadlocking in spinloops, | |
| 34 | +waiting for some i/o-space register to change, when it never will. | |
| 35 | +It also gives the drivers a chance to defer incoming I/O as | |
| 36 | +needed. | |
| 37 | + | |
| 38 | +Next, recovery is performed in several stages. Most of the complexity | |
| 39 | +is forced by the need to handle multi-function devices, that is, | |
| 40 | +devices that have multiple device drivers associated with them. | |
| 41 | +In the first stage, each driver is allowed to indicate what type | |
| 42 | +of reset it desires, the choices being a simple re-enabling of I/O | |
| 43 | +or requesting a slot reset. | |
| 44 | + | |
| 45 | +If any driver requests a slot reset, that is what will be done. | |
| 46 | + | |
| 47 | +After a reset and/or a re-enabling of I/O, all drivers are | |
| 48 | +again notified, so that they may then perform any device setup/config | |
| 49 | +that may be required. After these have all completed, a final | |
| 50 | +"resume normal operations" event is sent out. | |
| 51 | + | |
| 52 | +The biggest reason for choosing a kernel-based implementation rather | |
| 53 | +than a user-space implementation was the need to deal with bus | |
| 54 | +disconnects of PCI devices attached to storage media, and, in particular, | |
| 55 | +disconnects from devices holding the root file system. If the root | |
| 56 | +file system is disconnected, a user-space mechanism would have to go | |
| 57 | +through a large number of contortions to complete recovery. Almost all | |
| 58 | +of the current Linux file systems are not tolerant of disconnection | |
| 59 | +from/reconnection to their underlying block device. By contrast, | |
| 60 | +bus errors are easy to manage in the device driver. Indeed, most | |
| 61 | +device drivers already handle very similar recovery procedures; | |
| 62 | +for example, the SCSI-generic layer already provides significant | |
| 63 | +mechanisms for dealing with SCSI bus errors and SCSI bus resets. | |
| 64 | + | |
| 65 | + | |
| 66 | +Detailed Design | |
| 67 | +=============== | |
| 68 | + | |
| 69 | +Design and implementation details below, based on a chain of | |
| 70 | +public email discussions with Ben Herrenschmidt, circa 5 April 2005. | |
| 71 | + | |
| 72 | +The error recovery API support is exposed to the driver in the form of | |
| 73 | +a structure of function pointers pointed to by a new field in struct | |
| 74 | +pci_driver. A driver that fails to provide the structure is "non-aware", | |
| 75 | +and the actual recovery steps taken are platform dependent. The | |
| 76 | +arch/powerpc implementation will simulate a PCI hotplug remove/add. | |
| 77 | + | |
| 78 | +This structure has the form:: | |
| 79 | + | |
| 80 | + struct pci_error_handlers | |
| 81 | + { | |
| 82 | + int (*error_detected)(struct pci_dev *dev, enum pci_channel_state); | |
| 83 | + int (*mmio_enabled)(struct pci_dev *dev); | |
| 84 | + int (*slot_reset)(struct pci_dev *dev); | |
| 85 | + void (*resume)(struct pci_dev *dev); | |
| 86 | + }; | |
| 87 | + | |
| 88 | +The possible channel states are:: | |
| 89 | + | |
| 90 | + enum pci_channel_state { | |
| 91 | + pci_channel_io_normal, /* I/O channel is in normal state */ | |
| 92 | + pci_channel_io_frozen, /* I/O to channel is blocked */ | |
| 93 | + pci_channel_io_perm_failure, /* PCI card is dead */ | |
| 94 | + }; | |
| 95 | + | |
| 96 | +Possible return values are:: | |
| 97 | + | |
| 98 | + enum pci_ers_result { | |
| 99 | + PCI_ERS_RESULT_NONE, /* no result/none/not supported in device driver */ | |
| 100 | + PCI_ERS_RESULT_CAN_RECOVER, /* Device driver can recover without slot reset */ | |
| 101 | + PCI_ERS_RESULT_NEED_RESET, /* Device driver wants slot to be reset. */ | |
| 102 | + PCI_ERS_RESULT_DISCONNECT, /* Device has completely failed, is unrecoverable */ | |
| 103 | + PCI_ERS_RESULT_RECOVERED, /* Device driver is fully recovered and operational */ | |
| 104 | + }; | |
| 105 | + | |
| 106 | +A driver does not have to implement all of these callbacks; however, | |
| 107 | +if it implements any, it must implement error_detected(). If a callback | |
| 108 | +is not implemented, the corresponding feature is considered unsupported. | |
| 109 | +For example, if mmio_enabled() and resume() aren't there, then it | |
| 110 | +is assumed that the driver is not doing any direct recovery and requires | |
| 111 | +a slot reset. Typically a driver will want to know about | |
| 112 | +a slot_reset(). | |
| 113 | + | |
| 114 | +The actual steps taken by a platform to recover from a PCI error | |
| 115 | +event will be platform-dependent, but will follow the general | |
| 116 | +sequence described below. | |
| 117 | + | |
| 118 | +STEP 0: Error Event | |
| 119 | +------------------- | |
| 120 | +A PCI bus error is detected by the PCI hardware. On powerpc, the slot | |
| 121 | +is isolated, in that all I/O is blocked: all reads return 0xffffffff, | |
| 122 | +all writes are ignored. | |
| 123 | + | |
| 124 | + | |
| 125 | +STEP 1: Notification | |
| 126 | +-------------------- | |
| 127 | +Platform calls the error_detected() callback on every instance of | |
| 128 | +every driver affected by the error. | |
| 129 | + | |
| 130 | +At this point, the device might not be accessible anymore, depending on | |
| 131 | +the platform (the slot will be isolated on powerpc). The driver may | |
| 132 | +already have "noticed" the error because of a failing I/O, but this | |
| 133 | +is the proper "synchronization point", that is, it gives the driver | |
| 134 | +a chance to cleanup, waiting for pending stuff (timers, whatever, etc...) | |
| 135 | +to complete; it can take semaphores, schedule, etc... everything but | |
| 136 | +touch the device. Within this function and after it returns, the driver | |
| 137 | +shouldn't do any new IOs. Called in task context. This is sort of a | |
| 138 | +"quiesce" point. See note about interrupts at the end of this doc. | |
| 139 | + | |
| 140 | +All drivers participating in this system must implement this call. | |
| 141 | +The driver must return one of the following result codes: | |
| 142 | + | |
| 143 | + - PCI_ERS_RESULT_CAN_RECOVER | |
| 144 | + Driver returns this if it thinks it might be able to recover | |
| 145 | + the HW by just banging IOs or if it wants to be given | |
| 146 | + a chance to extract some diagnostic information (see | |
| 147 | + mmio_enable, below). | |
| 148 | + - PCI_ERS_RESULT_NEED_RESET | |
| 149 | + Driver returns this if it can't recover without a | |
| 150 | + slot reset. | |
| 151 | + - PCI_ERS_RESULT_DISCONNECT | |
| 152 | + Driver returns this if it doesn't want to recover at all. | |
| 153 | + | |
| 154 | +The next step taken will depend on the result codes returned by the | |
| 155 | +drivers. | |
| 156 | + | |
| 157 | +If all drivers on the segment/slot return PCI_ERS_RESULT_CAN_RECOVER, | |
| 158 | +then the platform should re-enable IOs on the slot (or do nothing in | |
| 159 | +particular, if the platform doesn't isolate slots), and recovery | |
| 160 | +proceeds to STEP 2 (MMIO Enable). | |
| 161 | + | |
| 162 | +If any driver requested a slot reset (by returning PCI_ERS_RESULT_NEED_RESET), | |
| 163 | +then recovery proceeds to STEP 4 (Slot Reset). | |
| 164 | + | |
| 165 | +If the platform is unable to recover the slot, the next step | |
| 166 | +is STEP 6 (Permanent Failure). | |
| 167 | + | |
| 168 | +.. note:: | |
| 169 | + | |
| 170 | + The current powerpc implementation assumes that a device driver will | |
| 171 | + *not* schedule or semaphore in this routine; the current powerpc | |
| 172 | + implementation uses one kernel thread to notify all devices; | |
| 173 | + thus, if one device sleeps/schedules, all devices are affected. | |
| 174 | + Doing better requires complex multi-threaded logic in the error | |
| 175 | + recovery implementation (e.g. waiting for all notification threads | |
| 176 | + to "join" before proceeding with recovery.) This seems excessively | |
| 177 | + complex and not worth implementing. | |
| 178 | + | |
| 179 | + The current powerpc implementation doesn't much care if the device | |
| 180 | + attempts I/O at this point, or not. I/O's will fail, returning | |
| 181 | + a value of 0xff on read, and writes will be dropped. If more than | |
| 182 | + EEH_MAX_FAILS I/O's are attempted to a frozen adapter, EEH | |
| 183 | + assumes that the device driver has gone into an infinite loop | |
| 184 | + and prints an error to syslog. A reboot is then required to | |
| 185 | + get the device working again. | |
| 186 | + | |
| 187 | +STEP 2: MMIO Enabled | |
| 188 | +-------------------- | |
| 189 | +The platform re-enables MMIO to the device (but typically not the | |
| 190 | +DMA), and then calls the mmio_enabled() callback on all affected | |
| 191 | +device drivers. | |
| 192 | + | |
| 193 | +This is the "early recovery" call. IOs are allowed again, but DMA is | |
| 194 | +not, with some restrictions. This is NOT a callback for the driver to | |
| 195 | +start operations again, only to peek/poke at the device, extract diagnostic | |
| 196 | +information, if any, and eventually do things like trigger a device local | |
| 197 | +reset or some such, but not restart operations. This callback is made if | |
| 198 | +all drivers on a segment agree that they can try to recover and if no automatic | |
| 199 | +link reset was performed by the HW. If the platform can't just re-enable IOs | |
| 200 | +without a slot reset or a link reset, it will not call this callback, and | |
| 201 | +instead will have gone directly to STEP 3 (Link Reset) or STEP 4 (Slot Reset) | |
| 202 | + | |
| 203 | +.. note:: | |
| 204 | + | |
| 205 | + The following is proposed; no platform implements this yet: | |
| 206 | + Proposal: All I/O's should be done _synchronously_ from within | |
| 207 | + this callback, errors triggered by them will be returned via | |
| 208 | + the normal pci_check_whatever() API, no new error_detected() | |
| 209 | + callback will be issued due to an error happening here. However, | |
| 210 | + such an error might cause IOs to be re-blocked for the whole | |
| 211 | + segment, and thus invalidate the recovery that other devices | |
| 212 | + on the same segment might have done, forcing the whole segment | |
| 213 | + into one of the next states, that is, link reset or slot reset. | |
| 214 | + | |
| 215 | +The driver should return one of the following result codes: | |
| 216 | + - PCI_ERS_RESULT_RECOVERED | |
| 217 | + Driver returns this if it thinks the device is fully | |
| 218 | + functional and thinks it is ready to start | |
| 219 | + normal driver operations again. There is no | |
| 220 | + guarantee that the driver will actually be | |
| 221 | + allowed to proceed, as another driver on the | |
| 222 | + same segment might have failed and thus triggered a | |
| 223 | + slot reset on platforms that support it. | |
| 224 | + | |
| 225 | + - PCI_ERS_RESULT_NEED_RESET | |
| 226 | + Driver returns this if it thinks the device is not | |
| 227 | + recoverable in its current state and it needs a slot | |
| 228 | + reset to proceed. | |
| 229 | + | |
| 230 | + - PCI_ERS_RESULT_DISCONNECT | |
| 231 | + Same as above. Total failure, no recovery even after | |
| 232 | + reset driver dead. (To be defined more precisely) | |
| 233 | + | |
| 234 | +The next step taken depends on the results returned by the drivers. | |
| 235 | +If all drivers returned PCI_ERS_RESULT_RECOVERED, then the platform | |
| 236 | +proceeds to either STEP3 (Link Reset) or to STEP 5 (Resume Operations). | |
| 237 | + | |
| 238 | +If any driver returned PCI_ERS_RESULT_NEED_RESET, then the platform | |
| 239 | +proceeds to STEP 4 (Slot Reset) | |
| 240 | + | |
| 241 | +STEP 3: Link Reset | |
| 242 | +------------------ | |
| 243 | +The platform resets the link. This is a PCI-Express specific step | |
| 244 | +and is done whenever a fatal error has been detected that can be | |
| 245 | +"solved" by resetting the link. | |
| 246 | + | |
| 247 | +STEP 4: Slot Reset | |
| 248 | +------------------ | |
| 249 | + | |
| 250 | +In response to a return value of PCI_ERS_RESULT_NEED_RESET, the | |
| 251 | +the platform will perform a slot reset on the requesting PCI device(s). | |
| 252 | +The actual steps taken by a platform to perform a slot reset | |
| 253 | +will be platform-dependent. Upon completion of slot reset, the | |
| 254 | +platform will call the device slot_reset() callback. | |
| 255 | + | |
| 256 | +Powerpc platforms implement two levels of slot reset: | |
| 257 | +soft reset(default) and fundamental(optional) reset. | |
| 258 | + | |
| 259 | +Powerpc soft reset consists of asserting the adapter #RST line and then | |
| 260 | +restoring the PCI BAR's and PCI configuration header to a state | |
| 261 | +that is equivalent to what it would be after a fresh system | |
| 262 | +power-on followed by power-on BIOS/system firmware initialization. | |
| 263 | +Soft reset is also known as hot-reset. | |
| 264 | + | |
| 265 | +Powerpc fundamental reset is supported by PCI Express cards only | |
| 266 | +and results in device's state machines, hardware logic, port states and | |
| 267 | +configuration registers to initialize to their default conditions. | |
| 268 | + | |
| 269 | +For most PCI devices, a soft reset will be sufficient for recovery. | |
| 270 | +Optional fundamental reset is provided to support a limited number | |
| 271 | +of PCI Express devices for which a soft reset is not sufficient | |
| 272 | +for recovery. | |
| 273 | + | |
| 274 | +If the platform supports PCI hotplug, then the reset might be | |
| 275 | +performed by toggling the slot electrical power off/on. | |
| 276 | + | |
| 277 | +It is important for the platform to restore the PCI config space | |
| 278 | +to the "fresh poweron" state, rather than the "last state". After | |
| 279 | +a slot reset, the device driver will almost always use its standard | |
| 280 | +device initialization routines, and an unusual config space setup | |
| 281 | +may result in hung devices, kernel panics, or silent data corruption. | |
| 282 | + | |
| 283 | +This call gives drivers the chance to re-initialize the hardware | |
| 284 | +(re-download firmware, etc.). At this point, the driver may assume | |
| 285 | +that the card is in a fresh state and is fully functional. The slot | |
| 286 | +is unfrozen and the driver has full access to PCI config space, | |
| 287 | +memory mapped I/O space and DMA. Interrupts (Legacy, MSI, or MSI-X) | |
| 288 | +will also be available. | |
| 289 | + | |
| 290 | +Drivers should not restart normal I/O processing operations | |
| 291 | +at this point. If all device drivers report success on this | |
| 292 | +callback, the platform will call resume() to complete the sequence, | |
| 293 | +and let the driver restart normal I/O processing. | |
| 294 | + | |
| 295 | +A driver can still return a critical failure for this function if | |
| 296 | +it can't get the device operational after reset. If the platform | |
| 297 | +previously tried a soft reset, it might now try a hard reset (power | |
| 298 | +cycle) and then call slot_reset() again. It the device still can't | |
| 299 | +be recovered, there is nothing more that can be done; the platform | |
| 300 | +will typically report a "permanent failure" in such a case. The | |
| 301 | +device will be considered "dead" in this case. | |
| 302 | + | |
| 303 | +Drivers for multi-function cards will need to coordinate among | |
| 304 | +themselves as to which driver instance will perform any "one-shot" | |
| 305 | +or global device initialization. For example, the Symbios sym53cxx2 | |
| 306 | +driver performs device init only from PCI function 0:: | |
| 307 | + | |
| 308 | + + if (PCI_FUNC(pdev->devfn) == 0) | |
| 309 | + + sym_reset_scsi_bus(np, 0); | |
| 310 | + | |
| 311 | +Result codes: | |
| 312 | + - PCI_ERS_RESULT_DISCONNECT | |
| 313 | + Same as above. | |
| 314 | + | |
| 315 | +Drivers for PCI Express cards that require a fundamental reset must | |
| 316 | +set the needs_freset bit in the pci_dev structure in their probe function. | |
| 317 | +For example, the QLogic qla2xxx driver sets the needs_freset bit for certain | |
| 318 | +PCI card types:: | |
| 319 | + | |
| 320 | + + /* Set EEH reset type to fundamental if required by hba */ | |
| 321 | + + if (IS_QLA24XX(ha) || IS_QLA25XX(ha) || IS_QLA81XX(ha)) | |
| 322 | + + pdev->needs_freset = 1; | |
| 323 | + + | |
| 324 | + | |
| 325 | +Platform proceeds either to STEP 5 (Resume Operations) or STEP 6 (Permanent | |
| 326 | +Failure). | |
| 327 | + | |
| 328 | +.. note:: | |
| 329 | + | |
| 330 | + The current powerpc implementation does not try a power-cycle | |
| 331 | + reset if the driver returned PCI_ERS_RESULT_DISCONNECT. | |
| 332 | + However, it probably should. | |
| 333 | + | |
| 334 | + | |
| 335 | +STEP 5: Resume Operations | |
| 336 | +------------------------- | |
| 337 | +The platform will call the resume() callback on all affected device | |
| 338 | +drivers if all drivers on the segment have returned | |
| 339 | +PCI_ERS_RESULT_RECOVERED from one of the 3 previous callbacks. | |
| 340 | +The goal of this callback is to tell the driver to restart activity, | |
| 341 | +that everything is back and running. This callback does not return | |
| 342 | +a result code. | |
| 343 | + | |
| 344 | +At this point, if a new error happens, the platform will restart | |
| 345 | +a new error recovery sequence. | |
| 346 | + | |
| 347 | +STEP 6: Permanent Failure | |
| 348 | +------------------------- | |
| 349 | +A "permanent failure" has occurred, and the platform cannot recover | |
| 350 | +the device. The platform will call error_detected() with a | |
| 351 | +pci_channel_state value of pci_channel_io_perm_failure. | |
| 352 | + | |
| 353 | +The device driver should, at this point, assume the worst. It should | |
| 354 | +cancel all pending I/O, refuse all new I/O, returning -EIO to | |
| 355 | +higher layers. The device driver should then clean up all of its | |
| 356 | +memory and remove itself from kernel operations, much as it would | |
| 357 | +during system shutdown. | |
| 358 | + | |
| 359 | +The platform will typically notify the system operator of the | |
| 360 | +permanent failure in some way. If the device is hotplug-capable, | |
| 361 | +the operator will probably want to remove and replace the device. | |
| 362 | +Note, however, not all failures are truly "permanent". Some are | |
| 363 | +caused by over-heating, some by a poorly seated card. Many | |
| 364 | +PCI error events are caused by software bugs, e.g. DMA's to | |
| 365 | +wild addresses or bogus split transactions due to programming | |
| 366 | +errors. See the discussion in powerpc/eeh-pci-error-recovery.txt | |
| 367 | +for additional detail on real-life experience of the causes of | |
| 368 | +software errors. | |
| 369 | + | |
| 370 | + | |
| 371 | +Conclusion; General Remarks | |
| 372 | +--------------------------- | |
| 373 | +The way the callbacks are called is platform policy. A platform with | |
| 374 | +no slot reset capability may want to just "ignore" drivers that can't | |
| 375 | +recover (disconnect them) and try to let other cards on the same segment | |
| 376 | +recover. Keep in mind that in most real life cases, though, there will | |
| 377 | +be only one driver per segment. | |
| 378 | + | |
| 379 | +Now, a note about interrupts. If you get an interrupt and your | |
| 380 | +device is dead or has been isolated, there is a problem :) | |
| 381 | +The current policy is to turn this into a platform policy. | |
| 382 | +That is, the recovery API only requires that: | |
| 383 | + | |
| 384 | + - There is no guarantee that interrupt delivery can proceed from any | |
| 385 | + device on the segment starting from the error detection and until the | |
| 386 | + slot_reset callback is called, at which point interrupts are expected | |
| 387 | + to be fully operational. | |
| 388 | + | |
| 389 | + - There is no guarantee that interrupt delivery is stopped, that is, | |
| 390 | + a driver that gets an interrupt after detecting an error, or that detects | |
| 391 | + an error within the interrupt handler such that it prevents proper | |
| 392 | + ack'ing of the interrupt (and thus removal of the source) should just | |
| 393 | + return IRQ_NOTHANDLED. It's up to the platform to deal with that | |
| 394 | + condition, typically by masking the IRQ source during the duration of | |
| 395 | + the error handling. It is expected that the platform "knows" which | |
| 396 | + interrupts are routed to error-management capable slots and can deal | |
| 397 | + with temporarily disabling that IRQ number during error processing (this | |
| 398 | + isn't terribly complex). That means some IRQ latency for other devices | |
| 399 | + sharing the interrupt, but there is simply no other way. High end | |
| 400 | + platforms aren't supposed to share interrupts between many devices | |
| 401 | + anyway :) | |
| 402 | + | |
| 403 | +.. note:: | |
| 404 | + | |
| 405 | + Implementation details for the powerpc platform are discussed in | |
| 406 | + the file Documentation/powerpc/eeh-pci-error-recovery.rst | |
| 407 | + | |
| 408 | + As of this writing, there is a growing list of device drivers with | |
| 409 | + patches implementing error recovery. Not all of these patches are in | |
| 410 | + mainline yet. These may be used as "examples": | |
| 411 | + | |
| 412 | + - drivers/scsi/ipr | |
| 413 | + - drivers/scsi/sym53c8xx_2 | |
| 414 | + - drivers/scsi/qla2xxx | |
| 415 | + - drivers/scsi/lpfc | |
| 416 | + - drivers/next/bnx2.c | |
| 417 | + - drivers/next/e100.c | |
| 418 | + - drivers/net/e1000 | |
| 419 | + - drivers/net/e1000e | |
| 420 | + - drivers/net/ixgb | |
| 421 | + - drivers/net/ixgbe | |
| 422 | + - drivers/net/cxgb3 | |
| 423 | + - drivers/net/s2io.c | |
| 424 | + - drivers/net/qlge | |
| 425 | + | |
| 426 | +The End | |
| 427 | +------- | |
| @@ -1,413 +0,0 @@ | ||
| 1 | − | |
| 2 | − PCI Error Recovery | |
| 3 | − ------------------ | |
| 4 | − February 2, 2006 | |
| 5 | − | |
| 6 | − Current document maintainer: | |
| 7 | − Linas Vepstas <linasvepstas@gmail.com> | |
| 8 | − updated by Richard Lary <rlary@us.ibm.com> | |
| 9 | − and Mike Mason <mmlnx@us.ibm.com> on 27-Jul-2009 | |
| 10 | − | |
| 11 | − | |
| 12 | −Many PCI bus controllers are able to detect a variety of hardware | |
| 13 | −PCI errors on the bus, such as parity errors on the data and address | |
| 14 | −buses, as well as SERR and PERR errors. Some of the more advanced | |
| 15 | −chipsets are able to deal with these errors; these include PCI-E chipsets, | |
| 16 | −and the PCI-host bridges found on IBM Power4, Power5 and Power6-based | |
| 17 | −pSeries boxes. A typical action taken is to disconnect the affected device, | |
| 18 | −halting all I/O to it. The goal of a disconnection is to avoid system | |
| 19 | −corruption; for example, to halt system memory corruption due to DMA's | |
| 20 | −to "wild" addresses. Typically, a reconnection mechanism is also | |
| 21 | −offered, so that the affected PCI device(s) are reset and put back | |
| 22 | −into working condition. The reset phase requires coordination | |
| 23 | −between the affected device drivers and the PCI controller chip. | |
| 24 | −This document describes a generic API for notifying device drivers | |
| 25 | −of a bus disconnection, and then performing error recovery. | |
| 26 | −This API is currently implemented in the 2.6.16 and later kernels. | |
| 27 | − | |
| 28 | −Reporting and recovery is performed in several steps. First, when | |
| 29 | −a PCI hardware error has resulted in a bus disconnect, that event | |
| 30 | −is reported as soon as possible to all affected device drivers, | |
| 31 | −including multiple instances of a device driver on multi-function | |
| 32 | −cards. This allows device drivers to avoid deadlocking in spinloops, | |
| 33 | −waiting for some i/o-space register to change, when it never will. | |
| 34 | −It also gives the drivers a chance to defer incoming I/O as | |
| 35 | −needed. | |
| 36 | − | |
| 37 | −Next, recovery is performed in several stages. Most of the complexity | |
| 38 | −is forced by the need to handle multi-function devices, that is, | |
| 39 | −devices that have multiple device drivers associated with them. | |
| 40 | −In the first stage, each driver is allowed to indicate what type | |
| 41 | −of reset it desires, the choices being a simple re-enabling of I/O | |
| 42 | −or requesting a slot reset. | |
| 43 | − | |
| 44 | −If any driver requests a slot reset, that is what will be done. | |
| 45 | − | |
| 46 | −After a reset and/or a re-enabling of I/O, all drivers are | |
| 47 | −again notified, so that they may then perform any device setup/config | |
| 48 | −that may be required. After these have all completed, a final | |
| 49 | −"resume normal operations" event is sent out. | |
| 50 | − | |
| 51 | −The biggest reason for choosing a kernel-based implementation rather | |
| 52 | −than a user-space implementation was the need to deal with bus | |
| 53 | −disconnects of PCI devices attached to storage media, and, in particular, | |
| 54 | −disconnects from devices holding the root file system. If the root | |
| 55 | −file system is disconnected, a user-space mechanism would have to go | |
| 56 | −through a large number of contortions to complete recovery. Almost all | |
| 57 | −of the current Linux file systems are not tolerant of disconnection | |
| 58 | −from/reconnection to their underlying block device. By contrast, | |
| 59 | −bus errors are easy to manage in the device driver. Indeed, most | |
| 60 | −device drivers already handle very similar recovery procedures; | |
| 61 | −for example, the SCSI-generic layer already provides significant | |
| 62 | −mechanisms for dealing with SCSI bus errors and SCSI bus resets. | |
| 63 | − | |
| 64 | − | |
| 65 | −Detailed Design | |
| 66 | −--------------- | |
| 67 | −Design and implementation details below, based on a chain of | |
| 68 | −public email discussions with Ben Herrenschmidt, circa 5 April 2005. | |
| 69 | − | |
| 70 | −The error recovery API support is exposed to the driver in the form of | |
| 71 | −a structure of function pointers pointed to by a new field in struct | |
| 72 | −pci_driver. A driver that fails to provide the structure is "non-aware", | |
| 73 | −and the actual recovery steps taken are platform dependent. The | |
| 74 | −arch/powerpc implementation will simulate a PCI hotplug remove/add. | |
| 75 | − | |
| 76 | −This structure has the form: | |
| 77 | −struct pci_error_handlers | |
| 78 | −{ | |
| 79 | − int (*error_detected)(struct pci_dev *dev, enum pci_channel_state); | |
| 80 | − int (*mmio_enabled)(struct pci_dev *dev); | |
| 81 | − int (*slot_reset)(struct pci_dev *dev); | |
| 82 | − void (*resume)(struct pci_dev *dev); | |
| 83 | −}; | |
| 84 | − | |
| 85 | −The possible channel states are: | |
| 86 | −enum pci_channel_state { | |
| 87 | − pci_channel_io_normal, /* I/O channel is in normal state */ | |
| 88 | − pci_channel_io_frozen, /* I/O to channel is blocked */ | |
| 89 | − pci_channel_io_perm_failure, /* PCI card is dead */ | |
| 90 | −}; | |
| 91 | − | |
| 92 | −Possible return values are: | |
| 93 | −enum pci_ers_result { | |
| 94 | − PCI_ERS_RESULT_NONE, /* no result/none/not supported in device driver */ | |
| 95 | − PCI_ERS_RESULT_CAN_RECOVER, /* Device driver can recover without slot reset */ | |
| 96 | − PCI_ERS_RESULT_NEED_RESET, /* Device driver wants slot to be reset. */ | |
| 97 | − PCI_ERS_RESULT_DISCONNECT, /* Device has completely failed, is unrecoverable */ | |
| 98 | − PCI_ERS_RESULT_RECOVERED, /* Device driver is fully recovered and operational */ | |
| 99 | −}; | |
| 100 | − | |
| 101 | −A driver does not have to implement all of these callbacks; however, | |
| 102 | −if it implements any, it must implement error_detected(). If a callback | |
| 103 | −is not implemented, the corresponding feature is considered unsupported. | |
| 104 | −For example, if mmio_enabled() and resume() aren't there, then it | |
| 105 | −is assumed that the driver is not doing any direct recovery and requires | |
| 106 | −a slot reset. Typically a driver will want to know about | |
| 107 | −a slot_reset(). | |
| 108 | − | |
| 109 | −The actual steps taken by a platform to recover from a PCI error | |
| 110 | −event will be platform-dependent, but will follow the general | |
| 111 | −sequence described below. | |
| 112 | − | |
| 113 | −STEP 0: Error Event | |
| 114 | −------------------- | |
| 115 | −A PCI bus error is detected by the PCI hardware. On powerpc, the slot | |
| 116 | −is isolated, in that all I/O is blocked: all reads return 0xffffffff, | |
| 117 | −all writes are ignored. | |
| 118 | − | |
| 119 | − | |
| 120 | −STEP 1: Notification | |
| 121 | −-------------------- | |
| 122 | −Platform calls the error_detected() callback on every instance of | |
| 123 | −every driver affected by the error. | |
| 124 | − | |
| 125 | −At this point, the device might not be accessible anymore, depending on | |
| 126 | −the platform (the slot will be isolated on powerpc). The driver may | |
| 127 | −already have "noticed" the error because of a failing I/O, but this | |
| 128 | −is the proper "synchronization point", that is, it gives the driver | |
| 129 | −a chance to cleanup, waiting for pending stuff (timers, whatever, etc...) | |
| 130 | −to complete; it can take semaphores, schedule, etc... everything but | |
| 131 | −touch the device. Within this function and after it returns, the driver | |
| 132 | −shouldn't do any new IOs. Called in task context. This is sort of a | |
| 133 | −"quiesce" point. See note about interrupts at the end of this doc. | |
| 134 | − | |
| 135 | −All drivers participating in this system must implement this call. | |
| 136 | −The driver must return one of the following result codes: | |
| 137 | − - PCI_ERS_RESULT_CAN_RECOVER: | |
| 138 | − Driver returns this if it thinks it might be able to recover | |
| 139 | − the HW by just banging IOs or if it wants to be given | |
| 140 | − a chance to extract some diagnostic information (see | |
| 141 | − mmio_enable, below). | |
| 142 | − - PCI_ERS_RESULT_NEED_RESET: | |
| 143 | − Driver returns this if it can't recover without a | |
| 144 | − slot reset. | |
| 145 | − - PCI_ERS_RESULT_DISCONNECT: | |
| 146 | − Driver returns this if it doesn't want to recover at all. | |
| 147 | − | |
| 148 | −The next step taken will depend on the result codes returned by the | |
| 149 | −drivers. | |
| 150 | − | |
| 151 | −If all drivers on the segment/slot return PCI_ERS_RESULT_CAN_RECOVER, | |
| 152 | −then the platform should re-enable IOs on the slot (or do nothing in | |
| 153 | −particular, if the platform doesn't isolate slots), and recovery | |
| 154 | −proceeds to STEP 2 (MMIO Enable). | |
| 155 | − | |
| 156 | −If any driver requested a slot reset (by returning PCI_ERS_RESULT_NEED_RESET), | |
| 157 | −then recovery proceeds to STEP 4 (Slot Reset). | |
| 158 | − | |
| 159 | −If the platform is unable to recover the slot, the next step | |
| 160 | −is STEP 6 (Permanent Failure). | |
| 161 | − | |
| 162 | −>>> The current powerpc implementation assumes that a device driver will | |
| 163 | −>>> *not* schedule or semaphore in this routine; the current powerpc | |
| 164 | −>>> implementation uses one kernel thread to notify all devices; | |
| 165 | −>>> thus, if one device sleeps/schedules, all devices are affected. | |
| 166 | −>>> Doing better requires complex multi-threaded logic in the error | |
| 167 | −>>> recovery implementation (e.g. waiting for all notification threads | |
| 168 | −>>> to "join" before proceeding with recovery.) This seems excessively | |
| 169 | −>>> complex and not worth implementing. | |
| 170 | − | |
| 171 | −>>> The current powerpc implementation doesn't much care if the device | |
| 172 | −>>> attempts I/O at this point, or not. I/O's will fail, returning | |
| 173 | −>>> a value of 0xff on read, and writes will be dropped. If more than | |
| 174 | −>>> EEH_MAX_FAILS I/O's are attempted to a frozen adapter, EEH | |
| 175 | −>>> assumes that the device driver has gone into an infinite loop | |
| 176 | −>>> and prints an error to syslog. A reboot is then required to | |
| 177 | −>>> get the device working again. | |
| 178 | − | |
| 179 | −STEP 2: MMIO Enabled | |
| 180 | −------------------- | |
| 181 | −The platform re-enables MMIO to the device (but typically not the | |
| 182 | −DMA), and then calls the mmio_enabled() callback on all affected | |
| 183 | −device drivers. | |
| 184 | − | |
| 185 | −This is the "early recovery" call. IOs are allowed again, but DMA is | |
| 186 | −not, with some restrictions. This is NOT a callback for the driver to | |
| 187 | −start operations again, only to peek/poke at the device, extract diagnostic | |
| 188 | −information, if any, and eventually do things like trigger a device local | |
| 189 | −reset or some such, but not restart operations. This callback is made if | |
| 190 | −all drivers on a segment agree that they can try to recover and if no automatic | |
| 191 | −link reset was performed by the HW. If the platform can't just re-enable IOs | |
| 192 | −without a slot reset or a link reset, it will not call this callback, and | |
| 193 | −instead will have gone directly to STEP 3 (Link Reset) or STEP 4 (Slot Reset) | |
| 194 | − | |
| 195 | −>>> The following is proposed; no platform implements this yet: | |
| 196 | −>>> Proposal: All I/O's should be done _synchronously_ from within | |
| 197 | −>>> this callback, errors triggered by them will be returned via | |
| 198 | −>>> the normal pci_check_whatever() API, no new error_detected() | |
| 199 | −>>> callback will be issued due to an error happening here. However, | |
| 200 | −>>> such an error might cause IOs to be re-blocked for the whole | |
| 201 | −>>> segment, and thus invalidate the recovery that other devices | |
| 202 | −>>> on the same segment might have done, forcing the whole segment | |
| 203 | −>>> into one of the next states, that is, link reset or slot reset. | |
| 204 | − | |
| 205 | −The driver should return one of the following result codes: | |
| 206 | − - PCI_ERS_RESULT_RECOVERED | |
| 207 | − Driver returns this if it thinks the device is fully | |
| 208 | − functional and thinks it is ready to start | |
| 209 | − normal driver operations again. There is no | |
| 210 | − guarantee that the driver will actually be | |
| 211 | − allowed to proceed, as another driver on the | |
| 212 | − same segment might have failed and thus triggered a | |
| 213 | − slot reset on platforms that support it. | |
| 214 | − | |
| 215 | − - PCI_ERS_RESULT_NEED_RESET | |
| 216 | − Driver returns this if it thinks the device is not | |
| 217 | − recoverable in its current state and it needs a slot | |
| 218 | − reset to proceed. | |
| 219 | − | |
| 220 | − - PCI_ERS_RESULT_DISCONNECT | |
| 221 | − Same as above. Total failure, no recovery even after | |
| 222 | − reset driver dead. (To be defined more precisely) | |
| 223 | − | |
| 224 | −The next step taken depends on the results returned by the drivers. | |
| 225 | −If all drivers returned PCI_ERS_RESULT_RECOVERED, then the platform | |
| 226 | −proceeds to either STEP3 (Link Reset) or to STEP 5 (Resume Operations). | |
| 227 | − | |
| 228 | −If any driver returned PCI_ERS_RESULT_NEED_RESET, then the platform | |
| 229 | −proceeds to STEP 4 (Slot Reset) | |
| 230 | − | |
| 231 | −STEP 3: Link Reset | |
| 232 | −------------------ | |
| 233 | −The platform resets the link. This is a PCI-Express specific step | |
| 234 | −and is done whenever a fatal error has been detected that can be | |
| 235 | −"solved" by resetting the link. | |
| 236 | − | |
| 237 | −STEP 4: Slot Reset | |
| 238 | −------------------ | |
| 239 | − | |
| 240 | −In response to a return value of PCI_ERS_RESULT_NEED_RESET, the | |
| 241 | −the platform will perform a slot reset on the requesting PCI device(s). | |
| 242 | −The actual steps taken by a platform to perform a slot reset | |
| 243 | −will be platform-dependent. Upon completion of slot reset, the | |
| 244 | −platform will call the device slot_reset() callback. | |
| 245 | − | |
| 246 | −Powerpc platforms implement two levels of slot reset: | |
| 247 | −soft reset(default) and fundamental(optional) reset. | |
| 248 | − | |
| 249 | −Powerpc soft reset consists of asserting the adapter #RST line and then | |
| 250 | −restoring the PCI BAR's and PCI configuration header to a state | |
| 251 | −that is equivalent to what it would be after a fresh system | |
| 252 | −power-on followed by power-on BIOS/system firmware initialization. | |
| 253 | −Soft reset is also known as hot-reset. | |
| 254 | − | |
| 255 | −Powerpc fundamental reset is supported by PCI Express cards only | |
| 256 | −and results in device's state machines, hardware logic, port states and | |
| 257 | −configuration registers to initialize to their default conditions. | |
| 258 | − | |
| 259 | −For most PCI devices, a soft reset will be sufficient for recovery. | |
| 260 | −Optional fundamental reset is provided to support a limited number | |
| 261 | −of PCI Express devices for which a soft reset is not sufficient | |
| 262 | −for recovery. | |
| 263 | − | |
| 264 | −If the platform supports PCI hotplug, then the reset might be | |
| 265 | −performed by toggling the slot electrical power off/on. | |
| 266 | − | |
| 267 | −It is important for the platform to restore the PCI config space | |
| 268 | −to the "fresh poweron" state, rather than the "last state". After | |
| 269 | −a slot reset, the device driver will almost always use its standard | |
| 270 | −device initialization routines, and an unusual config space setup | |
| 271 | −may result in hung devices, kernel panics, or silent data corruption. | |
| 272 | − | |
| 273 | −This call gives drivers the chance to re-initialize the hardware | |
| 274 | −(re-download firmware, etc.). At this point, the driver may assume | |
| 275 | −that the card is in a fresh state and is fully functional. The slot | |
| 276 | −is unfrozen and the driver has full access to PCI config space, | |
| 277 | −memory mapped I/O space and DMA. Interrupts (Legacy, MSI, or MSI-X) | |
| 278 | −will also be available. | |
| 279 | − | |
| 280 | −Drivers should not restart normal I/O processing operations | |
| 281 | −at this point. If all device drivers report success on this | |
| 282 | −callback, the platform will call resume() to complete the sequence, | |
| 283 | −and let the driver restart normal I/O processing. | |
| 284 | − | |
| 285 | −A driver can still return a critical failure for this function if | |
| 286 | −it can't get the device operational after reset. If the platform | |
| 287 | −previously tried a soft reset, it might now try a hard reset (power | |
| 288 | −cycle) and then call slot_reset() again. It the device still can't | |
| 289 | −be recovered, there is nothing more that can be done; the platform | |
| 290 | −will typically report a "permanent failure" in such a case. The | |
| 291 | −device will be considered "dead" in this case. | |
| 292 | − | |
| 293 | −Drivers for multi-function cards will need to coordinate among | |
| 294 | −themselves as to which driver instance will perform any "one-shot" | |
| 295 | −or global device initialization. For example, the Symbios sym53cxx2 | |
| 296 | −driver performs device init only from PCI function 0: | |
| 297 | − | |
| 298 | −+ if (PCI_FUNC(pdev->devfn) == 0) | |
| 299 | −+ sym_reset_scsi_bus(np, 0); | |
| 300 | − | |
| 301 | − Result codes: | |
| 302 | − - PCI_ERS_RESULT_DISCONNECT | |
| 303 | − Same as above. | |
| 304 | − | |
| 305 | −Drivers for PCI Express cards that require a fundamental reset must | |
| 306 | −set the needs_freset bit in the pci_dev structure in their probe function. | |
| 307 | −For example, the QLogic qla2xxx driver sets the needs_freset bit for certain | |
| 308 | −PCI card types: | |
| 309 | − | |
| 310 | −+ /* Set EEH reset type to fundamental if required by hba */ | |
| 311 | −+ if (IS_QLA24XX(ha) || IS_QLA25XX(ha) || IS_QLA81XX(ha)) | |
| 312 | −+ pdev->needs_freset = 1; | |
| 313 | −+ | |
| 314 | − | |
| 315 | −Platform proceeds either to STEP 5 (Resume Operations) or STEP 6 (Permanent | |
| 316 | −Failure). | |
| 317 | − | |
| 318 | −>>> The current powerpc implementation does not try a power-cycle | |
| 319 | −>>> reset if the driver returned PCI_ERS_RESULT_DISCONNECT. | |
| 320 | −>>> However, it probably should. | |
| 321 | − | |
| 322 | − | |
| 323 | −STEP 5: Resume Operations | |
| 324 | −------------------------- | |
| 325 | −The platform will call the resume() callback on all affected device | |
| 326 | −drivers if all drivers on the segment have returned | |
| 327 | −PCI_ERS_RESULT_RECOVERED from one of the 3 previous callbacks. | |
| 328 | −The goal of this callback is to tell the driver to restart activity, | |
| 329 | −that everything is back and running. This callback does not return | |
| 330 | −a result code. | |
| 331 | − | |
| 332 | −At this point, if a new error happens, the platform will restart | |
| 333 | −a new error recovery sequence. | |
| 334 | − | |
| 335 | −STEP 6: Permanent Failure | |
| 336 | −------------------------- | |
| 337 | −A "permanent failure" has occurred, and the platform cannot recover | |
| 338 | −the device. The platform will call error_detected() with a | |
| 339 | −pci_channel_state value of pci_channel_io_perm_failure. | |
| 340 | − | |
| 341 | −The device driver should, at this point, assume the worst. It should | |
| 342 | −cancel all pending I/O, refuse all new I/O, returning -EIO to | |
| 343 | −higher layers. The device driver should then clean up all of its | |
| 344 | −memory and remove itself from kernel operations, much as it would | |
| 345 | −during system shutdown. | |
| 346 | − | |
| 347 | −The platform will typically notify the system operator of the | |
| 348 | −permanent failure in some way. If the device is hotplug-capable, | |
| 349 | −the operator will probably want to remove and replace the device. | |
| 350 | −Note, however, not all failures are truly "permanent". Some are | |
| 351 | −caused by over-heating, some by a poorly seated card. Many | |
| 352 | −PCI error events are caused by software bugs, e.g. DMA's to | |
| 353 | −wild addresses or bogus split transactions due to programming | |
| 354 | −errors. See the discussion in powerpc/eeh-pci-error-recovery.txt | |
| 355 | −for additional detail on real-life experience of the causes of | |
| 356 | −software errors. | |
| 357 | − | |
| 358 | − | |
| 359 | −Conclusion; General Remarks | |
| 360 | −--------------------------- | |
| 361 | −The way the callbacks are called is platform policy. A platform with | |
| 362 | −no slot reset capability may want to just "ignore" drivers that can't | |
| 363 | −recover (disconnect them) and try to let other cards on the same segment | |
| 364 | −recover. Keep in mind that in most real life cases, though, there will | |
| 365 | −be only one driver per segment. | |
| 366 | − | |
| 367 | −Now, a note about interrupts. If you get an interrupt and your | |
| 368 | −device is dead or has been isolated, there is a problem :) | |
| 369 | −The current policy is to turn this into a platform policy. | |
| 370 | −That is, the recovery API only requires that: | |
| 371 | − | |
| 372 | − - There is no guarantee that interrupt delivery can proceed from any | |
| 373 | −device on the segment starting from the error detection and until the | |
| 374 | −slot_reset callback is called, at which point interrupts are expected | |
| 375 | −to be fully operational. | |
| 376 | − | |
| 377 | − - There is no guarantee that interrupt delivery is stopped, that is, | |
| 378 | −a driver that gets an interrupt after detecting an error, or that detects | |
| 379 | −an error within the interrupt handler such that it prevents proper | |
| 380 | −ack'ing of the interrupt (and thus removal of the source) should just | |
| 381 | −return IRQ_NOTHANDLED. It's up to the platform to deal with that | |
| 382 | −condition, typically by masking the IRQ source during the duration of | |
| 383 | −the error handling. It is expected that the platform "knows" which | |
| 384 | −interrupts are routed to error-management capable slots and can deal | |
| 385 | −with temporarily disabling that IRQ number during error processing (this | |
| 386 | −isn't terribly complex). That means some IRQ latency for other devices | |
| 387 | −sharing the interrupt, but there is simply no other way. High end | |
| 388 | −platforms aren't supposed to share interrupts between many devices | |
| 389 | −anyway :) | |
| 390 | − | |
| 391 | −>>> Implementation details for the powerpc platform are discussed in | |
| 392 | −>>> the file Documentation/powerpc/eeh-pci-error-recovery.txt | |
| 393 | − | |
| 394 | −>>> As of this writing, there is a growing list of device drivers with | |
| 395 | −>>> patches implementing error recovery. Not all of these patches are in | |
| 396 | −>>> mainline yet. These may be used as "examples": | |
| 397 | −>>> | |
| 398 | −>>> drivers/scsi/ipr | |
| 399 | −>>> drivers/scsi/sym53c8xx_2 | |
| 400 | −>>> drivers/scsi/qla2xxx | |
| 401 | −>>> drivers/scsi/lpfc | |
| 402 | −>>> drivers/next/bnx2.c | |
| 403 | −>>> drivers/next/e100.c | |
| 404 | −>>> drivers/net/e1000 | |
| 405 | −>>> drivers/net/e1000e | |
| 406 | −>>> drivers/net/ixgb | |
| 407 | −>>> drivers/net/ixgbe | |
| 408 | −>>> drivers/net/cxgb3 | |
| 409 | −>>> drivers/net/s2io.c | |
| 410 | −>>> drivers/net/qlge | |
| 411 | − | |
| 412 | −The End | |
| 413 | −------- | |
| @@ -0,0 +1,172 @@ | ||
| 1 | +.. SPDX-License-Identifier: GPL-2.0 | |
| 2 | +.. include:: <isonum.txt> | |
| 3 | + | |
| 4 | +==================================== | |
| 5 | +PCI Express I/O Virtualization Howto | |
| 6 | +==================================== | |
| 7 | + | |
| 8 | +:Copyright: |copy| 2009 Intel Corporation | |
| 9 | +:Authors: - Yu Zhao <yu.zhao@intel.com> | |
| 10 | + - Donald Dutile <ddutile@redhat.com> | |
| 11 | + | |
| 12 | +Overview | |
| 13 | +======== | |
| 14 | + | |
| 15 | +What is SR-IOV | |
| 16 | +-------------- | |
| 17 | + | |
| 18 | +Single Root I/O Virtualization (SR-IOV) is a PCI Express Extended | |
| 19 | +capability which makes one physical device appear as multiple virtual | |
| 20 | +devices. The physical device is referred to as Physical Function (PF) | |
| 21 | +while the virtual devices are referred to as Virtual Functions (VF). | |
| 22 | +Allocation of the VF can be dynamically controlled by the PF via | |
| 23 | +registers encapsulated in the capability. By default, this feature is | |
| 24 | +not enabled and the PF behaves as traditional PCIe device. Once it's | |
| 25 | +turned on, each VF's PCI configuration space can be accessed by its own | |
| 26 | +Bus, Device and Function Number (Routing ID). And each VF also has PCI | |
| 27 | +Memory Space, which is used to map its register set. VF device driver | |
| 28 | +operates on the register set so it can be functional and appear as a | |
| 29 | +real existing PCI device. | |
| 30 | + | |
| 31 | +User Guide | |
| 32 | +========== | |
| 33 | + | |
| 34 | +How can I enable SR-IOV capability | |
| 35 | +---------------------------------- | |
| 36 | + | |
| 37 | +Multiple methods are available for SR-IOV enablement. | |
| 38 | +In the first method, the device driver (PF driver) will control the | |
| 39 | +enabling and disabling of the capability via API provided by SR-IOV core. | |
| 40 | +If the hardware has SR-IOV capability, loading its PF driver would | |
| 41 | +enable it and all VFs associated with the PF. Some PF drivers require | |
| 42 | +a module parameter to be set to determine the number of VFs to enable. | |
| 43 | +In the second method, a write to the sysfs file sriov_numvfs will | |
| 44 | +enable and disable the VFs associated with a PCIe PF. This method | |
| 45 | +enables per-PF, VF enable/disable values versus the first method, | |
| 46 | +which applies to all PFs of the same device. Additionally, the | |
| 47 | +PCI SRIOV core support ensures that enable/disable operations are | |
| 48 | +valid to reduce duplication in multiple drivers for the same | |
| 49 | +checks, e.g., check numvfs == 0 if enabling VFs, ensure | |
| 50 | +numvfs <= totalvfs. | |
| 51 | +The second method is the recommended method for new/future VF devices. | |
| 52 | + | |
| 53 | +How can I use the Virtual Functions | |
| 54 | +----------------------------------- | |
| 55 | + | |
| 56 | +The VF is treated as hot-plugged PCI devices in the kernel, so they | |
| 57 | +should be able to work in the same way as real PCI devices. The VF | |
| 58 | +requires device driver that is same as a normal PCI device's. | |
| 59 | + | |
| 60 | +Developer Guide | |
| 61 | +=============== | |
| 62 | + | |
| 63 | +SR-IOV API | |
| 64 | +---------- | |
| 65 | + | |
| 66 | +To enable SR-IOV capability: | |
| 67 | + | |
| 68 | +(a) For the first method, in the driver:: | |
| 69 | + | |
| 70 | + int pci_enable_sriov(struct pci_dev *dev, int nr_virtfn); | |
| 71 | + | |
| 72 | +'nr_virtfn' is number of VFs to be enabled. | |
| 73 | + | |
| 74 | +(b) For the second method, from sysfs:: | |
| 75 | + | |
| 76 | + echo 'nr_virtfn' > \ | |
| 77 | + /sys/bus/pci/devices/<DOMAIN:BUS:DEVICE.FUNCTION>/sriov_numvfs | |
| 78 | + | |
| 79 | +To disable SR-IOV capability: | |
| 80 | + | |
| 81 | +(a) For the first method, in the driver:: | |
| 82 | + | |
| 83 | + void pci_disable_sriov(struct pci_dev *dev); | |
| 84 | + | |
| 85 | +(b) For the second method, from sysfs:: | |
| 86 | + | |
| 87 | + echo 0 > \ | |
| 88 | + /sys/bus/pci/devices/<DOMAIN:BUS:DEVICE.FUNCTION>/sriov_numvfs | |
| 89 | + | |
| 90 | +To enable auto probing VFs by a compatible driver on the host, run | |
| 91 | +command below before enabling SR-IOV capabilities. This is the | |
| 92 | +default behavior. | |
| 93 | +:: | |
| 94 | + | |
| 95 | + echo 1 > \ | |
| 96 | + /sys/bus/pci/devices/<DOMAIN:BUS:DEVICE.FUNCTION>/sriov_drivers_autoprobe | |
| 97 | + | |
| 98 | +To disable auto probing VFs by a compatible driver on the host, run | |
| 99 | +command below before enabling SR-IOV capabilities. Updating this | |
| 100 | +entry will not affect VFs which are already probed. | |
| 101 | +:: | |
| 102 | + | |
| 103 | + echo 0 > \ | |
| 104 | + /sys/bus/pci/devices/<DOMAIN:BUS:DEVICE.FUNCTION>/sriov_drivers_autoprobe | |
| 105 | + | |
| 106 | +Usage example | |
| 107 | +------------- | |
| 108 | + | |
| 109 | +Following piece of code illustrates the usage of the SR-IOV API. | |
| 110 | +:: | |
| 111 | + | |
| 112 | + static int dev_probe(struct pci_dev *dev, const struct pci_device_id *id) | |
| 113 | + { | |
| 114 | + pci_enable_sriov(dev, NR_VIRTFN); | |
| 115 | + | |
| 116 | + ... | |
| 117 | + | |
| 118 | + return 0; | |
| 119 | + } | |
| 120 | + | |
| 121 | + static void dev_remove(struct pci_dev *dev) | |
| 122 | + { | |
| 123 | + pci_disable_sriov(dev); | |
| 124 | + | |
| 125 | + ... | |
| 126 | + } | |
| 127 | + | |
| 128 | + static int dev_suspend(struct pci_dev *dev, pm_message_t state) | |
| 129 | + { | |
| 130 | + ... | |
| 131 | + | |
| 132 | + return 0; | |
| 133 | + } | |
| 134 | + | |
| 135 | + static int dev_resume(struct pci_dev *dev) | |
| 136 | + { | |
| 137 | + ... | |
| 138 | + | |
| 139 | + return 0; | |
| 140 | + } | |
| 141 | + | |
| 142 | + static void dev_shutdown(struct pci_dev *dev) | |
| 143 | + { | |
| 144 | + ... | |
| 145 | + } | |
| 146 | + | |
| 147 | + static int dev_sriov_configure(struct pci_dev *dev, int numvfs) | |
| 148 | + { | |
| 149 | + if (numvfs > 0) { | |
| 150 | + ... | |
| 151 | + pci_enable_sriov(dev, numvfs); | |
| 152 | + ... | |
| 153 | + return numvfs; | |
| 154 | + } | |
| 155 | + if (numvfs == 0) { | |
| 156 | + .... | |
| 157 | + pci_disable_sriov(dev); | |
| 158 | + ... | |
| 159 | + return 0; | |
| 160 | + } | |
| 161 | + } | |
| 162 | + | |
| 163 | + static struct pci_driver dev_driver = { | |
| 164 | + .name = "SR-IOV Physical Function driver", | |
| 165 | + .id_table = dev_id_table, | |
| 166 | + .probe = dev_probe, | |
| 167 | + .remove = dev_remove, | |
| 168 | + .suspend = dev_suspend, | |
| 169 | + .resume = dev_resume, | |
| 170 | + .shutdown = dev_shutdown, | |
| 171 | + .sriov_configure = dev_sriov_configure, | |
| 172 | + }; | |
| @@ -1,147 +0,0 @@ | ||
| 1 | − PCI Express I/O Virtualization Howto | |
| 2 | − Copyright (C) 2009 Intel Corporation | |
| 3 | − Yu Zhao <yu.zhao@intel.com> | |
| 4 | − | |
| 5 | − Update: November 2012 | |
| 6 | − -- sysfs-based SRIOV enable-/disable-ment | |
| 7 | − Donald Dutile <ddutile@redhat.com> | |
| 8 | − | |
| 9 | −1. Overview | |
| 10 | − | |
| 11 | −1.1 What is SR-IOV | |
| 12 | − | |
| 13 | −Single Root I/O Virtualization (SR-IOV) is a PCI Express Extended | |
| 14 | −capability which makes one physical device appear as multiple virtual | |
| 15 | −devices. The physical device is referred to as Physical Function (PF) | |
| 16 | −while the virtual devices are referred to as Virtual Functions (VF). | |
| 17 | −Allocation of the VF can be dynamically controlled by the PF via | |
| 18 | −registers encapsulated in the capability. By default, this feature is | |
| 19 | −not enabled and the PF behaves as traditional PCIe device. Once it's | |
| 20 | −turned on, each VF's PCI configuration space can be accessed by its own | |
| 21 | −Bus, Device and Function Number (Routing ID). And each VF also has PCI | |
| 22 | −Memory Space, which is used to map its register set. VF device driver | |
| 23 | −operates on the register set so it can be functional and appear as a | |
| 24 | −real existing PCI device. | |
| 25 | − | |
| 26 | −2. User Guide | |
| 27 | − | |
| 28 | −2.1 How can I enable SR-IOV capability | |
| 29 | − | |
| 30 | −Multiple methods are available for SR-IOV enablement. | |
| 31 | −In the first method, the device driver (PF driver) will control the | |
| 32 | −enabling and disabling of the capability via API provided by SR-IOV core. | |
| 33 | −If the hardware has SR-IOV capability, loading its PF driver would | |
| 34 | −enable it and all VFs associated with the PF. Some PF drivers require | |
| 35 | −a module parameter to be set to determine the number of VFs to enable. | |
| 36 | −In the second method, a write to the sysfs file sriov_numvfs will | |
| 37 | −enable and disable the VFs associated with a PCIe PF. This method | |
| 38 | −enables per-PF, VF enable/disable values versus the first method, | |
| 39 | −which applies to all PFs of the same device. Additionally, the | |
| 40 | −PCI SRIOV core support ensures that enable/disable operations are | |
| 41 | −valid to reduce duplication in multiple drivers for the same | |
| 42 | −checks, e.g., check numvfs == 0 if enabling VFs, ensure | |
| 43 | −numvfs <= totalvfs. | |
| 44 | −The second method is the recommended method for new/future VF devices. | |
| 45 | − | |
| 46 | −2.2 How can I use the Virtual Functions | |
| 47 | − | |
| 48 | −The VF is treated as hot-plugged PCI devices in the kernel, so they | |
| 49 | −should be able to work in the same way as real PCI devices. The VF | |
| 50 | −requires device driver that is same as a normal PCI device's. | |
| 51 | − | |
| 52 | −3. Developer Guide | |
| 53 | − | |
| 54 | −3.1 SR-IOV API | |
| 55 | − | |
| 56 | −To enable SR-IOV capability: | |
| 57 | −(a) For the first method, in the driver: | |
| 58 | − int pci_enable_sriov(struct pci_dev *dev, int nr_virtfn); | |
| 59 | − 'nr_virtfn' is number of VFs to be enabled. | |
| 60 | −(b) For the second method, from sysfs: | |
| 61 | − echo 'nr_virtfn' > \ | |
| 62 | − /sys/bus/pci/devices/<DOMAIN:BUS:DEVICE.FUNCTION>/sriov_numvfs | |
| 63 | − | |
| 64 | −To disable SR-IOV capability: | |
| 65 | −(a) For the first method, in the driver: | |
| 66 | − void pci_disable_sriov(struct pci_dev *dev); | |
| 67 | −(b) For the second method, from sysfs: | |
| 68 | − echo 0 > \ | |
| 69 | − /sys/bus/pci/devices/<DOMAIN:BUS:DEVICE.FUNCTION>/sriov_numvfs | |
| 70 | − | |
| 71 | −To enable auto probing VFs by a compatible driver on the host, run | |
| 72 | −command below before enabling SR-IOV capabilities. This is the | |
| 73 | −default behavior. | |
| 74 | − echo 1 > \ | |
| 75 | − /sys/bus/pci/devices/<DOMAIN:BUS:DEVICE.FUNCTION>/sriov_drivers_autoprobe | |
| 76 | − | |
| 77 | −To disable auto probing VFs by a compatible driver on the host, run | |
| 78 | −command below before enabling SR-IOV capabilities. Updating this | |
| 79 | −entry will not affect VFs which are already probed. | |
| 80 | − echo 0 > \ | |
| 81 | − /sys/bus/pci/devices/<DOMAIN:BUS:DEVICE.FUNCTION>/sriov_drivers_autoprobe | |
| 82 | − | |
| 83 | −3.2 Usage example | |
| 84 | − | |
| 85 | −Following piece of code illustrates the usage of the SR-IOV API. | |
| 86 | − | |
| 87 | −static int dev_probe(struct pci_dev *dev, const struct pci_device_id *id) | |
| 88 | −{ | |
| 89 | − pci_enable_sriov(dev, NR_VIRTFN); | |
| 90 | − | |
| 91 | − ... | |
| 92 | − | |
| 93 | − return 0; | |
| 94 | −} | |
| 95 | − | |
| 96 | −static void dev_remove(struct pci_dev *dev) | |
| 97 | −{ | |
| 98 | − pci_disable_sriov(dev); | |
| 99 | − | |
| 100 | − ... | |
| 101 | −} | |
| 102 | − | |
| 103 | −static int dev_suspend(struct pci_dev *dev, pm_message_t state) | |
| 104 | −{ | |
| 105 | − ... | |
| 106 | − | |
| 107 | − return 0; | |
| 108 | −} | |
| 109 | − | |
| 110 | −static int dev_resume(struct pci_dev *dev) | |
| 111 | −{ | |
| 112 | − ... | |
| 113 | − | |
| 114 | − return 0; | |
| 115 | −} | |
| 116 | − | |
| 117 | −static void dev_shutdown(struct pci_dev *dev) | |
| 118 | −{ | |
| 119 | − ... | |
| 120 | −} | |
| 121 | − | |
| 122 | −static int dev_sriov_configure(struct pci_dev *dev, int numvfs) | |
| 123 | −{ | |
| 124 | − if (numvfs > 0) { | |
| 125 | − ... | |
| 126 | − pci_enable_sriov(dev, numvfs); | |
| 127 | − ... | |
| 128 | − return numvfs; | |
| 129 | − } | |
| 130 | − if (numvfs == 0) { | |
| 131 | − .... | |
| 132 | − pci_disable_sriov(dev); | |
| 133 | − ... | |
| 134 | − return 0; | |
| 135 | − } | |
| 136 | −} | |
| 137 | − | |
| 138 | −static struct pci_driver dev_driver = { | |
| 139 | − .name = "SR-IOV Physical Function driver", | |
| 140 | − .id_table = dev_id_table, | |
| 141 | − .probe = dev_probe, | |
| 142 | − .remove = dev_remove, | |
| 143 | − .suspend = dev_suspend, | |
| 144 | − .resume = dev_resume, | |
| 145 | − .shutdown = dev_shutdown, | |
| 146 | − .sriov_configure = dev_sriov_configure, | |
| 147 | −}; | |
| @@ -0,0 +1,578 @@ | ||
| 1 | +.. SPDX-License-Identifier: GPL-2.0 | |
| 2 | + | |
| 3 | +============================== | |
| 4 | +How To Write Linux PCI Drivers | |
| 5 | +============================== | |
| 6 | + | |
| 7 | +:Authors: - Martin Mares <mj@ucw.cz> | |
| 8 | + - Grant Grundler <grundler@parisc-linux.org> | |
| 9 | + | |
| 10 | +The world of PCI is vast and full of (mostly unpleasant) surprises. | |
| 11 | +Since each CPU architecture implements different chip-sets and PCI devices | |
| 12 | +have different requirements (erm, "features"), the result is the PCI support | |
| 13 | +in the Linux kernel is not as trivial as one would wish. This short paper | |
| 14 | +tries to introduce all potential driver authors to Linux APIs for | |
| 15 | +PCI device drivers. | |
| 16 | + | |
| 17 | +A more complete resource is the third edition of "Linux Device Drivers" | |
| 18 | +by Jonathan Corbet, Alessandro Rubini, and Greg Kroah-Hartman. | |
| 19 | +LDD3 is available for free (under Creative Commons License) from: | |
| 20 | +http://lwn.net/Kernel/LDD3/. | |
| 21 | + | |
| 22 | +However, keep in mind that all documents are subject to "bit rot". | |
| 23 | +Refer to the source code if things are not working as described here. | |
| 24 | + | |
| 25 | +Please send questions/comments/patches about Linux PCI API to the | |
| 26 | +"Linux PCI" <linux-pci@atrey.karlin.mff.cuni.cz> mailing list. | |
| 27 | + | |
| 28 | + | |
| 29 | +Structure of PCI drivers | |
| 30 | +======================== | |
| 31 | +PCI drivers "discover" PCI devices in a system via pci_register_driver(). | |
| 32 | +Actually, it's the other way around. When the PCI generic code discovers | |
| 33 | +a new device, the driver with a matching "description" will be notified. | |
| 34 | +Details on this below. | |
| 35 | + | |
| 36 | +pci_register_driver() leaves most of the probing for devices to | |
| 37 | +the PCI layer and supports online insertion/removal of devices [thus | |
| 38 | +supporting hot-pluggable PCI, CardBus, and Express-Card in a single driver]. | |
| 39 | +pci_register_driver() call requires passing in a table of function | |
| 40 | +pointers and thus dictates the high level structure of a driver. | |
| 41 | + | |
| 42 | +Once the driver knows about a PCI device and takes ownership, the | |
| 43 | +driver generally needs to perform the following initialization: | |
| 44 | + | |
| 45 | + - Enable the device | |
| 46 | + - Request MMIO/IOP resources | |
| 47 | + - Set the DMA mask size (for both coherent and streaming DMA) | |
| 48 | + - Allocate and initialize shared control data (pci_allocate_coherent()) | |
| 49 | + - Access device configuration space (if needed) | |
| 50 | + - Register IRQ handler (request_irq()) | |
| 51 | + - Initialize non-PCI (i.e. LAN/SCSI/etc parts of the chip) | |
| 52 | + - Enable DMA/processing engines | |
| 53 | + | |
| 54 | +When done using the device, and perhaps the module needs to be unloaded, | |
| 55 | +the driver needs to take the follow steps: | |
| 56 | + | |
| 57 | + - Disable the device from generating IRQs | |
| 58 | + - Release the IRQ (free_irq()) | |
| 59 | + - Stop all DMA activity | |
| 60 | + - Release DMA buffers (both streaming and coherent) | |
| 61 | + - Unregister from other subsystems (e.g. scsi or netdev) | |
| 62 | + - Release MMIO/IOP resources | |
| 63 | + - Disable the device | |
| 64 | + | |
| 65 | +Most of these topics are covered in the following sections. | |
| 66 | +For the rest look at LDD3 or <linux/pci.h> . | |
| 67 | + | |
| 68 | +If the PCI subsystem is not configured (CONFIG_PCI is not set), most of | |
| 69 | +the PCI functions described below are defined as inline functions either | |
| 70 | +completely empty or just returning an appropriate error codes to avoid | |
| 71 | +lots of ifdefs in the drivers. | |
| 72 | + | |
| 73 | + | |
| 74 | +pci_register_driver() call | |
| 75 | +========================== | |
| 76 | + | |
| 77 | +PCI device drivers call ``pci_register_driver()`` during their | |
| 78 | +initialization with a pointer to a structure describing the driver | |
| 79 | +(``struct pci_driver``): | |
| 80 | + | |
| 81 | +.. kernel-doc:: include/linux/pci.h | |
| 82 | + :functions: pci_driver | |
| 83 | + | |
| 84 | +The ID table is an array of ``struct pci_device_id`` entries ending with an | |
| 85 | +all-zero entry. Definitions with static const are generally preferred. | |
| 86 | + | |
| 87 | +.. kernel-doc:: include/linux/mod_devicetable.h | |
| 88 | + :functions: pci_device_id | |
| 89 | + | |
| 90 | +Most drivers only need ``PCI_DEVICE()`` or ``PCI_DEVICE_CLASS()`` to set up | |
| 91 | +a pci_device_id table. | |
| 92 | + | |
| 93 | +New PCI IDs may be added to a device driver pci_ids table at runtime | |
| 94 | +as shown below:: | |
| 95 | + | |
| 96 | + echo "vendor device subvendor subdevice class class_mask driver_data" > \ | |
| 97 | + /sys/bus/pci/drivers/{driver}/new_id | |
| 98 | + | |
| 99 | +All fields are passed in as hexadecimal values (no leading 0x). | |
| 100 | +The vendor and device fields are mandatory, the others are optional. Users | |
| 101 | +need pass only as many optional fields as necessary: | |
| 102 | + | |
| 103 | + - subvendor and subdevice fields default to PCI_ANY_ID (FFFFFFFF) | |
| 104 | + - class and classmask fields default to 0 | |
| 105 | + - driver_data defaults to 0UL. | |
| 106 | + | |
| 107 | +Note that driver_data must match the value used by any of the pci_device_id | |
| 108 | +entries defined in the driver. This makes the driver_data field mandatory | |
| 109 | +if all the pci_device_id entries have a non-zero driver_data value. | |
| 110 | + | |
| 111 | +Once added, the driver probe routine will be invoked for any unclaimed | |
| 112 | +PCI devices listed in its (newly updated) pci_ids list. | |
| 113 | + | |
| 114 | +When the driver exits, it just calls pci_unregister_driver() and the PCI layer | |
| 115 | +automatically calls the remove hook for all devices handled by the driver. | |
| 116 | + | |
| 117 | + | |
| 118 | +"Attributes" for driver functions/data | |
| 119 | +-------------------------------------- | |
| 120 | + | |
| 121 | +Please mark the initialization and cleanup functions where appropriate | |
| 122 | +(the corresponding macros are defined in <linux/init.h>): | |
| 123 | + | |
| 124 | + ====== ================================================= | |
| 125 | + __init Initialization code. Thrown away after the driver | |
| 126 | + initializes. | |
| 127 | + __exit Exit code. Ignored for non-modular drivers. | |
| 128 | + ====== ================================================= | |
| 129 | + | |
| 130 | +Tips on when/where to use the above attributes: | |
| 131 | + - The module_init()/module_exit() functions (and all | |
| 132 | + initialization functions called _only_ from these) | |
| 133 | + should be marked __init/__exit. | |
| 134 | + | |
| 135 | + - Do not mark the struct pci_driver. | |
| 136 | + | |
| 137 | + - Do NOT mark a function if you are not sure which mark to use. | |
| 138 | + Better to not mark the function than mark the function wrong. | |
| 139 | + | |
| 140 | + | |
| 141 | +How to find PCI devices manually | |
| 142 | +================================ | |
| 143 | + | |
| 144 | +PCI drivers should have a really good reason for not using the | |
| 145 | +pci_register_driver() interface to search for PCI devices. | |
| 146 | +The main reason PCI devices are controlled by multiple drivers | |
| 147 | +is because one PCI device implements several different HW services. | |
| 148 | +E.g. combined serial/parallel port/floppy controller. | |
| 149 | + | |
| 150 | +A manual search may be performed using the following constructs: | |
| 151 | + | |
| 152 | +Searching by vendor and device ID:: | |
| 153 | + | |
| 154 | + struct pci_dev *dev = NULL; | |
| 155 | + while (dev = pci_get_device(VENDOR_ID, DEVICE_ID, dev)) | |
| 156 | + configure_device(dev); | |
| 157 | + | |
| 158 | +Searching by class ID (iterate in a similar way):: | |
| 159 | + | |
| 160 | + pci_get_class(CLASS_ID, dev) | |
| 161 | + | |
| 162 | +Searching by both vendor/device and subsystem vendor/device ID:: | |
| 163 | + | |
| 164 | + pci_get_subsys(VENDOR_ID,DEVICE_ID, SUBSYS_VENDOR_ID, SUBSYS_DEVICE_ID, dev). | |
| 165 | + | |
| 166 | +You can use the constant PCI_ANY_ID as a wildcard replacement for | |
| 167 | +VENDOR_ID or DEVICE_ID. This allows searching for any device from a | |
| 168 | +specific vendor, for example. | |
| 169 | + | |
| 170 | +These functions are hotplug-safe. They increment the reference count on | |
| 171 | +the pci_dev that they return. You must eventually (possibly at module unload) | |
| 172 | +decrement the reference count on these devices by calling pci_dev_put(). | |
| 173 | + | |
| 174 | + | |
| 175 | +Device Initialization Steps | |
| 176 | +=========================== | |
| 177 | + | |
| 178 | +As noted in the introduction, most PCI drivers need the following steps | |
| 179 | +for device initialization: | |
| 180 | + | |
| 181 | + - Enable the device | |
| 182 | + - Request MMIO/IOP resources | |
| 183 | + - Set the DMA mask size (for both coherent and streaming DMA) | |
| 184 | + - Allocate and initialize shared control data (pci_allocate_coherent()) | |
| 185 | + - Access device configuration space (if needed) | |
| 186 | + - Register IRQ handler (request_irq()) | |
| 187 | + - Initialize non-PCI (i.e. LAN/SCSI/etc parts of the chip) | |
| 188 | + - Enable DMA/processing engines. | |
| 189 | + | |
| 190 | +The driver can access PCI config space registers at any time. | |
| 191 | +(Well, almost. When running BIST, config space can go away...but | |
| 192 | +that will just result in a PCI Bus Master Abort and config reads | |
| 193 | +will return garbage). | |
| 194 | + | |
| 195 | + | |
| 196 | +Enable the PCI device | |
| 197 | +--------------------- | |
| 198 | +Before touching any device registers, the driver needs to enable | |
| 199 | +the PCI device by calling pci_enable_device(). This will: | |
| 200 | + | |
| 201 | + - wake up the device if it was in suspended state, | |
| 202 | + - allocate I/O and memory regions of the device (if BIOS did not), | |
| 203 | + - allocate an IRQ (if BIOS did not). | |
| 204 | + | |
| 205 | +.. note:: | |
| 206 | + pci_enable_device() can fail! Check the return value. | |
| 207 | + | |
| 208 | +.. warning:: | |
| 209 | + OS BUG: we don't check resource allocations before enabling those | |
| 210 | + resources. The sequence would make more sense if we called | |
| 211 | + pci_request_resources() before calling pci_enable_device(). | |
| 212 | + Currently, the device drivers can't detect the bug when when two | |
| 213 | + devices have been allocated the same range. This is not a common | |
| 214 | + problem and unlikely to get fixed soon. | |
| 215 | + | |
| 216 | + This has been discussed before but not changed as of 2.6.19: | |
| 217 | + http://lkml.org/lkml/2006/3/2/194 | |
| 218 | + | |
| 219 | + | |
| 220 | +pci_set_master() will enable DMA by setting the bus master bit | |
| 221 | +in the PCI_COMMAND register. It also fixes the latency timer value if | |
| 222 | +it's set to something bogus by the BIOS. pci_clear_master() will | |
| 223 | +disable DMA by clearing the bus master bit. | |
| 224 | + | |
| 225 | +If the PCI device can use the PCI Memory-Write-Invalidate transaction, | |
| 226 | +call pci_set_mwi(). This enables the PCI_COMMAND bit for Mem-Wr-Inval | |
| 227 | +and also ensures that the cache line size register is set correctly. | |
| 228 | +Check the return value of pci_set_mwi() as not all architectures | |
| 229 | +or chip-sets may support Memory-Write-Invalidate. Alternatively, | |
| 230 | +if Mem-Wr-Inval would be nice to have but is not required, call | |
| 231 | +pci_try_set_mwi() to have the system do its best effort at enabling | |
| 232 | +Mem-Wr-Inval. | |
| 233 | + | |
| 234 | + | |
| 235 | +Request MMIO/IOP resources | |
| 236 | +-------------------------- | |
| 237 | +Memory (MMIO), and I/O port addresses should NOT be read directly | |
| 238 | +from the PCI device config space. Use the values in the pci_dev structure | |
| 239 | +as the PCI "bus address" might have been remapped to a "host physical" | |
| 240 | +address by the arch/chip-set specific kernel support. | |
| 241 | + | |
| 242 | +See Documentation/io-mapping.txt for how to access device registers | |
| 243 | +or device memory. | |
| 244 | + | |
| 245 | +The device driver needs to call pci_request_region() to verify | |
| 246 | +no other device is already using the same address resource. | |
| 247 | +Conversely, drivers should call pci_release_region() AFTER | |
| 248 | +calling pci_disable_device(). | |
| 249 | +The idea is to prevent two devices colliding on the same address range. | |
| 250 | + | |
| 251 | +.. tip:: | |
| 252 | + See OS BUG comment above. Currently (2.6.19), The driver can only | |
| 253 | + determine MMIO and IO Port resource availability _after_ calling | |
| 254 | + pci_enable_device(). | |
| 255 | + | |
| 256 | +Generic flavors of pci_request_region() are request_mem_region() | |
| 257 | +(for MMIO ranges) and request_region() (for IO Port ranges). | |
| 258 | +Use these for address resources that are not described by "normal" PCI | |
| 259 | +BARs. | |
| 260 | + | |
| 261 | +Also see pci_request_selected_regions() below. | |
| 262 | + | |
| 263 | + | |
| 264 | +Set the DMA mask size | |
| 265 | +--------------------- | |
| 266 | +.. note:: | |
| 267 | + If anything below doesn't make sense, please refer to | |
| 268 | + Documentation/DMA-API.txt. This section is just a reminder that | |
| 269 | + drivers need to indicate DMA capabilities of the device and is not | |
| 270 | + an authoritative source for DMA interfaces. | |
| 271 | + | |
| 272 | +While all drivers should explicitly indicate the DMA capability | |
| 273 | +(e.g. 32 or 64 bit) of the PCI bus master, devices with more than | |
| 274 | +32-bit bus master capability for streaming data need the driver | |
| 275 | +to "register" this capability by calling pci_set_dma_mask() with | |
| 276 | +appropriate parameters. In general this allows more efficient DMA | |
| 277 | +on systems where System RAM exists above 4G _physical_ address. | |
| 278 | + | |
| 279 | +Drivers for all PCI-X and PCIe compliant devices must call | |
| 280 | +pci_set_dma_mask() as they are 64-bit DMA devices. | |
| 281 | + | |
| 282 | +Similarly, drivers must also "register" this capability if the device | |
| 283 | +can directly address "consistent memory" in System RAM above 4G physical | |
| 284 | +address by calling pci_set_consistent_dma_mask(). | |
| 285 | +Again, this includes drivers for all PCI-X and PCIe compliant devices. | |
| 286 | +Many 64-bit "PCI" devices (before PCI-X) and some PCI-X devices are | |
| 287 | +64-bit DMA capable for payload ("streaming") data but not control | |
| 288 | +("consistent") data. | |
| 289 | + | |
| 290 | + | |
| 291 | +Setup shared control data | |
| 292 | +------------------------- | |
| 293 | +Once the DMA masks are set, the driver can allocate "consistent" (a.k.a. shared) | |
| 294 | +memory. See Documentation/DMA-API.txt for a full description of | |
| 295 | +the DMA APIs. This section is just a reminder that it needs to be done | |
| 296 | +before enabling DMA on the device. | |
| 297 | + | |
| 298 | + | |
| 299 | +Initialize device registers | |
| 300 | +--------------------------- | |
| 301 | +Some drivers will need specific "capability" fields programmed | |
| 302 | +or other "vendor specific" register initialized or reset. | |
| 303 | +E.g. clearing pending interrupts. | |
| 304 | + | |
| 305 | + | |
| 306 | +Register IRQ handler | |
| 307 | +-------------------- | |
| 308 | +While calling request_irq() is the last step described here, | |
| 309 | +this is often just another intermediate step to initialize a device. | |
| 310 | +This step can often be deferred until the device is opened for use. | |
| 311 | + | |
| 312 | +All interrupt handlers for IRQ lines should be registered with IRQF_SHARED | |
| 313 | +and use the devid to map IRQs to devices (remember that all PCI IRQ lines | |
| 314 | +can be shared). | |
| 315 | + | |
| 316 | +request_irq() will associate an interrupt handler and device handle | |
| 317 | +with an interrupt number. Historically interrupt numbers represent | |
| 318 | +IRQ lines which run from the PCI device to the Interrupt controller. | |
| 319 | +With MSI and MSI-X (more below) the interrupt number is a CPU "vector". | |
| 320 | + | |
| 321 | +request_irq() also enables the interrupt. Make sure the device is | |
| 322 | +quiesced and does not have any interrupts pending before registering | |
| 323 | +the interrupt handler. | |
| 324 | + | |
| 325 | +MSI and MSI-X are PCI capabilities. Both are "Message Signaled Interrupts" | |
| 326 | +which deliver interrupts to the CPU via a DMA write to a Local APIC. | |
| 327 | +The fundamental difference between MSI and MSI-X is how multiple | |
| 328 | +"vectors" get allocated. MSI requires contiguous blocks of vectors | |
| 329 | +while MSI-X can allocate several individual ones. | |
| 330 | + | |
| 331 | +MSI capability can be enabled by calling pci_alloc_irq_vectors() with the | |
| 332 | +PCI_IRQ_MSI and/or PCI_IRQ_MSIX flags before calling request_irq(). This | |
| 333 | +causes the PCI support to program CPU vector data into the PCI device | |
| 334 | +capability registers. Many architectures, chip-sets, or BIOSes do NOT | |
| 335 | +support MSI or MSI-X and a call to pci_alloc_irq_vectors with just | |
| 336 | +the PCI_IRQ_MSI and PCI_IRQ_MSIX flags will fail, so try to always | |
| 337 | +specify PCI_IRQ_LEGACY as well. | |
| 338 | + | |
| 339 | +Drivers that have different interrupt handlers for MSI/MSI-X and | |
| 340 | +legacy INTx should chose the right one based on the msi_enabled | |
| 341 | +and msix_enabled flags in the pci_dev structure after calling | |
| 342 | +pci_alloc_irq_vectors. | |
| 343 | + | |
| 344 | +There are (at least) two really good reasons for using MSI: | |
| 345 | + | |
| 346 | +1) MSI is an exclusive interrupt vector by definition. | |
| 347 | + This means the interrupt handler doesn't have to verify | |
| 348 | + its device caused the interrupt. | |
| 349 | + | |
| 350 | +2) MSI avoids DMA/IRQ race conditions. DMA to host memory is guaranteed | |
| 351 | + to be visible to the host CPU(s) when the MSI is delivered. This | |
| 352 | + is important for both data coherency and avoiding stale control data. | |
| 353 | + This guarantee allows the driver to omit MMIO reads to flush | |
| 354 | + the DMA stream. | |
| 355 | + | |
| 356 | +See drivers/infiniband/hw/mthca/ or drivers/net/tg3.c for examples | |
| 357 | +of MSI/MSI-X usage. | |
| 358 | + | |
| 359 | + | |
| 360 | +PCI device shutdown | |
| 361 | +=================== | |
| 362 | + | |
| 363 | +When a PCI device driver is being unloaded, most of the following | |
| 364 | +steps need to be performed: | |
| 365 | + | |
| 366 | + - Disable the device from generating IRQs | |
| 367 | + - Release the IRQ (free_irq()) | |
| 368 | + - Stop all DMA activity | |
| 369 | + - Release DMA buffers (both streaming and consistent) | |
| 370 | + - Unregister from other subsystems (e.g. scsi or netdev) | |
| 371 | + - Disable device from responding to MMIO/IO Port addresses | |
| 372 | + - Release MMIO/IO Port resource(s) | |
| 373 | + | |
| 374 | + | |
| 375 | +Stop IRQs on the device | |
| 376 | +----------------------- | |
| 377 | +How to do this is chip/device specific. If it's not done, it opens | |
| 378 | +the possibility of a "screaming interrupt" if (and only if) | |
| 379 | +the IRQ is shared with another device. | |
| 380 | + | |
| 381 | +When the shared IRQ handler is "unhooked", the remaining devices | |
| 382 | +using the same IRQ line will still need the IRQ enabled. Thus if the | |
| 383 | +"unhooked" device asserts IRQ line, the system will respond assuming | |
| 384 | +it was one of the remaining devices asserted the IRQ line. Since none | |
| 385 | +of the other devices will handle the IRQ, the system will "hang" until | |
| 386 | +it decides the IRQ isn't going to get handled and masks the IRQ (100,000 | |
| 387 | +iterations later). Once the shared IRQ is masked, the remaining devices | |
| 388 | +will stop functioning properly. Not a nice situation. | |
| 389 | + | |
| 390 | +This is another reason to use MSI or MSI-X if it's available. | |
| 391 | +MSI and MSI-X are defined to be exclusive interrupts and thus | |
| 392 | +are not susceptible to the "screaming interrupt" problem. | |
| 393 | + | |
| 394 | + | |
| 395 | +Release the IRQ | |
| 396 | +--------------- | |
| 397 | +Once the device is quiesced (no more IRQs), one can call free_irq(). | |
| 398 | +This function will return control once any pending IRQs are handled, | |
| 399 | +"unhook" the drivers IRQ handler from that IRQ, and finally release | |
| 400 | +the IRQ if no one else is using it. | |
| 401 | + | |
| 402 | + | |
| 403 | +Stop all DMA activity | |
| 404 | +--------------------- | |
| 405 | +It's extremely important to stop all DMA operations BEFORE attempting | |
| 406 | +to deallocate DMA control data. Failure to do so can result in memory | |
| 407 | +corruption, hangs, and on some chip-sets a hard crash. | |
| 408 | + | |
| 409 | +Stopping DMA after stopping the IRQs can avoid races where the | |
| 410 | +IRQ handler might restart DMA engines. | |
| 411 | + | |
| 412 | +While this step sounds obvious and trivial, several "mature" drivers | |
| 413 | +didn't get this step right in the past. | |
| 414 | + | |
| 415 | + | |
| 416 | +Release DMA buffers | |
| 417 | +------------------- | |
| 418 | +Once DMA is stopped, clean up streaming DMA first. | |
| 419 | +I.e. unmap data buffers and return buffers to "upstream" | |
| 420 | +owners if there is one. | |
| 421 | + | |
| 422 | +Then clean up "consistent" buffers which contain the control data. | |
| 423 | + | |
| 424 | +See Documentation/DMA-API.txt for details on unmapping interfaces. | |
| 425 | + | |
| 426 | + | |
| 427 | +Unregister from other subsystems | |
| 428 | +-------------------------------- | |
| 429 | +Most low level PCI device drivers support some other subsystem | |
| 430 | +like USB, ALSA, SCSI, NetDev, Infiniband, etc. Make sure your | |
| 431 | +driver isn't losing resources from that other subsystem. | |
| 432 | +If this happens, typically the symptom is an Oops (panic) when | |
| 433 | +the subsystem attempts to call into a driver that has been unloaded. | |
| 434 | + | |
| 435 | + | |
| 436 | +Disable Device from responding to MMIO/IO Port addresses | |
| 437 | +-------------------------------------------------------- | |
| 438 | +io_unmap() MMIO or IO Port resources and then call pci_disable_device(). | |
| 439 | +This is the symmetric opposite of pci_enable_device(). | |
| 440 | +Do not access device registers after calling pci_disable_device(). | |
| 441 | + | |
| 442 | + | |
| 443 | +Release MMIO/IO Port Resource(s) | |
| 444 | +-------------------------------- | |
| 445 | +Call pci_release_region() to mark the MMIO or IO Port range as available. | |
| 446 | +Failure to do so usually results in the inability to reload the driver. | |
| 447 | + | |
| 448 | + | |
| 449 | +How to access PCI config space | |
| 450 | +============================== | |
| 451 | + | |
| 452 | +You can use `pci_(read|write)_config_(byte|word|dword)` to access the config | |
| 453 | +space of a device represented by `struct pci_dev *`. All these functions return | |
| 454 | +0 when successful or an error code (`PCIBIOS_...`) which can be translated to a | |
| 455 | +text string by pcibios_strerror. Most drivers expect that accesses to valid PCI | |
| 456 | +devices don't fail. | |
| 457 | + | |
| 458 | +If you don't have a struct pci_dev available, you can call | |
| 459 | +`pci_bus_(read|write)_config_(byte|word|dword)` to access a given device | |
| 460 | +and function on that bus. | |
| 461 | + | |
| 462 | +If you access fields in the standard portion of the config header, please | |
| 463 | +use symbolic names of locations and bits declared in <linux/pci.h>. | |
| 464 | + | |
| 465 | +If you need to access Extended PCI Capability registers, just call | |
| 466 | +pci_find_capability() for the particular capability and it will find the | |
| 467 | +corresponding register block for you. | |
| 468 | + | |
| 469 | + | |
| 470 | +Other interesting functions | |
| 471 | +=========================== | |
| 472 | + | |
| 473 | +============================= ================================================ | |
| 474 | +pci_get_domain_bus_and_slot() Find pci_dev corresponding to given domain, | |
| 475 | + bus and slot and number. If the device is | |
| 476 | + found, its reference count is increased. | |
| 477 | +pci_set_power_state() Set PCI Power Management state (0=D0 ... 3=D3) | |
| 478 | +pci_find_capability() Find specified capability in device's capability | |
| 479 | + list. | |
| 480 | +pci_resource_start() Returns bus start address for a given PCI region | |
| 481 | +pci_resource_end() Returns bus end address for a given PCI region | |
| 482 | +pci_resource_len() Returns the byte length of a PCI region | |
| 483 | +pci_set_drvdata() Set private driver data pointer for a pci_dev | |
| 484 | +pci_get_drvdata() Return private driver data pointer for a pci_dev | |
| 485 | +pci_set_mwi() Enable Memory-Write-Invalidate transactions. | |
| 486 | +pci_clear_mwi() Disable Memory-Write-Invalidate transactions. | |
| 487 | +============================= ================================================ | |
| 488 | + | |
| 489 | + | |
| 490 | +Miscellaneous hints | |
| 491 | +=================== | |
| 492 | + | |
| 493 | +When displaying PCI device names to the user (for example when a driver wants | |
| 494 | +to tell the user what card has it found), please use pci_name(pci_dev). | |
| 495 | + | |
| 496 | +Always refer to the PCI devices by a pointer to the pci_dev structure. | |
| 497 | +All PCI layer functions use this identification and it's the only | |
| 498 | +reasonable one. Don't use bus/slot/function numbers except for very | |
| 499 | +special purposes -- on systems with multiple primary buses their semantics | |
| 500 | +can be pretty complex. | |
| 501 | + | |
| 502 | +Don't try to turn on Fast Back to Back writes in your driver. All devices | |
| 503 | +on the bus need to be capable of doing it, so this is something which needs | |
| 504 | +to be handled by platform and generic code, not individual drivers. | |
| 505 | + | |
| 506 | + | |
| 507 | +Vendor and device identifications | |
| 508 | +================================= | |
| 509 | + | |
| 510 | +Do not add new device or vendor IDs to include/linux/pci_ids.h unless they | |
| 511 | +are shared across multiple drivers. You can add private definitions in | |
| 512 | +your driver if they're helpful, or just use plain hex constants. | |
| 513 | + | |
| 514 | +The device IDs are arbitrary hex numbers (vendor controlled) and normally used | |
| 515 | +only in a single location, the pci_device_id table. | |
| 516 | + | |
| 517 | +Please DO submit new vendor/device IDs to http://pci-ids.ucw.cz/. | |
| 518 | +There are mirrors of the pci.ids file at http://pciids.sourceforge.net/ | |
| 519 | +and https://github.com/pciutils/pciids. | |
| 520 | + | |
| 521 | + | |
| 522 | +Obsolete functions | |
| 523 | +================== | |
| 524 | + | |
| 525 | +There are several functions which you might come across when trying to | |
| 526 | +port an old driver to the new PCI interface. They are no longer present | |
| 527 | +in the kernel as they aren't compatible with hotplug or PCI domains or | |
| 528 | +having sane locking. | |
| 529 | + | |
| 530 | +================= =========================================== | |
| 531 | +pci_find_device() Superseded by pci_get_device() | |
| 532 | +pci_find_subsys() Superseded by pci_get_subsys() | |
| 533 | +pci_find_slot() Superseded by pci_get_domain_bus_and_slot() | |
| 534 | +pci_get_slot() Superseded by pci_get_domain_bus_and_slot() | |
| 535 | +================= =========================================== | |
| 536 | + | |
| 537 | +The alternative is the traditional PCI device driver that walks PCI | |
| 538 | +device lists. This is still possible but discouraged. | |
| 539 | + | |
| 540 | + | |
| 541 | +MMIO Space and "Write Posting" | |
| 542 | +============================== | |
| 543 | + | |
| 544 | +Converting a driver from using I/O Port space to using MMIO space | |
| 545 | +often requires some additional changes. Specifically, "write posting" | |
| 546 | +needs to be handled. Many drivers (e.g. tg3, acenic, sym53c8xx_2) | |
| 547 | +already do this. I/O Port space guarantees write transactions reach the PCI | |
| 548 | +device before the CPU can continue. Writes to MMIO space allow the CPU | |
| 549 | +to continue before the transaction reaches the PCI device. HW weenies | |
| 550 | +call this "Write Posting" because the write completion is "posted" to | |
| 551 | +the CPU before the transaction has reached its destination. | |
| 552 | + | |
| 553 | +Thus, timing sensitive code should add readl() where the CPU is | |
| 554 | +expected to wait before doing other work. The classic "bit banging" | |
| 555 | +sequence works fine for I/O Port space:: | |
| 556 | + | |
| 557 | + for (i = 8; --i; val >>= 1) { | |
| 558 | + outb(val & 1, ioport_reg); /* write bit */ | |
| 559 | + udelay(10); | |
| 560 | + } | |
| 561 | + | |
| 562 | +The same sequence for MMIO space should be:: | |
| 563 | + | |
| 564 | + for (i = 8; --i; val >>= 1) { | |
| 565 | + writeb(val & 1, mmio_reg); /* write bit */ | |
| 566 | + readb(safe_mmio_reg); /* flush posted write */ | |
| 567 | + udelay(10); | |
| 568 | + } | |
| 569 | + | |
| 570 | +It is important that "safe_mmio_reg" not have any side effects that | |
| 571 | +interferes with the correct operation of the device. | |
| 572 | + | |
| 573 | +Another case to watch out for is when resetting a PCI device. Use PCI | |
| 574 | +Configuration space reads to flush the writel(). This will gracefully | |
| 575 | +handle the PCI master abort on all platforms if the PCI device is | |
| 576 | +expected to not respond to a readl(). Most x86 platforms will allow | |
| 577 | +MMIO reads to master abort (a.k.a. "Soft Fail") and return garbage | |
| 578 | +(e.g. ~0). But many RISC platforms will crash (a.k.a."Hard Fail"). | |
| @@ -1,636 +0,0 @@ | ||
| 1 | − | |
| 2 | − How To Write Linux PCI Drivers | |
| 3 | − | |
| 4 | − by Martin Mares <mj@ucw.cz> on 07-Feb-2000 | |
| 5 | − updated by Grant Grundler <grundler@parisc-linux.org> on 23-Dec-2006 | |
| 6 | − | |
| 7 | −~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ | |
| 8 | −The world of PCI is vast and full of (mostly unpleasant) surprises. | |
| 9 | −Since each CPU architecture implements different chip-sets and PCI devices | |
| 10 | −have different requirements (erm, "features"), the result is the PCI support | |
| 11 | −in the Linux kernel is not as trivial as one would wish. This short paper | |
| 12 | −tries to introduce all potential driver authors to Linux APIs for | |
| 13 | −PCI device drivers. | |
| 14 | − | |
| 15 | −A more complete resource is the third edition of "Linux Device Drivers" | |
| 16 | −by Jonathan Corbet, Alessandro Rubini, and Greg Kroah-Hartman. | |
| 17 | −LDD3 is available for free (under Creative Commons License) from: | |
| 18 | − | |
| 19 | − http://lwn.net/Kernel/LDD3/ | |
| 20 | − | |
| 21 | −However, keep in mind that all documents are subject to "bit rot". | |
| 22 | −Refer to the source code if things are not working as described here. | |
| 23 | − | |
| 24 | −Please send questions/comments/patches about Linux PCI API to the | |
| 25 | −"Linux PCI" <linux-pci@atrey.karlin.mff.cuni.cz> mailing list. | |
| 26 | − | |
| 27 | − | |
| 28 | − | |
| 29 | −0. Structure of PCI drivers | |
| 30 | −~~~~~~~~~~~~~~~~~~~~~~~~~~~ | |
| 31 | −PCI drivers "discover" PCI devices in a system via pci_register_driver(). | |
| 32 | −Actually, it's the other way around. When the PCI generic code discovers | |
| 33 | −a new device, the driver with a matching "description" will be notified. | |
| 34 | −Details on this below. | |
| 35 | − | |
| 36 | −pci_register_driver() leaves most of the probing for devices to | |
| 37 | −the PCI layer and supports online insertion/removal of devices [thus | |
| 38 | −supporting hot-pluggable PCI, CardBus, and Express-Card in a single driver]. | |
| 39 | −pci_register_driver() call requires passing in a table of function | |
| 40 | −pointers and thus dictates the high level structure of a driver. | |
| 41 | − | |
| 42 | −Once the driver knows about a PCI device and takes ownership, the | |
| 43 | −driver generally needs to perform the following initialization: | |
| 44 | − | |
| 45 | − Enable the device | |
| 46 | − Request MMIO/IOP resources | |
| 47 | − Set the DMA mask size (for both coherent and streaming DMA) | |
| 48 | − Allocate and initialize shared control data (pci_allocate_coherent()) | |
| 49 | − Access device configuration space (if needed) | |
| 50 | − Register IRQ handler (request_irq()) | |
| 51 | − Initialize non-PCI (i.e. LAN/SCSI/etc parts of the chip) | |
| 52 | − Enable DMA/processing engines | |
| 53 | − | |
| 54 | −When done using the device, and perhaps the module needs to be unloaded, | |
| 55 | −the driver needs to take the follow steps: | |
| 56 | − Disable the device from generating IRQs | |
| 57 | − Release the IRQ (free_irq()) | |
| 58 | − Stop all DMA activity | |
| 59 | − Release DMA buffers (both streaming and coherent) | |
| 60 | − Unregister from other subsystems (e.g. scsi or netdev) | |
| 61 | − Release MMIO/IOP resources | |
| 62 | − Disable the device | |
| 63 | − | |
| 64 | −Most of these topics are covered in the following sections. | |
| 65 | −For the rest look at LDD3 or <linux/pci.h> . | |
| 66 | − | |
| 67 | −If the PCI subsystem is not configured (CONFIG_PCI is not set), most of | |
| 68 | −the PCI functions described below are defined as inline functions either | |
| 69 | −completely empty or just returning an appropriate error codes to avoid | |
| 70 | −lots of ifdefs in the drivers. | |
| 71 | − | |
| 72 | − | |
| 73 | − | |
| 74 | −1. pci_register_driver() call | |
| 75 | −~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ | |
| 76 | − | |
| 77 | −PCI device drivers call pci_register_driver() during their | |
| 78 | −initialization with a pointer to a structure describing the driver | |
| 79 | −(struct pci_driver): | |
| 80 | − | |
| 81 | − field name Description | |
| 82 | − ---------- ------------------------------------------------------ | |
| 83 | − id_table Pointer to table of device ID's the driver is | |
| 84 | − interested in. Most drivers should export this | |
| 85 | − table using MODULE_DEVICE_TABLE(pci,...). | |
| 86 | − | |
| 87 | − probe This probing function gets called (during execution | |
| 88 | − of pci_register_driver() for already existing | |
| 89 | − devices or later if a new device gets inserted) for | |
| 90 | − all PCI devices which match the ID table and are not | |
| 91 | − "owned" by the other drivers yet. This function gets | |
| 92 | − passed a "struct pci_dev *" for each device whose | |
| 93 | − entry in the ID table matches the device. The probe | |
| 94 | − function returns zero when the driver chooses to | |
| 95 | − take "ownership" of the device or an error code | |
| 96 | − (negative number) otherwise. | |
| 97 | − The probe function always gets called from process | |
| 98 | − context, so it can sleep. | |
| 99 | − | |
| 100 | − remove The remove() function gets called whenever a device | |
| 101 | − being handled by this driver is removed (either during | |
| 102 | − deregistration of the driver or when it's manually | |
| 103 | − pulled out of a hot-pluggable slot). | |
| 104 | − The remove function always gets called from process | |
| 105 | − context, so it can sleep. | |
| 106 | − | |
| 107 | − suspend Put device into low power state. | |
| 108 | − suspend_late Put device into low power state. | |
| 109 | − | |
| 110 | − resume_early Wake device from low power state. | |
| 111 | − resume Wake device from low power state. | |
| 112 | − | |
| 113 | − (Please see Documentation/power/pci.txt for descriptions | |
| 114 | − of PCI Power Management and the related functions.) | |
| 115 | − | |
| 116 | − shutdown Hook into reboot_notifier_list (kernel/sys.c). | |
| 117 | − Intended to stop any idling DMA operations. | |
| 118 | − Useful for enabling wake-on-lan (NIC) or changing | |
| 119 | − the power state of a device before reboot. | |
| 120 | − e.g. drivers/net/e100.c. | |
| 121 | − | |
| 122 | − err_handler See Documentation/PCI/pci-error-recovery.txt | |
| 123 | − | |
| 124 | − | |
| 125 | −The ID table is an array of struct pci_device_id entries ending with an | |
| 126 | −all-zero entry. Definitions with static const are generally preferred. | |
| 127 | − | |
| 128 | −Each entry consists of: | |
| 129 | − | |
| 130 | − vendor,device Vendor and device ID to match (or PCI_ANY_ID) | |
| 131 | − | |
| 132 | − subvendor, Subsystem vendor and device ID to match (or PCI_ANY_ID) | |
| 133 | − subdevice, | |
| 134 | − | |
| 135 | − class Device class, subclass, and "interface" to match. | |
| 136 | − See Appendix D of the PCI Local Bus Spec or | |
| 137 | − include/linux/pci_ids.h for a full list of classes. | |
| 138 | − Most drivers do not need to specify class/class_mask | |
| 139 | − as vendor/device is normally sufficient. | |
| 140 | − | |
| 141 | − class_mask limit which sub-fields of the class field are compared. | |
| 142 | − See drivers/scsi/sym53c8xx_2/ for example of usage. | |
| 143 | − | |
| 144 | − driver_data Data private to the driver. | |
| 145 | − Most drivers don't need to use driver_data field. | |
| 146 | − Best practice is to use driver_data as an index | |
| 147 | − into a static list of equivalent device types, | |
| 148 | − instead of using it as a pointer. | |
| 149 | − | |
| 150 | − | |
| 151 | −Most drivers only need PCI_DEVICE() or PCI_DEVICE_CLASS() to set up | |
| 152 | −a pci_device_id table. | |
| 153 | − | |
| 154 | −New PCI IDs may be added to a device driver pci_ids table at runtime | |
| 155 | −as shown below: | |
| 156 | − | |
| 157 | −echo "vendor device subvendor subdevice class class_mask driver_data" > \ | |
| 158 | −/sys/bus/pci/drivers/{driver}/new_id | |
| 159 | − | |
| 160 | −All fields are passed in as hexadecimal values (no leading 0x). | |
| 161 | −The vendor and device fields are mandatory, the others are optional. Users | |
| 162 | −need pass only as many optional fields as necessary: | |
| 163 | − o subvendor and subdevice fields default to PCI_ANY_ID (FFFFFFFF) | |
| 164 | − o class and classmask fields default to 0 | |
| 165 | − o driver_data defaults to 0UL. | |
| 166 | − | |
| 167 | −Note that driver_data must match the value used by any of the pci_device_id | |
| 168 | −entries defined in the driver. This makes the driver_data field mandatory | |
| 169 | −if all the pci_device_id entries have a non-zero driver_data value. | |
| 170 | − | |
| 171 | −Once added, the driver probe routine will be invoked for any unclaimed | |
| 172 | −PCI devices listed in its (newly updated) pci_ids list. | |
| 173 | − | |
| 174 | −When the driver exits, it just calls pci_unregister_driver() and the PCI layer | |
| 175 | −automatically calls the remove hook for all devices handled by the driver. | |
| 176 | − | |
| 177 | − | |
| 178 | −1.1 "Attributes" for driver functions/data | |
| 179 | − | |
| 180 | −Please mark the initialization and cleanup functions where appropriate | |
| 181 | −(the corresponding macros are defined in <linux/init.h>): | |
| 182 | − | |
| 183 | − __init Initialization code. Thrown away after the driver | |
| 184 | − initializes. | |
| 185 | − __exit Exit code. Ignored for non-modular drivers. | |
| 186 | − | |
| 187 | −Tips on when/where to use the above attributes: | |
| 188 | − o The module_init()/module_exit() functions (and all | |
| 189 | − initialization functions called _only_ from these) | |
| 190 | − should be marked __init/__exit. | |
| 191 | − | |
| 192 | − o Do not mark the struct pci_driver. | |
| 193 | − | |
| 194 | − o Do NOT mark a function if you are not sure which mark to use. | |
| 195 | − Better to not mark the function than mark the function wrong. | |
| 196 | − | |
| 197 | − | |
| 198 | − | |
| 199 | −2. How to find PCI devices manually | |
| 200 | −~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ | |
| 201 | − | |
| 202 | −PCI drivers should have a really good reason for not using the | |
| 203 | −pci_register_driver() interface to search for PCI devices. | |
| 204 | −The main reason PCI devices are controlled by multiple drivers | |
| 205 | −is because one PCI device implements several different HW services. | |
| 206 | −E.g. combined serial/parallel port/floppy controller. | |
| 207 | − | |
| 208 | −A manual search may be performed using the following constructs: | |
| 209 | − | |
| 210 | −Searching by vendor and device ID: | |
| 211 | − | |
| 212 | − struct pci_dev *dev = NULL; | |
| 213 | − while (dev = pci_get_device(VENDOR_ID, DEVICE_ID, dev)) | |
| 214 | − configure_device(dev); | |
| 215 | − | |
| 216 | −Searching by class ID (iterate in a similar way): | |
| 217 | − | |
| 218 | − pci_get_class(CLASS_ID, dev) | |
| 219 | − | |
| 220 | −Searching by both vendor/device and subsystem vendor/device ID: | |
| 221 | − | |
| 222 | − pci_get_subsys(VENDOR_ID,DEVICE_ID, SUBSYS_VENDOR_ID, SUBSYS_DEVICE_ID, dev). | |
| 223 | − | |
| 224 | −You can use the constant PCI_ANY_ID as a wildcard replacement for | |
| 225 | −VENDOR_ID or DEVICE_ID. This allows searching for any device from a | |
| 226 | −specific vendor, for example. | |
| 227 | − | |
| 228 | −These functions are hotplug-safe. They increment the reference count on | |
| 229 | −the pci_dev that they return. You must eventually (possibly at module unload) | |
| 230 | −decrement the reference count on these devices by calling pci_dev_put(). | |
| 231 | − | |
| 232 | − | |
| 233 | − | |
| 234 | −3. Device Initialization Steps | |
| 235 | −~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ | |
| 236 | − | |
| 237 | −As noted in the introduction, most PCI drivers need the following steps | |
| 238 | −for device initialization: | |
| 239 | − | |
| 240 | − Enable the device | |
| 241 | − Request MMIO/IOP resources | |
| 242 | − Set the DMA mask size (for both coherent and streaming DMA) | |
| 243 | − Allocate and initialize shared control data (pci_allocate_coherent()) | |
| 244 | − Access device configuration space (if needed) | |
| 245 | − Register IRQ handler (request_irq()) | |
| 246 | − Initialize non-PCI (i.e. LAN/SCSI/etc parts of the chip) | |
| 247 | − Enable DMA/processing engines. | |
| 248 | − | |
| 249 | −The driver can access PCI config space registers at any time. | |
| 250 | −(Well, almost. When running BIST, config space can go away...but | |
| 251 | −that will just result in a PCI Bus Master Abort and config reads | |
| 252 | −will return garbage). | |
| 253 | − | |
| 254 | − | |
| 255 | −3.1 Enable the PCI device | |
| 256 | −~~~~~~~~~~~~~~~~~~~~~~~~~ | |
| 257 | −Before touching any device registers, the driver needs to enable | |
| 258 | −the PCI device by calling pci_enable_device(). This will: | |
| 259 | − o wake up the device if it was in suspended state, | |
| 260 | − o allocate I/O and memory regions of the device (if BIOS did not), | |
| 261 | − o allocate an IRQ (if BIOS did not). | |
| 262 | − | |
| 263 | −NOTE: pci_enable_device() can fail! Check the return value. | |
| 264 | − | |
| 265 | −[ OS BUG: we don't check resource allocations before enabling those | |
| 266 | − resources. The sequence would make more sense if we called | |
| 267 | − pci_request_resources() before calling pci_enable_device(). | |
| 268 | − Currently, the device drivers can't detect the bug when when two | |
| 269 | − devices have been allocated the same range. This is not a common | |
| 270 | − problem and unlikely to get fixed soon. | |
| 271 | − | |
| 272 | − This has been discussed before but not changed as of 2.6.19: | |
| 273 | − http://lkml.org/lkml/2006/3/2/194 | |
| 274 | −] | |
| 275 | − | |
| 276 | −pci_set_master() will enable DMA by setting the bus master bit | |
| 277 | −in the PCI_COMMAND register. It also fixes the latency timer value if | |
| 278 | −it's set to something bogus by the BIOS. pci_clear_master() will | |
| 279 | −disable DMA by clearing the bus master bit. | |
| 280 | − | |
| 281 | −If the PCI device can use the PCI Memory-Write-Invalidate transaction, | |
| 282 | −call pci_set_mwi(). This enables the PCI_COMMAND bit for Mem-Wr-Inval | |
| 283 | −and also ensures that the cache line size register is set correctly. | |
| 284 | −Check the return value of pci_set_mwi() as not all architectures | |
| 285 | −or chip-sets may support Memory-Write-Invalidate. Alternatively, | |
| 286 | −if Mem-Wr-Inval would be nice to have but is not required, call | |
| 287 | −pci_try_set_mwi() to have the system do its best effort at enabling | |
| 288 | −Mem-Wr-Inval. | |
| 289 | − | |
| 290 | − | |
| 291 | −3.2 Request MMIO/IOP resources | |
| 292 | −~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ | |
| 293 | −Memory (MMIO), and I/O port addresses should NOT be read directly | |
| 294 | −from the PCI device config space. Use the values in the pci_dev structure | |
| 295 | −as the PCI "bus address" might have been remapped to a "host physical" | |
| 296 | −address by the arch/chip-set specific kernel support. | |
| 297 | − | |
| 298 | −See Documentation/io-mapping.txt for how to access device registers | |
| 299 | −or device memory. | |
| 300 | − | |
| 301 | −The device driver needs to call pci_request_region() to verify | |
| 302 | −no other device is already using the same address resource. | |
| 303 | −Conversely, drivers should call pci_release_region() AFTER | |
| 304 | −calling pci_disable_device(). | |
| 305 | −The idea is to prevent two devices colliding on the same address range. | |
| 306 | − | |
| 307 | −[ See OS BUG comment above. Currently (2.6.19), The driver can only | |
| 308 | − determine MMIO and IO Port resource availability _after_ calling | |
| 309 | − pci_enable_device(). ] | |
| 310 | − | |
| 311 | −Generic flavors of pci_request_region() are request_mem_region() | |
| 312 | −(for MMIO ranges) and request_region() (for IO Port ranges). | |
| 313 | −Use these for address resources that are not described by "normal" PCI | |
| 314 | −BARs. | |
| 315 | − | |
| 316 | −Also see pci_request_selected_regions() below. | |
| 317 | − | |
| 318 | − | |
| 319 | −3.3 Set the DMA mask size | |
| 320 | −~~~~~~~~~~~~~~~~~~~~~~~~~ | |
| 321 | −[ If anything below doesn't make sense, please refer to | |
| 322 | − Documentation/DMA-API.txt. This section is just a reminder that | |
| 323 | − drivers need to indicate DMA capabilities of the device and is not | |
| 324 | − an authoritative source for DMA interfaces. ] | |
| 325 | − | |
| 326 | −While all drivers should explicitly indicate the DMA capability | |
| 327 | −(e.g. 32 or 64 bit) of the PCI bus master, devices with more than | |
| 328 | −32-bit bus master capability for streaming data need the driver | |
| 329 | −to "register" this capability by calling pci_set_dma_mask() with | |
| 330 | −appropriate parameters. In general this allows more efficient DMA | |
| 331 | −on systems where System RAM exists above 4G _physical_ address. | |
| 332 | − | |
| 333 | −Drivers for all PCI-X and PCIe compliant devices must call | |
| 334 | −pci_set_dma_mask() as they are 64-bit DMA devices. | |
| 335 | − | |
| 336 | −Similarly, drivers must also "register" this capability if the device | |
| 337 | −can directly address "consistent memory" in System RAM above 4G physical | |
| 338 | −address by calling pci_set_consistent_dma_mask(). | |
| 339 | −Again, this includes drivers for all PCI-X and PCIe compliant devices. | |
| 340 | −Many 64-bit "PCI" devices (before PCI-X) and some PCI-X devices are | |
| 341 | −64-bit DMA capable for payload ("streaming") data but not control | |
| 342 | −("consistent") data. | |
| 343 | − | |
| 344 | − | |
| 345 | −3.4 Setup shared control data | |
| 346 | −~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ | |
| 347 | −Once the DMA masks are set, the driver can allocate "consistent" (a.k.a. shared) | |
| 348 | −memory. See Documentation/DMA-API.txt for a full description of | |
| 349 | −the DMA APIs. This section is just a reminder that it needs to be done | |
| 350 | −before enabling DMA on the device. | |
| 351 | − | |
| 352 | − | |
| 353 | −3.5 Initialize device registers | |
| 354 | −~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ | |
| 355 | −Some drivers will need specific "capability" fields programmed | |
| 356 | −or other "vendor specific" register initialized or reset. | |
| 357 | −E.g. clearing pending interrupts. | |
| 358 | − | |
| 359 | − | |
| 360 | −3.6 Register IRQ handler | |
| 361 | −~~~~~~~~~~~~~~~~~~~~~~~~ | |
| 362 | −While calling request_irq() is the last step described here, | |
| 363 | −this is often just another intermediate step to initialize a device. | |
| 364 | −This step can often be deferred until the device is opened for use. | |
| 365 | − | |
| 366 | −All interrupt handlers for IRQ lines should be registered with IRQF_SHARED | |
| 367 | −and use the devid to map IRQs to devices (remember that all PCI IRQ lines | |
| 368 | −can be shared). | |
| 369 | − | |
| 370 | −request_irq() will associate an interrupt handler and device handle | |
| 371 | −with an interrupt number. Historically interrupt numbers represent | |
| 372 | −IRQ lines which run from the PCI device to the Interrupt controller. | |
| 373 | −With MSI and MSI-X (more below) the interrupt number is a CPU "vector". | |
| 374 | − | |
| 375 | −request_irq() also enables the interrupt. Make sure the device is | |
| 376 | −quiesced and does not have any interrupts pending before registering | |
| 377 | −the interrupt handler. | |
| 378 | − | |
| 379 | −MSI and MSI-X are PCI capabilities. Both are "Message Signaled Interrupts" | |
| 380 | −which deliver interrupts to the CPU via a DMA write to a Local APIC. | |
| 381 | −The fundamental difference between MSI and MSI-X is how multiple | |
| 382 | −"vectors" get allocated. MSI requires contiguous blocks of vectors | |
| 383 | −while MSI-X can allocate several individual ones. | |
| 384 | − | |
| 385 | −MSI capability can be enabled by calling pci_alloc_irq_vectors() with the | |
| 386 | −PCI_IRQ_MSI and/or PCI_IRQ_MSIX flags before calling request_irq(). This | |
| 387 | −causes the PCI support to program CPU vector data into the PCI device | |
| 388 | −capability registers. Many architectures, chip-sets, or BIOSes do NOT | |
| 389 | −support MSI or MSI-X and a call to pci_alloc_irq_vectors with just | |
| 390 | −the PCI_IRQ_MSI and PCI_IRQ_MSIX flags will fail, so try to always | |
| 391 | −specify PCI_IRQ_LEGACY as well. | |
| 392 | − | |
| 393 | −Drivers that have different interrupt handlers for MSI/MSI-X and | |
| 394 | −legacy INTx should chose the right one based on the msi_enabled | |
| 395 | −and msix_enabled flags in the pci_dev structure after calling | |
| 396 | −pci_alloc_irq_vectors. | |
| 397 | − | |
| 398 | −There are (at least) two really good reasons for using MSI: | |
| 399 | −1) MSI is an exclusive interrupt vector by definition. | |
| 400 | − This means the interrupt handler doesn't have to verify | |
| 401 | − its device caused the interrupt. | |
| 402 | − | |
| 403 | −2) MSI avoids DMA/IRQ race conditions. DMA to host memory is guaranteed | |
| 404 | − to be visible to the host CPU(s) when the MSI is delivered. This | |
| 405 | − is important for both data coherency and avoiding stale control data. | |
| 406 | − This guarantee allows the driver to omit MMIO reads to flush | |
| 407 | − the DMA stream. | |
| 408 | − | |
| 409 | −See drivers/infiniband/hw/mthca/ or drivers/net/tg3.c for examples | |
| 410 | −of MSI/MSI-X usage. | |
| 411 | − | |
| 412 | − | |
| 413 | − | |
| 414 | −4. PCI device shutdown | |
| 415 | −~~~~~~~~~~~~~~~~~~~~~~~ | |
| 416 | − | |
| 417 | −When a PCI device driver is being unloaded, most of the following | |
| 418 | −steps need to be performed: | |
| 419 | − | |
| 420 | − Disable the device from generating IRQs | |
| 421 | − Release the IRQ (free_irq()) | |
| 422 | − Stop all DMA activity | |
| 423 | − Release DMA buffers (both streaming and consistent) | |
| 424 | − Unregister from other subsystems (e.g. scsi or netdev) | |
| 425 | − Disable device from responding to MMIO/IO Port addresses | |
| 426 | − Release MMIO/IO Port resource(s) | |
| 427 | − | |
| 428 | − | |
| 429 | −4.1 Stop IRQs on the device | |
| 430 | −~~~~~~~~~~~~~~~~~~~~~~~~~~~ | |
| 431 | −How to do this is chip/device specific. If it's not done, it opens | |
| 432 | −the possibility of a "screaming interrupt" if (and only if) | |
| 433 | −the IRQ is shared with another device. | |
| 434 | − | |
| 435 | −When the shared IRQ handler is "unhooked", the remaining devices | |
| 436 | −using the same IRQ line will still need the IRQ enabled. Thus if the | |
| 437 | −"unhooked" device asserts IRQ line, the system will respond assuming | |
| 438 | −it was one of the remaining devices asserted the IRQ line. Since none | |
| 439 | −of the other devices will handle the IRQ, the system will "hang" until | |
| 440 | −it decides the IRQ isn't going to get handled and masks the IRQ (100,000 | |
| 441 | −iterations later). Once the shared IRQ is masked, the remaining devices | |
| 442 | −will stop functioning properly. Not a nice situation. | |
| 443 | − | |
| 444 | −This is another reason to use MSI or MSI-X if it's available. | |
| 445 | −MSI and MSI-X are defined to be exclusive interrupts and thus | |
| 446 | −are not susceptible to the "screaming interrupt" problem. | |
| 447 | − | |
| 448 | − | |
| 449 | −4.2 Release the IRQ | |
| 450 | −~~~~~~~~~~~~~~~~~~~ | |
| 451 | −Once the device is quiesced (no more IRQs), one can call free_irq(). | |
| 452 | −This function will return control once any pending IRQs are handled, | |
| 453 | −"unhook" the drivers IRQ handler from that IRQ, and finally release | |
| 454 | −the IRQ if no one else is using it. | |
| 455 | − | |
| 456 | − | |
| 457 | −4.3 Stop all DMA activity | |
| 458 | −~~~~~~~~~~~~~~~~~~~~~~~~~ | |
| 459 | −It's extremely important to stop all DMA operations BEFORE attempting | |
| 460 | −to deallocate DMA control data. Failure to do so can result in memory | |
| 461 | −corruption, hangs, and on some chip-sets a hard crash. | |
| 462 | − | |
| 463 | −Stopping DMA after stopping the IRQs can avoid races where the | |
| 464 | −IRQ handler might restart DMA engines. | |
| 465 | − | |
| 466 | −While this step sounds obvious and trivial, several "mature" drivers | |
| 467 | −didn't get this step right in the past. | |
| 468 | − | |
| 469 | − | |
| 470 | −4.4 Release DMA buffers | |
| 471 | −~~~~~~~~~~~~~~~~~~~~~~~ | |
| 472 | −Once DMA is stopped, clean up streaming DMA first. | |
| 473 | −I.e. unmap data buffers and return buffers to "upstream" | |
| 474 | −owners if there is one. | |
| 475 | − | |
| 476 | −Then clean up "consistent" buffers which contain the control data. | |
| 477 | − | |
| 478 | −See Documentation/DMA-API.txt for details on unmapping interfaces. | |
| 479 | − | |
| 480 | − | |
| 481 | −4.5 Unregister from other subsystems | |
| 482 | −~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ | |
| 483 | −Most low level PCI device drivers support some other subsystem | |
| 484 | −like USB, ALSA, SCSI, NetDev, Infiniband, etc. Make sure your | |
| 485 | −driver isn't losing resources from that other subsystem. | |
| 486 | −If this happens, typically the symptom is an Oops (panic) when | |
| 487 | −the subsystem attempts to call into a driver that has been unloaded. | |
| 488 | − | |
| 489 | − | |
| 490 | −4.6 Disable Device from responding to MMIO/IO Port addresses | |
| 491 | −~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ | |
| 492 | −io_unmap() MMIO or IO Port resources and then call pci_disable_device(). | |
| 493 | −This is the symmetric opposite of pci_enable_device(). | |
| 494 | −Do not access device registers after calling pci_disable_device(). | |
| 495 | − | |
| 496 | − | |
| 497 | −4.7 Release MMIO/IO Port Resource(s) | |
| 498 | −~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ | |
| 499 | −Call pci_release_region() to mark the MMIO or IO Port range as available. | |
| 500 | −Failure to do so usually results in the inability to reload the driver. | |
| 501 | − | |
| 502 | − | |
| 503 | − | |
| 504 | −5. How to access PCI config space | |
| 505 | −~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ | |
| 506 | − | |
| 507 | −You can use pci_(read|write)_config_(byte|word|dword) to access the config | |
| 508 | −space of a device represented by struct pci_dev *. All these functions return 0 | |
| 509 | −when successful or an error code (PCIBIOS_...) which can be translated to a text | |
| 510 | −string by pcibios_strerror. Most drivers expect that accesses to valid PCI | |
| 511 | −devices don't fail. | |
| 512 | − | |
| 513 | −If you don't have a struct pci_dev available, you can call | |
| 514 | −pci_bus_(read|write)_config_(byte|word|dword) to access a given device | |
| 515 | −and function on that bus. | |
| 516 | − | |
| 517 | −If you access fields in the standard portion of the config header, please | |
| 518 | −use symbolic names of locations and bits declared in <linux/pci.h>. | |
| 519 | − | |
| 520 | −If you need to access Extended PCI Capability registers, just call | |
| 521 | −pci_find_capability() for the particular capability and it will find the | |
| 522 | −corresponding register block for you. | |
| 523 | − | |
| 524 | − | |
| 525 | − | |
| 526 | −6. Other interesting functions | |
| 527 | −~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ | |
| 528 | − | |
| 529 | −pci_get_domain_bus_and_slot() Find pci_dev corresponding to given domain, | |
| 530 | − bus and slot and number. If the device is | |
| 531 | − found, its reference count is increased. | |
| 532 | −pci_set_power_state() Set PCI Power Management state (0=D0 ... 3=D3) | |
| 533 | −pci_find_capability() Find specified capability in device's capability | |
| 534 | − list. | |
| 535 | −pci_resource_start() Returns bus start address for a given PCI region | |
| 536 | −pci_resource_end() Returns bus end address for a given PCI region | |
| 537 | −pci_resource_len() Returns the byte length of a PCI region | |
| 538 | −pci_set_drvdata() Set private driver data pointer for a pci_dev | |
| 539 | −pci_get_drvdata() Return private driver data pointer for a pci_dev | |
| 540 | −pci_set_mwi() Enable Memory-Write-Invalidate transactions. | |
| 541 | −pci_clear_mwi() Disable Memory-Write-Invalidate transactions. | |
| 542 | − | |
| 543 | − | |
| 544 | − | |
| 545 | −7. Miscellaneous hints | |
| 546 | −~~~~~~~~~~~~~~~~~~~~~~ | |
| 547 | − | |
| 548 | −When displaying PCI device names to the user (for example when a driver wants | |
| 549 | −to tell the user what card has it found), please use pci_name(pci_dev). | |
| 550 | − | |
| 551 | −Always refer to the PCI devices by a pointer to the pci_dev structure. | |
| 552 | −All PCI layer functions use this identification and it's the only | |
| 553 | −reasonable one. Don't use bus/slot/function numbers except for very | |
| 554 | −special purposes -- on systems with multiple primary buses their semantics | |
| 555 | −can be pretty complex. | |
| 556 | − | |
| 557 | −Don't try to turn on Fast Back to Back writes in your driver. All devices | |
| 558 | −on the bus need to be capable of doing it, so this is something which needs | |
| 559 | −to be handled by platform and generic code, not individual drivers. | |
| 560 | − | |
| 561 | − | |
| 562 | − | |
| 563 | −8. Vendor and device identifications | |
| 564 | −~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ | |
| 565 | − | |
| 566 | −Do not add new device or vendor IDs to include/linux/pci_ids.h unless they | |
| 567 | −are shared across multiple drivers. You can add private definitions in | |
| 568 | −your driver if they're helpful, or just use plain hex constants. | |
| 569 | − | |
| 570 | −The device IDs are arbitrary hex numbers (vendor controlled) and normally used | |
| 571 | −only in a single location, the pci_device_id table. | |
| 572 | − | |
| 573 | −Please DO submit new vendor/device IDs to http://pci-ids.ucw.cz/. | |
| 574 | −There are mirrors of the pci.ids file at http://pciids.sourceforge.net/ | |
| 575 | −and https://github.com/pciutils/pciids. | |
| 576 | − | |
| 577 | − | |
| 578 | − | |
| 579 | −9. Obsolete functions | |
| 580 | −~~~~~~~~~~~~~~~~~~~~~ | |
| 581 | − | |
| 582 | −There are several functions which you might come across when trying to | |
| 583 | −port an old driver to the new PCI interface. They are no longer present | |
| 584 | −in the kernel as they aren't compatible with hotplug or PCI domains or | |
| 585 | −having sane locking. | |
| 586 | − | |
| 587 | −pci_find_device() Superseded by pci_get_device() | |
| 588 | −pci_find_subsys() Superseded by pci_get_subsys() | |
| 589 | −pci_find_slot() Superseded by pci_get_domain_bus_and_slot() | |
| 590 | −pci_get_slot() Superseded by pci_get_domain_bus_and_slot() | |
| 591 | − | |
| 592 | − | |
| 593 | −The alternative is the traditional PCI device driver that walks PCI | |
| 594 | −device lists. This is still possible but discouraged. | |
| 595 | − | |
| 596 | − | |
| 597 | − | |
| 598 | −10. MMIO Space and "Write Posting" | |
| 599 | −~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ | |
| 600 | − | |
| 601 | −Converting a driver from using I/O Port space to using MMIO space | |
| 602 | −often requires some additional changes. Specifically, "write posting" | |
| 603 | −needs to be handled. Many drivers (e.g. tg3, acenic, sym53c8xx_2) | |
| 604 | −already do this. I/O Port space guarantees write transactions reach the PCI | |
| 605 | −device before the CPU can continue. Writes to MMIO space allow the CPU | |
| 606 | −to continue before the transaction reaches the PCI device. HW weenies | |
| 607 | −call this "Write Posting" because the write completion is "posted" to | |
| 608 | −the CPU before the transaction has reached its destination. | |
| 609 | − | |
| 610 | −Thus, timing sensitive code should add readl() where the CPU is | |
| 611 | −expected to wait before doing other work. The classic "bit banging" | |
| 612 | −sequence works fine for I/O Port space: | |
| 613 | − | |
| 614 | − for (i = 8; --i; val >>= 1) { | |
| 615 | − outb(val & 1, ioport_reg); /* write bit */ | |
| 616 | − udelay(10); | |
| 617 | − } | |
| 618 | − | |
| 619 | −The same sequence for MMIO space should be: | |
| 620 | − | |
| 621 | − for (i = 8; --i; val >>= 1) { | |
| 622 | − writeb(val & 1, mmio_reg); /* write bit */ | |
| 623 | − readb(safe_mmio_reg); /* flush posted write */ | |
| 624 | − udelay(10); | |
| 625 | − } | |
| 626 | − | |
| 627 | −It is important that "safe_mmio_reg" not have any side effects that | |
| 628 | −interferes with the correct operation of the device. | |
| 629 | − | |
| 630 | −Another case to watch out for is when resetting a PCI device. Use PCI | |
| 631 | −Configuration space reads to flush the writel(). This will gracefully | |
| 632 | −handle the PCI master abort on all platforms if the PCI device is | |
| 633 | −expected to not respond to a readl(). Most x86 platforms will allow | |
| 634 | −MMIO reads to master abort (a.k.a. "Soft Fail") and return garbage | |
| 635 | −(e.g. ~0). But many RISC platforms will crash (a.k.a."Hard Fail"). | |
| 636 | − | |
| @@ -0,0 +1,311 @@ | ||
| 1 | +.. SPDX-License-Identifier: GPL-2.0 | |
| 2 | +.. include:: <isonum.txt> | |
| 3 | + | |
| 4 | +=========================================================== | |
| 5 | +The PCI Express Advanced Error Reporting Driver Guide HOWTO | |
| 6 | +=========================================================== | |
| 7 | + | |
| 8 | +:Authors: - T. Long Nguyen <tom.l.nguyen@intel.com> | |
| 9 | + - Yanmin Zhang <yanmin.zhang@intel.com> | |
| 10 | + | |
| 11 | +:Copyright: |copy| 2006 Intel Corporation | |
| 12 | + | |
| 13 | +Overview | |
| 14 | +=========== | |
| 15 | + | |
| 16 | +About this guide | |
| 17 | +---------------- | |
| 18 | + | |
| 19 | +This guide describes the basics of the PCI Express Advanced Error | |
| 20 | +Reporting (AER) driver and provides information on how to use it, as | |
| 21 | +well as how to enable the drivers of endpoint devices to conform with | |
| 22 | +PCI Express AER driver. | |
| 23 | + | |
| 24 | + | |
| 25 | +What is the PCI Express AER Driver? | |
| 26 | +----------------------------------- | |
| 27 | + | |
| 28 | +PCI Express error signaling can occur on the PCI Express link itself | |
| 29 | +or on behalf of transactions initiated on the link. PCI Express | |
| 30 | +defines two error reporting paradigms: the baseline capability and | |
| 31 | +the Advanced Error Reporting capability. The baseline capability is | |
| 32 | +required of all PCI Express components providing a minimum defined | |
| 33 | +set of error reporting requirements. Advanced Error Reporting | |
| 34 | +capability is implemented with a PCI Express advanced error reporting | |
| 35 | +extended capability structure providing more robust error reporting. | |
| 36 | + | |
| 37 | +The PCI Express AER driver provides the infrastructure to support PCI | |
| 38 | +Express Advanced Error Reporting capability. The PCI Express AER | |
| 39 | +driver provides three basic functions: | |
| 40 | + | |
| 41 | + - Gathers the comprehensive error information if errors occurred. | |
| 42 | + - Reports error to the users. | |
| 43 | + - Performs error recovery actions. | |
| 44 | + | |
| 45 | +AER driver only attaches root ports which support PCI-Express AER | |
| 46 | +capability. | |
| 47 | + | |
| 48 | + | |
| 49 | +User Guide | |
| 50 | +========== | |
| 51 | + | |
| 52 | +Include the PCI Express AER Root Driver into the Linux Kernel | |
| 53 | +------------------------------------------------------------- | |
| 54 | + | |
| 55 | +The PCI Express AER Root driver is a Root Port service driver attached | |
| 56 | +to the PCI Express Port Bus driver. If a user wants to use it, the driver | |
| 57 | +has to be compiled. Option CONFIG_PCIEAER supports this capability. It | |
| 58 | +depends on CONFIG_PCIEPORTBUS, so pls. set CONFIG_PCIEPORTBUS=y and | |
| 59 | +CONFIG_PCIEAER = y. | |
| 60 | + | |
| 61 | +Load PCI Express AER Root Driver | |
| 62 | +-------------------------------- | |
| 63 | + | |
| 64 | +Some systems have AER support in firmware. Enabling Linux AER support at | |
| 65 | +the same time the firmware handles AER may result in unpredictable | |
| 66 | +behavior. Therefore, Linux does not handle AER events unless the firmware | |
| 67 | +grants AER control to the OS via the ACPI _OSC method. See the PCI FW 3.0 | |
| 68 | +Specification for details regarding _OSC usage. | |
| 69 | + | |
| 70 | +AER error output | |
| 71 | +---------------- | |
| 72 | + | |
| 73 | +When a PCIe AER error is captured, an error message will be output to | |
| 74 | +console. If it's a correctable error, it is output as a warning. | |
| 75 | +Otherwise, it is printed as an error. So users could choose different | |
| 76 | +log level to filter out correctable error messages. | |
| 77 | + | |
| 78 | +Below shows an example:: | |
| 79 | + | |
| 80 | + 0000:50:00.0: PCIe Bus Error: severity=Uncorrected (Fatal), type=Transaction Layer, id=0500(Requester ID) | |
| 81 | + 0000:50:00.0: device [8086:0329] error status/mask=00100000/00000000 | |
| 82 | + 0000:50:00.0: [20] Unsupported Request (First) | |
| 83 | + 0000:50:00.0: TLP Header: 04000001 00200a03 05010000 00050100 | |
| 84 | + | |
| 85 | +In the example, 'Requester ID' means the ID of the device who sends | |
| 86 | +the error message to root port. Pls. refer to pci express specs for | |
| 87 | +other fields. | |
| 88 | + | |
| 89 | +AER Statistics / Counters | |
| 90 | +------------------------- | |
| 91 | + | |
| 92 | +When PCIe AER errors are captured, the counters / statistics are also exposed | |
| 93 | +in the form of sysfs attributes which are documented at | |
| 94 | +Documentation/ABI/testing/sysfs-bus-pci-devices-aer_stats | |
| 95 | + | |
| 96 | +Developer Guide | |
| 97 | +=============== | |
| 98 | + | |
| 99 | +To enable AER aware support requires a software driver to configure | |
| 100 | +the AER capability structure within its device and to provide callbacks. | |
| 101 | + | |
| 102 | +To support AER better, developers need understand how AER does work | |
| 103 | +firstly. | |
| 104 | + | |
| 105 | +PCI Express errors are classified into two types: correctable errors | |
| 106 | +and uncorrectable errors. This classification is based on the impacts | |
| 107 | +of those errors, which may result in degraded performance or function | |
| 108 | +failure. | |
| 109 | + | |
| 110 | +Correctable errors pose no impacts on the functionality of the | |
| 111 | +interface. The PCI Express protocol can recover without any software | |
| 112 | +intervention or any loss of data. These errors are detected and | |
| 113 | +corrected by hardware. Unlike correctable errors, uncorrectable | |
| 114 | +errors impact functionality of the interface. Uncorrectable errors | |
| 115 | +can cause a particular transaction or a particular PCI Express link | |
| 116 | +to be unreliable. Depending on those error conditions, uncorrectable | |
| 117 | +errors are further classified into non-fatal errors and fatal errors. | |
| 118 | +Non-fatal errors cause the particular transaction to be unreliable, | |
| 119 | +but the PCI Express link itself is fully functional. Fatal errors, on | |
| 120 | +the other hand, cause the link to be unreliable. | |
| 121 | + | |
| 122 | +When AER is enabled, a PCI Express device will automatically send an | |
| 123 | +error message to the PCIe root port above it when the device captures | |
| 124 | +an error. The Root Port, upon receiving an error reporting message, | |
| 125 | +internally processes and logs the error message in its PCI Express | |
| 126 | +capability structure. Error information being logged includes storing | |
| 127 | +the error reporting agent's requestor ID into the Error Source | |
| 128 | +Identification Registers and setting the error bits of the Root Error | |
| 129 | +Status Register accordingly. If AER error reporting is enabled in Root | |
| 130 | +Error Command Register, the Root Port generates an interrupt if an | |
| 131 | +error is detected. | |
| 132 | + | |
| 133 | +Note that the errors as described above are related to the PCI Express | |
| 134 | +hierarchy and links. These errors do not include any device specific | |
| 135 | +errors because device specific errors will still get sent directly to | |
| 136 | +the device driver. | |
| 137 | + | |
| 138 | +Configure the AER capability structure | |
| 139 | +-------------------------------------- | |
| 140 | + | |
| 141 | +AER aware drivers of PCI Express component need change the device | |
| 142 | +control registers to enable AER. They also could change AER registers, | |
| 143 | +including mask and severity registers. Helper function | |
| 144 | +pci_enable_pcie_error_reporting could be used to enable AER. See | |
| 145 | +section 3.3. | |
| 146 | + | |
| 147 | +Provide callbacks | |
| 148 | +----------------- | |
| 149 | + | |
| 150 | +callback reset_link to reset pci express link | |
| 151 | +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ | |
| 152 | + | |
| 153 | +This callback is used to reset the pci express physical link when a | |
| 154 | +fatal error happens. The root port aer service driver provides a | |
| 155 | +default reset_link function, but different upstream ports might | |
| 156 | +have different specifications to reset pci express link, so all | |
| 157 | +upstream ports should provide their own reset_link functions. | |
| 158 | + | |
| 159 | +In struct pcie_port_service_driver, a new pointer, reset_link, is | |
| 160 | +added. | |
| 161 | +:: | |
| 162 | + | |
| 163 | + pci_ers_result_t (*reset_link) (struct pci_dev *dev); | |
| 164 | + | |
| 165 | +Section 3.2.2.2 provides more detailed info on when to call | |
| 166 | +reset_link. | |
| 167 | + | |
| 168 | +PCI error-recovery callbacks | |
| 169 | +~~~~~~~~~~~~~~~~~~~~~~~~~~~~ | |
| 170 | + | |
| 171 | +The PCI Express AER Root driver uses error callbacks to coordinate | |
| 172 | +with downstream device drivers associated with a hierarchy in question | |
| 173 | +when performing error recovery actions. | |
| 174 | + | |
| 175 | +Data struct pci_driver has a pointer, err_handler, to point to | |
| 176 | +pci_error_handlers who consists of a couple of callback function | |
| 177 | +pointers. AER driver follows the rules defined in | |
| 178 | +pci-error-recovery.txt except pci express specific parts (e.g. | |
| 179 | +reset_link). Pls. refer to pci-error-recovery.txt for detailed | |
| 180 | +definitions of the callbacks. | |
| 181 | + | |
| 182 | +Below sections specify when to call the error callback functions. | |
| 183 | + | |
| 184 | +Correctable errors | |
| 185 | +~~~~~~~~~~~~~~~~~~ | |
| 186 | + | |
| 187 | +Correctable errors pose no impacts on the functionality of | |
| 188 | +the interface. The PCI Express protocol can recover without any | |
| 189 | +software intervention or any loss of data. These errors do not | |
| 190 | +require any recovery actions. The AER driver clears the device's | |
| 191 | +correctable error status register accordingly and logs these errors. | |
| 192 | + | |
| 193 | +Non-correctable (non-fatal and fatal) errors | |
| 194 | +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ | |
| 195 | + | |
| 196 | +If an error message indicates a non-fatal error, performing link reset | |
| 197 | +at upstream is not required. The AER driver calls error_detected(dev, | |
| 198 | +pci_channel_io_normal) to all drivers associated within a hierarchy in | |
| 199 | +question. for example:: | |
| 200 | + | |
| 201 | + EndPoint<==>DownstreamPort B<==>UpstreamPort A<==>RootPort | |
| 202 | + | |
| 203 | +If Upstream port A captures an AER error, the hierarchy consists of | |
| 204 | +Downstream port B and EndPoint. | |
| 205 | + | |
| 206 | +A driver may return PCI_ERS_RESULT_CAN_RECOVER, | |
| 207 | +PCI_ERS_RESULT_DISCONNECT, or PCI_ERS_RESULT_NEED_RESET, depending on | |
| 208 | +whether it can recover or the AER driver calls mmio_enabled as next. | |
| 209 | + | |
| 210 | +If an error message indicates a fatal error, kernel will broadcast | |
| 211 | +error_detected(dev, pci_channel_io_frozen) to all drivers within | |
| 212 | +a hierarchy in question. Then, performing link reset at upstream is | |
| 213 | +necessary. As different kinds of devices might use different approaches | |
| 214 | +to reset link, AER port service driver is required to provide the | |
| 215 | +function to reset link. Firstly, kernel looks for if the upstream | |
| 216 | +component has an aer driver. If it has, kernel uses the reset_link | |
| 217 | +callback of the aer driver. If the upstream component has no aer driver | |
| 218 | +and the port is downstream port, we will perform a hot reset as the | |
| 219 | +default by setting the Secondary Bus Reset bit of the Bridge Control | |
| 220 | +register associated with the downstream port. As for upstream ports, | |
| 221 | +they should provide their own aer service drivers with reset_link | |
| 222 | +function. If error_detected returns PCI_ERS_RESULT_CAN_RECOVER and | |
| 223 | +reset_link returns PCI_ERS_RESULT_RECOVERED, the error handling goes | |
| 224 | +to mmio_enabled. | |
| 225 | + | |
| 226 | +helper functions | |
| 227 | +---------------- | |
| 228 | +:: | |
| 229 | + | |
| 230 | + int pci_enable_pcie_error_reporting(struct pci_dev *dev); | |
| 231 | + | |
| 232 | +pci_enable_pcie_error_reporting enables the device to send error | |
| 233 | +messages to root port when an error is detected. Note that devices | |
| 234 | +don't enable the error reporting by default, so device drivers need | |
| 235 | +call this function to enable it. | |
| 236 | + | |
| 237 | +:: | |
| 238 | + | |
| 239 | + int pci_disable_pcie_error_reporting(struct pci_dev *dev); | |
| 240 | + | |
| 241 | +pci_disable_pcie_error_reporting disables the device to send error | |
| 242 | +messages to root port when an error is detected. | |
| 243 | + | |
| 244 | +:: | |
| 245 | + | |
| 246 | + int pci_cleanup_aer_uncorrect_error_status(struct pci_dev *dev);` | |
| 247 | + | |
| 248 | +pci_cleanup_aer_uncorrect_error_status cleanups the uncorrectable | |
| 249 | +error status register. | |
| 250 | + | |
| 251 | +Frequent Asked Questions | |
| 252 | +------------------------ | |
| 253 | + | |
| 254 | +Q: | |
| 255 | + What happens if a PCI Express device driver does not provide an | |
| 256 | + error recovery handler (pci_driver->err_handler is equal to NULL)? | |
| 257 | + | |
| 258 | +A: | |
| 259 | + The devices attached with the driver won't be recovered. If the | |
| 260 | + error is fatal, kernel will print out warning messages. Please refer | |
| 261 | + to section 3 for more information. | |
| 262 | + | |
| 263 | +Q: | |
| 264 | + What happens if an upstream port service driver does not provide | |
| 265 | + callback reset_link? | |
| 266 | + | |
| 267 | +A: | |
| 268 | + Fatal error recovery will fail if the errors are reported by the | |
| 269 | + upstream ports who are attached by the service driver. | |
| 270 | + | |
| 271 | +Q: | |
| 272 | + How does this infrastructure deal with driver that is not PCI | |
| 273 | + Express aware? | |
| 274 | + | |
| 275 | +A: | |
| 276 | + This infrastructure calls the error callback functions of the | |
| 277 | + driver when an error happens. But if the driver is not aware of | |
| 278 | + PCI Express, the device might not report its own errors to root | |
| 279 | + port. | |
| 280 | + | |
| 281 | +Q: | |
| 282 | + What modifications will that driver need to make it compatible | |
| 283 | + with the PCI Express AER Root driver? | |
| 284 | + | |
| 285 | +A: | |
| 286 | + It could call the helper functions to enable AER in devices and | |
| 287 | + cleanup uncorrectable status register. Pls. refer to section 3.3. | |
| 288 | + | |
| 289 | + | |
| 290 | +Software error injection | |
| 291 | +======================== | |
| 292 | + | |
| 293 | +Debugging PCIe AER error recovery code is quite difficult because it | |
| 294 | +is hard to trigger real hardware errors. Software based error | |
| 295 | +injection can be used to fake various kinds of PCIe errors. | |
| 296 | + | |
| 297 | +First you should enable PCIe AER software error injection in kernel | |
| 298 | +configuration, that is, following item should be in your .config. | |
| 299 | + | |
| 300 | +CONFIG_PCIEAER_INJECT=y or CONFIG_PCIEAER_INJECT=m | |
| 301 | + | |
| 302 | +After reboot with new kernel or insert the module, a device file named | |
| 303 | +/dev/aer_inject should be created. | |
| 304 | + | |
| 305 | +Then, you need a user space tool named aer-inject, which can be gotten | |
| 306 | +from: | |
| 307 | + | |
| 308 | + https://git.kernel.org/cgit/linux/kernel/git/gong.chen/aer-inject.git/ | |
| 309 | + | |
| 310 | +More information about aer-inject can be found in the document comes | |
| 311 | +with its source code. | |
| @@ -1,267 +0,0 @@ | ||
| 1 | − The PCI Express Advanced Error Reporting Driver Guide HOWTO | |
| 2 | − T. Long Nguyen <tom.l.nguyen@intel.com> | |
| 3 | − Yanmin Zhang <yanmin.zhang@intel.com> | |
| 4 | − 07/29/2006 | |
| 5 | − | |
| 6 | − | |
| 7 | −1. Overview | |
| 8 | − | |
| 9 | −1.1 About this guide | |
| 10 | − | |
| 11 | −This guide describes the basics of the PCI Express Advanced Error | |
| 12 | −Reporting (AER) driver and provides information on how to use it, as | |
| 13 | −well as how to enable the drivers of endpoint devices to conform with | |
| 14 | −PCI Express AER driver. | |
| 15 | − | |
| 16 | −1.2 Copyright (C) Intel Corporation 2006. | |
| 17 | − | |
| 18 | −1.3 What is the PCI Express AER Driver? | |
| 19 | − | |
| 20 | −PCI Express error signaling can occur on the PCI Express link itself | |
| 21 | −or on behalf of transactions initiated on the link. PCI Express | |
| 22 | −defines two error reporting paradigms: the baseline capability and | |
| 23 | −the Advanced Error Reporting capability. The baseline capability is | |
| 24 | −required of all PCI Express components providing a minimum defined | |
| 25 | −set of error reporting requirements. Advanced Error Reporting | |
| 26 | −capability is implemented with a PCI Express advanced error reporting | |
| 27 | −extended capability structure providing more robust error reporting. | |
| 28 | − | |
| 29 | −The PCI Express AER driver provides the infrastructure to support PCI | |
| 30 | −Express Advanced Error Reporting capability. The PCI Express AER | |
| 31 | −driver provides three basic functions: | |
| 32 | − | |
| 33 | −- Gathers the comprehensive error information if errors occurred. | |
| 34 | −- Reports error to the users. | |
| 35 | −- Performs error recovery actions. | |
| 36 | − | |
| 37 | −AER driver only attaches root ports which support PCI-Express AER | |
| 38 | −capability. | |
| 39 | − | |
| 40 | − | |
| 41 | −2. User Guide | |
| 42 | − | |
| 43 | −2.1 Include the PCI Express AER Root Driver into the Linux Kernel | |
| 44 | − | |
| 45 | −The PCI Express AER Root driver is a Root Port service driver attached | |
| 46 | −to the PCI Express Port Bus driver. If a user wants to use it, the driver | |
| 47 | −has to be compiled. Option CONFIG_PCIEAER supports this capability. It | |
| 48 | −depends on CONFIG_PCIEPORTBUS, so pls. set CONFIG_PCIEPORTBUS=y and | |
| 49 | −CONFIG_PCIEAER = y. | |
| 50 | − | |
| 51 | −2.2 Load PCI Express AER Root Driver | |
| 52 | − | |
| 53 | −Some systems have AER support in firmware. Enabling Linux AER support at | |
| 54 | −the same time the firmware handles AER may result in unpredictable | |
| 55 | −behavior. Therefore, Linux does not handle AER events unless the firmware | |
| 56 | −grants AER control to the OS via the ACPI _OSC method. See the PCI FW 3.0 | |
| 57 | −Specification for details regarding _OSC usage. | |
| 58 | − | |
| 59 | −2.3 AER error output | |
| 60 | − | |
| 61 | −When a PCIe AER error is captured, an error message will be output to | |
| 62 | −console. If it's a correctable error, it is output as a warning. | |
| 63 | −Otherwise, it is printed as an error. So users could choose different | |
| 64 | −log level to filter out correctable error messages. | |
| 65 | − | |
| 66 | −Below shows an example: | |
| 67 | −0000:50:00.0: PCIe Bus Error: severity=Uncorrected (Fatal), type=Transaction Layer, id=0500(Requester ID) | |
| 68 | −0000:50:00.0: device [8086:0329] error status/mask=00100000/00000000 | |
| 69 | −0000:50:00.0: [20] Unsupported Request (First) | |
| 70 | −0000:50:00.0: TLP Header: 04000001 00200a03 05010000 00050100 | |
| 71 | − | |
| 72 | −In the example, 'Requester ID' means the ID of the device who sends | |
| 73 | −the error message to root port. Pls. refer to pci express specs for | |
| 74 | −other fields. | |
| 75 | − | |
| 76 | −2.4 AER Statistics / Counters | |
| 77 | − | |
| 78 | −When PCIe AER errors are captured, the counters / statistics are also exposed | |
| 79 | −in the form of sysfs attributes which are documented at | |
| 80 | −Documentation/ABI/testing/sysfs-bus-pci-devices-aer_stats | |
| 81 | − | |
| 82 | −3. Developer Guide | |
| 83 | − | |
| 84 | −To enable AER aware support requires a software driver to configure | |
| 85 | −the AER capability structure within its device and to provide callbacks. | |
| 86 | − | |
| 87 | −To support AER better, developers need understand how AER does work | |
| 88 | −firstly. | |
| 89 | − | |
| 90 | −PCI Express errors are classified into two types: correctable errors | |
| 91 | −and uncorrectable errors. This classification is based on the impacts | |
| 92 | −of those errors, which may result in degraded performance or function | |
| 93 | −failure. | |
| 94 | − | |
| 95 | −Correctable errors pose no impacts on the functionality of the | |
| 96 | −interface. The PCI Express protocol can recover without any software | |
| 97 | −intervention or any loss of data. These errors are detected and | |
| 98 | −corrected by hardware. Unlike correctable errors, uncorrectable | |
| 99 | −errors impact functionality of the interface. Uncorrectable errors | |
| 100 | −can cause a particular transaction or a particular PCI Express link | |
| 101 | −to be unreliable. Depending on those error conditions, uncorrectable | |
| 102 | −errors are further classified into non-fatal errors and fatal errors. | |
| 103 | −Non-fatal errors cause the particular transaction to be unreliable, | |
| 104 | −but the PCI Express link itself is fully functional. Fatal errors, on | |
| 105 | −the other hand, cause the link to be unreliable. | |
| 106 | − | |
| 107 | −When AER is enabled, a PCI Express device will automatically send an | |
| 108 | −error message to the PCIe root port above it when the device captures | |
| 109 | −an error. The Root Port, upon receiving an error reporting message, | |
| 110 | −internally processes and logs the error message in its PCI Express | |
| 111 | −capability structure. Error information being logged includes storing | |
| 112 | −the error reporting agent's requestor ID into the Error Source | |
| 113 | −Identification Registers and setting the error bits of the Root Error | |
| 114 | −Status Register accordingly. If AER error reporting is enabled in Root | |
| 115 | −Error Command Register, the Root Port generates an interrupt if an | |
| 116 | −error is detected. | |
| 117 | − | |
| 118 | −Note that the errors as described above are related to the PCI Express | |
| 119 | −hierarchy and links. These errors do not include any device specific | |
| 120 | −errors because device specific errors will still get sent directly to | |
| 121 | −the device driver. | |
| 122 | − | |
| 123 | −3.1 Configure the AER capability structure | |
| 124 | − | |
| 125 | −AER aware drivers of PCI Express component need change the device | |
| 126 | −control registers to enable AER. They also could change AER registers, | |
| 127 | −including mask and severity registers. Helper function | |
| 128 | −pci_enable_pcie_error_reporting could be used to enable AER. See | |
| 129 | −section 3.3. | |
| 130 | − | |
| 131 | −3.2. Provide callbacks | |
| 132 | − | |
| 133 | −3.2.1 callback reset_link to reset pci express link | |
| 134 | − | |
| 135 | −This callback is used to reset the pci express physical link when a | |
| 136 | −fatal error happens. The root port aer service driver provides a | |
| 137 | −default reset_link function, but different upstream ports might | |
| 138 | −have different specifications to reset pci express link, so all | |
| 139 | −upstream ports should provide their own reset_link functions. | |
| 140 | − | |
| 141 | −In struct pcie_port_service_driver, a new pointer, reset_link, is | |
| 142 | −added. | |
| 143 | − | |
| 144 | −pci_ers_result_t (*reset_link) (struct pci_dev *dev); | |
| 145 | − | |
| 146 | −Section 3.2.2.2 provides more detailed info on when to call | |
| 147 | −reset_link. | |
| 148 | − | |
| 149 | −3.2.2 PCI error-recovery callbacks | |
| 150 | − | |
| 151 | −The PCI Express AER Root driver uses error callbacks to coordinate | |
| 152 | −with downstream device drivers associated with a hierarchy in question | |
| 153 | −when performing error recovery actions. | |
| 154 | − | |
| 155 | −Data struct pci_driver has a pointer, err_handler, to point to | |
| 156 | −pci_error_handlers who consists of a couple of callback function | |
| 157 | −pointers. AER driver follows the rules defined in | |
| 158 | −pci-error-recovery.txt except pci express specific parts (e.g. | |
| 159 | −reset_link). Pls. refer to pci-error-recovery.txt for detailed | |
| 160 | −definitions of the callbacks. | |
| 161 | − | |
| 162 | −Below sections specify when to call the error callback functions. | |
| 163 | − | |
| 164 | −3.2.2.1 Correctable errors | |
| 165 | − | |
| 166 | −Correctable errors pose no impacts on the functionality of | |
| 167 | −the interface. The PCI Express protocol can recover without any | |
| 168 | −software intervention or any loss of data. These errors do not | |
| 169 | −require any recovery actions. The AER driver clears the device's | |
| 170 | −correctable error status register accordingly and logs these errors. | |
| 171 | − | |
| 172 | −3.2.2.2 Non-correctable (non-fatal and fatal) errors | |
| 173 | − | |
| 174 | −If an error message indicates a non-fatal error, performing link reset | |
| 175 | −at upstream is not required. The AER driver calls error_detected(dev, | |
| 176 | −pci_channel_io_normal) to all drivers associated within a hierarchy in | |
| 177 | −question. for example, | |
| 178 | −EndPoint<==>DownstreamPort B<==>UpstreamPort A<==>RootPort. | |
| 179 | −If Upstream port A captures an AER error, the hierarchy consists of | |
| 180 | −Downstream port B and EndPoint. | |
| 181 | − | |
| 182 | −A driver may return PCI_ERS_RESULT_CAN_RECOVER, | |
| 183 | −PCI_ERS_RESULT_DISCONNECT, or PCI_ERS_RESULT_NEED_RESET, depending on | |
| 184 | −whether it can recover or the AER driver calls mmio_enabled as next. | |
| 185 | − | |
| 186 | −If an error message indicates a fatal error, kernel will broadcast | |
| 187 | −error_detected(dev, pci_channel_io_frozen) to all drivers within | |
| 188 | −a hierarchy in question. Then, performing link reset at upstream is | |
| 189 | −necessary. As different kinds of devices might use different approaches | |
| 190 | −to reset link, AER port service driver is required to provide the | |
| 191 | −function to reset link. Firstly, kernel looks for if the upstream | |
| 192 | −component has an aer driver. If it has, kernel uses the reset_link | |
| 193 | −callback of the aer driver. If the upstream component has no aer driver | |
| 194 | −and the port is downstream port, we will perform a hot reset as the | |
| 195 | −default by setting the Secondary Bus Reset bit of the Bridge Control | |
| 196 | −register associated with the downstream port. As for upstream ports, | |
| 197 | −they should provide their own aer service drivers with reset_link | |
| 198 | −function. If error_detected returns PCI_ERS_RESULT_CAN_RECOVER and | |
| 199 | −reset_link returns PCI_ERS_RESULT_RECOVERED, the error handling goes | |
| 200 | −to mmio_enabled. | |
| 201 | − | |
| 202 | −3.3 helper functions | |
| 203 | − | |
| 204 | −3.3.1 int pci_enable_pcie_error_reporting(struct pci_dev *dev); | |
| 205 | −pci_enable_pcie_error_reporting enables the device to send error | |
| 206 | −messages to root port when an error is detected. Note that devices | |
| 207 | −don't enable the error reporting by default, so device drivers need | |
| 208 | −call this function to enable it. | |
| 209 | − | |
| 210 | −3.3.2 int pci_disable_pcie_error_reporting(struct pci_dev *dev); | |
| 211 | −pci_disable_pcie_error_reporting disables the device to send error | |
| 212 | −messages to root port when an error is detected. | |
| 213 | − | |
| 214 | −3.3.3 int pci_cleanup_aer_uncorrect_error_status(struct pci_dev *dev); | |
| 215 | −pci_cleanup_aer_uncorrect_error_status cleanups the uncorrectable | |
| 216 | −error status register. | |
| 217 | − | |
| 218 | −3.4 Frequent Asked Questions | |
| 219 | − | |
| 220 | −Q: What happens if a PCI Express device driver does not provide an | |
| 221 | −error recovery handler (pci_driver->err_handler is equal to NULL)? | |
| 222 | − | |
| 223 | −A: The devices attached with the driver won't be recovered. If the | |
| 224 | −error is fatal, kernel will print out warning messages. Please refer | |
| 225 | −to section 3 for more information. | |
| 226 | − | |
| 227 | −Q: What happens if an upstream port service driver does not provide | |
| 228 | −callback reset_link? | |
| 229 | − | |
| 230 | −A: Fatal error recovery will fail if the errors are reported by the | |
| 231 | −upstream ports who are attached by the service driver. | |
| 232 | − | |
| 233 | −Q: How does this infrastructure deal with driver that is not PCI | |
| 234 | −Express aware? | |
| 235 | − | |
| 236 | −A: This infrastructure calls the error callback functions of the | |
| 237 | −driver when an error happens. But if the driver is not aware of | |
| 238 | −PCI Express, the device might not report its own errors to root | |
| 239 | −port. | |
| 240 | − | |
| 241 | −Q: What modifications will that driver need to make it compatible | |
| 242 | −with the PCI Express AER Root driver? | |
| 243 | − | |
| 244 | −A: It could call the helper functions to enable AER in devices and | |
| 245 | −cleanup uncorrectable status register. Pls. refer to section 3.3. | |
| 246 | − | |
| 247 | − | |
| 248 | −4. Software error injection | |
| 249 | − | |
| 250 | −Debugging PCIe AER error recovery code is quite difficult because it | |
| 251 | −is hard to trigger real hardware errors. Software based error | |
| 252 | −injection can be used to fake various kinds of PCIe errors. | |
| 253 | − | |
| 254 | −First you should enable PCIe AER software error injection in kernel | |
| 255 | −configuration, that is, following item should be in your .config. | |
| 256 | − | |
| 257 | −CONFIG_PCIEAER_INJECT=y or CONFIG_PCIEAER_INJECT=m | |
| 258 | − | |
| 259 | −After reboot with new kernel or insert the module, a device file named | |
| 260 | −/dev/aer_inject should be created. | |
| 261 | − | |
| 262 | −Then, you need a user space tool named aer-inject, which can be gotten | |
| 263 | −from: | |
| 264 | − https://git.kernel.org/cgit/linux/kernel/git/gong.chen/aer-inject.git/ | |
| 265 | − | |
| 266 | −More information about aer-inject can be found in the document comes | |
| 267 | −with its source code. | |
| @@ -0,0 +1,220 @@ | ||
| 1 | +.. SPDX-License-Identifier: GPL-2.0 | |
| 2 | +.. include:: <isonum.txt> | |
| 3 | + | |
| 4 | +=========================================== | |
| 5 | +The PCI Express Port Bus Driver Guide HOWTO | |
| 6 | +=========================================== | |
| 7 | + | |
| 8 | +:Author: Tom L Nguyen tom.l.nguyen@intel.com 11/03/2004 | |
| 9 | +:Copyright: |copy| 2004 Intel Corporation | |
| 10 | + | |
| 11 | +About this guide | |
| 12 | +================ | |
| 13 | + | |
| 14 | +This guide describes the basics of the PCI Express Port Bus driver | |
| 15 | +and provides information on how to enable the service drivers to | |
| 16 | +register/unregister with the PCI Express Port Bus Driver. | |
| 17 | + | |
| 18 | + | |
| 19 | +What is the PCI Express Port Bus Driver | |
| 20 | +======================================= | |
| 21 | + | |
| 22 | +A PCI Express Port is a logical PCI-PCI Bridge structure. There | |
| 23 | +are two types of PCI Express Port: the Root Port and the Switch | |
| 24 | +Port. The Root Port originates a PCI Express link from a PCI Express | |
| 25 | +Root Complex and the Switch Port connects PCI Express links to | |
| 26 | +internal logical PCI buses. The Switch Port, which has its secondary | |
| 27 | +bus representing the switch's internal routing logic, is called the | |
| 28 | +switch's Upstream Port. The switch's Downstream Port is bridging from | |
| 29 | +switch's internal routing bus to a bus representing the downstream | |
| 30 | +PCI Express link from the PCI Express Switch. | |
| 31 | + | |
| 32 | +A PCI Express Port can provide up to four distinct functions, | |
| 33 | +referred to in this document as services, depending on its port type. | |
| 34 | +PCI Express Port's services include native hotplug support (HP), | |
| 35 | +power management event support (PME), advanced error reporting | |
| 36 | +support (AER), and virtual channel support (VC). These services may | |
| 37 | +be handled by a single complex driver or be individually distributed | |
| 38 | +and handled by corresponding service drivers. | |
| 39 | + | |
| 40 | +Why use the PCI Express Port Bus Driver? | |
| 41 | +======================================== | |
| 42 | + | |
| 43 | +In existing Linux kernels, the Linux Device Driver Model allows a | |
| 44 | +physical device to be handled by only a single driver. The PCI | |
| 45 | +Express Port is a PCI-PCI Bridge device with multiple distinct | |
| 46 | +services. To maintain a clean and simple solution each service | |
| 47 | +may have its own software service driver. In this case several | |
| 48 | +service drivers will compete for a single PCI-PCI Bridge device. | |
| 49 | +For example, if the PCI Express Root Port native hotplug service | |
| 50 | +driver is loaded first, it claims a PCI-PCI Bridge Root Port. The | |
| 51 | +kernel therefore does not load other service drivers for that Root | |
| 52 | +Port. In other words, it is impossible to have multiple service | |
| 53 | +drivers load and run on a PCI-PCI Bridge device simultaneously | |
| 54 | +using the current driver model. | |
| 55 | + | |
| 56 | +To enable multiple service drivers running simultaneously requires | |
| 57 | +having a PCI Express Port Bus driver, which manages all populated | |
| 58 | +PCI Express Ports and distributes all provided service requests | |
| 59 | +to the corresponding service drivers as required. Some key | |
| 60 | +advantages of using the PCI Express Port Bus driver are listed below: | |
| 61 | + | |
| 62 | + - Allow multiple service drivers to run simultaneously on | |
| 63 | + a PCI-PCI Bridge Port device. | |
| 64 | + | |
| 65 | + - Allow service drivers implemented in an independent | |
| 66 | + staged approach. | |
| 67 | + | |
| 68 | + - Allow one service driver to run on multiple PCI-PCI Bridge | |
| 69 | + Port devices. | |
| 70 | + | |
| 71 | + - Manage and distribute resources of a PCI-PCI Bridge Port | |
| 72 | + device to requested service drivers. | |
| 73 | + | |
| 74 | +Configuring the PCI Express Port Bus Driver vs. Service Drivers | |
| 75 | +=============================================================== | |
| 76 | + | |
| 77 | +Including the PCI Express Port Bus Driver Support into the Kernel | |
| 78 | +----------------------------------------------------------------- | |
| 79 | + | |
| 80 | +Including the PCI Express Port Bus driver depends on whether the PCI | |
| 81 | +Express support is included in the kernel config. The kernel will | |
| 82 | +automatically include the PCI Express Port Bus driver as a kernel | |
| 83 | +driver when the PCI Express support is enabled in the kernel. | |
| 84 | + | |
| 85 | +Enabling Service Driver Support | |
| 86 | +------------------------------- | |
| 87 | + | |
| 88 | +PCI device drivers are implemented based on Linux Device Driver Model. | |
| 89 | +All service drivers are PCI device drivers. As discussed above, it is | |
| 90 | +impossible to load any service driver once the kernel has loaded the | |
| 91 | +PCI Express Port Bus Driver. To meet the PCI Express Port Bus Driver | |
| 92 | +Model requires some minimal changes on existing service drivers that | |
| 93 | +imposes no impact on the functionality of existing service drivers. | |
| 94 | + | |
| 95 | +A service driver is required to use the two APIs shown below to | |
| 96 | +register its service with the PCI Express Port Bus driver (see | |
| 97 | +section 5.2.1 & 5.2.2). It is important that a service driver | |
| 98 | +initializes the pcie_port_service_driver data structure, included in | |
| 99 | +header file /include/linux/pcieport_if.h, before calling these APIs. | |
| 100 | +Failure to do so will result an identity mismatch, which prevents | |
| 101 | +the PCI Express Port Bus driver from loading a service driver. | |
| 102 | + | |
| 103 | +pcie_port_service_register | |
| 104 | +~~~~~~~~~~~~~~~~~~~~~~~~~~ | |
| 105 | +:: | |
| 106 | + | |
| 107 | + int pcie_port_service_register(struct pcie_port_service_driver *new) | |
| 108 | + | |
| 109 | +This API replaces the Linux Driver Model's pci_register_driver API. A | |
| 110 | +service driver should always calls pcie_port_service_register at | |
| 111 | +module init. Note that after service driver being loaded, calls | |
| 112 | +such as pci_enable_device(dev) and pci_set_master(dev) are no longer | |
| 113 | +necessary since these calls are executed by the PCI Port Bus driver. | |
| 114 | + | |
| 115 | +pcie_port_service_unregister | |
| 116 | +~~~~~~~~~~~~~~~~~~~~~~~~~~~~ | |
| 117 | +:: | |
| 118 | + | |
| 119 | + void pcie_port_service_unregister(struct pcie_port_service_driver *new) | |
| 120 | + | |
| 121 | +pcie_port_service_unregister replaces the Linux Driver Model's | |
| 122 | +pci_unregister_driver. It's always called by service driver when a | |
| 123 | +module exits. | |
| 124 | + | |
| 125 | +Sample Code | |
| 126 | +~~~~~~~~~~~ | |
| 127 | + | |
| 128 | +Below is sample service driver code to initialize the port service | |
| 129 | +driver data structure. | |
| 130 | +:: | |
| 131 | + | |
| 132 | + static struct pcie_port_service_id service_id[] = { { | |
| 133 | + .vendor = PCI_ANY_ID, | |
| 134 | + .device = PCI_ANY_ID, | |
| 135 | + .port_type = PCIE_RC_PORT, | |
| 136 | + .service_type = PCIE_PORT_SERVICE_AER, | |
| 137 | + }, { /* end: all zeroes */ } | |
| 138 | + }; | |
| 139 | + | |
| 140 | + static struct pcie_port_service_driver root_aerdrv = { | |
| 141 | + .name = (char *)device_name, | |
| 142 | + .id_table = &service_id[0], | |
| 143 | + | |
| 144 | + .probe = aerdrv_load, | |
| 145 | + .remove = aerdrv_unload, | |
| 146 | + | |
| 147 | + .suspend = aerdrv_suspend, | |
| 148 | + .resume = aerdrv_resume, | |
| 149 | + }; | |
| 150 | + | |
| 151 | +Below is a sample code for registering/unregistering a service | |
| 152 | +driver. | |
| 153 | +:: | |
| 154 | + | |
| 155 | + static int __init aerdrv_service_init(void) | |
| 156 | + { | |
| 157 | + int retval = 0; | |
| 158 | + | |
| 159 | + retval = pcie_port_service_register(&root_aerdrv); | |
| 160 | + if (!retval) { | |
| 161 | + /* | |
| 162 | + * FIX ME | |
| 163 | + */ | |
| 164 | + } | |
| 165 | + return retval; | |
| 166 | + } | |
| 167 | + | |
| 168 | + static void __exit aerdrv_service_exit(void) | |
| 169 | + { | |
| 170 | + pcie_port_service_unregister(&root_aerdrv); | |
| 171 | + } | |
| 172 | + | |
| 173 | + module_init(aerdrv_service_init); | |
| 174 | + module_exit(aerdrv_service_exit); | |
| 175 | + | |
| 176 | +Possible Resource Conflicts | |
| 177 | +=========================== | |
| 178 | + | |
| 179 | +Since all service drivers of a PCI-PCI Bridge Port device are | |
| 180 | +allowed to run simultaneously, below lists a few of possible resource | |
| 181 | +conflicts with proposed solutions. | |
| 182 | + | |
| 183 | +MSI and MSI-X Vector Resource | |
| 184 | +----------------------------- | |
| 185 | + | |
| 186 | +Once MSI or MSI-X interrupts are enabled on a device, it stays in this | |
| 187 | +mode until they are disabled again. Since service drivers of the same | |
| 188 | +PCI-PCI Bridge port share the same physical device, if an individual | |
| 189 | +service driver enables or disables MSI/MSI-X mode it may result | |
| 190 | +unpredictable behavior. | |
| 191 | + | |
| 192 | +To avoid this situation all service drivers are not permitted to | |
| 193 | +switch interrupt mode on its device. The PCI Express Port Bus driver | |
| 194 | +is responsible for determining the interrupt mode and this should be | |
| 195 | +transparent to service drivers. Service drivers need to know only | |
| 196 | +the vector IRQ assigned to the field irq of struct pcie_device, which | |
| 197 | +is passed in when the PCI Express Port Bus driver probes each service | |
| 198 | +driver. Service drivers should use (struct pcie_device*)dev->irq to | |
| 199 | +call request_irq/free_irq. In addition, the interrupt mode is stored | |
| 200 | +in the field interrupt_mode of struct pcie_device. | |
| 201 | + | |
| 202 | +PCI Memory/IO Mapped Regions | |
| 203 | +---------------------------- | |
| 204 | + | |
| 205 | +Service drivers for PCI Express Power Management (PME), Advanced | |
| 206 | +Error Reporting (AER), Hot-Plug (HP) and Virtual Channel (VC) access | |
| 207 | +PCI configuration space on the PCI Express port. In all cases the | |
| 208 | +registers accessed are independent of each other. This patch assumes | |
| 209 | +that all service drivers will be well behaved and not overwrite | |
| 210 | +other service driver's configuration settings. | |
| 211 | + | |
| 212 | +PCI Config Registers | |
| 213 | +-------------------- | |
| 214 | + | |
| 215 | +Each service driver runs its PCI config operations on its own | |
| 216 | +capability structure except the PCI Express capability structure, in | |
| 217 | +which Root Control register and Device Control register are shared | |
| 218 | +between PME and AER. This patch assumes that all service drivers | |
| 219 | +will be well behaved and not overwrite other service driver's | |
| 220 | +configuration settings. | |
| @@ -0,0 +1,143 @@ | ||
| 1 | +.. _up_doc: | |
| 2 | + | |
| 3 | +RCU on Uniprocessor Systems | |
| 4 | +=========================== | |
| 5 | + | |
| 6 | +A common misconception is that, on UP systems, the call_rcu() primitive | |
| 7 | +may immediately invoke its function. The basis of this misconception | |
| 8 | +is that since there is only one CPU, it should not be necessary to | |
| 9 | +wait for anything else to get done, since there are no other CPUs for | |
| 10 | +anything else to be happening on. Although this approach will *sort of* | |
| 11 | +work a surprising amount of the time, it is a very bad idea in general. | |
| 12 | +This document presents three examples that demonstrate exactly how bad | |
| 13 | +an idea this is. | |
| 14 | + | |
| 15 | +Example 1: softirq Suicide | |
| 16 | +-------------------------- | |
| 17 | + | |
| 18 | +Suppose that an RCU-based algorithm scans a linked list containing | |
| 19 | +elements A, B, and C in process context, and can delete elements from | |
| 20 | +this same list in softirq context. Suppose that the process-context scan | |
| 21 | +is referencing element B when it is interrupted by softirq processing, | |
| 22 | +which deletes element B, and then invokes call_rcu() to free element B | |
| 23 | +after a grace period. | |
| 24 | + | |
| 25 | +Now, if call_rcu() were to directly invoke its arguments, then upon return | |
| 26 | +from softirq, the list scan would find itself referencing a newly freed | |
| 27 | +element B. This situation can greatly decrease the life expectancy of | |
| 28 | +your kernel. | |
| 29 | + | |
| 30 | +This same problem can occur if call_rcu() is invoked from a hardware | |
| 31 | +interrupt handler. | |
| 32 | + | |
| 33 | +Example 2: Function-Call Fatality | |
| 34 | +--------------------------------- | |
| 35 | + | |
| 36 | +Of course, one could avert the suicide described in the preceding example | |
| 37 | +by having call_rcu() directly invoke its arguments only if it was called | |
| 38 | +from process context. However, this can fail in a similar manner. | |
| 39 | + | |
| 40 | +Suppose that an RCU-based algorithm again scans a linked list containing | |
| 41 | +elements A, B, and C in process contexts, but that it invokes a function | |
| 42 | +on each element as it is scanned. Suppose further that this function | |
| 43 | +deletes element B from the list, then passes it to call_rcu() for deferred | |
| 44 | +freeing. This may be a bit unconventional, but it is perfectly legal | |
| 45 | +RCU usage, since call_rcu() must wait for a grace period to elapse. | |
| 46 | +Therefore, in this case, allowing call_rcu() to immediately invoke | |
| 47 | +its arguments would cause it to fail to make the fundamental guarantee | |
| 48 | +underlying RCU, namely that call_rcu() defers invoking its arguments until | |
| 49 | +all RCU read-side critical sections currently executing have completed. | |
| 50 | + | |
| 51 | +Quick Quiz #1: | |
| 52 | + Why is it *not* legal to invoke synchronize_rcu() in this case? | |
| 53 | + | |
| 54 | +:ref:`Answers to Quick Quiz <answer_quick_quiz_up>` | |
| 55 | + | |
| 56 | +Example 3: Death by Deadlock | |
| 57 | +---------------------------- | |
| 58 | + | |
| 59 | +Suppose that call_rcu() is invoked while holding a lock, and that the | |
| 60 | +callback function must acquire this same lock. In this case, if | |
| 61 | +call_rcu() were to directly invoke the callback, the result would | |
| 62 | +be self-deadlock. | |
| 63 | + | |
| 64 | +In some cases, it would possible to restructure to code so that | |
| 65 | +the call_rcu() is delayed until after the lock is released. However, | |
| 66 | +there are cases where this can be quite ugly: | |
| 67 | + | |
| 68 | +1. If a number of items need to be passed to call_rcu() within | |
| 69 | + the same critical section, then the code would need to create | |
| 70 | + a list of them, then traverse the list once the lock was | |
| 71 | + released. | |
| 72 | + | |
| 73 | +2. In some cases, the lock will be held across some kernel API, | |
| 74 | + so that delaying the call_rcu() until the lock is released | |
| 75 | + requires that the data item be passed up via a common API. | |
| 76 | + It is far better to guarantee that callbacks are invoked | |
| 77 | + with no locks held than to have to modify such APIs to allow | |
| 78 | + arbitrary data items to be passed back up through them. | |
| 79 | + | |
| 80 | +If call_rcu() directly invokes the callback, painful locking restrictions | |
| 81 | +or API changes would be required. | |
| 82 | + | |
| 83 | +Quick Quiz #2: | |
| 84 | + What locking restriction must RCU callbacks respect? | |
| 85 | + | |
| 86 | +:ref:`Answers to Quick Quiz <answer_quick_quiz_up>` | |
| 87 | + | |
| 88 | +Summary | |
| 89 | +------- | |
| 90 | + | |
| 91 | +Permitting call_rcu() to immediately invoke its arguments breaks RCU, | |
| 92 | +even on a UP system. So do not do it! Even on a UP system, the RCU | |
| 93 | +infrastructure *must* respect grace periods, and *must* invoke callbacks | |
| 94 | +from a known environment in which no locks are held. | |
| 95 | + | |
| 96 | +Note that it *is* safe for synchronize_rcu() to return immediately on | |
| 97 | +UP systems, including PREEMPT SMP builds running on UP systems. | |
| 98 | + | |
| 99 | +Quick Quiz #3: | |
| 100 | + Why can't synchronize_rcu() return immediately on UP systems running | |
| 101 | + preemptable RCU? | |
| 102 | + | |
| 103 | +.. _answer_quick_quiz_up: | |
| 104 | + | |
| 105 | +Answer to Quick Quiz #1: | |
| 106 | + Why is it *not* legal to invoke synchronize_rcu() in this case? | |
| 107 | + | |
| 108 | + Because the calling function is scanning an RCU-protected linked | |
| 109 | + list, and is therefore within an RCU read-side critical section. | |
| 110 | + Therefore, the called function has been invoked within an RCU | |
| 111 | + read-side critical section, and is not permitted to block. | |
| 112 | + | |
| 113 | +Answer to Quick Quiz #2: | |
| 114 | + What locking restriction must RCU callbacks respect? | |
| 115 | + | |
| 116 | + Any lock that is acquired within an RCU callback must be acquired | |
| 117 | + elsewhere using an _bh variant of the spinlock primitive. | |
| 118 | + For example, if "mylock" is acquired by an RCU callback, then | |
| 119 | + a process-context acquisition of this lock must use something | |
| 120 | + like spin_lock_bh() to acquire the lock. Please note that | |
| 121 | + it is also OK to use _irq variants of spinlocks, for example, | |
| 122 | + spin_lock_irqsave(). | |
| 123 | + | |
| 124 | + If the process-context code were to simply use spin_lock(), | |
| 125 | + then, since RCU callbacks can be invoked from softirq context, | |
| 126 | + the callback might be called from a softirq that interrupted | |
| 127 | + the process-context critical section. This would result in | |
| 128 | + self-deadlock. | |
| 129 | + | |
| 130 | + This restriction might seem gratuitous, since very few RCU | |
| 131 | + callbacks acquire locks directly. However, a great many RCU | |
| 132 | + callbacks do acquire locks *indirectly*, for example, via | |
| 133 | + the kfree() primitive. | |
| 134 | + | |
| 135 | +Answer to Quick Quiz #3: | |
| 136 | + Why can't synchronize_rcu() return immediately on UP systems | |
| 137 | + running preemptable RCU? | |
| 138 | + | |
| 139 | + Because some other task might have been preempted in the middle | |
| 140 | + of an RCU read-side critical section. If synchronize_rcu() | |
| 141 | + simply immediately returned, it would prematurely signal the | |
| 142 | + end of the grace period, which would come as a nasty shock to | |
| 143 | + that other thread when it started running again. | |
| @@ -1,133 +0,0 @@ | ||
| 1 | −RCU on Uniprocessor Systems | |
| 2 | − | |
| 3 | − | |
| 4 | −A common misconception is that, on UP systems, the call_rcu() primitive | |
| 5 | −may immediately invoke its function. The basis of this misconception | |
| 6 | −is that since there is only one CPU, it should not be necessary to | |
| 7 | −wait for anything else to get done, since there are no other CPUs for | |
| 8 | −anything else to be happening on. Although this approach will -sort- -of- | |
| 9 | −work a surprising amount of the time, it is a very bad idea in general. | |
| 10 | −This document presents three examples that demonstrate exactly how bad | |
| 11 | −an idea this is. | |
| 12 | − | |
| 13 | − | |
| 14 | −Example 1: softirq Suicide | |
| 15 | − | |
| 16 | −Suppose that an RCU-based algorithm scans a linked list containing | |
| 17 | −elements A, B, and C in process context, and can delete elements from | |
| 18 | −this same list in softirq context. Suppose that the process-context scan | |
| 19 | −is referencing element B when it is interrupted by softirq processing, | |
| 20 | −which deletes element B, and then invokes call_rcu() to free element B | |
| 21 | −after a grace period. | |
| 22 | − | |
| 23 | −Now, if call_rcu() were to directly invoke its arguments, then upon return | |
| 24 | −from softirq, the list scan would find itself referencing a newly freed | |
| 25 | −element B. This situation can greatly decrease the life expectancy of | |
| 26 | −your kernel. | |
| 27 | − | |
| 28 | −This same problem can occur if call_rcu() is invoked from a hardware | |
| 29 | −interrupt handler. | |
| 30 | − | |
| 31 | − | |
| 32 | −Example 2: Function-Call Fatality | |
| 33 | − | |
| 34 | −Of course, one could avert the suicide described in the preceding example | |
| 35 | −by having call_rcu() directly invoke its arguments only if it was called | |
| 36 | −from process context. However, this can fail in a similar manner. | |
| 37 | − | |
| 38 | −Suppose that an RCU-based algorithm again scans a linked list containing | |
| 39 | −elements A, B, and C in process contexts, but that it invokes a function | |
| 40 | −on each element as it is scanned. Suppose further that this function | |
| 41 | −deletes element B from the list, then passes it to call_rcu() for deferred | |
| 42 | −freeing. This may be a bit unconventional, but it is perfectly legal | |
| 43 | −RCU usage, since call_rcu() must wait for a grace period to elapse. | |
| 44 | −Therefore, in this case, allowing call_rcu() to immediately invoke | |
| 45 | −its arguments would cause it to fail to make the fundamental guarantee | |
| 46 | −underlying RCU, namely that call_rcu() defers invoking its arguments until | |
| 47 | −all RCU read-side critical sections currently executing have completed. | |
| 48 | − | |
| 49 | −Quick Quiz #1: why is it -not- legal to invoke synchronize_rcu() in | |
| 50 | − this case? | |
| 51 | − | |
| 52 | − | |
| 53 | −Example 3: Death by Deadlock | |
| 54 | − | |
| 55 | −Suppose that call_rcu() is invoked while holding a lock, and that the | |
| 56 | −callback function must acquire this same lock. In this case, if | |
| 57 | −call_rcu() were to directly invoke the callback, the result would | |
| 58 | −be self-deadlock. | |
| 59 | − | |
| 60 | −In some cases, it would possible to restructure to code so that | |
| 61 | −the call_rcu() is delayed until after the lock is released. However, | |
| 62 | −there are cases where this can be quite ugly: | |
| 63 | − | |
| 64 | −1. If a number of items need to be passed to call_rcu() within | |
| 65 | − the same critical section, then the code would need to create | |
| 66 | − a list of them, then traverse the list once the lock was | |
| 67 | − released. | |
| 68 | − | |
| 69 | −2. In some cases, the lock will be held across some kernel API, | |
| 70 | − so that delaying the call_rcu() until the lock is released | |
| 71 | − requires that the data item be passed up via a common API. | |
| 72 | − It is far better to guarantee that callbacks are invoked | |
| 73 | − with no locks held than to have to modify such APIs to allow | |
| 74 | − arbitrary data items to be passed back up through them. | |
| 75 | − | |
| 76 | −If call_rcu() directly invokes the callback, painful locking restrictions | |
| 77 | −or API changes would be required. | |
| 78 | − | |
| 79 | −Quick Quiz #2: What locking restriction must RCU callbacks respect? | |
| 80 | − | |
| 81 | − | |
| 82 | −Summary | |
| 83 | − | |
| 84 | −Permitting call_rcu() to immediately invoke its arguments breaks RCU, | |
| 85 | −even on a UP system. So do not do it! Even on a UP system, the RCU | |
| 86 | −infrastructure -must- respect grace periods, and -must- invoke callbacks | |
| 87 | −from a known environment in which no locks are held. | |
| 88 | − | |
| 89 | −Note that it -is- safe for synchronize_rcu() to return immediately on | |
| 90 | −UP systems, including !PREEMPT SMP builds running on UP systems. | |
| 91 | − | |
| 92 | −Quick Quiz #3: Why can't synchronize_rcu() return immediately on | |
| 93 | − UP systems running preemptable RCU? | |
| 94 | − | |
| 95 | − | |
| 96 | −Answer to Quick Quiz #1: | |
| 97 | − Why is it -not- legal to invoke synchronize_rcu() in this case? | |
| 98 | − | |
| 99 | − Because the calling function is scanning an RCU-protected linked | |
| 100 | − list, and is therefore within an RCU read-side critical section. | |
| 101 | − Therefore, the called function has been invoked within an RCU | |
| 102 | − read-side critical section, and is not permitted to block. | |
| 103 | − | |
| 104 | −Answer to Quick Quiz #2: | |
| 105 | − What locking restriction must RCU callbacks respect? | |
| 106 | − | |
| 107 | − Any lock that is acquired within an RCU callback must be | |
| 108 | − acquired elsewhere using an _irq variant of the spinlock | |
| 109 | − primitive. For example, if "mylock" is acquired by an | |
| 110 | − RCU callback, then a process-context acquisition of this | |
| 111 | − lock must use something like spin_lock_irqsave() to | |
| 112 | − acquire the lock. | |
| 113 | − | |
| 114 | − If the process-context code were to simply use spin_lock(), | |
| 115 | − then, since RCU callbacks can be invoked from softirq context, | |
| 116 | − the callback might be called from a softirq that interrupted | |
| 117 | − the process-context critical section. This would result in | |
| 118 | − self-deadlock. | |
| 119 | − | |
| 120 | − This restriction might seem gratuitous, since very few RCU | |
| 121 | − callbacks acquire locks directly. However, a great many RCU | |
| 122 | − callbacks do acquire locks -indirectly-, for example, via | |
| 123 | − the kfree() primitive. | |
| 124 | − | |
| 125 | −Answer to Quick Quiz #3: | |
| 126 | − Why can't synchronize_rcu() return immediately on UP systems | |
| 127 | − running preemptable RCU? | |
| 128 | − | |
| 129 | − Because some other task might have been preempted in the middle | |
| 130 | − of an RCU read-side critical section. If synchronize_rcu() | |
| 131 | − simply immediately returned, it would prematurely signal the | |
| 132 | − end of the grace period, which would come as a nasty shock to | |
| 133 | − that other thread when it started running again. | |
| @@ -0,0 +1,19 @@ | ||
| 1 | +.. _rcu_concepts: | |
| 2 | + | |
| 3 | +============ | |
| 4 | +RCU concepts | |
| 5 | +============ | |
| 6 | + | |
| 7 | +.. toctree:: | |
| 8 | + :maxdepth: 1 | |
| 9 | + | |
| 10 | + rcu | |
| 11 | + listRCU | |
| 12 | + UP | |
| 13 | + | |
| 14 | +.. only:: subproject and html | |
| 15 | + | |
| 16 | + Indices | |
| 17 | + ======= | |
| 18 | + | |
| 19 | + * :ref:`genindex` | |
| @@ -0,0 +1,321 @@ | ||
| 1 | +.. _list_rcu_doc: | |
| 2 | + | |
| 3 | +Using RCU to Protect Read-Mostly Linked Lists | |
| 4 | +============================================= | |
| 5 | + | |
| 6 | +One of the best applications of RCU is to protect read-mostly linked lists | |
| 7 | +("struct list_head" in list.h). One big advantage of this approach | |
| 8 | +is that all of the required memory barriers are included for you in | |
| 9 | +the list macros. This document describes several applications of RCU, | |
| 10 | +with the best fits first. | |
| 11 | + | |
| 12 | +Example 1: Read-Side Action Taken Outside of Lock, No In-Place Updates | |
| 13 | +---------------------------------------------------------------------- | |
| 14 | + | |
| 15 | +The best applications are cases where, if reader-writer locking were | |
| 16 | +used, the read-side lock would be dropped before taking any action | |
| 17 | +based on the results of the search. The most celebrated example is | |
| 18 | +the routing table. Because the routing table is tracking the state of | |
| 19 | +equipment outside of the computer, it will at times contain stale data. | |
| 20 | +Therefore, once the route has been computed, there is no need to hold | |
| 21 | +the routing table static during transmission of the packet. After all, | |
| 22 | +you can hold the routing table static all you want, but that won't keep | |
| 23 | +the external Internet from changing, and it is the state of the external | |
| 24 | +Internet that really matters. In addition, routing entries are typically | |
| 25 | +added or deleted, rather than being modified in place. | |
| 26 | + | |
| 27 | +A straightforward example of this use of RCU may be found in the | |
| 28 | +system-call auditing support. For example, a reader-writer locked | |
| 29 | +implementation of audit_filter_task() might be as follows:: | |
| 30 | + | |
| 31 | + static enum audit_state audit_filter_task(struct task_struct *tsk) | |
| 32 | + { | |
| 33 | + struct audit_entry *e; | |
| 34 | + enum audit_state state; | |
| 35 | + | |
| 36 | + read_lock(&auditsc_lock); | |
| 37 | + /* Note: audit_netlink_sem held by caller. */ | |
| 38 | + list_for_each_entry(e, &audit_tsklist, list) { | |
| 39 | + if (audit_filter_rules(tsk, &e->rule, NULL, &state)) { | |
| 40 | + read_unlock(&auditsc_lock); | |
| 41 | + return state; | |
| 42 | + } | |
| 43 | + } | |
| 44 | + read_unlock(&auditsc_lock); | |
| 45 | + return AUDIT_BUILD_CONTEXT; | |
| 46 | + } | |
| 47 | + | |
| 48 | +Here the list is searched under the lock, but the lock is dropped before | |
| 49 | +the corresponding value is returned. By the time that this value is acted | |
| 50 | +on, the list may well have been modified. This makes sense, since if | |
| 51 | +you are turning auditing off, it is OK to audit a few extra system calls. | |
| 52 | + | |
| 53 | +This means that RCU can be easily applied to the read side, as follows:: | |
| 54 | + | |
| 55 | + static enum audit_state audit_filter_task(struct task_struct *tsk) | |
| 56 | + { | |
| 57 | + struct audit_entry *e; | |
| 58 | + enum audit_state state; | |
| 59 | + | |
| 60 | + rcu_read_lock(); | |
| 61 | + /* Note: audit_netlink_sem held by caller. */ | |
| 62 | + list_for_each_entry_rcu(e, &audit_tsklist, list) { | |
| 63 | + if (audit_filter_rules(tsk, &e->rule, NULL, &state)) { | |
| 64 | + rcu_read_unlock(); | |
| 65 | + return state; | |
| 66 | + } | |
| 67 | + } | |
| 68 | + rcu_read_unlock(); | |
| 69 | + return AUDIT_BUILD_CONTEXT; | |
| 70 | + } | |
| 71 | + | |
| 72 | +The read_lock() and read_unlock() calls have become rcu_read_lock() | |
| 73 | +and rcu_read_unlock(), respectively, and the list_for_each_entry() has | |
| 74 | +become list_for_each_entry_rcu(). The _rcu() list-traversal primitives | |
| 75 | +insert the read-side memory barriers that are required on DEC Alpha CPUs. | |
| 76 | + | |
| 77 | +The changes to the update side are also straightforward. A reader-writer | |
| 78 | +lock might be used as follows for deletion and insertion:: | |
| 79 | + | |
| 80 | + static inline int audit_del_rule(struct audit_rule *rule, | |
| 81 | + struct list_head *list) | |
| 82 | + { | |
| 83 | + struct audit_entry *e; | |
| 84 | + | |
| 85 | + write_lock(&auditsc_lock); | |
| 86 | + list_for_each_entry(e, list, list) { | |
| 87 | + if (!audit_compare_rule(rule, &e->rule)) { | |
| 88 | + list_del(&e->list); | |
| 89 | + write_unlock(&auditsc_lock); | |
| 90 | + return 0; | |
| 91 | + } | |
| 92 | + } | |
| 93 | + write_unlock(&auditsc_lock); | |
| 94 | + return -EFAULT; /* No matching rule */ | |
| 95 | + } | |
| 96 | + | |
| 97 | + static inline int audit_add_rule(struct audit_entry *entry, | |
| 98 | + struct list_head *list) | |
| 99 | + { | |
| 100 | + write_lock(&auditsc_lock); | |
| 101 | + if (entry->rule.flags & AUDIT_PREPEND) { | |
| 102 | + entry->rule.flags &= ~AUDIT_PREPEND; | |
| 103 | + list_add(&entry->list, list); | |
| 104 | + } else { | |
| 105 | + list_add_tail(&entry->list, list); | |
| 106 | + } | |
| 107 | + write_unlock(&auditsc_lock); | |
| 108 | + return 0; | |
| 109 | + } | |
| 110 | + | |
| 111 | +Following are the RCU equivalents for these two functions:: | |
| 112 | + | |
| 113 | + static inline int audit_del_rule(struct audit_rule *rule, | |
| 114 | + struct list_head *list) | |
| 115 | + { | |
| 116 | + struct audit_entry *e; | |
| 117 | + | |
| 118 | + /* Do not use the _rcu iterator here, since this is the only | |
| 119 | + * deletion routine. */ | |
| 120 | + list_for_each_entry(e, list, list) { | |
| 121 | + if (!audit_compare_rule(rule, &e->rule)) { | |
| 122 | + list_del_rcu(&e->list); | |
| 123 | + call_rcu(&e->rcu, audit_free_rule); | |
| 124 | + return 0; | |
| 125 | + } | |
| 126 | + } | |
| 127 | + return -EFAULT; /* No matching rule */ | |
| 128 | + } | |
| 129 | + | |
| 130 | + static inline int audit_add_rule(struct audit_entry *entry, | |
| 131 | + struct list_head *list) | |
| 132 | + { | |
| 133 | + if (entry->rule.flags & AUDIT_PREPEND) { | |
| 134 | + entry->rule.flags &= ~AUDIT_PREPEND; | |
| 135 | + list_add_rcu(&entry->list, list); | |
| 136 | + } else { | |
| 137 | + list_add_tail_rcu(&entry->list, list); | |
| 138 | + } | |
| 139 | + return 0; | |
| 140 | + } | |
| 141 | + | |
| 142 | +Normally, the write_lock() and write_unlock() would be replaced by | |
| 143 | +a spin_lock() and a spin_unlock(), but in this case, all callers hold | |
| 144 | +audit_netlink_sem, so no additional locking is required. The auditsc_lock | |
| 145 | +can therefore be eliminated, since use of RCU eliminates the need for | |
| 146 | +writers to exclude readers. Normally, the write_lock() calls would | |
| 147 | +be converted into spin_lock() calls. | |
| 148 | + | |
| 149 | +The list_del(), list_add(), and list_add_tail() primitives have been | |
| 150 | +replaced by list_del_rcu(), list_add_rcu(), and list_add_tail_rcu(). | |
| 151 | +The _rcu() list-manipulation primitives add memory barriers that are | |
| 152 | +needed on weakly ordered CPUs (most of them!). The list_del_rcu() | |
| 153 | +primitive omits the pointer poisoning debug-assist code that would | |
| 154 | +otherwise cause concurrent readers to fail spectacularly. | |
| 155 | + | |
| 156 | +So, when readers can tolerate stale data and when entries are either added | |
| 157 | +or deleted, without in-place modification, it is very easy to use RCU! | |
| 158 | + | |
| 159 | +Example 2: Handling In-Place Updates | |
| 160 | +------------------------------------ | |
| 161 | + | |
| 162 | +The system-call auditing code does not update auditing rules in place. | |
| 163 | +However, if it did, reader-writer-locked code to do so might look as | |
| 164 | +follows (presumably, the field_count is only permitted to decrease, | |
| 165 | +otherwise, the added fields would need to be filled in):: | |
| 166 | + | |
| 167 | + static inline int audit_upd_rule(struct audit_rule *rule, | |
| 168 | + struct list_head *list, | |
| 169 | + __u32 newaction, | |
| 170 | + __u32 newfield_count) | |
| 171 | + { | |
| 172 | + struct audit_entry *e; | |
| 173 | + struct audit_newentry *ne; | |
| 174 | + | |
| 175 | + write_lock(&auditsc_lock); | |
| 176 | + /* Note: audit_netlink_sem held by caller. */ | |
| 177 | + list_for_each_entry(e, list, list) { | |
| 178 | + if (!audit_compare_rule(rule, &e->rule)) { | |
| 179 | + e->rule.action = newaction; | |
| 180 | + e->rule.file_count = newfield_count; | |
| 181 | + write_unlock(&auditsc_lock); | |
| 182 | + return 0; | |
| 183 | + } | |
| 184 | + } | |
| 185 | + write_unlock(&auditsc_lock); | |
| 186 | + return -EFAULT; /* No matching rule */ | |
| 187 | + } | |
| 188 | + | |
| 189 | +The RCU version creates a copy, updates the copy, then replaces the old | |
| 190 | +entry with the newly updated entry. This sequence of actions, allowing | |
| 191 | +concurrent reads while doing a copy to perform an update, is what gives | |
| 192 | +RCU ("read-copy update") its name. The RCU code is as follows:: | |
| 193 | + | |
| 194 | + static inline int audit_upd_rule(struct audit_rule *rule, | |
| 195 | + struct list_head *list, | |
| 196 | + __u32 newaction, | |
| 197 | + __u32 newfield_count) | |
| 198 | + { | |
| 199 | + struct audit_entry *e; | |
| 200 | + struct audit_newentry *ne; | |
| 201 | + | |
| 202 | + list_for_each_entry(e, list, list) { | |
| 203 | + if (!audit_compare_rule(rule, &e->rule)) { | |
| 204 | + ne = kmalloc(sizeof(*entry), GFP_ATOMIC); | |
| 205 | + if (ne == NULL) | |
| 206 | + return -ENOMEM; | |
| 207 | + audit_copy_rule(&ne->rule, &e->rule); | |
| 208 | + ne->rule.action = newaction; | |
| 209 | + ne->rule.file_count = newfield_count; | |
| 210 | + list_replace_rcu(&e->list, &ne->list); | |
| 211 | + call_rcu(&e->rcu, audit_free_rule); | |
| 212 | + return 0; | |
| 213 | + } | |
| 214 | + } | |
| 215 | + return -EFAULT; /* No matching rule */ | |
| 216 | + } | |
| 217 | + | |
| 218 | +Again, this assumes that the caller holds audit_netlink_sem. Normally, | |
| 219 | +the reader-writer lock would become a spinlock in this sort of code. | |
| 220 | + | |
| 221 | +Example 3: Eliminating Stale Data | |
| 222 | +--------------------------------- | |
| 223 | + | |
| 224 | +The auditing examples above tolerate stale data, as do most algorithms | |
| 225 | +that are tracking external state. Because there is a delay from the | |
| 226 | +time the external state changes before Linux becomes aware of the change, | |
| 227 | +additional RCU-induced staleness is normally not a problem. | |
| 228 | + | |
| 229 | +However, there are many examples where stale data cannot be tolerated. | |
| 230 | +One example in the Linux kernel is the System V IPC (see the ipc_lock() | |
| 231 | +function in ipc/util.c). This code checks a "deleted" flag under a | |
| 232 | +per-entry spinlock, and, if the "deleted" flag is set, pretends that the | |
| 233 | +entry does not exist. For this to be helpful, the search function must | |
| 234 | +return holding the per-entry spinlock, as ipc_lock() does in fact do. | |
| 235 | + | |
| 236 | +Quick Quiz: | |
| 237 | + Why does the search function need to return holding the per-entry lock for | |
| 238 | + this deleted-flag technique to be helpful? | |
| 239 | + | |
| 240 | +:ref:`Answer to Quick Quiz <answer_quick_quiz_list>` | |
| 241 | + | |
| 242 | +If the system-call audit module were to ever need to reject stale data, | |
| 243 | +one way to accomplish this would be to add a "deleted" flag and a "lock" | |
| 244 | +spinlock to the audit_entry structure, and modify audit_filter_task() | |
| 245 | +as follows:: | |
| 246 | + | |
| 247 | + static enum audit_state audit_filter_task(struct task_struct *tsk) | |
| 248 | + { | |
| 249 | + struct audit_entry *e; | |
| 250 | + enum audit_state state; | |
| 251 | + | |
| 252 | + rcu_read_lock(); | |
| 253 | + list_for_each_entry_rcu(e, &audit_tsklist, list) { | |
| 254 | + if (audit_filter_rules(tsk, &e->rule, NULL, &state)) { | |
| 255 | + spin_lock(&e->lock); | |
| 256 | + if (e->deleted) { | |
| 257 | + spin_unlock(&e->lock); | |
| 258 | + rcu_read_unlock(); | |
| 259 | + return AUDIT_BUILD_CONTEXT; | |
| 260 | + } | |
| 261 | + rcu_read_unlock(); | |
| 262 | + return state; | |
| 263 | + } | |
| 264 | + } | |
| 265 | + rcu_read_unlock(); | |
| 266 | + return AUDIT_BUILD_CONTEXT; | |
| 267 | + } | |
| 268 | + | |
| 269 | +Note that this example assumes that entries are only added and deleted. | |
| 270 | +Additional mechanism is required to deal correctly with the | |
| 271 | +update-in-place performed by audit_upd_rule(). For one thing, | |
| 272 | +audit_upd_rule() would need additional memory barriers to ensure | |
| 273 | +that the list_add_rcu() was really executed before the list_del_rcu(). | |
| 274 | + | |
| 275 | +The audit_del_rule() function would need to set the "deleted" | |
| 276 | +flag under the spinlock as follows:: | |
| 277 | + | |
| 278 | + static inline int audit_del_rule(struct audit_rule *rule, | |
| 279 | + struct list_head *list) | |
| 280 | + { | |
| 281 | + struct audit_entry *e; | |
| 282 | + | |
| 283 | + /* Do not need to use the _rcu iterator here, since this | |
| 284 | + * is the only deletion routine. */ | |
| 285 | + list_for_each_entry(e, list, list) { | |
| 286 | + if (!audit_compare_rule(rule, &e->rule)) { | |
| 287 | + spin_lock(&e->lock); | |
| 288 | + list_del_rcu(&e->list); | |
| 289 | + e->deleted = 1; | |
| 290 | + spin_unlock(&e->lock); | |
| 291 | + call_rcu(&e->rcu, audit_free_rule); | |
| 292 | + return 0; | |
| 293 | + } | |
| 294 | + } | |
| 295 | + return -EFAULT; /* No matching rule */ | |
| 296 | + } | |
| 297 | + | |
| 298 | +Summary | |
| 299 | +------- | |
| 300 | + | |
| 301 | +Read-mostly list-based data structures that can tolerate stale data are | |
| 302 | +the most amenable to use of RCU. The simplest case is where entries are | |
| 303 | +either added or deleted from the data structure (or atomically modified | |
| 304 | +in place), but non-atomic in-place modifications can be handled by making | |
| 305 | +a copy, updating the copy, then replacing the original with the copy. | |
| 306 | +If stale data cannot be tolerated, then a "deleted" flag may be used | |
| 307 | +in conjunction with a per-entry spinlock in order to allow the search | |
| 308 | +function to reject newly deleted data. | |
| 309 | + | |
| 310 | +.. _answer_quick_quiz_list: | |
| 311 | + | |
| 312 | +Answer to Quick Quiz: | |
| 313 | + Why does the search function need to return holding the per-entry | |
| 314 | + lock for this deleted-flag technique to be helpful? | |
| 315 | + | |
| 316 | + If the search function drops the per-entry lock before returning, | |
| 317 | + then the caller will be processing stale data in any case. If it | |
| 318 | + is really OK to be processing stale data, then you don't need a | |
| 319 | + "deleted" flag. If processing stale data really is a problem, | |
| 320 | + then you need to hold the per-entry lock across all of the code | |
| 321 | + that uses the value that was returned. | |
| @@ -1,315 +0,0 @@ | ||
| 1 | −Using RCU to Protect Read-Mostly Linked Lists | |
| 2 | − | |
| 3 | − | |
| 4 | −One of the best applications of RCU is to protect read-mostly linked lists | |
| 5 | −("struct list_head" in list.h). One big advantage of this approach | |
| 6 | −is that all of the required memory barriers are included for you in | |
| 7 | −the list macros. This document describes several applications of RCU, | |
| 8 | −with the best fits first. | |
| 9 | − | |
| 10 | − | |
| 11 | −Example 1: Read-Side Action Taken Outside of Lock, No In-Place Updates | |
| 12 | − | |
| 13 | −The best applications are cases where, if reader-writer locking were | |
| 14 | −used, the read-side lock would be dropped before taking any action | |
| 15 | −based on the results of the search. The most celebrated example is | |
| 16 | −the routing table. Because the routing table is tracking the state of | |
| 17 | −equipment outside of the computer, it will at times contain stale data. | |
| 18 | −Therefore, once the route has been computed, there is no need to hold | |
| 19 | −the routing table static during transmission of the packet. After all, | |
| 20 | −you can hold the routing table static all you want, but that won't keep | |
| 21 | −the external Internet from changing, and it is the state of the external | |
| 22 | −Internet that really matters. In addition, routing entries are typically | |
| 23 | −added or deleted, rather than being modified in place. | |
| 24 | − | |
| 25 | −A straightforward example of this use of RCU may be found in the | |
| 26 | −system-call auditing support. For example, a reader-writer locked | |
| 27 | −implementation of audit_filter_task() might be as follows: | |
| 28 | − | |
| 29 | − static enum audit_state audit_filter_task(struct task_struct *tsk) | |
| 30 | − { | |
| 31 | − struct audit_entry *e; | |
| 32 | − enum audit_state state; | |
| 33 | − | |
| 34 | − read_lock(&auditsc_lock); | |
| 35 | − /* Note: audit_netlink_sem held by caller. */ | |
| 36 | − list_for_each_entry(e, &audit_tsklist, list) { | |
| 37 | − if (audit_filter_rules(tsk, &e->rule, NULL, &state)) { | |
| 38 | − read_unlock(&auditsc_lock); | |
| 39 | − return state; | |
| 40 | − } | |
| 41 | − } | |
| 42 | − read_unlock(&auditsc_lock); | |
| 43 | − return AUDIT_BUILD_CONTEXT; | |
| 44 | − } | |
| 45 | − | |
| 46 | −Here the list is searched under the lock, but the lock is dropped before | |
| 47 | −the corresponding value is returned. By the time that this value is acted | |
| 48 | −on, the list may well have been modified. This makes sense, since if | |
| 49 | −you are turning auditing off, it is OK to audit a few extra system calls. | |
| 50 | − | |
| 51 | −This means that RCU can be easily applied to the read side, as follows: | |
| 52 | − | |
| 53 | − static enum audit_state audit_filter_task(struct task_struct *tsk) | |
| 54 | − { | |
| 55 | − struct audit_entry *e; | |
| 56 | − enum audit_state state; | |
| 57 | − | |
| 58 | − rcu_read_lock(); | |
| 59 | − /* Note: audit_netlink_sem held by caller. */ | |
| 60 | − list_for_each_entry_rcu(e, &audit_tsklist, list) { | |
| 61 | − if (audit_filter_rules(tsk, &e->rule, NULL, &state)) { | |
| 62 | − rcu_read_unlock(); | |
| 63 | − return state; | |
| 64 | − } | |
| 65 | − } | |
| 66 | − rcu_read_unlock(); | |
| 67 | − return AUDIT_BUILD_CONTEXT; | |
| 68 | − } | |
| 69 | − | |
| 70 | −The read_lock() and read_unlock() calls have become rcu_read_lock() | |
| 71 | −and rcu_read_unlock(), respectively, and the list_for_each_entry() has | |
| 72 | −become list_for_each_entry_rcu(). The _rcu() list-traversal primitives | |
| 73 | −insert the read-side memory barriers that are required on DEC Alpha CPUs. | |
| 74 | − | |
| 75 | −The changes to the update side are also straightforward. A reader-writer | |
| 76 | −lock might be used as follows for deletion and insertion: | |
| 77 | − | |
| 78 | − static inline int audit_del_rule(struct audit_rule *rule, | |
| 79 | − struct list_head *list) | |
| 80 | − { | |
| 81 | − struct audit_entry *e; | |
| 82 | − | |
| 83 | − write_lock(&auditsc_lock); | |
| 84 | − list_for_each_entry(e, list, list) { | |
| 85 | − if (!audit_compare_rule(rule, &e->rule)) { | |
| 86 | − list_del(&e->list); | |
| 87 | − write_unlock(&auditsc_lock); | |
| 88 | − return 0; | |
| 89 | − } | |
| 90 | − } | |
| 91 | − write_unlock(&auditsc_lock); | |
| 92 | − return -EFAULT; /* No matching rule */ | |
| 93 | − } | |
| 94 | − | |
| 95 | − static inline int audit_add_rule(struct audit_entry *entry, | |
| 96 | − struct list_head *list) | |
| 97 | − { | |
| 98 | − write_lock(&auditsc_lock); | |
| 99 | − if (entry->rule.flags & AUDIT_PREPEND) { | |
| 100 | − entry->rule.flags &= ~AUDIT_PREPEND; | |
| 101 | − list_add(&entry->list, list); | |
| 102 | − } else { | |
| 103 | − list_add_tail(&entry->list, list); | |
| 104 | − } | |
| 105 | − write_unlock(&auditsc_lock); | |
| 106 | − return 0; | |
| 107 | − } | |
| 108 | − | |
| 109 | −Following are the RCU equivalents for these two functions: | |
| 110 | − | |
| 111 | − static inline int audit_del_rule(struct audit_rule *rule, | |
| 112 | − struct list_head *list) | |
| 113 | − { | |
| 114 | − struct audit_entry *e; | |
| 115 | − | |
| 116 | − /* Do not use the _rcu iterator here, since this is the only | |
| 117 | − * deletion routine. */ | |
| 118 | − list_for_each_entry(e, list, list) { | |
| 119 | − if (!audit_compare_rule(rule, &e->rule)) { | |
| 120 | − list_del_rcu(&e->list); | |
| 121 | − call_rcu(&e->rcu, audit_free_rule); | |
| 122 | − return 0; | |
| 123 | − } | |
| 124 | − } | |
| 125 | − return -EFAULT; /* No matching rule */ | |
| 126 | − } | |
| 127 | − | |
| 128 | − static inline int audit_add_rule(struct audit_entry *entry, | |
| 129 | − struct list_head *list) | |
| 130 | − { | |
| 131 | − if (entry->rule.flags & AUDIT_PREPEND) { | |
| 132 | − entry->rule.flags &= ~AUDIT_PREPEND; | |
| 133 | − list_add_rcu(&entry->list, list); | |
| 134 | − } else { | |
| 135 | − list_add_tail_rcu(&entry->list, list); | |
| 136 | − } | |
| 137 | − return 0; | |
| 138 | − } | |
| 139 | − | |
| 140 | −Normally, the write_lock() and write_unlock() would be replaced by | |
| 141 | −a spin_lock() and a spin_unlock(), but in this case, all callers hold | |
| 142 | −audit_netlink_sem, so no additional locking is required. The auditsc_lock | |
| 143 | −can therefore be eliminated, since use of RCU eliminates the need for | |
| 144 | −writers to exclude readers. Normally, the write_lock() calls would | |
| 145 | −be converted into spin_lock() calls. | |
| 146 | − | |
| 147 | −The list_del(), list_add(), and list_add_tail() primitives have been | |
| 148 | −replaced by list_del_rcu(), list_add_rcu(), and list_add_tail_rcu(). | |
| 149 | −The _rcu() list-manipulation primitives add memory barriers that are | |
| 150 | −needed on weakly ordered CPUs (most of them!). The list_del_rcu() | |
| 151 | −primitive omits the pointer poisoning debug-assist code that would | |
| 152 | −otherwise cause concurrent readers to fail spectacularly. | |
| 153 | − | |
| 154 | −So, when readers can tolerate stale data and when entries are either added | |
| 155 | −or deleted, without in-place modification, it is very easy to use RCU! | |
| 156 | − | |
| 157 | − | |
| 158 | −Example 2: Handling In-Place Updates | |
| 159 | − | |
| 160 | −The system-call auditing code does not update auditing rules in place. | |
| 161 | −However, if it did, reader-writer-locked code to do so might look as | |
| 162 | −follows (presumably, the field_count is only permitted to decrease, | |
| 163 | −otherwise, the added fields would need to be filled in): | |
| 164 | − | |
| 165 | − static inline int audit_upd_rule(struct audit_rule *rule, | |
| 166 | − struct list_head *list, | |
| 167 | − __u32 newaction, | |
| 168 | − __u32 newfield_count) | |
| 169 | − { | |
| 170 | − struct audit_entry *e; | |
| 171 | − struct audit_newentry *ne; | |
| 172 | − | |
| 173 | − write_lock(&auditsc_lock); | |
| 174 | − /* Note: audit_netlink_sem held by caller. */ | |
| 175 | − list_for_each_entry(e, list, list) { | |
| 176 | − if (!audit_compare_rule(rule, &e->rule)) { | |
| 177 | − e->rule.action = newaction; | |
| 178 | − e->rule.file_count = newfield_count; | |
| 179 | − write_unlock(&auditsc_lock); | |
| 180 | − return 0; | |
| 181 | − } | |
| 182 | − } | |
| 183 | − write_unlock(&auditsc_lock); | |
| 184 | − return -EFAULT; /* No matching rule */ | |
| 185 | − } | |
| 186 | − | |
| 187 | −The RCU version creates a copy, updates the copy, then replaces the old | |
| 188 | −entry with the newly updated entry. This sequence of actions, allowing | |
| 189 | −concurrent reads while doing a copy to perform an update, is what gives | |
| 190 | −RCU ("read-copy update") its name. The RCU code is as follows: | |
| 191 | − | |
| 192 | − static inline int audit_upd_rule(struct audit_rule *rule, | |
| 193 | − struct list_head *list, | |
| 194 | − __u32 newaction, | |
| 195 | − __u32 newfield_count) | |
| 196 | − { | |
| 197 | − struct audit_entry *e; | |
| 198 | − struct audit_newentry *ne; | |
| 199 | − | |
| 200 | − list_for_each_entry(e, list, list) { | |
| 201 | − if (!audit_compare_rule(rule, &e->rule)) { | |
| 202 | − ne = kmalloc(sizeof(*entry), GFP_ATOMIC); | |
| 203 | − if (ne == NULL) | |
| 204 | − return -ENOMEM; | |
| 205 | − audit_copy_rule(&ne->rule, &e->rule); | |
| 206 | − ne->rule.action = newaction; | |
| 207 | − ne->rule.file_count = newfield_count; | |
| 208 | − list_replace_rcu(&e->list, &ne->list); | |
| 209 | − call_rcu(&e->rcu, audit_free_rule); | |
| 210 | − return 0; | |
| 211 | − } | |
| 212 | − } | |
| 213 | − return -EFAULT; /* No matching rule */ | |
| 214 | − } | |
| 215 | − | |
| 216 | −Again, this assumes that the caller holds audit_netlink_sem. Normally, | |
| 217 | −the reader-writer lock would become a spinlock in this sort of code. | |
| 218 | − | |
| 219 | − | |
| 220 | −Example 3: Eliminating Stale Data | |
| 221 | − | |
| 222 | −The auditing examples above tolerate stale data, as do most algorithms | |
| 223 | −that are tracking external state. Because there is a delay from the | |
| 224 | −time the external state changes before Linux becomes aware of the change, | |
| 225 | −additional RCU-induced staleness is normally not a problem. | |
| 226 | − | |
| 227 | −However, there are many examples where stale data cannot be tolerated. | |
| 228 | −One example in the Linux kernel is the System V IPC (see the ipc_lock() | |
| 229 | −function in ipc/util.c). This code checks a "deleted" flag under a | |
| 230 | −per-entry spinlock, and, if the "deleted" flag is set, pretends that the | |
| 231 | −entry does not exist. For this to be helpful, the search function must | |
| 232 | −return holding the per-entry spinlock, as ipc_lock() does in fact do. | |
| 233 | − | |
| 234 | −Quick Quiz: Why does the search function need to return holding the | |
| 235 | − per-entry lock for this deleted-flag technique to be helpful? | |
| 236 | − | |
| 237 | −If the system-call audit module were to ever need to reject stale data, | |
| 238 | −one way to accomplish this would be to add a "deleted" flag and a "lock" | |
| 239 | −spinlock to the audit_entry structure, and modify audit_filter_task() | |
| 240 | −as follows: | |
| 241 | − | |
| 242 | − static enum audit_state audit_filter_task(struct task_struct *tsk) | |
| 243 | − { | |
| 244 | − struct audit_entry *e; | |
| 245 | − enum audit_state state; | |
| 246 | − | |
| 247 | − rcu_read_lock(); | |
| 248 | − list_for_each_entry_rcu(e, &audit_tsklist, list) { | |
| 249 | − if (audit_filter_rules(tsk, &e->rule, NULL, &state)) { | |
| 250 | − spin_lock(&e->lock); | |
| 251 | − if (e->deleted) { | |
| 252 | − spin_unlock(&e->lock); | |
| 253 | − rcu_read_unlock(); | |
| 254 | − return AUDIT_BUILD_CONTEXT; | |
| 255 | − } | |
| 256 | − rcu_read_unlock(); | |
| 257 | − return state; | |
| 258 | − } | |
| 259 | − } | |
| 260 | − rcu_read_unlock(); | |
| 261 | − return AUDIT_BUILD_CONTEXT; | |
| 262 | − } | |
| 263 | − | |
| 264 | −Note that this example assumes that entries are only added and deleted. | |
| 265 | −Additional mechanism is required to deal correctly with the | |
| 266 | −update-in-place performed by audit_upd_rule(). For one thing, | |
| 267 | −audit_upd_rule() would need additional memory barriers to ensure | |
| 268 | −that the list_add_rcu() was really executed before the list_del_rcu(). | |
| 269 | − | |
| 270 | −The audit_del_rule() function would need to set the "deleted" | |
| 271 | −flag under the spinlock as follows: | |
| 272 | − | |
| 273 | − static inline int audit_del_rule(struct audit_rule *rule, | |
| 274 | − struct list_head *list) | |
| 275 | − { | |
| 276 | − struct audit_entry *e; | |
| 277 | − | |
| 278 | − /* Do not need to use the _rcu iterator here, since this | |
| 279 | − * is the only deletion routine. */ | |
| 280 | − list_for_each_entry(e, list, list) { | |
| 281 | − if (!audit_compare_rule(rule, &e->rule)) { | |
| 282 | − spin_lock(&e->lock); | |
| 283 | − list_del_rcu(&e->list); | |
| 284 | − e->deleted = 1; | |
| 285 | − spin_unlock(&e->lock); | |
| 286 | − call_rcu(&e->rcu, audit_free_rule); | |
| 287 | − return 0; | |
| 288 | − } | |
| 289 | − } | |
| 290 | − return -EFAULT; /* No matching rule */ | |
| 291 | − } | |
| 292 | − | |
| 293 | − | |
| 294 | −Summary | |
| 295 | − | |
| 296 | −Read-mostly list-based data structures that can tolerate stale data are | |
| 297 | −the most amenable to use of RCU. The simplest case is where entries are | |
| 298 | −either added or deleted from the data structure (or atomically modified | |
| 299 | −in place), but non-atomic in-place modifications can be handled by making | |
| 300 | −a copy, updating the copy, then replacing the original with the copy. | |
| 301 | −If stale data cannot be tolerated, then a "deleted" flag may be used | |
| 302 | −in conjunction with a per-entry spinlock in order to allow the search | |
| 303 | −function to reject newly deleted data. | |
| 304 | − | |
| 305 | − | |
| 306 | −Answer to Quick Quiz | |
| 307 | − Why does the search function need to return holding the per-entry | |
| 308 | − lock for this deleted-flag technique to be helpful? | |
| 309 | − | |
| 310 | − If the search function drops the per-entry lock before returning, | |
| 311 | − then the caller will be processing stale data in any case. If it | |
| 312 | − is really OK to be processing stale data, then you don't need a | |
| 313 | − "deleted" flag. If processing stale data really is a problem, | |
| 314 | − then you need to hold the per-entry lock across all of the code | |
| 315 | − that uses the value that was returned. | |
| @@ -0,0 +1,92 @@ | ||
| 1 | +.. _rcu_doc: | |
| 2 | + | |
| 3 | +RCU Concepts | |
| 4 | +============ | |
| 5 | + | |
| 6 | +The basic idea behind RCU (read-copy update) is to split destructive | |
| 7 | +operations into two parts, one that prevents anyone from seeing the data | |
| 8 | +item being destroyed, and one that actually carries out the destruction. | |
| 9 | +A "grace period" must elapse between the two parts, and this grace period | |
| 10 | +must be long enough that any readers accessing the item being deleted have | |
| 11 | +since dropped their references. For example, an RCU-protected deletion | |
| 12 | +from a linked list would first remove the item from the list, wait for | |
| 13 | +a grace period to elapse, then free the element. See the | |
| 14 | +Documentation/RCU/listRCU.rst file for more information on using RCU with | |
| 15 | +linked lists. | |
| 16 | + | |
| 17 | +Frequently Asked Questions | |
| 18 | +-------------------------- | |
| 19 | + | |
| 20 | +- Why would anyone want to use RCU? | |
| 21 | + | |
| 22 | + The advantage of RCU's two-part approach is that RCU readers need | |
| 23 | + not acquire any locks, perform any atomic instructions, write to | |
| 24 | + shared memory, or (on CPUs other than Alpha) execute any memory | |
| 25 | + barriers. The fact that these operations are quite expensive | |
| 26 | + on modern CPUs is what gives RCU its performance advantages | |
| 27 | + in read-mostly situations. The fact that RCU readers need not | |
| 28 | + acquire locks can also greatly simplify deadlock-avoidance code. | |
| 29 | + | |
| 30 | +- How can the updater tell when a grace period has completed | |
| 31 | + if the RCU readers give no indication when they are done? | |
| 32 | + | |
| 33 | + Just as with spinlocks, RCU readers are not permitted to | |
| 34 | + block, switch to user-mode execution, or enter the idle loop. | |
| 35 | + Therefore, as soon as a CPU is seen passing through any of these | |
| 36 | + three states, we know that that CPU has exited any previous RCU | |
| 37 | + read-side critical sections. So, if we remove an item from a | |
| 38 | + linked list, and then wait until all CPUs have switched context, | |
| 39 | + executed in user mode, or executed in the idle loop, we can | |
| 40 | + safely free up that item. | |
| 41 | + | |
| 42 | + Preemptible variants of RCU (CONFIG_PREEMPT_RCU) get the | |
| 43 | + same effect, but require that the readers manipulate CPU-local | |
| 44 | + counters. These counters allow limited types of blocking within | |
| 45 | + RCU read-side critical sections. SRCU also uses CPU-local | |
| 46 | + counters, and permits general blocking within RCU read-side | |
| 47 | + critical sections. These variants of RCU detect grace periods | |
| 48 | + by sampling these counters. | |
| 49 | + | |
| 50 | +- If I am running on a uniprocessor kernel, which can only do one | |
| 51 | + thing at a time, why should I wait for a grace period? | |
| 52 | + | |
| 53 | + See the Documentation/RCU/UP.rst file for more information. | |
| 54 | + | |
| 55 | +- How can I see where RCU is currently used in the Linux kernel? | |
| 56 | + | |
| 57 | + Search for "rcu_read_lock", "rcu_read_unlock", "call_rcu", | |
| 58 | + "rcu_read_lock_bh", "rcu_read_unlock_bh", "srcu_read_lock", | |
| 59 | + "srcu_read_unlock", "synchronize_rcu", "synchronize_net", | |
| 60 | + "synchronize_srcu", and the other RCU primitives. Or grab one | |
| 61 | + of the cscope databases from: | |
| 62 | + | |
| 63 | + (http://www.rdrop.com/users/paulmck/RCU/linuxusage/rculocktab.html). | |
| 64 | + | |
| 65 | +- What guidelines should I follow when writing code that uses RCU? | |
| 66 | + | |
| 67 | + See the checklist.txt file in this directory. | |
| 68 | + | |
| 69 | +- Why the name "RCU"? | |
| 70 | + | |
| 71 | + "RCU" stands for "read-copy update". The file Documentation/RCU/listRCU.rst | |
| 72 | + has more information on where this name came from, search for | |
| 73 | + "read-copy update" to find it. | |
| 74 | + | |
| 75 | +- I hear that RCU is patented? What is with that? | |
| 76 | + | |
| 77 | + Yes, it is. There are several known patents related to RCU, | |
| 78 | + search for the string "Patent" in RTFP.txt to find them. | |
| 79 | + Of these, one was allowed to lapse by the assignee, and the | |
| 80 | + others have been contributed to the Linux kernel under GPL. | |
| 81 | + There are now also LGPL implementations of user-level RCU | |
| 82 | + available (http://liburcu.org/). | |
| 83 | + | |
| 84 | +- I hear that RCU needs work in order to support realtime kernels? | |
| 85 | + | |
| 86 | + Realtime-friendly RCU can be enabled via the CONFIG_PREEMPT_RCU | |
| 87 | + kernel configuration parameter. | |
| 88 | + | |
| 89 | +- Where can I find more information on RCU? | |
| 90 | + | |
| 91 | + See the RTFP.txt file in this directory. | |
| 92 | + Or point your browser at (http://www.rdrop.com/users/paulmck/RCU/). | |
| @@ -1,89 +0,0 @@ | ||
| 1 | −RCU Concepts | |
| 2 | − | |
| 3 | − | |
| 4 | −The basic idea behind RCU (read-copy update) is to split destructive | |
| 5 | −operations into two parts, one that prevents anyone from seeing the data | |
| 6 | −item being destroyed, and one that actually carries out the destruction. | |
| 7 | −A "grace period" must elapse between the two parts, and this grace period | |
| 8 | −must be long enough that any readers accessing the item being deleted have | |
| 9 | −since dropped their references. For example, an RCU-protected deletion | |
| 10 | −from a linked list would first remove the item from the list, wait for | |
| 11 | −a grace period to elapse, then free the element. See the listRCU.txt | |
| 12 | −file for more information on using RCU with linked lists. | |
| 13 | − | |
| 14 | − | |
| 15 | −Frequently Asked Questions | |
| 16 | − | |
| 17 | −o Why would anyone want to use RCU? | |
| 18 | − | |
| 19 | − The advantage of RCU's two-part approach is that RCU readers need | |
| 20 | − not acquire any locks, perform any atomic instructions, write to | |
| 21 | − shared memory, or (on CPUs other than Alpha) execute any memory | |
| 22 | − barriers. The fact that these operations are quite expensive | |
| 23 | − on modern CPUs is what gives RCU its performance advantages | |
| 24 | − in read-mostly situations. The fact that RCU readers need not | |
| 25 | − acquire locks can also greatly simplify deadlock-avoidance code. | |
| 26 | − | |
| 27 | −o How can the updater tell when a grace period has completed | |
| 28 | − if the RCU readers give no indication when they are done? | |
| 29 | − | |
| 30 | − Just as with spinlocks, RCU readers are not permitted to | |
| 31 | − block, switch to user-mode execution, or enter the idle loop. | |
| 32 | − Therefore, as soon as a CPU is seen passing through any of these | |
| 33 | − three states, we know that that CPU has exited any previous RCU | |
| 34 | − read-side critical sections. So, if we remove an item from a | |
| 35 | − linked list, and then wait until all CPUs have switched context, | |
| 36 | − executed in user mode, or executed in the idle loop, we can | |
| 37 | − safely free up that item. | |
| 38 | − | |
| 39 | − Preemptible variants of RCU (CONFIG_PREEMPT_RCU) get the | |
| 40 | − same effect, but require that the readers manipulate CPU-local | |
| 41 | − counters. These counters allow limited types of blocking within | |
| 42 | − RCU read-side critical sections. SRCU also uses CPU-local | |
| 43 | − counters, and permits general blocking within RCU read-side | |
| 44 | − critical sections. These variants of RCU detect grace periods | |
| 45 | − by sampling these counters. | |
| 46 | − | |
| 47 | −o If I am running on a uniprocessor kernel, which can only do one | |
| 48 | − thing at a time, why should I wait for a grace period? | |
| 49 | − | |
| 50 | − See the UP.txt file in this directory. | |
| 51 | − | |
| 52 | −o How can I see where RCU is currently used in the Linux kernel? | |
| 53 | − | |
| 54 | − Search for "rcu_read_lock", "rcu_read_unlock", "call_rcu", | |
| 55 | − "rcu_read_lock_bh", "rcu_read_unlock_bh", "srcu_read_lock", | |
| 56 | − "srcu_read_unlock", "synchronize_rcu", "synchronize_net", | |
| 57 | − "synchronize_srcu", and the other RCU primitives. Or grab one | |
| 58 | − of the cscope databases from: | |
| 59 | − | |
| 60 | − http://www.rdrop.com/users/paulmck/RCU/linuxusage/rculocktab.html | |
| 61 | − | |
| 62 | −o What guidelines should I follow when writing code that uses RCU? | |
| 63 | − | |
| 64 | − See the checklist.txt file in this directory. | |
| 65 | − | |
| 66 | −o Why the name "RCU"? | |
| 67 | − | |
| 68 | − "RCU" stands for "read-copy update". The file listRCU.txt has | |
| 69 | − more information on where this name came from, search for | |
| 70 | − "read-copy update" to find it. | |
| 71 | − | |
| 72 | −o I hear that RCU is patented? What is with that? | |
| 73 | − | |
| 74 | − Yes, it is. There are several known patents related to RCU, | |
| 75 | − search for the string "Patent" in RTFP.txt to find them. | |
| 76 | − Of these, one was allowed to lapse by the assignee, and the | |
| 77 | − others have been contributed to the Linux kernel under GPL. | |
| 78 | − There are now also LGPL implementations of user-level RCU | |
| 79 | − available (http://liburcu.org/). | |
| 80 | − | |
| 81 | −o I hear that RCU needs work in order to support realtime kernels? | |
| 82 | − | |
| 83 | − Realtime-friendly RCU can be enabled via the CONFIG_PREEMPT_RCU | |
| 84 | − kernel configuration parameter. | |
| 85 | − | |
| 86 | −o Where can I find more information on RCU? | |
| 87 | − | |
| 88 | − See the RTFP.txt file in this directory. | |
| 89 | − Or point your browser at http://www.rdrop.com/users/paulmck/RCU/. | |
| @@ -1,7 +1,7 @@ | ||
| 1 | 1 | Using hlist_nulls to protect read-mostly linked lists and |
| 2 | 2 | objects using SLAB_TYPESAFE_BY_RCU allocations. |
| 3 | 3 | |
| 4 | −Please read the basics in Documentation/RCU/listRCU.txt | |
| 4 | +Please read the basics in Documentation/RCU/listRCU.rst | |
| 5 | 5 | |
| 6 | 6 | Using special makers (called 'nulls') is a convenient way |
| 7 | 7 | to solve following problem : |
| @@ -12,6 +12,7 @@ please read on. · 11 unmodified lines | ||
| 12 | 12 | Reference counting on elements of lists which are protected by traditional |
| 13 | 13 | reader/writer spinlocks or semaphores are straightforward: |
| 14 | 14 | |
| 15 | +CODE LISTING A: | |
| 15 | 16 | 1. 2. |
| 16 | 17 | add() search_and_reference() |
| 17 | 18 | { { |
| @@ -28,7 +29,8 @@ add() search_and_reference() · 10 unmodified lines | ||
| 28 | 29 | release_referenced() delete() |
| 29 | 30 | { { |
| 30 | 31 | ... write_lock(&list_lock); |
| 31 | − atomic_dec(&el->rc, relfunc) ... | |
| 32 | + if(atomic_dec_and_test(&el->rc)) ... | |
| 33 | + kfree(el); | |
| 32 | 34 | ... remove_element |
| 33 | 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 | ||
| 44 | 46 | has already been deleted from the list/array. Use atomic_inc_not_zero() |
| 45 | 47 | in this scenario as follows: |
| 46 | 48 | |
| 49 | +CODE LISTING B: | |
| 47 | 50 | 1. 2. |
| 48 | 51 | add() search_and_reference() |
| 49 | 52 | { { |
| @@ -79,6 +82,7 @@ search_and_reference() code path. In such cases, the · 29 unmodified lines | ||
| 79 | 82 | atomic_dec_and_test() may be moved from delete() to el_free() |
| 80 | 83 | as follows: |
| 81 | 84 | |
| 85 | +CODE LISTING C: | |
| 82 | 86 | 1. 2. |
| 83 | 87 | add() search_and_reference() |
| 84 | 88 | { { |
| @@ -114,6 +118,17 @@ element can therefore safely be freed. This in turn guarantees that if · 29 unmodified lines | ||
| 114 | 118 | any reader finds the element, that reader may safely acquire a reference |
| 115 | 119 | without checking the value of the reference counter. |
| 116 | 120 | |
| 121 | +A clear advantage of the RCU-based pattern in listing C over the one | |
| 122 | +in listing B is that any call to search_and_reference() that locates | |
| 123 | +a given object will succeed in obtaining a reference to that object, | |
| 124 | +even given a concurrent invocation of delete() for that same object. | |
| 125 | +Similarly, a clear advantage of both listings B and C over listing A is | |
| 126 | +that a call to delete() is not delayed even if there are an arbitrarily | |
| 127 | +large number of calls to search_and_reference() searching for the same | |
| 128 | +object that delete() was invoked on. Instead, all that is delayed is | |
| 129 | +the eventual invocation of kfree(), which is usually not a problem on | |
| 130 | +modern computer systems, even the small ones. | |
| 131 | + | |
| 117 | 132 | In cases where delete() can sleep, synchronize_rcu() can be called from |
| 118 | 133 | delete(), so that el_free() can be subsumed into delete as follows: |
| 119 | 134 | |
| @@ -130,3 +145,7 @@ delete() · 10 unmodified lines | ||
| 130 | 145 | kfree(el); |
| 131 | 146 | ... |
| 132 | 147 | } |
| 148 | + | |
| 149 | +As additional examples in the kernel, the pattern in listing C is used by | |
| 150 | +reference counting of struct pid, while the pattern in listing B is used by | |
| 151 | +struct posix_acl. | |
| @@ -153,7 +153,7 @@ rcupdate.rcu_task_stall_timeout · 152 unmodified lines | ||
| 153 | 153 | This boot/sysfs parameter controls the RCU-tasks stall warning |
| 154 | 154 | interval. A value of zero or less suppresses RCU-tasks stall |
| 155 | 155 | 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 | 158 | INFO: rcu_tasks detected stalls on tasks: |
| 159 | 159 | |
| @@ -212,7 +212,7 @@ synchronize_rcu() · 211 unmodified lines | ||
| 212 | 212 | |
| 213 | 213 | rcu_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 | 217 | Yes, rcu_assign_pointer() -is- implemented as a macro, though it |
| 218 | 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 | 221 | The updater uses this function to assign a new value to an |
| 222 | 222 | RCU-protected pointer, in order to safely communicate the change |
| 223 | − in value from the updater to the reader. This function returns | |
| 224 | − the new value, and also executes any memory-barrier instructions | |
| 225 | − required for a given CPU architecture. | |
| 223 | + in value from the updater to the reader. This macro does not | |
| 224 | + evaluate to an rvalue, but it does execute any memory-barrier | |
| 225 | + instructions required for a given CPU architecture. | |
| 226 | 226 | |
| 227 | 227 | Perhaps just as important, it serves to document (1) which |
| 228 | 228 | pointers are protected by RCU and (2) the point at which a |
| @@ -0,0 +1,31 @@ | ||
| 1 | +================== | |
| 2 | +Control Groupstats | |
| 3 | +================== | |
| 4 | + | |
| 5 | +Control Groupstats is inspired by the discussion at | |
| 6 | +http://lkml.org/lkml/2007/4/11/187 and implements per cgroup statistics as | |
| 7 | +suggested by Andrew Morton in http://lkml.org/lkml/2007/4/11/263. | |
| 8 | + | |
| 9 | +Per cgroup statistics infrastructure re-uses code from the taskstats | |
| 10 | +interface. A new set of cgroup operations are registered with commands | |
| 11 | +and attributes specific to cgroups. It should be very easy to | |
| 12 | +extend per cgroup statistics, by adding members to the cgroupstats | |
| 13 | +structure. | |
| 14 | + | |
| 15 | +The current model for cgroupstats is a pull, a push model (to post | |
| 16 | +statistics on interesting events), should be very easy to add. Currently | |
| 17 | +user space requests for statistics by passing the cgroup path. | |
| 18 | +Statistics about the state of all the tasks in the cgroup is returned to | |
| 19 | +user space. | |
| 20 | + | |
| 21 | +NOTE: We currently rely on delay accounting for extracting information | |
| 22 | +about tasks blocked on I/O. If CONFIG_TASK_DELAY_ACCT is disabled, this | |
| 23 | +information will not be available. | |
| 24 | + | |
| 25 | +To extract cgroup statistics a utility very similar to getdelays.c | |
| 26 | +has been developed, the sample output of the utility is shown below:: | |
| 27 | + | |
| 28 | + ~/balbir/cgroupstats # ./getdelays -C "/sys/fs/cgroup/a" | |
| 29 | + sleeping 1, blocked 0, running 1, stopped 0, uninterruptible 0 | |
| 30 | + ~/balbir/cgroupstats # ./getdelays -C "/sys/fs/cgroup" | |
| 31 | + sleeping 155, blocked 0, running 1, stopped 0, uninterruptible 2 | |
| @@ -1,27 +0,0 @@ | ||
| 1 | −Control Groupstats is inspired by the discussion at | |
| 2 | −http://lkml.org/lkml/2007/4/11/187 and implements per cgroup statistics as | |
| 3 | −suggested by Andrew Morton in http://lkml.org/lkml/2007/4/11/263. | |
| 4 | − | |
| 5 | −Per cgroup statistics infrastructure re-uses code from the taskstats | |
| 6 | −interface. A new set of cgroup operations are registered with commands | |
| 7 | −and attributes specific to cgroups. It should be very easy to | |
| 8 | −extend per cgroup statistics, by adding members to the cgroupstats | |
| 9 | −structure. | |
| 10 | − | |
| 11 | −The current model for cgroupstats is a pull, a push model (to post | |
| 12 | −statistics on interesting events), should be very easy to add. Currently | |
| 13 | −user space requests for statistics by passing the cgroup path. | |
| 14 | −Statistics about the state of all the tasks in the cgroup is returned to | |
| 15 | −user space. | |
| 16 | − | |
| 17 | −NOTE: We currently rely on delay accounting for extracting information | |
| 18 | −about tasks blocked on I/O. If CONFIG_TASK_DELAY_ACCT is disabled, this | |
| 19 | −information will not be available. | |
| 20 | − | |
| 21 | −To extract cgroup statistics a utility very similar to getdelays.c | |
| 22 | −has been developed, the sample output of the utility is shown below | |
| 23 | − | |
| 24 | −~/balbir/cgroupstats # ./getdelays -C "/sys/fs/cgroup/a" | |
| 25 | −sleeping 1, blocked 0, running 1, stopped 0, uninterruptible 0 | |
| 26 | −~/balbir/cgroupstats # ./getdelays -C "/sys/fs/cgroup" | |
| 27 | −sleeping 155, blocked 0, running 1, stopped 0, uninterruptible 2 | |
| @@ -0,0 +1,126 @@ | ||
| 1 | +================ | |
| 2 | +Delay accounting | |
| 3 | +================ | |
| 4 | + | |
| 5 | +Tasks encounter delays in execution when they wait | |
| 6 | +for some kernel resource to become available e.g. a | |
| 7 | +runnable task may wait for a free CPU to run on. | |
| 8 | + | |
| 9 | +The per-task delay accounting functionality measures | |
| 10 | +the delays experienced by a task while | |
| 11 | + | |
| 12 | +a) waiting for a CPU (while being runnable) | |
| 13 | +b) completion of synchronous block I/O initiated by the task | |
| 14 | +c) swapping in pages | |
| 15 | +d) memory reclaim | |
| 16 | + | |
| 17 | +and makes these statistics available to userspace through | |
| 18 | +the taskstats interface. | |
| 19 | + | |
| 20 | +Such delays provide feedback for setting a task's cpu priority, | |
| 21 | +io priority and rss limit values appropriately. Long delays for | |
| 22 | +important tasks could be a trigger for raising its corresponding priority. | |
| 23 | + | |
| 24 | +The functionality, through its use of the taskstats interface, also provides | |
| 25 | +delay statistics aggregated for all tasks (or threads) belonging to a | |
| 26 | +thread group (corresponding to a traditional Unix process). This is a commonly | |
| 27 | +needed aggregation that is more efficiently done by the kernel. | |
| 28 | + | |
| 29 | +Userspace utilities, particularly resource management applications, can also | |
| 30 | +aggregate delay statistics into arbitrary groups. To enable this, delay | |
| 31 | +statistics of a task are available both during its lifetime as well as on its | |
| 32 | +exit, ensuring continuous and complete monitoring can be done. | |
| 33 | + | |
| 34 | + | |
| 35 | +Interface | |
| 36 | +--------- | |
| 37 | + | |
| 38 | +Delay accounting uses the taskstats interface which is described | |
| 39 | +in detail in a separate document in this directory. Taskstats returns a | |
| 40 | +generic data structure to userspace corresponding to per-pid and per-tgid | |
| 41 | +statistics. The delay accounting functionality populates specific fields of | |
| 42 | +this structure. See | |
| 43 | + | |
| 44 | + include/linux/taskstats.h | |
| 45 | + | |
| 46 | +for a description of the fields pertaining to delay accounting. | |
| 47 | +It will generally be in the form of counters returning the cumulative | |
| 48 | +delay seen for cpu, sync block I/O, swapin, memory reclaim etc. | |
| 49 | + | |
| 50 | +Taking the difference of two successive readings of a given | |
| 51 | +counter (say cpu_delay_total) for a task will give the delay | |
| 52 | +experienced by the task waiting for the corresponding resource | |
| 53 | +in that interval. | |
| 54 | + | |
| 55 | +When a task exits, records containing the per-task statistics | |
| 56 | +are sent to userspace without requiring a command. If it is the last exiting | |
| 57 | +task of a thread group, the per-tgid statistics are also sent. More details | |
| 58 | +are given in the taskstats interface description. | |
| 59 | + | |
| 60 | +The getdelays.c userspace utility in tools/accounting directory allows simple | |
| 61 | +commands to be run and the corresponding delay statistics to be displayed. It | |
| 62 | +also serves as an example of using the taskstats interface. | |
| 63 | + | |
| 64 | +Usage | |
| 65 | +----- | |
| 66 | + | |
| 67 | +Compile the kernel with:: | |
| 68 | + | |
| 69 | + CONFIG_TASK_DELAY_ACCT=y | |
| 70 | + CONFIG_TASKSTATS=y | |
| 71 | + | |
| 72 | +Delay accounting is enabled by default at boot up. | |
| 73 | +To disable, add:: | |
| 74 | + | |
| 75 | + nodelayacct | |
| 76 | + | |
| 77 | +to the kernel boot options. The rest of the instructions | |
| 78 | +below assume this has not been done. | |
| 79 | + | |
| 80 | +After the system has booted up, use a utility | |
| 81 | +similar to getdelays.c to access the delays | |
| 82 | +seen by a given task or a task group (tgid). | |
| 83 | +The utility also allows a given command to be | |
| 84 | +executed and the corresponding delays to be | |
| 85 | +seen. | |
| 86 | + | |
| 87 | +General format of the getdelays command:: | |
| 88 | + | |
| 89 | + getdelays [-t tgid] [-p pid] [-c cmd...] | |
| 90 | + | |
| 91 | + | |
| 92 | +Get delays, since system boot, for pid 10:: | |
| 93 | + | |
| 94 | + # ./getdelays -p 10 | |
| 95 | + (output similar to next case) | |
| 96 | + | |
| 97 | +Get sum of delays, since system boot, for all pids with tgid 5:: | |
| 98 | + | |
| 99 | + # ./getdelays -t 5 | |
| 100 | + | |
| 101 | + | |
| 102 | + CPU count real total virtual total delay total | |
| 103 | + 7876 92005750 100000000 24001500 | |
| 104 | + IO count delay total | |
| 105 | + 0 0 | |
| 106 | + SWAP count delay total | |
| 107 | + 0 0 | |
| 108 | + RECLAIM count delay total | |
| 109 | + 0 0 | |
| 110 | + | |
| 111 | +Get delays seen in executing a given simple command:: | |
| 112 | + | |
| 113 | + # ./getdelays -c ls / | |
| 114 | + | |
| 115 | + bin data1 data3 data5 dev home media opt root srv sys usr | |
| 116 | + boot data2 data4 data6 etc lib mnt proc sbin subdomain tmp var | |
| 117 | + | |
| 118 | + | |
| 119 | + CPU count real total virtual total delay total | |
| 120 | + 6 4000250 4000000 0 | |
| 121 | + IO count delay total | |
| 122 | + 0 0 | |
| 123 | + SWAP count delay total | |
| 124 | + 0 0 | |
| 125 | + RECLAIM count delay total | |
| 126 | + 0 0 | |
| @@ -1,117 +0,0 @@ | ||
| 1 | −Delay accounting | |
| 2 | −---------------- | |
| 3 | − | |
| 4 | −Tasks encounter delays in execution when they wait | |
| 5 | −for some kernel resource to become available e.g. a | |
| 6 | −runnable task may wait for a free CPU to run on. | |
| 7 | − | |
| 8 | −The per-task delay accounting functionality measures | |
| 9 | −the delays experienced by a task while | |
| 10 | − | |
| 11 | −a) waiting for a CPU (while being runnable) | |
| 12 | −b) completion of synchronous block I/O initiated by the task | |
| 13 | −c) swapping in pages | |
| 14 | −d) memory reclaim | |
| 15 | − | |
| 16 | −and makes these statistics available to userspace through | |
| 17 | −the taskstats interface. | |
| 18 | − | |
| 19 | −Such delays provide feedback for setting a task's cpu priority, | |
| 20 | −io priority and rss limit values appropriately. Long delays for | |
| 21 | −important tasks could be a trigger for raising its corresponding priority. | |
| 22 | − | |
| 23 | −The functionality, through its use of the taskstats interface, also provides | |
| 24 | −delay statistics aggregated for all tasks (or threads) belonging to a | |
| 25 | −thread group (corresponding to a traditional Unix process). This is a commonly | |
| 26 | −needed aggregation that is more efficiently done by the kernel. | |
| 27 | − | |
| 28 | −Userspace utilities, particularly resource management applications, can also | |
| 29 | −aggregate delay statistics into arbitrary groups. To enable this, delay | |
| 30 | −statistics of a task are available both during its lifetime as well as on its | |
| 31 | −exit, ensuring continuous and complete monitoring can be done. | |
| 32 | − | |
| 33 | − | |
| 34 | −Interface | |
| 35 | −--------- | |
| 36 | − | |
| 37 | −Delay accounting uses the taskstats interface which is described | |
| 38 | −in detail in a separate document in this directory. Taskstats returns a | |
| 39 | −generic data structure to userspace corresponding to per-pid and per-tgid | |
| 40 | −statistics. The delay accounting functionality populates specific fields of | |
| 41 | −this structure. See | |
| 42 | − include/linux/taskstats.h | |
| 43 | −for a description of the fields pertaining to delay accounting. | |
| 44 | −It will generally be in the form of counters returning the cumulative | |
| 45 | −delay seen for cpu, sync block I/O, swapin, memory reclaim etc. | |
| 46 | − | |
| 47 | −Taking the difference of two successive readings of a given | |
| 48 | −counter (say cpu_delay_total) for a task will give the delay | |
| 49 | −experienced by the task waiting for the corresponding resource | |
| 50 | −in that interval. | |
| 51 | − | |
| 52 | −When a task exits, records containing the per-task statistics | |
| 53 | −are sent to userspace without requiring a command. If it is the last exiting | |
| 54 | −task of a thread group, the per-tgid statistics are also sent. More details | |
| 55 | −are given in the taskstats interface description. | |
| 56 | − | |
| 57 | −The getdelays.c userspace utility in tools/accounting directory allows simple | |
| 58 | −commands to be run and the corresponding delay statistics to be displayed. It | |
| 59 | −also serves as an example of using the taskstats interface. | |
| 60 | − | |
| 61 | −Usage | |
| 62 | −----- | |
| 63 | − | |
| 64 | −Compile the kernel with | |
| 65 | − CONFIG_TASK_DELAY_ACCT=y | |
| 66 | − CONFIG_TASKSTATS=y | |
| 67 | − | |
| 68 | −Delay accounting is enabled by default at boot up. | |
| 69 | −To disable, add | |
| 70 | − nodelayacct | |
| 71 | −to the kernel boot options. The rest of the instructions | |
| 72 | −below assume this has not been done. | |
| 73 | − | |
| 74 | −After the system has booted up, use a utility | |
| 75 | −similar to getdelays.c to access the delays | |
| 76 | −seen by a given task or a task group (tgid). | |
| 77 | −The utility also allows a given command to be | |
| 78 | −executed and the corresponding delays to be | |
| 79 | −seen. | |
| 80 | − | |
| 81 | −General format of the getdelays command | |
| 82 | − | |
| 83 | −getdelays [-t tgid] [-p pid] [-c cmd...] | |
| 84 | − | |
| 85 | − | |
| 86 | −Get delays, since system boot, for pid 10 | |
| 87 | −# ./getdelays -p 10 | |
| 88 | −(output similar to next case) | |
| 89 | − | |
| 90 | −Get sum of delays, since system boot, for all pids with tgid 5 | |
| 91 | −# ./getdelays -t 5 | |
| 92 | − | |
| 93 | − | |
| 94 | −CPU count real total virtual total delay total | |
| 95 | − 7876 92005750 100000000 24001500 | |
| 96 | −IO count delay total | |
| 97 | − 0 0 | |
| 98 | −SWAP count delay total | |
| 99 | − 0 0 | |
| 100 | −RECLAIM count delay total | |
| 101 | − 0 0 | |
| 102 | − | |
| 103 | −Get delays seen in executing a given simple command | |
| 104 | −# ./getdelays -c ls / | |
| 105 | − | |
| 106 | −bin data1 data3 data5 dev home media opt root srv sys usr | |
| 107 | −boot data2 data4 data6 etc lib mnt proc sbin subdomain tmp var | |
| 108 | − | |
| 109 | − | |
| 110 | −CPU count real total virtual total delay total | |
| 111 | − 6 4000250 4000000 0 | |
| 112 | −IO count delay total | |
| 113 | − 0 0 | |
| 114 | −SWAP count delay total | |
| 115 | − 0 0 | |
| 116 | −RECLAIM count delay total | |
| 117 | − 0 0 | |
| @@ -0,0 +1,14 @@ | ||
| 1 | +.. SPDX-License-Identifier: GPL-2.0 | |
| 2 | + | |
| 3 | +========== | |
| 4 | +Accounting | |
| 5 | +========== | |
| 6 | + | |
| 7 | +.. toctree:: | |
| 8 | + :maxdepth: 1 | |
| 9 | + | |
| 10 | + cgroupstats | |
| 11 | + delay-accounting | |
| 12 | + psi | |
| 13 | + taskstats | |
| 14 | + taskstats-struct | |
| @@ -0,0 +1,182 @@ | ||
| 1 | +================================ | |
| 2 | +PSI - Pressure Stall Information | |
| 3 | +================================ | |
| 4 | + | |
| 5 | +:Date: April, 2018 | |
| 6 | +:Author: Johannes Weiner <hannes@cmpxchg.org> | |
| 7 | + | |
| 8 | +When CPU, memory or IO devices are contended, workloads experience | |
| 9 | +latency spikes, throughput losses, and run the risk of OOM kills. | |
| 10 | + | |
| 11 | +Without an accurate measure of such contention, users are forced to | |
| 12 | +either play it safe and under-utilize their hardware resources, or | |
| 13 | +roll the dice and frequently suffer the disruptions resulting from | |
| 14 | +excessive overcommit. | |
| 15 | + | |
| 16 | +The psi feature identifies and quantifies the disruptions caused by | |
| 17 | +such resource crunches and the time impact it has on complex workloads | |
| 18 | +or even entire systems. | |
| 19 | + | |
| 20 | +Having an accurate measure of productivity losses caused by resource | |
| 21 | +scarcity aids users in sizing workloads to hardware--or provisioning | |
| 22 | +hardware according to workload demand. | |
| 23 | + | |
| 24 | +As psi aggregates this information in realtime, systems can be managed | |
| 25 | +dynamically using techniques such as load shedding, migrating jobs to | |
| 26 | +other systems or data centers, or strategically pausing or killing low | |
| 27 | +priority or restartable batch jobs. | |
| 28 | + | |
| 29 | +This allows maximizing hardware utilization without sacrificing | |
| 30 | +workload health or risking major disruptions such as OOM kills. | |
| 31 | + | |
| 32 | +Pressure interface | |
| 33 | +================== | |
| 34 | + | |
| 35 | +Pressure information for each resource is exported through the | |
| 36 | +respective file in /proc/pressure/ -- cpu, memory, and io. | |
| 37 | + | |
| 38 | +The format for CPU is as such:: | |
| 39 | + | |
| 40 | + some avg10=0.00 avg60=0.00 avg300=0.00 total=0 | |
| 41 | + | |
| 42 | +and for memory and IO:: | |
| 43 | + | |
| 44 | + some avg10=0.00 avg60=0.00 avg300=0.00 total=0 | |
| 45 | + full avg10=0.00 avg60=0.00 avg300=0.00 total=0 | |
| 46 | + | |
| 47 | +The "some" line indicates the share of time in which at least some | |
| 48 | +tasks are stalled on a given resource. | |
| 49 | + | |
| 50 | +The "full" line indicates the share of time in which all non-idle | |
| 51 | +tasks are stalled on a given resource simultaneously. In this state | |
| 52 | +actual CPU cycles are going to waste, and a workload that spends | |
| 53 | +extended time in this state is considered to be thrashing. This has | |
| 54 | +severe impact on performance, and it's useful to distinguish this | |
| 55 | +situation from a state where some tasks are stalled but the CPU is | |
| 56 | +still doing productive work. As such, time spent in this subset of the | |
| 57 | +stall state is tracked separately and exported in the "full" averages. | |
| 58 | + | |
| 59 | +The ratios (in %) are tracked as recent trends over ten, sixty, and | |
| 60 | +three hundred second windows, which gives insight into short term events | |
| 61 | +as well as medium and long term trends. The total absolute stall time | |
| 62 | +(in us) is tracked and exported as well, to allow detection of latency | |
| 63 | +spikes which wouldn't necessarily make a dent in the time averages, | |
| 64 | +or to average trends over custom time frames. | |
| 65 | + | |
| 66 | +Monitoring for pressure thresholds | |
| 67 | +================================== | |
| 68 | + | |
| 69 | +Users can register triggers and use poll() to be woken up when resource | |
| 70 | +pressure exceeds certain thresholds. | |
| 71 | + | |
| 72 | +A trigger describes the maximum cumulative stall time over a specific | |
| 73 | +time window, e.g. 100ms of total stall time within any 500ms window to | |
| 74 | +generate a wakeup event. | |
| 75 | + | |
| 76 | +To register a trigger user has to open psi interface file under | |
| 77 | +/proc/pressure/ representing the resource to be monitored and write the | |
| 78 | +desired threshold and time window. The open file descriptor should be | |
| 79 | +used to wait for trigger events using select(), poll() or epoll(). | |
| 80 | +The following format is used:: | |
| 81 | + | |
| 82 | + <some|full> <stall amount in us> <time window in us> | |
| 83 | + | |
| 84 | +For example writing "some 150000 1000000" into /proc/pressure/memory | |
| 85 | +would add 150ms threshold for partial memory stall measured within | |
| 86 | +1sec time window. Writing "full 50000 1000000" into /proc/pressure/io | |
| 87 | +would add 50ms threshold for full io stall measured within 1sec time window. | |
| 88 | + | |
| 89 | +Triggers can be set on more than one psi metric and more than one trigger | |
| 90 | +for the same psi metric can be specified. However for each trigger a separate | |
| 91 | +file descriptor is required to be able to poll it separately from others, | |
| 92 | +therefore for each trigger a separate open() syscall should be made even | |
| 93 | +when opening the same psi interface file. | |
| 94 | + | |
| 95 | +Monitors activate only when system enters stall state for the monitored | |
| 96 | +psi metric and deactivates upon exit from the stall state. While system is | |
| 97 | +in the stall state psi signal growth is monitored at a rate of 10 times per | |
| 98 | +tracking window. | |
| 99 | + | |
| 100 | +The kernel accepts window sizes ranging from 500ms to 10s, therefore min | |
| 101 | +monitoring update interval is 50ms and max is 1s. Min limit is set to | |
| 102 | +prevent overly frequent polling. Max limit is chosen as a high enough number | |
| 103 | +after which monitors are most likely not needed and psi averages can be used | |
| 104 | +instead. | |
| 105 | + | |
| 106 | +When activated, psi monitor stays active for at least the duration of one | |
| 107 | +tracking window to avoid repeated activations/deactivations when system is | |
| 108 | +bouncing in and out of the stall state. | |
| 109 | + | |
| 110 | +Notifications to the userspace are rate-limited to one per tracking window. | |
| 111 | + | |
| 112 | +The trigger will de-register when the file descriptor used to define the | |
| 113 | +trigger is closed. | |
| 114 | + | |
| 115 | +Userspace monitor usage example | |
| 116 | +=============================== | |
| 117 | + | |
| 118 | +:: | |
| 119 | + | |
| 120 | + #include <errno.h> | |
| 121 | + #include <fcntl.h> | |
| 122 | + #include <stdio.h> | |
| 123 | + #include <poll.h> | |
| 124 | + #include <string.h> | |
| 125 | + #include <unistd.h> | |
| 126 | + | |
| 127 | + /* | |
| 128 | + * Monitor memory partial stall with 1s tracking window size | |
| 129 | + * and 150ms threshold. | |
| 130 | + */ | |
| 131 | + int main() { | |
| 132 | + const char trig[] = "some 150000 1000000"; | |
| 133 | + struct pollfd fds; | |
| 134 | + int n; | |
| 135 | + | |
| 136 | + fds.fd = open("/proc/pressure/memory", O_RDWR | O_NONBLOCK); | |
| 137 | + if (fds.fd < 0) { | |
| 138 | + printf("/proc/pressure/memory open error: %s\n", | |
| 139 | + strerror(errno)); | |
| 140 | + return 1; | |
| 141 | + } | |
| 142 | + fds.events = POLLPRI; | |
| 143 | + | |
| 144 | + if (write(fds.fd, trig, strlen(trig) + 1) < 0) { | |
| 145 | + printf("/proc/pressure/memory write error: %s\n", | |
| 146 | + strerror(errno)); | |
| 147 | + return 1; | |
| 148 | + } | |
| 149 | + | |
| 150 | + printf("waiting for events...\n"); | |
| 151 | + while (1) { | |
| 152 | + n = poll(&fds, 1, -1); | |
| 153 | + if (n < 0) { | |
| 154 | + printf("poll error: %s\n", strerror(errno)); | |
| 155 | + return 1; | |
| 156 | + } | |
| 157 | + if (fds.revents & POLLERR) { | |
| 158 | + printf("got POLLERR, event source is gone\n"); | |
| 159 | + return 0; | |
| 160 | + } | |
| 161 | + if (fds.revents & POLLPRI) { | |
| 162 | + printf("event triggered!\n"); | |
| 163 | + } else { | |
| 164 | + printf("unknown event received: 0x%x\n", fds.revents); | |
| 165 | + return 1; | |
| 166 | + } | |
| 167 | + } | |
| 168 | + | |
| 169 | + return 0; | |
| 170 | + } | |
| 171 | + | |
| 172 | +Cgroup2 interface | |
| 173 | +================= | |
| 174 | + | |
| 175 | +In a system with a CONFIG_CGROUP=y kernel and the cgroup2 filesystem | |
| 176 | +mounted, pressure stall information is also tracked for tasks grouped | |
| 177 | +into cgroups. Each subdirectory in the cgroupfs mountpoint contains | |
| 178 | +cpu.pressure, memory.pressure, and io.pressure files; the format is | |
| 179 | +the same as the /proc/pressure/ files. | |
| 180 | + | |
| 181 | +Per-cgroup psi monitors can be specified and used the same way as | |
| 182 | +system-wide ones. | |
| @@ -1,180 +0,0 @@ | ||
| 1 | −================================ | |
| 2 | −PSI - Pressure Stall Information | |
| 3 | −================================ | |
| 4 | − | |
| 5 | −:Date: April, 2018 | |
| 6 | −:Author: Johannes Weiner <hannes@cmpxchg.org> | |
| 7 | − | |
| 8 | −When CPU, memory or IO devices are contended, workloads experience | |
| 9 | −latency spikes, throughput losses, and run the risk of OOM kills. | |
| 10 | − | |
| 11 | −Without an accurate measure of such contention, users are forced to | |
| 12 | −either play it safe and under-utilize their hardware resources, or | |
| 13 | −roll the dice and frequently suffer the disruptions resulting from | |
| 14 | −excessive overcommit. | |
| 15 | − | |
| 16 | −The psi feature identifies and quantifies the disruptions caused by | |
| 17 | −such resource crunches and the time impact it has on complex workloads | |
| 18 | −or even entire systems. | |
| 19 | − | |
| 20 | −Having an accurate measure of productivity losses caused by resource | |
| 21 | −scarcity aids users in sizing workloads to hardware--or provisioning | |
| 22 | −hardware according to workload demand. | |
| 23 | − | |
| 24 | −As psi aggregates this information in realtime, systems can be managed | |
| 25 | −dynamically using techniques such as load shedding, migrating jobs to | |
| 26 | −other systems or data centers, or strategically pausing or killing low | |
| 27 | −priority or restartable batch jobs. | |
| 28 | − | |
| 29 | −This allows maximizing hardware utilization without sacrificing | |
| 30 | −workload health or risking major disruptions such as OOM kills. | |
| 31 | − | |
| 32 | −Pressure interface | |
| 33 | −================== | |
| 34 | − | |
| 35 | −Pressure information for each resource is exported through the | |
| 36 | −respective file in /proc/pressure/ -- cpu, memory, and io. | |
| 37 | − | |
| 38 | −The format for CPU is as such: | |
| 39 | − | |
| 40 | −some avg10=0.00 avg60=0.00 avg300=0.00 total=0 | |
| 41 | − | |
| 42 | −and for memory and IO: | |
| 43 | − | |
| 44 | −some avg10=0.00 avg60=0.00 avg300=0.00 total=0 | |
| 45 | −full avg10=0.00 avg60=0.00 avg300=0.00 total=0 | |
| 46 | − | |
| 47 | −The "some" line indicates the share of time in which at least some | |
| 48 | −tasks are stalled on a given resource. | |
| 49 | − | |
| 50 | −The "full" line indicates the share of time in which all non-idle | |
| 51 | −tasks are stalled on a given resource simultaneously. In this state | |
| 52 | −actual CPU cycles are going to waste, and a workload that spends | |
| 53 | −extended time in this state is considered to be thrashing. This has | |
| 54 | −severe impact on performance, and it's useful to distinguish this | |
| 55 | −situation from a state where some tasks are stalled but the CPU is | |
| 56 | −still doing productive work. As such, time spent in this subset of the | |
| 57 | −stall state is tracked separately and exported in the "full" averages. | |
| 58 | − | |
| 59 | −The ratios (in %) are tracked as recent trends over ten, sixty, and | |
| 60 | −three hundred second windows, which gives insight into short term events | |
| 61 | −as well as medium and long term trends. The total absolute stall time | |
| 62 | −(in us) is tracked and exported as well, to allow detection of latency | |
| 63 | −spikes which wouldn't necessarily make a dent in the time averages, | |
| 64 | −or to average trends over custom time frames. | |
| 65 | − | |
| 66 | −Monitoring for pressure thresholds | |
| 67 | −================================== | |
| 68 | − | |
| 69 | −Users can register triggers and use poll() to be woken up when resource | |
| 70 | −pressure exceeds certain thresholds. | |
| 71 | − | |
| 72 | −A trigger describes the maximum cumulative stall time over a specific | |
| 73 | −time window, e.g. 100ms of total stall time within any 500ms window to | |
| 74 | −generate a wakeup event. | |
| 75 | − | |
| 76 | −To register a trigger user has to open psi interface file under | |
| 77 | −/proc/pressure/ representing the resource to be monitored and write the | |
| 78 | −desired threshold and time window. The open file descriptor should be | |
| 79 | −used to wait for trigger events using select(), poll() or epoll(). | |
| 80 | −The following format is used: | |
| 81 | − | |
| 82 | −<some|full> <stall amount in us> <time window in us> | |
| 83 | − | |
| 84 | −For example writing "some 150000 1000000" into /proc/pressure/memory | |
| 85 | −would add 150ms threshold for partial memory stall measured within | |
| 86 | −1sec time window. Writing "full 50000 1000000" into /proc/pressure/io | |
| 87 | −would add 50ms threshold for full io stall measured within 1sec time window. | |
| 88 | − | |
| 89 | −Triggers can be set on more than one psi metric and more than one trigger | |
| 90 | −for the same psi metric can be specified. However for each trigger a separate | |
| 91 | −file descriptor is required to be able to poll it separately from others, | |
| 92 | −therefore for each trigger a separate open() syscall should be made even | |
| 93 | −when opening the same psi interface file. | |
| 94 | − | |
| 95 | −Monitors activate only when system enters stall state for the monitored | |
| 96 | −psi metric and deactivates upon exit from the stall state. While system is | |
| 97 | −in the stall state psi signal growth is monitored at a rate of 10 times per | |
| 98 | −tracking window. | |
| 99 | − | |
| 100 | −The kernel accepts window sizes ranging from 500ms to 10s, therefore min | |
| 101 | −monitoring update interval is 50ms and max is 1s. Min limit is set to | |
| 102 | −prevent overly frequent polling. Max limit is chosen as a high enough number | |
| 103 | −after which monitors are most likely not needed and psi averages can be used | |
| 104 | −instead. | |
| 105 | − | |
| 106 | −When activated, psi monitor stays active for at least the duration of one | |
| 107 | −tracking window to avoid repeated activations/deactivations when system is | |
| 108 | −bouncing in and out of the stall state. | |
| 109 | − | |
| 110 | −Notifications to the userspace are rate-limited to one per tracking window. | |
| 111 | − | |
| 112 | −The trigger will de-register when the file descriptor used to define the | |
| 113 | −trigger is closed. | |
| 114 | − | |
| 115 | −Userspace monitor usage example | |
| 116 | −=============================== | |
| 117 | − | |
| 118 | −#include <errno.h> | |
| 119 | −#include <fcntl.h> | |
| 120 | −#include <stdio.h> | |
| 121 | −#include <poll.h> | |
| 122 | −#include <string.h> | |
| 123 | −#include <unistd.h> | |
| 124 | − | |
| 125 | −/* | |
| 126 | − * Monitor memory partial stall with 1s tracking window size | |
| 127 | − * and 150ms threshold. | |
| 128 | − */ | |
| 129 | −int main() { | |
| 130 | − const char trig[] = "some 150000 1000000"; | |
| 131 | − struct pollfd fds; | |
| 132 | − int n; | |
| 133 | − | |
| 134 | − fds.fd = open("/proc/pressure/memory", O_RDWR | O_NONBLOCK); | |
| 135 | − if (fds.fd < 0) { | |
| 136 | − printf("/proc/pressure/memory open error: %s\n", | |
| 137 | − strerror(errno)); | |
| 138 | − return 1; | |
| 139 | − } | |
| 140 | − fds.events = POLLPRI; | |
| 141 | − | |
| 142 | − if (write(fds.fd, trig, strlen(trig) + 1) < 0) { | |
| 143 | − printf("/proc/pressure/memory write error: %s\n", | |
| 144 | − strerror(errno)); | |
| 145 | − return 1; | |
| 146 | − } | |
| 147 | − | |
| 148 | − printf("waiting for events...\n"); | |
| 149 | − while (1) { | |
| 150 | − n = poll(&fds, 1, -1); | |
| 151 | − if (n < 0) { | |
| 152 | − printf("poll error: %s\n", strerror(errno)); | |
| 153 | − return 1; | |
| 154 | − } | |
| 155 | − if (fds.revents & POLLERR) { | |
| 156 | − printf("got POLLERR, event source is gone\n"); | |
| 157 | − return 0; | |
| 158 | − } | |
| 159 | − if (fds.revents & POLLPRI) { | |
| 160 | − printf("event triggered!\n"); | |
| 161 | − } else { | |
| 162 | − printf("unknown event received: 0x%x\n", fds.revents); | |
| 163 | − return 1; | |
| 164 | − } | |
| 165 | − } | |
| 166 | − | |
| 167 | − return 0; | |
| 168 | −} | |
| 169 | − | |
| 170 | −Cgroup2 interface | |
| 171 | −================= | |
| 172 | − | |
| 173 | −In a system with a CONFIG_CGROUP=y kernel and the cgroup2 filesystem | |
| 174 | −mounted, pressure stall information is also tracked for tasks grouped | |
| 175 | −into cgroups. Each subdirectory in the cgroupfs mountpoint contains | |
| 176 | −cpu.pressure, memory.pressure, and io.pressure files; the format is | |
| 177 | −the same as the /proc/pressure/ files. | |
| 178 | − | |
| 179 | −Per-cgroup psi monitors can be specified and used the same way as | |
| 180 | −system-wide ones. | |
| @@ -0,0 +1,199 @@ | ||
| 1 | +==================== | |
| 2 | +The struct taskstats | |
| 3 | +==================== | |
| 4 | + | |
| 5 | +This document contains an explanation of the struct taskstats fields. | |
| 6 | + | |
| 7 | +There are three different groups of fields in the struct taskstats: | |
| 8 | + | |
| 9 | +1) Common and basic accounting fields | |
| 10 | + If CONFIG_TASKSTATS is set, the taskstats interface is enabled and | |
| 11 | + the common fields and basic accounting fields are collected for | |
| 12 | + delivery at do_exit() of a task. | |
| 13 | +2) Delay accounting fields | |
| 14 | + These fields are placed between:: | |
| 15 | + | |
| 16 | + /* Delay accounting fields start */ | |
| 17 | + | |
| 18 | + and:: | |
| 19 | + | |
| 20 | + /* Delay accounting fields end */ | |
| 21 | + | |
| 22 | + Their values are collected if CONFIG_TASK_DELAY_ACCT is set. | |
| 23 | +3) Extended accounting fields | |
| 24 | + These fields are placed between:: | |
| 25 | + | |
| 26 | + /* Extended accounting fields start */ | |
| 27 | + | |
| 28 | + and:: | |
| 29 | + | |
| 30 | + /* Extended accounting fields end */ | |
| 31 | + | |
| 32 | + Their values are collected if CONFIG_TASK_XACCT is set. | |
| 33 | + | |
| 34 | +4) Per-task and per-thread context switch count statistics | |
| 35 | + | |
| 36 | +5) Time accounting for SMT machines | |
| 37 | + | |
| 38 | +6) Extended delay accounting fields for memory reclaim | |
| 39 | + | |
| 40 | +Future extension should add fields to the end of the taskstats struct, and | |
| 41 | +should not change the relative position of each field within the struct. | |
| 42 | + | |
| 43 | +:: | |
| 44 | + | |
| 45 | + struct taskstats { | |
| 46 | + | |
| 47 | +1) Common and basic accounting fields:: | |
| 48 | + | |
| 49 | + /* The version number of this struct. This field is always set to | |
| 50 | + * TAKSTATS_VERSION, which is defined in <linux/taskstats.h>. | |
| 51 | + * Each time the struct is changed, the value should be incremented. | |
| 52 | + */ | |
| 53 | + __u16 version; | |
| 54 | + | |
| 55 | + /* The exit code of a task. */ | |
| 56 | + __u32 ac_exitcode; /* Exit status */ | |
| 57 | + | |
| 58 | + /* The accounting flags of a task as defined in <linux/acct.h> | |
| 59 | + * Defined values are AFORK, ASU, ACOMPAT, ACORE, and AXSIG. | |
| 60 | + */ | |
| 61 | + __u8 ac_flag; /* Record flags */ | |
| 62 | + | |
| 63 | + /* The value of task_nice() of a task. */ | |
| 64 | + __u8 ac_nice; /* task_nice */ | |
| 65 | + | |
| 66 | + /* The name of the command that started this task. */ | |
| 67 | + char ac_comm[TS_COMM_LEN]; /* Command name */ | |
| 68 | + | |
| 69 | + /* The scheduling discipline as set in task->policy field. */ | |
| 70 | + __u8 ac_sched; /* Scheduling discipline */ | |
| 71 | + | |
| 72 | + __u8 ac_pad[3]; | |
| 73 | + __u32 ac_uid; /* User ID */ | |
| 74 | + __u32 ac_gid; /* Group ID */ | |
| 75 | + __u32 ac_pid; /* Process ID */ | |
| 76 | + __u32 ac_ppid; /* Parent process ID */ | |
| 77 | + | |
| 78 | + /* The time when a task begins, in [secs] since 1970. */ | |
| 79 | + __u32 ac_btime; /* Begin time [sec since 1970] */ | |
| 80 | + | |
| 81 | + /* The elapsed time of a task, in [usec]. */ | |
| 82 | + __u64 ac_etime; /* Elapsed time [usec] */ | |
| 83 | + | |
| 84 | + /* The user CPU time of a task, in [usec]. */ | |
| 85 | + __u64 ac_utime; /* User CPU time [usec] */ | |
| 86 | + | |
| 87 | + /* The system CPU time of a task, in [usec]. */ | |
| 88 | + __u64 ac_stime; /* System CPU time [usec] */ | |
| 89 | + | |
| 90 | + /* The minor page fault count of a task, as set in task->min_flt. */ | |
| 91 | + __u64 ac_minflt; /* Minor Page Fault Count */ | |
| 92 | + | |
| 93 | + /* The major page fault count of a task, as set in task->maj_flt. */ | |
| 94 | + __u64 ac_majflt; /* Major Page Fault Count */ | |
| 95 | + | |
| 96 | + | |
| 97 | +2) Delay accounting fields:: | |
| 98 | + | |
| 99 | + /* Delay accounting fields start | |
| 100 | + * | |
| 101 | + * All values, until the comment "Delay accounting fields end" are | |
| 102 | + * available only if delay accounting is enabled, even though the last | |
| 103 | + * few fields are not delays | |
| 104 | + * | |
| 105 | + * xxx_count is the number of delay values recorded | |
| 106 | + * xxx_delay_total is the corresponding cumulative delay in nanoseconds | |
| 107 | + * | |
| 108 | + * xxx_delay_total wraps around to zero on overflow | |
| 109 | + * xxx_count incremented regardless of overflow | |
| 110 | + */ | |
| 111 | + | |
| 112 | + /* Delay waiting for cpu, while runnable | |
| 113 | + * count, delay_total NOT updated atomically | |
| 114 | + */ | |
| 115 | + __u64 cpu_count; | |
| 116 | + __u64 cpu_delay_total; | |
| 117 | + | |
| 118 | + /* Following four fields atomically updated using task->delays->lock */ | |
| 119 | + | |
| 120 | + /* Delay waiting for synchronous block I/O to complete | |
| 121 | + * does not account for delays in I/O submission | |
| 122 | + */ | |
| 123 | + __u64 blkio_count; | |
| 124 | + __u64 blkio_delay_total; | |
| 125 | + | |
| 126 | + /* Delay waiting for page fault I/O (swap in only) */ | |
| 127 | + __u64 swapin_count; | |
| 128 | + __u64 swapin_delay_total; | |
| 129 | + | |
| 130 | + /* cpu "wall-clock" running time | |
| 131 | + * On some architectures, value will adjust for cpu time stolen | |
| 132 | + * from the kernel in involuntary waits due to virtualization. | |
| 133 | + * Value is cumulative, in nanoseconds, without a corresponding count | |
| 134 | + * and wraps around to zero silently on overflow | |
| 135 | + */ | |
| 136 | + __u64 cpu_run_real_total; | |
| 137 | + | |
| 138 | + /* cpu "virtual" running time | |
| 139 | + * Uses time intervals seen by the kernel i.e. no adjustment | |
| 140 | + * for kernel's involuntary waits due to virtualization. | |
| 141 | + * Value is cumulative, in nanoseconds, without a corresponding count | |
| 142 | + * and wraps around to zero silently on overflow | |
| 143 | + */ | |
| 144 | + __u64 cpu_run_virtual_total; | |
| 145 | + /* Delay accounting fields end */ | |
| 146 | + /* version 1 ends here */ | |
| 147 | + | |
| 148 | + | |
| 149 | +3) Extended accounting fields:: | |
| 150 | + | |
| 151 | + /* Extended accounting fields start */ | |
| 152 | + | |
| 153 | + /* Accumulated RSS usage in duration of a task, in MBytes-usecs. | |
| 154 | + * The current rss usage is added to this counter every time | |
| 155 | + * a tick is charged to a task's system time. So, at the end we | |
| 156 | + * will have memory usage multiplied by system time. Thus an | |
| 157 | + * average usage per system time unit can be calculated. | |
| 158 | + */ | |
| 159 | + __u64 coremem; /* accumulated RSS usage in MB-usec */ | |
| 160 | + | |
| 161 | + /* Accumulated virtual memory usage in duration of a task. | |
| 162 | + * Same as acct_rss_mem1 above except that we keep track of VM usage. | |
| 163 | + */ | |
| 164 | + __u64 virtmem; /* accumulated VM usage in MB-usec */ | |
| 165 | + | |
| 166 | + /* High watermark of RSS usage in duration of a task, in KBytes. */ | |
| 167 | + __u64 hiwater_rss; /* High-watermark of RSS usage */ | |
| 168 | + | |
| 169 | + /* High watermark of VM usage in duration of a task, in KBytes. */ | |
| 170 | + __u64 hiwater_vm; /* High-water virtual memory usage */ | |
| 171 | + | |
| 172 | + /* The following four fields are I/O statistics of a task. */ | |
| 173 | + __u64 read_char; /* bytes read */ | |
| 174 | + __u64 write_char; /* bytes written */ | |
| 175 | + __u64 read_syscalls; /* read syscalls */ | |
| 176 | + __u64 write_syscalls; /* write syscalls */ | |
| 177 | + | |
| 178 | + /* Extended accounting fields end */ | |
| 179 | + | |
| 180 | +4) Per-task and per-thread statistics:: | |
| 181 | + | |
| 182 | + __u64 nvcsw; /* Context voluntary switch counter */ | |
| 183 | + __u64 nivcsw; /* Context involuntary switch counter */ | |
| 184 | + | |
| 185 | +5) Time accounting for SMT machines:: | |
| 186 | + | |
| 187 | + __u64 ac_utimescaled; /* utime scaled on frequency etc */ | |
| 188 | + __u64 ac_stimescaled; /* stime scaled on frequency etc */ | |
| 189 | + __u64 cpu_scaled_run_real_total; /* scaled cpu_run_real_total */ | |
| 190 | + | |
| 191 | +6) Extended delay accounting fields for memory reclaim:: | |
| 192 | + | |
| 193 | + /* Delay waiting for memory reclaim */ | |
| 194 | + __u64 freepages_count; | |
| 195 | + __u64 freepages_delay_total; | |
| 196 | + | |
| 197 | +:: | |
| 198 | + | |
| 199 | + } | |
| @@ -1,180 +0,0 @@ | ||
| 1 | −The struct taskstats | |
| 2 | −-------------------- | |
| 3 | − | |
| 4 | −This document contains an explanation of the struct taskstats fields. | |
| 5 | − | |
| 6 | −There are three different groups of fields in the struct taskstats: | |
| 7 | − | |
| 8 | −1) Common and basic accounting fields | |
| 9 | − If CONFIG_TASKSTATS is set, the taskstats interface is enabled and | |
| 10 | − the common fields and basic accounting fields are collected for | |
| 11 | − delivery at do_exit() of a task. | |
| 12 | −2) Delay accounting fields | |
| 13 | − These fields are placed between | |
| 14 | − /* Delay accounting fields start */ | |
| 15 | − and | |
| 16 | − /* Delay accounting fields end */ | |
| 17 | − Their values are collected if CONFIG_TASK_DELAY_ACCT is set. | |
| 18 | −3) Extended accounting fields | |
| 19 | − These fields are placed between | |
| 20 | − /* Extended accounting fields start */ | |
| 21 | − and | |
| 22 | − /* Extended accounting fields end */ | |
| 23 | − Their values are collected if CONFIG_TASK_XACCT is set. | |
| 24 | − | |
| 25 | −4) Per-task and per-thread context switch count statistics | |
| 26 | − | |
| 27 | −5) Time accounting for SMT machines | |
| 28 | − | |
| 29 | −6) Extended delay accounting fields for memory reclaim | |
| 30 | − | |
| 31 | −Future extension should add fields to the end of the taskstats struct, and | |
| 32 | −should not change the relative position of each field within the struct. | |
| 33 | − | |
| 34 | − | |
| 35 | −struct taskstats { | |
| 36 | − | |
| 37 | −1) Common and basic accounting fields: | |
| 38 | − /* The version number of this struct. This field is always set to | |
| 39 | − * TAKSTATS_VERSION, which is defined in <linux/taskstats.h>. | |
| 40 | − * Each time the struct is changed, the value should be incremented. | |
| 41 | − */ | |
| 42 | − __u16 version; | |
| 43 | − | |
| 44 | − /* The exit code of a task. */ | |
| 45 | − __u32 ac_exitcode; /* Exit status */ | |
| 46 | − | |
| 47 | − /* The accounting flags of a task as defined in <linux/acct.h> | |
| 48 | − * Defined values are AFORK, ASU, ACOMPAT, ACORE, and AXSIG. | |
| 49 | − */ | |
| 50 | − __u8 ac_flag; /* Record flags */ | |
| 51 | − | |
| 52 | − /* The value of task_nice() of a task. */ | |
| 53 | − __u8 ac_nice; /* task_nice */ | |
| 54 | − | |
| 55 | − /* The name of the command that started this task. */ | |
| 56 | − char ac_comm[TS_COMM_LEN]; /* Command name */ | |
| 57 | − | |
| 58 | − /* The scheduling discipline as set in task->policy field. */ | |
| 59 | − __u8 ac_sched; /* Scheduling discipline */ | |
| 60 | − | |
| 61 | − __u8 ac_pad[3]; | |
| 62 | − __u32 ac_uid; /* User ID */ | |
| 63 | − __u32 ac_gid; /* Group ID */ | |
| 64 | − __u32 ac_pid; /* Process ID */ | |
| 65 | − __u32 ac_ppid; /* Parent process ID */ | |
| 66 | − | |
| 67 | − /* The time when a task begins, in [secs] since 1970. */ | |
| 68 | − __u32 ac_btime; /* Begin time [sec since 1970] */ | |
| 69 | − | |
| 70 | − /* The elapsed time of a task, in [usec]. */ | |
| 71 | − __u64 ac_etime; /* Elapsed time [usec] */ | |
| 72 | − | |
| 73 | − /* The user CPU time of a task, in [usec]. */ | |
| 74 | − __u64 ac_utime; /* User CPU time [usec] */ | |
| 75 | − | |
| 76 | − /* The system CPU time of a task, in [usec]. */ | |
| 77 | − __u64 ac_stime; /* System CPU time [usec] */ | |
| 78 | − | |
| 79 | − /* The minor page fault count of a task, as set in task->min_flt. */ | |
| 80 | − __u64 ac_minflt; /* Minor Page Fault Count */ | |
| 81 | − | |
| 82 | − /* The major page fault count of a task, as set in task->maj_flt. */ | |
| 83 | − __u64 ac_majflt; /* Major Page Fault Count */ | |
| 84 | − | |
| 85 | − | |
| 86 | −2) Delay accounting fields: | |
| 87 | − /* Delay accounting fields start | |
| 88 | − * | |
| 89 | − * All values, until the comment "Delay accounting fields end" are | |
| 90 | − * available only if delay accounting is enabled, even though the last | |
| 91 | − * few fields are not delays | |
| 92 | − * | |
| 93 | − * xxx_count is the number of delay values recorded | |
| 94 | − * xxx_delay_total is the corresponding cumulative delay in nanoseconds | |
| 95 | − * | |
| 96 | − * xxx_delay_total wraps around to zero on overflow | |
| 97 | − * xxx_count incremented regardless of overflow | |
| 98 | − */ | |
| 99 | − | |
| 100 | − /* Delay waiting for cpu, while runnable | |
| 101 | − * count, delay_total NOT updated atomically | |
| 102 | − */ | |
| 103 | − __u64 cpu_count; | |
| 104 | − __u64 cpu_delay_total; | |
| 105 | − | |
| 106 | − /* Following four fields atomically updated using task->delays->lock */ | |
| 107 | − | |
| 108 | − /* Delay waiting for synchronous block I/O to complete | |
| 109 | − * does not account for delays in I/O submission | |
| 110 | − */ | |
| 111 | − __u64 blkio_count; | |
| 112 | − __u64 blkio_delay_total; | |
| 113 | − | |
| 114 | − /* Delay waiting for page fault I/O (swap in only) */ | |
| 115 | − __u64 swapin_count; | |
| 116 | − __u64 swapin_delay_total; | |
| 117 | − | |
| 118 | − /* cpu "wall-clock" running time | |
| 119 | − * On some architectures, value will adjust for cpu time stolen | |
| 120 | − * from the kernel in involuntary waits due to virtualization. | |
| 121 | − * Value is cumulative, in nanoseconds, without a corresponding count | |
| 122 | − * and wraps around to zero silently on overflow | |
| 123 | − */ | |
| 124 | − __u64 cpu_run_real_total; | |
| 125 | − | |
| 126 | − /* cpu "virtual" running time | |
| 127 | − * Uses time intervals seen by the kernel i.e. no adjustment | |
| 128 | − * for kernel's involuntary waits due to virtualization. | |
| 129 | − * Value is cumulative, in nanoseconds, without a corresponding count | |
| 130 | − * and wraps around to zero silently on overflow | |
| 131 | − */ | |
| 132 | − __u64 cpu_run_virtual_total; | |
| 133 | − /* Delay accounting fields end */ | |
| 134 | − /* version 1 ends here */ | |
| 135 | − | |
| 136 | − | |
| 137 | −3) Extended accounting fields | |
| 138 | − /* Extended accounting fields start */ | |
| 139 | − | |
| 140 | − /* Accumulated RSS usage in duration of a task, in MBytes-usecs. | |
| 141 | − * The current rss usage is added to this counter every time | |
| 142 | − * a tick is charged to a task's system time. So, at the end we | |
| 143 | − * will have memory usage multiplied by system time. Thus an | |
| 144 | − * average usage per system time unit can be calculated. | |
| 145 | − */ | |
| 146 | − __u64 coremem; /* accumulated RSS usage in MB-usec */ | |
| 147 | − | |
| 148 | − /* Accumulated virtual memory usage in duration of a task. | |
| 149 | − * Same as acct_rss_mem1 above except that we keep track of VM usage. | |
| 150 | − */ | |
| 151 | − __u64 virtmem; /* accumulated VM usage in MB-usec */ | |
| 152 | − | |
| 153 | − /* High watermark of RSS usage in duration of a task, in KBytes. */ | |
| 154 | − __u64 hiwater_rss; /* High-watermark of RSS usage */ | |
| 155 | − | |
| 156 | − /* High watermark of VM usage in duration of a task, in KBytes. */ | |
| 157 | − __u64 hiwater_vm; /* High-water virtual memory usage */ | |
| 158 | − | |
| 159 | − /* The following four fields are I/O statistics of a task. */ | |
| 160 | − __u64 read_char; /* bytes read */ | |
| 161 | − __u64 write_char; /* bytes written */ | |
| 162 | − __u64 read_syscalls; /* read syscalls */ | |
| 163 | − __u64 write_syscalls; /* write syscalls */ | |
| 164 | − | |
| 165 | − /* Extended accounting fields end */ | |
| 166 | − | |
| 167 | −4) Per-task and per-thread statistics | |
| 168 | − __u64 nvcsw; /* Context voluntary switch counter */ | |
| 169 | − __u64 nivcsw; /* Context involuntary switch counter */ | |
| 170 | − | |
| 171 | −5) Time accounting for SMT machines | |
| 172 | − __u64 ac_utimescaled; /* utime scaled on frequency etc */ | |
| 173 | − __u64 ac_stimescaled; /* stime scaled on frequency etc */ | |
| 174 | − __u64 cpu_scaled_run_real_total; /* scaled cpu_run_real_total */ | |
| 175 | − | |
| 176 | −6) Extended delay accounting fields for memory reclaim | |
| 177 | − /* Delay waiting for memory reclaim */ | |
| 178 | − __u64 freepages_count; | |
| 179 | − __u64 freepages_delay_total; | |
| 180 | −} | |
| @@ -0,0 +1,180 @@ | ||
| 1 | +============================= | |
| 2 | +Per-task statistics interface | |
| 3 | +============================= | |
| 4 | + | |
| 5 | + | |
| 6 | +Taskstats is a netlink-based interface for sending per-task and | |
| 7 | +per-process statistics from the kernel to userspace. | |
| 8 | + | |
| 9 | +Taskstats was designed for the following benefits: | |
| 10 | + | |
| 11 | +- efficiently provide statistics during lifetime of a task and on its exit | |
| 12 | +- unified interface for multiple accounting subsystems | |
| 13 | +- extensibility for use by future accounting patches | |
| 14 | + | |
| 15 | +Terminology | |
| 16 | +----------- | |
| 17 | + | |
| 18 | +"pid", "tid" and "task" are used interchangeably and refer to the standard | |
| 19 | +Linux task defined by struct task_struct. per-pid stats are the same as | |
| 20 | +per-task stats. | |
| 21 | + | |
| 22 | +"tgid", "process" and "thread group" are used interchangeably and refer to the | |
| 23 | +tasks that share an mm_struct i.e. the traditional Unix process. Despite the | |
| 24 | +use of tgid, there is no special treatment for the task that is thread group | |
| 25 | +leader - a process is deemed alive as long as it has any task belonging to it. | |
| 26 | + | |
| 27 | +Usage | |
| 28 | +----- | |
| 29 | + | |
| 30 | +To get statistics during a task's lifetime, userspace opens a unicast netlink | |
| 31 | +socket (NETLINK_GENERIC family) and sends commands specifying a pid or a tgid. | |
| 32 | +The response contains statistics for a task (if pid is specified) or the sum of | |
| 33 | +statistics for all tasks of the process (if tgid is specified). | |
| 34 | + | |
| 35 | +To obtain statistics for tasks which are exiting, the userspace listener | |
| 36 | +sends a register command and specifies a cpumask. Whenever a task exits on | |
| 37 | +one of the cpus in the cpumask, its per-pid statistics are sent to the | |
| 38 | +registered listener. Using cpumasks allows the data received by one listener | |
| 39 | +to be limited and assists in flow control over the netlink interface and is | |
| 40 | +explained in more detail below. | |
| 41 | + | |
| 42 | +If the exiting task is the last thread exiting its thread group, | |
| 43 | +an additional record containing the per-tgid stats is also sent to userspace. | |
| 44 | +The latter contains the sum of per-pid stats for all threads in the thread | |
| 45 | +group, both past and present. | |
| 46 | + | |
| 47 | +getdelays.c is a simple utility demonstrating usage of the taskstats interface | |
| 48 | +for reporting delay accounting statistics. Users can register cpumasks, | |
| 49 | +send commands and process responses, listen for per-tid/tgid exit data, | |
| 50 | +write the data received to a file and do basic flow control by increasing | |
| 51 | +receive buffer sizes. | |
| 52 | + | |
| 53 | +Interface | |
| 54 | +--------- | |
| 55 | + | |
| 56 | +The user-kernel interface is encapsulated in include/linux/taskstats.h | |
| 57 | + | |
| 58 | +To avoid this documentation becoming obsolete as the interface evolves, only | |
| 59 | +an outline of the current version is given. taskstats.h always overrides the | |
| 60 | +description here. | |
| 61 | + | |
| 62 | +struct taskstats is the common accounting structure for both per-pid and | |
| 63 | +per-tgid data. It is versioned and can be extended by each accounting subsystem | |
| 64 | +that is added to the kernel. The fields and their semantics are defined in the | |
| 65 | +taskstats.h file. | |
| 66 | + | |
| 67 | +The data exchanged between user and kernel space is a netlink message belonging | |
| 68 | +to the NETLINK_GENERIC family and using the netlink attributes interface. | |
| 69 | +The messages are in the format:: | |
| 70 | + | |
| 71 | + +----------+- - -+-------------+-------------------+ | |
| 72 | + | nlmsghdr | Pad | genlmsghdr | taskstats payload | | |
| 73 | + +----------+- - -+-------------+-------------------+ | |
| 74 | + | |
| 75 | + | |
| 76 | +The taskstats payload is one of the following three kinds: | |
| 77 | + | |
| 78 | +1. Commands: Sent from user to kernel. Commands to get data on | |
| 79 | +a pid/tgid consist of one attribute, of type TASKSTATS_CMD_ATTR_PID/TGID, | |
| 80 | +containing a u32 pid or tgid in the attribute payload. The pid/tgid denotes | |
| 81 | +the task/process for which userspace wants statistics. | |
| 82 | + | |
| 83 | +Commands to register/deregister interest in exit data from a set of cpus | |
| 84 | +consist of one attribute, of type | |
| 85 | +TASKSTATS_CMD_ATTR_REGISTER/DEREGISTER_CPUMASK and contain a cpumask in the | |
| 86 | +attribute payload. The cpumask is specified as an ascii string of | |
| 87 | +comma-separated cpu ranges e.g. to listen to exit data from cpus 1,2,3,5,7,8 | |
| 88 | +the cpumask would be "1-3,5,7-8". If userspace forgets to deregister interest | |
| 89 | +in cpus before closing the listening socket, the kernel cleans up its interest | |
| 90 | +set over time. However, for the sake of efficiency, an explicit deregistration | |
| 91 | +is advisable. | |
| 92 | + | |
| 93 | +2. Response for a command: sent from the kernel in response to a userspace | |
| 94 | +command. The payload is a series of three attributes of type: | |
| 95 | + | |
| 96 | +a) TASKSTATS_TYPE_AGGR_PID/TGID : attribute containing no payload but indicates | |
| 97 | +a pid/tgid will be followed by some stats. | |
| 98 | + | |
| 99 | +b) TASKSTATS_TYPE_PID/TGID: attribute whose payload is the pid/tgid whose stats | |
| 100 | +are being returned. | |
| 101 | + | |
| 102 | +c) TASKSTATS_TYPE_STATS: attribute with a struct taskstats as payload. The | |
| 103 | +same structure is used for both per-pid and per-tgid stats. | |
| 104 | + | |
| 105 | +3. New message sent by kernel whenever a task exits. The payload consists of a | |
| 106 | + series of attributes of the following type: | |
| 107 | + | |
| 108 | +a) TASKSTATS_TYPE_AGGR_PID: indicates next two attributes will be pid+stats | |
| 109 | +b) TASKSTATS_TYPE_PID: contains exiting task's pid | |
| 110 | +c) TASKSTATS_TYPE_STATS: contains the exiting task's per-pid stats | |
| 111 | +d) TASKSTATS_TYPE_AGGR_TGID: indicates next two attributes will be tgid+stats | |
| 112 | +e) TASKSTATS_TYPE_TGID: contains tgid of process to which task belongs | |
| 113 | +f) TASKSTATS_TYPE_STATS: contains the per-tgid stats for exiting task's process | |
| 114 | + | |
| 115 | + | |
| 116 | +per-tgid stats | |
| 117 | +-------------- | |
| 118 | + | |
| 119 | +Taskstats provides per-process stats, in addition to per-task stats, since | |
| 120 | +resource management is often done at a process granularity and aggregating task | |
| 121 | +stats in userspace alone is inefficient and potentially inaccurate (due to lack | |
| 122 | +of atomicity). | |
| 123 | + | |
| 124 | +However, maintaining per-process, in addition to per-task stats, within the | |
| 125 | +kernel has space and time overheads. To address this, the taskstats code | |
| 126 | +accumulates each exiting task's statistics into a process-wide data structure. | |
| 127 | +When the last task of a process exits, the process level data accumulated also | |
| 128 | +gets sent to userspace (along with the per-task data). | |
| 129 | + | |
| 130 | +When a user queries to get per-tgid data, the sum of all other live threads in | |
| 131 | +the group is added up and added to the accumulated total for previously exited | |
| 132 | +threads of the same thread group. | |
| 133 | + | |
| 134 | +Extending taskstats | |
| 135 | +------------------- | |
| 136 | + | |
| 137 | +There are two ways to extend the taskstats interface to export more | |
| 138 | +per-task/process stats as patches to collect them get added to the kernel | |
| 139 | +in future: | |
| 140 | + | |
| 141 | +1. Adding more fields to the end of the existing struct taskstats. Backward | |
| 142 | + compatibility is ensured by the version number within the | |
| 143 | + structure. Userspace will use only the fields of the struct that correspond | |
| 144 | + to the version its using. | |
| 145 | + | |
| 146 | +2. Defining separate statistic structs and using the netlink attributes | |
| 147 | + interface to return them. Since userspace processes each netlink attribute | |
| 148 | + independently, it can always ignore attributes whose type it does not | |
| 149 | + understand (because it is using an older version of the interface). | |
| 150 | + | |
| 151 | + | |
| 152 | +Choosing between 1. and 2. is a matter of trading off flexibility and | |
| 153 | +overhead. If only a few fields need to be added, then 1. is the preferable | |
| 154 | +path since the kernel and userspace don't need to incur the overhead of | |
| 155 | +processing new netlink attributes. But if the new fields expand the existing | |
| 156 | +struct too much, requiring disparate userspace accounting utilities to | |
| 157 | +unnecessarily receive large structures whose fields are of no interest, then | |
| 158 | +extending the attributes structure would be worthwhile. | |
| 159 | + | |
| 160 | +Flow control for taskstats | |
| 161 | +-------------------------- | |
| 162 | + | |
| 163 | +When the rate of task exits becomes large, a listener may not be able to keep | |
| 164 | +up with the kernel's rate of sending per-tid/tgid exit data leading to data | |
| 165 | +loss. This possibility gets compounded when the taskstats structure gets | |
| 166 | +extended and the number of cpus grows large. | |
| 167 | + | |
| 168 | +To avoid losing statistics, userspace should do one or more of the following: | |
| 169 | + | |
| 170 | +- increase the receive buffer sizes for the netlink sockets opened by | |
| 171 | + listeners to receive exit data. | |
| 172 | + | |
| 173 | +- create more listeners and reduce the number of cpus being listened to by | |
| 174 | + each listener. In the extreme case, there could be one listener for each cpu. | |
| 175 | + Users may also consider setting the cpu affinity of the listener to the subset | |
| 176 | + of cpus to which it listens, especially if they are listening to just one cpu. | |
| 177 | + | |
| 178 | +Despite these measures, if the userspace receives ENOBUFS error messages | |
| 179 | +indicated overflow of receive buffers, it should take measures to handle the | |
| 180 | +loss of data. | |
| @@ -1,181 +0,0 @@ | ||
| 1 | −Per-task statistics interface | |
| 2 | −----------------------------- | |
| 3 | − | |
| 4 | − | |
| 5 | −Taskstats is a netlink-based interface for sending per-task and | |
| 6 | −per-process statistics from the kernel to userspace. | |
| 7 | − | |
| 8 | −Taskstats was designed for the following benefits: | |
| 9 | − | |
| 10 | −- efficiently provide statistics during lifetime of a task and on its exit | |
| 11 | −- unified interface for multiple accounting subsystems | |
| 12 | −- extensibility for use by future accounting patches | |
| 13 | − | |
| 14 | −Terminology | |
| 15 | −----------- | |
| 16 | − | |
| 17 | −"pid", "tid" and "task" are used interchangeably and refer to the standard | |
| 18 | −Linux task defined by struct task_struct. per-pid stats are the same as | |
| 19 | −per-task stats. | |
| 20 | − | |
| 21 | −"tgid", "process" and "thread group" are used interchangeably and refer to the | |
| 22 | −tasks that share an mm_struct i.e. the traditional Unix process. Despite the | |
| 23 | −use of tgid, there is no special treatment for the task that is thread group | |
| 24 | −leader - a process is deemed alive as long as it has any task belonging to it. | |
| 25 | − | |
| 26 | −Usage | |
| 27 | −----- | |
| 28 | − | |
| 29 | −To get statistics during a task's lifetime, userspace opens a unicast netlink | |
| 30 | −socket (NETLINK_GENERIC family) and sends commands specifying a pid or a tgid. | |
| 31 | −The response contains statistics for a task (if pid is specified) or the sum of | |
| 32 | −statistics for all tasks of the process (if tgid is specified). | |
| 33 | − | |
| 34 | −To obtain statistics for tasks which are exiting, the userspace listener | |
| 35 | −sends a register command and specifies a cpumask. Whenever a task exits on | |
| 36 | −one of the cpus in the cpumask, its per-pid statistics are sent to the | |
| 37 | −registered listener. Using cpumasks allows the data received by one listener | |
| 38 | −to be limited and assists in flow control over the netlink interface and is | |
| 39 | −explained in more detail below. | |
| 40 | − | |
| 41 | −If the exiting task is the last thread exiting its thread group, | |
| 42 | −an additional record containing the per-tgid stats is also sent to userspace. | |
| 43 | −The latter contains the sum of per-pid stats for all threads in the thread | |
| 44 | −group, both past and present. | |
| 45 | − | |
| 46 | −getdelays.c is a simple utility demonstrating usage of the taskstats interface | |
| 47 | −for reporting delay accounting statistics. Users can register cpumasks, | |
| 48 | −send commands and process responses, listen for per-tid/tgid exit data, | |
| 49 | −write the data received to a file and do basic flow control by increasing | |
| 50 | −receive buffer sizes. | |
| 51 | − | |
| 52 | −Interface | |
| 53 | −--------- | |
| 54 | − | |
| 55 | −The user-kernel interface is encapsulated in include/linux/taskstats.h | |
| 56 | − | |
| 57 | −To avoid this documentation becoming obsolete as the interface evolves, only | |
| 58 | −an outline of the current version is given. taskstats.h always overrides the | |
| 59 | −description here. | |
| 60 | − | |
| 61 | −struct taskstats is the common accounting structure for both per-pid and | |
| 62 | −per-tgid data. It is versioned and can be extended by each accounting subsystem | |
| 63 | −that is added to the kernel. The fields and their semantics are defined in the | |
| 64 | −taskstats.h file. | |
| 65 | − | |
| 66 | −The data exchanged between user and kernel space is a netlink message belonging | |
| 67 | −to the NETLINK_GENERIC family and using the netlink attributes interface. | |
| 68 | −The messages are in the format | |
| 69 | − | |
| 70 | − +----------+- - -+-------------+-------------------+ | |
| 71 | − | nlmsghdr | Pad | genlmsghdr | taskstats payload | | |
| 72 | − +----------+- - -+-------------+-------------------+ | |
| 73 | − | |
| 74 | − | |
| 75 | −The taskstats payload is one of the following three kinds: | |
| 76 | − | |
| 77 | −1. Commands: Sent from user to kernel. Commands to get data on | |
| 78 | −a pid/tgid consist of one attribute, of type TASKSTATS_CMD_ATTR_PID/TGID, | |
| 79 | −containing a u32 pid or tgid in the attribute payload. The pid/tgid denotes | |
| 80 | −the task/process for which userspace wants statistics. | |
| 81 | − | |
| 82 | −Commands to register/deregister interest in exit data from a set of cpus | |
| 83 | −consist of one attribute, of type | |
| 84 | −TASKSTATS_CMD_ATTR_REGISTER/DEREGISTER_CPUMASK and contain a cpumask in the | |
| 85 | −attribute payload. The cpumask is specified as an ascii string of | |
| 86 | −comma-separated cpu ranges e.g. to listen to exit data from cpus 1,2,3,5,7,8 | |
| 87 | −the cpumask would be "1-3,5,7-8". If userspace forgets to deregister interest | |
| 88 | −in cpus before closing the listening socket, the kernel cleans up its interest | |
| 89 | −set over time. However, for the sake of efficiency, an explicit deregistration | |
| 90 | −is advisable. | |
| 91 | − | |
| 92 | −2. Response for a command: sent from the kernel in response to a userspace | |
| 93 | −command. The payload is a series of three attributes of type: | |
| 94 | − | |
| 95 | −a) TASKSTATS_TYPE_AGGR_PID/TGID : attribute containing no payload but indicates | |
| 96 | −a pid/tgid will be followed by some stats. | |
| 97 | − | |
| 98 | −b) TASKSTATS_TYPE_PID/TGID: attribute whose payload is the pid/tgid whose stats | |
| 99 | −are being returned. | |
| 100 | − | |
| 101 | −c) TASKSTATS_TYPE_STATS: attribute with a struct taskstats as payload. The | |
| 102 | −same structure is used for both per-pid and per-tgid stats. | |
| 103 | − | |
| 104 | −3. New message sent by kernel whenever a task exits. The payload consists of a | |
| 105 | − series of attributes of the following type: | |
| 106 | − | |
| 107 | −a) TASKSTATS_TYPE_AGGR_PID: indicates next two attributes will be pid+stats | |
| 108 | −b) TASKSTATS_TYPE_PID: contains exiting task's pid | |
| 109 | −c) TASKSTATS_TYPE_STATS: contains the exiting task's per-pid stats | |
| 110 | −d) TASKSTATS_TYPE_AGGR_TGID: indicates next two attributes will be tgid+stats | |
| 111 | −e) TASKSTATS_TYPE_TGID: contains tgid of process to which task belongs | |
| 112 | −f) TASKSTATS_TYPE_STATS: contains the per-tgid stats for exiting task's process | |
| 113 | − | |
| 114 | − | |
| 115 | −per-tgid stats | |
| 116 | −-------------- | |
| 117 | − | |
| 118 | −Taskstats provides per-process stats, in addition to per-task stats, since | |
| 119 | −resource management is often done at a process granularity and aggregating task | |
| 120 | −stats in userspace alone is inefficient and potentially inaccurate (due to lack | |
| 121 | −of atomicity). | |
| 122 | − | |
| 123 | −However, maintaining per-process, in addition to per-task stats, within the | |
| 124 | −kernel has space and time overheads. To address this, the taskstats code | |
| 125 | −accumulates each exiting task's statistics into a process-wide data structure. | |
| 126 | −When the last task of a process exits, the process level data accumulated also | |
| 127 | −gets sent to userspace (along with the per-task data). | |
| 128 | − | |
| 129 | −When a user queries to get per-tgid data, the sum of all other live threads in | |
| 130 | −the group is added up and added to the accumulated total for previously exited | |
| 131 | −threads of the same thread group. | |
| 132 | − | |
| 133 | −Extending taskstats | |
| 134 | −------------------- | |
| 135 | − | |
| 136 | −There are two ways to extend the taskstats interface to export more | |
| 137 | −per-task/process stats as patches to collect them get added to the kernel | |
| 138 | −in future: | |
| 139 | − | |
| 140 | −1. Adding more fields to the end of the existing struct taskstats. Backward | |
| 141 | − compatibility is ensured by the version number within the | |
| 142 | − structure. Userspace will use only the fields of the struct that correspond | |
| 143 | − to the version its using. | |
| 144 | − | |
| 145 | −2. Defining separate statistic structs and using the netlink attributes | |
| 146 | − interface to return them. Since userspace processes each netlink attribute | |
| 147 | − independently, it can always ignore attributes whose type it does not | |
| 148 | − understand (because it is using an older version of the interface). | |
| 149 | − | |
| 150 | − | |
| 151 | −Choosing between 1. and 2. is a matter of trading off flexibility and | |
| 152 | −overhead. If only a few fields need to be added, then 1. is the preferable | |
| 153 | −path since the kernel and userspace don't need to incur the overhead of | |
| 154 | −processing new netlink attributes. But if the new fields expand the existing | |
| 155 | −struct too much, requiring disparate userspace accounting utilities to | |
| 156 | −unnecessarily receive large structures whose fields are of no interest, then | |
| 157 | −extending the attributes structure would be worthwhile. | |
| 158 | − | |
| 159 | −Flow control for taskstats | |
| 160 | −-------------------------- | |
| 161 | − | |
| 162 | −When the rate of task exits becomes large, a listener may not be able to keep | |
| 163 | −up with the kernel's rate of sending per-tid/tgid exit data leading to data | |
| 164 | −loss. This possibility gets compounded when the taskstats structure gets | |
| 165 | −extended and the number of cpus grows large. | |
| 166 | − | |
| 167 | −To avoid losing statistics, userspace should do one or more of the following: | |
| 168 | − | |
| 169 | −- increase the receive buffer sizes for the netlink sockets opened by | |
| 170 | −listeners to receive exit data. | |
| 171 | − | |
| 172 | −- create more listeners and reduce the number of cpus being listened to by | |
| 173 | −each listener. In the extreme case, there could be one listener for each cpu. | |
| 174 | −Users may also consider setting the cpu affinity of the listener to the subset | |
| 175 | −of cpus to which it listens, especially if they are listening to just one cpu. | |
| 176 | − | |
| 177 | −Despite these measures, if the userspace receives ENOBUFS error messages | |
| 178 | −indicated overflow of receive buffers, it should take measures to handle the | |
| 179 | −loss of data. | |
| 180 | − | |
| 181 | −---- | |
| @@ -96,4 +96,4 @@ where · 95 unmodified lines | ||
| 96 | 96 | <URL:http://www.uefi.org/sites/default/files/resources/_DSD-hierarchical-data-extension-UUID-v1.1.pdf>, |
| 97 | 97 | referenced 2019-02-21. |
| 98 | 98 | |
| 99 | −[7] Documentation/acpi/dsd/data-node-reference.txt | |
| 99 | +[7] Documentation/firmware-guide/acpi/dsd/data-node-references.rst | |
| @@ -19,3 +19,13 @@ block device backing the filesystem is not read-only, a sysctl is · 18 unmodified lines | ||
| 19 | 19 | created to toggle pinning: ``/proc/sys/kernel/loadpin/enabled``. (Having |
| 20 | 20 | a mutable filesystem means pinning is mutable too, but having the |
| 21 | 21 | sysctl allows for easy testing on systems with a mutable filesystem.) |
| 22 | + | |
| 23 | +It's also possible to exclude specific file types from LoadPin using kernel | |
| 24 | +command line option "``loadpin.exclude``". By default, all files are | |
| 25 | +included, but they can be excluded using kernel command line option such | |
| 26 | +as "``loadpin.exclude=kernel-module,kexec-image``". This allows to use | |
| 27 | +different mechanisms such as ``CONFIG_MODULE_SIG`` and | |
| 28 | +``CONFIG_KEXEC_VERIFY_SIG`` to verify kernel module and kernel image while | |
| 29 | +still use LoadPin to protect the integrity of other files kernel loads. The | |
| 30 | +full list of valid file types can be found in ``kernel_read_file_str`` | |
| 31 | +defined in ``include/linux/fs.h``. | |
| @@ -227,7 +227,7 @@ Configuring the kernel · 226 unmodified lines | ||
| 227 | 227 | "make tinyconfig" Configure the tiniest possible kernel. |
| 228 | 228 | |
| 229 | 229 | 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 | 232 | - NOTES on ``make config``: |
| 233 | 233 | |
| @@ -0,0 +1,150 @@ | ||
| 1 | +Introduction | |
| 2 | +============ | |
| 3 | + | |
| 4 | +ATA over Ethernet is a network protocol that provides simple access to | |
| 5 | +block storage on the LAN. | |
| 6 | + | |
| 7 | + http://support.coraid.com/documents/AoEr11.txt | |
| 8 | + | |
| 9 | +The EtherDrive (R) HOWTO for 2.6 and 3.x kernels is found at ... | |
| 10 | + | |
| 11 | + http://support.coraid.com/support/linux/EtherDrive-2.6-HOWTO.html | |
| 12 | + | |
| 13 | +It has many tips and hints! Please see, especially, recommended | |
| 14 | +tunings for virtual memory: | |
| 15 | + | |
| 16 | + http://support.coraid.com/support/linux/EtherDrive-2.6-HOWTO-5.html#ss5.19 | |
| 17 | + | |
| 18 | +The aoetools are userland programs that are designed to work with this | |
| 19 | +driver. The aoetools are on sourceforge. | |
| 20 | + | |
| 21 | + http://aoetools.sourceforge.net/ | |
| 22 | + | |
| 23 | +The scripts in this Documentation/admin-guide/aoe directory are intended to | |
| 24 | +document the use of the driver and are not necessary if you install | |
| 25 | +the aoetools. | |
| 26 | + | |
| 27 | + | |
| 28 | +Creating Device Nodes | |
| 29 | +===================== | |
| 30 | + | |
| 31 | + Users of udev should find the block device nodes created | |
| 32 | + automatically, but to create all the necessary device nodes, use the | |
| 33 | + udev configuration rules provided in udev.txt (in this directory). | |
| 34 | + | |
| 35 | + There is a udev-install.sh script that shows how to install these | |
| 36 | + rules on your system. | |
| 37 | + | |
| 38 | + There is also an autoload script that shows how to edit | |
| 39 | + /etc/modprobe.d/aoe.conf to ensure that the aoe module is loaded when | |
| 40 | + necessary. Preloading the aoe module is preferable to autoloading, | |
| 41 | + however, because AoE discovery takes a few seconds. It can be | |
| 42 | + confusing when an AoE device is not present the first time the a | |
| 43 | + command is run but appears a second later. | |
| 44 | + | |
| 45 | +Using Device Nodes | |
| 46 | +================== | |
| 47 | + | |
| 48 | + "cat /dev/etherd/err" blocks, waiting for error diagnostic output, | |
| 49 | + like any retransmitted packets. | |
| 50 | + | |
| 51 | + "echo eth2 eth4 > /dev/etherd/interfaces" tells the aoe driver to | |
| 52 | + limit ATA over Ethernet traffic to eth2 and eth4. AoE traffic from | |
| 53 | + untrusted networks should be ignored as a matter of security. See | |
| 54 | + also the aoe_iflist driver option described below. | |
| 55 | + | |
| 56 | + "echo > /dev/etherd/discover" tells the driver to find out what AoE | |
| 57 | + devices are available. | |
| 58 | + | |
| 59 | + In the future these character devices may disappear and be replaced | |
| 60 | + by sysfs counterparts. Using the commands in aoetools insulates | |
| 61 | + users from these implementation details. | |
| 62 | + | |
| 63 | + The block devices are named like this:: | |
| 64 | + | |
| 65 | + e{shelf}.{slot} | |
| 66 | + e{shelf}.{slot}p{part} | |
| 67 | + | |
| 68 | + ... so that "e0.2" is the third blade from the left (slot 2) in the | |
| 69 | + first shelf (shelf address zero). That's the whole disk. The first | |
| 70 | + partition on that disk would be "e0.2p1". | |
| 71 | + | |
| 72 | +Using sysfs | |
| 73 | +=========== | |
| 74 | + | |
| 75 | + Each aoe block device in /sys/block has the extra attributes of | |
| 76 | + state, mac, and netif. The state attribute is "up" when the device | |
| 77 | + is ready for I/O and "down" if detected but unusable. The | |
| 78 | + "down,closewait" state shows that the device is still open and | |
| 79 | + cannot come up again until it has been closed. | |
| 80 | + | |
| 81 | + The mac attribute is the ethernet address of the remote AoE device. | |
| 82 | + The netif attribute is the network interface on the localhost | |
| 83 | + through which we are communicating with the remote AoE device. | |
| 84 | + | |
| 85 | + There is a script in this directory that formats this information in | |
| 86 | + a convenient way. Users with aoetools should use the aoe-stat | |
| 87 | + command:: | |
| 88 | + | |
| 89 | + root@makki root# sh Documentation/admin-guide/aoe/status.sh | |
| 90 | + e10.0 eth3 up | |
| 91 | + e10.1 eth3 up | |
| 92 | + e10.2 eth3 up | |
| 93 | + e10.3 eth3 up | |
| 94 | + e10.4 eth3 up | |
| 95 | + e10.5 eth3 up | |
| 96 | + e10.6 eth3 up | |
| 97 | + e10.7 eth3 up | |
| 98 | + e10.8 eth3 up | |
| 99 | + e10.9 eth3 up | |
| 100 | + e4.0 eth1 up | |
| 101 | + e4.1 eth1 up | |
| 102 | + e4.2 eth1 up | |
| 103 | + e4.3 eth1 up | |
| 104 | + e4.4 eth1 up | |
| 105 | + e4.5 eth1 up | |
| 106 | + e4.6 eth1 up | |
| 107 | + e4.7 eth1 up | |
| 108 | + e4.8 eth1 up | |
| 109 | + e4.9 eth1 up | |
| 110 | + | |
| 111 | + Use /sys/module/aoe/parameters/aoe_iflist (or better, the driver | |
| 112 | + option discussed below) instead of /dev/etherd/interfaces to limit | |
| 113 | + AoE traffic to the network interfaces in the given | |
| 114 | + whitespace-separated list. Unlike the old character device, the | |
| 115 | + sysfs entry can be read from as well as written to. | |
| 116 | + | |
| 117 | + It's helpful to trigger discovery after setting the list of allowed | |
| 118 | + interfaces. The aoetools package provides an aoe-discover script | |
| 119 | + for this purpose. You can also directly use the | |
| 120 | + /dev/etherd/discover special file described above. | |
| 121 | + | |
| 122 | +Driver Options | |
| 123 | +============== | |
| 124 | + | |
| 125 | + There is a boot option for the built-in aoe driver and a | |
| 126 | + corresponding module parameter, aoe_iflist. Without this option, | |
| 127 | + all network interfaces may be used for ATA over Ethernet. Here is a | |
| 128 | + usage example for the module parameter:: | |
| 129 | + | |
| 130 | + modprobe aoe_iflist="eth1 eth3" | |
| 131 | + | |
| 132 | + The aoe_deadsecs module parameter determines the maximum number of | |
| 133 | + seconds that the driver will wait for an AoE device to provide a | |
| 134 | + response to an AoE command. After aoe_deadsecs seconds have | |
| 135 | + elapsed, the AoE device will be marked as "down". A value of zero | |
| 136 | + is supported for testing purposes and makes the aoe driver keep | |
| 137 | + trying AoE commands forever. | |
| 138 | + | |
| 139 | + The aoe_maxout module parameter has a default of 128. This is the | |
| 140 | + maximum number of unresponded packets that will be sent to an AoE | |
| 141 | + target at one time. | |
| 142 | + | |
| 143 | + The aoe_dyndevs module parameter defaults to 1, meaning that the | |
| 144 | + driver will assign a block device minor number to a discovered AoE | |
| 145 | + target based on the order of its discovery. With dynamic minor | |
| 146 | + device numbers in use, a greater range of AoE shelf and slot | |
| 147 | + addresses can be supported. Users with udev will never have to | |
| 148 | + think about minor numbers. Using aoe_dyndevs=0 allows device nodes | |
| 149 | + to be pre-created using a static minor-number scheme with the | |
| 150 | + aoe-mkshelf script in the aoetools. | |
File renamed without changes.
| @@ -0,0 +1,23 @@ | ||
| 1 | +Example of udev rules | |
| 2 | +--------------------- | |
| 3 | + | |
| 4 | + .. include:: udev.txt | |
| 5 | + :literal: | |
| 6 | + | |
| 7 | +Example of udev install rules script | |
| 8 | +------------------------------------ | |
| 9 | + | |
| 10 | + .. literalinclude:: udev-install.sh | |
| 11 | + :language: shell | |
| 12 | + | |
| 13 | +Example script to get status | |
| 14 | +---------------------------- | |
| 15 | + | |
| 16 | + .. literalinclude:: status.sh | |
| 17 | + :language: shell | |
| 18 | + | |
| 19 | +Example of AoE autoload script | |
| 20 | +------------------------------ | |
| 21 | + | |
| 22 | + .. literalinclude:: autoload.sh | |
| 23 | + :language: shell | |
| @@ -0,0 +1,17 @@ | ||
| 1 | +======================= | |
| 2 | +ATA over Ethernet (AoE) | |
| 3 | +======================= | |
| 4 | + | |
| 5 | +.. toctree:: | |
| 6 | + :maxdepth: 1 | |
| 7 | + | |
| 8 | + aoe | |
| 9 | + todo | |
| 10 | + examples | |
| 11 | + | |
| 12 | +.. only:: subproject and html | |
| 13 | + | |
| 14 | + Indices | |
| 15 | + ======= | |
| 16 | + | |
| 17 | + * :ref:`genindex` | |
File renamed without changes.
| @@ -0,0 +1,17 @@ | ||
| 1 | +TODO | |
| 2 | +==== | |
| 3 | + | |
| 4 | +There is a potential for deadlock when allocating a struct sk_buff for | |
| 5 | +data that needs to be written out to aoe storage. If the data is | |
| 6 | +being written from a dirty page in order to free that page, and if | |
| 7 | +there are no other pages available, then deadlock may occur when a | |
| 8 | +free page is needed for the sk_buff allocation. This situation has | |
| 9 | +not been observed, but it would be nice to eliminate any potential for | |
| 10 | +deadlock under memory pressure. | |
| 11 | + | |
| 12 | +Because ATA over Ethernet is not fragmented by the kernel's IP code, | |
| 13 | +the destructor member of the struct sk_buff is available to the aoe | |
| 14 | +driver. By using a mempool for allocating all but the first few | |
| 15 | +sk_buffs, and by registering a destructor, we should be able to | |
| 16 | +efficiently allocate sk_buffs without introducing any potential for | |
| 17 | +deadlock. | |
File renamed without changes.
| @@ -11,7 +11,7 @@ · 10 unmodified lines | ||
| 11 | 11 | # udev_rules="/etc/udev/rules.d/" |
| 12 | 12 | # bash# ls /etc/udev/rules.d/ |
| 13 | 13 | # 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 | 15 | # /etc/udev/rules.d/60-aoe.rules |
| 16 | 16 | # |
| 17 | 17 | |
File renamed without changes.
File renamed without changes.
File renamed without changes.
File renamed without changes.
| @@ -0,0 +1,42 @@ | ||
| 1 | +================================ | |
| 2 | +kernel data structure for DRBD-9 | |
| 3 | +================================ | |
| 4 | + | |
| 5 | +This describes the in kernel data structure for DRBD-9. Starting with | |
| 6 | +Linux v3.14 we are reorganizing DRBD to use this data structure. | |
| 7 | + | |
| 8 | +Basic Data Structure | |
| 9 | +==================== | |
| 10 | + | |
| 11 | +A node has a number of DRBD resources. Each such resource has a number of | |
| 12 | +devices (aka volumes) and connections to other nodes ("peer nodes"). Each DRBD | |
| 13 | +device is represented by a block device locally. | |
| 14 | + | |
| 15 | +The DRBD objects are interconnected to form a matrix as depicted below; a | |
| 16 | +drbd_peer_device object sits at each intersection between a drbd_device and a | |
| 17 | +drbd_connection:: | |
| 18 | + | |
| 19 | + /--------------+---------------+.....+---------------\ | |
| 20 | + | resource | device | | device | | |
| 21 | + +--------------+---------------+.....+---------------+ | |
| 22 | + | connection | peer_device | | peer_device | | |
| 23 | + +--------------+---------------+.....+---------------+ | |
| 24 | + : : : : : | |
| 25 | + : : : : : | |
| 26 | + +--------------+---------------+.....+---------------+ | |
| 27 | + | connection | peer_device | | peer_device | | |
| 28 | + \--------------+---------------+.....+---------------/ | |
| 29 | + | |
| 30 | +In this table, horizontally, devices can be accessed from resources by their | |
| 31 | +volume number. Likewise, peer_devices can be accessed from connections by | |
| 32 | +their volume number. Objects in the vertical direction are connected by double | |
| 33 | +linked lists. There are back pointers from peer_devices to their connections a | |
| 34 | +devices, and from connections and devices to their resource. | |
| 35 | + | |
| 36 | +All resources are in the drbd_resources double-linked list. In addition, all | |
| 37 | +devices can be accessed by their minor device number via the drbd_devices idr. | |
| 38 | + | |
| 39 | +The drbd_resource, drbd_connection, and drbd_device objects are reference | |
| 40 | +counted. The peer_device objects only serve to establish the links between | |
| 41 | +devices and connections; their lifetime is determined by the lifetime of the | |
| 42 | +device and connection which they reference. | |
File renamed without changes.
File renamed without changes.
| @@ -0,0 +1,30 @@ | ||
| 1 | +.. SPDX-License-Identifier: GPL-2.0 | |
| 2 | + | |
| 3 | +.. The here included files are intended to help understand the implementation | |
| 4 | + | |
| 5 | +Data flows that Relate some functions, and write packets | |
| 6 | +======================================================== | |
| 7 | + | |
| 8 | +.. kernel-figure:: DRBD-8.3-data-packets.svg | |
| 9 | + :alt: DRBD-8.3-data-packets.svg | |
| 10 | + :align: center | |
| 11 | + | |
| 12 | +.. kernel-figure:: DRBD-data-packets.svg | |
| 13 | + :alt: DRBD-data-packets.svg | |
| 14 | + :align: center | |
| 15 | + | |
| 16 | + | |
| 17 | +Sub graphs of DRBD's state transitions | |
| 18 | +====================================== | |
| 19 | + | |
| 20 | +.. kernel-figure:: conn-states-8.dot | |
| 21 | + :alt: conn-states-8.dot | |
| 22 | + :align: center | |
| 23 | + | |
| 24 | +.. kernel-figure:: disk-states-8.dot | |
| 25 | + :alt: disk-states-8.dot | |
| 26 | + :align: center | |
| 27 | + | |
| 28 | +.. kernel-figure:: node-states-8.dot | |
| 29 | + :alt: node-states-8.dot | |
| 30 | + :align: center | |
| @@ -0,0 +1,19 @@ | ||
| 1 | +========================================== | |
| 2 | +Distributed Replicated Block Device - DRBD | |
| 3 | +========================================== | |
| 4 | + | |
| 5 | +Description | |
| 6 | +=========== | |
| 7 | + | |
| 8 | + DRBD is a shared-nothing, synchronously replicated block device. It | |
| 9 | + is designed to serve as a building block for high availability | |
| 10 | + clusters and in this context, is a "drop-in" replacement for shared | |
| 11 | + storage. Simplistically, you could see it as a network RAID 1. | |
| 12 | + | |
| 13 | + Please visit http://www.drbd.org to find out more. | |
| 14 | + | |
| 15 | +.. toctree:: | |
| 16 | + :maxdepth: 1 | |
| 17 | + | |
| 18 | + data-structure-v9 | |
| 19 | + figures | |
| @@ -11,4 +11,3 @@ digraph peer_states { · 10 unmodified lines | ||
| 11 | 11 | Unknown -> Primary [ label = "connected" ] |
| 12 | 12 | Unknown -> Secondary [ label = "connected" ] |
| 13 | 13 | } |
| 14 | − | |
| @@ -0,0 +1,255 @@ | ||
| 1 | +============= | |
| 2 | +Floppy Driver | |
| 3 | +============= | |
| 4 | + | |
| 5 | +FAQ list: | |
| 6 | +========= | |
| 7 | + | |
| 8 | +A FAQ list may be found in the fdutils package (see below), and also | |
| 9 | +at <http://fdutils.linux.lu/faq.html>. | |
| 10 | + | |
| 11 | + | |
| 12 | +LILO configuration options (Thinkpad users, read this) | |
| 13 | +====================================================== | |
| 14 | + | |
| 15 | +The floppy driver is configured using the 'floppy=' option in | |
| 16 | +lilo. This option can be typed at the boot prompt, or entered in the | |
| 17 | +lilo configuration file. | |
| 18 | + | |
| 19 | +Example: If your kernel is called linux-2.6.9, type the following line | |
| 20 | +at the lilo boot prompt (if you have a thinkpad):: | |
| 21 | + | |
| 22 | + linux-2.6.9 floppy=thinkpad | |
| 23 | + | |
| 24 | +You may also enter the following line in /etc/lilo.conf, in the description | |
| 25 | +of linux-2.6.9:: | |
| 26 | + | |
| 27 | + append = "floppy=thinkpad" | |
| 28 | + | |
| 29 | +Several floppy related options may be given, example:: | |
| 30 | + | |
| 31 | + linux-2.6.9 floppy=daring floppy=two_fdc | |
| 32 | + append = "floppy=daring floppy=two_fdc" | |
| 33 | + | |
| 34 | +If you give options both in the lilo config file and on the boot | |
| 35 | +prompt, the option strings of both places are concatenated, the boot | |
| 36 | +prompt options coming last. That's why there are also options to | |
| 37 | +restore the default behavior. | |
| 38 | + | |
| 39 | + | |
| 40 | +Module configuration options | |
| 41 | +============================ | |
| 42 | + | |
| 43 | +If you use the floppy driver as a module, use the following syntax:: | |
| 44 | + | |
| 45 | + modprobe floppy floppy="<options>" | |
| 46 | + | |
| 47 | +Example:: | |
| 48 | + | |
| 49 | + modprobe floppy floppy="omnibook messages" | |
| 50 | + | |
| 51 | +If you need certain options enabled every time you load the floppy driver, | |
| 52 | +you can put:: | |
| 53 | + | |
| 54 | + options floppy floppy="omnibook messages" | |
| 55 | + | |
| 56 | +in a configuration file in /etc/modprobe.d/. | |
| 57 | + | |
| 58 | + | |
| 59 | +The floppy driver related options are: | |
| 60 | + | |
| 61 | + floppy=asus_pci | |
| 62 | + Sets the bit mask to allow only units 0 and 1. (default) | |
| 63 | + | |
| 64 | + floppy=daring | |
| 65 | + Tells the floppy driver that you have a well behaved floppy controller. | |
| 66 | + This allows more efficient and smoother operation, but may fail on | |
| 67 | + certain controllers. This may speed up certain operations. | |
| 68 | + | |
| 69 | + floppy=0,daring | |
| 70 | + Tells the floppy driver that your floppy controller should be used | |
| 71 | + with caution. | |
| 72 | + | |
| 73 | + floppy=one_fdc | |
| 74 | + Tells the floppy driver that you have only one floppy controller. | |
| 75 | + (default) | |
| 76 | + | |
| 77 | + floppy=two_fdc / floppy=<address>,two_fdc | |
| 78 | + Tells the floppy driver that you have two floppy controllers. | |
| 79 | + The second floppy controller is assumed to be at <address>. | |
| 80 | + This option is not needed if the second controller is at address | |
| 81 | + 0x370, and if you use the 'cmos' option. | |
| 82 | + | |
| 83 | + floppy=thinkpad | |
| 84 | + Tells the floppy driver that you have a Thinkpad. Thinkpads use an | |
| 85 | + inverted convention for the disk change line. | |
| 86 | + | |
| 87 | + floppy=0,thinkpad | |
| 88 | + Tells the floppy driver that you don't have a Thinkpad. | |
| 89 | + | |
| 90 | + floppy=omnibook / floppy=nodma | |
| 91 | + Tells the floppy driver not to use Dma for data transfers. | |
| 92 | + This is needed on HP Omnibooks, which don't have a workable | |
| 93 | + DMA channel for the floppy driver. This option is also useful | |
| 94 | + if you frequently get "Unable to allocate DMA memory" messages. | |
| 95 | + Indeed, dma memory needs to be continuous in physical memory, | |
| 96 | + and is thus harder to find, whereas non-dma buffers may be | |
| 97 | + allocated in virtual memory. However, I advise against this if | |
| 98 | + you have an FDC without a FIFO (8272A or 82072). 82072A and | |
| 99 | + later are OK. You also need at least a 486 to use nodma. | |
| 100 | + If you use nodma mode, I suggest you also set the FIFO | |
| 101 | + threshold to 10 or lower, in order to limit the number of data | |
| 102 | + transfer interrupts. | |
| 103 | + | |
| 104 | + If you have a FIFO-able FDC, the floppy driver automatically | |
| 105 | + falls back on non DMA mode if no DMA-able memory can be found. | |
| 106 | + If you want to avoid this, explicitly ask for 'yesdma'. | |
| 107 | + | |
| 108 | + floppy=yesdma | |
| 109 | + Tells the floppy driver that a workable DMA channel is available. | |
| 110 | + (default) | |
| 111 | + | |
| 112 | + floppy=nofifo | |
| 113 | + Disables the FIFO entirely. This is needed if you get "Bus | |
| 114 | + master arbitration error" messages from your Ethernet card (or | |
| 115 | + from other devices) while accessing the floppy. | |
| 116 | + | |
| 117 | + floppy=usefifo | |
| 118 | + Enables the FIFO. (default) | |
| 119 | + | |
| 120 | + floppy=<threshold>,fifo_depth | |
| 121 | + Sets the FIFO threshold. This is mostly relevant in DMA | |
| 122 | + mode. If this is higher, the floppy driver tolerates more | |
| 123 | + interrupt latency, but it triggers more interrupts (i.e. it | |
| 124 | + imposes more load on the rest of the system). If this is | |
| 125 | + lower, the interrupt latency should be lower too (faster | |
| 126 | + processor). The benefit of a lower threshold is less | |
| 127 | + interrupts. | |
| 128 | + | |
| 129 | + To tune the fifo threshold, switch on over/underrun messages | |
| 130 | + using 'floppycontrol --messages'. Then access a floppy | |
| 131 | + disk. If you get a huge amount of "Over/Underrun - retrying" | |
| 132 | + messages, then the fifo threshold is too low. Try with a | |
| 133 | + higher value, until you only get an occasional Over/Underrun. | |
| 134 | + It is a good idea to compile the floppy driver as a module | |
| 135 | + when doing this tuning. Indeed, it allows to try different | |
| 136 | + fifo values without rebooting the machine for each test. Note | |
| 137 | + that you need to do 'floppycontrol --messages' every time you | |
| 138 | + re-insert the module. | |
| 139 | + | |
| 140 | + Usually, tuning the fifo threshold should not be needed, as | |
| 141 | + the default (0xa) is reasonable. | |
| 142 | + | |
| 143 | + floppy=<drive>,<type>,cmos | |
| 144 | + Sets the CMOS type of <drive> to <type>. This is mandatory if | |
| 145 | + you have more than two floppy drives (only two can be | |
| 146 | + described in the physical CMOS), or if your BIOS uses | |
| 147 | + non-standard CMOS types. The CMOS types are: | |
| 148 | + | |
| 149 | + == ================================== | |
| 150 | + 0 Use the value of the physical CMOS | |
| 151 | + 1 5 1/4 DD | |
| 152 | + 2 5 1/4 HD | |
| 153 | + 3 3 1/2 DD | |
| 154 | + 4 3 1/2 HD | |
| 155 | + 5 3 1/2 ED | |
| 156 | + 6 3 1/2 ED | |
| 157 | + 16 unknown or not installed | |
| 158 | + == ================================== | |
| 159 | + | |
| 160 | + (Note: there are two valid types for ED drives. This is because 5 was | |
| 161 | + initially chosen to represent floppy *tapes*, and 6 for ED drives. | |
| 162 | + AMI ignored this, and used 5 for ED drives. That's why the floppy | |
| 163 | + driver handles both.) | |
| 164 | + | |
| 165 | + floppy=unexpected_interrupts | |
| 166 | + Print a warning message when an unexpected interrupt is received. | |
| 167 | + (default) | |
| 168 | + | |
| 169 | + floppy=no_unexpected_interrupts / floppy=L40SX | |
| 170 | + Don't print a message when an unexpected interrupt is received. This | |
| 171 | + is needed on IBM L40SX laptops in certain video modes. (There seems | |
| 172 | + to be an interaction between video and floppy. The unexpected | |
| 173 | + interrupts affect only performance, and can be safely ignored.) | |
| 174 | + | |
| 175 | + floppy=broken_dcl | |
| 176 | + Don't use the disk change line, but assume that the disk was | |
| 177 | + changed whenever the device node is reopened. Needed on some | |
| 178 | + boxes where the disk change line is broken or unsupported. | |
| 179 | + This should be regarded as a stopgap measure, indeed it makes | |
| 180 | + floppy operation less efficient due to unneeded cache | |
| 181 | + flushings, and slightly more unreliable. Please verify your | |
| 182 | + cable, connection and jumper settings if you have any DCL | |
| 183 | + problems. However, some older drives, and also some laptops | |
| 184 | + are known not to have a DCL. | |
| 185 | + | |
| 186 | + floppy=debug | |
| 187 | + Print debugging messages. | |
| 188 | + | |
| 189 | + floppy=messages | |
| 190 | + Print informational messages for some operations (disk change | |
| 191 | + notifications, warnings about over and underruns, and about | |
| 192 | + autodetection). | |
| 193 | + | |
| 194 | + floppy=silent_dcl_clear | |
| 195 | + Uses a less noisy way to clear the disk change line (which | |
| 196 | + doesn't involve seeks). Implied by 'daring' option. | |
| 197 | + | |
| 198 | + floppy=<nr>,irq | |
| 199 | + Sets the floppy IRQ to <nr> instead of 6. | |
| 200 | + | |
| 201 | + floppy=<nr>,dma | |
| 202 | + Sets the floppy DMA channel to <nr> instead of 2. | |
| 203 | + | |
| 204 | + floppy=slow | |
| 205 | + Use PS/2 stepping rate:: | |
| 206 | + | |
| 207 | + PS/2 floppies have much slower step rates than regular floppies. | |
| 208 | + It's been recommended that take about 1/4 of the default speed | |
| 209 | + in some more extreme cases. | |
| 210 | + | |
| 211 | + | |
| 212 | +Supporting utilities and additional documentation: | |
| 213 | +================================================== | |
| 214 | + | |
| 215 | +Additional parameters of the floppy driver can be configured at | |
| 216 | +runtime. Utilities which do this can be found in the fdutils package. | |
| 217 | +This package also contains a new version of mtools which allows to | |
| 218 | +access high capacity disks (up to 1992K on a high density 3 1/2 disk!). | |
| 219 | +It also contains additional documentation about the floppy driver. | |
| 220 | + | |
| 221 | +The latest version can be found at fdutils homepage: | |
| 222 | + | |
| 223 | + http://fdutils.linux.lu | |
| 224 | + | |
| 225 | +The fdutils releases can be found at: | |
| 226 | + | |
| 227 | + http://fdutils.linux.lu/download.html | |
| 228 | + | |
| 229 | + http://www.tux.org/pub/knaff/fdutils/ | |
| 230 | + | |
| 231 | + ftp://metalab.unc.edu/pub/Linux/utils/disk-management/ | |
| 232 | + | |
| 233 | +Reporting problems about the floppy driver | |
| 234 | +========================================== | |
| 235 | + | |
| 236 | +If you have a question or a bug report about the floppy driver, mail | |
| 237 | +me at Alain.Knaff@poboxes.com . If you post to Usenet, preferably use | |
| 238 | +comp.os.linux.hardware. As the volume in these groups is rather high, | |
| 239 | +be sure to include the word "floppy" (or "FLOPPY") in the subject | |
| 240 | +line. If the reported problem happens when mounting floppy disks, be | |
| 241 | +sure to mention also the type of the filesystem in the subject line. | |
| 242 | + | |
| 243 | +Be sure to read the FAQ before mailing/posting any bug reports! | |
| 244 | + | |
| 245 | +Alain | |
| 246 | + | |
| 247 | +Changelog | |
| 248 | +========= | |
| 249 | + | |
| 250 | +10-30-2004 : | |
| 251 | + Cleanup, updating, add reference to module configuration. | |
| 252 | + James Nelson <james4765@gmail.com> | |
| 253 | + | |
| 254 | +6-3-2000 : | |
| 255 | + Original Document | |
| @@ -0,0 +1,16 @@ | ||
| 1 | +.. SPDX-License-Identifier: GPL-2.0 | |
| 2 | + | |
| 3 | +=========================== | |
| 4 | +The Linux RapidIO Subsystem | |
| 5 | +=========================== | |
| 6 | + | |
| 7 | +.. toctree:: | |
| 8 | + :maxdepth: 1 | |
| 9 | + | |
| 10 | + floppy | |
| 11 | + nbd | |
| 12 | + paride | |
| 13 | + ramdisk | |
| 14 | + zram | |
| 15 | + | |
| 16 | + drbd/index | |
| @@ -0,0 +1,31 @@ | ||
| 1 | +================================== | |
| 2 | +Network Block Device (TCP version) | |
| 3 | +================================== | |
| 4 | + | |
| 5 | +1) Overview | |
| 6 | +----------- | |
| 7 | + | |
| 8 | +What is it: With this compiled in the kernel (or as a module), Linux | |
| 9 | +can use a remote server as one of its block devices. So every time | |
| 10 | +the client computer wants to read, e.g., /dev/nb0, it sends a | |
| 11 | +request over TCP to the server, which will reply with the data read. | |
| 12 | +This can be used for stations with low disk space (or even diskless) | |
| 13 | +to borrow disk space from another computer. | |
| 14 | +Unlike NFS, it is possible to put any filesystem on it, etc. | |
| 15 | + | |
| 16 | +For more information, or to download the nbd-client and nbd-server | |
| 17 | +tools, go to http://nbd.sf.net/. | |
| 18 | + | |
| 19 | +The nbd kernel module need only be installed on the client | |
| 20 | +system, as the nbd-server is completely in userspace. In fact, | |
| 21 | +the nbd-server has been successfully ported to other operating | |
| 22 | +systems, including Windows. | |
| 23 | + | |
| 24 | +A) NBD parameters | |
| 25 | +----------------- | |
| 26 | + | |
| 27 | +max_part | |
| 28 | + Number of partitions per device (default: 0). | |
| 29 | + | |
| 30 | +nbds_max | |
| 31 | + Number of block devices that should be initialized (default: 16). | |
| @@ -0,0 +1,439 @@ | ||
| 1 | +=================================== | |
| 2 | +Linux and parallel port IDE devices | |
| 3 | +=================================== | |
| 4 | + | |
| 5 | +PARIDE v1.03 (c) 1997-8 Grant Guenther <grant@torque.net> | |
| 6 | + | |
| 7 | +1. Introduction | |
| 8 | +=============== | |
| 9 | + | |
| 10 | +Owing to the simplicity and near universality of the parallel port interface | |
| 11 | +to personal computers, many external devices such as portable hard-disk, | |
| 12 | +CD-ROM, LS-120 and tape drives use the parallel port to connect to their | |
| 13 | +host computer. While some devices (notably scanners) use ad-hoc methods | |
| 14 | +to pass commands and data through the parallel port interface, most | |
| 15 | +external devices are actually identical to an internal model, but with | |
| 16 | +a parallel-port adapter chip added in. Some of the original parallel port | |
| 17 | +adapters were little more than mechanisms for multiplexing a SCSI bus. | |
| 18 | +(The Iomega PPA-3 adapter used in the ZIP drives is an example of this | |
| 19 | +approach). Most current designs, however, take a different approach. | |
| 20 | +The adapter chip reproduces a small ISA or IDE bus in the external device | |
| 21 | +and the communication protocol provides operations for reading and writing | |
| 22 | +device registers, as well as data block transfer functions. Sometimes, | |
| 23 | +the device being addressed via the parallel cable is a standard SCSI | |
| 24 | +controller like an NCR 5380. The "ditto" family of external tape | |
| 25 | +drives use the ISA replicator to interface a floppy disk controller, | |
| 26 | +which is then connected to a floppy-tape mechanism. The vast majority | |
| 27 | +of external parallel port devices, however, are now based on standard | |
| 28 | +IDE type devices, which require no intermediate controller. If one | |
| 29 | +were to open up a parallel port CD-ROM drive, for instance, one would | |
| 30 | +find a standard ATAPI CD-ROM drive, a power supply, and a single adapter | |
| 31 | +that interconnected a standard PC parallel port cable and a standard | |
| 32 | +IDE cable. It is usually possible to exchange the CD-ROM device with | |
| 33 | +any other device using the IDE interface. | |
| 34 | + | |
| 35 | +The document describes the support in Linux for parallel port IDE | |
| 36 | +devices. It does not cover parallel port SCSI devices, "ditto" tape | |
| 37 | +drives or scanners. Many different devices are supported by the | |
| 38 | +parallel port IDE subsystem, including: | |
| 39 | + | |
| 40 | + - MicroSolutions backpack CD-ROM | |
| 41 | + - MicroSolutions backpack PD/CD | |
| 42 | + - MicroSolutions backpack hard-drives | |
| 43 | + - MicroSolutions backpack 8000t tape drive | |
| 44 | + - SyQuest EZ-135, EZ-230 & SparQ drives | |
| 45 | + - Avatar Shark | |
| 46 | + - Imation Superdisk LS-120 | |
| 47 | + - Maxell Superdisk LS-120 | |
| 48 | + - FreeCom Power CD | |
| 49 | + - Hewlett-Packard 5GB and 8GB tape drives | |
| 50 | + - Hewlett-Packard 7100 and 7200 CD-RW drives | |
| 51 | + | |
| 52 | +as well as most of the clone and no-name products on the market. | |
| 53 | + | |
| 54 | +To support such a wide range of devices, PARIDE, the parallel port IDE | |
| 55 | +subsystem, is actually structured in three parts. There is a base | |
| 56 | +paride module which provides a registry and some common methods for | |
| 57 | +accessing the parallel ports. The second component is a set of | |
| 58 | +high-level drivers for each of the different types of supported devices: | |
| 59 | + | |
| 60 | + === ============= | |
| 61 | + pd IDE disk | |
| 62 | + pcd ATAPI CD-ROM | |
| 63 | + pf ATAPI disk | |
| 64 | + pt ATAPI tape | |
| 65 | + pg ATAPI generic | |
| 66 | + === ============= | |
| 67 | + | |
| 68 | +(Currently, the pg driver is only used with CD-R drives). | |
| 69 | + | |
| 70 | +The high-level drivers function according to the relevant standards. | |
| 71 | +The third component of PARIDE is a set of low-level protocol drivers | |
| 72 | +for each of the parallel port IDE adapter chips. Thanks to the interest | |
| 73 | +and encouragement of Linux users from many parts of the world, | |
| 74 | +support is available for almost all known adapter protocols: | |
| 75 | + | |
| 76 | + ==== ====================================== ==== | |
| 77 | + aten ATEN EH-100 (HK) | |
| 78 | + bpck Microsolutions backpack (US) | |
| 79 | + comm DataStor (old-type) "commuter" adapter (TW) | |
| 80 | + dstr DataStor EP-2000 (TW) | |
| 81 | + epat Shuttle EPAT (UK) | |
| 82 | + epia Shuttle EPIA (UK) | |
| 83 | + fit2 FIT TD-2000 (US) | |
| 84 | + fit3 FIT TD-3000 (US) | |
| 85 | + friq Freecom IQ cable (DE) | |
| 86 | + frpw Freecom Power (DE) | |
| 87 | + kbic KingByte KBIC-951A and KBIC-971A (TW) | |
| 88 | + ktti KT Technology PHd adapter (SG) | |
| 89 | + on20 OnSpec 90c20 (US) | |
| 90 | + on26 OnSpec 90c26 (US) | |
| 91 | + ==== ====================================== ==== | |
| 92 | + | |
| 93 | + | |
| 94 | +2. Using the PARIDE subsystem | |
| 95 | +============================= | |
| 96 | + | |
| 97 | +While configuring the Linux kernel, you may choose either to build | |
| 98 | +the PARIDE drivers into your kernel, or to build them as modules. | |
| 99 | + | |
| 100 | +In either case, you will need to select "Parallel port IDE device support" | |
| 101 | +as well as at least one of the high-level drivers and at least one | |
| 102 | +of the parallel port communication protocols. If you do not know | |
| 103 | +what kind of parallel port adapter is used in your drive, you could | |
| 104 | +begin by checking the file names and any text files on your DOS | |
| 105 | +installation floppy. Alternatively, you can look at the markings on | |
| 106 | +the adapter chip itself. That's usually sufficient to identify the | |
| 107 | +correct device. | |
| 108 | + | |
| 109 | +You can actually select all the protocol modules, and allow the PARIDE | |
| 110 | +subsystem to try them all for you. | |
| 111 | + | |
| 112 | +For the "brand-name" products listed above, here are the protocol | |
| 113 | +and high-level drivers that you would use: | |
| 114 | + | |
| 115 | + ================ ============ ====== ======== | |
| 116 | + Manufacturer Model Driver Protocol | |
| 117 | + ================ ============ ====== ======== | |
| 118 | + MicroSolutions CD-ROM pcd bpck | |
| 119 | + MicroSolutions PD drive pf bpck | |
| 120 | + MicroSolutions hard-drive pd bpck | |
| 121 | + MicroSolutions 8000t tape pt bpck | |
| 122 | + SyQuest EZ, SparQ pd epat | |
| 123 | + Imation Superdisk pf epat | |
| 124 | + Maxell Superdisk pf friq | |
| 125 | + Avatar Shark pd epat | |
| 126 | + FreeCom CD-ROM pcd frpw | |
| 127 | + Hewlett-Packard 5GB Tape pt epat | |
| 128 | + Hewlett-Packard 7200e (CD) pcd epat | |
| 129 | + Hewlett-Packard 7200e (CD-R) pg epat | |
| 130 | + ================ ============ ====== ======== | |
| 131 | + | |
| 132 | +2.1 Configuring built-in drivers | |
| 133 | +--------------------------------- | |
| 134 | + | |
| 135 | +We recommend that you get to know how the drivers work and how to | |
| 136 | +configure them as loadable modules, before attempting to compile a | |
| 137 | +kernel with the drivers built-in. | |
| 138 | + | |
| 139 | +If you built all of your PARIDE support directly into your kernel, | |
| 140 | +and you have just a single parallel port IDE device, your kernel should | |
| 141 | +locate it automatically for you. If you have more than one device, | |
| 142 | +you may need to give some command line options to your bootloader | |
| 143 | +(eg: LILO), how to do that is beyond the scope of this document. | |
| 144 | + | |
| 145 | +The high-level drivers accept a number of command line parameters, all | |
| 146 | +of which are documented in the source files in linux/drivers/block/paride. | |
| 147 | +By default, each driver will automatically try all parallel ports it | |
| 148 | +can find, and all protocol types that have been installed, until it finds | |
| 149 | +a parallel port IDE adapter. Once it finds one, the probe stops. So, | |
| 150 | +if you have more than one device, you will need to tell the drivers | |
| 151 | +how to identify them. This requires specifying the port address, the | |
| 152 | +protocol identification number and, for some devices, the drive's | |
| 153 | +chain ID. While your system is booting, a number of messages are | |
| 154 | +displayed on the console. Like all such messages, they can be | |
| 155 | +reviewed with the 'dmesg' command. Among those messages will be | |
| 156 | +some lines like:: | |
| 157 | + | |
| 158 | + paride: bpck registered as protocol 0 | |
| 159 | + paride: epat registered as protocol 1 | |
| 160 | + | |
| 161 | +The numbers will always be the same until you build a new kernel with | |
| 162 | +different protocol selections. You should note these numbers as you | |
| 163 | +will need them to identify the devices. | |
| 164 | + | |
| 165 | +If you happen to be using a MicroSolutions backpack device, you will | |
| 166 | +also need to know the unit ID number for each drive. This is usually | |
| 167 | +the last two digits of the drive's serial number (but read MicroSolutions' | |
| 168 | +documentation about this). | |
| 169 | + | |
| 170 | +As an example, let's assume that you have a MicroSolutions PD/CD drive | |
| 171 | +with unit ID number 36 connected to the parallel port at 0x378, a SyQuest | |
| 172 | +EZ-135 connected to the chained port on the PD/CD drive and also an | |
| 173 | +Imation Superdisk connected to port 0x278. You could give the following | |
| 174 | +options on your boot command:: | |
| 175 | + | |
| 176 | + pd.drive0=0x378,1 pf.drive0=0x278,1 pf.drive1=0x378,0,36 | |
| 177 | + | |
| 178 | +In the last option, pf.drive1 configures device /dev/pf1, the 0x378 | |
| 179 | +is the parallel port base address, the 0 is the protocol registration | |
| 180 | +number and 36 is the chain ID. | |
| 181 | + | |
| 182 | +Please note: while PARIDE will work both with and without the | |
| 183 | +PARPORT parallel port sharing system that is included by the | |
| 184 | +"Parallel port support" option, PARPORT must be included and enabled | |
| 185 | +if you want to use chains of devices on the same parallel port. | |
| 186 | + | |
| 187 | +2.2 Loading and configuring PARIDE as modules | |
| 188 | +---------------------------------------------- | |
| 189 | + | |
| 190 | +It is much faster and simpler to get to understand the PARIDE drivers | |
| 191 | +if you use them as loadable kernel modules. | |
| 192 | + | |
| 193 | +Note 1: | |
| 194 | + using these drivers with the "kerneld" automatic module loading | |
| 195 | + system is not recommended for beginners, and is not documented here. | |
| 196 | + | |
| 197 | +Note 2: | |
| 198 | + if you build PARPORT support as a loadable module, PARIDE must | |
| 199 | + also be built as loadable modules, and PARPORT must be loaded before | |
| 200 | + the PARIDE modules. | |
| 201 | + | |
| 202 | +To use PARIDE, you must begin by:: | |
| 203 | + | |
| 204 | + insmod paride | |
| 205 | + | |
| 206 | +this loads a base module which provides a registry for the protocols, | |
| 207 | +among other tasks. | |
| 208 | + | |
| 209 | +Then, load as many of the protocol modules as you think you might need. | |
| 210 | +As you load each module, it will register the protocols that it supports, | |
| 211 | +and print a log message to your kernel log file and your console. For | |
| 212 | +example:: | |
| 213 | + | |
| 214 | + # insmod epat | |
| 215 | + paride: epat registered as protocol 0 | |
| 216 | + # insmod kbic | |
| 217 | + paride: k951 registered as protocol 1 | |
| 218 | + paride: k971 registered as protocol 2 | |
| 219 | + | |
| 220 | +Finally, you can load high-level drivers for each kind of device that | |
| 221 | +you have connected. By default, each driver will autoprobe for a single | |
| 222 | +device, but you can support up to four similar devices by giving their | |
| 223 | +individual co-ordinates when you load the driver. | |
| 224 | + | |
| 225 | +For example, if you had two no-name CD-ROM drives both using the | |
| 226 | +KingByte KBIC-951A adapter, one on port 0x378 and the other on 0x3bc | |
| 227 | +you could give the following command:: | |
| 228 | + | |
| 229 | + # insmod pcd drive0=0x378,1 drive1=0x3bc,1 | |
| 230 | + | |
| 231 | +For most adapters, giving a port address and protocol number is sufficient, | |
| 232 | +but check the source files in linux/drivers/block/paride for more | |
| 233 | +information. (Hopefully someone will write some man pages one day !). | |
| 234 | + | |
| 235 | +As another example, here's what happens when PARPORT is installed, and | |
| 236 | +a SyQuest EZ-135 is attached to port 0x378:: | |
| 237 | + | |
| 238 | + # insmod paride | |
| 239 | + paride: version 1.0 installed | |
| 240 | + # insmod epat | |
| 241 | + paride: epat registered as protocol 0 | |
| 242 | + # insmod pd | |
| 243 | + pd: pd version 1.0, major 45, cluster 64, nice 0 | |
| 244 | + pda: Sharing parport1 at 0x378 | |
| 245 | + pda: epat 1.0, Shuttle EPAT chip c3 at 0x378, mode 5 (EPP-32), delay 1 | |
| 246 | + pda: SyQuest EZ135A, 262144 blocks [128M], (512/16/32), removable media | |
| 247 | + pda: pda1 | |
| 248 | + | |
| 249 | +Note that the last line is the output from the generic partition table | |
| 250 | +scanner - in this case it reports that it has found a disk with one partition. | |
| 251 | + | |
| 252 | +2.3 Using a PARIDE device | |
| 253 | +-------------------------- | |
| 254 | + | |
| 255 | +Once the drivers have been loaded, you can access PARIDE devices in the | |
| 256 | +same way as their traditional counterparts. You will probably need to | |
| 257 | +create the device "special files". Here is a simple script that you can | |
| 258 | +cut to a file and execute:: | |
| 259 | + | |
| 260 | + #!/bin/bash | |
| 261 | + # | |
| 262 | + # mkd -- a script to create the device special files for the PARIDE subsystem | |
| 263 | + # | |
| 264 | + function mkdev { | |
| 265 | + mknod $1 $2 $3 $4 ; chmod 0660 $1 ; chown root:disk $1 | |
| 266 | + } | |
| 267 | + # | |
| 268 | + function pd { | |
| 269 | + D=$( printf \\$( printf "x%03x" $[ $1 + 97 ] ) ) | |
| 270 | + mkdev pd$D b 45 $[ $1 * 16 ] | |
| 271 | + for P in 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 | |
| 272 | + do mkdev pd$D$P b 45 $[ $1 * 16 + $P ] | |
| 273 | + done | |
| 274 | + } | |
| 275 | + # | |
| 276 | + cd /dev | |
| 277 | + # | |
| 278 | + for u in 0 1 2 3 ; do pd $u ; done | |
| 279 | + for u in 0 1 2 3 ; do mkdev pcd$u b 46 $u ; done | |
| 280 | + for u in 0 1 2 3 ; do mkdev pf$u b 47 $u ; done | |
| 281 | + for u in 0 1 2 3 ; do mkdev pt$u c 96 $u ; done | |
| 282 | + for u in 0 1 2 3 ; do mkdev npt$u c 96 $[ $u + 128 ] ; done | |
| 283 | + for u in 0 1 2 3 ; do mkdev pg$u c 97 $u ; done | |
| 284 | + # | |
| 285 | + # end of mkd | |
| 286 | + | |
| 287 | +With the device files and drivers in place, you can access PARIDE devices | |
| 288 | +like any other Linux device. For example, to mount a CD-ROM in pcd0, use:: | |
| 289 | + | |
| 290 | + mount /dev/pcd0 /cdrom | |
| 291 | + | |
| 292 | +If you have a fresh Avatar Shark cartridge, and the drive is pda, you | |
| 293 | +might do something like:: | |
| 294 | + | |
| 295 | + fdisk /dev/pda -- make a new partition table with | |
| 296 | + partition 1 of type 83 | |
| 297 | + | |
| 298 | + mke2fs /dev/pda1 -- to build the file system | |
| 299 | + | |
| 300 | + mkdir /shark -- make a place to mount the disk | |
| 301 | + | |
| 302 | + mount /dev/pda1 /shark | |
| 303 | + | |
| 304 | +Devices like the Imation superdisk work in the same way, except that | |
| 305 | +they do not have a partition table. For example to make a 120MB | |
| 306 | +floppy that you could share with a DOS system:: | |
| 307 | + | |
| 308 | + mkdosfs /dev/pf0 | |
| 309 | + mount /dev/pf0 /mnt | |
| 310 | + | |
| 311 | + | |
| 312 | +2.4 The pf driver | |
| 313 | +------------------ | |
| 314 | + | |
| 315 | +The pf driver is intended for use with parallel port ATAPI disk | |
| 316 | +devices. The most common devices in this category are PD drives | |
| 317 | +and LS-120 drives. Traditionally, media for these devices are not | |
| 318 | +partitioned. Consequently, the pf driver does not support partitioned | |
| 319 | +media. This may be changed in a future version of the driver. | |
| 320 | + | |
| 321 | +2.5 Using the pt driver | |
| 322 | +------------------------ | |
| 323 | + | |
| 324 | +The pt driver for parallel port ATAPI tape drives is a minimal driver. | |
| 325 | +It does not yet support many of the standard tape ioctl operations. | |
| 326 | +For best performance, a block size of 32KB should be used. You will | |
| 327 | +probably want to set the parallel port delay to 0, if you can. | |
| 328 | + | |
| 329 | +2.6 Using the pg driver | |
| 330 | +------------------------ | |
| 331 | + | |
| 332 | +The pg driver can be used in conjunction with the cdrecord program | |
| 333 | +to create CD-ROMs. Please get cdrecord version 1.6.1 or later | |
| 334 | +from ftp://ftp.fokus.gmd.de/pub/unix/cdrecord/ . To record CD-R media | |
| 335 | +your parallel port should ideally be set to EPP mode, and the "port delay" | |
| 336 | +should be set to 0. With those settings it is possible to record at 2x | |
| 337 | +speed without any buffer underruns. If you cannot get the driver to work | |
| 338 | +in EPP mode, try to use "bidirectional" or "PS/2" mode and 1x speeds only. | |
| 339 | + | |
| 340 | + | |
| 341 | +3. Troubleshooting | |
| 342 | +================== | |
| 343 | + | |
| 344 | +3.1 Use EPP mode if you can | |
| 345 | +---------------------------- | |
| 346 | + | |
| 347 | +The most common problems that people report with the PARIDE drivers | |
| 348 | +concern the parallel port CMOS settings. At this time, none of the | |
| 349 | +PARIDE protocol modules support ECP mode, or any ECP combination modes. | |
| 350 | +If you are able to do so, please set your parallel port into EPP mode | |
| 351 | +using your CMOS setup procedure. | |
| 352 | + | |
| 353 | +3.2 Check the port delay | |
| 354 | +------------------------- | |
| 355 | + | |
| 356 | +Some parallel ports cannot reliably transfer data at full speed. To | |
| 357 | +offset the errors, the PARIDE protocol modules introduce a "port | |
| 358 | +delay" between each access to the i/o ports. Each protocol sets | |
| 359 | +a default value for this delay. In most cases, the user can override | |
| 360 | +the default and set it to 0 - resulting in somewhat higher transfer | |
| 361 | +rates. In some rare cases (especially with older 486 systems) the | |
| 362 | +default delays are not long enough. if you experience corrupt data | |
| 363 | +transfers, or unexpected failures, you may wish to increase the | |
| 364 | +port delay. The delay can be programmed using the "driveN" parameters | |
| 365 | +to each of the high-level drivers. Please see the notes above, or | |
| 366 | +read the comments at the beginning of the driver source files in | |
| 367 | +linux/drivers/block/paride. | |
| 368 | + | |
| 369 | +3.3 Some drives need a printer reset | |
| 370 | +------------------------------------- | |
| 371 | + | |
| 372 | +There appear to be a number of "noname" external drives on the market | |
| 373 | +that do not always power up correctly. We have noticed this with some | |
| 374 | +drives based on OnSpec and older Freecom adapters. In these rare cases, | |
| 375 | +the adapter can often be reinitialised by issuing a "printer reset" on | |
| 376 | +the parallel port. As the reset operation is potentially disruptive in | |
| 377 | +multiple device environments, the PARIDE drivers will not do it | |
| 378 | +automatically. You can however, force a printer reset by doing:: | |
| 379 | + | |
| 380 | + insmod lp reset=1 | |
| 381 | + rmmod lp | |
| 382 | + | |
| 383 | +If you have one of these marginal cases, you should probably build | |
| 384 | +your paride drivers as modules, and arrange to do the printer reset | |
| 385 | +before loading the PARIDE drivers. | |
| 386 | + | |
| 387 | +3.4 Use the verbose option and dmesg if you need help | |
| 388 | +------------------------------------------------------ | |
| 389 | + | |
| 390 | +While a lot of testing has gone into these drivers to make them work | |
| 391 | +as smoothly as possible, problems will arise. If you do have problems, | |
| 392 | +please check all the obvious things first: does the drive work in | |
| 393 | +DOS with the manufacturer's drivers ? If that doesn't yield any useful | |
| 394 | +clues, then please make sure that only one drive is hooked to your system, | |
| 395 | +and that either (a) PARPORT is enabled or (b) no other device driver | |
| 396 | +is using your parallel port (check in /proc/ioports). Then, load the | |
| 397 | +appropriate drivers (you can load several protocol modules if you want) | |
| 398 | +as in:: | |
| 399 | + | |
| 400 | + # insmod paride | |
| 401 | + # insmod epat | |
| 402 | + # insmod bpck | |
| 403 | + # insmod kbic | |
| 404 | + ... | |
| 405 | + # insmod pd verbose=1 | |
| 406 | + | |
| 407 | +(using the correct driver for the type of device you have, of course). | |
| 408 | +The verbose=1 parameter will cause the drivers to log a trace of their | |
| 409 | +activity as they attempt to locate your drive. | |
| 410 | + | |
| 411 | +Use 'dmesg' to capture a log of all the PARIDE messages (any messages | |
| 412 | +beginning with paride:, a protocol module's name or a driver's name) and | |
| 413 | +include that with your bug report. You can submit a bug report in one | |
| 414 | +of two ways. Either send it directly to the author of the PARIDE suite, | |
| 415 | +by e-mail to grant@torque.net, or join the linux-parport mailing list | |
| 416 | +and post your report there. | |
| 417 | + | |
| 418 | +3.5 For more information or help | |
| 419 | +--------------------------------- | |
| 420 | + | |
| 421 | +You can join the linux-parport mailing list by sending a mail message | |
| 422 | +to: | |
| 423 | + | |
| 424 | + linux-parport-request@torque.net | |
| 425 | + | |
| 426 | +with the single word:: | |
| 427 | + | |
| 428 | + subscribe | |
| 429 | + | |
| 430 | +in the body of the mail message (not in the subject line). Please be | |
| 431 | +sure that your mail program is correctly set up when you do this, as | |
| 432 | +the list manager is a robot that will subscribe you using the reply | |
| 433 | +address in your mail headers. REMOVE any anti-spam gimmicks you may | |
| 434 | +have in your mail headers, when sending mail to the list server. | |
| 435 | + | |
| 436 | +You might also find some useful information on the linux-parport | |
| 437 | +web pages (although they are not always up to date) at | |
| 438 | + | |
| 439 | + http://web.archive.org/web/%2E/http://www.torque.net/parport/ | |
| @@ -0,0 +1,177 @@ | ||
| 1 | +========================================== | |
| 2 | +Using the RAM disk block device with Linux | |
| 3 | +========================================== | |
| 4 | + | |
| 5 | +.. Contents: | |
| 6 | + | |
| 7 | + 1) Overview | |
| 8 | + 2) Kernel Command Line Parameters | |
| 9 | + 3) Using "rdev -r" | |
| 10 | + 4) An Example of Creating a Compressed RAM Disk | |
| 11 | + | |
| 12 | + | |
| 13 | +1) Overview | |
| 14 | +----------- | |
| 15 | + | |
| 16 | +The RAM disk driver is a way to use main system memory as a block device. It | |
| 17 | +is required for initrd, an initial filesystem used if you need to load modules | |
| 18 | +in order to access the root filesystem (see Documentation/admin-guide/initrd.rst). It can | |
| 19 | +also be used for a temporary filesystem for crypto work, since the contents | |
| 20 | +are erased on reboot. | |
| 21 | + | |
| 22 | +The RAM disk dynamically grows as more space is required. It does this by using | |
| 23 | +RAM from the buffer cache. The driver marks the buffers it is using as dirty | |
| 24 | +so that the VM subsystem does not try to reclaim them later. | |
| 25 | + | |
| 26 | +The RAM disk supports up to 16 RAM disks by default, and can be reconfigured | |
| 27 | +to support an unlimited number of RAM disks (at your own risk). Just change | |
| 28 | +the configuration symbol BLK_DEV_RAM_COUNT in the Block drivers config menu | |
| 29 | +and (re)build the kernel. | |
| 30 | + | |
| 31 | +To use RAM disk support with your system, run './MAKEDEV ram' from the /dev | |
| 32 | +directory. RAM disks are all major number 1, and start with minor number 0 | |
| 33 | +for /dev/ram0, etc. If used, modern kernels use /dev/ram0 for an initrd. | |
| 34 | + | |
| 35 | +The new RAM disk also has the ability to load compressed RAM disk images, | |
| 36 | +allowing one to squeeze more programs onto an average installation or | |
| 37 | +rescue floppy disk. | |
| 38 | + | |
| 39 | + | |
| 40 | +2) Parameters | |
| 41 | +--------------------------------- | |
| 42 | + | |
| 43 | +2a) Kernel Command Line Parameters | |
| 44 | + | |
| 45 | + ramdisk_size=N | |
| 46 | + Size of the ramdisk. | |
| 47 | + | |
| 48 | +This parameter tells the RAM disk driver to set up RAM disks of N k size. The | |
| 49 | +default is 4096 (4 MB). | |
| 50 | + | |
| 51 | +2b) Module parameters | |
| 52 | + | |
| 53 | + rd_nr | |
| 54 | + /dev/ramX devices created. | |
| 55 | + | |
| 56 | + max_part | |
| 57 | + Maximum partition number. | |
| 58 | + | |
| 59 | + rd_size | |
| 60 | + See ramdisk_size. | |
| 61 | + | |
| 62 | +3) Using "rdev -r" | |
| 63 | +------------------ | |
| 64 | + | |
| 65 | +The usage of the word (two bytes) that "rdev -r" sets in the kernel image is | |
| 66 | +as follows. The low 11 bits (0 -> 10) specify an offset (in 1 k blocks) of up | |
| 67 | +to 2 MB (2^11) of where to find the RAM disk (this used to be the size). Bit | |
| 68 | +14 indicates that a RAM disk is to be loaded, and bit 15 indicates whether a | |
| 69 | +prompt/wait sequence is to be given before trying to read the RAM disk. Since | |
| 70 | +the RAM disk dynamically grows as data is being written into it, a size field | |
| 71 | +is not required. Bits 11 to 13 are not currently used and may as well be zero. | |
| 72 | +These numbers are no magical secrets, as seen below:: | |
| 73 | + | |
| 74 | + ./arch/x86/kernel/setup.c:#define RAMDISK_IMAGE_START_MASK 0x07FF | |
| 75 | + ./arch/x86/kernel/setup.c:#define RAMDISK_PROMPT_FLAG 0x8000 | |
| 76 | + ./arch/x86/kernel/setup.c:#define RAMDISK_LOAD_FLAG 0x4000 | |
| 77 | + | |
| 78 | +Consider a typical two floppy disk setup, where you will have the | |
| 79 | +kernel on disk one, and have already put a RAM disk image onto disk #2. | |
| 80 | + | |
| 81 | +Hence you want to set bits 0 to 13 as 0, meaning that your RAM disk | |
| 82 | +starts at an offset of 0 kB from the beginning of the floppy. | |
| 83 | +The command line equivalent is: "ramdisk_start=0" | |
| 84 | + | |
| 85 | +You want bit 14 as one, indicating that a RAM disk is to be loaded. | |
| 86 | +The command line equivalent is: "load_ramdisk=1" | |
| 87 | + | |
| 88 | +You want bit 15 as one, indicating that you want a prompt/keypress | |
| 89 | +sequence so that you have a chance to switch floppy disks. | |
| 90 | +The command line equivalent is: "prompt_ramdisk=1" | |
| 91 | + | |
| 92 | +Putting that together gives 2^15 + 2^14 + 0 = 49152 for an rdev word. | |
| 93 | +So to create disk one of the set, you would do:: | |
| 94 | + | |
| 95 | + /usr/src/linux# cat arch/x86/boot/zImage > /dev/fd0 | |
| 96 | + /usr/src/linux# rdev /dev/fd0 /dev/fd0 | |
| 97 | + /usr/src/linux# rdev -r /dev/fd0 49152 | |
| 98 | + | |
| 99 | +If you make a boot disk that has LILO, then for the above, you would use:: | |
| 100 | + | |
| 101 | + append = "ramdisk_start=0 load_ramdisk=1 prompt_ramdisk=1" | |
| 102 | + | |
| 103 | +Since the default start = 0 and the default prompt = 1, you could use:: | |
| 104 | + | |
| 105 | + append = "load_ramdisk=1" | |
| 106 | + | |
| 107 | + | |
| 108 | +4) An Example of Creating a Compressed RAM Disk | |
| 109 | +----------------------------------------------- | |
| 110 | + | |
| 111 | +To create a RAM disk image, you will need a spare block device to | |
| 112 | +construct it on. This can be the RAM disk device itself, or an | |
| 113 | +unused disk partition (such as an unmounted swap partition). For this | |
| 114 | +example, we will use the RAM disk device, "/dev/ram0". | |
| 115 | + | |
| 116 | +Note: This technique should not be done on a machine with less than 8 MB | |
| 117 | +of RAM. If using a spare disk partition instead of /dev/ram0, then this | |
| 118 | +restriction does not apply. | |
| 119 | + | |
| 120 | +a) Decide on the RAM disk size that you want. Say 2 MB for this example. | |
| 121 | + Create it by writing to the RAM disk device. (This step is not currently | |
| 122 | + required, but may be in the future.) It is wise to zero out the | |
| 123 | + area (esp. for disks) so that maximal compression is achieved for | |
| 124 | + the unused blocks of the image that you are about to create:: | |
| 125 | + | |
| 126 | + dd if=/dev/zero of=/dev/ram0 bs=1k count=2048 | |
| 127 | + | |
| 128 | +b) Make a filesystem on it. Say ext2fs for this example:: | |
| 129 | + | |
| 130 | + mke2fs -vm0 /dev/ram0 2048 | |
| 131 | + | |
| 132 | +c) Mount it, copy the files you want to it (eg: /etc/* /dev/* ...) | |
| 133 | + and unmount it again. | |
| 134 | + | |
| 135 | +d) Compress the contents of the RAM disk. The level of compression | |
| 136 | + will be approximately 50% of the space used by the files. Unused | |
| 137 | + space on the RAM disk will compress to almost nothing:: | |
| 138 | + | |
| 139 | + dd if=/dev/ram0 bs=1k count=2048 | gzip -v9 > /tmp/ram_image.gz | |
| 140 | + | |
| 141 | +e) Put the kernel onto the floppy:: | |
| 142 | + | |
| 143 | + dd if=zImage of=/dev/fd0 bs=1k | |
| 144 | + | |
| 145 | +f) Put the RAM disk image onto the floppy, after the kernel. Use an offset | |
| 146 | + that is slightly larger than the kernel, so that you can put another | |
| 147 | + (possibly larger) kernel onto the same floppy later without overlapping | |
| 148 | + the RAM disk image. An offset of 400 kB for kernels about 350 kB in | |
| 149 | + size would be reasonable. Make sure offset+size of ram_image.gz is | |
| 150 | + not larger than the total space on your floppy (usually 1440 kB):: | |
| 151 | + | |
| 152 | + dd if=/tmp/ram_image.gz of=/dev/fd0 bs=1k seek=400 | |
| 153 | + | |
| 154 | +g) Use "rdev" to set the boot device, RAM disk offset, prompt flag, etc. | |
| 155 | + For prompt_ramdisk=1, load_ramdisk=1, ramdisk_start=400, one would | |
| 156 | + have 2^15 + 2^14 + 400 = 49552:: | |
| 157 | + | |
| 158 | + rdev /dev/fd0 /dev/fd0 | |
| 159 | + rdev -r /dev/fd0 49552 | |
| 160 | + | |
| 161 | +That is it. You now have your boot/root compressed RAM disk floppy. Some | |
| 162 | +users may wish to combine steps (d) and (f) by using a pipe. | |
| 163 | + | |
| 164 | + | |
| 165 | + Paul Gortmaker 12/95 | |
| 166 | + | |
| 167 | +Changelog: | |
| 168 | +---------- | |
| 169 | + | |
| 170 | +10-22-04 : | |
| 171 | + Updated to reflect changes in command line options, remove | |
| 172 | + obsolete references, general cleanup. | |
| 173 | + James Nelson (james4765@gmail.com) | |
| 174 | + | |
| 175 | + | |
| 176 | +12-95 : | |
| 177 | + Original Document | |
| @@ -0,0 +1,422 @@ | ||
| 1 | +======================================== | |
| 2 | +zram: Compressed RAM based block devices | |
| 3 | +======================================== | |
| 4 | + | |
| 5 | +Introduction | |
| 6 | +============ | |
| 7 | + | |
| 8 | +The zram module creates RAM based block devices named /dev/zram<id> | |
| 9 | +(<id> = 0, 1, ...). Pages written to these disks are compressed and stored | |
| 10 | +in memory itself. These disks allow very fast I/O and compression provides | |
| 11 | +good amounts of memory savings. Some of the usecases include /tmp storage, | |
| 12 | +use as swap disks, various caches under /var and maybe many more :) | |
| 13 | + | |
| 14 | +Statistics for individual zram devices are exported through sysfs nodes at | |
| 15 | +/sys/block/zram<id>/ | |
| 16 | + | |
| 17 | +Usage | |
| 18 | +===== | |
| 19 | + | |
| 20 | +There are several ways to configure and manage zram device(-s): | |
| 21 | + | |
| 22 | +a) using zram and zram_control sysfs attributes | |
| 23 | +b) using zramctl utility, provided by util-linux (util-linux@vger.kernel.org). | |
| 24 | + | |
| 25 | +In this document we will describe only 'manual' zram configuration steps, | |
| 26 | +IOW, zram and zram_control sysfs attributes. | |
| 27 | + | |
| 28 | +In order to get a better idea about zramctl please consult util-linux | |
| 29 | +documentation, zramctl man-page or `zramctl --help`. Please be informed | |
| 30 | +that zram maintainers do not develop/maintain util-linux or zramctl, should | |
| 31 | +you have any questions please contact util-linux@vger.kernel.org | |
| 32 | + | |
| 33 | +Following shows a typical sequence of steps for using zram. | |
| 34 | + | |
| 35 | +WARNING | |
| 36 | +======= | |
| 37 | + | |
| 38 | +For the sake of simplicity we skip error checking parts in most of the | |
| 39 | +examples below. However, it is your sole responsibility to handle errors. | |
| 40 | + | |
| 41 | +zram sysfs attributes always return negative values in case of errors. | |
| 42 | +The list of possible return codes: | |
| 43 | + | |
| 44 | +======== ============================================================= | |
| 45 | +-EBUSY an attempt to modify an attribute that cannot be changed once | |
| 46 | + the device has been initialised. Please reset device first; | |
| 47 | +-ENOMEM zram was not able to allocate enough memory to fulfil your | |
| 48 | + needs; | |
| 49 | +-EINVAL invalid input has been provided. | |
| 50 | +======== ============================================================= | |
| 51 | + | |
| 52 | +If you use 'echo', the returned value that is changed by 'echo' utility, | |
| 53 | +and, in general case, something like:: | |
| 54 | + | |
| 55 | + echo 3 > /sys/block/zram0/max_comp_streams | |
| 56 | + if [ $? -ne 0 ]; | |
| 57 | + handle_error | |
| 58 | + fi | |
| 59 | + | |
| 60 | +should suffice. | |
| 61 | + | |
| 62 | +1) Load Module | |
| 63 | +============== | |
| 64 | + | |
| 65 | +:: | |
| 66 | + | |
| 67 | + modprobe zram num_devices=4 | |
| 68 | + This creates 4 devices: /dev/zram{0,1,2,3} | |
| 69 | + | |
| 70 | +num_devices parameter is optional and tells zram how many devices should be | |
| 71 | +pre-created. Default: 1. | |
| 72 | + | |
| 73 | +2) Set max number of compression streams | |
| 74 | +======================================== | |
| 75 | + | |
| 76 | +Regardless the value passed to this attribute, ZRAM will always | |
| 77 | +allocate multiple compression streams - one per online CPUs - thus | |
| 78 | +allowing several concurrent compression operations. The number of | |
| 79 | +allocated compression streams goes down when some of the CPUs | |
| 80 | +become offline. There is no single-compression-stream mode anymore, | |
| 81 | +unless you are running a UP system or has only 1 CPU online. | |
| 82 | + | |
| 83 | +To find out how many streams are currently available:: | |
| 84 | + | |
| 85 | + cat /sys/block/zram0/max_comp_streams | |
| 86 | + | |
| 87 | +3) Select compression algorithm | |
| 88 | +=============================== | |
| 89 | + | |
| 90 | +Using comp_algorithm device attribute one can see available and | |
| 91 | +currently selected (shown in square brackets) compression algorithms, | |
| 92 | +change selected compression algorithm (once the device is initialised | |
| 93 | +there is no way to change compression algorithm). | |
| 94 | + | |
| 95 | +Examples:: | |
| 96 | + | |
| 97 | + #show supported compression algorithms | |
| 98 | + cat /sys/block/zram0/comp_algorithm | |
| 99 | + lzo [lz4] | |
| 100 | + | |
| 101 | + #select lzo compression algorithm | |
| 102 | + echo lzo > /sys/block/zram0/comp_algorithm | |
| 103 | + | |
| 104 | +For the time being, the `comp_algorithm` content does not necessarily | |
| 105 | +show every compression algorithm supported by the kernel. We keep this | |
| 106 | +list primarily to simplify device configuration and one can configure | |
| 107 | +a new device with a compression algorithm that is not listed in | |
| 108 | +`comp_algorithm`. The thing is that, internally, ZRAM uses Crypto API | |
| 109 | +and, if some of the algorithms were built as modules, it's impossible | |
| 110 | +to list all of them using, for instance, /proc/crypto or any other | |
| 111 | +method. This, however, has an advantage of permitting the usage of | |
| 112 | +custom crypto compression modules (implementing S/W or H/W compression). | |
| 113 | + | |
| 114 | +4) Set Disksize | |
| 115 | +=============== | |
| 116 | + | |
| 117 | +Set disk size by writing the value to sysfs node 'disksize'. | |
| 118 | +The value can be either in bytes or you can use mem suffixes. | |
| 119 | +Examples:: | |
| 120 | + | |
| 121 | + # Initialize /dev/zram0 with 50MB disksize | |
| 122 | + echo $((50*1024*1024)) > /sys/block/zram0/disksize | |
| 123 | + | |
| 124 | + # Using mem suffixes | |
| 125 | + echo 256K > /sys/block/zram0/disksize | |
| 126 | + echo 512M > /sys/block/zram0/disksize | |
| 127 | + echo 1G > /sys/block/zram0/disksize | |
| 128 | + | |
| 129 | +Note: | |
| 130 | +There is little point creating a zram of greater than twice the size of memory | |
| 131 | +since we expect a 2:1 compression ratio. Note that zram uses about 0.1% of the | |
| 132 | +size of the disk when not in use so a huge zram is wasteful. | |
| 133 | + | |
| 134 | +5) Set memory limit: Optional | |
| 135 | +============================= | |
| 136 | + | |
| 137 | +Set memory limit by writing the value to sysfs node 'mem_limit'. | |
| 138 | +The value can be either in bytes or you can use mem suffixes. | |
| 139 | +In addition, you could change the value in runtime. | |
| 140 | +Examples:: | |
| 141 | + | |
| 142 | + # limit /dev/zram0 with 50MB memory | |
| 143 | + echo $((50*1024*1024)) > /sys/block/zram0/mem_limit | |
| 144 | + | |
| 145 | + # Using mem suffixes | |
| 146 | + echo 256K > /sys/block/zram0/mem_limit | |
| 147 | + echo 512M > /sys/block/zram0/mem_limit | |
| 148 | + echo 1G > /sys/block/zram0/mem_limit | |
| 149 | + | |
| 150 | + # To disable memory limit | |
| 151 | + echo 0 > /sys/block/zram0/mem_limit | |
| 152 | + | |
| 153 | +6) Activate | |
| 154 | +=========== | |
| 155 | + | |
| 156 | +:: | |
| 157 | + | |
| 158 | + mkswap /dev/zram0 | |
| 159 | + swapon /dev/zram0 | |
| 160 | + | |
| 161 | + mkfs.ext4 /dev/zram1 | |
| 162 | + mount /dev/zram1 /tmp | |
| 163 | + | |
| 164 | +7) Add/remove zram devices | |
| 165 | +========================== | |
| 166 | + | |
| 167 | +zram provides a control interface, which enables dynamic (on-demand) device | |
| 168 | +addition and removal. | |
| 169 | + | |
| 170 | +In order to add a new /dev/zramX device, perform read operation on hot_add | |
| 171 | +attribute. This will return either new device's device id (meaning that you | |
| 172 | +can use /dev/zram<id>) or error code. | |
| 173 | + | |
| 174 | +Example:: | |
| 175 | + | |
| 176 | + cat /sys/class/zram-control/hot_add | |
| 177 | + 1 | |
| 178 | + | |
| 179 | +To remove the existing /dev/zramX device (where X is a device id) | |
| 180 | +execute:: | |
| 181 | + | |
| 182 | + echo X > /sys/class/zram-control/hot_remove | |
| 183 | + | |
| 184 | +8) Stats | |
| 185 | +======== | |
| 186 | + | |
| 187 | +Per-device statistics are exported as various nodes under /sys/block/zram<id>/ | |
| 188 | + | |
| 189 | +A brief description of exported device attributes. For more details please | |
| 190 | +read Documentation/ABI/testing/sysfs-block-zram. | |
| 191 | + | |
| 192 | +====================== ====== =============================================== | |
| 193 | +Name access description | |
| 194 | +====================== ====== =============================================== | |
| 195 | +disksize RW show and set the device's disk size | |
| 196 | +initstate RO shows the initialization state of the device | |
| 197 | +reset WO trigger device reset | |
| 198 | +mem_used_max WO reset the `mem_used_max` counter (see later) | |
| 199 | +mem_limit WO specifies the maximum amount of memory ZRAM can | |
| 200 | + use to store the compressed data | |
| 201 | +writeback_limit WO specifies the maximum amount of write IO zram | |
| 202 | + can write out to backing device as 4KB unit | |
| 203 | +writeback_limit_enable RW show and set writeback_limit feature | |
| 204 | +max_comp_streams RW the number of possible concurrent compress | |
| 205 | + operations | |
| 206 | +comp_algorithm RW show and change the compression algorithm | |
| 207 | +compact WO trigger memory compaction | |
| 208 | +debug_stat RO this file is used for zram debugging purposes | |
| 209 | +backing_dev RW set up backend storage for zram to write out | |
| 210 | +idle WO mark allocated slot as idle | |
| 211 | +====================== ====== =============================================== | |
| 212 | + | |
| 213 | + | |
| 214 | +User space is advised to use the following files to read the device statistics. | |
| 215 | + | |
| 216 | +File /sys/block/zram<id>/stat | |
| 217 | + | |
| 218 | +Represents block layer statistics. Read Documentation/block/stat.rst for | |
| 219 | +details. | |
| 220 | + | |
| 221 | +File /sys/block/zram<id>/io_stat | |
| 222 | + | |
| 223 | +The stat file represents device's I/O statistics not accounted by block | |
| 224 | +layer and, thus, not available in zram<id>/stat file. It consists of a | |
| 225 | +single line of text and contains the following stats separated by | |
| 226 | +whitespace: | |
| 227 | + | |
| 228 | + ============= ============================================================= | |
| 229 | + failed_reads The number of failed reads | |
| 230 | + failed_writes The number of failed writes | |
| 231 | + invalid_io The number of non-page-size-aligned I/O requests | |
| 232 | + notify_free Depending on device usage scenario it may account | |
| 233 | + | |
| 234 | + a) the number of pages freed because of swap slot free | |
| 235 | + notifications | |
| 236 | + b) the number of pages freed because of | |
| 237 | + REQ_OP_DISCARD requests sent by bio. The former ones are | |
| 238 | + sent to a swap block device when a swap slot is freed, | |
| 239 | + which implies that this disk is being used as a swap disk. | |
| 240 | + | |
| 241 | + The latter ones are sent by filesystem mounted with | |
| 242 | + discard option, whenever some data blocks are getting | |
| 243 | + discarded. | |
| 244 | + ============= ============================================================= | |
| 245 | + | |
| 246 | +File /sys/block/zram<id>/mm_stat | |
| 247 | + | |
| 248 | +The stat file represents device's mm statistics. It consists of a single | |
| 249 | +line of text and contains the following stats separated by whitespace: | |
| 250 | + | |
| 251 | + ================ ============================================================= | |
| 252 | + orig_data_size uncompressed size of data stored in this disk. | |
| 253 | + This excludes same-element-filled pages (same_pages) since | |
| 254 | + no memory is allocated for them. | |
| 255 | + Unit: bytes | |
| 256 | + compr_data_size compressed size of data stored in this disk | |
| 257 | + mem_used_total the amount of memory allocated for this disk. This | |
| 258 | + includes allocator fragmentation and metadata overhead, | |
| 259 | + allocated for this disk. So, allocator space efficiency | |
| 260 | + can be calculated using compr_data_size and this statistic. | |
| 261 | + Unit: bytes | |
| 262 | + mem_limit the maximum amount of memory ZRAM can use to store | |
| 263 | + the compressed data | |
| 264 | + mem_used_max the maximum amount of memory zram have consumed to | |
| 265 | + store the data | |
| 266 | + same_pages the number of same element filled pages written to this disk. | |
| 267 | + No memory is allocated for such pages. | |
| 268 | + pages_compacted the number of pages freed during compaction | |
| 269 | + huge_pages the number of incompressible pages | |
| 270 | + ================ ============================================================= | |
| 271 | + | |
| 272 | +File /sys/block/zram<id>/bd_stat | |
| 273 | + | |
| 274 | +The stat file represents device's backing device statistics. It consists of | |
| 275 | +a single line of text and contains the following stats separated by whitespace: | |
| 276 | + | |
| 277 | + ============== ============================================================= | |
| 278 | + bd_count size of data written in backing device. | |
| 279 | + Unit: 4K bytes | |
| 280 | + bd_reads the number of reads from backing device | |
| 281 | + Unit: 4K bytes | |
| 282 | + bd_writes the number of writes to backing device | |
| 283 | + Unit: 4K bytes | |
| 284 | + ============== ============================================================= | |
| 285 | + | |
| 286 | +9) Deactivate | |
| 287 | +============= | |
| 288 | + | |
| 289 | +:: | |
| 290 | + | |
| 291 | + swapoff /dev/zram0 | |
| 292 | + umount /dev/zram1 | |
| 293 | + | |
| 294 | +10) Reset | |
| 295 | +========= | |
| 296 | + | |
| 297 | + Write any positive value to 'reset' sysfs node:: | |
| 298 | + | |
| 299 | + echo 1 > /sys/block/zram0/reset | |
| 300 | + echo 1 > /sys/block/zram1/reset | |
| 301 | + | |
| 302 | + This frees all the memory allocated for the given device and | |
| 303 | + resets the disksize to zero. You must set the disksize again | |
| 304 | + before reusing the device. | |
| 305 | + | |
| 306 | +Optional Feature | |
| 307 | +================ | |
| 308 | + | |
| 309 | +writeback | |
| 310 | +--------- | |
| 311 | + | |
| 312 | +With CONFIG_ZRAM_WRITEBACK, zram can write idle/incompressible page | |
| 313 | +to backing storage rather than keeping it in memory. | |
| 314 | +To use the feature, admin should set up backing device via:: | |
| 315 | + | |
| 316 | + echo /dev/sda5 > /sys/block/zramX/backing_dev | |
| 317 | + | |
| 318 | +before disksize setting. It supports only partition at this moment. | |
| 319 | +If admin want to use incompressible page writeback, they could do via:: | |
| 320 | + | |
| 321 | + echo huge > /sys/block/zramX/write | |
| 322 | + | |
| 323 | +To use idle page writeback, first, user need to declare zram pages | |
| 324 | +as idle:: | |
| 325 | + | |
| 326 | + echo all > /sys/block/zramX/idle | |
| 327 | + | |
| 328 | +From now on, any pages on zram are idle pages. The idle mark | |
| 329 | +will be removed until someone request access of the block. | |
| 330 | +IOW, unless there is access request, those pages are still idle pages. | |
| 331 | + | |
| 332 | +Admin can request writeback of those idle pages at right timing via:: | |
| 333 | + | |
| 334 | + echo idle > /sys/block/zramX/writeback | |
| 335 | + | |
| 336 | +With the command, zram writeback idle pages from memory to the storage. | |
| 337 | + | |
| 338 | +If there are lots of write IO with flash device, potentially, it has | |
| 339 | +flash wearout problem so that admin needs to design write limitation | |
| 340 | +to guarantee storage health for entire product life. | |
| 341 | + | |
| 342 | +To overcome the concern, zram supports "writeback_limit" feature. | |
| 343 | +The "writeback_limit_enable"'s default value is 0 so that it doesn't limit | |
| 344 | +any writeback. IOW, if admin want to apply writeback budget, he should | |
| 345 | +enable writeback_limit_enable via:: | |
| 346 | + | |
| 347 | + $ echo 1 > /sys/block/zramX/writeback_limit_enable | |
| 348 | + | |
| 349 | +Once writeback_limit_enable is set, zram doesn't allow any writeback | |
| 350 | +until admin set the budget via /sys/block/zramX/writeback_limit. | |
| 351 | + | |
| 352 | +(If admin doesn't enable writeback_limit_enable, writeback_limit's value | |
| 353 | +assigned via /sys/block/zramX/writeback_limit is meaninless.) | |
| 354 | + | |
| 355 | +If admin want to limit writeback as per-day 400M, he could do it | |
| 356 | +like below:: | |
| 357 | + | |
| 358 | + $ MB_SHIFT=20 | |
| 359 | + $ 4K_SHIFT=12 | |
| 360 | + $ echo $((400<<MB_SHIFT>>4K_SHIFT)) > \ | |
| 361 | + /sys/block/zram0/writeback_limit. | |
| 362 | + $ echo 1 > /sys/block/zram0/writeback_limit_enable | |
| 363 | + | |
| 364 | +If admin want to allow further write again once the bugdet is exausted, | |
| 365 | +he could do it like below:: | |
| 366 | + | |
| 367 | + $ echo $((400<<MB_SHIFT>>4K_SHIFT)) > \ | |
| 368 | + /sys/block/zram0/writeback_limit | |
| 369 | + | |
| 370 | +If admin want to see remaining writeback budget since he set:: | |
| 371 | + | |
| 372 | + $ cat /sys/block/zramX/writeback_limit | |
| 373 | + | |
| 374 | +If admin want to disable writeback limit, he could do:: | |
| 375 | + | |
| 376 | + $ echo 0 > /sys/block/zramX/writeback_limit_enable | |
| 377 | + | |
| 378 | +The writeback_limit count will reset whenever you reset zram(e.g., | |
| 379 | +system reboot, echo 1 > /sys/block/zramX/reset) so keeping how many of | |
| 380 | +writeback happened until you reset the zram to allocate extra writeback | |
| 381 | +budget in next setting is user's job. | |
| 382 | + | |
| 383 | +If admin want to measure writeback count in a certain period, he could | |
| 384 | +know it via /sys/block/zram0/bd_stat's 3rd column. | |
| 385 | + | |
| 386 | +memory tracking | |
| 387 | +=============== | |
| 388 | + | |
| 389 | +With CONFIG_ZRAM_MEMORY_TRACKING, user can know information of the | |
| 390 | +zram block. It could be useful to catch cold or incompressible | |
| 391 | +pages of the process with*pagemap. | |
| 392 | + | |
| 393 | +If you enable the feature, you could see block state via | |
| 394 | +/sys/kernel/debug/zram/zram0/block_state". The output is as follows:: | |
| 395 | + | |
| 396 | + 300 75.033841 .wh. | |
| 397 | + 301 63.806904 s... | |
| 398 | + 302 63.806919 ..hi | |
| 399 | + | |
| 400 | +First column | |
| 401 | + zram's block index. | |
| 402 | +Second column | |
| 403 | + access time since the system was booted | |
| 404 | +Third column | |
| 405 | + state of the block: | |
| 406 | + | |
| 407 | + s: | |
| 408 | + same page | |
| 409 | + w: | |
| 410 | + written page to backing store | |
| 411 | + h: | |
| 412 | + huge page | |
| 413 | + i: | |
| 414 | + idle page | |
| 415 | + | |
| 416 | +First line of above example says 300th block is accessed at 75.033841sec | |
| 417 | +and the block's state is huge so it is written back to the backing | |
| 418 | +storage. It's a debugging feature so anyone shouldn't rely on it to work | |
| 419 | +properly. | |
| 420 | + | |
| 421 | +Nitin Gupta | |
| 422 | +ngupta@vflare.org | |
File renamed without changes.
| @@ -90,9 +90,9 @@ the disk is not available then you have three options: · 89 unmodified lines | ||
| 90 | 90 | run a null modem to a second machine and capture the output there |
| 91 | 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 | 94 | 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 | |
| 97 | 97 | Finding the bug's location |
| 98 | 98 | -------------------------- |
| @@ -0,0 +1,302 @@ | ||
| 1 | +=================== | |
| 2 | +Block IO Controller | |
| 3 | +=================== | |
| 4 | + | |
| 5 | +Overview | |
| 6 | +======== | |
| 7 | +cgroup subsys "blkio" implements the block io controller. There seems to be | |
| 8 | +a need of various kinds of IO control policies (like proportional BW, max BW) | |
| 9 | +both at leaf nodes as well as at intermediate nodes in a storage hierarchy. | |
| 10 | +Plan is to use the same cgroup based management interface for blkio controller | |
| 11 | +and based on user options switch IO policies in the background. | |
| 12 | + | |
| 13 | +One IO control policy is throttling policy which can be used to | |
| 14 | +specify upper IO rate limits on devices. This policy is implemented in | |
| 15 | +generic block layer and can be used on leaf nodes as well as higher | |
| 16 | +level logical devices like device mapper. | |
| 17 | + | |
| 18 | +HOWTO | |
| 19 | +===== | |
| 20 | +Throttling/Upper Limit policy | |
| 21 | +----------------------------- | |
| 22 | +- Enable Block IO controller:: | |
| 23 | + | |
| 24 | + CONFIG_BLK_CGROUP=y | |
| 25 | + | |
| 26 | +- Enable throttling in block layer:: | |
| 27 | + | |
| 28 | + CONFIG_BLK_DEV_THROTTLING=y | |
| 29 | + | |
| 30 | +- Mount blkio controller (see cgroups.txt, Why are cgroups needed?):: | |
| 31 | + | |
| 32 | + mount -t cgroup -o blkio none /sys/fs/cgroup/blkio | |
| 33 | + | |
| 34 | +- Specify a bandwidth rate on particular device for root group. The format | |
| 35 | + for policy is "<major>:<minor> <bytes_per_second>":: | |
| 36 | + | |
| 37 | + echo "8:16 1048576" > /sys/fs/cgroup/blkio/blkio.throttle.read_bps_device | |
| 38 | + | |
| 39 | + Above will put a limit of 1MB/second on reads happening for root group | |
| 40 | + on device having major/minor number 8:16. | |
| 41 | + | |
| 42 | +- Run dd to read a file and see if rate is throttled to 1MB/s or not:: | |
| 43 | + | |
| 44 | + # dd iflag=direct if=/mnt/common/zerofile of=/dev/null bs=4K count=1024 | |
| 45 | + 1024+0 records in | |
| 46 | + 1024+0 records out | |
| 47 | + 4194304 bytes (4.2 MB) copied, 4.0001 s, 1.0 MB/s | |
| 48 | + | |
| 49 | + Limits for writes can be put using blkio.throttle.write_bps_device file. | |
| 50 | + | |
| 51 | +Hierarchical Cgroups | |
| 52 | +==================== | |
| 53 | + | |
| 54 | +Throttling implements hierarchy support; however, | |
| 55 | +throttling's hierarchy support is enabled iff "sane_behavior" is | |
| 56 | +enabled from cgroup side, which currently is a development option and | |
| 57 | +not publicly available. | |
| 58 | + | |
| 59 | +If somebody created a hierarchy like as follows:: | |
| 60 | + | |
| 61 | + root | |
| 62 | + / \ | |
| 63 | + test1 test2 | |
| 64 | + | | |
| 65 | + test3 | |
| 66 | + | |
| 67 | +Throttling with "sane_behavior" will handle the | |
| 68 | +hierarchy correctly. For throttling, all limits apply | |
| 69 | +to the whole subtree while all statistics are local to the IOs | |
| 70 | +directly generated by tasks in that cgroup. | |
| 71 | + | |
| 72 | +Throttling without "sane_behavior" enabled from cgroup side will | |
| 73 | +practically treat all groups at same level as if it looks like the | |
| 74 | +following:: | |
| 75 | + | |
| 76 | + pivot | |
| 77 | + / / \ \ | |
| 78 | + root test1 test2 test3 | |
| 79 | + | |
| 80 | +Various user visible config options | |
| 81 | +=================================== | |
| 82 | +CONFIG_BLK_CGROUP | |
| 83 | + - Block IO controller. | |
| 84 | + | |
| 85 | +CONFIG_BFQ_CGROUP_DEBUG | |
| 86 | + - Debug help. Right now some additional stats file show up in cgroup | |
| 87 | + if this option is enabled. | |
| 88 | + | |
| 89 | +CONFIG_BLK_DEV_THROTTLING | |
| 90 | + - Enable block device throttling support in block layer. | |
| 91 | + | |
| 92 | +Details of cgroup files | |
| 93 | +======================= | |
| 94 | +Proportional weight policy files | |
| 95 | +-------------------------------- | |
| 96 | +- blkio.weight | |
| 97 | + - Specifies per cgroup weight. This is default weight of the group | |
| 98 | + on all the devices until and unless overridden by per device rule. | |
| 99 | + (See blkio.weight_device). | |
| 100 | + Currently allowed range of weights is from 10 to 1000. | |
| 101 | + | |
| 102 | +- blkio.weight_device | |
| 103 | + - One can specify per cgroup per device rules using this interface. | |
| 104 | + These rules override the default value of group weight as specified | |
| 105 | + by blkio.weight. | |
| 106 | + | |
| 107 | + Following is the format:: | |
| 108 | + | |
| 109 | + # echo dev_maj:dev_minor weight > blkio.weight_device | |
| 110 | + | |
| 111 | + Configure weight=300 on /dev/sdb (8:16) in this cgroup:: | |
| 112 | + | |
| 113 | + # echo 8:16 300 > blkio.weight_device | |
| 114 | + # cat blkio.weight_device | |
| 115 | + dev weight | |
| 116 | + 8:16 300 | |
| 117 | + | |
| 118 | + Configure weight=500 on /dev/sda (8:0) in this cgroup:: | |
| 119 | + | |
| 120 | + # echo 8:0 500 > blkio.weight_device | |
| 121 | + # cat blkio.weight_device | |
| 122 | + dev weight | |
| 123 | + 8:0 500 | |
| 124 | + 8:16 300 | |
| 125 | + | |
| 126 | + Remove specific weight for /dev/sda in this cgroup:: | |
| 127 | + | |
| 128 | + # echo 8:0 0 > blkio.weight_device | |
| 129 | + # cat blkio.weight_device | |
| 130 | + dev weight | |
| 131 | + 8:16 300 | |
| 132 | + | |
| 133 | +- blkio.leaf_weight[_device] | |
| 134 | + - Equivalents of blkio.weight[_device] for the purpose of | |
| 135 | + deciding how much weight tasks in the given cgroup has while | |
| 136 | + competing with the cgroup's child cgroups. For details, | |
| 137 | + please refer to Documentation/block/cfq-iosched.txt. | |
| 138 | + | |
| 139 | +- blkio.time | |
| 140 | + - disk time allocated to cgroup per device in milliseconds. First | |
| 141 | + two fields specify the major and minor number of the device and | |
| 142 | + third field specifies the disk time allocated to group in | |
| 143 | + milliseconds. | |
| 144 | + | |
| 145 | +- blkio.sectors | |
| 146 | + - number of sectors transferred to/from disk by the group. First | |
| 147 | + two fields specify the major and minor number of the device and | |
| 148 | + third field specifies the number of sectors transferred by the | |
| 149 | + group to/from the device. | |
| 150 | + | |
| 151 | +- blkio.io_service_bytes | |
| 152 | + - Number of bytes transferred to/from the disk by the group. These | |
| 153 | + are further divided by the type of operation - read or write, sync | |
| 154 | + or async. First two fields specify the major and minor number of the | |
| 155 | + device, third field specifies the operation type and the fourth field | |
| 156 | + specifies the number of bytes. | |
| 157 | + | |
| 158 | +- blkio.io_serviced | |
| 159 | + - Number of IOs (bio) issued to the disk by the group. These | |
| 160 | + are further divided by the type of operation - read or write, sync | |
| 161 | + or async. First two fields specify the major and minor number of the | |
| 162 | + device, third field specifies the operation type and the fourth field | |
| 163 | + specifies the number of IOs. | |
| 164 | + | |
| 165 | +- blkio.io_service_time | |
| 166 | + - Total amount of time between request dispatch and request completion | |
| 167 | + for the IOs done by this cgroup. This is in nanoseconds to make it | |
| 168 | + meaningful for flash devices too. For devices with queue depth of 1, | |
| 169 | + this time represents the actual service time. When queue_depth > 1, | |
| 170 | + that is no longer true as requests may be served out of order. This | |
| 171 | + may cause the service time for a given IO to include the service time | |
| 172 | + of multiple IOs when served out of order which may result in total | |
| 173 | + io_service_time > actual time elapsed. This time is further divided by | |
| 174 | + the type of operation - read or write, sync or async. First two fields | |
| 175 | + specify the major and minor number of the device, third field | |
| 176 | + specifies the operation type and the fourth field specifies the | |
| 177 | + io_service_time in ns. | |
| 178 | + | |
| 179 | +- blkio.io_wait_time | |
| 180 | + - Total amount of time the IOs for this cgroup spent waiting in the | |
| 181 | + scheduler queues for service. This can be greater than the total time | |
| 182 | + elapsed since it is cumulative io_wait_time for all IOs. It is not a | |
| 183 | + measure of total time the cgroup spent waiting but rather a measure of | |
| 184 | + the wait_time for its individual IOs. For devices with queue_depth > 1 | |
| 185 | + this metric does not include the time spent waiting for service once | |
| 186 | + the IO is dispatched to the device but till it actually gets serviced | |
| 187 | + (there might be a time lag here due to re-ordering of requests by the | |
| 188 | + device). This is in nanoseconds to make it meaningful for flash | |
| 189 | + devices too. This time is further divided by the type of operation - | |
| 190 | + read or write, sync or async. First two fields specify the major and | |
| 191 | + minor number of the device, third field specifies the operation type | |
| 192 | + and the fourth field specifies the io_wait_time in ns. | |
| 193 | + | |
| 194 | +- blkio.io_merged | |
| 195 | + - Total number of bios/requests merged into requests belonging to this | |
| 196 | + cgroup. This is further divided by the type of operation - read or | |
| 197 | + write, sync or async. | |
| 198 | + | |
| 199 | +- blkio.io_queued | |
| 200 | + - Total number of requests queued up at any given instant for this | |
| 201 | + cgroup. This is further divided by the type of operation - read or | |
| 202 | + write, sync or async. | |
| 203 | + | |
| 204 | +- blkio.avg_queue_size | |
| 205 | + - Debugging aid only enabled if CONFIG_BFQ_CGROUP_DEBUG=y. | |
| 206 | + The average queue size for this cgroup over the entire time of this | |
| 207 | + cgroup's existence. Queue size samples are taken each time one of the | |
| 208 | + queues of this cgroup gets a timeslice. | |
| 209 | + | |
| 210 | +- blkio.group_wait_time | |
| 211 | + - Debugging aid only enabled if CONFIG_BFQ_CGROUP_DEBUG=y. | |
| 212 | + This is the amount of time the cgroup had to wait since it became busy | |
| 213 | + (i.e., went from 0 to 1 request queued) to get a timeslice for one of | |
| 214 | + its queues. This is different from the io_wait_time which is the | |
| 215 | + cumulative total of the amount of time spent by each IO in that cgroup | |
| 216 | + waiting in the scheduler queue. This is in nanoseconds. If this is | |
| 217 | + read when the cgroup is in a waiting (for timeslice) state, the stat | |
| 218 | + will only report the group_wait_time accumulated till the last time it | |
| 219 | + got a timeslice and will not include the current delta. | |
| 220 | + | |
| 221 | +- blkio.empty_time | |
| 222 | + - Debugging aid only enabled if CONFIG_BFQ_CGROUP_DEBUG=y. | |
| 223 | + This is the amount of time a cgroup spends without any pending | |
| 224 | + requests when not being served, i.e., it does not include any time | |
| 225 | + spent idling for one of the queues of the cgroup. This is in | |
| 226 | + nanoseconds. If this is read when the cgroup is in an empty state, | |
| 227 | + the stat will only report the empty_time accumulated till the last | |
| 228 | + time it had a pending request and will not include the current delta. | |
| 229 | + | |
| 230 | +- blkio.idle_time | |
| 231 | + - Debugging aid only enabled if CONFIG_BFQ_CGROUP_DEBUG=y. | |
| 232 | + This is the amount of time spent by the IO scheduler idling for a | |
| 233 | + given cgroup in anticipation of a better request than the existing ones | |
| 234 | + from other queues/cgroups. This is in nanoseconds. If this is read | |
| 235 | + when the cgroup is in an idling state, the stat will only report the | |
| 236 | + idle_time accumulated till the last idle period and will not include | |
| 237 | + the current delta. | |
| 238 | + | |
| 239 | +- blkio.dequeue | |
| 240 | + - Debugging aid only enabled if CONFIG_BFQ_CGROUP_DEBUG=y. This | |
| 241 | + gives the statistics about how many a times a group was dequeued | |
| 242 | + from service tree of the device. First two fields specify the major | |
| 243 | + and minor number of the device and third field specifies the number | |
| 244 | + of times a group was dequeued from a particular device. | |
| 245 | + | |
| 246 | +- blkio.*_recursive | |
| 247 | + - Recursive version of various stats. These files show the | |
| 248 | + same information as their non-recursive counterparts but | |
| 249 | + include stats from all the descendant cgroups. | |
| 250 | + | |
| 251 | +Throttling/Upper limit policy files | |
| 252 | +----------------------------------- | |
| 253 | +- blkio.throttle.read_bps_device | |
| 254 | + - Specifies upper limit on READ rate from the device. IO rate is | |
| 255 | + specified in bytes per second. Rules are per device. Following is | |
| 256 | + the format:: | |
| 257 | + | |
| 258 | + echo "<major>:<minor> <rate_bytes_per_second>" > /cgrp/blkio.throttle.read_bps_device | |
| 259 | + | |
| 260 | +- blkio.throttle.write_bps_device | |
| 261 | + - Specifies upper limit on WRITE rate to the device. IO rate is | |
| 262 | + specified in bytes per second. Rules are per device. Following is | |
| 263 | + the format:: | |
| 264 | + | |
| 265 | + echo "<major>:<minor> <rate_bytes_per_second>" > /cgrp/blkio.throttle.write_bps_device | |
| 266 | + | |
| 267 | +- blkio.throttle.read_iops_device | |
| 268 | + - Specifies upper limit on READ rate from the device. IO rate is | |
| 269 | + specified in IO per second. Rules are per device. Following is | |
| 270 | + the format:: | |
| 271 | + | |
| 272 | + echo "<major>:<minor> <rate_io_per_second>" > /cgrp/blkio.throttle.read_iops_device | |
| 273 | + | |
| 274 | +- blkio.throttle.write_iops_device | |
| 275 | + - Specifies upper limit on WRITE rate to the device. IO rate is | |
| 276 | + specified in io per second. Rules are per device. Following is | |
| 277 | + the format:: | |
| 278 | + | |
| 279 | + echo "<major>:<minor> <rate_io_per_second>" > /cgrp/blkio.throttle.write_iops_device | |
| 280 | + | |
| 281 | +Note: If both BW and IOPS rules are specified for a device, then IO is | |
| 282 | + subjected to both the constraints. | |
| 283 | + | |
| 284 | +- blkio.throttle.io_serviced | |
| 285 | + - Number of IOs (bio) issued to the disk by the group. These | |
| 286 | + are further divided by the type of operation - read or write, sync | |
| 287 | + or async. First two fields specify the major and minor number of the | |
| 288 | + device, third field specifies the operation type and the fourth field | |
| 289 | + specifies the number of IOs. | |
| 290 | + | |
| 291 | +- blkio.throttle.io_service_bytes | |
| 292 | + - Number of bytes transferred to/from the disk by the group. These | |
| 293 | + are further divided by the type of operation - read or write, sync | |
| 294 | + or async. First two fields specify the major and minor number of the | |
| 295 | + device, third field specifies the operation type and the fourth field | |
| 296 | + specifies the number of bytes. | |
| 297 | + | |
| 298 | +Common files among various policies | |
| 299 | +----------------------------------- | |
| 300 | +- blkio.reset_stats | |
| 301 | + - Writing an int to this file will result in resetting all the stats | |
| 302 | + for that cgroup. | |
| @@ -0,0 +1,695 @@ | ||
| 1 | +============== | |
| 2 | +Control Groups | |
| 3 | +============== | |
| 4 | + | |
| 5 | +Written by Paul Menage <menage@google.com> based on | |
| 6 | +Documentation/admin-guide/cgroup-v1/cpusets.rst | |
| 7 | + | |
| 8 | +Original copyright statements from cpusets.txt: | |
| 9 | + | |
| 10 | +Portions Copyright (C) 2004 BULL SA. | |
| 11 | + | |
| 12 | +Portions Copyright (c) 2004-2006 Silicon Graphics, Inc. | |
| 13 | + | |
| 14 | +Modified by Paul Jackson <pj@sgi.com> | |
| 15 | + | |
| 16 | +Modified by Christoph Lameter <cl@linux.com> | |
| 17 | + | |
| 18 | +.. CONTENTS: | |
| 19 | + | |
| 20 | + 1. Control Groups | |
| 21 | + 1.1 What are cgroups ? | |
| 22 | + 1.2 Why are cgroups needed ? | |
| 23 | + 1.3 How are cgroups implemented ? | |
| 24 | + 1.4 What does notify_on_release do ? | |
| 25 | + 1.5 What does clone_children do ? | |
| 26 | + 1.6 How do I use cgroups ? | |
| 27 | + 2. Usage Examples and Syntax | |
| 28 | + 2.1 Basic Usage | |
| 29 | + 2.2 Attaching processes | |
| 30 | + 2.3 Mounting hierarchies by name | |
| 31 | + 3. Kernel API | |
| 32 | + 3.1 Overview | |
| 33 | + 3.2 Synchronization | |
| 34 | + 3.3 Subsystem API | |
| 35 | + 4. Extended attributes usage | |
| 36 | + 5. Questions | |
| 37 | + | |
| 38 | +1. Control Groups | |
| 39 | +================= | |
| 40 | + | |
| 41 | +1.1 What are cgroups ? | |
| 42 | +---------------------- | |
| 43 | + | |
| 44 | +Control Groups provide a mechanism for aggregating/partitioning sets of | |
| 45 | +tasks, and all their future children, into hierarchical groups with | |
| 46 | +specialized behaviour. | |
| 47 | + | |
| 48 | +Definitions: | |
| 49 | + | |
| 50 | +A *cgroup* associates a set of tasks with a set of parameters for one | |
| 51 | +or more subsystems. | |
| 52 | + | |
| 53 | +A *subsystem* is a module that makes use of the task grouping | |
| 54 | +facilities provided by cgroups to treat groups of tasks in | |
| 55 | +particular ways. A subsystem is typically a "resource controller" that | |
| 56 | +schedules a resource or applies per-cgroup limits, but it may be | |
| 57 | +anything that wants to act on a group of processes, e.g. a | |
| 58 | +virtualization subsystem. | |
| 59 | + | |
| 60 | +A *hierarchy* is a set of cgroups arranged in a tree, such that | |
| 61 | +every task in the system is in exactly one of the cgroups in the | |
| 62 | +hierarchy, and a set of subsystems; each subsystem has system-specific | |
| 63 | +state attached to each cgroup in the hierarchy. Each hierarchy has | |
| 64 | +an instance of the cgroup virtual filesystem associated with it. | |
| 65 | + | |
| 66 | +At any one time there may be multiple active hierarchies of task | |
| 67 | +cgroups. Each hierarchy is a partition of all tasks in the system. | |
| 68 | + | |
| 69 | +User-level code may create and destroy cgroups by name in an | |
| 70 | +instance of the cgroup virtual file system, specify and query to | |
| 71 | +which cgroup a task is assigned, and list the task PIDs assigned to | |
| 72 | +a cgroup. Those creations and assignments only affect the hierarchy | |
| 73 | +associated with that instance of the cgroup file system. | |
| 74 | + | |
| 75 | +On their own, the only use for cgroups is for simple job | |
| 76 | +tracking. The intention is that other subsystems hook into the generic | |
| 77 | +cgroup support to provide new attributes for cgroups, such as | |
| 78 | +accounting/limiting the resources which processes in a cgroup can | |
| 79 | +access. For example, cpusets (see Documentation/admin-guide/cgroup-v1/cpusets.rst) allow | |
| 80 | +you to associate a set of CPUs and a set of memory nodes with the | |
| 81 | +tasks in each cgroup. | |
| 82 | + | |
| 83 | +1.2 Why are cgroups needed ? | |
| 84 | +---------------------------- | |
| 85 | + | |
| 86 | +There are multiple efforts to provide process aggregations in the | |
| 87 | +Linux kernel, mainly for resource-tracking purposes. Such efforts | |
| 88 | +include cpusets, CKRM/ResGroups, UserBeanCounters, and virtual server | |
| 89 | +namespaces. These all require the basic notion of a | |
| 90 | +grouping/partitioning of processes, with newly forked processes ending | |
| 91 | +up in the same group (cgroup) as their parent process. | |
| 92 | + | |
| 93 | +The kernel cgroup patch provides the minimum essential kernel | |
| 94 | +mechanisms required to efficiently implement such groups. It has | |
| 95 | +minimal impact on the system fast paths, and provides hooks for | |
| 96 | +specific subsystems such as cpusets to provide additional behaviour as | |
| 97 | +desired. | |
| 98 | + | |
| 99 | +Multiple hierarchy support is provided to allow for situations where | |
| 100 | +the division of tasks into cgroups is distinctly different for | |
| 101 | +different subsystems - having parallel hierarchies allows each | |
| 102 | +hierarchy to be a natural division of tasks, without having to handle | |
| 103 | +complex combinations of tasks that would be present if several | |
| 104 | +unrelated subsystems needed to be forced into the same tree of | |
| 105 | +cgroups. | |
| 106 | + | |
| 107 | +At one extreme, each resource controller or subsystem could be in a | |
| 108 | +separate hierarchy; at the other extreme, all subsystems | |
| 109 | +would be attached to the same hierarchy. | |
| 110 | + | |
| 111 | +As an example of a scenario (originally proposed by vatsa@in.ibm.com) | |
| 112 | +that can benefit from multiple hierarchies, consider a large | |
| 113 | +university server with various users - students, professors, system | |
| 114 | +tasks etc. The resource planning for this server could be along the | |
| 115 | +following lines:: | |
| 116 | + | |
| 117 | + CPU : "Top cpuset" | |
| 118 | + / \ | |
| 119 | + CPUSet1 CPUSet2 | |
| 120 | + | | | |
| 121 | + (Professors) (Students) | |
| 122 | + | |
| 123 | + In addition (system tasks) are attached to topcpuset (so | |
| 124 | + that they can run anywhere) with a limit of 20% | |
| 125 | + | |
| 126 | + Memory : Professors (50%), Students (30%), system (20%) | |
| 127 | + | |
| 128 | + Disk : Professors (50%), Students (30%), system (20%) | |
| 129 | + | |
| 130 | + Network : WWW browsing (20%), Network File System (60%), others (20%) | |
| 131 | + / \ | |
| 132 | + Professors (15%) students (5%) | |
| 133 | + | |
| 134 | +Browsers like Firefox/Lynx go into the WWW network class, while (k)nfsd goes | |
| 135 | +into the NFS network class. | |
| 136 | + | |
| 137 | +At the same time Firefox/Lynx will share an appropriate CPU/Memory class | |
| 138 | +depending on who launched it (prof/student). | |
| 139 | + | |
| 140 | +With the ability to classify tasks differently for different resources | |
| 141 | +(by putting those resource subsystems in different hierarchies), | |
| 142 | +the admin can easily set up a script which receives exec notifications | |
| 143 | +and depending on who is launching the browser he can:: | |
| 144 | + | |
| 145 | + # echo browser_pid > /sys/fs/cgroup/<restype>/<userclass>/tasks | |
| 146 | + | |
| 147 | +With only a single hierarchy, he now would potentially have to create | |
| 148 | +a separate cgroup for every browser launched and associate it with | |
| 149 | +appropriate network and other resource class. This may lead to | |
| 150 | +proliferation of such cgroups. | |
| 151 | + | |
| 152 | +Also let's say that the administrator would like to give enhanced network | |
| 153 | +access temporarily to a student's browser (since it is night and the user | |
| 154 | +wants to do online gaming :)) OR give one of the student's simulation | |
| 155 | +apps enhanced CPU power. | |
| 156 | + | |
| 157 | +With ability to write PIDs directly to resource classes, it's just a | |
| 158 | +matter of:: | |
| 159 | + | |
| 160 | + # echo pid > /sys/fs/cgroup/network/<new_class>/tasks | |
| 161 | + (after some time) | |
| 162 | + # echo pid > /sys/fs/cgroup/network/<orig_class>/tasks | |
| 163 | + | |
| 164 | +Without this ability, the administrator would have to split the cgroup into | |
| 165 | +multiple separate ones and then associate the new cgroups with the | |
| 166 | +new resource classes. | |
| 167 | + | |
| 168 | + | |
| 169 | + | |
| 170 | +1.3 How are cgroups implemented ? | |
| 171 | +--------------------------------- | |
| 172 | + | |
| 173 | +Control Groups extends the kernel as follows: | |
| 174 | + | |
| 175 | + - Each task in the system has a reference-counted pointer to a | |
| 176 | + css_set. | |
| 177 | + | |
| 178 | + - A css_set contains a set of reference-counted pointers to | |
| 179 | + cgroup_subsys_state objects, one for each cgroup subsystem | |
| 180 | + registered in the system. There is no direct link from a task to | |
| 181 | + the cgroup of which it's a member in each hierarchy, but this | |
| 182 | + can be determined by following pointers through the | |
| 183 | + cgroup_subsys_state objects. This is because accessing the | |
| 184 | + subsystem state is something that's expected to happen frequently | |
| 185 | + and in performance-critical code, whereas operations that require a | |
| 186 | + task's actual cgroup assignments (in particular, moving between | |
| 187 | + cgroups) are less common. A linked list runs through the cg_list | |
| 188 | + field of each task_struct using the css_set, anchored at | |
| 189 | + css_set->tasks. | |
| 190 | + | |
| 191 | + - A cgroup hierarchy filesystem can be mounted for browsing and | |
| 192 | + manipulation from user space. | |
| 193 | + | |
| 194 | + - You can list all the tasks (by PID) attached to any cgroup. | |
| 195 | + | |
| 196 | +The implementation of cgroups requires a few, simple hooks | |
| 197 | +into the rest of the kernel, none in performance-critical paths: | |
| 198 | + | |
| 199 | + - in init/main.c, to initialize the root cgroups and initial | |
| 200 | + css_set at system boot. | |
| 201 | + | |
| 202 | + - in fork and exit, to attach and detach a task from its css_set. | |
| 203 | + | |
| 204 | +In addition, a new file system of type "cgroup" may be mounted, to | |
| 205 | +enable browsing and modifying the cgroups presently known to the | |
| 206 | +kernel. When mounting a cgroup hierarchy, you may specify a | |
| 207 | +comma-separated list of subsystems to mount as the filesystem mount | |
| 208 | +options. By default, mounting the cgroup filesystem attempts to | |
| 209 | +mount a hierarchy containing all registered subsystems. | |
| 210 | + | |
| 211 | +If an active hierarchy with exactly the same set of subsystems already | |
| 212 | +exists, it will be reused for the new mount. If no existing hierarchy | |
| 213 | +matches, and any of the requested subsystems are in use in an existing | |
| 214 | +hierarchy, the mount will fail with -EBUSY. Otherwise, a new hierarchy | |
| 215 | +is activated, associated with the requested subsystems. | |
| 216 | + | |
| 217 | +It's not currently possible to bind a new subsystem to an active | |
| 218 | +cgroup hierarchy, or to unbind a subsystem from an active cgroup | |
| 219 | +hierarchy. This may be possible in future, but is fraught with nasty | |
| 220 | +error-recovery issues. | |
| 221 | + | |
| 222 | +When a cgroup filesystem is unmounted, if there are any | |
| 223 | +child cgroups created below the top-level cgroup, that hierarchy | |
| 224 | +will remain active even though unmounted; if there are no | |
| 225 | +child cgroups then the hierarchy will be deactivated. | |
| 226 | + | |
| 227 | +No new system calls are added for cgroups - all support for | |
| 228 | +querying and modifying cgroups is via this cgroup file system. | |
| 229 | + | |
| 230 | +Each task under /proc has an added file named 'cgroup' displaying, | |
| 231 | +for each active hierarchy, the subsystem names and the cgroup name | |
| 232 | +as the path relative to the root of the cgroup file system. | |
| 233 | + | |
| 234 | +Each cgroup is represented by a directory in the cgroup file system | |
| 235 | +containing the following files describing that cgroup: | |
| 236 | + | |
| 237 | + - tasks: list of tasks (by PID) attached to that cgroup. This list | |
| 238 | + is not guaranteed to be sorted. Writing a thread ID into this file | |
| 239 | + moves the thread into this cgroup. | |
| 240 | + - cgroup.procs: list of thread group IDs in the cgroup. This list is | |
| 241 | + not guaranteed to be sorted or free of duplicate TGIDs, and userspace | |
| 242 | + should sort/uniquify the list if this property is required. | |
| 243 | + Writing a thread group ID into this file moves all threads in that | |
| 244 | + group into this cgroup. | |
| 245 | + - notify_on_release flag: run the release agent on exit? | |
| 246 | + - release_agent: the path to use for release notifications (this file | |
| 247 | + exists in the top cgroup only) | |
| 248 | + | |
| 249 | +Other subsystems such as cpusets may add additional files in each | |
| 250 | +cgroup dir. | |
| 251 | + | |
| 252 | +New cgroups are created using the mkdir system call or shell | |
| 253 | +command. The properties of a cgroup, such as its flags, are | |
| 254 | +modified by writing to the appropriate file in that cgroups | |
| 255 | +directory, as listed above. | |
| 256 | + | |
| 257 | +The named hierarchical structure of nested cgroups allows partitioning | |
| 258 | +a large system into nested, dynamically changeable, "soft-partitions". | |
| 259 | + | |
| 260 | +The attachment of each task, automatically inherited at fork by any | |
| 261 | +children of that task, to a cgroup allows organizing the work load | |
| 262 | +on a system into related sets of tasks. A task may be re-attached to | |
| 263 | +any other cgroup, if allowed by the permissions on the necessary | |
| 264 | +cgroup file system directories. | |
| 265 | + | |
| 266 | +When a task is moved from one cgroup to another, it gets a new | |
| 267 | +css_set pointer - if there's an already existing css_set with the | |
| 268 | +desired collection of cgroups then that group is reused, otherwise a new | |
| 269 | +css_set is allocated. The appropriate existing css_set is located by | |
| 270 | +looking into a hash table. | |
| 271 | + | |
| 272 | +To allow access from a cgroup to the css_sets (and hence tasks) | |
| 273 | +that comprise it, a set of cg_cgroup_link objects form a lattice; | |
| 274 | +each cg_cgroup_link is linked into a list of cg_cgroup_links for | |
| 275 | +a single cgroup on its cgrp_link_list field, and a list of | |
| 276 | +cg_cgroup_links for a single css_set on its cg_link_list. | |
| 277 | + | |
| 278 | +Thus the set of tasks in a cgroup can be listed by iterating over | |
| 279 | +each css_set that references the cgroup, and sub-iterating over | |
| 280 | +each css_set's task set. | |
| 281 | + | |
| 282 | +The use of a Linux virtual file system (vfs) to represent the | |
| 283 | +cgroup hierarchy provides for a familiar permission and name space | |
| 284 | +for cgroups, with a minimum of additional kernel code. | |
| 285 | + | |
| 286 | +1.4 What does notify_on_release do ? | |
| 287 | +------------------------------------ | |
| 288 | + | |
| 289 | +If the notify_on_release flag is enabled (1) in a cgroup, then | |
| 290 | +whenever the last task in the cgroup leaves (exits or attaches to | |
| 291 | +some other cgroup) and the last child cgroup of that cgroup | |
| 292 | +is removed, then the kernel runs the command specified by the contents | |
| 293 | +of the "release_agent" file in that hierarchy's root directory, | |
| 294 | +supplying the pathname (relative to the mount point of the cgroup | |
| 295 | +file system) of the abandoned cgroup. This enables automatic | |
| 296 | +removal of abandoned cgroups. The default value of | |
| 297 | +notify_on_release in the root cgroup at system boot is disabled | |
| 298 | +(0). The default value of other cgroups at creation is the current | |
| 299 | +value of their parents' notify_on_release settings. The default value of | |
| 300 | +a cgroup hierarchy's release_agent path is empty. | |
| 301 | + | |
| 302 | +1.5 What does clone_children do ? | |
| 303 | +--------------------------------- | |
| 304 | + | |
| 305 | +This flag only affects the cpuset controller. If the clone_children | |
| 306 | +flag is enabled (1) in a cgroup, a new cpuset cgroup will copy its | |
| 307 | +configuration from the parent during initialization. | |
| 308 | + | |
| 309 | +1.6 How do I use cgroups ? | |
| 310 | +-------------------------- | |
| 311 | + | |
| 312 | +To start a new job that is to be contained within a cgroup, using | |
| 313 | +the "cpuset" cgroup subsystem, the steps are something like:: | |
| 314 | + | |
| 315 | + 1) mount -t tmpfs cgroup_root /sys/fs/cgroup | |
| 316 | + 2) mkdir /sys/fs/cgroup/cpuset | |
| 317 | + 3) mount -t cgroup -ocpuset cpuset /sys/fs/cgroup/cpuset | |
| 318 | + 4) Create the new cgroup by doing mkdir's and write's (or echo's) in | |
| 319 | + the /sys/fs/cgroup/cpuset virtual file system. | |
| 320 | + 5) Start a task that will be the "founding father" of the new job. | |
| 321 | + 6) Attach that task to the new cgroup by writing its PID to the | |
| 322 | + /sys/fs/cgroup/cpuset tasks file for that cgroup. | |
| 323 | + 7) fork, exec or clone the job tasks from this founding father task. | |
| 324 | + | |
| 325 | +For example, the following sequence of commands will setup a cgroup | |
| 326 | +named "Charlie", containing just CPUs 2 and 3, and Memory Node 1, | |
| 327 | +and then start a subshell 'sh' in that cgroup:: | |
| 328 | + | |
| 329 | + mount -t tmpfs cgroup_root /sys/fs/cgroup | |
| 330 | + mkdir /sys/fs/cgroup/cpuset | |
| 331 | + mount -t cgroup cpuset -ocpuset /sys/fs/cgroup/cpuset | |
| 332 | + cd /sys/fs/cgroup/cpuset | |
| 333 | + mkdir Charlie | |
| 334 | + cd Charlie | |
| 335 | + /bin/echo 2-3 > cpuset.cpus | |
| 336 | + /bin/echo 1 > cpuset.mems | |
| 337 | + /bin/echo $$ > tasks | |
| 338 | + sh | |
| 339 | + # The subshell 'sh' is now running in cgroup Charlie | |
| 340 | + # The next line should display '/Charlie' | |
| 341 | + cat /proc/self/cgroup | |
| 342 | + | |
| 343 | +2. Usage Examples and Syntax | |
| 344 | +============================ | |
| 345 | + | |
| 346 | +2.1 Basic Usage | |
| 347 | +--------------- | |
| 348 | + | |
| 349 | +Creating, modifying, using cgroups can be done through the cgroup | |
| 350 | +virtual filesystem. | |
| 351 | + | |
| 352 | +To mount a cgroup hierarchy with all available subsystems, type:: | |
| 353 | + | |
| 354 | + # mount -t cgroup xxx /sys/fs/cgroup | |
| 355 | + | |
| 356 | +The "xxx" is not interpreted by the cgroup code, but will appear in | |
| 357 | +/proc/mounts so may be any useful identifying string that you like. | |
| 358 | + | |
| 359 | +Note: Some subsystems do not work without some user input first. For instance, | |
| 360 | +if cpusets are enabled the user will have to populate the cpus and mems files | |
| 361 | +for each new cgroup created before that group can be used. | |
| 362 | + | |
| 363 | +As explained in section `1.2 Why are cgroups needed?` you should create | |
| 364 | +different hierarchies of cgroups for each single resource or group of | |
| 365 | +resources you want to control. Therefore, you should mount a tmpfs on | |
| 366 | +/sys/fs/cgroup and create directories for each cgroup resource or resource | |
| 367 | +group:: | |
| 368 | + | |
| 369 | + # mount -t tmpfs cgroup_root /sys/fs/cgroup | |
| 370 | + # mkdir /sys/fs/cgroup/rg1 | |
| 371 | + | |
| 372 | +To mount a cgroup hierarchy with just the cpuset and memory | |
| 373 | +subsystems, type:: | |
| 374 | + | |
| 375 | + # mount -t cgroup -o cpuset,memory hier1 /sys/fs/cgroup/rg1 | |
| 376 | + | |
| 377 | +While remounting cgroups is currently supported, it is not recommend | |
| 378 | +to use it. Remounting allows changing bound subsystems and | |
| 379 | +release_agent. Rebinding is hardly useful as it only works when the | |
| 380 | +hierarchy is empty and release_agent itself should be replaced with | |
| 381 | +conventional fsnotify. The support for remounting will be removed in | |
| 382 | +the future. | |
| 383 | + | |
| 384 | +To Specify a hierarchy's release_agent:: | |
| 385 | + | |
| 386 | + # mount -t cgroup -o cpuset,release_agent="/sbin/cpuset_release_agent" \ | |
| 387 | + xxx /sys/fs/cgroup/rg1 | |
| 388 | + | |
| 389 | +Note that specifying 'release_agent' more than once will return failure. | |
| 390 | + | |
| 391 | +Note that changing the set of subsystems is currently only supported | |
| 392 | +when the hierarchy consists of a single (root) cgroup. Supporting | |
| 393 | +the ability to arbitrarily bind/unbind subsystems from an existing | |
| 394 | +cgroup hierarchy is intended to be implemented in the future. | |
| 395 | + | |
| 396 | +Then under /sys/fs/cgroup/rg1 you can find a tree that corresponds to the | |
| 397 | +tree of the cgroups in the system. For instance, /sys/fs/cgroup/rg1 | |
| 398 | +is the cgroup that holds the whole system. | |
| 399 | + | |
| 400 | +If you want to change the value of release_agent:: | |
| 401 | + | |
| 402 | + # echo "/sbin/new_release_agent" > /sys/fs/cgroup/rg1/release_agent | |
| 403 | + | |
| 404 | +It can also be changed via remount. | |
| 405 | + | |
| 406 | +If you want to create a new cgroup under /sys/fs/cgroup/rg1:: | |
| 407 | + | |
| 408 | + # cd /sys/fs/cgroup/rg1 | |
| 409 | + # mkdir my_cgroup | |
| 410 | + | |
| 411 | +Now you want to do something with this cgroup: | |
| 412 | + | |
| 413 | + # cd my_cgroup | |
| 414 | + | |
| 415 | +In this directory you can find several files:: | |
| 416 | + | |
| 417 | + # ls | |
| 418 | + cgroup.procs notify_on_release tasks | |
| 419 | + (plus whatever files added by the attached subsystems) | |
| 420 | + | |
| 421 | +Now attach your shell to this cgroup:: | |
| 422 | + | |
| 423 | + # /bin/echo $$ > tasks | |
| 424 | + | |
| 425 | +You can also create cgroups inside your cgroup by using mkdir in this | |
| 426 | +directory:: | |
| 427 | + | |
| 428 | + # mkdir my_sub_cs | |
| 429 | + | |
| 430 | +To remove a cgroup, just use rmdir:: | |
| 431 | + | |
| 432 | + # rmdir my_sub_cs | |
| 433 | + | |
| 434 | +This will fail if the cgroup is in use (has cgroups inside, or | |
| 435 | +has processes attached, or is held alive by other subsystem-specific | |
| 436 | +reference). | |
| 437 | + | |
| 438 | +2.2 Attaching processes | |
| 439 | +----------------------- | |
| 440 | + | |
| 441 | +:: | |
| 442 | + | |
| 443 | + # /bin/echo PID > tasks | |
| 444 | + | |
| 445 | +Note that it is PID, not PIDs. You can only attach ONE task at a time. | |
| 446 | +If you have several tasks to attach, you have to do it one after another:: | |
| 447 | + | |
| 448 | + # /bin/echo PID1 > tasks | |
| 449 | + # /bin/echo PID2 > tasks | |
| 450 | + ... | |
| 451 | + # /bin/echo PIDn > tasks | |
| 452 | + | |
| 453 | +You can attach the current shell task by echoing 0:: | |
| 454 | + | |
| 455 | + # echo 0 > tasks | |
| 456 | + | |
| 457 | +You can use the cgroup.procs file instead of the tasks file to move all | |
| 458 | +threads in a threadgroup at once. Echoing the PID of any task in a | |
| 459 | +threadgroup to cgroup.procs causes all tasks in that threadgroup to be | |
| 460 | +attached to the cgroup. Writing 0 to cgroup.procs moves all tasks | |
| 461 | +in the writing task's threadgroup. | |
| 462 | + | |
| 463 | +Note: Since every task is always a member of exactly one cgroup in each | |
| 464 | +mounted hierarchy, to remove a task from its current cgroup you must | |
| 465 | +move it into a new cgroup (possibly the root cgroup) by writing to the | |
| 466 | +new cgroup's tasks file. | |
| 467 | + | |
| 468 | +Note: Due to some restrictions enforced by some cgroup subsystems, moving | |
| 469 | +a process to another cgroup can fail. | |
| 470 | + | |
| 471 | +2.3 Mounting hierarchies by name | |
| 472 | +-------------------------------- | |
| 473 | + | |
| 474 | +Passing the name=<x> option when mounting a cgroups hierarchy | |
| 475 | +associates the given name with the hierarchy. This can be used when | |
| 476 | +mounting a pre-existing hierarchy, in order to refer to it by name | |
| 477 | +rather than by its set of active subsystems. Each hierarchy is either | |
| 478 | +nameless, or has a unique name. | |
| 479 | + | |
| 480 | +The name should match [\w.-]+ | |
| 481 | + | |
| 482 | +When passing a name=<x> option for a new hierarchy, you need to | |
| 483 | +specify subsystems manually; the legacy behaviour of mounting all | |
| 484 | +subsystems when none are explicitly specified is not supported when | |
| 485 | +you give a subsystem a name. | |
| 486 | + | |
| 487 | +The name of the subsystem appears as part of the hierarchy description | |
| 488 | +in /proc/mounts and /proc/<pid>/cgroups. | |
| 489 | + | |
| 490 | + | |
| 491 | +3. Kernel API | |
| 492 | +============= | |
| 493 | + | |
| 494 | +3.1 Overview | |
| 495 | +------------ | |
| 496 | + | |
| 497 | +Each kernel subsystem that wants to hook into the generic cgroup | |
| 498 | +system needs to create a cgroup_subsys object. This contains | |
| 499 | +various methods, which are callbacks from the cgroup system, along | |
| 500 | +with a subsystem ID which will be assigned by the cgroup system. | |
| 501 | + | |
| 502 | +Other fields in the cgroup_subsys object include: | |
| 503 | + | |
| 504 | +- subsys_id: a unique array index for the subsystem, indicating which | |
| 505 | + entry in cgroup->subsys[] this subsystem should be managing. | |
| 506 | + | |
| 507 | +- name: should be initialized to a unique subsystem name. Should be | |
| 508 | + no longer than MAX_CGROUP_TYPE_NAMELEN. | |
| 509 | + | |
| 510 | +- early_init: indicate if the subsystem needs early initialization | |
| 511 | + at system boot. | |
| 512 | + | |
| 513 | +Each cgroup object created by the system has an array of pointers, | |
| 514 | +indexed by subsystem ID; this pointer is entirely managed by the | |
| 515 | +subsystem; the generic cgroup code will never touch this pointer. | |
| 516 | + | |
| 517 | +3.2 Synchronization | |
| 518 | +------------------- | |
| 519 | + | |
| 520 | +There is a global mutex, cgroup_mutex, used by the cgroup | |
| 521 | +system. This should be taken by anything that wants to modify a | |
| 522 | +cgroup. It may also be taken to prevent cgroups from being | |
| 523 | +modified, but more specific locks may be more appropriate in that | |
| 524 | +situation. | |
| 525 | + | |
| 526 | +See kernel/cgroup.c for more details. | |
| 527 | + | |
| 528 | +Subsystems can take/release the cgroup_mutex via the functions | |
| 529 | +cgroup_lock()/cgroup_unlock(). | |
| 530 | + | |
| 531 | +Accessing a task's cgroup pointer may be done in the following ways: | |
| 532 | +- while holding cgroup_mutex | |
| 533 | +- while holding the task's alloc_lock (via task_lock()) | |
| 534 | +- inside an rcu_read_lock() section via rcu_dereference() | |
| 535 | + | |
| 536 | +3.3 Subsystem API | |
| 537 | +----------------- | |
| 538 | + | |
| 539 | +Each subsystem should: | |
| 540 | + | |
| 541 | +- add an entry in linux/cgroup_subsys.h | |
| 542 | +- define a cgroup_subsys object called <name>_cgrp_subsys | |
| 543 | + | |
| 544 | +Each subsystem may export the following methods. The only mandatory | |
| 545 | +methods are css_alloc/free. Any others that are null are presumed to | |
| 546 | +be successful no-ops. | |
| 547 | + | |
| 548 | +``struct cgroup_subsys_state *css_alloc(struct cgroup *cgrp)`` | |
| 549 | +(cgroup_mutex held by caller) | |
| 550 | + | |
| 551 | +Called to allocate a subsystem state object for a cgroup. The | |
| 552 | +subsystem should allocate its subsystem state object for the passed | |
| 553 | +cgroup, returning a pointer to the new object on success or a | |
| 554 | +ERR_PTR() value. On success, the subsystem pointer should point to | |
| 555 | +a structure of type cgroup_subsys_state (typically embedded in a | |
| 556 | +larger subsystem-specific object), which will be initialized by the | |
| 557 | +cgroup system. Note that this will be called at initialization to | |
| 558 | +create the root subsystem state for this subsystem; this case can be | |
| 559 | +identified by the passed cgroup object having a NULL parent (since | |
| 560 | +it's the root of the hierarchy) and may be an appropriate place for | |
| 561 | +initialization code. | |
| 562 | + | |
| 563 | +``int css_online(struct cgroup *cgrp)`` | |
| 564 | +(cgroup_mutex held by caller) | |
| 565 | + | |
| 566 | +Called after @cgrp successfully completed all allocations and made | |
| 567 | +visible to cgroup_for_each_child/descendant_*() iterators. The | |
| 568 | +subsystem may choose to fail creation by returning -errno. This | |
| 569 | +callback can be used to implement reliable state sharing and | |
| 570 | +propagation along the hierarchy. See the comment on | |
| 571 | +cgroup_for_each_descendant_pre() for details. | |
| 572 | + | |
| 573 | +``void css_offline(struct cgroup *cgrp);`` | |
| 574 | +(cgroup_mutex held by caller) | |
| 575 | + | |
| 576 | +This is the counterpart of css_online() and called iff css_online() | |
| 577 | +has succeeded on @cgrp. This signifies the beginning of the end of | |
| 578 | +@cgrp. @cgrp is being removed and the subsystem should start dropping | |
| 579 | +all references it's holding on @cgrp. When all references are dropped, | |
| 580 | +cgroup removal will proceed to the next step - css_free(). After this | |
| 581 | +callback, @cgrp should be considered dead to the subsystem. | |
| 582 | + | |
| 583 | +``void css_free(struct cgroup *cgrp)`` | |
| 584 | +(cgroup_mutex held by caller) | |
| 585 | + | |
| 586 | +The cgroup system is about to free @cgrp; the subsystem should free | |
| 587 | +its subsystem state object. By the time this method is called, @cgrp | |
| 588 | +is completely unused; @cgrp->parent is still valid. (Note - can also | |
| 589 | +be called for a newly-created cgroup if an error occurs after this | |
| 590 | +subsystem's create() method has been called for the new cgroup). | |
| 591 | + | |
| 592 | +``int can_attach(struct cgroup *cgrp, struct cgroup_taskset *tset)`` | |
| 593 | +(cgroup_mutex held by caller) | |
| 594 | + | |
| 595 | +Called prior to moving one or more tasks into a cgroup; if the | |
| 596 | +subsystem returns an error, this will abort the attach operation. | |
| 597 | +@tset contains the tasks to be attached and is guaranteed to have at | |
| 598 | +least one task in it. | |
| 599 | + | |
| 600 | +If there are multiple tasks in the taskset, then: | |
| 601 | + - it's guaranteed that all are from the same thread group | |
| 602 | + - @tset contains all tasks from the thread group whether or not | |
| 603 | + they're switching cgroups | |
| 604 | + - the first task is the leader | |
| 605 | + | |
| 606 | +Each @tset entry also contains the task's old cgroup and tasks which | |
| 607 | +aren't switching cgroup can be skipped easily using the | |
| 608 | +cgroup_taskset_for_each() iterator. Note that this isn't called on a | |
| 609 | +fork. If this method returns 0 (success) then this should remain valid | |
| 610 | +while the caller holds cgroup_mutex and it is ensured that either | |
| 611 | +attach() or cancel_attach() will be called in future. | |
| 612 | + | |
| 613 | +``void css_reset(struct cgroup_subsys_state *css)`` | |
| 614 | +(cgroup_mutex held by caller) | |
| 615 | + | |
| 616 | +An optional operation which should restore @css's configuration to the | |
| 617 | +initial state. This is currently only used on the unified hierarchy | |
| 618 | +when a subsystem is disabled on a cgroup through | |
| 619 | +"cgroup.subtree_control" but should remain enabled because other | |
| 620 | +subsystems depend on it. cgroup core makes such a css invisible by | |
| 621 | +removing the associated interface files and invokes this callback so | |
| 622 | +that the hidden subsystem can return to the initial neutral state. | |
| 623 | +This prevents unexpected resource control from a hidden css and | |
| 624 | +ensures that the configuration is in the initial state when it is made | |
| 625 | +visible again later. | |
| 626 | + | |
| 627 | +``void cancel_attach(struct cgroup *cgrp, struct cgroup_taskset *tset)`` | |
| 628 | +(cgroup_mutex held by caller) | |
| 629 | + | |
| 630 | +Called when a task attach operation has failed after can_attach() has succeeded. | |
| 631 | +A subsystem whose can_attach() has some side-effects should provide this | |
| 632 | +function, so that the subsystem can implement a rollback. If not, not necessary. | |
| 633 | +This will be called only about subsystems whose can_attach() operation have | |
| 634 | +succeeded. The parameters are identical to can_attach(). | |
| 635 | + | |
| 636 | +``void attach(struct cgroup *cgrp, struct cgroup_taskset *tset)`` | |
| 637 | +(cgroup_mutex held by caller) | |
| 638 | + | |
| 639 | +Called after the task has been attached to the cgroup, to allow any | |
| 640 | +post-attachment activity that requires memory allocations or blocking. | |
| 641 | +The parameters are identical to can_attach(). | |
| 642 | + | |
| 643 | +``void fork(struct task_struct *task)`` | |
| 644 | + | |
| 645 | +Called when a task is forked into a cgroup. | |
| 646 | + | |
| 647 | +``void exit(struct task_struct *task)`` | |
| 648 | + | |
| 649 | +Called during task exit. | |
| 650 | + | |
| 651 | +``void free(struct task_struct *task)`` | |
| 652 | + | |
| 653 | +Called when the task_struct is freed. | |
| 654 | + | |
| 655 | +``void bind(struct cgroup *root)`` | |
| 656 | +(cgroup_mutex held by caller) | |
| 657 | + | |
| 658 | +Called when a cgroup subsystem is rebound to a different hierarchy | |
| 659 | +and root cgroup. Currently this will only involve movement between | |
| 660 | +the default hierarchy (which never has sub-cgroups) and a hierarchy | |
| 661 | +that is being created/destroyed (and hence has no sub-cgroups). | |
| 662 | + | |
| 663 | +4. Extended attribute usage | |
| 664 | +=========================== | |
| 665 | + | |
| 666 | +cgroup filesystem supports certain types of extended attributes in its | |
| 667 | +directories and files. The current supported types are: | |
| 668 | + | |
| 669 | + - Trusted (XATTR_TRUSTED) | |
| 670 | + - Security (XATTR_SECURITY) | |
| 671 | + | |
| 672 | +Both require CAP_SYS_ADMIN capability to set. | |
| 673 | + | |
| 674 | +Like in tmpfs, the extended attributes in cgroup filesystem are stored | |
| 675 | +using kernel memory and it's advised to keep the usage at minimum. This | |
| 676 | +is the reason why user defined extended attributes are not supported, since | |
| 677 | +any user can do it and there's no limit in the value size. | |
| 678 | + | |
| 679 | +The current known users for this feature are SELinux to limit cgroup usage | |
| 680 | +in containers and systemd for assorted meta data like main PID in a cgroup | |
| 681 | +(systemd creates a cgroup per service). | |
| 682 | + | |
| 683 | +5. Questions | |
| 684 | +============ | |
| 685 | + | |
| 686 | +:: | |
| 687 | + | |
| 688 | + Q: what's up with this '/bin/echo' ? | |
| 689 | + A: bash's builtin 'echo' command does not check calls to write() against | |
| 690 | + errors. If you use it in the cgroup file system, you won't be | |
| 691 | + able to tell whether a command succeeded or failed. | |
| 692 | + | |
| 693 | + Q: When I attach processes, only the first of the line gets really attached ! | |
| 694 | + A: We can only return one error code per call to write(). So you should also | |
| 695 | + put only ONE PID. | |
| @@ -0,0 +1,50 @@ | ||
| 1 | +========================= | |
| 2 | +CPU Accounting Controller | |
| 3 | +========================= | |
| 4 | + | |
| 5 | +The CPU accounting controller is used to group tasks using cgroups and | |
| 6 | +account the CPU usage of these groups of tasks. | |
| 7 | + | |
| 8 | +The CPU accounting controller supports multi-hierarchy groups. An accounting | |
| 9 | +group accumulates the CPU usage of all of its child groups and the tasks | |
| 10 | +directly present in its group. | |
| 11 | + | |
| 12 | +Accounting groups can be created by first mounting the cgroup filesystem:: | |
| 13 | + | |
| 14 | + # mount -t cgroup -ocpuacct none /sys/fs/cgroup | |
| 15 | + | |
| 16 | +With the above step, the initial or the parent accounting group becomes | |
| 17 | +visible at /sys/fs/cgroup. At bootup, this group includes all the tasks in | |
| 18 | +the system. /sys/fs/cgroup/tasks lists the tasks in this cgroup. | |
| 19 | +/sys/fs/cgroup/cpuacct.usage gives the CPU time (in nanoseconds) obtained | |
| 20 | +by this group which is essentially the CPU time obtained by all the tasks | |
| 21 | +in the system. | |
| 22 | + | |
| 23 | +New accounting groups can be created under the parent group /sys/fs/cgroup:: | |
| 24 | + | |
| 25 | + # cd /sys/fs/cgroup | |
| 26 | + # mkdir g1 | |
| 27 | + # echo $$ > g1/tasks | |
| 28 | + | |
| 29 | +The above steps create a new group g1 and move the current shell | |
| 30 | +process (bash) into it. CPU time consumed by this bash and its children | |
| 31 | +can be obtained from g1/cpuacct.usage and the same is accumulated in | |
| 32 | +/sys/fs/cgroup/cpuacct.usage also. | |
| 33 | + | |
| 34 | +cpuacct.stat file lists a few statistics which further divide the | |
| 35 | +CPU time obtained by the cgroup into user and system times. Currently | |
| 36 | +the following statistics are supported: | |
| 37 | + | |
| 38 | +user: Time spent by tasks of the cgroup in user mode. | |
| 39 | +system: Time spent by tasks of the cgroup in kernel mode. | |
| 40 | + | |
| 41 | +user and system are in USER_HZ unit. | |
| 42 | + | |
| 43 | +cpuacct controller uses percpu_counter interface to collect user and | |
| 44 | +system times. This has two side effects: | |
| 45 | + | |
| 46 | +- It is theoretically possible to see wrong values for user and system times. | |
| 47 | + This is because percpu_counter_read() on 32bit systems isn't safe | |
| 48 | + against concurrent writes. | |
| 49 | +- It is possible to see slightly outdated values for user and system times | |
| 50 | + due to the batch processing nature of percpu_counter. | |
| @@ -0,0 +1,866 @@ | ||
| 1 | +======= | |
| 2 | +CPUSETS | |
| 3 | +======= | |
| 4 | + | |
| 5 | +Copyright (C) 2004 BULL SA. | |
| 6 | + | |
| 7 | +Written by Simon.Derr@bull.net | |
| 8 | + | |
| 9 | +- Portions Copyright (c) 2004-2006 Silicon Graphics, Inc. | |
| 10 | +- Modified by Paul Jackson <pj@sgi.com> | |
| 11 | +- Modified by Christoph Lameter <cl@linux.com> | |
| 12 | +- Modified by Paul Menage <menage@google.com> | |
| 13 | +- Modified by Hidetoshi Seto <seto.hidetoshi@jp.fujitsu.com> | |
| 14 | + | |
| 15 | +.. CONTENTS: | |
| 16 | + | |
| 17 | + 1. Cpusets | |
| 18 | + 1.1 What are cpusets ? | |
| 19 | + 1.2 Why are cpusets needed ? | |
| 20 | + 1.3 How are cpusets implemented ? | |
| 21 | + 1.4 What are exclusive cpusets ? | |
| 22 | + 1.5 What is memory_pressure ? | |
| 23 | + 1.6 What is memory spread ? | |
| 24 | + 1.7 What is sched_load_balance ? | |
| 25 | + 1.8 What is sched_relax_domain_level ? | |
| 26 | + 1.9 How do I use cpusets ? | |
| 27 | + 2. Usage Examples and Syntax | |
| 28 | + 2.1 Basic Usage | |
| 29 | + 2.2 Adding/removing cpus | |
| 30 | + 2.3 Setting flags | |
| 31 | + 2.4 Attaching processes | |
| 32 | + 3. Questions | |
| 33 | + 4. Contact | |
| 34 | + | |
| 35 | +1. Cpusets | |
| 36 | +========== | |
| 37 | + | |
| 38 | +1.1 What are cpusets ? | |
| 39 | +---------------------- | |
| 40 | + | |
| 41 | +Cpusets provide a mechanism for assigning a set of CPUs and Memory | |
| 42 | +Nodes to a set of tasks. In this document "Memory Node" refers to | |
| 43 | +an on-line node that contains memory. | |
| 44 | + | |
| 45 | +Cpusets constrain the CPU and Memory placement of tasks to only | |
| 46 | +the resources within a task's current cpuset. They form a nested | |
| 47 | +hierarchy visible in a virtual file system. These are the essential | |
| 48 | +hooks, beyond what is already present, required to manage dynamic | |
| 49 | +job placement on large systems. | |
| 50 | + | |
| 51 | +Cpusets use the generic cgroup subsystem described in | |
| 52 | +Documentation/admin-guide/cgroup-v1/cgroups.rst. | |
| 53 | + | |
| 54 | +Requests by a task, using the sched_setaffinity(2) system call to | |
| 55 | +include CPUs in its CPU affinity mask, and using the mbind(2) and | |
| 56 | +set_mempolicy(2) system calls to include Memory Nodes in its memory | |
| 57 | +policy, are both filtered through that task's cpuset, filtering out any | |
| 58 | +CPUs or Memory Nodes not in that cpuset. The scheduler will not | |
| 59 | +schedule a task on a CPU that is not allowed in its cpus_allowed | |
| 60 | +vector, and the kernel page allocator will not allocate a page on a | |
| 61 | +node that is not allowed in the requesting task's mems_allowed vector. | |
| 62 | + | |
| 63 | +User level code may create and destroy cpusets by name in the cgroup | |
| 64 | +virtual file system, manage the attributes and permissions of these | |
| 65 | +cpusets and which CPUs and Memory Nodes are assigned to each cpuset, | |
| 66 | +specify and query to which cpuset a task is assigned, and list the | |
| 67 | +task pids assigned to a cpuset. | |
| 68 | + | |
| 69 | + | |
| 70 | +1.2 Why are cpusets needed ? | |
| 71 | +---------------------------- | |
| 72 | + | |
| 73 | +The management of large computer systems, with many processors (CPUs), | |
| 74 | +complex memory cache hierarchies and multiple Memory Nodes having | |
| 75 | +non-uniform access times (NUMA) presents additional challenges for | |
| 76 | +the efficient scheduling and memory placement of processes. | |
| 77 | + | |
| 78 | +Frequently more modest sized systems can be operated with adequate | |
| 79 | +efficiency just by letting the operating system automatically share | |
| 80 | +the available CPU and Memory resources amongst the requesting tasks. | |
| 81 | + | |
| 82 | +But larger systems, which benefit more from careful processor and | |
| 83 | +memory placement to reduce memory access times and contention, | |
| 84 | +and which typically represent a larger investment for the customer, | |
| 85 | +can benefit from explicitly placing jobs on properly sized subsets of | |
| 86 | +the system. | |
| 87 | + | |
| 88 | +This can be especially valuable on: | |
| 89 | + | |
| 90 | + * Web Servers running multiple instances of the same web application, | |
| 91 | + * Servers running different applications (for instance, a web server | |
| 92 | + and a database), or | |
| 93 | + * NUMA systems running large HPC applications with demanding | |
| 94 | + performance characteristics. | |
| 95 | + | |
| 96 | +These subsets, or "soft partitions" must be able to be dynamically | |
| 97 | +adjusted, as the job mix changes, without impacting other concurrently | |
| 98 | +executing jobs. The location of the running jobs pages may also be moved | |
| 99 | +when the memory locations are changed. | |
| 100 | + | |
| 101 | +The kernel cpuset patch provides the minimum essential kernel | |
| 102 | +mechanisms required to efficiently implement such subsets. It | |
| 103 | +leverages existing CPU and Memory Placement facilities in the Linux | |
| 104 | +kernel to avoid any additional impact on the critical scheduler or | |
| 105 | +memory allocator code. | |
| 106 | + | |
| 107 | + | |
| 108 | +1.3 How are cpusets implemented ? | |
| 109 | +--------------------------------- | |
| 110 | + | |
| 111 | +Cpusets provide a Linux kernel mechanism to constrain which CPUs and | |
| 112 | +Memory Nodes are used by a process or set of processes. | |
| 113 | + | |
| 114 | +The Linux kernel already has a pair of mechanisms to specify on which | |
| 115 | +CPUs a task may be scheduled (sched_setaffinity) and on which Memory | |
| 116 | +Nodes it may obtain memory (mbind, set_mempolicy). | |
| 117 | + | |
| 118 | +Cpusets extends these two mechanisms as follows: | |
| 119 | + | |
| 120 | + - Cpusets are sets of allowed CPUs and Memory Nodes, known to the | |
| 121 | + kernel. | |
| 122 | + - Each task in the system is attached to a cpuset, via a pointer | |
| 123 | + in the task structure to a reference counted cgroup structure. | |
| 124 | + - Calls to sched_setaffinity are filtered to just those CPUs | |
| 125 | + allowed in that task's cpuset. | |
| 126 | + - Calls to mbind and set_mempolicy are filtered to just | |
| 127 | + those Memory Nodes allowed in that task's cpuset. | |
| 128 | + - The root cpuset contains all the systems CPUs and Memory | |
| 129 | + Nodes. | |
| 130 | + - For any cpuset, one can define child cpusets containing a subset | |
| 131 | + of the parents CPU and Memory Node resources. | |
| 132 | + - The hierarchy of cpusets can be mounted at /dev/cpuset, for | |
| 133 | + browsing and manipulation from user space. | |
| 134 | + - A cpuset may be marked exclusive, which ensures that no other | |
| 135 | + cpuset (except direct ancestors and descendants) may contain | |
| 136 | + any overlapping CPUs or Memory Nodes. | |
| 137 | + - You can list all the tasks (by pid) attached to any cpuset. | |
| 138 | + | |
| 139 | +The implementation of cpusets requires a few, simple hooks | |
| 140 | +into the rest of the kernel, none in performance critical paths: | |
| 141 | + | |
| 142 | + - in init/main.c, to initialize the root cpuset at system boot. | |
| 143 | + - in fork and exit, to attach and detach a task from its cpuset. | |
| 144 | + - in sched_setaffinity, to mask the requested CPUs by what's | |
| 145 | + allowed in that task's cpuset. | |
| 146 | + - in sched.c migrate_live_tasks(), to keep migrating tasks within | |
| 147 | + the CPUs allowed by their cpuset, if possible. | |
| 148 | + - in the mbind and set_mempolicy system calls, to mask the requested | |
| 149 | + Memory Nodes by what's allowed in that task's cpuset. | |
| 150 | + - in page_alloc.c, to restrict memory to allowed nodes. | |
| 151 | + - in vmscan.c, to restrict page recovery to the current cpuset. | |
| 152 | + | |
| 153 | +You should mount the "cgroup" filesystem type in order to enable | |
| 154 | +browsing and modifying the cpusets presently known to the kernel. No | |
| 155 | +new system calls are added for cpusets - all support for querying and | |
| 156 | +modifying cpusets is via this cpuset file system. | |
| 157 | + | |
| 158 | +The /proc/<pid>/status file for each task has four added lines, | |
| 159 | +displaying the task's cpus_allowed (on which CPUs it may be scheduled) | |
| 160 | +and mems_allowed (on which Memory Nodes it may obtain memory), | |
| 161 | +in the two formats seen in the following example:: | |
| 162 | + | |
| 163 | + Cpus_allowed: ffffffff,ffffffff,ffffffff,ffffffff | |
| 164 | + Cpus_allowed_list: 0-127 | |
| 165 | + Mems_allowed: ffffffff,ffffffff | |
| 166 | + Mems_allowed_list: 0-63 | |
| 167 | + | |
| 168 | +Each cpuset is represented by a directory in the cgroup file system | |
| 169 | +containing (on top of the standard cgroup files) the following | |
| 170 | +files describing that cpuset: | |
| 171 | + | |
| 172 | + - cpuset.cpus: list of CPUs in that cpuset | |
| 173 | + - cpuset.mems: list of Memory Nodes in that cpuset | |
| 174 | + - cpuset.memory_migrate flag: if set, move pages to cpusets nodes | |
| 175 | + - cpuset.cpu_exclusive flag: is cpu placement exclusive? | |
| 176 | + - cpuset.mem_exclusive flag: is memory placement exclusive? | |
| 177 | + - cpuset.mem_hardwall flag: is memory allocation hardwalled | |
| 178 | + - cpuset.memory_pressure: measure of how much paging pressure in cpuset | |
| 179 | + - cpuset.memory_spread_page flag: if set, spread page cache evenly on allowed nodes | |
| 180 | + - cpuset.memory_spread_slab flag: if set, spread slab cache evenly on allowed nodes | |
| 181 | + - cpuset.sched_load_balance flag: if set, load balance within CPUs on that cpuset | |
| 182 | + - cpuset.sched_relax_domain_level: the searching range when migrating tasks | |
| 183 | + | |
| 184 | +In addition, only the root cpuset has the following file: | |
| 185 | + | |
| 186 | + - cpuset.memory_pressure_enabled flag: compute memory_pressure? | |
| 187 | + | |
| 188 | +New cpusets are created using the mkdir system call or shell | |
| 189 | +command. The properties of a cpuset, such as its flags, allowed | |
| 190 | +CPUs and Memory Nodes, and attached tasks, are modified by writing | |
| 191 | +to the appropriate file in that cpusets directory, as listed above. | |
| 192 | + | |
| 193 | +The named hierarchical structure of nested cpusets allows partitioning | |
| 194 | +a large system into nested, dynamically changeable, "soft-partitions". | |
| 195 | + | |
| 196 | +The attachment of each task, automatically inherited at fork by any | |
| 197 | +children of that task, to a cpuset allows organizing the work load | |
| 198 | +on a system into related sets of tasks such that each set is constrained | |
| 199 | +to using the CPUs and Memory Nodes of a particular cpuset. A task | |
| 200 | +may be re-attached to any other cpuset, if allowed by the permissions | |
| 201 | +on the necessary cpuset file system directories. | |
| 202 | + | |
| 203 | +Such management of a system "in the large" integrates smoothly with | |
| 204 | +the detailed placement done on individual tasks and memory regions | |
| 205 | +using the sched_setaffinity, mbind and set_mempolicy system calls. | |
| 206 | + | |
| 207 | +The following rules apply to each cpuset: | |
| 208 | + | |
| 209 | + - Its CPUs and Memory Nodes must be a subset of its parents. | |
| 210 | + - It can't be marked exclusive unless its parent is. | |
| 211 | + - If its cpu or memory is exclusive, they may not overlap any sibling. | |
| 212 | + | |
| 213 | +These rules, and the natural hierarchy of cpusets, enable efficient | |
| 214 | +enforcement of the exclusive guarantee, without having to scan all | |
| 215 | +cpusets every time any of them change to ensure nothing overlaps a | |
| 216 | +exclusive cpuset. Also, the use of a Linux virtual file system (vfs) | |
| 217 | +to represent the cpuset hierarchy provides for a familiar permission | |
| 218 | +and name space for cpusets, with a minimum of additional kernel code. | |
| 219 | + | |
| 220 | +The cpus and mems files in the root (top_cpuset) cpuset are | |
| 221 | +read-only. The cpus file automatically tracks the value of | |
| 222 | +cpu_online_mask using a CPU hotplug notifier, and the mems file | |
| 223 | +automatically tracks the value of node_states[N_MEMORY]--i.e., | |
| 224 | +nodes with memory--using the cpuset_track_online_nodes() hook. | |
| 225 | + | |
| 226 | + | |
| 227 | +1.4 What are exclusive cpusets ? | |
| 228 | +-------------------------------- | |
| 229 | + | |
| 230 | +If a cpuset is cpu or mem exclusive, no other cpuset, other than | |
| 231 | +a direct ancestor or descendant, may share any of the same CPUs or | |
| 232 | +Memory Nodes. | |
| 233 | + | |
| 234 | +A cpuset that is cpuset.mem_exclusive *or* cpuset.mem_hardwall is "hardwalled", | |
| 235 | +i.e. it restricts kernel allocations for page, buffer and other data | |
| 236 | +commonly shared by the kernel across multiple users. All cpusets, | |
| 237 | +whether hardwalled or not, restrict allocations of memory for user | |
| 238 | +space. This enables configuring a system so that several independent | |
| 239 | +jobs can share common kernel data, such as file system pages, while | |
| 240 | +isolating each job's user allocation in its own cpuset. To do this, | |
| 241 | +construct a large mem_exclusive cpuset to hold all the jobs, and | |
| 242 | +construct child, non-mem_exclusive cpusets for each individual job. | |
| 243 | +Only a small amount of typical kernel memory, such as requests from | |
| 244 | +interrupt handlers, is allowed to be taken outside even a | |
| 245 | +mem_exclusive cpuset. | |
| 246 | + | |
| 247 | + | |
| 248 | +1.5 What is memory_pressure ? | |
| 249 | +----------------------------- | |
| 250 | +The memory_pressure of a cpuset provides a simple per-cpuset metric | |
| 251 | +of the rate that the tasks in a cpuset are attempting to free up in | |
| 252 | +use memory on the nodes of the cpuset to satisfy additional memory | |
| 253 | +requests. | |
| 254 | + | |
| 255 | +This enables batch managers monitoring jobs running in dedicated | |
| 256 | +cpusets to efficiently detect what level of memory pressure that job | |
| 257 | +is causing. | |
| 258 | + | |
| 259 | +This is useful both on tightly managed systems running a wide mix of | |
| 260 | +submitted jobs, which may choose to terminate or re-prioritize jobs that | |
| 261 | +are trying to use more memory than allowed on the nodes assigned to them, | |
| 262 | +and with tightly coupled, long running, massively parallel scientific | |
| 263 | +computing jobs that will dramatically fail to meet required performance | |
| 264 | +goals if they start to use more memory than allowed to them. | |
| 265 | + | |
| 266 | +This mechanism provides a very economical way for the batch manager | |
| 267 | +to monitor a cpuset for signs of memory pressure. It's up to the | |
| 268 | +batch manager or other user code to decide what to do about it and | |
| 269 | +take action. | |
| 270 | + | |
| 271 | +==> | |
| 272 | + Unless this feature is enabled by writing "1" to the special file | |
| 273 | + /dev/cpuset/memory_pressure_enabled, the hook in the rebalance | |
| 274 | + code of __alloc_pages() for this metric reduces to simply noticing | |
| 275 | + that the cpuset_memory_pressure_enabled flag is zero. So only | |
| 276 | + systems that enable this feature will compute the metric. | |
| 277 | + | |
| 278 | +Why a per-cpuset, running average: | |
| 279 | + | |
| 280 | + Because this meter is per-cpuset, rather than per-task or mm, | |
| 281 | + the system load imposed by a batch scheduler monitoring this | |
| 282 | + metric is sharply reduced on large systems, because a scan of | |
| 283 | + the tasklist can be avoided on each set of queries. | |
| 284 | + | |
| 285 | + Because this meter is a running average, instead of an accumulating | |
| 286 | + counter, a batch scheduler can detect memory pressure with a | |
| 287 | + single read, instead of having to read and accumulate results | |
| 288 | + for a period of time. | |
| 289 | + | |
| 290 | + Because this meter is per-cpuset rather than per-task or mm, | |
| 291 | + the batch scheduler can obtain the key information, memory | |
| 292 | + pressure in a cpuset, with a single read, rather than having to | |
| 293 | + query and accumulate results over all the (dynamically changing) | |
| 294 | + set of tasks in the cpuset. | |
| 295 | + | |
| 296 | +A per-cpuset simple digital filter (requires a spinlock and 3 words | |
| 297 | +of data per-cpuset) is kept, and updated by any task attached to that | |
| 298 | +cpuset, if it enters the synchronous (direct) page reclaim code. | |
| 299 | + | |
| 300 | +A per-cpuset file provides an integer number representing the recent | |
| 301 | +(half-life of 10 seconds) rate of direct page reclaims caused by | |
| 302 | +the tasks in the cpuset, in units of reclaims attempted per second, | |
| 303 | +times 1000. | |
| 304 | + | |
| 305 | + | |
| 306 | +1.6 What is memory spread ? | |
| 307 | +--------------------------- | |
| 308 | +There are two boolean flag files per cpuset that control where the | |
| 309 | +kernel allocates pages for the file system buffers and related in | |
| 310 | +kernel data structures. They are called 'cpuset.memory_spread_page' and | |
| 311 | +'cpuset.memory_spread_slab'. | |
| 312 | + | |
| 313 | +If the per-cpuset boolean flag file 'cpuset.memory_spread_page' is set, then | |
| 314 | +the kernel will spread the file system buffers (page cache) evenly | |
| 315 | +over all the nodes that the faulting task is allowed to use, instead | |
| 316 | +of preferring to put those pages on the node where the task is running. | |
| 317 | + | |
| 318 | +If the per-cpuset boolean flag file 'cpuset.memory_spread_slab' is set, | |
| 319 | +then the kernel will spread some file system related slab caches, | |
| 320 | +such as for inodes and dentries evenly over all the nodes that the | |
| 321 | +faulting task is allowed to use, instead of preferring to put those | |
| 322 | +pages on the node where the task is running. | |
| 323 | + | |
| 324 | +The setting of these flags does not affect anonymous data segment or | |
| 325 | +stack segment pages of a task. | |
| 326 | + | |
| 327 | +By default, both kinds of memory spreading are off, and memory | |
| 328 | +pages are allocated on the node local to where the task is running, | |
| 329 | +except perhaps as modified by the task's NUMA mempolicy or cpuset | |
| 330 | +configuration, so long as sufficient free memory pages are available. | |
| 331 | + | |
| 332 | +When new cpusets are created, they inherit the memory spread settings | |
| 333 | +of their parent. | |
| 334 | + | |
| 335 | +Setting memory spreading causes allocations for the affected page | |
| 336 | +or slab caches to ignore the task's NUMA mempolicy and be spread | |
| 337 | +instead. Tasks using mbind() or set_mempolicy() calls to set NUMA | |
| 338 | +mempolicies will not notice any change in these calls as a result of | |
| 339 | +their containing task's memory spread settings. If memory spreading | |
| 340 | +is turned off, then the currently specified NUMA mempolicy once again | |
| 341 | +applies to memory page allocations. | |
| 342 | + | |
| 343 | +Both 'cpuset.memory_spread_page' and 'cpuset.memory_spread_slab' are boolean flag | |
| 344 | +files. By default they contain "0", meaning that the feature is off | |
| 345 | +for that cpuset. If a "1" is written to that file, then that turns | |
| 346 | +the named feature on. | |
| 347 | + | |
| 348 | +The implementation is simple. | |
| 349 | + | |
| 350 | +Setting the flag 'cpuset.memory_spread_page' turns on a per-process flag | |
| 351 | +PFA_SPREAD_PAGE for each task that is in that cpuset or subsequently | |
| 352 | +joins that cpuset. The page allocation calls for the page cache | |
| 353 | +is modified to perform an inline check for this PFA_SPREAD_PAGE task | |
| 354 | +flag, and if set, a call to a new routine cpuset_mem_spread_node() | |
| 355 | +returns the node to prefer for the allocation. | |
| 356 | + | |
| 357 | +Similarly, setting 'cpuset.memory_spread_slab' turns on the flag | |
| 358 | +PFA_SPREAD_SLAB, and appropriately marked slab caches will allocate | |
| 359 | +pages from the node returned by cpuset_mem_spread_node(). | |
| 360 | + | |
| 361 | +The cpuset_mem_spread_node() routine is also simple. It uses the | |
| 362 | +value of a per-task rotor cpuset_mem_spread_rotor to select the next | |
| 363 | +node in the current task's mems_allowed to prefer for the allocation. | |
| 364 | + | |
| 365 | +This memory placement policy is also known (in other contexts) as | |
| 366 | +round-robin or interleave. | |
| 367 | + | |
| 368 | +This policy can provide substantial improvements for jobs that need | |
| 369 | +to place thread local data on the corresponding node, but that need | |
| 370 | +to access large file system data sets that need to be spread across | |
| 371 | +the several nodes in the jobs cpuset in order to fit. Without this | |
| 372 | +policy, especially for jobs that might have one thread reading in the | |
| 373 | +data set, the memory allocation across the nodes in the jobs cpuset | |
| 374 | +can become very uneven. | |
| 375 | + | |
| 376 | +1.7 What is sched_load_balance ? | |
| 377 | +-------------------------------- | |
| 378 | + | |
| 379 | +The kernel scheduler (kernel/sched/core.c) automatically load balances | |
| 380 | +tasks. If one CPU is underutilized, kernel code running on that | |
| 381 | +CPU will look for tasks on other more overloaded CPUs and move those | |
| 382 | +tasks to itself, within the constraints of such placement mechanisms | |
| 383 | +as cpusets and sched_setaffinity. | |
| 384 | + | |
| 385 | +The algorithmic cost of load balancing and its impact on key shared | |
| 386 | +kernel data structures such as the task list increases more than | |
| 387 | +linearly with the number of CPUs being balanced. So the scheduler | |
| 388 | +has support to partition the systems CPUs into a number of sched | |
| 389 | +domains such that it only load balances within each sched domain. | |
| 390 | +Each sched domain covers some subset of the CPUs in the system; | |
| 391 | +no two sched domains overlap; some CPUs might not be in any sched | |
| 392 | +domain and hence won't be load balanced. | |
| 393 | + | |
| 394 | +Put simply, it costs less to balance between two smaller sched domains | |
| 395 | +than one big one, but doing so means that overloads in one of the | |
| 396 | +two domains won't be load balanced to the other one. | |
| 397 | + | |
| 398 | +By default, there is one sched domain covering all CPUs, including those | |
| 399 | +marked isolated using the kernel boot time "isolcpus=" argument. However, | |
| 400 | +the isolated CPUs will not participate in load balancing, and will not | |
| 401 | +have tasks running on them unless explicitly assigned. | |
| 402 | + | |
| 403 | +This default load balancing across all CPUs is not well suited for | |
| 404 | +the following two situations: | |
| 405 | + | |
| 406 | + 1) On large systems, load balancing across many CPUs is expensive. | |
| 407 | + If the system is managed using cpusets to place independent jobs | |
| 408 | + on separate sets of CPUs, full load balancing is unnecessary. | |
| 409 | + 2) Systems supporting realtime on some CPUs need to minimize | |
| 410 | + system overhead on those CPUs, including avoiding task load | |
| 411 | + balancing if that is not needed. | |
| 412 | + | |
| 413 | +When the per-cpuset flag "cpuset.sched_load_balance" is enabled (the default | |
| 414 | +setting), it requests that all the CPUs in that cpusets allowed 'cpuset.cpus' | |
| 415 | +be contained in a single sched domain, ensuring that load balancing | |
| 416 | +can move a task (not otherwised pinned, as by sched_setaffinity) | |
| 417 | +from any CPU in that cpuset to any other. | |
| 418 | + | |
| 419 | +When the per-cpuset flag "cpuset.sched_load_balance" is disabled, then the | |
| 420 | +scheduler will avoid load balancing across the CPUs in that cpuset, | |
| 421 | +--except-- in so far as is necessary because some overlapping cpuset | |
| 422 | +has "sched_load_balance" enabled. | |
| 423 | + | |
| 424 | +So, for example, if the top cpuset has the flag "cpuset.sched_load_balance" | |
| 425 | +enabled, then the scheduler will have one sched domain covering all | |
| 426 | +CPUs, and the setting of the "cpuset.sched_load_balance" flag in any other | |
| 427 | +cpusets won't matter, as we're already fully load balancing. | |
| 428 | + | |
| 429 | +Therefore in the above two situations, the top cpuset flag | |
| 430 | +"cpuset.sched_load_balance" should be disabled, and only some of the smaller, | |
| 431 | +child cpusets have this flag enabled. | |
| 432 | + | |
| 433 | +When doing this, you don't usually want to leave any unpinned tasks in | |
| 434 | +the top cpuset that might use non-trivial amounts of CPU, as such tasks | |
| 435 | +may be artificially constrained to some subset of CPUs, depending on | |
| 436 | +the particulars of this flag setting in descendant cpusets. Even if | |
| 437 | +such a task could use spare CPU cycles in some other CPUs, the kernel | |
| 438 | +scheduler might not consider the possibility of load balancing that | |
| 439 | +task to that underused CPU. | |
| 440 | + | |
| 441 | +Of course, tasks pinned to a particular CPU can be left in a cpuset | |
| 442 | +that disables "cpuset.sched_load_balance" as those tasks aren't going anywhere | |
| 443 | +else anyway. | |
| 444 | + | |
| 445 | +There is an impedance mismatch here, between cpusets and sched domains. | |
| 446 | +Cpusets are hierarchical and nest. Sched domains are flat; they don't | |
| 447 | +overlap and each CPU is in at most one sched domain. | |
| 448 | + | |
| 449 | +It is necessary for sched domains to be flat because load balancing | |
| 450 | +across partially overlapping sets of CPUs would risk unstable dynamics | |
| 451 | +that would be beyond our understanding. So if each of two partially | |
| 452 | +overlapping cpusets enables the flag 'cpuset.sched_load_balance', then we | |
| 453 | +form a single sched domain that is a superset of both. We won't move | |
| 454 | +a task to a CPU outside its cpuset, but the scheduler load balancing | |
| 455 | +code might waste some compute cycles considering that possibility. | |
| 456 | + | |
| 457 | +This mismatch is why there is not a simple one-to-one relation | |
| 458 | +between which cpusets have the flag "cpuset.sched_load_balance" enabled, | |
| 459 | +and the sched domain configuration. If a cpuset enables the flag, it | |
| 460 | +will get balancing across all its CPUs, but if it disables the flag, | |
| 461 | +it will only be assured of no load balancing if no other overlapping | |
| 462 | +cpuset enables the flag. | |
| 463 | + | |
| 464 | +If two cpusets have partially overlapping 'cpuset.cpus' allowed, and only | |
| 465 | +one of them has this flag enabled, then the other may find its | |
| 466 | +tasks only partially load balanced, just on the overlapping CPUs. | |
| 467 | +This is just the general case of the top_cpuset example given a few | |
| 468 | +paragraphs above. In the general case, as in the top cpuset case, | |
| 469 | +don't leave tasks that might use non-trivial amounts of CPU in | |
| 470 | +such partially load balanced cpusets, as they may be artificially | |
| 471 | +constrained to some subset of the CPUs allowed to them, for lack of | |
| 472 | +load balancing to the other CPUs. | |
| 473 | + | |
| 474 | +CPUs in "cpuset.isolcpus" were excluded from load balancing by the | |
| 475 | +isolcpus= kernel boot option, and will never be load balanced regardless | |
| 476 | +of the value of "cpuset.sched_load_balance" in any cpuset. | |
| 477 | + | |
| 478 | +1.7.1 sched_load_balance implementation details. | |
| 479 | +------------------------------------------------ | |
| 480 | + | |
| 481 | +The per-cpuset flag 'cpuset.sched_load_balance' defaults to enabled (contrary | |
| 482 | +to most cpuset flags.) When enabled for a cpuset, the kernel will | |
| 483 | +ensure that it can load balance across all the CPUs in that cpuset | |
| 484 | +(makes sure that all the CPUs in the cpus_allowed of that cpuset are | |
| 485 | +in the same sched domain.) | |
| 486 | + | |
| 487 | +If two overlapping cpusets both have 'cpuset.sched_load_balance' enabled, | |
| 488 | +then they will be (must be) both in the same sched domain. | |
| 489 | + | |
| 490 | +If, as is the default, the top cpuset has 'cpuset.sched_load_balance' enabled, | |
| 491 | +then by the above that means there is a single sched domain covering | |
| 492 | +the whole system, regardless of any other cpuset settings. | |
| 493 | + | |
| 494 | +The kernel commits to user space that it will avoid load balancing | |
| 495 | +where it can. It will pick as fine a granularity partition of sched | |
| 496 | +domains as it can while still providing load balancing for any set | |
| 497 | +of CPUs allowed to a cpuset having 'cpuset.sched_load_balance' enabled. | |
| 498 | + | |
| 499 | +The internal kernel cpuset to scheduler interface passes from the | |
| 500 | +cpuset code to the scheduler code a partition of the load balanced | |
| 501 | +CPUs in the system. This partition is a set of subsets (represented | |
| 502 | +as an array of struct cpumask) of CPUs, pairwise disjoint, that cover | |
| 503 | +all the CPUs that must be load balanced. | |
| 504 | + | |
| 505 | +The cpuset code builds a new such partition and passes it to the | |
| 506 | +scheduler sched domain setup code, to have the sched domains rebuilt | |
| 507 | +as necessary, whenever: | |
| 508 | + | |
| 509 | + - the 'cpuset.sched_load_balance' flag of a cpuset with non-empty CPUs changes, | |
| 510 | + - or CPUs come or go from a cpuset with this flag enabled, | |
| 511 | + - or 'cpuset.sched_relax_domain_level' value of a cpuset with non-empty CPUs | |
| 512 | + and with this flag enabled changes, | |
| 513 | + - or a cpuset with non-empty CPUs and with this flag enabled is removed, | |
| 514 | + - or a cpu is offlined/onlined. | |
| 515 | + | |
| 516 | +This partition exactly defines what sched domains the scheduler should | |
| 517 | +setup - one sched domain for each element (struct cpumask) in the | |
| 518 | +partition. | |
| 519 | + | |
| 520 | +The scheduler remembers the currently active sched domain partitions. | |
| 521 | +When the scheduler routine partition_sched_domains() is invoked from | |
| 522 | +the cpuset code to update these sched domains, it compares the new | |
| 523 | +partition requested with the current, and updates its sched domains, | |
| 524 | +removing the old and adding the new, for each change. | |
| 525 | + | |
| 526 | + | |
| 527 | +1.8 What is sched_relax_domain_level ? | |
| 528 | +-------------------------------------- | |
| 529 | + | |
| 530 | +In sched domain, the scheduler migrates tasks in 2 ways; periodic load | |
| 531 | +balance on tick, and at time of some schedule events. | |
| 532 | + | |
| 533 | +When a task is woken up, scheduler try to move the task on idle CPU. | |
| 534 | +For example, if a task A running on CPU X activates another task B | |
| 535 | +on the same CPU X, and if CPU Y is X's sibling and performing idle, | |
| 536 | +then scheduler migrate task B to CPU Y so that task B can start on | |
| 537 | +CPU Y without waiting task A on CPU X. | |
| 538 | + | |
| 539 | +And if a CPU run out of tasks in its runqueue, the CPU try to pull | |
| 540 | +extra tasks from other busy CPUs to help them before it is going to | |
| 541 | +be idle. | |
| 542 | + | |
| 543 | +Of course it takes some searching cost to find movable tasks and/or | |
| 544 | +idle CPUs, the scheduler might not search all CPUs in the domain | |
| 545 | +every time. In fact, in some architectures, the searching ranges on | |
| 546 | +events are limited in the same socket or node where the CPU locates, | |
| 547 | +while the load balance on tick searches all. | |
| 548 | + | |
| 549 | +For example, assume CPU Z is relatively far from CPU X. Even if CPU Z | |
| 550 | +is idle while CPU X and the siblings are busy, scheduler can't migrate | |
| 551 | +woken task B from X to Z since it is out of its searching range. | |
| 552 | +As the result, task B on CPU X need to wait task A or wait load balance | |
| 553 | +on the next tick. For some applications in special situation, waiting | |
| 554 | +1 tick may be too long. | |
| 555 | + | |
| 556 | +The 'cpuset.sched_relax_domain_level' file allows you to request changing | |
| 557 | +this searching range as you like. This file takes int value which | |
| 558 | +indicates size of searching range in levels ideally as follows, | |
| 559 | +otherwise initial value -1 that indicates the cpuset has no request. | |
| 560 | + | |
| 561 | +====== =========================================================== | |
| 562 | + -1 no request. use system default or follow request of others. | |
| 563 | + 0 no search. | |
| 564 | + 1 search siblings (hyperthreads in a core). | |
| 565 | + 2 search cores in a package. | |
| 566 | + 3 search cpus in a node [= system wide on non-NUMA system] | |
| 567 | + 4 search nodes in a chunk of node [on NUMA system] | |
| 568 | + 5 search system wide [on NUMA system] | |
| 569 | +====== =========================================================== | |
| 570 | + | |
| 571 | +The system default is architecture dependent. The system default | |
| 572 | +can be changed using the relax_domain_level= boot parameter. | |
| 573 | + | |
| 574 | +This file is per-cpuset and affect the sched domain where the cpuset | |
| 575 | +belongs to. Therefore if the flag 'cpuset.sched_load_balance' of a cpuset | |
| 576 | +is disabled, then 'cpuset.sched_relax_domain_level' have no effect since | |
| 577 | +there is no sched domain belonging the cpuset. | |
| 578 | + | |
| 579 | +If multiple cpusets are overlapping and hence they form a single sched | |
| 580 | +domain, the largest value among those is used. Be careful, if one | |
| 581 | +requests 0 and others are -1 then 0 is used. | |
| 582 | + | |
| 583 | +Note that modifying this file will have both good and bad effects, | |
| 584 | +and whether it is acceptable or not depends on your situation. | |
| 585 | +Don't modify this file if you are not sure. | |
| 586 | + | |
| 587 | +If your situation is: | |
| 588 | + | |
| 589 | + - The migration costs between each cpu can be assumed considerably | |
| 590 | + small(for you) due to your special application's behavior or | |
| 591 | + special hardware support for CPU cache etc. | |
| 592 | + - The searching cost doesn't have impact(for you) or you can make | |
| 593 | + the searching cost enough small by managing cpuset to compact etc. | |
| 594 | + - The latency is required even it sacrifices cache hit rate etc. | |
| 595 | + then increasing 'sched_relax_domain_level' would benefit you. | |
| 596 | + | |
| 597 | + | |
| 598 | +1.9 How do I use cpusets ? | |
| 599 | +-------------------------- | |
| 600 | + | |
| 601 | +In order to minimize the impact of cpusets on critical kernel | |
| 602 | +code, such as the scheduler, and due to the fact that the kernel | |
| 603 | +does not support one task updating the memory placement of another | |
| 604 | +task directly, the impact on a task of changing its cpuset CPU | |
| 605 | +or Memory Node placement, or of changing to which cpuset a task | |
| 606 | +is attached, is subtle. | |
| 607 | + | |
| 608 | +If a cpuset has its Memory Nodes modified, then for each task attached | |
| 609 | +to that cpuset, the next time that the kernel attempts to allocate | |
| 610 | +a page of memory for that task, the kernel will notice the change | |
| 611 | +in the task's cpuset, and update its per-task memory placement to | |
| 612 | +remain within the new cpusets memory placement. If the task was using | |
| 613 | +mempolicy MPOL_BIND, and the nodes to which it was bound overlap with | |
| 614 | +its new cpuset, then the task will continue to use whatever subset | |
| 615 | +of MPOL_BIND nodes are still allowed in the new cpuset. If the task | |
| 616 | +was using MPOL_BIND and now none of its MPOL_BIND nodes are allowed | |
| 617 | +in the new cpuset, then the task will be essentially treated as if it | |
| 618 | +was MPOL_BIND bound to the new cpuset (even though its NUMA placement, | |
| 619 | +as queried by get_mempolicy(), doesn't change). If a task is moved | |
| 620 | +from one cpuset to another, then the kernel will adjust the task's | |
| 621 | +memory placement, as above, the next time that the kernel attempts | |
| 622 | +to allocate a page of memory for that task. | |
| 623 | + | |
| 624 | +If a cpuset has its 'cpuset.cpus' modified, then each task in that cpuset | |
| 625 | +will have its allowed CPU placement changed immediately. Similarly, | |
| 626 | +if a task's pid is written to another cpuset's 'tasks' file, then its | |
| 627 | +allowed CPU placement is changed immediately. If such a task had been | |
| 628 | +bound to some subset of its cpuset using the sched_setaffinity() call, | |
| 629 | +the task will be allowed to run on any CPU allowed in its new cpuset, | |
| 630 | +negating the effect of the prior sched_setaffinity() call. | |
| 631 | + | |
| 632 | +In summary, the memory placement of a task whose cpuset is changed is | |
| 633 | +updated by the kernel, on the next allocation of a page for that task, | |
| 634 | +and the processor placement is updated immediately. | |
| 635 | + | |
| 636 | +Normally, once a page is allocated (given a physical page | |
| 637 | +of main memory) then that page stays on whatever node it | |
| 638 | +was allocated, so long as it remains allocated, even if the | |
| 639 | +cpusets memory placement policy 'cpuset.mems' subsequently changes. | |
| 640 | +If the cpuset flag file 'cpuset.memory_migrate' is set true, then when | |
| 641 | +tasks are attached to that cpuset, any pages that task had | |
| 642 | +allocated to it on nodes in its previous cpuset are migrated | |
| 643 | +to the task's new cpuset. The relative placement of the page within | |
| 644 | +the cpuset is preserved during these migration operations if possible. | |
| 645 | +For example if the page was on the second valid node of the prior cpuset | |
| 646 | +then the page will be placed on the second valid node of the new cpuset. | |
| 647 | + | |
| 648 | +Also if 'cpuset.memory_migrate' is set true, then if that cpuset's | |
| 649 | +'cpuset.mems' file is modified, pages allocated to tasks in that | |
| 650 | +cpuset, that were on nodes in the previous setting of 'cpuset.mems', | |
| 651 | +will be moved to nodes in the new setting of 'mems.' | |
| 652 | +Pages that were not in the task's prior cpuset, or in the cpuset's | |
| 653 | +prior 'cpuset.mems' setting, will not be moved. | |
| 654 | + | |
| 655 | +There is an exception to the above. If hotplug functionality is used | |
| 656 | +to remove all the CPUs that are currently assigned to a cpuset, | |
| 657 | +then all the tasks in that cpuset will be moved to the nearest ancestor | |
| 658 | +with non-empty cpus. But the moving of some (or all) tasks might fail if | |
| 659 | +cpuset is bound with another cgroup subsystem which has some restrictions | |
| 660 | +on task attaching. In this failing case, those tasks will stay | |
| 661 | +in the original cpuset, and the kernel will automatically update | |
| 662 | +their cpus_allowed to allow all online CPUs. When memory hotplug | |
| 663 | +functionality for removing Memory Nodes is available, a similar exception | |
| 664 | +is expected to apply there as well. In general, the kernel prefers to | |
| 665 | +violate cpuset placement, over starving a task that has had all | |
| 666 | +its allowed CPUs or Memory Nodes taken offline. | |
| 667 | + | |
| 668 | +There is a second exception to the above. GFP_ATOMIC requests are | |
| 669 | +kernel internal allocations that must be satisfied, immediately. | |
| 670 | +The kernel may drop some request, in rare cases even panic, if a | |
| 671 | +GFP_ATOMIC alloc fails. If the request cannot be satisfied within | |
| 672 | +the current task's cpuset, then we relax the cpuset, and look for | |
| 673 | +memory anywhere we can find it. It's better to violate the cpuset | |
| 674 | +than stress the kernel. | |
| 675 | + | |
| 676 | +To start a new job that is to be contained within a cpuset, the steps are: | |
| 677 | + | |
| 678 | + 1) mkdir /sys/fs/cgroup/cpuset | |
| 679 | + 2) mount -t cgroup -ocpuset cpuset /sys/fs/cgroup/cpuset | |
| 680 | + 3) Create the new cpuset by doing mkdir's and write's (or echo's) in | |
| 681 | + the /sys/fs/cgroup/cpuset virtual file system. | |
| 682 | + 4) Start a task that will be the "founding father" of the new job. | |
| 683 | + 5) Attach that task to the new cpuset by writing its pid to the | |
| 684 | + /sys/fs/cgroup/cpuset tasks file for that cpuset. | |
| 685 | + 6) fork, exec or clone the job tasks from this founding father task. | |
| 686 | + | |
| 687 | +For example, the following sequence of commands will setup a cpuset | |
| 688 | +named "Charlie", containing just CPUs 2 and 3, and Memory Node 1, | |
| 689 | +and then start a subshell 'sh' in that cpuset:: | |
| 690 | + | |
| 691 | + mount -t cgroup -ocpuset cpuset /sys/fs/cgroup/cpuset | |
| 692 | + cd /sys/fs/cgroup/cpuset | |
| 693 | + mkdir Charlie | |
| 694 | + cd Charlie | |
| 695 | + /bin/echo 2-3 > cpuset.cpus | |
| 696 | + /bin/echo 1 > cpuset.mems | |
| 697 | + /bin/echo $$ > tasks | |
| 698 | + sh | |
| 699 | + # The subshell 'sh' is now running in cpuset Charlie | |
| 700 | + # The next line should display '/Charlie' | |
| 701 | + cat /proc/self/cpuset | |
| 702 | + | |
| 703 | +There are ways to query or modify cpusets: | |
| 704 | + | |
| 705 | + - via the cpuset file system directly, using the various cd, mkdir, echo, | |
| 706 | + cat, rmdir commands from the shell, or their equivalent from C. | |
| 707 | + - via the C library libcpuset. | |
| 708 | + - via the C library libcgroup. | |
| 709 | + (http://sourceforge.net/projects/libcg/) | |
| 710 | + - via the python application cset. | |
| 711 | + (http://code.google.com/p/cpuset/) | |
| 712 | + | |
| 713 | +The sched_setaffinity calls can also be done at the shell prompt using | |
| 714 | +SGI's runon or Robert Love's taskset. The mbind and set_mempolicy | |
| 715 | +calls can be done at the shell prompt using the numactl command | |
| 716 | +(part of Andi Kleen's numa package). | |
| 717 | + | |
| 718 | +2. Usage Examples and Syntax | |
| 719 | +============================ | |
| 720 | + | |
| 721 | +2.1 Basic Usage | |
| 722 | +--------------- | |
| 723 | + | |
| 724 | +Creating, modifying, using the cpusets can be done through the cpuset | |
| 725 | +virtual filesystem. | |
| 726 | + | |
| 727 | +To mount it, type: | |
| 728 | +# mount -t cgroup -o cpuset cpuset /sys/fs/cgroup/cpuset | |
| 729 | + | |
| 730 | +Then under /sys/fs/cgroup/cpuset you can find a tree that corresponds to the | |
| 731 | +tree of the cpusets in the system. For instance, /sys/fs/cgroup/cpuset | |
| 732 | +is the cpuset that holds the whole system. | |
| 733 | + | |
| 734 | +If you want to create a new cpuset under /sys/fs/cgroup/cpuset:: | |
| 735 | + | |
| 736 | + # cd /sys/fs/cgroup/cpuset | |
| 737 | + # mkdir my_cpuset | |
| 738 | + | |
| 739 | +Now you want to do something with this cpuset:: | |
| 740 | + | |
| 741 | + # cd my_cpuset | |
| 742 | + | |
| 743 | +In this directory you can find several files:: | |
| 744 | + | |
| 745 | + # ls | |
| 746 | + cgroup.clone_children cpuset.memory_pressure | |
| 747 | + cgroup.event_control cpuset.memory_spread_page | |
| 748 | + cgroup.procs cpuset.memory_spread_slab | |
| 749 | + cpuset.cpu_exclusive cpuset.mems | |
| 750 | + cpuset.cpus cpuset.sched_load_balance | |
| 751 | + cpuset.mem_exclusive cpuset.sched_relax_domain_level | |
| 752 | + cpuset.mem_hardwall notify_on_release | |
| 753 | + cpuset.memory_migrate tasks | |
| 754 | + | |
| 755 | +Reading them will give you information about the state of this cpuset: | |
| 756 | +the CPUs and Memory Nodes it can use, the processes that are using | |
| 757 | +it, its properties. By writing to these files you can manipulate | |
| 758 | +the cpuset. | |
| 759 | + | |
| 760 | +Set some flags:: | |
| 761 | + | |
| 762 | + # /bin/echo 1 > cpuset.cpu_exclusive | |
| 763 | + | |
| 764 | +Add some cpus:: | |
| 765 | + | |
| 766 | + # /bin/echo 0-7 > cpuset.cpus | |
| 767 | + | |
| 768 | +Add some mems:: | |
| 769 | + | |
| 770 | + # /bin/echo 0-7 > cpuset.mems | |
| 771 | + | |
| 772 | +Now attach your shell to this cpuset:: | |
| 773 | + | |
| 774 | + # /bin/echo $$ > tasks | |
| 775 | + | |
| 776 | +You can also create cpusets inside your cpuset by using mkdir in this | |
| 777 | +directory:: | |
| 778 | + | |
| 779 | + # mkdir my_sub_cs | |
| 780 | + | |
| 781 | +To remove a cpuset, just use rmdir:: | |
| 782 | + | |
| 783 | + # rmdir my_sub_cs | |
| 784 | + | |
| 785 | +This will fail if the cpuset is in use (has cpusets inside, or has | |
| 786 | +processes attached). | |
| 787 | + | |
| 788 | +Note that for legacy reasons, the "cpuset" filesystem exists as a | |
| 789 | +wrapper around the cgroup filesystem. | |
| 790 | + | |
| 791 | +The command:: | |
| 792 | + | |
| 793 | + mount -t cpuset X /sys/fs/cgroup/cpuset | |
| 794 | + | |
| 795 | +is equivalent to:: | |
| 796 | + | |
| 797 | + mount -t cgroup -ocpuset,noprefix X /sys/fs/cgroup/cpuset | |
| 798 | + echo "/sbin/cpuset_release_agent" > /sys/fs/cgroup/cpuset/release_agent | |
| 799 | + | |
| 800 | +2.2 Adding/removing cpus | |
| 801 | +------------------------ | |
| 802 | + | |
| 803 | +This is the syntax to use when writing in the cpus or mems files | |
| 804 | +in cpuset directories:: | |
| 805 | + | |
| 806 | + # /bin/echo 1-4 > cpuset.cpus -> set cpus list to cpus 1,2,3,4 | |
| 807 | + # /bin/echo 1,2,3,4 > cpuset.cpus -> set cpus list to cpus 1,2,3,4 | |
| 808 | + | |
| 809 | +To add a CPU to a cpuset, write the new list of CPUs including the | |
| 810 | +CPU to be added. To add 6 to the above cpuset:: | |
| 811 | + | |
| 812 | + # /bin/echo 1-4,6 > cpuset.cpus -> set cpus list to cpus 1,2,3,4,6 | |
| 813 | + | |
| 814 | +Similarly to remove a CPU from a cpuset, write the new list of CPUs | |
| 815 | +without the CPU to be removed. | |
| 816 | + | |
| 817 | +To remove all the CPUs:: | |
| 818 | + | |
| 819 | + # /bin/echo "" > cpuset.cpus -> clear cpus list | |
| 820 | + | |
| 821 | +2.3 Setting flags | |
| 822 | +----------------- | |
| 823 | + | |
| 824 | +The syntax is very simple:: | |
| 825 | + | |
| 826 | + # /bin/echo 1 > cpuset.cpu_exclusive -> set flag 'cpuset.cpu_exclusive' | |
| 827 | + # /bin/echo 0 > cpuset.cpu_exclusive -> unset flag 'cpuset.cpu_exclusive' | |
| 828 | + | |
| 829 | +2.4 Attaching processes | |
| 830 | +----------------------- | |
| 831 | + | |
| 832 | +:: | |
| 833 | + | |
| 834 | + # /bin/echo PID > tasks | |
| 835 | + | |
| 836 | +Note that it is PID, not PIDs. You can only attach ONE task at a time. | |
| 837 | +If you have several tasks to attach, you have to do it one after another:: | |
| 838 | + | |
| 839 | + # /bin/echo PID1 > tasks | |
| 840 | + # /bin/echo PID2 > tasks | |
| 841 | + ... | |
| 842 | + # /bin/echo PIDn > tasks | |
| 843 | + | |
| 844 | + | |
| 845 | +3. Questions | |
| 846 | +============ | |
| 847 | + | |
| 848 | +Q: | |
| 849 | + what's up with this '/bin/echo' ? | |
| 850 | + | |
| 851 | +A: | |
| 852 | + bash's builtin 'echo' command does not check calls to write() against | |
| 853 | + errors. If you use it in the cpuset file system, you won't be | |
| 854 | + able to tell whether a command succeeded or failed. | |
| 855 | + | |
| 856 | +Q: | |
| 857 | + When I attach processes, only the first of the line gets really attached ! | |
| 858 | + | |
| 859 | +A: | |
| 860 | + We can only return one error code per call to write(). So you should also | |
| 861 | + put only ONE pid. | |
| 862 | + | |
| 863 | +4. Contact | |
| 864 | +========== | |
| 865 | + | |
| 866 | +Web: http://www.bullopensource.org/cpuset | |
| @@ -0,0 +1,132 @@ | ||
| 1 | +=========================== | |
| 2 | +Device Whitelist Controller | |
| 3 | +=========================== | |
| 4 | + | |
| 5 | +1. Description | |
| 6 | +============== | |
| 7 | + | |
| 8 | +Implement a cgroup to track and enforce open and mknod restrictions | |
| 9 | +on device files. A device cgroup associates a device access | |
| 10 | +whitelist with each cgroup. A whitelist entry has 4 fields. | |
| 11 | +'type' is a (all), c (char), or b (block). 'all' means it applies | |
| 12 | +to all types and all major and minor numbers. Major and minor are | |
| 13 | +either an integer or * for all. Access is a composition of r | |
| 14 | +(read), w (write), and m (mknod). | |
| 15 | + | |
| 16 | +The root device cgroup starts with rwm to 'all'. A child device | |
| 17 | +cgroup gets a copy of the parent. Administrators can then remove | |
| 18 | +devices from the whitelist or add new entries. A child cgroup can | |
| 19 | +never receive a device access which is denied by its parent. | |
| 20 | + | |
| 21 | +2. User Interface | |
| 22 | +================= | |
| 23 | + | |
| 24 | +An entry is added using devices.allow, and removed using | |
| 25 | +devices.deny. For instance:: | |
| 26 | + | |
| 27 | + echo 'c 1:3 mr' > /sys/fs/cgroup/1/devices.allow | |
| 28 | + | |
| 29 | +allows cgroup 1 to read and mknod the device usually known as | |
| 30 | +/dev/null. Doing:: | |
| 31 | + | |
| 32 | + echo a > /sys/fs/cgroup/1/devices.deny | |
| 33 | + | |
| 34 | +will remove the default 'a *:* rwm' entry. Doing:: | |
| 35 | + | |
| 36 | + echo a > /sys/fs/cgroup/1/devices.allow | |
| 37 | + | |
| 38 | +will add the 'a *:* rwm' entry to the whitelist. | |
| 39 | + | |
| 40 | +3. Security | |
| 41 | +=========== | |
| 42 | + | |
| 43 | +Any task can move itself between cgroups. This clearly won't | |
| 44 | +suffice, but we can decide the best way to adequately restrict | |
| 45 | +movement as people get some experience with this. We may just want | |
| 46 | +to require CAP_SYS_ADMIN, which at least is a separate bit from | |
| 47 | +CAP_MKNOD. We may want to just refuse moving to a cgroup which | |
| 48 | +isn't a descendant of the current one. Or we may want to use | |
| 49 | +CAP_MAC_ADMIN, since we really are trying to lock down root. | |
| 50 | + | |
| 51 | +CAP_SYS_ADMIN is needed to modify the whitelist or move another | |
| 52 | +task to a new cgroup. (Again we'll probably want to change that). | |
| 53 | + | |
| 54 | +A cgroup may not be granted more permissions than the cgroup's | |
| 55 | +parent has. | |
| 56 | + | |
| 57 | +4. Hierarchy | |
| 58 | +============ | |
| 59 | + | |
| 60 | +device cgroups maintain hierarchy by making sure a cgroup never has more | |
| 61 | +access permissions than its parent. Every time an entry is written to | |
| 62 | +a cgroup's devices.deny file, all its children will have that entry removed | |
| 63 | +from their whitelist and all the locally set whitelist entries will be | |
| 64 | +re-evaluated. In case one of the locally set whitelist entries would provide | |
| 65 | +more access than the cgroup's parent, it'll be removed from the whitelist. | |
| 66 | + | |
| 67 | +Example:: | |
| 68 | + | |
| 69 | + A | |
| 70 | + / \ | |
| 71 | + B | |
| 72 | + | |
| 73 | + group behavior exceptions | |
| 74 | + A allow "b 8:* rwm", "c 116:1 rw" | |
| 75 | + B deny "c 1:3 rwm", "c 116:2 rwm", "b 3:* rwm" | |
| 76 | + | |
| 77 | +If a device is denied in group A:: | |
| 78 | + | |
| 79 | + # echo "c 116:* r" > A/devices.deny | |
| 80 | + | |
| 81 | +it'll propagate down and after revalidating B's entries, the whitelist entry | |
| 82 | +"c 116:2 rwm" will be removed:: | |
| 83 | + | |
| 84 | + group whitelist entries denied devices | |
| 85 | + A all "b 8:* rwm", "c 116:* rw" | |
| 86 | + B "c 1:3 rwm", "b 3:* rwm" all the rest | |
| 87 | + | |
| 88 | +In case parent's exceptions change and local exceptions are not allowed | |
| 89 | +anymore, they'll be deleted. | |
| 90 | + | |
| 91 | +Notice that new whitelist entries will not be propagated:: | |
| 92 | + | |
| 93 | + A | |
| 94 | + / \ | |
| 95 | + B | |
| 96 | + | |
| 97 | + group whitelist entries denied devices | |
| 98 | + A "c 1:3 rwm", "c 1:5 r" all the rest | |
| 99 | + B "c 1:3 rwm", "c 1:5 r" all the rest | |
| 100 | + | |
| 101 | +when adding ``c *:3 rwm``:: | |
| 102 | + | |
| 103 | + # echo "c *:3 rwm" >A/devices.allow | |
| 104 | + | |
| 105 | +the result:: | |
| 106 | + | |
| 107 | + group whitelist entries denied devices | |
| 108 | + A "c *:3 rwm", "c 1:5 r" all the rest | |
| 109 | + B "c 1:3 rwm", "c 1:5 r" all the rest | |
| 110 | + | |
| 111 | +but now it'll be possible to add new entries to B:: | |
| 112 | + | |
| 113 | + # echo "c 2:3 rwm" >B/devices.allow | |
| 114 | + # echo "c 50:3 r" >B/devices.allow | |
| 115 | + | |
| 116 | +or even:: | |
| 117 | + | |
| 118 | + # echo "c *:3 rwm" >B/devices.allow | |
| 119 | + | |
| 120 | +Allowing or denying all by writing 'a' to devices.allow or devices.deny will | |
| 121 | +not be possible once the device cgroups has children. | |
| 122 | + | |
| 123 | +4.1 Hierarchy (internal implementation) | |
| 124 | +--------------------------------------- | |
| 125 | + | |
| 126 | +device cgroups is implemented internally using a behavior (ALLOW, DENY) and a | |
| 127 | +list of exceptions. The internal state is controlled using the same user | |
| 128 | +interface to preserve compatibility with the previous whitelist-only | |
| 129 | +implementation. Removal or addition of exceptions that will reduce the access | |
| 130 | +to devices will be propagated down the hierarchy. | |
| 131 | +For every propagated exception, the effective rules will be re-evaluated based | |
| 132 | +on current parent's access rules. | |
| @@ -0,0 +1,127 @@ | ||
| 1 | +============== | |
| 2 | +Cgroup Freezer | |
| 3 | +============== | |
| 4 | + | |
| 5 | +The cgroup freezer is useful to batch job management system which start | |
| 6 | +and stop sets of tasks in order to schedule the resources of a machine | |
| 7 | +according to the desires of a system administrator. This sort of program | |
| 8 | +is often used on HPC clusters to schedule access to the cluster as a | |
| 9 | +whole. The cgroup freezer uses cgroups to describe the set of tasks to | |
| 10 | +be started/stopped by the batch job management system. It also provides | |
| 11 | +a means to start and stop the tasks composing the job. | |
| 12 | + | |
| 13 | +The cgroup freezer will also be useful for checkpointing running groups | |
| 14 | +of tasks. The freezer allows the checkpoint code to obtain a consistent | |
| 15 | +image of the tasks by attempting to force the tasks in a cgroup into a | |
| 16 | +quiescent state. Once the tasks are quiescent another task can | |
| 17 | +walk /proc or invoke a kernel interface to gather information about the | |
| 18 | +quiesced tasks. Checkpointed tasks can be restarted later should a | |
| 19 | +recoverable error occur. This also allows the checkpointed tasks to be | |
| 20 | +migrated between nodes in a cluster by copying the gathered information | |
| 21 | +to another node and restarting the tasks there. | |
| 22 | + | |
| 23 | +Sequences of SIGSTOP and SIGCONT are not always sufficient for stopping | |
| 24 | +and resuming tasks in userspace. Both of these signals are observable | |
| 25 | +from within the tasks we wish to freeze. While SIGSTOP cannot be caught, | |
| 26 | +blocked, or ignored it can be seen by waiting or ptracing parent tasks. | |
| 27 | +SIGCONT is especially unsuitable since it can be caught by the task. Any | |
| 28 | +programs designed to watch for SIGSTOP and SIGCONT could be broken by | |
| 29 | +attempting to use SIGSTOP and SIGCONT to stop and resume tasks. We can | |
| 30 | +demonstrate this problem using nested bash shells:: | |
| 31 | + | |
| 32 | + $ echo $$ | |
| 33 | + 16644 | |
| 34 | + $ bash | |
| 35 | + $ echo $$ | |
| 36 | + 16690 | |
| 37 | + | |
| 38 | + From a second, unrelated bash shell: | |
| 39 | + $ kill -SIGSTOP 16690 | |
| 40 | + $ kill -SIGCONT 16690 | |
| 41 | + | |
| 42 | + <at this point 16690 exits and causes 16644 to exit too> | |
| 43 | + | |
| 44 | +This happens because bash can observe both signals and choose how it | |
| 45 | +responds to them. | |
| 46 | + | |
| 47 | +Another example of a program which catches and responds to these | |
| 48 | +signals is gdb. In fact any program designed to use ptrace is likely to | |
| 49 | +have a problem with this method of stopping and resuming tasks. | |
| 50 | + | |
| 51 | +In contrast, the cgroup freezer uses the kernel freezer code to | |
| 52 | +prevent the freeze/unfreeze cycle from becoming visible to the tasks | |
| 53 | +being frozen. This allows the bash example above and gdb to run as | |
| 54 | +expected. | |
| 55 | + | |
| 56 | +The cgroup freezer is hierarchical. Freezing a cgroup freezes all | |
| 57 | +tasks belonging to the cgroup and all its descendant cgroups. Each | |
| 58 | +cgroup has its own state (self-state) and the state inherited from the | |
| 59 | +parent (parent-state). Iff both states are THAWED, the cgroup is | |
| 60 | +THAWED. | |
| 61 | + | |
| 62 | +The following cgroupfs files are created by cgroup freezer. | |
| 63 | + | |
| 64 | +* freezer.state: Read-write. | |
| 65 | + | |
| 66 | + When read, returns the effective state of the cgroup - "THAWED", | |
| 67 | + "FREEZING" or "FROZEN". This is the combined self and parent-states. | |
| 68 | + If any is freezing, the cgroup is freezing (FREEZING or FROZEN). | |
| 69 | + | |
| 70 | + FREEZING cgroup transitions into FROZEN state when all tasks | |
| 71 | + belonging to the cgroup and its descendants become frozen. Note that | |
| 72 | + a cgroup reverts to FREEZING from FROZEN after a new task is added | |
| 73 | + to the cgroup or one of its descendant cgroups until the new task is | |
| 74 | + frozen. | |
| 75 | + | |
| 76 | + When written, sets the self-state of the cgroup. Two values are | |
| 77 | + allowed - "FROZEN" and "THAWED". If FROZEN is written, the cgroup, | |
| 78 | + if not already freezing, enters FREEZING state along with all its | |
| 79 | + descendant cgroups. | |
| 80 | + | |
| 81 | + If THAWED is written, the self-state of the cgroup is changed to | |
| 82 | + THAWED. Note that the effective state may not change to THAWED if | |
| 83 | + the parent-state is still freezing. If a cgroup's effective state | |
| 84 | + becomes THAWED, all its descendants which are freezing because of | |
| 85 | + the cgroup also leave the freezing state. | |
| 86 | + | |
| 87 | +* freezer.self_freezing: Read only. | |
| 88 | + | |
| 89 | + Shows the self-state. 0 if the self-state is THAWED; otherwise, 1. | |
| 90 | + This value is 1 iff the last write to freezer.state was "FROZEN". | |
| 91 | + | |
| 92 | +* freezer.parent_freezing: Read only. | |
| 93 | + | |
| 94 | + Shows the parent-state. 0 if none of the cgroup's ancestors is | |
| 95 | + frozen; otherwise, 1. | |
| 96 | + | |
| 97 | +The root cgroup is non-freezable and the above interface files don't | |
| 98 | +exist. | |
| 99 | + | |
| 100 | +* Examples of usage:: | |
| 101 | + | |
| 102 | + # mkdir /sys/fs/cgroup/freezer | |
| 103 | + # mount -t cgroup -ofreezer freezer /sys/fs/cgroup/freezer | |
| 104 | + # mkdir /sys/fs/cgroup/freezer/0 | |
| 105 | + # echo $some_pid > /sys/fs/cgroup/freezer/0/tasks | |
| 106 | + | |
| 107 | +to get status of the freezer subsystem:: | |
| 108 | + | |
| 109 | + # cat /sys/fs/cgroup/freezer/0/freezer.state | |
| 110 | + THAWED | |
| 111 | + | |
| 112 | +to freeze all tasks in the container:: | |
| 113 | + | |
| 114 | + # echo FROZEN > /sys/fs/cgroup/freezer/0/freezer.state | |
| 115 | + # cat /sys/fs/cgroup/freezer/0/freezer.state | |
| 116 | + FREEZING | |
| 117 | + # cat /sys/fs/cgroup/freezer/0/freezer.state | |
| 118 | + FROZEN | |
| 119 | + | |
| 120 | +to unfreeze all tasks in the container:: | |
| 121 | + | |
| 122 | + # echo THAWED > /sys/fs/cgroup/freezer/0/freezer.state | |
| 123 | + # cat /sys/fs/cgroup/freezer/0/freezer.state | |
| 124 | + THAWED | |
| 125 | + | |
| 126 | +This is the basic mechanism which should do the right thing for user space task | |
| 127 | +in a simple scenario. | |
| @@ -0,0 +1,50 @@ | ||
| 1 | +================== | |
| 2 | +HugeTLB Controller | |
| 3 | +================== | |
| 4 | + | |
| 5 | +The HugeTLB controller allows to limit the HugeTLB usage per control group and | |
| 6 | +enforces the controller limit during page fault. Since HugeTLB doesn't | |
| 7 | +support page reclaim, enforcing the limit at page fault time implies that, | |
| 8 | +the application will get SIGBUS signal if it tries to access HugeTLB pages | |
| 9 | +beyond its limit. This requires the application to know beforehand how much | |
| 10 | +HugeTLB pages it would require for its use. | |
| 11 | + | |
| 12 | +HugeTLB controller can be created by first mounting the cgroup filesystem. | |
| 13 | + | |
| 14 | +# mount -t cgroup -o hugetlb none /sys/fs/cgroup | |
| 15 | + | |
| 16 | +With the above step, the initial or the parent HugeTLB group becomes | |
| 17 | +visible at /sys/fs/cgroup. At bootup, this group includes all the tasks in | |
| 18 | +the system. /sys/fs/cgroup/tasks lists the tasks in this cgroup. | |
| 19 | + | |
| 20 | +New groups can be created under the parent group /sys/fs/cgroup:: | |
| 21 | + | |
| 22 | + # cd /sys/fs/cgroup | |
| 23 | + # mkdir g1 | |
| 24 | + # echo $$ > g1/tasks | |
| 25 | + | |
| 26 | +The above steps create a new group g1 and move the current shell | |
| 27 | +process (bash) into it. | |
| 28 | + | |
| 29 | +Brief summary of control files:: | |
| 30 | + | |
| 31 | + hugetlb.<hugepagesize>.limit_in_bytes # set/show limit of "hugepagesize" hugetlb usage | |
| 32 | + hugetlb.<hugepagesize>.max_usage_in_bytes # show max "hugepagesize" hugetlb usage recorded | |
| 33 | + hugetlb.<hugepagesize>.usage_in_bytes # show current usage for "hugepagesize" hugetlb | |
| 34 | + hugetlb.<hugepagesize>.failcnt # show the number of allocation failure due to HugeTLB limit | |
| 35 | + | |
| 36 | +For a system supporting three hugepage sizes (64k, 32M and 1G), the control | |
| 37 | +files include:: | |
| 38 | + | |
| 39 | + hugetlb.1GB.limit_in_bytes | |
| 40 | + hugetlb.1GB.max_usage_in_bytes | |
| 41 | + hugetlb.1GB.usage_in_bytes | |
| 42 | + hugetlb.1GB.failcnt | |
| 43 | + hugetlb.64KB.limit_in_bytes | |
| 44 | + hugetlb.64KB.max_usage_in_bytes | |
| 45 | + hugetlb.64KB.usage_in_bytes | |
| 46 | + hugetlb.64KB.failcnt | |
| 47 | + hugetlb.32MB.limit_in_bytes | |
| 48 | + hugetlb.32MB.max_usage_in_bytes | |
| 49 | + hugetlb.32MB.usage_in_bytes | |
| 50 | + hugetlb.32MB.failcnt | |
| @@ -0,0 +1,28 @@ | ||
| 1 | +======================== | |
| 2 | +Control Groups version 1 | |
| 3 | +======================== | |
| 4 | + | |
| 5 | +.. toctree:: | |
| 6 | + :maxdepth: 1 | |
| 7 | + | |
| 8 | + cgroups | |
| 9 | + | |
| 10 | + blkio-controller | |
| 11 | + cpuacct | |
| 12 | + cpusets | |
| 13 | + devices | |
| 14 | + freezer-subsystem | |
| 15 | + hugetlb | |
| 16 | + memcg_test | |
| 17 | + memory | |
| 18 | + net_cls | |
| 19 | + net_prio | |
| 20 | + pids | |
| 21 | + rdma | |
| 22 | + | |
| 23 | +.. only:: subproject and html | |
| 24 | + | |
| 25 | + Indices | |
| 26 | + ======= | |
| 27 | + | |
| 28 | + * :ref:`genindex` | |
| @@ -0,0 +1,355 @@ | ||
| 1 | +===================================================== | |
| 2 | +Memory Resource Controller(Memcg) Implementation Memo | |
| 3 | +===================================================== | |
| 4 | + | |
| 5 | +Last Updated: 2010/2 | |
| 6 | + | |
| 7 | +Base Kernel Version: based on 2.6.33-rc7-mm(candidate for 34). | |
| 8 | + | |
| 9 | +Because VM is getting complex (one of reasons is memcg...), memcg's behavior | |
| 10 | +is complex. This is a document for memcg's internal behavior. | |
| 11 | +Please note that implementation details can be changed. | |
| 12 | + | |
| 13 | +(*) Topics on API should be in Documentation/admin-guide/cgroup-v1/memory.rst) | |
| 14 | + | |
| 15 | +0. How to record usage ? | |
| 16 | +======================== | |
| 17 | + | |
| 18 | + 2 objects are used. | |
| 19 | + | |
| 20 | + page_cgroup ....an object per page. | |
| 21 | + | |
| 22 | + Allocated at boot or memory hotplug. Freed at memory hot removal. | |
| 23 | + | |
| 24 | + swap_cgroup ... an entry per swp_entry. | |
| 25 | + | |
| 26 | + Allocated at swapon(). Freed at swapoff(). | |
| 27 | + | |
| 28 | + The page_cgroup has USED bit and double count against a page_cgroup never | |
| 29 | + occurs. swap_cgroup is used only when a charged page is swapped-out. | |
| 30 | + | |
| 31 | +1. Charge | |
| 32 | +========= | |
| 33 | + | |
| 34 | + a page/swp_entry may be charged (usage += PAGE_SIZE) at | |
| 35 | + | |
| 36 | + mem_cgroup_try_charge() | |
| 37 | + | |
| 38 | +2. Uncharge | |
| 39 | +=========== | |
| 40 | + | |
| 41 | + a page/swp_entry may be uncharged (usage -= PAGE_SIZE) by | |
| 42 | + | |
| 43 | + mem_cgroup_uncharge() | |
| 44 | + Called when a page's refcount goes down to 0. | |
| 45 | + | |
| 46 | + mem_cgroup_uncharge_swap() | |
| 47 | + Called when swp_entry's refcnt goes down to 0. A charge against swap | |
| 48 | + disappears. | |
| 49 | + | |
| 50 | +3. charge-commit-cancel | |
| 51 | +======================= | |
| 52 | + | |
| 53 | + Memcg pages are charged in two steps: | |
| 54 | + | |
| 55 | + - mem_cgroup_try_charge() | |
| 56 | + - mem_cgroup_commit_charge() or mem_cgroup_cancel_charge() | |
| 57 | + | |
| 58 | + At try_charge(), there are no flags to say "this page is charged". | |
| 59 | + at this point, usage += PAGE_SIZE. | |
| 60 | + | |
| 61 | + At commit(), the page is associated with the memcg. | |
| 62 | + | |
| 63 | + At cancel(), simply usage -= PAGE_SIZE. | |
| 64 | + | |
| 65 | +Under below explanation, we assume CONFIG_MEM_RES_CTRL_SWAP=y. | |
| 66 | + | |
| 67 | +4. Anonymous | |
| 68 | +============ | |
| 69 | + | |
| 70 | + Anonymous page is newly allocated at | |
| 71 | + - page fault into MAP_ANONYMOUS mapping. | |
| 72 | + - Copy-On-Write. | |
| 73 | + | |
| 74 | + 4.1 Swap-in. | |
| 75 | + At swap-in, the page is taken from swap-cache. There are 2 cases. | |
| 76 | + | |
| 77 | + (a) If the SwapCache is newly allocated and read, it has no charges. | |
| 78 | + (b) If the SwapCache has been mapped by processes, it has been | |
| 79 | + charged already. | |
| 80 | + | |
| 81 | + 4.2 Swap-out. | |
| 82 | + At swap-out, typical state transition is below. | |
| 83 | + | |
| 84 | + (a) add to swap cache. (marked as SwapCache) | |
| 85 | + swp_entry's refcnt += 1. | |
| 86 | + (b) fully unmapped. | |
| 87 | + swp_entry's refcnt += # of ptes. | |
| 88 | + (c) write back to swap. | |
| 89 | + (d) delete from swap cache. (remove from SwapCache) | |
| 90 | + swp_entry's refcnt -= 1. | |
| 91 | + | |
| 92 | + | |
| 93 | + Finally, at task exit, | |
| 94 | + (e) zap_pte() is called and swp_entry's refcnt -=1 -> 0. | |
| 95 | + | |
| 96 | +5. Page Cache | |
| 97 | +============= | |
| 98 | + | |
| 99 | + Page Cache is charged at | |
| 100 | + - add_to_page_cache_locked(). | |
| 101 | + | |
| 102 | + The logic is very clear. (About migration, see below) | |
| 103 | + | |
| 104 | + Note: | |
| 105 | + __remove_from_page_cache() is called by remove_from_page_cache() | |
| 106 | + and __remove_mapping(). | |
| 107 | + | |
| 108 | +6. Shmem(tmpfs) Page Cache | |
| 109 | +=========================== | |
| 110 | + | |
| 111 | + The best way to understand shmem's page state transition is to read | |
| 112 | + mm/shmem.c. | |
| 113 | + | |
| 114 | + But brief explanation of the behavior of memcg around shmem will be | |
| 115 | + helpful to understand the logic. | |
| 116 | + | |
| 117 | + Shmem's page (just leaf page, not direct/indirect block) can be on | |
| 118 | + | |
| 119 | + - radix-tree of shmem's inode. | |
| 120 | + - SwapCache. | |
| 121 | + - Both on radix-tree and SwapCache. This happens at swap-in | |
| 122 | + and swap-out, | |
| 123 | + | |
| 124 | + It's charged when... | |
| 125 | + | |
| 126 | + - A new page is added to shmem's radix-tree. | |
| 127 | + - A swp page is read. (move a charge from swap_cgroup to page_cgroup) | |
| 128 | + | |
| 129 | +7. Page Migration | |
| 130 | +================= | |
| 131 | + | |
| 132 | + mem_cgroup_migrate() | |
| 133 | + | |
| 134 | +8. LRU | |
| 135 | +====== | |
| 136 | + Each memcg has its own private LRU. Now, its handling is under global | |
| 137 | + VM's control (means that it's handled under global pgdat->lru_lock). | |
| 138 | + Almost all routines around memcg's LRU is called by global LRU's | |
| 139 | + list management functions under pgdat->lru_lock. | |
| 140 | + | |
| 141 | + A special function is mem_cgroup_isolate_pages(). This scans | |
| 142 | + memcg's private LRU and call __isolate_lru_page() to extract a page | |
| 143 | + from LRU. | |
| 144 | + | |
| 145 | + (By __isolate_lru_page(), the page is removed from both of global and | |
| 146 | + private LRU.) | |
| 147 | + | |
| 148 | + | |
| 149 | +9. Typical Tests. | |
| 150 | +================= | |
| 151 | + | |
| 152 | + Tests for racy cases. | |
| 153 | + | |
| 154 | +9.1 Small limit to memcg. | |
| 155 | +------------------------- | |
| 156 | + | |
| 157 | + When you do test to do racy case, it's good test to set memcg's limit | |
| 158 | + to be very small rather than GB. Many races found in the test under | |
| 159 | + xKB or xxMB limits. | |
| 160 | + | |
| 161 | + (Memory behavior under GB and Memory behavior under MB shows very | |
| 162 | + different situation.) | |
| 163 | + | |
| 164 | +9.2 Shmem | |
| 165 | +--------- | |
| 166 | + | |
| 167 | + Historically, memcg's shmem handling was poor and we saw some amount | |
| 168 | + of troubles here. This is because shmem is page-cache but can be | |
| 169 | + SwapCache. Test with shmem/tmpfs is always good test. | |
| 170 | + | |
| 171 | +9.3 Migration | |
| 172 | +------------- | |
| 173 | + | |
| 174 | + For NUMA, migration is an another special case. To do easy test, cpuset | |
| 175 | + is useful. Following is a sample script to do migration:: | |
| 176 | + | |
| 177 | + mount -t cgroup -o cpuset none /opt/cpuset | |
| 178 | + | |
| 179 | + mkdir /opt/cpuset/01 | |
| 180 | + echo 1 > /opt/cpuset/01/cpuset.cpus | |
| 181 | + echo 0 > /opt/cpuset/01/cpuset.mems | |
| 182 | + echo 1 > /opt/cpuset/01/cpuset.memory_migrate | |
| 183 | + mkdir /opt/cpuset/02 | |
| 184 | + echo 1 > /opt/cpuset/02/cpuset.cpus | |
| 185 | + echo 1 > /opt/cpuset/02/cpuset.mems | |
| 186 | + echo 1 > /opt/cpuset/02/cpuset.memory_migrate | |
| 187 | + | |
| 188 | + In above set, when you moves a task from 01 to 02, page migration to | |
| 189 | + node 0 to node 1 will occur. Following is a script to migrate all | |
| 190 | + under cpuset.:: | |
| 191 | + | |
| 192 | + -- | |
| 193 | + move_task() | |
| 194 | + { | |
| 195 | + for pid in $1 | |
| 196 | + do | |
| 197 | + /bin/echo $pid >$2/tasks 2>/dev/null | |
| 198 | + echo -n $pid | |
| 199 | + echo -n " " | |
| 200 | + done | |
| 201 | + echo END | |
| 202 | + } | |
| 203 | + | |
| 204 | + G1_TASK=`cat ${G1}/tasks` | |
| 205 | + G2_TASK=`cat ${G2}/tasks` | |
| 206 | + move_task "${G1_TASK}" ${G2} & | |
| 207 | + -- | |
| 208 | + | |
| 209 | +9.4 Memory hotplug | |
| 210 | +------------------ | |
| 211 | + | |
| 212 | + memory hotplug test is one of good test. | |
| 213 | + | |
| 214 | + to offline memory, do following:: | |
| 215 | + | |
| 216 | + # echo offline > /sys/devices/system/memory/memoryXXX/state | |
| 217 | + | |
| 218 | + (XXX is the place of memory) | |
| 219 | + | |
| 220 | + This is an easy way to test page migration, too. | |
| 221 | + | |
| 222 | +9.5 mkdir/rmdir | |
| 223 | +--------------- | |
| 224 | + | |
| 225 | + When using hierarchy, mkdir/rmdir test should be done. | |
| 226 | + Use tests like the following:: | |
| 227 | + | |
| 228 | + echo 1 >/opt/cgroup/01/memory/use_hierarchy | |
| 229 | + mkdir /opt/cgroup/01/child_a | |
| 230 | + mkdir /opt/cgroup/01/child_b | |
| 231 | + | |
| 232 | + set limit to 01. | |
| 233 | + add limit to 01/child_b | |
| 234 | + run jobs under child_a and child_b | |
| 235 | + | |
| 236 | + create/delete following groups at random while jobs are running:: | |
| 237 | + | |
| 238 | + /opt/cgroup/01/child_a/child_aa | |
| 239 | + /opt/cgroup/01/child_b/child_bb | |
| 240 | + /opt/cgroup/01/child_c | |
| 241 | + | |
| 242 | + running new jobs in new group is also good. | |
| 243 | + | |
| 244 | +9.6 Mount with other subsystems | |
| 245 | +------------------------------- | |
| 246 | + | |
| 247 | + Mounting with other subsystems is a good test because there is a | |
| 248 | + race and lock dependency with other cgroup subsystems. | |
| 249 | + | |
| 250 | + example:: | |
| 251 | + | |
| 252 | + # mount -t cgroup none /cgroup -o cpuset,memory,cpu,devices | |
| 253 | + | |
| 254 | + and do task move, mkdir, rmdir etc...under this. | |
| 255 | + | |
| 256 | +9.7 swapoff | |
| 257 | +----------- | |
| 258 | + | |
| 259 | + Besides management of swap is one of complicated parts of memcg, | |
| 260 | + call path of swap-in at swapoff is not same as usual swap-in path.. | |
| 261 | + It's worth to be tested explicitly. | |
| 262 | + | |
| 263 | + For example, test like following is good: | |
| 264 | + | |
| 265 | + (Shell-A):: | |
| 266 | + | |
| 267 | + # mount -t cgroup none /cgroup -o memory | |
| 268 | + # mkdir /cgroup/test | |
| 269 | + # echo 40M > /cgroup/test/memory.limit_in_bytes | |
| 270 | + # echo 0 > /cgroup/test/tasks | |
| 271 | + | |
| 272 | + Run malloc(100M) program under this. You'll see 60M of swaps. | |
| 273 | + | |
| 274 | + (Shell-B):: | |
| 275 | + | |
| 276 | + # move all tasks in /cgroup/test to /cgroup | |
| 277 | + # /sbin/swapoff -a | |
| 278 | + # rmdir /cgroup/test | |
| 279 | + # kill malloc task. | |
| 280 | + | |
| 281 | + Of course, tmpfs v.s. swapoff test should be tested, too. | |
| 282 | + | |
| 283 | +9.8 OOM-Killer | |
| 284 | +-------------- | |
| 285 | + | |
| 286 | + Out-of-memory caused by memcg's limit will kill tasks under | |
| 287 | + the memcg. When hierarchy is used, a task under hierarchy | |
| 288 | + will be killed by the kernel. | |
| 289 | + | |
| 290 | + In this case, panic_on_oom shouldn't be invoked and tasks | |
| 291 | + in other groups shouldn't be killed. | |
| 292 | + | |
| 293 | + It's not difficult to cause OOM under memcg as following. | |
| 294 | + | |
| 295 | + Case A) when you can swapoff:: | |
| 296 | + | |
| 297 | + #swapoff -a | |
| 298 | + #echo 50M > /memory.limit_in_bytes | |
| 299 | + | |
| 300 | + run 51M of malloc | |
| 301 | + | |
| 302 | + Case B) when you use mem+swap limitation:: | |
| 303 | + | |
| 304 | + #echo 50M > memory.limit_in_bytes | |
| 305 | + #echo 50M > memory.memsw.limit_in_bytes | |
| 306 | + | |
| 307 | + run 51M of malloc | |
| 308 | + | |
| 309 | +9.9 Move charges at task migration | |
| 310 | +---------------------------------- | |
| 311 | + | |
| 312 | + Charges associated with a task can be moved along with task migration. | |
| 313 | + | |
| 314 | + (Shell-A):: | |
| 315 | + | |
| 316 | + #mkdir /cgroup/A | |
| 317 | + #echo $$ >/cgroup/A/tasks | |
| 318 | + | |
| 319 | + run some programs which uses some amount of memory in /cgroup/A. | |
| 320 | + | |
| 321 | + (Shell-B):: | |
| 322 | + | |
| 323 | + #mkdir /cgroup/B | |
| 324 | + #echo 1 >/cgroup/B/memory.move_charge_at_immigrate | |
| 325 | + #echo "pid of the program running in group A" >/cgroup/B/tasks | |
| 326 | + | |
| 327 | + You can see charges have been moved by reading ``*.usage_in_bytes`` or | |
| 328 | + memory.stat of both A and B. | |
| 329 | + | |
| 330 | + See 8.2 of Documentation/admin-guide/cgroup-v1/memory.rst to see what value should | |
| 331 | + be written to move_charge_at_immigrate. | |
| 332 | + | |
| 333 | +9.10 Memory thresholds | |
| 334 | +---------------------- | |
| 335 | + | |
| 336 | + Memory controller implements memory thresholds using cgroups notification | |
| 337 | + API. You can use tools/cgroup/cgroup_event_listener.c to test it. | |
| 338 | + | |
| 339 | + (Shell-A) Create cgroup and run event listener:: | |
| 340 | + | |
| 341 | + # mkdir /cgroup/A | |
| 342 | + # ./cgroup_event_listener /cgroup/A/memory.usage_in_bytes 5M | |
| 343 | + | |
| 344 | + (Shell-B) Add task to cgroup and try to allocate and free memory:: | |
| 345 | + | |
| 346 | + # echo $$ >/cgroup/A/tasks | |
| 347 | + # a="$(dd if=/dev/zero bs=1M count=10)" | |
| 348 | + # a= | |
| 349 | + | |
| 350 | + You will see message from cgroup_event_listener every time you cross | |
| 351 | + the thresholds. | |
| 352 | + | |
| 353 | + Use /cgroup/A/memory.memsw.usage_in_bytes to test memsw thresholds. | |
| 354 | + | |
| 355 | + It's good idea to test root cgroup as well. | |
| @@ -0,0 +1,1003 @@ | ||
| 1 | +========================== | |
| 2 | +Memory Resource Controller | |
| 3 | +========================== | |
| 4 | + | |
| 5 | +NOTE: | |
| 6 | + This document is hopelessly outdated and it asks for a complete | |
| 7 | + rewrite. It still contains a useful information so we are keeping it | |
| 8 | + here but make sure to check the current code if you need a deeper | |
| 9 | + understanding. | |
| 10 | + | |
| 11 | +NOTE: | |
| 12 | + The Memory Resource Controller has generically been referred to as the | |
| 13 | + memory controller in this document. Do not confuse memory controller | |
| 14 | + used here with the memory controller that is used in hardware. | |
| 15 | + | |
| 16 | +(For editors) In this document: | |
| 17 | + When we mention a cgroup (cgroupfs's directory) with memory controller, | |
| 18 | + we call it "memory cgroup". When you see git-log and source code, you'll | |
| 19 | + see patch's title and function names tend to use "memcg". | |
| 20 | + In this document, we avoid using it. | |
| 21 | + | |
| 22 | +Benefits and Purpose of the memory controller | |
| 23 | +============================================= | |
| 24 | + | |
| 25 | +The memory controller isolates the memory behaviour of a group of tasks | |
| 26 | +from the rest of the system. The article on LWN [12] mentions some probable | |
| 27 | +uses of the memory controller. The memory controller can be used to | |
| 28 | + | |
| 29 | +a. Isolate an application or a group of applications | |
| 30 | + Memory-hungry applications can be isolated and limited to a smaller | |
| 31 | + amount of memory. | |
| 32 | +b. Create a cgroup with a limited amount of memory; this can be used | |
| 33 | + as a good alternative to booting with mem=XXXX. | |
| 34 | +c. Virtualization solutions can control the amount of memory they want | |
| 35 | + to assign to a virtual machine instance. | |
| 36 | +d. A CD/DVD burner could control the amount of memory used by the | |
| 37 | + rest of the system to ensure that burning does not fail due to lack | |
| 38 | + of available memory. | |
| 39 | +e. There are several other use cases; find one or use the controller just | |
| 40 | + for fun (to learn and hack on the VM subsystem). | |
| 41 | + | |
| 42 | +Current Status: linux-2.6.34-mmotm(development version of 2010/April) | |
| 43 | + | |
| 44 | +Features: | |
| 45 | + | |
| 46 | + - accounting anonymous pages, file caches, swap caches usage and limiting them. | |
| 47 | + - pages are linked to per-memcg LRU exclusively, and there is no global LRU. | |
| 48 | + - optionally, memory+swap usage can be accounted and limited. | |
| 49 | + - hierarchical accounting | |
| 50 | + - soft limit | |
| 51 | + - moving (recharging) account at moving a task is selectable. | |
| 52 | + - usage threshold notifier | |
| 53 | + - memory pressure notifier | |
| 54 | + - oom-killer disable knob and oom-notifier | |
| 55 | + - Root cgroup has no limit controls. | |
| 56 | + | |
| 57 | + Kernel memory support is a work in progress, and the current version provides | |
| 58 | + basically functionality. (See Section 2.7) | |
| 59 | + | |
| 60 | +Brief summary of control files. | |
| 61 | + | |
| 62 | +==================================== ========================================== | |
| 63 | + tasks attach a task(thread) and show list of | |
| 64 | + threads | |
| 65 | + cgroup.procs show list of processes | |
| 66 | + cgroup.event_control an interface for event_fd() | |
| 67 | + memory.usage_in_bytes show current usage for memory | |
| 68 | + (See 5.5 for details) | |
| 69 | + memory.memsw.usage_in_bytes show current usage for memory+Swap | |
| 70 | + (See 5.5 for details) | |
| 71 | + memory.limit_in_bytes set/show limit of memory usage | |
| 72 | + memory.memsw.limit_in_bytes set/show limit of memory+Swap usage | |
| 73 | + memory.failcnt show the number of memory usage hits limits | |
| 74 | + memory.memsw.failcnt show the number of memory+Swap hits limits | |
| 75 | + memory.max_usage_in_bytes show max memory usage recorded | |
| 76 | + memory.memsw.max_usage_in_bytes show max memory+Swap usage recorded | |
| 77 | + memory.soft_limit_in_bytes set/show soft limit of memory usage | |
| 78 | + memory.stat show various statistics | |
| 79 | + memory.use_hierarchy set/show hierarchical account enabled | |
| 80 | + memory.force_empty trigger forced page reclaim | |
| 81 | + memory.pressure_level set memory pressure notifications | |
| 82 | + memory.swappiness set/show swappiness parameter of vmscan | |
| 83 | + (See sysctl's vm.swappiness) | |
| 84 | + memory.move_charge_at_immigrate set/show controls of moving charges | |
| 85 | + memory.oom_control set/show oom controls. | |
| 86 | + memory.numa_stat show the number of memory usage per numa | |
| 87 | + node | |
| 88 | + | |
| 89 | + memory.kmem.limit_in_bytes set/show hard limit for kernel memory | |
| 90 | + memory.kmem.usage_in_bytes show current kernel memory allocation | |
| 91 | + memory.kmem.failcnt show the number of kernel memory usage | |
| 92 | + hits limits | |
| 93 | + memory.kmem.max_usage_in_bytes show max kernel memory usage recorded | |
| 94 | + | |
| 95 | + memory.kmem.tcp.limit_in_bytes set/show hard limit for tcp buf memory | |
| 96 | + memory.kmem.tcp.usage_in_bytes show current tcp buf memory allocation | |
| 97 | + memory.kmem.tcp.failcnt show the number of tcp buf memory usage | |
| 98 | + hits limits | |
| 99 | + memory.kmem.tcp.max_usage_in_bytes show max tcp buf memory usage recorded | |
| 100 | +==================================== ========================================== | |
| 101 | + | |
| 102 | +1. History | |
| 103 | +========== | |
| 104 | + | |
| 105 | +The memory controller has a long history. A request for comments for the memory | |
| 106 | +controller was posted by Balbir Singh [1]. At the time the RFC was posted | |
| 107 | +there were several implementations for memory control. The goal of the | |
| 108 | +RFC was to build consensus and agreement for the minimal features required | |
| 109 | +for memory control. The first RSS controller was posted by Balbir Singh[2] | |
| 110 | +in Feb 2007. Pavel Emelianov [3][4][5] has since posted three versions of the | |
| 111 | +RSS controller. At OLS, at the resource management BoF, everyone suggested | |
| 112 | +that we handle both page cache and RSS together. Another request was raised | |
| 113 | +to allow user space handling of OOM. The current memory controller is | |
| 114 | +at version 6; it combines both mapped (RSS) and unmapped Page | |
| 115 | +Cache Control [11]. | |
| 116 | + | |
| 117 | +2. Memory Control | |
| 118 | +================= | |
| 119 | + | |
| 120 | +Memory is a unique resource in the sense that it is present in a limited | |
| 121 | +amount. If a task requires a lot of CPU processing, the task can spread | |
| 122 | +its processing over a period of hours, days, months or years, but with | |
| 123 | +memory, the same physical memory needs to be reused to accomplish the task. | |
| 124 | + | |
| 125 | +The memory controller implementation has been divided into phases. These | |
| 126 | +are: | |
| 127 | + | |
| 128 | +1. Memory controller | |
| 129 | +2. mlock(2) controller | |
| 130 | +3. Kernel user memory accounting and slab control | |
| 131 | +4. user mappings length controller | |
| 132 | + | |
| 133 | +The memory controller is the first controller developed. | |
| 134 | + | |
| 135 | +2.1. Design | |
| 136 | +----------- | |
| 137 | + | |
| 138 | +The core of the design is a counter called the page_counter. The | |
| 139 | +page_counter tracks the current memory usage and limit of the group of | |
| 140 | +processes associated with the controller. Each cgroup has a memory controller | |
| 141 | +specific data structure (mem_cgroup) associated with it. | |
| 142 | + | |
| 143 | +2.2. Accounting | |
| 144 | +--------------- | |
| 145 | + | |
| 146 | +:: | |
| 147 | + | |
| 148 | + +--------------------+ | |
| 149 | + | mem_cgroup | | |
| 150 | + | (page_counter) | | |
| 151 | + +--------------------+ | |
| 152 | + / ^ \ | |
| 153 | + / | \ | |
| 154 | + +---------------+ | +---------------+ | |
| 155 | + | mm_struct | |.... | mm_struct | | |
| 156 | + | | | | | | |
| 157 | + +---------------+ | +---------------+ | |
| 158 | + | | |
| 159 | + + --------------+ | |
| 160 | + | | |
| 161 | + +---------------+ +------+--------+ | |
| 162 | + | page +----------> page_cgroup| | |
| 163 | + | | | | | |
| 164 | + +---------------+ +---------------+ | |
| 165 | + | |
| 166 | + (Figure 1: Hierarchy of Accounting) | |
| 167 | + | |
| 168 | + | |
| 169 | +Figure 1 shows the important aspects of the controller | |
| 170 | + | |
| 171 | +1. Accounting happens per cgroup | |
| 172 | +2. Each mm_struct knows about which cgroup it belongs to | |
| 173 | +3. Each page has a pointer to the page_cgroup, which in turn knows the | |
| 174 | + cgroup it belongs to | |
| 175 | + | |
| 176 | +The accounting is done as follows: mem_cgroup_charge_common() is invoked to | |
| 177 | +set up the necessary data structures and check if the cgroup that is being | |
| 178 | +charged is over its limit. If it is, then reclaim is invoked on the cgroup. | |
| 179 | +More details can be found in the reclaim section of this document. | |
| 180 | +If everything goes well, a page meta-data-structure called page_cgroup is | |
| 181 | +updated. page_cgroup has its own LRU on cgroup. | |
| 182 | +(*) page_cgroup structure is allocated at boot/memory-hotplug time. | |
| 183 | + | |
| 184 | +2.2.1 Accounting details | |
| 185 | +------------------------ | |
| 186 | + | |
| 187 | +All mapped anon pages (RSS) and cache pages (Page Cache) are accounted. | |
| 188 | +Some pages which are never reclaimable and will not be on the LRU | |
| 189 | +are not accounted. We just account pages under usual VM management. | |
| 190 | + | |
| 191 | +RSS pages are accounted at page_fault unless they've already been accounted | |
| 192 | +for earlier. A file page will be accounted for as Page Cache when it's | |
| 193 | +inserted into inode (radix-tree). While it's mapped into the page tables of | |
| 194 | +processes, duplicate accounting is carefully avoided. | |
| 195 | + | |
| 196 | +An RSS page is unaccounted when it's fully unmapped. A PageCache page is | |
| 197 | +unaccounted when it's removed from radix-tree. Even if RSS pages are fully | |
| 198 | +unmapped (by kswapd), they may exist as SwapCache in the system until they | |
| 199 | +are really freed. Such SwapCaches are also accounted. | |
| 200 | +A swapped-in page is not accounted until it's mapped. | |
| 201 | + | |
| 202 | +Note: The kernel does swapin-readahead and reads multiple swaps at once. | |
| 203 | +This means swapped-in pages may contain pages for other tasks than a task | |
| 204 | +causing page fault. So, we avoid accounting at swap-in I/O. | |
| 205 | + | |
| 206 | +At page migration, accounting information is kept. | |
| 207 | + | |
| 208 | +Note: we just account pages-on-LRU because our purpose is to control amount | |
| 209 | +of used pages; not-on-LRU pages tend to be out-of-control from VM view. | |
| 210 | + | |
| 211 | +2.3 Shared Page Accounting | |
| 212 | +-------------------------- | |
| 213 | + | |
| 214 | +Shared pages are accounted on the basis of the first touch approach. The | |
| 215 | +cgroup that first touches a page is accounted for the page. The principle | |
| 216 | +behind this approach is that a cgroup that aggressively uses a shared | |
| 217 | +page will eventually get charged for it (once it is uncharged from | |
| 218 | +the cgroup that brought it in -- this will happen on memory pressure). | |
| 219 | + | |
| 220 | +But see section 8.2: when moving a task to another cgroup, its pages may | |
| 221 | +be recharged to the new cgroup, if move_charge_at_immigrate has been chosen. | |
| 222 | + | |
| 223 | +Exception: If CONFIG_MEMCG_SWAP is not used. | |
| 224 | +When you do swapoff and make swapped-out pages of shmem(tmpfs) to | |
| 225 | +be backed into memory in force, charges for pages are accounted against the | |
| 226 | +caller of swapoff rather than the users of shmem. | |
| 227 | + | |
| 228 | +2.4 Swap Extension (CONFIG_MEMCG_SWAP) | |
| 229 | +-------------------------------------- | |
| 230 | + | |
| 231 | +Swap Extension allows you to record charge for swap. A swapped-in page is | |
| 232 | +charged back to original page allocator if possible. | |
| 233 | + | |
| 234 | +When swap is accounted, following files are added. | |
| 235 | + | |
| 236 | + - memory.memsw.usage_in_bytes. | |
| 237 | + - memory.memsw.limit_in_bytes. | |
| 238 | + | |
| 239 | +memsw means memory+swap. Usage of memory+swap is limited by | |
| 240 | +memsw.limit_in_bytes. | |
| 241 | + | |
| 242 | +Example: Assume a system with 4G of swap. A task which allocates 6G of memory | |
| 243 | +(by mistake) under 2G memory limitation will use all swap. | |
| 244 | +In this case, setting memsw.limit_in_bytes=3G will prevent bad use of swap. | |
| 245 | +By using the memsw limit, you can avoid system OOM which can be caused by swap | |
| 246 | +shortage. | |
| 247 | + | |
| 248 | +**why 'memory+swap' rather than swap** | |
| 249 | + | |
| 250 | +The global LRU(kswapd) can swap out arbitrary pages. Swap-out means | |
| 251 | +to move account from memory to swap...there is no change in usage of | |
| 252 | +memory+swap. In other words, when we want to limit the usage of swap without | |
| 253 | +affecting global LRU, memory+swap limit is better than just limiting swap from | |
| 254 | +an OS point of view. | |
| 255 | + | |
| 256 | +**What happens when a cgroup hits memory.memsw.limit_in_bytes** | |
| 257 | + | |
| 258 | +When a cgroup hits memory.memsw.limit_in_bytes, it's useless to do swap-out | |
| 259 | +in this cgroup. Then, swap-out will not be done by cgroup routine and file | |
| 260 | +caches are dropped. But as mentioned above, global LRU can do swapout memory | |
| 261 | +from it for sanity of the system's memory management state. You can't forbid | |
| 262 | +it by cgroup. | |
| 263 | + | |
| 264 | +2.5 Reclaim | |
| 265 | +----------- | |
| 266 | + | |
| 267 | +Each cgroup maintains a per cgroup LRU which has the same structure as | |
| 268 | +global VM. When a cgroup goes over its limit, we first try | |
| 269 | +to reclaim memory from the cgroup so as to make space for the new | |
| 270 | +pages that the cgroup has touched. If the reclaim is unsuccessful, | |
| 271 | +an OOM routine is invoked to select and kill the bulkiest task in the | |
| 272 | +cgroup. (See 10. OOM Control below.) | |
| 273 | + | |
| 274 | +The reclaim algorithm has not been modified for cgroups, except that | |
| 275 | +pages that are selected for reclaiming come from the per-cgroup LRU | |
| 276 | +list. | |
| 277 | + | |
| 278 | +NOTE: | |
| 279 | + Reclaim does not work for the root cgroup, since we cannot set any | |
| 280 | + limits on the root cgroup. | |
| 281 | + | |
| 282 | +Note2: | |
| 283 | + When panic_on_oom is set to "2", the whole system will panic. | |
| 284 | + | |
| 285 | +When oom event notifier is registered, event will be delivered. | |
| 286 | +(See oom_control section) | |
| 287 | + | |
| 288 | +2.6 Locking | |
| 289 | +----------- | |
| 290 | + | |
| 291 | + lock_page_cgroup()/unlock_page_cgroup() should not be called under | |
| 292 | + the i_pages lock. | |
| 293 | + | |
| 294 | + Other lock order is following: | |
| 295 | + | |
| 296 | + PG_locked. | |
| 297 | + mm->page_table_lock | |
| 298 | + pgdat->lru_lock | |
| 299 | + lock_page_cgroup. | |
| 300 | + | |
| 301 | + In many cases, just lock_page_cgroup() is called. | |
| 302 | + | |
| 303 | + per-zone-per-cgroup LRU (cgroup's private LRU) is just guarded by | |
| 304 | + pgdat->lru_lock, it has no lock of its own. | |
| 305 | + | |
| 306 | +2.7 Kernel Memory Extension (CONFIG_MEMCG_KMEM) | |
| 307 | +----------------------------------------------- | |
| 308 | + | |
| 309 | +With the Kernel memory extension, the Memory Controller is able to limit | |
| 310 | +the amount of kernel memory used by the system. Kernel memory is fundamentally | |
| 311 | +different than user memory, since it can't be swapped out, which makes it | |
| 312 | +possible to DoS the system by consuming too much of this precious resource. | |
| 313 | + | |
| 314 | +Kernel memory accounting is enabled for all memory cgroups by default. But | |
| 315 | +it can be disabled system-wide by passing cgroup.memory=nokmem to the kernel | |
| 316 | +at boot time. In this case, kernel memory will not be accounted at all. | |
| 317 | + | |
| 318 | +Kernel memory limits are not imposed for the root cgroup. Usage for the root | |
| 319 | +cgroup may or may not be accounted. The memory used is accumulated into | |
| 320 | +memory.kmem.usage_in_bytes, or in a separate counter when it makes sense. | |
| 321 | +(currently only for tcp). | |
| 322 | + | |
| 323 | +The main "kmem" counter is fed into the main counter, so kmem charges will | |
| 324 | +also be visible from the user counter. | |
| 325 | + | |
| 326 | +Currently no soft limit is implemented for kernel memory. It is future work | |
| 327 | +to trigger slab reclaim when those limits are reached. | |
| 328 | + | |
| 329 | +2.7.1 Current Kernel Memory resources accounted | |
| 330 | +----------------------------------------------- | |
| 331 | + | |
| 332 | +stack pages: | |
| 333 | + every process consumes some stack pages. By accounting into | |
| 334 | + kernel memory, we prevent new processes from being created when the kernel | |
| 335 | + memory usage is too high. | |
| 336 | + | |
| 337 | +slab pages: | |
| 338 | + pages allocated by the SLAB or SLUB allocator are tracked. A copy | |
| 339 | + of each kmem_cache is created every time the cache is touched by the first time | |
| 340 | + from inside the memcg. The creation is done lazily, so some objects can still be | |
| 341 | + skipped while the cache is being created. All objects in a slab page should | |
| 342 | + belong to the same memcg. This only fails to hold when a task is migrated to a | |
| 343 | + different memcg during the page allocation by the cache. | |
| 344 | + | |
| 345 | +sockets memory pressure: | |
| 346 | + some sockets protocols have memory pressure | |
| 347 | + thresholds. The Memory Controller allows them to be controlled individually | |
| 348 | + per cgroup, instead of globally. | |
| 349 | + | |
| 350 | +tcp memory pressure: | |
| 351 | + sockets memory pressure for the tcp protocol. | |
| 352 | + | |
| 353 | +2.7.2 Common use cases | |
| 354 | +---------------------- | |
| 355 | + | |
| 356 | +Because the "kmem" counter is fed to the main user counter, kernel memory can | |
| 357 | +never be limited completely independently of user memory. Say "U" is the user | |
| 358 | +limit, and "K" the kernel limit. There are three possible ways limits can be | |
| 359 | +set: | |
| 360 | + | |
| 361 | +U != 0, K = unlimited: | |
| 362 | + This is the standard memcg limitation mechanism already present before kmem | |
| 363 | + accounting. Kernel memory is completely ignored. | |
| 364 | + | |
| 365 | +U != 0, K < U: | |
| 366 | + Kernel memory is a subset of the user memory. This setup is useful in | |
| 367 | + deployments where the total amount of memory per-cgroup is overcommited. | |
| 368 | + Overcommiting kernel memory limits is definitely not recommended, since the | |
| 369 | + box can still run out of non-reclaimable memory. | |
| 370 | + In this case, the admin could set up K so that the sum of all groups is | |
| 371 | + never greater than the total memory, and freely set U at the cost of his | |
| 372 | + QoS. | |
| 373 | + | |
| 374 | +WARNING: | |
| 375 | + In the current implementation, memory reclaim will NOT be | |
| 376 | + triggered for a cgroup when it hits K while staying below U, which makes | |
| 377 | + this setup impractical. | |
| 378 | + | |
| 379 | +U != 0, K >= U: | |
| 380 | + Since kmem charges will also be fed to the user counter and reclaim will be | |
| 381 | + triggered for the cgroup for both kinds of memory. This setup gives the | |
| 382 | + admin a unified view of memory, and it is also useful for people who just | |
| 383 | + want to track kernel memory usage. | |
| 384 | + | |
| 385 | +3. User Interface | |
| 386 | +================= | |
| 387 | + | |
| 388 | +3.0. Configuration | |
| 389 | +------------------ | |
| 390 | + | |
| 391 | +a. Enable CONFIG_CGROUPS | |
| 392 | +b. Enable CONFIG_MEMCG | |
| 393 | +c. Enable CONFIG_MEMCG_SWAP (to use swap extension) | |
| 394 | +d. Enable CONFIG_MEMCG_KMEM (to use kmem extension) | |
| 395 | + | |
| 396 | +3.1. Prepare the cgroups (see cgroups.txt, Why are cgroups needed?) | |
| 397 | +------------------------------------------------------------------- | |
| 398 | + | |
| 399 | +:: | |
| 400 | + | |
| 401 | + # mount -t tmpfs none /sys/fs/cgroup | |
| 402 | + # mkdir /sys/fs/cgroup/memory | |
| 403 | + # mount -t cgroup none /sys/fs/cgroup/memory -o memory | |
| 404 | + | |
| 405 | +3.2. Make the new group and move bash into it:: | |
| 406 | + | |
| 407 | + # mkdir /sys/fs/cgroup/memory/0 | |
| 408 | + # echo $$ > /sys/fs/cgroup/memory/0/tasks | |
| 409 | + | |
| 410 | +Since now we're in the 0 cgroup, we can alter the memory limit:: | |
| 411 | + | |
| 412 | + # echo 4M > /sys/fs/cgroup/memory/0/memory.limit_in_bytes | |
| 413 | + | |
| 414 | +NOTE: | |
| 415 | + We can use a suffix (k, K, m, M, g or G) to indicate values in kilo, | |
| 416 | + mega or gigabytes. (Here, Kilo, Mega, Giga are Kibibytes, Mebibytes, | |
| 417 | + Gibibytes.) | |
| 418 | + | |
| 419 | +NOTE: | |
| 420 | + We can write "-1" to reset the ``*.limit_in_bytes(unlimited)``. | |
| 421 | + | |
| 422 | +NOTE: | |
| 423 | + We cannot set limits on the root cgroup any more. | |
| 424 | + | |
| 425 | +:: | |
| 426 | + | |
| 427 | + # cat /sys/fs/cgroup/memory/0/memory.limit_in_bytes | |
| 428 | + 4194304 | |
| 429 | + | |
| 430 | +We can check the usage:: | |
| 431 | + | |
| 432 | + # cat /sys/fs/cgroup/memory/0/memory.usage_in_bytes | |
| 433 | + 1216512 | |
| 434 | + | |
| 435 | +A successful write to this file does not guarantee a successful setting of | |
| 436 | +this limit to the value written into the file. This can be due to a | |
| 437 | +number of factors, such as rounding up to page boundaries or the total | |
| 438 | +availability of memory on the system. The user is required to re-read | |
| 439 | +this file after a write to guarantee the value committed by the kernel:: | |
| 440 | + | |
| 441 | + # echo 1 > memory.limit_in_bytes | |
| 442 | + # cat memory.limit_in_bytes | |
| 443 | + 4096 | |
| 444 | + | |
| 445 | +The memory.failcnt field gives the number of times that the cgroup limit was | |
| 446 | +exceeded. | |
| 447 | + | |
| 448 | +The memory.stat file gives accounting information. Now, the number of | |
| 449 | +caches, RSS and Active pages/Inactive pages are shown. | |
| 450 | + | |
| 451 | +4. Testing | |
| 452 | +========== | |
| 453 | + | |
| 454 | +For testing features and implementation, see memcg_test.txt. | |
| 455 | + | |
| 456 | +Performance test is also important. To see pure memory controller's overhead, | |
| 457 | +testing on tmpfs will give you good numbers of small overheads. | |
| 458 | +Example: do kernel make on tmpfs. | |
| 459 | + | |
| 460 | +Page-fault scalability is also important. At measuring parallel | |
| 461 | +page fault test, multi-process test may be better than multi-thread | |
| 462 | +test because it has noise of shared objects/status. | |
| 463 | + | |
| 464 | +But the above two are testing extreme situations. | |
| 465 | +Trying usual test under memory controller is always helpful. | |
| 466 | + | |
| 467 | +4.1 Troubleshooting | |
| 468 | +------------------- | |
| 469 | + | |
| 470 | +Sometimes a user might find that the application under a cgroup is | |
| 471 | +terminated by the OOM killer. There are several causes for this: | |
| 472 | + | |
| 473 | +1. The cgroup limit is too low (just too low to do anything useful) | |
| 474 | +2. The user is using anonymous memory and swap is turned off or too low | |
| 475 | + | |
| 476 | +A sync followed by echo 1 > /proc/sys/vm/drop_caches will help get rid of | |
| 477 | +some of the pages cached in the cgroup (page cache pages). | |
| 478 | + | |
| 479 | +To know what happens, disabling OOM_Kill as per "10. OOM Control" (below) and | |
| 480 | +seeing what happens will be helpful. | |
| 481 | + | |
| 482 | +4.2 Task migration | |
| 483 | +------------------ | |
| 484 | + | |
| 485 | +When a task migrates from one cgroup to another, its charge is not | |
| 486 | +carried forward by default. The pages allocated from the original cgroup still | |
| 487 | +remain charged to it, the charge is dropped when the page is freed or | |
| 488 | +reclaimed. | |
| 489 | + | |
| 490 | +You can move charges of a task along with task migration. | |
| 491 | +See 8. "Move charges at task migration" | |
| 492 | + | |
| 493 | +4.3 Removing a cgroup | |
| 494 | +--------------------- | |
| 495 | + | |
| 496 | +A cgroup can be removed by rmdir, but as discussed in sections 4.1 and 4.2, a | |
| 497 | +cgroup might have some charge associated with it, even though all | |
| 498 | +tasks have migrated away from it. (because we charge against pages, not | |
| 499 | +against tasks.) | |
| 500 | + | |
| 501 | +We move the stats to root (if use_hierarchy==0) or parent (if | |
| 502 | +use_hierarchy==1), and no change on the charge except uncharging | |
| 503 | +from the child. | |
| 504 | + | |
| 505 | +Charges recorded in swap information is not updated at removal of cgroup. | |
| 506 | +Recorded information is discarded and a cgroup which uses swap (swapcache) | |
| 507 | +will be charged as a new owner of it. | |
| 508 | + | |
| 509 | +About use_hierarchy, see Section 6. | |
| 510 | + | |
| 511 | +5. Misc. interfaces | |
| 512 | +=================== | |
| 513 | + | |
| 514 | +5.1 force_empty | |
| 515 | +--------------- | |
| 516 | + memory.force_empty interface is provided to make cgroup's memory usage empty. | |
| 517 | + When writing anything to this:: | |
| 518 | + | |
| 519 | + # echo 0 > memory.force_empty | |
| 520 | + | |
| 521 | + the cgroup will be reclaimed and as many pages reclaimed as possible. | |
| 522 | + | |
| 523 | + The typical use case for this interface is before calling rmdir(). | |
| 524 | + Though rmdir() offlines memcg, but the memcg may still stay there due to | |
| 525 | + charged file caches. Some out-of-use page caches may keep charged until | |
| 526 | + memory pressure happens. If you want to avoid that, force_empty will be useful. | |
| 527 | + | |
| 528 | + Also, note that when memory.kmem.limit_in_bytes is set the charges due to | |
| 529 | + kernel pages will still be seen. This is not considered a failure and the | |
| 530 | + write will still return success. In this case, it is expected that | |
| 531 | + memory.kmem.usage_in_bytes == memory.usage_in_bytes. | |
| 532 | + | |
| 533 | + About use_hierarchy, see Section 6. | |
| 534 | + | |
| 535 | +5.2 stat file | |
| 536 | +------------- | |
| 537 | + | |
| 538 | +memory.stat file includes following statistics | |
| 539 | + | |
| 540 | +per-memory cgroup local status | |
| 541 | +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ | |
| 542 | + | |
| 543 | +=============== =============================================================== | |
| 544 | +cache # of bytes of page cache memory. | |
| 545 | +rss # of bytes of anonymous and swap cache memory (includes | |
| 546 | + transparent hugepages). | |
| 547 | +rss_huge # of bytes of anonymous transparent hugepages. | |
| 548 | +mapped_file # of bytes of mapped file (includes tmpfs/shmem) | |
| 549 | +pgpgin # of charging events to the memory cgroup. The charging | |
| 550 | + event happens each time a page is accounted as either mapped | |
| 551 | + anon page(RSS) or cache page(Page Cache) to the cgroup. | |
| 552 | +pgpgout # of uncharging events to the memory cgroup. The uncharging | |
| 553 | + event happens each time a page is unaccounted from the cgroup. | |
| 554 | +swap # of bytes of swap usage | |
| 555 | +dirty # of bytes that are waiting to get written back to the disk. | |
| 556 | +writeback # of bytes of file/anon cache that are queued for syncing to | |
| 557 | + disk. | |
| 558 | +inactive_anon # of bytes of anonymous and swap cache memory on inactive | |
| 559 | + LRU list. | |
| 560 | +active_anon # of bytes of anonymous and swap cache memory on active | |
| 561 | + LRU list. | |
| 562 | +inactive_file # of bytes of file-backed memory on inactive LRU list. | |
| 563 | +active_file # of bytes of file-backed memory on active LRU list. | |
| 564 | +unevictable # of bytes of memory that cannot be reclaimed (mlocked etc). | |
| 565 | +=============== =============================================================== | |
| 566 | + | |
| 567 | +status considering hierarchy (see memory.use_hierarchy settings) | |
| 568 | +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ | |
| 569 | + | |
| 570 | +========================= =================================================== | |
| 571 | +hierarchical_memory_limit # of bytes of memory limit with regard to hierarchy | |
| 572 | + under which the memory cgroup is | |
| 573 | +hierarchical_memsw_limit # of bytes of memory+swap limit with regard to | |
| 574 | + hierarchy under which memory cgroup is. | |
| 575 | + | |
| 576 | +total_<counter> # hierarchical version of <counter>, which in | |
| 577 | + addition to the cgroup's own value includes the | |
| 578 | + sum of all hierarchical children's values of | |
| 579 | + <counter>, i.e. total_cache | |
| 580 | +========================= =================================================== | |
| 581 | + | |
| 582 | +The following additional stats are dependent on CONFIG_DEBUG_VM | |
| 583 | +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ | |
| 584 | + | |
| 585 | +========================= ======================================== | |
| 586 | +recent_rotated_anon VM internal parameter. (see mm/vmscan.c) | |
| 587 | +recent_rotated_file VM internal parameter. (see mm/vmscan.c) | |
| 588 | +recent_scanned_anon VM internal parameter. (see mm/vmscan.c) | |
| 589 | +recent_scanned_file VM internal parameter. (see mm/vmscan.c) | |
| 590 | +========================= ======================================== | |
| 591 | + | |
| 592 | +Memo: | |
| 593 | + recent_rotated means recent frequency of LRU rotation. | |
| 594 | + recent_scanned means recent # of scans to LRU. | |
| 595 | + showing for better debug please see the code for meanings. | |
| 596 | + | |
| 597 | +Note: | |
| 598 | + Only anonymous and swap cache memory is listed as part of 'rss' stat. | |
| 599 | + This should not be confused with the true 'resident set size' or the | |
| 600 | + amount of physical memory used by the cgroup. | |
| 601 | + | |
| 602 | + 'rss + mapped_file" will give you resident set size of cgroup. | |
| 603 | + | |
| 604 | + (Note: file and shmem may be shared among other cgroups. In that case, | |
| 605 | + mapped_file is accounted only when the memory cgroup is owner of page | |
| 606 | + cache.) | |
| 607 | + | |
| 608 | +5.3 swappiness | |
| 609 | +-------------- | |
| 610 | + | |
| 611 | +Overrides /proc/sys/vm/swappiness for the particular group. The tunable | |
| 612 | +in the root cgroup corresponds to the global swappiness setting. | |
| 613 | + | |
| 614 | +Please note that unlike during the global reclaim, limit reclaim | |
| 615 | +enforces that 0 swappiness really prevents from any swapping even if | |
| 616 | +there is a swap storage available. This might lead to memcg OOM killer | |
| 617 | +if there are no file pages to reclaim. | |
| 618 | + | |
| 619 | +5.4 failcnt | |
| 620 | +----------- | |
| 621 | + | |
| 622 | +A memory cgroup provides memory.failcnt and memory.memsw.failcnt files. | |
| 623 | +This failcnt(== failure count) shows the number of times that a usage counter | |
| 624 | +hit its limit. When a memory cgroup hits a limit, failcnt increases and | |
| 625 | +memory under it will be reclaimed. | |
| 626 | + | |
| 627 | +You can reset failcnt by writing 0 to failcnt file:: | |
| 628 | + | |
| 629 | + # echo 0 > .../memory.failcnt | |
| 630 | + | |
| 631 | +5.5 usage_in_bytes | |
| 632 | +------------------ | |
| 633 | + | |
| 634 | +For efficiency, as other kernel components, memory cgroup uses some optimization | |
| 635 | +to avoid unnecessary cacheline false sharing. usage_in_bytes is affected by the | |
| 636 | +method and doesn't show 'exact' value of memory (and swap) usage, it's a fuzz | |
| 637 | +value for efficient access. (Of course, when necessary, it's synchronized.) | |
| 638 | +If you want to know more exact memory usage, you should use RSS+CACHE(+SWAP) | |
| 639 | +value in memory.stat(see 5.2). | |
| 640 | + | |
| 641 | +5.6 numa_stat | |
| 642 | +------------- | |
| 643 | + | |
| 644 | +This is similar to numa_maps but operates on a per-memcg basis. This is | |
| 645 | +useful for providing visibility into the numa locality information within | |
| 646 | +an memcg since the pages are allowed to be allocated from any physical | |
| 647 | +node. One of the use cases is evaluating application performance by | |
| 648 | +combining this information with the application's CPU allocation. | |
| 649 | + | |
| 650 | +Each memcg's numa_stat file includes "total", "file", "anon" and "unevictable" | |
| 651 | +per-node page counts including "hierarchical_<counter>" which sums up all | |
| 652 | +hierarchical children's values in addition to the memcg's own value. | |
| 653 | + | |
| 654 | +The output format of memory.numa_stat is:: | |
| 655 | + | |
| 656 | + total=<total pages> N0=<node 0 pages> N1=<node 1 pages> ... | |
| 657 | + file=<total file pages> N0=<node 0 pages> N1=<node 1 pages> ... | |
| 658 | + anon=<total anon pages> N0=<node 0 pages> N1=<node 1 pages> ... | |
| 659 | + unevictable=<total anon pages> N0=<node 0 pages> N1=<node 1 pages> ... | |
| 660 | + hierarchical_<counter>=<counter pages> N0=<node 0 pages> N1=<node 1 pages> ... | |
| 661 | + | |
| 662 | +The "total" count is sum of file + anon + unevictable. | |
| 663 | + | |
| 664 | +6. Hierarchy support | |
| 665 | +==================== | |
| 666 | + | |
| 667 | +The memory controller supports a deep hierarchy and hierarchical accounting. | |
| 668 | +The hierarchy is created by creating the appropriate cgroups in the | |
| 669 | +cgroup filesystem. Consider for example, the following cgroup filesystem | |
| 670 | +hierarchy:: | |
| 671 | + | |
| 672 | + root | |
| 673 | + / | \ | |
| 674 | + / | \ | |
| 675 | + a b c | |
| 676 | + | \ | |
| 677 | + | \ | |
| 678 | + d e | |
| 679 | + | |
| 680 | +In the diagram above, with hierarchical accounting enabled, all memory | |
| 681 | +usage of e, is accounted to its ancestors up until the root (i.e, c and root), | |
| 682 | +that has memory.use_hierarchy enabled. If one of the ancestors goes over its | |
| 683 | +limit, the reclaim algorithm reclaims from the tasks in the ancestor and the | |
| 684 | +children of the ancestor. | |
| 685 | + | |
| 686 | +6.1 Enabling hierarchical accounting and reclaim | |
| 687 | +------------------------------------------------ | |
| 688 | + | |
| 689 | +A memory cgroup by default disables the hierarchy feature. Support | |
| 690 | +can be enabled by writing 1 to memory.use_hierarchy file of the root cgroup:: | |
| 691 | + | |
| 692 | + # echo 1 > memory.use_hierarchy | |
| 693 | + | |
| 694 | +The feature can be disabled by:: | |
| 695 | + | |
| 696 | + # echo 0 > memory.use_hierarchy | |
| 697 | + | |
| 698 | +NOTE1: | |
| 699 | + Enabling/disabling will fail if either the cgroup already has other | |
| 700 | + cgroups created below it, or if the parent cgroup has use_hierarchy | |
| 701 | + enabled. | |
| 702 | + | |
| 703 | +NOTE2: | |
| 704 | + When panic_on_oom is set to "2", the whole system will panic in | |
| 705 | + case of an OOM event in any cgroup. | |
| 706 | + | |
| 707 | +7. Soft limits | |
| 708 | +============== | |
| 709 | + | |
| 710 | +Soft limits allow for greater sharing of memory. The idea behind soft limits | |
| 711 | +is to allow control groups to use as much of the memory as needed, provided | |
| 712 | + | |
| 713 | +a. There is no memory contention | |
| 714 | +b. They do not exceed their hard limit | |
| 715 | + | |
| 716 | +When the system detects memory contention or low memory, control groups | |
| 717 | +are pushed back to their soft limits. If the soft limit of each control | |
| 718 | +group is very high, they are pushed back as much as possible to make | |
| 719 | +sure that one control group does not starve the others of memory. | |
| 720 | + | |
| 721 | +Please note that soft limits is a best-effort feature; it comes with | |
| 722 | +no guarantees, but it does its best to make sure that when memory is | |
| 723 | +heavily contended for, memory is allocated based on the soft limit | |
| 724 | +hints/setup. Currently soft limit based reclaim is set up such that | |
| 725 | +it gets invoked from balance_pgdat (kswapd). | |
| 726 | + | |
| 727 | +7.1 Interface | |
| 728 | +------------- | |
| 729 | + | |
| 730 | +Soft limits can be setup by using the following commands (in this example we | |
| 731 | +assume a soft limit of 256 MiB):: | |
| 732 | + | |
| 733 | + # echo 256M > memory.soft_limit_in_bytes | |
| 734 | + | |
| 735 | +If we want to change this to 1G, we can at any time use:: | |
| 736 | + | |
| 737 | + # echo 1G > memory.soft_limit_in_bytes | |
| 738 | + | |
| 739 | +NOTE1: | |
| 740 | + Soft limits take effect over a long period of time, since they involve | |
| 741 | + reclaiming memory for balancing between memory cgroups | |
| 742 | +NOTE2: | |
| 743 | + It is recommended to set the soft limit always below the hard limit, | |
| 744 | + otherwise the hard limit will take precedence. | |
| 745 | + | |
| 746 | +8. Move charges at task migration | |
| 747 | +================================= | |
| 748 | + | |
| 749 | +Users can move charges associated with a task along with task migration, that | |
| 750 | +is, uncharge task's pages from the old cgroup and charge them to the new cgroup. | |
| 751 | +This feature is not supported in !CONFIG_MMU environments because of lack of | |
| 752 | +page tables. | |
| 753 | + | |
| 754 | +8.1 Interface | |
| 755 | +------------- | |
| 756 | + | |
| 757 | +This feature is disabled by default. It can be enabled (and disabled again) by | |
| 758 | +writing to memory.move_charge_at_immigrate of the destination cgroup. | |
| 759 | + | |
| 760 | +If you want to enable it:: | |
| 761 | + | |
| 762 | + # echo (some positive value) > memory.move_charge_at_immigrate | |
| 763 | + | |
| 764 | +Note: | |
| 765 | + Each bits of move_charge_at_immigrate has its own meaning about what type | |
| 766 | + of charges should be moved. See 8.2 for details. | |
| 767 | +Note: | |
| 768 | + Charges are moved only when you move mm->owner, in other words, | |
| 769 | + a leader of a thread group. | |
| 770 | +Note: | |
| 771 | + If we cannot find enough space for the task in the destination cgroup, we | |
| 772 | + try to make space by reclaiming memory. Task migration may fail if we | |
| 773 | + cannot make enough space. | |
| 774 | +Note: | |
| 775 | + It can take several seconds if you move charges much. | |
| 776 | + | |
| 777 | +And if you want disable it again:: | |
| 778 | + | |
| 779 | + # echo 0 > memory.move_charge_at_immigrate | |
| 780 | + | |
| 781 | +8.2 Type of charges which can be moved | |
| 782 | +-------------------------------------- | |
| 783 | + | |
| 784 | +Each bit in move_charge_at_immigrate has its own meaning about what type of | |
| 785 | +charges should be moved. But in any case, it must be noted that an account of | |
| 786 | +a page or a swap can be moved only when it is charged to the task's current | |
| 787 | +(old) memory cgroup. | |
| 788 | + | |
| 789 | ++---+--------------------------------------------------------------------------+ | |
| 790 | +|bit| what type of charges would be moved ? | | |
| 791 | ++===+==========================================================================+ | |
| 792 | +| 0 | A charge of an anonymous page (or swap of it) used by the target task. | | |
| 793 | +| | You must enable Swap Extension (see 2.4) to enable move of swap charges. | | |
| 794 | ++---+--------------------------------------------------------------------------+ | |
| 795 | +| 1 | A charge of file pages (normal file, tmpfs file (e.g. ipc shared memory) | | |
| 796 | +| | and swaps of tmpfs file) mmapped by the target task. Unlike the case of | | |
| 797 | +| | anonymous pages, file pages (and swaps) in the range mmapped by the task | | |
| 798 | +| | will be moved even if the task hasn't done page fault, i.e. they might | | |
| 799 | +| | not be the task's "RSS", but other task's "RSS" that maps the same file. | | |
| 800 | +| | And mapcount of the page is ignored (the page can be moved even if | | |
| 801 | +| | page_mapcount(page) > 1). You must enable Swap Extension (see 2.4) to | | |
| 802 | +| | enable move of swap charges. | | |
| 803 | ++---+--------------------------------------------------------------------------+ | |
| 804 | + | |
| 805 | +8.3 TODO | |
| 806 | +-------- | |
| 807 | + | |
| 808 | +- All of moving charge operations are done under cgroup_mutex. It's not good | |
| 809 | + behavior to hold the mutex too long, so we may need some trick. | |
| 810 | + | |
| 811 | +9. Memory thresholds | |
| 812 | +==================== | |
| 813 | + | |
| 814 | +Memory cgroup implements memory thresholds using the cgroups notification | |
| 815 | +API (see cgroups.txt). It allows to register multiple memory and memsw | |
| 816 | +thresholds and gets notifications when it crosses. | |
| 817 | + | |
| 818 | +To register a threshold, an application must: | |
| 819 | + | |
| 820 | +- create an eventfd using eventfd(2); | |
| 821 | +- open memory.usage_in_bytes or memory.memsw.usage_in_bytes; | |
| 822 | +- write string like "<event_fd> <fd of memory.usage_in_bytes> <threshold>" to | |
| 823 | + cgroup.event_control. | |
| 824 | + | |
| 825 | +Application will be notified through eventfd when memory usage crosses | |
| 826 | +threshold in any direction. | |
| 827 | + | |
| 828 | +It's applicable for root and non-root cgroup. | |
| 829 | + | |
| 830 | +10. OOM Control | |
| 831 | +=============== | |
| 832 | + | |
| 833 | +memory.oom_control file is for OOM notification and other controls. | |
| 834 | + | |
| 835 | +Memory cgroup implements OOM notifier using the cgroup notification | |
| 836 | +API (See cgroups.txt). It allows to register multiple OOM notification | |
| 837 | +delivery and gets notification when OOM happens. | |
| 838 | + | |
| 839 | +To register a notifier, an application must: | |
| 840 | + | |
| 841 | + - create an eventfd using eventfd(2) | |
| 842 | + - open memory.oom_control file | |
| 843 | + - write string like "<event_fd> <fd of memory.oom_control>" to | |
| 844 | + cgroup.event_control | |
| 845 | + | |
| 846 | +The application will be notified through eventfd when OOM happens. | |
| 847 | +OOM notification doesn't work for the root cgroup. | |
| 848 | + | |
| 849 | +You can disable the OOM-killer by writing "1" to memory.oom_control file, as: | |
| 850 | + | |
| 851 | + #echo 1 > memory.oom_control | |
| 852 | + | |
| 853 | +If OOM-killer is disabled, tasks under cgroup will hang/sleep | |
| 854 | +in memory cgroup's OOM-waitqueue when they request accountable memory. | |
| 855 | + | |
| 856 | +For running them, you have to relax the memory cgroup's OOM status by | |
| 857 | + | |
| 858 | + * enlarge limit or reduce usage. | |
| 859 | + | |
| 860 | +To reduce usage, | |
| 861 | + | |
| 862 | + * kill some tasks. | |
| 863 | + * move some tasks to other group with account migration. | |
| 864 | + * remove some files (on tmpfs?) | |
| 865 | + | |
| 866 | +Then, stopped tasks will work again. | |
| 867 | + | |
| 868 | +At reading, current status of OOM is shown. | |
| 869 | + | |
| 870 | + - oom_kill_disable 0 or 1 | |
| 871 | + (if 1, oom-killer is disabled) | |
| 872 | + - under_oom 0 or 1 | |
| 873 | + (if 1, the memory cgroup is under OOM, tasks may be stopped.) | |
| 874 | + | |
| 875 | +11. Memory Pressure | |
| 876 | +=================== | |
| 877 | + | |
| 878 | +The pressure level notifications can be used to monitor the memory | |
| 879 | +allocation cost; based on the pressure, applications can implement | |
| 880 | +different strategies of managing their memory resources. The pressure | |
| 881 | +levels are defined as following: | |
| 882 | + | |
| 883 | +The "low" level means that the system is reclaiming memory for new | |
| 884 | +allocations. Monitoring this reclaiming activity might be useful for | |
| 885 | +maintaining cache level. Upon notification, the program (typically | |
| 886 | +"Activity Manager") might analyze vmstat and act in advance (i.e. | |
| 887 | +prematurely shutdown unimportant services). | |
| 888 | + | |
| 889 | +The "medium" level means that the system is experiencing medium memory | |
| 890 | +pressure, the system might be making swap, paging out active file caches, | |
| 891 | +etc. Upon this event applications may decide to further analyze | |
| 892 | +vmstat/zoneinfo/memcg or internal memory usage statistics and free any | |
| 893 | +resources that can be easily reconstructed or re-read from a disk. | |
| 894 | + | |
| 895 | +The "critical" level means that the system is actively thrashing, it is | |
| 896 | +about to out of memory (OOM) or even the in-kernel OOM killer is on its | |
| 897 | +way to trigger. Applications should do whatever they can to help the | |
| 898 | +system. It might be too late to consult with vmstat or any other | |
| 899 | +statistics, so it's advisable to take an immediate action. | |
| 900 | + | |
| 901 | +By default, events are propagated upward until the event is handled, i.e. the | |
| 902 | +events are not pass-through. For example, you have three cgroups: A->B->C. Now | |
| 903 | +you set up an event listener on cgroups A, B and C, and suppose group C | |
| 904 | +experiences some pressure. In this situation, only group C will receive the | |
| 905 | +notification, i.e. groups A and B will not receive it. This is done to avoid | |
| 906 | +excessive "broadcasting" of messages, which disturbs the system and which is | |
| 907 | +especially bad if we are low on memory or thrashing. Group B, will receive | |
| 908 | +notification only if there are no event listers for group C. | |
| 909 | + | |
| 910 | +There are three optional modes that specify different propagation behavior: | |
| 911 | + | |
| 912 | + - "default": this is the default behavior specified above. This mode is the | |
| 913 | + same as omitting the optional mode parameter, preserved by backwards | |
| 914 | + compatibility. | |
| 915 | + | |
| 916 | + - "hierarchy": events always propagate up to the root, similar to the default | |
| 917 | + behavior, except that propagation continues regardless of whether there are | |
| 918 | + event listeners at each level, with the "hierarchy" mode. In the above | |
| 919 | + example, groups A, B, and C will receive notification of memory pressure. | |
| 920 | + | |
| 921 | + - "local": events are pass-through, i.e. they only receive notifications when | |
| 922 | + memory pressure is experienced in the memcg for which the notification is | |
| 923 | + registered. In the above example, group C will receive notification if | |
| 924 | + registered for "local" notification and the group experiences memory | |
| 925 | + pressure. However, group B will never receive notification, regardless if | |
| 926 | + there is an event listener for group C or not, if group B is registered for | |
| 927 | + local notification. | |
| 928 | + | |
| 929 | +The level and event notification mode ("hierarchy" or "local", if necessary) are | |
| 930 | +specified by a comma-delimited string, i.e. "low,hierarchy" specifies | |
| 931 | +hierarchical, pass-through, notification for all ancestor memcgs. Notification | |
| 932 | +that is the default, non pass-through behavior, does not specify a mode. | |
| 933 | +"medium,local" specifies pass-through notification for the medium level. | |
| 934 | + | |
| 935 | +The file memory.pressure_level is only used to setup an eventfd. To | |
| 936 | +register a notification, an application must: | |
| 937 | + | |
| 938 | +- create an eventfd using eventfd(2); | |
| 939 | +- open memory.pressure_level; | |
| 940 | +- write string as "<event_fd> <fd of memory.pressure_level> <level[,mode]>" | |
| 941 | + to cgroup.event_control. | |
| 942 | + | |
| 943 | +Application will be notified through eventfd when memory pressure is at | |
| 944 | +the specific level (or higher). Read/write operations to | |
| 945 | +memory.pressure_level are no implemented. | |
| 946 | + | |
| 947 | +Test: | |
| 948 | + | |
| 949 | + Here is a small script example that makes a new cgroup, sets up a | |
| 950 | + memory limit, sets up a notification in the cgroup and then makes child | |
| 951 | + cgroup experience a critical pressure:: | |
| 952 | + | |
| 953 | + # cd /sys/fs/cgroup/memory/ | |
| 954 | + # mkdir foo | |
| 955 | + # cd foo | |
| 956 | + # cgroup_event_listener memory.pressure_level low,hierarchy & | |
| 957 | + # echo 8000000 > memory.limit_in_bytes | |
| 958 | + # echo 8000000 > memory.memsw.limit_in_bytes | |
| 959 | + # echo $$ > tasks | |
| 960 | + # dd if=/dev/zero | read x | |
| 961 | + | |
| 962 | + (Expect a bunch of notifications, and eventually, the oom-killer will | |
| 963 | + trigger.) | |
| 964 | + | |
| 965 | +12. TODO | |
| 966 | +======== | |
| 967 | + | |
| 968 | +1. Make per-cgroup scanner reclaim not-shared pages first | |
| 969 | +2. Teach controller to account for shared-pages | |
| 970 | +3. Start reclamation in the background when the limit is | |
| 971 | + not yet hit but the usage is getting closer | |
| 972 | + | |
| 973 | +Summary | |
| 974 | +======= | |
| 975 | + | |
| 976 | +Overall, the memory controller has been a stable controller and has been | |
| 977 | +commented and discussed quite extensively in the community. | |
| 978 | + | |
| 979 | +References | |
| 980 | +========== | |
| 981 | + | |
| 982 | +1. Singh, Balbir. RFC: Memory Controller, http://lwn.net/Articles/206697/ | |
| 983 | +2. Singh, Balbir. Memory Controller (RSS Control), | |
| 984 | + http://lwn.net/Articles/222762/ | |
| 985 | +3. Emelianov, Pavel. Resource controllers based on process cgroups | |
| 986 | + http://lkml.org/lkml/2007/3/6/198 | |
| 987 | +4. Emelianov, Pavel. RSS controller based on process cgroups (v2) | |
| 988 | + http://lkml.org/lkml/2007/4/9/78 | |
| 989 | +5. Emelianov, Pavel. RSS controller based on process cgroups (v3) | |
| 990 | + http://lkml.org/lkml/2007/5/30/244 | |
| 991 | +6. Menage, Paul. Control Groups v10, http://lwn.net/Articles/236032/ | |
| 992 | +7. Vaidyanathan, Srinivasan, Control Groups: Pagecache accounting and control | |
| 993 | + subsystem (v3), http://lwn.net/Articles/235534/ | |
| 994 | +8. Singh, Balbir. RSS controller v2 test results (lmbench), | |
| 995 | + http://lkml.org/lkml/2007/5/17/232 | |
| 996 | +9. Singh, Balbir. RSS controller v2 AIM9 results | |
| 997 | + http://lkml.org/lkml/2007/5/18/1 | |
| 998 | +10. Singh, Balbir. Memory controller v6 test results, | |
| 999 | + http://lkml.org/lkml/2007/8/19/36 | |
| 1000 | +11. Singh, Balbir. Memory controller introduction (v6), | |
| 1001 | + http://lkml.org/lkml/2007/8/17/69 | |
| 1002 | +12. Corbet, Jonathan, Controlling memory use in cgroups, | |
| 1003 | + http://lwn.net/Articles/243795/ | |
| @@ -0,0 +1,44 @@ | ||
| 1 | +========================= | |
| 2 | +Network classifier cgroup | |
| 3 | +========================= | |
| 4 | + | |
| 5 | +The Network classifier cgroup provides an interface to | |
| 6 | +tag network packets with a class identifier (classid). | |
| 7 | + | |
| 8 | +The Traffic Controller (tc) can be used to assign | |
| 9 | +different priorities to packets from different cgroups. | |
| 10 | +Also, Netfilter (iptables) can use this tag to perform | |
| 11 | +actions on such packets. | |
| 12 | + | |
| 13 | +Creating a net_cls cgroups instance creates a net_cls.classid file. | |
| 14 | +This net_cls.classid value is initialized to 0. | |
| 15 | + | |
| 16 | +You can write hexadecimal values to net_cls.classid; the format for these | |
| 17 | +values is 0xAAAABBBB; AAAA is the major handle number and BBBB | |
| 18 | +is the minor handle number. | |
| 19 | +Reading net_cls.classid yields a decimal result. | |
| 20 | + | |
| 21 | +Example:: | |
| 22 | + | |
| 23 | + mkdir /sys/fs/cgroup/net_cls | |
| 24 | + mount -t cgroup -onet_cls net_cls /sys/fs/cgroup/net_cls | |
| 25 | + mkdir /sys/fs/cgroup/net_cls/0 | |
| 26 | + echo 0x100001 > /sys/fs/cgroup/net_cls/0/net_cls.classid | |
| 27 | + | |
| 28 | +- setting a 10:1 handle:: | |
| 29 | + | |
| 30 | + cat /sys/fs/cgroup/net_cls/0/net_cls.classid | |
| 31 | + 1048577 | |
| 32 | + | |
| 33 | +- configuring tc:: | |
| 34 | + | |
| 35 | + tc qdisc add dev eth0 root handle 10: htb | |
| 36 | + tc class add dev eth0 parent 10: classid 10:1 htb rate 40mbit | |
| 37 | + | |
| 38 | +- creating traffic class 10:1:: | |
| 39 | + | |
| 40 | + tc filter add dev eth0 parent 10: protocol ip prio 10 handle 1: cgroup | |
| 41 | + | |
| 42 | +configuring iptables, basic example:: | |
| 43 | + | |
| 44 | + iptables -A OUTPUT -m cgroup ! --cgroup 0x100001 -j DROP | |
| @@ -0,0 +1,57 @@ | ||
| 1 | +======================= | |
| 2 | +Network priority cgroup | |
| 3 | +======================= | |
| 4 | + | |
| 5 | +The Network priority cgroup provides an interface to allow an administrator to | |
| 6 | +dynamically set the priority of network traffic generated by various | |
| 7 | +applications | |
| 8 | + | |
| 9 | +Nominally, an application would set the priority of its traffic via the | |
| 10 | +SO_PRIORITY socket option. This however, is not always possible because: | |
| 11 | + | |
| 12 | +1) The application may not have been coded to set this value | |
| 13 | +2) The priority of application traffic is often a site-specific administrative | |
| 14 | + decision rather than an application defined one. | |
| 15 | + | |
| 16 | +This cgroup allows an administrator to assign a process to a group which defines | |
| 17 | +the priority of egress traffic on a given interface. Network priority groups can | |
| 18 | +be created by first mounting the cgroup filesystem:: | |
| 19 | + | |
| 20 | + # mount -t cgroup -onet_prio none /sys/fs/cgroup/net_prio | |
| 21 | + | |
| 22 | +With the above step, the initial group acting as the parent accounting group | |
| 23 | +becomes visible at '/sys/fs/cgroup/net_prio'. This group includes all tasks in | |
| 24 | +the system. '/sys/fs/cgroup/net_prio/tasks' lists the tasks in this cgroup. | |
| 25 | + | |
| 26 | +Each net_prio cgroup contains two files that are subsystem specific | |
| 27 | + | |
| 28 | +net_prio.prioidx | |
| 29 | + This file is read-only, and is simply informative. It contains a unique | |
| 30 | + integer value that the kernel uses as an internal representation of this | |
| 31 | + cgroup. | |
| 32 | + | |
| 33 | +net_prio.ifpriomap | |
| 34 | + This file contains a map of the priorities assigned to traffic originating | |
| 35 | + from processes in this group and egressing the system on various interfaces. | |
| 36 | + It contains a list of tuples in the form <ifname priority>. Contents of this | |
| 37 | + file can be modified by echoing a string into the file using the same tuple | |
| 38 | + format. For example:: | |
| 39 | + | |
| 40 | + echo "eth0 5" > /sys/fs/cgroups/net_prio/iscsi/net_prio.ifpriomap | |
| 41 | + | |
| 42 | +This command would force any traffic originating from processes belonging to the | |
| 43 | +iscsi net_prio cgroup and egressing on interface eth0 to have the priority of | |
| 44 | +said traffic set to the value 5. The parent accounting group also has a | |
| 45 | +writeable 'net_prio.ifpriomap' file that can be used to set a system default | |
| 46 | +priority. | |
| 47 | + | |
| 48 | +Priorities are set immediately prior to queueing a frame to the device | |
| 49 | +queueing discipline (qdisc) so priorities will be assigned prior to the hardware | |
| 50 | +queue selection being made. | |
| 51 | + | |
| 52 | +One usage for the net_prio cgroup is with mqprio qdisc allowing application | |
| 53 | +traffic to be steered to hardware/driver based traffic classes. These mappings | |
| 54 | +can then be managed by administrators or other networking protocols such as | |
| 55 | +DCBX. | |
| 56 | + | |
| 57 | +A new net_prio cgroup inherits the parent's configuration. | |
| @@ -0,0 +1,92 @@ | ||
| 1 | +========================= | |
| 2 | +Process Number Controller | |
| 3 | +========================= | |
| 4 | + | |
| 5 | +Abstract | |
| 6 | +-------- | |
| 7 | + | |
| 8 | +The process number controller is used to allow a cgroup hierarchy to stop any | |
| 9 | +new tasks from being fork()'d or clone()'d after a certain limit is reached. | |
| 10 | + | |
| 11 | +Since it is trivial to hit the task limit without hitting any kmemcg limits in | |
| 12 | +place, PIDs are a fundamental resource. As such, PID exhaustion must be | |
| 13 | +preventable in the scope of a cgroup hierarchy by allowing resource limiting of | |
| 14 | +the number of tasks in a cgroup. | |
| 15 | + | |
| 16 | +Usage | |
| 17 | +----- | |
| 18 | + | |
| 19 | +In order to use the `pids` controller, set the maximum number of tasks in | |
| 20 | +pids.max (this is not available in the root cgroup for obvious reasons). The | |
| 21 | +number of processes currently in the cgroup is given by pids.current. | |
| 22 | + | |
| 23 | +Organisational operations are not blocked by cgroup policies, so it is possible | |
| 24 | +to have pids.current > pids.max. This can be done by either setting the limit to | |
| 25 | +be smaller than pids.current, or attaching enough processes to the cgroup such | |
| 26 | +that pids.current > pids.max. However, it is not possible to violate a cgroup | |
| 27 | +policy through fork() or clone(). fork() and clone() will return -EAGAIN if the | |
| 28 | +creation of a new process would cause a cgroup policy to be violated. | |
| 29 | + | |
| 30 | +To set a cgroup to have no limit, set pids.max to "max". This is the default for | |
| 31 | +all new cgroups (N.B. that PID limits are hierarchical, so the most stringent | |
| 32 | +limit in the hierarchy is followed). | |
| 33 | + | |
| 34 | +pids.current tracks all child cgroup hierarchies, so parent/pids.current is a | |
| 35 | +superset of parent/child/pids.current. | |
| 36 | + | |
| 37 | +The pids.events file contains event counters: | |
| 38 | + | |
| 39 | + - max: Number of times fork failed because limit was hit. | |
| 40 | + | |
| 41 | +Example | |
| 42 | +------- | |
| 43 | + | |
| 44 | +First, we mount the pids controller:: | |
| 45 | + | |
| 46 | + # mkdir -p /sys/fs/cgroup/pids | |
| 47 | + # mount -t cgroup -o pids none /sys/fs/cgroup/pids | |
| 48 | + | |
| 49 | +Then we create a hierarchy, set limits and attach processes to it:: | |
| 50 | + | |
| 51 | + # mkdir -p /sys/fs/cgroup/pids/parent/child | |
| 52 | + # echo 2 > /sys/fs/cgroup/pids/parent/pids.max | |
| 53 | + # echo $$ > /sys/fs/cgroup/pids/parent/cgroup.procs | |
| 54 | + # cat /sys/fs/cgroup/pids/parent/pids.current | |
| 55 | + 2 | |
| 56 | + # | |
| 57 | + | |
| 58 | +It should be noted that attempts to overcome the set limit (2 in this case) will | |
| 59 | +fail:: | |
| 60 | + | |
| 61 | + # cat /sys/fs/cgroup/pids/parent/pids.current | |
| 62 | + 2 | |
| 63 | + # ( /bin/echo "Here's some processes for you." | cat ) | |
| 64 | + sh: fork: Resource temporary unavailable | |
| 65 | + # | |
| 66 | + | |
| 67 | +Even if we migrate to a child cgroup (which doesn't have a set limit), we will | |
| 68 | +not be able to overcome the most stringent limit in the hierarchy (in this case, | |
| 69 | +parent's):: | |
| 70 | + | |
| 71 | + # echo $$ > /sys/fs/cgroup/pids/parent/child/cgroup.procs | |
| 72 | + # cat /sys/fs/cgroup/pids/parent/pids.current | |
| 73 | + 2 | |
| 74 | + # cat /sys/fs/cgroup/pids/parent/child/pids.current | |
| 75 | + 2 | |
| 76 | + # cat /sys/fs/cgroup/pids/parent/child/pids.max | |
| 77 | + max | |
| 78 | + # ( /bin/echo "Here's some processes for you." | cat ) | |
| 79 | + sh: fork: Resource temporary unavailable | |
| 80 | + # | |
| 81 | + | |
| 82 | +We can set a limit that is smaller than pids.current, which will stop any new | |
| 83 | +processes from being forked at all (note that the shell itself counts towards | |
| 84 | +pids.current):: | |
| 85 | + | |
| 86 | + # echo 1 > /sys/fs/cgroup/pids/parent/pids.max | |
| 87 | + # /bin/echo "We can't even spawn a single process now." | |
| 88 | + sh: fork: Resource temporary unavailable | |
| 89 | + # echo 0 > /sys/fs/cgroup/pids/parent/pids.max | |
| 90 | + # /bin/echo "We can't even spawn a single process now." | |
| 91 | + sh: fork: Resource temporary unavailable | |
| 92 | + # | |
| @@ -0,0 +1,117 @@ | ||
| 1 | +=============== | |
| 2 | +RDMA Controller | |
| 3 | +=============== | |
| 4 | + | |
| 5 | +.. Contents | |
| 6 | + | |
| 7 | + 1. Overview | |
| 8 | + 1-1. What is RDMA controller? | |
| 9 | + 1-2. Why RDMA controller needed? | |
| 10 | + 1-3. How is RDMA controller implemented? | |
| 11 | + 2. Usage Examples | |
| 12 | + | |
| 13 | +1. Overview | |
| 14 | +=========== | |
| 15 | + | |
| 16 | +1-1. What is RDMA controller? | |
| 17 | +----------------------------- | |
| 18 | + | |
| 19 | +RDMA controller allows user to limit RDMA/IB specific resources that a given | |
| 20 | +set of processes can use. These processes are grouped using RDMA controller. | |
| 21 | + | |
| 22 | +RDMA controller defines two resources which can be limited for processes of a | |
| 23 | +cgroup. | |
| 24 | + | |
| 25 | +1-2. Why RDMA controller needed? | |
| 26 | +-------------------------------- | |
| 27 | + | |
| 28 | +Currently user space applications can easily take away all the rdma verb | |
| 29 | +specific resources such as AH, CQ, QP, MR etc. Due to which other applications | |
| 30 | +in other cgroup or kernel space ULPs may not even get chance to allocate any | |
| 31 | +rdma resources. This can lead to service unavailability. | |
| 32 | + | |
| 33 | +Therefore RDMA controller is needed through which resource consumption | |
| 34 | +of processes can be limited. Through this controller different rdma | |
| 35 | +resources can be accounted. | |
| 36 | + | |
| 37 | +1-3. How is RDMA controller implemented? | |
| 38 | +---------------------------------------- | |
| 39 | + | |
| 40 | +RDMA cgroup allows limit configuration of resources. Rdma cgroup maintains | |
| 41 | +resource accounting per cgroup, per device using resource pool structure. | |
| 42 | +Each such resource pool is limited up to 64 resources in given resource pool | |
| 43 | +by rdma cgroup, which can be extended later if required. | |
| 44 | + | |
| 45 | +This resource pool object is linked to the cgroup css. Typically there | |
| 46 | +are 0 to 4 resource pool instances per cgroup, per device in most use cases. | |
| 47 | +But nothing limits to have it more. At present hundreds of RDMA devices per | |
| 48 | +single cgroup may not be handled optimally, however there is no | |
| 49 | +known use case or requirement for such configuration either. | |
| 50 | + | |
| 51 | +Since RDMA resources can be allocated from any process and can be freed by any | |
| 52 | +of the child processes which shares the address space, rdma resources are | |
| 53 | +always owned by the creator cgroup css. This allows process migration from one | |
| 54 | +to other cgroup without major complexity of transferring resource ownership; | |
| 55 | +because such ownership is not really present due to shared nature of | |
| 56 | +rdma resources. Linking resources around css also ensures that cgroups can be | |
| 57 | +deleted after processes migrated. This allow progress migration as well with | |
| 58 | +active resources, even though that is not a primary use case. | |
| 59 | + | |
| 60 | +Whenever RDMA resource charging occurs, owner rdma cgroup is returned to | |
| 61 | +the caller. Same rdma cgroup should be passed while uncharging the resource. | |
| 62 | +This also allows process migrated with active RDMA resource to charge | |
| 63 | +to new owner cgroup for new resource. It also allows to uncharge resource of | |
| 64 | +a process from previously charged cgroup which is migrated to new cgroup, | |
| 65 | +even though that is not a primary use case. | |
| 66 | + | |
| 67 | +Resource pool object is created in following situations. | |
| 68 | +(a) User sets the limit and no previous resource pool exist for the device | |
| 69 | +of interest for the cgroup. | |
| 70 | +(b) No resource limits were configured, but IB/RDMA stack tries to | |
| 71 | +charge the resource. So that it correctly uncharge them when applications are | |
| 72 | +running without limits and later on when limits are enforced during uncharging, | |
| 73 | +otherwise usage count will drop to negative. | |
| 74 | + | |
| 75 | +Resource pool is destroyed if all the resource limits are set to max and | |
| 76 | +it is the last resource getting deallocated. | |
| 77 | + | |
| 78 | +User should set all the limit to max value if it intents to remove/unconfigure | |
| 79 | +the resource pool for a particular device. | |
| 80 | + | |
| 81 | +IB stack honors limits enforced by the rdma controller. When application | |
| 82 | +query about maximum resource limits of IB device, it returns minimum of | |
| 83 | +what is configured by user for a given cgroup and what is supported by | |
| 84 | +IB device. | |
| 85 | + | |
| 86 | +Following resources can be accounted by rdma controller. | |
| 87 | + | |
| 88 | + ========== ============================= | |
| 89 | + hca_handle Maximum number of HCA Handles | |
| 90 | + hca_object Maximum number of HCA Objects | |
| 91 | + ========== ============================= | |
| 92 | + | |
| 93 | +2. Usage Examples | |
| 94 | +================= | |
| 95 | + | |
| 96 | +(a) Configure resource limit:: | |
| 97 | + | |
| 98 | + echo mlx4_0 hca_handle=2 hca_object=2000 > /sys/fs/cgroup/rdma/1/rdma.max | |
| 99 | + echo ocrdma1 hca_handle=3 > /sys/fs/cgroup/rdma/2/rdma.max | |
| 100 | + | |
| 101 | +(b) Query resource limit:: | |
| 102 | + | |
| 103 | + cat /sys/fs/cgroup/rdma/2/rdma.max | |
| 104 | + #Output: | |
| 105 | + mlx4_0 hca_handle=2 hca_object=2000 | |
| 106 | + ocrdma1 hca_handle=3 hca_object=max | |
| 107 | + | |
| 108 | +(c) Query current usage:: | |
| 109 | + | |
| 110 | + cat /sys/fs/cgroup/rdma/2/rdma.current | |
| 111 | + #Output: | |
| 112 | + mlx4_0 hca_handle=1 hca_object=20 | |
| 113 | + ocrdma1 hca_handle=1 hca_object=23 | |
| 114 | + | |
| 115 | +(d) Delete resource limit:: | |
| 116 | + | |
| 117 | + echo echo mlx4_0 hca_handle=max hca_object=max > /sys/fs/cgroup/rdma/1/rdma.max | |
| @@ -9,7 +9,7 @@ This is the authoritative documentation on the design, interface and · 8 unmodified lines | ||
| 9 | 9 | conventions of cgroup v2. It describes all userland-visible aspects |
| 10 | 10 | of cgroup including core and specific controller behaviors. All |
| 11 | 11 | future changes must be reflected in this document. Documentation for |
| 12 | −v1 is available under Documentation/cgroup-v1/. | |
| 12 | +v1 is available under Documentation/admin-guide/cgroup-v1/. | |
| 13 | 13 | |
| 14 | 14 | .. CONTENTS |
| 15 | 15 | |
| @@ -705,6 +705,12 @@ Conventions · 689 unmodified lines | ||
| 705 | 705 | informational files on the root cgroup which end up showing global |
| 706 | 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 | 714 | - If a controller implements weight based resource distribution, its |
| 709 | 715 | interface file should be named "weight" and have the range [1, |
| 710 | 716 | 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 | 1014 | A read-only nested-key file which exists on non-root cgroups. |
| 1009 | 1015 | |
| 1010 | 1016 | 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 | |
| 1014 | 1020 | Memory |
| @@ -1140,6 +1146,11 @@ PAGE_SIZE multiple when read back. · 125 unmodified lines | ||
| 1140 | 1146 | otherwise, a value change in this file generates a file |
| 1141 | 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 | 1154 | low |
| 1144 | 1155 | The number of times the cgroup is reclaimed due to |
| 1145 | 1156 | high memory pressure even though its usage is under |
| @@ -1179,6 +1190,11 @@ PAGE_SIZE multiple when read back. · 33 unmodified lines | ||
| 1179 | 1190 | The number of processes belonging to this cgroup |
| 1180 | 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 | 1198 | memory.stat |
| 1183 | 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 | 1355 | A read-only nested-key file which exists on non-root cgroups. |
| 1340 | 1356 | |
| 1341 | 1357 | 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 | |
| 1345 | 1361 | Usage Guidelines |
| @@ -1482,7 +1498,7 @@ IO Interface Files · 136 unmodified lines | ||
| 1482 | 1498 | A read-only nested-key file which exists on non-root cgroups. |
| 1483 | 1499 | |
| 1484 | 1500 | 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 | |
| 1488 | 1504 | Writeback |
| @@ -2108,7 +2124,7 @@ following two functions. · 619 unmodified lines | ||
| 2108 | 2124 | a queue (device) has been associated with the bio and |
| 2109 | 2125 | before submission. |
| 2110 | 2126 | |
| 2111 | − wbc_account_io(@wbc, @page, @bytes) | |
| 2127 | + wbc_account_cgroup_owner(@wbc, @page, @bytes) | |
| 2112 | 2128 | Should be called for each data segment being written out. |
| 2113 | 2129 | While this function doesn't care exactly when it's called |
| 2114 | 2130 | during the writeback session, it's the easiest and most |
File renamed without changes.
| @@ -1,10 +0,0 @@ | ||
| 1 | −# -*- coding: utf-8; mode: python -*- | |
| 2 | − | |
| 3 | −project = 'Linux Kernel User Documentation' | |
| 4 | − | |
| 5 | −tags.add("subproject") | |
| 6 | − | |
| 7 | −latex_documents = [ | |
| 8 | − ('index', 'linux-user.tex', 'Linux Kernel User Documentation', | |
| 9 | − 'The kernel development community', 'manual'), | |
| 10 | −] | |
File renamed without changes.
| @@ -0,0 +1,177 @@ | ||
| 1 | +=========================================== | |
| 2 | +How CPU topology info is exported via sysfs | |
| 3 | +=========================================== | |
| 4 | + | |
| 5 | +Export CPU topology info via sysfs. Items (attributes) are similar | |
| 6 | +to /proc/cpuinfo output of some architectures. They reside in | |
| 7 | +/sys/devices/system/cpu/cpuX/topology/: | |
| 8 | + | |
| 9 | +physical_package_id: | |
| 10 | + | |
| 11 | + physical package id of cpuX. Typically corresponds to a physical | |
| 12 | + socket number, but the actual value is architecture and platform | |
| 13 | + dependent. | |
| 14 | + | |
| 15 | +die_id: | |
| 16 | + | |
| 17 | + the CPU die ID of cpuX. Typically it is the hardware platform's | |
| 18 | + identifier (rather than the kernel's). The actual value is | |
| 19 | + architecture and platform dependent. | |
| 20 | + | |
| 21 | +core_id: | |
| 22 | + | |
| 23 | + the CPU core ID of cpuX. Typically it is the hardware platform's | |
| 24 | + identifier (rather than the kernel's). The actual value is | |
| 25 | + architecture and platform dependent. | |
| 26 | + | |
| 27 | +book_id: | |
| 28 | + | |
| 29 | + the book ID of cpuX. Typically it is the hardware platform's | |
| 30 | + identifier (rather than the kernel's). The actual value is | |
| 31 | + architecture and platform dependent. | |
| 32 | + | |
| 33 | +drawer_id: | |
| 34 | + | |
| 35 | + the drawer ID of cpuX. Typically it is the hardware platform's | |
| 36 | + identifier (rather than the kernel's). The actual value is | |
| 37 | + architecture and platform dependent. | |
| 38 | + | |
| 39 | +core_cpus: | |
| 40 | + | |
| 41 | + internal kernel map of CPUs within the same core. | |
| 42 | + (deprecated name: "thread_siblings") | |
| 43 | + | |
| 44 | +core_cpus_list: | |
| 45 | + | |
| 46 | + human-readable list of CPUs within the same core. | |
| 47 | + (deprecated name: "thread_siblings_list"); | |
| 48 | + | |
| 49 | +package_cpus: | |
| 50 | + | |
| 51 | + internal kernel map of the CPUs sharing the same physical_package_id. | |
| 52 | + (deprecated name: "core_siblings") | |
| 53 | + | |
| 54 | +package_cpus_list: | |
| 55 | + | |
| 56 | + human-readable list of CPUs sharing the same physical_package_id. | |
| 57 | + (deprecated name: "core_siblings_list") | |
| 58 | + | |
| 59 | +die_cpus: | |
| 60 | + | |
| 61 | + internal kernel map of CPUs within the same die. | |
| 62 | + | |
| 63 | +die_cpus_list: | |
| 64 | + | |
| 65 | + human-readable list of CPUs within the same die. | |
| 66 | + | |
| 67 | +book_siblings: | |
| 68 | + | |
| 69 | + internal kernel map of cpuX's hardware threads within the same | |
| 70 | + book_id. | |
| 71 | + | |
| 72 | +book_siblings_list: | |
| 73 | + | |
| 74 | + human-readable list of cpuX's hardware threads within the same | |
| 75 | + book_id. | |
| 76 | + | |
| 77 | +drawer_siblings: | |
| 78 | + | |
| 79 | + internal kernel map of cpuX's hardware threads within the same | |
| 80 | + drawer_id. | |
| 81 | + | |
| 82 | +drawer_siblings_list: | |
| 83 | + | |
| 84 | + human-readable list of cpuX's hardware threads within the same | |
| 85 | + drawer_id. | |
| 86 | + | |
| 87 | +Architecture-neutral, drivers/base/topology.c, exports these attributes. | |
| 88 | +However, the book and drawer related sysfs files will only be created if | |
| 89 | +CONFIG_SCHED_BOOK and CONFIG_SCHED_DRAWER are selected, respectively. | |
| 90 | + | |
| 91 | +CONFIG_SCHED_BOOK and CONFIG_SCHED_DRAWER are currently only used on s390, | |
| 92 | +where they reflect the cpu and cache hierarchy. | |
| 93 | + | |
| 94 | +For an architecture to support this feature, it must define some of | |
| 95 | +these macros in include/asm-XXX/topology.h:: | |
| 96 | + | |
| 97 | + #define topology_physical_package_id(cpu) | |
| 98 | + #define topology_die_id(cpu) | |
| 99 | + #define topology_core_id(cpu) | |
| 100 | + #define topology_book_id(cpu) | |
| 101 | + #define topology_drawer_id(cpu) | |
| 102 | + #define topology_sibling_cpumask(cpu) | |
| 103 | + #define topology_core_cpumask(cpu) | |
| 104 | + #define topology_die_cpumask(cpu) | |
| 105 | + #define topology_book_cpumask(cpu) | |
| 106 | + #define topology_drawer_cpumask(cpu) | |
| 107 | + | |
| 108 | +The type of ``**_id macros`` is int. | |
| 109 | +The type of ``**_cpumask macros`` is ``(const) struct cpumask *``. The latter | |
| 110 | +correspond with appropriate ``**_siblings`` sysfs attributes (except for | |
| 111 | +topology_sibling_cpumask() which corresponds with thread_siblings). | |
| 112 | + | |
| 113 | +To be consistent on all architectures, include/linux/topology.h | |
| 114 | +provides default definitions for any of the above macros that are | |
| 115 | +not defined by include/asm-XXX/topology.h: | |
| 116 | + | |
| 117 | +1) topology_physical_package_id: -1 | |
| 118 | +2) topology_die_id: -1 | |
| 119 | +3) topology_core_id: 0 | |
| 120 | +4) topology_sibling_cpumask: just the given CPU | |
| 121 | +5) topology_core_cpumask: just the given CPU | |
| 122 | +6) topology_die_cpumask: just the given CPU | |
| 123 | + | |
| 124 | +For architectures that don't support books (CONFIG_SCHED_BOOK) there are no | |
| 125 | +default definitions for topology_book_id() and topology_book_cpumask(). | |
| 126 | +For architectures that don't support drawers (CONFIG_SCHED_DRAWER) there are | |
| 127 | +no default definitions for topology_drawer_id() and topology_drawer_cpumask(). | |
| 128 | + | |
| 129 | +Additionally, CPU topology information is provided under | |
| 130 | +/sys/devices/system/cpu and includes these files. The internal | |
| 131 | +source for the output is in brackets ("[]"). | |
| 132 | + | |
| 133 | + =========== ========================================================== | |
| 134 | + kernel_max: the maximum CPU index allowed by the kernel configuration. | |
| 135 | + [NR_CPUS-1] | |
| 136 | + | |
| 137 | + offline: CPUs that are not online because they have been | |
| 138 | + HOTPLUGGED off (see cpu-hotplug.txt) or exceed the limit | |
| 139 | + of CPUs allowed by the kernel configuration (kernel_max | |
| 140 | + above). [~cpu_online_mask + cpus >= NR_CPUS] | |
| 141 | + | |
| 142 | + online: CPUs that are online and being scheduled [cpu_online_mask] | |
| 143 | + | |
| 144 | + possible: CPUs that have been allocated resources and can be | |
| 145 | + brought online if they are present. [cpu_possible_mask] | |
| 146 | + | |
| 147 | + present: CPUs that have been identified as being present in the | |
| 148 | + system. [cpu_present_mask] | |
| 149 | + =========== ========================================================== | |
| 150 | + | |
| 151 | +The format for the above output is compatible with cpulist_parse() | |
| 152 | +[see <linux/cpumask.h>]. Some examples follow. | |
| 153 | + | |
| 154 | +In this example, there are 64 CPUs in the system but cpus 32-63 exceed | |
| 155 | +the kernel max which is limited to 0..31 by the NR_CPUS config option | |
| 156 | +being 32. Note also that CPUs 2 and 4-31 are not online but could be | |
| 157 | +brought online as they are both present and possible:: | |
| 158 | + | |
| 159 | + kernel_max: 31 | |
| 160 | + offline: 2,4-31,32-63 | |
| 161 | + online: 0-1,3 | |
| 162 | + possible: 0-31 | |
| 163 | + present: 0-31 | |
| 164 | + | |
| 165 | +In this example, the NR_CPUS config option is 128, but the kernel was | |
| 166 | +started with possible_cpus=144. There are 4 CPUs in the system and cpu2 | |
| 167 | +was manually taken offline (and is the only CPU that can be brought | |
| 168 | +online.):: | |
| 169 | + | |
| 170 | + kernel_max: 127 | |
| 171 | + offline: 2,4-127,128-143 | |
| 172 | + online: 0-1,3 | |
| 173 | + possible: 0-127 | |
| 174 | + present: 0-3 | |
| 175 | + | |
| 176 | +See cpu-hotplug.txt for the possible_cpus=NUM kernel start parameter | |
| 177 | +as well as more information on the various cpumasks. | |
| @@ -0,0 +1,131 @@ | ||
| 1 | +============================= | |
| 2 | +Guidance for writing policies | |
| 3 | +============================= | |
| 4 | + | |
| 5 | +Try to keep transactionality out of it. The core is careful to | |
| 6 | +avoid asking about anything that is migrating. This is a pain, but | |
| 7 | +makes it easier to write the policies. | |
| 8 | + | |
| 9 | +Mappings are loaded into the policy at construction time. | |
| 10 | + | |
| 11 | +Every bio that is mapped by the target is referred to the policy. | |
| 12 | +The policy can return a simple HIT or MISS or issue a migration. | |
| 13 | + | |
| 14 | +Currently there's no way for the policy to issue background work, | |
| 15 | +e.g. to start writing back dirty blocks that are going to be evicted | |
| 16 | +soon. | |
| 17 | + | |
| 18 | +Because we map bios, rather than requests it's easy for the policy | |
| 19 | +to get fooled by many small bios. For this reason the core target | |
| 20 | +issues periodic ticks to the policy. It's suggested that the policy | |
| 21 | +doesn't update states (eg, hit counts) for a block more than once | |
| 22 | +for each tick. The core ticks by watching bios complete, and so | |
| 23 | +trying to see when the io scheduler has let the ios run. | |
| 24 | + | |
| 25 | + | |
| 26 | +Overview of supplied cache replacement policies | |
| 27 | +=============================================== | |
| 28 | + | |
| 29 | +multiqueue (mq) | |
| 30 | +--------------- | |
| 31 | + | |
| 32 | +This policy is now an alias for smq (see below). | |
| 33 | + | |
| 34 | +The following tunables are accepted, but have no effect:: | |
| 35 | + | |
| 36 | + 'sequential_threshold <#nr_sequential_ios>' | |
| 37 | + 'random_threshold <#nr_random_ios>' | |
| 38 | + 'read_promote_adjustment <value>' | |
| 39 | + 'write_promote_adjustment <value>' | |
| 40 | + 'discard_promote_adjustment <value>' | |
| 41 | + | |
| 42 | +Stochastic multiqueue (smq) | |
| 43 | +--------------------------- | |
| 44 | + | |
| 45 | +This policy is the default. | |
| 46 | + | |
| 47 | +The stochastic multi-queue (smq) policy addresses some of the problems | |
| 48 | +with the multiqueue (mq) policy. | |
| 49 | + | |
| 50 | +The smq policy (vs mq) offers the promise of less memory utilization, | |
| 51 | +improved performance and increased adaptability in the face of changing | |
| 52 | +workloads. smq also does not have any cumbersome tuning knobs. | |
| 53 | + | |
| 54 | +Users may switch from "mq" to "smq" simply by appropriately reloading a | |
| 55 | +DM table that is using the cache target. Doing so will cause all of the | |
| 56 | +mq policy's hints to be dropped. Also, performance of the cache may | |
| 57 | +degrade slightly until smq recalculates the origin device's hotspots | |
| 58 | +that should be cached. | |
| 59 | + | |
| 60 | +Memory usage | |
| 61 | +^^^^^^^^^^^^ | |
| 62 | + | |
| 63 | +The mq policy used a lot of memory; 88 bytes per cache block on a 64 | |
| 64 | +bit machine. | |
| 65 | + | |
| 66 | +smq uses 28bit indexes to implement its data structures rather than | |
| 67 | +pointers. It avoids storing an explicit hit count for each block. It | |
| 68 | +has a 'hotspot' queue, rather than a pre-cache, which uses a quarter of | |
| 69 | +the entries (each hotspot block covers a larger area than a single | |
| 70 | +cache block). | |
| 71 | + | |
| 72 | +All this means smq uses ~25bytes per cache block. Still a lot of | |
| 73 | +memory, but a substantial improvement nontheless. | |
| 74 | + | |
| 75 | +Level balancing | |
| 76 | +^^^^^^^^^^^^^^^ | |
| 77 | + | |
| 78 | +mq placed entries in different levels of the multiqueue structures | |
| 79 | +based on their hit count (~ln(hit count)). This meant the bottom | |
| 80 | +levels generally had the most entries, and the top ones had very | |
| 81 | +few. Having unbalanced levels like this reduced the efficacy of the | |
| 82 | +multiqueue. | |
| 83 | + | |
| 84 | +smq does not maintain a hit count, instead it swaps hit entries with | |
| 85 | +the least recently used entry from the level above. The overall | |
| 86 | +ordering being a side effect of this stochastic process. With this | |
| 87 | +scheme we can decide how many entries occupy each multiqueue level, | |
| 88 | +resulting in better promotion/demotion decisions. | |
| 89 | + | |
| 90 | +Adaptability: | |
| 91 | +The mq policy maintained a hit count for each cache block. For a | |
| 92 | +different block to get promoted to the cache its hit count has to | |
| 93 | +exceed the lowest currently in the cache. This meant it could take a | |
| 94 | +long time for the cache to adapt between varying IO patterns. | |
| 95 | + | |
| 96 | +smq doesn't maintain hit counts, so a lot of this problem just goes | |
| 97 | +away. In addition it tracks performance of the hotspot queue, which | |
| 98 | +is used to decide which blocks to promote. If the hotspot queue is | |
| 99 | +performing badly then it starts moving entries more quickly between | |
| 100 | +levels. This lets it adapt to new IO patterns very quickly. | |
| 101 | + | |
| 102 | +Performance | |
| 103 | +^^^^^^^^^^^ | |
| 104 | + | |
| 105 | +Testing smq shows substantially better performance than mq. | |
| 106 | + | |
| 107 | +cleaner | |
| 108 | +------- | |
| 109 | + | |
| 110 | +The cleaner writes back all dirty blocks in a cache to decommission it. | |
| 111 | + | |
| 112 | +Examples | |
| 113 | +======== | |
| 114 | + | |
| 115 | +The syntax for a table is:: | |
| 116 | + | |
| 117 | + cache <metadata dev> <cache dev> <origin dev> <block size> | |
| 118 | + <#feature_args> [<feature arg>]* | |
| 119 | + <policy> <#policy_args> [<policy arg>]* | |
| 120 | + | |
| 121 | +The syntax to send a message using the dmsetup command is:: | |
| 122 | + | |
| 123 | + dmsetup message <mapped device> 0 sequential_threshold 1024 | |
| 124 | + dmsetup message <mapped device> 0 random_threshold 8 | |
| 125 | + | |
| 126 | +Using dmsetup:: | |
| 127 | + | |
| 128 | + dmsetup create blah --table "0 268435456 cache /dev/sdb /dev/sdc \ | |
| 129 | + /dev/sdd 512 0 mq 4 sequential_threshold 1024 random_threshold 8" | |
| 130 | + creates a 128GB large mapped device named 'blah' with the | |
| 131 | + sequential threshold set to 1024 and the random_threshold set to 8. | |
| @@ -0,0 +1,337 @@ | ||
| 1 | +===== | |
| 2 | +Cache | |
| 3 | +===== | |
| 4 | + | |
| 5 | +Introduction | |
| 6 | +============ | |
| 7 | + | |
| 8 | +dm-cache is a device mapper target written by Joe Thornber, Heinz | |
| 9 | +Mauelshagen, and Mike Snitzer. | |
| 10 | + | |
| 11 | +It aims to improve performance of a block device (eg, a spindle) by | |
| 12 | +dynamically migrating some of its data to a faster, smaller device | |
| 13 | +(eg, an SSD). | |
| 14 | + | |
| 15 | +This device-mapper solution allows us to insert this caching at | |
| 16 | +different levels of the dm stack, for instance above the data device for | |
| 17 | +a thin-provisioning pool. Caching solutions that are integrated more | |
| 18 | +closely with the virtual memory system should give better performance. | |
| 19 | + | |
| 20 | +The target reuses the metadata library used in the thin-provisioning | |
| 21 | +library. | |
| 22 | + | |
| 23 | +The decision as to what data to migrate and when is left to a plug-in | |
| 24 | +policy module. Several of these have been written as we experiment, | |
| 25 | +and we hope other people will contribute others for specific io | |
| 26 | +scenarios (eg. a vm image server). | |
| 27 | + | |
| 28 | +Glossary | |
| 29 | +======== | |
| 30 | + | |
| 31 | + Migration | |
| 32 | + Movement of the primary copy of a logical block from one | |
| 33 | + device to the other. | |
| 34 | + Promotion | |
| 35 | + Migration from slow device to fast device. | |
| 36 | + Demotion | |
| 37 | + Migration from fast device to slow device. | |
| 38 | + | |
| 39 | +The origin device always contains a copy of the logical block, which | |
| 40 | +may be out of date or kept in sync with the copy on the cache device | |
| 41 | +(depending on policy). | |
| 42 | + | |
| 43 | +Design | |
| 44 | +====== | |
| 45 | + | |
| 46 | +Sub-devices | |
| 47 | +----------- | |
| 48 | + | |
| 49 | +The target is constructed by passing three devices to it (along with | |
| 50 | +other parameters detailed later): | |
| 51 | + | |
| 52 | +1. An origin device - the big, slow one. | |
| 53 | + | |
| 54 | +2. A cache device - the small, fast one. | |
| 55 | + | |
| 56 | +3. A small metadata device - records which blocks are in the cache, | |
| 57 | + which are dirty, and extra hints for use by the policy object. | |
| 58 | + This information could be put on the cache device, but having it | |
| 59 | + separate allows the volume manager to configure it differently, | |
| 60 | + e.g. as a mirror for extra robustness. This metadata device may only | |
| 61 | + be used by a single cache device. | |
| 62 | + | |
| 63 | +Fixed block size | |
| 64 | +---------------- | |
| 65 | + | |
| 66 | +The origin is divided up into blocks of a fixed size. This block size | |
| 67 | +is configurable when you first create the cache. Typically we've been | |
| 68 | +using block sizes of 256KB - 1024KB. The block size must be between 64 | |
| 69 | +sectors (32KB) and 2097152 sectors (1GB) and a multiple of 64 sectors (32KB). | |
| 70 | + | |
| 71 | +Having a fixed block size simplifies the target a lot. But it is | |
| 72 | +something of a compromise. For instance, a small part of a block may be | |
| 73 | +getting hit a lot, yet the whole block will be promoted to the cache. | |
| 74 | +So large block sizes are bad because they waste cache space. And small | |
| 75 | +block sizes are bad because they increase the amount of metadata (both | |
| 76 | +in core and on disk). | |
| 77 | + | |
| 78 | +Cache operating modes | |
| 79 | +--------------------- | |
| 80 | + | |
| 81 | +The cache has three operating modes: writeback, writethrough and | |
| 82 | +passthrough. | |
| 83 | + | |
| 84 | +If writeback, the default, is selected then a write to a block that is | |
| 85 | +cached will go only to the cache and the block will be marked dirty in | |
| 86 | +the metadata. | |
| 87 | + | |
| 88 | +If writethrough is selected then a write to a cached block will not | |
| 89 | +complete until it has hit both the origin and cache devices. Clean | |
| 90 | +blocks should remain clean. | |
| 91 | + | |
| 92 | +If passthrough is selected, useful when the cache contents are not known | |
| 93 | +to be coherent with the origin device, then all reads are served from | |
| 94 | +the origin device (all reads miss the cache) and all writes are | |
| 95 | +forwarded to the origin device; additionally, write hits cause cache | |
| 96 | +block invalidates. To enable passthrough mode the cache must be clean. | |
| 97 | +Passthrough mode allows a cache device to be activated without having to | |
| 98 | +worry about coherency. Coherency that exists is maintained, although | |
| 99 | +the cache will gradually cool as writes take place. If the coherency of | |
| 100 | +the cache can later be verified, or established through use of the | |
| 101 | +"invalidate_cblocks" message, the cache device can be transitioned to | |
| 102 | +writethrough or writeback mode while still warm. Otherwise, the cache | |
| 103 | +contents can be discarded prior to transitioning to the desired | |
| 104 | +operating mode. | |
| 105 | + | |
| 106 | +A simple cleaner policy is provided, which will clean (write back) all | |
| 107 | +dirty blocks in a cache. Useful for decommissioning a cache or when | |
| 108 | +shrinking a cache. Shrinking the cache's fast device requires all cache | |
| 109 | +blocks, in the area of the cache being removed, to be clean. If the | |
| 110 | +area being removed from the cache still contains dirty blocks the resize | |
| 111 | +will fail. Care must be taken to never reduce the volume used for the | |
| 112 | +cache's fast device until the cache is clean. This is of particular | |
| 113 | +importance if writeback mode is used. Writethrough and passthrough | |
| 114 | +modes already maintain a clean cache. Future support to partially clean | |
| 115 | +the cache, above a specified threshold, will allow for keeping the cache | |
| 116 | +warm and in writeback mode during resize. | |
| 117 | + | |
| 118 | +Migration throttling | |
| 119 | +-------------------- | |
| 120 | + | |
| 121 | +Migrating data between the origin and cache device uses bandwidth. | |
| 122 | +The user can set a throttle to prevent more than a certain amount of | |
| 123 | +migration occurring at any one time. Currently we're not taking any | |
| 124 | +account of normal io traffic going to the devices. More work needs | |
| 125 | +doing here to avoid migrating during those peak io moments. | |
| 126 | + | |
| 127 | +For the time being, a message "migration_threshold <#sectors>" | |
| 128 | +can be used to set the maximum number of sectors being migrated, | |
| 129 | +the default being 2048 sectors (1MB). | |
| 130 | + | |
| 131 | +Updating on-disk metadata | |
| 132 | +------------------------- | |
| 133 | + | |
| 134 | +On-disk metadata is committed every time a FLUSH or FUA bio is written. | |
| 135 | +If no such requests are made then commits will occur every second. This | |
| 136 | +means the cache behaves like a physical disk that has a volatile write | |
| 137 | +cache. If power is lost you may lose some recent writes. The metadata | |
| 138 | +should always be consistent in spite of any crash. | |
| 139 | + | |
| 140 | +The 'dirty' state for a cache block changes far too frequently for us | |
| 141 | +to keep updating it on the fly. So we treat it as a hint. In normal | |
| 142 | +operation it will be written when the dm device is suspended. If the | |
| 143 | +system crashes all cache blocks will be assumed dirty when restarted. | |
| 144 | + | |
| 145 | +Per-block policy hints | |
| 146 | +---------------------- | |
| 147 | + | |
| 148 | +Policy plug-ins can store a chunk of data per cache block. It's up to | |
| 149 | +the policy how big this chunk is, but it should be kept small. Like the | |
| 150 | +dirty flags this data is lost if there's a crash so a safe fallback | |
| 151 | +value should always be possible. | |
| 152 | + | |
| 153 | +Policy hints affect performance, not correctness. | |
| 154 | + | |
| 155 | +Policy messaging | |
| 156 | +---------------- | |
| 157 | + | |
| 158 | +Policies will have different tunables, specific to each one, so we | |
| 159 | +need a generic way of getting and setting these. Device-mapper | |
| 160 | +messages are used. Refer to cache-policies.txt. | |
| 161 | + | |
| 162 | +Discard bitset resolution | |
| 163 | +------------------------- | |
| 164 | + | |
| 165 | +We can avoid copying data during migration if we know the block has | |
| 166 | +been discarded. A prime example of this is when mkfs discards the | |
| 167 | +whole block device. We store a bitset tracking the discard state of | |
| 168 | +blocks. However, we allow this bitset to have a different block size | |
| 169 | +from the cache blocks. This is because we need to track the discard | |
| 170 | +state for all of the origin device (compare with the dirty bitset | |
| 171 | +which is just for the smaller cache device). | |
| 172 | + | |
| 173 | +Target interface | |
| 174 | +================ | |
| 175 | + | |
| 176 | +Constructor | |
| 177 | +----------- | |
| 178 | + | |
| 179 | + :: | |
| 180 | + | |
| 181 | + cache <metadata dev> <cache dev> <origin dev> <block size> | |
| 182 | + <#feature args> [<feature arg>]* | |
| 183 | + <policy> <#policy args> [policy args]* | |
| 184 | + | |
| 185 | + ================ ======================================================= | |
| 186 | + metadata dev fast device holding the persistent metadata | |
| 187 | + cache dev fast device holding cached data blocks | |
| 188 | + origin dev slow device holding original data blocks | |
| 189 | + block size cache unit size in sectors | |
| 190 | + | |
| 191 | + #feature args number of feature arguments passed | |
| 192 | + feature args writethrough or passthrough (The default is writeback.) | |
| 193 | + | |
| 194 | + policy the replacement policy to use | |
| 195 | + #policy args an even number of arguments corresponding to | |
| 196 | + key/value pairs passed to the policy | |
| 197 | + policy args key/value pairs passed to the policy | |
| 198 | + E.g. 'sequential_threshold 1024' | |
| 199 | + See cache-policies.txt for details. | |
| 200 | + ================ ======================================================= | |
| 201 | + | |
| 202 | +Optional feature arguments are: | |
| 203 | + | |
| 204 | + | |
| 205 | + ==================== ======================================================== | |
| 206 | + writethrough write through caching that prohibits cache block | |
| 207 | + content from being different from origin block content. | |
| 208 | + Without this argument, the default behaviour is to write | |
| 209 | + back cache block contents later for performance reasons, | |
| 210 | + so they may differ from the corresponding origin blocks. | |
| 211 | + | |
| 212 | + passthrough a degraded mode useful for various cache coherency | |
| 213 | + situations (e.g., rolling back snapshots of | |
| 214 | + underlying storage). Reads and writes always go to | |
| 215 | + the origin. If a write goes to a cached origin | |
| 216 | + block, then the cache block is invalidated. | |
| 217 | + To enable passthrough mode the cache must be clean. | |
| 218 | + | |
| 219 | + metadata2 use version 2 of the metadata. This stores the dirty | |
| 220 | + bits in a separate btree, which improves speed of | |
| 221 | + shutting down the cache. | |
| 222 | + | |
| 223 | + no_discard_passdown disable passing down discards from the cache | |
| 224 | + to the origin's data device. | |
| 225 | + ==================== ======================================================== | |
| 226 | + | |
| 227 | +A policy called 'default' is always registered. This is an alias for | |
| 228 | +the policy we currently think is giving best all round performance. | |
| 229 | + | |
| 230 | +As the default policy could vary between kernels, if you are relying on | |
| 231 | +the characteristics of a specific policy, always request it by name. | |
| 232 | + | |
| 233 | +Status | |
| 234 | +------ | |
| 235 | + | |
| 236 | +:: | |
| 237 | + | |
| 238 | + <metadata block size> <#used metadata blocks>/<#total metadata blocks> | |
| 239 | + <cache block size> <#used cache blocks>/<#total cache blocks> | |
| 240 | + <#read hits> <#read misses> <#write hits> <#write misses> | |
| 241 | + <#demotions> <#promotions> <#dirty> <#features> <features>* | |
| 242 | + <#core args> <core args>* <policy name> <#policy args> <policy args>* | |
| 243 | + <cache metadata mode> | |
| 244 | + | |
| 245 | + | |
| 246 | +========================= ===================================================== | |
| 247 | +metadata block size Fixed block size for each metadata block in | |
| 248 | + sectors | |
| 249 | +#used metadata blocks Number of metadata blocks used | |
| 250 | +#total metadata blocks Total number of metadata blocks | |
| 251 | +cache block size Configurable block size for the cache device | |
| 252 | + in sectors | |
| 253 | +#used cache blocks Number of blocks resident in the cache | |
| 254 | +#total cache blocks Total number of cache blocks | |
| 255 | +#read hits Number of times a READ bio has been mapped | |
| 256 | + to the cache | |
| 257 | +#read misses Number of times a READ bio has been mapped | |
| 258 | + to the origin | |
| 259 | +#write hits Number of times a WRITE bio has been mapped | |
| 260 | + to the cache | |
| 261 | +#write misses Number of times a WRITE bio has been | |
| 262 | + mapped to the origin | |
| 263 | +#demotions Number of times a block has been removed | |
| 264 | + from the cache | |
| 265 | +#promotions Number of times a block has been moved to | |
| 266 | + the cache | |
| 267 | +#dirty Number of blocks in the cache that differ | |
| 268 | + from the origin | |
| 269 | +#feature args Number of feature args to follow | |
| 270 | +feature args 'writethrough' (optional) | |
| 271 | +#core args Number of core arguments (must be even) | |
| 272 | +core args Key/value pairs for tuning the core | |
| 273 | + e.g. migration_threshold | |
| 274 | +policy name Name of the policy | |
| 275 | +#policy args Number of policy arguments to follow (must be even) | |
| 276 | +policy args Key/value pairs e.g. sequential_threshold | |
| 277 | +cache metadata mode ro if read-only, rw if read-write | |
| 278 | + | |
| 279 | + In serious cases where even a read-only mode is | |
| 280 | + deemed unsafe no further I/O will be permitted and | |
| 281 | + the status will just contain the string 'Fail'. | |
| 282 | + The userspace recovery tools should then be used. | |
| 283 | +needs_check 'needs_check' if set, '-' if not set | |
| 284 | + A metadata operation has failed, resulting in the | |
| 285 | + needs_check flag being set in the metadata's | |
| 286 | + superblock. The metadata device must be | |
| 287 | + deactivated and checked/repaired before the | |
| 288 | + cache can be made fully operational again. | |
| 289 | + '-' indicates needs_check is not set. | |
| 290 | +========================= ===================================================== | |
| 291 | + | |
| 292 | +Messages | |
| 293 | +-------- | |
| 294 | + | |
| 295 | +Policies will have different tunables, specific to each one, so we | |
| 296 | +need a generic way of getting and setting these. Device-mapper | |
| 297 | +messages are used. (A sysfs interface would also be possible.) | |
| 298 | + | |
| 299 | +The message format is:: | |
| 300 | + | |
| 301 | + <key> <value> | |
| 302 | + | |
| 303 | +E.g.:: | |
| 304 | + | |
| 305 | + dmsetup message my_cache 0 sequential_threshold 1024 | |
| 306 | + | |
| 307 | + | |
| 308 | +Invalidation is removing an entry from the cache without writing it | |
| 309 | +back. Cache blocks can be invalidated via the invalidate_cblocks | |
| 310 | +message, which takes an arbitrary number of cblock ranges. Each cblock | |
| 311 | +range's end value is "one past the end", meaning 5-10 expresses a range | |
| 312 | +of values from 5 to 9. Each cblock must be expressed as a decimal | |
| 313 | +value, in the future a variant message that takes cblock ranges | |
| 314 | +expressed in hexadecimal may be needed to better support efficient | |
| 315 | +invalidation of larger caches. The cache must be in passthrough mode | |
| 316 | +when invalidate_cblocks is used:: | |
| 317 | + | |
| 318 | + invalidate_cblocks [<cblock>|<cblock begin>-<cblock end>]* | |
| 319 | + | |
| 320 | +E.g.:: | |
| 321 | + | |
| 322 | + dmsetup message my_cache 0 invalidate_cblocks 2345 3456-4567 5678-6789 | |
| 323 | + | |
| 324 | +Examples | |
| 325 | +======== | |
| 326 | + | |
| 327 | +The test suite can be found here: | |
| 328 | + | |
| 329 | +https://github.com/jthornber/device-mapper-test-suite | |
| 330 | + | |
| 331 | +:: | |
| 332 | + | |
| 333 | + dmsetup create my_cache --table '0 41943040 cache /dev/mapper/metadata \ | |
| 334 | + /dev/mapper/ssd /dev/mapper/origin 512 1 writeback default 0' | |
| 335 | + dmsetup create my_cache --table '0 41943040 cache /dev/mapper/metadata \ | |
| 336 | + /dev/mapper/ssd /dev/mapper/origin 1024 1 writeback \ | |
| 337 | + mq 4 sequential_threshold 1024 random_threshold 8' | |
| @@ -0,0 +1,31 @@ | ||
| 1 | +======== | |
| 2 | +dm-delay | |
| 3 | +======== | |
| 4 | + | |
| 5 | +Device-Mapper's "delay" target delays reads and/or writes | |
| 6 | +and maps them to different devices. | |
| 7 | + | |
| 8 | +Parameters:: | |
| 9 | + | |
| 10 | + <device> <offset> <delay> [<write_device> <write_offset> <write_delay> | |
| 11 | + [<flush_device> <flush_offset> <flush_delay>]] | |
| 12 | + | |
| 13 | +With separate write parameters, the first set is only used for reads. | |
| 14 | +Offsets are specified in sectors. | |
| 15 | +Delays are specified in milliseconds. | |
| 16 | + | |
| 17 | +Example scripts | |
| 18 | +=============== | |
| 19 | + | |
| 20 | +:: | |
| 21 | + | |
| 22 | + #!/bin/sh | |
| 23 | + # Create device delaying rw operation for 500ms | |
| 24 | + echo "0 `blockdev --getsz $1` delay $1 0 500" | dmsetup create delayed | |
| 25 | + | |
| 26 | +:: | |
| 27 | + | |
| 28 | + #!/bin/sh | |
| 29 | + # Create device delaying only write operation for 500ms and | |
| 30 | + # splitting reads and writes to different devices $1 $2 | |
| 31 | + echo "0 `blockdev --getsz $1` delay $1 0 0 $2 0 500" | dmsetup create delayed | |
| @@ -0,0 +1,173 @@ | ||
| 1 | +======== | |
| 2 | +dm-crypt | |
| 3 | +======== | |
| 4 | + | |
| 5 | +Device-Mapper's "crypt" target provides transparent encryption of block devices | |
| 6 | +using the kernel crypto API. | |
| 7 | + | |
| 8 | +For a more detailed description of supported parameters see: | |
| 9 | +https://gitlab.com/cryptsetup/cryptsetup/wikis/DMCrypt | |
| 10 | + | |
| 11 | +Parameters:: | |
| 12 | + | |
| 13 | + <cipher> <key> <iv_offset> <device path> \ | |
| 14 | + <offset> [<#opt_params> <opt_params>] | |
| 15 | + | |
| 16 | +<cipher> | |
| 17 | + Encryption cipher, encryption mode and Initial Vector (IV) generator. | |
| 18 | + | |
| 19 | + The cipher specifications format is:: | |
| 20 | + | |
| 21 | + cipher[:keycount]-chainmode-ivmode[:ivopts] | |
| 22 | + | |
| 23 | + Examples:: | |
| 24 | + | |
| 25 | + aes-cbc-essiv:sha256 | |
| 26 | + aes-xts-plain64 | |
| 27 | + serpent-xts-plain64 | |
| 28 | + | |
| 29 | + Cipher format also supports direct specification with kernel crypt API | |
| 30 | + format (selected by capi: prefix). The IV specification is the same | |
| 31 | + as for the first format type. | |
| 32 | + This format is mainly used for specification of authenticated modes. | |
| 33 | + | |
| 34 | + The crypto API cipher specifications format is:: | |
| 35 | + | |
| 36 | + capi:cipher_api_spec-ivmode[:ivopts] | |
| 37 | + | |
| 38 | + Examples:: | |
| 39 | + | |
| 40 | + capi:cbc(aes)-essiv:sha256 | |
| 41 | + capi:xts(aes)-plain64 | |
| 42 | + | |
| 43 | + Examples of authenticated modes:: | |
| 44 | + | |
| 45 | + capi:gcm(aes)-random | |
| 46 | + capi:authenc(hmac(sha256),xts(aes))-random | |
| 47 | + capi:rfc7539(chacha20,poly1305)-random | |
| 48 | + | |
| 49 | + The /proc/crypto contains a list of curently loaded crypto modes. | |
| 50 | + | |
| 51 | +<key> | |
| 52 | + Key used for encryption. It is encoded either as a hexadecimal number | |
| 53 | + or it can be passed as <key_string> prefixed with single colon | |
| 54 | + character (':') for keys residing in kernel keyring service. | |
| 55 | + You can only use key sizes that are valid for the selected cipher | |
| 56 | + in combination with the selected iv mode. | |
| 57 | + Note that for some iv modes the key string can contain additional | |
| 58 | + keys (for example IV seed) so the key contains more parts concatenated | |
| 59 | + into a single string. | |
| 60 | + | |
| 61 | +<key_string> | |
| 62 | + The kernel keyring key is identified by string in following format: | |
| 63 | + <key_size>:<key_type>:<key_description>. | |
| 64 | + | |
| 65 | +<key_size> | |
| 66 | + The encryption key size in bytes. The kernel key payload size must match | |
| 67 | + the value passed in <key_size>. | |
| 68 | + | |
| 69 | +<key_type> | |
| 70 | + Either 'logon' or 'user' kernel key type. | |
| 71 | + | |
| 72 | +<key_description> | |
| 73 | + The kernel keyring key description crypt target should look for | |
| 74 | + when loading key of <key_type>. | |
| 75 | + | |
| 76 | +<keycount> | |
| 77 | + Multi-key compatibility mode. You can define <keycount> keys and | |
| 78 | + then sectors are encrypted according to their offsets (sector 0 uses key0; | |
| 79 | + sector 1 uses key1 etc.). <keycount> must be a power of two. | |
| 80 | + | |
| 81 | +<iv_offset> | |
| 82 | + The IV offset is a sector count that is added to the sector number | |
| 83 | + before creating the IV. | |
| 84 | + | |
| 85 | +<device path> | |
| 86 | + This is the device that is going to be used as backend and contains the | |
| 87 | + encrypted data. You can specify it as a path like /dev/xxx or a device | |
| 88 | + number <major>:<minor>. | |
| 89 | + | |
| 90 | +<offset> | |
| 91 | + Starting sector within the device where the encrypted data begins. | |
| 92 | + | |
| 93 | +<#opt_params> | |
| 94 | + Number of optional parameters. If there are no optional parameters, | |
| 95 | + the optional paramaters section can be skipped or #opt_params can be zero. | |
| 96 | + Otherwise #opt_params is the number of following arguments. | |
| 97 | + | |
| 98 | + Example of optional parameters section: | |
| 99 | + 3 allow_discards same_cpu_crypt submit_from_crypt_cpus | |
| 100 | + | |
| 101 | +allow_discards | |
| 102 | + Block discard requests (a.k.a. TRIM) are passed through the crypt device. | |
| 103 | + The default is to ignore discard requests. | |
| 104 | + | |
| 105 | + WARNING: Assess the specific security risks carefully before enabling this | |
| 106 | + option. For example, allowing discards on encrypted devices may lead to | |
| 107 | + the leak of information about the ciphertext device (filesystem type, | |
| 108 | + used space etc.) if the discarded blocks can be located easily on the | |
| 109 | + device later. | |
| 110 | + | |
| 111 | +same_cpu_crypt | |
| 112 | + Perform encryption using the same cpu that IO was submitted on. | |
| 113 | + The default is to use an unbound workqueue so that encryption work | |
| 114 | + is automatically balanced between available CPUs. | |
| 115 | + | |
| 116 | +submit_from_crypt_cpus | |
| 117 | + Disable offloading writes to a separate thread after encryption. | |
| 118 | + There are some situations where offloading write bios from the | |
| 119 | + encryption threads to a single thread degrades performance | |
| 120 | + significantly. The default is to offload write bios to the same | |
| 121 | + thread because it benefits CFQ to have writes submitted using the | |
| 122 | + same context. | |
| 123 | + | |
| 124 | +integrity:<bytes>:<type> | |
| 125 | + The device requires additional <bytes> metadata per-sector stored | |
| 126 | + in per-bio integrity structure. This metadata must by provided | |
| 127 | + by underlying dm-integrity target. | |
| 128 | + | |
| 129 | + The <type> can be "none" if metadata is used only for persistent IV. | |
| 130 | + | |
| 131 | + For Authenticated Encryption with Additional Data (AEAD) | |
| 132 | + the <type> is "aead". An AEAD mode additionally calculates and verifies | |
| 133 | + integrity for the encrypted device. The additional space is then | |
| 134 | + used for storing authentication tag (and persistent IV if needed). | |
| 135 | + | |
| 136 | +sector_size:<bytes> | |
| 137 | + Use <bytes> as the encryption unit instead of 512 bytes sectors. | |
| 138 | + This option can be in range 512 - 4096 bytes and must be power of two. | |
| 139 | + Virtual device will announce this size as a minimal IO and logical sector. | |
| 140 | + | |
| 141 | +iv_large_sectors | |
| 142 | + IV generators will use sector number counted in <sector_size> units | |
| 143 | + instead of default 512 bytes sectors. | |
| 144 | + | |
| 145 | + For example, if <sector_size> is 4096 bytes, plain64 IV for the second | |
| 146 | + sector will be 8 (without flag) and 1 if iv_large_sectors is present. | |
| 147 | + The <iv_offset> must be multiple of <sector_size> (in 512 bytes units) | |
| 148 | + if this flag is specified. | |
| 149 | + | |
| 150 | +Example scripts | |
| 151 | +=============== | |
| 152 | +LUKS (Linux Unified Key Setup) is now the preferred way to set up disk | |
| 153 | +encryption with dm-crypt using the 'cryptsetup' utility, see | |
| 154 | +https://gitlab.com/cryptsetup/cryptsetup | |
| 155 | + | |
| 156 | +:: | |
| 157 | + | |
| 158 | + #!/bin/sh | |
| 159 | + # Create a crypt device using dmsetup | |
| 160 | + dmsetup create crypt1 --table "0 `blockdev --getsz $1` crypt aes-cbc-essiv:sha256 babebabebabebabebabebabebabebabe 0 $1 0" | |
| 161 | + | |
| 162 | +:: | |
| 163 | + | |
| 164 | + #!/bin/sh | |
| 165 | + # Create a crypt device using dmsetup when encryption key is stored in keyring service | |
| 166 | + dmsetup create crypt2 --table "0 `blockdev --getsize $1` crypt aes-cbc-essiv:sha256 :32:logon:my_prefix:my_key 0 $1 0" | |
| 167 | + | |
| 168 | +:: | |
| 169 | + | |
| 170 | + #!/bin/sh | |
| 171 | + # Create a crypt device using cryptsetup and LUKS header with default cipher | |
| 172 | + cryptsetup luksFormat $1 | |
| 173 | + cryptsetup luksOpen $1 crypt1 | |
File renamed without changes.
| @@ -0,0 +1,74 @@ | ||
| 1 | +========= | |
| 2 | +dm-flakey | |
| 3 | +========= | |
| 4 | + | |
| 5 | +This target is the same as the linear target except that it exhibits | |
| 6 | +unreliable behaviour periodically. It's been found useful in simulating | |
| 7 | +failing devices for testing purposes. | |
| 8 | + | |
| 9 | +Starting from the time the table is loaded, the device is available for | |
| 10 | +<up interval> seconds, then exhibits unreliable behaviour for <down | |
| 11 | +interval> seconds, and then this cycle repeats. | |
| 12 | + | |
| 13 | +Also, consider using this in combination with the dm-delay target too, | |
| 14 | +which can delay reads and writes and/or send them to different | |
| 15 | +underlying devices. | |
| 16 | + | |
| 17 | +Table parameters | |
| 18 | +---------------- | |
| 19 | + | |
| 20 | +:: | |
| 21 | + | |
| 22 | + <dev path> <offset> <up interval> <down interval> \ | |
| 23 | + [<num_features> [<feature arguments>]] | |
| 24 | + | |
| 25 | +Mandatory parameters: | |
| 26 | + | |
| 27 | + <dev path>: | |
| 28 | + Full pathname to the underlying block-device, or a | |
| 29 | + "major:minor" device-number. | |
| 30 | + <offset>: | |
| 31 | + Starting sector within the device. | |
| 32 | + <up interval>: | |
| 33 | + Number of seconds device is available. | |
| 34 | + <down interval>: | |
| 35 | + Number of seconds device returns errors. | |
| 36 | + | |
| 37 | +Optional feature parameters: | |
| 38 | + | |
| 39 | + If no feature parameters are present, during the periods of | |
| 40 | + unreliability, all I/O returns errors. | |
| 41 | + | |
| 42 | + drop_writes: | |
| 43 | + All write I/O is silently ignored. | |
| 44 | + Read I/O is handled correctly. | |
| 45 | + | |
| 46 | + error_writes: | |
| 47 | + All write I/O is failed with an error signalled. | |
| 48 | + Read I/O is handled correctly. | |
| 49 | + | |
| 50 | + corrupt_bio_byte <Nth_byte> <direction> <value> <flags>: | |
| 51 | + During <down interval>, replace <Nth_byte> of the data of | |
| 52 | + each matching bio with <value>. | |
| 53 | + | |
| 54 | + <Nth_byte>: | |
| 55 | + The offset of the byte to replace. | |
| 56 | + Counting starts at 1, to replace the first byte. | |
| 57 | + <direction>: | |
| 58 | + Either 'r' to corrupt reads or 'w' to corrupt writes. | |
| 59 | + 'w' is incompatible with drop_writes. | |
| 60 | + <value>: | |
| 61 | + The value (from 0-255) to write. | |
| 62 | + <flags>: | |
| 63 | + Perform the replacement only if bio->bi_opf has all the | |
| 64 | + selected flags set. | |
| 65 | + | |
| 66 | +Examples: | |
| 67 | + | |
| 68 | +Replaces the 32nd byte of READ bios with the value 1:: | |
| 69 | + | |
| 70 | + corrupt_bio_byte 32 r 1 0 | |
| 71 | + | |
| 72 | +Replaces the 224th byte of REQ_META (=32) bios with the value 0:: | |
| 73 | + | |
| 74 | + corrupt_bio_byte 224 w 0 32 | |
| @@ -0,0 +1,125 @@ | ||
| 1 | +================================ | |
| 2 | +Early creation of mapped devices | |
| 3 | +================================ | |
| 4 | + | |
| 5 | +It is possible to configure a device-mapper device to act as the root device for | |
| 6 | +your system in two ways. | |
| 7 | + | |
| 8 | +The first is to build an initial ramdisk which boots to a minimal userspace | |
| 9 | +which configures the device, then pivot_root(8) in to it. | |
| 10 | + | |
| 11 | +The second is to create one or more device-mappers using the module parameter | |
| 12 | +"dm-mod.create=" through the kernel boot command line argument. | |
| 13 | + | |
| 14 | +The format is specified as a string of data separated by commas and optionally | |
| 15 | +semi-colons, where: | |
| 16 | + | |
| 17 | + - a comma is used to separate fields like name, uuid, flags and table | |
| 18 | + (specifies one device) | |
| 19 | + - a semi-colon is used to separate devices. | |
| 20 | + | |
| 21 | +So the format will look like this:: | |
| 22 | + | |
| 23 | + dm-mod.create=<name>,<uuid>,<minor>,<flags>,<table>[,<table>+][;<name>,<uuid>,<minor>,<flags>,<table>[,<table>+]+] | |
| 24 | + | |
| 25 | +Where:: | |
| 26 | + | |
| 27 | + <name> ::= The device name. | |
| 28 | + <uuid> ::= xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx | "" | |
| 29 | + <minor> ::= The device minor number | "" | |
| 30 | + <flags> ::= "ro" | "rw" | |
| 31 | + <table> ::= <start_sector> <num_sectors> <target_type> <target_args> | |
| 32 | + <target_type> ::= "verity" | "linear" | ... (see list below) | |
| 33 | + | |
| 34 | +The dm line should be equivalent to the one used by the dmsetup tool with the | |
| 35 | +`--concise` argument. | |
| 36 | + | |
| 37 | +Target types | |
| 38 | +============ | |
| 39 | + | |
| 40 | +Not all target types are available as there are serious risks in allowing | |
| 41 | +activation of certain DM targets without first using userspace tools to check | |
| 42 | +the validity of associated metadata. | |
| 43 | + | |
| 44 | +======================= ======================================================= | |
| 45 | +`cache` constrained, userspace should verify cache device | |
| 46 | +`crypt` allowed | |
| 47 | +`delay` allowed | |
| 48 | +`era` constrained, userspace should verify metadata device | |
| 49 | +`flakey` constrained, meant for test | |
| 50 | +`linear` allowed | |
| 51 | +`log-writes` constrained, userspace should verify metadata device | |
| 52 | +`mirror` constrained, userspace should verify main/mirror device | |
| 53 | +`raid` constrained, userspace should verify metadata device | |
| 54 | +`snapshot` constrained, userspace should verify src/dst device | |
| 55 | +`snapshot-origin` allowed | |
| 56 | +`snapshot-merge` constrained, userspace should verify src/dst device | |
| 57 | +`striped` allowed | |
| 58 | +`switch` constrained, userspace should verify dev path | |
| 59 | +`thin` constrained, requires dm target message from userspace | |
| 60 | +`thin-pool` constrained, requires dm target message from userspace | |
| 61 | +`verity` allowed | |
| 62 | +`writecache` constrained, userspace should verify cache device | |
| 63 | +`zero` constrained, not meant for rootfs | |
| 64 | +======================= ======================================================= | |
| 65 | + | |
| 66 | +If the target is not listed above, it is constrained by default (not tested). | |
| 67 | + | |
| 68 | +Examples | |
| 69 | +======== | |
| 70 | +An example of booting to a linear array made up of user-mode linux block | |
| 71 | +devices:: | |
| 72 | + | |
| 73 | + dm-mod.create="lroot,,,rw, 0 4096 linear 98:16 0, 4096 4096 linear 98:32 0" root=/dev/dm-0 | |
| 74 | + | |
| 75 | +This will boot to a rw dm-linear target of 8192 sectors split across two block | |
| 76 | +devices identified by their major:minor numbers. After boot, udev will rename | |
| 77 | +this target to /dev/mapper/lroot (depending on the rules). No uuid was assigned. | |
| 78 | + | |
| 79 | +An example of multiple device-mappers, with the dm-mod.create="..." contents | |
| 80 | +is shown here split on multiple lines for readability:: | |
| 81 | + | |
| 82 | + dm-linear,,1,rw, | |
| 83 | + 0 32768 linear 8:1 0, | |
| 84 | + 32768 1024000 linear 8:2 0; | |
| 85 | + dm-verity,,3,ro, | |
| 86 | + 0 1638400 verity 1 /dev/sdc1 /dev/sdc2 4096 4096 204800 1 sha256 | |
| 87 | + ac87db56303c9c1da433d7209b5a6ef3e4779df141200cbd7c157dcb8dd89c42 | |
| 88 | + 5ebfe87f7df3235b80a117ebc4078e44f55045487ad4a96581d1adb564615b51 | |
| 89 | + | |
| 90 | +Other examples (per target): | |
| 91 | + | |
| 92 | +"crypt":: | |
| 93 | + | |
| 94 | + dm-crypt,,8,ro, | |
| 95 | + 0 1048576 crypt aes-xts-plain64 | |
| 96 | + babebabebabebabebabebabebabebabebabebabebabebabebabebabebabebabe 0 | |
| 97 | + /dev/sda 0 1 allow_discards | |
| 98 | + | |
| 99 | +"delay":: | |
| 100 | + | |
| 101 | + dm-delay,,4,ro,0 409600 delay /dev/sda1 0 500 | |
| 102 | + | |
| 103 | +"linear":: | |
| 104 | + | |
| 105 | + dm-linear,,,rw, | |
| 106 | + 0 32768 linear /dev/sda1 0, | |
| 107 | + 32768 1024000 linear /dev/sda2 0, | |
| 108 | + 1056768 204800 linear /dev/sda3 0, | |
| 109 | + 1261568 512000 linear /dev/sda4 0 | |
| 110 | + | |
| 111 | +"snapshot-origin":: | |
| 112 | + | |
| 113 | + dm-snap-orig,,4,ro,0 409600 snapshot-origin 8:2 | |
| 114 | + | |
| 115 | +"striped":: | |
| 116 | + | |
| 117 | + dm-striped,,4,ro,0 1638400 striped 4 4096 | |
| 118 | + /dev/sda1 0 /dev/sda2 0 /dev/sda3 0 /dev/sda4 0 | |
| 119 | + | |
| 120 | +"verity":: | |
| 121 | + | |
| 122 | + dm-verity,,4,ro, | |
| 123 | + 0 1638400 verity 1 8:1 8:2 4096 4096 204800 1 sha256 | |
| 124 | + fb1a5a0f00deb908d8b53cb270858975e76cf64105d412ce764225d53b8f3cfd | |
| 125 | + 51934789604d1b92399c52e7cb149d1b3a1b74bbbcb103b2a0aaacbed5c08584 | |
| @@ -0,0 +1,259 @@ | ||
| 1 | +============ | |
| 2 | +dm-integrity | |
| 3 | +============ | |
| 4 | + | |
| 5 | +The dm-integrity target emulates a block device that has additional | |
| 6 | +per-sector tags that can be used for storing integrity information. | |
| 7 | + | |
| 8 | +A general problem with storing integrity tags with every sector is that | |
| 9 | +writing the sector and the integrity tag must be atomic - i.e. in case of | |
| 10 | +crash, either both sector and integrity tag or none of them is written. | |
| 11 | + | |
| 12 | +To guarantee write atomicity, the dm-integrity target uses journal, it | |
| 13 | +writes sector data and integrity tags into a journal, commits the journal | |
| 14 | +and then copies the data and integrity tags to their respective location. | |
| 15 | + | |
| 16 | +The dm-integrity target can be used with the dm-crypt target - in this | |
| 17 | +situation the dm-crypt target creates the integrity data and passes them | |
| 18 | +to the dm-integrity target via bio_integrity_payload attached to the bio. | |
| 19 | +In this mode, the dm-crypt and dm-integrity targets provide authenticated | |
| 20 | +disk encryption - if the attacker modifies the encrypted device, an I/O | |
| 21 | +error is returned instead of random data. | |
| 22 | + | |
| 23 | +The dm-integrity target can also be used as a standalone target, in this | |
| 24 | +mode it calculates and verifies the integrity tag internally. In this | |
| 25 | +mode, the dm-integrity target can be used to detect silent data | |
| 26 | +corruption on the disk or in the I/O path. | |
| 27 | + | |
| 28 | +There's an alternate mode of operation where dm-integrity uses bitmap | |
| 29 | +instead of a journal. If a bit in the bitmap is 1, the corresponding | |
| 30 | +region's data and integrity tags are not synchronized - if the machine | |
| 31 | +crashes, the unsynchronized regions will be recalculated. The bitmap mode | |
| 32 | +is faster than the journal mode, because we don't have to write the data | |
| 33 | +twice, but it is also less reliable, because if data corruption happens | |
| 34 | +when the machine crashes, it may not be detected. | |
| 35 | + | |
| 36 | +When loading the target for the first time, the kernel driver will format | |
| 37 | +the device. But it will only format the device if the superblock contains | |
| 38 | +zeroes. If the superblock is neither valid nor zeroed, the dm-integrity | |
| 39 | +target can't be loaded. | |
| 40 | + | |
| 41 | +To use the target for the first time: | |
| 42 | + | |
| 43 | +1. overwrite the superblock with zeroes | |
| 44 | +2. load the dm-integrity target with one-sector size, the kernel driver | |
| 45 | + will format the device | |
| 46 | +3. unload the dm-integrity target | |
| 47 | +4. read the "provided_data_sectors" value from the superblock | |
| 48 | +5. load the dm-integrity target with the the target size | |
| 49 | + "provided_data_sectors" | |
| 50 | +6. if you want to use dm-integrity with dm-crypt, load the dm-crypt target | |
| 51 | + with the size "provided_data_sectors" | |
| 52 | + | |
| 53 | + | |
| 54 | +Target arguments: | |
| 55 | + | |
| 56 | +1. the underlying block device | |
| 57 | + | |
| 58 | +2. the number of reserved sector at the beginning of the device - the | |
| 59 | + dm-integrity won't read of write these sectors | |
| 60 | + | |
| 61 | +3. the size of the integrity tag (if "-" is used, the size is taken from | |
| 62 | + the internal-hash algorithm) | |
| 63 | + | |
| 64 | +4. mode: | |
| 65 | + | |
| 66 | + D - direct writes (without journal) | |
| 67 | + in this mode, journaling is | |
| 68 | + not used and data sectors and integrity tags are written | |
| 69 | + separately. In case of crash, it is possible that the data | |
| 70 | + and integrity tag doesn't match. | |
| 71 | + J - journaled writes | |
| 72 | + data and integrity tags are written to the | |
| 73 | + journal and atomicity is guaranteed. In case of crash, | |
| 74 | + either both data and tag or none of them are written. The | |
| 75 | + journaled mode degrades write throughput twice because the | |
| 76 | + data have to be written twice. | |
| 77 | + B - bitmap mode - data and metadata are written without any | |
| 78 | + synchronization, the driver maintains a bitmap of dirty | |
| 79 | + regions where data and metadata don't match. This mode can | |
| 80 | + only be used with internal hash. | |
| 81 | + R - recovery mode - in this mode, journal is not replayed, | |
| 82 | + checksums are not checked and writes to the device are not | |
| 83 | + allowed. This mode is useful for data recovery if the | |
| 84 | + device cannot be activated in any of the other standard | |
| 85 | + modes. | |
| 86 | + | |
| 87 | +5. the number of additional arguments | |
| 88 | + | |
| 89 | +Additional arguments: | |
| 90 | + | |
| 91 | +journal_sectors:number | |
| 92 | + The size of journal, this argument is used only if formatting the | |
| 93 | + device. If the device is already formatted, the value from the | |
| 94 | + superblock is used. | |
| 95 | + | |
| 96 | +interleave_sectors:number | |
| 97 | + The number of interleaved sectors. This values is rounded down to | |
| 98 | + a power of two. If the device is already formatted, the value from | |
| 99 | + the superblock is used. | |
| 100 | + | |
| 101 | +meta_device:device | |
| 102 | + Don't interleave the data and metadata on on device. Use a | |
| 103 | + separate device for metadata. | |
| 104 | + | |
| 105 | +buffer_sectors:number | |
| 106 | + The number of sectors in one buffer. The value is rounded down to | |
| 107 | + a power of two. | |
| 108 | + | |
| 109 | + The tag area is accessed using buffers, the buffer size is | |
| 110 | + configurable. The large buffer size means that the I/O size will | |
| 111 | + be larger, but there could be less I/Os issued. | |
| 112 | + | |
| 113 | +journal_watermark:number | |
| 114 | + The journal watermark in percents. When the size of the journal | |
| 115 | + exceeds this watermark, the thread that flushes the journal will | |
| 116 | + be started. | |
| 117 | + | |
| 118 | +commit_time:number | |
| 119 | + Commit time in milliseconds. When this time passes, the journal is | |
| 120 | + written. The journal is also written immediatelly if the FLUSH | |
| 121 | + request is received. | |
| 122 | + | |
| 123 | +internal_hash:algorithm(:key) (the key is optional) | |
| 124 | + Use internal hash or crc. | |
| 125 | + When this argument is used, the dm-integrity target won't accept | |
| 126 | + integrity tags from the upper target, but it will automatically | |
| 127 | + generate and verify the integrity tags. | |
| 128 | + | |
| 129 | + You can use a crc algorithm (such as crc32), then integrity target | |
| 130 | + will protect the data against accidental corruption. | |
| 131 | + You can also use a hmac algorithm (for example | |
| 132 | + "hmac(sha256):0123456789abcdef"), in this mode it will provide | |
| 133 | + cryptographic authentication of the data without encryption. | |
| 134 | + | |
| 135 | + When this argument is not used, the integrity tags are accepted | |
| 136 | + from an upper layer target, such as dm-crypt. The upper layer | |
| 137 | + target should check the validity of the integrity tags. | |
| 138 | + | |
| 139 | +recalculate | |
| 140 | + Recalculate the integrity tags automatically. It is only valid | |
| 141 | + when using internal hash. | |
| 142 | + | |
| 143 | +journal_crypt:algorithm(:key) (the key is optional) | |
| 144 | + Encrypt the journal using given algorithm to make sure that the | |
| 145 | + attacker can't read the journal. You can use a block cipher here | |
| 146 | + (such as "cbc(aes)") or a stream cipher (for example "chacha20", | |
| 147 | + "salsa20", "ctr(aes)" or "ecb(arc4)"). | |
| 148 | + | |
| 149 | + The journal contains history of last writes to the block device, | |
| 150 | + an attacker reading the journal could see the last sector nubmers | |
| 151 | + that were written. From the sector numbers, the attacker can infer | |
| 152 | + the size of files that were written. To protect against this | |
| 153 | + situation, you can encrypt the journal. | |
| 154 | + | |
| 155 | +journal_mac:algorithm(:key) (the key is optional) | |
| 156 | + Protect sector numbers in the journal from accidental or malicious | |
| 157 | + modification. To protect against accidental modification, use a | |
| 158 | + crc algorithm, to protect against malicious modification, use a | |
| 159 | + hmac algorithm with a key. | |
| 160 | + | |
| 161 | + This option is not needed when using internal-hash because in this | |
| 162 | + mode, the integrity of journal entries is checked when replaying | |
| 163 | + the journal. Thus, modified sector number would be detected at | |
| 164 | + this stage. | |
| 165 | + | |
| 166 | +block_size:number | |
| 167 | + The size of a data block in bytes. The larger the block size the | |
| 168 | + less overhead there is for per-block integrity metadata. | |
| 169 | + Supported values are 512, 1024, 2048 and 4096 bytes. If not | |
| 170 | + specified the default block size is 512 bytes. | |
| 171 | + | |
| 172 | +sectors_per_bit:number | |
| 173 | + In the bitmap mode, this parameter specifies the number of | |
| 174 | + 512-byte sectors that corresponds to one bitmap bit. | |
| 175 | + | |
| 176 | +bitmap_flush_interval:number | |
| 177 | + The bitmap flush interval in milliseconds. The metadata buffers | |
| 178 | + are synchronized when this interval expires. | |
| 179 | + | |
| 180 | + | |
| 181 | +The journal mode (D/J), buffer_sectors, journal_watermark, commit_time can | |
| 182 | +be changed when reloading the target (load an inactive table and swap the | |
| 183 | +tables with suspend and resume). The other arguments should not be changed | |
| 184 | +when reloading the target because the layout of disk data depend on them | |
| 185 | +and the reloaded target would be non-functional. | |
| 186 | + | |
| 187 | + | |
| 188 | +The layout of the formatted block device: | |
| 189 | + | |
| 190 | +* reserved sectors | |
| 191 | + (they are not used by this target, they can be used for | |
| 192 | + storing LUKS metadata or for other purpose), the size of the reserved | |
| 193 | + area is specified in the target arguments | |
| 194 | + | |
| 195 | +* superblock (4kiB) | |
| 196 | + * magic string - identifies that the device was formatted | |
| 197 | + * version | |
| 198 | + * log2(interleave sectors) | |
| 199 | + * integrity tag size | |
| 200 | + * the number of journal sections | |
| 201 | + * provided data sectors - the number of sectors that this target | |
| 202 | + provides (i.e. the size of the device minus the size of all | |
| 203 | + metadata and padding). The user of this target should not send | |
| 204 | + bios that access data beyond the "provided data sectors" limit. | |
| 205 | + * flags | |
| 206 | + SB_FLAG_HAVE_JOURNAL_MAC | |
| 207 | + - a flag is set if journal_mac is used | |
| 208 | + SB_FLAG_RECALCULATING | |
| 209 | + - recalculating is in progress | |
| 210 | + SB_FLAG_DIRTY_BITMAP | |
| 211 | + - journal area contains the bitmap of dirty | |
| 212 | + blocks | |
| 213 | + * log2(sectors per block) | |
| 214 | + * a position where recalculating finished | |
| 215 | +* journal | |
| 216 | + The journal is divided into sections, each section contains: | |
| 217 | + | |
| 218 | + * metadata area (4kiB), it contains journal entries | |
| 219 | + | |
| 220 | + - every journal entry contains: | |
| 221 | + | |
| 222 | + * logical sector (specifies where the data and tag should | |
| 223 | + be written) | |
| 224 | + * last 8 bytes of data | |
| 225 | + * integrity tag (the size is specified in the superblock) | |
| 226 | + | |
| 227 | + - every metadata sector ends with | |
| 228 | + | |
| 229 | + * mac (8-bytes), all the macs in 8 metadata sectors form a | |
| 230 | + 64-byte value. It is used to store hmac of sector | |
| 231 | + numbers in the journal section, to protect against a | |
| 232 | + possibility that the attacker tampers with sector | |
| 233 | + numbers in the journal. | |
| 234 | + * commit id | |
| 235 | + | |
| 236 | + * data area (the size is variable; it depends on how many journal | |
| 237 | + entries fit into the metadata area) | |
| 238 | + | |
| 239 | + - every sector in the data area contains: | |
| 240 | + | |
| 241 | + * data (504 bytes of data, the last 8 bytes are stored in | |
| 242 | + the journal entry) | |
| 243 | + * commit id | |
| 244 | + | |
| 245 | + To test if the whole journal section was written correctly, every | |
| 246 | + 512-byte sector of the journal ends with 8-byte commit id. If the | |
| 247 | + commit id matches on all sectors in a journal section, then it is | |
| 248 | + assumed that the section was written correctly. If the commit id | |
| 249 | + doesn't match, the section was written partially and it should not | |
| 250 | + be replayed. | |
| 251 | + | |
| 252 | +* one or more runs of interleaved tags and data. | |
| 253 | + Each run contains: | |
| 254 | + | |
| 255 | + * tag area - it contains integrity tags. There is one tag for each | |
| 256 | + sector in the data area | |
| 257 | + * data area - it contains data sectors. The number of data sectors | |
| 258 | + in one run must be a power of two. log2 of this value is stored | |
| 259 | + in the superblock. | |
| @@ -0,0 +1,75 @@ | ||
| 1 | +===== | |
| 2 | +dm-io | |
| 3 | +===== | |
| 4 | + | |
| 5 | +Dm-io provides synchronous and asynchronous I/O services. There are three | |
| 6 | +types of I/O services available, and each type has a sync and an async | |
| 7 | +version. | |
| 8 | + | |
| 9 | +The user must set up an io_region structure to describe the desired location | |
| 10 | +of the I/O. Each io_region indicates a block-device along with the starting | |
| 11 | +sector and size of the region:: | |
| 12 | + | |
| 13 | + struct io_region { | |
| 14 | + struct block_device *bdev; | |
| 15 | + sector_t sector; | |
| 16 | + sector_t count; | |
| 17 | + }; | |
| 18 | + | |
| 19 | +Dm-io can read from one io_region or write to one or more io_regions. Writes | |
| 20 | +to multiple regions are specified by an array of io_region structures. | |
| 21 | + | |
| 22 | +The first I/O service type takes a list of memory pages as the data buffer for | |
| 23 | +the I/O, along with an offset into the first page:: | |
| 24 | + | |
| 25 | + struct page_list { | |
| 26 | + struct page_list *next; | |
| 27 | + struct page *page; | |
| 28 | + }; | |
| 29 | + | |
| 30 | + int dm_io_sync(unsigned int num_regions, struct io_region *where, int rw, | |
| 31 | + struct page_list *pl, unsigned int offset, | |
| 32 | + unsigned long *error_bits); | |
| 33 | + int dm_io_async(unsigned int num_regions, struct io_region *where, int rw, | |
| 34 | + struct page_list *pl, unsigned int offset, | |
| 35 | + io_notify_fn fn, void *context); | |
| 36 | + | |
| 37 | +The second I/O service type takes an array of bio vectors as the data buffer | |
| 38 | +for the I/O. This service can be handy if the caller has a pre-assembled bio, | |
| 39 | +but wants to direct different portions of the bio to different devices:: | |
| 40 | + | |
| 41 | + int dm_io_sync_bvec(unsigned int num_regions, struct io_region *where, | |
| 42 | + int rw, struct bio_vec *bvec, | |
| 43 | + unsigned long *error_bits); | |
| 44 | + int dm_io_async_bvec(unsigned int num_regions, struct io_region *where, | |
| 45 | + int rw, struct bio_vec *bvec, | |
| 46 | + io_notify_fn fn, void *context); | |
| 47 | + | |
| 48 | +The third I/O service type takes a pointer to a vmalloc'd memory buffer as the | |
| 49 | +data buffer for the I/O. This service can be handy if the caller needs to do | |
| 50 | +I/O to a large region but doesn't want to allocate a large number of individual | |
| 51 | +memory pages:: | |
| 52 | + | |
| 53 | + int dm_io_sync_vm(unsigned int num_regions, struct io_region *where, int rw, | |
| 54 | + void *data, unsigned long *error_bits); | |
| 55 | + int dm_io_async_vm(unsigned int num_regions, struct io_region *where, int rw, | |
| 56 | + void *data, io_notify_fn fn, void *context); | |
| 57 | + | |
| 58 | +Callers of the asynchronous I/O services must include the name of a completion | |
| 59 | +callback routine and a pointer to some context data for the I/O:: | |
| 60 | + | |
| 61 | + typedef void (*io_notify_fn)(unsigned long error, void *context); | |
| 62 | + | |
| 63 | +The "error" parameter in this callback, as well as the `*error` parameter in | |
| 64 | +all of the synchronous versions, is a bitset (instead of a simple error value). | |
| 65 | +In the case of an write-I/O to multiple regions, this bitset allows dm-io to | |
| 66 | +indicate success or failure on each individual region. | |
| 67 | + | |
| 68 | +Before using any of the dm-io services, the user should call dm_io_get() | |
| 69 | +and specify the number of pages they expect to perform I/O on concurrently. | |
| 70 | +Dm-io will attempt to resize its mempool to make sure enough pages are | |
| 71 | +always available in order to avoid unnecessary waiting while performing I/O. | |
| 72 | + | |
| 73 | +When the user is finished using the dm-io services, they should call | |
| 74 | +dm_io_put() and specify the same number of pages that were given on the | |
| 75 | +dm_io_get() call. | |
| @@ -0,0 +1,57 @@ | ||
| 1 | +===================== | |
| 2 | +Device-Mapper Logging | |
| 3 | +===================== | |
| 4 | +The device-mapper logging code is used by some of the device-mapper | |
| 5 | +RAID targets to track regions of the disk that are not consistent. | |
| 6 | +A region (or portion of the address space) of the disk may be | |
| 7 | +inconsistent because a RAID stripe is currently being operated on or | |
| 8 | +a machine died while the region was being altered. In the case of | |
| 9 | +mirrors, a region would be considered dirty/inconsistent while you | |
| 10 | +are writing to it because the writes need to be replicated for all | |
| 11 | +the legs of the mirror and may not reach the legs at the same time. | |
| 12 | +Once all writes are complete, the region is considered clean again. | |
| 13 | + | |
| 14 | +There is a generic logging interface that the device-mapper RAID | |
| 15 | +implementations use to perform logging operations (see | |
| 16 | +dm_dirty_log_type in include/linux/dm-dirty-log.h). Various different | |
| 17 | +logging implementations are available and provide different | |
| 18 | +capabilities. The list includes: | |
| 19 | + | |
| 20 | +============== ============================================================== | |
| 21 | +Type Files | |
| 22 | +============== ============================================================== | |
| 23 | +disk drivers/md/dm-log.c | |
| 24 | +core drivers/md/dm-log.c | |
| 25 | +userspace drivers/md/dm-log-userspace* include/linux/dm-log-userspace.h | |
| 26 | +============== ============================================================== | |
| 27 | + | |
| 28 | +The "disk" log type | |
| 29 | +------------------- | |
| 30 | +This log implementation commits the log state to disk. This way, the | |
| 31 | +logging state survives reboots/crashes. | |
| 32 | + | |
| 33 | +The "core" log type | |
| 34 | +------------------- | |
| 35 | +This log implementation keeps the log state in memory. The log state | |
| 36 | +will not survive a reboot or crash, but there may be a small boost in | |
| 37 | +performance. This method can also be used if no storage device is | |
| 38 | +available for storing log state. | |
| 39 | + | |
| 40 | +The "userspace" log type | |
| 41 | +------------------------ | |
| 42 | +This log type simply provides a way to export the log API to userspace, | |
| 43 | +so log implementations can be done there. This is done by forwarding most | |
| 44 | +logging requests to userspace, where a daemon receives and processes the | |
| 45 | +request. | |
| 46 | + | |
| 47 | +The structure used for communication between kernel and userspace are | |
| 48 | +located in include/linux/dm-log-userspace.h. Due to the frequency, | |
| 49 | +diversity, and 2-way communication nature of the exchanges between | |
| 50 | +kernel and userspace, 'connector' is used as the interface for | |
| 51 | +communication. | |
| 52 | + | |
| 53 | +There are currently two userspace log implementations that leverage this | |
| 54 | +framework - "clustered-disk" and "clustered-core". These implementations | |
| 55 | +provide a cluster-coherent log for shared-storage. Device-mapper mirroring | |
| 56 | +can be used in a shared-storage environment when the cluster log implementations | |
| 57 | +are employed. | |
| @@ -0,0 +1,48 @@ | ||
| 1 | +=============== | |
| 2 | +dm-queue-length | |
| 3 | +=============== | |
| 4 | + | |
| 5 | +dm-queue-length is a path selector module for device-mapper targets, | |
| 6 | +which selects a path with the least number of in-flight I/Os. | |
| 7 | +The path selector name is 'queue-length'. | |
| 8 | + | |
| 9 | +Table parameters for each path: [<repeat_count>] | |
| 10 | + | |
| 11 | +:: | |
| 12 | + | |
| 13 | + <repeat_count>: The number of I/Os to dispatch using the selected | |
| 14 | + path before switching to the next path. | |
| 15 | + If not given, internal default is used. To check | |
| 16 | + the default value, see the activated table. | |
| 17 | + | |
| 18 | +Status for each path: <status> <fail-count> <in-flight> | |
| 19 | + | |
| 20 | +:: | |
| 21 | + | |
| 22 | + <status>: 'A' if the path is active, 'F' if the path is failed. | |
| 23 | + <fail-count>: The number of path failures. | |
| 24 | + <in-flight>: The number of in-flight I/Os on the path. | |
| 25 | + | |
| 26 | + | |
| 27 | +Algorithm | |
| 28 | +========= | |
| 29 | + | |
| 30 | +dm-queue-length increments/decrements 'in-flight' when an I/O is | |
| 31 | +dispatched/completed respectively. | |
| 32 | +dm-queue-length selects a path with the minimum 'in-flight'. | |
| 33 | + | |
| 34 | + | |
| 35 | +Examples | |
| 36 | +======== | |
| 37 | +In case that 2 paths (sda and sdb) are used with repeat_count == 128. | |
| 38 | + | |
| 39 | +:: | |
| 40 | + | |
| 41 | + # echo "0 10 multipath 0 0 1 1 queue-length 0 2 1 8:0 128 8:16 128" \ | |
| 42 | + dmsetup create test | |
| 43 | + # | |
| 44 | + # dmsetup table | |
| 45 | + test: 0 10 multipath 0 0 1 1 queue-length 0 2 1 8:0 128 8:16 128 | |
| 46 | + # | |
| 47 | + # dmsetup status | |
| 48 | + test: 0 10 multipath 2 0 0 0 1 1 E 0 2 1 8:0 A 0 0 8:16 A 0 0 | |
| @@ -0,0 +1,419 @@ | ||
| 1 | +======= | |
| 2 | +dm-raid | |
| 3 | +======= | |
| 4 | + | |
| 5 | +The device-mapper RAID (dm-raid) target provides a bridge from DM to MD. | |
| 6 | +It allows the MD RAID drivers to be accessed using a device-mapper | |
| 7 | +interface. | |
| 8 | + | |
| 9 | + | |
| 10 | +Mapping Table Interface | |
| 11 | +----------------------- | |
| 12 | +The target is named "raid" and it accepts the following parameters:: | |
| 13 | + | |
| 14 | + <raid_type> <#raid_params> <raid_params> \ | |
| 15 | + <#raid_devs> <metadata_dev0> <dev0> [.. <metadata_devN> <devN>] | |
| 16 | + | |
| 17 | +<raid_type>: | |
| 18 | + | |
| 19 | + ============= =============================================================== | |
| 20 | + raid0 RAID0 striping (no resilience) | |
| 21 | + raid1 RAID1 mirroring | |
| 22 | + raid4 RAID4 with dedicated last parity disk | |
| 23 | + raid5_n RAID5 with dedicated last parity disk supporting takeover | |
| 24 | + Same as raid4 | |
| 25 | + | |
| 26 | + - Transitory layout | |
| 27 | + raid5_la RAID5 left asymmetric | |
| 28 | + | |
| 29 | + - rotating parity 0 with data continuation | |
| 30 | + raid5_ra RAID5 right asymmetric | |
| 31 | + | |
| 32 | + - rotating parity N with data continuation | |
| 33 | + raid5_ls RAID5 left symmetric | |
| 34 | + | |
| 35 | + - rotating parity 0 with data restart | |
| 36 | + raid5_rs RAID5 right symmetric | |
| 37 | + | |
| 38 | + - rotating parity N with data restart | |
| 39 | + raid6_zr RAID6 zero restart | |
| 40 | + | |
| 41 | + - rotating parity zero (left-to-right) with data restart | |
| 42 | + raid6_nr RAID6 N restart | |
| 43 | + | |
| 44 | + - rotating parity N (right-to-left) with data restart | |
| 45 | + raid6_nc RAID6 N continue | |
| 46 | + | |
| 47 | + - rotating parity N (right-to-left) with data continuation | |
| 48 | + raid6_n_6 RAID6 with dedicate parity disks | |
| 49 | + | |
| 50 | + - parity and Q-syndrome on the last 2 disks; | |
| 51 | + layout for takeover from/to raid4/raid5_n | |
| 52 | + raid6_la_6 Same as "raid_la" plus dedicated last Q-syndrome disk | |
| 53 | + | |
| 54 | + - layout for takeover from raid5_la from/to raid6 | |
| 55 | + raid6_ra_6 Same as "raid5_ra" dedicated last Q-syndrome disk | |
| 56 | + | |
| 57 | + - layout for takeover from raid5_ra from/to raid6 | |
| 58 | + raid6_ls_6 Same as "raid5_ls" dedicated last Q-syndrome disk | |
| 59 | + | |
| 60 | + - layout for takeover from raid5_ls from/to raid6 | |
| 61 | + raid6_rs_6 Same as "raid5_rs" dedicated last Q-syndrome disk | |
| 62 | + | |
| 63 | + - layout for takeover from raid5_rs from/to raid6 | |
| 64 | + raid10 Various RAID10 inspired algorithms chosen by additional params | |
| 65 | + (see raid10_format and raid10_copies below) | |
| 66 | + | |
| 67 | + - RAID10: Striped Mirrors (aka 'Striping on top of mirrors') | |
| 68 | + - RAID1E: Integrated Adjacent Stripe Mirroring | |
| 69 | + - RAID1E: Integrated Offset Stripe Mirroring | |
| 70 | + - and other similar RAID10 variants | |
| 71 | + ============= =============================================================== | |
| 72 | + | |
| 73 | + Reference: Chapter 4 of | |
| 74 | + http://www.snia.org/sites/default/files/SNIA_DDF_Technical_Position_v2.0.pdf | |
| 75 | + | |
| 76 | +<#raid_params>: The number of parameters that follow. | |
| 77 | + | |
| 78 | +<raid_params> consists of | |
| 79 | + | |
| 80 | + Mandatory parameters: | |
| 81 | + <chunk_size>: | |
| 82 | + Chunk size in sectors. This parameter is often known as | |
| 83 | + "stripe size". It is the only mandatory parameter and | |
| 84 | + is placed first. | |
| 85 | + | |
| 86 | + followed by optional parameters (in any order): | |
| 87 | + [sync|nosync] | |
| 88 | + Force or prevent RAID initialization. | |
| 89 | + | |
| 90 | + [rebuild <idx>] | |
| 91 | + Rebuild drive number 'idx' (first drive is 0). | |
| 92 | + | |
| 93 | + [daemon_sleep <ms>] | |
| 94 | + Interval between runs of the bitmap daemon that | |
| 95 | + clear bits. A longer interval means less bitmap I/O but | |
| 96 | + resyncing after a failure is likely to take longer. | |
| 97 | + | |
| 98 | + [min_recovery_rate <kB/sec/disk>] | |
| 99 | + Throttle RAID initialization | |
| 100 | + [max_recovery_rate <kB/sec/disk>] | |
| 101 | + Throttle RAID initialization | |
| 102 | + [write_mostly <idx>] | |
| 103 | + Mark drive index 'idx' write-mostly. | |
| 104 | + [max_write_behind <sectors>] | |
| 105 | + See '--write-behind=' (man mdadm) | |
| 106 | + [stripe_cache <sectors>] | |
| 107 | + Stripe cache size (RAID 4/5/6 only) | |
| 108 | + [region_size <sectors>] | |
| 109 | + The region_size multiplied by the number of regions is the | |
| 110 | + logical size of the array. The bitmap records the device | |
| 111 | + synchronisation state for each region. | |
| 112 | + | |
| 113 | + [raid10_copies <# copies>], [raid10_format <near|far|offset>] | |
| 114 | + These two options are used to alter the default layout of | |
| 115 | + a RAID10 configuration. The number of copies is can be | |
| 116 | + specified, but the default is 2. There are also three | |
| 117 | + variations to how the copies are laid down - the default | |
| 118 | + is "near". Near copies are what most people think of with | |
| 119 | + respect to mirroring. If these options are left unspecified, | |
| 120 | + or 'raid10_copies 2' and/or 'raid10_format near' are given, | |
| 121 | + then the layouts for 2, 3 and 4 devices are: | |
| 122 | + | |
| 123 | + ======== ========== ============== | |
| 124 | + 2 drives 3 drives 4 drives | |
| 125 | + ======== ========== ============== | |
| 126 | + A1 A1 A1 A1 A2 A1 A1 A2 A2 | |
| 127 | + A2 A2 A2 A3 A3 A3 A3 A4 A4 | |
| 128 | + A3 A3 A4 A4 A5 A5 A5 A6 A6 | |
| 129 | + A4 A4 A5 A6 A6 A7 A7 A8 A8 | |
| 130 | + .. .. .. .. .. .. .. .. .. | |
| 131 | + ======== ========== ============== | |
| 132 | + | |
| 133 | + The 2-device layout is equivalent 2-way RAID1. The 4-device | |
| 134 | + layout is what a traditional RAID10 would look like. The | |
| 135 | + 3-device layout is what might be called a 'RAID1E - Integrated | |
| 136 | + Adjacent Stripe Mirroring'. | |
| 137 | + | |
| 138 | + If 'raid10_copies 2' and 'raid10_format far', then the layouts | |
| 139 | + for 2, 3 and 4 devices are: | |
| 140 | + | |
| 141 | + ======== ============ =================== | |
| 142 | + 2 drives 3 drives 4 drives | |
| 143 | + ======== ============ =================== | |
| 144 | + A1 A2 A1 A2 A3 A1 A2 A3 A4 | |
| 145 | + A3 A4 A4 A5 A6 A5 A6 A7 A8 | |
| 146 | + A5 A6 A7 A8 A9 A9 A10 A11 A12 | |
| 147 | + .. .. .. .. .. .. .. .. .. | |
| 148 | + A2 A1 A3 A1 A2 A2 A1 A4 A3 | |
| 149 | + A4 A3 A6 A4 A5 A6 A5 A8 A7 | |
| 150 | + A6 A5 A9 A7 A8 A10 A9 A12 A11 | |
| 151 | + .. .. .. .. .. .. .. .. .. | |
| 152 | + ======== ============ =================== | |
| 153 | + | |
| 154 | + If 'raid10_copies 2' and 'raid10_format offset', then the | |
| 155 | + layouts for 2, 3 and 4 devices are: | |
| 156 | + | |
| 157 | + ======== ========== ================ | |
| 158 | + 2 drives 3 drives 4 drives | |
| 159 | + ======== ========== ================ | |
| 160 | + A1 A2 A1 A2 A3 A1 A2 A3 A4 | |
| 161 | + A2 A1 A3 A1 A2 A2 A1 A4 A3 | |
| 162 | + A3 A4 A4 A5 A6 A5 A6 A7 A8 | |
| 163 | + A4 A3 A6 A4 A5 A6 A5 A8 A7 | |
| 164 | + A5 A6 A7 A8 A9 A9 A10 A11 A12 | |
| 165 | + A6 A5 A9 A7 A8 A10 A9 A12 A11 | |
| 166 | + .. .. .. .. .. .. .. .. .. | |
| 167 | + ======== ========== ================ | |
| 168 | + | |
| 169 | + Here we see layouts closely akin to 'RAID1E - Integrated | |
| 170 | + Offset Stripe Mirroring'. | |
| 171 | + | |
| 172 | + [delta_disks <N>] | |
| 173 | + The delta_disks option value (-251 < N < +251) triggers | |
| 174 | + device removal (negative value) or device addition (positive | |
| 175 | + value) to any reshape supporting raid levels 4/5/6 and 10. | |
| 176 | + RAID levels 4/5/6 allow for addition of devices (metadata | |
| 177 | + and data device tuple), raid10_near and raid10_offset only | |
| 178 | + allow for device addition. raid10_far does not support any | |
| 179 | + reshaping at all. | |
| 180 | + A minimum of devices have to be kept to enforce resilience, | |
| 181 | + which is 3 devices for raid4/5 and 4 devices for raid6. | |
| 182 | + | |
| 183 | + [data_offset <sectors>] | |
| 184 | + This option value defines the offset into each data device | |
| 185 | + where the data starts. This is used to provide out-of-place | |
| 186 | + reshaping space to avoid writing over data while | |
| 187 | + changing the layout of stripes, hence an interruption/crash | |
| 188 | + may happen at any time without the risk of losing data. | |
| 189 | + E.g. when adding devices to an existing raid set during | |
| 190 | + forward reshaping, the out-of-place space will be allocated | |
| 191 | + at the beginning of each raid device. The kernel raid4/5/6/10 | |
| 192 | + MD personalities supporting such device addition will read the data from | |
| 193 | + the existing first stripes (those with smaller number of stripes) | |
| 194 | + starting at data_offset to fill up a new stripe with the larger | |
| 195 | + number of stripes, calculate the redundancy blocks (CRC/Q-syndrome) | |
| 196 | + and write that new stripe to offset 0. Same will be applied to all | |
| 197 | + N-1 other new stripes. This out-of-place scheme is used to change | |
| 198 | + the RAID type (i.e. the allocation algorithm) as well, e.g. | |
| 199 | + changing from raid5_ls to raid5_n. | |
| 200 | + | |
| 201 | + [journal_dev <dev>] | |
| 202 | + This option adds a journal device to raid4/5/6 raid sets and | |
| 203 | + uses it to close the 'write hole' caused by the non-atomic updates | |
| 204 | + to the component devices which can cause data loss during recovery. | |
| 205 | + The journal device is used as writethrough thus causing writes to | |
| 206 | + be throttled versus non-journaled raid4/5/6 sets. | |
| 207 | + Takeover/reshape is not possible with a raid4/5/6 journal device; | |
| 208 | + it has to be deconfigured before requesting these. | |
| 209 | + | |
| 210 | + [journal_mode <mode>] | |
| 211 | + This option sets the caching mode on journaled raid4/5/6 raid sets | |
| 212 | + (see 'journal_dev <dev>' above) to 'writethrough' or 'writeback'. | |
| 213 | + If 'writeback' is selected the journal device has to be resilient | |
| 214 | + and must not suffer from the 'write hole' problem itself (e.g. use | |
| 215 | + raid1 or raid10) to avoid a single point of failure. | |
| 216 | + | |
| 217 | +<#raid_devs>: The number of devices composing the array. | |
| 218 | + Each device consists of two entries. The first is the device | |
| 219 | + containing the metadata (if any); the second is the one containing the | |
| 220 | + data. A Maximum of 64 metadata/data device entries are supported | |
| 221 | + up to target version 1.8.0. | |
| 222 | + 1.9.0 supports up to 253 which is enforced by the used MD kernel runtime. | |
| 223 | + | |
| 224 | + If a drive has failed or is missing at creation time, a '-' can be | |
| 225 | + given for both the metadata and data drives for a given position. | |
| 226 | + | |
| 227 | + | |
| 228 | +Example Tables | |
| 229 | +-------------- | |
| 230 | + | |
| 231 | +:: | |
| 232 | + | |
| 233 | + # RAID4 - 4 data drives, 1 parity (no metadata devices) | |
| 234 | + # No metadata devices specified to hold superblock/bitmap info | |
| 235 | + # Chunk size of 1MiB | |
| 236 | + # (Lines separated for easy reading) | |
| 237 | + | |
| 238 | + 0 1960893648 raid \ | |
| 239 | + raid4 1 2048 \ | |
| 240 | + 5 - 8:17 - 8:33 - 8:49 - 8:65 - 8:81 | |
| 241 | + | |
| 242 | + # RAID4 - 4 data drives, 1 parity (with metadata devices) | |
| 243 | + # Chunk size of 1MiB, force RAID initialization, | |
| 244 | + # min recovery rate at 20 kiB/sec/disk | |
| 245 | + | |
| 246 | + 0 1960893648 raid \ | |
| 247 | + raid4 4 2048 sync min_recovery_rate 20 \ | |
| 248 | + 5 8:17 8:18 8:33 8:34 8:49 8:50 8:65 8:66 8:81 8:82 | |
| 249 | + | |
| 250 | + | |
| 251 | +Status Output | |
| 252 | +------------- | |
| 253 | +'dmsetup table' displays the table used to construct the mapping. | |
| 254 | +The optional parameters are always printed in the order listed | |
| 255 | +above with "sync" or "nosync" always output ahead of the other | |
| 256 | +arguments, regardless of the order used when originally loading the table. | |
| 257 | +Arguments that can be repeated are ordered by value. | |
| 258 | + | |
| 259 | + | |
| 260 | +'dmsetup status' yields information on the state and health of the array. | |
| 261 | +The output is as follows (normally a single line, but expanded here for | |
| 262 | +clarity):: | |
| 263 | + | |
| 264 | + 1: <s> <l> raid \ | |
| 265 | + 2: <raid_type> <#devices> <health_chars> \ | |
| 266 | + 3: <sync_ratio> <sync_action> <mismatch_cnt> | |
| 267 | + | |
| 268 | +Line 1 is the standard output produced by device-mapper. | |
| 269 | + | |
| 270 | +Line 2 & 3 are produced by the raid target and are best explained by example:: | |
| 271 | + | |
| 272 | + 0 1960893648 raid raid4 5 AAAAA 2/490221568 init 0 | |
| 273 | + | |
| 274 | +Here we can see the RAID type is raid4, there are 5 devices - all of | |
| 275 | +which are 'A'live, and the array is 2/490221568 complete with its initial | |
| 276 | +recovery. Here is a fuller description of the individual fields: | |
| 277 | + | |
| 278 | + =============== ========================================================= | |
| 279 | + <raid_type> Same as the <raid_type> used to create the array. | |
| 280 | + <health_chars> One char for each device, indicating: | |
| 281 | + | |
| 282 | + - 'A' = alive and in-sync | |
| 283 | + - 'a' = alive but not in-sync | |
| 284 | + - 'D' = dead/failed. | |
| 285 | + <sync_ratio> The ratio indicating how much of the array has undergone | |
| 286 | + the process described by 'sync_action'. If the | |
| 287 | + 'sync_action' is "check" or "repair", then the process | |
| 288 | + of "resync" or "recover" can be considered complete. | |
| 289 | + <sync_action> One of the following possible states: | |
| 290 | + | |
| 291 | + idle | |
| 292 | + - No synchronization action is being performed. | |
| 293 | + frozen | |
| 294 | + - The current action has been halted. | |
| 295 | + resync | |
| 296 | + - Array is undergoing its initial synchronization | |
| 297 | + or is resynchronizing after an unclean shutdown | |
| 298 | + (possibly aided by a bitmap). | |
| 299 | + recover | |
| 300 | + - A device in the array is being rebuilt or | |
| 301 | + replaced. | |
| 302 | + check | |
| 303 | + - A user-initiated full check of the array is | |
| 304 | + being performed. All blocks are read and | |
| 305 | + checked for consistency. The number of | |
| 306 | + discrepancies found are recorded in | |
| 307 | + <mismatch_cnt>. No changes are made to the | |
| 308 | + array by this action. | |
| 309 | + repair | |
| 310 | + - The same as "check", but discrepancies are | |
| 311 | + corrected. | |
| 312 | + reshape | |
| 313 | + - The array is undergoing a reshape. | |
| 314 | + <mismatch_cnt> The number of discrepancies found between mirror copies | |
| 315 | + in RAID1/10 or wrong parity values found in RAID4/5/6. | |
| 316 | + This value is valid only after a "check" of the array | |
| 317 | + is performed. A healthy array has a 'mismatch_cnt' of 0. | |
| 318 | + <data_offset> The current data offset to the start of the user data on | |
| 319 | + each component device of a raid set (see the respective | |
| 320 | + raid parameter to support out-of-place reshaping). | |
| 321 | + <journal_char> - 'A' - active write-through journal device. | |
| 322 | + - 'a' - active write-back journal device. | |
| 323 | + - 'D' - dead journal device. | |
| 324 | + - '-' - no journal device. | |
| 325 | + =============== ========================================================= | |
| 326 | + | |
| 327 | + | |
| 328 | +Message Interface | |
| 329 | +----------------- | |
| 330 | +The dm-raid target will accept certain actions through the 'message' interface. | |
| 331 | +('man dmsetup' for more information on the message interface.) These actions | |
| 332 | +include: | |
| 333 | + | |
| 334 | + ========= ================================================ | |
| 335 | + "idle" Halt the current sync action. | |
| 336 | + "frozen" Freeze the current sync action. | |
| 337 | + "resync" Initiate/continue a resync. | |
| 338 | + "recover" Initiate/continue a recover process. | |
| 339 | + "check" Initiate a check (i.e. a "scrub") of the array. | |
| 340 | + "repair" Initiate a repair of the array. | |
| 341 | + ========= ================================================ | |
| 342 | + | |
| 343 | + | |
| 344 | +Discard Support | |
| 345 | +--------------- | |
| 346 | +The implementation of discard support among hardware vendors varies. | |
| 347 | +When a block is discarded, some storage devices will return zeroes when | |
| 348 | +the block is read. These devices set the 'discard_zeroes_data' | |
| 349 | +attribute. Other devices will return random data. Confusingly, some | |
| 350 | +devices that advertise 'discard_zeroes_data' will not reliably return | |
| 351 | +zeroes when discarded blocks are read! Since RAID 4/5/6 uses blocks | |
| 352 | +from a number of devices to calculate parity blocks and (for performance | |
| 353 | +reasons) relies on 'discard_zeroes_data' being reliable, it is important | |
| 354 | +that the devices be consistent. Blocks may be discarded in the middle | |
| 355 | +of a RAID 4/5/6 stripe and if subsequent read results are not | |
| 356 | +consistent, the parity blocks may be calculated differently at any time; | |
| 357 | +making the parity blocks useless for redundancy. It is important to | |
| 358 | +understand how your hardware behaves with discards if you are going to | |
| 359 | +enable discards with RAID 4/5/6. | |
| 360 | + | |
| 361 | +Since the behavior of storage devices is unreliable in this respect, | |
| 362 | +even when reporting 'discard_zeroes_data', by default RAID 4/5/6 | |
| 363 | +discard support is disabled -- this ensures data integrity at the | |
| 364 | +expense of losing some performance. | |
| 365 | + | |
| 366 | +Storage devices that properly support 'discard_zeroes_data' are | |
| 367 | +increasingly whitelisted in the kernel and can thus be trusted. | |
| 368 | + | |
| 369 | +For trusted devices, the following dm-raid module parameter can be set | |
| 370 | +to safely enable discard support for RAID 4/5/6: | |
| 371 | + | |
| 372 | + 'devices_handle_discards_safely' | |
| 373 | + | |
| 374 | + | |
| 375 | +Version History | |
| 376 | +--------------- | |
| 377 | + | |
| 378 | +:: | |
| 379 | + | |
| 380 | + 1.0.0 Initial version. Support for RAID 4/5/6 | |
| 381 | + 1.1.0 Added support for RAID 1 | |
| 382 | + 1.2.0 Handle creation of arrays that contain failed devices. | |
| 383 | + 1.3.0 Added support for RAID 10 | |
| 384 | + 1.3.1 Allow device replacement/rebuild for RAID 10 | |
| 385 | + 1.3.2 Fix/improve redundancy checking for RAID10 | |
| 386 | + 1.4.0 Non-functional change. Removes arg from mapping function. | |
| 387 | + 1.4.1 RAID10 fix redundancy validation checks (commit 55ebbb5). | |
| 388 | + 1.4.2 Add RAID10 "far" and "offset" algorithm support. | |
| 389 | + 1.5.0 Add message interface to allow manipulation of the sync_action. | |
| 390 | + New status (STATUSTYPE_INFO) fields: sync_action and mismatch_cnt. | |
| 391 | + 1.5.1 Add ability to restore transiently failed devices on resume. | |
| 392 | + 1.5.2 'mismatch_cnt' is zero unless [last_]sync_action is "check". | |
| 393 | + 1.6.0 Add discard support (and devices_handle_discard_safely module param). | |
| 394 | + 1.7.0 Add support for MD RAID0 mappings. | |
| 395 | + 1.8.0 Explicitly check for compatible flags in the superblock metadata | |
| 396 | + and reject to start the raid set if any are set by a newer | |
| 397 | + target version, thus avoiding data corruption on a raid set | |
| 398 | + with a reshape in progress. | |
| 399 | + 1.9.0 Add support for RAID level takeover/reshape/region size | |
| 400 | + and set size reduction. | |
| 401 | + 1.9.1 Fix activation of existing RAID 4/10 mapped devices | |
| 402 | + 1.9.2 Don't emit '- -' on the status table line in case the constructor | |
| 403 | + fails reading a superblock. Correctly emit 'maj:min1 maj:min2' and | |
| 404 | + 'D' on the status line. If '- -' is passed into the constructor, emit | |
| 405 | + '- -' on the table line and '-' as the status line health character. | |
| 406 | + 1.10.0 Add support for raid4/5/6 journal device | |
| 407 | + 1.10.1 Fix data corruption on reshape request | |
| 408 | + 1.11.0 Fix table line argument order | |
| 409 | + (wrong raid10_copies/raid10_format sequence) | |
| 410 | + 1.11.1 Add raid4/5/6 journal write-back support via journal_mode option | |
| 411 | + 1.12.1 Fix for MD deadlock between mddev_suspend() and md_write_start() available | |
| 412 | + 1.13.0 Fix dev_health status at end of "recover" (was 'a', now 'A') | |
| 413 | + 1.13.1 Fix deadlock caused by early md_stop_writes(). Also fix size an | |
| 414 | + state races. | |
| 415 | + 1.13.2 Fix raid redundancy validation and avoid keeping raid set frozen | |
| 416 | + 1.14.0 Fix reshape race on small devices. Fix stripe adding reshape | |
| 417 | + deadlock/potential data corruption. Update superblock when | |
| 418 | + specific devices are requested via rebuild. Fix RAID leg | |
| 419 | + rebuild errors. | |
| @@ -0,0 +1,101 @@ | ||
| 1 | +=============== | |
| 2 | +dm-service-time | |
| 3 | +=============== | |
| 4 | + | |
| 5 | +dm-service-time is a path selector module for device-mapper targets, | |
| 6 | +which selects a path with the shortest estimated service time for | |
| 7 | +the incoming I/O. | |
| 8 | + | |
| 9 | +The service time for each path is estimated by dividing the total size | |
| 10 | +of in-flight I/Os on a path with the performance value of the path. | |
| 11 | +The performance value is a relative throughput value among all paths | |
| 12 | +in a path-group, and it can be specified as a table argument. | |
| 13 | + | |
| 14 | +The path selector name is 'service-time'. | |
| 15 | + | |
| 16 | +Table parameters for each path: | |
| 17 | + | |
| 18 | + [<repeat_count> [<relative_throughput>]] | |
| 19 | + <repeat_count>: | |
| 20 | + The number of I/Os to dispatch using the selected | |
| 21 | + path before switching to the next path. | |
| 22 | + If not given, internal default is used. To check | |
| 23 | + the default value, see the activated table. | |
| 24 | + <relative_throughput>: | |
| 25 | + The relative throughput value of the path | |
| 26 | + among all paths in the path-group. | |
| 27 | + The valid range is 0-100. | |
| 28 | + If not given, minimum value '1' is used. | |
| 29 | + If '0' is given, the path isn't selected while | |
| 30 | + other paths having a positive value are available. | |
| 31 | + | |
| 32 | +Status for each path: | |
| 33 | + | |
| 34 | + <status> <fail-count> <in-flight-size> <relative_throughput> | |
| 35 | + <status>: | |
| 36 | + 'A' if the path is active, 'F' if the path is failed. | |
| 37 | + <fail-count>: | |
| 38 | + The number of path failures. | |
| 39 | + <in-flight-size>: | |
| 40 | + The size of in-flight I/Os on the path. | |
| 41 | + <relative_throughput>: | |
| 42 | + The relative throughput value of the path | |
| 43 | + among all paths in the path-group. | |
| 44 | + | |
| 45 | + | |
| 46 | +Algorithm | |
| 47 | +========= | |
| 48 | + | |
| 49 | +dm-service-time adds the I/O size to 'in-flight-size' when the I/O is | |
| 50 | +dispatched and subtracts when completed. | |
| 51 | +Basically, dm-service-time selects a path having minimum service time | |
| 52 | +which is calculated by:: | |
| 53 | + | |
| 54 | + ('in-flight-size' + 'size-of-incoming-io') / 'relative_throughput' | |
| 55 | + | |
| 56 | +However, some optimizations below are used to reduce the calculation | |
| 57 | +as much as possible. | |
| 58 | + | |
| 59 | + 1. If the paths have the same 'relative_throughput', skip | |
| 60 | + the division and just compare the 'in-flight-size'. | |
| 61 | + | |
| 62 | + 2. If the paths have the same 'in-flight-size', skip the division | |
| 63 | + and just compare the 'relative_throughput'. | |
| 64 | + | |
| 65 | + 3. If some paths have non-zero 'relative_throughput' and others | |
| 66 | + have zero 'relative_throughput', ignore those paths with zero | |
| 67 | + 'relative_throughput'. | |
| 68 | + | |
| 69 | +If such optimizations can't be applied, calculate service time, and | |
| 70 | +compare service time. | |
| 71 | +If calculated service time is equal, the path having maximum | |
| 72 | +'relative_throughput' may be better. So compare 'relative_throughput' | |
| 73 | +then. | |
| 74 | + | |
| 75 | + | |
| 76 | +Examples | |
| 77 | +======== | |
| 78 | +In case that 2 paths (sda and sdb) are used with repeat_count == 128 | |
| 79 | +and sda has an average throughput 1GB/s and sdb has 4GB/s, | |
| 80 | +'relative_throughput' value may be '1' for sda and '4' for sdb:: | |
| 81 | + | |
| 82 | + # echo "0 10 multipath 0 0 1 1 service-time 0 2 2 8:0 128 1 8:16 128 4" \ | |
| 83 | + dmsetup create test | |
| 84 | + # | |
| 85 | + # dmsetup table | |
| 86 | + test: 0 10 multipath 0 0 1 1 service-time 0 2 2 8:0 128 1 8:16 128 4 | |
| 87 | + # | |
| 88 | + # dmsetup status | |
| 89 | + test: 0 10 multipath 2 0 0 0 1 1 E 0 2 2 8:0 A 0 0 1 8:16 A 0 0 4 | |
| 90 | + | |
| 91 | + | |
| 92 | +Or '2' for sda and '8' for sdb would be also true:: | |
| 93 | + | |
| 94 | + # echo "0 10 multipath 0 0 1 1 service-time 0 2 2 8:0 128 2 8:16 128 8" \ | |
| 95 | + dmsetup create test | |
| 96 | + # | |
| 97 | + # dmsetup table | |
| 98 | + test: 0 10 multipath 0 0 1 1 service-time 0 2 2 8:0 128 2 8:16 128 8 | |
| 99 | + # | |
| 100 | + # dmsetup status | |
| 101 | + test: 0 10 multipath 2 0 0 0 1 1 E 0 2 2 8:0 A 0 0 2 8:16 A 0 0 8 | |
| @@ -0,0 +1,110 @@ | ||
| 1 | +==================== | |
| 2 | +device-mapper uevent | |
| 3 | +==================== | |
| 4 | + | |
| 5 | +The device-mapper uevent code adds the capability to device-mapper to create | |
| 6 | +and send kobject uevents (uevents). Previously device-mapper events were only | |
| 7 | +available through the ioctl interface. The advantage of the uevents interface | |
| 8 | +is the event contains environment attributes providing increased context for | |
| 9 | +the event avoiding the need to query the state of the device-mapper device after | |
| 10 | +the event is received. | |
| 11 | + | |
| 12 | +There are two functions currently for device-mapper events. The first function | |
| 13 | +listed creates the event and the second function sends the event(s):: | |
| 14 | + | |
| 15 | + void dm_path_uevent(enum dm_uevent_type event_type, struct dm_target *ti, | |
| 16 | + const char *path, unsigned nr_valid_paths) | |
| 17 | + | |
| 18 | + void dm_send_uevents(struct list_head *events, struct kobject *kobj) | |
| 19 | + | |
| 20 | + | |
| 21 | +The variables added to the uevent environment are: | |
| 22 | + | |
| 23 | +Variable Name: DM_TARGET | |
| 24 | +------------------------ | |
| 25 | +:Uevent Action(s): KOBJ_CHANGE | |
| 26 | +:Type: string | |
| 27 | +:Description: | |
| 28 | +:Value: Name of device-mapper target that generated the event. | |
| 29 | + | |
| 30 | +Variable Name: DM_ACTION | |
| 31 | +------------------------ | |
| 32 | +:Uevent Action(s): KOBJ_CHANGE | |
| 33 | +:Type: string | |
| 34 | +:Description: | |
| 35 | +:Value: Device-mapper specific action that caused the uevent action. | |
| 36 | + PATH_FAILED - A path has failed; | |
| 37 | + PATH_REINSTATED - A path has been reinstated. | |
| 38 | + | |
| 39 | +Variable Name: DM_SEQNUM | |
| 40 | +------------------------ | |
| 41 | +:Uevent Action(s): KOBJ_CHANGE | |
| 42 | +:Type: unsigned integer | |
| 43 | +:Description: A sequence number for this specific device-mapper device. | |
| 44 | +:Value: Valid unsigned integer range. | |
| 45 | + | |
| 46 | +Variable Name: DM_PATH | |
| 47 | +---------------------- | |
| 48 | +:Uevent Action(s): KOBJ_CHANGE | |
| 49 | +:Type: string | |
| 50 | +:Description: Major and minor number of the path device pertaining to this | |
| 51 | + event. | |
| 52 | +:Value: Path name in the form of "Major:Minor" | |
| 53 | + | |
| 54 | +Variable Name: DM_NR_VALID_PATHS | |
| 55 | +-------------------------------- | |
| 56 | +:Uevent Action(s): KOBJ_CHANGE | |
| 57 | +:Type: unsigned integer | |
| 58 | +:Description: | |
| 59 | +:Value: Valid unsigned integer range. | |
| 60 | + | |
| 61 | +Variable Name: DM_NAME | |
| 62 | +---------------------- | |
| 63 | +:Uevent Action(s): KOBJ_CHANGE | |
| 64 | +:Type: string | |
| 65 | +:Description: Name of the device-mapper device. | |
| 66 | +:Value: Name | |
| 67 | + | |
| 68 | +Variable Name: DM_UUID | |
| 69 | +---------------------- | |
| 70 | +:Uevent Action(s): KOBJ_CHANGE | |
| 71 | +:Type: string | |
| 72 | +:Description: UUID of the device-mapper device. | |
| 73 | +:Value: UUID. (Empty string if there isn't one.) | |
| 74 | + | |
| 75 | +An example of the uevents generated as captured by udevmonitor is shown | |
| 76 | +below | |
| 77 | + | |
| 78 | +1.) Path failure:: | |
| 79 | + | |
| 80 | + UEVENT[1192521009.711215] change@/block/dm-3 | |
| 81 | + ACTION=change | |
| 82 | + DEVPATH=/block/dm-3 | |
| 83 | + SUBSYSTEM=block | |
| 84 | + DM_TARGET=multipath | |
| 85 | + DM_ACTION=PATH_FAILED | |
| 86 | + DM_SEQNUM=1 | |
| 87 | + DM_PATH=8:32 | |
| 88 | + DM_NR_VALID_PATHS=0 | |
| 89 | + DM_NAME=mpath2 | |
| 90 | + DM_UUID=mpath-35333333000002328 | |
| 91 | + MINOR=3 | |
| 92 | + MAJOR=253 | |
| 93 | + SEQNUM=1130 | |
| 94 | + | |
| 95 | +2.) Path reinstate:: | |
| 96 | + | |
| 97 | + UEVENT[1192521132.989927] change@/block/dm-3 | |
| 98 | + ACTION=change | |
| 99 | + DEVPATH=/block/dm-3 | |
| 100 | + SUBSYSTEM=block | |
| 101 | + DM_TARGET=multipath | |
| 102 | + DM_ACTION=PATH_REINSTATED | |
| 103 | + DM_SEQNUM=2 | |
| 104 | + DM_PATH=8:32 | |
| 105 | + DM_NR_VALID_PATHS=1 | |
| 106 | + DM_NAME=mpath2 | |
| 107 | + DM_UUID=mpath-35333333000002328 | |
| 108 | + MINOR=3 | |
| 109 | + MAJOR=253 | |
| 110 | + SEQNUM=1131 | |
| @@ -0,0 +1,146 @@ | ||
| 1 | +======== | |
| 2 | +dm-zoned | |
| 3 | +======== | |
| 4 | + | |
| 5 | +The dm-zoned device mapper target exposes a zoned block device (ZBC and | |
| 6 | +ZAC compliant devices) as a regular block device without any write | |
| 7 | +pattern constraints. In effect, it implements a drive-managed zoned | |
| 8 | +block device which hides from the user (a file system or an application | |
| 9 | +doing raw block device accesses) the sequential write constraints of | |
| 10 | +host-managed zoned block devices and can mitigate the potential | |
| 11 | +device-side performance degradation due to excessive random writes on | |
| 12 | +host-aware zoned block devices. | |
| 13 | + | |
| 14 | +For a more detailed description of the zoned block device models and | |
| 15 | +their constraints see (for SCSI devices): | |
| 16 | + | |
| 17 | +http://www.t10.org/drafts.htm#ZBC_Family | |
| 18 | + | |
| 19 | +and (for ATA devices): | |
| 20 | + | |
| 21 | +http://www.t13.org/Documents/UploadedDocuments/docs2015/di537r05-Zoned_Device_ATA_Command_Set_ZAC.pdf | |
| 22 | + | |
| 23 | +The dm-zoned implementation is simple and minimizes system overhead (CPU | |
| 24 | +and memory usage as well as storage capacity loss). For a 10TB | |
| 25 | +host-managed disk with 256 MB zones, dm-zoned memory usage per disk | |
| 26 | +instance is at most 4.5 MB and as little as 5 zones will be used | |
| 27 | +internally for storing metadata and performaing reclaim operations. | |
| 28 | + | |
| 29 | +dm-zoned target devices are formatted and checked using the dmzadm | |
| 30 | +utility available at: | |
| 31 | + | |
| 32 | +https://github.com/hgst/dm-zoned-tools | |
| 33 | + | |
| 34 | +Algorithm | |
| 35 | +========= | |
| 36 | + | |
| 37 | +dm-zoned implements an on-disk buffering scheme to handle non-sequential | |
| 38 | +write accesses to the sequential zones of a zoned block device. | |
| 39 | +Conventional zones are used for caching as well as for storing internal | |
| 40 | +metadata. | |
| 41 | + | |
| 42 | +The zones of the device are separated into 2 types: | |
| 43 | + | |
| 44 | +1) Metadata zones: these are conventional zones used to store metadata. | |
| 45 | +Metadata zones are not reported as useable capacity to the user. | |
| 46 | + | |
| 47 | +2) Data zones: all remaining zones, the vast majority of which will be | |
| 48 | +sequential zones used exclusively to store user data. The conventional | |
| 49 | +zones of the device may be used also for buffering user random writes. | |
| 50 | +Data in these zones may be directly mapped to the conventional zone, but | |
| 51 | +later moved to a sequential zone so that the conventional zone can be | |
| 52 | +reused for buffering incoming random writes. | |
| 53 | + | |
| 54 | +dm-zoned exposes a logical device with a sector size of 4096 bytes, | |
| 55 | +irrespective of the physical sector size of the backend zoned block | |
| 56 | +device being used. This allows reducing the amount of metadata needed to | |
| 57 | +manage valid blocks (blocks written). | |
| 58 | + | |
| 59 | +The on-disk metadata format is as follows: | |
| 60 | + | |
| 61 | +1) The first block of the first conventional zone found contains the | |
| 62 | +super block which describes the on disk amount and position of metadata | |
| 63 | +blocks. | |
| 64 | + | |
| 65 | +2) Following the super block, a set of blocks is used to describe the | |
| 66 | +mapping of the logical device blocks. The mapping is done per chunk of | |
| 67 | +blocks, with the chunk size equal to the zoned block device size. The | |
| 68 | +mapping table is indexed by chunk number and each mapping entry | |
| 69 | +indicates the zone number of the device storing the chunk of data. Each | |
| 70 | +mapping entry may also indicate if the zone number of a conventional | |
| 71 | +zone used to buffer random modification to the data zone. | |
| 72 | + | |
| 73 | +3) A set of blocks used to store bitmaps indicating the validity of | |
| 74 | +blocks in the data zones follows the mapping table. A valid block is | |
| 75 | +defined as a block that was written and not discarded. For a buffered | |
| 76 | +data chunk, a block is always valid only in the data zone mapping the | |
| 77 | +chunk or in the buffer zone of the chunk. | |
| 78 | + | |
| 79 | +For a logical chunk mapped to a conventional zone, all write operations | |
| 80 | +are processed by directly writing to the zone. If the mapping zone is a | |
| 81 | +sequential zone, the write operation is processed directly only if the | |
| 82 | +write offset within the logical chunk is equal to the write pointer | |
| 83 | +offset within of the sequential data zone (i.e. the write operation is | |
| 84 | +aligned on the zone write pointer). Otherwise, write operations are | |
| 85 | +processed indirectly using a buffer zone. In that case, an unused | |
| 86 | +conventional zone is allocated and assigned to the chunk being | |
| 87 | +accessed. Writing a block to the buffer zone of a chunk will | |
| 88 | +automatically invalidate the same block in the sequential zone mapping | |
| 89 | +the chunk. If all blocks of the sequential zone become invalid, the zone | |
| 90 | +is freed and the chunk buffer zone becomes the primary zone mapping the | |
| 91 | +chunk, resulting in native random write performance similar to a regular | |
| 92 | +block device. | |
| 93 | + | |
| 94 | +Read operations are processed according to the block validity | |
| 95 | +information provided by the bitmaps. Valid blocks are read either from | |
| 96 | +the sequential zone mapping a chunk, or if the chunk is buffered, from | |
| 97 | +the buffer zone assigned. If the accessed chunk has no mapping, or the | |
| 98 | +accessed blocks are invalid, the read buffer is zeroed and the read | |
| 99 | +operation terminated. | |
| 100 | + | |
| 101 | +After some time, the limited number of convnetional zones available may | |
| 102 | +be exhausted (all used to map chunks or buffer sequential zones) and | |
| 103 | +unaligned writes to unbuffered chunks become impossible. To avoid this | |
| 104 | +situation, a reclaim process regularly scans used conventional zones and | |
| 105 | +tries to reclaim the least recently used zones by copying the valid | |
| 106 | +blocks of the buffer zone to a free sequential zone. Once the copy | |
| 107 | +completes, the chunk mapping is updated to point to the sequential zone | |
| 108 | +and the buffer zone freed for reuse. | |
| 109 | + | |
| 110 | +Metadata Protection | |
| 111 | +=================== | |
| 112 | + | |
| 113 | +To protect metadata against corruption in case of sudden power loss or | |
| 114 | +system crash, 2 sets of metadata zones are used. One set, the primary | |
| 115 | +set, is used as the main metadata region, while the secondary set is | |
| 116 | +used as a staging area. Modified metadata is first written to the | |
| 117 | +secondary set and validated by updating the super block in the secondary | |
| 118 | +set, a generation counter is used to indicate that this set contains the | |
| 119 | +newest metadata. Once this operation completes, in place of metadata | |
| 120 | +block updates can be done in the primary metadata set. This ensures that | |
| 121 | +one of the set is always consistent (all modifications committed or none | |
| 122 | +at all). Flush operations are used as a commit point. Upon reception of | |
| 123 | +a flush request, metadata modification activity is temporarily blocked | |
| 124 | +(for both incoming BIO processing and reclaim process) and all dirty | |
| 125 | +metadata blocks are staged and updated. Normal operation is then | |
| 126 | +resumed. Flushing metadata thus only temporarily delays write and | |
| 127 | +discard requests. Read requests can be processed concurrently while | |
| 128 | +metadata flush is being executed. | |
| 129 | + | |
| 130 | +Usage | |
| 131 | +===== | |
| 132 | + | |
| 133 | +A zoned block device must first be formatted using the dmzadm tool. This | |
| 134 | +will analyze the device zone configuration, determine where to place the | |
| 135 | +metadata sets on the device and initialize the metadata sets. | |
| 136 | + | |
| 137 | +Ex:: | |
| 138 | + | |
| 139 | + dmzadm --format /dev/sdxx | |
| 140 | + | |
| 141 | +For a formatted device, the target can be created normally with the | |
| 142 | +dmsetup utility. The only parameter that dm-zoned requires is the | |
| 143 | +underlying zoned block device name. Ex:: | |
| 144 | + | |
| 145 | + echo "0 `blockdev --getsize ${dev}` zoned ${dev}" | \ | |
| 146 | + dmsetup create dmz-`basename ${dev}` | |
| @@ -0,0 +1,116 @@ | ||
| 1 | +====== | |
| 2 | +dm-era | |
| 3 | +====== | |
| 4 | + | |
| 5 | +Introduction | |
| 6 | +============ | |
| 7 | + | |
| 8 | +dm-era is a target that behaves similar to the linear target. In | |
| 9 | +addition it keeps track of which blocks were written within a user | |
| 10 | +defined period of time called an 'era'. Each era target instance | |
| 11 | +maintains the current era as a monotonically increasing 32-bit | |
| 12 | +counter. | |
| 13 | + | |
| 14 | +Use cases include tracking changed blocks for backup software, and | |
| 15 | +partially invalidating the contents of a cache to restore cache | |
| 16 | +coherency after rolling back a vendor snapshot. | |
| 17 | + | |
| 18 | +Constructor | |
| 19 | +=========== | |
| 20 | + | |
| 21 | +era <metadata dev> <origin dev> <block size> | |
| 22 | + | |
| 23 | + ================ ====================================================== | |
| 24 | + metadata dev fast device holding the persistent metadata | |
| 25 | + origin dev device holding data blocks that may change | |
| 26 | + block size block size of origin data device, granularity that is | |
| 27 | + tracked by the target | |
| 28 | + ================ ====================================================== | |
| 29 | + | |
| 30 | +Messages | |
| 31 | +======== | |
| 32 | + | |
| 33 | +None of the dm messages take any arguments. | |
| 34 | + | |
| 35 | +checkpoint | |
| 36 | +---------- | |
| 37 | + | |
| 38 | +Possibly move to a new era. You shouldn't assume the era has | |
| 39 | +incremented. After sending this message, you should check the | |
| 40 | +current era via the status line. | |
| 41 | + | |
| 42 | +take_metadata_snap | |
| 43 | +------------------ | |
| 44 | + | |
| 45 | +Create a clone of the metadata, to allow a userland process to read it. | |
| 46 | + | |
| 47 | +drop_metadata_snap | |
| 48 | +------------------ | |
| 49 | + | |
| 50 | +Drop the metadata snapshot. | |
| 51 | + | |
| 52 | +Status | |
| 53 | +====== | |
| 54 | + | |
| 55 | +<metadata block size> <#used metadata blocks>/<#total metadata blocks> | |
| 56 | +<current era> <held metadata root | '-'> | |
| 57 | + | |
| 58 | +========================= ============================================== | |
| 59 | +metadata block size Fixed block size for each metadata block in | |
| 60 | + sectors | |
| 61 | +#used metadata blocks Number of metadata blocks used | |
| 62 | +#total metadata blocks Total number of metadata blocks | |
| 63 | +current era The current era | |
| 64 | +held metadata root The location, in blocks, of the metadata root | |
| 65 | + that has been 'held' for userspace read | |
| 66 | + access. '-' indicates there is no held root | |
| 67 | +========================= ============================================== | |
| 68 | + | |
| 69 | +Detailed use case | |
| 70 | +================= | |
| 71 | + | |
| 72 | +The scenario of invalidating a cache when rolling back a vendor | |
| 73 | +snapshot was the primary use case when developing this target: | |
| 74 | + | |
| 75 | +Taking a vendor snapshot | |
| 76 | +------------------------ | |
| 77 | + | |
| 78 | +- Send a checkpoint message to the era target | |
| 79 | +- Make a note of the current era in its status line | |
| 80 | +- Take vendor snapshot (the era and snapshot should be forever | |
| 81 | + associated now). | |
| 82 | + | |
| 83 | +Rolling back to an vendor snapshot | |
| 84 | +---------------------------------- | |
| 85 | + | |
| 86 | +- Cache enters passthrough mode (see: dm-cache's docs in cache.txt) | |
| 87 | +- Rollback vendor storage | |
| 88 | +- Take metadata snapshot | |
| 89 | +- Ascertain which blocks have been written since the snapshot was taken | |
| 90 | + by checking each block's era | |
| 91 | +- Invalidate those blocks in the caching software | |
| 92 | +- Cache returns to writeback/writethrough mode | |
| 93 | + | |
| 94 | +Memory usage | |
| 95 | +============ | |
| 96 | + | |
| 97 | +The target uses a bitset to record writes in the current era. It also | |
| 98 | +has a spare bitset ready for switching over to a new era. Other than | |
| 99 | +that it uses a few 4k blocks for updating metadata:: | |
| 100 | + | |
| 101 | + (4 * nr_blocks) bytes + buffers | |
| 102 | + | |
| 103 | +Resilience | |
| 104 | +========== | |
| 105 | + | |
| 106 | +Metadata is updated on disk before a write to a previously unwritten | |
| 107 | +block is performed. As such dm-era should not be effected by a hard | |
| 108 | +crash such as power failure. | |
| 109 | + | |
| 110 | +Userland tools | |
| 111 | +============== | |
| 112 | + | |
| 113 | +Userland tools are found in the increasingly poorly named | |
| 114 | +thin-provisioning-tools project: | |
| 115 | + | |
| 116 | + https://github.com/jthornber/thin-provisioning-tools | |
| @@ -0,0 +1,42 @@ | ||
| 1 | +============= | |
| 2 | +Device Mapper | |
| 3 | +============= | |
| 4 | + | |
| 5 | +.. toctree:: | |
| 6 | + :maxdepth: 1 | |
| 7 | + | |
| 8 | + cache-policies | |
| 9 | + cache | |
| 10 | + delay | |
| 11 | + dm-crypt | |
| 12 | + dm-flakey | |
| 13 | + dm-init | |
| 14 | + dm-integrity | |
| 15 | + dm-io | |
| 16 | + dm-log | |
| 17 | + dm-queue-length | |
| 18 | + dm-raid | |
| 19 | + dm-service-time | |
| 20 | + dm-uevent | |
| 21 | + dm-zoned | |
| 22 | + era | |
| 23 | + kcopyd | |
| 24 | + linear | |
| 25 | + log-writes | |
| 26 | + persistent-data | |
| 27 | + snapshot | |
| 28 | + statistics | |
| 29 | + striped | |
| 30 | + switch | |
| 31 | + thin-provisioning | |
| 32 | + unstriped | |
| 33 | + verity | |
| 34 | + writecache | |
| 35 | + zero | |
| 36 | + | |
| 37 | +.. only:: subproject and html | |
| 38 | + | |
| 39 | + Indices | |
| 40 | + ======= | |
| 41 | + | |
| 42 | + * :ref:`genindex` | |
| @@ -0,0 +1,47 @@ | ||
| 1 | +====== | |
| 2 | +kcopyd | |
| 3 | +====== | |
| 4 | + | |
| 5 | +Kcopyd provides the ability to copy a range of sectors from one block-device | |
| 6 | +to one or more other block-devices, with an asynchronous completion | |
| 7 | +notification. It is used by dm-snapshot and dm-mirror. | |
| 8 | + | |
| 9 | +Users of kcopyd must first create a client and indicate how many memory pages | |
| 10 | +to set aside for their copy jobs. This is done with a call to | |
| 11 | +kcopyd_client_create():: | |
| 12 | + | |
| 13 | + int kcopyd_client_create(unsigned int num_pages, | |
| 14 | + struct kcopyd_client **result); | |
| 15 | + | |
| 16 | +To start a copy job, the user must set up io_region structures to describe | |
| 17 | +the source and destinations of the copy. Each io_region indicates a | |
| 18 | +block-device along with the starting sector and size of the region. The source | |
| 19 | +of the copy is given as one io_region structure, and the destinations of the | |
| 20 | +copy are given as an array of io_region structures:: | |
| 21 | + | |
| 22 | + struct io_region { | |
| 23 | + struct block_device *bdev; | |
| 24 | + sector_t sector; | |
| 25 | + sector_t count; | |
| 26 | + }; | |
| 27 | + | |
| 28 | +To start the copy, the user calls kcopyd_copy(), passing in the client | |
| 29 | +pointer, pointers to the source and destination io_regions, the name of a | |
| 30 | +completion callback routine, and a pointer to some context data for the copy:: | |
| 31 | + | |
| 32 | + int kcopyd_copy(struct kcopyd_client *kc, struct io_region *from, | |
| 33 | + unsigned int num_dests, struct io_region *dests, | |
| 34 | + unsigned int flags, kcopyd_notify_fn fn, void *context); | |
| 35 | + | |
| 36 | + typedef void (*kcopyd_notify_fn)(int read_err, unsigned int write_err, | |
| 37 | + void *context); | |
| 38 | + | |
| 39 | +When the copy completes, kcopyd will call the user's completion routine, | |
| 40 | +passing back the user's context pointer. It will also indicate if a read or | |
| 41 | +write error occurred during the copy. | |
| 42 | + | |
| 43 | +When a user is done with all their copy jobs, they should call | |
| 44 | +kcopyd_client_destroy() to delete the kcopyd client, which will release the | |
| 45 | +associated memory pages:: | |
| 46 | + | |
| 47 | + void kcopyd_client_destroy(struct kcopyd_client *kc); | |
| @@ -0,0 +1,63 @@ | ||
| 1 | +========= | |
| 2 | +dm-linear | |
| 3 | +========= | |
| 4 | + | |
| 5 | +Device-Mapper's "linear" target maps a linear range of the Device-Mapper | |
| 6 | +device onto a linear range of another device. This is the basic building | |
| 7 | +block of logical volume managers. | |
| 8 | + | |
| 9 | +Parameters: <dev path> <offset> | |
| 10 | + <dev path>: | |
| 11 | + Full pathname to the underlying block-device, or a | |
| 12 | + "major:minor" device-number. | |
| 13 | + <offset>: | |
| 14 | + Starting sector within the device. | |
| 15 | + | |
| 16 | + | |
| 17 | +Example scripts | |
| 18 | +=============== | |
| 19 | + | |
| 20 | +:: | |
| 21 | + | |
| 22 | + #!/bin/sh | |
| 23 | + # Create an identity mapping for a device | |
| 24 | + echo "0 `blockdev --getsz $1` linear $1 0" | dmsetup create identity | |
| 25 | + | |
| 26 | +:: | |
| 27 | + | |
| 28 | + #!/bin/sh | |
| 29 | + # Join 2 devices together | |
| 30 | + size1=`blockdev --getsz $1` | |
| 31 | + size2=`blockdev --getsz $2` | |
| 32 | + echo "0 $size1 linear $1 0 | |
| 33 | + $size1 $size2 linear $2 0" | dmsetup create joined | |
| 34 | + | |
| 35 | +:: | |
| 36 | + | |
| 37 | + #!/usr/bin/perl -w | |
| 38 | + # Split a device into 4M chunks and then join them together in reverse order. | |
| 39 | + | |
| 40 | + my $name = "reverse"; | |
| 41 | + my $extent_size = 4 * 1024 * 2; | |
| 42 | + my $dev = $ARGV[0]; | |
| 43 | + my $table = ""; | |
| 44 | + my $count = 0; | |
| 45 | + | |
| 46 | + if (!defined($dev)) { | |
| 47 | + die("Please specify a device.\n"); | |
| 48 | + } | |
| 49 | + | |
| 50 | + my $dev_size = `blockdev --getsz $dev`; | |
| 51 | + my $extents = int($dev_size / $extent_size) - | |
| 52 | + (($dev_size % $extent_size) ? 1 : 0); | |
| 53 | + | |
| 54 | + while ($extents > 0) { | |
| 55 | + my $this_start = $count * $extent_size; | |
| 56 | + $extents--; | |
| 57 | + $count++; | |
| 58 | + my $this_offset = $extents * $extent_size; | |
| 59 | + | |
| 60 | + $table .= "$this_start $extent_size linear $dev $this_offset\n"; | |
| 61 | + } | |
| 62 | + | |
| 63 | + `echo \"$table\" | dmsetup create $name`; | |
| @@ -0,0 +1,145 @@ | ||
| 1 | +============= | |
| 2 | +dm-log-writes | |
| 3 | +============= | |
| 4 | + | |
| 5 | +This target takes 2 devices, one to pass all IO to normally, and one to log all | |
| 6 | +of the write operations to. This is intended for file system developers wishing | |
| 7 | +to verify the integrity of metadata or data as the file system is written to. | |
| 8 | +There is a log_write_entry written for every WRITE request and the target is | |
| 9 | +able to take arbitrary data from userspace to insert into the log. The data | |
| 10 | +that is in the WRITE requests is copied into the log to make the replay happen | |
| 11 | +exactly as it happened originally. | |
| 12 | + | |
| 13 | +Log Ordering | |
| 14 | +============ | |
| 15 | + | |
| 16 | +We log things in order of completion once we are sure the write is no longer in | |
| 17 | +cache. This means that normal WRITE requests are not actually logged until the | |
| 18 | +next REQ_PREFLUSH request. This is to make it easier for userspace to replay | |
| 19 | +the log in a way that correlates to what is on disk and not what is in cache, | |
| 20 | +to make it easier to detect improper waiting/flushing. | |
| 21 | + | |
| 22 | +This works by attaching all WRITE requests to a list once the write completes. | |
| 23 | +Once we see a REQ_PREFLUSH request we splice this list onto the request and once | |
| 24 | +the FLUSH request completes we log all of the WRITEs and then the FLUSH. Only | |
| 25 | +completed WRITEs, at the time the REQ_PREFLUSH is issued, are added in order to | |
| 26 | +simulate the worst case scenario with regard to power failures. Consider the | |
| 27 | +following example (W means write, C means complete): | |
| 28 | + | |
| 29 | + W1,W2,W3,C3,C2,Wflush,C1,Cflush | |
| 30 | + | |
| 31 | +The log would show the following: | |
| 32 | + | |
| 33 | + W3,W2,flush,W1.... | |
| 34 | + | |
| 35 | +Again this is to simulate what is actually on disk, this allows us to detect | |
| 36 | +cases where a power failure at a particular point in time would create an | |
| 37 | +inconsistent file system. | |
| 38 | + | |
| 39 | +Any REQ_FUA requests bypass this flushing mechanism and are logged as soon as | |
| 40 | +they complete as those requests will obviously bypass the device cache. | |
| 41 | + | |
| 42 | +Any REQ_OP_DISCARD requests are treated like WRITE requests. Otherwise we would | |
| 43 | +have all the DISCARD requests, and then the WRITE requests and then the FLUSH | |
| 44 | +request. Consider the following example: | |
| 45 | + | |
| 46 | + WRITE block 1, DISCARD block 1, FLUSH | |
| 47 | + | |
| 48 | +If we logged DISCARD when it completed, the replay would look like this: | |
| 49 | + | |
| 50 | + DISCARD 1, WRITE 1, FLUSH | |
| 51 | + | |
| 52 | +which isn't quite what happened and wouldn't be caught during the log replay. | |
| 53 | + | |
| 54 | +Target interface | |
| 55 | +================ | |
| 56 | + | |
| 57 | +i) Constructor | |
| 58 | + | |
| 59 | + log-writes <dev_path> <log_dev_path> | |
| 60 | + | |
| 61 | + ============= ============================================== | |
| 62 | + dev_path Device that all of the IO will go to normally. | |
| 63 | + log_dev_path Device where the log entries are written to. | |
| 64 | + ============= ============================================== | |
| 65 | + | |
| 66 | +ii) Status | |
| 67 | + | |
| 68 | + <#logged entries> <highest allocated sector> | |
| 69 | + | |
| 70 | + =========================== ======================== | |
| 71 | + #logged entries Number of logged entries | |
| 72 | + highest allocated sector Highest allocated sector | |
| 73 | + =========================== ======================== | |
| 74 | + | |
| 75 | +iii) Messages | |
| 76 | + | |
| 77 | + mark <description> | |
| 78 | + | |
| 79 | + You can use a dmsetup message to set an arbitrary mark in a log. | |
| 80 | + For example say you want to fsck a file system after every | |
| 81 | + write, but first you need to replay up to the mkfs to make sure | |
| 82 | + we're fsck'ing something reasonable, you would do something like | |
| 83 | + this:: | |
| 84 | + | |
| 85 | + mkfs.btrfs -f /dev/mapper/log | |
| 86 | + dmsetup message log 0 mark mkfs | |
| 87 | + <run test> | |
| 88 | + | |
| 89 | + This would allow you to replay the log up to the mkfs mark and | |
| 90 | + then replay from that point on doing the fsck check in the | |
| 91 | + interval that you want. | |
| 92 | + | |
| 93 | + Every log has a mark at the end labeled "dm-log-writes-end". | |
| 94 | + | |
| 95 | +Userspace component | |
| 96 | +=================== | |
| 97 | + | |
| 98 | +There is a userspace tool that will replay the log for you in various ways. | |
| 99 | +It can be found here: https://github.com/josefbacik/log-writes | |
| 100 | + | |
| 101 | +Example usage | |
| 102 | +============= | |
| 103 | + | |
| 104 | +Say you want to test fsync on your file system. You would do something like | |
| 105 | +this:: | |
| 106 | + | |
| 107 | + TABLE="0 $(blockdev --getsz /dev/sdb) log-writes /dev/sdb /dev/sdc" | |
| 108 | + dmsetup create log --table "$TABLE" | |
| 109 | + mkfs.btrfs -f /dev/mapper/log | |
| 110 | + dmsetup message log 0 mark mkfs | |
| 111 | + | |
| 112 | + mount /dev/mapper/log /mnt/btrfs-test | |
| 113 | + <some test that does fsync at the end> | |
| 114 | + dmsetup message log 0 mark fsync | |
| 115 | + md5sum /mnt/btrfs-test/foo | |
| 116 | + umount /mnt/btrfs-test | |
| 117 | + | |
| 118 | + dmsetup remove log | |
| 119 | + replay-log --log /dev/sdc --replay /dev/sdb --end-mark fsync | |
| 120 | + mount /dev/sdb /mnt/btrfs-test | |
| 121 | + md5sum /mnt/btrfs-test/foo | |
| 122 | + <verify md5sum's are correct> | |
| 123 | + | |
| 124 | + Another option is to do a complicated file system operation and verify the file | |
| 125 | + system is consistent during the entire operation. You could do this with: | |
| 126 | + | |
| 127 | + TABLE="0 $(blockdev --getsz /dev/sdb) log-writes /dev/sdb /dev/sdc" | |
| 128 | + dmsetup create log --table "$TABLE" | |
| 129 | + mkfs.btrfs -f /dev/mapper/log | |
| 130 | + dmsetup message log 0 mark mkfs | |
| 131 | + | |
| 132 | + mount /dev/mapper/log /mnt/btrfs-test | |
| 133 | + <fsstress to dirty the fs> | |
| 134 | + btrfs filesystem balance /mnt/btrfs-test | |
| 135 | + umount /mnt/btrfs-test | |
| 136 | + dmsetup remove log | |
| 137 | + | |
| 138 | + replay-log --log /dev/sdc --replay /dev/sdb --end-mark mkfs | |
| 139 | + btrfsck /dev/sdb | |
| 140 | + replay-log --log /dev/sdc --replay /dev/sdb --start-mark mkfs \ | |
| 141 | + --fsck "btrfsck /dev/sdb" --check fua | |
| 142 | + | |
| 143 | +And that will replay the log until it sees a FUA request, run the fsck command | |
| 144 | +and if the fsck passes it will replay to the next FUA, until it is completed or | |
| 145 | +the fsck command exists abnormally. | |
| @@ -0,0 +1,88 @@ | ||
| 1 | +=============== | |
| 2 | +Persistent data | |
| 3 | +=============== | |
| 4 | + | |
| 5 | +Introduction | |
| 6 | +============ | |
| 7 | + | |
| 8 | +The more-sophisticated device-mapper targets require complex metadata | |
| 9 | +that is managed in kernel. In late 2010 we were seeing that various | |
| 10 | +different targets were rolling their own data structures, for example: | |
| 11 | + | |
| 12 | +- Mikulas Patocka's multisnap implementation | |
| 13 | +- Heinz Mauelshagen's thin provisioning target | |
| 14 | +- Another btree-based caching target posted to dm-devel | |
| 15 | +- Another multi-snapshot target based on a design of Daniel Phillips | |
| 16 | + | |
| 17 | +Maintaining these data structures takes a lot of work, so if possible | |
| 18 | +we'd like to reduce the number. | |
| 19 | + | |
| 20 | +The persistent-data library is an attempt to provide a re-usable | |
| 21 | +framework for people who want to store metadata in device-mapper | |
| 22 | +targets. It's currently used by the thin-provisioning target and an | |
| 23 | +upcoming hierarchical storage target. | |
| 24 | + | |
| 25 | +Overview | |
| 26 | +======== | |
| 27 | + | |
| 28 | +The main documentation is in the header files which can all be found | |
| 29 | +under drivers/md/persistent-data. | |
| 30 | + | |
| 31 | +The block manager | |
| 32 | +----------------- | |
| 33 | + | |
| 34 | +dm-block-manager.[hc] | |
| 35 | + | |
| 36 | +This provides access to the data on disk in fixed sized-blocks. There | |
| 37 | +is a read/write locking interface to prevent concurrent accesses, and | |
| 38 | +keep data that is being used in the cache. | |
| 39 | + | |
| 40 | +Clients of persistent-data are unlikely to use this directly. | |
| 41 | + | |
| 42 | +The transaction manager | |
| 43 | +----------------------- | |
| 44 | + | |
| 45 | +dm-transaction-manager.[hc] | |
| 46 | + | |
| 47 | +This restricts access to blocks and enforces copy-on-write semantics. | |
| 48 | +The only way you can get hold of a writable block through the | |
| 49 | +transaction manager is by shadowing an existing block (ie. doing | |
| 50 | +copy-on-write) or allocating a fresh one. Shadowing is elided within | |
| 51 | +the same transaction so performance is reasonable. The commit method | |
| 52 | +ensures that all data is flushed before it writes the superblock. | |
| 53 | +On power failure your metadata will be as it was when last committed. | |
| 54 | + | |
| 55 | +The Space Maps | |
| 56 | +-------------- | |
| 57 | + | |
| 58 | +dm-space-map.h | |
| 59 | +dm-space-map-metadata.[hc] | |
| 60 | +dm-space-map-disk.[hc] | |
| 61 | + | |
| 62 | +On-disk data structures that keep track of reference counts of blocks. | |
| 63 | +Also acts as the allocator of new blocks. Currently two | |
| 64 | +implementations: a simpler one for managing blocks on a different | |
| 65 | +device (eg. thinly-provisioned data blocks); and one for managing | |
| 66 | +the metadata space. The latter is complicated by the need to store | |
| 67 | +its own data within the space it's managing. | |
| 68 | + | |
| 69 | +The data structures | |
| 70 | +------------------- | |
| 71 | + | |
| 72 | +dm-btree.[hc] | |
| 73 | +dm-btree-remove.c | |
| 74 | +dm-btree-spine.c | |
| 75 | +dm-btree-internal.h | |
| 76 | + | |
| 77 | +Currently there is only one data structure, a hierarchical btree. | |
| 78 | +There are plans to add more. For example, something with an | |
| 79 | +array-like interface would see a lot of use. | |
| 80 | + | |
| 81 | +The btree is 'hierarchical' in that you can define it to be composed | |
| 82 | +of nested btrees, and take multiple keys. For example, the | |
| 83 | +thin-provisioning target uses a btree with two levels of nesting. | |
| 84 | +The first maps a device id to a mapping tree, and that in turn maps a | |
| 85 | +virtual block to a physical block. | |
| 86 | + | |
| 87 | +Values stored in the btrees can have arbitrary size. Keys are always | |
| 88 | +64bits, although nesting allows you to use multiple keys. | |
| @@ -0,0 +1,196 @@ | ||
| 1 | +============================== | |
| 2 | +Device-mapper snapshot support | |
| 3 | +============================== | |
| 4 | + | |
| 5 | +Device-mapper allows you, without massive data copying: | |
| 6 | + | |
| 7 | +- To create snapshots of any block device i.e. mountable, saved states of | |
| 8 | + the block device which are also writable without interfering with the | |
| 9 | + original content; | |
| 10 | +- To create device "forks", i.e. multiple different versions of the | |
| 11 | + same data stream. | |
| 12 | +- To merge a snapshot of a block device back into the snapshot's origin | |
| 13 | + device. | |
| 14 | + | |
| 15 | +In the first two cases, dm copies only the chunks of data that get | |
| 16 | +changed and uses a separate copy-on-write (COW) block device for | |
| 17 | +storage. | |
| 18 | + | |
| 19 | +For snapshot merge the contents of the COW storage are merged back into | |
| 20 | +the origin device. | |
| 21 | + | |
| 22 | + | |
| 23 | +There are three dm targets available: | |
| 24 | +snapshot, snapshot-origin, and snapshot-merge. | |
| 25 | + | |
| 26 | +- snapshot-origin <origin> | |
| 27 | + | |
| 28 | +which will normally have one or more snapshots based on it. | |
| 29 | +Reads will be mapped directly to the backing device. For each write, the | |
| 30 | +original data will be saved in the <COW device> of each snapshot to keep | |
| 31 | +its visible content unchanged, at least until the <COW device> fills up. | |
| 32 | + | |
| 33 | + | |
| 34 | +- snapshot <origin> <COW device> <persistent?> <chunksize> | |
| 35 | + [<# feature args> [<arg>]*] | |
| 36 | + | |
| 37 | +A snapshot of the <origin> block device is created. Changed chunks of | |
| 38 | +<chunksize> sectors will be stored on the <COW device>. Writes will | |
| 39 | +only go to the <COW device>. Reads will come from the <COW device> or | |
| 40 | +from <origin> for unchanged data. <COW device> will often be | |
| 41 | +smaller than the origin and if it fills up the snapshot will become | |
| 42 | +useless and be disabled, returning errors. So it is important to monitor | |
| 43 | +the amount of free space and expand the <COW device> before it fills up. | |
| 44 | + | |
| 45 | +<persistent?> is P (Persistent) or N (Not persistent - will not survive | |
| 46 | +after reboot). O (Overflow) can be added as a persistent store option | |
| 47 | +to allow userspace to advertise its support for seeing "Overflow" in the | |
| 48 | +snapshot status. So supported store types are "P", "PO" and "N". | |
| 49 | + | |
| 50 | +The difference between persistent and transient is with transient | |
| 51 | +snapshots less metadata must be saved on disk - they can be kept in | |
| 52 | +memory by the kernel. | |
| 53 | + | |
| 54 | +When loading or unloading the snapshot target, the corresponding | |
| 55 | +snapshot-origin or snapshot-merge target must be suspended. A failure to | |
| 56 | +suspend the origin target could result in data corruption. | |
| 57 | + | |
| 58 | +Optional features: | |
| 59 | + | |
| 60 | + discard_zeroes_cow - a discard issued to the snapshot device that | |
| 61 | + maps to entire chunks to will zero the corresponding exception(s) in | |
| 62 | + the snapshot's exception store. | |
| 63 | + | |
| 64 | + discard_passdown_origin - a discard to the snapshot device is passed | |
| 65 | + down to the snapshot-origin's underlying device. This doesn't cause | |
| 66 | + copy-out to the snapshot exception store because the snapshot-origin | |
| 67 | + target is bypassed. | |
| 68 | + | |
| 69 | + The discard_passdown_origin feature depends on the discard_zeroes_cow | |
| 70 | + feature being enabled. | |
| 71 | + | |
| 72 | + | |
| 73 | +- snapshot-merge <origin> <COW device> <persistent> <chunksize> | |
| 74 | + [<# feature args> [<arg>]*] | |
| 75 | + | |
| 76 | +takes the same table arguments as the snapshot target except it only | |
| 77 | +works with persistent snapshots. This target assumes the role of the | |
| 78 | +"snapshot-origin" target and must not be loaded if the "snapshot-origin" | |
| 79 | +is still present for <origin>. | |
| 80 | + | |
| 81 | +Creates a merging snapshot that takes control of the changed chunks | |
| 82 | +stored in the <COW device> of an existing snapshot, through a handover | |
| 83 | +procedure, and merges these chunks back into the <origin>. Once merging | |
| 84 | +has started (in the background) the <origin> may be opened and the merge | |
| 85 | +will continue while I/O is flowing to it. Changes to the <origin> are | |
| 86 | +deferred until the merging snapshot's corresponding chunk(s) have been | |
| 87 | +merged. Once merging has started the snapshot device, associated with | |
| 88 | +the "snapshot" target, will return -EIO when accessed. | |
| 89 | + | |
| 90 | + | |
| 91 | +How snapshot is used by LVM2 | |
| 92 | +============================ | |
| 93 | +When you create the first LVM2 snapshot of a volume, four dm devices are used: | |
| 94 | + | |
| 95 | +1) a device containing the original mapping table of the source volume; | |
| 96 | +2) a device used as the <COW device>; | |
| 97 | +3) a "snapshot" device, combining #1 and #2, which is the visible snapshot | |
| 98 | + volume; | |
| 99 | +4) the "original" volume (which uses the device number used by the original | |
| 100 | + source volume), whose table is replaced by a "snapshot-origin" mapping | |
| 101 | + from device #1. | |
| 102 | + | |
| 103 | +A fixed naming scheme is used, so with the following commands:: | |
| 104 | + | |
| 105 | + lvcreate -L 1G -n base volumeGroup | |
| 106 | + lvcreate -L 100M --snapshot -n snap volumeGroup/base | |
| 107 | + | |
| 108 | +we'll have this situation (with volumes in above order):: | |
| 109 | + | |
| 110 | + # dmsetup table|grep volumeGroup | |
| 111 | + | |
| 112 | + volumeGroup-base-real: 0 2097152 linear 8:19 384 | |
| 113 | + volumeGroup-snap-cow: 0 204800 linear 8:19 2097536 | |
| 114 | + volumeGroup-snap: 0 2097152 snapshot 254:11 254:12 P 16 | |
| 115 | + volumeGroup-base: 0 2097152 snapshot-origin 254:11 | |
| 116 | + | |
| 117 | + # ls -lL /dev/mapper/volumeGroup-* | |
| 118 | + brw------- 1 root root 254, 11 29 ago 18:15 /dev/mapper/volumeGroup-base-real | |
| 119 | + brw------- 1 root root 254, 12 29 ago 18:15 /dev/mapper/volumeGroup-snap-cow | |
| 120 | + brw------- 1 root root 254, 13 29 ago 18:15 /dev/mapper/volumeGroup-snap | |
| 121 | + brw------- 1 root root 254, 10 29 ago 18:14 /dev/mapper/volumeGroup-base | |
| 122 | + | |
| 123 | + | |
| 124 | +How snapshot-merge is used by LVM2 | |
| 125 | +================================== | |
| 126 | +A merging snapshot assumes the role of the "snapshot-origin" while | |
| 127 | +merging. As such the "snapshot-origin" is replaced with | |
| 128 | +"snapshot-merge". The "-real" device is not changed and the "-cow" | |
| 129 | +device is renamed to <origin name>-cow to aid LVM2's cleanup of the | |
| 130 | +merging snapshot after it completes. The "snapshot" that hands over its | |
| 131 | +COW device to the "snapshot-merge" is deactivated (unless using lvchange | |
| 132 | +--refresh); but if it is left active it will simply return I/O errors. | |
| 133 | + | |
| 134 | +A snapshot will merge into its origin with the following command:: | |
| 135 | + | |
| 136 | + lvconvert --merge volumeGroup/snap | |
| 137 | + | |
| 138 | +we'll now have this situation:: | |
| 139 | + | |
| 140 | + # dmsetup table|grep volumeGroup | |
| 141 | + | |
| 142 | + volumeGroup-base-real: 0 2097152 linear 8:19 384 | |
| 143 | + volumeGroup-base-cow: 0 204800 linear 8:19 2097536 | |
| 144 | + volumeGroup-base: 0 2097152 snapshot-merge 254:11 254:12 P 16 | |
| 145 | + | |
| 146 | + # ls -lL /dev/mapper/volumeGroup-* | |
| 147 | + brw------- 1 root root 254, 11 29 ago 18:15 /dev/mapper/volumeGroup-base-real | |
| 148 | + brw------- 1 root root 254, 12 29 ago 18:16 /dev/mapper/volumeGroup-base-cow | |
| 149 | + brw------- 1 root root 254, 10 29 ago 18:16 /dev/mapper/volumeGroup-base | |
| 150 | + | |
| 151 | + | |
| 152 | +How to determine when a merging is complete | |
| 153 | +=========================================== | |
| 154 | +The snapshot-merge and snapshot status lines end with: | |
| 155 | + | |
| 156 | + <sectors_allocated>/<total_sectors> <metadata_sectors> | |
| 157 | + | |
| 158 | +Both <sectors_allocated> and <total_sectors> include both data and metadata. | |
| 159 | +During merging, the number of sectors allocated gets smaller and | |
| 160 | +smaller. Merging has finished when the number of sectors holding data | |
| 161 | +is zero, in other words <sectors_allocated> == <metadata_sectors>. | |
| 162 | + | |
| 163 | +Here is a practical example (using a hybrid of lvm and dmsetup commands):: | |
| 164 | + | |
| 165 | + # lvs | |
| 166 | + LV VG Attr LSize Origin Snap% Move Log Copy% Convert | |
| 167 | + base volumeGroup owi-a- 4.00g | |
| 168 | + snap volumeGroup swi-a- 1.00g base 18.97 | |
| 169 | + | |
| 170 | + # dmsetup status volumeGroup-snap | |
| 171 | + 0 8388608 snapshot 397896/2097152 1560 | |
| 172 | + ^^^^ metadata sectors | |
| 173 | + | |
| 174 | + # lvconvert --merge -b volumeGroup/snap | |
| 175 | + Merging of volume snap started. | |
| 176 | + | |
| 177 | + # lvs volumeGroup/snap | |
| 178 | + LV VG Attr LSize Origin Snap% Move Log Copy% Convert | |
| 179 | + base volumeGroup Owi-a- 4.00g 17.23 | |
| 180 | + | |
| 181 | + # dmsetup status volumeGroup-base | |
| 182 | + 0 8388608 snapshot-merge 281688/2097152 1104 | |
| 183 | + | |
| 184 | + # dmsetup status volumeGroup-base | |
| 185 | + 0 8388608 snapshot-merge 180480/2097152 712 | |
| 186 | + | |
| 187 | + # dmsetup status volumeGroup-base | |
| 188 | + 0 8388608 snapshot-merge 16/2097152 16 | |
| 189 | + | |
| 190 | +Merging has finished. | |
| 191 | + | |
| 192 | +:: | |
| 193 | + | |
| 194 | + # lvs | |
| 195 | + LV VG Attr LSize Origin Snap% Move Log Copy% Convert | |
| 196 | + base volumeGroup owi-a- 4.00g | |
| @@ -0,0 +1,225 @@ | ||
| 1 | +============= | |
| 2 | +DM statistics | |
| 3 | +============= | |
| 4 | + | |
| 5 | +Device Mapper supports the collection of I/O statistics on user-defined | |
| 6 | +regions of a DM device. If no regions are defined no statistics are | |
| 7 | +collected so there isn't any performance impact. Only bio-based DM | |
| 8 | +devices are currently supported. | |
| 9 | + | |
| 10 | +Each user-defined region specifies a starting sector, length and step. | |
| 11 | +Individual statistics will be collected for each step-sized area within | |
| 12 | +the range specified. | |
| 13 | + | |
| 14 | +The I/O statistics counters for each step-sized area of a region are | |
| 15 | +in the same format as `/sys/block/*/stat` or `/proc/diskstats` (see: | |
| 16 | +Documentation/admin-guide/iostats.rst). But two extra counters (12 and 13) are | |
| 17 | +provided: total time spent reading and writing. When the histogram | |
| 18 | +argument is used, the 14th parameter is reported that represents the | |
| 19 | +histogram of latencies. All these counters may be accessed by sending | |
| 20 | +the @stats_print message to the appropriate DM device via dmsetup. | |
| 21 | + | |
| 22 | +The reported times are in milliseconds and the granularity depends on | |
| 23 | +the kernel ticks. When the option precise_timestamps is used, the | |
| 24 | +reported times are in nanoseconds. | |
| 25 | + | |
| 26 | +Each region has a corresponding unique identifier, which we call a | |
| 27 | +region_id, that is assigned when the region is created. The region_id | |
| 28 | +must be supplied when querying statistics about the region, deleting the | |
| 29 | +region, etc. Unique region_ids enable multiple userspace programs to | |
| 30 | +request and process statistics for the same DM device without stepping | |
| 31 | +on each other's data. | |
| 32 | + | |
| 33 | +The creation of DM statistics will allocate memory via kmalloc or | |
| 34 | +fallback to using vmalloc space. At most, 1/4 of the overall system | |
| 35 | +memory may be allocated by DM statistics. The admin can see how much | |
| 36 | +memory is used by reading: | |
| 37 | + | |
| 38 | + /sys/module/dm_mod/parameters/stats_current_allocated_bytes | |
| 39 | + | |
| 40 | +Messages | |
| 41 | +======== | |
| 42 | + | |
| 43 | + @stats_create <range> <step> [<number_of_optional_arguments> <optional_arguments>...] [<program_id> [<aux_data>]] | |
| 44 | + Create a new region and return the region_id. | |
| 45 | + | |
| 46 | + <range> | |
| 47 | + "-" | |
| 48 | + whole device | |
| 49 | + "<start_sector>+<length>" | |
| 50 | + a range of <length> 512-byte sectors | |
| 51 | + starting with <start_sector>. | |
| 52 | + | |
| 53 | + <step> | |
| 54 | + "<area_size>" | |
| 55 | + the range is subdivided into areas each containing | |
| 56 | + <area_size> sectors. | |
| 57 | + "/<number_of_areas>" | |
| 58 | + the range is subdivided into the specified | |
| 59 | + number of areas. | |
| 60 | + | |
| 61 | + <number_of_optional_arguments> | |
| 62 | + The number of optional arguments | |
| 63 | + | |
| 64 | + <optional_arguments> | |
| 65 | + The following optional arguments are supported: | |
| 66 | + | |
| 67 | + precise_timestamps | |
| 68 | + use precise timer with nanosecond resolution | |
| 69 | + instead of the "jiffies" variable. When this argument is | |
| 70 | + used, the resulting times are in nanoseconds instead of | |
| 71 | + milliseconds. Precise timestamps are a little bit slower | |
| 72 | + to obtain than jiffies-based timestamps. | |
| 73 | + histogram:n1,n2,n3,n4,... | |
| 74 | + collect histogram of latencies. The | |
| 75 | + numbers n1, n2, etc are times that represent the boundaries | |
| 76 | + of the histogram. If precise_timestamps is not used, the | |
| 77 | + times are in milliseconds, otherwise they are in | |
| 78 | + nanoseconds. For each range, the kernel will report the | |
| 79 | + number of requests that completed within this range. For | |
| 80 | + example, if we use "histogram:10,20,30", the kernel will | |
| 81 | + report four numbers a:b:c:d. a is the number of requests | |
| 82 | + that took 0-10 ms to complete, b is the number of requests | |
| 83 | + that took 10-20 ms to complete, c is the number of requests | |
| 84 | + that took 20-30 ms to complete and d is the number of | |
| 85 | + requests that took more than 30 ms to complete. | |
| 86 | + | |
| 87 | + <program_id> | |
| 88 | + An optional parameter. A name that uniquely identifies | |
| 89 | + the userspace owner of the range. This groups ranges together | |
| 90 | + so that userspace programs can identify the ranges they | |
| 91 | + created and ignore those created by others. | |
| 92 | + The kernel returns this string back in the output of | |
| 93 | + @stats_list message, but it doesn't use it for anything else. | |
| 94 | + If we omit the number of optional arguments, program id must not | |
| 95 | + be a number, otherwise it would be interpreted as the number of | |
| 96 | + optional arguments. | |
| 97 | + | |
| 98 | + <aux_data> | |
| 99 | + An optional parameter. A word that provides auxiliary data | |
| 100 | + that is useful to the client program that created the range. | |
| 101 | + The kernel returns this string back in the output of | |
| 102 | + @stats_list message, but it doesn't use this value for anything. | |
| 103 | + | |
| 104 | + @stats_delete <region_id> | |
| 105 | + Delete the region with the specified id. | |
| 106 | + | |
| 107 | + <region_id> | |
| 108 | + region_id returned from @stats_create | |
| 109 | + | |
| 110 | + @stats_clear <region_id> | |
| 111 | + Clear all the counters except the in-flight i/o counters. | |
| 112 | + | |
| 113 | + <region_id> | |
| 114 | + region_id returned from @stats_create | |
| 115 | + | |
| 116 | + @stats_list [<program_id>] | |
| 117 | + List all regions registered with @stats_create. | |
| 118 | + | |
| 119 | + <program_id> | |
| 120 | + An optional parameter. | |
| 121 | + If this parameter is specified, only matching regions | |
| 122 | + are returned. | |
| 123 | + If it is not specified, all regions are returned. | |
| 124 | + | |
| 125 | + Output format: | |
| 126 | + <region_id>: <start_sector>+<length> <step> <program_id> <aux_data> | |
| 127 | + precise_timestamps histogram:n1,n2,n3,... | |
| 128 | + | |
| 129 | + The strings "precise_timestamps" and "histogram" are printed only | |
| 130 | + if they were specified when creating the region. | |
| 131 | + | |
| 132 | + @stats_print <region_id> [<starting_line> <number_of_lines>] | |
| 133 | + Print counters for each step-sized area of a region. | |
| 134 | + | |
| 135 | + <region_id> | |
| 136 | + region_id returned from @stats_create | |
| 137 | + | |
| 138 | + <starting_line> | |
| 139 | + The index of the starting line in the output. | |
| 140 | + If omitted, all lines are returned. | |
| 141 | + | |
| 142 | + <number_of_lines> | |
| 143 | + The number of lines to include in the output. | |
| 144 | + If omitted, all lines are returned. | |
| 145 | + | |
| 146 | + Output format for each step-sized area of a region: | |
| 147 | + | |
| 148 | + <start_sector>+<length> | |
| 149 | + counters | |
| 150 | + | |
| 151 | + The first 11 counters have the same meaning as | |
| 152 | + `/sys/block/*/stat or /proc/diskstats`. | |
| 153 | + | |
| 154 | + Please refer to Documentation/admin-guide/iostats.rst for details. | |
| 155 | + | |
| 156 | + 1. the number of reads completed | |
| 157 | + 2. the number of reads merged | |
| 158 | + 3. the number of sectors read | |
| 159 | + 4. the number of milliseconds spent reading | |
| 160 | + 5. the number of writes completed | |
| 161 | + 6. the number of writes merged | |
| 162 | + 7. the number of sectors written | |
| 163 | + 8. the number of milliseconds spent writing | |
| 164 | + 9. the number of I/Os currently in progress | |
| 165 | + 10. the number of milliseconds spent doing I/Os | |
| 166 | + 11. the weighted number of milliseconds spent doing I/Os | |
| 167 | + | |
| 168 | + Additional counters: | |
| 169 | + | |
| 170 | + 12. the total time spent reading in milliseconds | |
| 171 | + 13. the total time spent writing in milliseconds | |
| 172 | + | |
| 173 | + @stats_print_clear <region_id> [<starting_line> <number_of_lines>] | |
| 174 | + Atomically print and then clear all the counters except the | |
| 175 | + in-flight i/o counters. Useful when the client consuming the | |
| 176 | + statistics does not want to lose any statistics (those updated | |
| 177 | + between printing and clearing). | |
| 178 | + | |
| 179 | + <region_id> | |
| 180 | + region_id returned from @stats_create | |
| 181 | + | |
| 182 | + <starting_line> | |
| 183 | + The index of the starting line in the output. | |
| 184 | + If omitted, all lines are printed and then cleared. | |
| 185 | + | |
| 186 | + <number_of_lines> | |
| 187 | + The number of lines to process. | |
| 188 | + If omitted, all lines are printed and then cleared. | |
| 189 | + | |
| 190 | + @stats_set_aux <region_id> <aux_data> | |
| 191 | + Store auxiliary data aux_data for the specified region. | |
| 192 | + | |
| 193 | + <region_id> | |
| 194 | + region_id returned from @stats_create | |
| 195 | + | |
| 196 | + <aux_data> | |
| 197 | + The string that identifies data which is useful to the client | |
| 198 | + program that created the range. The kernel returns this | |
| 199 | + string back in the output of @stats_list message, but it | |
| 200 | + doesn't use this value for anything. | |
| 201 | + | |
| 202 | +Examples | |
| 203 | +======== | |
| 204 | + | |
| 205 | +Subdivide the DM device 'vol' into 100 pieces and start collecting | |
| 206 | +statistics on them:: | |
| 207 | + | |
| 208 | + dmsetup message vol 0 @stats_create - /100 | |
| 209 | + | |
| 210 | +Set the auxiliary data string to "foo bar baz" (the escape for each | |
| 211 | +space must also be escaped, otherwise the shell will consume them):: | |
| 212 | + | |
| 213 | + dmsetup message vol 0 @stats_set_aux 0 foo\\ bar\\ baz | |
| 214 | + | |
| 215 | +List the statistics:: | |
| 216 | + | |
| 217 | + dmsetup message vol 0 @stats_list | |
| 218 | + | |
| 219 | +Print the statistics:: | |
| 220 | + | |
| 221 | + dmsetup message vol 0 @stats_print 0 | |
| 222 | + | |
| 223 | +Delete the statistics:: | |
| 224 | + | |
| 225 | + dmsetup message vol 0 @stats_delete 0 | |
| @@ -0,0 +1,61 @@ | ||
| 1 | +========= | |
| 2 | +dm-stripe | |
| 3 | +========= | |
| 4 | + | |
| 5 | +Device-Mapper's "striped" target is used to create a striped (i.e. RAID-0) | |
| 6 | +device across one or more underlying devices. Data is written in "chunks", | |
| 7 | +with consecutive chunks rotating among the underlying devices. This can | |
| 8 | +potentially provide improved I/O throughput by utilizing several physical | |
| 9 | +devices in parallel. | |
| 10 | + | |
| 11 | +Parameters: <num devs> <chunk size> [<dev path> <offset>]+ | |
| 12 | + <num devs>: | |
| 13 | + Number of underlying devices. | |
| 14 | + <chunk size>: | |
| 15 | + Size of each chunk of data. Must be at least as | |
| 16 | + large as the system's PAGE_SIZE. | |
| 17 | + <dev path>: | |
| 18 | + Full pathname to the underlying block-device, or a | |
| 19 | + "major:minor" device-number. | |
| 20 | + <offset>: | |
| 21 | + Starting sector within the device. | |
| 22 | + | |
| 23 | +One or more underlying devices can be specified. The striped device size must | |
| 24 | +be a multiple of the chunk size multiplied by the number of underlying devices. | |
| 25 | + | |
| 26 | + | |
| 27 | +Example scripts | |
| 28 | +=============== | |
| 29 | + | |
| 30 | +:: | |
| 31 | + | |
| 32 | + #!/usr/bin/perl -w | |
| 33 | + # Create a striped device across any number of underlying devices. The device | |
| 34 | + # will be called "stripe_dev" and have a chunk-size of 128k. | |
| 35 | + | |
| 36 | + my $chunk_size = 128 * 2; | |
| 37 | + my $dev_name = "stripe_dev"; | |
| 38 | + my $num_devs = @ARGV; | |
| 39 | + my @devs = @ARGV; | |
| 40 | + my ($min_dev_size, $stripe_dev_size, $i); | |
| 41 | + | |
| 42 | + if (!$num_devs) { | |
| 43 | + die("Specify at least one device\n"); | |
| 44 | + } | |
| 45 | + | |
| 46 | + $min_dev_size = `blockdev --getsz $devs[0]`; | |
| 47 | + for ($i = 1; $i < $num_devs; $i++) { | |
| 48 | + my $this_size = `blockdev --getsz $devs[$i]`; | |
| 49 | + $min_dev_size = ($min_dev_size < $this_size) ? | |
| 50 | + $min_dev_size : $this_size; | |
| 51 | + } | |
| 52 | + | |
| 53 | + $stripe_dev_size = $min_dev_size * $num_devs; | |
| 54 | + $stripe_dev_size -= $stripe_dev_size % ($chunk_size * $num_devs); | |
| 55 | + | |
| 56 | + $table = "0 $stripe_dev_size striped $num_devs $chunk_size"; | |
| 57 | + for ($i = 0; $i < $num_devs; $i++) { | |
| 58 | + $table .= " $devs[$i] 0"; | |
| 59 | + } | |
| 60 | + | |
| 61 | + `echo $table | dmsetup create $dev_name`; | |
| @@ -0,0 +1,141 @@ | ||
| 1 | +========= | |
| 2 | +dm-switch | |
| 3 | +========= | |
| 4 | + | |
| 5 | +The device-mapper switch target creates a device that supports an | |
| 6 | +arbitrary mapping of fixed-size regions of I/O across a fixed set of | |
| 7 | +paths. The path used for any specific region can be switched | |
| 8 | +dynamically by sending the target a message. | |
| 9 | + | |
| 10 | +It maps I/O to underlying block devices efficiently when there is a large | |
| 11 | +number of fixed-sized address regions but there is no simple pattern | |
| 12 | +that would allow for a compact representation of the mapping such as | |
| 13 | +dm-stripe. | |
| 14 | + | |
| 15 | +Background | |
| 16 | +---------- | |
| 17 | + | |
| 18 | +Dell EqualLogic and some other iSCSI storage arrays use a distributed | |
| 19 | +frameless architecture. In this architecture, the storage group | |
| 20 | +consists of a number of distinct storage arrays ("members") each having | |
| 21 | +independent controllers, disk storage and network adapters. When a LUN | |
| 22 | +is created it is spread across multiple members. The details of the | |
| 23 | +spreading are hidden from initiators connected to this storage system. | |
| 24 | +The storage group exposes a single target discovery portal, no matter | |
| 25 | +how many members are being used. When iSCSI sessions are created, each | |
| 26 | +session is connected to an eth port on a single member. Data to a LUN | |
| 27 | +can be sent on any iSCSI session, and if the blocks being accessed are | |
| 28 | +stored on another member the I/O will be forwarded as required. This | |
| 29 | +forwarding is invisible to the initiator. The storage layout is also | |
| 30 | +dynamic, and the blocks stored on disk may be moved from member to | |
| 31 | +member as needed to balance the load. | |
| 32 | + | |
| 33 | +This architecture simplifies the management and configuration of both | |
| 34 | +the storage group and initiators. In a multipathing configuration, it | |
| 35 | +is possible to set up multiple iSCSI sessions to use multiple network | |
| 36 | +interfaces on both the host and target to take advantage of the | |
| 37 | +increased network bandwidth. An initiator could use a simple round | |
| 38 | +robin algorithm to send I/O across all paths and let the storage array | |
| 39 | +members forward it as necessary, but there is a performance advantage to | |
| 40 | +sending data directly to the correct member. | |
| 41 | + | |
| 42 | +A device-mapper table already lets you map different regions of a | |
| 43 | +device onto different targets. However in this architecture the LUN is | |
| 44 | +spread with an address region size on the order of 10s of MBs, which | |
| 45 | +means the resulting table could have more than a million entries and | |
| 46 | +consume far too much memory. | |
| 47 | + | |
| 48 | +Using this device-mapper switch target we can now build a two-layer | |
| 49 | +device hierarchy: | |
| 50 | + | |
| 51 | + Upper Tier - Determine which array member the I/O should be sent to. | |
| 52 | + Lower Tier - Load balance amongst paths to a particular member. | |
| 53 | + | |
| 54 | +The lower tier consists of a single dm multipath device for each member. | |
| 55 | +Each of these multipath devices contains the set of paths directly to | |
| 56 | +the array member in one priority group, and leverages existing path | |
| 57 | +selectors to load balance amongst these paths. We also build a | |
| 58 | +non-preferred priority group containing paths to other array members for | |
| 59 | +failover reasons. | |
| 60 | + | |
| 61 | +The upper tier consists of a single dm-switch device. This device uses | |
| 62 | +a bitmap to look up the location of the I/O and choose the appropriate | |
| 63 | +lower tier device to route the I/O. By using a bitmap we are able to | |
| 64 | +use 4 bits for each address range in a 16 member group (which is very | |
| 65 | +large for us). This is a much denser representation than the dm table | |
| 66 | +b-tree can achieve. | |
| 67 | + | |
| 68 | +Construction Parameters | |
| 69 | +======================= | |
| 70 | + | |
| 71 | + <num_paths> <region_size> <num_optional_args> [<optional_args>...] [<dev_path> <offset>]+ | |
| 72 | + <num_paths> | |
| 73 | + The number of paths across which to distribute the I/O. | |
| 74 | + | |
| 75 | + <region_size> | |
| 76 | + The number of 512-byte sectors in a region. Each region can be redirected | |
| 77 | + to any of the available paths. | |
| 78 | + | |
| 79 | + <num_optional_args> | |
| 80 | + The number of optional arguments. Currently, no optional arguments | |
| 81 | + are supported and so this must be zero. | |
| 82 | + | |
| 83 | + <dev_path> | |
| 84 | + The block device that represents a specific path to the device. | |
| 85 | + | |
| 86 | + <offset> | |
| 87 | + The offset of the start of data on the specific <dev_path> (in units | |
| 88 | + of 512-byte sectors). This number is added to the sector number when | |
| 89 | + forwarding the request to the specific path. Typically it is zero. | |
| 90 | + | |
| 91 | +Messages | |
| 92 | +======== | |
| 93 | + | |
| 94 | +set_region_mappings <index>:<path_nr> [<index>]:<path_nr> [<index>]:<path_nr>... | |
| 95 | + | |
| 96 | +Modify the region table by specifying which regions are redirected to | |
| 97 | +which paths. | |
| 98 | + | |
| 99 | +<index> | |
| 100 | + The region number (region size was specified in constructor parameters). | |
| 101 | + If index is omitted, the next region (previous index + 1) is used. | |
| 102 | + Expressed in hexadecimal (WITHOUT any prefix like 0x). | |
| 103 | + | |
| 104 | +<path_nr> | |
| 105 | + The path number in the range 0 ... (<num_paths> - 1). | |
| 106 | + Expressed in hexadecimal (WITHOUT any prefix like 0x). | |
| 107 | + | |
| 108 | +R<n>,<m> | |
| 109 | + This parameter allows repetitive patterns to be loaded quickly. <n> and <m> | |
| 110 | + are hexadecimal numbers. The last <n> mappings are repeated in the next <m> | |
| 111 | + slots. | |
| 112 | + | |
| 113 | +Status | |
| 114 | +====== | |
| 115 | + | |
| 116 | +No status line is reported. | |
| 117 | + | |
| 118 | +Example | |
| 119 | +======= | |
| 120 | + | |
| 121 | +Assume that you have volumes vg1/switch0 vg1/switch1 vg1/switch2 with | |
| 122 | +the same size. | |
| 123 | + | |
| 124 | +Create a switch device with 64kB region size:: | |
| 125 | + | |
| 126 | + dmsetup create switch --table "0 `blockdev --getsz /dev/vg1/switch0` | |
| 127 | + switch 3 128 0 /dev/vg1/switch0 0 /dev/vg1/switch1 0 /dev/vg1/switch2 0" | |
| 128 | + | |
| 129 | +Set mappings for the first 7 entries to point to devices switch0, switch1, | |
| 130 | +switch2, switch0, switch1, switch2, switch1:: | |
| 131 | + | |
| 132 | + dmsetup message switch 0 set_region_mappings 0:0 :1 :2 :0 :1 :2 :1 | |
| 133 | + | |
| 134 | +Set repetitive mapping. This command:: | |
| 135 | + | |
| 136 | + dmsetup message switch 0 set_region_mappings 1000:1 :2 R2,10 | |
| 137 | + | |
| 138 | +is equivalent to:: | |
| 139 | + | |
| 140 | + dmsetup message switch 0 set_region_mappings 1000:1 :2 :1 :2 :1 :2 :1 :2 \ | |
| 141 | + :1 :2 :1 :2 :1 :2 :1 :2 :1 :2 | |
| @@ -0,0 +1,427 @@ | ||
| 1 | +================= | |
| 2 | +Thin provisioning | |
| 3 | +================= | |
| 4 | + | |
| 5 | +Introduction | |
| 6 | +============ | |
| 7 | + | |
| 8 | +This document describes a collection of device-mapper targets that | |
| 9 | +between them implement thin-provisioning and snapshots. | |
| 10 | + | |
| 11 | +The main highlight of this implementation, compared to the previous | |
| 12 | +implementation of snapshots, is that it allows many virtual devices to | |
| 13 | +be stored on the same data volume. This simplifies administration and | |
| 14 | +allows the sharing of data between volumes, thus reducing disk usage. | |
| 15 | + | |
| 16 | +Another significant feature is support for an arbitrary depth of | |
| 17 | +recursive snapshots (snapshots of snapshots of snapshots ...). The | |
| 18 | +previous implementation of snapshots did this by chaining together | |
| 19 | +lookup tables, and so performance was O(depth). This new | |
| 20 | +implementation uses a single data structure to avoid this degradation | |
| 21 | +with depth. Fragmentation may still be an issue, however, in some | |
| 22 | +scenarios. | |
| 23 | + | |
| 24 | +Metadata is stored on a separate device from data, giving the | |
| 25 | +administrator some freedom, for example to: | |
| 26 | + | |
| 27 | +- Improve metadata resilience by storing metadata on a mirrored volume | |
| 28 | + but data on a non-mirrored one. | |
| 29 | + | |
| 30 | +- Improve performance by storing the metadata on SSD. | |
| 31 | + | |
| 32 | +Status | |
| 33 | +====== | |
| 34 | + | |
| 35 | +These targets are considered safe for production use. But different use | |
| 36 | +cases will have different performance characteristics, for example due | |
| 37 | +to fragmentation of the data volume. | |
| 38 | + | |
| 39 | +If you find this software is not performing as expected please mail | |
| 40 | +dm-devel@redhat.com with details and we'll try our best to improve | |
| 41 | +things for you. | |
| 42 | + | |
| 43 | +Userspace tools for checking and repairing the metadata have been fully | |
| 44 | +developed and are available as 'thin_check' and 'thin_repair'. The name | |
| 45 | +of the package that provides these utilities varies by distribution (on | |
| 46 | +a Red Hat distribution it is named 'device-mapper-persistent-data'). | |
| 47 | + | |
| 48 | +Cookbook | |
| 49 | +======== | |
| 50 | + | |
| 51 | +This section describes some quick recipes for using thin provisioning. | |
| 52 | +They use the dmsetup program to control the device-mapper driver | |
| 53 | +directly. End users will be advised to use a higher-level volume | |
| 54 | +manager such as LVM2 once support has been added. | |
| 55 | + | |
| 56 | +Pool device | |
| 57 | +----------- | |
| 58 | + | |
| 59 | +The pool device ties together the metadata volume and the data volume. | |
| 60 | +It maps I/O linearly to the data volume and updates the metadata via | |
| 61 | +two mechanisms: | |
| 62 | + | |
| 63 | +- Function calls from the thin targets | |
| 64 | + | |
| 65 | +- Device-mapper 'messages' from userspace which control the creation of new | |
| 66 | + virtual devices amongst other things. | |
| 67 | + | |
| 68 | +Setting up a fresh pool device | |
| 69 | +------------------------------ | |
| 70 | + | |
| 71 | +Setting up a pool device requires a valid metadata device, and a | |
| 72 | +data device. If you do not have an existing metadata device you can | |
| 73 | +make one by zeroing the first 4k to indicate empty metadata. | |
| 74 | + | |
| 75 | + dd if=/dev/zero of=$metadata_dev bs=4096 count=1 | |
| 76 | + | |
| 77 | +The amount of metadata you need will vary according to how many blocks | |
| 78 | +are shared between thin devices (i.e. through snapshots). If you have | |
| 79 | +less sharing than average you'll need a larger-than-average metadata device. | |
| 80 | + | |
| 81 | +As a guide, we suggest you calculate the number of bytes to use in the | |
| 82 | +metadata device as 48 * $data_dev_size / $data_block_size but round it up | |
| 83 | +to 2MB if the answer is smaller. If you're creating large numbers of | |
| 84 | +snapshots which are recording large amounts of change, you may find you | |
| 85 | +need to increase this. | |
| 86 | + | |
| 87 | +The largest size supported is 16GB: If the device is larger, | |
| 88 | +a warning will be issued and the excess space will not be used. | |
| 89 | + | |
| 90 | +Reloading a pool table | |
| 91 | +---------------------- | |
| 92 | + | |
| 93 | +You may reload a pool's table, indeed this is how the pool is resized | |
| 94 | +if it runs out of space. (N.B. While specifying a different metadata | |
| 95 | +device when reloading is not forbidden at the moment, things will go | |
| 96 | +wrong if it does not route I/O to exactly the same on-disk location as | |
| 97 | +previously.) | |
| 98 | + | |
| 99 | +Using an existing pool device | |
| 100 | +----------------------------- | |
| 101 | + | |
| 102 | +:: | |
| 103 | + | |
| 104 | + dmsetup create pool \ | |
| 105 | + --table "0 20971520 thin-pool $metadata_dev $data_dev \ | |
| 106 | + $data_block_size $low_water_mark" | |
| 107 | + | |
| 108 | +$data_block_size gives the smallest unit of disk space that can be | |
| 109 | +allocated at a time expressed in units of 512-byte sectors. | |
| 110 | +$data_block_size must be between 128 (64KB) and 2097152 (1GB) and a | |
| 111 | +multiple of 128 (64KB). $data_block_size cannot be changed after the | |
| 112 | +thin-pool is created. People primarily interested in thin provisioning | |
| 113 | +may want to use a value such as 1024 (512KB). People doing lots of | |
| 114 | +snapshotting may want a smaller value such as 128 (64KB). If you are | |
| 115 | +not zeroing newly-allocated data, a larger $data_block_size in the | |
| 116 | +region of 256000 (128MB) is suggested. | |
| 117 | + | |
| 118 | +$low_water_mark is expressed in blocks of size $data_block_size. If | |
| 119 | +free space on the data device drops below this level then a dm event | |
| 120 | +will be triggered which a userspace daemon should catch allowing it to | |
| 121 | +extend the pool device. Only one such event will be sent. | |
| 122 | + | |
| 123 | +No special event is triggered if a just resumed device's free space is below | |
| 124 | +the low water mark. However, resuming a device always triggers an | |
| 125 | +event; a userspace daemon should verify that free space exceeds the low | |
| 126 | +water mark when handling this event. | |
| 127 | + | |
| 128 | +A low water mark for the metadata device is maintained in the kernel and | |
| 129 | +will trigger a dm event if free space on the metadata device drops below | |
| 130 | +it. | |
| 131 | + | |
| 132 | +Updating on-disk metadata | |
| 133 | +------------------------- | |
| 134 | + | |
| 135 | +On-disk metadata is committed every time a FLUSH or FUA bio is written. | |
| 136 | +If no such requests are made then commits will occur every second. This | |
| 137 | +means the thin-provisioning target behaves like a physical disk that has | |
| 138 | +a volatile write cache. If power is lost you may lose some recent | |
| 139 | +writes. The metadata should always be consistent in spite of any crash. | |
| 140 | + | |
| 141 | +If data space is exhausted the pool will either error or queue IO | |
| 142 | +according to the configuration (see: error_if_no_space). If metadata | |
| 143 | +space is exhausted or a metadata operation fails: the pool will error IO | |
| 144 | +until the pool is taken offline and repair is performed to 1) fix any | |
| 145 | +potential inconsistencies and 2) clear the flag that imposes repair. | |
| 146 | +Once the pool's metadata device is repaired it may be resized, which | |
| 147 | +will allow the pool to return to normal operation. Note that if a pool | |
| 148 | +is flagged as needing repair, the pool's data and metadata devices | |
| 149 | +cannot be resized until repair is performed. It should also be noted | |
| 150 | +that when the pool's metadata space is exhausted the current metadata | |
| 151 | +transaction is aborted. Given that the pool will cache IO whose | |
| 152 | +completion may have already been acknowledged to upper IO layers | |
| 153 | +(e.g. filesystem) it is strongly suggested that consistency checks | |
| 154 | +(e.g. fsck) be performed on those layers when repair of the pool is | |
| 155 | +required. | |
| 156 | + | |
| 157 | +Thin provisioning | |
| 158 | +----------------- | |
| 159 | + | |
| 160 | +i) Creating a new thinly-provisioned volume. | |
| 161 | + | |
| 162 | + To create a new thinly- provisioned volume you must send a message to an | |
| 163 | + active pool device, /dev/mapper/pool in this example:: | |
| 164 | + | |
| 165 | + dmsetup message /dev/mapper/pool 0 "create_thin 0" | |
| 166 | + | |
| 167 | + Here '0' is an identifier for the volume, a 24-bit number. It's up | |
| 168 | + to the caller to allocate and manage these identifiers. If the | |
| 169 | + identifier is already in use, the message will fail with -EEXIST. | |
| 170 | + | |
| 171 | +ii) Using a thinly-provisioned volume. | |
| 172 | + | |
| 173 | + Thinly-provisioned volumes are activated using the 'thin' target:: | |
| 174 | + | |
| 175 | + dmsetup create thin --table "0 2097152 thin /dev/mapper/pool 0" | |
| 176 | + | |
| 177 | + The last parameter is the identifier for the thinp device. | |
| 178 | + | |
| 179 | +Internal snapshots | |
| 180 | +------------------ | |
| 181 | + | |
| 182 | +i) Creating an internal snapshot. | |
| 183 | + | |
| 184 | + Snapshots are created with another message to the pool. | |
| 185 | + | |
| 186 | + N.B. If the origin device that you wish to snapshot is active, you | |
| 187 | + must suspend it before creating the snapshot to avoid corruption. | |
| 188 | + This is NOT enforced at the moment, so please be careful! | |
| 189 | + | |
| 190 | + :: | |
| 191 | + | |
| 192 | + dmsetup suspend /dev/mapper/thin | |
| 193 | + dmsetup message /dev/mapper/pool 0 "create_snap 1 0" | |
| 194 | + dmsetup resume /dev/mapper/thin | |
| 195 | + | |
| 196 | + Here '1' is the identifier for the volume, a 24-bit number. '0' is the | |
| 197 | + identifier for the origin device. | |
| 198 | + | |
| 199 | +ii) Using an internal snapshot. | |
| 200 | + | |
| 201 | + Once created, the user doesn't have to worry about any connection | |
| 202 | + between the origin and the snapshot. Indeed the snapshot is no | |
| 203 | + different from any other thinly-provisioned device and can be | |
| 204 | + snapshotted itself via the same method. It's perfectly legal to | |
| 205 | + have only one of them active, and there's no ordering requirement on | |
| 206 | + activating or removing them both. (This differs from conventional | |
| 207 | + device-mapper snapshots.) | |
| 208 | + | |
| 209 | + Activate it exactly the same way as any other thinly-provisioned volume:: | |
| 210 | + | |
| 211 | + dmsetup create snap --table "0 2097152 thin /dev/mapper/pool 1" | |
| 212 | + | |
| 213 | +External snapshots | |
| 214 | +------------------ | |
| 215 | + | |
| 216 | +You can use an external **read only** device as an origin for a | |
| 217 | +thinly-provisioned volume. Any read to an unprovisioned area of the | |
| 218 | +thin device will be passed through to the origin. Writes trigger | |
| 219 | +the allocation of new blocks as usual. | |
| 220 | + | |
| 221 | +One use case for this is VM hosts that want to run guests on | |
| 222 | +thinly-provisioned volumes but have the base image on another device | |
| 223 | +(possibly shared between many VMs). | |
| 224 | + | |
| 225 | +You must not write to the origin device if you use this technique! | |
| 226 | +Of course, you may write to the thin device and take internal snapshots | |
| 227 | +of the thin volume. | |
| 228 | + | |
| 229 | +i) Creating a snapshot of an external device | |
| 230 | + | |
| 231 | + This is the same as creating a thin device. | |
| 232 | + You don't mention the origin at this stage. | |
| 233 | + | |
| 234 | + :: | |
| 235 | + | |
| 236 | + dmsetup message /dev/mapper/pool 0 "create_thin 0" | |
| 237 | + | |
| 238 | +ii) Using a snapshot of an external device. | |
| 239 | + | |
| 240 | + Append an extra parameter to the thin target specifying the origin:: | |
| 241 | + | |
| 242 | + dmsetup create snap --table "0 2097152 thin /dev/mapper/pool 0 /dev/image" | |
| 243 | + | |
| 244 | + N.B. All descendants (internal snapshots) of this snapshot require the | |
| 245 | + same extra origin parameter. | |
| 246 | + | |
| 247 | +Deactivation | |
| 248 | +------------ | |
| 249 | + | |
| 250 | +All devices using a pool must be deactivated before the pool itself | |
| 251 | +can be. | |
| 252 | + | |
| 253 | +:: | |
| 254 | + | |
| 255 | + dmsetup remove thin | |
| 256 | + dmsetup remove snap | |
| 257 | + dmsetup remove pool | |
| 258 | + | |
| 259 | +Reference | |
| 260 | +========= | |
| 261 | + | |
| 262 | +'thin-pool' target | |
| 263 | +------------------ | |
| 264 | + | |
| 265 | +i) Constructor | |
| 266 | + | |
| 267 | + :: | |
| 268 | + | |
| 269 | + thin-pool <metadata dev> <data dev> <data block size (sectors)> \ | |
| 270 | + <low water mark (blocks)> [<number of feature args> [<arg>]*] | |
| 271 | + | |
| 272 | + Optional feature arguments: | |
| 273 | + | |
| 274 | + skip_block_zeroing: | |
| 275 | + Skip the zeroing of newly-provisioned blocks. | |
| 276 | + | |
| 277 | + ignore_discard: | |
| 278 | + Disable discard support. | |
| 279 | + | |
| 280 | + no_discard_passdown: | |
| 281 | + Don't pass discards down to the underlying | |
| 282 | + data device, but just remove the mapping. | |
| 283 | + | |
| 284 | + read_only: | |
| 285 | + Don't allow any changes to be made to the pool | |
| 286 | + metadata. This mode is only available after the | |
| 287 | + thin-pool has been created and first used in full | |
| 288 | + read/write mode. It cannot be specified on initial | |
| 289 | + thin-pool creation. | |
| 290 | + | |
| 291 | + error_if_no_space: | |
| 292 | + Error IOs, instead of queueing, if no space. | |
| 293 | + | |
| 294 | + Data block size must be between 64KB (128 sectors) and 1GB | |
| 295 | + (2097152 sectors) inclusive. | |
| 296 | + | |
| 297 | + | |
| 298 | +ii) Status | |
| 299 | + | |
| 300 | + :: | |
| 301 | + | |
| 302 | + <transaction id> <used metadata blocks>/<total metadata blocks> | |
| 303 | + <used data blocks>/<total data blocks> <held metadata root> | |
| 304 | + ro|rw|out_of_data_space [no_]discard_passdown [error|queue]_if_no_space | |
| 305 | + needs_check|- metadata_low_watermark | |
| 306 | + | |
| 307 | + transaction id: | |
| 308 | + A 64-bit number used by userspace to help synchronise with metadata | |
| 309 | + from volume managers. | |
| 310 | + | |
| 311 | + used data blocks / total data blocks | |
| 312 | + If the number of free blocks drops below the pool's low water mark a | |
| 313 | + dm event will be sent to userspace. This event is edge-triggered and | |
| 314 | + it will occur only once after each resume so volume manager writers | |
| 315 | + should register for the event and then check the target's status. | |
| 316 | + | |
| 317 | + held metadata root: | |
| 318 | + The location, in blocks, of the metadata root that has been | |
| 319 | + 'held' for userspace read access. '-' indicates there is no | |
| 320 | + held root. | |
| 321 | + | |
| 322 | + discard_passdown|no_discard_passdown | |
| 323 | + Whether or not discards are actually being passed down to the | |
| 324 | + underlying device. When this is enabled when loading the table, | |
| 325 | + it can get disabled if the underlying device doesn't support it. | |
| 326 | + | |
| 327 | + ro|rw|out_of_data_space | |
| 328 | + If the pool encounters certain types of device failures it will | |
| 329 | + drop into a read-only metadata mode in which no changes to | |
| 330 | + the pool metadata (like allocating new blocks) are permitted. | |
| 331 | + | |
| 332 | + In serious cases where even a read-only mode is deemed unsafe | |
| 333 | + no further I/O will be permitted and the status will just | |
| 334 | + contain the string 'Fail'. The userspace recovery tools | |
| 335 | + should then be used. | |
| 336 | + | |
| 337 | + error_if_no_space|queue_if_no_space | |
| 338 | + If the pool runs out of data or metadata space, the pool will | |
| 339 | + either queue or error the IO destined to the data device. The | |
| 340 | + default is to queue the IO until more space is added or the | |
| 341 | + 'no_space_timeout' expires. The 'no_space_timeout' dm-thin-pool | |
| 342 | + module parameter can be used to change this timeout -- it | |
| 343 | + defaults to 60 seconds but may be disabled using a value of 0. | |
| 344 | + | |
| 345 | + needs_check | |
| 346 | + A metadata operation has failed, resulting in the needs_check | |
| 347 | + flag being set in the metadata's superblock. The metadata | |
| 348 | + device must be deactivated and checked/repaired before the | |
| 349 | + thin-pool can be made fully operational again. '-' indicates | |
| 350 | + needs_check is not set. | |
| 351 | + | |
| 352 | + metadata_low_watermark: | |
| 353 | + Value of metadata low watermark in blocks. The kernel sets this | |
| 354 | + value internally but userspace needs to know this value to | |
| 355 | + determine if an event was caused by crossing this threshold. | |
| 356 | + | |
| 357 | +iii) Messages | |
| 358 | + | |
| 359 | + create_thin <dev id> | |
| 360 | + Create a new thinly-provisioned device. | |
| 361 | + <dev id> is an arbitrary unique 24-bit identifier chosen by | |
| 362 | + the caller. | |
| 363 | + | |
| 364 | + create_snap <dev id> <origin id> | |
| 365 | + Create a new snapshot of another thinly-provisioned device. | |
| 366 | + <dev id> is an arbitrary unique 24-bit identifier chosen by | |
| 367 | + the caller. | |
| 368 | + <origin id> is the identifier of the thinly-provisioned device | |
| 369 | + of which the new device will be a snapshot. | |
| 370 | + | |
| 371 | + delete <dev id> | |
| 372 | + Deletes a thin device. Irreversible. | |
| 373 | + | |
| 374 | + set_transaction_id <current id> <new id> | |
| 375 | + Userland volume managers, such as LVM, need a way to | |
| 376 | + synchronise their external metadata with the internal metadata of the | |
| 377 | + pool target. The thin-pool target offers to store an | |
| 378 | + arbitrary 64-bit transaction id and return it on the target's | |
| 379 | + status line. To avoid races you must provide what you think | |
| 380 | + the current transaction id is when you change it with this | |
| 381 | + compare-and-swap message. | |
| 382 | + | |
| 383 | + reserve_metadata_snap | |
| 384 | + Reserve a copy of the data mapping btree for use by userland. | |
| 385 | + This allows userland to inspect the mappings as they were when | |
| 386 | + this message was executed. Use the pool's status command to | |
| 387 | + get the root block associated with the metadata snapshot. | |
| 388 | + | |
| 389 | + release_metadata_snap | |
| 390 | + Release a previously reserved copy of the data mapping btree. | |
| 391 | + | |
| 392 | +'thin' target | |
| 393 | +------------- | |
| 394 | + | |
| 395 | +i) Constructor | |
| 396 | + | |
| 397 | + :: | |
| 398 | + | |
| 399 | + thin <pool dev> <dev id> [<external origin dev>] | |
| 400 | + | |
| 401 | + pool dev: | |
| 402 | + the thin-pool device, e.g. /dev/mapper/my_pool or 253:0 | |
| 403 | + | |
| 404 | + dev id: | |
| 405 | + the internal device identifier of the device to be | |
| 406 | + activated. | |
| 407 | + | |
| 408 | + external origin dev: | |
| 409 | + an optional block device outside the pool to be treated as a | |
| 410 | + read-only snapshot origin: reads to unprovisioned areas of the | |
| 411 | + thin target will be mapped to this device. | |
| 412 | + | |
| 413 | +The pool doesn't store any size against the thin devices. If you | |
| 414 | +load a thin target that is smaller than you've been using previously, | |
| 415 | +then you'll have no access to blocks mapped beyond the end. If you | |
| 416 | +load a target that is bigger than before, then extra blocks will be | |
| 417 | +provisioned as and when needed. | |
| 418 | + | |
| 419 | +ii) Status | |
| 420 | + | |
| 421 | + <nr mapped sectors> <highest mapped sector> | |
| 422 | + If the pool has encountered device errors and failed, the status | |
| 423 | + will just contain the string 'Fail'. The userspace recovery | |
| 424 | + tools should then be used. | |
| 425 | + | |
| 426 | + In the case where <nr mapped sectors> is 0, there is no highest | |
| 427 | + mapped sector and the value of <highest mapped sector> is unspecified. | |
| @@ -0,0 +1,135 @@ | ||
| 1 | +================================ | |
| 2 | +Device-mapper "unstriped" target | |
| 3 | +================================ | |
| 4 | + | |
| 5 | +Introduction | |
| 6 | +============ | |
| 7 | + | |
| 8 | +The device-mapper "unstriped" target provides a transparent mechanism to | |
| 9 | +unstripe a device-mapper "striped" target to access the underlying disks | |
| 10 | +without having to touch the true backing block-device. It can also be | |
| 11 | +used to unstripe a hardware RAID-0 to access backing disks. | |
| 12 | + | |
| 13 | +Parameters: | |
| 14 | +<number of stripes> <chunk size> <stripe #> <dev_path> <offset> | |
| 15 | + | |
| 16 | +<number of stripes> | |
| 17 | + The number of stripes in the RAID 0. | |
| 18 | + | |
| 19 | +<chunk size> | |
| 20 | + The amount of 512B sectors in the chunk striping. | |
| 21 | + | |
| 22 | +<dev_path> | |
| 23 | + The block device you wish to unstripe. | |
| 24 | + | |
| 25 | +<stripe #> | |
| 26 | + The stripe number within the device that corresponds to physical | |
| 27 | + drive you wish to unstripe. This must be 0 indexed. | |
| 28 | + | |
| 29 | + | |
| 30 | +Why use this module? | |
| 31 | +==================== | |
| 32 | + | |
| 33 | +An example of undoing an existing dm-stripe | |
| 34 | +------------------------------------------- | |
| 35 | + | |
| 36 | +This small bash script will setup 4 loop devices and use the existing | |
| 37 | +striped target to combine the 4 devices into one. It then will use | |
| 38 | +the unstriped target ontop of the striped device to access the | |
| 39 | +individual backing loop devices. We write data to the newly exposed | |
| 40 | +unstriped devices and verify the data written matches the correct | |
| 41 | +underlying device on the striped array:: | |
| 42 | + | |
| 43 | + #!/bin/bash | |
| 44 | + | |
| 45 | + MEMBER_SIZE=$((128 * 1024 * 1024)) | |
| 46 | + NUM=4 | |
| 47 | + SEQ_END=$((${NUM}-1)) | |
| 48 | + CHUNK=256 | |
| 49 | + BS=4096 | |
| 50 | + | |
| 51 | + RAID_SIZE=$((${MEMBER_SIZE}*${NUM}/512)) | |
| 52 | + DM_PARMS="0 ${RAID_SIZE} striped ${NUM} ${CHUNK}" | |
| 53 | + COUNT=$((${MEMBER_SIZE} / ${BS})) | |
| 54 | + | |
| 55 | + for i in $(seq 0 ${SEQ_END}); do | |
| 56 | + dd if=/dev/zero of=member-${i} bs=${MEMBER_SIZE} count=1 oflag=direct | |
| 57 | + losetup /dev/loop${i} member-${i} | |
| 58 | + DM_PARMS+=" /dev/loop${i} 0" | |
| 59 | + done | |
| 60 | + | |
| 61 | + echo $DM_PARMS | dmsetup create raid0 | |
| 62 | + for i in $(seq 0 ${SEQ_END}); do | |
| 63 | + echo "0 1 unstriped ${NUM} ${CHUNK} ${i} /dev/mapper/raid0 0" | dmsetup create set-${i} | |
| 64 | + done; | |
| 65 | + | |
| 66 | + for i in $(seq 0 ${SEQ_END}); do | |
| 67 | + dd if=/dev/urandom of=/dev/mapper/set-${i} bs=${BS} count=${COUNT} oflag=direct | |
| 68 | + diff /dev/mapper/set-${i} member-${i} | |
| 69 | + done; | |
| 70 | + | |
| 71 | + for i in $(seq 0 ${SEQ_END}); do | |
| 72 | + dmsetup remove set-${i} | |
| 73 | + done | |
| 74 | + | |
| 75 | + dmsetup remove raid0 | |
| 76 | + | |
| 77 | + for i in $(seq 0 ${SEQ_END}); do | |
| 78 | + losetup -d /dev/loop${i} | |
| 79 | + rm -f member-${i} | |
| 80 | + done | |
| 81 | + | |
| 82 | +Another example | |
| 83 | +--------------- | |
| 84 | + | |
| 85 | +Intel NVMe drives contain two cores on the physical device. | |
| 86 | +Each core of the drive has segregated access to its LBA range. | |
| 87 | +The current LBA model has a RAID 0 128k chunk on each core, resulting | |
| 88 | +in a 256k stripe across the two cores:: | |
| 89 | + | |
| 90 | + Core 0: Core 1: | |
| 91 | + __________ __________ | |
| 92 | + | LBA 512| | LBA 768| | |
| 93 | + | LBA 0 | | LBA 256| | |
| 94 | + ---------- ---------- | |
| 95 | + | |
| 96 | +The purpose of this unstriping is to provide better QoS in noisy | |
| 97 | +neighbor environments. When two partitions are created on the | |
| 98 | +aggregate drive without this unstriping, reads on one partition | |
| 99 | +can affect writes on another partition. This is because the partitions | |
| 100 | +are striped across the two cores. When we unstripe this hardware RAID 0 | |
| 101 | +and make partitions on each new exposed device the two partitions are now | |
| 102 | +physically separated. | |
| 103 | + | |
| 104 | +With the dm-unstriped target we're able to segregate an fio script that | |
| 105 | +has read and write jobs that are independent of each other. Compared to | |
| 106 | +when we run the test on a combined drive with partitions, we were able | |
| 107 | +to get a 92% reduction in read latency using this device mapper target. | |
| 108 | + | |
| 109 | + | |
| 110 | +Example dmsetup usage | |
| 111 | +===================== | |
| 112 | + | |
| 113 | +unstriped ontop of Intel NVMe device that has 2 cores | |
| 114 | +----------------------------------------------------- | |
| 115 | + | |
| 116 | +:: | |
| 117 | + | |
| 118 | + dmsetup create nvmset0 --table '0 512 unstriped 2 256 0 /dev/nvme0n1 0' | |
| 119 | + dmsetup create nvmset1 --table '0 512 unstriped 2 256 1 /dev/nvme0n1 0' | |
| 120 | + | |
| 121 | +There will now be two devices that expose Intel NVMe core 0 and 1 | |
| 122 | +respectively:: | |
| 123 | + | |
| 124 | + /dev/mapper/nvmset0 | |
| 125 | + /dev/mapper/nvmset1 | |
| 126 | + | |
| 127 | +unstriped ontop of striped with 4 drives using 128K chunk size | |
| 128 | +-------------------------------------------------------------- | |
| 129 | + | |
| 130 | +:: | |
| 131 | + | |
| 132 | + dmsetup create raid_disk0 --table '0 512 unstriped 4 256 0 /dev/mapper/striped 0' | |
| 133 | + dmsetup create raid_disk1 --table '0 512 unstriped 4 256 1 /dev/mapper/striped 0' | |
| 134 | + dmsetup create raid_disk2 --table '0 512 unstriped 4 256 2 /dev/mapper/striped 0' | |
| 135 | + dmsetup create raid_disk3 --table '0 512 unstriped 4 256 3 /dev/mapper/striped 0' | |
| @@ -0,0 +1,229 @@ | ||
| 1 | +========= | |
| 2 | +dm-verity | |
| 3 | +========= | |
| 4 | + | |
| 5 | +Device-Mapper's "verity" target provides transparent integrity checking of | |
| 6 | +block devices using a cryptographic digest provided by the kernel crypto API. | |
| 7 | +This target is read-only. | |
| 8 | + | |
| 9 | +Construction Parameters | |
| 10 | +======================= | |
| 11 | + | |
| 12 | +:: | |
| 13 | + | |
| 14 | + <version> <dev> <hash_dev> | |
| 15 | + <data_block_size> <hash_block_size> | |
| 16 | + <num_data_blocks> <hash_start_block> | |
| 17 | + <algorithm> <digest> <salt> | |
| 18 | + [<#opt_params> <opt_params>] | |
| 19 | + | |
| 20 | +<version> | |
| 21 | + This is the type of the on-disk hash format. | |
| 22 | + | |
| 23 | + 0 is the original format used in the Chromium OS. | |
| 24 | + The salt is appended when hashing, digests are stored continuously and | |
| 25 | + the rest of the block is padded with zeroes. | |
| 26 | + | |
| 27 | + 1 is the current format that should be used for new devices. | |
| 28 | + The salt is prepended when hashing and each digest is | |
| 29 | + padded with zeroes to the power of two. | |
| 30 | + | |
| 31 | +<dev> | |
| 32 | + This is the device containing data, the integrity of which needs to be | |
| 33 | + checked. It may be specified as a path, like /dev/sdaX, or a device number, | |
| 34 | + <major>:<minor>. | |
| 35 | + | |
| 36 | +<hash_dev> | |
| 37 | + This is the device that supplies the hash tree data. It may be | |
| 38 | + specified similarly to the device path and may be the same device. If the | |
| 39 | + same device is used, the hash_start should be outside the configured | |
| 40 | + dm-verity device. | |
| 41 | + | |
| 42 | +<data_block_size> | |
| 43 | + The block size on a data device in bytes. | |
| 44 | + Each block corresponds to one digest on the hash device. | |
| 45 | + | |
| 46 | +<hash_block_size> | |
| 47 | + The size of a hash block in bytes. | |
| 48 | + | |
| 49 | +<num_data_blocks> | |
| 50 | + The number of data blocks on the data device. Additional blocks are | |
| 51 | + inaccessible. You can place hashes to the same partition as data, in this | |
| 52 | + case hashes are placed after <num_data_blocks>. | |
| 53 | + | |
| 54 | +<hash_start_block> | |
| 55 | + This is the offset, in <hash_block_size>-blocks, from the start of hash_dev | |
| 56 | + to the root block of the hash tree. | |
| 57 | + | |
| 58 | +<algorithm> | |
| 59 | + The cryptographic hash algorithm used for this device. This should | |
| 60 | + be the name of the algorithm, like "sha1". | |
| 61 | + | |
| 62 | +<digest> | |
| 63 | + The hexadecimal encoding of the cryptographic hash of the root hash block | |
| 64 | + and the salt. This hash should be trusted as there is no other authenticity | |
| 65 | + beyond this point. | |
| 66 | + | |
| 67 | +<salt> | |
| 68 | + The hexadecimal encoding of the salt value. | |
| 69 | + | |
| 70 | +<#opt_params> | |
| 71 | + Number of optional parameters. If there are no optional parameters, | |
| 72 | + the optional paramaters section can be skipped or #opt_params can be zero. | |
| 73 | + Otherwise #opt_params is the number of following arguments. | |
| 74 | + | |
| 75 | + Example of optional parameters section: | |
| 76 | + 1 ignore_corruption | |
| 77 | + | |
| 78 | +ignore_corruption | |
| 79 | + Log corrupted blocks, but allow read operations to proceed normally. | |
| 80 | + | |
| 81 | +restart_on_corruption | |
| 82 | + Restart the system when a corrupted block is discovered. This option is | |
| 83 | + not compatible with ignore_corruption and requires user space support to | |
| 84 | + avoid restart loops. | |
| 85 | + | |
| 86 | +ignore_zero_blocks | |
| 87 | + Do not verify blocks that are expected to contain zeroes and always return | |
| 88 | + zeroes instead. This may be useful if the partition contains unused blocks | |
| 89 | + that are not guaranteed to contain zeroes. | |
| 90 | + | |
| 91 | +use_fec_from_device <fec_dev> | |
| 92 | + Use forward error correction (FEC) to recover from corruption if hash | |
| 93 | + verification fails. Use encoding data from the specified device. This | |
| 94 | + may be the same device where data and hash blocks reside, in which case | |
| 95 | + fec_start must be outside data and hash areas. | |
| 96 | + | |
| 97 | + If the encoding data covers additional metadata, it must be accessible | |
| 98 | + on the hash device after the hash blocks. | |
| 99 | + | |
| 100 | + Note: block sizes for data and hash devices must match. Also, if the | |
| 101 | + verity <dev> is encrypted the <fec_dev> should be too. | |
| 102 | + | |
| 103 | +fec_roots <num> | |
| 104 | + Number of generator roots. This equals to the number of parity bytes in | |
| 105 | + the encoding data. For example, in RS(M, N) encoding, the number of roots | |
| 106 | + is M-N. | |
| 107 | + | |
| 108 | +fec_blocks <num> | |
| 109 | + The number of encoding data blocks on the FEC device. The block size for | |
| 110 | + the FEC device is <data_block_size>. | |
| 111 | + | |
| 112 | +fec_start <offset> | |
| 113 | + This is the offset, in <data_block_size> blocks, from the start of the | |
| 114 | + FEC device to the beginning of the encoding data. | |
| 115 | + | |
| 116 | +check_at_most_once | |
| 117 | + Verify data blocks only the first time they are read from the data device, | |
| 118 | + rather than every time. This reduces the overhead of dm-verity so that it | |
| 119 | + can be used on systems that are memory and/or CPU constrained. However, it | |
| 120 | + provides a reduced level of security because only offline tampering of the | |
| 121 | + data device's content will be detected, not online tampering. | |
| 122 | + | |
| 123 | + Hash blocks are still verified each time they are read from the hash device, | |
| 124 | + since verification of hash blocks is less performance critical than data | |
| 125 | + blocks, and a hash block will not be verified any more after all the data | |
| 126 | + blocks it covers have been verified anyway. | |
| 127 | + | |
| 128 | +Theory of operation | |
| 129 | +=================== | |
| 130 | + | |
| 131 | +dm-verity is meant to be set up as part of a verified boot path. This | |
| 132 | +may be anything ranging from a boot using tboot or trustedgrub to just | |
| 133 | +booting from a known-good device (like a USB drive or CD). | |
| 134 | + | |
| 135 | +When a dm-verity device is configured, it is expected that the caller | |
| 136 | +has been authenticated in some way (cryptographic signatures, etc). | |
| 137 | +After instantiation, all hashes will be verified on-demand during | |
| 138 | +disk access. If they cannot be verified up to the root node of the | |
| 139 | +tree, the root hash, then the I/O will fail. This should detect | |
| 140 | +tampering with any data on the device and the hash data. | |
| 141 | + | |
| 142 | +Cryptographic hashes are used to assert the integrity of the device on a | |
| 143 | +per-block basis. This allows for a lightweight hash computation on first read | |
| 144 | +into the page cache. Block hashes are stored linearly, aligned to the nearest | |
| 145 | +block size. | |
| 146 | + | |
| 147 | +If forward error correction (FEC) support is enabled any recovery of | |
| 148 | +corrupted data will be verified using the cryptographic hash of the | |
| 149 | +corresponding data. This is why combining error correction with | |
| 150 | +integrity checking is essential. | |
| 151 | + | |
| 152 | +Hash Tree | |
| 153 | +--------- | |
| 154 | + | |
| 155 | +Each node in the tree is a cryptographic hash. If it is a leaf node, the hash | |
| 156 | +of some data block on disk is calculated. If it is an intermediary node, | |
| 157 | +the hash of a number of child nodes is calculated. | |
| 158 | + | |
| 159 | +Each entry in the tree is a collection of neighboring nodes that fit in one | |
| 160 | +block. The number is determined based on block_size and the size of the | |
| 161 | +selected cryptographic digest algorithm. The hashes are linearly-ordered in | |
| 162 | +this entry and any unaligned trailing space is ignored but included when | |
| 163 | +calculating the parent node. | |
| 164 | + | |
| 165 | +The tree looks something like: | |
| 166 | + | |
| 167 | + alg = sha256, num_blocks = 32768, block_size = 4096 | |
| 168 | + | |
| 169 | +:: | |
| 170 | + | |
| 171 | + [ root ] | |
| 172 | + / . . . \ | |
| 173 | + [entry_0] [entry_1] | |
| 174 | + / . . . \ . . . \ | |
| 175 | + [entry_0_0] . . . [entry_0_127] . . . . [entry_1_127] | |
| 176 | + / ... \ / . . . \ / \ | |
| 177 | + blk_0 ... blk_127 blk_16256 blk_16383 blk_32640 . . . blk_32767 | |
| 178 | + | |
| 179 | + | |
| 180 | +On-disk format | |
| 181 | +============== | |
| 182 | + | |
| 183 | +The verity kernel code does not read the verity metadata on-disk header. | |
| 184 | +It only reads the hash blocks which directly follow the header. | |
| 185 | +It is expected that a user-space tool will verify the integrity of the | |
| 186 | +verity header. | |
| 187 | + | |
| 188 | +Alternatively, the header can be omitted and the dmsetup parameters can | |
| 189 | +be passed via the kernel command-line in a rooted chain of trust where | |
| 190 | +the command-line is verified. | |
| 191 | + | |
| 192 | +Directly following the header (and with sector number padded to the next hash | |
| 193 | +block boundary) are the hash blocks which are stored a depth at a time | |
| 194 | +(starting from the root), sorted in order of increasing index. | |
| 195 | + | |
| 196 | +The full specification of kernel parameters and on-disk metadata format | |
| 197 | +is available at the cryptsetup project's wiki page | |
| 198 | + | |
| 199 | + https://gitlab.com/cryptsetup/cryptsetup/wikis/DMVerity | |
| 200 | + | |
| 201 | +Status | |
| 202 | +====== | |
| 203 | +V (for Valid) is returned if every check performed so far was valid. | |
| 204 | +If any check failed, C (for Corruption) is returned. | |
| 205 | + | |
| 206 | +Example | |
| 207 | +======= | |
| 208 | +Set up a device:: | |
| 209 | + | |
| 210 | + # dmsetup create vroot --readonly --table \ | |
| 211 | + "0 2097152 verity 1 /dev/sda1 /dev/sda2 4096 4096 262144 1 sha256 "\ | |
| 212 | + "4392712ba01368efdf14b05c76f9e4df0d53664630b5d48632ed17a137f39076 "\ | |
| 213 | + "1234000000000000000000000000000000000000000000000000000000000000" | |
| 214 | + | |
| 215 | +A command line tool veritysetup is available to compute or verify | |
| 216 | +the hash tree or activate the kernel device. This is available from | |
| 217 | +the cryptsetup upstream repository https://gitlab.com/cryptsetup/cryptsetup/ | |
| 218 | +(as a libcryptsetup extension). | |
| 219 | + | |
| 220 | +Create hash on the device:: | |
| 221 | + | |
| 222 | + # veritysetup format /dev/sda1 /dev/sda2 | |
| 223 | + ... | |
| 224 | + Root hash: 4392712ba01368efdf14b05c76f9e4df0d53664630b5d48632ed17a137f39076 | |
| 225 | + | |
| 226 | +Activate the device:: | |
| 227 | + | |
| 228 | + # veritysetup create vroot /dev/sda1 /dev/sda2 \ | |
| 229 | + 4392712ba01368efdf14b05c76f9e4df0d53664630b5d48632ed17a137f39076 | |
| @@ -0,0 +1,79 @@ | ||
| 1 | +================= | |
| 2 | +Writecache target | |
| 3 | +================= | |
| 4 | + | |
| 5 | +The writecache target caches writes on persistent memory or on SSD. It | |
| 6 | +doesn't cache reads because reads are supposed to be cached in page cache | |
| 7 | +in normal RAM. | |
| 8 | + | |
| 9 | +When the device is constructed, the first sector should be zeroed or the | |
| 10 | +first sector should contain valid superblock from previous invocation. | |
| 11 | + | |
| 12 | +Constructor parameters: | |
| 13 | + | |
| 14 | +1. type of the cache device - "p" or "s" | |
| 15 | + | |
| 16 | + - p - persistent memory | |
| 17 | + - s - SSD | |
| 18 | +2. the underlying device that will be cached | |
| 19 | +3. the cache device | |
| 20 | +4. block size (4096 is recommended; the maximum block size is the page | |
| 21 | + size) | |
| 22 | +5. the number of optional parameters (the parameters with an argument | |
| 23 | + count as two) | |
| 24 | + | |
| 25 | + start_sector n (default: 0) | |
| 26 | + offset from the start of cache device in 512-byte sectors | |
| 27 | + high_watermark n (default: 50) | |
| 28 | + start writeback when the number of used blocks reach this | |
| 29 | + watermark | |
| 30 | + low_watermark x (default: 45) | |
| 31 | + stop writeback when the number of used blocks drops below | |
| 32 | + this watermark | |
| 33 | + writeback_jobs n (default: unlimited) | |
| 34 | + limit the number of blocks that are in flight during | |
| 35 | + writeback. Setting this value reduces writeback | |
| 36 | + throughput, but it may improve latency of read requests | |
| 37 | + autocommit_blocks n (default: 64 for pmem, 65536 for ssd) | |
| 38 | + when the application writes this amount of blocks without | |
| 39 | + issuing the FLUSH request, the blocks are automatically | |
| 40 | + commited | |
| 41 | + autocommit_time ms (default: 1000) | |
| 42 | + autocommit time in milliseconds. The data is automatically | |
| 43 | + commited if this time passes and no FLUSH request is | |
| 44 | + received | |
| 45 | + fua (by default on) | |
| 46 | + applicable only to persistent memory - use the FUA flag | |
| 47 | + when writing data from persistent memory back to the | |
| 48 | + underlying device | |
| 49 | + nofua | |
| 50 | + applicable only to persistent memory - don't use the FUA | |
| 51 | + flag when writing back data and send the FLUSH request | |
| 52 | + afterwards | |
| 53 | + | |
| 54 | + - some underlying devices perform better with fua, some | |
| 55 | + with nofua. The user should test it | |
| 56 | + | |
| 57 | +Status: | |
| 58 | +1. error indicator - 0 if there was no error, otherwise error number | |
| 59 | +2. the number of blocks | |
| 60 | +3. the number of free blocks | |
| 61 | +4. the number of blocks under writeback | |
| 62 | + | |
| 63 | +Messages: | |
| 64 | + flush | |
| 65 | + flush the cache device. The message returns successfully | |
| 66 | + if the cache device was flushed without an error | |
| 67 | + flush_on_suspend | |
| 68 | + flush the cache device on next suspend. Use this message | |
| 69 | + when you are going to remove the cache device. The proper | |
| 70 | + sequence for removing the cache device is: | |
| 71 | + | |
| 72 | + 1. send the "flush_on_suspend" message | |
| 73 | + 2. load an inactive table with a linear target that maps | |
| 74 | + to the underlying device | |
| 75 | + 3. suspend the device | |
| 76 | + 4. ask for status and verify that there are no errors | |
| 77 | + 5. resume the device, so that it will use the linear | |
| 78 | + target | |
| 79 | + 6. the cache device is now inactive and it can be deleted | |
| @@ -0,0 +1,37 @@ | ||
| 1 | +======= | |
| 2 | +dm-zero | |
| 3 | +======= | |
| 4 | + | |
33 more lines aren’t shown here.
This diff is large: its 11 lines aren’t shown here.
File renamed without changes.
This diff is large: its 18 lines aren’t shown here.
File renamed without changes.
File renamed without changes.
This diff is large: its 7 lines aren’t shown here.
This diff is large: its 9 lines aren’t shown here.
This diff is large: its 698 lines aren’t shown here.
File renamed without changes.
This diff is large: its 70 lines aren’t shown here.
This diff is large: its 198 lines aren’t shown here.
File renamed without changes.
This diff is large: its 21 lines aren’t shown here.
This diff is large: its 535 lines aren’t shown here.
This diff is large: its 489 lines aren’t shown here.
This diff is large: its 45 lines aren’t shown here.
This diff is large: its 504 lines aren’t shown here.
This diff is large: its 357 lines aren’t shown here.
This diff is large: its 272 lines aren’t shown here.
This diff is large: its 152 lines aren’t shown here.
This diff is large: its 18 lines aren’t shown here.
This diff is large: its 782 lines aren’t shown here.
This diff is large: its 7 lines aren’t shown here.
This diff is large: its 175 lines aren’t shown here.
This diff is large: its 159 lines aren’t shown here.
This diff is large: its 1563 lines aren’t shown here.
This diff is large: its 88 lines aren’t shown here.
This diff is large: its 28 lines aren’t shown here.
File renamed without changes.
File renamed without changes.
This diff is large: its 26 lines aren’t shown here.
This diff is large: its 17 lines aren’t shown here.
This diff is large: its 9 lines aren’t shown here.
This diff is large: its 9 lines aren’t shown here.
This diff is large: its 9 lines aren’t shown here.
This diff is large: its 9 lines aren’t shown here.
This diff is large: its 44 lines aren’t shown here.
This diff is large: its 12 lines aren’t shown here.
This diff is large: its 19 lines aren’t shown here.
File renamed without changes.
This diff is large: its 62 lines aren’t shown here.
This diff is large: its 30 lines aren’t shown here.
This diff is large: its 61 lines aren’t shown here.
This diff is large: its 17 lines aren’t shown here.
This diff is large: its 40 lines aren’t shown here.
This diff is large: its 27 lines aren’t shown here.
This diff is large: its 43 lines aren’t shown here.
This diff is large: its 50 lines aren’t shown here.
File renamed without changes.
File renamed without changes.
This diff is large: its 9 lines aren’t shown here.
File renamed without changes.
File renamed without changes.
This diff is large: its 68 lines aren’t shown here.
This diff is large: its 385 lines aren’t shown here.
This diff is large: its 99 lines aren’t shown here.
This diff is large: its 1178 lines aren’t shown here.
This diff is large: its 462 lines aren’t shown here.
This diff is large: its 26 lines aren’t shown here.
This diff is large: its 79 lines aren’t shown here.
This diff is large: its 965 lines aren’t shown here.
File renamed without changes.
This diff is large: its 467 lines aren’t shown here.
This diff is large: its 144 lines aren’t shown here.
This diff is large: its 15 lines aren’t shown here.
This diff is large: its 219 lines aren’t shown here.
This diff is large: its 173 lines aren’t shown here.
This diff is large: its 168 lines aren’t shown here.
This diff is large: its 396 lines aren’t shown here.
This diff is large: its 170 lines aren’t shown here.
This diff is large: its 79 lines aren’t shown here.
This diff is large: its 363 lines aren’t shown here.
This diff is large: its 12 lines aren’t shown here.
This diff is large: its 155 lines aren’t shown here.
This diff is large: its 136 lines aren’t shown here.
This diff is large: its 205 lines aren’t shown here.
This diff is large: its 44 lines aren’t shown here.
This diff is large: its 301 lines aren’t shown here.
This diff is large: its 67 lines aren’t shown here.
This diff is large: its 30 lines aren’t shown here.
This diff is large: its 22 lines aren’t shown here.
This diff is large: its 99 lines aren’t shown here.
This diff is large: its 54 lines aren’t shown here.
This diff is large: its 18 lines aren’t shown here.
This diff is large: its 40 lines aren’t shown here.
This diff is large: its 15 lines aren’t shown here.
This diff is large: its 12 lines aren’t shown here.
This diff is large: its 24 lines aren’t shown here.
This diff is large: its 8 lines aren’t shown here.
This diff is large: its 3 lines aren’t shown here.
This diff is large: its 3 lines aren’t shown here.
This diff is large: its 12 lines aren’t shown here.
This diff is large: its 48 lines aren’t shown here.
This diff is large: its 64 lines aren’t shown here.
This diff is large: its 76 lines aren’t shown here.
This diff is large: its 59 lines aren’t shown here.
This diff is large: its 172 lines aren’t shown here.
This diff is large: its 41 lines aren’t shown here.
This diff is large: its 31 lines aren’t shown here.
This diff is large: its 319 lines aren’t shown here.
This diff is large: its 121 lines aren’t shown here.
This diff is large: its 22 lines aren’t shown here.
This diff is large: its 57 lines aren’t shown here.
This diff is large: its 138 lines aren’t shown here.
This diff is large: its 94 lines aren’t shown here.
This diff is large: its 69 lines aren’t shown here.
This diff is large: its 41 lines aren’t shown here.
This diff is large: its 87 lines aren’t shown here.
This diff is large: its 130 lines aren’t shown here.
This diff is large: its 56 lines aren’t shown here.
This diff is large: its 215 lines aren’t shown here.
This diff is large: its 238 lines aren’t shown here.
This diff is large: its 534 lines aren’t shown here.
This diff is large: its 499 lines aren’t shown here.
This diff is large: its 73 lines aren’t shown here.
This diff is large: its 71 lines aren’t shown here.
This diff is large: its 81 lines aren’t shown here.
This diff is large: its 170 lines aren’t shown here.
This diff is large: its 174 lines aren’t shown here.
This diff is large: its 125 lines aren’t shown here.
This diff is large: its 122 lines aren’t shown here.
This diff is large: its 269 lines aren’t shown here.
This diff is large: its 268 lines aren’t shown here.
This diff is large: its 56 lines aren’t shown here.
This diff is large: its 61 lines aren’t shown here.
This diff is large: its 57 lines aren’t shown here.
This diff is large: its 75 lines aren’t shown here.
This diff is large: its 489 lines aren’t shown here.
This diff is large: its 59 lines aren’t shown here.
This diff is large: its 64 lines aren’t shown here.
This diff is large: its 94 lines aren’t shown here.
This diff is large: its 89 lines aren’t shown here.
This diff is large: its 205 lines aren’t shown here.
This diff is large: its 86 lines aren’t shown here.
This diff is large: its 30 lines aren’t shown here.
This diff is large: its 71 lines aren’t shown here.
This diff is large: its 157 lines aren’t shown here.
This diff is large: its 68 lines aren’t shown here.
This diff is large: its 14 lines aren’t shown here.
This diff is large: its 163 lines aren’t shown here.
This diff is large: its 33 lines aren’t shown here.
This diff is large: its 75 lines aren’t shown here.
This diff is large: its 73 lines aren’t shown here.
This diff is large: its 373 lines aren’t shown here.
This diff is large: its 13 lines aren’t shown here.
This diff is large: its 19 lines aren’t shown here.
This diff is large: its 166 lines aren’t shown here.
This diff is large: its 138 lines aren’t shown here.
This diff is large: its 289 lines aren’t shown here.
This diff is large: its 287 lines aren’t shown here.
This diff is large: its 52 lines aren’t shown here.
This diff is large: its 302 lines aren’t shown here.
This diff is large: its 70 lines aren’t shown here.
This diff is large: its 36 lines aren’t shown here.
This diff is large: its 26 lines aren’t shown here.
This diff is large: its 103 lines aren’t shown here.
This diff is large: its 61 lines aren’t shown here.
This diff is large: its 22 lines aren’t shown here.
This diff is large: its 26 lines aren’t shown here.
This diff is large: its 48 lines aren’t shown here.
This diff is large: its 16 lines aren’t shown here.
This diff is large: its 12 lines aren’t shown here.
This diff is large: its 30 lines aren’t shown here.
This diff is large: its 14 lines aren’t shown here.
This diff is large: its 52 lines aren’t shown here.
This diff is large: its 8 lines aren’t shown here.
This diff is large: its 6 lines aren’t shown here.
This diff is large: its 77 lines aren’t shown here.
This diff is large: its 60 lines aren’t shown here.
This diff is large: its 173 lines aren’t shown here.
This diff is large: its 42 lines aren’t shown here.
This diff is large: its 21 lines aren’t shown here.
This diff is large: its 31 lines aren’t shown here.
This diff is large: its 320 lines aren’t shown here.
This diff is large: its 122 lines aren’t shown here.
This diff is large: its 23 lines aren’t shown here.
This diff is large: its 58 lines aren’t shown here.
This diff is large: its 138 lines aren’t shown here.
This diff is large: its 92 lines aren’t shown here.
This diff is large: its 82 lines aren’t shown here.
File renamed without changes.
This diff is large: its 42 lines aren’t shown here.
This diff is large: its 13 lines aren’t shown here.
This diff is large: its 90 lines aren’t shown here.
This diff is large: its 109 lines aren’t shown here.
File renamed without changes.
This diff is large: its 67 lines aren’t shown here.
This diff is large: its 37 lines aren’t shown here.
This diff is large: its 34 lines aren’t shown here.
This diff is large: its 20 lines aren’t shown here.
This diff is large: its 19 lines aren’t shown here.
This diff is large: its 15 lines aren’t shown here.
This diff is large: its 13 lines aren’t shown here.
This diff is large: its 14 lines aren’t shown here.
This diff is large: its 13 lines aren’t shown here.
This diff is large: its 22 lines aren’t shown here.
This diff is large: its 21 lines aren’t shown here.
This diff is large: its 13 lines aren’t shown here.
This diff is large: its 13 lines aren’t shown here.
This diff is large: its 13 lines aren’t shown here.
This diff is large: its 13 lines aren’t shown here.
This diff is large: its 5 lines aren’t shown here.
This diff is large: its 151 lines aren’t shown here.
This diff is large: its 103 lines aren’t shown here.
This diff is large: its 58 lines aren’t shown here.
This diff is large: its 57 lines aren’t shown here.
This diff is large: its 28 lines aren’t shown here.
This diff is large: its 28 lines aren’t shown here.
This diff is large: its 162 lines aren’t shown here.
This diff is large: its 156 lines aren’t shown here.
This diff is large: its 68 lines aren’t shown here.
This diff is large: its 61 lines aren’t shown here.
This diff is large: its 58 lines aren’t shown here.
This diff is large: its 213 lines aren’t shown here.
This diff is large: its 212 lines aren’t shown here.
This diff is large: its 739 lines aren’t shown here.
This diff is large: its 623 lines aren’t shown here.
This diff is large: its 529 lines aren’t shown here.
This diff is large: its 520 lines aren’t shown here.
This diff is large: its 294 lines aren’t shown here.
This diff is large: its 267 lines aren’t shown here.
This diff is large: its 305 lines aren’t shown here.
This diff is large: its 297 lines aren’t shown here.
This diff is large: its 210 lines aren’t shown here.
This diff is large: its 232 lines aren’t shown here.
This diff is large: its 42 lines aren’t shown here.
This diff is large: its 39 lines aren’t shown here.
This diff is large: its 27 lines aren’t shown here.
This diff is large: its 69 lines aren’t shown here.
This diff is large: its 58 lines aren’t shown here.
This diff is large: its 99 lines aren’t shown here.
This diff is large: its 98 lines aren’t shown here.
This diff is large: its 110 lines aren’t shown here.
This diff is large: its 108 lines aren’t shown here.
This diff is large: its 134 lines aren’t shown here.
This diff is large: its 89 lines aren’t shown here.
This diff is large: its 546 lines aren’t shown here.
This diff is large: its 542 lines aren’t shown here.
This diff is large: its 69 lines aren’t shown here.
This diff is large: its 67 lines aren’t shown here.
This diff is large: its 60 lines aren’t shown here.
This diff is large: its 25 lines aren’t shown here.
This diff is large: its 67 lines aren’t shown here.
This diff is large: its 598 lines aren’t shown here.
This diff is large: its 584 lines aren’t shown here.
This diff is large: its 1165 lines aren’t shown here.
This diff is large: its 1078 lines aren’t shown here.
This diff is large: its 147 lines aren’t shown here.
This diff is large: its 145 lines aren’t shown here.
This diff is large: its 19 lines aren’t shown here.
This diff is large: its 16 lines aren’t shown here.
This diff is large: its 54 lines aren’t shown here.
This diff is large: its 47 lines aren’t shown here.
This diff is large: its 292 lines aren’t shown here.
This diff is large: its 282 lines aren’t shown here.
This diff is large: its 73 lines aren’t shown here.
This diff is large: its 76 lines aren’t shown here.
This diff is large: its 26 lines aren’t shown here.
This diff is large: its 183 lines aren’t shown here.
This diff is large: its 184 lines aren’t shown here.
This diff is large: its 16 lines aren’t shown here.
This diff is large: its 15 lines aren’t shown here.
This diff is large: its 127 lines aren’t shown here.
This diff is large: its 100 lines aren’t shown here.
This diff is large: its 120 lines aren’t shown here.
This diff is large: its 120 lines aren’t shown here.
This diff is large: its 255 lines aren’t shown here.
This diff is large: its 232 lines aren’t shown here.
This diff is large: its 100 lines aren’t shown here.
This diff is large: its 89 lines aren’t shown here.
This diff is large: its 94 lines aren’t shown here.
This diff is large: its 87 lines aren’t shown here.
This diff is large: its 40 lines aren’t shown here.
This diff is large: its 36 lines aren’t shown here.
This diff is large: its 87 lines aren’t shown here.
This diff is large: its 87 lines aren’t shown here.
This diff is large: its 17 lines aren’t shown here.
This diff is large: its 39 lines aren’t shown here.
This diff is large: its 246 lines aren’t shown here.
This diff is large: its 32 lines aren’t shown here.
This diff is large: its 418 lines aren’t shown here.
This diff is large: its 175 lines aren’t shown here.
This diff is large: its 356 lines aren’t shown here.
This diff is large: its 37 lines aren’t shown here.
This diff is large: its 16 lines aren’t shown here.
This diff is large: its 8 lines aren’t shown here.
This diff is large: its 94 lines aren’t shown here.
This diff is large: its 123 lines aren’t shown here.
This diff is large: its 22 lines aren’t shown here.
This diff is large: its 1064 lines aren’t shown here.
This diff is large: its 1027 lines aren’t shown here.
This diff is large: its 535 lines aren’t shown here.
This diff is large: its 539 lines aren’t shown here.
This diff is large: its 20 lines aren’t shown here.
This diff is large: its 140 lines aren’t shown here.
This diff is large: its 133 lines aren’t shown here.
This diff is large: its 294 lines aren’t shown here.
This diff is large: its 678 lines aren’t shown here.
This diff is large: its 50 lines aren’t shown here.
This diff is large: its 840 lines aren’t shown here.
This diff is large: its 117 lines aren’t shown here.
This diff is large: its 124 lines aren’t shown here.
This diff is large: its 50 lines aren’t shown here.
This diff is large: its 281 lines aren’t shown here.
This diff is large: its 893 lines aren’t shown here.
This diff is large: its 40 lines aren’t shown here.
This diff is large: its 56 lines aren’t shown here.
This diff is large: its 89 lines aren’t shown here.
This diff is large: its 110 lines aren’t shown here.
This diff is large: its 22 lines aren’t shown here.
This diff is large: its 73 lines aren’t shown here.
This diff is large: its 197 lines aren’t shown here.
This diff is large: its 146 lines aren’t shown here.
This diff is large: its 9 lines aren’t shown here.
This diff is large: its 11 lines aren’t shown here.
File renamed without changes.
This diff is large: its 10 lines aren’t shown here.
This diff is large: its 44 lines aren’t shown here.
This diff is large: its 9 lines aren’t shown here.
File renamed without changes.
This diff is large: its 37 lines aren’t shown here.
This diff is large: its 507 lines aren’t shown here.
This diff is large: its 9 lines aren’t shown here.
This diff is large: its 160 lines aren’t shown here.
This diff is large: its 189 lines aren’t shown here.
This diff is large: its 9 lines aren’t shown here.
This diff is large: its 11 lines aren’t shown here.
This diff is large: its 11 lines aren’t shown here.
This diff is large: its 124 lines aren’t shown here.
This diff is large: its 11 lines aren’t shown here.
This diff is large: its 75 lines aren’t shown here.
This diff is large: its 12 lines aren’t shown here.
This diff is large: its 122 lines aren’t shown here.
This diff is large: its 312 lines aren’t shown here.
This diff is large: its 29 lines aren’t shown here.
This diff is large: its 163 lines aren’t shown here.
This diff is large: its 58 lines aren’t shown here.
This diff is large: its 115 lines aren’t shown here.
This diff is large: its 234 lines aren’t shown here.
This diff is large: its 76 lines aren’t shown here.
This diff is large: its 55 lines aren’t shown here.
This diff is large: its 40 lines aren’t shown here.
This diff is large: its 355 lines aren’t shown here.
This diff is large: its 92 lines aren’t shown here.
This diff is large: its 98 lines aren’t shown here.
This diff is large: its 145 lines aren’t shown here.
This diff is large: its 109 lines aren’t shown here.
This diff is large: its 48 lines aren’t shown here.
This diff is large: its 62 lines aren’t shown here.
This diff is large: its 141 lines aren’t shown here.
This diff is large: its 85 lines aren’t shown here.
This diff is large: its 177 lines aren’t shown here.
This diff is large: its 224 lines aren’t shown here.
This diff is large: its 58 lines aren’t shown here.
This diff is large: its 139 lines aren’t shown here.
This diff is large: its 412 lines aren’t shown here.
This diff is large: its 125 lines aren’t shown here.
This diff is large: its 220 lines aren’t shown here.
This diff is large: its 71 lines aren’t shown here.
This diff is large: its 38 lines aren’t shown here.
This diff is large: its 9 lines aren’t shown here.
This diff is large: its 17 lines aren’t shown here.
This diff is large: its 22 lines aren’t shown here.
This diff is large: its 143 lines aren’t shown here.
This diff is large: its 145 lines aren’t shown here.
This diff is large: its 29 lines aren’t shown here.
This diff is large: its 9 lines aren’t shown here.
This diff is large: its 9 lines aren’t shown here.
This diff is large: its 74 lines aren’t shown here.
This diff is large: its 135 lines aren’t shown here.
This diff is large: its 13 lines aren’t shown here.
This diff is large: its 20 lines aren’t shown here.
This diff is large: its 11 lines aren’t shown here.
This diff is large: its 22 lines aren’t shown here.
This diff is large: its 506 lines aren’t shown here.
This diff is large: its 7 lines aren’t shown here.
This diff is large: its 17 lines aren’t shown here.
This diff is large: its 13 lines aren’t shown here.
This diff is large: its 58 lines aren’t shown here.
This diff is large: its 92 lines aren’t shown here.
This diff is large: its 33 lines aren’t shown here.
This diff is large: its 90 lines aren’t shown here.
This diff is large: its 92 lines aren’t shown here.
This diff is large: its 8 lines aren’t shown here.
This diff is large: its 9 lines aren’t shown here.
This diff is large: its 13 lines aren’t shown here.
This diff is large: its 20 lines aren’t shown here.
This diff is large: its 9 lines aren’t shown here.
This diff is large: its 26 lines aren’t shown here.
This diff is large: its 10 lines aren’t shown here.
This diff is large: its 112 lines aren’t shown here.
This diff is large: its 164 lines aren’t shown here.
This diff is large: its 28 lines aren’t shown here.
This diff is large: its 18 lines aren’t shown here.
This diff is large: its 21 lines aren’t shown here.
This diff is large: its 24 lines aren’t shown here.
This diff is large: its 20 lines aren’t shown here.
This diff is large: its 9 lines aren’t shown here.
This diff is large: its 38 lines aren’t shown here.
This diff is large: its 11 lines aren’t shown here.
This diff is large: its 32 lines aren’t shown here.
This diff is large: its 9 lines aren’t shown here.
This diff is large: its 10 lines aren’t shown here.
This diff is large: its 9 lines aren’t shown here.
This diff is large: its 9 lines aren’t shown here.
This diff is large: its 81 lines aren’t shown here.
This diff is large: its 48 lines aren’t shown here.
This diff is large: its 142 lines aren’t shown here.
This diff is large: its 8 lines aren’t shown here.
This diff is large: its 15 lines aren’t shown here.
This diff is large: its 23 lines aren’t shown here.
This diff is large: its 8 lines aren’t shown here.
This diff is large: its 8 lines aren’t shown here.
This diff is large: its 17 lines aren’t shown here.
This diff is large: its 26 lines aren’t shown here.
This diff is large: its 163 lines aren’t shown here.
This diff is large: its 63 lines aren’t shown here.
This diff is large: its 39 lines aren’t shown here.
This diff is large: its 38 lines aren’t shown here.
This diff is large: its 17 lines aren’t shown here.
This diff is large: its 39 lines aren’t shown here.
This diff is large: its 14 lines aren’t shown here.
This diff is large: its 24 lines aren’t shown here.
This diff is large: its 8 lines aren’t shown here.
This diff is large: its 39 lines aren’t shown here.
This diff is large: its 34 lines aren’t shown here.
This diff is large: its 10 lines aren’t shown here.
This diff is large: its 78 lines aren’t shown here.
This diff is large: its 8 lines aren’t shown here.
This diff is large: its 55 lines aren’t shown here.
This diff is large: its 20 lines aren’t shown here.
This diff is large: its 20 lines aren’t shown here.
This diff is large: its 9 lines aren’t shown here.
This diff is large: its 29 lines aren’t shown here.
This diff is large: its 11 lines aren’t shown here.
This diff is large: its 70 lines aren’t shown here.
This diff is large: its 8 lines aren’t shown here.
This diff is large: its 8 lines aren’t shown here.
This diff is large: its 44 lines aren’t shown here.
This diff is large: its 66 lines aren’t shown here.
This diff is large: its 26 lines aren’t shown here.
This diff is large: its 65 lines aren’t shown here.
This diff is large: its 24 lines aren’t shown here.
This diff is large: its 8 lines aren’t shown here.
This diff is large: its 9 lines aren’t shown here.
This diff is large: its 42 lines aren’t shown here.
This diff is large: its 125 lines aren’t shown here.
This diff is large: its 8 lines aren’t shown here.
This diff is large: its 11 lines aren’t shown here.
This diff is large: its 73 lines aren’t shown here.
This diff is large: its 64 lines aren’t shown here.
This diff is large: its 40 lines aren’t shown here.
This diff is large: its 34 lines aren’t shown here.
This diff is large: its 76 lines aren’t shown here.
This diff is large: its 161 lines aren’t shown here.
This diff is large: its 49 lines aren’t shown here.
This diff is large: its 88 lines aren’t shown here.
This diff is large: its 8 lines aren’t shown here.
This diff is large: its 11 lines aren’t shown here.
This diff is large: its 8 lines aren’t shown here.
This diff is large: its 13 lines aren’t shown here.
This diff is large: its 40 lines aren’t shown here.
This diff is large: its 64 lines aren’t shown here.
This diff is large: its 28 lines aren’t shown here.
This diff is large: its 57 lines aren’t shown here.
This diff is large: its 26 lines aren’t shown here.
This diff is large: its 47 lines aren’t shown here.
This diff is large: its 43 lines aren’t shown here.
This diff is large: its 84 lines aren’t shown here.
This diff is large: its 21 lines aren’t shown here.
This diff is large: its 8 lines aren’t shown here.
This diff is large: its 28 lines aren’t shown here.
This diff is large: its 8 lines aren’t shown here.
This diff is large: its 44 lines aren’t shown here.
This diff is large: its 9 lines aren’t shown here.
This diff is large: its 44 lines aren’t shown here.
This diff is large: its 6 lines aren’t shown here.
This diff is large: its 46 lines aren’t shown here.
This diff is large: its 86 lines aren’t shown here.
This diff is large: its 74 lines aren’t shown here.
This diff is large: its 45 lines aren’t shown here.
This diff is large: its 116 lines aren’t shown here.
This diff is large: its 44 lines aren’t shown here.
This diff is large: its 72 lines aren’t shown here.
This diff is large: its 23 lines aren’t shown here.
This diff is large: its 51 lines aren’t shown here.
This diff is large: its 9 lines aren’t shown here.
This diff is large: its 8 lines aren’t shown here.
This diff is large: its 8 lines aren’t shown here.
This diff is large: its 39 lines aren’t shown here.
This diff is large: its 19 lines aren’t shown here.
This diff is large: its 40 lines aren’t shown here.
This diff is large: its 33 lines aren’t shown here.
This diff is large: its 77 lines aren’t shown here.
This diff is large: its 103 lines aren’t shown here.
This diff is large: its 24 lines aren’t shown here.
This diff is large: its 154 lines aren’t shown here.
This diff is large: its 12 lines aren’t shown here.
This diff is large: its 50 lines aren’t shown here.
This diff is large: its 50 lines aren’t shown here.
This diff is large: its 24 lines aren’t shown here.
This diff is large: its 59 lines aren’t shown here.
This diff is large: its 99 lines aren’t shown here.
This diff is large: its 11 lines aren’t shown here.
This diff is large: its 375 lines aren’t shown here.
This diff is large: its 179 lines aren’t shown here.
This diff is large: its 112 lines aren’t shown here.
This diff is large: its 26 lines aren’t shown here.
This diff is large: its 44 lines aren’t shown here.
This diff is large: its 53 lines aren’t shown here.
This diff is large: its 121 lines aren’t shown here.
This diff is large: its 11 lines aren’t shown here.
This diff is large: its 21 lines aren’t shown here.
This diff is large: its 19 lines aren’t shown here.
This diff is large: its 14 lines aren’t shown here.
This diff is large: its 8 lines aren’t shown here.
This diff is large: its 44 lines aren’t shown here.
This diff is large: its 52 lines aren’t shown here.
This diff is large: its 61 lines aren’t shown here.
This diff is large: its 130 lines aren’t shown here.
This diff is large: its 57 lines aren’t shown here.
This diff is large: its 71 lines aren’t shown here.
This diff is large: its 20 lines aren’t shown here.
This diff is large: its 28 lines aren’t shown here.
This diff is large: its 28 lines aren’t shown here.
This diff is large: its 66 lines aren’t shown here.
This diff is large: its 322 lines aren’t shown here.
This diff is large: its 8 lines aren’t shown here.
This diff is large: its 34 lines aren’t shown here.
This diff is large: its 35 lines aren’t shown here.
This diff is large: its 9 lines aren’t shown here.
This diff is large: its 16 lines aren’t shown here.
This diff is large: its 27 lines aren’t shown here.
This diff is large: its 83 lines aren’t shown here.
This diff is large: its 202 lines aren’t shown here.
This diff is large: its 207 lines aren’t shown here.
This diff is large: its 178 lines aren’t shown here.
This diff is large: its 69 lines aren’t shown here.
This diff is large: its 56 lines aren’t shown here.
This diff is large: its 21 lines aren’t shown here.
This diff is large: its 34 lines aren’t shown here.
This diff is large: its 62 lines aren’t shown here.
This diff is large: its 12 lines aren’t shown here.
This diff is large: its 26 lines aren’t shown here.
This diff is large: its 9 lines aren’t shown here.
This diff is large: its 39 lines aren’t shown here.
This diff is large: its 75 lines aren’t shown here.
This diff is large: its 34 lines aren’t shown here.
This diff is large: its 34 lines aren’t shown here.
This diff is large: its 81 lines aren’t shown here.
This diff is large: its 46 lines aren’t shown here.
This diff is large: its 31 lines aren’t shown here.
This diff is large: its 412 lines aren’t shown here.
This diff is large: its 20 lines aren’t shown here.
This diff is large: its 180 lines aren’t shown here.
This diff is large: its 28 lines aren’t shown here.
This diff is large: its 51 lines aren’t shown here.
This diff is large: its 50 lines aren’t shown here.
This diff is large: its 52 lines aren’t shown here.
This diff is large: its 30 lines aren’t shown here.
This diff is large: its 8 lines aren’t shown here.
This diff is large: its 46 lines aren’t shown here.
This diff is large: its 82 lines aren’t shown here.
This diff is large: its 94 lines aren’t shown here.
This diff is large: its 8 lines aren’t shown here.
This diff is large: its 9 lines aren’t shown here.
This diff is large: its 11 lines aren’t shown here.
This diff is large: its 15 lines aren’t shown here.
This diff is large: its 10 lines aren’t shown here.
This diff is large: its 57 lines aren’t shown here.
This diff is large: its 8 lines aren’t shown here.
This diff is large: its 22 lines aren’t shown here.
This diff is large: its 9 lines aren’t shown here.
This diff is large: its 30 lines aren’t shown here.
This diff is large: its 17 lines aren’t shown here.
This diff is large: its 19 lines aren’t shown here.
This diff is large: its 7 lines aren’t shown here.
This diff is large: its 19 lines aren’t shown here.
This diff is large: its 43 lines aren’t shown here.
This diff is large: its 36 lines aren’t shown here.
This diff is large: its 9 lines aren’t shown here.
This diff is large: its 84 lines aren’t shown here.
This diff is large: its 134 lines aren’t shown here.
This diff is large: its 50 lines aren’t shown here.
This diff is large: its 10 lines aren’t shown here.
This diff is large: its 9 lines aren’t shown here.
This diff is large: its 40 lines aren’t shown here.
This diff is large: its 55 lines aren’t shown here.
This diff is large: its 23 lines aren’t shown here.
This diff is large: its 9 lines aren’t shown here.
This diff is large: its 6 lines aren’t shown here.
This diff is large: its 108 lines aren’t shown here.
This diff is large: its 173 lines aren’t shown here.
This diff is large: its 17 lines aren’t shown here.
This diff is large: its 21 lines aren’t shown here.
This diff is large: its 21 lines aren’t shown here.
This diff is large: its 21 lines aren’t shown here.
This diff is large: its 21 lines aren’t shown here.
This diff is large: its 21 lines aren’t shown here.
This diff is large: its 21 lines aren’t shown here.
This diff is large: its 21 lines aren’t shown here.
This diff is large: its 45 lines aren’t shown here.
This diff is large: its 21 lines aren’t shown here.
This diff is large: its 21 lines aren’t shown here.
This diff is large: its 30 lines aren’t shown here.
This diff is large: its 191 lines aren’t shown here.
This diff is large: its 209 lines aren’t shown here.
This diff is large: its 272 lines aren’t shown here.
This diff is large: its 9 lines aren’t shown here.
This diff is large: its 27 lines aren’t shown here.
This diff is large: its 8 lines aren’t shown here.
This diff is large: its 50 lines aren’t shown here.
This diff is large: its 9 lines aren’t shown here.
This diff is large: its 58 lines aren’t shown here.
This diff is large: its 12 lines aren’t shown here.
This diff is large: its 34 lines aren’t shown here.
This diff is large: its 23 lines aren’t shown here.
This diff is large: its 17 lines aren’t shown here.
This diff is large: its 25 lines aren’t shown here.
This diff is large: its 10 lines aren’t shown here.
This diff is large: its 15 lines aren’t shown here.
This diff is large: its 58 lines aren’t shown here.
This diff is large: its 119 lines aren’t shown here.
This diff is large: its 48 lines aren’t shown here.
This diff is large: its 78 lines aren’t shown here.
This diff is large: its 6 lines aren’t shown here.
This diff is large: its 9 lines aren’t shown here.
This diff is large: its 48 lines aren’t shown here.
This diff is large: its 141 lines aren’t shown here.
This diff is large: its 201 lines aren’t shown here.
This diff is large: its 89 lines aren’t shown here.
This diff is large: its 19 lines aren’t shown here.
This diff is large: its 126 lines aren’t shown here.
This diff is large: its 141 lines aren’t shown here.
This diff is large: its 64 lines aren’t shown here.
This diff is large: its 19 lines aren’t shown here.
This diff is large: its 8 lines aren’t shown here.
This diff is large: its 150 lines aren’t shown here.
This diff is large: its 26 lines aren’t shown here.
This diff is large: its 8 lines aren’t shown here.
This diff is large: its 44 lines aren’t shown here.
This diff is large: its 135 lines aren’t shown here.
This diff is large: its 74 lines aren’t shown here.
This diff is large: its 51 lines aren’t shown here.
This diff is large: its 47 lines aren’t shown here.
This diff is large: its 18 lines aren’t shown here.
This diff is large: its 93 lines aren’t shown here.
This diff is large: its 30 lines aren’t shown here.
This diff is large: its 27 lines aren’t shown here.
This diff is large: its 8 lines aren’t shown here.
This diff is large: its 8 lines aren’t shown here.
This diff is large: its 24 lines aren’t shown here.
This diff is large: its 82 lines aren’t shown here.
This diff is large: its 21 lines aren’t shown here.
This diff is large: its 12 lines aren’t shown here.
This diff is large: its 133 lines aren’t shown here.
This diff is large: its 121 lines aren’t shown here.
This diff is large: its 17 lines aren’t shown here.
This diff is large: its 56 lines aren’t shown here.
This diff is large: its 6 lines aren’t shown here.
This diff is large: its 18 lines aren’t shown here.
This diff is large: its 10 lines aren’t shown here.
This diff is large: its 68 lines aren’t shown here.
This diff is large: its 11 lines aren’t shown here.
This diff is large: its 33 lines aren’t shown here.
This diff is large: its 18 lines aren’t shown here.
This diff is large: its 9 lines aren’t shown here.
This diff is large: its 9 lines aren’t shown here.
This diff is large: its 46 lines aren’t shown here.
This diff is large: its 43 lines aren’t shown here.
This diff is large: its 88 lines aren’t shown here.
This diff is large: its 108 lines aren’t shown here.
This diff is large: its 113 lines aren’t shown here.
This diff is large: its 162 lines aren’t shown here.
This diff is large: its 44 lines aren’t shown here.
This diff is large: its 73 lines aren’t shown here.
This diff is large: its 166 lines aren’t shown here.
This diff is large: its 13 lines aren’t shown here.
This diff is large: its 24 lines aren’t shown here.
This diff is large: its 45 lines aren’t shown here.
This diff is large: its 28 lines aren’t shown here.
This diff is large: its 71 lines aren’t shown here.
This diff is large: its 9 lines aren’t shown here.
This diff is large: its 26 lines aren’t shown here.
This diff is large: its 19 lines aren’t shown here.
This diff is large: its 11 lines aren’t shown here.
This diff is large: its 15 lines aren’t shown here.
This diff is large: its 9 lines aren’t shown here.
This diff is large: its 17 lines aren’t shown here.
File renamed without changes.
This diff is large: its 58 lines aren’t shown here.
This diff is large: its 56 lines aren’t shown here.
This diff is large: its 9 lines aren’t shown here.
This diff is large: its 13 lines aren’t shown here.
This diff is large: its 306 lines aren’t shown here.
This diff is large: its 67 lines aren’t shown here.
This diff is large: its 41 lines aren’t shown here.
This diff is large: its 25 lines aren’t shown here.
File renamed without changes.
This diff is large: its 8 lines aren’t shown here.
This diff is large: its 27 lines aren’t shown here.
This diff is large: its 11 lines aren’t shown here.
This diff is large: its 9 lines aren’t shown here.
This diff is large: its 69 lines aren’t shown here.
This diff is large: its 6 lines aren’t shown here.
This diff is large: its 8 lines aren’t shown here.
This diff is large: its 11 lines aren’t shown here.
This diff is large: its 10 lines aren’t shown here.
This diff is large: its 82 lines aren’t shown here.
This diff is large: its 10 lines aren’t shown here.
File renamed without changes.
This diff is large: its 13 lines aren’t shown here.
This diff is large: its 11 lines aren’t shown here.
This diff is large: its 157 lines aren’t shown here.
This diff is large: its 153 lines aren’t shown here.
File renamed without changes.
File renamed without changes.
This diff is large: its 44 lines aren’t shown here.
This diff is large: its 99 lines aren’t shown here.
This diff is large: its 147 lines aren’t shown here.
This diff is large: its 150 lines aren’t shown here.
This diff is large: its 117 lines aren’t shown here.
This diff is large: its 110 lines aren’t shown here.
This diff is large: its 419 lines aren’t shown here.
This diff is large: its 224 lines aren’t shown here.
This diff is large: its 25 lines aren’t shown here.
This diff is large: its 125 lines aren’t shown here.
This diff is large: its 247 lines aren’t shown here.
This diff is large: its 449 lines aren’t shown here.
This diff is large: its 120 lines aren’t shown here.
This diff is large: its 155 lines aren’t shown here.
This diff is large: its 19 lines aren’t shown here.
This diff is large: its 59 lines aren’t shown here.
This diff is large: its 231 lines aren’t shown here.
This diff is large: its 9 lines aren’t shown here.
This diff is large: its 18 lines aren’t shown here.
This diff is large: its 9 lines aren’t shown here.
This diff is large: its 27 lines aren’t shown here.
This diff is large: its 60 lines aren’t shown here.
This diff is large: its 8 lines aren’t shown here.
This diff is large: its 84 lines aren’t shown here.
This diff is large: its 9 lines aren’t shown here.
This diff is large: its 106 lines aren’t shown here.
File renamed without changes.
File renamed without changes.
File renamed without changes.
This diff is large: its 13 lines aren’t shown here.
This diff is large: its 386 lines aren’t shown here.
This diff is large: its 112 lines aren’t shown here.
This diff is large: its 48 lines aren’t shown here.
This diff is large: its 33 lines aren’t shown here.
This diff is large: its 102 lines aren’t shown here.
This diff is large: its 24 lines aren’t shown here.
This diff is large: its 169 lines aren’t shown here.
This diff is large: its 177 lines aren’t shown here.
This diff is large: its 29 lines aren’t shown here.
This diff is large: its 19 lines aren’t shown here.
This diff is large: its 65 lines aren’t shown here.
This diff is large: its 180 lines aren’t shown here.
File renamed without changes.
This diff is large: its 14 lines aren’t shown here.
This diff is large: its 99 lines aren’t shown here.
This diff is large: its 92 lines aren’t shown here.
This diff is large: its 42 lines aren’t shown here.
This diff is large: its 38 lines aren’t shown here.
This diff is large: its 13 lines aren’t shown here.
This diff is large: its 91 lines aren’t shown here.
This diff is large: its 764 lines aren’t shown here.
This diff is large: its 67 lines aren’t shown here.
This diff is large: its 12 lines aren’t shown here.
This diff is large: its 312 lines aren’t shown here.
This diff is large: its 35 lines aren’t shown here.
This diff is large: its 264 lines aren’t shown here.
This diff is large: its 286 lines aren’t shown here.
This diff is large: its 13 lines aren’t shown here.
This diff is large: its 888 lines aren’t shown here.
This diff is large: its 144 lines aren’t shown here.
This diff is large: its 190 lines aren’t shown here.
File renamed without changes.
This diff is large: its 19 lines aren’t shown here.
This diff is large: its 198 lines aren’t shown here.
This diff is large: its 138 lines aren’t shown here.
This diff is large: its 11 lines aren’t shown here.
This diff is large: its 27 lines aren’t shown here.
This diff is large: its 243 lines aren’t shown here.
This diff is large: its 107 lines aren’t shown here.
This diff is large: its 97 lines aren’t shown here.
This diff is large: its 166 lines aren’t shown here.
This diff is large: its 16 lines aren’t shown here.
This diff is large: its 111 lines aren’t shown here.
This diff is large: its 363 lines aren’t shown here.
This diff is large: its 136 lines aren’t shown here.
This diff is large: its 8 lines aren’t shown here.
This diff is large: its 113 lines aren’t shown here.
File renamed without changes.
This diff is large: its 18 lines aren’t shown here.
File renamed without changes.
This diff is large: its 550 lines aren’t shown here.
This diff is large: its 33 lines aren’t shown here.
File renamed without changes.
File renamed without changes.
File renamed without changes.
File renamed without changes.
File renamed without changes.
File renamed without changes.
File renamed without changes.
File renamed without changes.
File renamed without changes.
This diff is large: its 11 lines aren’t shown here.
This diff is large: its 103 lines aren’t shown here.
File renamed without changes.
This diff is large: its 11 lines aren’t shown here.
This diff is large: its 11 lines aren’t shown here.
This diff is large: its 9 lines aren’t shown here.
This diff is large: its 415 lines aren’t shown here.
File renamed without changes.
This diff is large: its 68 lines aren’t shown here.
This diff is large: its 17 lines aren’t shown here.
File renamed without changes.
File renamed without changes.
This diff is large: its 99 lines aren’t shown here.
This diff is large: its 144 lines aren’t shown here.
This diff is large: its 148 lines aren’t shown here.
This diff is large: its 117 lines aren’t shown here.
This diff is large: its 107 lines aren’t shown here.
This diff is large: its 413 lines aren’t shown here.
This diff is large: its 216 lines aren’t shown here.
This diff is large: its 124 lines aren’t shown here.
This diff is large: its 245 lines aren’t shown here.
This diff is large: its 448 lines aren’t shown here.
This diff is large: its 152 lines aren’t shown here.
This diff is large: its 113 lines aren’t shown here.
This diff is large: its 231 lines aren’t shown here.
This diff is large: its 28 lines aren’t shown here.
This diff is large: its 447 lines aren’t shown here.
This diff is large: its 436 lines aren’t shown here.
This diff is large: its 21 lines aren’t shown here.
This diff is large: its 99 lines aren’t shown here.
This diff is large: its 95 lines aren’t shown here.
This diff is large: its 179 lines aren’t shown here.
This diff is large: its 117 lines aren’t shown here.
This diff is large: its 49 lines aren’t shown here.
This diff is large: its 39 lines aren’t shown here.
This diff is large: its 308 lines aren’t shown here.
This diff is large: its 307 lines aren’t shown here.
This diff is large: its 69 lines aren’t shown here.
This diff is large: its 69 lines aren’t shown here.
This diff is large: its 76 lines aren’t shown here.
This diff is large: its 73 lines aren’t shown here.
This diff is large: its 95 lines aren’t shown here.
This diff is large: its 98 lines aren’t shown here.
This diff is large: its 57 lines aren’t shown here.
This diff is large: its 54 lines aren’t shown here.
This diff is large: its 80 lines aren’t shown here.
This diff is large: its 76 lines aren’t shown here.
This diff is large: its 40 lines aren’t shown here.
This diff is large: its 38 lines aren’t shown here.
This diff is large: its 141 lines aren’t shown here.
This diff is large: its 136 lines aren’t shown here.
This diff is large: its 351 lines aren’t shown here.
This diff is large: its 348 lines aren’t shown here.
This diff is large: its 354 lines aren’t shown here.
This diff is large: its 344 lines aren’t shown here.
This diff is large: its 55 lines aren’t shown here.
This diff is large: its 53 lines aren’t shown here.
This diff is large: its 51 lines aren’t shown here.
This diff is large: its 288 lines aren’t shown here.
This diff is large: its 279 lines aren’t shown here.
This diff is large: its 156 lines aren’t shown here.
This diff is large: its 150 lines aren’t shown here.
This diff is large: its 87 lines aren’t shown here.
This diff is large: its 83 lines aren’t shown here.
This diff is large: its 56 lines aren’t shown here.
This diff is large: its 53 lines aren’t shown here.
This diff is large: its 444 lines aren’t shown here.
This diff is large: its 414 lines aren’t shown here.
This diff is large: its 39 lines aren’t shown here.
This diff is large: its 37 lines aren’t shown here.
This diff is large: its 170 lines aren’t shown here.
This diff is large: its 166 lines aren’t shown here.
This diff is large: its 67 lines aren’t shown here.
This diff is large: its 66 lines aren’t shown here.
This diff is large: its 174 lines aren’t shown here.
This diff is large: its 143 lines aren’t shown here.
This diff is large: its 83 lines aren’t shown here.
This diff is large: its 83 lines aren’t shown here.
This diff is large: its 41 lines aren’t shown here.
This diff is large: its 40 lines aren’t shown here.
This diff is large: its 131 lines aren’t shown here.
This diff is large: its 132 lines aren’t shown here.
This diff is large: its 161 lines aren’t shown here.
This diff is large: its 159 lines aren’t shown here.
This diff is large: its 16 lines aren’t shown here.
This diff is large: its 11 lines aren’t shown here.
This diff is large: its 36 lines aren’t shown here.
This diff is large: its 32 lines aren’t shown here.
This diff is large: its 208 lines aren’t shown here.
This diff is large: its 175 lines aren’t shown here.
This diff is large: its 72 lines aren’t shown here.
This diff is large: its 70 lines aren’t shown here.
This diff is large: its 79 lines aren’t shown here.
This diff is large: its 71 lines aren’t shown here.
This diff is large: its 163 lines aren’t shown here.
This diff is large: its 160 lines aren’t shown here.
This diff is large: its 189 lines aren’t shown here.
This diff is large: its 185 lines aren’t shown here.
This diff is large: its 193 lines aren’t shown here.
This diff is large: its 182 lines aren’t shown here.
This diff is large: its 298 lines aren’t shown here.
This diff is large: its 253 lines aren’t shown here.
This diff is large: its 65 lines aren’t shown here.
This diff is large: its 65 lines aren’t shown here.
This diff is large: its 9 lines aren’t shown here.
This diff is large: its 33 lines aren’t shown here.
This diff is large: its 10 lines aren’t shown here.
This diff is large: its 25 lines aren’t shown here.
This diff is large: its 11 lines aren’t shown here.
This diff is large: its 9 lines aren’t shown here.
This diff is large: its 9 lines aren’t shown here.
This diff is large: its 15 lines aren’t shown here.
This diff is large: its 12 lines aren’t shown here.
This diff is large: its 191 lines aren’t shown here.
This diff is large: its 54 lines aren’t shown here.
This diff is large: its 24 lines aren’t shown here.
This diff is large: its 9 lines aren’t shown here.
This diff is large: its 63 lines aren’t shown here.
This diff is large: its 154 lines aren’t shown here.
This diff is large: its 18 lines aren’t shown here.
This diff is large: its 9 lines aren’t shown here.
This diff is large: its 9 lines aren’t shown here.
This diff is large: its 12 lines aren’t shown here.
This diff is large: its 1429 lines aren’t shown here.
This diff is large: its 1269 lines aren’t shown here.
This diff is large: its 9 lines aren’t shown here.
This diff is large: its 36 lines aren’t shown here.
This diff is large: its 471 lines aren’t shown here.
This diff is large: its 18 lines aren’t shown here.
This diff is large: its 34 lines aren’t shown here.
This diff is large: its 5 lines aren’t shown here.
This diff is large: its 9 lines aren’t shown here.
This diff is large: its 48 lines aren’t shown here.
This diff is large: its 89 lines aren’t shown here.
This diff is large: its 312 lines aren’t shown here.
This diff is large: its 65 lines aren’t shown here.
This diff is large: its 37 lines aren’t shown here.
This diff is large: its 18 lines aren’t shown here.
This diff is large: its 99 lines aren’t shown here.
This diff is large: its 169 lines aren’t shown here.
This diff is large: its 124 lines aren’t shown here.
This diff is large: its 57 lines aren’t shown here.
This diff is large: its 292 lines aren’t shown here.
This diff is large: its 286 lines aren’t shown here.
This diff is large: its 18 lines aren’t shown here.
This diff is large: its 18 lines aren’t shown here.
This diff is large: its 11 lines aren’t shown here.
This diff is large: its 6 lines aren’t shown here.
This diff is large: its 181 lines aren’t shown here.
This diff is large: its 140 lines aren’t shown here.
This diff is large: its 243 lines aren’t shown here.
This diff is large: its 225 lines aren’t shown here.
This diff is large: its 360 lines aren’t shown here.
This diff is large: its 318 lines aren’t shown here.
This diff is large: its 252 lines aren’t shown here.
This diff is large: its 206 lines aren’t shown here.
This diff is large: its 139 lines aren’t shown here.
This diff is large: its 120 lines aren’t shown here.
This diff is large: its 19 lines aren’t shown here.
This diff is large: its 486 lines aren’t shown here.
This diff is large: its 455 lines aren’t shown here.
This diff is large: its 194 lines aren’t shown here.
This diff is large: its 188 lines aren’t shown here.
This diff is large: its 9 lines aren’t shown here.
This diff is large: its 91 lines aren’t shown here.
This diff is large: its 9 lines aren’t shown here.
This diff is large: its 102 lines aren’t shown here.
This diff is large: its 50 lines aren’t shown here.
This diff is large: its 18 lines aren’t shown here.
This diff is large: its 18 lines aren’t shown here.
This diff is large: its 70 lines aren’t shown here.
This diff is large: its 44 lines aren’t shown here.
This diff is large: its 247 lines aren’t shown here.
This diff is large: its 222 lines aren’t shown here.
This diff is large: its 145 lines aren’t shown here.
This diff is large: its 129 lines aren’t shown here.
This diff is large: its 1068 lines aren’t shown here.
This diff is large: its 1069 lines aren’t shown here.
This diff is large: its 304 lines aren’t shown here.
This diff is large: its 287 lines aren’t shown here.
This diff is large: its 50 lines aren’t shown here.
This diff is large: its 19 lines aren’t shown here.
This diff is large: its 81 lines aren’t shown here.
This diff is large: its 199 lines aren’t shown here.
This diff is large: its 195 lines aren’t shown here.
This diff is large: its 166 lines aren’t shown here.
This diff is large: its 152 lines aren’t shown here.
This diff is large: its 207 lines aren’t shown here.
This diff is large: its 184 lines aren’t shown here.
This diff is large: its 18 lines aren’t shown here.
This diff is large: its 69 lines aren’t shown here.
This diff is large: its 66 lines aren’t shown here.
This diff is large: its 266 lines aren’t shown here.
This diff is large: its 257 lines aren’t shown here.
This diff is large: its 22 lines aren’t shown here.
This diff is large: its 19 lines aren’t shown here.
This diff is large: its 19 lines aren’t shown here.
This diff is large: its 41 lines aren’t shown here.
This diff is large: its 30 lines aren’t shown here.
This diff is large: its 102 lines aren’t shown here.
This diff is large: its 94 lines aren’t shown here.
This diff is large: its 13 lines aren’t shown here.
This diff is large: its 90 lines aren’t shown here.
This diff is large: its 119 lines aren’t shown here.
This diff is large: its 113 lines aren’t shown here.
This diff is large: its 24 lines aren’t shown here.
This diff is large: its 116 lines aren’t shown here.
This diff is large: its 106 lines aren’t shown here.
This diff is large: its 160 lines aren’t shown here.
This diff is large: its 154 lines aren’t shown here.
This diff is large: its 7 lines aren’t shown here.
This diff is large: its 5 lines aren’t shown here.
This diff is large: its 70 lines aren’t shown here.
This diff is large: its 65 lines aren’t shown here.
This diff is large: its 167 lines aren’t shown here.
This diff is large: its 154 lines aren’t shown here.
This diff is large: its 76 lines aren’t shown here.
This diff is large: its 70 lines aren’t shown here.
This diff is large: its 11 lines aren’t shown here.
This diff is large: its 9 lines aren’t shown here.
This diff is large: its 226 lines aren’t shown here.
This diff is large: its 225 lines aren’t shown here.
This diff is large: its 1234 lines aren’t shown here.
This diff is large: its 968 lines aren’t shown here.
This diff is large: its 1343 lines aren’t shown here.
This diff is large: its 1072 lines aren’t shown here.
This diff is large: its 17 lines aren’t shown here.
This diff is large: its 32 lines aren’t shown here.
This diff is large: its 25 lines aren’t shown here.
This diff is large: its 362 lines aren’t shown here.
This diff is large: its 351 lines aren’t shown here.
This diff is large: its 194 lines aren’t shown here.
This diff is large: its 97 lines aren’t shown here.
This diff is large: its 760 lines aren’t shown here.
This diff is large: its 164 lines aren’t shown here.
This diff is large: its 600 lines aren’t shown here.
This diff is large: its 27 lines aren’t shown here.
This diff is large: its 660 lines aren’t shown here.
This diff is large: its 139 lines aren’t shown here.
This diff is large: its 260 lines aren’t shown here.
This diff is large: its 128 lines aren’t shown here.
This diff is large: its 46 lines aren’t shown here.
This diff is large: its 71 lines aren’t shown here.
This diff is large: its 42 lines aren’t shown here.
This diff is large: its 59 lines aren’t shown here.
This diff is large: its 185 lines aren’t shown here.
This diff is large: its 225 lines aren’t shown here.
This diff is large: its 45 lines aren’t shown here.
This diff is large: its 51 lines aren’t shown here.
This diff is large: its 28 lines aren’t shown here.
This diff is large: its 16 lines aren’t shown here.
This diff is large: its 275 lines aren’t shown here.
This diff is large: its 249 lines aren’t shown here.
This diff is large: its 702 lines aren’t shown here.
This diff is large: its 670 lines aren’t shown here.
This diff is large: its 248 lines aren’t shown here.
This diff is large: its 243 lines aren’t shown here.
This diff is large: its 305 lines aren’t shown here.
This diff is large: its 273 lines aren’t shown here.
This diff is large: its 1523 lines aren’t shown here.
This diff is large: its 1370 lines aren’t shown here.
This diff is large: its 572 lines aren’t shown here.
This diff is large: its 542 lines aren’t shown here.
This diff is large: its 510 lines aren’t shown here.
This diff is large: its 496 lines aren’t shown here.
This diff is large: its 11 lines aren’t shown here.
This diff is large: its 18 lines aren’t shown here.
This diff is large: its 36 lines aren’t shown here.
This diff is large: its 357 lines aren’t shown here.
This diff is large: its 258 lines aren’t shown here.
This diff is large: its 150 lines aren’t shown here.
This diff is large: its 783 lines aren’t shown here.
This diff is large: its 145 lines aren’t shown here.
This diff is large: its 153 lines aren’t shown here.
This diff is large: its 1488 lines aren’t shown here.
This diff is large: its 77 lines aren’t shown here.
This diff is large: its 26 lines aren’t shown here.
This diff is large: its 85 lines aren’t shown here.
This diff is large: its 81 lines aren’t shown here.
This diff is large: its 91 lines aren’t shown here.
This diff is large: its 74 lines aren’t shown here.
This diff is large: its 126 lines aren’t shown here.
This diff is large: its 123 lines aren’t shown here.
This diff is large: its 138 lines aren’t shown here.
This diff is large: its 86 lines aren’t shown here.
This diff is large: its 60 lines aren’t shown here.
This diff is large: its 51 lines aren’t shown here.
This diff is large: its 116 lines aren’t shown here.
This diff is large: its 102 lines aren’t shown here.
This diff is large: its 148 lines aren’t shown here.
This diff is large: its 131 lines aren’t shown here.
This diff is large: its 138 lines aren’t shown here.
This diff is large: its 121 lines aren’t shown here.
This diff is large: its 225 lines aren’t shown here.
This diff is large: its 195 lines aren’t shown here.
This diff is large: its 119 lines aren’t shown here.
This diff is large: its 111 lines aren’t shown here.
This diff is large: its 45 lines aren’t shown here.
This diff is large: its 44 lines aren’t shown here.
This diff is large: its 168 lines aren’t shown here.
This diff is large: its 153 lines aren’t shown here.
This diff is large: its 47 lines aren’t shown here.
This diff is large: its 42 lines aren’t shown here.
This diff is large: its 38 lines aren’t shown here.
This diff is large: its 37 lines aren’t shown here.
This diff is large: its 6 lines aren’t shown here.
This diff is large: its 25 lines aren’t shown here.
This diff is large: its 395 lines aren’t shown here.
This diff is large: its 334 lines aren’t shown here.
This diff is large: its 205 lines aren’t shown here.
This diff is large: its 184 lines aren’t shown here.
This diff is large: its 171 lines aren’t shown here.
This diff is large: its 146 lines aren’t shown here.
This diff is large: its 153 lines aren’t shown here.
This diff is large: its 143 lines aren’t shown here.
This diff is large: its 575 lines aren’t shown here.
This diff is large: its 560 lines aren’t shown here.
This diff is large: its 78 lines aren’t shown here.
This diff is large: its 74 lines aren’t shown here.
This diff is large: its 178 lines aren’t shown here.
This diff is large: its 168 lines aren’t shown here.
This diff is large: its 394 lines aren’t shown here.
This diff is large: its 384 lines aren’t shown here.
This diff is large: its 18 lines aren’t shown here.
This diff is large: its 912 lines aren’t shown here.
This diff is large: its 885 lines aren’t shown here.
This diff is large: its 11 lines aren’t shown here.
This diff is large: its 7 lines aren’t shown here.
This diff is large: its 227 lines aren’t shown here.
This diff is large: its 326 lines aren’t shown here.
This diff is large: its 110 lines aren’t shown here.
This diff is large: its 46 lines aren’t shown here.
This diff is large: its 13 lines aren’t shown here.
This diff is large: its 16 lines aren’t shown here.
This diff is large: its 481 lines aren’t shown here.
This diff is large: its 9 lines aren’t shown here.
This diff is large: its 10 lines aren’t shown here.
This diff is large: its 29 lines aren’t shown here.
This diff is large: its 21 lines aren’t shown here.
This diff is large: its 135 lines aren’t shown here.
This diff is large: its 16 lines aren’t shown here.
This diff is large: its 646 lines aren’t shown here.
This diff is large: its 35 lines aren’t shown here.
This diff is large: its 41 lines aren’t shown here.
This diff is large: its 32 lines aren’t shown here.
This diff is large: its 22 lines aren’t shown here.
This diff is large: its 20 lines aren’t shown here.
This diff is large: its 15 lines aren’t shown here.
This diff is large: its 37 lines aren’t shown here.
This diff is large: its 7 lines aren’t shown here.
This diff is large: its 23 lines aren’t shown here.
This diff is large: its 99 lines aren’t shown here.
This diff is large: its 12 lines aren’t shown here.
This diff is large: its 12 lines aren’t shown here.
This diff is large: its 18 lines aren’t shown here.
This diff is large: its 58 lines aren’t shown here.
This diff is large: its 17 lines aren’t shown here.
This diff is large: its 86 lines aren’t shown here.
This diff is large: its 82 lines aren’t shown here.
This diff is large: its 109 lines aren’t shown here.
This diff is large: its 99 lines aren’t shown here.
This diff is large: its 97 lines aren’t shown here.
This diff is large: its 108 lines aren’t shown here.
This diff is large: its 32 lines aren’t shown here.
This diff is large: its 37 lines aren’t shown here.
This diff is large: its 10 lines aren’t shown here.
This diff is large: its 63 lines aren’t shown here.
This diff is large: its 76 lines aren’t shown here.
This diff is large: its 94 lines aren’t shown here.
This diff is large: its 100 lines aren’t shown here.
This diff is large: its 111 lines aren’t shown here.
This diff is large: its 137 lines aren’t shown here.
This diff is large: its 142 lines aren’t shown here.
This diff is large: its 267 lines aren’t shown here.
This diff is large: its 88 lines aren’t shown here.
This diff is large: its 78 lines aren’t shown here.
This diff is large: its 41 lines aren’t shown here.
This diff is large: its 35 lines aren’t shown here.
This diff is large: its 89 lines aren’t shown here.
This diff is large: its 715 lines aren’t shown here.
This diff is large: its 66 lines aren’t shown here.
This diff is large: its 40 lines aren’t shown here.
This diff is large: its 15 lines aren’t shown here.
This diff is large: its 57 lines aren’t shown here.
This diff is large: its 50 lines aren’t shown here.
This diff is large: its 6 lines aren’t shown here.
This diff is large: its 22 lines aren’t shown here.
This diff is large: its 53 lines aren’t shown here.
This diff is large: its 47 lines aren’t shown here.
This diff is large: its 54 lines aren’t shown here.
This diff is large: its 48 lines aren’t shown here.
This diff is large: its 44 lines aren’t shown here.
This diff is large: its 30 lines aren’t shown here.
This diff is large: its 11 lines aren’t shown here.
This diff is large: its 24 lines aren’t shown here.
This diff is large: its 440 lines aren’t shown here.
This diff is large: its 18 lines aren’t shown here.
This diff is large: its 124 lines aren’t shown here.
This diff is large: its 9 lines aren’t shown here.
This diff is large: its 193 lines aren’t shown here.
This diff is large: its 184 lines aren’t shown here.
This diff is large: its 293 lines aren’t shown here.
This diff is large: its 18 lines aren’t shown here.
This diff is large: its 9 lines aren’t shown here.
This diff is large: its 17 lines aren’t shown here.
This diff is large: its 114 lines aren’t shown here.
This diff is large: its 9 lines aren’t shown here.
This diff is large: its 59 lines aren’t shown here.
This diff is large: its 9 lines aren’t shown here.
This diff is large: its 20 lines aren’t shown here.
This diff is large: its 9 lines aren’t shown here.
This diff is large: its 112 lines aren’t shown here.
This diff is large: its 291 lines aren’t shown here.
This diff is large: its 33 lines aren’t shown here.
This diff is large: its 237 lines aren’t shown here.
This diff is large: its 274 lines aren’t shown here.
This diff is large: its 816 lines aren’t shown here.
This diff is large: its 142 lines aren’t shown here.
This diff is large: its 184 lines aren’t shown here.
This diff is large: its 38 lines aren’t shown here.
This diff is large: its 34 lines aren’t shown here.
This diff is large: its 161 lines aren’t shown here.
This diff is large: its 150 lines aren’t shown here.
This diff is large: its 31 lines aren’t shown here.
This diff is large: its 31 lines aren’t shown here.
This diff is large: its 21 lines aren’t shown here.
This diff is large: its 134 lines aren’t shown here.
This diff is large: its 119 lines aren’t shown here.
This diff is large: its 60 lines aren’t shown here.
This diff is large: its 29 lines aren’t shown here.
This diff is large: its 54 lines aren’t shown here.
This diff is large: its 39 lines aren’t shown here.
This diff is large: its 26 lines aren’t shown here.
This diff is large: its 42 lines aren’t shown here.
This diff is large: its 49 lines aren’t shown here.
This diff is large: its 198 lines aren’t shown here.
This diff is large: its 136 lines aren’t shown here.
This diff is large: its 6 lines aren’t shown here.
This diff is large: its 19 lines aren’t shown here.
This diff is large: its 37 lines aren’t shown here.
This diff is large: its 33 lines aren’t shown here.
This diff is large: its 270 lines aren’t shown here.
This diff is large: its 255 lines aren’t shown here.
This diff is large: its 206 lines aren’t shown here.
This diff is large: its 201 lines aren’t shown here.
This diff is large: its 52 lines aren’t shown here.
This diff is large: its 47 lines aren’t shown here.
This diff is large: its 148 lines aren’t shown here.
This diff is large: its 145 lines aren’t shown here.
This diff is large: its 245 lines aren’t shown here.
This diff is large: its 232 lines aren’t shown here.
This diff is large: its 47 lines aren’t shown here.
This diff is large: its 80 lines aren’t shown here.
This diff is large: its 78 lines aren’t shown here.
This diff is large: its 380 lines aren’t shown here.
This diff is large: its 343 lines aren’t shown here.
This diff is large: its 1136 lines aren’t shown here.
This diff is large: its 1095 lines aren’t shown here.
This diff is large: its 228 lines aren’t shown here.
This diff is large: its 213 lines aren’t shown here.
This diff is large: its 289 lines aren’t shown here.
This diff is large: its 232 lines aren’t shown here.
This diff is large: its 258 lines aren’t shown here.
This diff is large: its 237 lines aren’t shown here.
This diff is large: its 230 lines aren’t shown here.
This diff is large: its 219 lines aren’t shown here.
This diff is large: its 39 lines aren’t shown here.
This diff is large: its 34 lines aren’t shown here.
This diff is large: its 98 lines aren’t shown here.
This diff is large: its 97 lines aren’t shown here.
This diff is large: its 179 lines aren’t shown here.
This diff is large: its 172 lines aren’t shown here.
This diff is large: its 33 lines aren’t shown here.
This diff is large: its 31 lines aren’t shown here.
This diff is large: its 941 lines aren’t shown here.
This diff is large: its 929 lines aren’t shown here.
This diff is large: its 88 lines aren’t shown here.
This diff is large: its 86 lines aren’t shown here.
This diff is large: its 287 lines aren’t shown here.
This diff is large: its 275 lines aren’t shown here.
This diff is large: its 138 lines aren’t shown here.
This diff is large: its 136 lines aren’t shown here.
This diff is large: its 64 lines aren’t shown here.
This diff is large: its 61 lines aren’t shown here.
This diff is large: its 141 lines aren’t shown here.
This diff is large: its 139 lines aren’t shown here.
This diff is large: its 502 lines aren’t shown here.
This diff is large: its 447 lines aren’t shown here.
This diff is large: its 30 lines aren’t shown here.
This diff is large: its 28 lines aren’t shown here.
This diff is large: its 192 lines aren’t shown here.
This diff is large: its 171 lines aren’t shown here.
This diff is large: its 214 lines aren’t shown here.
This diff is large: its 186 lines aren’t shown here.
This diff is large: its 91 lines aren’t shown here.
This diff is large: its 156 lines aren’t shown here.
This diff is large: its 142 lines aren’t shown here.
This diff is large: its 223 lines aren’t shown here.
This diff is large: its 222 lines aren’t shown here.
This diff is large: its 61 lines aren’t shown here.
This diff is large: its 57 lines aren’t shown here.
This diff is large: its 468 lines aren’t shown here.
This diff is large: its 450 lines aren’t shown here.
This diff is large: its 434 lines aren’t shown here.
This diff is large: its 430 lines aren’t shown here.
This diff is large: its 94 lines aren’t shown here.
This diff is large: its 88 lines aren’t shown here.
This diff is large: its 84 lines aren’t shown here.
This diff is large: its 337 lines aren’t shown here.
This diff is large: its 335 lines aren’t shown here.
This diff is large: its 302 lines aren’t shown here.
This diff is large: its 293 lines aren’t shown here.
This diff is large: its 582 lines aren’t shown here.
This diff is large: its 568 lines aren’t shown here.
This diff is large: its 35 lines aren’t shown here.
This diff is large: its 42 lines aren’t shown here.
This diff is large: its 44 lines aren’t shown here.
This diff is large: its 40 lines aren’t shown here.
This diff is large: its 313 lines aren’t shown here.
This diff is large: its 302 lines aren’t shown here.
This diff is large: its 139 lines aren’t shown here.
This diff is large: its 138 lines aren’t shown here.
This diff is large: its 157 lines aren’t shown here.
This diff is large: its 152 lines aren’t shown here.
This diff is large: its 297 lines aren’t shown here.
This diff is large: its 296 lines aren’t shown here.
This diff is large: its 111 lines aren’t shown here.
This diff is large: its 106 lines aren’t shown here.
This diff is large: its 248 lines aren’t shown here.
This diff is large: its 245 lines aren’t shown here.
This diff is large: its 69 lines aren’t shown here.
This diff is large: its 240 lines aren’t shown here.
This diff is large: its 9 lines aren’t shown here.
This diff is large: its 63 lines aren’t shown here.
This diff is large: its 9 lines aren’t shown here.
This diff is large: its 11 lines aren’t shown here.
This diff is large: its 18 lines aren’t shown here.
This diff is large: its 58 lines aren’t shown here.
This diff is large: its 18 lines aren’t shown here.
This diff is large: its 9 lines aren’t shown here.
This diff is large: its 100 lines aren’t shown here.
This diff is large: its 87 lines aren’t shown here.
This diff is large: its 159 lines aren’t shown here.
This diff is large: its 108 lines aren’t shown here.
This diff is large: its 352 lines aren’t shown here.
This diff is large: its 120 lines aren’t shown here.
This diff is large: its 4 lines aren’t shown here.
This diff is large: its 98 lines aren’t shown here.
This diff is large: its 25 lines aren’t shown here.
This diff is large: its 28 lines aren’t shown here.
This diff is large: its 51 lines aren’t shown here.
This diff is large: its 16 lines aren’t shown here.
This diff is large: its 256 lines aren’t shown here.
This diff is large: its 250 lines aren’t shown here.
This diff is large: its 299 lines aren’t shown here.
This diff is large: its 272 lines aren’t shown here.
This diff is large: its 126 lines aren’t shown here.
This diff is large: its 74 lines aren’t shown here.
This diff is large: its 2143 lines aren’t shown here.
This diff is large: its 531 lines aren’t shown here.
This diff is large: its 473 lines aren’t shown here.
This diff is large: its 141 lines aren’t shown here.
This diff is large: its 85 lines aren’t shown here.
This diff is large: its 2614 lines aren’t shown here.
This diff is large: its 329 lines aren’t shown here.
This diff is large: its 288 lines aren’t shown here.
This diff is large: its 29 lines aren’t shown here.
This diff is large: its 213 lines aren’t shown here.
This diff is large: its 198 lines aren’t shown here.
This diff is large: its 65 lines aren’t shown here.
This diff is large: its 51 lines aren’t shown here.
This diff is large: its 488 lines aren’t shown here.
This diff is large: its 668 lines aren’t shown here.
This diff is large: its 12 lines aren’t shown here.
This diff is large: its 867 lines aren’t shown here.
This diff is large: its 838 lines aren’t shown here.
This diff is large: its 352 lines aren’t shown here.
This diff is large: its 301 lines aren’t shown here.
This diff is large: its 51 lines aren’t shown here.
This diff is large: its 49 lines aren’t shown here.
This diff is large: its 294 lines aren’t shown here.
This diff is large: its 292 lines aren’t shown here.
This diff is large: its 28 lines aren’t shown here.
This diff is large: its 77 lines aren’t shown here.
This diff is large: its 75 lines aren’t shown here.
This diff is large: its 129 lines aren’t shown here.
This diff is large: its 123 lines aren’t shown here.
This diff is large: its 889 lines aren’t shown here.
This diff is large: its 872 lines aren’t shown here.
This diff is large: its 250 lines aren’t shown here.
This diff is large: its 243 lines aren’t shown here.
This diff is large: its 84 lines aren’t shown here.
This diff is large: its 78 lines aren’t shown here.
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.