diff options
Diffstat (limited to 'Documentation')
393 files changed, 18820 insertions, 5131 deletions
diff --git a/Documentation/ABI/stable/sysfs-devices-node b/Documentation/ABI/stable/sysfs-devices-node index 484fc04bcc25..8db67aa472f1 100644 --- a/Documentation/ABI/stable/sysfs-devices-node +++ b/Documentation/ABI/stable/sysfs-devices-node @@ -176,3 +176,9 @@ Contact: Keith Busch <keith.busch@intel.com> Description: The cache write policy: 0 for write-back, 1 for write-through, other or unknown. + +What: /sys/devices/system/node/nodeX/x86/sgx_total_bytes +Date: November 2021 +Contact: Jarkko Sakkinen <jarkko@kernel.org> +Description: + The total amount of SGX physical memory in bytes. diff --git a/Documentation/ABI/testing/sysfs-class-firmware-attributes b/Documentation/ABI/testing/sysfs-class-firmware-attributes index 90fdf935aa5e..13e31c6a0e9c 100644 --- a/Documentation/ABI/testing/sysfs-class-firmware-attributes +++ b/Documentation/ABI/testing/sysfs-class-firmware-attributes @@ -161,6 +161,15 @@ Description: power-on: Representing a password required to use the system + system-mgmt: + Representing System Management password. + See Lenovo extensions section for details + HDD: + Representing HDD password + See Lenovo extensions section for details + NVMe: + Representing NVMe password + See Lenovo extensions section for details mechanism: The means of authentication. This attribute is mandatory. @@ -207,6 +216,13 @@ Description: On Lenovo systems the following additional settings are available: + role: system-mgmt This gives the same authority as the bios-admin password to control + security related features. The authorities allocated can be set via + the BIOS menu SMP Access Control Policy + + role: HDD & NVMe This password is used to unlock access to the drive at boot. Note see + 'level' and 'index' extensions below. + lenovo_encoding: The encoding method that is used. This can be either "ascii" or "scancode". Default is set to "ascii" @@ -216,6 +232,22 @@ Description: two char code (e.g. "us", "fr", "gr") and may vary per platform. Default is set to "us" + level: + Available for HDD and NVMe authentication to set 'user' or 'master' + privilege level. + If only the user password is configured then this should be used to + unlock the drive at boot. If both master and user passwords are set + then either can be used. If a master password is set a user password + is required. + This attribute defaults to 'user' level + + index: + Used with HDD and NVME authentication to set the drive index + that is being referenced (e.g hdd0, hdd1 etc) + This attribute defaults to device 0. + + + What: /sys/class/firmware-attributes/*/attributes/pending_reboot Date: February 2021 KernelVersion: 5.11 diff --git a/Documentation/ABI/testing/sysfs-class-power b/Documentation/ABI/testing/sysfs-class-power index f7904efc4cfa..fde21d900420 100644 --- a/Documentation/ABI/testing/sysfs-class-power +++ b/Documentation/ABI/testing/sysfs-class-power @@ -413,7 +413,7 @@ Description: "Over voltage", "Unspecified failure", "Cold", "Watchdog timer expire", "Safety timer expire", "Over current", "Calibration required", "Warm", - "Cool", "Hot" + "Cool", "Hot", "No battery" What: /sys/class/power_supply/<supply_name>/precharge_current Date: June 2017 @@ -455,6 +455,20 @@ Description: "Unknown", "Charging", "Discharging", "Not charging", "Full" +What: /sys/class/power_supply/<supply_name>/charge_behaviour +Date: November 2021 +Contact: linux-pm@vger.kernel.org +Description: + Represents the charging behaviour. + + Access: Read, Write + + Valid values: + ================ ==================================== + auto: Charge normally, respect thresholds + inhibit-charge: Do not charge while AC is attached + force-discharge: Force discharge while AC is attached + What: /sys/class/power_supply/<supply_name>/technology Date: May 2007 Contact: linux-pm@vger.kernel.org diff --git a/Documentation/Makefile b/Documentation/Makefile index c3feb657b654..9f4bd42cef18 100644 --- a/Documentation/Makefile +++ b/Documentation/Makefile @@ -19,6 +19,8 @@ endif SPHINXBUILD = sphinx-build SPHINXOPTS = SPHINXDIRS = . +DOCS_THEME = +DOCS_CSS = _SPHINXDIRS = $(sort $(patsubst $(srctree)/Documentation/%/index.rst,%,$(wildcard $(srctree)/Documentation/*/index.rst))) SPHINX_CONF = conf.py PAPER = @@ -84,7 +86,10 @@ quiet_cmd_sphinx = SPHINX $@ --> file://$(abspath $(BUILDDIR)/$3/$4) -D version=$(KERNELVERSION) -D release=$(KERNELRELEASE) \ $(ALLSPHINXOPTS) \ $(abspath $(srctree)/$(src)/$5) \ - $(abspath $(BUILDDIR)/$3/$4) + $(abspath $(BUILDDIR)/$3/$4) && \ + if [ "x$(DOCS_CSS)" != "x" ]; then \ + cp $(if $(patsubst /%,,$(DOCS_CSS)),$(abspath $(srctree)/$(DOCS_CSS)),$(DOCS_CSS)) $(BUILDDIR)/$3/_static/; \ + fi htmldocs: @$(srctree)/scripts/sphinx-pre-install --version-check @@ -154,4 +159,8 @@ dochelp: @echo ' make SPHINX_CONF={conf-file} [target] use *additional* sphinx-build' @echo ' configuration. This is e.g. useful to build with nit-picking config.' @echo + @echo ' make DOCS_THEME={sphinx-theme} selects a different Sphinx theme.' + @echo + @echo ' make DOCS_CSS={a .css file} adds a DOCS_CSS override file for html/epub output.' + @echo @echo ' Default location for the generated documents is Documentation/output' diff --git a/Documentation/RCU/Design/Expedited-Grace-Periods/Funnel0.svg b/Documentation/RCU/Design/Expedited-Grace-Periods/Funnel0.svg index 98af66557908..16b1ff0ad38c 100644 --- a/Documentation/RCU/Design/Expedited-Grace-Periods/Funnel0.svg +++ b/Documentation/RCU/Design/Expedited-Grace-Periods/Funnel0.svg @@ -116,7 +116,7 @@ <flowRoot xml:space="preserve" id="flowRoot2985" - style="font-size:10px;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;text-align:center;line-height:125%;letter-spacing:0px;word-spacing:0px;writing-mode:lr-tb;text-anchor:middle;fill:#000000;fill-opacity:1;stroke:none;font-family:Symbol;-inkscape-font-specification:Symbol"><flowRegion + style="font-size:10px;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;text-align:center;line-height:125%;letter-spacing:0px;word-spacing:0px;writing-mode:lr-tb;text-anchor:middle;fill:#000000;fill-opacity:1;stroke:none;font-family:monospace;-inkscape-font-specification:monospace"><flowRegion id="flowRegion2987"><rect id="rect2989" width="82.85714" @@ -125,7 +125,7 @@ y="492.36218" /></flowRegion><flowPara id="flowPara2991" /></flowRoot> <text xml:space="preserve" - style="font-size:10px;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;text-align:center;line-height:125%;letter-spacing:0px;word-spacing:0px;writing-mode:lr-tb;text-anchor:middle;fill:#000000;fill-opacity:1;stroke:none;font-family:Symbol;-inkscape-font-specification:Symbol" + style="font-size:10px;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;text-align:center;line-height:125%;letter-spacing:0px;word-spacing:0px;writing-mode:lr-tb;text-anchor:middle;fill:#000000;fill-opacity:1;stroke:none;font-family:monospace;-inkscape-font-specification:monospace" x="362.371" y="262.51819" id="text4441" diff --git a/Documentation/RCU/Design/Expedited-Grace-Periods/Funnel1.svg b/Documentation/RCU/Design/Expedited-Grace-Periods/Funnel1.svg index e0184a37aec7..684a4b969725 100644 --- a/Documentation/RCU/Design/Expedited-Grace-Periods/Funnel1.svg +++ b/Documentation/RCU/Design/Expedited-Grace-Periods/Funnel1.svg @@ -116,7 +116,7 @@ <flowRoot xml:space="preserve" id="flowRoot2985" - style="font-size:10px;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;text-align:center;line-height:125%;letter-spacing:0px;word-spacing:0px;writing-mode:lr-tb;text-anchor:middle;fill:#000000;fill-opacity:1;stroke:none;font-family:Symbol;-inkscape-font-specification:Symbol"><flowRegion + style="font-size:10px;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;text-align:center;line-height:125%;letter-spacing:0px;word-spacing:0px;writing-mode:lr-tb;text-anchor:middle;fill:#000000;fill-opacity:1;stroke:none;font-family:monospace;-inkscape-font-specification:monospace"><flowRegion id="flowRegion2987"><rect id="rect2989" width="82.85714" @@ -125,7 +125,7 @@ y="492.36218" /></flowRegion><flowPara id="flowPara2991" /></flowRoot> <text xml:space="preserve" - style="font-size:10px;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;text-align:center;line-height:125%;letter-spacing:0px;word-spacing:0px;writing-mode:lr-tb;text-anchor:middle;fill:#000000;fill-opacity:1;stroke:none;font-family:Symbol;-inkscape-font-specification:Symbol" + style="font-size:10px;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;text-align:center;line-height:125%;letter-spacing:0px;word-spacing:0px;writing-mode:lr-tb;text-anchor:middle;fill:#000000;fill-opacity:1;stroke:none;font-family:monospace;-inkscape-font-specification:monospace" x="362.371" y="262.51819" id="text4441" diff --git a/Documentation/RCU/Design/Expedited-Grace-Periods/Funnel2.svg b/Documentation/RCU/Design/Expedited-Grace-Periods/Funnel2.svg index 1bc3fed54d58..8fb2454d9544 100644 --- a/Documentation/RCU/Design/Expedited-Grace-Periods/Funnel2.svg +++ b/Documentation/RCU/Design/Expedited-Grace-Periods/Funnel2.svg @@ -116,7 +116,7 @@ <flowRoot xml:space="preserve" id="flowRoot2985" - style="font-size:10px;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;text-align:center;line-height:125%;letter-spacing:0px;word-spacing:0px;writing-mode:lr-tb;text-anchor:middle;fill:#000000;fill-opacity:1;stroke:none;font-family:Symbol;-inkscape-font-specification:Symbol"><flowRegion + style="font-size:10px;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;text-align:center;line-height:125%;letter-spacing:0px;word-spacing:0px;writing-mode:lr-tb;text-anchor:middle;fill:#000000;fill-opacity:1;stroke:none;font-family:monospace;-inkscape-font-specification:monospace"><flowRegion id="flowRegion2987"><rect id="rect2989" width="82.85714" @@ -125,7 +125,7 @@ y="492.36218" /></flowRegion><flowPara id="flowPara2991" /></flowRoot> <text xml:space="preserve" - style="font-size:10px;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;text-align:center;line-height:125%;letter-spacing:0px;word-spacing:0px;writing-mode:lr-tb;text-anchor:middle;fill:#000000;fill-opacity:1;stroke:none;font-family:Symbol;-inkscape-font-specification:Symbol" + style="font-size:10px;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;text-align:center;line-height:125%;letter-spacing:0px;word-spacing:0px;writing-mode:lr-tb;text-anchor:middle;fill:#000000;fill-opacity:1;stroke:none;font-family:monospace;-inkscape-font-specification:monospace" x="362.371" y="262.51819" id="text4441" diff --git a/Documentation/RCU/Design/Expedited-Grace-Periods/Funnel3.svg b/Documentation/RCU/Design/Expedited-Grace-Periods/Funnel3.svg index 6d8a1bffb3e4..5d4f22d5662c 100644 --- a/Documentation/RCU/Design/Expedited-Grace-Periods/Funnel3.svg +++ b/Documentation/RCU/Design/Expedited-Grace-Periods/Funnel3.svg @@ -116,7 +116,7 @@ <flowRoot xml:space="preserve" id="flowRoot2985" - style="font-size:10px;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;text-align:center;line-height:125%;letter-spacing:0px;word-spacing:0px;writing-mode:lr-tb;text-anchor:middle;fill:#000000;fill-opacity:1;stroke:none;font-family:Symbol;-inkscape-font-specification:Symbol"><flowRegion + style="font-size:10px;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;text-align:center;line-height:125%;letter-spacing:0px;word-spacing:0px;writing-mode:lr-tb;text-anchor:middle;fill:#000000;fill-opacity:1;stroke:none;font-family:monospace;-inkscape-font-specification:monospace"><flowRegion id="flowRegion2987"><rect id="rect2989" width="82.85714" @@ -125,7 +125,7 @@ y="492.36218" /></flowRegion><flowPara id="flowPara2991" /></flowRoot> <text xml:space="preserve" - style="font-size:10px;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;text-align:center;line-height:125%;letter-spacing:0px;word-spacing:0px;writing-mode:lr-tb;text-anchor:middle;fill:#000000;fill-opacity:1;stroke:none;font-family:Symbol;-inkscape-font-specification:Symbol" + style="font-size:10px;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;text-align:center;line-height:125%;letter-spacing:0px;word-spacing:0px;writing-mode:lr-tb;text-anchor:middle;fill:#000000;fill-opacity:1;stroke:none;font-family:monospace;-inkscape-font-specification:monospace" x="362.371" y="262.51819" id="text4441" diff --git a/Documentation/RCU/Design/Expedited-Grace-Periods/Funnel4.svg b/Documentation/RCU/Design/Expedited-Grace-Periods/Funnel4.svg index 44018fd6342b..b89b02869914 100644 --- a/Documentation/RCU/Design/Expedited-Grace-Periods/Funnel4.svg +++ b/Documentation/RCU/Design/Expedited-Grace-Periods/Funnel4.svg @@ -116,7 +116,7 @@ <flowRoot xml:space="preserve" id="flowRoot2985" - style="font-size:10px;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;text-align:center;line-height:125%;letter-spacing:0px;word-spacing:0px;writing-mode:lr-tb;text-anchor:middle;fill:#000000;fill-opacity:1;stroke:none;font-family:Symbol;-inkscape-font-specification:Symbol"><flowRegion + style="font-size:10px;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;text-align:center;line-height:125%;letter-spacing:0px;word-spacing:0px;writing-mode:lr-tb;text-anchor:middle;fill:#000000;fill-opacity:1;stroke:none;font-family:monospace;-inkscape-font-specification:monospace"><flowRegion id="flowRegion2987"><rect id="rect2989" width="82.85714" @@ -125,7 +125,7 @@ y="492.36218" /></flowRegion><flowPara id="flowPara2991" /></flowRoot> <text xml:space="preserve" - style="font-size:10px;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;text-align:center;line-height:125%;letter-spacing:0px;word-spacing:0px;writing-mode:lr-tb;text-anchor:middle;fill:#000000;fill-opacity:1;stroke:none;font-family:Symbol;-inkscape-font-specification:Symbol" + style="font-size:10px;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;text-align:center;line-height:125%;letter-spacing:0px;word-spacing:0px;writing-mode:lr-tb;text-anchor:middle;fill:#000000;fill-opacity:1;stroke:none;font-family:monospace;-inkscape-font-specification:monospace" x="362.371" y="262.51819" id="text4441" diff --git a/Documentation/RCU/Design/Expedited-Grace-Periods/Funnel5.svg b/Documentation/RCU/Design/Expedited-Grace-Periods/Funnel5.svg index e5eef50454fb..90f1c77bea2f 100644 --- a/Documentation/RCU/Design/Expedited-Grace-Periods/Funnel5.svg +++ b/Documentation/RCU/Design/Expedited-Grace-Periods/Funnel5.svg @@ -116,7 +116,7 @@ <flowRoot xml:space="preserve" id="flowRoot2985" - style="font-size:10px;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;text-align:center;line-height:125%;letter-spacing:0px;word-spacing:0px;writing-mode:lr-tb;text-anchor:middle;fill:#000000;fill-opacity:1;stroke:none;font-family:Symbol;-inkscape-font-specification:Symbol"><flowRegion + style="font-size:10px;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;text-align:center;line-height:125%;letter-spacing:0px;word-spacing:0px;writing-mode:lr-tb;text-anchor:middle;fill:#000000;fill-opacity:1;stroke:none;font-family:monospace;-inkscape-font-specification:monospace"><flowRegion id="flowRegion2987"><rect id="rect2989" width="82.85714" @@ -125,7 +125,7 @@ y="492.36218" /></flowRegion><flowPara id="flowPara2991" /></flowRoot> <text xml:space="preserve" - style="font-size:10px;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;text-align:center;line-height:125%;letter-spacing:0px;word-spacing:0px;writing-mode:lr-tb;text-anchor:middle;fill:#000000;fill-opacity:1;stroke:none;font-family:Symbol;-inkscape-font-specification:Symbol" + style="font-size:10px;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;text-align:center;line-height:125%;letter-spacing:0px;word-spacing:0px;writing-mode:lr-tb;text-anchor:middle;fill:#000000;fill-opacity:1;stroke:none;font-family:monospace;-inkscape-font-specification:monospace" x="362.371" y="262.51819" id="text4441" diff --git a/Documentation/RCU/Design/Expedited-Grace-Periods/Funnel6.svg b/Documentation/RCU/Design/Expedited-Grace-Periods/Funnel6.svg index fbd2c1892886..3e5651da031a 100644 --- a/Documentation/RCU/Design/Expedited-Grace-Periods/Funnel6.svg +++ b/Documentation/RCU/Design/Expedited-Grace-Periods/Funnel6.svg @@ -116,7 +116,7 @@ <flowRoot xml:space="preserve" id="flowRoot2985" - style="font-size:10px;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;text-align:center;line-height:125%;letter-spacing:0px;word-spacing:0px;writing-mode:lr-tb;text-anchor:middle;fill:#000000;fill-opacity:1;stroke:none;font-family:Symbol;-inkscape-font-specification:Symbol"><flowRegion + style="font-size:10px;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;text-align:center;line-height:125%;letter-spacing:0px;word-spacing:0px;writing-mode:lr-tb;text-anchor:middle;fill:#000000;fill-opacity:1;stroke:none;font-family:monospace;-inkscape-font-specification:monospace"><flowRegion id="flowRegion2987"><rect id="rect2989" width="82.85714" @@ -125,7 +125,7 @@ y="492.36218" /></flowRegion><flowPara id="flowPara2991" /></flowRoot> <text xml:space="preserve" - style="font-size:10px;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;text-align:center;line-height:125%;letter-spacing:0px;word-spacing:0px;writing-mode:lr-tb;text-anchor:middle;fill:#000000;fill-opacity:1;stroke:none;font-family:Symbol;-inkscape-font-specification:Symbol" + style="font-size:10px;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;text-align:center;line-height:125%;letter-spacing:0px;word-spacing:0px;writing-mode:lr-tb;text-anchor:middle;fill:#000000;fill-opacity:1;stroke:none;font-family:monospace;-inkscape-font-specification:monospace" x="362.371" y="262.51819" id="text4441" diff --git a/Documentation/RCU/Design/Expedited-Grace-Periods/Funnel7.svg b/Documentation/RCU/Design/Expedited-Grace-Periods/Funnel7.svg index 502e159ed278..9483f08d345e 100644 --- a/Documentation/RCU/Design/Expedited-Grace-Periods/Funnel7.svg +++ b/Documentation/RCU/Design/Expedited-Grace-Periods/Funnel7.svg @@ -116,7 +116,7 @@ <flowRoot xml:space="preserve" id="flowRoot2985" - style="font-size:10px;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;text-align:center;line-height:125%;letter-spacing:0px;word-spacing:0px;writing-mode:lr-tb;text-anchor:middle;fill:#000000;fill-opacity:1;stroke:none;font-family:Symbol;-inkscape-font-specification:Symbol"><flowRegion + style="font-size:10px;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;text-align:center;line-height:125%;letter-spacing:0px;word-spacing:0px;writing-mode:lr-tb;text-anchor:middle;fill:#000000;fill-opacity:1;stroke:none;font-family:monospace;-inkscape-font-specification:monospace"><flowRegion id="flowRegion2987"><rect id="rect2989" width="82.85714" @@ -125,7 +125,7 @@ y="492.36218" /></flowRegion><flowPara id="flowPara2991" /></flowRoot> <text xml:space="preserve" - style="font-size:10px;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;text-align:center;line-height:125%;letter-spacing:0px;word-spacing:0px;writing-mode:lr-tb;text-anchor:middle;fill:#000000;fill-opacity:1;stroke:none;font-family:Symbol;-inkscape-font-specification:Symbol" + style="font-size:10px;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;text-align:center;line-height:125%;letter-spacing:0px;word-spacing:0px;writing-mode:lr-tb;text-anchor:middle;fill:#000000;fill-opacity:1;stroke:none;font-family:monospace;-inkscape-font-specification:monospace" x="362.371" y="262.51819" id="text4441" diff --git a/Documentation/RCU/Design/Expedited-Grace-Periods/Funnel8.svg b/Documentation/RCU/Design/Expedited-Grace-Periods/Funnel8.svg index 677401551c7d..1101ec30e604 100644 --- a/Documentation/RCU/Design/Expedited-Grace-Periods/Funnel8.svg +++ b/Documentation/RCU/Design/Expedited-Grace-Periods/Funnel8.svg @@ -116,7 +116,7 @@ <flowRoot xml:space="preserve" id="flowRoot2985" - style="font-size:10px;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;text-align:center;line-height:125%;letter-spacing:0px;word-spacing:0px;writing-mode:lr-tb;text-anchor:middle;fill:#000000;fill-opacity:1;stroke:none;font-family:Symbol;-inkscape-font-specification:Symbol"><flowRegion + style="font-size:10px;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;text-align:center;line-height:125%;letter-spacing:0px;word-spacing:0px;writing-mode:lr-tb;text-anchor:middle;fill:#000000;fill-opacity:1;stroke:none;font-family:monospace;-inkscape-font-specification:monospace"><flowRegion id="flowRegion2987"><rect id="rect2989" width="82.85714" @@ -125,7 +125,7 @@ y="492.36218" /></flowRegion><flowPara id="flowPara2991" /></flowRoot> <text xml:space="preserve" - style="font-size:10px;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;text-align:center;line-height:125%;letter-spacing:0px;word-spacing:0px;writing-mode:lr-tb;text-anchor:middle;fill:#000000;fill-opacity:1;stroke:none;font-family:Symbol;-inkscape-font-specification:Symbol" + style="font-size:10px;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;text-align:center;line-height:125%;letter-spacing:0px;word-spacing:0px;writing-mode:lr-tb;text-anchor:middle;fill:#000000;fill-opacity:1;stroke:none;font-family:monospace;-inkscape-font-specification:monospace" x="362.371" y="262.51819" id="text4441" diff --git a/Documentation/RCU/Design/Requirements/GPpartitionReaders1.svg b/Documentation/RCU/Design/Requirements/GPpartitionReaders1.svg index 4b4014fda770..87851a8fac1e 100644 --- a/Documentation/RCU/Design/Requirements/GPpartitionReaders1.svg +++ b/Documentation/RCU/Design/Requirements/GPpartitionReaders1.svg @@ -88,7 +88,7 @@ <flowRoot xml:space="preserve" id="flowRoot2985" - style="font-size:10px;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;text-align:center;line-height:125%;letter-spacing:0px;word-spacing:0px;writing-mode:lr-tb;text-anchor:middle;fill:#000000;fill-opacity:1;stroke:none;font-family:Symbol;-inkscape-font-specification:Symbol"><flowRegion + style="font-size:10px;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;text-align:center;line-height:125%;letter-spacing:0px;word-spacing:0px;writing-mode:lr-tb;text-anchor:middle;fill:#000000;fill-opacity:1;stroke:none;font-family:monospace;-inkscape-font-specification:monospace"><flowRegion id="flowRegion2987"><rect id="rect2989" width="82.85714" @@ -103,7 +103,7 @@ id="text2993" y="-261.66608" x="412.12299" - style="font-size:10px;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;text-align:center;line-height:125%;letter-spacing:0px;word-spacing:0px;writing-mode:lr-tb;text-anchor:middle;fill:#000000;fill-opacity:1;stroke:none;font-family:Symbol;-inkscape-font-specification:Symbol" + style="font-size:10px;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;text-align:center;line-height:125%;letter-spacing:0px;word-spacing:0px;writing-mode:lr-tb;text-anchor:middle;fill:#000000;fill-opacity:1;stroke:none;font-family:monospace;-inkscape-font-specification:monospace" xml:space="preserve" transform="matrix(0,1,-1,0,0,0)"><tspan y="-261.66608" @@ -135,7 +135,7 @@ </g> <text xml:space="preserve" - style="font-size:10px;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;text-align:center;line-height:125%;letter-spacing:0px;word-spacing:0px;writing-mode:lr-tb;text-anchor:middle;fill:#000000;fill-opacity:1;stroke:none;font-family:Symbol;-inkscape-font-specification:Symbol" + style="font-size:10px;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;text-align:center;line-height:125%;letter-spacing:0px;word-spacing:0px;writing-mode:lr-tb;text-anchor:middle;fill:#000000;fill-opacity:1;stroke:none;font-family:monospace;-inkscape-font-specification:monospace" x="112.04738" y="268.18076" id="text4429" @@ -146,7 +146,7 @@ y="268.18076">WRITE_ONCE(a, 1);</tspan></text> <text xml:space="preserve" - style="font-size:10px;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;text-align:center;line-height:125%;letter-spacing:0px;word-spacing:0px;writing-mode:lr-tb;text-anchor:middle;fill:#000000;fill-opacity:1;stroke:none;font-family:Symbol;-inkscape-font-specification:Symbol" + style="font-size:10px;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;text-align:center;line-height:125%;letter-spacing:0px;word-spacing:0px;writing-mode:lr-tb;text-anchor:middle;fill:#000000;fill-opacity:1;stroke:none;font-family:monospace;-inkscape-font-specification:monospace" x="112.04738" y="439.13766" id="text4441" @@ -157,7 +157,7 @@ y="439.13766">WRITE_ONCE(b, 1);</tspan></text> <text xml:space="preserve" - style="font-size:10px;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;text-align:center;line-height:125%;letter-spacing:0px;word-spacing:0px;writing-mode:lr-tb;text-anchor:middle;fill:#000000;fill-opacity:1;stroke:none;font-family:Symbol;-inkscape-font-specification:Symbol" + style="font-size:10px;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;text-align:center;line-height:125%;letter-spacing:0px;word-spacing:0px;writing-mode:lr-tb;text-anchor:middle;fill:#000000;fill-opacity:1;stroke:none;font-family:monospace;-inkscape-font-specification:monospace" x="255.60869" y="309.29346" id="text4445" @@ -168,7 +168,7 @@ y="309.29346">r1 = READ_ONCE(a);</tspan></text> <text xml:space="preserve" - style="font-size:10px;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;text-align:center;line-height:125%;letter-spacing:0px;word-spacing:0px;writing-mode:lr-tb;text-anchor:middle;fill:#000000;fill-opacity:1;stroke:none;font-family:Symbol;-inkscape-font-specification:Symbol" + style="font-size:10px;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;text-align:center;line-height:125%;letter-spacing:0px;word-spacing:0px;writing-mode:lr-tb;text-anchor:middle;fill:#000000;fill-opacity:1;stroke:none;font-family:monospace;-inkscape-font-specification:monospace" x="255.14423" y="520.61786" id="text4449" @@ -179,7 +179,7 @@ y="520.61786">WRITE_ONCE(c, 1);</tspan></text> <text xml:space="preserve" - style="font-size:10px;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;text-align:center;line-height:125%;letter-spacing:0px;word-spacing:0px;writing-mode:lr-tb;text-anchor:middle;fill:#000000;fill-opacity:1;stroke:none;font-family:Symbol;-inkscape-font-specification:Symbol" + style="font-size:10px;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;text-align:center;line-height:125%;letter-spacing:0px;word-spacing:0px;writing-mode:lr-tb;text-anchor:middle;fill:#000000;fill-opacity:1;stroke:none;font-family:monospace;-inkscape-font-specification:monospace" x="396.10254" y="384.71124" id="text4453" @@ -190,7 +190,7 @@ y="384.71124">r2 = READ_ONCE(b);</tspan></text> <text xml:space="preserve" - style="font-size:10px;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;text-align:center;line-height:125%;letter-spacing:0px;word-spacing:0px;writing-mode:lr-tb;text-anchor:middle;fill:#000000;fill-opacity:1;stroke:none;font-family:Symbol;-inkscape-font-specification:Symbol" + style="font-size:10px;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;text-align:center;line-height:125%;letter-spacing:0px;word-spacing:0px;writing-mode:lr-tb;text-anchor:middle;fill:#000000;fill-opacity:1;stroke:none;font-family:monospace;-inkscape-font-specification:monospace" x="396.10254" y="582.13617" id="text4457" @@ -201,7 +201,7 @@ y="582.13617">r3 = READ_ONCE(c);</tspan></text> <text xml:space="preserve" - style="font-size:10px;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;text-align:center;line-height:125%;letter-spacing:0px;word-spacing:0px;writing-mode:lr-tb;text-anchor:middle;fill:#000000;fill-opacity:1;stroke:none;font-family:Symbol;-inkscape-font-specification:Symbol" + style="font-size:10px;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;text-align:center;line-height:125%;letter-spacing:0px;word-spacing:0px;writing-mode:lr-tb;text-anchor:middle;fill:#000000;fill-opacity:1;stroke:none;font-family:monospace;-inkscape-font-specification:monospace" x="112.08231" y="213.91006" id="text4461" @@ -212,7 +212,7 @@ y="213.91006">thread0()</tspan></text> <text xml:space="preserve" - style="font-size:10px;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;text-align:center;line-height:125%;letter-spacing:0px;word-spacing:0px;writing-mode:lr-tb;text-anchor:middle;fill:#000000;fill-opacity:1;stroke:none;font-family:Symbol;-inkscape-font-specification:Symbol" + style="font-size:10px;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;text-align:center;line-height:125%;letter-spacing:0px;word-spacing:0px;writing-mode:lr-tb;text-anchor:middle;fill:#000000;fill-opacity:1;stroke:none;font-family:monospace;-inkscape-font-specification:monospace" x="252.34512" y="213.91006" id="text4461-6" @@ -223,7 +223,7 @@ y="213.91006">thread1()</tspan></text> <text xml:space="preserve" - style="font-size:10px;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;text-align:center;line-height:125%;letter-spacing:0px;word-spacing:0px;writing-mode:lr-tb;text-anchor:middle;fill:#000000;fill-opacity:1;stroke:none;font-family:Symbol;-inkscape-font-specification:Symbol" + style="font-size:10px;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;text-align:center;line-height:125%;letter-spacing:0px;word-spacing:0px;writing-mode:lr-tb;text-anchor:middle;fill:#000000;fill-opacity:1;stroke:none;font-family:monospace;-inkscape-font-specification:monospace" x="396.42557" y="213.91006" id="text4461-2" @@ -251,7 +251,7 @@ inkscape:connector-curvature="0" /> <text xml:space="preserve" - style="font-size:10px;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;text-align:center;line-height:125%;letter-spacing:0px;word-spacing:0px;writing-mode:lr-tb;text-anchor:middle;fill:#000000;fill-opacity:1;stroke:none;font-family:Symbol;-inkscape-font-specification:Symbol" + style="font-size:10px;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;text-align:center;line-height:125%;letter-spacing:0px;word-spacing:0px;writing-mode:lr-tb;text-anchor:middle;fill:#000000;fill-opacity:1;stroke:none;font-family:monospace;-inkscape-font-specification:monospace" x="111.75929" y="251.53981" id="text4429-8" @@ -262,7 +262,7 @@ y="251.53981">rcu_read_lock();</tspan></text> <text xml:space="preserve" - style="font-size:10px;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;text-align:center;line-height:125%;letter-spacing:0px;word-spacing:0px;writing-mode:lr-tb;text-anchor:middle;fill:#000000;fill-opacity:1;stroke:none;font-family:Symbol;-inkscape-font-specification:Symbol" + style="font-size:10px;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;text-align:center;line-height:125%;letter-spacing:0px;word-spacing:0px;writing-mode:lr-tb;text-anchor:middle;fill:#000000;fill-opacity:1;stroke:none;font-family:monospace;-inkscape-font-specification:monospace" x="396.10254" y="367.91556" id="text4429-8-9" @@ -273,7 +273,7 @@ y="367.91556">rcu_read_lock();</tspan></text> <text xml:space="preserve" - style="font-size:10px;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;text-align:center;line-height:125%;letter-spacing:0px;word-spacing:0px;writing-mode:lr-tb;text-anchor:middle;fill:#000000;fill-opacity:1;stroke:none;font-family:Symbol;-inkscape-font-specification:Symbol" + style="font-size:10px;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;text-align:center;line-height:125%;letter-spacing:0px;word-spacing:0px;writing-mode:lr-tb;text-anchor:middle;fill:#000000;fill-opacity:1;stroke:none;font-family:monospace;-inkscape-font-specification:monospace" x="396.10254" y="597.40289" id="text4429-8-9-3" @@ -284,7 +284,7 @@ y="597.40289">rcu_read_unlock();</tspan></text> <text xml:space="preserve" - style="font-size:10px;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;text-align:center;line-height:125%;letter-spacing:0px;word-spacing:0px;writing-mode:lr-tb;text-anchor:middle;fill:#000000;fill-opacity:1;stroke:none;font-family:Symbol;-inkscape-font-specification:Symbol" + style="font-size:10px;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;text-align:center;line-height:125%;letter-spacing:0px;word-spacing:0px;writing-mode:lr-tb;text-anchor:middle;fill:#000000;fill-opacity:1;stroke:none;font-family:monospace;-inkscape-font-specification:monospace" x="111.75929" y="453.15311" id="text4429-8-9-3-1" @@ -300,7 +300,7 @@ inkscape:connector-curvature="0" /> <text xml:space="preserve" - style="font-size:10px;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;text-align:center;line-height:125%;letter-spacing:0px;word-spacing:0px;writing-mode:lr-tb;text-anchor:middle;fill:#000000;fill-opacity:1;stroke:none;font-family:Symbol;-inkscape-font-specification:Symbol" + style="font-size:10px;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;text-align:center;line-height:125%;letter-spacing:0px;word-spacing:0px;writing-mode:lr-tb;text-anchor:middle;fill:#000000;fill-opacity:1;stroke:none;font-family:monospace;-inkscape-font-specification:monospace" x="394.94427" y="345.66351" id="text4648" @@ -324,7 +324,7 @@ sodipodi:open="true" /> <text xml:space="preserve" - style="font-size:10px;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;text-align:center;line-height:125%;letter-spacing:0px;word-spacing:0px;writing-mode:lr-tb;text-anchor:middle;fill:#000000;fill-opacity:1;stroke:none;font-family:Symbol;-inkscape-font-specification:Symbol" + style="font-size:10px;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;text-align:center;line-height:125%;letter-spacing:0px;word-spacing:0px;writing-mode:lr-tb;text-anchor:middle;fill:#000000;fill-opacity:1;stroke:none;font-family:monospace;-inkscape-font-specification:monospace" x="112.11968" y="475.77856" id="text4648-4" @@ -361,7 +361,7 @@ sodipodi:open="true" /> <text xml:space="preserve" - style="font-size:10px;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;text-align:center;line-height:125%;letter-spacing:0px;word-spacing:0px;writing-mode:lr-tb;text-anchor:middle;fill:#000000;fill-opacity:1;stroke:none;font-family:Symbol;-inkscape-font-specification:Symbol" + style="font-size:10px;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;text-align:center;line-height:125%;letter-spacing:0px;word-spacing:0px;writing-mode:lr-tb;text-anchor:middle;fill:#000000;fill-opacity:1;stroke:none;font-family:monospace;-inkscape-font-specification:monospace" x="254.85066" y="348.96619" id="text4648-4-3" diff --git a/Documentation/RCU/Design/Requirements/ReadersPartitionGP1.svg b/Documentation/RCU/Design/Requirements/ReadersPartitionGP1.svg index 48cd1623d4d4..e2a8af592bab 100644 --- a/Documentation/RCU/Design/Requirements/ReadersPartitionGP1.svg +++ b/Documentation/RCU/Design/Requirements/ReadersPartitionGP1.svg @@ -116,7 +116,7 @@ <flowRoot xml:space="preserve" id="flowRoot2985" - style="font-size:10px;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;text-align:center;line-height:125%;letter-spacing:0px;word-spacing:0px;writing-mode:lr-tb;text-anchor:middle;fill:#000000;fill-opacity:1;stroke:none;font-family:Symbol;-inkscape-font-specification:Symbol"><flowRegion + style="font-size:10px;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;text-align:center;line-height:125%;letter-spacing:0px;word-spacing:0px;writing-mode:lr-tb;text-anchor:middle;fill:#000000;fill-opacity:1;stroke:none;font-family:monospace;-inkscape-font-specification:monospace"><flowRegion id="flowRegion2987"><rect id="rect2989" width="82.85714" @@ -131,7 +131,7 @@ id="text2993" y="-261.66608" x="436.12299" - style="font-size:10px;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;text-align:center;line-height:125%;letter-spacing:0px;word-spacing:0px;writing-mode:lr-tb;text-anchor:middle;fill:#000000;fill-opacity:1;stroke:none;font-family:Symbol;-inkscape-font-specification:Symbol" + style="font-size:10px;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;text-align:center;line-height:125%;letter-spacing:0px;word-spacing:0px;writing-mode:lr-tb;text-anchor:middle;fill:#000000;fill-opacity:1;stroke:none;font-family:monospace;-inkscape-font-specification:monospace" xml:space="preserve" transform="matrix(0,1,-1,0,0,0)"><tspan y="-261.66608" @@ -163,7 +163,7 @@ </g> <text xml:space="preserve" - style="font-size:10px;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;text-align:center;line-height:125%;letter-spacing:0px;word-spacing:0px;writing-mode:lr-tb;text-anchor:middle;fill:#000000;fill-opacity:1;stroke:none;font-family:Symbol;-inkscape-font-specification:Symbol" + style="font-size:10px;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;text-align:center;line-height:125%;letter-spacing:0px;word-spacing:0px;writing-mode:lr-tb;text-anchor:middle;fill:#000000;fill-opacity:1;stroke:none;font-family:monospace;-inkscape-font-specification:monospace" x="112.04738" y="268.18076" id="text4429" @@ -174,7 +174,7 @@ y="268.18076">WRITE_ONCE(a, 1);</tspan></text> <text xml:space="preserve" - style="font-size:10px;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;text-align:center;line-height:125%;letter-spacing:0px;word-spacing:0px;writing-mode:lr-tb;text-anchor:middle;fill:#000000;fill-opacity:1;stroke:none;font-family:Symbol;-inkscape-font-specification:Symbol" + style="font-size:10px;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;text-align:center;line-height:125%;letter-spacing:0px;word-spacing:0px;writing-mode:lr-tb;text-anchor:middle;fill:#000000;fill-opacity:1;stroke:none;font-family:monospace;-inkscape-font-specification:monospace" x="112.04738" y="487.13766" id="text4441" @@ -185,7 +185,7 @@ y="487.13766">WRITE_ONCE(b, 1);</tspan></text> <text xml:space="preserve" - style="font-size:10px;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;text-align:center;line-height:125%;letter-spacing:0px;word-spacing:0px;writing-mode:lr-tb;text-anchor:middle;fill:#000000;fill-opacity:1;stroke:none;font-family:Symbol;-inkscape-font-specification:Symbol" + style="font-size:10px;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;text-align:center;line-height:125%;letter-spacing:0px;word-spacing:0px;writing-mode:lr-tb;text-anchor:middle;fill:#000000;fill-opacity:1;stroke:none;font-family:monospace;-inkscape-font-specification:monospace" x="255.60869" y="297.29346" id="text4445" @@ -196,7 +196,7 @@ y="297.29346">r1 = READ_ONCE(a);</tspan></text> <text xml:space="preserve" - style="font-size:10px;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;text-align:center;line-height:125%;letter-spacing:0px;word-spacing:0px;writing-mode:lr-tb;text-anchor:middle;fill:#000000;fill-opacity:1;stroke:none;font-family:Symbol;-inkscape-font-specification:Symbol" + style="font-size:10px;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;text-align:center;line-height:125%;letter-spacing:0px;word-spacing:0px;writing-mode:lr-tb;text-anchor:middle;fill:#000000;fill-opacity:1;stroke:none;font-family:monospace;-inkscape-font-specification:monospace" x="255.14423" y="554.61786" id="text4449" @@ -207,7 +207,7 @@ y="554.61786">WRITE_ONCE(c, 1);</tspan></text> <text xml:space="preserve" - style="font-size:10px;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;text-align:center;line-height:125%;letter-spacing:0px;word-spacing:0px;writing-mode:lr-tb;text-anchor:middle;fill:#000000;fill-opacity:1;stroke:none;font-family:Symbol;-inkscape-font-specification:Symbol" + style="font-size:10px;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;text-align:center;line-height:125%;letter-spacing:0px;word-spacing:0px;writing-mode:lr-tb;text-anchor:middle;fill:#000000;fill-opacity:1;stroke:none;font-family:monospace;-inkscape-font-specification:monospace" x="396.10254" y="370.71124" id="text4453" @@ -218,7 +218,7 @@ y="370.71124">WRITE_ONCE(d, 1);</tspan></text> <text xml:space="preserve" - style="font-size:10px;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;text-align:center;line-height:125%;letter-spacing:0px;word-spacing:0px;writing-mode:lr-tb;text-anchor:middle;fill:#000000;fill-opacity:1;stroke:none;font-family:Symbol;-inkscape-font-specification:Symbol" + style="font-size:10px;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;text-align:center;line-height:125%;letter-spacing:0px;word-spacing:0px;writing-mode:lr-tb;text-anchor:middle;fill:#000000;fill-opacity:1;stroke:none;font-family:monospace;-inkscape-font-specification:monospace" x="396.10254" y="572.13617" id="text4457" @@ -229,7 +229,7 @@ y="572.13617">r2 = READ_ONCE(c);</tspan></text> <text xml:space="preserve" - style="font-size:10px;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;text-align:center;line-height:125%;letter-spacing:0px;word-spacing:0px;writing-mode:lr-tb;text-anchor:middle;fill:#000000;fill-opacity:1;stroke:none;font-family:Symbol;-inkscape-font-specification:Symbol" + style="font-size:10px;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;text-align:center;line-height:125%;letter-spacing:0px;word-spacing:0px;writing-mode:lr-tb;text-anchor:middle;fill:#000000;fill-opacity:1;stroke:none;font-family:monospace;-inkscape-font-specification:monospace" x="112.08231" y="213.91006" id="text4461" @@ -240,7 +240,7 @@ y="213.91006">thread0()</tspan></text> <text xml:space="preserve" - style="font-size:10px;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;text-align:center;line-height:125%;letter-spacing:0px;word-spacing:0px;writing-mode:lr-tb;text-anchor:middle;fill:#000000;fill-opacity:1;stroke:none;font-family:Symbol;-inkscape-font-specification:Symbol" + style="font-size:10px;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;text-align:center;line-height:125%;letter-spacing:0px;word-spacing:0px;writing-mode:lr-tb;text-anchor:middle;fill:#000000;fill-opacity:1;stroke:none;font-family:monospace;-inkscape-font-specification:monospace" x="252.34512" y="213.91006" id="text4461-6" @@ -251,7 +251,7 @@ y="213.91006">thread1()</tspan></text> <text xml:space="preserve" - style="font-size:10px;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;text-align:center;line-height:125%;letter-spacing:0px;word-spacing:0px;writing-mode:lr-tb;text-anchor:middle;fill:#000000;fill-opacity:1;stroke:none;font-family:Symbol;-inkscape-font-specification:Symbol" + style="font-size:10px;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;text-align:center;line-height:125%;letter-spacing:0px;word-spacing:0px;writing-mode:lr-tb;text-anchor:middle;fill:#000000;fill-opacity:1;stroke:none;font-family:monospace;-inkscape-font-specification:monospace" x="396.42557" y="213.91006" id="text4461-2" @@ -281,7 +281,7 @@ sodipodi:nodetypes="cc" /> <text xml:space="preserve" - style="font-size:10px;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;text-align:center;line-height:125%;letter-spacing:0px;word-spacing:0px;writing-mode:lr-tb;text-anchor:middle;fill:#000000;fill-opacity:1;stroke:none;font-family:Symbol;-inkscape-font-specification:Symbol" + style="font-size:10px;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;text-align:center;line-height:125%;letter-spacing:0px;word-spacing:0px;writing-mode:lr-tb;text-anchor:middle;fill:#000000;fill-opacity:1;stroke:none;font-family:monospace;-inkscape-font-specification:monospace" x="111.75929" y="251.53981" id="text4429-8" @@ -292,7 +292,7 @@ y="251.53981">rcu_read_lock();</tspan></text> <text xml:space="preserve" - style="font-size:10px;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;text-align:center;line-height:125%;letter-spacing:0px;word-spacing:0px;writing-mode:lr-tb;text-anchor:middle;fill:#000000;fill-opacity:1;stroke:none;font-family:Symbol;-inkscape-font-specification:Symbol" + style="font-size:10px;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;text-align:center;line-height:125%;letter-spacing:0px;word-spacing:0px;writing-mode:lr-tb;text-anchor:middle;fill:#000000;fill-opacity:1;stroke:none;font-family:monospace;-inkscape-font-specification:monospace" x="396.10254" y="353.91556" id="text4429-8-9" @@ -303,7 +303,7 @@ y="353.91556">rcu_read_lock();</tspan></text> <text xml:space="preserve" - style="font-size:10px;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;text-align:center;line-height:125%;letter-spacing:0px;word-spacing:0px;writing-mode:lr-tb;text-anchor:middle;fill:#000000;fill-opacity:1;stroke:none;font-family:Symbol;-inkscape-font-specification:Symbol" + style="font-size:10px;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;text-align:center;line-height:125%;letter-spacing:0px;word-spacing:0px;writing-mode:lr-tb;text-anchor:middle;fill:#000000;fill-opacity:1;stroke:none;font-family:monospace;-inkscape-font-specification:monospace" x="396.10254" y="587.40289" id="text4429-8-9-3" @@ -314,7 +314,7 @@ y="587.40289">rcu_read_unlock();</tspan></text> <text xml:space="preserve" - style="font-size:10px;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;text-align:center;line-height:125%;letter-spacing:0px;word-spacing:0px;writing-mode:lr-tb;text-anchor:middle;fill:#000000;fill-opacity:1;stroke:none;font-family:Symbol;-inkscape-font-specification:Symbol" + style="font-size:10px;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;text-align:center;line-height:125%;letter-spacing:0px;word-spacing:0px;writing-mode:lr-tb;text-anchor:middle;fill:#000000;fill-opacity:1;stroke:none;font-family:monospace;-inkscape-font-specification:monospace" x="111.75929" y="501.15311" id="text4429-8-9-3-1" @@ -331,7 +331,7 @@ sodipodi:nodetypes="cc" /> <text xml:space="preserve" - style="font-size:10px;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;text-align:center;line-height:125%;letter-spacing:0px;word-spacing:0px;writing-mode:lr-tb;text-anchor:middle;fill:#000000;fill-opacity:1;stroke:none;font-family:Symbol;-inkscape-font-specification:Symbol" + style="font-size:10px;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;text-align:center;line-height:125%;letter-spacing:0px;word-spacing:0px;writing-mode:lr-tb;text-anchor:middle;fill:#000000;fill-opacity:1;stroke:none;font-family:monospace;-inkscape-font-specification:monospace" x="394.94427" y="331.66351" id="text4648" @@ -355,7 +355,7 @@ sodipodi:open="true" /> <text xml:space="preserve" - style="font-size:10px;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;text-align:center;line-height:125%;letter-spacing:0px;word-spacing:0px;writing-mode:lr-tb;text-anchor:middle;fill:#000000;fill-opacity:1;stroke:none;font-family:Symbol;-inkscape-font-specification:Symbol" + style="font-size:10px;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;text-align:center;line-height:125%;letter-spacing:0px;word-spacing:0px;writing-mode:lr-tb;text-anchor:middle;fill:#000000;fill-opacity:1;stroke:none;font-family:monospace;-inkscape-font-specification:monospace" x="112.11968" y="523.77856" id="text4648-4" @@ -392,7 +392,7 @@ sodipodi:open="true" /> <text xml:space="preserve" - style="font-size:10px;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;text-align:center;line-height:125%;letter-spacing:0px;word-spacing:0px;writing-mode:lr-tb;text-anchor:middle;fill:#000000;fill-opacity:1;stroke:none;font-family:Symbol;-inkscape-font-specification:Symbol" + style="font-size:10px;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;text-align:center;line-height:125%;letter-spacing:0px;word-spacing:0px;writing-mode:lr-tb;text-anchor:middle;fill:#000000;fill-opacity:1;stroke:none;font-family:monospace;-inkscape-font-specification:monospace" x="254.85066" y="336.96619" id="text4648-4-3" @@ -421,7 +421,7 @@ id="text2993-7" y="-261.66608" x="440.12299" - style="font-size:10px;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;text-align:center;line-height:125%;letter-spacing:0px;word-spacing:0px;writing-mode:lr-tb;text-anchor:middle;fill:#000000;fill-opacity:1;stroke:none;font-family:Symbol;-inkscape-font-specification:Symbol" + style="font-size:10px;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;text-align:center;line-height:125%;letter-spacing:0px;word-spacing:0px;writing-mode:lr-tb;text-anchor:middle;fill:#000000;fill-opacity:1;stroke:none;font-family:monospace;-inkscape-font-specification:monospace" xml:space="preserve" transform="matrix(0,1,-1,0,0,0)"><tspan y="-261.66608" @@ -453,7 +453,7 @@ </g> <text xml:space="preserve" - style="font-size:10px;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;text-align:center;line-height:125%;letter-spacing:0px;word-spacing:0px;writing-mode:lr-tb;text-anchor:middle;fill:#000000;fill-opacity:1;stroke:none;font-family:Symbol;-inkscape-font-specification:Symbol" + style="font-size:10px;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;text-align:center;line-height:125%;letter-spacing:0px;word-spacing:0px;writing-mode:lr-tb;text-anchor:middle;fill:#000000;fill-opacity:1;stroke:none;font-family:monospace;-inkscape-font-specification:monospace" x="541.70508" y="387.6217" id="text4445-0" @@ -464,7 +464,7 @@ y="387.6217">r3 = READ_ONCE(d);</tspan></text> <text xml:space="preserve" - style="font-size:10px;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;text-align:center;line-height:125%;letter-spacing:0px;word-spacing:0px;writing-mode:lr-tb;text-anchor:middle;fill:#000000;fill-opacity:1;stroke:none;font-family:Symbol;-inkscape-font-specification:Symbol" + style="font-size:10px;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;text-align:center;line-height:125%;letter-spacing:0px;word-spacing:0px;writing-mode:lr-tb;text-anchor:middle;fill:#000000;fill-opacity:1;stroke:none;font-family:monospace;-inkscape-font-specification:monospace" x="541.2406" y="646.94611" id="text4449-6" @@ -488,7 +488,7 @@ sodipodi:open="true" /> <text xml:space="preserve" - style="font-size:10px;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;text-align:center;line-height:125%;letter-spacing:0px;word-spacing:0px;writing-mode:lr-tb;text-anchor:middle;fill:#000000;fill-opacity:1;stroke:none;font-family:Symbol;-inkscape-font-specification:Symbol" + style="font-size:10px;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;text-align:center;line-height:125%;letter-spacing:0px;word-spacing:0px;writing-mode:lr-tb;text-anchor:middle;fill:#000000;fill-opacity:1;stroke:none;font-family:monospace;-inkscape-font-specification:monospace" x="540.94702" y="427.29443" id="text4648-4-3-1" @@ -499,7 +499,7 @@ y="427.29443">QS</tspan></text> <text xml:space="preserve" - style="font-size:10px;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;text-align:center;line-height:125%;letter-spacing:0px;word-spacing:0px;writing-mode:lr-tb;text-anchor:middle;fill:#000000;fill-opacity:1;stroke:none;font-family:Symbol;-inkscape-font-specification:Symbol" + style="font-size:10px;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;text-align:center;line-height:125%;letter-spacing:0px;word-spacing:0px;writing-mode:lr-tb;text-anchor:middle;fill:#000000;fill-opacity:1;stroke:none;font-family:monospace;-inkscape-font-specification:monospace" x="686.27747" y="461.83929" id="text4453-7" @@ -510,7 +510,7 @@ y="461.83929">r4 = READ_ONCE(b);</tspan></text> <text xml:space="preserve" - style="font-size:10px;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;text-align:center;line-height:125%;letter-spacing:0px;word-spacing:0px;writing-mode:lr-tb;text-anchor:middle;fill:#000000;fill-opacity:1;stroke:none;font-family:Symbol;-inkscape-font-specification:Symbol" + style="font-size:10px;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;text-align:center;line-height:125%;letter-spacing:0px;word-spacing:0px;writing-mode:lr-tb;text-anchor:middle;fill:#000000;fill-opacity:1;stroke:none;font-family:monospace;-inkscape-font-specification:monospace" x="686.27747" y="669.26422" id="text4457-9" @@ -521,7 +521,7 @@ y="669.26422">r5 = READ_ONCE(e);</tspan></text> <text xml:space="preserve" - style="font-size:10px;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;text-align:center;line-height:125%;letter-spacing:0px;word-spacing:0px;writing-mode:lr-tb;text-anchor:middle;fill:#000000;fill-opacity:1;stroke:none;font-family:Symbol;-inkscape-font-specification:Symbol" + style="font-size:10px;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;text-align:center;line-height:125%;letter-spacing:0px;word-spacing:0px;writing-mode:lr-tb;text-anchor:middle;fill:#000000;fill-opacity:1;stroke:none;font-family:monospace;-inkscape-font-specification:monospace" x="686.27747" y="445.04358" id="text4429-8-9-33" @@ -532,7 +532,7 @@ y="445.04358">rcu_read_lock();</tspan></text> <text xml:space="preserve" - style="font-size:10px;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;text-align:center;line-height:125%;letter-spacing:0px;word-spacing:0px;writing-mode:lr-tb;text-anchor:middle;fill:#000000;fill-opacity:1;stroke:none;font-family:Symbol;-inkscape-font-specification:Symbol" + style="font-size:10px;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;text-align:center;line-height:125%;letter-spacing:0px;word-spacing:0px;writing-mode:lr-tb;text-anchor:middle;fill:#000000;fill-opacity:1;stroke:none;font-family:monospace;-inkscape-font-specification:monospace" x="686.27747" y="684.53094" id="text4429-8-9-3-8" @@ -543,7 +543,7 @@ y="684.53094">rcu_read_unlock();</tspan></text> <text xml:space="preserve" - style="font-size:10px;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;text-align:center;line-height:125%;letter-spacing:0px;word-spacing:0px;writing-mode:lr-tb;text-anchor:middle;fill:#000000;fill-opacity:1;stroke:none;font-family:Symbol;-inkscape-font-specification:Symbol" + style="font-size:10px;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;text-align:center;line-height:125%;letter-spacing:0px;word-spacing:0px;writing-mode:lr-tb;text-anchor:middle;fill:#000000;fill-opacity:1;stroke:none;font-family:monospace;-inkscape-font-specification:monospace" x="685.11914" y="422.79153" id="text4648-9" @@ -567,7 +567,7 @@ sodipodi:open="true" /> <text xml:space="preserve" - style="font-size:10px;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;text-align:center;line-height:125%;letter-spacing:0px;word-spacing:0px;writing-mode:lr-tb;text-anchor:middle;fill:#000000;fill-opacity:1;stroke:none;font-family:Symbol;-inkscape-font-specification:Symbol" + style="font-size:10px;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;text-align:center;line-height:125%;letter-spacing:0px;word-spacing:0px;writing-mode:lr-tb;text-anchor:middle;fill:#000000;fill-opacity:1;stroke:none;font-family:monospace;-inkscape-font-specification:monospace" x="397.85934" y="609.59003" id="text4648-5" @@ -591,7 +591,7 @@ sodipodi:open="true" /> <text xml:space="preserve" - style="font-size:10px;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;text-align:center;line-height:125%;letter-spacing:0px;word-spacing:0px;writing-mode:lr-tb;text-anchor:middle;fill:#000000;fill-opacity:1;stroke:none;font-family:Symbol;-inkscape-font-specification:Symbol" + style="font-size:10px;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;text-align:center;line-height:125%;letter-spacing:0px;word-spacing:0px;writing-mode:lr-tb;text-anchor:middle;fill:#000000;fill-opacity:1;stroke:none;font-family:monospace;-inkscape-font-specification:monospace" x="256.75986" y="586.99133" id="text4648-5-2" @@ -615,7 +615,7 @@ sodipodi:open="true" /> <text xml:space="preserve" - style="font-size:10px;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;text-align:center;line-height:125%;letter-spacing:0px;word-spacing:0px;writing-mode:lr-tb;text-anchor:middle;fill:#000000;fill-opacity:1;stroke:none;font-family:Symbol;-inkscape-font-specification:Symbol" + style="font-size:10px;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;text-align:center;line-height:125%;letter-spacing:0px;word-spacing:0px;writing-mode:lr-tb;text-anchor:middle;fill:#000000;fill-opacity:1;stroke:none;font-family:monospace;-inkscape-font-specification:monospace" x="546.22791" y="213.91006" id="text4461-2-5" @@ -626,7 +626,7 @@ y="213.91006">thread3()</tspan></text> <text xml:space="preserve" - style="font-size:10px;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;text-align:center;line-height:125%;letter-spacing:0px;word-spacing:0px;writing-mode:lr-tb;text-anchor:middle;fill:#000000;fill-opacity:1;stroke:none;font-family:Symbol;-inkscape-font-specification:Symbol" + style="font-size:10px;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;text-align:center;line-height:125%;letter-spacing:0px;word-spacing:0px;writing-mode:lr-tb;text-anchor:middle;fill:#000000;fill-opacity:1;stroke:none;font-family:monospace;-inkscape-font-specification:monospace" x="684.00067" y="213.91006" id="text4461-2-1" diff --git a/Documentation/RCU/stallwarn.rst b/Documentation/RCU/stallwarn.rst index 28f8ad16db25..78404625bad2 100644 --- a/Documentation/RCU/stallwarn.rst +++ b/Documentation/RCU/stallwarn.rst @@ -254,17 +254,6 @@ period (in this case 2603), the grace-period sequence number (7075), and an estimate of the total number of RCU callbacks queued across all CPUs (625 in this case). -In kernels with CONFIG_RCU_FAST_NO_HZ, more information is printed -for each CPU:: - - 0: (64628 ticks this GP) idle=dd5/3fffffffffffffff/0 softirq=82/543 last_accelerate: a345/d342 dyntick_enabled: 1 - -The "last_accelerate:" prints the low-order 16 bits (in hex) of the -jiffies counter when this CPU last invoked rcu_try_advance_all_cbs() -from rcu_needs_cpu() or last invoked rcu_accelerate_cbs() from -rcu_prepare_for_idle(). "dyntick_enabled: 1" indicates that dyntick-idle -processing is enabled. - If the grace period ends just as the stall warning starts printing, there will be a spurious stall-warning message, which will include the following:: diff --git a/Documentation/RCU/whatisRCU.rst b/Documentation/RCU/whatisRCU.rst index 17e95ab2a201..c34d2212eaca 100644 --- a/Documentation/RCU/whatisRCU.rst +++ b/Documentation/RCU/whatisRCU.rst @@ -39,9 +39,11 @@ different paths, as follows: :ref:`6. ANALOGY WITH READER-WRITER LOCKING <6_whatisRCU>` -:ref:`7. FULL LIST OF RCU APIs <7_whatisRCU>` +:ref:`7. ANALOGY WITH REFERENCE COUNTING <7_whatisRCU>` -:ref:`8. ANSWERS TO QUICK QUIZZES <8_whatisRCU>` +:ref:`8. FULL LIST OF RCU APIs <8_whatisRCU>` + +:ref:`9. ANSWERS TO QUICK QUIZZES <9_whatisRCU>` People who prefer starting with a conceptual overview should focus on Section 1, though most readers will profit by reading this section at @@ -677,7 +679,7 @@ Quick Quiz #1: occur when using this algorithm in a real-world Linux kernel? How could this deadlock be avoided? -:ref:`Answers to Quick Quiz <8_whatisRCU>` +:ref:`Answers to Quick Quiz <9_whatisRCU>` 5B. "TOY" EXAMPLE #2: CLASSIC RCU ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ @@ -732,7 +734,7 @@ Quick Quiz #2: Give an example where Classic RCU's read-side overhead is **negative**. -:ref:`Answers to Quick Quiz <8_whatisRCU>` +:ref:`Answers to Quick Quiz <9_whatisRCU>` .. _quiz_3: @@ -741,7 +743,7 @@ Quick Quiz #3: critical section, what the heck do you do in CONFIG_PREEMPT_RT, where normal spinlocks can block??? -:ref:`Answers to Quick Quiz <8_whatisRCU>` +:ref:`Answers to Quick Quiz <9_whatisRCU>` .. _6_whatisRCU: @@ -872,7 +874,79 @@ be used in place of synchronize_rcu(). .. _7_whatisRCU: -7. FULL LIST OF RCU APIs +7. ANALOGY WITH REFERENCE COUNTING +----------------------------------- + +The reader-writer analogy (illustrated by the previous section) is not +always the best way to think about using RCU. Another helpful analogy +considers RCU an effective reference count on everything which is +protected by RCU. + +A reference count typically does not prevent the referenced object's +values from changing, but does prevent changes to type -- particularly the +gross change of type that happens when that object's memory is freed and +re-allocated for some other purpose. Once a type-safe reference to the +object is obtained, some other mechanism is needed to ensure consistent +access to the data in the object. This could involve taking a spinlock, +but with RCU the typical approach is to perform reads with SMP-aware +operations such as smp_load_acquire(), to perform updates with atomic +read-modify-write operations, and to provide the necessary ordering. +RCU provides a number of support functions that embed the required +operations and ordering, such as the list_for_each_entry_rcu() macro +used in the previous section. + +A more focused view of the reference counting behavior is that, +between rcu_read_lock() and rcu_read_unlock(), any reference taken with +rcu_dereference() on a pointer marked as ``__rcu`` can be treated as +though a reference-count on that object has been temporarily increased. +This prevents the object from changing type. Exactly what this means +will depend on normal expectations of objects of that type, but it +typically includes that spinlocks can still be safely locked, normal +reference counters can be safely manipulated, and ``__rcu`` pointers +can be safely dereferenced. + +Some operations that one might expect to see on an object for +which an RCU reference is held include: + + - Copying out data that is guaranteed to be stable by the object's type. + - Using kref_get_unless_zero() or similar to get a longer-term + reference. This may fail of course. + - Acquiring a spinlock in the object, and checking if the object still + is the expected object and if so, manipulating it freely. + +The understanding that RCU provides a reference that only prevents a +change of type is particularly visible with objects allocated from a +slab cache marked ``SLAB_TYPESAFE_BY_RCU``. RCU operations may yield a +reference to an object from such a cache that has been concurrently +freed and the memory reallocated to a completely different object, +though of the same type. In this case RCU doesn't even protect the +identity of the object from changing, only its type. So the object +found may not be the one expected, but it will be one where it is safe +to take a reference or spinlock and then confirm that the identity +matches the expectations. + +With traditional reference counting -- such as that implemented by the +kref library in Linux -- there is typically code that runs when the last +reference to an object is dropped. With kref, this is the function +passed to kref_put(). When RCU is being used, such finalization code +must not be run until all ``__rcu`` pointers referencing the object have +been updated, and then a grace period has passed. Every remaining +globally visible pointer to the object must be considered to be a +potential counted reference, and the finalization code is typically run +using call_rcu() only after all those pointers have been changed. + +To see how to choose between these two analogies -- of RCU as a +reader-writer lock and RCU as a reference counting system -- it is useful +to reflect on the scale of the thing being protected. The reader-writer +lock analogy looks at larger multi-part objects such as a linked list +and shows how RCU can facilitate concurrency while elements are added +to, and removed from, the list. The reference-count analogy looks at +the individual objects and looks at how they can be accessed safely +within whatever whole they are a part of. + +.. _8_whatisRCU: + +8. FULL LIST OF RCU APIs ------------------------- The RCU APIs are documented in docbook-format header comments in the @@ -1035,9 +1109,9 @@ g. Otherwise, use RCU. Of course, this all assumes that you have determined that RCU is in fact the right tool for your job. -.. _8_whatisRCU: +.. _9_whatisRCU: -8. ANSWERS TO QUICK QUIZZES +9. ANSWERS TO QUICK QUIZZES ---------------------------- Quick Quiz #1: diff --git a/Documentation/admin-guide/acpi/cppc_sysfs.rst b/Documentation/admin-guide/acpi/cppc_sysfs.rst index fccf22114e85..e53d76365aa7 100644 --- a/Documentation/admin-guide/acpi/cppc_sysfs.rst +++ b/Documentation/admin-guide/acpi/cppc_sysfs.rst @@ -4,6 +4,8 @@ Collaborative Processor Performance Control (CPPC) ================================================== +.. _cppc_sysfs: + CPPC ==== diff --git a/Documentation/admin-guide/blockdev/drbd/figures.rst b/Documentation/admin-guide/blockdev/drbd/figures.rst index bd9a4901fe46..9f73253ea353 100644 --- a/Documentation/admin-guide/blockdev/drbd/figures.rst +++ b/Documentation/admin-guide/blockdev/drbd/figures.rst @@ -25,6 +25,6 @@ Sub graphs of DRBD's state transitions :alt: disk-states-8.dot :align: center -.. kernel-figure:: node-states-8.dot - :alt: node-states-8.dot +.. kernel-figure:: peer-states-8.dot + :alt: peer-states-8.dot :align: center diff --git a/Documentation/admin-guide/blockdev/drbd/node-states-8.dot b/Documentation/admin-guide/blockdev/drbd/peer-states-8.dot index bfa54e1f8016..6dc3954954d6 100644 --- a/Documentation/admin-guide/blockdev/drbd/node-states-8.dot +++ b/Documentation/admin-guide/blockdev/drbd/peer-states-8.dot @@ -1,8 +1,3 @@ -digraph node_states { - Secondary -> Primary [ label = "ioctl_set_state()" ] - Primary -> Secondary [ label = "ioctl_set_state()" ] -} - digraph peer_states { Secondary -> Primary [ label = "recv state packet" ] Primary -> Secondary [ label = "recv state packet" ] diff --git a/Documentation/admin-guide/cifs/usage.rst b/Documentation/admin-guide/cifs/usage.rst index f170d8820258..3766bf8a1c20 100644 --- a/Documentation/admin-guide/cifs/usage.rst +++ b/Documentation/admin-guide/cifs/usage.rst @@ -734,10 +734,9 @@ SecurityFlags Flags which control security negotiation and using weaker password hashes is 0x37037 (lanman, plaintext, ntlm, ntlmv2, signing allowed). Some SecurityFlags require the corresponding menuconfig - options to be enabled (lanman and plaintext require - CONFIG_CIFS_WEAK_PW_HASH for example). Enabling - plaintext authentication currently requires also - enabling lanman authentication in the security flags + options to be enabled. Enabling plaintext + authentication currently requires also enabling + lanman authentication in the security flags because the cifs module only supports sending laintext passwords using the older lanman dialect form of the session setup SMB. (e.g. for authentication diff --git a/Documentation/admin-guide/devices.txt b/Documentation/admin-guide/devices.txt index 922c23bb4372..c07dc0ee860e 100644 --- a/Documentation/admin-guide/devices.txt +++ b/Documentation/admin-guide/devices.txt @@ -2339,13 +2339,7 @@ disks (see major number 3) except that the limit on partitions is 31. - 162 char Raw block device interface - 0 = /dev/rawctl Raw I/O control device - 1 = /dev/raw/raw1 First raw I/O device - 2 = /dev/raw/raw2 Second raw I/O device - ... - max minor number of raw device is set by kernel config - MAX_RAW_DEVS or raw module parameter 'max_raw_devs' + 162 char Used for (now removed) raw block device interface 163 char diff --git a/Documentation/admin-guide/gpio/gpio-sim.rst b/Documentation/admin-guide/gpio/gpio-sim.rst new file mode 100644 index 000000000000..d8a90c81b9ee --- /dev/null +++ b/Documentation/admin-guide/gpio/gpio-sim.rst @@ -0,0 +1,134 @@ +.. SPDX-License-Identifier: GPL-2.0-or-later + +Configfs GPIO Simulator +======================= + +The configfs GPIO Simulator (gpio-sim) provides a way to create simulated GPIO +chips for testing purposes. The lines exposed by these chips can be accessed +using the standard GPIO character device interface as well as manipulated +using sysfs attributes. + +Creating simulated chips +------------------------ + +The gpio-sim module registers a configfs subsystem called ``'gpio-sim'``. For +details of the configfs filesystem, please refer to the configfs documentation. + +The user can create a hierarchy of configfs groups and items as well as modify +values of exposed attributes. Once the chip is instantiated, this hierarchy +will be translated to appropriate device properties. The general structure is: + +**Group:** ``/config/gpio-sim`` + +This is the top directory of the gpio-sim configfs tree. + +**Group:** ``/config/gpio-sim/gpio-device`` + +**Attribute:** ``/config/gpio-sim/gpio-device/dev_name`` + +**Attribute:** ``/config/gpio-sim/gpio-device/live`` + +This is a directory representing a GPIO platform device. The ``'dev_name'`` +attribute is read-only and allows the user-space to read the platform device +name (e.g. ``'gpio-sim.0'``). The ``'live'`` attribute allows to trigger the +actual creation of the device once it's fully configured. The accepted values +are: ``'1'`` to enable the simulated device and ``'0'`` to disable and tear +it down. + +**Group:** ``/config/gpio-sim/gpio-device/gpio-bankX`` + +**Attribute:** ``/config/gpio-sim/gpio-device/gpio-bankX/chip_name`` + +**Attribute:** ``/config/gpio-sim/gpio-device/gpio-bankX/num_lines`` + +This group represents a bank of GPIOs under the top platform device. The +``'chip_name'`` attribute is read-only and allows the user-space to read the +device name of the bank device. The ``'num_lines'`` attribute allows to specify +the number of lines exposed by this bank. + +**Group:** ``/config/gpio-sim/gpio-device/gpio-bankX/lineY`` + +**Attribute:** ``/config/gpio-sim/gpio-device/gpio-bankX/lineY/name`` + +This group represents a single line at the offset Y. The 'name' attribute +allows to set the line name as represented by the 'gpio-line-names' property. + +**Item:** ``/config/gpio-sim/gpio-device/gpio-bankX/lineY/hog`` + +**Attribute:** ``/config/gpio-sim/gpio-device/gpio-bankX/lineY/hog/name`` + +**Attribute:** ``/config/gpio-sim/gpio-device/gpio-bankX/lineY/hog/direction`` + +This item makes the gpio-sim module hog the associated line. The ``'name'`` +attribute specifies the in-kernel consumer name to use. The ``'direction'`` +attribute specifies the hog direction and must be one of: ``'input'``, +``'output-high'`` and ``'output-low'``. + +Inside each bank directory, there's a set of attributes that can be used to +configure the new chip. Additionally the user can ``mkdir()`` subdirectories +inside the chip's directory that allow to pass additional configuration for +specific lines. The name of those subdirectories must take the form of: +``'line<offset>'`` (e.g. ``'line0'``, ``'line20'``, etc.) as the name will be +used by the module to assign the config to the specific line at given offset. + +Once the confiuration is complete, the ``'live'`` attribute must be set to 1 in +order to instantiate the chip. It can be set back to 0 to destroy the simulated +chip. The module will synchronously wait for the new simulated device to be +successfully probed and if this doesn't happen, writing to ``'live'`` will +result in an error. + +Simulated GPIO chips can also be defined in device-tree. The compatible string +must be: ``"gpio-simulator"``. Supported properties are: + + ``"gpio-sim,label"`` - chip label + +Other standard GPIO properties (like ``"gpio-line-names"``, ``"ngpios"`` or +``"gpio-hog"``) are also supported. Please refer to the GPIO documentation for +details. + +An example device-tree code defining a GPIO simulator: + +.. code-block :: none + + gpio-sim { + compatible = "gpio-simulator"; + + bank0 { + gpio-controller; + #gpio-cells = <2>; + ngpios = <16>; + gpio-sim,label = "dt-bank0"; + gpio-line-names = "", "sim-foo", "", "sim-bar"; + }; + + bank1 { + gpio-controller; + #gpio-cells = <2>; + ngpios = <8>; + gpio-sim,label = "dt-bank1"; + + line3 { + gpio-hog; + gpios = <3 0>; + output-high; + line-name = "sim-hog-from-dt"; + }; + }; + }; + +Manipulating simulated lines +---------------------------- + +Each simulated GPIO chip creates a separate sysfs group under its device +directory for each exposed line +(e.g. ``/sys/devices/platform/gpio-sim.X/gpiochipY/``). The name of each group +is of the form: ``'sim_gpioX'`` where X is the offset of the line. Inside each +group there are two attibutes: + + ``pull`` - allows to read and set the current simulated pull setting for + every line, when writing the value must be one of: ``'pull-up'``, + ``'pull-down'`` + + ``value`` - allows to read the current value of the line which may be + different from the pull if the line is being driven from + user-space diff --git a/Documentation/admin-guide/hw-vuln/spectre.rst b/Documentation/admin-guide/hw-vuln/spectre.rst index ab7d402c1677..a2b22d5640ec 100644 --- a/Documentation/admin-guide/hw-vuln/spectre.rst +++ b/Documentation/admin-guide/hw-vuln/spectre.rst @@ -468,7 +468,7 @@ Spectre variant 2 before invoking any firmware code to prevent Spectre variant 2 exploits using the firmware. - Using kernel address space randomization (CONFIG_RANDOMIZE_SLAB=y + Using kernel address space randomization (CONFIG_RANDOMIZE_BASE=y and CONFIG_SLAB_FREELIST_RANDOM=y in the kernel configuration) makes attacks on the kernel generally more difficult. diff --git a/Documentation/admin-guide/kernel-parameters.txt b/Documentation/admin-guide/kernel-parameters.txt index 9725c546a0d4..685645e75706 100644 --- a/Documentation/admin-guide/kernel-parameters.txt +++ b/Documentation/admin-guide/kernel-parameters.txt @@ -225,14 +225,23 @@ For broken nForce2 BIOS resulting in XT-PIC timer. acpi_sleep= [HW,ACPI] Sleep options - Format: { s3_bios, s3_mode, s3_beep, s4_nohwsig, - old_ordering, nonvs, sci_force_enable, nobl } + Format: { s3_bios, s3_mode, s3_beep, s4_hwsig, + s4_nohwsig, old_ordering, nonvs, + sci_force_enable, nobl } See Documentation/power/video.rst for information on s3_bios and s3_mode. s3_beep is for debugging; it makes the PC's speaker beep as soon as the kernel's real-mode entry point is called. + s4_hwsig causes the kernel to check the ACPI hardware + signature during resume from hibernation, and gracefully + refuse to resume if it has changed. This complies with + the ACPI specification but not with reality, since + Windows does not do this and many laptops do change it + on docking. So the default behaviour is to allow resume + and simply warn when the signature changes, unless the + s4_hwsig option is enabled. s4_nohwsig prevents ACPI hardware signature from being - used during resume from hibernation. + used (or even warned about) during resume. old_ordering causes the ACPI 1.0 ordering of the _PTS control method, with respect to putting devices into low power states, to be enforced (the ACPI 2.0 ordering @@ -1689,6 +1698,8 @@ architectures force reset to be always executed i8042.unlock [HW] Unlock (ignore) the keylock i8042.kbdreset [HW] Reset device connected to KBD port + i8042.probe_defer + [HW] Allow deferred probing upon i8042 probe errors i810= [HW,DRM] @@ -2413,8 +2424,12 @@ Default is 1 (enabled) kvm-intel.emulate_invalid_guest_state= - [KVM,Intel] Enable emulation of invalid guest states - Default is 0 (disabled) + [KVM,Intel] Disable emulation of invalid guest state. + Ignored if kvm-intel.enable_unrestricted_guest=1, as + guest state is never invalid for unrestricted guests. + This param doesn't apply to nested guests (L2), as KVM + never emulates invalid L2 guest state. + Default is 1 (enabled) kvm-intel.flexpriority= [KVM,Intel] Disable FlexPriority feature (TPR shadow). @@ -2934,7 +2949,7 @@ both parameters are enabled, hugetlb_free_vmemmap takes precedence over memory_hotplug.memmap_on_memory. - memtest= [KNL,X86,ARM,PPC,RISCV] Enable memtest + memtest= [KNL,X86,ARM,M68K,PPC,RISCV] Enable memtest Format: <integer> default : 0 <disable> Specifies the number of memtest passes to be @@ -3545,6 +3560,13 @@ shutdown the other cpus. Instead use the REBOOT_VECTOR irq. + nomodeset Disable kernel modesetting. DRM drivers will not perform + display-mode changes or accelerated rendering. Only the + system framebuffer will be available for use if this was + set-up by the firmware or boot loader. + + Useful as fallback, or for testing and debugging. + nomodule Disable module load nopat [X86] Disable PAT (page attribute table extension of @@ -4343,19 +4365,30 @@ Disable the Correctable Errors Collector, see CONFIG_RAS_CEC help text. - rcu_nocbs= [KNL] - The argument is a cpu list, as described above. - - In kernels built with CONFIG_RCU_NOCB_CPU=y, set - the specified list of CPUs to be no-callback CPUs. - Invocation of these CPUs' RCU callbacks will be - offloaded to "rcuox/N" kthreads created for that - purpose, where "x" is "p" for RCU-preempt, and - "s" for RCU-sched, and "N" is the CPU number. - This reduces OS jitter on the offloaded CPUs, - which can be useful for HPC and real-time - workloads. It can also improve energy efficiency - for asymmetric multiprocessors. + rcu_nocbs[=cpu-list] + [KNL] The optional argument is a cpu list, + as described above. + + In kernels built with CONFIG_RCU_NOCB_CPU=y, + enable the no-callback CPU mode, which prevents + such CPUs' callbacks from being invoked in + softirq context. Invocation of such CPUs' RCU + callbacks will instead be offloaded to "rcuox/N" + kthreads created for that purpose, where "x" is + "p" for RCU-preempt, "s" for RCU-sched, and "g" + for the kthreads that mediate grace periods; and + "N" is the CPU number. This reduces OS jitter on + the offloaded CPUs, which can be useful for HPC + and real-time workloads. It can also improve + energy efficiency for asymmetric multiprocessors. + + If a cpulist is passed as an argument, the specified + list of CPUs is set to no-callback mode from boot. + + Otherwise, if the '=' sign and the cpulist + arguments are omitted, no CPU will be set to + no-callback mode from boot but the mode may be + toggled at runtime via cpusets. rcu_nocb_poll [KNL] Rather than requiring that offloaded CPUs @@ -4489,10 +4522,6 @@ on rcutree.qhimark at boot time and to zero to disable more aggressive help enlistment. - rcutree.rcu_idle_gp_delay= [KNL] - Set wakeup interval for idle CPUs that have - RCU callbacks (RCU_FAST_NO_HZ=y). - rcutree.rcu_kick_kthreads= [KNL] Cause the grace-period kthread to get an extra wake_up() if it sleeps three times longer than @@ -4603,8 +4632,12 @@ in seconds. rcutorture.fwd_progress= [KNL] - Enable RCU grace-period forward-progress testing + Specifies the number of kthreads to be used + for RCU grace-period forward-progress testing for the types of RCU supporting this notion. + Defaults to 1 kthread, values less than zero or + greater than the number of CPUs cause the number + of CPUs to be used. rcutorture.fwd_progress_div= [KNL] Specify the fraction of a CPU-stall-warning @@ -4805,6 +4838,29 @@ period to instead use normal non-expedited grace-period processing. + rcupdate.rcu_task_collapse_lim= [KNL] + Set the maximum number of callbacks present + at the beginning of a grace period that allows + the RCU Tasks flavors to collapse back to using + a single callback queue. This switching only + occurs when rcupdate.rcu_task_enqueue_lim is + set to the default value of -1. + + rcupdate.rcu_task_contend_lim= [KNL] + Set the minimum number of callback-queuing-time + lock-contention events per jiffy required to + cause the RCU Tasks flavors to switch to per-CPU + callback queuing. This switching only occurs + when rcupdate.rcu_task_enqueue_lim is set to + the default value of -1. + + rcupdate.rcu_task_enqueue_lim= [KNL] + Set the number of callback queues to use for the + RCU Tasks family of RCU flavors. The default + of -1 allows this to be automatically (and + dynamically) adjusted. This parameter is intended + for use in testing. + rcupdate.rcu_task_ipi_delay= [KNL] Set time in jiffies during which RCU tasks will avoid sending IPIs, starting with the beginning diff --git a/Documentation/admin-guide/kernel-per-CPU-kthreads.rst b/Documentation/admin-guide/kernel-per-CPU-kthreads.rst index 5e51ee5b0358..e4a5fc26f1a9 100644 --- a/Documentation/admin-guide/kernel-per-CPU-kthreads.rst +++ b/Documentation/admin-guide/kernel-per-CPU-kthreads.rst @@ -208,7 +208,7 @@ Do at least one of the following: 2. Enable RCU to do its processing remotely via dyntick-idle by doing all of the following: - a. Build with CONFIG_NO_HZ=y and CONFIG_RCU_FAST_NO_HZ=y. + a. Build with CONFIG_NO_HZ=y. b. Ensure that the CPU goes idle frequently, allowing other CPUs to detect that it has passed through an RCU quiescent state. If the kernel is built with CONFIG_NO_HZ_FULL=y, diff --git a/Documentation/admin-guide/media/platform-cardlist.rst b/Documentation/admin-guide/media/platform-cardlist.rst index 261e7772eb3e..ac73c4166d1e 100644 --- a/Documentation/admin-guide/media/platform-cardlist.rst +++ b/Documentation/admin-guide/media/platform-cardlist.rst @@ -60,6 +60,7 @@ s5p-mfc Samsung S5P MFC Video Codec sh_veu SuperH VEU mem2mem video processing sh_vou SuperH VOU video output stm32-dcmi STM32 Digital Camera Memory Interface (DCMI) +stm32-dma2d STM32 Chrom-Art Accelerator Unit sun4i-csi Allwinner A10 CMOS Sensor Interface Support sun6i-csi Allwinner V3s Camera Sensor Interface sun8i-di Allwinner Deinterlace diff --git a/Documentation/admin-guide/perf/hisi-pcie-pmu.rst b/Documentation/admin-guide/perf/hisi-pcie-pmu.rst new file mode 100644 index 000000000000..294ebbdb22af --- /dev/null +++ b/Documentation/admin-guide/perf/hisi-pcie-pmu.rst @@ -0,0 +1,106 @@ +================================================ +HiSilicon PCIe Performance Monitoring Unit (PMU) +================================================ + +On Hip09, HiSilicon PCIe Performance Monitoring Unit (PMU) could monitor +bandwidth, latency, bus utilization and buffer occupancy data of PCIe. + +Each PCIe Core has a PMU to monitor multi Root Ports of this PCIe Core and +all Endpoints downstream these Root Ports. + + +HiSilicon PCIe PMU driver +========================= + +The PCIe PMU driver registers a perf PMU with the name of its sicl-id and PCIe +Core id.:: + + /sys/bus/event_source/hisi_pcie<sicl>_<core> + +PMU driver provides description of available events and filter options in sysfs, +see /sys/bus/event_source/devices/hisi_pcie<sicl>_<core>. + +The "format" directory describes all formats of the config (events) and config1 +(filter options) fields of the perf_event_attr structure. The "events" directory +describes all documented events shown in perf list. + +The "identifier" sysfs file allows users to identify the version of the +PMU hardware device. + +The "bus" sysfs file allows users to get the bus number of Root Ports +monitored by PMU. + +Example usage of perf:: + + $# perf list + hisi_pcie0_0/rx_mwr_latency/ [kernel PMU event] + hisi_pcie0_0/rx_mwr_cnt/ [kernel PMU event] + ------------------------------------------ + + $# perf stat -e hisi_pcie0_0/rx_mwr_latency/ + $# perf stat -e hisi_pcie0_0/rx_mwr_cnt/ + $# perf stat -g -e hisi_pcie0_0/rx_mwr_latency/ -e hisi_pcie0_0/rx_mwr_cnt/ + +The current driver does not support sampling. So "perf record" is unsupported. +Also attach to a task is unsupported for PCIe PMU. + +Filter options +-------------- + +1. Target filter +PMU could only monitor the performance of traffic downstream target Root Ports +or downstream target Endpoint. PCIe PMU driver support "port" and "bdf" +interfaces for users, and these two interfaces aren't supported at the same +time. + +-port +"port" filter can be used in all PCIe PMU events, target Root Port can be +selected by configuring the 16-bits-bitmap "port". Multi ports can be selected +for AP-layer-events, and only one port can be selected for TL/DL-layer-events. + +For example, if target Root Port is 0000:00:00.0 (x8 lanes), bit0 of bitmap +should be set, port=0x1; if target Root Port is 0000:00:04.0 (x4 lanes), +bit8 is set, port=0x100; if these two Root Ports are both monitored, port=0x101. + +Example usage of perf:: + + $# perf stat -e hisi_pcie0_0/rx_mwr_latency,port=0x1/ sleep 5 + +-bdf + +"bdf" filter can only be used in bandwidth events, target Endpoint is selected +by configuring BDF to "bdf". Counter only counts the bandwidth of message +requested by target Endpoint. + +For example, "bdf=0x3900" means BDF of target Endpoint is 0000:39:00.0. + +Example usage of perf:: + + $# perf stat -e hisi_pcie0_0/rx_mrd_flux,bdf=0x3900/ sleep 5 + +2. Trigger filter +Event statistics start when the first time TLP length is greater/smaller +than trigger condition. You can set the trigger condition by writing "trig_len", +and set the trigger mode by writing "trig_mode". This filter can only be used +in bandwidth events. + +For example, "trig_len=4" means trigger condition is 2^4 DW, "trig_mode=0" +means statistics start when TLP length > trigger condition, "trig_mode=1" +means start when TLP length < condition. + +Example usage of perf:: + + $# perf stat -e hisi_pcie0_0/rx_mrd_flux,trig_len=0x4,trig_mode=1/ sleep 5 + +3. Threshold filter +Counter counts when TLP length within the specified range. You can set the +threshold by writing "thr_len", and set the threshold mode by writing +"thr_mode". This filter can only be used in bandwidth events. + +For example, "thr_len=4" means threshold is 2^4 DW, "thr_mode=0" means +counter counts when TLP length >= threshold, and "thr_mode=1" means counts +when TLP length < threshold. + +Example usage of perf:: + + $# perf stat -e hisi_pcie0_0/rx_mrd_flux,thr_len=0x4,thr_mode=1/ sleep 5 diff --git a/Documentation/admin-guide/pm/amd-pstate.rst b/Documentation/admin-guide/pm/amd-pstate.rst new file mode 100644 index 000000000000..2f066df4ee9c --- /dev/null +++ b/Documentation/admin-guide/pm/amd-pstate.rst @@ -0,0 +1,382 @@ +.. SPDX-License-Identifier: GPL-2.0 +.. include:: <isonum.txt> + +=============================================== +``amd-pstate`` CPU Performance Scaling Driver +=============================================== + +:Copyright: |copy| 2021 Advanced Micro Devices, Inc. + +:Author: Huang Rui <ray.huang@amd.com> + + +Introduction +=================== + +``amd-pstate`` is the AMD CPU performance scaling driver that introduces a +new CPU frequency control mechanism on modern AMD APU and CPU series in +Linux kernel. The new mechanism is based on Collaborative Processor +Performance Control (CPPC) which provides finer grain frequency management +than legacy ACPI hardware P-States. Current AMD CPU/APU platforms are using +the ACPI P-states driver to manage CPU frequency and clocks with switching +only in 3 P-states. CPPC replaces the ACPI P-states controls, allows a +flexible, low-latency interface for the Linux kernel to directly +communicate the performance hints to hardware. + +``amd-pstate`` leverages the Linux kernel governors such as ``schedutil``, +``ondemand``, etc. to manage the performance hints which are provided by +CPPC hardware functionality that internally follows the hardware +specification (for details refer to AMD64 Architecture Programmer's Manual +Volume 2: System Programming [1]_). Currently ``amd-pstate`` supports basic +frequency control function according to kernel governors on some of the +Zen2 and Zen3 processors, and we will implement more AMD specific functions +in future after we verify them on the hardware and SBIOS. + + +AMD CPPC Overview +======================= + +Collaborative Processor Performance Control (CPPC) interface enumerates a +continuous, abstract, and unit-less performance value in a scale that is +not tied to a specific performance state / frequency. This is an ACPI +standard [2]_ which software can specify application performance goals and +hints as a relative target to the infrastructure limits. AMD processors +provides the low latency register model (MSR) instead of AML code +interpreter for performance adjustments. ``amd-pstate`` will initialize a +``struct cpufreq_driver`` instance ``amd_pstate_driver`` with the callbacks +to manage each performance update behavior. :: + + Highest Perf ------>+-----------------------+ +-----------------------+ + | | | | + | | | | + | | Max Perf ---->| | + | | | | + | | | | + Nominal Perf ------>+-----------------------+ +-----------------------+ + | | | | + | | | | + | | | | + | | | | + | | | | + | | | | + | | Desired Perf ---->| | + | | | | + | | | | + | | | | + | | | | + | | | | + | | | | + | | | | + | | | | + | | | | + Lowest non- | | | | + linear perf ------>+-----------------------+ +-----------------------+ + | | | | + | | Lowest perf ---->| | + | | | | + Lowest perf ------>+-----------------------+ +-----------------------+ + | | | | + | | | | + | | | | + 0 ------>+-----------------------+ +-----------------------+ + + AMD P-States Performance Scale + + +.. _perf_cap: + +AMD CPPC Performance Capability +-------------------------------- + +Highest Performance (RO) +......................... + +It is the absolute maximum performance an individual processor may reach, +assuming ideal conditions. This performance level may not be sustainable +for long durations and may only be achievable if other platform components +are in a specific state; for example, it may require other processors be in +an idle state. This would be equivalent to the highest frequencies +supported by the processor. + +Nominal (Guaranteed) Performance (RO) +...................................... + +It is the maximum sustained performance level of the processor, assuming +ideal operating conditions. In absence of an external constraint (power, +thermal, etc.) this is the performance level the processor is expected to +be able to maintain continuously. All cores/processors are expected to be +able to sustain their nominal performance state simultaneously. + +Lowest non-linear Performance (RO) +................................... + +It is the lowest performance level at which nonlinear power savings are +achieved, for example, due to the combined effects of voltage and frequency +scaling. Above this threshold, lower performance levels should be generally +more energy efficient than higher performance levels. This register +effectively conveys the most efficient performance level to ``amd-pstate``. + +Lowest Performance (RO) +........................ + +It is the absolute lowest performance level of the processor. Selecting a +performance level lower than the lowest nonlinear performance level may +cause an efficiency penalty but should reduce the instantaneous power +consumption of the processor. + +AMD CPPC Performance Control +------------------------------ + +``amd-pstate`` passes performance goals through these registers. The +register drives the behavior of the desired performance target. + +Minimum requested performance (RW) +................................... + +``amd-pstate`` specifies the minimum allowed performance level. + +Maximum requested performance (RW) +................................... + +``amd-pstate`` specifies a limit the maximum performance that is expected +to be supplied by the hardware. + +Desired performance target (RW) +................................... + +``amd-pstate`` specifies a desired target in the CPPC performance scale as +a relative number. This can be expressed as percentage of nominal +performance (infrastructure max). Below the nominal sustained performance +level, desired performance expresses the average performance level of the +processor subject to hardware. Above the nominal performance level, +processor must provide at least nominal performance requested and go higher +if current operating conditions allow. + +Energy Performance Preference (EPP) (RW) +......................................... + +Provides a hint to the hardware if software wants to bias toward performance +(0x0) or energy efficiency (0xff). + + +Key Governors Support +======================= + +``amd-pstate`` can be used with all the (generic) scaling governors listed +by the ``scaling_available_governors`` policy attribute in ``sysfs``. Then, +it is responsible for the configuration of policy objects corresponding to +CPUs and provides the ``CPUFreq`` core (and the scaling governors attached +to the policy objects) with accurate information on the maximum and minimum +operating frequencies supported by the hardware. Users can check the +``scaling_cur_freq`` information comes from the ``CPUFreq`` core. + +``amd-pstate`` mainly supports ``schedutil`` and ``ondemand`` for dynamic +frequency control. It is to fine tune the processor configuration on +``amd-pstate`` to the ``schedutil`` with CPU CFS scheduler. ``amd-pstate`` +registers adjust_perf callback to implement the CPPC similar performance +update behavior. It is initialized by ``sugov_start`` and then populate the +CPU's update_util_data pointer to assign ``sugov_update_single_perf`` as +the utilization update callback function in CPU scheduler. CPU scheduler +will call ``cpufreq_update_util`` and assign the target performance +according to the ``struct sugov_cpu`` that utilization update belongs to. +Then ``amd-pstate`` updates the desired performance according to the CPU +scheduler assigned. + + +Processor Support +======================= + +The ``amd-pstate`` initialization will fail if the _CPC in ACPI SBIOS is +not existed at the detected processor, and it uses ``acpi_cpc_valid`` to +check the _CPC existence. All Zen based processors support legacy ACPI +hardware P-States function, so while the ``amd-pstate`` fails to be +initialized, the kernel will fall back to initialize ``acpi-cpufreq`` +driver. + +There are two types of hardware implementations for ``amd-pstate``: one is +`Full MSR Support <perf_cap_>`_ and another is `Shared Memory Support +<perf_cap_>`_. It can use :c:macro:`X86_FEATURE_CPPC` feature flag (for +details refer to Processor Programming Reference (PPR) for AMD Family +19h Model 51h, Revision A1 Processors [3]_) to indicate the different +types. ``amd-pstate`` is to register different ``static_call`` instances +for different hardware implementations. + +Currently, some of Zen2 and Zen3 processors support ``amd-pstate``. In the +future, it will be supported on more and more AMD processors. + +Full MSR Support +----------------- + +Some new Zen3 processors such as Cezanne provide the MSR registers directly +while the :c:macro:`X86_FEATURE_CPPC` CPU feature flag is set. +``amd-pstate`` can handle the MSR register to implement the fast switch +function in ``CPUFreq`` that can shrink latency of frequency control on the +interrupt context. The functions with ``pstate_xxx`` prefix represent the +operations of MSR registers. + +Shared Memory Support +---------------------- + +If :c:macro:`X86_FEATURE_CPPC` CPU feature flag is not set, that means the +processor supports shared memory solution. In this case, ``amd-pstate`` +uses the ``cppc_acpi`` helper methods to implement the callback functions +that defined on ``static_call``. The functions with ``cppc_xxx`` prefix +represent the operations of acpi cppc helpers for shared memory solution. + + +AMD P-States and ACPI hardware P-States always can be supported in one +processor. But AMD P-States has the higher priority and if it is enabled +with :c:macro:`MSR_AMD_CPPC_ENABLE` or ``cppc_set_enable``, it will respond +to the request from AMD P-States. + + +User Space Interface in ``sysfs`` +================================== + +``amd-pstate`` exposes several global attributes (files) in ``sysfs`` to +control its functionality at the system level. They located in the +``/sys/devices/system/cpu/cpufreq/policyX/`` directory and affect all CPUs. :: + + root@hr-test1:/home/ray# ls /sys/devices/system/cpu/cpufreq/policy0/*amd* + /sys/devices/system/cpu/cpufreq/policy0/amd_pstate_highest_perf + /sys/devices/system/cpu/cpufreq/policy0/amd_pstate_lowest_nonlinear_freq + /sys/devices/system/cpu/cpufreq/policy0/amd_pstate_max_freq + + +``amd_pstate_highest_perf / amd_pstate_max_freq`` + +Maximum CPPC performance and CPU frequency that the driver is allowed to +set in percent of the maximum supported CPPC performance level (the highest +performance supported in `AMD CPPC Performance Capability <perf_cap_>`_). +In some of ASICs, the highest CPPC performance is not the one in the _CPC +table, so we need to expose it to sysfs. If boost is not active but +supported, this maximum frequency will be larger than the one in +``cpuinfo``. +This attribute is read-only. + +``amd_pstate_lowest_nonlinear_freq`` + +The lowest non-linear CPPC CPU frequency that the driver is allowed to set +in percent of the maximum supported CPPC performance level (Please see the +lowest non-linear performance in `AMD CPPC Performance Capability +<perf_cap_>`_). +This attribute is read-only. + +For other performance and frequency values, we can read them back from +``/sys/devices/system/cpu/cpuX/acpi_cppc/``, see :ref:`cppc_sysfs`. + + +``amd-pstate`` vs ``acpi-cpufreq`` +====================================== + +On majority of AMD platforms supported by ``acpi-cpufreq``, the ACPI tables +provided by the platform firmware used for CPU performance scaling, but +only provides 3 P-states on AMD processors. +However, on modern AMD APU and CPU series, it provides the collaborative +processor performance control according to ACPI protocol and customize this +for AMD platforms. That is fine-grain and continuous frequency range +instead of the legacy hardware P-states. ``amd-pstate`` is the kernel +module which supports the new AMD P-States mechanism on most of future AMD +platforms. The AMD P-States mechanism will be the more performance and energy +efficiency frequency management method on AMD processors. + +Kernel Module Options for ``amd-pstate`` +========================================= + +``shared_mem`` +Use a module param (shared_mem) to enable related processors manually with +**amd_pstate.shared_mem=1**. +Due to the performance issue on the processors with `Shared Memory Support +<perf_cap_>`_, so we disable it for the moment and will enable this by default +once we address performance issue on this solution. + +The way to check whether current processor is `Full MSR Support <perf_cap_>`_ +or `Shared Memory Support <perf_cap_>`_ : :: + + ray@hr-test1:~$ lscpu | grep cppc + Flags: fpu vme de pse tsc msr pae mce cx8 apic sep mtrr pge mca cmov pat pse36 clflush mmx fxsr sse sse2 ht syscall nx mmxext fxsr_opt pdpe1gb rdtscp lm constant_tsc rep_good nopl nonstop_tsc cpuid extd_apicid aperfmperf rapl pni pclmulqdq monitor ssse3 fma cx16 sse4_1 sse4_2 x2apic movbe popcnt aes xsave avx f16c rdrand lahf_lm cmp_legacy svm extapic cr8_legacy abm sse4a misalignsse 3dnowprefetch osvw ibs skinit wdt tce topoext perfctr_core perfctr_nb bpext perfctr_llc mwaitx cpb cat_l3 cdp_l3 hw_pstate ssbd mba ibrs ibpb stibp vmmcall fsgsbase bmi1 avx2 smep bmi2 erms invpcid cqm rdt_a rdseed adx smap clflushopt clwb sha_ni xsaveopt xsavec xgetbv1 xsaves cqm_llc cqm_occup_llc cqm_mbm_total cqm_mbm_local clzero irperf xsaveerptr rdpru wbnoinvd cppc arat npt lbrv svm_lock nrip_save tsc_scale vmcb_clean flushbyasid decodeassists pausefilter pfthreshold avic v_vmsave_vmload vgif v_spec_ctrl umip pku ospke vaes vpclmulqdq rdpid overflow_recov succor smca fsrm + +If CPU Flags have cppc, then this processor supports `Full MSR Support +<perf_cap_>`_. Otherwise it supports `Shared Memory Support <perf_cap_>`_. + + +``cpupower`` tool support for ``amd-pstate`` +=============================================== + +``amd-pstate`` is supported on ``cpupower`` tool that can be used to dump the frequency +information. And it is in progress to support more and more operations for new +``amd-pstate`` module with this tool. :: + + root@hr-test1:/home/ray# cpupower frequency-info + analyzing CPU 0: + driver: amd-pstate + CPUs which run at the same hardware frequency: 0 + CPUs which need to have their frequency coordinated by software: 0 + maximum transition latency: 131 us + hardware limits: 400 MHz - 4.68 GHz + available cpufreq governors: ondemand conservative powersave userspace performance schedutil + current policy: frequency should be within 400 MHz and 4.68 GHz. + The governor "schedutil" may decide which speed to use + within this range. + current CPU frequency: Unable to call hardware + current CPU frequency: 4.02 GHz (asserted by call to kernel) + boost state support: + Supported: yes + Active: yes + AMD PSTATE Highest Performance: 166. Maximum Frequency: 4.68 GHz. + AMD PSTATE Nominal Performance: 117. Nominal Frequency: 3.30 GHz. + AMD PSTATE Lowest Non-linear Performance: 39. Lowest Non-linear Frequency: 1.10 GHz. + AMD PSTATE Lowest Performance: 15. Lowest Frequency: 400 MHz. + + +Diagnostics and Tuning +======================= + +Trace Events +-------------- + +There are two static trace events that can be used for ``amd-pstate`` +diagnostics. One of them is the cpu_frequency trace event generally used +by ``CPUFreq``, and the other one is the ``amd_pstate_perf`` trace event +specific to ``amd-pstate``. The following sequence of shell commands can +be used to enable them and see their output (if the kernel is generally +configured to support event tracing). :: + + root@hr-test1:/home/ray# cd /sys/kernel/tracing/ + root@hr-test1:/sys/kernel/tracing# echo 1 > events/amd_cpu/enable + root@hr-test1:/sys/kernel/tracing# cat trace + # tracer: nop + # + # entries-in-buffer/entries-written: 47827/42233061 #P:2 + # + # _-----=> irqs-off + # / _----=> need-resched + # | / _---=> hardirq/softirq + # || / _--=> preempt-depth + # ||| / delay + # TASK-PID CPU# |||| TIMESTAMP FUNCTION + # | | | |||| | | + <idle>-0 [015] dN... 4995.979886: amd_pstate_perf: amd_min_perf=85 amd_des_perf=85 amd_max_perf=166 cpu_id=15 changed=false fast_switch=true + <idle>-0 [007] d.h.. 4995.979893: amd_pstate_perf: amd_min_perf=85 amd_des_perf=85 amd_max_perf=166 cpu_id=7 changed=false fast_switch=true + cat-2161 [000] d.... 4995.980841: amd_pstate_perf: amd_min_perf=85 amd_des_perf=85 amd_max_perf=166 cpu_id=0 changed=false fast_switch=true + sshd-2125 [004] d.s.. 4995.980968: amd_pstate_perf: amd_min_perf=85 amd_des_perf=85 amd_max_perf=166 cpu_id=4 changed=false fast_switch=true + <idle>-0 [007] d.s.. 4995.980968: amd_pstate_perf: amd_min_perf=85 amd_des_perf=85 amd_max_perf=166 cpu_id=7 changed=false fast_switch=true + <idle>-0 [003] d.s.. 4995.980971: amd_pstate_perf: amd_min_perf=85 amd_des_perf=85 amd_max_perf=166 cpu_id=3 changed=false fast_switch=true + <idle>-0 [011] d.s.. 4995.980996: amd_pstate_perf: amd_min_perf=85 amd_des_perf=85 amd_max_perf=166 cpu_id=11 changed=false fast_switch=true + +The cpu_frequency trace event will be triggered either by the ``schedutil`` scaling +governor (for the policies it is attached to), or by the ``CPUFreq`` core (for the +policies with other scaling governors). + + +Reference +=========== + +.. [1] AMD64 Architecture Programmer's Manual Volume 2: System Programming, + https://www.amd.com/system/files/TechDocs/24593.pdf + +.. [2] Advanced Configuration and Power Interface Specification, + https://uefi.org/sites/default/files/resources/ACPI_Spec_6_4_Jan22.pdf + +.. [3] Processor Programming Reference (PPR) for AMD Family 19h Model 51h, Revision A1 Processors + https://www.amd.com/system/files/TechDocs/56569-A1-PUB.zip diff --git a/Documentation/admin-guide/pm/working-state.rst b/Documentation/admin-guide/pm/working-state.rst index f40994c422dc..5d2757e2de65 100644 --- a/Documentation/admin-guide/pm/working-state.rst +++ b/Documentation/admin-guide/pm/working-state.rst @@ -11,6 +11,7 @@ Working-State Power Management intel_idle cpufreq intel_pstate + amd-pstate cpufreq_drivers intel_epb intel-speed-select diff --git a/Documentation/admin-guide/sysctl/kernel.rst b/Documentation/admin-guide/sysctl/kernel.rst index 0e486f41185e..d359bcfadd39 100644 --- a/Documentation/admin-guide/sysctl/kernel.rst +++ b/Documentation/admin-guide/sysctl/kernel.rst @@ -905,6 +905,17 @@ enabled, otherwise writing to this file will return ``-EBUSY``. The default value is 8. +perf_user_access (arm64 only) +================================= + +Controls user space access for reading perf event counters. When set to 1, +user space can read performance monitor counter registers directly. + +The default value is 0 (access disabled). + +See Documentation/arm64/perf.rst for more information. + + pid_max ======= diff --git a/Documentation/arc/arc.rst b/Documentation/arc/arc.rst new file mode 100644 index 000000000000..6c4d978f3f4e --- /dev/null +++ b/Documentation/arc/arc.rst @@ -0,0 +1,85 @@ +.. SPDX-License-Identifier: GPL-2.0 + +Linux kernel for ARC processors +******************************* + +Other sources of information +############################ + +Below are some resources where more information can be found on +ARC processors and relevant open source projects. + +- `<https://embarc.org>`_ - Community portal for open source on ARC. + Good place to start to find relevant FOSS projects, toolchain releases, + news items and more. + +- `<https://github.com/foss-for-synopsys-dwc-arc-processors>`_ - + Home for all development activities regarding open source projects for + ARC processors. Some of the projects are forks of various upstream projects, + where "work in progress" is hosted prior to submission to upstream projects. + Other projects are developed by Synopsys and made available to community + as open source for use on ARC Processors. + +- `Official Synopsys ARC Processors website + <https://www.synopsys.com/designware-ip/processor-solutions.html>`_ - + location, with access to some IP documentation (`Programmer's Reference + Manual, AKA PRM for ARC HS processors + <https://www.synopsys.com/dw/doc.php/ds/cc/programmers-reference-manual-ARC-HS.pdf>`_) + and free versions of some commercial tools (`Free nSIM + <https://www.synopsys.com/cgi-bin/dwarcnsim/req1.cgi>`_ and + `MetaWare Light Edition <https://www.synopsys.com/cgi-bin/arcmwtk_lite/reg1.cgi>`_). + Please note though, registration is required to access both the documentation and + the tools. + +Important note on ARC processors configurability +################################################ + +ARC processors are highly configurable and several configurable options +are supported in Linux. Some options are transparent to software +(i.e cache geometries, some can be detected at runtime and configured +and used accordingly, while some need to be explicitly selected or configured +in the kernel's configuration utility (AKA "make menuconfig"). + +However not all configurable options are supported when an ARC processor +is to run Linux. SoC design teams should refer to "Appendix E: +Configuration for ARC Linux" in the ARC HS Databook for configurability +guidelines. + +Following these guidelines and selecting valid configuration options +up front is critical to help prevent any unwanted issues during +SoC bringup and software development in general. + +Building the Linux kernel for ARC processors +############################################ + +The process of kernel building for ARC processors is the same as for any other +architecture and could be done in 2 ways: + +- Cross-compilation: process of compiling for ARC targets on a development + host with a different processor architecture (generally x86_64/amd64). +- Native compilation: process of compiling for ARC on a ARC platform + (hardware board or a simulator like QEMU) with complete development environment + (GNU toolchain, dtc, make etc) installed on the platform. + +In both cases, up-to-date GNU toolchain for ARC for the host is needed. +Synopsys offers prebuilt toolchain releases which can be used for this purpose, +available from: + +- Synopsys GNU toolchain releases: + `<https://github.com/foss-for-synopsys-dwc-arc-processors/toolchain/releases>`_ + +- Linux kernel compilers collection: + `<https://mirrors.edge.kernel.org/pub/tools/crosstool>`_ + +- Bootlin's toolchain collection: `<https://toolchains.bootlin.com>`_ + +Once the toolchain is installed in the system, make sure its "bin" folder +is added in your ``PATH`` environment variable. Then set ``ARCH=arc`` & +``CROSS_COMPILE=arc-linux`` (or whatever matches installed ARC toolchain prefix) +and then as usual ``make defconfig && make``. + +This will produce "vmlinux" file in the root of the kernel source tree +usable for loading on the target system via JTAG. +If you need to get an image usable with U-Boot bootloader, +type ``make uImage`` and ``uImage`` will be produced in ``arch/arc/boot`` +folder. diff --git a/Documentation/arc/features.rst b/Documentation/arc/features.rst new file mode 100644 index 000000000000..b793583d688a --- /dev/null +++ b/Documentation/arc/features.rst @@ -0,0 +1,3 @@ +.. SPDX-License-Identifier: GPL-2.0 + +.. kernel-feat:: $srctree/Documentation/features arc diff --git a/Documentation/arc/index.rst b/Documentation/arc/index.rst new file mode 100644 index 000000000000..7b098d4a5e3e --- /dev/null +++ b/Documentation/arc/index.rst @@ -0,0 +1,17 @@ +=================== +ARC architecture +=================== + +.. toctree:: + :maxdepth: 1 + + arc + + features + +.. only:: subproject and html + + Indices + ======= + + * :ref:`genindex` diff --git a/Documentation/arch.rst b/Documentation/arch.rst index f10bd32a5972..14bcd8294b93 100644 --- a/Documentation/arch.rst +++ b/Documentation/arch.rst @@ -9,6 +9,7 @@ implementation. .. toctree:: :maxdepth: 2 + arc/index arm/index arm64/index ia64/index diff --git a/Documentation/arm64/cpu-feature-registers.rst b/Documentation/arm64/cpu-feature-registers.rst index 9f9b8fd06089..749ae970c319 100644 --- a/Documentation/arm64/cpu-feature-registers.rst +++ b/Documentation/arm64/cpu-feature-registers.rst @@ -275,6 +275,23 @@ infrastructure: | SVEVer | [3-0] | y | +------------------------------+---------+---------+ + 8) ID_AA64MMFR1_EL1 - Memory model feature register 1 + + +------------------------------+---------+---------+ + | Name | bits | visible | + +------------------------------+---------+---------+ + | AFP | [47-44] | y | + +------------------------------+---------+---------+ + + 9) ID_AA64ISAR2_EL1 - Instruction set attribute register 2 + + +------------------------------+---------+---------+ + | Name | bits | visible | + +------------------------------+---------+---------+ + | RPRES | [7-4] | y | + +------------------------------+---------+---------+ + + Appendix I: Example ------------------- diff --git a/Documentation/arm64/elf_hwcaps.rst b/Documentation/arm64/elf_hwcaps.rst index af106af8e1c0..b72ff17d600a 100644 --- a/Documentation/arm64/elf_hwcaps.rst +++ b/Documentation/arm64/elf_hwcaps.rst @@ -251,6 +251,14 @@ HWCAP2_ECV Functionality implied by ID_AA64MMFR0_EL1.ECV == 0b0001. +HWCAP2_AFP + + Functionality implied by ID_AA64MFR1_EL1.AFP == 0b0001. + +HWCAP2_RPRES + + Functionality implied by ID_AA64ISAR2_EL1.RPRES == 0b0001. + 4. Unused AT_HWCAP bits ----------------------- diff --git a/Documentation/arm64/perf.rst b/Documentation/arm64/perf.rst index b567f177d385..1f87b57c2332 100644 --- a/Documentation/arm64/perf.rst +++ b/Documentation/arm64/perf.rst @@ -2,7 +2,10 @@ .. _perf_index: -===================== +==== +Perf +==== + Perf Event Attributes ===================== @@ -88,3 +91,76 @@ exclude_host. However when using !exclude_hv there is a small blackout window at the guest entry/exit where host events are not captured. On VHE systems there are no blackout windows. + +Perf Userspace PMU Hardware Counter Access +========================================== + +Overview +-------- +The perf userspace tool relies on the PMU to monitor events. It offers an +abstraction layer over the hardware counters since the underlying +implementation is cpu-dependent. +Arm64 allows userspace tools to have access to the registers storing the +hardware counters' values directly. + +This targets specifically self-monitoring tasks in order to reduce the overhead +by directly accessing the registers without having to go through the kernel. + +How-to +------ +The focus is set on the armv8 PMUv3 which makes sure that the access to the pmu +registers is enabled and that the userspace has access to the relevant +information in order to use them. + +In order to have access to the hardware counters, the global sysctl +kernel/perf_user_access must first be enabled: + +.. code-block:: sh + + echo 1 > /proc/sys/kernel/perf_user_access + +It is necessary to open the event using the perf tool interface with config1:1 +attr bit set: the sys_perf_event_open syscall returns a fd which can +subsequently be used with the mmap syscall in order to retrieve a page of memory +containing information about the event. The PMU driver uses this page to expose +to the user the hardware counter's index and other necessary data. Using this +index enables the user to access the PMU registers using the `mrs` instruction. +Access to the PMU registers is only valid while the sequence lock is unchanged. +In particular, the PMSELR_EL0 register is zeroed each time the sequence lock is +changed. + +The userspace access is supported in libperf using the perf_evsel__mmap() +and perf_evsel__read() functions. See `tools/lib/perf/tests/test-evsel.c`_ for +an example. + +About heterogeneous systems +--------------------------- +On heterogeneous systems such as big.LITTLE, userspace PMU counter access can +only be enabled when the tasks are pinned to a homogeneous subset of cores and +the corresponding PMU instance is opened by specifying the 'type' attribute. +The use of generic event types is not supported in this case. + +Have a look at `tools/perf/arch/arm64/tests/user-events.c`_ for an example. It +can be run using the perf tool to check that the access to the registers works +correctly from userspace: + +.. code-block:: sh + + perf test -v user + +About chained events and counter sizes +-------------------------------------- +The user can request either a 32-bit (config1:0 == 0) or 64-bit (config1:0 == 1) +counter along with userspace access. The sys_perf_event_open syscall will fail +if a 64-bit counter is requested and the hardware doesn't support 64-bit +counters. Chained events are not supported in conjunction with userspace counter +access. If a 32-bit counter is requested on hardware with 64-bit counters, then +userspace must treat the upper 32-bits read from the counter as UNKNOWN. The +'pmc_width' field in the user page will indicate the valid width of the counter +and should be used to mask the upper bits as needed. + +.. Links +.. _tools/perf/arch/arm64/tests/user-events.c: + https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/tree/tools/perf/arch/arm64/tests/user-events.c +.. _tools/lib/perf/tests/test-evsel.c: + https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/tree/tools/lib/perf/tests/test-evsel.c diff --git a/Documentation/arm64/pointer-authentication.rst b/Documentation/arm64/pointer-authentication.rst index f127666ea3a8..e5dad2e40aa8 100644 --- a/Documentation/arm64/pointer-authentication.rst +++ b/Documentation/arm64/pointer-authentication.rst @@ -53,11 +53,10 @@ The number of bits that the PAC occupies in a pointer is 55 minus the virtual address size configured by the kernel. For example, with a virtual address size of 48, the PAC is 7 bits wide. -Recent versions of GCC can compile code with APIAKey-based return -address protection when passed the -msign-return-address option. This -uses instructions in the HINT space (unless -march=armv8.3-a or higher -is also passed), and such code can run on systems without the pointer -authentication extension. +When ARM64_PTR_AUTH_KERNEL is selected, the kernel will be compiled +with HINT space pointer authentication instructions protecting +function returns. Kernels built with this option will work on hardware +with or without pointer authentication support. In addition to exec(), keys can also be reinitialized to random values using the PR_PAC_RESET_KEYS prctl. A bitmask of PR_PAC_APIAKEY, diff --git a/Documentation/arm64/sve.rst b/Documentation/arm64/sve.rst index 03137154299e..9d9a4de5bc34 100644 --- a/Documentation/arm64/sve.rst +++ b/Documentation/arm64/sve.rst @@ -255,7 +255,7 @@ prctl(PR_SVE_GET_VL) vector length change (which would only normally be the case between a fork() or vfork() and the corresponding execve() in typical use). - To extract the vector length from the result, and it with + To extract the vector length from the result, bitwise and it with PR_SVE_VL_LEN_MASK. Return value: a nonnegative value on success, or a negative value on error: diff --git a/Documentation/arm64/tagged-address-abi.rst b/Documentation/arm64/tagged-address-abi.rst index 0c9120ec58ae..540a1d4fc6c9 100644 --- a/Documentation/arm64/tagged-address-abi.rst +++ b/Documentation/arm64/tagged-address-abi.rst @@ -49,7 +49,7 @@ how the user addresses are used by the kernel: - ``brk()``, ``mmap()`` and the ``new_address`` argument to ``mremap()`` as these have the potential to alias with existing - user addresses. + user addresses. NOTE: This behaviour changed in v5.6 and so some earlier kernels may incorrectly accept valid tagged pointers for the ``brk()``, diff --git a/Documentation/bpf/btf.rst b/Documentation/bpf/btf.rst index 9ad4218a751f..1ebf4c5c7ddc 100644 --- a/Documentation/bpf/btf.rst +++ b/Documentation/bpf/btf.rst @@ -3,7 +3,7 @@ BPF Type Format (BTF) ===================== 1. Introduction -*************** +=============== BTF (BPF Type Format) is the metadata format which encodes the debug info related to BPF program/map. The name BTF was used initially to describe data @@ -30,7 +30,7 @@ sections are discussed in details in :ref:`BTF_Type_String`. .. _BTF_Type_String: 2. BTF Type and String Encoding -******************************* +=============================== The file ``include/uapi/linux/btf.h`` provides high-level definition of how types/strings are encoded. @@ -57,13 +57,13 @@ little-endian target. The ``btf_header`` is designed to be extensible with generated. 2.1 String Encoding -=================== +------------------- The first string in the string section must be a null string. The rest of string table is a concatenation of other null-terminated strings. 2.2 Type Encoding -================= +----------------- The type id ``0`` is reserved for ``void`` type. The type section is parsed sequentially and type id is assigned to each recognized type starting from id @@ -86,6 +86,7 @@ sequentially and type id is assigned to each recognized type starting from id #define BTF_KIND_DATASEC 15 /* Section */ #define BTF_KIND_FLOAT 16 /* Floating point */ #define BTF_KIND_DECL_TAG 17 /* Decl Tag */ + #define BTF_KIND_TYPE_TAG 18 /* Type Tag */ Note that the type section encodes debug info, not just pure types. ``BTF_KIND_FUNC`` is not a type, and it represents a defined subprogram. @@ -107,7 +108,7 @@ Each type contains the following common data:: * "size" tells the size of the type it is describing. * * "type" is used by PTR, TYPEDEF, VOLATILE, CONST, RESTRICT, - * FUNC, FUNC_PROTO and DECL_TAG. + * FUNC, FUNC_PROTO, DECL_TAG and TYPE_TAG. * "type" is a type_id referring to another type. */ union { @@ -492,8 +493,18 @@ the attribute is applied to a ``struct``/``union`` member or a ``func`` argument, and ``btf_decl_tag.component_idx`` should be a valid index (starting from 0) pointing to a member or an argument. +2.2.17 BTF_KIND_TYPE_TAG +~~~~~~~~~~~~~~~~~~~~~~~~ + +``struct btf_type`` encoding requirement: + * ``name_off``: offset to a non-empty string + * ``info.kind_flag``: 0 + * ``info.kind``: BTF_KIND_TYPE_TAG + * ``info.vlen``: 0 + * ``type``: the type with ``btf_type_tag`` attribute + 3. BTF Kernel API -***************** +================= The following bpf syscall command involves BTF: * BPF_BTF_LOAD: load a blob of BTF data into kernel @@ -536,14 +547,14 @@ The workflow typically looks like: 3.1 BPF_BTF_LOAD -================ +---------------- Load a blob of BTF data into kernel. A blob of data, described in :ref:`BTF_Type_String`, can be directly loaded into the kernel. A ``btf_fd`` is returned to a userspace. 3.2 BPF_MAP_CREATE -================== +------------------ A map can be created with ``btf_fd`` and specified key/value type id.:: @@ -570,7 +581,7 @@ automatically. .. _BPF_Prog_Load: 3.3 BPF_PROG_LOAD -================= +----------------- During prog_load, func_info and line_info can be passed to kernel with proper values for the following attributes: @@ -620,7 +631,7 @@ For line_info, the line number and column number are defined as below: #define BPF_LINE_INFO_LINE_COL(line_col) ((line_col) & 0x3ff) 3.4 BPF_{PROG,MAP}_GET_NEXT_ID -============================== +------------------------------ In kernel, every loaded program, map or btf has a unique id. The id won't change during the lifetime of a program, map, or btf. @@ -630,13 +641,13 @@ each command, to user space, for bpf program or maps, respectively, so an inspection tool can inspect all programs and maps. 3.5 BPF_{PROG,MAP}_GET_FD_BY_ID -=============================== +------------------------------- An introspection tool cannot use id to get details about program or maps. A file descriptor needs to be obtained first for reference-counting purpose. 3.6 BPF_OBJ_GET_INFO_BY_FD -========================== +-------------------------- Once a program/map fd is acquired, an introspection tool can get the detailed information from kernel about this fd, some of which are BTF-related. For @@ -645,7 +656,7 @@ example, ``bpf_map_info`` returns ``btf_id`` and key/value type ids. bpf byte codes, and jited_line_info. 3.7 BPF_BTF_GET_FD_BY_ID -======================== +------------------------ With ``btf_id`` obtained in ``bpf_map_info`` and ``bpf_prog_info``, bpf syscall command BPF_BTF_GET_FD_BY_ID can retrieve a btf fd. Then, with @@ -657,10 +668,10 @@ tool has full btf knowledge and is able to pretty print map key/values, dump func signatures and line info, along with byte/jit codes. 4. ELF File Format Interface -**************************** +============================ 4.1 .BTF section -================ +---------------- The .BTF section contains type and string data. The format of this section is same as the one describe in :ref:`BTF_Type_String`. @@ -668,7 +679,7 @@ same as the one describe in :ref:`BTF_Type_String`. .. _BTF_Ext_Section: 4.2 .BTF.ext section -==================== +-------------------- The .BTF.ext section encodes func_info and line_info which needs loader manipulation before loading into the kernel. @@ -732,7 +743,7 @@ bpf_insn``. For ELF API, the ``insn_off`` is the byte offset from the beginning of section (``btf_ext_info_sec->sec_name_off``). 4.2 .BTF_ids section -==================== +-------------------- The .BTF_ids section encodes BTF ID values that are used within the kernel. @@ -793,10 +804,10 @@ All the BTF ID lists and sets are compiled in the .BTF_ids section and resolved during the linking phase of kernel build by ``resolve_btfids`` tool. 5. Using BTF -************ +============ 5.1 bpftool map pretty print -============================ +---------------------------- With BTF, the map key/value can be printed based on fields rather than simply raw bytes. This is especially valuable for large structure or if your data @@ -838,7 +849,7 @@ bpftool is able to pretty print like below: ] 5.2 bpftool prog dump -===================== +--------------------- The following is an example showing how func_info and line_info can help prog dump with better kernel symbol names, function prototypes and line @@ -872,7 +883,7 @@ information.:: [...] 5.3 Verifier Log -================ +---------------- The following is an example of how line_info can help debugging verification failure.:: @@ -898,7 +909,7 @@ failure.:: R2 offset is outside of the packet 6. BTF Generation -***************** +================= You need latest pahole @@ -1005,6 +1016,6 @@ format.:: .long 8206 # Line 8 Col 14 7. Testing -********** +========== Kernel bpf selftest `test_btf.c` provides extensive set of BTF-related tests. diff --git a/Documentation/bpf/classic_vs_extended.rst b/Documentation/bpf/classic_vs_extended.rst new file mode 100644 index 000000000000..2f81a81f5267 --- /dev/null +++ b/Documentation/bpf/classic_vs_extended.rst @@ -0,0 +1,376 @@ + +=================== +Classic BPF vs eBPF +=================== + +eBPF is designed to be JITed with one to one mapping, which can also open up +the possibility for GCC/LLVM compilers to generate optimized eBPF code through +an eBPF backend that performs almost as fast as natively compiled code. + +Some core changes of the eBPF format from classic BPF: + +- Number of registers increase from 2 to 10: + + The old format had two registers A and X, and a hidden frame pointer. The + new layout extends this to be 10 internal registers and a read-only frame + pointer. Since 64-bit CPUs are passing arguments to functions via registers + the number of args from eBPF program to in-kernel function is restricted + to 5 and one register is used to accept return value from an in-kernel + function. Natively, x86_64 passes first 6 arguments in registers, aarch64/ + sparcv9/mips64 have 7 - 8 registers for arguments; x86_64 has 6 callee saved + registers, and aarch64/sparcv9/mips64 have 11 or more callee saved registers. + + Thus, all eBPF registers map one to one to HW registers on x86_64, aarch64, + etc, and eBPF calling convention maps directly to ABIs used by the kernel on + 64-bit architectures. + + On 32-bit architectures JIT may map programs that use only 32-bit arithmetic + and may let more complex programs to be interpreted. + + R0 - R5 are scratch registers and eBPF program needs spill/fill them if + necessary across calls. Note that there is only one eBPF program (== one + eBPF main routine) and it cannot call other eBPF functions, it can only + call predefined in-kernel functions, though. + +- Register width increases from 32-bit to 64-bit: + + Still, the semantics of the original 32-bit ALU operations are preserved + via 32-bit subregisters. All eBPF registers are 64-bit with 32-bit lower + subregisters that zero-extend into 64-bit if they are being written to. + That behavior maps directly to x86_64 and arm64 subregister definition, but + makes other JITs more difficult. + + 32-bit architectures run 64-bit eBPF programs via interpreter. + Their JITs may convert BPF programs that only use 32-bit subregisters into + native instruction set and let the rest being interpreted. + + Operation is 64-bit, because on 64-bit architectures, pointers are also + 64-bit wide, and we want to pass 64-bit values in/out of kernel functions, + so 32-bit eBPF registers would otherwise require to define register-pair + ABI, thus, there won't be able to use a direct eBPF register to HW register + mapping and JIT would need to do combine/split/move operations for every + register in and out of the function, which is complex, bug prone and slow. + Another reason is the use of atomic 64-bit counters. + +- Conditional jt/jf targets replaced with jt/fall-through: + + While the original design has constructs such as ``if (cond) jump_true; + else jump_false;``, they are being replaced into alternative constructs like + ``if (cond) jump_true; /* else fall-through */``. + +- Introduces bpf_call insn and register passing convention for zero overhead + calls from/to other kernel functions: + + Before an in-kernel function call, the eBPF program needs to + place function arguments into R1 to R5 registers to satisfy calling + convention, then the interpreter will take them from registers and pass + to in-kernel function. If R1 - R5 registers are mapped to CPU registers + that are used for argument passing on given architecture, the JIT compiler + doesn't need to emit extra moves. Function arguments will be in the correct + registers and BPF_CALL instruction will be JITed as single 'call' HW + instruction. This calling convention was picked to cover common call + situations without performance penalty. + + After an in-kernel function call, R1 - R5 are reset to unreadable and R0 has + a return value of the function. Since R6 - R9 are callee saved, their state + is preserved across the call. + + For example, consider three C functions:: + + u64 f1() { return (*_f2)(1); } + u64 f2(u64 a) { return f3(a + 1, a); } + u64 f3(u64 a, u64 b) { return a - b; } + + GCC can compile f1, f3 into x86_64:: + + f1: + movl $1, %edi + movq _f2(%rip), %rax + jmp *%rax + f3: + movq %rdi, %rax + subq %rsi, %rax + ret + + Function f2 in eBPF may look like:: + + f2: + bpf_mov R2, R1 + bpf_add R1, 1 + bpf_call f3 + bpf_exit + + If f2 is JITed and the pointer stored to ``_f2``. The calls f1 -> f2 -> f3 and + returns will be seamless. Without JIT, __bpf_prog_run() interpreter needs to + be used to call into f2. + + For practical reasons all eBPF programs have only one argument 'ctx' which is + already placed into R1 (e.g. on __bpf_prog_run() startup) and the programs + can call kernel functions with up to 5 arguments. Calls with 6 or more arguments + are currently not supported, but these restrictions can be lifted if necessary + in the future. + + On 64-bit architectures all register map to HW registers one to one. For + example, x86_64 JIT compiler can map them as ... + + :: + + R0 - rax + R1 - rdi + R2 - rsi + R3 - rdx + R4 - rcx + R5 - r8 + R6 - rbx + R7 - r13 + R8 - r14 + R9 - r15 + R10 - rbp + + ... since x86_64 ABI mandates rdi, rsi, rdx, rcx, r8, r9 for argument passing + and rbx, r12 - r15 are callee saved. + + Then the following eBPF pseudo-program:: + + bpf_mov R6, R1 /* save ctx */ + bpf_mov R2, 2 + bpf_mov R3, 3 + bpf_mov R4, 4 + bpf_mov R5, 5 + bpf_call foo + bpf_mov R7, R0 /* save foo() return value */ + bpf_mov R1, R6 /* restore ctx for next call */ + bpf_mov R2, 6 + bpf_mov R3, 7 + bpf_mov R4, 8 + bpf_mov R5, 9 + bpf_call bar + bpf_add R0, R7 + bpf_exit + + After JIT to x86_64 may look like:: + + push %rbp + mov %rsp,%rbp + sub $0x228,%rsp + mov %rbx,-0x228(%rbp) + mov %r13,-0x220(%rbp) + mov %rdi,%rbx + mov $0x2,%esi + mov $0x3,%edx + mov $0x4,%ecx + mov $0x5,%r8d + callq foo + mov %rax,%r13 + mov %rbx,%rdi + mov $0x6,%esi + mov $0x7,%edx + mov $0x8,%ecx + mov $0x9,%r8d + callq bar + add %r13,%rax + mov -0x228(%rbp),%rbx + mov -0x220(%rbp),%r13 + leaveq + retq + + Which is in this example equivalent in C to:: + + u64 bpf_filter(u64 ctx) + { + return foo(ctx, 2, 3, 4, 5) + bar(ctx, 6, 7, 8, 9); + } + + In-kernel functions foo() and bar() with prototype: u64 (*)(u64 arg1, u64 + arg2, u64 arg3, u64 arg4, u64 arg5); will receive arguments in proper + registers and place their return value into ``%rax`` which is R0 in eBPF. + Prologue and epilogue are emitted by JIT and are implicit in the + interpreter. R0-R5 are scratch registers, so eBPF program needs to preserve + them across the calls as defined by calling convention. + + For example the following program is invalid:: + + bpf_mov R1, 1 + bpf_call foo + bpf_mov R0, R1 + bpf_exit + + After the call the registers R1-R5 contain junk values and cannot be read. + An in-kernel verifier.rst is used to validate eBPF programs. + +Also in the new design, eBPF is limited to 4096 insns, which means that any +program will terminate quickly and will only call a fixed number of kernel +functions. Original BPF and eBPF are two operand instructions, +which helps to do one-to-one mapping between eBPF insn and x86 insn during JIT. + +The input context pointer for invoking the interpreter function is generic, +its content is defined by a specific use case. For seccomp register R1 points +to seccomp_data, for converted BPF filters R1 points to a skb. + +A program, that is translated internally consists of the following elements:: + + op:16, jt:8, jf:8, k:32 ==> op:8, dst_reg:4, src_reg:4, off:16, imm:32 + +So far 87 eBPF instructions were implemented. 8-bit 'op' opcode field +has room for new instructions. Some of them may use 16/24/32 byte encoding. New +instructions must be multiple of 8 bytes to preserve backward compatibility. + +eBPF is a general purpose RISC instruction set. Not every register and +every instruction are used during translation from original BPF to eBPF. +For example, socket filters are not using ``exclusive add`` instruction, but +tracing filters may do to maintain counters of events, for example. Register R9 +is not used by socket filters either, but more complex filters may be running +out of registers and would have to resort to spill/fill to stack. + +eBPF can be used as a generic assembler for last step performance +optimizations, socket filters and seccomp are using it as assembler. Tracing +filters may use it as assembler to generate code from kernel. In kernel usage +may not be bounded by security considerations, since generated eBPF code +may be optimizing internal code path and not being exposed to the user space. +Safety of eBPF can come from the verifier.rst. In such use cases as +described, it may be used as safe instruction set. + +Just like the original BPF, eBPF runs within a controlled environment, +is deterministic and the kernel can easily prove that. The safety of the program +can be determined in two steps: first step does depth-first-search to disallow +loops and other CFG validation; second step starts from the first insn and +descends all possible paths. It simulates execution of every insn and observes +the state change of registers and stack. + +opcode encoding +=============== + +eBPF is reusing most of the opcode encoding from classic to simplify conversion +of classic BPF to eBPF. + +For arithmetic and jump instructions the 8-bit 'code' field is divided into three +parts:: + + +----------------+--------+--------------------+ + | 4 bits | 1 bit | 3 bits | + | operation code | source | instruction class | + +----------------+--------+--------------------+ + (MSB) (LSB) + +Three LSB bits store instruction class which is one of: + + =================== =============== + Classic BPF classes eBPF classes + =================== =============== + BPF_LD 0x00 BPF_LD 0x00 + BPF_LDX 0x01 BPF_LDX 0x01 + BPF_ST 0x02 BPF_ST 0x02 + BPF_STX 0x03 BPF_STX 0x03 + BPF_ALU 0x04 BPF_ALU 0x04 + BPF_JMP 0x05 BPF_JMP 0x05 + BPF_RET 0x06 BPF_JMP32 0x06 + BPF_MISC 0x07 BPF_ALU64 0x07 + =================== =============== + +The 4th bit encodes the source operand ... + + :: + + BPF_K 0x00 + BPF_X 0x08 + + * in classic BPF, this means:: + + BPF_SRC(code) == BPF_X - use register X as source operand + BPF_SRC(code) == BPF_K - use 32-bit immediate as source operand + + * in eBPF, this means:: + + BPF_SRC(code) == BPF_X - use 'src_reg' register as source operand + BPF_SRC(code) == BPF_K - use 32-bit immediate as source operand + +... and four MSB bits store operation code. + +If BPF_CLASS(code) == BPF_ALU or BPF_ALU64 [ in eBPF ], BPF_OP(code) is one of:: + + BPF_ADD 0x00 + BPF_SUB 0x10 + BPF_MUL 0x20 + BPF_DIV 0x30 + BPF_OR 0x40 + BPF_AND 0x50 + BPF_LSH 0x60 + BPF_RSH 0x70 + BPF_NEG 0x80 + BPF_MOD 0x90 + BPF_XOR 0xa0 + BPF_MOV 0xb0 /* eBPF only: mov reg to reg */ + BPF_ARSH 0xc0 /* eBPF only: sign extending shift right */ + BPF_END 0xd0 /* eBPF only: endianness conversion */ + +If BPF_CLASS(code) == BPF_JMP or BPF_JMP32 [ in eBPF ], BPF_OP(code) is one of:: + + BPF_JA 0x00 /* BPF_JMP only */ + BPF_JEQ 0x10 + BPF_JGT 0x20 + BPF_JGE 0x30 + BPF_JSET 0x40 + BPF_JNE 0x50 /* eBPF only: jump != */ + BPF_JSGT 0x60 /* eBPF only: signed '>' */ + BPF_JSGE 0x70 /* eBPF only: signed '>=' */ + BPF_CALL 0x80 /* eBPF BPF_JMP only: function call */ + BPF_EXIT 0x90 /* eBPF BPF_JMP only: function return */ + BPF_JLT 0xa0 /* eBPF only: unsigned '<' */ + BPF_JLE 0xb0 /* eBPF only: unsigned '<=' */ + BPF_JSLT 0xc0 /* eBPF only: signed '<' */ + BPF_JSLE 0xd0 /* eBPF only: signed '<=' */ + +So BPF_ADD | BPF_X | BPF_ALU means 32-bit addition in both classic BPF +and eBPF. There are only two registers in classic BPF, so it means A += X. +In eBPF it means dst_reg = (u32) dst_reg + (u32) src_reg; similarly, +BPF_XOR | BPF_K | BPF_ALU means A ^= imm32 in classic BPF and analogous +src_reg = (u32) src_reg ^ (u32) imm32 in eBPF. + +Classic BPF is using BPF_MISC class to represent A = X and X = A moves. +eBPF is using BPF_MOV | BPF_X | BPF_ALU code instead. Since there are no +BPF_MISC operations in eBPF, the class 7 is used as BPF_ALU64 to mean +exactly the same operations as BPF_ALU, but with 64-bit wide operands +instead. So BPF_ADD | BPF_X | BPF_ALU64 means 64-bit addition, i.e.: +dst_reg = dst_reg + src_reg + +Classic BPF wastes the whole BPF_RET class to represent a single ``ret`` +operation. Classic BPF_RET | BPF_K means copy imm32 into return register +and perform function exit. eBPF is modeled to match CPU, so BPF_JMP | BPF_EXIT +in eBPF means function exit only. The eBPF program needs to store return +value into register R0 before doing a BPF_EXIT. Class 6 in eBPF is used as +BPF_JMP32 to mean exactly the same operations as BPF_JMP, but with 32-bit wide +operands for the comparisons instead. + +For load and store instructions the 8-bit 'code' field is divided as:: + + +--------+--------+-------------------+ + | 3 bits | 2 bits | 3 bits | + | mode | size | instruction class | + +--------+--------+-------------------+ + (MSB) (LSB) + +Size modifier is one of ... + +:: + + BPF_W 0x00 /* word */ + BPF_H 0x08 /* half word */ + BPF_B 0x10 /* byte */ + BPF_DW 0x18 /* eBPF only, double word */ + +... which encodes size of load/store operation:: + + B - 1 byte + H - 2 byte + W - 4 byte + DW - 8 byte (eBPF only) + +Mode modifier is one of:: + + BPF_IMM 0x00 /* used for 32-bit mov in classic BPF and 64-bit in eBPF */ + BPF_ABS 0x20 + BPF_IND 0x40 + BPF_MEM 0x60 + BPF_LEN 0x80 /* classic BPF only, reserved in eBPF */ + BPF_MSH 0xa0 /* classic BPF only, reserved in eBPF */ + BPF_ATOMIC 0xc0 /* eBPF only, atomic operations */ diff --git a/Documentation/bpf/faq.rst b/Documentation/bpf/faq.rst new file mode 100644 index 000000000000..a622602ce9ad --- /dev/null +++ b/Documentation/bpf/faq.rst @@ -0,0 +1,11 @@ +================================ +Frequently asked questions (FAQ) +================================ + +Two sets of Questions and Answers (Q&A) are maintained. + +.. toctree:: + :maxdepth: 1 + + bpf_design_QA + bpf_devel_QA diff --git a/Documentation/bpf/helpers.rst b/Documentation/bpf/helpers.rst new file mode 100644 index 000000000000..c4ee0cc20dec --- /dev/null +++ b/Documentation/bpf/helpers.rst @@ -0,0 +1,7 @@ +Helper functions +================ + +* `bpf-helpers(7)`_ maintains a list of helpers available to eBPF programs. + +.. Links +.. _bpf-helpers(7): https://man7.org/linux/man-pages/man7/bpf-helpers.7.html
\ No newline at end of file diff --git a/Documentation/bpf/index.rst b/Documentation/bpf/index.rst index 610450f59e05..ef5c996547ec 100644 --- a/Documentation/bpf/index.rst +++ b/Documentation/bpf/index.rst @@ -5,104 +5,33 @@ BPF Documentation This directory contains documentation for the BPF (Berkeley Packet Filter) facility, with a focus on the extended BPF version (eBPF). -This kernel side documentation is still work in progress. The main -textual documentation is (for historical reasons) described in -:ref:`networking-filter`, which describe both classical and extended -BPF instruction-set. +This kernel side documentation is still work in progress. The Cilium project also maintains a `BPF and XDP Reference Guide`_ that goes into great technical depth about the BPF Architecture. -libbpf -====== - -Documentation/bpf/libbpf/index.rst is a userspace library for loading and interacting with bpf programs. - -BPF Type Format (BTF) -===================== - .. toctree:: :maxdepth: 1 + instruction-set + verifier + libbpf/index btf - - -Frequently asked questions (FAQ) -================================ - -Two sets of Questions and Answers (Q&A) are maintained. - -.. toctree:: - :maxdepth: 1 - - bpf_design_QA - bpf_devel_QA - -Syscall API -=========== - -The primary info for the bpf syscall is available in the `man-pages`_ -for `bpf(2)`_. For more information about the userspace API, see -Documentation/userspace-api/ebpf/index.rst. - -Helper functions -================ - -* `bpf-helpers(7)`_ maintains a list of helpers available to eBPF programs. - - -Program types -============= - -.. toctree:: - :maxdepth: 1 - - prog_cgroup_sockopt - prog_cgroup_sysctl - prog_flow_dissector - bpf_lsm - prog_sk_lookup - - -Map types -========= - -.. toctree:: - :maxdepth: 1 - - map_cgroup_storage - - -Testing and debugging BPF -========================= - -.. toctree:: - :maxdepth: 1 - - drgn - s390 - - -Licensing -========= - -.. toctree:: - :maxdepth: 1 - + faq + syscall_api + helpers + programs + maps + classic_vs_extended.rst bpf_licensing + test_debug + other +.. only:: subproject and html -Other -===== - -.. toctree:: - :maxdepth: 1 + Indices + ======= - ringbuf - llvm_reloc + * :ref:`genindex` .. Links: -.. _networking-filter: ../networking/filter.rst -.. _man-pages: https://www.kernel.org/doc/man-pages/ -.. _bpf(2): https://man7.org/linux/man-pages/man2/bpf.2.html -.. _bpf-helpers(7): https://man7.org/linux/man-pages/man7/bpf-helpers.7.html .. _BPF and XDP Reference Guide: https://docs.cilium.io/en/latest/bpf/ diff --git a/Documentation/bpf/instruction-set.rst b/Documentation/bpf/instruction-set.rst new file mode 100644 index 000000000000..3704836fe6df --- /dev/null +++ b/Documentation/bpf/instruction-set.rst @@ -0,0 +1,279 @@ + +==================== +eBPF Instruction Set +==================== + +Registers and calling convention +================================ + +eBPF has 10 general purpose registers and a read-only frame pointer register, +all of which are 64-bits wide. + +The eBPF calling convention is defined as: + + * R0: return value from function calls, and exit value for eBPF programs + * R1 - R5: arguments for function calls + * R6 - R9: callee saved registers that function calls will preserve + * R10: read-only frame pointer to access stack + +R0 - R5 are scratch registers and eBPF programs needs to spill/fill them if +necessary across calls. + +Instruction encoding +==================== + +eBPF uses 64-bit instructions with the following encoding: + + ============= ======= =============== ==================== ============ + 32 bits (MSB) 16 bits 4 bits 4 bits 8 bits (LSB) + ============= ======= =============== ==================== ============ + immediate offset source register destination register opcode + ============= ======= =============== ==================== ============ + +Note that most instructions do not use all of the fields. +Unused fields shall be cleared to zero. + +Instruction classes +------------------- + +The three LSB bits of the 'opcode' field store the instruction class: + + ========= ===== =============================== + class value description + ========= ===== =============================== + BPF_LD 0x00 non-standard load operations + BPF_LDX 0x01 load into register operations + BPF_ST 0x02 store from immediate operations + BPF_STX 0x03 store from register operations + BPF_ALU 0x04 32-bit arithmetic operations + BPF_JMP 0x05 64-bit jump operations + BPF_JMP32 0x06 32-bit jump operations + BPF_ALU64 0x07 64-bit arithmetic operations + ========= ===== =============================== + +Arithmetic and jump instructions +================================ + +For arithmetic and jump instructions (BPF_ALU, BPF_ALU64, BPF_JMP and +BPF_JMP32), the 8-bit 'opcode' field is divided into three parts: + + ============== ====== ================= + 4 bits (MSB) 1 bit 3 bits (LSB) + ============== ====== ================= + operation code source instruction class + ============== ====== ================= + +The 4th bit encodes the source operand: + + ====== ===== ======================================== + source value description + ====== ===== ======================================== + BPF_K 0x00 use 32-bit immediate as source operand + BPF_X 0x08 use 'src_reg' register as source operand + ====== ===== ======================================== + +The four MSB bits store the operation code. + + +Arithmetic instructions +----------------------- + +BPF_ALU uses 32-bit wide operands while BPF_ALU64 uses 64-bit wide operands for +otherwise identical operations. +The code field encodes the operation as below: + + ======== ===== ========================== + code value description + ======== ===== ========================== + BPF_ADD 0x00 dst += src + BPF_SUB 0x10 dst -= src + BPF_MUL 0x20 dst \*= src + BPF_DIV 0x30 dst /= src + BPF_OR 0x40 dst \|= src + BPF_AND 0x50 dst &= src + BPF_LSH 0x60 dst <<= src + BPF_RSH 0x70 dst >>= src + BPF_NEG 0x80 dst = ~src + BPF_MOD 0x90 dst %= src + BPF_XOR 0xa0 dst ^= src + BPF_MOV 0xb0 dst = src + BPF_ARSH 0xc0 sign extending shift right + BPF_END 0xd0 endianness conversion + ======== ===== ========================== + +BPF_ADD | BPF_X | BPF_ALU means:: + + dst_reg = (u32) dst_reg + (u32) src_reg; + +BPF_ADD | BPF_X | BPF_ALU64 means:: + + dst_reg = dst_reg + src_reg + +BPF_XOR | BPF_K | BPF_ALU means:: + + src_reg = (u32) src_reg ^ (u32) imm32 + +BPF_XOR | BPF_K | BPF_ALU64 means:: + + src_reg = src_reg ^ imm32 + + +Jump instructions +----------------- + +BPF_JMP32 uses 32-bit wide operands while BPF_JMP uses 64-bit wide operands for +otherwise identical operations. +The code field encodes the operation as below: + + ======== ===== ========================= ============ + code value description notes + ======== ===== ========================= ============ + BPF_JA 0x00 PC += off BPF_JMP only + BPF_JEQ 0x10 PC += off if dst == src + BPF_JGT 0x20 PC += off if dst > src unsigned + BPF_JGE 0x30 PC += off if dst >= src unsigned + BPF_JSET 0x40 PC += off if dst & src + BPF_JNE 0x50 PC += off if dst != src + BPF_JSGT 0x60 PC += off if dst > src signed + BPF_JSGE 0x70 PC += off if dst >= src signed + BPF_CALL 0x80 function call + BPF_EXIT 0x90 function / program return BPF_JMP only + BPF_JLT 0xa0 PC += off if dst < src unsigned + BPF_JLE 0xb0 PC += off if dst <= src unsigned + BPF_JSLT 0xc0 PC += off if dst < src signed + BPF_JSLE 0xd0 PC += off if dst <= src signed + ======== ===== ========================= ============ + +The eBPF program needs to store the return value into register R0 before doing a +BPF_EXIT. + + +Load and store instructions +=========================== + +For load and store instructions (BPF_LD, BPF_LDX, BPF_ST and BPF_STX), the +8-bit 'opcode' field is divided as: + + ============ ====== ================= + 3 bits (MSB) 2 bits 3 bits (LSB) + ============ ====== ================= + mode size instruction class + ============ ====== ================= + +The size modifier is one of: + + ============= ===== ===================== + size modifier value description + ============= ===== ===================== + BPF_W 0x00 word (4 bytes) + BPF_H 0x08 half word (2 bytes) + BPF_B 0x10 byte + BPF_DW 0x18 double word (8 bytes) + ============= ===== ===================== + +The mode modifier is one of: + + ============= ===== ==================================== + mode modifier value description + ============= ===== ==================================== + BPF_IMM 0x00 used for 64-bit mov + BPF_ABS 0x20 legacy BPF packet access + BPF_IND 0x40 legacy BPF packet access + BPF_MEM 0x60 all normal load and store operations + BPF_ATOMIC 0xc0 atomic operations + ============= ===== ==================================== + +BPF_MEM | <size> | BPF_STX means:: + + *(size *) (dst_reg + off) = src_reg + +BPF_MEM | <size> | BPF_ST means:: + + *(size *) (dst_reg + off) = imm32 + +BPF_MEM | <size> | BPF_LDX means:: + + dst_reg = *(size *) (src_reg + off) + +Where size is one of: BPF_B or BPF_H or BPF_W or BPF_DW. + +Atomic operations +----------------- + +eBPF includes atomic operations, which use the immediate field for extra +encoding:: + + .imm = BPF_ADD, .code = BPF_ATOMIC | BPF_W | BPF_STX: lock xadd *(u32 *)(dst_reg + off16) += src_reg + .imm = BPF_ADD, .code = BPF_ATOMIC | BPF_DW | BPF_STX: lock xadd *(u64 *)(dst_reg + off16) += src_reg + +The basic atomic operations supported are:: + + BPF_ADD + BPF_AND + BPF_OR + BPF_XOR + +Each having equivalent semantics with the ``BPF_ADD`` example, that is: the +memory location addresed by ``dst_reg + off`` is atomically modified, with +``src_reg`` as the other operand. If the ``BPF_FETCH`` flag is set in the +immediate, then these operations also overwrite ``src_reg`` with the +value that was in memory before it was modified. + +The more special operations are:: + + BPF_XCHG + +This atomically exchanges ``src_reg`` with the value addressed by ``dst_reg + +off``. :: + + BPF_CMPXCHG + +This atomically compares the value addressed by ``dst_reg + off`` with +``R0``. If they match it is replaced with ``src_reg``. In either case, the +value that was there before is zero-extended and loaded back to ``R0``. + +Note that 1 and 2 byte atomic operations are not supported. + +Clang can generate atomic instructions by default when ``-mcpu=v3`` is +enabled. If a lower version for ``-mcpu`` is set, the only atomic instruction +Clang can generate is ``BPF_ADD`` *without* ``BPF_FETCH``. If you need to enable +the atomics features, while keeping a lower ``-mcpu`` version, you can use +``-Xclang -target-feature -Xclang +alu32``. + +You may encounter ``BPF_XADD`` - this is a legacy name for ``BPF_ATOMIC``, +referring to the exclusive-add operation encoded when the immediate field is +zero. + +16-byte instructions +-------------------- + +eBPF has one 16-byte instruction: ``BPF_LD | BPF_DW | BPF_IMM`` which consists +of two consecutive ``struct bpf_insn`` 8-byte blocks and interpreted as single +instruction that loads 64-bit immediate value into a dst_reg. + +Packet access instructions +-------------------------- + +eBPF has two non-generic instructions: (BPF_ABS | <size> | BPF_LD) and +(BPF_IND | <size> | BPF_LD) which are used to access packet data. + +They had to be carried over from classic BPF to have strong performance of +socket filters running in eBPF interpreter. These instructions can only +be used when interpreter context is a pointer to ``struct sk_buff`` and +have seven implicit operands. Register R6 is an implicit input that must +contain pointer to sk_buff. Register R0 is an implicit output which contains +the data fetched from the packet. Registers R1-R5 are scratch registers +and must not be used to store the data across BPF_ABS | BPF_LD or +BPF_IND | BPF_LD instructions. + +These instructions have implicit program exit condition as well. When +eBPF program is trying to access the data beyond the packet boundary, +the interpreter will abort the execution of the program. JIT compilers +therefore must preserve this property. src_reg and imm32 fields are +explicit inputs to these instructions. + +For example, BPF_IND | BPF_W | BPF_LD means:: + + R0 = ntohl(*(u32 *) (((struct sk_buff *) R6)->data + src_reg + imm32)) + +and R1 - R5 are clobbered. diff --git a/Documentation/bpf/libbpf/index.rst b/Documentation/bpf/libbpf/index.rst index 4f8adfc3ab83..4e8c656b539a 100644 --- a/Documentation/bpf/libbpf/index.rst +++ b/Documentation/bpf/libbpf/index.rst @@ -3,8 +3,6 @@ libbpf ====== -For API documentation see the `versioned API documentation site <https://libbpf.readthedocs.io/en/latest/api.html>`_. - .. toctree:: :maxdepth: 1 @@ -14,6 +12,8 @@ For API documentation see the `versioned API documentation site <https://libbpf. This is documentation for libbpf, a userspace library for loading and interacting with bpf programs. +For API documentation see the `versioned API documentation site <https://libbpf.readthedocs.io/en/latest/api.html>`_. + All general BPF questions, including kernel functionality, libbpf APIs and their application, should be sent to bpf@vger.kernel.org mailing list. You can `subscribe <http://vger.kernel.org/vger-lists.html#bpf>`_ to the diff --git a/Documentation/bpf/maps.rst b/Documentation/bpf/maps.rst new file mode 100644 index 000000000000..f41619e312ac --- /dev/null +++ b/Documentation/bpf/maps.rst @@ -0,0 +1,52 @@ + +========= +eBPF maps +========= + +'maps' is a generic storage of different types for sharing data between kernel +and userspace. + +The maps are accessed from user space via BPF syscall, which has commands: + +- create a map with given type and attributes + ``map_fd = bpf(BPF_MAP_CREATE, union bpf_attr *attr, u32 size)`` + using attr->map_type, attr->key_size, attr->value_size, attr->max_entries + returns process-local file descriptor or negative error + +- lookup key in a given map + ``err = bpf(BPF_MAP_LOOKUP_ELEM, union bpf_attr *attr, u32 size)`` + using attr->map_fd, attr->key, attr->value + returns zero and stores found elem into value or negative error + +- create or update key/value pair in a given map + ``err = bpf(BPF_MAP_UPDATE_ELEM, union bpf_attr *attr, u32 size)`` + using attr->map_fd, attr->key, attr->value + returns zero or negative error + +- find and delete element by key in a given map + ``err = bpf(BPF_MAP_DELETE_ELEM, union bpf_attr *attr, u32 size)`` + using attr->map_fd, attr->key + +- to delete map: close(fd) + Exiting process will delete maps automatically + +userspace programs use this syscall to create/access maps that eBPF programs +are concurrently updating. + +maps can have different types: hash, array, bloom filter, radix-tree, etc. + +The map is defined by: + + - type + - max number of elements + - key size in bytes + - value size in bytes + +Map Types +========= + +.. toctree:: + :maxdepth: 1 + :glob: + + map_*
\ No newline at end of file diff --git a/Documentation/bpf/other.rst b/Documentation/bpf/other.rst new file mode 100644 index 000000000000..3d61963403b4 --- /dev/null +++ b/Documentation/bpf/other.rst @@ -0,0 +1,9 @@ +===== +Other +===== + +.. toctree:: + :maxdepth: 1 + + ringbuf + llvm_reloc
\ No newline at end of file diff --git a/Documentation/bpf/bpf_lsm.rst b/Documentation/bpf/prog_lsm.rst index 0dc3fb0d9544..0dc3fb0d9544 100644 --- a/Documentation/bpf/bpf_lsm.rst +++ b/Documentation/bpf/prog_lsm.rst diff --git a/Documentation/bpf/programs.rst b/Documentation/bpf/programs.rst new file mode 100644 index 000000000000..620eb667ac7a --- /dev/null +++ b/Documentation/bpf/programs.rst @@ -0,0 +1,9 @@ +============= +Program Types +============= + +.. toctree:: + :maxdepth: 1 + :glob: + + prog_* diff --git a/Documentation/bpf/syscall_api.rst b/Documentation/bpf/syscall_api.rst new file mode 100644 index 000000000000..f0a1dff087ad --- /dev/null +++ b/Documentation/bpf/syscall_api.rst @@ -0,0 +1,11 @@ +=========== +Syscall API +=========== + +The primary info for the bpf syscall is available in the `man-pages`_ +for `bpf(2)`_. For more information about the userspace API, see +Documentation/userspace-api/ebpf/index.rst. + +.. Links: +.. _man-pages: https://www.kernel.org/doc/man-pages/ +.. _bpf(2): https://man7.org/linux/man-pages/man2/bpf.2.html
\ No newline at end of file diff --git a/Documentation/bpf/test_debug.rst b/Documentation/bpf/test_debug.rst new file mode 100644 index 000000000000..ebf0caceb6a6 --- /dev/null +++ b/Documentation/bpf/test_debug.rst @@ -0,0 +1,9 @@ +========================= +Testing and debugging BPF +========================= + +.. toctree:: + :maxdepth: 1 + + drgn + s390 diff --git a/Documentation/bpf/verifier.rst b/Documentation/bpf/verifier.rst new file mode 100644 index 000000000000..fae5f6273bac --- /dev/null +++ b/Documentation/bpf/verifier.rst @@ -0,0 +1,529 @@ + +============= +eBPF verifier +============= + +The safety of the eBPF program is determined in two steps. + +First step does DAG check to disallow loops and other CFG validation. +In particular it will detect programs that have unreachable instructions. +(though classic BPF checker allows them) + +Second step starts from the first insn and descends all possible paths. +It simulates execution of every insn and observes the state change of +registers and stack. + +At the start of the program the register R1 contains a pointer to context +and has type PTR_TO_CTX. +If verifier sees an insn that does R2=R1, then R2 has now type +PTR_TO_CTX as well and can be used on the right hand side of expression. +If R1=PTR_TO_CTX and insn is R2=R1+R1, then R2=SCALAR_VALUE, +since addition of two valid pointers makes invalid pointer. +(In 'secure' mode verifier will reject any type of pointer arithmetic to make +sure that kernel addresses don't leak to unprivileged users) + +If register was never written to, it's not readable:: + + bpf_mov R0 = R2 + bpf_exit + +will be rejected, since R2 is unreadable at the start of the program. + +After kernel function call, R1-R5 are reset to unreadable and +R0 has a return type of the function. + +Since R6-R9 are callee saved, their state is preserved across the call. + +:: + + bpf_mov R6 = 1 + bpf_call foo + bpf_mov R0 = R6 + bpf_exit + +is a correct program. If there was R1 instead of R6, it would have +been rejected. + +load/store instructions are allowed only with registers of valid types, which +are PTR_TO_CTX, PTR_TO_MAP, PTR_TO_STACK. They are bounds and alignment checked. +For example:: + + bpf_mov R1 = 1 + bpf_mov R2 = 2 + bpf_xadd *(u32 *)(R1 + 3) += R2 + bpf_exit + +will be rejected, since R1 doesn't have a valid pointer type at the time of +execution of instruction bpf_xadd. + +At the start R1 type is PTR_TO_CTX (a pointer to generic ``struct bpf_context``) +A callback is used to customize verifier to restrict eBPF program access to only +certain fields within ctx structure with specified size and alignment. + +For example, the following insn:: + + bpf_ld R0 = *(u32 *)(R6 + 8) + +intends to load a word from address R6 + 8 and store it into R0 +If R6=PTR_TO_CTX, via is_valid_access() callback the verifier will know +that offset 8 of size 4 bytes can be accessed for reading, otherwise +the verifier will reject the program. +If R6=PTR_TO_STACK, then access should be aligned and be within +stack bounds, which are [-MAX_BPF_STACK, 0). In this example offset is 8, +so it will fail verification, since it's out of bounds. + +The verifier will allow eBPF program to read data from stack only after +it wrote into it. + +Classic BPF verifier does similar check with M[0-15] memory slots. +For example:: + + bpf_ld R0 = *(u32 *)(R10 - 4) + bpf_exit + +is invalid program. +Though R10 is correct read-only register and has type PTR_TO_STACK +and R10 - 4 is within stack bounds, there were no stores into that location. + +Pointer register spill/fill is tracked as well, since four (R6-R9) +callee saved registers may not be enough for some programs. + +Allowed function calls are customized with bpf_verifier_ops->get_func_proto() +The eBPF verifier will check that registers match argument constraints. +After the call register R0 will be set to return type of the function. + +Function calls is a main mechanism to extend functionality of eBPF programs. +Socket filters may let programs to call one set of functions, whereas tracing +filters may allow completely different set. + +If a function made accessible to eBPF program, it needs to be thought through +from safety point of view. The verifier will guarantee that the function is +called with valid arguments. + +seccomp vs socket filters have different security restrictions for classic BPF. +Seccomp solves this by two stage verifier: classic BPF verifier is followed +by seccomp verifier. In case of eBPF one configurable verifier is shared for +all use cases. + +See details of eBPF verifier in kernel/bpf/verifier.c + +Register value tracking +======================= + +In order to determine the safety of an eBPF program, the verifier must track +the range of possible values in each register and also in each stack slot. +This is done with ``struct bpf_reg_state``, defined in include/linux/ +bpf_verifier.h, which unifies tracking of scalar and pointer values. Each +register state has a type, which is either NOT_INIT (the register has not been +written to), SCALAR_VALUE (some value which is not usable as a pointer), or a +pointer type. The types of pointers describe their base, as follows: + + + PTR_TO_CTX + Pointer to bpf_context. + CONST_PTR_TO_MAP + Pointer to struct bpf_map. "Const" because arithmetic + on these pointers is forbidden. + PTR_TO_MAP_VALUE + Pointer to the value stored in a map element. + PTR_TO_MAP_VALUE_OR_NULL + Either a pointer to a map value, or NULL; map accesses + (see maps.rst) return this type, which becomes a + PTR_TO_MAP_VALUE when checked != NULL. Arithmetic on + these pointers is forbidden. + PTR_TO_STACK + Frame pointer. + PTR_TO_PACKET + skb->data. + PTR_TO_PACKET_END + skb->data + headlen; arithmetic forbidden. + PTR_TO_SOCKET + Pointer to struct bpf_sock_ops, implicitly refcounted. + PTR_TO_SOCKET_OR_NULL + Either a pointer to a socket, or NULL; socket lookup + returns this type, which becomes a PTR_TO_SOCKET when + checked != NULL. PTR_TO_SOCKET is reference-counted, + so programs must release the reference through the + socket release function before the end of the program. + Arithmetic on these pointers is forbidden. + +However, a pointer may be offset from this base (as a result of pointer +arithmetic), and this is tracked in two parts: the 'fixed offset' and 'variable +offset'. The former is used when an exactly-known value (e.g. an immediate +operand) is added to a pointer, while the latter is used for values which are +not exactly known. The variable offset is also used in SCALAR_VALUEs, to track +the range of possible values in the register. + +The verifier's knowledge about the variable offset consists of: + +* minimum and maximum values as unsigned +* minimum and maximum values as signed + +* knowledge of the values of individual bits, in the form of a 'tnum': a u64 + 'mask' and a u64 'value'. 1s in the mask represent bits whose value is unknown; + 1s in the value represent bits known to be 1. Bits known to be 0 have 0 in both + mask and value; no bit should ever be 1 in both. For example, if a byte is read + into a register from memory, the register's top 56 bits are known zero, while + the low 8 are unknown - which is represented as the tnum (0x0; 0xff). If we + then OR this with 0x40, we get (0x40; 0xbf), then if we add 1 we get (0x0; + 0x1ff), because of potential carries. + +Besides arithmetic, the register state can also be updated by conditional +branches. For instance, if a SCALAR_VALUE is compared > 8, in the 'true' branch +it will have a umin_value (unsigned minimum value) of 9, whereas in the 'false' +branch it will have a umax_value of 8. A signed compare (with BPF_JSGT or +BPF_JSGE) would instead update the signed minimum/maximum values. Information +from the signed and unsigned bounds can be combined; for instance if a value is +first tested < 8 and then tested s> 4, the verifier will conclude that the value +is also > 4 and s< 8, since the bounds prevent crossing the sign boundary. + +PTR_TO_PACKETs with a variable offset part have an 'id', which is common to all +pointers sharing that same variable offset. This is important for packet range +checks: after adding a variable to a packet pointer register A, if you then copy +it to another register B and then add a constant 4 to A, both registers will +share the same 'id' but the A will have a fixed offset of +4. Then if A is +bounds-checked and found to be less than a PTR_TO_PACKET_END, the register B is +now known to have a safe range of at least 4 bytes. See 'Direct packet access', +below, for more on PTR_TO_PACKET ranges. + +The 'id' field is also used on PTR_TO_MAP_VALUE_OR_NULL, common to all copies of +the pointer returned from a map lookup. This means that when one copy is +checked and found to be non-NULL, all copies can become PTR_TO_MAP_VALUEs. +As well as range-checking, the tracked information is also used for enforcing +alignment of pointer accesses. For instance, on most systems the packet pointer +is 2 bytes after a 4-byte alignment. If a program adds 14 bytes to that to jump +over the Ethernet header, then reads IHL and addes (IHL * 4), the resulting +pointer will have a variable offset known to be 4n+2 for some n, so adding the 2 +bytes (NET_IP_ALIGN) gives a 4-byte alignment and so word-sized accesses through +that pointer are safe. +The 'id' field is also used on PTR_TO_SOCKET and PTR_TO_SOCKET_OR_NULL, common +to all copies of the pointer returned from a socket lookup. This has similar +behaviour to the handling for PTR_TO_MAP_VALUE_OR_NULL->PTR_TO_MAP_VALUE, but +it also handles reference tracking for the pointer. PTR_TO_SOCKET implicitly +represents a reference to the corresponding ``struct sock``. To ensure that the +reference is not leaked, it is imperative to NULL-check the reference and in +the non-NULL case, and pass the valid reference to the socket release function. + +Direct packet access +==================== + +In cls_bpf and act_bpf programs the verifier allows direct access to the packet +data via skb->data and skb->data_end pointers. +Ex:: + + 1: r4 = *(u32 *)(r1 +80) /* load skb->data_end */ + 2: r3 = *(u32 *)(r1 +76) /* load skb->data */ + 3: r5 = r3 + 4: r5 += 14 + 5: if r5 > r4 goto pc+16 + R1=ctx R3=pkt(id=0,off=0,r=14) R4=pkt_end R5=pkt(id=0,off=14,r=14) R10=fp + 6: r0 = *(u16 *)(r3 +12) /* access 12 and 13 bytes of the packet */ + +this 2byte load from the packet is safe to do, since the program author +did check ``if (skb->data + 14 > skb->data_end) goto err`` at insn #5 which +means that in the fall-through case the register R3 (which points to skb->data) +has at least 14 directly accessible bytes. The verifier marks it +as R3=pkt(id=0,off=0,r=14). +id=0 means that no additional variables were added to the register. +off=0 means that no additional constants were added. +r=14 is the range of safe access which means that bytes [R3, R3 + 14) are ok. +Note that R5 is marked as R5=pkt(id=0,off=14,r=14). It also points +to the packet data, but constant 14 was added to the register, so +it now points to ``skb->data + 14`` and accessible range is [R5, R5 + 14 - 14) +which is zero bytes. + +More complex packet access may look like:: + + + R0=inv1 R1=ctx R3=pkt(id=0,off=0,r=14) R4=pkt_end R5=pkt(id=0,off=14,r=14) R10=fp + 6: r0 = *(u8 *)(r3 +7) /* load 7th byte from the packet */ + 7: r4 = *(u8 *)(r3 +12) + 8: r4 *= 14 + 9: r3 = *(u32 *)(r1 +76) /* load skb->data */ + 10: r3 += r4 + 11: r2 = r1 + 12: r2 <<= 48 + 13: r2 >>= 48 + 14: r3 += r2 + 15: r2 = r3 + 16: r2 += 8 + 17: r1 = *(u32 *)(r1 +80) /* load skb->data_end */ + 18: if r2 > r1 goto pc+2 + R0=inv(id=0,umax_value=255,var_off=(0x0; 0xff)) R1=pkt_end R2=pkt(id=2,off=8,r=8) R3=pkt(id=2,off=0,r=8) R4=inv(id=0,umax_value=3570,var_off=(0x0; 0xfffe)) R5=pkt(id=0,off=14,r=14) R10=fp + 19: r1 = *(u8 *)(r3 +4) + +The state of the register R3 is R3=pkt(id=2,off=0,r=8) +id=2 means that two ``r3 += rX`` instructions were seen, so r3 points to some +offset within a packet and since the program author did +``if (r3 + 8 > r1) goto err`` at insn #18, the safe range is [R3, R3 + 8). +The verifier only allows 'add'/'sub' operations on packet registers. Any other +operation will set the register state to 'SCALAR_VALUE' and it won't be +available for direct packet access. + +Operation ``r3 += rX`` may overflow and become less than original skb->data, +therefore the verifier has to prevent that. So when it sees ``r3 += rX`` +instruction and rX is more than 16-bit value, any subsequent bounds-check of r3 +against skb->data_end will not give us 'range' information, so attempts to read +through the pointer will give "invalid access to packet" error. + +Ex. after insn ``r4 = *(u8 *)(r3 +12)`` (insn #7 above) the state of r4 is +R4=inv(id=0,umax_value=255,var_off=(0x0; 0xff)) which means that upper 56 bits +of the register are guaranteed to be zero, and nothing is known about the lower +8 bits. After insn ``r4 *= 14`` the state becomes +R4=inv(id=0,umax_value=3570,var_off=(0x0; 0xfffe)), since multiplying an 8-bit +value by constant 14 will keep upper 52 bits as zero, also the least significant +bit will be zero as 14 is even. Similarly ``r2 >>= 48`` will make +R2=inv(id=0,umax_value=65535,var_off=(0x0; 0xffff)), since the shift is not sign +extending. This logic is implemented in adjust_reg_min_max_vals() function, +which calls adjust_ptr_min_max_vals() for adding pointer to scalar (or vice +versa) and adjust_scalar_min_max_vals() for operations on two scalars. + +The end result is that bpf program author can access packet directly +using normal C code as:: + + void *data = (void *)(long)skb->data; + void *data_end = (void *)(long)skb->data_end; + struct eth_hdr *eth = data; + struct iphdr *iph = data + sizeof(*eth); + struct udphdr *udp = data + sizeof(*eth) + sizeof(*iph); + + if (data + sizeof(*eth) + sizeof(*iph) + sizeof(*udp) > data_end) + return 0; + if (eth->h_proto != htons(ETH_P_IP)) + return 0; + if (iph->protocol != IPPROTO_UDP || iph->ihl != 5) + return 0; + if (udp->dest == 53 || udp->source == 9) + ...; + +which makes such programs easier to write comparing to LD_ABS insn +and significantly faster. + +Pruning +======= + +The verifier does not actually walk all possible paths through the program. For +each new branch to analyse, the verifier looks at all the states it's previously +been in when at this instruction. If any of them contain the current state as a +subset, the branch is 'pruned' - that is, the fact that the previous state was +accepted implies the current state would be as well. For instance, if in the +previous state, r1 held a packet-pointer, and in the current state, r1 holds a +packet-pointer with a range as long or longer and at least as strict an +alignment, then r1 is safe. Similarly, if r2 was NOT_INIT before then it can't +have been used by any path from that point, so any value in r2 (including +another NOT_INIT) is safe. The implementation is in the function regsafe(). +Pruning considers not only the registers but also the stack (and any spilled +registers it may hold). They must all be safe for the branch to be pruned. +This is implemented in states_equal(). + +Understanding eBPF verifier messages +==================================== + +The following are few examples of invalid eBPF programs and verifier error +messages as seen in the log: + +Program with unreachable instructions:: + + static struct bpf_insn prog[] = { + BPF_EXIT_INSN(), + BPF_EXIT_INSN(), + }; + +Error: + + unreachable insn 1 + +Program that reads uninitialized register:: + + BPF_MOV64_REG(BPF_REG_0, BPF_REG_2), + BPF_EXIT_INSN(), + +Error:: + + 0: (bf) r0 = r2 + R2 !read_ok + +Program that doesn't initialize R0 before exiting:: + + BPF_MOV64_REG(BPF_REG_2, BPF_REG_1), + BPF_EXIT_INSN(), + +Error:: + + 0: (bf) r2 = r1 + 1: (95) exit + R0 !read_ok + +Program that accesses stack out of bounds:: + + BPF_ST_MEM(BPF_DW, BPF_REG_10, 8, 0), + BPF_EXIT_INSN(), + +Error:: + + 0: (7a) *(u64 *)(r10 +8) = 0 + invalid stack off=8 size=8 + +Program that doesn't initialize stack before passing its address into function:: + + BPF_MOV64_REG(BPF_REG_2, BPF_REG_10), + BPF_ALU64_IMM(BPF_ADD, BPF_REG_2, -8), + BPF_LD_MAP_FD(BPF_REG_1, 0), + BPF_RAW_INSN(BPF_JMP | BPF_CALL, 0, 0, 0, BPF_FUNC_map_lookup_elem), + BPF_EXIT_INSN(), + +Error:: + + 0: (bf) r2 = r10 + 1: (07) r2 += -8 + 2: (b7) r1 = 0x0 + 3: (85) call 1 + invalid indirect read from stack off -8+0 size 8 + +Program that uses invalid map_fd=0 while calling to map_lookup_elem() function:: + + BPF_ST_MEM(BPF_DW, BPF_REG_10, -8, 0), + BPF_MOV64_REG(BPF_REG_2, BPF_REG_10), + BPF_ALU64_IMM(BPF_ADD, BPF_REG_2, -8), + BPF_LD_MAP_FD(BPF_REG_1, 0), + BPF_RAW_INSN(BPF_JMP | BPF_CALL, 0, 0, 0, BPF_FUNC_map_lookup_elem), + BPF_EXIT_INSN(), + +Error:: + + 0: (7a) *(u64 *)(r10 -8) = 0 + 1: (bf) r2 = r10 + 2: (07) r2 += -8 + 3: (b7) r1 = 0x0 + 4: (85) call 1 + fd 0 is not pointing to valid bpf_map + +Program that doesn't check return value of map_lookup_elem() before accessing +map element:: + + BPF_ST_MEM(BPF_DW, BPF_REG_10, -8, 0), + BPF_MOV64_REG(BPF_REG_2, BPF_REG_10), + BPF_ALU64_IMM(BPF_ADD, BPF_REG_2, -8), + BPF_LD_MAP_FD(BPF_REG_1, 0), + BPF_RAW_INSN(BPF_JMP | BPF_CALL, 0, 0, 0, BPF_FUNC_map_lookup_elem), + BPF_ST_MEM(BPF_DW, BPF_REG_0, 0, 0), + BPF_EXIT_INSN(), + +Error:: + + 0: (7a) *(u64 *)(r10 -8) = 0 + 1: (bf) r2 = r10 + 2: (07) r2 += -8 + 3: (b7) r1 = 0x0 + 4: (85) call 1 + 5: (7a) *(u64 *)(r0 +0) = 0 + R0 invalid mem access 'map_value_or_null' + +Program that correctly checks map_lookup_elem() returned value for NULL, but +accesses the memory with incorrect alignment:: + + BPF_ST_MEM(BPF_DW, BPF_REG_10, -8, 0), + BPF_MOV64_REG(BPF_REG_2, BPF_REG_10), + BPF_ALU64_IMM(BPF_ADD, BPF_REG_2, -8), + BPF_LD_MAP_FD(BPF_REG_1, 0), + BPF_RAW_INSN(BPF_JMP | BPF_CALL, 0, 0, 0, BPF_FUNC_map_lookup_elem), + BPF_JMP_IMM(BPF_JEQ, BPF_REG_0, 0, 1), + BPF_ST_MEM(BPF_DW, BPF_REG_0, 4, 0), + BPF_EXIT_INSN(), + +Error:: + + 0: (7a) *(u64 *)(r10 -8) = 0 + 1: (bf) r2 = r10 + 2: (07) r2 += -8 + 3: (b7) r1 = 1 + 4: (85) call 1 + 5: (15) if r0 == 0x0 goto pc+1 + R0=map_ptr R10=fp + 6: (7a) *(u64 *)(r0 +4) = 0 + misaligned access off 4 size 8 + +Program that correctly checks map_lookup_elem() returned value for NULL and +accesses memory with correct alignment in one side of 'if' branch, but fails +to do so in the other side of 'if' branch:: + + BPF_ST_MEM(BPF_DW, BPF_REG_10, -8, 0), + BPF_MOV64_REG(BPF_REG_2, BPF_REG_10), + BPF_ALU64_IMM(BPF_ADD, BPF_REG_2, -8), + BPF_LD_MAP_FD(BPF_REG_1, 0), + BPF_RAW_INSN(BPF_JMP | BPF_CALL, 0, 0, 0, BPF_FUNC_map_lookup_elem), + BPF_JMP_IMM(BPF_JEQ, BPF_REG_0, 0, 2), + BPF_ST_MEM(BPF_DW, BPF_REG_0, 0, 0), + BPF_EXIT_INSN(), + BPF_ST_MEM(BPF_DW, BPF_REG_0, 0, 1), + BPF_EXIT_INSN(), + +Error:: + + 0: (7a) *(u64 *)(r10 -8) = 0 + 1: (bf) r2 = r10 + 2: (07) r2 += -8 + 3: (b7) r1 = 1 + 4: (85) call 1 + 5: (15) if r0 == 0x0 goto pc+2 + R0=map_ptr R10=fp + 6: (7a) *(u64 *)(r0 +0) = 0 + 7: (95) exit + + from 5 to 8: R0=imm0 R10=fp + 8: (7a) *(u64 *)(r0 +0) = 1 + R0 invalid mem access 'imm' + +Program that performs a socket lookup then sets the pointer to NULL without +checking it:: + + BPF_MOV64_IMM(BPF_REG_2, 0), + BPF_STX_MEM(BPF_W, BPF_REG_10, BPF_REG_2, -8), + BPF_MOV64_REG(BPF_REG_2, BPF_REG_10), + BPF_ALU64_IMM(BPF_ADD, BPF_REG_2, -8), + BPF_MOV64_IMM(BPF_REG_3, 4), + BPF_MOV64_IMM(BPF_REG_4, 0), + BPF_MOV64_IMM(BPF_REG_5, 0), + BPF_EMIT_CALL(BPF_FUNC_sk_lookup_tcp), + BPF_MOV64_IMM(BPF_REG_0, 0), + BPF_EXIT_INSN(), + +Error:: + + 0: (b7) r2 = 0 + 1: (63) *(u32 *)(r10 -8) = r2 + 2: (bf) r2 = r10 + 3: (07) r2 += -8 + 4: (b7) r3 = 4 + 5: (b7) r4 = 0 + 6: (b7) r5 = 0 + 7: (85) call bpf_sk_lookup_tcp#65 + 8: (b7) r0 = 0 + 9: (95) exit + Unreleased reference id=1, alloc_insn=7 + +Program that performs a socket lookup but does not NULL-check the returned +value:: + + BPF_MOV64_IMM(BPF_REG_2, 0), + BPF_STX_MEM(BPF_W, BPF_REG_10, BPF_REG_2, -8), + BPF_MOV64_REG(BPF_REG_2, BPF_REG_10), + BPF_ALU64_IMM(BPF_ADD, BPF_REG_2, -8), + BPF_MOV64_IMM(BPF_REG_3, 4), + BPF_MOV64_IMM(BPF_REG_4, 0), + BPF_MOV64_IMM(BPF_REG_5, 0), + BPF_EMIT_CALL(BPF_FUNC_sk_lookup_tcp), + BPF_EXIT_INSN(), + +Error:: + + 0: (b7) r2 = 0 + 1: (63) *(u32 *)(r10 -8) = r2 + 2: (bf) r2 = r10 + 3: (07) r2 += -8 + 4: (b7) r3 = 4 + 5: (b7) r4 = 0 + 6: (b7) r5 = 0 + 7: (85) call bpf_sk_lookup_tcp#65 + 8: (95) exit + Unreleased reference id=1, alloc_insn=7 diff --git a/Documentation/conf.py b/Documentation/conf.py index 17f7cee56987..f07f2e9b9f2c 100644 --- a/Documentation/conf.py +++ b/Documentation/conf.py @@ -208,16 +208,86 @@ highlight_language = 'none' # The theme to use for HTML and HTML Help pages. See the documentation for # a list of builtin themes. -# The Read the Docs theme is available from -# - https://github.com/snide/sphinx_rtd_theme -# - https://pypi.python.org/pypi/sphinx_rtd_theme -# - python-sphinx-rtd-theme package (on Debian) -try: - import sphinx_rtd_theme - html_theme = 'sphinx_rtd_theme' - html_theme_path = [sphinx_rtd_theme.get_html_theme_path()] -except ImportError: - sys.stderr.write('Warning: The Sphinx \'sphinx_rtd_theme\' HTML theme was not found. Make sure you have the theme installed to produce pretty HTML output. Falling back to the default theme.\n') +# Default theme +html_theme = 'sphinx_rtd_theme' +html_css_files = [] + +if "DOCS_THEME" in os.environ: + html_theme = os.environ["DOCS_THEME"] + +if html_theme == 'sphinx_rtd_theme' or html_theme == 'sphinx_rtd_dark_mode': + # Read the Docs theme + try: + import sphinx_rtd_theme + html_theme_path = [sphinx_rtd_theme.get_html_theme_path()] + + # Add any paths that contain custom static files (such as style sheets) here, + # relative to this directory. They are copied after the builtin static files, + # so a file named "default.css" will overwrite the builtin "default.css". + html_css_files = [ + 'theme_overrides.css', + ] + + # Read the Docs dark mode override theme + if html_theme == 'sphinx_rtd_dark_mode': + try: + import sphinx_rtd_dark_mode + extensions.append('sphinx_rtd_dark_mode') + except ImportError: + html_theme == 'sphinx_rtd_theme' + + if html_theme == 'sphinx_rtd_theme': + # Add color-specific RTD normal mode + html_css_files.append('theme_rtd_colors.css') + + except ImportError: + html_theme = 'classic' + +if "DOCS_CSS" in os.environ: + css = os.environ["DOCS_CSS"].split(" ") + + for l in css: + html_css_files.append(l) + +if major <= 1 and minor < 8: + html_context = { + 'css_files': [], + } + + for l in html_css_files: + html_context['css_files'].append('_static/' + l) + +if html_theme == 'classic': + html_theme_options = { + 'rightsidebar': False, + 'stickysidebar': True, + 'collapsiblesidebar': True, + 'externalrefs': False, + + 'footerbgcolor': "white", + 'footertextcolor': "white", + 'sidebarbgcolor': "white", + 'sidebarbtncolor': "black", + 'sidebartextcolor': "black", + 'sidebarlinkcolor': "#686bff", + 'relbarbgcolor': "#133f52", + 'relbartextcolor': "white", + 'relbarlinkcolor': "white", + 'bgcolor': "white", + 'textcolor': "black", + 'headbgcolor': "#f2f2f2", + 'headtextcolor': "#20435c", + 'headlinkcolor': "#c60f0f", + 'linkcolor': "#355f7c", + 'visitedlinkcolor': "#355f7c", + 'codebgcolor': "#3f3f3f", + 'codetextcolor': "white", + + 'bodyfont': "serif", + 'headfont': "sans-serif", + } + +sys.stderr.write("Using %s theme\n" % html_theme) # Theme options are theme-specific and customize the look and feel of a theme # further. For a list of options available for each theme, see the @@ -246,15 +316,8 @@ except ImportError: # Add any paths that contain custom static files (such as style sheets) here, # relative to this directory. They are copied after the builtin static files, # so a file named "default.css" will overwrite the builtin "default.css". - html_static_path = ['sphinx-static'] -html_context = { - 'css_files': [ - '_static/theme_overrides.css', - ], -} - # Add any extra paths that contain custom files (such as robots.txt or # .htaccess) here, relative to this directory. These files are copied # directly to the root of the documentation. diff --git a/Documentation/cpu-freq/core.rst b/Documentation/cpu-freq/core.rst index 33cb90bd1d8f..4ceef8e7217c 100644 --- a/Documentation/cpu-freq/core.rst +++ b/Documentation/cpu-freq/core.rst @@ -73,12 +73,12 @@ CPUFREQ_POSTCHANGE. The third argument is a struct cpufreq_freqs with the following values: -===== =========================== -cpu number of the affected CPU +====== ====================================== +policy a pointer to the struct cpufreq_policy old old frequency new new frequency flags flags of the cpufreq driver -===== =========================== +====== ====================================== 3. CPUFreq Table Generation with Operating Performance Point (OPP) ================================================================== diff --git a/Documentation/dev-tools/index.rst b/Documentation/dev-tools/index.rst index 010a2af1e7d9..4621eac290f4 100644 --- a/Documentation/dev-tools/index.rst +++ b/Documentation/dev-tools/index.rst @@ -32,6 +32,7 @@ Documentation/dev-tools/testing-overview.rst kgdb kselftest kunit/index + ktap .. only:: subproject and html diff --git a/Documentation/dev-tools/kcsan.rst b/Documentation/dev-tools/kcsan.rst index 7db43c7c09b8..3ae866dcc924 100644 --- a/Documentation/dev-tools/kcsan.rst +++ b/Documentation/dev-tools/kcsan.rst @@ -204,17 +204,17 @@ Ultimately this allows to determine the possible executions of concurrent code, and if that code is free from data races. KCSAN is aware of *marked atomic operations* (``READ_ONCE``, ``WRITE_ONCE``, -``atomic_*``, etc.), but is oblivious of any ordering guarantees and simply -assumes that memory barriers are placed correctly. In other words, KCSAN -assumes that as long as a plain access is not observed to race with another -conflicting access, memory operations are correctly ordered. - -This means that KCSAN will not report *potential* data races due to missing -memory ordering. Developers should therefore carefully consider the required -memory ordering requirements that remain unchecked. If, however, missing -memory ordering (that is observable with a particular compiler and -architecture) leads to an observable data race (e.g. entering a critical -section erroneously), KCSAN would report the resulting data race. +``atomic_*``, etc.), and a subset of ordering guarantees implied by memory +barriers. With ``CONFIG_KCSAN_WEAK_MEMORY=y``, KCSAN models load or store +buffering, and can detect missing ``smp_mb()``, ``smp_wmb()``, ``smp_rmb()``, +``smp_store_release()``, and all ``atomic_*`` operations with equivalent +implied barriers. + +Note, KCSAN will not report all data races due to missing memory ordering, +specifically where a memory barrier would be required to prohibit subsequent +memory operation from reordering before the barrier. Developers should +therefore carefully consider the required memory ordering requirements that +remain unchecked. Race Detection Beyond Data Races -------------------------------- @@ -268,6 +268,56 @@ marked operations, if all accesses to a variable that is accessed concurrently are properly marked, KCSAN will never trigger a watchpoint and therefore never report the accesses. +Modeling Weak Memory +~~~~~~~~~~~~~~~~~~~~ + +KCSAN's approach to detecting data races due to missing memory barriers is +based on modeling access reordering (with ``CONFIG_KCSAN_WEAK_MEMORY=y``). +Each plain memory access for which a watchpoint is set up, is also selected for +simulated reordering within the scope of its function (at most 1 in-flight +access). + +Once an access has been selected for reordering, it is checked along every +other access until the end of the function scope. If an appropriate memory +barrier is encountered, the access will no longer be considered for simulated +reordering. + +When the result of a memory operation should be ordered by a barrier, KCSAN can +then detect data races where the conflict only occurs as a result of a missing +barrier. Consider the example:: + + int x, flag; + void T1(void) + { + x = 1; // data race! + WRITE_ONCE(flag, 1); // correct: smp_store_release(&flag, 1) + } + void T2(void) + { + while (!READ_ONCE(flag)); // correct: smp_load_acquire(&flag) + ... = x; // data race! + } + +When weak memory modeling is enabled, KCSAN can consider ``x`` in ``T1`` for +simulated reordering. After the write of ``flag``, ``x`` is again checked for +concurrent accesses: because ``T2`` is able to proceed after the write of +``flag``, a data race is detected. With the correct barriers in place, ``x`` +would not be considered for reordering after the proper release of ``flag``, +and no data race would be detected. + +Deliberate trade-offs in complexity but also practical limitations mean only a +subset of data races due to missing memory barriers can be detected. With +currently available compiler support, the implementation is limited to modeling +the effects of "buffering" (delaying accesses), since the runtime cannot +"prefetch" accesses. Also recall that watchpoints are only set up for plain +accesses, and the only access type for which KCSAN simulates reordering. This +means reordering of marked accesses is not modeled. + +A consequence of the above is that acquire operations do not require barrier +instrumentation (no prefetching). Furthermore, marked accesses introducing +address or control dependencies do not require special handling (the marked +access cannot be reordered, later dependent accesses cannot be prefetched). + Key Properties ~~~~~~~~~~~~~~ @@ -290,8 +340,8 @@ Key Properties 4. **Detects Racy Writes from Devices:** Due to checking data values upon setting up watchpoints, racy writes from devices can also be detected. -5. **Memory Ordering:** KCSAN is *not* explicitly aware of the LKMM's ordering - rules; this may result in missed data races (false negatives). +5. **Memory Ordering:** KCSAN is aware of only a subset of LKMM ordering rules; + this may result in missed data races (false negatives). 6. **Analysis Accuracy:** For observed executions, due to using a sampling strategy, the analysis is *unsound* (false negatives possible), but aims to diff --git a/Documentation/dev-tools/kgdb.rst b/Documentation/dev-tools/kgdb.rst index 43456244651a..f83ba2601e55 100644 --- a/Documentation/dev-tools/kgdb.rst +++ b/Documentation/dev-tools/kgdb.rst @@ -402,7 +402,7 @@ This is a quick example of how to use kdb. 2. Enter the kernel debugger manually or by waiting for an oops or fault. There are several ways you can enter the kernel debugger manually; all involve using the :kbd:`SysRq-G`, which means you must have - enabled ``CONFIG_MAGIC_SysRq=y`` in your kernel config. + enabled ``CONFIG_MAGIC_SYSRQ=y`` in your kernel config. - When logged in as root or with a super user session you can run:: @@ -461,7 +461,7 @@ This is a quick example of how to use kdb with a keyboard. 2. Enter the kernel debugger manually or by waiting for an oops or fault. There are several ways you can enter the kernel debugger manually; all involve using the :kbd:`SysRq-G`, which means you must have - enabled ``CONFIG_MAGIC_SysRq=y`` in your kernel config. + enabled ``CONFIG_MAGIC_SYSRQ=y`` in your kernel config. - When logged in as root or with a super user session you can run:: @@ -557,7 +557,7 @@ Connecting with gdb to a serial port Example (using a directly connected port):: % gdb ./vmlinux - (gdb) set remotebaud 115200 + (gdb) set serial baud 115200 (gdb) target remote /dev/ttyS0 diff --git a/Documentation/dev-tools/ktap.rst b/Documentation/dev-tools/ktap.rst new file mode 100644 index 000000000000..878530cb9c27 --- /dev/null +++ b/Documentation/dev-tools/ktap.rst @@ -0,0 +1,298 @@ +.. SPDX-License-Identifier: GPL-2.0 + +======================================== +The Kernel Test Anything Protocol (KTAP) +======================================== + +TAP, or the Test Anything Protocol is a format for specifying test results used +by a number of projects. It's website and specification are found at this `link +<https://testanything.org/>`_. The Linux Kernel largely uses TAP output for test +results. However, Kernel testing frameworks have special needs for test results +which don't align with the original TAP specification. Thus, a "Kernel TAP" +(KTAP) format is specified to extend and alter TAP to support these use-cases. +This specification describes the generally accepted format of KTAP as it is +currently used in the kernel. + +KTAP test results describe a series of tests (which may be nested: i.e., test +can have subtests), each of which can contain both diagnostic data -- e.g., log +lines -- and a final result. The test structure and results are +machine-readable, whereas the diagnostic data is unstructured and is there to +aid human debugging. + +KTAP output is built from four different types of lines: +- Version lines +- Plan lines +- Test case result lines +- Diagnostic lines + +In general, valid KTAP output should also form valid TAP output, but some +information, in particular nested test results, may be lost. Also note that +there is a stagnant draft specification for TAP14, KTAP diverges from this in +a couple of places (notably the "Subtest" header), which are described where +relevant later in this document. + +Version lines +------------- + +All KTAP-formatted results begin with a "version line" which specifies which +version of the (K)TAP standard the result is compliant with. + +For example: +- "KTAP version 1" +- "TAP version 13" +- "TAP version 14" + +Note that, in KTAP, subtests also begin with a version line, which denotes the +start of the nested test results. This differs from TAP14, which uses a +separate "Subtest" line. + +While, going forward, "KTAP version 1" should be used by compliant tests, it +is expected that most parsers and other tooling will accept the other versions +listed here for compatibility with existing tests and frameworks. + +Plan lines +---------- + +A test plan provides the number of tests (or subtests) in the KTAP output. + +Plan lines must follow the format of "1..N" where N is the number of tests or subtests. +Plan lines follow version lines to indicate the number of nested tests. + +While there are cases where the number of tests is not known in advance -- in +which case the test plan may be omitted -- it is strongly recommended one is +present where possible. + +Test case result lines +---------------------- + +Test case result lines indicate the final status of a test. +They are required and must have the format: + +.. code-block:: + + <result> <number> [<description>][ # [<directive>] [<diagnostic data>]] + +The result can be either "ok", which indicates the test case passed, +or "not ok", which indicates that the test case failed. + +<number> represents the number of the test being performed. The first test must +have the number 1 and the number then must increase by 1 for each additional +subtest within the same test at the same nesting level. + +The description is a description of the test, generally the name of +the test, and can be any string of words (can't include #). The +description is optional, but recommended. + +The directive and any diagnostic data is optional. If either are present, they +must follow a hash sign, "#". + +A directive is a keyword that indicates a different outcome for a test other +than passed and failed. The directive is optional, and consists of a single +keyword preceding the diagnostic data. In the event that a parser encounters +a directive it doesn't support, it should fall back to the "ok" / "not ok" +result. + +Currently accepted directives are: + +- "SKIP", which indicates a test was skipped (note the result of the test case + result line can be either "ok" or "not ok" if the SKIP directive is used) +- "TODO", which indicates that a test is not expected to pass at the moment, + e.g. because the feature it is testing is known to be broken. While this + directive is inherited from TAP, its use in the kernel is discouraged. +- "XFAIL", which indicates that a test is expected to fail. This is similar + to "TODO", above, and is used by some kselftest tests. +- “TIMEOUT”, which indicates a test has timed out (note the result of the test + case result line should be “not ok” if the TIMEOUT directive is used) +- “ERROR”, which indicates that the execution of a test has failed due to a + specific error that is included in the diagnostic data. (note the result of + the test case result line should be “not ok” if the ERROR directive is used) + +The diagnostic data is a plain-text field which contains any additional details +about why this result was produced. This is typically an error message for ERROR +or failed tests, or a description of missing dependencies for a SKIP result. + +The diagnostic data field is optional, and results which have neither a +directive nor any diagnostic data do not need to include the "#" field +separator. + +Example result lines include: + +.. code-block:: + + ok 1 test_case_name + +The test "test_case_name" passed. + +.. code-block:: + + not ok 1 test_case_name + +The test "test_case_name" failed. + +.. code-block:: + + ok 1 test # SKIP necessary dependency unavailable + +The test "test" was SKIPPED with the diagnostic message "necessary dependency +unavailable". + +.. code-block:: + + not ok 1 test # TIMEOUT 30 seconds + +The test "test" timed out, with diagnostic data "30 seconds". + +.. code-block:: + + ok 5 check return code # rcode=0 + +The test "check return code" passed, with additional diagnostic data “rcode=0” + + +Diagnostic lines +---------------- + +If tests wish to output any further information, they should do so using +"diagnostic lines". Diagnostic lines are optional, freeform text, and are +often used to describe what is being tested and any intermediate results in +more detail than the final result and diagnostic data line provides. + +Diagnostic lines are formatted as "# <diagnostic_description>", where the +description can be any string. Diagnostic lines can be anywhere in the test +output. As a rule, diagnostic lines regarding a test are directly before the +test result line for that test. + +Note that most tools will treat unknown lines (see below) as diagnostic lines, +even if they do not start with a "#": this is to capture any other useful +kernel output which may help debug the test. It is nevertheless recommended +that tests always prefix any diagnostic output they have with a "#" character. + +Unknown lines +------------- + +There may be lines within KTAP output that do not follow the format of one of +the four formats for lines described above. This is allowed, however, they will +not influence the status of the tests. + +Nested tests +------------ + +In KTAP, tests can be nested. This is done by having a test include within its +output an entire set of KTAP-formatted results. This can be used to categorize +and group related tests, or to split out different results from the same test. + +The "parent" test's result should consist of all of its subtests' results, +starting with another KTAP version line and test plan, and end with the overall +result. If one of the subtests fail, for example, the parent test should also +fail. + +Additionally, all result lines in a subtest should be indented. One level of +indentation is two spaces: " ". The indentation should begin at the version +line and should end before the parent test's result line. + +An example of a test with two nested subtests: + +.. code-block:: + + KTAP version 1 + 1..1 + KTAP version 1 + 1..2 + ok 1 test_1 + not ok 2 test_2 + # example failed + not ok 1 example + +An example format with multiple levels of nested testing: + +.. code-block:: + + KTAP version 1 + 1..2 + KTAP version 1 + 1..2 + KTAP version 1 + 1..2 + not ok 1 test_1 + ok 2 test_2 + not ok 1 test_3 + ok 2 test_4 # SKIP + not ok 1 example_test_1 + ok 2 example_test_2 + + +Major differences between TAP and KTAP +-------------------------------------- + +Note the major differences between the TAP and KTAP specification: +- yaml and json are not recommended in diagnostic messages +- TODO directive not recognized +- KTAP allows for an arbitrary number of tests to be nested + +The TAP14 specification does permit nested tests, but instead of using another +nested version line, uses a line of the form +"Subtest: <name>" where <name> is the name of the parent test. + +Example KTAP output +-------------------- +.. code-block:: + + KTAP version 1 + 1..1 + KTAP version 1 + 1..3 + KTAP version 1 + 1..1 + # test_1: initializing test_1 + ok 1 test_1 + ok 1 example_test_1 + KTAP version 1 + 1..2 + ok 1 test_1 # SKIP test_1 skipped + ok 2 test_2 + ok 2 example_test_2 + KTAP version 1 + 1..3 + ok 1 test_1 + # test_2: FAIL + not ok 2 test_2 + ok 3 test_3 # SKIP test_3 skipped + not ok 3 example_test_3 + not ok 1 main_test + +This output defines the following hierarchy: + +A single test called "main_test", which fails, and has three subtests: +- "example_test_1", which passes, and has one subtest: + + - "test_1", which passes, and outputs the diagnostic message "test_1: initializing test_1" + +- "example_test_2", which passes, and has two subtests: + + - "test_1", which is skipped, with the explanation "test_1 skipped" + - "test_2", which passes + +- "example_test_3", which fails, and has three subtests + + - "test_1", which passes + - "test_2", which outputs the diagnostic line "test_2: FAIL", and fails. + - "test_3", which is skipped with the explanation "test_3 skipped" + +Note that the individual subtests with the same names do not conflict, as they +are found in different parent tests. This output also exhibits some sensible +rules for "bubbling up" test results: a test fails if any of its subtests fail. +Skipped tests do not affect the result of the parent test (though it often +makes sense for a test to be marked skipped if _all_ of its subtests have been +skipped). + +See also: +--------- + +- The TAP specification: + https://testanything.org/tap-version-13-specification.html +- The (stagnant) TAP version 14 specification: + https://github.com/TestAnything/Specification/blob/tap-14-specification/specification.md +- The kselftest documentation: + Documentation/dev-tools/kselftest.rst +- The KUnit documentation: + Documentation/dev-tools/kunit/index.rst diff --git a/Documentation/dev-tools/kunit/api/index.rst b/Documentation/dev-tools/kunit/api/index.rst index b33ad72bcf0b..3006cadcf44a 100644 --- a/Documentation/dev-tools/kunit/api/index.rst +++ b/Documentation/dev-tools/kunit/api/index.rst @@ -12,5 +12,4 @@ following sections: Documentation/dev-tools/kunit/api/test.rst - - documents all of the standard testing API excluding mocking - or mocking related features. + - documents all of the standard testing API diff --git a/Documentation/dev-tools/kunit/api/test.rst b/Documentation/dev-tools/kunit/api/test.rst index aaa97f17e5b3..c5eca423e8b6 100644 --- a/Documentation/dev-tools/kunit/api/test.rst +++ b/Documentation/dev-tools/kunit/api/test.rst @@ -4,8 +4,7 @@ Test API ======== -This file documents all of the standard testing API excluding mocking or mocking -related features. +This file documents all of the standard testing API. .. kernel-doc:: include/kunit/test.h :internal: diff --git a/Documentation/dev-tools/kunit/architecture.rst b/Documentation/dev-tools/kunit/architecture.rst new file mode 100644 index 000000000000..aa2cea821e25 --- /dev/null +++ b/Documentation/dev-tools/kunit/architecture.rst @@ -0,0 +1,204 @@ +.. SPDX-License-Identifier: GPL-2.0 + +================== +KUnit Architecture +================== + +The KUnit architecture can be divided into two parts: + +- Kernel testing library +- kunit_tool (Command line test harness) + +In-Kernel Testing Framework +=========================== + +The kernel testing library supports KUnit tests written in C using +KUnit. KUnit tests are kernel code. KUnit does several things: + +- Organizes tests +- Reports test results +- Provides test utilities + +Test Cases +---------- + +The fundamental unit in KUnit is the test case. The KUnit test cases are +grouped into KUnit suites. A KUnit test case is a function with type +signature ``void (*)(struct kunit *test)``. +These test case functions are wrapped in a struct called +``struct kunit_case``. For code, see: + +.. kernel-doc:: include/kunit/test.h + :identifiers: kunit_case + +.. note: + ``generate_params`` is optional for non-parameterized tests. + +Each KUnit test case gets a ``struct kunit`` context +object passed to it that tracks a running test. The KUnit assertion +macros and other KUnit utilities use the ``struct kunit`` context +object. As an exception, there are two fields: + +- ``->priv``: The setup functions can use it to store arbitrary test + user data. + +- ``->param_value``: It contains the parameter value which can be + retrieved in the parameterized tests. + +Test Suites +----------- + +A KUnit suite includes a collection of test cases. The KUnit suites +are represented by the ``struct kunit_suite``. For example: + +.. code-block:: c + + static struct kunit_case example_test_cases[] = { + KUNIT_CASE(example_test_foo), + KUNIT_CASE(example_test_bar), + KUNIT_CASE(example_test_baz), + {} + }; + + static struct kunit_suite example_test_suite = { + .name = "example", + .init = example_test_init, + .exit = example_test_exit, + .test_cases = example_test_cases, + }; + kunit_test_suite(example_test_suite); + +In the above example, the test suite ``example_test_suite``, runs the +test cases ``example_test_foo``, ``example_test_bar``, and +``example_test_baz``. Before running the test, the ``example_test_init`` +is called and after running the test, ``example_test_exit`` is called. +The ``kunit_test_suite(example_test_suite)`` registers the test suite +with the KUnit test framework. + +Executor +-------- + +The KUnit executor can list and run built-in KUnit tests on boot. +The Test suites are stored in a linker section +called ``.kunit_test_suites``. For code, see: +https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/tree/include/asm-generic/vmlinux.lds.h?h=v5.15#n945. +The linker section consists of an array of pointers to +``struct kunit_suite``, and is populated by the ``kunit_test_suites()`` +macro. To run all tests compiled into the kernel, the KUnit executor +iterates over the linker section array. + +.. kernel-figure:: kunit_suitememorydiagram.svg + :alt: KUnit Suite Memory + + KUnit Suite Memory Diagram + +On the kernel boot, the KUnit executor uses the start and end addresses +of this section to iterate over and run all tests. For code, see: +https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/tree/lib/kunit/executor.c + +When built as a module, the ``kunit_test_suites()`` macro defines a +``module_init()`` function, which runs all the tests in the compilation +unit instead of utilizing the executor. + +In KUnit tests, some error classes do not affect other tests +or parts of the kernel, each KUnit case executes in a separate thread +context. For code, see: +https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/tree/lib/kunit/try-catch.c?h=v5.15#n58 + +Assertion Macros +---------------- + +KUnit tests verify state using expectations/assertions. +All expectations/assertions are formatted as: +``KUNIT_{EXPECT|ASSERT}_<op>[_MSG](kunit, property[, message])`` + +- ``{EXPECT|ASSERT}`` determines whether the check is an assertion or an + expectation. + + - For an expectation, if the check fails, marks the test as failed + and logs the failure. + + - An assertion, on failure, causes the test case to terminate + immediately. + + - Assertions call function: + ``void __noreturn kunit_abort(struct kunit *)``. + + - ``kunit_abort`` calls function: + ``void __noreturn kunit_try_catch_throw(struct kunit_try_catch *try_catch)``. + + - ``kunit_try_catch_throw`` calls function: + ``void complete_and_exit(struct completion *, long) __noreturn;`` + and terminates the special thread context. + +- ``<op>`` denotes a check with options: ``TRUE`` (supplied property + has the boolean value “true”), ``EQ`` (two supplied properties are + equal), ``NOT_ERR_OR_NULL`` (supplied pointer is not null and does not + contain an “err” value). + +- ``[_MSG]`` prints a custom message on failure. + +Test Result Reporting +--------------------- +KUnit prints test results in KTAP format. KTAP is based on TAP14, see: +https://github.com/isaacs/testanything.github.io/blob/tap14/tap-version-14-specification.md. +KTAP (yet to be standardized format) works with KUnit and Kselftest. +The KUnit executor prints KTAP results to dmesg, and debugfs +(if configured). + +Parameterized Tests +------------------- + +Each KUnit parameterized test is associated with a collection of +parameters. The test is invoked multiple times, once for each parameter +value and the parameter is stored in the ``param_value`` field. +The test case includes a ``KUNIT_CASE_PARAM()`` macro that accepts a +generator function. +The generator function is passed the previous parameter and returns the next +parameter. It also provides a macro to generate common-case generators based on +arrays. + +For code, see: + +.. kernel-doc:: include/kunit/test.h + :identifiers: KUNIT_ARRAY_PARAM + + +kunit_tool (Command Line Test Harness) +====================================== + +kunit_tool is a Python script ``(tools/testing/kunit/kunit.py)`` +that can be used to configure, build, exec, parse and run (runs other +commands in order) test results. You can either run KUnit tests using +kunit_tool or can include KUnit in kernel and parse manually. + +- ``configure`` command generates the kernel ``.config`` from a + ``.kunitconfig`` file (and any architecture-specific options). + For some architectures, additional config options are specified in the + ``qemu_config`` Python script + (For example: ``tools/testing/kunit/qemu_configs/powerpc.py``). + It parses both the existing ``.config`` and the ``.kunitconfig`` files + and ensures that ``.config`` is a superset of ``.kunitconfig``. + If this is not the case, it will combine the two and run + ``make olddefconfig`` to regenerate the ``.config`` file. It then + verifies that ``.config`` is now a superset. This checks if all + Kconfig dependencies are correctly specified in ``.kunitconfig``. + ``kunit_config.py`` includes the parsing Kconfigs code. The code which + runs ``make olddefconfig`` is a part of ``kunit_kernel.py``. You can + invoke this command via: ``./tools/testing/kunit/kunit.py config`` and + generate a ``.config`` file. +- ``build`` runs ``make`` on the kernel tree with required options + (depends on the architecture and some options, for example: build_dir) + and reports any errors. + To build a KUnit kernel from the current ``.config``, you can use the + ``build`` argument: ``./tools/testing/kunit/kunit.py build``. +- ``exec`` command executes kernel results either directly (using + User-mode Linux configuration), or via an emulator such + as QEMU. It reads results from the log via standard + output (stdout), and passes them to ``parse`` to be parsed. + If you already have built a kernel with built-in KUnit tests, + you can run the kernel and display the test results with the ``exec`` + argument: ``./tools/testing/kunit/kunit.py exec``. +- ``parse`` extracts the KTAP output from a kernel log, parses + the test results, and prints a summary. For failed tests, any + diagnostic output will be included. diff --git a/Documentation/dev-tools/kunit/faq.rst b/Documentation/dev-tools/kunit/faq.rst index 5c6555d020f3..172e239791a8 100644 --- a/Documentation/dev-tools/kunit/faq.rst +++ b/Documentation/dev-tools/kunit/faq.rst @@ -4,56 +4,55 @@ Frequently Asked Questions ========================== -How is this different from Autotest, kselftest, etc? -==================================================== +How is this different from Autotest, kselftest, and so on? +========================================================== KUnit is a unit testing framework. Autotest, kselftest (and some others) are not. A `unit test <https://martinfowler.com/bliki/UnitTest.html>`_ is supposed to -test a single unit of code in isolation, hence the name. A unit test should be -the finest granularity of testing and as such should allow all possible code -paths to be tested in the code under test; this is only possible if the code -under test is very small and does not have any external dependencies outside of +test a single unit of code in isolation and hence the name *unit test*. A unit +test should be the finest granularity of testing and should allow all possible +code paths to be tested in the code under test. This is only possible if the +code under test is small and does not have any external dependencies outside of the test's control like hardware. There are no testing frameworks currently available for the kernel that do not -require installing the kernel on a test machine or in a VM and all require -tests to be written in userspace and run on the kernel under test; this is true -for Autotest, kselftest, and some others, disqualifying any of them from being -considered unit testing frameworks. +require installing the kernel on a test machine or in a virtual machine. All +testing frameworks require tests to be written in userspace and run on the +kernel under test. This is true for Autotest, kselftest, and some others, +disqualifying any of them from being considered unit testing frameworks. Does KUnit support running on architectures other than UML? =========================================================== -Yes, well, mostly. +Yes, mostly. -For the most part, the KUnit core framework (what you use to write the tests) -can compile to any architecture; it compiles like just another part of the +For the most part, the KUnit core framework (what we use to write the tests) +can compile to any architecture. It compiles like just another part of the kernel and runs when the kernel boots, or when built as a module, when the -module is loaded. However, there is some infrastructure, -like the KUnit Wrapper (``tools/testing/kunit/kunit.py``) that does not support -other architectures. +module is loaded. However, there is infrastructure, like the KUnit Wrapper +(``tools/testing/kunit/kunit.py``) that does not support other architectures. -In short, this means that, yes, you can run KUnit on other architectures, but -it might require more work than using KUnit on UML. +In short, yes, you can run KUnit on other architectures, but it might require +more work than using KUnit on UML. For more information, see :ref:`kunit-on-non-uml`. -What is the difference between a unit test and these other kinds of tests? -========================================================================== +What is the difference between a unit test and other kinds of tests? +==================================================================== Most existing tests for the Linux kernel would be categorized as an integration test, or an end-to-end test. -- A unit test is supposed to test a single unit of code in isolation, hence the - name. A unit test should be the finest granularity of testing and as such - should allow all possible code paths to be tested in the code under test; this - is only possible if the code under test is very small and does not have any - external dependencies outside of the test's control like hardware. +- A unit test is supposed to test a single unit of code in isolation. A unit + test should be the finest granularity of testing and, as such, allows all + possible code paths to be tested in the code under test. This is only possible + if the code under test is small and does not have any external dependencies + outside of the test's control like hardware. - An integration test tests the interaction between a minimal set of components, usually just two or three. For example, someone might write an integration test to test the interaction between a driver and a piece of hardware, or to test the interaction between the userspace libraries the kernel provides and - the kernel itself; however, one of these tests would probably not test the + the kernel itself. However, one of these tests would probably not test the entire kernel along with hardware interactions and interactions with the userspace. - An end-to-end test usually tests the entire system from the perspective of the @@ -62,26 +61,26 @@ test, or an end-to-end test. hardware with a production userspace and then trying to exercise some behavior that depends on interactions between the hardware, the kernel, and userspace. -KUnit isn't working, what should I do? -====================================== +KUnit is not working, what should I do? +======================================= Unfortunately, there are a number of things which can break, but here are some things to try. -1. Try running ``./tools/testing/kunit/kunit.py run`` with the ``--raw_output`` +1. Run ``./tools/testing/kunit/kunit.py run`` with the ``--raw_output`` parameter. This might show details or error messages hidden by the kunit_tool parser. 2. Instead of running ``kunit.py run``, try running ``kunit.py config``, ``kunit.py build``, and ``kunit.py exec`` independently. This can help track down where an issue is occurring. (If you think the parser is at fault, you - can run it manually against stdin or a file with ``kunit.py parse``.) -3. Running the UML kernel directly can often reveal issues or error messages - kunit_tool ignores. This should be as simple as running ``./vmlinux`` after - building the UML kernel (e.g., by using ``kunit.py build``). Note that UML - has some unusual requirements (such as the host having a tmpfs filesystem - mounted), and has had issues in the past when built statically and the host - has KASLR enabled. (On older host kernels, you may need to run ``setarch - `uname -m` -R ./vmlinux`` to disable KASLR.) + can run it manually against ``stdin`` or a file with ``kunit.py parse``.) +3. Running the UML kernel directly can often reveal issues or error messages, + ``kunit_tool`` ignores. This should be as simple as running ``./vmlinux`` + after building the UML kernel (for example, by using ``kunit.py build``). + Note that UML has some unusual requirements (such as the host having a tmpfs + filesystem mounted), and has had issues in the past when built statically and + the host has KASLR enabled. (On older host kernels, you may need to run + ``setarch `uname -m` -R ./vmlinux`` to disable KASLR.) 4. Make sure the kernel .config has ``CONFIG_KUNIT=y`` and at least one test (e.g. ``CONFIG_KUNIT_EXAMPLE_TEST=y``). kunit_tool will keep its .config around, so you can see what config was used after running ``kunit.py run``. diff --git a/Documentation/dev-tools/kunit/index.rst b/Documentation/dev-tools/kunit/index.rst index cacb35ec658d..595205348d2d 100644 --- a/Documentation/dev-tools/kunit/index.rst +++ b/Documentation/dev-tools/kunit/index.rst @@ -1,13 +1,17 @@ .. SPDX-License-Identifier: GPL-2.0 -========================================= -KUnit - Unit Testing for the Linux Kernel -========================================= +================================= +KUnit - Linux Kernel Unit Testing +================================= .. toctree:: :maxdepth: 2 + :caption: Contents: start + architecture + run_wrapper + run_manual usage kunit-tool api/index @@ -16,82 +20,94 @@ KUnit - Unit Testing for the Linux Kernel tips running_tips -What is KUnit? -============== - -KUnit is a lightweight unit testing and mocking framework for the Linux kernel. - -KUnit is heavily inspired by JUnit, Python's unittest.mock, and -Googletest/Googlemock for C++. KUnit provides facilities for defining unit test -cases, grouping related test cases into test suites, providing common -infrastructure for running tests, and much more. - -KUnit consists of a kernel component, which provides a set of macros for easily -writing unit tests. Tests written against KUnit will run on kernel boot if -built-in, or when loaded if built as a module. These tests write out results to -the kernel log in `TAP <https://testanything.org/>`_ format. - -To make running these tests (and reading the results) easier, KUnit offers -:doc:`kunit_tool <kunit-tool>`, which builds a `User Mode Linux -<http://user-mode-linux.sourceforge.net>`_ kernel, runs it, and parses the test -results. This provides a quick way of running KUnit tests during development, -without requiring a virtual machine or separate hardware. - -Get started now: Documentation/dev-tools/kunit/start.rst - -Why KUnit? -========== - -A unit test is supposed to test a single unit of code in isolation, hence the -name. A unit test should be the finest granularity of testing and as such should -allow all possible code paths to be tested in the code under test; this is only -possible if the code under test is very small and does not have any external -dependencies outside of the test's control like hardware. - -KUnit provides a common framework for unit tests within the kernel. - -KUnit tests can be run on most architectures, and most tests are architecture -independent. All built-in KUnit tests run on kernel startup. Alternatively, -KUnit and KUnit tests can be built as modules and tests will run when the test -module is loaded. - -.. note:: - - KUnit can also run tests without needing a virtual machine or actual - hardware under User Mode Linux. User Mode Linux is a Linux architecture, - like ARM or x86, which compiles the kernel as a Linux executable. KUnit - can be used with UML either by building with ``ARCH=um`` (like any other - architecture), or by using :doc:`kunit_tool <kunit-tool>`. - -KUnit is fast. Excluding build time, from invocation to completion KUnit can run -several dozen tests in only 10 to 20 seconds; this might not sound like a big -deal to some people, but having such fast and easy to run tests fundamentally -changes the way you go about testing and even writing code in the first place. -Linus himself said in his `git talk at Google -<https://gist.github.com/lorn/1272686/revisions#diff-53c65572127855f1b003db4064a94573R874>`_: - - "... a lot of people seem to think that performance is about doing the - same thing, just doing it faster, and that is not true. That is not what - performance is all about. If you can do something really fast, really - well, people will start using it differently." - -In this context Linus was talking about branching and merging, -but this point also applies to testing. If your tests are slow, unreliable, are -difficult to write, and require a special setup or special hardware to run, -then you wait a lot longer to write tests, and you wait a lot longer to run -tests; this means that tests are likely to break, unlikely to test a lot of -things, and are unlikely to be rerun once they pass. If your tests are really -fast, you run them all the time, every time you make a change, and every time -someone sends you some code. Why trust that someone ran all their tests -correctly on every change when you can just run them yourself in less time than -it takes to read their test log? +This section details the kernel unit testing framework. + +Introduction +============ + +KUnit (Kernel unit testing framework) provides a common framework for +unit tests within the Linux kernel. Using KUnit, you can define groups +of test cases called test suites. The tests either run on kernel boot +if built-in, or load as a module. KUnit automatically flags and reports +failed test cases in the kernel log. The test results appear in `TAP +(Test Anything Protocol) format <https://testanything.org/>`_. It is inspired by +JUnit, Python’s unittest.mock, and GoogleTest/GoogleMock (C++ unit testing +framework). + +KUnit tests are part of the kernel, written in the C (programming) +language, and test parts of the Kernel implementation (example: a C +language function). Excluding build time, from invocation to +completion, KUnit can run around 100 tests in less than 10 seconds. +KUnit can test any kernel component, for example: file system, system +calls, memory management, device drivers and so on. + +KUnit follows the white-box testing approach. The test has access to +internal system functionality. KUnit runs in kernel space and is not +restricted to things exposed to user-space. + +In addition, KUnit has kunit_tool, a script (``tools/testing/kunit/kunit.py``) +that configures the Linux kernel, runs KUnit tests under QEMU or UML (`User Mode +Linux <http://user-mode-linux.sourceforge.net/>`_), parses the test results and +displays them in a user friendly manner. + +Features +-------- + +- Provides a framework for writing unit tests. +- Runs tests on any kernel architecture. +- Runs a test in milliseconds. + +Prerequisites +------------- + +- Any Linux kernel compatible hardware. +- For Kernel under test, Linux kernel version 5.5 or greater. + +Unit Testing +============ + +A unit test tests a single unit of code in isolation. A unit test is the finest +granularity of testing and allows all possible code paths to be tested in the +code under test. This is possible if the code under test is small and does not +have any external dependencies outside of the test's control like hardware. + + +Write Unit Tests +---------------- + +To write good unit tests, there is a simple but powerful pattern: +Arrange-Act-Assert. This is a great way to structure test cases and +defines an order of operations. + +- Arrange inputs and targets: At the start of the test, arrange the data + that allows a function to work. Example: initialize a statement or + object. +- Act on the target behavior: Call your function/code under test. +- Assert expected outcome: Verify that the result (or resulting state) is as + expected. + +Unit Testing Advantages +----------------------- + +- Increases testing speed and development in the long run. +- Detects bugs at initial stage and therefore decreases bug fix cost + compared to acceptance testing. +- Improves code quality. +- Encourages writing testable code. How do I use it? ================ -* Documentation/dev-tools/kunit/start.rst - for new users of KUnit -* Documentation/dev-tools/kunit/tips.rst - for short examples of best practices -* Documentation/dev-tools/kunit/usage.rst - for a more detailed explanation of KUnit features -* Documentation/dev-tools/kunit/api/index.rst - for the list of KUnit APIs used for testing -* Documentation/dev-tools/kunit/kunit-tool.rst - for more information on the kunit_tool helper script -* Documentation/dev-tools/kunit/faq.rst - for answers to some common questions about KUnit +* Documentation/dev-tools/kunit/start.rst - for KUnit new users. +* Documentation/dev-tools/kunit/architecture.rst - KUnit architecture. +* Documentation/dev-tools/kunit/run_wrapper.rst - run kunit_tool. +* Documentation/dev-tools/kunit/run_manual.rst - run tests without kunit_tool. +* Documentation/dev-tools/kunit/usage.rst - write tests. +* Documentation/dev-tools/kunit/tips.rst - best practices with + examples. +* Documentation/dev-tools/kunit/api/index.rst - KUnit APIs + used for testing. +* Documentation/dev-tools/kunit/kunit-tool.rst - kunit_tool helper + script. +* Documentation/dev-tools/kunit/faq.rst - KUnit common questions and + answers. diff --git a/Documentation/dev-tools/kunit/kunit_suitememorydiagram.svg b/Documentation/dev-tools/kunit/kunit_suitememorydiagram.svg new file mode 100644 index 000000000000..cf8fddc27500 --- /dev/null +++ b/Documentation/dev-tools/kunit/kunit_suitememorydiagram.svg @@ -0,0 +1,81 @@ +<?xml version="1.0" encoding="UTF-8"?> +<svg width="796.93" height="555.73" version="1.1" viewBox="0 0 796.93 555.73" xmlns="http://www.w3.org/2000/svg"> + <g transform="translate(-13.724 -17.943)"> + <g fill="#dad4d4" fill-opacity=".91765" stroke="#1a1a1a"> + <rect x="323.56" y="18.443" width="115.75" height="41.331"/> + <rect x="323.56" y="463.09" width="115.75" height="41.331"/> + <rect x="323.56" y="531.84" width="115.75" height="41.331"/> + <rect x="323.56" y="88.931" width="115.75" height="74.231"/> + </g> + <g> + <rect x="323.56" y="421.76" width="115.75" height="41.331" fill="#b9dbc6" stroke="#1a1a1a"/> + <text x="328.00888" y="446.61826" fill="#000000" font-family="sans-serif" font-size="16px" style="line-height:1.25" xml:space="preserve"><tspan x="328.00888" y="446.61826" font-family="monospace" font-size="16px">kunit_suite</tspan></text> + </g> + <g transform="translate(0 -258.6)"> + <rect x="323.56" y="421.76" width="115.75" height="41.331" fill="#b9dbc6" stroke="#1a1a1a"/> + <text x="328.00888" y="446.61826" fill="#000000" font-family="sans-serif" font-size="16px" style="line-height:1.25" xml:space="preserve"><tspan x="328.00888" y="446.61826" font-family="monospace" font-size="16px">kunit_suite</tspan></text> + </g> + <g transform="translate(0 -217.27)"> + <rect x="323.56" y="421.76" width="115.75" height="41.331" fill="#b9dbc6" stroke="#1a1a1a"/> + <text x="328.00888" y="446.61826" fill="#000000" font-family="sans-serif" font-size="16px" style="line-height:1.25" xml:space="preserve"><tspan x="328.00888" y="446.61826" font-family="monospace" font-size="16px">kunit_suite</tspan></text> + </g> + <g transform="translate(0 -175.94)"> + <rect x="323.56" y="421.76" width="115.75" height="41.331" fill="#b9dbc6" stroke="#1a1a1a"/> + <text x="328.00888" y="446.61826" fill="#000000" font-family="sans-serif" font-size="16px" style="line-height:1.25" xml:space="preserve"><tspan x="328.00888" y="446.61826" font-family="monospace" font-size="16px">kunit_suite</tspan></text> + </g> + <g transform="translate(0 -134.61)"> + <rect x="323.56" y="421.76" width="115.75" height="41.331" fill="#b9dbc6" stroke="#1a1a1a"/> + <text x="328.00888" y="446.61826" fill="#000000" font-family="sans-serif" font-size="16px" style="line-height:1.25" xml:space="preserve"><tspan x="328.00888" y="446.61826" font-family="monospace" font-size="16px">kunit_suite</tspan></text> + </g> + <g transform="translate(0 -41.331)"> + <rect x="323.56" y="421.76" width="115.75" height="41.331" fill="#b9dbc6" stroke="#1a1a1a"/> + <text x="328.00888" y="446.61826" fill="#000000" font-family="sans-serif" font-size="16px" style="line-height:1.25" xml:space="preserve"><tspan x="328.00888" y="446.61826" font-family="monospace" font-size="16px">kunit_suite</tspan></text> + </g> + <g transform="translate(3.4459e-5 -.71088)"> + <rect x="502.19" y="143.16" width="201.13" height="41.331" fill="#dad4d4" fill-opacity=".91765" stroke="#1a1a1a"/> + <text x="512.02319" y="168.02026" font-family="sans-serif" font-size="16px" style="line-height:1.25" xml:space="preserve"><tspan x="512.02319" y="168.02026" font-family="monospace">_kunit_suites_start</tspan></text> + </g> + <g transform="translate(3.0518e-5 -3.1753)"> + <rect x="502.19" y="445.69" width="201.13" height="41.331" fill="#dad4d4" fill-opacity=".91765" stroke="#1a1a1a"/> + <text x="521.61694" y="470.54846" font-family="sans-serif" font-size="16px" style="line-height:1.25" xml:space="preserve"><tspan x="521.61694" y="470.54846" font-family="monospace">_kunit_suites_end</tspan></text> + </g> + <rect x="14.224" y="277.78" width="134.47" height="41.331" fill="#dad4d4" fill-opacity=".91765" stroke="#1a1a1a"/> + <text x="32.062176" y="304.41287" font-family="sans-serif" font-size="16px" style="line-height:1.25" xml:space="preserve"><tspan x="32.062176" y="304.41287" font-family="monospace">.init.data</tspan></text> + <g transform="translate(217.98 145.12)" stroke="#1a1a1a"> + <circle cx="149.97" cy="373.01" r="3.4012"/> + <circle cx="163.46" cy="373.01" r="3.4012"/> + <circle cx="176.95" cy="373.01" r="3.4012"/> + </g> + <g transform="translate(217.98 -298.66)" stroke="#1a1a1a"> + <circle cx="149.97" cy="373.01" r="3.4012"/> + <circle cx="163.46" cy="373.01" r="3.4012"/> + <circle cx="176.95" cy="373.01" r="3.4012"/> + </g> + <g stroke="#1a1a1a"> + <rect x="323.56" y="328.49" width="115.75" height="51.549" fill="#b9dbc6"/> + <g transform="translate(217.98 -18.75)"> + <circle cx="149.97" cy="373.01" r="3.4012"/> + <circle cx="163.46" cy="373.01" r="3.4012"/> + <circle cx="176.95" cy="373.01" r="3.4012"/> + </g> + </g> + <g transform="scale(1.0933 .9147)" stroke-width="32.937" aria-label="{"> + <path d="m275.49 545.57c-35.836-8.432-47.43-24.769-47.957-64.821v-88.536c-0.527-44.795-10.54-57.97-49.538-67.456 38.998-10.013 49.011-23.715 49.538-67.983v-88.536c0.527-40.052 12.121-56.389 47.957-64.821v-5.797c-65.348 0-85.901 17.391-86.955 73.253v93.806c-0.527 36.89-10.013 50.065-44.795 59.551 34.782 10.013 44.268 23.188 44.795 60.078v93.279c1.581 56.389 21.607 73.78 86.955 73.78z"/> + </g> + <g transform="scale(1.1071 .90325)" stroke-width="14.44" aria-label="{"> + <path d="m461.46 443.55c-15.711-3.6967-20.794-10.859-21.025-28.418v-38.815c-0.23104-19.639-4.6209-25.415-21.718-29.574 17.097-4.3898 21.487-10.397 21.718-29.805v-38.815c0.23105-17.559 5.314-24.722 21.025-28.418v-2.5415c-28.649 0-37.66 7.6244-38.122 32.115v41.126c-0.23105 16.173-4.3898 21.949-19.639 26.108 15.249 4.3898 19.408 10.166 19.639 26.339v40.895c0.69313 24.722 9.4728 32.346 38.122 32.346z"/> + </g> + <path d="m449.55 161.84v2.5h49.504v-2.5z" color="#000000" style="-inkscape-stroke:none"/> + <g fill-rule="evenodd"> + <path d="m443.78 163.09 8.65-5v10z" color="#000000" stroke-width="1pt" style="-inkscape-stroke:none"/> + <path d="m453.1 156.94-10.648 6.1543 0.99804 0.57812 9.6504 5.5781zm-1.334 2.3125v7.6856l-6.6504-3.8438z" color="#000000" style="-inkscape-stroke:none"/> + </g> + <path d="m449.55 461.91v2.5h49.504v-2.5z" color="#000000" style="-inkscape-stroke:none"/> + <g fill-rule="evenodd"> + <path d="m443.78 463.16 8.65-5v10z" color="#000000" stroke-width="1pt" style="-inkscape-stroke:none"/> + <path d="m453.1 457-10.648 6.1562 0.99804 0.57617 9.6504 5.5781zm-1.334 2.3125v7.6856l-6.6504-3.8438z" color="#000000" style="-inkscape-stroke:none"/> + </g> + <rect x="515.64" y="223.9" width="294.52" height="178.49" fill="#dad4d4" fill-opacity=".91765" stroke="#1a1a1a"/> + <text x="523.33319" y="262.52542" font-family="monospace" font-size="14.667px" style="line-height:1.25" xml:space="preserve"><tspan x="523.33319" y="262.52542"><tspan fill="#008000" font-family="monospace" font-size="14.667px" font-weight="bold">struct</tspan> kunit_suite {</tspan><tspan x="523.33319" y="280.8588"><tspan fill="#008000" font-family="monospace" font-size="14.667px" font-weight="bold"> const char</tspan> name[<tspan fill="#ff00ff" font-size="14.667px">256</tspan>];</tspan><tspan x="523.33319" y="299.19217"> <tspan fill="#008000" font-family="monospace" font-size="14.667px" font-weight="bold">int</tspan> (*init)(<tspan fill="#008000" font-family="monospace" font-size="14.667px" font-weight="bold">struct</tspan> kunit *);</tspan><tspan x="523.33319" y="317.52554"> <tspan fill="#008000" font-family="monospace" font-size="14.667px" font-weight="bold">void</tspan> (*exit)(<tspan fill="#008000" font-family="monospace" font-size="14.667px" font-weight="bold">struct</tspan> kunit *);</tspan><tspan x="523.33319" y="335.85892"> <tspan fill="#008000" font-family="monospace" font-size="14.667px" font-weight="bold">struct</tspan> kunit_case *test_cases;</tspan><tspan x="523.33319" y="354.19229"> ...</tspan><tspan x="523.33319" y="372.52567">};</tspan></text> + </g> +</svg> diff --git a/Documentation/dev-tools/kunit/run_manual.rst b/Documentation/dev-tools/kunit/run_manual.rst new file mode 100644 index 000000000000..e7b46421f247 --- /dev/null +++ b/Documentation/dev-tools/kunit/run_manual.rst @@ -0,0 +1,57 @@ +.. SPDX-License-Identifier: GPL-2.0 + +============================ +Run Tests without kunit_tool +============================ + +If we do not want to use kunit_tool (For example: we want to integrate +with other systems, or run tests on real hardware), we can +include KUnit in any kernel, read out results, and parse manually. + +.. note:: KUnit is not designed for use in a production system. It is + possible that tests may reduce the stability or security of + the system. + +Configure the Kernel +==================== + +KUnit tests can run without kunit_tool. This can be useful, if: + +- We have an existing kernel configuration to test. +- Need to run on real hardware (or using an emulator/VM kunit_tool + does not support). +- Wish to integrate with some existing testing systems. + +KUnit is configured with the ``CONFIG_KUNIT`` option, and individual +tests can also be built by enabling their config options in our +``.config``. KUnit tests usually (but don't always) have config options +ending in ``_KUNIT_TEST``. Most tests can either be built as a module, +or be built into the kernel. + +.. note :: + + We can enable the ``KUNIT_ALL_TESTS`` config option to + automatically enable all tests with satisfied dependencies. This is + a good way of quickly testing everything applicable to the current + config. + +Once we have built our kernel (and/or modules), it is simple to run +the tests. If the tests are built-in, they will run automatically on the +kernel boot. The results will be written to the kernel log (``dmesg``) +in TAP format. + +If the tests are built as modules, they will run when the module is +loaded. + +.. code-block :: bash + + # modprobe example-test + +The results will appear in TAP format in ``dmesg``. + +.. note :: + + If ``CONFIG_KUNIT_DEBUGFS`` is enabled, KUnit test results will + be accessible from the ``debugfs`` filesystem (if mounted). + They will be in ``/sys/kernel/debug/kunit/<test_suite>/results``, in + TAP format. diff --git a/Documentation/dev-tools/kunit/run_wrapper.rst b/Documentation/dev-tools/kunit/run_wrapper.rst new file mode 100644 index 000000000000..653985ce9cae --- /dev/null +++ b/Documentation/dev-tools/kunit/run_wrapper.rst @@ -0,0 +1,247 @@ +.. SPDX-License-Identifier: GPL-2.0 + +========================= +Run Tests with kunit_tool +========================= + +We can either run KUnit tests using kunit_tool or can run tests +manually, and then use kunit_tool to parse the results. To run tests +manually, see: Documentation/dev-tools/kunit/run_manual.rst. +As long as we can build the kernel, we can run KUnit. + +kunit_tool is a Python script which configures and builds a kernel, runs +tests, and formats the test results. + +Run command: + +.. code-block:: + + ./tools/testing/kunit/kunit.py run + +We should see the following: + +.. code-block:: + + Generating .config... + Building KUnit kernel... + Starting KUnit kernel... + +We may want to use the following options: + +.. code-block:: + + ./tools/testing/kunit/kunit.py run --timeout=30 --jobs=`nproc --all + +- ``--timeout`` sets a maximum amount of time for tests to run. +- ``--jobs`` sets the number of threads to build the kernel. + +kunit_tool will generate a ``.kunitconfig`` with a default +configuration, if no other ``.kunitconfig`` file exists +(in the build directory). In addition, it verifies that the +generated ``.config`` file contains the ``CONFIG`` options in the +``.kunitconfig``. +It is also possible to pass a separate ``.kunitconfig`` fragment to +kunit_tool. This is useful if we have several different groups of +tests we want to run independently, or if we want to use pre-defined +test configs for certain subsystems. + +To use a different ``.kunitconfig`` file (such as one +provided to test a particular subsystem), pass it as an option: + +.. code-block:: + + ./tools/testing/kunit/kunit.py run --kunitconfig=fs/ext4/.kunitconfig + +To view kunit_tool flags (optional command-line arguments), run: + +.. code-block:: + + ./tools/testing/kunit/kunit.py run --help + +Create a ``.kunitconfig`` File +=============================== + +If we want to run a specific set of tests (rather than those listed +in the KUnit ``defconfig``), we can provide Kconfig options in the +``.kunitconfig`` file. For default .kunitconfig, see: +https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/tree/tools/testing/kunit/configs/default.config. +A ``.kunitconfig`` is a ``minconfig`` (a .config +generated by running ``make savedefconfig``), used for running a +specific set of tests. This file contains the regular Kernel configs +with specific test targets. The ``.kunitconfig`` also +contains any other config options required by the tests (For example: +dependencies for features under tests, configs that enable/disable +certain code blocks, arch configs and so on). + +To create a ``.kunitconfig``, using the KUnit ``defconfig``: + +.. code-block:: + + cd $PATH_TO_LINUX_REPO + cp tools/testing/kunit/configs/default.config .kunit/.kunitconfig + +We can then add any other Kconfig options. For example: + +.. code-block:: + + CONFIG_LIST_KUNIT_TEST=y + +kunit_tool ensures that all config options in ``.kunitconfig`` are +set in the kernel ``.config`` before running the tests. It warns if we +have not included the options dependencies. + +.. note:: Removing something from the ``.kunitconfig`` will + not rebuild the ``.config file``. The configuration is only + updated if the ``.kunitconfig`` is not a subset of ``.config``. + This means that we can use other tools + (For example: ``make menuconfig``) to adjust other config options. + The build dir needs to be set for ``make menuconfig`` to + work, therefore by default use ``make O=.kunit menuconfig``. + +Configure, Build, and Run Tests +=============================== + +If we want to make manual changes to the KUnit build process, we +can run part of the KUnit build process independently. +When running kunit_tool, from a ``.kunitconfig``, we can generate a +``.config`` by using the ``config`` argument: + +.. code-block:: + + ./tools/testing/kunit/kunit.py config + +To build a KUnit kernel from the current ``.config``, we can use the +``build`` argument: + +.. code-block:: + + ./tools/testing/kunit/kunit.py build + +If we already have built UML kernel with built-in KUnit tests, we +can run the kernel, and display the test results with the ``exec`` +argument: + +.. code-block:: + + ./tools/testing/kunit/kunit.py exec + +The ``run`` command discussed in section: **Run Tests with kunit_tool**, +is equivalent to running the above three commands in sequence. + +Parse Test Results +================== + +KUnit tests output displays results in TAP (Test Anything Protocol) +format. When running tests, kunit_tool parses this output and prints +a summary. To see the raw test results in TAP format, we can pass the +``--raw_output`` argument: + +.. code-block:: + + ./tools/testing/kunit/kunit.py run --raw_output + +If we have KUnit results in the raw TAP format, we can parse them and +print the human-readable summary with the ``parse`` command for +kunit_tool. This accepts a filename for an argument, or will read from +standard input. + +.. code-block:: bash + + # Reading from a file + ./tools/testing/kunit/kunit.py parse /var/log/dmesg + # Reading from stdin + dmesg | ./tools/testing/kunit/kunit.py parse + +Run Selected Test Suites +======================== + +By passing a bash style glob filter to the ``exec`` or ``run`` +commands, we can run a subset of the tests built into a kernel . For +example: if we only want to run KUnit resource tests, use: + +.. code-block:: + + ./tools/testing/kunit/kunit.py run 'kunit-resource*' + +This uses the standard glob format with wildcard characters. + +Run Tests on qemu +================= + +kunit_tool supports running tests on qemu as well as +via UML. To run tests on qemu, by default it requires two flags: + +- ``--arch``: Selects a configs collection (Kconfig, qemu config options + and so on), that allow KUnit tests to be run on the specified + architecture in a minimal way. The architecture argument is same as + the option name passed to the ``ARCH`` variable used by Kbuild. + Not all architectures currently support this flag, but we can use + ``--qemu_config`` to handle it. If ``um`` is passed (or this flag + is ignored), the tests will run via UML. Non-UML architectures, + for example: i386, x86_64, arm and so on; run on qemu. + +- ``--cross_compile``: Specifies the Kbuild toolchain. It passes the + same argument as passed to the ``CROSS_COMPILE`` variable used by + Kbuild. As a reminder, this will be the prefix for the toolchain + binaries such as GCC. For example: + + - ``sparc64-linux-gnu`` if we have the sparc toolchain installed on + our system. + + - ``$HOME/toolchains/microblaze/gcc-9.2.0-nolibc/microblaze-linux/bin/microblaze-linux`` + if we have downloaded the microblaze toolchain from the 0-day + website to a directory in our home directory called toolchains. + +If we want to run KUnit tests on an architecture not supported by +the ``--arch`` flag, or want to run KUnit tests on qemu using a +non-default configuration; then we can write our own``QemuConfig``. +These ``QemuConfigs`` are written in Python. They have an import line +``from..qemu_config import QemuArchParams`` at the top of the file. +The file must contain a variable called ``QEMU_ARCH`` that has an +instance of ``QemuArchParams`` assigned to it. See example in: +``tools/testing/kunit/qemu_configs/x86_64.py``. + +Once we have a ``QemuConfig``, we can pass it into kunit_tool, +using the ``--qemu_config`` flag. When used, this flag replaces the +``--arch`` flag. For example: using +``tools/testing/kunit/qemu_configs/x86_64.py``, the invocation appear +as + +.. code-block:: bash + + ./tools/testing/kunit/kunit.py run \ + --timeout=60 \ + --jobs=12 \ + --qemu_config=./tools/testing/kunit/qemu_configs/x86_64.py + +To run existing KUnit tests on non-UML architectures, see: +Documentation/dev-tools/kunit/non_uml.rst. + +Command-Line Arguments +====================== + +kunit_tool has a number of other command-line arguments which can +be useful for our test environment. Below the most commonly used +command line arguments: + +- ``--help``: Lists all available options. To list common options, + place ``--help`` before the command. To list options specific to that + command, place ``--help`` after the command. + + .. note:: Different commands (``config``, ``build``, ``run``, etc) + have different supported options. +- ``--build_dir``: Specifies kunit_tool build directory. It includes + the ``.kunitconfig``, ``.config`` files and compiled kernel. + +- ``--make_options``: Specifies additional options to pass to make, when + compiling a kernel (using ``build`` or ``run`` commands). For example: + to enable compiler warnings, we can pass ``--make_options W=1``. + +- ``--alltests``: Builds a UML kernel with all config options enabled + using ``make allyesconfig``. This allows us to run as many tests as + possible. + + .. note:: It is slow and prone to breakage as new options are + added or modified. Instead, enable all tests + which have satisfied dependencies by adding + ``CONFIG_KUNIT_ALL_TESTS=y`` to your ``.kunitconfig``. diff --git a/Documentation/dev-tools/kunit/start.rst b/Documentation/dev-tools/kunit/start.rst index 1e00f9226f74..ad168d16968f 100644 --- a/Documentation/dev-tools/kunit/start.rst +++ b/Documentation/dev-tools/kunit/start.rst @@ -4,132 +4,137 @@ Getting Started =============== -Installing dependencies +Installing Dependencies ======================= -KUnit has the same dependencies as the Linux kernel. As long as you can build -the kernel, you can run KUnit. +KUnit has the same dependencies as the Linux kernel. As long as you can +build the kernel, you can run KUnit. -Running tests with the KUnit Wrapper -==================================== -Included with KUnit is a simple Python wrapper which runs tests under User Mode -Linux, and formats the test results. - -The wrapper can be run with: +Running tests with kunit_tool +============================= +kunit_tool is a Python script, which configures and builds a kernel, runs +tests, and formats the test results. From the kernel repository, you +can run kunit_tool: .. code-block:: bash ./tools/testing/kunit/kunit.py run -For more information on this wrapper (also called kunit_tool) check out the -Documentation/dev-tools/kunit/kunit-tool.rst page. +For more information on this wrapper, see: +Documentation/dev-tools/kunit/run_wrapper.rst. + +Creating a ``.kunitconfig`` +--------------------------- + +By default, kunit_tool runs a selection of tests. However, you can specify which +unit tests to run by creating a ``.kunitconfig`` file with kernel config options +that enable only a specific set of tests and their dependencies. +The ``.kunitconfig`` file contains a list of kconfig options which are required +to run the desired targets. The ``.kunitconfig`` also contains any other test +specific config options, such as test dependencies. For example: the +``FAT_FS`` tests - ``FAT_KUNIT_TEST``, depends on +``FAT_FS``. ``FAT_FS`` can be enabled by selecting either ``MSDOS_FS`` +or ``VFAT_FS``. To run ``FAT_KUNIT_TEST``, the ``.kunitconfig`` has: -Creating a .kunitconfig ------------------------ -If you want to run a specific set of tests (rather than those listed in the -KUnit defconfig), you can provide Kconfig options in the ``.kunitconfig`` file. -This file essentially contains the regular Kernel config, with the specific -test targets as well. The ``.kunitconfig`` should also contain any other config -options required by the tests. +.. code-block:: none + + CONFIG_KUNIT=y + CONFIG_MSDOS_FS=y + CONFIG_FAT_KUNIT_TEST=y -A good starting point for a ``.kunitconfig`` is the KUnit defconfig: +1. A good starting point for the ``.kunitconfig``, is the KUnit default + config. Run the command: .. code-block:: bash cd $PATH_TO_LINUX_REPO cp tools/testing/kunit/configs/default.config .kunitconfig -You can then add any other Kconfig options you wish, e.g.: +.. note :: + You may want to remove CONFIG_KUNIT_ALL_TESTS from the ``.kunitconfig`` as + it will enable a number of additional tests that you may not want. + +2. You can then add any other Kconfig options, for example: .. code-block:: none CONFIG_LIST_KUNIT_TEST=y -:doc:`kunit_tool <kunit-tool>` will ensure that all config options set in -``.kunitconfig`` are set in the kernel ``.config`` before running the tests. -It'll warn you if you haven't included the dependencies of the options you're -using. +Before running the tests, kunit_tool ensures that all config options +set in ``.kunitconfig`` are set in the kernel ``.config``. It will warn +you if you have not included dependencies for the options used. -.. note:: - Note that removing something from the ``.kunitconfig`` will not trigger a - rebuild of the ``.config`` file: the configuration is only updated if the - ``.kunitconfig`` is not a subset of ``.config``. This means that you can use - other tools (such as make menuconfig) to adjust other config options. +.. note :: + If you change the ``.kunitconfig``, kunit.py will trigger a rebuild of the + ``.config`` file. But you can edit the ``.config`` file directly or with + tools like ``make menuconfig O=.kunit``. As long as its a superset of + ``.kunitconfig``, kunit.py won't overwrite your changes. - -Running the tests (KUnit Wrapper) ---------------------------------- - -To make sure that everything is set up correctly, simply invoke the Python -wrapper from your kernel repo: +Running Tests (KUnit Wrapper) +----------------------------- +1. To make sure that everything is set up correctly, invoke the Python + wrapper from your kernel repository: .. code-block:: bash ./tools/testing/kunit/kunit.py run -.. note:: - You may want to run ``make mrproper`` first. - If everything worked correctly, you should see the following: -.. code-block:: bash +.. code-block:: Generating .config ... Building KUnit Kernel ... Starting KUnit Kernel ... -followed by a list of tests that are run. All of them should be passing. +The tests will pass or fail. -.. note:: - Because it is building a lot of sources for the first time, the - ``Building KUnit kernel`` step may take a while. +.. note :: + Because it is building a lot of sources for the first time, the + ``Building KUnit kernel`` may take a while. -Running tests without the KUnit Wrapper +Running Tests without the KUnit Wrapper ======================================= - -If you'd rather not use the KUnit Wrapper (if, for example, you need to -integrate with other systems, or use an architecture other than UML), KUnit can -be included in any kernel, and the results read out and parsed manually. - -.. note:: - KUnit is not designed for use in a production system, and it's possible that - tests may reduce the stability or security of the system. - - - -Configuring the kernel +If you do not want to use the KUnit Wrapper (for example: you want code +under test to integrate with other systems, or use a different/ +unsupported architecture or configuration), KUnit can be included in +any kernel, and the results are read out and parsed manually. + +.. note :: + ``CONFIG_KUNIT`` should not be enabled in a production environment. + Enabling KUnit disables Kernel Address-Space Layout Randomization + (KASLR), and tests may affect the state of the kernel in ways not + suitable for production. + +Configuring the Kernel ---------------------- +To enable KUnit itself, you need to enable the ``CONFIG_KUNIT`` Kconfig +option (under Kernel Hacking/Kernel Testing and Coverage in +``menuconfig``). From there, you can enable any KUnit tests. They +usually have config options ending in ``_KUNIT_TEST``. -In order to enable KUnit itself, you simply need to enable the ``CONFIG_KUNIT`` -Kconfig option (it's under Kernel Hacking/Kernel Testing and Coverage in -menuconfig). From there, you can enable any KUnit tests you want: they usually -have config options ending in ``_KUNIT_TEST``. - -KUnit and KUnit tests can be compiled as modules: in this case the tests in a -module will be run when the module is loaded. +KUnit and KUnit tests can be compiled as modules. The tests in a module +will run when the module is loaded. - -Running the tests (w/o KUnit Wrapper) +Running Tests (without KUnit Wrapper) ------------------------------------- +Build and run your kernel. In the kernel log, the test output is printed +out in the TAP format. This will only happen by default if KUnit/tests +are built-in. Otherwise the module will need to be loaded. -Build and run your kernel as usual. Test output will be written to the kernel -log in `TAP <https://testanything.org/>`_ format. - -.. note:: - It's possible that there will be other lines and/or data interspersed in the - TAP output. - +.. note :: + Some lines and/or data may get interspersed in the TAP output. -Writing your first test +Writing Your First Test ======================= +In your kernel repository, let's add some code that we can test. -In your kernel repo let's add some code that we can test. Create a file -``drivers/misc/example.h`` with the contents: +1. Create a file ``drivers/misc/example.h``, which includes: .. code-block:: c int misc_example_add(int left, int right); -create a file ``drivers/misc/example.c``: +2. Create a file ``drivers/misc/example.c``, which includes: .. code-block:: c @@ -142,21 +147,22 @@ create a file ``drivers/misc/example.c``: return left + right; } -Now add the following lines to ``drivers/misc/Kconfig``: +3. Add the following lines to ``drivers/misc/Kconfig``: .. code-block:: kconfig config MISC_EXAMPLE bool "My example" -and the following lines to ``drivers/misc/Makefile``: +4. Add the following lines to ``drivers/misc/Makefile``: .. code-block:: make obj-$(CONFIG_MISC_EXAMPLE) += example.o -Now we are ready to write the test. The test will be in -``drivers/misc/example-test.c``: +Now we are ready to write the test cases. + +1. Add the below test case in ``drivers/misc/example_test.c``: .. code-block:: c @@ -191,7 +197,7 @@ Now we are ready to write the test. The test will be in }; kunit_test_suite(misc_example_test_suite); -Now add the following to ``drivers/misc/Kconfig``: +2. Add the following lines to ``drivers/misc/Kconfig``: .. code-block:: kconfig @@ -200,20 +206,20 @@ Now add the following to ``drivers/misc/Kconfig``: depends on MISC_EXAMPLE && KUNIT=y default KUNIT_ALL_TESTS -and the following to ``drivers/misc/Makefile``: +3. Add the following lines to ``drivers/misc/Makefile``: .. code-block:: make - obj-$(CONFIG_MISC_EXAMPLE_TEST) += example-test.o + obj-$(CONFIG_MISC_EXAMPLE_TEST) += example_test.o -Now add it to your ``.kunitconfig``: +4. Add the following lines to ``.kunitconfig``: .. code-block:: none CONFIG_MISC_EXAMPLE=y CONFIG_MISC_EXAMPLE_TEST=y -Now you can run the test: +5. Run the test: .. code-block:: bash @@ -227,16 +233,23 @@ You should see the following failure: [16:08:57] [PASSED] misc-example:misc_example_add_test_basic [16:08:57] [FAILED] misc-example:misc_example_test_failure [16:08:57] EXPECTATION FAILED at drivers/misc/example-test.c:17 - [16:08:57] This test never passes. + [16:08:57] This test never passes. ... -Congrats! You just wrote your first KUnit test! +Congrats! You just wrote your first KUnit test. Next Steps ========== -* Check out the Documentation/dev-tools/kunit/tips.rst page for tips on - writing idiomatic KUnit tests. -* Check out the :doc:`running_tips` page for tips on - how to make running KUnit tests easier. -* Optional: see the :doc:`usage` page for a more - in-depth explanation of KUnit. + +* Documentation/dev-tools/kunit/architecture.rst - KUnit architecture. +* Documentation/dev-tools/kunit/run_wrapper.rst - run kunit_tool. +* Documentation/dev-tools/kunit/run_manual.rst - run tests without kunit_tool. +* Documentation/dev-tools/kunit/usage.rst - write tests. +* Documentation/dev-tools/kunit/tips.rst - best practices with + examples. +* Documentation/dev-tools/kunit/api/index.rst - KUnit APIs + used for testing. +* Documentation/dev-tools/kunit/kunit-tool.rst - kunit_tool helper + script. +* Documentation/dev-tools/kunit/faq.rst - KUnit common questions and + answers. diff --git a/Documentation/dev-tools/kunit/style.rst b/Documentation/dev-tools/kunit/style.rst index 8dbcdc552606..b6d0d7359f00 100644 --- a/Documentation/dev-tools/kunit/style.rst +++ b/Documentation/dev-tools/kunit/style.rst @@ -4,37 +4,36 @@ Test Style and Nomenclature =========================== -To make finding, writing, and using KUnit tests as simple as possible, it's +To make finding, writing, and using KUnit tests as simple as possible, it is strongly encouraged that they are named and written according to the guidelines -below. While it's possible to write KUnit tests which do not follow these rules, +below. While it is possible to write KUnit tests which do not follow these rules, they may break some tooling, may conflict with other tests, and may not be run automatically by testing systems. -It's recommended that you only deviate from these guidelines when: +It is recommended that you only deviate from these guidelines when: -1. Porting tests to KUnit which are already known with an existing name, or -2. Writing tests which would cause serious problems if automatically run (e.g., - non-deterministically producing false positives or negatives, or taking an - extremely long time to run). +1. Porting tests to KUnit which are already known with an existing name. +2. Writing tests which would cause serious problems if automatically run. For + example, non-deterministically producing false positives or negatives, or + taking a long time to run. Subsystems, Suites, and Tests ============================= -In order to make tests as easy to find as possible, they're grouped into suites -and subsystems. A test suite is a group of tests which test a related area of -the kernel, and a subsystem is a set of test suites which test different parts -of the same kernel subsystem or driver. +To make tests easy to find, they are grouped into suites and subsystems. A test +suite is a group of tests which test a related area of the kernel. A subsystem +is a set of test suites which test different parts of a kernel subsystem +or a driver. Subsystems ---------- Every test suite must belong to a subsystem. A subsystem is a collection of one or more KUnit test suites which test the same driver or part of the kernel. A -rule of thumb is that a test subsystem should match a single kernel module. If -the code being tested can't be compiled as a module, in many cases the subsystem -should correspond to a directory in the source tree or an entry in the -MAINTAINERS file. If unsure, follow the conventions set by tests in similar -areas. +test subsystem should match a single kernel module. If the code being tested +cannot be compiled as a module, in many cases the subsystem should correspond to +a directory in the source tree or an entry in the ``MAINTAINERS`` file. If +unsure, follow the conventions set by tests in similar areas. Test subsystems should be named after the code being tested, either after the module (wherever possible), or after the directory or files being tested. Test @@ -42,9 +41,8 @@ subsystems should be named to avoid ambiguity where necessary. If a test subsystem name has multiple components, they should be separated by underscores. *Do not* include "test" or "kunit" directly in the subsystem name -unless you are actually testing other tests or the kunit framework itself. - -Example subsystems could be: +unless we are actually testing other tests or the kunit framework itself. For +example, subsystems could be called: ``ext4`` Matches the module and filesystem name. @@ -56,48 +54,46 @@ Example subsystems could be: Has several components (``snd``, ``hda``, ``codec``, ``hdmi``) separated by underscores. Matches the module name. -Avoid names like these: +Avoid names as shown in examples below: ``linear-ranges`` Names should use underscores, not dashes, to separate words. Prefer ``linear_ranges``. ``qos-kunit-test`` - As well as using underscores, this name should not have "kunit-test" as a - suffix, and ``qos`` is ambiguous as a subsystem name. ``power_qos`` would be a - better name. + This name should use underscores, and not have "kunit-test" as a + suffix. ``qos`` is also ambiguous as a subsystem name, because several parts + of the kernel have a ``qos`` subsystem. ``power_qos`` would be a better name. ``pc_parallel_port`` The corresponding module name is ``parport_pc``, so this subsystem should also be named ``parport_pc``. .. note:: - The KUnit API and tools do not explicitly know about subsystems. They're - simply a way of categorising test suites and naming modules which - provides a simple, consistent way for humans to find and run tests. This - may change in the future, though. + The KUnit API and tools do not explicitly know about subsystems. They are + a way of categorizing test suites and naming modules which provides a + simple, consistent way for humans to find and run tests. This may change + in the future. Suites ------ KUnit tests are grouped into test suites, which cover a specific area of -functionality being tested. Test suites can have shared initialisation and -shutdown code which is run for all tests in the suite. -Not all subsystems will need to be split into multiple test suites (e.g. simple drivers). +functionality being tested. Test suites can have shared initialization and +shutdown code which is run for all tests in the suite. Not all subsystems need +to be split into multiple test suites (for example, simple drivers). Test suites are named after the subsystem they are part of. If a subsystem contains several suites, the specific area under test should be appended to the subsystem name, separated by an underscore. In the event that there are multiple types of test using KUnit within a -subsystem (e.g., both unit tests and integration tests), they should be put into -separate suites, with the type of test as the last element in the suite name. -Unless these tests are actually present, avoid using ``_test``, ``_unittest`` or -similar in the suite name. +subsystem (for example, both unit tests and integration tests), they should be +put into separate suites, with the type of test as the last element in the suite +name. Unless these tests are actually present, avoid using ``_test``, ``_unittest`` +or similar in the suite name. The full test suite name (including the subsystem name) should be specified as the ``.name`` member of the ``kunit_suite`` struct, and forms the base for the -module name (see below). - -Example test suites could include: +module name. For example, test suites could include: ``ext4_inode`` Part of the ``ext4`` subsystem, testing the ``inode`` area. @@ -109,26 +105,27 @@ Example test suites could include: The ``kasan`` subsystem has only one suite, so the suite name is the same as the subsystem name. -Avoid names like: +Avoid names, for example: ``ext4_ext4_inode`` - There's no reason to state the subsystem twice. + There is no reason to state the subsystem twice. ``property_entry`` The suite name is ambiguous without the subsystem name. ``kasan_integration_test`` Because there is only one suite in the ``kasan`` subsystem, the suite should - just be called ``kasan``. There's no need to redundantly add - ``integration_test``. Should a separate test suite with, for example, unit - tests be added, then that suite could be named ``kasan_unittest`` or similar. + just be called as ``kasan``. Do not redundantly add + ``integration_test``. It should be a separate test suite. For example, if the + unit tests are added, then that suite could be named as ``kasan_unittest`` or + similar. Test Cases ---------- Individual tests consist of a single function which tests a constrained -codepath, property, or function. In the test output, individual tests' results -will show up as subtests of the suite's results. +codepath, property, or function. In the test output, an individual test's +results will show up as subtests of the suite's results. -Tests should be named after what they're testing. This is often the name of the +Tests should be named after what they are testing. This is often the name of the function being tested, with a description of the input or codepath being tested. As tests are C functions, they should be named and written in accordance with the kernel coding style. @@ -136,7 +133,7 @@ the kernel coding style. .. note:: As tests are themselves functions, their names cannot conflict with other C identifiers in the kernel. This may require some creative - naming. It's a good idea to make your test functions `static` to avoid + naming. It is a good idea to make your test functions `static` to avoid polluting the global namespace. Example test names include: @@ -162,16 +159,16 @@ This Kconfig entry must: * be named ``CONFIG_<name>_KUNIT_TEST``: where <name> is the name of the test suite. * be listed either alongside the config entries for the driver/subsystem being - tested, or be under [Kernel Hacking]→[Kernel Testing and Coverage] -* depend on ``CONFIG_KUNIT`` + tested, or be under [Kernel Hacking]->[Kernel Testing and Coverage] +* depend on ``CONFIG_KUNIT``. * be visible only if ``CONFIG_KUNIT_ALL_TESTS`` is not enabled. * have a default value of ``CONFIG_KUNIT_ALL_TESTS``. -* have a brief description of KUnit in the help text +* have a brief description of KUnit in the help text. -Unless there's a specific reason not to (e.g. the test is unable to be built as -a module), Kconfig entries for tests should be tristate. +If we are not able to meet above conditions (for example, the test is unable to +be built as a module), Kconfig entries for tests should be tristate. -An example Kconfig entry: +For example, a Kconfig entry might look like: .. code-block:: none @@ -182,8 +179,8 @@ An example Kconfig entry: help This builds unit tests for foo. - For more information on KUnit and unit tests in general, please refer - to the KUnit documentation in Documentation/dev-tools/kunit/. + For more information on KUnit and unit tests in general, + please refer to the KUnit documentation in Documentation/dev-tools/kunit/. If unsure, say N. diff --git a/Documentation/dev-tools/kunit/usage.rst b/Documentation/dev-tools/kunit/usage.rst index 63f1bb89ebf5..76af931a332c 100644 --- a/Documentation/dev-tools/kunit/usage.rst +++ b/Documentation/dev-tools/kunit/usage.rst @@ -1,57 +1,13 @@ .. SPDX-License-Identifier: GPL-2.0 -=========== -Using KUnit -=========== - -The purpose of this document is to describe what KUnit is, how it works, how it -is intended to be used, and all the concepts and terminology that are needed to -understand it. This guide assumes a working knowledge of the Linux kernel and -some basic knowledge of testing. - -For a high level introduction to KUnit, including setting up KUnit for your -project, see Documentation/dev-tools/kunit/start.rst. - -Organization of this document -============================= - -This document is organized into two main sections: Testing and Common Patterns. -The first covers what unit tests are and how to use KUnit to write them. The -second covers common testing patterns, e.g. how to isolate code and make it -possible to unit test code that was otherwise un-unit-testable. - -Testing -======= - -What is KUnit? --------------- - -"K" is short for "kernel" so "KUnit" is the "(Linux) Kernel Unit Testing -Framework." KUnit is intended first and foremost for writing unit tests; it is -general enough that it can be used to write integration tests; however, this is -a secondary goal. KUnit has no ambition of being the only testing framework for -the kernel; for example, it does not intend to be an end-to-end testing -framework. - -What is Unit Testing? ---------------------- - -A `unit test <https://martinfowler.com/bliki/UnitTest.html>`_ is a test that -tests code at the smallest possible scope, a *unit* of code. In the C -programming language that's a function. - -Unit tests should be written for all the publicly exposed functions in a -compilation unit; so that is all the functions that are exported in either a -*class* (defined below) or all functions which are **not** static. - Writing Tests -------------- +============= Test Cases -~~~~~~~~~~ +---------- The fundamental unit in KUnit is the test case. A test case is a function with -the signature ``void (*)(struct kunit *test)``. It calls a function to be tested +the signature ``void (*)(struct kunit *test)``. It calls the function under test and then sets *expectations* for what should happen. For example: .. code-block:: c @@ -65,18 +21,19 @@ and then sets *expectations* for what should happen. For example: KUNIT_FAIL(test, "This test never passes."); } -In the above example ``example_test_success`` always passes because it does -nothing; no expectations are set, so all expectations pass. On the other hand -``example_test_failure`` always fails because it calls ``KUNIT_FAIL``, which is -a special expectation that logs a message and causes the test case to fail. +In the above example, ``example_test_success`` always passes because it does +nothing; no expectations are set, and therefore all expectations pass. On the +other hand ``example_test_failure`` always fails because it calls ``KUNIT_FAIL``, +which is a special expectation that logs a message and causes the test case to +fail. Expectations ~~~~~~~~~~~~ -An *expectation* is a way to specify that you expect a piece of code to do -something in a test. An expectation is called like a function. A test is made -by setting expectations about the behavior of a piece of code under test; when -one or more of the expectations fail, the test case fails and information about -the failure is logged. For example: +An *expectation* specifies that we expect a piece of code to do something in a +test. An expectation is called like a function. A test is made by setting +expectations about the behavior of a piece of code under test. When one or more +expectations fail, the test case fails and information about the failure is +logged. For example: .. code-block:: c @@ -86,29 +43,28 @@ the failure is logged. For example: KUNIT_EXPECT_EQ(test, 2, add(1, 1)); } -In the above example ``add_test_basic`` makes a number of assertions about the -behavior of a function called ``add``; the first parameter is always of type -``struct kunit *``, which contains information about the current test context; -the second parameter, in this case, is what the value is expected to be; the +In the above example, ``add_test_basic`` makes a number of assertions about the +behavior of a function called ``add``. The first parameter is always of type +``struct kunit *``, which contains information about the current test context. +The second parameter, in this case, is what the value is expected to be. The last value is what the value actually is. If ``add`` passes all of these expectations, the test case, ``add_test_basic`` will pass; if any one of these expectations fails, the test case will fail. -It is important to understand that a test case *fails* when any expectation is -violated; however, the test will continue running, potentially trying other -expectations until the test case ends or is otherwise terminated. This is as -opposed to *assertions* which are discussed later. +A test case *fails* when any expectation is violated; however, the test will +continue to run, and try other expectations until the test case ends or is +otherwise terminated. This is as opposed to *assertions* which are discussed +later. -To learn about more expectations supported by KUnit, see -Documentation/dev-tools/kunit/api/test.rst. +To learn about more KUnit expectations, see Documentation/dev-tools/kunit/api/test.rst. .. note:: - A single test case should be pretty short, pretty easy to understand, - focused on a single behavior. + A single test case should be short, easy to understand, and focused on a + single behavior. -For example, if we wanted to properly test the add function above, we would -create additional tests cases which would each test a different property that an -add function should have like this: +For example, if we want to rigorously test the ``add`` function above, create +additional tests cases which would test each property that an ``add`` function +should have as shown below: .. code-block:: c @@ -134,56 +90,43 @@ add function should have like this: KUNIT_EXPECT_EQ(test, INT_MIN, add(INT_MAX, 1)); } -Notice how it is immediately obvious what all the properties that we are testing -for are. - Assertions ~~~~~~~~~~ -KUnit also has the concept of an *assertion*. An assertion is just like an -expectation except the assertion immediately terminates the test case if it is -not satisfied. - -For example: +An assertion is like an expectation, except that the assertion immediately +terminates the test case if the condition is not satisfied. For example: .. code-block:: c - static void mock_test_do_expect_default_return(struct kunit *test) + static void test_sort(struct kunit *test) { - struct mock_test_context *ctx = test->priv; - struct mock *mock = ctx->mock; - int param0 = 5, param1 = -5; - const char *two_param_types[] = {"int", "int"}; - const void *two_params[] = {¶m0, ¶m1}; - const void *ret; - - ret = mock->do_expect(mock, - "test_printk", test_printk, - two_param_types, two_params, - ARRAY_SIZE(two_params)); - KUNIT_ASSERT_NOT_ERR_OR_NULL(test, ret); - KUNIT_EXPECT_EQ(test, -4, *((int *) ret)); + int *a, i, r = 1; + a = kunit_kmalloc_array(test, TEST_LEN, sizeof(*a), GFP_KERNEL); + KUNIT_ASSERT_NOT_ERR_OR_NULL(test, a); + for (i = 0; i < TEST_LEN; i++) { + r = (r * 725861) % 6599; + a[i] = r; + } + sort(a, TEST_LEN, sizeof(*a), cmpint, NULL); + for (i = 0; i < TEST_LEN-1; i++) + KUNIT_EXPECT_LE(test, a[i], a[i + 1]); } -In this example, the method under test should return a pointer to a value, so -if the pointer returned by the method is null or an errno, we don't want to -bother continuing the test since the following expectation could crash the test -case. `ASSERT_NOT_ERR_OR_NULL(...)` allows us to bail out of the test case if -the appropriate conditions have not been satisfied to complete the test. +In this example, the method under test should return pointer to a value. If the +pointer returns null or an errno, we want to stop the test since the following +expectation could crash the test case. `ASSERT_NOT_ERR_OR_NULL(...)` allows us +to bail out of the test case if the appropriate conditions are not satisfied to +complete the test. Test Suites ~~~~~~~~~~~ -Now obviously one unit test isn't very helpful; the power comes from having -many test cases covering all of a unit's behaviors. Consequently it is common -to have many *similar* tests; in order to reduce duplication in these closely -related tests most unit testing frameworks - including KUnit - provide the -concept of a *test suite*. A *test suite* is just a collection of test cases -for a unit of code with a set up function that gets invoked before every test -case and then a tear down function that gets invoked after every test case -completes. - -Example: +We need many test cases covering all the unit's behaviors. It is common to have +many similar tests. In order to reduce duplication in these closely related +tests, most unit testing frameworks (including KUnit) provide the concept of a +*test suite*. A test suite is a collection of test cases for a unit of code +with a setup function that gets invoked before every test case and then a tear +down function that gets invoked after every test case completes. For example: .. code-block:: c @@ -202,23 +145,48 @@ Example: }; kunit_test_suite(example_test_suite); -In the above example the test suite, ``example_test_suite``, would run the test -cases ``example_test_foo``, ``example_test_bar``, and ``example_test_baz``; -each would have ``example_test_init`` called immediately before it and would -have ``example_test_exit`` called immediately after it. +In the above example, the test suite ``example_test_suite`` would run the test +cases ``example_test_foo``, ``example_test_bar``, and ``example_test_baz``. Each +would have ``example_test_init`` called immediately before it and +``example_test_exit`` called immediately after it. ``kunit_test_suite(example_test_suite)`` registers the test suite with the KUnit test framework. .. note:: - A test case will only be run if it is associated with a test suite. + A test case will only run if it is associated with a test suite. + +``kunit_test_suite(...)`` is a macro which tells the linker to put the +specified test suite in a special linker section so that it can be run by KUnit +either after ``late_init``, or when the test module is loaded (if the test was +built as a module). + +For more information, see Documentation/dev-tools/kunit/api/test.rst. + +Writing Tests For Other Architectures +------------------------------------- + +It is better to write tests that run on UML to tests that only run under a +particular architecture. It is better to write tests that run under QEMU or +another easy to obtain (and monetarily free) software environment to a specific +piece of hardware. -``kunit_test_suite(...)`` is a macro which tells the linker to put the specified -test suite in a special linker section so that it can be run by KUnit either -after late_init, or when the test module is loaded (depending on whether the -test was built in or not). +Nevertheless, there are still valid reasons to write a test that is architecture +or hardware specific. For example, we might want to test code that really +belongs in ``arch/some-arch/*``. Even so, try to write the test so that it does +not depend on physical hardware. Some of our test cases may not need hardware, +only few tests actually require the hardware to test it. When hardware is not +available, instead of disabling tests, we can skip them. -For more information on these types of things see the -Documentation/dev-tools/kunit/api/test.rst. +Now that we have narrowed down exactly what bits are hardware specific, the +actual procedure for writing and running the tests is same as writing normal +KUnit tests. + +.. important:: + We may have to reset hardware state. If this is not possible, we may only + be able to run one test case per invocation. + +.. TODO(brendanhiggins@google.com): Add an actual example of an architecture- + dependent KUnit test. Common Patterns =============== @@ -226,43 +194,39 @@ Common Patterns Isolating Behavior ------------------ -The most important aspect of unit testing that other forms of testing do not -provide is the ability to limit the amount of code under test to a single unit. -In practice, this is only possible by being able to control what code gets run -when the unit under test calls a function and this is usually accomplished -through some sort of indirection where a function is exposed as part of an API -such that the definition of that function can be changed without affecting the -rest of the code base. In the kernel this primarily comes from two constructs, -classes, structs that contain function pointers that are provided by the -implementer, and architecture-specific functions which have definitions selected -at compile time. +Unit testing limits the amount of code under test to a single unit. It controls +what code gets run when the unit under test calls a function. Where a function +is exposed as part of an API such that the definition of that function can be +changed without affecting the rest of the code base. In the kernel, this comes +from two constructs: classes, which are structs that contain function pointers +provided by the implementer, and architecture-specific functions, which have +definitions selected at compile time. Classes ~~~~~~~ Classes are not a construct that is built into the C programming language; -however, it is an easily derived concept. Accordingly, pretty much every project -that does not use a standardized object oriented library (like GNOME's GObject) -has their own slightly different way of doing object oriented programming; the -Linux kernel is no exception. +however, it is an easily derived concept. Accordingly, in most cases, every +project that does not use a standardized object oriented library (like GNOME's +GObject) has their own slightly different way of doing object oriented +programming; the Linux kernel is no exception. The central concept in kernel object oriented programming is the class. In the kernel, a *class* is a struct that contains function pointers. This creates a contract between *implementers* and *users* since it forces them to use the -same function signature without having to call the function directly. In order -for it to truly be a class, the function pointers must specify that a pointer -to the class, known as a *class handle*, be one of the parameters; this makes -it possible for the member functions (also known as *methods*) to have access -to member variables (more commonly known as *fields*) allowing the same -implementation to have multiple *instances*. - -Typically a class can be *overridden* by *child classes* by embedding the -*parent class* in the child class. Then when a method provided by the child -class is called, the child implementation knows that the pointer passed to it is -of a parent contained within the child; because of this, the child can compute -the pointer to itself because the pointer to the parent is always a fixed offset -from the pointer to the child; this offset is the offset of the parent contained -in the child struct. For example: +same function signature without having to call the function directly. To be a +class, the function pointers must specify that a pointer to the class, known as +a *class handle*, be one of the parameters. Thus the member functions (also +known as *methods*) have access to member variables (also known as *fields*) +allowing the same implementation to have multiple *instances*. + +A class can be *overridden* by *child classes* by embedding the *parent class* +in the child class. Then when the child class *method* is called, the child +implementation knows that the pointer passed to it is of a parent contained +within the child. Thus, the child can compute the pointer to itself because the +pointer to the parent is always a fixed offset from the pointer to the child. +This offset is the offset of the parent contained in the child struct. For +example: .. code-block:: c @@ -290,8 +254,8 @@ in the child struct. For example: self->width = width; } -In this example (as in most kernel code) the operation of computing the pointer -to the child from the pointer to the parent is done by ``container_of``. +In this example, computing the pointer to the child from the pointer to the +parent is done by ``container_of``. Faking Classes ~~~~~~~~~~~~~~ @@ -300,14 +264,11 @@ In order to unit test a piece of code that calls a method in a class, the behavior of the method must be controllable, otherwise the test ceases to be a unit test and becomes an integration test. -A fake just provides an implementation of a piece of code that is different than -what runs in a production instance, but behaves identically from the standpoint -of the callers; this is usually done to replace a dependency that is hard to -deal with, or is slow. - -A good example for this might be implementing a fake EEPROM that just stores the -"contents" in an internal buffer. For example, let's assume we have a class that -represents an EEPROM: +A fake class implements a piece of code that is different than what runs in a +production instance, but behaves identical from the standpoint of the callers. +This is done to replace a dependency that is hard to deal with, or is slow. For +example, implementing a fake EEPROM that stores the "contents" in an +internal buffer. Assume we have a class that represents an EEPROM: .. code-block:: c @@ -316,7 +277,7 @@ represents an EEPROM: ssize_t (*write)(struct eeprom *this, size_t offset, const char *buffer, size_t count); }; -And we want to test some code that buffers writes to the EEPROM: +And we want to test code that buffers writes to the EEPROM: .. code-block:: c @@ -329,7 +290,7 @@ And we want to test some code that buffers writes to the EEPROM: struct eeprom_buffer *new_eeprom_buffer(struct eeprom *eeprom); void destroy_eeprom_buffer(struct eeprom *eeprom); -We can easily test this code by *faking out* the underlying EEPROM: +We can test this code by *faking out* the underlying EEPROM: .. code-block:: c @@ -456,14 +417,14 @@ We can now use it to test ``struct eeprom_buffer``: destroy_eeprom_buffer(ctx->eeprom_buffer); } -Testing against multiple inputs +Testing Against Multiple Inputs ------------------------------- -Testing just a few inputs might not be enough to have confidence that the code -works correctly, e.g. for a hash function. +Testing just a few inputs is not enough to ensure that the code works correctly, +for example: testing a hash function. -In such cases, it can be helpful to have a helper macro or function, e.g. this -fictitious example for ``sha1sum(1)`` +We can write a helper macro or function. The function is called for each input. +For example, to test ``sha1sum(1)``, we can write: .. code-block:: c @@ -475,16 +436,15 @@ fictitious example for ``sha1sum(1)`` TEST_SHA1("hello world", "2aae6c35c94fcfb415dbe95f408b9ce91ee846ed"); TEST_SHA1("hello world!", "430ce34d020724ed75a196dfc2ad67c77772d169"); +Note the use of the ``_MSG`` version of ``KUNIT_EXPECT_STREQ`` to print a more +detailed error and make the assertions clearer within the helper macros. -Note the use of ``KUNIT_EXPECT_STREQ_MSG`` to give more context when it fails -and make it easier to track down. (Yes, in this example, ``want`` is likely -going to be unique enough on its own). +The ``_MSG`` variants are useful when the same expectation is called multiple +times (in a loop or helper function) and thus the line number is not enough to +identify what failed, as shown below. -The ``_MSG`` variants are even more useful when the same expectation is called -multiple times (in a loop or helper function) and thus the line number isn't -enough to identify what failed, like below. - -In some cases, it can be helpful to write a *table-driven test* instead, e.g. +In complicated cases, we recommend using a *table-driven test* compared to the +helper macro variation, for example: .. code-block:: c @@ -513,17 +473,18 @@ In some cases, it can be helpful to write a *table-driven test* instead, e.g. } -There's more boilerplate involved, but it can: +There is more boilerplate code involved, but it can: + +* be more readable when there are multiple inputs/outputs (due to field names). -* be more readable when there are multiple inputs/outputs thanks to field names, + * For example, see ``fs/ext4/inode-test.c``. - * E.g. see ``fs/ext4/inode-test.c`` for an example of both. -* reduce duplication if test cases can be shared across multiple tests. +* reduce duplication if test cases are shared across multiple tests. - * E.g. if we wanted to also test ``sha256sum``, we could add a ``sha256`` + * For example: if we want to test ``sha256sum``, we could add a ``sha256`` field and reuse ``cases``. -* be converted to a "parameterized test", see below. +* be converted to a "parameterized test". Parameterized Testing ~~~~~~~~~~~~~~~~~~~~~ @@ -531,7 +492,7 @@ Parameterized Testing The table-driven testing pattern is common enough that KUnit has special support for it. -Reusing the same ``cases`` array from above, we can write the test as a +By reusing the same ``cases`` array from above, we can write the test as a "parameterized test" with the following. .. code-block:: c @@ -582,193 +543,160 @@ Reusing the same ``cases`` array from above, we can write the test as a .. _kunit-on-non-uml: -KUnit on non-UML architectures -============================== - -By default KUnit uses UML as a way to provide dependencies for code under test. -Under most circumstances KUnit's usage of UML should be treated as an -implementation detail of how KUnit works under the hood. Nevertheless, there -are instances where being able to run architecture-specific code or test -against real hardware is desirable. For these reasons KUnit supports running on -other architectures. - -Running existing KUnit tests on non-UML architectures ------------------------------------------------------ +Exiting Early on Failed Expectations +------------------------------------ -There are some special considerations when running existing KUnit tests on -non-UML architectures: +We can use ``KUNIT_EXPECT_EQ`` to mark the test as failed and continue +execution. In some cases, it is unsafe to continue. We can use the +``KUNIT_ASSERT`` variant to exit on failure. -* Hardware may not be deterministic, so a test that always passes or fails - when run under UML may not always do so on real hardware. -* Hardware and VM environments may not be hermetic. KUnit tries its best to - provide a hermetic environment to run tests; however, it cannot manage state - that it doesn't know about outside of the kernel. Consequently, tests that - may be hermetic on UML may not be hermetic on other architectures. -* Some features and tooling may not be supported outside of UML. -* Hardware and VMs are slower than UML. +.. code-block:: c -None of these are reasons not to run your KUnit tests on real hardware; they are -only things to be aware of when doing so. + void example_test_user_alloc_function(struct kunit *test) + { + void *object = alloc_some_object_for_me(); -Currently, the KUnit Wrapper (``tools/testing/kunit/kunit.py``) (aka -kunit_tool) only fully supports running tests inside of UML and QEMU; however, -this is only due to our own time limitations as humans working on KUnit. It is -entirely possible to support other emulators and even actual hardware, but for -now QEMU and UML is what is fully supported within the KUnit Wrapper. Again, to -be clear, this is just the Wrapper. The actualy KUnit tests and the KUnit -library they are written in is fully architecture agnostic and can be used in -virtually any setup, you just won't have the benefit of typing a single command -out of the box and having everything magically work perfectly. + /* Make sure we got a valid pointer back. */ + KUNIT_ASSERT_NOT_ERR_OR_NULL(test, object); + do_something_with_object(object); + } -Again, all core KUnit framework features are fully supported on all -architectures, and using them is straightforward: Most popular architectures -are supported directly in the KUnit Wrapper via QEMU. Currently, supported -architectures on QEMU include: +Allocating Memory +----------------- -* i386 -* x86_64 -* arm -* arm64 -* alpha -* powerpc -* riscv -* s390 -* sparc +Where you might use ``kzalloc``, you can instead use ``kunit_kzalloc`` as KUnit +will then ensure that the memory is freed once the test completes. -In order to run KUnit tests on one of these architectures via QEMU with the -KUnit wrapper, all you need to do is specify the flags ``--arch`` and -``--cross_compile`` when invoking the KUnit Wrapper. For example, we could run -the default KUnit tests on ARM in the following manner (assuming we have an ARM -toolchain installed): +This is useful because it lets us use the ``KUNIT_ASSERT_EQ`` macros to exit +early from a test without having to worry about remembering to call ``kfree``. +For example: -.. code-block:: bash +.. code-block:: c - tools/testing/kunit/kunit.py run --timeout=60 --jobs=12 --arch=arm --cross_compile=arm-linux-gnueabihf- + void example_test_allocation(struct kunit *test) + { + char *buffer = kunit_kzalloc(test, 16, GFP_KERNEL); + /* Ensure allocation succeeded. */ + KUNIT_ASSERT_NOT_ERR_OR_NULL(test, buffer); -Alternatively, if you want to run your tests on real hardware or in some other -emulation environment, all you need to do is to take your kunitconfig, your -Kconfig options for the tests you would like to run, and merge them into -whatever config your are using for your platform. That's it! + KUNIT_ASSERT_STREQ(test, buffer, ""); + } -For example, let's say you have the following kunitconfig: -.. code-block:: none +Testing Static Functions +------------------------ - CONFIG_KUNIT=y - CONFIG_KUNIT_EXAMPLE_TEST=y +If we do not want to expose functions or variables for testing, one option is to +conditionally ``#include`` the test file at the end of your .c file. For +example: -If you wanted to run this test on an x86 VM, you might add the following config -options to your ``.config``: +.. code-block:: c -.. code-block:: none + /* In my_file.c */ - CONFIG_KUNIT=y - CONFIG_KUNIT_EXAMPLE_TEST=y - CONFIG_SERIAL_8250=y - CONFIG_SERIAL_8250_CONSOLE=y + static int do_interesting_thing(); -All these new options do is enable support for a common serial console needed -for logging. + #ifdef CONFIG_MY_KUNIT_TEST + #include "my_kunit_test.c" + #endif -Next, you could build a kernel with these tests as follows: +Injecting Test-Only Code +------------------------ +Similar to as shown above, we can add test-specific logic. For example: -.. code-block:: bash +.. code-block:: c - make ARCH=x86 olddefconfig - make ARCH=x86 + /* In my_file.h */ -Once you have built a kernel, you could run it on QEMU as follows: + #ifdef CONFIG_MY_KUNIT_TEST + /* Defined in my_kunit_test.c */ + void test_only_hook(void); + #else + void test_only_hook(void) { } + #endif -.. code-block:: bash +This test-only code can be made more useful by accessing the current ``kunit_test`` +as shown in next section: *Accessing The Current Test*. - qemu-system-x86_64 -enable-kvm \ - -m 1024 \ - -kernel arch/x86_64/boot/bzImage \ - -append 'console=ttyS0' \ - --nographic +Accessing The Current Test +-------------------------- -Interspersed in the kernel logs you might see the following: +In some cases, we need to call test-only code from outside the test file. +For example, see example in section *Injecting Test-Only Code* or if +we are providing a fake implementation of an ops struct. Using +``kunit_test`` field in ``task_struct``, we can access it via +``current->kunit_test``. -.. code-block:: none +The example below includes how to implement "mocking": - TAP version 14 - # Subtest: example - 1..1 - # example_simple_test: initializing - ok 1 - example_simple_test - ok 1 - example +.. code-block:: c -Congratulations, you just ran a KUnit test on the x86 architecture! + #include <linux/sched.h> /* for current */ -In a similar manner, kunit and kunit tests can also be built as modules, -so if you wanted to run tests in this way you might add the following config -options to your ``.config``: + struct test_data { + int foo_result; + int want_foo_called_with; + }; -.. code-block:: none + static int fake_foo(int arg) + { + struct kunit *test = current->kunit_test; + struct test_data *test_data = test->priv; - CONFIG_KUNIT=m - CONFIG_KUNIT_EXAMPLE_TEST=m + KUNIT_EXPECT_EQ(test, test_data->want_foo_called_with, arg); + return test_data->foo_result; + } -Once the kernel is built and installed, a simple + static void example_simple_test(struct kunit *test) + { + /* Assume priv (private, a member used to pass test data from + * the init function) is allocated in the suite's .init */ + struct test_data *test_data = test->priv; -.. code-block:: bash + test_data->foo_result = 42; + test_data->want_foo_called_with = 1; - modprobe example-test + /* In a real test, we'd probably pass a pointer to fake_foo somewhere + * like an ops struct, etc. instead of calling it directly. */ + KUNIT_EXPECT_EQ(test, fake_foo(1), 42); + } -...will run the tests. +In this example, we are using the ``priv`` member of ``struct kunit`` as a way +of passing data to the test from the init function. In general ``priv`` is +pointer that can be used for any user data. This is preferred over static +variables, as it avoids concurrency issues. -.. note:: - Note that you should make sure your test depends on ``KUNIT=y`` in Kconfig - if the test does not support module build. Otherwise, it will trigger - compile errors if ``CONFIG_KUNIT`` is ``m``. +Had we wanted something more flexible, we could have used a named ``kunit_resource``. +Each test can have multiple resources which have string names providing the same +flexibility as a ``priv`` member, but also, for example, allowing helper +functions to create resources without conflicting with each other. It is also +possible to define a clean up function for each resource, making it easy to +avoid resource leaks. For more information, see Documentation/dev-tools/kunit/api/test.rst. -Writing new tests for other architectures ------------------------------------------ +Failing The Current Test +------------------------ -The first thing you must do is ask yourself whether it is necessary to write a -KUnit test for a specific architecture, and then whether it is necessary to -write that test for a particular piece of hardware. In general, writing a test -that depends on having access to a particular piece of hardware or software (not -included in the Linux source repo) should be avoided at all costs. +If we want to fail the current test, we can use ``kunit_fail_current_test(fmt, args...)`` +which is defined in ``<kunit/test-bug.h>`` and does not require pulling in ``<kunit/test.h>``. +For example, we have an option to enable some extra debug checks on some data +structures as shown below: -Even if you only ever plan on running your KUnit test on your hardware -configuration, other people may want to run your tests and may not have access -to your hardware. If you write your test to run on UML, then anyone can run your -tests without knowing anything about your particular setup, and you can still -run your tests on your hardware setup just by compiling for your architecture. +.. code-block:: c -.. important:: - Always prefer tests that run on UML to tests that only run under a particular - architecture, and always prefer tests that run under QEMU or another easy - (and monetarily free) to obtain software environment to a specific piece of - hardware. - -Nevertheless, there are still valid reasons to write an architecture or hardware -specific test: for example, you might want to test some code that really belongs -in ``arch/some-arch/*``. Even so, try your best to write the test so that it -does not depend on physical hardware: if some of your test cases don't need the -hardware, only require the hardware for tests that actually need it. - -Now that you have narrowed down exactly what bits are hardware specific, the -actual procedure for writing and running the tests is pretty much the same as -writing normal KUnit tests. One special caveat is that you have to reset -hardware state in between test cases; if this is not possible, you may only be -able to run one test case per invocation. + #include <kunit/test-bug.h> -.. TODO(brendanhiggins@google.com): Add an actual example of an architecture- - dependent KUnit test. + #ifdef CONFIG_EXTRA_DEBUG_CHECKS + static void validate_my_data(struct data *data) + { + if (is_valid(data)) + return; -KUnit debugfs representation -============================ -When kunit test suites are initialized, they create an associated directory -in ``/sys/kernel/debug/kunit/<test-suite>``. The directory contains one file + kunit_fail_current_test("data %p is invalid", data); -- results: "cat results" displays results of each test case and the results - of the entire suite for the last test run. + /* Normal, non-KUnit, error reporting code here. */ + } + #else + static void my_debug_function(void) { } + #endif -The debugfs representation is primarily of use when kunit test suites are -run in a native environment, either as modules or builtin. Having a way -to display results like this is valuable as otherwise results can be -intermixed with other events in dmesg output. The maximum size of each -results file is KUNIT_LOG_SIZE bytes (defined in ``include/kunit/test.h``). diff --git a/Documentation/devicetree/bindings/arm/apple.yaml b/Documentation/devicetree/bindings/arm/apple.yaml index 1e772c85206c..8d93e8a6cc18 100644 --- a/Documentation/devicetree/bindings/arm/apple.yaml +++ b/Documentation/devicetree/bindings/arm/apple.yaml @@ -12,12 +12,19 @@ maintainers: description: | ARM platforms using SoCs designed by Apple Inc., branded "Apple Silicon". - This currently includes devices based on the "M1" SoC, starting with the - three Mac models released in late 2020: + This currently includes devices based on the "M1" SoC: - Mac mini (M1, 2020) - MacBook Pro (13-inch, M1, 2020) - MacBook Air (M1, 2020) + - iMac (24-inch, M1, 2021) + + And devices based on the "M1 Pro" and "M1 Max" SoCs: + + - MacBook Pro (14-inch, M1 Pro, 2021) + - MacBook Pro (14-inch, M1 Max, 2021) + - MacBook Pro (16-inch, M1 Pro, 2021) + - MacBook Pro (16-inch, M1 Max, 2021) The compatible property should follow this format: @@ -56,8 +63,24 @@ properties: - apple,j274 # Mac mini (M1, 2020) - apple,j293 # MacBook Pro (13-inch, M1, 2020) - apple,j313 # MacBook Air (M1, 2020) + - apple,j456 # iMac (24-inch, 4x USB-C, M1, 2021) + - apple,j457 # iMac (24-inch, 2x USB-C, M1, 2021) - const: apple,t8103 - const: apple,arm-platform + - description: Apple M1 Pro SoC based platforms + items: + - enum: + - apple,j314s # MacBook Pro (14-inch, M1 Pro, 2021) + - apple,j316s # MacBook Pro (16-inch, M1 Pro, 2021) + - const: apple,t6000 + - const: apple,arm-platform + - description: Apple M1 Max SoC based platforms + items: + - enum: + - apple,j314c # MacBook Pro (14-inch, M1 Max, 2021) + - apple,j316c # MacBook Pro (16-inch, M1 Max, 2021) + - const: apple,t6001 + - const: apple,arm-platform additionalProperties: true diff --git a/Documentation/devicetree/bindings/arm/apple/apple,pmgr.yaml b/Documentation/devicetree/bindings/arm/apple/apple,pmgr.yaml new file mode 100644 index 000000000000..b6b5d3a912b3 --- /dev/null +++ b/Documentation/devicetree/bindings/arm/apple/apple,pmgr.yaml @@ -0,0 +1,134 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/arm/apple/apple,pmgr.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Apple SoC Power Manager (PMGR) + +maintainers: + - Hector Martin <marcan@marcan.st> + +description: | + Apple SoCs include PMGR blocks responsible for power management, + which can control various clocks, resets, power states, and + performance features. This node represents the PMGR as a syscon, + with sub-nodes representing individual features. + +properties: + $nodename: + pattern: "^power-management@[0-9a-f]+$" + + compatible: + items: + - enum: + - apple,t8103-pmgr + - apple,t6000-pmgr + - const: apple,pmgr + - const: syscon + - const: simple-mfd + + reg: + maxItems: 1 + + "#address-cells": + const: 1 + + "#size-cells": + const: 1 + +patternProperties: + "power-controller@[0-9a-f]+$": + description: + The individual power management domains within this controller + type: object + $ref: /power/apple,pmgr-pwrstate.yaml# + +required: + - compatible + - reg + +additionalProperties: false + +examples: + - | + soc { + #address-cells = <2>; + #size-cells = <2>; + + power-management@23b700000 { + compatible = "apple,t8103-pmgr", "apple,pmgr", "syscon", "simple-mfd"; + #address-cells = <1>; + #size-cells = <1>; + reg = <0x2 0x3b700000 0x0 0x14000>; + + ps_sio: power-controller@1c0 { + compatible = "apple,t8103-pmgr-pwrstate", "apple,pmgr-pwrstate"; + reg = <0x1c0 8>; + #power-domain-cells = <0>; + #reset-cells = <0>; + label = "sio"; + apple,always-on; + }; + + ps_uart_p: power-controller@220 { + compatible = "apple,t8103-pmgr-pwrstate", "apple,pmgr-pwrstate"; + reg = <0x220 8>; + #power-domain-cells = <0>; + #reset-cells = <0>; + label = "uart_p"; + power-domains = <&ps_sio>; + }; + + ps_uart0: power-controller@270 { + compatible = "apple,t8103-pmgr-pwrstate", "apple,pmgr-pwrstate"; + reg = <0x270 8>; + #power-domain-cells = <0>; + #reset-cells = <0>; + label = "uart0"; + power-domains = <&ps_uart_p>; + }; + }; + + power-management@23d280000 { + compatible = "apple,t8103-pmgr", "apple,pmgr", "syscon", "simple-mfd"; + #address-cells = <1>; + #size-cells = <1>; + reg = <0x2 0x3d280000 0x0 0xc000>; + + ps_aop_filter: power-controller@4000 { + compatible = "apple,t8103-pmgr-pwrstate", "apple,pmgr-pwrstate"; + reg = <0x4000 8>; + #power-domain-cells = <0>; + #reset-cells = <0>; + label = "aop_filter"; + }; + + ps_aop_base: power-controller@4010 { + compatible = "apple,t8103-pmgr-pwrstate", "apple,pmgr-pwrstate"; + reg = <0x4010 8>; + #power-domain-cells = <0>; + #reset-cells = <0>; + label = "aop_base"; + power-domains = <&ps_aop_filter>; + }; + + ps_aop_shim: power-controller@4038 { + compatible = "apple,t8103-pmgr-pwrstate", "apple,pmgr-pwrstate"; + reg = <0x4038 8>; + #power-domain-cells = <0>; + #reset-cells = <0>; + label = "aop_shim"; + power-domains = <&ps_aop_base>; + }; + + ps_aop_uart0: power-controller@4048 { + compatible = "apple,t8103-pmgr-pwrstate", "apple,pmgr-pwrstate"; + reg = <0x4048 8>; + #power-domain-cells = <0>; + #reset-cells = <0>; + label = "aop_uart0"; + power-domains = <&ps_aop_shim>; + }; + }; + }; diff --git a/Documentation/devicetree/bindings/arm/aspeed/aspeed,sbc.yaml b/Documentation/devicetree/bindings/arm/aspeed/aspeed,sbc.yaml new file mode 100644 index 000000000000..c72aab706484 --- /dev/null +++ b/Documentation/devicetree/bindings/arm/aspeed/aspeed,sbc.yaml @@ -0,0 +1,37 @@ +# SPDX-License-Identifier: (GPL-2.0-or-later OR BSD-2-Clause) +# Copyright 2021 Joel Stanley, IBM Corp. +%YAML 1.2 +--- +$id: "http://devicetree.org/schemas/arm/aspeed/aspeed,sbc.yaml#" +$schema: "http://devicetree.org/meta-schemas/core.yaml#" + +title: ASPEED Secure Boot Controller + +maintainers: + - Joel Stanley <joel@jms.id.au> + - Andrew Jeffery <andrew@aj.id.au> + +description: | + The ASPEED SoCs have a register bank for interacting with the secure boot + controller. + +properties: + compatible: + items: + - const: aspeed,ast2600-sbc + + reg: + maxItems: 1 + +required: + - compatible + - reg + +additionalProperties: false + +examples: + - | + sbc: secure-boot-controller@1e6f2000 { + compatible = "aspeed,ast2600-sbc"; + reg = <0x1e6f2000 0x1000>; + }; diff --git a/Documentation/devicetree/bindings/arm/bcm/brcm,bcm4908.yaml b/Documentation/devicetree/bindings/arm/bcm/brcm,bcm4908.yaml index 2cd4e4a32278..9b745531ff04 100644 --- a/Documentation/devicetree/bindings/arm/bcm/brcm,bcm4908.yaml +++ b/Documentation/devicetree/bindings/arm/bcm/brcm,bcm4908.yaml @@ -29,6 +29,7 @@ properties: items: - enum: - asus,gt-ac5300 + - netgear,raxe500 - const: brcm,bcm4908 - description: BCM49408 based boards diff --git a/Documentation/devicetree/bindings/arm/cpus.yaml b/Documentation/devicetree/bindings/arm/cpus.yaml index f2ab6423b4af..dfa28e3525cb 100644 --- a/Documentation/devicetree/bindings/arm/cpus.yaml +++ b/Documentation/devicetree/bindings/arm/cpus.yaml @@ -174,6 +174,7 @@ properties: - qcom,kryo560 - qcom,kryo570 - qcom,kryo685 + - qcom,kryo780 - qcom,scorpion enable-method: diff --git a/Documentation/devicetree/bindings/arm/firmware/linaro,optee-tz.yaml b/Documentation/devicetree/bindings/arm/firmware/linaro,optee-tz.yaml index c24047c1fdd5..9a426110a14a 100644 --- a/Documentation/devicetree/bindings/arm/firmware/linaro,optee-tz.yaml +++ b/Documentation/devicetree/bindings/arm/firmware/linaro,optee-tz.yaml @@ -24,6 +24,12 @@ properties: compatible: const: linaro,optee-tz + interrupts: + maxItems: 1 + description: | + This interrupt which is used to signal an event by the secure world + software is expected to be edge-triggered. + method: enum: [smc, hvc] description: | @@ -42,10 +48,12 @@ additionalProperties: false examples: - | + #include <dt-bindings/interrupt-controller/arm-gic.h> firmware { optee { compatible = "linaro,optee-tz"; method = "smc"; + interrupts = <GIC_SPI 187 IRQ_TYPE_EDGE_RISING>; }; }; diff --git a/Documentation/devicetree/bindings/arm/fsl.yaml b/Documentation/devicetree/bindings/arm/fsl.yaml index 0b595b26061f..97f6eebad76a 100644 --- a/Documentation/devicetree/bindings/arm/fsl.yaml +++ b/Documentation/devicetree/bindings/arm/fsl.yaml @@ -240,6 +240,7 @@ properties: - uniwest,imx6q-evi # Uniwest Evi - variscite,dt6customboard - wand,imx6q-wandboard # Wandboard i.MX6 Quad Board + - ysoft,imx6q-yapp4-crux # i.MX6 Quad Y Soft IOTA Crux board - zealz,imx6q-gk802 # Zealz GK802 - zii,imx6q-zii-rdu2 # ZII RDU2 Board - const: fsl,imx6q @@ -323,6 +324,20 @@ properties: - const: toradex,apalis_imx6q - const: fsl,imx6q + - description: TQ-Systems TQMa6Q SoM (variant A) on MBa6x + items: + - const: tq,imx6q-mba6x-a + - const: tq,mba6a # Expected by bootloader, to be removed in the future + - const: tq,imx6q-tqma6q-a + - const: fsl,imx6q + + - description: TQ-Systems TQMa6Q SoM (variant B) on MBa6x + items: + - const: tq,imx6q-mba6x-b + - const: tq,mba6b # Expected by bootloader, to be removed in the future + - const: tq,imx6q-tqma6q-b + - const: fsl,imx6q + - description: i.MX6QP based Boards items: - enum: @@ -334,6 +349,7 @@ properties: - kvg,vicutp # Kverneland UT1P board - prt,prtwd3 # Protonic WD3 board - wand,imx6qp-wandboard # Wandboard i.MX6 QuadPlus Board + - ysoft,imx6qp-yapp4-crux-plus # i.MX6 Quad Plus Y Soft IOTA Crux+ board - zii,imx6qp-zii-rdu2 # ZII RDU2+ Board - const: fsl,imx6qp @@ -344,6 +360,13 @@ properties: - const: phytec,imx6qdl-pcm058 # PHYTEC phyCORE-i.MX6 - const: fsl,imx6qp + - description: TQ-Systems TQMa6QP SoM on MBa6x + items: + - const: tq,imx6qp-mba6x-b + - const: tq,mba6b # Expected by bootloader, to be removed in the future + - const: tq,imx6qp-tqma6qp-b + - const: fsl,imx6qp + - description: i.MX6DL based Boards items: - enum: @@ -482,6 +505,20 @@ properties: - const: dh,imx6s-dhcom-som - const: fsl,imx6dl + - description: TQ-Systems TQMa6DL SoM (variant A) on MBa6x + items: + - const: tq,imx6dl-mba6x-a + - const: tq,mba6a # Expected by bootloader, to be removed in the future + - const: tq,imx6dl-tqma6dl-a + - const: fsl,imx6dl + + - description: TQ-Systems TQMa6DL SoM (variant B) on MBa6x + items: + - const: tq,imx6dl-mba6x-b + - const: tq,mba6b # Expected by bootloader, to be removed in the future + - const: tq,imx6dl-tqma6dl-b + - const: fsl,imx6dl + - description: i.MX6SL based Boards items: - enum: @@ -580,6 +617,7 @@ properties: items: - enum: - fsl,imx6ull-14x14-evk # i.MX6 UltraLiteLite 14x14 EVK Board + - joz,jozacp # JOZ Access Point - kontron,imx6ull-n6411-som # Kontron N6411 SOM - myir,imx6ull-mys-6ulx-eval # MYiR Tech iMX6ULL Evaluation Board - toradex,colibri-imx6ull # Colibri iMX6ULL Modules @@ -632,6 +670,7 @@ properties: - description: i.MX6ULZ based Boards items: - enum: + - bsh,imx6ulz-bsh-smm-m2 # i.MX6 ULZ BSH SystemMaster - fsl,imx6ulz-14x14-evk # i.MX6 ULZ 14x14 EVK Board - const: fsl,imx6ull # This seems odd. Should be last? - const: fsl,imx6ulz @@ -754,10 +793,23 @@ properties: - const: variscite,var-som-mx8mm - const: fsl,imx8mm + - description: + TQMa8MxML is a series of SOM featuring NXP i.MX8MM system-on-chip + variants. It is designed to be soldered on different carrier boards. + All variants (TQMa8M[Q,D,S][L]ML) use the same device tree, hence only + one compatible is needed. + items: + - enum: + - tq,imx8mm-tqma8mqml-mba8mx # TQ-Systems GmbH i.MX8MM TQMa8MQML SOM on MBa8Mx + - const: tq,imx8mm-tqma8mqml # TQ-Systems GmbH i.MX8MM TQMa8MQML SOM + - const: fsl,imx8mm + - description: i.MX8MN based Boards items: - enum: - beacon,imx8mn-beacon-kit # i.MX8MN Beacon Development Kit + - bsh,imx8mn-bsh-smm-s2 # i.MX8MN BSH SystemMaster S2 + - bsh,imx8mn-bsh-smm-s2pro # i.MX8MN BSH SystemMaster S2 PRO - fsl,imx8mn-ddr4-evk # i.MX8MN DDR4 EVK Board - fsl,imx8mn-evk # i.MX8MN LPDDR4 EVK Board - gw,imx8mn-gw7902 # i.MX8MM Gateworks Board @@ -769,6 +821,17 @@ properties: - const: variscite,var-som-mx8mn - const: fsl,imx8mn + - description: + TQMa8MxNL is a series of SOM featuring NXP i.MX8MN system-on-chip + variants. It is designed to be soldered on different carrier boards. + All variants (TQMa8M[Q,D,S][L]NL) use the same device tree, hence only + one compatible is needed. + items: + - enum: + - tq,imx8mn-tqma8mqnl-mba8mx # TQ-Systems GmbH i.MX8MN TQMa8MQNL SOM on MBa8Mx + - const: tq,imx8mn-tqma8mqnl # TQ-Systems GmbH i.MX8MN TQMa8MQNL SOM + - const: fsl,imx8mn + - description: i.MX8MP based Boards items: - enum: @@ -805,6 +868,15 @@ properties: - const: purism,librem5 - const: fsl,imx8mq + - description: + TQMa8Mx is a series of SOM featuring NXP i.MX8MQ system-on-chip + variants. It is designed to be clicked on different carrier boards. + items: + - enum: + - tq,imx8mq-tqma8mq-mba8mx # TQ-Systems GmbH i.MX8MQ TQMa8Mx SOM on MBa8Mx + - const: tq,imx8mq-tqma8mq # TQ-Systems GmbH i.MX8MQ TQMa8Mx SOM + - const: fsl,imx8mq + - description: Zodiac Inflight Innovations Ultra Boards items: - enum: @@ -834,6 +906,12 @@ properties: - const: toradex,colibri-imx8x - const: fsl,imx8qxp + - description: i.MX8ULP based Boards + items: + - enum: + - fsl,imx8ulp-evk # i.MX8ULP EVK Board + - const: fsl,imx8ulp + - description: Freescale Vybrid Platform Device Tree Bindings diff --git a/Documentation/devicetree/bindings/arm/mediatek.yaml b/Documentation/devicetree/bindings/arm/mediatek.yaml index 0fa55497b96f..0ffe1acf1344 100644 --- a/Documentation/devicetree/bindings/arm/mediatek.yaml +++ b/Documentation/devicetree/bindings/arm/mediatek.yaml @@ -79,6 +79,14 @@ properties: - const: mediatek,mt7629 - items: - enum: + - mediatek,mt7986a-rfb + - const: mediatek,mt7986a + - items: + - enum: + - mediatek,mt7986b-rfb + - const: mediatek,mt7986b + - items: + - enum: - mediatek,mt8127-moose - const: mediatek,mt8127 - items: @@ -134,6 +142,10 @@ properties: - google,krane-sku176 - const: google,krane - const: mediatek,mt8183 + - description: Google Cozmo (Acer Chromebook 314) + items: + - const: google,cozmo + - const: mediatek,mt8183 - description: Google Damu (ASUS Chromebook Flip CM3) items: - const: google,damu @@ -143,7 +155,9 @@ properties: - enum: - google,fennel-sku0 - google,fennel-sku1 + - google,fennel-sku2 - google,fennel-sku6 + - google,fennel-sku7 - const: google,fennel - const: mediatek,mt8183 - description: Google Juniper (Acer Chromebook Spin 311) / Kenzo (Acer Chromebook 311) @@ -159,6 +173,12 @@ properties: - const: google,kakadu-rev2 - const: google,kakadu - const: mediatek,mt8183 + - description: Google Kakadu (ASUS Chromebook Detachable CM3) + items: + - const: google,kakadu-rev3-sku22 + - const: google,kakadu-rev2-sku22 + - const: google,kakadu + - const: mediatek,mt8183 - description: Google Kappa (HP Chromebook 11a) items: - const: google,kappa diff --git a/Documentation/devicetree/bindings/arm/msm/qcom,llcc.yaml b/Documentation/devicetree/bindings/arm/msm/qcom,llcc.yaml index 62fcbd883392..03882aac8d2d 100644 --- a/Documentation/devicetree/bindings/arm/msm/qcom,llcc.yaml +++ b/Documentation/devicetree/bindings/arm/msm/qcom,llcc.yaml @@ -24,6 +24,7 @@ properties: - qcom,sc7180-llcc - qcom,sc7280-llcc - qcom,sdm845-llcc + - qcom,sm6350-llcc - qcom,sm8150-llcc - qcom,sm8250-llcc @@ -44,7 +45,6 @@ required: - compatible - reg - reg-names - - interrupts additionalProperties: false diff --git a/Documentation/devicetree/bindings/arm/qcom.yaml b/Documentation/devicetree/bindings/arm/qcom.yaml index c8808e0f9e64..370aab274cd1 100644 --- a/Documentation/devicetree/bindings/arm/qcom.yaml +++ b/Documentation/devicetree/bindings/arm/qcom.yaml @@ -48,8 +48,10 @@ description: | sdx65 sm7225 sm8150 + sdx65 sm8250 sm8350 + sm8450 The 'board' element must be one of the following strings: @@ -201,8 +203,10 @@ properties: - items: - enum: + - qcom,sc7280-crd - qcom,sc7280-idp - qcom,sc7280-idp2 + - google,hoglin - google,piglin - google,senor - const: qcom,sc7280 @@ -226,6 +230,11 @@ properties: - items: - enum: + - qcom,sdx65-mtp + - const: qcom,sdx65 + + - items: + - enum: - qcom,ipq6018-cp01 - qcom,ipq6018-cp01-c1 - const: qcom,ipq6018 @@ -257,6 +266,11 @@ properties: - qcom,sm8350-mtp - const: qcom,sm8350 + - items: + - enum: + - qcom,sm8450-qrd + - const: qcom,sm8450 + additionalProperties: true ... diff --git a/Documentation/devicetree/bindings/arm/renesas.yaml b/Documentation/devicetree/bindings/arm/renesas.yaml index 517206507801..6a9350ee690b 100644 --- a/Documentation/devicetree/bindings/arm/renesas.yaml +++ b/Documentation/devicetree/bindings/arm/renesas.yaml @@ -315,6 +315,18 @@ properties: - const: renesas,falcon-cpu - const: renesas,r8a779a0 + - description: R-Car S4-8 (R8A779F0) + items: + - enum: + - renesas,spider-cpu # Spider CPU board (RTP8A779F0ASKB0SC2S) + - const: renesas,r8a779f0 + + - items: + - enum: + - renesas,spider-breakout # Spider BreakOut board (RTP8A779F0ASKB0SB0S) + - const: renesas,spider-cpu + - const: renesas,r8a779f0 + - description: R-Car H3e (R8A779M0) items: - enum: diff --git a/Documentation/devicetree/bindings/arm/samsung/samsung-boards.yaml b/Documentation/devicetree/bindings/arm/samsung/samsung-boards.yaml index ef6dc14be4b5..052cd94113d4 100644 --- a/Documentation/devicetree/bindings/arm/samsung/samsung-boards.yaml +++ b/Documentation/devicetree/bindings/arm/samsung/samsung-boards.yaml @@ -199,6 +199,18 @@ properties: - samsung,exynos7-espresso # Samsung Exynos7 Espresso - const: samsung,exynos7 + - description: Exynos7885 based boards + items: + - enum: + - samsung,jackpotlte # Samsung Galaxy A8 (2018) + - const: samsung,exynos7885 + + - description: Exynos850 based boards + items: + - enum: + - winlink,e850-96 # WinLink E850-96 + - const: samsung,exynos850 + - description: Exynos Auto v9 based boards items: - enum: diff --git a/Documentation/devicetree/bindings/arm/stm32/stm32.yaml b/Documentation/devicetree/bindings/arm/stm32/stm32.yaml index bcaf7be3ab37..b07720ea9611 100644 --- a/Documentation/devicetree/bindings/arm/stm32/stm32.yaml +++ b/Documentation/devicetree/bindings/arm/stm32/stm32.yaml @@ -77,6 +77,7 @@ properties: items: - enum: - engicam,icore-stm32mp1-ctouch2 # STM32MP1 Engicam i.Core STM32MP1 C.TOUCH 2.0 + - engicam,icore-stm32mp1-ctouch2-of10 # STM32MP1 Engicam i.Core STM32MP1 C.TOUCH 2.0 10.1" OF - engicam,icore-stm32mp1-edimm2.2 # STM32MP1 Engicam i.Core STM32MP1 EDIMM2.2 Starter Kit - const: engicam,icore-stm32mp1 # STM32MP1 Engicam i.Core STM32MP1 SoM - const: st,stm32mp157 diff --git a/Documentation/devicetree/bindings/arm/sunxi.yaml b/Documentation/devicetree/bindings/arm/sunxi.yaml index 889128acf49a..c8a3102c0fde 100644 --- a/Documentation/devicetree/bindings/arm/sunxi.yaml +++ b/Documentation/devicetree/bindings/arm/sunxi.yaml @@ -808,6 +808,11 @@ properties: - const: oranth,tanix-tx6 - const: allwinner,sun50i-h6 + - description: Tanix TX6 mini + items: + - const: oranth,tanix-tx6-mini + - const: allwinner,sun50i-h6 + - description: TBS A711 Tablet items: - const: tbs-biometrics,a711 diff --git a/Documentation/devicetree/bindings/arm/sunxi/allwinner,sun4i-a10-mbus.yaml b/Documentation/devicetree/bindings/arm/sunxi/allwinner,sun4i-a10-mbus.yaml index 29c9961ee2d8..8eee312c2e6f 100644 --- a/Documentation/devicetree/bindings/arm/sunxi/allwinner,sun4i-a10-mbus.yaml +++ b/Documentation/devicetree/bindings/arm/sunxi/allwinner,sun4i-a10-mbus.yaml @@ -32,12 +32,38 @@ properties: - allwinner,sun8i-h3-mbus - allwinner,sun8i-r40-mbus - allwinner,sun50i-a64-mbus + - allwinner,sun50i-h5-mbus reg: - maxItems: 1 + minItems: 1 + items: + - description: MBUS interconnect/bandwidth limit/PMU registers + - description: DRAM controller/PHY registers + + reg-names: + minItems: 1 + items: + - const: mbus + - const: dram clocks: + minItems: 1 + items: + - description: MBUS interconnect module clock + - description: DRAM controller/PHY module clock + - description: Register bus clock, shared by MBUS and DRAM + + clock-names: + minItems: 1 + items: + - const: mbus + - const: dram + - const: bus + + interrupts: maxItems: 1 + description: + MBUS PMU activity interrupt. dma-ranges: description: @@ -54,13 +80,55 @@ required: - clocks - dma-ranges +if: + properties: + compatible: + contains: + enum: + - allwinner,sun8i-h3-mbus + - allwinner,sun50i-a64-mbus + - allwinner,sun50i-h5-mbus + +then: + properties: + reg: + minItems: 2 + + reg-names: + minItems: 2 + + clocks: + minItems: 3 + + clock-names: + minItems: 3 + + required: + - reg-names + - clock-names + +else: + properties: + reg: + maxItems: 1 + + reg-names: + maxItems: 1 + + clocks: + maxItems: 1 + + clock-names: + maxItems: 1 + additionalProperties: false examples: - | - #include <dt-bindings/clock/sun5i-ccu.h> + #include <dt-bindings/clock/sun50i-a64-ccu.h> + #include <dt-bindings/interrupt-controller/arm-gic.h> - mbus: dram-controller@1c01000 { + dram-controller@1c01000 { compatible = "allwinner,sun5i-a13-mbus"; reg = <0x01c01000 0x1000>; clocks = <&ccu CLK_MBUS>; @@ -70,4 +138,21 @@ examples: #interconnect-cells = <1>; }; + - | + dram-controller@1c62000 { + compatible = "allwinner,sun50i-a64-mbus"; + reg = <0x01c62000 0x1000>, + <0x01c63000 0x1000>; + reg-names = "mbus", "dram"; + clocks = <&ccu CLK_MBUS>, + <&ccu CLK_DRAM>, + <&ccu CLK_BUS_DRAM>; + clock-names = "mbus", "dram", "bus"; + interrupts = <GIC_SPI 69 IRQ_TYPE_LEVEL_HIGH>; + #address-cells = <1>; + #size-cells = <1>; + dma-ranges = <0x00000000 0x40000000 0xc0000000>; + #interconnect-cells = <1>; + }; + ... diff --git a/Documentation/devicetree/bindings/arm/tegra.yaml b/Documentation/devicetree/bindings/arm/tegra.yaml index d79d36ac0c44..49841ca272ee 100644 --- a/Documentation/devicetree/bindings/arm/tegra.yaml +++ b/Documentation/devicetree/bindings/arm/tegra.yaml @@ -37,6 +37,9 @@ properties: - const: toradex,colibri_t20 - const: nvidia,tegra20 - items: + - const: asus,tf101 + - const: nvidia,tegra20 + - items: - const: acer,picasso - const: nvidia,tegra20 - items: @@ -50,6 +53,18 @@ properties: - const: nvidia,cardhu - const: nvidia,tegra30 - items: + - const: asus,tf201 + - const: nvidia,tegra30 + - items: + - const: asus,tf300t + - const: nvidia,tegra30 + - items: + - const: asus,tf300tg + - const: nvidia,tegra30 + - items: + - const: asus,tf700t + - const: nvidia,tegra30 + - items: - const: toradex,apalis_t30-eval - const: toradex,apalis_t30 - const: nvidia,tegra30 @@ -75,7 +90,11 @@ properties: - const: ouya,ouya - const: nvidia,tegra30 - items: + - const: pegatron,chagall + - const: nvidia,tegra30 + - items: - enum: + - asus,tf701t - nvidia,dalmore - nvidia,roth - nvidia,tn7 @@ -108,14 +127,17 @@ properties: - nvidia,p2571 - nvidia,p2894-0050-a08 - const: nvidia,tegra210 - - items: - - enum: - - nvidia,p2771-0000 - - nvidia,p3509-0000+p3636-0001 + - description: Jetson TX2 Developer Kit + items: + - const: nvidia,p2771-0000 - const: nvidia,tegra186 - - items: - - enum: - - nvidia,p2972-0000 + - description: Jetson TX2 NX Developer Kit + items: + - const: nvidia,p3509-0000+p3636-0001 + - const: nvidia,tegra186 + - description: Jetson AGX Xavier Developer Kit + items: + - const: nvidia,p2972-0000 - const: nvidia,tegra194 - description: Jetson Xavier NX items: @@ -134,8 +156,16 @@ properties: - const: nvidia,p3509-0000+p3668-0001 - const: nvidia,tegra194 - items: - - enum: - - nvidia,tegra234-vdk + - const: nvidia,tegra234-vdk + - const: nvidia,tegra234 + - description: Jetson AGX Orin + items: + - const: nvidia,p3701-0000 + - const: nvidia,tegra234 + - description: Jetson AGX Orin Developer Kit + items: + - const: nvidia,p3737-0000+p3701-0000 + - const: nvidia,p3701-0000 - const: nvidia,tegra234 additionalProperties: true diff --git a/Documentation/devicetree/bindings/arm/tegra/nvidia,tegra186-pmc.txt b/Documentation/devicetree/bindings/arm/tegra/nvidia,tegra186-pmc.txt deleted file mode 100644 index 576462fae27f..000000000000 --- a/Documentation/devicetree/bindings/arm/tegra/nvidia,tegra186-pmc.txt +++ /dev/null @@ -1,133 +0,0 @@ -NVIDIA Tegra Power Management Controller (PMC) - -Required properties: -- compatible: Should contain one of the following: - - "nvidia,tegra186-pmc": for Tegra186 - - "nvidia,tegra194-pmc": for Tegra194 - - "nvidia,tegra234-pmc": for Tegra234 -- reg: Must contain an (offset, length) pair of the register set for each - entry in reg-names. -- reg-names: Must include the following entries: - - "pmc" - - "wake" - - "aotag" - - "scratch" - - "misc" (Only for Tegra194 and later) - -Optional properties: -- nvidia,invert-interrupt: If present, inverts the PMU interrupt signal. -- interrupt-controller: Identifies the node as an interrupt controller. -- #interrupt-cells: Specifies the number of cells needed to encode an - interrupt source. The value must be 2. - -Example: - -SoC DTSI: - - pmc@c3600000 { - compatible = "nvidia,tegra186-pmc"; - reg = <0 0x0c360000 0 0x10000>, - <0 0x0c370000 0 0x10000>, - <0 0x0c380000 0 0x10000>, - <0 0x0c390000 0 0x10000>; - reg-names = "pmc", "wake", "aotag", "scratch"; - }; - -Board DTS: - - pmc@c360000 { - nvidia,invert-interrupt; - }; - -== Pad Control == - -On Tegra SoCs a pad is a set of pins which are configured as a group. -The pin grouping is a fixed attribute of the hardware. The PMC can be -used to set pad power state and signaling voltage. A pad can be either -in active or power down mode. The support for power state and signaling -voltage configuration varies depending on the pad in question. 3.3 V and -1.8 V signaling voltages are supported on pins where software -controllable signaling voltage switching is available. - -Pad configurations are described with pin configuration nodes which -are placed under the pmc node and they are referred to by the pinctrl -client properties. For more information see -Documentation/devicetree/bindings/pinctrl/pinctrl-bindings.txt. - -The following pads are present on Tegra186: -csia csib dsi mipi-bias -pex-clk-bias pex-clk3 pex-clk2 pex-clk1 -usb0 usb1 usb2 usb-bias -uart audio hsic dbg -hdmi-dp0 hdmi-dp1 pex-cntrl sdmmc2-hv -sdmmc4 cam dsib dsic -dsid csic csid csie -dsif spi ufs dmic-hv -edp sdmmc1-hv sdmmc3-hv conn -audio-hv ao-hv - -Required pin configuration properties: - - pins: A list of strings, each of which contains the name of a pad - to be configured. - -Optional pin configuration properties: - - low-power-enable: Configure the pad into power down mode - - low-power-disable: Configure the pad into active mode - - power-source: Must contain either TEGRA_IO_PAD_VOLTAGE_1V8 or - TEGRA_IO_PAD_VOLTAGE_3V3 to select between signaling voltages. - The values are defined in - include/dt-bindings/pinctrl/pinctrl-tegra-io-pad.h. - -Note: The power state can be configured on all of the above pads except - for ao-hv. Following pads have software configurable signaling - voltages: sdmmc2-hv, dmic-hv, sdmmc1-hv, sdmmc3-hv, audio-hv, - ao-hv. - -Pad configuration state example: - pmc: pmc@7000e400 { - compatible = "nvidia,tegra186-pmc"; - reg = <0 0x0c360000 0 0x10000>, - <0 0x0c370000 0 0x10000>, - <0 0x0c380000 0 0x10000>, - <0 0x0c390000 0 0x10000>; - reg-names = "pmc", "wake", "aotag", "scratch"; - - ... - - sdmmc1_3v3: sdmmc1-3v3 { - pins = "sdmmc1-hv"; - power-source = <TEGRA_IO_PAD_VOLTAGE_3V3>; - }; - - sdmmc1_1v8: sdmmc1-1v8 { - pins = "sdmmc1-hv"; - power-source = <TEGRA_IO_PAD_VOLTAGE_1V8>; - }; - - hdmi_off: hdmi-off { - pins = "hdmi"; - low-power-enable; - } - - hdmi_on: hdmi-on { - pins = "hdmi"; - low-power-disable; - } - }; - -Pinctrl client example: - sdmmc1: sdhci@3400000 { - ... - pinctrl-names = "sdmmc-3v3", "sdmmc-1v8"; - pinctrl-0 = <&sdmmc1_3v3>; - pinctrl-1 = <&sdmmc1_1v8>; - }; - - ... - - sor0: sor@15540000 { - ... - pinctrl-0 = <&hdmi_off>; - pinctrl-1 = <&hdmi_on>; - pinctrl-names = "hdmi-on", "hdmi-off"; - }; diff --git a/Documentation/devicetree/bindings/arm/tegra/nvidia,tegra186-pmc.yaml b/Documentation/devicetree/bindings/arm/tegra/nvidia,tegra186-pmc.yaml new file mode 100644 index 000000000000..0faa403f68c8 --- /dev/null +++ b/Documentation/devicetree/bindings/arm/tegra/nvidia,tegra186-pmc.yaml @@ -0,0 +1,198 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/arm/tegra/nvidia,tegra186-pmc.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: NVIDIA Tegra Power Management Controller (PMC) + +maintainers: + - Thierry Reding <thierry.reding@gmail.com> + - Jon Hunter <jonathanh@nvidia.com> + +properties: + compatible: + enum: + - nvidia,tegra186-pmc + - nvidia,tegra194-pmc + - nvidia,tegra234-pmc + + reg: + minItems: 4 + maxItems: 5 + + reg-names: + minItems: 4 + items: + - const: pmc + - const: wake + - const: aotag + - const: scratch + - const: misc + + interrupt-controller: true + + "#interrupt-cells": + description: Specifies the number of cells needed to encode an + interrupt source. The value must be 2. + const: 2 + + nvidia,invert-interrupt: + description: If present, inverts the PMU interrupt signal. + $ref: /schemas/types.yaml#/definitions/flag + +if: + properties: + compatible: + contains: + const: nvidia,tegra186-pmc +then: + properties: + reg: + maxItems: 4 + + reg-names: + maxItems: 4 +else: + properties: + reg: + minItems: 5 + + reg-names: + minItems: 5 + +patternProperties: + "^[a-z0-9]+-[a-z0-9]+$": + if: + type: object + then: + description: | + These are pad configuration nodes. On Tegra SoCs a pad is a set of + pins which are configured as a group. The pin grouping is a fixed + attribute of the hardware. The PMC can be used to set pad power + state and signaling voltage. A pad can be either in active or + power down mode. The support for power state and signaling voltage + configuration varies depending on the pad in question. 3.3 V and + 1.8 V signaling voltages are supported on pins where software + controllable signaling voltage switching is available. + + Pad configurations are described with pin configuration nodes + which are placed under the pmc node and they are referred to by + the pinctrl client properties. For more information see + + Documentation/devicetree/bindings/pinctrl/pinctrl-bindings.txt + + The following pads are present on Tegra186: + + csia, csib, dsi, mipi-bias, pex-clk-bias, pex-clk3, pex-clk2, + pex-clk1, usb0, usb1, usb2, usb-bias, uart, audio, hsic, dbg, + hdmi-dp0, hdmi-dp1, pex-cntrl, sdmmc2-hv, sdmmc4, cam, dsib, + dsic, dsid, csic, csid, csie, dsif, spi, ufs, dmic-hv, edp, + sdmmc1-hv, sdmmc3-hv, conn, audio-hv, ao-hv + + The following pads are present on Tegra194: + + csia, csib, mipi-bias, pex-clk-bias, pex-clk3, pex-clk2, + pex-clk1, eqos, pex-clk-2-bias, pex-clk-2, dap3, dap5, uart, + pwr-ctl, soc-gpio53, audio, gp-pwm2, gp-pwm3, soc-gpio12, + soc-gpio13, soc-gpio10, uart4, uart5, dbg, hdmi-dp3, hdmi-dp2, + hdmi-dp0, hdmi-dp1, pex-cntrl, pex-ctl2, pex-l0-rst, + pex-l1-rst, sdmmc4, pex-l5-rst, cam, csic, csid, csie, csif, + spi, ufs, csig, csih, edp, sdmmc1-hv, sdmmc3-hv, conn, + audio-hv, ao-hv + + properties: + pins: + $ref: /schemas/types.yaml#/definitions/string + description: Must contain the name of the pad(s) to be + configured. + + low-power-enable: + description: Configure the pad into power down mode. + $ref: /schemas/types.yaml#/definitions/flag + + low-power-disable: + description: Configure the pad into active mode. + $ref: /schemas/types.yaml#/definitions/flag + + power-source: + $ref: /schemas/types.yaml#/definitions/uint32 + description: | + Must contain either TEGRA_IO_PAD_VOLTAGE_1V8 or + TEGRA_IO_PAD_VOLTAGE_3V3 to select between signalling + voltages. + + The values are defined in + + include/dt-bindings/pinctrl/pinctrl-tegra-io-pad.h + + The power state can be configured on all of the above pads + except for ao-hv. Following pads have software configurable + signaling voltages: sdmmc2-hv, dmic-hv, sdmmc1-hv, sdmmc3-hv, + audio-hv, ao-hv. + + phandle: true + + required: + - pins + + additionalProperties: false + +required: + - compatible + - reg + - reg-names + +additionalProperties: false + +dependencies: + interrupt-controller: ['#interrupt-cells'] + "#interrupt-cells": + required: + - interrupt-controller + +examples: + - | + #include <dt-bindings/clock/tegra186-clock.h> + #include <dt-bindings/interrupt-controller/arm-gic.h> + #include <dt-bindings/pinctrl/pinctrl-tegra-io-pad.h> + #include <dt-bindings/memory/tegra186-mc.h> + #include <dt-bindings/reset/tegra186-reset.h> + + pmc@c3600000 { + compatible = "nvidia,tegra186-pmc"; + reg = <0x0c360000 0x10000>, + <0x0c370000 0x10000>, + <0x0c380000 0x10000>, + <0x0c390000 0x10000>; + reg-names = "pmc", "wake", "aotag", "scratch"; + nvidia,invert-interrupt; + + sdmmc1_3v3: sdmmc1-3v3 { + pins = "sdmmc1-hv"; + power-source = <TEGRA_IO_PAD_VOLTAGE_3V3>; + }; + + sdmmc1_1v8: sdmmc1-1v8 { + pins = "sdmmc1-hv"; + power-source = <TEGRA_IO_PAD_VOLTAGE_1V8>; + }; + }; + + sdmmc1: mmc@3400000 { + compatible = "nvidia,tegra186-sdhci"; + reg = <0x03400000 0x10000>; + interrupts = <GIC_SPI 62 IRQ_TYPE_LEVEL_HIGH>; + clocks = <&bpmp TEGRA186_CLK_SDMMC1>, + <&bpmp TEGRA186_CLK_SDMMC_LEGACY_TM>; + clock-names = "sdhci", "tmclk"; + resets = <&bpmp TEGRA186_RESET_SDMMC1>; + reset-names = "sdhci"; + interconnects = <&mc TEGRA186_MEMORY_CLIENT_SDMMCRA &emc>, + <&mc TEGRA186_MEMORY_CLIENT_SDMMCWA &emc>; + interconnect-names = "dma-mem", "write"; + iommus = <&smmu TEGRA186_SID_SDMMC1>; + pinctrl-names = "sdmmc-3v3", "sdmmc-1v8"; + pinctrl-0 = <&sdmmc1_3v3>; + pinctrl-1 = <&sdmmc1_1v8>; + }; diff --git a/Documentation/devicetree/bindings/arm/ti/k3.yaml b/Documentation/devicetree/bindings/arm/ti/k3.yaml index cf327230fc0e..b03c10fa2e7a 100644 --- a/Documentation/devicetree/bindings/arm/ti/k3.yaml +++ b/Documentation/devicetree/bindings/arm/ti/k3.yaml @@ -53,6 +53,12 @@ properties: - ti,am642-sk - const: ti,am642 + - description: K3 J721s2 SoC + items: + - enum: + - ti,j721s2-evm + - const: ti,j721s2 + additionalProperties: true ... diff --git a/Documentation/devicetree/bindings/bus/fsl,spba-bus.yaml b/Documentation/devicetree/bindings/bus/fsl,spba-bus.yaml new file mode 100644 index 000000000000..d42dbb0bbc2e --- /dev/null +++ b/Documentation/devicetree/bindings/bus/fsl,spba-bus.yaml @@ -0,0 +1,68 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/bus/fsl,spba-bus.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Shared Peripherals Bus Interface + +maintainers: + - Shawn Guo <shawnguo@kernel.org> + +description: | + A simple bus enabling access to shared peripherals. + + The "spba-bus" follows the "simple-bus" set of properties, as + specified in the Devicetree Specification. It is an extension of + "simple-bus" because the SDMA controller uses this compatible flag to + determine which peripherals are available to it and the range over which + the SDMA can access. There are no special clocks for the bus, because + the SDMA controller itself has its interrupt and clock assignments. + +select: + properties: + compatible: + contains: + const: fsl,spba-bus + required: + - compatible + +properties: + $nodename: + pattern: "^spba-bus(@[0-9a-f]+)?$" + + compatible: + items: + - const: fsl,spba-bus + - const: simple-bus + + '#address-cells': + enum: [ 1, 2 ] + + '#size-cells': + enum: [ 1, 2 ] + + reg: + maxItems: 1 + + ranges: true + +required: + - compatible + - '#address-cells' + - '#size-cells' + - reg + - ranges + +additionalProperties: + type: object + +examples: + - | + spba-bus@30000000 { + compatible = "fsl,spba-bus", "simple-bus"; + #address-cells = <1>; + #size-cells = <1>; + reg = <0x30000000 0x100000>; + ranges; + }; diff --git a/Documentation/devicetree/bindings/bus/imx-weim.txt b/Documentation/devicetree/bindings/bus/imx-weim.txt index 1b1d1c5c21ea..e7f502070d77 100644 --- a/Documentation/devicetree/bindings/bus/imx-weim.txt +++ b/Documentation/devicetree/bindings/bus/imx-weim.txt @@ -48,6 +48,11 @@ Optional properties: devices, the presence of this property indicates that the weim bus should operate in Burst Clock Mode. + - fsl,continuous-burst-clk Make Burst Clock to output continuous clock. + Without this option Burst Clock will output clock + only when necessary. This takes effect only if + "fsl,burst-clk-enable" is set. + Timing property for child nodes. It is mandatory, not optional. - fsl,weim-cs-timing: The timing array, contains timing values for the diff --git a/Documentation/devicetree/bindings/clock/nvidia,tegra20-car.yaml b/Documentation/devicetree/bindings/clock/nvidia,tegra20-car.yaml index 459d2a525393..f832abb7f11a 100644 --- a/Documentation/devicetree/bindings/clock/nvidia,tegra20-car.yaml +++ b/Documentation/devicetree/bindings/clock/nvidia,tegra20-car.yaml @@ -42,6 +42,36 @@ properties: "#reset-cells": const: 1 +patternProperties: + "^(sclk)|(pll-[cem])$": + type: object + properties: + compatible: + enum: + - nvidia,tegra20-sclk + - nvidia,tegra30-sclk + - nvidia,tegra30-pllc + - nvidia,tegra30-plle + - nvidia,tegra30-pllm + + operating-points-v2: true + + clocks: + items: + - description: node's clock + + power-domains: + maxItems: 1 + description: phandle to the core SoC power domain + + required: + - compatible + - operating-points-v2 + - clocks + - power-domains + + additionalProperties: false + required: - compatible - reg @@ -59,6 +89,13 @@ examples: reg = <0x60006000 0x1000>; #clock-cells = <1>; #reset-cells = <1>; + + sclk { + compatible = "nvidia,tegra20-sclk"; + operating-points-v2 = <&opp_table>; + clocks = <&tegra_car TEGRA20_CLK_SCLK>; + power-domains = <&domain>; + }; }; usb-controller@c5004000 { diff --git a/Documentation/devicetree/bindings/clock/qcom,gcc-sdx65.yaml b/Documentation/devicetree/bindings/clock/qcom,gcc-sdx65.yaml new file mode 100644 index 000000000000..16c4cdc7b4d6 --- /dev/null +++ b/Documentation/devicetree/bindings/clock/qcom,gcc-sdx65.yaml @@ -0,0 +1,80 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/clock/qcom,gcc-sdx65.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Qualcomm Global Clock & Reset Controller Binding for SDX65 + +maintainers: + - Vamsi krishna Lanka <quic_vamslank@quicinc.com> + +description: | + Qualcomm global clock control module which supports the clocks, resets and + power domains on SDX65 + + See also: + - dt-bindings/clock/qcom,gcc-sdx65.h + +properties: + compatible: + const: qcom,gcc-sdx65 + + reg: + maxItems: 1 + + clocks: + items: + - description: Board XO source + - description: Board active XO source + - description: Sleep clock source + - description: PCIE Pipe clock source + - description: USB3 phy wrapper pipe clock source + - description: PLL test clock source (Optional clock) + minItems: 5 + + clock-names: + items: + - const: bi_tcxo + - const: bi_tcxo_ao + - const: sleep_clk + - const: pcie_pipe_clk + - const: usb3_phy_wrapper_gcc_usb30_pipe_clk + - const: core_bi_pll_test_se # Optional clock + minItems: 5 + + '#clock-cells': + const: 1 + + '#reset-cells': + const: 1 + + '#power-domain-cells': + const: 1 + +required: + - compatible + - reg + - clocks + - clock-names + - '#clock-cells' + - '#reset-cells' + - '#power-domain-cells' + +additionalProperties: false + +examples: + - | + #include <dt-bindings/clock/qcom,rpmh.h> + clock-controller@100000 { + compatible = "qcom,gcc-sdx65"; + reg = <0x100000 0x1f7400>; + clocks = <&rpmhcc RPMH_CXO_CLK>, <&rpmhcc RPMH_CXO_CLK_A>, <&sleep_clk>, + <&pcie_pipe_clk>, <&usb3_phy_wrapper_gcc_usb30_pipe_clk>, <&pll_test_clk>; + clock-names = "bi_tcxo", "bi_tcxo_ao", "sleep_clk", + "pcie_pipe_clk", "usb3_phy_wrapper_gcc_usb30_pipe_clk", "core_bi_pll_test_se"; + #clock-cells = <1>; + #reset-cells = <1>; + #power-domain-cells = <1>; + }; +... diff --git a/Documentation/devicetree/bindings/clock/qcom,gcc-sm8450.yaml b/Documentation/devicetree/bindings/clock/qcom,gcc-sm8450.yaml new file mode 100644 index 000000000000..58d98a766de6 --- /dev/null +++ b/Documentation/devicetree/bindings/clock/qcom,gcc-sm8450.yaml @@ -0,0 +1,85 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/clock/qcom,gcc-sm8450.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Qualcomm Global Clock & Reset Controller Binding for SM8450 + +maintainers: + - Vinod Koul <vkoul@kernel.org> + +description: | + Qualcomm global clock control module which supports the clocks, resets and + power domains on SM8450 + + See also: + - dt-bindings/clock/qcom,gcc-sm8450.h + +properties: + compatible: + const: qcom,gcc-sm8450 + + clocks: + items: + - description: Board XO source + - description: Sleep clock source + - description: PCIE 0 Pipe clock source (Optional clock) + - description: PCIE 1 Pipe clock source (Optional clock) + - description: PCIE 1 Phy Auxillary clock source (Optional clock) + - description: UFS Phy Rx symbol 0 clock source (Optional clock) + - description: UFS Phy Rx symbol 1 clock source (Optional clock) + - description: UFS Phy Tx symbol 0 clock source (Optional clock) + - description: USB3 Phy wrapper pipe clock source (Optional clock) + minItems: 2 + + clock-names: + items: + - const: bi_tcxo + - const: sleep_clk + - const: pcie_0_pipe_clk # Optional clock + - const: pcie_1_pipe_clk # Optional clock + - const: pcie_1_phy_aux_clk # Optional clock + - const: ufs_phy_rx_symbol_0_clk # Optional clock + - const: ufs_phy_rx_symbol_1_clk # Optional clock + - const: ufs_phy_tx_symbol_0_clk # Optional clock + - const: usb3_phy_wrapper_gcc_usb30_pipe_clk # Optional clock + minItems: 2 + + '#clock-cells': + const: 1 + + '#reset-cells': + const: 1 + + '#power-domain-cells': + const: 1 + + reg: + maxItems: 1 + +required: + - compatible + - reg + - clocks + - clock-names + - '#clock-cells' + - '#reset-cells' + - '#power-domain-cells' + +additionalProperties: false + +examples: + - | + #include <dt-bindings/clock/qcom,rpmh.h> + clock-controller@100000 { + compatible = "qcom,gcc-sm8450"; + reg = <0x00100000 0x001f4200>; + clocks = <&rpmhcc RPMH_CXO_CLK>, <&sleep_clk>; + clock-names = "bi_tcxo", "sleep_clk"; + #clock-cells = <1>; + #reset-cells = <1>; + #power-domain-cells = <1>; + }; + +... diff --git a/Documentation/devicetree/bindings/clock/starfive,jh7100-clkgen.yaml b/Documentation/devicetree/bindings/clock/starfive,jh7100-clkgen.yaml new file mode 100644 index 000000000000..12f17b60ecbe --- /dev/null +++ b/Documentation/devicetree/bindings/clock/starfive,jh7100-clkgen.yaml @@ -0,0 +1,56 @@ +# SPDX-License-Identifier: GPL-2.0-only OR BSD-2-Clause +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/clock/starfive,jh7100-clkgen.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: StarFive JH7100 Clock Generator + +maintainers: + - Geert Uytterhoeven <geert@linux-m68k.org> + - Emil Renner Berthing <kernel@esmil.dk> + +properties: + compatible: + const: starfive,jh7100-clkgen + + reg: + maxItems: 1 + + clocks: + items: + - description: Main clock source (25 MHz) + - description: Application-specific clock source (12-27 MHz) + - description: RMII reference clock (50 MHz) + - description: RGMII RX clock (125 MHz) + + clock-names: + items: + - const: osc_sys + - const: osc_aud + - const: gmac_rmii_ref + - const: gmac_gr_mii_rxclk + + '#clock-cells': + const: 1 + description: + See <dt-bindings/clock/starfive-jh7100.h> for valid indices. + +required: + - compatible + - reg + - clocks + - clock-names + - '#clock-cells' + +additionalProperties: false + +examples: + - | + clock-controller@11800000 { + compatible = "starfive,jh7100-clkgen"; + reg = <0x11800000 0x10000>; + clocks = <&osc_sys>, <&osc_aud>, <&gmac_rmii_ref>, <&gmac_gr_mii_rxclk>; + clock-names = "osc_sys", "osc_aud", "gmac_rmii_ref", "gmac_gr_mii_rxclk"; + #clock-cells = <1>; + }; diff --git a/Documentation/devicetree/bindings/crypto/allwinner,sun4i-a10-crypto.yaml b/Documentation/devicetree/bindings/crypto/allwinner,sun4i-a10-crypto.yaml index 0429fb774f10..dedc99e34ebc 100644 --- a/Documentation/devicetree/bindings/crypto/allwinner,sun4i-a10-crypto.yaml +++ b/Documentation/devicetree/bindings/crypto/allwinner,sun4i-a10-crypto.yaml @@ -44,6 +44,16 @@ properties: - const: ahb - const: mod + dmas: + items: + - description: RX DMA Channel + - description: TX DMA Channel + + dma-names: + items: + - const: rx + - const: tx + resets: maxItems: 1 diff --git a/Documentation/devicetree/bindings/display/bridge/analogix,anx7625.yaml b/Documentation/devicetree/bindings/display/bridge/analogix,anx7625.yaml index ab48ab2f4240..1d3e88daca04 100644 --- a/Documentation/devicetree/bindings/display/bridge/analogix,anx7625.yaml +++ b/Documentation/devicetree/bindings/display/bridge/analogix,anx7625.yaml @@ -43,14 +43,70 @@ properties: vdd33-supply: description: Regulator that provides the supply 3.3V power. + analogix,lane0-swing: + $ref: /schemas/types.yaml#/definitions/uint8-array + minItems: 1 + maxItems: 20 + description: + an array of swing register setting for DP tx lane0 PHY. + Registers 0~9 are Swing0_Pre0, Swing1_Pre0, Swing2_Pre0, + Swing3_Pre0, Swing0_Pre1, Swing1_Pre1, Swing2_Pre1, Swing0_Pre2, + Swing1_Pre2, Swing0_Pre3, they are for [Boost control] and + [Swing control] setting. + Registers 0~9, bit 3:0 is [Boost control], these bits control + post cursor manual, increase the [Boost control] to increase + Pre-emphasis value. + Registers 0~9, bit 6:4 is [Swing control], these bits control + swing manual, increase [Swing control] setting to add Vp-p value + for each Swing, Pre. + Registers 10~19 are Swing0_Pre0, Swing1_Pre0, Swing2_Pre0, + Swing3_Pre0, Swing0_Pre1, Swing1_Pre1, Swing2_Pre1, Swing0_Pre2, + Swing1_Pre2, Swing0_Pre3, they are for [R select control] and + [R Termination control] setting. + Registers 10~19, bit 4:0 is [R select control], these bits are + compensation manual, increase it can enhance IO driven strength + and Vp-p. + Registers 10~19, bit 5:6 is [R termination control], these bits + adjust 50ohm impedance of DP tx termination. 00:55 ohm, + 01:50 ohm(default), 10:45 ohm, 11:40 ohm. + + analogix,lane1-swing: + $ref: /schemas/types.yaml#/definitions/uint8-array + minItems: 1 + maxItems: 20 + description: + an array of swing register setting for DP tx lane1 PHY. + DP TX lane1 swing register setting same with lane0 + swing, please refer lane0-swing property description. + + analogix,audio-enable: + type: boolean + description: let the driver enable audio HDMI codec function or not. + ports: $ref: /schemas/graph.yaml#/properties/ports properties: port@0: - $ref: /schemas/graph.yaml#/properties/port + $ref: /schemas/graph.yaml#/$defs/port-base + unevaluatedProperties: false description: - Video port for MIPI DSI input. + MIPI DSI/DPI input. + + properties: + endpoint: + $ref: /schemas/media/video-interfaces.yaml# + type: object + additionalProperties: false + + properties: + remote-endpoint: true + + bus-type: + enum: [1, 5] + default: 1 + + data-lanes: true port@1: $ref: /schemas/graph.yaml#/properties/port @@ -87,6 +143,9 @@ examples: vdd10-supply = <&pp1000_mipibrdg>; vdd18-supply = <&pp1800_mipibrdg>; vdd33-supply = <&pp3300_mipibrdg>; + analogix,audio-enable; + analogix,lane0-swing = /bits/ 8 <0x14 0x54 0x64 0x74>; + analogix,lane1-swing = /bits/ 8 <0x14 0x54 0x64 0x74>; ports { #address-cells = <1>; @@ -96,6 +155,8 @@ examples: reg = <0>; anx7625_in: endpoint { remote-endpoint = <&mipi_dsi>; + bus-type = <5>; + data-lanes = <0 1 2 3>; }; }; diff --git a/Documentation/devicetree/bindings/display/bridge/lvds-codec.yaml b/Documentation/devicetree/bindings/display/bridge/lvds-codec.yaml index 1faae3e323a4..5079c1cc337b 100644 --- a/Documentation/devicetree/bindings/display/bridge/lvds-codec.yaml +++ b/Documentation/devicetree/bindings/display/bridge/lvds-codec.yaml @@ -79,6 +79,14 @@ properties: - port@0 - port@1 + pclk-sample: + description: + Data sampling on rising or falling edge. + enum: + - 0 # Falling edge + - 1 # Rising edge + default: 0 + powerdown-gpios: description: The GPIO used to control the power down line of this device. @@ -86,21 +94,32 @@ properties: power-supply: true -if: - not: - properties: - compatible: - contains: - const: lvds-decoder -then: - properties: - ports: +allOf: + - if: + not: + properties: + compatible: + contains: + const: lvds-decoder + then: properties: - port@0: + ports: properties: - endpoint: + port@0: properties: - data-mapping: false + endpoint: + properties: + data-mapping: false + + - if: + not: + properties: + compatible: + contains: + const: lvds-encoder + then: + properties: + pclk-sample: false required: - compatible diff --git a/Documentation/devicetree/bindings/display/bridge/nxp,ptn3460.yaml b/Documentation/devicetree/bindings/display/bridge/nxp,ptn3460.yaml new file mode 100644 index 000000000000..107dd138e6c6 --- /dev/null +++ b/Documentation/devicetree/bindings/display/bridge/nxp,ptn3460.yaml @@ -0,0 +1,106 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/display/bridge/nxp,ptn3460.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: NXP PTN3460 eDP to LVDS bridge + +maintainers: + - Sean Paul <seanpaul@chromium.org> + +properties: + compatible: + const: nxp,ptn3460 + + reg: + description: I2C address of the bridge + maxItems: 1 + + edid-emulation: + $ref: "/schemas/types.yaml#/definitions/uint32" + description: + The EDID emulation entry to use + Value Resolution Description + 0 1024x768 NXP Generic + 1 1920x1080 NXP Generic + 2 1920x1080 NXP Generic + 3 1600x900 Samsung LTM200KT + 4 1920x1080 Samsung LTM230HT + 5 1366x768 NXP Generic + 6 1600x900 ChiMei M215HGE + enum: [0, 1, 2, 3, 4, 5, 6] + + powerdown-gpios: + description: GPIO connected to the PD_N signal. + maxItems: 1 + + reset-gpios: + description: GPIO connected to the RST_N signal. + maxItems: 1 + + ports: + $ref: /schemas/graph.yaml#/properties/ports + + properties: + port@0: + $ref: /schemas/graph.yaml#/properties/port + description: + Video port for LVDS output + + port@1: + $ref: /schemas/graph.yaml#/properties/port + description: + Video port for eDP input + + required: + - port@0 + - port@1 + +required: + - compatible + - reg + - edid-emulation + - powerdown-gpios + - reset-gpios + - ports + +additionalProperties: false + +examples: + - | + #include <dt-bindings/gpio/gpio.h> + + i2c1 { + #address-cells = <1>; + #size-cells = <0>; + + bridge@20 { + compatible = "nxp,ptn3460"; + reg = <0x20>; + edid-emulation = <5>; + powerdown-gpios = <&gpy2 5 GPIO_ACTIVE_HIGH>; + reset-gpios = <&gpx1 5 GPIO_ACTIVE_LOW>; + + ports { + #address-cells = <1>; + #size-cells = <0>; + + port@0 { + reg = <0>; + bridge_out: endpoint { + remote-endpoint = <&panel_in>; + }; + }; + + port@1 { + reg = <1>; + bridge_in: endpoint { + remote-endpoint = <&dp_out>; + }; + }; + }; + }; + }; + +... diff --git a/Documentation/devicetree/bindings/display/bridge/ptn3460.txt b/Documentation/devicetree/bindings/display/bridge/ptn3460.txt deleted file mode 100644 index 361971ba104d..000000000000 --- a/Documentation/devicetree/bindings/display/bridge/ptn3460.txt +++ /dev/null @@ -1,39 +0,0 @@ -ptn3460 bridge bindings - -Required properties: - - compatible: "nxp,ptn3460" - - reg: i2c address of the bridge - - powerdown-gpio: OF device-tree gpio specification for PD_N pin. - - reset-gpio: OF device-tree gpio specification for RST_N pin. - - edid-emulation: The EDID emulation entry to use - +-------+------------+------------------+ - | Value | Resolution | Description | - | 0 | 1024x768 | NXP Generic | - | 1 | 1920x1080 | NXP Generic | - | 2 | 1920x1080 | NXP Generic | - | 3 | 1600x900 | Samsung LTM200KT | - | 4 | 1920x1080 | Samsung LTM230HT | - | 5 | 1366x768 | NXP Generic | - | 6 | 1600x900 | ChiMei M215HGE | - +-------+------------+------------------+ - - - video interfaces: Device node can contain video interface port - nodes for panel according to [1]. - -[1]: Documentation/devicetree/bindings/media/video-interfaces.txt - -Example: - lvds-bridge@20 { - compatible = "nxp,ptn3460"; - reg = <0x20>; - powerdown-gpio = <&gpy2 5 1 0 0>; - reset-gpio = <&gpx1 5 1 0 0>; - edid-emulation = <5>; - ports { - port@0 { - bridge_out: endpoint { - remote-endpoint = <&panel_in>; - }; - }; - }; - }; diff --git a/Documentation/devicetree/bindings/display/bridge/renesas,dsi-csi2-tx.yaml b/Documentation/devicetree/bindings/display/bridge/renesas,dsi-csi2-tx.yaml new file mode 100644 index 000000000000..afeeb967393d --- /dev/null +++ b/Documentation/devicetree/bindings/display/bridge/renesas,dsi-csi2-tx.yaml @@ -0,0 +1,118 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/display/bridge/renesas,dsi-csi2-tx.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Renesas R-Car MIPI DSI/CSI-2 Encoder + +maintainers: + - Laurent Pinchart <laurent.pinchart+renesas@ideasonboard.com> + +description: | + This binding describes the MIPI DSI/CSI-2 encoder embedded in the Renesas + R-Car V3U SoC. The encoder can operate in either DSI or CSI-2 mode, with up + to four data lanes. + +properties: + compatible: + enum: + - renesas,r8a779a0-dsi-csi2-tx # for V3U + + reg: + maxItems: 1 + + clocks: + items: + - description: Functional clock + - description: DSI (and CSI-2) functional clock + - description: PLL reference clock + + clock-names: + items: + - const: fck + - const: dsi + - const: pll + + power-domains: + maxItems: 1 + + resets: + maxItems: 1 + + ports: + $ref: /schemas/graph.yaml#/properties/ports + + properties: + port@0: + $ref: /schemas/graph.yaml#/properties/port + description: Parallel input port + + port@1: + $ref: /schemas/graph.yaml#/$defs/port-base + unevaluatedProperties: false + description: DSI/CSI-2 output port + + properties: + endpoint: + $ref: /schemas/media/video-interfaces.yaml# + unevaluatedProperties: false + + properties: + data-lanes: + minItems: 1 + maxItems: 4 + + required: + - data-lanes + + required: + - port@0 + - port@1 + +required: + - compatible + - reg + - clocks + - power-domains + - resets + - ports + +additionalProperties: false + +examples: + - | + #include <dt-bindings/clock/r8a779a0-cpg-mssr.h> + #include <dt-bindings/power/r8a779a0-sysc.h> + + dsi0: dsi-encoder@fed80000 { + compatible = "renesas,r8a779a0-dsi-csi2-tx"; + reg = <0xfed80000 0x10000>; + power-domains = <&sysc R8A779A0_PD_ALWAYS_ON>; + clocks = <&cpg CPG_MOD 415>, + <&cpg CPG_CORE R8A779A0_CLK_DSI>, + <&cpg CPG_CORE R8A779A0_CLK_CP>; + clock-names = "fck", "dsi", "pll"; + resets = <&cpg 415>; + + ports { + #address-cells = <1>; + #size-cells = <0>; + + port@0 { + reg = <0>; + dsi0_in: endpoint { + remote-endpoint = <&du_out_dsi0>; + }; + }; + + port@1 { + reg = <1>; + dsi0_out: endpoint { + data-lanes = <1 2>; + remote-endpoint = <&sn65dsi86_in>; + }; + }; + }; + }; +... diff --git a/Documentation/devicetree/bindings/display/bridge/sii9234.txt b/Documentation/devicetree/bindings/display/bridge/sii9234.txt deleted file mode 100644 index a55bf77bd960..000000000000 --- a/Documentation/devicetree/bindings/display/bridge/sii9234.txt +++ /dev/null @@ -1,49 +0,0 @@ -Silicon Image SiI9234 HDMI/MHL bridge bindings - -Required properties: - - compatible : "sil,sii9234". - - reg : I2C address for TPI interface, use 0x39 - - avcc33-supply : MHL/USB Switch Supply Voltage (3.3V) - - iovcc18-supply : I/O Supply Voltage (1.8V) - - avcc12-supply : TMDS Analog Supply Voltage (1.2V) - - cvcc12-supply : Digital Core Supply Voltage (1.2V) - - interrupts: interrupt specifier of INT pin - - reset-gpios: gpio specifier of RESET pin (active low) - - video interfaces: Device node can contain two video interface port - nodes for HDMI encoder and connector according to [1]. - - port@0 - MHL to HDMI - - port@1 - MHL to connector - -[1]: Documentation/devicetree/bindings/media/video-interfaces.txt - - -Example: - sii9234@39 { - compatible = "sil,sii9234"; - reg = <0x39>; - avcc33-supply = <&vcc33mhl>; - iovcc18-supply = <&vcc18mhl>; - avcc12-supply = <&vsil12>; - cvcc12-supply = <&vsil12>; - reset-gpios = <&gpf3 4 GPIO_ACTIVE_LOW>; - interrupt-parent = <&gpf3>; - interrupts = <5 IRQ_TYPE_LEVEL_HIGH>; - - ports { - #address-cells = <1>; - #size-cells = <0>; - - port@0 { - reg = <0>; - mhl_to_hdmi: endpoint { - remote-endpoint = <&hdmi_to_mhl>; - }; - }; - port@1 { - reg = <1>; - mhl_to_connector: endpoint { - remote-endpoint = <&connector_to_mhl>; - }; - }; - }; - }; diff --git a/Documentation/devicetree/bindings/display/bridge/sil,sii9234.yaml b/Documentation/devicetree/bindings/display/bridge/sil,sii9234.yaml new file mode 100644 index 000000000000..f88ddfe4818b --- /dev/null +++ b/Documentation/devicetree/bindings/display/bridge/sil,sii9234.yaml @@ -0,0 +1,110 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/display/bridge/sil,sii9234.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Silicon Image SiI9234 HDMI/MHL bridge + +maintainers: + - Maciej Purski <m.purski@samsung.com> + +properties: + compatible: + const: sil,sii9234 + + reg: + description: I2C address for TPI interface + maxItems: 1 + + avcc12-supply: + description: TMDS Analog Supply Voltage, 1.2V + + avcc33-supply: + description: MHL/USB Switch Supply Voltage, 3.3V + + cvcc12-supply: + description: Digital Core Supply Voltage, 1.2V + + iovcc18-supply: + description: I/O voltage supply, 1.8V + + interrupts: + maxItems: 1 + + reset-gpios: + description: GPIO connected to the reset pin. + maxItems: 1 + + ports: + $ref: /schemas/graph.yaml#/properties/ports + + properties: + port@0: + $ref: /schemas/graph.yaml#/properties/port + description: + Video port for HDMI (encoder) input + + port@1: + $ref: /schemas/graph.yaml#/properties/port + description: + MHL to connector port + + required: + - port@0 + +required: + - compatible + - reg + - avcc12-supply + - avcc33-supply + - cvcc12-supply + - iovcc18-supply + - interrupts + - reset-gpios + - ports + +additionalProperties: false + +examples: + - | + #include <dt-bindings/gpio/gpio.h> + #include <dt-bindings/interrupt-controller/irq.h> + + i2c1 { + #address-cells = <1>; + #size-cells = <0>; + + bridge@39 { + compatible = "sil,sii9234"; + reg = <0x39>; + avcc12-supply = <&vsil12>; + avcc33-supply = <&vcc33mhl>; + cvcc12-supply = <&vsil12>; + iovcc18-supply = <&vcc18mhl>; + interrupt-parent = <&gpf3>; + interrupts = <5 IRQ_TYPE_LEVEL_HIGH>; + reset-gpios = <&gpf3 4 GPIO_ACTIVE_LOW>; + + ports { + #address-cells = <1>; + #size-cells = <0>; + + port@0 { + reg = <0>; + mhl_to_hdmi: endpoint { + remote-endpoint = <&hdmi_to_mhl>; + }; + }; + + port@1 { + reg = <1>; + mhl_to_connector: endpoint { + remote-endpoint = <&connector_to_mhl>; + }; + }; + }; + }; + }; + +... diff --git a/Documentation/devicetree/bindings/display/msm/dp-controller.yaml b/Documentation/devicetree/bindings/display/msm/dp-controller.yaml index 63e585f48789..5457612ab136 100644 --- a/Documentation/devicetree/bindings/display/msm/dp-controller.yaml +++ b/Documentation/devicetree/bindings/display/msm/dp-controller.yaml @@ -17,6 +17,8 @@ properties: compatible: enum: - qcom,sc7180-dp + - qcom,sc7280-dp + - qcom,sc7280-edp - qcom,sc8180x-dp - qcom,sc8180x-edp diff --git a/Documentation/devicetree/bindings/display/msm/edp.txt b/Documentation/devicetree/bindings/display/msm/edp.txt deleted file mode 100644 index eff9daff418c..000000000000 --- a/Documentation/devicetree/bindings/display/msm/edp.txt +++ /dev/null @@ -1,56 +0,0 @@ -Qualcomm Technologies Inc. adreno/snapdragon eDP output - -Required properties: -- compatible: - * "qcom,mdss-edp" -- reg: Physical base address and length of the registers of controller and PLL -- reg-names: The names of register regions. The following regions are required: - * "edp" - * "pll_base" -- interrupts: The interrupt signal from the eDP block. -- power-domains: Should be <&mmcc MDSS_GDSC>. -- clocks: device clocks - See Documentation/devicetree/bindings/clock/clock-bindings.txt for details. -- clock-names: the following clocks are required: - * "core" - * "iface" - * "mdp_core" - * "pixel" - * "link" -- #clock-cells: The value should be 1. -- vdda-supply: phandle to vdda regulator device node -- lvl-vdd-supply: phandle to regulator device node which is used to supply power - to HPD receiving chip -- panel-en-gpios: GPIO pin to supply power to panel. -- panel-hpd-gpios: GPIO pin used for eDP hpd. - - -Example: - mdss_edp: qcom,mdss_edp@fd923400 { - compatible = "qcom,mdss-edp"; - reg-names = - "edp", - "pll_base"; - reg = <0xfd923400 0x700>, - <0xfd923a00 0xd4>; - interrupt-parent = <&mdss_mdp>; - interrupts = <12 0>; - power-domains = <&mmcc MDSS_GDSC>; - clock-names = - "core", - "pixel", - "iface", - "link", - "mdp_core"; - clocks = - <&mmcc MDSS_EDPAUX_CLK>, - <&mmcc MDSS_EDPPIXEL_CLK>, - <&mmcc MDSS_AHB_CLK>, - <&mmcc MDSS_EDPLINK_CLK>, - <&mmcc MDSS_MDP_CLK>; - #clock-cells = <1>; - vdda-supply = <&pma8084_l12>; - lvl-vdd-supply = <&lvl_vreg>; - panel-en-gpios = <&tlmm 137 0>; - panel-hpd-gpios = <&tlmm 103 0>; - }; diff --git a/Documentation/devicetree/bindings/display/panel/boe,bf060y8m-aj0.yaml b/Documentation/devicetree/bindings/display/panel/boe,bf060y8m-aj0.yaml new file mode 100644 index 000000000000..a8f3afa922c8 --- /dev/null +++ b/Documentation/devicetree/bindings/display/panel/boe,bf060y8m-aj0.yaml @@ -0,0 +1,81 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/display/panel/boe,bf060y8m-aj0.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: BOE BF060Y8M-AJ0 5.99" 1080x2160 AMOLED Panel + +maintainers: + - AngeloGioacchino Del Regno <angelogioacchino.delregno@somainline.org> + +description: | + This is a 5.99" 1080x2160 16.7M Color active matrix AMOLED + video mode panel module on MIPI-DSI 4-Lane interface, GGRB + pixel arrangement, 63 micrometers pitch, with an active + area of 68.04 x 136.08 millimeters. + Each pixel is divided into red and green dots, or blue and + green dots, and two pixels share red or blue dots which are + arranged in vertical stripe. + The DriverIC for this panel module is SW43404. + +allOf: + - $ref: panel-common.yaml# + +properties: + compatible: + const: boe,bf060y8m-aj0 + + elvdd-supply: + description: EL Driving positive (VDD) supply (4.40-4.80V) + elvss-supply: + description: EL Driving negative (VSS) supply (-5.00V to -1.40V) + vcc-supply: + description: Core (TSP) voltage supply (2.70-3.60V) + vci-supply: + description: DriverIC Operation supply (2.60-3.60V) + vddio-supply: + description: I/O voltage supply (1.62-1.98V) + + port: true + reg: true + reset-gpios: true + +required: + - compatible + - elvdd-supply + - elvss-supply + - vcc-supply + - vci-supply + - vddio-supply + - reg + - reset-gpios + +additionalProperties: false + +examples: + - | + #include <dt-bindings/gpio/gpio.h> + + dsi { + #address-cells = <1>; + #size-cells = <0>; + panel@0 { + compatible = "boe,bf060y8m-aj0"; + reg = <0>; + + reset-gpios = <&tlmm 94 GPIO_ACTIVE_HIGH>; + + vcc-supply = <&disp_vcc_vreg>; + vddio-supply = <&disp_vddio_vreg>; + vci-supply = <&disp_vci_vreg>; + elvdd-supply = <&disp_elvdd_vreg>; + elvss-supply = <&disp_elvss_vreg>; + + port { + panel_in: endpoint { + remote-endpoint = <&dsi0_out>; + }; + }; + }; + }; diff --git a/Documentation/devicetree/bindings/display/panel/ilitek,ili9163.yaml b/Documentation/devicetree/bindings/display/panel/ilitek,ili9163.yaml new file mode 100644 index 000000000000..7e7a8362b951 --- /dev/null +++ b/Documentation/devicetree/bindings/display/panel/ilitek,ili9163.yaml @@ -0,0 +1,69 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/display/panel/ilitek,ili9163.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Ilitek ILI9163 display panels device tree bindings + +maintainers: + - Daniel Mack <daniel@zonque.org> + +description: + This binding is for display panels using an Ilitek ILI9163 controller in SPI + mode. + +allOf: + - $ref: panel-common.yaml# + +properties: + compatible: + items: + - enum: + - newhaven,1.8-128160EF + - const: ilitek,ili9163 + + spi-max-frequency: + maximum: 32000000 + + dc-gpios: + maxItems: 1 + description: Display data/command selection (D/CX) + + backlight: true + reg: true + reset-gpios: true + rotation: true + +required: + - compatible + - reg + - dc-gpios + - reset-gpios + +additionalProperties: false + +examples: + - | + #include <dt-bindings/gpio/gpio.h> + + backlight: backlight { + compatible = "gpio-backlight"; + gpios = <&gpio 22 GPIO_ACTIVE_HIGH>; + }; + spi { + #address-cells = <1>; + #size-cells = <0>; + + display@0 { + compatible = "newhaven,1.8-128160EF", "ilitek,ili9163"; + reg = <0>; + spi-max-frequency = <32000000>; + dc-gpios = <&gpio0 24 GPIO_ACTIVE_HIGH>; + reset-gpios = <&gpio0 25 GPIO_ACTIVE_HIGH>; + rotation = <180>; + backlight = <&backlight>; + }; + }; + +... diff --git a/Documentation/devicetree/bindings/display/panel/ilitek,ili9881c.yaml b/Documentation/devicetree/bindings/display/panel/ilitek,ili9881c.yaml index b2fcec4f22fd..c5d1df680858 100644 --- a/Documentation/devicetree/bindings/display/panel/ilitek,ili9881c.yaml +++ b/Documentation/devicetree/bindings/display/panel/ilitek,ili9881c.yaml @@ -9,24 +9,28 @@ title: Ilitek ILI9881c based MIPI-DSI panels maintainers: - Maxime Ripard <mripard@kernel.org> +allOf: + - $ref: panel-common.yaml# + properties: compatible: items: - enum: - bananapi,lhr050h41 - feixin,k101-im2byl02 + - wanchanglong,w552946aba - const: ilitek,ili9881c backlight: true power-supply: true reg: true reset-gpios: true + rotation: true required: - compatible - power-supply - reg - - reset-gpios additionalProperties: false diff --git a/Documentation/devicetree/bindings/display/panel/novatek,nt35950.yaml b/Documentation/devicetree/bindings/display/panel/novatek,nt35950.yaml new file mode 100644 index 000000000000..377a05d48a02 --- /dev/null +++ b/Documentation/devicetree/bindings/display/panel/novatek,nt35950.yaml @@ -0,0 +1,106 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/display/panel/novatek,nt35950.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Novatek NT35950-based display panels + +maintainers: + - AngeloGioacchino Del Regno <angelogioacchino.delregno@somainline.org> + +description: | + The nt35950 IC from Novatek is a Driver IC used to drive MIPI-DSI panels, + with Static RAM for content retention in command mode and also supports + video mode with VESA Frame Buffer Compression or Display Stream Compression + on single, or dual dsi port(s). + This DDIC is also capable of upscaling an input image to the panel's native + resolution, for example it can upscale a 1920x1080 input to 3840x2160 with + either bilinear interpolation or pixel duplication. + +allOf: + - $ref: panel-common.yaml# + +properties: + compatible: + items: + - enum: + - sharp,ls055d1sx04 + - const: novatek,nt35950 + description: This indicates the panel manufacturer of the panel + that is in turn using the NT35950 panel driver. The compatible + string determines how the NT35950 panel driver shall be configured + to work with the indicated panel. The novatek,nt35950 compatible shall + always be provided as a fallback. + + reset-gpios: + maxItems: 1 + description: phandle of gpio for reset line - This should be 8mA, gpio + can be configured using mux, pinctrl, pinctrl-names (active high) + + avdd-supply: + description: positive boost supply regulator + avee-supply: + description: negative boost supply regulator + dvdd-supply: + description: regulator that supplies the digital voltage + vddio-supply: + description: regulator that supplies the I/O voltage + + backlight: true + ports: true + reg: true + +required: + - compatible + - reg + - reset-gpios + - avdd-supply + - avee-supply + - dvdd-supply + - vddio-supply + +additionalProperties: false + +examples: + - | + #include <dt-bindings/gpio/gpio.h> + + dsi0 { + #address-cells = <1>; + #size-cells = <0>; + + panel@0 { + compatible = "sharp,ls055d1sx04", "novatek,nt35950"; + reg = <0>; + + backlight = <&pmi8998_wled>; + reset-gpios = <&tlmm 94 GPIO_ACTIVE_HIGH>; + + avdd-supply = <&lab>; + avee-supply = <&ibb>; + dvdd-supply = <&disp_dvdd_vreg>; + vddio-supply = <&vreg_l14a_1p85>; + + ports { + #address-cells = <1>; + #size-cells = <0>; + + port@0 { + reg = <0>; + panel_in0: endpoint { + remote-endpoint = <&dsi0_out>; + }; + }; + + port@1 { + reg = <1>; + panel_in1: endpoint { + remote-endpoint = <&dsi1_out>; + }; + }; + }; + }; + }; + +... diff --git a/Documentation/devicetree/bindings/display/panel/panel-simple-dsi.yaml b/Documentation/devicetree/bindings/display/panel/panel-simple-dsi.yaml index fbd71669248f..2c00813f5d20 100644 --- a/Documentation/devicetree/bindings/display/panel/panel-simple-dsi.yaml +++ b/Documentation/devicetree/bindings/display/panel/panel-simple-dsi.yaml @@ -35,6 +35,8 @@ properties: - boe,tv080wum-nl0 # Innolux P079ZCA 7.85" 768x1024 TFT LCD panel - innolux,p079zca + # JDI FHD_R63452 1080x1920 5.2" IPS LCD Panel + - jdi,fhd-r63452 # Khadas TS050 5" 1080x1920 LCD panel - khadas,ts050 # Kingdisplay KD097D04 9.7" 1536x2048 TFT LCD panel diff --git a/Documentation/devicetree/bindings/display/panel/panel-simple.yaml b/Documentation/devicetree/bindings/display/panel/panel-simple.yaml index f3c9395d23b6..62f5f050c1bc 100644 --- a/Documentation/devicetree/bindings/display/panel/panel-simple.yaml +++ b/Documentation/devicetree/bindings/display/panel/panel-simple.yaml @@ -290,6 +290,8 @@ properties: - starry,kr070pe2t # Starry 12.2" (1920x1200 pixels) TFT LCD panel - starry,kr122ea0sra + # Team Source Display Technology TST043015CMHX 4.3" WQVGA TFT LCD panel + - team-source-display,tst043015cmhx # Tianma Micro-electronics TM070JDHG30 7.0" WXGA TFT LCD panel - tianma,tm070jdhg30 # Tianma Micro-electronics TM070JVHG33 7.0" WXGA TFT LCD panel diff --git a/Documentation/devicetree/bindings/display/panel/sony,tulip-truly-nt35521.yaml b/Documentation/devicetree/bindings/display/panel/sony,tulip-truly-nt35521.yaml new file mode 100644 index 000000000000..967972939598 --- /dev/null +++ b/Documentation/devicetree/bindings/display/panel/sony,tulip-truly-nt35521.yaml @@ -0,0 +1,72 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/display/panel/sony,tulip-truly-nt35521.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Sony Tulip Truly NT35521 5.24" 1280x720 MIPI-DSI Panel + +maintainers: + - Shawn Guo <shawn.guo@linaro.org> + +description: | + The Sony Tulip Truly NT35521 is a 5.24" 1280x720 MIPI-DSI panel, which + can be found no Sony Xperia M4 phone. The panel backlight is managed + through DSI link. + +allOf: + - $ref: panel-common.yaml# + +properties: + compatible: + const: sony,tulip-truly-nt35521 + + reg: true + + positive5-supply: + description: Positive 5V supply + + negative5-supply: + description: Negative 5V supply + + reset-gpios: true + + enable-gpios: true + + port: true + +required: + - compatible + - reg + - positive5-supply + - negative5-supply + - reset-gpios + - enable-gpios + - port + +additionalProperties: false + +examples: + - | + #include <dt-bindings/gpio/gpio.h> + + dsi { + #address-cells = <1>; + #size-cells = <0>; + + panel@0 { + compatible = "sony,tulip-truly-nt35521"; + reg = <0>; + positive5-supply = <&positive5_reg>; + negative5-supply = <&negative5_reg>; + reset-gpios = <&msmgpio 25 GPIO_ACTIVE_LOW>; + enable-gpios = <&msmgpio 10 GPIO_ACTIVE_HIGH>; + + port { + panel_in: endpoint { + remote-endpoint = <&dsi0_out>; + }; + }; + }; + }; +... diff --git a/Documentation/devicetree/bindings/display/sprd/sprd,display-subsystem.yaml b/Documentation/devicetree/bindings/display/sprd/sprd,display-subsystem.yaml new file mode 100644 index 000000000000..3d107e9434be --- /dev/null +++ b/Documentation/devicetree/bindings/display/sprd/sprd,display-subsystem.yaml @@ -0,0 +1,64 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/display/sprd/sprd,display-subsystem.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Unisoc DRM master device + +maintainers: + - Kevin Tang <kevin.tang@unisoc.com> + +description: | + The Unisoc DRM master device is a virtual device needed to list all + DPU devices or other display interface nodes that comprise the + graphics subsystem. + + Unisoc's display pipeline have several components as below description, + multi display controllers and corresponding physical interfaces. + For different display scenarios, dpu0 and dpu1 maybe binding to different + encoder. + + E.g: + dpu0 and dpu1 both binding to DSI for dual mipi-dsi display; + dpu0 binding to DSI for primary display, and dpu1 binding to DP for external display; + + +-----------------------------------------+ + | | + | +---------+ | + +----+ | +----+ +---------+ |DPHY/CPHY| | +------+ + | +----->+dpu0+--->+MIPI|DSI +--->+Combo +----->+Panel0| + |AXI | | +----+ +---------+ +---------+ | +------+ + | | | ^ | + | | | | | + | | | +-----------+ | + | | | | | + |APB | | +--+-+ +-----------+ +---+ | +------+ + | +----->+dpu1+--->+DisplayPort+--->+PHY+--------->+Panel1| + | | | +----+ +-----------+ +---+ | +------+ + +----+ | | + +-----------------------------------------+ + +properties: + compatible: + const: sprd,display-subsystem + + ports: + $ref: /schemas/types.yaml#/definitions/phandle-array + description: + Should contain a list of phandles pointing to display interface port + of DPU devices. + +required: + - compatible + - ports + +additionalProperties: false + +examples: + - | + display-subsystem { + compatible = "sprd,display-subsystem"; + ports = <&dpu_out>; + }; + diff --git a/Documentation/devicetree/bindings/display/sprd/sprd,sharkl3-dpu.yaml b/Documentation/devicetree/bindings/display/sprd/sprd,sharkl3-dpu.yaml new file mode 100644 index 000000000000..4ebea60b8c5b --- /dev/null +++ b/Documentation/devicetree/bindings/display/sprd/sprd,sharkl3-dpu.yaml @@ -0,0 +1,77 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/display/sprd/sprd,sharkl3-dpu.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Unisoc Sharkl3 Display Processor Unit (DPU) + +maintainers: + - Kevin Tang <kevin.tang@unisoc.com> + +description: | + DPU (Display Processor Unit) is the Display Controller for the Unisoc SoCs + which transfers the image data from a video memory buffer to an internal + LCD interface. + +properties: + compatible: + const: sprd,sharkl3-dpu + + reg: + maxItems: 1 + + interrupts: + maxItems: 1 + + clocks: + minItems: 2 + + clock-names: + items: + - const: clk_src_128m + - const: clk_src_384m + + power-domains: + maxItems: 1 + + iommus: + maxItems: 1 + + port: + type: object + description: + A port node with endpoint definitions as defined in + Documentation/devicetree/bindings/media/video-interfaces.txt. + That port should be the output endpoint, usually output to + the associated DSI. + +required: + - compatible + - reg + - interrupts + - clocks + - clock-names + - port + +additionalProperties: false + +examples: + - | + #include <dt-bindings/interrupt-controller/arm-gic.h> + #include <dt-bindings/clock/sprd,sc9860-clk.h> + dpu: dpu@63000000 { + compatible = "sprd,sharkl3-dpu"; + reg = <0x63000000 0x1000>; + interrupts = <GIC_SPI 46 IRQ_TYPE_LEVEL_HIGH>; + clock-names = "clk_src_128m", "clk_src_384m"; + + clocks = <&pll CLK_TWPLL_128M>, + <&pll CLK_TWPLL_384M>; + + dpu_port: port { + dpu_out: endpoint { + remote-endpoint = <&dsi_in>; + }; + }; + }; diff --git a/Documentation/devicetree/bindings/display/sprd/sprd,sharkl3-dsi-host.yaml b/Documentation/devicetree/bindings/display/sprd/sprd,sharkl3-dsi-host.yaml new file mode 100644 index 000000000000..bc5594d18643 --- /dev/null +++ b/Documentation/devicetree/bindings/display/sprd/sprd,sharkl3-dsi-host.yaml @@ -0,0 +1,88 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/display/sprd/sprd,sharkl3-dsi-host.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Unisoc MIPI DSI Controller + +maintainers: + - Kevin Tang <kevin.tang@unisoc.com> + +properties: + compatible: + const: sprd,sharkl3-dsi-host + + reg: + maxItems: 1 + + interrupts: + maxItems: 2 + + clocks: + minItems: 1 + + clock-names: + items: + - const: clk_src_96m + + power-domains: + maxItems: 1 + + ports: + type: object + + properties: + "#address-cells": + const: 1 + + "#size-cells": + const: 0 + + port@0: + type: object + description: + A port node with endpoint definitions as defined in + Documentation/devicetree/bindings/media/video-interfaces.txt. + That port should be the input endpoint, usually coming from + the associated DPU. + + required: + - "#address-cells" + - "#size-cells" + - port@0 + + additionalProperties: false + +required: + - compatible + - reg + - interrupts + - clocks + - clock-names + - ports + +additionalProperties: false + +examples: + - | + #include <dt-bindings/interrupt-controller/arm-gic.h> + #include <dt-bindings/clock/sprd,sc9860-clk.h> + dsi: dsi@63100000 { + compatible = "sprd,sharkl3-dsi-host"; + reg = <0x63100000 0x1000>; + interrupts = <GIC_SPI 48 IRQ_TYPE_LEVEL_HIGH>, + <GIC_SPI 49 IRQ_TYPE_LEVEL_HIGH>; + clock-names = "clk_src_96m"; + clocks = <&pll CLK_TWPLL_96M>; + ports { + #address-cells = <1>; + #size-cells = <0>; + port@0 { + reg = <0>; + dsi_in: endpoint { + remote-endpoint = <&dpu_out>; + }; + }; + }; + }; diff --git a/Documentation/devicetree/bindings/display/tegra/nvidia,tegra20-host1x.txt b/Documentation/devicetree/bindings/display/tegra/nvidia,tegra20-host1x.txt index 8a6d3e1ee306..e61999ce54e9 100644 --- a/Documentation/devicetree/bindings/display/tegra/nvidia,tegra20-host1x.txt +++ b/Documentation/devicetree/bindings/display/tegra/nvidia,tegra20-host1x.txt @@ -19,6 +19,19 @@ Required properties: See ../reset/reset.txt for details. - reset-names: Must include the following entries: - host1x + - mc + +Optional properties: +- operating-points-v2: See ../bindings/opp/opp.txt for details. + - power-domains: Phandle to HEG or core power domain. + +For each opp entry in 'operating-points-v2' table of host1x and its modules: +- opp-supported-hw: One bitfield indicating: + On Tegra20: SoC process ID mask + On Tegra30+: SoC speedo ID mask + + A bitwise AND is performed against the value and if any bit + matches, the OPP gets enabled. Each host1x client module having to perform DMA through the Memory Controller should have the interconnect endpoints set to the Memory Client and External @@ -45,6 +58,8 @@ of the following host1x client modules: - interconnect-names: Must include name of the interconnect path for each interconnect entry. Consult TRM documentation for information about available memory clients, see MEMORY CONTROLLER section. + - operating-points-v2: See ../bindings/opp/opp.txt for details. + - power-domains: Phandle to MPE power domain. - vi: video input @@ -128,6 +143,8 @@ of the following host1x client modules: - interconnect-names: Must include name of the interconnect path for each interconnect entry. Consult TRM documentation for information about available memory clients, see MEMORY CONTROLLER section. + - operating-points-v2: See ../bindings/opp/opp.txt for details. + - power-domains: Phandle to VENC power domain. - epp: encoder pre-processor @@ -147,6 +164,8 @@ of the following host1x client modules: - interconnect-names: Must include name of the interconnect path for each interconnect entry. Consult TRM documentation for information about available memory clients, see MEMORY CONTROLLER section. + - operating-points-v2: See ../bindings/opp/opp.txt for details. + - power-domains: Phandle to HEG or core power domain. - isp: image signal processor @@ -166,6 +185,7 @@ of the following host1x client modules: - interconnect-names: Must include name of the interconnect path for each interconnect entry. Consult TRM documentation for information about available memory clients, see MEMORY CONTROLLER section. + - power-domains: Phandle to VENC or core power domain. - gr2d: 2D graphics engine @@ -179,12 +199,15 @@ of the following host1x client modules: See ../reset/reset.txt for details. - reset-names: Must include the following entries: - 2d + - mc Optional properties: - interconnects: Must contain entry for the GR2D memory clients. - interconnect-names: Must include name of the interconnect path for each interconnect entry. Consult TRM documentation for information about available memory clients, see MEMORY CONTROLLER section. + - operating-points-v2: See ../bindings/opp/opp.txt for details. + - power-domains: Phandle to HEG or core power domain. - gr3d: 3D graphics engine @@ -203,12 +226,16 @@ of the following host1x client modules: - reset-names: Must include the following entries: - 3d - 3d2 (Only required on SoCs with two 3D clocks) + - mc + - mc2 (Only required on SoCs with two 3D clocks) Optional properties: - interconnects: Must contain entry for the GR3D memory clients. - interconnect-names: Must include name of the interconnect path for each interconnect entry. Consult TRM documentation for information about available memory clients, see MEMORY CONTROLLER section. + - operating-points-v2: See ../bindings/opp/opp.txt for details. + - power-domains: Phandles to 3D or core power domain. - dc: display controller @@ -241,6 +268,8 @@ of the following host1x client modules: - interconnect-names: Must include name of the interconnect path for each interconnect entry. Consult TRM documentation for information about available memory clients, see MEMORY CONTROLLER section. + - operating-points-v2: See ../bindings/opp/opp.txt for details. + - power-domains: Phandle to core power domain. - hdmi: High Definition Multimedia Interface @@ -267,6 +296,7 @@ of the following host1x client modules: - nvidia,hpd-gpio: specifies a GPIO used for hotplug detection - nvidia,edid: supplies a binary EDID blob - nvidia,panel: phandle of a display panel + - operating-points-v2: See ../bindings/opp/opp.txt for details. - tvo: TV encoder output @@ -277,6 +307,10 @@ of the following host1x client modules: - clocks: Must contain one entry, for the module clock. See ../clocks/clock-bindings.txt for details. + Optional properties: + - operating-points-v2: See ../bindings/opp/opp.txt for details. + - power-domains: Phandle to core power domain. + - dsi: display serial interface Required properties: @@ -305,6 +339,7 @@ of the following host1x client modules: - nvidia,panel: phandle of a display panel - nvidia,ganged-mode: contains a phandle to a second DSI controller to gang up with in order to support up to 8 data lanes + - operating-points-v2: See ../bindings/opp/opp.txt for details. - sor: serial output resource @@ -408,6 +443,8 @@ Example: clocks = <&tegra_car TEGRA20_CLK_HOST1X>; resets = <&tegra_car 28>; reset-names = "host1x"; + operating-points-v2 = <&dvfs_opp_table>; + power-domains = <&domain>; #address-cells = <1>; #size-cells = <1>; @@ -421,6 +458,8 @@ Example: clocks = <&tegra_car TEGRA20_CLK_MPE>; resets = <&tegra_car 60>; reset-names = "mpe"; + operating-points-v2 = <&dvfs_opp_table>; + power-domains = <&domain>; }; vi@54080000 { @@ -429,6 +468,7 @@ Example: interrupts = <GIC_SPI 69 IRQ_TYPE_LEVEL_HIGH>; assigned-clocks = <&tegra_car TEGRA210_CLK_VI>; assigned-clock-parents = <&tegra_car TEGRA210_CLK_PLL_C4_OUT0>; + operating-points-v2 = <&dvfs_opp_table>; clocks = <&tegra_car TEGRA210_CLK_VI>; power-domains = <&pd_venc>; @@ -510,6 +550,8 @@ Example: clocks = <&tegra_car TEGRA20_CLK_EPP>; resets = <&tegra_car 19>; reset-names = "epp"; + operating-points-v2 = <&dvfs_opp_table>; + power-domains = <&domain>; }; isp { @@ -528,6 +570,8 @@ Example: clocks = <&tegra_car TEGRA20_CLK_GR2D>; resets = <&tegra_car 21>; reset-names = "2d"; + operating-points-v2 = <&dvfs_opp_table>; + power-domains = <&domain>; }; gr3d { @@ -536,6 +580,8 @@ Example: clocks = <&tegra_car TEGRA20_CLK_GR3D>; resets = <&tegra_car 24>; reset-names = "3d"; + operating-points-v2 = <&dvfs_opp_table>; + power-domains = <&domain>; }; dc@54200000 { @@ -547,6 +593,8 @@ Example: clock-names = "dc", "parent"; resets = <&tegra_car 27>; reset-names = "dc"; + operating-points-v2 = <&dvfs_opp_table>; + power-domains = <&domain>; interconnects = <&mc TEGRA20_MC_DISPLAY0A &emc>, <&mc TEGRA20_MC_DISPLAY0B &emc>, @@ -571,6 +619,8 @@ Example: clock-names = "dc", "parent"; resets = <&tegra_car 26>; reset-names = "dc"; + operating-points-v2 = <&dvfs_opp_table>; + power-domains = <&domain>; interconnects = <&mc TEGRA20_MC_DISPLAY0AB &emc>, <&mc TEGRA20_MC_DISPLAY0BB &emc>, @@ -596,6 +646,7 @@ Example: resets = <&tegra_car 51>; reset-names = "hdmi"; status = "disabled"; + operating-points-v2 = <&dvfs_opp_table>; }; tvo { @@ -604,6 +655,7 @@ Example: interrupts = <0 76 0x04>; clocks = <&tegra_car TEGRA20_CLK_TVO>; status = "disabled"; + operating-points-v2 = <&dvfs_opp_table>; }; dsi { @@ -615,6 +667,7 @@ Example: resets = <&tegra_car 48>; reset-names = "dsi"; status = "disabled"; + operating-points-v2 = <&dvfs_opp_table>; }; }; diff --git a/Documentation/devicetree/bindings/firmware/intel,ixp4xx-network-processing-engine.yaml b/Documentation/devicetree/bindings/firmware/intel,ixp4xx-network-processing-engine.yaml index c435c9f369a4..9a785bbaafb7 100644 --- a/Documentation/devicetree/bindings/firmware/intel,ixp4xx-network-processing-engine.yaml +++ b/Documentation/devicetree/bindings/firmware/intel,ixp4xx-network-processing-engine.yaml @@ -37,6 +37,20 @@ properties: should be named with the instance number of the NPE engine used for the crypto engine. + "#address-cells": + const: 1 + + "#size-cells": + const: 0 + +patternProperties: + hss@[0-9]+$: + $ref: /schemas/net/intel,ixp4xx-hss.yaml# + type: object + description: Optional node for the High Speed Serial link (HSS), the + node should be named with the instance number of the NPE engine + used for the HSS. + required: - compatible - reg @@ -45,9 +59,30 @@ additionalProperties: false examples: - | + #include <dt-bindings/gpio/gpio.h> + npe: npe@c8006000 { compatible = "intel,ixp4xx-network-processing-engine"; reg = <0xc8006000 0x1000>, <0xc8007000 0x1000>, <0xc8008000 0x1000>; + #address-cells = <1>; + #size-cells = <0>; + + hss@0 { + compatible = "intel,ixp4xx-hss"; + reg = <0>; + intel,npe-handle = <&npe 0>; + intel,queue-chl-rxtrig = <&qmgr 12>; + intel,queue-chl-txready = <&qmgr 34>; + intel,queue-pkt-rx = <&qmgr 13>; + intel,queue-pkt-tx = <&qmgr 14>, <&qmgr 15>, <&qmgr 16>, <&qmgr 17>; + intel,queue-pkt-rxfree = <&qmgr 18>, <&qmgr 19>, <&qmgr 20>, <&qmgr 21>; + intel,queue-pkt-txdone = <&qmgr 22>; + cts-gpios = <&gpio0 10 GPIO_ACTIVE_LOW>; + rts-gpios = <&gpio0 14 GPIO_ACTIVE_LOW>; + dcd-gpios = <&gpio0 6 GPIO_ACTIVE_LOW>; + dtr-gpios = <&gpio_74 2 GPIO_ACTIVE_LOW>; + clk-internal-gpios = <&gpio_74 0 GPIO_ACTIVE_HIGH>; + }; crypto { compatible = "intel,ixp4xx-crypto"; diff --git a/Documentation/devicetree/bindings/firmware/nvidia,tegra186-bpmp.txt b/Documentation/devicetree/bindings/firmware/nvidia,tegra186-bpmp.txt deleted file mode 100644 index e44a13bc06ed..000000000000 --- a/Documentation/devicetree/bindings/firmware/nvidia,tegra186-bpmp.txt +++ /dev/null @@ -1,107 +0,0 @@ -NVIDIA Tegra Boot and Power Management Processor (BPMP) - -The BPMP is a specific processor in Tegra chip, which is designed for -booting process handling and offloading the power management, clock -management, and reset control tasks from the CPU. The binding document -defines the resources that would be used by the BPMP firmware driver, -which can create the interprocessor communication (IPC) between the CPU -and BPMP. - -Required properties: -- compatible - Array of strings - One of: - - "nvidia,tegra186-bpmp" -- mboxes : The phandle of mailbox controller and the mailbox specifier. -- shmem : List of the phandle of the TX and RX shared memory area that - the IPC between CPU and BPMP is based on. -- #clock-cells : Should be 1. -- #power-domain-cells : Should be 1. -- #reset-cells : Should be 1. - -This node is a mailbox consumer. See the following files for details of -the mailbox subsystem, and the specifiers implemented by the relevant -provider(s): - -- .../mailbox/mailbox.txt -- .../mailbox/nvidia,tegra186-hsp.txt - -This node is a clock, power domain, and reset provider. See the following -files for general documentation of those features, and the specifiers -implemented by this node: - -- .../clock/clock-bindings.txt -- <dt-bindings/clock/tegra186-clock.h> -- ../power/power-domain.yaml -- <dt-bindings/power/tegra186-powergate.h> -- .../reset/reset.txt -- <dt-bindings/reset/tegra186-reset.h> - -The BPMP implements some services which must be represented by separate nodes. -For example, it can provide access to certain I2C controllers, and the I2C -bindings represent each I2C controller as a device tree node. Such nodes should -be nested directly inside the main BPMP node. - -Software can determine whether a child node of the BPMP node represents a device -by checking for a compatible property. Any node with a compatible property -represents a device that can be instantiated. Nodes without a compatible -property may be used to provide configuration information regarding the BPMP -itself, although no such configuration nodes are currently defined by this -binding. - -The BPMP firmware defines no single global name-/numbering-space for such -services. Put another way, the numbering scheme for I2C buses is distinct from -the numbering scheme for any other service the BPMP may provide (e.g. a future -hypothetical SPI bus service). As such, child device nodes will have no reg -property, and the BPMP node will have no #address-cells or #size-cells property. - -The shared memory bindings for BPMP ------------------------------------ - -The shared memory area for the IPC TX and RX between CPU and BPMP are -predefined and work on top of sysram, which is an SRAM inside the chip. - -See ".../sram/sram.txt" for the bindings. - -Example: - -hsp_top0: hsp@3c00000 { - ... - #mbox-cells = <2>; -}; - -sysram@30000000 { - compatible = "nvidia,tegra186-sysram", "mmio-sram"; - reg = <0x0 0x30000000 0x0 0x50000>; - #address-cells = <2>; - #size-cells = <2>; - ranges = <0 0x0 0x0 0x30000000 0x0 0x50000>; - - cpu_bpmp_tx: shmem@4e000 { - compatible = "nvidia,tegra186-bpmp-shmem"; - reg = <0x0 0x4e000 0x0 0x1000>; - label = "cpu-bpmp-tx"; - pool; - }; - - cpu_bpmp_rx: shmem@4f000 { - compatible = "nvidia,tegra186-bpmp-shmem"; - reg = <0x0 0x4f000 0x0 0x1000>; - label = "cpu-bpmp-rx"; - pool; - }; -}; - -bpmp { - compatible = "nvidia,tegra186-bpmp"; - mboxes = <&hsp_top0 TEGRA_HSP_MBOX_TYPE_DB TEGRA_HSP_DB_MASTER_BPMP>; - shmem = <&cpu_bpmp_tx &cpu_bpmp_rx>; - #clock-cells = <1>; - #power-domain-cells = <1>; - #reset-cells = <1>; - - i2c { - compatible = "..."; - ... - }; -}; diff --git a/Documentation/devicetree/bindings/firmware/nvidia,tegra186-bpmp.yaml b/Documentation/devicetree/bindings/firmware/nvidia,tegra186-bpmp.yaml new file mode 100644 index 000000000000..833c07f1685c --- /dev/null +++ b/Documentation/devicetree/bindings/firmware/nvidia,tegra186-bpmp.yaml @@ -0,0 +1,186 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/firmware/nvidia,tegra186-bpmp.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: NVIDIA Tegra Boot and Power Management Processor (BPMP) + +maintainers: + - Thierry Reding <thierry.reding@gmail.com> + - Jon Hunter <jonathanh@nvidia.com> + +description: | + The BPMP is a specific processor in Tegra chip, which is designed for + booting process handling and offloading the power management, clock + management, and reset control tasks from the CPU. The binding document + defines the resources that would be used by the BPMP firmware driver, + which can create the interprocessor communication (IPC) between the + CPU and BPMP. + + This node is a mailbox consumer. See the following files for details + of the mailbox subsystem, and the specifiers implemented by the + relevant provider(s): + + - .../mailbox/mailbox.txt + - .../mailbox/nvidia,tegra186-hsp.yaml + + This node is a clock, power domain, and reset provider. See the + following files for general documentation of those features, and the + specifiers implemented by this node: + + - .../clock/clock-bindings.txt + - <dt-bindings/clock/tegra186-clock.h> + - ../power/power-domain.yaml + - <dt-bindings/power/tegra186-powergate.h> + - .../reset/reset.txt + - <dt-bindings/reset/tegra186-reset.h> + + The BPMP implements some services which must be represented by + separate nodes. For example, it can provide access to certain I2C + controllers, and the I2C bindings represent each I2C controller as a + device tree node. Such nodes should be nested directly inside the main + BPMP node. + + Software can determine whether a child node of the BPMP node + represents a device by checking for a compatible property. Any node + with a compatible property represents a device that can be + instantiated. Nodes without a compatible property may be used to + provide configuration information regarding the BPMP itself, although + no such configuration nodes are currently defined by this binding. + + The BPMP firmware defines no single global name-/numbering-space for + such services. Put another way, the numbering scheme for I2C buses is + distinct from the numbering scheme for any other service the BPMP may + provide (e.g. a future hypothetical SPI bus service). As such, child + device nodes will have no reg property, and the BPMP node will have no + "#address-cells" or "#size-cells" property. + + The shared memory area for the IPC TX and RX between CPU and BPMP are + predefined and work on top of sysram, which is an SRAM inside the + chip. See ".../sram/sram.yaml" for the bindings. + +properties: + compatible: + oneOf: + - items: + - enum: + - nvidia,tegra194-bpmp + - nvidia,tegra234-bpmp + - const: nvidia,tegra186-bpmp + - const: nvidia,tegra186-bpmp + + mboxes: + description: A phandle and channel specifier for the mailbox used to + communicate with the BPMP. + maxItems: 1 + + shmem: + description: List of the phandle to the TX and RX shared memory area + that the IPC between CPU and BPMP is based on. + minItems: 2 + maxItems: 2 + + "#clock-cells": + const: 1 + + "#power-domain-cells": + const: 1 + + "#reset-cells": + const: 1 + + interconnects: + items: + - description: memory read client + - description: memory write client + - description: DMA read client + - description: DMA write client + + interconnect-names: + items: + - const: read + - const: write + - const: dma-mem # dma-read + - const: dma-write + + iommus: + maxItems: 1 + + i2c: + type: object + + thermal: + type: object + +additionalProperties: false + +required: + - compatible + - mboxes + - shmem + - "#clock-cells" + - "#power-domain-cells" + - "#reset-cells" + +examples: + - | + #include <dt-bindings/interrupt-controller/arm-gic.h> + #include <dt-bindings/mailbox/tegra186-hsp.h> + #include <dt-bindings/memory/tegra186-mc.h> + + hsp_top0: hsp@3c00000 { + compatible = "nvidia,tegra186-hsp"; + reg = <0x03c00000 0xa0000>; + interrupts = <GIC_SPI 176 IRQ_TYPE_LEVEL_HIGH>; + interrupt-names = "doorbell"; + #mbox-cells = <2>; + }; + + sram@30000000 { + compatible = "nvidia,tegra186-sysram", "mmio-sram"; + reg = <0x30000000 0x50000>; + #address-cells = <1>; + #size-cells = <1>; + ranges = <0x0 0x30000000 0x50000>; + + cpu_bpmp_tx: sram@4e000 { + reg = <0x4e000 0x1000>; + label = "cpu-bpmp-tx"; + pool; + }; + + cpu_bpmp_rx: sram@4f000 { + reg = <0x4f000 0x1000>; + label = "cpu-bpmp-rx"; + pool; + }; + }; + + bpmp { + compatible = "nvidia,tegra186-bpmp"; + interconnects = <&mc TEGRA186_MEMORY_CLIENT_BPMPR &emc>, + <&mc TEGRA186_MEMORY_CLIENT_BPMPW &emc>, + <&mc TEGRA186_MEMORY_CLIENT_BPMPDMAR &emc>, + <&mc TEGRA186_MEMORY_CLIENT_BPMPDMAW &emc>; + interconnect-names = "read", "write", "dma-mem", "dma-write"; + iommus = <&smmu TEGRA186_SID_BPMP>; + mboxes = <&hsp_top0 TEGRA_HSP_MBOX_TYPE_DB + TEGRA_HSP_DB_MASTER_BPMP>; + shmem = <&cpu_bpmp_tx>, <&cpu_bpmp_rx>; + #clock-cells = <1>; + #power-domain-cells = <1>; + #reset-cells = <1>; + + i2c { + compatible = "nvidia,tegra186-bpmp-i2c"; + nvidia,bpmp-bus-id = <5>; + #address-cells = <1>; + #size-cells = <0>; + }; + + thermal { + compatible = "nvidia,tegra186-bpmp-thermal"; + #thermal-sensor-cells = <1>; + }; + }; diff --git a/Documentation/devicetree/bindings/firmware/qcom,scm.txt b/Documentation/devicetree/bindings/firmware/qcom,scm.txt index d7e3cda8924e..b1cd4ad1889a 100644 --- a/Documentation/devicetree/bindings/firmware/qcom,scm.txt +++ b/Documentation/devicetree/bindings/firmware/qcom,scm.txt @@ -26,9 +26,11 @@ Required properties: * "qcom,scm-sc7280" * "qcom,scm-sdm845" * "qcom,scm-sdx55" + * "qcom,scm-sm6350" * "qcom,scm-sm8150" * "qcom,scm-sm8250" * "qcom,scm-sm8350" + * "qcom,scm-sm8450" and: * "qcom,scm" - clocks: Specifies clocks needed by the SCM interface, if any: diff --git a/Documentation/devicetree/bindings/fuse/nvidia,tegra20-fuse.txt b/Documentation/devicetree/bindings/fuse/nvidia,tegra20-fuse.txt deleted file mode 100644 index b109911669e4..000000000000 --- a/Documentation/devicetree/bindings/fuse/nvidia,tegra20-fuse.txt +++ /dev/null @@ -1,42 +0,0 @@ -NVIDIA Tegra20/Tegra30/Tegr114/Tegra124 fuse block. - -Required properties: -- compatible : For Tegra20, must contain "nvidia,tegra20-efuse". For Tegra30, - must contain "nvidia,tegra30-efuse". For Tegra114, must contain - "nvidia,tegra114-efuse". For Tegra124, must contain "nvidia,tegra124-efuse". - For Tegra132 must contain "nvidia,tegra132-efuse", "nvidia,tegra124-efuse". - For Tegra210 must contain "nvidia,tegra210-efuse". For Tegra186 must contain - "nvidia,tegra186-efuse". For Tegra194 must contain "nvidia,tegra194-efuse". - For Tegra234 must contain "nvidia,tegra234-efuse". - Details: - nvidia,tegra20-efuse: Tegra20 requires using APB DMA to read the fuse data - due to a hardware bug. Tegra20 also lacks certain information which is - available in later generations such as fab code, lot code, wafer id,.. - nvidia,tegra30-efuse, nvidia,tegra114-efuse and nvidia,tegra124-efuse: - The differences between these SoCs are the size of the efuse array, - the location of the spare (OEM programmable) bits and the location of - the speedo data. -- reg: Should contain 1 entry: the entry gives the physical address and length - of the fuse registers. -- clocks: Must contain an entry for each entry in clock-names. - See ../clocks/clock-bindings.txt for details. -- clock-names: Must include the following entries: - - fuse -- resets: Must contain an entry for each entry in reset-names. - See ../reset/reset.txt for details. -- reset-names: Must include the following entries: - - fuse - -Example: - - fuse@7000f800 { - compatible = "nvidia,tegra20-efuse"; - reg = <0x7000f800 0x400>, - <0x70000000 0x400>; - clocks = <&tegra_car TEGRA20_CLK_FUSE>; - clock-names = "fuse"; - resets = <&tegra_car 39>; - reset-names = "fuse"; - }; - - diff --git a/Documentation/devicetree/bindings/fuse/nvidia,tegra20-fuse.yaml b/Documentation/devicetree/bindings/fuse/nvidia,tegra20-fuse.yaml new file mode 100644 index 000000000000..481901269872 --- /dev/null +++ b/Documentation/devicetree/bindings/fuse/nvidia,tegra20-fuse.yaml @@ -0,0 +1,89 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/fuse/nvidia,tegra20-fuse.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: NVIDIA Tegra FUSE block + +maintainers: + - Thierry Reding <thierry.reding@gmail.com> + - Jon Hunter <jonathanh@nvidia.com> + +properties: + compatible: + oneOf: + - enum: + - nvidia,tegra20-efuse + - nvidia,tegra30-efuse + - nvidia,tegra114-efuse + - nvidia,tegra124-efuse + - nvidia,tegra210-efuse + - nvidia,tegra186-efuse + - nvidia,tegra194-efuse + - nvidia,tegra234-efuse + + - items: + - const: nvidia,tegra132-efuse + - const: nvidia,tegra124-efuse + + reg: + maxItems: 1 + + clocks: + maxItems: 1 + + clock-names: + items: + - const: fuse + + resets: + maxItems: 1 + + reset-names: + items: + - const: fuse + + operating-points-v2: + $ref: "/schemas/types.yaml#/definitions/phandle" + + power-domains: + items: + - description: phandle to the core power domain + +additionalProperties: false + +required: + - compatible + - reg + - clocks + - clock-names + +if: + properties: + compatible: + contains: + enum: + - nvidia,tegra20-efuse + - nvidia,tegra30-efuse + - nvidia,tegra114-efuse + - nvidia,tegra124-efuse + - nvidia,tegra132-efuse + - nvidia,tegra210-efuse +then: + required: + - resets + - reset-names + +examples: + - | + #include <dt-bindings/clock/tegra20-car.h> + + fuse@7000f800 { + compatible = "nvidia,tegra20-efuse"; + reg = <0x7000f800 0x400>; + clocks = <&tegra_car TEGRA20_CLK_FUSE>; + clock-names = "fuse"; + resets = <&tegra_car 39>; + reset-names = "fuse"; + }; diff --git a/Documentation/devicetree/bindings/gpio/gpio-samsung.txt b/Documentation/devicetree/bindings/gpio/gpio-samsung.txt deleted file mode 100644 index 5375625e8cd2..000000000000 --- a/Documentation/devicetree/bindings/gpio/gpio-samsung.txt +++ /dev/null @@ -1,41 +0,0 @@ -Samsung Exynos4 GPIO Controller - -Required properties: -- compatible: Compatible property value should be "samsung,exynos4-gpio>". - -- reg: Physical base address of the controller and length of memory mapped - region. - -- #gpio-cells: Should be 4. The syntax of the gpio specifier used by client nodes - should be the following with values derived from the SoC user manual. - <[phandle of the gpio controller node] - [pin number within the gpio controller] - [mux function] - [flags and pull up/down] - [drive strength]> - - Values for gpio specifier: - - Pin number: is a value between 0 to 7. - - Flags and Pull Up/Down: 0 - Pull Up/Down Disabled. - 1 - Pull Down Enabled. - 3 - Pull Up Enabled. - Bit 16 (0x00010000) - Input is active low. - - Drive Strength: 0 - 1x, - 1 - 3x, - 2 - 2x, - 3 - 4x - -- gpio-controller: Specifies that the node is a gpio controller. -- #address-cells: should be 1. -- #size-cells: should be 1. - -Example: - - gpa0: gpio-controller@11400000 { - #address-cells = <1>; - #size-cells = <1>; - compatible = "samsung,exynos4-gpio"; - reg = <0x11400000 0x20>; - #gpio-cells = <4>; - gpio-controller; - }; diff --git a/Documentation/devicetree/bindings/gpio/gpio-vf610.yaml b/Documentation/devicetree/bindings/gpio/gpio-vf610.yaml index 19738a457a58..e1359391d3a4 100644 --- a/Documentation/devicetree/bindings/gpio/gpio-vf610.yaml +++ b/Documentation/devicetree/bindings/gpio/gpio-vf610.yaml @@ -24,6 +24,9 @@ properties: - items: - const: fsl,imx7ulp-gpio - const: fsl,vf610-gpio + - items: + - const: fsl,imx8ulp-gpio + - const: fsl,imx7ulp-gpio reg: description: The first reg tuple represents the PORT module, the second tuple diff --git a/Documentation/devicetree/bindings/gpio/mstar,msc313-gpio.yaml b/Documentation/devicetree/bindings/gpio/mstar,msc313-gpio.yaml index fe1e1c63ffe3..18fe90387b87 100644 --- a/Documentation/devicetree/bindings/gpio/mstar,msc313-gpio.yaml +++ b/Documentation/devicetree/bindings/gpio/mstar,msc313-gpio.yaml @@ -14,7 +14,9 @@ properties: pattern: "^gpio@[0-9a-f]+$" compatible: - const: mstar,msc313-gpio + enum: + - mstar,msc313-gpio + - sstar,ssd20xd-gpio reg: maxItems: 1 diff --git a/Documentation/devicetree/bindings/gpio/nvidia,tegra186-gpio.txt b/Documentation/devicetree/bindings/gpio/nvidia,tegra186-gpio.txt deleted file mode 100644 index adff16c71d21..000000000000 --- a/Documentation/devicetree/bindings/gpio/nvidia,tegra186-gpio.txt +++ /dev/null @@ -1,165 +0,0 @@ -NVIDIA Tegra186 GPIO controllers - -Tegra186 contains two GPIO controllers; a main controller and an "AON" -controller. This binding document applies to both controllers. The register -layouts for the controllers share many similarities, but also some significant -differences. Hence, this document describes closely related but different -bindings and compatible values. - -The Tegra186 GPIO controller allows software to set the IO direction of, and -read/write the value of, numerous GPIO signals. Routing of GPIO signals to -package balls is under the control of a separate pin controller HW block. Two -major sets of registers exist: - -a) Security registers, which allow configuration of allowed access to the GPIO -register set. These registers exist in a single contiguous block of physical -address space. The size of this block, and the security features available, -varies between the different GPIO controllers. - -Access to this set of registers is not necessary in all circumstances. Code -that wishes to configure access to the GPIO registers needs access to these -registers to do so. Code which simply wishes to read or write GPIO data does not -need access to these registers. - -b) GPIO registers, which allow manipulation of the GPIO signals. In some GPIO -controllers, these registers are exposed via multiple "physical aliases" in -address space, each of which access the same underlying state. See the hardware -documentation for rationale. Any particular GPIO client is expected to access -just one of these physical aliases. - -Tegra HW documentation describes a unified naming convention for all GPIOs -implemented by the SoC. Each GPIO is assigned to a port, and a port may control -a number of GPIOs. Thus, each GPIO is named according to an alphabetical port -name and an integer GPIO name within the port. For example, GPIO_PA0, GPIO_PN6, -or GPIO_PCC3. - -The number of ports implemented by each GPIO controller varies. The number of -implemented GPIOs within each port varies. GPIO registers within a controller -are grouped and laid out according to the port they affect. - -The mapping from port name to the GPIO controller that implements that port, and -the mapping from port name to register offset within a controller, are both -extremely non-linear. The header file <dt-bindings/gpio/tegra186-gpio.h> -describes the port-level mapping. In that file, the naming convention for ports -matches the HW documentation. The values chosen for the names are alphabetically -sorted within a particular controller. Drivers need to map between the DT GPIO -IDs and HW register offsets using a lookup table. - -Each GPIO controller can generate a number of interrupt signals. Each signal -represents the aggregate status for all GPIOs within a set of ports. Thus, the -number of interrupt signals generated by a controller varies as a rough function -of the number of ports it implements. Note that the HW documentation refers to -both the overall controller HW module and the sets-of-ports as "controllers". - -Each GPIO controller in fact generates multiple interrupts signals for each set -of ports. Each GPIO may be configured to feed into a specific one of the -interrupt signals generated by a set-of-ports. The intent is for each generated -signal to be routed to a different CPU, thus allowing different CPUs to each -handle subsets of the interrupts within a port. The status of each of these -per-port-set signals is reported via a separate register. Thus, a driver needs -to know which status register to observe. This binding currently defines no -configuration mechanism for this. By default, drivers should use register -GPIO_${port}_INTERRUPT_STATUS_G1_0. Future revisions to the binding could -define a property to configure this. - -Required properties: -- compatible - Array of strings. - One of: - - "nvidia,tegra186-gpio". - - "nvidia,tegra186-gpio-aon". - - "nvidia,tegra194-gpio". - - "nvidia,tegra194-gpio-aon". -- reg-names - Array of strings. - Contains a list of names for the register spaces described by the reg - property. May contain the following entries, in any order: - - "gpio": Mandatory. GPIO control registers. This may cover either: - a) The single physical alias that this OS should use. - b) All physical aliases that exist in the controller. This is - appropriate when the OS is responsible for managing assignment of - the physical aliases. - - "security": Optional. Security configuration registers. - Users of this binding MUST look up entries in the reg property by name, - using this reg-names property to do so. -- reg - Array of (physical base address, length) tuples. - Must contain one entry per entry in the reg-names property, in a matching - order. -- interrupts - Array of interrupt specifiers. - The interrupt outputs from the HW block, one per set of ports, in the - order the HW manual describes them. The number of entries required varies - depending on compatible value: - - "nvidia,tegra186-gpio": 6 entries. - - "nvidia,tegra186-gpio-aon": 1 entry. - - "nvidia,tegra194-gpio": 6 entries. - - "nvidia,tegra194-gpio-aon": 1 entry. -- gpio-controller - Boolean. - Marks the device node as a GPIO controller/provider. -- #gpio-cells - Single-cell integer. - Must be <2>. - Indicates how many cells are used in a consumer's GPIO specifier. - In the specifier: - - The first cell is the pin number. - See <dt-bindings/gpio/tegra186-gpio.h>. - - The second cell contains flags: - - Bit 0 specifies polarity - - 0: Active-high (normal). - - 1: Active-low (inverted). -- interrupt-controller - Boolean. - Marks the device node as an interrupt controller/provider. -- #interrupt-cells - Single-cell integer. - Must be <2>. - Indicates how many cells are used in a consumer's interrupt specifier. - In the specifier: - - The first cell is the GPIO number. - See <dt-bindings/gpio/tegra186-gpio.h>. - - The second cell is contains flags: - - Bits [3:0] indicate trigger type and level: - - 1: Low-to-high edge triggered. - - 2: High-to-low edge triggered. - - 4: Active high level-sensitive. - - 8: Active low level-sensitive. - Valid combinations are 1, 2, 3, 4, 8. - -Example: - -#include <dt-bindings/interrupt-controller/irq.h> - -gpio@2200000 { - compatible = "nvidia,tegra186-gpio"; - reg-names = "security", "gpio"; - reg = - <0x0 0x2200000 0x0 0x10000>, - <0x0 0x2210000 0x0 0x10000>; - interrupts = - <0 47 IRQ_TYPE_LEVEL_HIGH>, - <0 50 IRQ_TYPE_LEVEL_HIGH>, - <0 53 IRQ_TYPE_LEVEL_HIGH>, - <0 56 IRQ_TYPE_LEVEL_HIGH>, - <0 59 IRQ_TYPE_LEVEL_HIGH>, - <0 180 IRQ_TYPE_LEVEL_HIGH>; - gpio-controller; - #gpio-cells = <2>; - interrupt-controller; - #interrupt-cells = <2>; -}; - -gpio@c2f0000 { - compatible = "nvidia,tegra186-gpio-aon"; - reg-names = "security", "gpio"; - reg = - <0x0 0xc2f0000 0x0 0x1000>, - <0x0 0xc2f1000 0x0 0x1000>; - interrupts = - <0 60 IRQ_TYPE_LEVEL_HIGH>; - gpio-controller; - #gpio-cells = <2>; - interrupt-controller; - #interrupt-cells = <2>; -}; diff --git a/Documentation/devicetree/bindings/gpio/nvidia,tegra186-gpio.yaml b/Documentation/devicetree/bindings/gpio/nvidia,tegra186-gpio.yaml new file mode 100644 index 000000000000..4ef06b2ff1ff --- /dev/null +++ b/Documentation/devicetree/bindings/gpio/nvidia,tegra186-gpio.yaml @@ -0,0 +1,214 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/gpio/nvidia,tegra186-gpio.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: NVIDIA Tegra GPIO Controller (Tegra186 and later) + +maintainers: + - Thierry Reding <thierry.reding@gmail.com> + - Jon Hunter <jonathanh@nvidia.com> + +description: | + Tegra186 contains two GPIO controllers; a main controller and an "AON" + controller. This binding document applies to both controllers. The register + layouts for the controllers share many similarities, but also some + significant differences. Hence, this document describes closely related but + different bindings and compatible values. + + The Tegra186 GPIO controller allows software to set the IO direction of, + and read/write the value of, numerous GPIO signals. Routing of GPIO signals + to package balls is under the control of a separate pin controller hardware + block. Two major sets of registers exist: + + a) Security registers, which allow configuration of allowed access to the + GPIO register set. These registers exist in a single contiguous block + of physical address space. The size of this block, and the security + features available, varies between the different GPIO controllers. + + Access to this set of registers is not necessary in all circumstances. + Code that wishes to configure access to the GPIO registers needs access + to these registers to do so. Code which simply wishes to read or write + GPIO data does not need access to these registers. + + b) GPIO registers, which allow manipulation of the GPIO signals. In some + GPIO controllers, these registers are exposed via multiple "physical + aliases" in address space, each of which access the same underlying + state. See the hardware documentation for rationale. Any particular + GPIO client is expected to access just one of these physical aliases. + + Tegra HW documentation describes a unified naming convention for all GPIOs + implemented by the SoC. Each GPIO is assigned to a port, and a port may + control a number of GPIOs. Thus, each GPIO is named according to an + alphabetical port name and an integer GPIO name within the port. For + example, GPIO_PA0, GPIO_PN6, or GPIO_PCC3. + + The number of ports implemented by each GPIO controller varies. The number + of implemented GPIOs within each port varies. GPIO registers within a + controller are grouped and laid out according to the port they affect. + + The mapping from port name to the GPIO controller that implements that + port, and the mapping from port name to register offset within a + controller, are both extremely non-linear. The header file + <dt-bindings/gpio/tegra186-gpio.h> describes the port-level mapping. In + that file, the naming convention for ports matches the HW documentation. + The values chosen for the names are alphabetically sorted within a + particular controller. Drivers need to map between the DT GPIO IDs and HW + register offsets using a lookup table. + + Each GPIO controller can generate a number of interrupt signals. Each + signal represents the aggregate status for all GPIOs within a set of + ports. Thus, the number of interrupt signals generated by a controller + varies as a rough function of the number of ports it implements. Note + that the HW documentation refers to both the overall controller HW + module and the sets-of-ports as "controllers". + + Each GPIO controller in fact generates multiple interrupts signals for + each set of ports. Each GPIO may be configured to feed into a specific + one of the interrupt signals generated by a set-of-ports. The intent is + for each generated signal to be routed to a different CPU, thus allowing + different CPUs to each handle subsets of the interrupts within a port. + The status of each of these per-port-set signals is reported via a + separate register. Thus, a driver needs to know which status register to + observe. This binding currently defines no configuration mechanism for + this. By default, drivers should use register + GPIO_${port}_INTERRUPT_STATUS_G1_0. Future revisions to the binding could + define a property to configure this. + +properties: + compatible: + enum: + - nvidia,tegra186-gpio + - nvidia,tegra186-gpio-aon + - nvidia,tegra194-gpio + - nvidia,tegra194-gpio-aon + - nvidia,tegra234-gpio + - nvidia,tegra234-gpio-aon + + reg-names: + items: + - const: security + - const: gpio + minItems: 1 + + reg: + items: + - description: Security configuration registers. + - description: | + GPIO control registers. This may cover either: + + a) The single physical alias that this OS should use. + b) All physical aliases that exist in the controller. This is + appropriate when the OS is responsible for managing assignment + of the physical aliases. + minItems: 1 + + interrupts: + description: The interrupt outputs from the HW block, one per set of + ports, in the order the HW manual describes them. The number of entries + required varies depending on compatible value. + + gpio-controller: true + + "#gpio-cells": + description: | + Indicates how many cells are used in a consumer's GPIO specifier. In the + specifier: + + - The first cell is the pin number. + See <dt-bindings/gpio/tegra186-gpio.h>. + - The second cell contains flags: + - Bit 0 specifies polarity + - 0: Active-high (normal). + - 1: Active-low (inverted). + const: 2 + + interrupt-controller: true + + "#interrupt-cells": + description: | + Indicates how many cells are used in a consumer's interrupt specifier. + In the specifier: + + - The first cell is the GPIO number. + See <dt-bindings/gpio/tegra186-gpio.h>. + - The second cell is contains flags: + - Bits [3:0] indicate trigger type and level: + - 1: Low-to-high edge triggered. + - 2: High-to-low edge triggered. + - 4: Active high level-sensitive. + - 8: Active low level-sensitive. + + Valid combinations are 1, 2, 3, 4, 8. + const: 2 + +allOf: + - if: + properties: + compatible: + contains: + enum: + - nvidia,tegra186-gpio + - nvidia,tegra194-gpio + - nvidia,tegra234-gpio + then: + properties: + interrupts: + minItems: 6 + maxItems: 48 + + - if: + properties: + compatible: + contains: + enum: + - nvidia,tegra186-gpio-aon + - nvidia,tegra194-gpio-aon + - nvidia,tegra234-gpio-aon + then: + properties: + interrupts: + minItems: 1 + maxItems: 4 + +required: + - compatible + - reg + - reg-names + - interrupts + +additionalProperties: false + +examples: + - | + #include <dt-bindings/interrupt-controller/irq.h> + + gpio@2200000 { + compatible = "nvidia,tegra186-gpio"; + reg-names = "security", "gpio"; + reg = <0x2200000 0x10000>, + <0x2210000 0x10000>; + interrupts = <0 47 IRQ_TYPE_LEVEL_HIGH>, + <0 50 IRQ_TYPE_LEVEL_HIGH>, + <0 53 IRQ_TYPE_LEVEL_HIGH>, + <0 56 IRQ_TYPE_LEVEL_HIGH>, + <0 59 IRQ_TYPE_LEVEL_HIGH>, + <0 180 IRQ_TYPE_LEVEL_HIGH>; + gpio-controller; + #gpio-cells = <2>; + interrupt-controller; + #interrupt-cells = <2>; + }; + + gpio@c2f0000 { + compatible = "nvidia,tegra186-gpio-aon"; + reg-names = "security", "gpio"; + reg = <0xc2f0000 0x1000>, + <0xc2f1000 0x1000>; + interrupts = <0 60 IRQ_TYPE_LEVEL_HIGH>; + gpio-controller; + #gpio-cells = <2>; + interrupt-controller; + #interrupt-cells = <2>; + }; diff --git a/Documentation/devicetree/bindings/gpio/nvidia,tegra20-gpio.txt b/Documentation/devicetree/bindings/gpio/nvidia,tegra20-gpio.txt deleted file mode 100644 index 023c9526e5f8..000000000000 --- a/Documentation/devicetree/bindings/gpio/nvidia,tegra20-gpio.txt +++ /dev/null @@ -1,40 +0,0 @@ -NVIDIA Tegra GPIO controller - -Required properties: -- compatible : "nvidia,tegra<chip>-gpio" -- reg : Physical base address and length of the controller's registers. -- interrupts : The interrupt outputs from the controller. For Tegra20, - there should be 7 interrupts specified, and for Tegra30, there should - be 8 interrupts specified. -- #gpio-cells : Should be two. The first cell is the pin number and the - second cell is used to specify optional parameters: - - bit 0 specifies polarity (0 for normal, 1 for inverted) -- gpio-controller : Marks the device node as a GPIO controller. -- #interrupt-cells : Should be 2. - The first cell is the GPIO number. - The second cell is used to specify flags: - bits[3:0] trigger type and level flags: - 1 = low-to-high edge triggered. - 2 = high-to-low edge triggered. - 4 = active high level-sensitive. - 8 = active low level-sensitive. - Valid combinations are 1, 2, 3, 4, 8. -- interrupt-controller : Marks the device node as an interrupt controller. - -Example: - -gpio: gpio@6000d000 { - compatible = "nvidia,tegra20-gpio"; - reg = < 0x6000d000 0x1000 >; - interrupts = < 0 32 0x04 - 0 33 0x04 - 0 34 0x04 - 0 35 0x04 - 0 55 0x04 - 0 87 0x04 - 0 89 0x04 >; - #gpio-cells = <2>; - gpio-controller; - #interrupt-cells = <2>; - interrupt-controller; -}; diff --git a/Documentation/devicetree/bindings/gpio/nvidia,tegra20-gpio.yaml b/Documentation/devicetree/bindings/gpio/nvidia,tegra20-gpio.yaml new file mode 100644 index 000000000000..94b51749ee76 --- /dev/null +++ b/Documentation/devicetree/bindings/gpio/nvidia,tegra20-gpio.yaml @@ -0,0 +1,110 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/gpio/nvidia,tegra20-gpio.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: NVIDIA Tegra GPIO Controller (Tegra20 - Tegra210) + +maintainers: + - Thierry Reding <thierry.reding@gmail.com> + - Jon Hunter <jonathanh@nvidia.com> + +properties: + compatible: + oneOf: + - enum: + - nvidia,tegra20-gpio + - nvidia,tegra30-gpio + + - items: + - enum: + - nvidia,tegra114-gpio + - nvidia,tegra124-gpio + - nvidia,tegra210-gpio + - const: nvidia,tegra30-gpio + + reg: + maxItems: 1 + + interrupts: + description: The interrupt outputs from the controller. For Tegra20, + there should be 7 interrupts specified, and for Tegra30, there should + be 8 interrupts specified. + + "#gpio-cells": + description: The first cell is the pin number and the second cell is used + to specify the GPIO polarity (0 = active high, 1 = active low). + const: 2 + + gpio-controller: true + + gpio-ranges: + maxItems: 1 + + "#interrupt-cells": + description: | + Should be 2. The first cell is the GPIO number. The second cell is + used to specify flags: + + bits[3:0] trigger type and level flags: + 1 = low-to-high edge triggered. + 2 = high-to-low edge triggered. + 4 = active high level-sensitive. + 8 = active low level-sensitive. + + Valid combinations are 1, 2, 3, 4, 8. + const: 2 + + interrupt-controller: true + +allOf: + - if: + properties: + compatible: + contains: + const: nvidia,tegra30-gpio + then: + properties: + interrupts: + minItems: 8 + maxItems: 8 + else: + properties: + interrupts: + minItems: 7 + maxItems: 7 + +required: + - compatible + - reg + - interrupts + - "#gpio-cells" + - gpio-controller + - "#interrupt-cells" + - interrupt-controller + +additionalProperties: + type: object + required: + - gpio-hog + +examples: + - | + #include <dt-bindings/interrupt-controller/arm-gic.h> + + gpio: gpio@6000d000 { + compatible = "nvidia,tegra20-gpio"; + reg = <0x6000d000 0x1000>; + interrupts = <GIC_SPI 32 IRQ_TYPE_LEVEL_HIGH>, + <GIC_SPI 33 IRQ_TYPE_LEVEL_HIGH>, + <GIC_SPI 34 IRQ_TYPE_LEVEL_HIGH>, + <GIC_SPI 35 IRQ_TYPE_LEVEL_HIGH>, + <GIC_SPI 55 IRQ_TYPE_LEVEL_HIGH>, + <GIC_SPI 87 IRQ_TYPE_LEVEL_HIGH>, + <GIC_SPI 89 IRQ_TYPE_LEVEL_HIGH>; + #gpio-cells = <2>; + gpio-controller; + #interrupt-cells = <2>; + interrupt-controller; + }; diff --git a/Documentation/devicetree/bindings/gpio/sifive,gpio.yaml b/Documentation/devicetree/bindings/gpio/sifive,gpio.yaml index c2902aac2514..e04349567eeb 100644 --- a/Documentation/devicetree/bindings/gpio/sifive,gpio.yaml +++ b/Documentation/devicetree/bindings/gpio/sifive,gpio.yaml @@ -77,7 +77,8 @@ examples: gpio@10060000 { compatible = "sifive,fu540-c000-gpio", "sifive,gpio0"; interrupt-parent = <&plic>; - interrupts = <7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22>; + interrupts = <7>, <8>, <9>, <10>, <11>, <12>, <13>, <14>, <15>, <16>, + <17>, <18>, <19>, <20>, <21>, <22>; reg = <0x10060000 0x1000>; clocks = <&tlclk PRCI_CLK_TLCLK>; gpio-controller; diff --git a/Documentation/devicetree/bindings/gpu/host1x/nvidia,tegra210-nvenc.yaml b/Documentation/devicetree/bindings/gpu/host1x/nvidia,tegra210-nvenc.yaml new file mode 100644 index 000000000000..e63ae1a00818 --- /dev/null +++ b/Documentation/devicetree/bindings/gpu/host1x/nvidia,tegra210-nvenc.yaml @@ -0,0 +1,135 @@ +# SPDX-License-Identifier: (GPL-2.0 OR BSD-2-Clause) +%YAML 1.2 +--- +$id: "http://devicetree.org/schemas/gpu/host1x/nvidia,tegra210-nvenc.yaml#" +$schema: "http://devicetree.org/meta-schemas/core.yaml#" + +title: Device tree binding for NVIDIA Tegra NVENC + +description: | + NVENC is the hardware video encoder present on NVIDIA Tegra210 + and newer chips. It is located on the Host1x bus and typically + programmed through Host1x channels. + +maintainers: + - Thierry Reding <treding@gmail.com> + - Mikko Perttunen <mperttunen@nvidia.com> + +properties: + $nodename: + pattern: "^nvenc@[0-9a-f]*$" + + compatible: + enum: + - nvidia,tegra210-nvenc + - nvidia,tegra186-nvenc + - nvidia,tegra194-nvenc + + reg: + maxItems: 1 + + clocks: + maxItems: 1 + + clock-names: + items: + - const: nvenc + + resets: + maxItems: 1 + + reset-names: + items: + - const: nvenc + + power-domains: + maxItems: 1 + + iommus: + maxItems: 1 + + dma-coherent: true + + interconnects: + minItems: 2 + maxItems: 3 + + interconnect-names: + minItems: 2 + maxItems: 3 + + nvidia,host1x-class: + description: | + Host1x class of the engine, used to specify the targeted engine + when programming the engine through Host1x channels or when + configuring engine-specific behavior in Host1x. + default: 0x21 + $ref: /schemas/types.yaml#/definitions/uint32 + +required: + - compatible + - reg + - clocks + - clock-names + - resets + - reset-names + - power-domains + +allOf: + - if: + properties: + compatible: + enum: + - nvidia,tegra210-nvenc + - nvidia,tegra186-nvenc + then: + properties: + interconnects: + items: + - description: DMA read memory client + - description: DMA write memory client + interconnect-names: + items: + - const: dma-mem + - const: write + - if: + properties: + compatible: + enum: + - nvidia,tegra194-nvenc + then: + properties: + interconnects: + items: + - description: DMA read memory client + - description: DMA read 2 memory client + - description: DMA write memory client + interconnect-names: + items: + - const: dma-mem + - const: read-1 + - const: write + +additionalProperties: false + +examples: + - | + #include <dt-bindings/clock/tegra186-clock.h> + #include <dt-bindings/memory/tegra186-mc.h> + #include <dt-bindings/power/tegra186-powergate.h> + #include <dt-bindings/reset/tegra186-reset.h> + + nvenc@154c0000 { + compatible = "nvidia,tegra186-nvenc"; + reg = <0x154c0000 0x40000>; + clocks = <&bpmp TEGRA186_CLK_NVENC>; + clock-names = "nvenc"; + resets = <&bpmp TEGRA186_RESET_NVENC>; + reset-names = "nvenc"; + + power-domains = <&bpmp TEGRA186_POWER_DOMAIN_MPE>; + interconnects = <&mc TEGRA186_MEMORY_CLIENT_NVENCSRD &emc>, + <&mc TEGRA186_MEMORY_CLIENT_NVENCSWR &emc>; + interconnect-names = "dma-mem", "write"; + iommus = <&smmu TEGRA186_SID_NVENC>; + }; diff --git a/Documentation/devicetree/bindings/gpu/host1x/nvidia,tegra210-nvjpg.yaml b/Documentation/devicetree/bindings/gpu/host1x/nvidia,tegra210-nvjpg.yaml new file mode 100644 index 000000000000..8647404d67e4 --- /dev/null +++ b/Documentation/devicetree/bindings/gpu/host1x/nvidia,tegra210-nvjpg.yaml @@ -0,0 +1,94 @@ +# SPDX-License-Identifier: (GPL-2.0 OR BSD-2-Clause) +%YAML 1.2 +--- +$id: "http://devicetree.org/schemas/gpu/host1x/nvidia,tegra210-nvjpg.yaml#" +$schema: "http://devicetree.org/meta-schemas/core.yaml#" + +title: Device tree binding for NVIDIA Tegra NVJPG + +description: | + NVJPG is the hardware JPEG decoder and encoder present on NVIDIA Tegra210 + and newer chips. It is located on the Host1x bus and typically programmed + through Host1x channels. + +maintainers: + - Thierry Reding <treding@gmail.com> + - Mikko Perttunen <mperttunen@nvidia.com> + +properties: + $nodename: + pattern: "^nvjpg@[0-9a-f]*$" + + compatible: + enum: + - nvidia,tegra210-nvjpg + - nvidia,tegra186-nvjpg + - nvidia,tegra194-nvjpg + + reg: + maxItems: 1 + + clocks: + maxItems: 1 + + clock-names: + items: + - const: nvjpg + + resets: + maxItems: 1 + + reset-names: + items: + - const: nvjpg + + power-domains: + maxItems: 1 + + iommus: + maxItems: 1 + + dma-coherent: true + + interconnects: + items: + - description: DMA read memory client + - description: DMA write memory client + + interconnect-names: + items: + - const: dma-mem + - const: write + +required: + - compatible + - reg + - clocks + - clock-names + - resets + - reset-names + - power-domains + +additionalProperties: false + +examples: + - | + #include <dt-bindings/clock/tegra186-clock.h> + #include <dt-bindings/memory/tegra186-mc.h> + #include <dt-bindings/power/tegra186-powergate.h> + #include <dt-bindings/reset/tegra186-reset.h> + + nvjpg@15380000 { + compatible = "nvidia,tegra186-nvjpg"; + reg = <0x15380000 0x40000>; + clocks = <&bpmp TEGRA186_CLK_NVJPG>; + clock-names = "nvjpg"; + resets = <&bpmp TEGRA186_RESET_NVJPG>; + reset-names = "nvjpg"; + + power-domains = <&bpmp TEGRA186_POWER_DOMAIN_NVJPG>; + interconnects = <&mc TEGRA186_MEMORY_CLIENT_NVJPGSRD &emc>, + <&mc TEGRA186_MEMORY_CLIENT_NVJPGSWR &emc>; + interconnect-names = "dma-mem", "write"; + iommus = <&smmu TEGRA186_SID_NVJPG>; + }; diff --git a/Documentation/devicetree/bindings/hwmon/ntc-thermistor.yaml b/Documentation/devicetree/bindings/hwmon/ntc-thermistor.yaml index 9e77cee07dbc..3d3b139a91a2 100644 --- a/Documentation/devicetree/bindings/hwmon/ntc-thermistor.yaml +++ b/Documentation/devicetree/bindings/hwmon/ntc-thermistor.yaml @@ -76,6 +76,7 @@ properties: - const: murata,ncp15wl333 - const: murata,ncp03wf104 - const: murata,ncp15xh103 + - const: samsung,1404-001221 # Deprecated "ntp," compatible strings - const: ntc,ncp15wb473 deprecated: true diff --git a/Documentation/devicetree/bindings/hwmon/ti,ina2xx.yaml b/Documentation/devicetree/bindings/hwmon/ti,ina2xx.yaml index 6f0443322a36..47af97bb4ced 100644 --- a/Documentation/devicetree/bindings/hwmon/ti,ina2xx.yaml +++ b/Documentation/devicetree/bindings/hwmon/ti,ina2xx.yaml @@ -26,6 +26,7 @@ properties: - ti,ina226 - ti,ina230 - ti,ina231 + - ti,ina238 reg: maxItems: 1 @@ -35,6 +36,27 @@ properties: Shunt resistor value in micro-Ohm. $ref: /schemas/types.yaml#/definitions/uint32 + ti,shunt-gain: + description: | + Programmable gain divisor for the shunt voltage accuracy and range. This + property only applies to devices that have configurable PGA/ADCRANGE. The + gain value is used configure the gain and to convert the shunt voltage, + current and power register values when reading measurements from the + device. + + For devices that have a configurable PGA (e.g. INA209, INA219, INA220), + the gain value maps directly with the PG bits of the config register. + + For devices that have ADCRANGE configuration (e.g. INA238) a shunt-gain + value of 1 maps to ADCRANGE=1 where no gain divisor is applied to the + shunt voltage, and a value of 4 maps to ADCRANGE=0 such that a wider + voltage range is used. + + The default value is device dependent, and is defined by the reset value + of PGA/ADCRANGE in the respective configuration registers. + $ref: /schemas/types.yaml#/definitions/uint32 + enum: [1, 2, 4, 8] + required: - compatible - reg diff --git a/Documentation/devicetree/bindings/i2c/apple,i2c.yaml b/Documentation/devicetree/bindings/i2c/apple,i2c.yaml index 22fc8483256f..4ac61fec90e2 100644 --- a/Documentation/devicetree/bindings/i2c/apple,i2c.yaml +++ b/Documentation/devicetree/bindings/i2c/apple,i2c.yaml @@ -20,9 +20,11 @@ allOf: properties: compatible: - enum: - - apple,t8103-i2c - - apple,i2c + items: + - enum: + - apple,t8103-i2c + - apple,t6000-i2c + - const: apple,i2c reg: maxItems: 1 @@ -40,6 +42,9 @@ properties: used. This frequency is generated by dividing the reference clock. Allowed values are between ref_clk/(16*4) and ref_clk/(16*255). + power-domains: + maxItems: 1 + required: - compatible - reg @@ -51,7 +56,7 @@ unevaluatedProperties: false examples: - | i2c@35010000 { - compatible = "apple,t8103-i2c"; + compatible = "apple,t8103-i2c", "apple,i2c"; reg = <0x35010000 0x4000>; interrupt-parent = <&aic>; interrupts = <0 627 4>; diff --git a/Documentation/devicetree/bindings/iio/adc/samsung,exynos-adc.yaml b/Documentation/devicetree/bindings/iio/adc/samsung,exynos-adc.yaml index c65921e66dc1..81c87295912c 100644 --- a/Documentation/devicetree/bindings/iio/adc/samsung,exynos-adc.yaml +++ b/Documentation/devicetree/bindings/iio/adc/samsung,exynos-adc.yaml @@ -136,7 +136,7 @@ examples: samsung,syscon-phandle = <&pmu_system_controller>; /* NTC thermistor is a hwmon device */ - ncp15wb473 { + thermistor { compatible = "murata,ncp15wb473"; pullup-uv = <1800000>; pullup-ohm = <47000>; diff --git a/Documentation/devicetree/bindings/input/gpio-keys.yaml b/Documentation/devicetree/bindings/input/gpio-keys.yaml index 060a309ff8e7..dbe7ecc19ccb 100644 --- a/Documentation/devicetree/bindings/input/gpio-keys.yaml +++ b/Documentation/devicetree/bindings/input/gpio-keys.yaml @@ -142,7 +142,7 @@ examples: down { label = "GPIO Key DOWN"; linux,code = <108>; - interrupts = <1 IRQ_TYPE_LEVEL_HIGH 7>; + interrupts = <1 IRQ_TYPE_EDGE_FALLING>; }; }; diff --git a/Documentation/devicetree/bindings/input/hid-over-i2c.txt b/Documentation/devicetree/bindings/input/hid-over-i2c.txt index c76bafaf98d2..34c43d3bddfd 100644 --- a/Documentation/devicetree/bindings/input/hid-over-i2c.txt +++ b/Documentation/devicetree/bindings/input/hid-over-i2c.txt @@ -32,6 +32,8 @@ device-specific compatible properties, which should be used in addition to the - vdd-supply: phandle of the regulator that provides the supply voltage. - post-power-on-delay-ms: time required by the device after enabling its regulators or powering it on, before it is ready for communication. +- touchscreen-inverted-x: See touchscreen.txt +- touchscreen-inverted-y: See touchscreen.txt Example: diff --git a/Documentation/devicetree/bindings/interrupt-controller/apple,aic.yaml b/Documentation/devicetree/bindings/interrupt-controller/apple,aic.yaml index cf6c091a07b1..97359024709a 100644 --- a/Documentation/devicetree/bindings/interrupt-controller/apple,aic.yaml +++ b/Documentation/devicetree/bindings/interrupt-controller/apple,aic.yaml @@ -65,6 +65,9 @@ properties: Specifies base physical address and size of the AIC registers. maxItems: 1 + power-domains: + maxItems: 1 + required: - compatible - '#interrupt-cells' diff --git a/Documentation/devicetree/bindings/interrupt-controller/sifive,plic-1.0.0.yaml b/Documentation/devicetree/bindings/interrupt-controller/sifive,plic-1.0.0.yaml index 08d5a57ce00f..28b6b17fe4b2 100644 --- a/Documentation/devicetree/bindings/interrupt-controller/sifive,plic-1.0.0.yaml +++ b/Documentation/devicetree/bindings/interrupt-controller/sifive,plic-1.0.0.yaml @@ -45,6 +45,7 @@ properties: items: - enum: - sifive,fu540-c000-plic + - starfive,jh7100-plic - canaan,k210-plic - const: sifive,plic-1.0.0 diff --git a/Documentation/devicetree/bindings/iommu/apple,dart.yaml b/Documentation/devicetree/bindings/iommu/apple,dart.yaml index 94aa9e9afa59..82ad669feef7 100644 --- a/Documentation/devicetree/bindings/iommu/apple,dart.yaml +++ b/Documentation/devicetree/bindings/iommu/apple,dart.yaml @@ -41,6 +41,9 @@ properties: Has to be one. The single cell describes the stream id emitted by a master to the IOMMU. + power-domains: + maxItems: 1 + required: - compatible - reg diff --git a/Documentation/devicetree/bindings/ipmi/aspeed,ast2400-ibt-bmc.txt b/Documentation/devicetree/bindings/ipmi/aspeed,ast2400-ibt-bmc.txt index c9902fd4b38b..25f86da804b7 100644 --- a/Documentation/devicetree/bindings/ipmi/aspeed,ast2400-ibt-bmc.txt +++ b/Documentation/devicetree/bindings/ipmi/aspeed,ast2400-ibt-bmc.txt @@ -11,6 +11,7 @@ Required properties: "aspeed,ast2500-ibt-bmc" "aspeed,ast2600-ibt-bmc" - reg: physical address and size of the registers +- clocks: clock for the device Optional properties: @@ -23,4 +24,5 @@ Example: compatible = "aspeed,ast2400-ibt-bmc"; reg = <0x1e789140 0x18>; interrupts = <8>; + clocks = <&syscon ASPEED_CLK_GATE_LCLK>; }; diff --git a/Documentation/devicetree/bindings/mailbox/apple,mailbox.yaml b/Documentation/devicetree/bindings/mailbox/apple,mailbox.yaml index 2c1704b34e7a..c4255f42e801 100644 --- a/Documentation/devicetree/bindings/mailbox/apple,mailbox.yaml +++ b/Documentation/devicetree/bindings/mailbox/apple,mailbox.yaml @@ -56,6 +56,9 @@ properties: "#mbox-cells": const: 0 + power-domains: + maxItems: 1 + required: - compatible - reg diff --git a/Documentation/devicetree/bindings/mailbox/nvidia,tegra186-hsp.txt b/Documentation/devicetree/bindings/mailbox/nvidia,tegra186-hsp.txt deleted file mode 100644 index ff3eafc5a882..000000000000 --- a/Documentation/devicetree/bindings/mailbox/nvidia,tegra186-hsp.txt +++ /dev/null @@ -1,72 +0,0 @@ -NVIDIA Tegra Hardware Synchronization Primitives (HSP) - -The HSP modules are used for the processors to share resources and communicate -together. It provides a set of hardware synchronization primitives for -interprocessor communication. So the interprocessor communication (IPC) -protocols can use hardware synchronization primitives, when operating between -two processors not in an SMP relationship. - -The features that HSP supported are shared mailboxes, shared semaphores, -arbitrated semaphores and doorbells. - -Required properties: -- name : Should be hsp -- compatible - Array of strings. - one of: - - "nvidia,tegra186-hsp" - - "nvidia,tegra194-hsp", "nvidia,tegra186-hsp" -- reg : Offset and length of the register set for the device. -- interrupt-names - Array of strings. - Contains a list of names for the interrupts described by the interrupt - property. May contain the following entries, in any order: - - "doorbell" - - "sharedN", where 'N' is a number from zero up to the number of - external interrupts supported by the HSP instance minus one. - Users of this binding MUST look up entries in the interrupt property - by name, using this interrupt-names property to do so. -- interrupts - Array of interrupt specifiers. - Must contain one entry per entry in the interrupt-names property, - in a matching order. -- #mbox-cells : Should be 2. - -The mbox specifier of the "mboxes" property in the client node should contain -two cells. The first cell determines the HSP type and the second cell is used -to identify the mailbox that the client is going to use. - -For doorbells, the second cell specifies the index of the doorbell to use. - -For shared mailboxes, the second cell is composed of two fields: -- bits 31..24: - A bit mask of flags that further specify how the shared mailbox will be - used. Valid flags are: - - bit 31: - Defines the direction of the mailbox. If set, the mailbox will be used - as a producer (i.e. used to send data). If cleared, the mailbox is the - consumer of data sent by a producer. - -- bits 23.. 0: - The index of the shared mailbox to use. The number of available mailboxes - may vary by instance of the HSP block and SoC generation. - -The following file contains definitions that can be used to construct mailbox -specifiers: - - <dt-bindings/mailbox/tegra186-hsp.h> - -Example: - -hsp_top0: hsp@3c00000 { - compatible = "nvidia,tegra186-hsp"; - reg = <0x0 0x03c00000 0x0 0xa0000>; - interrupts = <GIC_SPI 176 IRQ_TYPE_LEVEL_HIGH>; - interrupt-names = "doorbell"; - #mbox-cells = <2>; -}; - -client { - ... - mboxes = <&hsp_top0 TEGRA_HSP_MBOX_TYPE_DB TEGRA_HSP_DB_MASTER_XXX>; -}; diff --git a/Documentation/devicetree/bindings/mailbox/nvidia,tegra186-hsp.yaml b/Documentation/devicetree/bindings/mailbox/nvidia,tegra186-hsp.yaml new file mode 100644 index 000000000000..9f7a7296b57f --- /dev/null +++ b/Documentation/devicetree/bindings/mailbox/nvidia,tegra186-hsp.yaml @@ -0,0 +1,114 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/mailbox/nvidia,tegra186-hsp.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: NVIDIA Tegra Hardware Synchronization Primitives (HSP) + +maintainers: + - Thierry Reding <thierry.reding@gmail.com> + - Jon Hunter <jonathanh@nvidia.com> + +description: | + The HSP modules are used for the processors to share resources and + communicate together. It provides a set of hardware synchronization + primitives for interprocessor communication. So the interprocessor + communication (IPC) protocols can use hardware synchronization + primitives, when operating between two processors not in an SMP + relationship. + + The features that HSP supported are shared mailboxes, shared + semaphores, arbitrated semaphores and doorbells. + + The mbox specifier of the "mboxes" property in the client node should + contain two cells. The first cell determines the HSP type and the + second cell is used to identify the mailbox that the client is going + to use. + + For doorbells, the second cell specifies the index of the doorbell to + use. + + For shared mailboxes, the second cell is composed of two fields: + - bits 31..24: + A bit mask of flags that further specify how the shared mailbox + will be used. Valid flags are: + - bit 31: + Defines the direction of the mailbox. If set, the mailbox + will be used as a producer (i.e. used to send data). If + cleared, the mailbox is the consumer of data sent by a + producer. + + - bits 23..0: + The index of the shared mailbox to use. The number of available + mailboxes may vary by instance of the HSP block and SoC + generation. + + The following file contains definitions that can be used to + construct mailbox specifiers: + + <dt-bindings/mailbox/tegra186-hsp.h> + +properties: + $nodename: + pattern: "^hsp@[0-9a-f]+$" + + compatible: + oneOf: + - const: nvidia,tegra186-hsp + - const: nvidia,tegra194-hsp + - items: + - const: nvidia,tegra234-hsp + - const: nvidia,tegra194-hsp + + reg: + maxItems: 1 + + interrupts: + minItems: 1 + maxItems: 9 + + interrupt-names: + oneOf: + # shared interrupts are optional + - items: + - const: doorbell + + - items: + - const: doorbell + - pattern: "^shared[0-7]$" + - pattern: "^shared[0-7]$" + - pattern: "^shared[0-7]$" + - pattern: "^shared[0-7]$" + - pattern: "^shared[0-7]$" + - pattern: "^shared[0-7]$" + - pattern: "^shared[0-7]$" + - pattern: "^shared[0-7]$" + + - items: + - pattern: "^shared[0-7]$" + - pattern: "^shared[0-7]$" + - pattern: "^shared[0-7]$" + - pattern: "^shared[0-7]$" + + "#mbox-cells": + const: 2 + +additionalProperties: false + +examples: + - | + #include <dt-bindings/interrupt-controller/arm-gic.h> + #include <dt-bindings/mailbox/tegra186-hsp.h> + + hsp_top0: hsp@3c00000 { + compatible = "nvidia,tegra186-hsp"; + reg = <0x03c00000 0xa0000>; + interrupts = <GIC_SPI 176 IRQ_TYPE_LEVEL_HIGH>; + interrupt-names = "doorbell"; + #mbox-cells = <2>; + }; + + client { + mboxes = <&hsp_top0 TEGRA_HSP_MBOX_TYPE_DB TEGRA_HSP_DB_MASTER_CCPLEX>; + }; diff --git a/Documentation/devicetree/bindings/media/allwinner,sun4i-a10-video-engine.yaml b/Documentation/devicetree/bindings/media/allwinner,sun4i-a10-video-engine.yaml index c34303b87a5b..c3de96d10396 100644 --- a/Documentation/devicetree/bindings/media/allwinner,sun4i-a10-video-engine.yaml +++ b/Documentation/devicetree/bindings/media/allwinner,sun4i-a10-video-engine.yaml @@ -20,6 +20,7 @@ properties: - allwinner,sun8i-h3-video-engine - allwinner,sun8i-v3s-video-engine - allwinner,sun8i-r40-video-engine + - allwinner,sun20i-d1-video-engine - allwinner,sun50i-a64-video-engine - allwinner,sun50i-h5-video-engine - allwinner,sun50i-h6-video-engine diff --git a/Documentation/devicetree/bindings/media/allwinner,sun50i-h6-vpu-g2.yaml b/Documentation/devicetree/bindings/media/allwinner,sun50i-h6-vpu-g2.yaml new file mode 100644 index 000000000000..24d7bf21499e --- /dev/null +++ b/Documentation/devicetree/bindings/media/allwinner,sun50i-h6-vpu-g2.yaml @@ -0,0 +1,64 @@ +# SPDX-License-Identifier: (GPL-2.0 OR BSD-2-Clause) + +%YAML 1.2 +--- +$id: "http://devicetree.org/schemas/media/allwinner,sun50i-h6-vpu-g2.yaml#" +$schema: "http://devicetree.org/meta-schemas/core.yaml#" + +title: Hantro G2 VPU codec implemented on Allwinner H6 SoC + +maintainers: + - Jernej Skrabec <jernej.skrabec@gmail.com> + +description: + Hantro G2 video decode accelerator present on Allwinner H6 SoC. + +properties: + compatible: + const: allwinner,sun50i-h6-vpu-g2 + + reg: + maxItems: 1 + + interrupts: + maxItems: 1 + + clocks: + items: + - description: Bus Clock + - description: Module Clock + + clock-names: + items: + - const: bus + - const: mod + + resets: + maxItems: 1 + +required: + - compatible + - reg + - interrupts + - clocks + - clock-names + - resets + +additionalProperties: false + +examples: + - | + #include <dt-bindings/interrupt-controller/arm-gic.h> + #include <dt-bindings/clock/sun50i-h6-ccu.h> + #include <dt-bindings/reset/sun50i-h6-ccu.h> + + video-codec-g2@1c00000 { + compatible = "allwinner,sun50i-h6-vpu-g2"; + reg = <0x01c00000 0x1000>; + interrupts = <GIC_SPI 90 IRQ_TYPE_LEVEL_HIGH>; + clocks = <&ccu CLK_BUS_VP9>, <&ccu CLK_VP9>; + clock-names = "bus", "mod"; + resets = <&ccu RST_BUS_VP9>; + }; + +... diff --git a/Documentation/devicetree/bindings/media/i2c/adv748x.txt b/Documentation/devicetree/bindings/media/i2c/adv748x.txt deleted file mode 100644 index 4f91686e54a6..000000000000 --- a/Documentation/devicetree/bindings/media/i2c/adv748x.txt +++ /dev/null @@ -1,116 +0,0 @@ -* Analog Devices ADV748X video decoder with HDMI receiver - -The ADV7481 and ADV7482 are multi format video decoders with an integrated -HDMI receiver. They can output CSI-2 on two independent outputs TXA and TXB -from three input sources HDMI, analog and TTL. - -Required Properties: - - - compatible: Must contain one of the following - - "adi,adv7481" for the ADV7481 - - "adi,adv7482" for the ADV7482 - - - reg: I2C slave addresses - The ADV748x has up to twelve 256-byte maps that can be accessed via the - main I2C ports. Each map has it own I2C address and acts as a standard - slave device on the I2C bus. The main address is mandatory, others are - optional and remain at default values if not specified. - -Optional Properties: - - - interrupt-names: Should specify the interrupts as "intrq1", "intrq2" and/or - "intrq3". All interrupts are optional. The "intrq3" interrupt - is only available on the adv7481 - - interrupts: Specify the interrupt lines for the ADV748x - - reg-names : Names of maps with programmable addresses. - It shall contain all maps needing a non-default address. - Possible map names are: - "main", "dpll", "cp", "hdmi", "edid", "repeater", - "infoframe", "cbus", "cec", "sdp", "txa", "txb" - -The device node must contain one 'port' child node per device input and output -port, in accordance with the video interface bindings defined in -Documentation/devicetree/bindings/media/video-interfaces.txt. The port nodes -are numbered as follows. - - Name Type Port - --------------------------------------- - AIN0 sink 0 - AIN1 sink 1 - AIN2 sink 2 - AIN3 sink 3 - AIN4 sink 4 - AIN5 sink 5 - AIN6 sink 6 - AIN7 sink 7 - HDMI sink 8 - TTL sink 9 - TXA source 10 - TXB source 11 - -The digital output port nodes, when present, shall contain at least one -endpoint. Each of those endpoints shall contain the data-lanes property as -described in video-interfaces.txt. - -Required source endpoint properties: - - data-lanes: an array of physical data lane indexes - The accepted value(s) for this property depends on which of the two - sources are described. For TXA 1, 2 or 4 data lanes can be described - while for TXB only 1 data lane is valid. See video-interfaces.txt - for detailed description. - -Ports are optional if they are not connected to anything at the hardware level. - -Example: - - video-receiver@70 { - compatible = "adi,adv7482"; - reg = <0x70 0x71 0x72 0x73 0x74 0x75 - 0x60 0x61 0x62 0x63 0x64 0x65>; - reg-names = "main", "dpll", "cp", "hdmi", "edid", "repeater", - "infoframe", "cbus", "cec", "sdp", "txa", "txb"; - - #address-cells = <1>; - #size-cells = <0>; - - interrupt-parent = <&gpio6>; - interrupt-names = "intrq1", "intrq2"; - interrupts = <30 IRQ_TYPE_LEVEL_LOW>, - <31 IRQ_TYPE_LEVEL_LOW>; - - port@7 { - reg = <7>; - - adv7482_ain7: endpoint { - remote-endpoint = <&cvbs_in>; - }; - }; - - port@8 { - reg = <8>; - - adv7482_hdmi: endpoint { - remote-endpoint = <&hdmi_in>; - }; - }; - - port@a { - reg = <10>; - - adv7482_txa: endpoint { - clock-lanes = <0>; - data-lanes = <1 2 3 4>; - remote-endpoint = <&csi40_in>; - }; - }; - - port@b { - reg = <11>; - - adv7482_txb: endpoint { - clock-lanes = <0>; - data-lanes = <1>; - remote-endpoint = <&csi20_in>; - }; - }; - }; diff --git a/Documentation/devicetree/bindings/media/i2c/adv748x.yaml b/Documentation/devicetree/bindings/media/i2c/adv748x.yaml new file mode 100644 index 000000000000..d6353081402b --- /dev/null +++ b/Documentation/devicetree/bindings/media/i2c/adv748x.yaml @@ -0,0 +1,212 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/media/i2c/adv748x.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Analog Devices ADV748X video decoder with HDMI receiver + +maintainers: + - Kieran Bingham <kieran.bingham@ideasonboard.com> + - Niklas Söderlund <niklas.soderlund@ragnatech.se> + +description: + The ADV7481 and ADV7482 are multi format video decoders with an integrated + HDMI receiver. They can output CSI-2 on two independent outputs TXA and TXB + from three input sources HDMI, analog and TTL. + +properties: + compatible: + items: + - enum: + - adi,adv7481 + - adi,adv7482 + + reg: + minItems: 1 + maxItems: 12 + description: + The ADV748x has up to twelve 256-byte maps that can be accessed via the + main I2C ports. Each map has it own I2C address and acts as a standard + slave device on the I2C bus. The main address is mandatory, others are + optional and remain at default values if not specified. + + reg-names: + minItems: 1 + items: + - const: main + - enum: [ dpll, cp, hdmi, edid, repeater, infoframe, cbus, cec, sdp, txa, txb ] + - enum: [ dpll, cp, hdmi, edid, repeater, infoframe, cbus, cec, sdp, txa, txb ] + - enum: [ dpll, cp, hdmi, edid, repeater, infoframe, cbus, cec, sdp, txa, txb ] + - enum: [ dpll, cp, hdmi, edid, repeater, infoframe, cbus, cec, sdp, txa, txb ] + - enum: [ dpll, cp, hdmi, edid, repeater, infoframe, cbus, cec, sdp, txa, txb ] + - enum: [ dpll, cp, hdmi, edid, repeater, infoframe, cbus, cec, sdp, txa, txb ] + - enum: [ dpll, cp, hdmi, edid, repeater, infoframe, cbus, cec, sdp, txa, txb ] + - enum: [ dpll, cp, hdmi, edid, repeater, infoframe, cbus, cec, sdp, txa, txb ] + - enum: [ dpll, cp, hdmi, edid, repeater, infoframe, cbus, cec, sdp, txa, txb ] + - enum: [ dpll, cp, hdmi, edid, repeater, infoframe, cbus, cec, sdp, txa, txb ] + - enum: [ dpll, cp, hdmi, edid, repeater, infoframe, cbus, cec, sdp, txa, txb ] + + interrupts: true + + interrupt-names: true + + ports: + $ref: /schemas/graph.yaml#/properties/ports + + patternProperties: + "^port@[0-7]$": + $ref: /schemas/graph.yaml#/properties/port + description: Input port nodes for analog inputs AIN[0-7]. + + properties: + port@8: + $ref: /schemas/graph.yaml#/properties/port + description: Input port node for HDMI. + + port@9: + $ref: /schemas/graph.yaml#/properties/port + description: Input port node for TTL. + + port@a: + $ref: /schemas/graph.yaml#/$defs/port-base + unevaluatedProperties: false + description: + Output port node, single endpoint describing the CSI-2 transmitter TXA. + + properties: + endpoint: + $ref: /schemas/media/video-interfaces.yaml# + unevaluatedProperties: false + + properties: + clock-lanes: + maxItems: 1 + + data-lanes: + minItems: 1 + maxItems: 4 + + required: + - clock-lanes + - data-lanes + + port@b: + $ref: /schemas/graph.yaml#/$defs/port-base + unevaluatedProperties: false + description: + Output port node, single endpoint describing the CSI-2 transmitter TXB. + + properties: + endpoint: + $ref: /schemas/media/video-interfaces.yaml# + unevaluatedProperties: false + + properties: + clock-lanes: + maxItems: 1 + + data-lanes: + maxItems: 1 + + required: + - clock-lanes + - data-lanes + +allOf: + - if: + properties: + compatible: + contains: + const: adi,adv7481 + then: + properties: + interrupts: + minItems: 1 + maxItems: 3 + + interrupt-names: + minItems: 1 + maxItems: 3 + items: + enum: [ intrq1, intrq2, intrq3 ] + else: + properties: + interrupts: + minItems: 1 + maxItems: 2 + + interrupt-names: + minItems: 1 + maxItems: 2 + items: + enum: [ intrq1, intrq2 ] + +additionalProperties: false + +required: + - compatible + - reg + - ports + +examples: + - | + #include <dt-bindings/interrupt-controller/irq.h> + + i2c { + #address-cells = <1>; + #size-cells = <0>; + + video-receiver@70 { + compatible = "adi,adv7482"; + reg = <0x70 0x71 0x72 0x73 0x74 0x75 + 0x60 0x61 0x62 0x63 0x64 0x65>; + reg-names = "main", "dpll", "cp", "hdmi", "edid", "repeater", + "infoframe", "cbus", "cec", "sdp", "txa", "txb"; + + interrupt-parent = <&gpio6>; + interrupts = <30 IRQ_TYPE_LEVEL_LOW>, <31 IRQ_TYPE_LEVEL_LOW>; + interrupt-names = "intrq1", "intrq2"; + + ports { + #address-cells = <1>; + #size-cells = <0>; + + port@7 { + reg = <7>; + + adv7482_ain7: endpoint { + remote-endpoint = <&cvbs_in>; + }; + }; + + port@8 { + reg = <8>; + + adv7482_hdmi: endpoint { + remote-endpoint = <&hdmi_in>; + }; + }; + + port@a { + reg = <10>; + + adv7482_txa: endpoint { + clock-lanes = <0>; + data-lanes = <1 2 3 4>; + remote-endpoint = <&csi40_in>; + }; + }; + + port@b { + reg = <11>; + + adv7482_txb: endpoint { + clock-lanes = <0>; + data-lanes = <1>; + remote-endpoint = <&csi20_in>; + }; + }; + }; + }; + }; diff --git a/Documentation/devicetree/bindings/media/nvidia,tegra-vde.txt b/Documentation/devicetree/bindings/media/nvidia,tegra-vde.txt deleted file mode 100644 index 602169b8aa19..000000000000 --- a/Documentation/devicetree/bindings/media/nvidia,tegra-vde.txt +++ /dev/null @@ -1,64 +0,0 @@ -NVIDIA Tegra Video Decoder Engine - -Required properties: -- compatible : Must contain one of the following values: - - "nvidia,tegra20-vde" - - "nvidia,tegra30-vde" - - "nvidia,tegra114-vde" - - "nvidia,tegra124-vde" - - "nvidia,tegra132-vde" -- reg : Must contain an entry for each entry in reg-names. -- reg-names : Must include the following entries: - - sxe - - bsev - - mbe - - ppe - - mce - - tfe - - ppb - - vdma - - frameid -- iram : Must contain phandle to the mmio-sram device node that represents - IRAM region used by VDE. -- interrupts : Must contain an entry for each entry in interrupt-names. -- interrupt-names : Must include the following entries: - - sync-token - - bsev - - sxe -- clocks : Must include the following entries: - - vde -- resets : Must contain an entry for each entry in reset-names. -- reset-names : Should include the following entries: - - vde - -Optional properties: -- resets : Must contain an entry for each entry in reset-names. -- reset-names : Must include the following entries: - - mc -- iommus: Must contain phandle to the IOMMU device node. - -Example: - -video-codec@6001a000 { - compatible = "nvidia,tegra20-vde"; - reg = <0x6001a000 0x1000 /* Syntax Engine */ - 0x6001b000 0x1000 /* Video Bitstream Engine */ - 0x6001c000 0x100 /* Macroblock Engine */ - 0x6001c200 0x100 /* Post-processing Engine */ - 0x6001c400 0x100 /* Motion Compensation Engine */ - 0x6001c600 0x100 /* Transform Engine */ - 0x6001c800 0x100 /* Pixel prediction block */ - 0x6001ca00 0x100 /* Video DMA */ - 0x6001d800 0x300 /* Video frame controls */>; - reg-names = "sxe", "bsev", "mbe", "ppe", "mce", - "tfe", "ppb", "vdma", "frameid"; - iram = <&vde_pool>; /* IRAM region */ - interrupts = <GIC_SPI 9 IRQ_TYPE_LEVEL_HIGH>, /* Sync token interrupt */ - <GIC_SPI 10 IRQ_TYPE_LEVEL_HIGH>, /* BSE-V interrupt */ - <GIC_SPI 12 IRQ_TYPE_LEVEL_HIGH>; /* SXE interrupt */ - interrupt-names = "sync-token", "bsev", "sxe"; - clocks = <&tegra_car TEGRA20_CLK_VDE>; - reset-names = "vde", "mc"; - resets = <&tegra_car 61>, <&mc TEGRA20_MC_RESET_VDE>; - iommus = <&mc TEGRA_SWGROUP_VDE>; -}; diff --git a/Documentation/devicetree/bindings/media/nvidia,tegra-vde.yaml b/Documentation/devicetree/bindings/media/nvidia,tegra-vde.yaml new file mode 100644 index 000000000000..4ecdee1be37e --- /dev/null +++ b/Documentation/devicetree/bindings/media/nvidia,tegra-vde.yaml @@ -0,0 +1,119 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/media/nvidia,tegra-vde.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: NVIDIA Tegra Video Decoder Engine + +maintainers: + - Dmitry Osipenko <digetx@gmail.com> + - Jon Hunter <jonathanh@nvidia.com> + - Thierry Reding <thierry.reding@gmail.com> + +properties: + compatible: + oneOf: + - items: + - enum: + - nvidia,tegra132-vde + - nvidia,tegra124-vde + - nvidia,tegra114-vde + - items: + - const: nvidia,tegra30-vde + - const: nvidia,tegra20-vde + - items: + - const: nvidia,tegra20-vde + + reg: + maxItems: 9 + + reg-names: + items: + - const: sxe + - const: bsev + - const: mbe + - const: ppe + - const: mce + - const: tfe + - const: ppb + - const: vdma + - const: frameid + + clocks: + maxItems: 1 + + resets: + maxItems: 2 + + reset-names: + items: + - const: vde + - const: mc + + interrupts: + maxItems: 3 + + interrupt-names: + items: + - const: sync-token + - const: bsev + - const: sxe + + iommus: + maxItems: 1 + + iram: + $ref: /schemas/types.yaml#/definitions/phandle + description: + Phandle of the SRAM MMIO node. + + operating-points-v2: + description: + Should contain freqs and voltages and opp-supported-hw property, + which is a bitfield indicating SoC speedo or process ID mask. + + power-domains: + maxItems: 1 + description: + Phandle to the SoC core power domain. + +required: + - compatible + - reg + - reg-names + - clocks + - resets + - reset-names + - interrupts + - interrupt-names + +additionalProperties: false + +examples: + - | + video-codec@6001a000 { + compatible = "nvidia,tegra20-vde"; + reg = <0x6001a000 0x1000>, /* Syntax Engine */ + <0x6001b000 0x1000>, /* Video Bitstream Engine */ + <0x6001c000 0x100>, /* Macroblock Engine */ + <0x6001c200 0x100>, /* Post-processing Engine */ + <0x6001c400 0x100>, /* Motion Compensation Engine */ + <0x6001c600 0x100>, /* Transform Engine */ + <0x6001c800 0x100>, /* Pixel prediction block */ + <0x6001ca00 0x100>, /* Video DMA */ + <0x6001d800 0x300>; /* Video frame controls */ + reg-names = "sxe", "bsev", "mbe", "ppe", "mce", + "tfe", "ppb", "vdma", "frameid"; + iram = <&iram>; /* IRAM MMIO region */ + interrupts = <0 9 4>, /* Sync token */ + <0 10 4>, /* BSE-V */ + <0 12 4>; /* SXE */ + interrupt-names = "sync-token", "bsev", "sxe"; + clocks = <&clk 61>; + reset-names = "vde", "mc"; + resets = <&rst 61>, <&mem 13>; + iommus = <&mem 15>; + operating-points-v2 = <&dvfs_opp_table>; + power-domains = <&domain>; + }; diff --git a/Documentation/devicetree/bindings/media/nxp,imx7-mipi-csi2.yaml b/Documentation/devicetree/bindings/media/nxp,imx7-mipi-csi2.yaml index 877183cf4278..1ef849dc74d7 100644 --- a/Documentation/devicetree/bindings/media/nxp,imx7-mipi-csi2.yaml +++ b/Documentation/devicetree/bindings/media/nxp,imx7-mipi-csi2.yaml @@ -79,6 +79,8 @@ properties: properties: data-lanes: + description: + Note that 'fsl,imx7-mipi-csi2' only supports up to 2 data lines. items: minItems: 1 maxItems: 4 @@ -91,18 +93,6 @@ properties: required: - data-lanes - allOf: - - if: - properties: - compatible: - contains: - const: fsl,imx7-mipi-csi2 - then: - properties: - data-lanes: - items: - maxItems: 2 - port@1: $ref: /schemas/graph.yaml#/properties/port description: diff --git a/Documentation/devicetree/bindings/media/renesas,jpu.txt b/Documentation/devicetree/bindings/media/renesas,jpu.txt deleted file mode 100644 index d3436e5190f9..000000000000 --- a/Documentation/devicetree/bindings/media/renesas,jpu.txt +++ /dev/null @@ -1,25 +0,0 @@ -* Renesas JPEG Processing Unit - -The JPEG processing unit (JPU) incorporates the JPEG codec with an encoding -and decoding function conforming to the JPEG baseline process, so that the JPU -can encode image data and decode JPEG data quickly. - -Required properties: -- compatible: "renesas,jpu-<soctype>", "renesas,rcar-gen2-jpu" as fallback. - Examples with soctypes are: - - "renesas,jpu-r8a7790" for R-Car H2 - - "renesas,jpu-r8a7791" for R-Car M2-W - - "renesas,jpu-r8a7792" for R-Car V2H - - "renesas,jpu-r8a7793" for R-Car M2-N - - - reg: Base address and length of the registers block for the JPU. - - interrupts: JPU interrupt specifier. - - clocks: A phandle + clock-specifier pair for the JPU functional clock. - -Example: R8A7790 (R-Car H2) JPU node - jpeg-codec@fe980000 { - compatible = "renesas,jpu-r8a7790", "renesas,rcar-gen2-jpu"; - reg = <0 0xfe980000 0 0x10300>; - interrupts = <0 272 IRQ_TYPE_LEVEL_HIGH>; - clocks = <&mstp1_clks R8A7790_CLK_JPU>; - }; diff --git a/Documentation/devicetree/bindings/media/renesas,jpu.yaml b/Documentation/devicetree/bindings/media/renesas,jpu.yaml new file mode 100644 index 000000000000..2f55968e864f --- /dev/null +++ b/Documentation/devicetree/bindings/media/renesas,jpu.yaml @@ -0,0 +1,65 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/media/renesas,jpu.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Renesas JPEG Processing Unit + +maintainers: + - Mikhail Ulyanov <mikhail.ulyanov@cogentembedded.com> + +description: + The JPEG processing unit (JPU) incorporates the JPEG codec with an encoding + and decoding function conforming to the JPEG baseline process, so that the + JPU can encode image data and decode JPEG data quickly. + +properties: + compatible: + items: + - enum: + - renesas,jpu-r8a7790 # R-Car H2 + - renesas,jpu-r8a7791 # R-Car M2-W + - renesas,jpu-r8a7792 # R-Car V2H + - renesas,jpu-r8a7793 # R-Car M2-N + - const: renesas,rcar-gen2-jpu # R-Car Gen2 + + reg: + maxItems: 1 + + interrupts: + maxItems: 1 + + clocks: + maxItems: 1 + + power-domains: + maxItems: 1 + + resets: + maxItems: 1 + +required: + - compatible + - reg + - interrupts + - clocks + - power-domains + - resets + +additionalProperties: false + +examples: + - | + #include <dt-bindings/clock/r8a7790-cpg-mssr.h> + #include <dt-bindings/interrupt-controller/arm-gic.h> + #include <dt-bindings/power/r8a7790-sysc.h> + + jpeg-codec@fe980000 { + compatible = "renesas,jpu-r8a7790", "renesas,rcar-gen2-jpu"; + reg = <0xfe980000 0x10300>; + interrupts = <GIC_SPI 272 IRQ_TYPE_LEVEL_HIGH>; + clocks = <&cpg CPG_MOD 106>; + power-domains = <&sysc R8A7790_PD_ALWAYS_ON>; + resets = <&cpg 106>; + }; diff --git a/Documentation/devicetree/bindings/media/st,stm32-dma2d.yaml b/Documentation/devicetree/bindings/media/st,stm32-dma2d.yaml new file mode 100644 index 000000000000..f97b4a246605 --- /dev/null +++ b/Documentation/devicetree/bindings/media/st,stm32-dma2d.yaml @@ -0,0 +1,71 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/media/st,stm32-dma2d.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: STMicroelectronics STM32 Chrom-Art Accelerator DMA2D binding + +description: + Chrom-ART Accelerator(DMA2D), graphical hardware accelerator + enabling enhanced graphical user interface with minimum CPU load + + It can perform the following operations. + + - Filling a part or the whole of a destination image with a specific color. + - Copying a part or the whole of a source image into a part or the whole of + a destination image. + - Copying a part or the whole of a source image into a part or the whole of + a destination image with a pixel format conversion. + - Blending a part and/or two complete source images with different pixel + format and copy the result into a part or the whole of a destination image + with a different color format. (TODO) + + +maintainers: + - Dillon Min <dillon.minfei@gmail.com> + +properties: + compatible: + const: st,stm32-dma2d + + reg: + maxItems: 1 + + interrupts: + maxItems: 1 + + clocks: + maxItems: 1 + + clock-names: + items: + - const: dma2d + + resets: + maxItems: 1 + +required: + - compatible + - reg + - interrupts + - clocks + - clock-names + - resets + +additionalProperties: false + +examples: + - | + #include <dt-bindings/clock/stm32fx-clock.h> + #include <dt-bindings/mfd/stm32f4-rcc.h> + dma2d: dma2d@4002b000 { + compatible = "st,stm32-dma2d"; + reg = <0x4002b000 0xc00>; + interrupts = <90>; + resets = <&rcc STM32F4_AHB1_RESET(DMA2D)>; + clocks = <&rcc 0 STM32F4_AHB1_CLOCK(DMA2D)>; + clock-names = "dma2d"; + }; + +... diff --git a/Documentation/devicetree/bindings/memory-controllers/nvidia,tegra186-mc.yaml b/Documentation/devicetree/bindings/memory-controllers/nvidia,tegra186-mc.yaml index 611bda38d187..13c4c82fd0d3 100644 --- a/Documentation/devicetree/bindings/memory-controllers/nvidia,tegra186-mc.yaml +++ b/Documentation/devicetree/bindings/memory-controllers/nvidia,tegra186-mc.yaml @@ -31,12 +31,15 @@ properties: - enum: - nvidia,tegra186-mc - nvidia,tegra194-mc + - nvidia,tegra234-mc reg: - maxItems: 1 + minItems: 1 + maxItems: 3 interrupts: - maxItems: 1 + items: + - description: MC general interrupt "#address-cells": const: 2 @@ -48,6 +51,9 @@ properties: dma-ranges: true + "#interconnect-cells": + const: 1 + patternProperties: "^external-memory-controller@[0-9a-f]+$": description: @@ -63,12 +69,15 @@ patternProperties: - enum: - nvidia,tegra186-emc - nvidia,tegra194-emc + - nvidia,tegra234-emc reg: - maxItems: 1 + minItems: 1 + maxItems: 2 interrupts: - maxItems: 1 + items: + - description: EMC general interrupt clocks: items: @@ -78,11 +87,83 @@ patternProperties: items: - const: emc + "#interconnect-cells": + const: 0 + nvidia,bpmp: $ref: /schemas/types.yaml#/definitions/phandle description: phandle of the node representing the BPMP + allOf: + - if: + properties: + compatible: + const: nvidia,tegra186-emc + then: + properties: + reg: + maxItems: 1 + + - if: + properties: + compatible: + const: nvidia,tegra194-emc + then: + properties: + reg: + minItems: 2 + + - if: + properties: + compatible: + const: nvidia,tegra234-emc + then: + properties: + reg: + minItems: 2 + + additionalProperties: false + + required: + - compatible + - reg + - interrupts + - clocks + - clock-names + - "#interconnect-cells" + - nvidia,bpmp + +allOf: + - if: + properties: + compatible: + const: nvidia,tegra186-mc + then: + properties: + reg: + maxItems: 1 + + - if: + properties: + compatible: + const: nvidia,tegra194-mc + then: + properties: + reg: + minItems: 3 + + - if: + properties: + compatible: + const: nvidia,tegra234-mc + then: + properties: + reg: + minItems: 3 + +additionalProperties: false + required: - compatible - reg @@ -90,8 +171,6 @@ required: - "#address-cells" - "#size-cells" -additionalProperties: false - examples: - | #include <dt-bindings/clock/tegra186-clock.h> @@ -124,12 +203,9 @@ examples: clocks = <&bpmp TEGRA186_CLK_EMC>; clock-names = "emc"; + #interconnect-cells = <0>; + nvidia,bpmp = <&bpmp>; }; }; }; - - bpmp: bpmp { - compatible = "nvidia,tegra186-bpmp"; - #clock-cells = <1>; - }; diff --git a/Documentation/devicetree/bindings/memory-controllers/renesas,rpc-if.yaml b/Documentation/devicetree/bindings/memory-controllers/renesas,rpc-if.yaml index 9da80e8f2444..294f1036420d 100644 --- a/Documentation/devicetree/bindings/memory-controllers/renesas,rpc-if.yaml +++ b/Documentation/devicetree/bindings/memory-controllers/renesas,rpc-if.yaml @@ -24,17 +24,23 @@ allOf: properties: compatible: - items: - - enum: - - renesas,r8a774a1-rpc-if # RZ/G2M - - renesas,r8a774b1-rpc-if # RZ/G2N - - renesas,r8a774c0-rpc-if # RZ/G2E - - renesas,r8a774e1-rpc-if # RZ/G2H - - renesas,r8a77970-rpc-if # R-Car V3M - - renesas,r8a77980-rpc-if # R-Car V3H - - renesas,r8a77995-rpc-if # R-Car D3 - - renesas,r8a779a0-rpc-if # R-Car V3U - - const: renesas,rcar-gen3-rpc-if # a generic R-Car gen3 or RZ/G2 device + oneOf: + - items: + - enum: + - renesas,r8a774a1-rpc-if # RZ/G2M + - renesas,r8a774b1-rpc-if # RZ/G2N + - renesas,r8a774c0-rpc-if # RZ/G2E + - renesas,r8a774e1-rpc-if # RZ/G2H + - renesas,r8a77970-rpc-if # R-Car V3M + - renesas,r8a77980-rpc-if # R-Car V3H + - renesas,r8a77995-rpc-if # R-Car D3 + - renesas,r8a779a0-rpc-if # R-Car V3U + - const: renesas,rcar-gen3-rpc-if # a generic R-Car gen3 or RZ/G2{E,H,M,N} device + + - items: + - enum: + - renesas,r9a07g044-rpc-if # RZ/G2{L,LC} + - const: renesas,rzg2l-rpc-if # RZ/G2L family reg: items: @@ -48,7 +54,9 @@ properties: - const: dirmap - const: wbuf - clocks: + clocks: true + + interrupts: maxItems: 1 power-domains: @@ -67,8 +75,6 @@ patternProperties: - cfi-flash - jedec,spi-nor -unevaluatedProperties: false - required: - compatible - reg @@ -79,6 +85,26 @@ required: - '#address-cells' - '#size-cells' +if: + properties: + compatible: + contains: + enum: + - renesas,rzg2l-rpc-if +then: + properties: + clocks: + items: + - description: SPI Multi IO Register access clock (SPI_CLK2) + - description: SPI Multi IO Main clock (SPI_CLK). + +else: + properties: + clocks: + maxItems: 1 + +unevaluatedProperties: false + examples: - | #include <dt-bindings/clock/renesas-cpg-mssr.h> diff --git a/Documentation/devicetree/bindings/memory-controllers/synopsys,ddrc-ecc.yaml b/Documentation/devicetree/bindings/memory-controllers/synopsys,ddrc-ecc.yaml index a24588474625..fb7ae38a9c86 100644 --- a/Documentation/devicetree/bindings/memory-controllers/synopsys,ddrc-ecc.yaml +++ b/Documentation/devicetree/bindings/memory-controllers/synopsys,ddrc-ecc.yaml @@ -26,6 +26,7 @@ properties: enum: - xlnx,zynq-ddrc-a05 - xlnx,zynqmp-ddrc-2.40a + - snps,ddrc-3.80a interrupts: maxItems: 1 diff --git a/Documentation/devicetree/bindings/memory-controllers/ti,gpmc.yaml b/Documentation/devicetree/bindings/memory-controllers/ti,gpmc.yaml index 25b42d68f9b3..64dc9d398d9a 100644 --- a/Documentation/devicetree/bindings/memory-controllers/ti,gpmc.yaml +++ b/Documentation/devicetree/bindings/memory-controllers/ti,gpmc.yaml @@ -23,13 +23,20 @@ properties: items: - enum: - ti,am3352-gpmc + - ti,am64-gpmc - ti,omap2420-gpmc - ti,omap2430-gpmc - ti,omap3430-gpmc - ti,omap4430-gpmc reg: - maxItems: 1 + minItems: 1 + maxItems: 2 + + reg-names: + items: + - const: cfg + - const: data interrupts: maxItems: 1 @@ -44,6 +51,9 @@ properties: items: - const: fck + power-domains: + maxItems: 1 + dmas: items: - description: DMA channel for GPMC NAND prefetch @@ -133,6 +143,17 @@ required: - "#address-cells" - "#size-cells" +allOf: + - if: + properties: + compatible: + contains: + const: ti,am64-gpmc + then: + required: + - reg-names + - power-domains + additionalProperties: false examples: diff --git a/Documentation/devicetree/bindings/mfd/bd9571mwv.txt b/Documentation/devicetree/bindings/mfd/bd9571mwv.txt deleted file mode 100644 index 1d6413e96c37..000000000000 --- a/Documentation/devicetree/bindings/mfd/bd9571mwv.txt +++ /dev/null @@ -1,69 +0,0 @@ -* ROHM BD9571MWV/BD9574MWF Power Management Integrated Circuit (PMIC) bindings - -Required properties: - - compatible : Should be "rohm,bd9571mwv" or "rohm,bd9574mwf". - - reg : I2C slave address. - - interrupts : The interrupt line the device is connected to. - - interrupt-controller : Marks the device node as an interrupt controller. - - #interrupt-cells : The number of cells to describe an IRQ, should be 2. - The first cell is the IRQ number. - The second cell is the flags, encoded as trigger - masks from ../interrupt-controller/interrupts.txt. - - gpio-controller : Marks the device node as a GPIO Controller. - - #gpio-cells : Should be two. The first cell is the pin number and - the second cell is used to specify flags. - See ../gpio/gpio.txt for more information. - - regulators: : List of child nodes that specify the regulator - initialization data. Child nodes must be named - after their hardware counterparts: - - vd09 - - vd18 - - vd25 - - vd33 - - dvfs - Each child node is defined using the standard - binding for regulators. - -Optional properties: - - rohm,ddr-backup-power : Value to use for DDR-Backup Power (default 0). - This is a bitmask that specifies which DDR power - rails need to be kept powered when backup mode is - entered, for system suspend: - - bit 0: DDR0 - - bit 1: DDR1 - - bit 2: DDR0C - - bit 3: DDR1C - These bits match the KEEPON_DDR* bits in the - documentation for the "BKUP Mode Cnt" register. - - rohm,rstbmode-level: The RSTB signal is configured for level mode, to - accommodate a toggle power switch (the RSTBMODE pin is - strapped low). - - rohm,rstbmode-pulse: The RSTB signal is configured for pulse mode, to - accommodate a momentary power switch (the RSTBMODE pin - is strapped high). - The two properties above are mutually exclusive. - -Example: - - pmic: pmic@30 { - compatible = "rohm,bd9571mwv"; - reg = <0x30>; - interrupt-parent = <&gpio2>; - interrupts = <0 IRQ_TYPE_LEVEL_LOW>; - interrupt-controller; - #interrupt-cells = <2>; - gpio-controller; - #gpio-cells = <2>; - rohm,ddr-backup-power = <0xf>; - rohm,rstbmode-pulse; - - regulators { - dvfs: dvfs { - regulator-name = "dvfs"; - regulator-min-microvolt = <750000>; - regulator-max-microvolt = <1030000>; - regulator-boot-on; - regulator-always-on; - }; - }; - }; diff --git a/Documentation/devicetree/bindings/mfd/brcm,twd.yaml b/Documentation/devicetree/bindings/mfd/brcm,twd.yaml new file mode 100644 index 000000000000..634526f790b8 --- /dev/null +++ b/Documentation/devicetree/bindings/mfd/brcm,twd.yaml @@ -0,0 +1,61 @@ +# SPDX-License-Identifier: GPL-2.0-only OR BSD-2-Clause +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/mfd/brcm,twd.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Broadcom's Timer-Watchdog (aka TWD) + +maintainers: + - Rafał Miłecki <rafal@milecki.pl> + +description: | + Broadcom has a Timer-Watchdog block used in multiple SoCs (e.g., BCM4908, + BCM63xx, BCM7038). There are few variants available (they differ slightly in + registers layout). This block consists of: timers, watchdog and optionally a + software reset handler. + +properties: + compatible: + items: + - enum: + - brcm,bcm4908-twd + - brcm,bcm7038-twd + - const: simple-mfd + - const: syscon + + reg: + maxItems: 1 + + ranges: true + + "#address-cells": + const: 1 + + "#size-cells": + const: 1 + +patternProperties: + '^watchdog@[a-f0-9]+$': + $ref: /schemas/watchdog/brcm,bcm7038-wdt.yaml + +additionalProperties: false + +required: + - reg + +examples: + - | + timer-mfd@ff800400 { + compatible = "brcm,bcm4908-twd", "simple-mfd", "syscon"; + reg = <0xff800400 0x4c>; + ranges = <0x00000000 0xff800400 0x4c>; + + #address-cells = <1>; + #size-cells = <1>; + + watchdog@28 { + compatible = "brcm,bcm7038-wdt"; + reg = <0x28 0x8>; + }; + }; diff --git a/Documentation/devicetree/bindings/mfd/da9063.txt b/Documentation/devicetree/bindings/mfd/da9063.txt index 8da879935c59..91b79a21d403 100644 --- a/Documentation/devicetree/bindings/mfd/da9063.txt +++ b/Documentation/devicetree/bindings/mfd/da9063.txt @@ -1,6 +1,6 @@ * Dialog DA9063/DA9063L Power Management Integrated Circuit (PMIC) -DA9093 consists of a large and varied group of sub-devices (I2C Only): +DA9063 consists of a large and varied group of sub-devices (I2C Only): Device Supply Names Description ------ ------------ ----------- diff --git a/Documentation/devicetree/bindings/mfd/google,cros-ec.yaml b/Documentation/devicetree/bindings/mfd/google,cros-ec.yaml index d793dd0316b7..0faa4da6c7c8 100644 --- a/Documentation/devicetree/bindings/mfd/google,cros-ec.yaml +++ b/Documentation/devicetree/bindings/mfd/google,cros-ec.yaml @@ -59,7 +59,7 @@ properties: whether this nvram is present or not. type: boolean - mtk,rpmsg-name: + mediatek,rpmsg-name: description: Must be defined if the cros-ec is a rpmsg device for a Mediatek ARM Cortex M4 Co-processor. Contains the name pf the rpmsg diff --git a/Documentation/devicetree/bindings/mfd/max77686.txt b/Documentation/devicetree/bindings/mfd/max77686.txt deleted file mode 100644 index 4447d074894a..000000000000 --- a/Documentation/devicetree/bindings/mfd/max77686.txt +++ /dev/null @@ -1,26 +0,0 @@ -Maxim MAX77686 multi-function device - -MAX77686 is a Multifunction device with PMIC, RTC and Charger on chip. It is -interfaced to host controller using i2c interface. PMIC and Charger submodules -are addressed using same i2c slave address whereas RTC submodule uses -different i2c slave address,presently for which we are statically creating i2c -client while probing.This document describes the binding for mfd device and -PMIC submodule. - -Bindings for the built-in 32k clock generator block and -regulators are defined in ../clk/maxim,max77686.txt and -../regulator/max77686.txt respectively. - -Required properties: -- compatible : Must be "maxim,max77686"; -- reg : Specifies the i2c slave address of PMIC block. -- interrupts : This i2c device has an IRQ line connected to the main SoC. - -Example: - - max77686: pmic@9 { - compatible = "maxim,max77686"; - interrupt-parent = <&wakeup_eint>; - interrupts = <26 IRQ_TYPE_LEVEL_LOW>; - reg = <0x09>; - }; diff --git a/Documentation/devicetree/bindings/mfd/maxim,max77686.yaml b/Documentation/devicetree/bindings/mfd/maxim,max77686.yaml new file mode 100644 index 000000000000..859655a789c3 --- /dev/null +++ b/Documentation/devicetree/bindings/mfd/maxim,max77686.yaml @@ -0,0 +1,132 @@ +# SPDX-License-Identifier: GPL-2.0-only OR BSD-2-Clause +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/mfd/maxim,max77686.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Maxim MAX77686 Power Management IC + +maintainers: + - Chanwoo Choi <cw00.choi@samsung.com> + - Krzysztof Kozlowski <krzysztof.kozlowski@canonical.com> + +description: | + This is a part of device tree bindings for Maxim MAX77686 Power Management + Integrated Circuit (PMIC). + + The Maxim MAX77686 is a Power Management IC which includes voltage and + current regulators, RTC and clock outputs. + + The MAX77686 provides three 32.768khz clock outputs that can be controlled + (gated/ungated) over I2C. The clock IDs are defined as preprocessor macros + in dt-bindings/clock/maxim,max77686.h. + +properties: + compatible: + const: maxim,max77686 + + '#clock-cells': + const: 1 + + interrupts: + maxItems: 1 + + reg: + maxItems: 1 + + voltage-regulators: + $ref: ../regulator/maxim,max77686.yaml + description: + List of child nodes that specify the regulators. + + wakeup-source: true + +required: + - compatible + - '#clock-cells' + - reg + +additionalProperties: false + +examples: + - | + #include <dt-bindings/gpio/gpio.h> + #include <dt-bindings/interrupt-controller/irq.h> + + i2c { + #address-cells = <1>; + #size-cells = <0>; + + max77686: pmic@9 { + compatible = "maxim,max77686"; + reg = <0x09>; + + interrupt-parent = <&gpx0>; + interrupts = <7 IRQ_TYPE_LEVEL_LOW>; + pinctrl-0 = <&max77686_irq>; + pinctrl-names = "default"; + wakeup-source; + #clock-cells = <1>; + + voltage-regulators { + LDO1 { + regulator-name = "VALIVE_1.0V_AP"; + regulator-min-microvolt = <1000000>; + regulator-max-microvolt = <1000000>; + regulator-always-on; + }; + + LDO2 { + regulator-name = "VM1M2_1.2V_AP"; + regulator-min-microvolt = <1200000>; + regulator-max-microvolt = <1200000>; + regulator-always-on; + regulator-state-mem { + regulator-on-in-suspend; + }; + }; + + // ... + + LDO22 { + regulator-name = "VMEM_VDD_2.8V"; + regulator-min-microvolt = <2800000>; + regulator-max-microvolt = <2800000>; + maxim,ena-gpios = <&gpk0 2 GPIO_ACTIVE_HIGH>; + }; + + // ... + + BUCK1 { + regulator-name = "VDD_MIF"; + regulator-min-microvolt = <850000>; + regulator-max-microvolt = <1100000>; + regulator-always-on; + regulator-boot-on; + regulator-state-mem { + regulator-off-in-suspend; + }; + }; + + BUCK2 { + regulator-name = "VDD_ARM"; + regulator-min-microvolt = <850000>; + regulator-max-microvolt = <1500000>; + regulator-always-on; + regulator-boot-on; + regulator-state-mem { + regulator-on-in-suspend; + }; + }; + + // ... + + BUCK9 { + regulator-name = "CAM_ISP_CORE_1.2V"; + regulator-min-microvolt = <1000000>; + regulator-max-microvolt = <1200000>; + maxim,ena-gpios = <&gpm0 3 GPIO_ACTIVE_HIGH>; + }; + }; + }; + }; diff --git a/Documentation/devicetree/bindings/mfd/rohm,bd70528-pmic.txt b/Documentation/devicetree/bindings/mfd/rohm,bd70528-pmic.txt deleted file mode 100644 index 386eec06cf08..000000000000 --- a/Documentation/devicetree/bindings/mfd/rohm,bd70528-pmic.txt +++ /dev/null @@ -1,102 +0,0 @@ -* ROHM BD70528 Power Management Integrated Circuit bindings - -BD70528MWV is an ultra-low quiescent current general purpose, single-chip, -power management IC for battery-powered portable devices. The IC -integrates 3 ultra-low current consumption buck converters, 3 LDOs and 2 -LED Drivers. Also included are 4 GPIOs, a real-time clock (RTC), a 32kHz -clock gate, high-accuracy VREF for use with an external ADC, flexible -dual-input power path, 10 bit SAR ADC for battery temperature monitor and -1S battery charger with scalable charge currents. - -Required properties: - - compatible : Should be "rohm,bd70528" - - reg : I2C slave address. - - interrupts : The interrupt line the device is connected to. - - interrupt-controller : To indicate BD70528 acts as an interrupt controller. - - #interrupt-cells : Should be 2. Usage is compliant to the 2 cells - variant of ../interrupt-controller/interrupts.txt - - gpio-controller : To indicate BD70528 acts as a GPIO controller. - - #gpio-cells : Should be 2. The first cell is the pin number and - the second cell is used to specify flags. See - ../gpio/gpio.txt for more information. - - #clock-cells : Should be 0. - - regulators: : List of child nodes that specify the regulators. - Please see ../regulator/rohm,bd70528-regulator.txt - -Optional properties: - - clock-output-names : Should contain name for output clock. - -Example: -/* External oscillator */ -osc: oscillator { - compatible = "fixed-clock"; - #clock-cells = <1>; - clock-frequency = <32768>; - clock-output-names = "osc"; -}; - -pmic: pmic@4b { - compatible = "rohm,bd70528"; - reg = <0x4b>; - interrupt-parent = <&gpio1>; - interrupts = <29 IRQ_TYPE_LEVEL_LOW>; - clocks = <&osc 0>; - #clock-cells = <0>; - clock-output-names = "bd70528-32k-out"; - #gpio-cells = <2>; - gpio-controller; - interrupt-controller; - #interrupt-cells = <2>; - - regulators { - buck1: BUCK1 { - regulator-name = "buck1"; - regulator-min-microvolt = <1200000>; - regulator-max-microvolt = <3400000>; - regulator-boot-on; - regulator-ramp-delay = <125>; - }; - buck2: BUCK2 { - regulator-name = "buck2"; - regulator-min-microvolt = <1200000>; - regulator-max-microvolt = <3300000>; - regulator-boot-on; - regulator-ramp-delay = <125>; - }; - buck3: BUCK3 { - regulator-name = "buck3"; - regulator-min-microvolt = <800000>; - regulator-max-microvolt = <1800000>; - regulator-boot-on; - regulator-ramp-delay = <250>; - }; - ldo1: LDO1 { - regulator-name = "ldo1"; - regulator-min-microvolt = <1650000>; - regulator-max-microvolt = <3300000>; - regulator-boot-on; - }; - ldo2: LDO2 { - regulator-name = "ldo2"; - regulator-min-microvolt = <1650000>; - regulator-max-microvolt = <3300000>; - regulator-boot-on; - }; - - ldo3: LDO3 { - regulator-name = "ldo3"; - regulator-min-microvolt = <1650000>; - regulator-max-microvolt = <3300000>; - }; - led_ldo1: LED_LDO1 { - regulator-name = "led_ldo1"; - regulator-min-microvolt = <200000>; - regulator-max-microvolt = <300000>; - }; - led_ldo2: LED_LDO2 { - regulator-name = "led_ldo2"; - regulator-min-microvolt = <200000>; - regulator-max-microvolt = <300000>; - }; - }; -}; diff --git a/Documentation/devicetree/bindings/mfd/rohm,bd9571mwv.yaml b/Documentation/devicetree/bindings/mfd/rohm,bd9571mwv.yaml new file mode 100644 index 000000000000..89f9efee465b --- /dev/null +++ b/Documentation/devicetree/bindings/mfd/rohm,bd9571mwv.yaml @@ -0,0 +1,127 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/mfd/rohm,bd9571mwv.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: ROHM BD9571MWV/BD9574MWF Power Management Integrated Circuit (PMIC) + +maintainers: + - Marek Vasut <marek.vasut@gmail.com> + +properties: + compatible: + enum: + - rohm,bd9571mwv + - rohm,bd9574mwf + + reg: + maxItems: 1 + + interrupts: + maxItems: 1 + + interrupt-controller: true + + '#interrupt-cells': + const: 2 + + gpio-controller: true + + '#gpio-cells': + const: 2 + + rohm,ddr-backup-power: + $ref: /schemas/types.yaml#/definitions/uint32 + minimum: 0x0 + maximum: 0xf + description: | + Value to use for DDR-Backup Power (default 0). + This is a bitmask that specifies which DDR power rails need to be kept + powered when backup mode is entered, for system suspend: + - bit 0: DDR0 + - bit 1: DDR1 + - bit 2: DDR0C + - bit 3: DDR1C + These bits match the KEEPON_DDR* bits in the documentation for the "BKUP + Mode Cnt" register. + + rohm,rstbmode-level: + $ref: /schemas/types.yaml#/definitions/flag + description: + The RSTB signal is configured for level mode, to accommodate a toggle + power switch (the RSTBMODE pin is strapped low). + + rohm,rstbmode-pulse: + $ref: /schemas/types.yaml#/definitions/flag + description: + The RSTB signal is configured for pulse mode, to accommodate a momentary + power switch (the RSTBMODE pin is strapped high). + + regulators: + type: object + description: + List of child nodes that specify the regulator initialization data. + Child nodes must be named after their hardware counterparts. + + patternProperties: + "^(vd09|vd18|vd25|vd33|dvfs)$": + type: object + $ref: ../regulator/regulator.yaml# + + properties: + regulator-name: + pattern: "^(vd09|vd18|vd25|vd33|dvfs)$" + + unevaluatedProperties: false + + additionalProperties: false + +additionalProperties: false + +required: + - compatible + - reg + - interrupts + - interrupt-controller + - '#interrupt-cells' + - gpio-controller + - '#gpio-cells' + +oneOf: + - required: + - rohm,rstbmode-level + - required: + - rohm,rstbmode-pulse + +examples: + - | + #include <dt-bindings/interrupt-controller/irq.h> + + i2c { + #address-cells = <1>; + #size-cells = <0>; + + pmic: pmic@30 { + compatible = "rohm,bd9571mwv"; + reg = <0x30>; + interrupt-parent = <&gpio2>; + interrupts = <0 IRQ_TYPE_LEVEL_LOW>; + interrupt-controller; + #interrupt-cells = <2>; + gpio-controller; + #gpio-cells = <2>; + rohm,ddr-backup-power = <0xf>; + rohm,rstbmode-pulse; + + regulators { + dvfs: dvfs { + regulator-name = "dvfs"; + regulator-min-microvolt = <750000>; + regulator-max-microvolt = <1030000>; + regulator-boot-on; + regulator-always-on; + }; + }; + }; + }; diff --git a/Documentation/devicetree/bindings/mfd/syscon.yaml b/Documentation/devicetree/bindings/mfd/syscon.yaml index 5de16388a089..eeac1cbc5a17 100644 --- a/Documentation/devicetree/bindings/mfd/syscon.yaml +++ b/Documentation/devicetree/bindings/mfd/syscon.yaml @@ -39,6 +39,7 @@ properties: - allwinner,sun8i-v3s-system-controller - allwinner,sun50i-a64-system-controller - brcm,cru-clkset + - freecom,fsg-cs2-system-controller - hisilicon,dsa-subctrl - hisilicon,hi6220-sramctrl - hisilicon,pcie-sas-subctrl @@ -57,6 +58,7 @@ properties: - samsung,exynos4-sysreg - samsung,exynos5-sysreg - samsung,exynos5433-sysreg + - samsung,exynos850-sysreg - samsung,exynosautov9-sysreg - const: syscon diff --git a/Documentation/devicetree/bindings/misc/nvidia,tegra186-misc.txt b/Documentation/devicetree/bindings/misc/nvidia,tegra186-misc.txt deleted file mode 100644 index 43d777ed8316..000000000000 --- a/Documentation/devicetree/bindings/misc/nvidia,tegra186-misc.txt +++ /dev/null @@ -1,14 +0,0 @@ -NVIDIA Tegra186 (and later) MISC register block - -The MISC register block found on Tegra186 and later SoCs contains registers -that can be used to identify a given chip and various strapping options. - -Required properties: -- compatible: Must be: - - Tegra186: "nvidia,tegra186-misc" - - Tegra194: "nvidia,tegra194-misc" - - Tegra234: "nvidia,tegra234-misc" -- reg: Should contain 2 entries: The first entry gives the physical address - and length of the register region which contains revision and debug - features. The second entry specifies the physical address and length - of the register region indicating the strapping options. diff --git a/Documentation/devicetree/bindings/misc/nvidia,tegra186-misc.yaml b/Documentation/devicetree/bindings/misc/nvidia,tegra186-misc.yaml new file mode 100644 index 000000000000..cacb845868f4 --- /dev/null +++ b/Documentation/devicetree/bindings/misc/nvidia,tegra186-misc.yaml @@ -0,0 +1,43 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/misc/nvidia,tegra186-misc.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: NVIDIA Tegra186 (and later) MISC register block + +maintainers: + - Thierry Reding <thierry.reding@gmail.com> + - Jon Hunter <jonathanh@nvidia.com> + +description: The MISC register block found on Tegra186 and later SoCs contains + registers that can be used to identify a given chip and various strapping + options. + +properties: + compatible: + enum: + - nvidia,tegra186-misc + - nvidia,tegra194-misc + - nvidia,tegra234-misc + + reg: + items: + - description: physical address and length of the registers which + contain revision and debug features + - description: physical address and length of the registers which + indicate strapping options + +additionalProperties: false + +required: + - compatible + - reg + +examples: + - | + misc@100000 { + compatible = "nvidia,tegra186-misc"; + reg = <0x00100000 0xf000>, + <0x0010f000 0x1000>; + }; diff --git a/Documentation/devicetree/bindings/misc/nvidia,tegra20-apbmisc.txt b/Documentation/devicetree/bindings/misc/nvidia,tegra20-apbmisc.txt deleted file mode 100644 index 83f6a251ba3e..000000000000 --- a/Documentation/devicetree/bindings/misc/nvidia,tegra20-apbmisc.txt +++ /dev/null @@ -1,17 +0,0 @@ -NVIDIA Tegra APBMISC block - -Required properties: -- compatible: Must be: - - Tegra20: "nvidia,tegra20-apbmisc" - - Tegra30: "nvidia,tegra30-apbmisc", "nvidia,tegra20-apbmisc" - - Tegra114: "nvidia,tegra114-apbmisc", "nvidia,tegra20-apbmisc" - - Tegra124: "nvidia,tegra124-apbmisc", "nvidia,tegra20-apbmisc" - - Tegra132: "nvidia,tegra124-apbmisc", "nvidia,tegra20-apbmisc" - - Tegra210: "nvidia,tegra210-apbmisc", "nvidia,tegra20-apbmisc" -- reg: Should contain 2 entries: the first entry gives the physical address - and length of the registers which contain revision and debug features. - The second entry gives the physical address and length of the - registers indicating the strapping options. - -Optional properties: -- nvidia,long-ram-code: If present, the RAM code is long (4 bit). If not, short (2 bit). diff --git a/Documentation/devicetree/bindings/misc/nvidia,tegra20-apbmisc.yaml b/Documentation/devicetree/bindings/misc/nvidia,tegra20-apbmisc.yaml new file mode 100644 index 000000000000..6f504fa74007 --- /dev/null +++ b/Documentation/devicetree/bindings/misc/nvidia,tegra20-apbmisc.yaml @@ -0,0 +1,51 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/misc/nvidia,tegra20-apbmisc.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: NVIDIA Tegra APBMISC block + +maintainers: + - Thierry Reding <thierry.reding@gmail.com> + - Jon Hunter <jonathanh@nvidia.com> + +properties: + compatible: + oneOf: + - items: + - enum: + - nvidia,tegra210-apbmisc + - nvidia,tegra124-apbmisc + - nvidia,tegra114-apbmisc + - nvidia,tegra30-apbmisc + - const: nvidia,tegra20-apbmisc + + - items: + - const: nvidia,tegra20-apbmisc + + reg: + items: + - description: physical address and length of the registers which + contain revision and debug features + - description: physical address and length of the registers which + indicate strapping options + + nvidia,long-ram-code: + description: If present, the RAM code is long (4 bit). If not, short + (2 bit). + type: boolean + +additionalProperties: false + +required: + - compatible + - reg + +examples: + - | + apbmisc@70000800 { + compatible = "nvidia,tegra20-apbmisc"; + reg = <0x70000800 0x64>, /* Chip revision */ + <0x70000008 0x04>; /* Strapping options */ + }; diff --git a/Documentation/devicetree/bindings/mmc/arasan,sdhci.yaml b/Documentation/devicetree/bindings/mmc/arasan,sdhci.yaml index de6f076e0ece..83be9e93d221 100644 --- a/Documentation/devicetree/bindings/mmc/arasan,sdhci.yaml +++ b/Documentation/devicetree/bindings/mmc/arasan,sdhci.yaml @@ -118,6 +118,9 @@ properties: phy-names: const: phy_arasan + resets: + maxItems: 1 + arasan,soc-ctl-syscon: $ref: /schemas/types.yaml#/definitions/phandle description: diff --git a/Documentation/devicetree/bindings/mmc/arm,pl18x.yaml b/Documentation/devicetree/bindings/mmc/arm,pl18x.yaml index 47595cb483be..a4f74bec68a3 100644 --- a/Documentation/devicetree/bindings/mmc/arm,pl18x.yaml +++ b/Documentation/devicetree/bindings/mmc/arm,pl18x.yaml @@ -53,6 +53,12 @@ properties: items: - const: arm,pl18x - const: arm,primecell + - description: Entry for STMicroelectronics variant of PL18x. + This dedicated compatible is used by bootloaders. + items: + - const: st,stm32-sdmmc2 + - const: arm,pl18x + - const: arm,primecell clocks: description: One or two clocks, the "apb_pclk" and the "MCLK" @@ -60,6 +66,18 @@ properties: minItems: 1 maxItems: 2 + dmas: + maxItems: 2 + + dma-names: + oneOf: + - items: + - const: tx + - const: rx + - items: + - const: rx + - const: tx + power-domains: true resets: @@ -213,7 +231,6 @@ examples: arm,primecell-periphid = <0x10153180>; reg = <0x52007000 0x1000>; interrupts = <49>; - interrupt-names = "cmd_irq"; clocks = <&rcc 0>; clock-names = "apb_pclk"; resets = <&rcc 1>; diff --git a/Documentation/devicetree/bindings/mmc/brcm,sdhci-brcmstb.txt b/Documentation/devicetree/bindings/mmc/brcm,sdhci-brcmstb.txt deleted file mode 100644 index ae2074184528..000000000000 --- a/Documentation/devicetree/bindings/mmc/brcm,sdhci-brcmstb.txt +++ /dev/null @@ -1,53 +0,0 @@ -* BROADCOM BRCMSTB/BMIPS SDHCI Controller - -This file documents differences between the core properties in mmc.txt -and the properties used by the sdhci-brcmstb driver. - -NOTE: The driver disables all UHS speed modes by default and depends -on Device Tree properties to enable them for SoC/Board combinations -that support them. - -Required properties: -- compatible: should be one of the following - - "brcm,bcm7425-sdhci" - - "brcm,bcm7445-sdhci" - - "brcm,bcm7216-sdhci" - -Refer to clocks/clock-bindings.txt for generic clock consumer properties. - -Example: - - sdhci@84b0000 { - sd-uhs-sdr50; - sd-uhs-ddr50; - sd-uhs-sdr104; - sdhci,auto-cmd12; - compatible = "brcm,bcm7216-sdhci", - "brcm,bcm7445-sdhci", - "brcm,sdhci-brcmstb"; - reg = <0x84b0000 0x260 0x84b0300 0x200>; - reg-names = "host", "cfg"; - interrupts = <0x0 0x26 0x4>; - interrupt-names = "sdio0_0"; - clocks = <&scmi_clk 245>; - clock-names = "sw_sdio"; - }; - - sdhci@84b1000 { - mmc-ddr-1_8v; - mmc-hs200-1_8v; - mmc-hs400-1_8v; - mmc-hs400-enhanced-strobe; - supports-cqe; - non-removable; - bus-width = <0x8>; - compatible = "brcm,bcm7216-sdhci", - "brcm,bcm7445-sdhci", - "brcm,sdhci-brcmstb"; - reg = <0x84b1000 0x260 0x84b1300 0x200>; - reg-names = "host", "cfg"; - interrupts = <0x0 0x27 0x4>; - interrupt-names = "sdio1_0"; - clocks = <&scmi_clk 245>; - clock-names = "sw_sdio"; - }; diff --git a/Documentation/devicetree/bindings/mmc/brcm,sdhci-brcmstb.yaml b/Documentation/devicetree/bindings/mmc/brcm,sdhci-brcmstb.yaml new file mode 100644 index 000000000000..dccd5ad96981 --- /dev/null +++ b/Documentation/devicetree/bindings/mmc/brcm,sdhci-brcmstb.yaml @@ -0,0 +1,100 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/mmc/brcm,sdhci-brcmstb.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Broadcom BRCMSTB/BMIPS SDHCI Controller binding + +maintainers: + - Al Cooper <alcooperx@gmail.com> + - Florian Fainelli <f.fainelli@gmail.com> + +allOf: + - $ref: mmc-controller.yaml# + +properties: + compatible: + oneOf: + - items: + - enum: + - brcm,bcm7216-sdhci + - const: brcm,bcm7445-sdhci + - const: brcm,sdhci-brcmstb + - items: + - enum: + - brcm,bcm7445-sdhci + - const: brcm,sdhci-brcmstb + - items: + - enum: + - brcm,bcm7425-sdhci + - const: brcm,sdhci-brcmstb + + reg: + minItems: 2 + + reg-names: + items: + - const: host + - const: cfg + + interrupts: + maxItems: 1 + + clocks: + maxItems: 1 + description: + handle to core clock for the sdhci controller. + + clock-names: + items: + - const: sw_sdio + + sdhci,auto-cmd12: + type: boolean + description: Specifies that controller should use auto CMD12 + +required: + - compatible + - reg + - interrupts + - clocks + +unevaluatedProperties: false + +examples: + - | + mmc@84b0000 { + sd-uhs-sdr50; + sd-uhs-ddr50; + sd-uhs-sdr104; + sdhci,auto-cmd12; + compatible = "brcm,bcm7216-sdhci", + "brcm,bcm7445-sdhci", + "brcm,sdhci-brcmstb"; + reg = <0x84b0000 0x260>, <0x84b0300 0x200>; + reg-names = "host", "cfg"; + interrupts = <0x0 0x26 0x4>; + interrupt-names = "sdio0_0"; + clocks = <&scmi_clk 245>; + clock-names = "sw_sdio"; + }; + + mmc@84b1000 { + mmc-ddr-1_8v; + mmc-hs200-1_8v; + mmc-hs400-1_8v; + mmc-hs400-enhanced-strobe; + supports-cqe; + non-removable; + bus-width = <0x8>; + compatible = "brcm,bcm7216-sdhci", + "brcm,bcm7445-sdhci", + "brcm,sdhci-brcmstb"; + reg = <0x84b1000 0x260>, <0x84b1300 0x200>; + reg-names = "host", "cfg"; + interrupts = <0x0 0x27 0x4>; + interrupt-names = "sdio1_0"; + clocks = <&scmi_clk 245>; + clock-names = "sw_sdio"; + }; diff --git a/Documentation/devicetree/bindings/mmc/exynos-dw-mshc.txt b/Documentation/devicetree/bindings/mmc/exynos-dw-mshc.txt index 0419a63f73a0..753e9d7d8956 100644 --- a/Documentation/devicetree/bindings/mmc/exynos-dw-mshc.txt +++ b/Documentation/devicetree/bindings/mmc/exynos-dw-mshc.txt @@ -22,6 +22,8 @@ Required Properties: specific extensions. - "samsung,exynos7-dw-mshc-smu": for controllers with Samsung Exynos7 specific extensions having an SMU. + - "axis,artpec8-dw-mshc": for controllers with ARTPEC-8 specific + extensions. * samsung,dw-mshc-ciu-div: Specifies the divider value for the card interface unit (ciu) clock. This property is applicable only for Exynos5 SoC's and diff --git a/Documentation/devicetree/bindings/mmc/fsl-imx-esdhc.yaml b/Documentation/devicetree/bindings/mmc/fsl-imx-esdhc.yaml index 19621a2f8beb..17acbc665f5a 100644 --- a/Documentation/devicetree/bindings/mmc/fsl-imx-esdhc.yaml +++ b/Documentation/devicetree/bindings/mmc/fsl-imx-esdhc.yaml @@ -34,6 +34,7 @@ properties: - fsl,imx6ull-usdhc - fsl,imx7d-usdhc - fsl,imx7ulp-usdhc + - fsl,imxrt1050-usdhc - nxp,s32g2-usdhc - items: - enum: @@ -44,6 +45,10 @@ properties: - fsl,imx8qm-usdhc - fsl,imx8qxp-usdhc - const: fsl,imx7d-usdhc + - items: + - enum: + - fsl,imx8ulp-usdhc + - const: fsl,imx8mm-usdhc reg: maxItems: 1 @@ -116,6 +121,9 @@ properties: - const: ahb - const: per + power-domains: + maxItems: 1 + pinctrl-names: oneOf: - minItems: 3 diff --git a/Documentation/devicetree/bindings/mmc/img-dw-mshc.txt b/Documentation/devicetree/bindings/mmc/img-dw-mshc.txt deleted file mode 100644 index c54e577eea07..000000000000 --- a/Documentation/devicetree/bindings/mmc/img-dw-mshc.txt +++ /dev/null @@ -1,28 +0,0 @@ -* Imagination specific extensions to the Synopsys Designware Mobile Storage - Host Controller - -The Synopsys designware mobile storage host controller is used to interface -a SoC with storage medium such as eMMC or SD/MMC cards. This file documents -differences between the core Synopsys dw mshc controller properties described -by synopsys-dw-mshc.txt and the properties used by the Imagination specific -extensions to the Synopsys Designware Mobile Storage Host Controller. - -Required Properties: - -* compatible: should be - - "img,pistachio-dw-mshc": for Pistachio SoCs - -Example: - - mmc@18142000 { - compatible = "img,pistachio-dw-mshc"; - reg = <0x18142000 0x400>; - interrupts = <GIC_SHARED 39 IRQ_TYPE_LEVEL_HIGH>; - - clocks = <&system_clk>, <&sdhost_clk>; - clock-names = "biu", "ciu"; - - fifo-depth = <0x20>; - bus-width = <4>; - disable-wp; - }; diff --git a/Documentation/devicetree/bindings/mmc/ingenic,mmc.yaml b/Documentation/devicetree/bindings/mmc/ingenic,mmc.yaml index 01d5c6da0eeb..2d10aedf2e00 100644 --- a/Documentation/devicetree/bindings/mmc/ingenic,mmc.yaml +++ b/Documentation/devicetree/bindings/mmc/ingenic,mmc.yaml @@ -39,14 +39,15 @@ properties: const: mmc dmas: - items: - - description: DMA controller phandle and request line for RX - - description: DMA controller phandle and request line for TX + minItems: 1 + maxItems: 2 dma-names: - items: - - const: rx - - const: tx + oneOf: + - items: + - const: rx + - const: tx + - const: tx-rx required: - compatible @@ -80,3 +81,27 @@ examples: <&dma JZ4780_DMA_MSC0_TX 0xffffffff>; dma-names = "rx", "tx"; }; + - | + #include <dt-bindings/clock/ingenic,jz4780-cgu.h> + #include <dt-bindings/dma/jz4780-dma.h> + /* + * Alternative version of the example above, + * but using one single DMA channel for both + * TX and RX. + */ + mmc1: mmc@13460000 { + compatible = "ingenic,jz4780-mmc"; + reg = <0x13460000 0x1000>; + + interrupt-parent = <&intc>; + interrupts = <36>; + + clocks = <&cgu JZ4780_CLK_MSC1>; + clock-names = "mmc"; + + cap-sd-highspeed; + cap-mmc-highspeed; + cap-sdio-irq; + dmas = <&dma JZ4780_DMA_MSC1_TX JZ4780_DMA_MSC1_RX 0xffffffff>; + dma-names = "tx-rx"; + }; diff --git a/Documentation/devicetree/bindings/mmc/mtk-sd.yaml b/Documentation/devicetree/bindings/mmc/mtk-sd.yaml index 82768a807294..faf89b0c918f 100644 --- a/Documentation/devicetree/bindings/mmc/mtk-sd.yaml +++ b/Documentation/devicetree/bindings/mmc/mtk-sd.yaml @@ -36,6 +36,9 @@ properties: - const: mediatek,mt8195-mmc - const: mediatek,mt8183-mmc + reg: + maxItems: 1 + clocks: description: Should contain phandle for the clock feeding the MMC controller. @@ -62,6 +65,9 @@ properties: - const: axi_cg - const: ahb_cg + interrupts: + maxItems: 1 + pinctrl-names: items: - const: default diff --git a/Documentation/devicetree/bindings/mmc/nvidia,tegra20-sdhci.txt b/Documentation/devicetree/bindings/mmc/nvidia,tegra20-sdhci.txt deleted file mode 100644 index 96c0b1440c9c..000000000000 --- a/Documentation/devicetree/bindings/mmc/nvidia,tegra20-sdhci.txt +++ /dev/null @@ -1,143 +0,0 @@ -* NVIDIA Tegra Secure Digital Host Controller - -This controller on Tegra family SoCs provides an interface for MMC, SD, -and SDIO types of memory cards. - -This file documents differences between the core properties described -by mmc.txt and the properties used by the sdhci-tegra driver. - -Required properties: -- compatible : should be one of: - - "nvidia,tegra20-sdhci": for Tegra20 - - "nvidia,tegra30-sdhci": for Tegra30 - - "nvidia,tegra114-sdhci": for Tegra114 - - "nvidia,tegra124-sdhci": for Tegra124 and Tegra132 - - "nvidia,tegra210-sdhci": for Tegra210 - - "nvidia,tegra186-sdhci": for Tegra186 - - "nvidia,tegra194-sdhci": for Tegra194 -- clocks: For Tegra210, Tegra186 and Tegra194 must contain two entries. - One for the module clock and one for the timeout clock. - For all other Tegra devices, must contain a single entry for - the module clock. See ../clocks/clock-bindings.txt for details. -- clock-names: For Tegra210, Tegra186 and Tegra194 must contain the - strings 'sdhci' and 'tmclk' to represent the module and - the timeout clocks, respectively. - For all other Tegra devices must contain the string 'sdhci' - to represent the module clock. -- resets : Must contain an entry for each entry in reset-names. - See ../reset/reset.txt for details. -- reset-names : Must include the following entries: - - sdhci - -Optional properties: -- power-gpios : Specify GPIOs for power control - -Example: - -sdhci@c8000200 { - compatible = "nvidia,tegra20-sdhci"; - reg = <0xc8000200 0x200>; - interrupts = <47>; - clocks = <&tegra_car 14>; - resets = <&tegra_car 14>; - reset-names = "sdhci"; - cd-gpios = <&gpio 69 0>; /* gpio PI5 */ - wp-gpios = <&gpio 57 0>; /* gpio PH1 */ - power-gpios = <&gpio 155 0>; /* gpio PT3 */ - bus-width = <8>; -}; - -Optional properties for Tegra210, Tegra186 and Tegra194: -- pinctrl-names, pinctrl-0, pinctrl-1 : Specify pad voltage - configurations. Valid pinctrl-names are "sdmmc-3v3" and "sdmmc-1v8" - for controllers supporting multiple voltage levels. The order of names - should correspond to the pin configuration states in pinctrl-0 and - pinctrl-1. -- pinctrl-names : "sdmmc-3v3-drv" and "sdmmc-1v8-drv" are applicable for - Tegra210 where pad config registers are in the pinmux register domain - for pull-up-strength and pull-down-strength values configuration when - using pads at 3V3 and 1V8 levels. -- nvidia,only-1-8-v : The presence of this property indicates that the - controller operates at a 1.8 V fixed I/O voltage. -- nvidia,pad-autocal-pull-up-offset-3v3, - nvidia,pad-autocal-pull-down-offset-3v3 : Specify drive strength - calibration offsets for 3.3 V signaling modes. -- nvidia,pad-autocal-pull-up-offset-1v8, - nvidia,pad-autocal-pull-down-offset-1v8 : Specify drive strength - calibration offsets for 1.8 V signaling modes. -- nvidia,pad-autocal-pull-up-offset-3v3-timeout, - nvidia,pad-autocal-pull-down-offset-3v3-timeout : Specify drive - strength used as a fallback in case the automatic calibration times - out on a 3.3 V signaling mode. -- nvidia,pad-autocal-pull-up-offset-1v8-timeout, - nvidia,pad-autocal-pull-down-offset-1v8-timeout : Specify drive - strength used as a fallback in case the automatic calibration times - out on a 1.8 V signaling mode. -- nvidia,pad-autocal-pull-up-offset-sdr104, - nvidia,pad-autocal-pull-down-offset-sdr104 : Specify drive strength - calibration offsets for SDR104 mode. -- nvidia,pad-autocal-pull-up-offset-hs400, - nvidia,pad-autocal-pull-down-offset-hs400 : Specify drive strength - calibration offsets for HS400 mode. -- nvidia,default-tap : Specify the default inbound sampling clock - trimmer value for non-tunable modes. -- nvidia,default-trim : Specify the default outbound clock trimmer - value. -- nvidia,dqs-trim : Specify DQS trim value for HS400 timing - - Notes on the pad calibration pull up and pulldown offset values: - - The property values are drive codes which are programmed into the - PD_OFFSET and PU_OFFSET sections of the - SDHCI_TEGRA_AUTO_CAL_CONFIG register. - - A higher value corresponds to higher drive strength. Please refer - to the reference manual of the SoC for correct values. - - The SDR104 and HS400 timing specific values are used in - corresponding modes if specified. - - Notes on tap and trim values: - - The values are used for compensating trace length differences - by adjusting the sampling point. - - The values are programmed to the Vendor Clock Control Register. - Please refer to the reference manual of the SoC for correct - values. - - The DQS trim values are only used on controllers which support - HS400 timing. Only SDMMC4 on Tegra210 and Tegra 186 supports - HS400. - -Example: -sdhci@700b0000 { - compatible = "nvidia,tegra124-sdhci"; - reg = <0x0 0x700b0000 0x0 0x200>; - interrupts = <GIC_SPI 14 IRQ_TYPE_LEVEL_HIGH>; - clocks = <&tegra_car TEGRA210_CLK_SDMMC1>; - clock-names = "sdhci"; - resets = <&tegra_car 14>; - reset-names = "sdhci"; - pinctrl-names = "sdmmc-3v3", "sdmmc-1v8"; - pinctrl-0 = <&sdmmc1_3v3>; - pinctrl-1 = <&sdmmc1_1v8>; - nvidia,pad-autocal-pull-up-offset-3v3 = <0x00>; - nvidia,pad-autocal-pull-down-offset-3v3 = <0x7d>; - nvidia,pad-autocal-pull-up-offset-1v8 = <0x7b>; - nvidia,pad-autocal-pull-down-offset-1v8 = <0x7b>; - status = "disabled"; -}; - -sdhci@700b0000 { - compatible = "nvidia,tegra210-sdhci"; - reg = <0x0 0x700b0000 0x0 0x200>; - interrupts = <GIC_SPI 14 IRQ_TYPE_LEVEL_HIGH>; - clocks = <&tegra_car TEGRA210_CLK_SDMMC1>, - <&tegra_car TEGRA210_CLK_SDMMC_LEGACY>; - clock-names = "sdhci", "tmclk"; - resets = <&tegra_car 14>; - reset-names = "sdhci"; - pinctrl-names = "sdmmc-3v3", "sdmmc-1v8"; - pinctrl-0 = <&sdmmc1_3v3>; - pinctrl-1 = <&sdmmc1_1v8>; - nvidia,pad-autocal-pull-up-offset-3v3 = <0x00>; - nvidia,pad-autocal-pull-down-offset-3v3 = <0x7d>; - nvidia,pad-autocal-pull-up-offset-1v8 = <0x7b>; - nvidia,pad-autocal-pull-down-offset-1v8 = <0x7b>; - status = "disabled"; -}; diff --git a/Documentation/devicetree/bindings/mmc/nvidia,tegra20-sdhci.yaml b/Documentation/devicetree/bindings/mmc/nvidia,tegra20-sdhci.yaml new file mode 100644 index 000000000000..ce64b3498378 --- /dev/null +++ b/Documentation/devicetree/bindings/mmc/nvidia,tegra20-sdhci.yaml @@ -0,0 +1,317 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/mmc/nvidia,tegra20-sdhci.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: NVIDIA Tegra Secure Digital Host Controller + +maintainers: + - Thierry Reding <thierry.reding@gmail.com> + - Jon Hunter <jonathanh@nvidia.com> + +description: | + This controller on Tegra family SoCs provides an interface for MMC, SD, and + SDIO types of memory cards. + + This file documents differences between the core properties described by + mmc-controller.yaml and the properties for the Tegra SDHCI controller. + +properties: + compatible: + oneOf: + - enum: + - nvidia,tegra20-sdhci + - nvidia,tegra30-sdhci + - nvidia,tegra114-sdhci + - nvidia,tegra124-sdhci + - nvidia,tegra210-sdhci + - nvidia,tegra186-sdhci + - nvidia,tegra194-sdhci + + - items: + - const: nvidia,tegra132-sdhci + - const: nvidia,tegra124-sdhci + + - items: + - enum: + - nvidia,tegra194-sdhci + - nvidia,tegra234-sdhci + - const: nvidia,tegra186-sdhci + + reg: + maxItems: 1 + + interrupts: + maxItems: 1 + + assigned-clocks: true + assigned-clock-parents: true + assigned-clock-rates: true + + clocks: + minItems: 1 + maxItems: 2 + + clock-names: + minItems: 1 + maxItems: 2 + + resets: + items: + - description: module reset + + reset-names: + items: + - const: sdhci + + power-gpios: + description: specify GPIOs for power control + maxItems: 1 + + interconnects: + items: + - description: memory read client + - description: memory write client + + interconnect-names: + items: + - const: dma-mem # read + - const: write + + iommus: + maxItems: 1 + + operating-points-v2: + $ref: "/schemas/types.yaml#/definitions/phandle" + + power-domains: + items: + - description: phandle to the core power domain + + nvidia,default-tap: + description: Specify the default inbound sampling clock trimmer value for + non-tunable modes. + + The values are used for compensating trace length differences by + adjusting the sampling point. The values are programmed to the Vendor + Clock Control Register. Please refer to the reference manual of the SoC + for correct values. + + The DQS trim values are only used on controllers which support HS400 + timing. Only SDMMC4 on Tegra210 and Tegra186 supports HS400. + $ref: "/schemas/types.yaml#/definitions/uint32" + + nvidia,default-trim: + description: Specify the default outbound clock trimmer value. + $ref: "/schemas/types.yaml#/definitions/uint32" + + nvidia,dqs-trim: + description: Specify DQS trim value for HS400 timing. + $ref: "/schemas/types.yaml#/definitions/uint32" + + nvidia,pad-autocal-pull-down-offset-1v8: + description: Specify drive strength calibration offsets for 1.8 V + signaling modes. + $ref: "/schemas/types.yaml#/definitions/uint32" + + nvidia,pad-autocal-pull-down-offset-1v8-timeout: + description: Specify drive strength used as a fallback in case the + automatic calibration times out on a 1.8 V signaling mode. + $ref: "/schemas/types.yaml#/definitions/uint32" + + nvidia,pad-autocal-pull-down-offset-3v3: + description: Specify drive strength calibration offsets for 3.3 V + signaling modes. + $ref: "/schemas/types.yaml#/definitions/uint32" + + nvidia,pad-autocal-pull-down-offset-3v3-timeout: + description: Specify drive strength used as a fallback in case the + automatic calibration times out on a 3.3 V signaling mode. + $ref: "/schemas/types.yaml#/definitions/uint32" + + nvidia,pad-autocal-pull-down-offset-sdr104: + description: Specify drive strength calibration offsets for SDR104 mode. + $ref: "/schemas/types.yaml#/definitions/uint32" + + nvidia,pad-autocal-pull-down-offset-hs400: + description: Specify drive strength calibration offsets for HS400 mode. + $ref: "/schemas/types.yaml#/definitions/uint32" + + nvidia,pad-autocal-pull-up-offset-1v8: + description: Specify drive strength calibration offsets for 1.8 V + signaling modes. + $ref: "/schemas/types.yaml#/definitions/uint32" + + nvidia,pad-autocal-pull-up-offset-1v8-timeout: + description: Specify drive strength used as a fallback in case the + automatic calibration times out on a 1.8 V signaling mode. + $ref: "/schemas/types.yaml#/definitions/uint32" + + nvidia,pad-autocal-pull-up-offset-3v3: + description: Specify drive strength calibration offsets for 3.3 V + signaling modes. + + The property values are drive codes which are programmed into the + PD_OFFSET and PU_OFFSET sections of the SDHCI_TEGRA_AUTO_CAL_CONFIG + register. A higher value corresponds to higher drive strength. Please + refer to the reference manual of the SoC for correct values. The SDR104 + and HS400 timing specific values are used in corresponding modes if + specified. + $ref: "/schemas/types.yaml#/definitions/uint32" + + nvidia,pad-autocal-pull-up-offset-3v3-timeout: + description: Specify drive strength used as a fallback in case the + automatic calibration times out on a 3.3 V signaling mode. + $ref: "/schemas/types.yaml#/definitions/uint32" + + nvidia,pad-autocal-pull-up-offset-sdr104: + description: Specify drive strength calibration offsets for SDR104 mode. + $ref: "/schemas/types.yaml#/definitions/uint32" + + nvidia,pad-autocal-pull-up-offset-hs400: + description: Specify drive strength calibration offsets for HS400 mode. + $ref: "/schemas/types.yaml#/definitions/uint32" + + nvidia,only-1-8v: + description: The presence of this property indicates that the controller + operates at a 1.8 V fixed I/O voltage. + $ref: "/schemas/types.yaml#/definitions/flag" + +required: + - compatible + - reg + - interrupts + - clocks + - resets + - reset-names + +allOf: + - $ref: "mmc-controller.yaml" + - if: + properties: + compatible: + contains: + enum: + - nvidia,tegra20-sdhci + - nvidia,tegra30-sdhci + - nvidia,tegra114-sdhci + - nvidia,tegra124-sdhci + clocks: + items: + - description: module clock + minItems: 1 + maxItems: 1 + else: + properties: + clocks: + items: + - description: module clock + - description: timeout clock + minItems: 2 + maxItems: 2 + clock-names: + items: + - const: sdhci + - const: tmclk + minItems: 2 + maxItems: 2 + required: + - clock-names + + - if: + properties: + compatible: + contains: + const: nvidia,tegra210-sdhci + then: + properties: + pinctrl-names: + oneOf: + - items: + - const: sdmmc-3v3 + description: pad configuration for 3.3 V + - const: sdmmc-1v8 + description: pad configuration for 1.8 V + - const: sdmmc-3v3-drv + description: pull-up/down configuration for 3.3 V + - const: sdmmc-1v8-drv + description: pull-up/down configuration for 1.8 V + - items: + - const: sdmmc-3v3-drv + description: pull-up/down configuration for 3.3 V + - const: sdmmc-1v8-drv + description: pull-up/down configuration for 1.8 V + - items: + - const: sdmmc-1v8-drv + description: pull-up/down configuration for 1.8 V + required: + - clock-names + - if: + properties: + compatible: + contains: + enum: + - nvidia,tegra186-sdhci + - nvidia,tegra194-sdhci + then: + properties: + pinctrl-names: + items: + - const: sdmmc-3v3 + description: pad configuration for 3.3 V + - const: sdmmc-1v8 + description: pad configuration for 1.8 V + required: + - clock-names + +unevaluatedProperties: false + +examples: + - | + #include <dt-bindings/interrupt-controller/arm-gic.h> + + mmc@c8000200 { + compatible = "nvidia,tegra20-sdhci"; + reg = <0xc8000200 0x200>; + interrupts = <47>; + clocks = <&tegra_car 14>; + resets = <&tegra_car 14>; + reset-names = "sdhci"; + cd-gpios = <&gpio 69 0>; /* gpio PI5 */ + wp-gpios = <&gpio 57 0>; /* gpio PH1 */ + power-gpios = <&gpio 155 0>; /* gpio PT3 */ + bus-width = <8>; + }; + + - | + #include <dt-bindings/clock/tegra210-car.h> + #include <dt-bindings/interrupt-controller/arm-gic.h> + + mmc@700b0000 { + compatible = "nvidia,tegra210-sdhci"; + reg = <0x700b0000 0x200>; + interrupts = <GIC_SPI 14 IRQ_TYPE_LEVEL_HIGH>; + clocks = <&tegra_car TEGRA210_CLK_SDMMC1>, + <&tegra_car TEGRA210_CLK_SDMMC_LEGACY>; + clock-names = "sdhci", "tmclk"; + resets = <&tegra_car 14>; + reset-names = "sdhci"; + pinctrl-names = "sdmmc-3v3", "sdmmc-1v8", + "sdmmc-3v3-drv", "sdmmc-1v8-drv"; + pinctrl-0 = <&sdmmc1_3v3>; + pinctrl-1 = <&sdmmc1_1v8>; + pinctrl-2 = <&sdmmc1_3v3_drv>; + pinctrl-3 = <&sdmmc1_1v8_drv>; + nvidia,pad-autocal-pull-up-offset-3v3 = <0x00>; + nvidia,pad-autocal-pull-down-offset-3v3 = <0x7d>; + nvidia,pad-autocal-pull-up-offset-1v8 = <0x7b>; + nvidia,pad-autocal-pull-down-offset-1v8 = <0x7b>; + nvidia,default-tap = <0x2>; + nvidia,default-trim = <0x4>; + assigned-clocks = <&tegra_car TEGRA210_CLK_SDMMC4>, + <&tegra_car TEGRA210_CLK_PLL_C4_OUT0>, + <&tegra_car TEGRA210_CLK_PLL_C4>; + assigned-clock-parents = <&tegra_car TEGRA210_CLK_PLL_C4_OUT0>; + assigned-clock-rates = <200000000>, <1000000000>, <1000000000>; + }; diff --git a/Documentation/devicetree/bindings/mmc/renesas,sdhi.yaml b/Documentation/devicetree/bindings/mmc/renesas,sdhi.yaml index 9f1e7092cf44..9ce6e06c19db 100644 --- a/Documentation/devicetree/bindings/mmc/renesas,sdhi.yaml +++ b/Documentation/devicetree/bindings/mmc/renesas,sdhi.yaml @@ -113,31 +113,51 @@ allOf: clocks: items: - description: IMCLK, SDHI channel main clock1. + - description: CLK_HS, SDHI channel High speed clock which operates + 4 times that of SDHI channel main clock1. - description: IMCLK2, SDHI channel main clock2. When this clock is turned off, external SD card detection cannot be detected. - - description: CLK_HS, SDHI channel High speed clock which operates - 4 times that of SDHI channel main clock1. - description: ACLK, SDHI channel bus clock. clock-names: items: - - const: imclk - - const: imclk2 - - const: clk_hs + - const: core + - const: clkh + - const: cd - const: aclk required: - clock-names - resets else: - properties: - clocks: - minItems: 1 - maxItems: 2 - clock-names: - minItems: 1 - items: - - const: core - - const: cd + if: + properties: + compatible: + contains: + enum: + - renesas,rcar-gen2-sdhi + - renesas,rcar-gen3-sdhi + then: + properties: + clocks: + minItems: 1 + maxItems: 3 + clock-names: + minItems: 1 + uniqueItems: true + items: + - const: core + - enum: [ clkh, cd ] + - const: cd + else: + properties: + clocks: + minItems: 1 + maxItems: 2 + clock-names: + minItems: 1 + items: + - const: core + - const: cd - if: properties: diff --git a/Documentation/devicetree/bindings/mmc/sdhci-am654.yaml b/Documentation/devicetree/bindings/mmc/sdhci-am654.yaml index 224303f5b913..9fbf16b3bc8d 100644 --- a/Documentation/devicetree/bindings/mmc/sdhci-am654.yaml +++ b/Documentation/devicetree/bindings/mmc/sdhci-am654.yaml @@ -48,6 +48,8 @@ properties: - const: clk_ahb - const: clk_xin + sdhci-caps-mask: true + # PHY output tap delays: # Used to delay the data valid window and align it to the sampling clock. # Binding needs to be provided for each supported speed mode otherwise the diff --git a/Documentation/devicetree/bindings/mmc/sdhci-msm.txt b/Documentation/devicetree/bindings/mmc/sdhci-msm.txt index 50841e2843fc..6a8cc261bf61 100644 --- a/Documentation/devicetree/bindings/mmc/sdhci-msm.txt +++ b/Documentation/devicetree/bindings/mmc/sdhci-msm.txt @@ -17,6 +17,7 @@ Required properties: "qcom,msm8974-sdhci", "qcom,sdhci-msm-v4" "qcom,msm8916-sdhci", "qcom,sdhci-msm-v4" "qcom,msm8992-sdhci", "qcom,sdhci-msm-v4" + "qcom,msm8994-sdhci", "qcom,sdhci-msm-v4" "qcom,msm8996-sdhci", "qcom,sdhci-msm-v4" "qcom,qcs404-sdhci", "qcom,sdhci-msm-v5" "qcom,sc7180-sdhci", "qcom,sdhci-msm-v5"; diff --git a/Documentation/devicetree/bindings/mmc/socfpga-dw-mshc.txt b/Documentation/devicetree/bindings/mmc/socfpga-dw-mshc.txt deleted file mode 100644 index 4897bea7e3f8..000000000000 --- a/Documentation/devicetree/bindings/mmc/socfpga-dw-mshc.txt +++ /dev/null @@ -1,23 +0,0 @@ -* Altera SOCFPGA specific extensions to the Synopsys Designware Mobile - Storage Host Controller - -The Synopsys designware mobile storage host controller is used to interface -a SoC with storage medium such as eMMC or SD/MMC cards. This file documents -differences between the core Synopsys dw mshc controller properties described -by synopsys-dw-mshc.txt and the properties used by the Altera SOCFPGA specific -extensions to the Synopsys Designware Mobile Storage Host Controller. - -Required Properties: - -* compatible: should be - - "altr,socfpga-dw-mshc": for Altera's SOCFPGA platform - -Example: - - mmc: dwmmc0@ff704000 { - compatible = "altr,socfpga-dw-mshc"; - reg = <0xff704000 0x1000>; - interrupts = <0 129 4>; - #address-cells = <1>; - #size-cells = <0>; - }; diff --git a/Documentation/devicetree/bindings/mmc/socionext,uniphier-sd.yaml b/Documentation/devicetree/bindings/mmc/socionext,uniphier-sd.yaml index 56f9ff12742d..a586fad0a46b 100644 --- a/Documentation/devicetree/bindings/mmc/socionext,uniphier-sd.yaml +++ b/Documentation/devicetree/bindings/mmc/socionext,uniphier-sd.yaml @@ -26,6 +26,12 @@ properties: clocks: maxItems: 1 + dmas: + maxItems: 1 + + dma-names: + const: rx-tx + reset-names: description: | There are three reset signals at maximum diff --git a/Documentation/devicetree/bindings/mmc/synopsys-dw-mshc.yaml b/Documentation/devicetree/bindings/mmc/synopsys-dw-mshc.yaml index 240abb6f102c..ae6d6fca79e2 100644 --- a/Documentation/devicetree/bindings/mmc/synopsys-dw-mshc.yaml +++ b/Documentation/devicetree/bindings/mmc/synopsys-dw-mshc.yaml @@ -15,7 +15,10 @@ maintainers: # Everything else is described in the common file properties: compatible: - const: snps,dw-mshc + enum: + - altr,socfpga-dw-mshc + - img,pistachio-dw-mshc + - snps,dw-mshc reg: maxItems: 1 diff --git a/Documentation/devicetree/bindings/mtd/jedec,spi-nor.yaml b/Documentation/devicetree/bindings/mtd/jedec,spi-nor.yaml index ed590d7c6e37..39421f7233e4 100644 --- a/Documentation/devicetree/bindings/mtd/jedec,spi-nor.yaml +++ b/Documentation/devicetree/bindings/mtd/jedec,spi-nor.yaml @@ -11,6 +11,7 @@ maintainers: allOf: - $ref: "mtd.yaml#" + - $ref: /schemas/spi/spi-peripheral-props.yaml# properties: compatible: @@ -88,7 +89,7 @@ patternProperties: "^otp(-[0-9]+)?$": type: object -additionalProperties: false +unevaluatedProperties: false examples: - | diff --git a/Documentation/devicetree/bindings/mtd/renesas-nandc.yaml b/Documentation/devicetree/bindings/mtd/renesas-nandc.yaml new file mode 100644 index 000000000000..2870d36361c4 --- /dev/null +++ b/Documentation/devicetree/bindings/mtd/renesas-nandc.yaml @@ -0,0 +1,61 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/mtd/renesas-nandc.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Renesas R-Car Gen3 & RZ/N1x NAND flash controller device tree bindings + +maintainers: + - Miquel Raynal <miquel.raynal@bootlin.com> + +allOf: + - $ref: "nand-controller.yaml" + +properties: + compatible: + oneOf: + - items: + - enum: + - renesas,r9a06g032-nandc + - const: renesas,rzn1-nandc + + reg: + maxItems: 1 + + interrupts: + maxItems: 1 + + clocks: + items: + - description: APB host controller clock + - description: External NAND bus clock + + clock-names: + items: + - const: hclk + - const: eclk + +required: + - compatible + - reg + - clocks + - clock-names + - interrupts + +unevaluatedProperties: false + +examples: + - | + #include <dt-bindings/interrupt-controller/arm-gic.h> + #include <dt-bindings/clock/r9a06g032-sysctrl.h> + + nand-controller@40102000 { + compatible = "renesas,r9a06g032-nandc", "renesas,rzn1-nandc"; + reg = <0x40102000 0x2000>; + interrupts = <GIC_SPI 58 IRQ_TYPE_LEVEL_HIGH>; + clocks = <&sysctrl R9A06G032_HCLK_NAND>, <&sysctrl R9A06G032_CLK_NAND>; + clock-names = "hclk", "eclk"; + #address-cells = <1>; + #size-cells = <0>; + }; diff --git a/Documentation/devicetree/bindings/mtd/ti,gpmc-nand.yaml b/Documentation/devicetree/bindings/mtd/ti,gpmc-nand.yaml index beb26b9bcfb2..4ac198814b7a 100644 --- a/Documentation/devicetree/bindings/mtd/ti,gpmc-nand.yaml +++ b/Documentation/devicetree/bindings/mtd/ti,gpmc-nand.yaml @@ -16,7 +16,10 @@ description: properties: compatible: - const: ti,omap2-nand + items: + - enum: + - ti,am64-nand + - ti,omap2-nand reg: maxItems: 1 @@ -53,6 +56,11 @@ properties: enum: [8, 16] default: 8 + rb-gpios: + description: + GPIO connection to R/B signal from NAND chip + maxItems: 1 + patternProperties: "@[0-9a-f]+$": $ref: "/schemas/mtd/partitions/partition.yaml" diff --git a/Documentation/devicetree/bindings/net/can/allwinner,sun4i-a10-can.yaml b/Documentation/devicetree/bindings/net/can/allwinner,sun4i-a10-can.yaml index a95960ee3feb..c93fe9d3ea82 100644 --- a/Documentation/devicetree/bindings/net/can/allwinner,sun4i-a10-can.yaml +++ b/Documentation/devicetree/bindings/net/can/allwinner,sun4i-a10-can.yaml @@ -17,6 +17,7 @@ properties: - const: allwinner,sun7i-a20-can - const: allwinner,sun4i-a10-can - const: allwinner,sun4i-a10-can + - const: allwinner,sun8i-r40-can reg: maxItems: 1 @@ -27,6 +28,19 @@ properties: clocks: maxItems: 1 + resets: + maxItems: 1 + +if: + properties: + compatible: + contains: + const: allwinner,sun8i-r40-can + +then: + required: + - resets + required: - compatible - reg @@ -47,5 +61,15 @@ examples: interrupts = <GIC_SPI 26 IRQ_TYPE_LEVEL_HIGH>; clocks = <&ccu CLK_APB1_CAN>; }; + - | + #define RST_BUS_CAN 68 + #define CLK_BUS_CAN 91 + can1: can@1c2bc00 { + compatible = "allwinner,sun8i-r40-can"; + reg = <0x01c2bc00 0x400>; + interrupts = <GIC_SPI 26 IRQ_TYPE_LEVEL_HIGH>; + clocks = <&ccu CLK_BUS_CAN>; + resets = <&ccu RST_BUS_CAN>; + }; ... diff --git a/Documentation/devicetree/bindings/net/dsa/dsa-port.yaml b/Documentation/devicetree/bindings/net/dsa/dsa-port.yaml new file mode 100644 index 000000000000..702df848a71d --- /dev/null +++ b/Documentation/devicetree/bindings/net/dsa/dsa-port.yaml @@ -0,0 +1,77 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/net/dsa/dsa-port.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Ethernet Switch port Device Tree Bindings + +maintainers: + - Andrew Lunn <andrew@lunn.ch> + - Florian Fainelli <f.fainelli@gmail.com> + - Vivien Didelot <vivien.didelot@gmail.com> + +description: + Ethernet switch port Description + +allOf: + - $ref: "http://devicetree.org/schemas/net/ethernet-controller.yaml#" + +properties: + reg: + description: Port number + + label: + description: + Describes the label associated with this port, which will become + the netdev name + $ref: /schemas/types.yaml#/definitions/string + + link: + description: + Should be a list of phandles to other switch's DSA port. This + port is used as the outgoing port towards the phandle ports. The + full routing information must be given, not just the one hop + routes to neighbouring switches + $ref: /schemas/types.yaml#/definitions/phandle-array + + ethernet: + description: + Should be a phandle to a valid Ethernet device node. This host + device is what the switch port is connected to + $ref: /schemas/types.yaml#/definitions/phandle + + dsa-tag-protocol: + description: + Instead of the default, the switch will use this tag protocol if + possible. Useful when a device supports multiple protocols and + the default is incompatible with the Ethernet device. + enum: + - dsa + - edsa + - ocelot + - ocelot-8021q + - seville + + phy-handle: true + + phy-mode: true + + fixed-link: true + + mac-address: true + + sfp: true + + managed: true + + rx-internal-delay-ps: true + + tx-internal-delay-ps: true + +required: + - reg + +additionalProperties: true + +... diff --git a/Documentation/devicetree/bindings/net/dsa/dsa.yaml b/Documentation/devicetree/bindings/net/dsa/dsa.yaml index 2ad7f79ad371..b9d48e357e77 100644 --- a/Documentation/devicetree/bindings/net/dsa/dsa.yaml +++ b/Documentation/devicetree/bindings/net/dsa/dsa.yaml @@ -46,65 +46,9 @@ patternProperties: type: object description: Ethernet switch ports - allOf: - - $ref: "http://devicetree.org/schemas/net/ethernet-controller.yaml#" + $ref: dsa-port.yaml# - properties: - reg: - description: Port number - - label: - description: - Describes the label associated with this port, which will become - the netdev name - $ref: /schemas/types.yaml#/definitions/string - - link: - description: - Should be a list of phandles to other switch's DSA port. This - port is used as the outgoing port towards the phandle ports. The - full routing information must be given, not just the one hop - routes to neighbouring switches - $ref: /schemas/types.yaml#/definitions/phandle-array - - ethernet: - description: - Should be a phandle to a valid Ethernet device node. This host - device is what the switch port is connected to - $ref: /schemas/types.yaml#/definitions/phandle - - dsa-tag-protocol: - description: - Instead of the default, the switch will use this tag protocol if - possible. Useful when a device supports multiple protocols and - the default is incompatible with the Ethernet device. - enum: - - dsa - - edsa - - ocelot - - ocelot-8021q - - seville - - phy-handle: true - - phy-mode: true - - fixed-link: true - - mac-address: true - - sfp: true - - managed: true - - rx-internal-delay-ps: true - - tx-internal-delay-ps: true - - required: - - reg - - additionalProperties: false + unevaluatedProperties: false oneOf: - required: diff --git a/Documentation/devicetree/bindings/net/dsa/qca8k.yaml b/Documentation/devicetree/bindings/net/dsa/qca8k.yaml index 48de0ace265d..89c21b289447 100644 --- a/Documentation/devicetree/bindings/net/dsa/qca8k.yaml +++ b/Documentation/devicetree/bindings/net/dsa/qca8k.yaml @@ -99,40 +99,9 @@ patternProperties: type: object description: Ethernet switch ports - properties: - reg: - description: Port number - - label: - description: - Describes the label associated with this port, which will become - the netdev name - $ref: /schemas/types.yaml#/definitions/string - - link: - description: - Should be a list of phandles to other switch's DSA port. This - port is used as the outgoing port towards the phandle ports. The - full routing information must be given, not just the one hop - routes to neighbouring switches - $ref: /schemas/types.yaml#/definitions/phandle-array - - ethernet: - description: - Should be a phandle to a valid Ethernet device node. This host - device is what the switch port is connected to - $ref: /schemas/types.yaml#/definitions/phandle - - phy-handle: true - - phy-mode: true - - fixed-link: true - - mac-address: true - - sfp: true + $ref: dsa-port.yaml# + properties: qca,sgmii-rxclk-falling-edge: $ref: /schemas/types.yaml#/definitions/flag description: @@ -154,10 +123,7 @@ patternProperties: SGMII on the QCA8337, it is advised to set this unless a communication issue is observed. - required: - - reg - - additionalProperties: false + unevaluatedProperties: false oneOf: - required: diff --git a/Documentation/devicetree/bindings/net/engleder,tsnep.yaml b/Documentation/devicetree/bindings/net/engleder,tsnep.yaml new file mode 100644 index 000000000000..d0e1476e15b5 --- /dev/null +++ b/Documentation/devicetree/bindings/net/engleder,tsnep.yaml @@ -0,0 +1,79 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/net/engleder,tsnep.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: TSN endpoint Ethernet MAC binding + +maintainers: + - Gerhard Engleder <gerhard@engleder-embedded.com> + +allOf: + - $ref: ethernet-controller.yaml# + +properties: + compatible: + const: engleder,tsnep + + reg: + maxItems: 1 + + interrupts: + maxItems: 1 + + local-mac-address: true + + mac-address: true + + nvmem-cells: true + + nvmem-cells-names: true + + phy-connection-type: + enum: + - mii + - gmii + - rgmii + - rgmii-id + + phy-mode: true + + phy-handle: true + + mdio: + type: object + $ref: "mdio.yaml#" + description: optional node for embedded MDIO controller + +required: + - compatible + - reg + - interrupts + +additionalProperties: false + +examples: + - | + axi { + #address-cells = <2>; + #size-cells = <2>; + tnsep0: ethernet@a0000000 { + compatible = "engleder,tsnep"; + reg = <0x0 0xa0000000 0x0 0x10000>; + interrupts = <0 89 1>; + interrupt-parent = <&gic>; + local-mac-address = [00 00 00 00 00 00]; + phy-mode = "rgmii"; + phy-handle = <&phy0>; + mdio { + #address-cells = <1>; + #size-cells = <0>; + suppress-preamble; + phy0: ethernet-phy@1 { + reg = <1>; + rxc-skew-ps = <1080>; + }; + }; + }; + }; diff --git a/Documentation/devicetree/bindings/net/ethernet-phy.yaml b/Documentation/devicetree/bindings/net/ethernet-phy.yaml index 2766fe45bb98..ee42328a109d 100644 --- a/Documentation/devicetree/bindings/net/ethernet-phy.yaml +++ b/Documentation/devicetree/bindings/net/ethernet-phy.yaml @@ -91,6 +91,14 @@ properties: compensate for the board being designed with the lanes swapped. + enet-phy-lane-no-swap: + $ref: /schemas/types.yaml#/definitions/flag + description: + If set, indicates that PHY will disable swap of the + TX/RX lanes. This property allows the PHY to work correcly after + e.g. wrong bootstrap configuration caused by issues in PCB + layout design. + eee-broken-100tx: $ref: /schemas/types.yaml#/definitions/flag description: diff --git a/Documentation/devicetree/bindings/net/intel,ixp4xx-hss.yaml b/Documentation/devicetree/bindings/net/intel,ixp4xx-hss.yaml new file mode 100644 index 000000000000..4dcd53c3e0b4 --- /dev/null +++ b/Documentation/devicetree/bindings/net/intel,ixp4xx-hss.yaml @@ -0,0 +1,100 @@ +# SPDX-License-Identifier: (GPL-2.0 OR BSD-2-Clause) +# Copyright 2021 Linaro Ltd. +%YAML 1.2 +--- +$id: "http://devicetree.org/schemas/net/intel,ixp4xx-hss.yaml#" +$schema: "http://devicetree.org/meta-schemas/core.yaml#" + +title: Intel IXP4xx V.35 WAN High Speed Serial Link (HSS) + +maintainers: + - Linus Walleij <linus.walleij@linaro.org> + +description: | + The Intel IXP4xx HSS makes use of the IXP4xx NPE (Network + Processing Engine) and the IXP4xx Queue Manager to process + V.35 Wideband Modem (WAN) links. + +properties: + compatible: + const: intel,ixp4xx-hss + + reg: + maxItems: 1 + description: The HSS instance + + intel,npe-handle: + $ref: '/schemas/types.yaml#/definitions/phandle-array' + maxItems: 1 + description: phandle to the NPE this HSS instance is using + and the instance to use in the second cell + + intel,queue-chl-rxtrig: + $ref: '/schemas/types.yaml#/definitions/phandle-array' + maxItems: 1 + description: phandle to the RX trigger queue on the NPE + + intel,queue-chl-txready: + $ref: '/schemas/types.yaml#/definitions/phandle-array' + maxItems: 1 + description: phandle to the TX ready queue on the NPE + + intel,queue-pkt-rx: + $ref: '/schemas/types.yaml#/definitions/phandle-array' + maxItems: 1 + description: phandle to the packet RX queue on the NPE + + intel,queue-pkt-tx: + $ref: '/schemas/types.yaml#/definitions/phandle-array' + maxItems: 4 + description: phandle to the packet TX0, TX1, TX2 and TX3 queues on the NPE + + intel,queue-pkt-rxfree: + $ref: '/schemas/types.yaml#/definitions/phandle-array' + maxItems: 4 + description: phandle to the packet RXFREE0, RXFREE1, RXFREE2 and + RXFREE3 queues on the NPE + + intel,queue-pkt-txdone: + $ref: '/schemas/types.yaml#/definitions/phandle-array' + maxItems: 1 + description: phandle to the packet TXDONE queue on the NPE + + cts-gpios: + maxItems: 1 + description: Clear To Send (CTS) GPIO line + + rts-gpios: + maxItems: 1 + description: Ready To Send (RTS) GPIO line + + dcd-gpios: + maxItems: 1 + description: Data Carrier Detect (DCD) GPIO line + + dtr-gpios: + maxItems: 1 + description: Data Terminal Ready (DTR) GPIO line + + clk-internal-gpios: + maxItems: 1 + description: Clock internal GPIO line, driving this high will make the HSS + use internal clocking as opposed to external clocking + +required: + - compatible + - reg + - intel,npe-handle + - intel,queue-chl-rxtrig + - intel,queue-chl-txready + - intel,queue-pkt-rx + - intel,queue-pkt-tx + - intel,queue-pkt-rxfree + - intel,queue-pkt-txdone + - cts-gpios + - rts-gpios + - dcd-gpios + - dtr-gpios + - clk-internal-gpios + +additionalProperties: false diff --git a/Documentation/devicetree/bindings/net/microchip,lan966x-switch.yaml b/Documentation/devicetree/bindings/net/microchip,lan966x-switch.yaml new file mode 100644 index 000000000000..e79e4e166ad8 --- /dev/null +++ b/Documentation/devicetree/bindings/net/microchip,lan966x-switch.yaml @@ -0,0 +1,169 @@ +# SPDX-License-Identifier: GPL-2.0-only OR BSD-2-Clause +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/net/microchip,lan966x-switch.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Microchip Lan966x Ethernet switch controller + +maintainers: + - Horatiu Vultur <horatiu.vultur@microchip.com> + +description: | + The lan966x switch is a multi-port Gigabit AVB/TSN Ethernet Switch with + two integrated 10/100/1000Base-T PHYs. In addition to the integrated PHYs, + it supports up to 2RGMII/RMII, up to 3BASE-X/SERDES/2.5GBASE-X and up to + 2 Quad-SGMII/Quad-USGMII interfaces. + +properties: + $nodename: + pattern: "^switch@[0-9a-f]+$" + + compatible: + const: microchip,lan966x-switch + + reg: + items: + - description: cpu target + - description: general control block target + + reg-names: + items: + - const: cpu + - const: gcb + + interrupts: + minItems: 1 + items: + - description: register based extraction + - description: frame dma based extraction + - description: analyzer interrupt + + interrupt-names: + minItems: 1 + items: + - const: xtr + - const: fdma + - const: ana + + resets: + items: + - description: Reset controller used for switch core reset (soft reset) + - description: Reset controller used for releasing the phy from reset + + reset-names: + items: + - const: switch + - const: phy + + ethernet-ports: + type: object + + properties: + '#address-cells': + const: 1 + '#size-cells': + const: 0 + + additionalProperties: false + + patternProperties: + "^port@[0-9a-f]+$": + type: object + + $ref: "/schemas/net/ethernet-controller.yaml#" + unevaluatedProperties: false + + properties: + '#address-cells': + const: 1 + '#size-cells': + const: 0 + + reg: + description: + Switch port number + + phys: + description: + Phandle of a Ethernet SerDes PHY + + phy-mode: + description: + This specifies the interface used by the Ethernet SerDes towards + the PHY or SFP. + enum: + - gmii + - sgmii + - qsgmii + - 1000base-x + - 2500base-x + + phy-handle: + description: + Phandle of a Ethernet PHY. + + sfp: + description: + Phandle of an SFP. + + managed: true + + required: + - reg + - phys + - phy-mode + + oneOf: + - required: + - phy-handle + - required: + - sfp + - managed + +required: + - compatible + - reg + - reg-names + - interrupts + - interrupt-names + - resets + - reset-names + - ethernet-ports + +additionalProperties: false + +examples: + - | + #include <dt-bindings/interrupt-controller/arm-gic.h> + switch: switch@e0000000 { + compatible = "microchip,lan966x-switch"; + reg = <0xe0000000 0x0100000>, + <0xe2000000 0x0800000>; + reg-names = "cpu", "gcb"; + interrupts = <GIC_SPI 30 IRQ_TYPE_LEVEL_HIGH>; + interrupt-names = "xtr"; + resets = <&switch_reset 0>, <&phy_reset 0>; + reset-names = "switch", "phy"; + ethernet-ports { + #address-cells = <1>; + #size-cells = <0>; + + port0: port@0 { + reg = <0>; + phy-handle = <&phy0>; + phys = <&serdes 0 0>; + phy-mode = "gmii"; + }; + + port1: port@1 { + reg = <1>; + sfp = <&sfp_eth1>; + managed = "in-band-status"; + phys = <&serdes 2 4>; + phy-mode = "sgmii"; + }; + }; + }; + +... diff --git a/Documentation/devicetree/bindings/net/qcom,bam-dmux.yaml b/Documentation/devicetree/bindings/net/qcom,bam-dmux.yaml new file mode 100644 index 000000000000..b30544410d09 --- /dev/null +++ b/Documentation/devicetree/bindings/net/qcom,bam-dmux.yaml @@ -0,0 +1,92 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/net/qcom,bam-dmux.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Qualcomm BAM Data Multiplexer + +maintainers: + - Stephan Gerhold <stephan@gerhold.net> + +description: | + The BAM Data Multiplexer provides access to the network data channels + of modems integrated into many older Qualcomm SoCs, e.g. Qualcomm MSM8916 + or MSM8974. It is built using a simple protocol layer on top of a DMA engine + (Qualcomm BAM DMA) and bidirectional interrupts to coordinate power control. + + Note that this schema does not directly describe a hardware block but rather + a firmware convention that combines several other hardware blocks (such as the + DMA engine). As such it is specific to a firmware version, not a particular + SoC or hardware version. + +properties: + compatible: + const: qcom,bam-dmux + + interrupts: + description: + Interrupts used by the modem to signal the AP. + Both interrupts must be declared as IRQ_TYPE_EDGE_BOTH. + items: + - description: Power control + - description: Power control acknowledgment + + interrupt-names: + items: + - const: pc + - const: pc-ack + + qcom,smem-states: + $ref: /schemas/types.yaml#/definitions/phandle-array + description: State bits used by the AP to signal the modem. + items: + - description: Power control + - description: Power control acknowledgment + + qcom,smem-state-names: + description: Names for the state bits used by the AP to signal the modem. + items: + - const: pc + - const: pc-ack + + dmas: + items: + - description: TX DMA channel phandle + - description: RX DMA channel phandle + + dma-names: + items: + - const: tx + - const: rx + +required: + - compatible + - interrupts + - interrupt-names + - qcom,smem-states + - qcom,smem-state-names + - dmas + - dma-names + +additionalProperties: false + +examples: + - | + #include <dt-bindings/interrupt-controller/irq.h> + + mpss: remoteproc { + bam-dmux { + compatible = "qcom,bam-dmux"; + + interrupt-parent = <&modem_smsm>; + interrupts = <1 IRQ_TYPE_EDGE_BOTH>, <11 IRQ_TYPE_EDGE_BOTH>; + interrupt-names = "pc", "pc-ack"; + + qcom,smem-states = <&apps_smsm 1>, <&apps_smsm 11>; + qcom,smem-state-names = "pc", "pc-ack"; + + dmas = <&bam_dmux_dma 4>, <&bam_dmux_dma 5>; + dma-names = "tx", "rx"; + }; + }; diff --git a/Documentation/devicetree/bindings/net/vertexcom-mse102x.yaml b/Documentation/devicetree/bindings/net/vertexcom-mse102x.yaml new file mode 100644 index 000000000000..8156a9aeb589 --- /dev/null +++ b/Documentation/devicetree/bindings/net/vertexcom-mse102x.yaml @@ -0,0 +1,71 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: "http://devicetree.org/schemas/net/vertexcom-mse102x.yaml#" +$schema: "http://devicetree.org/meta-schemas/core.yaml#" + +title: The Vertexcom MSE102x (SPI) Device Tree Bindings + +maintainers: + - Stefan Wahren <stefan.wahren@in-tech.com> + +description: + Vertexcom's MSE102x are a family of HomePlug GreenPHY chips. + They can be connected either via RGMII, RMII or SPI to a host CPU. + + In order to use a MSE102x chip as SPI device, it must be defined as + a child of an SPI master device in the device tree. + + More information can be found at + http://www.vertexcom.com/doc/MSE1022%20Product%20Brief.pdf + +allOf: + - $ref: ethernet-controller.yaml# + +properties: + compatible: + enum: + - vertexcom,mse1021 + - vertexcom,mse1022 + + reg: + maxItems: 1 + + interrupts: + maxItems: 1 + + spi-cpha: true + + spi-cpol: true + + spi-max-frequency: + minimum: 6000000 + maximum: 7142857 + +required: + - compatible + - reg + - interrupts + - spi-cpha + - spi-cpol + - spi-max-frequency + +additionalProperties: false + +examples: + - | + #include <dt-bindings/interrupt-controller/irq.h> + spi0 { + #address-cells = <1>; + #size-cells = <0>; + + ethernet@0 { + compatible = "vertexcom,mse1021"; + reg = <0>; + interrupt-parent = <&gpio>; + interrupts = <23 IRQ_TYPE_EDGE_RISING>; + spi-cpha; + spi-cpol; + spi-max-frequency = <7142857>; + }; + }; diff --git a/Documentation/devicetree/bindings/net/wireless/microchip,wilc1000.yaml b/Documentation/devicetree/bindings/net/wireless/microchip,wilc1000.yaml index 6c35682377e6..60de78f1bc7b 100644 --- a/Documentation/devicetree/bindings/net/wireless/microchip,wilc1000.yaml +++ b/Documentation/devicetree/bindings/net/wireless/microchip,wilc1000.yaml @@ -32,6 +32,21 @@ properties: clock-names: const: rtc + enable-gpios: + maxItems: 1 + description: Used by wilc1000-spi to determine the GPIO line + connected to the ENABLE line. If specified, reset-gpios + must be specified as well as otherwise the driver cannot + ensure the timing required between asserting ENABLE + and deasserting RESET. This should be declared as an + active-high signal. + + reset-gpios: + maxItems: 1 + description: Used by wilc1000-spi to determine the GPIO line + connected to the RESET line. This should be declared as an + active-low signal. + required: - compatible - interrupts @@ -40,6 +55,8 @@ additionalProperties: false examples: - | + #include <dt-bindings/gpio/gpio.h> + spi { #address-cells = <1>; #size-cells = <0>; @@ -51,6 +68,8 @@ examples: interrupts = <27 0>; clocks = <&pck1>; clock-names = "rtc"; + enable-gpios = <&pioA 5 GPIO_ACTIVE_HIGH>; + reset-gpios = <&pioA 6 GPIO_ACTIVE_LOW>; }; }; diff --git a/Documentation/devicetree/bindings/net/wireless/qcom,ath11k.yaml b/Documentation/devicetree/bindings/net/wireless/qcom,ath11k.yaml index 85c2f699d602..cdf7b873b419 100644 --- a/Documentation/devicetree/bindings/net/wireless/qcom,ath11k.yaml +++ b/Documentation/devicetree/bindings/net/wireless/qcom,ath11k.yaml @@ -150,6 +150,12 @@ properties: string to uniquely identify variant of the calibration data in the board-2.bin for designs with colliding bus and device specific ids + memory-region: + maxItems: 1 + description: + phandle to a node describing reserved memory (System RAM memory) + used by ath11k firmware (see bindings/reserved-memory/reserved-memory.txt) + required: - compatible - reg @@ -279,3 +285,27 @@ examples: "tcl2host-status-ring"; qcom,rproc = <&q6v5_wcss>; }; + + - | + + reserved-memory { + #address-cells = <2>; + #size-cells = <2>; + + qcn9074_0: qcn9074_0@51100000 { + no-map; + reg = <0x0 0x51100000 0x0 0x03500000>; + }; + }; + + pci { + pcie0 { + #size-cells = <2>; + #address-cells = <3>; + + wifi_0: wifi@0 { + reg = <0 0 0 0 0>; + memory-region = <&qcn9074_0>; + }; + }; + }; diff --git a/Documentation/devicetree/bindings/pci/apple,pcie.yaml b/Documentation/devicetree/bindings/pci/apple,pcie.yaml index ef1d424ec299..7f01e15fc81c 100644 --- a/Documentation/devicetree/bindings/pci/apple,pcie.yaml +++ b/Documentation/devicetree/bindings/pci/apple,pcie.yaml @@ -28,19 +28,17 @@ description: | distributed over the root ports as the OS sees fit by programming the PCIe controller's port registers. -allOf: - - $ref: /schemas/pci/pci-bus.yaml# - - $ref: /schemas/interrupt-controller/msi-controller.yaml# - properties: compatible: items: - - const: apple,t8103-pcie + - enum: + - apple,t8103-pcie + - apple,t6000-pcie - const: apple,pcie reg: minItems: 3 - maxItems: 5 + maxItems: 6 reg-names: minItems: 3 @@ -50,6 +48,7 @@ properties: - const: port0 - const: port1 - const: port2 + - const: port3 ranges: minItems: 2 @@ -59,7 +58,7 @@ properties: description: Interrupt specifiers, one for each root port. minItems: 1 - maxItems: 3 + maxItems: 4 msi-parent: true @@ -81,6 +80,21 @@ required: unevaluatedProperties: false +allOf: + - $ref: /schemas/pci/pci-bus.yaml# + - $ref: /schemas/interrupt-controller/msi-controller.yaml# + - if: + properties: + compatible: + contains: + const: apple,t8103-pcie + then: + properties: + reg: + maxItems: 5 + interrupts: + maxItems: 3 + examples: - | #include <dt-bindings/interrupt-controller/apple-aic.h> diff --git a/Documentation/devicetree/bindings/perf/arm,cmn.yaml b/Documentation/devicetree/bindings/perf/arm,cmn.yaml index 42424ccbdd0c..2d4219ec7eda 100644 --- a/Documentation/devicetree/bindings/perf/arm,cmn.yaml +++ b/Documentation/devicetree/bindings/perf/arm,cmn.yaml @@ -12,12 +12,14 @@ maintainers: properties: compatible: - const: arm,cmn-600 + enum: + - arm,cmn-600 + - arm,ci-700 reg: items: - description: Physical address of the base (PERIPHBASE) and - size (up to 64MB) of the configuration address space. + size of the configuration address space. interrupts: minItems: 1 @@ -31,14 +33,23 @@ properties: arm,root-node: $ref: /schemas/types.yaml#/definitions/uint32 - description: Offset from PERIPHBASE of the configuration - discovery node (see TRM definition of ROOTNODEBASE). + description: Offset from PERIPHBASE of CMN-600's configuration + discovery node (see TRM definition of ROOTNODEBASE). Not + relevant for newer CMN/CI products. required: - compatible - reg - interrupts - - arm,root-node + +if: + properties: + compatible: + contains: + const: arm,cmn-600 +then: + required: + - arm,root-node additionalProperties: false diff --git a/Documentation/devicetree/bindings/perf/arm,smmu-v3-pmcg.yaml b/Documentation/devicetree/bindings/perf/arm,smmu-v3-pmcg.yaml new file mode 100644 index 000000000000..a4b53a6a1ebf --- /dev/null +++ b/Documentation/devicetree/bindings/perf/arm,smmu-v3-pmcg.yaml @@ -0,0 +1,70 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/perf/arm,smmu-v3-pmcg.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Arm SMMUv3 Performance Monitor Counter Group + +maintainers: + - Will Deacon <will@kernel.org> + - Robin Murphy <robin.murphy@arm.com> + +description: | + An SMMUv3 may have several Performance Monitor Counter Group (PMCG). + They are standalone performance monitoring units that support both + architected and IMPLEMENTATION DEFINED event counters. + +properties: + $nodename: + pattern: "^pmu@[0-9a-f]*" + compatible: + oneOf: + - items: + - const: arm,mmu-600-pmcg + - const: arm,smmu-v3-pmcg + - const: arm,smmu-v3-pmcg + + reg: + items: + - description: Register page 0 + - description: Register page 1, if SMMU_PMCG_CFGR.RELOC_CTRS = 1 + minItems: 1 + + interrupts: + maxItems: 1 + + msi-parent: true + +required: + - compatible + - reg + +anyOf: + - required: + - interrupts + - required: + - msi-parent + +additionalProperties: false + +examples: + - | + #include <dt-bindings/interrupt-controller/arm-gic.h> + #include <dt-bindings/interrupt-controller/irq.h> + + pmu@2b420000 { + compatible = "arm,smmu-v3-pmcg"; + reg = <0x2b420000 0x1000>, + <0x2b430000 0x1000>; + interrupts = <GIC_SPI 80 IRQ_TYPE_EDGE_RISING>; + msi-parent = <&its 0xff0000>; + }; + + pmu@2b440000 { + compatible = "arm,smmu-v3-pmcg"; + reg = <0x2b440000 0x1000>, + <0x2b450000 0x1000>; + interrupts = <GIC_SPI 81 IRQ_TYPE_EDGE_RISING>; + msi-parent = <&its 0xff0000>; + }; diff --git a/Documentation/devicetree/bindings/perf/marvell-cn10k-tad.yaml b/Documentation/devicetree/bindings/perf/marvell-cn10k-tad.yaml new file mode 100644 index 000000000000..362142252667 --- /dev/null +++ b/Documentation/devicetree/bindings/perf/marvell-cn10k-tad.yaml @@ -0,0 +1,63 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/perf/marvell-cn10k-tad.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Marvell CN10K LLC-TAD performance monitor + +maintainers: + - Bhaskara Budiredla <bbudiredla@marvell.com> + +description: | + The Tag-and-Data units (TADs) maintain coherence and contain CN10K + shared on-chip last level cache (LLC). The tad pmu measures the + performance of last-level cache. Each tad pmu supports up to eight + counters. + + The DT setup comprises of number of tad blocks, the sizes of pmu + regions, tad blocks and overall base address of the HW. + +properties: + compatible: + const: marvell,cn10k-tad-pmu + + reg: + maxItems: 1 + + marvell,tad-cnt: + description: specifies the number of tads on the soc + $ref: /schemas/types.yaml#/definitions/uint32 + + marvell,tad-page-size: + description: specifies the size of each tad page + $ref: /schemas/types.yaml#/definitions/uint32 + + marvell,tad-pmu-page-size: + description: specifies the size of page that the pmu uses + $ref: /schemas/types.yaml#/definitions/uint32 + +required: + - compatible + - reg + - marvell,tad-cnt + - marvell,tad-page-size + - marvell,tad-pmu-page-size + +additionalProperties: false + +examples: + - | + + tad { + #address-cells = <2>; + #size-cells = <2>; + + tad_pmu@80000000 { + compatible = "marvell,cn10k-tad-pmu"; + reg = <0x87e2 0x80000000 0x0 0x1000>; + marvell,tad-cnt = <1>; + marvell,tad-page-size = <0x1000>; + marvell,tad-pmu-page-size = <0x1000>; + }; + }; diff --git a/Documentation/devicetree/bindings/phy/xlnx,zynqmp-psgtr.yaml b/Documentation/devicetree/bindings/phy/xlnx,zynqmp-psgtr.yaml index 04d5654efb38..79906519c652 100644 --- a/Documentation/devicetree/bindings/phy/xlnx,zynqmp-psgtr.yaml +++ b/Documentation/devicetree/bindings/phy/xlnx,zynqmp-psgtr.yaml @@ -29,7 +29,7 @@ properties: - PHY_TYPE_PCIE - PHY_TYPE_SATA - PHY_TYPE_SGMII - - PHY_TYPE_USB + - PHY_TYPE_USB3 - description: The PHY instance minimum: 0 maximum: 1 # for DP, SATA or USB diff --git a/Documentation/devicetree/bindings/pinctrl/apple,pinctrl.yaml b/Documentation/devicetree/bindings/pinctrl/apple,pinctrl.yaml index 07b00de79755..572923d7023e 100644 --- a/Documentation/devicetree/bindings/pinctrl/apple,pinctrl.yaml +++ b/Documentation/devicetree/bindings/pinctrl/apple,pinctrl.yaml @@ -17,7 +17,9 @@ description: | properties: compatible: items: - - const: apple,t8103-pinctrl + - enum: + - apple,t8103-pinctrl + - apple,t6000-pinctrl - const: apple,pinctrl reg: @@ -50,6 +52,9 @@ properties: '#interrupt-cells': const: 2 + power-domains: + maxItems: 1 + patternProperties: '-pins$': type: object diff --git a/Documentation/devicetree/bindings/pinctrl/starfive,jh7100-pinctrl.yaml b/Documentation/devicetree/bindings/pinctrl/starfive,jh7100-pinctrl.yaml new file mode 100644 index 000000000000..92963604422f --- /dev/null +++ b/Documentation/devicetree/bindings/pinctrl/starfive,jh7100-pinctrl.yaml @@ -0,0 +1,307 @@ +# SPDX-License-Identifier: GPL-2.0-only OR BSD-2-Clause +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/pinctrl/starfive,jh7100-pinctrl.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: StarFive JH7100 Pin Controller Device Tree Bindings + +description: | + Bindings for the JH7100 RISC-V SoC from StarFive Ltd. + + Out of the SoC's many pins only the ones named PAD_GPIO[0] to PAD_GPIO[63] + and PAD_FUNC_SHARE[0] to PAD_FUNC_SHARE[141] can be multiplexed and have + configurable bias, drive strength, schmitt trigger etc. The SoC has an + interesting 2-layered approach to pin muxing best illustrated by the diagram + below. + + Signal group 0, 1, ... or 6 + ___|___ + | | + LCD output -----------------| | + CMOS Camera interface ------| |--- PAD_GPIO[0] + Ethernet PHY interface -----| MUX |--- PAD_GPIO[1] + ... | | ... + | |--- PAD_GPIO[63] + -------- GPIO0 ------------| | + | -------|-- GPIO1 --------| |--- PAD_FUNC_SHARE[0] + | | | | | |--- PAD_FUNC_SHARE[1] + | | | | ... | | ... + | | | | | |--- PAD_FUNC_SHARE[141] + | | -----|---|-- GPIO63 ---| | + | | | | | | ------- + UART0 UART1 -- + + + The big MUX in the diagram only has 7 different ways of mapping peripherals + on the left to pins on the right. StarFive calls the 7 configurations "signal + groups". + However some peripherals have their I/O go through the 64 "GPIOs". The + diagram only shows UART0 and UART1, but this also includes a number of other + UARTs, I2Cs, SPIs, PWMs etc. All these peripherals are connected to all 64 + GPIOs such that any GPIO can be set up to be controlled by any of the + peripherals. + Note that signal group 0 doesn't map any of the GPIOs to pins, and only + signal group 1 maps the GPIOs to the pins named PAD_GPIO[0] to PAD_GPIO[63]. + +maintainers: + - Emil Renner Berthing <kernel@esmil.dk> + - Drew Fustini <drew@beagleboard.org> + +properties: + compatible: + const: starfive,jh7100-pinctrl + + reg: + minItems: 2 + maxItems: 2 + + reg-names: + items: + - const: gpio + - const: padctl + + clocks: + maxItems: 1 + + resets: + maxItems: 1 + + gpio-controller: true + + "#gpio-cells": + const: 2 + + interrupts: + maxItems: 1 + description: The GPIO parent interrupt. + + interrupt-controller: true + + "#interrupt-cells": + const: 2 + + starfive,signal-group: + description: | + Select one of the 7 signal groups. If this property is not set it + defaults to the configuration already chosen by the earlier boot stages. + $ref: /schemas/types.yaml#/definitions/uint32 + enum: [0, 1, 2, 3, 4, 5, 6] + +required: + - compatible + - reg + - reg-names + - clocks + - gpio-controller + - "#gpio-cells" + - interrupts + - interrupt-controller + - "#interrupt-cells" + +patternProperties: + '-[0-9]+$': + type: object + patternProperties: + '-pins$': + type: object + description: | + A pinctrl node should contain at least one subnode representing the + pinctrl groups available on the machine. Each subnode will list the + pins it needs, and how they should be configured, with regard to + muxer configuration, bias, input enable/disable, input schmitt + trigger enable/disable, slew-rate and drive strength. + $ref: "/schemas/pinctrl/pincfg-node.yaml" + + properties: + pins: + description: | + The list of pin identifiers that properties in the node apply to. + This should be set using either the PAD_GPIO or PAD_FUNC_SHARE + macros. + Either this or "pinmux" has to be specified, but not both. + $ref: "/schemas/pinctrl/pinmux-node.yaml#/properties/pins" + + pinmux: + description: | + The list of GPIOs and their mux settings that properties in the + node apply to. This should be set using the GPIOMUX macro. + Either this or "pins" has to be specified, but not both. + $ref: "/schemas/pinctrl/pinmux-node.yaml#/properties/pinmux" + + bias-disable: true + + bias-pull-up: + type: boolean + + bias-pull-down: + type: boolean + + drive-strength: + enum: [ 14, 21, 28, 35, 42, 49, 56, 63 ] + + input-enable: true + + input-disable: true + + input-schmitt-enable: true + + input-schmitt-disable: true + + slew-rate: + maximum: 7 + + starfive,strong-pull-up: + description: enable strong pull-up. + type: boolean + + additionalProperties: false + + additionalProperties: false + +additionalProperties: false + +examples: + - | + #include <dt-bindings/clock/starfive-jh7100.h> + #include <dt-bindings/reset/starfive-jh7100.h> + #include <dt-bindings/pinctrl/pinctrl-starfive.h> + + soc { + #address-cells = <2>; + #size-cells = <2>; + + pinctrl@11910000 { + compatible = "starfive,jh7100-pinctrl"; + reg = <0x0 0x11910000 0x0 0x10000>, + <0x0 0x11858000 0x0 0x1000>; + reg-names = "gpio", "padctl"; + clocks = <&clkgen JH7100_CLK_GPIO_APB>; + resets = <&clkgen JH7100_RSTN_GPIO_APB>; + interrupts = <32>; + gpio-controller; + #gpio-cells = <2>; + interrupt-controller; + #interrupt-cells = <2>; + starfive,signal-group = <6>; + + gmac_pins_default: gmac-0 { + gtxclk-pins { + pins = <PAD_FUNC_SHARE(115)>; + bias-pull-up; + drive-strength = <35>; + input-enable; + input-schmitt-enable; + slew-rate = <0>; + }; + miitxclk-pins { + pins = <PAD_FUNC_SHARE(116)>; + bias-pull-up; + drive-strength = <14>; + input-enable; + input-schmitt-disable; + slew-rate = <0>; + }; + tx-pins { + pins = <PAD_FUNC_SHARE(117)>, + <PAD_FUNC_SHARE(119)>, + <PAD_FUNC_SHARE(120)>, + <PAD_FUNC_SHARE(121)>, + <PAD_FUNC_SHARE(122)>, + <PAD_FUNC_SHARE(123)>, + <PAD_FUNC_SHARE(124)>, + <PAD_FUNC_SHARE(125)>, + <PAD_FUNC_SHARE(126)>; + bias-disable; + drive-strength = <35>; + input-disable; + input-schmitt-disable; + slew-rate = <0>; + }; + rxclk-pins { + pins = <PAD_FUNC_SHARE(127)>; + bias-pull-up; + drive-strength = <14>; + input-enable; + input-schmitt-disable; + slew-rate = <6>; + }; + rxer-pins { + pins = <PAD_FUNC_SHARE(129)>; + bias-pull-up; + drive-strength = <14>; + input-enable; + input-schmitt-disable; + slew-rate = <0>; + }; + rx-pins { + pins = <PAD_FUNC_SHARE(128)>, + <PAD_FUNC_SHARE(130)>, + <PAD_FUNC_SHARE(131)>, + <PAD_FUNC_SHARE(132)>, + <PAD_FUNC_SHARE(133)>, + <PAD_FUNC_SHARE(134)>, + <PAD_FUNC_SHARE(135)>, + <PAD_FUNC_SHARE(136)>, + <PAD_FUNC_SHARE(137)>, + <PAD_FUNC_SHARE(138)>, + <PAD_FUNC_SHARE(139)>, + <PAD_FUNC_SHARE(140)>, + <PAD_FUNC_SHARE(141)>; + bias-pull-up; + drive-strength = <14>; + input-enable; + input-schmitt-enable; + slew-rate = <0>; + }; + }; + + i2c0_pins_default: i2c0-0 { + i2c-pins { + pinmux = <GPIOMUX(62, GPO_LOW, + GPO_I2C0_PAD_SCK_OEN, + GPI_I2C0_PAD_SCK_IN)>, + <GPIOMUX(61, GPO_LOW, + GPO_I2C0_PAD_SDA_OEN, + GPI_I2C0_PAD_SDA_IN)>; + bias-disable; /* external pull-up */ + input-enable; + input-schmitt-enable; + }; + }; + + uart3_pins_default: uart3-0 { + rx-pins { + pinmux = <GPIOMUX(13, GPO_LOW, GPO_DISABLE, + GPI_UART3_PAD_SIN)>; + bias-pull-up; + input-enable; + input-schmitt-enable; + }; + tx-pins { + pinmux = <GPIOMUX(14, GPO_UART3_PAD_SOUT, + GPO_ENABLE, GPI_NONE)>; + bias-disable; + input-disable; + input-schmitt-disable; + }; + }; + }; + + gmac { + pinctrl-0 = <&gmac_pins_default>; + pinctrl-names = "default"; + }; + + i2c0 { + pinctrl-0 = <&i2c0_pins_default>; + pinctrl-names = "default"; + }; + + uart3 { + pinctrl-0 = <&uart3_pins_default>; + pinctrl-names = "default"; + }; + }; + +... diff --git a/Documentation/devicetree/bindings/power/apple,pmgr-pwrstate.yaml b/Documentation/devicetree/bindings/power/apple,pmgr-pwrstate.yaml new file mode 100644 index 000000000000..19a194980142 --- /dev/null +++ b/Documentation/devicetree/bindings/power/apple,pmgr-pwrstate.yaml @@ -0,0 +1,79 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/power/apple,pmgr-pwrstate.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Apple SoC PMGR Power States + +maintainers: + - Hector Martin <marcan@marcan.st> + +allOf: + - $ref: "power-domain.yaml#" + +description: | + Apple SoCs include PMGR blocks responsible for power management, + which can control various clocks, resets, power states, and + performance features. This binding describes the device power + state registers, which control power states and resets. + + Each instance of a power controller within the PMGR syscon node + represents a generic power domain provider, as documented in + Documentation/devicetree/bindings/power/power-domain.yaml. + The provider controls a single SoC block. The power hierarchy is + represented via power-domains relationships between these nodes. + + See Documentation/devicetree/bindings/arm/apple/apple,pmgr.yaml + for the top-level PMGR node documentation. + +properties: + compatible: + items: + - enum: + - apple,t8103-pmgr-pwrstate + - apple,t6000-pmgr-pwrstate + - const: apple,pmgr-pwrstate + + reg: + maxItems: 1 + + "#power-domain-cells": + const: 0 + + "#reset-cells": + const: 0 + + power-domains: + description: + Reference to parent power domains. A domain may have multiple parents, + and all will be powered up when it is powered. + minItems: 1 + maxItems: 8 # Arbitrary, should be enough + + label: + description: + Specifies the name of the SoC domain being controlled. This is used to + name the power/reset domains. + + apple,always-on: + description: + Forces this power domain to always be powered up. + type: boolean + + apple,min-state: + description: + Specifies the minimum power state for auto-PM. + 0 = power gated, 4 = clock gated, 15 = on. + $ref: /schemas/types.yaml#/definitions/uint32 + minimum: 0 + maximum: 15 + +required: + - compatible + - reg + - "#power-domain-cells" + - "#reset-cells" + - label + +additionalProperties: false diff --git a/Documentation/devicetree/bindings/power/qcom,rpmpd.yaml b/Documentation/devicetree/bindings/power/qcom,rpmpd.yaml index e810480e3eb7..f48bc41d81ec 100644 --- a/Documentation/devicetree/bindings/power/qcom,rpmpd.yaml +++ b/Documentation/devicetree/bindings/power/qcom,rpmpd.yaml @@ -24,6 +24,7 @@ properties: - qcom,msm8994-rpmpd - qcom,msm8996-rpmpd - qcom,msm8998-rpmpd + - qcom,qcm2290-rpmpd - qcom,qcs404-rpmpd - qcom,sdm660-rpmpd - qcom,sc7180-rpmhpd @@ -32,10 +33,12 @@ properties: - qcom,sdm845-rpmhpd - qcom,sdx55-rpmhpd - qcom,sm6115-rpmpd + - qcom,sm6125-rpmpd - qcom,sm6350-rpmhpd - qcom,sm8150-rpmhpd - qcom,sm8250-rpmhpd - qcom,sm8350-rpmhpd + - qcom,sm8450-rpmhpd '#power-domain-cells': const: 1 diff --git a/Documentation/devicetree/bindings/power/renesas,rcar-sysc.yaml b/Documentation/devicetree/bindings/power/renesas,rcar-sysc.yaml index 99e8042ac111..62a49ca319ec 100644 --- a/Documentation/devicetree/bindings/power/renesas,rcar-sysc.yaml +++ b/Documentation/devicetree/bindings/power/renesas,rcar-sysc.yaml @@ -41,6 +41,7 @@ properties: - renesas,r8a77990-sysc # R-Car E3 - renesas,r8a77995-sysc # R-Car D3 - renesas,r8a779a0-sysc # R-Car V3U + - renesas,r8a779f0-sysc # R-Car S4-8 reg: maxItems: 1 diff --git a/Documentation/devicetree/bindings/power/reset/gpio-poweroff.txt b/Documentation/devicetree/bindings/power/reset/gpio-poweroff.txt deleted file mode 100644 index 3e56c1b34a4c..000000000000 --- a/Documentation/devicetree/bindings/power/reset/gpio-poweroff.txt +++ /dev/null @@ -1,41 +0,0 @@ -Driver a GPIO line that can be used to turn the power off. - -The driver supports both level triggered and edge triggered power off. -At driver load time, the driver will request the given gpio line and -install a handler to power off the system. If the optional properties -'input' is not found, the GPIO line will be driven in the inactive -state. Otherwise its configured as an input. - -When the power-off handler is called, the gpio is configured as an -output, and drive active, so triggering a level triggered power off -condition. This will also cause an inactive->active edge condition, so -triggering positive edge triggered power off. After a delay of 100ms, -the GPIO is set to inactive, thus causing an active->inactive edge, -triggering negative edge triggered power off. After another 100ms -delay the GPIO is driver active again. If the power is still on and -the CPU still running after a 3000ms delay, a WARN_ON(1) is emitted. - -Required properties: -- compatible : should be "gpio-poweroff". -- gpios : The GPIO to set high/low, see "gpios property" in - Documentation/devicetree/bindings/gpio/gpio.txt. If the pin should be - low to power down the board set it to "Active Low", otherwise set - gpio to "Active High". - -Optional properties: -- input : Initially configure the GPIO line as an input. Only reconfigure - it to an output when the power-off handler is called. If this optional - property is not specified, the GPIO is initialized as an output in its - inactive state. -- active-delay-ms: Delay (default 100) to wait after driving gpio active -- inactive-delay-ms: Delay (default 100) to wait after driving gpio inactive -- timeout-ms: Time to wait before asserting a WARN_ON(1). If nothing is - specified, 3000 ms is used. - -Examples: - -gpio-poweroff { - compatible = "gpio-poweroff"; - gpios = <&gpio 4 0>; - timeout-ms = <3000>; -}; diff --git a/Documentation/devicetree/bindings/power/reset/gpio-poweroff.yaml b/Documentation/devicetree/bindings/power/reset/gpio-poweroff.yaml new file mode 100644 index 000000000000..45d66c775115 --- /dev/null +++ b/Documentation/devicetree/bindings/power/reset/gpio-poweroff.yaml @@ -0,0 +1,59 @@ +# SPDX-License-Identifier: (GPL-2.0-only or BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/power/reset/gpio-poweroff.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: GPIO controlled power off + +maintainers: + - Sebastian Reichel <sre@kernel.org> + +description: > + System power off support via a GPIO line. When a shutdown is + executed the operating system is expected to switch the GPIO + from inactive to active. After a delay (active-delay-ms) it + is expected to be switched back to inactive. After another + delay (inactive-delay-ms) it is configured as active again. + Finally the operating system assumes the power off failed if + the system is still running after waiting some time (timeout-ms). + +properties: + compatible: + const: gpio-poweroff + + gpios: + maxItems: 1 + + input: + type: boolean + description: > + Initially configure the GPIO line as an input. Only reconfigure + it to an output when the power-off sequence is initiated. If this optional + property is not specified, the GPIO is initialized as an output in its inactive state. + + active-delay-ms: + default: 100 + description: Delay to wait after driving gpio active + + inactive-delay-ms: + default: 100 + description: Delay to wait after driving gpio inactive + + timeout-ms: + default: 3000 + description: Time to wait before assuming the power off sequence failed. + +required: + - compatible + - gpios + +additionalProperties: false + +examples: + - | + gpio-poweroff { + compatible = "gpio-poweroff"; + gpios = <&gpio 4 0>; + timeout-ms = <3000>; + }; diff --git a/Documentation/devicetree/bindings/power/supply/bq25980.yaml b/Documentation/devicetree/bindings/power/supply/bq25980.yaml index 06eca6667f67..8367a1fd4057 100644 --- a/Documentation/devicetree/bindings/power/supply/bq25980.yaml +++ b/Documentation/devicetree/bindings/power/supply/bq25980.yaml @@ -105,7 +105,7 @@ examples: reg = <0x65>; interrupt-parent = <&gpio1>; interrupts = <16 IRQ_TYPE_EDGE_FALLING>; - ti,watchdog-timer = <0>; + ti,watchdog-timeout-ms = <0>; ti,sc-ocp-limit-microamp = <2000000>; ti,sc-ovp-limit-microvolt = <17800000>; monitored-battery = <&bat>; diff --git a/Documentation/devicetree/bindings/power/supply/maxim,max77976.yaml b/Documentation/devicetree/bindings/power/supply/maxim,max77976.yaml new file mode 100644 index 000000000000..675b9b26d233 --- /dev/null +++ b/Documentation/devicetree/bindings/power/supply/maxim,max77976.yaml @@ -0,0 +1,44 @@ +# SPDX-License-Identifier: (GPL-2.0 OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/power/supply/maxim,max77976.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Maxim Integrated MAX77976 Battery charger + +maintainers: + - Luca Ceresoli <luca@lucaceresoli.net> + +description: | + The Maxim MAX77976 is a 19Vin / 5.5A, 1-Cell Li+ battery charger + configured via I2C. + +allOf: + - $ref: power-supply.yaml# + +properties: + compatible: + const: maxim,max77976 + + reg: + maxItems: 1 + +required: + - compatible + - reg + +unevaluatedProperties: false + +examples: + - | + i2c { + #address-cells = <1>; + #size-cells = <0>; + + charger@6b { + compatible = "maxim,max77976"; + reg = <0x6b>; + }; + }; + +... diff --git a/Documentation/devicetree/bindings/power/supply/qcom,pm8941-charger.yaml b/Documentation/devicetree/bindings/power/supply/qcom,pm8941-charger.yaml index bc8904872d1b..caeff68c66d5 100644 --- a/Documentation/devicetree/bindings/power/supply/qcom,pm8941-charger.yaml +++ b/Documentation/devicetree/bindings/power/supply/qcom,pm8941-charger.yaml @@ -11,7 +11,9 @@ maintainers: properties: compatible: - const: qcom,pm8941-charger + enum: + - qcom,pm8226-charger + - qcom,pm8941-charger reg: maxItems: 1 diff --git a/Documentation/devicetree/bindings/regulator/dlg,da9121.yaml b/Documentation/devicetree/bindings/regulator/dlg,da9121.yaml index 228018c87bea..24ace6e1e5ec 100644 --- a/Documentation/devicetree/bindings/regulator/dlg,da9121.yaml +++ b/Documentation/devicetree/bindings/regulator/dlg,da9121.yaml @@ -17,27 +17,39 @@ description: | Dialog Semiconductor DA9130 Single-channel 10A double-phase buck converter Dialog Semiconductor DA9131 Double-channel 5A single-phase buck converter Dialog Semiconductor DA9132 Double-channel 3A single-phase buck converter - - Current limits - - This is PER PHASE, and the current limit setting in the devices reflect - that with a maximum 10A limit. Allowing for transients at/near double - the rated current, this translates across the device range to per - channel figures as so... - - | DA9121 DA9122 DA9220 DA9217 DA9140 - | /DA9130 /DA9131 /DA9132 - ----------------------------------------------------------------------------- - Output current / channel | 10000000 5000000 3000000 6000000 40000000 - Output current / phase | 5000000 5000000 3000000 3000000 9500000 - ----------------------------------------------------------------------------- - Min regulator-min-microvolt| 300000 300000 300000 300000 500000 - Max regulator-max-microvolt| 1900000 1900000 1900000 1900000 1000000 - Device hardware default | 1000000 1000000 1000000 1000000 1000000 - ----------------------------------------------------------------------------- - Min regulator-min-microamp | 7000000 3500000 3500000 7000000 26000000 - Max regulator-max-microamp | 20000000 10000000 6000000 12000000 78000000 - Device hardware default | 15000000 7500000 5500000 11000000 58000000 + Dialog Semiconductor DA9141 Single-channel 40A quad-phase buck converter + Dialog Semiconductor DA9142 Single-channel 20A double-phase buck converter + + Device parameter ranges + + The current limits can be set to at/near double the rated current per channel + to allow for transient peaks. + Current limit changes when the output is enabled are not supported, as a + precaution against undefined behaviour. + + |----------------------------------------------| + | | range & reset default value | + | Device |------------------------------| + | | microvolt | microamp | + |----------------------------------------------| + | DA9121/DA9130 | Min: 300000 | Min: 7000000 | + | | Max: 1900000 | Max: 20000000 | + |----------------------------------------------| + | DA9121/DA9131 | Min: 300000 | Min: 3500000 | + | | Max: 1900000 | Max: 10000000 | + |----------------------------------------------| + | DA9121/DA9131 | Min: 300000 | Min: 3500000 | + | | Max: 1900000 | Max: 6000000 | + |----------------------------------------------| + | DA9217 | Min: 300000 | Min: 7000000 | + | | Max: 1900000 | Max: 12000000 | + |----------------------------------------------| + | DA9141 | Min: 300000 | Min: 26000000 | + | | Max: 1300000 | Max: 78000000 | + |----------------------------------------------| + | DA9142 | Min: 300000 | Min: 13000000 | + | | Max: 1300000 | Max: 39000000 | + |----------------------------------------------| properties: $nodename: @@ -51,7 +63,8 @@ properties: - dlg,da9130 - dlg,da9131 - dlg,da9132 - - dlg,da9140 + - dlg,da9141 + - dlg,da9142 reg: maxItems: 1 @@ -70,26 +83,24 @@ properties: regulators: type: object - $ref: regulator.yaml# description: | - This node defines the settings for the BUCK. The content of the - sub-node is defined by the standard binding for regulators; see regulator.yaml. - The DA9121 regulator is bound using their names listed below - buck1 - BUCK1 - buck2 - BUCK2 //DA9122, DA9220, DA9131, DA9132 only + List of regulators provided by the device patternProperties: "^buck([1-2])$": type: object $ref: regulator.yaml# + description: | + Properties for a single BUCK regulator properties: - regulator-mode: - maxItems: 1 - description: Defined in include/dt-bindings/regulator/dlg,da9121-regulator.h + regulator-name: + pattern: "^BUCK([1-2])$" + description: | + BUCK2 present in DA9122, DA9220, DA9131, DA9132 only regulator-initial-mode: - maxItems: 1 + enum: [ 0, 1, 2, 3 ] description: Defined in include/dt-bindings/regulator/dlg,da9121-regulator.h enable-gpios: @@ -98,6 +109,7 @@ properties: dlg,ripple-cancel: $ref: "/schemas/types.yaml#/definitions/uint32" + enum: [ 0, 1, 2, 3 ] description: | Defined in include/dt-bindings/regulator/dlg,da9121-regulator.h Only present on multi-channel devices (DA9122, DA9220, DA9131, DA9132) diff --git a/Documentation/devicetree/bindings/regulator/max77686.txt b/Documentation/devicetree/bindings/regulator/max77686.txt deleted file mode 100644 index ff3d2dec8c4b..000000000000 --- a/Documentation/devicetree/bindings/regulator/max77686.txt +++ /dev/null @@ -1,71 +0,0 @@ -Binding for Maxim MAX77686 regulators - -This is a part of the device tree bindings of MAX77686 multi-function device. -More information can be found in ../mfd/max77686.txt file. - -The MAX77686 PMIC has 9 high-efficiency Buck and 26 Low-DropOut (LDO) -regulators that can be controlled over I2C. - -Following properties should be present in main device node of the MFD chip. - -Optional node: -- voltage-regulators : The regulators of max77686 have to be instantiated - under subnode named "voltage-regulators" using the following format. - - regulator_name { - regulator-compatible = LDOn/BUCKn - standard regulator constraints.... - }; - refer Documentation/devicetree/bindings/regulator/regulator.txt - - The regulator node's name should be initialized with a string -to get matched with their hardware counterparts as follow: - - -LDOn : for LDOs, where n can lie in range 1 to 26. - example: LDO1, LDO2, LDO26. - -BUCKn : for BUCKs, where n can lie in range 1 to 9. - example: BUCK1, BUCK5, BUCK9. - - Regulators which can be turned off during system suspend: - -LDOn : 2, 6-8, 10-12, 14-16, - -BUCKn : 1-4. - Use standard regulator bindings for it ('regulator-off-in-suspend'). - - LDO20, LDO21, LDO22, BUCK8 and BUCK9 can be configured to GPIO enable - control. To turn this feature on this property must be added to the regulator - sub-node: - - maxim,ena-gpios : one GPIO specifier enable control (the gpio - flags are actually ignored and always - ACTIVE_HIGH is used) - -Example: - - max77686: pmic@9 { - compatible = "maxim,max77686"; - interrupt-parent = <&wakeup_eint>; - interrupts = <26 IRQ_TYPE_LEVEL_LOW>; - reg = <0x09>; - - voltage-regulators { - ldo11_reg: LDO11 { - regulator-name = "vdd_ldo11"; - regulator-min-microvolt = <1900000>; - regulator-max-microvolt = <1900000>; - regulator-always-on; - }; - - buck1_reg: BUCK1 { - regulator-name = "vdd_mif"; - regulator-min-microvolt = <950000>; - regulator-max-microvolt = <1300000>; - regulator-always-on; - regulator-boot-on; - }; - - buck9_reg: BUCK9 { - regulator-name = "CAM_ISP_CORE_1.2V"; - regulator-min-microvolt = <1000000>; - regulator-max-microvolt = <1200000>; - maxim,ena-gpios = <&gpm0 3 GPIO_ACTIVE_HIGH>; - }; - }; diff --git a/Documentation/devicetree/bindings/regulator/maxim,max20086.yaml b/Documentation/devicetree/bindings/regulator/maxim,max20086.yaml new file mode 100644 index 000000000000..05f72391185e --- /dev/null +++ b/Documentation/devicetree/bindings/regulator/maxim,max20086.yaml @@ -0,0 +1,106 @@ +# SPDX-License-Identifier: (GPL-2.0 OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/regulator/maxim,max20086.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Maxim Integrated MAX20086-MAX20089 Camera Power Protector + +maintainers: + - Laurent Pinchart <laurent.pinchart@ideasonboard.com> + +description: | + The MAX20086-MAX20089 are dual/quad camera power protectors, designed to + deliver power over coax for radar and camera modules. They support + software-configurable output switching and monitoring. The output voltage and + current limit are fixed by the hardware design. + +properties: + compatible: + enum: + - maxim,max20086 + - maxim,max20087 + - maxim,max20088 + - maxim,max20089 + + reg: + maxItems: 1 + + enable-gpios: + maxItems: 1 + description: GPIO connected to the EN pin, active high + + in-supply: + description: Input supply for the camera outputs (IN pin, 3.0V to 15.0V) + + vdd-supply: + description: Input supply for the device (VDD pin, 3.0V to 5.5V) + + regulators: + type: object + + patternProperties: + "^OUT[1-4]$": + type: object + $ref: regulator.yaml# + + additionalProperties: false + +required: + - compatible + - reg + - in-supply + - vdd-supply + - regulators + +allOf: + - if: + properties: + compatible: + contains: + enum: + - maxim,max20088 + - maxim,max20089 + then: + properties: + regulators: + properties: + OUT3: false + OUT4: false + +additionalProperties: false + +examples: + - | + #include <dt-bindings/gpio/gpio.h> + + i2c { + #address-cells = <1>; + #size-cells = <0>; + + regulator@28 { + compatible = "maxim,max20087"; + reg = <0x28>; + + in-supply = <®_12v0>; + vdd-supply = <®_3v3>; + + enable-gpios = <&gpio 108 GPIO_ACTIVE_HIGH>; + + regulators { + OUT1 { + regulator-name = "VOUT1"; + }; + OUT2 { + regulator-name = "VOUT2"; + }; + OUT3 { + regulator-name = "VOUT3"; + }; + OUT4 { + regulator-name = "VOUT4"; + }; + }; + }; + }; +... diff --git a/Documentation/devicetree/bindings/regulator/maxim,max77686.yaml b/Documentation/devicetree/bindings/regulator/maxim,max77686.yaml new file mode 100644 index 000000000000..bb64b679f765 --- /dev/null +++ b/Documentation/devicetree/bindings/regulator/maxim,max77686.yaml @@ -0,0 +1,83 @@ +# SPDX-License-Identifier: GPL-2.0-only OR BSD-2-Clause +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/regulator/maxim,max77686.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Maxim MAX77686 Power Management IC regulators + +maintainers: + - Chanwoo Choi <cw00.choi@samsung.com> + - Krzysztof Kozlowski <krzysztof.kozlowski@canonical.com> + +description: | + This is a part of device tree bindings for Maxim MAX77686 Power Management + Integrated Circuit (PMIC). + + The Maxim MAX77686 provides high-efficiency Buck and 26 Low-DropOut (LDO) + regulators. + + See also Documentation/devicetree/bindings/mfd/maxim,max77686.yaml for + additional information and example. + +patternProperties: + # 26 LDOs + "^LDO([1-9]|1[0-9]|2[3-6])$": + type: object + $ref: regulator.yaml# + unevaluatedProperties: false + description: | + Properties for single LDO regulator. + Regulators which can be turned off during system suspend: + LDO2, LDO6-8, LDO10-12, LDO14-16 + + required: + - regulator-name + + # LDO20-LDO22 with maxim,ena-gpios + "^LDO2[0-2]$": + type: object + $ref: regulator.yaml# + unevaluatedProperties: false + description: | + Properties for single LDO regulator. + + properties: + maxim,ena-gpios: + maxItems: 1 + description: | + GPIO specifier to enable the GPIO control (on/off) for regulator. + + required: + - regulator-name + + # 9 bucks + "^BUCK[1-7]$": + type: object + $ref: regulator.yaml# + unevaluatedProperties: false + description: | + Properties for single BUCK regulator. + Regulators which can be turned off during system suspend: + BUCK[1-4] + + required: + - regulator-name + + "^BUCK[89]$": + type: object + $ref: regulator.yaml# + unevaluatedProperties: false + description: | + Properties for single BUCK regulator. + + properties: + maxim,ena-gpios: + maxItems: 1 + description: | + GPIO specifier to enable the GPIO control (on/off) for regulator. + + required: + - regulator-name + +additionalProperties: false diff --git a/Documentation/devicetree/bindings/regulator/maxim,max8973.yaml b/Documentation/devicetree/bindings/regulator/maxim,max8973.yaml index 54522827265b..35c53e27f78c 100644 --- a/Documentation/devicetree/bindings/regulator/maxim,max8973.yaml +++ b/Documentation/devicetree/bindings/regulator/maxim,max8973.yaml @@ -86,6 +86,9 @@ properties: reg: maxItems: 1 + interrupts: + maxItems: 1 + required: - compatible - reg diff --git a/Documentation/devicetree/bindings/regulator/qcom,rpmh-regulator.yaml b/Documentation/devicetree/bindings/regulator/qcom,rpmh-regulator.yaml index b959504e0ea4..5c73d3f639c7 100644 --- a/Documentation/devicetree/bindings/regulator/qcom,rpmh-regulator.yaml +++ b/Documentation/devicetree/bindings/regulator/qcom,rpmh-regulator.yaml @@ -43,6 +43,7 @@ description: | For PM8150L, smps1 - smps8, ldo1 - ldo11, bob, flash, rgb For PM8350, smps1 - smps12, ldo1 - ldo10 For PM8350C, smps1 - smps10, ldo1 - ldo13, bob + For PM8450, smps1 - smps6, ldo1 - ldo4 For PM8998, smps1 - smps13, ldo1 - ldo28, lvs1 - lvs2 For PMI8998, bob For PMR735A, smps1 - smps3, ldo1 - ldo7 @@ -62,7 +63,9 @@ properties: - qcom,pm8150l-rpmh-regulators - qcom,pm8350-rpmh-regulators - qcom,pm8350c-rpmh-regulators + - qcom,pm8450-rpmh-regulators - qcom,pm8998-rpmh-regulators + - qcom,pmg1110-rpmh-regulators - qcom,pmi8998-rpmh-regulators - qcom,pmm8155au-rpmh-regulators - qcom,pmr735a-rpmh-regulators diff --git a/Documentation/devicetree/bindings/regulator/qcom,spmi-regulator.txt b/Documentation/devicetree/bindings/regulator/qcom,spmi-regulator.txt index 2b544059e029..c2a39b121b1b 100644 --- a/Documentation/devicetree/bindings/regulator/qcom,spmi-regulator.txt +++ b/Documentation/devicetree/bindings/regulator/qcom,spmi-regulator.txt @@ -6,6 +6,7 @@ Qualcomm SPMI Regulators Definition: must be one of: "qcom,pm8004-regulators" "qcom,pm8005-regulators" + "qcom,pm8226-regulators" "qcom,pm8841-regulators" "qcom,pm8916-regulators" "qcom,pm8941-regulators" diff --git a/Documentation/devicetree/bindings/regulator/regulator.yaml b/Documentation/devicetree/bindings/regulator/regulator.yaml index a6ae9ecae5cc..ed560ee8714e 100644 --- a/Documentation/devicetree/bindings/regulator/regulator.yaml +++ b/Documentation/devicetree/bindings/regulator/regulator.yaml @@ -218,7 +218,7 @@ properties: description: Array of maximum spread between voltages of coupled regulators in microvolts, each value in the array relates to the corresponding couple specified by the regulator-coupled-with property. - $ref: "/schemas/types.yaml#/definitions/uint32" + $ref: "/schemas/types.yaml#/definitions/uint32-array" regulator-max-step-microvolt: description: Maximum difference between current and target voltages diff --git a/Documentation/devicetree/bindings/regulator/rohm,bd70528-regulator.txt b/Documentation/devicetree/bindings/regulator/rohm,bd70528-regulator.txt deleted file mode 100644 index 698cfc3bc3dd..000000000000 --- a/Documentation/devicetree/bindings/regulator/rohm,bd70528-regulator.txt +++ /dev/null @@ -1,68 +0,0 @@ -ROHM BD70528 Power Management Integrated Circuit regulator bindings - -Required properties: - - regulator-name: should be "buck1", "buck2", "buck3", "ldo1", "ldo2", "ldo3", - "led_ldo1", "led_ldo2" - -List of regulators provided by this controller. BD70528 regulators node -should be sub node of the BD70528 MFD node. See BD70528 MFD bindings at -Documentation/devicetree/bindings/mfd/rohm,bd70528-pmic.txt - -The valid names for BD70528 regulator nodes are: -BUCK1, BUCK2, BUCK3, LDO1, LDO2, LDO3, LED_LDO1, LED_LDO2 - -Optional properties: -- Any optional property defined in bindings/regulator/regulator.txt - -Example: -regulators { - buck1: BUCK1 { - regulator-name = "buck1"; - regulator-min-microvolt = <1200000>; - regulator-max-microvolt = <3400000>; - regulator-boot-on; - regulator-ramp-delay = <125>; - }; - buck2: BUCK2 { - regulator-name = "buck2"; - regulator-min-microvolt = <1200000>; - regulator-max-microvolt = <3300000>; - regulator-boot-on; - regulator-ramp-delay = <125>; - }; - buck3: BUCK3 { - regulator-name = "buck3"; - regulator-min-microvolt = <800000>; - regulator-max-microvolt = <1800000>; - regulator-boot-on; - regulator-ramp-delay = <250>; - }; - ldo1: LDO1 { - regulator-name = "ldo1"; - regulator-min-microvolt = <1650000>; - regulator-max-microvolt = <3300000>; - regulator-boot-on; - }; - ldo2: LDO2 { - regulator-name = "ldo2"; - regulator-min-microvolt = <1650000>; - regulator-max-microvolt = <3300000>; - regulator-boot-on; - }; - - ldo3: LDO3 { - regulator-name = "ldo3"; - regulator-min-microvolt = <1650000>; - regulator-max-microvolt = <3300000>; - }; - led_ldo1: LED_LDO1 { - regulator-name = "led_ldo1"; - regulator-min-microvolt = <200000>; - regulator-max-microvolt = <300000>; - }; - led_ldo2: LED_LDO2 { - regulator-name = "led_ldo2"; - regulator-min-microvolt = <200000>; - regulator-max-microvolt = <300000>; - }; -}; diff --git a/Documentation/devicetree/bindings/regulator/samsung,s5m8767.yaml b/Documentation/devicetree/bindings/regulator/samsung,s5m8767.yaml index 80a63d47790a..3c1617b66861 100644 --- a/Documentation/devicetree/bindings/regulator/samsung,s5m8767.yaml +++ b/Documentation/devicetree/bindings/regulator/samsung,s5m8767.yaml @@ -51,11 +51,25 @@ patternProperties: description: Properties for single BUCK regulator. + properties: + op_mode: + $ref: /schemas/types.yaml#/definitions/uint32 + enum: [0, 1, 2, 3] + default: 1 + description: | + Describes the different operating modes of the regulator with power + mode change in SOC. The different possible values are: + 0 - always off mode + 1 - on in normal mode + 2 - low power mode + 3 - suspend mode + required: - regulator-name +properties: # 9 buck - "^BUCK9$": + BUCK9: type: object $ref: regulator.yaml# unevaluatedProperties: false @@ -63,6 +77,18 @@ patternProperties: Properties for single BUCK regulator. properties: + op_mode: + $ref: /schemas/types.yaml#/definitions/uint32 + enum: [0, 1, 2, 3] + default: 1 + description: | + Describes the different operating modes of the regulator with power + mode change in SOC. The different possible values are: + 0 - always off mode + 1 - on in normal mode + 2 - low power mode + 3 - suspend mode + s5m8767,pmic-ext-control-gpios: maxItems: 1 description: | diff --git a/Documentation/devicetree/bindings/reset/renesas,rst.yaml b/Documentation/devicetree/bindings/reset/renesas,rst.yaml index 620cd0538bbe..bbe313bf1796 100644 --- a/Documentation/devicetree/bindings/reset/renesas,rst.yaml +++ b/Documentation/devicetree/bindings/reset/renesas,rst.yaml @@ -48,6 +48,7 @@ properties: - renesas,r8a77990-rst # R-Car E3 - renesas,r8a77995-rst # R-Car D3 - renesas,r8a779a0-rst # R-Car V3U + - renesas,r8a779f0-rst # R-Car S4-8 reg: maxItems: 1 diff --git a/Documentation/devicetree/bindings/reset/starfive,jh7100-reset.yaml b/Documentation/devicetree/bindings/reset/starfive,jh7100-reset.yaml new file mode 100644 index 000000000000..300359a5e14b --- /dev/null +++ b/Documentation/devicetree/bindings/reset/starfive,jh7100-reset.yaml @@ -0,0 +1,38 @@ +# SPDX-License-Identifier: GPL-2.0-only OR BSD-2-Clause +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/reset/starfive,jh7100-reset.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: StarFive JH7100 SoC Reset Controller Device Tree Bindings + +maintainers: + - Emil Renner Berthing <kernel@esmil.dk> + +properties: + compatible: + enum: + - starfive,jh7100-reset + + reg: + maxItems: 1 + + "#reset-cells": + const: 1 + +required: + - compatible + - reg + - "#reset-cells" + +additionalProperties: false + +examples: + - | + reset-controller@11840000 { + compatible = "starfive,jh7100-reset"; + reg = <0x11840000 0x10000>; + #reset-cells = <1>; + }; + +... diff --git a/Documentation/devicetree/bindings/rtc/nvidia,tegra20-rtc.txt b/Documentation/devicetree/bindings/rtc/nvidia,tegra20-rtc.txt deleted file mode 100644 index b7d98ed3e098..000000000000 --- a/Documentation/devicetree/bindings/rtc/nvidia,tegra20-rtc.txt +++ /dev/null @@ -1,24 +0,0 @@ -NVIDIA Tegra20 real-time clock - -The Tegra RTC maintains seconds and milliseconds counters, and five alarm -registers. The alarms and other interrupts may wake the system from low-power -state. - -Required properties: - -- compatible : For Tegra20, must contain "nvidia,tegra20-rtc". Otherwise, - must contain '"nvidia,<chip>-rtc", "nvidia,tegra20-rtc"', where <chip> - can be tegra30, tegra114, tegra124, or tegra132. -- reg : Specifies base physical address and size of the registers. -- interrupts : A single interrupt specifier. -- clocks : Must contain one entry, for the module clock. - See ../clocks/clock-bindings.txt for details. - -Example: - -timer { - compatible = "nvidia,tegra20-rtc"; - reg = <0x7000e000 0x100>; - interrupts = <0 2 0x04>; - clocks = <&tegra_car 4>; -}; diff --git a/Documentation/devicetree/bindings/rtc/nvidia,tegra20-rtc.yaml b/Documentation/devicetree/bindings/rtc/nvidia,tegra20-rtc.yaml new file mode 100644 index 000000000000..17d6280e5515 --- /dev/null +++ b/Documentation/devicetree/bindings/rtc/nvidia,tegra20-rtc.yaml @@ -0,0 +1,61 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/rtc/nvidia,tegra20-rtc.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: NVIDIA Tegra real-time clock + +maintainers: + - Thierry Reding <thierry.reding@gmail.com> + - Jon Hunter <jonathanh@nvidia.com> + +description: | + The Tegra RTC maintains seconds and milliseconds counters, and five + alarm registers. The alarms and other interrupts may wake the system + from low-power state. + +properties: + compatible: + oneOf: + - const: nvidia,tegra20-rtc + - items: + - enum: + - nvidia,tegra30-rtc + - nvidia,tegra114-rtc + - nvidia,tegra124-rtc + - nvidia,tegra210-rtc + - nvidia,tegra186-rtc + - nvidia,tegra194-rtc + - nvidia,tegra234-rtc + - const: nvidia,tegra20-rtc + + reg: + maxItems: 1 + + interrupts: + maxItems: 1 + + clocks: + maxItems: 1 + + clock-names: + items: + - const: rtc + +additionalProperties: false + +required: + - compatible + - reg + - interrupts + - clocks + +examples: + - | + timer@7000e000 { + compatible = "nvidia,tegra20-rtc"; + reg = <0x7000e000 0x100>; + interrupts = <0 2 0x04>; + clocks = <&tegra_car 4>; + }; diff --git a/Documentation/devicetree/bindings/serial/8250.yaml b/Documentation/devicetree/bindings/serial/8250.yaml index fa767440f281..3bab2f27b970 100644 --- a/Documentation/devicetree/bindings/serial/8250.yaml +++ b/Documentation/devicetree/bindings/serial/8250.yaml @@ -113,9 +113,10 @@ properties: - nvidia,tegra30-uart - nvidia,tegra114-uart - nvidia,tegra124-uart + - nvidia,tegra210-uart - nvidia,tegra186-uart - nvidia,tegra194-uart - - nvidia,tegra210-uart + - nvidia,tegra234-uart - const: nvidia,tegra20-uart reg: diff --git a/Documentation/devicetree/bindings/serial/nvidia,tegra194-tcu.txt b/Documentation/devicetree/bindings/serial/nvidia,tegra194-tcu.txt deleted file mode 100644 index 085a8591accd..000000000000 --- a/Documentation/devicetree/bindings/serial/nvidia,tegra194-tcu.txt +++ /dev/null @@ -1,35 +0,0 @@ -NVIDIA Tegra Combined UART (TCU) - -The TCU is a system for sharing a hardware UART instance among multiple -systems within the Tegra SoC. It is implemented through a mailbox- -based protocol where each "virtual UART" has a pair of mailboxes, one -for transmitting and one for receiving, that is used to communicate -with the hardware implementing the TCU. - -Required properties: -- name : Should be tcu -- compatible - Array of strings - One of: - - "nvidia,tegra194-tcu" -- mbox-names: - "rx" - Mailbox for receiving data from hardware UART - "tx" - Mailbox for transmitting data to hardware UART -- mboxes: Mailboxes corresponding to the mbox-names. - -This node is a mailbox consumer. See the following files for details of -the mailbox subsystem, and the specifiers implemented by the relevant -provider(s): - -- .../mailbox/mailbox.txt -- .../mailbox/nvidia,tegra186-hsp.txt - -Example bindings: ------------------ - -tcu: tcu { - compatible = "nvidia,tegra194-tcu"; - mboxes = <&hsp_top0 TEGRA_HSP_MBOX_TYPE_SM 0>, - <&hsp_aon TEGRA_HSP_MBOX_TYPE_SM 1>; - mbox-names = "rx", "tx"; -}; diff --git a/Documentation/devicetree/bindings/serial/nvidia,tegra194-tcu.yaml b/Documentation/devicetree/bindings/serial/nvidia,tegra194-tcu.yaml new file mode 100644 index 000000000000..e2d111b3e0b0 --- /dev/null +++ b/Documentation/devicetree/bindings/serial/nvidia,tegra194-tcu.yaml @@ -0,0 +1,61 @@ +# SPDX-License-Identifier: GPL-2.0 +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/serial/nvidia,tegra194-tcu.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: NVIDIA Tegra Combined UART (TCU) + +maintainers: + - Thierry Reding <thierry.reding@gmail.com> + - Jonathan Hunter <jonathanh@nvidia.com> + +description: + The TCU is a system for sharing a hardware UART instance among multiple + systems within the Tegra SoC. It is implemented through a mailbox- + based protocol where each "virtual UART" has a pair of mailboxes, one + for transmitting and one for receiving, that is used to communicate + with the hardware implementing the TCU. + +properties: + $nodename: + pattern: "^serial(@.*)?$" + + compatible: + oneOf: + - const: nvidia,tegra194-tcu + - items: + - enum: + - nvidia,tegra234-tcu + - const: nvidia,tegra194-tcu + + mbox-names: + items: + - const: rx + - const: tx + + mboxes: + description: | + List of phandles to mailbox channels used for receiving and + transmitting data from and to the hardware UART. + items: + - description: mailbox for receiving data from hardware UART + - description: mailbox for transmitting data to hardware UART + +required: + - compatible + - mbox-names + - mboxes + +additionalProperties: false + +examples: + - | + #include <dt-bindings/mailbox/tegra186-hsp.h> + + tcu: serial { + compatible = "nvidia,tegra194-tcu"; + mboxes = <&hsp_top0 TEGRA_HSP_MBOX_TYPE_SM 0>, + <&hsp_aon TEGRA_HSP_MBOX_TYPE_SM 1>; + mbox-names = "rx", "tx"; + }; diff --git a/Documentation/devicetree/bindings/serial/snps-dw-apb-uart.yaml b/Documentation/devicetree/bindings/serial/snps-dw-apb-uart.yaml index b49fda5e608f..12137fe80acf 100644 --- a/Documentation/devicetree/bindings/serial/snps-dw-apb-uart.yaml +++ b/Documentation/devicetree/bindings/serial/snps-dw-apb-uart.yaml @@ -40,6 +40,11 @@ properties: - brcm,bcm11351-dw-apb-uart - brcm,bcm21664-dw-apb-uart - const: snps,dw-apb-uart + - items: + - enum: + - starfive,jh7100-hsuart + - starfive,jh7100-uart + - const: snps,dw-apb-uart - const: snps,dw-apb-uart reg: diff --git a/Documentation/devicetree/bindings/soc/bcm/brcm,bcm2835-vchiq.txt b/Documentation/devicetree/bindings/soc/bcm/brcm,bcm2835-vchiq.txt deleted file mode 100644 index f331316183f6..000000000000 --- a/Documentation/devicetree/bindings/soc/bcm/brcm,bcm2835-vchiq.txt +++ /dev/null @@ -1,17 +0,0 @@ -Broadcom VCHIQ firmware services - -Required properties: - -- compatible: Should be "brcm,bcm2835-vchiq" on BCM2835, otherwise - "brcm,bcm2836-vchiq". -- reg: Physical base address and length of the doorbell register pair -- interrupts: The interrupt number - See bindings/interrupt-controller/brcm,bcm2835-armctrl-ic.txt - -Example: - -mailbox@7e00b840 { - compatible = "brcm,bcm2835-vchiq"; - reg = <0x7e00b840 0xf>; - interrupts = <0 2>; -}; diff --git a/Documentation/devicetree/bindings/soc/bcm/brcm,bcm2835-vchiq.yaml b/Documentation/devicetree/bindings/soc/bcm/brcm,bcm2835-vchiq.yaml new file mode 100644 index 000000000000..e04439b3355b --- /dev/null +++ b/Documentation/devicetree/bindings/soc/bcm/brcm,bcm2835-vchiq.yaml @@ -0,0 +1,53 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/soc/bcm/brcm,bcm2835-vchiq.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Broadcom VCHIQ firmware services + +maintainers: + - Nicolas Saenz Julienne <nsaenz@kernel.org> + +description: + The VCHIQ communication channel can be provided by BCM283x and Capri SoCs, + to communicate with the VPU-side OS services. + +properties: + compatible: + oneOf: + - description: BCM2835 based boards + items: + - enum: + - brcm,bcm2835-vchiq + + - description: BCM2836/BCM2837 based boards + items: + - enum: + - brcm,bcm2836-vchiq + - const: brcm,bcm2835-vchiq + + reg: + description: Physical base address and length of the doorbell register pair + minItems: 1 + + interrupts: + description: Interrupt number of the doorbell interrupt + minItems: 1 + +required: + - compatible + - reg + - interrupts + +additionalProperties: false + +examples: + - | + mailbox@7e00b840 { + compatible = "brcm,bcm2835-vchiq"; + reg = <0x7e00b840 0xf>; + interrupts = <0 2>; + }; + +... diff --git a/Documentation/devicetree/bindings/soc/imx/fsl,imx8mn-disp-blk-ctrl.yaml b/Documentation/devicetree/bindings/soc/imx/fsl,imx8mn-disp-blk-ctrl.yaml new file mode 100644 index 000000000000..fbeaac399c50 --- /dev/null +++ b/Documentation/devicetree/bindings/soc/imx/fsl,imx8mn-disp-blk-ctrl.yaml @@ -0,0 +1,97 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/soc/imx/fsl,imx8mn-disp-blk-ctrl.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: NXP i.MX8MN DISP blk-ctrl + +maintainers: + - Lucas Stach <l.stach@pengutronix.de> + +description: + The i.MX8MN DISP blk-ctrl is a top-level peripheral providing access to + the NoC and ensuring proper power sequencing of the display and MIPI CSI + peripherals located in the DISP domain of the SoC. + +properties: + compatible: + items: + - const: fsl,imx8mn-disp-blk-ctrl + - const: syscon + + reg: + maxItems: 1 + + '#power-domain-cells': + const: 1 + + power-domains: + minItems: 5 + maxItems: 5 + + power-domain-names: + items: + - const: bus + - const: isi + - const: lcdif + - const: mipi-dsi + - const: mipi-csi + + clocks: + minItems: 11 + maxItems: 11 + + clock-names: + items: + - const: disp_axi + - const: disp_apb + - const: disp_axi_root + - const: disp_apb_root + - const: lcdif-axi + - const: lcdif-apb + - const: lcdif-pix + - const: dsi-pclk + - const: dsi-ref + - const: csi-aclk + - const: csi-pclk + +required: + - compatible + - reg + - power-domains + - power-domain-names + - clocks + - clock-names + +additionalProperties: false + +examples: + - | + #include <dt-bindings/clock/imx8mn-clock.h> + #include <dt-bindings/power/imx8mn-power.h> + + disp_blk_ctl: blk_ctrl@32e28000 { + compatible = "fsl,imx8mn-disp-blk-ctrl", "syscon"; + reg = <0x32e28000 0x100>; + power-domains = <&pgc_dispmix>, <&pgc_dispmix>, + <&pgc_dispmix>, <&pgc_mipi>, + <&pgc_mipi>; + power-domain-names = "bus", "isi", "lcdif", "mipi-dsi", + "mipi-csi"; + clocks = <&clk IMX8MN_CLK_DISP_AXI>, + <&clk IMX8MN_CLK_DISP_APB>, + <&clk IMX8MN_CLK_DISP_AXI_ROOT>, + <&clk IMX8MN_CLK_DISP_APB_ROOT>, + <&clk IMX8MN_CLK_DISP_AXI_ROOT>, + <&clk IMX8MN_CLK_DISP_APB_ROOT>, + <&clk IMX8MN_CLK_DISP_PIXEL_ROOT>, + <&clk IMX8MN_CLK_DSI_CORE>, + <&clk IMX8MN_CLK_DSI_PHY_REF>, + <&clk IMX8MN_CLK_CSI1_PHY_REF>, + <&clk IMX8MN_CLK_CAMERA_PIXEL_ROOT>; + clock-names = "disp_axi", "disp_apb", "disp_axi_root", "disp_apb_root", + "lcdif-axi", "lcdif-apb", "lcdif-pix", "dsi-pclk", + "dsi-ref", "csi-aclk", "csi-pclk"; + #power-domain-cells = <1>; + }; diff --git a/Documentation/devicetree/bindings/soc/qcom/qcom-stats.yaml b/Documentation/devicetree/bindings/soc/qcom/qcom-stats.yaml index 99dff7d73b7e..473adca4e973 100644 --- a/Documentation/devicetree/bindings/soc/qcom/qcom-stats.yaml +++ b/Documentation/devicetree/bindings/soc/qcom/qcom-stats.yaml @@ -21,6 +21,11 @@ properties: enum: - qcom,rpmh-stats - qcom,rpm-stats + # For older RPM firmware versions with fixed offset for the sleep stats + - qcom,apq8084-rpm-stats + - qcom,msm8226-rpm-stats + - qcom,msm8916-rpm-stats + - qcom,msm8974-rpm-stats reg: maxItems: 1 diff --git a/Documentation/devicetree/bindings/arm/samsung/exynos-chipid.yaml b/Documentation/devicetree/bindings/soc/samsung/exynos-chipid.yaml index bfc352a2fdd6..4bb8efb83ac1 100644 --- a/Documentation/devicetree/bindings/arm/samsung/exynos-chipid.yaml +++ b/Documentation/devicetree/bindings/soc/samsung/exynos-chipid.yaml @@ -1,7 +1,7 @@ # SPDX-License-Identifier: GPL-2.0 %YAML 1.2 --- -$id: http://devicetree.org/schemas/arm/samsung/exynos-chipid.yaml# +$id: http://devicetree.org/schemas/soc/samsung/exynos-chipid.yaml# $schema: http://devicetree.org/meta-schemas/core.yaml# title: Samsung Exynos SoC series Chipid driver diff --git a/Documentation/devicetree/bindings/arm/samsung/pmu.yaml b/Documentation/devicetree/bindings/soc/samsung/exynos-pmu.yaml index 17678d9686c1..c30a6437030d 100644 --- a/Documentation/devicetree/bindings/arm/samsung/pmu.yaml +++ b/Documentation/devicetree/bindings/soc/samsung/exynos-pmu.yaml @@ -1,7 +1,7 @@ # SPDX-License-Identifier: GPL-2.0 %YAML 1.2 --- -$id: http://devicetree.org/schemas/arm/samsung/pmu.yaml# +$id: http://devicetree.org/schemas/soc/samsung/exynos-pmu.yaml# $schema: http://devicetree.org/meta-schemas/core.yaml# title: Samsung Exynos SoC series Power Management Unit (PMU) @@ -24,6 +24,7 @@ select: - samsung,exynos5420-pmu - samsung,exynos5433-pmu - samsung,exynos7-pmu + - samsung,exynos850-pmu - samsung-s5pv210-pmu required: - compatible @@ -41,6 +42,7 @@ properties: - samsung,exynos5420-pmu - samsung,exynos5433-pmu - samsung,exynos7-pmu + - samsung,exynos850-pmu - samsung-s5pv210-pmu - const: syscon diff --git a/Documentation/devicetree/bindings/soc/samsung/exynos-usi.yaml b/Documentation/devicetree/bindings/soc/samsung/exynos-usi.yaml new file mode 100644 index 000000000000..273f2d95a043 --- /dev/null +++ b/Documentation/devicetree/bindings/soc/samsung/exynos-usi.yaml @@ -0,0 +1,159 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/soc/samsung/exynos-usi.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Samsung's Exynos USI (Universal Serial Interface) binding + +maintainers: + - Sam Protsenko <semen.protsenko@linaro.org> + - Krzysztof Kozlowski <krzysztof.kozlowski@canonical.com> + +description: | + USI IP-core provides selectable serial protocol (UART, SPI or High-Speed I2C). + USI shares almost all internal circuits within each protocol, so only one + protocol can be chosen at a time. USI is modeled as a node with zero or more + child nodes, each representing a serial sub-node device. The mode setting + selects which particular function will be used. + + Refer to next bindings documentation for information on protocol subnodes that + can exist under USI node: + + [1] Documentation/devicetree/bindings/serial/samsung_uart.yaml + [2] Documentation/devicetree/bindings/i2c/i2c-exynos5.txt + [3] Documentation/devicetree/bindings/spi/spi-samsung.txt + +properties: + $nodename: + pattern: "^usi@[0-9a-f]+$" + + compatible: + enum: + - samsung,exynos850-usi # for USIv2 (Exynos850, ExynosAutoV9) + + reg: true + + clocks: true + + clock-names: true + + ranges: true + + "#address-cells": + const: 1 + + "#size-cells": + const: 1 + + samsung,sysreg: + $ref: /schemas/types.yaml#/definitions/phandle-array + description: + Should be phandle/offset pair. The phandle to System Register syscon node + (for the same domain where this USI controller resides) and the offset + of SW_CONF register for this USI controller. + + samsung,mode: + $ref: /schemas/types.yaml#/definitions/uint32 + description: + Selects USI function (which serial protocol to use). Refer to + <include/dt-bindings/soc/samsung,exynos-usi.h> for valid USI mode values. + + samsung,clkreq-on: + type: boolean + description: + Enable this property if underlying protocol requires the clock to be + continuously provided without automatic gating. As suggested by SoC + manual, it should be set in case of SPI/I2C slave, UART Rx and I2C + multi-master mode. Usually this property is needed if USI mode is set + to "UART". + + This property is optional. + +patternProperties: + # All other properties should be child nodes + "^(serial|spi|i2c)@[0-9a-f]+$": + type: object + description: Child node describing underlying USI serial protocol + +required: + - compatible + - ranges + - "#address-cells" + - "#size-cells" + - samsung,sysreg + - samsung,mode + +if: + properties: + compatible: + contains: + enum: + - samsung,exynos850-usi + +then: + properties: + reg: + maxItems: 1 + + clocks: + items: + - description: Bus (APB) clock + - description: Operating clock for UART/SPI/I2C protocol + + clock-names: + items: + - const: pclk + - const: ipclk + + required: + - reg + - clocks + - clock-names + +else: + properties: + reg: false + clocks: false + clock-names: false + samsung,clkreq-on: false + +additionalProperties: false + +examples: + - | + #include <dt-bindings/interrupt-controller/arm-gic.h> + #include <dt-bindings/soc/samsung,exynos-usi.h> + + usi0: usi@138200c0 { + compatible = "samsung,exynos850-usi"; + reg = <0x138200c0 0x20>; + samsung,sysreg = <&sysreg_peri 0x1010>; + samsung,mode = <USI_V2_UART>; + samsung,clkreq-on; /* needed for UART mode */ + #address-cells = <1>; + #size-cells = <1>; + ranges; + clocks = <&cmu_peri 32>, <&cmu_peri 31>; + clock-names = "pclk", "ipclk"; + + serial_0: serial@13820000 { + compatible = "samsung,exynos850-uart"; + reg = <0x13820000 0xc0>; + interrupts = <GIC_SPI 227 IRQ_TYPE_LEVEL_HIGH>; + clocks = <&cmu_peri 32>, <&cmu_peri 31>; + clock-names = "uart", "clk_uart_baud0"; + status = "disabled"; + }; + + hsi2c_0: i2c@13820000 { + compatible = "samsung,exynosautov9-hsi2c"; + reg = <0x13820000 0xc0>; + interrupts = <GIC_SPI 227 IRQ_TYPE_LEVEL_HIGH>; + #address-cells = <1>; + #size-cells = <0>; + clocks = <&cmu_peri 31>, <&cmu_peri 32>; + clock-names = "hsi2c", "hsi2c_pclk"; + status = "disabled"; + }; + }; diff --git a/Documentation/devicetree/bindings/sound/wlf,wm8962.yaml b/Documentation/devicetree/bindings/sound/wlf,wm8962.yaml index 0e6249d7c133..5e172e9462b9 100644 --- a/Documentation/devicetree/bindings/sound/wlf,wm8962.yaml +++ b/Documentation/devicetree/bindings/sound/wlf,wm8962.yaml @@ -19,6 +19,9 @@ properties: clocks: maxItems: 1 + interrupts: + maxItems: 1 + "#sound-dai-cells": const: 0 diff --git a/Documentation/devicetree/bindings/spi/atmel,quadspi.yaml b/Documentation/devicetree/bindings/spi/atmel,quadspi.yaml new file mode 100644 index 000000000000..1d493add4053 --- /dev/null +++ b/Documentation/devicetree/bindings/spi/atmel,quadspi.yaml @@ -0,0 +1,99 @@ +# SPDX-License-Identifier: GPL-2.0-only OR BSD-2-Clause +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/spi/atmel,quadspi.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Atmel Quad Serial Peripheral Interface (QSPI) + +maintainers: + - Tudor Ambarus <tudor.ambarus@microchip.com> + +allOf: + - $ref: spi-controller.yaml# + +properties: + compatible: + enum: + - atmel,sama5d2-qspi + - microchip,sam9x60-qspi + - microchip,sama7g5-qspi + - microchip,sama7g5-ospi + + reg: + items: + - description: base registers + - description: mapped memory + + reg-names: + items: + - const: qspi_base + - const: qspi_mmap + + clocks: + minItems: 1 + items: + - description: peripheral clock + - description: system clock or generic clock, if available + + clock-names: + minItems: 1 + items: + - const: pclk + - enum: [ qspick, gclk ] + + interrupts: + maxItems: 1 + + dmas: + items: + - description: tx DMA channel + - description: rx DMA channel + + dma-names: + items: + - const: tx + - const: rx + + '#address-cells': + const: 1 + + '#size-cells': + const: 0 + +required: + - compatible + - reg + - reg-names + - interrupts + - clocks + - clock-names + - '#address-cells' + - '#size-cells' + +unevaluatedProperties: false + +examples: + - | + #include <dt-bindings/interrupt-controller/irq.h> + #include <dt-bindings/clock/at91.h> + spi@f0020000 { + compatible = "atmel,sama5d2-qspi"; + reg = <0xf0020000 0x100>, <0xd0000000 0x8000000>; + reg-names = "qspi_base", "qspi_mmap"; + interrupts = <52 IRQ_TYPE_LEVEL_HIGH 7>; + clocks = <&pmc PMC_TYPE_PERIPHERAL 52>; + clock-names = "pclk"; + #address-cells = <1>; + #size-cells = <0>; + pinctrl-names = "default"; + pinctrl-0 = <&pinctrl_spi0_default>; + + flash@0 { + compatible = "jedec,spi-nor"; + spi-max-frequency = <50000000>; + reg = <0>; + spi-rx-bus-width = <4>; + spi-tx-bus-width = <4>; + }; + }; diff --git a/Documentation/devicetree/bindings/spi/atmel-quadspi.txt b/Documentation/devicetree/bindings/spi/atmel-quadspi.txt deleted file mode 100644 index 7c40ea694352..000000000000 --- a/Documentation/devicetree/bindings/spi/atmel-quadspi.txt +++ /dev/null @@ -1,37 +0,0 @@ -* Atmel Quad Serial Peripheral Interface (QSPI) - -Required properties: -- compatible: Should be one of the following: - - "atmel,sama5d2-qspi" - - "microchip,sam9x60-qspi" -- reg: Should contain the locations and lengths of the base registers - and the mapped memory. -- reg-names: Should contain the resource reg names: - - qspi_base: configuration register address space - - qspi_mmap: memory mapped address space -- interrupts: Should contain the interrupt for the device. -- clocks: Should reference the peripheral clock and the QSPI system - clock if available. -- clock-names: Should contain "pclk" for the peripheral clock and "qspick" - for the system clock when available. -- #address-cells: Should be <1>. -- #size-cells: Should be <0>. - -Example: - -spi@f0020000 { - compatible = "atmel,sama5d2-qspi"; - reg = <0xf0020000 0x100>, <0xd0000000 0x8000000>; - reg-names = "qspi_base", "qspi_mmap"; - interrupts = <52 IRQ_TYPE_LEVEL_HIGH 7>; - clocks = <&pmc PMC_TYPE_PERIPHERAL 52>; - clock-names = "pclk"; - #address-cells = <1>; - #size-cells = <0>; - pinctrl-names = "default"; - pinctrl-0 = <&pinctrl_spi0_default>; - - m25p80@0 { - ... - }; -}; diff --git a/Documentation/devicetree/bindings/spi/cdns,qspi-nor-peripheral-props.yaml b/Documentation/devicetree/bindings/spi/cdns,qspi-nor-peripheral-props.yaml new file mode 100644 index 000000000000..553601a441a7 --- /dev/null +++ b/Documentation/devicetree/bindings/spi/cdns,qspi-nor-peripheral-props.yaml @@ -0,0 +1,42 @@ +# SPDX-License-Identifier: (GPL-2.0 OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/spi/cdns,qspi-nor-peripheral-props.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Peripheral-specific properties for the Cadence QSPI controller. + +description: + See spi-peripheral-props.yaml for more info. + +maintainers: + - Pratyush Yadav <p.yadav@ti.com> + +properties: + # cdns,qspi-nor.yaml + cdns,read-delay: + $ref: /schemas/types.yaml#/definitions/uint32 + description: + Delay for read capture logic, in clock cycles. + + cdns,tshsl-ns: + description: + Delay in nanoseconds for the length that the master mode chip select + outputs are de-asserted between transactions. + + cdns,tsd2d-ns: + description: + Delay in nanoseconds between one chip select being de-activated + and the activation of another. + + cdns,tchsh-ns: + description: + Delay in nanoseconds between last bit of current transaction and + deasserting the device chip select (qspi_n_ss_out). + + cdns,tslch-ns: + description: + Delay in nanoseconds between setting qspi_n_ss_out low and + first bit transfer. + +additionalProperties: true diff --git a/Documentation/devicetree/bindings/spi/cdns,qspi-nor.yaml b/Documentation/devicetree/bindings/spi/cdns,qspi-nor.yaml index ca155abbda7a..0a537fa3a641 100644 --- a/Documentation/devicetree/bindings/spi/cdns,qspi-nor.yaml +++ b/Documentation/devicetree/bindings/spi/cdns,qspi-nor.yaml @@ -29,6 +29,7 @@ properties: - ti,am654-ospi - intel,lgm-qspi - xlnx,versal-ospi-1.0 + - intel,socfpga-qspi - const: cdns,qspi-nor - const: cdns,qspi-nor @@ -86,39 +87,6 @@ properties: items: enum: [ qspi, qspi-ocp ] -# subnode's properties -patternProperties: - "@[0-9a-f]+$": - type: object - description: - Flash device uses the below defined properties in the subnode. - - properties: - cdns,read-delay: - $ref: /schemas/types.yaml#/definitions/uint32 - description: - Delay for read capture logic, in clock cycles. - - cdns,tshsl-ns: - description: - Delay in nanoseconds for the length that the master mode chip select - outputs are de-asserted between transactions. - - cdns,tsd2d-ns: - description: - Delay in nanoseconds between one chip select being de-activated - and the activation of another. - - cdns,tchsh-ns: - description: - Delay in nanoseconds between last bit of current transaction and - deasserting the device chip select (qspi_n_ss_out). - - cdns,tslch-ns: - description: - Delay in nanoseconds between setting qspi_n_ss_out low and - first bit transfer. - required: - compatible - reg diff --git a/Documentation/devicetree/bindings/spi/mediatek,spi-mtk-nor.yaml b/Documentation/devicetree/bindings/spi/mediatek,spi-mtk-nor.yaml index 7393f30535df..4e4694e3d539 100644 --- a/Documentation/devicetree/bindings/spi/mediatek,spi-mtk-nor.yaml +++ b/Documentation/devicetree/bindings/spi/mediatek,spi-mtk-nor.yaml @@ -43,14 +43,19 @@ properties: maxItems: 1 clocks: + minItems: 2 items: - description: clock used for spi bus - description: clock used for controller + - description: clock used for nor dma bus. this depends on hardware + design, so this is optional. clock-names: + minItems: 2 items: - const: spi - const: sf + - const: axi required: - compatible @@ -72,7 +77,7 @@ examples: nor_flash: spi@1100d000 { compatible = "mediatek,mt8173-nor"; reg = <0 0x1100d000 0 0xe0>; - interrupts = <&spi_flash_irq>; + interrupts = <1>; clocks = <&pericfg CLK_PERI_SPI>, <&topckgen CLK_TOP_SPINFI_IFR_SEL>; clock-names = "spi", "sf"; #address-cells = <1>; @@ -84,4 +89,3 @@ examples: }; }; }; - diff --git a/Documentation/devicetree/bindings/spi/renesas,rspi.yaml b/Documentation/devicetree/bindings/spi/renesas,rspi.yaml index 8397f60d80a2..76e6d9e52fc7 100644 --- a/Documentation/devicetree/bindings/spi/renesas,rspi.yaml +++ b/Documentation/devicetree/bindings/spi/renesas,rspi.yaml @@ -21,7 +21,8 @@ properties: - enum: - renesas,rspi-r7s72100 # RZ/A1H - renesas,rspi-r7s9210 # RZ/A2 - - const: renesas,rspi-rz # RZ/A + - renesas,r9a07g044-rspi # RZ/G2{L,LC} + - const: renesas,rspi-rz # RZ/A and RZ/G2{L,LC} - items: - enum: @@ -122,6 +123,7 @@ allOf: contains: enum: - renesas,qspi + - renesas,r9a07g044-rspi then: required: - resets diff --git a/Documentation/devicetree/bindings/spi/spi-controller.yaml b/Documentation/devicetree/bindings/spi/spi-controller.yaml index 8246891602e7..36b72518f565 100644 --- a/Documentation/devicetree/bindings/spi/spi-controller.yaml +++ b/Documentation/devicetree/bindings/spi/spi-controller.yaml @@ -94,73 +94,8 @@ patternProperties: "^.*@[0-9a-f]+$": type: object - properties: - compatible: - description: - Compatible of the SPI device. - - reg: - minItems: 1 - maxItems: 256 - items: - minimum: 0 - maximum: 256 - description: - Chip select used by the device. - - spi-3wire: - $ref: /schemas/types.yaml#/definitions/flag - description: - The device requires 3-wire mode. - - spi-cpha: - $ref: /schemas/types.yaml#/definitions/flag - description: - The device requires shifted clock phase (CPHA) mode. - - spi-cpol: - $ref: /schemas/types.yaml#/definitions/flag - description: - The device requires inverse clock polarity (CPOL) mode. - - spi-cs-high: - $ref: /schemas/types.yaml#/definitions/flag - description: - The device requires the chip select active high. - - spi-lsb-first: - $ref: /schemas/types.yaml#/definitions/flag - description: - The device requires the LSB first mode. - - spi-max-frequency: - $ref: /schemas/types.yaml#/definitions/uint32 - description: - Maximum SPI clocking speed of the device in Hz. - - spi-rx-bus-width: - description: - Bus width to the SPI bus used for read transfers. - If 0 is provided, then no RX will be possible on this device. - $ref: /schemas/types.yaml#/definitions/uint32 - enum: [0, 1, 2, 4, 8] - default: 1 - - spi-rx-delay-us: - description: - Delay, in microseconds, after a read transfer. - - spi-tx-bus-width: - description: - Bus width to the SPI bus used for write transfers. - If 0 is provided, then no TX will be possible on this device. - $ref: /schemas/types.yaml#/definitions/uint32 - enum: [0, 1, 2, 4, 8] - default: 1 - - spi-tx-delay-us: - description: - Delay, in microseconds, after a write transfer. + allOf: + - $ref: spi-peripheral-props.yaml required: - compatible diff --git a/Documentation/devicetree/bindings/spi/spi-fsl-lpspi.yaml b/Documentation/devicetree/bindings/spi/spi-fsl-lpspi.yaml index 312d8fee9dbb..1d46877fe46a 100644 --- a/Documentation/devicetree/bindings/spi/spi-fsl-lpspi.yaml +++ b/Documentation/devicetree/bindings/spi/spi-fsl-lpspi.yaml @@ -14,10 +14,13 @@ allOf: properties: compatible: - enum: - - fsl,imx7ulp-spi - - fsl,imx8qxp-spi - + oneOf: + - enum: + - fsl,imx7ulp-spi + - fsl,imx8qxp-spi + - items: + - const: fsl,imx8ulp-spi + - const: fsl,imx7ulp-spi reg: maxItems: 1 diff --git a/Documentation/devicetree/bindings/spi/spi-mux.yaml b/Documentation/devicetree/bindings/spi/spi-mux.yaml index 51c7622dc20b..7ea79f6d33f3 100644 --- a/Documentation/devicetree/bindings/spi/spi-mux.yaml +++ b/Documentation/devicetree/bindings/spi/spi-mux.yaml @@ -31,6 +31,7 @@ description: | allOf: - $ref: "/schemas/spi/spi-controller.yaml#" + - $ref: "/schemas/spi/spi-peripheral-props.yaml#" maintainers: - Chris Packham <chris.packham@alliedtelesis.co.nz> diff --git a/Documentation/devicetree/bindings/spi/spi-peripheral-props.yaml b/Documentation/devicetree/bindings/spi/spi-peripheral-props.yaml new file mode 100644 index 000000000000..5dd209206e88 --- /dev/null +++ b/Documentation/devicetree/bindings/spi/spi-peripheral-props.yaml @@ -0,0 +1,89 @@ +# SPDX-License-Identifier: (GPL-2.0 OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/spi/spi-peripheral-props.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Peripheral-specific properties for a SPI bus. + +description: + Many SPI controllers need to add properties to peripheral devices. They could + be common properties like spi-max-frequency, spi-cpha, etc. or they could be + controller specific like delay in clock or data lines, etc. These properties + need to be defined in the peripheral node because they are per-peripheral and + there can be multiple peripherals attached to a controller. All those + properties are listed here. The controller specific properties should go in + their own separate schema that should be referenced from here. + +maintainers: + - Pratyush Yadav <p.yadav@ti.com> + +properties: + reg: + minItems: 1 + maxItems: 256 + items: + minimum: 0 + maximum: 256 + description: + Chip select used by the device. + + spi-3wire: + $ref: /schemas/types.yaml#/definitions/flag + description: + The device requires 3-wire mode. + + spi-cpha: + $ref: /schemas/types.yaml#/definitions/flag + description: + The device requires shifted clock phase (CPHA) mode. + + spi-cpol: + $ref: /schemas/types.yaml#/definitions/flag + description: + The device requires inverse clock polarity (CPOL) mode. + + spi-cs-high: + $ref: /schemas/types.yaml#/definitions/flag + description: + The device requires the chip select active high. + + spi-lsb-first: + $ref: /schemas/types.yaml#/definitions/flag + description: + The device requires the LSB first mode. + + spi-max-frequency: + $ref: /schemas/types.yaml#/definitions/uint32 + description: + Maximum SPI clocking speed of the device in Hz. + + spi-rx-bus-width: + description: + Bus width to the SPI bus used for read transfers. + If 0 is provided, then no RX will be possible on this device. + $ref: /schemas/types.yaml#/definitions/uint32 + enum: [0, 1, 2, 4, 8] + default: 1 + + spi-rx-delay-us: + description: + Delay, in microseconds, after a read transfer. + + spi-tx-bus-width: + description: + Bus width to the SPI bus used for write transfers. + If 0 is provided, then no TX will be possible on this device. + $ref: /schemas/types.yaml#/definitions/uint32 + enum: [0, 1, 2, 4, 8] + default: 1 + + spi-tx-delay-us: + description: + Delay, in microseconds, after a write transfer. + +# The controller specific properties go here. +allOf: + - $ref: cdns,qspi-nor-peripheral-props.yaml# + +additionalProperties: true diff --git a/Documentation/devicetree/bindings/spi/spi-pl022.yaml b/Documentation/devicetree/bindings/spi/spi-pl022.yaml index a91d868e40c5..6d633728fc2b 100644 --- a/Documentation/devicetree/bindings/spi/spi-pl022.yaml +++ b/Documentation/devicetree/bindings/spi/spi-pl022.yaml @@ -72,6 +72,9 @@ properties: - const: rx - const: tx + resets: + maxItems: 1 + patternProperties: "^[a-zA-Z][a-zA-Z0-9,+\\-._]{0,63}@[0-9a-f]+$": type: object diff --git a/Documentation/devicetree/bindings/spi/spi-rockchip.yaml b/Documentation/devicetree/bindings/spi/spi-rockchip.yaml index 7f987e79337c..52a78a2e362e 100644 --- a/Documentation/devicetree/bindings/spi/spi-rockchip.yaml +++ b/Documentation/devicetree/bindings/spi/spi-rockchip.yaml @@ -33,6 +33,7 @@ properties: - rockchip,rk3328-spi - rockchip,rk3368-spi - rockchip,rk3399-spi + - rockchip,rk3568-spi - rockchip,rv1126-spi - const: rockchip,rk3066-spi diff --git a/Documentation/devicetree/bindings/sram/sram.yaml b/Documentation/devicetree/bindings/sram/sram.yaml index d4e418b6a1c1..668a9a41a775 100644 --- a/Documentation/devicetree/bindings/sram/sram.yaml +++ b/Documentation/devicetree/bindings/sram/sram.yaml @@ -31,6 +31,9 @@ properties: - amlogic,meson-gxbb-sram - arm,juno-sram-ns - atmel,sama5d2-securam + - nvidia,tegra186-sysram + - nvidia,tegra194-sysram + - nvidia,tegra234-sysram - qcom,rpm-msg-ram - rockchip,rk3288-pmu-sram diff --git a/Documentation/devicetree/bindings/thermal/nvidia,tegra186-bpmp-thermal.txt b/Documentation/devicetree/bindings/thermal/nvidia,tegra186-bpmp-thermal.txt deleted file mode 100644 index fc87f6aa1b8f..000000000000 --- a/Documentation/devicetree/bindings/thermal/nvidia,tegra186-bpmp-thermal.txt +++ /dev/null @@ -1,33 +0,0 @@ -NVIDIA Tegra186 BPMP thermal sensor - -In Tegra186, the BPMP (Boot and Power Management Processor) implements an -interface that is used to read system temperatures, including CPU cluster -and GPU temperatures. This binding describes the thermal sensor that is -exposed by BPMP. - -The BPMP thermal node must be located directly inside the main BPMP node. See -../firmware/nvidia,tegra186-bpmp.txt for details of the BPMP binding. - -This node represents a thermal sensor. See Documentation/devicetree/bindings/thermal/thermal-sensor.yaml for details of the -core thermal binding. - -Required properties: -- compatible: - Array of strings. - One of: - - "nvidia,tegra186-bpmp-thermal" - - "nvidia,tegra194-bpmp-thermal" -- #thermal-sensor-cells: Cell for sensor index. - Single-cell integer. - Must be <1>. - -Example: - -bpmp { - ... - - bpmp_thermal: thermal { - compatible = "nvidia,tegra186-bpmp-thermal"; - #thermal-sensor-cells = <1>; - }; -}; diff --git a/Documentation/devicetree/bindings/thermal/nvidia,tegra186-bpmp-thermal.yaml b/Documentation/devicetree/bindings/thermal/nvidia,tegra186-bpmp-thermal.yaml new file mode 100644 index 000000000000..c91fd07e4061 --- /dev/null +++ b/Documentation/devicetree/bindings/thermal/nvidia,tegra186-bpmp-thermal.yaml @@ -0,0 +1,42 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/thermal/nvidia,tegra186-bpmp-thermal.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: NVIDIA Tegra186 (and later) BPMP thermal sensor + +maintainers: + - Thierry Reding <thierry.reding@gmail.com> + - Jon Hunter <jonathanh@nvidia.com> + +description: | + In Tegra186, the BPMP (Boot and Power Management Processor) implements + an interface that is used to read system temperatures, including CPU + cluster and GPU temperatures. This binding describes the thermal + sensor that is exposed by BPMP. + + The BPMP thermal node must be located directly inside the main BPMP + node. See ../firmware/nvidia,tegra186-bpmp.yaml for details of the + BPMP binding. + + This node represents a thermal sensor. See + + Documentation/devicetree/bindings/thermal/thermal-sensor.yaml + + for details of the core thermal binding. + +properties: + compatible: + enum: + - nvidia,tegra186-bpmp-thermal + - nvidia,tegra194-bpmp-thermal + + '#thermal-sensor-cells': + $ref: /schemas/types.yaml#/definitions/uint32 + description: Number of cells needed in the phandle specifier to + identify a given sensor. Must be 1 and the single cell specifies + the sensor index. + const: 1 + +additionalProperties: false diff --git a/Documentation/devicetree/bindings/thermal/rzg2l-thermal.yaml b/Documentation/devicetree/bindings/thermal/rzg2l-thermal.yaml new file mode 100644 index 000000000000..ccab9511a042 --- /dev/null +++ b/Documentation/devicetree/bindings/thermal/rzg2l-thermal.yaml @@ -0,0 +1,76 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/thermal/rzg2l-thermal.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Renesas RZ/G2L Thermal Sensor Unit + +description: + On RZ/G2L SoCs, the thermal sensor unit (TSU) measures the + temperature(Tj) inside the LSI. + +maintainers: + - Biju Das <biju.das.jz@bp.renesas.com> + +properties: + compatible: + items: + - enum: + - renesas,r9a07g044-tsu # RZ/G2{L,LC} + - const: renesas,rzg2l-tsu + + reg: + maxItems: 1 + + clocks: + maxItems: 1 + + power-domains: + maxItems: 1 + + resets: + maxItems: 1 + + "#thermal-sensor-cells": + const: 1 + +required: + - compatible + - reg + - clocks + - power-domains + - resets + - "#thermal-sensor-cells" + +additionalProperties: false + +examples: + - | + #include <dt-bindings/clock/r9a07g044-cpg.h> + + tsu: thermal@10059400 { + compatible = "renesas,r9a07g044-tsu", + "renesas,rzg2l-tsu"; + reg = <0x10059400 0x400>; + clocks = <&cpg CPG_MOD R9A07G044_TSU_PCLK>; + resets = <&cpg R9A07G044_TSU_PRESETN>; + power-domains = <&cpg>; + #thermal-sensor-cells = <1>; + }; + + thermal-zones { + cpu-thermal { + polling-delay-passive = <250>; + polling-delay = <1000>; + thermal-sensors = <&tsu 0>; + + trips { + sensor_crit: sensor-crit { + temperature = <125000>; + hysteresis = <1000>; + type = "critical"; + }; + }; + }; + }; diff --git a/Documentation/devicetree/bindings/timer/sifive,clint.yaml b/Documentation/devicetree/bindings/timer/sifive,clint.yaml index a35952f48742..8d5f4687add9 100644 --- a/Documentation/devicetree/bindings/timer/sifive,clint.yaml +++ b/Documentation/devicetree/bindings/timer/sifive,clint.yaml @@ -25,6 +25,7 @@ properties: items: - enum: - sifive,fu540-c000-clint + - starfive,jh7100-clint - canaan,k210-clint - const: sifive,clint0 diff --git a/Documentation/devicetree/bindings/trivial-devices.yaml b/Documentation/devicetree/bindings/trivial-devices.yaml index 791079021f1b..c451ae82d8d7 100644 --- a/Documentation/devicetree/bindings/trivial-devices.yaml +++ b/Documentation/devicetree/bindings/trivial-devices.yaml @@ -73,6 +73,8 @@ properties: - dallas,ds4510 # Digital Thermometer and Thermostat - dallas,ds75 + # Delta AHE-50DC Open19 power shelf fan control module + - delta,ahe50dc-fan # Delta Electronics DPS-650-AB power supply - delta,dps650ab # Delta Electronics DPS920AB 920W 54V Power Supply @@ -121,8 +123,14 @@ properties: - ibm,cffps2 # Infineon IR36021 digital POL buck controller - infineon,ir36021 + # Infineon IR38060 Voltage Regulator + - infineon,ir38060 # Infineon IR38064 Voltage Regulator - infineon,ir38064 + # Infineon IR38164 Voltage Regulator + - infineon,ir38164 + # Infineon IR38263 Voltage Regulator + - infineon,ir38263 # Infineon SLB9635 (Soft-) I2C TPM (old protocol, max 100khz) - infineon,slb9635tt # Infineon SLB9645 I2C TPM (new protocol, max 400khz) diff --git a/Documentation/devicetree/bindings/usb/nvidia,tegra-xudc.yaml b/Documentation/devicetree/bindings/usb/nvidia,tegra-xudc.yaml index 8428415896ce..a39c76b89484 100644 --- a/Documentation/devicetree/bindings/usb/nvidia,tegra-xudc.yaml +++ b/Documentation/devicetree/bindings/usb/nvidia,tegra-xudc.yaml @@ -59,6 +59,19 @@ properties: - const: fs_src - const: hs_src + interconnects: + items: + - description: memory read client + - description: memory write client + + interconnect-names: + items: + - const: dma-mem # read + - const: write + + iommus: + maxItems: 1 + power-domains: items: - description: XUSBB(device) power-domain diff --git a/Documentation/devicetree/bindings/vendor-prefixes.yaml b/Documentation/devicetree/bindings/vendor-prefixes.yaml index 66d6432fd781..ae2aaaba620a 100644 --- a/Documentation/devicetree/bindings/vendor-prefixes.yaml +++ b/Documentation/devicetree/bindings/vendor-prefixes.yaml @@ -187,6 +187,8 @@ patternProperties: description: Shanghai Broadmobi Communication Technology Co.,Ltd. "^brcm,.*": description: Broadcom Corporation + "^bsh,.*": + description: BSH Hausgeraete GmbH "^buffalo,.*": description: Buffalo, Inc. "^bur,.*": @@ -379,6 +381,8 @@ patternProperties: description: Silicon Laboratories (formerly Energy Micro AS) "^engicam,.*": description: Engicam S.r.l. + "^engleder,.*": + description: Engleder "^epcos,.*": description: EPCOS AG "^epfl,.*": @@ -593,6 +597,8 @@ patternProperties: description: JetHome (IP Sokolov P.A.) "^jianda,.*": description: Jiandangjing Technology Co., Ltd. + "^joz,.*": + description: JOZ BV "^kam,.*": description: Kamstrup A/S "^karo,.*": @@ -1236,6 +1242,8 @@ patternProperties: description: Truly Semiconductors Limited "^visionox,.*": description: Visionox + "^team-source-display,.*": + description: Shenzhen Team Source Display Technology Co., Ltd. (TSD) "^tsd,.*": description: Theobroma Systems Design und Consulting GmbH "^tyan,.*": @@ -1272,6 +1280,8 @@ patternProperties: description: Variscite Ltd. "^vdl,.*": description: Van der Laan b.v. + "^vertexcom,.*": + description: Vertexcom Technologies, Inc. "^via,.*": description: VIA Technologies, Inc. "^videostrong,.*": @@ -1318,6 +1328,8 @@ patternProperties: description: Wiligear, Ltd. "^winbond,.*": description: Winbond Electronics corp. + "^winlink,.*": + description: WinLink Co., Ltd "^winstar,.*": description: Winstar Display Corp. "^wits,.*": @@ -1328,6 +1340,8 @@ patternProperties: description: Wondermedia Technologies, Inc. "^wobo,.*": description: Wobo + "^wanchanglong,.*": + description: Wanchanglong Electronics Technology（SHENZHEN）Co.，Ltd. "^x-powers,.*": description: X-Powers "^xes,.*": @@ -1350,6 +1364,8 @@ patternProperties: description: Shenzhen Xunlong Software CO.,Limited "^xylon,.*": description: Xylon + "^yadro,.*": + description: YADRO "^yamaha,.*": description: Yamaha Corporation "^yes-optoelectronics,.*": diff --git a/Documentation/devicetree/bindings/watchdog/apple,wdt.yaml b/Documentation/devicetree/bindings/watchdog/apple,wdt.yaml new file mode 100644 index 000000000000..e58c56a6fdf6 --- /dev/null +++ b/Documentation/devicetree/bindings/watchdog/apple,wdt.yaml @@ -0,0 +1,52 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/watchdog/apple,wdt.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Apple SoC Watchdog + +allOf: + - $ref: "watchdog.yaml#" + +maintainers: + - Sven Peter <sven@svenpeter.dev> + +properties: + compatible: + items: + - enum: + - apple,t8103-wdt + - apple,t6000-wdt + - const: apple,wdt + + reg: + maxItems: 1 + + clocks: + maxItems: 1 + + interrupts: + maxItems: 1 + +required: + - compatible + - reg + - clocks + - interrupts + +unevaluatedProperties: false + +examples: + - | + #include <dt-bindings/interrupt-controller/apple-aic.h> + #include <dt-bindings/interrupt-controller/irq.h> + + wdt: watchdog@50000000 { + compatible = "apple,t8103-wdt", "apple,wdt"; + reg = <0x50000000 0x4000>; + clocks = <&clk>; + interrupts = <AIC_IRQ 123 IRQ_TYPE_LEVEL_HIGH>; + }; + +... diff --git a/Documentation/doc-guide/sphinx.rst b/Documentation/doc-guide/sphinx.rst index e445cb146efe..bb36f18ae9ac 100644 --- a/Documentation/doc-guide/sphinx.rst +++ b/Documentation/doc-guide/sphinx.rst @@ -138,6 +138,17 @@ To pass extra options to Sphinx, you can use the ``SPHINXOPTS`` make variable. For example, use ``make SPHINXOPTS=-v htmldocs`` to get more verbose output. +It is also possible to pass an extra DOCS_CSS overlay file, in order to customize +the html layout, by using the ``DOCS_CSS`` make variable. + +By default, the build will try to use the Read the Docs sphinx theme: + + https://github.com/readthedocs/sphinx_rtd_theme + +If the theme is not available, it will fall-back to the classic one. + +The Sphinx theme can be overridden by using the ``DOCS_THEME`` make variable. + To remove the generated documentation, run ``make cleandocs``. Writing Documentation @@ -250,12 +261,11 @@ please feel free to remove it. list tables ----------- -We recommend the use of *list table* formats. The *list table* formats are -double-stage lists. Compared to the ASCII-art they might not be as -comfortable for -readers of the text files. Their advantage is that they are easy to -create or modify and that the diff of a modification is much more meaningful, -because it is limited to the modified content. +The list-table formats can be useful for tables that are not easily laid +out in the usual Sphinx ASCII-art formats. These formats are nearly +impossible for readers of the plain-text documents to understand, though, +and should be avoided in the absence of a strong justification for their +use. The ``flat-table`` is a double-stage list similar to the ``list-table`` with some additional features: diff --git a/Documentation/driver-api/media/drivers/index.rst b/Documentation/driver-api/media/drivers/index.rst index 426cda633bf0..32406490557c 100644 --- a/Documentation/driver-api/media/drivers/index.rst +++ b/Documentation/driver-api/media/drivers/index.rst @@ -21,6 +21,7 @@ Video4Linux (V4L) drivers pvrusb2 pxa_camera radiotrack + rkisp1 saa7134-devel sh_mobile_ceu_camera tuners diff --git a/Documentation/filesystems/idmappings.rst b/Documentation/filesystems/idmappings.rst index 1229a75ec75d..7a879ec3b6bf 100644 --- a/Documentation/filesystems/idmappings.rst +++ b/Documentation/filesystems/idmappings.rst @@ -952,75 +952,3 @@ The raw userspace id that is put on disk is ``u1000`` so when the user takes their home directory back to their home computer where they are assigned ``u1000`` using the initial idmapping and mount the filesystem with the initial idmapping they will see all those files owned by ``u1000``. - -Shortcircuting --------------- - -Currently, the implementation of idmapped mounts enforces that the filesystem -is mounted with the initial idmapping. The reason is simply that none of the -filesystems that we targeted were mountable with a non-initial idmapping. But -that might change soon enough. As we've seen above, thanks to the properties of -idmappings the translation works for both filesystems mounted with the initial -idmapping and filesystem with non-initial idmappings. - -Based on this current restriction to filesystem mounted with the initial -idmapping two noticeable shortcuts have been taken: - -1. We always stash a reference to the initial user namespace in ``struct - vfsmount``. Idmapped mounts are thus mounts that have a non-initial user - namespace attached to them. - - In order to support idmapped mounts this needs to be changed. Instead of - stashing the initial user namespace the user namespace the filesystem was - mounted with must be stashed. An idmapped mount is then any mount that has - a different user namespace attached then the filesystem was mounted with. - This has no user-visible consequences. - -2. The translation algorithms in ``mapped_fs*id()`` and ``i_*id_into_mnt()`` - are simplified. - - Let's consider ``mapped_fs*id()`` first. This function translates the - caller's kernel id into a kernel id in the filesystem's idmapping via - a mount's idmapping. The full algorithm is:: - - mapped_fsuid(kid): - /* Map the kernel id up into a userspace id in the mount's idmapping. */ - from_kuid(mount-idmapping, kid) = uid - - /* Map the userspace id down into a kernel id in the filesystem's idmapping. */ - make_kuid(filesystem-idmapping, uid) = kuid - - We know that the filesystem is always mounted with the initial idmapping as - we enforce this in ``mount_setattr()``. So this can be shortened to:: - - mapped_fsuid(kid): - /* Map the kernel id up into a userspace id in the mount's idmapping. */ - from_kuid(mount-idmapping, kid) = uid - - /* Map the userspace id down into a kernel id in the filesystem's idmapping. */ - KUIDT_INIT(uid) = kuid - - Similarly, for ``i_*id_into_mnt()`` which translated the filesystem's kernel - id into a mount's kernel id:: - - i_uid_into_mnt(kid): - /* Map the kernel id up into a userspace id in the filesystem's idmapping. */ - from_kuid(filesystem-idmapping, kid) = uid - - /* Map the userspace id down into a kernel id in the mounts's idmapping. */ - make_kuid(mount-idmapping, uid) = kuid - - Again, we know that the filesystem is always mounted with the initial - idmapping as we enforce this in ``mount_setattr()``. So this can be - shortened to:: - - i_uid_into_mnt(kid): - /* Map the kernel id up into a userspace id in the filesystem's idmapping. */ - __kuid_val(kid) = uid - - /* Map the userspace id down into a kernel id in the mounts's idmapping. */ - make_kuid(mount-idmapping, uid) = kuid - -Handling filesystems mounted with non-initial idmappings requires that the -translation functions be converted to their full form. They can still be -shortcircuited on non-idmapped mounts. This has no user-visible consequences. diff --git a/Documentation/filesystems/locking.rst b/Documentation/filesystems/locking.rst index d36fe79167b3..3f9b1497ebb8 100644 --- a/Documentation/filesystems/locking.rst +++ b/Documentation/filesystems/locking.rst @@ -169,7 +169,6 @@ prototypes:: int (*show_options)(struct seq_file *, struct dentry *); ssize_t (*quota_read)(struct super_block *, int, char *, size_t, loff_t); ssize_t (*quota_write)(struct super_block *, int, const char *, size_t, loff_t); - int (*bdev_try_to_free_page)(struct super_block*, struct page*, gfp_t); locking rules: All may block [not true, see below] @@ -194,7 +193,6 @@ umount_begin: no show_options: no (namespace_sem) quota_read: no (see below) quota_write: no (see below) -bdev_try_to_free_page: no (see below) ====================== ============ ======================== ->statfs() has s_umount (shared) when called by ustat(2) (native or @@ -210,9 +208,6 @@ dqio_sem) (unless an admin really wants to screw up something and writes to quota files with quotas on). For other details about locking see also dquot_operations section. -->bdev_try_to_free_page is called from the ->releasepage handler of -the block device inode. See there for more details. - file_system_type ================ diff --git a/Documentation/filesystems/netfs_library.rst b/Documentation/filesystems/netfs_library.rst index bb68d39f03b7..375baca7edcd 100644 --- a/Documentation/filesystems/netfs_library.rst +++ b/Documentation/filesystems/netfs_library.rst @@ -1,7 +1,7 @@ .. SPDX-License-Identifier: GPL-2.0 ================================= -NETWORK FILESYSTEM HELPER LIBRARY +Network Filesystem Helper Library ================================= .. Contents: @@ -37,22 +37,22 @@ into a common call framework. The following services are provided: - * Handles transparent huge pages (THPs). + * Handle folios that span multiple pages. - * Insulates the netfs from VM interface changes. + * Insulate the netfs from VM interface changes. - * Allows the netfs to arbitrarily split reads up into pieces, even ones that - don't match page sizes or page alignments and that may cross pages. + * Allow the netfs to arbitrarily split reads up into pieces, even ones that + don't match folio sizes or folio alignments and that may cross folios. - * Allows the netfs to expand a readahead request in both directions to meet - its needs. + * Allow the netfs to expand a readahead request in both directions to meet its + needs. - * Allows the netfs to partially fulfil a read, which will then be resubmitted. + * Allow the netfs to partially fulfil a read, which will then be resubmitted. - * Handles local caching, allowing cached data and server-read data to be + * Handle local caching, allowing cached data and server-read data to be interleaved for a single request. - * Handles clearing of bufferage that aren't on the server. + * Handle clearing of bufferage that aren't on the server. * Handle retrying of reads that failed, switching reads from the cache to the server as necessary. @@ -70,22 +70,22 @@ Read Helper Functions Three read helpers are provided:: - * void netfs_readahead(struct readahead_control *ractl, - const struct netfs_read_request_ops *ops, - void *netfs_priv);`` - * int netfs_readpage(struct file *file, - struct page *page, - const struct netfs_read_request_ops *ops, - void *netfs_priv); - * int netfs_write_begin(struct file *file, - struct address_space *mapping, - loff_t pos, - unsigned int len, - unsigned int flags, - struct page **_page, - void **_fsdata, - const struct netfs_read_request_ops *ops, - void *netfs_priv); + void netfs_readahead(struct readahead_control *ractl, + const struct netfs_read_request_ops *ops, + void *netfs_priv); + int netfs_readpage(struct file *file, + struct folio *folio, + const struct netfs_read_request_ops *ops, + void *netfs_priv); + int netfs_write_begin(struct file *file, + struct address_space *mapping, + loff_t pos, + unsigned int len, + unsigned int flags, + struct folio **_folio, + void **_fsdata, + const struct netfs_read_request_ops *ops, + void *netfs_priv); Each corresponds to a VM operation, with the addition of a couple of parameters for the use of the read helpers: @@ -103,8 +103,8 @@ Both of these values will be stored into the read request structure. For ->readahead() and ->readpage(), the network filesystem should just jump into the corresponding read helper; whereas for ->write_begin(), it may be a little more complicated as the network filesystem might want to flush -conflicting writes or track dirty data and needs to put the acquired page if an -error occurs after calling the helper. +conflicting writes or track dirty data and needs to put the acquired folio if +an error occurs after calling the helper. The helpers manage the read request, calling back into the network filesystem through the suppplied table of operations. Waits will be performed as @@ -253,7 +253,7 @@ through which it can issue requests and negotiate:: void (*issue_op)(struct netfs_read_subrequest *subreq); bool (*is_still_valid)(struct netfs_read_request *rreq); int (*check_write_begin)(struct file *file, loff_t pos, unsigned len, - struct page *page, void **_fsdata); + struct folio *folio, void **_fsdata); void (*done)(struct netfs_read_request *rreq); void (*cleanup)(struct address_space *mapping, void *netfs_priv); }; @@ -313,13 +313,14 @@ The operations are as follows: There is no return value; the netfs_subreq_terminated() function should be called to indicate whether or not the operation succeeded and how much data - it transferred. The filesystem also should not deal with setting pages + it transferred. The filesystem also should not deal with setting folios uptodate, unlocking them or dropping their refs - the helpers need to deal with this as they have to coordinate with copying to the local cache. - Note that the helpers have the pages locked, but not pinned. It is possible - to use the ITER_XARRAY iov iterator to refer to the range of the inode that - is being operated upon without the need to allocate large bvec tables. + Note that the helpers have the folios locked, but not pinned. It is + possible to use the ITER_XARRAY iov iterator to refer to the range of the + inode that is being operated upon without the need to allocate large bvec + tables. * ``is_still_valid()`` @@ -330,15 +331,15 @@ The operations are as follows: * ``check_write_begin()`` [Optional] This is called from the netfs_write_begin() helper once it has - allocated/grabbed the page to be modified to allow the filesystem to flush + allocated/grabbed the folio to be modified to allow the filesystem to flush conflicting state before allowing it to be modified. - It should return 0 if everything is now fine, -EAGAIN if the page should be + It should return 0 if everything is now fine, -EAGAIN if the folio should be regrabbed and any other error code to abort the operation. * ``done`` - [Optional] This is called after the pages in the request have all been + [Optional] This is called after the folios in the request have all been unlocked (and marked uptodate if applicable). * ``cleanup`` @@ -390,7 +391,7 @@ The read helpers work by the following general procedure: * If NETFS_SREQ_CLEAR_TAIL was set, a short read will be cleared to the end of the slice instead of reissuing. - * Once the data is read, the pages that have been fully read/cleared: + * Once the data is read, the folios that have been fully read/cleared: * Will be marked uptodate. @@ -398,11 +399,11 @@ The read helpers work by the following general procedure: * Unlocked - * Any pages that need writing to the cache will then have DIO writes issued. + * Any folios that need writing to the cache will then have DIO writes issued. * Synchronous operations will wait for reading to be complete. - * Writes to the cache will proceed asynchronously and the pages will have the + * Writes to the cache will proceed asynchronously and the folios will have the PG_fscache mark removed when that completes. * The request structures will be cleaned up when everything has completed. @@ -452,6 +453,9 @@ operation table looks like the following:: netfs_io_terminated_t term_func, void *term_func_priv); + int (*prepare_write)(struct netfs_cache_resources *cres, + loff_t *_start, size_t *_len, loff_t i_size); + int (*write)(struct netfs_cache_resources *cres, loff_t start_pos, struct iov_iter *iter, @@ -509,6 +513,14 @@ The methods defined in the table are: indicating whether the termination is definitely happening in the caller's context. + * ``prepare_write()`` + + [Required] Called to adjust a write to the cache and check that there is + sufficient space in the cache. The start and length values indicate the + size of the write that netfslib is proposing, and this can be adjusted by + the cache to respect DIO boundaries. The file size is passed for + information. + * ``write()`` [Required] Called to write to the cache. The start file offset is given @@ -525,4 +537,9 @@ not the read request structure as they could be used in other situations where there isn't a read request structure as well, such as writing dirty data to the cache. + +API Function Reference +====================== + .. kernel-doc:: include/linux/netfs.h +.. kernel-doc:: fs/netfs/read_helper.c diff --git a/Documentation/firmware-guide/acpi/apei/einj.rst b/Documentation/firmware-guide/acpi/apei/einj.rst index c042176e1707..55e2331a6438 100644 --- a/Documentation/firmware-guide/acpi/apei/einj.rst +++ b/Documentation/firmware-guide/acpi/apei/einj.rst @@ -181,5 +181,24 @@ You should see something like this in dmesg:: [22715.834759] EDAC sbridge MC3: PROCESSOR 0:306e7 TIME 1422553404 SOCKET 0 APIC 0 [22716.616173] EDAC MC3: 1 CE memory read error on CPU_SrcID#0_Channel#0_DIMM#0 (channel:0 slot:0 page:0x12345 offset:0x0 grain:32 syndrome:0x0 - area:DRAM err_code:0001:0090 socket:0 channel_mask:1 rank:0) +Special notes for injection into SGX enclaves: + +There may be a separate BIOS setup option to enable SGX injection. + +The injection process consists of setting some special memory controller +trigger that will inject the error on the next write to the target +address. But the h/w prevents any software outside of an SGX enclave +from accessing enclave pages (even BIOS SMM mode). + +The following sequence can be used: + 1) Determine physical address of enclave page + 2) Use "notrigger=1" mode to inject (this will setup + the injection address, but will not actually inject) + 3) Enter the enclave + 4) Store data to the virtual address matching physical address from step 1 + 5) Execute CLFLUSH for that virtual address + 6) Spin delay for 250ms + 7) Read from the virtual address. This will trigger the error + For more information about EINJ, please refer to ACPI specification version 4.0, section 17.5 and ACPI 5.0, section 18.6. diff --git a/Documentation/firmware-guide/acpi/dsd/data-node-references.rst b/Documentation/firmware-guide/acpi/dsd/data-node-references.rst index b7ad47df49de..8d8b53e96bcf 100644 --- a/Documentation/firmware-guide/acpi/dsd/data-node-references.rst +++ b/Documentation/firmware-guide/acpi/dsd/data-node-references.rst @@ -5,7 +5,7 @@ Referencing hierarchical data nodes =================================== -:Copyright: |copy| 2018 Intel Corporation +:Copyright: |copy| 2018, 2021 Intel Corporation :Author: Sakari Ailus <sakari.ailus@linux.intel.com> ACPI in general allows referring to device objects in the tree only. @@ -13,9 +13,9 @@ Hierarchical data extension nodes may not be referred to directly, hence this document defines a scheme to implement such references. A reference consist of the device object name followed by one or more -hierarchical data extension [1] keys. Specifically, the hierarchical data -extension node which is referred to by the key shall lie directly under the -parent object i.e. either the device object or another hierarchical data +hierarchical data extension [dsd-guide] keys. Specifically, the hierarchical +data extension node which is referred to by the key shall lie directly under +the parent object i.e. either the device object or another hierarchical data extension node. The keys in the hierarchical data nodes shall consist of the name of the node, @@ -33,7 +33,7 @@ extension key. Example ======= -In the ASL snippet below, the "reference" _DSD property [2] contains a +In the ASL snippet below, the "reference" _DSD property contains a device object reference to DEV0 and under that device object, a hierarchical data extension key "node@1" referring to the NOD1 object and lastly, a hierarchical data extension key "anothernode" referring to @@ -52,12 +52,14 @@ the ANOD object which is also the final target node of the reference. Name (NOD0, Package() { ToUUID("daffd814-6eba-4d8c-8a91-bc9bbf4aa301"), Package () { + Package () { "reg", 0 }, Package () { "random-property", 3 }, } }) Name (NOD1, Package() { ToUUID("dbb8e3e6-5886-4ba6-8795-1319f52a966b"), Package () { + Package () { "reg", 1 }, Package () { "anothernode", "ANOD" }, } }) @@ -74,7 +76,11 @@ the ANOD object which is also the final target node of the reference. Name (_DSD, Package () { ToUUID("daffd814-6eba-4d8c-8a91-bc9bbf4aa301"), Package () { - Package () { "reference", ^DEV0, "node@1", "anothernode" }, + Package () { + "reference", Package () { + ^DEV0, "node@1", "anothernode" + } + }, } }) } @@ -85,10 +91,6 @@ Documentation/firmware-guide/acpi/dsd/graph.rst. References ========== -[1] Hierarchical Data Extension UUID For _DSD. -<https://www.uefi.org/sites/default/files/resources/_DSD-hierarchical-data-extension-UUID-v1.1.pdf>, -referenced 2018-07-17. - -[2] Device Properties UUID For _DSD. -<https://www.uefi.org/sites/default/files/resources/_DSD-device-properties-UUID.pdf>, -referenced 2016-10-04. +[dsd-guide] DSD Guide. + https://github.com/UEFI/DSD-Guide/blob/main/dsd-guide.adoc, referenced + 2021-11-30. diff --git a/Documentation/firmware-guide/acpi/dsd/graph.rst b/Documentation/firmware-guide/acpi/dsd/graph.rst index 0ced07cb1be3..b9dbfc73ed25 100644 --- a/Documentation/firmware-guide/acpi/dsd/graph.rst +++ b/Documentation/firmware-guide/acpi/dsd/graph.rst @@ -7,11 +7,11 @@ Graphs _DSD ==== -_DSD (Device Specific Data) [7] is a predefined ACPI device +_DSD (Device Specific Data) [dsd-guide] is a predefined ACPI device configuration object that can be used to convey information on hardware features which are not specifically covered by the ACPI -specification [1][6]. There are two _DSD extensions that are relevant -for graphs: property [4] and hierarchical data extensions [5]. The +specification [acpi]. There are two _DSD extensions that are relevant +for graphs: property [dsd-guide] and hierarchical data extensions. The property extension provides generic key-value pairs whereas the hierarchical data extension supports nodes with references to other nodes, forming a tree. The nodes in the tree may contain properties as @@ -36,8 +36,9 @@ Ports and endpoints =================== The port and endpoint concepts are very similar to those in Devicetree -[3]. A port represents an interface in a device, and an endpoint -represents a connection to that interface. +[devicetree, graph-bindings]. A port represents an interface in a device, and +an endpoint represents a connection to that interface. Also see [data-node-ref] +for generic data node references. All port nodes are located under the device's "_DSD" node in the hierarchical data extension tree. The data extension related to each port node must begin @@ -153,25 +154,20 @@ the "ISP" device and vice versa. References ========== -[1] _DSD (Device Specific Data) Implementation Guide. - https://www.uefi.org/sites/default/files/resources/_DSD-implementation-guide-toplevel-1_1.htm, - referenced 2016-10-03. +[acpi] Advanced Configuration and Power Interface Specification. + https://uefi.org/specifications/ACPI/6.4/, referenced 2021-11-30. -[2] Devicetree. https://www.devicetree.org, referenced 2016-10-03. +[data-node-ref] Documentation/firmware-guide/acpi/dsd/data-node-references.rst -[3] Documentation/devicetree/bindings/graph.txt +[devicetree] Devicetree. https://www.devicetree.org, referenced 2016-10-03. -[4] Device Properties UUID For _DSD. - https://www.uefi.org/sites/default/files/resources/_DSD-device-properties-UUID.pdf, - referenced 2016-10-04. +[dsd-guide] DSD Guide. + https://github.com/UEFI/DSD-Guide/blob/main/dsd-guide.adoc, referenced + 2021-11-30. -[5] Hierarchical Data Extension UUID For _DSD. - https://www.uefi.org/sites/default/files/resources/_DSD-hierarchical-data-extension-UUID-v1.1.pdf, - referenced 2016-10-04. - -[6] Advanced Configuration and Power Interface Specification. - https://www.uefi.org/sites/default/files/resources/ACPI_6_1.pdf, - referenced 2016-10-04. - -[7] _DSD Device Properties Usage Rules. +[dsd-rules] _DSD Device Properties Usage Rules. Documentation/firmware-guide/acpi/DSD-properties-rules.rst + +[graph-bindings] Common bindings for device graphs (Devicetree). + https://github.com/devicetree-org/dt-schema/blob/main/schemas/graph.yaml, + referenced 2021-11-30. diff --git a/Documentation/firmware-guide/acpi/dsd/leds.rst b/Documentation/firmware-guide/acpi/dsd/leds.rst index b99fff8e06f2..93db592c93c7 100644 --- a/Documentation/firmware-guide/acpi/dsd/leds.rst +++ b/Documentation/firmware-guide/acpi/dsd/leds.rst @@ -5,19 +5,20 @@ Describing and referring to LEDs in ACPI ======================================== -Individual LEDs are described by hierarchical data extension [6] nodes under the +Individual LEDs are described by hierarchical data extension [5] nodes under the device node, the LED driver chip. The "reg" property in the LED specific nodes tells the numerical ID of each individual LED output to which the LEDs are -connected. [3] The hierarchical data nodes are named "led@X", where X is the +connected. [leds] The hierarchical data nodes are named "led@X", where X is the number of the LED output. -Referring to LEDs in Device tree is documented in [4], in "flash-leds" property -documentation. In short, LEDs are directly referred to by using phandles. +Referring to LEDs in Device tree is documented in [video-interfaces], in +"flash-leds" property documentation. In short, LEDs are directly referred to by +using phandles. -While Device tree allows referring to any node in the tree[1], in ACPI -references are limited to device nodes only [2]. For this reason using the same -mechanism on ACPI is not possible. A mechanism to refer to non-device ACPI nodes -is documented in [7]. +While Device tree allows referring to any node in the tree [devicetree], in +ACPI references are limited to device nodes only [acpi]. For this reason using +the same mechanism on ACPI is not possible. A mechanism to refer to non-device +ACPI nodes is documented in [data-node-ref]. ACPI allows (as does DT) using integer arguments after the reference. A combination of the LED driver device reference and an integer argument, @@ -90,22 +91,17 @@ where References ========== -[1] Device tree. https://www.devicetree.org, referenced 2019-02-21. +[acpi] Advanced Configuration and Power Interface Specification. + https://uefi.org/specifications/ACPI/6.4/, referenced 2021-11-30. -[2] Advanced Configuration and Power Interface Specification. - https://uefi.org/sites/default/files/resources/ACPI_6_3_final_Jan30.pdf, - referenced 2019-02-21. +[data-node-ref] Documentation/firmware-guide/acpi/dsd/data-node-references.rst -[3] Documentation/devicetree/bindings/leds/common.txt +[devicetree] Devicetree. https://www.devicetree.org, referenced 2019-02-21. -[4] Documentation/devicetree/bindings/media/video-interfaces.txt +[dsd-guide] DSD Guide. + https://github.com/UEFI/DSD-Guide/blob/main/dsd-guide.adoc, referenced + 2021-11-30. -[5] Device Properties UUID For _DSD. - https://www.uefi.org/sites/default/files/resources/_DSD-device-properties-UUID.pdf, - referenced 2019-02-21. +[leds] Documentation/devicetree/bindings/leds/common.yaml -[6] Hierarchical Data Extension UUID For _DSD. - https://www.uefi.org/sites/default/files/resources/_DSD-hierarchical-data-extension-UUID-v1.1.pdf, - referenced 2019-02-21. - -[7] Documentation/firmware-guide/acpi/dsd/data-node-references.rst +[video-interfaces] Documentation/devicetree/bindings/media/video-interfaces.yaml diff --git a/Documentation/firmware-guide/acpi/dsd/phy.rst b/Documentation/firmware-guide/acpi/dsd/phy.rst index 680ad179e5f9..673ac374f92a 100644 --- a/Documentation/firmware-guide/acpi/dsd/phy.rst +++ b/Documentation/firmware-guide/acpi/dsd/phy.rst @@ -4,17 +4,17 @@ MDIO bus and PHYs in ACPI ========================= -The PHYs on an MDIO bus [1] are probed and registered using +The PHYs on an MDIO bus [phy] are probed and registered using fwnode_mdiobus_register_phy(). Later, for connecting these PHYs to their respective MACs, the PHYs registered on the MDIO bus have to be referenced. This document introduces two _DSD properties that are to be used -for connecting PHYs on the MDIO bus [3] to the MAC layer. +for connecting PHYs on the MDIO bus [dsd-properties-rules] to the MAC layer. These properties are defined in accordance with the "Device -Properties UUID For _DSD" [2] document and the +Properties UUID For _DSD" [dsd-guide] document and the daffd814-6eba-4d8c-8a91-bc9bbf4aa301 UUID must be used in the Device Data Descriptors containing them. @@ -48,22 +48,22 @@ as device object references (e.g. \_SB.MDI0.PHY1). phy-mode -------- The "phy-mode" _DSD property is used to describe the connection to -the PHY. The valid values for "phy-mode" are defined in [4]. +the PHY. The valid values for "phy-mode" are defined in [ethernet-controller]. managed ------- Optional property, which specifies the PHY management type. -The valid values for "managed" are defined in [4]. +The valid values for "managed" are defined in [ethernet-controller]. fixed-link ---------- The "fixed-link" is described by a data-only subnode of the MAC port, which is linked in the _DSD package via hierarchical data extension (UUID dbb8e3e6-5886-4ba6-8795-1319f52a966b -in accordance with [5] "_DSD Implementation Guide" document). +in accordance with [dsd-guide] "_DSD Implementation Guide" document). The subnode should comprise a required property ("speed") and possibly the optional ones - complete list of parameters and -their values are specified in [4]. +their values are specified in [ethernet-controller]. The following ASL example illustrates the usage of these properties. @@ -188,12 +188,14 @@ MAC node example with a "fixed-link" subnode. References ========== -[1] Documentation/networking/phy.rst +[phy] Documentation/networking/phy.rst -[2] https://www.uefi.org/sites/default/files/resources/_DSD-device-properties-UUID.pdf +[dsd-properties-rules] + Documentation/firmware-guide/acpi/DSD-properties-rules.rst -[3] Documentation/firmware-guide/acpi/DSD-properties-rules.rst +[ethernet-controller] + Documentation/devicetree/bindings/net/ethernet-controller.yaml -[4] Documentation/devicetree/bindings/net/ethernet-controller.yaml - -[5] https://github.com/UEFI/DSD-Guide/blob/main/dsd-guide.pdf +[dsd-guide] DSD Guide. + https://github.com/UEFI/DSD-Guide/blob/main/dsd-guide.adoc, referenced + 2021-11-30. diff --git a/Documentation/gpu/amdgpu-dc.rst b/Documentation/gpu/amdgpu-dc.rst deleted file mode 100644 index f7ff7e1309de..000000000000 --- a/Documentation/gpu/amdgpu-dc.rst +++ /dev/null @@ -1,74 +0,0 @@ -=================================== -drm/amd/display - Display Core (DC) -=================================== - -*placeholder - general description of supported platforms, what dc is, etc.* - -Because it is partially shared with other operating systems, the Display Core -Driver is divided in two pieces. - -1. **Display Core (DC)** contains the OS-agnostic components. Things like - hardware programming and resource management are handled here. -2. **Display Manager (DM)** contains the OS-dependent components. Hooks to the - amdgpu base driver and DRM are implemented here. - -It doesn't help that the entire package is frequently referred to as DC. But -with the context in mind, it should be clear. - -When CONFIG_DRM_AMD_DC is enabled, DC will be initialized by default for -supported ASICs. To force disable, set `amdgpu.dc=0` on kernel command line. -Likewise, to force enable on unsupported ASICs, set `amdgpu.dc=1`. - -To determine if DC is loaded, search dmesg for the following entry: - -``Display Core initialized with <version number here>`` - -AMDgpu Display Manager -====================== - -.. kernel-doc:: drivers/gpu/drm/amd/display/amdgpu_dm/amdgpu_dm.c - :doc: overview - -.. kernel-doc:: drivers/gpu/drm/amd/display/amdgpu_dm/amdgpu_dm.h - :internal: - -Lifecycle ---------- - -.. kernel-doc:: drivers/gpu/drm/amd/display/amdgpu_dm/amdgpu_dm.c - :doc: DM Lifecycle - -.. kernel-doc:: drivers/gpu/drm/amd/display/amdgpu_dm/amdgpu_dm.c - :functions: dm_hw_init dm_hw_fini - -Interrupts ----------- - -.. kernel-doc:: drivers/gpu/drm/amd/display/amdgpu_dm/amdgpu_dm_irq.c - :doc: overview - -.. kernel-doc:: drivers/gpu/drm/amd/display/amdgpu_dm/amdgpu_dm_irq.c - :internal: - -.. kernel-doc:: drivers/gpu/drm/amd/display/amdgpu_dm/amdgpu_dm.c - :functions: register_hpd_handlers dm_crtc_high_irq dm_pflip_high_irq - -Atomic Implementation ---------------------- - -.. kernel-doc:: drivers/gpu/drm/amd/display/amdgpu_dm/amdgpu_dm.c - :doc: atomic - -.. kernel-doc:: drivers/gpu/drm/amd/display/amdgpu_dm/amdgpu_dm.c - :functions: amdgpu_dm_atomic_check amdgpu_dm_atomic_commit_tail - -Display Core -============ - -**WIP** - -FreeSync Video --------------- - -.. kernel-doc:: drivers/gpu/drm/amd/display/amdgpu_dm/amdgpu_dm.c - :doc: FreeSync Video diff --git a/Documentation/gpu/amdgpu.rst b/Documentation/gpu/amdgpu.rst deleted file mode 100644 index 8ba72e898099..000000000000 --- a/Documentation/gpu/amdgpu.rst +++ /dev/null @@ -1,324 +0,0 @@ -========================= - drm/amdgpu AMDgpu driver -========================= - -The drm/amdgpu driver supports all AMD Radeon GPUs based on the Graphics Core -Next (GCN) architecture. - -Module Parameters -================= - -The amdgpu driver supports the following module parameters: - -.. kernel-doc:: drivers/gpu/drm/amd/amdgpu/amdgpu_drv.c - -Core Driver Infrastructure -========================== - -This section covers core driver infrastructure. - -.. _amdgpu_memory_domains: - -Memory Domains --------------- - -.. kernel-doc:: include/uapi/drm/amdgpu_drm.h - :doc: memory domains - -Buffer Objects --------------- - -.. kernel-doc:: drivers/gpu/drm/amd/amdgpu/amdgpu_object.c - :doc: amdgpu_object - -.. kernel-doc:: drivers/gpu/drm/amd/amdgpu/amdgpu_object.c - :internal: - -PRIME Buffer Sharing --------------------- - -.. kernel-doc:: drivers/gpu/drm/amd/amdgpu/amdgpu_dma_buf.c - :doc: PRIME Buffer Sharing - -.. kernel-doc:: drivers/gpu/drm/amd/amdgpu/amdgpu_dma_buf.c - :internal: - -MMU Notifier ------------- - -.. kernel-doc:: drivers/gpu/drm/amd/amdgpu/amdgpu_mn.c - :doc: MMU Notifier - -.. kernel-doc:: drivers/gpu/drm/amd/amdgpu/amdgpu_mn.c - :internal: - -AMDGPU Virtual Memory ---------------------- - -.. kernel-doc:: drivers/gpu/drm/amd/amdgpu/amdgpu_vm.c - :doc: GPUVM - -.. kernel-doc:: drivers/gpu/drm/amd/amdgpu/amdgpu_vm.c - :internal: - -Interrupt Handling ------------------- - -.. kernel-doc:: drivers/gpu/drm/amd/amdgpu/amdgpu_irq.c - :doc: Interrupt Handling - -.. kernel-doc:: drivers/gpu/drm/amd/amdgpu/amdgpu_irq.c - :internal: - -IP Blocks ------------------- - -.. kernel-doc:: drivers/gpu/drm/amd/include/amd_shared.h - :doc: IP Blocks - -.. kernel-doc:: drivers/gpu/drm/amd/include/amd_shared.h - :identifiers: amd_ip_block_type amd_ip_funcs - -AMDGPU XGMI Support -=================== - -.. kernel-doc:: drivers/gpu/drm/amd/amdgpu/amdgpu_xgmi.c - -AMDGPU RAS Support -================== - -The AMDGPU RAS interfaces are exposed via sysfs (for informational queries) and -debugfs (for error injection). - -RAS debugfs/sysfs Control and Error Injection Interfaces --------------------------------------------------------- - -.. kernel-doc:: drivers/gpu/drm/amd/amdgpu/amdgpu_ras.c - :doc: AMDGPU RAS debugfs control interface - -RAS Reboot Behavior for Unrecoverable Errors --------------------------------------------------------- - -.. kernel-doc:: drivers/gpu/drm/amd/amdgpu/amdgpu_ras.c - :doc: AMDGPU RAS Reboot Behavior for Unrecoverable Errors - -RAS Error Count sysfs Interface -------------------------------- - -.. kernel-doc:: drivers/gpu/drm/amd/amdgpu/amdgpu_ras.c - :doc: AMDGPU RAS sysfs Error Count Interface - -RAS EEPROM debugfs Interface ----------------------------- - -.. kernel-doc:: drivers/gpu/drm/amd/amdgpu/amdgpu_ras.c - :doc: AMDGPU RAS debugfs EEPROM table reset interface - -RAS VRAM Bad Pages sysfs Interface ----------------------------------- - -.. kernel-doc:: drivers/gpu/drm/amd/amdgpu/amdgpu_ras.c - :doc: AMDGPU RAS sysfs gpu_vram_bad_pages Interface - -Sample Code ------------ -Sample code for testing error injection can be found here: -https://cgit.freedesktop.org/mesa/drm/tree/tests/amdgpu/ras_tests.c - -This is part of the libdrm amdgpu unit tests which cover several areas of the GPU. -There are four sets of tests: - -RAS Basic Test - -The test verifies the RAS feature enabled status and makes sure the necessary sysfs and debugfs files -are present. - -RAS Query Test - -This test checks the RAS availability and enablement status for each supported IP block as well as -the error counts. - -RAS Inject Test - -This test injects errors for each IP. - -RAS Disable Test - -This test tests disabling of RAS features for each IP block. - - -GPU Power/Thermal Controls and Monitoring -========================================= - -This section covers hwmon and power/thermal controls. - -HWMON Interfaces ----------------- - -.. kernel-doc:: drivers/gpu/drm/amd/pm/amdgpu_pm.c - :doc: hwmon - -GPU sysfs Power State Interfaces --------------------------------- - -GPU power controls are exposed via sysfs files. - -power_dpm_state -~~~~~~~~~~~~~~~ - -.. kernel-doc:: drivers/gpu/drm/amd/pm/amdgpu_pm.c - :doc: power_dpm_state - -power_dpm_force_performance_level -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -.. kernel-doc:: drivers/gpu/drm/amd/pm/amdgpu_pm.c - :doc: power_dpm_force_performance_level - -pp_table -~~~~~~~~ - -.. kernel-doc:: drivers/gpu/drm/amd/pm/amdgpu_pm.c - :doc: pp_table - -pp_od_clk_voltage -~~~~~~~~~~~~~~~~~ - -.. kernel-doc:: drivers/gpu/drm/amd/pm/amdgpu_pm.c - :doc: pp_od_clk_voltage - -pp_dpm_* -~~~~~~~~ - -.. kernel-doc:: drivers/gpu/drm/amd/pm/amdgpu_pm.c - :doc: pp_dpm_sclk pp_dpm_mclk pp_dpm_socclk pp_dpm_fclk pp_dpm_dcefclk pp_dpm_pcie - -pp_power_profile_mode -~~~~~~~~~~~~~~~~~~~~~ - -.. kernel-doc:: drivers/gpu/drm/amd/pm/amdgpu_pm.c - :doc: pp_power_profile_mode - -\*_busy_percent -~~~~~~~~~~~~~~~ - -.. kernel-doc:: drivers/gpu/drm/amd/pm/amdgpu_pm.c - :doc: gpu_busy_percent - -.. kernel-doc:: drivers/gpu/drm/amd/pm/amdgpu_pm.c - :doc: mem_busy_percent - -gpu_metrics -~~~~~~~~~~~~~~~~~~~~~ - -.. kernel-doc:: drivers/gpu/drm/amd/pm/amdgpu_pm.c - :doc: gpu_metrics - -GPU Product Information -======================= - -Information about the GPU can be obtained on certain cards -via sysfs - -product_name ------------- - -.. kernel-doc:: drivers/gpu/drm/amd/amdgpu/amdgpu_device.c - :doc: product_name - -product_number --------------- - -.. kernel-doc:: drivers/gpu/drm/amd/amdgpu/amdgpu_device.c - :doc: product_name - -serial_number -------------- - -.. kernel-doc:: drivers/gpu/drm/amd/amdgpu/amdgpu_device.c - :doc: serial_number - -unique_id ---------- - -.. kernel-doc:: drivers/gpu/drm/amd/pm/amdgpu_pm.c - :doc: unique_id - -GPU Memory Usage Information -============================ - -Various memory accounting can be accessed via sysfs - -mem_info_vram_total -------------------- - -.. kernel-doc:: drivers/gpu/drm/amd/amdgpu/amdgpu_vram_mgr.c - :doc: mem_info_vram_total - -mem_info_vram_used ------------------- - -.. kernel-doc:: drivers/gpu/drm/amd/amdgpu/amdgpu_vram_mgr.c - :doc: mem_info_vram_used - -mem_info_vis_vram_total ------------------------ - -.. kernel-doc:: drivers/gpu/drm/amd/amdgpu/amdgpu_vram_mgr.c - :doc: mem_info_vis_vram_total - -mem_info_vis_vram_used ----------------------- - -.. kernel-doc:: drivers/gpu/drm/amd/amdgpu/amdgpu_vram_mgr.c - :doc: mem_info_vis_vram_used - -mem_info_gtt_total ------------------- - -.. kernel-doc:: drivers/gpu/drm/amd/amdgpu/amdgpu_gtt_mgr.c - :doc: mem_info_gtt_total - -mem_info_gtt_used ------------------ - -.. kernel-doc:: drivers/gpu/drm/amd/amdgpu/amdgpu_gtt_mgr.c - :doc: mem_info_gtt_used - -PCIe Accounting Information -=========================== - -pcie_bw -------- - -.. kernel-doc:: drivers/gpu/drm/amd/pm/amdgpu_pm.c - :doc: pcie_bw - -pcie_replay_count ------------------ - -.. kernel-doc:: drivers/gpu/drm/amd/amdgpu/amdgpu_device.c - :doc: pcie_replay_count - -GPU SmartShift Information -========================== - -GPU SmartShift information via sysfs - -smartshift_apu_power --------------------- - -.. kernel-doc:: drivers/gpu/drm/amd/pm/amdgpu_pm.c - :doc: smartshift_apu_power - -smartshift_dgpu_power ---------------------- - -.. kernel-doc:: drivers/gpu/drm/amd/pm/amdgpu_pm.c - :doc: smartshift_dgpu_power - -smartshift_bias ---------------- - -.. kernel-doc:: drivers/gpu/drm/amd/pm/amdgpu_pm.c - :doc: smartshift_bias diff --git a/Documentation/gpu/amdgpu/amdgpu-glossary.rst b/Documentation/gpu/amdgpu/amdgpu-glossary.rst new file mode 100644 index 000000000000..859dcec6c6f9 --- /dev/null +++ b/Documentation/gpu/amdgpu/amdgpu-glossary.rst @@ -0,0 +1,87 @@ +=============== +AMDGPU Glossary +=============== + +Here you can find some generic acronyms used in the amdgpu driver. Notice that +we have a dedicated glossary for Display Core at +'Documentation/gpu/amdgpu/display/dc-glossary.rst'. + +.. glossary:: + + CP + Command Processor + + CPLIB + Content Protection Library + + DFS + Digital Frequency Synthesizer + + ECP + Enhanced Content Protection + + EOP + End Of Pipe/Pipeline + + GC + Graphics and Compute + + GMC + Graphic Memory Controller + + IH + Interrupt Handler + + HQD + Hardware Queue Descriptor + + IB + Indirect Buffer + + IP + Intellectual Property blocks + + KCQ + Kernel Compute Queue + + KGQ + Kernel Graphics Queue + + KIQ + Kernel Interface Queue + + MEC + MicroEngine Compute + + MES + MicroEngine Scheduler + + MMHUB + Multi-Media HUB + + MQD + Memory Queue Descriptor + + PPLib + PowerPlay Library - PowerPlay is the power management component. + + PSP + Platform Security Processor + + RCL + RunList Controller + + SDMA + System DMA + + SMU + System Management Unit + + SS + Spread Spectrum + + VCE + Video Compression Engine + + VCN + Video Codec Next diff --git a/Documentation/gpu/amdgpu/display/config_example.svg b/Documentation/gpu/amdgpu/display/config_example.svg new file mode 100644 index 000000000000..cdac9858601c --- /dev/null +++ b/Documentation/gpu/amdgpu/display/config_example.svg @@ -0,0 +1,414 @@ +<?xml version="1.0" encoding="UTF-8" standalone="no"?> +<!-- Created with Inkscape (http://www.inkscape.org/) --> + +<svg + xmlns:dc="http://purl.org/dc/elements/1.1/" + xmlns:cc="http://creativecommons.org/ns#" + xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#" + xmlns:svg="http://www.w3.org/2000/svg" + xmlns="http://www.w3.org/2000/svg" + xmlns:sodipodi="http://sodipodi.sourceforge.net/DTD/sodipodi-0.dtd" + xmlns:inkscape="http://www.inkscape.org/namespaces/inkscape" + width="144.63406mm" + height="66.596054mm" + viewBox="0 0 144.15195 66.596054" + version="1.1" + id="svg8" + inkscape:version="0.92.5 (2060ec1f9f, 2020-04-08)" + sodipodi:docname="config_example.svg"> + <defs + id="defs2"> + <marker + inkscape:stockid="Arrow1Mend" + orient="auto" + refY="0" + refX="0" + id="Arrow1Mend" + style="overflow:visible" + inkscape:isstock="true"> + <path + id="path4547" + d="M 0,0 5,-5 -12.5,0 5,5 Z" + style="fill:#ff0000;fill-opacity:1;fill-rule:evenodd;stroke:#ff0000;stroke-width:1.00000003pt;stroke-opacity:1" + transform="matrix(-0.4,0,0,-0.4,-4,0)" + inkscape:connector-curvature="0" /> + </marker> + <marker + inkscape:stockid="Arrow1Mend" + orient="auto" + refY="0" + refX="0" + id="Arrow1Mend-3" + style="overflow:visible" + inkscape:isstock="true"> + <path + inkscape:connector-curvature="0" + id="path4547-6" + d="M 0,0 5,-5 -12.5,0 5,5 Z" + style="fill:#ff0000;fill-opacity:1;fill-rule:evenodd;stroke:#ff0000;stroke-width:1.00000003pt;stroke-opacity:1" + transform="matrix(-0.4,0,0,-0.4,-4,0)" /> + </marker> + <marker + inkscape:stockid="Arrow1Mend" + orient="auto" + refY="0" + refX="0" + id="Arrow1Mend-3-5" + style="overflow:visible" + inkscape:isstock="true"> + <path + inkscape:connector-curvature="0" + id="path4547-6-3" + d="M 0,0 5,-5 -12.5,0 5,5 Z" + style="fill:#ff0000;fill-opacity:1;fill-rule:evenodd;stroke:#ff0000;stroke-width:1.00000003pt;stroke-opacity:1" + transform="matrix(-0.4,0,0,-0.4,-4,0)" /> + </marker> + <marker + inkscape:stockid="Arrow1Mend" + orient="auto" + refY="0" + refX="0" + id="Arrow1Mend-3-5-0" + style="overflow:visible" + inkscape:isstock="true"> + <path + inkscape:connector-curvature="0" + id="path4547-6-3-6" + d="M 0,0 5,-5 -12.5,0 5,5 Z" + style="fill:#ff0000;fill-opacity:1;fill-rule:evenodd;stroke:#ff0000;stroke-width:1.00000003pt;stroke-opacity:1" + transform="matrix(-0.4,0,0,-0.4,-4,0)" /> + </marker> + <marker + inkscape:stockid="Arrow1Mend" + orient="auto" + refY="0" + refX="0" + id="Arrow1Mend-3-5-7" + style="overflow:visible" + inkscape:isstock="true"> + <path + inkscape:connector-curvature="0" + id="path4547-6-3-3" + d="M 0,0 5,-5 -12.5,0 5,5 Z" + style="fill:#ff0000;fill-opacity:1;fill-rule:evenodd;stroke:#ff0000;stroke-width:1.00000003pt;stroke-opacity:1" + transform="matrix(-0.4,0,0,-0.4,-4,0)" /> + </marker> + </defs> + <sodipodi:namedview + id="base" + pagecolor="#ffffff" + bordercolor="#666666" + borderopacity="1.0" + inkscape:pageopacity="0.0" + inkscape:pageshadow="2" + inkscape:zoom="0.98994949" + inkscape:cx="518.91791" + inkscape:cy="172.50112" + inkscape:document-units="mm" + inkscape:current-layer="layer1" + showgrid="true" + viewbox-width="209.3" + inkscape:window-width="3840" + inkscape:window-height="1136" + inkscape:window-x="0" + inkscape:window-y="27" + inkscape:window-maximized="1" + fit-margin-top="0" + fit-margin-left="0" + fit-margin-right="0" + fit-margin-bottom="0"> + <inkscape:grid + type="xygrid" + id="grid817" + originx="4.390216" + originy="-208.88856" /> + </sodipodi:namedview> + <metadata + id="metadata5"> + <rdf:RDF> + <cc:Work + rdf:about=""> + <dc:format>image/svg+xml</dc:format> + <dc:type + rdf:resource="http://purl.org/dc/dcmitype/StillImage" /> + <dc:title></dc:title> + </cc:Work> + </rdf:RDF> + </metadata> + <g + inkscape:label="Layer 1" + inkscape:groupmode="layer" + id="layer1" + transform="translate(4.4048992,-21.515392)"> + <path + style="fill:none;stroke:#000000;stroke-width:0.26458335px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1" + d="m 20.816662,35.062492 h 23.8125 v -5.291667 h 5.291667 v 5.291667 h 10.583334 v -5.291667 h 5.291667 v 5.291667 h 2.645833 v -5.291667 h 5.291667 v 5.291667 h 66.14583" + id="path4522" + inkscape:connector-curvature="0" /> + <path + style="fill:none;stroke:#000000;stroke-width:0.26458335px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1" + d="m 20.816662,48.291659 h 7.9375 v -5.291667 h 5.291667 v 5.291667 h 58.208335 v -5.291667 h 5.291666 v 5.291667 h 42.33333" + id="path4524" + inkscape:connector-curvature="0" /> + <path + style="fill:none;stroke:#000000;stroke-width:0.26458335px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1" + d="m 20.816662,61.520826 h 26.458334 v -5.291667 h 44.979168 v 5.291667 h 47.624996" + id="path4526" + inkscape:connector-curvature="0" /> + <path + style="fill:none;stroke:#000000;stroke-width:0.26458335px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1" + d="M 20.816662,72.104159 H 139.87916" + id="path4528" + inkscape:connector-curvature="0" /> + <path + style="fill:none;stroke:#000000;stroke-width:0.26458335px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1" + d="M 20.816662,77.395826 H 139.87916" + id="path4530" + inkscape:connector-curvature="0" /> + <path + style="fill:none;stroke:#000000;stroke-width:0.26458335px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1" + d="M 20.816662,82.687493 H 139.87916" + id="path4532" + inkscape:connector-curvature="0" /> + <path + style="fill:none;stroke:#000000;stroke-width:0.26458335px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1" + d="M 20.816662,87.97916 H 139.87916" + id="path4534" + inkscape:connector-curvature="0" /> + <path + style="fill:none;stroke:#ff0000;stroke-width:0.5291667;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:0.52916668, 0.52916668;stroke-dashoffset:0;stroke-opacity:1;marker-end:url(#Arrow1Mend)" + d="m 47.274996,29.770826 c 3.836215,14.933158 3.472151,27.586643 0.264583,41.010418" + id="path4536" + inkscape:connector-curvature="0" + sodipodi:nodetypes="cc" /> + <path + style="fill:none;stroke:#ff0000;stroke-width:0.5291667;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:0.52916669, 0.52916669;stroke-dashoffset:0;stroke-opacity:1;marker-end:url(#Arrow1Mend-3)" + d="m 63.149996,29.770826 c 3.836214,14.933158 5.059652,27.586642 1.852084,41.010418" + id="path4536-7" + inkscape:connector-curvature="0" + sodipodi:nodetypes="cc" /> + <path + style="fill:none;stroke:#ff0000;stroke-width:0.5291667;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:0.5291667, 0.5291667;stroke-dashoffset:0;stroke-opacity:1;marker-end:url(#Arrow1Mend-3-5)" + d="m 71.087496,29.770825 c 3.836214,14.933158 5.059652,27.586643 1.852084,41.010419" + id="path4536-7-5" + inkscape:connector-curvature="0" + sodipodi:nodetypes="cc" /> + <text + xml:space="preserve" + style="font-style:normal;font-weight:normal;font-size:10.58333397px;line-height:1.25;font-family:sans-serif;letter-spacing:0px;word-spacing:0px;fill:#000000;fill-opacity:1;stroke:none;stroke-width:0.26458335" + x="59.359009" + y="24.195677" + id="text6572"><tspan + sodipodi:role="line" + x="59.359009" + y="24.195677" + style="font-size:3.52777791px;line-height:5.39999962;text-align:center;text-anchor:middle;stroke-width:0.26458335" + id="tspan6574">Configurations</tspan></text> + <text + xml:space="preserve" + style="font-style:normal;font-weight:normal;font-size:10.58333397px;line-height:1.25;font-family:sans-serif;letter-spacing:0px;word-spacing:0px;fill:#000000;fill-opacity:1;stroke:none;stroke-width:0.26458335" + x="46.825508" + y="28.542402" + id="text6572-6"><tspan + sodipodi:role="line" + x="46.825508" + y="28.542402" + style="font-size:3.52777815px;line-height:5.39999962;text-align:center;text-anchor:middle;fill:#008000;stroke-width:0.26458335" + id="tspan6574-2">A</tspan></text> + <text + xml:space="preserve" + style="font-style:normal;font-weight:normal;font-size:10.58333397px;line-height:1.25;font-family:sans-serif;letter-spacing:0px;word-spacing:0px;fill:#000000;fill-opacity:1;stroke:none;stroke-width:0.26458335" + x="62.8895" + y="28.825886" + id="text6572-6-2"><tspan + sodipodi:role="line" + x="62.8895" + y="28.825886" + style="font-size:3.52777839px;line-height:5.39999962;text-align:center;text-anchor:middle;fill:#0000ff;stroke-width:0.26458335" + id="tspan6574-2-7">B</tspan></text> + <text + xml:space="preserve" + style="font-style:normal;font-weight:normal;font-size:10.58333397px;line-height:1.25;font-family:sans-serif;letter-spacing:0px;word-spacing:0px;fill:#000000;fill-opacity:1;stroke:none;stroke-width:0.26458335" + x="70.827003" + y="29.109362" + id="text6572-6-2-3"><tspan + sodipodi:role="line" + x="70.827003" + y="29.109362" + style="font-size:3.52777863px;line-height:5.39999962;text-align:center;text-anchor:middle;fill:#c87137;stroke-width:0.26458335" + id="tspan6574-2-7-6">C</tspan></text> + <path + style="fill:none;stroke:#ff0000;stroke-width:0.5291667;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:0.52916671, 0.52916671;stroke-dashoffset:0;stroke-opacity:1;marker-end:url(#Arrow1Mend-3-5-0)" + d="m 92.254164,42.999993 c 9.142136,12.745655 4.411987,28.608461 0.529167,38.364584" + id="path4536-7-5-2" + inkscape:connector-curvature="0" + sodipodi:nodetypes="cc" /> + <path + style="fill:none;stroke:#000000;stroke-width:0.5291667;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:none;stroke-opacity:1" + d="m 47.274996,72.104159 v 5.291667" + id="path8053" + inkscape:connector-curvature="0" /> + <path + style="fill:none;stroke:#000000;stroke-width:0.5291667;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:none;stroke-opacity:1" + d="m 64.472913,72.10416 v 5.291667" + id="path8053-6" + inkscape:connector-curvature="0" /> + <path + style="fill:none;stroke:#000000;stroke-width:0.5291667;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:none;stroke-opacity:1" + d="m 72.410413,72.10416 v 5.291667" + id="path8053-6-1" + inkscape:connector-curvature="0" /> + <path + style="fill:none;stroke:#000000;stroke-width:0.5291667;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:none;stroke-opacity:1" + d="m 92.254164,82.687494 v 5.291667" + id="path8053-6-1-8" + inkscape:connector-curvature="0" /> + <text + xml:space="preserve" + style="font-style:normal;font-weight:normal;font-size:10.58333397px;line-height:1.25;font-family:sans-serif;letter-spacing:0px;word-spacing:0px;fill:#000000;fill-opacity:1;stroke:none;stroke-width:0.26458335" + x="55.802444" + y="76.167412" + id="text6572-6-7"><tspan + sodipodi:role="line" + x="55.802444" + y="76.167412" + style="font-size:3.52777839px;line-height:5.39999962;text-align:center;text-anchor:middle;fill:#008000;stroke-width:0.26458335" + id="tspan6574-2-9">A</tspan></text> + <text + xml:space="preserve" + style="font-style:normal;font-weight:normal;font-size:10.58333397px;line-height:1.25;font-family:sans-serif;letter-spacing:0px;word-spacing:0px;fill:#000000;fill-opacity:1;stroke:none;stroke-width:0.26458335" + x="68.559143" + y="75.883926" + id="text6572-6-2-2"><tspan + sodipodi:role="line" + x="68.559143" + y="75.883926" + style="font-size:3.52777863px;line-height:5.39999962;text-align:center;text-anchor:middle;fill:#0000ff;stroke-width:0.26458335" + id="tspan6574-2-7-0">B</tspan></text> + <text + xml:space="preserve" + style="font-style:normal;font-weight:normal;font-size:10.58333397px;line-height:1.25;font-family:sans-serif;letter-spacing:0px;word-spacing:0px;fill:#000000;fill-opacity:1;stroke:none;stroke-width:0.26458335" + x="84.812119" + y="75.883911" + id="text6572-6-2-3-2"><tspan + sodipodi:role="line" + x="84.812119" + y="75.883911" + style="font-size:3.52777863px;line-height:5.39999962;text-align:center;text-anchor:middle;fill:#c87137;stroke-width:0.26458335" + id="tspan6574-2-7-6-3">C</tspan></text> + <text + xml:space="preserve" + style="font-style:normal;font-weight:normal;font-size:10.58333397px;line-height:1.25;font-family:sans-serif;letter-spacing:0px;word-spacing:0px;fill:#000000;fill-opacity:1;stroke:none;stroke-width:0.26458335" + x="98.513756" + y="86.845222" + id="text6572-6-2-3-2-7"><tspan + sodipodi:role="line" + x="98.513756" + y="86.845222" + style="font-size:3.52777863px;line-height:5.39999962;text-align:center;text-anchor:middle;fill:#c87137;stroke-width:0.26458335" + id="tspan6574-2-7-6-3-5">C</tspan></text> + <text + xml:space="preserve" + style="font-style:normal;font-weight:normal;font-size:10.58333397px;line-height:1.25;font-family:sans-serif;letter-spacing:0px;word-spacing:0px;fill:#000000;fill-opacity:1;stroke:none;stroke-width:0.26458335" + x="35.452015" + y="75.694931" + id="text6572-9"><tspan + sodipodi:role="line" + x="35.452015" + y="75.694931" + style="font-size:3.52777815px;line-height:5.39999962;text-align:center;text-anchor:middle;stroke-width:0.26458335" + id="tspan6574-22">Old config</tspan></text> + <text + xml:space="preserve" + style="font-style:normal;font-weight:normal;font-size:10.58333397px;line-height:1.25;font-family:sans-serif;letter-spacing:0px;word-spacing:0px;fill:#000000;fill-opacity:1;stroke:none;stroke-width:0.26458335" + x="55.484753" + y="86.656235" + id="text6572-9-8"><tspan + sodipodi:role="line" + x="55.484753" + y="86.656235" + style="font-size:3.52777839px;line-height:5.39999962;text-align:center;text-anchor:middle;stroke-width:0.26458335" + id="tspan6574-22-9">Old config</tspan></text> + <path + style="fill:none;stroke:#ff0000;stroke-width:0.5291667;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:0.52916671, 0.52916671;stroke-dashoffset:0;stroke-opacity:1;marker-end:url(#Arrow1Mend-3-5-7)" + d="m 92.254164,42.999993 c 4.233333,4.7625 2.645833,13.229167 0.79375,17.197917" + inkscape:connector-curvature="0" + sodipodi:nodetypes="cc" /> + <text + xml:space="preserve" + style="font-style:normal;font-weight:normal;font-size:10.58333397px;line-height:1.25;font-family:sans-serif;letter-spacing:0px;word-spacing:0px;fill:#000000;fill-opacity:1;stroke:none;stroke-width:0.26458335" + x="3.7020128" + y="33.550579" + id="text6572-1"><tspan + sodipodi:role="line" + x="3.7020128" + y="42.914349" + style="font-size:3.52777815px;line-height:5.39999962;text-align:center;text-anchor:middle;stroke-width:0.26458335" + id="tspan15310" /></text> + <text + xml:space="preserve" + style="font-style:normal;font-weight:normal;font-size:3.17500019px;line-height:1.25;font-family:sans-serif;letter-spacing:0px;word-spacing:0px;fill:#000000;fill-opacity:1;stroke:none;stroke-width:0.26458335" + x="13.366468" + y="46.590767" + id="text15316"><tspan + sodipodi:role="line" + x="13.366468" + y="46.590767" + style="text-align:center;text-anchor:middle;stroke-width:0.26458335" + id="tspan15318">VUpdate</tspan></text> + <text + xml:space="preserve" + style="font-style:normal;font-weight:normal;font-size:3.17500043px;line-height:1.25;font-family:sans-serif;letter-spacing:0px;word-spacing:0px;fill:#000000;fill-opacity:1;stroke:none;stroke-width:0.26458335" + x="14.45245" + y="29.676321" + id="text15316-3"><tspan + sodipodi:role="line" + id="tspan15314-1" + x="14.45245" + y="29.676321" + style="text-align:center;text-anchor:middle;stroke-width:0.26458335">Update</tspan><tspan + sodipodi:role="line" + x="14.45245" + y="33.645073" + style="text-align:center;text-anchor:middle;stroke-width:0.26458335" + id="tspan15318-9">Lock</tspan></text> + <text + xml:space="preserve" + style="font-style:normal;font-weight:normal;font-size:3.17500043px;line-height:1.25;font-family:sans-serif;letter-spacing:0px;word-spacing:0px;fill:#000000;fill-opacity:1;stroke:none;stroke-width:0.26458335" + x="7.5676007" + y="56.985115" + id="text15316-4"><tspan + sodipodi:role="line" + x="7.5676007" + y="56.985115" + style="text-align:center;text-anchor:middle;stroke-width:0.26458335" + id="tspan15318-7">Register update</tspan><tspan + sodipodi:role="line" + x="7.5676007" + y="60.953865" + style="text-align:center;text-anchor:middle;stroke-width:0.26458335" + id="tspan15361">Pending Status</tspan></text> + <text + xml:space="preserve" + style="font-style:normal;font-weight:normal;font-size:3.17500043px;line-height:1.25;font-family:sans-serif;letter-spacing:0px;word-spacing:0px;fill:#000000;fill-opacity:1;stroke:none;stroke-width:0.26458335" + x="16.074829" + y="76.167404" + id="text15316-8"><tspan + sodipodi:role="line" + x="16.074829" + y="76.167404" + style="text-align:center;text-anchor:middle;stroke-width:0.26458335" + id="tspan15318-4">Buf 0</tspan></text> + <text + xml:space="preserve" + style="font-style:normal;font-weight:normal;font-size:3.17500067px;line-height:1.25;font-family:sans-serif;letter-spacing:0px;word-spacing:0px;fill:#000000;fill-opacity:1;stroke:none;stroke-width:0.26458335" + x="16.156994" + y="86.089279" + id="text15316-8-5"><tspan + sodipodi:role="line" + x="16.156994" + y="86.089279" + style="text-align:center;text-anchor:middle;stroke-width:0.26458335" + id="tspan15318-4-0">Buf 1</tspan></text> + </g> +</svg> diff --git a/Documentation/gpu/amdgpu/display/dc-debug.rst b/Documentation/gpu/amdgpu/display/dc-debug.rst new file mode 100644 index 000000000000..40c55a618918 --- /dev/null +++ b/Documentation/gpu/amdgpu/display/dc-debug.rst @@ -0,0 +1,77 @@ +======================== +Display Core Debug tools +======================== + +DC Visual Confirmation +====================== + +Display core provides a feature named visual confirmation, which is a set of +bars added at the scanout time by the driver to convey some specific +information. In general, you can enable this debug option by using:: + + echo <N> > /sys/kernel/debug/dri/0/amdgpu_dm_visual_confirm + +Where `N` is an integer number for some specific scenarios that the developer +wants to enable, you will see some of these debug cases in the following +subsection. + +Multiple Planes Debug +--------------------- + +If you want to enable or debug multiple planes in a specific user-space +application, you can leverage a debug feature named visual confirm. For +enabling it, you will need:: + + echo 1 > /sys/kernel/debug/dri/0/amdgpu_dm_visual_confirm + +You need to reload your GUI to see the visual confirmation. When the plane +configuration changes or a full update occurs there will be a colored bar at +the bottom of each hardware plane being drawn on the screen. + +* The color indicates the format - For example, red is AR24 and green is NV12 +* The height of the bar indicates the index of the plane +* Pipe split can be observed if there are two bars with a difference in height + covering the same plane + +Consider the video playback case in which a video is played in a specific +plane, and the desktop is drawn in another plane. The video plane should +feature one or two green bars at the bottom of the video depending on pipe +split configuration. + +* There should **not** be any visual corruption +* There should **not** be any underflow or screen flashes +* There should **not** be any black screens +* There should **not** be any cursor corruption +* Multiple plane **may** be briefly disabled during window transitions or + resizing but should come back after the action has finished + +Pipe Split Debug +---------------- + +Sometimes we need to debug if DCN is splitting pipes correctly, and visual +confirmation is also handy for this case. Similar to the MPO case, you can use +the below command to enable visual confirmation:: + + echo 1 > /sys/kernel/debug/dri/0/amdgpu_dm_visual_confirm + +In this case, if you have a pipe split, you will see one small red bar at the +bottom of the display covering the entire display width and another bar +covering the second pipe. In other words, you will see a bit high bar in the +second pipe. + +DTN Debug +========= + +DC (DCN) provides an extensive log that dumps multiple details from our +hardware configuration. Via debugfs, you can capture those status values by +using Display Test Next (DTN) log, which can be captured via debugfs by using:: + + cat /sys/kernel/debug/dri/0/amdgpu_dm_dtn_log + +Since this log is updated accordingly with DCN status, you can also follow the +change in real-time by using something like:: + + sudo watch -d cat /sys/kernel/debug/dri/0/amdgpu_dm_dtn_log + +When reporting a bug related to DC, consider attaching this log before and +after you reproduce the bug. diff --git a/Documentation/gpu/amdgpu/display/dc-glossary.rst b/Documentation/gpu/amdgpu/display/dc-glossary.rst new file mode 100644 index 000000000000..116f5f0942fd --- /dev/null +++ b/Documentation/gpu/amdgpu/display/dc-glossary.rst @@ -0,0 +1,237 @@ +=========== +DC Glossary +=========== + +On this page, we try to keep track of acronyms related to the display +component. If you do not find what you are looking for, look at the +'Documentation/gpu/amdgpu/amdgpu-glossary.rst'; if you cannot find it anywhere, +consider asking in the amdgfx and update this page. + +.. glossary:: + + ABM + Adaptive Backlight Modulation + + APU + Accelerated Processing Unit + + ASIC + Application-Specific Integrated Circuit + + ASSR + Alternate Scrambler Seed Reset + + AZ + Azalia (HD audio DMA engine) + + BPC + Bits Per Colour/Component + + BPP + Bits Per Pixel + + Clocks + * PCLK: Pixel Clock + * SYMCLK: Symbol Clock + * SOCCLK: GPU Engine Clock + * DISPCLK: Display Clock + * DPPCLK: DPP Clock + * DCFCLK: Display Controller Fabric Clock + * REFCLK: Real Time Reference Clock + * PPLL: Pixel PLL + * FCLK: Fabric Clock + * MCLK: Memory Clock + + CRC + Cyclic Redundancy Check + + CRTC + Cathode Ray Tube Controller - commonly called "Controller" - Generates + raw stream of pixels, clocked at pixel clock + + CVT + Coordinated Video Timings + + DAL + Display Abstraction layer + + DC (Software) + Display Core + + DC (Hardware) + Display Controller + + DCC + Delta Colour Compression + + DCE + Display Controller Engine + + DCHUB + Display Controller HUB + + ARB + Arbiter + + VTG + Vertical Timing Generator + + DCN + Display Core Next + + DCCG + Display Clock Generator block + + DDC + Display Data Channel + + DIO + Display IO + + DPP + Display Pipes and Planes + + DSC + Display Stream Compression (Reduce the amount of bits to represent pixel + count while at the same pixel clock) + + dGPU + discrete GPU + + DMIF + Display Memory Interface + + DML + Display Mode Library + + DMCU + Display Micro-Controller Unit + + DMCUB + Display Micro-Controller Unit, version B + + DPCD + DisplayPort Configuration Data + + DPM(S) + Display Power Management (Signaling) + + DRR + Dynamic Refresh Rate + + DWB + Display Writeback + + FB + Frame Buffer + + FBC + Frame Buffer Compression + + FEC + Forward Error Correction + + FRL + Fixed Rate Link + + GCO + Graphical Controller Object + + GSL + Global Swap Lock + + iGPU + integrated GPU + + ISR + Interrupt Service Request + + ISV + Independent Software Vendor + + KMD + Kernel Mode Driver + + LB + Line Buffer + + LFC + Low Framerate Compensation + + LTTPR + Link Training Tunable Phy Repeater + + LUT + Lookup Table + + MALL + Memory Access at Last Level + + MC + Memory Controller + + MPC + Multiple pipes and plane combine + + MPO + Multi Plane Overlay + + MST + Multi Stream Transport + + NBP State + Northbridge Power State + + NBIO + North Bridge Input/Output + + ODM + Output Data Mapping + + OPM + Output Protection Manager + + OPP + Output Plane Processor + + OPTC + Output Pipe Timing Combiner + + OTG + Output Timing Generator + + PCON + Power Controller + + PGFSM + Power Gate Finite State Machine + + PSR + Panel Self Refresh + + SCL + Scaler + + SDP + Scalable Data Port + + SLS + Single Large Surface + + SST + Single Stream Transport + + TMDS + Transition-Minimized Differential Signaling + + TMZ + Trusted Memory Zone + + TTU + Time to Underflow + + VRR + Variable Refresh Rate + + UVD + Unified Video Decoder diff --git a/Documentation/gpu/amdgpu/display/dc_pipeline_overview.svg b/Documentation/gpu/amdgpu/display/dc_pipeline_overview.svg new file mode 100644 index 000000000000..9adecebfe65b --- /dev/null +++ b/Documentation/gpu/amdgpu/display/dc_pipeline_overview.svg @@ -0,0 +1,1125 @@ +<?xml version="1.0" encoding="UTF-8" standalone="no"?> +<!-- Created with Inkscape (http://www.inkscape.org/) --> + +<svg + xmlns:dc="http://purl.org/dc/elements/1.1/" + xmlns:cc="http://creativecommons.org/ns#" + xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#" + xmlns:svg="http://www.w3.org/2000/svg" + xmlns="http://www.w3.org/2000/svg" + xmlns:sodipodi="http://sodipodi.sourceforge.net/DTD/sodipodi-0.dtd" + xmlns:inkscape="http://www.inkscape.org/namespaces/inkscape" + width="1296.7491" + height="741.97845" + viewBox="0 0 343.0982 196.31514" + version="1.1" + id="svg8" + inkscape:version="0.92.5 (2060ec1f9f, 2020-04-08)" + sodipodi:docname="dc_pipeline_overview.svg"> + <defs + id="defs2"> + <marker + inkscape:stockid="Arrow2Mend" + orient="auto" + refY="0" + refX="0" + id="marker8858" + style="overflow:visible" + inkscape:isstock="true"> + <path + id="path8616" + style="fill:#aa00d4;fill-opacity:1;fill-rule:evenodd;stroke:#aa00d4;stroke-width:0.625;stroke-linejoin:round;stroke-opacity:1" + d="M 8.7185878,4.0337352 -2.2072895,0.01601326 8.7185884,-4.0017078 c -1.7454984,2.3720609 -1.7354408,5.6174519 -6e-7,8.035443 z" + transform="scale(-0.6)" + inkscape:connector-curvature="0" /> + </marker> + <marker + inkscape:stockid="Arrow2Send" + orient="auto" + refY="0" + refX="0" + id="Arrow2Send" + style="overflow:visible" + inkscape:isstock="true"> + <path + id="path8622" + style="fill:#ff0000;fill-opacity:1;fill-rule:evenodd;stroke:#ff0000;stroke-width:0.625;stroke-linejoin:round;stroke-opacity:1" + d="M 8.7185878,4.0337352 -2.2072895,0.01601326 8.7185884,-4.0017078 c -1.7454984,2.3720609 -1.7354408,5.6174519 -6e-7,8.035443 z" + transform="matrix(-0.3,0,0,-0.3,0.69,0)" + inkscape:connector-curvature="0" /> + </marker> + <marker + inkscape:stockid="Arrow1Lend" + orient="auto" + refY="0" + refX="0" + id="Arrow1Lend" + style="overflow:visible" + inkscape:isstock="true"> + <path + id="path8592" + d="M 0,0 5,-5 -12.5,0 5,5 Z" + style="fill:#ff0000;fill-opacity:1;fill-rule:evenodd;stroke:#ff0000;stroke-width:1.00000003pt;stroke-opacity:1" + transform="matrix(-0.8,0,0,-0.8,-10,0)" + inkscape:connector-curvature="0" /> + </marker> + <marker + inkscape:stockid="Arrow2Lend" + orient="auto" + refY="0" + refX="0" + id="Arrow2Lend" + style="overflow:visible" + inkscape:isstock="true"> + <path + id="path8610" + style="fill:#ff0000;fill-opacity:1;fill-rule:evenodd;stroke:#ff0000;stroke-width:0.625;stroke-linejoin:round;stroke-opacity:1" + d="M 8.7185878,4.0337352 -2.2072895,0.01601326 8.7185884,-4.0017078 c -1.7454984,2.3720609 -1.7354408,5.6174519 -6e-7,8.035443 z" + transform="matrix(-1.1,0,0,-1.1,-1.1,0)" + inkscape:connector-curvature="0" /> + </marker> + <marker + inkscape:stockid="Arrow2Mend" + orient="auto" + refY="0" + refX="0" + id="Arrow2Mend" + style="overflow:visible" + inkscape:isstock="true"> + <path + id="path1200" + style="fill:#ff0000;fill-opacity:1;fill-rule:evenodd;stroke:#ff0000;stroke-width:0.625;stroke-linejoin:round;stroke-opacity:1" + d="M 8.7185878,4.0337352 -2.2072895,0.01601326 8.7185884,-4.0017078 c -1.7454984,2.3720609 -1.7354408,5.6174519 -6e-7,8.035443 z" + transform="scale(-0.6)" + inkscape:connector-curvature="0" /> + </marker> + <marker + inkscape:stockid="Arrow2Mend" + orient="auto" + refY="0" + refX="0" + id="Arrow2Mend-8" + style="overflow:visible" + inkscape:isstock="true"> + <path + inkscape:connector-curvature="0" + id="path1200-9" + style="fill:#ff0000;fill-opacity:1;fill-rule:evenodd;stroke:#ff0000;stroke-width:0.625;stroke-linejoin:round;stroke-opacity:1" + d="M 8.7185878,4.0337352 -2.2072895,0.01601326 8.7185884,-4.0017078 c -1.7454984,2.3720609 -1.7354408,5.6174519 -6e-7,8.035443 z" + transform="scale(-0.6)" /> + </marker> + <marker + inkscape:stockid="Arrow2Mend" + orient="auto" + refY="0" + refX="0" + id="Arrow2Mend-8-3" + style="overflow:visible" + inkscape:isstock="true"> + <path + inkscape:connector-curvature="0" + id="path1200-9-6" + style="fill:#ff0000;fill-opacity:1;fill-rule:evenodd;stroke:#ff0000;stroke-width:0.625;stroke-linejoin:round;stroke-opacity:1" + d="M 8.7185878,4.0337352 -2.2072895,0.01601326 8.7185884,-4.0017078 c -1.7454984,2.3720609 -1.7354408,5.6174519 -6e-7,8.035443 z" + transform="scale(-0.6)" /> + </marker> + <marker + inkscape:stockid="Arrow2Mend" + orient="auto" + refY="0" + refX="0" + id="Arrow2Mend-8-3-2" + style="overflow:visible" + inkscape:isstock="true"> + <path + inkscape:connector-curvature="0" + id="path1200-9-6-9" + style="fill:#ff0000;fill-opacity:1;fill-rule:evenodd;stroke:#ff0000;stroke-width:0.625;stroke-linejoin:round;stroke-opacity:1" + d="M 8.7185878,4.0337352 -2.2072895,0.01601326 8.7185884,-4.0017078 c -1.7454984,2.3720609 -1.7354408,5.6174519 -6e-7,8.035443 z" + transform="scale(-0.6)" /> + </marker> + <marker + inkscape:stockid="Arrow2Mend" + orient="auto" + refY="0" + refX="0" + id="Arrow2Mend-8-3-2-1" + style="overflow:visible" + inkscape:isstock="true"> + <path + inkscape:connector-curvature="0" + id="path1200-9-6-9-9" + style="fill:#ff0000;fill-opacity:1;fill-rule:evenodd;stroke:#ff0000;stroke-width:0.625;stroke-linejoin:round;stroke-opacity:1" + d="M 8.7185878,4.0337352 -2.2072895,0.01601326 8.7185884,-4.0017078 c -1.7454984,2.3720609 -1.7354408,5.6174519 -6e-7,8.035443 z" + transform="scale(-0.6)" /> + </marker> + <marker + inkscape:stockid="Arrow2Mend" + orient="auto" + refY="0" + refX="0" + id="Arrow2Mend-8-3-2-7" + style="overflow:visible" + inkscape:isstock="true"> + <path + inkscape:connector-curvature="0" + id="path1200-9-6-9-8" + style="fill:#008000;fill-opacity:1;fill-rule:evenodd;stroke:#008000;stroke-width:0.625;stroke-linejoin:round;stroke-opacity:1" + d="M 8.7185878,4.0337352 -2.2072895,0.01601326 8.7185884,-4.0017078 c -1.7454984,2.3720609 -1.7354408,5.6174519 -6e-7,8.035443 z" + transform="scale(-0.6)" /> + </marker> + <marker + inkscape:stockid="Arrow2Mend" + orient="auto" + refY="0" + refX="0" + id="Arrow2Mend-8-3-4" + style="overflow:visible" + inkscape:isstock="true"> + <path + inkscape:connector-curvature="0" + id="path1200-9-6-5" + style="fill:#008000;fill-opacity:1;fill-rule:evenodd;stroke:#008000;stroke-width:0.625;stroke-linejoin:round;stroke-opacity:1" + d="M 8.7185878,4.0337352 -2.2072895,0.01601326 8.7185884,-4.0017078 c -1.7454984,2.3720609 -1.7354408,5.6174519 -6e-7,8.035443 z" + transform="scale(-0.6)" /> + </marker> + <marker + inkscape:stockid="Arrow2Mend" + orient="auto" + refY="0" + refX="0" + id="Arrow2Mend-8-0" + style="overflow:visible" + inkscape:isstock="true"> + <path + inkscape:connector-curvature="0" + id="path1200-9-3" + style="fill:#008000;fill-opacity:1;fill-rule:evenodd;stroke:#008000;stroke-width:0.625;stroke-linejoin:round;stroke-opacity:1" + d="M 8.7185878,4.0337352 -2.2072895,0.01601326 8.7185884,-4.0017078 c -1.7454984,2.3720609 -1.7354408,5.6174519 -6e-7,8.035443 z" + transform="scale(-0.6)" /> + </marker> + <marker + inkscape:stockid="Arrow2Mend" + orient="auto" + refY="0" + refX="0" + id="Arrow2Mend-6" + style="overflow:visible" + inkscape:isstock="true"> + <path + inkscape:connector-curvature="0" + id="path1200-1" + style="fill:#008000;fill-opacity:1;fill-rule:evenodd;stroke:#008000;stroke-width:0.625;stroke-linejoin:round;stroke-opacity:1" + d="M 8.7185878,4.0337352 -2.2072895,0.01601326 8.7185884,-4.0017078 c -1.7454984,2.3720609 -1.7354408,5.6174519 -6e-7,8.035443 z" + transform="scale(-0.6)" /> + </marker> + <marker + inkscape:stockid="Arrow2Mend" + orient="auto" + refY="0" + refX="0" + id="Arrow2Mend-8-3-2-6" + style="overflow:visible" + inkscape:isstock="true"> + <path + inkscape:connector-curvature="0" + id="path1200-9-6-9-1" + style="fill:#ff0000;fill-opacity:1;fill-rule:evenodd;stroke:#ff0000;stroke-width:0.625;stroke-linejoin:round;stroke-opacity:1" + d="M 8.7185878,4.0337352 -2.2072895,0.01601326 8.7185884,-4.0017078 c -1.7454984,2.3720609 -1.7354408,5.6174519 -6e-7,8.035443 z" + transform="scale(-0.6)" /> + </marker> + <marker + inkscape:stockid="Arrow2Mend" + orient="auto" + refY="0" + refX="0" + id="Arrow2Mend-8-0-7" + style="overflow:visible" + inkscape:isstock="true"> + <path + inkscape:connector-curvature="0" + id="path1200-9-3-4" + style="fill:#008000;fill-opacity:1;fill-rule:evenodd;stroke:#008000;stroke-width:0.625;stroke-linejoin:round;stroke-opacity:1" + d="M 8.7185878,4.0337352 -2.2072895,0.01601326 8.7185884,-4.0017078 c -1.7454984,2.3720609 -1.7354408,5.6174519 -6e-7,8.035443 z" + transform="scale(-0.6)" /> + </marker> + <marker + inkscape:stockid="Arrow2Mend" + orient="auto" + refY="0" + refX="0" + id="Arrow2Mend-6-3" + style="overflow:visible" + inkscape:isstock="true"> + <path + inkscape:connector-curvature="0" + id="path1200-1-0" + style="fill:#008000;fill-opacity:1;fill-rule:evenodd;stroke:#008000;stroke-width:0.625;stroke-linejoin:round;stroke-opacity:1" + d="M 8.7185878,4.0337352 -2.2072895,0.01601326 8.7185884,-4.0017078 c -1.7454984,2.3720609 -1.7354408,5.6174519 -6e-7,8.035443 z" + transform="scale(-0.6)" /> + </marker> + <marker + inkscape:stockid="Arrow2Mend" + orient="auto" + refY="0" + refX="0" + id="Arrow2Mend-8-3-2-8" + style="overflow:visible" + inkscape:isstock="true"> + <path + inkscape:connector-curvature="0" + id="path1200-9-6-9-6" + style="fill:#ff0000;fill-opacity:1;fill-rule:evenodd;stroke:#ff0000;stroke-width:0.625;stroke-linejoin:round;stroke-opacity:1" + d="M 8.7185878,4.0337352 -2.2072895,0.01601326 8.7185884,-4.0017078 c -1.7454984,2.3720609 -1.7354408,5.6174519 -6e-7,8.035443 z" + transform="scale(-0.6)" /> + </marker> + <marker + inkscape:stockid="Arrow2Mend" + orient="auto" + refY="0" + refX="0" + id="Arrow2Mend-3" + style="overflow:visible" + inkscape:isstock="true"> + <path + id="path1200-6" + style="fill:#ff0000;fill-opacity:1;fill-rule:evenodd;stroke:#ff0000;stroke-width:0.625;stroke-linejoin:round;stroke-opacity:1" + d="M 8.7185878,4.0337352 -2.2072895,0.01601326 8.7185884,-4.0017078 c -1.7454984,2.3720609 -1.7354408,5.6174519 -6e-7,8.035443 z" + transform="scale(-0.6)" + inkscape:connector-curvature="0" /> + </marker> + <marker + inkscape:stockid="Arrow2Mend" + orient="auto" + refY="0" + refX="0" + id="marker8858-3" + style="overflow:visible" + inkscape:isstock="true"> + <path + id="path8616-5" + style="fill:#00ffcc;fill-opacity:1;fill-rule:evenodd;stroke:#00ffcc;stroke-width:0.625;stroke-linejoin:round;stroke-opacity:1" + d="M 8.7185878,4.0337352 -2.2072895,0.01601326 8.7185884,-4.0017078 c -1.7454984,2.3720609 -1.7354408,5.6174519 -6e-7,8.035443 z" + transform="scale(-0.6)" + inkscape:connector-curvature="0" /> + </marker> + <marker + inkscape:stockid="Arrow2Mend" + orient="auto" + refY="0" + refX="0" + id="Arrow2Mend-8-3-3" + style="overflow:visible" + inkscape:isstock="true"> + <path + inkscape:connector-curvature="0" + id="path1200-9-6-56" + style="fill:#ff0000;fill-opacity:1;fill-rule:evenodd;stroke:#ff0000;stroke-width:0.625;stroke-linejoin:round;stroke-opacity:1" + d="M 8.7185878,4.0337352 -2.2072895,0.01601326 8.7185884,-4.0017078 c -1.7454984,2.3720609 -1.7354408,5.6174519 -6e-7,8.035443 z" + transform="scale(-0.6)" /> + </marker> + <marker + inkscape:stockid="Arrow2Mend" + orient="auto" + refY="0" + refX="0" + id="Arrow2Mend-8-0-2" + style="overflow:visible" + inkscape:isstock="true"> + <path + inkscape:connector-curvature="0" + id="path1200-9-3-9" + style="fill:#008000;fill-opacity:1;fill-rule:evenodd;stroke:#008000;stroke-width:0.625;stroke-linejoin:round;stroke-opacity:1" + d="M 8.7185878,4.0337352 -2.2072895,0.01601326 8.7185884,-4.0017078 c -1.7454984,2.3720609 -1.7354408,5.6174519 -6e-7,8.035443 z" + transform="scale(-0.6)" /> + </marker> + </defs> + <sodipodi:namedview + id="base" + pagecolor="#ffffff" + bordercolor="#666666" + borderopacity="1.0" + inkscape:pageopacity="0.0" + inkscape:pageshadow="2" + inkscape:zoom="2.8" + inkscape:cx="603.80172" + inkscape:cy="404.14319" + inkscape:document-units="mm" + inkscape:current-layer="layer1" + showgrid="false" + inkscape:window-width="3840" + inkscape:window-height="2096" + inkscape:window-x="0" + inkscape:window-y="27" + inkscape:window-maximized="1" + showguides="false" + fit-margin-top="0" + fit-margin-left="0" + fit-margin-right="0" + fit-margin-bottom="0" + units="px" + inkscape:snap-global="false" /> + <metadata + id="metadata5"> + <rdf:RDF> + <cc:Work + rdf:about=""> + <dc:format>image/svg+xml</dc:format> + <dc:type + rdf:resource="http://purl.org/dc/dcmitype/StillImage" /> + <dc:title /> + </cc:Work> + </rdf:RDF> + </metadata> + <g + inkscape:label="Layer 1" + inkscape:groupmode="layer" + id="layer1" + transform="translate(419.79645,20.103767)"> + <path + style="fill:#008000;stroke:#008000;stroke-width:0.59275198;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:none;stroke-opacity:1;marker-end:url(#Arrow2Mend-8-3-2-7)" + d="m -340.37552,57.5332 h -14.81024" + id="path1171-7-1-3-0" + inkscape:connector-curvature="0" /> + <path + style="fill:#008000;stroke:#008000;stroke-width:0.59715915;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:none;stroke-opacity:1;marker-end:url(#Arrow2Mend-8-3-4)" + d="m -293.23443,57.5332 h -15.03129" + id="path1171-7-1-32" + inkscape:connector-curvature="0" /> + <path + style="fill:#008000;stroke:#008000;stroke-width:0.59275198;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:none;stroke-opacity:1;marker-end:url(#Arrow2Mend-8-0)" + d="M -246.45946,57.5332 H -261.2697" + id="path1171-7-6" + inkscape:connector-curvature="0" /> + <path + style="fill:#008000;stroke:#008000;stroke-width:0.59275198;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:none;stroke-opacity:1;marker-end:url(#Arrow2Mend-6)" + d="m -151.28623,57.5332 h -14.81024" + id="path1171-0" + inkscape:connector-curvature="0" /> + <path + style="fill:none;stroke:#ff0000;stroke-width:0.98222464;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:none;stroke-opacity:1;marker-end:url(#Arrow2Mend-8-3-2-6)" + d="m -310.11621,-10.988713 h -35.41856" + id="path1171-7-1-3-5" + inkscape:connector-curvature="0" + sodipodi:nodetypes="cc" /> + <path + style="fill:none;stroke:#ff0000;stroke-width:1.33745635;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:none;stroke-opacity:1;marker-end:url(#Arrow2Mend-8-3-2-1)" + d="M -174.42569,48.441117 V -10.963061 L -277.26548,-11.45916" + id="path1171-7-1-3-4" + inkscape:connector-curvature="0" + sodipodi:nodetypes="ccc" /> + <path + style="fill:none;stroke:#ff0000;stroke-width:0.95872593;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:none;stroke-opacity:1;marker-end:url(#Arrow2Mend-8-3)" + d="m -262.79442,87.935594 h 14.32069" + id="path1171-7-1" + inkscape:connector-curvature="0" /> + <path + style="fill:none;stroke:#ff0000;stroke-width:0.97006679;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:none;stroke-opacity:1;marker-end:url(#Arrow2Mend-8)" + d="m -309.80088,87.935594 h 14.44587" + id="path1171-7" + inkscape:connector-curvature="0" /> + <path + style="fill:none;stroke:#ff0000;stroke-width:0.96187615;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:none;stroke-opacity:1;marker-end:url(#Arrow2Mend)" + d="m -356.45657,87.935594 h 14.20296" + id="path1171" + inkscape:connector-curvature="0" /> + <path + style="fill:none;stroke:#ff0000;stroke-width:0.96061862;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:none;stroke-opacity:1;marker-end:url(#Arrow2Mend-8-3-2)" + d="m -167.44556,87.935594 h 14.16584" + id="path1171-7-1-3" + inkscape:connector-curvature="0" /> + <path + style="fill:none;stroke:#008000;stroke-width:0.87091714;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:none;stroke-opacity:1;marker-end:url(#Arrow2Mend-8-0-7)" + d="M -193.82812,48.312503 V 14.168502 l -84.03577,-0.467726" + id="path1171-7-6-4" + inkscape:connector-curvature="0" + sodipodi:nodetypes="ccc" /> + <path + style="fill:none;stroke:#000000;stroke-width:0.81852055;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:4.91112339, 0.81852057;stroke-dashoffset:0;stroke-opacity:1" + d="m -133.33998,42.989657 v 5.457081" + id="path7149-3-7" + inkscape:connector-curvature="0" /> + <path + style="fill:none;stroke:#000000;stroke-width:0.81852055;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:4.91112339, 0.81852057;stroke-dashoffset:0;stroke-opacity:1" + d="m -298.69506,162.44998 v 13.31197" + id="path7149" + inkscape:connector-curvature="0" /> + <path + style="fill:none;stroke:#008080;stroke-width:0.81852055;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:0.81852057, 0.81852057;stroke-dashoffset:0;stroke-opacity:1" + d="m -242.80131,107.00907 v 9.60171" + id="path7040-5-4-7-5-6-9" + inkscape:connector-curvature="0" /> + <path + style="fill:none;stroke:#008080;stroke-width:0.81852055;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:0.81852057, 0.81852057;stroke-dashoffset:0;stroke-opacity:1" + d="m -300.34873,107.17445 v 9.6017" + id="path7040-5-4-7-5-6" + inkscape:connector-curvature="0" /> + <path + style="fill:none;stroke:#008080;stroke-width:0.81852055;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:0.81852057, 0.81852057;stroke-dashoffset:0;stroke-opacity:1" + d="m -359.26293,106.99745 v 9.60171" + id="path7040-5-4-7-5" + inkscape:connector-curvature="0" /> + <path + style="fill:none;stroke:#008080;stroke-width:0.81852055;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:0.81852057, 0.81852057;stroke-dashoffset:0;stroke-opacity:1" + d="M -369.74543,25.114933 V 37.991587" + id="path7040-5-4-7-6" + inkscape:connector-curvature="0" /> + <path + style="fill:none;stroke:#008080;stroke-width:0.91136348;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:0.91136346, 0.91136346;stroke-dashoffset:0;stroke-opacity:1" + d="M -135.17034,93.582486 V 107.10642 H -403.93077 V 37.882965 h 109.60575 V 25.225991" + id="path7038" + inkscape:connector-curvature="0" + sodipodi:nodetypes="cccccc" /> + <path + style="fill:none;stroke:#008080;stroke-width:0.81852055;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:0.81852057, 0.81852057;stroke-dashoffset:0;stroke-opacity:1" + d="M -231.106,94.010086 V 106.96943" + id="path7040" + inkscape:connector-curvature="0" /> + <path + style="fill:none;stroke:#008080;stroke-width:0.81852055;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:0.81852057, 0.81852057;stroke-dashoffset:0;stroke-opacity:1" + d="M -278.50224,93.844719 V 106.80406" + id="path7040-5" + inkscape:connector-curvature="0" /> + <path + style="fill:none;stroke:#008080;stroke-width:0.81852055;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:0.81852057, 0.81852057;stroke-dashoffset:0;stroke-opacity:1" + d="M -325.89848,93.701083 V 106.99115" + id="path7040-5-4" + inkscape:connector-curvature="0" /> + <path + style="fill:none;stroke:#008080;stroke-width:0.81852055;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:0.81852057, 0.81852057;stroke-dashoffset:0;stroke-opacity:1" + d="M -373.29471,93.899037 V 107.27179" + id="path7040-5-4-7" + inkscape:connector-curvature="0" /> + <g + id="g934" + transform="matrix(0.61872421,0,0,0.61872421,-154.16506,-3.5724799)"> + <rect + ry="2.1052283e-06" + y="84.280701" + x="-376.383" + height="72.786827" + width="49.352299" + id="rect834" + style="fill:none;stroke:#000000;stroke-width:1.16258347;stroke-linecap:round;stroke-linejoin:bevel;stroke-miterlimit:4;stroke-dasharray:none" /> + <text + id="text838" + y="95.916664" + x="-371.17261" + style="font-style:normal;font-weight:normal;font-size:10.58333302px;line-height:1.25;font-family:sans-serif;letter-spacing:0px;word-spacing:0px;fill:#000000;fill-opacity:1;stroke:none;stroke-width:0.26458332" + xml:space="preserve"><tspan + style="stroke-width:0.26458332" + y="95.916664" + x="-371.17261" + id="tspan836" + sodipodi:role="line">DCHUB</tspan></text> + <text + id="text846" + y="121.99702" + x="-352.74997" + style="font-style:normal;font-weight:normal;font-size:10.58333302px;line-height:1.25;font-family:sans-serif;letter-spacing:0px;word-spacing:0px;fill:#000000;fill-opacity:1;stroke:none;stroke-width:0.26458332" + xml:space="preserve"><tspan + style="text-align:center;text-anchor:middle;stroke-width:0.26458332" + y="121.99702" + x="-352.74997" + id="tspan844" + sodipodi:role="line">HUBP</tspan><tspan + id="tspan863" + style="text-align:center;text-anchor:middle;stroke-width:0.26458332" + y="135.22618" + x="-352.74997" + sodipodi:role="line">(n)</tspan></text> + </g> + <g + id="g942" + transform="matrix(0.61872421,0,0,0.61872421,-158.40385,-3.2216813)"> + <text + id="text838-5" + y="116.65257" + x="-269.45752" + style="font-style:normal;font-weight:normal;font-size:10.58333302px;line-height:1.25;font-family:sans-serif;letter-spacing:0px;word-spacing:0px;fill:#000000;fill-opacity:1;stroke:none;stroke-width:0.26458332" + xml:space="preserve"><tspan + style="text-align:center;text-anchor:middle;stroke-width:0.26458332" + y="116.65257" + x="-269.45752" + id="tspan836-3" + sodipodi:role="line">DPP</tspan><tspan + id="tspan936" + style="text-align:center;text-anchor:middle;stroke-width:0.26458332" + y="129.88174" + x="-269.45752" + sodipodi:role="line">(n)</tspan></text> + <rect + ry="2.1052283e-06" + y="83.71373" + x="-293.7952" + height="72.786827" + width="49.352303" + id="rect834-5" + style="fill:none;stroke:#000000;stroke-width:1.16258347;stroke-linecap:round;stroke-linejoin:bevel;stroke-miterlimit:4;stroke-dasharray:none" /> + </g> + <g + id="g1158" + transform="matrix(0.61872421,0,0,0.61872421,-154.34048,-6.2618995)"> + <text + id="text838-5-2" + y="128.87331" + x="-200.18195" + style="font-style:normal;font-weight:normal;font-size:10.58333302px;line-height:1.25;font-family:sans-serif;letter-spacing:0px;word-spacing:0px;fill:#000000;fill-opacity:1;stroke:none;stroke-width:0.26458332" + xml:space="preserve"><tspan + id="tspan936-1" + style="text-align:center;text-anchor:middle;stroke-width:0.26458332" + y="128.87331" + x="-200.18195" + sodipodi:role="line">MPC</tspan></text> + <rect + ry="2.1052283e-06" + y="88.627419" + x="-224.62555" + height="72.786827" + width="49.352303" + id="rect834-5-2" + style="fill:none;stroke:#000000;stroke-width:1.16258347;stroke-linecap:round;stroke-linejoin:bevel;stroke-miterlimit:4;stroke-dasharray:none" /> + </g> + <g + id="g1153" + transform="matrix(0.61872421,0,0,0.61872421,-108.51628,-6.4957668)"> + <text + id="text838-5-2-7" + y="129.2513" + x="-120.96272" + style="font-style:normal;font-weight:normal;font-size:10.58333302px;line-height:1.25;font-family:sans-serif;letter-spacing:0px;word-spacing:0px;fill:#000000;fill-opacity:1;stroke:none;stroke-width:0.26458332" + xml:space="preserve"><tspan + id="tspan936-1-0" + style="text-align:center;text-anchor:middle;stroke-width:0.26458332" + y="129.2513" + x="-120.96272" + sodipodi:role="line">OPTC</tspan></text> + <rect + ry="2.1052283e-06" + y="89.005402" + x="-145.62854" + height="72.786827" + width="49.352306" + id="rect834-5-2-9" + style="fill:none;stroke:#000000;stroke-width:1.16258347;stroke-linecap:round;stroke-linejoin:bevel;stroke-miterlimit:4;stroke-dasharray:none" /> + </g> + <g + id="g1148" + transform="matrix(0.61872421,0,0,0.61872421,-105.25474,-7.6650796)"> + <text + id="text838-5-2-7-3" + y="131.14117" + x="-48.981136" + style="font-style:normal;font-weight:normal;font-size:10.58333302px;line-height:1.25;font-family:sans-serif;letter-spacing:0px;word-spacing:0px;fill:#000000;fill-opacity:1;stroke:none;stroke-width:0.26458332" + xml:space="preserve"><tspan + id="tspan936-1-0-6" + style="text-align:center;text-anchor:middle;stroke-width:0.26458332" + y="131.14117" + x="-48.981136" + sodipodi:role="line">DIO</tspan></text> + <rect + ry="2.1052283e-06" + y="90.895279" + x="-73.435081" + height="72.786827" + width="49.352306" + id="rect834-5-2-9-0" + style="fill:none;stroke:#000000;stroke-width:1.16258347;stroke-linecap:round;stroke-linejoin:bevel;stroke-miterlimit:4;stroke-dasharray:none" /> + </g> + <g + id="g1133" + transform="matrix(0.61872421,0,0,0.61872421,-181.52704,-7.6650796)"> + <text + id="text838-5-2-6" + y="241.13223" + x="-286.96921" + style="font-style:normal;font-weight:normal;font-size:10.58333302px;line-height:1.25;font-family:sans-serif;letter-spacing:0px;word-spacing:0px;fill:#000000;fill-opacity:1;stroke:none;stroke-width:0.26458332" + xml:space="preserve"><tspan + id="tspan936-1-2" + style="text-align:center;text-anchor:middle;stroke-width:0.26458332" + y="241.13223" + x="-286.96921" + sodipodi:role="line">DCCG</tspan></text> + <rect + ry="2.1052283e-06" + y="200.88634" + x="-311.56009" + height="72.786827" + width="49.352306" + id="rect834-5-2-6" + style="fill:none;stroke:#000000;stroke-width:1.16258347;stroke-linecap:round;stroke-linejoin:bevel;stroke-miterlimit:4;stroke-dasharray:none" /> + </g> + <g + id="g1138" + transform="matrix(0.61872421,0,0,0.61872421,-181.52704,-7.6650796)"> + <text + id="text838-5-2-6-1" + y="241.81844" + x="-190.55942" + style="font-style:normal;font-weight:normal;font-size:10.58333302px;line-height:1.25;font-family:sans-serif;letter-spacing:0px;word-spacing:0px;fill:#000000;fill-opacity:1;stroke:none;stroke-width:0.26458332" + xml:space="preserve"><tspan + id="tspan936-1-2-8" + style="text-align:center;text-anchor:middle;stroke-width:0.26458332" + y="241.81844" + x="-190.55942" + sodipodi:role="line">DMU</tspan></text> + <rect + ry="2.1052283e-06" + y="201.6423" + x="-215.17615" + height="72.786827" + width="49.352306" + id="rect834-5-2-6-7" + style="fill:none;stroke:#000000;stroke-width:1.16258347;stroke-linecap:round;stroke-linejoin:bevel;stroke-miterlimit:4;stroke-dasharray:none" /> + </g> + <text + xml:space="preserve" + style="font-style:normal;font-weight:normal;font-size:6.54816437px;line-height:1.25;font-family:sans-serif;letter-spacing:0px;word-spacing:0px;fill:#000000;fill-opacity:1;stroke:none;stroke-width:0.1637041" + x="-297.75696" + y="109.44505" + id="text1063"><tspan + sodipodi:role="line" + id="tspan1061" + x="-297.75696" + y="115.23865" + style="stroke-width:0.1637041" /></text> + <g + id="g1143" + transform="matrix(0.61872421,0,0,0.61872421,-181.52704,-8.9747125)"> + <text + id="text838-5-2-6-1-9" + y="243.02728" + x="-99.967323" + style="font-style:normal;font-weight:normal;font-size:10.58333302px;line-height:1.25;font-family:sans-serif;letter-spacing:0px;word-spacing:0px;fill:#000000;fill-opacity:1;stroke:none;stroke-width:0.26458332" + xml:space="preserve"><tspan + id="tspan936-1-2-8-2" + style="text-align:center;text-anchor:middle;stroke-width:0.26458332" + y="243.02728" + x="-99.967323" + sodipodi:role="line">AZ</tspan></text> + <rect + ry="2.1052283e-06" + y="202.77623" + x="-124.83984" + height="72.786827" + width="49.352306" + id="rect834-5-2-6-7-0" + style="fill:none;stroke:#000000;stroke-width:1.16258347;stroke-linecap:round;stroke-linejoin:bevel;stroke-miterlimit:4;stroke-dasharray:none" /> + </g> + <g + id="g1169" + transform="matrix(0.61872421,0,0,0.61872421,-154.16506,1.4555785)"> + <text + id="text838-5-2-6-2" + y="5.9612885" + x="-348.74365" + style="font-style:normal;font-weight:normal;font-size:10.58333302px;line-height:1.25;font-family:sans-serif;letter-spacing:0px;word-spacing:0px;fill:#000000;fill-opacity:1;stroke:none;stroke-width:0.26458332" + xml:space="preserve"><tspan + id="tspan936-1-2-3" + style="text-align:center;text-anchor:middle;stroke-width:0.26458332" + y="5.9612885" + x="-348.74365" + sodipodi:role="line">MMHUBBUB</tspan></text> + <rect + ry="2.1010696e-06" + y="-34.142948" + x="-384.64743" + height="72.643044" + width="72.096924" + id="rect834-5-2-6-75" + style="fill:none;stroke:#000000;stroke-width:1.40378118;stroke-linecap:round;stroke-linejoin:bevel;stroke-miterlimit:4;stroke-dasharray:none" /> + </g> + <g + id="g1164" + transform="matrix(0.61872421,0,0,0.61872421,-154.16506,-7.6650796)"> + <text + id="text838-5-2-6-9" + y="13.465075" + x="-227.30836" + style="font-style:normal;font-weight:normal;font-size:10.58333302px;line-height:1.25;font-family:sans-serif;letter-spacing:0px;word-spacing:0px;fill:#000000;fill-opacity:1;stroke:none;stroke-width:0.26458332" + xml:space="preserve"><tspan + id="tspan936-1-2-2" + style="text-align:center;text-anchor:middle;stroke-width:0.26458332" + y="13.465075" + x="-227.30836" + sodipodi:role="line">DWB</tspan><tspan + id="tspan1128" + style="text-align:center;text-anchor:middle;stroke-width:0.26458332" + y="26.694241" + x="-227.30836" + sodipodi:role="line">(n)</tspan></text> + <rect + ry="2.1052283e-06" + y="-19.473768" + x="-251.83983" + height="72.786827" + width="49.352306" + id="rect834-5-2-6-2" + style="fill:none;stroke:#000000;stroke-width:1.16258347;stroke-linecap:round;stroke-linejoin:bevel;stroke-miterlimit:4;stroke-dasharray:none" /> + </g> + <path + style="fill:none;stroke:#000000;stroke-width:0.91371936;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:5.48231601, 0.91371934;stroke-dashoffset:0;stroke-opacity:1" + d="m -358.95963,161.63019 v 14.12431 h 250.20395 V 43.149938 H -361.845 V 25.478973" + id="path7147" + inkscape:connector-curvature="0" + sodipodi:nodetypes="cccccc" /> + <path + style="fill:none;stroke:#000000;stroke-width:0.81852055;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:4.91112339, 0.81852057;stroke-dashoffset:0;stroke-opacity:1" + d="m -242.92533,161.58513 v 14.05612" + id="path7149-3" + inkscape:connector-curvature="0" /> + <path + style="fill:none;stroke:#000000;stroke-width:0.81852055;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:4.91112339, 0.81852057;stroke-dashoffset:0;stroke-opacity:1" + d="m -184.37695,42.955607 v 5.457082" + id="path7149-3-7-4" + inkscape:connector-curvature="0" /> + <path + style="fill:none;stroke:#000000;stroke-width:0.81852055;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:4.91112339, 0.81852057;stroke-dashoffset:0;stroke-opacity:1" + d="m -277.36283,43.141644 v 5.457082" + id="path7149-3-7-5" + inkscape:connector-curvature="0" /> + <path + style="fill:none;stroke:#000000;stroke-width:0.81852055;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:4.91112339, 0.81852057;stroke-dashoffset:0;stroke-opacity:1" + d="M -325.48437,42.976278 V 48.43336" + id="path7149-3-7-2" + inkscape:connector-curvature="0" /> + <path + style="fill:none;stroke:#000000;stroke-width:0.81852055;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:4.91112339, 0.81852057;stroke-dashoffset:0;stroke-opacity:1" + d="m -361.86492,43.141644 v 5.457083" + id="path7149-3-7-54" + inkscape:connector-curvature="0" /> + <path + style="fill:#008000;stroke:#008000;stroke-width:0.46329758;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:none;stroke-opacity:1;marker-end:url(#Arrow2Mend-6-3)" + d="m -147.58542,-8.2978166 h -9.04766" + id="path1171-0-7" + inkscape:connector-curvature="0" /> + <path + style="fill:none;stroke:#ff0000;stroke-width:0.98222464;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:none;stroke-opacity:1;marker-end:url(#Arrow2Mend-8-3-2-8)" + d="m -157.13421,-1.6500501 h 8.66407" + id="path1171-7-1-3-8" + inkscape:connector-curvature="0" /> + <path + style="fill:none;stroke:#000000;stroke-width:0.74503672;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:4.47022031, 0.74503672;stroke-dashoffset:0;stroke-opacity:1" + d="m -148.50314,4.9845652 h -7.91265" + id="path7149-3-7-8" + inkscape:connector-curvature="0" /> + <path + style="fill:none;stroke:#008080;stroke-width:0.81852055;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:0.81852057, 0.81852057;stroke-dashoffset:0;stroke-opacity:1" + d="m -157.59442,11.623513 h 10.26991" + id="path7040-4" + inkscape:connector-curvature="0" /> + <text + xml:space="preserve" + style="font-style:normal;font-weight:normal;font-size:6.54816437px;line-height:1.25;font-family:sans-serif;letter-spacing:0px;word-spacing:0px;fill:#000000;fill-opacity:1;stroke:none;stroke-width:0.1637041" + x="-142.72867" + y="-6.9685979" + id="text12079"><tspan + sodipodi:role="line" + id="tspan12077" + x="-142.72867" + y="-6.9685979" + style="font-size:4.80198765px;stroke-width:0.1637041">Global sync</tspan></text> + <text + xml:space="preserve" + style="font-style:normal;font-weight:normal;font-size:6.54816437px;line-height:1.25;font-family:sans-serif;letter-spacing:0px;word-spacing:0px;fill:#000000;fill-opacity:1;stroke:none;stroke-width:0.1637041" + x="-142.93031" + y="0.13578746" + id="text12079-3"><tspan + sodipodi:role="line" + id="tspan12077-1" + x="-142.93031" + y="0.13578746" + style="font-size:4.80198765px;stroke-width:0.1637041">Pixel data</tspan></text> + <text + xml:space="preserve" + style="font-style:normal;font-weight:normal;font-size:6.54816437px;line-height:1.25;font-family:sans-serif;letter-spacing:0px;word-spacing:0px;fill:#000000;fill-opacity:1;stroke:none;stroke-width:0.1637041" + x="-142.77556" + y="6.3093324" + id="text12079-3-4"><tspan + sodipodi:role="line" + id="tspan12077-1-9" + x="-142.77556" + y="6.3093324" + style="font-size:4.80198765px;stroke-width:0.1637041">Sideband signal</tspan></text> + <text + xml:space="preserve" + style="font-style:normal;font-weight:normal;font-size:6.54816437px;line-height:1.25;font-family:sans-serif;letter-spacing:0px;word-spacing:0px;fill:#000000;fill-opacity:1;stroke:none;stroke-width:0.1637041" + x="-142.72867" + y="12.948278" + id="text12079-3-4-2"><tspan + sodipodi:role="line" + id="tspan12077-1-9-0" + x="-142.72867" + y="12.948278" + style="font-size:4.80198765px;stroke-width:0.1637041">Config. Bus</tspan></text> + <path + style="fill:none;stroke:#aa00d4;stroke-width:1.32291663;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:none;stroke-opacity:1;marker-end:url(#marker8858)" + d="m -406.68795,73.185276 h 14.20296" + id="path1171-75" + inkscape:connector-curvature="0" /> + <text + xml:space="preserve" + style="font-style:normal;font-weight:normal;font-size:3.17499995px;line-height:1.25;font-family:sans-serif;letter-spacing:0px;word-spacing:0px;fill:#000000;fill-opacity:1;stroke:none;stroke-width:0.26458332" + x="-420.21503" + y="75.065918" + id="text8862"><tspan + sodipodi:role="line" + id="tspan8860" + x="-420.21503" + y="75.065918" + style="font-size:6.3499999px;stroke-width:0.26458332">SDP</tspan></text> + <path + style="fill:none;stroke:#00ffcc;stroke-width:1.25980031;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:none;stroke-opacity:1;marker-end:url(#marker8858-3)" + d="m -119.19923,72.243805 h 12.88004" + id="path1171-75-6" + inkscape:connector-curvature="0" /> + <text + xml:space="preserve" + style="font-style:normal;font-weight:normal;font-size:3.17499995px;line-height:1.25;font-family:sans-serif;letter-spacing:0px;word-spacing:0px;fill:#000000;fill-opacity:1;stroke:none;stroke-width:0.26458332" + x="-104.87327" + y="74.54258" + id="text8862-2"><tspan + sodipodi:role="line" + id="tspan8860-9" + x="-104.87327" + y="74.54258" + style="font-size:6.3499999px;stroke-width:0.26458332">Monitor</tspan></text> + <g + id="g6280" + transform="translate(-133.43389,-37.35791)"> + <text + id="text838-5-2-7-6" + y="110.67171" + x="-97.4758" + style="font-style:normal;font-weight:normal;font-size:6.54816437px;line-height:1.25;font-family:sans-serif;letter-spacing:0px;word-spacing:0px;fill:#000000;fill-opacity:1;stroke:none;stroke-width:0.16370411" + xml:space="preserve"><tspan + id="tspan936-1-0-7" + style="text-align:center;text-anchor:middle;stroke-width:0.16370411" + y="110.67171" + x="-97.4758" + sodipodi:role="line">OPP</tspan></text> + <rect + ry="1.3025557e-06" + y="85.770599" + x="-112.73714" + height="45.034973" + width="30.535467" + id="rect834-5-2-9-5" + style="fill:none;stroke:#000000;stroke-width:0.71931857;stroke-linecap:round;stroke-linejoin:bevel;stroke-miterlimit:4;stroke-dasharray:none" /> + </g> + <path + style="fill:#008000;stroke:#008000;stroke-width:0.59275198;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:none;stroke-opacity:1;marker-end:url(#Arrow2Mend-8-0-2)" + d="m -199.6735,57.600919 h -14.81024" + id="path1171-7-6-1" + inkscape:connector-curvature="0" /> + <path + style="fill:none;stroke:#ff0000;stroke-width:0.95872593;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:none;stroke-opacity:1;marker-end:url(#Arrow2Mend-8-3-3)" + d="m -214.95012,88.003315 h 14.32069" + id="path1171-7-1-2" + inkscape:connector-curvature="0" /> + <path + style="fill:none;stroke:#008080;stroke-width:0.81852055;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:0.81852058, 0.81852058;stroke-dashoffset:0;stroke-opacity:1" + d="M -182.99565,94.057598 V 107.01694" + id="path7040-7" + inkscape:connector-curvature="0" /> + <path + style="fill:none;stroke:#000000;stroke-width:0.81852055;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:4.91112344, 0.81852058;stroke-dashoffset:0;stroke-opacity:1" + d="m -231.7616,43.563759 v 5.457082" + id="path7149-3-7-4-0" + inkscape:connector-curvature="0" /> + <g + aria-label="[" + transform="matrix(0,-1,0.74237844,0,14.567595,39.540924)" + style="font-style:normal;font-weight:normal;font-size:3.17499995px;line-height:1.25;font-family:sans-serif;letter-spacing:0px;word-spacing:0px;fill:#000000;fill-opacity:1;stroke:none;stroke-width:0.26458332" + id="text6872"> + <path + d="m -65.936923,-548.78511 h 8.816294 v 2.79112 h -6.82247 v 176.34952 h 6.82247 v 2.41314 h -8.816294 z" + style="font-size:50.79999924px;stroke-width:0.26458332" + id="path6874" + inkscape:connector-curvature="0" + sodipodi:nodetypes="ccccccccc" /> + </g> + <g + aria-label="[" + transform="rotate(-90,182.49521,-144.01791)" + style="font-style:normal;font-weight:normal;font-size:3.17499995px;line-height:1.25;font-family:sans-serif;letter-spacing:0px;word-spacing:0px;fill:#000000;fill-opacity:1;stroke:none;stroke-width:0.26458332" + id="text6872-3"> + <path + d="m -63.825546,-623.34091 h 7.228794 v 2.26195 h -5.764137 l 0,127.08032 h 5.764137 v 1.88397 h -7.228794 z" + style="font-size:50.79999924px;stroke-width:0.26458332" + id="path6874-6" + inkscape:connector-curvature="0" + sodipodi:nodetypes="ccccccccc" /> + </g> + <text + xml:space="preserve" + style="font-style:normal;font-weight:normal;font-size:3.17499995px;line-height:1.25;font-family:sans-serif;letter-spacing:0px;word-spacing:0px;fill:#000000;fill-opacity:1;stroke:none;stroke-width:0.26458332" + x="-359.80389" + y="99.104233" + id="text6929"><tspan + sodipodi:role="line" + id="tspan6927" + x="-359.80389" + y="99.104233" + style="font-style:normal;font-variant:normal;font-weight:bold;font-stretch:normal;font-size:5.64444447px;font-family:sans-serif;-inkscape-font-specification:'sans-serif Bold';stroke-width:0.26458332">dc_plane</tspan></text> + <text + xml:space="preserve" + style="font-style:normal;font-weight:normal;font-size:3.17499995px;line-height:1.25;font-family:sans-serif;letter-spacing:0px;word-spacing:0px;fill:#000000;fill-opacity:1;stroke:none;stroke-width:0.26458332" + x="-223.56163" + y="99.142021" + id="text6933"><tspan + sodipodi:role="line" + id="tspan6931" + x="-223.56163" + y="99.142021" + style="font-style:normal;font-variant:normal;font-weight:bold;font-stretch:normal;font-size:5.64444447px;font-family:sans-serif;-inkscape-font-specification:'sans-serif Bold';stroke-width:0.26458332">dc_stream</tspan></text> + <g + aria-label="[" + transform="matrix(0,1,1,0,153.30551,96.566025)" + style="font-style:normal;font-weight:normal;font-size:3.17499995px;line-height:1.25;font-family:sans-serif;letter-spacing:0px;word-spacing:0px;fill:#000000;fill-opacity:1;stroke:none;stroke-width:0.26458332" + id="text6872-35"> + <path + d="m -65.936923,-545.95029 h 8.816294 v 2.79112 h -6.898066 v 271.78851 h 6.898066 v 2.41314 h -8.816294 z" + style="font-size:50.79999924px;stroke-width:0.26458332" + id="path6874-62" + inkscape:connector-curvature="0" + sodipodi:nodetypes="ccccccccc" /> + </g> + <text + xml:space="preserve" + style="font-style:normal;font-weight:normal;font-size:3.17499995px;line-height:1.25;font-family:sans-serif;letter-spacing:0px;word-spacing:0px;fill:#000000;fill-opacity:1;stroke:none;stroke-width:0.26458332" + x="-267.43958" + y="28.5028" + id="text6933-9"><tspan + sodipodi:role="line" + id="tspan6931-1" + x="-267.43958" + y="28.5028" + style="font-style:normal;font-variant:normal;font-weight:bold;font-stretch:normal;font-size:5.64444447px;font-family:sans-serif;-inkscape-font-specification:'sans-serif Bold';stroke-width:0.26458332">dc_state</tspan></text> + <g + aria-label="[" + transform="matrix(0,0.98158883,-1.0187565,0,0,-7.4835468)" + style="font-style:normal;font-variant:normal;font-weight:bold;font-stretch:normal;font-size:6.62759447px;line-height:1.25;font-family:sans-serif;-inkscape-font-specification:'sans-serif Bold';letter-spacing:0px;word-spacing:0px;fill:#000000;fill-opacity:1;stroke:none;stroke-width:0.5522995" + id="text6973"> + <path + d="m 23.679381,144.30265 h 3.028123 v 1.29445 h -1.820839 v 7.91629 h 1.820839 v 1.29445 h -3.028123 z" + style="font-style:normal;font-variant:normal;font-weight:bold;font-stretch:normal;font-size:11.78239059px;font-family:sans-serif;-inkscape-font-specification:'sans-serif Bold';stroke-width:0.5522995" + id="path6975" + inkscape:connector-curvature="0" + sodipodi:nodetypes="ccccccccc" /> + </g> + <text + xml:space="preserve" + style="font-style:normal;font-weight:normal;font-size:3.17499995px;line-height:1.25;font-family:sans-serif;letter-spacing:0px;word-spacing:0px;fill:#000000;fill-opacity:1;stroke:none;stroke-width:0.26458332" + x="-142.71655" + y="18.955769" + id="text6980"><tspan + sodipodi:role="line" + id="tspan6978" + x="-142.71655" + y="18.955769" + style="font-size:4.58611107px;stroke-width:0.26458332">Code struct</tspan></text> + <g + aria-label="[" + transform="rotate(-90,94.826273,-58.762727)" + style="font-style:normal;font-weight:normal;font-size:3.17499995px;line-height:1.25;font-family:sans-serif;letter-spacing:0px;word-spacing:0px;fill:#000000;fill-opacity:1;stroke:none;stroke-width:0.26458332" + id="text6872-35-2"> + <path + d="m -66.881863,-308.95922 h 7.115401 l 0,1.69499 h -5.197173 v 42.03568 h 5.197173 v 1.78948 h -7.115401 z" + style="font-size:50.79999924px;stroke-width:0.26458332" + id="path6874-62-7" + inkscape:connector-curvature="0" + sodipodi:nodetypes="ccccccccc" /> + </g> + <text + xml:space="preserve" + style="font-style:normal;font-weight:normal;font-size:3.17499995px;line-height:1.25;font-family:sans-serif;letter-spacing:0px;word-spacing:0px;fill:#000000;fill-opacity:1;stroke:none;stroke-width:0.26458332" + x="-134.09625" + y="99.354439" + id="text6933-9-0"><tspan + sodipodi:role="line" + id="tspan6931-1-9" + x="-134.09625" + y="99.354439" + style="font-style:normal;font-variant:normal;font-weight:bold;font-stretch:normal;font-size:5.64444447px;font-family:sans-serif;-inkscape-font-specification:'sans-serif Bold';stroke-width:0.26458332">dc_link</tspan></text> + <g + aria-label="}" + transform="rotate(90,-145.27371,-140.09832)" + style="font-style:normal;font-weight:normal;font-size:3.17499995px;line-height:1.25;font-family:sans-serif;letter-spacing:0px;word-spacing:0px;fill:#3771c8;fill-opacity:1;stroke:none;stroke-width:0.26458332" + id="text1003"> + <path + d="m 102.58571,58.211269 h 0.86816 c 1.15755,0 3.11267,-0.177767 3.45994,-0.5333 0.35553,-0.355534 1.28925,-1.124479 1.28925,-2.306836 V -61.475482 c 0,-1.289844 0.18603,-2.228288 0.5581,-2.815332 0.37207,-0.587044 0.26105,-0.992187 1.17882,-1.215429 -0.91777,-0.206706 -0.80675,-0.603581 -1.17882,-1.190625 -0.37207,-0.587045 -0.5581,-1.529623 -0.5581,-2.827735 v -3.075781 c 0,-1.174088 -0.93372,-1.938899 -1.28925,-2.294433 -0.34727,-0.363802 -2.30239,-0.545703 -3.45994,-0.545703 h -0.86816 v -1.773536 h 0.78134 c 2.05879,0 4.63403,0.305924 5.32029,0.917774 0.69453,0.60358 1.0418,1.81901 1.0418,3.646289 v 2.976562 c 0,1.231966 0.22324,2.087728 0.66973,2.567285 0.44648,0.471289 5.80035,0.706934 6.97444,0.706934 h 0.76894 v 1.773535 h -0.76894 c -1.17409,0 -6.52796,0.239778 -6.97444,0.719336 -0.44649,0.479557 -0.66973,1.343587 -0.66973,2.59209 V 55.420742 c 0,1.827279 -0.34727,3.046842 -1.0418,3.658691 -0.68626,0.611849 -3.2615,0.917774 -5.32029,0.917774 h -0.78134 z" + style="font-size:25.39999962px;fill:#3771c8;stroke-width:0.26458332" + id="path1005" + inkscape:connector-curvature="0" + sodipodi:nodetypes="cscsscccsscsccscsscsccscsscscc" /> + </g> + <text + xml:space="preserve" + style="font-style:normal;font-weight:normal;font-size:3.17499995px;line-height:1.25;font-family:sans-serif;letter-spacing:0px;word-spacing:0px;fill:#000000;fill-opacity:1;stroke:none;stroke-width:0.26458332" + x="-200.59984" + y="129.60852" + id="text1010"><tspan + sodipodi:role="line" + id="tspan1008" + x="-200.59984" + y="129.60852" + style="font-style:italic;font-variant:normal;font-weight:bold;font-stretch:normal;font-size:6.3499999px;font-family:sans-serif;-inkscape-font-specification:'sans-serif Bold Italic';text-align:center;text-anchor:middle;stroke-width:0.26458332">Floating point</tspan><tspan + sodipodi:role="line" + x="-200.59984" + y="137.54602" + style="font-size:6.3499999px;text-align:center;text-anchor:middle;stroke-width:0.26458332" + id="tspan1059">calculation</tspan></text> + <g + aria-label="}" + transform="rotate(90,-94.294068,-92.593178)" + style="font-style:normal;font-weight:normal;font-size:3.17499995px;line-height:1.25;font-family:sans-serif;letter-spacing:0px;word-spacing:0px;fill:#3771c8;fill-opacity:1;stroke:none;stroke-width:0.26458332" + id="text1003-5"> + <path + d="m 102.58571,58.211269 h 0.86816 c 1.15755,0 3.11267,-0.177767 3.45994,-0.5333 0.35553,-0.355534 1.10026,-1.124479 1.10026,-2.306836 V -44.637502 c 0,-1.289844 0.18603,-2.228288 0.5581,-2.815332 0.37207,-0.587044 0.45004,-0.992187 1.36781,-1.215429 -0.91777,-0.206706 -0.99574,-0.603581 -1.36781,-1.190625 -0.37207,-0.587045 -0.5581,-1.529623 -0.5581,-2.827735 v -19.913761 c 0,-1.174088 -0.74473,-1.938899 -1.10026,-2.294433 -0.34727,-0.363802 -2.30239,-0.545703 -3.45994,-0.545703 h -0.86816 v -1.773536 h 0.78134 c 2.05879,0 4.63403,0.305924 5.32029,0.917774 0.69453,0.60358 1.0418,1.81901 1.0418,3.646289 v 19.814542 c 0,1.231966 0.22324,2.087728 0.66973,2.567285 0.44648,0.471289 1.25677,0.706934 2.43086,0.706934 h 0.76894 v 1.773535 h -0.76894 c -1.17409,0 -1.98438,0.239778 -2.43086,0.719336 -0.44649,0.479557 -0.66973,1.343587 -0.66973,2.59209 v 99.897013 c 0,1.827279 -0.34727,3.046842 -1.0418,3.658691 -0.68626,0.611849 -3.2615,0.917774 -5.32029,0.917774 h -0.78134 z" + style="font-size:25.39999962px;fill:#3771c8;stroke-width:0.26458332" + id="path1005-3" + inkscape:connector-curvature="0" + sodipodi:nodetypes="cscsscccsscsccscsscsccscsscscc" /> + </g> + <text + xml:space="preserve" + style="font-style:normal;font-weight:normal;font-size:3.17499995px;line-height:1.25;font-family:sans-serif;letter-spacing:0px;word-spacing:0px;fill:#000000;fill-opacity:1;stroke:none;stroke-width:0.26458332" + x="-137.43764" + y="122.46283" + id="text1010-5"><tspan + sodipodi:role="line" + id="tspan1008-6" + x="-137.43764" + y="122.46283" + style="font-size:6.3499999px;text-align:center;text-anchor:middle;stroke-width:0.26458332">bit-depth</tspan><tspan + sodipodi:role="line" + x="-137.43764" + y="130.40033" + style="font-size:6.3499999px;text-align:center;text-anchor:middle;stroke-width:0.26458332" + id="tspan1057">reduction/dither</tspan></text> + <text + xml:space="preserve" + style="font-style:normal;font-weight:normal;font-size:3.17499995px;line-height:1.25;font-family:sans-serif;letter-spacing:0px;word-spacing:0px;fill:#3771c8;fill-opacity:1;stroke:none;stroke-width:0.26458332;" + x="21.087883" + y="155.64751" + id="text1064" + transform="rotate(90)"><tspan + sodipodi:role="line" + id="tspan1062" + x="21.087883" + y="155.64751" + style="font-size:9.87777805px;stroke-width:0.26458332;fill:#3771c8;">}</tspan></text> + <text + xml:space="preserve" + style="font-style:normal;font-weight:normal;font-size:3.17499995px;line-height:1.25;font-family:sans-serif;letter-spacing:0px;word-spacing:0px;fill:#000000;fill-opacity:1;stroke:none;stroke-width:0.26458332" + x="-142.71655" + y="25.939869" + id="text6980-9"><tspan + sodipodi:role="line" + id="tspan6978-1" + x="-142.71655" + y="25.939869" + style="font-size:4.58611107px;stroke-width:0.26458332">Notes</tspan></text> + </g> +</svg> diff --git a/Documentation/gpu/amdgpu/display/dcn-overview.rst b/Documentation/gpu/amdgpu/display/dcn-overview.rst new file mode 100644 index 000000000000..f98624d7828e --- /dev/null +++ b/Documentation/gpu/amdgpu/display/dcn-overview.rst @@ -0,0 +1,171 @@ +======================= +Display Core Next (DCN) +======================= + +To equip our readers with the basic knowledge of how AMD Display Core Next +(DCN) works, we need to start with an overview of the hardware pipeline. Below +you can see a picture that provides a DCN overview, keep in mind that this is a +generic diagram, and we have variations per ASIC. + +.. kernel-figure:: dc_pipeline_overview.svg + +Based on this diagram, we can pass through each block and briefly describe +them: + +* **Display Controller Hub (DCHUB)**: This is the gateway between the Scalable + Data Port (SDP) and DCN. This component has multiple features, such as memory + arbitration, rotation, and cursor manipulation. + +* **Display Pipe and Plane (DPP)**: This block provides pre-blend pixel + processing such as color space conversion, linearization of pixel data, tone + mapping, and gamut mapping. + +* **Multiple Pipe/Plane Combined (MPC)**: This component performs blending of + multiple planes, using global or per-pixel alpha. + +* **Output Pixel Processing (OPP)**: Process and format pixels to be sent to + the display. + +* **Output Pipe Timing Combiner (OPTC)**: It generates time output to combine + streams or divide capabilities. CRC values are generated in this block. + +* **Display Output (DIO)**: Codify the output to the display connected to our + GPU. + +* **Display Writeback (DWB)**: It provides the ability to write the output of + the display pipe back to memory as video frames. + +* **Multi-Media HUB (MMHUBBUB)**: Memory controller interface for DMCUB and DWB + (Note that DWB is not hooked yet). + +* **DCN Management Unit (DMU)**: It provides registers with access control and + interrupts the controller to the SOC host interrupt unit. This block includes + the Display Micro-Controller Unit - version B (DMCUB), which is handled via + firmware. + +* **DCN Clock Generator Block (DCCG)**: It provides the clocks and resets + for all of the display controller clock domains. + +* **Azalia (AZ)**: Audio engine. + +The above diagram is an architecture generalization of DCN, which means that +every ASIC has variations around this base model. Notice that the display +pipeline is connected to the Scalable Data Port (SDP) via DCHUB; you can see +the SDP as the element from our Data Fabric that feeds the display pipe. + +Always approach the DCN architecture as something flexible that can be +configured and reconfigured in multiple ways; in other words, each block can be +setup or ignored accordingly with userspace demands. For example, if we +want to drive an 8k@60Hz with a DSC enabled, our DCN may require 4 DPP and 2 +OPP. It is DC's responsibility to drive the best configuration for each +specific scenario. Orchestrate all of these components together requires a +sophisticated communication interface which is highlighted in the diagram by +the edges that connect each block; from the chart, each connection between +these blocks represents: + +1. Pixel data interface (red): Represents the pixel data flow; +2. Global sync signals (green): It is a set of synchronization signals composed + by VStartup, VUpdate, and VReady; +3. Config interface: Responsible to configure blocks; +4. Sideband signals: All other signals that do not fit the previous one. + +These signals are essential and play an important role in DCN. Nevertheless, +the Global Sync deserves an extra level of detail described in the next +section. + +All of these components are represented by a data structure named dc_state. +From DCHUB to MPC, we have a representation called dc_plane; from MPC to OPTC, +we have dc_stream, and the output (DIO) is handled by dc_link. Keep in mind +that HUBP accesses a surface using a specific format read from memory, and our +dc_plane should work to convert all pixels in the plane to something that can +be sent to the display via dc_stream and dc_link. + +Front End and Back End +---------------------- + +Display pipeline can be broken down into two components that are usually +referred as **Front End (FE)** and **Back End (BE)**, where FE consists of: + +* DCHUB (Mainly referring to a subcomponent named HUBP) +* DPP +* MPC + +On the other hand, BE consist of + +* OPP +* OPTC +* DIO (DP/HDMI stream encoder and link encoder) + +OPP and OPTC are two joining blocks between FE and BE. On a side note, this is +a one-to-one mapping of the link encoder to PHY, but we can configure the DCN +to choose which link encoder to connect to which PHY. FE's main responsibility +is to change, blend and compose pixel data, while BE's job is to frame a +generic pixel stream to a specific display's pixel stream. + +Data Flow +--------- + +Initially, data is passed in from VRAM through Data Fabric (DF) in native pixel +formats. Such data format stays through till HUBP in DCHUB, where HUBP unpacks +different pixel formats and outputs them to DPP in uniform streams through 4 +channels (1 for alpha + 3 for colors). + +The Converter and Cursor (CNVC) in DPP would then normalize the data +representation and convert them to a DCN specific floating-point format (i.e., +different from the IEEE floating-point format). In the process, CNVC also +applies a degamma function to transform the data from non-linear to linear +space to relax the floating-point calculations following. Data would stay in +this floating-point format from DPP to OPP. + +Starting OPP, because color transformation and blending have been completed +(i.e alpha can be dropped), and the end sinks do not require the precision and +dynamic range that floating points provide (i.e. all displays are in integer +depth format), bit-depth reduction/dithering would kick in. In OPP, we would +also apply a regamma function to introduce the gamma removed earlier back. +Eventually, we output data in integer format at DIO. + +Global Sync +----------- + +Many DCN registers are double buffered, most importantly the surface address. +This allows us to update DCN hardware atomically for page flips, as well as +for most other updates that don't require enabling or disabling of new pipes. + +(Note: There are many scenarios when DC will decide to reserve extra pipes +in order to support outputs that need a very high pixel clock, or for +power saving purposes.) + +These atomic register updates are driven by global sync signals in DCN. In +order to understand how atomic updates interact with DCN hardware, and how DCN +signals page flip and vblank events it is helpful to understand how global sync +is programmed. + +Global sync consists of three signals, VSTARTUP, VUPDATE, and VREADY. These are +calculated by the Display Mode Library - DML (drivers/gpu/drm/amd/display/dc/dml) +based on a large number of parameters and ensure our hardware is able to feed +the DCN pipeline without underflows or hangs in any given system configuration. +The global sync signals always happen during VBlank, are independent from the +VSync signal, and do not overlap each other. + +VUPDATE is the only signal that is of interest to the rest of the driver stack +or userspace clients as it signals the point at which hardware latches to +atomically programmed (i.e. double buffered) registers. Even though it is +independent of the VSync signal we use VUPDATE to signal the VSync event as it +provides the best indication of how atomic commits and hardware interact. + +Since DCN hardware is double-buffered the DC driver is able to program the +hardware at any point during the frame. + +The below picture illustrates the global sync signals: + +.. kernel-figure:: global_sync_vblank.svg + +These signals affect core DCN behavior. Programming them incorrectly will lead +to a number of negative consequences, most of them quite catastrophic. + +The following picture shows how global sync allows for a mailbox style of +updates, i.e. it allows for multiple re-configurations between VUpdate +events where only the last configuration programmed before the VUpdate signal +becomes effective. + +.. kernel-figure:: config_example.svg diff --git a/Documentation/gpu/amdgpu/display/display-manager.rst b/Documentation/gpu/amdgpu/display/display-manager.rst new file mode 100644 index 000000000000..7ce31f89d9a0 --- /dev/null +++ b/Documentation/gpu/amdgpu/display/display-manager.rst @@ -0,0 +1,42 @@ +====================== +AMDgpu Display Manager +====================== + +.. contents:: Table of Contents + :depth: 3 + +.. kernel-doc:: drivers/gpu/drm/amd/display/amdgpu_dm/amdgpu_dm.c + :doc: overview + +.. kernel-doc:: drivers/gpu/drm/amd/display/amdgpu_dm/amdgpu_dm.h + :internal: + +Lifecycle +========= + +.. kernel-doc:: drivers/gpu/drm/amd/display/amdgpu_dm/amdgpu_dm.c + :doc: DM Lifecycle + +.. kernel-doc:: drivers/gpu/drm/amd/display/amdgpu_dm/amdgpu_dm.c + :functions: dm_hw_init dm_hw_fini + +Interrupts +========== + +.. kernel-doc:: drivers/gpu/drm/amd/display/amdgpu_dm/amdgpu_dm_irq.c + :doc: overview + +.. kernel-doc:: drivers/gpu/drm/amd/display/amdgpu_dm/amdgpu_dm_irq.c + :internal: + +.. kernel-doc:: drivers/gpu/drm/amd/display/amdgpu_dm/amdgpu_dm.c + :functions: register_hpd_handlers dm_crtc_high_irq dm_pflip_high_irq + +Atomic Implementation +===================== + +.. kernel-doc:: drivers/gpu/drm/amd/display/amdgpu_dm/amdgpu_dm.c + :doc: atomic + +.. kernel-doc:: drivers/gpu/drm/amd/display/amdgpu_dm/amdgpu_dm.c + :functions: amdgpu_dm_atomic_check amdgpu_dm_atomic_commit_tail diff --git a/Documentation/gpu/amdgpu/display/global_sync_vblank.svg b/Documentation/gpu/amdgpu/display/global_sync_vblank.svg new file mode 100644 index 000000000000..48f5dc4fd5d3 --- /dev/null +++ b/Documentation/gpu/amdgpu/display/global_sync_vblank.svg @@ -0,0 +1,485 @@ +<?xml version="1.0" encoding="UTF-8" standalone="no"?> +<!-- Created with Inkscape (http://www.inkscape.org/) --> + +<svg + xmlns:dc="http://purl.org/dc/elements/1.1/" + xmlns:cc="http://creativecommons.org/ns#" + xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#" + xmlns:svg="http://www.w3.org/2000/svg" + xmlns="http://www.w3.org/2000/svg" + xmlns:sodipodi="http://sodipodi.sourceforge.net/DTD/sodipodi-0.dtd" + xmlns:inkscape="http://www.inkscape.org/namespaces/inkscape" + width="232.24133mm" + height="96.174995mm" + viewBox="0 0 232.24133 96.174995" + version="1.1" + id="svg8" + inkscape:version="0.92.5 (2060ec1f9f, 2020-04-08)" + sodipodi:docname="global_sync_vblank.svg"> + <defs + id="defs2"> + <marker + inkscape:stockid="Arrow2Mend" + orient="auto" + refY="0" + refX="0" + id="Arrow2Mend" + style="overflow:visible" + inkscape:isstock="true"> + <path + id="path862" + style="fill:#800080;fill-opacity:1;fill-rule:evenodd;stroke:#800080;stroke-width:0.625;stroke-linejoin:round;stroke-opacity:1" + d="M 8.7185878,4.0337352 -2.2072895,0.01601326 8.7185884,-4.0017078 c -1.7454984,2.3720609 -1.7354408,5.6174519 -6e-7,8.035443 z" + transform="scale(-0.6)" + inkscape:connector-curvature="0" /> + </marker> + <marker + inkscape:stockid="Arrow2Send" + orient="auto" + refY="0" + refX="0" + id="Arrow2Send" + style="overflow:visible" + inkscape:isstock="true"> + <path + id="path868" + style="fill:#ff00ff;fill-opacity:1;fill-rule:evenodd;stroke:#ff00ff;stroke-width:0.625;stroke-linejoin:round;stroke-opacity:1" + d="M 8.7185878,4.0337352 -2.2072895,0.01601326 8.7185884,-4.0017078 c -1.7454984,2.3720609 -1.7354408,5.6174519 -6e-7,8.035443 z" + transform="matrix(-0.3,0,0,-0.3,0.69,0)" + inkscape:connector-curvature="0" /> + </marker> + <marker + inkscape:stockid="Arrow2Lend" + orient="auto" + refY="0" + refX="0" + id="Arrow2Lend" + style="overflow:visible" + inkscape:isstock="true"> + <path + id="path856" + style="fill:#ff00ff;fill-opacity:1;fill-rule:evenodd;stroke:#ff00ff;stroke-width:0.625;stroke-linejoin:round;stroke-opacity:1" + d="M 8.7185878,4.0337352 -2.2072895,0.01601326 8.7185884,-4.0017078 c -1.7454984,2.3720609 -1.7354408,5.6174519 -6e-7,8.035443 z" + transform="matrix(-1.1,0,0,-1.1,-1.1,0)" + inkscape:connector-curvature="0" /> + </marker> + <marker + inkscape:stockid="Arrow1Lend" + orient="auto" + refY="0" + refX="0" + id="marker1719" + style="overflow:visible" + inkscape:isstock="true"> + <path + id="path1717" + d="M 0,0 5,-5 -12.5,0 5,5 Z" + style="fill:#ff00ff;fill-opacity:1;fill-rule:evenodd;stroke:#ff00ff;stroke-width:1.00000003pt;stroke-opacity:1" + transform="matrix(-0.8,0,0,-0.8,-10,0)" + inkscape:connector-curvature="0" /> + </marker> + <marker + inkscape:stockid="Arrow1Lend" + orient="auto" + refY="0" + refX="0" + id="marker1661" + style="overflow:visible" + inkscape:isstock="true"> + <path + id="path1659" + d="M 0,0 5,-5 -12.5,0 5,5 Z" + style="fill:#ff00ff;fill-opacity:1;fill-rule:evenodd;stroke:#ff00ff;stroke-width:1.00000003pt;stroke-opacity:1" + transform="matrix(-0.8,0,0,-0.8,-10,0)" + inkscape:connector-curvature="0" /> + </marker> + <marker + inkscape:isstock="true" + style="overflow:visible" + id="marker1311" + refX="0" + refY="0" + orient="auto" + inkscape:stockid="Arrow1Lend" + inkscape:collect="always"> + <path + transform="matrix(-0.8,0,0,-0.8,-10,0)" + style="fill:#ff0000;fill-opacity:1;fill-rule:evenodd;stroke:#ff0000;stroke-width:1.00000003pt;stroke-opacity:1" + d="M 0,0 5,-5 -12.5,0 5,5 Z" + id="path1309" + inkscape:connector-curvature="0" /> + </marker> + <marker + inkscape:isstock="true" + style="overflow:visible" + id="marker1253" + refX="0" + refY="0" + orient="auto" + inkscape:stockid="Arrow1Lstart"> + <path + transform="matrix(0.8,0,0,0.8,10,0)" + style="fill:#ff0000;fill-opacity:1;fill-rule:evenodd;stroke:#ff0000;stroke-width:1.00000003pt;stroke-opacity:1" + d="M 0,0 5,-5 -12.5,0 5,5 Z" + id="path1251" + inkscape:connector-curvature="0" /> + </marker> + <marker + inkscape:stockid="Arrow1Lend" + orient="auto" + refY="0" + refX="0" + id="Arrow1Lend" + style="overflow:visible" + inkscape:isstock="true" + inkscape:collect="always"> + <path + id="path838" + d="M 0,0 5,-5 -12.5,0 5,5 Z" + style="fill:#ff0000;fill-opacity:1;fill-rule:evenodd;stroke:#ff0000;stroke-width:1.00000003pt;stroke-opacity:1" + transform="matrix(-0.8,0,0,-0.8,-10,0)" + inkscape:connector-curvature="0" /> + </marker> + <marker + inkscape:stockid="Arrow1Lstart" + orient="auto" + refY="0" + refX="0" + id="Arrow1Lstart" + style="overflow:visible" + inkscape:isstock="true" + inkscape:collect="always"> + <path + id="path835" + d="M 0,0 5,-5 -12.5,0 5,5 Z" + style="fill:#ff0000;fill-opacity:1;fill-rule:evenodd;stroke:#ff0000;stroke-width:1.00000003pt;stroke-opacity:1" + transform="matrix(0.8,0,0,0.8,10,0)" + inkscape:connector-curvature="0" /> + </marker> + <marker + inkscape:stockid="Arrow1Send" + orient="auto" + refY="0" + refX="0" + id="Arrow1Send" + style="overflow:visible" + inkscape:isstock="true"> + <path + id="path850" + d="M 0,0 5,-5 -12.5,0 5,5 Z" + style="fill:#000000;fill-opacity:1;fill-rule:evenodd;stroke:#000000;stroke-width:1.00000003pt;stroke-opacity:1" + transform="matrix(-0.2,0,0,-0.2,-1.2,0)" + inkscape:connector-curvature="0" /> + </marker> + <marker + inkscape:stockid="Arrow2Sstart" + orient="auto" + refY="0" + refX="0" + id="Arrow2Sstart" + style="overflow:visible" + inkscape:isstock="true"> + <path + id="path865" + style="fill:#000000;fill-opacity:1;fill-rule:evenodd;stroke:#000000;stroke-width:0.625;stroke-linejoin:round;stroke-opacity:1" + d="M 8.7185878,4.0337352 -2.2072895,0.01601326 8.7185884,-4.0017078 c -1.7454984,2.3720609 -1.7354408,5.6174519 -6e-7,8.035443 z" + transform="matrix(0.3,0,0,0.3,-0.69,0)" + inkscape:connector-curvature="0" /> + </marker> + <marker + inkscape:stockid="Arrow2Mend" + orient="auto" + refY="0" + refX="0" + id="Arrow2Mend-2" + style="overflow:visible" + inkscape:isstock="true"> + <path + inkscape:connector-curvature="0" + id="path862-3" + style="fill:#800080;fill-opacity:1;fill-rule:evenodd;stroke:#800080;stroke-width:0.625;stroke-linejoin:round;stroke-opacity:1" + d="M 8.7185878,4.0337352 -2.2072895,0.01601326 8.7185884,-4.0017078 c -1.7454984,2.3720609 -1.7354408,5.6174519 -6e-7,8.035443 z" + transform="scale(-0.6)" /> + </marker> + <marker + inkscape:stockid="Arrow2Mend" + orient="auto" + refY="0" + refX="0" + id="Arrow2Mend-2-5" + style="overflow:visible" + inkscape:isstock="true"> + <path + inkscape:connector-curvature="0" + id="path862-3-9" + style="fill:#800080;fill-opacity:1;fill-rule:evenodd;stroke:#800080;stroke-width:0.625;stroke-linejoin:round;stroke-opacity:1" + d="M 8.7185878,4.0337352 -2.2072895,0.01601326 8.7185884,-4.0017078 c -1.7454984,2.3720609 -1.7354408,5.6174519 -6e-7,8.035443 z" + transform="scale(-0.6)" /> + </marker> + </defs> + <sodipodi:namedview + id="base" + pagecolor="#ffffff" + bordercolor="#666666" + borderopacity="1.0" + inkscape:pageopacity="0.0" + inkscape:pageshadow="2" + inkscape:zoom="1.979899" + inkscape:cx="747.52324" + inkscape:cy="319.84503" + inkscape:document-units="mm" + inkscape:current-layer="layer1" + showgrid="true" + inkscape:window-width="3840" + inkscape:window-height="2096" + inkscape:window-x="0" + inkscape:window-y="27" + inkscape:window-maximized="1" + fit-margin-top="0" + fit-margin-left="0" + fit-margin-right="0" + fit-margin-bottom="0"> + <inkscape:grid + type="xygrid" + id="grid815" + originx="15.282997" + originy="-184.54792" /> + </sodipodi:namedview> + <metadata + id="metadata5"> + <rdf:RDF> + <cc:Work + rdf:about=""> + <dc:format>image/svg+xml</dc:format> + <dc:type + rdf:resource="http://purl.org/dc/dcmitype/StillImage" /> + <dc:title /> + </cc:Work> + </rdf:RDF> + </metadata> + <g + inkscape:label="Layer 1" + inkscape:groupmode="layer" + id="layer1" + transform="translate(15.282998,-16.277083)"> + <path + style="fill:none;stroke:#000000;stroke-width:0.5291667;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:none;stroke-opacity:1" + d="M 15.875,27.125001 V 16.541666 H 26.458333 V 27.125001 H 177.27084 V 16.541666 h 10.58333 v 10.583335 h 29.10416" + id="path817" + inkscape:connector-curvature="0" + sodipodi:nodetypes="ccccccccc" /> + <path + style="fill:none;stroke:#000000;stroke-width:0.5291667;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:none;stroke-opacity:1" + d="M 15.875,37.708334 H 44.979166 V 48.291667 H 100.54167 V 37.708334 H 206.375 v 10.583333 h 10.58333" + id="path819" + inkscape:connector-curvature="0" /> + <path + style="fill:none;stroke:#000000;stroke-width:0.5291667;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:none;stroke-opacity:1" + d="m 15.875,66.8125 h 97.89583 V 56.229167 h 7.9375 V 66.8125 h 92.60417" + id="path821" + inkscape:connector-curvature="0" /> + <path + style="fill:none;stroke:#000000;stroke-width:0.5291667;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:none;stroke-opacity:1" + d="m 15.875,85.333334 c 0,0 132.29166,0 132.29166,0 V 74.75 h 15.875 v 10.583334 h 47.625" + id="path823" + inkscape:connector-curvature="0" /> + <path + style="fill:none;stroke:#000000;stroke-width:0.5291667;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:none;stroke-opacity:1" + d="M 15.875,101.20833 H 187.85416 V 90.625 h 10.58334 v 10.58333 h 10.58333" + id="path825" + inkscape:connector-curvature="0" /> + <path + style="fill:none;stroke:#000000;stroke-width:0.5291667;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:0.52916667, 0.52916667;stroke-dashoffset:0;stroke-opacity:1" + d="M 100.54167,48.291667 V 111.79167" + id="path827" + inkscape:connector-curvature="0" /> + <path + style="fill:none;stroke:#000000;stroke-width:0.5291667;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:0.52916667, 0.52916667;stroke-dashoffset:0;stroke-opacity:1" + d="m 113.77083,66.8125 v 44.97917" + id="path829" + inkscape:connector-curvature="0" /> + <path + style="fill:none;stroke:#000000;stroke-width:0.5291667;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:0.52916667, 0.52916667;stroke-dashoffset:0;stroke-opacity:1" + d="M 206.375,48.291667 V 109.14583" + id="path831" + inkscape:connector-curvature="0" /> + <path + style="fill:none;stroke:#ff0000;stroke-width:0.26458332px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1;marker-start:url(#Arrow1Lstart);marker-end:url(#Arrow1Lend)" + d="m 100.54167,106.5 h 13.22916" + id="path833" + inkscape:connector-curvature="0" /> + <path + style="fill:none;stroke:#ff0000;stroke-width:0.26458332px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1;marker-start:url(#marker1253);marker-end:url(#marker1311)" + d="M 113.77083,106.5 H 206.375" + id="path1243" + inkscape:connector-curvature="0" /> + <text + xml:space="preserve" + style="font-style:normal;font-weight:normal;font-size:3.17499995px;line-height:1.25;font-family:sans-serif;letter-spacing:0px;word-spacing:0px;fill:#000000;fill-opacity:1;stroke:none;stroke-width:0.26458332" + x="105.83333" + y="111.79166" + id="text1405"><tspan + sodipodi:role="line" + id="tspan1403" + x="105.83333" + y="111.79166" + style="stroke-width:0.26458332">To</tspan></text> + <text + xml:space="preserve" + style="font-style:normal;font-weight:normal;font-size:3.17499995px;line-height:1.25;font-family:sans-serif;letter-spacing:0px;word-spacing:0px;fill:#000000;fill-opacity:1;stroke:none;stroke-width:0.26458332" + x="145.52083" + y="111.79166" + id="text1409"><tspan + sodipodi:role="line" + id="tspan1407" + x="145.52083" + y="111.79166" + style="stroke-width:0.26458332">VStartup Period</tspan></text> + <text + xml:space="preserve" + style="font-style:normal;font-weight:normal;font-size:3.17499995px;line-height:1.25;font-family:sans-serif;letter-spacing:0px;word-spacing:0px;fill:#000000;fill-opacity:1;stroke:none;stroke-width:0.26458332" + x="156.01123" + y="78.71875" + id="text1413"><tspan + sodipodi:role="line" + x="156.01123" + y="78.71875" + style="font-weight:bold;text-align:center;text-anchor:middle;stroke-width:0.26458332" + id="tspan1415">VUpdate</tspan><tspan + sodipodi:role="line" + x="156.01123" + y="82.6875" + style="font-weight:bold;text-align:center;text-anchor:middle;stroke-width:0.26458332" + id="tspan1440">Width</tspan></text> + <text + xml:space="preserve" + style="font-style:normal;font-weight:normal;font-size:3.17499995px;line-height:1.25;font-family:sans-serif;letter-spacing:0px;word-spacing:0px;fill:#000000;fill-opacity:1;stroke:none;stroke-width:0.26458332" + x="173.77611" + y="92.703873" + id="text1413-3"><tspan + sodipodi:role="line" + id="tspan1411-6" + x="173.77611" + y="92.703873" + style="font-weight:bold;text-align:center;text-anchor:middle;stroke-width:0.26458332">VReady</tspan><tspan + sodipodi:role="line" + x="173.77611" + y="96.672623" + style="font-weight:bold;text-align:center;text-anchor:middle;stroke-width:0.26458332" + id="tspan1415-7">Offset</tspan></text> + <text + xml:space="preserve" + style="font-style:normal;font-weight:normal;font-size:3.17499995px;line-height:1.25;font-family:sans-serif;letter-spacing:0px;word-spacing:0px;fill:#000000;fill-opacity:1;stroke:none;stroke-width:0.26458332" + x="135.78951" + y="70.78125" + id="text1413-5"><tspan + sodipodi:role="line" + x="135.78951" + y="70.78125" + style="font-weight:bold;text-align:center;text-anchor:middle;stroke-width:0.26458332" + id="tspan1440-5">VUpdate</tspan><tspan + sodipodi:role="line" + x="135.78951" + y="74.75" + style="font-weight:bold;text-align:center;text-anchor:middle;stroke-width:0.26458332" + id="tspan1465">Offset</tspan></text> + <text + xml:space="preserve" + style="font-style:normal;font-weight:normal;font-size:3.17499995px;line-height:1.25;font-family:sans-serif;letter-spacing:0px;word-spacing:0px;fill:#000000;fill-opacity:1;stroke:none;stroke-width:0.26458332" + x="137.39433" + y="48.291664" + id="text1479"><tspan + sodipodi:role="line" + id="tspan1477" + x="137.39433" + y="48.291664" + style="font-weight:bold;stroke-width:0.26458332">VSTARTUP_START</tspan></text> + <text + xml:space="preserve" + style="font-style:normal;font-weight:normal;font-size:3.17499995px;line-height:1.25;font-family:sans-serif;letter-spacing:0px;word-spacing:0px;fill:#000000;fill-opacity:1;stroke:none;stroke-width:0.26458332" + x="-5.4806676" + y="22.778271" + id="text1479-1"><tspan + sodipodi:role="line" + id="tspan1477-2" + x="-5.4806676" + y="22.778271" + style="font-weight:bold;font-size:4.93888903px;stroke-width:0.26458332">VSYNC</tspan></text> + <text + xml:space="preserve" + style="font-style:normal;font-weight:normal;font-size:3.17499995px;line-height:1.25;font-family:sans-serif;letter-spacing:0px;word-spacing:0px;fill:#000000;fill-opacity:1;stroke:none;stroke-width:0.26458332" + x="-9.3767252" + y="45.64584" + id="text1479-1-7"><tspan + sodipodi:role="line" + id="tspan1477-2-0" + x="-9.3767252" + y="45.64584" + style="font-weight:bold;font-size:5.64444447px;stroke-width:0.26458332">VBlank</tspan></text> + <text + xml:space="preserve" + style="font-style:normal;font-weight:normal;font-size:3.17499995px;line-height:1.25;font-family:sans-serif;letter-spacing:0px;word-spacing:0px;fill:#000000;fill-opacity:1;stroke:none;stroke-width:0.26458332" + x="-15.310558" + y="64.92263" + id="text1479-1-7-9"><tspan + sodipodi:role="line" + id="tspan1477-2-0-3" + x="-15.310558" + y="64.92263" + style="font-weight:bold;font-size:5.64444447px;stroke-width:0.26458332">VStartup</tspan></text> + <text + xml:space="preserve" + style="font-style:normal;font-weight:normal;font-size:3.17499995px;line-height:1.25;font-family:sans-serif;letter-spacing:0px;word-spacing:0px;fill:#000000;fill-opacity:1;stroke:none;stroke-width:0.26458332" + x="-14.17781" + y="85.144356" + id="text1479-1-7-9-6"><tspan + sodipodi:role="line" + id="tspan1477-2-0-3-0" + x="-14.17781" + y="85.144356" + style="font-weight:bold;font-size:5.64444447px;stroke-width:0.26458332">VUpdate</tspan></text> + <text + xml:space="preserve" + style="font-style:normal;font-weight:normal;font-size:3.17499995px;line-height:1.25;font-family:sans-serif;letter-spacing:0px;word-spacing:0px;fill:#000000;fill-opacity:1;stroke:none;stroke-width:0.26458332" + x="-11.052421" + y="101.39733" + id="text1479-1-7-9-6-6"><tspan + sodipodi:role="line" + id="tspan1477-2-0-3-0-2" + x="-11.052421" + y="101.39733" + style="font-weight:bold;font-size:5.64444447px;stroke-width:0.26458332">VReady</tspan></text> + <g + id="g5189" + transform="translate(269.875,-14.287499)"> + <path + sodipodi:nodetypes="cc" + inkscape:connector-curvature="0" + id="path5143" + d="m -202.40625,45.645828 3.96875,-7.9375" + style="fill:none;stroke:#000000;stroke-width:0.5291667;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:none;stroke-opacity:1" /> + <path + sodipodi:nodetypes="cc" + inkscape:connector-curvature="0" + id="path5143-2" + d="m -199.76042,45.645828 3.96874,-7.937499" + style="fill:none;stroke:#000000;stroke-width:0.52916676;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:none;stroke-opacity:1" /> + </g> + <g + id="g5189-3" + transform="translate(268.55209,7.9375003)"> + <path + sodipodi:nodetypes="cc" + inkscape:connector-curvature="0" + id="path5143-6" + d="m -202.40625,45.645828 3.96875,-7.9375" + style="fill:none;stroke:#000000;stroke-width:0.5291667;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:none;stroke-opacity:1" /> + <path + sodipodi:nodetypes="cc" + inkscape:connector-curvature="0" + id="path5143-2-1" + d="m -199.76042,45.645828 3.96874,-7.937499" + style="fill:none;stroke:#000000;stroke-width:0.52916676;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:none;stroke-opacity:1" /> + </g> + </g> +</svg> diff --git a/Documentation/gpu/amdgpu/display/index.rst b/Documentation/gpu/amdgpu/display/index.rst new file mode 100644 index 000000000000..c1fb2fb3c710 --- /dev/null +++ b/Documentation/gpu/amdgpu/display/index.rst @@ -0,0 +1,31 @@ +.. _amdgpu-display-core: + +=================================== +drm/amd/display - Display Core (DC) +=================================== + +AMD display engine is partially shared with other operating systems; for this +reason, our Display Core Driver is divided into two pieces: + +1. **Display Core (DC)** contains the OS-agnostic components. Things like + hardware programming and resource management are handled here. +2. **Display Manager (DM)** contains the OS-dependent components. Hooks to the + amdgpu base driver and DRM are implemented here. + +The display pipe is responsible for "scanning out" a rendered frame from the +GPU memory (also called VRAM, FrameBuffer, etc.) to a display. In other words, +it would: + +1. Read frame information from memory; +2. Perform required transformation; +3. Send pixel data to sink devices. + +If you want to learn more about our driver details, take a look at the below +table of content: + +.. toctree:: + + display-manager.rst + dc-debug.rst + dcn-overview.rst + dc-glossary.rst diff --git a/Documentation/gpu/amdgpu/driver-core.rst b/Documentation/gpu/amdgpu/driver-core.rst new file mode 100644 index 000000000000..ebf5932845a9 --- /dev/null +++ b/Documentation/gpu/amdgpu/driver-core.rst @@ -0,0 +1,182 @@ +============================ + Core Driver Infrastructure +============================ + +GPU Hardware Structure +====================== + +Each ASIC is a collection of hardware blocks. We refer to them as +"IPs" (Intellectual Property blocks). Each IP encapsulates certain +functionality. IPs are versioned and can also be mixed and matched. +E.g., you might have two different ASICs that both have System DMA (SDMA) 5.x IPs. +The driver is arranged by IPs. There are driver components to handle +the initialization and operation of each IP. There are also a bunch +of smaller IPs that don't really need much if any driver interaction. +Those end up getting lumped into the common stuff in the soc files. +The soc files (e.g., vi.c, soc15.c nv.c) contain code for aspects of +the SoC itself rather than specific IPs. E.g., things like GPU resets +and register access functions are SoC dependent. + +An APU contains more than just CPU and GPU, it also contains all of +the platform stuff (audio, usb, gpio, etc.). Also, a lot of +components are shared between the CPU, platform, and the GPU (e.g., +SMU, PSP, etc.). Specific components (CPU, GPU, etc.) usually have +their interface to interact with those common components. For things +like S0i3 there is a ton of coordination required across all the +components, but that is probably a bit beyond the scope of this +section. + +With respect to the GPU, we have the following major IPs: + +GMC (Graphics Memory Controller) + This was a dedicated IP on older pre-vega chips, but has since + become somewhat decentralized on vega and newer chips. They now + have dedicated memory hubs for specific IPs or groups of IPs. We + still treat it as a single component in the driver however since + the programming model is still pretty similar. This is how the + different IPs on the GPU get the memory (VRAM or system memory). + It also provides the support for per process GPU virtual address + spaces. + +IH (Interrupt Handler) + This is the interrupt controller on the GPU. All of the IPs feed + their interrupts into this IP and it aggregates them into a set of + ring buffers that the driver can parse to handle interrupts from + different IPs. + +PSP (Platform Security Processor) + This handles security policy for the SoC and executes trusted + applications, and validates and loads firmwares for other blocks. + +SMU (System Management Unit) + This is the power management microcontroller. It manages the entire + SoC. The driver interacts with it to control power management + features like clocks, voltages, power rails, etc. + +DCN (Display Controller Next) + This is the display controller. It handles the display hardware. + It is described in more details in :ref:`Display Core <amdgpu-display-core>`. + +SDMA (System DMA) + This is a multi-purpose DMA engine. The kernel driver uses it for + various things including paging and GPU page table updates. It's also + exposed to userspace for use by user mode drivers (OpenGL, Vulkan, + etc.) + +GC (Graphics and Compute) + This is the graphics and compute engine, i.e., the block that + encompasses the 3D pipeline and and shader blocks. This is by far the + largest block on the GPU. The 3D pipeline has tons of sub-blocks. In + addition to that, it also contains the CP microcontrollers (ME, PFP, + CE, MEC) and the RLC microcontroller. It's exposed to userspace for + user mode drivers (OpenGL, Vulkan, OpenCL, etc.) + +VCN (Video Core Next) + This is the multi-media engine. It handles video and image encode and + decode. It's exposed to userspace for user mode drivers (VA-API, + OpenMAX, etc.) + +Graphics and Compute Microcontrollers +------------------------------------- + +CP (Command Processor) + The name for the hardware block that encompasses the front end of the + GFX/Compute pipeline. Consists mainly of a bunch of microcontrollers + (PFP, ME, CE, MEC). The firmware that runs on these microcontrollers + provides the driver interface to interact with the GFX/Compute engine. + + MEC (MicroEngine Compute) + This is the microcontroller that controls the compute queues on the + GFX/compute engine. + + MES (MicroEngine Scheduler) + This is a new engine for managing queues. This is currently unused. + +RLC (RunList Controller) + This is another microcontroller in the GFX/Compute engine. It handles + power management related functionality within the GFX/Compute engine. + The name is a vestige of old hardware where it was originally added + and doesn't really have much relation to what the engine does now. + +Driver Structure +================ + +In general, the driver has a list of all of the IPs on a particular +SoC and for things like init/fini/suspend/resume, more or less just +walks the list and handles each IP. + +Some useful constructs: + +KIQ (Kernel Interface Queue) + This is a control queue used by the kernel driver to manage other gfx + and compute queues on the GFX/compute engine. You can use it to + map/unmap additional queues, etc. + +IB (Indirect Buffer) + A command buffer for a particular engine. Rather than writing + commands directly to the queue, you can write the commands into a + piece of memory and then put a pointer to the memory into the queue. + The hardware will then follow the pointer and execute the commands in + the memory, then returning to the rest of the commands in the ring. + +.. _amdgpu_memory_domains: + +Memory Domains +============== + +.. kernel-doc:: include/uapi/drm/amdgpu_drm.h + :doc: memory domains + +Buffer Objects +============== + +.. kernel-doc:: drivers/gpu/drm/amd/amdgpu/amdgpu_object.c + :doc: amdgpu_object + +.. kernel-doc:: drivers/gpu/drm/amd/amdgpu/amdgpu_object.c + :internal: + +PRIME Buffer Sharing +==================== + +.. kernel-doc:: drivers/gpu/drm/amd/amdgpu/amdgpu_dma_buf.c + :doc: PRIME Buffer Sharing + +.. kernel-doc:: drivers/gpu/drm/amd/amdgpu/amdgpu_dma_buf.c + :internal: + +MMU Notifier +============ + +.. kernel-doc:: drivers/gpu/drm/amd/amdgpu/amdgpu_mn.c + :doc: MMU Notifier + +.. kernel-doc:: drivers/gpu/drm/amd/amdgpu/amdgpu_mn.c + :internal: + +AMDGPU Virtual Memory +===================== + +.. kernel-doc:: drivers/gpu/drm/amd/amdgpu/amdgpu_vm.c + :doc: GPUVM + +.. kernel-doc:: drivers/gpu/drm/amd/amdgpu/amdgpu_vm.c + :internal: + +Interrupt Handling +================== + +.. kernel-doc:: drivers/gpu/drm/amd/amdgpu/amdgpu_irq.c + :doc: Interrupt Handling + +.. kernel-doc:: drivers/gpu/drm/amd/amdgpu/amdgpu_irq.c + :internal: + +IP Blocks +========= + +.. kernel-doc:: drivers/gpu/drm/amd/include/amd_shared.h + :doc: IP Blocks + +.. kernel-doc:: drivers/gpu/drm/amd/include/amd_shared.h + :identifiers: amd_ip_block_type amd_ip_funcs diff --git a/Documentation/gpu/amdgpu/driver-misc.rst b/Documentation/gpu/amdgpu/driver-misc.rst new file mode 100644 index 000000000000..e3d6b2fa2493 --- /dev/null +++ b/Documentation/gpu/amdgpu/driver-misc.rst @@ -0,0 +1,112 @@ +================================ + Misc AMDGPU driver information +================================ + +GPU Product Information +======================= + +Information about the GPU can be obtained on certain cards +via sysfs + +product_name +------------ + +.. kernel-doc:: drivers/gpu/drm/amd/amdgpu/amdgpu_device.c + :doc: product_name + +product_number +-------------- + +.. kernel-doc:: drivers/gpu/drm/amd/amdgpu/amdgpu_device.c + :doc: product_name + +serial_number +------------- + +.. kernel-doc:: drivers/gpu/drm/amd/amdgpu/amdgpu_device.c + :doc: serial_number + +unique_id +--------- + +.. kernel-doc:: drivers/gpu/drm/amd/pm/amdgpu_pm.c + :doc: unique_id + +GPU Memory Usage Information +============================ + +Various memory accounting can be accessed via sysfs + +mem_info_vram_total +------------------- + +.. kernel-doc:: drivers/gpu/drm/amd/amdgpu/amdgpu_vram_mgr.c + :doc: mem_info_vram_total + +mem_info_vram_used +------------------ + +.. kernel-doc:: drivers/gpu/drm/amd/amdgpu/amdgpu_vram_mgr.c + :doc: mem_info_vram_used + +mem_info_vis_vram_total +----------------------- + +.. kernel-doc:: drivers/gpu/drm/amd/amdgpu/amdgpu_vram_mgr.c + :doc: mem_info_vis_vram_total + +mem_info_vis_vram_used +---------------------- + +.. kernel-doc:: drivers/gpu/drm/amd/amdgpu/amdgpu_vram_mgr.c + :doc: mem_info_vis_vram_used + +mem_info_gtt_total +------------------ + +.. kernel-doc:: drivers/gpu/drm/amd/amdgpu/amdgpu_gtt_mgr.c + :doc: mem_info_gtt_total + +mem_info_gtt_used +----------------- + +.. kernel-doc:: drivers/gpu/drm/amd/amdgpu/amdgpu_gtt_mgr.c + :doc: mem_info_gtt_used + +PCIe Accounting Information +=========================== + +pcie_bw +------- + +.. kernel-doc:: drivers/gpu/drm/amd/pm/amdgpu_pm.c + :doc: pcie_bw + +pcie_replay_count +----------------- + +.. kernel-doc:: drivers/gpu/drm/amd/amdgpu/amdgpu_device.c + :doc: pcie_replay_count + +GPU SmartShift Information +========================== + +GPU SmartShift information via sysfs + +smartshift_apu_power +-------------------- + +.. kernel-doc:: drivers/gpu/drm/amd/pm/amdgpu_pm.c + :doc: smartshift_apu_power + +smartshift_dgpu_power +--------------------- + +.. kernel-doc:: drivers/gpu/drm/amd/pm/amdgpu_pm.c + :doc: smartshift_dgpu_power + +smartshift_bias +--------------- + +.. kernel-doc:: drivers/gpu/drm/amd/pm/amdgpu_pm.c + :doc: smartshift_bias diff --git a/Documentation/gpu/amdgpu/index.rst b/Documentation/gpu/amdgpu/index.rst new file mode 100644 index 000000000000..a24e1cfa7407 --- /dev/null +++ b/Documentation/gpu/amdgpu/index.rst @@ -0,0 +1,17 @@ +========================== + drm/amdgpu AMDgpu driver +========================== + +The drm/amdgpu driver supports all AMD Radeon GPUs based on the Graphics Core +Next (GCN) architecture. + +.. toctree:: + + module-parameters + driver-core + display/index + xgmi + ras + thermal + driver-misc + amdgpu-glossary diff --git a/Documentation/gpu/amdgpu/module-parameters.rst b/Documentation/gpu/amdgpu/module-parameters.rst new file mode 100644 index 000000000000..ea538c8dda35 --- /dev/null +++ b/Documentation/gpu/amdgpu/module-parameters.rst @@ -0,0 +1,7 @@ +=================== + Module Parameters +=================== + +The amdgpu driver supports the following module parameters: + +.. kernel-doc:: drivers/gpu/drm/amd/amdgpu/amdgpu_drv.c diff --git a/Documentation/gpu/amdgpu/ras.rst b/Documentation/gpu/amdgpu/ras.rst new file mode 100644 index 000000000000..047f76e395cf --- /dev/null +++ b/Documentation/gpu/amdgpu/ras.rst @@ -0,0 +1,62 @@ +==================== + AMDGPU RAS Support +==================== + +The AMDGPU RAS interfaces are exposed via sysfs (for informational queries) and +debugfs (for error injection). + +RAS debugfs/sysfs Control and Error Injection Interfaces +======================================================== + +.. kernel-doc:: drivers/gpu/drm/amd/amdgpu/amdgpu_ras.c + :doc: AMDGPU RAS debugfs control interface + +RAS Reboot Behavior for Unrecoverable Errors +============================================ + +.. kernel-doc:: drivers/gpu/drm/amd/amdgpu/amdgpu_ras.c + :doc: AMDGPU RAS Reboot Behavior for Unrecoverable Errors + +RAS Error Count sysfs Interface +=============================== + +.. kernel-doc:: drivers/gpu/drm/amd/amdgpu/amdgpu_ras.c + :doc: AMDGPU RAS sysfs Error Count Interface + +RAS EEPROM debugfs Interface +============================ + +.. kernel-doc:: drivers/gpu/drm/amd/amdgpu/amdgpu_ras.c + :doc: AMDGPU RAS debugfs EEPROM table reset interface + +RAS VRAM Bad Pages sysfs Interface +================================== + +.. kernel-doc:: drivers/gpu/drm/amd/amdgpu/amdgpu_ras.c + :doc: AMDGPU RAS sysfs gpu_vram_bad_pages Interface + +Sample Code +=========== +Sample code for testing error injection can be found here: +https://cgit.freedesktop.org/mesa/drm/tree/tests/amdgpu/ras_tests.c + +This is part of the libdrm amdgpu unit tests which cover several areas of the GPU. +There are four sets of tests: + +RAS Basic Test + +The test verifies the RAS feature enabled status and makes sure the necessary sysfs and debugfs files +are present. + +RAS Query Test + +This test checks the RAS availability and enablement status for each supported IP block as well as +the error counts. + +RAS Inject Test + +This test injects errors for each IP. + +RAS Disable Test + +This test tests disabling of RAS features for each IP block. diff --git a/Documentation/gpu/amdgpu/thermal.rst b/Documentation/gpu/amdgpu/thermal.rst new file mode 100644 index 000000000000..8aeb0186c9ef --- /dev/null +++ b/Documentation/gpu/amdgpu/thermal.rst @@ -0,0 +1,65 @@ +=========================================== + GPU Power/Thermal Controls and Monitoring +=========================================== + +HWMON Interfaces +================ + +.. kernel-doc:: drivers/gpu/drm/amd/pm/amdgpu_pm.c + :doc: hwmon + +GPU sysfs Power State Interfaces +================================ + +GPU power controls are exposed via sysfs files. + +power_dpm_state +--------------- + +.. kernel-doc:: drivers/gpu/drm/amd/pm/amdgpu_pm.c + :doc: power_dpm_state + +power_dpm_force_performance_level +--------------------------------- + +.. kernel-doc:: drivers/gpu/drm/amd/pm/amdgpu_pm.c + :doc: power_dpm_force_performance_level + +pp_table +-------- + +.. kernel-doc:: drivers/gpu/drm/amd/pm/amdgpu_pm.c + :doc: pp_table + +pp_od_clk_voltage +----------------- + +.. kernel-doc:: drivers/gpu/drm/amd/pm/amdgpu_pm.c + :doc: pp_od_clk_voltage + +pp_dpm_* +-------- + +.. kernel-doc:: drivers/gpu/drm/amd/pm/amdgpu_pm.c + :doc: pp_dpm_sclk pp_dpm_mclk pp_dpm_socclk pp_dpm_fclk pp_dpm_dcefclk pp_dpm_pcie + +pp_power_profile_mode +--------------------- + +.. kernel-doc:: drivers/gpu/drm/amd/pm/amdgpu_pm.c + :doc: pp_power_profile_mode + +\*_busy_percent +--------------- + +.. kernel-doc:: drivers/gpu/drm/amd/pm/amdgpu_pm.c + :doc: gpu_busy_percent + +.. kernel-doc:: drivers/gpu/drm/amd/pm/amdgpu_pm.c + :doc: mem_busy_percent + +gpu_metrics +----------- + +.. kernel-doc:: drivers/gpu/drm/amd/pm/amdgpu_pm.c + :doc: gpu_metrics diff --git a/Documentation/gpu/amdgpu/xgmi.rst b/Documentation/gpu/amdgpu/xgmi.rst new file mode 100644 index 000000000000..23f2856f4524 --- /dev/null +++ b/Documentation/gpu/amdgpu/xgmi.rst @@ -0,0 +1,5 @@ +===================== + AMDGPU XGMI Support +===================== + +.. kernel-doc:: drivers/gpu/drm/amd/amdgpu/amdgpu_xgmi.c diff --git a/Documentation/gpu/drivers.rst b/Documentation/gpu/drivers.rst index b4a0ed3ca961..3a52f48215a3 100644 --- a/Documentation/gpu/drivers.rst +++ b/Documentation/gpu/drivers.rst @@ -4,8 +4,7 @@ GPU Driver Documentation .. toctree:: - amdgpu - amdgpu-dc + amdgpu/index i915 mcde meson diff --git a/Documentation/gpu/drm-kms-helpers.rst b/Documentation/gpu/drm-kms-helpers.rst index ec2f65b31930..5bb55ec1b9b5 100644 --- a/Documentation/gpu/drm-kms-helpers.rst +++ b/Documentation/gpu/drm-kms-helpers.rst @@ -435,3 +435,18 @@ Legacy CRTC/Modeset Helper Functions Reference .. kernel-doc:: drivers/gpu/drm/drm_crtc_helper.c :export: + +Privacy-screen class +==================== + +.. kernel-doc:: drivers/gpu/drm/drm_privacy_screen.c + :doc: overview + +.. kernel-doc:: include/drm/drm_privacy_screen_driver.h + :internal: + +.. kernel-doc:: include/drm/drm_privacy_screen_machine.h + :internal: + +.. kernel-doc:: drivers/gpu/drm/drm_privacy_screen.c + :export: diff --git a/Documentation/gpu/drm-kms.rst b/Documentation/gpu/drm-kms.rst index 1ef7951ded5e..d14bf1c35d7e 100644 --- a/Documentation/gpu/drm-kms.rst +++ b/Documentation/gpu/drm-kms.rst @@ -506,6 +506,8 @@ Property Types and Blob Property Support .. kernel-doc:: drivers/gpu/drm/drm_property.c :export: +.. _standard_connector_properties: + Standard Connector Properties ----------------------------- diff --git a/Documentation/gpu/todo.rst b/Documentation/gpu/todo.rst index 60d1d7ee0719..da138dd39883 100644 --- a/Documentation/gpu/todo.rst +++ b/Documentation/gpu/todo.rst @@ -268,17 +268,6 @@ Contact: Daniel Vetter Level: Intermediate -Clean up mmap forwarding ------------------------- - -A lot of drivers forward gem mmap calls to dma-buf mmap for imported buffers. -And also a lot of them forward dma-buf mmap to the gem mmap implementations. -There's drm_gem_prime_mmap() for this now, but still needs to be rolled out. - -Contact: Daniel Vetter - -Level: Intermediate - Generic fbdev defio support --------------------------- @@ -463,6 +452,21 @@ Contact: Thomas Zimmermann <tzimmermann@suse.de>, Christian König, Daniel Vette Level: Intermediate +Review all drivers for setting struct drm_mode_config.{max_width,max_height} correctly +-------------------------------------------------------------------------------------- + +The values in struct drm_mode_config.{max_width,max_height} describe the +maximum supported framebuffer size. It's the virtual screen size, but many +drivers treat it like limitations of the physical resolution. + +The maximum width depends on the hardware's maximum scanline pitch. The +maximum height depends on the amount of addressable video memory. Review all +drivers to initialize the fields to the correct values. + +Contact: Thomas Zimmermann <tzimmermann@suse.de> + +Level: Intermediate + Core refactorings ================= @@ -642,6 +646,17 @@ See drivers/gpu/drm/amd/display/TODO for tasks. Contact: Harry Wentland, Alex Deucher +vmwgfx: Replace hashtable with Linux' implementation +---------------------------------------------------- + +The vmwgfx driver uses its own hashtable implementation. Replace the +code with Linux' implementation and update the callers. It's mostly a +refactoring task, but the interfaces are different. + +Contact: Zack Rusin, Thomas Zimmermann <tzimmermann@suse.de> + +Level: Intermediate + Bootsplash ========== diff --git a/Documentation/hwmon/asus_wmi_ec_sensors.rst b/Documentation/hwmon/asus_wmi_ec_sensors.rst new file mode 100644 index 000000000000..1b287f229e86 --- /dev/null +++ b/Documentation/hwmon/asus_wmi_ec_sensors.rst @@ -0,0 +1,38 @@ +.. SPDX-License-Identifier: GPL-2.0-or-later + +Kernel driver asus_wmi_ec_sensors +================================= + +Supported boards: + * PRIME X570-PRO, + * Pro WS X570-ACE, + * ROG CROSSHAIR VIII DARK HERO, + * ROG CROSSHAIR VIII FORMULA, + * ROG CROSSHAIR VIII HERO, + * ROG STRIX B550-E GAMING, + * ROG STRIX B550-I GAMING, + * ROG STRIX X570-E GAMING. + +Authors: + - Eugene Shalygin <eugene.shalygin@gmail.com> + +Description: +------------ +ASUS mainboards publish hardware monitoring information via Super I/O +chip and the ACPI embedded controller (EC) registers. Some of the sensors +are only available via the EC. + +ASUS WMI interface provides a method (BREC) to read data from EC registers, +which is utilized by this driver to publish those sensor readings to the +HWMON system. The driver is aware of and reads the following sensors: + +1. Chipset (PCH) temperature +2. CPU package temperature +3. Motherboard temperature +4. Readings from the T_Sensor header +5. VRM temperature +6. CPU_Opt fan RPM +7. Chipset fan RPM +8. Readings from the "Water flow meter" header (RPM) +9. Readings from the "Water In" and "Water Out" temperature headers +10. CPU current diff --git a/Documentation/hwmon/asus_wmi_sensors.rst b/Documentation/hwmon/asus_wmi_sensors.rst new file mode 100644 index 000000000000..8f2096cf5183 --- /dev/null +++ b/Documentation/hwmon/asus_wmi_sensors.rst @@ -0,0 +1,78 @@ +.. SPDX-License-Identifier: GPL-2.0-or-later + +Kernel driver asus_wmi_sensors +================================= + +Supported boards: + * PRIME X399-A, + * PRIME X470-PRO, + * ROG CROSSHAIR VI EXTREME, + * ROG CROSSHAIR VI HERO, + * ROG CROSSHAIR VI HERO (WI-FI AC), + * ROG CROSSHAIR VII HERO, + * ROG CROSSHAIR VII HERO (WI-FI), + * ROG STRIX B450-E GAMING, + * ROG STRIX B450-F GAMING, + * ROG STRIX B450-I GAMING, + * ROG STRIX X399-E GAMING, + * ROG STRIX X470-F GAMING, + * ROG STRIX X470-I GAMING, + * ROG ZENITH EXTREME, + * ROG ZENITH EXTREME ALPHA. + +Authors: + - Ed Brindley <kernel@maidavale.org> + +Description: +------------ +ASUS mainboards publish hardware monitoring information via WMI interface. + +ASUS WMI interface provides a methods to get list of sensors and values of +such, which is utilized by this driver to publish those sensor readings to the +HWMON system. + +The driver is aware of and reads the following sensors: + * CPU Core Voltage, + * CPU SOC Voltage, + * DRAM Voltage, + * VDDP Voltage, + * 1.8V PLL Voltage, + * +12V Voltage, + * +5V Voltage, + * 3VSB Voltage, + * VBAT Voltage, + * AVCC3 Voltage, + * SB 1.05V Voltage, + * CPU Core Voltage, + * CPU SOC Voltage, + * DRAM Voltage, + * CPU Fan RPM, + * Chassis Fan 1 RPM, + * Chassis Fan 2 RPM, + * Chassis Fan 3 RPM, + * HAMP Fan RPM, + * Water Pump RPM, + * CPU OPT RPM, + * Water Flow RPM, + * AIO Pump RPM, + * CPU Temperature, + * CPU Socket Temperature, + * Motherboard Temperature, + * Chipset Temperature, + * Tsensor 1 Temperature, + * CPU VRM Temperature, + * Water In, + * Water Out, + * CPU VRM Output Current. + +Known Issues: + * The WMI implementation in some of Asus' BIOSes is buggy. This can result in + fans stopping, fans getting stuck at max speed, or temperature readouts + getting stuck. This is not an issue with the driver, but the BIOS. The Prime + X470 Pro seems particularly bad for this. The more frequently the WMI + interface is polled the greater the potential for this to happen. Until you + have subjected your computer to an extended soak test while polling the + sensors frequently, don't leave you computer unattended. Upgrading to new + BIOS version with method version greater than or equal to two should + rectify the issue. + * A few boards report 12v voltages to be ~10v. diff --git a/Documentation/hwmon/ina238.rst b/Documentation/hwmon/ina238.rst new file mode 100644 index 000000000000..d9f479984420 --- /dev/null +++ b/Documentation/hwmon/ina238.rst @@ -0,0 +1,56 @@ +.. SPDX-License-Identifier: GPL-2.0-only + +Kernel driver ina238 +==================== + +Supported chips: + + * Texas Instruments INA238 + + Prefix: 'ina238' + + Addresses: I2C 0x40 - 0x4f + + Datasheet: + https://www.ti.com/lit/gpn/ina238 + +Author: Nathan Rossi <nathan.rossi@digi.com> + +Description +----------- + +The INA238 is a current shunt, power and temperature monitor with an I2C +interface. It includes a number of programmable functions including alerts, +conversion rate, sample averaging and selectable shunt voltage accuracy. + +The shunt value in micro-ohms can be set via platform data or device tree at +compile-time or via the shunt_resistor attribute in sysfs at run-time. Please +refer to the Documentation/devicetree/bindings/hwmon/ti,ina2xx.yaml for bindings +if the device tree is used. + +Sysfs entries +------------- + +======================= ======================================================= +in0_input Shunt voltage (mV) +in0_min Minimum shunt voltage threshold (mV) +in0_min_alarm Minimum shunt voltage alarm +in0_max Maximum shunt voltage threshold (mV) +in0_max_alarm Maximum shunt voltage alarm + +in1_input Bus voltage (mV) +in1_min Minimum bus voltage threshold (mV) +in1_min_alarm Minimum shunt voltage alarm +in1_max Maximum bus voltage threshold (mV) +in1_max_alarm Maximum shunt voltage alarm + +power1_input Power measurement (uW) +power1_max Maximum power threshold (uW) +power1_max_alarm Maximum power alarm + +curr1_input Current measurement (mA) + +temp1_input Die temperature measurement (mC) +temp1_max Maximum die temperature threshold (mC) +temp1_max_alarm Maximum die temperature alarm +======================= ======================================================= diff --git a/Documentation/hwmon/index.rst b/Documentation/hwmon/index.rst index 7046bf1870d9..df20022c741f 100644 --- a/Documentation/hwmon/index.rst +++ b/Documentation/hwmon/index.rst @@ -43,6 +43,8 @@ Hardware Monitoring Kernel Drivers asb100 asc7621 aspeed-pwm-tacho + asus_wmi_ec_sensors + asus_wmi_sensors bcm54140 bel-pfe bpa-rs600 @@ -76,6 +78,7 @@ Hardware Monitoring Kernel Drivers ibmpowernv ina209 ina2xx + ina238 ina3221 intel-m10-bmc-hwmon ir35221 @@ -142,6 +145,7 @@ Hardware Monitoring Kernel Drivers mlxreg-fan mp2888 mp2975 + mp5023 nct6683 nct6775 nct7802 @@ -150,6 +154,7 @@ Hardware Monitoring Kernel Drivers nsa320 ntc_thermistor nzxt-kraken2 + nzxt-smart2 occ pc87360 pc87427 diff --git a/Documentation/hwmon/ir38064.rst b/Documentation/hwmon/ir38064.rst index c455d755a267..e1148f21ea2a 100644 --- a/Documentation/hwmon/ir38064.rst +++ b/Documentation/hwmon/ir38064.rst @@ -3,14 +3,38 @@ Kernel driver ir38064 Supported chips: + * Infineon IR38060 + + Prefix: 'IR38060' + Addresses scanned: - + + Datasheet: Publicly available at the Infineon website + https://www.infineon.com/dgdl/Infineon-IR38060M-DS-v03_16-EN.pdf?fileId=5546d4625c167129015c3291ea9a4cee + * Infineon IR38064 Prefix: 'ir38064' Addresses scanned: - - Datasheet: Publicly available at the Infineon webiste + Datasheet: Publicly available at the Infineon website https://www.infineon.com/dgdl/Infineon-IR38064MTRPBF-DS-v03_07-EN.pdf?fileId=5546d462584d1d4a0158db0d9efb67ca + * Infineon IR38164 + + Prefix: 'ir38164' + Addresses scanned: - + + Datasheet: Publicly available at the Infineon website + https://www.infineon.com/dgdl/Infineon-IR38164M-DS-v02_02-EN.pdf?fileId=5546d462636cc8fb01640046efea1248 + + * Infineon ir38263 + + Prefix: 'ir38263' + Addresses scanned: - + + Datasheet: Publicly available at the Infineon website + https://www.infineon.com/dgdl/Infineon-IR38263M-DataSheet-v03_05-EN.pdf?fileId=5546d4625b62cd8a015bcf81f90a6e52 + Authors: - Maxim Sloyko <maxims@google.com> - Patrick Venture <venture@google.com> @@ -18,7 +42,7 @@ Authors: Description ----------- -IR38064 is a Single-input Voltage, Synchronous Buck Regulator, DC-DC Converter. +IR38x6x are a Single-input Voltage, Synchronous Buck Regulator, DC-DC Converter. Usage Notes ----------- diff --git a/Documentation/hwmon/mp5023.rst b/Documentation/hwmon/mp5023.rst new file mode 100644 index 000000000000..af5ab1345a91 --- /dev/null +++ b/Documentation/hwmon/mp5023.rst @@ -0,0 +1,84 @@ +.. SPDX-License-Identifier: GPL-2.0 + +Kernel driver mp5023 +==================== + +Supported chips: + + * MPS MP5023 + + Prefix: 'mp5023' + + * Datasheet + + Publicly available at the MPS website : https://www.monolithicpower.com/en/mp5023.html + +Author: + + Howard Chiu <howard.chiu@quantatw.com> + +Description +----------- + +This driver implements support for Monolithic Power Systems, Inc. (MPS) +MP5023 Hot-Swap Controller. + +Device complaint with: + +- PMBus rev 1.3 interface. + +Device supports direct format for reading input voltage, output voltage, +output current, input power and temperature. + +The driver exports the following attributes via the 'sysfs' files +for input voltage: + +**in1_input** + +**in1_label** + +**in1_max** + +**in1_max_alarm** + +**in1_min** + +**in1_min_alarm** + +The driver provides the following attributes for output voltage: + +**in2_input** + +**in2_label** + +**in2_alarm** + +The driver provides the following attributes for output current: + +**curr1_input** + +**curr1_label** + +**curr1_alarm** + +**curr1_max** + +The driver provides the following attributes for input power: + +**power1_input** + +**power1_label** + +**power1_alarm** + +The driver provides the following attributes for temperature: + +**temp1_input** + +**temp1_max** + +**temp1_max_alarm** + +**temp1_crit** + +**temp1_crit_alarm** diff --git a/Documentation/hwmon/nzxt-smart2.rst b/Documentation/hwmon/nzxt-smart2.rst new file mode 100644 index 000000000000..d9d1b2742665 --- /dev/null +++ b/Documentation/hwmon/nzxt-smart2.rst @@ -0,0 +1,62 @@ +.. SPDX-License-Identifier: GPL-2.0-or-later + +Kernel driver nzxt-smart2 +========================= + +Supported devices: + +- NZXT RGB & Fan controller +- NZXT Smart Device v2 + +Description +----------- + +This driver implements monitoring and control of fans plugged into the device. +Besides typical speed monitoring and PWM duty cycle control, voltage and current +is reported for every fan. + +The device also has two connectors for RGB LEDs; support for them isn't +implemented (mainly because there is no standardized sysfs interface). + +Also, the device has a noise sensor, but the sensor seems to be completely +useless (and very imprecise), so support for it isn't implemented too. + +Usage Notes +----------- + +The device should be autodetected, and the driver should load automatically. + +If fans are plugged in/unplugged while the system is powered on, the driver +must be reloaded to detect configuration changes; otherwise, new fans can't +be controlled (`pwm*` changes will be ignored). It is necessary because the +device has a dedicated "detect fans" command, and currently, it is executed only +during initialization. Speed, voltage, current monitoring will work even without +reload. As an alternative to reloading the module, a userspace tool (like +`liquidctl`_) can be used to run "detect fans" command through hidraw interface. + +The driver coexists with userspace tools that access the device through hidraw +interface with no known issues. + +.. _liquidctl: https://github.com/liquidctl/liquidctl + +Sysfs entries +------------- + +======================= ======================================================== +fan[1-3]_input Fan speed monitoring (in rpm). +curr[1-3]_input Current supplied to the fan (in milliamperes). +in[0-2]_input Voltage supplied to the fan (in millivolts). +pwm[1-3] Controls fan speed: PWM duty cycle for PWM-controlled + fans, voltage for other fans. Voltage can be changed in + 9-12 V range, but the value of the sysfs attribute is + always in 0-255 range (1 = 9V, 255 = 12V). Setting the + attribute to 0 turns off the fan completely. +pwm[1-3]_enable 1 if the fan can be controlled by writing to the + corresponding pwm* attribute, 0 otherwise. The device + can control only the fans it detected itself, so the + attribute is read-only. +pwm[1-3]_mode Read-only, 1 for PWM-controlled fans, 0 for other fans + (or if no fan connected). +update_interval The interval at which all inputs are updated (in + milliseconds). The default is 1000ms. Minimum is 250ms. +======================= ======================================================== diff --git a/Documentation/i2c/summary.rst b/Documentation/i2c/summary.rst index 136c4e333be7..786c618ba3be 100644 --- a/Documentation/i2c/summary.rst +++ b/Documentation/i2c/summary.rst @@ -11,9 +11,11 @@ systems. Some systems use variants that don't meet branding requirements, and so are not advertised as being I2C but come under different names, e.g. TWI (Two Wire Interface), IIC. -The official I2C specification is the `"I2C-bus specification and user -manual" (UM10204) <https://www.nxp.com/docs/en/user-guide/UM10204.pdf>`_ -published by NXP Semiconductors. +The latest official I2C specification is the `"I2C-bus specification and user +manual" (UM10204) <https://www.nxp.com/webapp/Download?colCode=UM10204>`_ +published by NXP Semiconductors. However, you need to log-in to the site to +access the PDF. An older version of the specification (revision 6) is archived +`here <https://web.archive.org/web/20210813122132/https://www.nxp.com/docs/en/user-guide/UM10204.pdf>`_. SMBus (System Management Bus) is based on the I2C protocol, and is mostly a subset of I2C protocols and signaling. Many I2C devices will work on an diff --git a/Documentation/locking/locktypes.rst b/Documentation/locking/locktypes.rst index ddada4a53749..4fd7b70fcde1 100644 --- a/Documentation/locking/locktypes.rst +++ b/Documentation/locking/locktypes.rst @@ -439,11 +439,9 @@ preemption. The following substitution works on both kernels:: spin_lock(&p->lock); p->count += this_cpu_read(var2); -On a non-PREEMPT_RT kernel migrate_disable() maps to preempt_disable() -which makes the above code fully equivalent. On a PREEMPT_RT kernel migrate_disable() ensures that the task is pinned on the current CPU which in turn guarantees that the per-CPU access to var1 and var2 are staying on -the same CPU. +the same CPU while the task remains preemptible. The migrate_disable() substitution is not valid for the following scenario:: @@ -456,9 +454,8 @@ scenario:: p = this_cpu_ptr(&var1); p->val = func2(); -While correct on a non-PREEMPT_RT kernel, this breaks on PREEMPT_RT because -here migrate_disable() does not protect against reentrancy from a -preempting task. A correct substitution for this case is:: +This breaks because migrate_disable() does not protect against reentrancy from +a preempting task. A correct substitution for this case is:: func() { diff --git a/Documentation/memory-barriers.txt b/Documentation/memory-barriers.txt index 7367ada13208..b12df9137e1c 100644 --- a/Documentation/memory-barriers.txt +++ b/Documentation/memory-barriers.txt @@ -1950,6 +1950,14 @@ There are some more advanced barrier functions: For load from persistent memory, existing read memory barriers are sufficient to ensure read ordering. + (*) io_stop_wc(); + + For memory accesses with write-combining attributes (e.g. those returned + by ioremap_wc(), the CPU may wait for prior accesses to be merged with + subsequent ones. io_stop_wc() can be used to prevent the merging of + write-combining memory accesses before this macro with those after it when + such wait has performance implications. + =============================== IMPLICIT KERNEL MEMORY BARRIERS =============================== diff --git a/Documentation/networking/bonding.rst b/Documentation/networking/bonding.rst index 31cfd7d674a6..ab98373535ea 100644 --- a/Documentation/networking/bonding.rst +++ b/Documentation/networking/bonding.rst @@ -196,11 +196,12 @@ ad_actor_sys_prio ad_actor_system In an AD system, this specifies the mac-address for the actor in - protocol packet exchanges (LACPDUs). The value cannot be NULL or - multicast. It is preferred to have the local-admin bit set for this - mac but driver does not enforce it. If the value is not given then - system defaults to using the masters' mac address as actors' system - address. + protocol packet exchanges (LACPDUs). The value cannot be a multicast + address. If the all-zeroes MAC is specified, bonding will internally + use the MAC of the bond itself. It is preferred to have the + local-admin bit set for this mac but driver does not enforce it. If + the value is not given then system defaults to using the masters' + mac address as actors' system address. This parameter has effect only in 802.3ad mode and is available through SysFs interface. @@ -421,6 +422,17 @@ arp_all_targets consider the slave up only when all of the arp_ip_targets are reachable +arp_missed_max + + Specifies the number of arp_interval monitor checks that must + fail in order for an interface to be marked down by the ARP monitor. + + In order to provide orderly failover semantics, backup interfaces + are permitted an extra monitor check (i.e., they must fail + arp_missed_max + 1 times before being marked down). + + The default value is 2, and the allowable range is 1 - 255. + downdelay Specifies the time, in milliseconds, to wait before disabling diff --git a/Documentation/networking/device_drivers/can/freescale/flexcan.rst b/Documentation/networking/device_drivers/can/freescale/flexcan.rst new file mode 100644 index 000000000000..4e3eec6cecd2 --- /dev/null +++ b/Documentation/networking/device_drivers/can/freescale/flexcan.rst @@ -0,0 +1,54 @@ +.. SPDX-License-Identifier: GPL-2.0+ + +============================= +Flexcan CAN Controller driver +============================= + +Authors: Marc Kleine-Budde <mkl@pengutronix.de>, +Dario Binacchi <dario.binacchi@amarula.solutions.com> + +On/off RTR frames reception +=========================== + +For most flexcan IP cores the driver supports 2 RX modes: + +- FIFO +- mailbox + +The older flexcan cores (integrated into the i.MX25, i.MX28, i.MX35 +and i.MX53 SOCs) only receive RTR frames if the controller is +configured for RX-FIFO mode. + +The RX FIFO mode uses a hardware FIFO with a depth of 6 CAN frames, +while the mailbox mode uses a software FIFO with a depth of up to 62 +CAN frames. With the help of the bigger buffer, the mailbox mode +performs better under high system load situations. + +As reception of RTR frames is part of the CAN standard, all flexcan +cores come up in a mode where RTR reception is possible. + +With the "rx-rtr" private flag the ability to receive RTR frames can +be waived at the expense of losing the ability to receive RTR +messages. This trade off is beneficial in certain use cases. + +"rx-rtr" on + Receive RTR frames. (default) + + The CAN controller can and will receive RTR frames. + + On some IP cores the controller cannot receive RTR frames in the + more performant "RX mailbox" mode and will use "RX FIFO" mode + instead. + +"rx-rtr" off + + Waive ability to receive RTR frames. (not supported on all IP cores) + + This mode activates the "RX mailbox mode" for better performance, on + some IP cores RTR frames cannot be received anymore. + +The setting can only be changed if the interface is down:: + + ip link set dev can0 down + ethtool --set-priv-flags can0 rx-rtr {off|on} + ip link set dev can0 up diff --git a/Documentation/networking/device_drivers/can/index.rst b/Documentation/networking/device_drivers/can/index.rst new file mode 100644 index 000000000000..58b6e0ad3030 --- /dev/null +++ b/Documentation/networking/device_drivers/can/index.rst @@ -0,0 +1,20 @@ +.. SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) + +Controller Area Network (CAN) Device Drivers +============================================ + +Device drivers for CAN devices. + +Contents: + +.. toctree:: + :maxdepth: 2 + + freescale/flexcan + +.. only:: subproject and html + + Indices + ======= + + * :ref:`genindex` diff --git a/Documentation/networking/device_drivers/ethernet/amazon/ena.rst b/Documentation/networking/device_drivers/ethernet/amazon/ena.rst index 01b2a69b0cb0..8bcb173e0353 100644 --- a/Documentation/networking/device_drivers/ethernet/amazon/ena.rst +++ b/Documentation/networking/device_drivers/ethernet/amazon/ena.rst @@ -135,7 +135,7 @@ The ENA driver supports two Queue Operation modes for Tx SQs: - **Low Latency Queue (LLQ) mode or "push-mode":** In this mode the driver pushes the transmit descriptors and the - first 128 bytes of the packet directly to the ENA device memory + first 96 bytes of the packet directly to the ENA device memory space. The rest of the packet payload is fetched by the device. For this operation mode, the driver uses a dedicated PCI device memory BAR, which is mapped with write-combine capability. diff --git a/Documentation/networking/device_drivers/ethernet/freescale/dpaa2/overview.rst b/Documentation/networking/device_drivers/ethernet/freescale/dpaa2/overview.rst index d638b5a8aadd..199647729251 100644 --- a/Documentation/networking/device_drivers/ethernet/freescale/dpaa2/overview.rst +++ b/Documentation/networking/device_drivers/ethernet/freescale/dpaa2/overview.rst @@ -183,6 +183,7 @@ PHY and allows physical transmission and reception of Ethernet frames. IRQ config, enable, reset DPNI (Datapath Network Interface) +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Contains TX/RX queues, network interface configuration, and RX buffer pool configuration mechanisms. The TX/RX queues are in memory and are identified by queue number. diff --git a/Documentation/networking/device_drivers/ethernet/intel/ixgbe.rst b/Documentation/networking/device_drivers/ethernet/intel/ixgbe.rst index f1d5233e5e51..0a233b17c664 100644 --- a/Documentation/networking/device_drivers/ethernet/intel/ixgbe.rst +++ b/Documentation/networking/device_drivers/ethernet/intel/ixgbe.rst @@ -440,6 +440,22 @@ NOTE: For 82599-based network connections, if you are enabling jumbo frames in a virtual function (VF), jumbo frames must first be enabled in the physical function (PF). The VF MTU setting cannot be larger than the PF MTU. +NBASE-T Support +--------------- +The ixgbe driver supports NBASE-T on some devices. However, the advertisement +of NBASE-T speeds is suppressed by default, to accommodate broken network +switches which cannot cope with advertised NBASE-T speeds. Use the ethtool +command to enable advertising NBASE-T speeds on devices which support it:: + + ethtool -s eth? advertise 0x1800000001028 + +On Linux systems with INTERFACES(5), this can be specified as a pre-up command +in /etc/network/interfaces so that the interface is always brought up with +NBASE-T support, e.g.:: + + iface eth? inet dhcp + pre-up ethtool -s eth? advertise 0x1800000001028 || true + Generic Receive Offload, aka GRO -------------------------------- The driver supports the in-kernel software implementation of GRO. GRO has diff --git a/Documentation/networking/device_drivers/index.rst b/Documentation/networking/device_drivers/index.rst index 3a5a1d46e77e..5f5cfdb2a300 100644 --- a/Documentation/networking/device_drivers/index.rst +++ b/Documentation/networking/device_drivers/index.rst @@ -11,6 +11,7 @@ Contents: appletalk/index atm/index cable/index + can/index cellular/index ethernet/index fddi/index diff --git a/Documentation/networking/devlink/devlink-params.rst b/Documentation/networking/devlink/devlink-params.rst index 4878907e9232..4e01dc32bc08 100644 --- a/Documentation/networking/devlink/devlink-params.rst +++ b/Documentation/networking/devlink/devlink-params.rst @@ -109,14 +109,19 @@ own name. - Boolean - When enabled, the device driver will instantiate VDPA networking specific auxiliary device of the devlink device. + * - ``enable_iwarp`` + - Boolean + - Enable handling of iWARP traffic in the device. * - ``internal_err_reset`` - Boolean - When enabled, the device driver will reset the device on internal errors. * - ``max_macs`` - u32 - - Specifies the maximum number of MAC addresses per ethernet port of - this device. + - Typically macvlan, vlan net devices mac are also programmed in their + parent netdevice's Function rx filter. This parameter limit the + maximum number of unicast mac address filters to receive traffic from + per ethernet port of this device. * - ``region_snapshot_enable`` - Boolean - Enable capture of ``devlink-region`` snapshots. @@ -126,3 +131,9 @@ own name. will NACK any attempt of other host to reset the device. This parameter is useful for setups where a device is shared by different hosts, such as multi-host setup. + * - ``io_eq_size`` + - u32 + - Control the size of I/O completion EQs. + * - ``event_eq_size`` + - u32 + - Control the size of asynchronous control events EQ. diff --git a/Documentation/networking/devlink/ice.rst b/Documentation/networking/devlink/ice.rst index 59c78e9717d2..8c082b139bbd 100644 --- a/Documentation/networking/devlink/ice.rst +++ b/Documentation/networking/devlink/ice.rst @@ -26,8 +26,10 @@ The ``ice`` driver reports the following versions * - ``fw.mgmt`` - running - 2.1.7 - - 3-digit version number of the management firmware that controls the - PHY, link, etc. + - 3-digit version number of the management firmware running on the + Embedded Management Processor of the device. It controls the PHY, + link, access to device resources, etc. Intel documentation refers to + this as the EMP firmware. * - ``fw.mgmt.api`` - running - 1.5.1 @@ -119,6 +121,24 @@ preserving settings, and thus ``DEVLINK_FLASH_OVERWRITE_IDENTIFIERS`` on its own will be rejected. If no overwrite mask is provided, the firmware will be instructed to preserve all settings and identifying fields when updating. +Reload +====== + +The ``ice`` driver supports activating new firmware after a flash update +using ``DEVLINK_CMD_RELOAD`` with the ``DEVLINK_RELOAD_ACTION_FW_ACTIVATE`` +action. + +.. code:: shell + + $ devlink dev reload pci/0000:01:00.0 reload action fw_activate + +The new firmware is activated by issuing a device specific Embedded +Management Processor reset which requests the device to reset and reload the +EMP firmware image. + +The driver does not currently support reloading the driver via +``DEVLINK_RELOAD_ACTION_DRIVER_REINIT``. + Regions ======= diff --git a/Documentation/networking/devlink/mlx5.rst b/Documentation/networking/devlink/mlx5.rst index 4e4b97f7971a..29ad304e6fba 100644 --- a/Documentation/networking/devlink/mlx5.rst +++ b/Documentation/networking/devlink/mlx5.rst @@ -14,8 +14,19 @@ Parameters * - Name - Mode + - Validation * - ``enable_roce`` - driverinit + - Type: Boolean + * - ``io_eq_size`` + - driverinit + - The range is between 64 and 4096. + * - ``event_eq_size`` + - driverinit + - The range is between 64 and 4096. + * - ``max_macs`` + - driverinit + - The range is between 1 and 2^31. Only power of 2 values are supported. The ``mlx5`` driver also implements the following driver-specific parameters. diff --git a/Documentation/networking/ethtool-netlink.rst b/Documentation/networking/ethtool-netlink.rst index 7b598c7e3912..9d98e0511249 100644 --- a/Documentation/networking/ethtool-netlink.rst +++ b/Documentation/networking/ethtool-netlink.rst @@ -849,7 +849,7 @@ Request contents: Kernel response contents: - ==================================== ====== ========================== + ==================================== ====== =========================== ``ETHTOOL_A_RINGS_HEADER`` nested reply header ``ETHTOOL_A_RINGS_RX_MAX`` u32 max size of RX ring ``ETHTOOL_A_RINGS_RX_MINI_MAX`` u32 max size of RX mini ring @@ -859,7 +859,8 @@ Kernel response contents: ``ETHTOOL_A_RINGS_RX_MINI`` u32 size of RX mini ring ``ETHTOOL_A_RINGS_RX_JUMBO`` u32 size of RX jumbo ring ``ETHTOOL_A_RINGS_TX`` u32 size of TX ring - ==================================== ====== ========================== + ``ETHTOOL_A_RINGS_RX_BUF_LEN`` u32 size of buffers on the ring + ==================================== ====== =========================== RINGS_SET @@ -869,13 +870,14 @@ Sets ring sizes like ``ETHTOOL_SRINGPARAM`` ioctl request. Request contents: - ==================================== ====== ========================== + ==================================== ====== =========================== ``ETHTOOL_A_RINGS_HEADER`` nested reply header ``ETHTOOL_A_RINGS_RX`` u32 size of RX ring ``ETHTOOL_A_RINGS_RX_MINI`` u32 size of RX mini ring ``ETHTOOL_A_RINGS_RX_JUMBO`` u32 size of RX jumbo ring ``ETHTOOL_A_RINGS_TX`` u32 size of TX ring - ==================================== ====== ========================== + ``ETHTOOL_A_RINGS_RX_BUF_LEN`` u32 size of buffers on the ring + ==================================== ====== =========================== Kernel checks that requested ring sizes do not exceed limits reported by driver. Driver may impose additional constraints and may not suspport all diff --git a/Documentation/networking/filter.rst b/Documentation/networking/filter.rst index ce2b8e8bb9ab..43cdc4d34745 100644 --- a/Documentation/networking/filter.rst +++ b/Documentation/networking/filter.rst @@ -6,6 +6,13 @@ Linux Socket Filtering aka Berkeley Packet Filter (BPF) ======================================================= +Notice +------ + +This file used to document the eBPF format and mechanisms even when not +related to socket filtering. The ../bpf/index.rst has more details +on eBPF. + Introduction ------------ @@ -617,15 +624,11 @@ format with similar underlying principles from BPF described in previous paragraphs is being used. However, the instruction set format is modelled closer to the underlying architecture to mimic native instruction sets, so that a better performance can be achieved (more details later). This new -ISA is called 'eBPF' or 'internal BPF' interchangeably. (Note: eBPF which +ISA is called eBPF. See the ../bpf/index.rst for details. (Note: eBPF which originates from [e]xtended BPF is not the same as BPF extensions! While eBPF is an ISA, BPF extensions date back to classic BPF's 'overloading' of BPF_LD | BPF_{B,H,W} | BPF_ABS instruction.) -It is designed to be JITed with one to one mapping, which can also open up -the possibility for GCC/LLVM compilers to generate optimized eBPF code through -an eBPF backend that performs almost as fast as natively compiled code. - The new instruction set was originally designed with the possible goal in mind to write programs in "restricted C" and compile into eBPF with a optional GCC/LLVM backend, so that it can just-in-time map to modern 64-bit CPUs with @@ -650,1032 +653,11 @@ Currently, the classic BPF format is being used for JITing on most sparc64, arm32, riscv64, riscv32 perform JIT compilation from eBPF instruction set. -Some core changes of the new internal format: - -- Number of registers increase from 2 to 10: - - The old format had two registers A and X, and a hidden frame pointer. The - new layout extends this to be 10 internal registers and a read-only frame - pointer. Since 64-bit CPUs are passing arguments to functions via registers - the number of args from eBPF program to in-kernel function is restricted - to 5 and one register is used to accept return value from an in-kernel - function. Natively, x86_64 passes first 6 arguments in registers, aarch64/ - sparcv9/mips64 have 7 - 8 registers for arguments; x86_64 has 6 callee saved - registers, and aarch64/sparcv9/mips64 have 11 or more callee saved registers. - - Therefore, eBPF calling convention is defined as: - - * R0 - return value from in-kernel function, and exit value for eBPF program - * R1 - R5 - arguments from eBPF program to in-kernel function - * R6 - R9 - callee saved registers that in-kernel function will preserve - * R10 - read-only frame pointer to access stack - - Thus, all eBPF registers map one to one to HW registers on x86_64, aarch64, - etc, and eBPF calling convention maps directly to ABIs used by the kernel on - 64-bit architectures. - - On 32-bit architectures JIT may map programs that use only 32-bit arithmetic - and may let more complex programs to be interpreted. - - R0 - R5 are scratch registers and eBPF program needs spill/fill them if - necessary across calls. Note that there is only one eBPF program (== one - eBPF main routine) and it cannot call other eBPF functions, it can only - call predefined in-kernel functions, though. - -- Register width increases from 32-bit to 64-bit: - - Still, the semantics of the original 32-bit ALU operations are preserved - via 32-bit subregisters. All eBPF registers are 64-bit with 32-bit lower - subregisters that zero-extend into 64-bit if they are being written to. - That behavior maps directly to x86_64 and arm64 subregister definition, but - makes other JITs more difficult. - - 32-bit architectures run 64-bit internal BPF programs via interpreter. - Their JITs may convert BPF programs that only use 32-bit subregisters into - native instruction set and let the rest being interpreted. - - Operation is 64-bit, because on 64-bit architectures, pointers are also - 64-bit wide, and we want to pass 64-bit values in/out of kernel functions, - so 32-bit eBPF registers would otherwise require to define register-pair - ABI, thus, there won't be able to use a direct eBPF register to HW register - mapping and JIT would need to do combine/split/move operations for every - register in and out of the function, which is complex, bug prone and slow. - Another reason is the use of atomic 64-bit counters. - -- Conditional jt/jf targets replaced with jt/fall-through: - - While the original design has constructs such as ``if (cond) jump_true; - else jump_false;``, they are being replaced into alternative constructs like - ``if (cond) jump_true; /* else fall-through */``. - -- Introduces bpf_call insn and register passing convention for zero overhead - calls from/to other kernel functions: - - Before an in-kernel function call, the internal BPF program needs to - place function arguments into R1 to R5 registers to satisfy calling - convention, then the interpreter will take them from registers and pass - to in-kernel function. If R1 - R5 registers are mapped to CPU registers - that are used for argument passing on given architecture, the JIT compiler - doesn't need to emit extra moves. Function arguments will be in the correct - registers and BPF_CALL instruction will be JITed as single 'call' HW - instruction. This calling convention was picked to cover common call - situations without performance penalty. - - After an in-kernel function call, R1 - R5 are reset to unreadable and R0 has - a return value of the function. Since R6 - R9 are callee saved, their state - is preserved across the call. - - For example, consider three C functions:: - - u64 f1() { return (*_f2)(1); } - u64 f2(u64 a) { return f3(a + 1, a); } - u64 f3(u64 a, u64 b) { return a - b; } - - GCC can compile f1, f3 into x86_64:: - - f1: - movl $1, %edi - movq _f2(%rip), %rax - jmp *%rax - f3: - movq %rdi, %rax - subq %rsi, %rax - ret - - Function f2 in eBPF may look like:: - - f2: - bpf_mov R2, R1 - bpf_add R1, 1 - bpf_call f3 - bpf_exit - - If f2 is JITed and the pointer stored to ``_f2``. The calls f1 -> f2 -> f3 and - returns will be seamless. Without JIT, __bpf_prog_run() interpreter needs to - be used to call into f2. - - For practical reasons all eBPF programs have only one argument 'ctx' which is - already placed into R1 (e.g. on __bpf_prog_run() startup) and the programs - can call kernel functions with up to 5 arguments. Calls with 6 or more arguments - are currently not supported, but these restrictions can be lifted if necessary - in the future. - - On 64-bit architectures all register map to HW registers one to one. For - example, x86_64 JIT compiler can map them as ... - - :: - - R0 - rax - R1 - rdi - R2 - rsi - R3 - rdx - R4 - rcx - R5 - r8 - R6 - rbx - R7 - r13 - R8 - r14 - R9 - r15 - R10 - rbp - - ... since x86_64 ABI mandates rdi, rsi, rdx, rcx, r8, r9 for argument passing - and rbx, r12 - r15 are callee saved. - - Then the following internal BPF pseudo-program:: - - bpf_mov R6, R1 /* save ctx */ - bpf_mov R2, 2 - bpf_mov R3, 3 - bpf_mov R4, 4 - bpf_mov R5, 5 - bpf_call foo - bpf_mov R7, R0 /* save foo() return value */ - bpf_mov R1, R6 /* restore ctx for next call */ - bpf_mov R2, 6 - bpf_mov R3, 7 - bpf_mov R4, 8 - bpf_mov R5, 9 - bpf_call bar - bpf_add R0, R7 - bpf_exit - - After JIT to x86_64 may look like:: - - push %rbp - mov %rsp,%rbp - sub $0x228,%rsp - mov %rbx,-0x228(%rbp) - mov %r13,-0x220(%rbp) - mov %rdi,%rbx - mov $0x2,%esi - mov $0x3,%edx - mov $0x4,%ecx - mov $0x5,%r8d - callq foo - mov %rax,%r13 - mov %rbx,%rdi - mov $0x6,%esi - mov $0x7,%edx - mov $0x8,%ecx - mov $0x9,%r8d - callq bar - add %r13,%rax - mov -0x228(%rbp),%rbx - mov -0x220(%rbp),%r13 - leaveq - retq - - Which is in this example equivalent in C to:: - - u64 bpf_filter(u64 ctx) - { - return foo(ctx, 2, 3, 4, 5) + bar(ctx, 6, 7, 8, 9); - } - - In-kernel functions foo() and bar() with prototype: u64 (*)(u64 arg1, u64 - arg2, u64 arg3, u64 arg4, u64 arg5); will receive arguments in proper - registers and place their return value into ``%rax`` which is R0 in eBPF. - Prologue and epilogue are emitted by JIT and are implicit in the - interpreter. R0-R5 are scratch registers, so eBPF program needs to preserve - them across the calls as defined by calling convention. - - For example the following program is invalid:: - - bpf_mov R1, 1 - bpf_call foo - bpf_mov R0, R1 - bpf_exit - - After the call the registers R1-R5 contain junk values and cannot be read. - An in-kernel eBPF verifier is used to validate internal BPF programs. - -Also in the new design, eBPF is limited to 4096 insns, which means that any -program will terminate quickly and will only call a fixed number of kernel -functions. Original BPF and the new format are two operand instructions, -which helps to do one-to-one mapping between eBPF insn and x86 insn during JIT. - -The input context pointer for invoking the interpreter function is generic, -its content is defined by a specific use case. For seccomp register R1 points -to seccomp_data, for converted BPF filters R1 points to a skb. - -A program, that is translated internally consists of the following elements:: - - op:16, jt:8, jf:8, k:32 ==> op:8, dst_reg:4, src_reg:4, off:16, imm:32 - -So far 87 internal BPF instructions were implemented. 8-bit 'op' opcode field -has room for new instructions. Some of them may use 16/24/32 byte encoding. New -instructions must be multiple of 8 bytes to preserve backward compatibility. - -Internal BPF is a general purpose RISC instruction set. Not every register and -every instruction are used during translation from original BPF to new format. -For example, socket filters are not using ``exclusive add`` instruction, but -tracing filters may do to maintain counters of events, for example. Register R9 -is not used by socket filters either, but more complex filters may be running -out of registers and would have to resort to spill/fill to stack. - -Internal BPF can be used as a generic assembler for last step performance -optimizations, socket filters and seccomp are using it as assembler. Tracing -filters may use it as assembler to generate code from kernel. In kernel usage -may not be bounded by security considerations, since generated internal BPF code -may be optimizing internal code path and not being exposed to the user space. -Safety of internal BPF can come from a verifier (TBD). In such use cases as -described, it may be used as safe instruction set. - -Just like the original BPF, the new format runs within a controlled environment, -is deterministic and the kernel can easily prove that. The safety of the program -can be determined in two steps: first step does depth-first-search to disallow -loops and other CFG validation; second step starts from the first insn and -descends all possible paths. It simulates execution of every insn and observes -the state change of registers and stack. - -eBPF opcode encoding --------------------- - -eBPF is reusing most of the opcode encoding from classic to simplify conversion -of classic BPF to eBPF. For arithmetic and jump instructions the 8-bit 'code' -field is divided into three parts:: - - +----------------+--------+--------------------+ - | 4 bits | 1 bit | 3 bits | - | operation code | source | instruction class | - +----------------+--------+--------------------+ - (MSB) (LSB) - -Three LSB bits store instruction class which is one of: - - =================== =============== - Classic BPF classes eBPF classes - =================== =============== - BPF_LD 0x00 BPF_LD 0x00 - BPF_LDX 0x01 BPF_LDX 0x01 - BPF_ST 0x02 BPF_ST 0x02 - BPF_STX 0x03 BPF_STX 0x03 - BPF_ALU 0x04 BPF_ALU 0x04 - BPF_JMP 0x05 BPF_JMP 0x05 - BPF_RET 0x06 BPF_JMP32 0x06 - BPF_MISC 0x07 BPF_ALU64 0x07 - =================== =============== - -When BPF_CLASS(code) == BPF_ALU or BPF_JMP, 4th bit encodes source operand ... - - :: - - BPF_K 0x00 - BPF_X 0x08 - - * in classic BPF, this means:: - - BPF_SRC(code) == BPF_X - use register X as source operand - BPF_SRC(code) == BPF_K - use 32-bit immediate as source operand - - * in eBPF, this means:: - - BPF_SRC(code) == BPF_X - use 'src_reg' register as source operand - BPF_SRC(code) == BPF_K - use 32-bit immediate as source operand - -... and four MSB bits store operation code. - -If BPF_CLASS(code) == BPF_ALU or BPF_ALU64 [ in eBPF ], BPF_OP(code) is one of:: - - BPF_ADD 0x00 - BPF_SUB 0x10 - BPF_MUL 0x20 - BPF_DIV 0x30 - BPF_OR 0x40 - BPF_AND 0x50 - BPF_LSH 0x60 - BPF_RSH 0x70 - BPF_NEG 0x80 - BPF_MOD 0x90 - BPF_XOR 0xa0 - BPF_MOV 0xb0 /* eBPF only: mov reg to reg */ - BPF_ARSH 0xc0 /* eBPF only: sign extending shift right */ - BPF_END 0xd0 /* eBPF only: endianness conversion */ - -If BPF_CLASS(code) == BPF_JMP or BPF_JMP32 [ in eBPF ], BPF_OP(code) is one of:: - - BPF_JA 0x00 /* BPF_JMP only */ - BPF_JEQ 0x10 - BPF_JGT 0x20 - BPF_JGE 0x30 - BPF_JSET 0x40 - BPF_JNE 0x50 /* eBPF only: jump != */ - BPF_JSGT 0x60 /* eBPF only: signed '>' */ - BPF_JSGE 0x70 /* eBPF only: signed '>=' */ - BPF_CALL 0x80 /* eBPF BPF_JMP only: function call */ - BPF_EXIT 0x90 /* eBPF BPF_JMP only: function return */ - BPF_JLT 0xa0 /* eBPF only: unsigned '<' */ - BPF_JLE 0xb0 /* eBPF only: unsigned '<=' */ - BPF_JSLT 0xc0 /* eBPF only: signed '<' */ - BPF_JSLE 0xd0 /* eBPF only: signed '<=' */ - -So BPF_ADD | BPF_X | BPF_ALU means 32-bit addition in both classic BPF -and eBPF. There are only two registers in classic BPF, so it means A += X. -In eBPF it means dst_reg = (u32) dst_reg + (u32) src_reg; similarly, -BPF_XOR | BPF_K | BPF_ALU means A ^= imm32 in classic BPF and analogous -src_reg = (u32) src_reg ^ (u32) imm32 in eBPF. - -Classic BPF is using BPF_MISC class to represent A = X and X = A moves. -eBPF is using BPF_MOV | BPF_X | BPF_ALU code instead. Since there are no -BPF_MISC operations in eBPF, the class 7 is used as BPF_ALU64 to mean -exactly the same operations as BPF_ALU, but with 64-bit wide operands -instead. So BPF_ADD | BPF_X | BPF_ALU64 means 64-bit addition, i.e.: -dst_reg = dst_reg + src_reg - -Classic BPF wastes the whole BPF_RET class to represent a single ``ret`` -operation. Classic BPF_RET | BPF_K means copy imm32 into return register -and perform function exit. eBPF is modeled to match CPU, so BPF_JMP | BPF_EXIT -in eBPF means function exit only. The eBPF program needs to store return -value into register R0 before doing a BPF_EXIT. Class 6 in eBPF is used as -BPF_JMP32 to mean exactly the same operations as BPF_JMP, but with 32-bit wide -operands for the comparisons instead. - -For load and store instructions the 8-bit 'code' field is divided as:: - - +--------+--------+-------------------+ - | 3 bits | 2 bits | 3 bits | - | mode | size | instruction class | - +--------+--------+-------------------+ - (MSB) (LSB) - -Size modifier is one of ... - -:: - - BPF_W 0x00 /* word */ - BPF_H 0x08 /* half word */ - BPF_B 0x10 /* byte */ - BPF_DW 0x18 /* eBPF only, double word */ - -... which encodes size of load/store operation:: - - B - 1 byte - H - 2 byte - W - 4 byte - DW - 8 byte (eBPF only) - -Mode modifier is one of:: - - BPF_IMM 0x00 /* used for 32-bit mov in classic BPF and 64-bit in eBPF */ - BPF_ABS 0x20 - BPF_IND 0x40 - BPF_MEM 0x60 - BPF_LEN 0x80 /* classic BPF only, reserved in eBPF */ - BPF_MSH 0xa0 /* classic BPF only, reserved in eBPF */ - BPF_ATOMIC 0xc0 /* eBPF only, atomic operations */ - -eBPF has two non-generic instructions: (BPF_ABS | <size> | BPF_LD) and -(BPF_IND | <size> | BPF_LD) which are used to access packet data. - -They had to be carried over from classic to have strong performance of -socket filters running in eBPF interpreter. These instructions can only -be used when interpreter context is a pointer to ``struct sk_buff`` and -have seven implicit operands. Register R6 is an implicit input that must -contain pointer to sk_buff. Register R0 is an implicit output which contains -the data fetched from the packet. Registers R1-R5 are scratch registers -and must not be used to store the data across BPF_ABS | BPF_LD or -BPF_IND | BPF_LD instructions. - -These instructions have implicit program exit condition as well. When -eBPF program is trying to access the data beyond the packet boundary, -the interpreter will abort the execution of the program. JIT compilers -therefore must preserve this property. src_reg and imm32 fields are -explicit inputs to these instructions. - -For example:: - - BPF_IND | BPF_W | BPF_LD means: - - R0 = ntohl(*(u32 *) (((struct sk_buff *) R6)->data + src_reg + imm32)) - and R1 - R5 were scratched. - -Unlike classic BPF instruction set, eBPF has generic load/store operations:: - - BPF_MEM | <size> | BPF_STX: *(size *) (dst_reg + off) = src_reg - BPF_MEM | <size> | BPF_ST: *(size *) (dst_reg + off) = imm32 - BPF_MEM | <size> | BPF_LDX: dst_reg = *(size *) (src_reg + off) - -Where size is one of: BPF_B or BPF_H or BPF_W or BPF_DW. - -It also includes atomic operations, which use the immediate field for extra -encoding:: - - .imm = BPF_ADD, .code = BPF_ATOMIC | BPF_W | BPF_STX: lock xadd *(u32 *)(dst_reg + off16) += src_reg - .imm = BPF_ADD, .code = BPF_ATOMIC | BPF_DW | BPF_STX: lock xadd *(u64 *)(dst_reg + off16) += src_reg - -The basic atomic operations supported are:: - - BPF_ADD - BPF_AND - BPF_OR - BPF_XOR - -Each having equivalent semantics with the ``BPF_ADD`` example, that is: the -memory location addresed by ``dst_reg + off`` is atomically modified, with -``src_reg`` as the other operand. If the ``BPF_FETCH`` flag is set in the -immediate, then these operations also overwrite ``src_reg`` with the -value that was in memory before it was modified. - -The more special operations are:: - - BPF_XCHG - -This atomically exchanges ``src_reg`` with the value addressed by ``dst_reg + -off``. :: - - BPF_CMPXCHG - -This atomically compares the value addressed by ``dst_reg + off`` with -``R0``. If they match it is replaced with ``src_reg``. In either case, the -value that was there before is zero-extended and loaded back to ``R0``. - -Note that 1 and 2 byte atomic operations are not supported. - -Clang can generate atomic instructions by default when ``-mcpu=v3`` is -enabled. If a lower version for ``-mcpu`` is set, the only atomic instruction -Clang can generate is ``BPF_ADD`` *without* ``BPF_FETCH``. If you need to enable -the atomics features, while keeping a lower ``-mcpu`` version, you can use -``-Xclang -target-feature -Xclang +alu32``. - -You may encounter ``BPF_XADD`` - this is a legacy name for ``BPF_ATOMIC``, -referring to the exclusive-add operation encoded when the immediate field is -zero. - -eBPF has one 16-byte instruction: ``BPF_LD | BPF_DW | BPF_IMM`` which consists -of two consecutive ``struct bpf_insn`` 8-byte blocks and interpreted as single -instruction that loads 64-bit immediate value into a dst_reg. -Classic BPF has similar instruction: ``BPF_LD | BPF_W | BPF_IMM`` which loads -32-bit immediate value into a register. - -eBPF verifier -------------- -The safety of the eBPF program is determined in two steps. - -First step does DAG check to disallow loops and other CFG validation. -In particular it will detect programs that have unreachable instructions. -(though classic BPF checker allows them) - -Second step starts from the first insn and descends all possible paths. -It simulates execution of every insn and observes the state change of -registers and stack. - -At the start of the program the register R1 contains a pointer to context -and has type PTR_TO_CTX. -If verifier sees an insn that does R2=R1, then R2 has now type -PTR_TO_CTX as well and can be used on the right hand side of expression. -If R1=PTR_TO_CTX and insn is R2=R1+R1, then R2=SCALAR_VALUE, -since addition of two valid pointers makes invalid pointer. -(In 'secure' mode verifier will reject any type of pointer arithmetic to make -sure that kernel addresses don't leak to unprivileged users) - -If register was never written to, it's not readable:: - - bpf_mov R0 = R2 - bpf_exit - -will be rejected, since R2 is unreadable at the start of the program. - -After kernel function call, R1-R5 are reset to unreadable and -R0 has a return type of the function. - -Since R6-R9 are callee saved, their state is preserved across the call. - -:: - - bpf_mov R6 = 1 - bpf_call foo - bpf_mov R0 = R6 - bpf_exit - -is a correct program. If there was R1 instead of R6, it would have -been rejected. - -load/store instructions are allowed only with registers of valid types, which -are PTR_TO_CTX, PTR_TO_MAP, PTR_TO_STACK. They are bounds and alignment checked. -For example:: - - bpf_mov R1 = 1 - bpf_mov R2 = 2 - bpf_xadd *(u32 *)(R1 + 3) += R2 - bpf_exit - -will be rejected, since R1 doesn't have a valid pointer type at the time of -execution of instruction bpf_xadd. - -At the start R1 type is PTR_TO_CTX (a pointer to generic ``struct bpf_context``) -A callback is used to customize verifier to restrict eBPF program access to only -certain fields within ctx structure with specified size and alignment. - -For example, the following insn:: - - bpf_ld R0 = *(u32 *)(R6 + 8) - -intends to load a word from address R6 + 8 and store it into R0 -If R6=PTR_TO_CTX, via is_valid_access() callback the verifier will know -that offset 8 of size 4 bytes can be accessed for reading, otherwise -the verifier will reject the program. -If R6=PTR_TO_STACK, then access should be aligned and be within -stack bounds, which are [-MAX_BPF_STACK, 0). In this example offset is 8, -so it will fail verification, since it's out of bounds. - -The verifier will allow eBPF program to read data from stack only after -it wrote into it. - -Classic BPF verifier does similar check with M[0-15] memory slots. -For example:: - - bpf_ld R0 = *(u32 *)(R10 - 4) - bpf_exit - -is invalid program. -Though R10 is correct read-only register and has type PTR_TO_STACK -and R10 - 4 is within stack bounds, there were no stores into that location. - -Pointer register spill/fill is tracked as well, since four (R6-R9) -callee saved registers may not be enough for some programs. - -Allowed function calls are customized with bpf_verifier_ops->get_func_proto() -The eBPF verifier will check that registers match argument constraints. -After the call register R0 will be set to return type of the function. - -Function calls is a main mechanism to extend functionality of eBPF programs. -Socket filters may let programs to call one set of functions, whereas tracing -filters may allow completely different set. - -If a function made accessible to eBPF program, it needs to be thought through -from safety point of view. The verifier will guarantee that the function is -called with valid arguments. - -seccomp vs socket filters have different security restrictions for classic BPF. -Seccomp solves this by two stage verifier: classic BPF verifier is followed -by seccomp verifier. In case of eBPF one configurable verifier is shared for -all use cases. - -See details of eBPF verifier in kernel/bpf/verifier.c - -Register value tracking ------------------------ -In order to determine the safety of an eBPF program, the verifier must track -the range of possible values in each register and also in each stack slot. -This is done with ``struct bpf_reg_state``, defined in include/linux/ -bpf_verifier.h, which unifies tracking of scalar and pointer values. Each -register state has a type, which is either NOT_INIT (the register has not been -written to), SCALAR_VALUE (some value which is not usable as a pointer), or a -pointer type. The types of pointers describe their base, as follows: - - - PTR_TO_CTX - Pointer to bpf_context. - CONST_PTR_TO_MAP - Pointer to struct bpf_map. "Const" because arithmetic - on these pointers is forbidden. - PTR_TO_MAP_VALUE - Pointer to the value stored in a map element. - PTR_TO_MAP_VALUE_OR_NULL - Either a pointer to a map value, or NULL; map accesses - (see section 'eBPF maps', below) return this type, - which becomes a PTR_TO_MAP_VALUE when checked != NULL. - Arithmetic on these pointers is forbidden. - PTR_TO_STACK - Frame pointer. - PTR_TO_PACKET - skb->data. - PTR_TO_PACKET_END - skb->data + headlen; arithmetic forbidden. - PTR_TO_SOCKET - Pointer to struct bpf_sock_ops, implicitly refcounted. - PTR_TO_SOCKET_OR_NULL - Either a pointer to a socket, or NULL; socket lookup - returns this type, which becomes a PTR_TO_SOCKET when - checked != NULL. PTR_TO_SOCKET is reference-counted, - so programs must release the reference through the - socket release function before the end of the program. - Arithmetic on these pointers is forbidden. - -However, a pointer may be offset from this base (as a result of pointer -arithmetic), and this is tracked in two parts: the 'fixed offset' and 'variable -offset'. The former is used when an exactly-known value (e.g. an immediate -operand) is added to a pointer, while the latter is used for values which are -not exactly known. The variable offset is also used in SCALAR_VALUEs, to track -the range of possible values in the register. - -The verifier's knowledge about the variable offset consists of: - -* minimum and maximum values as unsigned -* minimum and maximum values as signed - -* knowledge of the values of individual bits, in the form of a 'tnum': a u64 - 'mask' and a u64 'value'. 1s in the mask represent bits whose value is unknown; - 1s in the value represent bits known to be 1. Bits known to be 0 have 0 in both - mask and value; no bit should ever be 1 in both. For example, if a byte is read - into a register from memory, the register's top 56 bits are known zero, while - the low 8 are unknown - which is represented as the tnum (0x0; 0xff). If we - then OR this with 0x40, we get (0x40; 0xbf), then if we add 1 we get (0x0; - 0x1ff), because of potential carries. - -Besides arithmetic, the register state can also be updated by conditional -branches. For instance, if a SCALAR_VALUE is compared > 8, in the 'true' branch -it will have a umin_value (unsigned minimum value) of 9, whereas in the 'false' -branch it will have a umax_value of 8. A signed compare (with BPF_JSGT or -BPF_JSGE) would instead update the signed minimum/maximum values. Information -from the signed and unsigned bounds can be combined; for instance if a value is -first tested < 8 and then tested s> 4, the verifier will conclude that the value -is also > 4 and s< 8, since the bounds prevent crossing the sign boundary. - -PTR_TO_PACKETs with a variable offset part have an 'id', which is common to all -pointers sharing that same variable offset. This is important for packet range -checks: after adding a variable to a packet pointer register A, if you then copy -it to another register B and then add a constant 4 to A, both registers will -share the same 'id' but the A will have a fixed offset of +4. Then if A is -bounds-checked and found to be less than a PTR_TO_PACKET_END, the register B is -now known to have a safe range of at least 4 bytes. See 'Direct packet access', -below, for more on PTR_TO_PACKET ranges. - -The 'id' field is also used on PTR_TO_MAP_VALUE_OR_NULL, common to all copies of -the pointer returned from a map lookup. This means that when one copy is -checked and found to be non-NULL, all copies can become PTR_TO_MAP_VALUEs. -As well as range-checking, the tracked information is also used for enforcing -alignment of pointer accesses. For instance, on most systems the packet pointer -is 2 bytes after a 4-byte alignment. If a program adds 14 bytes to that to jump -over the Ethernet header, then reads IHL and addes (IHL * 4), the resulting -pointer will have a variable offset known to be 4n+2 for some n, so adding the 2 -bytes (NET_IP_ALIGN) gives a 4-byte alignment and so word-sized accesses through -that pointer are safe. -The 'id' field is also used on PTR_TO_SOCKET and PTR_TO_SOCKET_OR_NULL, common -to all copies of the pointer returned from a socket lookup. This has similar -behaviour to the handling for PTR_TO_MAP_VALUE_OR_NULL->PTR_TO_MAP_VALUE, but -it also handles reference tracking for the pointer. PTR_TO_SOCKET implicitly -represents a reference to the corresponding ``struct sock``. To ensure that the -reference is not leaked, it is imperative to NULL-check the reference and in -the non-NULL case, and pass the valid reference to the socket release function. - -Direct packet access --------------------- -In cls_bpf and act_bpf programs the verifier allows direct access to the packet -data via skb->data and skb->data_end pointers. -Ex:: - - 1: r4 = *(u32 *)(r1 +80) /* load skb->data_end */ - 2: r3 = *(u32 *)(r1 +76) /* load skb->data */ - 3: r5 = r3 - 4: r5 += 14 - 5: if r5 > r4 goto pc+16 - R1=ctx R3=pkt(id=0,off=0,r=14) R4=pkt_end R5=pkt(id=0,off=14,r=14) R10=fp - 6: r0 = *(u16 *)(r3 +12) /* access 12 and 13 bytes of the packet */ - -this 2byte load from the packet is safe to do, since the program author -did check ``if (skb->data + 14 > skb->data_end) goto err`` at insn #5 which -means that in the fall-through case the register R3 (which points to skb->data) -has at least 14 directly accessible bytes. The verifier marks it -as R3=pkt(id=0,off=0,r=14). -id=0 means that no additional variables were added to the register. -off=0 means that no additional constants were added. -r=14 is the range of safe access which means that bytes [R3, R3 + 14) are ok. -Note that R5 is marked as R5=pkt(id=0,off=14,r=14). It also points -to the packet data, but constant 14 was added to the register, so -it now points to ``skb->data + 14`` and accessible range is [R5, R5 + 14 - 14) -which is zero bytes. - -More complex packet access may look like:: - - - R0=inv1 R1=ctx R3=pkt(id=0,off=0,r=14) R4=pkt_end R5=pkt(id=0,off=14,r=14) R10=fp - 6: r0 = *(u8 *)(r3 +7) /* load 7th byte from the packet */ - 7: r4 = *(u8 *)(r3 +12) - 8: r4 *= 14 - 9: r3 = *(u32 *)(r1 +76) /* load skb->data */ - 10: r3 += r4 - 11: r2 = r1 - 12: r2 <<= 48 - 13: r2 >>= 48 - 14: r3 += r2 - 15: r2 = r3 - 16: r2 += 8 - 17: r1 = *(u32 *)(r1 +80) /* load skb->data_end */ - 18: if r2 > r1 goto pc+2 - R0=inv(id=0,umax_value=255,var_off=(0x0; 0xff)) R1=pkt_end R2=pkt(id=2,off=8,r=8) R3=pkt(id=2,off=0,r=8) R4=inv(id=0,umax_value=3570,var_off=(0x0; 0xfffe)) R5=pkt(id=0,off=14,r=14) R10=fp - 19: r1 = *(u8 *)(r3 +4) - -The state of the register R3 is R3=pkt(id=2,off=0,r=8) -id=2 means that two ``r3 += rX`` instructions were seen, so r3 points to some -offset within a packet and since the program author did -``if (r3 + 8 > r1) goto err`` at insn #18, the safe range is [R3, R3 + 8). -The verifier only allows 'add'/'sub' operations on packet registers. Any other -operation will set the register state to 'SCALAR_VALUE' and it won't be -available for direct packet access. - -Operation ``r3 += rX`` may overflow and become less than original skb->data, -therefore the verifier has to prevent that. So when it sees ``r3 += rX`` -instruction and rX is more than 16-bit value, any subsequent bounds-check of r3 -against skb->data_end will not give us 'range' information, so attempts to read -through the pointer will give "invalid access to packet" error. - -Ex. after insn ``r4 = *(u8 *)(r3 +12)`` (insn #7 above) the state of r4 is -R4=inv(id=0,umax_value=255,var_off=(0x0; 0xff)) which means that upper 56 bits -of the register are guaranteed to be zero, and nothing is known about the lower -8 bits. After insn ``r4 *= 14`` the state becomes -R4=inv(id=0,umax_value=3570,var_off=(0x0; 0xfffe)), since multiplying an 8-bit -value by constant 14 will keep upper 52 bits as zero, also the least significant -bit will be zero as 14 is even. Similarly ``r2 >>= 48`` will make -R2=inv(id=0,umax_value=65535,var_off=(0x0; 0xffff)), since the shift is not sign -extending. This logic is implemented in adjust_reg_min_max_vals() function, -which calls adjust_ptr_min_max_vals() for adding pointer to scalar (or vice -versa) and adjust_scalar_min_max_vals() for operations on two scalars. - -The end result is that bpf program author can access packet directly -using normal C code as:: - - void *data = (void *)(long)skb->data; - void *data_end = (void *)(long)skb->data_end; - struct eth_hdr *eth = data; - struct iphdr *iph = data + sizeof(*eth); - struct udphdr *udp = data + sizeof(*eth) + sizeof(*iph); - - if (data + sizeof(*eth) + sizeof(*iph) + sizeof(*udp) > data_end) - return 0; - if (eth->h_proto != htons(ETH_P_IP)) - return 0; - if (iph->protocol != IPPROTO_UDP || iph->ihl != 5) - return 0; - if (udp->dest == 53 || udp->source == 9) - ...; - -which makes such programs easier to write comparing to LD_ABS insn -and significantly faster. - -eBPF maps ---------- -'maps' is a generic storage of different types for sharing data between kernel -and userspace. - -The maps are accessed from user space via BPF syscall, which has commands: - -- create a map with given type and attributes - ``map_fd = bpf(BPF_MAP_CREATE, union bpf_attr *attr, u32 size)`` - using attr->map_type, attr->key_size, attr->value_size, attr->max_entries - returns process-local file descriptor or negative error - -- lookup key in a given map - ``err = bpf(BPF_MAP_LOOKUP_ELEM, union bpf_attr *attr, u32 size)`` - using attr->map_fd, attr->key, attr->value - returns zero and stores found elem into value or negative error - -- create or update key/value pair in a given map - ``err = bpf(BPF_MAP_UPDATE_ELEM, union bpf_attr *attr, u32 size)`` - using attr->map_fd, attr->key, attr->value - returns zero or negative error - -- find and delete element by key in a given map - ``err = bpf(BPF_MAP_DELETE_ELEM, union bpf_attr *attr, u32 size)`` - using attr->map_fd, attr->key - -- to delete map: close(fd) - Exiting process will delete maps automatically - -userspace programs use this syscall to create/access maps that eBPF programs -are concurrently updating. - -maps can have different types: hash, array, bloom filter, radix-tree, etc. - -The map is defined by: - - - type - - max number of elements - - key size in bytes - - value size in bytes - -Pruning -------- -The verifier does not actually walk all possible paths through the program. For -each new branch to analyse, the verifier looks at all the states it's previously -been in when at this instruction. If any of them contain the current state as a -subset, the branch is 'pruned' - that is, the fact that the previous state was -accepted implies the current state would be as well. For instance, if in the -previous state, r1 held a packet-pointer, and in the current state, r1 holds a -packet-pointer with a range as long or longer and at least as strict an -alignment, then r1 is safe. Similarly, if r2 was NOT_INIT before then it can't -have been used by any path from that point, so any value in r2 (including -another NOT_INIT) is safe. The implementation is in the function regsafe(). -Pruning considers not only the registers but also the stack (and any spilled -registers it may hold). They must all be safe for the branch to be pruned. -This is implemented in states_equal(). - -Understanding eBPF verifier messages ------------------------------------- - -The following are few examples of invalid eBPF programs and verifier error -messages as seen in the log: - -Program with unreachable instructions:: - - static struct bpf_insn prog[] = { - BPF_EXIT_INSN(), - BPF_EXIT_INSN(), - }; - -Error: - - unreachable insn 1 - -Program that reads uninitialized register:: - - BPF_MOV64_REG(BPF_REG_0, BPF_REG_2), - BPF_EXIT_INSN(), - -Error:: - - 0: (bf) r0 = r2 - R2 !read_ok - -Program that doesn't initialize R0 before exiting:: - - BPF_MOV64_REG(BPF_REG_2, BPF_REG_1), - BPF_EXIT_INSN(), - -Error:: - - 0: (bf) r2 = r1 - 1: (95) exit - R0 !read_ok - -Program that accesses stack out of bounds:: - - BPF_ST_MEM(BPF_DW, BPF_REG_10, 8, 0), - BPF_EXIT_INSN(), - -Error:: - - 0: (7a) *(u64 *)(r10 +8) = 0 - invalid stack off=8 size=8 - -Program that doesn't initialize stack before passing its address into function:: - - BPF_MOV64_REG(BPF_REG_2, BPF_REG_10), - BPF_ALU64_IMM(BPF_ADD, BPF_REG_2, -8), - BPF_LD_MAP_FD(BPF_REG_1, 0), - BPF_RAW_INSN(BPF_JMP | BPF_CALL, 0, 0, 0, BPF_FUNC_map_lookup_elem), - BPF_EXIT_INSN(), - -Error:: - - 0: (bf) r2 = r10 - 1: (07) r2 += -8 - 2: (b7) r1 = 0x0 - 3: (85) call 1 - invalid indirect read from stack off -8+0 size 8 - -Program that uses invalid map_fd=0 while calling to map_lookup_elem() function:: - - BPF_ST_MEM(BPF_DW, BPF_REG_10, -8, 0), - BPF_MOV64_REG(BPF_REG_2, BPF_REG_10), - BPF_ALU64_IMM(BPF_ADD, BPF_REG_2, -8), - BPF_LD_MAP_FD(BPF_REG_1, 0), - BPF_RAW_INSN(BPF_JMP | BPF_CALL, 0, 0, 0, BPF_FUNC_map_lookup_elem), - BPF_EXIT_INSN(), - -Error:: - - 0: (7a) *(u64 *)(r10 -8) = 0 - 1: (bf) r2 = r10 - 2: (07) r2 += -8 - 3: (b7) r1 = 0x0 - 4: (85) call 1 - fd 0 is not pointing to valid bpf_map - -Program that doesn't check return value of map_lookup_elem() before accessing -map element:: - - BPF_ST_MEM(BPF_DW, BPF_REG_10, -8, 0), - BPF_MOV64_REG(BPF_REG_2, BPF_REG_10), - BPF_ALU64_IMM(BPF_ADD, BPF_REG_2, -8), - BPF_LD_MAP_FD(BPF_REG_1, 0), - BPF_RAW_INSN(BPF_JMP | BPF_CALL, 0, 0, 0, BPF_FUNC_map_lookup_elem), - BPF_ST_MEM(BPF_DW, BPF_REG_0, 0, 0), - BPF_EXIT_INSN(), - -Error:: - - 0: (7a) *(u64 *)(r10 -8) = 0 - 1: (bf) r2 = r10 - 2: (07) r2 += -8 - 3: (b7) r1 = 0x0 - 4: (85) call 1 - 5: (7a) *(u64 *)(r0 +0) = 0 - R0 invalid mem access 'map_value_or_null' - -Program that correctly checks map_lookup_elem() returned value for NULL, but -accesses the memory with incorrect alignment:: - - BPF_ST_MEM(BPF_DW, BPF_REG_10, -8, 0), - BPF_MOV64_REG(BPF_REG_2, BPF_REG_10), - BPF_ALU64_IMM(BPF_ADD, BPF_REG_2, -8), - BPF_LD_MAP_FD(BPF_REG_1, 0), - BPF_RAW_INSN(BPF_JMP | BPF_CALL, 0, 0, 0, BPF_FUNC_map_lookup_elem), - BPF_JMP_IMM(BPF_JEQ, BPF_REG_0, 0, 1), - BPF_ST_MEM(BPF_DW, BPF_REG_0, 4, 0), - BPF_EXIT_INSN(), - -Error:: - - 0: (7a) *(u64 *)(r10 -8) = 0 - 1: (bf) r2 = r10 - 2: (07) r2 += -8 - 3: (b7) r1 = 1 - 4: (85) call 1 - 5: (15) if r0 == 0x0 goto pc+1 - R0=map_ptr R10=fp - 6: (7a) *(u64 *)(r0 +4) = 0 - misaligned access off 4 size 8 - -Program that correctly checks map_lookup_elem() returned value for NULL and -accesses memory with correct alignment in one side of 'if' branch, but fails -to do so in the other side of 'if' branch:: - - BPF_ST_MEM(BPF_DW, BPF_REG_10, -8, 0), - BPF_MOV64_REG(BPF_REG_2, BPF_REG_10), - BPF_ALU64_IMM(BPF_ADD, BPF_REG_2, -8), - BPF_LD_MAP_FD(BPF_REG_1, 0), - BPF_RAW_INSN(BPF_JMP | BPF_CALL, 0, 0, 0, BPF_FUNC_map_lookup_elem), - BPF_JMP_IMM(BPF_JEQ, BPF_REG_0, 0, 2), - BPF_ST_MEM(BPF_DW, BPF_REG_0, 0, 0), - BPF_EXIT_INSN(), - BPF_ST_MEM(BPF_DW, BPF_REG_0, 0, 1), - BPF_EXIT_INSN(), - -Error:: - - 0: (7a) *(u64 *)(r10 -8) = 0 - 1: (bf) r2 = r10 - 2: (07) r2 += -8 - 3: (b7) r1 = 1 - 4: (85) call 1 - 5: (15) if r0 == 0x0 goto pc+2 - R0=map_ptr R10=fp - 6: (7a) *(u64 *)(r0 +0) = 0 - 7: (95) exit - - from 5 to 8: R0=imm0 R10=fp - 8: (7a) *(u64 *)(r0 +0) = 1 - R0 invalid mem access 'imm' - -Program that performs a socket lookup then sets the pointer to NULL without -checking it:: - - BPF_MOV64_IMM(BPF_REG_2, 0), - BPF_STX_MEM(BPF_W, BPF_REG_10, BPF_REG_2, -8), - BPF_MOV64_REG(BPF_REG_2, BPF_REG_10), - BPF_ALU64_IMM(BPF_ADD, BPF_REG_2, -8), - BPF_MOV64_IMM(BPF_REG_3, 4), - BPF_MOV64_IMM(BPF_REG_4, 0), - BPF_MOV64_IMM(BPF_REG_5, 0), - BPF_EMIT_CALL(BPF_FUNC_sk_lookup_tcp), - BPF_MOV64_IMM(BPF_REG_0, 0), - BPF_EXIT_INSN(), - -Error:: - - 0: (b7) r2 = 0 - 1: (63) *(u32 *)(r10 -8) = r2 - 2: (bf) r2 = r10 - 3: (07) r2 += -8 - 4: (b7) r3 = 4 - 5: (b7) r4 = 0 - 6: (b7) r5 = 0 - 7: (85) call bpf_sk_lookup_tcp#65 - 8: (b7) r0 = 0 - 9: (95) exit - Unreleased reference id=1, alloc_insn=7 - -Program that performs a socket lookup but does not NULL-check the returned -value:: - - BPF_MOV64_IMM(BPF_REG_2, 0), - BPF_STX_MEM(BPF_W, BPF_REG_10, BPF_REG_2, -8), - BPF_MOV64_REG(BPF_REG_2, BPF_REG_10), - BPF_ALU64_IMM(BPF_ADD, BPF_REG_2, -8), - BPF_MOV64_IMM(BPF_REG_3, 4), - BPF_MOV64_IMM(BPF_REG_4, 0), - BPF_MOV64_IMM(BPF_REG_5, 0), - BPF_EMIT_CALL(BPF_FUNC_sk_lookup_tcp), - BPF_EXIT_INSN(), - -Error:: - - 0: (b7) r2 = 0 - 1: (63) *(u32 *)(r10 -8) = r2 - 2: (bf) r2 = r10 - 3: (07) r2 += -8 - 4: (b7) r3 = 4 - 5: (b7) r4 = 0 - 6: (b7) r5 = 0 - 7: (85) call bpf_sk_lookup_tcp#65 - 8: (95) exit - Unreleased reference id=1, alloc_insn=7 - Testing ------- Next to the BPF toolchain, the kernel also ships a test module that contains -various test cases for classic and internal BPF that can be executed against +various test cases for classic and eBPF that can be executed against the BPF interpreter and JIT compiler. It can be found in lib/test_bpf.c and enabled via Kconfig:: diff --git a/Documentation/networking/ip-sysctl.rst b/Documentation/networking/ip-sysctl.rst index c04431144f7a..2572eecc3e86 100644 --- a/Documentation/networking/ip-sysctl.rst +++ b/Documentation/networking/ip-sysctl.rst @@ -25,7 +25,8 @@ ip_default_ttl - INTEGER ip_no_pmtu_disc - INTEGER Disable Path MTU Discovery. If enabled in mode 1 and a fragmentation-required ICMP is received, the PMTU to this - destination will be set to min_pmtu (see below). You will need + destination will be set to the smallest of the old MTU to + this destination and min_pmtu (see below). You will need to raise min_pmtu to the smallest interface MTU on your system manually if you want to avoid locally generated fragments. @@ -49,7 +50,8 @@ ip_no_pmtu_disc - INTEGER Default: FALSE min_pmtu - INTEGER - default 552 - minimum discovered Path MTU + default 552 - minimum Path MTU. Unless this is changed mannually, + each cached pmtu will never be lower than this setting. ip_forward_use_pmtu - BOOLEAN By default we don't trust protocol path MTUs while forwarding diff --git a/Documentation/networking/net_failover.rst b/Documentation/networking/net_failover.rst index e143ab79a960..3a662f2b4d6e 100644 --- a/Documentation/networking/net_failover.rst +++ b/Documentation/networking/net_failover.rst @@ -35,7 +35,7 @@ To support this, the hypervisor needs to enable VIRTIO_NET_F_STANDBY feature on the virtio-net interface and assign the same MAC address to both virtio-net and VF interfaces. -Here is an example XML snippet that shows such configuration. +Here is an example libvirt XML snippet that shows such configuration: :: <interface type='network'> @@ -45,18 +45,32 @@ Here is an example XML snippet that shows such configuration. <model type='virtio'/> <driver name='vhost' queues='4'/> <link state='down'/> - <address type='pci' domain='0x0000' bus='0x00' slot='0x0a' function='0x0'/> + <teaming type='persistent'/> + <alias name='ua-backup0'/> </interface> <interface type='hostdev' managed='yes'> <mac address='52:54:00:00:12:53'/> <source> <address type='pci' domain='0x0000' bus='0x42' slot='0x02' function='0x5'/> </source> - <address type='pci' domain='0x0000' bus='0x00' slot='0x0b' function='0x0'/> + <teaming type='transient' persistent='ua-backup0'/> </interface> +In this configuration, the first device definition is for the virtio-net +interface and this acts as the 'persistent' device indicating that this +interface will always be plugged in. This is specified by the 'teaming' tag with +required attribute type having value 'persistent'. The link state for the +virtio-net device is set to 'down' to ensure that the 'failover' netdev prefers +the VF passthrough device for normal communication. The virtio-net device will +be brought UP during live migration to allow uninterrupted communication. + +The second device definition is for the VF passthrough interface. Here the +'teaming' tag is provided with type 'transient' indicating that this device may +periodically be unplugged. A second attribute - 'persistent' is provided and +points to the alias name declared for the virtio-net device. + Booting a VM with the above configuration will result in the following 3 -netdevs created in the VM. +interfaces created in the VM: :: 4: ens10: <BROADCAST,MULTICAST,UP,LOWER_UP> mtu 1500 qdisc noqueue state UP group default qlen 1000 @@ -65,13 +79,36 @@ netdevs created in the VM. valid_lft 42482sec preferred_lft 42482sec inet6 fe80::97d8:db2:8c10:b6d6/64 scope link valid_lft forever preferred_lft forever - 5: ens10nsby: <BROADCAST,MULTICAST,UP,LOWER_UP> mtu 1500 qdisc fq_codel master ens10 state UP group default qlen 1000 + 5: ens10nsby: <BROADCAST,MULTICAST> mtu 1500 qdisc fq_codel master ens10 state DOWN group default qlen 1000 link/ether 52:54:00:00:12:53 brd ff:ff:ff:ff:ff:ff 7: ens11: <BROADCAST,MULTICAST,UP,LOWER_UP> mtu 1500 qdisc mq master ens10 state UP group default qlen 1000 link/ether 52:54:00:00:12:53 brd ff:ff:ff:ff:ff:ff -ens10 is the 'failover' master netdev, ens10nsby and ens11 are the slave -'standby' and 'primary' netdevs respectively. +Here, ens10 is the 'failover' master interface, ens10nsby is the slave 'standby' +virtio-net interface, and ens11 is the slave 'primary' VF passthrough interface. + +One point to note here is that some user space network configuration daemons +like systemd-networkd, ifupdown, etc, do not understand the 'net_failover' +device; and on the first boot, the VM might end up with both 'failover' device +and VF accquiring IP addresses (either same or different) from the DHCP server. +This will result in lack of connectivity to the VM. So some tweaks might be +needed to these network configuration daemons to make sure that an IP is +received only on the 'failover' device. + +Below is the patch snippet used with 'cloud-ifupdown-helper' script found on +Debian cloud images: + +:: + @@ -27,6 +27,8 @@ do_setup() { + local working="$cfgdir/.$INTERFACE" + local final="$cfgdir/$INTERFACE" + + + if [ -d "/sys/class/net/${INTERFACE}/master" ]; then exit 0; fi + + + if ifup --no-act "$INTERFACE" > /dev/null 2>&1; then + # interface is already known to ifupdown, no need to generate cfg + log "Skipping configuration generation for $INTERFACE" + Live Migration of a VM with SR-IOV VF & virtio-net in STANDBY mode ================================================================== @@ -80,40 +117,68 @@ net_failover also enables hypervisor controlled live migration to be supported with VMs that have direct attached SR-IOV VF devices by automatic failover to the paravirtual datapath when the VF is unplugged. -Here is a sample script that shows the steps to initiate live migration on -the source hypervisor. +Here is a sample script that shows the steps to initiate live migration from +the source hypervisor. Note: It is assumed that the VM is connected to a +software bridge 'br0' which has a single VF attached to it along with the vnet +device to the VM. This is not the VF that was passthrough'd to the VM (seen in +the vf.xml file). :: - # cat vf_xml + # cat vf.xml <interface type='hostdev' managed='yes'> <mac address='52:54:00:00:12:53'/> <source> <address type='pci' domain='0x0000' bus='0x42' slot='0x02' function='0x5'/> </source> - <address type='pci' domain='0x0000' bus='0x00' slot='0x0b' function='0x0'/> + <teaming type='transient' persistent='ua-backup0'/> </interface> - # Source Hypervisor + # Source Hypervisor migrate.sh #!/bin/bash - DOMAIN=fedora27-tap01 - PF=enp66s0f0 - VF_NUM=5 - TAP_IF=tap01 - VF_XML= + DOMAIN=vm-01 + PF=ens6np0 + VF=ens6v1 # VF attached to the bridge. + VF_NUM=1 + TAP_IF=vmtap01 # virtio-net interface in the VM. + VF_XML=vf.xml MAC=52:54:00:00:12:53 ZERO_MAC=00:00:00:00:00:00 + # Set the virtio-net interface up. virsh domif-setlink $DOMAIN $TAP_IF up - bridge fdb del $MAC dev $PF master - virsh detach-device $DOMAIN $VF_XML + + # Remove the VF that was passthrough'd to the VM. + virsh detach-device --live --config $DOMAIN $VF_XML + ip link set $PF vf $VF_NUM mac $ZERO_MAC - virsh migrate --live $DOMAIN qemu+ssh://$REMOTE_HOST/system + # Add FDB entry for traffic to continue going to the VM via + # the VF -> br0 -> vnet interface path. + bridge fdb add $MAC dev $VF + bridge fdb add $MAC dev $TAP_IF master + + # Migrate the VM + virsh migrate --live --persistent $DOMAIN qemu+ssh://$REMOTE_HOST/system + + # Clean up FDB entries after migration completes. + bridge fdb del $MAC dev $VF + bridge fdb del $MAC dev $TAP_IF master - # Destination Hypervisor +On the destination hypervisor, a shared bridge 'br0' is created before migration +starts, and a VF from the destination PF is added to the bridge. Similarly an +appropriate FDB entry is added. + +The following script is executed on the destination hypervisor once migration +completes, and it reattaches the VF to the VM and brings down the virtio-net +interface. + +:: + # reattach-vf.sh #!/bin/bash - virsh attach-device $DOMAIN $VF_XML - virsh domif-setlink $DOMAIN $TAP_IF down + bridge fdb del 52:54:00:00:12:53 dev ens36v0 + bridge fdb del 52:54:00:00:12:53 dev vmtap01 master + virsh attach-device --config --live vm01 vf.xml + virsh domif-setlink vm01 vmtap01 down diff --git a/Documentation/networking/phy.rst b/Documentation/networking/phy.rst index 571ba08386e7..d43da709bf40 100644 --- a/Documentation/networking/phy.rst +++ b/Documentation/networking/phy.rst @@ -237,6 +237,11 @@ negotiation results. Some of the interface modes are described below: +``PHY_INTERFACE_MODE_SMII`` + This is serial MII, clocked at 125MHz, supporting 100M and 10M speeds. + Some details can be found in + https://opencores.org/ocsvn/smii/smii/trunk/doc/SMII.pdf + ``PHY_INTERFACE_MODE_1000BASEX`` This defines the 1000BASE-X single-lane serdes link as defined by the 802.3 standard section 36. The link operates at a fixed bit rate of diff --git a/Documentation/networking/rds.rst b/Documentation/networking/rds.rst index 44936c27ab3a..498395f5fbcb 100644 --- a/Documentation/networking/rds.rst +++ b/Documentation/networking/rds.rst @@ -1,6 +1,6 @@ .. SPDX-License-Identifier: GPL-2.0 -== +=== RDS === diff --git a/Documentation/networking/timestamping.rst b/Documentation/networking/timestamping.rst index 80b13353254a..f5809206eb93 100644 --- a/Documentation/networking/timestamping.rst +++ b/Documentation/networking/timestamping.rst @@ -582,8 +582,8 @@ Time stamps for outgoing packets are to be generated as follows: and hardware timestamping is not possible (SKBTX_IN_PROGRESS not set). - As soon as the driver has sent the packet and/or obtained a hardware time stamp for it, it passes the time stamp back by - calling skb_hwtstamp_tx() with the original skb, the raw - hardware time stamp. skb_hwtstamp_tx() clones the original skb and + calling skb_tstamp_tx() with the original skb, the raw + hardware time stamp. skb_tstamp_tx() clones the original skb and adds the timestamps, therefore the original skb has to be freed now. If obtaining the hardware time stamp somehow fails, then the driver should not fall back to software time stamping. The rationale is that diff --git a/Documentation/power/opp.rst b/Documentation/power/opp.rst index e3cc4f349ea8..a7c03c470980 100644 --- a/Documentation/power/opp.rst +++ b/Documentation/power/opp.rst @@ -48,9 +48,9 @@ We can represent these as three OPPs as the following {Hz, uV} tuples: OPP library provides a set of helper functions to organize and query the OPP information. The library is located in drivers/opp/ directory and the header is located in include/linux/pm_opp.h. OPP library can be enabled by enabling -CONFIG_PM_OPP from power management menuconfig menu. OPP library depends on -CONFIG_PM as certain SoCs such as Texas Instrument's OMAP framework allows to -optionally boot at a certain OPP without needing cpufreq. +CONFIG_PM_OPP from power management menuconfig menu. Certain SoCs such as Texas +Instrument's OMAP framework allows to optionally boot at a certain OPP without +needing cpufreq. Typical usage of the OPP library is as follows:: @@ -75,8 +75,8 @@ operations until that OPP could be re-enabled if possible. OPP library facilitates this concept in its implementation. The following operational functions operate only on available opps: -opp_find_freq_{ceil, floor}, dev_pm_opp_get_voltage, dev_pm_opp_get_freq, -dev_pm_opp_get_opp_count +dev_pm_opp_find_freq_{ceil, floor}, dev_pm_opp_get_voltage, dev_pm_opp_get_freq, +dev_pm_opp_get_opp_count. dev_pm_opp_find_freq_exact is meant to be used to find the opp pointer which can then be used for dev_pm_opp_enable/disable functions to make an @@ -103,7 +103,7 @@ dev_pm_opp_add The OPP is defined using the frequency and voltage. Once added, the OPP is assumed to be available and control of its availability can be done with the dev_pm_opp_enable/disable functions. OPP library - internally stores and manages this information in the opp struct. + internally stores and manages this information in the dev_pm_opp struct. This function may be used by SoC framework to define a optimal list as per the demands of SoC usage environment. @@ -247,7 +247,7 @@ dev_pm_opp_disable 5. OPP Data Retrieval Functions =============================== Since OPP library abstracts away the OPP information, a set of functions to pull -information from the OPP structure is necessary. Once an OPP pointer is +information from the dev_pm_opp structure is necessary. Once an OPP pointer is retrieved using the search functions, the following functions can be used by SoC framework to retrieve the information represented inside the OPP layer. diff --git a/Documentation/power/runtime_pm.rst b/Documentation/power/runtime_pm.rst index d6bf84f061f4..65b86e487afe 100644 --- a/Documentation/power/runtime_pm.rst +++ b/Documentation/power/runtime_pm.rst @@ -265,6 +265,10 @@ defined in include/linux/pm.h: RPM_SUSPENDED, which means that each device is initially regarded by the PM core as 'suspended', regardless of its real hardware status + `enum rpm_status last_status;` + - the last runtime PM status of the device captured before disabling runtime + PM for it (invalid initially and when disable_depth is 0) + `unsigned int runtime_auto;` - if set, indicates that the user space has allowed the device driver to power manage the device at run time via the /sys/devices/.../power/control @@ -333,10 +337,12 @@ drivers/base/power/runtime.c and include/linux/pm_runtime.h: `int pm_runtime_resume(struct device *dev);` - execute the subsystem-level resume callback for the device; returns 0 on - success, 1 if the device's runtime PM status was already 'active' or - error code on failure, where -EAGAIN means it may be safe to attempt to - resume the device again in future, but 'power.runtime_error' should be - checked additionally, and -EACCES means that 'power.disable_depth' is + success, 1 if the device's runtime PM status is already 'active' (also if + 'power.disable_depth' is nonzero, but the status was 'active' when it was + changing from 0 to 1) or error code on failure, where -EAGAIN means it may + be safe to attempt to resume the device again in future, but + 'power.runtime_error' should be checked additionally, and -EACCES means + that the callback could not be run, because 'power.disable_depth' was different from 0 `int pm_runtime_resume_and_get(struct device *dev);` diff --git a/Documentation/process/5.Posting.rst b/Documentation/process/5.Posting.rst index 855a70b80269..bd36ecb29409 100644 --- a/Documentation/process/5.Posting.rst +++ b/Documentation/process/5.Posting.rst @@ -197,14 +197,29 @@ the build process, for example, or editor backup files) in the patch. The file "dontdiff" in the Documentation directory can help in this regard; pass it to diff with the "-X" option. -The tags mentioned above are used to describe how various developers have -been associated with the development of this patch. They are described in -detail in -the :ref:`Documentation/process/submitting-patches.rst <submittingpatches>` -document; what follows here is a brief summary. Each of these lines has -the format: +The tags already briefly mentioned above are used to provide insights how +the patch came into being. They are described in detail in the +:ref:`Documentation/process/submitting-patches.rst <submittingpatches>` +document; what follows here is a brief summary. -:: +One tag is used to refer to earlier commits which introduced problems fixed by +the patch:: + + Fixes: 1f2e3d4c5b6a ("The first line of the commit specified by the first 12 characters of its SHA-1 ID") + +Another tag is used for linking web pages with additional backgrounds or +details, for example a report about a bug fixed by the patch or a document +with a specification implemented by the patch:: + + Link: https://example.com/somewhere.html optional-other-stuff + +Many maintainers when applying a patch also add this tag to link to the +latest public review posting of the patch; often this is automatically done +by tools like b4 or a git hook like the one described in +'Documentation/maintainer/configure-git.rst'. + +A third kind of tag is used to document who was involved in the development of +the patch. Each of these uses this format:: tag: Full Name <email address> optional-other-stuff diff --git a/Documentation/process/changes.rst b/Documentation/process/changes.rst index b398b8576417..cf908d79666e 100644 --- a/Documentation/process/changes.rst +++ b/Documentation/process/changes.rst @@ -35,6 +35,7 @@ GNU make 3.81 make --version binutils 2.23 ld -v flex 2.5.35 flex --version bison 2.0 bison --version +pahole 1.16 pahole --version util-linux 2.10o fdformat --version kmod 13 depmod -V e2fsprogs 1.41.4 e2fsck -V @@ -108,6 +109,16 @@ Bison Since Linux 4.16, the build system generates parsers during build. This requires bison 2.0 or later. +pahole: +------- + +Since Linux 5.2, if CONFIG_DEBUG_INFO_BTF is selected, the build system +generates BTF (BPF Type Format) from DWARF in vmlinux, a bit later from kernel +modules as well. This requires pahole v1.16 or later. + +It is found in the 'dwarves' or 'pahole' distro packages or from +https://fedorapeople.org/~acme/dwarves/. + Perl ---- diff --git a/Documentation/process/submitting-patches.rst b/Documentation/process/submitting-patches.rst index da085d63af9b..31ea120ce531 100644 --- a/Documentation/process/submitting-patches.rst +++ b/Documentation/process/submitting-patches.rst @@ -14,7 +14,8 @@ works, see Documentation/process/development-process.rst. Also, read Documentation/process/submit-checklist.rst for a list of items to check before submitting code. If you are submitting a driver, also read Documentation/process/submitting-drivers.rst; for device -tree binding patches, read Documentation/process/submitting-patches.rst. +tree binding patches, read +Documentation/devicetree/bindings/submitting-patches.rst. This documentation assumes that you're using ``git`` to prepare your patches. If you're unfamiliar with ``git``, you would be well-advised to learn how to @@ -270,25 +271,6 @@ least a notification of the change, so that some information makes its way into the manual pages. User-space API changes should also be copied to linux-api@vger.kernel.org. -For small patches you may want to CC the Trivial Patch Monkey -trivial@kernel.org which collects "trivial" patches. Have a look -into the MAINTAINERS file for its current manager. - -Trivial patches must qualify for one of the following rules: - -- Spelling fixes in documentation -- Spelling fixes for errors which could break :manpage:`grep(1)` -- Warning fixes (cluttering with useless warnings is bad) -- Compilation fixes (only if they are actually correct) -- Runtime fixes (only if they actually fix things) -- Removing use of deprecated functions/macros -- Contact detail and documentation fixes -- Non-portable code replaced by portable code (even in arch-specific, - since people copy, as long as it's trivial) -- Any fix by the author/maintainer of the file (ie. patch monkey - in re-transmission mode) - - No MIME, no links, no compression, no attachments. Just plain text ------------------------------------------------------------------- diff --git a/Documentation/scheduler/sched-bwc.rst b/Documentation/scheduler/sched-bwc.rst index 173c14110c85..f166b182ff95 100644 --- a/Documentation/scheduler/sched-bwc.rst +++ b/Documentation/scheduler/sched-bwc.rst @@ -74,7 +74,6 @@ Quota, period and burst are managed within the cpu subsystem via cgroupfs. to cgroup v1. For cgroup v2, see :ref:`Documentation/admin-guide/cgroup-v2.rst <cgroup-v2-cpu>`. -- cpu.cfs_quota_us: the total available run-time within a period (in - cpu.cfs_quota_us: run-time replenished within a period (in microseconds) - cpu.cfs_period_us: the length of a period (in microseconds) - cpu.stat: exports throttling statistics [explained further below] @@ -135,7 +134,7 @@ cpu.stat: of the group have been throttled. - nr_bursts: Number of periods burst occurs. - burst_time: Cumulative wall-time (in nanoseconds) that any CPUs has used - above quota in respective periods + above quota in respective periods. This interface is read-only. @@ -238,7 +237,7 @@ Examples additionally, in case accumulation has been done. With 50ms period, 20ms quota will be equivalent to 40% of 1 CPU. - And 10ms burst will be equivalent to 20% of 1 CPU. + And 10ms burst will be equivalent to 20% of 1 CPU:: # echo 20000 > cpu.cfs_quota_us /* quota = 20ms */ # echo 50000 > cpu.cfs_period_us /* period = 50ms */ diff --git a/Documentation/security/self-protection.rst b/Documentation/security/self-protection.rst index f584fb74b4ff..910668e665cb 100644 --- a/Documentation/security/self-protection.rst +++ b/Documentation/security/self-protection.rst @@ -81,8 +81,7 @@ of the kernel, gaining the protection of the kernel's strict memory permissions as described above. For variables that are initialized once at ``__init`` time, these can -be marked with the (new and under development) ``__ro_after_init`` -attribute. +be marked with the ``__ro_after_init`` attribute. What remains are variables that are updated rarely (e.g. GDT). These will need another infrastructure (similar to the temporary exceptions diff --git a/Documentation/sound/hd-audio/models.rst b/Documentation/sound/hd-audio/models.rst index 0ea967d34583..d25335993e55 100644 --- a/Documentation/sound/hd-audio/models.rst +++ b/Documentation/sound/hd-audio/models.rst @@ -326,6 +326,8 @@ usi-headset Headset support on USI machines dual-codecs Lenovo laptops with dual codecs +alc285-hp-amp-init + HP laptops which require speaker amplifier initialization (ALC285) ALC680 ====== diff --git a/Documentation/sphinx-static/theme_overrides.css b/Documentation/sphinx-static/theme_overrides.css index 459ec5b29d68..f6f2b941a5d6 100644 --- a/Documentation/sphinx-static/theme_overrides.css +++ b/Documentation/sphinx-static/theme_overrides.css @@ -1,14 +1,14 @@ /* -*- coding: utf-8; mode: css -*- * * Sphinx HTML theme customization: read the doc - * + * Please don't add any color definition here, as the theme should + * work for both normal and dark modes. */ /* Improve contrast and increase size for easier reading. */ body { font-family: serif; - color: black; font-size: 100%; } @@ -16,17 +16,8 @@ h1, h2, .rst-content .toctree-wrapper p.caption, h3, h4, h5, h6, legend { font-family: sans-serif; } -.wy-menu-vertical li.current a { - color: #505050; -} - -.wy-menu-vertical li.on a, .wy-menu-vertical li.current > a { - color: #303030; -} - div[class^="highlight"] pre { font-family: monospace; - color: black; font-size: 100%; } @@ -104,13 +95,10 @@ div[class^="highlight"] pre { /* Menu selection and keystrokes */ span.menuselection { - color: blue; font-family: "Courier New", Courier, monospace } code.kbd, code.kbd span { - color: white; - background-color: darkblue; font-weight: bold; font-family: "Courier New", Courier, monospace } diff --git a/Documentation/sphinx-static/theme_rtd_colors.css b/Documentation/sphinx-static/theme_rtd_colors.css new file mode 100644 index 000000000000..55b6e1c3664b --- /dev/null +++ b/Documentation/sphinx-static/theme_rtd_colors.css @@ -0,0 +1,37 @@ +/* -*- coding: utf-8; mode: css -*- + * + * Sphinx HTML theme customization: color settings for RTD (non-dark) theme + * + */ + +/* Improve contrast and increase size for easier reading. */ + +body { + color: black; +} + +.wy-menu-vertical li.current a { + color: #505050; +} + +.wy-menu-vertical li.on a, .wy-menu-vertical li.current > a { + color: #303030; +} + +div[class^="highlight"] pre { + color: black; +} + +@media screen { + + /* Menu selection and keystrokes */ + + span.menuselection { + color: blue; + } + + code.kbd, code.kbd span { + color: white; + background-color: darkblue; + } +} diff --git a/Documentation/sphinx/automarkup.py b/Documentation/sphinx/automarkup.py index acf5473002f3..cc348b219fca 100644 --- a/Documentation/sphinx/automarkup.py +++ b/Documentation/sphinx/automarkup.py @@ -271,19 +271,30 @@ def get_c_namespace(app, docname): def auto_markup(app, doctree, name): global c_namespace c_namespace = get_c_namespace(app, name) + def text_but_not_a_reference(node): + # The nodes.literal test catches ``literal text``, its purpose is to + # avoid adding cross-references to functions that have been explicitly + # marked with cc:func:. + if not isinstance(node, nodes.Text) or isinstance(node.parent, nodes.literal): + return False + + child_of_reference = False + parent = node.parent + while parent: + if isinstance(parent, nodes.Referential): + child_of_reference = True + break + parent = parent.parent + return not child_of_reference + # # This loop could eventually be improved on. Someday maybe we # want a proper tree traversal with a lot of awareness of which # kinds of nodes to prune. But this works well for now. # - # The nodes.literal test catches ``literal text``, its purpose is to - # avoid adding cross-references to functions that have been explicitly - # marked with cc:func:. - # for para in doctree.traverse(nodes.paragraph): - for node in para.traverse(nodes.Text): - if not isinstance(node.parent, nodes.literal): - node.parent.replace(node, markup_refs(name, app, node)) + for node in para.traverse(condition=text_but_not_a_reference): + node.parent.replace(node, markup_refs(name, app, node)) def setup(app): app.connect('doctree-resolved', auto_markup) diff --git a/Documentation/sphinx/kernel_abi.py b/Documentation/sphinx/kernel_abi.py index efe760e410c4..4392b3cb4020 100644 --- a/Documentation/sphinx/kernel_abi.py +++ b/Documentation/sphinx/kernel_abi.py @@ -104,7 +104,7 @@ class KernelCmd(Directive): return nodeList def runCmd(self, cmd, **kwargs): - u"""Run command ``cmd`` and return it's stdout as unicode.""" + u"""Run command ``cmd`` and return its stdout as unicode.""" try: proc = subprocess.Popen( diff --git a/Documentation/sphinx/kernel_feat.py b/Documentation/sphinx/kernel_feat.py index c91ea2b27697..8138d69a6987 100644 --- a/Documentation/sphinx/kernel_feat.py +++ b/Documentation/sphinx/kernel_feat.py @@ -106,7 +106,7 @@ class KernelFeat(Directive): return nodeList def runCmd(self, cmd, **kwargs): - u"""Run command ``cmd`` and return it's stdout as unicode.""" + u"""Run command ``cmd`` and return its stdout as unicode.""" try: proc = subprocess.Popen( diff --git a/Documentation/spi/pxa2xx.rst b/Documentation/spi/pxa2xx.rst index 6312968acfe9..6347580826be 100644 --- a/Documentation/spi/pxa2xx.rst +++ b/Documentation/spi/pxa2xx.rst @@ -101,8 +101,7 @@ device. All fields are optional. u8 rx_threshold; u8 dma_burst_size; u32 timeout; - u8 enable_loopback; - void (*cs_control)(u32 command); + int gpio_cs; }; The "pxa2xx_spi_chip.tx_threshold" and "pxa2xx_spi_chip.rx_threshold" fields are @@ -128,16 +127,6 @@ dependent on the SPI bus speed ("spi_board_info.max_speed_hz") and the specific slave device. Please note that the PXA2xx SSP 1 does not support trailing byte timeouts and must busy-wait any trailing bytes. -The "pxa2xx_spi_chip.enable_loopback" field is used to place the SSP porting -into internal loopback mode. In this mode the SSP controller internally -connects the SSPTX pin to the SSPRX pin. This is useful for initial setup -testing. - -The "pxa2xx_spi_chip.cs_control" field is used to point to a board specific -function for asserting/deasserting a slave device chip select. If the field is -NULL, the pxa2xx_spi master controller driver assumes that the SSP port is -configured to use GPIO or SSPFRM instead. - NOTE: the SPI driver cannot control the chip select if SSPFRM is used, so the chipselect is dropped after each spi_transfer. Most devices need chip select asserted around the complete message. Use SSPFRM as a GPIO (through a descriptor) @@ -152,30 +141,12 @@ field. Below is a sample configuration using the PXA255 NSSP. :: - /* Chip Select control for the CS8415A SPI slave device */ - static void cs8415a_cs_control(u32 command) - { - if (command & PXA2XX_CS_ASSERT) - GPCR(2) = GPIO_bit(2); - else - GPSR(2) = GPIO_bit(2); - } - - /* Chip Select control for the CS8405A SPI slave device */ - static void cs8405a_cs_control(u32 command) - { - if (command & PXA2XX_CS_ASSERT) - GPCR(3) = GPIO_bit(3); - else - GPSR(3) = GPIO_bit(3); - } - static struct pxa2xx_spi_chip cs8415a_chip_info = { .tx_threshold = 8, /* SSP hardward FIFO threshold */ .rx_threshold = 8, /* SSP hardward FIFO threshold */ .dma_burst_size = 8, /* Byte wide transfers used so 8 byte bursts */ .timeout = 235, /* See Intel documentation */ - .cs_control = cs8415a_cs_control, /* Use external chip select */ + .gpio_cs = 2, /* Use external chip select */ }; static struct pxa2xx_spi_chip cs8405a_chip_info = { @@ -183,7 +154,7 @@ field. Below is a sample configuration using the PXA255 NSSP. .rx_threshold = 8, /* SSP hardward FIFO threshold */ .dma_burst_size = 8, /* Byte wide transfers used so 8 byte bursts */ .timeout = 235, /* See Intel documentation */ - .cs_control = cs8405a_cs_control, /* Use external chip select */ + .gpio_cs = 3, /* Use external chip select */ }; static struct spi_board_info streetracer_spi_board_info[] __initdata = { diff --git a/Documentation/spi/spidev.rst b/Documentation/spi/spidev.rst index f05dbc5ccdbc..369c657ba435 100644 --- a/Documentation/spi/spidev.rst +++ b/Documentation/spi/spidev.rst @@ -29,21 +29,49 @@ of the driver stack) that are not accessible to userspace. DEVICE CREATION, DRIVER BINDING =============================== -The simplest way to arrange to use this driver is to just list it in the -spi_board_info for a device as the driver it should use: the "modalias" -entry is "spidev", matching the name of the driver exposing this API. -Set up the other device characteristics (bits per word, SPI clocking, -chipselect polarity, etc) as usual, so you won't always need to override -them later. - -(Sysfs also supports userspace driven binding/unbinding of drivers to -devices. That mechanism might be supported here in the future.) - -When you do that, the sysfs node for the SPI device will include a child -device node with a "dev" attribute that will be understood by udev or mdev. -(Larger systems will have "udev". Smaller ones may configure "mdev" into -busybox; it's less featureful, but often enough.) For a SPI device with -chipselect C on bus B, you should see: + +The spidev driver contains lists of SPI devices that are supported for +the different hardware topology representations. + +The following are the SPI device tables supported by the spidev driver: + + - struct spi_device_id spidev_spi_ids[]: list of devices that can be + bound when these are defined using a struct spi_board_info with a + .modalias field matching one of the entries in the table. + + - struct of_device_id spidev_dt_ids[]: list of devices that can be + bound when these are defined using a Device Tree node that has a + compatible string matching one of the entries in the table. + + - struct acpi_device_id spidev_acpi_ids[]: list of devices that can + be bound when these are defined using a ACPI device object with a + _HID matching one of the entries in the table. + +You are encouraged to add an entry for your SPI device name to relevant +tables, if these don't already have an entry for the device. To do that, +post a patch for spidev to the linux-spi@vger.kernel.org mailing list. + +It used to be supported to define an SPI device using the "spidev" name. +For example, as .modalias = "spidev" or compatible = "spidev". But this +is no longer supported by the Linux kernel and instead a real SPI device +name as listed in one of the tables must be used. + +Not having a real SPI device name will lead to an error being printed and +the spidev driver failing to probe. + +Sysfs also supports userspace driven binding/unbinding of drivers to +devices that do not bind automatically using one of the tables above. +To make the spidev driver bind to such a device, use the following: + + echo spidev > /sys/bus/spi/devices/spiB.C/driver_override + echo spiB.C > /sys/bus/spi/drivers/spidev/bind + +When the spidev driver is bound to a SPI device, the sysfs node for the +device will include a child device node with a "dev" attribute that will +be understood by udev or mdev (udev replacement from BusyBox; it's less +featureful, but often enough). + +For a SPI device with chipselect C on bus B, you should see: /dev/spidevB.C ... character special device, major number 153 with diff --git a/Documentation/staging/tee.rst b/Documentation/staging/tee.rst index 4d4b5f889603..3c63d8dcd61e 100644 --- a/Documentation/staging/tee.rst +++ b/Documentation/staging/tee.rst @@ -184,6 +184,36 @@ order to support device enumeration. In other words, OP-TEE driver invokes this application to retrieve a list of Trusted Applications which can be registered as devices on the TEE bus. +OP-TEE notifications +-------------------- + +There are two kinds of notifications that secure world can use to make +normal world aware of some event. + +1. Synchronous notifications delivered with ``OPTEE_RPC_CMD_NOTIFICATION`` + using the ``OPTEE_RPC_NOTIFICATION_SEND`` parameter. +2. Asynchronous notifications delivered with a combination of a non-secure + edge-triggered interrupt and a fast call from the non-secure interrupt + handler. + +Synchronous notifications are limited by depending on RPC for delivery, +this is only usable when secure world is entered with a yielding call via +``OPTEE_SMC_CALL_WITH_ARG``. This excludes such notifications from secure +world interrupt handlers. + +An asynchronous notification is delivered via a non-secure edge-triggered +interrupt to an interrupt handler registered in the OP-TEE driver. The +actual notification value are retrieved with the fast call +``OPTEE_SMC_GET_ASYNC_NOTIF_VALUE``. Note that one interrupt can represent +multiple notifications. + +One notification value ``OPTEE_SMC_ASYNC_NOTIF_VALUE_DO_BOTTOM_HALF`` has a +special meaning. When this value is received it means that normal world is +supposed to make a yielding call ``OPTEE_MSG_CMD_DO_BOTTOM_HALF``. This +call is done from the thread assisting the interrupt handler. This is a +building block for OP-TEE OS in secure world to implement the top half and +bottom half style of device drivers. + AMD-TEE driver ============== diff --git a/Documentation/timers/no_hz.rst b/Documentation/timers/no_hz.rst index 20ad23a6c618..f8786be15183 100644 --- a/Documentation/timers/no_hz.rst +++ b/Documentation/timers/no_hz.rst @@ -184,16 +184,12 @@ There are situations in which idle CPUs cannot be permitted to enter either dyntick-idle mode or adaptive-tick mode, the most common being when that CPU has RCU callbacks pending. -The CONFIG_RCU_FAST_NO_HZ=y Kconfig option may be used to cause such CPUs -to enter dyntick-idle mode or adaptive-tick mode anyway. In this case, -a timer will awaken these CPUs every four jiffies in order to ensure -that the RCU callbacks are processed in a timely fashion. - -Another approach is to offload RCU callback processing to "rcuo" kthreads +Avoid this by offloading RCU callback processing to "rcuo" kthreads using the CONFIG_RCU_NOCB_CPU=y Kconfig option. The specific CPUs to offload may be selected using The "rcu_nocbs=" kernel boot parameter, which takes a comma-separated list of CPUs and CPU ranges, for example, -"1,3-5" selects CPUs 1, 3, 4, and 5. +"1,3-5" selects CPUs 1, 3, 4, and 5. Note that CPUs specified by +the "nohz_full" kernel boot parameter are also offloaded. The offloaded CPUs will never queue RCU callbacks, and therefore RCU never prevents offloaded CPUs from entering either dyntick-idle mode diff --git a/Documentation/trace/boottime-trace.rst b/Documentation/trace/boottime-trace.rst index 6dcfbc64014d..d594597201fd 100644 --- a/Documentation/trace/boottime-trace.rst +++ b/Documentation/trace/boottime-trace.rst @@ -131,9 +131,7 @@ Ftrace Histogram Options Since it is too long to write a histogram action as a string for per-event action option, there are tree-style options under per-event 'hist' subkey for the histogram actions. For the detail of the each parameter, -please read the event histogram document [3]_. - -.. [3] See :ref:`Documentation/trace/histogram.rst <histogram>` +please read the event histogram document (Documentation/trace/histogram.rst) ftrace.[instance.INSTANCE.]event.GROUP.EVENT.hist.[N.]keys = KEY1[, KEY2[...]] Set histogram key parameters. (Mandatory) diff --git a/Documentation/translations/it_IT/process/submitting-patches.rst b/Documentation/translations/it_IT/process/submitting-patches.rst index c2fb712a1377..4fb5b3aa306d 100644 --- a/Documentation/translations/it_IT/process/submitting-patches.rst +++ b/Documentation/translations/it_IT/process/submitting-patches.rst @@ -276,25 +276,6 @@ cosicché l'informazione possa trovare la sua strada nel manuale. Le modifiche all'API dello spazio utente dovrebbero essere inviate in copia anche a linux-api@vger.kernel.org. -Per le piccole patch potreste aggiungere in CC l'indirizzo -*Trivial Patch Monkey trivial@kernel.org* che ha lo scopo di raccogliere -le patch "banali". Date uno sguardo al file MAINTAINERS per vedere chi -è l'attuale amministratore. - -Le patch banali devono rientrare in una delle seguenti categorie: - -- errori grammaticali nella documentazione -- errori grammaticali negli errori che potrebbero rompere :manpage:`grep(1)` -- correzione di avvisi di compilazione (riempirsi di avvisi inutili è negativo) -- correzione di errori di compilazione (solo se correggono qualcosa sul serio) -- rimozione di funzioni/macro deprecate -- sostituzione di codice non potabile con uno portabile (anche in codice - specifico per un'architettura, dato che le persone copiano, fintanto che - la modifica sia banale) -- qualsiasi modifica dell'autore/manutentore di un file (in pratica - "patch monkey" in modalità ritrasmissione) - - Niente: MIME, links, compressione, allegati. Solo puro testo ------------------------------------------------------------- diff --git a/Documentation/translations/ja_JP/SubmittingPatches b/Documentation/translations/ja_JP/SubmittingPatches index 6854f5add72e..0d308edef781 100644 --- a/Documentation/translations/ja_JP/SubmittingPatches +++ b/Documentation/translations/ja_JP/SubmittingPatches @@ -208,21 +208,6 @@ VGER.KERNEL.ORG でホスティングされているメーリングリストの たとえ、メンテナが #5 で反応がなかったとしても、メンテナのコードに変更を 加えたときには、いつもメンテナに CC するのを忘れないようにしてください。 -小さなパッチであれば、Trivial Patch Monkey(ちょっとしたパッチを集めている) -<trivial@kernel.org>に CC してもいいです。その現管理者については MAINTAINERS -ファイルを見てください。ちょっとしたパッチとは以下のルールのどれか1つを満たして -いなければなりません。 - ・ドキュメントのスペルミスの修正 - ・grep(1) コマンドによる検索を困難にしているスペルの修正 - ・コンパイル時の警告の修正(無駄な警告が散乱することは好ましくないた - めです) - ・コンパイル問題の修正(それらの修正が本当に正しい場合に限る) - ・実行時の問題の修正(それらの修正が本当に問題を修正している場合に限る) - ・廃止予定の関数やマクロを使用しているコードの除去(例 check_region ) - ・問い合わせ先やドキュメントの修正 - ・移植性のないコードから移植性のあるコードへの置き換え(小さい範囲で - あればアーキテクチャ特有のことでも他の人がコピーできます) - ・作者やメンテナによる修正(すなわち patch monkey の再転送モード) 7) MIME やリンクや圧縮ファイルや添付ファイルではなくプレインテキストのみ diff --git a/Documentation/translations/zh_CN/PCI/index.rst b/Documentation/translations/zh_CN/PCI/index.rst index 5c96017e9f41..16acb2bd9b58 100644 --- a/Documentation/translations/zh_CN/PCI/index.rst +++ b/Documentation/translations/zh_CN/PCI/index.rst @@ -22,13 +22,14 @@ Linux PCI总线子系统 :numbered: pci - -Todolist: - pciebus-howto pci-iov-howto msi-howto sysfs-pci + + +Todolist: + acpi-info pci-error-recovery pcieaer-howto diff --git a/Documentation/translations/zh_CN/PCI/msi-howto.rst b/Documentation/translations/zh_CN/PCI/msi-howto.rst new file mode 100644 index 000000000000..7ea4d50cdad2 --- /dev/null +++ b/Documentation/translations/zh_CN/PCI/msi-howto.rst @@ -0,0 +1,233 @@ +.. SPDX-License-Identifier: GPL-2.0 +.. include:: <isonum.txt> +.. include:: ../disclaimer-zh_CN.rst + +:Original: Documentation/PCI/msi-howto.rst + +:翻译: + + 司延腾 Yanteng Si <siyanteng@loongson.cn> + +:校译: + + + +=========== +MSI驱动指南 +=========== + +:作者: Tom L Nguyen; Martine Silbermann; Matthew Wilcox + +:版权: 2003, 2008 Intel Corporation + +关于本指南 +========== + +本指南介绍了消息标记中断（MSI）的基本知识，使用MSI相对于传统中断机制的优势，如何 +改变你的驱动程序以使用MSI或MSI-X，以及在设备不支持MSI时可以尝试的一些基本诊断方法。 + + +什么是MSI? +========== + +信息信号中断是指从设备写到一个特殊的地址，导致CPU接收到一个中断。 + +MSI能力首次在PCI 2.2中规定，后来在PCI 3.0中得到增强，允许对每个中断进行单独屏蔽。 +MSI-X功能也随着PCI 3.0被引入。它比MSI支持每个设备更多的中断，并允许独立配置中断。 + +设备可以同时支持MSI和MSI-X，但一次只能启用一个。 + + +为什么用MSI? +============ + +有三个原因可以说明为什么使用MSI比传统的基于针脚的中断有优势。 + +基于针脚的PCI中断通常在几个设备之间共享。为了支持这一点，内核必须调用每个与中断相 +关的中断处理程序，这导致了整个系统性能的降低。MSI从不共享，所以这个问题不会出现。 + +当一个设备将数据写入内存，然后引发一个基于引脚的中断时，有可能在所有的数据到达内存 +之前，中断就已经到达了（这在PCI-PCI桥后面的设备中变得更有可能）。为了确保所有的数 +据已经到达内存中，中断处理程序必须在引发中断的设备上读取一个寄存器。PCI事务排序规 +则要求所有的数据在返回寄存器的值之前到达内存。使用MSI可以避免这个问题，因为中断产 +生的写入不能通过数据写入，所以当中断发生时，驱动程序知道所有的数据已经到达内存中。 + +PCI设备每个功能只能支持一个基于引脚的中断。通常情况下，驱动程序必须查询设备以找出 +发生了什么事件，这就减慢了对常见情况的中断处理。有了MSI，设备可以支持更多的中断， +允许每个中断被专门用于不同的目的。一种可能的设计是给不经常发生的情况（如错误）提供 +自己的中断，这使得驱动程序可以更有效地处理正常的中断处理路径。其他可能的设计包括给 +网卡的每个数据包队列或存储控制器的每个端口提供一个中断。 + + +如何使用MSI +=========== + +PCI设备被初始化为使用基于引脚的中断。设备驱动程序必须将设备设置为使用MSI或MSI-X。 +并非所有的机器都能正确地支持MSI，对于这些机器，下面描述的API将简单地失败，设备将 +继续使用基于引脚的中断。 + +加入内核对MSI的支持 +------------------- + +为了支持MSI或MSI-X，内核在构建时必须启用CONFIG_PCI_MSI选项。这个选项只在某些架 +构上可用，而且它可能取决于其他一些选项的设置。例如，在x86上，你必须同时启用X86_UP_APIC +或SMP，才能看到CONFIG_PCI_MSI选项。 + +使用MSI +------- + +大部分沉重的工作是在PCI层为驱动程序完成的。驱动程序只需要请求PCI层为这个设备设置 +MSI功能。 + +要自动使用MSI或MSI-X中断向量，请使用以下函数:: + + int pci_alloc_irq_vectors(struct pci_dev *dev, unsigned int min_vecs, + unsigned int max_vecs, unsigned int flags); + +它为一个PCI设备分配最多至max_vecs的中断向量。它返回分配的向量数量或一个负的错误。 +如果设备对最小数量的向量有要求，驱动程序可以传递一个min_vecs参数，设置为这个限制， +如果PCI核不能满足最小数量的向量，将返回-ENOSPC。 + +flags参数用来指定设备和驱动程序可以使用哪种类型的中断（PCI_IRQ_LEGACY, PCI_IRQ_MSI, +PCI_IRQ_MSIX）。一个方便的短语（PCI_IRQ_ALL_TYPES）也可以用来要求任何可能的中断类型。 +如果PCI_IRQ_AFFINITY标志被设置，pci_alloc_irq_vectors()将把中断分散到可用的CPU上。 + +要获得传递给require_irq()和free_irq()的Linux IRQ号码和向量，请使用以下函数:: + + int pci_irq_vector(struct pci_dev *dev, unsigned int nr); + +在删除设备之前，应使用以下功能释放任何已分配的资源:: + + void pci_free_irq_vectors(struct pci_dev *dev); + +如果一个设备同时支持MSI-X和MSI功能，这个API将优先使用MSI-X，而不是MSI。MSI-X支 +持1到2048之间的任何数量的中断。相比之下，MSI被限制为最多32个中断（而且必须是2的幂）。 +此外，MSI中断向量必须连续分配，所以系统可能无法为MSI分配像MSI-X那样多的向量。在一 +些平台上，MSI中断必须全部针对同一组CPU，而MSI-X中断可以全部针对不同的CPU。 + +如果一个设备既不支持MSI-X，也不支持MSI，它就会退回到一个传统的IRQ向量。 + +MSI或MSI-X中断的典型用法是分配尽可能多的向量，可能达到设备支持的极限。如果nvec大于 +设备支持的数量，它将自动被限制在支持的限度内，所以没有必要事先查询支持的向量的数量。:: + + nvec = pci_alloc_irq_vectors(pdev, 1, nvec, PCI_IRQ_ALL_TYPES) + if (nvec < 0) + goto out_err; + +如果一个驱动程序不能或不愿意处理可变数量的MSI中断，它可以要求一个特定数量的中断，将该 +数量作为“min_vecs“和“max_vecs“参数传递给pci_alloc_irq_vectors()函数。:: + + ret = pci_alloc_irq_vectors(pdev, nvec, nvec, PCI_IRQ_ALL_TYPES); + if (ret < 0) + goto out_err; + +上述请求类型的最臭名昭著的例子是为一个设备启用单一的MSI模式。它可以通过传递两个1作为 +'min_vecs'和'max_vecs'来实现:: + + ret = pci_alloc_irq_vectors(pdev, 1, 1, PCI_IRQ_ALL_TYPES); + if (ret < 0) + goto out_err; + +一些设备可能不支持使用传统的线路中断，在这种情况下，驱动程序可以指定只接受MSI或MSI-X。:: + + nvec = pci_alloc_irq_vectors(pdev, 1, nvec, PCI_IRQ_MSI | PCI_IRQ_MSIX); + if (nvec < 0) + goto out_err; + +传统API +----------- + +以下用于启用和禁用MSI或MSI-X中断的旧API不应该在新代码中使用:: + + pci_enable_msi() /* deprecated */ + pci_disable_msi() /* deprecated */ + pci_enable_msix_range() /* deprecated */ + pci_enable_msix_exact() /* deprecated */ + pci_disable_msix() /* deprecated */ + +此外，还有一些API来提供支持的MSI或MSI-X向量的数量：pci_msi_vec_count()和 +pci_msix_vec_count()。一般来说，应该避免使用这些方法，而是让pci_alloc_irq_vectors() +来限制向量的数量。如果你对向量的数量有合法的特殊用例，我们可能要重新审视这个决定， +并增加一个pci_nr_irq_vectors()助手，透明地处理MSI和MSI-X。 + +使用MSI时需要考虑的因素 +----------------------- + +自旋锁 +~~~~~~ + +大多数设备驱动程序都有一个每的自旋锁，在中断处理程序中被占用。对于基于引脚的中断 +或单一的MSI，没有必要禁用中断（Linux保证同一中断不会被重新输入）。如果一个设备 +使用多个中断，驱动程序必须在锁被持有的时候禁用中断。如果设备发出一个不同的中断， +驱动程序将死锁，试图递归地获取自旋锁。这种死锁可以通过使用spin_lock_irqsave() +或spin_lock_irq()来避免，它们可以禁用本地中断并获取锁（见《不可靠的锁定指南》）。 + +如何判断一个设备上是否启用了MSI/MSI-X +------------------------------------- + +使用“lspci -v“（以root身份）可能会显示一些具有“MSI“、“Message Signalled Interrupts“ +或“MSI-X“功能的设备。这些功能中的每一个都有一个“启用“标志，后面是“+“（启用） +或“-“（禁用）。 + + +MSI特性 +======= + +众所周知，一些PCI芯片组或设备不支持MSI。PCI协议栈提供了三种禁用MSI的方法: + +1. 全局的 +2. 在一个特定的桥后面的所有设备上 +3. 在单一设备上 + +全局禁用MSI +----------- + +一些主控芯片组根本无法正确支持MSI。如果我们幸运的话，制造商知道这一点，并在 +ACPI FADT表中指明了它。在这种情况下，Linux会自动禁用MSI。有些板卡在表中没 +有包括这一信息，因此我们必须自己检测它们。完整的列表可以在drivers/pci/quirks.c +中的quirk_disable_all_msi()函数附近找到。 + +如果你有一块有MSI问题的板子，你可以在内核命令行中传递pci=nomsi来禁用所有设 +备上的MSI。你最好把问题报告给linux-pci@vger.kernel.org，包括完整的 +“lspci -v“，这样我们就可以把这些怪癖添加到内核中。 + +禁用桥下的MSI +------------- + +一些PCI桥接器不能在总线之间正确地路由MSI。在这种情况下，必须在桥接器后面的所 +有设备上禁用MSI。 + +一些桥接器允许你通过改变PCI配置空间的一些位来启用MSI（特别是Hypertransport +芯片组，如nVidia nForce和Serverworks HT2000）。与主机芯片组一样，Linux大 +多知道它们，如果可以的话，会自动启用MSI。如果你有一个Linux不知道的网桥，你可以 +用你知道的任何方法在配置空间中启用MSI，然后通过以下方式在该网桥上启用MSI:: + + echo 1 > /sys/bus/pci/devices/$bridge/msi_bus + +其中$bridge是你所启用的桥的PCI地址（例如0000:00:0e.0）。 + +要禁用MSI，请回显0而不是1。改变这个值应该谨慎进行，因为它可能会破坏这个桥下面所 +有设备的中断处理。 + +同样，请通知 linux-pci@vger.kernel.org 任何需要特殊处理的桥。 + +在单一设备上关闭MSIs +-------------------- + +众所周知，有些设备的MSI实现是有问题的。通常情况下，这是在单个设备驱动程序中处理的， +但偶尔也有必要用一个古怪的方法来处理。一些驱动程序有一个选项可以禁用MSI的使用。虽然 +这对驱动程序的作者来说是一个方便的变通办法，但这不是一个好的做法，不应该被模仿。 + +寻找设备上MSI被禁用的原因 +------------------------- + +从以上三个部分，你可以看到有许多原因导致MSI没有在某个设备上被启用。你的第一步应该是 +仔细检查你的dmesg以确定你的机器是否启用了MSI。你还应该检查你的.config以确定你已经 +启用了CONFIG_PCI_MSI。 + +然后，“lspci -t“给出一个设备上面的网列表。读取 ``/sys/bus/pci/devices/*/msi_bus`` +将告诉你MSI是否被启用（1）或禁用（0）。如果在任何属于PCI根和设备之间的桥的msi_bus +文件中发现0，说明MSI被禁用。 + +也需要检查设备驱动程序，看它是否支持MSI。例如，它可能包含对带有PCI_IRQ_MSI或 +PCI_IRQ_MSIX标志的pci_alloc_irq_vectors（）的调用。 diff --git a/Documentation/translations/zh_CN/PCI/pci-iov-howto.rst b/Documentation/translations/zh_CN/PCI/pci-iov-howto.rst new file mode 100644 index 000000000000..fbc83dfdcead --- /dev/null +++ b/Documentation/translations/zh_CN/PCI/pci-iov-howto.rst @@ -0,0 +1,170 @@ +.. SPDX-License-Identifier: GPL-2.0 +.. include:: <isonum.txt> +.. include:: ../disclaimer-zh_CN.rst + +:Original: Documentation/PCI/pci-iov-howto.rst + +:翻译: + + 司延腾 Yanteng Si <siyanteng@loongson.cn> + +:校译: + + + +.. _cn_pci-iov-howto: + +========================== +PCI Express I/O 虚拟化指南 +========================== + +:版权: |copy| 2009 Intel Corporation +:作者: - Yu Zhao <yu.zhao@intel.com> + - Donald Dutile <ddutile@redhat.com> + +概述 +==== + +什么是SR-IOV +------------ + +单根I/O虚拟化（SR-IOV）是一种PCI Express扩展功能，它使一个物理设备显示为多个 +虚拟设备。物理设备被称为物理功能（PF），而虚拟设备被称为虚拟功能（VF）。VF的分 +配可以由PF通过封装在该功能中的寄存器动态控制。默认情况下，该功能未被启用，PF表 +现为传统的PCIe设备。一旦开启，每个VF的PCI配置空间都可以通过自己的总线、设备和 +功能编号（路由ID）来访问。而且每个VF也有PCI内存空间，用于映射其寄存器集。VF设 +备驱动程序对寄存器集进行操作，这样它就可以发挥功能，并作为一个真正的现有PCI设备 +出现。 + +使用指南 +======== + +我怎样才能启用SR-IOV功能 +------------------------ + +有多种方法可用于SR-IOV的启用。在第一种方法中，设备驱动（PF驱动）将通过SR-IOV +核心提供的API控制功能的启用和禁用。如果硬件具有SR-IOV能力，加载其PF驱动器将启 +用它和与PF相关的所有VF。一些PF驱动需要设置一个模块参数，以确定要启用的VF的数量。 +在第二种方法中，对sysfs文件sriov_numvfs的写入将启用和禁用与PCIe PF相关的VF。 +这种方法实现了每个PF的VF启用/禁用值，而第一种方法则适用于同一设备的所有PF。此外， +PCI SRIOV核心支持确保启用/禁用操作是有效的，以减少同一检查在多个驱动程序中的重 +复，例如，如果启用VF，检查numvfs == 0，确保numvfs <= totalvfs。 +第二种方法是对新的/未来的VF设备的推荐方法。 + +我怎样才能使用虚拟功能 +---------------------- + +在内核中，VF被视为热插拔的PCI设备，所以它们应该能够以与真正的PCI设备相同的方式 +工作。VF需要的设备驱动与普通PCI设备的驱动相同。 + +开发者指南 +========== + +SR-IOV API +---------- + +用来开启SR-IOV功能: + +(a) 对于第一种方法，在驱动程序中:: + + int pci_enable_sriov(struct pci_dev *dev, int nr_virtfn); + +nr_virtfn'是要启用的VF的编号。 + +(b) 对于第二种方法，从sysfs:: + + echo 'nr_virtfn' > \ + /sys/bus/pci/devices/<DOMAIN:BUS:DEVICE.FUNCTION>/sriov_numvfs + +用来关闭SR-IOV功能: + +(a) 对于第一种方法，在驱动程序中:: + + void pci_disable_sriov(struct pci_dev *dev); + +(b) 对于第二种方法，从sysfs:: + + echo 0 > \ + /sys/bus/pci/devices/<DOMAIN:BUS:DEVICE.FUNCTION>/sriov_numvfs + +要想通过主机上的兼容驱动启用自动探测VF，在启用SR-IOV功能之前运行下面的命令。这 +是默认的行为。 +:: + + echo 1 > \ + /sys/bus/pci/devices/<DOMAIN:BUS:DEVICE.FUNCTION>/sriov_drivers_autoprobe + +要禁止主机上的兼容驱动自动探测VF，请在启用SR-IOV功能之前运行以下命令。更新这个 +入口不会影响已经被探测的VF。 +:: + + echo 0 > \ + /sys/bus/pci/devices/<DOMAIN:BUS:DEVICE.FUNCTION>/sriov_drivers_autoprobe + +用例 +---- + +下面的代码演示了SR-IOV API的用法 +:: + + static int dev_probe(struct pci_dev *dev, const struct pci_device_id *id) + { + pci_enable_sriov(dev, NR_VIRTFN); + + ... + + return 0; + } + + static void dev_remove(struct pci_dev *dev) + { + pci_disable_sriov(dev); + + ... + } + + static int dev_suspend(struct pci_dev *dev, pm_message_t state) + { + ... + + return 0; + } + + static int dev_resume(struct pci_dev *dev) + { + ... + + return 0; + } + + static void dev_shutdown(struct pci_dev *dev) + { + ... + } + + static int dev_sriov_configure(struct pci_dev *dev, int numvfs) + { + if (numvfs > 0) { + ... + pci_enable_sriov(dev, numvfs); + ... + return numvfs; + } + if (numvfs == 0) { + .... + pci_disable_sriov(dev); + ... + return 0; + } + } + + static struct pci_driver dev_driver = { + .name = "SR-IOV Physical Function driver", + .id_table = dev_id_table, + .probe = dev_probe, + .remove = dev_remove, + .suspend = dev_suspend, + .resume = dev_resume, + .shutdown = dev_shutdown, + .sriov_configure = dev_sriov_configure, + }; diff --git a/Documentation/translations/zh_CN/PCI/pciebus-howto.rst b/Documentation/translations/zh_CN/PCI/pciebus-howto.rst new file mode 100644 index 000000000000..65c4301f12cd --- /dev/null +++ b/Documentation/translations/zh_CN/PCI/pciebus-howto.rst @@ -0,0 +1,192 @@ +.. SPDX-License-Identifier: GPL-2.0 +.. include:: <isonum.txt> +.. include:: ../disclaimer-zh_CN.rst + +:Original: Documentation/PCI/pciebus-howto.rst + +:翻译: + + 司延腾 Yanteng Si <siyanteng@loongson.cn> + +:校译: + + + +.. _cn_pciebus-howto: + +=========================== +PCI Express端口总线驱动指南 +=========================== + +:作者: Tom L Nguyen tom.l.nguyen@intel.com 11/03/2004 +:版权: |copy| 2004 Intel Corporation + +关于本指南 +========== + +本指南介绍了PCI Express端口总线驱动程序的基本知识，并提供了如何使服务驱 +动程序在PCI Express端口总线驱动程序中注册/取消注册的介绍。 + + +什么是PCI Express端口总线驱动程序 +================================= + +一个PCI Express端口是一个逻辑的PCI-PCI桥结构。有两种类型的PCI Express端 +口：根端口和交换端口。根端口从PCI Express根综合体发起一个PCI Express链接， +交换端口将PCI Express链接连接到内部逻辑PCI总线。交换机端口，其二级总线代表 +交换机的内部路由逻辑，被称为交换机的上行端口。交换机的下行端口是从交换机的内部 +路由总线桥接到代表来自PCI Express交换机的下游PCI Express链接的总线。 + +一个PCI Express端口可以提供多达四个不同的功能，在本文中被称为服务，这取决于 +其端口类型。PCI Express端口的服务包括本地热拔插支持（HP）、电源管理事件支持（PME）、 +高级错误报告支持（AER）和虚拟通道支持（VC）。这些服务可以由一个复杂的驱动程序 +处理，也可以单独分布并由相应的服务驱动程序处理。 + +为什么要使用PCI Express端口总线驱动程序？ +========================================= + +在现有的Linux内核中，Linux设备驱动模型允许一个物理设备只由一个驱动处理。 +PCI Express端口是一个具有多个不同服务的PCI-PCI桥设备。为了保持一个干净和简 +单的解决方案，每个服务都可以有自己的软件服务驱动。在这种情况下，几个服务驱动将 +竞争一个PCI-PCI桥设备。例如，如果PCI Express根端口的本机热拔插服务驱动程序 +首先被加载，它就会要求一个PCI-PCI桥根端口。因此，内核不会为该根端口加载其他服 +务驱动。换句话说，使用当前的驱动模型，不可能让多个服务驱动同时加载并运行在 +PCI-PCI桥设备上。 + +为了使多个服务驱动程序同时运行，需要有一个PCI Express端口总线驱动程序，它管 +理所有填充的PCI Express端口，并根据需要将所有提供的服务请求分配给相应的服务 +驱动程序。下面列出了使用PCI Express端口总线驱动程序的一些关键优势: + + - 允许在一个PCI-PCI桥接端口设备上同时运行多个服务驱动。 + + - 允许以独立的分阶段方式实施服务驱动程序。 + + - 允许一个服务驱动程序在多个PCI-PCI桥接端口设备上运行。 + + - 管理和分配PCI-PCI桥接端口设备的资源给要求的服务驱动程序。 + +配置PCI Express端口总线驱动程序与服务驱动程序 +============================================= + +将PCI Express端口总线驱动支持纳入内核 +------------------------------------- + +包括PCI Express端口总线驱动程序取决于内核配置中是否包含PCI Express支持。当内核 +中的PCI Express支持被启用时，内核将自动包含PCI Express端口总线驱动程序作为内核 +驱动程序。 + +启用服务驱动支持 +---------------- + +PCI设备驱动是基于Linux设备驱动模型实现的。所有的服务驱动都是PCI设备驱动。如上所述， +一旦内核加载了PCI Express端口总线驱动程序，就不可能再加载任何服务驱动程序。为了满 +足PCI Express端口总线驱动程序模型，需要对现有的服务驱动程序进行一些最小的改变，其 +对现有的服务驱动程序的功能没有影响。 + +服务驱动程序需要使用下面所示的两个API，将其服务注册到PCI Express端口总线驱动程 +序中（见第5.2.1和5.2.2节）。在调用这些API之前，服务驱动程序必须初始化头文件 +/include/linux/pcieport_if.h中的pcie_port_service_driver数据结构。如果不这 +样做，将导致身份不匹配，从而使PCI Express端口总线驱动程序无法加载服务驱动程序。 + +pcie_port_service_register +~~~~~~~~~~~~~~~~~~~~~~~~~~ +:: + + int pcie_port_service_register(struct pcie_port_service_driver *new) + +这个API取代了Linux驱动模型的 pci_register_driver API。一个服务驱动应该总是在模 +块启动时调用 pcie_port_service_register。请注意，在服务驱动被加载后，诸如 +pci_enable_device(dev) 和 pci_set_master(dev) 的调用不再需要，因为这些调用由 +PCI端口总线驱动执行。 + +pcie_port_service_unregister +~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +:: + + void pcie_port_service_unregister(struct pcie_port_service_driver *new) + +pcie_port_service_unregister取代了Linux驱动模型的pci_unregister_driver。当一 +个模块退出时，它总是被服务驱动调用。 + +示例代码 +~~~~~~~~ + +下面是服务驱动代码示例，用于初始化端口服务的驱动程序数据结构。 +:: + + static struct pcie_port_service_id service_id[] = { { + .vendor = PCI_ANY_ID, + .device = PCI_ANY_ID, + .port_type = PCIE_RC_PORT, + .service_type = PCIE_PORT_SERVICE_AER, + }, { /* end: all zeroes */ } + }; + + static struct pcie_port_service_driver root_aerdrv = { + .name = (char *)device_name, + .id_table = &service_id[0], + + .probe = aerdrv_load, + .remove = aerdrv_unload, + + .suspend = aerdrv_suspend, + .resume = aerdrv_resume, + }; + +下面是一个注册/取消注册服务驱动的示例代码。 +:: + + static int __init aerdrv_service_init(void) + { + int retval = 0; + + retval = pcie_port_service_register(&root_aerdrv); + if (!retval) { + /* + * FIX ME + */ + } + return retval; + } + + static void __exit aerdrv_service_exit(void) + { + pcie_port_service_unregister(&root_aerdrv); + } + + module_init(aerdrv_service_init); + module_exit(aerdrv_service_exit); + +可能的资源冲突 +============== + +由于PCI-PCI桥接端口设备的所有服务驱动被允许同时运行，下面列出了一些可能的资源冲突和 +建议的解决方案。 + +MSI 和 MSI-X 向量资源 +--------------------- + +一旦设备上的MSI或MSI-X中断被启用，它就会一直保持这种模式，直到它们再次被禁用。由于同 +一个PCI-PCI桥接端口的服务驱动程序共享同一个物理设备，如果一个单独的服务驱动程序启用或 +禁用MSI/MSI-X模式，可能会导致不可预知的行为。 + +为了避免这种情况，所有的服务驱动程序都不允许在其设备上切换中断模式。PCI Express端口 +总线驱动程序负责确定中断模式，这对服务驱动程序来说应该是透明的。服务驱动程序只需要知道 +分配给结构体pcie_device的字段irq的向量IRQ，当PCI Express端口总线驱动程序探测每 +个服务驱动程序时，它被传入。服务驱动应该使用（struct pcie_device*）dev->irq来调用 +request_irq/free_irq。此外，中断模式被存储在struct pcie_device的interrupt_mode +字段中。 + +PCI内存/IO映射的区域 +-------------------- + +PCI Express电源管理（PME）、高级错误报告（AER）、热插拔（HP）和虚拟通道（VC）的服务 +驱动程序访问PCI Express端口的PCI配置空间。在所有情况下，访问的寄存器是相互独立的。这 +个补丁假定所有的服务驱动程序都会表现良好，不会覆盖其他服务驱动程序的配置设置。 + +PCI配置寄存器 +------------- + +每个服务驱动都在自己的功能结构体上运行PCI配置操作，除了PCI Express功能结构体，其中根控制 +寄存器和设备控制寄存器是在PME和AER之间共享。这个补丁假定所有的服务驱动都会表现良好，不会 +覆盖其他服务驱动的配置设置。 diff --git a/Documentation/translations/zh_CN/PCI/sysfs-pci.rst b/Documentation/translations/zh_CN/PCI/sysfs-pci.rst new file mode 100644 index 000000000000..0d75c2e99d52 --- /dev/null +++ b/Documentation/translations/zh_CN/PCI/sysfs-pci.rst @@ -0,0 +1,126 @@ +.. SPDX-License-Identifier: GPL-2.0 +.. include:: ../disclaimer-zh_CN.rst + +:Original: Documentation/PCI/sysfs-pci.rst + +:翻译: + + 司延腾 Yanteng Si <siyanteng@loongson.cn> + +:校译: + + + +======================== +通过sysfs访问PCI设备资源 +======================== + +sysfs，通常挂载在/sys，在支持它的平台上提供对PCI资源的访问。例如，一个特定的总线可能看起 +来像这样:: + + /sys/devices/pci0000:17 + |-- 0000:17:00.0 + | |-- class + | |-- config + | |-- device + | |-- enable + | |-- irq + | |-- local_cpus + | |-- remove + | |-- resource + | |-- resource0 + | |-- resource1 + | |-- resource2 + | |-- revision + | |-- rom + | |-- subsystem_device + | |-- subsystem_vendor + | `-- vendor + `-- ... + +最上面的元素描述了PCI域和总线号码。在这种情况下，域号是0000，总线号是17（两个值都是十六进制）。 +这个总线在0号插槽中包含一个单一功能的设备。为了方便起见，我们复制了域和总线的编号。在设备目录 +下有几个文件，每个文件都有自己的功能。 + + =================== ===================================================== + 文件 功能 + =================== ===================================================== + class PCI级别 (ascii, ro) + config PCI配置空间 (binary, rw) + device PCI设备 (ascii, ro) + enable 设备是否被启用 (ascii, rw) + irq IRQ编号 (ascii, ro) + local_cpus 临近CPU掩码(cpumask, ro) + remove 从内核的列表中删除设备 (ascii, wo) + resource PCI资源主机地址 (ascii, ro) + resource0..N PCI资源N，如果存在的话 (binary, mmap, rw\ [1]_) + resource0_wc..N_wc PCI WC映射资源N，如果可预取的话 (binary, mmap) + revision PCI修订版 (ascii, ro) + rom PCI ROM资源，如果存在的话 (binary, ro) + subsystem_device PCI子系统设备 (ascii, ro) + subsystem_vendor PCI子系统供应商 (ascii, ro) + vendor PCI供应商 (ascii, ro) + =================== ===================================================== + +:: + + ro - 只读文件 + rw - 文件是可读和可写的 + wo - 只写文件 + mmap - 文件是可移动的 + ascii - 文件包含ascii文本 + binary - 文件包含二进制数据 + cpumask - 文件包含一个cpumask类型的 + +.. [1] rw 仅适用于 IORESOURCE_IO（I/O 端口）区域 + +只读文件是信息性的，对它们的写入将被忽略，但 "rom "文件除外。可写文件可以用来在设备上执 +行操作（例如，改变配置空间，分离设备）。 mmapable文件可以通过偏移量为0的文件的mmap获得， +可以用来从用户空间进行实际的设备编程。注意，有些平台不支持某些资源的mmapping，所以一定要 +检查任何尝试的mmap的返回值。其中最值得注意的是I/O端口资源，它也提供读/写访问。 + +enable "文件提供了一个计数器，表明设备已经被启用了多少次。如果'enable'文件目前返回'4'， +而一个'1'被呼入它，它将返回'5'。向它呼入一个'0'会减少计数。不过，即使它返回到0，一些初始 +化可能也不会被逆转。 + +rom "文件很特别，因为它提供了对设备ROM文件的只读访问，如果有的话。然而，它在默认情况下是 +禁用的，所以应用程序应该在尝试读取调用之前将字符串 "1 "写入该文件以启用它，并在访问之后将 +"0 "写入该文件以禁用它。请注意，设备必须被启用，才能成功返回数据。如果驱动没有被绑定到设备 +上，可以使用上面提到的 "enable "文件将其启用。 + +remove "文件是用来移除PCI设备的，通过向该文件写入一个非零的整数。这并不涉及任何形式的热插 +拔功能，例如关闭设备的电源。该设备被从内核的PCI设备列表中移除，它的sysfs目录被移除，并且该 +设备将被从任何连接到它的驱动程序中移除。移除PCI根总线是不允许的。 + +通过sysfs访问原有资源 +--------------------- + +如果底层平台支持的话，传统的I/O端口和ISA内存资源也会在sysfs中提供。它们位于PCI类的层次结构 +中，例如:: + + /sys/class/pci_bus/0000:17/ + |-- bridge -> ../../../devices/pci0000:17 + |-- cpuaffinity + |-- legacy_io + `-- legacy_mem + +legacy_io文件是一个读/写文件，可以被应用程序用来做传统的端口I/O。应用程序应该打开该文件，寻 +找所需的端口（例如0x3e8），并进行1、2或4字节的读或写。legacy_mem文件应该被mmapped，其偏移 +量与所需的内存偏移量相对应，例如0xa0000用于VGA帧缓冲器。然后，应用程序可以简单地解除引用返回 +的指针（当然是在检查了错误之后）来访问遗留内存空间。 + +支持新平台上的PCI访问 +--------------------- + +为了支持上述的PCI资源映射，Linux平台代码最好定义ARCH_GENERIC_PCI_MMAP_RESOURCE并使用该 +功能的通用实现。为了支持通过/proc/bus/pci中的文件实现mmap()的历史接口，平台也可以设置 +HAVE_PCI_MMAP。 + +另外，设置了 HAVE_PCI_MMAP 的平台可以提供他们自己的 pci_mmap_page_range() 实现，而不是定 +义 ARCH_GENERIC_PCI_MMAP_RESOURCE。 + +支持PCI资源的写组合映射的平台必须定义arch_can_pci_mmap_wc()，当写组合被允许时，在运行时应 +评估为非零。支持I/O资源映射的平台同样定义arch_can_pci_mmap_io()。 + +遗留资源由HAVE_PCI_LEGACY定义保护。希望支持遗留功能的平台应该定义它并提供 pci_legacy_read, +pci_legacy_write 和 pci_mmap_legacy_page_range 函数。 diff --git a/Documentation/translations/zh_CN/accounting/delay-accounting.rst b/Documentation/translations/zh_CN/accounting/delay-accounting.rst new file mode 100644 index 000000000000..67d5606e5401 --- /dev/null +++ b/Documentation/translations/zh_CN/accounting/delay-accounting.rst @@ -0,0 +1,111 @@ +.. include:: ../disclaimer-zh_CN.rst + +:Original: Documentation/accounting/delay-accounting.rst + +:Translator: Yang Yang <yang.yang29@zte.com.cn> + +======== +延时计数 +======== + +任务在等待某些内核资源可用时，会造成延时。例如一个可运行的任务可能会等待 +一个空闲CPU来运行。 + +基于每任务的延时计数功能度量由以下情况造成的任务延时： + +a) 等待一个CPU（任务为可运行） +b) 完成由该任务发起的块I/O同步请求 +c) 页面交换 +d) 内存回收 + +并将这些统计信息通过taskstats接口提供给用户空间。 + +这些延时信息为适当的调整任务CPU优先级、io优先级、rss限制提供反馈。重要任务 +长期延时，表示可能需要提高其相关优先级。 + +通过使用taskstats接口，本功能还可提供一个线程组（对应传统Unix进程）所有任务 +（或线程）的总延时统计信息。此类汇总往往是需要的，由内核来完成更加高效。 + +用户空间的实体，特别是资源管理程序，可将延时统计信息汇总到任意组中。为实现 +这一点，任务的延时统计信息在其生命周期内和退出时皆可获取，从而确保可进行 +连续、完整的监控。 + +接口 +---- + +延时计数使用taskstats接口，该接口由本目录另一个单独的文档详细描述。Taskstats +向用户态返回一个通用数据结构，对应每pid或每tgid的统计信息。延时计数功能填写 +该数据结构的特定字段。见 + + include/linux/taskstats.h + +其描述了延时计数相关字段。系统通常以计数器形式返回 CPU、同步块 I/O、交换、内存 +回收等的累积延时。 + +取任务某计数器两个连续读数的差值，将得到任务在该时间间隔内等待对应资源的总延时。 + +当任务退出时，内核会将包含每任务的统计信息发送给用户空间，而无需额外的命令。 +若其为线程组最后一个退出的任务，内核还会发送每tgid的统计信息。更多详细信息见 +taskstats接口的描述。 + +tools/accounting目录中的用户空间程序getdelays.c提供了一些简单的命令，用以显示 +延时统计信息。其也是使用taskstats接口的示例。 + +用法 +---- + +使用以下配置编译内核:: + + CONFIG_TASK_DELAY_ACCT=y + CONFIG_TASKSTATS=y + +延时计数在启动时默认关闭。 +若需开启，在启动参数中增加:: + + delayacct + +本文后续的说明基于延时计数已开启。也可在系统运行时，使用sysctl的 +kernel.task_delayacct进行开关。注意，只有在启用延时计数后启动的 +任务才会有相关信息。 + +系统启动后，使用类似getdelays.c的工具获取任务或线程组（tgid）的延时信息。 + +getdelays命令的一般格式:: + + getdelays [-t tgid] [-p pid] [-c cmd...] + +获取pid为10的任务从系统启动后的延时信息:: + + # ./getdelays -p 10 + （输出信息和下例相似） + +获取所有tgid为5的任务从系统启动后的总延时信息:: + + # ./getdelays -t 5 + + + CPU count real total virtual total delay total + 7876 92005750 100000000 24001500 + IO count delay total + 0 0 + SWAP count delay total + 0 0 + RECLAIM count delay total + 0 0 + +获取指定简单命令运行时的延时信息:: + + # ./getdelays -c ls / + + bin data1 data3 data5 dev home media opt root srv sys usr + boot data2 data4 data6 etc lib mnt proc sbin subdomain tmp var + + + CPU count real total virtual total delay total + 6 4000250 4000000 0 + IO count delay total + 0 0 + SWAP count delay total + 0 0 + RECLAIM count delay total + 0 0 diff --git a/Documentation/translations/zh_CN/accounting/index.rst b/Documentation/translations/zh_CN/accounting/index.rst index 362e907b41f9..a34952e12a27 100644 --- a/Documentation/translations/zh_CN/accounting/index.rst +++ b/Documentation/translations/zh_CN/accounting/index.rst @@ -15,11 +15,11 @@ .. toctree:: :maxdepth: 1 + delay-accounting psi + taskstats Todolist: cgroupstats - delay-accounting - taskstats taskstats-struct diff --git a/Documentation/translations/zh_CN/accounting/taskstats.rst b/Documentation/translations/zh_CN/accounting/taskstats.rst new file mode 100644 index 000000000000..307ac5ce0e4b --- /dev/null +++ b/Documentation/translations/zh_CN/accounting/taskstats.rst @@ -0,0 +1,145 @@ +.. include:: ../disclaimer-zh_CN.rst + +:Original: Documentation/accounting/taskstats.rst + +:Translator: Yang Yang <yang.yang29@zte.com.cn> + +================ +每任务的统计接口 +================ + +Taskstats是一个基于netlink的接口，用于从内核向用户空间发送每任务及每进程的 +统计信息。 + +Taskstats设计目的： + +- 在任务生命周期内和退出时高效的提供统计信息 +- 统一不同计数子系统的接口 +- 支持未来计数系统的扩展 + +术语 +---- + +“pid”、“tid”、“任务”互换使用，用于描述由struct task_struct定义的标准 +Linux任务。“每pid的统计数据”等价于“每任务的统计数据”。 + +“tgid”、“进程”、“线程组”互换使用，用于描述共享mm_struct的任务集， +也就是传统的Unix进程。尽管使用了tgid这个词，即使一个任务是线程组组长， +对它的处理也没有什么不同。只要一个进程还有任何归属它的任务，它就被认为 +活着。 + +用法 +---- + +为了在任务生命周期内获得统计信息，用户空间需打开一个单播的netlink套接字 +（NETLINK_GENERIC族）然后发送指定pid或tgid的命令。响应消息中包含单个 +任务的统计信息（若指定了pid）或进程所有任务汇总的统计信息（若指定了tgid）。 + +为了在任务退出时获取统计信息，用户空间的监听者发送一个指定cpu掩码的注册命令。 +cpu掩码内的cpu上有任务退出时，每pid的统计信息将发送给注册成功的监听者。使用 +cpu掩码可以限制一个监听者收到的数据，并有助于对netlink接口进行流量控制，后文 +将进行更详细的解释。 + +如果正在退出的任务是线程组中最后一个退出的线程，额外一条包含每tgid统计信息的 +记录也将发送给用户空间。后者包含线程组中所有线程（包括过去和现在）的每pid统计 +信息总和。 + +getdelays.c是一个简单的示例，用以演示如何使用taskstats接口获取延迟统计信息。 +用户可注册cpu掩码、发送命令和处理响应、监听每tid/tgid退出数据、将收到的数据 +写入文件、通过增大接收缓冲区进行基本的流量控制。 + +接口 +---- + +内核用户接口封装在include/linux/taskstats.h。 + +为避免本文档随着接口的演进而过期，本文仅给出当前版本的概要。当本文与taskstats.h +不一致时，以taskstats.h为准。 + +struct taskstats是每pid和每tgid数据共用的计数结构体。它是版本化的，可在内核新增 +计数子系统时进行扩展。taskstats.h中定义了各字段及语义。 + +用户、内核空间的数据交换是属于NETLINK_GENERIC族的netlink消息，使用netlink属性 +接口。消息格式如下:: + + +----------+- - -+-------------+-------------------+ + | nlmsghdr | Pad | genlmsghdr | taskstats payload | + +----------+- - -+-------------+-------------------+ + +Taskstats载荷有三种类型： + +1. 命令：由用户发送给内核。获取指定pid/tgid数据的命令包含一个类型为 +TASKSTATS_CMD_ATTR_PID/TGID的属性，该属性包含u32的pid或tgid载荷。 +pid/tgid指示用户空间要统计的任务/进程。 + +注册/注销获取指定cpu集上退出数据的命令包含一个类型为 +TASKSTATS_CMD_ATTR_REGISTER/DEREGISTER_CPUMASK的属性，该属性包含cpu掩码载荷。 +cpu掩码是以ascii码表示，用逗号分隔的cpu范围。例如若需监听1,2,3,5,7,8号cpu的 +退出数据，cpu掩码表示为"1-3,5,7-8"。若用户空间在关闭监听套接字前忘了注销监听 +的cpu集，随着时间的推移，内核会清理此监听集。但是，出于提效的目的，建议明确 +执行注销。 + +2. 命令的应答：内核发出应答用户空间的命令。载荷有三类属性： + +a) TASKSTATS_TYPE_AGGR_PID/TGID： 本属性不包含载荷，用以指示其后为被统计对象 +的pig/tgid。 + +b) TASKSTATS_TYPE_PID/TGID：本属性的载荷为pig/tgid，其统计信息将被返回。 + +c) TASKSTATS_TYPE_STATS：本属性的载荷为一个struct taskstats实例。每pid和 +每tgid统计信息共用该结构体。 + +3. 内核会在任务退出时发送新消息。其载荷包含一系列以下类型的属性： + +a) TASKSTATS_TYPE_AGGR_PID：指示其后两个属性为pid+stats。 +b) TASKSTATS_TYPE_PID：包含退出任务的pid。 +c) TASKSTATS_TYPE_STATS：包含退出任务的每pid统计信息 +d) TASKSTATS_TYPE_AGGR_TGID：指示其后两个属性为tgid+stats。 +e) TASKSTATS_TYPE_TGID：包含任务所属进程的tgid +f) TASKSTATS_TYPE_STATS：包含退出任务所属进程的每tgid统计信息 + +每tgid的统计 +------------ + +除了每任务的统计信息，taskstats还提供每进程的统计信息，因为资源管理通常以进程 +粒度完成，并且仅在用户空间聚合任务统计信息效率低下且可能不准确（缺乏原子性）。 + +然而，除了每任务统计信息，在内核中维护每进程统计信息存在额外的时间和空间开销。 +为解决此问题，taskstats代码将退出任务的统计信息累积到进程范围的数据结构中。 +当进程最后一个任务退出时，累积的进程级数据也会发送到用户空间（与每任务数据一起）。 + +当用户查询每tgid数据时，内核将指定线程组中所有活动线程的统计信息相加，并添加到 +该线程组的累积总数（含之前退出的线程）。 + +扩展taskstats +------------- + +有两种方法可在未来修改内核扩展taskstats接口，以导出更多的每任务/进程统计信息： + +1. 在现有struct taskstats末尾增加字段。该结构体中的版本号确保了向后兼容性。 +用户空间将仅使用与其版本对应的结构体字段。 + +2. 定义单独的统计结构体并使用netlink属性接口返回对应的数据。由于用户空间独立 +处理每个netlink属性，所以总是可以忽略其不理解类型的属性（因为使用了旧版本接口）。 + +在1.和2.之间进行选择，属于权衡灵活性和开销的问题。若仅需增加少数字段，那么1.是 +首选方法，因为内核和用户空间无需承担处理新netlink属性的开销。但若新字段过多的 +扩展现有结构体，导致不同的用户空间计数程序不必要的接收大型结构体，而对结构体 +字段并不感兴趣，那么2.是值得的。 + +Taskstats的流量控制 +------------------- + +当退出任务数速率变大，监听者可能跟不上内核发送每tid/tgid退出数据的速率，而导致 +数据丢失。taskstats结构体变大、cpu数量上升，都会导致这种可能性增加。 + +为避免统计信息丢失，用户空间应执行以下操作中至少一项： + +- 增大监听者用于接收退出数据的netlink套接字接收缓存区。 + +- 创建更多的监听者，减少每个监听者监听的cpu数量。极端情况下可为每个cpu创建 + 一个监听者。用户还可考虑将监听者的cpu亲和性设置为监听cpu的子集，特别是当他们 + 仅监听一个cpu。 + +尽管采取了这些措施，若用户空间仍收到指示接收缓存区溢出的ENOBUFS错误消息， +则应采取其他措施处理数据丢失。 diff --git a/Documentation/translations/zh_CN/admin-guide/README.rst b/Documentation/translations/zh_CN/admin-guide/README.rst index 980eb20521cf..d20949e8bf6f 100644 --- a/Documentation/translations/zh_CN/admin-guide/README.rst +++ b/Documentation/translations/zh_CN/admin-guide/README.rst @@ -133,7 +133,7 @@ Linux内核5.x版本 <http://kernel.org/> 即使只升级一个小版本，也不要跳过此步骤。每个版本中都会添加新的配置选项， 如果配置文件没有按预定设置，就会出现奇怪的问题。如果您想以最少的工作量 - 将现有配置升级到新版本，请使用 ``makeoldconfig`` ，它只会询问您新配置 + 将现有配置升级到新版本，请使用 ``make oldconfig`` ，它只会询问您新配置 选项的答案。 - 其他配置命令包括:: @@ -161,7 +161,7 @@ Linux内核5.x版本 <http://kernel.org/> "make ${PLATFORM}_defconfig" 使用arch/$arch/configs/${PLATFORM}_defconfig中 的默认选项值创建一个./.config文件。 - 用“makehelp”来获取您体系架构中所有可用平台的列表。 + 用“make help”来获取您体系架构中所有可用平台的列表。 "make allyesconfig" 通过尽可能将选项值设置为“y”，创建一个 @@ -197,9 +197,10 @@ Linux内核5.x版本 <http://kernel.org/> "make localyesconfig" 与localmodconfig类似，只是它会将所有模块选项转换 为内置（=y）。你可以同时通过LMC_KEEP保留模块。 - "make kvmconfig" 为kvm客体内核支持启用其他选项。 + "make kvm_guest.config" + 为kvm客户机内核支持启用其他选项。 - "make xenconfig" 为xen dom0客体内核支持启用其他选项。 + "make xen.config" 为xen dom0客户机内核支持启用其他选项。 "make tinyconfig" 配置尽可能小的内核。 @@ -229,7 +230,7 @@ Linux内核5.x版本 <http://kernel.org/> 请注意，您仍然可以使用此内核运行a.out用户程序。 - 执行 ``make`` 来创建压缩内核映像。如果您安装了lilo以适配内核makefile， - 那么也可以进行 ``makeinstall`` ，但是您可能需要先检查特定的lilo设置。 + 那么也可以进行 ``make install`` ，但是您可能需要先检查特定的lilo设置。 实际安装必须以root身份执行，但任何正常构建都不需要。 无须徒然使用root身份。 diff --git a/Documentation/translations/zh_CN/admin-guide/cputopology.rst b/Documentation/translations/zh_CN/admin-guide/cputopology.rst new file mode 100644 index 000000000000..544d42f8f3fa --- /dev/null +++ b/Documentation/translations/zh_CN/admin-guide/cputopology.rst @@ -0,0 +1,96 @@ +.. SPDX-License-Identifier: GPL-2.0 +.. include:: ../disclaimer-zh_CN.rst + +:Original: Documentation/admin-guide/cputopology.rst + +:翻译: + + 唐艺舟 Tang Yizhou <tangyeechou@gmail.com> + +========================== +如何通过sysfs将CPU拓扑导出 +========================== + +CPU拓扑信息通过sysfs导出。显示的项（属性）和某些架构的/proc/cpuinfo输出相似。它们位于 +/sys/devices/system/cpu/cpuX/topology/。请阅读ABI文件： +Documentation/ABI/stable/sysfs-devices-system-cpu。 + +drivers/base/topology.c是体系结构中性的，它导出了这些属性。然而，die、cluster、book、 +draw这些层次结构相关的文件仅在体系结构提供了下文描述的宏的条件下被创建。 + +对于支持这个特性的体系结构，它必须在include/asm-XXX/topology.h中定义这些宏中的一部分:: + + #define topology_physical_package_id(cpu) + #define topology_die_id(cpu) + #define topology_cluster_id(cpu) + #define topology_core_id(cpu) + #define topology_book_id(cpu) + #define topology_drawer_id(cpu) + #define topology_sibling_cpumask(cpu) + #define topology_core_cpumask(cpu) + #define topology_cluster_cpumask(cpu) + #define topology_die_cpumask(cpu) + #define topology_book_cpumask(cpu) + #define topology_drawer_cpumask(cpu) + +``**_id macros`` 的类型是int。 +``**_cpumask macros`` 的类型是 ``(const) struct cpumask *`` 。后者和恰当的 +``**_siblings`` sysfs属性对应（除了topology_sibling_cpumask()，它和thread_siblings +对应）。 + +为了在所有体系结构上保持一致，include/linux/topology.h提供了上述所有宏的默认定义，以防 +它们未在include/asm-XXX/topology.h中定义: + +1) topology_physical_package_id: -1 +2) topology_die_id: -1 +3) topology_cluster_id: -1 +4) topology_core_id: 0 +5) topology_book_id: -1 +6) topology_drawer_id: -1 +7) topology_sibling_cpumask: 仅入参CPU +8) topology_core_cpumask: 仅入参CPU +9) topology_cluster_cpumask: 仅入参CPU +10) topology_die_cpumask: 仅入参CPU +11) topology_book_cpumask: 仅入参CPU +12) topology_drawer_cpumask: 仅入参CPU + +此外，CPU拓扑信息由/sys/devices/system/cpu提供，包含下述文件。输出对应的内部数据源放在 +方括号（"[]"）中。 + + =========== ================================================================== + kernel_max: 内核配置允许的最大CPU下标值。[NR_CPUS-1] + + offline: 由于热插拔移除或者超过内核允许的CPU上限（上文描述的kernel_max） + 导致未上线的CPU。[~cpu_online_mask + cpus >= NR_CPUS] + + online: 在线的CPU，可供调度使用。[cpu_online_mask] + + possible: 已被分配资源的CPU，如果它们CPU实际存在，可以上线。 + [cpu_possible_mask] + + present: 被系统识别实际存在的CPU。[cpu_present_mask] + =========== ================================================================== + +上述输出的格式和cpulist_parse()兼容[参见 <linux/cpumask.h>]。下面给些例子。 + +在本例中，系统中有64个CPU，但是CPU 32-63超过了kernel_max值，因为NR_CPUS配置项是32， +取值范围被限制为0..31。此外注意CPU2和4-31未上线，但是可以上线，因为它们同时存在于 +present和possible:: + + kernel_max: 31 + offline: 2,4-31,32-63 + online: 0-1,3 + possible: 0-31 + present: 0-31 + +在本例中，NR_CPUS配置项是128，但内核启动时设置possible_cpus=144。系统中有4个CPU， +CPU2被手动设置下线（也是唯一一个可以上线的CPU）:: + + kernel_max: 127 + offline: 2,4-127,128-143 + online: 0-1,3 + possible: 0-127 + present: 0-3 + +阅读Documentation/core-api/cpu_hotplug.rst可了解开机参数possible_cpus=NUM，同时还 +可以了解各种cpumask的信息。 diff --git a/Documentation/translations/zh_CN/admin-guide/index.rst b/Documentation/translations/zh_CN/admin-guide/index.rst index 83db84282562..548e57f4b3f1 100644 --- a/Documentation/translations/zh_CN/admin-guide/index.rst +++ b/Documentation/translations/zh_CN/admin-guide/index.rst @@ -65,6 +65,7 @@ Todolist: clearing-warn-once cpu-load + cputopology lockup-watchdogs unicode sysrq @@ -84,7 +85,6 @@ Todolist: cgroup-v1/index cgroup-v2 cifs/index - cputopology dell_rbu device-mapper/index edid diff --git a/Documentation/translations/zh_CN/cpu-freq/core.rst b/Documentation/translations/zh_CN/cpu-freq/core.rst index 0c6fd447ced6..b3c095306ffe 100644 --- a/Documentation/translations/zh_CN/cpu-freq/core.rst +++ b/Documentation/translations/zh_CN/cpu-freq/core.rst @@ -7,7 +7,9 @@ 司延腾 Yanteng Si <siyanteng@loongson.cn> -.. _cn_core.rst: +:校译: + + 唐艺舟 Tang Yizhou <tangyeechou@gmail.com> ==================================== CPUFreq核心和CPUFreq通知器的通用说明 @@ -29,10 +31,10 @@ CPUFreq核心和CPUFreq通知器的通用说明 ====================== cpufreq核心代码位于drivers/cpufreq/cpufreq.c中。这些cpufreq代码为CPUFreq架构的驱 -动程序（那些操作硬件切换频率的代码）以及 "通知器 "提供了一个标准化的接口。 -这些是设备驱动程序或需要了解策略变化的其它内核部分（如 ACPI 热量管理）或所有频率更改（除 -计时代码外），甚至需要强制确定速度限制的通知器（如 ARM 架构上的 LCD 驱动程序）。 -此外， 内核 "常数" loops_per_jiffy会根据频率变化而更新。 +动程序（那些执行硬件频率切换的代码）以及 "通知器" 提供了一个标准化的接口。 +包括设备驱动程序；需要了解策略变化（如 ACPI 热量管理），或所有频率变化（如计时代码）， +甚至需要强制限制为指定频率（如 ARM 架构上的 LCD 驱动程序）的其它内核组件。 +此外，内核 "常数" loops_per_jiffy 会根据频率变化而更新。 cpufreq策略的引用计数由 cpufreq_cpu_get 和 cpufreq_cpu_put 来完成，以确保 cpufreq 驱 动程序被正确地注册到核心中，并且驱动程序在 cpufreq_put_cpu 被调用之前不会被卸载。这也保证 @@ -41,7 +43,7 @@ cpufreq策略的引用计数由 cpufreq_cpu_get 和 cpufreq_cpu_put 来完成， 2. CPUFreq 通知器 ==================== -CPUFreq通知器符合标准的内核通知器接口。 +CPUFreq通知器遵循标准的内核通知器接口。 关于通知器的细节请参阅 linux/include/linux/notifier.h。 这里有两个不同的CPUfreq通知器 - 策略通知器和转换通知器。 @@ -69,20 +71,20 @@ CPUFreq通知器符合标准的内核通知器接口。 第三个参数是一个包含如下值的结构体cpufreq_freqs： -===== ==================== -cpu 受影响cpu的编号 +====== =============================== +policy 指向struct cpufreq_policy的指针 old 旧频率 new 新频率 flags cpufreq驱动的标志 -===== ==================== +====== =============================== 3. 含有Operating Performance Point (OPP)的CPUFreq表的生成 ================================================================== 关于OPP的细节请参阅 Documentation/power/opp.rst dev_pm_opp_init_cpufreq_table - - 这个功能提供了一个随时可用的转换程序，用来将OPP层关于可用频率的内部信息翻译成一种容易提供给 - cpufreq的格式。 + 这个函数提供了一个随时可用的转换例程，用来将OPP层关于可用频率的内部信息翻译成一种 + cpufreq易于处理的格式。 .. Warning:: diff --git a/Documentation/translations/zh_CN/cpu-freq/cpu-drivers.rst b/Documentation/translations/zh_CN/cpu-freq/cpu-drivers.rst index 0fc5d1495789..87a36044f828 100644 --- a/Documentation/translations/zh_CN/cpu-freq/cpu-drivers.rst +++ b/Documentation/translations/zh_CN/cpu-freq/cpu-drivers.rst @@ -8,7 +8,9 @@ 司延腾 Yanteng Si <siyanteng@loongson.cn> -.. _cn_cpu-drivers.rst: +:校译: + + 唐艺舟 Tang Yizhou <tangyeechou@gmail.com> ======================================= 如何实现一个新的CPUFreq处理器驱动程序？ @@ -38,14 +40,14 @@ 1. 怎么做？ =========== -如此，你刚刚得到了一个全新的CPU/芯片组及其数据手册，并希望为这个CPU/芯片组添加cpufreq +如果，你刚刚得到了一个全新的CPU/芯片组及其数据手册，并希望为这个CPU/芯片组添加cpufreq 支持？很好，这里有一些至关重要的提示： 1.1 初始化 ---------- -首先，在__initcall_level_7 (module_init())或更靠后的函数中检查这个内核是否 +首先，在 __initcall level 7 (module_init())或更靠后的函数中检查这个内核是否 运行在正确的CPU和正确的芯片组上。如果是，则使用cpufreq_register_driver()向 CPUfreq核心层注册一个cpufreq_driver结构体。 @@ -60,11 +62,11 @@ CPUfreq核心层注册一个cpufreq_driver结构体。 .setpolicy 或 .fast_switch 或 .target 或 .target_index - 差异见 下文。 -并且可选择 +其它可选成员 - .flags - cpufreq核的提示。 + .flags - 给cpufreq核心的提示。 - .driver_data - cpufreq驱动程序的特定数据。 + .driver_data - cpufreq驱动程序的特有数据。 .get_intermediate 和 target_intermediate - 用于在改变CPU频率时切换到稳定 的频率。 @@ -73,16 +75,16 @@ CPUfreq核心层注册一个cpufreq_driver结构体。 .bios_limit - 返回HW/BIOS对CPU的最大频率限制值。 - .exit - 一个指向per-policy清理函数的指针，该函数在cpu热插拔过程的CPU_POST_DEAD + .exit - 一个指向per-policy清理函数的指针，该函数在CPU热插拔过程的CPU_POST_DEAD 阶段被调用。 .suspend - 一个指向per-policy暂停函数的指针，该函数在关中断且在该策略的调节器停止 后被调用。 - .resume - 一个指向per-policy恢复函数的指针，该函数在关中断且在调节器再一次开始前被 + .resume - 一个指向per-policy恢复函数的指针，该函数在关中断且在调节器再一次启动前被 调用。 - .attr - 一个指向NULL结尾的"struct freq_attr"列表的指针，该函数允许导出值到 + .attr - 一个指向NULL结尾的"struct freq_attr"列表的指针，该列表允许导出值到 sysfs。 .boost_enabled - 如果设置，则启用提升(boost)频率。 @@ -93,95 +95,93 @@ CPUfreq核心层注册一个cpufreq_driver结构体。 1.2 Per-CPU 初始化 ------------------ -每当一个新的CPU被注册到设备模型中，或者在cpufreq驱动注册自己之后，如果此CPU的cpufreq策 -略不存在，则会调用per-policy的初始化函数cpufreq_driver.init。请注意，.init()和.exit()程序 -只对策略调用一次，而不是对策略管理的每个CPU调用一次。它需要一个 ``struct cpufreq_policy +每当一个新的CPU被注册到设备模型中，或者当cpufreq驱动注册自身之后，如果此CPU的cpufreq策 +略不存在，则会调用per-policy的初始化函数cpufreq_driver.init。请注意，.init()和.exit()例程 +只为某个策略调用一次，而不是对该策略管理的每个CPU调用一次。它需要一个 ``struct cpufreq_policy *policy`` 作为参数。现在该怎么做呢？ 如果有必要，请在你的CPU上激活CPUfreq功能支持。 -然后，驱动程序必须填写以下数值: +然后，驱动程序必须填写以下值: +-----------------------------------+--------------------------------------+ -|policy->cpuinfo.min_freq 和 | | -|policy->cpuinfo.max_freq | 该CPU支持的最低和最高频率（kHz） | -| | | -| | | +|policy->cpuinfo.min_freq和 | 该CPU支持的最低和最高频率（kHz） | +|policy->cpuinfo.max_freq | | +| | | +-----------------------------------+--------------------------------------+ -|policy->cpuinfo.transition_latency | | -| | CPU在两个频率之间切换所需的时间，以 | -| | 纳秒为单位（如适用，否则指定 | -| | CPUFREQ_ETERNAL） | +|policy->cpuinfo.transition_latency | CPU在两个频率之间切换所需的时间，以 | +| | 纳秒为单位（如不适用，设定为 | +| | CPUFREQ_ETERNAL） | +| | | +-----------------------------------+--------------------------------------+ -|policy->cur | 该CPU当前的工作频率(如适用) | -| | | +|policy->cur | 该CPU当前的工作频率(如适用) | +| | | +-----------------------------------+--------------------------------------+ -|policy->min, | | -|policy->max, | | -|policy->policy and, if necessary, | | -|policy->governor | 必须包含该cpu的 “默认策略”。稍后 | -| | 会用这些值调用 | -| | cpufreq_driver.verify and either | -| | cpufreq_driver.setpolicy or | -| | cpufreq_driver.target/target_index | -| | | +|policy->min, | 必须包含该CPU的"默认策略"。稍后 | +|policy->max, | 会用这些值调用 | +|policy->policy and, if necessary, | cpufreq_driver.verify和下面函数 | +|policy->governor | 之一：cpufreq_driver.setpolicy或 | +| | cpufreq_driver.target/target_index | +| | | +-----------------------------------+--------------------------------------+ -|policy->cpus | 用与这个CPU一起做DVFS的(在线+离线) | -| | CPU(即与它共享时钟/电压轨)的掩码更新 | -| | 这个 | -| | | +|policy->cpus | 该policy通过DVFS框架影响的全部CPU | +| | (即与本CPU共享"时钟/电压"对)构成 | +| | 掩码(同时包含在线和离线CPU)，用掩码 | +| | 更新本字段 | +| | | +-----------------------------------+--------------------------------------+ -对于设置其中的一些值(cpuinfo.min[max]_freq, policy->min[max])，频率表助手可能会有帮 +对于设置其中的一些值(cpuinfo.min[max]_freq, policy->min[max])，频率表辅助函数可能会有帮 助。关于它们的更多信息，请参见第2节。 1.3 验证 -------- -当用户决定设置一个新的策略(由 “policy,governor,min,max组成”)时，必须对这个策略进行验证， +当用户决定设置一个新的策略(由"policy,governor,min,max组成")时，必须对这个策略进行验证， 以便纠正不兼容的值。为了验证这些值，cpufreq_verify_within_limits(``struct cpufreq_policy *policy``, ``unsigned int min_freq``, ``unsigned int max_freq``)函数可能会有帮助。 -关于频率表助手的详细内容请参见第2节。 +关于频率表辅助函数的详细内容请参见第2节。 您需要确保至少有一个有效频率（或工作范围）在 policy->min 和 policy->max 范围内。如果有必 -要，先增加policy->max，只有在没有办法的情况下，才减少policy->min。 +要，先增大policy->max，只有在没有解决方案的情况下，才减小policy->min。 1.4 target 或 target_index 或 setpolicy 或 fast_switch? ------------------------------------------------------- -大多数cpufreq驱动甚至大多数cpu频率升降算法只允许将CPU频率设置为预定义的固定值。对于这些，你 +大多数cpufreq驱动甚至大多数CPU频率升降算法只允许将CPU频率设置为预定义的固定值。对于这些，你 可以使用->target()，->target_index()或->fast_switch()回调。 -有些cpufreq功能的处理器可以自己在某些限制之间切换频率。这些应使用->setpolicy()回调。 +有些具有硬件调频能力的处理器可以自行依据某些限制来切换CPU频率。它们应使用->setpolicy()回调。 1.5. target/target_index ------------------------ -target_index调用有两个参数：``struct cpufreq_policy * policy``和``unsigned int`` -索引(于列出的频率表)。 +target_index调用有两个参数： ``struct cpufreq_policy * policy`` 和 ``unsigned int`` +索引(用于索引频率表项)。 当调用这里时，CPUfreq驱动必须设置新的频率。实际频率必须由freq_table[index].frequency决定。 -它应该总是在错误的情况下恢复到之前的频率(即policy->restore_freq)，即使我们之前切换到中间频率。 +在发生错误的情况下总是应该恢复到之前的频率(即policy->restore_freq)，即使我们已经切换到了 +中间频率。 已弃用 ---------- -目标调用有三个参数。``struct cpufreq_policy * policy``, unsigned int target_frequency, +target调用有三个参数。``struct cpufreq_policy * policy``, unsigned int target_frequency, unsigned int relation. CPUfreq驱动在调用这里时必须设置新的频率。实际的频率必须使用以下规则来确定。 -- 紧跟 "目标频率"。 +- 尽量贴近"目标频率"。 - policy->min <= new_freq <= policy->max (这必须是有效的!!!) - 如果 relation==CPUFREQ_REL_L，尝试选择一个高于或等于 target_freq 的 new_freq。("L代表 最低，但不能低于") - 如果 relation==CPUFREQ_REL_H，尝试选择一个低于或等于 target_freq 的 new_freq。("H代表 最高，但不能高于") -这里，频率表助手可能会帮助你--详见第2节。 +这里，频率表辅助函数可能会帮助你 -- 详见第2节。 1.6. fast_switch ---------------- @@ -195,42 +195,43 @@ CPUfreq驱动在调用这里时必须设置新的频率。实际的频率必须 1.7 setpolicy ------------- -setpolicy调用只需要一个``struct cpufreq_policy * policy``作为参数。需要将处理器内或芯片组内动态频 +setpolicy调用只需要一个 ``struct cpufreq_policy * policy`` 作为参数。需要将处理器内或芯片组内动态频 率切换的下限设置为policy->min，上限设置为policy->max，如果支持的话，当policy->policy为 -CPUFREQ_POLICY_PERFORMANCE时选择面向性能的设置，当CPUFREQ_POLICY_POWERSAVE时选择面向省电的设置。 +CPUFREQ_POLICY_PERFORMANCE时选择面向性能的设置，为CPUFREQ_POLICY_POWERSAVE时选择面向省电的设置。 也可以查看drivers/cpufreq/longrun.c中的参考实现。 1.8 get_intermediate 和 target_intermediate -------------------------------------------- -仅适用于 target_index() 和 CPUFREQ_ASYNC_NOTIFICATION 未设置的驱动。 +仅适用于未设置 target_index() 和 CPUFREQ_ASYNC_NOTIFICATION 的驱动。 get_intermediate应该返回一个平台想要切换到的稳定的中间频率，target_intermediate()应该将CPU设置为 -该频率，然后再跳转到'index'对应的频率。核心会负责发送通知，驱动不必在target_intermediate()或 -target_index()中处理。 +该频率，然后再跳转到'index'对应的频率。cpufreq核心会负责发送通知，驱动不必在 +target_intermediate()或target_index()中处理它们。 -在驱动程序不想因为某个目标频率切换到中间频率的情况下，它们可以从get_intermediate()中返回'0'。在这种情况 -下，核心将直接调用->target_index()。 +在驱动程序不想为某个目标频率切换到中间频率的情况下，它们可以让get_intermediate()返回'0'。 +在这种情况下，cpufreq核心将直接调用->target_index()。 -注意：->target_index()应该在失败的情况下恢复到policy->restore_freq，因为core会为此发送通知。 +注意：->target_index()应该在发生失败的情况下将频率恢复到policy->restore_freq， +因为cpufreq核心会为此发送通知。 -2. 频率表助手 -============= +2. 频率表辅助函数 +================= -由于大多数cpufreq处理器只允许被设置为几个特定的频率，因此，一个带有一些函数的 “频率表”可能会辅助处理器驱动 -程序的一些工作。这样的 "频率表" 由一个cpufreq_frequency_table条目构成的数组组成，"driver_data" 中包 -含了驱动程序的具体数值，"frequency" 中包含了相应的频率，并设置了标志。在表的最后，需要添加一个 -cpufreq_frequency_table条目，频率设置为CPUFREQ_TABLE_END。而如果想跳过表中的一个条目，则将频率设置为 -CPUFREQ_ENTRY_INVALID。这些条目不需要按照任何特定的顺序排序，但如果它们是cpufreq 核心会对它们进行快速的DVFS， +由于大多数支持cpufreq的处理器只允许被设置为几个特定的频率，因此，"频率表"和一些相关函数可能会辅助处理器驱动 +程序的一些工作。这样的"频率表"是一个由struct cpufreq_frequency_table的条目构成的数组，"driver_data"成员包 +含驱动程序的专用值，"frequency"成员包含了相应的频率，此外还有标志成员。在表的最后，需要添加一个 +cpufreq_frequency_table条目，频率设置为CPUFREQ_TABLE_END。如果想跳过表中的一个条目，则将频率设置为 +CPUFREQ_ENTRY_INVALID。这些条目不需要按照任何特定的顺序排序，如果排序了，cpufreq核心执行DVFS会更快一点， 因为搜索最佳匹配会更快。 -如果策略在其policy->freq_table字段中包含一个有效的指针，cpufreq表就会被核心自动验证。 +如果在policy->freq_table字段中包含一个有效的频率表指针，频率表就会被cpufreq核心自动验证。 cpufreq_frequency_table_verify()保证至少有一个有效的频率在policy->min和policy->max范围内，并且所有其他 -标准都被满足。这对->verify调用很有帮助。 +准则都被满足。这对->verify调用很有帮助。 -cpufreq_frequency_table_target()是对应于->target阶段的频率表助手。只要把数值传递给这个函数，这个函数就会返 +cpufreq_frequency_table_target()是对应于->target阶段的频率表辅助函数。只要把值传递给这个函数，这个函数就会返 回包含CPU要设置的频率的频率表条目。 以下宏可以作为cpufreq_frequency_table的迭代器。 @@ -238,8 +239,8 @@ cpufreq_frequency_table_target()是对应于->target阶段的频率表助手。 cpufreq_for_each_entry(pos, table) - 遍历频率表的所有条目。 cpufreq_for_each_valid_entry(pos, table) - 该函数遍历所有条目，不包括CPUFREQ_ENTRY_INVALID频率。 -使用参数 "pos"-一个``cpufreq_frequency_table * `` 作为循环变量，使用参数 "table"-作为你想迭代 -的``cpufreq_frequency_table * `` 。 +使用参数"pos" -- 一个 ``cpufreq_frequency_table *`` 作为循环指针，使用参数"table" -- 作为你想迭代 +的 ``cpufreq_frequency_table *`` 。 例如:: @@ -250,5 +251,5 @@ cpufreq_for_each_valid_entry(pos, table) - 该函数遍历所有条目，不包 pos->frequency = ... } -如果你需要在driver_freq_table中处理pos的位置，不要减去指针，因为它的代价相当高。相反，使用宏 +如果你需要在driver_freq_table中处理pos的位置，不要做指针减法，因为它的代价相当高。作为替代，使用宏 cpufreq_for_each_entry_idx() 和 cpufreq_for_each_valid_entry_idx() 。 diff --git a/Documentation/translations/zh_CN/cpu-freq/cpufreq-stats.rst b/Documentation/translations/zh_CN/cpu-freq/cpufreq-stats.rst index f14423099d4b..e8fdba923cd5 100644 --- a/Documentation/translations/zh_CN/cpu-freq/cpufreq-stats.rst +++ b/Documentation/translations/zh_CN/cpu-freq/cpufreq-stats.rst @@ -8,13 +8,15 @@ 司延腾 Yanteng Si <siyanteng@loongson.cn> -.. _cn_cpufreq-stats.rst: +:校译: + + 唐艺舟 Tang Yizhou <tangyeechou@gmail.com> ========================================== sysfs CPUFreq Stats的一般说明 ========================================== -用户信息 +为使用者准备的信息 作者: Venkatesh Pallipadi <venkatesh.pallipadi@intel.com> @@ -29,17 +31,16 @@ sysfs CPUFreq Stats的一般说明 1. 简介 =============== -cpufreq-stats是一个为每个CPU提供CPU频率统计的驱动。 -这些统计数据在/sysfs中以一堆只读接口的形式提供。这个接口（在配置好后）将出现在 -/sysfs（<sysfs root>/devices/system/cpu/cpuX/cpufreq/stats/）中cpufreq下的一个单 -独的目录中，提供给每个CPU。 -各种统计数据将在此目录下形成只读文件。 +cpufreq-stats是一种为每个CPU提供CPU频率统计的驱动。 +这些统计数据以/sysfs中一系列只读接口的形式呈现。cpufreq-stats接口（若已配置）将为每个CPU生成 +/sysfs（<sysfs root>/devices/system/cpu/cpuX/cpufreq/stats/）中cpufreq目录下的stats目录。 +各项统计数据将在stats目录下形成对应的只读文件。 -此驱动是独立于任何可能运行在你所用CPU上的特定cpufreq_driver而设计的。因此，它将与所有 -cpufreq_driver一起工作。 +此驱动是以独立于任何可能运行在你所用CPU上的特定cpufreq_driver的方式设计的。因此，它将能和任何 +cpufreq_driver协同工作。 -2. 提供的统计数据(举例说明) +2. 已提供的统计数据(有例子) ===================================== cpufreq stats提供了以下统计数据（在下面详细解释）。 @@ -48,8 +49,8 @@ cpufreq stats提供了以下统计数据（在下面详细解释）。 - total_trans - trans_table -所有的统计数据将从统计驱动被载入的时间（或统计被重置的时间）开始，到某一统计数据被读取的时间为止。 -显然，统计驱动不会有任何关于统计驱动载入之前的频率转换信息。 +所有统计数据来自以下时间范围：从统计驱动被加载的时间（或统计数据被重置的时间）开始，到某一统计数据被读取的时间为止。 +显然，统计驱动不会保存它被加载之前的任何频率转换信息。 :: @@ -64,14 +65,14 @@ cpufreq stats提供了以下统计数据（在下面详细解释）。 - **reset** -只写属性，可用于重置统计计数器。这对于评估不同调节器下的系统行为非常有用，且无需重启。 +只写属性，可用于重置统计计数器。这对于评估不同调节器的系统行为非常有用，且无需重启。 - **time_in_state** -此项给出了这个CPU所支持的每个频率所花费的时间。cat输出的每一行都会有"<frequency> -<time>"对，表示这个CPU在<frequency>上花费了<time>个usertime单位的时间。这里的 -usertime单位是10mS（类似于/proc中输出的其他时间）。 +此文件给出了在本CPU支持的每个频率上分别花费的时间。cat输出的每一行都是一个"<frequency> +<time>"对，表示这个CPU在<frequency>上花费了<time>个usertime单位的时间。输出的每一行对应 +一个CPU支持的频率。这里usertime单位是10mS（类似于/proc导出的其它时间）。 :: @@ -85,7 +86,7 @@ usertime单位是10mS（类似于/proc中输出的其他时间）。 - **total_trans** -给出了这个CPU上频率转换的总次数。cat的输出将有一个单一的计数，这就是频率转换的总数。 +此文件给出了这个CPU频率转换的总次数。cat的输出是一个计数值，它就是频率转换的总次数。 :: @@ -94,10 +95,10 @@ usertime单位是10mS（类似于/proc中输出的其他时间）。 - **trans_table** -这将提供所有CPU频率转换的细粒度信息。这里的cat输出是一个二维矩阵，其中一个条目<i, j>（第 +本文件提供所有CPU频率转换的细粒度信息。这里的cat输出是一个二维矩阵，其中一个条目<i, j>（第 i行，第j列）代表从Freq_i到Freq_j的转换次数。Freq_i行和Freq_j列遵循驱动最初提供给cpufreq -核的频率表的排序顺序，因此可以排序（升序或降序）或不排序。 这里的输出也包含了每行每列的实际 -频率值，以便更好地阅读。 +核心的频率表的排列顺序，因此可以已排序（升序或降序）或未排序。这里的输出也包含了实际 +频率值，分别按行和按列显示，以便更好地阅读。 如果转换表大于PAGE_SIZE，读取时将返回一个-EFBIG错误。 @@ -115,7 +116,7 @@ i行，第j列）代表从Freq_i到Freq_j的转换次数。Freq_i行和Freq_j列 3. 配置cpufreq-stats ============================ -要在你的内核中配置cpufreq-stats:: +按以下方式在你的内核中配置cpufreq-stats:: Config Main Menu Power management options (ACPI, APM) ---> @@ -124,7 +125,7 @@ i行，第j列）代表从Freq_i到Freq_j的转换次数。Freq_i行和Freq_j列 [*] CPU frequency translation statistics -"CPU Frequency scaling" (CONFIG_CPU_FREQ) 应该被启用以配置cpufreq-stats。 +"CPU Frequency scaling" (CONFIG_CPU_FREQ) 应该被启用，以支持配置cpufreq-stats。 "CPU frequency translation statistics" (CONFIG_CPU_FREQ_STAT)提供了包括 time_in_state、total_trans和trans_table的统计数据。 diff --git a/Documentation/translations/zh_CN/dev-tools/index.rst b/Documentation/translations/zh_CN/dev-tools/index.rst index 0f770b8664e9..77a8c44cdf49 100644 --- a/Documentation/translations/zh_CN/dev-tools/index.rst +++ b/Documentation/translations/zh_CN/dev-tools/index.rst @@ -22,13 +22,13 @@ Documentation/translations/zh_CN/dev-tools/testing-overview.rst :maxdepth: 2 testing-overview + sparse gcov kasan Todolist: - coccinelle - - sparse - kcov - ubsan - kmemleak diff --git a/Documentation/translations/zh_CN/sparse.txt b/Documentation/translations/zh_CN/dev-tools/sparse.rst index 0f444b83d639..556282437aad 100644 --- a/Documentation/translations/zh_CN/sparse.txt +++ b/Documentation/translations/zh_CN/dev-tools/sparse.rst @@ -1,34 +1,34 @@ -Chinese translated version of Documentation/dev-tools/sparse.rst +Copyright 2004 Linus Torvalds +Copyright 2004 Pavel Machek <pavel@ucw.cz> +Copyright 2006 Bob Copeland <me@bobcopeland.com> -If you have any comment or update to the content, please contact the -original document maintainer directly. However, if you have a problem -communicating in English you can also ask the Chinese maintainer for -help. Contact the Chinese maintainer if this translation is outdated -or if there is a problem with the translation. +.. include:: ../disclaimer-zh_CN.rst -Chinese maintainer: Li Yang <leoyang.li@nxp.com> ---------------------------------------------------------------------- -Documentation/dev-tools/sparse.rst 的中文翻译 +:Original: Documentation/dev-tools/sparse.rst -如果想评论或更新本文的内容，请直接联系原文档的维护者。如果你使用英文 -交流有困难的话，也可以向中文版维护者求助。如果本翻译更新不及时或者翻 -译存在问题，请联系中文版维护者。 +:翻译: -中文版维护者： 李阳 Li Yang <leoyang.li@nxp.com> -中文版翻译者： 李阳 Li Yang <leoyang.li@nxp.com> + Li Yang <leoyang.li@nxp.com> +:校译: -以下为正文 ---------------------------------------------------------------------- + 司延腾 Yanteng Si <siyanteng@loongson.cn> -Copyright 2004 Linus Torvalds -Copyright 2004 Pavel Machek <pavel@ucw.cz> -Copyright 2006 Bob Copeland <me@bobcopeland.com> +.. _cn_sparse: + +Sparse +====== + +Sparse是一个C程序的语义检查器；它可以用来发现内核代码的一些潜在问题。 关 +于sparse的概述，请参见https://lwn.net/Articles/689907/；本文档包含 +一些针对内核的sparse信息。 +关于sparse的更多信息，主要是关于它的内部结构，可以在它的官方网页上找到： +https://sparse.docs.kernel.org。 使用 sparse 工具做类型检查 ~~~~~~~~~~~~~~~~~~~~~~~~~~ -"__bitwise" 是一种类型属性，所以你应该这样使用它： +"__bitwise" 是一种类型属性，所以你应该这样使用它:: typedef int __bitwise pm_request_t; @@ -48,7 +48,7 @@ Copyright 2006 Bob Copeland <me@bobcopeland.com> 坦白来说，你并不需要使用枚举类型。上面那些实际都可以浓缩成一个特殊的"int __bitwise"类型。 -所以更简单的办法只要这样做： +所以更简单的办法只要这样做:: typedef int __bitwise pm_request_t; @@ -60,25 +60,42 @@ __bitwise"类型。 一个小提醒：常数整数"0"是特殊的。你可以直接把常数零当作位方式整数使用而 不用担心 sparse 会抱怨。这是因为"bitwise"（恰如其名）是用来确保不同位方 式类型不会被弄混（小尾模式，大尾模式，cpu尾模式，或者其他），对他们来说 -常数"0"确实是特殊的。 +常数"0"确实 **是** 特殊的。 + +使用sparse进行锁检查 +-------------------- + +下面的宏对于 gcc 来说是未定义的，在 sparse 运行时定义，以使用sparse的“上下文” +跟踪功能，应用于锁定。 这些注释告诉 sparse 什么时候有锁，以及注释的函数的进入和 +退出。 + +__must_hold - 指定的锁在函数进入和退出时被持有。 + +__acquires - 指定的锁在函数退出时被持有，但在进入时不被持有。 + +__releases - 指定的锁在函数进入时被持有，但在退出时不被持有。 + +如果函数在不持有锁的情况下进入和退出，在函数内部以平衡的方式获取和释放锁，则不 +需要注释。 +上面的三个注释是针对sparse否则会报告上下文不平衡的情况。 获取 sparse 工具 ~~~~~~~~~~~~~~~~ 你可以从 Sparse 的主页获取最新的发布版本： - http://www.kernel.org/pub/linux/kernel/people/josh/sparse/ + https://www.kernel.org/pub/software/devel/sparse/dist/ 或者，你也可以使用 git 克隆最新的 sparse 开发版本： - git://git.kernel.org/pub/scm/linux/kernel/git/josh/sparse.git + git://git.kernel.org/pub/scm/devel/sparse/sparse.git 一旦你下载了源码，只要以普通用户身份运行： make make install -它将会被自动安装到你的 ~/bin 目录下。 +如果是标准的用户，它将会被自动安装到你的~/bin目录下。 使用 sparse 工具 ~~~~~~~~~~~~~~~~ diff --git a/Documentation/translations/zh_CN/index.rst b/Documentation/translations/zh_CN/index.rst index a34e58733ac8..46e14ec9963d 100644 --- a/Documentation/translations/zh_CN/index.rst +++ b/Documentation/translations/zh_CN/index.rst @@ -23,6 +23,11 @@ 另外，随时欢迎您对内核文档进行改进；如果您想提供帮助，请加入vger.kernel.org 上的linux-doc邮件列表。 +顺便说下，中文文档也需要遵守内核编码风格，风格中中文和英文的主要不同就是中文 +的字符标点占用两个英文字符宽度， 所以，当英文要求不要超过每行100个字符时， +中文就不要超过50个字符。另外，也要注意'-'，'=' 等符号与相关标题的对齐。在将 +补丁提交到社区之前，一定要进行必要的checkpatch.pl检查和编译测试。 + 许可证文档 ---------- @@ -106,6 +111,7 @@ TODOList: virt/index infiniband/index accounting/index + scheduler/index TODOList: @@ -140,7 +146,6 @@ TODOList: * PCI/index * scsi/index * misc-devices/index -* scheduler/index * mhi/index 体系结构无关文档 diff --git a/Documentation/translations/zh_CN/process/submitting-patches.rst b/Documentation/translations/zh_CN/process/submitting-patches.rst index 3f1683cd4727..a9570165582a 100644 --- a/Documentation/translations/zh_CN/process/submitting-patches.rst +++ b/Documentation/translations/zh_CN/process/submitting-patches.rst @@ -254,29 +254,6 @@ Linus Torvalds 是决定改动能否进入 Linux 内核的最终裁决者。他 手册页补丁，或至少发送更改通知，以便一些信息进入手册页。还应将用户空间API 更改复制到 linux-api@vger.kernel.org。 -对于小的补丁，你也许会CC到搜集琐碎补丁的邮件列表(Trivial Patch Monkey) -trivial@kernel.org，那里专门收集琐碎的补丁。下面这样的补丁会被看作“琐碎的” -补丁： - - - 文档的拼写修正。 - - 修正会影响到 grep(1) 的拼写。 - - 警告信息修正(频繁的打印无用的警告是不好的。) - - 编译错误修正（代码逻辑的确是对的，只是编译有问题。） - - 运行时修正（只要真的修正了错误。） - - 移除使用了被废弃的函数/宏的代码(例如 check_region。) - - 联系方式和文档修正。 - - 用可移植的代码替换不可移植的代码（即使在体系结构相关的代码中，既然有 - - 人拷贝，只要它是琐碎的） - - 任何文件的作者/维护者对该文件的改动（例如 patch monkey 在重传模式下） - -(译注，关于“琐碎补丁”的一些说明：因为原文的这一部分写得比较简单，所以不得不 -违例写一下译注。"trivial"这个英文单词的本意是“琐碎的，不重要的。”但是在这里 -有稍微有一些变化，例如对一些明显的NULL指针的修正，属于运行时修正，会被归类 -到琐碎补丁里。虽然NULL指针的修正很重要，但是这样的修正往往很小而且很容易得到 -检验，所以也被归入琐碎补丁。琐碎补丁更精确的归类应该是 -“simple, localized & easy to verify”，也就是说简单的，局部的和易于检验的。 -trivial@kernel.org邮件列表的目的是针对这样的补丁，为提交者提供一个中心，来 -降低提交的门槛。) 6) 没有 MIME 编码，没有链接，没有压缩，没有附件，只有纯文本 ----------------------------------------------------------- diff --git a/Documentation/translations/zh_CN/scheduler/completion.rst b/Documentation/translations/zh_CN/scheduler/completion.rst new file mode 100644 index 000000000000..bc8218514e0a --- /dev/null +++ b/Documentation/translations/zh_CN/scheduler/completion.rst @@ -0,0 +1,256 @@ +.. include:: ../disclaimer-zh_CN.rst + +:Original: Documentation/scheduler/completion.rst + +:翻译: + + 司延腾 Yanteng Si <siyanteng@loongson.cn> + +:校译: + + 唐艺舟 Tang Yizhou <tangyeechou@gmail.com> + +======================================= +完成 - "等待完成" 屏障应用程序接口(API) +======================================= + +简介: +----- + +如果你有一个或多个线程必须等待某些内核活动达到某个点或某个特定的状态，完成可以为这 +个问题提供一个无竞争的解决方案。从语义上讲，它们有点像pthread_barrier()，并且使 +用的案例类似 + +完成是一种代码同步机制，它比任何滥用锁/信号量和忙等待循环的行为都要好。当你想用yield() +或一些古怪的msleep(1)循环来允许其它代码继续运行时，你可能想用wait_for_completion*() +调用和completion()来代替。 + +使用“完成”的好处是，它们有一个良好定义、聚焦的目标，这不仅使得我们很容易理解代码的意图， +而且它们也会生成更高效的代码，因为所有线程都可以继续执行，直到真正需要结果的时刻。而且等 +待和信号都高效的使用了低层调度器的睡眠/唤醒设施。 + +完成是建立在Linux调度器的等待队列和唤醒基础设施之上的。等待队列中的线程所等待的 +事件被简化为 ``struct completion`` 中的一个简单标志，被恰如其名地称为‘done’。 + +由于完成与调度有关，代码可以在kernel/sched/completion.c中找到。 + + +用法: +----- + +使用完成需要三个主要部分: + + - 'struct completion' 同步对象的初始化 + - 通过调用wait_for_completion()的一个变体来实现等待部分。 + - 通过调用complete()或complete_all()实现发信端。 + +也有一些辅助函数用于检查完成的状态。请注意，虽然必须先做初始化，但等待和信号部分可以 +按任何时间顺序出现。也就是说，一个线程在另一个线程检查是否需要等待它之前，已经将一个 +完成标记为 "done"，这是完全正常的。 + +要使用完成API，你需要#include <linux/completion.h>并创建一个静态或动态的 +``struct completion`` 类型的变量，它只有两个字段:: + + struct completion { + unsigned int done; + wait_queue_head_t wait; + }; + +结构体提供了->wait等待队列来放置任务进行等待（如果有的话），以及->done完成标志来表明它 +是否完成。 + +完成的命名应当与正在被同步的事件名一致。一个好的例子是:: + + wait_for_completion(&early_console_added); + + complete(&early_console_added); + +好的、直观的命名（一如既往地）有助于代码的可读性。将一个完成命名为 ``complete`` +是没有帮助的，除非其目的是超级明显的... + + +初始化完成: +----------- + +动态分配的完成对象最好被嵌入到数据结构中，以确保在函数/驱动的生命周期内存活，以防 +止与异步complete()调用发生竞争。 + +在使用wait_for_completion()的_timeout()或_killable()/_interruptible()变体 +时应特别小心，因为必须保证在所有相关活动（complete()或reinit_completion()）发生 +之前不会发生内存解除分配，即使这些等待函数由于超时或信号触发而过早返回。 + +动态分配的完成对象的初始化是通过调用init_completion()来完成的:: + + init_completion(&dynamic_object->done); + +在这个调用中，我们初始化 waitqueue 并将 ->done 设置为 0，即“not completed”或 +“not done”。 + +重新初始化函数reinit_completion()，只是将->done字段重置为0（“not done”），而 +不触及等待队列。这个函数的调用者必须确保没有任何令人讨厌的wait_for_completion() +调用在并行进行。 + +在同一个完成对象上调用init_completion()两次很可能是一个bug，因为它将队列重新初始 +化为一个空队列，已排队的任务可能会“丢失”--在这种情况下使用reinit_completion()，但 +要注意其他竞争。 + +对于静态声明和初始化，可以使用宏。 + +对于文件范围内的静态（或全局）声明，你可以使用 DECLARE_COMPLETION():: + + static DECLARE_COMPLETION(setup_done); + DECLARE_COMPLETION(setup_done); + +注意，在这种情况下，完成在启动时（或模块加载时）被初始化为“not done”，不需要调用 +init_completion()。 + +当完成被声明为一个函数中的局部变量时，那么应该总是明确地使用 +DECLARE_COMPLETION_ONSTACK()来初始化，这不仅仅是为了让lockdep正确运行，也是明确表 +名它有限的使用范围是有意为之并被仔细考虑的:: + + DECLARE_COMPLETION_ONSTACK(setup_done) + +请注意，当使用完成对象作为局部变量时，你必须敏锐地意识到函数堆栈的短暂生命期：在所有 +活动（如等待的线程）停止并且完成对象完全未被使用之前，函数不得返回到调用上下文。 + +再次强调这一点：特别是在使用一些具有更复杂结果的等待API变体时，比如超时或信号 +（_timeout(), _killable()和_interruptible()）变体，等待可能会提前完成，而对象可 +能仍在被其他线程使用 - 从wait_on_completion*()调用者函数的返回会取消分配函数栈，如 +果complete()在其它某线程中完成调用，会引起微小的数据损坏。简单的测试可能不会触发这 +些类型的竞争。 + +如果不确定的话，使用动态分配的完成对象， 最好是嵌入到其它一些生命周期长的对象中，长到 +超过使用完成对象的任何辅助线程的生命周期，或者有一个锁或其他同步机制来确保complete() +不会在一个被释放的对象中调用。 + +在堆栈上单纯地调用DECLARE_COMPLETION()会触发一个lockdep警告。 + +等待完成: +--------- + +对于一个线程来说，要等待一些并发活动的完成，它要在初始化的完成结构体上调用 +wait_for_completion():: + + void wait_for_completion(struct completion *done) + +一个典型的使用场景是:: + + CPU#1 CPU#2 + + struct completion setup_done; + + init_completion(&setup_done); + initialize_work(...,&setup_done,...); + + /* run non-dependent code */ /* do setup */ + + wait_for_completion(&setup_done); complete(setup_done); + +这并不意味着调用wait_for_completion()和complete()有任何特定的时间顺序--如果调 +用complete()发生在调用wait_for_completion()之前，那么等待方将立即继续执行，因为 +所有的依赖都得到了满足；如果没有，它将阻塞，直到complete()发出完成的信号。 + +注意，wait_for_completion()是在调用spin_lock_irq()/spin_unlock_irq()，所以 +只有当你知道中断被启用时才能安全地调用它。从IRQs-off的原子上下文中调用它将导致难以检 +测的错误的中断启用。 + +默认行为是不带超时的等待，并将任务标记为“UNINTERRUPTIBLE”状态。wait_for_completion() +及其变体只有在进程上下文中才是安全的（因为它们可以休眠），但在原子上下文、中断上下文、IRQ +被禁用或抢占被禁用的情况下是不安全的--关于在原子/中断上下文中处理完成的问题，还请看下面的 +try_wait_for_completion()。 + +由于wait_for_completion()的所有变体都可能（很明显）阻塞很长时间，这取决于它们所等 +待的活动的性质，所以在大多数情况下，你可能不想在持有mutex锁的情况下调用它。 + + +wait_for_completion*()可用的变体: +--------------------------------- + +下面的变体都会返回状态，在大多数(/所有)情况下都应该检查这个状态--在故意不检查状态的情 +况下，你可能要做一个说明(例如，见arch/arm/kernel/smp.c:__cpu_up())。 + +一个常见的问题是不准确的返回类型赋值，所以要注意将返回值赋值给适当类型的变量。 + +检查返回值的具体含义也可能被发现是相当不准确的，例如，像这样的构造:: + + if (!wait_for_completion_interruptible_timeout(...)) + +...会在成功完成和中断的情况下执行相同的代码路径--这可能不是你想要的结果:: + + int wait_for_completion_interruptible(struct completion *done) + +这个函数在任务等待时标记为TASK_INTERRUPTIBLE。如果在等待期间收到信号，它将返回 +-ERESTARTSYS；否则为0:: + + unsigned long wait_for_completion_timeout(struct completion *done, unsigned long timeout) + +该任务被标记为TASK_UNINTERRUPTIBLE，并将最多超时等待“timeout”个jiffies。如果超时发生，则 +返回0，否则返回剩余的时间（但至少是1）。 + +超时最好用msecs_to_jiffies()或usecs_to_jiffies()计算，以使代码在很大程度上不受 +HZ的影响。 + +如果返回的超时值被故意忽略，那么注释应该解释原因 +（例如，见drivers/mfd/wm8350-core.c wm8350_read_auxadc():: + + long wait_for_completion_interruptible_timeout(struct completion *done, unsigned long timeout) + +这个函数传递一个以jiffies为单位的超时，并将任务标记为TASK_INTERRUPTIBLE。如果收到 +信号，则返回-ERESTARTSYS；否则，如果完成超时，则返回0；如果完成了，则返回剩余的时间 +（jiffies）。 + +更多的变体包括_killable，它使用TASK_KILLABLE作为指定的任务状态，如果它被中断，将返 +回-ERESTARTSYS，如果完成了，则返回0。它也有一个_timeout变体:: + + long wait_for_completion_killable(struct completion *done) + long wait_for_completion_killable_timeout(struct completion *done, unsigned long timeout) + +wait_for_completion_io()的_io变体的行为与非_io变体相同，只是将等待时间计为“IO等待”， +这对任务在调度/IO统计中的计算方式有影响:: + + void wait_for_completion_io(struct completion *done) + unsigned long wait_for_completion_io_timeout(struct completion *done, unsigned long timeout) + + +对完成发信号: +------------- + +一个线程想要发出信号通知继续的条件已经达到，就会调用complete()，向其中一个等待者发出信 +号表明它可以继续:: + + void complete(struct completion *done) + +... or calls complete_all() to signal all current and future waiters:: + + void complete_all(struct completion *done) + +即使在线程开始等待之前就发出了完成的信号，信号传递也会继续进行。这是通过等待者 +“consuming”（递减）“struct completion” 的完成字段来实现的。等待的线程唤醒的顺序 +与它们被排队的顺序相同（FIFO顺序）。 + +如果多次调用complete()，那么这将允许该数量的等待者继续进行--每次调用complete()将 +简单地增加已完成的字段。但多次调用complete_all()是一个错误。complete()和 +complete_all()都可以在IRQ/atomic上下文中安全调用。 + +在任何时候，只能有一个线程在一个特定的 “struct completion”上调用 complete() 或 +complete_all() - 通过等待队列自旋锁进行序列化。任何对 complete() 或 +complete_all() 的并发调用都可能是一个设计错误。 + +从IRQ上下文中发出完成信号 是可行的，因为它将正确地用 +spin_lock_irqsave()/spin_unlock_irqrestore()执行锁操作 + + +try_wait_for_completion()/completion_done(): +-------------------------------------------- + +try_wait_for_completion()函数不会将线程放在等待队列中，而是在需要排队（阻塞）线 +程时返回false，否则会消耗一个已发布的完成并返回true:: + + bool try_wait_for_completion(struct completion *done) + +最后，为了在不以任何方式改变完成的情况下检查完成的状态，可以调用completion_done()， +如果没有发布的完成尚未被等待者消耗，则返回false（意味着存在等待者），否则返回true:: + + bool completion_done(struct completion *done) + +try_wait_for_completion()和completion_done()都可以在IRQ或原子上下文中安全调用。 diff --git a/Documentation/translations/zh_CN/scheduler/index.rst b/Documentation/translations/zh_CN/scheduler/index.rst new file mode 100644 index 000000000000..f8f8f35d53c7 --- /dev/null +++ b/Documentation/translations/zh_CN/scheduler/index.rst @@ -0,0 +1,44 @@ +.. include:: ../disclaimer-zh_CN.rst + +:Original: Documentation/scheduler/index.rst + +:翻译: + + 司延腾 Yanteng Si <siyanteng@loongson.cn> + +:校译: + + + +=============== +Linux调度器 +=============== + +.. toctree:: + :maxdepth: 1 + + completion + sched-arch + sched-bwc + sched-design-CFS + sched-domains + sched-capacity + + +TODOList: + + sched-bwc + sched-deadline + sched-energy + sched-nice-design + sched-rt-group + sched-stats + + text_files + +.. only:: subproject and html + + Indices + ======= + + * :ref:`genindex` diff --git a/Documentation/translations/zh_CN/scheduler/sched-arch.rst b/Documentation/translations/zh_CN/scheduler/sched-arch.rst new file mode 100644 index 000000000000..754a15c6b60f --- /dev/null +++ b/Documentation/translations/zh_CN/scheduler/sched-arch.rst @@ -0,0 +1,76 @@ +.. include:: ../disclaimer-zh_CN.rst + +:Original: Documentation/scheduler/sched-arch.rst + +:翻译: + + 司延腾 Yanteng Si <siyanteng@loongson.cn> + +:校译: + + + +=============================== +架构特定代码的CPU调度器实现提示 +=============================== + + Nick Piggin, 2005 + +上下文切换 +========== +1. 运行队列锁 +默认情况下，switch_to arch函数在调用时锁定了运行队列。这通常不是一个问题，除非 +switch_to可能需要获取运行队列锁。这通常是由于上下文切换中的唤醒操作造成的。见 +arch/ia64/include/asm/switch_to.h的例子。 + +为了要求调度器在运行队列解锁的情况下调用switch_to，你必须在头文件 +中`#define __ARCH_WANT_UNLOCKED_CTXSW`(通常是定义switch_to的那个文件）。 + +在CONFIG_SMP的情况下，解锁的上下文切换对核心调度器的实现只带来了非常小的性能损 +失。 + +CPU空转 +======= +你的cpu_idle程序需要遵守以下规则： + +1. 现在抢占应该在空闲的例程上禁用。应该只在调用schedule()时启用，然后再禁用。 + +2. need_resched/TIF_NEED_RESCHED 只会被设置，并且在运行任务调用 schedule() + 之前永远不会被清除。空闲线程只需要查询need_resched，并且永远不会设置或清除它。 + +3. 当cpu_idle发现（need_resched() == 'true'），它应该调用schedule()。否则 + 它不应该调用schedule()。 + +4. 在检查need_resched时，唯一需要禁用中断的情况是，我们要让处理器休眠到下一个中 + 断（这并不对need_resched提供任何保护，它可以防止丢失一个中断）: + + 4a. 这种睡眠类型的常见问题似乎是:: + + local_irq_disable(); + if (!need_resched()) { + local_irq_enable(); + *** resched interrupt arrives here *** + __asm__("sleep until next interrupt"); + } + +5. 当need_resched变为高电平时，TIF_POLLING_NRFLAG可以由不需要中断来唤醒它们 + 的空闲程序设置。换句话说，它们必须定期轮询need_resched，尽管做一些后台工作或 + 进入低CPU优先级可能是合理的。 + + - 5a. 如果TIF_POLLING_NRFLAG被设置，而我们确实决定进入一个中断睡眠，那 + 么需要清除它，然后发出一个内存屏障（接着测试need_resched，禁用中断，如3中解释）。 + +arch/x86/kernel/process.c有轮询和睡眠空闲函数的例子。 + + +可能出现的arch/问题 +=================== + +我发现的可能的arch问题（并试图解决或没有解决）。: + +ia64 - safe_halt的调用与中断相比，是否很荒谬？ (它睡眠了吗) (参考 #4a) + +sh64 - 睡眠与中断相比，是否很荒谬？ (参考 #4a) + +sparc - 在这一点上，IRQ是开着的（？），把local_irq_save改为_disable。 + - 待办事项: 需要第二个CPU来禁用抢占 (参考 #1) diff --git a/Documentation/translations/zh_CN/scheduler/sched-bwc.rst b/Documentation/translations/zh_CN/scheduler/sched-bwc.rst new file mode 100644 index 000000000000..90e931f4ceed --- /dev/null +++ b/Documentation/translations/zh_CN/scheduler/sched-bwc.rst @@ -0,0 +1,204 @@ +.. include:: ../disclaimer-zh_CN.rst + +:Original: Documentation/scheduler/sched-bwc.rst + +:翻译: + + 司延腾 Yanteng Si <siyanteng@loongson.cn> + +:校译: + + + +============ +CFS 带宽控制 +============ + +.. note:: + 本文只讨论了SCHED_NORMAL的CPU带宽控制。 + SCHED_RT的情况在Documentation/scheduler/sched-rt-group.rst中有涉及。 + +CFS带宽控制是一个CONFIG_FAIR_GROUP_SCHED扩展，它允许指定一个组或层次的最大CPU带宽。 + +一个组允许的带宽是用配额和周期指定的。在每个给定的”周期“（微秒）内，一个任务组被分配多 +达“配额”微秒的CPU时间。当cgroup中的线程可运行时，该配额以时间片段的方式被分配到每个cpu +运行队列中。一旦所有的配额被分配，任何额外的配额请求将导致这些线程被限流。被限流的线程将不 +能再次运行，直到下一个时期的配额得到补充。 + +一个组的未分配配额是全局跟踪的，在每个周期边界被刷新为cfs_quota单元。当线程消耗这个带宽时， +它以需求为基础被转移到cpu-local“筒仓”，在每次更新中转移的数量是可调整的，被描述为“片“（时 +间片）。 + +突发特性 +-------- +现在这个功能借来的时间是用于防范我们对未来的低估，代价是对其他系统用户的干扰增加。所有这些都 +有很好的限制。 + +传统的（UP-EDF）带宽控制是这样的: + + (U = \Sum u_i) <= 1 + +这既保证了每个最后期限的实现，也保证了系统的稳定。毕竟，如果U>1，那么每一秒钟的壁钟时间，我 +们就必须运行超过一秒钟的程序时间，显然会错过我们的最后期限，但下一个最后期限会更远，永远没有 +时间赶上，无边无界的失败。 + +突发特性观察到工作负载并不总是执行全部配额；这使得人们可以将u_i描述为一个统计分布。 + +例如，让u_i = {x,e}_i，其中x是p(95)和x+e p(100)（传统的WCET）。这实际上允许u更小，提 +高了效率（我们可以在系统中打包更多的任务），但代价是当所有的概率都一致时，会错过最后期限。然 +而，它确实保持了稳定性，因为只要我们的x高于平均水平，每一次超限都必须与低估相匹配。 + +也就是说，假设我们有两个任务，都指定了一个p(95)值，那么我们有一个p(95)*p(95)=90.25%的机 +会，两个任务都在他们的配额内，一切都很好。同时，我们有一个p(5)p(5)=0.25%的机会，两个任务同 +时超过他们的配额（保证最后期限失败）。在这两者之间有一个阈值，其中一个超过了，而另一个没有不足， +无法补偿；这取决于具体的CDFs。 + +同时，我们可以说，最坏的情况下的截止日期失败，将是Sum e_i；也就是说，有一个有界的迟延（在假 +设x+e确实是WCET的情况下）。 + +使用突发时的干扰是由错过最后期限的可能性和平均WCET来评价的。测试结果表明，当有许多cgroup或 +CPU未被充分利用时，干扰是有限的。更多的细节显示在： +https://lore.kernel.org/lkml/5371BD36-55AE-4F71-B9D7-B86DC32E3D2B@linux.alibaba.com/ + +管理 +---- +配额、周期和突发是在cpu子系统内通过cgroupfs管理的。 + +.. note:: + 本节描述的cgroupfs文件只适用于cgroup v1.对于cgroup v2，请参阅Control Group v2。 + :ref:`Documentation/admin-guide/cgroup-v2.rst <cgroup-v2-cpu>`. + +- cpu.cfs_quota_us：在一个时期内补充的运行时间（微秒）。 +- cpu.cfs_period_us：一个周期的长度（微秒）。 +- cpu.stat: 输出节流统计数据[下面进一步解释] +- cpu.cfs_burst_us：最大累积运行时间（微秒）。 + +默认值是:: + + cpu.cfs_period_us=100ms + cpu.cfs_quota_us=-1 + cpu.cfs_burst_us=0 + +cpu.cfs_quota_us的值为-1表示该组没有任何带宽限制，这样的组被描述为无限制的带宽组。这代表 +了CFS的传统工作保护行为。 + +写入不小于cpu.cfs_burst_us的任何（有效的）正值将配发指定的带宽限制。该配额或周期允许的最 +小配额是1ms。周期长度也有一个1s的上限。当带宽限制以分层方式使用时，存在额外的限制，这些在下 +面有更详细的解释。 + +向cpu.cfs_quota_us写入任何负值都会移除带宽限制，并使组再次回到无限制的状态。 + +cpu.cfs_burst_us的值为0表示该组不能积累任何未使用的带宽。它使得CFS的传统带宽控制行为没有 +改变。将不大于 cpu.cfs_quota_us 的任何(有效的)正值写入 cpu.cfs_burst_us 将配发未使用 +带宽累积的上限。 + +如果一个组处于受限状态，对该组带宽规格的任何更新都将导致其成为无限流状态。 + +系统范围设置 +------------ +为了提高效率，运行时间在全局池和CPU本地“筒仓”之间以批处理方式转移。这大大减少了大型系统的全 +局核算压力。每次需要进行这种更新时，传输的数量被描述为 "片"。 + +这是可以通过procfs调整的:: + + /proc/sys/kernel/sched_cfs_bandwidth_slice_us (default=5ms) + +较大的时间片段值将减少传输开销，而较小的值则允许更精细的消费。 + +统计 +---- +一个组的带宽统计数据通过cpu.stat的5个字段导出。 + +cpu.stat: + +- nr_periods：已经过去的执行间隔的数量。 +- nr_throttled: 该组已被节流/限制的次数。 +- throttled_time: 该组的实体被限流的总时间长度（纳秒）。 +- nr_bursts：突发发生的周期数。 +- burst_time: 任何CPU在各个时期使用超过配额的累计壁钟时间（纳秒）。 + +这个接口是只读的。 + +分层考虑 +-------- +该接口强制要求单个实体的带宽总是可以达到的，即：max(c_i) <= C。然而，在总体情况下，是明确 +允许过度订阅的，以便在一个层次结构中实现工作保护语义: + + 例如，Sum (c_i)可能超过C + +[ 其中C是父方的带宽，c_i是其子方的带宽。 ] + +.. note:: + 译文中的父亲/孩子指的是cgroup parent, cgroup children。 + +有两种方式可以使一个组变得限流: + + a. 它在一段时期内完全消耗自己的配额 + b. 父方的配额在其期间内全部用完 + +在上述b)情况下，即使孩子可能有剩余的运行时间，它也不会被允许，直到父亲的运行时间被刷新。 + +CFS带宽配额的注意事项 +--------------------- +一旦一个片断被分配给一个cpu，它就不会过期。然而，如果该cpu上的所有线程都无法运行，那么除了 +1ms以外的所有时间片都可以返回到全局池中。这是在编译时由min_cfs_rq_runtime变量配置的。这 +是一个性能调整，有助于防止对全局锁的额外争夺。 + +cpu-local分片不会过期的事实导致了一些有趣的罕见案例，应该被理解。 + +对于cgroup cpu限制的应用程序来说，这是一个相对有意义的问题，因为他们自然会消耗他们的全部配 +额，以及每个cpu-本地片在每个时期的全部。因此，预计nr_periods大致等于nr_throttled，并且 +cpuacct.用量的增加大致等于cfs_quota_us在每个周期的增加。 + +对于高线程、非cpu绑定的应用程序，这种非过期的细微差别允许应用程序短暂地突破他们的配额限制， +即任务组正在运行的每个cpu上未使用的片断量（通常每个cpu最多1ms或由min_cfs_rq_runtime定 +义）。这种轻微的突发只适用于配额已经分配给cpu，然后没有完全使用或在以前的时期返回。这个突发 +量不会在核心之间转移。因此，这种机制仍然严格限制任务组的配额平均使用量，尽管是在比单一时期更 +长的时间窗口。这也限制了突发能力，每个cpu不超过1ms。这为在高核数机器上有小配额限制的高线程 +应用提供了更好的更可预测的用户体验。它还消除了在使用低于配额的cpu时对这些应用进行节流的倾向。 +另一种说法是，通过允许一个片断的未使用部分在不同时期保持有效，我们减少了在不需要整个片断的cpu +时间的cpu-local 筒仓上浪费配额的可能性。 + +绑定cpu和非绑定cpu的交互式应用之间的互动也应该被考虑，特别是当单核使用率达到100%时。如果你 +给了这些应用程序一半的cpu-core，并且它们都被安排在同一个CPU上，理论上非cpu绑定的应用程序有 +可能在某些时期使用多达1ms的额外配额，从而阻止cpu绑定的应用程序完全使用其配额，这也是同样的数 +量。在这些情况下，将由CFS算法（见CFS调度器）来决定选择哪个应用程序来运行，因为它们都是可运行 +的，并且有剩余的配额。这个运行时间的差异将在接下来的交互式应用程序空闲期间得到弥补。 + +例子 +---- +1. 限制一个组的运行时间为1个CPU的价值:: + + 如果周期是250ms，配额也是250ms，那么该组将每250ms获得价值1个CPU的运行时间。 + + # echo 250000 > cpu.cfs_quota_us /* quota = 250ms */ + # echo 250000 > cpu.cfs_period_us /* period = 250ms */ + +2. 在多CPU机器上，将一个组的运行时间限制为2个CPU的价值 + + 在500ms周期和1000ms配额的情况下，该组每500ms可以获得2个CPU的运行时间:: + + # echo 1000000 > cpu.cfs_quota_us /* quota = 1000ms */ + # echo 500000 > cpu.cfs_period_us /* period = 500ms */ + + 这里较大的周期允许增加突发能力。 + +3. 将一个组限制在1个CPU的20%。 + + 在50ms周期内，10ms配额将相当于1个CPU的20%。:: + + # echo 10000 > cpu.cfs_quota_us /* quota = 10ms */ + # echo 50000 > cpu.cfs_period_us /* period = 50ms */ + + 通过在这里使用一个小的周期，我们以牺牲突发容量为代价来确保稳定的延迟响应。 + +4. 将一个组限制在1个CPU的40%，并允许累积到1个CPU的20%，如果已经累积了的话。 + + 在50ms周期内，20ms配额将相当于1个CPU的40%。而10毫秒的突发将相当于1个 + CPU的20%:: + + # echo 20000 > cpu.cfs_quota_us /* quota = 20ms */ + # echo 50000 > cpu.cfs_period_us /* period = 50ms */ + # echo 10000 > cpu.cfs_burst_us /* burst = 10ms */ + + 较大的缓冲区设置（不大于配额）允许更大的突发容量。 diff --git a/Documentation/translations/zh_CN/scheduler/sched-capacity.rst b/Documentation/translations/zh_CN/scheduler/sched-capacity.rst new file mode 100644 index 000000000000..3a52053c29dc --- /dev/null +++ b/Documentation/translations/zh_CN/scheduler/sched-capacity.rst @@ -0,0 +1,390 @@ +.. SPDX-License-Identifier: GPL-2.0 +.. include:: ../disclaimer-zh_CN.rst + +:Original: Documentation/scheduler/sched-capacity.rst + +:翻译: + + 唐艺舟 Tang Yizhou <tangyeechou@gmail.com> + +:校译: + + 时奎亮 Alex Shi <alexs@kernel.org> + +============= +算力感知调度 +============= + +1. CPU算力 +========== + +1.1 简介 +-------- + +一般来说，同构的SMP平台由完全相同的CPU构成。异构的平台则由性能特征不同的CPU构成，在这样的 +平台中，CPU不能被认为是相同的。 + +我们引入CPU算力（capacity）的概念来测量每个CPU能达到的性能，它的值相对系统中性能最强的CPU +做过归一化处理。异构系统也被称为非对称CPU算力系统，因为它们由不同算力的CPU组成。 + +最大可达性能（换言之，最大CPU算力）的差异有两个主要来源: + +- 不是所有CPU的微架构都相同。 +- 在动态电压频率升降（Dynamic Voltage and Frequency Scaling，DVFS）框架中，不是所有的CPU都 + 能达到一样高的操作性能值（Operating Performance Points，OPP。译注，也就是“频率-电压”对）。 + +Arm大小核（big.LITTLE）系统是同时具有两种差异的一个例子。相较小核，大核面向性能（拥有更多的 +流水线层级，更大的缓存，更智能的分支预测器等），通常可以达到更高的操作性能值。 + +CPU性能通常由每秒百万指令（Millions of Instructions Per Second，MIPS）表示，也可表示为 +per Hz能执行的指令数，故:: + + capacity(cpu) = work_per_hz(cpu) * max_freq(cpu) + +1.2 调度器术语 +-------------- + +调度器使用了两种不同的算力值。CPU的 ``capacity_orig`` 是它的最大可达算力，即最大可达性能等级。 +CPU的 ``capacity`` 是 ``capacity_orig`` 扣除了一些性能损失（比如处理中断的耗时）的值。 + +注意CPU的 ``capacity`` 仅仅被设计用于CFS调度类，而 ``capacity_orig`` 是不感知调度类的。为 +简洁起见，本文档的剩余部分将不加区分的使用术语 ``capacity`` 和 ``capacity_orig`` 。 + +1.3 平台示例 +------------ + +1.3.1 操作性能值相同 +~~~~~~~~~~~~~~~~~~~~ + +考虑一个假想的双核非对称CPU算力系统，其中 + +- work_per_hz(CPU0) = W +- work_per_hz(CPU1) = W/2 +- 所有CPU以相同的固定频率运行 + +根据上文对算力的定义: + +- capacity(CPU0) = C +- capacity(CPU1) = C/2 + +若这是Arm大小核系统，那么CPU0是大核，而CPU1是小核。 + +考虑一种周期性产生固定工作量的工作负载，你将会得到类似下图的执行轨迹:: + + CPU0 work ^ + | ____ ____ ____ + | | | | | | | + +----+----+----+----+----+----+----+----+----+----+-> time + + CPU1 work ^ + | _________ _________ ____ + | | | | | | + +----+----+----+----+----+----+----+----+----+----+-> time + +CPU0在系统中具有最高算力（C），它使用T个单位时间完成固定工作量W。另一方面，CPU1只有CPU0一半 +算力，因此在T个单位时间内仅完成工作量W/2。 + +1.3.2 最大操作性能值不同 +~~~~~~~~~~~~~~~~~~~~~~~~ + +具有不同算力值的CPU，通常来说最大操作性能值也不同。考虑上一小节提到的CPU（也就是说， +work_per_hz()相同）: + +- max_freq(CPU0) = F +- max_freq(CPU1) = 2/3 * F + +这将推出： + +- capacity(CPU0) = C +- capacity(CPU1) = C/3 + +执行1.3.1节描述的工作负载，每个CPU按最大频率运行，结果为:: + + CPU0 work ^ + | ____ ____ ____ + | | | | | | | + +----+----+----+----+----+----+----+----+----+----+-> time + + workload on CPU1 + CPU1 work ^ + | ______________ ______________ ____ + | | | | | | + +----+----+----+----+----+----+----+----+----+----+-> time + +1.4 关于计算方式的注意事项 +-------------------------- + +需要注意的是，使用单一值来表示CPU性能的差异是有些争议的。两个不同的微架构的相对性能差异应该 +描述为：X%整数运算差异，Y%浮点数运算差异，Z%分支跳转差异，等等。尽管如此，使用简单计算方式 +的结果目前还是令人满意的。 + +2. 任务使用率 +============= + +2.1 简介 +-------- + +算力感知调度要求描述任务需求，描述方式要和CPU算力相关。每个调度类可以用不同的方式描述它。 +任务使用率是CFS独有的描述方式，不过在这里介绍它有助于引入更多一般性的概念。 + +任务使用率是一种用百分比来描述任务吞吐率需求的方式。一个简单的近似是任务的占空比，也就是说:: + + task_util(p) = duty_cycle(p) + +在频率固定的SMP系统中，100%的利用率意味着任务是忙等待循环。反之，10%的利用率暗示这是一个 +小周期任务，它在睡眠上花费的时间比执行更多。 + +2.2 频率不变性 +-------------- + +一个需要考虑的议题是，工作负载的占空比受CPU正在运行的操作性能值直接影响。考虑以给定的频率F +执行周期性工作负载:: + + CPU work ^ + | ____ ____ ____ + | | | | | | | + +----+----+----+----+----+----+----+----+----+----+-> time + +可以算出 duty_cycle(p) == 25%。 + +现在，考虑以给定频率F/2执行 *同一个* 工作负载:: + + CPU work ^ + | _________ _________ ____ + | | | | | | + +----+----+----+----+----+----+----+----+----+----+-> time + +可以算出 duty_cycle(p) == 50%，尽管两次执行中，任务的行为完全一致（也就是说，执行的工作量 +相同）。 + +任务利用率信号可按下面公式处理成频率不变的（译注：这里的术语用到了信号与系统的概念）:: + + task_util_freq_inv(p) = duty_cycle(p) * (curr_frequency(cpu) / max_frequency(cpu)) + +对上面两个例子运用该公式，可以算出频率不变的任务利用率均为25%。 + +2.3 CPU不变性 +------------- + +CPU算力与任务利用率具有类型的效应，在算力不同的CPU上执行完全相同的工作负载，将算出不同的 +占空比。 + +考虑1.3.2节提到的系统，也就是说:: + +- capacity(CPU0) = C +- capacity(CPU1) = C/3 + +每个CPU按最大频率执行指定周期性工作负载，结果为:: + + CPU0 work ^ + | ____ ____ ____ + | | | | | | | + +----+----+----+----+----+----+----+----+----+----+-> time + + CPU1 work ^ + | ______________ ______________ ____ + | | | | | | + +----+----+----+----+----+----+----+----+----+----+-> time + +也就是说， + +- duty_cycle(p) == 25%，如果任务p在CPU0上按最大频率运行。 +- duty_cycle(p) == 75%，如果任务p在CPU1上按最大频率运行。 + +任务利用率信号可按下面公式处理成CPU算力不变的:: + + task_util_cpu_inv(p) = duty_cycle(p) * (capacity(cpu) / max_capacity) + +其中 ``max_capacity`` 是系统中最高的CPU算力。对上面的例子运用该公式，可以算出CPU算力不变 +的任务利用率均为25%。 + +2.4 任务利用率不变量 +-------------------- + +频率和CPU算力不变性都需要被应用到任务利用率的计算中，以便求出真正的不变信号。 +任务利用率的伪计算公式是同时具备CPU和频率不变性的，也就是说，对于指定任务p:: + + curr_frequency(cpu) capacity(cpu) + task_util_inv(p) = duty_cycle(p) * ------------------- * ------------- + max_frequency(cpu) max_capacity + +也就是说，任务利用率不变量假定任务在系统中最高算力CPU上以最高频率运行，以此描述任务的行为。 + +在接下来的章节中提到的任何任务利用率，均是不变量的形式。 + +2.5 利用率估算 +-------------- + +由于预测未来的水晶球不存在，当任务第一次变成可运行时，任务的行为和任务利用率均不能被准确预测。 +CFS调度类基于实体负载跟踪机制（Per-Entity Load Tracking, PELT）维护了少量CPU和任务信号， +其中之一可以算出平均利用率（与瞬时相反）。 + +这意味着，尽管运用“真实的”任务利用率（凭借水晶球）写出算力感知调度的准则，但是它的实现将只能 +用任务利用率的估算值。 + +3. 算力感知调度的需求 +===================== + +3.1 CPU算力 +----------- + +当前，Linux无法凭自身算出CPU算力，因此必须要有把这个信息传递给Linux的方式。每个架构必须为此 +定义arch_scale_cpu_capacity()函数。 + +arm和arm64架构直接把这个信息映射到arch_topology驱动的CPU scaling数据中（译注：参考 +arch_topology.h的percpu变量cpu_scale），它是从capacity-dmips-mhz CPU binding中衍生计算 +出来的。参见Documentation/devicetree/bindings/arm/cpu-capacity.txt。 + +3.2 频率不变性 +-------------- + +如2.2节所述，算力感知调度需要频率不变的任务利用率。每个架构必须为此定义 +arch_scale_freq_capacity(cpu)函数。 + +实现该函数要求计算出每个CPU当前以什么频率在运行。实现它的一种方式是利用硬件计数器（x86的 +APERF/MPERF，arm64的AMU），它能按CPU当前频率动态可扩展地升降递增计数器的速率。另一种方式是 +在cpufreq频率变化时直接使用钩子函数，内核此时感知到将要被切换的频率（也被arm/arm64实现了）。 + +4. 调度器拓扑结构 +================= + +在构建调度域时，调度器将会发现系统是否表现为非对称CPU算力。如果是，那么： + +- sched_asym_cpucapacity静态键（static key）将使能。 +- SD_ASYM_CPUCAPACITY_FULL标志位将在尽量最低调度域层级中被设置，同时要满足条件：调度域恰好 + 完整包含某个CPU算力值的全部CPU。 +- SD_ASYM_CPUCAPACITY标志将在所有包含非对称CPU的调度域中被设置。 + +sched_asym_cpucapacity静态键的设计意图是，保护为非对称CPU算力系统所准备的代码。不过要注意的 +是，这个键是系统范围可见的。想象下面使用了cpuset的步骤:: + + capacity C/2 C + ________ ________ + / \ / \ + CPUs 0 1 2 3 4 5 6 7 + \__/ \______________/ + cpusets cs0 cs1 + +可以通过下面的方式创建： + +.. code-block:: sh + + mkdir /sys/fs/cgroup/cpuset/cs0 + echo 0-1 > /sys/fs/cgroup/cpuset/cs0/cpuset.cpus + echo 0 > /sys/fs/cgroup/cpuset/cs0/cpuset.mems + + mkdir /sys/fs/cgroup/cpuset/cs1 + echo 2-7 > /sys/fs/cgroup/cpuset/cs1/cpuset.cpus + echo 0 > /sys/fs/cgroup/cpuset/cs1/cpuset.mems + + echo 0 > /sys/fs/cgroup/cpuset/cpuset.sched_load_balance + +由于“这是”非对称CPU算力系统，sched_asym_cpucapacity静态键将使能。然而，CPU 0--1对应的 +调度域层级，算力值仅有一个，该层级中SD_ASYM_CPUCAPACITY未被设置，它描述的是一个SMP区域，也 +应该被以此处理。 + +因此，“典型的”保护非对称CPU算力代码路径的代码模式是： + +- 检查sched_asym_cpucapacity静态键 +- 如果它被使能，接着检查调度域层级中SD_ASYM_CPUCAPACITY标志位是否出现 + +5. 算力感知调度的实现 +===================== + +5.1 CFS +------- + +5.1.1 算力适应性（fitness） +~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +CFS最主要的算力调度准则是:: + + task_util(p) < capacity(task_cpu(p)) + +它通常被称为算力适应性准则。也就是说，CFS必须保证任务“适合”在某个CPU上运行。如果准则被违反， +任务将要更长地消耗该CPU，任务是CPU受限的（CPU-bound）。 + +此外，uclamp允许用户空间指定任务的最小和最大利用率，要么以sched_setattr()的方式，要么以 +cgroup接口的方式（参阅Documentation/admin-guide/cgroup-v2.rst）。如其名字所暗示，uclamp +可以被用在前一条准则中限制task_util()。 + +5.1.2 被唤醒任务的CPU选择 +~~~~~~~~~~~~~~~~~~~~~~~~~ + +CFS任务唤醒的CPU选择，遵循上面描述的算力适应性准则。在此之上，uclamp被用来限制任务利用率， +这令用户空间对CFS任务的CPU选择有更多的控制。也就是说，CFS被唤醒任务的CPU选择，搜索满足以下 +条件的CPU:: + + clamp(task_util(p), task_uclamp_min(p), task_uclamp_max(p)) < capacity(cpu) + +通过使用uclamp，举例来说，用户空间可以允许忙等待循环（100%使用率）在任意CPU上运行，只要给 +它设置低的uclamp.max值。相反，uclamp能强制一个小的周期性任务（比如，10%利用率）在最高性能 +的CPU上运行，只要给它设置高的uclamp.min值。 + +.. note:: + + CFS的被唤醒的任务的CPU选择，可被能耗感知调度（Energy Aware Scheduling，EAS）覆盖，在 + Documentation/scheduler/sched-energy.rst中描述。 + +5.1.3 负载均衡 +~~~~~~~~~~~~~~ + +被唤醒任务的CPU选择的一个病理性的例子是，任务几乎不睡眠，那么也几乎不发生唤醒。考虑:: + + w == wakeup event + + capacity(CPU0) = C + capacity(CPU1) = C / 3 + + workload on CPU0 + CPU work ^ + | _________ _________ ____ + | | | | | | + +----+----+----+----+----+----+----+----+----+----+-> time + w w w + + workload on CPU1 + CPU work ^ + | ____________________________________________ + | | + +----+----+----+----+----+----+----+----+----+----+-> + w + +该工作负载应该在CPU0上运行，不过如果任务满足以下条件之一： + +- 一开始发生不合适的调度（不准确的初始利用率估计） +- 一开始调度正确，但突然需要更多的处理器功率 + +则任务可能变为CPU受限的，也就是说 ``task_util(p) > capacity(task_cpu(p))`` ；CPU算力 +调度准则被违反，将不会有任何唤醒事件来修复这个错误的CPU选择。 + +这种场景下的任务被称为“不合适的”（misfit）任务，处理这个场景的机制同样也以此命名。Misfit +任务迁移借助CFS负载均衡器，更明确的说，是主动负载均衡的部分（用来迁移正在运行的任务）。 +当发生负载均衡时，如果一个misfit任务可以被迁移到一个相较当前运行的CPU具有更高算力的CPU上， +那么misfit任务的主动负载均衡将被触发。 + +5.2 实时调度 +------------ + +5.2.1 被唤醒任务的CPU选择 +~~~~~~~~~~~~~~~~~~~~~~~~~ + +实时任务唤醒时的CPU选择，搜索满足以下条件的CPU:: + + task_uclamp_min(p) <= capacity(task_cpu(cpu)) + +同时仍然允许接着使用常规的优先级限制。如果没有CPU能满足这个算力准则，那么将使用基于严格 +优先级的调度，CPU算力将被忽略。 + +5.3 最后期限调度 +---------------- + +5.3.1 被唤醒任务的CPU选择 +~~~~~~~~~~~~~~~~~~~~~~~~~ + +最后期限任务唤醒时的CPU选择，搜索满足以下条件的CPU:: + + task_bandwidth(p) < capacity(task_cpu(p)) + +同时仍然允许接着使用常规的带宽和截止期限限制。如果没有CPU能满足这个算力准则，那么任务依然 +在当前CPU队列中。 diff --git a/Documentation/translations/zh_CN/scheduler/sched-design-CFS.rst b/Documentation/translations/zh_CN/scheduler/sched-design-CFS.rst new file mode 100644 index 000000000000..26b0f36f793d --- /dev/null +++ b/Documentation/translations/zh_CN/scheduler/sched-design-CFS.rst @@ -0,0 +1,205 @@ +.. SPDX-License-Identifier: GPL-2.0 +.. include:: ../disclaimer-zh_CN.rst + +:Original: Documentation/scheduler/sched-design-CFS.rst + +:翻译: + + 唐艺舟 Tang Yizhou <tangyeechou@gmail.com> + +=============== +完全公平调度器 +=============== + + +1. 概述 +======= + +CFS表示“完全公平调度器”，它是为桌面新设计的进程调度器，由Ingo Molnar实现并合入Linux +2.6.23。它替代了之前原始调度器中SCHED_OTHER策略的交互式代码。 + +CFS 80%的设计可以总结为一句话：CFS在真实硬件上建模了一个“理想的，精确的多任务CPU”。 + +“理想的多任务CPU”是一种（不存在的 :-)）具有100%物理算力的CPU，它能让每个任务精确地以 +相同的速度并行运行，速度均为1/nr_running。举例来说，如果有两个任务正在运行，那么每个 +任务获得50%物理算力。 --- 也就是说，真正的并行。 + +在真实的硬件上，一次只能运行一个任务，所以我们需要介绍“虚拟运行时间”的概念。任务的虚拟 +运行时间表明，它的下一个时间片将在上文描述的理想多任务CPU上开始执行。在实践中，任务的 +虚拟运行时间由它的真实运行时间相较正在运行的任务总数归一化计算得到。 + + + +2. 一些实现细节 +=============== + +在CFS中，虚拟运行时间由每个任务的p->se.vruntime（单位为纳秒）的值表达和跟踪。因此， +精确地计时和测量一个任务应得的“预期的CPU时间”是可能的。 + + 一些细节：在“理想的”硬件上，所有的任务在任何时刻都应该具有一样的p->se.vruntime值， + --- 也就是说，任务应当同时执行，没有任务会在“理想的”CPU分时中变得“不平衡”。 + +CFS的任务选择逻辑基于p->se.vruntime的值，因此非常简单：总是试图选择p->se.vruntime值 +最小的任务运行（也就是说，至今执行时间最少的任务）。CFS总是尽可能尝试按“理想多任务硬件” +那样将CPU时间在可运行任务中均分。 + +CFS剩下的其它设计，一般脱离了这个简单的概念，附加的设计包括nice级别，多处理，以及各种 +用来识别已睡眠任务的算法变体。 + + + +3. 红黑树 +========= + +CFS的设计非常激进：它不使用运行队列的旧数据结构，而是使用按时间排序的红黑树，构建出 +任务未来执行的“时间线”。因此没有任何“数组切换”的旧包袱（之前的原始调度器和RSDL/SD都 +被它影响）。 + +CFS同样维护了rq->cfs.min_vruntime值，它是单调递增的，跟踪运行队列中的所有任务的最小 +虚拟运行时间值。系统做的全部工作是：使用min_vruntime跟踪，然后用它的值将新激活的调度 +实体尽可能地放在红黑树的左侧。 + +运行队列中正在运行的任务的总数由rq->cfs.load计数，它是运行队列中的任务的权值之和。 + +CFS维护了一个按时间排序的红黑树，所有可运行任务以p->se.vruntime为键值排序。CFS从这颗 +树上选择“最左侧”的任务并运行。系统继续运行，被执行过的任务越来越被放到树的右侧 --- 缓慢， +但很明确每个任务都有成为“最左侧任务”的机会，因此任务将确定性地获得一定量CPU时间。 + +总结一下，CFS工作方式像这样：它运行一个任务一会儿，当任务发生调度（或者调度器时钟滴答 +tick产生），就会考虑任务的CPU使用率：任务刚刚花在物理CPU上的（少量）时间被加到 +p->se.vruntime。一旦p->se.vruntime变得足够大，其它的任务将成为按时间排序的红黑树的 +“最左侧任务”（相较最左侧的任务，还要加上一个很小的“粒度”量，使得我们不会对任务过度调度， +导致缓存颠簸），然后新的最左侧任务将被选中，当前任务被抢占。 + + + + +4. CFS的一些特征 +================ + +CFS使用纳秒粒度的计时，不依赖于任何jiffies或HZ的细节。因此CFS并不像之前的调度器那样 +有“时间片”的概念，也没有任何启发式的设计。唯一可调的参数（你需要打开CONFIG_SCHED_DEBUG）是： + + /proc/sys/kernel/sched_min_granularity_ns + +它可以用来将调度器从“桌面”模式（也就是低时延）调节为“服务器”（也就是高批处理）模式。 +它的默认设置是适合桌面的工作负载。SCHED_BATCH也被CFS调度器模块处理。 + +CFS的设计不易受到当前存在的任何针对stock调度器的“攻击”的影响，包括fiftyp.c，thud.c， +chew.c，ring-test.c，massive_intr.c，它们都能很好地运行，不会影响交互性，将产生 +符合预期的行为。 + +CFS调度器处理nice级别和SCHED_BATCH的能力比之前的原始调度器更强：两种类型的工作负载 +都被更激进地隔离了。 + +SMP负载均衡被重做/清理过：遍历运行队列的假设已经从负载均衡的代码中移除，使用调度模块 +的迭代器。结果是，负载均衡代码变得简单不少。 + + + +5. 调度策略 +=========== + +CFS实现了三种调度策略： + + - SCHED_NORMAL：（传统被称为SCHED_OTHER）：该调度策略用于普通任务。 + + - SCHED_BATCH：抢占不像普通任务那样频繁，因此允许任务运行更长时间，更好地利用缓存， + 不过要以交互性为代价。它很适合批处理工作。 + + - SCHED_IDLE：它比nice 19更弱，不过它不是真正的idle定时器调度器，因为要避免给机器 + 带来死锁的优先级反转问题。 + +SCHED_FIFO/_RR被实现在sched/rt.c中，它们由POSIX具体说明。 + +util-linux-ng 2.13.1.1中的chrt命令可以设置以上所有策略，除了SCHED_IDLE。 + + + +6. 调度类 +========= + +新的CFS调度器被设计成支持“调度类”，一种调度模块的可扩展层次结构。这些模块封装了调度策略 +细节，由调度器核心代码处理，且无需对它们做太多假设。 + +sched/fair.c 实现了上文描述的CFS调度器。 + +sched/rt.c 实现了SCHED_FIFO和SCHED_RR语义，且比之前的原始调度器更简洁。它使用了100个 +运行队列（总共100个实时优先级，替代了之前调度器的140个），且不需要过期数组（expired +array）。 + +调度类由sched_class结构体实现，它包括一些函数钩子，当感兴趣的事件发生时，钩子被调用。 + +这是（部分）钩子的列表： + + - enqueue_task(...) + + 当任务进入可运行状态时，被调用。它将调度实体（任务）放到红黑树中，增加nr_running变量 + 的值。 + + - dequeue_task(...) + + 当任务不再可运行时，这个函数被调用，对应的调度实体被移出红黑树。它减少nr_running变量 + 的值。 + + - yield_task(...) + + 这个函数的行为基本上是出队，紧接着入队，除非compat_yield sysctl被开启。在那种情况下， + 它将调度实体放在红黑树的最右端。 + + - check_preempt_curr(...) + + 这个函数检查进入可运行状态的任务能否抢占当前正在运行的任务。 + + - pick_next_task(...) + + 这个函数选择接下来最适合运行的任务。 + + - set_curr_task(...) + + 这个函数在任务改变调度类或改变任务组时被调用。 + + - task_tick(...) + + 这个函数最常被时间滴答函数调用，它可能导致进程切换。这驱动了运行时抢占。 + + + + +7. CFS的组调度扩展 +================== + +通常，调度器操作粒度为任务，努力为每个任务提供公平的CPU时间。有时可能希望将任务编组， +并为每个组提供公平的CPU时间。举例来说，可能首先希望为系统中的每个用户提供公平的CPU +时间，接下来才是某个用户的每个任务。 + +CONFIG_CGROUP_SCHED 力求实现它。它将任务编组，并为这些组公平地分配CPU时间。 + +CONFIG_RT_GROUP_SCHED 允许将实时（也就是说，SCHED_FIFO和SCHED_RR）任务编组。 + +CONFIG_FAIR_GROUP_SCHED 允许将CFS（也就是说，SCHED_NORMAL和SCHED_BATCH）任务编组。 + + 这些编译选项要求CONFIG_CGROUPS被定义，然后管理员能使用cgroup伪文件系统任意创建任务组。 + 关于该文件系统的更多信息，参见Documentation/admin-guide/cgroup-v1/cgroups.rst + +当CONFIG_FAIR_GROUP_SCHED被定义后，通过伪文件系统，每个组被创建一个“cpu.shares”文件。 +参见下面的例子来创建任务组，并通过“cgroup”伪文件系统修改它们的CPU份额:: + + # mount -t tmpfs cgroup_root /sys/fs/cgroup + # mkdir /sys/fs/cgroup/cpu + # mount -t cgroup -ocpu none /sys/fs/cgroup/cpu + # cd /sys/fs/cgroup/cpu + + # mkdir multimedia # 创建 "multimedia" 任务组 + # mkdir browser # 创建 "browser" 任务组 + + # #配置multimedia组，令其获得browser组两倍CPU带宽 + + # echo 2048 > multimedia/cpu.shares + # echo 1024 > browser/cpu.shares + + # firefox & # 启动firefox并把它移到 "browser" 组 + # echo <firefox_pid> > browser/tasks + + # #启动gmplayer（或者你最喜欢的电影播放器） + # echo <movie_player_pid> > multimedia/tasks diff --git a/Documentation/translations/zh_CN/scheduler/sched-domains.rst b/Documentation/translations/zh_CN/scheduler/sched-domains.rst new file mode 100644 index 000000000000..e814d4c01141 --- /dev/null +++ b/Documentation/translations/zh_CN/scheduler/sched-domains.rst @@ -0,0 +1,72 @@ +.. SPDX-License-Identifier: GPL-2.0 +.. include:: ../disclaimer-zh_CN.rst + +:Original: Documentation/scheduler/sched-domains.rst + +:翻译: + + 唐艺舟 Tang Yizhou <tangyeechou@gmail.com> + +:校译: + + 司延腾 Yanteng Si <siyanteng@loongson.cn> + +====== +调度域 +====== + +每个CPU有一个“基”调度域（struct sched_domain）。调度域层次结构从基调度域构建而来，可 +通过->parent指针自下而上遍历。->parent必须以NULL结尾，调度域结构体必须是per-CPU的， +因为它们无锁更新。 + +每个调度域管辖数个CPU（存储在->span字段中）。一个调度域的span必须是它的子调度域span的 +超集（如有需求出现，这个限制可以放宽）。CPU i的基调度域必须至少管辖CPU i。每个CPU的 +顶层调度域通常将会管辖系统中的全部CPU，尽管严格来说这不是必须的，假如是这样，会导致某些 +CPU出现永远不会被指定任务运行的情况，直到允许的CPU掩码被显式设定。调度域的span字段意味 +着“在这些CPU中做进程负载均衡”。 + +每个调度域必须具有一个或多个CPU调度组（struct sched_group），它们以单向循环链表的形式 +组织，存储在->groups指针中。这些组的CPU掩码的并集必须和调度域span字段一致。->groups +指针指向的这些组包含的CPU，必须被调度域管辖。组包含的是只读数据，被创建之后，可能被多个 +CPU共享。任意两个组的CPU掩码的交集不一定为空，如果是这种情况，对应调度域的SD_OVERLAP +标志位被设置，它管辖的调度组可能不能在多个CPU中共享。 + +调度域中的负载均衡发生在调度组中。也就是说，每个组被视为一个实体。组的负载被定义为它 +管辖的每个CPU的负载之和。仅当组的负载不均衡后，任务才在组之间发生迁移。 + +在kernel/sched/core.c中，trigger_load_balance()在每个CPU上通过scheduler_tick() +周期执行。在当前运行队列下一个定期调度再平衡事件到达后，它引发一个软中断。负载均衡真正 +的工作由run_rebalance_domains()->rebalance_domains()完成，在软中断上下文中执行 +（SCHED_SOFTIRQ）。 + +后一个函数有两个入参：当前CPU的运行队列、它在scheduler_tick()调用时是否空闲。函数会从 +当前CPU所在的基调度域开始迭代执行，并沿着parent指针链向上进入更高层级的调度域。在迭代 +过程中，函数会检查当前调度域是否已经耗尽了再平衡的时间间隔，如果是，它在该调度域运行 +load_balance()。接下来它检查父调度域（如果存在），再后来父调度域的父调度域，以此类推。 + +起初，load_balance()查找当前调度域中最繁忙的调度组。如果成功，在该调度组管辖的全部CPU +的运行队列中找出最繁忙的运行队列。如能找到，对当前的CPU运行队列和新找到的最繁忙运行 +队列均加锁，并把任务从最繁忙队列中迁移到当前CPU上。被迁移的任务数量等于在先前迭代执行 +中计算出的该调度域的调度组的不均衡值。 + +实现调度域 +========== + +基调度域会管辖CPU层次结构中的第一层。对于超线程（SMT）而言，基调度域将会管辖同一个物理 +CPU的全部虚拟CPU，每个虚拟CPU对应一个调度组。 + +在SMP中，基调度域的父调度域将会管辖同一个结点中的全部物理CPU，每个调度组对应一个物理CPU。 +接下来，如果是非统一内存访问（NUMA）系统，SMP调度域的父调度域将管辖整个机器，一个结点的 +CPU掩码对应一个调度组。亦或，你可以使用多级NUMA；举例来说Opteron处理器，可能仅用一个 +调度域来覆盖它的一个NUMA层级。 + +实现者需要阅读include/linux/sched/sd_flags.h的注释：读SD_*来了解具体情况以及调度域的 +SD标志位调节了哪些东西。 + +体系结构可以把指定的拓扑层级的通用调度域构建器和默认的SD标志位覆盖掉，方法是创建一个 +sched_domain_topology_level数组，并以该数组作为入参调用set_sched_topology()。 + +调度域调试基础设施可以通过CONFIG_SCHED_DEBUG开启，并在开机启动命令行中增加 +“sched_verbose”。如果你忘记调整开机启动命令行了，也可以打开 +/sys/kernel/debug/sched/verbose开关。这将开启调度域错误检查的解析，它应该能捕获（上文 +描述过的）绝大多数错误，同时以可视化格式打印调度域的结构。 diff --git a/Documentation/translations/zh_TW/process/submitting-patches.rst b/Documentation/translations/zh_TW/process/submitting-patches.rst index 37eccf9e2746..c4fd48f5bd8b 100644 --- a/Documentation/translations/zh_TW/process/submitting-patches.rst +++ b/Documentation/translations/zh_TW/process/submitting-patches.rst @@ -257,30 +257,6 @@ Linus Torvalds 是決定改動能否進入 Linux 內核的最終裁決者。他 手冊頁補丁，或至少發送更改通知，以便一些信息進入手冊頁。還應將用戶空間API 更改複製到 linux-api@vger.kernel.org。 -對於小的補丁，你也許會CC到搜集瑣碎補丁的郵件列表(Trivial Patch Monkey) -trivial@kernel.org，那裡專門收集瑣碎的補丁。下面這樣的補丁會被看作「瑣碎的」 -補丁： - - - 文檔的拼寫修正。 - - 修正會影響到 grep(1) 的拼寫。 - - 警告信息修正(頻繁的列印無用的警告是不好的。) - - 編譯錯誤修正（代碼邏輯的確是對的，只是編譯有問題。） - - 運行時修正（只要真的修正了錯誤。） - - 移除使用了被廢棄的函數/宏的代碼(例如 check_region。) - - 聯繫方式和文檔修正。 - - 用可移植的代碼替換不可移植的代碼（即使在體系結構相關的代碼中，既然有 - - 人拷貝，只要它是瑣碎的） - - 任何文件的作者/維護者對該文件的改動（例如 patch monkey 在重傳模式下） - -(譯註，關於「瑣碎補丁」的一些說明：因爲原文的這一部分寫得比較簡單，所以不得不 -違例寫一下譯註。"trivial"這個英文單詞的本意是「瑣碎的，不重要的。」但是在這裡 -有稍微有一些變化，例如對一些明顯的NULL指針的修正，屬於運行時修正，會被歸類 -到瑣碎補丁里。雖然NULL指針的修正很重要，但是這樣的修正往往很小而且很容易得到 -檢驗，所以也被歸入瑣碎補丁。瑣碎補丁更精確的歸類應該是 -「simple, localized & easy to verify」，也就是說簡單的，局部的和易於檢驗的。 -trivial@kernel.org郵件列表的目的是針對這樣的補丁，爲提交者提供一個中心，來 -降低提交的門檻。) - 6) 沒有 MIME 編碼，沒有連結，沒有壓縮，沒有附件，只有純文本 ----------------------------------------------------------- diff --git a/Documentation/userspace-api/media/cec/cec-ioc-receive.rst b/Documentation/userspace-api/media/cec/cec-ioc-receive.rst index bd7f7e7235cb..364938ad34df 100644 --- a/Documentation/userspace-api/media/cec/cec-ioc-receive.rst +++ b/Documentation/userspace-api/media/cec/cec-ioc-receive.rst @@ -48,9 +48,12 @@ it will return -1 and set errno to the ``ETIMEDOUT`` error code. A received message can be: 1. a message received from another CEC device (the ``sequence`` field will - be 0). -2. the result of an earlier non-blocking transmit (the ``sequence`` field will - be non-zero). + be 0, ``tx_status`` will be 0 and ``rx_status`` will be non-zero). +2. the transmit result of an earlier non-blocking transmit (the ``sequence`` + field will be non-zero, ``tx_status`` will be non-zero and ``rx_status`` + will be 0). +3. the reply to an earlier non-blocking transmit (the ``sequence`` field will + be non-zero, ``tx_status`` will be 0 and ``rx_status`` will be non-zero). To send a CEC message the application has to fill in the struct :c:type:`cec_msg` and pass it to :ref:`ioctl CEC_TRANSMIT <CEC_TRANSMIT>`. @@ -64,12 +67,11 @@ idea to fully fill up the transmit queue. If the file descriptor is in non-blocking mode then the transmit will return 0 and the result of the transmit will be available via -:ref:`ioctl CEC_RECEIVE <CEC_RECEIVE>` once the transmit has finished -(including waiting for a reply, if requested). - -The ``sequence`` field is filled in for every transmit and this can be -checked against the received messages to find the corresponding transmit -result. +:ref:`ioctl CEC_RECEIVE <CEC_RECEIVE>` once the transmit has finished. +If a non-blocking transmit also specified waiting for a reply, then +the reply will arrive in a later message. The ``sequence`` field can +be used to associate both transmit results and replies with the original +transmit. Normally calling :ref:`ioctl CEC_TRANSMIT <CEC_TRANSMIT>` when the physical address is invalid (due to e.g. a disconnect) will return ``ENONET``. @@ -123,18 +125,17 @@ View On' messages from initiator 0xf ('Unregistered') to destination 0 ('TV'). - ``sequence`` - A non-zero sequence number is automatically assigned by the CEC framework for all transmitted messages. It is used by the CEC framework when it queues - the transmit result (when transmit was called in non-blocking mode). This - allows the application to associate the received message with the original - transmit. + the transmit result for a non-blocking transmit. This allows the application + to associate the received message with the original transmit. + + In addition, if a non-blocking transmit will wait for a reply (ii.e. ``timeout`` + was not 0), then the ``sequence`` field of the reply will be set to the sequence + value of the original transmit. This allows the application to associate the + received message with the original transmit. * - __u32 - ``flags`` - Flags. See :ref:`cec-msg-flags` for a list of available flags. * - __u8 - - ``tx_status`` - - The status bits of the transmitted message. See - :ref:`cec-tx-status` for the possible status values. It is 0 if - this message was received, not transmitted. - * - __u8 - ``msg[16]`` - The message payload. For :ref:`ioctl CEC_TRANSMIT <CEC_TRANSMIT>` this is filled in by the application. The driver will fill this in for :ref:`ioctl CEC_RECEIVE <CEC_RECEIVE>`. @@ -162,15 +163,17 @@ View On' messages from initiator 0xf ('Unregistered') to destination 0 ('TV'). * - __u8 - ``rx_status`` - The status bits of the received message. See - :ref:`cec-rx-status` for the possible status values. It is 0 if - this message was transmitted, not received, unless this is the - reply to a transmitted message. In that case both ``rx_status`` - and ``tx_status`` are set. + :ref:`cec-rx-status` for the possible status values. * - __u8 - ``tx_status`` - The status bits of the transmitted message. See - :ref:`cec-tx-status` for the possible status values. It is 0 if - this message was received, not transmitted. + :ref:`cec-tx-status` for the possible status values. + When calling :ref:`ioctl CEC_TRANSMIT <CEC_TRANSMIT>` in non-blocking mode, + this field will be 0 if the transmit started, or non-0 if the transmit + result is known immediately. The latter would be the case when attempting + to transmit a Poll message to yourself. That results in a + :ref:`CEC_TX_STATUS_NACK <CEC-TX-STATUS-NACK>` without ever actually + transmitting the Poll message. * - __u8 - ``tx_arb_lost_cnt`` - A counter of the number of transmit attempts that resulted in the diff --git a/Documentation/userspace-api/media/lirc.h.rst.exceptions b/Documentation/userspace-api/media/lirc.h.rst.exceptions index e74b73cd0e9e..ec86e82d026d 100644 --- a/Documentation/userspace-api/media/lirc.h.rst.exceptions +++ b/Documentation/userspace-api/media/lirc.h.rst.exceptions @@ -33,6 +33,7 @@ ignore define LIRC_CAN_SET_REC_DUTY_CYCLE # Obsolete ioctls ignore ioctl LIRC_GET_LENGTH +ignore ioctl LIRC_SET_REC_TIMEOUT_REPORTS # rc protocols @@ -73,6 +74,7 @@ ignore define PULSE_MASK ignore define LIRC_MODE2_SPACE ignore define LIRC_MODE2_PULSE +ignore define LIRC_MODE2_TIMEOUT ignore define LIRC_VALUE_MASK ignore define LIRC_MODE2_MASK diff --git a/Documentation/userspace-api/media/rc/lirc-dev-intro.rst b/Documentation/userspace-api/media/rc/lirc-dev-intro.rst index c88973732282..9a5e5f0aae11 100644 --- a/Documentation/userspace-api/media/rc/lirc-dev-intro.rst +++ b/Documentation/userspace-api/media/rc/lirc-dev-intro.rst @@ -117,11 +117,9 @@ on the following table. ``LIRC_MODE2_TIMEOUT`` - If timeout reports are enabled with - :ref:`lirc_set_rec_timeout_reports`, when the timeout set with - :ref:`lirc_set_rec_timeout` expires due to no IR being detected, - this packet will be sent, with the number of microseconds with - no IR. + When the timeout set with :ref:`lirc_set_rec_timeout` expires due + to no IR being detected, this packet will be sent, with the number + of microseconds with no IR. .. _lirc-mode-pulse: diff --git a/Documentation/userspace-api/media/rc/lirc-func.rst b/Documentation/userspace-api/media/rc/lirc-func.rst index 793f295d3ac9..5c84888f1eca 100644 --- a/Documentation/userspace-api/media/rc/lirc-func.rst +++ b/Documentation/userspace-api/media/rc/lirc-func.rst @@ -22,6 +22,5 @@ LIRC Function Reference lirc-set-rec-carrier-range lirc-set-send-carrier lirc-set-transmitter-mask - lirc-set-rec-timeout-reports lirc-set-measure-carrier-mode lirc-set-wideband-receiver diff --git a/Documentation/userspace-api/media/rc/lirc-set-rec-timeout-reports.rst b/Documentation/userspace-api/media/rc/lirc-set-rec-timeout-reports.rst deleted file mode 100644 index aebe81012939..000000000000 --- a/Documentation/userspace-api/media/rc/lirc-set-rec-timeout-reports.rst +++ /dev/null @@ -1,49 +0,0 @@ -.. SPDX-License-Identifier: GPL-2.0 OR GFDL-1.1-no-invariants-or-later -.. c:namespace:: RC - -.. _lirc_set_rec_timeout_reports: - -********************************** -ioctl LIRC_SET_REC_TIMEOUT_REPORTS -********************************** - -Name -==== - -LIRC_SET_REC_TIMEOUT_REPORTS - enable or disable timeout reports for IR receive - -Synopsis -======== - -.. c:macro:: LIRC_SET_REC_TIMEOUT_REPORTS - -``int ioctl(int fd, LIRC_SET_REC_TIMEOUT_REPORTS, __u32 *enable)`` - -Arguments -========= - -``fd`` - File descriptor returned by open(). - -``enable`` - enable = 1 means enable timeout report, enable = 0 means disable timeout - reports. - -Description -=========== - -.. _lirc-mode2-timeout: - -Enable or disable timeout reports for IR receive. By default, timeout reports -should be turned off. - -.. note:: - - This ioctl is only valid for :ref:`LIRC_MODE_MODE2 <lirc-mode-mode2>`. - -Return Value -============ - -On success 0 is returned, on error -1 and the ``errno`` variable is set -appropriately. The generic error codes are described at the -:ref:`Generic Error Codes <gen-errors>` chapter. diff --git a/Documentation/userspace-api/media/v4l/biblio.rst b/Documentation/userspace-api/media/v4l/biblio.rst index 7b8e6738ff9e..9cd18c153d19 100644 --- a/Documentation/userspace-api/media/v4l/biblio.rst +++ b/Documentation/userspace-api/media/v4l/biblio.rst @@ -417,3 +417,13 @@ VP8 :title: RFC 6386: "VP8 Data Format and Decoding Guide" :author: J. Bankoski et al. + +.. _vp9: + +VP9 +=== + + +:title: VP9 Bitstream & Decoding Process Specification + +:author: Adrian Grange (Google), Peter de Rivaz (Argon Design), Jonathan Hunt (Argon Design) diff --git a/Documentation/userspace-api/media/v4l/capture.c.rst b/Documentation/userspace-api/media/v4l/capture.c.rst index ccbd52c3897f..eef6772967a1 100644 --- a/Documentation/userspace-api/media/v4l/capture.c.rst +++ b/Documentation/userspace-api/media/v4l/capture.c.rst @@ -56,7 +56,7 @@ file: media/v4l/capture.c static void errno_exit(const char *s) { - fprintf(stderr, "%s error %d, %s\\n", s, errno, strerror(errno)); + fprintf(stderr, "%s error %d, %s\n", s, errno, strerror(errno)); exit(EXIT_FAILURE); } @@ -201,7 +201,7 @@ file: media/v4l/capture.c } if (0 == r) { - fprintf(stderr, "select timeout\\n"); + fprintf(stderr, "select timeout\n"); exit(EXIT_FAILURE); } @@ -307,7 +307,7 @@ file: media/v4l/capture.c buffers = calloc(1, sizeof(*buffers)); if (!buffers) { - fprintf(stderr, "Out of memory\\n"); + fprintf(stderr, "Out of memory\n"); exit(EXIT_FAILURE); } @@ -315,7 +315,7 @@ file: media/v4l/capture.c buffers[0].start = malloc(buffer_size); if (!buffers[0].start) { - fprintf(stderr, "Out of memory\\n"); + fprintf(stderr, "Out of memory\n"); exit(EXIT_FAILURE); } } @@ -341,7 +341,7 @@ file: media/v4l/capture.c } if (req.count < 2) { - fprintf(stderr, "Insufficient buffer memory on %s\\n", + fprintf(stderr, "Insufficient buffer memory on %s\n", dev_name); exit(EXIT_FAILURE); } @@ -349,7 +349,7 @@ file: media/v4l/capture.c buffers = calloc(req.count, sizeof(*buffers)); if (!buffers) { - fprintf(stderr, "Out of memory\\n"); + fprintf(stderr, "Out of memory\n"); exit(EXIT_FAILURE); } @@ -401,7 +401,7 @@ file: media/v4l/capture.c buffers = calloc(4, sizeof(*buffers)); if (!buffers) { - fprintf(stderr, "Out of memory\\n"); + fprintf(stderr, "Out of memory\n"); exit(EXIT_FAILURE); } @@ -410,7 +410,7 @@ file: media/v4l/capture.c buffers[n_buffers].start = malloc(buffer_size); if (!buffers[n_buffers].start) { - fprintf(stderr, "Out of memory\\n"); + fprintf(stderr, "Out of memory\n"); exit(EXIT_FAILURE); } } @@ -426,7 +426,7 @@ file: media/v4l/capture.c if (-1 == xioctl(fd, VIDIOC_QUERYCAP, &cap)) { if (EINVAL == errno) { - fprintf(stderr, "%s is no V4L2 device\\n", + fprintf(stderr, "%s is no V4L2 device\n", dev_name); exit(EXIT_FAILURE); } else { @@ -435,7 +435,7 @@ file: media/v4l/capture.c } if (!(cap.capabilities & V4L2_CAP_VIDEO_CAPTURE)) { - fprintf(stderr, "%s is no video capture device\\n", + fprintf(stderr, "%s is no video capture device\n", dev_name); exit(EXIT_FAILURE); } @@ -443,7 +443,7 @@ file: media/v4l/capture.c switch (io) { case IO_METHOD_READ: if (!(cap.capabilities & V4L2_CAP_READWRITE)) { - fprintf(stderr, "%s does not support read i/o\\n", + fprintf(stderr, "%s does not support read i/o\n", dev_name); exit(EXIT_FAILURE); } @@ -452,7 +452,7 @@ file: media/v4l/capture.c case IO_METHOD_MMAP: case IO_METHOD_USERPTR: if (!(cap.capabilities & V4L2_CAP_STREAMING)) { - fprintf(stderr, "%s does not support streaming i/o\\n", + fprintf(stderr, "%s does not support streaming i/o\n", dev_name); exit(EXIT_FAILURE); } @@ -541,7 +541,7 @@ file: media/v4l/capture.c struct stat st; if (-1 == stat(dev_name, &st)) { - fprintf(stderr, "Cannot identify '%s': %d, %s\\n", + fprintf(stderr, "Cannot identify '%s': %d, %s\n", dev_name, errno, strerror(errno)); exit(EXIT_FAILURE); } @@ -554,7 +554,7 @@ file: media/v4l/capture.c fd = open(dev_name, O_RDWR /* required */ | O_NONBLOCK, 0); if (-1 == fd) { - fprintf(stderr, "Cannot open '%s': %d, %s\\n", + fprintf(stderr, "Cannot open '%s': %d, %s\n", dev_name, errno, strerror(errno)); exit(EXIT_FAILURE); } @@ -563,17 +563,17 @@ file: media/v4l/capture.c static void usage(FILE *fp, int argc, char **argv) { fprintf(fp, - "Usage: %s [options]\\n\\n" - "Version 1.3\\n" - "Options:\\n" - "-d | --device name Video device name [%s]n" - "-h | --help Print this messagen" - "-m | --mmap Use memory mapped buffers [default]n" - "-r | --read Use read() callsn" - "-u | --userp Use application allocated buffersn" - "-o | --output Outputs stream to stdoutn" - "-f | --format Force format to 640x480 YUYVn" - "-c | --count Number of frames to grab [%i]n" + "Usage: %s [options]\n\n" + "Version 1.3\n" + "Options:\n" + "-d | --device name Video device name [%s]\n" + "-h | --help Print this message\n" + "-m | --mmap Use memory mapped buffers [default]\n" + "-r | --read Use read() calls\n" + "-u | --userp Use application allocated buffers\n" + "-o | --output Outputs stream to stdout\n" + "-f | --format Force format to 640x480 YUYV\n" + "-c | --count Number of frames to grab [%i]\n" "", argv[0], dev_name, frame_count); } @@ -659,6 +659,6 @@ file: media/v4l/capture.c stop_capturing(); uninit_device(); close_device(); - fprintf(stderr, "\\n"); + fprintf(stderr, "\n"); return 0; } diff --git a/Documentation/userspace-api/media/v4l/control.rst b/Documentation/userspace-api/media/v4l/control.rst index f8d0b923da20..3eec65174260 100644 --- a/Documentation/userspace-api/media/v4l/control.rst +++ b/Documentation/userspace-api/media/v4l/control.rst @@ -242,8 +242,17 @@ Control IDs * - ``V4L2_COLORFX_SET_CBCR`` - The Cb and Cr chroma components are replaced by fixed coefficients determined by ``V4L2_CID_COLORFX_CBCR`` control. + * - ``V4L2_COLORFX_SET_RGB`` + - The RGB components are replaced by the fixed RGB components determined + by ``V4L2_CID_COLORFX_RGB`` control. +``V4L2_CID_COLORFX_RGB`` ``(integer)`` + Determines the Red, Green, and Blue coefficients for + ``V4L2_COLORFX_SET_RGB`` color effect. + Bits [7:0] of the supplied 32 bit value are interpreted as Blue component, + bits [15:8] as Green component, bits [23:16] as Red component, and + bits [31:24] must be zero. ``V4L2_CID_COLORFX_CBCR`` ``(integer)`` Determines the Cb and Cr coefficients for ``V4L2_COLORFX_SET_CBCR`` diff --git a/Documentation/userspace-api/media/v4l/dev-decoder.rst b/Documentation/userspace-api/media/v4l/dev-decoder.rst index 5b9b83feeceb..3cf2b496f2d0 100644 --- a/Documentation/userspace-api/media/v4l/dev-decoder.rst +++ b/Documentation/userspace-api/media/v4l/dev-decoder.rst @@ -752,6 +752,23 @@ available to dequeue. Specifically: buffers are out-of-order compared to the ``OUTPUT`` buffers): ``CAPTURE`` timestamps will not retain the order of ``OUTPUT`` timestamps. +.. note:: + + The backing memory of ``CAPTURE`` buffers that are used as reference frames + by the stream may be read by the hardware even after they are dequeued. + Consequently, the client should avoid writing into this memory while the + ``CAPTURE`` queue is streaming. Failure to observe this may result in + corruption of decoded frames. + + Similarly, when using a memory type other than ``V4L2_MEMORY_MMAP``, the + client should make sure that each ``CAPTURE`` buffer is always queued with + the same backing memory for as long as the ``CAPTURE`` queue is streaming. + The reason for this is that V4L2 buffer indices can be used by drivers to + identify frames. Thus, if the backing memory of a reference frame is + submitted under a different buffer ID, the driver may misidentify it and + decode a new frame into it while it is still in use, resulting in corruption + of the following frames. + During the decoding, the decoder may initiate one of the special sequences, as listed below. The sequences will result in the decoder returning all the ``CAPTURE`` buffers that originated from all the ``OUTPUT`` buffers processed diff --git a/Documentation/userspace-api/media/v4l/ext-ctrls-codec-stateless.rst b/Documentation/userspace-api/media/v4l/ext-ctrls-codec-stateless.rst index 72f5e85b4f34..cc080c4257d0 100644 --- a/Documentation/userspace-api/media/v4l/ext-ctrls-codec-stateless.rst +++ b/Documentation/userspace-api/media/v4l/ext-ctrls-codec-stateless.rst @@ -1458,3 +1458,576 @@ FWHT Flags .. raw:: latex \normalsize + +.. _v4l2-codec-stateless-vp9: + +``V4L2_CID_STATELESS_VP9_COMPRESSED_HDR (struct)`` + Stores VP9 probabilities updates as parsed from the current compressed frame + header. A value of zero in an array element means no update of the relevant + probability. Motion vector-related updates contain a new value or zero. All + other updates contain values translated with inv_map_table[] (see 6.3.5 in + :ref:`vp9`). + +.. c:type:: v4l2_ctrl_vp9_compressed_hdr + +.. tabularcolumns:: |p{1cm}|p{4.8cm}|p{11.4cm}| + +.. cssclass:: longtable + +.. flat-table:: struct v4l2_ctrl_vp9_compressed_hdr + :header-rows: 0 + :stub-columns: 0 + :widths: 1 1 2 + + * - __u8 + - ``tx_mode`` + - Specifies the TX mode. See :ref:`TX Mode <vp9_tx_mode>` for more details. + * - __u8 + - ``tx8[2][1]`` + - TX 8x8 probabilities delta. + * - __u8 + - ``tx16[2][2]`` + - TX 16x16 probabilities delta. + * - __u8 + - ``tx32[2][3]`` + - TX 32x32 probabilities delta. + * - __u8 + - ``coef[4][2][2][6][6][3]`` + - Coefficient probabilities delta. + * - __u8 + - ``skip[3]`` + - Skip probabilities delta. + * - __u8 + - ``inter_mode[7][3]`` + - Inter prediction mode probabilities delta. + * - __u8 + - ``interp_filter[4][2]`` + - Interpolation filter probabilities delta. + * - __u8 + - ``is_inter[4]`` + - Is inter-block probabilities delta. + * - __u8 + - ``comp_mode[5]`` + - Compound prediction mode probabilities delta. + * - __u8 + - ``single_ref[5][2]`` + - Single reference probabilities delta. + * - __u8 + - ``comp_ref[5]`` + - Compound reference probabilities delta. + * - __u8 + - ``y_mode[4][9]`` + - Y prediction mode probabilities delta. + * - __u8 + - ``uv_mode[10][9]`` + - UV prediction mode probabilities delta. + * - __u8 + - ``partition[16][3]`` + - Partition probabilities delta. + * - __u8 + - ``mv.joint[3]`` + - Motion vector joint probabilities delta. + * - __u8 + - ``mv.sign[2]`` + - Motion vector sign probabilities delta. + * - __u8 + - ``mv.classes[2][10]`` + - Motion vector class probabilities delta. + * - __u8 + - ``mv.class0_bit[2]`` + - Motion vector class0 bit probabilities delta. + * - __u8 + - ``mv.bits[2][10]`` + - Motion vector bits probabilities delta. + * - __u8 + - ``mv.class0_fr[2][2][3]`` + - Motion vector class0 fractional bit probabilities delta. + * - __u8 + - ``mv.fr[2][3]`` + - Motion vector fractional bit probabilities delta. + * - __u8 + - ``mv.class0_hp[2]`` + - Motion vector class0 high precision fractional bit probabilities delta. + * - __u8 + - ``mv.hp[2]`` + - Motion vector high precision fractional bit probabilities delta. + +.. _vp9_tx_mode: + +``TX Mode`` + +.. tabularcolumns:: |p{6.5cm}|p{0.5cm}|p{10.3cm}| + +.. flat-table:: + :header-rows: 0 + :stub-columns: 0 + :widths: 1 1 2 + + * - ``V4L2_VP9_TX_MODE_ONLY_4X4`` + - 0 + - Transform size is 4x4. + * - ``V4L2_VP9_TX_MODE_ALLOW_8X8`` + - 1 + - Transform size can be up to 8x8. + * - ``V4L2_VP9_TX_MODE_ALLOW_16X16`` + - 2 + - Transform size can be up to 16x16. + * - ``V4L2_VP9_TX_MODE_ALLOW_32X32`` + - 3 + - transform size can be up to 32x32. + * - ``V4L2_VP9_TX_MODE_SELECT`` + - 4 + - Bitstream contains the transform size for each block. + +See section '7.3.1 Tx mode semantics' of the :ref:`vp9` specification for more details. + +``V4L2_CID_STATELESS_VP9_FRAME (struct)`` + Specifies the frame parameters for the associated VP9 frame decode request. + This includes the necessary parameters for configuring a stateless hardware + decoding pipeline for VP9. The bitstream parameters are defined according + to :ref:`vp9`. + +.. c:type:: v4l2_ctrl_vp9_frame + +.. raw:: latex + + \small + +.. tabularcolumns:: |p{4.7cm}|p{5.5cm}|p{7.1cm}| + +.. cssclass:: longtable + +.. flat-table:: struct v4l2_ctrl_vp9_frame + :header-rows: 0 + :stub-columns: 0 + :widths: 1 1 2 + + * - struct :c:type:`v4l2_vp9_loop_filter` + - ``lf`` + - Loop filter parameters. See struct :c:type:`v4l2_vp9_loop_filter` for more details. + * - struct :c:type:`v4l2_vp9_quantization` + - ``quant`` + - Quantization parameters. See :c:type:`v4l2_vp9_quantization` for more details. + * - struct :c:type:`v4l2_vp9_segmentation` + - ``seg`` + - Segmentation parameters. See :c:type:`v4l2_vp9_segmentation` for more details. + * - __u32 + - ``flags`` + - Combination of V4L2_VP9_FRAME_FLAG_* flags. See :ref:`Frame Flags<vp9_frame_flags>`. + * - __u16 + - ``compressed_header_size`` + - Compressed header size in bytes. + * - __u16 + - ``uncompressed_header_size`` + - Uncompressed header size in bytes. + * - __u16 + - ``frame_width_minus_1`` + - Add 1 to get the frame width expressed in pixels. See section 7.2.3 in :ref:`vp9`. + * - __u16 + - ``frame_height_minus_1`` + - Add 1 to get the frame height expressed in pixels. See section 7.2.3 in :ref:`vp9`. + * - __u16 + - ``render_width_minus_1`` + - Add 1 to get the expected render width expressed in pixels. This is + not used during the decoding process but might be used by HW scalers to + prepare a frame that's ready for scanout. See section 7.2.4 in :ref:`vp9`. + * - __u16 + - render_height_minus_1 + - Add 1 to get the expected render height expressed in pixels. This is + not used during the decoding process but might be used by HW scalers to + prepare a frame that's ready for scanout. See section 7.2.4 in :ref:`vp9`. + * - __u64 + - ``last_frame_ts`` + - "last" reference buffer timestamp. + The timestamp refers to the ``timestamp`` field in + struct :c:type:`v4l2_buffer`. Use the :c:func:`v4l2_timeval_to_ns()` + function to convert the struct :c:type:`timeval` in struct + :c:type:`v4l2_buffer` to a __u64. + * - __u64 + - ``golden_frame_ts`` + - "golden" reference buffer timestamp. + The timestamp refers to the ``timestamp`` field in + struct :c:type:`v4l2_buffer`. Use the :c:func:`v4l2_timeval_to_ns()` + function to convert the struct :c:type:`timeval` in struct + :c:type:`v4l2_buffer` to a __u64. + * - __u64 + - ``alt_frame_ts`` + - "alt" reference buffer timestamp. + The timestamp refers to the ``timestamp`` field in + struct :c:type:`v4l2_buffer`. Use the :c:func:`v4l2_timeval_to_ns()` + function to convert the struct :c:type:`timeval` in struct + :c:type:`v4l2_buffer` to a __u64. + * - __u8 + - ``ref_frame_sign_bias`` + - a bitfield specifying whether the sign bias is set for a given + reference frame. See :ref:`Reference Frame Sign Bias<vp9_ref_frame_sign_bias>` + for more details. + * - __u8 + - ``reset_frame_context`` + - specifies whether the frame context should be reset to default values. See + :ref:`Reset Frame Context<vp9_reset_frame_context>` for more details. + * - __u8 + - ``frame_context_idx`` + - Frame context that should be used/updated. + * - __u8 + - ``profile`` + - VP9 profile. Can be 0, 1, 2 or 3. + * - __u8 + - ``bit_depth`` + - Component depth in bits. Can be 8, 10 or 12. Note that not all profiles + support 10 and/or 12 bits depths. + * - __u8 + - ``interpolation_filter`` + - Specifies the filter selection used for performing inter prediction. See + :ref:`Interpolation Filter<vp9_interpolation_filter>` for more details. + * - __u8 + - ``tile_cols_log2`` + - Specifies the base 2 logarithm of the width of each tile (where the + width is measured in units of 8x8 blocks). Shall be less than or equal + to 6. + * - __u8 + - ``tile_rows_log2`` + - Specifies the base 2 logarithm of the height of each tile (where the + height is measured in units of 8x8 blocks). + * - __u8 + - ``reference_mode`` + - Specifies the type of inter prediction to be used. See + :ref:`Reference Mode<vp9_reference_mode>` for more details. + * - __u8 + - ``reserved[7]`` + - Applications and drivers must set this to zero. + +.. raw:: latex + + \normalsize + +.. _vp9_frame_flags: + +``Frame Flags`` + +.. tabularcolumns:: |p{10.0cm}|p{1.2cm}|p{6.1cm}| + +.. flat-table:: + :header-rows: 0 + :stub-columns: 0 + :widths: 1 1 2 + + * - ``V4L2_VP9_FRAME_FLAG_KEY_FRAME`` + - 0x001 + - The frame is a key frame. + * - ``V4L2_VP9_FRAME_FLAG_SHOW_FRAME`` + - 0x002 + - The frame should be displayed. + * - ``V4L2_VP9_FRAME_FLAG_ERROR_RESILIENT`` + - 0x004 + - The decoding should be error resilient. + * - ``V4L2_VP9_FRAME_FLAG_INTRA_ONLY`` + - 0x008 + - The frame does not reference other frames. + * - ``V4L2_VP9_FRAME_FLAG_ALLOW_HIGH_PREC_MV`` + - 0x010 + - The frame can use high precision motion vectors. + * - ``V4L2_VP9_FRAME_FLAG_REFRESH_FRAME_CTX`` + - 0x020 + - Frame context should be updated after decoding. + * - ``V4L2_VP9_FRAME_FLAG_PARALLEL_DEC_MODE`` + - 0x040 + - Parallel decoding is used. + * - ``V4L2_VP9_FRAME_FLAG_X_SUBSAMPLING`` + - 0x080 + - Vertical subsampling is enabled. + * - ``V4L2_VP9_FRAME_FLAG_Y_SUBSAMPLING`` + - 0x100 + - Horizontal subsampling is enabled. + * - ``V4L2_VP9_FRAME_FLAG_COLOR_RANGE_FULL_SWING`` + - 0x200 + - The full UV range is used. + +.. _vp9_ref_frame_sign_bias: + +``Reference Frame Sign Bias`` + +.. tabularcolumns:: |p{7.0cm}|p{1.2cm}|p{9.1cm}| + +.. flat-table:: + :header-rows: 0 + :stub-columns: 0 + :widths: 1 1 2 + + * - ``V4L2_VP9_SIGN_BIAS_LAST`` + - 0x1 + - Sign bias is set for the last reference frame. + * - ``V4L2_VP9_SIGN_BIAS_GOLDEN`` + - 0x2 + - Sign bias is set for the golden reference frame. + * - ``V4L2_VP9_SIGN_BIAS_ALT`` + - 0x2 + - Sign bias is set for the alt reference frame. + +.. _vp9_reset_frame_context: + +``Reset Frame Context`` + +.. tabularcolumns:: |p{7.0cm}|p{1.2cm}|p{9.1cm}| + +.. flat-table:: + :header-rows: 0 + :stub-columns: 0 + :widths: 1 1 2 + + * - ``V4L2_VP9_RESET_FRAME_CTX_NONE`` + - 0 + - Do not reset any frame context. + * - ``V4L2_VP9_RESET_FRAME_CTX_SPEC`` + - 1 + - Reset the frame context pointed to by + :c:type:`v4l2_ctrl_vp9_frame`.frame_context_idx. + * - ``V4L2_VP9_RESET_FRAME_CTX_ALL`` + - 2 + - Reset all frame contexts. + +See section '7.2 Uncompressed header semantics' of the :ref:`vp9` specification +for more details. + +.. _vp9_interpolation_filter: + +``Interpolation Filter`` + +.. tabularcolumns:: |p{9.0cm}|p{1.2cm}|p{7.1cm}| + +.. flat-table:: + :header-rows: 0 + :stub-columns: 0 + :widths: 1 1 2 + + * - ``V4L2_VP9_INTERP_FILTER_EIGHTTAP`` + - 0 + - Eight tap filter. + * - ``V4L2_VP9_INTERP_FILTER_EIGHTTAP_SMOOTH`` + - 1 + - Eight tap smooth filter. + * - ``V4L2_VP9_INTERP_FILTER_EIGHTTAP_SHARP`` + - 2 + - Eeight tap sharp filter. + * - ``V4L2_VP9_INTERP_FILTER_BILINEAR`` + - 3 + - Bilinear filter. + * - ``V4L2_VP9_INTERP_FILTER_SWITCHABLE`` + - 4 + - Filter selection is signaled at the block level. + +See section '7.2.7 Interpolation filter semantics' of the :ref:`vp9` specification +for more details. + +.. _vp9_reference_mode: + +``Reference Mode`` + +.. tabularcolumns:: |p{9.6cm}|p{0.5cm}|p{7.2cm}| + +.. flat-table:: + :header-rows: 0 + :stub-columns: 0 + :widths: 1 1 2 + + * - ``V4L2_VP9_REFERENCE_MODE_SINGLE_REFERENCE`` + - 0 + - Indicates that all the inter blocks use only a single reference frame + to generate motion compensated prediction. + * - ``V4L2_VP9_REFERENCE_MODE_COMPOUND_REFERENCE`` + - 1 + - Requires all the inter blocks to use compound mode. Single reference + frame prediction is not allowed. + * - ``V4L2_VP9_REFERENCE_MODE_SELECT`` + - 2 + - Allows each individual inter block to select between single and + compound prediction modes. + +See section '7.3.6 Frame reference mode semantics' of the :ref:`vp9` specification for more details. + +.. c:type:: v4l2_vp9_segmentation + +Encodes the quantization parameters. See section '7.2.10 Segmentation +params syntax' of the :ref:`vp9` specification for more details. + +.. tabularcolumns:: |p{0.8cm}|p{5cm}|p{11.4cm}| + +.. cssclass:: longtable + +.. flat-table:: struct v4l2_vp9_segmentation + :header-rows: 0 + :stub-columns: 0 + :widths: 1 1 2 + + * - __u8 + - ``feature_data[8][4]`` + - Data attached to each feature. Data entry is only valid if the feature + is enabled. The array shall be indexed with segment number as the first dimension + (0..7) and one of V4L2_VP9_SEG_* as the second dimension. + See :ref:`Segment Feature IDs<vp9_segment_feature>`. + * - __u8 + - ``feature_enabled[8]`` + - Bitmask defining which features are enabled in each segment. The value for each + segment is a combination of V4L2_VP9_SEGMENT_FEATURE_ENABLED(id) values where id is + one of V4L2_VP9_SEG_*. See :ref:`Segment Feature IDs<vp9_segment_feature>`. + * - __u8 + - ``tree_probs[7]`` + - Specifies the probability values to be used when decoding a Segment-ID. + See '5.15. Segmentation map' section of :ref:`vp9` for more details. + * - __u8 + - ``pred_probs[3]`` + - Specifies the probability values to be used when decoding a + Predicted-Segment-ID. See '6.4.14. Get segment id syntax' + section of :ref:`vp9` for more details. + * - __u8 + - ``flags`` + - Combination of V4L2_VP9_SEGMENTATION_FLAG_* flags. See + :ref:`Segmentation Flags<vp9_segmentation_flags>`. + * - __u8 + - ``reserved[5]`` + - Applications and drivers must set this to zero. + +.. _vp9_segment_feature: + +``Segment feature IDs`` + +.. tabularcolumns:: |p{6.0cm}|p{1cm}|p{10.3cm}| + +.. flat-table:: + :header-rows: 0 + :stub-columns: 0 + :widths: 1 1 2 + + * - ``V4L2_VP9_SEG_LVL_ALT_Q`` + - 0 + - Quantizer segment feature. + * - ``V4L2_VP9_SEG_LVL_ALT_L`` + - 1 + - Loop filter segment feature. + * - ``V4L2_VP9_SEG_LVL_REF_FRAME`` + - 2 + - Reference frame segment feature. + * - ``V4L2_VP9_SEG_LVL_SKIP`` + - 3 + - Skip segment feature. + * - ``V4L2_VP9_SEG_LVL_MAX`` + - 4 + - Number of segment features. + +.. _vp9_segmentation_flags: + +``Segmentation Flags`` + +.. tabularcolumns:: |p{10.6cm}|p{0.8cm}|p{5.9cm}| + +.. flat-table:: + :header-rows: 0 + :stub-columns: 0 + :widths: 1 1 2 + + * - ``V4L2_VP9_SEGMENTATION_FLAG_ENABLED`` + - 0x01 + - Indicates that this frame makes use of the segmentation tool. + * - ``V4L2_VP9_SEGMENTATION_FLAG_UPDATE_MAP`` + - 0x02 + - Indicates that the segmentation map should be updated during the + decoding of this frame. + * - ``V4L2_VP9_SEGMENTATION_FLAG_TEMPORAL_UPDATE`` + - 0x04 + - Indicates that the updates to the segmentation map are coded + relative to the existing segmentation map. + * - ``V4L2_VP9_SEGMENTATION_FLAG_UPDATE_DATA`` + - 0x08 + - Indicates that new parameters are about to be specified for each + segment. + * - ``V4L2_VP9_SEGMENTATION_FLAG_ABS_OR_DELTA_UPDATE`` + - 0x10 + - Indicates that the segmentation parameters represent the actual values + to be used. + +.. c:type:: v4l2_vp9_quantization + +Encodes the quantization parameters. See section '7.2.9 Quantization params +syntax' of the VP9 specification for more details. + +.. tabularcolumns:: |p{0.8cm}|p{4cm}|p{12.4cm}| + +.. cssclass:: longtable + +.. flat-table:: struct v4l2_vp9_quantization + :header-rows: 0 + :stub-columns: 0 + :widths: 1 1 2 + + * - __u8 + - ``base_q_idx`` + - Indicates the base frame qindex. + * - __s8 + - ``delta_q_y_dc`` + - Indicates the Y DC quantizer relative to base_q_idx. + * - __s8 + - ``delta_q_uv_dc`` + - Indicates the UV DC quantizer relative to base_q_idx. + * - __s8 + - ``delta_q_uv_ac`` + - Indicates the UV AC quantizer relative to base_q_idx. + * - __u8 + - ``reserved[4]`` + - Applications and drivers must set this to zero. + +.. c:type:: v4l2_vp9_loop_filter + +This structure contains all loop filter related parameters. See sections +'7.2.8 Loop filter semantics' of the :ref:`vp9` specification for more details. + +.. tabularcolumns:: |p{0.8cm}|p{4cm}|p{12.4cm}| + +.. cssclass:: longtable + +.. flat-table:: struct v4l2_vp9_loop_filter + :header-rows: 0 + :stub-columns: 0 + :widths: 1 1 2 + + * - __s8 + - ``ref_deltas[4]`` + - Contains the adjustment needed for the filter level based on the chosen + reference frame. + * - __s8 + - ``mode_deltas[2]`` + - Contains the adjustment needed for the filter level based on the chosen + mode. + * - __u8 + - ``level`` + - Indicates the loop filter strength. + * - __u8 + - ``sharpness`` + - Indicates the sharpness level. + * - __u8 + - ``flags`` + - Combination of V4L2_VP9_LOOP_FILTER_FLAG_* flags. + See :ref:`Loop Filter Flags <vp9_loop_filter_flags>`. + * - __u8 + - ``reserved[7]`` + - Applications and drivers must set this to zero. + + +.. _vp9_loop_filter_flags: + +``Loop Filter Flags`` + +.. tabularcolumns:: |p{9.6cm}|p{0.5cm}|p{7.2cm}| + +.. flat-table:: + :header-rows: 0 + :stub-columns: 0 + :widths: 1 1 2 + + * - ``V4L2_VP9_LOOP_FILTER_FLAG_DELTA_ENABLED`` + - 0x1 + - When set, the filter level depends on the mode and reference frame used + to predict a block. + * - ``V4L2_VP9_LOOP_FILTER_FLAG_DELTA_UPDATE`` + - 0x2 + - When set, the bitstream contains additional syntax elements that + specify which mode and reference frame deltas are to be updated. diff --git a/Documentation/userspace-api/media/v4l/libv4l-introduction.rst b/Documentation/userspace-api/media/v4l/libv4l-introduction.rst index 05690f2358ce..90215313b965 100644 --- a/Documentation/userspace-api/media/v4l/libv4l-introduction.rst +++ b/Documentation/userspace-api/media/v4l/libv4l-introduction.rst @@ -26,7 +26,7 @@ found in V4L2 drivers into a few common RGB and YUY formats. It currently accepts the following V4L2 driver formats: :ref:`V4L2_PIX_FMT_BGR24 <V4L2-PIX-FMT-BGR24>`, -:ref:`V4L2_PIX_FMT_HM12 <V4L2-PIX-FMT-HM12>`, +:ref:`V4L2_PIX_FMT_NV12_16L16 <V4L2-PIX-FMT-NV12-16L16>`, :ref:`V4L2_PIX_FMT_JPEG <V4L2-PIX-FMT-JPEG>`, :ref:`V4L2_PIX_FMT_MJPEG <V4L2-PIX-FMT-MJPEG>`, :ref:`V4L2_PIX_FMT_MR97310A <V4L2-PIX-FMT-MR97310A>`, diff --git a/Documentation/userspace-api/media/v4l/pixfmt-compressed.rst b/Documentation/userspace-api/media/v4l/pixfmt-compressed.rst index 0ede39907ee2..967fc803ef94 100644 --- a/Documentation/userspace-api/media/v4l/pixfmt-compressed.rst +++ b/Documentation/userspace-api/media/v4l/pixfmt-compressed.rst @@ -172,6 +172,21 @@ Compressed Formats - VP9 compressed video frame. The encoder generates one compressed frame per buffer, and the decoder requires one compressed frame per buffer. + * .. _V4L2-PIX-FMT-VP9-FRAME: + + - ``V4L2_PIX_FMT_VP9_FRAME`` + - 'VP9F' + - VP9 parsed frame, including the frame header, as extracted from the container. + This format is adapted for stateless video decoders that implement a + VP9 pipeline with the :ref:`stateless_decoder`. + Metadata associated with the frame to decode is required to be passed + through the ``V4L2_CID_STATELESS_VP9_FRAME`` and + the ``V4L2_CID_STATELESS_VP9_COMPRESSED_HDR`` controls. + See the :ref:`associated Codec Control IDs <v4l2-codec-stateless-vp9>`. + Exactly one output and one capture buffer must be provided for use with + this pixel format. The output buffer must contain the appropriate number + of macroblocks to decode a full corresponding frame to the matching + capture buffer. * .. _V4L2-PIX-FMT-HEVC: - ``V4L2_PIX_FMT_HEVC`` diff --git a/Documentation/userspace-api/media/v4l/subdev-formats.rst b/Documentation/userspace-api/media/v4l/subdev-formats.rst index bd68588b2683..0cbc045d5df6 100644 --- a/Documentation/userspace-api/media/v4l/subdev-formats.rst +++ b/Documentation/userspace-api/media/v4l/subdev-formats.rst @@ -7833,7 +7833,7 @@ The following table lists existing HSV/HSL formats. .. raw:: latex - \normalsize + \endgroup JPEG Compressed Formats diff --git a/Documentation/userspace-api/media/v4l/v4l2grab.c.rst b/Documentation/userspace-api/media/v4l/v4l2grab.c.rst index eaa0f95048e7..b38f661da733 100644 --- a/Documentation/userspace-api/media/v4l/v4l2grab.c.rst +++ b/Documentation/userspace-api/media/v4l/v4l2grab.c.rst @@ -46,7 +46,7 @@ file: media/v4l/v4l2grab.c } while (r == -1 && ((errno == EINTR) || (errno == EAGAIN))); if (r == -1) { - fprintf(stderr, "error %d, %s\\n", errno, strerror(errno)); + fprintf(stderr, "error %d, %s\n", errno, strerror(errno)); exit(EXIT_FAILURE); } } @@ -80,11 +80,11 @@ file: media/v4l/v4l2grab.c fmt.fmt.pix.field = V4L2_FIELD_INTERLACED; xioctl(fd, VIDIOC_S_FMT, &fmt); if (fmt.fmt.pix.pixelformat != V4L2_PIX_FMT_RGB24) { - printf("Libv4l didn't accept RGB24 format. Can't proceed.\\n"); + printf("Libv4l didn't accept RGB24 format. Can't proceed.\n"); exit(EXIT_FAILURE); } if ((fmt.fmt.pix.width != 640) || (fmt.fmt.pix.height != 480)) - printf("Warning: driver is sending image at %dx%d\\n", + printf("Warning: driver is sending image at %dx%d\n", fmt.fmt.pix.width, fmt.fmt.pix.height); CLEAR(req); @@ -151,7 +151,7 @@ file: media/v4l/v4l2grab.c perror("Cannot open image"); exit(EXIT_FAILURE); } - fprintf(fout, "P6\\n%d %d 255\\n", + fprintf(fout, "P6\n%d %d 255\n", fmt.fmt.pix.width, fmt.fmt.pix.height); fwrite(buffers[buf.index].start, buf.bytesused, 1, fout); fclose(fout); diff --git a/Documentation/userspace-api/media/v4l/vidioc-g-ext-ctrls.rst b/Documentation/userspace-api/media/v4l/vidioc-g-ext-ctrls.rst index fdde0ae6d521..29971a45a2d4 100644 --- a/Documentation/userspace-api/media/v4l/vidioc-g-ext-ctrls.rst +++ b/Documentation/userspace-api/media/v4l/vidioc-g-ext-ctrls.rst @@ -233,6 +233,14 @@ still cause this situation. - ``p_mpeg2_quantisation`` - A pointer to a struct :c:type:`v4l2_ctrl_mpeg2_quantisation`. Valid if this control is of type ``V4L2_CTRL_TYPE_MPEG2_QUANTISATION``. + * - struct :c:type:`v4l2_ctrl_vp9_compressed_hdr` * + - ``p_vp9_compressed_hdr_probs`` + - A pointer to a struct :c:type:`v4l2_ctrl_vp9_compressed_hdr`. Valid if this + control is of type ``V4L2_CTRL_TYPE_VP9_COMPRESSED_HDR``. + * - struct :c:type:`v4l2_ctrl_vp9_frame` * + - ``p_vp9_frame`` + - A pointer to a struct :c:type:`v4l2_ctrl_vp9_frame`. Valid if this + control is of type ``V4L2_CTRL_TYPE_VP9_FRAME``. * - struct :c:type:`v4l2_ctrl_hdr10_cll_info` * - ``p_hdr10_cll`` - A pointer to a struct :c:type:`v4l2_ctrl_hdr10_cll_info`. Valid if this control is diff --git a/Documentation/userspace-api/media/v4l/vidioc-queryctrl.rst b/Documentation/userspace-api/media/v4l/vidioc-queryctrl.rst index 2f491c17dd5d..88f630252d98 100644 --- a/Documentation/userspace-api/media/v4l/vidioc-queryctrl.rst +++ b/Documentation/userspace-api/media/v4l/vidioc-queryctrl.rst @@ -513,6 +513,18 @@ See also the examples in :ref:`control`. - n/a - A struct :c:type:`v4l2_ctrl_hevc_decode_params`, containing HEVC decoding parameters for stateless video decoders. + * - ``V4L2_CTRL_TYPE_VP9_COMPRESSED_HDR`` + - n/a + - n/a + - n/a + - A struct :c:type:`v4l2_ctrl_vp9_compressed_hdr`, containing VP9 + probabilities updates for stateless video decoders. + * - ``V4L2_CTRL_TYPE_VP9_FRAME`` + - n/a + - n/a + - n/a + - A struct :c:type:`v4l2_ctrl_vp9_frame`, containing VP9 + frame decode parameters for stateless video decoders. .. raw:: latex diff --git a/Documentation/userspace-api/media/videodev2.h.rst.exceptions b/Documentation/userspace-api/media/videodev2.h.rst.exceptions index eb0b1cd37abd..9cbb7a0c354a 100644 --- a/Documentation/userspace-api/media/videodev2.h.rst.exceptions +++ b/Documentation/userspace-api/media/videodev2.h.rst.exceptions @@ -149,6 +149,8 @@ replace symbol V4L2_CTRL_TYPE_HEVC_SLICE_PARAMS :c:type:`v4l2_ctrl_type` replace symbol V4L2_CTRL_TYPE_AREA :c:type:`v4l2_ctrl_type` replace symbol V4L2_CTRL_TYPE_FWHT_PARAMS :c:type:`v4l2_ctrl_type` replace symbol V4L2_CTRL_TYPE_VP8_FRAME :c:type:`v4l2_ctrl_type` +replace symbol V4L2_CTRL_TYPE_VP9_COMPRESSED_HDR :c:type:`v4l2_ctrl_type` +replace symbol V4L2_CTRL_TYPE_VP9_FRAME :c:type:`v4l2_ctrl_type` replace symbol V4L2_CTRL_TYPE_HDR10_CLL_INFO :c:type:`v4l2_ctrl_type` replace symbol V4L2_CTRL_TYPE_HDR10_MASTERING_DISPLAY :c:type:`v4l2_ctrl_type` diff --git a/Documentation/virt/kvm/amd-memory-encryption.rst b/Documentation/virt/kvm/amd-memory-encryption.rst index 5c081c8c7164..1c6847fff304 100644 --- a/Documentation/virt/kvm/amd-memory-encryption.rst +++ b/Documentation/virt/kvm/amd-memory-encryption.rst @@ -85,6 +85,12 @@ guests, such as launching, running, snapshotting, migrating and decommissioning. The KVM_SEV_INIT command is used by the hypervisor to initialize the SEV platform context. In a typical workflow, this command should be the first command issued. +The firmware can be initialized either by using its own non-volatile storage or +the OS can manage the NV storage for the firmware using the module parameter +``init_ex_path``. The file specified by ``init_ex_path`` must exist. To create +a new NV storage file allocate the file with 32KB bytes of 0xFF as required by +the SEV spec. + Returns: 0 on success, -negative on error 2. KVM_SEV_LAUNCH_START diff --git a/Documentation/vm/overcommit-accounting.rst b/Documentation/vm/overcommit-accounting.rst index 0dd54bbe4afa..1addb0c374a4 100644 --- a/Documentation/vm/overcommit-accounting.rst +++ b/Documentation/vm/overcommit-accounting.rst @@ -34,7 +34,8 @@ The Linux kernel supports the following overcommit handling modes The overcommit policy is set via the sysctl ``vm.overcommit_memory``. The overcommit amount can be set via ``vm.overcommit_ratio`` (percentage) -or ``vm.overcommit_kbytes`` (absolute value). +or ``vm.overcommit_kbytes`` (absolute value). These only have an effect +when ``vm.overcommit_memory`` is set to 2. The current overcommit limit and amount committed are viewable in ``/proc/meminfo`` as CommitLimit and Committed_AS respectively. diff --git a/Documentation/x86/sgx.rst b/Documentation/x86/sgx.rst index a608f667fb95..265568a9292c 100644 --- a/Documentation/x86/sgx.rst +++ b/Documentation/x86/sgx.rst @@ -10,7 +10,7 @@ Overview Software Guard eXtensions (SGX) hardware enables for user space applications to set aside private memory regions of code and data: -* Privileged (ring-0) ENCLS functions orchestrate the construction of the. +* Privileged (ring-0) ENCLS functions orchestrate the construction of the regions. * Unprivileged (ring-3) ENCLU functions allow an application to enter and execute inside the regions. @@ -91,7 +91,7 @@ In addition to the traditional compiler and linker build process, SGX has a separate enclave “build” process. Enclaves must be built before they can be executed (entered). The first step in building an enclave is opening the **/dev/sgx_enclave** device. Since enclave memory is protected from direct -access, special privileged instructions are Then used to copy data into enclave +access, special privileged instructions are then used to copy data into enclave pages and establish enclave page permissions. .. kernel-doc:: arch/x86/kernel/cpu/sgx/ioctl.c @@ -126,13 +126,13 @@ the need to juggle signal handlers. ksgxd ===== -SGX support includes a kernel thread called *ksgxwapd*. +SGX support includes a kernel thread called *ksgxd*. EPC sanitization ---------------- ksgxd is started when SGX initializes. Enclave memory is typically ready -For use when the processor powers on or resets. However, if SGX has been in +for use when the processor powers on or resets. However, if SGX has been in use since the reset, enclave pages may be in an inconsistent state. This might occur after a crash and kexec() cycle, for instance. At boot, ksgxd reinitializes all enclave pages so that they can be allocated and re-used. @@ -147,7 +147,7 @@ Page reclaimer Similar to the core kswapd, ksgxd, is responsible for managing the overcommitment of enclave memory. If the system runs out of enclave memory, -*ksgxwapd* “swaps” enclave memory to normal memory. +*ksgxd* “swaps” enclave memory to normal memory. Launch Control ============== @@ -156,7 +156,7 @@ SGX provides a launch control mechanism. After all enclave pages have been copied, kernel executes EINIT function, which initializes the enclave. Only after this the CPU can execute inside the enclave. -ENIT function takes an RSA-3072 signature of the enclave measurement. The function +EINIT function takes an RSA-3072 signature of the enclave measurement. The function checks that the measurement is correct and signature is signed with the key hashed to the four **IA32_SGXLEPUBKEYHASH{0, 1, 2, 3}** MSRs representing the SHA256 of a public key. @@ -184,7 +184,7 @@ CPUs starting from Icelake use Total Memory Encryption (TME) in the place of MEE. TME-based SGX implementations do not have an integrity Merkle tree, which means integrity and replay-attacks are not mitigated. B, it includes additional changes to prevent cipher text from being returned and SW memory -aliases from being Created. +aliases from being created. DMA to enclave memory is blocked by range registers on both MEE and TME systems (SDM section 41.10). |
