diff options
Diffstat (limited to 'Documentation')
389 files changed, 17726 insertions, 4067 deletions
diff --git a/Documentation/ABI/testing/debugfs-cros-ec b/Documentation/ABI/testing/debugfs-cros-ec index 1fe0add99a2a..9a040c6f5e03 100644 --- a/Documentation/ABI/testing/debugfs-cros-ec +++ b/Documentation/ABI/testing/debugfs-cros-ec @@ -54,3 +54,25 @@ Description: this feature. Output will be in the format: "0x%08x\n". + +What: /sys/kernel/debug/<cros-ec-device>/suspend_timeout_ms +Date: August 2022 +KernelVersion: 6.1 +Description: + Some ECs have a feature where they will track transitions of + a hardware-controlled sleep line, such as Intel's SLP_S0 line, + in order to detect cases where a system failed to go into deep + sleep states. The suspend_timeout_ms file controls the amount of + time in milliseconds the EC will wait before declaring a sleep + timeout event and attempting to wake the system. + + Supply 0 to use the default value coded into EC firmware. Supply + 65535 (EC_HOST_SLEEP_TIMEOUT_INFINITE) to disable the EC sleep + failure detection mechanism. Values in between 0 and 65535 + indicate the number of milliseconds the EC should wait after a + sleep transition before declaring a timeout. This includes both + the duration after a sleep command was received but before the + hardware line changed, as well as the duration between when the + hardware line changed and the kernel sent an EC resume command. + + Output will be in the format: "%u\n". diff --git a/Documentation/ABI/testing/sysfs-amd-pmc b/Documentation/ABI/testing/sysfs-amd-pmc new file mode 100644 index 000000000000..c421b72844f1 --- /dev/null +++ b/Documentation/ABI/testing/sysfs-amd-pmc @@ -0,0 +1,13 @@ +What: /sys/bus/platform/drivers/amd_pmc/*/smu_fw_version +Date: October 2022 +Contact: Mario Limonciello <mario.limonciello@amd.com> +Description: Reading this file reports the version of the firmware loaded to + System Management Unit (SMU) contained in AMD CPUs and + APUs. + +What: /sys/bus/platform/drivers/amd_pmc/*/smu_program +Date: October 2022 +Contact: Mario Limonciello <mario.limonciello@amd.com> +Description: Reading this file reports the program corresponding to the SMU + firmware version. The program field is used to disambiguate two + APU/CPU models that can share the same firmware binary. diff --git a/Documentation/ABI/testing/sysfs-amd-pmf b/Documentation/ABI/testing/sysfs-amd-pmf new file mode 100644 index 000000000000..7fc0e1c2b76b --- /dev/null +++ b/Documentation/ABI/testing/sysfs-amd-pmf @@ -0,0 +1,13 @@ +What: /sys/devices/platform/*/cnqf_enable +Date: September 2022 +Contact: Shyam Sundar S K <Shyam-sundar.S-k@amd.com> +Description: Reading this file tells if the AMD Platform Management(PMF) + Cool n Quiet Framework(CnQF) feature is enabled or not. + + This feature is not enabled by default and gets only turned on + if OEM BIOS passes a "flag" to PMF ACPI function (index 11 or 12) + or in case the user writes "on". + + To turn off CnQF user can write "off" to the sysfs node. + Note: Systems that support auto mode will not have this sysfs file + available. diff --git a/Documentation/ABI/testing/sysfs-bus-bcma b/Documentation/ABI/testing/sysfs-bus-bcma index 721b4aea3020..e93d3ddca844 100644 --- a/Documentation/ABI/testing/sysfs-bus-bcma +++ b/Documentation/ABI/testing/sysfs-bus-bcma @@ -3,7 +3,7 @@ Date: May 2011 KernelVersion: 3.0 Contact: RafaÅ‚ MiÅ‚ecki <zajec5@gmail.com> Description: - Each BCMA core has it's manufacturer id. See + Each BCMA core has its manufacturer id. See include/linux/bcma/bcma.h for possible values. What: /sys/bus/bcma/devices/.../id diff --git a/Documentation/ABI/testing/sysfs-bus-fcoe b/Documentation/ABI/testing/sysfs-bus-fcoe index 8fe787cc4ab7..5a4f2091ac37 100644 --- a/Documentation/ABI/testing/sysfs-bus-fcoe +++ b/Documentation/ABI/testing/sysfs-bus-fcoe @@ -31,7 +31,7 @@ Description: 'FCoE Controller' instances on the fcoe bus. 1) Write interface name to ctlr_create 2) Configure the FCoE Controller (ctlr_X) 3) Enable the FCoE Controller to begin discovery and login. The FCoE Controller is destroyed by - writing it's name, i.e. ctlr_X to the ctlr_delete file. + writing its name, i.e. ctlr_X to the ctlr_delete file. Attributes: diff --git a/Documentation/ABI/testing/sysfs-bus-iio-proximity b/Documentation/ABI/testing/sysfs-bus-iio-proximity index 3aac6dab8775..9b9d1cc9b703 100644 --- a/Documentation/ABI/testing/sysfs-bus-iio-proximity +++ b/Documentation/ABI/testing/sysfs-bus-iio-proximity @@ -18,7 +18,7 @@ Description: on the signal from which time of flight measurements are taken. The appropriate values to take is dependent on both the - sensor and it's operating environment: + sensor and its operating environment: * as3935 (0-31 range) 18 = indoors (default) 14 = outdoors diff --git a/Documentation/ABI/testing/sysfs-class-power b/Documentation/ABI/testing/sysfs-class-power index a9ce63cfbe87..e434fc523291 100644 --- a/Documentation/ABI/testing/sysfs-class-power +++ b/Documentation/ABI/testing/sysfs-class-power @@ -364,7 +364,10 @@ Date: April 2019 Contact: linux-pm@vger.kernel.org Description: Represents a battery percentage level, above which charging will - stop. + stop. Not all hardware is capable of setting this to an arbitrary + percentage. Drivers will round written values to the nearest + supported value. Reading back the value will show the actual + threshold set by the driver. Access: Read, Write diff --git a/Documentation/ABI/testing/sysfs-devices-system-cpu b/Documentation/ABI/testing/sysfs-devices-system-cpu index 760c889b6cd1..f54867cadb0f 100644 --- a/Documentation/ABI/testing/sysfs-devices-system-cpu +++ b/Documentation/ABI/testing/sysfs-devices-system-cpu @@ -296,7 +296,7 @@ Description: Processor frequency boosting control This switch controls the boost setting for the whole system. Boosting allows the CPU and the firmware to run at a frequency - beyond it's nominal limit. + beyond its nominal limit. More details can be found in Documentation/admin-guide/pm/cpufreq.rst diff --git a/Documentation/ABI/testing/sysfs-platform-asus-wmi b/Documentation/ABI/testing/sysfs-platform-asus-wmi index 04885738cf15..a77a004a1baa 100644 --- a/Documentation/ABI/testing/sysfs-platform-asus-wmi +++ b/Documentation/ABI/testing/sysfs-platform-asus-wmi @@ -57,3 +57,44 @@ Description: * 0 - default, * 1 - overboost, * 2 - silent + +What: /sys/devices/platform/<platform>/gpu_mux_mode +Date: Aug 2022 +KernelVersion: 6.1 +Contact: "Luke Jones" <luke@ljones.dev> +Description: + Switch the GPU hardware MUX mode. Laptops with this feature can + can be toggled to boot with only the dGPU (discrete mode) or in + standard Optimus/Hybrid mode. On switch a reboot is required: + + * 0 - Discrete GPU, + * 1 - Optimus/Hybrid, + +What: /sys/devices/platform/<platform>/dgpu_disable +Date: Aug 2022 +KernelVersion: 5.17 +Contact: "Luke Jones" <luke@ljones.dev> +Description: + Disable discrete GPU: + * 0 - Enable dGPU, + * 1 - Disable dGPU + +What: /sys/devices/platform/<platform>/egpu_enable +Date: Aug 2022 +KernelVersion: 5.17 +Contact: "Luke Jones" <luke@ljones.dev> +Description: + Enable the external GPU paired with ROG X-Flow laptops. + Toggling this setting will also trigger ACPI to disable the dGPU: + + * 0 - Disable, + * 1 - Enable + +What: /sys/devices/platform/<platform>/panel_od +Date: Aug 2022 +KernelVersion: 5.17 +Contact: "Luke Jones" <luke@ljones.dev> +Description: + Enable an LCD response-time boost to reduce or remove ghosting: + * 0 - Disable, + * 1 - Enable diff --git a/Documentation/ABI/testing/sysfs-platform-chipidea-usb2 b/Documentation/ABI/testing/sysfs-platform-chipidea-usb2 index b0f4684a83fe..b9f7d924f28a 100644 --- a/Documentation/ABI/testing/sysfs-platform-chipidea-usb2 +++ b/Documentation/ABI/testing/sysfs-platform-chipidea-usb2 @@ -2,8 +2,8 @@ What: /sys/bus/platform/devices/ci_hdrc.0/role Date: Mar 2017 Contact: Peter Chen <peter.chen@nxp.com> Description: - It returns string "gadget" or "host" when read it, it indicates - current controller role. + When read, it returns string "gadget" or "host", indicating + the current controller role. - It will do role switch when write "gadget" or "host" to it. + It will do role switch when "gadget" or "host" is written to it. Only controller at dual-role configuration supports writing. diff --git a/Documentation/ABI/testing/sysfs-power b/Documentation/ABI/testing/sysfs-power index 90ec4987074b..f99d433ff311 100644 --- a/Documentation/ABI/testing/sysfs-power +++ b/Documentation/ABI/testing/sysfs-power @@ -152,7 +152,7 @@ Description: case further investigation is required to determine which device is causing the problem. Note that genuine RTC clock values (such as when pm_trace has not been used), can still - match a device and output it's name here. + match a device and output its name here. What: /sys/power/pm_async Date: January 2009 diff --git a/Documentation/RCU/checklist.rst b/Documentation/RCU/checklist.rst index 42cc5d891bd2..048c5bc1f813 100644 --- a/Documentation/RCU/checklist.rst +++ b/Documentation/RCU/checklist.rst @@ -66,8 +66,13 @@ over a rather long period of time, but improvements are always welcome! As a rough rule of thumb, any dereference of an RCU-protected pointer must be covered by rcu_read_lock(), rcu_read_lock_bh(), rcu_read_lock_sched(), or by the appropriate update-side lock. - Disabling of preemption can serve as rcu_read_lock_sched(), but - is less readable and prevents lockdep from detecting locking issues. + Explicit disabling of preemption (preempt_disable(), for example) + can serve as rcu_read_lock_sched(), but is less readable and + prevents lockdep from detecting locking issues. + + Please not that you *cannot* rely on code known to be built + only in non-preemptible kernels. Such code can and will break, + especially in kernels built with CONFIG_PREEMPT_COUNT=y. Letting RCU-protected pointers "leak" out of an RCU read-side critical section is every bit as bad as letting them leak out @@ -185,6 +190,9 @@ over a rather long period of time, but improvements are always welcome! 5. If call_rcu() or call_srcu() is used, the callback function will be called from softirq context. In particular, it cannot block. + If you need the callback to block, run that code in a workqueue + handler scheduled from the callback. The queue_rcu_work() + function does this for you in the case of call_rcu(). 6. Since synchronize_rcu() can block, it cannot be called from any sort of irq context. The same rule applies @@ -297,7 +305,8 @@ over a rather long period of time, but improvements are always welcome! the machine. d. Periodically invoke synchronize_rcu(), permitting a limited - number of updates per grace period. + number of updates per grace period. Better yet, periodically + invoke rcu_barrier() to wait for all outstanding callbacks. The same cautions apply to call_srcu() and kfree_rcu(). @@ -477,6 +486,6 @@ over a rather long period of time, but improvements are always welcome! So if you need to wait for both an RCU grace period and for all pre-existing call_rcu() callbacks, you will need to execute both rcu_barrier() and synchronize_rcu(), if necessary, using - something like workqueues to to execute them concurrently. + something like workqueues to execute them concurrently. See rcubarrier.rst for more information. diff --git a/Documentation/RCU/lockdep.rst b/Documentation/RCU/lockdep.rst index cc860a0c296b..a94f55991a71 100644 --- a/Documentation/RCU/lockdep.rst +++ b/Documentation/RCU/lockdep.rst @@ -61,7 +61,7 @@ checking of rcu_dereference() primitives: rcu_access_pointer(p): Return the value of the pointer and omit all barriers, but retain the compiler constraints that prevent duplicating - or coalescsing. This is useful when when testing the + or coalescsing. This is useful when testing the value of the pointer itself, for example, against NULL. The rcu_dereference_check() check expression can be any boolean diff --git a/Documentation/RCU/rcu_dereference.rst b/Documentation/RCU/rcu_dereference.rst index 0b418a5b243c..81e828c8313b 100644 --- a/Documentation/RCU/rcu_dereference.rst +++ b/Documentation/RCU/rcu_dereference.rst @@ -128,10 +128,16 @@ Follow these rules to keep your RCU code working properly: This sort of comparison occurs frequently when scanning RCU-protected circular linked lists. - Note that if checks for being within an RCU read-side - critical section are not required and the pointer is never - dereferenced, rcu_access_pointer() should be used in place - of rcu_dereference(). + Note that if the pointer comparison is done outside + of an RCU read-side critical section, and the pointer + is never dereferenced, rcu_access_pointer() should be + used in place of rcu_dereference(). In most cases, + it is best to avoid accidental dereferences by testing + the rcu_access_pointer() return value directly, without + assigning it to a variable. + + Within an RCU read-side critical section, there is little + reason to use rcu_access_pointer(). - The comparison is against a pointer that references memory that was initialized "a long time ago." The reason diff --git a/Documentation/RCU/whatisRCU.rst b/Documentation/RCU/whatisRCU.rst index 77ea260efd12..1c747ac3f2c8 100644 --- a/Documentation/RCU/whatisRCU.rst +++ b/Documentation/RCU/whatisRCU.rst @@ -6,13 +6,15 @@ What is RCU? -- "Read, Copy, Update" Please note that the "What is RCU?" LWN series is an excellent place to start learning about RCU: -| 1. What is RCU, Fundamentally? http://lwn.net/Articles/262464/ -| 2. What is RCU? Part 2: Usage http://lwn.net/Articles/263130/ -| 3. RCU part 3: the RCU API http://lwn.net/Articles/264090/ -| 4. The RCU API, 2010 Edition http://lwn.net/Articles/418853/ -| 2010 Big API Table http://lwn.net/Articles/419086/ -| 5. The RCU API, 2014 Edition http://lwn.net/Articles/609904/ -| 2014 Big API Table http://lwn.net/Articles/609973/ +| 1. What is RCU, Fundamentally? https://lwn.net/Articles/262464/ +| 2. What is RCU? Part 2: Usage https://lwn.net/Articles/263130/ +| 3. RCU part 3: the RCU API https://lwn.net/Articles/264090/ +| 4. The RCU API, 2010 Edition https://lwn.net/Articles/418853/ +| 2010 Big API Table https://lwn.net/Articles/419086/ +| 5. The RCU API, 2014 Edition https://lwn.net/Articles/609904/ +| 2014 Big API Table https://lwn.net/Articles/609973/ +| 6. The RCU API, 2019 Edition https://lwn.net/Articles/777036/ +| 2019 Big API Table https://lwn.net/Articles/777165/ What is RCU? @@ -915,13 +917,18 @@ which an RCU reference is held include: 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. +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 +(and then potentially acquiring a spinlock), allowing subsequent code +to check whether the identity matches expectations. It is tempting +to simply acquire the spinlock without first taking the reference, but +unfortunately any spinlock in a ``SLAB_TYPESAFE_BY_RCU`` object must be +initialized after each and every call to kmem_cache_alloc(), which renders +reference-free spinlock acquisition completely unsafe. Therefore, when +using ``SLAB_TYPESAFE_BY_RCU``, make proper use of a reference counter. With traditional reference counting -- such as that implemented by the kref library in Linux -- there is typically code that runs when the last @@ -1057,14 +1064,20 @@ SRCU: Initialization/cleanup:: init_srcu_struct cleanup_srcu_struct -All: lockdep-checked RCU-protected pointer access:: +All: lockdep-checked RCU utility APIs:: - rcu_access_pointer - rcu_dereference_raw RCU_LOCKDEP_WARN rcu_sleep_check RCU_NONIDLE +All: Unchecked RCU-protected pointer access:: + + rcu_dereference_raw + +All: Unchecked RCU-protected pointer access with dereferencing prohibited:: + + rcu_access_pointer + See the comment headers in the source code (or the docbook generated from them) for more information. diff --git a/Documentation/admin-guide/README.rst b/Documentation/admin-guide/README.rst index caa3c09a5c3f..9a969c0157f1 100644 --- a/Documentation/admin-guide/README.rst +++ b/Documentation/admin-guide/README.rst @@ -1,9 +1,9 @@ .. _readme: -Linux kernel release 5.x <http://kernel.org/> +Linux kernel release 6.x <http://kernel.org/> ============================================= -These are the release notes for Linux version 5. Read them carefully, +These are the release notes for Linux version 6. Read them carefully, as they tell you what this is all about, explain how to install the kernel, and what to do if something goes wrong. @@ -63,7 +63,7 @@ Installing the kernel source directory where you have permissions (e.g. your home directory) and unpack it:: - xz -cd linux-5.x.tar.xz | tar xvf - + xz -cd linux-6.x.tar.xz | tar xvf - Replace "X" with the version number of the latest kernel. @@ -72,12 +72,12 @@ Installing the kernel source files. They should match the library, and not get messed up by whatever the kernel-du-jour happens to be. - - You can also upgrade between 5.x releases by patching. Patches are + - You can also upgrade between 6.x releases by patching. Patches are distributed in the xz format. To install by patching, get all the newer patch files, enter the top level directory of the kernel source - (linux-5.x) and execute:: + (linux-6.x) and execute:: - xz -cd ../patch-5.x.xz | patch -p1 + xz -cd ../patch-6.x.xz | patch -p1 Replace "x" for all versions bigger than the version "x" of your current source tree, **in_order**, and you should be ok. You may want to remove @@ -85,13 +85,13 @@ Installing the kernel source that there are no failed patches (some-file-name# or some-file-name.rej). If there are, either you or I have made a mistake. - Unlike patches for the 5.x kernels, patches for the 5.x.y kernels + Unlike patches for the 6.x kernels, patches for the 6.x.y kernels (also known as the -stable kernels) are not incremental but instead apply - directly to the base 5.x kernel. For example, if your base kernel is 5.0 - and you want to apply the 5.0.3 patch, you must not first apply the 5.0.1 - and 5.0.2 patches. Similarly, if you are running kernel version 5.0.2 and - want to jump to 5.0.3, you must first reverse the 5.0.2 patch (that is, - patch -R) **before** applying the 5.0.3 patch. You can read more on this in + directly to the base 6.x kernel. For example, if your base kernel is 6.0 + and you want to apply the 6.0.3 patch, you must not first apply the 6.0.1 + and 6.0.2 patches. Similarly, if you are running kernel version 6.0.2 and + want to jump to 6.0.3, you must first reverse the 6.0.2 patch (that is, + patch -R) **before** applying the 6.0.3 patch. You can read more on this in :ref:`Documentation/process/applying-patches.rst <applying_patches>`. Alternatively, the script patch-kernel can be used to automate this @@ -114,7 +114,7 @@ Installing the kernel source Software requirements --------------------- - Compiling and running the 5.x kernels requires up-to-date + Compiling and running the 6.x kernels requires up-to-date versions of various software packages. Consult :ref:`Documentation/process/changes.rst <changes>` for the minimum version numbers required and how to get updates for these packages. Beware that using @@ -132,12 +132,12 @@ Build directory for the kernel place for the output files (including .config). Example:: - kernel source code: /usr/src/linux-5.x + kernel source code: /usr/src/linux-6.x build directory: /home/name/build/kernel To configure and build the kernel, use:: - cd /usr/src/linux-5.x + cd /usr/src/linux-6.x make O=/home/name/build/kernel menuconfig make O=/home/name/build/kernel sudo make O=/home/name/build/kernel modules_install install @@ -262,8 +262,6 @@ Compiling the kernel - Make sure you have at least gcc 5.1 available. For more information, refer to :ref:`Documentation/process/changes.rst <changes>`. - Please note that you can still run a.out user programs with this kernel. - - Do a ``make`` to create a compressed kernel image. It is also possible to do ``make install`` if you have lilo installed to suit the kernel makefiles, but you may want to check your particular lilo setup first. @@ -332,85 +330,10 @@ Compiling the kernel If something goes wrong ----------------------- - - If you have problems that seem to be due to kernel bugs, please check - the file MAINTAINERS to see if there is a particular person associated - with the part of the kernel that you are having trouble with. If there - isn't anyone listed there, then the second best thing is to mail - them to me (torvalds@linux-foundation.org), and possibly to any other - relevant mailing-list or to the newsgroup. - - - In all bug-reports, *please* tell what kernel you are talking about, - how to duplicate the problem, and what your setup is (use your common - sense). If the problem is new, tell me so, and if the problem is - old, please try to tell me when you first noticed it. - - - If the bug results in a message like:: - - unable to handle kernel paging request at address C0000010 - Oops: 0002 - EIP: 0010:XXXXXXXX - eax: xxxxxxxx ebx: xxxxxxxx ecx: xxxxxxxx edx: xxxxxxxx - esi: xxxxxxxx edi: xxxxxxxx ebp: xxxxxxxx - ds: xxxx es: xxxx fs: xxxx gs: xxxx - Pid: xx, process nr: xx - xx xx xx xx xx xx xx xx xx xx - - or similar kernel debugging information on your screen or in your - system log, please duplicate it *exactly*. The dump may look - incomprehensible to you, but it does contain information that may - help debugging the problem. The text above the dump is also - important: it tells something about why the kernel dumped code (in - the above example, it's due to a bad kernel pointer). More information - on making sense of the dump is in Documentation/admin-guide/bug-hunting.rst - - - If you compiled the kernel with CONFIG_KALLSYMS you can send the dump - as is, otherwise you will have to use the ``ksymoops`` program to make - sense of the dump (but compiling with CONFIG_KALLSYMS is usually preferred). - This utility can be downloaded from - https://www.kernel.org/pub/linux/utils/kernel/ksymoops/ . - Alternatively, you can do the dump lookup by hand: - - - In debugging dumps like the above, it helps enormously if you can - look up what the EIP value means. The hex value as such doesn't help - me or anybody else very much: it will depend on your particular - kernel setup. What you should do is take the hex value from the EIP - line (ignore the ``0010:``), and look it up in the kernel namelist to - see which kernel function contains the offending address. - - To find out the kernel function name, you'll need to find the system - binary associated with the kernel that exhibited the symptom. This is - the file 'linux/vmlinux'. To extract the namelist and match it against - the EIP from the kernel crash, do:: - - nm vmlinux | sort | less - - This will give you a list of kernel addresses sorted in ascending - order, from which it is simple to find the function that contains the - offending address. Note that the address given by the kernel - debugging messages will not necessarily match exactly with the - function addresses (in fact, that is very unlikely), so you can't - just 'grep' the list: the list will, however, give you the starting - point of each kernel function, so by looking for the function that - has a starting address lower than the one you are searching for but - is followed by a function with a higher address you will find the one - you want. In fact, it may be a good idea to include a bit of - "context" in your problem report, giving a few lines around the - interesting one. - - If you for some reason cannot do the above (you have a pre-compiled - kernel image or similar), telling me as much about your setup as - possible will help. Please read - 'Documentation/admin-guide/reporting-issues.rst' for details. - - - Alternatively, you can use gdb on a running kernel. (read-only; i.e. you - cannot change values or set break points.) To do this, first compile the - kernel with -g; edit arch/x86/Makefile appropriately, then do a ``make - clean``. You'll also need to enable CONFIG_PROC_FS (via ``make config``). - - After you've rebooted with the new kernel, do ``gdb vmlinux /proc/kcore``. - You can now use all the usual gdb commands. The command to look up the - point where your system crashed is ``l *0xXXXXXXXX``. (Replace the XXXes - with the EIP value.) - - gdb'ing a non-running kernel currently fails because ``gdb`` (wrongly) - disregards the starting offset for which the kernel is compiled. +If you have problems that seem to be due to kernel bugs, please follow the +instructions at 'Documentation/admin-guide/reporting-issues.rst'. + +Hints on understanding kernel bug reports are in +'Documentation/admin-guide/bug-hunting.rst'. More on debugging the kernel +with gdb is in 'Documentation/dev-tools/gdb-kernel-debugging.rst' and +'Documentation/dev-tools/kgdb.rst'. diff --git a/Documentation/admin-guide/acpi/dsdt-override.rst b/Documentation/admin-guide/acpi/dsdt-override.rst deleted file mode 100644 index 50bd7f194bf4..000000000000 --- a/Documentation/admin-guide/acpi/dsdt-override.rst +++ /dev/null @@ -1,13 +0,0 @@ -.. SPDX-License-Identifier: GPL-2.0 - -=============== -Overriding DSDT -=============== - -Linux supports a method of overriding the BIOS DSDT: - -CONFIG_ACPI_CUSTOM_DSDT - builds the image into the kernel. - -When to use this method is described in detail on the -Linux/ACPI home page: -https://01.org/linux-acpi/documentation/overriding-dsdt diff --git a/Documentation/admin-guide/hw-vuln/spectre.rst b/Documentation/admin-guide/hw-vuln/spectre.rst index 2ce2a38cdd55..c4dcdb3d0d45 100644 --- a/Documentation/admin-guide/hw-vuln/spectre.rst +++ b/Documentation/admin-guide/hw-vuln/spectre.rst @@ -613,6 +613,7 @@ kernel command line. eibrs enhanced IBRS eibrs,retpoline enhanced IBRS + Retpolines eibrs,lfence enhanced IBRS + LFENCE + ibrs use IBRS to protect kernel Not specifying this option is equivalent to spectre_v2=auto. diff --git a/Documentation/admin-guide/kdump/vmcoreinfo.rst b/Documentation/admin-guide/kdump/vmcoreinfo.rst index 8419019b6a88..6726f439958c 100644 --- a/Documentation/admin-guide/kdump/vmcoreinfo.rst +++ b/Documentation/admin-guide/kdump/vmcoreinfo.rst @@ -200,7 +200,7 @@ prb A pointer to the printk ringbuffer (struct printk_ringbuffer). This may be pointing to the static boot ringbuffer or the dynamically -allocated ringbuffer, depending on when the the core dump occurred. +allocated ringbuffer, depending on when the core dump occurred. Used by user-space tools to read the active kernel log buffer. printk_rb_static diff --git a/Documentation/admin-guide/kernel-parameters.txt b/Documentation/admin-guide/kernel-parameters.txt index 426fa892d311..e92d63d3e878 100644 --- a/Documentation/admin-guide/kernel-parameters.txt +++ b/Documentation/admin-guide/kernel-parameters.txt @@ -966,10 +966,6 @@ debugpat [X86] Enable PAT debugging - decnet.addr= [HW,NET] - Format: <area>[,<node>] - See also Documentation/networking/decnet.rst. - default_hugepagesz= [HW] The size of the default HugeTLB page. This is the size represented by the legacy /proc/ hugepages @@ -3805,6 +3801,10 @@ nox2apic [X86-64,APIC] Do not enable x2APIC mode. + NOTE: this parameter will be ignored on systems with the + LEGACY_XAPIC_DISABLED bit set in the + IA32_XAPIC_DISABLE_STATUS MSR. + nps_mtm_hs_ctr= [KNL,ARC] This parameter sets the maximum duration, in cycles, each HW thread of the CTOP can run diff --git a/Documentation/admin-guide/mm/damon/usage.rst b/Documentation/admin-guide/mm/damon/usage.rst index d52f572a9029..ca91ecc29078 100644 --- a/Documentation/admin-guide/mm/damon/usage.rst +++ b/Documentation/admin-guide/mm/damon/usage.rst @@ -50,10 +50,10 @@ For a short example, users can monitor the virtual address space of a given workload as below. :: # cd /sys/kernel/mm/damon/admin/ - # echo 1 > kdamonds/nr && echo 1 > kdamonds/0/contexts/nr + # echo 1 > kdamonds/nr_kdamonds && echo 1 > kdamonds/0/contexts/nr_contexts # echo vaddr > kdamonds/0/contexts/0/operations - # echo 1 > kdamonds/0/contexts/0/targets/nr - # echo $(pidof <workload>) > kdamonds/0/contexts/0/targets/0/pid + # echo 1 > kdamonds/0/contexts/0/targets/nr_targets + # echo $(pidof <workload>) > kdamonds/0/contexts/0/targets/0/pid_target # echo on > kdamonds/0/state Files Hierarchy @@ -366,12 +366,12 @@ memory rate becomes larger than 60%, or lower than 30%". :: # echo 1 > kdamonds/0/contexts/0/schemes/nr_schemes # cd kdamonds/0/contexts/0/schemes/0 # # set the basic access pattern and the action - # echo 4096 > access_patterns/sz/min - # echo 8192 > access_patterns/sz/max - # echo 0 > access_patterns/nr_accesses/min - # echo 5 > access_patterns/nr_accesses/max - # echo 10 > access_patterns/age/min - # echo 20 > access_patterns/age/max + # echo 4096 > access_pattern/sz/min + # echo 8192 > access_pattern/sz/max + # echo 0 > access_pattern/nr_accesses/min + # echo 5 > access_pattern/nr_accesses/max + # echo 10 > access_pattern/age/min + # echo 20 > access_pattern/age/max # echo pageout > action # # set quotas # echo 10 > quotas/ms diff --git a/Documentation/admin-guide/mm/hugetlbpage.rst b/Documentation/admin-guide/mm/hugetlbpage.rst index 8e2727dc18d4..19f27c0d92e0 100644 --- a/Documentation/admin-guide/mm/hugetlbpage.rst +++ b/Documentation/admin-guide/mm/hugetlbpage.rst @@ -65,7 +65,7 @@ HugePages_Surp may be temporarily larger than the maximum number of surplus huge pages when the system is under memory pressure. Hugepagesize - is the default hugepage size (in Kb). + is the default hugepage size (in kB). Hugetlb is the total amount of memory (in kB), consumed by huge pages of all sizes. diff --git a/Documentation/admin-guide/sysctl/net.rst b/Documentation/admin-guide/sysctl/net.rst index 60d44165fba7..6394f5dc2303 100644 --- a/Documentation/admin-guide/sysctl/net.rst +++ b/Documentation/admin-guide/sysctl/net.rst @@ -31,17 +31,18 @@ see only some of them, depending on your kernel's configuration. Table : Subdirectories in /proc/sys/net - ========= =================== = ========== ================== + ========= =================== = ========== =================== Directory Content Directory Content - ========= =================== = ========== ================== - core General parameter appletalk Appletalk protocol - unix Unix domain sockets netrom NET/ROM - 802 E802 protocol ax25 AX25 - ethernet Ethernet protocol rose X.25 PLP layer + ========= =================== = ========== =================== + 802 E802 protocol mptcp Multipath TCP + appletalk Appletalk protocol netfilter Network Filter + ax25 AX25 netrom NET/ROM + bridge Bridging rose X.25 PLP layer + core General parameter tipc TIPC + ethernet Ethernet protocol unix Unix domain sockets ipv4 IP version 4 x25 X.25 protocol - bridge Bridging decnet DEC net - ipv6 IP version 6 tipc TIPC - ========= =================== = ========== ================== + ipv6 IP version 6 + ========= =================== = ========== =================== 1. /proc/sys/net/core - Network core options ============================================ @@ -101,6 +102,9 @@ Values: - 1 - enable JIT hardening for unprivileged users only - 2 - enable JIT hardening for all users +where "privileged user" in this context means a process having +CAP_BPF or CAP_SYS_ADMIN in the root user name space. + bpf_jit_kallsyms ---------------- diff --git a/Documentation/admin-guide/tainted-kernels.rst b/Documentation/admin-guide/tainted-kernels.rst index 7d80e8c307d1..92a8a07f5c43 100644 --- a/Documentation/admin-guide/tainted-kernels.rst +++ b/Documentation/admin-guide/tainted-kernels.rst @@ -134,6 +134,12 @@ More detailed explanation for tainting scsi/snic on something else than x86_64, scsi/ips on non x86/x86_64/itanium, have broken firmware settings for the irqchip/irq-gic on arm64 ...). + - x86/x86_64: Microcode late loading is dangerous and will result in + tainting the kernel. It requires that all CPUs rendezvous to make sure + the update happens when the system is as quiescent as possible. However, + a higher priority MCE/SMI/NMI can move control flow away from that + rendezvous and interrupt the update, which can be detrimental to the + machine. 3) ``R`` if a module was force unloaded by ``rmmod -f``, ``' '`` if all modules were unloaded normally. diff --git a/Documentation/block/index.rst b/Documentation/block/index.rst index 68f115f2b1c6..c4c73db748a8 100644 --- a/Documentation/block/index.rst +++ b/Documentation/block/index.rst @@ -23,3 +23,4 @@ Block stat switching-sched writeback_cache_control + ublk diff --git a/Documentation/block/ublk.rst b/Documentation/block/ublk.rst new file mode 100644 index 000000000000..2122d1a4a541 --- /dev/null +++ b/Documentation/block/ublk.rst @@ -0,0 +1,253 @@ +.. SPDX-License-Identifier: GPL-2.0 + +=========================================== +Userspace block device driver (ublk driver) +=========================================== + +Overview +======== + +ublk is a generic framework for implementing block device logic from userspace. +The motivation behind it is that moving virtual block drivers into userspace, +such as loop, nbd and similar can be very helpful. It can help to implement +new virtual block device such as ublk-qcow2 (there are several attempts of +implementing qcow2 driver in kernel). + +Userspace block devices are attractive because: + +- They can be written many programming languages. +- They can use libraries that are not available in the kernel. +- They can be debugged with tools familiar to application developers. +- Crashes do not kernel panic the machine. +- Bugs are likely to have a lower security impact than bugs in kernel + code. +- They can be installed and updated independently of the kernel. +- They can be used to simulate block device easily with user specified + parameters/setting for test/debug purpose + +ublk block device (``/dev/ublkb*``) is added by ublk driver. Any IO request +on the device will be forwarded to ublk userspace program. For convenience, +in this document, ``ublk server`` refers to generic ublk userspace +program. ``ublksrv`` [#userspace]_ is one of such implementation. It +provides ``libublksrv`` [#userspace_lib]_ library for developing specific +user block device conveniently, while also generic type block device is +included, such as loop and null. Richard W.M. Jones wrote userspace nbd device +``nbdublk`` [#userspace_nbdublk]_ based on ``libublksrv`` [#userspace_lib]_. + +After the IO is handled by userspace, the result is committed back to the +driver, thus completing the request cycle. This way, any specific IO handling +logic is totally done by userspace, such as loop's IO handling, NBD's IO +communication, or qcow2's IO mapping. + +``/dev/ublkb*`` is driven by blk-mq request-based driver. Each request is +assigned by one queue wide unique tag. ublk server assigns unique tag to each +IO too, which is 1:1 mapped with IO of ``/dev/ublkb*``. + +Both the IO request forward and IO handling result committing are done via +``io_uring`` passthrough command; that is why ublk is also one io_uring based +block driver. It has been observed that using io_uring passthrough command can +give better IOPS than block IO; which is why ublk is one of high performance +implementation of userspace block device: not only IO request communication is +done by io_uring, but also the preferred IO handling in ublk server is io_uring +based approach too. + +ublk provides control interface to set/get ublk block device parameters. +The interface is extendable and kabi compatible: basically any ublk request +queue's parameter or ublk generic feature parameters can be set/get via the +interface. Thus, ublk is generic userspace block device framework. +For example, it is easy to setup a ublk device with specified block +parameters from userspace. + +Using ublk +========== + +ublk requires userspace ublk server to handle real block device logic. + +Below is example of using ``ublksrv`` to provide ublk-based loop device. + +- add a device:: + + ublk add -t loop -f ublk-loop.img + +- format with xfs, then use it:: + + mkfs.xfs /dev/ublkb0 + mount /dev/ublkb0 /mnt + # do anything. all IOs are handled by io_uring + ... + umount /mnt + +- list the devices with their info:: + + ublk list + +- delete the device:: + + ublk del -a + ublk del -n $ublk_dev_id + +See usage details in README of ``ublksrv`` [#userspace_readme]_. + +Design +====== + +Control plane +------------- + +ublk driver provides global misc device node (``/dev/ublk-control``) for +managing and controlling ublk devices with help of several control commands: + +- ``UBLK_CMD_ADD_DEV`` + + Add a ublk char device (``/dev/ublkc*``) which is talked with ublk server + WRT IO command communication. Basic device info is sent together with this + command. It sets UAPI structure of ``ublksrv_ctrl_dev_info``, + such as ``nr_hw_queues``, ``queue_depth``, and max IO request buffer size, + for which the info is negotiated with the driver and sent back to the server. + When this command is completed, the basic device info is immutable. + +- ``UBLK_CMD_SET_PARAMS`` / ``UBLK_CMD_GET_PARAMS`` + + Set or get parameters of the device, which can be either generic feature + related, or request queue limit related, but can't be IO logic specific, + because the driver does not handle any IO logic. This command has to be + sent before sending ``UBLK_CMD_START_DEV``. + +- ``UBLK_CMD_START_DEV`` + + After the server prepares userspace resources (such as creating per-queue + pthread & io_uring for handling ublk IO), this command is sent to the + driver for allocating & exposing ``/dev/ublkb*``. Parameters set via + ``UBLK_CMD_SET_PARAMS`` are applied for creating the device. + +- ``UBLK_CMD_STOP_DEV`` + + Halt IO on ``/dev/ublkb*`` and remove the device. When this command returns, + ublk server will release resources (such as destroying per-queue pthread & + io_uring). + +- ``UBLK_CMD_DEL_DEV`` + + Remove ``/dev/ublkc*``. When this command returns, the allocated ublk device + number can be reused. + +- ``UBLK_CMD_GET_QUEUE_AFFINITY`` + + When ``/dev/ublkc`` is added, the driver creates block layer tagset, so + that each queue's affinity info is available. The server sends + ``UBLK_CMD_GET_QUEUE_AFFINITY`` to retrieve queue affinity info. It can + set up the per-queue context efficiently, such as bind affine CPUs with IO + pthread and try to allocate buffers in IO thread context. + +- ``UBLK_CMD_GET_DEV_INFO`` + + For retrieving device info via ``ublksrv_ctrl_dev_info``. It is the server's + responsibility to save IO target specific info in userspace. + +Data plane +---------- + +ublk server needs to create per-queue IO pthread & io_uring for handling IO +commands via io_uring passthrough. The per-queue IO pthread +focuses on IO handling and shouldn't handle any control & management +tasks. + +The's IO is assigned by a unique tag, which is 1:1 mapping with IO +request of ``/dev/ublkb*``. + +UAPI structure of ``ublksrv_io_desc`` is defined for describing each IO from +the driver. A fixed mmaped area (array) on ``/dev/ublkc*`` is provided for +exporting IO info to the server; such as IO offset, length, OP/flags and +buffer address. Each ``ublksrv_io_desc`` instance can be indexed via queue id +and IO tag directly. + +The following IO commands are communicated via io_uring passthrough command, +and each command is only for forwarding the IO and committing the result +with specified IO tag in the command data: + +- ``UBLK_IO_FETCH_REQ`` + + Sent from the server IO pthread for fetching future incoming IO requests + destined to ``/dev/ublkb*``. This command is sent only once from the server + IO pthread for ublk driver to setup IO forward environment. + +- ``UBLK_IO_COMMIT_AND_FETCH_REQ`` + + When an IO request is destined to ``/dev/ublkb*``, the driver stores + the IO's ``ublksrv_io_desc`` to the specified mapped area; then the + previous received IO command of this IO tag (either ``UBLK_IO_FETCH_REQ`` + or ``UBLK_IO_COMMIT_AND_FETCH_REQ)`` is completed, so the server gets + the IO notification via io_uring. + + After the server handles the IO, its result is committed back to the + driver by sending ``UBLK_IO_COMMIT_AND_FETCH_REQ`` back. Once ublkdrv + received this command, it parses the result and complete the request to + ``/dev/ublkb*``. In the meantime setup environment for fetching future + requests with the same IO tag. That is, ``UBLK_IO_COMMIT_AND_FETCH_REQ`` + is reused for both fetching request and committing back IO result. + +- ``UBLK_IO_NEED_GET_DATA`` + + With ``UBLK_F_NEED_GET_DATA`` enabled, the WRITE request will be firstly + issued to ublk server without data copy. Then, IO backend of ublk server + receives the request and it can allocate data buffer and embed its addr + inside this new io command. After the kernel driver gets the command, + data copy is done from request pages to this backend's buffer. Finally, + backend receives the request again with data to be written and it can + truly handle the request. + + ``UBLK_IO_NEED_GET_DATA`` adds one additional round-trip and one + io_uring_enter() syscall. Any user thinks that it may lower performance + should not enable UBLK_F_NEED_GET_DATA. ublk server pre-allocates IO + buffer for each IO by default. Any new project should try to use this + buffer to communicate with ublk driver. However, existing project may + break or not able to consume the new buffer interface; that's why this + command is added for backwards compatibility so that existing projects + can still consume existing buffers. + +- data copy between ublk server IO buffer and ublk block IO request + + The driver needs to copy the block IO request pages into the server buffer + (pages) first for WRITE before notifying the server of the coming IO, so + that the server can handle WRITE request. + + When the server handles READ request and sends + ``UBLK_IO_COMMIT_AND_FETCH_REQ`` to the server, ublkdrv needs to copy + the server buffer (pages) read to the IO request pages. + +Future development +================== + +Container-aware ublk deivice +---------------------------- + +ublk driver doesn't handle any IO logic. Its function is well defined +for now and very limited userspace interfaces are needed, which is also +well defined too. It is possible to make ublk devices container-aware block +devices in future as Stefan Hajnoczi suggested [#stefan]_, by removing +ADMIN privilege. + +Zero copy +--------- + +Zero copy is a generic requirement for nbd, fuse or similar drivers. A +problem [#xiaoguang]_ Xiaoguang mentioned is that pages mapped to userspace +can't be remapped any more in kernel with existing mm interfaces. This can +occurs when destining direct IO to ``/dev/ublkb*``. Also, he reported that +big requests (IO size >= 256 KB) may benefit a lot from zero copy. + + +References +========== + +.. [#userspace] https://github.com/ming1/ubdsrv + +.. [#userspace_lib] https://github.com/ming1/ubdsrv/tree/master/lib + +.. [#userspace_nbdublk] https://gitlab.com/rwmjones/libnbd/-/tree/nbdublk + +.. [#userspace_readme] https://github.com/ming1/ubdsrv/blob/master/README + +.. [#stefan] https://lore.kernel.org/linux-block/YoOr6jBfgVm8GvWg@stefanha-x1.localdomain/ + +.. [#xiaoguang] https://lore.kernel.org/linux-block/YoOr6jBfgVm8GvWg@stefanha-x1.localdomain/ diff --git a/Documentation/bpf/clang-notes.rst b/Documentation/bpf/clang-notes.rst new file mode 100644 index 000000000000..528feddf2db9 --- /dev/null +++ b/Documentation/bpf/clang-notes.rst @@ -0,0 +1,30 @@ +.. contents:: +.. sectnum:: + +========================== +Clang implementation notes +========================== + +This document provides more details specific to the Clang/LLVM implementation of the eBPF instruction set. + +Versions +======== + +Clang defined "CPU" versions, where a CPU version of 3 corresponds to the current eBPF ISA. + +Clang can select the eBPF ISA version using ``-mcpu=v3`` for example to select version 3. + +Arithmetic instructions +======================= + +For CPU versions prior to 3, Clang v7.0 and later can enable ``BPF_ALU`` support with +``-Xclang -target-feature -Xclang +alu32``. In CPU version 3, support is automatically included. + +Atomic operations +================= + +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``. diff --git a/Documentation/bpf/index.rst b/Documentation/bpf/index.rst index 1bc2c5c58bdb..1b50de1983ee 100644 --- a/Documentation/bpf/index.rst +++ b/Documentation/bpf/index.rst @@ -26,6 +26,8 @@ that goes into great technical depth about the BPF Architecture. classic_vs_extended.rst bpf_licensing test_debug + clang-notes + linux-notes other .. only:: subproject and html diff --git a/Documentation/bpf/instruction-set.rst b/Documentation/bpf/instruction-set.rst index 1b0e6711dec9..5d798437dad4 100644 --- a/Documentation/bpf/instruction-set.rst +++ b/Documentation/bpf/instruction-set.rst @@ -1,7 +1,12 @@ +.. contents:: +.. sectnum:: + +======================================== +eBPF Instruction Set Specification, v1.0 +======================================== + +This document specifies version 1.0 of the eBPF instruction set. -==================== -eBPF Instruction Set -==================== Registers and calling convention ================================ @@ -11,10 +16,10 @@ 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: 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. @@ -24,17 +29,17 @@ Instruction encoding eBPF has two instruction encodings: - * the basic instruction encoding, which uses 64 bits to encode an instruction - * the wide instruction encoding, which appends a second 64-bit immediate value - (imm64) after the basic instruction for a total of 128 bits. +* the basic instruction encoding, which uses 64 bits to encode an instruction +* the wide instruction encoding, which appends a second 64-bit immediate value + (imm64) after the basic instruction for a total of 128 bits. The basic instruction encoding looks as follows: - ============= ======= =============== ==================== ============ - 32 bits (MSB) 16 bits 4 bits 4 bits 8 bits (LSB) - ============= ======= =============== ==================== ============ - immediate offset source register destination register opcode - ============= ======= =============== ==================== ============ +============= ======= =============== ==================== ============ +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. @@ -44,30 +49,30 @@ 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 - ========= ===== =============================== +========= ===== =============================== =================================== +class value description reference +========= ===== =============================== =================================== +BPF_LD 0x00 non-standard load operations `Load and store instructions`_ +BPF_LDX 0x01 load into register operations `Load and store instructions`_ +BPF_ST 0x02 store from immediate operations `Load and store instructions`_ +BPF_STX 0x03 store from register operations `Load and store instructions`_ +BPF_ALU 0x04 32-bit arithmetic operations `Arithmetic and jump instructions`_ +BPF_JMP 0x05 64-bit jump operations `Arithmetic and jump instructions`_ +BPF_JMP32 0x06 32-bit jump operations `Arithmetic and jump instructions`_ +BPF_ALU64 0x07 64-bit arithmetic operations `Arithmetic and jump instructions`_ +========= ===== =============================== =================================== 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: +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 - ============== ====== ================= +============== ====== ================= +4 bits (MSB) 1 bit 3 bits (LSB) +============== ====== ================= +operation code source instruction class +============== ====== ================= The 4th bit encodes the source operand: @@ -84,66 +89,66 @@ 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 +``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 byte swap operations (see separate section below) - ======== ===== ================================================= - -BPF_ADD | BPF_X | BPF_ALU means:: +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 byte swap operations (see `Byte swap instructions`_ below) +======== ===== ========================================================== + +``BPF_ADD | BPF_X | BPF_ALU`` means:: dst_reg = (u32) dst_reg + (u32) src_reg; -BPF_ADD | BPF_X | BPF_ALU64 means:: +``BPF_ADD | BPF_X | BPF_ALU64`` means:: dst_reg = dst_reg + src_reg -BPF_XOR | BPF_K | BPF_ALU means:: +``BPF_XOR | BPF_K | BPF_ALU`` means:: src_reg = (u32) src_reg ^ (u32) imm32 -BPF_XOR | BPF_K | BPF_ALU64 means:: +``BPF_XOR | BPF_K | BPF_ALU64`` means:: src_reg = src_reg ^ imm32 Byte swap instructions ----------------------- +~~~~~~~~~~~~~~~~~~~~~~ The byte swap instructions use an instruction class of ``BPF_ALU`` and a 4-bit -code field of ``BPF_END``. +'code' field of ``BPF_END``. The byte swap instructions operate on the destination register only and do not use a separate source register or immediate value. -The 1-bit source operand field in the opcode is used to to select what byte +The 1-bit source operand field in the opcode is used to select what byte order the operation convert from or to: - ========= ===== ================================================= - source value description - ========= ===== ================================================= - BPF_TO_LE 0x00 convert between host byte order and little endian - BPF_TO_BE 0x08 convert between host byte order and big endian - ========= ===== ================================================= +========= ===== ================================================= +source value description +========= ===== ================================================= +BPF_TO_LE 0x00 convert between host byte order and little endian +BPF_TO_BE 0x08 convert between host byte order and big endian +========= ===== ================================================= -The imm field encodes the width of the swap operations. The following widths +The 'imm' field encodes the width of the swap operations. The following widths are supported: 16, 32 and 64. Examples: @@ -156,35 +161,31 @@ Examples: dst_reg = htobe64(dst_reg) -``BPF_FROM_LE`` and ``BPF_FROM_BE`` exist as aliases for ``BPF_TO_LE`` and -``BPF_TO_BE`` respectively. - - Jump instructions ----------------- -BPF_JMP32 uses 32-bit wide operands while BPF_JMP uses 64-bit wide operands for +``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 '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. @@ -193,14 +194,26 @@ BPF_EXIT. Load and store instructions =========================== -For load and store instructions (BPF_LD, BPF_LDX, BPF_ST and BPF_STX), the +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 - ============ ====== ================= +============ ====== ================= +3 bits (MSB) 2 bits 3 bits (LSB) +============ ====== ================= +mode size instruction class +============ ====== ================= + +The mode modifier is one of: + + ============= ===== ==================================== ============= + mode modifier value description reference + ============= ===== ==================================== ============= + BPF_IMM 0x00 64-bit immediate instructions `64-bit immediate instructions`_ + BPF_ABS 0x20 legacy BPF packet access (absolute) `Legacy BPF Packet access instructions`_ + BPF_IND 0x40 legacy BPF packet access (indirect) `Legacy BPF Packet access instructions`_ + BPF_MEM 0x60 regular load and store operations `Regular load and store operations`_ + BPF_ATOMIC 0xc0 atomic operations `Atomic operations`_ + ============= ===== ==================================== ============= The size modifier is one of: @@ -213,19 +226,6 @@ The size modifier is one of: BPF_DW 0x18 double word (8 bytes) ============= ===== ===================== -The mode modifier is one of: - - ============= ===== ==================================== - mode modifier value description - ============= ===== ==================================== - BPF_IMM 0x00 64-bit immediate instructions - BPF_ABS 0x20 legacy BPF packet access (absolute) - BPF_IND 0x40 legacy BPF packet access (indirect) - BPF_MEM 0x60 regular load and store operations - BPF_ATOMIC 0xc0 atomic operations - ============= ===== ==================================== - - Regular load and store operations --------------------------------- @@ -256,44 +256,42 @@ by other eBPF programs or means outside of this specification. All atomic operations supported by eBPF are encoded as store operations that use the ``BPF_ATOMIC`` mode modifier as follows: - * ``BPF_ATOMIC | BPF_W | BPF_STX`` for 32-bit operations - * ``BPF_ATOMIC | BPF_DW | BPF_STX`` for 64-bit operations - * 8-bit and 16-bit wide atomic operations are not supported. +* ``BPF_ATOMIC | BPF_W | BPF_STX`` for 32-bit operations +* ``BPF_ATOMIC | BPF_DW | BPF_STX`` for 64-bit operations +* 8-bit and 16-bit wide atomic operations are not supported. -The imm field is used to encode the actual atomic operation. +The 'imm' field is used to encode the actual atomic operation. Simple atomic operation use a subset of the values defined to encode -arithmetic operations in the imm field to encode the atomic operation: +arithmetic operations in the 'imm' field to encode the atomic operation: - ======== ===== =========== - imm value description - ======== ===== =========== - BPF_ADD 0x00 atomic add - BPF_OR 0x40 atomic or - BPF_AND 0x50 atomic and - BPF_XOR 0xa0 atomic xor - ======== ===== =========== +======== ===== =========== +imm value description +======== ===== =========== +BPF_ADD 0x00 atomic add +BPF_OR 0x40 atomic or +BPF_AND 0x50 atomic and +BPF_XOR 0xa0 atomic xor +======== ===== =========== -``BPF_ATOMIC | BPF_W | BPF_STX`` with imm = BPF_ADD means:: +``BPF_ATOMIC | BPF_W | BPF_STX`` with 'imm' = BPF_ADD means:: *(u32 *)(dst_reg + off16) += src_reg -``BPF_ATOMIC | BPF_DW | BPF_STX`` with imm = BPF ADD means:: +``BPF_ATOMIC | BPF_DW | BPF_STX`` with 'imm' = BPF ADD means:: *(u64 *)(dst_reg + off16) += src_reg -``BPF_XADD`` is a deprecated name for ``BPF_ATOMIC | BPF_ADD``. - In addition to the simple atomic operations, there also is a modifier and two complex atomic operations: - =========== ================ =========================== - imm value description - =========== ================ =========================== - BPF_FETCH 0x01 modifier: return old value - BPF_XCHG 0xe0 | BPF_FETCH atomic exchange - BPF_CMPXCHG 0xf0 | BPF_FETCH atomic compare and exchange - =========== ================ =========================== +=========== ================ =========================== +imm value description +=========== ================ =========================== +BPF_FETCH 0x01 modifier: return old value +BPF_XCHG 0xe0 | BPF_FETCH atomic exchange +BPF_CMPXCHG 0xf0 | BPF_FETCH atomic compare and exchange +=========== ================ =========================== The ``BPF_FETCH`` modifier is optional for simple atomic operations, and always set for the complex atomic operations. If the ``BPF_FETCH`` flag @@ -309,16 +307,10 @@ The ``BPF_CMPXCHG`` operation atomically compares the value addressed by value that was at ``dst_reg + off`` before the operation is zero-extended and loaded back to ``R0``. -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``. - 64-bit immediate instructions ----------------------------- -Instructions with the ``BPF_IMM`` mode modifier use the wide instruction +Instructions with the ``BPF_IMM`` 'mode' modifier use the wide instruction encoding for an extra imm64 value. There is currently only one such instruction. @@ -331,36 +323,6 @@ There is currently only one such instruction. Legacy BPF Packet access instructions ------------------------------------- -eBPF has special instructions for access to packet data that have been -carried over from classic BPF to retain the performance of legacy socket -filters running in the eBPF interpreter. - -The instructions come in two forms: ``BPF_ABS | <size> | BPF_LD`` and -``BPF_IND | <size> | BPF_LD``. - -These instructions are used to access packet data and can only be used when -the program context is a pointer to networking packet. ``BPF_ABS`` -accesses packet data at an absolute offset specified by the immediate data -and ``BPF_IND`` access packet data at an offset that includes the value of -a register in addition to the immediate data. - -These instructions have seven implicit operands: - - * Register R6 is an implicit input that must contain pointer to a - struct sk_buff. - * Register R0 is an implicit output which contains the data fetched from - the packet. - * Registers R1-R5 are scratch registers that are clobbered after a call to - ``BPF_ABS | BPF_LD`` or ``BPF_IND | BPF_LD`` instructions. - -These instructions have an implicit program exit condition as well. When an -eBPF program is trying to access the data beyond the packet boundary, the -program execution will be aborted. - -``BPF_ABS | BPF_W | BPF_LD`` means:: - - R0 = ntohl(*(u32 *) (((struct sk_buff *) R6)->data + imm32)) - -``BPF_IND | BPF_W | BPF_LD`` means:: - - R0 = ntohl(*(u32 *) (((struct sk_buff *) R6)->data + src_reg + imm32)) +eBPF previously introduced special instructions for access to packet data that were +carried over from classic BPF. However, these instructions are +deprecated and should no longer be used. diff --git a/Documentation/bpf/kfuncs.rst b/Documentation/bpf/kfuncs.rst index c0b7dae6dbf5..0f858156371d 100644 --- a/Documentation/bpf/kfuncs.rst +++ b/Documentation/bpf/kfuncs.rst @@ -137,14 +137,37 @@ KF_ACQUIRE and KF_RET_NULL flags. -------------------------- The KF_TRUSTED_ARGS flag is used for kfuncs taking pointer arguments. It -indicates that the all pointer arguments will always be refcounted, and have -their offset set to 0. It can be used to enforce that a pointer to a refcounted -object acquired from a kfunc or BPF helper is passed as an argument to this -kfunc without any modifications (e.g. pointer arithmetic) such that it is -trusted and points to the original object. This flag is often used for kfuncs -that operate (change some property, perform some operation) on an object that -was obtained using an acquire kfunc. Such kfuncs need an unchanged pointer to -ensure the integrity of the operation being performed on the expected object. +indicates that the all pointer arguments will always have a guaranteed lifetime, +and pointers to kernel objects are always passed to helpers in their unmodified +form (as obtained from acquire kfuncs). + +It can be used to enforce that a pointer to a refcounted object acquired from a +kfunc or BPF helper is passed as an argument to this kfunc without any +modifications (e.g. pointer arithmetic) such that it is trusted and points to +the original object. + +Meanwhile, it is also allowed pass pointers to normal memory to such kfuncs, +but those can have a non-zero offset. + +This flag is often used for kfuncs that operate (change some property, perform +some operation) on an object that was obtained using an acquire kfunc. Such +kfuncs need an unchanged pointer to ensure the integrity of the operation being +performed on the expected object. + +2.4.6 KF_SLEEPABLE flag +----------------------- + +The KF_SLEEPABLE flag is used for kfuncs that may sleep. Such kfuncs can only +be called by sleepable BPF programs (BPF_F_SLEEPABLE). + +2.4.7 KF_DESTRUCTIVE flag +-------------------------- + +The KF_DESTRUCTIVE flag is used to indicate functions calling which is +destructive to the system. For example such a call can result in system +rebooting or panicking. Due to this additional restrictions apply to these +calls. At the moment they only require CAP_SYS_BOOT capability, but more can be +added later. 2.5 Registering the kfuncs -------------------------- diff --git a/Documentation/bpf/linux-notes.rst b/Documentation/bpf/linux-notes.rst new file mode 100644 index 000000000000..956b0c86699d --- /dev/null +++ b/Documentation/bpf/linux-notes.rst @@ -0,0 +1,53 @@ +.. contents:: +.. sectnum:: + +========================== +Linux implementation notes +========================== + +This document provides more details specific to the Linux kernel implementation of the eBPF instruction set. + +Byte swap instructions +====================== + +``BPF_FROM_LE`` and ``BPF_FROM_BE`` exist as aliases for ``BPF_TO_LE`` and ``BPF_TO_BE`` respectively. + +Legacy BPF Packet access instructions +===================================== + +As mentioned in the `ISA standard documentation <instruction-set.rst#legacy-bpf-packet-access-instructions>`_, +Linux has special eBPF instructions for access to packet data that have been +carried over from classic BPF to retain the performance of legacy socket +filters running in the eBPF interpreter. + +The instructions come in two forms: ``BPF_ABS | <size> | BPF_LD`` and +``BPF_IND | <size> | BPF_LD``. + +These instructions are used to access packet data and can only be used when +the program context is a pointer to a networking packet. ``BPF_ABS`` +accesses packet data at an absolute offset specified by the immediate data +and ``BPF_IND`` access packet data at an offset that includes the value of +a register in addition to the immediate data. + +These instructions have seven implicit operands: + +* Register R6 is an implicit input that must contain a pointer to a + struct sk_buff. +* Register R0 is an implicit output which contains the data fetched from + the packet. +* Registers R1-R5 are scratch registers that are clobbered by the + instruction. + +These instructions have an implicit program exit condition as well. If an +eBPF program attempts access data beyond the packet boundary, the +program execution will be aborted. + +``BPF_ABS | BPF_W | BPF_LD`` (0x20) means:: + + R0 = ntohl(*(u32 *) ((struct sk_buff *) R6->data + imm)) + +where ``ntohl()`` converts a 32-bit value from network byte order to host byte order. + +``BPF_IND | BPF_W | BPF_LD`` (0x40) means:: + + R0 = ntohl(*(u32 *) ((struct sk_buff *) R6->data + src + imm)) diff --git a/Documentation/bpf/map_cgroup_storage.rst b/Documentation/bpf/map_cgroup_storage.rst index cab9543017bf..8e5fe532c07e 100644 --- a/Documentation/bpf/map_cgroup_storage.rst +++ b/Documentation/bpf/map_cgroup_storage.rst @@ -31,7 +31,7 @@ The map uses key of type of either ``__u64 cgroup_inode_id`` or }; ``cgroup_inode_id`` is the inode id of the cgroup directory. -``attach_type`` is the the program's attach type. +``attach_type`` is the program's attach type. Linux 5.9 added support for type ``__u64 cgroup_inode_id`` as the key type. When this key type is used, then all attach types of the particular cgroup and @@ -155,7 +155,7 @@ However, the BPF program can still only associate with one map of each type ``BPF_MAP_TYPE_CGROUP_STORAGE`` or more than one ``BPF_MAP_TYPE_PERCPU_CGROUP_STORAGE``. -In all versions, userspace may use the the attach parameters of cgroup and +In all versions, userspace may use the attach parameters of cgroup and attach type pair in ``struct bpf_cgroup_storage_key`` as the key to the BPF map APIs to read or update the storage for a given attachment. For Linux 5.9 attach type shared storages, only the first value in the struct, cgroup inode diff --git a/Documentation/conf.py b/Documentation/conf.py index 934727e23e0e..b50c85083149 100644 --- a/Documentation/conf.py +++ b/Documentation/conf.py @@ -15,6 +15,18 @@ import sys import os import sphinx +import shutil + +# helper +# ------ + +def have_command(cmd): + """Search ``cmd`` in the ``PATH`` environment. + + If found, return True. + If not found, return False. + """ + return shutil.which(cmd) is not None # Get Sphinx version major, minor, patch = sphinx.version_info[:3] @@ -86,6 +98,7 @@ if major >= 3: "__used", "__weak", "noinline", + "__fix_address", # include/linux/memblock.h: "__init_memblock", @@ -106,7 +119,32 @@ else: autosectionlabel_prefix_document = True autosectionlabel_maxdepth = 2 -extensions.append("sphinx.ext.imgmath") +# Load math renderer: +# For html builder, load imgmath only when its dependencies are met. +# mathjax is the default math renderer since Sphinx 1.8. +have_latex = have_command('latex') +have_dvipng = have_command('dvipng') +load_imgmath = have_latex and have_dvipng + +# Respect SPHINX_IMGMATH (for html docs only) +if 'SPHINX_IMGMATH' in os.environ: + env_sphinx_imgmath = os.environ['SPHINX_IMGMATH'] + if 'yes' in env_sphinx_imgmath: + load_imgmath = True + elif 'no' in env_sphinx_imgmath: + load_imgmath = False + else: + sys.stderr.write("Unknown env SPHINX_IMGMATH=%s ignored.\n" % env_sphinx_imgmath) + +# Always load imgmath for Sphinx <1.8 or for epub docs +load_imgmath = (load_imgmath or (major == 1 and minor < 8) + or 'epub' in sys.argv) + +if load_imgmath: + extensions.append("sphinx.ext.imgmath") + math_renderer = 'imgmath' +else: + math_renderer = 'mathjax' # Add any paths that contain templates here, relative to this directory. templates_path = ['_templates'] @@ -332,7 +370,8 @@ html_static_path = ['sphinx-static'] html_use_smartypants = False # Custom sidebar templates, maps document names to template names. -#html_sidebars = {} +# Note that the RTD theme ignores this. +html_sidebars = { '**': ['searchbox.html', 'localtoc.html', 'sourcelink.html']} # Additional templates that should be rendered to pages, maps page names to # template names. diff --git a/Documentation/asm-annotations.rst b/Documentation/core-api/asm-annotations.rst index a64f2ca469d4..bc514ed59887 100644 --- a/Documentation/asm-annotations.rst +++ b/Documentation/core-api/asm-annotations.rst @@ -43,10 +43,11 @@ annotated objects like this, tools can be run on them to generate more useful information. In particular, on properly annotated objects, ``objtool`` can be run to check and fix the object if needed. Currently, ``objtool`` can report missing frame pointer setup/destruction in functions. It can also -automatically generate annotations for :doc:`ORC unwinder <x86/orc-unwinder>` +automatically generate annotations for the ORC unwinder +(Documentation/x86/orc-unwinder.rst) for most code. Both of these are especially important to support reliable -stack traces which are in turn necessary for :doc:`Kernel live patching -<livepatch/livepatch>`. +stack traces which are in turn necessary for kernel live patching +(Documentation/livepatch/livepatch.rst). Caveat and Discussion --------------------- diff --git a/Documentation/core-api/cpu_hotplug.rst b/Documentation/core-api/cpu_hotplug.rst index c6f4ba2fb32d..f75778d37488 100644 --- a/Documentation/core-api/cpu_hotplug.rst +++ b/Documentation/core-api/cpu_hotplug.rst @@ -560,7 +560,7 @@ available: * cpuhp_state_remove_instance(state, node) * cpuhp_state_remove_instance_nocalls(state, node) -The arguments are the same as for the the cpuhp_state_add_instance*() +The arguments are the same as for the cpuhp_state_add_instance*() variants above. The functions differ in the way how the installed callbacks are treated: diff --git a/Documentation/core-api/index.rst b/Documentation/core-api/index.rst index dc95df462eea..b0e7b4771fff 100644 --- a/Documentation/core-api/index.rst +++ b/Documentation/core-api/index.rst @@ -23,6 +23,7 @@ it. printk-formats printk-index symbol-namespaces + asm-annotations Data structures and low-level utilities ======================================= @@ -44,6 +45,8 @@ Library functionality that is used throughout the kernel. this_cpu_ops timekeeping errseq + wrappers/atomic_t + wrappers/atomic_bitops Low level entry and exit ======================== @@ -67,6 +70,7 @@ Documentation/locking/index.rst for more related documentation. local_ops padata ../RCU/index + wrappers/memory-barriers.rst Low-level hardware management ============================= diff --git a/Documentation/core-api/irq/irq-domain.rst b/Documentation/core-api/irq/irq-domain.rst index d30b4d0a9769..f88a6ee67a35 100644 --- a/Documentation/core-api/irq/irq-domain.rst +++ b/Documentation/core-api/irq/irq-domain.rst @@ -71,7 +71,7 @@ variety of methods: Note that irq domain lookups must happen in contexts that are compatible with a RCU read-side critical section. -The irq_create_mapping() function must be called *atleast once* +The irq_create_mapping() function must be called *at least once* before any call to irq_find_mapping(), lest the descriptor will not be allocated. diff --git a/Documentation/core-api/printk-formats.rst b/Documentation/core-api/printk-formats.rst index 5e89497ba314..dbe1aacc79d0 100644 --- a/Documentation/core-api/printk-formats.rst +++ b/Documentation/core-api/printk-formats.rst @@ -625,6 +625,16 @@ Examples:: %p4cc Y10 little-endian (0x20303159) %p4cc NV12 big-endian (0xb231564e) +Rust +---- + +:: + + %pA + +Only intended to be used from Rust code to format ``core::fmt::Arguments``. +Do *not* use it from C. + Thanks ====== diff --git a/Documentation/core-api/wrappers/atomic_bitops.rst b/Documentation/core-api/wrappers/atomic_bitops.rst new file mode 100644 index 000000000000..bf24e4081a8f --- /dev/null +++ b/Documentation/core-api/wrappers/atomic_bitops.rst @@ -0,0 +1,18 @@ +.. SPDX-License-Identifier: GPL-2.0 + This is a simple wrapper to bring atomic_bitops.txt into the RST world + until such a time as that file can be converted directly. + +============= +Atomic bitops +============= + +.. raw:: latex + + \footnotesize + +.. include:: ../../atomic_bitops.txt + :literal: + +.. raw:: latex + + \normalsize diff --git a/Documentation/core-api/wrappers/atomic_t.rst b/Documentation/core-api/wrappers/atomic_t.rst new file mode 100644 index 000000000000..ed109a964c77 --- /dev/null +++ b/Documentation/core-api/wrappers/atomic_t.rst @@ -0,0 +1,19 @@ +.. SPDX-License-Identifier: GPL-2.0 + This is a simple wrapper to bring atomic_t.txt into the RST world + until such a time as that file can be converted directly. + +============ +Atomic types +============ + +.. raw:: latex + + \footnotesize + +.. include:: ../../atomic_t.txt + :literal: + +.. raw:: latex + + \normalsize + diff --git a/Documentation/core-api/wrappers/memory-barriers.rst b/Documentation/core-api/wrappers/memory-barriers.rst new file mode 100644 index 000000000000..532460b5e3eb --- /dev/null +++ b/Documentation/core-api/wrappers/memory-barriers.rst @@ -0,0 +1,18 @@ +.. SPDX-License-Identifier: GPL-2.0 + This is a simple wrapper to bring memory-barriers.txt into the RST world + until such a time as that file can be converted directly. + +============================ +Linux kernel memory barriers +============================ + +.. raw:: latex + + \footnotesize + +.. include:: ../../memory-barriers.txt + :literal: + +.. raw:: latex + + \normalsize diff --git a/Documentation/devicetree/bindings/arm/amlogic/amlogic,meson-gx-ao-secure.yaml b/Documentation/devicetree/bindings/arm/amlogic/amlogic,meson-gx-ao-secure.yaml index 6cc74523ebfd..1748f1605cc7 100644 --- a/Documentation/devicetree/bindings/arm/amlogic/amlogic,meson-gx-ao-secure.yaml +++ b/Documentation/devicetree/bindings/arm/amlogic/amlogic,meson-gx-ao-secure.yaml @@ -8,7 +8,7 @@ $schema: "http://devicetree.org/meta-schemas/core.yaml#" title: Amlogic Meson Firmware registers Interface maintainers: - - Neil Armstrong <narmstrong@baylibre.com> + - Neil Armstrong <neil.armstrong@linaro.org> description: | The Meson SoCs have a register bank with status and data shared with the diff --git a/Documentation/devicetree/bindings/arm/mediatek/mediatek,mt7622-wed.yaml b/Documentation/devicetree/bindings/arm/mediatek/mediatek,mt7622-wed.yaml index 787d6673f952..84fb0a146b6e 100644 --- a/Documentation/devicetree/bindings/arm/mediatek/mediatek,mt7622-wed.yaml +++ b/Documentation/devicetree/bindings/arm/mediatek/mediatek,mt7622-wed.yaml @@ -20,6 +20,7 @@ properties: items: - enum: - mediatek,mt7622-wed + - mediatek,mt7986-wed - const: syscon reg: diff --git a/Documentation/devicetree/bindings/arm/mediatek/mediatek,mt7986-wed-pcie.yaml b/Documentation/devicetree/bindings/arm/mediatek/mediatek,mt7986-wed-pcie.yaml new file mode 100644 index 000000000000..96221f51c1c3 --- /dev/null +++ b/Documentation/devicetree/bindings/arm/mediatek/mediatek,mt7986-wed-pcie.yaml @@ -0,0 +1,43 @@ +# SPDX-License-Identifier: (GPL-2.0 OR BSD-2-Clause) +%YAML 1.2 +--- +$id: "http://devicetree.org/schemas/arm/mediatek/mediatek,mt7986-wed-pcie.yaml#" +$schema: "http://devicetree.org/meta-schemas/core.yaml#" + +title: MediaTek PCIE WED Controller for MT7986 + +maintainers: + - Lorenzo Bianconi <lorenzo@kernel.org> + - Felix Fietkau <nbd@nbd.name> + +description: + The mediatek WED PCIE provides a configuration interface for PCIE + controller on MT7986 soc. + +properties: + compatible: + items: + - enum: + - mediatek,mt7986-wed-pcie + - const: syscon + + reg: + maxItems: 1 + +required: + - compatible + - reg + +additionalProperties: false + +examples: + - | + soc { + #address-cells = <2>; + #size-cells = <2>; + wed_pcie: wed-pcie@10003000 { + compatible = "mediatek,mt7986-wed-pcie", + "syscon"; + reg = <0 0x10003000 0 0x10>; + }; + }; diff --git a/Documentation/devicetree/bindings/display/amlogic,meson-dw-hdmi.yaml b/Documentation/devicetree/bindings/display/amlogic,meson-dw-hdmi.yaml index 2e208d2fc98f..7cdffdb131ac 100644 --- a/Documentation/devicetree/bindings/display/amlogic,meson-dw-hdmi.yaml +++ b/Documentation/devicetree/bindings/display/amlogic,meson-dw-hdmi.yaml @@ -8,7 +8,7 @@ $schema: "http://devicetree.org/meta-schemas/core.yaml#" title: Amlogic specific extensions to the Synopsys Designware HDMI Controller maintainers: - - Neil Armstrong <narmstrong@baylibre.com> + - Neil Armstrong <neil.armstrong@linaro.org> allOf: - $ref: /schemas/sound/name-prefix.yaml# diff --git a/Documentation/devicetree/bindings/display/amlogic,meson-vpu.yaml b/Documentation/devicetree/bindings/display/amlogic,meson-vpu.yaml index 047fd69e0377..6655a93b1874 100644 --- a/Documentation/devicetree/bindings/display/amlogic,meson-vpu.yaml +++ b/Documentation/devicetree/bindings/display/amlogic,meson-vpu.yaml @@ -8,7 +8,7 @@ $schema: "http://devicetree.org/meta-schemas/core.yaml#" title: Amlogic Meson Display Controller maintainers: - - Neil Armstrong <narmstrong@baylibre.com> + - Neil Armstrong <neil.armstrong@linaro.org> description: | The Amlogic Meson Display controller is composed of several components diff --git a/Documentation/devicetree/bindings/display/bridge/analogix,anx7814.yaml b/Documentation/devicetree/bindings/display/bridge/analogix,anx7814.yaml index bce96b5b0db0..4a5e5d9d6f90 100644 --- a/Documentation/devicetree/bindings/display/bridge/analogix,anx7814.yaml +++ b/Documentation/devicetree/bindings/display/bridge/analogix,anx7814.yaml @@ -8,7 +8,7 @@ title: Analogix ANX7814 SlimPort (Full-HD Transmitter) maintainers: - Andrzej Hajda <andrzej.hajda@intel.com> - - Neil Armstrong <narmstrong@baylibre.com> + - Neil Armstrong <neil.armstrong@linaro.org> - Robert Foss <robert.foss@linaro.org> properties: diff --git a/Documentation/devicetree/bindings/display/bridge/chipone,icn6211.yaml b/Documentation/devicetree/bindings/display/bridge/chipone,icn6211.yaml index 4f0b7c71313c..5fb54375aeb6 100644 --- a/Documentation/devicetree/bindings/display/bridge/chipone,icn6211.yaml +++ b/Documentation/devicetree/bindings/display/bridge/chipone,icn6211.yaml @@ -24,6 +24,15 @@ properties: maxItems: 1 description: virtual channel number of a DSI peripheral + clock-names: + const: refclk + + clocks: + maxItems: 1 + description: | + Optional external clock connected to REF_CLK input. + The clock rate must be in 10..154 MHz range. + enable-gpios: description: Bridge EN pin, chip is reset when EN is low. diff --git a/Documentation/devicetree/bindings/display/bridge/ite,it66121.yaml b/Documentation/devicetree/bindings/display/bridge/ite,it66121.yaml index c6e81f532215..1b2185be92cd 100644 --- a/Documentation/devicetree/bindings/display/bridge/ite,it66121.yaml +++ b/Documentation/devicetree/bindings/display/bridge/ite,it66121.yaml @@ -8,7 +8,7 @@ title: ITE it66121 HDMI bridge Device Tree Bindings maintainers: - Phong LE <ple@baylibre.com> - - Neil Armstrong <narmstrong@baylibre.com> + - Neil Armstrong <neil.armstrong@linaro.org> description: | The IT66121 is a high-performance and low-power single channel HDMI diff --git a/Documentation/devicetree/bindings/display/bridge/renesas,dw-hdmi.yaml b/Documentation/devicetree/bindings/display/bridge/renesas,dw-hdmi.yaml index 0c9785c8db51..e3ec697f89e7 100644 --- a/Documentation/devicetree/bindings/display/bridge/renesas,dw-hdmi.yaml +++ b/Documentation/devicetree/bindings/display/bridge/renesas,dw-hdmi.yaml @@ -38,6 +38,9 @@ properties: clock-names: maxItems: 2 + resets: + maxItems: 1 + ports: $ref: /schemas/graph.yaml#/properties/ports @@ -67,6 +70,7 @@ required: - reg - clocks - clock-names + - resets - interrupts - ports @@ -85,6 +89,7 @@ examples: clocks = <&cpg CPG_CORE R8A7795_CLK_S0D4>, <&cpg CPG_MOD 729>; clock-names = "iahb", "isfr"; power-domains = <&sysc R8A7795_PD_ALWAYS_ON>; + resets = <&cpg 729>; ports { #address-cells = <1>; diff --git a/Documentation/devicetree/bindings/display/ingenic,lcd.yaml b/Documentation/devicetree/bindings/display/ingenic,lcd.yaml index 0049010b37ca..c0bb02fb49f4 100644 --- a/Documentation/devicetree/bindings/display/ingenic,lcd.yaml +++ b/Documentation/devicetree/bindings/display/ingenic,lcd.yaml @@ -17,6 +17,8 @@ properties: enum: - ingenic,jz4740-lcd - ingenic,jz4725b-lcd + - ingenic,jz4760-lcd + - ingenic,jz4760b-lcd - ingenic,jz4770-lcd - ingenic,jz4780-lcd diff --git a/Documentation/devicetree/bindings/display/mediatek/mediatek,dp.yaml b/Documentation/devicetree/bindings/display/mediatek/mediatek,dp.yaml new file mode 100644 index 000000000000..ff781f2174a0 --- /dev/null +++ b/Documentation/devicetree/bindings/display/mediatek/mediatek,dp.yaml @@ -0,0 +1,116 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/display/mediatek/mediatek,dp.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: MediaTek Display Port Controller + +maintainers: + - Chun-Kuang Hu <chunkuang.hu@kernel.org> + - Jitao shi <jitao.shi@mediatek.com> + +description: | + MediaTek DP and eDP are different hardwares and there are some features + which are not supported for eDP. For example, audio is not supported for + eDP. Therefore, we need to use two different compatibles to describe them. + In addition, We just need to enable the power domain of DP, so the clock + of DP is generated by itself and we are not using other PLL to generate + clocks. + +properties: + compatible: + enum: + - mediatek,mt8195-dp-tx + - mediatek,mt8195-edp-tx + + reg: + maxItems: 1 + + nvmem-cells: + maxItems: 1 + description: efuse data for display port calibration + + nvmem-cell-names: + const: dp_calibration_data + + power-domains: + maxItems: 1 + + interrupts: + maxItems: 1 + + ports: + $ref: /schemas/graph.yaml#/properties/ports + properties: + port@0: + $ref: /schemas/graph.yaml#/properties/port + description: Input endpoint of the controller, usually dp_intf + + port@1: + $ref: /schemas/graph.yaml#/$defs/port-base + unevaluatedProperties: false + description: Output endpoint of the controller + properties: + endpoint: + $ref: /schemas/media/video-interfaces.yaml# + unevaluatedProperties: false + properties: + data-lanes: + description: | + number of lanes supported by the hardware. + The possible values: + 0 - For 1 lane enabled in IP. + 0 1 - For 2 lanes enabled in IP. + 0 1 2 3 - For 4 lanes enabled in IP. + minItems: 1 + maxItems: 4 + required: + - data-lanes + + required: + - port@0 + - port@1 + + max-linkrate-mhz: + enum: [ 1620, 2700, 5400, 8100 ] + description: maximum link rate supported by the hardware. + +required: + - compatible + - reg + - interrupts + - ports + - max-linkrate-mhz + +additionalProperties: false + +examples: + - | + #include <dt-bindings/interrupt-controller/arm-gic.h> + #include <dt-bindings/power/mt8195-power.h> + dptx@1c600000 { + compatible = "mediatek,mt8195-dp-tx"; + reg = <0x1c600000 0x8000>; + power-domains = <&spm MT8195_POWER_DOMAIN_DP_TX>; + interrupts = <GIC_SPI 458 IRQ_TYPE_LEVEL_HIGH 0>; + max-linkrate-mhz = <8100>; + + ports { + #address-cells = <1>; + #size-cells = <0>; + + port@0 { + reg = <0>; + dptx_in: endpoint { + remote-endpoint = <&dp_intf0_out>; + }; + }; + port@1 { + reg = <1>; + dptx_out: endpoint { + data-lanes = <0 1 2 3>; + }; + }; + }; + }; diff --git a/Documentation/devicetree/bindings/display/msm/dp-controller.yaml b/Documentation/devicetree/bindings/display/msm/dp-controller.yaml index 94bc6e1b6451..f2515af8256f 100644 --- a/Documentation/devicetree/bindings/display/msm/dp-controller.yaml +++ b/Documentation/devicetree/bindings/display/msm/dp-controller.yaml @@ -24,6 +24,7 @@ properties: - qcom,sm8350-dp reg: + minItems: 4 items: - description: ahb register block - description: aux register block @@ -70,14 +71,28 @@ properties: operating-points-v2: maxItems: 1 + opp-table: true + power-domains: maxItems: 1 + aux-bus: + $ref: /schemas/display/dp-aux-bus.yaml# + + data-lanes: + $ref: /schemas/types.yaml#/definitions/uint32-array + minItems: 1 + maxItems: 4 + items: + maximum: 3 + "#sound-dai-cells": const: 0 - vdda-0p9-supply: true - vdda-1p2-supply: true + vdda-0p9-supply: + deprecated: true + vdda-1p2-supply: + deprecated: true ports: $ref: /schemas/graph.yaml#/properties/ports @@ -98,10 +113,33 @@ required: - clock-names - phys - phy-names - - "#sound-dai-cells" - power-domains - ports +allOf: + # AUX BUS does not exist on DP controllers + # Audio output also is present only on DP output + # p1 regions is present on DP, but not on eDP + - if: + properties: + compatible: + contains: + enum: + - qcom,sc7280-edp + - qcom,sc8180x-edp + then: + properties: + "#sound-dai-cells": false + reg: + maxItems: 4 + else: + properties: + aux-bus: false + reg: + minItems: 5 + required: + - "#sound-dai-cells" + additionalProperties: false examples: @@ -140,9 +178,6 @@ examples: power-domains = <&rpmhpd SC7180_CX>; - vdda-0p9-supply = <&vdda_usb_ss_dp_core>; - vdda-1p2-supply = <&vdda_usb_ss_dp_1p2>; - ports { #address-cells = <1>; #size-cells = <0>; diff --git a/Documentation/devicetree/bindings/display/msm/dpu-msm8998.yaml b/Documentation/devicetree/bindings/display/msm/dpu-msm8998.yaml index 2df64afb76e6..253665c693e6 100644 --- a/Documentation/devicetree/bindings/display/msm/dpu-msm8998.yaml +++ b/Documentation/devicetree/bindings/display/msm/dpu-msm8998.yaml @@ -62,6 +62,7 @@ patternProperties: "^display-controller@[0-9a-f]+$": type: object description: Node containing the properties of DPU. + additionalProperties: false properties: compatible: @@ -105,6 +106,9 @@ patternProperties: maxItems: 1 operating-points-v2: true + opp-table: + type: object + ports: $ref: /schemas/graph.yaml#/properties/ports description: | diff --git a/Documentation/devicetree/bindings/display/msm/dpu-qcm2290.yaml b/Documentation/devicetree/bindings/display/msm/dpu-qcm2290.yaml index 734d14de966d..c5824e1d2382 100644 --- a/Documentation/devicetree/bindings/display/msm/dpu-qcm2290.yaml +++ b/Documentation/devicetree/bindings/display/msm/dpu-qcm2290.yaml @@ -74,6 +74,7 @@ patternProperties: "^display-controller@[0-9a-f]+$": type: object description: Node containing the properties of DPU. + additionalProperties: false properties: compatible: @@ -113,6 +114,8 @@ patternProperties: maxItems: 1 operating-points-v2: true + opp-table: + type: object ports: $ref: /schemas/graph.yaml#/properties/ports diff --git a/Documentation/devicetree/bindings/display/msm/dpu-sc7180.yaml b/Documentation/devicetree/bindings/display/msm/dpu-sc7180.yaml index d3c3e4b07897..4890bc25f3fd 100644 --- a/Documentation/devicetree/bindings/display/msm/dpu-sc7180.yaml +++ b/Documentation/devicetree/bindings/display/msm/dpu-sc7180.yaml @@ -73,6 +73,7 @@ patternProperties: "^display-controller@[0-9a-f]+$": type: object description: Node containing the properties of DPU. + additionalProperties: false properties: compatible: @@ -114,6 +115,8 @@ patternProperties: maxItems: 1 operating-points-v2: true + opp-table: + type: object ports: $ref: /schemas/graph.yaml#/properties/ports diff --git a/Documentation/devicetree/bindings/display/msm/dpu-sc7280.yaml b/Documentation/devicetree/bindings/display/msm/dpu-sc7280.yaml index f427eec3d3a4..584d646021d5 100644 --- a/Documentation/devicetree/bindings/display/msm/dpu-sc7280.yaml +++ b/Documentation/devicetree/bindings/display/msm/dpu-sc7280.yaml @@ -72,6 +72,7 @@ patternProperties: "^display-controller@[0-9a-f]+$": type: object description: Node containing the properties of DPU. + additionalProperties: false properties: compatible: @@ -112,6 +113,8 @@ patternProperties: maxItems: 1 operating-points-v2: true + opp-table: + type: object ports: $ref: /schemas/graph.yaml#/properties/ports diff --git a/Documentation/devicetree/bindings/display/msm/dpu-sdm845.yaml b/Documentation/devicetree/bindings/display/msm/dpu-sdm845.yaml index 2bb8896beffc..7d1037373175 100644 --- a/Documentation/devicetree/bindings/display/msm/dpu-sdm845.yaml +++ b/Documentation/devicetree/bindings/display/msm/dpu-sdm845.yaml @@ -65,6 +65,7 @@ patternProperties: "^display-controller@[0-9a-f]+$": type: object description: Node containing the properties of DPU. + additionalProperties: false properties: compatible: @@ -102,6 +103,9 @@ patternProperties: maxItems: 1 operating-points-v2: true + opp-table: + type: object + ports: $ref: /schemas/graph.yaml#/properties/ports description: | diff --git a/Documentation/devicetree/bindings/display/msm/gmu.yaml b/Documentation/devicetree/bindings/display/msm/gmu.yaml index fe55611d2603..67fdeeabae0c 100644 --- a/Documentation/devicetree/bindings/display/msm/gmu.yaml +++ b/Documentation/devicetree/bindings/display/msm/gmu.yaml @@ -20,35 +20,24 @@ description: | properties: compatible: items: - - enum: - - qcom,adreno-gmu-630.2 + - pattern: '^qcom,adreno-gmu-6[0-9][0-9]\.[0-9]$' - const: qcom,adreno-gmu reg: - items: - - description: Core GMU registers - - description: GMU PDC registers - - description: GMU PDC sequence registers + minItems: 3 + maxItems: 4 reg-names: - items: - - const: gmu - - const: gmu_pdc - - const: gmu_pdc_seq + minItems: 3 + maxItems: 4 clocks: - items: - - description: GMU clock - - description: GPU CX clock - - description: GPU AXI clock - - description: GPU MEMNOC clock + minItems: 4 + maxItems: 7 clock-names: - items: - - const: gmu - - const: cxo - - const: axi - - const: memnoc + minItems: 4 + maxItems: 7 interrupts: items: @@ -76,6 +65,9 @@ properties: operating-points-v2: true + opp-table: + type: object + required: - compatible - reg @@ -91,6 +83,140 @@ required: additionalProperties: false +allOf: + - if: + properties: + compatible: + contains: + enum: + - qcom,adreno-gmu-618.0 + - qcom,adreno-gmu-630.2 + then: + properties: + reg: + items: + - description: Core GMU registers + - description: GMU PDC registers + - description: GMU PDC sequence registers + reg-names: + items: + - const: gmu + - const: gmu_pdc + - const: gmu_pdc_seq + clocks: + items: + - description: GMU clock + - description: GPU CX clock + - description: GPU AXI clock + - description: GPU MEMNOC clock + clock-names: + items: + - const: gmu + - const: cxo + - const: axi + - const: memnoc + + - if: + properties: + compatible: + contains: + enum: + - qcom,adreno-gmu-635.0 + then: + properties: + reg: + items: + - description: Core GMU registers + - description: Resource controller registers + - description: GMU PDC registers + reg-names: + items: + - const: gmu + - const: rscc + - const: gmu_pdc + clocks: + items: + - description: GMU clock + - description: GPU CX clock + - description: GPU AXI clock + - description: GPU MEMNOC clock + - description: GPU AHB clock + - description: GPU HUB CX clock + - description: GPU SMMU vote clock + clock-names: + items: + - const: gmu + - const: cxo + - const: axi + - const: memnoc + - const: ahb + - const: hub + - const: smmu_vote + + - if: + properties: + compatible: + contains: + enum: + - qcom,adreno-gmu-640.1 + then: + properties: + reg: + items: + - description: Core GMU registers + - description: GMU PDC registers + - description: GMU PDC sequence registers + reg-names: + items: + - const: gmu + - const: gmu_pdc + - const: gmu_pdc_seq + + - if: + properties: + compatible: + contains: + enum: + - qcom,adreno-gmu-650.2 + then: + properties: + reg: + items: + - description: Core GMU registers + - description: Resource controller registers + - description: GMU PDC registers + - description: GMU PDC sequence registers + reg-names: + items: + - const: gmu + - const: rscc + - const: gmu_pdc + - const: gmu_pdc_seq + + - if: + properties: + compatible: + contains: + enum: + - qcom,adreno-gmu-640.1 + - qcom,adreno-gmu-650.2 + then: + properties: + clocks: + items: + - description: GPU AHB clock + - description: GMU clock + - description: GPU CX clock + - description: GPU AXI clock + - description: GPU MEMNOC clock + clock-names: + items: + - const: ahb + - const: gmu + - const: cxo + - const: axi + - const: memnoc + examples: - | #include <dt-bindings/clock/qcom,gpucc-sdm845.h> diff --git a/Documentation/devicetree/bindings/display/msm/gpu.yaml b/Documentation/devicetree/bindings/display/msm/gpu.yaml index 3397bc31d087..346aabdccf7b 100644 --- a/Documentation/devicetree/bindings/display/msm/gpu.yaml +++ b/Documentation/devicetree/bindings/display/msm/gpu.yaml @@ -58,7 +58,8 @@ properties: - const: ocmem iommus: - maxItems: 1 + minItems: 1 + maxItems: 64 sram: $ref: /schemas/types.yaml#/definitions/phandle-array diff --git a/Documentation/devicetree/bindings/display/msm/mdp4.yaml b/Documentation/devicetree/bindings/display/msm/mdp4.yaml index f63f60fea27c..58c13f5277b6 100644 --- a/Documentation/devicetree/bindings/display/msm/mdp4.yaml +++ b/Documentation/devicetree/bindings/display/msm/mdp4.yaml @@ -36,7 +36,7 @@ properties: maxItems: 1 iommus: - maxItems: 1 + maxItems: 4 ports: $ref: /schemas/graph.yaml#/properties/ports diff --git a/Documentation/devicetree/bindings/display/panel/kingdisplay,kd035g6-54nt.yaml b/Documentation/devicetree/bindings/display/panel/kingdisplay,kd035g6-54nt.yaml index 2a2756d19681..b4be9bd8ddde 100644 --- a/Documentation/devicetree/bindings/display/panel/kingdisplay,kd035g6-54nt.yaml +++ b/Documentation/devicetree/bindings/display/panel/kingdisplay,kd035g6-54nt.yaml @@ -23,6 +23,8 @@ properties: reg: true reset-gpios: true + spi-3wire: true + required: - compatible - power-supply diff --git a/Documentation/devicetree/bindings/display/panel/leadtek,ltk035c5444t.yaml b/Documentation/devicetree/bindings/display/panel/leadtek,ltk035c5444t.yaml index 817a9bed7d5a..ebdca5f5a001 100644 --- a/Documentation/devicetree/bindings/display/panel/leadtek,ltk035c5444t.yaml +++ b/Documentation/devicetree/bindings/display/panel/leadtek,ltk035c5444t.yaml @@ -24,6 +24,8 @@ properties: reg: true reset-gpios: true + spi-3wire: true + required: - compatible - power-supply diff --git a/Documentation/devicetree/bindings/display/panel/panel-simple.yaml b/Documentation/devicetree/bindings/display/panel/panel-simple.yaml index bc8e9c0c1dc3..18241f4051d2 100644 --- a/Documentation/devicetree/bindings/display/panel/panel-simple.yaml +++ b/Documentation/devicetree/bindings/display/panel/panel-simple.yaml @@ -234,6 +234,8 @@ properties: - mitsubishi,aa070mc01-ca1 # Multi-Inno Technology Co.,Ltd MI0700S4T-6 7" 800x480 TFT Resistive Touch Module - multi-inno,mi0700s4t-6 + # Multi-Inno Technology Co.,Ltd MI0800FT-9 8" 800x600 TFT Resistive Touch Module + - multi-inno,mi0800ft-9 # Multi-Inno Technology Co.,Ltd MI1010AIT-1CP 10.1" 1280x800 LVDS IPS Cap Touch Mod. - multi-inno,mi1010ait-1cp # NEC LCD Technologies, Ltd. 12.1" WXGA (1280x800) LVDS TFT LCD panel @@ -280,6 +282,8 @@ properties: - samsung,atna33xc20 # Samsung 12.2" (2560x1600 pixels) TFT LCD panel - samsung,lsn122dl01-c01 + # Samsung Electronics 10.1" WXGA (1280x800) TFT LCD panel + - samsung,ltl101al01 # Samsung Electronics 10.1" WSVGA TFT LCD panel - samsung,ltn101nt05 # Samsung Electronics 14" WXGA (1366x768) TFT LCD panel diff --git a/Documentation/devicetree/bindings/display/panel/samsung,s6e63m0.yaml b/Documentation/devicetree/bindings/display/panel/samsung,s6e63m0.yaml index 940f7f88526f..6f1fc7469f07 100644 --- a/Documentation/devicetree/bindings/display/panel/samsung,s6e63m0.yaml +++ b/Documentation/devicetree/bindings/display/panel/samsung,s6e63m0.yaml @@ -24,6 +24,10 @@ properties: default-brightness: true max-brightness: true + spi-3wire: true + spi-cpha: true + spi-cpol: true + vdd3-supply: description: VDD regulator diff --git a/Documentation/devicetree/bindings/display/panel/sgd,gktw70sdae4se.yaml b/Documentation/devicetree/bindings/display/panel/sgd,gktw70sdae4se.yaml index 44e02decdf3a..2e75e3738ff0 100644 --- a/Documentation/devicetree/bindings/display/panel/sgd,gktw70sdae4se.yaml +++ b/Documentation/devicetree/bindings/display/panel/sgd,gktw70sdae4se.yaml @@ -7,7 +7,7 @@ $schema: http://devicetree.org/meta-schemas/core.yaml# title: Solomon Goldentek Display GKTW70SDAE4SE 7" WVGA LVDS Display Panel maintainers: - - Neil Armstrong <narmstrong@baylibre.com> + - Neil Armstrong <neil.armstrong@linaro.org> - Thierry Reding <thierry.reding@gmail.com> allOf: diff --git a/Documentation/devicetree/bindings/display/panel/sitronix,st7701.yaml b/Documentation/devicetree/bindings/display/panel/sitronix,st7701.yaml index 6dff59fe4be1..34d5e20c6cb3 100644 --- a/Documentation/devicetree/bindings/display/panel/sitronix,st7701.yaml +++ b/Documentation/devicetree/bindings/display/panel/sitronix,st7701.yaml @@ -17,6 +17,9 @@ description: | Techstar TS8550B is 480x854, 2-lane MIPI DSI LCD panel which has inbuilt ST7701 chip. + Densitron DMT028VGHMCMI-1A is 480x640, 2-lane MIPI DSI LCD panel + which has built-in ST7701 chip. + allOf: - $ref: panel-common.yaml# @@ -24,6 +27,7 @@ properties: compatible: items: - enum: + - densitron,dmt028vghmcmi-1a - techstar,ts8550b - const: sitronix,st7701 diff --git a/Documentation/devicetree/bindings/display/rockchip/dw_mipi_dsi_rockchip.txt b/Documentation/devicetree/bindings/display/rockchip/dw_mipi_dsi_rockchip.txt index 39792f051d2d..9a223df8530c 100644 --- a/Documentation/devicetree/bindings/display/rockchip/dw_mipi_dsi_rockchip.txt +++ b/Documentation/devicetree/bindings/display/rockchip/dw_mipi_dsi_rockchip.txt @@ -8,6 +8,7 @@ Required properties: "rockchip,px30-mipi-dsi", "snps,dw-mipi-dsi" "rockchip,rk3288-mipi-dsi", "snps,dw-mipi-dsi" "rockchip,rk3399-mipi-dsi", "snps,dw-mipi-dsi" + "rockchip,rk3568-mipi-dsi", "snps,dw-mipi-dsi" - reg: Represent the physical address range of the controller. - interrupts: Represent the controller's interrupt to the CPU(s). - clocks, clock-names: Phandles to the controller's pll reference diff --git a/Documentation/devicetree/bindings/dma/moxa,moxart-dma.txt b/Documentation/devicetree/bindings/dma/moxa,moxart-dma.txt index 8a9f3559335b..7e14e26676ec 100644 --- a/Documentation/devicetree/bindings/dma/moxa,moxart-dma.txt +++ b/Documentation/devicetree/bindings/dma/moxa,moxart-dma.txt @@ -34,8 +34,8 @@ Example: Use specific request line passing from dma For example, MMC request line is 5 - sdhci: sdhci@98e00000 { - compatible = "moxa,moxart-sdhci"; + mmc: mmc@98e00000 { + compatible = "moxa,moxart-mmc"; reg = <0x98e00000 0x5C>; interrupts = <5 0>; clocks = <&clk_apb>; diff --git a/Documentation/devicetree/bindings/dsp/fsl,dsp.yaml b/Documentation/devicetree/bindings/dsp/fsl,dsp.yaml index e66ef2da7879..9af40da5688e 100644 --- a/Documentation/devicetree/bindings/dsp/fsl,dsp.yaml +++ b/Documentation/devicetree/bindings/dsp/fsl,dsp.yaml @@ -20,6 +20,7 @@ properties: - fsl,imx8qxp-dsp - fsl,imx8qm-dsp - fsl,imx8mp-dsp + - fsl,imx8ulp-dsp - fsl,imx8qxp-hifi4 - fsl,imx8qm-hifi4 - fsl,imx8mp-hifi4 diff --git a/Documentation/devicetree/bindings/hwmon/adi,max31760.yaml b/Documentation/devicetree/bindings/hwmon/adi,max31760.yaml new file mode 100644 index 000000000000..9f2d08d7b978 --- /dev/null +++ b/Documentation/devicetree/bindings/hwmon/adi,max31760.yaml @@ -0,0 +1,42 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/hwmon/adi,max31760.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Analog Devices MAX31760 Fan-Speed Controller + +maintainers: + - Ibrahim Tilki <Ibrahim.Tilki@analog.com> + +description: | + Analog Devices MAX31760 Fan-Speed Controller + https://datasheets.maximintegrated.com/en/ds/MAX31760.pdf + +properties: + compatible: + enum: + - adi,max31760 + + reg: + description: I2C address of slave device. + minimum: 0x50 + maximum: 0x57 + +required: + - compatible + - reg + +additionalProperties: false + +examples: + - | + i2c { + #address-cells = <1>; + #size-cells = <0>; + + fan-controller@50 { + reg = <0x50>; + compatible = "adi,max31760"; + }; + }; diff --git a/Documentation/devicetree/bindings/hwmon/microchip,sparx5-temp.yaml b/Documentation/devicetree/bindings/hwmon/microchip,sparx5-temp.yaml index 76be625d5646..51e8619dbf3c 100644 --- a/Documentation/devicetree/bindings/hwmon/microchip,sparx5-temp.yaml +++ b/Documentation/devicetree/bindings/hwmon/microchip,sparx5-temp.yaml @@ -22,7 +22,7 @@ properties: clocks: items: - - description: AHB reference clock + - description: System reference clock '#thermal-sensor-cells': const: 0 @@ -40,5 +40,5 @@ examples: compatible = "microchip,sparx5-temp"; reg = <0x10508110 0xc>; #thermal-sensor-cells = <0>; - clocks = <&ahb_clk>; + clocks = <&sys_clk>; }; diff --git a/Documentation/devicetree/bindings/hwmon/moortec,mr75203.yaml b/Documentation/devicetree/bindings/hwmon/moortec,mr75203.yaml index b79f069a04c2..d0d549749208 100644 --- a/Documentation/devicetree/bindings/hwmon/moortec,mr75203.yaml +++ b/Documentation/devicetree/bindings/hwmon/moortec,mr75203.yaml @@ -9,6 +9,32 @@ title: Moortec Semiconductor MR75203 PVT Controller bindings maintainers: - Rahul Tanwar <rtanwar@maxlinear.com> +description: | + A Moortec PVT (Process, Voltage, Temperature) monitoring logic design can + include many different units. + Such a design will usually consists of several Moortec's embedded analog IPs, + and a single Moortec controller (mr75203) to configure and control the IPs. + + Some of the Moortec's analog hard IPs that can be used in a design: + *) Temperature Sensor (TS) - used to monitor core temperature (e.g. mr74137). + *) Voltage Monitor (VM) - used to monitor voltage levels (e.g. mr74138). + *) Process Detector (PD) - used to assess silicon speed (e.g. mr74139). + *) Delay Chain - ring oscillator connected to the PD, used to measure IO + based transistors (e.g. mr76008 ring oscillator at 1.1V, mr76007 ring + oscillator at 1.8V). + *) Pre Scaler - provides divide-by-X scaling of input voltage, which can then + be presented for VM for measurement within its range (e.g. mr76006 - + divide by 2 pre-scaler). + + TS, VM & PD also include a digital interface, which consists of configuration + inputs and measurement outputs. + + Some of the units have number of series, each series can have slightly + different characteristics. + + The mr75203 binding describes configuration for the controller unit, but also + for some of the analog IPs. + properties: compatible: const: moortec,mr75203 @@ -44,13 +70,76 @@ properties: "#thermal-sensor-cells": const: 1 + moortec,vm-active-channels: + description: + Defines the number of channels per VM that are actually used and are + connected to some input source. + Maximum number of items - number of VMs. + Maximum value of each item - number of channels. + Minimum value of each item - 0 (which means entire VM sensor is not used). + $ref: /schemas/types.yaml#/definitions/uint8-array + + moortec,vm-pre-scaler-x2: + description: + Defines the channels that use a mr76006 pre-scaler to divide the input + source by 2. + The pre-scaler is used for input sources that exceed the VM input range. + The driver uses this information to present to the user with the actual + value of the voltage source. + For channels that are not listed, no pre-scaler is assumed. + Maximum number of items - total number of channels in all VMs. + Each channel should not appear more than once. + $ref: /schemas/types.yaml#/definitions/uint8-array + + moortec,ts-series: + description: + Definition of the temperature equation and coefficients that shall be + used to convert the digital output to value in milli-Celsius. + minimum: 5 + maximum: 6 + default: 5 + $ref: /schemas/types.yaml#/definitions/uint32 + + moortec,ts-coeff-g: + description: + G coefficient for temperature equation. + Default for series 5 = 60000 + Default for series 6 = 57400 + multipleOf: 1000 + minimum: 1000 + $ref: /schemas/types.yaml#/definitions/uint32 + + moortec,ts-coeff-h: + description: + H coefficient for temperature equation. + Default for series 5 = 200000 + Default for series 6 = 249400 + multipleOf: 1000 + minimum: 1000 + $ref: /schemas/types.yaml#/definitions/uint32 + + moortec,ts-coeff-cal5: + description: + cal5 coefficient for temperature equation. + Default for series 5 = 4094 + Default for series 6 = 4096 + minimum: 1 + $ref: /schemas/types.yaml#/definitions/uint32 + + moortec,ts-coeff-j: + description: + J coefficient for temperature equation. + Default for series 5 = -100 + Default for series 6 = 0 + multipleOf: 1000 + maximum: 0 + $ref: /schemas/types.yaml#/definitions/int32 + required: - compatible - reg - reg-names - - intel,vm-map - clocks - - resets - "#thermal-sensor-cells" additionalProperties: false @@ -67,5 +156,9 @@ examples: intel,vm-map = [03 01 04 ff ff]; clocks = <&osc0>; resets = <&rcu0 0x40 7>; + moortec,vm-active-channels = /bits/ 8 <0x10 0x05>; + moortec,vm-pre-scaler-x2 = /bits/ 8 <5 6 20>; + moortec,ts-coeff-g = <61400>; + moortec,ts-coeff-h = <253700>; #thermal-sensor-cells = <1>; }; diff --git a/Documentation/devicetree/bindings/hwmon/sensirion,shtc1.yaml b/Documentation/devicetree/bindings/hwmon/sensirion,shtc1.yaml index 7d49478d9668..159238efa9ed 100644 --- a/Documentation/devicetree/bindings/hwmon/sensirion,shtc1.yaml +++ b/Documentation/devicetree/bindings/hwmon/sensirion,shtc1.yaml @@ -10,7 +10,7 @@ maintainers: - Christopher Ruehl chris.ruehl@gtsys.com.hk description: | - The SHTC1, SHTW1 and SHTC3 are digital humidity and temperature sensor + The SHTC1, SHTW1 and SHTC3 are digital humidity and temperature sensors designed especially for battery-driven high-volume consumer electronics applications. For further information refere to Documentation/hwmon/shtc1.rst @@ -31,13 +31,13 @@ properties: sensirion,blocking-io: $ref: /schemas/types.yaml#/definitions/flag description: - If set, the driver hold the i2c bus until measurement is finished. + If set, the driver holds the i2c bus until the measurement is finished. sensirion,low-precision: $ref: /schemas/types.yaml#/definitions/flag description: - If set, the sensor aquire data with low precision (not recommended). - The driver aquire data with high precision by default. + If set, the sensor acquires data with low precision (not recommended). + The driver acquires data with high precision by default. required: - compatible diff --git a/Documentation/devicetree/bindings/i2c/amlogic,meson6-i2c.yaml b/Documentation/devicetree/bindings/i2c/amlogic,meson6-i2c.yaml index 6ecb0270d88d..199a354ccb97 100644 --- a/Documentation/devicetree/bindings/i2c/amlogic,meson6-i2c.yaml +++ b/Documentation/devicetree/bindings/i2c/amlogic,meson6-i2c.yaml @@ -8,7 +8,7 @@ $schema: "http://devicetree.org/meta-schemas/core.yaml#" title: Amlogic Meson I2C Controller maintainers: - - Neil Armstrong <narmstrong@baylibre.com> + - Neil Armstrong <neil.armstrong@linaro.org> - Beniamino Galvani <b.galvani@gmail.com> allOf: diff --git a/Documentation/devicetree/bindings/i2c/i2c-imx-lpi2c.yaml b/Documentation/devicetree/bindings/i2c/i2c-imx-lpi2c.yaml index 529bea56d324..4656f5112b84 100644 --- a/Documentation/devicetree/bindings/i2c/i2c-imx-lpi2c.yaml +++ b/Documentation/devicetree/bindings/i2c/i2c-imx-lpi2c.yaml @@ -23,6 +23,7 @@ properties: - fsl,imx8dxl-lpi2c - fsl,imx8qm-lpi2c - fsl,imx8ulp-lpi2c + - fsl,imx93-lpi2c - const: fsl,imx7ulp-lpi2c reg: @@ -37,10 +38,22 @@ properties: clock-frequency: true clock-names: - maxItems: 1 + items: + - const: per + - const: ipg clocks: - maxItems: 1 + maxItems: 2 + + dmas: + items: + - description: DMA controller phandle and request line for TX + - description: DMA controller phandle and request line for RX + + dma-names: + items: + - const: tx + - const: rx power-domains: maxItems: 1 @@ -63,5 +76,6 @@ examples: reg = <0x40A50000 0x10000>; interrupt-parent = <&intc>; interrupts = <GIC_SPI 37 IRQ_TYPE_LEVEL_HIGH>; - clocks = <&clks IMX7ULP_CLK_LPI2C7>; + clocks = <&clks IMX7ULP_CLK_LPI2C7>, + <&clks IMX7ULP_CLK_NIC1_BUS_DIV>; }; diff --git a/Documentation/devicetree/bindings/i2c/i2c-imx.yaml b/Documentation/devicetree/bindings/i2c/i2c-imx.yaml index 01720e338b4c..85ee1282d6d2 100644 --- a/Documentation/devicetree/bindings/i2c/i2c-imx.yaml +++ b/Documentation/devicetree/bindings/i2c/i2c-imx.yaml @@ -19,6 +19,17 @@ properties: - const: fsl,imx21-i2c - const: fsl,vf610-i2c - items: + - enum: + - fsl,ls1012a-i2c + - fsl,ls1021a-i2c + - fsl,ls1028a-i2c + - fsl,ls1043a-i2c + - fsl,ls1046a-i2c + - fsl,ls1088a-i2c + - fsl,ls208xa-i2c + - fsl,lx2160a-i2c + - const: fsl,vf610-i2c + - items: - const: fsl,imx35-i2c - const: fsl,imx1-i2c - items: diff --git a/Documentation/devicetree/bindings/i2c/i2c-rk3x.yaml b/Documentation/devicetree/bindings/i2c/i2c-rk3x.yaml index ee9f8b91d2e2..82b9d6682297 100644 --- a/Documentation/devicetree/bindings/i2c/i2c-rk3x.yaml +++ b/Documentation/devicetree/bindings/i2c/i2c-rk3x.yaml @@ -29,6 +29,7 @@ properties: - items: - enum: - rockchip,rk3036-i2c + - rockchip,rk3128-i2c - rockchip,rk3368-i2c - const: rockchip,rk3288-i2c - items: diff --git a/Documentation/devicetree/bindings/i2c/marvell,mv64xxx-i2c.yaml b/Documentation/devicetree/bindings/i2c/marvell,mv64xxx-i2c.yaml index 0ec033e48830..63d665a4f9bb 100644 --- a/Documentation/devicetree/bindings/i2c/marvell,mv64xxx-i2c.yaml +++ b/Documentation/devicetree/bindings/i2c/marvell,mv64xxx-i2c.yaml @@ -66,6 +66,19 @@ properties: resets: maxItems: 1 + dmas: + items: + - description: RX DMA Channel + - description: TX DMA Channel + + dma-names: + items: + - const: rx + - const: tx + +dependencies: + dmas: [ dma-names ] + required: - compatible - reg diff --git a/Documentation/devicetree/bindings/i2c/mellanox,i2c-mlxbf.yaml b/Documentation/devicetree/bindings/i2c/mellanox,i2c-mlxbf.yaml deleted file mode 100644 index 93198d5d43a6..000000000000 --- a/Documentation/devicetree/bindings/i2c/mellanox,i2c-mlxbf.yaml +++ /dev/null @@ -1,77 +0,0 @@ -# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) -%YAML 1.2 ---- -$id: http://devicetree.org/schemas/i2c/mellanox,i2c-mlxbf.yaml# -$schema: http://devicetree.org/meta-schemas/core.yaml# - -title: Mellanox I2C SMBus on BlueField SoCs - -maintainers: - - Khalil Blaiech <kblaiech@nvidia.com> - -allOf: - - $ref: /schemas/i2c/i2c-controller.yaml# - -properties: - compatible: - enum: - - mellanox,i2c-mlxbf1 - - mellanox,i2c-mlxbf2 - - reg: - minItems: 3 - items: - - description: Smbus block registers - - description: Cause master registers - - description: Cause slave registers - - description: Cause coalesce registers - - interrupts: - maxItems: 1 - - clock-frequency: - enum: [ 100000, 400000, 1000000 ] - description: - bus frequency used to configure timing registers; - The frequency is expressed in Hz. Default is 100000. - -required: - - compatible - - reg - - interrupts - -unevaluatedProperties: false - -if: - properties: - compatible: - contains: - enum: - - mellanox,i2c-mlxbf1 - -then: - properties: - reg: - maxItems: 3 - -examples: - - | - i2c@2804000 { - compatible = "mellanox,i2c-mlxbf1"; - reg = <0x02804000 0x800>, - <0x02801200 0x020>, - <0x02801260 0x020>; - interrupts = <57>; - clock-frequency = <100000>; - }; - - - | - i2c@2808800 { - compatible = "mellanox,i2c-mlxbf2"; - reg = <0x02808800 0x600>, - <0x02808e00 0x020>, - <0x02808e20 0x020>, - <0x02808e40 0x010>; - interrupts = <57>; - clock-frequency = <400000>; - }; diff --git a/Documentation/devicetree/bindings/i2c/qcom,i2c-cci.yaml b/Documentation/devicetree/bindings/i2c/qcom,i2c-cci.yaml index 90c9e401229e..e51a85848d6e 100644 --- a/Documentation/devicetree/bindings/i2c/qcom,i2c-cci.yaml +++ b/Documentation/devicetree/bindings/i2c/qcom,i2c-cci.yaml @@ -126,6 +126,7 @@ allOf: contains: enum: - qcom,sm8250-cci + - qcom,sm8450-cci then: properties: clocks: diff --git a/Documentation/devicetree/bindings/i2c/renesas,rcar-i2c.yaml b/Documentation/devicetree/bindings/i2c/renesas,rcar-i2c.yaml index f9929578c761..c4ace5585e1e 100644 --- a/Documentation/devicetree/bindings/i2c/renesas,rcar-i2c.yaml +++ b/Documentation/devicetree/bindings/i2c/renesas,rcar-i2c.yaml @@ -52,6 +52,7 @@ properties: - enum: - renesas,i2c-r8a779a0 # R-Car V3U - renesas,i2c-r8a779f0 # R-Car S4-8 + - renesas,i2c-r8a779g0 # R-Car V4H - const: renesas,rcar-gen4-i2c # R-Car Gen4 reg: diff --git a/Documentation/devicetree/bindings/i2c/renesas,riic.yaml b/Documentation/devicetree/bindings/i2c/renesas,riic.yaml index 2f315489aaae..d3c0d5c427ac 100644 --- a/Documentation/devicetree/bindings/i2c/renesas,riic.yaml +++ b/Documentation/devicetree/bindings/i2c/renesas,riic.yaml @@ -60,6 +60,9 @@ properties: power-domains: maxItems: 1 + resets: + maxItems: 1 + required: - compatible - reg diff --git a/Documentation/devicetree/bindings/i2c/st,stm32-i2c.yaml b/Documentation/devicetree/bindings/i2c/st,stm32-i2c.yaml index a41588763786..bf396e9466aa 100644 --- a/Documentation/devicetree/bindings/i2c/st,stm32-i2c.yaml +++ b/Documentation/devicetree/bindings/i2c/st,stm32-i2c.yaml @@ -57,6 +57,11 @@ properties: - description: interrupt ID for I2C event - description: interrupt ID for I2C error + interrupt-names: + items: + - const: event + - const: error + resets: maxItems: 1 @@ -92,6 +97,8 @@ properties: - description: register offset within syscfg - description: register bitmask for FMP bit + wakeup-source: true + required: - compatible - reg diff --git a/Documentation/devicetree/bindings/iio/gyroscope/bosch,bmg160.yaml b/Documentation/devicetree/bindings/iio/gyroscope/bosch,bmg160.yaml index b6bbc312a7cf..1414ba9977c1 100644 --- a/Documentation/devicetree/bindings/iio/gyroscope/bosch,bmg160.yaml +++ b/Documentation/devicetree/bindings/iio/gyroscope/bosch,bmg160.yaml @@ -24,8 +24,10 @@ properties: interrupts: minItems: 1 + maxItems: 2 description: Should be configured with type IRQ_TYPE_EDGE_RISING. + If two interrupts are provided, expected order is INT1 and INT2. required: - compatible diff --git a/Documentation/devicetree/bindings/input/touchscreen/goodix.yaml b/Documentation/devicetree/bindings/input/touchscreen/goodix.yaml index 93f2ce3130ae..19ac9da421df 100644 --- a/Documentation/devicetree/bindings/input/touchscreen/goodix.yaml +++ b/Documentation/devicetree/bindings/input/touchscreen/goodix.yaml @@ -16,6 +16,7 @@ properties: compatible: enum: - goodix,gt1151 + - goodix,gt1158 - goodix,gt5663 - goodix,gt5688 - goodix,gt911 diff --git a/Documentation/devicetree/bindings/interconnect/fsl,imx8m-noc.yaml b/Documentation/devicetree/bindings/interconnect/fsl,imx8m-noc.yaml index 09c8948b5e25..fa4f7685ab2b 100644 --- a/Documentation/devicetree/bindings/interconnect/fsl,imx8m-noc.yaml +++ b/Documentation/devicetree/bindings/interconnect/fsl,imx8m-noc.yaml @@ -7,7 +7,7 @@ $schema: http://devicetree.org/meta-schemas/core.yaml# title: Generic i.MX bus frequency device maintainers: - - Leonard Crestez <leonard.crestez@nxp.com> + - Peng Fan <peng.fan@nxp.com> description: | The i.MX SoC family has multiple buses for which clock frequency (and diff --git a/Documentation/devicetree/bindings/interrupt-controller/apple,aic.yaml b/Documentation/devicetree/bindings/interrupt-controller/apple,aic.yaml index 85c85b694217..e18107eafe7c 100644 --- a/Documentation/devicetree/bindings/interrupt-controller/apple,aic.yaml +++ b/Documentation/devicetree/bindings/interrupt-controller/apple,aic.yaml @@ -96,7 +96,7 @@ properties: Documentation/devicetree/bindings/arm/cpus.yaml). required: - - fiq-index + - apple,fiq-index - cpus required: diff --git a/Documentation/devicetree/bindings/leds/backlight/mediatek,mt6370-backlight.yaml b/Documentation/devicetree/bindings/leds/backlight/mediatek,mt6370-backlight.yaml new file mode 100644 index 000000000000..5533b6562d92 --- /dev/null +++ b/Documentation/devicetree/bindings/leds/backlight/mediatek,mt6370-backlight.yaml @@ -0,0 +1,121 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/leds/backlight/mediatek,mt6370-backlight.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: MediaTek MT6370 Backlight + +maintainers: + - ChiaEn Wu <chiaen_wu@richtek.com> + +description: | + This module is part of the MT6370 MFD device. + The MT6370 Backlight WLED driver supports up to a 29V output voltage for + 4 channels of 8 series WLEDs. Each channel supports up to 30mA of current + capability with 2048 current steps (11 bits, only for MT6370/MT6371) or + 16384 current steps (14 bits, only for MT6372) in exponential or linear + mapping curves. + +allOf: + - $ref: common.yaml# + +properties: + compatible: + enum: + - mediatek,mt6370-backlight + - mediatek,mt6372-backlight + + default-brightness: + minimum: 0 + + max-brightness: + minimum: 0 + + enable-gpios: + description: External backlight 'enable' pin + maxItems: 1 + + mediatek,bled-pwm-enable: + description: | + Enable external PWM input for backlight dimming + type: boolean + + mediatek,bled-pwm-hys-enable: + description: | + Enable the backlight input-hysteresis for PWM mode + type: boolean + + mediatek,bled-pwm-hys-input-th-steps: + $ref: /schemas/types.yaml#/definitions/uint8 + enum: [1, 4, 16, 64] + description: | + The selection of the upper and lower bounds threshold of backlight + PWM resolution. If we choose selection 64, the variation of PWM + resolution needs more than 64 steps. + + mediatek,bled-ovp-shutdown: + description: | + Enable the backlight shutdown when OVP level triggered + type: boolean + + mediatek,bled-ovp-microvolt: + enum: [17000000, 21000000, 25000000, 29000000] + description: | + Backlight OVP level selection. + + mediatek,bled-ocp-shutdown: + description: | + Enable the backlight shutdown when OCP level triggerred. + type: boolean + + mediatek,bled-ocp-microamp: + enum: [900000, 1200000, 1500000, 1800000] + description: | + Backlight OC level selection. + + mediatek,bled-exponential-mode-enable: + description: | + Enable the exponential mode of backlight brightness. If this property + is not enabled, the default is to use linear mode. + type: boolean + + mediatek,bled-channel-use: + $ref: /schemas/types.yaml#/definitions/uint8 + description: | + Backlight LED channel to be used. + Each bit mapping to: + - 0: CH4 + - 1: CH3 + - 2: CH2 + - 3: CH1 + minimum: 1 + maximum: 15 + +if: + properties: + compatible: + contains: + const: mediatek,mt6372-backlight + +then: + properties: + default-brightness: + maximum: 16384 + + max-brightness: + maximum: 16384 + +else: + properties: + default-brightness: + maximum: 2048 + + max-brightness: + maximum: 2048 + +required: + - compatible + - mediatek,bled-channel-use + +additionalProperties: false diff --git a/Documentation/devicetree/bindings/mailbox/amlogic,meson-gxbb-mhu.yaml b/Documentation/devicetree/bindings/mailbox/amlogic,meson-gxbb-mhu.yaml index ea06976fbbc7..dfd26b998189 100644 --- a/Documentation/devicetree/bindings/mailbox/amlogic,meson-gxbb-mhu.yaml +++ b/Documentation/devicetree/bindings/mailbox/amlogic,meson-gxbb-mhu.yaml @@ -8,7 +8,7 @@ $schema: "http://devicetree.org/meta-schemas/core.yaml#" title: Amlogic Meson Message-Handling-Unit Controller maintainers: - - Neil Armstrong <narmstrong@baylibre.com> + - Neil Armstrong <neil.armstrong@linaro.org> description: | The Amlogic's Meson SoCs Message-Handling-Unit (MHU) is a mailbox controller diff --git a/Documentation/devicetree/bindings/media/amlogic,axg-ge2d.yaml b/Documentation/devicetree/bindings/media/amlogic,axg-ge2d.yaml index bee93bd84771..e551be5e680e 100644 --- a/Documentation/devicetree/bindings/media/amlogic,axg-ge2d.yaml +++ b/Documentation/devicetree/bindings/media/amlogic,axg-ge2d.yaml @@ -8,7 +8,7 @@ $schema: "http://devicetree.org/meta-schemas/core.yaml#" title: Amlogic GE2D Acceleration Unit maintainers: - - Neil Armstrong <narmstrong@baylibre.com> + - Neil Armstrong <neil.armstrong@linaro.org> properties: compatible: diff --git a/Documentation/devicetree/bindings/media/amlogic,gx-vdec.yaml b/Documentation/devicetree/bindings/media/amlogic,gx-vdec.yaml index 5044c4bb94e0..b827edabcafa 100644 --- a/Documentation/devicetree/bindings/media/amlogic,gx-vdec.yaml +++ b/Documentation/devicetree/bindings/media/amlogic,gx-vdec.yaml @@ -8,7 +8,7 @@ $schema: "http://devicetree.org/meta-schemas/core.yaml#" title: Amlogic Video Decoder maintainers: - - Neil Armstrong <narmstrong@baylibre.com> + - Neil Armstrong <neil.armstrong@linaro.org> - Maxime Jourdan <mjourdan@baylibre.com> description: | diff --git a/Documentation/devicetree/bindings/media/amlogic,meson-gx-ao-cec.yaml b/Documentation/devicetree/bindings/media/amlogic,meson-gx-ao-cec.yaml index d93aea6a0258..8d844f4312d1 100644 --- a/Documentation/devicetree/bindings/media/amlogic,meson-gx-ao-cec.yaml +++ b/Documentation/devicetree/bindings/media/amlogic,meson-gx-ao-cec.yaml @@ -8,7 +8,7 @@ $schema: "http://devicetree.org/meta-schemas/core.yaml#" title: Amlogic Meson AO-CEC Controller maintainers: - - Neil Armstrong <narmstrong@baylibre.com> + - Neil Armstrong <neil.armstrong@linaro.org> description: | The Amlogic Meson AO-CEC module is present is Amlogic SoCs and its purpose is diff --git a/Documentation/devicetree/bindings/memory-controllers/fsl/imx8m-ddrc.yaml b/Documentation/devicetree/bindings/memory-controllers/fsl/imx8m-ddrc.yaml index 445e46feda69..2b39fce5f650 100644 --- a/Documentation/devicetree/bindings/memory-controllers/fsl/imx8m-ddrc.yaml +++ b/Documentation/devicetree/bindings/memory-controllers/fsl/imx8m-ddrc.yaml @@ -7,7 +7,7 @@ $schema: http://devicetree.org/meta-schemas/core.yaml# title: i.MX8M DDR Controller maintainers: - - Leonard Crestez <leonard.crestez@nxp.com> + - Peng Fan <peng.fan@nxp.com> description: The DDRC block is integrated in i.MX8M for interfacing with DDR based diff --git a/Documentation/devicetree/bindings/memory-controllers/mediatek,mt7621-memc.yaml b/Documentation/devicetree/bindings/memory-controllers/mediatek,mt7621-memc.yaml index 85e02854f083..6ccdaf99c778 100644 --- a/Documentation/devicetree/bindings/memory-controllers/mediatek,mt7621-memc.yaml +++ b/Documentation/devicetree/bindings/memory-controllers/mediatek,mt7621-memc.yaml @@ -11,7 +11,9 @@ maintainers: properties: compatible: - const: mediatek,mt7621-memc + items: + - const: mediatek,mt7621-memc + - const: syscon reg: maxItems: 1 @@ -25,6 +27,6 @@ additionalProperties: false examples: - | memory-controller@5000 { - compatible = "mediatek,mt7621-memc"; + compatible = "mediatek,mt7621-memc", "syscon"; reg = <0x5000 0x1000>; }; diff --git a/Documentation/devicetree/bindings/mfd/khadas,mcu.yaml b/Documentation/devicetree/bindings/mfd/khadas,mcu.yaml index a3b976f101e8..5750cc06e923 100644 --- a/Documentation/devicetree/bindings/mfd/khadas,mcu.yaml +++ b/Documentation/devicetree/bindings/mfd/khadas,mcu.yaml @@ -7,7 +7,7 @@ $schema: http://devicetree.org/meta-schemas/core.yaml# title: Khadas on-board Microcontroller Device Tree Bindings maintainers: - - Neil Armstrong <narmstrong@baylibre.com> + - Neil Armstrong <neil.armstrong@linaro.org> description: | Khadas embeds a microcontroller on their VIM and Edge boards adding some diff --git a/Documentation/devicetree/bindings/mfd/mscc,ocelot.yaml b/Documentation/devicetree/bindings/mfd/mscc,ocelot.yaml new file mode 100644 index 000000000000..8bf45a5673a4 --- /dev/null +++ b/Documentation/devicetree/bindings/mfd/mscc,ocelot.yaml @@ -0,0 +1,160 @@ +# SPDX-License-Identifier: GPL-2.0 OR BSD-2-Clause */ +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/mfd/mscc,ocelot.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Ocelot Externally-Controlled Ethernet Switch + +maintainers: + - Colin Foster <colin.foster@in-advantage.com> + +description: | + The Ocelot ethernet switch family contains chips that have an internal CPU + (VSC7513, VSC7514) and chips that don't (VSC7511, VSC7512). All switches have + the option to be controlled externally, which is the purpose of this driver. + + The switch family is a multi-port networking switch that supports many + interfaces. Additionally, the device can perform pin control, MDIO buses, and + external GPIO expanders. + +properties: + compatible: + enum: + - mscc,vsc7512 + + reg: + maxItems: 1 + + "#address-cells": + const: 1 + + "#size-cells": + const: 1 + + spi-max-frequency: + maxItems: 1 + +patternProperties: + "^pinctrl@[0-9a-f]+$": + type: object + $ref: /schemas/pinctrl/mscc,ocelot-pinctrl.yaml + + "^gpio@[0-9a-f]+$": + type: object + $ref: /schemas/pinctrl/microchip,sparx5-sgpio.yaml + properties: + compatible: + enum: + - mscc,ocelot-sgpio + + "^mdio@[0-9a-f]+$": + type: object + $ref: /schemas/net/mscc,miim.yaml + properties: + compatible: + enum: + - mscc,ocelot-miim + +required: + - compatible + - reg + - '#address-cells' + - '#size-cells' + - spi-max-frequency + +additionalProperties: false + +examples: + - | + ocelot_clock: ocelot-clock { + compatible = "fixed-clock"; + #clock-cells = <0>; + clock-frequency = <125000000>; + }; + + spi { + #address-cells = <1>; + #size-cells = <0>; + + soc@0 { + compatible = "mscc,vsc7512"; + spi-max-frequency = <2500000>; + reg = <0>; + #address-cells = <1>; + #size-cells = <1>; + + mdio@7107009c { + compatible = "mscc,ocelot-miim"; + #address-cells = <1>; + #size-cells = <0>; + reg = <0x7107009c 0x24>; + + sw_phy0: ethernet-phy@0 { + reg = <0x0>; + }; + }; + + mdio@710700c0 { + compatible = "mscc,ocelot-miim"; + pinctrl-names = "default"; + pinctrl-0 = <&miim1_pins>; + #address-cells = <1>; + #size-cells = <0>; + reg = <0x710700c0 0x24>; + + sw_phy4: ethernet-phy@4 { + reg = <0x4>; + }; + }; + + gpio: pinctrl@71070034 { + compatible = "mscc,ocelot-pinctrl"; + gpio-controller; + #gpio-cells = <2>; + gpio-ranges = <&gpio 0 0 22>; + reg = <0x71070034 0x6c>; + + sgpio_pins: sgpio-pins { + pins = "GPIO_0", "GPIO_1", "GPIO_2", "GPIO_3"; + function = "sg0"; + }; + + miim1_pins: miim1-pins { + pins = "GPIO_14", "GPIO_15"; + function = "miim"; + }; + }; + + gpio@710700f8 { + compatible = "mscc,ocelot-sgpio"; + #address-cells = <1>; + #size-cells = <0>; + bus-frequency = <12500000>; + clocks = <&ocelot_clock>; + microchip,sgpio-port-ranges = <0 15>; + pinctrl-names = "default"; + pinctrl-0 = <&sgpio_pins>; + reg = <0x710700f8 0x100>; + + sgpio_in0: gpio@0 { + compatible = "microchip,sparx5-sgpio-bank"; + reg = <0>; + gpio-controller; + #gpio-cells = <3>; + ngpios = <64>; + }; + + sgpio_out1: gpio@1 { + compatible = "microchip,sparx5-sgpio-bank"; + reg = <1>; + gpio-controller; + #gpio-cells = <3>; + ngpios = <64>; + }; + }; + }; + }; + +... + diff --git a/Documentation/devicetree/bindings/mmc/cdns,sdhci.yaml b/Documentation/devicetree/bindings/mmc/cdns,sdhci.yaml index 4207fed62dfe..8b1a0fdcb5e3 100644 --- a/Documentation/devicetree/bindings/mmc/cdns,sdhci.yaml +++ b/Documentation/devicetree/bindings/mmc/cdns,sdhci.yaml @@ -8,7 +8,6 @@ title: Cadence SD/SDIO/eMMC Host Controller (SD4HC) maintainers: - Masahiro Yamada <yamada.masahiro@socionext.com> - - Piotr Sroka <piotrs@cadence.com> allOf: - $ref: mmc-controller.yaml diff --git a/Documentation/devicetree/bindings/mmc/mmc-controller.yaml b/Documentation/devicetree/bindings/mmc/mmc-controller.yaml index ff5ce89e5111..802e3ca8be4d 100644 --- a/Documentation/devicetree/bindings/mmc/mmc-controller.yaml +++ b/Documentation/devicetree/bindings/mmc/mmc-controller.yaml @@ -88,11 +88,18 @@ properties: default: 1 max-frequency: - description: - Maximum operating frequency of the bus. + description: | + Maximum operating frequency of the bus: + - for eMMC, the maximum supported frequency is 200MHz, + - for SD/SDIO cards the SDR104 mode has a max supported + frequency of 208MHz, + - some mmc host controllers do support a max frequency upto + 384MHz. + So, lets keep the maximum supported value here. + $ref: /schemas/types.yaml#/definitions/uint32 minimum: 400000 - maximum: 200000000 + maximum: 384000000 disable-wp: $ref: /schemas/types.yaml#/definitions/flag diff --git a/Documentation/devicetree/bindings/mmc/mmc-spi-slot.yaml b/Documentation/devicetree/bindings/mmc/mmc-spi-slot.yaml index c45b91099325..c0662ce9946d 100644 --- a/Documentation/devicetree/bindings/mmc/mmc-spi-slot.yaml +++ b/Documentation/devicetree/bindings/mmc/mmc-spi-slot.yaml @@ -23,8 +23,6 @@ properties: reg: maxItems: 1 - spi-max-frequency: true - interrupts: maxItems: 1 diff --git a/Documentation/devicetree/bindings/mmc/mtk-sd.yaml b/Documentation/devicetree/bindings/mmc/mtk-sd.yaml index 083d1ec2f661..d8e1e2e9adf2 100644 --- a/Documentation/devicetree/bindings/mmc/mtk-sd.yaml +++ b/Documentation/devicetree/bindings/mmc/mtk-sd.yaml @@ -20,6 +20,7 @@ properties: - mediatek,mt2701-mmc - mediatek,mt2712-mmc - mediatek,mt6779-mmc + - mediatek,mt6795-mmc - mediatek,mt7620-mmc - mediatek,mt7622-mmc - mediatek,mt8135-mmc diff --git a/Documentation/devicetree/bindings/mmc/renesas,sdhi.yaml b/Documentation/devicetree/bindings/mmc/renesas,sdhi.yaml index 14945ebc31d2..0424b06cb655 100644 --- a/Documentation/devicetree/bindings/mmc/renesas,sdhi.yaml +++ b/Documentation/devicetree/bindings/mmc/renesas,sdhi.yaml @@ -89,6 +89,9 @@ properties: - tx - rx + iommus: + maxItems: 1 + power-domains: maxItems: 1 diff --git a/Documentation/devicetree/bindings/mmc/rockchip-dw-mshc.yaml b/Documentation/devicetree/bindings/mmc/rockchip-dw-mshc.yaml index 8d888b435817..ccf0e3e93efa 100644 --- a/Documentation/devicetree/bindings/mmc/rockchip-dw-mshc.yaml +++ b/Documentation/devicetree/bindings/mmc/rockchip-dw-mshc.yaml @@ -32,6 +32,7 @@ properties: - rockchip,px30-dw-mshc - rockchip,rk1808-dw-mshc - rockchip,rk3036-dw-mshc + - rockchip,rk3128-dw-mshc - rockchip,rk3228-dw-mshc - rockchip,rk3308-dw-mshc - rockchip,rk3328-dw-mshc diff --git a/Documentation/devicetree/bindings/mmc/sdhci-am654.yaml b/Documentation/devicetree/bindings/mmc/sdhci-am654.yaml index 0ab07759b472..ea9121fb188d 100644 --- a/Documentation/devicetree/bindings/mmc/sdhci-am654.yaml +++ b/Documentation/devicetree/bindings/mmc/sdhci-am654.yaml @@ -51,6 +51,9 @@ properties: sdhci-caps-mask: true + dma-coherent: + type: boolean + # 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.yaml b/Documentation/devicetree/bindings/mmc/sdhci-msm.yaml index fc0e81c2066c..a96f143479c7 100644 --- a/Documentation/devicetree/bindings/mmc/sdhci-msm.yaml +++ b/Documentation/devicetree/bindings/mmc/sdhci-msm.yaml @@ -38,9 +38,11 @@ properties: - qcom,sc7180-sdhci - qcom,sc7280-sdhci - qcom,sdm630-sdhci + - qcom,sdm670-sdhci - qcom,sdm845-sdhci - qcom,sdx55-sdhci - qcom,sdx65-sdhci + - qcom,sm6115-sdhci - qcom,sm6125-sdhci - qcom,sm6350-sdhci - qcom,sm8150-sdhci @@ -96,6 +98,10 @@ properties: description: Should specify pin control groups used for this controller. + pinctrl-1: + description: + Should specify sleep pin control groups used for this controller. + resets: maxItems: 1 diff --git a/Documentation/devicetree/bindings/net/adi,adin1110.yaml b/Documentation/devicetree/bindings/net/adi,adin1110.yaml new file mode 100644 index 000000000000..b6bd8ee38a18 --- /dev/null +++ b/Documentation/devicetree/bindings/net/adi,adin1110.yaml @@ -0,0 +1,77 @@ +# SPDX-License-Identifier: (GPL-2.0 OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/net/adi,adin1110.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: ADI ADIN1110 MAC-PHY + +maintainers: + - Alexandru Tachici <alexandru.tachici@analog.com> + +description: | + The ADIN1110 is a low power single port 10BASE-T1L MAC- + PHY designed for industrial Ethernet applications. It integrates + an Ethernet PHY core with a MAC and all the associated analog + circuitry, input and output clock buffering. + + The ADIN2111 is a low power, low complexity, two-Ethernet ports + switch with integrated 10BASE-T1L PHYs and one serial peripheral + interface (SPI) port. The device is designed for industrial Ethernet + applications using low power constrained nodes and is compliant + with the IEEE 802.3cg-2019 Ethernet standard for long reach + 10 Mbps single pair Ethernet (SPE). + + The device has a 4-wire SPI interface for communication + between the MAC and host processor. + +allOf: + - $ref: ethernet-controller.yaml# + - $ref: /schemas/spi/spi-peripheral-props.yaml# + +properties: + compatible: + enum: + - adi,adin1110 + - adi,adin2111 + + reg: + maxItems: 1 + + adi,spi-crc: + description: | + Enable CRC8 checks on SPI read/writes. + type: boolean + + interrupts: + maxItems: 1 + +required: + - compatible + - reg + - interrupts + +unevaluatedProperties: false + +examples: + - | + #include <dt-bindings/interrupt-controller/irq.h> + + spi { + + #address-cells = <1>; + #size-cells = <0>; + + ethernet@0 { + compatible = "adi,adin2111"; + reg = <0>; + spi-max-frequency = <24500000>; + + adi,spi-crc; + + interrupt-parent = <&gpio>; + interrupts = <25 IRQ_TYPE_LEVEL_LOW>; + + local-mac-address = [ 00 11 22 33 44 55 ]; + }; + }; diff --git a/Documentation/devicetree/bindings/net/altera_tse.txt b/Documentation/devicetree/bindings/net/altera_tse.txt deleted file mode 100644 index 1d9148ff5130..000000000000 --- a/Documentation/devicetree/bindings/net/altera_tse.txt +++ /dev/null @@ -1,113 +0,0 @@ -* Altera Triple-Speed Ethernet MAC driver (TSE) - -Required properties: -- compatible: Should be "altr,tse-1.0" for legacy SGDMA based TSE, and should - be "altr,tse-msgdma-1.0" for the preferred MSGDMA based TSE. - ALTR is supported for legacy device trees, but is deprecated. - altr should be used for all new designs. -- reg: Address and length of the register set for the device. It contains - the information of registers in the same order as described by reg-names -- reg-names: Should contain the reg names - "control_port": MAC configuration space region - "tx_csr": xDMA Tx dispatcher control and status space region - "tx_desc": MSGDMA Tx dispatcher descriptor space region - "rx_csr" : xDMA Rx dispatcher control and status space region - "rx_desc": MSGDMA Rx dispatcher descriptor space region - "rx_resp": MSGDMA Rx dispatcher response space region - "s1": SGDMA descriptor memory -- interrupts: Should contain the TSE interrupts and its mode. -- interrupt-names: Should contain the interrupt names - "rx_irq": xDMA Rx dispatcher interrupt - "tx_irq": xDMA Tx dispatcher interrupt -- rx-fifo-depth: MAC receive FIFO buffer depth in bytes -- tx-fifo-depth: MAC transmit FIFO buffer depth in bytes -- phy-mode: See ethernet.txt in the same directory. -- phy-handle: See ethernet.txt in the same directory. -- phy-addr: See ethernet.txt in the same directory. A configuration should - include phy-handle or phy-addr. -- altr,has-supplementary-unicast: - If present, TSE supports additional unicast addresses. - Otherwise additional unicast addresses are not supported. -- altr,has-hash-multicast-filter: - If present, TSE supports a hash based multicast filter. - Otherwise, hash-based multicast filtering is not supported. - -- mdio device tree subnode: When the TSE has a phy connected to its local - mdio, there must be device tree subnode with the following - required properties: - - - compatible: Must be "altr,tse-mdio". - - #address-cells: Must be <1>. - - #size-cells: Must be <0>. - - For each phy on the mdio bus, there must be a node with the following - fields: - - - reg: phy id used to communicate to phy. - - device_type: Must be "ethernet-phy". - -The MAC address will be determined using the optional properties defined in -ethernet.txt. - -Example: - - tse_sub_0_eth_tse_0: ethernet@1,00000000 { - compatible = "altr,tse-msgdma-1.0"; - reg = <0x00000001 0x00000000 0x00000400>, - <0x00000001 0x00000460 0x00000020>, - <0x00000001 0x00000480 0x00000020>, - <0x00000001 0x000004A0 0x00000008>, - <0x00000001 0x00000400 0x00000020>, - <0x00000001 0x00000420 0x00000020>; - reg-names = "control_port", "rx_csr", "rx_desc", "rx_resp", "tx_csr", "tx_desc"; - interrupt-parent = <&hps_0_arm_gic_0>; - interrupts = <0 41 4>, <0 40 4>; - interrupt-names = "rx_irq", "tx_irq"; - rx-fifo-depth = <2048>; - tx-fifo-depth = <2048>; - address-bits = <48>; - max-frame-size = <1500>; - local-mac-address = [ 00 00 00 00 00 00 ]; - phy-mode = "gmii"; - altr,has-supplementary-unicast; - altr,has-hash-multicast-filter; - phy-handle = <&phy0>; - mdio { - compatible = "altr,tse-mdio"; - #address-cells = <1>; - #size-cells = <0>; - phy0: ethernet-phy@0 { - reg = <0x0>; - device_type = "ethernet-phy"; - }; - - phy1: ethernet-phy@1 { - reg = <0x1>; - device_type = "ethernet-phy"; - }; - - }; - }; - - tse_sub_1_eth_tse_0: ethernet@1,00001000 { - compatible = "altr,tse-msgdma-1.0"; - reg = <0x00000001 0x00001000 0x00000400>, - <0x00000001 0x00001460 0x00000020>, - <0x00000001 0x00001480 0x00000020>, - <0x00000001 0x000014A0 0x00000008>, - <0x00000001 0x00001400 0x00000020>, - <0x00000001 0x00001420 0x00000020>; - reg-names = "control_port", "rx_csr", "rx_desc", "rx_resp", "tx_csr", "tx_desc"; - interrupt-parent = <&hps_0_arm_gic_0>; - interrupts = <0 43 4>, <0 42 4>; - interrupt-names = "rx_irq", "tx_irq"; - rx-fifo-depth = <2048>; - tx-fifo-depth = <2048>; - address-bits = <48>; - max-frame-size = <1500>; - local-mac-address = [ 00 00 00 00 00 00 ]; - phy-mode = "gmii"; - altr,has-supplementary-unicast; - altr,has-hash-multicast-filter; - phy-handle = <&phy1>; - }; diff --git a/Documentation/devicetree/bindings/net/altr,tse.yaml b/Documentation/devicetree/bindings/net/altr,tse.yaml new file mode 100644 index 000000000000..8d1d94494349 --- /dev/null +++ b/Documentation/devicetree/bindings/net/altr,tse.yaml @@ -0,0 +1,168 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/net/altr,tse.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Altera Triple Speed Ethernet MAC driver (TSE) + +maintainers: + - Maxime Chevallier <maxime.chevallier@bootlin.com> + +properties: + compatible: + oneOf: + - const: altr,tse-1.0 + - const: ALTR,tse-1.0 + deprecated: true + - const: altr,tse-msgdma-1.0 + + interrupts: + minItems: 2 + + interrupt-names: + items: + - const: rx_irq + - const: tx_irq + + rx-fifo-depth: + $ref: /schemas/types.yaml#/definitions/uint32 + description: + Depth in bytes of the RX FIFO + + tx-fifo-depth: + $ref: /schemas/types.yaml#/definitions/uint32 + description: + Depth in bytes of the TX FIFO + + altr,has-supplementary-unicast: + type: boolean + description: + If present, TSE supports additional unicast addresses. + + altr,has-hash-multicast-filter: + type: boolean + description: + If present, TSE supports hash based multicast filter. + + mdio: + $ref: mdio.yaml# + unevaluatedProperties: false + description: + Creates and registers an MDIO bus. + + properties: + compatible: + const: altr,tse-mdio + + required: + - compatible + +required: + - compatible + - reg + - interrupts + - rx-fifo-depth + - tx-fifo-depth + +allOf: + - $ref: "ethernet-controller.yaml#" + - if: + properties: + compatible: + contains: + enum: + - const: altr,tse-1.0 + - const: ALTR,tse-1.0 + then: + properties: + reg: + minItems: 4 + reg-names: + items: + - const: control_port + - const: rx_csr + - const: tx_csr + - const: s1 + + - if: + properties: + compatible: + contains: + enum: + - altr,tse-msgdma-1.0 + then: + properties: + reg: + minItems: 6 + maxItems: 7 + reg-names: + minItems: 6 + items: + - const: control_port + - const: rx_csr + - const: rx_desc + - const: rx_resp + - const: tx_csr + - const: tx_desc + - const: pcs + +unevaluatedProperties: false + +examples: + - | + tse_sub_0: ethernet@c0100000 { + compatible = "altr,tse-msgdma-1.0"; + reg = <0xc0100000 0x00000400>, + <0xc0101000 0x00000020>, + <0xc0102000 0x00000020>, + <0xc0103000 0x00000008>, + <0xc0104000 0x00000020>, + <0xc0105000 0x00000020>, + <0xc0106000 0x00000100>; + reg-names = "control_port", "rx_csr", "rx_desc", "rx_resp", "tx_csr", "tx_desc", "pcs"; + interrupt-parent = <&intc>; + interrupts = <0 44 4>,<0 45 4>; + interrupt-names = "rx_irq","tx_irq"; + rx-fifo-depth = <2048>; + tx-fifo-depth = <2048>; + max-frame-size = <1500>; + local-mac-address = [ 00 00 00 00 00 00 ]; + altr,has-supplementary-unicast; + altr,has-hash-multicast-filter; + sfp = <&sfp0>; + phy-mode = "sgmii"; + managed = "in-band-status"; + }; + - | + tse_sub_1_eth_tse_0: ethernet@1,00001000 { + compatible = "altr,tse-msgdma-1.0"; + reg = <0x00001000 0x00000400>, + <0x00001460 0x00000020>, + <0x00001480 0x00000020>, + <0x000014A0 0x00000008>, + <0x00001400 0x00000020>, + <0x00001420 0x00000020>; + reg-names = "control_port", "rx_csr", "rx_desc", "rx_resp", "tx_csr", "tx_desc"; + interrupt-parent = <&hps_0_arm_gic_0>; + interrupts = <0 43 4>, <0 42 4>; + interrupt-names = "rx_irq", "tx_irq"; + rx-fifo-depth = <2048>; + tx-fifo-depth = <2048>; + max-frame-size = <1500>; + local-mac-address = [ 00 00 00 00 00 00 ]; + phy-mode = "gmii"; + altr,has-supplementary-unicast; + altr,has-hash-multicast-filter; + phy-handle = <&phy1>; + mdio { + compatible = "altr,tse-mdio"; + #address-cells = <1>; + #size-cells = <0>; + phy1: ethernet-phy@1 { + reg = <0x1>; + }; + }; + }; + +... diff --git a/Documentation/devicetree/bindings/net/amlogic,meson-dwmac.yaml b/Documentation/devicetree/bindings/net/amlogic,meson-dwmac.yaml index 608e1d62bed5..ddd5a073c3a8 100644 --- a/Documentation/devicetree/bindings/net/amlogic,meson-dwmac.yaml +++ b/Documentation/devicetree/bindings/net/amlogic,meson-dwmac.yaml @@ -8,7 +8,7 @@ $schema: "http://devicetree.org/meta-schemas/core.yaml#" title: Amlogic Meson DWMAC Ethernet controller maintainers: - - Neil Armstrong <narmstrong@baylibre.com> + - Neil Armstrong <neil.armstrong@linaro.org> - Martin Blumenstingl <martin.blumenstingl@googlemail.com> # We need a select here so we don't match all nodes with 'snps,dwmac' diff --git a/Documentation/devicetree/bindings/net/can/nxp,sja1000.yaml b/Documentation/devicetree/bindings/net/can/nxp,sja1000.yaml index b1327c5b86cf..144a3785132c 100644 --- a/Documentation/devicetree/bindings/net/can/nxp,sja1000.yaml +++ b/Documentation/devicetree/bindings/net/can/nxp,sja1000.yaml @@ -30,8 +30,10 @@ properties: clocks: maxItems: 1 + power-domains: + maxItems: 1 + reg-io-width: - $ref: /schemas/types.yaml#/definitions/uint32 description: I/O register width (in bytes) implemented by this device default: 1 enum: [ 1, 2, 4 ] @@ -105,6 +107,7 @@ allOf: then: required: - clocks + - power-domains unevaluatedProperties: false @@ -129,4 +132,5 @@ examples: reg-io-width = <4>; interrupts = <GIC_SPI 95 IRQ_TYPE_LEVEL_HIGH>; clocks = <&sysctrl R9A06G032_HCLK_CAN0>; + power-domains = <&sysctrl>; }; diff --git a/Documentation/devicetree/bindings/net/cortina,gemini-ethernet.yaml b/Documentation/devicetree/bindings/net/cortina,gemini-ethernet.yaml index cc01b9b5752a..253b5d1407ee 100644 --- a/Documentation/devicetree/bindings/net/cortina,gemini-ethernet.yaml +++ b/Documentation/devicetree/bindings/net/cortina,gemini-ethernet.yaml @@ -37,6 +37,7 @@ properties: patternProperties: "^ethernet-port@[0-9]+$": type: object + unevaluatedProperties: false description: contains the resources for ethernet port allOf: - $ref: ethernet-controller.yaml# diff --git a/Documentation/devicetree/bindings/net/dsa/ar9331.txt b/Documentation/devicetree/bindings/net/dsa/ar9331.txt index 320607cbbb17..f824fdae0da2 100644 --- a/Documentation/devicetree/bindings/net/dsa/ar9331.txt +++ b/Documentation/devicetree/bindings/net/dsa/ar9331.txt @@ -76,7 +76,6 @@ eth1: ethernet@1a000000 { switch_port0: port@0 { reg = <0x0>; - label = "cpu"; ethernet = <ð1>; phy-mode = "gmii"; diff --git a/Documentation/devicetree/bindings/net/dsa/arrow,xrs700x.yaml b/Documentation/devicetree/bindings/net/dsa/arrow,xrs700x.yaml index 3f01b65f3b22..259a0c6547f3 100644 --- a/Documentation/devicetree/bindings/net/dsa/arrow,xrs700x.yaml +++ b/Documentation/devicetree/bindings/net/dsa/arrow,xrs700x.yaml @@ -61,8 +61,9 @@ examples: }; ethernet-port@3 { reg = <3>; - label = "cpu"; ethernet = <&fec1>; + phy-mode = "rgmii-id"; + fixed-link { speed = <1000>; full-duplex; diff --git a/Documentation/devicetree/bindings/net/dsa/brcm,b53.yaml b/Documentation/devicetree/bindings/net/dsa/brcm,b53.yaml index 23114d691d2a..1219b830b1a4 100644 --- a/Documentation/devicetree/bindings/net/dsa/brcm,b53.yaml +++ b/Documentation/devicetree/bindings/net/dsa/brcm,b53.yaml @@ -169,7 +169,6 @@ examples: port@8 { reg = <8>; - label = "cpu"; phy-mode = "rgmii-txid"; ethernet = <ð0>; fixed-link { @@ -252,8 +251,9 @@ examples: port@8 { ethernet = <&amac2>; - label = "cpu"; reg = <8>; + phy-mode = "internal"; + fixed-link { speed = <1000>; full-duplex; diff --git a/Documentation/devicetree/bindings/net/dsa/dsa-port.yaml b/Documentation/devicetree/bindings/net/dsa/dsa-port.yaml index 09317e16cb5d..10ad7e71097b 100644 --- a/Documentation/devicetree/bindings/net/dsa/dsa-port.yaml +++ b/Documentation/devicetree/bindings/net/dsa/dsa-port.yaml @@ -76,6 +76,23 @@ properties: required: - reg +# CPU and DSA ports must have phylink-compatible link descriptions +if: + oneOf: + - required: [ ethernet ] + - required: [ link ] +then: + allOf: + - required: + - phy-mode + - oneOf: + - required: + - fixed-link + - required: + - phy-handle + - required: + - managed + additionalProperties: true ... diff --git a/Documentation/devicetree/bindings/net/dsa/hirschmann,hellcreek.yaml b/Documentation/devicetree/bindings/net/dsa/hirschmann,hellcreek.yaml index 228683773151..73b774eadd0b 100644 --- a/Documentation/devicetree/bindings/net/dsa/hirschmann,hellcreek.yaml +++ b/Documentation/devicetree/bindings/net/dsa/hirschmann,hellcreek.yaml @@ -91,8 +91,13 @@ examples: port@0 { reg = <0>; - label = "cpu"; ethernet = <&gmac0>; + phy-mode = "mii"; + + fixed-link { + speed = <100>; + full-duplex; + }; }; port@2 { diff --git a/Documentation/devicetree/bindings/net/dsa/lan9303.txt b/Documentation/devicetree/bindings/net/dsa/lan9303.txt index 464d6bf87605..46a732087f5c 100644 --- a/Documentation/devicetree/bindings/net/dsa/lan9303.txt +++ b/Documentation/devicetree/bindings/net/dsa/lan9303.txt @@ -46,7 +46,6 @@ I2C managed mode: port@0 { /* RMII fixed link to master */ reg = <0>; - label = "cpu"; ethernet = <&master>; }; @@ -83,7 +82,6 @@ MDIO managed mode: port@0 { reg = <0>; - label = "cpu"; ethernet = <&master>; }; diff --git a/Documentation/devicetree/bindings/net/dsa/lantiq-gswip.txt b/Documentation/devicetree/bindings/net/dsa/lantiq-gswip.txt index e3829d3e480e..8bb1eff21cb1 100644 --- a/Documentation/devicetree/bindings/net/dsa/lantiq-gswip.txt +++ b/Documentation/devicetree/bindings/net/dsa/lantiq-gswip.txt @@ -96,7 +96,6 @@ switch@e108000 { port@6 { reg = <0x6>; - label = "cpu"; ethernet = <ð0>; }; }; diff --git a/Documentation/devicetree/bindings/net/dsa/mediatek,mt7530.yaml b/Documentation/devicetree/bindings/net/dsa/mediatek,mt7530.yaml index 17ab6c69ecc7..f2e9ff3f580b 100644 --- a/Documentation/devicetree/bindings/net/dsa/mediatek,mt7530.yaml +++ b/Documentation/devicetree/bindings/net/dsa/mediatek,mt7530.yaml @@ -4,67 +4,92 @@ $id: http://devicetree.org/schemas/net/dsa/mediatek,mt7530.yaml# $schema: http://devicetree.org/meta-schemas/core.yaml# -title: Mediatek MT7530 Ethernet switch +title: Mediatek MT7530 and MT7531 Ethernet Switches maintainers: - - Sean Wang <sean.wang@mediatek.com> + - Arınç ÃœNAL <arinc.unal@arinc9.com> - Landen Chao <Landen.Chao@mediatek.com> - DENG Qingfang <dqfext@gmail.com> + - Sean Wang <sean.wang@mediatek.com> description: | - Port 5 of mt7530 and mt7621 switch is muxed between: - 1. GMAC5: GMAC5 can interface with another external MAC or PHY. - 2. PHY of port 0 or port 4: PHY interfaces with an external MAC like 2nd GMAC - of the SOC. Used in many setups where port 0/4 becomes the WAN port. - Note: On a MT7621 SOC with integrated switch: 2nd GMAC can only connected to - GMAC5 when the gpios for RGMII2 (GPIO 22-33) are not used and not - connected to external component! - - Port 5 modes/configurations: - 1. Port 5 is disabled and isolated: An external phy can interface to the 2nd - GMAC of the SOC. - In the case of a build-in MT7530 switch, port 5 shares the RGMII bus with 2nd - GMAC and an optional external phy. Mind the GPIO/pinctl settings of the SOC! - 2. Port 5 is muxed to PHY of port 0/4: Port 0/4 interfaces with 2nd GMAC. - It is a simple MAC to PHY interface, port 5 needs to be setup for xMII mode - and RGMII delay. - 3. Port 5 is muxed to GMAC5 and can interface to an external phy. - Port 5 becomes an extra switch port. - Only works on platform where external phy TX<->RX lines are swapped. - Like in the Ubiquiti ER-X-SFP. - 4. Port 5 is muxed to GMAC5 and interfaces with the 2nd GAMC as 2nd CPU port. - Currently a 2nd CPU port is not supported by DSA code. - - Depending on how the external PHY is wired: - 1. normal: The PHY can only connect to 2nd GMAC but not to the switch - 2. swapped: RGMII TX, RX are swapped; external phy interface with the switch as - a ethernet port. But can't interface to the 2nd GMAC. - - Based on the DT the port 5 mode is configured. - - Driver tries to lookup the phy-handle of the 2nd GMAC of the master device. - When phy-handle matches PHY of port 0 or 4 then port 5 set-up as mode 2. - phy-mode must be set, see also example 2 below! - * mt7621: phy-mode = "rgmii-txid"; - * mt7623: phy-mode = "rgmii"; - - CPU-Ports need a phy-mode property: - Allowed values on mt7530 and mt7621: - - "rgmii" - - "trgmii" - On mt7531: - - "1000base-x" - - "2500base-x" - - "rgmii" - - "sgmii" + There are two versions of MT7530, standalone and in a multi-chip module. + + MT7530 is a part of the multi-chip module in MT7620AN, MT7620DA, MT7620DAN, + MT7620NN, MT7621AT, MT7621DAT, MT7621ST and MT7623AI SoCs. + + MT7530 in MT7620AN, MT7620DA, MT7620DAN and MT7620NN SoCs has got 10/100 PHYs + and the switch registers are directly mapped into SoC's memory map rather than + using MDIO. The DSA driver currently doesn't support this. + + There is only the standalone version of MT7531. + + Port 5 on MT7530 has got various ways of configuration. + + For standalone MT7530: + + - Port 5 can be used as a CPU port. + + - PHY 0 or 4 of the switch can be muxed to connect to the gmac of the SoC + which port 5 is wired to. Usually used for connecting the wan port + directly to the CPU to achieve 2 Gbps routing in total. + + The driver looks up the reg on the ethernet-phy node which the phy-handle + property refers to on the gmac node to mux the specified phy. + + The driver requires the gmac of the SoC to have "mediatek,eth-mac" as the + compatible string and the reg must be 1. So, for now, only gmac1 of an + MediaTek SoC can benefit this. Banana Pi BPI-R2 suits this. + Check out example 5 for a similar configuration. + + - Port 5 can be wired to an external phy. Port 5 becomes a DSA slave. + Check out example 7 for a similar configuration. + + For multi-chip module MT7530: + + - Port 5 can be used as a CPU port. + + - PHY 0 or 4 of the switch can be muxed to connect to gmac1 of the SoC. + Usually used for connecting the wan port directly to the CPU to achieve 2 + Gbps routing in total. + + The driver looks up the reg on the ethernet-phy node which the phy-handle + property refers to on the gmac node to mux the specified phy. + + For the MT7621 SoCs, rgmii2 group must be claimed with rgmii2 function. + Check out example 5. + + - In case of an external phy wired to gmac1 of the SoC, port 5 must not be + enabled. + + In case of muxing PHY 0 or 4, the external phy must not be enabled. + + For the MT7621 SoCs, rgmii2 group must be claimed with rgmii2 function. + Check out example 6. + - Port 5 can be muxed to an external phy. Port 5 becomes a DSA slave. + The external phy must be wired TX to TX to gmac1 of the SoC for this to + work. Ubiquiti EdgeRouter X SFP is wired this way. + + Muxing PHY 0 or 4 won't work when the external phy is connected TX to TX. + + For the MT7621 SoCs, rgmii2 group must be claimed with gpio function. + Check out example 7. properties: compatible: - enum: - - mediatek,mt7530 - - mediatek,mt7531 - - mediatek,mt7621 + oneOf: + - description: + Standalone MT7530 and multi-chip module MT7530 in MT7623AI SoC + const: mediatek,mt7530 + + - description: + Standalone MT7531 + const: mediatek,mt7531 + + - description: + Multi-chip module MT7530 in MT7621AT, MT7621DAT and MT7621ST SoCs + const: mediatek,mt7621 reg: maxItems: 1 @@ -79,7 +104,14 @@ properties: gpio-controller: type: boolean description: - if defined, MT7530's LED controller will run on GPIO mode. + If defined, LED controller of the MT7530 switch will run on GPIO mode. + + There are 15 controllable pins. + port 0 LED 0..2 as GPIO 0..2 + port 1 LED 0..2 as GPIO 3..5 + port 2 LED 0..2 as GPIO 6..8 + port 3 LED 0..2 as GPIO 9..11 + port 4 LED 0..2 as GPIO 12..14 "#interrupt-cells": const: 1 @@ -92,17 +124,21 @@ properties: io-supply: description: Phandle to the regulator node necessary for the I/O power. - See Documentation/devicetree/bindings/regulator/mt6323-regulator.txt - for details for the regulator setup on these boards. + See Documentation/devicetree/bindings/regulator/mt6323-regulator.txt for + details for the regulator setup on these boards. mediatek,mcm: type: boolean description: - if defined, indicates that either MT7530 is the part on multi-chip - module belong to MT7623A has or the remotely standalone chip as the - function MT7623N reference board provided for. + Used for MT7621AT, MT7621DAT, MT7621ST and MT7623AI SoCs which the MT7530 + switch is a part of the multi-chip module. reset-gpios: + description: + GPIO to reset the switch. Use this if mediatek,mcm is not used. + This property is optional because some boards share the reset line with + other components which makes it impossible to probe the switch if the + reset line is used. maxItems: 1 reset-names: @@ -110,8 +146,8 @@ properties: resets: description: - Phandle pointing to the system reset controller with line index for - the ethsys. + Phandle pointing to the system reset controller with line index for the + ethsys. maxItems: 1 patternProperties: @@ -128,31 +164,88 @@ patternProperties: properties: reg: description: - Port address described must be 5 or 6 for CPU port and from 0 - to 5 for user ports. + Port address described must be 5 or 6 for CPU port and from 0 to 5 + for user ports. allOf: - $ref: dsa-port.yaml# - if: - properties: - label: - items: - - const: cpu + required: [ ethernet ] then: - required: - - reg - - phy-mode + properties: + reg: + enum: + - 5 + - 6 required: - compatible - reg +$defs: + mt7530-dsa-port: + patternProperties: + "^(ethernet-)?ports$": + patternProperties: + "^(ethernet-)?port@[0-9]+$": + if: + required: [ ethernet ] + then: + if: + properties: + reg: + const: 5 + then: + properties: + phy-mode: + enum: + - gmii + - mii + - rgmii + else: + properties: + phy-mode: + enum: + - rgmii + - trgmii + + mt7531-dsa-port: + patternProperties: + "^(ethernet-)?ports$": + patternProperties: + "^(ethernet-)?port@[0-9]+$": + if: + required: [ ethernet ] + then: + if: + properties: + reg: + const: 5 + then: + properties: + phy-mode: + enum: + - 1000base-x + - 2500base-x + - rgmii + - sgmii + else: + properties: + phy-mode: + enum: + - 1000base-x + - 2500base-x + - sgmii + allOf: - - $ref: "dsa.yaml#" + - $ref: dsa.yaml# - if: required: - mediatek,mcm then: + properties: + reset-gpios: false + required: - resets - reset-names @@ -163,52 +256,139 @@ allOf: - if: properties: compatible: - items: - - const: mediatek,mt7530 + const: mediatek,mt7530 then: + $ref: "#/$defs/mt7530-dsa-port" required: - core-supply - io-supply + - if: + properties: + compatible: + const: mediatek,mt7531 + then: + $ref: "#/$defs/mt7531-dsa-port" + properties: + gpio-controller: false + mediatek,mcm: false + + - if: + properties: + compatible: + const: mediatek,mt7621 + then: + $ref: "#/$defs/mt7530-dsa-port" + required: + - mediatek,mcm + unevaluatedProperties: false examples: + # Example 1: Standalone MT7530 - | #include <dt-bindings/gpio/gpio.h> + mdio { #address-cells = <1>; #size-cells = <0>; - switch@0 { + + switch@1f { compatible = "mediatek,mt7530"; - reg = <0>; + reg = <0x1f>; + + reset-gpios = <&pio 33 0>; core-supply = <&mt6323_vpa_reg>; io-supply = <&mt6323_vemc3v3_reg>; - reset-gpios = <&pio 33 GPIO_ACTIVE_HIGH>; ethernet-ports { #address-cells = <1>; #size-cells = <0>; + port@0 { reg = <0>; - label = "lan0"; + label = "lan1"; }; port@1 { reg = <1>; - label = "lan1"; + label = "lan2"; }; port@2 { reg = <2>; - label = "lan2"; + label = "lan3"; }; port@3 { reg = <3>; + label = "lan4"; + }; + + port@4 { + reg = <4>; + label = "wan"; + }; + + port@6 { + reg = <6>; + ethernet = <&gmac0>; + phy-mode = "rgmii"; + + fixed-link { + speed = <1000>; + full-duplex; + pause; + }; + }; + }; + }; + }; + + # Example 2: MT7530 in MT7623AI SoC + - | + #include <dt-bindings/reset/mt2701-resets.h> + + mdio { + #address-cells = <1>; + #size-cells = <0>; + + switch@1f { + compatible = "mediatek,mt7530"; + reg = <0x1f>; + + mediatek,mcm; + resets = <ðsys MT2701_ETHSYS_MCM_RST>; + reset-names = "mcm"; + + core-supply = <&mt6323_vpa_reg>; + io-supply = <&mt6323_vemc3v3_reg>; + + ethernet-ports { + #address-cells = <1>; + #size-cells = <0>; + + port@0 { + reg = <0>; + label = "lan1"; + }; + + port@1 { + reg = <1>; + label = "lan2"; + }; + + port@2 { + reg = <2>; label = "lan3"; }; + port@3 { + reg = <3>; + label = "lan4"; + }; + port@4 { reg = <4>; label = "wan"; @@ -216,96 +396,226 @@ examples: port@6 { reg = <6>; - label = "cpu"; ethernet = <&gmac0>; phy-mode = "trgmii"; + fixed-link { speed = <1000>; full-duplex; + pause; }; }; }; }; }; + # Example 3: Standalone MT7531 - | - //Example 2: MT7621: Port 4 is WAN port: 2nd GMAC -> Port 5 -> PHY port 4. + #include <dt-bindings/gpio/gpio.h> + #include <dt-bindings/interrupt-controller/irq.h> - ethernet { + mdio { #address-cells = <1>; #size-cells = <0>; - gmac0: mac@0 { - compatible = "mediatek,eth-mac"; + + switch@0 { + compatible = "mediatek,mt7531"; reg = <0>; - phy-mode = "rgmii"; - fixed-link { - speed = <1000>; - full-duplex; - pause; + reset-gpios = <&pio 54 0>; + + interrupt-controller; + #interrupt-cells = <1>; + interrupt-parent = <&pio>; + interrupts = <53 IRQ_TYPE_LEVEL_HIGH>; + + ethernet-ports { + #address-cells = <1>; + #size-cells = <0>; + + port@0 { + reg = <0>; + label = "lan1"; + }; + + port@1 { + reg = <1>; + label = "lan2"; + }; + + port@2 { + reg = <2>; + label = "lan3"; + }; + + port@3 { + reg = <3>; + label = "lan4"; + }; + + port@4 { + reg = <4>; + label = "wan"; + }; + + port@6 { + reg = <6>; + ethernet = <&gmac0>; + phy-mode = "2500base-x"; + + fixed-link { + speed = <2500>; + full-duplex; + pause; + }; + }; + }; + }; + }; + + # Example 4: MT7530 in MT7621AT, MT7621DAT and MT7621ST SoCs + - | + #include <dt-bindings/interrupt-controller/mips-gic.h> + #include <dt-bindings/reset/mt7621-reset.h> + + mdio { + #address-cells = <1>; + #size-cells = <0>; + + switch@1f { + compatible = "mediatek,mt7621"; + reg = <0x1f>; + + mediatek,mcm; + resets = <&sysc MT7621_RST_MCM>; + reset-names = "mcm"; + + interrupt-controller; + #interrupt-cells = <1>; + interrupt-parent = <&gic>; + interrupts = <GIC_SHARED 23 IRQ_TYPE_LEVEL_HIGH>; + + ethernet-ports { + #address-cells = <1>; + #size-cells = <0>; + + port@0 { + reg = <0>; + label = "lan1"; + }; + + port@1 { + reg = <1>; + label = "lan2"; + }; + + port@2 { + reg = <2>; + label = "lan3"; + }; + + port@3 { + reg = <3>; + label = "lan4"; + }; + + port@4 { + reg = <4>; + label = "wan"; + }; + + port@6 { + reg = <6>; + ethernet = <&gmac0>; + phy-mode = "trgmii"; + + fixed-link { + speed = <1000>; + full-duplex; + pause; + }; + }; }; }; + }; - gmac1: mac@1 { + # Example 5: MT7621: mux MT7530's phy4 to SoC's gmac1 + - | + #include <dt-bindings/interrupt-controller/mips-gic.h> + #include <dt-bindings/reset/mt7621-reset.h> + + ethernet { + #address-cells = <1>; + #size-cells = <0>; + + pinctrl-names = "default"; + pinctrl-0 = <&rgmii2_pins>; + + mac@1 { compatible = "mediatek,eth-mac"; reg = <1>; - phy-mode = "rgmii-txid"; - phy-handle = <&phy4>; + + phy-mode = "rgmii"; + phy-handle = <&example5_ethphy4>; }; - mdio: mdio-bus { + mdio { #address-cells = <1>; #size-cells = <0>; - /* Internal phy */ - phy4: ethernet-phy@4 { + /* MT7530's phy4 */ + example5_ethphy4: ethernet-phy@4 { reg = <4>; }; - mt7530: switch@1f { + switch@1f { compatible = "mediatek,mt7621"; reg = <0x1f>; - mediatek,mcm; - resets = <&rstctrl 2>; + mediatek,mcm; + resets = <&sysc MT7621_RST_MCM>; reset-names = "mcm"; + interrupt-controller; + #interrupt-cells = <1>; + interrupt-parent = <&gic>; + interrupts = <GIC_SHARED 23 IRQ_TYPE_LEVEL_HIGH>; + ethernet-ports { #address-cells = <1>; #size-cells = <0>; port@0 { reg = <0>; - label = "lan0"; + label = "lan1"; }; port@1 { reg = <1>; - label = "lan1"; + label = "lan2"; }; port@2 { reg = <2>; - label = "lan2"; + label = "lan3"; }; port@3 { reg = <3>; - label = "lan3"; + label = "lan4"; }; - /* Commented out. Port 4 is handled by 2nd GMAC. + /* Commented out, phy4 is muxed to gmac1. port@4 { reg = <4>; - label = "lan4"; + label = "wan"; }; */ port@6 { reg = <6>; - label = "cpu"; ethernet = <&gmac0>; - phy-mode = "rgmii"; + phy-mode = "trgmii"; fixed-link { speed = <1000>; @@ -318,82 +628,169 @@ examples: }; }; + # Example 6: MT7621: mux external phy to SoC's gmac1 - | - //Example 3: MT7621: Port 5 is connected to external PHY: Port 5 -> external PHY. + #include <dt-bindings/interrupt-controller/mips-gic.h> + #include <dt-bindings/reset/mt7621-reset.h> ethernet { #address-cells = <1>; #size-cells = <0>; - gmac_0: mac@0 { + + pinctrl-names = "default"; + pinctrl-0 = <&rgmii2_pins>; + + mac@1 { compatible = "mediatek,eth-mac"; - reg = <0>; + reg = <1>; + phy-mode = "rgmii"; + phy-handle = <&example6_ethphy7>; + }; + + mdio { + #address-cells = <1>; + #size-cells = <0>; - fixed-link { - speed = <1000>; - full-duplex; - pause; + /* External PHY */ + example6_ethphy7: ethernet-phy@7 { + reg = <7>; + phy-mode = "rgmii"; + }; + + switch@1f { + compatible = "mediatek,mt7621"; + reg = <0x1f>; + + mediatek,mcm; + resets = <&sysc MT7621_RST_MCM>; + reset-names = "mcm"; + + interrupt-controller; + #interrupt-cells = <1>; + interrupt-parent = <&gic>; + interrupts = <GIC_SHARED 23 IRQ_TYPE_LEVEL_HIGH>; + + ethernet-ports { + #address-cells = <1>; + #size-cells = <0>; + + port@0 { + reg = <0>; + label = "lan1"; + }; + + port@1 { + reg = <1>; + label = "lan2"; + }; + + port@2 { + reg = <2>; + label = "lan3"; + }; + + port@3 { + reg = <3>; + label = "lan4"; + }; + + port@4 { + reg = <4>; + label = "wan"; + }; + + port@6 { + reg = <6>; + ethernet = <&gmac0>; + phy-mode = "trgmii"; + + fixed-link { + speed = <1000>; + full-duplex; + pause; + }; + }; + }; }; }; + }; + + # Example 7: MT7621: mux external phy to MT7530's port 5 + - | + #include <dt-bindings/interrupt-controller/mips-gic.h> + #include <dt-bindings/reset/mt7621-reset.h> + + ethernet { + #address-cells = <1>; + #size-cells = <0>; - mdio0: mdio-bus { + pinctrl-names = "default"; + pinctrl-0 = <&rgmii2_pins>; + + mdio { #address-cells = <1>; #size-cells = <0>; - /* External phy */ - ephy5: ethernet-phy@7 { + /* External PHY */ + example7_ethphy7: ethernet-phy@7 { reg = <7>; + phy-mode = "rgmii"; }; switch@1f { compatible = "mediatek,mt7621"; reg = <0x1f>; - mediatek,mcm; - resets = <&rstctrl 2>; + mediatek,mcm; + resets = <&sysc MT7621_RST_MCM>; reset-names = "mcm"; + interrupt-controller; + #interrupt-cells = <1>; + interrupt-parent = <&gic>; + interrupts = <GIC_SHARED 23 IRQ_TYPE_LEVEL_HIGH>; + ethernet-ports { #address-cells = <1>; #size-cells = <0>; port@0 { reg = <0>; - label = "lan0"; + label = "lan1"; }; port@1 { reg = <1>; - label = "lan1"; + label = "lan2"; }; port@2 { reg = <2>; - label = "lan2"; + label = "lan3"; }; port@3 { reg = <3>; - label = "lan3"; + label = "lan4"; }; port@4 { reg = <4>; - label = "lan4"; + label = "wan"; }; port@5 { reg = <5>; - label = "lan5"; - phy-mode = "rgmii"; - phy-handle = <&ephy5>; + label = "extphy"; + phy-mode = "rgmii-txid"; + phy-handle = <&example7_ethphy7>; }; - cpu_port0: port@6 { + port@6 { reg = <6>; - label = "cpu"; - ethernet = <&gmac_0>; - phy-mode = "rgmii"; + ethernet = <&gmac0>; + phy-mode = "trgmii"; fixed-link { speed = <1000>; diff --git a/Documentation/devicetree/bindings/net/dsa/microchip,ksz.yaml b/Documentation/devicetree/bindings/net/dsa/microchip,ksz.yaml index 6bbd8145b6c1..4da75b1f9533 100644 --- a/Documentation/devicetree/bindings/net/dsa/microchip,ksz.yaml +++ b/Documentation/devicetree/bindings/net/dsa/microchip,ksz.yaml @@ -107,8 +107,9 @@ examples: }; port@5 { reg = <5>; - label = "cpu"; ethernet = <ð0>; + phy-mode = "rgmii"; + fixed-link { speed = <1000>; full-duplex; @@ -144,8 +145,9 @@ examples: }; port@6 { reg = <6>; - label = "cpu"; ethernet = <ð0>; + phy-mode = "rgmii"; + fixed-link { speed = <1000>; full-duplex; diff --git a/Documentation/devicetree/bindings/net/dsa/mscc,ocelot.yaml b/Documentation/devicetree/bindings/net/dsa/mscc,ocelot.yaml new file mode 100644 index 000000000000..8d93ed9c172c --- /dev/null +++ b/Documentation/devicetree/bindings/net/dsa/mscc,ocelot.yaml @@ -0,0 +1,260 @@ +# SPDX-License-Identifier: (GPL-2.0 OR MIT) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/net/dsa/mscc,ocelot.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Microchip Ocelot Switch Family Device Tree Bindings + +maintainers: + - Vladimir Oltean <vladimir.oltean@nxp.com> + - Claudiu Manoil <claudiu.manoil@nxp.com> + - Alexandre Belloni <alexandre.belloni@bootlin.com> + - UNGLinuxDriver@microchip.com + +description: | + There are multiple switches which are either part of the Ocelot-1 family, or + derivatives of this architecture. These switches can be found embedded in + various SoCs and accessed using MMIO, or as discrete chips and accessed over + SPI or PCIe. The present DSA binding shall be used when the host controlling + them performs packet I/O primarily through an Ethernet port of the switch + (which is attached to an Ethernet port of the host), rather than through + Frame DMA or register-based I/O. + + VSC9953 (Seville): + + This is found in the NXP T1040, where it is a memory-mapped platform + device. + + The following PHY interface types are supported: + + - phy-mode = "internal": on ports 8 and 9 + - phy-mode = "sgmii": on ports 0, 1, 2, 3, 4, 5, 6, 7 + - phy-mode = "qsgmii": on ports 0, 1, 2, 3, 4, 5, 6, 7 + - phy-mode = "1000base-x": on ports 0, 1, 2, 3, 4, 5, 6, 7 + + VSC9959 (Felix): + + This is found in the NXP LS1028A. It is a PCI device, part of the larger + enetc root complex. As a result, the ethernet-switch node is a sub-node of + the PCIe root complex node and its "reg" property conforms to the parent + node bindings, describing it as PF 5 of device 0, bus 0. + + If any external switch port is enabled, the enetc PF2 (enetc_port2) should + be enabled as well. This is because the internal MDIO bus (exposed through + EA BAR 0) used to access the MAC PCS registers truly belongs to the enetc + port 2 and not to Felix. + + The following PHY interface types are supported: + + - phy-mode = "internal": on ports 4 and 5 + - phy-mode = "sgmii": on ports 0, 1, 2, 3 + - phy-mode = "qsgmii": on ports 0, 1, 2, 3 + - phy-mode = "usxgmii": on ports 0, 1, 2, 3 + - phy-mode = "1000base-x": on ports 0, 1, 2, 3 + - phy-mode = "2500base-x": on ports 0, 1, 2, 3 + +properties: + compatible: + enum: + - mscc,vsc9953-switch + - pci1957,eef0 + + reg: + maxItems: 1 + + interrupts: + maxItems: 1 + + description: + Used to signal availability of PTP TX timestamps, and state changes of + the MAC merge layer of ports that support Frame Preemption. + + little-endian: true + big-endian: true + +required: + - compatible + - reg + +allOf: + - $ref: dsa.yaml# + - if: + properties: + compatible: + const: pci1957,eef0 + then: + required: + - interrupts + +unevaluatedProperties: false + +examples: + # Felix VSC9959 (NXP LS1028A) + - | + #include <dt-bindings/interrupt-controller/arm-gic.h> + + pcie { /* Integrated Endpoint Root Complex */ + #address-cells = <3>; + #size-cells = <2>; + + ethernet-switch@0,5 { + compatible = "pci1957,eef0"; + reg = <0x000500 0 0 0 0>; + interrupts = <GIC_SPI 95 IRQ_TYPE_LEVEL_HIGH>; + + ethernet-ports { + #address-cells = <1>; + #size-cells = <0>; + + port@0 { + reg = <0>; + phy-mode = "qsgmii"; + phy-handle = <&phy0>; + managed = "in-band-status"; + }; + + port@1 { + reg = <1>; + phy-mode = "qsgmii"; + phy-handle = <&phy1>; + managed = "in-band-status"; + }; + + port@2 { + reg = <2>; + phy-mode = "qsgmii"; + phy-handle = <&phy2>; + managed = "in-band-status"; + }; + + port@3 { + reg = <3>; + phy-mode = "qsgmii"; + phy-handle = <&phy3>; + managed = "in-band-status"; + }; + + port@4 { + reg = <4>; + ethernet = <&enetc_port2>; + phy-mode = "internal"; + + fixed-link { + speed = <2500>; + full-duplex; + pause; + }; + }; + + port@5 { + reg = <5>; + ethernet = <&enetc_port3>; + phy-mode = "internal"; + + fixed-link { + speed = <1000>; + full-duplex; + pause; + }; + }; + }; + }; + }; + # Seville VSC9953 (NXP T1040) + - | + soc { + #address-cells = <1>; + #size-cells = <1>; + + ethernet-switch@800000 { + compatible = "mscc,vsc9953-switch"; + reg = <0x800000 0x290000>; + little-endian; + + ethernet-ports { + #address-cells = <1>; + #size-cells = <0>; + + port@0 { + reg = <0>; + phy-mode = "qsgmii"; + phy-handle = <&phy0>; + managed = "in-band-status"; + }; + + port@1 { + reg = <1>; + phy-mode = "qsgmii"; + phy-handle = <&phy1>; + managed = "in-band-status"; + }; + + port@2 { + reg = <2>; + phy-mode = "qsgmii"; + phy-handle = <&phy2>; + managed = "in-band-status"; + }; + + port@3 { + reg = <3>; + phy-mode = "qsgmii"; + phy-handle = <&phy3>; + managed = "in-band-status"; + }; + + port@4 { + reg = <4>; + phy-mode = "qsgmii"; + phy-handle = <&phy4>; + managed = "in-band-status"; + }; + + port@5 { + reg = <5>; + phy-mode = "qsgmii"; + phy-handle = <&phy5>; + managed = "in-band-status"; + }; + + port@6 { + reg = <6>; + phy-mode = "qsgmii"; + phy-handle = <&phy6>; + managed = "in-band-status"; + }; + + port@7 { + reg = <7>; + phy-mode = "qsgmii"; + phy-handle = <&phy7>; + managed = "in-band-status"; + }; + + port@8 { + reg = <8>; + phy-mode = "internal"; + ethernet = <&enet0>; + + fixed-link { + speed = <2500>; + full-duplex; + pause; + }; + }; + + port@9 { + reg = <9>; + phy-mode = "internal"; + ethernet = <&enet1>; + + fixed-link { + speed = <2500>; + full-duplex; + pause; + }; + }; + }; + }; + }; diff --git a/Documentation/devicetree/bindings/net/dsa/ocelot.txt b/Documentation/devicetree/bindings/net/dsa/ocelot.txt deleted file mode 100644 index 7a271d070b72..000000000000 --- a/Documentation/devicetree/bindings/net/dsa/ocelot.txt +++ /dev/null @@ -1,213 +0,0 @@ -Microchip Ocelot switch driver family -===================================== - -Felix ------ - -Currently the switches supported by the felix driver are: - -- VSC9959 (Felix) -- VSC9953 (Seville) - -The VSC9959 switch is found in the NXP LS1028A. It is a PCI device, part of the -larger ENETC root complex. As a result, the ethernet-switch node is a sub-node -of the PCIe root complex node and its "reg" property conforms to the parent -node bindings: - -* reg: Specifies PCIe Device Number and Function Number of the endpoint device, - in this case for the Ethernet L2Switch it is PF5 (of device 0, bus 0). - -It does not require a "compatible" string. - -The interrupt line is used to signal availability of PTP TX timestamps and for -TSN frame preemption. - -For the external switch ports, depending on board configuration, "phy-mode" and -"phy-handle" are populated by board specific device tree instances. Ports 4 and -5 are fixed as internal ports in the NXP LS1028A instantiation. - -The CPU port property ("ethernet") configures the feature called "NPI port" in -the Ocelot hardware core. The CPU port in Ocelot is a set of queues, which are -connected, in the Node Processor Interface (NPI) mode, to an Ethernet port. -By default, in fsl-ls1028a.dtsi, the NPI port is assigned to the internal -2.5Gbps port@4, but can be moved to the 1Gbps port@5, depending on the specific -use case. Moving the NPI port to an external switch port is hardware possible, -but there is no platform support for the Linux system on the LS1028A chip to -operate as an entire slave DSA chip. NPI functionality (and therefore DSA -tagging) is supported on a single port at a time. - -Any port can be disabled (and in fsl-ls1028a.dtsi, they are indeed all disabled -by default, and should be enabled on a per-board basis). But if any external -switch port is enabled at all, the ENETC PF2 (enetc_port2) should be enabled as -well, regardless of whether it is configured as the DSA master or not. This is -because the Felix PHYLINK implementation accesses the MAC PCS registers, which -in hardware truly belong to the ENETC port #2 and not to Felix. - -Supported PHY interface types (appropriate SerDes protocol setting changes are -needed in the RCW binary): - -* phy_mode = "internal": on ports 4 and 5 -* phy_mode = "sgmii": on ports 0, 1, 2, 3 -* phy_mode = "qsgmii": on ports 0, 1, 2, 3 -* phy_mode = "usxgmii": on ports 0, 1, 2, 3 -* phy_mode = "2500base-x": on ports 0, 1, 2, 3 - -For the rest of the device tree binding definitions, which are standard DSA and -PCI, refer to the following documents: - -Documentation/devicetree/bindings/net/dsa/dsa.txt -Documentation/devicetree/bindings/pci/pci.txt - -Example: - -&soc { - pcie@1f0000000 { /* Integrated Endpoint Root Complex */ - ethernet-switch@0,5 { - reg = <0x000500 0 0 0 0>; - /* IEP INT_B */ - interrupts = <GIC_SPI 95 IRQ_TYPE_LEVEL_HIGH>; - - ports { - #address-cells = <1>; - #size-cells = <0>; - - /* External ports */ - port@0 { - reg = <0>; - label = "swp0"; - }; - - port@1 { - reg = <1>; - label = "swp1"; - }; - - port@2 { - reg = <2>; - label = "swp2"; - }; - - port@3 { - reg = <3>; - label = "swp3"; - }; - - /* Tagging CPU port */ - port@4 { - reg = <4>; - ethernet = <&enetc_port2>; - phy-mode = "internal"; - - fixed-link { - speed = <2500>; - full-duplex; - }; - }; - - /* Non-tagging CPU port */ - port@5 { - reg = <5>; - phy-mode = "internal"; - status = "disabled"; - - fixed-link { - speed = <1000>; - full-duplex; - }; - }; - }; - }; - }; -}; - -The VSC9953 switch is found inside NXP T1040. It is a platform device with the -following required properties: - -- compatible: - Must be "mscc,vsc9953-switch". - -Supported PHY interface types (appropriate SerDes protocol setting changes are -needed in the RCW binary): - -* phy_mode = "internal": on ports 8 and 9 -* phy_mode = "sgmii": on ports 0, 1, 2, 3, 4, 5, 6, 7 -* phy_mode = "qsgmii": on ports 0, 1, 2, 3, 4, 5, 6, 7 - -Example: - -&soc { - ethernet-switch@800000 { - #address-cells = <0x1>; - #size-cells = <0x0>; - compatible = "mscc,vsc9953-switch"; - little-endian; - reg = <0x800000 0x290000>; - - ports { - #address-cells = <0x1>; - #size-cells = <0x0>; - - port@0 { - reg = <0x0>; - label = "swp0"; - }; - - port@1 { - reg = <0x1>; - label = "swp1"; - }; - - port@2 { - reg = <0x2>; - label = "swp2"; - }; - - port@3 { - reg = <0x3>; - label = "swp3"; - }; - - port@4 { - reg = <0x4>; - label = "swp4"; - }; - - port@5 { - reg = <0x5>; - label = "swp5"; - }; - - port@6 { - reg = <0x6>; - label = "swp6"; - }; - - port@7 { - reg = <0x7>; - label = "swp7"; - }; - - port@8 { - reg = <0x8>; - phy-mode = "internal"; - ethernet = <&enet0>; - - fixed-link { - speed = <2500>; - full-duplex; - }; - }; - - port@9 { - reg = <0x9>; - phy-mode = "internal"; - status = "disabled"; - - fixed-link { - speed = <2500>; - full-duplex; - }; - }; - }; - }; -}; diff --git a/Documentation/devicetree/bindings/net/dsa/qca8k.yaml b/Documentation/devicetree/bindings/net/dsa/qca8k.yaml index f3c88371d76c..978162df51f7 100644 --- a/Documentation/devicetree/bindings/net/dsa/qca8k.yaml +++ b/Documentation/devicetree/bindings/net/dsa/qca8k.yaml @@ -159,7 +159,6 @@ examples: port@0 { reg = <0>; - label = "cpu"; ethernet = <&gmac1>; phy-mode = "rgmii"; @@ -221,7 +220,6 @@ examples: port@0 { reg = <0>; - label = "cpu"; ethernet = <&gmac1>; phy-mode = "rgmii"; @@ -268,7 +266,6 @@ examples: port@6 { reg = <0>; - label = "cpu"; ethernet = <&gmac1>; phy-mode = "sgmii"; diff --git a/Documentation/devicetree/bindings/net/dsa/realtek.yaml b/Documentation/devicetree/bindings/net/dsa/realtek.yaml index 4f99aff029dc..1a7d45a8ad66 100644 --- a/Documentation/devicetree/bindings/net/dsa/realtek.yaml +++ b/Documentation/devicetree/bindings/net/dsa/realtek.yaml @@ -189,7 +189,6 @@ examples: }; port@5 { reg = <5>; - label = "cpu"; ethernet = <&gmac0>; phy-mode = "rgmii"; fixed-link { @@ -277,7 +276,6 @@ examples: }; port@6 { reg = <6>; - label = "cpu"; ethernet = <&fec1>; phy-mode = "rgmii"; tx-internal-delay-ps = <2000>; diff --git a/Documentation/devicetree/bindings/net/dsa/renesas,rzn1-a5psw.yaml b/Documentation/devicetree/bindings/net/dsa/renesas,rzn1-a5psw.yaml index 4d428f5ad044..7ca9c19a157c 100644 --- a/Documentation/devicetree/bindings/net/dsa/renesas,rzn1-a5psw.yaml +++ b/Documentation/devicetree/bindings/net/dsa/renesas,rzn1-a5psw.yaml @@ -130,7 +130,8 @@ examples: port@4 { reg = <4>; ethernet = <&gmac2>; - label = "cpu"; + phy-mode = "internal"; + fixed-link { speed = <1000>; full-duplex; diff --git a/Documentation/devicetree/bindings/net/dsa/vitesse,vsc73xx.txt b/Documentation/devicetree/bindings/net/dsa/vitesse,vsc73xx.txt index bbf4a13f6d75..258bef483673 100644 --- a/Documentation/devicetree/bindings/net/dsa/vitesse,vsc73xx.txt +++ b/Documentation/devicetree/bindings/net/dsa/vitesse,vsc73xx.txt @@ -75,7 +75,6 @@ switch@0 { }; vsc: port@6 { reg = <6>; - label = "cpu"; ethernet = <&gmac1>; phy-mode = "rgmii"; fixed-link { @@ -117,7 +116,6 @@ switch@2,0 { }; vsc: port@6 { reg = <6>; - label = "cpu"; ethernet = <&enet0>; phy-mode = "rgmii"; fixed-link { diff --git a/Documentation/devicetree/bindings/net/engleder,tsnep.yaml b/Documentation/devicetree/bindings/net/engleder,tsnep.yaml index d0e1476e15b5..5bd964a46a9d 100644 --- a/Documentation/devicetree/bindings/net/engleder,tsnep.yaml +++ b/Documentation/devicetree/bindings/net/engleder,tsnep.yaml @@ -20,7 +20,26 @@ properties: maxItems: 1 interrupts: - maxItems: 1 + minItems: 1 + maxItems: 8 + + interrupt-names: + minItems: 1 + items: + - const: mac + - const: txrx-1 + - const: txrx-2 + - const: txrx-3 + - const: txrx-4 + - const: txrx-5 + - const: txrx-6 + - const: txrx-7 + description: + The main interrupt for basic MAC features and the first TX/RX queue pair + is named "mac". "txrx-[1-7]" are the interrupts for additional TX/RX + queue pairs. + + dma-coherent: true local-mac-address: true @@ -58,7 +77,7 @@ examples: axi { #address-cells = <2>; #size-cells = <2>; - tnsep0: ethernet@a0000000 { + tsnep0: ethernet@a0000000 { compatible = "engleder,tsnep"; reg = <0x0 0xa0000000 0x0 0x10000>; interrupts = <0 89 1>; @@ -76,4 +95,24 @@ examples: }; }; }; + + tsnep1: ethernet@a0010000 { + compatible = "engleder,tsnep"; + reg = <0x0 0xa0010000 0x0 0x10000>; + interrupts = <0 93 1>, <0 94 1>, <0 95 1>, <0 96 1>; + interrupt-names = "mac", "txrx-1", "txrx-2", "txrx-3"; + interrupt-parent = <&gic>; + local-mac-address = [00 00 00 00 00 00]; + phy-mode = "rgmii"; + phy-handle = <&phy1>; + mdio { + #address-cells = <1>; + #size-cells = <0>; + suppress-preamble; + phy1: ethernet-phy@1 { + reg = <1>; + rxc-skew-ps = <1080>; + }; + }; + }; }; diff --git a/Documentation/devicetree/bindings/net/ethernet-controller.yaml b/Documentation/devicetree/bindings/net/ethernet-controller.yaml index c138a1022879..4b3c590fcebf 100644 --- a/Documentation/devicetree/bindings/net/ethernet-controller.yaml +++ b/Documentation/devicetree/bindings/net/ethernet-controller.yaml @@ -67,6 +67,7 @@ properties: - gmii - sgmii - qsgmii + - qusgmii - tbi - rev-mii - rmii diff --git a/Documentation/devicetree/bindings/net/ethernet-phy.yaml b/Documentation/devicetree/bindings/net/ethernet-phy.yaml index ed1415a4381f..ad808e9ce5b9 100644 --- a/Documentation/devicetree/bindings/net/ethernet-phy.yaml +++ b/Documentation/devicetree/bindings/net/ethernet-phy.yaml @@ -144,6 +144,12 @@ properties: Mark the corresponding energy efficient ethernet mode as broken and request the ethernet to stop advertising it. + pses: + $ref: /schemas/types.yaml#/definitions/phandle-array + maxItems: 1 + description: + Specifies a reference to a node representing a Power Sourcing Equipment. + phy-is-integrated: $ref: /schemas/types.yaml#/definitions/flag description: diff --git a/Documentation/devicetree/bindings/net/fsl,fec.yaml b/Documentation/devicetree/bindings/net/fsl,fec.yaml index 5cfb661be124..e0f376f7e274 100644 --- a/Documentation/devicetree/bindings/net/fsl,fec.yaml +++ b/Documentation/devicetree/bindings/net/fsl,fec.yaml @@ -21,6 +21,7 @@ properties: - fsl,imx28-fec - fsl,imx6q-fec - fsl,mvf600-fec + - fsl,s32v234-fec - items: - enum: - fsl,imx53-fec diff --git a/Documentation/devicetree/bindings/net/fsl,fman-dtsec.yaml b/Documentation/devicetree/bindings/net/fsl,fman-dtsec.yaml new file mode 100644 index 000000000000..3a35ac1c260d --- /dev/null +++ b/Documentation/devicetree/bindings/net/fsl,fman-dtsec.yaml @@ -0,0 +1,145 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/net/fsl,fman-dtsec.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: NXP FMan MAC + +maintainers: + - Madalin Bucur <madalin.bucur@nxp.com> + +description: | + Each FMan has several MACs, each implementing an Ethernet interface. Earlier + versions of FMan used the Datapath Three Speed Ethernet Controller (dTSEC) for + 10/100/1000 MBit/s speeds, and the 10-Gigabit Ethernet Media Access Controller + (10GEC) for 10 Gbit/s speeds. Later versions of FMan use the Multirate + Ethernet Media Access Controller (mEMAC) to handle all speeds. + +properties: + compatible: + enum: + - fsl,fman-dtsec + - fsl,fman-xgec + - fsl,fman-memac + + cell-index: + maximum: 64 + description: | + FManV2: + register[bit] MAC cell-index + ============================================================ + FM_EPI[16] XGEC 8 + FM_EPI[16+n] dTSECn n-1 + FM_NPI[11+n] dTSECn n-1 + n = 1,..,5 + + FManV3: + register[bit] MAC cell-index + ============================================================ + FM_EPI[16+n] mEMACn n-1 + FM_EPI[25] mEMAC10 9 + + FM_NPI[11+n] mEMACn n-1 + FM_NPI[10] mEMAC10 9 + FM_NPI[11] mEMAC9 8 + n = 1,..8 + + FM_EPI and FM_NPI are located in the FMan memory map. + + 2. SoC registers: + + - P2041, P3041, P4080 P5020, P5040: + register[bit] FMan MAC cell + Unit index + ============================================================ + DCFG_DEVDISR2[7] 1 XGEC 8 + DCFG_DEVDISR2[7+n] 1 dTSECn n-1 + DCFG_DEVDISR2[15] 2 XGEC 8 + DCFG_DEVDISR2[15+n] 2 dTSECn n-1 + n = 1,..5 + + - T1040, T2080, T4240, B4860: + register[bit] FMan MAC cell + Unit index + ============================================================ + DCFG_CCSR_DEVDISR2[n-1] 1 mEMACn n-1 + DCFG_CCSR_DEVDISR2[11+n] 2 mEMACn n-1 + n = 1,..6,9,10 + + EVDISR, DCFG_DEVDISR2 and DCFG_CCSR_DEVDISR2 are located in + the specific SoC "Device Configuration/Pin Control" Memory + Map. + + reg: + maxItems: 1 + + fsl,fman-ports: + $ref: /schemas/types.yaml#/definitions/phandle-array + maxItems: 2 + description: | + An array of two references: the first is the FMan RX port and the second + is the TX port used by this MAC. + + ptp-timer: + $ref: /schemas/types.yaml#/definitions/phandle + description: A reference to the IEEE1588 timer + + pcsphy-handle: + $ref: /schemas/types.yaml#/definitions/phandle + description: A reference to the PCS (typically found on the SerDes) + + tbi-handle: + $ref: /schemas/types.yaml#/definitions/phandle + description: A reference to the (TBI-based) PCS + +required: + - compatible + - cell-index + - reg + - fsl,fman-ports + - ptp-timer + +allOf: + - $ref: ethernet-controller.yaml# + - if: + properties: + compatible: + contains: + const: fsl,fman-dtsec + then: + required: + - tbi-handle + - if: + properties: + compatible: + contains: + const: fsl,fman-memac + then: + required: + - pcsphy-handle + +unevaluatedProperties: false + +examples: + - | + ethernet@e0000 { + compatible = "fsl,fman-dtsec"; + cell-index = <0>; + reg = <0xe0000 0x1000>; + fsl,fman-ports = <&fman1_rx8 &fman1_tx28>; + ptp-timer = <&ptp_timer>; + tbi-handle = <&tbi0>; + }; + - | + ethernet@e8000 { + cell-index = <4>; + compatible = "fsl,fman-memac"; + reg = <0xe8000 0x1000>; + fsl,fman-ports = <&fman0_rx_0x0c &fman0_tx_0x2c>; + ptp-timer = <&ptp_timer0>; + pcsphy-handle = <&pcsphy4>; + phy-handle = <&sgmii_phy1>; + phy-connection-type = "sgmii"; + }; +... diff --git a/Documentation/devicetree/bindings/net/fsl-fman.txt b/Documentation/devicetree/bindings/net/fsl-fman.txt index 801efc7d6818..b9055335db3b 100644 --- a/Documentation/devicetree/bindings/net/fsl-fman.txt +++ b/Documentation/devicetree/bindings/net/fsl-fman.txt @@ -232,133 +232,7 @@ port@81000 { ============================================================================= FMan dTSEC/XGEC/mEMAC Node -DESCRIPTION - -mEMAC/dTSEC/XGEC are the Ethernet network interfaces - -PROPERTIES - -- compatible - Usage: required - Value type: <stringlist> - Definition: A standard property. - Must include one of the following: - - "fsl,fman-dtsec" for dTSEC MAC - - "fsl,fman-xgec" for XGEC MAC - - "fsl,fman-memac" for mEMAC MAC - -- cell-index - Usage: required - Value type: <u32> - Definition: Specifies the MAC id. - - The cell-index value may be used by the FMan or the SoC, to - identify the MAC unit in the FMan (or SoC) memory map. - In the tables below there's a description of the cell-index - use, there are two tables, one describes the use of cell-index - by the FMan, the second describes the use by the SoC: - - 1. FMan Registers - - FManV2: - register[bit] MAC cell-index - ============================================================ - FM_EPI[16] XGEC 8 - FM_EPI[16+n] dTSECn n-1 - FM_NPI[11+n] dTSECn n-1 - n = 1,..,5 - - FManV3: - register[bit] MAC cell-index - ============================================================ - FM_EPI[16+n] mEMACn n-1 - FM_EPI[25] mEMAC10 9 - - FM_NPI[11+n] mEMACn n-1 - FM_NPI[10] mEMAC10 9 - FM_NPI[11] mEMAC9 8 - n = 1,..8 - - FM_EPI and FM_NPI are located in the FMan memory map. - - 2. SoC registers: - - - P2041, P3041, P4080 P5020, P5040: - register[bit] FMan MAC cell - Unit index - ============================================================ - DCFG_DEVDISR2[7] 1 XGEC 8 - DCFG_DEVDISR2[7+n] 1 dTSECn n-1 - DCFG_DEVDISR2[15] 2 XGEC 8 - DCFG_DEVDISR2[15+n] 2 dTSECn n-1 - n = 1,..5 - - - T1040, T2080, T4240, B4860: - register[bit] FMan MAC cell - Unit index - ============================================================ - DCFG_CCSR_DEVDISR2[n-1] 1 mEMACn n-1 - DCFG_CCSR_DEVDISR2[11+n] 2 mEMACn n-1 - n = 1,..6,9,10 - - EVDISR, DCFG_DEVDISR2 and DCFG_CCSR_DEVDISR2 are located in - the specific SoC "Device Configuration/Pin Control" Memory - Map. - -- reg - Usage: required - Value type: <prop-encoded-array> - Definition: A standard property. - -- fsl,fman-ports - Usage: required - Value type: <prop-encoded-array> - Definition: An array of two phandles - the first references is - the FMan RX port and the second is the TX port used by this - MAC. - -- ptp-timer - Usage required - Value type: <phandle> - Definition: A phandle for 1EEE1588 timer. - -- pcsphy-handle - Usage required for "fsl,fman-memac" MACs - Value type: <phandle> - Definition: A phandle for pcsphy. - -- tbi-handle - Usage required for "fsl,fman-dtsec" MACs - Value type: <phandle> - Definition: A phandle for tbiphy. - -EXAMPLE - -fman1_tx28: port@a8000 { - cell-index = <0x28>; - compatible = "fsl,fman-v2-port-tx"; - reg = <0xa8000 0x1000>; -}; - -fman1_rx8: port@88000 { - cell-index = <0x8>; - compatible = "fsl,fman-v2-port-rx"; - reg = <0x88000 0x1000>; -}; - -ptp-timer: ptp_timer@fe000 { - compatible = "fsl,fman-ptp-timer"; - reg = <0xfe000 0x1000>; -}; - -ethernet@e0000 { - compatible = "fsl,fman-dtsec"; - cell-index = <0>; - reg = <0xe0000 0x1000>; - fsl,fman-ports = <&fman1_rx8 &fman1_tx28>; - ptp-timer = <&ptp-timer>; - tbi-handle = <&tbi0>; -}; +Refer to Documentation/devicetree/bindings/net/fsl,fman-dtsec.yaml ============================================================================ FMan IEEE 1588 Node diff --git a/Documentation/devicetree/bindings/net/mediatek,mt7620-gsw.txt b/Documentation/devicetree/bindings/net/mediatek,mt7620-gsw.txt deleted file mode 100644 index 358fed2fab43..000000000000 --- a/Documentation/devicetree/bindings/net/mediatek,mt7620-gsw.txt +++ /dev/null @@ -1,24 +0,0 @@ -Mediatek Gigabit Switch -======================= - -The mediatek gigabit switch can be found on Mediatek SoCs (mt7620, mt7621). - -Required properties: -- compatible: Should be "mediatek,mt7620-gsw" or "mediatek,mt7621-gsw" -- reg: Address and length of the register set for the device -- interrupts: Should contain the gigabit switches interrupt -- resets: Should contain the gigabit switches resets -- reset-names: Should contain the reset names "gsw" - -Example: - -gsw@10110000 { - compatible = "ralink,mt7620-gsw"; - reg = <0x10110000 8000>; - - resets = <&rstctrl 23>; - reset-names = "gsw"; - - interrupt-parent = <&intc>; - interrupts = <17>; -}; diff --git a/Documentation/devicetree/bindings/net/mediatek,net.yaml b/Documentation/devicetree/bindings/net/mediatek,net.yaml index f5564ecddb62..7ef696204c5a 100644 --- a/Documentation/devicetree/bindings/net/mediatek,net.yaml +++ b/Documentation/devicetree/bindings/net/mediatek,net.yaml @@ -69,6 +69,15 @@ properties: A list of phandle to the syscon node that handles the SGMII setup which is required for those SoCs equipped with SGMII. + mediatek,wed: + $ref: /schemas/types.yaml#/definitions/phandle-array + minItems: 2 + maxItems: 2 + items: + maxItems: 1 + description: + List of phandles to wireless ethernet dispatch nodes. + dma-coherent: true mdio-bus: @@ -112,6 +121,8 @@ allOf: Phandle to the syscon node that handles the ports slew rate and driver current. + mediatek,wed: false + - if: properties: compatible: @@ -144,15 +155,6 @@ allOf: minItems: 1 maxItems: 1 - mediatek,wed: - $ref: /schemas/types.yaml#/definitions/phandle-array - minItems: 2 - maxItems: 2 - items: - maxItems: 1 - description: - List of phandles to wireless ethernet dispatch nodes. - mediatek,pcie-mirror: $ref: /schemas/types.yaml#/definitions/phandle description: @@ -202,6 +204,8 @@ allOf: minItems: 2 maxItems: 2 + mediatek,wed: false + - if: properties: compatible: @@ -238,6 +242,11 @@ allOf: minItems: 2 maxItems: 2 + mediatek,wed-pcie: + $ref: /schemas/types.yaml#/definitions/phandle + description: + Phandle to the mediatek wed-pcie controller. + patternProperties: "^mac@[0-1]$": type: object diff --git a/Documentation/devicetree/bindings/net/mediatek-dwmac.yaml b/Documentation/devicetree/bindings/net/mediatek-dwmac.yaml index 61b2fb9e141b..0fa2132fa4f4 100644 --- a/Documentation/devicetree/bindings/net/mediatek-dwmac.yaml +++ b/Documentation/devicetree/bindings/net/mediatek-dwmac.yaml @@ -19,6 +19,7 @@ select: contains: enum: - mediatek,mt2712-gmac + - mediatek,mt8188-gmac - mediatek,mt8195-gmac required: - compatible @@ -37,6 +38,11 @@ properties: - enum: - mediatek,mt8195-gmac - const: snps,dwmac-5.10a + - items: + - enum: + - mediatek,mt8188-gmac + - const: mediatek,mt8195-gmac + - const: snps,dwmac-5.10a clocks: minItems: 5 @@ -74,7 +80,7 @@ properties: or will round down. Range 0~31*170. For MT2712 RMII/MII interface, Allowed value need to be a multiple of 550, or will round down. Range 0~31*550. - For MT8195 RGMII/RMII/MII interface, Allowed value need to be a multiple of 290, + For MT8188/MT8195 RGMII/RMII/MII interface, Allowed value need to be a multiple of 290, or will round down. Range 0~31*290. mediatek,rx-delay-ps: @@ -84,7 +90,7 @@ properties: or will round down. Range 0~31*170. For MT2712 RMII/MII interface, Allowed value need to be a multiple of 550, or will round down. Range 0~31*550. - For MT8195 RGMII/RMII/MII interface, Allowed value need to be a multiple + For MT8188/MT8195 RGMII/RMII/MII interface, Allowed value need to be a multiple of 290, or will round down. Range 0~31*290. mediatek,rmii-rxc: diff --git a/Documentation/devicetree/bindings/net/microchip,sparx5-switch.yaml b/Documentation/devicetree/bindings/net/microchip,sparx5-switch.yaml index 6c86d3d85e99..57ffeb8fc876 100644 --- a/Documentation/devicetree/bindings/net/microchip,sparx5-switch.yaml +++ b/Documentation/devicetree/bindings/net/microchip,sparx5-switch.yaml @@ -74,16 +74,20 @@ properties: ethernet-ports: type: object + additionalProperties: false + + properties: + '#address-cells': + const: 1 + '#size-cells': + const: 0 + 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 @@ -93,29 +97,11 @@ properties: phandle of a Ethernet SerDes PHY. This defines which SerDes instance will handle the Ethernet traffic. - phy-mode: - description: - This specifies the interface used by the Ethernet SerDes towards - the PHY or SFP. - microchip,bandwidth: description: Specifies bandwidth in Mbit/s allocated to the port. $ref: "/schemas/types.yaml#/definitions/uint32" maximum: 25000 - phy-handle: - description: - phandle of a Ethernet PHY. This is optional and if provided it - points to the cuPHY used by the Ethernet SerDes. - - sfp: - description: - phandle of an SFP. This is optional and used when not specifying - a cuPHY. It points to the SFP node that describes the SFP used by - the Ethernet SerDes. - - managed: true - microchip,sd-sgpio: description: Index of the ports Signal Detect SGPIO in the set of 384 SGPIOs @@ -144,8 +130,6 @@ required: - reg-names - interrupts - interrupt-names - - resets - - reset-names - ethernet-ports additionalProperties: false diff --git a/Documentation/devicetree/bindings/net/nfc/marvell,nci.yaml b/Documentation/devicetree/bindings/net/nfc/marvell,nci.yaml index a191a04e681c..308485a8ee6c 100644 --- a/Documentation/devicetree/bindings/net/nfc/marvell,nci.yaml +++ b/Documentation/devicetree/bindings/net/nfc/marvell,nci.yaml @@ -128,7 +128,7 @@ examples: i2c-int-rising; - reset-n-io = <&gpio3 19 GPIO_ACTIVE_HIGH>; + reset-n-io = <&gpio3 19 GPIO_ACTIVE_LOW>; }; }; @@ -151,7 +151,7 @@ examples: interrupt-parent = <&gpio1>; interrupts = <17 IRQ_TYPE_EDGE_RISING>; - reset-n-io = <&gpio3 19 GPIO_ACTIVE_HIGH>; + reset-n-io = <&gpio3 19 GPIO_ACTIVE_LOW>; }; }; @@ -162,7 +162,7 @@ examples: nfc { compatible = "marvell,nfc-uart"; - reset-n-io = <&gpio3 16 GPIO_ACTIVE_HIGH>; + reset-n-io = <&gpio3 16 GPIO_ACTIVE_LOW>; hci-muxed; flow-control; diff --git a/Documentation/devicetree/bindings/net/nxp,tja11xx.yaml b/Documentation/devicetree/bindings/net/nxp,tja11xx.yaml index d51da24f3505..ab8867e6939b 100644 --- a/Documentation/devicetree/bindings/net/nxp,tja11xx.yaml +++ b/Documentation/devicetree/bindings/net/nxp,tja11xx.yaml @@ -31,6 +31,22 @@ patternProperties: description: The ID number for the child PHY. Should be +1 of parent PHY. + nxp,rmii-refclk-in: + type: boolean + description: | + The REF_CLK is provided for both transmitted and received data + in RMII mode. This clock signal is provided by the PHY and is + typically derived from an external 25MHz crystal. Alternatively, + a 50MHz clock signal generated by an external oscillator can be + connected to pin REF_CLK. A third option is to connect a 25MHz + clock to pin CLK_IN_OUT. So, the REF_CLK should be configured + as input or output according to the actual circuit connection. + If present, indicates that the REF_CLK will be configured as + interface reference clock input when RMII mode enabled. + If not present, the REF_CLK will be configured as interface + reference clock output when RMII mode enabled. + Only supported on TJA1100 and TJA1101. + required: - reg @@ -44,6 +60,7 @@ examples: tja1101_phy0: ethernet-phy@4 { reg = <0x4>; + nxp,rmii-refclk-in; }; }; - | diff --git a/Documentation/devicetree/bindings/net/pse-pd/podl-pse-regulator.yaml b/Documentation/devicetree/bindings/net/pse-pd/podl-pse-regulator.yaml new file mode 100644 index 000000000000..c6b1c188abf7 --- /dev/null +++ b/Documentation/devicetree/bindings/net/pse-pd/podl-pse-regulator.yaml @@ -0,0 +1,40 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/net/pse-pd/podl-pse-regulator.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Regulator based Power Sourcing Equipment + +maintainers: + - Oleksij Rempel <o.rempel@pengutronix.de> + +description: Regulator based PoDL PSE controller. The device must be referenced + by the PHY node to control power injection to the Ethernet cable. + +allOf: + - $ref: "pse-controller.yaml#" + +properties: + compatible: + const: podl-pse-regulator + + '#pse-cells': + const: 0 + + pse-supply: + description: Power supply for the PSE controller + +additionalProperties: false + +required: + - compatible + - pse-supply + +examples: + - | + ethernet-pse { + compatible = "podl-pse-regulator"; + pse-supply = <®_t1l1>; + #pse-cells = <0>; + }; diff --git a/Documentation/devicetree/bindings/net/pse-pd/pse-controller.yaml b/Documentation/devicetree/bindings/net/pse-pd/pse-controller.yaml new file mode 100644 index 000000000000..b110abb42597 --- /dev/null +++ b/Documentation/devicetree/bindings/net/pse-pd/pse-controller.yaml @@ -0,0 +1,33 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/net/pse-pd/pse-controller.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Power Sourcing Equipment (PSE). + +description: Binding for the Power Sourcing Equipment (PSE) as defined in the + IEEE 802.3 specification. It is designed for hardware which is delivering + power over twisted pair/ethernet cable. The ethernet-pse nodes should be + used to describe PSE controller and referenced by the ethernet-phy node. + +maintainers: + - Oleksij Rempel <o.rempel@pengutronix.de> + +properties: + $nodename: + pattern: "^ethernet-pse(@.*)?$" + + "#pse-cells": + description: + Used to uniquely identify a PSE instance within an IC. Will be + 0 on PSE nodes with only a single output and at least 1 on nodes + controlling several outputs. + enum: [0, 1] + +required: + - "#pse-cells" + +additionalProperties: true + +... diff --git a/Documentation/devicetree/bindings/net/qca,ar803x.yaml b/Documentation/devicetree/bindings/net/qca,ar803x.yaml index b3d4013b7ca6..161d28919316 100644 --- a/Documentation/devicetree/bindings/net/qca,ar803x.yaml +++ b/Documentation/devicetree/bindings/net/qca,ar803x.yaml @@ -40,6 +40,14 @@ properties: Only supported on the AR8031. type: boolean + qca,disable-hibernation-mode: + description: | + Disable Atheros AR803X PHYs hibernation mode. If present, indicates + that the hardware of PHY will not enter power saving mode when the + cable is disconnected. And the RX_CLK always keeps outputting a + valid clock. + type: boolean + qca,smarteee-tw-us-100m: description: EEE Tw parameter for 100M links. $ref: /schemas/types.yaml#/definitions/uint32 diff --git a/Documentation/devicetree/bindings/net/ralink,rt2880-net.txt b/Documentation/devicetree/bindings/net/ralink,rt2880-net.txt deleted file mode 100644 index 9fe1a0a22e44..000000000000 --- a/Documentation/devicetree/bindings/net/ralink,rt2880-net.txt +++ /dev/null @@ -1,59 +0,0 @@ -Ralink Frame Engine Ethernet controller -======================================= - -The Ralink frame engine ethernet controller can be found on Ralink and -Mediatek SoCs (RT288x, RT3x5x, RT366x, RT388x, rt5350, mt7620, mt7621, mt76x8). - -Depending on the SoC, there is a number of ports connected to the CPU port -directly and/or via a (gigabit-)switch. - -* Ethernet controller node - -Required properties: -- compatible: Should be one of "ralink,rt2880-eth", "ralink,rt3050-eth", - "ralink,rt3050-eth", "ralink,rt3883-eth", "ralink,rt5350-eth", - "mediatek,mt7620-eth", "mediatek,mt7621-eth" -- reg: Address and length of the register set for the device -- interrupts: Should contain the frame engines interrupt -- resets: Should contain the frame engines resets -- reset-names: Should contain the reset names "fe". If a switch is present - "esw" is also required. - - -* Ethernet port node - -Required properties: -- compatible: Should be "ralink,eth-port" -- reg: The number of the physical port -- phy-handle: reference to the node describing the phy - -Example: - -mdio-bus { - ... - phy0: ethernet-phy@0 { - phy-mode = "mii"; - reg = <0>; - }; -}; - -ethernet@400000 { - compatible = "ralink,rt2880-eth"; - reg = <0x00400000 10000>; - - #address-cells = <1>; - #size-cells = <0>; - - resets = <&rstctrl 18>; - reset-names = "fe"; - - interrupt-parent = <&cpuintc>; - interrupts = <5>; - - port@0 { - compatible = "ralink,eth-port"; - reg = <0>; - phy-handle = <&phy0>; - }; - -}; diff --git a/Documentation/devicetree/bindings/net/ralink,rt3050-esw.txt b/Documentation/devicetree/bindings/net/ralink,rt3050-esw.txt deleted file mode 100644 index 87e315856efa..000000000000 --- a/Documentation/devicetree/bindings/net/ralink,rt3050-esw.txt +++ /dev/null @@ -1,30 +0,0 @@ -Ralink Fast Ethernet Embedded Switch -==================================== - -The ralink fast ethernet embedded switch can be found on Ralink and Mediatek -SoCs (RT3x5x, RT5350, MT76x8). - -Required properties: -- compatible: Should be "ralink,rt3050-esw" -- reg: Address and length of the register set for the device -- interrupts: Should contain the embedded switches interrupt -- resets: Should contain the embedded switches resets -- reset-names: Should contain the reset names "esw" - -Optional properties: -- ralink,portmap: can be used to choose if the default switch setup is - llllw or wllll -- ralink,led_polarity: override the active high/low settings of the leds - -Example: - -esw@10110000 { - compatible = "ralink,rt3050-esw"; - reg = <0x10110000 8000>; - - resets = <&rstctrl 23>; - reset-names = "esw"; - - interrupt-parent = <&intc>; - interrupts = <17>; -}; diff --git a/Documentation/devicetree/bindings/net/renesas,etheravb.yaml b/Documentation/devicetree/bindings/net/renesas,etheravb.yaml index acf347f3cdbe..3f41294f5997 100644 --- a/Documentation/devicetree/bindings/net/renesas,etheravb.yaml +++ b/Documentation/devicetree/bindings/net/renesas,etheravb.yaml @@ -40,11 +40,16 @@ properties: - renesas,etheravb-r8a77980 # R-Car V3H - renesas,etheravb-r8a77990 # R-Car E3 - renesas,etheravb-r8a77995 # R-Car D3 - - renesas,etheravb-r8a779a0 # R-Car V3U - const: renesas,etheravb-rcar-gen3 # R-Car Gen3 and RZ/G2 - items: - enum: + - renesas,etheravb-r8a779a0 # R-Car V3U + - renesas,etheravb-r8a779g0 # R-Car V4H + - const: renesas,etheravb-rcar-gen4 # R-Car Gen4 + + - items: + - enum: - renesas,etheravb-r9a09g011 # RZ/V2M - const: renesas,etheravb-rzv2m # RZ/V2M compatible @@ -207,7 +212,7 @@ allOf: - renesas,etheravb-r8a77965 - renesas,etheravb-r8a77970 - renesas,etheravb-r8a77980 - - renesas,etheravb-r8a779a0 + - renesas,etheravb-rcar-gen4 then: required: - tx-internal-delay-ps diff --git a/Documentation/devicetree/bindings/net/rockchip-dwmac.yaml b/Documentation/devicetree/bindings/net/rockchip-dwmac.yaml index 083623c8d718..42fb72b6909d 100644 --- a/Documentation/devicetree/bindings/net/rockchip-dwmac.yaml +++ b/Documentation/devicetree/bindings/net/rockchip-dwmac.yaml @@ -25,7 +25,9 @@ select: - rockchip,rk3368-gmac - rockchip,rk3399-gmac - rockchip,rk3568-gmac + - rockchip,rk3588-gmac - rockchip,rv1108-gmac + - rockchip,rv1126-gmac required: - compatible @@ -47,9 +49,11 @@ properties: - rockchip,rk3368-gmac - rockchip,rk3399-gmac - rockchip,rv1108-gmac + - rockchip,rv1126-gmac - items: - enum: - rockchip,rk3568-gmac + - rockchip,rk3588-gmac - const: snps,dwmac-4.20a clocks: @@ -81,6 +85,11 @@ properties: description: The phandle of the syscon node for the general register file. $ref: /schemas/types.yaml#/definitions/phandle + rockchip,php-grf: + description: + The phandle of the syscon node for the peripheral general register file. + $ref: /schemas/types.yaml#/definitions/phandle + tx_delay: description: Delay value for TXD timing. Range value is 0~0x7F, 0x30 as default. $ref: /schemas/types.yaml#/definitions/uint32 diff --git a/Documentation/devicetree/bindings/net/snps,dwmac.yaml b/Documentation/devicetree/bindings/net/snps,dwmac.yaml index 491597c02edf..f94a0a4320f1 100644 --- a/Documentation/devicetree/bindings/net/snps,dwmac.yaml +++ b/Documentation/devicetree/bindings/net/snps,dwmac.yaml @@ -74,6 +74,7 @@ properties: - rockchip,rk3328-gmac - rockchip,rk3366-gmac - rockchip,rk3368-gmac + - rockchip,rk3588-gmac - rockchip,rk3399-gmac - rockchip,rv1108-gmac - snps,dwmac @@ -288,6 +289,11 @@ properties: is supported. For example, this is used in case of SGMII and MAC2MAC connection. + snps,clk-csr: + $ref: /schemas/types.yaml#/definitions/uint32 + description: + Frequency division factor for MDC clock. + mdio: $ref: mdio.yaml# unevaluatedProperties: false @@ -301,6 +307,60 @@ properties: required: - compatible + stmmac-axi-config: + type: object + unevaluatedProperties: false + description: + AXI BUS Mode parameters. + + properties: + snps,lpi_en: + $ref: /schemas/types.yaml#/definitions/flag + description: + enable Low Power Interface + + snps,xit_frm: + $ref: /schemas/types.yaml#/definitions/flag + description: + unlock on WoL + + snps,wr_osr_lmt: + $ref: /schemas/types.yaml#/definitions/uint32 + description: + max write outstanding req. limit + + snps,rd_osr_lmt: + $ref: /schemas/types.yaml#/definitions/uint32 + description: + max read outstanding req. limit + + snps,kbbe: + $ref: /schemas/types.yaml#/definitions/uint32 + description: + do not cross 1KiB boundary. + + snps,blen: + $ref: /schemas/types.yaml#/definitions/uint32-array + description: + this is a vector of supported burst length. + minItems: 7 + maxItems: 7 + + snps,fb: + $ref: /schemas/types.yaml#/definitions/flag + description: + fixed-burst + + snps,mb: + $ref: /schemas/types.yaml#/definitions/flag + description: + mixed-burst + + snps,rb: + $ref: /schemas/types.yaml#/definitions/flag + description: + rebuild INCRx Burst + required: - compatible - reg diff --git a/Documentation/devicetree/bindings/net/sunplus,sp7021-emac.yaml b/Documentation/devicetree/bindings/net/sunplus,sp7021-emac.yaml index 62dffee27c3d..8e51dcdb4796 100644 --- a/Documentation/devicetree/bindings/net/sunplus,sp7021-emac.yaml +++ b/Documentation/devicetree/bindings/net/sunplus,sp7021-emac.yaml @@ -32,6 +32,7 @@ properties: ethernet-ports: type: object + additionalProperties: false description: Ethernet ports to PHY properties: @@ -44,6 +45,7 @@ properties: patternProperties: "^port@[0-1]$": type: object + additionalProperties: false description: Port to PHY properties: diff --git a/Documentation/devicetree/bindings/net/ti,cpsw-switch.yaml b/Documentation/devicetree/bindings/net/ti,cpsw-switch.yaml index 31bf825c6598..46e330f45768 100644 --- a/Documentation/devicetree/bindings/net/ti,cpsw-switch.yaml +++ b/Documentation/devicetree/bindings/net/ti,cpsw-switch.yaml @@ -77,6 +77,8 @@ properties: ethernet-ports: type: object + additionalProperties: false + properties: '#address-cells': const: 1 @@ -89,6 +91,7 @@ properties: description: CPSW external ports $ref: ethernet-controller.yaml# + unevaluatedProperties: false properties: reg: @@ -117,6 +120,7 @@ properties: cpts: type: object + unevaluatedProperties: false description: The Common Platform Time Sync (CPTS) module diff --git a/Documentation/devicetree/bindings/net/ti,k3-am654-cpsw-nuss.yaml b/Documentation/devicetree/bindings/net/ti,k3-am654-cpsw-nuss.yaml index b8281d8be940..7d90beaccc60 100644 --- a/Documentation/devicetree/bindings/net/ti,k3-am654-cpsw-nuss.yaml +++ b/Documentation/devicetree/bindings/net/ti,k3-am654-cpsw-nuss.yaml @@ -55,6 +55,7 @@ properties: compatible: enum: - ti,am654-cpsw-nuss + - ti,j7200-cpswxg-nuss - ti,j721e-cpsw-nuss - ti,am642-cpsw-nuss @@ -110,16 +111,17 @@ properties: const: 0 patternProperties: - port@[1-2]: + "^port@[1-4]$": type: object description: CPSWxG NUSS external ports $ref: ethernet-controller.yaml# + unevaluatedProperties: false properties: reg: minimum: 1 - maximum: 2 + maximum: 4 description: CPSW port number phys: @@ -178,6 +180,19 @@ required: - '#address-cells' - '#size-cells' +allOf: + - if: + not: + properties: + compatible: + contains: + const: ti,j7200-cpswxg-nuss + then: + properties: + ethernet-ports: + patternProperties: + "^port@[3-4]$": false + additionalProperties: false examples: diff --git a/Documentation/devicetree/bindings/net/ti,k3-am654-cpts.yaml b/Documentation/devicetree/bindings/net/ti,k3-am654-cpts.yaml index b783ad0d1f53..e9f78cef6b7f 100644 --- a/Documentation/devicetree/bindings/net/ti,k3-am654-cpts.yaml +++ b/Documentation/devicetree/bindings/net/ti,k3-am654-cpts.yaml @@ -95,6 +95,7 @@ properties: refclk-mux: type: object + additionalProperties: false description: CPTS reference clock multiplexer clock properties: '#clock-cells': diff --git a/Documentation/devicetree/bindings/net/vertexcom-mse102x.yaml b/Documentation/devicetree/bindings/net/vertexcom-mse102x.yaml index 8156a9aeb589..304757bf9281 100644 --- a/Documentation/devicetree/bindings/net/vertexcom-mse102x.yaml +++ b/Documentation/devicetree/bindings/net/vertexcom-mse102x.yaml @@ -7,7 +7,7 @@ $schema: "http://devicetree.org/meta-schemas/core.yaml#" title: The Vertexcom MSE102x (SPI) Device Tree Bindings maintainers: - - Stefan Wahren <stefan.wahren@in-tech.com> + - Stefan Wahren <stefan.wahren@chargebyte.com> description: Vertexcom's MSE102x are a family of HomePlug GreenPHY chips. diff --git a/Documentation/devicetree/bindings/net/wireless/brcm,bcm4329-fmac.yaml b/Documentation/devicetree/bindings/net/wireless/brcm,bcm4329-fmac.yaml index 53b4153d9bfc..fec1cc9b9a08 100644 --- a/Documentation/devicetree/bindings/net/wireless/brcm,bcm4329-fmac.yaml +++ b/Documentation/devicetree/bindings/net/wireless/brcm,bcm4329-fmac.yaml @@ -4,7 +4,7 @@ $id: http://devicetree.org/schemas/net/wireless/brcm,bcm4329-fmac.yaml# $schema: http://devicetree.org/meta-schemas/core.yaml# -title: Broadcom BCM4329 family fullmac wireless SDIO devices +title: Broadcom BCM4329 family fullmac wireless SDIO/PCIE devices maintainers: - Arend van Spriel <arend@broadcom.com> @@ -41,11 +41,17 @@ properties: - cypress,cyw4373-fmac - cypress,cyw43012-fmac - const: brcm,bcm4329-fmac - - const: brcm,bcm4329-fmac + - enum: + - brcm,bcm4329-fmac + - pci14e4,43dc # BCM4355 + - pci14e4,4464 # BCM4364 + - pci14e4,4488 # BCM4377 + - pci14e4,4425 # BCM4378 + - pci14e4,4433 # BCM4387 reg: - description: SDIO function number for the device, for most cases - this will be 1. + description: SDIO function number for the device (for most cases + this will be 1) or PCI device identifier. interrupts: maxItems: 1 @@ -85,6 +91,31 @@ properties: takes precedence. type: boolean + brcm,cal-blob: + $ref: /schemas/types.yaml#/definitions/uint8-array + description: A per-device calibration blob for the Wi-Fi radio. This + should be filled in by the bootloader from platform configuration + data, if necessary, and will be uploaded to the device if present. + + brcm,board-type: + $ref: /schemas/types.yaml#/definitions/string + description: Overrides the board type, which is normally the compatible of + the root node. This can be used to decouple the overall system board or + device name from the board type for WiFi purposes, which is used to + construct firmware and NVRAM configuration filenames, allowing for + multiple devices that share the same module or characteristics for the + WiFi subsystem to share the same firmware/NVRAM files. On Apple platforms, + this should be the Apple module-instance codename prefixed by "apple,", + e.g. "apple,honshu". + + apple,antenna-sku: + $ref: /schemas/types.yaml#/definitions/string + description: Antenna SKU used to identify a specific antenna configuration + on Apple platforms. This is use to build firmware filenames, to allow + platforms with different antenna configs to have different firmware and/or + NVRAM. This would normally be filled in by the bootloader from platform + configuration data. + required: - compatible - reg diff --git a/Documentation/devicetree/bindings/net/wireless/microchip,wilc1000.yaml b/Documentation/devicetree/bindings/net/wireless/microchip,wilc1000.yaml index 60de78f1bc7b..b3405f284580 100644 --- a/Documentation/devicetree/bindings/net/wireless/microchip,wilc1000.yaml +++ b/Documentation/devicetree/bindings/net/wireless/microchip,wilc1000.yaml @@ -20,8 +20,6 @@ properties: reg: true - spi-max-frequency: true - interrupts: maxItems: 1 @@ -51,7 +49,10 @@ required: - compatible - interrupts -additionalProperties: false +allOf: + - $ref: /schemas/spi/spi-peripheral-props.yaml# + +unevaluatedProperties: false examples: - | diff --git a/Documentation/devicetree/bindings/net/wireless/qcom,ath11k.yaml b/Documentation/devicetree/bindings/net/wireless/qcom,ath11k.yaml index a677b056f112..f7cf135aa37f 100644 --- a/Documentation/devicetree/bindings/net/wireless/qcom,ath11k.yaml +++ b/Documentation/devicetree/bindings/net/wireless/qcom,ath11k.yaml @@ -66,6 +66,18 @@ properties: required: - iommus + qcom,smem-states: + $ref: /schemas/types.yaml#/definitions/phandle-array + description: State bits used by the AP to signal the WLAN Q6. + items: + - description: Signal bits used to enable/disable low power mode + on WCN6750 in the case of WoW (Wake on Wireless). + + qcom,smem-state-names: + description: The names of the state bits used for SMP2P output. + items: + - const: wlan-smp2p-out + required: - compatible - reg @@ -448,6 +460,8 @@ examples: <GIC_SPI 799 IRQ_TYPE_EDGE_RISING>; qcom,rproc = <&remoteproc_wpss>; memory-region = <&wlan_fw_mem>, <&wlan_ce_mem>; + qcom,smem-states = <&wlan_smp2p_out 0>; + qcom,smem-state-names = "wlan-smp2p-out"; wifi-firmware { iommus = <&apps_smmu 0x1c02 0x1>; }; diff --git a/Documentation/devicetree/bindings/net/wireless/silabs,wfx.yaml b/Documentation/devicetree/bindings/net/wireless/silabs,wfx.yaml index 76199a67d628..b35d2f3ad1ad 100644 --- a/Documentation/devicetree/bindings/net/wireless/silabs,wfx.yaml +++ b/Documentation/devicetree/bindings/net/wireless/silabs,wfx.yaml @@ -29,12 +29,6 @@ description: > Documentation/devicetree/bindings/mmc/mmc-pwrseq-simple.yaml for more information. - For SPI: - - In add of the properties below, please consult - Documentation/devicetree/bindings/spi/spi-controller.yaml for optional SPI - related properties. - properties: compatible: items: @@ -52,8 +46,6 @@ properties: bindings. maxItems: 1 - spi-max-frequency: true - interrupts: description: The interrupt line. Should be IRQ_TYPE_EDGE_RISING. When SPI is used, this property is required. When SDIO is used, the "in-band" @@ -84,12 +76,15 @@ properties: mac-address: true -additionalProperties: false - required: - compatible - reg +allOf: + - $ref: /schemas/spi/spi-peripheral-props.yaml# + +unevaluatedProperties: false + examples: - | #include <dt-bindings/gpio/gpio.h> diff --git a/Documentation/devicetree/bindings/net/wireless/ti,wlcore.yaml b/Documentation/devicetree/bindings/net/wireless/ti,wlcore.yaml index d68bb2ec1f7e..e31456730e9f 100644 --- a/Documentation/devicetree/bindings/net/wireless/ti,wlcore.yaml +++ b/Documentation/devicetree/bindings/net/wireless/ti,wlcore.yaml @@ -36,8 +36,6 @@ properties: This is required when connected via SPI, and optional when connected via SDIO. - spi-max-frequency: true - interrupts: minItems: 1 maxItems: 2 @@ -69,20 +67,22 @@ required: - compatible - interrupts -if: - properties: - compatible: - contains: - enum: - - ti,wl1271 - - ti,wl1273 - - ti,wl1281 - - ti,wl1283 -then: - required: - - ref-clock-frequency - -additionalProperties: false +allOf: + - $ref: /schemas/spi/spi-peripheral-props.yaml# + - if: + properties: + compatible: + contains: + enum: + - ti,wl1271 + - ti,wl1273 + - ti,wl1281 + - ti,wl1283 + then: + required: + - ref-clock-frequency + +unevaluatedProperties: false examples: - | diff --git a/Documentation/devicetree/bindings/opp/opp-v2-kryo-cpu.yaml b/Documentation/devicetree/bindings/opp/opp-v2-kryo-cpu.yaml index 59663e897dae..a202b6c6561d 100644 --- a/Documentation/devicetree/bindings/opp/opp-v2-kryo-cpu.yaml +++ b/Documentation/devicetree/bindings/opp/opp-v2-kryo-cpu.yaml @@ -40,6 +40,7 @@ properties: patternProperties: '^opp-?[0-9]+$': type: object + additionalProperties: false properties: opp-hz: true diff --git a/Documentation/devicetree/bindings/opp/opp-v2-qcom-level.yaml b/Documentation/devicetree/bindings/opp/opp-v2-qcom-level.yaml index 14a7a689ad6d..df8442fb11f0 100644 --- a/Documentation/devicetree/bindings/opp/opp-v2-qcom-level.yaml +++ b/Documentation/devicetree/bindings/opp/opp-v2-qcom-level.yaml @@ -19,6 +19,7 @@ properties: patternProperties: '^opp-?[0-9]+$': type: object + additionalProperties: false properties: opp-level: true diff --git a/Documentation/devicetree/bindings/phy/amlogic,axg-mipi-dphy.yaml b/Documentation/devicetree/bindings/phy/amlogic,axg-mipi-dphy.yaml index be485f500887..5eddaed3d853 100644 --- a/Documentation/devicetree/bindings/phy/amlogic,axg-mipi-dphy.yaml +++ b/Documentation/devicetree/bindings/phy/amlogic,axg-mipi-dphy.yaml @@ -8,7 +8,7 @@ $schema: "http://devicetree.org/meta-schemas/core.yaml#" title: Amlogic AXG MIPI D-PHY maintainers: - - Neil Armstrong <narmstrong@baylibre.com> + - Neil Armstrong <neil.armstrong@linaro.org> properties: compatible: diff --git a/Documentation/devicetree/bindings/phy/amlogic,meson-g12a-usb2-phy.yaml b/Documentation/devicetree/bindings/phy/amlogic,meson-g12a-usb2-phy.yaml index 399ebde45409..f3a5fbabbbb5 100644 --- a/Documentation/devicetree/bindings/phy/amlogic,meson-g12a-usb2-phy.yaml +++ b/Documentation/devicetree/bindings/phy/amlogic,meson-g12a-usb2-phy.yaml @@ -8,7 +8,7 @@ $schema: "http://devicetree.org/meta-schemas/core.yaml#" title: Amlogic G12A USB2 PHY maintainers: - - Neil Armstrong <narmstrong@baylibre.com> + - Neil Armstrong <neil.armstrong@linaro.org> properties: compatible: diff --git a/Documentation/devicetree/bindings/phy/amlogic,meson-g12a-usb3-pcie-phy.yaml b/Documentation/devicetree/bindings/phy/amlogic,meson-g12a-usb3-pcie-phy.yaml index 453c083cf44c..868b4e6fde71 100644 --- a/Documentation/devicetree/bindings/phy/amlogic,meson-g12a-usb3-pcie-phy.yaml +++ b/Documentation/devicetree/bindings/phy/amlogic,meson-g12a-usb3-pcie-phy.yaml @@ -8,7 +8,7 @@ $schema: "http://devicetree.org/meta-schemas/core.yaml#" title: Amlogic G12A USB3 + PCIE Combo PHY maintainers: - - Neil Armstrong <narmstrong@baylibre.com> + - Neil Armstrong <neil.armstrong@linaro.org> properties: compatible: diff --git a/Documentation/devicetree/bindings/phy/qcom,hdmi-phy-qmp.yaml b/Documentation/devicetree/bindings/phy/qcom,hdmi-phy-qmp.yaml index eea2e02678ed..83fe4b39b56f 100644 --- a/Documentation/devicetree/bindings/phy/qcom,hdmi-phy-qmp.yaml +++ b/Documentation/devicetree/bindings/phy/qcom,hdmi-phy-qmp.yaml @@ -28,12 +28,15 @@ properties: - const: hdmi_phy clocks: - maxItems: 2 + minItems: 2 + maxItems: 3 clock-names: + minItems: 2 items: - const: iface - const: ref + - const: xo power-domains: maxItems: 1 @@ -44,6 +47,9 @@ properties: vddio-supply: description: phandle to VDD I/O supply regulator + '#clock-cells': + const: 0 + '#phy-cells': const: 0 @@ -75,9 +81,12 @@ examples: "hdmi_phy"; clocks = <&mmcc 116>, - <&gcc 214>; + <&gcc 214>, + <&xo_board>; clock-names = "iface", - "ref"; + "ref", + "xo"; + #clock-cells = <0>; #phy-cells = <0>; vddio-supply = <&vreg_l12a_1p8>; diff --git a/Documentation/devicetree/bindings/pinctrl/qcom,sc7280-lpass-lpi-pinctrl.yaml b/Documentation/devicetree/bindings/pinctrl/qcom,sc7280-lpass-lpi-pinctrl.yaml index 33d1d37fdf6d..624e14f00790 100644 --- a/Documentation/devicetree/bindings/pinctrl/qcom,sc7280-lpass-lpi-pinctrl.yaml +++ b/Documentation/devicetree/bindings/pinctrl/qcom,sc7280-lpass-lpi-pinctrl.yaml @@ -8,7 +8,6 @@ title: Qualcomm Technologies, Inc. Low Power Audio SubSystem (LPASS) Low Power Island (LPI) TLMM block maintainers: - - Srinivasa Rao Mandadapu <srivasam@codeaurora.org> - Srinivas Kandagatla <srinivas.kandagatla@linaro.org> description: | diff --git a/Documentation/devicetree/bindings/pinctrl/qcom,sc7280-pinctrl.yaml b/Documentation/devicetree/bindings/pinctrl/qcom,sc7280-pinctrl.yaml index 2d228164357c..2bd60c49a442 100644 --- a/Documentation/devicetree/bindings/pinctrl/qcom,sc7280-pinctrl.yaml +++ b/Documentation/devicetree/bindings/pinctrl/qcom,sc7280-pinctrl.yaml @@ -7,7 +7,7 @@ $schema: http://devicetree.org/meta-schemas/core.yaml# title: Qualcomm Technologies, Inc. SC7280 TLMM block maintainers: - - Rajendra Nayak <rnayak@codeaurora.org> + - Bjorn Andersson <andersson@kernel.org> description: | This binding describes the Top Level Mode Multiplexer block found in the diff --git a/Documentation/devicetree/bindings/power/amlogic,meson-ee-pwrc.yaml b/Documentation/devicetree/bindings/power/amlogic,meson-ee-pwrc.yaml index 5390e988a934..43a932237a92 100644 --- a/Documentation/devicetree/bindings/power/amlogic,meson-ee-pwrc.yaml +++ b/Documentation/devicetree/bindings/power/amlogic,meson-ee-pwrc.yaml @@ -8,7 +8,7 @@ $schema: http://devicetree.org/meta-schemas/core.yaml# title: Amlogic Meson Everything-Else Power Domains maintainers: - - Neil Armstrong <narmstrong@baylibre.com> + - Neil Armstrong <neil.armstrong@linaro.org> description: |+ The Everything-Else Power Domains node should be the child of a syscon diff --git a/Documentation/devicetree/bindings/regulator/dlg,da9121.yaml b/Documentation/devicetree/bindings/regulator/dlg,da9121.yaml index 24ace6e1e5ec..63e1161a87de 100644 --- a/Documentation/devicetree/bindings/regulator/dlg,da9121.yaml +++ b/Documentation/devicetree/bindings/regulator/dlg,da9121.yaml @@ -83,6 +83,7 @@ properties: regulators: type: object + additionalProperties: false description: | List of regulators provided by the device diff --git a/Documentation/devicetree/bindings/regulator/gpio-regulator.yaml b/Documentation/devicetree/bindings/regulator/gpio-regulator.yaml index f7e3d8fd3bf3..6c3371d706bb 100644 --- a/Documentation/devicetree/bindings/regulator/gpio-regulator.yaml +++ b/Documentation/devicetree/bindings/regulator/gpio-regulator.yaml @@ -85,6 +85,9 @@ properties: - current default: voltage + vin-supply: + description: Input supply phandle. + required: - compatible - regulator-name diff --git a/Documentation/devicetree/bindings/regulator/maxim,max77802.yaml b/Documentation/devicetree/bindings/regulator/maxim,max77802.yaml index 236348c4710c..71138c611b6c 100644 --- a/Documentation/devicetree/bindings/regulator/maxim,max77802.yaml +++ b/Documentation/devicetree/bindings/regulator/maxim,max77802.yaml @@ -79,6 +79,7 @@ patternProperties: patternProperties: regulator-state-(standby|mem|disk): type: object + additionalProperties: true properties: regulator-mode: false diff --git a/Documentation/devicetree/bindings/regulator/maxim,max8997.yaml b/Documentation/devicetree/bindings/regulator/maxim,max8997.yaml index 4321f061a7f6..2b266ea43716 100644 --- a/Documentation/devicetree/bindings/regulator/maxim,max8997.yaml +++ b/Documentation/devicetree/bindings/regulator/maxim,max8997.yaml @@ -111,6 +111,7 @@ properties: regulators: type: object + additionalProperties: false description: List of child nodes that specify the regulators. diff --git a/Documentation/devicetree/bindings/regulator/mediatek,mt6331-regulator.yaml b/Documentation/devicetree/bindings/regulator/mediatek,mt6331-regulator.yaml new file mode 100644 index 000000000000..771cc134393c --- /dev/null +++ b/Documentation/devicetree/bindings/regulator/mediatek,mt6331-regulator.yaml @@ -0,0 +1,273 @@ +# SPDX-License-Identifier: (GPL-2.0 OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/regulator/mediatek,mt6331-regulator.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: MT6331 Regulator from MediaTek Integrated + +maintainers: + - AngeloGioacchino Del Regno <angelogioacchino.delregno@collabora.com> + +description: | + The MT6331 PMIC provides 6 BUCK and 21 LDO (Low Dropout) regulators + and nodes are named according to the regulator type: + buck-<name> and ldo-<name>. + MT6331 regulators node should be sub node of the MT6397 MFD node. + +patternProperties: + "^buck-v(core2|io18|dvfs11|dvfs12|dvfs13|dvfs14)$": + type: object + $ref: "regulator.yaml#" + + properties: + regulator-name: + pattern: "^v(core2|io18|dvfs11|dvfs12|dvfs13|dvfs14)$" + + unevaluatedProperties: false + + "^ldo-v(avdd32aud|auxa32)$": + type: object + $ref: "regulator.yaml#" + + properties: + regulator-name: + pattern: "^v(avdd32aud|auxa32)$" + + unevaluatedProperties: false + + "^ldo-v(dig18|emc33|ibr|mc|mch|mipi|rtc|sram|usb10)$": + type: object + $ref: "regulator.yaml#" + + properties: + regulator-name: + pattern: "^v(dig18|emc33|ibr|mc|mch|mipi|rtc|sram|usb10)$" + + unevaluatedProperties: false + + "^ldo-vcam(a|af|d|io)$": + type: object + $ref: "regulator.yaml#" + + properties: + regulator-name: + pattern: "^vcam(a|af|d|io)$" + + unevaluatedProperties: false + + "^ldo-vtcxo[12]$": + type: object + $ref: "regulator.yaml#" + + properties: + regulator-name: + pattern: "^vtcxo[12]$" + + required: + - regulator-name + + unevaluatedProperties: false + + "^ldo-vgp[1234]$": + type: object + $ref: "regulator.yaml#" + + properties: + regulator-name: + pattern: "^vgp[12]$" + + required: + - regulator-name + + unevaluatedProperties: false + +additionalProperties: false + +examples: + - | + pmic { + regulators { + mt6331_vdvfs11_reg: buck-vdvfs11 { + regulator-name = "vdvfs11"; + regulator-min-microvolt = <700000>; + regulator-max-microvolt = <1493750>; + regulator-ramp-delay = <12500>; + regulator-enable-ramp-delay = <1>; + regulator-allowed-modes = <0 1>; + }; + mt6331_vdvfs12_reg: buck-vdvfs12 { + regulator-name = "vdvfs12"; + regulator-min-microvolt = <700000>; + regulator-max-microvolt = <1493750>; + regulator-ramp-delay = <12500>; + regulator-enable-ramp-delay = <1>; + regulator-allowed-modes = <0 1>; + }; + mt6331_vdvfs13_reg: buck-vdvfs13 { + regulator-name = "vdvfs13"; + regulator-min-microvolt = <700000>; + regulator-max-microvolt = <1493750>; + regulator-ramp-delay = <12500>; + regulator-enable-ramp-delay = <1>; + regulator-allowed-modes = <0 1>; + }; + mt6331_vdvfs14_reg: buck-vdvfs14 { + regulator-name = "vdvfs14"; + regulator-min-microvolt = <700000>; + regulator-max-microvolt = <1493750>; + regulator-ramp-delay = <12500>; + regulator-enable-ramp-delay = <1>; + regulator-allowed-modes = <0 1>; + }; + mt6331_vcore2_reg: buck-vcore2 { + regulator-name = "vcore2"; + regulator-min-microvolt = <700000>; + regulator-max-microvolt = <1493750>; + regulator-ramp-delay = <12500>; + regulator-enable-ramp-delay = <1>; + regulator-allowed-modes = <0 1>; + }; + mt6331_vio18_reg: buck-vio18 { + regulator-name = "vio18"; + regulator-min-microvolt = <1800000>; + regulator-max-microvolt = <1800000>; + regulator-ramp-delay = <12500>; + regulator-enable-ramp-delay = <0>; + regulator-allowed-modes = <0 1>; + }; + mt6331_vtcxo1_reg: ldo-vtcxo1 { + regulator-name = "vtcxo1"; + regulator-min-microvolt = <2800000>; + regulator-max-microvolt = <2800000>; + regulator-always-on; + regulator-boot-on; + }; + mt6331_vtcxo2_reg: ldo-vtcxo2 { + regulator-name = "vtcxo2"; + regulator-min-microvolt = <2800000>; + regulator-max-microvolt = <2800000>; + regulator-always-on; + regulator-boot-on; + }; + mt6331_avdd32_aud_reg: ldo-avdd32aud { + regulator-name = "avdd32_aud"; + regulator-min-microvolt = <2800000>; + regulator-max-microvolt = <3200000>; + }; + mt6331_vauxa32_reg: ldo-vauxa32 { + regulator-name = "vauxa32"; + regulator-min-microvolt = <2800000>; + regulator-max-microvolt = <3200000>; + }; + mt6331_vcama_reg: ldo-vcama { + regulator-name = "vcama"; + regulator-min-microvolt = <1500000>; + regulator-max-microvolt = <2800000>; + regulator-always-on; + }; + mt6331_vio28_reg: ldo-vio28 { + regulator-name = "vio28"; + regulator-min-microvolt = <2800000>; + regulator-max-microvolt = <2800000>; + regulator-always-on; + regulator-boot-on; + }; + mt6331_vcamaf_reg: ldo-vcamaf { + regulator-name = "vcam_af"; + regulator-min-microvolt = <1200000>; + regulator-max-microvolt = <3300000>; + }; + mt6331_vmc_reg: ldo-vmc { + regulator-name = "vmc"; + regulator-min-microvolt = <1800000>; + regulator-max-microvolt = <3300000>; + }; + mt6331_vmch_reg: ldo-vmch { + regulator-name = "vmch"; + regulator-min-microvolt = <3000000>; + regulator-max-microvolt = <3300000>; + }; + mt6331_vemc33_reg: ldo-vemc33 { + regulator-name = "vemc33"; + regulator-min-microvolt = <3300000>; + regulator-max-microvolt = <3300000>; + }; + mt6331_vgp1_reg: ldo-vgp1 { + regulator-name = "vgp1"; + regulator-min-microvolt = <1200000>; + regulator-max-microvolt = <3300000>; + }; + mt6331_vsim1_reg: ldo-vsim1 { + regulator-name = "vsim1"; + regulator-min-microvolt = <1700000>; + regulator-max-microvolt = <3100000>; + }; + mt6331_vsim2_reg: ldo-vsim2 { + regulator-name = "vsim2"; + regulator-min-microvolt = <1700000>; + regulator-max-microvolt = <3100000>; + }; + mt6331_vmipi_reg: ldo-vmipi { + regulator-name = "vmipi"; + regulator-min-microvolt = <1200000>; + regulator-max-microvolt = <3300000>; + }; + mt6331_vibr_reg: ldo-vibr { + regulator-name = "vibr"; + regulator-min-microvolt = <1200000>; + regulator-max-microvolt = <3300000>; + }; + mt6331_vgp4_reg: ldo-vgp4 { + regulator-name = "vgp4"; + regulator-min-microvolt = <1600000>; + regulator-max-microvolt = <2200000>; + }; + mt6331_vcamd_reg: ldo-vcamd { + regulator-name = "vcamd"; + regulator-min-microvolt = <900000>; + regulator-max-microvolt = <1500000>; + }; + mt6331_vusb10_reg: ldo-vusb10 { + regulator-name = "vusb"; + regulator-min-microvolt = <1000000>; + regulator-max-microvolt = <1300000>; + regulator-boot-on; + }; + mt6331_vcamio_reg: ldo-vcamio { + regulator-name = "vcam_io"; + regulator-min-microvolt = <1200000>; + regulator-max-microvolt = <1800000>; + }; + mt6331_vsram_reg: ldo-vsram { + regulator-name = "vsram"; + regulator-min-microvolt = <1012500>; + regulator-max-microvolt = <1012500>; + regulator-always-on; + regulator-boot-on; + }; + mt6331_vgp2_reg: ldo-vgp2 { + regulator-name = "vgp2"; + regulator-min-microvolt = <1100000>; + regulator-max-microvolt = <1500000>; + regulator-boot-on; + }; + mt6331_vgp3_reg: ldo-vgp3 { + regulator-name = "vgp3"; + regulator-min-microvolt = <1200000>; + regulator-max-microvolt = <1800000>; + }; + mt6331_vrtc_reg: ldo-vrtc { + regulator-name = "vrtc"; + regulator-min-microvolt = <2800000>; + regulator-max-microvolt = <2800000>; + regulator-always-on; + }; + mt6331_vdig18_reg: ldo-vdig18 { + regulator-name = "dvdd18_dig"; + regulator-min-microvolt = <1800000>; + regulator-max-microvolt = <1800000>; + }; + }; + }; +... diff --git a/Documentation/devicetree/bindings/regulator/mediatek,mt6332-regulator.yaml b/Documentation/devicetree/bindings/regulator/mediatek,mt6332-regulator.yaml new file mode 100644 index 000000000000..3218f43e6957 --- /dev/null +++ b/Documentation/devicetree/bindings/regulator/mediatek,mt6332-regulator.yaml @@ -0,0 +1,112 @@ +# SPDX-License-Identifier: (GPL-2.0 OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/regulator/mediatek,mt6332-regulator.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: MT6332 Regulator from MediaTek Integrated + +maintainers: + - AngeloGioacchino Del Regno <angelogioacchino.delregno@collabora.com> + +description: | + The MT6332 Companion PMIC provides 6 BUCK and 4 LDO (Low Dropout) + regulators and nodes are named according to the regulator type: + buck-<name> and ldo-<name>. + MT6332 regulators node should be sub node of the MT6397 MFD node. + +patternProperties: + "^buck-v(dram|dvfs2|pa|rf18a|rf18b|sbst)$": + type: object + $ref: "regulator.yaml#" + + properties: + regulator-name: + pattern: "^v(dram|dvfs2|pa|rf18a|rf18b|sbst)$" + + unevaluatedProperties: false + + "^ldo-v(bif28|dig18|sram|usb33)$": + type: object + $ref: "regulator.yaml#" + + properties: + regulator-name: + pattern: "^v(bif28|dig18|sram|usb33)$" + + unevaluatedProperties: false + +additionalProperties: false + +examples: + - | + pmic { + regulators { + mt6332_vdram_reg: buck-vdram { + regulator-name = "vdram"; + regulator-min-microvolt = <700000>; + regulator-max-microvolt = <1493750>; + regulator-ramp-delay = <12500>; + regulator-allowed-modes = <0 1>; + regulator-always-on; + }; + mt6332_vdvfs2_reg: buck-vdvfs2 { + regulator-name = "vdvfs2"; + regulator-min-microvolt = <700000>; + regulator-max-microvolt = <1312500>; + regulator-ramp-delay = <12500>; + regulator-enable-ramp-delay = <1>; + regulator-allowed-modes = <0 1>; + }; + mt6332_vpa_reg: buck-vpa { + regulator-name = "vpa"; + regulator-min-microvolt = <500000>; + regulator-max-microvolt = <3400000>; + }; + mt6332_vrf18a_reg: buck-vrf18a { + regulator-name = "vrf18a"; + regulator-min-microvolt = <1050000>; + regulator-max-microvolt = <2240625>; + regulator-allowed-modes = <0 1>; + }; + mt6332_vrf18b_reg: buck-vrf18b { + regulator-name = "vrf18b"; + regulator-min-microvolt = <1050000>; + regulator-max-microvolt = <2240625>; + regulator-allowed-modes = <0 1>; + }; + mt6332_vsbst_reg: buck-vsbst { + regulator-name = "vsbst"; + regulator-min-microvolt = <3500000>; + regulator-max-microvolt = <7468750>; + }; + mt6332_vauxb32_reg: ldo-vauxb32 { + regulator-name = "vauxb32"; + regulator-min-microvolt = <2800000>; + regulator-max-microvolt = <3200000>; + }; + mt6332_vbif28_reg: ldo-vbif28 { + regulator-name = "vbif28"; + regulator-min-microvolt = <2800000>; + regulator-max-microvolt = <2800000>; + }; + mt6332_vdig18_reg: ldo-vdig18 { + regulator-name = "vdig18"; + regulator-min-microvolt = <1200000>; + regulator-max-microvolt = <1800000>; + regulator-always-on; + }; + mt6332_vsram_reg: ldo-vsram { + regulator-name = "vauxa32"; + regulator-min-microvolt = <700000>; + regulator-max-microvolt = <1493750>; + regulator-always-on; + }; + mt6332_vusb33_reg: ldo-vusb33 { + regulator-name = "vusb33"; + regulator-min-microvolt = <3300000>; + regulator-max-microvolt = <3300000>; + }; + }; + }; +... diff --git a/Documentation/devicetree/bindings/regulator/mt6315-regulator.yaml b/Documentation/devicetree/bindings/regulator/mt6315-regulator.yaml index 37402c370fbb..364b58730be2 100644 --- a/Documentation/devicetree/bindings/regulator/mt6315-regulator.yaml +++ b/Documentation/devicetree/bindings/regulator/mt6315-regulator.yaml @@ -29,6 +29,7 @@ properties: "^vbuck[1-4]$": type: object $ref: "regulator.yaml#" + unevaluatedProperties: false properties: regulator-compatible: diff --git a/Documentation/devicetree/bindings/regulator/qcom,rpmh-regulator.yaml b/Documentation/devicetree/bindings/regulator/qcom,rpmh-regulator.yaml index 9a36bee750af..90c3bda31c23 100644 --- a/Documentation/devicetree/bindings/regulator/qcom,rpmh-regulator.yaml +++ b/Documentation/devicetree/bindings/regulator/qcom,rpmh-regulator.yaml @@ -37,6 +37,8 @@ description: | For PM6150, smps1 - smps5, ldo1 - ldo19 For PM6150L, smps1 - smps8, ldo1 - ldo11, bob For PM6350, smps1 - smps5, ldo1 - ldo22 + For PM660, smps1 - smps6, ldo1 - ldo3, ldo5 - ldo19 + For PM660L, smps1 - smps3, smps5, ldo1 - ldo8, bob For PM7325, smps1 - smps8, ldo1 - ldo19 For PM8005, smps1 - smps4 For PM8009, smps1 - smps2, ldo1 - ldo7 @@ -57,6 +59,8 @@ properties: - qcom,pm6150-rpmh-regulators - qcom,pm6150l-rpmh-regulators - qcom,pm6350-rpmh-regulators + - qcom,pm660-rpmh-regulators + - qcom,pm660l-rpmh-regulators - qcom,pm7325-rpmh-regulators - qcom,pm8005-rpmh-regulators - qcom,pm8009-rpmh-regulators @@ -99,12 +103,16 @@ properties: type: object $ref: "regulator.yaml#" description: BOB regulator node. + dependencies: + regulator-allow-set-load: ["regulator-allowed-modes"] patternProperties: "^(smps|ldo|lvs)[0-9]+$": type: object $ref: "regulator.yaml#" description: smps/ldo regulator nodes(s). + dependencies: + regulator-allow-set-load: ["regulator-allowed-modes"] required: - compatible @@ -148,6 +156,38 @@ allOf: properties: compatible: enum: + - qcom,pm660-rpmh-regulators + then: + properties: + vdd-l1-l6-l7-supply: true + vdd-l2-l3-supply: true + vdd-l5-supply: true + vdd-l8-l9-l10-l11-l12-l13-l14-supply: true + vdd-l15-l16-l17-l18-l19-supply: true + patternProperties: + "^vdd-s[1-6]-supply$": true + + - if: + properties: + compatible: + enum: + - qcom,pm660l-rpmh-regulators + then: + properties: + vdd-bob-supply: + description: BOB regulator parent supply phandle. + vdd-l1-l9-l10-supply: true + vdd-l2-supply: true + vdd-l3-l5-l7-l8-supply: true + vdd-l4-l6-supply: true + vdd-s3-s4-supply: true + patternProperties: + "^vdd-s[125]-supply$": true + + - if: + properties: + compatible: + enum: - qcom,pm7325-rpmh-regulators then: properties: diff --git a/Documentation/devicetree/bindings/regulator/qcom,smd-rpm-regulator.yaml b/Documentation/devicetree/bindings/regulator/qcom,smd-rpm-regulator.yaml index c233461cc980..961eed51912c 100644 --- a/Documentation/devicetree/bindings/regulator/qcom,smd-rpm-regulator.yaml +++ b/Documentation/devicetree/bindings/regulator/qcom,smd-rpm-regulator.yaml @@ -24,6 +24,17 @@ description: For mp5496, s2 + For pm2250, s1, s2, s3, s4, l1, l2, l3, l4, l5, l6, l7, l8, l9, l10, l11, + l12, l13, l14, l15, l16, l17, l18, l19, l20, l21, l22 + + For pm6125 s1, s2, s3, s4, s5, s6, s7, s8, l1, l2, l3, l5, l6, l7, l8, l9, + l10, l22, l12, l13, l14, l15, l16, l17, l18, l19, l20, l21, l22, l23, l24 + + For pm660, s1, s2, s3, s4, s5, s6, l1, l2, l3, l5, l6, l7, l8, l9, l10, l22, + l12, l13, l14, l15, l16, l17, l18, l19 + + For pm660l s1, s2, s3, s5, l1, l2, l3, l4, l5, l6, l7, l8, l9, l10, bob + For pm8226, s1, s2, s3, s4, s5, l1, l2, l3, l4, l5, l6, l7, l8, l9, l10, l11, l12, l13, l14, l15, l16, l17, l18, l19, l20, l21, l22, l23, l24, l25, l26, l27, l28, lvs1 @@ -52,11 +63,6 @@ description: l3, l4, l5, l6, l7, l8, l9, l10, l11, l12, l13, l14, l15, l16, l17, l18, l19, l20, l21, l22, l23, l24, l25, l26, l27, l28, lvs1, lvs2 - For pm660, s1, s2, s3, s4, s5, s6, l1, l2, l3, l5, l6, l7, l8, l9, l10, l22, - l12, l13, l14, l15, l16, l17, l18, l19 - - For pm660l s1, s2, s3, s5, l1, l2, l3, l4, l5, l6, l7, l8, l9, l10, bob - For pma8084, s1, s2, s3, s4, s5, s6, s7, s8, s9, s10, s11, s12, l1, l2, l3, l4, l5, l6, l7, l8, l9, l10, l11, l12, l13, l14, l15, l16, l17, l18, l19, l20, l21, l22, l23, l24, l25, l26, l27, lvs1, lvs2, lvs3, lvs4, 5vs1 @@ -68,9 +74,6 @@ description: For pms405, s1, s2, s3, s4, s5, l1, l2, l3, l4, l5, l6, l7, l8, l9, l10, l11, l12, l13 - For pm2250, s1, s2, s3, s4, l1, l2, l3, l4, l5, l6, l7, l8, l9, l10, l11, - l12, l13, l14, l15, l16, l17, l18, l19, l20, l21, l22 - maintainers: - Andy Gross <agross@kernel.org> - Bjorn Andersson <bjorn.andersson@linaro.org> @@ -79,6 +82,10 @@ properties: compatible: enum: - qcom,rpm-mp5496-regulators + - qcom,rpm-pm2250-regulators + - qcom,rpm-pm6125-regulators + - qcom,rpm-pm660-regulators + - qcom,rpm-pm660l-regulators - qcom,rpm-pm8226-regulators - qcom,rpm-pm8841-regulators - qcom,rpm-pm8909-regulators @@ -88,13 +95,10 @@ properties: - qcom,rpm-pm8953-regulators - qcom,rpm-pm8994-regulators - qcom,rpm-pm8998-regulators - - qcom,rpm-pm660-regulators - - qcom,rpm-pm660l-regulators - qcom,rpm-pma8084-regulators - qcom,rpm-pmi8994-regulators - qcom,rpm-pmi8998-regulators - qcom,rpm-pms405-regulators - - qcom,rpm-pm2250-regulators patternProperties: ".*-supply$": diff --git a/Documentation/devicetree/bindings/regulator/qcom,spmi-regulator.yaml b/Documentation/devicetree/bindings/regulator/qcom,spmi-regulator.yaml index 8b7c4af4b551..bdf34c2de96b 100644 --- a/Documentation/devicetree/bindings/regulator/qcom,spmi-regulator.yaml +++ b/Documentation/devicetree/bindings/regulator/qcom,spmi-regulator.yaml @@ -12,6 +12,7 @@ maintainers: properties: compatible: enum: + - qcom,pm6125-regulators - qcom,pm660-regulators - qcom,pm660l-regulators - qcom,pm8004-regulators @@ -35,6 +36,7 @@ patternProperties: description: List of regulators and its properties type: object $ref: regulator.yaml# + unevaluatedProperties: false properties: qcom,ocp-max-retries: @@ -100,8 +102,6 @@ patternProperties: SAW controlled gang leader. Will be configured as SAW regulator. type: boolean - unevaluatedProperties: false - required: - compatible @@ -111,6 +111,25 @@ allOf: compatible: contains: enum: + - qcom,pm6125-regulators + then: + properties: + vdd_l1_l7_l17_l18-supply: true + vdd_l2_l3_l4-supply: true + vdd_l5_l15_l19_l20_l21_l22-supply: true + vdd_l6_l8-supply: true + vdd_l9_l11-supply: true + vdd_l10_l13_l14-supply: true + vdd_l12_l16-supply: true + vdd_l23_l24-supply: true + patternProperties: + "^vdd_s[1-8]-supply$": true + + - if: + properties: + compatible: + contains: + enum: - qcom,pm660-regulators then: properties: @@ -121,6 +140,7 @@ allOf: vdd_l8_l9_l10_l11_l12_l13_l14-supply: true patternProperties: "^vdd_s[1-6]-supply$": true + - if: properties: compatible: @@ -135,6 +155,7 @@ allOf: vdd_l4_l6-supply: true patternProperties: "^vdd_s[1-5]-supply$": true + - if: properties: compatible: @@ -144,6 +165,7 @@ allOf: then: patternProperties: "^vdd_s[25]-supply$": true + - if: properties: compatible: @@ -153,6 +175,7 @@ allOf: then: patternProperties: "^vdd_s[1-4]-supply$": true + - if: properties: compatible: @@ -172,6 +195,7 @@ allOf: vdd_lvs1-supply: true patternProperties: "^vdd_s[1-5]-supply$": true + - if: properties: compatible: @@ -181,6 +205,7 @@ allOf: then: patternProperties: "^vdd_s[1-8]-supply$": true + - if: properties: compatible: @@ -196,6 +221,7 @@ allOf: patternProperties: "^vdd_l[27]-supply$": true "^vdd_s[1-4]-supply$": true + - if: properties: compatible: @@ -224,6 +250,7 @@ allOf: vin_5vs-supply: true patternProperties: "^vdd_s[1-3]-supply$": true + - if: properties: compatible: @@ -242,6 +269,7 @@ allOf: vdd_l9_l10_l13_l14_l15_l18-supply: true patternProperties: "^vdd_s[1-6]-supply$": true + - if: properties: compatible: @@ -266,6 +294,7 @@ allOf: vdd_lvs_1_2-supply: true patternProperties: "^vdd_s[1-9][0-2]?-supply$": true + - if: properties: compatible: @@ -277,6 +306,7 @@ allOf: vdd_l1-supply: true patternProperties: "^vdd_s[1-3]-supply$": true + - if: properties: compatible: @@ -292,6 +322,7 @@ allOf: patternProperties: "^vdd_l[479]-supply$": true "^vdd_s[1-5]-supply$": true + - if: properties: compatible: diff --git a/Documentation/devicetree/bindings/regulator/qcom-labibb-regulator.yaml b/Documentation/devicetree/bindings/regulator/qcom-labibb-regulator.yaml index 1ddc1efd19e2..f97b8083678f 100644 --- a/Documentation/devicetree/bindings/regulator/qcom-labibb-regulator.yaml +++ b/Documentation/devicetree/bindings/regulator/qcom-labibb-regulator.yaml @@ -20,6 +20,7 @@ properties: lab: type: object + additionalProperties: false properties: qcom,soft-start-us: @@ -33,11 +34,19 @@ properties: description: Short-circuit and over-current interrupts for lab. + interrupt-names: + minItems: 1 + items: + - const: sc-err + - const: ocp + required: - interrupts + - interrupt-names ibb: type: object + additionalProperties: false properties: qcom,discharge-resistor-kohms: @@ -52,8 +61,15 @@ properties: description: Short-circuit and over-current interrupts for ibb. + interrupt-names: + minItems: 1 + items: + - const: sc-err + - const: ocp + required: - interrupts + - interrupt-names required: - compatible diff --git a/Documentation/devicetree/bindings/regulator/richtek,rt4801-regulator.yaml b/Documentation/devicetree/bindings/regulator/richtek,rt4801-regulator.yaml index 091150c4e579..4a8a221bc902 100644 --- a/Documentation/devicetree/bindings/regulator/richtek,rt4801-regulator.yaml +++ b/Documentation/devicetree/bindings/regulator/richtek,rt4801-regulator.yaml @@ -42,6 +42,7 @@ patternProperties: "^DSV(P|N)$": type: object $ref: regulator.yaml# + unevaluatedProperties: false description: Properties for single display bias regulator. diff --git a/Documentation/devicetree/bindings/regulator/rohm,bd71815-regulator.yaml b/Documentation/devicetree/bindings/regulator/rohm,bd71815-regulator.yaml index 7d0adb74a396..d61e8675f067 100644 --- a/Documentation/devicetree/bindings/regulator/rohm,bd71815-regulator.yaml +++ b/Documentation/devicetree/bindings/regulator/rohm,bd71815-regulator.yaml @@ -27,6 +27,7 @@ properties: description: properties for wled regulator $ref: regulator.yaml# + unevaluatedProperties: false properties: regulator-name: diff --git a/Documentation/devicetree/bindings/regulator/ti,tps65219.yaml b/Documentation/devicetree/bindings/regulator/ti,tps65219.yaml new file mode 100644 index 000000000000..78be79930fda --- /dev/null +++ b/Documentation/devicetree/bindings/regulator/ti,tps65219.yaml @@ -0,0 +1,173 @@ +# SPDX-License-Identifier: GPL-2.0-only OR BSD-2-Clause +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/regulator/ti,tps65219.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: TI tps65219 Power Management Integrated Circuit regulators + +maintainers: + - Jerome Neanne <jerome.neanne@baylibre.com> + +description: | + Regulator nodes should be named to buck<number> and ldo<number>. + +properties: + compatible: + enum: + - ti,tps65219 + + reg: + maxItems: 1 + + system-power-controller: + type: boolean + description: Optional property that indicates that this device is + controlling system power. + + interrupts: + description: Short-circuit, over-current, under-voltage for regulators, PB interrupts. + maxItems: 1 + + interrupt-controller: true + + '#interrupt-cells': + description: Specifies the PIN numbers and Flags, as defined in + include/dt-bindings/interrupt-controller/irq.h + const: 1 + + ti,power-button: + type: boolean + description: | + Optional property that sets the EN/PB/VSENSE pin to be a + power-button. + TPS65219 has a multipurpose pin called EN/PB/VSENSE that can be either + 1. EN in which case it functions as an enable pin. + 2. VSENSE which compares the voltages and triggers an automatic + on/off request. + 3. PB in which case it can be configured to trigger an interrupt + to the SoC. + ti,power-button reflects the last one of those options + where the board has a button wired to the pin and triggers + an interrupt on pressing it. + +patternProperties: + "^buck[1-3]-supply$": + description: Input supply phandle of one regulator. + + "^ldo[1-4]-supply$": + description: Input supply phandle of one regulator. + + regulators: + type: object + description: | + list of regulators provided by this controller + + patternProperties: + "^ldo[1-4]$": + type: object + $ref: regulator.yaml# + description: + Properties for single LDO regulator. + + unevaluatedProperties: false + + "^buck[1-3]$": + type: object + $ref: regulator.yaml# + description: + Properties for single BUCK regulator. + + unevaluatedProperties: false + + additionalProperties: false + +required: + - compatible + - reg + - interrupts + - regulators + +additionalProperties: false + +examples: + - | + #include <dt-bindings/interrupt-controller/arm-gic.h> + i2c { + #address-cells = <1>; + #size-cells = <0>; + + tps65219: pmic@30 { + compatible = "ti,tps65219"; + reg = <0x30>; + buck1-supply = <&vcc_3v3_sys>; + buck2-supply = <&vcc_3v3_sys>; + buck3-supply = <&vcc_3v3_sys>; + ldo1-supply = <&vcc_3v3_sys>; + ldo2-supply = <&buck2_reg>; + ldo3-supply = <&vcc_3v3_sys>; + ldo4-supply = <&vcc_3v3_sys>; + + pinctrl-0 = <&pmic_irq_pins_default>; + + interrupt-parent = <&gic500>; + interrupts = <GIC_SPI 224 IRQ_TYPE_LEVEL_HIGH>; + ti,power-button; + + regulators { + buck1_reg: buck1 { + regulator-name = "VDD_CORE"; + regulator-min-microvolt = <750000>; + regulator-max-microvolt = <750000>; + regulator-boot-on; + regulator-always-on; + }; + + buck2_reg: buck2 { + regulator-name = "VCC1V8"; + regulator-min-microvolt = <1800000>; + regulator-max-microvolt = <1800000>; + regulator-boot-on; + regulator-always-on; + }; + + buck3_reg: buck3 { + regulator-name = "VDD_LPDDR4"; + regulator-min-microvolt = <1100000>; + regulator-max-microvolt = <1100000>; + regulator-boot-on; + regulator-always-on; + }; + + ldo1_reg: ldo1 { + regulator-name = "VDDSHV_SD_IO_PMIC"; + regulator-min-microvolt = <33000000>; + regulator-max-microvolt = <33000000>; + }; + + ldo2_reg: ldo2 { + regulator-name = "VDDAR_CORE"; + regulator-min-microvolt = <850000>; + regulator-max-microvolt = <850000>; + regulator-boot-on; + regulator-always-on; + }; + + ldo3_reg: ldo3 { + regulator-name = "VDDA_1V8"; + regulator-min-microvolt = <18000000>; + regulator-max-microvolt = <18000000>; + regulator-boot-on; + regulator-always-on; + }; + + ldo4_reg: ldo4 { + regulator-name = "VDD_PHY_2V5"; + regulator-min-microvolt = <25000000>; + regulator-max-microvolt = <25000000>; + regulator-boot-on; + regulator-always-on; + }; + }; + }; + }; diff --git a/Documentation/devicetree/bindings/reset/amlogic,meson-reset.yaml b/Documentation/devicetree/bindings/reset/amlogic,meson-reset.yaml index 494a454928ce..98db2aa74dc8 100644 --- a/Documentation/devicetree/bindings/reset/amlogic,meson-reset.yaml +++ b/Documentation/devicetree/bindings/reset/amlogic,meson-reset.yaml @@ -8,7 +8,7 @@ $schema: "http://devicetree.org/meta-schemas/core.yaml#" title: Amlogic Meson SoC Reset Controller maintainers: - - Neil Armstrong <narmstrong@baylibre.com> + - Neil Armstrong <neil.armstrong@linaro.org> properties: compatible: diff --git a/Documentation/devicetree/bindings/riscv/sifive-l2-cache.yaml b/Documentation/devicetree/bindings/riscv/sifive-l2-cache.yaml index 69cdab18d629..ca3b9be58058 100644 --- a/Documentation/devicetree/bindings/riscv/sifive-l2-cache.yaml +++ b/Documentation/devicetree/bindings/riscv/sifive-l2-cache.yaml @@ -17,9 +17,6 @@ description: acts as directory-based coherency manager. All the properties in ePAPR/DeviceTree specification applies for this platform. -allOf: - - $ref: /schemas/cache-controller.yaml# - select: properties: compatible: @@ -33,11 +30,16 @@ select: properties: compatible: - items: - - enum: - - sifive,fu540-c000-ccache - - sifive,fu740-c000-ccache - - const: cache + oneOf: + - items: + - enum: + - sifive,fu540-c000-ccache + - sifive,fu740-c000-ccache + - const: cache + - items: + - const: microchip,mpfs-ccache + - const: sifive,fu540-c000-ccache + - const: cache cache-block-size: const: 64 @@ -72,29 +74,46 @@ properties: The reference to the reserved-memory for the L2 Loosely Integrated Memory region. The reserved memory node should be defined as per the bindings in reserved-memory.txt. -if: - properties: - compatible: - contains: - const: sifive,fu540-c000-ccache +allOf: + - $ref: /schemas/cache-controller.yaml# -then: - properties: - interrupts: - description: | - Must contain entries for DirError, DataError and DataFail signals. - maxItems: 3 - cache-sets: - const: 1024 - -else: - properties: - interrupts: - description: | - Must contain entries for DirError, DataError, DataFail, DirFail signals. - minItems: 4 - cache-sets: - const: 2048 + - if: + properties: + compatible: + contains: + enum: + - sifive,fu740-c000-ccache + - microchip,mpfs-ccache + + then: + properties: + interrupts: + description: | + Must contain entries for DirError, DataError, DataFail, DirFail signals. + minItems: 4 + + else: + properties: + interrupts: + description: | + Must contain entries for DirError, DataError and DataFail signals. + maxItems: 3 + + - if: + properties: + compatible: + contains: + const: sifive,fu740-c000-ccache + + then: + properties: + cache-sets: + const: 2048 + + else: + properties: + cache-sets: + const: 1024 additionalProperties: false diff --git a/Documentation/devicetree/bindings/rng/amlogic,meson-rng.yaml b/Documentation/devicetree/bindings/rng/amlogic,meson-rng.yaml index 444be32a8a29..09c6c906b1f9 100644 --- a/Documentation/devicetree/bindings/rng/amlogic,meson-rng.yaml +++ b/Documentation/devicetree/bindings/rng/amlogic,meson-rng.yaml @@ -8,7 +8,7 @@ $schema: "http://devicetree.org/meta-schemas/core.yaml#" title: Amlogic Meson Random number generator maintainers: - - Neil Armstrong <narmstrong@baylibre.com> + - Neil Armstrong <neil.armstrong@linaro.org> properties: compatible: diff --git a/Documentation/devicetree/bindings/serial/amlogic,meson-uart.yaml b/Documentation/devicetree/bindings/serial/amlogic,meson-uart.yaml index 72e8868db3e0..7822705ad16c 100644 --- a/Documentation/devicetree/bindings/serial/amlogic,meson-uart.yaml +++ b/Documentation/devicetree/bindings/serial/amlogic,meson-uart.yaml @@ -8,7 +8,7 @@ $schema: "http://devicetree.org/meta-schemas/core.yaml#" title: Amlogic Meson SoC UART Serial Interface maintainers: - - Neil Armstrong <narmstrong@baylibre.com> + - Neil Armstrong <neil.armstrong@linaro.org> description: | The Amlogic Meson SoC UART Serial Interface is present on a large range diff --git a/Documentation/devicetree/bindings/soc/amlogic/amlogic,canvas.yaml b/Documentation/devicetree/bindings/soc/amlogic/amlogic,canvas.yaml index 17db87cb9dab..c3c599096353 100644 --- a/Documentation/devicetree/bindings/soc/amlogic/amlogic,canvas.yaml +++ b/Documentation/devicetree/bindings/soc/amlogic/amlogic,canvas.yaml @@ -8,7 +8,7 @@ $schema: "http://devicetree.org/meta-schemas/core.yaml#" title: Amlogic Canvas Video Lookup Table maintainers: - - Neil Armstrong <narmstrong@baylibre.com> + - Neil Armstrong <neil.armstrong@linaro.org> - Maxime Jourdan <mjourdan@baylibre.com> description: | diff --git a/Documentation/devicetree/bindings/soc/qcom/qcom,apr.yaml b/Documentation/devicetree/bindings/soc/qcom/qcom,apr.yaml index 028c5d105adb..f47491aab3b1 100644 --- a/Documentation/devicetree/bindings/soc/qcom/qcom,apr.yaml +++ b/Documentation/devicetree/bindings/soc/qcom/qcom,apr.yaml @@ -20,6 +20,9 @@ properties: - qcom,apr-v2 - qcom,gpr + power-domains: + maxItems: 1 + qcom,apr-domain: $ref: /schemas/types.yaml#/definitions/uint32 enum: [1, 2, 3, 4, 5, 6, 7] @@ -52,6 +55,26 @@ properties: 2 = Audio DSP Domain 3 = Application Processor Domain + qcom,glink-channels: + $ref: /schemas/types.yaml#/definitions/string-array + description: Channel name used for the communication + items: + - const: apr_audio_svc + + qcom,intents: + $ref: /schemas/types.yaml#/definitions/uint32-array + description: + List of (size, amount) pairs describing what intents should be + preallocated for this virtual channel. This can be used to tweak the + default intents available for the channel to meet expectations of the + remote. + + qcom,smd-channels: + $ref: /schemas/types.yaml#/definitions/string-array + description: Channel name used for the communication + items: + - const: apr_audio_svc + '#address-cells': const: 1 @@ -97,6 +120,26 @@ patternProperties: 3 = AMDB Service. 4 = Voice processing manager. + clock-controller: + $ref: /schemas/sound/qcom,q6dsp-lpass-clocks.yaml# + description: Qualcomm DSP LPASS clock controller + unevaluatedProperties: false + + dais: + type: object + oneOf: + - $ref: /schemas/sound/qcom,q6apm-dai.yaml# + - $ref: /schemas/sound/qcom,q6dsp-lpass-ports.yaml# + - $ref: /schemas/sound/qcom,q6asm-dais.yaml# + unevaluatedProperties: false + description: Qualcomm DSP audio ports + + routing: + type: object + $ref: /schemas/sound/qcom,q6adm-routing.yaml# + unevaluatedProperties: false + description: Qualcomm DSP LPASS audio routing + qcom,protection-domain: $ref: /schemas/types.yaml#/definitions/string-array description: protection domain service name and path for apr service @@ -107,17 +150,44 @@ patternProperties: "tms/servreg", "msm/modem/wlan_pd". "tms/servreg", "msm/slpi/sensor_pd". - '#address-cells': - const: 1 + allOf: + - if: + properties: + compatible: + enum: + - qcom,q6afe + then: + properties: + dais: + properties: + compatible: + const: qcom,q6afe-dais - '#size-cells': - const: 0 + - if: + properties: + compatible: + enum: + - qcom,q6apm + then: + properties: + dais: + properties: + compatible: + enum: + - qcom,q6apm-dais + - qcom,q6apm-lpass-dais - patternProperties: - "^.*@[0-9a-f]+$": - type: object - description: - Service based devices like clock controllers or digital audio interfaces. + - if: + properties: + compatible: + enum: + - qcom,q6asm + then: + properties: + dais: + properties: + compatible: + const: qcom,q6asm-dais additionalProperties: false @@ -125,6 +195,30 @@ required: - compatible - qcom,domain +allOf: + - if: + properties: + compatible: + enum: + - qcom,gpr + then: + properties: + power-domains: false + + - if: + required: + - qcom,glink-channels + then: + properties: + qcom,smd-channels: false + + - if: + required: + - qcom,smd-channels + then: + properties: + qcom,glink-channels: false + additionalProperties: false examples: diff --git a/Documentation/devicetree/bindings/sound/adi,max98396.yaml b/Documentation/devicetree/bindings/sound/adi,max98396.yaml index 8d2ef991db40..7985b1410017 100644 --- a/Documentation/devicetree/bindings/sound/adi,max98396.yaml +++ b/Documentation/devicetree/bindings/sound/adi,max98396.yaml @@ -78,6 +78,40 @@ properties: interleaved on a single output channel. type: boolean + adi,dmon-stuck-enable: + description: + Enables the "data monitor stuck" feature. Once the data monitor is + enabled, it actively monitors the selected input data (from DIN) to the + speaker amplifier. Once a data error is detected, the data monitor + automatically places the device into software shutdown. + type: boolean + + adi,dmon-stuck-threshold-bits: + description: + Sets the threshold for the "data monitor stuck" feature, in bits. + enum: [9, 11, 13, 15] + default: 15 + + adi,dmon-magnitude-enable: + description: + Enables the "data monitor magnitude" feature. Once the data monitor is + enabled, it actively monitors the selected input data (from DIN) to the + speaker amplifier. Once a data error is detected, the data monitor + automatically places the device into software shutdown. + type: boolean + + adi,dmon-magnitude-threshold-bits: + description: + Sets the threshold for the "data monitor magnitude" feature, in bits. + enum: [2, 3, 4, 5] + default: 5 + + adi,dmon-duration-ms: + description: + Sets the duration for the "data monitor" feature, in milliseconds. + enum: [64, 256, 1024, 4096] + default: 64 + reset-gpios: maxItems: 1 diff --git a/Documentation/devicetree/bindings/sound/allwinner,sun50i-h6-dmic.yaml b/Documentation/devicetree/bindings/sound/allwinner,sun50i-h6-dmic.yaml new file mode 100644 index 000000000000..2f12cabe4c71 --- /dev/null +++ b/Documentation/devicetree/bindings/sound/allwinner,sun50i-h6-dmic.yaml @@ -0,0 +1,79 @@ +# SPDX-License-Identifier: (GPL-2.0+ OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/sound/allwinner,sun50i-h6-dmic.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Allwinner H6 DMIC + +maintainers: + - Ban Tao <fengzheng923@gmail.com> + +properties: + compatible: + const: allwinner,sun50i-h6-dmic + + "#sound-dai-cells": + const: 0 + + reg: + maxItems: 1 + + interrupts: + maxItems: 1 + + clocks: + items: + - description: Bus Clock + - description: Module Clock + + clock-names: + items: + - const: bus + - const: mod + + dmas: + items: + - description: RX DMA Channel + + dma-names: + items: + - const: rx + + resets: + maxItems: 1 + +required: + - "#sound-dai-cells" + - compatible + - reg + - interrupts + - clocks + - clock-names + - dmas + - dma-names + - resets + +additionalProperties: false + +examples: + - | + #include <dt-bindings/interrupt-controller/arm-gic.h> + #include <dt-bindings/interrupt-controller/irq.h> + + #include <dt-bindings/clock/sun50i-h6-ccu.h> + #include <dt-bindings/reset/sun50i-h6-ccu.h> + + dmic: dmic@5095000 { + #sound-dai-cells = <0>; + compatible = "allwinner,sun50i-h6-dmic"; + reg = <0x05095000 0x400>; + interrupts = <GIC_SPI 22 IRQ_TYPE_LEVEL_HIGH>; + clocks = <&ccu CLK_BUS_DMIC>, <&ccu CLK_DMIC>; + clock-names = "bus", "mod"; + dmas = <&dma 7>; + dma-names = "rx"; + resets = <&ccu RST_BUS_DMIC>; + }; + +... diff --git a/Documentation/devicetree/bindings/sound/amlogic,gx-sound-card.yaml b/Documentation/devicetree/bindings/sound/amlogic,gx-sound-card.yaml index b4b35edcb493..5b8d59245f82 100644 --- a/Documentation/devicetree/bindings/sound/amlogic,gx-sound-card.yaml +++ b/Documentation/devicetree/bindings/sound/amlogic,gx-sound-card.yaml @@ -40,6 +40,7 @@ properties: patternProperties: "^dai-link-[0-9]+$": type: object + additionalProperties: false description: |- dai-link child nodes: Container for dai-link level properties and the CODEC sub-nodes. @@ -63,6 +64,7 @@ patternProperties: patternProperties: "^codec-[0-9]+$": type: object + additionalProperties: false description: |- Codecs: dai-link representing backend links should have at least one subnode. diff --git a/Documentation/devicetree/bindings/sound/apple,mca.yaml b/Documentation/devicetree/bindings/sound/apple,mca.yaml new file mode 100644 index 000000000000..d5dc92b5b654 --- /dev/null +++ b/Documentation/devicetree/bindings/sound/apple,mca.yaml @@ -0,0 +1,131 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/sound/apple,mca.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Apple MCA I2S transceiver + +description: | + MCA is an I2S transceiver peripheral found on M1 and other Apple chips. It is + composed of a number of identical clusters which can operate independently + or in an interlinked fashion. Up to 6 clusters have been seen on an MCA. + +maintainers: + - Martin PoviÅ¡er <povik+lin@cutebit.org> + +properties: + compatible: + items: + - enum: + - apple,t6000-mca + - apple,t8103-mca + - const: apple,mca + + reg: + items: + - description: Register region of the MCA clusters proper + - description: Register region of the DMA glue and its FIFOs + + interrupts: + minItems: 4 + maxItems: 6 + description: + One interrupt per each cluster + + '#address-cells': + const: 1 + + '#size-cells': + const: 0 + + dmas: + minItems: 16 + maxItems: 24 + description: + DMA channels corresponding to the SERDES units in the peripheral. They are + listed in groups of four per cluster, and within the group they are given + as associated to the TXA, RXA, TXB, RXB units. + + dma-names: + minItems: 16 + items: + - const: tx0a + - const: rx0a + - const: tx0b + - const: rx0b + - const: tx1a + - const: rx1a + - const: tx1b + - const: rx1b + - const: tx2a + - const: rx2a + - const: tx2b + - const: rx2b + - const: tx3a + - const: rx3a + - const: tx3b + - const: rx3b + - const: tx4a + - const: rx4a + - const: tx4b + - const: rx4b + - const: tx5a + - const: rx5a + - const: tx5b + - const: rx5b + description: | + Names for the DMA channels: 'tx'/'rx', then cluster number, then 'a'/'b' + based on the associated SERDES unit. + + clocks: + minItems: 4 + maxItems: 6 + description: + Clusters' input reference clock. + + resets: + maxItems: 1 + + power-domains: + minItems: 5 + maxItems: 7 + description: + First a general power domain for register access, then the power + domains of individual clusters for their operation. + + '#sound-dai-cells': + const: 1 + +required: + - compatible + - reg + - dmas + - dma-names + - clocks + - power-domains + - '#sound-dai-cells' + +additionalProperties: false + +examples: + - | + mca: i2s@9b600000 { + compatible = "apple,t6000-mca", "apple,mca"; + reg = <0x9b600000 0x10000>, + <0x9b200000 0x20000>; + + clocks = <&nco 0>, <&nco 1>, <&nco 2>, <&nco 3>; + power-domains = <&ps_audio_p>, <&ps_mca0>, <&ps_mca1>, + <&ps_mca2>, <&ps_mca3>; + dmas = <&admac 0>, <&admac 1>, <&admac 2>, <&admac 3>, + <&admac 4>, <&admac 5>, <&admac 6>, <&admac 7>, + <&admac 8>, <&admac 9>, <&admac 10>, <&admac 11>, + <&admac 12>, <&admac 13>, <&admac 14>, <&admac 15>; + dma-names = "tx0a", "rx0a", "tx0b", "rx0b", + "tx1a", "rx1a", "tx1b", "rx1b", + "tx2a", "rx2a", "tx2b", "rx2b", + "tx3a", "rx3a", "tx3b", "rx3b"; + + #sound-dai-cells = <1>; + }; diff --git a/Documentation/devicetree/bindings/sound/audio-graph-port.yaml b/Documentation/devicetree/bindings/sound/audio-graph-port.yaml index 5c368674d11a..64654ceef208 100644 --- a/Documentation/devicetree/bindings/sound/audio-graph-port.yaml +++ b/Documentation/devicetree/bindings/sound/audio-graph-port.yaml @@ -19,14 +19,17 @@ properties: description: "device name prefix" $ref: /schemas/types.yaml#/definitions/string convert-rate: - description: CPU to Codec rate convert. - $ref: /schemas/types.yaml#/definitions/uint32 + $ref: "/schemas/sound/dai-params.yaml#/$defs/dai-sample-rate" convert-channels: - description: CPU to Codec rate channels. - $ref: /schemas/types.yaml#/definitions/uint32 + $ref: "/schemas/sound/dai-params.yaml#/$defs/dai-channels" + convert-sample-format: + $ref: "/schemas/sound/dai-params.yaml#/$defs/dai-sample-format" + patternProperties: "^endpoint(@[0-9a-f]+)?": $ref: /schemas/graph.yaml#/$defs/endpoint-base + unevaluatedProperties: false + properties: mclk-fs: description: | @@ -65,12 +68,18 @@ patternProperties: - msb - lsb convert-rate: - description: CPU to Codec rate convert. - $ref: /schemas/types.yaml#/definitions/uint32 + $ref: "/schemas/sound/dai-params.yaml#/$defs/dai-sample-rate" convert-channels: - description: CPU to Codec rate channels. - $ref: /schemas/types.yaml#/definitions/uint32 + $ref: "/schemas/sound/dai-params.yaml#/$defs/dai-channels" + convert-sample-format: + $ref: "/schemas/sound/dai-params.yaml#/$defs/dai-sample-format" + dai-tdm-slot-num: + description: Number of slots in use. + $ref: /schemas/types.yaml#/definitions/uint32 + dai-tdm-slot-width: + description: Width in bits for each slot. + $ref: /schemas/types.yaml#/definitions/uint32 dai-tdm-slot-width-map: description: Mapping of sample widths to slot widths. For hardware that cannot support a fixed slot width or a slot width always diff --git a/Documentation/devicetree/bindings/sound/audio-graph.yaml b/Documentation/devicetree/bindings/sound/audio-graph.yaml index 4b46794e5153..aaa99c2deda0 100644 --- a/Documentation/devicetree/bindings/sound/audio-graph.yaml +++ b/Documentation/devicetree/bindings/sound/audio-graph.yaml @@ -27,11 +27,12 @@ properties: description: User specified audio sound widgets. $ref: /schemas/types.yaml#/definitions/non-unique-string-array convert-rate: - description: CPU to Codec rate convert. - $ref: /schemas/types.yaml#/definitions/uint32 + $ref: "/schemas/sound/dai-params.yaml#/$defs/dai-sample-rate" convert-channels: - description: CPU to Codec rate channels. - $ref: /schemas/types.yaml#/definitions/uint32 + $ref: "/schemas/sound/dai-params.yaml#/$defs/dai-channels" + convert-sample-format: + $ref: "/schemas/sound/dai-params.yaml#/$defs/dai-sample-format" + pa-gpios: maxItems: 1 hp-det-gpio: diff --git a/Documentation/devicetree/bindings/sound/cirrus,cs42l42.yaml b/Documentation/devicetree/bindings/sound/cirrus,cs42l42.yaml index 31800f70e9d9..7356084a2ca2 100644 --- a/Documentation/devicetree/bindings/sound/cirrus,cs42l42.yaml +++ b/Documentation/devicetree/bindings/sound/cirrus,cs42l42.yaml @@ -19,6 +19,7 @@ properties: compatible: enum: - cirrus,cs42l42 + - cirrus,cs42l83 reg: description: diff --git a/Documentation/devicetree/bindings/sound/dai-params.yaml b/Documentation/devicetree/bindings/sound/dai-params.yaml new file mode 100644 index 000000000000..f5fb71f9b603 --- /dev/null +++ b/Documentation/devicetree/bindings/sound/dai-params.yaml @@ -0,0 +1,40 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/sound/dai-params.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Digital Audio Interface (DAI) Stream Parameters + +maintainers: + - Kuninori Morimoto <kuninori.morimoto.gx@renesas.com> + +select: false + +$defs: + + dai-channels: + description: Number of audio channels used by DAI + $ref: /schemas/types.yaml#/definitions/uint32 + minimum: 1 + maximum: 32 + + dai-sample-format: + description: Audio sample format used by DAI + $ref: /schemas/types.yaml#/definitions/string + enum: + - s8 + - s16_le + - s24_le + - s24_3le + - s32_le + + dai-sample-rate: + description: Audio sample rate used by DAI + $ref: /schemas/types.yaml#/definitions/uint32 + minimum: 8000 + maximum: 192000 + +properties: {} + +additionalProperties: true diff --git a/Documentation/devicetree/bindings/sound/everest,es8326.yaml b/Documentation/devicetree/bindings/sound/everest,es8326.yaml new file mode 100755 index 000000000000..07781408e788 --- /dev/null +++ b/Documentation/devicetree/bindings/sound/everest,es8326.yaml @@ -0,0 +1,116 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/sound/everest,es8326.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Everest ES8326 audio CODEC + +maintainers: + - David Yang <yangxiaohua@everest-semi.com> + +properties: + compatible: + const: everest,es8326 + + reg: + maxItems: 1 + + clocks: + items: + - description: clock for master clock (MCLK) + + clock-names: + items: + - const: mclk + + "#sound-dai-cells": + const: 0 + + everest,jack-pol: + $ref: /schemas/types.yaml#/definitions/uint8 + description: | + just the value of reg 57. Bit(3) decides whether the jack polarity is inverted. + Bit(2) decides whether the button on the headset is inverted. + Bit(1)/(0) decides the mic properity to be OMTP/CTIA or auto. + minimum: 0x00 + maximum: 0x0f + default: 0x0f + + everest,mic1-src: + $ref: /schemas/types.yaml#/definitions/uint8 + description: + the value of reg 2A when headset plugged. + minimum: 0x00 + maximum: 0x77 + default: 0x22 + + everest,mic2-src: + $ref: /schemas/types.yaml#/definitions/uint8 + description: + the value of reg 2A when headset unplugged. + minimum: 0x00 + maximum: 0x77 + default: 0x44 + + everest,jack-detect-inverted: + $ref: /schemas/types.yaml#/definitions/flag + description: + Defined to invert the jack detection. + + everest,interrupt-src: + $ref: /schemas/types.yaml#/definitions/uint8 + description: | + value of reg 0x58, Defines the interrupt source. + Bit(2) 1 means button press triggers irq, 0 means not. + Bit(3) 1 means PIN9 is the irq source for jack detection. When set to 0, + bias change on PIN9 do not triggers irq. + Bit(4) 1 means PIN27 is the irq source for jack detection. + Bit(5) 1 means PIN9 is the irq source after MIC detect. + Bit(6) 1 means PIN27 is the irq source after MIC detect. + minimum: 0 + maximum: 0x3c + default: 0x08 + + everest,interrupt-clk: + $ref: /schemas/types.yaml#/definitions/uint8 + description: | + value of reg 0x59, Defines the interrupt output behavior. + Bit(0-3) 0 means irq pulse equals 512*internal clock + 1 means irq pulse equals 1024*internal clock + 2 means ... + 7 means irq pulse equals 65536*internal clock + 8 means irq mutes PA + 9 means irq mutes PA and DAC output + Bit(4) 1 means we invert the interrupt output. + Bit(6) 1 means the chip do not detect jack type after button released. + 0 means the chip detect jack type again after button released. + minimum: 0 + maximum: 0x7f + default: 0x45 + +required: + - compatible + - reg + - "#sound-dai-cells" + +additionalProperties: false + +examples: + - | + i2c { + #address-cells = <1>; + #size-cells = <0>; + es8326: codec@19 { + compatible = "everest,es8326"; + reg = <0x19>; + clocks = <&clks 10>; + clock-names = "mclk"; + #sound-dai-cells = <0>; + everest,mic1-src = [22]; + everest,mic2-src = [44]; + everest,jack-pol = [0e]; + everest,interrupt-src = [08]; + everest,interrupt-clk = [45]; + }; + }; diff --git a/Documentation/devicetree/bindings/sound/fsl,sai.yaml b/Documentation/devicetree/bindings/sound/fsl,sai.yaml new file mode 100644 index 000000000000..70c4111d59c7 --- /dev/null +++ b/Documentation/devicetree/bindings/sound/fsl,sai.yaml @@ -0,0 +1,216 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/sound/fsl,sai.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Freescale Synchronous Audio Interface (SAI). + +maintainers: + - Shengjiu Wang <shengjiu.wang@nxp.com> + +description: | + The SAI is based on I2S module that used communicating with audio codecs, + which provides a synchronous audio interface that supports fullduplex + serial interfaces with frame synchronization such as I2S, AC97, TDM, and + codec/DSP interfaces. + +properties: + compatible: + oneOf: + - enum: + - fsl,vf610-sai + - fsl,imx6sx-sai + - fsl,imx6ul-sai + - fsl,imx7ulp-sai + - fsl,imx8mq-sai + - fsl,imx8qm-sai + - fsl,imx8ulp-sai + - items: + - enum: + - fsl,imx8mm-sai + - fsl,imx8mn-sai + - fsl,imx8mp-sai + - const: fsl,imx8mq-sai + + reg: + maxItems: 1 + + interrupts: + items: + - description: receive and transmit interrupt + + dmas: + maxItems: 2 + + dma-names: + maxItems: 2 + + clocks: + items: + - description: The ipg clock for register access + - description: master clock source 0 (obsoleted) + - description: master clock source 1 + - description: master clock source 2 + - description: master clock source 3 + - description: PLL clock source for 8kHz series + - description: PLL clock source for 11kHz series + minItems: 4 + + clock-names: + oneOf: + - items: + - const: bus + - const: mclk0 + - const: mclk1 + - const: mclk2 + - const: mclk3 + - const: pll8k + - const: pll11k + minItems: 4 + - items: + - const: bus + - const: mclk1 + - const: mclk2 + - const: mclk3 + - const: pll8k + - const: pll11k + minItems: 4 + + lsb-first: + description: | + Configures whether the LSB or the MSB is transmitted + first for the fifo data. If this property is absent, + the MSB is transmitted first as default, or the LSB + is transmitted first. + type: boolean + + big-endian: + description: | + required if all the SAI registers are big-endian rather than little-endian. + type: boolean + + fsl,sai-synchronous-rx: + description: | + SAI will work in the synchronous mode (sync Tx with Rx) which means + both the transmitter and the receiver will send and receive data by + following receiver's bit clocks and frame sync clocks. + type: boolean + + fsl,sai-asynchronous: + description: | + SAI will work in the asynchronous mode, which means both transmitter + and receiver will send and receive data by following their own bit clocks + and frame sync clocks separately. + If both fsl,sai-asynchronous and fsl,sai-synchronous-rx are absent, the + default synchronous mode (sync Rx with Tx) will be used, which means both + transmitter and receiver will send and receive data by following clocks + of transmitter. + type: boolean + + fsl,dataline: + $ref: /schemas/types.yaml#/definitions/uint32-matrix + description: | + Configure the dataline. It has 3 value for each configuration + maxItems: 16 + items: + items: + - description: format Default(0), I2S(1) or PDM(2) + enum: [0, 1, 2] + - description: dataline mask for 'rx' + - description: dataline mask for 'tx' + + fsl,sai-mclk-direction-output: + description: SAI will output the SAI MCLK clock. + type: boolean + + fsl,shared-interrupt: + description: Interrupt is shared with other modules. + type: boolean + + "#sound-dai-cells": + const: 0 + description: optional, some dts node didn't add it. + +allOf: + - if: + properties: + compatible: + contains: + const: fsl,vf610-sai + then: + properties: + dmas: + items: + - description: DMA controller phandle and request line for TX + - description: DMA controller phandle and request line for RX + dma-names: + items: + - const: tx + - const: rx + else: + properties: + dmas: + items: + - description: DMA controller phandle and request line for RX + - description: DMA controller phandle and request line for TX + dma-names: + items: + - const: rx + - const: tx + - if: + required: + - fsl,sai-asynchronous + then: + properties: + fsl,sai-synchronous-rx: false + +required: + - compatible + - reg + - interrupts + - dmas + - dma-names + - clocks + - clock-names + +additionalProperties: false + +examples: + - | + #include <dt-bindings/interrupt-controller/arm-gic.h> + #include <dt-bindings/clock/vf610-clock.h> + sai2: sai@40031000 { + compatible = "fsl,vf610-sai"; + reg = <0x40031000 0x1000>; + interrupts = <86 IRQ_TYPE_LEVEL_HIGH>; + pinctrl-names = "default"; + pinctrl-0 = <&pinctrl_sai2_1>; + clocks = <&clks VF610_CLK_PLATFORM_BUS>, + <&clks VF610_CLK_SAI2>, + <&clks 0>, <&clks 0>; + clock-names = "bus", "mclk1", "mclk2", "mclk3"; + dma-names = "tx", "rx"; + dmas = <&edma0 0 21>, + <&edma0 0 20>; + big-endian; + lsb-first; + }; + + - | + #include <dt-bindings/interrupt-controller/arm-gic.h> + #include <dt-bindings/clock/imx8mm-clock.h> + sai1: sai@30010000 { + compatible = "fsl,imx8mm-sai", "fsl,imx8mq-sai"; + reg = <0x30010000 0x10000>; + interrupts = <GIC_SPI 95 IRQ_TYPE_LEVEL_HIGH>; + clocks = <&clk IMX8MM_CLK_SAI1_IPG>, + <&clk IMX8MM_CLK_DUMMY>, + <&clk IMX8MM_CLK_SAI1_ROOT>, + <&clk IMX8MM_CLK_DUMMY>, <&clk IMX8MM_CLK_DUMMY>; + clock-names = "bus", "mclk0", "mclk1", "mclk2", "mclk3"; + dmas = <&sdma2 0 2 0>, <&sdma2 1 2 0>; + dma-names = "rx", "tx"; + fsl,dataline = <1 0xff 0xff 2 0xff 0x11>; + #sound-dai-cells = <0>; + }; diff --git a/Documentation/devicetree/bindings/sound/fsl-sai.txt b/Documentation/devicetree/bindings/sound/fsl-sai.txt deleted file mode 100644 index fbdefc3fade7..000000000000 --- a/Documentation/devicetree/bindings/sound/fsl-sai.txt +++ /dev/null @@ -1,95 +0,0 @@ -Freescale Synchronous Audio Interface (SAI). - -The SAI is based on I2S module that used communicating with audio codecs, -which provides a synchronous audio interface that supports fullduplex -serial interfaces with frame synchronization such as I2S, AC97, TDM, and -codec/DSP interfaces. - -Required properties: - - - compatible : Compatible list, contains "fsl,vf610-sai", - "fsl,imx6sx-sai", "fsl,imx6ul-sai", - "fsl,imx7ulp-sai", "fsl,imx8mq-sai", - "fsl,imx8qm-sai", "fsl,imx8mm-sai", - "fsl,imx8mn-sai", "fsl,imx8mp-sai", or - "fsl,imx8ulp-sai". - - - reg : Offset and length of the register set for the device. - - - clocks : Must contain an entry for each entry in clock-names. - - - clock-names : Must include the "bus" for register access and - "mclk1", "mclk2", "mclk3" for bit clock and frame - clock providing. - "pll8k", "pll11k" are optional, they are the clock - source for root clock, one is for 8kHz series rates - another one is for 11kHz series rates. - - dmas : Generic dma devicetree binding as described in - Documentation/devicetree/bindings/dma/dma.txt. - - - dma-names : Two dmas have to be defined, "tx" and "rx". - - - pinctrl-names : Must contain a "default" entry. - - - pinctrl-NNN : One property must exist for each entry in - pinctrl-names. See ../pinctrl/pinctrl-bindings.txt - for details of the property values. - - - lsb-first : Configures whether the LSB or the MSB is transmitted - first for the fifo data. If this property is absent, - the MSB is transmitted first as default, or the LSB - is transmitted first. - - - fsl,sai-synchronous-rx: This is a boolean property. If present, indicating - that SAI will work in the synchronous mode (sync Tx - with Rx) which means both the transmitter and the - receiver will send and receive data by following - receiver's bit clocks and frame sync clocks. - - - fsl,sai-asynchronous: This is a boolean property. If present, indicating - that SAI will work in the asynchronous mode, which - means both transmitter and receiver will send and - receive data by following their own bit clocks and - frame sync clocks separately. - - - fsl,dataline : configure the dataline. it has 3 value for each configuration - first one means the type: I2S(1) or PDM(2) - second one is dataline mask for 'rx' - third one is dataline mask for 'tx'. - for example: fsl,dataline = <1 0xff 0xff 2 0xff 0x11>; - it means I2S type rx mask is 0xff, tx mask is 0xff, PDM type - rx mask is 0xff, tx mask is 0x11 (dataline 1 and 4 enabled). - -Optional properties: - - - big-endian : Boolean property, required if all the SAI - registers are big-endian rather than little-endian. - -Optional properties (for mx6ul): - - - fsl,sai-mclk-direction-output: This is a boolean property. If present, - indicates that SAI will output the SAI MCLK clock. - -Note: -- If both fsl,sai-asynchronous and fsl,sai-synchronous-rx are absent, the - default synchronous mode (sync Rx with Tx) will be used, which means both - transmitter and receiver will send and receive data by following clocks - of transmitter. -- fsl,sai-asynchronous and fsl,sai-synchronous-rx are exclusive. - -Example: -sai2: sai@40031000 { - compatible = "fsl,vf610-sai"; - reg = <0x40031000 0x1000>; - pinctrl-names = "default"; - pinctrl-0 = <&pinctrl_sai2_1>; - clocks = <&clks VF610_CLK_PLATFORM_BUS>, - <&clks VF610_CLK_SAI2>, - <&clks 0>, <&clks 0>; - clock-names = "bus", "mclk1", "mclk2", "mclk3"; - dma-names = "tx", "rx"; - dmas = <&edma0 0 VF610_EDMA_MUXID0_SAI2_TX>, - <&edma0 0 VF610_EDMA_MUXID0_SAI2_RX>; - big-endian; - lsb-first; -}; diff --git a/Documentation/devicetree/bindings/sound/google,sc7180-trogdor.yaml b/Documentation/devicetree/bindings/sound/google,sc7180-trogdor.yaml index 233caa0ade87..67ccddd44489 100644 --- a/Documentation/devicetree/bindings/sound/google,sc7180-trogdor.yaml +++ b/Documentation/devicetree/bindings/sound/google,sc7180-trogdor.yaml @@ -61,6 +61,8 @@ patternProperties: cpu: description: Holds subnode which indicates cpu dai. type: object + additionalProperties: false + properties: sound-dai: maxItems: 1 @@ -68,6 +70,8 @@ patternProperties: codec: description: Holds subnode which indicates codec dai. type: object + additionalProperties: false + properties: sound-dai: maxItems: 1 diff --git a/Documentation/devicetree/bindings/sound/imx-audio-card.yaml b/Documentation/devicetree/bindings/sound/imx-audio-card.yaml index bb3a435722c7..b6f5d486600e 100644 --- a/Documentation/devicetree/bindings/sound/imx-audio-card.yaml +++ b/Documentation/devicetree/bindings/sound/imx-audio-card.yaml @@ -58,6 +58,7 @@ patternProperties: cpu: description: Holds subnode which indicates cpu dai. type: object + additionalProperties: false properties: sound-dai: maxItems: 1 @@ -65,6 +66,7 @@ patternProperties: codec: description: Holds subnode which indicates codec dai. type: object + additionalProperties: false properties: sound-dai: minItems: 1 diff --git a/Documentation/devicetree/bindings/sound/mt8186-mt6366-da7219-max98357.yaml b/Documentation/devicetree/bindings/sound/mt8186-mt6366-da7219-max98357.yaml index 513cd28b2027..d427f7f623db 100644 --- a/Documentation/devicetree/bindings/sound/mt8186-mt6366-da7219-max98357.yaml +++ b/Documentation/devicetree/bindings/sound/mt8186-mt6366-da7219-max98357.yaml @@ -43,6 +43,16 @@ properties: required: - sound-dai + mediatek,adsp: + $ref: /schemas/types.yaml#/definitions/phandle + description: The phandle of MT8186 ADSP platform. + + mediatek,dai-link: + $ref: /schemas/types.yaml#/definitions/string-array + description: + A list of the desired dai-links in the sound card. Each entry is a + name defined in the machine driver. + additionalProperties: false required: diff --git a/Documentation/devicetree/bindings/sound/mt8186-mt6366-rt1019-rt5682s.yaml b/Documentation/devicetree/bindings/sound/mt8186-mt6366-rt1019-rt5682s.yaml index 059a7629b2d3..4fc5b045d3cf 100644 --- a/Documentation/devicetree/bindings/sound/mt8186-mt6366-rt1019-rt5682s.yaml +++ b/Documentation/devicetree/bindings/sound/mt8186-mt6366-rt1019-rt5682s.yaml @@ -43,6 +43,16 @@ properties: required: - sound-dai + mediatek,adsp: + $ref: /schemas/types.yaml#/definitions/phandle + description: The phandle of MT8186 ADSP platform. + + mediatek,dai-link: + $ref: /schemas/types.yaml#/definitions/string-array + description: + A list of the desired dai-links in the sound card. Each entry is a + name defined in the machine driver. + additionalProperties: false required: diff --git a/Documentation/devicetree/bindings/sound/mt8192-mt6359-rt1015-rt5682.yaml b/Documentation/devicetree/bindings/sound/mt8192-mt6359-rt1015-rt5682.yaml index 4fa179909c62..478be7e3fa29 100644 --- a/Documentation/devicetree/bindings/sound/mt8192-mt6359-rt1015-rt5682.yaml +++ b/Documentation/devicetree/bindings/sound/mt8192-mt6359-rt1015-rt5682.yaml @@ -30,6 +30,8 @@ properties: headset-codec: type: object + additionalProperties: false + properties: sound-dai: $ref: /schemas/types.yaml#/definitions/phandle @@ -38,6 +40,8 @@ properties: speaker-codecs: type: object + additionalProperties: false + properties: sound-dai: minItems: 1 diff --git a/Documentation/devicetree/bindings/sound/nau8825.txt b/Documentation/devicetree/bindings/sound/nau8825.txt index 388a7bc60b1f..cb861aca8d40 100644 --- a/Documentation/devicetree/bindings/sound/nau8825.txt +++ b/Documentation/devicetree/bindings/sound/nau8825.txt @@ -71,6 +71,9 @@ Optional properties: - nuvoton,crosstalk-enable: make crosstalk function enable if set. + - nuvoton,adcout-drive-strong: make the drive strength of ADCOUT IO PIN strong if set. + Otherwise, the drive keeps normal strength. + - clocks: list of phandle and clock specifier pairs according to common clock bindings for the clocks described in clock-names - clock-names: should include "mclk" for the MCLK master clock diff --git a/Documentation/devicetree/bindings/sound/qcom,lpass-rx-macro.yaml b/Documentation/devicetree/bindings/sound/qcom,lpass-rx-macro.yaml index a6905bcf89d2..1de11e7f33bb 100644 --- a/Documentation/devicetree/bindings/sound/qcom,lpass-rx-macro.yaml +++ b/Documentation/devicetree/bindings/sound/qcom,lpass-rx-macro.yaml @@ -14,6 +14,8 @@ properties: enum: - qcom,sc7280-lpass-rx-macro - qcom,sm8250-lpass-rx-macro + - qcom,sm8450-lpass-rx-macro + - qcom,sc8280xp-lpass-rx-macro reg: maxItems: 1 diff --git a/Documentation/devicetree/bindings/sound/qcom,lpass-tx-macro.yaml b/Documentation/devicetree/bindings/sound/qcom,lpass-tx-macro.yaml index 324595a62ae8..de8297b358e8 100644 --- a/Documentation/devicetree/bindings/sound/qcom,lpass-tx-macro.yaml +++ b/Documentation/devicetree/bindings/sound/qcom,lpass-tx-macro.yaml @@ -14,6 +14,8 @@ properties: enum: - qcom,sc7280-lpass-tx-macro - qcom,sm8250-lpass-tx-macro + - qcom,sm8450-lpass-tx-macro + - qcom,sc8280xp-lpass-tx-macro reg: maxItems: 1 diff --git a/Documentation/devicetree/bindings/sound/qcom,lpass-va-macro.yaml b/Documentation/devicetree/bindings/sound/qcom,lpass-va-macro.yaml index 7b4cc84eda8c..9f473c08cb2e 100644 --- a/Documentation/devicetree/bindings/sound/qcom,lpass-va-macro.yaml +++ b/Documentation/devicetree/bindings/sound/qcom,lpass-va-macro.yaml @@ -14,6 +14,8 @@ properties: enum: - qcom,sc7280-lpass-va-macro - qcom,sm8250-lpass-va-macro + - qcom,sm8450-lpass-va-macro + - qcom,sc8280xp-lpass-va-macro reg: maxItems: 1 diff --git a/Documentation/devicetree/bindings/sound/qcom,lpass-wsa-macro.yaml b/Documentation/devicetree/bindings/sound/qcom,lpass-wsa-macro.yaml index 13cdb8a10687..4959ad658eac 100644 --- a/Documentation/devicetree/bindings/sound/qcom,lpass-wsa-macro.yaml +++ b/Documentation/devicetree/bindings/sound/qcom,lpass-wsa-macro.yaml @@ -14,6 +14,8 @@ properties: enum: - qcom,sc7280-lpass-wsa-macro - qcom,sm8250-lpass-wsa-macro + - qcom,sm8450-lpass-wsa-macro + - qcom,sc8280xp-lpass-wsa-macro reg: maxItems: 1 diff --git a/Documentation/devicetree/bindings/sound/qcom,q6adm-routing.yaml b/Documentation/devicetree/bindings/sound/qcom,q6adm-routing.yaml new file mode 100644 index 000000000000..d0f7a79e240a --- /dev/null +++ b/Documentation/devicetree/bindings/sound/qcom,q6adm-routing.yaml @@ -0,0 +1,52 @@ +# SPDX-License-Identifier: GPL-2.0 OR BSD-2-Clause +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/sound/qcom,q6adm-routing.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Qualcomm Audio Device Manager (Q6ADM) routing + +maintainers: + - Krzysztof Kozlowski <krzysztof.kozlowski@linaro.org> + - Srinivas Kandagatla <srinivas.kandagatla@linaro.org> + +description: + Qualcomm Audio Device Manager (Q6ADM) routing node represents routing + specific configuration. + +properties: + compatible: + enum: + - qcom,q6adm-routing + + "#sound-dai-cells": + const: 0 + +required: + - compatible + - "#sound-dai-cells" + +additionalProperties: false + +examples: + - | + #include <dt-bindings/soc/qcom,apr.h> + #include <dt-bindings/sound/qcom,q6asm.h> + + apr { + compatible = "qcom,apr-v2"; + qcom,domain = <APR_DOMAIN_ADSP>; + #address-cells = <1>; + #size-cells = <0>; + + service@8 { + compatible = "qcom,q6adm"; + reg = <APR_SVC_ADM>; + qcom,protection-domain = "avs/audio", "msm/adsp/audio_pd"; + + routing { + compatible = "qcom,q6adm-routing"; + #sound-dai-cells = <0>; + }; + }; + }; diff --git a/Documentation/devicetree/bindings/sound/qcom,q6adm.txt b/Documentation/devicetree/bindings/sound/qcom,q6adm.txt deleted file mode 100644 index 15c353a20de8..000000000000 --- a/Documentation/devicetree/bindings/sound/qcom,q6adm.txt +++ /dev/null @@ -1,39 +0,0 @@ -Qualcomm Audio Device Manager (Q6ADM) binding - -Q6ADM is one of the APR audio service on Q6DSP. -Please refer to qcom,apr.txt for details of the coommon apr service bindings -used by the apr service device. - -- but must contain the following property: - -- compatible: - Usage: required - Value type: <stringlist> - Definition: must be "qcom,q6adm-v<MAJOR-NUMBER>.<MINOR-NUMBER>". - Or "qcom,q6adm" where the version number can be queried - from DSP. - example "qcom,q6adm-v2.0" - - -= ADM routing -"routing" subnode of the ADM node represents adm routing specific configuration - -- compatible: - Usage: required - Value type: <stringlist> - Definition: must be "qcom,q6adm-routing". - -- #sound-dai-cells - Usage: required - Value type: <u32> - Definition: Must be 0 - -= EXAMPLE -apr-service@8 { - compatible = "qcom,q6adm"; - reg = <APR_SVC_ADM>; - q6routing: routing { - compatible = "qcom,q6adm-routing"; - #sound-dai-cells = <0>; - }; -}; diff --git a/Documentation/devicetree/bindings/sound/qcom,q6afe.txt b/Documentation/devicetree/bindings/sound/qcom,q6afe.txt deleted file mode 100644 index bc6b5f1fe4f1..000000000000 --- a/Documentation/devicetree/bindings/sound/qcom,q6afe.txt +++ /dev/null @@ -1,20 +0,0 @@ -Qualcomm Audio Front End (Q6AFE) binding - -AFE is one of the APR audio service on Q6DSP -Please refer to qcom,apr.txt for details of the common apr service bindings -used by all apr services. Must contain the following properties. - -- compatible: - Usage: required - Value type: <stringlist> - Definition: must be "qcom,q6afe-v<MAJOR-NUMBER>.<MINOR-NUMBER>" - Or "qcom,q6afe" where the version number can be queried - from DSP. - example "qcom,q6afe" - -= EXAMPLE - -apr-service@4 { - compatible = "qcom,q6afe"; - reg = <APR_SVC_AFE>; -}; diff --git a/Documentation/devicetree/bindings/sound/qcom,q6apm-dai.yaml b/Documentation/devicetree/bindings/sound/qcom,q6apm-dai.yaml index 5d972784321d..24f7bf2bfd95 100644 --- a/Documentation/devicetree/bindings/sound/qcom,q6apm-dai.yaml +++ b/Documentation/devicetree/bindings/sound/qcom,q6apm-dai.yaml @@ -16,16 +16,12 @@ properties: compatible: const: qcom,q6apm-dais - reg: - maxItems: 1 - iommus: maxItems: 1 required: - compatible - iommus - - reg additionalProperties: false @@ -37,17 +33,14 @@ examples: #address-cells = <1>; #size-cells = <0>; qcom,domain = <GPR_DOMAIN_ID_ADSP>; - service@1 { - compatible = "qcom,q6apm"; - reg = <1>; - #address-cells = <1>; - #size-cells = <0>; - - apm-dai@1 { - compatible = "qcom,q6apm-dais"; - iommus = <&apps_smmu 0x1801 0x0>; + service@1 { + compatible = "qcom,q6apm"; reg = <1>; - }; + + dais { + compatible = "qcom,q6apm-dais"; + iommus = <&apps_smmu 0x1801 0x0>; + }; }; }; diff --git a/Documentation/devicetree/bindings/sound/qcom,q6asm-dais.yaml b/Documentation/devicetree/bindings/sound/qcom,q6asm-dais.yaml new file mode 100644 index 000000000000..8deb8ffb143b --- /dev/null +++ b/Documentation/devicetree/bindings/sound/qcom,q6asm-dais.yaml @@ -0,0 +1,112 @@ +# SPDX-License-Identifier: GPL-2.0 OR BSD-2-Clause +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/sound/qcom,q6asm-dais.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Qualcomm Audio Stream Manager (Q6ASM) + +maintainers: + - Krzysztof Kozlowski <krzysztof.kozlowski@linaro.org> + - Srinivas Kandagatla <srinivas.kandagatla@linaro.org> + +description: + Q6ASM is one of the APR audio services on Q6DSP. Each of its subnodes + represent a dai with board specific configuration. + +properties: + compatible: + enum: + - qcom,q6asm-dais + + iommus: + maxItems: 1 + + "#sound-dai-cells": + const: 1 + + "#address-cells": + const: 1 + + "#size-cells": + const: 0 + +patternProperties: + "^dai@[0-9]+$": + type: object + description: + Q6ASM Digital Audio Interface + + properties: + reg: + maxItems: 1 + + direction: + $ref: /schemas/types.yaml#/definitions/uint32 + enum: [0, 1, 2] + description: | + The direction of the dai stream:: + - Q6ASM_DAI_TX_RX (0) for both tx and rx + - Q6ASM_DAI_TX (1) for only tx (Capture/Encode) + - Q6ASM_DAI_RX (2) for only rx (Playback/Decode) + + is-compress-dai: + type: boolean + description: + Compress offload dai. + + dependencies: + is-compress-dai: ["direction"] + + required: + - reg + + additionalProperties: false + +required: + - compatible + - "#sound-dai-cells" + - "#address-cells" + - "#size-cells" + +additionalProperties: false + +examples: + - | + #include <dt-bindings/soc/qcom,apr.h> + #include <dt-bindings/sound/qcom,q6asm.h> + + apr { + compatible = "qcom,apr-v2"; + qcom,domain = <APR_DOMAIN_ADSP>; + #address-cells = <1>; + #size-cells = <0>; + + service@7 { + compatible = "qcom,q6asm"; + reg = <APR_SVC_ASM>; + qcom,protection-domain = "avs/audio", "msm/adsp/audio_pd"; + + dais { + compatible = "qcom,q6asm-dais"; + iommus = <&apps_smmu 0x1821 0x0>; + #address-cells = <1>; + #size-cells = <0>; + #sound-dai-cells = <1>; + + dai@0 { + reg = <0>; + }; + + dai@1 { + reg = <1>; + }; + + dai@2 { + reg = <2>; + is-compress-dai; + direction = <1>; + }; + }; + }; + }; diff --git a/Documentation/devicetree/bindings/sound/qcom,q6asm.txt b/Documentation/devicetree/bindings/sound/qcom,q6asm.txt deleted file mode 100644 index 0d0075125243..000000000000 --- a/Documentation/devicetree/bindings/sound/qcom,q6asm.txt +++ /dev/null @@ -1,70 +0,0 @@ -Qualcomm Audio Stream Manager (Q6ASM) binding - -Q6ASM is one of the APR audio service on Q6DSP. -Please refer to qcom,apr.txt for details of the common apr service bindings -used by the apr service device. - -- but must contain the following property: - -- compatible: - Usage: required - Value type: <stringlist> - Definition: must be "qcom,q6asm-v<MAJOR-NUMBER>.<MINOR-NUMBER>". - Or "qcom,q6asm" where the version number can be queried - from DSP. - example "qcom,q6asm-v2.0" - -= ASM DAIs (Digital Audio Interface) -"dais" subnode of the ASM node represents dai specific configuration - -- compatible: - Usage: required - Value type: <stringlist> - Definition: must be "qcom,q6asm-dais". - -- #sound-dai-cells - Usage: required - Value type: <u32> - Definition: Must be 1 - -== ASM DAI is subnode of "dais" and represent a dai, it includes board specific -configuration of each dai. Must contain the following properties. - -- reg - Usage: required - Value type: <u32> - Definition: Must be dai id - -- direction: - Usage: Required for Compress offload dais - Value type: <u32> - Definition: Specifies the direction of the dai stream - Q6ASM_DAI_TX_RX (0) for both tx and rx - Q6ASM_DAI_TX (1) for only tx (Capture/Encode) - Q6ASM_DAI_RX (2) for only rx (Playback/Decode) - -- is-compress-dai: - Usage: Required for Compress offload dais - Value type: <boolean> - Definition: present for Compress offload dais - - -= EXAMPLE -#include <dt-bindings/sound/qcom,q6asm.h> - -apr-service@7 { - compatible = "qcom,q6asm"; - reg = <APR_SVC_ASM>; - q6asmdai: dais { - compatible = "qcom,q6asm-dais"; - #address-cells = <1>; - #size-cells = <0>; - #sound-dai-cells = <1>; - - dai@0 { - reg = <0>; - direction = <Q6ASM_DAI_RX>; - is-compress-dai; - }; - }; -}; diff --git a/Documentation/devicetree/bindings/sound/qcom,q6core.txt b/Documentation/devicetree/bindings/sound/qcom,q6core.txt deleted file mode 100644 index 5cd4cc9b1fde..000000000000 --- a/Documentation/devicetree/bindings/sound/qcom,q6core.txt +++ /dev/null @@ -1,21 +0,0 @@ -Qualcomm ADSP Core service binding - -Q6CORE is one of the APR audio service on Q6DSP. -Please refer to qcom,apr.txt for details of the common apr service bindings -used by the apr service device. - -- but must contain the following property: - -- compatible: - Usage: required - Value type: <stringlist> - Definition: must be "qcom,q6core-v<MAJOR-NUMBER>.<MINOR-NUMBER>". - Or "qcom,q6core" where the version number can be queried - from DSP. - example "qcom,q6core-v2.0" - -= EXAMPLE -apr-service@3 { - compatible = "qcom,q6core"; - reg = <APR_SVC_ADSP_CORE>; -}; diff --git a/Documentation/devicetree/bindings/sound/qcom,q6dsp-lpass-clocks.yaml b/Documentation/devicetree/bindings/sound/qcom,q6dsp-lpass-clocks.yaml index f83f00737a2f..fd567d20417d 100644 --- a/Documentation/devicetree/bindings/sound/qcom,q6dsp-lpass-clocks.yaml +++ b/Documentation/devicetree/bindings/sound/qcom,q6dsp-lpass-clocks.yaml @@ -18,9 +18,6 @@ properties: - qcom,q6afe-clocks - qcom,q6prm-lpass-clocks - reg: - maxItems: 1 - '#clock-cells': const: 2 description: @@ -32,7 +29,6 @@ properties: required: - compatible - - reg - "#clock-cells" additionalProperties: false @@ -42,19 +38,22 @@ examples: #include <dt-bindings/soc/qcom,apr.h> #include <dt-bindings/sound/qcom,q6afe.h> apr { + compatible = "qcom,apr-v2"; + qcom,domain = <APR_DOMAIN_ADSP>; #address-cells = <1>; #size-cells = <0>; - apr-service@4 { + + service@4 { + compatible = "qcom,q6afe"; reg = <APR_SVC_AFE>; - #address-cells = <1>; - #size-cells = <0>; - clock-controller@2 { - compatible = "qcom,q6afe-clocks"; - reg = <2>; - #clock-cells = <2>; + qcom,protection-domain = "avs/audio", "msm/adsp/audio_pd"; + + clock-controller { + compatible = "qcom,q6afe-clocks"; + #clock-cells = <2>; }; }; - }; + }; - | #include <dt-bindings/soc/qcom,gpr.h> @@ -63,15 +62,14 @@ examples: qcom,domain = <GPR_DOMAIN_ID_ADSP>; #address-cells = <1>; #size-cells = <0>; + service@2 { reg = <GPR_PRM_MODULE_IID>; compatible = "qcom,q6prm"; - #address-cells = <1>; - #size-cells = <0>; - clock-controller@2 { - compatible = "qcom,q6prm-lpass-clocks"; - reg = <2>; - #clock-cells = <2>; + + clock-controller { + compatible = "qcom,q6prm-lpass-clocks"; + #clock-cells = <2>; }; }; - }; + }; diff --git a/Documentation/devicetree/bindings/sound/qcom,q6dsp-lpass-ports.yaml b/Documentation/devicetree/bindings/sound/qcom,q6dsp-lpass-ports.yaml index dc7fba7b92d5..e53fc0960a14 100644 --- a/Documentation/devicetree/bindings/sound/qcom,q6dsp-lpass-ports.yaml +++ b/Documentation/devicetree/bindings/sound/qcom,q6dsp-lpass-ports.yaml @@ -18,9 +18,6 @@ properties: - qcom,q6afe-dais - qcom,q6apm-lpass-dais - reg: - maxItems: 1 - '#sound-dai-cells': const: 1 @@ -145,7 +142,6 @@ patternProperties: required: - compatible - - reg - "#sound-dai-cells" - "#address-cells" - "#size-cells" @@ -157,26 +153,29 @@ examples: #include <dt-bindings/soc/qcom,apr.h> #include <dt-bindings/sound/qcom,q6afe.h> apr { + compatible = "qcom,apr-v2"; #address-cells = <1>; #size-cells = <0>; - apr-service@4 { + qcom,domain = <APR_DOMAIN_ADSP>; + + service@4 { + compatible = "qcom,q6afe"; reg = <APR_SVC_AFE>; - #address-cells = <1>; - #size-cells = <0>; - q6afedai@1 { - compatible = "qcom,q6afe-dais"; - reg = <1>; - #address-cells = <1>; - #size-cells = <0>; - #sound-dai-cells = <1>; - - dai@22 { - reg = <QUATERNARY_MI2S_RX>; - qcom,sd-lines = <0 1 2 3>; - }; + qcom,protection-domain = "avs/audio", "msm/adsp/audio_pd"; + + dais { + compatible = "qcom,q6afe-dais"; + #address-cells = <1>; + #size-cells = <0>; + #sound-dai-cells = <1>; + + dai@22 { + reg = <QUATERNARY_MI2S_RX>; + qcom,sd-lines = <0 1 2 3>; + }; }; }; - }; + }; - | #include <dt-bindings/soc/qcom,gpr.h> gpr { @@ -184,22 +183,21 @@ examples: #address-cells = <1>; #size-cells = <0>; qcom,domain = <GPR_DOMAIN_ID_ADSP>; + service@1 { compatible = "qcom,q6apm"; reg = <GPR_APM_MODULE_IID>; - #address-cells = <1>; - #size-cells = <0>; - q6apmdai@1 { - compatible = "qcom,q6apm-lpass-dais"; - reg = <1>; - #address-cells = <1>; - #size-cells = <0>; - #sound-dai-cells = <1>; - - dai@22 { - reg = <QUATERNARY_MI2S_RX>; - qcom,sd-lines = <0 1 2 3>; - }; + + dais { + compatible = "qcom,q6apm-lpass-dais"; + #address-cells = <1>; + #size-cells = <0>; + #sound-dai-cells = <1>; + + dai@22 { + reg = <QUATERNARY_MI2S_RX>; + qcom,sd-lines = <0 1 2 3>; + }; }; }; - }; + }; diff --git a/Documentation/devicetree/bindings/sound/qcom,sm8250.yaml b/Documentation/devicetree/bindings/sound/qcom,sm8250.yaml index e6e27d09783e..70080d04ddc9 100644 --- a/Documentation/devicetree/bindings/sound/qcom,sm8250.yaml +++ b/Documentation/devicetree/bindings/sound/qcom,sm8250.yaml @@ -20,9 +20,11 @@ properties: - qcom,apq8016-sbc-sndcard - qcom,db845c-sndcard - qcom,msm8916-qdsp6-sndcard + - qcom,qrb5165-rb5-sndcard + - qcom,sc8280xp-sndcard - qcom,sdm845-sndcard - qcom,sm8250-sndcard - - qcom,qrb5165-rb5-sndcard + - qcom,sm8450-sndcard audio-routing: $ref: /schemas/types.yaml#/definitions/non-unique-string-array @@ -71,6 +73,8 @@ patternProperties: cpu: description: Holds subnode which indicates cpu dai. type: object + additionalProperties: false + properties: sound-dai: maxItems: 1 @@ -78,6 +82,8 @@ patternProperties: platform: description: Holds subnode which indicates platform dai. type: object + additionalProperties: false + properties: sound-dai: maxItems: 1 @@ -85,6 +91,8 @@ patternProperties: codec: description: Holds subnode which indicates codec dai. type: object + additionalProperties: false + properties: sound-dai: minItems: 1 diff --git a/Documentation/devicetree/bindings/sound/renesas,rsnd.yaml b/Documentation/devicetree/bindings/sound/renesas,rsnd.yaml index e17c0245f77a..268895c90bd5 100644 --- a/Documentation/devicetree/bindings/sound/renesas,rsnd.yaml +++ b/Documentation/devicetree/bindings/sound/renesas,rsnd.yaml @@ -129,6 +129,8 @@ properties: patternProperties: "^dvc-[0-1]$": type: object + additionalProperties: false + properties: dmas: maxItems: 1 @@ -145,7 +147,7 @@ properties: patternProperties: "^mix-[0-1]$": type: object - # no properties + additionalProperties: false additionalProperties: false rcar_sound,ctu: @@ -154,7 +156,7 @@ properties: patternProperties: "^ctu-[0-7]$": type: object - # no properties + additionalProperties: false additionalProperties: false rcar_sound,src: @@ -163,6 +165,8 @@ properties: patternProperties: "^src-[0-9]$": type: object + additionalProperties: false + properties: interrupts: maxItems: 1 @@ -186,6 +190,8 @@ properties: patternProperties: "^ssiu-[0-9]+$": type: object + additionalProperties: false + properties: dmas: maxItems: 2 @@ -206,6 +212,8 @@ properties: patternProperties: "^ssi-[0-9]$": type: object + additionalProperties: false + properties: interrupts: maxItems: 1 @@ -243,6 +251,8 @@ properties: patternProperties: "^dai([0-9]+)?$": type: object + additionalProperties: false + properties: playback: $ref: /schemas/types.yaml#/definitions/phandle-array diff --git a/Documentation/devicetree/bindings/sound/samsung,aries-wm8994.yaml b/Documentation/devicetree/bindings/sound/samsung,aries-wm8994.yaml index a01c4ad929b8..447e013f6e17 100644 --- a/Documentation/devicetree/bindings/sound/samsung,aries-wm8994.yaml +++ b/Documentation/devicetree/bindings/sound/samsung,aries-wm8994.yaml @@ -23,6 +23,7 @@ properties: cpu: type: object + additionalProperties: false properties: sound-dai: minItems: 2 @@ -34,6 +35,7 @@ properties: - sound-dai codec: + additionalProperties: false type: object properties: sound-dai: diff --git a/Documentation/devicetree/bindings/sound/samsung,midas-audio.yaml b/Documentation/devicetree/bindings/sound/samsung,midas-audio.yaml index ec50bcb4af5f..31095913e330 100644 --- a/Documentation/devicetree/bindings/sound/samsung,midas-audio.yaml +++ b/Documentation/devicetree/bindings/sound/samsung,midas-audio.yaml @@ -19,6 +19,7 @@ properties: cpu: type: object + additionalProperties: false properties: sound-dai: maxItems: 1 @@ -28,6 +29,7 @@ properties: codec: type: object + additionalProperties: false properties: sound-dai: maxItems: 1 diff --git a/Documentation/devicetree/bindings/sound/samsung,snow.yaml b/Documentation/devicetree/bindings/sound/samsung,snow.yaml index 51a83d3c7274..3d49aa4c9be2 100644 --- a/Documentation/devicetree/bindings/sound/samsung,snow.yaml +++ b/Documentation/devicetree/bindings/sound/samsung,snow.yaml @@ -19,6 +19,7 @@ properties: codec: type: object + additionalProperties: false properties: sound-dai: description: List of phandles to the CODEC and HDMI IP nodes. @@ -30,6 +31,7 @@ properties: cpu: type: object + additionalProperties: false properties: sound-dai: description: Phandle to the Samsung I2S controller. diff --git a/Documentation/devicetree/bindings/sound/st,stm32-sai.yaml b/Documentation/devicetree/bindings/sound/st,stm32-sai.yaml index fe2e15504ebc..56d206f97a96 100644 --- a/Documentation/devicetree/bindings/sound/st,stm32-sai.yaml +++ b/Documentation/devicetree/bindings/sound/st,stm32-sai.yaml @@ -60,6 +60,7 @@ required: patternProperties: "^audio-controller@[0-9a-f]+$": type: object + additionalProperties: false description: Two subnodes corresponding to SAI sub-block instances A et B can be defined. Subnode can be omitted for unsused sub-block. @@ -121,6 +122,10 @@ patternProperties: description: Configure the SAI device as master clock provider. const: 0 + port: + $ref: audio-graph-port.yaml# + unevaluatedProperties: false + required: - compatible - "#sound-dai-cells" diff --git a/Documentation/devicetree/bindings/sound/ti,src4xxx.yaml b/Documentation/devicetree/bindings/sound/ti,src4xxx.yaml new file mode 100644 index 000000000000..9681b72b4918 --- /dev/null +++ b/Documentation/devicetree/bindings/sound/ti,src4xxx.yaml @@ -0,0 +1,48 @@ +# SPDX-License-Identifier: (GPL-2.0 OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/sound/ti,src4xxx.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Texas Instruments SRC4392 Device Tree Bindings + +description: | + The SRC4392 is a digital audio codec that can be connected via + I2C or SPI. Currently, only I2C bus is supported. + +maintainers: + - Matt Flax <flatmax@flatmax.com> + +allOf: + - $ref: name-prefix.yaml# + +properties: + compatible: + const: ti,src4392 + + "#sound-dai-cells": + const: 0 + + reg: + maxItems: 1 + +required: + - "#sound-dai-cells" + - compatible + - reg + +additionalProperties: false + +examples: + - | + i2c { + #address-cells = <1>; + #size-cells = <0>; + + audio-codec@70 { + #sound-dai-cells = <0>; + compatible = "ti,src4392"; + reg = <0x70>; + }; + }; +... diff --git a/Documentation/devicetree/bindings/sound/ti,ts3a227e.yaml b/Documentation/devicetree/bindings/sound/ti,ts3a227e.yaml new file mode 100644 index 000000000000..785930658029 --- /dev/null +++ b/Documentation/devicetree/bindings/sound/ti,ts3a227e.yaml @@ -0,0 +1,94 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/sound/ti,ts3a227e.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Texas Instruments TS3A227E + Autonomous Audio Accessory Detection and Configuration Switch + +maintainers: + - Dylan Reid <dgreid@chromium.org> + +description: | + The TS3A227E detect headsets of 3-ring and 4-ring standards and + switches automatically to route the microphone correctly. It also + handles key press detection in accordance with the Android audio + headset specification v1.0. + +properties: + compatible: + enum: + - ti,ts3a227e + + reg: + const: 0x3b + + interrupts: + maxItems: 1 + + ti,micbias: + $ref: /schemas/types.yaml#/definitions/uint32 + description: Intended MICBIAS voltage (datasheet section 9.6.7). + enum: + - 0 # 2.1 V + - 1 # 2.2 V + - 2 # 2.3 V + - 3 # 2.4 V + - 4 # 2.5 V + - 5 # 2.6 V + - 6 # 2.7 V + - 7 # 2.8 V + default: 1 + + ti,debounce-release-ms: + description: key release debounce time in ms (datasheet section 9.6.7). + enum: + - 0 + - 20 + default: 20 + + ti,debounce-press-ms: + description: key press debounce time in ms (datasheet section 9.6.7). + enum: + - 2 + - 40 + - 80 + - 120 + default: 80 + + ti,debounce-insertion-ms: + description: headset insertion debounce time in ms (datasheet section 9.6.5). + enum: + - 2 + - 30 + - 60 + - 90 + - 120 + - 150 + - 1000 + - 2000 + default: 90 + +required: + - compatible + - reg + - interrupts + +additionalProperties: false + +examples: + - | + #include <dt-bindings/interrupt-controller/irq.h> + i2c { + #address-cells = <1>; + #size-cells = <0>; + codec: audio-controller@3b { + compatible = "ti,ts3a227e"; + reg = <0x3b>; + interrupt-parent = <&gpio1>; + interrupts = <3 IRQ_TYPE_LEVEL_LOW>; + }; + }; + +... diff --git a/Documentation/devicetree/bindings/sound/ts3a227e.txt b/Documentation/devicetree/bindings/sound/ts3a227e.txt deleted file mode 100644 index 21ab45bc7e8f..000000000000 --- a/Documentation/devicetree/bindings/sound/ts3a227e.txt +++ /dev/null @@ -1,30 +0,0 @@ -Texas Instruments TS3A227E -Autonomous Audio Accessory Detection and Configuration Switch - -The TS3A227E detect headsets of 3-ring and 4-ring standards and -switches automatically to route the microphone correctly. It also -handles key press detection in accordance with the Android audio -headset specification v1.0. - -Required properties: - - - compatible: Should contain "ti,ts3a227e". - - reg: The i2c address. Should contain <0x3b>. - - interrupts: Interrupt number for /INT pin from the 227e - -Optional properies: - - ti,micbias: Intended MICBIAS voltage (datasheet section 9.6.7). - Select 0/1/2/3/4/5/6/7 to specify MICBIAS voltage - 2.1V/2.2V/2.3V/2.4V/2.5V/2.6V/2.7V/2.8V - Default value is "1" (2.2V). - -Examples: - - i2c { - ts3a227e@3b { - compatible = "ti,ts3a227e"; - reg = <0x3b>; - interrupt-parent = <&gpio>; - interrupts = <3 IRQ_TYPE_LEVEL_LOW>; - }; - }; diff --git a/Documentation/devicetree/bindings/spi/amlogic,meson-gx-spicc.yaml b/Documentation/devicetree/bindings/spi/amlogic,meson-gx-spicc.yaml index 50de0da42c13..0c10f7678178 100644 --- a/Documentation/devicetree/bindings/spi/amlogic,meson-gx-spicc.yaml +++ b/Documentation/devicetree/bindings/spi/amlogic,meson-gx-spicc.yaml @@ -8,7 +8,7 @@ $schema: "http://devicetree.org/meta-schemas/core.yaml#" title: Amlogic Meson SPI Communication Controller maintainers: - - Neil Armstrong <narmstrong@baylibre.com> + - Neil Armstrong <neil.armstrong@linaro.org> allOf: - $ref: "spi-controller.yaml#" diff --git a/Documentation/devicetree/bindings/spi/amlogic,meson6-spifc.yaml b/Documentation/devicetree/bindings/spi/amlogic,meson6-spifc.yaml index 8a9d526d06eb..ac3b2ec300ac 100644 --- a/Documentation/devicetree/bindings/spi/amlogic,meson6-spifc.yaml +++ b/Documentation/devicetree/bindings/spi/amlogic,meson6-spifc.yaml @@ -8,7 +8,7 @@ $schema: "http://devicetree.org/meta-schemas/core.yaml#" title: Amlogic Meson SPI Flash Controller maintainers: - - Neil Armstrong <narmstrong@baylibre.com> + - Neil Armstrong <neil.armstrong@linaro.org> allOf: - $ref: "spi-controller.yaml#" diff --git a/Documentation/devicetree/bindings/spi/mediatek,spi-mtk-nor.yaml b/Documentation/devicetree/bindings/spi/mediatek,spi-mtk-nor.yaml index 970b1119898b..a453996c13f2 100644 --- a/Documentation/devicetree/bindings/spi/mediatek,spi-mtk-nor.yaml +++ b/Documentation/devicetree/bindings/spi/mediatek,spi-mtk-nor.yaml @@ -85,8 +85,9 @@ examples: compatible = "mediatek,mt8173-nor"; reg = <0 0x1100d000 0 0xe0>; interrupts = <1>; - clocks = <&pericfg CLK_PERI_SPI>, <&topckgen CLK_TOP_SPINFI_IFR_SEL>; - clock-names = "spi", "sf"; + clocks = <&pericfg CLK_PERI_SPI>, <&topckgen CLK_TOP_SPINFI_IFR_SEL>, + <&pericfg CLK_PERI_NFI>; + clock-names = "spi", "sf", "axi"; #address-cells = <1>; #size-cells = <0>; diff --git a/Documentation/devicetree/bindings/spi/microchip,mpfs-spi.yaml b/Documentation/devicetree/bindings/spi/microchip,mpfs-spi.yaml index 7326c0a28d16..1051690e3753 100644 --- a/Documentation/devicetree/bindings/spi/microchip,mpfs-spi.yaml +++ b/Documentation/devicetree/bindings/spi/microchip,mpfs-spi.yaml @@ -4,7 +4,11 @@ $id: http://devicetree.org/schemas/spi/microchip,mpfs-spi.yaml# $schema: http://devicetree.org/meta-schemas/core.yaml# -title: Microchip MPFS {Q,}SPI Controller Device Tree Bindings +title: Microchip FPGA {Q,}SPI Controllers + +description: + SPI and QSPI controllers on Microchip PolarFire SoC and the "soft"/ + fabric IP cores they are based on maintainers: - Conor Dooley <conor.dooley@microchip.com> @@ -14,9 +18,12 @@ allOf: properties: compatible: - enum: - - microchip,mpfs-spi - - microchip,mpfs-qspi + oneOf: + - items: + - const: microchip,mpfs-qspi + - const: microchip,coreqspi-rtl-v2 + - const: microchip,coreqspi-rtl-v2 #FPGA QSPI + - const: microchip,mpfs-spi reg: maxItems: 1 diff --git a/Documentation/devicetree/bindings/spi/nuvoton,npcm-pspi.txt b/Documentation/devicetree/bindings/spi/nuvoton,npcm-pspi.txt index b98203ca656d..a4e72e52af59 100644 --- a/Documentation/devicetree/bindings/spi/nuvoton,npcm-pspi.txt +++ b/Documentation/devicetree/bindings/spi/nuvoton,npcm-pspi.txt @@ -3,7 +3,8 @@ Nuvoton NPCM Peripheral Serial Peripheral Interface(PSPI) controller driver Nuvoton NPCM7xx SOC support two PSPI channels. Required properties: - - compatible : "nuvoton,npcm750-pspi" for NPCM7XX BMC + - compatible : "nuvoton,npcm750-pspi" for Poleg NPCM7XX. + "nuvoton,npcm845-pspi" for Arbel NPCM8XX. - #address-cells : should be 1. see spi-bus.txt - #size-cells : should be 0. see spi-bus.txt - specifies physical base address and size of the register. diff --git a/Documentation/devicetree/bindings/spi/nvidia,tegra210-quad-peripheral-props.yaml b/Documentation/devicetree/bindings/spi/nvidia,tegra210-quad-peripheral-props.yaml index 24e0c2181d25..2c3cada75339 100644 --- a/Documentation/devicetree/bindings/spi/nvidia,tegra210-quad-peripheral-props.yaml +++ b/Documentation/devicetree/bindings/spi/nvidia,tegra210-quad-peripheral-props.yaml @@ -29,5 +29,4 @@ properties: minimum: 0 maximum: 255 -unevaluatedProperties: true - +additionalProperties: true diff --git a/Documentation/devicetree/bindings/spi/ralink,mt7621-spi.yaml b/Documentation/devicetree/bindings/spi/ralink,mt7621-spi.yaml new file mode 100644 index 000000000000..22879f7dcb77 --- /dev/null +++ b/Documentation/devicetree/bindings/spi/ralink,mt7621-spi.yaml @@ -0,0 +1,61 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/spi/ralink,mt7621-spi.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +maintainers: + - Sergio Paracuellos <sergio.paracuellos@gmail.com> + +title: Mediatek MT7621/MT7628 SPI controller + +allOf: + - $ref: /schemas/spi/spi-controller.yaml# + +properties: + compatible: + const: ralink,mt7621-spi + + reg: + maxItems: 1 + + clocks: + maxItems: 1 + + clock-names: + const: spi + + resets: + maxItems: 1 + + reset-names: + const: spi + +required: + - compatible + - reg + - resets + - "#address-cells" + - "#size-cells" + +unevaluatedProperties: false + +examples: + - | + #include <dt-bindings/clock/mt7621-clk.h> + #include <dt-bindings/reset/mt7621-reset.h> + + spi@b00 { + compatible = "ralink,mt7621-spi"; + reg = <0xb00 0x100>; + clocks = <&sysc MT7621_CLK_SPI>; + clock-names = "spi"; + resets = <&sysc MT7621_RST_SPI>; + reset-names = "spi"; + + #address-cells = <1>; + #size-cells = <0>; + + pinctrl-names = "default"; + pinctrl-0 = <&spi_pins>; + }; diff --git a/Documentation/devicetree/bindings/spi/renesas,sh-msiof.yaml b/Documentation/devicetree/bindings/spi/renesas,sh-msiof.yaml index 5de710adfa63..491a695a2deb 100644 --- a/Documentation/devicetree/bindings/spi/renesas,sh-msiof.yaml +++ b/Documentation/devicetree/bindings/spi/renesas,sh-msiof.yaml @@ -47,10 +47,16 @@ properties: - renesas,msiof-r8a77980 # R-Car V3H - renesas,msiof-r8a77990 # R-Car E3 - renesas,msiof-r8a77995 # R-Car D3 - - renesas,msiof-r8a779a0 # R-Car V3U - const: renesas,rcar-gen3-msiof # generic R-Car Gen3 and RZ/G2 # compatible device - items: + - enum: + - renesas,msiof-r8a779a0 # R-Car V3U + - renesas,msiof-r8a779f0 # R-Car S4-8 + - renesas,msiof-r8a779g0 # R-Car V4H + - const: renesas,rcar-gen4-msiof # generic R-Car Gen4 + # compatible device + - items: - const: renesas,sh-msiof # deprecated reg: @@ -69,6 +75,12 @@ properties: clocks: maxItems: 1 + power-domains: + maxItems: 1 + + resets: + maxItems: 1 + num-cs: description: | Total number of chip selects (default is 1). diff --git a/Documentation/devicetree/bindings/spi/snps,dw-apb-ssi.yaml b/Documentation/devicetree/bindings/spi/snps,dw-apb-ssi.yaml index 37c3c272407d..d33b72fabc5d 100644 --- a/Documentation/devicetree/bindings/spi/snps,dw-apb-ssi.yaml +++ b/Documentation/devicetree/bindings/spi/snps,dw-apb-ssi.yaml @@ -104,7 +104,6 @@ properties: const: spi reg-io-width: - $ref: /schemas/types.yaml#/definitions/uint32 description: I/O register width (in bytes) implemented by this device default: 4 enum: [ 2, 4 ] diff --git a/Documentation/devicetree/bindings/spi/spi-controller.yaml b/Documentation/devicetree/bindings/spi/spi-controller.yaml index 655713fba7e2..01042a7f382e 100644 --- a/Documentation/devicetree/bindings/spi/spi-controller.yaml +++ b/Documentation/devicetree/bindings/spi/spi-controller.yaml @@ -96,6 +96,11 @@ patternProperties: $ref: spi-peripheral-props.yaml properties: + spi-3wire: + $ref: /schemas/types.yaml#/definitions/flag + description: + The device requires 3-wire mode. + spi-cpha: $ref: /schemas/types.yaml#/definitions/flag description: diff --git a/Documentation/devicetree/bindings/spi/spi-fsl-lpspi.yaml b/Documentation/devicetree/bindings/spi/spi-fsl-lpspi.yaml index 1d46877fe46a..8b44284d30c6 100644 --- a/Documentation/devicetree/bindings/spi/spi-fsl-lpspi.yaml +++ b/Documentation/devicetree/bindings/spi/spi-fsl-lpspi.yaml @@ -19,7 +19,9 @@ properties: - fsl,imx7ulp-spi - fsl,imx8qxp-spi - items: - - const: fsl,imx8ulp-spi + - enum: + - fsl,imx8ulp-spi + - fsl,imx93-spi - const: fsl,imx7ulp-spi reg: maxItems: 1 @@ -37,6 +39,16 @@ properties: - const: per - const: ipg + dmas: + items: + - description: TX DMA Channel + - description: RX DMA Channel + + dma-names: + items: + - const: tx + - const: rx + fsl,spi-only-use-cs1-sel: description: spi common code does not support use of CS signals discontinuously. diff --git a/Documentation/devicetree/bindings/spi/spi-mt7621.txt b/Documentation/devicetree/bindings/spi/spi-mt7621.txt deleted file mode 100644 index d5baec0fa56e..000000000000 --- a/Documentation/devicetree/bindings/spi/spi-mt7621.txt +++ /dev/null @@ -1,26 +0,0 @@ -Binding for MTK SPI controller (MT7621 MIPS) - -Required properties: -- compatible: Should be one of the following: - - "ralink,mt7621-spi": for mt7621/mt7628/mt7688 platforms -- #address-cells: should be 1. -- #size-cells: should be 0. -- reg: Address and length of the register set for the device -- resets: phandle to the reset controller asserting this device in - reset - See ../reset/reset.txt for details. - -Optional properties: -- cs-gpios: see spi-bus.txt. - -Example: - -- SoC Specific Portion: -spi0: spi@b00 { - compatible = "ralink,mt7621-spi"; - reg = <0xb00 0x100>; - #address-cells = <1>; - #size-cells = <0>; - resets = <&rstctrl 18>; - reset-names = "spi"; -}; diff --git a/Documentation/devicetree/bindings/spi/spi-peripheral-props.yaml b/Documentation/devicetree/bindings/spi/spi-peripheral-props.yaml index a4abe1588005..dca677f9e1b9 100644 --- a/Documentation/devicetree/bindings/spi/spi-peripheral-props.yaml +++ b/Documentation/devicetree/bindings/spi/spi-peripheral-props.yaml @@ -29,11 +29,6 @@ properties: description: Chip select used by the device. - spi-3wire: - $ref: /schemas/types.yaml#/definitions/flag - description: - The device requires 3-wire mode. - spi-cs-high: $ref: /schemas/types.yaml#/definitions/flag description: diff --git a/Documentation/devicetree/bindings/spi/spi-rockchip.yaml b/Documentation/devicetree/bindings/spi/spi-rockchip.yaml index 52a78a2e362e..66e49947b703 100644 --- a/Documentation/devicetree/bindings/spi/spi-rockchip.yaml +++ b/Documentation/devicetree/bindings/spi/spi-rockchip.yaml @@ -27,6 +27,7 @@ properties: - items: - enum: - rockchip,px30-spi + - rockchip,rk3128-spi - rockchip,rk3188-spi - rockchip,rk3288-spi - rockchip,rk3308-spi @@ -34,6 +35,7 @@ properties: - rockchip,rk3368-spi - rockchip,rk3399-spi - rockchip,rk3568-spi + - rockchip,rk3588-spi - rockchip,rv1126-spi - const: rockchip,rk3066-spi @@ -80,6 +82,9 @@ properties: where the "sleep" configuration may describe the state the pins should be in during system suspend. + power-domains: + maxItems: 1 + required: - compatible - reg diff --git a/Documentation/devicetree/bindings/usb/amlogic,meson-g12a-usb-ctrl.yaml b/Documentation/devicetree/bindings/usb/amlogic,meson-g12a-usb-ctrl.yaml index e349fa5de606..daf2a859418d 100644 --- a/Documentation/devicetree/bindings/usb/amlogic,meson-g12a-usb-ctrl.yaml +++ b/Documentation/devicetree/bindings/usb/amlogic,meson-g12a-usb-ctrl.yaml @@ -8,7 +8,7 @@ $schema: "http://devicetree.org/meta-schemas/core.yaml#" title: Amlogic Meson G12A DWC3 USB SoC Controller Glue maintainers: - - Neil Armstrong <narmstrong@baylibre.com> + - Neil Armstrong <neil.armstrong@linaro.org> description: | The Amlogic G12A embeds a DWC3 USB IP Core configured for USB2 and USB3 diff --git a/Documentation/devicetree/bindings/usb/mediatek,mtu3.yaml b/Documentation/devicetree/bindings/usb/mediatek,mtu3.yaml index e63b66545317..b019d490170d 100644 --- a/Documentation/devicetree/bindings/usb/mediatek,mtu3.yaml +++ b/Documentation/devicetree/bindings/usb/mediatek,mtu3.yaml @@ -24,6 +24,7 @@ properties: - mediatek,mt2712-mtu3 - mediatek,mt8173-mtu3 - mediatek,mt8183-mtu3 + - mediatek,mt8188-mtu3 - mediatek,mt8192-mtu3 - mediatek,mt8195-mtu3 - const: mediatek,mtu3 diff --git a/Documentation/devicetree/bindings/usb/qcom,dwc3.yaml b/Documentation/devicetree/bindings/usb/qcom,dwc3.yaml index fea3e7092ace..cd2f7cb6745a 100644 --- a/Documentation/devicetree/bindings/usb/qcom,dwc3.yaml +++ b/Documentation/devicetree/bindings/usb/qcom,dwc3.yaml @@ -33,6 +33,7 @@ properties: - qcom,sm6115-dwc3 - qcom,sm6125-dwc3 - qcom,sm6350-dwc3 + - qcom,sm6375-dwc3 - qcom,sm8150-dwc3 - qcom,sm8250-dwc3 - qcom,sm8350-dwc3 @@ -108,12 +109,17 @@ properties: HS/FS/LS modes are supported. type: boolean + wakeup-source: true + # Required child node: patternProperties: "^usb@[0-9a-f]+$": $ref: snps,dwc3.yaml# + properties: + wakeup-source: false + required: - compatible - reg diff --git a/Documentation/devicetree/bindings/vendor-prefixes.yaml b/Documentation/devicetree/bindings/vendor-prefixes.yaml index 2f0151e9f6be..9bf7c2cd7e89 100644 --- a/Documentation/devicetree/bindings/vendor-prefixes.yaml +++ b/Documentation/devicetree/bindings/vendor-prefixes.yaml @@ -819,6 +819,8 @@ patternProperties: description: MNT Research GmbH "^modtronix,.*": description: Modtronix Engineering + "^moortec,.*": + description: Moortec Semiconductor Ltd. "^mosaixtech,.*": description: Mosaix Technologies, Inc. "^motorola,.*": diff --git a/Documentation/devicetree/bindings/watchdog/amlogic,meson-gxbb-wdt.yaml b/Documentation/devicetree/bindings/watchdog/amlogic,meson-gxbb-wdt.yaml index c7459cf70e30..497d60408ea0 100644 --- a/Documentation/devicetree/bindings/watchdog/amlogic,meson-gxbb-wdt.yaml +++ b/Documentation/devicetree/bindings/watchdog/amlogic,meson-gxbb-wdt.yaml @@ -8,7 +8,7 @@ $schema: "http://devicetree.org/meta-schemas/core.yaml#" title: Meson GXBB SoCs Watchdog timer maintainers: - - Neil Armstrong <narmstrong@baylibre.com> + - Neil Armstrong <neil.armstrong@linaro.org> allOf: - $ref: watchdog.yaml# diff --git a/Documentation/doc-guide/kernel-doc.rst b/Documentation/doc-guide/kernel-doc.rst index 9c779bd7a751..1dcbd7332476 100644 --- a/Documentation/doc-guide/kernel-doc.rst +++ b/Documentation/doc-guide/kernel-doc.rst @@ -14,6 +14,9 @@ when it is embedded in source files. reasons. The kernel source contains tens of thousands of kernel-doc comments. Please stick to the style described here. +.. note:: kernel-doc does not cover Rust code: please see + Documentation/rust/general-information.rst instead. + The kernel-doc structure is extracted from the comments, and proper `Sphinx C Domain`_ function and type descriptions with anchors are generated from them. The descriptions are filtered for special kernel-doc diff --git a/Documentation/doc-guide/sphinx.rst b/Documentation/doc-guide/sphinx.rst index 1228b85f6f77..c708cec889af 100644 --- a/Documentation/doc-guide/sphinx.rst +++ b/Documentation/doc-guide/sphinx.rst @@ -48,10 +48,6 @@ or ``virtualenv``, depending on how your distribution packaged Python 3. on the Sphinx version, it should be installed separately, with ``pip install sphinx_rtd_theme``. - #) Some ReST pages contain math expressions. Due to the way Sphinx works, - those expressions are written using LaTeX notation. It needs texlive - installed with amsfonts and amsmath in order to evaluate them. - In summary, if you want to install Sphinx version 2.4.4, you should do:: $ virtualenv sphinx_2.4.4 @@ -86,6 +82,27 @@ Depending on the distribution, you may also need to install a series of ``texlive`` packages that provide the minimal set of functionalities required for ``XeLaTeX`` to work. +Math Expressions in HTML +------------------------ + +Some ReST pages contain math expressions. Due to the way Sphinx works, +those expressions are written using LaTeX notation. +There are two options for Sphinx to render math expressions in html output. +One is an extension called `imgmath`_ which converts math expressions into +images and embeds them in html pages. +The other is an extension called `mathjax`_ which delegates math rendering +to JavaScript capable web browsers. +The former was the only option for pre-6.1 kernel documentation and it +requires quite a few texlive packages including amsfonts and amsmath among +others. + +Since kernel release 6.1, html pages with math expressions can be built +without installing any texlive packages. See `Choice of Math Renderer`_ for +further info. + +.. _imgmath: https://www.sphinx-doc.org/en/master/usage/extensions/math.html#module-sphinx.ext.imgmath +.. _mathjax: https://www.sphinx-doc.org/en/master/usage/extensions/math.html#module-sphinx.ext.mathjax + .. _sphinx-pre-install: Checking for Sphinx dependencies @@ -164,6 +181,38 @@ To remove the generated documentation, run ``make cleandocs``. as well would improve the quality of images embedded in PDF documents, especially for kernel releases 5.18 and later. +Choice of Math Renderer +----------------------- + +Since kernel release 6.1, mathjax works as a fallback math renderer for +html output.\ [#sph1_8]_ + +Math renderer is chosen depending on available commands as shown below: + +.. table:: Math Renderer Choices for HTML + + ============= ================= ============ + Math renderer Required commands Image format + ============= ================= ============ + imgmath latex, dvipng PNG (raster) + mathjax + ============= ================= ============ + +The choice can be overridden by setting an environment variable +``SPHINX_IMGMATH`` as shown below: + +.. table:: Effect of Setting ``SPHINX_IMGMATH`` + + ====================== ======== + Setting Renderer + ====================== ======== + ``SPHINX_IMGMATH=yes`` imgmath + ``SPHINX_IMGMATH=no`` mathjax + ====================== ======== + +.. [#sph1_8] Fallback of math renderer requires Sphinx >=1.8. + + Writing Documentation ===================== diff --git a/Documentation/driver-api/driver-model/devres.rst b/Documentation/driver-api/driver-model/devres.rst index 55272942e721..5e6de4ab25dc 100644 --- a/Documentation/driver-api/driver-model/devres.rst +++ b/Documentation/driver-api/driver-model/devres.rst @@ -301,6 +301,7 @@ IO region devm_release_region() devm_release_resource() devm_request_mem_region() + devm_request_free_mem_region() devm_request_region() devm_request_resource() @@ -334,7 +335,7 @@ IRQ devm_irq_alloc_descs_from() devm_irq_alloc_generic_chip() devm_irq_setup_generic_chip() - devm_irq_sim_init() + devm_irq_domain_create_sim() LED devm_led_classdev_register() @@ -392,7 +393,9 @@ PHY PINCTRL devm_pinctrl_get() devm_pinctrl_put() + devm_pinctrl_get_select() devm_pinctrl_register() + devm_pinctrl_register_and_init() devm_pinctrl_unregister() POWER @@ -401,14 +404,24 @@ POWER PWM devm_pwm_get() - devm_of_pwm_get() devm_fwnode_pwm_get() REGULATOR + devm_regulator_bulk_register_supply_alias() devm_regulator_bulk_get() + devm_regulator_bulk_get_enable() + devm_regulator_bulk_put() devm_regulator_get() + devm_regulator_get_enable() + devm_regulator_get_enable_optional() + devm_regulator_get_exclusive() + devm_regulator_get_optional() + devm_regulator_irq_helper() devm_regulator_put() devm_regulator_register() + devm_regulator_register_notifier() + devm_regulator_register_supply_alias() + devm_regulator_unregister_notifier() RESET devm_reset_control_get() @@ -427,6 +440,8 @@ SLAVE DMA ENGINE devm_acpi_dma_controller_register() SPI + devm_spi_alloc_master() + devm_spi_alloc_slave() devm_spi_register_master() WATCHDOG diff --git a/Documentation/driver-api/isa.rst b/Documentation/driver-api/isa.rst index def4a7b690b5..3df1b1696524 100644 --- a/Documentation/driver-api/isa.rst +++ b/Documentation/driver-api/isa.rst @@ -100,7 +100,7 @@ I believe platform_data is available for this, but if rather not, moving the isa_driver pointer to the private struct isa_dev is ofcourse fine as well. -Then, if the the driver did not provide a .match, it matches. If it did, +Then, if the driver did not provide a .match, it matches. If it did, the driver match() method is called to determine a match. If it did **not** match, dev->platform_data is reset to indicate this to diff --git a/Documentation/driver-api/pwm.rst b/Documentation/driver-api/pwm.rst index fd26c3d895b6..8c71a2055d27 100644 --- a/Documentation/driver-api/pwm.rst +++ b/Documentation/driver-api/pwm.rst @@ -40,8 +40,7 @@ after usage with pwm_free(). New users should use the pwm_get() function and pass to it the consumer device or a consumer name. pwm_put() is used to free the PWM device. Managed -variants of the getter, devm_pwm_get(), devm_of_pwm_get(), -devm_fwnode_pwm_get(), also exist. +variants of the getter, devm_pwm_get() and devm_fwnode_pwm_get(), also exist. After being requested, a PWM has to be configured using:: diff --git a/Documentation/fb/udlfb.rst b/Documentation/fb/udlfb.rst index 732b37db3504..99cfbb7a1922 100644 --- a/Documentation/fb/udlfb.rst +++ b/Documentation/fb/udlfb.rst @@ -86,17 +86,24 @@ Module Options Special configuration for udlfb is usually unnecessary. There are a few options, however. -From the command line, pass options to modprobe -modprobe udlfb fb_defio=0 console=1 shadow=1 +From the command line, pass options to modprobe:: -Or modify options on the fly at /sys/module/udlfb/parameters directory via -sudo nano fb_defio -change the parameter in place, and save the file. + modprobe udlfb fb_defio=0 console=1 shadow=1 -Unplug/replug USB device to apply with new settings +Or change options on the fly by editing +/sys/module/udlfb/parameters/PARAMETER_NAME :: -Or for permanent option, create file like /etc/modprobe.d/udlfb.conf with text -options udlfb fb_defio=0 console=1 shadow=1 + cd /sys/module/udlfb/parameters + ls # to see a list of parameter names + sudo nano PARAMETER_NAME + # change the parameter in place, and save the file. + +Unplug/replug USB device to apply with new settings. + +Or to apply options permanently, create a modprobe configuration file +like /etc/modprobe.d/udlfb.conf with text:: + + options udlfb fb_defio=0 console=1 shadow=1 Accepted boolean options: diff --git a/Documentation/filesystems/caching/backend-api.rst b/Documentation/filesystems/caching/backend-api.rst index d7507becf674..3a199fc50828 100644 --- a/Documentation/filesystems/caching/backend-api.rst +++ b/Documentation/filesystems/caching/backend-api.rst @@ -122,7 +122,7 @@ volumes, calling:: to tell fscache that a volume has been withdrawn. This waits for all outstanding accesses on the volume to complete before returning. -When the the cache is completely withdrawn, fscache should be notified by +When the cache is completely withdrawn, fscache should be notified by calling:: void fscache_relinquish_cache(struct fscache_cache *cache); diff --git a/Documentation/filesystems/ext4/super.rst b/Documentation/filesystems/ext4/super.rst index 268888522e35..0152888cac29 100644 --- a/Documentation/filesystems/ext4/super.rst +++ b/Documentation/filesystems/ext4/super.rst @@ -456,15 +456,15 @@ The ext4 superblock is laid out as follows in * - 0x277 - __u8 - s_lastcheck_hi - - Upper 8 bits of the s_lastcheck_hi field. + - Upper 8 bits of the s_lastcheck field. * - 0x278 - __u8 - s_first_error_time_hi - - Upper 8 bits of the s_first_error_time_hi field. + - Upper 8 bits of the s_first_error_time field. * - 0x279 - __u8 - s_last_error_time_hi - - Upper 8 bits of the s_last_error_time_hi field. + - Upper 8 bits of the s_last_error_time field. * - 0x27A - __u8 - s_pad[2] diff --git a/Documentation/filesystems/f2fs.rst b/Documentation/filesystems/f2fs.rst index d0c09663dae8..17df9a02ccff 100644 --- a/Documentation/filesystems/f2fs.rst +++ b/Documentation/filesystems/f2fs.rst @@ -286,9 +286,8 @@ compress_algorithm=%s:%d Control compress algorithm and its compress level, now, algorithm level range lz4 3 - 16 zstd 1 - 22 -compress_log_size=%u Support configuring compress cluster size, the size will - be 4KB * (1 << %u), 16KB is minimum size, also it's - default size. +compress_log_size=%u Support configuring compress cluster size. The size will + be 4KB * (1 << %u). The default and minimum sizes are 16KB. compress_extension=%s Support adding specified extension, so that f2fs can enable compression on those corresponding files, e.g. if all files with '.ext' has high compression rate, we can set the '.ext' diff --git a/Documentation/filesystems/idmappings.rst b/Documentation/filesystems/idmappings.rst index c1db8748389c..b9b31066aef2 100644 --- a/Documentation/filesystems/idmappings.rst +++ b/Documentation/filesystems/idmappings.rst @@ -661,7 +661,7 @@ idmappings:: mount idmapping: u0:k10000:r10000 Assume a file owned by ``u1000`` is read from disk. The filesystem maps this id -to ``k21000`` according to it's idmapping. This is what is stored in the +to ``k21000`` according to its idmapping. This is what is stored in the inode's ``i_uid`` and ``i_gid`` fields. When the caller queries the ownership of this file via ``stat()`` the kernel diff --git a/Documentation/filesystems/qnx6.rst b/Documentation/filesystems/qnx6.rst index fd13433d362c..523b798f04e7 100644 --- a/Documentation/filesystems/qnx6.rst +++ b/Documentation/filesystems/qnx6.rst @@ -176,7 +176,7 @@ Then userspace. The requirement for a static, fixed preallocated system area comes from how qnx6fs deals with writes. -Each superblock got it's own half of the system area. So superblock #1 +Each superblock got its own half of the system area. So superblock #1 always uses blocks from the lower half while superblock #2 just writes to blocks represented by the upper half bitmap system area bits. diff --git a/Documentation/filesystems/spufs/spufs.rst b/Documentation/filesystems/spufs/spufs.rst index 8a42859bb100..ca0441cbe37e 100644 --- a/Documentation/filesystems/spufs/spufs.rst +++ b/Documentation/filesystems/spufs/spufs.rst @@ -227,7 +227,7 @@ Files from the data buffer, updating the value of the specified signal notification register. The signal notification register will either be replaced with the input data or will be updated to the - bitwise OR or the old value and the input data, depending on the + bitwise OR of the old value and the input data, depending on the contents of the signal1_type, or signal2_type respectively, file. diff --git a/Documentation/filesystems/xfs-delayed-logging-design.rst b/Documentation/filesystems/xfs-delayed-logging-design.rst index 4ef419f54663..6402ab8e370c 100644 --- a/Documentation/filesystems/xfs-delayed-logging-design.rst +++ b/Documentation/filesystems/xfs-delayed-logging-design.rst @@ -100,7 +100,7 @@ transactions together:: ntp = xfs_trans_dup(tp); xfs_trans_commit(tp); - xfs_log_reserve(ntp); + xfs_trans_reserve(ntp); This results in a series of "rolling transactions" where the inode is locked across the entire chain of transactions. Hence while this series of rolling @@ -191,7 +191,7 @@ transaction rolling mechanism to re-reserve space on every transaction roll. We know from the implementation of the permanent transactions how many transaction rolls are likely for the common modifications that need to be made. -For example, and inode allocation is typically two transactions - one to +For example, an inode allocation is typically two transactions - one to physically allocate a free inode chunk on disk, and another to allocate an inode from an inode chunk that has free inodes in it. Hence for an inode allocation transaction, we might set the reservation log count to a value of 2 to indicate @@ -200,7 +200,7 @@ chain. Each time a permanent transaction rolls, it consumes an entire unit reservation. Hence when the permanent transaction is first allocated, the log space -reservation is increases from a single unit reservation to multiple unit +reservation is increased from a single unit reservation to multiple unit reservations. That multiple is defined by the reservation log count, and this means we can roll the transaction multiple times before we have to re-reserve log space when we roll the transaction. This ensures that the common @@ -259,7 +259,7 @@ the next transaction in the sequeunce, but we have none remaining. We cannot sleep during the transaction commit process waiting for new log space to become available, as we may end up on the end of the FIFO queue and the items we have locked while we sleep could end up pinning the tail of the log before there is -enough free space in the log to fulfil all of the pending reservations and +enough free space in the log to fulfill all of the pending reservations and then wake up transaction commit in progress. To take a new reservation without sleeping requires us to be able to take a @@ -551,14 +551,14 @@ Essentially, this shows that an item that is in the AIL can still be modified and relogged, so any tracking must be separate to the AIL infrastructure. As such, we cannot reuse the AIL list pointers for tracking committed items, nor can we store state in any field that is protected by the AIL lock. Hence the -committed item tracking needs it's own locks, lists and state fields in the log +committed item tracking needs its own locks, lists and state fields in the log item. Similar to the AIL, tracking of committed items is done through a new list called the Committed Item List (CIL). The list tracks log items that have been committed and have formatted memory buffers attached to them. It tracks objects in transaction commit order, so when an object is relogged it is removed from -it's place in the list and re-inserted at the tail. This is entirely arbitrary +its place in the list and re-inserted at the tail. This is entirely arbitrary and done to make it easy for debugging - the last items in the list are the ones that are most recently modified. Ordering of the CIL is not necessary for transactional integrity (as discussed in the next section) so the ordering is @@ -615,7 +615,7 @@ those changes into the current checkpoint context. We then initialise a new context and attach that to the CIL for aggregation of new transactions. This allows us to unlock the CIL immediately after transfer of all the -committed items and effectively allow new transactions to be issued while we +committed items and effectively allows new transactions to be issued while we are formatting the checkpoint into the log. It also allows concurrent checkpoints to be written into the log buffers in the case of log force heavy workloads, just like the existing transaction commit code does. This, however, @@ -884,9 +884,9 @@ pin the object the first time it is inserted into the CIL - if it is already in the CIL during a transaction commit, then we do not pin it again. Because there can be multiple outstanding checkpoint contexts, we can still see elevated pin counts, but as each checkpoint completes the pin count will retain the correct -value according to it's context. +value according to its context. -Just to make matters more slightly more complex, this checkpoint level context +Just to make matters slightly more complex, this checkpoint level context for the pin count means that the pinning of an item must take place under the CIL commit/flush lock. If we pin the object outside this lock, we cannot guarantee which context the pin count is associated with. This is because of diff --git a/Documentation/firmware-guide/acpi/enumeration.rst b/Documentation/firmware-guide/acpi/enumeration.rst index dbb03022b127..b9dc0c603f36 100644 --- a/Documentation/firmware-guide/acpi/enumeration.rst +++ b/Documentation/firmware-guide/acpi/enumeration.rst @@ -21,7 +21,7 @@ possible we decided to do following: - Devices behind real busses where there is a connector resource are represented as struct spi_device or struct i2c_device. Note that standard UARTs are not busses so there is no struct uart_device, - although some of them may be represented by sturct serdev_device. + although some of them may be represented by struct serdev_device. As both ACPI and Device Tree represent a tree of devices (and their resources) this implementation follows the Device Tree way as much as @@ -205,7 +205,7 @@ Here is what the ACPI namespace for a SPI slave might look like:: } ... -The SPI device drivers only need to add ACPI IDs in a similar way than with +The SPI device drivers only need to add ACPI IDs in a similar way to the platform device drivers. Below is an example where we add ACPI support to at25 SPI eeprom driver (this is meant for the above ACPI snippet):: @@ -362,7 +362,7 @@ These GPIO numbers are controller relative and path "\\_SB.PCI0.GPI0" specifies the path to the controller. In order to use these GPIOs in Linux we need to translate them to the corresponding Linux GPIO descriptors. -There is a standard GPIO API for that and is documented in +There is a standard GPIO API for that and it is documented in Documentation/admin-guide/gpio/. In the above example we can get the corresponding two GPIO descriptors with @@ -538,8 +538,8 @@ information. PCI hierarchy representation ============================ -Sometimes could be useful to enumerate a PCI device, knowing its position on the -PCI bus. +Sometimes it could be useful to enumerate a PCI device, knowing its position on +the PCI bus. For example, some systems use PCI devices soldered directly on the mother board, in a fixed position (ethernet, Wi-Fi, serial ports, etc.). In this conditions it @@ -550,7 +550,7 @@ To identify a PCI device, a complete hierarchical description is required, from the chipset root port to the final device, through all the intermediate bridges/switches of the board. -For example, let us assume to have a system with a PCIe serial port, an +For example, let's assume we have a system with a PCIe serial port, an Exar XR17V3521, soldered on the main board. This UART chip also includes 16 GPIOs and we want to add the property ``gpio-line-names`` [1] to these pins. In this case, the ``lspci`` output for this component is:: @@ -593,8 +593,8 @@ of the chipset bridge (also called "root port") with address:: Bus: 0 - Device: 14 - Function: 1 -To find this information is necessary disassemble the BIOS ACPI tables, in -particular the DSDT (see also [2]):: +To find this information, it is necessary to disassemble the BIOS ACPI tables, +in particular the DSDT (see also [2]):: mkdir ~/tables/ cd ~/tables/ diff --git a/Documentation/firmware-guide/acpi/osi.rst b/Documentation/firmware-guide/acpi/osi.rst index 05869c0045d7..784850adfcb6 100644 --- a/Documentation/firmware-guide/acpi/osi.rst +++ b/Documentation/firmware-guide/acpi/osi.rst @@ -41,26 +41,23 @@ But it is likely that they will all eventually be added. What should an OEM do if they want to support Linux and Windows using the same BIOS image? Often they need to do something different for Linux to deal with how Linux is different from Windows. -Here the BIOS should ask exactly what it wants to know: +In this case, the OEM should create custom ASL to be executed by the +Linux kernel and changes to Linux kernel drivers to execute this custom +ASL. The easiest way to accomplish this is to introduce a device specific +method (_DSM) that is called from the Linux kernel. + +In the past the kernel used to support something like: _OSI("Linux-OEM-my_interface_name") where 'OEM' is needed if this is an OEM-specific hook, and 'my_interface_name' describes the hook, which could be a quirk, a bug, or a bug-fix. -In addition, the OEM should send a patch to upstream Linux -via the linux-acpi@vger.kernel.org mailing list. When that patch -is checked into Linux, the OS will answer "YES" when the BIOS -on the OEM's system uses _OSI to ask if the interface is supported -by the OS. Linux distributors can back-port that patch for Linux -pre-installs, and it will be included by all distributions that -re-base to upstream. If the distribution can not update the kernel binary, -they can also add an acpi_osi=Linux-OEM-my_interface_name -cmdline parameter to the boot loader, as needed. - -If the string refers to a feature where the upstream kernel -eventually grows support, a patch should be sent to remove -the string when that support is added to the kernel. +However this was discovered to be abused by other BIOS vendors to change +completely unrelated code on completely unrelated systems. This prompted +an evaluation of all of it's uses. This uncovered that they aren't needed +for any of the original reasons. As such, the kernel will not respond to +any custom Linux-* strings by default. That was easy. Read on, to find out how to do it wrong. diff --git a/Documentation/gpu/amdgpu/apu-asic-info-table.csv b/Documentation/gpu/amdgpu/apu-asic-info-table.csv new file mode 100644 index 000000000000..98c6988e424e --- /dev/null +++ b/Documentation/gpu/amdgpu/apu-asic-info-table.csv @@ -0,0 +1,8 @@ +Product Name, Code Reference, DCN/DCE version, GC version, VCE/UVD/VCN version, SDMA version +Radeon R* Graphics, CARRIZO/STONEY, DCE 11, 8, VCE 3 / UVD 6, 3 +Ryzen 3000 series / AMD Ryzen Embedded V1*/R1* with Radeon Vega Gfx, RAVEN/PICASSO, DCN 1.0, 9.1.0, VCN 1.0, 4.1.0 +Ryzen 4000 series, RENOIR, DCN 2.1, 9.3, VCN 2.2, 4.1.2 +Ryzen 3000 series / AMD Ryzen Embedded V1*/R1* with Radeon Vega Gfx, RAVEN2, DCN 1.0, 9.2.2, VCN 1.0.1, 4.1.1 +SteamDeck, VANGOGH, DCN 3.0.1, 10.3.1, VCN 3.1.0, 5.2.1 +Ryzen 5000 series, GREEN SARDINE, DCN 2.1, 9.3, VCN 2.2, 4.1.1 +Ryzen 6000 Zen, YELLOW CARP, 3.1.2, 10.3.3, VCN 3.1.1, 5.2.3 diff --git a/Documentation/gpu/amdgpu/dgpu-asic-info-table.csv b/Documentation/gpu/amdgpu/dgpu-asic-info-table.csv new file mode 100644 index 000000000000..84617aa35dab --- /dev/null +++ b/Documentation/gpu/amdgpu/dgpu-asic-info-table.csv @@ -0,0 +1,24 @@ +Product Name, Code Reference, DCN/DCE version, GC version, VCN version, SDMA version +AMD Radeon (TM) HD 8500M/ 8600M /M200 /M320 /M330 /M335 Series, HAINAN, --, 6, --, -- +AMD Radeon HD 7800 /7900 /FireGL Series, TAHITI, DCE 6, 6, VCE 1 / UVD 3, -- +AMD Radeon R7 (TM|HD) M265 /M370 /8500M /8600 /8700 /8700M, OLAND, DCE 6, 6, VCE 1 / UVD 3, -- +AMD Radeon (TM) (HD|R7) 7800 /7970 /8800 /8970 /370/ Series, PITCAIRN, DCE 6, 6, VCE 1 / UVD 3, -- +AMD Radeon (TM|R7|R9|HD) E8860 /M360 /7700 /7800 /8800 /9000(M) /W4100 Series, VERDE, DCE 6, 6, VCE 1 / UVD 3, -- +AMD Radeon HD M280X /M380 /7700 /8950 /W5100, BONAIRE, DCE 8, 7, VCE 2 / UVD 4.2, 1 +AMD Radeon (R9|TM) 200 /390 /W8100 /W9100 Series, HAWAII, DCE 8, 7, VCE 2 / UVD 4.2, 1 +AMD Radeon (TM) R(5|7) M315 /M340 /M360, TOPAZ, *, 8, --, 2 +AMD Radeon (TM) R9 200 /380 /W7100 /S7150 /M390 /M395 Series, TONGA, DCE 10, 8, VCE 3 / UVD 5, 3 +AMD Radeon (FirePro) (TM) R9 Fury Series, FIJI, DCE 10, 8, VCE 3 / UVD 6, 3 +Radeon RX 470 /480 /570 /580 /590 Series - AMD Radeon (TM) (Pro WX) 5100 /E9390 /E9560 /E9565 /V7350 /7100 /P30PH, POLARIS10, DCE 11.2, 8, VCE 3.4 / UVD 6.3, 3 +Radeon (TM) (RX|Pro WX) E9260 /460 /V5300X /550 /560(X) Series, POLARIS11, DCE 11.2, 8, VCE 3.4 / UVD 6.3, 3 +Radeon (RX/Pro) 500 /540(X) /550 /640 /WX2100 /WX3100 /WX200 Series, POLARIS12, DCE 11.2, 8, VCE 3.4 / UVD 6.3, 3 +Radeon (RX|TM) (PRO|WX) Vega /MI25 /V320 /V340L /8200 /9100 /SSG MxGPU, VEGA10, DCE 12, 9.0.1, VCE 4.0.0 / UVD 7.0.0, 4.0.0 +AMD Radeon (Pro) VII /MI50 /MI60, VEGA20, DCE 12, 9.4.0, VCE 4.1.0 / UVD 7.2.0, 4.2.0 +MI100, ARCTURUS, *, 9.4.1, VCN 2.5.0, 4.2.2 +MI200, ALDEBARAN, *, 9.4.2, VCN 2.6.0, 4.4.0 +AMD Radeon (RX|Pro) 5600(M|XT) /5700 (M|XT|XTB) /W5700, NAVI10, DCN 2.0.0, 10.1.10, VCN 2.0.0, 5.0.0 +AMD Radeon (Pro) 5300 /5500XTB/5500(XT|M) /W5500M /W5500, NAVI14, DCN 2.0.0, 10.1.1, VCN 2.0.2, 5.0.2 +AMD Radeon RX 6800(XT) /6900(XT) /W6800, SIENNA_CICHLID, DCN 3.0.0, 10.3.0, VCN 3.0.0, 5.2.0 +AMD Radeon RX 6700 XT / 6800M / 6700M, NAVY_FLOUNDER, DCN 3.0.0, 10.3.2, VCN 3.0.0, 5.2.2 +AMD Radeon RX 6600(XT) /6600M /W6600 /W6600M, DIMGREY_CAVEFISH, DCN 3.0.2, 10.3.4, VCN 3.0.16, 5.2.4 +AMD Radeon RX 6500M /6300M /W6500M /W6300M, BEIGE_GOBY, DCN 3.0.3, 10.3.5, VCN 3.0.33, 5.2.5 diff --git a/Documentation/gpu/amdgpu/display/dc-glossary.rst b/Documentation/gpu/amdgpu/display/dc-glossary.rst index 116f5f0942fd..0b0ffd428dd2 100644 --- a/Documentation/gpu/amdgpu/display/dc-glossary.rst +++ b/Documentation/gpu/amdgpu/display/dc-glossary.rst @@ -170,7 +170,7 @@ consider asking in the amdgfx and update this page. MC Memory Controller - MPC + MPC/MPCC Multiple pipes and plane combine MPO diff --git a/Documentation/gpu/amdgpu/display/dcn-overview.rst b/Documentation/gpu/amdgpu/display/dcn-overview.rst index f98624d7828e..9fea6500448b 100644 --- a/Documentation/gpu/amdgpu/display/dcn-overview.rst +++ b/Documentation/gpu/amdgpu/display/dcn-overview.rst @@ -124,6 +124,65 @@ 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. +AMD Hardware Pipeline +--------------------- + +When discussing graphics on Linux, the **pipeline** term can sometimes be +overloaded with multiple meanings, so it is important to define what we mean +when we say **pipeline**. In the DCN driver, we use the term **hardware +pipeline** or **pipeline** or just **pipe** as an abstraction to indicate a +sequence of DCN blocks instantiated to address some specific configuration. DC +core treats DCN blocks as individual resources, meaning we can build a pipeline +by taking resources for all individual hardware blocks to compose one pipeline. +In actuality, we can't connect an arbitrary block from one pipe to a block from +another pipe; they are routed linearly, except for DSC, which can be +arbitrarily assigned as needed. We have this pipeline concept for trying to +optimize bandwidth utilization. + +.. kernel-figure:: pipeline_4k_no_split.svg + +Additionally, let's take a look at parts of the DTN log (see +'Documentation/gpu/amdgpu/display/dc-debug.rst' for more information) since +this log can help us to see part of this pipeline behavior in real-time:: + + HUBP: format addr_hi width height ... + [ 0]: 8h 81h 3840 2160 + [ 1]: 0h 0h 0 0 + [ 2]: 0h 0h 0 0 + [ 3]: 0h 0h 0 0 + [ 4]: 0h 0h 0 0 + ... + MPCC: OPP DPP ... + [ 0]: 0h 0h ... + +The first thing to notice from the diagram and DTN log it is the fact that we +have different clock domains for each part of the DCN blocks. In this example, +we have just a single **pipeline** where the data flows from DCHUB to DIO, as +we intuitively expect. Nonetheless, DCN is flexible, as mentioned before, and +we can split this single pipe differently, as described in the below diagram: + +.. kernel-figure:: pipeline_4k_split.svg + +Now, if we inspect the DTN log again we can see some interesting changes:: + + HUBP: format addr_hi width height ... + [ 0]: 8h 81h 1920 2160 ... + ... + [ 4]: 0h 0h 0 0 ... + [ 5]: 8h 81h 1920 2160 ... + ... + MPCC: OPP DPP ... + [ 0]: 0h 0h ... + [ 5]: 0h 5h ... + +From the above example, we now split the display pipeline into two vertical +parts of 1920x2160 (i.e., 3440x2160), and as a result, we could reduce the +clock frequency in the DPP part. This is not only useful for saving power but +also to better handle the required throughput. The idea to keep in mind here is +that the pipe configuration can vary a lot according to the display +configuration, and it is the DML's responsibility to set up all required +configuration parameters for multiple scenarios supported by our hardware. + Global Sync ----------- diff --git a/Documentation/gpu/amdgpu/display/dcn2_cm_drm_current.svg b/Documentation/gpu/amdgpu/display/dcn2_cm_drm_current.svg new file mode 100644 index 000000000000..315ffc5a1a4b --- /dev/null +++ b/Documentation/gpu/amdgpu/display/dcn2_cm_drm_current.svg @@ -0,0 +1,1370 @@ +<?xml version="1.0" encoding="UTF-8" standalone="no"?> +<!-- Created with Inkscape (http://www.inkscape.org/) --> + +<svg + version="1.1" + id="svg2019" + width="1702" + height="1845" + viewBox="0 0 1702 1845" + sodipodi:docname="dcn2_cm_drm_current.svg" + inkscape:version="1.1.2 (0a00cf5339, 2022-02-04)" + xmlns:inkscape="http://www.inkscape.org/namespaces/inkscape" + xmlns:sodipodi="http://sodipodi.sourceforge.net/DTD/sodipodi-0.dtd" + xmlns="http://www.w3.org/2000/svg" + xmlns:svg="http://www.w3.org/2000/svg"> + <defs + id="defs2023" /> + <sodipodi:namedview + id="namedview2021" + pagecolor="#ffffff" + bordercolor="#666666" + borderopacity="1.0" + inkscape:pageshadow="2" + inkscape:pageopacity="0.0" + inkscape:pagecheckerboard="0" + showgrid="false" + inkscape:zoom="0.56413987" + inkscape:cx="1003.2973" + inkscape:cy="691.31792" + inkscape:window-width="1920" + inkscape:window-height="1011" + inkscape:window-x="0" + inkscape:window-y="0" + inkscape:window-maximized="1" + inkscape:current-layer="g2025" /> + <g + inkscape:groupmode="layer" + inkscape:label="Image" + id="g2025"> + <rect + style="fill:#000000;fill-opacity:0;stroke:#000000;stroke-opacity:1" + id="rect34" + width="208.83351" + height="486.09872" + x="0.90158081" + y="132.77872" /> + <rect + style="fill:#fad7ac;fill-opacity:1;stroke:#000000;stroke-opacity:1" + id="rect1019" + width="126.38867" + height="55.320732" + x="25.960823" + y="188.06937" /> + <rect + style="fill:#d0cee2;fill-opacity:1;stroke:#000000;stroke-opacity:1" + id="rect1021" + width="126.38867" + height="55.320732" + x="25.960823" + y="346.06937" /> + <rect + style="fill:#afdde9;fill-opacity:1;stroke:#000000;stroke-opacity:1" + id="rect1103" + width="126.38867" + height="55.320732" + x="25.960823" + y="266.06937" /> + <rect + style="fill:#f9f7ed;fill-opacity:1;stroke:#000000;stroke-opacity:1" + id="rect1105" + width="126.38867" + height="55.320732" + x="25.960823" + y="426.06937" /> + <rect + style="fill:#e6e6e6;fill-opacity:1;stroke:#000000;stroke-opacity:1" + id="rect1107" + width="126.38867" + height="55.320732" + x="25.960823" + y="506.06934" /> + <path + d="m 402.61883,171.88069 c 0.025,10.97895 0.01,1001.03791 0.049,1012.01891 2.5462,-1.1592 5.0637,-2.3779 7.6202,-3.5187 -2.7411,4.8298 -5.4987,9.6453 -8.2624,14.4607 -2.7925,-4.8257 -5.5993,-9.6453 -8.3856,-14.4751 2.6221,1.1736 5.2217,2.3923 7.8398,3.5721 0,-10.8825 -0.035,-1000.84096 -0.031,-1011.72348 0.053,-0.30366 -0.2175,-0.50268 -0.3652,-0.72837 l 1.5347,0.39394 z" + id="path381056" + sodipodi:nodetypes="cccccccccc" + style="stroke-width:0.205176" + inkscape:transform-center-x="-325.50819" + inkscape:transform-center-y="-121.97185" /> + <rect + style="fill:#000000;fill-opacity:0;stroke:#000000;stroke-opacity:1" + id="rect1131" + width="239.47592" + height="1015.9909" + x="298.65631" + y="82.399658" /> + <rect + style="fill:#000000;fill-opacity:0;stroke:#000000;stroke-width:1.27861;stroke-opacity:1" + id="rect1133" + width="340.44653" + height="525.77448" + x="298.79562" + y="1142.5299" /> + <rect + style="fill:#000000;fill-opacity:0;stroke:#000000;stroke-opacity:1" + id="rect1237" + width="284.00113" + height="945.41412" + x="827.75012" + y="82.880798" + inkscape:connector-avoid="true" /> + <rect + style="fill:#000000;fill-opacity:0;stroke:#000000;stroke-opacity:1" + id="rect1239" + width="239.37569" + height="179.03308" + x="1356.9507" + y="98.758331" /> + <rect + style="fill:#000000;fill-opacity:0;stroke:#000000;stroke-width:1.00744;stroke-opacity:1" + id="rect1241" + width="239.4184" + height="713.64905" + x="1356.9543" + y="307.7951" + inkscape:connector-avoid="true" /> + <rect + style="fill:#000000;fill-opacity:0;stroke:#000000;stroke-opacity:1" + id="rect1345" + width="330.32059" + height="409.44757" + x="1363.8723" + y="1147.7572" /> + <rect + style="fill:#000000;fill-opacity:0;stroke:#000000;stroke-opacity:1" + id="rect1347" + width="369.8941" + height="682.32245" + x="825.72528" + y="1146.6448" + inkscape:connector-avoid="true" /> + <rect + style="fill:#f9f7ed;fill-opacity:1;stroke:#000000;stroke-opacity:1" + id="rect1349" + width="163.95746" + height="40.144867" + x="1389.9988" + y="190.80583" /> + <rect + style="fill:#000000;fill-opacity:0;stroke:#000000;stroke-width:0.964132;stroke-opacity:1" + id="rect1619" + width="271.99091" + height="42.038273" + x="1393.981" + y="1197.161" + inkscape:connector-avoid="true" /> + <path + d="m 1469.3028,1238.8328 c 0.025,10.9789 0.01,175.0378 0.049,186.0188 2.5462,-1.1592 5.0637,-2.3779 7.6202,-3.5187 -2.7411,4.8298 -5.4987,9.6453 -8.2624,14.4607 -2.7925,-4.8257 -5.5993,-9.6453 -8.3856,-14.4751 2.6221,1.1736 5.2217,2.3923 7.8398,3.5721 0,-10.8825 -0.035,-174.8409 -0.031,-185.7234 0.053,-0.3037 -0.2175,-0.5027 -0.3652,-0.7284 l 1.5347,0.394 z" + id="path106-1" + sodipodi:nodetypes="cccccccccc" + style="stroke-width:0.205176" + inkscape:transform-center-x="-325.50819" + inkscape:transform-center-y="-121.97185" /> + <path + d="m 407.4759,1238.4728 c 0.025,10.9789 0.01,291.0378 0.049,302.0188 2.5462,-1.1592 5.0637,-2.3779 7.6202,-3.5187 -2.7411,4.8298 -5.4987,9.6453 -8.2624,14.4607 -2.7925,-4.8257 -5.5993,-9.6453 -8.3856,-14.4751 2.6221,1.1736 5.2217,2.3923 7.8398,3.5721 0,-10.8825 -0.035,-290.8409 -0.031,-301.7234 0.053,-0.3037 -0.2175,-0.5027 -0.3652,-0.7284 l 1.5347,0.394 z" + id="path106-1-7" + sodipodi:nodetypes="cccccccccc" + style="stroke-width:0.205176" + inkscape:transform-center-x="-325.50819" + inkscape:transform-center-y="-121.97185" /> + <rect + style="fill:#afdde9;fill-opacity:1;stroke:#000000;stroke-opacity:1" + id="rect1623" + width="137.32646" + height="41.782684" + x="1396.3848" + y="1268.2837" + inkscape:connector-avoid="true" /> + <rect + style="fill:#fad7ac;fill-opacity:1;stroke:#000000;stroke-opacity:1" + id="rect1705" + width="137.32646" + height="41.782684" + x="1396.3848" + y="1348.2837" /> + <rect + style="fill:#afdde9;fill-opacity:1;stroke:#000000;stroke-opacity:1" + id="rect1707" + width="137.32646" + height="41.782684" + x="1396.3848" + y="1432.2837" /> + <rect + style="fill:#f9f7ed;fill-opacity:1;stroke:#000000;stroke-opacity:1" + id="rect1731" + width="222.34483" + height="44.64616" + x="867.36292" + y="190.42665" + inkscape:connector-avoid="true" /> + <rect + style="fill:#f9f7ed;fill-opacity:1;stroke:#000000;stroke-opacity:1" + id="rect1813" + width="222.34483" + height="44.64616" + x="867.36292" + y="254.42664" + inkscape:connector-avoid="true" /> + <rect + style="fill:#f9f7ed;fill-opacity:1;stroke:#000000;stroke-opacity:1" + id="rect1815" + width="222.34483" + height="44.64616" + x="867.36292" + y="318.42664" + inkscape:connector-avoid="true" /> + <rect + style="fill:#fad7ac;fill-opacity:1;stroke:#000000;stroke-opacity:1" + id="rect1817" + width="222.34483" + height="44.64616" + x="867.36292" + y="412.42664" + inkscape:connector-avoid="true" /> + <rect + style="fill:#afdde9;fill-opacity:1;stroke:#000000;stroke-opacity:1" + id="rect1819" + width="222.34483" + height="44.64616" + x="867.36292" + y="560.42664" /> + <rect + style="fill:#e6e6e6;fill-opacity:1;stroke:#000000;stroke-opacity:1" + id="rect1821" + width="222.34483" + height="44.64616" + x="867.36292" + y="674.42664" + inkscape:connector-avoid="true" /> + <rect + style="fill:#fad7ac;fill-opacity:1;stroke:#000000;stroke-opacity:1" + id="rect1823" + width="222.34483" + height="44.64616" + x="867.36292" + y="744.42664" + inkscape:connector-avoid="true" /> + <rect + style="fill:#afdde9;fill-opacity:1;stroke:#000000;stroke-opacity:1" + id="rect1825" + width="222.34483" + height="44.64616" + x="867.36292" + y="820.42664" + inkscape:connector-avoid="true" /> + <rect + style="fill:#d0cee2;fill-opacity:1;stroke:#000000;stroke-opacity:1" + id="rect1827" + width="222.34483" + height="44.64616" + x="867.36292" + y="890.42664" + inkscape:connector-avoid="true" /> + <rect + style="fill:#afdde9;fill-opacity:1;stroke:#000000;stroke-opacity:1" + id="rect1829" + width="222.34483" + height="44.64616" + x="867.36292" + y="956.42664" + inkscape:connector-avoid="true" /> + <rect + style="fill:#fad7ac;fill-opacity:1;stroke:#000000;stroke-opacity:1" + id="rect1831" + width="222.34483" + height="44.64616" + x="867.36292" + y="1256.4268" /> + <rect + style="fill:#d0cee2;fill-opacity:1;stroke:#000000;stroke-opacity:1" + id="rect1833" + width="222.34483" + height="44.64616" + x="867.36292" + y="1402.4268" /> + <rect + style="fill:#afdde9;fill-opacity:1;stroke:#000000;stroke-opacity:1" + id="rect1915" + width="222.34483" + height="44.64616" + x="867.36292" + y="1330.4268" + inkscape:connector-avoid="true" /> + <rect + style="fill:#afdde9;fill-opacity:1;stroke:#000000;stroke-opacity:1" + id="rect1917" + width="222.34483" + height="44.64616" + x="867.36292" + y="1478.4268" /> + <rect + style="fill:#fad7ac;fill-opacity:1;stroke:#000000;stroke-opacity:1" + id="rect1919" + width="222.34483" + height="44.64616" + x="867.36292" + y="1548.4268" /> + <rect + style="fill:#eeeeee;fill-opacity:1;stroke:#000000;stroke-opacity:1" + id="rect1921" + width="222.34483" + height="44.64616" + x="867.36292" + y="1614.4268" /> + <rect + style="fill:#eeeeee;fill-opacity:1;stroke:#000000;stroke-opacity:1" + id="rect1923" + width="222.34483" + height="44.64616" + x="867.36292" + y="1686.4268" /> + <rect + style="fill:#eeeeee;fill-opacity:1;stroke:#000000;stroke-opacity:1" + id="rect1925" + width="222.34483" + height="44.64616" + x="867.36292" + y="1754.4268" /> + <rect + style="fill:#f9f7ed;fill-opacity:1;stroke:#000000;stroke-width:0.872749;stroke-opacity:1" + id="rect1925-3" + width="169.23357" + height="44.678963" + x="325.21747" + y="134.37756" /> + <rect + style="fill:#fad7ac;fill-opacity:1;stroke:#000000;stroke-width:0.872749;stroke-opacity:1" + id="rect1954" + width="169.23357" + height="44.678963" + x="325.21747" + y="276.37756" + inkscape:connector-avoid="true" /> + <rect + style="fill:#afdde9;fill-opacity:1;stroke:#000000;stroke-width:0.87333333;stroke-opacity:1;stroke-miterlimit:4;stroke-dasharray:none" + id="rect1956" + width="168.66573" + height="122.14091" + x="325.50134" + y="358.6615" + inkscape:connector-avoid="true" /> + <rect + style="fill:#e6e6e6;fill-opacity:1;stroke:#000000;stroke-width:0.872749;stroke-opacity:1" + id="rect1958" + width="169.23357" + height="44.678963" + x="325.21747" + y="672.37756" /> + <rect + style="fill:#fad7ac;fill-opacity:1;stroke:#000000;stroke-width:0.872749;stroke-opacity:1" + id="rect1960" + width="169.23357" + height="44.678963" + x="325.21747" + y="744.37756" /> + <rect + style="fill:#afdde9;fill-opacity:1;stroke:#000000;stroke-width:0.965912;stroke-opacity:1" + id="rect1962" + width="169.14041" + height="54.756817" + x="325.26404" + y="814.42413" + inkscape:connector-avoid="true" /> + <rect + style="fill:#d0cee2;fill-opacity:1;stroke:#000000;stroke-width:0.965912;stroke-opacity:1" + id="rect1964" + width="169.14041" + height="54.756817" + x="325.26404" + y="886.42413" + inkscape:connector-avoid="true" /> + <rect + style="fill:#afdde9;fill-opacity:1;stroke:#000000;stroke-width:0.965912;stroke-opacity:1" + id="rect1966" + width="169.14041" + height="54.756817" + x="325.26404" + y="952.42413" + inkscape:connector-avoid="true" /> + <rect + style="fill:#afdde9;fill-opacity:1;stroke:#000000;stroke-width:1.02091;stroke-opacity:1" + id="rect2428" + width="169.0854" + height="61.19017" + x="325.29156" + y="1468.4518" /> + <rect + style="fill:#fad7ac;fill-opacity:1;stroke:#000000;stroke-width:0.839627;stroke-opacity:1" + id="rect2430" + width="169.26669" + height="41.344128" + x="325.20093" + y="1550.3611" /> + <rect + style="fill:#000000;fill-opacity:0;stroke:#000000;stroke-width:1.13491;stroke-opacity:1" + id="rect2432" + width="287.86237" + height="44.416805" + x="325.34854" + y="1194.5088" /> + <rect + style="fill:#000000;fill-opacity:0;stroke:#000000;stroke-width:1.13102;stroke-opacity:1" + id="rect2434" + width="285.86655" + height="44.4207" + x="867.34656" + y="1194.5068" /> + <path + style="fill:none;stroke:#000000;stroke-width:2.66666675;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1;stroke-miterlimit:4;stroke-dasharray:8.00000024, 8.00000024;stroke-dashoffset:0" + d="m 867.36292,235.07281 v 0" + id="path2509" /> + <path + style="fill:none;stroke:#000000;stroke-width:2.66666675;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1;stroke-miterlimit:4;stroke-dasharray:8.00000024, 8.00000024;stroke-dashoffset:0" + d="m 867.36292,235.07281 v 0" + id="path2511" /> + <path + style="fill:none;stroke:#000000;stroke-width:2.66666675;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1;stroke-miterlimit:4;stroke-dasharray:8.00000024, 8.00000024;stroke-dashoffset:0" + d="m 867.36292,235.07281 v 0" + id="path2513" /> + <path + style="fill:none;stroke:#000000;stroke-width:2.66666675;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1;stroke-miterlimit:4;stroke-dasharray:8.00000024, 8.00000024;stroke-dashoffset:0" + d="m 867.36292,235.07281 v 0" + id="path2515" /> + <path + style="fill:none;stroke:#000000;stroke-width:2.66666675;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1;stroke-miterlimit:4;stroke-dasharray:8.00000024, 8.00000024;stroke-dashoffset:0" + d="m 867.36292,235.07281 v 0" + id="path2517" /> + <path + style="fill:none;stroke:#000000;stroke-width:2.66666675;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1;stroke-miterlimit:4;stroke-dasharray:8.00000024, 8.00000024;stroke-dashoffset:0" + d="m 867.36292,235.07281 v 0" + id="path2519" /> + <path + style="fill:none;stroke:#000000;stroke-width:2.66666675;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1;stroke-miterlimit:4;stroke-dasharray:8.00000024, 8.00000024;stroke-dashoffset:0" + d="m 867.36292,235.07281 v 0" + id="path2521" /> + <path + style="fill:none;stroke:#000000;stroke-width:2.66666675;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1;stroke-miterlimit:4;stroke-dasharray:8.00000024, 8.00000024;stroke-dashoffset:0" + d="m 867.36292,235.07281 v 0" + id="path2523" /> + <path + style="fill:none;stroke:#000000;stroke-width:2.66666675;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1;stroke-miterlimit:4;stroke-dasharray:8.00000024, 8.00000024;stroke-dashoffset:0" + d="m 867.36292,235.07281 v 0" + id="path2525" /> + <path + style="fill:none;stroke:#000000;stroke-width:2.66666675;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1;stroke-miterlimit:4;stroke-dasharray:8.00000024, 8.00000024;stroke-dashoffset:0" + d="m 867.36292,235.07281 v 0" + id="path2527" /> + <path + style="fill:none;stroke:#000000;stroke-width:2.66666675;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1;stroke-miterlimit:4;stroke-dasharray:8.00000024, 8.00000024;stroke-dashoffset:0" + d="m 867.36292,235.07281 v 0" + id="path2529" /> + <path + style="fill:none;stroke:#000000;stroke-width:2.66666675;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1;stroke-miterlimit:4;stroke-dasharray:8.00000024, 8.00000024;stroke-dashoffset:0" + d="m 867.36292,235.07281 v 0" + id="path2531" /> + <path + style="fill:none;fill-rule:evenodd;stroke:#000000;stroke-width:2;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:6, 6;stroke-dashoffset:0;stroke-opacity:1" + d="m 442.80064,179.02883 0.91401,36.01283 423.64827,-2.29193" + id="path6876" + inkscape:connector-type="orthogonal" + inkscape:connector-curvature="0" + inkscape:connection-start="#rect1925-3" + inkscape:connection-end="#rect1731" + sodipodi:nodetypes="ccc" /> + <path + style="display:inline;fill:none;fill-rule:evenodd;stroke:#000000;stroke-width:2;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:6, 6;stroke-dashoffset:0;stroke-opacity:1" + d="m 494.45103,156.71704 205.18886,-0.43622 0.59548,162.1112 167.12755,0.0346" + id="path6878" + inkscape:connector-type="orthogonal" + inkscape:connector-curvature="0" + inkscape:connection-start="#rect1925-3" + sodipodi:nodetypes="cccc" /> + <path + style="fill:none;fill-rule:evenodd;stroke:#000000;stroke-width:2;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:6, 6;stroke-dashoffset:0;stroke-opacity:1" + d="m 447.83425,321.05653 v 19.69319 h 419.52867" + id="path7294" + inkscape:connector-type="orthogonal" + inkscape:connector-curvature="0" + inkscape:connection-start="#rect1954" + inkscape:connection-end="#rect1815" + sodipodi:nodetypes="ccc" /> + <path + style="fill:none;fill-rule:evenodd;stroke:#000000;stroke-width:2;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:6, 6;stroke-dashoffset:0;stroke-opacity:1" + d="M 494.45103,298.71704 H 659.10058 V 434.74972 H 867.36292" + id="path7296" + inkscape:connector-type="orthogonal" + inkscape:connector-curvature="0" + inkscape:connection-end="#rect1817" + inkscape:connection-start="#rect1954" + sodipodi:nodetypes="cccc" /> + <path + style="display:inline;fill:none;fill-rule:evenodd;stroke:#000000;stroke-width:2;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:6, 6;stroke-dashoffset:0;stroke-opacity:1" + d="m 867.36292,560.42664 -422.77356,1.33638 0.45008,-79.26417" + id="path7720" + inkscape:connector-type="orthogonal" + inkscape:connector-curvature="0" + sodipodi:nodetypes="ccc" /> + <path + style="fill:none;fill-rule:evenodd;stroke:#000000;stroke-width:2;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:6, 6;stroke-dashoffset:0;stroke-opacity:1" + d="M 494.45103,696.74972 H 867.36292" + id="path7726" + inkscape:connector-type="orthogonal" + inkscape:connector-curvature="0" + inkscape:connection-start="#rect1958" + inkscape:connection-end="#rect1821" /> + <path + style="fill:none;fill-rule:evenodd;stroke:#000000;stroke-width:2;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:6, 6;stroke-dashoffset:0;stroke-opacity:1" + d="M 867.36292,766.74972 H 494.45103" + id="path7728" + inkscape:connector-type="orthogonal" + inkscape:connector-curvature="0" + inkscape:connection-start="#rect1823" + inkscape:connection-end="#rect1960" /> + <path + style="display:inline;fill:none;fill-rule:evenodd;stroke:#000000;stroke-width:2;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:6, 6;stroke-dashoffset:0;stroke-opacity:1" + d="M 494.45105,789.05652 H 657.82418 V 1278.7498 H 867.36292" + id="path7730" + inkscape:connector-type="orthogonal" + inkscape:connector-curvature="0" + inkscape:connection-end="#rect1831" + sodipodi:nodetypes="cccc" /> + <path + style="fill:none;fill-rule:evenodd;stroke:#000000;stroke-width:2;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:6, 6;stroke-dashoffset:0;stroke-opacity:1" + d="m 494.40445,841.80254 h 167.41973 v 0.94718 h 205.53874" + id="path8140" + inkscape:connector-type="orthogonal" + inkscape:connector-curvature="0" + inkscape:connection-start="#rect1962" + inkscape:connection-end="#rect1825" /> + <path + style="fill:none;fill-rule:evenodd;stroke:#000000;stroke-width:2;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:6, 6;stroke-dashoffset:0;stroke-opacity:1" + d="m 494.40445,913.80254 h 167.41973 v -1.05282 h 205.53874" + id="path8142" + inkscape:connector-type="orthogonal" + inkscape:connector-curvature="0" + inkscape:connection-start="#rect1964" + inkscape:connection-end="#rect1827" /> + <path + style="fill:none;fill-rule:evenodd;stroke:#000000;stroke-width:2;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:6, 6;stroke-dashoffset:0;stroke-opacity:1" + d="m 494.40445,979.80254 h 167.41973 v -1.05282 h 205.53874" + id="path8144" + inkscape:connector-type="orthogonal" + inkscape:connector-curvature="0" + inkscape:connection-start="#rect1966" + inkscape:connection-end="#rect1829" /> + <path + style="fill:none;fill-rule:evenodd;stroke:#000000;stroke-width:2;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:6, 6;stroke-dashoffset:0;stroke-opacity:1" + d="M 494.37697,1500.7498 H 867.36292" + id="path8150" + inkscape:connector-type="orthogonal" + inkscape:connector-curvature="0" + inkscape:connection-start="#rect2428" + inkscape:connection-end="#rect1917" /> + <path + style="fill:none;fill-rule:evenodd;stroke:#000000;stroke-width:2;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:6, 6;stroke-dashoffset:0;stroke-opacity:1" + d="m 494.46762,1570.7498 h 372.8953" + id="path8152" + inkscape:connector-type="orthogonal" + inkscape:connector-curvature="0" + inkscape:connection-start="#rect2430" + inkscape:connection-end="#rect1919" /> + <path + style="fill:none;fill-rule:evenodd;stroke:#000000;stroke-width:2;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:6, 6;stroke-dashoffset:0;stroke-opacity:1" + d="M 1396.3848,1289.175 H 1288.1445 V 582.74972 h -198.4368" + id="path8154" + inkscape:connector-type="orthogonal" + inkscape:connector-curvature="0" + inkscape:connection-start="#rect1623" + inkscape:connection-end="#rect1819" /> + <path + style="fill:none;fill-rule:evenodd;stroke:#000000;stroke-width:2;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:6, 6;stroke-dashoffset:0;stroke-opacity:1" + d="m 1396.3848,1369.175 -159.2837,-1.364 0.5816,-88.2579 -147.975,-0.8033" + id="path8462" + inkscape:connector-type="orthogonal" + inkscape:connector-curvature="0" + inkscape:connection-start="#rect1705" + inkscape:connection-end="#rect1831" + sodipodi:nodetypes="cccc" /> + <path + style="fill:none;fill-rule:evenodd;stroke:#000000;stroke-width:2;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:6, 6;stroke-dashoffset:0;stroke-opacity:1" + d="m 1089.7077,1500.7498 h 375.3403 v -26.6834" + id="path8668" + inkscape:connector-type="orthogonal" + inkscape:connector-curvature="0" + inkscape:connection-start="#rect1917" + inkscape:connection-end="#rect1707" /> + <path + style="fill:none;fill-rule:evenodd;stroke:#000000;stroke-width:2;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:6, 6;stroke-dashoffset:0;stroke-opacity:1" + d="M 1389.9988,212.74973 H 1089.7077" + id="path8672" + inkscape:connector-type="orthogonal" + inkscape:connector-curvature="0" + inkscape:connection-start="#rect1349" + inkscape:connection-end="#rect1731" /> + <path + style="display:inline;fill:none;fill-rule:evenodd;stroke:#000000;stroke-width:2;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:6, 6;stroke-dashoffset:0;stroke-opacity:1" + d="M 1389.9988,230.9507 H 1223.331 v 109.79902 h -133.6233" + id="path8674" + inkscape:connector-type="orthogonal" + inkscape:connector-curvature="0" + inkscape:connection-end="#rect1815" + sodipodi:nodetypes="cccc" /> + <text + xml:space="preserve" + style="font-style:normal;font-weight:normal;font-size:40px;line-height:1.25;font-family:sans-serif;fill:#000000;fill-opacity:1;stroke:none" + x="58.63356" + y="69.574417" + id="text28675"><tspan + sodipodi:role="line" + id="tspan28673" + x="58.63356" + y="69.574417" /></text> + <text + xml:space="preserve" + style="font-style:normal;font-weight:normal;font-size:18.6667px;line-height:1.25;font-family:sans-serif;fill:#000000;fill-opacity:1;stroke:none" + x="56.388252" + y="221.86568" + id="text31913"><tspan + sodipodi:role="line" + id="tspan31911" + x="56.388252" + y="221.86568">Matrix</tspan></text> + <text + xml:space="preserve" + style="font-style:normal;font-weight:normal;font-size:18.6667px;line-height:1.25;font-family:sans-serif;fill:#000000;fill-opacity:1;stroke:none" + x="53.441296" + y="300.866" + id="text38843"><tspan + sodipodi:role="line" + id="tspan38841" + x="53.441296" + y="300.866">1D LUT</tspan></text> + <text + xml:space="preserve" + style="font-style:normal;font-weight:normal;font-size:18.6667px;line-height:1.25;font-family:sans-serif;fill:#000000;fill-opacity:1;stroke:none" + x="53.441296" + y="378.866" + id="text41049"><tspan + sodipodi:role="line" + id="tspan41047" + x="53.441296" + y="378.866">3D LUT</tspan></text> + <text + xml:space="preserve" + style="font-style:normal;font-weight:normal;font-size:18.6667px;line-height:1.25;font-family:sans-serif;fill:#000000;fill-opacity:1;stroke:none" + x="40.831493" + y="460.87411" + id="text45037"><tspan + sodipodi:role="line" + id="tspan45035" + x="40.831493" + y="460.87411" + style="font-size:18.6667px">Unpacking</tspan></text> + <text + xml:space="preserve" + style="font-style:normal;font-weight:normal;font-size:18.6667px;line-height:1.25;font-family:sans-serif;fill:#000000;fill-opacity:1;stroke:none" + x="62.130371" + y="540.68872" + id="text49945"><tspan + sodipodi:role="line" + id="tspan49943" + x="62.130371" + y="540.68872" + style="font-size:18.6667px">Other</tspan></text> + <text + xml:space="preserve" + style="font-style:normal;font-weight:normal;font-size:18.6667px;line-height:1.25;font-family:sans-serif;fill:#000000;fill-opacity:1;stroke:none" + x="1423.2806" + y="128.08769" + id="text55719"><tspan + sodipodi:role="line" + id="tspan55717" + x="1423.2806" + y="128.08769" + style="font-size:18.6667px">drm_framebuffer</tspan></text> + <text + xml:space="preserve" + style="font-style:normal;font-weight:normal;font-size:18.6667px;line-height:1.25;font-family:sans-serif;fill:#000000;fill-opacity:1;stroke:none" + x="1439.9988" + y="218.74973" + id="text62479"><tspan + sodipodi:role="line" + id="tspan62477" + x="1439.9988" + y="218.74973" + style="font-size:18.6667px">format</tspan></text> + <text + xml:space="preserve" + style="font-style:normal;font-weight:normal;font-size:18.6667px;line-height:1.25;font-family:sans-serif;fill:#000000;fill-opacity:1;stroke:none" + x="1475.2806" + y="340.08771" + id="text64465"><tspan + sodipodi:role="line" + id="tspan64463" + x="1475.2806" + y="340.08771" + style="font-size:18.6667px">drm_plane</tspan></text> + <text + xml:space="preserve" + style="font-style:normal;font-weight:normal;font-size:18.6667px;line-height:1.25;font-family:sans-serif;fill:#000000;fill-opacity:1;stroke:none" + x="1589.2806" + y="1178.0876" + id="text64469"><tspan + sodipodi:role="line" + id="tspan64467" + x="1589.2806" + y="1178.0876" + style="font-size:18.6667px">drm_crtc</tspan></text> + <text + xml:space="preserve" + style="font-style:normal;font-weight:normal;font-size:18.6667px;line-height:1.25;font-family:sans-serif;fill:#000000;fill-opacity:1;stroke:none" + x="872.23993" + y="1172.4491" + id="text64469-9"><tspan + sodipodi:role="line" + id="tspan64467-2" + x="872.23993" + y="1172.4491" + style="font-size:18.6667px">Stream</tspan></text> + <text + xml:space="preserve" + style="font-style:normal;font-weight:normal;font-size:18.6667px;line-height:1.25;font-family:sans-serif;fill:#000000;fill-opacity:1;stroke:none" + x="328.26071" + y="1175.6371" + id="text64469-9-2"><tspan + sodipodi:role="line" + id="tspan64467-2-8" + x="328.26071" + y="1175.6371" + style="font-size:18.6667px">MPC</tspan></text> + <text + xml:space="preserve" + style="font-style:normal;font-weight:normal;font-size:18.6667px;line-height:1.25;font-family:sans-serif;fill:#000000;fill-opacity:1;stroke:none" + x="330.14737" + y="114.41869" + id="text64469-9-9"><tspan + sodipodi:role="line" + id="tspan64467-2-7" + x="330.14737" + y="114.41869" + style="font-size:18.6667px">DPP</tspan></text> + <path + d="m 1488.3608,401.47792 c 0.025,10.97895 0.01,773.03788 0.049,784.01888 2.5462,-1.1592 5.0637,-2.3779 7.6202,-3.5187 -2.7411,4.8298 -5.4987,9.6453 -8.2624,14.4607 -2.7925,-4.8257 -5.5993,-9.6453 -8.3856,-14.4751 2.6221,1.1736 5.2217,2.3923 7.8398,3.5721 0,-10.8825 -0.035,-772.84093 -0.031,-783.72345 0.053,-0.30366 -0.2175,-0.50268 -0.3652,-0.72837 l 1.5347,0.39394 z" + id="path106" + sodipodi:nodetypes="cccccccccc" + style="stroke-width:0.205176" + inkscape:transform-center-x="-325.50819" + inkscape:transform-center-y="-121.97185" /> + <text + xml:space="preserve" + style="font-style:normal;font-weight:normal;font-size:18.6667px;line-height:1.25;font-family:sans-serif;fill:#000000;fill-opacity:1;stroke:none" + x="1495.9988" + y="1224.7498" + id="text78849"><tspan + sodipodi:role="line" + id="tspan78847" + x="1495.9988" + y="1224.7498" + style="font-size:18.6667px">Blender</tspan></text> + <text + xml:space="preserve" + style="font-style:normal;font-weight:normal;font-size:18.6667px;line-height:1.25;font-family:sans-serif;fill:#000000;fill-opacity:1;stroke:none" + x="1417.9988" + y="1294.7498" + id="text78853"><tspan + sodipodi:role="line" + id="tspan78851" + x="1417.9988" + y="1294.7498" + style="font-size:18.6667px">Degamma</tspan></text> + <text + xml:space="preserve" + style="font-style:normal;font-weight:normal;font-size:18.6667px;line-height:1.25;font-family:sans-serif;fill:#000000;fill-opacity:1;stroke:none" + x="1451.9988" + y="1376.7498" + id="text78857"><tspan + sodipodi:role="line" + id="tspan78855" + x="1451.9988" + y="1376.7498" + style="font-size:18.6667px">CTM</tspan></text> + <text + xml:space="preserve" + style="font-style:normal;font-weight:normal;font-size:18.6667px;line-height:1.25;font-family:sans-serif;fill:#000000;fill-opacity:1;stroke:none" + x="1427.9988" + y="1458.7498" + id="text78861"><tspan + sodipodi:role="line" + id="tspan78859" + x="1427.9988" + y="1458.7498" + style="font-size:18.6667px">Gamma</tspan></text> + <text + xml:space="preserve" + style="font-style:normal;font-weight:normal;font-size:18.6667px;line-height:1.25;font-family:sans-serif;fill:#000000;fill-opacity:1;stroke:none" + x="949.99878" + y="218.74973" + id="text104653"><tspan + sodipodi:role="line" + id="tspan104651" + x="949.99878" + y="218.74973" + style="font-size:18.6667px">format</tspan></text> + <text + xml:space="preserve" + style="font-style:normal;font-weight:normal;font-size:18.6667px;line-height:1.25;font-family:sans-serif;fill:#000000;fill-opacity:1;stroke:none" + x="911.99878" + y="284.74973" + id="text104657"><tspan + sodipodi:role="line" + id="tspan104655" + x="911.99878" + y="284.74973" + style="font-size:18.6667px">bias_and_scale</tspan></text> + <text + xml:space="preserve" + style="font-style:normal;font-weight:normal;font-size:18.6667px;line-height:1.25;font-family:sans-serif;fill:#000000;fill-opacity:1;stroke:none" + x="887.99878" + y="346.74973" + id="text104661"><tspan + sodipodi:role="line" + id="tspan104659" + x="887.99878" + y="346.74973" + style="font-size:18.6667px">color space matrix</tspan></text> + <text + xml:space="preserve" + style="font-style:normal;font-weight:normal;font-size:18.6667px;line-height:1.25;font-family:sans-serif;fill:#000000;fill-opacity:1;stroke:none" + x="871.99878" + y="442.74973" + id="text104665"><tspan + sodipodi:role="line" + id="tspan104663" + x="871.99878" + y="442.74973" + style="font-size:18.6667px">input_csc_color_matrix</tspan></text> + <text + xml:space="preserve" + style="font-style:normal;font-weight:normal;font-size:18.6667px;line-height:1.25;font-family:sans-serif;fill:#000000;fill-opacity:1;stroke:none" + x="905.99878" + y="586.74976" + id="text125075"><tspan + sodipodi:role="line" + id="tspan125073" + x="905.99878" + y="586.74976" + style="font-size:18.6667px">in_transfer_func</tspan></text> + <text + xml:space="preserve" + style="font-style:normal;font-weight:normal;font-size:18.6667px;line-height:1.25;font-family:sans-serif;fill:#000000;fill-opacity:1;stroke:none" + x="945.0083" + y="702.85938" + id="text117309"><tspan + sodipodi:role="line" + id="tspan117307" + x="945.0083" + y="702.85938" + style="font-size:18.6667px">hdr_mult</tspan></text> + <text + xml:space="preserve" + style="font-style:normal;font-weight:normal;font-size:18.6667px;line-height:1.25;font-family:sans-serif;fill:#000000;fill-opacity:1;stroke:none" + x="874.5556" + y="773.42615" + id="text117309-6"><tspan + sodipodi:role="line" + id="tspan117307-7" + x="874.5556" + y="773.42615" + style="font-size:18.6667px">gamut_remap_matrix</tspan></text> + <text + xml:space="preserve" + style="font-style:normal;font-weight:normal;font-size:18.6667px;line-height:1.25;font-family:sans-serif;fill:#000000;fill-opacity:1;stroke:none" + x="913.72528" + y="846.55896" + id="text117309-5"><tspan + sodipodi:role="line" + id="tspan117307-3" + x="913.72528" + y="846.55896" + style="font-size:18.6667px">in_shaper_func</tspan></text> + <text + xml:space="preserve" + style="font-style:normal;font-weight:normal;font-size:18.6667px;line-height:1.25;font-family:sans-serif;fill:#000000;fill-opacity:1;stroke:none" + x="937.72528" + y="918.25787" + id="text117309-56"><tspan + sodipodi:role="line" + id="tspan117307-2" + x="937.72528" + y="918.25787" + style="font-size:18.6667px">lut3d_func</tspan></text> + <text + xml:space="preserve" + style="font-style:normal;font-weight:normal;font-size:18.6667px;line-height:1.25;font-family:sans-serif;fill:#000000;fill-opacity:1;stroke:none" + x="945.9895" + y="986.10767" + id="text117309-9"><tspan + sodipodi:role="line" + id="tspan117307-1" + x="945.9895" + y="986.10767" + style="font-size:18.6667px">blend_tf</tspan></text> + <text + xml:space="preserve" + style="font-style:normal;font-weight:normal;font-size:18.6667px;line-height:1.25;font-family:sans-serif;fill:#000000;fill-opacity:1;stroke:none" + x="975.91803" + y="1224.5564" + id="text137434"><tspan + sodipodi:role="line" + id="tspan137432" + x="975.91803" + y="1224.5564" + style="font-size:18.6667px">Blender</tspan></text> + <text + xml:space="preserve" + style="font-style:normal;font-weight:normal;font-size:18.6667px;line-height:1.25;font-family:sans-serif;fill:#000000;fill-opacity:1;stroke:none" + x="879.31372" + y="1283.4249" + id="text137434-2"><tspan + sodipodi:role="line" + id="tspan137432-7" + x="879.31372" + y="1283.4249" + style="font-size:18.6667px">gamut_remap_matrix</tspan></text> + <text + xml:space="preserve" + style="font-style:normal;font-weight:normal;font-size:18.6667px;line-height:1.25;font-family:sans-serif;fill:#000000;fill-opacity:1;stroke:none" + x="925.31372" + y="1359.2747" + id="text137434-0"><tspan + sodipodi:role="line" + id="tspan137432-9" + x="925.31372" + y="1359.2747" + style="font-size:18.6667px">func_shaper</tspan></text> + <text + xml:space="preserve" + style="font-style:normal;font-weight:normal;font-size:18.6667px;line-height:1.25;font-family:sans-serif;fill:#000000;fill-opacity:1;stroke:none" + x="930.33252" + y="1430.2566" + id="text137434-3"><tspan + sodipodi:role="line" + id="tspan137432-6" + x="930.33252" + y="1430.2566" + style="font-size:18.6667px">lut3d_func</tspan></text> + <text + xml:space="preserve" + style="font-style:normal;font-weight:normal;font-size:18.6667px;line-height:1.25;font-family:sans-serif;fill:#000000;fill-opacity:1;stroke:none" + x="900.18158" + y="1504.6725" + id="text137434-06"><tspan + sodipodi:role="line" + id="tspan137432-2" + x="900.18158" + y="1504.6725" + style="font-size:18.6667px">out_transfer_func</tspan></text> + <text + xml:space="preserve" + style="font-style:normal;font-weight:normal;font-size:18.6667px;line-height:1.25;font-family:sans-serif;fill:#000000;fill-opacity:1;stroke:none" + x="904.0307" + y="1575.8053" + id="text137434-6"><tspan + sodipodi:role="line" + id="tspan137432-1" + x="904.0307" + y="1575.8053" + style="font-size:18.6667px">csc_color_matrix</tspan></text> + <text + xml:space="preserve" + style="font-style:normal;font-weight:normal;font-size:18.6667px;line-height:1.25;font-family:sans-serif;fill:#000000;fill-opacity:1;stroke:none" + x="903.16278" + y="1642.1078" + id="text137434-8"><tspan + sodipodi:role="line" + id="tspan137432-79" + x="903.16278" + y="1642.1078" + style="font-size:18.6667px">bit_depth_param</tspan></text> + <text + xml:space="preserve" + style="font-style:normal;font-weight:normal;font-size:18.6667px;line-height:1.25;font-family:sans-serif;fill:#000000;fill-opacity:1;stroke:none" + x="939.31372" + y="1713.8068" + id="text137434-20"><tspan + sodipodi:role="line" + id="tspan137432-23" + x="939.31372" + y="1713.8068" + style="font-size:18.6667px">clamping</tspan></text> + <text + xml:space="preserve" + style="font-style:normal;font-weight:normal;font-size:18.6667px;line-height:1.25;font-family:sans-serif;fill:#000000;fill-opacity:1;stroke:none" + x="894.0307" + y="1782.5244" + id="text137434-7"><tspan + sodipodi:role="line" + id="tspan137432-5" + x="894.0307" + y="1782.5244" + style="font-size:18.6667px">output_color_space</tspan></text> + <text + xml:space="preserve" + style="font-style:normal;font-weight:normal;font-size:18.6667px;line-height:1.25;font-family:sans-serif;fill:#000000;fill-opacity:1;stroke:none" + x="869.63062" + y="117.7968" + id="text176429"><tspan + sodipodi:role="line" + id="tspan176427" + x="869.63062" + y="117.7968" + style="font-size:18.6667px">Plane</tspan></text> + <text + xml:space="preserve" + style="font-style:normal;font-weight:normal;font-size:18.6667px;line-height:1.25;font-family:sans-serif;fill:#000000;fill-opacity:1;stroke:none" + x="27.605465" + y="162.20587" + id="text176429-2"><tspan + sodipodi:role="line" + id="tspan176427-0" + x="27.605465" + y="162.20587" + style="font-size:18.6667px">Legend</tspan></text> + <text + xml:space="preserve" + style="font-style:normal;font-weight:normal;font-size:18.6667px;line-height:1.25;font-family:sans-serif;fill:#000000;fill-opacity:1;stroke:none" + x="298.63959" + y="59.293999" + id="text176429-9"><tspan + sodipodi:role="line" + id="tspan176427-2" + x="298.63959" + y="59.293999" + style="font-size:18.6667px">DCN 2.0</tspan></text> + <text + xml:space="preserve" + style="font-style:normal;font-weight:normal;font-size:18.6667px;line-height:1.25;font-family:sans-serif;fill:#000000;fill-opacity:1;stroke:none" + x="826.65735" + y="59.458061" + id="text176429-66"><tspan + sodipodi:role="line" + id="tspan176427-4" + x="826.65735" + y="59.458061" + style="font-size:18.6667px">DC Interface</tspan></text> + <text + xml:space="preserve" + style="font-style:normal;font-weight:normal;font-size:18.6667px;line-height:1.25;font-family:sans-serif;fill:#000000;fill-opacity:1;stroke:none" + x="1362.9948" + y="59.458061" + id="text176429-95"><tspan + sodipodi:role="line" + id="tspan176427-04" + x="1362.9948" + y="59.458061" + style="font-size:18.6667px">DRM Interface</tspan></text> + <text + xml:space="preserve" + style="font-style:normal;font-weight:normal;font-size:40px;line-height:1.25;font-family:sans-serif;fill:#000000;fill-opacity:1;stroke:none" + x="867.34656" + y="1194.5068" + id="text184728"><tspan + sodipodi:role="line" + id="tspan184726" + x="867.34656" + y="1194.5068" /></text> + <text + xml:space="preserve" + style="font-style:normal;font-weight:normal;font-size:18.6667px;line-height:1.25;font-family:sans-serif;fill:#000000;fill-opacity:1;stroke:none" + x="389.01593" + y="159.8909" + id="text64469-9-3"><tspan + sodipodi:role="line" + id="tspan64467-2-6" + x="389.01593" + y="159.8909" + style="font-size:18.6667px">CNVC</tspan></text> + <text + xml:space="preserve" + style="font-style:normal;font-weight:normal;font-size:18.6667px;line-height:1.25;font-family:sans-serif;fill:#000000;fill-opacity:1;stroke:none" + x="365.88379" + y="303.59048" + id="text64469-9-1"><tspan + sodipodi:role="line" + id="tspan64467-2-2" + x="365.88379" + y="303.59048" + style="font-size:18.6667px">Input CSC</tspan></text> + <text + xml:space="preserve" + style="font-style:normal;font-weight:normal;font-size:18.6667px;line-height:1.25;font-family:sans-serif;fill:#000000;fill-opacity:1;stroke:none" + x="409.06488" + y="404.95001" + id="text64469-9-93"><tspan + sodipodi:role="line" + id="tspan64467-2-1" + x="409.06488" + y="404.95001" + style="font-size:18.6667px;text-align:center;text-anchor:middle">DeGamma</tspan><tspan + sodipodi:role="line" + x="409.06488" + y="428.28339" + style="font-size:18.6667px;text-align:center;text-anchor:middle" + id="tspan233797">RAM and ROM</tspan><tspan + sodipodi:role="line" + x="409.06488" + y="451.61676" + style="font-size:10.6667px;text-align:center;text-anchor:middle" + id="tspan242597">(sRGB, BT2020</tspan></text> + <text + xml:space="preserve" + style="font-style:normal;font-weight:normal;font-size:18.6667px;line-height:1.25;font-family:sans-serif;fill:#000000;fill-opacity:1;stroke:none" + x="351.16684" + y="700.34918" + id="text64469-9-0"><tspan + sodipodi:role="line" + id="tspan64467-2-3" + x="351.16684" + y="700.34918" + style="font-size:18.6667px">HDR Multiply</tspan></text> + <text + xml:space="preserve" + style="font-style:normal;font-weight:normal;font-size:18.6667px;line-height:1.25;font-family:sans-serif;fill:#000000;fill-opacity:1;stroke:none" + x="345.16684" + y="771.33112" + id="text64469-9-6"><tspan + sodipodi:role="line" + id="tspan64467-2-10" + x="345.16684" + y="771.33112" + style="font-size:18.6667px">Gamut Remap</tspan></text> + <text + xml:space="preserve" + style="font-style:normal;font-weight:normal;font-size:18.6667px;line-height:1.25;font-family:sans-serif;fill:#000000;fill-opacity:1;stroke:none" + x="412.5184" + y="836.04877" + id="text64469-9-63"><tspan + sodipodi:role="line" + id="tspan64467-2-20" + x="412.5184" + y="836.04877" + style="font-size:18.6667px;text-align:center;text-anchor:middle">Shaper LUT</tspan><tspan + sodipodi:role="line" + x="412.5184" + y="859.38214" + style="font-size:18.6667px;text-align:center;text-anchor:middle" + id="tspan222533">RAM</tspan></text> + <text + xml:space="preserve" + style="font-style:normal;font-weight:normal;font-size:18.6667px;line-height:1.25;font-family:sans-serif;fill:#000000;fill-opacity:1;stroke:none" + x="413.54086" + y="908.61554" + id="text64469-9-61"><tspan + sodipodi:role="line" + id="tspan64467-2-55" + x="413.54086" + y="908.61554" + style="font-size:18.6667px;text-align:center;text-anchor:middle">3D LUT</tspan><tspan + sodipodi:role="line" + x="413.54086" + y="931.94891" + style="font-size:18.6667px;text-align:center;text-anchor:middle" + id="tspan221121">RAM</tspan></text> + <text + xml:space="preserve" + style="font-style:normal;font-weight:normal;font-size:18.6667px;line-height:1.25;font-family:sans-serif;fill:#000000;fill-opacity:1;stroke:none" + x="344.0347" + y="985.33319" + id="text64469-9-47"><tspan + sodipodi:role="line" + id="tspan64467-2-65" + x="344.0347" + y="985.33319" + style="font-size:18.6667px">Blend Gamma</tspan></text> + <text + xml:space="preserve" + style="font-style:normal;font-weight:normal;font-size:18.6667px;line-height:1.25;font-family:sans-serif;fill:#000000;fill-opacity:1;stroke:none" + x="433.84625" + y="1223.411" + id="text64469-9-69"><tspan + sodipodi:role="line" + id="tspan64467-2-37" + x="433.84625" + y="1223.411" + style="font-size:18.6667px">Blender</tspan></text> + <text + xml:space="preserve" + style="font-style:normal;font-weight:normal;font-size:18.6667px;line-height:1.25;font-family:sans-serif;fill:#000000;fill-opacity:1;stroke:none" + x="408.64996" + y="1492.8102" + id="text64469-9-8"><tspan + sodipodi:role="line" + id="tspan64467-2-84" + x="408.64996" + y="1492.8102" + style="font-size:18.6667px;text-align:center;text-anchor:middle">Gamma</tspan><tspan + sodipodi:role="line" + x="408.64996" + y="1516.1436" + style="font-size:18.6667px;text-align:center;text-anchor:middle" + id="tspan197733">RAM</tspan></text> + <text + xml:space="preserve" + style="font-style:normal;font-weight:normal;font-size:18.6667px;line-height:1.25;font-family:sans-serif;fill:#000000;fill-opacity:1;stroke:none" + x="385.46863" + y="1575.2261" + id="text64469-9-31"><tspan + sodipodi:role="line" + id="tspan64467-2-49" + x="385.46863" + y="1575.2261" + style="font-size:18.6667px">OCSC</tspan></text> + <text + xml:space="preserve" + style="font-style:normal;font-weight:normal;font-size:40px;line-height:1.25;font-family:sans-serif;fill:#000000;fill-opacity:1;stroke:none" + x="1356.5106" + y="53.140579" + id="text273287"><tspan + sodipodi:role="line" + id="tspan273285" + x="1356.5106" + y="53.140579" /></text> + <rect + style="fill:#f9f7ed;fill-opacity:1;stroke:#000000;stroke-opacity:1" + id="rect1411" + width="177.28049" + height="38.940468" + x="1392.2576" + y="459.24118" /> + <text + xml:space="preserve" + style="font-style:normal;font-weight:normal;font-size:18.6667px;line-height:1.25;font-family:sans-serif;fill:#000000;fill-opacity:1;stroke:none" + x="1411.7203" + y="485.93231" + id="text78841"><tspan + sodipodi:role="line" + id="tspan78839" + x="1411.7203" + y="485.93231" + style="font-size:18.6667px">color_encoding</tspan></text> + <rect + style="fill:#f9f7ed;fill-opacity:1;stroke:#000000;stroke-opacity:1" + id="rect1515" + width="175.11876" + height="43.239407" + x="1393.7493" + y="525.6983" /> + <text + xml:space="preserve" + style="font-style:normal;font-weight:normal;font-size:17.3333px;line-height:1.25;font-family:sans-serif;fill:#000000;fill-opacity:1;stroke:none" + x="1399.212" + y="553.44904" + id="text78845"><tspan + sodipodi:role="line" + id="tspan78843" + x="1399.212" + y="553.44904">pixel_blend_mode</tspan></text> + <rect + style="fill:#f9f7ed;fill-opacity:1;stroke:#000000;stroke-opacity:1" + id="rect371322" + width="177.28049" + height="38.940468" + x="1391.6781" + y="385.61713" /> + <text + xml:space="preserve" + style="font-style:normal;font-weight:normal;font-size:18.6667px;line-height:1.25;font-family:sans-serif;fill:#000000;fill-opacity:1;stroke:none" + x="1427.5771" + y="409.29523" + id="text78837"><tspan + sodipodi:role="line" + id="tspan78835" + x="1427.5771" + y="409.29523" + style="font-size:18.6667px">color_range</tspan></text> + <path + d="m 1469.6815,1334.9145 c 3.2597,-1.4841 6.4827,-3.0444 9.7556,-4.5049 -3.5093,6.1834 -7.0396,12.3483 -10.5778,18.5131 -3.575,-6.178 -7.1683,-12.3481 -10.7354,-18.5314 3.3569,1.5025 6.685,3.0627 10.0367,4.5731 0,0 0,0 1.5209,-0.05 z" + id="path371636-7" + sodipodi:nodetypes="cccccc" + style="stroke-width:0.262672" + inkscape:transform-center-x="-416.72543" + inkscape:transform-center-y="-156.15191" /> + <path + d="m 1467.8882,1256.0056 c 3.2597,-1.4841 6.4827,-3.0443 9.7556,-4.5048 -3.5093,6.1833 -7.0396,12.3482 -10.5778,18.5131 -3.575,-6.178 -7.1683,-12.3482 -10.7354,-18.5315 3.3569,1.5025 6.685,3.0628 10.0367,4.5731 0,0 0,0 1.5209,-0.05 z" + id="path371636-7-2" + sodipodi:nodetypes="cccccc" + style="stroke-width:0.262672" + inkscape:transform-center-x="-416.72543" + inkscape:transform-center-y="-156.15191" /> + <path + d="m 1487.6154,441.80981 c 3.2597,-1.48411 6.4827,-3.04435 9.7556,-4.50482 -3.5093,6.18331 -7.0396,12.34823 -10.5778,18.51307 -3.575,-6.17798 -7.1683,-12.34815 -10.7354,-18.53146 3.3569,1.50251 6.685,3.06275 10.0367,4.57314 0,0 0,0 1.5209,-0.0499 z" + id="path371636-7-7" + sodipodi:nodetypes="cccccc" + style="stroke-width:0.262672" + inkscape:transform-center-x="-416.72543" + inkscape:transform-center-y="-156.15191" /> + <path + d="m 1489.4088,515.3385 c 3.2597,-1.48411 6.4827,-3.04435 9.7556,-4.50482 -3.5093,6.18331 -7.0396,12.34823 -10.5778,18.51307 -3.575,-6.17798 -7.1683,-12.34815 -10.7354,-18.53146 3.3569,1.50251 6.685,3.06275 10.0367,4.57314 0,0 0,0 1.5209,-0.0499 z" + id="path371636-7-22" + sodipodi:nodetypes="cccccc" + style="stroke-width:0.262672" + inkscape:transform-center-x="-416.72543" + inkscape:transform-center-y="-156.15191" /> + <path + d="m 400.8254,264.26491 c 3.2597,-1.48411 6.4827,-3.04435 9.7556,-4.50482 -3.5093,6.18331 -7.0396,12.34823 -10.5778,18.51307 -3.575,-6.17798 -7.1683,-12.34815 -10.7354,-18.53146 3.3569,1.50251 6.685,3.06275 10.0367,4.57314 0,0 0,0 1.5209,-0.0499 z" + id="path371636-7-6" + sodipodi:nodetypes="cccccc" + style="stroke-width:0.262672" + inkscape:transform-center-x="-416.72543" + inkscape:transform-center-y="-156.15191" /> + <path + d="m 402.6188,346.76052 c 3.2597,-1.48411 6.4827,-3.04435 9.7556,-4.50482 -3.5093,6.18331 -7.0396,12.34823 -10.5778,18.51307 -3.575,-6.17798 -7.1683,-12.34815 -10.7354,-18.53146 3.3569,1.50251 6.685,3.06275 10.0367,4.57314 0,0 0,0 1.5209,-0.0499 z" + id="path371636-7-1" + sodipodi:nodetypes="cccccc" + style="stroke-width:0.262672" + inkscape:transform-center-x="-416.72543" + inkscape:transform-center-y="-156.15191" /> + <path + d="m 402.6188,658.80913 c 3.2597,-1.48411 6.4827,-3.04435 9.7556,-4.50482 -3.5093,6.18331 -7.0396,12.34823 -10.5778,18.51307 -3.575,-6.17798 -7.1683,-12.34815 -10.7354,-18.53146 3.3569,1.50251 6.685,3.06275 10.0367,4.57314 0,0 0,0 1.5209,-0.0499 z" + id="path371636-7-5" + sodipodi:nodetypes="cccccc" + style="stroke-width:0.262672" + inkscape:transform-center-x="-416.72543" + inkscape:transform-center-y="-156.15191" /> + <path + d="m 402.6188,732.33782 c 3.2597,-1.48411 6.4827,-3.04435 9.7556,-4.50482 -3.5093,6.18331 -7.0396,12.34823 -10.5778,18.51307 -3.575,-6.17798 -7.1683,-12.34815 -10.7354,-18.53146 3.3569,1.50251 6.685,3.06275 10.0367,4.57314 0,0 0,0 1.5209,-0.0499 z" + id="path371636-7-9" + sodipodi:nodetypes="cccccc" + style="stroke-width:0.262672" + inkscape:transform-center-x="-416.72543" + inkscape:transform-center-y="-156.15191" /> + <path + d="m 402.4121,800.48637 c 3.2597,-1.48411 6.4827,-3.04435 9.7556,-4.50482 -3.5093,6.18331 -7.0396,12.34823 -10.5778,18.51307 -3.575,-6.17798 -7.1683,-12.34815 -10.7354,-18.53146 3.3569,1.50251 6.685,3.06275 10.0367,4.57314 0,0 0,0 1.5209,-0.0499 z" + id="path371636-7-4" + sodipodi:nodetypes="cccccc" + style="stroke-width:0.262672" + inkscape:transform-center-x="-416.72543" + inkscape:transform-center-y="-156.15191" /> + <path + d="m 402.2055,875.80845 c 3.2597,-1.48411 6.4827,-3.04435 9.7556,-4.50482 -3.5093,6.18331 -7.0396,12.34823 -10.5778,18.51307 -3.575,-6.17798 -7.1683,-12.34815 -10.7354,-18.53146 3.3569,1.50251 6.685,3.06275 10.0367,4.57314 0,0 0,0 1.5209,-0.0499 z" + id="path371636-7-90" + sodipodi:nodetypes="cccccc" + style="stroke-width:0.262672" + inkscape:transform-center-x="-416.72543" + inkscape:transform-center-y="-156.15191" /> + <path + d="m 400.4121,942.16362 c 3.2597,-1.48411 6.4827,-3.04435 9.7556,-4.50482 -3.5093,6.18331 -7.0396,12.34823 -10.5778,18.51307 -3.575,-6.17798 -7.1683,-12.34815 -10.7354,-18.53146 3.3569,1.50251 6.685,3.06275 10.0367,4.57314 0,0 0,0 1.5209,-0.0499 z" + id="path371636-7-91" + sodipodi:nodetypes="cccccc" + style="stroke-width:0.262672" + inkscape:transform-center-x="-416.72543" + inkscape:transform-center-y="-156.15191" /> + <path + d="m 407.9989,1458.6579 c 3.2597,-1.4841 6.4827,-3.0444 9.7556,-4.5049 -3.5093,6.1834 -7.0396,12.3483 -10.5778,18.5131 -3.575,-6.178 -7.1683,-12.3481 -10.7354,-18.5314 3.3569,1.5025 6.685,3.0627 10.0367,4.5731 0,0 0,0 1.5209,-0.05 z" + id="path371636-7-59" + sodipodi:nodetypes="cccccc" + style="stroke-width:0.262672" + inkscape:transform-center-x="-416.72543" + inkscape:transform-center-y="-156.15191" /> + </g> +</svg> diff --git a/Documentation/gpu/amdgpu/display/dcn3_cm_drm_current.svg b/Documentation/gpu/amdgpu/display/dcn3_cm_drm_current.svg new file mode 100644 index 000000000000..7299ee9b6d64 --- /dev/null +++ b/Documentation/gpu/amdgpu/display/dcn3_cm_drm_current.svg @@ -0,0 +1,1529 @@ +<?xml version="1.0" encoding="UTF-8" standalone="no"?> +<!-- Created with Inkscape (http://www.inkscape.org/) --> + +<svg + version="1.1" + id="svg2019" + width="1702" + height="1845" + viewBox="0 0 1702 1845" + sodipodi:docname="dcn3_cm_drm_current.svg" + inkscape:version="1.1.2 (0a00cf5339, 2022-02-04)" + xmlns:inkscape="http://www.inkscape.org/namespaces/inkscape" + xmlns:sodipodi="http://sodipodi.sourceforge.net/DTD/sodipodi-0.dtd" + xmlns="http://www.w3.org/2000/svg" + xmlns:svg="http://www.w3.org/2000/svg"> + <defs + id="defs2023" /> + <sodipodi:namedview + id="namedview2021" + pagecolor="#ffffff" + bordercolor="#666666" + borderopacity="1.0" + inkscape:pageshadow="2" + inkscape:pageopacity="0.0" + inkscape:pagecheckerboard="0" + showgrid="false" + inkscape:zoom="0.55760543" + inkscape:cx="1011.4679" + inkscape:cy="249.28021" + inkscape:window-width="1920" + inkscape:window-height="1011" + inkscape:window-x="0" + inkscape:window-y="0" + inkscape:window-maximized="1" + inkscape:current-layer="g2025" /> + <g + inkscape:groupmode="layer" + inkscape:label="Image" + id="g2025"> + <rect + style="fill:#000000;fill-opacity:0;stroke:#000000;stroke-opacity:1" + id="rect34" + width="208.83351" + height="486.09872" + x="0.90158081" + y="132.77872" /> + <rect + style="fill:#fad7ac;fill-opacity:1;stroke:#000000;stroke-opacity:1" + id="rect1019" + width="126.38867" + height="55.320732" + x="25.960823" + y="188.06937" /> + <rect + style="fill:#d0cee2;fill-opacity:1;stroke:#000000;stroke-opacity:1" + id="rect1021" + width="126.38867" + height="55.320732" + x="25.960823" + y="346.06937" /> + <rect + style="fill:#afdde9;fill-opacity:1;stroke:#000000;stroke-opacity:1" + id="rect1103" + width="126.38867" + height="55.320732" + x="25.960823" + y="266.06937" /> + <rect + style="fill:#f9f7ed;fill-opacity:1;stroke:#000000;stroke-opacity:1" + id="rect1105" + width="126.38867" + height="55.320732" + x="25.960823" + y="426.06937" /> + <rect + style="fill:#e6e6e6;fill-opacity:1;stroke:#000000;stroke-opacity:1" + id="rect1107" + width="126.38867" + height="55.320732" + x="25.960823" + y="506.06934" /> + <path + d="m 402.61883,171.88069 c 0.025,10.97895 0.01,1001.03791 0.049,1012.01891 2.5462,-1.1592 5.0637,-2.3779 7.6202,-3.5187 -2.7411,4.8298 -5.4987,9.6453 -8.2624,14.4607 -2.7925,-4.8257 -5.5993,-9.6453 -8.3856,-14.4751 2.6221,1.1736 5.2217,2.3923 7.8398,3.5721 0,-10.8825 -0.035,-1000.84096 -0.031,-1011.72348 0.053,-0.30366 -0.2175,-0.50268 -0.3652,-0.72837 l 1.5347,0.39394 z" + id="path381056" + sodipodi:nodetypes="cccccccccc" + style="stroke-width:0.205176" + inkscape:transform-center-x="-325.50819" + inkscape:transform-center-y="-121.97185" /> + <rect + style="fill:#000000;fill-opacity:0;stroke:#000000;stroke-opacity:1" + id="rect1131" + width="239.47592" + height="1015.9909" + x="298.65631" + y="82.399658" /> + <rect + style="fill:#000000;fill-opacity:0;stroke:#000000;stroke-width:1.27861;stroke-opacity:1" + id="rect1133" + width="340.44653" + height="525.77448" + x="298.79562" + y="1142.5299" /> + <rect + style="fill:#000000;fill-opacity:0;stroke:#000000;stroke-opacity:1" + id="rect1237" + width="284.00113" + height="945.41412" + x="827.75012" + y="82.880798" + inkscape:connector-avoid="true" /> + <rect + style="fill:#000000;fill-opacity:0;stroke:#000000;stroke-opacity:1" + id="rect1239" + width="239.37569" + height="179.03308" + x="1356.9507" + y="98.758331" /> + <rect + style="fill:#000000;fill-opacity:0;stroke:#000000;stroke-width:1.00744;stroke-opacity:1" + id="rect1241" + width="239.4184" + height="713.64905" + x="1356.9543" + y="307.7951" + inkscape:connector-avoid="true" /> + <rect + style="fill:#000000;fill-opacity:0;stroke:#000000;stroke-opacity:1" + id="rect1345" + width="330.32059" + height="409.44757" + x="1363.8723" + y="1147.7572" /> + <rect + style="fill:#000000;fill-opacity:0;stroke:#000000;stroke-opacity:1" + id="rect1347" + width="369.8941" + height="682.32245" + x="825.72528" + y="1146.6448" + inkscape:connector-avoid="true" /> + <rect + style="fill:#f9f7ed;fill-opacity:1;stroke:#000000;stroke-opacity:1" + id="rect1349" + width="163.95746" + height="40.144867" + x="1389.9988" + y="190.80583" /> + <rect + style="fill:#000000;fill-opacity:0;stroke:#000000;stroke-width:0.964132;stroke-opacity:1" + id="rect1619" + width="271.99091" + height="42.038273" + x="1393.981" + y="1197.161" + inkscape:connector-avoid="true" /> + <path + d="m 1469.3028,1238.8328 c 0.025,10.9789 0.01,175.0378 0.049,186.0188 2.5462,-1.1592 5.0637,-2.3779 7.6202,-3.5187 -2.7411,4.8298 -5.4987,9.6453 -8.2624,14.4607 -2.7925,-4.8257 -5.5993,-9.6453 -8.3856,-14.4751 2.6221,1.1736 5.2217,2.3923 7.8398,3.5721 0,-10.8825 -0.035,-174.8409 -0.031,-185.7234 0.053,-0.3037 -0.2175,-0.5027 -0.3652,-0.7284 l 1.5347,0.394 z" + id="path106-1" + sodipodi:nodetypes="cccccccccc" + style="stroke-width:0.205176" + inkscape:transform-center-x="-325.50819" + inkscape:transform-center-y="-121.97185" /> + <path + d="m 407.4759,1238.4728 c 0.025,10.9789 0.01,291.0378 0.049,302.0188 2.5462,-1.1592 5.0637,-2.3779 7.6202,-3.5187 -2.7411,4.8298 -5.4987,9.6453 -8.2624,14.4607 -2.7925,-4.8257 -5.5993,-9.6453 -8.3856,-14.4751 2.6221,1.1736 5.2217,2.3923 7.8398,3.5721 0,-10.8825 -0.035,-290.8409 -0.031,-301.7234 0.053,-0.3037 -0.2175,-0.5027 -0.3652,-0.7284 l 1.5347,0.394 z" + id="path106-1-7" + sodipodi:nodetypes="cccccccccc" + style="stroke-width:0.205176" + inkscape:transform-center-x="-325.50819" + inkscape:transform-center-y="-121.97185" /> + <rect + style="fill:#afdde9;fill-opacity:1;stroke:#000000;stroke-opacity:1" + id="rect1623" + width="137.32646" + height="41.782684" + x="1396.3848" + y="1268.2837" + inkscape:connector-avoid="true" /> + <rect + style="fill:#fad7ac;fill-opacity:1;stroke:#000000;stroke-opacity:1" + id="rect1705" + width="137.32646" + height="41.782684" + x="1396.3848" + y="1348.2837" /> + <rect + style="fill:#afdde9;fill-opacity:1;stroke:#000000;stroke-opacity:1" + id="rect1707" + width="137.32646" + height="41.782684" + x="1396.3848" + y="1432.2837" /> + <rect + style="fill:#f9f7ed;fill-opacity:1;stroke:#000000;stroke-opacity:1" + id="rect1731" + width="222.34483" + height="44.64616" + x="867.36292" + y="190.42665" + inkscape:connector-avoid="true" /> + <rect + style="fill:#f9f7ed;fill-opacity:1;stroke:#000000;stroke-opacity:1" + id="rect1813" + width="222.34483" + height="44.64616" + x="867.36292" + y="254.42664" + inkscape:connector-avoid="true" /> + <rect + style="fill:#f9f7ed;fill-opacity:1;stroke:#000000;stroke-opacity:1" + id="rect1815" + width="222.34483" + height="44.64616" + x="867.36292" + y="318.42664" + inkscape:connector-avoid="true" /> + <rect + style="fill:#fad7ac;fill-opacity:1;stroke:#000000;stroke-opacity:1" + id="rect1817" + width="222.34483" + height="44.64616" + x="867.36292" + y="412.42664" + inkscape:connector-avoid="true" /> + <rect + style="fill:#afdde9;fill-opacity:1;stroke:#000000;stroke-opacity:1" + id="rect1819" + width="222.34483" + height="44.64616" + x="867.36292" + y="560.42664" /> + <rect + style="fill:#e6e6e6;fill-opacity:1;stroke:#000000;stroke-opacity:1" + id="rect1821" + width="222.34483" + height="44.64616" + x="867.36292" + y="674.42664" + inkscape:connector-avoid="true" /> + <rect + style="fill:#fad7ac;fill-opacity:1;stroke:#000000;stroke-opacity:1" + id="rect1823" + width="222.34483" + height="44.64616" + x="867.36292" + y="744.42664" + inkscape:connector-avoid="true" /> + <rect + style="fill:#afdde9;fill-opacity:1;stroke:#000000;stroke-opacity:1" + id="rect1825" + width="222.34483" + height="44.64616" + x="867.36292" + y="820.42664" + inkscape:connector-avoid="true" /> + <rect + style="fill:#d0cee2;fill-opacity:1;stroke:#000000;stroke-opacity:1" + id="rect1827" + width="222.34483" + height="44.64616" + x="867.36292" + y="890.42664" + inkscape:connector-avoid="true" /> + <rect + style="fill:#afdde9;fill-opacity:1;stroke:#000000;stroke-opacity:1" + id="rect1829" + width="222.34483" + height="44.64616" + x="867.36292" + y="956.42664" + inkscape:connector-avoid="true" /> + <rect + style="fill:#fad7ac;fill-opacity:1;stroke:#000000;stroke-opacity:1" + id="rect1831" + width="222.34483" + height="44.64616" + x="867.36292" + y="1256.4268" /> + <rect + style="fill:#d0cee2;fill-opacity:1;stroke:#000000;stroke-opacity:1" + id="rect1833" + width="222.34483" + height="44.64616" + x="867.36292" + y="1402.4268" /> + <rect + style="fill:#afdde9;fill-opacity:1;stroke:#000000;stroke-opacity:1" + id="rect1915" + width="222.34483" + height="44.64616" + x="867.36292" + y="1330.4268" + inkscape:connector-avoid="true" /> + <rect + style="fill:#afdde9;fill-opacity:1;stroke:#000000;stroke-opacity:1" + id="rect1917" + width="222.34483" + height="44.64616" + x="867.36292" + y="1478.4268" /> + <rect + style="fill:#fad7ac;fill-opacity:1;stroke:#000000;stroke-opacity:1" + id="rect1919" + width="222.34483" + height="44.64616" + x="867.36292" + y="1548.4268" /> + <rect + style="fill:#eeeeee;fill-opacity:1;stroke:#000000;stroke-opacity:1" + id="rect1921" + width="222.34483" + height="44.64616" + x="867.36292" + y="1614.4268" /> + <rect + style="fill:#eeeeee;fill-opacity:1;stroke:#000000;stroke-opacity:1" + id="rect1923" + width="222.34483" + height="44.64616" + x="867.36292" + y="1686.4268" /> + <rect + style="fill:#eeeeee;fill-opacity:1;stroke:#000000;stroke-opacity:1" + id="rect1925" + width="222.34483" + height="44.64616" + x="867.36292" + y="1754.4268" /> + <rect + style="fill:#f9f7ed;fill-opacity:1;stroke:#000000;stroke-width:0.872749;stroke-opacity:1" + id="rect1925-3" + width="169.23357" + height="44.678963" + x="325.21747" + y="134.37756" /> + <rect + style="fill:#fad7ac;fill-opacity:1;stroke:#000000;stroke-width:0.872749;stroke-opacity:1" + id="rect1954" + width="169.23357" + height="44.678963" + x="325.21747" + y="276.37756" + inkscape:connector-avoid="true" /> + <rect + style="fill:#afdde9;fill-opacity:1;stroke:#000000;stroke-width:0.87333333;stroke-opacity:1;stroke-miterlimit:4;stroke-dasharray:none" + id="rect1956" + width="168.66573" + height="122.14091" + x="325.50134" + y="358.6615" + inkscape:connector-avoid="true" /> + <rect + style="fill:#e6e6e6;fill-opacity:1;stroke:#000000;stroke-width:0.872749;stroke-opacity:1" + id="rect1958" + width="169.23357" + height="44.678963" + x="325.21747" + y="672.37756" /> + <rect + style="fill:#fad7ac;fill-opacity:1;stroke:#000000;stroke-width:0.872749;stroke-opacity:1" + id="rect1960" + width="169.23357" + height="44.678963" + x="325.21747" + y="744.37756" /> + <rect + style="fill:#afdde9;fill-opacity:1;stroke:#000000;stroke-width:0.965912;stroke-opacity:1" + id="rect1962" + width="169.14041" + height="54.756817" + x="325.26404" + y="814.42413" + inkscape:connector-avoid="true" /> + <rect + style="fill:#d0cee2;fill-opacity:1;stroke:#000000;stroke-width:0.965912;stroke-opacity:1" + id="rect1964" + width="169.14041" + height="54.756817" + x="325.26404" + y="886.42413" + inkscape:connector-avoid="true" /> + <rect + style="fill:#afdde9;fill-opacity:1;stroke:#000000;stroke-width:0.965912;stroke-opacity:1" + id="rect1966" + width="169.14041" + height="54.756817" + x="325.26404" + y="952.42413" + inkscape:connector-avoid="true" /> + <rect + style="fill:#fad7ac;fill-opacity:1;stroke:#000000;stroke-width:0.872749;stroke-opacity:1" + id="rect2418" + width="169.23357" + height="44.678963" + x="325.21747" + y="510.37756" + inkscape:connector-avoid="true" /> + <rect + style="fill:#fad7ac;fill-opacity:1;stroke:#000000;stroke-width:0.872749;stroke-opacity:1" + id="rect2422" + width="169.23357" + height="44.678963" + x="325.21747" + y="1262.3777" /> + <rect + style="fill:#afdde9;fill-opacity:1;stroke:#000000;stroke-width:0.981369;stroke-opacity:1" + id="rect2424" + width="169.12494" + height="56.528603" + x="325.27179" + y="1322.432" /> + <rect + style="fill:#d0cee2;fill-opacity:1;stroke:#000000;stroke-width:0.981369;stroke-opacity:1" + id="rect2426" + width="169.12494" + height="56.528603" + x="325.27179" + y="1396.432" /> + <rect + style="fill:#afdde9;fill-opacity:1;stroke:#000000;stroke-width:1.02091;stroke-opacity:1" + id="rect2428" + width="169.0854" + height="61.19017" + x="325.29156" + y="1468.4518" /> + <rect + style="fill:#fad7ac;fill-opacity:1;stroke:#000000;stroke-width:0.839627;stroke-opacity:1" + id="rect2430" + width="169.26669" + height="41.344128" + x="325.20093" + y="1550.3611" /> + <rect + style="fill:#000000;fill-opacity:0;stroke:#000000;stroke-width:1.13491;stroke-opacity:1" + id="rect2432" + width="287.86237" + height="44.416805" + x="325.34854" + y="1194.5088" /> + <rect + style="fill:#000000;fill-opacity:0;stroke:#000000;stroke-width:1.13102;stroke-opacity:1" + id="rect2434" + width="285.86655" + height="44.4207" + x="867.34656" + y="1194.5068" /> + <path + style="fill:none;stroke:#000000;stroke-width:2.66666675;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1;stroke-miterlimit:4;stroke-dasharray:8.00000024, 8.00000024;stroke-dashoffset:0" + d="m 867.36292,235.07281 v 0" + id="path2509" /> + <path + style="fill:none;stroke:#000000;stroke-width:2.66666675;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1;stroke-miterlimit:4;stroke-dasharray:8.00000024, 8.00000024;stroke-dashoffset:0" + d="m 867.36292,235.07281 v 0" + id="path2511" /> + <path + style="fill:none;stroke:#000000;stroke-width:2.66666675;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1;stroke-miterlimit:4;stroke-dasharray:8.00000024, 8.00000024;stroke-dashoffset:0" + d="m 867.36292,235.07281 v 0" + id="path2513" /> + <path + style="fill:none;stroke:#000000;stroke-width:2.66666675;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1;stroke-miterlimit:4;stroke-dasharray:8.00000024, 8.00000024;stroke-dashoffset:0" + d="m 867.36292,235.07281 v 0" + id="path2515" /> + <path + style="fill:none;stroke:#000000;stroke-width:2.66666675;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1;stroke-miterlimit:4;stroke-dasharray:8.00000024, 8.00000024;stroke-dashoffset:0" + d="m 867.36292,235.07281 v 0" + id="path2517" /> + <path + style="fill:none;stroke:#000000;stroke-width:2.66666675;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1;stroke-miterlimit:4;stroke-dasharray:8.00000024, 8.00000024;stroke-dashoffset:0" + d="m 867.36292,235.07281 v 0" + id="path2519" /> + <path + style="fill:none;stroke:#000000;stroke-width:2.66666675;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1;stroke-miterlimit:4;stroke-dasharray:8.00000024, 8.00000024;stroke-dashoffset:0" + d="m 867.36292,235.07281 v 0" + id="path2521" /> + <path + style="fill:none;stroke:#000000;stroke-width:2.66666675;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1;stroke-miterlimit:4;stroke-dasharray:8.00000024, 8.00000024;stroke-dashoffset:0" + d="m 867.36292,235.07281 v 0" + id="path2523" /> + <path + style="fill:none;stroke:#000000;stroke-width:2.66666675;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1;stroke-miterlimit:4;stroke-dasharray:8.00000024, 8.00000024;stroke-dashoffset:0" + d="m 867.36292,235.07281 v 0" + id="path2525" /> + <path + style="fill:none;stroke:#000000;stroke-width:2.66666675;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1;stroke-miterlimit:4;stroke-dasharray:8.00000024, 8.00000024;stroke-dashoffset:0" + d="m 867.36292,235.07281 v 0" + id="path2527" /> + <path + style="fill:none;stroke:#000000;stroke-width:2.66666675;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1;stroke-miterlimit:4;stroke-dasharray:8.00000024, 8.00000024;stroke-dashoffset:0" + d="m 867.36292,235.07281 v 0" + id="path2529" /> + <path + style="fill:none;stroke:#000000;stroke-width:2.66666675;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1;stroke-miterlimit:4;stroke-dasharray:8.00000024, 8.00000024;stroke-dashoffset:0" + d="m 867.36292,235.07281 v 0" + id="path2531" /> + <path + style="fill:none;fill-rule:evenodd;stroke:#000000;stroke-width:2;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:6, 6;stroke-dashoffset:0;stroke-opacity:1" + d="m 449.83425,179.05653 v 33.6932 h 417.52867" + id="path6876" + inkscape:connector-type="orthogonal" + inkscape:connector-curvature="0" + inkscape:connection-start="#rect1925-3" + inkscape:connection-end="#rect1731" + sodipodi:nodetypes="ccc" /> + <path + style="display:inline;fill:none;fill-rule:evenodd;stroke:#000000;stroke-width:2;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:6, 6;stroke-dashoffset:0;stroke-opacity:1" + d="m 494.45103,156.71704 h 216.64955 v 161.7096 h 156.26234" + id="path6878" + inkscape:connector-type="orthogonal" + inkscape:connector-curvature="0" + inkscape:connection-start="#rect1925-3" + sodipodi:nodetypes="cccc" /> + <path + style="fill:none;fill-rule:evenodd;stroke:#000000;stroke-width:2;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:6, 6;stroke-dashoffset:0;stroke-opacity:1" + d="m 451.83425,321.05653 v 19.69319 h 415.52867" + id="path7294" + inkscape:connector-type="orthogonal" + inkscape:connector-curvature="0" + inkscape:connection-start="#rect1954" + inkscape:connection-end="#rect1815" + sodipodi:nodetypes="ccc" /> + <path + style="fill:none;fill-rule:evenodd;stroke:#000000;stroke-width:2;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:6, 6;stroke-dashoffset:0;stroke-opacity:1" + d="M 494.45103,298.71704 H 659.10058 V 434.74972 H 867.36292" + id="path7296" + inkscape:connector-type="orthogonal" + inkscape:connector-curvature="0" + inkscape:connection-end="#rect1817" + inkscape:connection-start="#rect1954" + sodipodi:nodetypes="cccc" /> + <path + style="display:inline;fill:none;fill-rule:evenodd;stroke:#000000;stroke-width:2;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:6, 6;stroke-dashoffset:0;stroke-opacity:1" + d="M 867.36292,560.42664 H 661.10058 V 480.8024 H 494.16705" + id="path7720" + inkscape:connector-type="orthogonal" + inkscape:connector-curvature="0" + sodipodi:nodetypes="cccc" /> + <path + style="fill:none;fill-rule:evenodd;stroke:#000000;stroke-width:2;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:6, 6;stroke-dashoffset:0;stroke-opacity:1" + d="M 455.83425,594.37756 V 582.74972 H 867.36292" + id="path7724" + inkscape:connector-type="orthogonal" + inkscape:connector-curvature="0" + inkscape:connection-start="#rect2420" + inkscape:connection-end="#rect1819" + sodipodi:nodetypes="ccc" /> + <rect + style="fill:#afdde9;fill-opacity:1;stroke:#000000;stroke-width:0.872749;stroke-opacity:1" + id="rect2420" + width="169.23357" + height="44.678963" + x="325.21747" + y="594.37756" /> + <path + style="fill:none;fill-rule:evenodd;stroke:#000000;stroke-width:2;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:6, 6;stroke-dashoffset:0;stroke-opacity:1" + d="M 494.45103,696.74972 H 867.36292" + id="path7726" + inkscape:connector-type="orthogonal" + inkscape:connector-curvature="0" + inkscape:connection-start="#rect1958" + inkscape:connection-end="#rect1821" /> + <path + style="fill:none;fill-rule:evenodd;stroke:#000000;stroke-width:2;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:6, 6;stroke-dashoffset:0;stroke-opacity:1" + d="M 867.36292,766.74972 H 494.45103" + id="path7728" + inkscape:connector-type="orthogonal" + inkscape:connector-curvature="0" + inkscape:connection-start="#rect1823" + inkscape:connection-end="#rect1960" /> + <path + style="display:inline;fill:none;fill-rule:evenodd;stroke:#000000;stroke-width:2;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:6, 6;stroke-dashoffset:0;stroke-opacity:1" + d="M 494.45105,789.05652 H 657.82418 V 1278.7498 H 867.36292" + id="path7730" + inkscape:connector-type="orthogonal" + inkscape:connector-curvature="0" + inkscape:connection-end="#rect1831" + sodipodi:nodetypes="cccc" /> + <path + style="fill:none;fill-rule:evenodd;stroke:#000000;stroke-width:2;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:6, 6;stroke-dashoffset:0;stroke-opacity:1" + d="m 494.40445,841.80254 h 167.41973 v 0.94718 h 205.53874" + id="path8140" + inkscape:connector-type="orthogonal" + inkscape:connector-curvature="0" + inkscape:connection-start="#rect1962" + inkscape:connection-end="#rect1825" /> + <path + style="fill:none;fill-rule:evenodd;stroke:#000000;stroke-width:2;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:6, 6;stroke-dashoffset:0;stroke-opacity:1" + d="m 494.40445,913.80254 h 167.41973 v -1.05282 h 205.53874" + id="path8142" + inkscape:connector-type="orthogonal" + inkscape:connector-curvature="0" + inkscape:connection-start="#rect1964" + inkscape:connection-end="#rect1827" /> + <path + style="fill:none;fill-rule:evenodd;stroke:#000000;stroke-width:2;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:6, 6;stroke-dashoffset:0;stroke-opacity:1" + d="m 494.40445,979.80254 h 167.41973 v -1.05282 h 205.53874" + id="path8144" + inkscape:connector-type="orthogonal" + inkscape:connector-curvature="0" + inkscape:connection-start="#rect1966" + inkscape:connection-end="#rect1829" /> + <path + style="fill:none;fill-rule:evenodd;stroke:#000000;stroke-width:2;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:6, 6;stroke-dashoffset:0;stroke-opacity:1" + d="M 494.39673,1352.7498 H 867.36292" + id="path8146" + inkscape:connector-type="orthogonal" + inkscape:connector-curvature="0" + inkscape:connection-start="#rect2424" + inkscape:connection-end="#rect1915" /> + <path + style="fill:none;fill-rule:evenodd;stroke:#000000;stroke-width:2;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:6, 6;stroke-dashoffset:0;stroke-opacity:1" + d="M 494.39673,1424.7498 H 867.36292" + id="path8148" + inkscape:connector-type="orthogonal" + inkscape:connector-curvature="0" + inkscape:connection-start="#rect2426" + inkscape:connection-end="#rect1833" /> + <path + style="fill:none;fill-rule:evenodd;stroke:#000000;stroke-width:2;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:6, 6;stroke-dashoffset:0;stroke-opacity:1" + d="M 494.37697,1500.7498 H 867.36292" + id="path8150" + inkscape:connector-type="orthogonal" + inkscape:connector-curvature="0" + inkscape:connection-start="#rect2428" + inkscape:connection-end="#rect1917" /> + <path + style="fill:none;fill-rule:evenodd;stroke:#000000;stroke-width:2;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:6, 6;stroke-dashoffset:0;stroke-opacity:1" + d="m 494.46762,1570.7498 h 372.8953" + id="path8152" + inkscape:connector-type="orthogonal" + inkscape:connector-curvature="0" + inkscape:connection-start="#rect2430" + inkscape:connection-end="#rect1919" /> + <path + style="fill:none;fill-rule:evenodd;stroke:#000000;stroke-width:2;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:6, 6;stroke-dashoffset:0;stroke-opacity:1" + d="M 1396.3848,1289.175 H 1288.1445 V 582.74972 h -198.4368" + id="path8154" + inkscape:connector-type="orthogonal" + inkscape:connector-curvature="0" + inkscape:connection-start="#rect1623" + inkscape:connection-end="#rect1819" /> + <path + style="fill:none;fill-rule:evenodd;stroke:#000000;stroke-width:2;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:6, 6;stroke-dashoffset:0;stroke-opacity:1" + d="m 1396.3848,1369.175 h -156.2403 v -90.4252 h -150.4368" + id="path8462" + inkscape:connector-type="orthogonal" + inkscape:connector-curvature="0" + inkscape:connection-start="#rect1705" + inkscape:connection-end="#rect1831" + sodipodi:nodetypes="cccc" /> + <path + style="fill:none;fill-rule:evenodd;stroke:#000000;stroke-width:2;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:6, 6;stroke-dashoffset:0;stroke-opacity:1" + d="m 1089.7077,1500.7498 h 375.3403 v -26.6834" + id="path8668" + inkscape:connector-type="orthogonal" + inkscape:connector-curvature="0" + inkscape:connection-start="#rect1917" + inkscape:connection-end="#rect1707" /> + <path + style="fill:none;fill-rule:evenodd;stroke:#000000;stroke-width:2;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:6, 6;stroke-dashoffset:0;stroke-opacity:1" + d="M 1389.9988,212.74973 H 1089.7077" + id="path8672" + inkscape:connector-type="orthogonal" + inkscape:connector-curvature="0" + inkscape:connection-start="#rect1349" + inkscape:connection-end="#rect1731" /> + <path + style="display:inline;fill:none;fill-rule:evenodd;stroke:#000000;stroke-width:2;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:6, 6;stroke-dashoffset:0;stroke-opacity:1" + d="M 1389.9988,230.9507 H 1223.331 v 109.79902 h -133.6233" + id="path8674" + inkscape:connector-type="orthogonal" + inkscape:connector-curvature="0" + inkscape:connection-end="#rect1815" + sodipodi:nodetypes="cccc" /> + <text + xml:space="preserve" + style="font-style:normal;font-weight:normal;font-size:40px;line-height:1.25;font-family:sans-serif;fill:#000000;fill-opacity:1;stroke:none" + x="58.63356" + y="69.574417" + id="text28675"><tspan + sodipodi:role="line" + id="tspan28673" + x="58.63356" + y="69.574417" /></text> + <text + xml:space="preserve" + style="font-style:normal;font-weight:normal;font-size:18.6667px;line-height:1.25;font-family:sans-serif;fill:#000000;fill-opacity:1;stroke:none" + x="56.388252" + y="221.86568" + id="text31913"><tspan + sodipodi:role="line" + id="tspan31911" + x="56.388252" + y="221.86568">Matrix</tspan></text> + <text + xml:space="preserve" + style="font-style:normal;font-weight:normal;font-size:18.6667px;line-height:1.25;font-family:sans-serif;fill:#000000;fill-opacity:1;stroke:none" + x="53.441296" + y="300.866" + id="text38843"><tspan + sodipodi:role="line" + id="tspan38841" + x="53.441296" + y="300.866">1D LUT</tspan></text> + <text + xml:space="preserve" + style="font-style:normal;font-weight:normal;font-size:18.6667px;line-height:1.25;font-family:sans-serif;fill:#000000;fill-opacity:1;stroke:none" + x="53.441296" + y="378.866" + id="text41049"><tspan + sodipodi:role="line" + id="tspan41047" + x="53.441296" + y="378.866">3D LUT</tspan></text> + <text + xml:space="preserve" + style="font-style:normal;font-weight:normal;font-size:18.6667px;line-height:1.25;font-family:sans-serif;fill:#000000;fill-opacity:1;stroke:none" + x="40.831493" + y="460.87411" + id="text45037"><tspan + sodipodi:role="line" + id="tspan45035" + x="40.831493" + y="460.87411" + style="font-size:18.6667px">Unpacking</tspan></text> + <text + xml:space="preserve" + style="font-style:normal;font-weight:normal;font-size:18.6667px;line-height:1.25;font-family:sans-serif;fill:#000000;fill-opacity:1;stroke:none" + x="62.130371" + y="540.68872" + id="text49945"><tspan + sodipodi:role="line" + id="tspan49943" + x="62.130371" + y="540.68872" + style="font-size:18.6667px">Other</tspan></text> + <text + xml:space="preserve" + style="font-style:normal;font-weight:normal;font-size:18.6667px;line-height:1.25;font-family:sans-serif;fill:#000000;fill-opacity:1;stroke:none" + x="1423.2806" + y="128.08769" + id="text55719"><tspan + sodipodi:role="line" + id="tspan55717" + x="1423.2806" + y="128.08769" + style="font-size:18.6667px">drm_framebuffer</tspan></text> + <text + xml:space="preserve" + style="font-style:normal;font-weight:normal;font-size:18.6667px;line-height:1.25;font-family:sans-serif;fill:#000000;fill-opacity:1;stroke:none" + x="1439.9988" + y="218.74973" + id="text62479"><tspan + sodipodi:role="line" + id="tspan62477" + x="1439.9988" + y="218.74973" + style="font-size:18.6667px">format</tspan></text> + <text + xml:space="preserve" + style="font-style:normal;font-weight:normal;font-size:18.6667px;line-height:1.25;font-family:sans-serif;fill:#000000;fill-opacity:1;stroke:none" + x="1475.2806" + y="340.08771" + id="text64465"><tspan + sodipodi:role="line" + id="tspan64463" + x="1475.2806" + y="340.08771" + style="font-size:18.6667px">drm_plane</tspan></text> + <text + xml:space="preserve" + style="font-style:normal;font-weight:normal;font-size:18.6667px;line-height:1.25;font-family:sans-serif;fill:#000000;fill-opacity:1;stroke:none" + x="1589.2806" + y="1178.0876" + id="text64469"><tspan + sodipodi:role="line" + id="tspan64467" + x="1589.2806" + y="1178.0876" + style="font-size:18.6667px">drm_crtc</tspan></text> + <text + xml:space="preserve" + style="font-style:normal;font-weight:normal;font-size:18.6667px;line-height:1.25;font-family:sans-serif;fill:#000000;fill-opacity:1;stroke:none" + x="872.23993" + y="1172.4491" + id="text64469-9"><tspan + sodipodi:role="line" + id="tspan64467-2" + x="872.23993" + y="1172.4491" + style="font-size:18.6667px">Stream</tspan></text> + <text + xml:space="preserve" + style="font-style:normal;font-weight:normal;font-size:18.6667px;line-height:1.25;font-family:sans-serif;fill:#000000;fill-opacity:1;stroke:none" + x="328.26071" + y="1175.6371" + id="text64469-9-2"><tspan + sodipodi:role="line" + id="tspan64467-2-8" + x="328.26071" + y="1175.6371" + style="font-size:18.6667px">MPC</tspan></text> + <text + xml:space="preserve" + style="font-style:normal;font-weight:normal;font-size:18.6667px;line-height:1.25;font-family:sans-serif;fill:#000000;fill-opacity:1;stroke:none" + x="330.14737" + y="114.41869" + id="text64469-9-9"><tspan + sodipodi:role="line" + id="tspan64467-2-7" + x="330.14737" + y="114.41869" + style="font-size:18.6667px">DPP</tspan></text> + <path + d="m 1488.3608,401.47792 c 0.025,10.97895 0.01,773.03788 0.049,784.01888 2.5462,-1.1592 5.0637,-2.3779 7.6202,-3.5187 -2.7411,4.8298 -5.4987,9.6453 -8.2624,14.4607 -2.7925,-4.8257 -5.5993,-9.6453 -8.3856,-14.4751 2.6221,1.1736 5.2217,2.3923 7.8398,3.5721 0,-10.8825 -0.035,-772.84093 -0.031,-783.72345 0.053,-0.30366 -0.2175,-0.50268 -0.3652,-0.72837 l 1.5347,0.39394 z" + id="path106" + sodipodi:nodetypes="cccccccccc" + style="stroke-width:0.205176" + inkscape:transform-center-x="-325.50819" + inkscape:transform-center-y="-121.97185" /> + <text + xml:space="preserve" + style="font-style:normal;font-weight:normal;font-size:18.6667px;line-height:1.25;font-family:sans-serif;fill:#000000;fill-opacity:1;stroke:none" + x="1495.9988" + y="1224.7498" + id="text78849"><tspan + sodipodi:role="line" + id="tspan78847" + x="1495.9988" + y="1224.7498" + style="font-size:18.6667px">Blender</tspan></text> + <text + xml:space="preserve" + style="font-style:normal;font-weight:normal;font-size:18.6667px;line-height:1.25;font-family:sans-serif;fill:#000000;fill-opacity:1;stroke:none" + x="1417.9988" + y="1294.7498" + id="text78853"><tspan + sodipodi:role="line" + id="tspan78851" + x="1417.9988" + y="1294.7498" + style="font-size:18.6667px">Degamma</tspan></text> + <text + xml:space="preserve" + style="font-style:normal;font-weight:normal;font-size:18.6667px;line-height:1.25;font-family:sans-serif;fill:#000000;fill-opacity:1;stroke:none" + x="1451.9988" + y="1376.7498" + id="text78857"><tspan + sodipodi:role="line" + id="tspan78855" + x="1451.9988" + y="1376.7498" + style="font-size:18.6667px">CTM</tspan></text> + <text + xml:space="preserve" + style="font-style:normal;font-weight:normal;font-size:18.6667px;line-height:1.25;font-family:sans-serif;fill:#000000;fill-opacity:1;stroke:none" + x="1427.9988" + y="1458.7498" + id="text78861"><tspan + sodipodi:role="line" + id="tspan78859" + x="1427.9988" + y="1458.7498" + style="font-size:18.6667px">Gamma</tspan></text> + <text + xml:space="preserve" + style="font-style:normal;font-weight:normal;font-size:18.6667px;line-height:1.25;font-family:sans-serif;fill:#000000;fill-opacity:1;stroke:none" + x="949.99878" + y="218.74973" + id="text104653"><tspan + sodipodi:role="line" + id="tspan104651" + x="949.99878" + y="218.74973" + style="font-size:18.6667px">format</tspan></text> + <text + xml:space="preserve" + style="font-style:normal;font-weight:normal;font-size:18.6667px;line-height:1.25;font-family:sans-serif;fill:#000000;fill-opacity:1;stroke:none" + x="911.99878" + y="284.74973" + id="text104657"><tspan + sodipodi:role="line" + id="tspan104655" + x="911.99878" + y="284.74973" + style="font-size:18.6667px">bias_and_scale</tspan></text> + <text + xml:space="preserve" + style="font-style:normal;font-weight:normal;font-size:18.6667px;line-height:1.25;font-family:sans-serif;fill:#000000;fill-opacity:1;stroke:none" + x="887.99878" + y="346.74973" + id="text104661"><tspan + sodipodi:role="line" + id="tspan104659" + x="887.99878" + y="346.74973" + style="font-size:18.6667px">color space matrix</tspan></text> + <text + xml:space="preserve" + style="font-style:normal;font-weight:normal;font-size:18.6667px;line-height:1.25;font-family:sans-serif;fill:#000000;fill-opacity:1;stroke:none" + x="871.99878" + y="442.74973" + id="text104665"><tspan + sodipodi:role="line" + id="tspan104663" + x="871.99878" + y="442.74973" + style="font-size:18.6667px">input_csc_color_matrix</tspan></text> + <text + xml:space="preserve" + style="font-style:normal;font-weight:normal;font-size:18.6667px;line-height:1.25;font-family:sans-serif;fill:#000000;fill-opacity:1;stroke:none" + x="905.99878" + y="586.74976" + id="text125075"><tspan + sodipodi:role="line" + id="tspan125073" + x="905.99878" + y="586.74976" + style="font-size:18.6667px">in_transfer_func</tspan></text> + <text + xml:space="preserve" + style="font-style:normal;font-weight:normal;font-size:18.6667px;line-height:1.25;font-family:sans-serif;fill:#000000;fill-opacity:1;stroke:none" + x="945.0083" + y="702.85938" + id="text117309"><tspan + sodipodi:role="line" + id="tspan117307" + x="945.0083" + y="702.85938" + style="font-size:18.6667px">hdr_mult</tspan></text> + <text + xml:space="preserve" + style="font-style:normal;font-weight:normal;font-size:18.6667px;line-height:1.25;font-family:sans-serif;fill:#000000;fill-opacity:1;stroke:none" + x="874.5556" + y="773.42615" + id="text117309-6"><tspan + sodipodi:role="line" + id="tspan117307-7" + x="874.5556" + y="773.42615" + style="font-size:18.6667px">gamut_remap_matrix</tspan></text> + <text + xml:space="preserve" + style="font-style:normal;font-weight:normal;font-size:18.6667px;line-height:1.25;font-family:sans-serif;fill:#000000;fill-opacity:1;stroke:none" + x="913.72528" + y="846.55896" + id="text117309-5"><tspan + sodipodi:role="line" + id="tspan117307-3" + x="913.72528" + y="846.55896" + style="font-size:18.6667px">in_shaper_func</tspan></text> + <text + xml:space="preserve" + style="font-style:normal;font-weight:normal;font-size:18.6667px;line-height:1.25;font-family:sans-serif;fill:#000000;fill-opacity:1;stroke:none" + x="937.72528" + y="918.25787" + id="text117309-56"><tspan + sodipodi:role="line" + id="tspan117307-2" + x="937.72528" + y="918.25787" + style="font-size:18.6667px">lut3d_func</tspan></text> + <text + xml:space="preserve" + style="font-style:normal;font-weight:normal;font-size:18.6667px;line-height:1.25;font-family:sans-serif;fill:#000000;fill-opacity:1;stroke:none" + x="945.9895" + y="986.10767" + id="text117309-9"><tspan + sodipodi:role="line" + id="tspan117307-1" + x="945.9895" + y="986.10767" + style="font-size:18.6667px">blend_tf</tspan></text> + <text + xml:space="preserve" + style="font-style:normal;font-weight:normal;font-size:18.6667px;line-height:1.25;font-family:sans-serif;fill:#000000;fill-opacity:1;stroke:none" + x="975.91803" + y="1224.5564" + id="text137434"><tspan + sodipodi:role="line" + id="tspan137432" + x="975.91803" + y="1224.5564" + style="font-size:18.6667px">Blender</tspan></text> + <text + xml:space="preserve" + style="font-style:normal;font-weight:normal;font-size:18.6667px;line-height:1.25;font-family:sans-serif;fill:#000000;fill-opacity:1;stroke:none" + x="879.31372" + y="1283.4249" + id="text137434-2"><tspan + sodipodi:role="line" + id="tspan137432-7" + x="879.31372" + y="1283.4249" + style="font-size:18.6667px">gamut_remap_matrix</tspan></text> + <text + xml:space="preserve" + style="font-style:normal;font-weight:normal;font-size:18.6667px;line-height:1.25;font-family:sans-serif;fill:#000000;fill-opacity:1;stroke:none" + x="925.31372" + y="1359.2747" + id="text137434-0"><tspan + sodipodi:role="line" + id="tspan137432-9" + x="925.31372" + y="1359.2747" + style="font-size:18.6667px">func_shaper</tspan></text> + <text + xml:space="preserve" + style="font-style:normal;font-weight:normal;font-size:18.6667px;line-height:1.25;font-family:sans-serif;fill:#000000;fill-opacity:1;stroke:none" + x="930.33252" + y="1430.2566" + id="text137434-3"><tspan + sodipodi:role="line" + id="tspan137432-6" + x="930.33252" + y="1430.2566" + style="font-size:18.6667px">lut3d_func</tspan></text> + <text + xml:space="preserve" + style="font-style:normal;font-weight:normal;font-size:18.6667px;line-height:1.25;font-family:sans-serif;fill:#000000;fill-opacity:1;stroke:none" + x="900.18158" + y="1504.6725" + id="text137434-06"><tspan + sodipodi:role="line" + id="tspan137432-2" + x="900.18158" + y="1504.6725" + style="font-size:18.6667px">out_transfer_func</tspan></text> + <text + xml:space="preserve" + style="font-style:normal;font-weight:normal;font-size:18.6667px;line-height:1.25;font-family:sans-serif;fill:#000000;fill-opacity:1;stroke:none" + x="904.0307" + y="1575.8053" + id="text137434-6"><tspan + sodipodi:role="line" + id="tspan137432-1" + x="904.0307" + y="1575.8053" + style="font-size:18.6667px">csc_color_matrix</tspan></text> + <text + xml:space="preserve" + style="font-style:normal;font-weight:normal;font-size:18.6667px;line-height:1.25;font-family:sans-serif;fill:#000000;fill-opacity:1;stroke:none" + x="903.16278" + y="1642.1078" + id="text137434-8"><tspan + sodipodi:role="line" + id="tspan137432-79" + x="903.16278" + y="1642.1078" + style="font-size:18.6667px">bit_depth_param</tspan></text> + <text + xml:space="preserve" + style="font-style:normal;font-weight:normal;font-size:18.6667px;line-height:1.25;font-family:sans-serif;fill:#000000;fill-opacity:1;stroke:none" + x="939.31372" + y="1713.8068" + id="text137434-20"><tspan + sodipodi:role="line" + id="tspan137432-23" + x="939.31372" + y="1713.8068" + style="font-size:18.6667px">clamping</tspan></text> + <text + xml:space="preserve" + style="font-style:normal;font-weight:normal;font-size:18.6667px;line-height:1.25;font-family:sans-serif;fill:#000000;fill-opacity:1;stroke:none" + x="894.0307" + y="1782.5244" + id="text137434-7"><tspan + sodipodi:role="line" + id="tspan137432-5" + x="894.0307" + y="1782.5244" + style="font-size:18.6667px">output_color_space</tspan></text> + <text + xml:space="preserve" + style="font-style:normal;font-weight:normal;font-size:18.6667px;line-height:1.25;font-family:sans-serif;fill:#000000;fill-opacity:1;stroke:none" + x="869.63062" + y="117.7968" + id="text176429"><tspan + sodipodi:role="line" + id="tspan176427" + x="869.63062" + y="117.7968" + style="font-size:18.6667px">Plane</tspan></text> + <text + xml:space="preserve" + style="font-style:normal;font-weight:normal;font-size:18.6667px;line-height:1.25;font-family:sans-serif;fill:#000000;fill-opacity:1;stroke:none" + x="27.605465" + y="162.20587" + id="text176429-2"><tspan + sodipodi:role="line" + id="tspan176427-0" + x="27.605465" + y="162.20587" + style="font-size:18.6667px">Legend</tspan></text> + <text + xml:space="preserve" + style="font-style:normal;font-weight:normal;font-size:18.6667px;line-height:1.25;font-family:sans-serif;fill:#000000;fill-opacity:1;stroke:none" + x="298.63959" + y="59.293999" + id="text176429-9"><tspan + sodipodi:role="line" + id="tspan176427-2" + x="298.63959" + y="59.293999" + style="font-size:18.6667px">DCN 3.0</tspan></text> + <text + xml:space="preserve" + style="font-style:normal;font-weight:normal;font-size:18.6667px;line-height:1.25;font-family:sans-serif;fill:#000000;fill-opacity:1;stroke:none" + x="826.65735" + y="59.458061" + id="text176429-66"><tspan + sodipodi:role="line" + id="tspan176427-4" + x="826.65735" + y="59.458061" + style="font-size:18.6667px">DC Interface</tspan></text> + <text + xml:space="preserve" + style="font-style:normal;font-weight:normal;font-size:18.6667px;line-height:1.25;font-family:sans-serif;fill:#000000;fill-opacity:1;stroke:none" + x="1362.9948" + y="59.458061" + id="text176429-95"><tspan + sodipodi:role="line" + id="tspan176427-04" + x="1362.9948" + y="59.458061" + style="font-size:18.6667px">DRM Interface</tspan></text> + <text + xml:space="preserve" + style="font-style:normal;font-weight:normal;font-size:40px;line-height:1.25;font-family:sans-serif;fill:#000000;fill-opacity:1;stroke:none" + x="867.34656" + y="1194.5068" + id="text184728"><tspan + sodipodi:role="line" + id="tspan184726" + x="867.34656" + y="1194.5068" /></text> + <text + xml:space="preserve" + style="font-style:normal;font-weight:normal;font-size:18.6667px;line-height:1.25;font-family:sans-serif;fill:#000000;fill-opacity:1;stroke:none" + x="389.01593" + y="159.8909" + id="text64469-9-3"><tspan + sodipodi:role="line" + id="tspan64467-2-6" + x="389.01593" + y="159.8909" + style="font-size:18.6667px">CNVC</tspan></text> + <text + xml:space="preserve" + style="font-style:normal;font-weight:normal;font-size:18.6667px;line-height:1.25;font-family:sans-serif;fill:#000000;fill-opacity:1;stroke:none" + x="365.88379" + y="303.59048" + id="text64469-9-1"><tspan + sodipodi:role="line" + id="tspan64467-2-2" + x="365.88379" + y="303.59048" + style="font-size:18.6667px">Input CSC</tspan></text> + <text + xml:space="preserve" + style="font-style:normal;font-weight:normal;font-size:18.6667px;line-height:1.25;font-family:sans-serif;fill:#000000;fill-opacity:1;stroke:none" + x="413.06488" + y="390.95001" + id="text64469-9-93"><tspan + sodipodi:role="line" + id="tspan64467-2-1" + x="413.06488" + y="390.95001" + style="font-size:18.6667px;text-align:center;text-anchor:middle">DeGamma</tspan><tspan + sodipodi:role="line" + x="413.06488" + y="414.28339" + style="font-size:18.6667px;text-align:center;text-anchor:middle" + id="tspan233797">ROM</tspan><tspan + sodipodi:role="line" + x="413.06488" + y="437.61676" + style="font-size:10.6667px;text-align:center;text-anchor:middle" + id="tspan233799">(sRGB, BT2020, Gamma 2.2,</tspan><tspan + sodipodi:role="line" + x="413.06488" + y="460.95013" + style="font-size:10.6667px;text-align:center;text-anchor:middle" + id="tspan242597">PQ, HLG)</tspan></text> + <text + xml:space="preserve" + style="font-style:normal;font-weight:normal;font-size:18.6667px;line-height:1.25;font-family:sans-serif;fill:#000000;fill-opacity:1;stroke:none" + x="372.44986" + y="538.83807" + id="text64469-9-94"><tspan + sodipodi:role="line" + id="tspan64467-2-78" + x="372.44986" + y="538.83807" + style="font-size:18.6667px">Post CSC</tspan></text> + <text + xml:space="preserve" + style="font-style:normal;font-weight:normal;font-size:16px;line-height:1.25;font-family:sans-serif;fill:#000000;fill-opacity:1;stroke:none" + x="335.31775" + y="622.23511" + id="text64469-9-4"><tspan + sodipodi:role="line" + id="tspan64467-2-5" + x="335.31775" + y="622.23511" + style="font-size:16px">Gamma Correction</tspan></text> + <text + xml:space="preserve" + style="font-style:normal;font-weight:normal;font-size:18.6667px;line-height:1.25;font-family:sans-serif;fill:#000000;fill-opacity:1;stroke:none" + x="351.16684" + y="700.34918" + id="text64469-9-0"><tspan + sodipodi:role="line" + id="tspan64467-2-3" + x="351.16684" + y="700.34918" + style="font-size:18.6667px">HDR Multiply</tspan></text> + <text + xml:space="preserve" + style="font-style:normal;font-weight:normal;font-size:18.6667px;line-height:1.25;font-family:sans-serif;fill:#000000;fill-opacity:1;stroke:none" + x="345.16684" + y="771.33112" + id="text64469-9-6"><tspan + sodipodi:role="line" + id="tspan64467-2-10" + x="345.16684" + y="771.33112" + style="font-size:18.6667px">Gamut Remap</tspan></text> + <text + xml:space="preserve" + style="font-style:normal;font-weight:normal;font-size:18.6667px;line-height:1.25;font-family:sans-serif;fill:#000000;fill-opacity:1;stroke:none" + x="412.5184" + y="836.04877" + id="text64469-9-63"><tspan + sodipodi:role="line" + id="tspan64467-2-20" + x="412.5184" + y="836.04877" + style="font-size:18.6667px;text-align:center;text-anchor:middle">Shaper LUT</tspan><tspan + sodipodi:role="line" + x="412.5184" + y="859.38214" + style="font-size:18.6667px;text-align:center;text-anchor:middle" + id="tspan222533">RAM</tspan></text> + <text + xml:space="preserve" + style="font-style:normal;font-weight:normal;font-size:18.6667px;line-height:1.25;font-family:sans-serif;fill:#000000;fill-opacity:1;stroke:none" + x="413.54086" + y="908.61554" + id="text64469-9-61"><tspan + sodipodi:role="line" + id="tspan64467-2-55" + x="413.54086" + y="908.61554" + style="font-size:18.6667px;text-align:center;text-anchor:middle">3D LUT</tspan><tspan + sodipodi:role="line" + x="413.54086" + y="931.94891" + style="font-size:18.6667px;text-align:center;text-anchor:middle" + id="tspan221121">RAM</tspan></text> + <text + xml:space="preserve" + style="font-style:normal;font-weight:normal;font-size:18.6667px;line-height:1.25;font-family:sans-serif;fill:#000000;fill-opacity:1;stroke:none" + x="344.0347" + y="985.33319" + id="text64469-9-47"><tspan + sodipodi:role="line" + id="tspan64467-2-65" + x="344.0347" + y="985.33319" + style="font-size:18.6667px">Blend Gamma</tspan></text> + <text + xml:space="preserve" + style="font-style:normal;font-weight:normal;font-size:18.6667px;line-height:1.25;font-family:sans-serif;fill:#000000;fill-opacity:1;stroke:none" + x="433.84625" + y="1223.411" + id="text64469-9-69"><tspan + sodipodi:role="line" + id="tspan64467-2-37" + x="433.84625" + y="1223.411" + style="font-size:18.6667px">Blender</tspan></text> + <text + xml:space="preserve" + style="font-style:normal;font-weight:normal;font-size:18.6667px;line-height:1.25;font-family:sans-serif;fill:#000000;fill-opacity:1;stroke:none" + x="343.73291" + y="1290.2421" + id="text64469-9-45"><tspan + sodipodi:role="line" + id="tspan64467-2-25" + x="343.73291" + y="1290.2421" + style="font-size:18.6667px">Gamut Remap</tspan></text> + <text + xml:space="preserve" + style="font-style:normal;font-weight:normal;font-size:18.6667px;line-height:1.25;font-family:sans-serif;fill:#000000;fill-opacity:1;stroke:none" + x="408.74442" + y="1344.2428" + id="text64469-9-474"><tspan + sodipodi:role="line" + id="tspan64467-2-4" + x="408.74442" + y="1344.2428" + style="font-size:18.6667px;text-align:center;text-anchor:middle">Shaper LUT</tspan><tspan + sodipodi:role="line" + x="408.74442" + y="1367.5762" + style="font-size:18.6667px;text-align:center;text-anchor:middle" + id="tspan208303">RAM</tspan></text> + <text + xml:space="preserve" + style="font-style:normal;font-weight:normal;font-size:18.6667px;line-height:1.25;font-family:sans-serif;fill:#000000;fill-opacity:1;stroke:none" + x="407.1257" + y="1420.2435" + id="text64469-9-30"><tspan + sodipodi:role="line" + id="tspan64467-2-786" + x="407.1257" + y="1420.2435" + style="font-size:18.6667px;text-align:center;text-anchor:middle">3D LUT</tspan><tspan + sodipodi:role="line" + x="407.1257" + y="1443.5769" + style="font-size:18.6667px;text-align:center;text-anchor:middle" + id="tspan204749">RAM</tspan></text> + <text + xml:space="preserve" + style="font-style:normal;font-weight:normal;font-size:18.6667px;line-height:1.25;font-family:sans-serif;fill:#000000;fill-opacity:1;stroke:none" + x="408.64996" + y="1492.8102" + id="text64469-9-8"><tspan + sodipodi:role="line" + id="tspan64467-2-84" + x="408.64996" + y="1492.8102" + style="font-size:18.6667px;text-align:center;text-anchor:middle">Gamma</tspan><tspan + sodipodi:role="line" + x="408.64996" + y="1516.1436" + style="font-size:18.6667px;text-align:center;text-anchor:middle" + id="tspan197733">RAM</tspan></text> + <text + xml:space="preserve" + style="font-style:normal;font-weight:normal;font-size:18.6667px;line-height:1.25;font-family:sans-serif;fill:#000000;fill-opacity:1;stroke:none" + x="385.46863" + y="1575.2261" + id="text64469-9-31"><tspan + sodipodi:role="line" + id="tspan64467-2-49" + x="385.46863" + y="1575.2261" + style="font-size:18.6667px">OCSC</tspan></text> + <text + xml:space="preserve" + style="font-style:normal;font-weight:normal;font-size:40px;line-height:1.25;font-family:sans-serif;fill:#000000;fill-opacity:1;stroke:none" + x="1356.5106" + y="53.140579" + id="text273287"><tspan + sodipodi:role="line" + id="tspan273285" + x="1356.5106" + y="53.140579" /></text> + <rect + style="fill:#f9f7ed;fill-opacity:1;stroke:#000000;stroke-opacity:1" + id="rect1411" + width="177.28049" + height="38.940468" + x="1392.2576" + y="459.24118" /> + <text + xml:space="preserve" + style="font-style:normal;font-weight:normal;font-size:18.6667px;line-height:1.25;font-family:sans-serif;fill:#000000;fill-opacity:1;stroke:none" + x="1411.7203" + y="485.93231" + id="text78841"><tspan + sodipodi:role="line" + id="tspan78839" + x="1411.7203" + y="485.93231" + style="font-size:18.6667px">color_encoding</tspan></text> + <rect + style="fill:#f9f7ed;fill-opacity:1;stroke:#000000;stroke-opacity:1" + id="rect1515" + width="175.11876" + height="43.239407" + x="1393.7493" + y="525.6983" /> + <text + xml:space="preserve" + style="font-style:normal;font-weight:normal;font-size:17.3333px;line-height:1.25;font-family:sans-serif;fill:#000000;fill-opacity:1;stroke:none" + x="1399.212" + y="553.44904" + id="text78845"><tspan + sodipodi:role="line" + id="tspan78843" + x="1399.212" + y="553.44904">pixel_blend_mode</tspan></text> + <rect + style="fill:#f9f7ed;fill-opacity:1;stroke:#000000;stroke-opacity:1" + id="rect371322" + width="177.28049" + height="38.940468" + x="1391.6781" + y="385.61713" /> + <text + xml:space="preserve" + style="font-style:normal;font-weight:normal;font-size:18.6667px;line-height:1.25;font-family:sans-serif;fill:#000000;fill-opacity:1;stroke:none" + x="1427.5771" + y="409.29523" + id="text78837"><tspan + sodipodi:role="line" + id="tspan78835" + x="1427.5771" + y="409.29523" + style="font-size:18.6667px">color_range</tspan></text> + <path + d="m 1469.6815,1334.9145 c 3.2597,-1.4841 6.4827,-3.0444 9.7556,-4.5049 -3.5093,6.1834 -7.0396,12.3483 -10.5778,18.5131 -3.575,-6.178 -7.1683,-12.3481 -10.7354,-18.5314 3.3569,1.5025 6.685,3.0627 10.0367,4.5731 0,0 0,0 1.5209,-0.05 z" + id="path371636-7" + sodipodi:nodetypes="cccccc" + style="stroke-width:0.262672" + inkscape:transform-center-x="-416.72543" + inkscape:transform-center-y="-156.15191" /> + <path + d="m 1467.8882,1256.0056 c 3.2597,-1.4841 6.4827,-3.0443 9.7556,-4.5048 -3.5093,6.1833 -7.0396,12.3482 -10.5778,18.5131 -3.575,-6.178 -7.1683,-12.3482 -10.7354,-18.5315 3.3569,1.5025 6.685,3.0628 10.0367,4.5731 0,0 0,0 1.5209,-0.05 z" + id="path371636-7-2" + sodipodi:nodetypes="cccccc" + style="stroke-width:0.262672" + inkscape:transform-center-x="-416.72543" + inkscape:transform-center-y="-156.15191" /> + <path + d="m 1487.6154,441.80981 c 3.2597,-1.48411 6.4827,-3.04435 9.7556,-4.50482 -3.5093,6.18331 -7.0396,12.34823 -10.5778,18.51307 -3.575,-6.17798 -7.1683,-12.34815 -10.7354,-18.53146 3.3569,1.50251 6.685,3.06275 10.0367,4.57314 0,0 0,0 1.5209,-0.0499 z" + id="path371636-7-7" + sodipodi:nodetypes="cccccc" + style="stroke-width:0.262672" + inkscape:transform-center-x="-416.72543" + inkscape:transform-center-y="-156.15191" /> + <path + d="m 1489.4088,515.3385 c 3.2597,-1.48411 6.4827,-3.04435 9.7556,-4.50482 -3.5093,6.18331 -7.0396,12.34823 -10.5778,18.51307 -3.575,-6.17798 -7.1683,-12.34815 -10.7354,-18.53146 3.3569,1.50251 6.685,3.06275 10.0367,4.57314 0,0 0,0 1.5209,-0.0499 z" + id="path371636-7-22" + sodipodi:nodetypes="cccccc" + style="stroke-width:0.262672" + inkscape:transform-center-x="-416.72543" + inkscape:transform-center-y="-156.15191" /> + <path + d="m 400.8254,264.26491 c 3.2597,-1.48411 6.4827,-3.04435 9.7556,-4.50482 -3.5093,6.18331 -7.0396,12.34823 -10.5778,18.51307 -3.575,-6.17798 -7.1683,-12.34815 -10.7354,-18.53146 3.3569,1.50251 6.685,3.06275 10.0367,4.57314 0,0 0,0 1.5209,-0.0499 z" + id="path371636-7-6" + sodipodi:nodetypes="cccccc" + style="stroke-width:0.262672" + inkscape:transform-center-x="-416.72543" + inkscape:transform-center-y="-156.15191" /> + <path + d="m 402.6188,346.76052 c 3.2597,-1.48411 6.4827,-3.04435 9.7556,-4.50482 -3.5093,6.18331 -7.0396,12.34823 -10.5778,18.51307 -3.575,-6.17798 -7.1683,-12.34815 -10.7354,-18.53146 3.3569,1.50251 6.685,3.06275 10.0367,4.57314 0,0 0,0 1.5209,-0.0499 z" + id="path371636-7-1" + sodipodi:nodetypes="cccccc" + style="stroke-width:0.262672" + inkscape:transform-center-x="-416.72543" + inkscape:transform-center-y="-156.15191" /> + <path + d="m 404.2055,500.78482 c 3.2597,-1.48411 6.4827,-3.04435 9.7556,-4.50482 -3.5093,6.18331 -7.0396,12.34823 -10.5778,18.51307 -3.575,-6.17798 -7.1683,-12.34815 -10.7354,-18.53146 3.3569,1.50251 6.685,3.06275 10.0367,4.57314 0,0 0,0 1.5209,-0.0499 z" + id="path371636-7-0" + sodipodi:nodetypes="cccccc" + style="stroke-width:0.262672" + inkscape:transform-center-x="-416.72543" + inkscape:transform-center-y="-156.15191" /> + <path + d="m 402.6188,581.69367 c 3.2597,-1.48411 6.4827,-3.04435 9.7556,-4.50482 -3.5093,6.18331 -7.0396,12.34823 -10.5778,18.51307 -3.575,-6.17798 -7.1683,-12.34815 -10.7354,-18.53146 3.3569,1.50251 6.685,3.06275 10.0367,4.57314 0,0 0,0 1.5209,-0.0499 z" + id="path371636-7-61" + sodipodi:nodetypes="cccccc" + style="stroke-width:0.262672" + inkscape:transform-center-x="-416.72543" + inkscape:transform-center-y="-156.15191" /> + <path + d="m 402.6188,658.80913 c 3.2597,-1.48411 6.4827,-3.04435 9.7556,-4.50482 -3.5093,6.18331 -7.0396,12.34823 -10.5778,18.51307 -3.575,-6.17798 -7.1683,-12.34815 -10.7354,-18.53146 3.3569,1.50251 6.685,3.06275 10.0367,4.57314 0,0 0,0 1.5209,-0.0499 z" + id="path371636-7-5" + sodipodi:nodetypes="cccccc" + style="stroke-width:0.262672" + inkscape:transform-center-x="-416.72543" + inkscape:transform-center-y="-156.15191" /> + <path + d="m 402.6188,732.33782 c 3.2597,-1.48411 6.4827,-3.04435 9.7556,-4.50482 -3.5093,6.18331 -7.0396,12.34823 -10.5778,18.51307 -3.575,-6.17798 -7.1683,-12.34815 -10.7354,-18.53146 3.3569,1.50251 6.685,3.06275 10.0367,4.57314 0,0 0,0 1.5209,-0.0499 z" + id="path371636-7-9" + sodipodi:nodetypes="cccccc" + style="stroke-width:0.262672" + inkscape:transform-center-x="-416.72543" + inkscape:transform-center-y="-156.15191" /> + <path + d="m 402.4121,800.48637 c 3.2597,-1.48411 6.4827,-3.04435 9.7556,-4.50482 -3.5093,6.18331 -7.0396,12.34823 -10.5778,18.51307 -3.575,-6.17798 -7.1683,-12.34815 -10.7354,-18.53146 3.3569,1.50251 6.685,3.06275 10.0367,4.57314 0,0 0,0 1.5209,-0.0499 z" + id="path371636-7-4" + sodipodi:nodetypes="cccccc" + style="stroke-width:0.262672" + inkscape:transform-center-x="-416.72543" + inkscape:transform-center-y="-156.15191" /> + <path + d="m 402.2055,875.80845 c 3.2597,-1.48411 6.4827,-3.04435 9.7556,-4.50482 -3.5093,6.18331 -7.0396,12.34823 -10.5778,18.51307 -3.575,-6.17798 -7.1683,-12.34815 -10.7354,-18.53146 3.3569,1.50251 6.685,3.06275 10.0367,4.57314 0,0 0,0 1.5209,-0.0499 z" + id="path371636-7-90" + sodipodi:nodetypes="cccccc" + style="stroke-width:0.262672" + inkscape:transform-center-x="-416.72543" + inkscape:transform-center-y="-156.15191" /> + <path + d="m 400.4121,942.16362 c 3.2597,-1.48411 6.4827,-3.04435 9.7556,-4.50482 -3.5093,6.18331 -7.0396,12.34823 -10.5778,18.51307 -3.575,-6.17798 -7.1683,-12.34815 -10.7354,-18.53146 3.3569,1.50251 6.685,3.06275 10.0367,4.57314 0,0 0,0 1.5209,-0.0499 z" + id="path371636-7-91" + sodipodi:nodetypes="cccccc" + style="stroke-width:0.262672" + inkscape:transform-center-x="-416.72543" + inkscape:transform-center-y="-156.15191" /> + <path + d="m 407.9989,1311.6005 c 3.2597,-1.4841 6.4827,-3.0444 9.7556,-4.5048 -3.5093,6.1833 -7.0396,12.3482 -10.5778,18.513 -3.575,-6.1779 -7.1683,-12.3481 -10.7354,-18.5314 3.3569,1.5025 6.685,3.0627 10.0367,4.5731 0,0 0,0 1.5209,-0.05 z" + id="path371636-7-77" + sodipodi:nodetypes="cccccc" + style="stroke-width:0.262672" + inkscape:transform-center-x="-416.72543" + inkscape:transform-center-y="-156.15191" /> + <path + d="m 407.9989,1381.5424 c 3.2597,-1.4841 6.4827,-3.0443 9.7556,-4.5048 -3.5093,6.1833 -7.0396,12.3482 -10.5778,18.5131 -3.575,-6.178 -7.1683,-12.3482 -10.7354,-18.5315 3.3569,1.5025 6.685,3.0627 10.0367,4.5731 0,0 0,0 1.5209,-0.05 z" + id="path371636-7-11" + sodipodi:nodetypes="cccccc" + style="stroke-width:0.262672" + inkscape:transform-center-x="-416.72543" + inkscape:transform-center-y="-156.15191" /> + <path + d="m 407.9989,1458.6579 c 3.2597,-1.4841 6.4827,-3.0444 9.7556,-4.5049 -3.5093,6.1834 -7.0396,12.3483 -10.5778,18.5131 -3.575,-6.178 -7.1683,-12.3481 -10.7354,-18.5314 3.3569,1.5025 6.685,3.0627 10.0367,4.5731 0,0 0,0 1.5209,-0.05 z" + id="path371636-7-59" + sodipodi:nodetypes="cccccc" + style="stroke-width:0.262672" + inkscape:transform-center-x="-416.72543" + inkscape:transform-center-y="-156.15191" /> + </g> +</svg> diff --git a/Documentation/gpu/amdgpu/display/display-manager.rst b/Documentation/gpu/amdgpu/display/display-manager.rst index 7ce31f89d9a0..b7abb18cfc82 100644 --- a/Documentation/gpu/amdgpu/display/display-manager.rst +++ b/Documentation/gpu/amdgpu/display/display-manager.rst @@ -40,3 +40,144 @@ Atomic Implementation .. kernel-doc:: drivers/gpu/drm/amd/display/amdgpu_dm/amdgpu_dm.c :functions: amdgpu_dm_atomic_check amdgpu_dm_atomic_commit_tail + +Color Management Properties +=========================== + +.. kernel-doc:: drivers/gpu/drm/amd/display/amdgpu_dm/amdgpu_dm_color.c + :doc: overview + +.. kernel-doc:: drivers/gpu/drm/amd/display/amdgpu_dm/amdgpu_dm_color.c + :internal: + + +DC Color Capabilities between DCN generations +--------------------------------------------- + +DRM/KMS framework defines three CRTC color correction properties: degamma, +color transformation matrix (CTM) and gamma, and two properties for degamma and +gamma LUT sizes. AMD DC programs some of the color correction features +pre-blending but DRM/KMS has not per-plane color correction properties. + +In general, the DRM CRTC color properties are programmed to DC, as follows: +CRTC gamma after blending, and CRTC degamma pre-blending. Although CTM is +programmed after blending, it is mapped to DPP hw blocks (pre-blending). Other +color caps available in the hw is not currently exposed by DRM interface and +are bypassed. + +.. kernel-doc:: drivers/gpu/drm/amd/display/dc/dc.h + :doc: color-management-caps + +.. kernel-doc:: drivers/gpu/drm/amd/display/dc/dc.h + :internal: + +The color pipeline has undergone major changes between DCN hardware +generations. What's possible to do before and after blending depends on +hardware capabilities, as illustrated below by the DCN 2.0 and DCN 3.0 families +schemas. + +**DCN 2.0 family color caps and mapping** + +.. kernel-figure:: dcn2_cm_drm_current.svg + +**DCN 3.0 family color caps and mapping** + +.. kernel-figure:: dcn3_cm_drm_current.svg + +Blend Mode Properties +===================== + +Pixel blend mode is a DRM plane composition property of :c:type:`drm_plane` used to +describes how pixels from a foreground plane (fg) are composited with the +background plane (bg). Here, we present main concepts of DRM blend mode to help +to understand how this property is mapped to AMD DC interface. See more about +this DRM property and the alpha blending equations in :ref:`DRM Plane +Composition Properties <plane_composition_properties>`. + +Basically, a blend mode sets the alpha blending equation for plane +composition that fits the mode in which the alpha channel affects the state of +pixel color values and, therefore, the resulted pixel color. For +example, consider the following elements of the alpha blending equation: + +- *fg.rgb*: Each of the RGB component values from the foreground's pixel. +- *fg.alpha*: Alpha component value from the foreground's pixel. +- *bg.rgb*: Each of the RGB component values from the background. +- *plane_alpha*: Plane alpha value set by the **plane "alpha" property**, see + more in :ref:`DRM Plane Composition Properties <plane_composition_properties>`. + +in the basic alpha blending equation:: + + out.rgb = alpha * fg.rgb + (1 - alpha) * bg.rgb + +the alpha channel value of each pixel in a plane is ignored and only the plane +alpha affects the resulted pixel color values. + +DRM has three blend mode to define the blend formula in the plane composition: + +* **None**: Blend formula that ignores the pixel alpha. + +* **Pre-multiplied**: Blend formula that assumes the pixel color values in a + plane was already pre-multiplied by its own alpha channel before storage. + +* **Coverage**: Blend formula that assumes the pixel color values were not + pre-multiplied with the alpha channel values. + +and pre-multiplied is the default pixel blend mode, that means, when no blend +mode property is created or defined, DRM considers the plane's pixels has +pre-multiplied color values. On IGT GPU tools, the kms_plane_alpha_blend test +provides a set of subtests to verify plane alpha and blend mode properties. + +The DRM blend mode and its elements are then mapped by AMDGPU display manager +(DM) to program the blending configuration of the Multiple Pipe/Plane Combined +(MPC), as follows: + +.. kernel-doc:: drivers/gpu/drm/amd/display/dc/inc/hw/mpc.h + :doc: mpc-overview + +.. kernel-doc:: drivers/gpu/drm/amd/display/dc/inc/hw/mpc.h + :functions: mpcc_blnd_cfg + +Therefore, the blending configuration for a single MPCC instance on the MPC +tree is defined by :c:type:`mpcc_blnd_cfg`, where +:c:type:`pre_multiplied_alpha` is the alpha pre-multiplied mode flag used to +set :c:type:`MPCC_ALPHA_MULTIPLIED_MODE`. It controls whether alpha is +multiplied (true/false), being only true for DRM pre-multiplied blend mode. +:c:type:`mpcc_alpha_blend_mode` defines the alpha blend mode regarding pixel +alpha and plane alpha values. It sets one of the three modes for +:c:type:`MPCC_ALPHA_BLND_MODE`, as described below. + +.. kernel-doc:: drivers/gpu/drm/amd/display/dc/inc/hw/mpc.h + :functions: mpcc_alpha_blend_mode + +DM then maps the elements of `enum mpcc_alpha_blend_mode` to those in the DRM +blend formula, as follows: + +* *MPC pixel alpha* matches *DRM fg.alpha* as the alpha component value + from the plane's pixel +* *MPC global alpha* matches *DRM plane_alpha* when the pixel alpha should + be ignored and, therefore, pixel values are not pre-multiplied +* *MPC global gain* assumes *MPC global alpha* value when both *DRM + fg.alpha* and *DRM plane_alpha* participate in the blend equation + +In short, *fg.alpha* is ignored by selecting +:c:type:`MPCC_ALPHA_BLEND_MODE_GLOBAL_ALPHA`. On the other hand, (plane_alpha * +fg.alpha) component becomes available by selecting +:c:type:`MPCC_ALPHA_BLEND_MODE_PER_PIXEL_ALPHA_COMBINED_GLOBAL_GAIN`. And the +:c:type:`MPCC_ALPHA_MULTIPLIED_MODE` defines if the pixel color values are +pre-multiplied by alpha or not. + +Blend configuration flow +------------------------ + +The alpha blending equation is configured from DRM to DC interface by the +following path: + +1. When updating a :c:type:`drm_plane_state <drm_plane_state>`, DM calls + :c:type:`fill_blending_from_plane_state()` that maps + :c:type:`drm_plane_state <drm_plane_state>` attributes to + :c:type:`dc_plane_info <dc_plane_info>` struct to be handled in the + OS-agnostic component (DC). + +2. On DC interface, :c:type:`struct mpcc_blnd_cfg <mpcc_blnd_cfg>` programs the + MPCC blend configuration considering the :c:type:`dc_plane_info + <dc_plane_info>` input from DPP. diff --git a/Documentation/gpu/amdgpu/display/index.rst b/Documentation/gpu/amdgpu/display/index.rst index c1fb2fb3c710..f8a4f53d70d8 100644 --- a/Documentation/gpu/amdgpu/display/index.rst +++ b/Documentation/gpu/amdgpu/display/index.rst @@ -28,4 +28,5 @@ table of content: display-manager.rst dc-debug.rst dcn-overview.rst + mpo-overview.rst dc-glossary.rst diff --git a/Documentation/gpu/amdgpu/display/mpo-cursor.svg b/Documentation/gpu/amdgpu/display/mpo-cursor.svg new file mode 100644 index 000000000000..9d9de76847c3 --- /dev/null +++ b/Documentation/gpu/amdgpu/display/mpo-cursor.svg @@ -0,0 +1,435 @@ +<?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="160.5318mm" + height="65.443306mm" + viewBox="0 0 160.5318 65.443308" + version="1.1" + id="svg843" + inkscape:version="0.92.5 (2060ec1f9f, 2020-04-08)" + sodipodi:docname="mpo-cursor.svg"> + <defs + id="defs837"> + <marker + inkscape:stockid="Arrow1Send" + orient="auto" + refY="0" + refX="0" + id="Arrow1Send" + style="overflow:visible" + inkscape:isstock="true"> + <path + id="path1568" + 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="Arrow1Mend" + orient="auto" + refY="0" + refX="0" + id="Arrow1Mend" + style="overflow:visible" + inkscape:isstock="true"> + <path + id="path1562" + 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.4,0,0,-0.4,-4,0)" + inkscape:connector-curvature="0" /> + </marker> + <marker + inkscape:stockid="Arrow2Mend" + orient="auto" + refY="0" + refX="0" + id="marker1837" + style="overflow:visible" + inkscape:isstock="true"> + <path + id="path1835" + 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="scale(-0.6)" + 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="path1580" + 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="scale(-0.6)" + inkscape:connector-curvature="0" /> + </marker> + <marker + inkscape:stockid="Arrow1Send" + orient="auto" + refY="0" + refX="0" + id="Arrow1Send-7" + style="overflow:visible" + inkscape:isstock="true"> + <path + inkscape:connector-curvature="0" + id="path1568-5" + 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)" /> + </marker> + <marker + inkscape:stockid="Arrow1Send" + orient="auto" + refY="0" + refX="0" + id="Arrow1Send-7-2" + style="overflow:visible" + inkscape:isstock="true"> + <path + inkscape:connector-curvature="0" + id="path1568-5-2" + 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)" /> + </marker> + <marker + inkscape:stockid="Arrow1Send" + orient="auto" + refY="0" + refX="0" + id="Arrow1Send-9" + style="overflow:visible" + inkscape:isstock="true"> + <path + inkscape:connector-curvature="0" + id="path1568-7" + 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)" /> + </marker> + <marker + inkscape:stockid="Arrow1Send" + orient="auto" + refY="0" + refX="0" + id="Arrow1Send-9-6" + style="overflow:visible" + inkscape:isstock="true"> + <path + inkscape:connector-curvature="0" + id="path1568-7-1" + 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)" /> + </marker> + <marker + inkscape:stockid="Arrow1Send" + orient="auto" + refY="0" + refX="0" + id="Arrow1Send-9-6-9" + style="overflow:visible" + inkscape:isstock="true"> + <path + inkscape:connector-curvature="0" + id="path1568-7-1-3" + 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)" /> + </marker> + </defs> + <sodipodi:namedview + id="base" + pagecolor="#ffffff" + bordercolor="#666666" + borderopacity="1.0" + inkscape:pageopacity="0.0" + inkscape:pageshadow="2" + inkscape:zoom="0.35" + inkscape:cx="895.68984" + inkscape:cy="-284.87808" + inkscape:document-units="mm" + inkscape:current-layer="g1433-6" + showgrid="false" + inkscape:window-width="2560" + inkscape:window-height="1376" + 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" /> + <metadata + id="metadata840"> + <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(70.035531,-11.72001)"> + <g + id="g1438" + transform="matrix(0.33108827,0,0,0.33108827,-46.847588,7.8396545)"> + <rect + y="51.228218" + x="-69.09626" + height="34.773811" + width="66.523811" + id="rect1388" + style="fill:none;fill-opacity:1;stroke:#000000;stroke-width:1.87854159;stroke-linecap:butt;stroke-linejoin:bevel;stroke-miterlimit:4;stroke-dasharray:none;stroke-dashoffset:0" /> + <text + id="text1392" + y="73.238098" + x="-59.718166" + 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" + xml:space="preserve"><tspan + style="font-weight:bold;font-size:12.69999981px;stroke-width:0.26458332" + y="73.238098" + x="-59.718166" + id="tspan1390" + sodipodi:role="line">Cursor</tspan></text> + </g> + <g + id="g1433" + transform="matrix(0.33108827,0,0,0.33108827,-49.701591,6.5552955)"> + <rect + y="116.32738" + x="-60.476192" + height="34.773811" + width="66.523811" + id="rect1388-3" + style="fill:none;fill-opacity:1;stroke:#000000;stroke-width:1.87854159;stroke-linecap:butt;stroke-linejoin:bevel;stroke-miterlimit:4;stroke-dasharray:none;stroke-dashoffset:0" /> + <text + id="text1392-6" + y="138.44888" + x="-53.932037" + 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" + xml:space="preserve"><tspan + style="font-weight:bold;font-size:12.69999981px;stroke-width:0.26458332" + y="138.44888" + x="-53.932037" + id="tspan1390-7" + sodipodi:role="line">Plane 1</tspan></text> + </g> + <g + id="g1428" + transform="matrix(0.33108827,0,0,0.33108827,-46.847588,7.8396518)"> + <rect + y="173.66814" + x="-69.09626" + height="34.773811" + width="66.523811" + id="rect1388-5" + style="fill:none;fill-opacity:1;stroke:#000000;stroke-width:1.87854159;stroke-linecap:butt;stroke-linejoin:bevel;stroke-miterlimit:4;stroke-dasharray:none;stroke-dashoffset:0" /> + <text + id="text1392-3" + y="195.78964" + x="-62.437382" + 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" + xml:space="preserve"><tspan + style="font-weight:bold;font-size:12.69999981px;stroke-width:0.26458332" + y="195.78964" + x="-62.437382" + id="tspan1390-5" + sodipodi:role="line">Plane 2</tspan></text> + </g> + <g + id="g1433-6" + transform="translate(116.41667,-9.0714256)"> + <g + id="g1467" + transform="matrix(0.33108827,0,0,0.33108827,-132.72925,15.626721)"> + <rect + style="fill:none;fill-opacity:1;stroke:#000000;stroke-width:1.87854159;stroke-linecap:butt;stroke-linejoin:bevel;stroke-miterlimit:4;stroke-dasharray:none;stroke-dashoffset:0" + id="rect1388-3-2" + width="66.523811" + height="34.773811" + x="-60.476192" + y="116.32738" /> + <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="-45.380619" + y="138.33725" + id="text1392-6-9"><tspan + sodipodi:role="line" + id="tspan1390-7-1" + x="-45.380619" + y="138.33725" + style="font-weight:bold;font-size:12.69999981px;stroke-width:0.26458332">CRTC</tspan></text> + </g> + <g + id="g1438-2" + transform="matrix(0.33108827,0,0,0.33108827,-92.282164,27.16881)"> + <rect + y="51.228218" + x="-69.09626" + height="34.773811" + width="66.523811" + id="rect1388-7" + style="fill:none;fill-opacity:1;stroke:#000000;stroke-width:1.87854159;stroke-linecap:butt;stroke-linejoin:bevel;stroke-miterlimit:4;stroke-dasharray:none;stroke-dashoffset:0" /> + <text + id="text1392-0" + y="73.238098" + x="-59.718166" + 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" + xml:space="preserve"><tspan + style="font-weight:bold;font-size:12.69999981px;stroke-width:0.26458332" + y="73.238098" + x="-59.718166" + id="tspan1390-9" + sodipodi:role="line">Cursor</tspan></text> + </g> + <g + id="g1433-3" + transform="matrix(0.33108827,0,0,0.33108827,-61.59731,5.6152398)"> + <rect + y="116.32738" + x="-60.476192" + height="34.773811" + width="66.523811" + id="rect1388-3-6" + style="fill:none;fill-opacity:1;stroke:#000000;stroke-width:1.87854159;stroke-linecap:butt;stroke-linejoin:bevel;stroke-miterlimit:4;stroke-dasharray:none;stroke-dashoffset:0" /> + <text + id="text1392-6-0" + y="138.44888" + x="-53.932037" + 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" + xml:space="preserve"><tspan + style="font-weight:bold;font-size:12.69999981px;stroke-width:0.26458332" + y="138.44888" + x="-53.932037" + id="tspan1390-7-6" + sodipodi:role="line">Plane 1</tspan></text> + </g> + <g + id="g1428-2" + transform="matrix(0.33108827,0,0,0.33108827,-58.743296,6.7994816)"> + <rect + y="173.66814" + x="-69.09626" + height="34.773811" + width="66.523811" + id="rect1388-5-6" + style="fill:none;fill-opacity:1;stroke:#000000;stroke-width:1.87854159;stroke-linecap:butt;stroke-linejoin:bevel;stroke-miterlimit:4;stroke-dasharray:none;stroke-dashoffset:0" /> + <text + id="text1392-3-1" + y="195.78964" + x="-62.437382" + 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" + xml:space="preserve"><tspan + style="font-weight:bold;font-size:12.69999981px;stroke-width:0.26458332" + y="195.78964" + x="-62.437382" + id="tspan1390-5-8" + sodipodi:role="line">Plane 2</tspan></text> + </g> + <g + id="g1467-7" + transform="matrix(0.33108827,0,0,0.33108827,-28.233674,5.6152398)"> + <rect + style="fill:none;fill-opacity:1;stroke:#000000;stroke-width:1.87854159;stroke-linecap:butt;stroke-linejoin:bevel;stroke-miterlimit:4;stroke-dasharray:none;stroke-dashoffset:0" + id="rect1388-3-2-9" + width="66.523811" + height="34.773811" + x="-60.476192" + y="116.32738" /> + <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="-45.380619" + y="138.33725" + id="text1392-6-9-2"><tspan + sodipodi:role="line" + id="tspan1390-7-1-0" + x="-45.380619" + y="138.33725" + style="font-weight:bold;font-size:12.69999981px;stroke-width:0.26458332">CRTC</tspan></text> + </g> + <text + xml:space="preserve" + style="font-style:normal;font-weight:normal;font-size:1.05120528px;line-height:1.25;font-family:sans-serif;letter-spacing:0px;word-spacing:0px;fill:#000000;fill-opacity:1;stroke:none;stroke-width:0.08760043" + x="-164.26541" + y="24.302296" + id="text1531"><tspan + sodipodi:role="line" + id="tspan1529" + x="-164.26541" + y="24.302296" + style="font-weight:bold;font-size:4.6720233px;stroke-width:0.08760043">DRM</tspan></text> + <text + xml:space="preserve" + style="font-style:normal;font-weight:normal;font-size:1.05120528px;line-height:1.25;font-family:sans-serif;letter-spacing:0px;word-spacing:0px;fill:#000000;fill-opacity:1;stroke:none;stroke-width:0.08760043" + x="-89.233742" + y="24.341078" + id="text1531-2"><tspan + sodipodi:role="line" + id="tspan1529-3" + x="-89.233742" + y="24.341078" + style="font-weight:bold;font-size:4.6720233px;stroke-width:0.08760043">AMD Hardware</tspan></text> + <path + style="fill:none;stroke:#000000;stroke-width:1.53318286;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:none;stroke-opacity:1;marker-end:url(#Arrow1Send)" + d="m -164.26541,39.407343 h 20.27325 v 11.262913" + id="path1551" + inkscape:connector-curvature="0" + sodipodi:nodetypes="ccc" /> + <path + style="fill:none;stroke:#000000;stroke-width:1.53318286;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:none;stroke-opacity:1;marker-end:url(#Arrow1Send-7)" + d="m -164.11597,80.385815 h 20.27325 v -11.26291" + id="path1551-9" + inkscape:connector-curvature="0" + sodipodi:nodetypes="ccc" /> + <path + style="fill:none;stroke:#000000;stroke-width:1.53318286;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:none;stroke-opacity:1;marker-end:url(#Arrow1Send-7-2)" + d="m -59.24211,70.452123 h 20.273243 V 59.18921" + id="path1551-9-8" + inkscape:connector-curvature="0" + sodipodi:nodetypes="ccc" /> + <path + style="fill:none;stroke:#000000;stroke-width:1.53318286;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:none;stroke-opacity:1;marker-end:url(#Arrow1Send-9)" + d="m -163.61178,59.821549 h 9.26062" + id="path1551-3" + inkscape:connector-curvature="0" + sodipodi:nodetypes="cc" /> + <path + style="fill:none;stroke:#000000;stroke-width:1.53318286;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:none;stroke-opacity:1;marker-end:url(#Arrow1Send-9-6)" + d="m -93.426241,50.16968 h 9.260617" + id="path1551-3-2" + inkscape:connector-curvature="0" + sodipodi:nodetypes="cc" /> + <path + style="fill:none;stroke:#000000;stroke-width:1.53318286;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:none;stroke-opacity:1;marker-end:url(#Arrow1Send-9-6-9)" + d="m -59.637503,50.169684 h 9.260618" + id="path1551-3-2-1" + inkscape:connector-curvature="0" + sodipodi:nodetypes="cc" /> + </g> + </g> +</svg> diff --git a/Documentation/gpu/amdgpu/display/mpo-overview.rst b/Documentation/gpu/amdgpu/display/mpo-overview.rst new file mode 100644 index 000000000000..0499aa92d08d --- /dev/null +++ b/Documentation/gpu/amdgpu/display/mpo-overview.rst @@ -0,0 +1,242 @@ +======================== +Multiplane Overlay (MPO) +======================== + +.. note:: You will get more from this page if you have already read the + 'Documentation/gpu/amdgpu/display/dcn-overview.rst'. + + +Multiplane Overlay (MPO) allows for multiple framebuffers to be composited via +fixed-function hardware in the display controller rather than using graphics or +compute shaders for composition. This can yield some power savings if it means +the graphics/compute pipelines can be put into low-power states. In summary, +MPO can bring the following benefits: + +* Decreased GPU and CPU workload - no composition shaders needed, no extra + buffer copy needed, GPU can remain idle. +* Plane independent page flips - No need to be tied to global compositor + page-flip present rate, reduced latency, independent timing. + +.. note:: Keep in mind that MPO is all about power-saving; if you want to learn + more about power-save in the display context, check the link: + `Power <https://gitlab.freedesktop.org/pq/color-and-hdr/-/blob/main/doc/power.rst>`__. + +Multiplane Overlay is only available using the DRM atomic model. The atomic +model only uses a single userspace IOCTL for configuring the display hardware +(modesetting, page-flipping, etc) - drmModeAtomicCommit. To query hardware +resources and limitations userspace also calls into drmModeGetResources which +reports back the number of planes, CRTCs, and connectors. There are three types +of DRM planes that the driver can register and work with: + +* ``DRM_PLANE_TYPE_PRIMARY``: Primary planes represent a "main" plane for a + CRTC, primary planes are the planes operated upon by CRTC modesetting and + flipping operations. +* ``DRM_PLANE_TYPE_CURSOR``: Cursor planes represent a "cursor" plane for a + CRTC. Cursor planes are the planes operated upon by the cursor IOCTLs +* ``DRM_PLANE_TYPE_OVERLAY``: Overlay planes represent all non-primary, + non-cursor planes. Some drivers refer to these types of planes as "sprites" + internally. + +To illustrate how it works, let's take a look at a device that exposes the +following planes to userspace: + +* 4 Primary planes (1 per CRTC). +* 4 Cursor planes (1 per CRTC). +* 1 Overlay plane (shared among CRTCs). + +.. note:: Keep in mind that different ASICs might expose other numbers of + planes. + +For this hardware example, we have 4 pipes (if you don't know what AMD pipe +means, look at 'Documentation/gpu/amdgpu/display/dcn-overview.rst', section +"AMD Hardware Pipeline"). Typically most AMD devices operate in a pipe-split +configuration for optimal single display output (e.g., 2 pipes per plane). + +A typical MPO configuration from userspace - 1 primary + 1 overlay on a single +display - will see 4 pipes in use, 2 per plane. + +At least 1 pipe must be used per plane (primary and overlay), so for this +hypothetical hardware that we are using as an example, we have an absolute +limit of 4 planes across all CRTCs. Atomic commits will be rejected for display +configurations using more than 4 planes. Again, it is important to stress that +every DCN has different restrictions; here, we are just trying to provide the +concept idea. + +Plane Restrictions +================== + +AMDGPU imposes restrictions on the use of DRM planes in the driver. + +Atomic commits will be rejected for commits which do not follow these +restrictions: + +* Overlay planes must be in ARGB8888 or XRGB8888 format +* Planes cannot be placed outside of the CRTC destination rectangle +* Planes cannot be downscaled more than 1/4x of their original size +* Planes cannot be upscaled more than 16x of their original size + +Not every property is available on every plane: + +* Only primary planes have color-space and non-RGB format support +* Only overlay planes have alpha blending support + +Cursor Restrictions +=================== + +Before we start to describe some restrictions around cursor and MPO, see the +below image: + +.. kernel-figure:: mpo-cursor.svg + +The image on the left side represents how DRM expects the cursor and planes to +be blended. However, AMD hardware handles cursors differently, as you can see +on the right side; basically, our cursor cannot be drawn outside its associated +plane as it is being treated as part of the plane. Another consequence of that +is that cursors inherit the color and scale from the plane. + +As a result of the above behavior, do not use legacy API to set up the cursor +plane when working with MPO; otherwise, you might encounter unexpected +behavior. + +In short, AMD HW has no dedicated cursor planes. A cursor is attached to +another plane and therefore inherits any scaling or color processing from its +parent plane. + +Use Cases +========= + +Picture-in-Picture (PIP) playback - Underlay strategy +----------------------------------------------------- + +Video playback should be done using the "primary plane as underlay" MPO +strategy. This is a 2 planes configuration: + +* 1 YUV DRM Primary Plane (e.g. NV12 Video) +* 1 RGBA DRM Overlay Plane (e.g. ARGB8888 desktop). The compositor should + prepare the framebuffers for the planes as follows: + - The overlay plane contains general desktop UI, video player controls, and video subtitles + - Primary plane contains one or more videos + +.. note:: Keep in mind that we could extend this configuration to more planes, + but that is currently not supported by our driver yet (maybe if we have a + userspace request in the future, we can change that). + +See below a single-video example: + +.. kernel-figure:: single-display-mpo.svg + +.. note:: We could extend this behavior to more planes, but that is currently + not supported by our driver. + +The video buffer should be used directly for the primary plane. The video can +be scaled and positioned for the desktop using the properties: CRTC_X, CRTC_Y, +CRTC_W, and CRTC_H. The primary plane should also have the color encoding and +color range properties set based on the source content: + +* ``COLOR_RANGE``, ``COLOR_ENCODING`` + +The overlay plane should be the native size of the CRTC. The compositor must +draw a transparent cutout for where the video should be placed on the desktop +(i.e., set the alpha to zero). The primary plane video will be visible through +the underlay. The overlay plane's buffer may remain static while the primary +plane's framebuffer is used for standard double-buffered playback. + +The compositor should create a YUV buffer matching the native size of the CRTC. +Each video buffer should be composited onto this YUV buffer for direct YUV +scanout. The primary plane should have the color encoding and color range +properties set based on the source content: ``COLOR_RANGE``, +``COLOR_ENCODING``. However, be mindful that the source color space and +encoding match for each video since it affect the entire plane. + +The overlay plane should be the native size of the CRTC. The compositor must +draw a transparent cutout for where each video should be placed on the desktop +(i.e., set the alpha to zero). The primary plane videos will be visible through +the underlay. The overlay plane's buffer may remain static while compositing +operations for video playback will be done on the video buffer. + +This kernel interface is validated using IGT GPU Tools. The following tests can +be run to validate positioning, blending, scaling under a variety of sequences +and interactions with operations such as DPMS and S3: + +- ``kms_plane@plane-panning-bottom-right-pipe-*-planes`` +- ``kms_plane@plane-panning-bottom-right-suspend-pipe-*-`` +- ``kms_plane@plane-panning-top-left-pipe-*-`` +- ``kms_plane@plane-position-covered-pipe-*-`` +- ``kms_plane@plane-position-hole-dpms-pipe-*-`` +- ``kms_plane@plane-position-hole-pipe-*-`` +- ``kms_plane_multiple@atomic-pipe-*-tiling-`` +- ``kms_plane_scaling@pipe-*-plane-scaling`` +- ``kms_plane_alpha_blend@pipe-*-alpha-basic`` +- ``kms_plane_alpha_blend@pipe-*-alpha-transparant-fb`` +- ``kms_plane_alpha_blend@pipe-*-alpha-opaque-fb`` +- ``kms_plane_alpha_blend@pipe-*-constant-alpha-min`` +- ``kms_plane_alpha_blend@pipe-*-constant-alpha-mid`` +- ``kms_plane_alpha_blend@pipe-*-constant-alpha-max`` + +Multiple Display MPO +-------------------- + +AMDGPU supports display MPO when using multiple displays; however, this feature +behavior heavily relies on the compositor implementation. Keep in mind that +usespace can define different policies. For example, some OSes can use MPO to +protect the plane that handles the video playback; notice that we don't have +many limitations for a single display. Nonetheless, this manipulation can have +many more restrictions for a multi-display scenario. The below example shows a +video playback in the middle of two displays, and it is up to the compositor to +define a policy on how to handle it: + +.. kernel-figure:: multi-display-hdcp-mpo.svg + +Let's discuss some of the hardware limitations we have when dealing with +multi-display with MPO. + +Limitations +~~~~~~~~~~~ + +For simplicity's sake, for discussing the hardware limitation, this +documentation supposes an example where we have two displays and video playback +that will be moved around different displays. + +* **Hardware limitations** + +From the DCN overview page, each display requires at least one pipe and each +MPO plane needs another pipe. As a result, when the video is in the middle of +the two displays, we need to use 2 pipes. See the example below where we avoid +pipe split: + +- 1 display (1 pipe) + MPO (1 pipe), we will use two pipes +- 2 displays (2 pipes) + MPO (1-2 pipes); we will use 4 pipes. MPO in the + middle of both displays needs 2 pipes. +- 3 Displays (3 pipes) + MPO (1-2 pipes), we need 5 pipes. + +If we use MPO with multiple displays, the userspace has to decide to enable +multiple MPO by the price of limiting the number of external displays supported +or disable it in favor of multiple displays; it is a policy decision. For +example: + +* When ASIC has 3 pipes, AMD hardware can NOT support 2 displays with MPO +* When ASIC has 4 pipes, AMD hardware can NOT support 3 displays with MPO + +Let's briefly explore how userspace can handle these two display configurations +on an ASIC that only supports three pipes. We can have: + +.. kernel-figure:: multi-display-hdcp-mpo-less-pipe-ex.svg + +- Total pipes are 3 +- User lights up 2 displays (2 out of 3 pipes are used) +- User launches video (1 pipe used for MPO) +- Now, if the user moves the video in the middle of 2 displays, one part of the + video won't be MPO since we have used 3/3 pipes. + +* **Scaling limitation** + +MPO cannot handle scaling less than 0.25 and more than x16. For example: + +If 4k video (3840x2160) is playing in windowed mode, the physical size of the +window cannot be smaller than (960x540). + +.. note:: These scaling limitations might vary from ASIC to ASIC. + +* **Size Limitation** + +The minimum MPO size is 12px. diff --git a/Documentation/gpu/amdgpu/display/multi-display-hdcp-mpo-less-pipe-ex.svg b/Documentation/gpu/amdgpu/display/multi-display-hdcp-mpo-less-pipe-ex.svg new file mode 100644 index 000000000000..6d06b39e83fa --- /dev/null +++ b/Documentation/gpu/amdgpu/display/multi-display-hdcp-mpo-less-pipe-ex.svg @@ -0,0 +1,220 @@ +<?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="103.08798mm" + height="30.335283mm" + viewBox="0 0 103.08798 30.335284" + version="1.1" + id="svg8" + inkscape:version="0.92.5 (2060ec1f9f, 2020-04-08)" + sodipodi:docname="multi-display-hdcp-mpo-less-pipe-ex.svg"> + <defs + id="defs2"> + <marker + inkscape:stockid="TriangleOutL" + orient="auto" + refY="0" + refX="0" + id="TriangleOutL" + style="overflow:visible" + inkscape:isstock="true"> + <path + id="path1133" + d="M 5.77,0 -2.88,5 V -5 Z" + style="fill:#000000;fill-opacity:1;fill-rule:evenodd;stroke:#000000;stroke-width:1.00000003pt;stroke-opacity:1" + transform="scale(0.8)" + inkscape:connector-curvature="0" /> + </marker> + <marker + inkscape:stockid="TriangleOutL" + orient="auto" + refY="0" + refX="0" + id="TriangleOutL-6" + style="overflow:visible" + inkscape:isstock="true"> + <path + inkscape:connector-curvature="0" + id="path1133-0" + d="M 5.77,0 -2.88,5 V -5 Z" + style="fill:#000000;fill-opacity:1;fill-rule:evenodd;stroke:#000000;stroke-width:1.00000003pt;stroke-opacity:1" + transform="scale(0.8)" /> + </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="205.69673" + inkscape:cy="33.960031" + inkscape:document-units="mm" + inkscape:current-layer="layer1" + showgrid="false" + inkscape:window-width="1288" + inkscape:window-height="1376" + inkscape:window-x="1272" + inkscape:window-y="27" + inkscape:window-maximized="0" + fit-margin-top="0" + fit-margin-left="0" + fit-margin-right="0" + fit-margin-bottom="0" /> + <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(112.75816,51.721433)"> + <rect + style="fill:#ffe680;fill-opacity:1;stroke:#000000;stroke-width:0.62916809;stroke-linecap:round;stroke-linejoin:bevel;stroke-miterlimit:4;stroke-dasharray:none;stroke-dashoffset:0" + id="rect836" + width="48.988979" + height="29.48851" + x="-112.44358" + y="-51.189243" + ry="0" /> + <rect + style="fill:#008000;fill-opacity:1;stroke:none;stroke-width:0.38327959;stroke-linecap:round;stroke-linejoin:bevel;stroke-miterlimit:4;stroke-dasharray:none;stroke-dashoffset:0" + id="rect834" + width="14.422765" + height="15.872559" + x="-78.227928" + y="-44.469936" /> + <text + xml:space="preserve" + style="font-style:normal;font-weight:normal;font-size:0.82813358px;line-height:1.25;font-family:sans-serif;letter-spacing:0px;word-spacing:0px;fill:#000000;fill-opacity:1;stroke:none;stroke-width:0.06901112" + x="-71.189278" + y="-48.114422" + id="text844"><tspan + sodipodi:role="line" + x="-71.189278" + y="-48.114422" + style="font-style:normal;font-variant:normal;font-weight:bold;font-stretch:normal;font-size:2.02432632px;font-family:sans-serif;-inkscape-font-specification:'sans-serif Bold';text-align:center;text-anchor:middle;stroke-width:0.06901112" + id="tspan846">Protected</tspan><tspan + sodipodi:role="line" + x="-71.189278" + y="-45.584015" + style="font-style:normal;font-variant:normal;font-weight:bold;font-stretch:normal;font-size:2.02432632px;font-family:sans-serif;-inkscape-font-specification:'sans-serif Bold';text-align:center;text-anchor:middle;stroke-width:0.06901112" + id="tspan2288">MPO plane</tspan></text> + <rect + style="fill:#ffe680;fill-opacity:1;stroke:#000000;stroke-width:0.62916809;stroke-linecap:round;stroke-linejoin:bevel;stroke-miterlimit:4;stroke-dasharray:none;stroke-dashoffset:0" + id="rect836-3" + width="48.988979" + height="29.48851" + x="-58.973743" + y="-51.406849" + ry="0" /> + <rect + style="fill:#000000;fill-opacity:1;stroke:none;stroke-width:0.2500253;stroke-linecap:round;stroke-linejoin:bevel;stroke-miterlimit:4;stroke-dasharray:none;stroke-dashoffset:0" + id="rect834-6" + width="6.1374092" + height="15.872559" + x="-58.632965" + y="-44.469936" /> + <text + xml:space="preserve" + style="font-style:normal;font-weight:normal;font-size:0.82813358px;line-height:1.25;font-family:sans-serif;letter-spacing:0px;word-spacing:0px;fill:#000000;fill-opacity:1;stroke:none;stroke-width:0.06901112" + x="-107.96788" + y="-47.033775" + id="text844-7"><tspan + sodipodi:role="line" + x="-107.96788" + y="-47.033775" + style="font-style:normal;font-variant:normal;font-weight:bold;font-stretch:normal;font-size:3.52777767px;font-family:sans-serif;-inkscape-font-specification:'sans-serif Bold';text-align:center;text-anchor:middle;stroke-width:0.06901112" + id="tspan846-3">#1</tspan></text> + <text + xml:space="preserve" + style="font-style:normal;font-weight:normal;font-size:0.82813358px;line-height:1.25;font-family:sans-serif;letter-spacing:0px;word-spacing:0px;fill:#000000;fill-opacity:1;stroke:none;stroke-width:0.06901112" + x="-15.20074" + y="-46.715996" + id="text844-7-2"><tspan + sodipodi:role="line" + x="-15.20074" + y="-46.715996" + style="font-style:normal;font-variant:normal;font-weight:bold;font-stretch:normal;font-size:3.52777767px;font-family:sans-serif;-inkscape-font-specification:'sans-serif Bold';text-align:center;text-anchor:middle;stroke-width:0.06901112" + id="tspan846-3-9">#2</tspan></text> + <text + xml:space="preserve" + style="font-style:normal;font-weight:normal;font-size:0.82813358px;line-height:1.25;font-family:sans-serif;letter-spacing:0px;word-spacing:0px;fill:#000000;fill-opacity:1;stroke:none;stroke-width:0.06901112" + x="-88.926605" + y="-23.173674" + id="text844-1"><tspan + sodipodi:role="line" + x="-88.926605" + y="-23.173674" + style="font-style:normal;font-variant:normal;font-weight:bold;font-stretch:normal;font-size:2.02432632px;font-family:sans-serif;-inkscape-font-specification:'sans-serif Bold';text-align:center;text-anchor:middle;stroke-width:0.06901112" + id="tspan846-7">Desktop</tspan></text> + <text + xml:space="preserve" + style="font-style:normal;font-weight:normal;font-size:0.82813358px;line-height:1.25;font-family:sans-serif;letter-spacing:0px;word-spacing:0px;fill:#000000;fill-opacity:1;stroke:none;stroke-width:0.06901112" + x="-33.770744" + y="-23.819901" + id="text844-1-0"><tspan + sodipodi:role="line" + x="-33.770744" + y="-23.819901" + style="font-style:normal;font-variant:normal;font-weight:bold;font-stretch:normal;font-size:2.02432632px;font-family:sans-serif;-inkscape-font-specification:'sans-serif Bold';text-align:center;text-anchor:middle;stroke-width:0.06901112" + id="tspan846-7-9">Desktop</tspan></text> + <text + xml:space="preserve" + style="font-style:normal;font-weight:normal;font-size:0.82813358px;line-height:1.25;font-family:sans-serif;letter-spacing:0px;word-spacing:0px;fill:#ffffff;fill-opacity:1;stroke:none;stroke-width:0.06901112" + x="-75.17498" + y="-41.219398" + id="text844-7-2-3"><tspan + sodipodi:role="line" + x="-75.17498" + y="-41.219398" + style="font-style:normal;font-variant:normal;font-weight:bold;font-stretch:normal;font-size:3.52777767px;font-family:sans-serif;-inkscape-font-specification:'sans-serif Bold';text-align:center;text-anchor:middle;fill:#ffffff;stroke-width:0.06901112" + id="tspan846-3-9-6">#3</tspan></text> + <text + xml:space="preserve" + style="font-style:normal;font-weight:normal;font-size:0.82813358px;line-height:1.25;font-family:sans-serif;letter-spacing:0px;word-spacing:0px;fill:#000000;fill-opacity:1;stroke:none;stroke-width:0.06901112" + x="-47.142235" + y="-48.056866" + id="text844-0"><tspan + sodipodi:role="line" + x="-47.142235" + y="-48.056866" + style="font-style:normal;font-variant:normal;font-weight:bold;font-stretch:normal;font-size:2.02432632px;font-family:sans-serif;-inkscape-font-specification:'sans-serif Bold';text-align:center;text-anchor:middle;stroke-width:0.06901112" + id="tspan2288-2">Software</tspan><tspan + sodipodi:role="line" + x="-47.142235" + y="-45.526459" + style="font-style:normal;font-variant:normal;font-weight:bold;font-stretch:normal;font-size:2.02432632px;font-family:sans-serif;-inkscape-font-specification:'sans-serif Bold';text-align:center;text-anchor:middle;stroke-width:0.06901112" + id="tspan2313">Composited Video</tspan></text> + <text + xml:space="preserve" + style="font-style:normal;font-weight:normal;font-size:0.82813358px;line-height:1.25;font-family:sans-serif;letter-spacing:0px;word-spacing:0px;fill:#000000;fill-opacity:1;stroke:none;stroke-width:0.06901112" + x="-36.23288" + y="-34.592064" + id="text844-1-6"><tspan + sodipodi:role="line" + x="-36.23288" + y="-34.592064" + style="font-style:normal;font-variant:normal;font-weight:bold;font-stretch:normal;font-size:2.02432632px;font-family:sans-serif;-inkscape-font-specification:'sans-serif Bold';text-align:center;text-anchor:middle;stroke-width:0.06901112" + id="tspan846-7-1">Video will not be displayed</tspan></text> + </g> +</svg> diff --git a/Documentation/gpu/amdgpu/display/multi-display-hdcp-mpo.svg b/Documentation/gpu/amdgpu/display/multi-display-hdcp-mpo.svg new file mode 100644 index 000000000000..84d53a558b05 --- /dev/null +++ b/Documentation/gpu/amdgpu/display/multi-display-hdcp-mpo.svg @@ -0,0 +1,171 @@ +<?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="103.08798mm" + height="30.335283mm" + viewBox="0 0 103.08798 30.335284" + version="1.1" + id="svg8" + inkscape:version="0.92.5 (2060ec1f9f, 2020-04-08)" + sodipodi:docname="multi-display-hdcp-mpo.svg"> + <defs + id="defs2"> + <marker + inkscape:stockid="TriangleOutL" + orient="auto" + refY="0" + refX="0" + id="TriangleOutL" + style="overflow:visible" + inkscape:isstock="true"> + <path + id="path1133" + d="M 5.77,0 -2.88,5 V -5 Z" + style="fill:#000000;fill-opacity:1;fill-rule:evenodd;stroke:#000000;stroke-width:1.00000003pt;stroke-opacity:1" + transform="scale(0.8)" + inkscape:connector-curvature="0" /> + </marker> + <marker + inkscape:stockid="TriangleOutL" + orient="auto" + refY="0" + refX="0" + id="TriangleOutL-6" + style="overflow:visible" + inkscape:isstock="true"> + <path + inkscape:connector-curvature="0" + id="path1133-0" + d="M 5.77,0 -2.88,5 V -5 Z" + style="fill:#000000;fill-opacity:1;fill-rule:evenodd;stroke:#000000;stroke-width:1.00000003pt;stroke-opacity:1" + transform="scale(0.8)" /> + </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="196.85789" + inkscape:cy="33.960027" + inkscape:document-units="mm" + inkscape:current-layer="layer1" + showgrid="false" + inkscape:window-width="1288" + inkscape:window-height="1376" + inkscape:window-x="1272" + inkscape:window-y="27" + inkscape:window-maximized="0" + fit-margin-top="0" + fit-margin-left="0" + fit-margin-right="0" + fit-margin-bottom="0" /> + <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(112.75816,51.721433)"> + <rect + style="fill:#ffe680;fill-opacity:1;stroke:#000000;stroke-width:0.62916809;stroke-linecap:round;stroke-linejoin:bevel;stroke-miterlimit:4;stroke-dasharray:none;stroke-dashoffset:0" + id="rect836" + width="48.988979" + height="29.48851" + x="-112.44358" + y="-51.189243" + ry="0" /> + <rect + style="fill:#008000;fill-opacity:1;stroke:none;stroke-width:0.38327959;stroke-linecap:round;stroke-linejoin:bevel;stroke-miterlimit:4;stroke-dasharray:none;stroke-dashoffset:0" + id="rect834" + width="14.422765" + height="15.872559" + x="-78.227928" + y="-44.469936" /> + <text + xml:space="preserve" + style="font-style:normal;font-weight:normal;font-size:0.82813358px;line-height:1.25;font-family:sans-serif;letter-spacing:0px;word-spacing:0px;fill:#000000;fill-opacity:1;stroke:none;stroke-width:0.06901112" + x="-71.189278" + y="-48.114422" + id="text844"><tspan + sodipodi:role="line" + x="-71.189278" + y="-48.114422" + style="font-style:normal;font-variant:normal;font-weight:bold;font-stretch:normal;font-size:2.02432632px;font-family:sans-serif;-inkscape-font-specification:'sans-serif Bold';text-align:center;text-anchor:middle;stroke-width:0.06901112" + id="tspan846">Protected</tspan><tspan + sodipodi:role="line" + x="-71.189278" + y="-45.584015" + style="font-style:normal;font-variant:normal;font-weight:bold;font-stretch:normal;font-size:2.02432632px;font-family:sans-serif;-inkscape-font-specification:'sans-serif Bold';text-align:center;text-anchor:middle;stroke-width:0.06901112" + id="tspan2288">MPO plane</tspan></text> + <rect + style="fill:#ffe680;fill-opacity:1;stroke:#000000;stroke-width:0.62916809;stroke-linecap:round;stroke-linejoin:bevel;stroke-miterlimit:4;stroke-dasharray:none;stroke-dashoffset:0" + id="rect836-3" + width="48.988979" + height="29.48851" + x="-58.973743" + y="-51.406849" + ry="0" /> + <rect + style="fill:#008000;fill-opacity:1;stroke:none;stroke-width:0.2500253;stroke-linecap:round;stroke-linejoin:bevel;stroke-miterlimit:4;stroke-dasharray:none;stroke-dashoffset:0" + id="rect834-6" + width="6.1374092" + height="15.872559" + x="-58.632965" + y="-44.469936" /> + <text + xml:space="preserve" + style="font-style:normal;font-weight:normal;font-size:0.82813358px;line-height:1.25;font-family:sans-serif;letter-spacing:0px;word-spacing:0px;fill:#000000;fill-opacity:1;stroke:none;stroke-width:0.06901112" + x="-88.926605" + y="-23.173674" + id="text844-1"><tspan + sodipodi:role="line" + x="-88.926605" + y="-23.173674" + style="font-style:normal;font-variant:normal;font-weight:bold;font-stretch:normal;font-size:2.02432632px;font-family:sans-serif;-inkscape-font-specification:'sans-serif Bold';text-align:center;text-anchor:middle;stroke-width:0.06901112" + id="tspan846-7">Desktop</tspan></text> + <text + xml:space="preserve" + style="font-style:normal;font-weight:normal;font-size:0.82813358px;line-height:1.25;font-family:sans-serif;letter-spacing:0px;word-spacing:0px;fill:#000000;fill-opacity:1;stroke:none;stroke-width:0.06901112" + x="-33.770744" + y="-23.819901" + id="text844-1-0"><tspan + sodipodi:role="line" + x="-33.770744" + y="-23.819901" + style="font-style:normal;font-variant:normal;font-weight:bold;font-stretch:normal;font-size:2.02432632px;font-family:sans-serif;-inkscape-font-specification:'sans-serif Bold';text-align:center;text-anchor:middle;stroke-width:0.06901112" + id="tspan846-7-9">Desktop</tspan></text> + <text + xml:space="preserve" + style="font-style:normal;font-weight:normal;font-size:0.82813358px;line-height:1.25;font-family:sans-serif;letter-spacing:0px;word-spacing:0px;fill:#ffffff;fill-opacity:1;stroke:none;stroke-width:0.06901112" + x="-70.364128" + y="-35.740372" + id="text844-7-2-3"><tspan + sodipodi:role="line" + x="-70.364128" + y="-35.740372" + style="font-style:normal;font-variant:normal;font-weight:bold;font-stretch:normal;font-size:3.52777767px;font-family:sans-serif;-inkscape-font-specification:'sans-serif Bold';text-align:center;text-anchor:middle;fill:#ffffff;stroke-width:0.06901112" + id="tspan846-3-9-6">Video</tspan></text> + </g> +</svg> diff --git a/Documentation/gpu/amdgpu/display/pipeline_4k_no_split.svg b/Documentation/gpu/amdgpu/display/pipeline_4k_no_split.svg new file mode 100644 index 000000000000..5fa289d99fcd --- /dev/null +++ b/Documentation/gpu/amdgpu/display/pipeline_4k_no_split.svg @@ -0,0 +1,958 @@ +<?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="1055.4928" + height="404.60379" + viewBox="0 0 279.26579 107.05142" + version="1.1" + id="svg8" + inkscape:version="0.92.5 (2060ec1f9f, 2020-04-08)" + sodipodi:docname="pipeline_4k_no_split.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> + <marker + inkscape:stockid="Arrow2Mend" + orient="auto" + refY="0" + refX="0" + id="Arrow2Mend-9" + style="overflow:visible" + inkscape:isstock="true"> + <path + id="path1200-3" + 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-94" + style="overflow:visible" + inkscape:isstock="true"> + <path + id="path1200-7" + 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-94-6" + style="overflow:visible" + inkscape:isstock="true"> + <path + id="path1200-7-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)" + inkscape:connector-curvature="0" /> + </marker> + <marker + inkscape:stockid="Arrow2Mend" + orient="auto" + refY="0" + refX="0" + id="Arrow2Mend-94-6-7" + style="overflow:visible" + inkscape:isstock="true"> + <path + id="path1200-7-9-4" + 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-94-6-0" + style="overflow:visible" + inkscape:isstock="true"> + <path + id="path1200-7-9-7" + 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-94-6-0-1" + style="overflow:visible" + inkscape:isstock="true"> + <path + id="path1200-7-9-7-4" + 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-94-6-0-2" + style="overflow:visible" + inkscape:isstock="true"> + <path + id="path1200-7-9-7-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="Arrow2Mend-94-6-0-2-4" + style="overflow:visible" + inkscape:isstock="true"> + <path + id="path1200-7-9-7-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)" + inkscape:connector-curvature="0" /> + </marker> + <marker + inkscape:stockid="Arrow2Mend" + orient="auto" + refY="0" + refX="0" + id="Arrow2Mend-94-8" + style="overflow:visible" + inkscape:isstock="true"> + <path + id="path1200-7-7" + 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="scale(-0.6)" + inkscape:connector-curvature="0" /> + </marker> + <marker + inkscape:stockid="Arrow2Mend" + orient="auto" + refY="0" + refX="0" + id="Arrow2Mend-94-6-0-2-7" + style="overflow:visible" + inkscape:isstock="true"> + <path + id="path1200-7-9-7-6-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> + </defs> + <sodipodi:namedview + id="base" + pagecolor="#ffffff" + bordercolor="#666666" + borderopacity="1.0" + inkscape:pageopacity="0.0" + inkscape:pageshadow="2" + inkscape:zoom="1.4" + inkscape:cx="213.41584" + inkscape:cy="301.17934" + inkscape:document-units="mm" + inkscape:current-layer="layer1" + showgrid="false" + inkscape:window-width="2560" + inkscape:window-height="1376" + 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(349.34521,-0.81564989)"> + <rect + style="fill:none;stroke:#000000;stroke-width:1.00353587;stroke-linecap:round;stroke-linejoin:bevel;stroke-miterlimit:4;stroke-dasharray:none" + id="rect834" + width="30.251244" + height="88.477814" + x="-317.81958" + y="14.782127" + ry="2.5590618e-06" /> + <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.16370411" + x="-314.73792" + y="21.83947" + id="text838"><tspan + sodipodi:role="line" + id="tspan836" + x="-314.73792" + y="21.83947" + style="stroke-width:0.16370411">DCHUB</tspan></text> + <g + id="g2025" + transform="translate(-2.4916954,-1.2533369)"> + <text + id="text838-5" + y="31.969406" + x="-254.53119" + 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 + style="text-align:center;text-anchor:middle;stroke-width:0.16370411" + y="31.969406" + x="-254.53119" + id="tspan836-3" + sodipodi:role="line">DPP</tspan><tspan + id="tspan936" + style="text-align:center;text-anchor:middle;stroke-width:0.16370411" + y="40.15461" + x="-254.53119" + sodipodi:role="line">(0)</tspan></text> + <rect + ry="7.8154301e-07" + y="20.596174" + x="-269.66983" + height="27.021315" + width="30.696135" + id="rect834-5" + style="fill:none;stroke:#000000;stroke-width:0.55864918;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="g1878" + transform="translate(-0.62971878)"> + <text + id="text846" + y="30.716068" + x="-302.27368" + 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:#44aa00;fill-opacity:1;stroke:none;stroke-width:0.16370411" + xml:space="preserve"><tspan + style="text-align:center;text-anchor:middle;fill:#44aa00;stroke-width:0.16370411" + y="30.716068" + x="-302.27368" + id="tspan844" + sodipodi:role="line">HUBP</tspan><tspan + id="tspan863" + style="text-align:center;text-anchor:middle;fill:#44aa00;stroke-width:0.16370411" + y="38.901276" + x="-302.27368" + sodipodi:role="line">(0)</tspan></text> + <g + id="g1853"> + <rect + style="fill:none;fill-opacity:1;stroke:#55d400;stroke-width:0.94157624;stroke-linecap:butt;stroke-linejoin:bevel;stroke-miterlimit:4;stroke-dasharray:none;stroke-dashoffset:0" + id="rect1850" + width="24.708241" + height="17.224693" + x="-314.41837" + y="24.241148" /> + </g> + </g> + <g + transform="translate(-0.62971878,18.810271)" + id="g1878-1"> + <text + id="text846-2" + y="30.716068" + x="-302.27368" + 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:#44aa00;fill-opacity:1;stroke:none;stroke-width:0.16370411" + xml:space="preserve"><tspan + style="text-align:center;text-anchor:middle;fill:#44aa00;stroke-width:0.16370411" + y="30.716068" + x="-302.27368" + id="tspan844-7" + sodipodi:role="line">HUBP</tspan><tspan + id="tspan863-0" + style="text-align:center;text-anchor:middle;fill:#44aa00;stroke-width:0.16370411" + y="38.901276" + x="-302.27368" + sodipodi:role="line">(1)</tspan></text> + <g + id="g1853-9"> + <rect + style="fill:none;fill-opacity:1;stroke:#55d400;stroke-width:0.94157624;stroke-linecap:butt;stroke-linejoin:bevel;stroke-miterlimit:4;stroke-dasharray:none;stroke-dashoffset:0" + id="rect1850-3" + width="24.708241" + height="17.224693" + x="-314.41837" + y="24.241148" /> + </g> + </g> + <g + transform="translate(-0.62971878,57.029814)" + id="g1878-8"> + <text + id="text846-7" + y="30.716068" + x="-302.27368" + 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:#44aa00;fill-opacity:1;stroke:none;stroke-width:0.16370411" + xml:space="preserve"><tspan + style="text-align:center;text-anchor:middle;fill:#44aa00;stroke-width:0.16370411" + y="30.716068" + x="-302.27368" + id="tspan844-9" + sodipodi:role="line">HUBP</tspan><tspan + id="tspan863-20" + style="text-align:center;text-anchor:middle;fill:#44aa00;stroke-width:0.16370411" + y="38.901276" + x="-302.27368" + sodipodi:role="line">(5)</tspan></text> + <g + id="g1853-2"> + <rect + style="fill:none;fill-opacity:1;stroke:#55d400;stroke-width:0.94157624;stroke-linecap:butt;stroke-linejoin:bevel;stroke-miterlimit:4;stroke-dasharray:none;stroke-dashoffset:0" + id="rect1850-37" + width="24.708241" + height="17.224693" + x="-314.41837" + y="24.241148" /> + </g> + </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="-310.7348" + y="72.106789" + id="text8862-5"><tspan + sodipodi:role="line" + id="tspan8860-9" + x="-310.7348" + y="72.106789" + style="font-style:normal;font-variant:normal;font-weight:bold;font-stretch:normal;font-size:14.11111069px;font-family:sans-serif;-inkscape-font-specification:'sans-serif Bold';fill:#44aa00;stroke-width:0.26458332">...</tspan></text> + <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-94)" + d="m -288.90777,32.862737 h 14.20296" + id="path1171" + 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="-264.85431" + y="62.072891" + id="text8862-5-8"><tspan + sodipodi:role="line" + id="tspan8860-9-4" + x="-264.85431" + y="62.072891" + style="font-style:normal;font-variant:normal;font-weight:bold;font-stretch:normal;font-size:14.11111069px;font-family:sans-serif;-inkscape-font-specification:'sans-serif Bold';fill:#000000;stroke-width:0.26458332">...</tspan></text> + <g + id="g2025-5" + transform="translate(40.522337,-1.1484419)" /> + <g + id="g7343" + transform="translate(40.522337,-1.2533369)"> + <text + id="text838-5-6" + y="31.969406" + x="-254.53119" + 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 + style="text-align:center;text-anchor:middle;stroke-width:0.16370411" + y="31.969406" + x="-254.53119" + id="tspan836-3-3" + sodipodi:role="line">MPC</tspan><tspan + id="tspan936-2" + style="text-align:center;text-anchor:middle;stroke-width:0.16370411" + y="40.15461" + x="-254.53119" + sodipodi:role="line">(0)</tspan></text> + <rect + ry="7.8154301e-07" + y="20.596174" + x="-269.66983" + height="27.021315" + width="30.696135" + id="rect834-5-0" + style="fill:none;stroke:#000000;stroke-width:0.55864918;stroke-linecap:round;stroke-linejoin:bevel;stroke-miterlimit:4;stroke-dasharray:none" /> + </g> + <g + id="g7343-2" + transform="translate(84.178583,-1.2533369)"> + <text + id="text838-5-6-54" + y="31.969406" + x="-254.53119" + 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 + style="text-align:center;text-anchor:middle;stroke-width:0.16370411" + y="31.969406" + x="-254.53119" + id="tspan836-3-3-7" + sodipodi:role="line">OPP</tspan><tspan + id="tspan936-2-44" + style="text-align:center;text-anchor:middle;stroke-width:0.16370411" + y="40.15461" + x="-254.53119" + sodipodi:role="line">(0)</tspan></text> + <rect + ry="7.8154301e-07" + y="20.596174" + x="-269.66983" + height="27.021315" + width="30.696135" + id="rect834-5-0-3" + style="fill:none;stroke:#000000;stroke-width:0.55864918;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: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="-221.84029" + y="62.072891" + id="text8862-5-8-6"><tspan + sodipodi:role="line" + id="tspan8860-9-4-5" + x="-221.84029" + y="62.072891" + style="font-style:normal;font-variant:normal;font-weight:bold;font-stretch:normal;font-size:14.11111069px;font-family:sans-serif;-inkscape-font-specification:'sans-serif Bold';fill:#000000;stroke-width:0.26458332">...</tspan></text> + <path + style="fill:none;stroke:#ff0000;stroke-width:0.83149505;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:none;stroke-opacity:1;marker-end:url(#Arrow2Mend-94-6)" + d="m -240.90479,32.86192 h 10.61353" + id="path1171-3" + inkscape:connector-curvature="0" /> + <path + style="fill:none;stroke:#ff0000;stroke-width:0.83149505;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:none;stroke-opacity:1;marker-end:url(#Arrow2Mend-94-6-0)" + d="m -198.19009,32.86192 h 10.61353" + id="path1171-3-8" + inkscape:connector-curvature="0" /> + <g + id="g7343-2-2" + transform="translate(127.15447,-1.1484419)"> + <text + id="text838-5-6-54-0" + y="65.122154" + x="-254.32814" + 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-2-44-8" + style="text-align:center;text-anchor:middle;stroke-width:0.16370411" + y="65.122154" + x="-254.32814" + sodipodi:role="line">OPTC</tspan></text> + <rect + ry="2.4256708e-06" + y="20.805576" + x="-269.46042" + height="83.865906" + width="30.277332" + id="rect834-5-0-3-9" + style="fill:none;stroke:#000000;stroke-width:0.97745234;stroke-linecap:round;stroke-linejoin:bevel;stroke-miterlimit:4;stroke-dasharray:none" /> + </g> + <path + style="fill:none;stroke:#ff0000;stroke-width:0.83149505;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:none;stroke-opacity:1;marker-end:url(#Arrow2Mend-94-6-0-2)" + d="m -154.34485,32.86192 h 10.61353" + id="path1171-3-8-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="-178.18404" + y="62.072891" + id="text8862-5-8-6-0"><tspan + sodipodi:role="line" + id="tspan8860-9-4-5-4" + x="-178.18404" + y="62.072891" + style="font-style:normal;font-variant:normal;font-weight:bold;font-stretch:normal;font-size:14.11111069px;font-family:sans-serif;-inkscape-font-specification:'sans-serif Bold';fill:#000000;stroke-width:0.26458332">...</tspan></text> + <path + style="fill:#000000;stroke:#000000;stroke-width:0.96187615;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:none;stroke-opacity:1;marker-end:url(#Arrow2Mend-94-8)" + d="m -335.20986,59.030276 h 14.20296" + id="path1171-17" + 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.16370411" + x="-349.77686" + y="61.404655" + id="text838-2"><tspan + sodipodi:role="line" + id="tspan836-7" + x="-349.77686" + y="61.404655" + style="stroke-width:0.16370411">SDP</tspan></text> + <path + style="fill:none;stroke:#000000;stroke-width:1.32291663;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:1.32291667, 1.32291667;stroke-dashoffset:0;stroke-opacity:1" + d="M -279.04164,107.86706 V 0.89985833" + id="path11907" + inkscape:connector-curvature="0" /> + <path + style="fill:none;stroke:#000000;stroke-width:1.32291663;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:1.3229167, 1.3229167;stroke-dashoffset:0;stroke-opacity:1" + d="M -235.57438,107.86707 V 0.89985663" + id="path11907-6-1" + inkscape:connector-curvature="0" /> + <path + style="fill:none;stroke:#000000;stroke-width:1.32291663;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:1.32291671, 1.32291671;stroke-dashoffset:0;stroke-opacity:1" + d="M -149.96277,107.86707 V 0.89985223" + id="path11907-6-1-0" + 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.16370411" + x="-257.38275" + y="5.003336" + id="text838-6"><tspan + sodipodi:role="line" + id="tspan836-1" + x="-257.38275" + y="5.003336" + style="font-size:4.93888903px;text-align:center;text-anchor:middle;stroke-width:0.16370411">DPPCLK</tspan><tspan + sodipodi:role="line" + x="-257.38275" + y="13.188541" + style="font-size:4.93888903px;text-align:center;text-anchor:middle;stroke-width:0.16370411" + id="tspan12658">535.916Mhz</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.16370411" + x="-192.85298" + y="5.003336" + id="text838-6-5"><tspan + sodipodi:role="line" + id="tspan836-1-9" + x="-192.85298" + y="5.003336" + style="font-size:4.93888903px;text-align:center;text-anchor:middle;stroke-width:0.16370411">DISPCLK</tspan><tspan + sodipodi:role="line" + x="-192.85298" + y="13.188541" + style="font-size:4.93888903px;text-align:center;text-anchor:middle;stroke-width:0.16370411" + id="tspan12662">541.275 Mhz</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.16370411" + x="-302.03766" + y="5.003336" + id="text838-6-5-4"><tspan + sodipodi:role="line" + id="tspan836-1-9-9" + x="-312.23135" + y="5.003336" + style="font-size:4.93888903px;stroke-width:0.16370411;text-anchor:middle;text-align:center">DCFCLK</tspan><tspan + sodipodi:role="line" + x="-312.23135" + y="13.188541" + style="font-size:4.93888903px;stroke-width:0.16370411;text-anchor:middle;text-align:center" + id="tspan12660">506 Mhz</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.16370411" + x="-96.075348" + y="4.568048" + id="text838-6-5-0"><tspan + sodipodi:role="line" + id="tspan836-1-9-91" + x="-96.075348" + y="4.568048" + style="font-size:4.93888903px;stroke-width:0.16370411">SymCLK</tspan></text> + <g + id="g7343-2-2-7" + transform="translate(168.61494,-1.1484419)"> + <text + id="text838-5-6-54-0-7" + y="65.122154" + x="-254.32814" + 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-2-44-8-1" + style="text-align:center;text-anchor:middle;stroke-width:0.16370411" + y="65.122154" + x="-254.32814" + sodipodi:role="line">DIO</tspan></text> + <rect + ry="2.4256708e-06" + y="20.805576" + x="-269.46042" + height="83.865906" + width="30.277332" + id="rect834-5-0-3-9-1" + style="fill:none;stroke:#000000;stroke-width:0.97745234;stroke-linecap:round;stroke-linejoin:bevel;stroke-miterlimit:4;stroke-dasharray:none" /> + </g> + <path + style="fill:none;stroke:#000000;stroke-width:1.32291663;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:1.32291672, 1.32291672;stroke-dashoffset:0;stroke-opacity:1" + d="M -108.38539,107.86707 V 0.89985092" + id="path11907-6-1-0-5" + 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.16370411" + x="-143.52292" + y="5.0467439" + id="text838-6-5-0-9"><tspan + sodipodi:role="line" + id="tspan836-1-9-91-7" + x="-143.52292" + y="5.0467439" + style="font-size:4.93888903px;stroke-width:0.16370411">VirtualPCLK</tspan></text> + <path + style="fill:none;stroke:#ff0000;stroke-width:0.83149505;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:none;stroke-opacity:1;marker-end:url(#Arrow2Mend-94-6-0-2-7)" + d="m -112.24183,60.747629 h 10.61353" + id="path1171-3-8-6-7" + inkscape:connector-curvature="0" /> + </g> +</svg> diff --git a/Documentation/gpu/amdgpu/display/pipeline_4k_split.svg b/Documentation/gpu/amdgpu/display/pipeline_4k_split.svg new file mode 100644 index 000000000000..b43119e7eb8a --- /dev/null +++ b/Documentation/gpu/amdgpu/display/pipeline_4k_split.svg @@ -0,0 +1,1062 @@ +<?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="1055.4928" + height="404.60379" + viewBox="0 0 279.26579 107.05142" + version="1.1" + id="svg8" + inkscape:version="0.92.5 (2060ec1f9f, 2020-04-08)" + sodipodi:docname="pipeline_no_split_4k.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> + <marker + inkscape:stockid="Arrow2Mend" + orient="auto" + refY="0" + refX="0" + id="Arrow2Mend-9" + style="overflow:visible" + inkscape:isstock="true"> + <path + id="path1200-3" + 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-94" + style="overflow:visible" + inkscape:isstock="true"> + <path + id="path1200-7" + 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-94-6" + style="overflow:visible" + inkscape:isstock="true"> + <path + id="path1200-7-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)" + inkscape:connector-curvature="0" /> + </marker> + <marker + inkscape:stockid="Arrow2Mend" + orient="auto" + refY="0" + refX="0" + id="Arrow2Mend-94-6-7" + style="overflow:visible" + inkscape:isstock="true"> + <path + id="path1200-7-9-4" + 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-94-6-0" + style="overflow:visible" + inkscape:isstock="true"> + <path + id="path1200-7-9-7" + 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-94-6-0-1" + style="overflow:visible" + inkscape:isstock="true"> + <path + id="path1200-7-9-7-4" + 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-94-6-0-2" + style="overflow:visible" + inkscape:isstock="true"> + <path + id="path1200-7-9-7-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="Arrow2Mend-94-6-0-2-4" + style="overflow:visible" + inkscape:isstock="true"> + <path + id="path1200-7-9-7-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)" + inkscape:connector-curvature="0" /> + </marker> + <marker + inkscape:stockid="Arrow2Mend" + orient="auto" + refY="0" + refX="0" + id="Arrow2Mend-94-8" + style="overflow:visible" + inkscape:isstock="true"> + <path + id="path1200-7-7" + 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="scale(-0.6)" + inkscape:connector-curvature="0" /> + </marker> + <marker + inkscape:stockid="Arrow2Mend" + orient="auto" + refY="0" + refX="0" + id="Arrow2Mend-94-6-0-2-7" + style="overflow:visible" + inkscape:isstock="true"> + <path + id="path1200-7-9-7-6-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> + </defs> + <sodipodi:namedview + id="base" + pagecolor="#ffffff" + bordercolor="#666666" + borderopacity="1.0" + inkscape:pageopacity="0.0" + inkscape:pageshadow="2" + inkscape:zoom="1.4" + inkscape:cx="491.27298" + inkscape:cy="306.89362" + inkscape:document-units="mm" + inkscape:current-layer="layer1" + showgrid="false" + inkscape:window-width="2560" + inkscape:window-height="1376" + 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></dc:title> + </cc:Work> + </rdf:RDF> + </metadata> + <g + inkscape:label="Layer 1" + inkscape:groupmode="layer" + id="layer1" + transform="translate(349.34521,-0.81564989)"> + <rect + style="fill:none;stroke:#000000;stroke-width:1.00353587;stroke-linecap:round;stroke-linejoin:bevel;stroke-miterlimit:4;stroke-dasharray:none" + id="rect834" + width="30.251244" + height="88.477814" + x="-317.81958" + y="14.782127" + ry="2.5590618e-06" /> + <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.16370411" + x="-314.73792" + y="21.83947" + id="text838"><tspan + sodipodi:role="line" + id="tspan836" + x="-314.73792" + y="21.83947" + style="stroke-width:0.16370411">DCHUB</tspan></text> + <g + id="g2025" + transform="translate(-2.4916954,-1.2533369)"> + <text + id="text838-5" + y="31.969406" + x="-254.53119" + 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 + style="text-align:center;text-anchor:middle;stroke-width:0.16370411" + y="31.969406" + x="-254.53119" + id="tspan836-3" + sodipodi:role="line">DPP</tspan><tspan + id="tspan936" + style="text-align:center;text-anchor:middle;stroke-width:0.16370411" + y="40.15461" + x="-254.53119" + sodipodi:role="line">(0)</tspan></text> + <rect + ry="7.8154301e-07" + y="20.596174" + x="-269.66983" + height="27.021315" + width="30.696135" + id="rect834-5" + style="fill:none;stroke:#000000;stroke-width:0.55864918;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="g1878" + transform="translate(-0.62971878)"> + <text + id="text846" + y="30.716068" + x="-302.27368" + 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:#44aa00;fill-opacity:1;stroke:none;stroke-width:0.16370411" + xml:space="preserve"><tspan + style="text-align:center;text-anchor:middle;fill:#44aa00;stroke-width:0.16370411" + y="30.716068" + x="-302.27368" + id="tspan844" + sodipodi:role="line">HUBP</tspan><tspan + id="tspan863" + style="text-align:center;text-anchor:middle;fill:#44aa00;stroke-width:0.16370411" + y="38.901276" + x="-302.27368" + sodipodi:role="line">(0)</tspan></text> + <g + id="g1853"> + <rect + style="fill:none;fill-opacity:1;stroke:#55d400;stroke-width:0.94157624;stroke-linecap:butt;stroke-linejoin:bevel;stroke-miterlimit:4;stroke-dasharray:none;stroke-dashoffset:0" + id="rect1850" + width="24.708241" + height="17.224693" + x="-314.41837" + y="24.241148" /> + </g> + </g> + <g + transform="translate(-0.62971878,18.810271)" + id="g1878-1"> + <text + id="text846-2" + y="30.716068" + x="-302.27368" + 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:#44aa00;fill-opacity:1;stroke:none;stroke-width:0.16370411" + xml:space="preserve"><tspan + style="text-align:center;text-anchor:middle;fill:#44aa00;stroke-width:0.16370411" + y="30.716068" + x="-302.27368" + id="tspan844-7" + sodipodi:role="line">HUBP</tspan><tspan + id="tspan863-0" + style="text-align:center;text-anchor:middle;fill:#44aa00;stroke-width:0.16370411" + y="38.901276" + x="-302.27368" + sodipodi:role="line">(1)</tspan></text> + <g + id="g1853-9"> + <rect + style="fill:none;fill-opacity:1;stroke:#55d400;stroke-width:0.94157624;stroke-linecap:butt;stroke-linejoin:bevel;stroke-miterlimit:4;stroke-dasharray:none;stroke-dashoffset:0" + id="rect1850-3" + width="24.708241" + height="17.224693" + x="-314.41837" + y="24.241148" /> + </g> + </g> + <g + transform="translate(-0.62971878,57.029814)" + id="g1878-8"> + <text + id="text846-7" + y="30.716068" + x="-302.27368" + 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:#44aa00;fill-opacity:1;stroke:none;stroke-width:0.16370411" + xml:space="preserve"><tspan + style="text-align:center;text-anchor:middle;fill:#44aa00;stroke-width:0.16370411" + y="30.716068" + x="-302.27368" + id="tspan844-9" + sodipodi:role="line">HUBP</tspan><tspan + id="tspan863-20" + style="text-align:center;text-anchor:middle;fill:#44aa00;stroke-width:0.16370411" + y="38.901276" + x="-302.27368" + sodipodi:role="line">(5)</tspan></text> + <g + id="g1853-2"> + <rect + style="fill:none;fill-opacity:1;stroke:#55d400;stroke-width:0.94157624;stroke-linecap:butt;stroke-linejoin:bevel;stroke-miterlimit:4;stroke-dasharray:none;stroke-dashoffset:0" + id="rect1850-37" + width="24.708241" + height="17.224693" + x="-314.41837" + y="24.241148" /> + </g> + </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="-310.7348" + y="72.106789" + id="text8862-5"><tspan + sodipodi:role="line" + id="tspan8860-9" + x="-310.7348" + y="72.106789" + style="font-style:normal;font-variant:normal;font-weight:bold;font-stretch:normal;font-size:14.11111069px;font-family:sans-serif;-inkscape-font-specification:'sans-serif Bold';fill:#44aa00;stroke-width:0.26458332">...</tspan></text> + <g + id="g2031" + transform="translate(-2.4568452,2.9399645)"> + <text + id="text838-5-3" + y="84.805916" + x="-254.56604" + 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 + style="text-align:center;text-anchor:middle;stroke-width:0.16370411" + y="84.805916" + x="-254.56604" + id="tspan836-3-6" + sodipodi:role="line">DPP</tspan><tspan + id="tspan936-1" + style="text-align:center;text-anchor:middle;stroke-width:0.16370411" + y="92.991119" + x="-254.56604" + sodipodi:role="line">(5)</tspan></text> + <rect + ry="7.8154301e-07" + y="73.432686" + x="-269.70468" + height="27.021317" + width="30.696136" + id="rect834-5-2" + style="fill:none;stroke:#000000;stroke-width:0.55864918;stroke-linecap:round;stroke-linejoin:bevel;stroke-miterlimit:4;stroke-dasharray:none" /> + </g> + <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-9)" + d="m -289.17681,89.892551 h 14.20296" + id="path1171-1" + 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-94)" + d="m -288.90777,32.862737 h 14.20296" + id="path1171" + 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="-264.85431" + y="62.072891" + id="text8862-5-8"><tspan + sodipodi:role="line" + id="tspan8860-9-4" + x="-264.85431" + y="62.072891" + style="font-style:normal;font-variant:normal;font-weight:bold;font-stretch:normal;font-size:14.11111069px;font-family:sans-serif;-inkscape-font-specification:'sans-serif Bold';fill:#000000;stroke-width:0.26458332">...</tspan></text> + <g + id="g2025-5" + transform="translate(40.522337,-1.1484419)" /> + <g + id="g7343" + transform="translate(40.522337,-1.2533369)"> + <text + id="text838-5-6" + y="31.969406" + x="-254.53119" + 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 + style="text-align:center;text-anchor:middle;stroke-width:0.16370411" + y="31.969406" + x="-254.53119" + id="tspan836-3-3" + sodipodi:role="line">MPC</tspan><tspan + id="tspan936-2" + style="text-align:center;text-anchor:middle;stroke-width:0.16370411" + y="40.15461" + x="-254.53119" + sodipodi:role="line">(0)</tspan></text> + <rect + ry="7.8154301e-07" + y="20.596174" + x="-269.66983" + height="27.021315" + width="30.696135" + id="rect834-5-0" + style="fill:none;stroke:#000000;stroke-width:0.55864918;stroke-linecap:round;stroke-linejoin:bevel;stroke-miterlimit:4;stroke-dasharray:none" /> + </g> + <g + id="g7343-1" + transform="translate(40.522337,56.303939)"> + <text + id="text838-5-6-5" + y="31.969406" + x="-254.53119" + 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 + style="text-align:center;text-anchor:middle;stroke-width:0.16370411" + y="31.969406" + x="-254.53119" + id="tspan836-3-3-5" + sodipodi:role="line">MPC</tspan><tspan + id="tspan936-2-4" + style="text-align:center;text-anchor:middle;stroke-width:0.16370411" + y="40.15461" + x="-254.53119" + sodipodi:role="line">(5)</tspan></text> + <rect + ry="7.8154301e-07" + y="20.596174" + x="-269.66983" + height="27.021315" + width="30.696135" + id="rect834-5-0-7" + style="fill:none;stroke:#000000;stroke-width:0.55864918;stroke-linecap:round;stroke-linejoin:bevel;stroke-miterlimit:4;stroke-dasharray:none" /> + </g> + <g + id="g7343-2" + transform="translate(84.178583,-1.2533369)"> + <text + id="text838-5-6-54" + y="31.969406" + x="-254.53119" + 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 + style="text-align:center;text-anchor:middle;stroke-width:0.16370411" + y="31.969406" + x="-254.53119" + id="tspan836-3-3-7" + sodipodi:role="line">OPP</tspan><tspan + id="tspan936-2-44" + style="text-align:center;text-anchor:middle;stroke-width:0.16370411" + y="40.15461" + x="-254.53119" + sodipodi:role="line">(0)</tspan></text> + <rect + ry="7.8154301e-07" + y="20.596174" + x="-269.66983" + height="27.021315" + width="30.696135" + id="rect834-5-0-3" + style="fill:none;stroke:#000000;stroke-width:0.55864918;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: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="-221.84029" + y="62.072891" + id="text8862-5-8-6"><tspan + sodipodi:role="line" + id="tspan8860-9-4-5" + x="-221.84029" + y="62.072891" + style="font-style:normal;font-variant:normal;font-weight:bold;font-stretch:normal;font-size:14.11111069px;font-family:sans-serif;-inkscape-font-specification:'sans-serif Bold';fill:#000000;stroke-width:0.26458332">...</tspan></text> + <path + style="fill:none;stroke:#ff0000;stroke-width:0.83149505;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:none;stroke-opacity:1;marker-end:url(#Arrow2Mend-94-6)" + d="m -240.90479,32.86192 h 10.61353" + id="path1171-3" + inkscape:connector-curvature="0" /> + <path + style="fill:none;stroke:#ff0000;stroke-width:0.83149505;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:none;stroke-opacity:1;marker-end:url(#Arrow2Mend-94-6-7)" + d="m -241.09039,89.891298 h 10.61353" + id="path1171-3-5" + inkscape:connector-curvature="0" /> + <path + style="fill:none;stroke:#ff0000;stroke-width:0.83149505;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:none;stroke-opacity:1;marker-end:url(#Arrow2Mend-94-6-0)" + d="m -198.19009,32.86192 h 10.61353" + id="path1171-3-8" + inkscape:connector-curvature="0" /> + <g + id="g7343-2-6" + transform="translate(84.178583,56.303939)"> + <text + id="text838-5-6-54-8" + y="31.969406" + x="-254.53119" + 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 + style="text-align:center;text-anchor:middle;stroke-width:0.16370411" + y="31.969406" + x="-254.53119" + id="tspan836-3-3-7-8" + sodipodi:role="line">OPP</tspan><tspan + id="tspan936-2-44-4" + style="text-align:center;text-anchor:middle;stroke-width:0.16370411" + y="40.15461" + x="-254.53119" + sodipodi:role="line">(0)</tspan></text> + <rect + ry="7.8154301e-07" + y="20.596174" + x="-269.66983" + height="27.021315" + width="30.696135" + id="rect834-5-0-3-3" + style="fill:none;stroke:#000000;stroke-width:0.55864918;stroke-linecap:round;stroke-linejoin:bevel;stroke-miterlimit:4;stroke-dasharray:none" /> + </g> + <path + style="fill:none;stroke:#ff0000;stroke-width:0.83149505;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:none;stroke-opacity:1;marker-end:url(#Arrow2Mend-94-6-0-1)" + d="m -198.00111,89.891298 h 10.61353" + id="path1171-3-8-9" + inkscape:connector-curvature="0" /> + <g + id="g7343-2-2" + transform="translate(127.15447,-1.1484419)"> + <text + id="text838-5-6-54-0" + y="65.122154" + x="-254.32814" + 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-2-44-8" + style="text-align:center;text-anchor:middle;stroke-width:0.16370411" + y="65.122154" + x="-254.32814" + sodipodi:role="line">OPTC</tspan></text> + <rect + ry="2.4256708e-06" + y="20.805576" + x="-269.46042" + height="83.865906" + width="30.277332" + id="rect834-5-0-3-9" + style="fill:none;stroke:#000000;stroke-width:0.97745234;stroke-linecap:round;stroke-linejoin:bevel;stroke-miterlimit:4;stroke-dasharray:none" /> + </g> + <path + style="fill:none;stroke:#ff0000;stroke-width:0.83149505;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:none;stroke-opacity:1;marker-end:url(#Arrow2Mend-94-6-0-2)" + d="m -154.34485,32.86192 h 10.61353" + id="path1171-3-8-6" + inkscape:connector-curvature="0" /> + <path + style="fill:none;stroke:#ff0000;stroke-width:0.83149505;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:none;stroke-opacity:1;marker-end:url(#Arrow2Mend-94-6-0-2-4)" + d="m -154.34485,89.891298 h 10.61353" + id="path1171-3-8-6-5" + 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="-178.18404" + y="62.072891" + id="text8862-5-8-6-0"><tspan + sodipodi:role="line" + id="tspan8860-9-4-5-4" + x="-178.18404" + y="62.072891" + style="font-style:normal;font-variant:normal;font-weight:bold;font-stretch:normal;font-size:14.11111069px;font-family:sans-serif;-inkscape-font-specification:'sans-serif Bold';fill:#000000;stroke-width:0.26458332">...</tspan></text> + <path + style="fill:#000000;stroke:#000000;stroke-width:0.96187615;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:none;stroke-opacity:1;marker-end:url(#Arrow2Mend-94-8)" + d="m -335.20986,59.030276 h 14.20296" + id="path1171-17" + 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.16370411" + x="-349.77686" + y="61.404655" + id="text838-2"><tspan + sodipodi:role="line" + id="tspan836-7" + x="-349.77686" + y="61.404655" + style="stroke-width:0.16370411">SDP</tspan></text> + <path + style="fill:none;stroke:#000000;stroke-width:1.32291663;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:1.32291667, 1.32291667;stroke-dashoffset:0;stroke-opacity:1" + d="M -279.04164,107.86706 V 0.89985833" + id="path11907" + inkscape:connector-curvature="0" /> + <path + style="fill:none;stroke:#000000;stroke-width:1.32291663;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:1.3229167, 1.3229167;stroke-dashoffset:0;stroke-opacity:1" + d="M -235.57438,107.86707 V 0.89985663" + id="path11907-6-1" + inkscape:connector-curvature="0" /> + <path + style="fill:none;stroke:#000000;stroke-width:1.32291663;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:1.32291671, 1.32291671;stroke-dashoffset:0;stroke-opacity:1" + d="M -149.96277,107.86707 V 0.89985223" + id="path11907-6-1-0" + 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.16370411" + x="-257.38275" + y="5.003336" + id="text838-6"><tspan + sodipodi:role="line" + id="tspan836-1" + x="-257.38275" + y="5.003336" + style="font-size:4.93888903px;text-align:center;text-anchor:middle;stroke-width:0.16370411">DPPCLK</tspan><tspan + sodipodi:role="line" + x="-257.38275" + y="13.188541" + style="font-size:4.93888903px;text-align:center;text-anchor:middle;stroke-width:0.16370411" + id="tspan12658">267.958Mhz</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.16370411" + x="-192.85298" + y="5.003336" + id="text838-6-5"><tspan + sodipodi:role="line" + id="tspan836-1-9" + x="-192.85298" + y="5.003336" + style="font-size:4.93888903px;text-align:center;text-anchor:middle;stroke-width:0.16370411">DISPCLK</tspan><tspan + sodipodi:role="line" + x="-192.85298" + y="13.188541" + style="font-size:4.93888903px;text-align:center;text-anchor:middle;stroke-width:0.16370411" + id="tspan12662">541.275 Mhz</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.16370411" + x="-302.03766" + y="5.003336" + id="text838-6-5-4"><tspan + sodipodi:role="line" + id="tspan836-1-9-9" + x="-312.23135" + y="5.003336" + style="font-size:4.93888903px;stroke-width:0.16370411;text-anchor:middle;text-align:center">DCFCLK</tspan><tspan + sodipodi:role="line" + x="-312.23135" + y="13.188541" + style="font-size:4.93888903px;stroke-width:0.16370411;text-anchor:middle;text-align:center" + id="tspan12660">506 Mhz</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.16370411" + x="-96.075348" + y="4.568048" + id="text838-6-5-0"><tspan + sodipodi:role="line" + id="tspan836-1-9-91" + x="-96.075348" + y="4.568048" + style="font-size:4.93888903px;stroke-width:0.16370411">SymCLK</tspan></text> + <g + id="g7343-2-2-7" + transform="translate(168.61494,-1.1484419)"> + <text + id="text838-5-6-54-0-7" + y="65.122154" + x="-254.32814" + 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-2-44-8-1" + style="text-align:center;text-anchor:middle;stroke-width:0.16370411" + y="65.122154" + x="-254.32814" + sodipodi:role="line">DIO</tspan></text> + <rect + ry="2.4256708e-06" + y="20.805576" + x="-269.46042" + height="83.865906" + width="30.277332" + id="rect834-5-0-3-9-1" + style="fill:none;stroke:#000000;stroke-width:0.97745234;stroke-linecap:round;stroke-linejoin:bevel;stroke-miterlimit:4;stroke-dasharray:none" /> + </g> + <path + style="fill:none;stroke:#000000;stroke-width:1.32291663;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:1.32291672, 1.32291672;stroke-dashoffset:0;stroke-opacity:1" + d="M -108.38539,107.86707 V 0.89985092" + id="path11907-6-1-0-5" + 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.16370411" + x="-143.52292" + y="5.0467439" + id="text838-6-5-0-9"><tspan + sodipodi:role="line" + id="tspan836-1-9-91-7" + x="-143.52292" + y="5.0467439" + style="font-size:4.93888903px;stroke-width:0.16370411">VirtualPCLK</tspan></text> + <path + style="fill:none;stroke:#ff0000;stroke-width:0.83149505;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:none;stroke-opacity:1;marker-end:url(#Arrow2Mend-94-6-0-2-7)" + d="m -112.24183,60.747629 h 10.61353" + id="path1171-3-8-6-7" + inkscape:connector-curvature="0" /> + </g> +</svg> diff --git a/Documentation/gpu/amdgpu/display/single-display-mpo-multi-video.svg b/Documentation/gpu/amdgpu/display/single-display-mpo-multi-video.svg new file mode 100644 index 000000000000..fa807115cfe2 --- /dev/null +++ b/Documentation/gpu/amdgpu/display/single-display-mpo-multi-video.svg @@ -0,0 +1,339 @@ +<?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="112.16296mm" + height="93.314507mm" + viewBox="0 0 112.16296 93.314508" + version="1.1" + id="svg8" + inkscape:version="0.92.5 (2060ec1f9f, 2020-04-08)" + sodipodi:docname="single-display-mpo-multi-video.svg"> + <defs + id="defs2"> + <marker + inkscape:stockid="TriangleOutL" + orient="auto" + refY="0" + refX="0" + id="TriangleOutL" + style="overflow:visible" + inkscape:isstock="true"> + <path + id="path1133" + d="M 5.77,0 -2.88,5 V -5 Z" + style="fill:#000000;fill-opacity:1;fill-rule:evenodd;stroke:#000000;stroke-width:1.00000003pt;stroke-opacity:1" + transform="scale(0.8)" + 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="path1006" + 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="TriangleOutL" + orient="auto" + refY="0" + refX="0" + id="TriangleOutL-6" + style="overflow:visible" + inkscape:isstock="true"> + <path + inkscape:connector-curvature="0" + id="path1133-0" + d="M 5.77,0 -2.88,5 V -5 Z" + style="fill:#000000;fill-opacity:1;fill-rule:evenodd;stroke:#000000;stroke-width:1.00000003pt;stroke-opacity:1" + transform="scale(0.8)" /> + </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="255.95284" + inkscape:cy="222.25473" + inkscape:document-units="mm" + inkscape:current-layer="layer1" + showgrid="false" + inkscape:window-width="1514" + inkscape:window-height="1376" + inkscape:window-x="1046" + inkscape:window-y="27" + inkscape:window-maximized="0" + fit-margin-top="0" + fit-margin-left="0" + fit-margin-right="0" + fit-margin-bottom="0" /> + <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(26.189925,5.2546503)"> + <text + xml:space="preserve" + style="font-style:normal;font-weight:normal;font-size:0.82813352px;line-height:1.25;font-family:sans-serif;letter-spacing:0px;word-spacing:0px;fill:#000000;fill-opacity:1;stroke:none;stroke-width:0.06901112" + x="-2.2053311" + y="32.839729" + id="text844"><tspan + sodipodi:role="line" + x="-2.2053313" + y="32.839729" + style="font-style:normal;font-variant:normal;font-weight:bold;font-stretch:normal;font-size:2.02432632px;font-family:sans-serif;-inkscape-font-specification:'sans-serif Bold';text-align:center;text-anchor:middle;stroke-width:0.06901112" + id="tspan846">Video Buffer (YUV)</tspan></text> + <text + xml:space="preserve" + style="font-style:normal;font-weight:normal;font-size:0.82813352px;line-height:1.25;font-family:sans-serif;letter-spacing:0px;word-spacing:0px;fill:#000000;fill-opacity:1;stroke:none;stroke-width:0.06901112" + x="30.867918" + y="87.638779" + id="text844-2"><tspan + sodipodi:role="line" + x="30.867918" + y="87.638779" + style="font-style:normal;font-variant:normal;font-weight:bold;font-stretch:normal;font-size:2.02432632px;font-family:sans-serif;-inkscape-font-specification:'sans-serif Bold';text-align:center;text-anchor:middle;stroke-width:0.06901112" + id="tspan846-0">CRTC Output</tspan></text> + <rect + style="fill:none;fill-opacity:1;stroke:#000000;stroke-width:0.53249496;stroke-linecap:butt;stroke-linejoin:bevel;stroke-miterlimit:4;stroke-dasharray:1.59748484, 0.53249495;stroke-dashoffset:0" + id="rect969" + width="111.63046" + height="44.238331" + x="-25.923677" + y="-4.9884028" /> + <text + xml:space="preserve" + style="font-style:normal;font-weight:normal;font-size:0.82813352px;line-height:1.25;font-family:sans-serif;letter-spacing:0px;word-spacing:0px;fill:#000000;fill-opacity:1;stroke:none;stroke-width:0.06901112" + x="48.037342" + y="45.781586" + id="text844-2-9"><tspan + sodipodi:role="line" + x="48.037342" + y="45.781586" + style="font-style:normal;font-variant:normal;font-weight:bold;font-stretch:normal;font-size:2.02432632px;font-family:sans-serif;-inkscape-font-specification:'sans-serif Bold';text-align:center;text-anchor:middle;stroke-width:0.06901112" + id="tspan2868">Hardware Composition</tspan></text> + <path + style="fill:none;stroke:#000000;stroke-width:0.48997903;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:none;stroke-opacity:1;marker-end:url(#TriangleOutL)" + d="m 32.66992,40.326865 v 9.760144" + id="path989" + inkscape:connector-curvature="0" /> + <g + id="g4447" + style="stroke:#000000"> + <rect + ry="0" + y="0.23764905" + x="-23.784248" + height="29.48851" + width="48.988979" + id="rect836" + style="fill:#000000;fill-opacity:1;stroke:#000000;stroke-width:0.62916809;stroke-linecap:round;stroke-linejoin:bevel;stroke-miterlimit:4;stroke-dasharray:none;stroke-dashoffset:0" /> + <rect + ry="0" + y="3.8184125" + x="-20.589451" + height="6.9794898" + width="11.594959" + id="rect836-2-6" + style="fill:#008000;fill-opacity:1;stroke:#000000;stroke-width:0.14891468;stroke-linecap:round;stroke-linejoin:bevel;stroke-miterlimit:4;stroke-dasharray:none;stroke-dashoffset:0" /> + <rect + ry="0" + y="3.8184123" + x="-5.6613555" + height="6.9794903" + width="11.594959" + id="rect836-2-6-1" + style="fill:#008000;fill-opacity:1;stroke:#000000;stroke-width:0.14891469;stroke-linecap:round;stroke-linejoin:bevel;stroke-miterlimit:4;stroke-dasharray:none;stroke-dashoffset:0" /> + <rect + ry="0" + y="3.8184121" + x="10.374816" + height="6.9794908" + width="11.594959" + id="rect836-2-6-1-8" + style="fill:#008000;fill-opacity:1;stroke:#000000;stroke-width:0.14891469;stroke-linecap:round;stroke-linejoin:bevel;stroke-miterlimit:4;stroke-dasharray:none;stroke-dashoffset:0" /> + <rect + ry="0" + y="18.386644" + x="-20.341679" + height="6.9794903" + width="11.594959" + id="rect836-2-6-7" + style="fill:#008000;fill-opacity:1;stroke:#000000;stroke-width:0.14891469;stroke-linecap:round;stroke-linejoin:bevel;stroke-miterlimit:4;stroke-dasharray:none;stroke-dashoffset:0" /> + <rect + ry="0" + y="18.386644" + x="-5.4135842" + height="6.9794908" + width="11.594959" + id="rect836-2-6-1-9" + style="fill:#008000;fill-opacity:1;stroke:#000000;stroke-width:0.14891469;stroke-linecap:round;stroke-linejoin:bevel;stroke-miterlimit:4;stroke-dasharray:none;stroke-dashoffset:0" /> + <rect + ry="0" + y="18.386644" + x="10.622585" + height="6.9794908" + width="11.594959" + id="rect836-2-6-1-8-2" + style="fill:#008000;fill-opacity:1;stroke:#000000;stroke-width:0.14891469;stroke-linecap:round;stroke-linejoin:bevel;stroke-miterlimit:4;stroke-dasharray:none;stroke-dashoffset:0" /> + </g> + <rect + style="fill:#808080;fill-opacity:1;stroke:#808080;stroke-width:0.62916809;stroke-linecap:round;stroke-linejoin:bevel;stroke-miterlimit:4;stroke-dasharray:none;stroke-dashoffset:0" + id="rect836-2" + width="48.988979" + height="29.48851" + x="31.367332" + y="0.45039755" + ry="0" /> + <rect + style="fill:#ffffff;fill-opacity:1;stroke:none;stroke-width:0.14891468;stroke-linecap:round;stroke-linejoin:bevel;stroke-miterlimit:4;stroke-dasharray:none;stroke-dashoffset:0" + id="rect836-2-6-3" + width="11.594959" + height="6.9794898" + x="34.56213" + y="4.0311608" + ry="0" /> + <rect + style="fill:#ffffff;fill-opacity:1;stroke:none;stroke-width:0.14891469;stroke-linecap:round;stroke-linejoin:bevel;stroke-miterlimit:4;stroke-dasharray:none;stroke-dashoffset:0" + id="rect836-2-6-1-7" + width="11.594959" + height="6.9794903" + x="49.490223" + y="4.0311608" + ry="0" /> + <rect + style="fill:#ffffff;fill-opacity:1;stroke:none;stroke-width:0.14891469;stroke-linecap:round;stroke-linejoin:bevel;stroke-miterlimit:4;stroke-dasharray:none;stroke-dashoffset:0" + id="rect836-2-6-1-8-5" + width="11.594959" + height="6.9794908" + x="65.526398" + y="4.0311604" + ry="0" /> + <rect + style="fill:#ffffff;fill-opacity:1;stroke:none;stroke-width:0.14891469;stroke-linecap:round;stroke-linejoin:bevel;stroke-miterlimit:4;stroke-dasharray:none;stroke-dashoffset:0" + id="rect836-2-6-7-9" + width="11.594959" + height="6.9794903" + x="34.809902" + y="18.599392" + ry="0" /> + <rect + style="fill:#ffffff;fill-opacity:1;stroke:none;stroke-width:0.14891469;stroke-linecap:round;stroke-linejoin:bevel;stroke-miterlimit:4;stroke-dasharray:none;stroke-dashoffset:0" + id="rect836-2-6-1-9-2" + width="11.594959" + height="6.9794908" + x="49.737995" + y="18.599392" + ry="0" /> + <rect + style="fill:#ffffff;fill-opacity:1;stroke:none;stroke-width:0.14891469;stroke-linecap:round;stroke-linejoin:bevel;stroke-miterlimit:4;stroke-dasharray:none;stroke-dashoffset:0" + id="rect836-2-6-1-8-2-2" + width="11.594959" + height="6.9794908" + x="65.774162" + y="18.599392" + ry="0" /> + <g + id="g4562" + transform="translate(0,11.22532)"> + <rect + ry="0" + y="43.21352" + x="5.9767256" + height="29.48851" + width="48.988979" + id="rect836-97" + style="fill:#808080;fill-opacity:1;stroke:#808080;stroke-width:0.62916809;stroke-linecap:round;stroke-linejoin:bevel;stroke-miterlimit:4;stroke-dasharray:none;stroke-dashoffset:0" /> + <rect + ry="0" + y="46.794285" + x="9.1715231" + height="6.9794898" + width="11.594959" + id="rect836-2-6-36" + style="fill:#008000;fill-opacity:1;stroke:#000000;stroke-width:0.14891468;stroke-linecap:round;stroke-linejoin:bevel;stroke-miterlimit:4;stroke-dasharray:none;stroke-dashoffset:0" /> + <rect + ry="0" + y="46.794285" + x="24.099619" + height="6.9794903" + width="11.594959" + id="rect836-2-6-1-1" + style="fill:#008000;fill-opacity:1;stroke:#000000;stroke-width:0.14891469;stroke-linecap:round;stroke-linejoin:bevel;stroke-miterlimit:4;stroke-dasharray:none;stroke-dashoffset:0" /> + <rect + ry="0" + y="46.794285" + x="40.135792" + height="6.9794908" + width="11.594959" + id="rect836-2-6-1-8-29" + style="fill:#008000;fill-opacity:1;stroke:#000000;stroke-width:0.14891469;stroke-linecap:round;stroke-linejoin:bevel;stroke-miterlimit:4;stroke-dasharray:none;stroke-dashoffset:0" /> + <rect + ry="0" + y="61.362514" + x="9.4192953" + height="6.9794903" + width="11.594959" + id="rect836-2-6-7-3" + style="fill:#008000;fill-opacity:1;stroke:#000000;stroke-width:0.14891469;stroke-linecap:round;stroke-linejoin:bevel;stroke-miterlimit:4;stroke-dasharray:none;stroke-dashoffset:0" /> + <rect + ry="0" + y="61.362514" + x="24.347389" + height="6.9794908" + width="11.594959" + id="rect836-2-6-1-9-1" + style="fill:#008000;fill-opacity:1;stroke:#000000;stroke-width:0.14891469;stroke-linecap:round;stroke-linejoin:bevel;stroke-miterlimit:4;stroke-dasharray:none;stroke-dashoffset:0" /> + <rect + ry="0" + y="61.362514" + x="40.38356" + height="6.9794908" + width="11.594959" + id="rect836-2-6-1-8-2-9" + style="fill:#008000;fill-opacity:1;stroke:#000000;stroke-width:0.14891469;stroke-linecap:round;stroke-linejoin:bevel;stroke-miterlimit:4;stroke-dasharray:none;stroke-dashoffset:0" /> + </g> + <text + xml:space="preserve" + style="font-style:normal;font-weight:normal;font-size:0.82813358px;line-height:1.25;font-family:sans-serif;letter-spacing:0px;word-spacing:0px;fill:#000000;fill-opacity:1;stroke:none;stroke-width:0.06901112" + x="57.012939" + y="33.603645" + id="text844-4"><tspan + sodipodi:role="line" + x="57.012939" + y="33.603645" + style="font-style:normal;font-variant:normal;font-weight:bold;font-stretch:normal;font-size:2.02432632px;font-family:sans-serif;-inkscape-font-specification:'sans-serif Bold';text-align:center;text-anchor:middle;stroke-width:0.06901112" + id="tspan846-7">Desktop Buffer (ARGB)</tspan></text> + </g> +</svg> diff --git a/Documentation/gpu/amdgpu/display/single-display-mpo.svg b/Documentation/gpu/amdgpu/display/single-display-mpo.svg new file mode 100644 index 000000000000..fb53b0920c87 --- /dev/null +++ b/Documentation/gpu/amdgpu/display/single-display-mpo.svg @@ -0,0 +1,266 @@ +<?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="148.71147mm" + height="38.356358mm" + viewBox="0 0 148.71148 38.356358" + version="1.1" + id="svg8" + inkscape:version="0.92.5 (2060ec1f9f, 2020-04-08)" + sodipodi:docname="single-display-mpo.svg"> + <defs + id="defs2"> + <marker + inkscape:stockid="TriangleOutL" + orient="auto" + refY="0" + refX="0" + id="TriangleOutL" + style="overflow:visible" + inkscape:isstock="true"> + <path + id="path1133" + d="M 5.77,0 -2.88,5 V -5 Z" + style="fill:#000000;fill-opacity:1;fill-rule:evenodd;stroke:#000000;stroke-width:1.00000003pt;stroke-opacity:1" + transform="scale(0.8)" + 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="path1006" + 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="TriangleOutL" + orient="auto" + refY="0" + refX="0" + id="TriangleOutL-6" + style="overflow:visible" + inkscape:isstock="true"> + <path + inkscape:connector-curvature="0" + id="path1133-0" + d="M 5.77,0 -2.88,5 V -5 Z" + style="fill:#000000;fill-opacity:1;fill-rule:evenodd;stroke:#000000;stroke-width:1.00000003pt;stroke-opacity:1" + transform="scale(0.8)" /> + </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="266.07058" + inkscape:cy="81.254796" + inkscape:document-units="mm" + inkscape:current-layer="layer1" + showgrid="false" + inkscape:window-width="1514" + inkscape:window-height="1376" + inkscape:window-x="1046" + inkscape:window-y="27" + inkscape:window-maximized="0" + fit-margin-top="0" + fit-margin-left="0" + fit-margin-right="0" + fit-margin-bottom="0" /> + <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(26.323559,-14.790568)"> + <rect + style="fill:#999999;fill-opacity:1;stroke:#999999;stroke-width:0.62916809;stroke-linecap:round;stroke-linejoin:bevel;stroke-miterlimit:4;stroke-dasharray:none;stroke-dashoffset:0" + id="rect836" + width="48.988979" + height="29.48851" + x="4.9472256" + y="17.075632" + ry="0" /> + <g + id="g905" + transform="matrix(0.26082945,0,0,0.26082945,-26.950235,-0.99631462)"> + <rect + y="67.568451" + x="12.473214" + height="60.854164" + width="102.43154" + id="rect834" + style="fill:#008000;fill-opacity:1;stroke:none;stroke-width:2;stroke-linecap:round;stroke-linejoin:bevel;stroke-miterlimit:4;stroke-dasharray:none;stroke-dashoffset:0" /> + <path + inkscape:transform-center-y="-3.581986e-06" + inkscape:transform-center-x="-3.3106064" + d="m 73.620805,97.995537 -9.931819,5.734143 -9.931819,5.73413 0,-11.468274 0,-11.468276 9.931819,5.734139 z" + inkscape:randomized="0" + inkscape:rounded="0" + inkscape:flatsided="false" + sodipodi:arg2="1.0471976" + sodipodi:arg1="0" + sodipodi:r2="6.6212125" + sodipodi:r1="13.242425" + sodipodi:cy="97.995537" + sodipodi:cx="60.37838" + sodipodi:sides="3" + id="path840" + style="fill:#ffffff;fill-opacity:1;stroke:none;stroke-width:1.22854495;stroke-linecap:round;stroke-linejoin:bevel;stroke-miterlimit:4;stroke-dasharray:none;stroke-dashoffset:0" + sodipodi:type="star" /> + </g> + <text + xml:space="preserve" + style="font-style:normal;font-weight:normal;font-size:0.82813352px;line-height:1.25;font-family:sans-serif;letter-spacing:0px;word-spacing:0px;fill:#000000;fill-opacity:1;stroke:none;stroke-width:0.06901112" + x="-10.357052" + y="34.176075" + id="text844"><tspan + sodipodi:role="line" + id="tspan842" + x="-10.357052" + y="34.176075" + style="font-style:normal;font-variant:normal;font-weight:bold;font-stretch:normal;font-size:2.02432632px;font-family:sans-serif;-inkscape-font-specification:'sans-serif Bold';text-align:center;text-anchor:middle;stroke-width:0.06901112">Video Buffer (YUV)</tspan><tspan + sodipodi:role="line" + x="-10.357052" + y="36.706482" + style="font-style:normal;font-variant:normal;font-weight:bold;font-stretch:normal;font-size:2.02432632px;font-family:sans-serif;-inkscape-font-specification:'sans-serif Bold';text-align:center;text-anchor:middle;stroke-width:0.06901112" + id="tspan846">DRM PRIMARY PLANE</tspan></text> + <rect + style="fill:#ffffff;fill-opacity:1;stroke:none;stroke-width:0.5216589;stroke-linecap:round;stroke-linejoin:bevel;stroke-miterlimit:4;stroke-dasharray:none;stroke-dashoffset:0" + id="rect834-3" + width="26.717165" + height="15.872559" + x="16.083126" + y="23.883608" /> + <text + xml:space="preserve" + style="font-style:normal;font-weight:normal;font-size:0.82813352px;line-height:1.25;font-family:sans-serif;letter-spacing:0px;word-spacing:0px;fill:#000000;fill-opacity:1;stroke:none;stroke-width:0.06901112" + x="28.437061" + y="49.158085" + id="text844-6"><tspan + sodipodi:role="line" + x="28.437061" + y="49.158085" + style="font-style:normal;font-variant:normal;font-weight:bold;font-stretch:normal;font-size:2.02432632px;font-family:sans-serif;-inkscape-font-specification:'sans-serif Bold';text-align:center;text-anchor:middle;stroke-width:0.06901112" + id="tspan846-5">Desktop Buffer (ARGB)</tspan><tspan + sodipodi:role="line" + x="28.437061" + y="51.688492" + style="font-style:normal;font-variant:normal;font-weight:bold;font-stretch:normal;font-size:2.02432632px;font-family:sans-serif;-inkscape-font-specification:'sans-serif Bold';text-align:center;text-anchor:middle;stroke-width:0.06901112" + id="tspan886">DRM OVERLAY PLANE</tspan></text> + <g + id="g2874" + transform="matrix(1.0858687,0,0,1.0858687,-4.5597909,-2.06277)"> + <rect + ry="0" + y="17.624969" + x="71.504173" + height="27.156607" + width="45.115009" + id="rect836-9" + style="fill:#999999;fill-opacity:1;stroke:#999999;stroke-width:0.57941455;stroke-linecap:round;stroke-linejoin:bevel;stroke-miterlimit:4;stroke-dasharray:none;stroke-dashoffset:0" /> + <g + id="g905-5" + transform="matrix(0.24020349,0,0,0.24020349,78.763353,7.664402)"> + <rect + style="fill:#008000;fill-opacity:1;stroke:none;stroke-width:2;stroke-linecap:round;stroke-linejoin:bevel;stroke-miterlimit:4;stroke-dasharray:none;stroke-dashoffset:0" + id="rect834-6" + width="102.43154" + height="60.854164" + x="12.473214" + y="67.568451" /> + <path + sodipodi:type="star" + style="fill:#ffffff;fill-opacity:1;stroke:none;stroke-width:1.22854495;stroke-linecap:round;stroke-linejoin:bevel;stroke-miterlimit:4;stroke-dasharray:none;stroke-dashoffset:0" + id="path840-2" + sodipodi:sides="3" + sodipodi:cx="60.37838" + sodipodi:cy="97.995537" + sodipodi:r1="13.242425" + sodipodi:r2="6.6212125" + sodipodi:arg1="0" + sodipodi:arg2="1.0471976" + inkscape:flatsided="false" + inkscape:rounded="0" + inkscape:randomized="0" + d="m 73.620805,97.995537 -9.931819,5.734143 -9.931819,5.73413 0,-11.468274 0,-11.468276 9.931819,5.734139 z" + inkscape:transform-center-x="-3.3106064" + inkscape:transform-center-y="-3.581986e-06" /> + </g> + </g> + <text + xml:space="preserve" + style="font-style:normal;font-weight:normal;font-size:0.82813352px;line-height:1.25;font-family:sans-serif;letter-spacing:0px;word-spacing:0px;fill:#000000;fill-opacity:1;stroke:none;stroke-width:0.06901112" + x="97.551666" + y="50.221046" + id="text844-2"><tspan + sodipodi:role="line" + x="97.551666" + y="50.221046" + style="font-style:normal;font-variant:normal;font-weight:bold;font-stretch:normal;font-size:2.02432632px;font-family:sans-serif;-inkscape-font-specification:'sans-serif Bold';text-align:center;text-anchor:middle;stroke-width:0.06901112" + id="tspan846-0">CRTC Output</tspan></text> + <rect + style="fill:none;fill-opacity:1;stroke:#000000;stroke-width:0.42211887;stroke-linecap:butt;stroke-linejoin:bevel;stroke-miterlimit:4;stroke-dasharray:1.26635657, 0.42211886;stroke-dashoffset:0" + id="rect969" + width="81.806648" + height="37.934238" + x="-26.112499" + y="15.001627" /> + <text + xml:space="preserve" + style="font-style:normal;font-weight:normal;font-size:0.82813352px;line-height:1.25;font-family:sans-serif;letter-spacing:0px;word-spacing:0px;fill:#000000;fill-opacity:1;stroke:none;stroke-width:0.06901112" + x="64.474419" + y="31.883568" + id="text844-2-9"><tspan + sodipodi:role="line" + x="64.474419" + y="31.883568" + style="font-style:normal;font-variant:normal;font-weight:bold;font-stretch:normal;font-size:2.02432632px;font-family:sans-serif;-inkscape-font-specification:'sans-serif Bold';text-align:center;text-anchor:middle;stroke-width:0.06901112" + id="tspan846-0-3">Hardware</tspan><tspan + sodipodi:role="line" + x="64.474419" + y="34.413975" + style="font-style:normal;font-variant:normal;font-weight:bold;font-stretch:normal;font-size:2.02432632px;font-family:sans-serif;-inkscape-font-specification:'sans-serif Bold';text-align:center;text-anchor:middle;stroke-width:0.06901112" + id="tspan2868">Composition</tspan></text> + <path + style="fill:none;stroke:#000000;stroke-width:0.48997903;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:none;stroke-opacity:1;marker-end:url(#TriangleOutL)" + d="m 57.401149,24.81643 h 9.760144" + id="path989" + inkscape:connector-curvature="0" /> + <path + style="fill:none;stroke:#000000;stroke-width:0.48997903;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:none;stroke-opacity:1;marker-end:url(#TriangleOutL-6)" + d="m 57.401149,41.794278 h 9.760144" + id="path989-6" + inkscape:connector-curvature="0" /> + </g> +</svg> diff --git a/Documentation/gpu/amdgpu/driver-misc.rst b/Documentation/gpu/amdgpu/driver-misc.rst index e3d6b2fa2493..1800543d45f7 100644 --- a/Documentation/gpu/amdgpu/driver-misc.rst +++ b/Documentation/gpu/amdgpu/driver-misc.rst @@ -32,6 +32,23 @@ unique_id .. kernel-doc:: drivers/gpu/drm/amd/pm/amdgpu_pm.c :doc: unique_id +Accelerated Processing Units (APU) Info +--------------------------------------- + +.. csv-table:: + :header-rows: 1 + :widths: 3, 2, 2, 1, 1, 1 + :file: ./apu-asic-info-table.csv + +Discrete GPU Info +----------------- + +.. csv-table:: + :header-rows: 1 + :widths: 3, 2, 2, 1, 1, 1 + :file: ./dgpu-asic-info-table.csv + + GPU Memory Usage Information ============================ diff --git a/Documentation/gpu/amdgpu/thermal.rst b/Documentation/gpu/amdgpu/thermal.rst index 997231b6adcf..5e27e4eb3959 100644 --- a/Documentation/gpu/amdgpu/thermal.rst +++ b/Documentation/gpu/amdgpu/thermal.rst @@ -72,7 +72,8 @@ card's RLC (RunList Controller) firmware powers off the gfx engine dynamically when there is no workload on gfx or compute pipes. GFXOFF is on by default on supported GPUs. -Userspace can interact with GFXOFF through a debugfs interface: +Userspace can interact with GFXOFF through a debugfs interface (all values in +`uint32_t`, unless otherwise noted): ``amdgpu_gfxoff`` ----------------- @@ -104,3 +105,18 @@ Read it to check current GFXOFF's status of a GPU:: If GFXOFF is enabled, the value will be transitioning around [0, 3], always getting into 0 when possible. When it's disabled, it's always at 2. Returns ``-EINVAL`` if it's not supported. + +``amdgpu_gfxoff_count`` +----------------------- + +Read it to get the total GFXOFF entry count at the time of query since system +power-up. The value is an `uint64_t` type, however, due to firmware limitations, +it can currently overflow as an `uint32_t`. *Only supported in vangogh* + +``amdgpu_gfxoff_residency`` +--------------------------- + +Write 1 to amdgpu_gfxoff_residency to start logging, and 0 to stop. Read it to +get average GFXOFF residency % multiplied by 100 during the last logging +interval. E.g. a value of 7854 means 78.54% of the time in the last logging +interval the GPU was in GFXOFF mode. *Only supported in vangogh* diff --git a/Documentation/gpu/drm-kms-helpers.rst b/Documentation/gpu/drm-kms-helpers.rst index 2d473bc64c9f..dbc85fd7a971 100644 --- a/Documentation/gpu/drm-kms-helpers.rst +++ b/Documentation/gpu/drm-kms-helpers.rst @@ -122,13 +122,13 @@ format Helper Functions Reference .. kernel-doc:: drivers/gpu/drm/drm_format_helper.c :export: -Framebuffer CMA Helper Functions Reference +Framebuffer DMA Helper Functions Reference ========================================== -.. kernel-doc:: drivers/gpu/drm/drm_fb_cma_helper.c - :doc: framebuffer cma helper functions +.. kernel-doc:: drivers/gpu/drm/drm_fb_dma_helper.c + :doc: framebuffer dma helper functions -.. kernel-doc:: drivers/gpu/drm/drm_fb_cma_helper.c +.. kernel-doc:: drivers/gpu/drm/drm_fb_dma_helper.c :export: Framebuffer GEM Helper Reference diff --git a/Documentation/gpu/drm-kms.rst b/Documentation/gpu/drm-kms.rst index 6f9c064fd323..b4377a545425 100644 --- a/Documentation/gpu/drm-kms.rst +++ b/Documentation/gpu/drm-kms.rst @@ -532,6 +532,8 @@ Standard Plane Properties .. kernel-doc:: drivers/gpu/drm/drm_plane.c :doc: standard plane properties +.. _plane_composition_properties: + Plane Composition Properties ---------------------------- diff --git a/Documentation/gpu/drm-mm.rst b/Documentation/gpu/drm-mm.rst index f32ccce5722d..a79fd3549ff8 100644 --- a/Documentation/gpu/drm-mm.rst +++ b/Documentation/gpu/drm-mm.rst @@ -300,12 +300,12 @@ Drivers that want to map the GEM object upfront instead of handling page faults can implement their own mmap file operation handler. For platforms without MMU the GEM core provides a helper method -drm_gem_cma_get_unmapped_area(). The mmap() routines will call this to get a +drm_gem_dma_get_unmapped_area(). The mmap() routines will call this to get a proposed address for the mapping. -To use drm_gem_cma_get_unmapped_area(), drivers must fill the struct +To use drm_gem_dma_get_unmapped_area(), drivers must fill the struct :c:type:`struct file_operations <file_operations>` get_unmapped_area field with -a pointer on drm_gem_cma_get_unmapped_area(). +a pointer on drm_gem_dma_get_unmapped_area(). More detailed information about get_unmapped_area can be found in Documentation/admin-guide/mm/nommu-mmap.rst @@ -355,16 +355,16 @@ GEM Function Reference .. kernel-doc:: drivers/gpu/drm/drm_gem.c :export: -GEM CMA Helper Functions Reference +GEM DMA Helper Functions Reference ---------------------------------- -.. kernel-doc:: drivers/gpu/drm/drm_gem_cma_helper.c - :doc: cma helpers +.. kernel-doc:: drivers/gpu/drm/drm_gem_dma_helper.c + :doc: dma helpers -.. kernel-doc:: include/drm/drm_gem_cma_helper.h +.. kernel-doc:: include/drm/drm_gem_dma_helper.h :internal: -.. kernel-doc:: drivers/gpu/drm/drm_gem_cma_helper.c +.. kernel-doc:: drivers/gpu/drm/drm_gem_dma_helper.c :export: GEM SHMEM Helper Function Reference diff --git a/Documentation/gpu/todo.rst b/Documentation/gpu/todo.rst index 513b20ccef1e..393d218e4a0c 100644 --- a/Documentation/gpu/todo.rst +++ b/Documentation/gpu/todo.rst @@ -322,18 +322,6 @@ Contact: Daniel Vetter, Noralf Tronnes Level: Advanced -idr_init_base() ---------------- - -DRM core&drivers uses a lot of idr (integer lookup directories) for mapping -userspace IDs to internal objects, and in most places ID=0 means NULL and hence -is never used. Switching to idr_init_base() for these would make the idr more -efficient. - -Contact: Daniel Vetter - -Level: Starter - struct drm_gem_object_funcs --------------------------- @@ -343,19 +331,6 @@ converted, except for struct drm_driver.gem_prime_mmap. Level: Intermediate -Rename CMA helpers to DMA helpers ---------------------------------- - -CMA (standing for contiguous memory allocator) is really a bit an accident of -what these were used for first, a much better name would be DMA helpers. In the -text these should even be called coherent DMA memory helpers (so maybe CDM, but -no one knows what that means) since underneath they just use dma_alloc_coherent. - -Contact: Laurent Pinchart, Daniel Vetter - -Level: Intermediate (mostly because it is a huge tasks without good partial -milestones, not technically itself that challenging) - connector register/unregister fixes ----------------------------------- @@ -617,17 +592,6 @@ Contact: Javier Martinez Canillas <javierm@redhat.com> Level: Intermediate -Convert Kernel Selftests (kselftest) to KUnit tests when appropriate --------------------------------------------------------------------- - -Many of the `Kselftest <https://www.kernel.org/doc/html/latest/dev-tools/kselftest.html>`_ -tests in DRM could be converted to Kunit tests instead, since that framework -is more suitable for unit testing. - -Contact: Javier Martinez Canillas <javierm@redhat.com> - -Level: Starter - Enable trinity for DRM ---------------------- @@ -715,6 +679,74 @@ Contact: Sam Ravnborg Level: Advanced +Brightness handling on devices with multiple internal panels +============================================================ + +On x86/ACPI devices there can be multiple backlight firmware interfaces: +(ACPI) video, vendor specific and others. As well as direct/native (PWM) +register programming by the KMS driver. + +To deal with this backlight drivers used on x86/ACPI call +acpi_video_get_backlight_type() which has heuristics (+quirks) to select +which backlight interface to use; and backlight drivers which do not match +the returned type will not register themselves, so that only one backlight +device gets registered (in a single GPU setup, see below). + +At the moment this more or less assumes that there will only +be 1 (internal) panel on a system. + +On systems with 2 panels this may be a problem, depending on +what interface acpi_video_get_backlight_type() selects: + +1. native: in this case the KMS driver is expected to know which backlight + device belongs to which output so everything should just work. +2. video: this does support controlling multiple backlights, but some work + will need to be done to get the output <-> backlight device mapping + +The above assumes both panels will require the same backlight interface type. +Things will break on systems with multiple panels where the 2 panels need +a different type of control. E.g. one panel needs ACPI video backlight control, +where as the other is using native backlight control. Currently in this case +only one of the 2 required backlight devices will get registered, based on +the acpi_video_get_backlight_type() return value. + +If this (theoretical) case ever shows up, then supporting this will need some +work. A possible solution here would be to pass a device and connector-name +to acpi_video_get_backlight_type() so that it can deal with this. + +Note in a way we already have a case where userspace sees 2 panels, +in dual GPU laptop setups with a mux. On those systems we may see +either 2 native backlight devices; or 2 native backlight devices. + +Userspace already has code to deal with this by detecting if the related +panel is active (iow which way the mux between the GPU and the panels +points) and then uses that backlight device. Userspace here very much +assumes a single panel though. It picks only 1 of the 2 backlight devices +and then only uses that one. + +Note that all userspace code (that I know off) is currently hardcoded +to assume a single panel. + +Before the recent changes to not register multiple (e.g. video + native) +/sys/class/backlight devices for a single panel (on a single GPU laptop), +userspace would see multiple backlight devices all controlling the same +backlight. + +To deal with this userspace had to always picks one preferred device under +/sys/class/backlight and will ignore the others. So to support brightness +control on multiple panels userspace will need to be updated too. + +There are plans to allow brightness control through the KMS API by adding +a "display brightness" property to drm_connector objects for panels. This +solves a number of issues with the /sys/class/backlight API, including not +being able to map a sysfs backlight device to a specific connector. Any +userspace changes to add support for brightness control on devices with +multiple panels really should build on top of this new KMS property. + +Contact: Hans de Goede + +Level: Advanced + Outside DRM =========== diff --git a/Documentation/gpu/vkms.rst b/Documentation/gpu/vkms.rst index 973e2d43108b..49db221c0f52 100644 --- a/Documentation/gpu/vkms.rst +++ b/Documentation/gpu/vkms.rst @@ -118,15 +118,10 @@ Add Plane Features There's lots of plane features we could add support for: -- Clearing primary plane: clear primary plane before plane composition (at the - start) for correctness of pixel blend ops. It also guarantees alpha channel - is cleared in the target buffer for stable crc. [Good to get started] - - ARGB format on primary plane: blend the primary plane into background with translucent alpha. -- Support when the primary plane isn't exactly matching the output size: blend - the primary plane into the black background. +- Add background color KMS property[Good to get started]. - Full alpha blending on all planes. diff --git a/Documentation/hwmon/aquacomputer_d5next.rst b/Documentation/hwmon/aquacomputer_d5next.rst index 33649a1e3a05..e238533b5fe0 100644 --- a/Documentation/hwmon/aquacomputer_d5next.rst +++ b/Documentation/hwmon/aquacomputer_d5next.rst @@ -10,6 +10,7 @@ Supported devices: * Aquacomputer Farbwerk 360 RGB controller * Aquacomputer Octo fan controller * Aquacomputer Quadro fan controller +* Aquacomputer High Flow Next sensor Author: Aleksa Savic @@ -20,10 +21,11 @@ This driver exposes hardware sensors of listed Aquacomputer devices, which communicate through proprietary USB HID protocols. For the D5 Next pump, available sensors are pump and fan speed, power, voltage -and current, as well as coolant temperature. Also available through debugfs are -the serial number, firmware version and power-on count. Attaching a fan to it is -optional and allows it to be controlled using temperature curves directly from the -pump. If it's not connected, the fan-related sensors will report zeroes. +and current, as well as coolant temperature and eight virtual temp sensors. Also +available through debugfs are the serial number, firmware version and power-on +count. Attaching a fan to it is optional and allows it to be controlled using +temperature curves directly from the pump. If it's not connected, the fan-related +sensors will report zeroes. The pump can be configured either through software or via its physical interface. Configuring the pump through this driver is not implemented, as it @@ -31,14 +33,23 @@ seems to require sending it a complete configuration. That includes addressable RGB LEDs, for which there is no standard sysfs interface. Thus, that task is better suited for userspace tools. -The Octo exposes four temperature sensors and eight PWM controllable fans, along -with their speed (in RPM), power, voltage and current. +The Octo exposes four physical and sixteen virtual temperature sensors, as well as +eight PWM controllable fans, along with their speed (in RPM), power, voltage and +current. -The Quadro exposes four temperature sensors, a flow sensor and four PWM controllable -fans, along with their speed (in RPM), power, voltage and current. +The Quadro exposes four physical and sixteen virtual temperature sensors, a flow +sensor and four PWM controllable fans, along with their speed (in RPM), power, +voltage and current. -The Farbwerk and Farbwerk 360 expose four temperature sensors. Depending on the device, -not all sysfs and debugfs entries will be available. +The Farbwerk and Farbwerk 360 expose four temperature sensors. Additionally, +sixteen virtual temperature sensors of the Farbwerk 360 are exposed. + +The High Flow Next exposes +5V voltages, water quality, conductivity and flow readings. +A temperature sensor can be connected to it, in which case it provides its reading +and an estimation of the dissipated/absorbed power in the liquid cooling loop. + +Depending on the device, not all sysfs and debugfs entries will be available. +Writing to virtual temperature sensors is not currently supported. Usage notes ----------- @@ -49,14 +60,14 @@ the kernel and supports hotswapping. Sysfs entries ------------- -================ ============================================== -temp[1-4]_input Temperature sensors (in millidegrees Celsius) +================ ============================================================== +temp[1-20]_input Physical/virtual temperature sensors (in millidegrees Celsius) fan[1-8]_input Pump/fan speed (in RPM) / Flow speed (in dL/h) power[1-8]_input Pump/fan power (in micro Watts) in[0-7]_input Pump/fan voltage (in milli Volts) curr[1-8]_input Pump/fan current (in milli Amperes) pwm[1-8] Fan PWM (0 - 255) -================ ============================================== +================ ============================================================== Debugfs entries --------------- diff --git a/Documentation/hwmon/asus_wmi_ec_sensors.rst b/Documentation/hwmon/asus_wmi_ec_sensors.rst deleted file mode 100644 index 1b287f229e86..000000000000 --- a/Documentation/hwmon/asus_wmi_ec_sensors.rst +++ /dev/null @@ -1,38 +0,0 @@ -.. 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/corsair-psu.rst b/Documentation/hwmon/corsair-psu.rst index e8378e7a1d8c..3c1b164eb3c0 100644 --- a/Documentation/hwmon/corsair-psu.rst +++ b/Documentation/hwmon/corsair-psu.rst @@ -15,7 +15,7 @@ Supported devices: Corsair HX850i - Corsair HX1000i + Corsair HX1000i (revision 1 and 2) Corsair HX1200i @@ -86,8 +86,9 @@ Debugfs entries --------------- ======================= ======================================================== -uptime Current uptime of the psu +ocpmode Single or multi rail mode of the PCIe power connectors +product Product name of the psu +uptime Session uptime of the psu uptime_total Total uptime of the psu vendor Vendor name of the psu -product Product name of the psu ======================= ======================================================== diff --git a/Documentation/hwmon/emc2305.rst b/Documentation/hwmon/emc2305.rst new file mode 100644 index 000000000000..2403dbaf2728 --- /dev/null +++ b/Documentation/hwmon/emc2305.rst @@ -0,0 +1,37 @@ +.. SPDX-License-Identifier: GPL-2.0 + +Kernel driver emc2305 +===================== + +Supported chips: + Microchip EMC2305, EMC2303, EMC2302, EMC2301 + + Addresses scanned: I2C 0x27, 0x2c, 0x2d, 0x2e, 0x2f, 0x4c, 0x4d + Prefixes: 'emc2305' + + Datasheet: Publicly available at the Microchip website : + https://www.microchip.com/en-us/product/EMC2305 + +Description: +------------ +This driver implements support for Microchip EMC2301/2/3/5 RPM-based PWM Fan Controller. +The EMC2305 Fan Controller supports up to 5 independently controlled PWM fan drives. +Fan rotation speeds are reported in RPM. +The driver supports the RPM-based PWM control to keep a fan at the desired speed. +The driver provides the possibility to have one common PWM interface for all FANs +or up to the maximum available or configured independent PWMs. + +The driver provides the following sysfs interfaces in hwmon subsystem: + +================= == =================================================== +fan[1-5]_fault RO files for tachometers TACH1-TACH5 fault indication +fan[1-5]_input RO files for tachometers TACH1-TACH5 input (in RPM) +pwm[1-5] RW file for fan[1-5] target duty cycle (0..255) +================= == =================================================== + +sysfs interfaces in thermal subsystem: + +================= == ======================================================================== +cur_state RW file for the current cooling state of the cooling device (0..max_state) +max_state RO file for the maximum cooling state of the cooling device +================= == ======================================================================== diff --git a/Documentation/hwmon/index.rst b/Documentation/hwmon/index.rst index f7113b0f8b2a..c1d11cf13eef 100644 --- a/Documentation/hwmon/index.rst +++ b/Documentation/hwmon/index.rst @@ -44,7 +44,6 @@ Hardware Monitoring Kernel Drivers asc7621 aspeed-pwm-tacho asus_ec_sensors - asus_wmi_ec_sensors asus_wmi_sensors bcm54140 bel-pfe @@ -63,6 +62,7 @@ Hardware Monitoring Kernel Drivers ds620 emc1403 emc2103 + emc2305 emc6w201 f71805f f71882fg @@ -133,6 +133,7 @@ Hardware Monitoring Kernel Drivers max20751 max31722 max31730 + max31760 max31785 max31790 max34440 @@ -205,6 +206,7 @@ Hardware Monitoring Kernel Drivers tps23861 tps40422 tps53679 + tps546d24 twl4030-madc-hwmon ucd9000 ucd9200 diff --git a/Documentation/hwmon/max31760.rst b/Documentation/hwmon/max31760.rst new file mode 100644 index 000000000000..b1b55fb843c1 --- /dev/null +++ b/Documentation/hwmon/max31760.rst @@ -0,0 +1,77 @@ +.. SPDX-License-Identifier: GPL-2.0-or-later + +Kernel driver max31760 +====================== + +Supported chips: + * Analog Devices MAX31760 + + Prefix: 'max31760' + + Addresses scanned: none + + Datasheet: https://datasheets.maximintegrated.com/en/ds/MAX31760.pdf + + +Author: Ibrahim Tilki <Ibrahim.Tilki@analog.com> + +Description +----------- + +The MAX31760 integrates temperature sensing along with precision PWM fan +control. It accurately measures its local die temperature and the remote +temperature of a discrete diode-connected transistor, such as a 2N3906, +or a thermal diode commonly found on CPUs, graphics processor units (GPUs), +and other ASICs. Multiple temperature thresholds, such as local +high/overtemperature (OT) and remote high/overtemperature, can be set by an +I2C-compatible interface. Fan speed is controlled based on the temperature +reading as an index to a 48-byte lookup table (LUT) containing +user-programmed PWM values. The flexible LUT-based architecture enables +the user to program a smooth nonlinear fan speed vs. temperature transfer +function to minimize acoustic fan noise. Two tachometer inputs allow +measuring the speeds of two fans independently. When the local or remote +OT threshold is exceeded, the SHDN pin is asserted low and can be used to +shut down the system. A dedicated ALERT pin reports that either a local or +remote high-temperature threshold has been exceeded. + +Temperature measurement range: from -55°C to 125°C + +Temperature Resolution: 11 Bits, ±0.125°C + +Please refer how to instantiate this driver: Documentation/i2c/instantiating-devices.rst + +Lookup table for auto fan control +--------------------------------- + +========= ================================= +LUT Index Name +========= ================================= +1 PWM value for T < +18°C +2 PWM value for +18°C ≤ T < +20°C +3 PWM value for +20°C ≤ T < +22°C +... ... +47 PWM value for +108°C ≤ T < +110°C +48 PWM value for T ≥ +110°C +========= ================================= + +Sysfs entries +------------- + +=============================== ================================================================================= +fan[1-2]_input Fan speed (in RPM) +fan[1-2]_enable Enable fan readings and fan fault alarms +fan[1-2]_fault Fan fault status +temp[1-2]_label "Remote" and "Local" temperature channel labels +temp[1-2]_input Temperature sensor readings (in millidegrees Celsius) +temp1_fault Remote temperature sensor fault status +temp[1-2]_max Temperature max value. Asserts "ALERT" pin when exceeded +temp[1-2]_max_alarm Temperature max alarm status +temp[1-2]_crit Temperature critical value. Asserts "SHDN" pin when exceeded +temp[1-2]_crit_alarm Temperature critical alarm status +pwm1 PWM value for direct fan control +pwm1_enable 1: direct fan control, 2: temperature based auto fan control +pwm1_freq PWM frequency in hertz +pwm1_auto_channels_temp Temperature source for auto fan control. 1: temp1, 2: temp2, 3: max(temp1, temp2) +pwm1_auto_point[1-48]_pwm PWM value for LUT point +pwm1_auto_point_temp_hyst Temperature hysteresis for auto fan control. Can be either 2000mC or 4000mC +=============================== ================================================================================= diff --git a/Documentation/hwmon/max31790.rst b/Documentation/hwmon/max31790.rst index 7b097c3b9b90..33c5c7330efc 100644 --- a/Documentation/hwmon/max31790.rst +++ b/Documentation/hwmon/max31790.rst @@ -38,6 +38,7 @@ Sysfs entries fan[1-12]_input RO fan tachometer speed in RPM fan[1-12]_fault RO fan experienced fault fan[1-6]_target RW desired fan speed in RPM +fan[1-6]_enable RW enable or disable the tachometer input pwm[1-6]_enable RW regulator mode, 0=disabled (duty cycle=0%), 1=manual mode, 2=rpm mode pwm[1-6] RW read: current pwm duty cycle, write: target pwm duty cycle (0-255) diff --git a/Documentation/hwmon/pwm-fan.rst b/Documentation/hwmon/pwm-fan.rst index 82fe96742fee..f77998b204ef 100644 --- a/Documentation/hwmon/pwm-fan.rst +++ b/Documentation/hwmon/pwm-fan.rst @@ -18,3 +18,15 @@ the hwmon's sysfs interface. The fan rotation speed returned via the optional 'fan1_input' is extrapolated from the sampled interrupts from the tachometer signal within 1 second. + +The driver provides the following sensor accesses in sysfs: + +=============== ======= ======================================================= +fan1_input ro fan tachometer speed in RPM +pwm1_enable rw keep enable mode, defines behaviour when pwm1=0 + 0 -> disable pwm and regulator + 1 -> enable pwm; if pwm==0, disable pwm, keep regulator enabled + 2 -> enable pwm; if pwm==0, keep pwm and regulator enabled + 3 -> enable pwm; if pwm==0, disable pwm and regulator +pwm1 rw relative speed (0-255), 255=max. speed. +=============== ======= ======================================================= diff --git a/Documentation/hwmon/tps546d24.rst b/Documentation/hwmon/tps546d24.rst new file mode 100644 index 000000000000..97adb8a30fc0 --- /dev/null +++ b/Documentation/hwmon/tps546d24.rst @@ -0,0 +1,35 @@ +.. SPDX-License-Identifier: GPL-2.0-only + +Kernel driver tps546d24 +======================= + +Supported chips: + + * TI TPS546D24 + + Prefix: 'tps546d24' + + Addresses scanned: - + + Datasheet: https://www.ti.com/lit/gpn/tps546d24 + +Author: Duke Du <dukedu83@gmail.com> + + +Description +----------- + +The TPS546D24A is a highly integrated, non-isolated DC/DC converter capable +of high frequency operation and 40-A current output from a 7-mm x 5-mm +package. + +Two, three, and four TPS546D24A devices can be interconnected +to provide up to 160 A on a single output. The device has an option to +overdrive the internal 5-V LDO with an external 5-V supply via the VDD5 +pin to improve efficiency and reduce power dissipation of the converter. + + +Platform data support +--------------------- + +The driver supports standard PMBus driver platform data. diff --git a/Documentation/i2c/busses/i2c-piix4.rst b/Documentation/i2c/busses/i2c-piix4.rst index cc9000259223..07fe6f6f4b18 100644 --- a/Documentation/i2c/busses/i2c-piix4.rst +++ b/Documentation/i2c/busses/i2c-piix4.rst @@ -64,7 +64,7 @@ correct address for this module, you could get in big trouble (read: crashes, data corruption, etc.). Try this only as a last resort (try BIOS updates first, for example), and backup first! An even more dangerous option is 'force_addr=<IOPORT>'. This will not only enable the PIIX4 like -'force' foes, but it will also set a new base I/O port address. The SMBus +'force' does, but it will also set a new base I/O port address. The SMBus parts of the PIIX4 needs a range of 8 of these addresses to function correctly. If these addresses are already reserved by some other device, you will get into big trouble! DON'T USE THIS IF YOU ARE NOT VERY SURE @@ -86,15 +86,15 @@ If you own Force CPCI735 motherboard or other OSB4 based systems you may need to change the SMBus Interrupt Select register so the SMBus controller uses the SMI mode. -1) Use lspci command and locate the PCI device with the SMBus controller: +1) Use ``lspci`` command and locate the PCI device with the SMBus controller: 00:0f.0 ISA bridge: ServerWorks OSB4 South Bridge (rev 4f) The line may vary for different chipsets. Please consult the driver source - for all possible PCI ids (and lspci -n to match them). Lets assume the + for all possible PCI ids (and ``lspci -n`` to match them). Let's assume the device is located at 00:0f.0. 2) Now you just need to change the value in 0xD2 register. Get it first with - command: lspci -xxx -s 00:0f.0 + command: ``lspci -xxx -s 00:0f.0`` If the value is 0x3 then you need to change it to 0x1: - setpci -s 00:0f.0 d2.b=1 + ``setpci -s 00:0f.0 d2.b=1`` Please note that you don't need to do that in all cases, just when the SMBus is not working properly. @@ -109,6 +109,3 @@ which can easily get corrupted due to a state machine bug. These are mostly Thinkpad laptops, but desktop systems may also be affected. We have no list of all affected systems, so the only safe solution was to prevent access to the SMBus on all IBM systems (detected using DMI data.) - -For additional information, read: -http://www.lm-sensors.org/browser/lm-sensors/trunk/README diff --git a/Documentation/i2c/dev-interface.rst b/Documentation/i2c/dev-interface.rst index 73ad34849f99..c277a8e1202b 100644 --- a/Documentation/i2c/dev-interface.rst +++ b/Documentation/i2c/dev-interface.rst @@ -148,7 +148,7 @@ You can do plain I2C transactions by using read(2) and write(2) calls. You do not need to pass the address byte; instead, set it through ioctl I2C_SLAVE before you try to access the device. -You can do SMBus level transactions (see documentation file smbus-protocol +You can do SMBus level transactions (see documentation file smbus-protocol.rst for details) through the following functions:: __s32 i2c_smbus_write_quick(int file, __u8 value); diff --git a/Documentation/i2c/i2c-topology.rst b/Documentation/i2c/i2c-topology.rst index 7cb53819778e..48fce0f7491b 100644 --- a/Documentation/i2c/i2c-topology.rst +++ b/Documentation/i2c/i2c-topology.rst @@ -5,6 +5,8 @@ I2C muxes and complex topologies There are a couple of reasons for building more complex I2C topologies than a straight-forward I2C bus with one adapter and one or more devices. +Some example use cases are: + 1. A mux may be needed on the bus to prevent address collisions. 2. The bus may be accessible from some external bus master, and arbitration @@ -14,10 +16,10 @@ than a straight-forward I2C bus with one adapter and one or more devices. from the I2C bus, at least most of the time, and sits behind a gate that has to be operated before the device can be accessed. -Etc -=== +Several types of hardware components such as I2C muxes, I2C gates and I2C +arbitrators allow to handle such needs. -These constructs are represented as I2C adapter trees by Linux, where +These components are represented as I2C adapter trees by Linux, where each adapter has a parent adapter (except the root adapter) and zero or more child adapters. The root adapter is the actual adapter that issues I2C transfers, and all adapters with a parent are part of an "i2c-mux" @@ -35,46 +37,7 @@ Locking ======= There are two variants of locking available to I2C muxes, they can be -mux-locked or parent-locked muxes. As is evident from below, it can be -useful to know if a mux is mux-locked or if it is parent-locked. The -following list was correct at the time of writing: - -In drivers/i2c/muxes/: - -====================== ============================================= -i2c-arb-gpio-challenge Parent-locked -i2c-mux-gpio Normally parent-locked, mux-locked iff - all involved gpio pins are controlled by the - same I2C root adapter that they mux. -i2c-mux-gpmux Normally parent-locked, mux-locked iff - specified in device-tree. -i2c-mux-ltc4306 Mux-locked -i2c-mux-mlxcpld Parent-locked -i2c-mux-pca9541 Parent-locked -i2c-mux-pca954x Parent-locked -i2c-mux-pinctrl Normally parent-locked, mux-locked iff - all involved pinctrl devices are controlled - by the same I2C root adapter that they mux. -i2c-mux-reg Parent-locked -====================== ============================================= - -In drivers/iio/: - -====================== ============================================= -gyro/mpu3050 Mux-locked -imu/inv_mpu6050/ Mux-locked -====================== ============================================= - -In drivers/media/: - -======================= ============================================= -dvb-frontends/lgdt3306a Mux-locked -dvb-frontends/m88ds3103 Parent-locked -dvb-frontends/rtl2830 Parent-locked -dvb-frontends/rtl2832 Mux-locked -dvb-frontends/si2168 Mux-locked -usb/cx231xx/ Parent-locked -======================= ============================================= +mux-locked or parent-locked muxes. Mux-locked muxes @@ -89,40 +52,8 @@ full transaction, unrelated I2C transfers may interleave the different stages of the transaction. This has the benefit that the mux driver may be easier and cleaner to implement, but it has some caveats. -==== ===================================================================== -ML1. If you build a topology with a mux-locked mux being the parent - of a parent-locked mux, this might break the expectation from the - parent-locked mux that the root adapter is locked during the - transaction. - -ML2. It is not safe to build arbitrary topologies with two (or more) - mux-locked muxes that are not siblings, when there are address - collisions between the devices on the child adapters of these - non-sibling muxes. - - I.e. the select-transfer-deselect transaction targeting e.g. device - address 0x42 behind mux-one may be interleaved with a similar - operation targeting device address 0x42 behind mux-two. The - intension with such a topology would in this hypothetical example - be that mux-one and mux-two should not be selected simultaneously, - but mux-locked muxes do not guarantee that in all topologies. - -ML3. A mux-locked mux cannot be used by a driver for auto-closing - gates/muxes, i.e. something that closes automatically after a given - number (one, in most cases) of I2C transfers. Unrelated I2C transfers - may creep in and close prematurely. - -ML4. If any non-I2C operation in the mux driver changes the I2C mux state, - the driver has to lock the root adapter during that operation. - Otherwise garbage may appear on the bus as seen from devices - behind the mux, when an unrelated I2C transfer is in flight during - the non-I2C mux-changing operation. -==== ===================================================================== - - Mux-locked Example ------------------- - +~~~~~~~~~~~~~~~~~~ :: @@ -153,6 +84,43 @@ This means that accesses to D2 are lockout out for the full duration of the entire operation. But accesses to D3 are possibly interleaved at any point. +Mux-locked caveats +~~~~~~~~~~~~~~~~~~ + +When using a mux-locked mux, be aware of the following restrictions: + +[ML1] + If you build a topology with a mux-locked mux being the parent + of a parent-locked mux, this might break the expectation from the + parent-locked mux that the root adapter is locked during the + transaction. + +[ML2] + It is not safe to build arbitrary topologies with two (or more) + mux-locked muxes that are not siblings, when there are address + collisions between the devices on the child adapters of these + non-sibling muxes. + + I.e. the select-transfer-deselect transaction targeting e.g. device + address 0x42 behind mux-one may be interleaved with a similar + operation targeting device address 0x42 behind mux-two. The + intent with such a topology would in this hypothetical example + be that mux-one and mux-two should not be selected simultaneously, + but mux-locked muxes do not guarantee that in all topologies. + +[ML3] + A mux-locked mux cannot be used by a driver for auto-closing + gates/muxes, i.e. something that closes automatically after a given + number (one, in most cases) of I2C transfers. Unrelated I2C transfers + may creep in and close prematurely. + +[ML4] + If any non-I2C operation in the mux driver changes the I2C mux state, + the driver has to lock the root adapter during that operation. + Otherwise garbage may appear on the bus as seen from devices + behind the mux, when an unrelated I2C transfer is in flight during + the non-I2C mux-changing operation. + Parent-locked muxes ------------------- @@ -161,28 +129,10 @@ Parent-locked muxes lock the parent adapter during the full select- transfer-deselect transaction. The implication is that the mux driver has to ensure that any and all I2C transfers through that parent adapter during the transaction are unlocked I2C transfers (using e.g. -__i2c_transfer), or a deadlock will follow. There are a couple of -caveats. - -==== ==================================================================== -PL1. If you build a topology with a parent-locked mux being the child - of another mux, this might break a possible assumption from the - child mux that the root adapter is unused between its select op - and the actual transfer (e.g. if the child mux is auto-closing - and the parent mux issues I2C transfers as part of its select). - This is especially the case if the parent mux is mux-locked, but - it may also happen if the parent mux is parent-locked. - -PL2. If select/deselect calls out to other subsystems such as gpio, - pinctrl, regmap or iio, it is essential that any I2C transfers - caused by these subsystems are unlocked. This can be convoluted to - accomplish, maybe even impossible if an acceptably clean solution - is sought. -==== ==================================================================== - +__i2c_transfer), or a deadlock will follow. Parent-locked Example ---------------------- +~~~~~~~~~~~~~~~~~~~~~ :: @@ -212,10 +162,30 @@ When there is an access to D1, this happens: 9. M1 unlocks its parent adapter. 10. M1 unlocks muxes on its parent. - This means that accesses to both D2 and D3 are locked out for the full duration of the entire operation. +Parent-locked Caveats +~~~~~~~~~~~~~~~~~~~~~ + +When using a parent-locked mux, be aware of the following restrictions: + +[PL1] + If you build a topology with a parent-locked mux being the child + of another mux, this might break a possible assumption from the + child mux that the root adapter is unused between its select op + and the actual transfer (e.g. if the child mux is auto-closing + and the parent mux issues I2C transfers as part of its select). + This is especially the case if the parent mux is mux-locked, but + it may also happen if the parent mux is parent-locked. + +[PL2] + If select/deselect calls out to other subsystems such as gpio, + pinctrl, regmap or iio, it is essential that any I2C transfers + caused by these subsystems are unlocked. This can be convoluted to + accomplish, maybe even impossible if an acceptably clean solution + is sought. + Complex Examples ================ @@ -261,8 +231,10 @@ This is a good topology:: When device D1 is accessed, accesses to D2 are locked out for the full duration of the operation (muxes on the top child adapter of M1 are locked). But accesses to D3 and D4 are possibly interleaved at -any point. Accesses to D3 locks out D1 and D2, but accesses to D4 -are still possibly interleaved. +any point. + +Accesses to D3 locks out D1 and D2, but accesses to D4 are still possibly +interleaved. Mux-locked mux as parent of parent-locked mux @@ -394,3 +366,47 @@ This is a good topology:: When D1 or D2 are accessed, accesses to D3 and D4 are locked out while accesses to D5 may interleave. When D3 or D4 are accessed, accesses to all other devices are locked out. + + +Mux type of existing device drivers +=================================== + +Whether a device is mux-locked or parent-locked depends on its +implementation. The following list was correct at the time of writing: + +In drivers/i2c/muxes/: + +====================== ============================================= +i2c-arb-gpio-challenge Parent-locked +i2c-mux-gpio Normally parent-locked, mux-locked iff + all involved gpio pins are controlled by the + same I2C root adapter that they mux. +i2c-mux-gpmux Normally parent-locked, mux-locked iff + specified in device-tree. +i2c-mux-ltc4306 Mux-locked +i2c-mux-mlxcpld Parent-locked +i2c-mux-pca9541 Parent-locked +i2c-mux-pca954x Parent-locked +i2c-mux-pinctrl Normally parent-locked, mux-locked iff + all involved pinctrl devices are controlled + by the same I2C root adapter that they mux. +i2c-mux-reg Parent-locked +====================== ============================================= + +In drivers/iio/: + +====================== ============================================= +gyro/mpu3050 Mux-locked +imu/inv_mpu6050/ Mux-locked +====================== ============================================= + +In drivers/media/: + +======================= ============================================= +dvb-frontends/lgdt3306a Mux-locked +dvb-frontends/m88ds3103 Parent-locked +dvb-frontends/rtl2830 Parent-locked +dvb-frontends/rtl2832 Mux-locked +dvb-frontends/si2168 Mux-locked +usb/cx231xx/ Parent-locked +======================= ============================================= diff --git a/Documentation/i2c/slave-interface.rst b/Documentation/i2c/slave-interface.rst index 82ea3e1d6fe4..3f0d320bc80a 100644 --- a/Documentation/i2c/slave-interface.rst +++ b/Documentation/i2c/slave-interface.rst @@ -32,9 +32,9 @@ User manual =========== I2C slave backends behave like standard I2C clients. So, you can instantiate -them as described in the document 'instantiating-devices'. The only difference -is that i2c slave backends have their own address space. So, you have to add -0x1000 to the address you would originally request. An example for +them as described in the document instantiating-devices.rst. The only +difference is that i2c slave backends have their own address space. So, you +have to add 0x1000 to the address you would originally request. An example for instantiating the slave-eeprom driver from userspace at the 7 bit address 0x64 on bus 1:: @@ -72,12 +72,15 @@ Event types: 'val': unused - 'ret': always 0 + 'ret': 0 if the backend is ready, otherwise some errno Another I2C master wants to write data to us. This event should be sent once our own address and the write bit was detected. The data did not arrive yet, so -there is nothing to process or return. Wakeup or initialization probably needs -to be done, though. +there is nothing to process or return. After returning, the bus driver must +always ack the address phase. If 'ret' is zero, backend initialization or +wakeup is done and further data may be received. If 'ret' is an errno, the bus +driver should nack all incoming bytes until the next stop condition to enforce +a retry of the transmission. * I2C_SLAVE_READ_REQUESTED (mandatory) diff --git a/Documentation/i2c/writing-clients.rst b/Documentation/i2c/writing-clients.rst index e3b126cf4a3b..b7d3ae7458f8 100644 --- a/Documentation/i2c/writing-clients.rst +++ b/Documentation/i2c/writing-clients.rst @@ -156,7 +156,7 @@ those devices, and a remove() method to unbind. :: static int foo_probe(struct i2c_client *client); - static int foo_remove(struct i2c_client *client); + static void foo_remove(struct i2c_client *client); Remember that the i2c_driver does not create those client handles. The handle may be used during foo_probe(). If foo_probe() reports success @@ -364,7 +364,7 @@ stop condition is issued between transaction. The i2c_msg structure contains for each message the client address, the number of bytes of the message and the message data itself. -You can read the file ``i2c-protocol`` for more information about the +You can read the file i2c-protocol.rst for more information about the actual I2C protocol. @@ -414,7 +414,7 @@ transactions return 0 on success; the 'read' transactions return the read value, except for block transactions, which return the number of values read. The block buffers need not be longer than 32 bytes. -You can read the file ``smbus-protocol`` for more information about the +You can read the file smbus-protocol.rst for more information about the actual SMBus protocol. diff --git a/Documentation/index.rst b/Documentation/index.rst index 4737c18c97ff..bf6aa681c960 100644 --- a/Documentation/index.rst +++ b/Documentation/index.rst @@ -1,11 +1,5 @@ .. SPDX-License-Identifier: GPL-2.0 - -.. The Linux Kernel documentation master file, created by - sphinx-quickstart on Fri Feb 12 13:51:46 2016. - You can adapt this file completely to your liking, but it should at least - contain the root `toctree` directive. - .. _linux_doc: The Linux Kernel documentation @@ -18,133 +12,85 @@ documents into a coherent whole. Please note that improvements to the documentation are welcome; join the linux-doc list at vger.kernel.org if you want to help out. -Licensing documentation ------------------------ +Working with the development community +-------------------------------------- -The following describes the license of the Linux kernel source code -(GPLv2), how to properly mark the license of individual files in the source -tree, as well as links to the full license text. - -* :ref:`kernel_licensing` - -User-oriented documentation ---------------------------- - -The following manuals are written for *users* of the kernel — those who are -trying to get it to work optimally on a given system. +The essential guides for interacting with the kernel's development +community and getting your work upstream. .. toctree:: - :maxdepth: 2 - - admin-guide/index - kbuild/index - -Firmware-related documentation ------------------------------- -The following holds information on the kernel's expectations regarding the -platform firmwares. + :maxdepth: 1 -.. toctree:: - :maxdepth: 2 + process/development-process + process/submitting-patches + Code of conduct <process/code-of-conduct> + maintainer/index + All development-process docs <process/index> - firmware-guide/index - devicetree/index -Application-developer documentation ------------------------------------ +Internal API manuals +-------------------- -The user-space API manual gathers together documents describing aspects of -the kernel interface as seen by application developers. +Manuals for use by developers working to interface with the rest of the +kernel. .. toctree:: - :maxdepth: 2 - - userspace-api/index + :maxdepth: 1 + core-api/index + driver-api/index + subsystem-apis + Locking in the kernel <locking/index> -Introduction to kernel development ----------------------------------- +Development tools and processes +------------------------------- -These manuals contain overall information about how to develop the kernel. -The kernel community is quite large, with thousands of developers -contributing over the course of a year. As with any large community, -knowing how things are done will make the process of getting your changes -merged much easier. +Various other manuals with useful information for all kernel developers. .. toctree:: - :maxdepth: 2 + :maxdepth: 1 - process/index - dev-tools/index + process/license-rules doc-guide/index + dev-tools/index + dev-tools/testing-overview kernel-hacking/index trace/index - maintainer/index fault-injection/index livepatch/index + rust/index -Kernel API documentation ------------------------- +User-oriented documentation +--------------------------- -These books get into the details of how specific kernel subsystems work -from the point of view of a kernel developer. Much of the information here -is taken directly from the kernel source, with supplemental material added -as needed (or at least as we managed to add it — probably *not* all that is -needed). +The following manuals are written for *users* of the kernel — those who are +trying to get it to work optimally on a given system and application +developers seeking information on the kernel's user-space APIs. .. toctree:: - :maxdepth: 2 + :maxdepth: 1 - driver-api/index - core-api/index - locking/index - accounting/index - block/index - cdrom/index - cpu-freq/index - fb/index - fpga/index - hid/index - i2c/index - iio/index - isdn/index - infiniband/index - leds/index - netlabel/index - networking/index - pcmcia/index - power/index - target/index - timers/index - spi/index - w1/index - watchdog/index - virt/index - input/index - hwmon/index - gpu/index - security/index - sound/index - crypto/index - filesystems/index - mm/index - bpf/index - usb/index - PCI/index - scsi/index - misc-devices/index - scheduler/index - mhi/index - peci/index - -Architecture-agnostic documentation ------------------------------------ + admin-guide/index + The kernel build system <kbuild/index> + admin-guide/reporting-issues.rst + User-space tools <tools/index> + userspace-api/index + +See also: the `Linux man pages <https://www.kernel.org/doc/man-pages/>`_, +which are kept separately from the kernel's own documentation. + +Firmware-related documentation +------------------------------ +The following holds information on the kernel's expectations regarding the +platform firmwares. .. toctree:: - :maxdepth: 2 + :maxdepth: 1 + + firmware-guide/index + devicetree/index - asm-annotations Architecture-specific documentation ----------------------------------- @@ -163,9 +109,8 @@ of the documentation body, or may require some adjustments and/or conversion to ReStructured Text format, or are simply too old. .. toctree:: - :maxdepth: 2 + :maxdepth: 1 - tools/index staging/index diff --git a/Documentation/input/joydev/joystick.rst b/Documentation/input/joydev/joystick.rst index f615906a0821..6d721396717a 100644 --- a/Documentation/input/joydev/joystick.rst +++ b/Documentation/input/joydev/joystick.rst @@ -517,6 +517,7 @@ All I-Force devices are supported by the iforce module. This includes: * AVB Mag Turbo Force * AVB Top Shot Pegasus * AVB Top Shot Force Feedback Racing Wheel +* Boeder Force Feedback Wheel * Logitech WingMan Force * Logitech WingMan Force Wheel * Guillemot Race Leader Force Feedback diff --git a/Documentation/kbuild/gcc-plugins.rst b/Documentation/kbuild/gcc-plugins.rst index 0ba76719f1b9..c578c6ba3eb6 100644 --- a/Documentation/kbuild/gcc-plugins.rst +++ b/Documentation/kbuild/gcc-plugins.rst @@ -90,7 +90,11 @@ e.g., on Ubuntu for gcc-10:: Or on Fedora:: - dnf install gcc-plugin-devel + dnf install gcc-plugin-devel libmpc-devel + +Or on Fedora when using cross-compilers that include plugins:: + + dnf install libmpc-devel Enable the GCC plugin infrastructure and some plugin(s) you want to use in the kernel config:: @@ -99,6 +103,19 @@ in the kernel config:: CONFIG_GCC_PLUGIN_LATENT_ENTROPY=y ... +Run gcc (native or cross-compiler) to ensure plugin headers are detected:: + + gcc -print-file-name=plugin + CROSS_COMPILE=arm-linux-gnu- ${CROSS_COMPILE}gcc -print-file-name=plugin + +The word "plugin" means they are not detected:: + + plugin + +A full path means they are detected:: + + /usr/lib/gcc/x86_64-redhat-linux/12/plugin + To compile the minimum tool set including the plugin(s):: make scripts diff --git a/Documentation/kbuild/kbuild.rst b/Documentation/kbuild/kbuild.rst index ef19b9c13523..08f575e6236c 100644 --- a/Documentation/kbuild/kbuild.rst +++ b/Documentation/kbuild/kbuild.rst @@ -48,6 +48,10 @@ KCFLAGS ------- Additional options to the C compiler (for built-in and modules). +KRUSTFLAGS +---------- +Additional options to the Rust compiler (for built-in and modules). + CFLAGS_KERNEL ------------- Additional options for $(CC) when used to compile @@ -57,6 +61,15 @@ CFLAGS_MODULE ------------- Additional module specific options to use for $(CC). +RUSTFLAGS_KERNEL +---------------- +Additional options for $(RUSTC) when used to compile +code that is compiled as built-in. + +RUSTFLAGS_MODULE +---------------- +Additional module specific options to use for $(RUSTC). + LDFLAGS_MODULE -------------- Additional options used for $(LD) when linking modules. @@ -69,6 +82,10 @@ HOSTCXXFLAGS ------------ Additional flags to be passed to $(HOSTCXX) when building host programs. +HOSTRUSTFLAGS +------------- +Additional flags to be passed to $(HOSTRUSTC) when building host programs. + HOSTLDFLAGS ----------- Additional flags to be passed when linking host programs. diff --git a/Documentation/kbuild/makefiles.rst b/Documentation/kbuild/makefiles.rst index 11a296e52d68..5ea1e72d89c8 100644 --- a/Documentation/kbuild/makefiles.rst +++ b/Documentation/kbuild/makefiles.rst @@ -29,8 +29,9 @@ This document describes the Linux kernel Makefiles. --- 4.1 Simple Host Program --- 4.2 Composite Host Programs --- 4.3 Using C++ for host programs - --- 4.4 Controlling compiler options for host programs - --- 4.5 When host programs are actually built + --- 4.4 Using Rust for host programs + --- 4.5 Controlling compiler options for host programs + --- 4.6 When host programs are actually built === 5 Userspace Program support --- 5.1 Simple Userspace Program @@ -835,7 +836,24 @@ Both possibilities are described in the following. qconf-cxxobjs := qconf.o qconf-objs := check.o -4.4 Controlling compiler options for host programs +4.4 Using Rust for host programs +-------------------------------- + + Kbuild offers support for host programs written in Rust. However, + since a Rust toolchain is not mandatory for kernel compilation, + it may only be used in scenarios where Rust is required to be + available (e.g. when ``CONFIG_RUST`` is enabled). + + Example:: + + hostprogs := target + target-rust := y + + Kbuild will compile ``target`` using ``target.rs`` as the crate root, + located in the same directory as the ``Makefile``. The crate may + consist of several source files (see ``samples/rust/hostprogs``). + +4.5 Controlling compiler options for host programs -------------------------------------------------- When compiling host programs, it is possible to set specific flags. @@ -867,7 +885,7 @@ Both possibilities are described in the following. When linking qconf, it will be passed the extra option "-L$(QTDIR)/lib". -4.5 When host programs are actually built +4.6 When host programs are actually built ----------------------------------------- Kbuild will only build host-programs when they are referenced @@ -1181,6 +1199,17 @@ When kbuild executes, the following steps are followed (roughly): The first example utilises the trick that a config option expands to 'y' when selected. + KBUILD_RUSTFLAGS + $(RUSTC) compiler flags + + Default value - see top level Makefile + Append or modify as required per architecture. + + Often, the KBUILD_RUSTFLAGS variable depends on the configuration. + + Note that target specification file generation (for ``--target``) + is handled in ``scripts/generate_rust_target.rs``. + KBUILD_AFLAGS_KERNEL Assembler options specific for built-in @@ -1208,6 +1237,19 @@ When kbuild executes, the following steps are followed (roughly): are used for $(CC). From commandline CFLAGS_MODULE shall be used (see kbuild.rst). + KBUILD_RUSTFLAGS_KERNEL + $(RUSTC) options specific for built-in + + $(KBUILD_RUSTFLAGS_KERNEL) contains extra Rust compiler flags used to + compile resident kernel code. + + KBUILD_RUSTFLAGS_MODULE + Options for $(RUSTC) when building modules + + $(KBUILD_RUSTFLAGS_MODULE) is used to add arch-specific options that + are used for $(RUSTC). + From commandline RUSTFLAGS_MODULE shall be used (see kbuild.rst). + KBUILD_LDFLAGS_MODULE Options for $(LD) when linking modules diff --git a/Documentation/locking/seqlock.rst b/Documentation/locking/seqlock.rst index 64405e5da63e..bfda1a5fecad 100644 --- a/Documentation/locking/seqlock.rst +++ b/Documentation/locking/seqlock.rst @@ -39,7 +39,7 @@ as the writer can invalidate a pointer that the reader is following. Sequence counters (``seqcount_t``) ================================== -This is the the raw counting mechanism, which does not protect against +This is the raw counting mechanism, which does not protect against multiple writers. Write side critical sections must thus be serialized by an external lock. diff --git a/Documentation/memory-barriers.txt b/Documentation/memory-barriers.txt index 832b5d36e279..06f80e3785c5 100644 --- a/Documentation/memory-barriers.txt +++ b/Documentation/memory-barriers.txt @@ -52,7 +52,7 @@ CONTENTS - Varieties of memory barrier. - What may not be assumed about memory barriers? - - Data dependency barriers (historical). + - Address-dependency barriers (historical). - Control dependencies. - SMP barrier pairing. - Examples of memory barrier sequences. @@ -187,9 +187,9 @@ As a further example, consider this sequence of events: B = 4; Q = P; P = &B; D = *Q; -There is an obvious data dependency here, as the value loaded into D depends on -the address retrieved from P by CPU 2. At the end of the sequence, any of the -following results are possible: +There is an obvious address dependency here, as the value loaded into D depends +on the address retrieved from P by CPU 2. At the end of the sequence, any of +the following results are possible: (Q == &A) and (D == 1) (Q == &B) and (D == 2) @@ -391,58 +391,62 @@ Memory barriers come in four basic varieties: memory system as time progresses. All stores _before_ a write barrier will occur _before_ all the stores after the write barrier. - [!] Note that write barriers should normally be paired with read or data - dependency barriers; see the "SMP barrier pairing" subsection. + [!] Note that write barriers should normally be paired with read or + address-dependency barriers; see the "SMP barrier pairing" subsection. - (2) Data dependency barriers. + (2) Address-dependency barriers (historical). - A data dependency barrier is a weaker form of read barrier. In the case - where two loads are performed such that the second depends on the result - of the first (eg: the first load retrieves the address to which the second - load will be directed), a data dependency barrier would be required to - make sure that the target of the second load is updated after the address - obtained by the first load is accessed. + An address-dependency barrier is a weaker form of read barrier. In the + case where two loads are performed such that the second depends on the + result of the first (eg: the first load retrieves the address to which + the second load will be directed), an address-dependency barrier would + be required to make sure that the target of the second load is updated + after the address obtained by the first load is accessed. - A data dependency barrier is a partial ordering on interdependent loads - only; it is not required to have any effect on stores, independent loads - or overlapping loads. + An address-dependency barrier is a partial ordering on interdependent + loads only; it is not required to have any effect on stores, independent + loads or overlapping loads. As mentioned in (1), the other CPUs in the system can be viewed as committing sequences of stores to the memory system that the CPU being - considered can then perceive. A data dependency barrier issued by the CPU - under consideration guarantees that for any load preceding it, if that - load touches one of a sequence of stores from another CPU, then by the - time the barrier completes, the effects of all the stores prior to that - touched by the load will be perceptible to any loads issued after the data - dependency barrier. + considered can then perceive. An address-dependency barrier issued by + the CPU under consideration guarantees that for any load preceding it, + if that load touches one of a sequence of stores from another CPU, then + by the time the barrier completes, the effects of all the stores prior to + that touched by the load will be perceptible to any loads issued after + the address-dependency barrier. See the "Examples of memory barrier sequences" subsection for diagrams showing the ordering constraints. - [!] Note that the first load really has to have a _data_ dependency and + [!] Note that the first load really has to have an _address_ dependency and not a control dependency. If the address for the second load is dependent on the first load, but the dependency is through a conditional rather than actually loading the address itself, then it's a _control_ dependency and a full read barrier or better is required. See the "Control dependencies" subsection for more information. - [!] Note that data dependency barriers should normally be paired with + [!] Note that address-dependency barriers should normally be paired with write barriers; see the "SMP barrier pairing" subsection. + [!] Kernel release v5.9 removed kernel APIs for explicit address- + dependency barriers. Nowadays, APIs for marking loads from shared + variables such as READ_ONCE() and rcu_dereference() provide implicit + address-dependency barriers. (3) Read (or load) memory barriers. - A read barrier is a data dependency barrier plus a guarantee that all the - LOAD operations specified before the barrier will appear to happen before - all the LOAD operations specified after the barrier with respect to the - other components of the system. + A read barrier is an address-dependency barrier plus a guarantee that all + the LOAD operations specified before the barrier will appear to happen + before all the LOAD operations specified after the barrier with respect to + the other components of the system. A read barrier is a partial ordering on loads only; it is not required to have any effect on stores. - Read memory barriers imply data dependency barriers, and so can substitute - for them. + Read memory barriers imply address-dependency barriers, and so can + substitute for them. [!] Note that read barriers should normally be paired with write barriers; see the "SMP barrier pairing" subsection. @@ -550,17 +554,21 @@ There are certain things that the Linux kernel memory barriers do not guarantee: Documentation/core-api/dma-api.rst -DATA DEPENDENCY BARRIERS (HISTORICAL) -------------------------------------- +ADDRESS-DEPENDENCY BARRIERS (HISTORICAL) +---------------------------------------- As of v4.15 of the Linux kernel, an smp_mb() was added to READ_ONCE() for DEC Alpha, which means that about the only people who need to pay attention to this section are those working on DEC Alpha architecture-specific code and those working on READ_ONCE() itself. For those who need it, and for those who are interested in the history, here is the story of -data-dependency barriers. +address-dependency barriers. + +[!] While address dependencies are observed in both load-to-load and +load-to-store relations, address-dependency barriers are not necessary +for load-to-store situations. -The usage requirements of data dependency barriers are a little subtle, and +The requirement of address-dependency barriers is a little subtle, and it's not always obvious that they're needed. To illustrate, consider the following sequence of events: @@ -570,11 +578,14 @@ following sequence of events: B = 4; <write barrier> WRITE_ONCE(P, &B); - Q = READ_ONCE(P); + Q = READ_ONCE_OLD(P); D = *Q; -There's a clear data dependency here, and it would seem that by the end of the -sequence, Q must be either &A or &B, and that: +[!] READ_ONCE_OLD() corresponds to READ_ONCE() of pre-4.15 kernel, which +doesn't imply an address-dependency barrier. + +There's a clear address dependency here, and it would seem that by the end of +the sequence, Q must be either &A or &B, and that: (Q == &A) implies (D == 1) (Q == &B) implies (D == 4) @@ -588,8 +599,8 @@ While this may seem like a failure of coherency or causality maintenance, it isn't, and this behaviour can be observed on certain real CPUs (such as the DEC Alpha). -To deal with this, a data dependency barrier or better must be inserted -between the address load and the data load: +To deal with this, READ_ONCE() provides an implicit address-dependency barrier +since kernel release v4.15: CPU 1 CPU 2 =============== =============== @@ -598,7 +609,7 @@ between the address load and the data load: <write barrier> WRITE_ONCE(P, &B); Q = READ_ONCE(P); - <data dependency barrier> + <implicit address-dependency barrier> D = *Q; This enforces the occurrence of one of the two implications, and prevents the @@ -615,13 +626,13 @@ odd-numbered bank is idle, one can see the new value of the pointer P (&B), but the old value of the variable B (2). -A data-dependency barrier is not required to order dependent writes -because the CPUs that the Linux kernel supports don't do writes -until they are certain (1) that the write will actually happen, (2) -of the location of the write, and (3) of the value to be written. +An address-dependency barrier is not required to order dependent writes +because the CPUs that the Linux kernel supports don't do writes until they +are certain (1) that the write will actually happen, (2) of the location of +the write, and (3) of the value to be written. But please carefully read the "CONTROL DEPENDENCIES" section and the -Documentation/RCU/rcu_dereference.rst file: The compiler can and does -break dependencies in a great many highly creative ways. +Documentation/RCU/rcu_dereference.rst file: The compiler can and does break +dependencies in a great many highly creative ways. CPU 1 CPU 2 =============== =============== @@ -629,12 +640,12 @@ break dependencies in a great many highly creative ways. B = 4; <write barrier> WRITE_ONCE(P, &B); - Q = READ_ONCE(P); + Q = READ_ONCE_OLD(P); WRITE_ONCE(*Q, 5); -Therefore, no data-dependency barrier is required to order the read into +Therefore, no address-dependency barrier is required to order the read into Q with the store into *Q. In other words, this outcome is prohibited, -even without a data-dependency barrier: +even without an implicit address-dependency barrier of modern READ_ONCE(): (Q == &B) && (B == 4) @@ -645,12 +656,12 @@ can be used to record rare error conditions and the like, and the CPUs' naturally occurring ordering prevents such records from being lost. -Note well that the ordering provided by a data dependency is local to +Note well that the ordering provided by an address dependency is local to the CPU containing it. See the section on "Multicopy atomicity" for more information. -The data dependency barrier is very important to the RCU system, +The address-dependency barrier is very important to the RCU system, for example. See rcu_assign_pointer() and rcu_dereference() in include/linux/rcupdate.h. This permits the current target of an RCU'd pointer to be replaced with a new modified target, without the replacement @@ -667,20 +678,21 @@ not understand them. The purpose of this section is to help you prevent the compiler's ignorance from breaking your code. A load-load control dependency requires a full read memory barrier, not -simply a data dependency barrier to make it work correctly. Consider the -following bit of code: +simply an (implicit) address-dependency barrier to make it work correctly. +Consider the following bit of code: q = READ_ONCE(a); + <implicit address-dependency barrier> if (q) { - <data dependency barrier> /* BUG: No data dependency!!! */ + /* BUG: No address dependency!!! */ p = READ_ONCE(b); } -This will not have the desired effect because there is no actual data +This will not have the desired effect because there is no actual address dependency, but rather a control dependency that the CPU may short-circuit by attempting to predict the outcome in advance, so that other CPUs see -the load from b as having happened before the load from a. In such a -case what's actually required is: +the load from b as having happened before the load from a. In such a case +what's actually required is: q = READ_ONCE(a); if (q) { @@ -927,9 +939,9 @@ General barriers pair with each other, though they also pair with most other types of barriers, albeit without multicopy atomicity. An acquire barrier pairs with a release barrier, but both may also pair with other barriers, including of course general barriers. A write barrier pairs -with a data dependency barrier, a control dependency, an acquire barrier, +with an address-dependency barrier, a control dependency, an acquire barrier, a release barrier, a read barrier, or a general barrier. Similarly a -read barrier, control dependency, or a data dependency barrier pairs +read barrier, control dependency, or an address-dependency barrier pairs with a write barrier, an acquire barrier, a release barrier, or a general barrier: @@ -948,7 +960,7 @@ Or: a = 1; <write barrier> WRITE_ONCE(b, &a); x = READ_ONCE(b); - <data dependency barrier> + <implicit address-dependency barrier> y = *x; Or even: @@ -968,8 +980,8 @@ Basically, the read barrier always has to be there, even though it can be of the "weaker" type. [!] Note that the stores before the write barrier would normally be expected to -match the loads after the read barrier or the data dependency barrier, and vice -versa: +match the loads after the read barrier or the address-dependency barrier, and +vice versa: CPU 1 CPU 2 =================== =================== @@ -1021,8 +1033,8 @@ STORE B, STORE C } all occurring before the unordered set of { STORE D, STORE E V -Secondly, data dependency barriers act as partial orderings on data-dependent -loads. Consider the following sequence of events: +Secondly, address-dependency barriers act as partial orderings on address- +dependent loads. Consider the following sequence of events: CPU 1 CPU 2 ======================= ======================= @@ -1067,8 +1079,8 @@ effectively random order, despite the write barrier issued by CPU 1: In the above example, CPU 2 perceives that B is 7, despite the load of *C (which would be B) coming after the LOAD of C. -If, however, a data dependency barrier were to be placed between the load of C -and the load of *C (ie: B) on CPU 2: +If, however, an address-dependency barrier were to be placed between the load +of C and the load of *C (ie: B) on CPU 2: CPU 1 CPU 2 ======================= ======================= @@ -1078,7 +1090,7 @@ and the load of *C (ie: B) on CPU 2: <write barrier> STORE C = &B LOAD X STORE D = 4 LOAD C (gets &B) - <data dependency barrier> + <address-dependency barrier> LOAD *C (reads B) then the following will occur: @@ -1101,7 +1113,7 @@ then the following will occur: | +-------+ | | | | X->9 |------>| | | +-------+ | | - Makes sure all effects ---> \ ddddddddddddddddd | | + Makes sure all effects ---> \ aaaaaaaaaaaaaaaaa | | prior to the store of C \ +-------+ | | are perceptible to ----->| B->2 |------>| | subsequent loads +-------+ | | @@ -1292,7 +1304,7 @@ Which might appear as this: LOAD with immediate effect : : +-------+ -Placing a read barrier or a data dependency barrier just before the second +Placing a read barrier or an address-dependency barrier just before the second load: CPU 1 CPU 2 @@ -1816,20 +1828,20 @@ which may then reorder things however it wishes. CPU MEMORY BARRIERS ------------------- -The Linux kernel has eight basic CPU memory barriers: +The Linux kernel has seven basic CPU memory barriers: - TYPE MANDATORY SMP CONDITIONAL - =============== ======================= =========================== - GENERAL mb() smp_mb() - WRITE wmb() smp_wmb() - READ rmb() smp_rmb() - DATA DEPENDENCY READ_ONCE() + TYPE MANDATORY SMP CONDITIONAL + ======================= =============== =============== + GENERAL mb() smp_mb() + WRITE wmb() smp_wmb() + READ rmb() smp_rmb() + ADDRESS DEPENDENCY READ_ONCE() -All memory barriers except the data dependency barriers imply a compiler -barrier. Data dependencies do not impose any additional compiler ordering. +All memory barriers except the address-dependency barriers imply a compiler +barrier. Address dependencies do not impose any additional compiler ordering. -Aside: In the case of data dependencies, the compiler would be expected +Aside: In the case of address dependencies, the compiler would be expected to issue the loads in the correct order (eg. `a[b]` would have to load the value of b before loading a[b]), however there is no guarantee in the C specification that the compiler may not speculate the value of b @@ -2749,7 +2761,8 @@ is discarded from the CPU's cache and reloaded. To deal with this, the appropriate part of the kernel must invalidate the overlapping bits of the cache on each CPU. -See Documentation/core-api/cachetlb.rst for more information on cache management. +See Documentation/core-api/cachetlb.rst for more information on cache +management. CACHE COHERENCY VS MMIO @@ -2889,8 +2902,8 @@ AND THEN THERE'S THE ALPHA The DEC Alpha CPU is one of the most relaxed CPUs there is. Not only that, some versions of the Alpha CPU have a split data cache, permitting them to have two semantically-related cache lines updated at separate times. This is where -the data dependency barrier really becomes necessary as this synchronises both -caches with the memory coherence system, thus making it seem like pointer +the address-dependency barrier really becomes necessary as this synchronises +both caches with the memory coherence system, thus making it seem like pointer changes vs new data occur in the right order. The Alpha defines the Linux kernel's memory model, although as of v4.15 diff --git a/Documentation/mm/unevictable-lru.rst b/Documentation/mm/unevictable-lru.rst index b280367d6a44..4a0e158aa9ce 100644 --- a/Documentation/mm/unevictable-lru.rst +++ b/Documentation/mm/unevictable-lru.rst @@ -197,7 +197,7 @@ unevictable list for the memory cgroup and node being scanned. There may be situations where a page is mapped into a VM_LOCKED VMA, but the page is not marked as PG_mlocked. Such pages will make it all the way to shrink_active_list() or shrink_page_list() where they will be detected when -vmscan walks the reverse map in page_referenced() or try_to_unmap(). The page +vmscan walks the reverse map in folio_referenced() or try_to_unmap(). The page is culled to the unevictable list when it is released by the shrinker. To "cull" an unevictable page, vmscan simply puts the page back on the LRU list @@ -267,7 +267,7 @@ the LRU. Such pages can be "noticed" by memory management in several places: (4) in the fault path and when a VM_LOCKED stack segment is expanded; or (5) as mentioned above, in vmscan:shrink_page_list() when attempting to - reclaim a page in a VM_LOCKED VMA by page_referenced() or try_to_unmap(). + reclaim a page in a VM_LOCKED VMA by folio_referenced() or try_to_unmap(). mlocked pages become unlocked and rescued from the unevictable list when: @@ -547,7 +547,7 @@ vmscan's shrink_inactive_list() and shrink_page_list() also divert obviously unevictable pages found on the inactive lists to the appropriate memory cgroup and node unevictable list. -rmap's page_referenced_one(), called via vmscan's shrink_active_list() or +rmap's folio_referenced_one(), called via vmscan's shrink_active_list() or shrink_page_list(), and rmap's try_to_unmap_one() called via shrink_page_list(), check for (3) pages still mapped into VM_LOCKED VMAs, and call mlock_vma_page() to correct them. Such pages are culled to the unevictable list when released diff --git a/Documentation/networking/bonding.rst b/Documentation/networking/bonding.rst index 7823a069a903..96cd7a26f3d9 100644 --- a/Documentation/networking/bonding.rst +++ b/Documentation/networking/bonding.rst @@ -846,7 +846,7 @@ primary_reselect tlb_dynamic_lb Specifies if dynamic shuffling of flows is enabled in tlb - mode. The value has no effect on any other modes. + or alb mode. The value has no effect on any other modes. The default behavior of tlb mode is to shuffle active flows across slaves based on the load in that interval. This gives nice lb diff --git a/Documentation/networking/decnet.rst b/Documentation/networking/decnet.rst deleted file mode 100644 index b8bc11ff8370..000000000000 --- a/Documentation/networking/decnet.rst +++ /dev/null @@ -1,243 +0,0 @@ -.. SPDX-License-Identifier: GPL-2.0 - -========================================= -Linux DECnet Networking Layer Information -========================================= - -1. Other documentation.... -========================== - - - Project Home Pages - - http://www.chygwyn.com/ - Kernel info - - http://linux-decnet.sourceforge.net/ - Userland tools - - http://www.sourceforge.net/projects/linux-decnet/ - Status page - -2. Configuring the kernel -========================= - -Be sure to turn on the following options: - - - CONFIG_DECNET (obviously) - - CONFIG_PROC_FS (to see what's going on) - - CONFIG_SYSCTL (for easy configuration) - -if you want to try out router support (not properly debugged yet) -you'll need the following options as well... - - - CONFIG_DECNET_ROUTER (to be able to add/delete routes) - - CONFIG_NETFILTER (will be required for the DECnet routing daemon) - -Don't turn on SIOCGIFCONF support for DECnet unless you are really sure -that you need it, in general you won't and it can cause ifconfig to -malfunction. - -Run time configuration has changed slightly from the 2.4 system. If you -want to configure an endnode, then the simplified procedure is as follows: - - - Set the MAC address on your ethernet card before starting _any_ other - network protocols. - -As soon as your network card is brought into the UP state, DECnet should -start working. If you need something more complicated or are unsure how -to set the MAC address, see the next section. Also all configurations which -worked with 2.4 will work under 2.5 with no change. - -3. Command line options -======================= - -You can set a DECnet address on the kernel command line for compatibility -with the 2.4 configuration procedure, but in general it's not needed any more. -If you do st a DECnet address on the command line, it has only one purpose -which is that its added to the addresses on the loopback device. - -With 2.4 kernels, DECnet would only recognise addresses as local if they -were added to the loopback device. In 2.5, any local interface address -can be used to loop back to the local machine. Of course this does not -prevent you adding further addresses to the loopback device if you -want to. - -N.B. Since the address list of an interface determines the addresses for -which "hello" messages are sent, if you don't set an address on the loopback -interface then you won't see any entries in /proc/net/neigh for the local -host until such time as you start a connection. This doesn't affect the -operation of the local communications in any other way though. - -The kernel command line takes options looking like the following:: - - decnet.addr=1,2 - -the two numbers are the node address 1,2 = 1.2 For 2.2.xx kernels -and early 2.3.xx kernels, you must use a comma when specifying the -DECnet address like this. For more recent 2.3.xx kernels, you may -use almost any character except space, although a `.` would be the most -obvious choice :-) - -There used to be a third number specifying the node type. This option -has gone away in favour of a per interface node type. This is now set -using /proc/sys/net/decnet/conf/<dev>/forwarding. This file can be -set with a single digit, 0=EndNode, 1=L1 Router and 2=L2 Router. - -There are also equivalent options for modules. The node address can -also be set through the /proc/sys/net/decnet/ files, as can other system -parameters. - -Currently the only supported devices are ethernet and ip_gre. The -ethernet address of your ethernet card has to be set according to the DECnet -address of the node in order for it to be autoconfigured (and then appear in -/proc/net/decnet_dev). There is a utility available at the above -FTP sites called dn2ethaddr which can compute the correct ethernet -address to use. The address can be set by ifconfig either before or -at the time the device is brought up. If you are using RedHat you can -add the line:: - - MACADDR=AA:00:04:00:03:04 - -or something similar, to /etc/sysconfig/network-scripts/ifcfg-eth0 or -wherever your network card's configuration lives. Setting the MAC address -of your ethernet card to an address starting with "hi-ord" will cause a -DECnet address which matches to be added to the interface (which you can -verify with iproute2). - -The default device for routing can be set through the /proc filesystem -by setting /proc/sys/net/decnet/default_device to the -device you want DECnet to route packets out of when no specific route -is available. Usually this will be eth0, for example:: - - echo -n "eth0" >/proc/sys/net/decnet/default_device - -If you don't set the default device, then it will default to the first -ethernet card which has been autoconfigured as described above. You can -confirm that by looking in the default_device file of course. - -There is a list of what the other files under /proc/sys/net/decnet/ do -on the kernel patch web site (shown above). - -4. Run time kernel configuration -================================ - - -This is either done through the sysctl/proc interface (see the kernel web -pages for details on what the various options do) or through the iproute2 -package in the same way as IPv4/6 configuration is performed. - -Documentation for iproute2 is included with the package, although there is -as yet no specific section on DECnet, most of the features apply to both -IP and DECnet, albeit with DECnet addresses instead of IP addresses and -a reduced functionality. - -If you want to configure a DECnet router you'll need the iproute2 package -since its the _only_ way to add and delete routes currently. Eventually -there will be a routing daemon to send and receive routing messages for -each interface and update the kernel routing tables accordingly. The -routing daemon will use netfilter to listen to routing packets, and -rtnetlink to update the kernels routing tables. - -The DECnet raw socket layer has been removed since it was there purely -for use by the routing daemon which will now use netfilter (a much cleaner -and more generic solution) instead. - -5. How can I tell if its working? -================================= - -Here is a quick guide of what to look for in order to know if your DECnet -kernel subsystem is working. - - - Is the node address set (see /proc/sys/net/decnet/node_address) - - Is the node of the correct type - (see /proc/sys/net/decnet/conf/<dev>/forwarding) - - Is the Ethernet MAC address of each Ethernet card set to match - the DECnet address. If in doubt use the dn2ethaddr utility available - at the ftp archive. - - If the previous two steps are satisfied, and the Ethernet card is up, - you should find that it is listed in /proc/net/decnet_dev and also - that it appears as a directory in /proc/sys/net/decnet/conf/. The - loopback device (lo) should also appear and is required to communicate - within a node. - - If you have any DECnet routers on your network, they should appear - in /proc/net/decnet_neigh, otherwise this file will only contain the - entry for the node itself (if it doesn't check to see if lo is up). - - If you want to send to any node which is not listed in the - /proc/net/decnet_neigh file, you'll need to set the default device - to point to an Ethernet card with connection to a router. This is - again done with the /proc/sys/net/decnet/default_device file. - - Try starting a simple server and client, like the dnping/dnmirror - over the loopback interface. With luck they should communicate. - For this step and those after, you'll need the DECnet library - which can be obtained from the above ftp sites as well as the - actual utilities themselves. - - If this seems to work, then try talking to a node on your local - network, and see if you can obtain the same results. - - At this point you are on your own... :-) - -6. How to send a bug report -=========================== - -If you've found a bug and want to report it, then there are several things -you can do to help me work out exactly what it is that is wrong. Useful -information (_most_ of which _is_ _essential_) includes: - - - What kernel version are you running ? - - What version of the patch are you running ? - - How far though the above set of tests can you get ? - - What is in the /proc/decnet* files and /proc/sys/net/decnet/* files ? - - Which services are you running ? - - Which client caused the problem ? - - How much data was being transferred ? - - Was the network congested ? - - How can the problem be reproduced ? - - Can you use tcpdump to get a trace ? (N.B. Most (all?) versions of - tcpdump don't understand how to dump DECnet properly, so including - the hex listing of the packet contents is _essential_, usually the -x flag. - You may also need to increase the length grabbed with the -s flag. The - -e flag also provides very useful information (ethernet MAC addresses)) - -7. MAC FAQ -========== - -A quick FAQ on ethernet MAC addresses to explain how Linux and DECnet -interact and how to get the best performance from your hardware. - -Ethernet cards are designed to normally only pass received network frames -to a host computer when they are addressed to it, or to the broadcast address. - -Linux has an interface which allows the setting of extra addresses for -an ethernet card to listen to. If the ethernet card supports it, the -filtering operation will be done in hardware, if not the extra unwanted packets -received will be discarded by the host computer. In the latter case, -significant processor time and bus bandwidth can be used up on a busy -network (see the NAPI documentation for a longer explanation of these -effects). - -DECnet makes use of this interface to allow running DECnet on an ethernet -card which has already been configured using TCP/IP (presumably using the -built in MAC address of the card, as usual) and/or to allow multiple DECnet -addresses on each physical interface. If you do this, be aware that if your -ethernet card doesn't support perfect hashing in its MAC address filter -then your computer will be doing more work than required. Some cards -will simply set themselves into promiscuous mode in order to receive -packets from the DECnet specified addresses. So if you have one of these -cards its better to set the MAC address of the card as described above -to gain the best efficiency. Better still is to use a card which supports -NAPI as well. - - -8. Mailing list -=============== - -If you are keen to get involved in development, or want to ask questions -about configuration, or even just report bugs, then there is a mailing -list that you can join, details are at: - -http://sourceforge.net/mail/?group_id=4993 - -9. Legal Info -============= - -The Linux DECnet project team have placed their code under the GPL. The -software is provided "as is" and without warranty express or implied. -DECnet is a trademark of Compaq. This software is not a product of -Compaq. We acknowledge the help of people at Compaq in providing extra -documentation above and beyond what was previously publicly available. - -Steve Whitehouse <SteveW@ACM.org> - diff --git a/Documentation/networking/device_drivers/can/freescale/flexcan.rst b/Documentation/networking/device_drivers/can/freescale/flexcan.rst index 4e3eec6cecd2..106cd2890135 100644 --- a/Documentation/networking/device_drivers/can/freescale/flexcan.rst +++ b/Documentation/networking/device_drivers/can/freescale/flexcan.rst @@ -5,7 +5,7 @@ Flexcan CAN Controller driver ============================= Authors: Marc Kleine-Budde <mkl@pengutronix.de>, -Dario Binacchi <dario.binacchi@amarula.solutions.com> +Dario Binacchi <dario.binacchi@amarulasolutions.com> On/off RTR frames reception =========================== diff --git a/Documentation/networking/device_drivers/ethernet/index.rst b/Documentation/networking/device_drivers/ethernet/index.rst index 7f1777173abb..5196905582c5 100644 --- a/Documentation/networking/device_drivers/ethernet/index.rst +++ b/Documentation/networking/device_drivers/ethernet/index.rst @@ -52,6 +52,7 @@ Contents: ti/tlan toshiba/spider_net wangxun/txgbe + wangxun/ngbe .. only:: subproject and html diff --git a/Documentation/networking/device_drivers/ethernet/wangxun/ngbe.rst b/Documentation/networking/device_drivers/ethernet/wangxun/ngbe.rst new file mode 100644 index 000000000000..43a02f9943e1 --- /dev/null +++ b/Documentation/networking/device_drivers/ethernet/wangxun/ngbe.rst @@ -0,0 +1,14 @@ +.. SPDX-License-Identifier: GPL-2.0 + +============================================================= +Linux Base Driver for WangXun(R) Gigabit PCI Express Adapters +============================================================= + +WangXun Gigabit Linux driver. +Copyright (c) 2019 - 2022 Beijing WangXun Technology Co., Ltd. + +Support +======= + If you have problems with the software or hardware, please contact our + customer support team via email at nic-support@net-swift.com or check our website + at https://www.net-swift.com diff --git a/Documentation/networking/devlink/ice.rst b/Documentation/networking/devlink/ice.rst index 8c082b139bbd..0c89ceb8986d 100644 --- a/Documentation/networking/devlink/ice.rst +++ b/Documentation/networking/devlink/ice.rst @@ -139,6 +139,42 @@ EMP firmware image. The driver does not currently support reloading the driver via ``DEVLINK_RELOAD_ACTION_DRIVER_REINIT``. +Port split +========== + +The ``ice`` driver supports port splitting only for port 0, as the FW has +a predefined set of available port split options for the whole device. + +A system reboot is required for port split to be applied. + +The following command will select the port split option with 4 ports: + +.. code:: shell + + $ devlink port split pci/0000:16:00.0/0 count 4 + +The list of all available port options will be printed to dynamic debug after +each ``split`` and ``unsplit`` command. The first option is the default. + +.. code:: shell + + ice 0000:16:00.0: Available port split options and max port speeds (Gbps): + ice 0000:16:00.0: Status Split Quad 0 Quad 1 + ice 0000:16:00.0: count L0 L1 L2 L3 L4 L5 L6 L7 + ice 0000:16:00.0: Active 2 100 - - - 100 - - - + ice 0000:16:00.0: 2 50 - 50 - - - - - + ice 0000:16:00.0: Pending 4 25 25 25 25 - - - - + ice 0000:16:00.0: 4 25 25 - - 25 25 - - + ice 0000:16:00.0: 8 10 10 10 10 10 10 10 10 + ice 0000:16:00.0: 1 100 - - - - - - - + +There could be multiple FW port options with the same port split count. When +the same port split count request is issued again, the next FW port option with +the same port split count will be selected. + +``devlink port unsplit`` will select the option with a split count of 1. If +there is no FW option available with split count 1, you will receive an error. + Regions ======= diff --git a/Documentation/networking/devlink/index.rst b/Documentation/networking/devlink/index.rst index e3a5f985673e..4b653d040627 100644 --- a/Documentation/networking/devlink/index.rst +++ b/Documentation/networking/devlink/index.rst @@ -13,10 +13,8 @@ new APIs prefixed by ``devl_*``. The older APIs handle all the locking in devlink core, but don't allow registration of most sub-objects once the main devlink object is itself registered. The newer ``devl_*`` APIs assume the devlink instance lock is already held. Drivers can take the instance -lock by calling ``devl_lock()``. It is also held in most of the callbacks. -Eventually all callbacks will be invoked under the devlink instance lock, -refer to the use of the ``DEVLINK_NL_FLAG_NO_LOCK`` flag in devlink core -to find out which callbacks are not converted, yet. +lock by calling ``devl_lock()``. It is also held all callbacks of devlink +netlink commands. Drivers are encouraged to use the devlink instance lock for their own needs. diff --git a/Documentation/networking/devlink/netdevsim.rst b/Documentation/networking/devlink/netdevsim.rst index 8a292fb5aaea..ec5e6d79b2e2 100644 --- a/Documentation/networking/devlink/netdevsim.rst +++ b/Documentation/networking/devlink/netdevsim.rst @@ -67,7 +67,7 @@ The ``netdevsim`` driver supports rate objects management, which includes: - setting tx_share and tx_max rate values for any rate object type; - setting parent node for any rate object type. -Rate nodes and it's parameters are exposed in ``netdevsim`` debugfs in RO mode. +Rate nodes and their parameters are exposed in ``netdevsim`` debugfs in RO mode. For example created rate node with name ``some_group``: .. code:: shell diff --git a/Documentation/networking/driver.rst b/Documentation/networking/driver.rst index c8f59dbda46f..64f7236ff10b 100644 --- a/Documentation/networking/driver.rst +++ b/Documentation/networking/driver.rst @@ -8,7 +8,7 @@ Transmit path guidelines: 1) The ndo_start_xmit method must not return NETDEV_TX_BUSY under any normal circumstances. It is considered a hard error unless - there is no way your device can tell ahead of time when it's + there is no way your device can tell ahead of time when its transmit function will become busy. Instead it must maintain the queue properly. For example, diff --git a/Documentation/networking/dsa/configuration.rst b/Documentation/networking/dsa/configuration.rst index 2b08f1a772d3..827701f8cbfe 100644 --- a/Documentation/networking/dsa/configuration.rst +++ b/Documentation/networking/dsa/configuration.rst @@ -49,6 +49,9 @@ In this documentation the following Ethernet interfaces are used: *eth0* the master interface +*eth1* + another master interface + *lan1* a slave interface @@ -360,3 +363,96 @@ the ``self`` flag) has been removed. This results in the following changes: Script writers are therefore encouraged to use the ``master static`` set of flags when working with bridge FDB entries on DSA switch interfaces. + +Affinity of user ports to CPU ports +----------------------------------- + +Typically, DSA switches are attached to the host via a single Ethernet +interface, but in cases where the switch chip is discrete, the hardware design +may permit the use of 2 or more ports connected to the host, for an increase in +termination throughput. + +DSA can make use of multiple CPU ports in two ways. First, it is possible to +statically assign the termination traffic associated with a certain user port +to be processed by a certain CPU port. This way, user space can implement +custom policies of static load balancing between user ports, by spreading the +affinities according to the available CPU ports. + +Secondly, it is possible to perform load balancing between CPU ports on a per +packet basis, rather than statically assigning user ports to CPU ports. +This can be achieved by placing the DSA masters under a LAG interface (bonding +or team). DSA monitors this operation and creates a mirror of this software LAG +on the CPU ports facing the physical DSA masters that constitute the LAG slave +devices. + +To make use of multiple CPU ports, the firmware (device tree) description of +the switch must mark all the links between CPU ports and their DSA masters +using the ``ethernet`` reference/phandle. At startup, only a single CPU port +and DSA master will be used - the numerically first port from the firmware +description which has an ``ethernet`` property. It is up to the user to +configure the system for the switch to use other masters. + +DSA uses the ``rtnl_link_ops`` mechanism (with a "dsa" ``kind``) to allow +changing the DSA master of a user port. The ``IFLA_DSA_MASTER`` u32 netlink +attribute contains the ifindex of the master device that handles each slave +device. The DSA master must be a valid candidate based on firmware node +information, or a LAG interface which contains only slaves which are valid +candidates. + +Using iproute2, the following manipulations are possible: + + .. code-block:: sh + + # See the DSA master in current use + ip -d link show dev swp0 + (...) + dsa master eth0 + + # Static CPU port distribution + ip link set swp0 type dsa master eth1 + ip link set swp1 type dsa master eth0 + ip link set swp2 type dsa master eth1 + ip link set swp3 type dsa master eth0 + + # CPU ports in LAG, using explicit assignment of the DSA master + ip link add bond0 type bond mode balance-xor && ip link set bond0 up + ip link set eth1 down && ip link set eth1 master bond0 + ip link set swp0 type dsa master bond0 + ip link set swp1 type dsa master bond0 + ip link set swp2 type dsa master bond0 + ip link set swp3 type dsa master bond0 + ip link set eth0 down && ip link set eth0 master bond0 + ip -d link show dev swp0 + (...) + dsa master bond0 + + # CPU ports in LAG, relying on implicit migration of the DSA master + ip link add bond0 type bond mode balance-xor && ip link set bond0 up + ip link set eth0 down && ip link set eth0 master bond0 + ip link set eth1 down && ip link set eth1 master bond0 + ip -d link show dev swp0 + (...) + dsa master bond0 + +Notice that in the case of CPU ports under a LAG, the use of the +``IFLA_DSA_MASTER`` netlink attribute is not strictly needed, but rather, DSA +reacts to the ``IFLA_MASTER`` attribute change of its present master (``eth0``) +and migrates all user ports to the new upper of ``eth0``, ``bond0``. Similarly, +when ``bond0`` is destroyed using ``RTM_DELLINK``, DSA migrates the user ports +that were assigned to this interface to the first physical DSA master which is +eligible, based on the firmware description (it effectively reverts to the +startup configuration). + +In a setup with more than 2 physical CPU ports, it is therefore possible to mix +static user to CPU port assignment with LAG between DSA masters. It is not +possible to statically assign a user port towards a DSA master that has any +upper interfaces (this includes LAG devices - the master must always be the LAG +in this case). + +Live changing of the DSA master (and thus CPU port) affinity of a user port is +permitted, in order to allow dynamic redistribution in response to traffic. + +Physical DSA masters are allowed to join and leave at any time a LAG interface +used as a DSA master; however, DSA will reject a LAG interface as a valid +candidate for being a DSA master unless it has at least one physical DSA master +as a slave device. diff --git a/Documentation/networking/dsa/dsa.rst b/Documentation/networking/dsa/dsa.rst index d742ba6bd211..a94ddf83348a 100644 --- a/Documentation/networking/dsa/dsa.rst +++ b/Documentation/networking/dsa/dsa.rst @@ -303,6 +303,20 @@ These frames are then queued for transmission using the master network device Ethernet switch will be able to process these incoming frames from the management interface and deliver them to the physical switch port. +When using multiple CPU ports, it is possible to stack a LAG (bonding/team) +device between the DSA slave devices and the physical DSA masters. The LAG +device is thus also a DSA master, but the LAG slave devices continue to be DSA +masters as well (just with no user port assigned to them; this is needed for +recovery in case the LAG DSA master disappears). Thus, the data path of the LAG +DSA master is used asymmetrically. On RX, the ``ETH_P_XDSA`` handler, which +calls ``dsa_switch_rcv()``, is invoked early (on the physical DSA master; +LAG slave). Therefore, the RX data path of the LAG DSA master is not used. +On the other hand, TX takes place linearly: ``dsa_slave_xmit`` calls +``dsa_enqueue_skb``, which calls ``dev_queue_xmit`` towards the LAG DSA master. +The latter calls ``dev_queue_xmit`` towards one physical DSA master or the +other, and in both cases, the packet exits the system through a hardware path +towards the switch. + Graphical representation ------------------------ @@ -629,6 +643,24 @@ Switch configuration PHY cannot be found. In this case, probing of the DSA switch continues without that particular port. +- ``port_change_master``: method through which the affinity (association used + for traffic termination purposes) between a user port and a CPU port can be + changed. By default all user ports from a tree are assigned to the first + available CPU port that makes sense for them (most of the times this means + the user ports of a tree are all assigned to the same CPU port, except for H + topologies as described in commit 2c0b03258b8b). The ``port`` argument + represents the index of the user port, and the ``master`` argument represents + the new DSA master ``net_device``. The CPU port associated with the new + master can be retrieved by looking at ``struct dsa_port *cpu_dp = + master->dsa_ptr``. Additionally, the master can also be a LAG device where + all the slave devices are physical DSA masters. LAG DSA masters also have a + valid ``master->dsa_ptr`` pointer, however this is not unique, but rather a + duplicate of the first physical DSA master's (LAG slave) ``dsa_ptr``. In case + of a LAG DSA master, a further call to ``port_lag_join`` will be emitted + separately for the physical CPU ports associated with the physical DSA + masters, requesting them to create a hardware LAG associated with the LAG + interface. + PHY devices and link management ------------------------------- @@ -1095,9 +1127,3 @@ capable hardware, but does not enforce a strict switch device driver model. On the other DSA enforces a fairly strict device driver model, and deals with most of the switch specific. At some point we should envision a merger between these two subsystems and get the best of both worlds. - -Other hanging fruits --------------------- - -- allowing more than one CPU/management interface: - http://comments.gmane.org/gmane.linux.network/365657 diff --git a/Documentation/networking/ethtool-netlink.rst b/Documentation/networking/ethtool-netlink.rst index dbca3e9ec782..d578b8bcd8a4 100644 --- a/Documentation/networking/ethtool-netlink.rst +++ b/Documentation/networking/ethtool-netlink.rst @@ -220,6 +220,8 @@ Userspace to kernel: ``ETHTOOL_MSG_PHC_VCLOCKS_GET`` get PHC virtual clocks info ``ETHTOOL_MSG_MODULE_SET`` set transceiver module parameters ``ETHTOOL_MSG_MODULE_GET`` get transceiver module parameters + ``ETHTOOL_MSG_PSE_SET`` set PSE parameters + ``ETHTOOL_MSG_PSE_GET`` get PSE parameters ===================================== ================================= Kernel to userspace: @@ -260,6 +262,7 @@ Kernel to userspace: ``ETHTOOL_MSG_STATS_GET_REPLY`` standard statistics ``ETHTOOL_MSG_PHC_VCLOCKS_GET_REPLY`` PHC virtual clocks info ``ETHTOOL_MSG_MODULE_GET_REPLY`` transceiver module parameters + ``ETHTOOL_MSG_PSE_GET_REPLY`` PSE parameters ======================================== ================================= ``GET`` requests are sent by userspace applications to retrieve device @@ -426,6 +429,7 @@ Kernel response contents: ``ETHTOOL_A_LINKMODES_DUPLEX`` u8 duplex mode ``ETHTOOL_A_LINKMODES_MASTER_SLAVE_CFG`` u8 Master/slave port mode ``ETHTOOL_A_LINKMODES_MASTER_SLAVE_STATE`` u8 Master/slave port state + ``ETHTOOL_A_LINKMODES_RATE_MATCHING`` u8 PHY rate matching ========================================== ====== ========================== For ``ETHTOOL_A_LINKMODES_OURS``, value represents advertised modes and mask @@ -449,6 +453,7 @@ Request contents: ``ETHTOOL_A_LINKMODES_SPEED`` u32 link speed (Mb/s) ``ETHTOOL_A_LINKMODES_DUPLEX`` u8 duplex mode ``ETHTOOL_A_LINKMODES_MASTER_SLAVE_CFG`` u8 Master/slave port mode + ``ETHTOOL_A_LINKMODES_RATE_MATCHING`` u8 PHY rate matching ``ETHTOOL_A_LINKMODES_LANES`` u32 lanes ========================================== ====== ========================== @@ -1625,6 +1630,62 @@ For SFF-8636 modules, low power mode is forced by the host according to table For CMIS modules, low power mode is forced by the host according to table 6-12 in revision 5.0 of the specification. +PSE_GET +======= + +Gets PSE attributes. + +Request contents: + + ===================================== ====== ========================== + ``ETHTOOL_A_PSE_HEADER`` nested request header + ===================================== ====== ========================== + +Kernel response contents: + + ====================================== ====== ============================= + ``ETHTOOL_A_PSE_HEADER`` nested reply header + ``ETHTOOL_A_PODL_PSE_ADMIN_STATE`` u32 Operational state of the PoDL + PSE functions + ``ETHTOOL_A_PODL_PSE_PW_D_STATUS`` u32 power detection status of the + PoDL PSE. + ====================================== ====== ============================= + +When set, the optional ``ETHTOOL_A_PODL_PSE_ADMIN_STATE`` attribute identifies +the operational state of the PoDL PSE functions. The operational state of the +PSE function can be changed using the ``ETHTOOL_A_PODL_PSE_ADMIN_CONTROL`` +action. This option is corresponding to ``IEEE 802.3-2018`` 30.15.1.1.2 +aPoDLPSEAdminState. Possible values are: + +.. kernel-doc:: include/uapi/linux/ethtool.h + :identifiers: ethtool_podl_pse_admin_state + +When set, the optional ``ETHTOOL_A_PODL_PSE_PW_D_STATUS`` attribute identifies +the power detection status of the PoDL PSE. The status depend on internal PSE +state machine and automatic PD classification support. This option is +corresponding to ``IEEE 802.3-2018`` 30.15.1.1.3 aPoDLPSEPowerDetectionStatus. +Possible values are: + +.. kernel-doc:: include/uapi/linux/ethtool.h + :identifiers: ethtool_podl_pse_pw_d_status + +PSE_SET +======= + +Sets PSE parameters. + +Request contents: + + ====================================== ====== ============================= + ``ETHTOOL_A_PSE_HEADER`` nested request header + ``ETHTOOL_A_PODL_PSE_ADMIN_CONTROL`` u32 Control PoDL PSE Admin state + ====================================== ====== ============================= + +When set, the optional ``ETHTOOL_A_PODL_PSE_ADMIN_CONTROL`` attribute is used +to control PoDL PSE Admin functions. This option is implementing +``IEEE 802.3-2018`` 30.15.1.2.1 acPoDLPSEAdminControl. See +``ETHTOOL_A_PODL_PSE_ADMIN_STATE`` for supported values. + Request translation =================== diff --git a/Documentation/networking/index.rst b/Documentation/networking/index.rst index 03b215bddde8..16a153bcc5fe 100644 --- a/Documentation/networking/index.rst +++ b/Documentation/networking/index.rst @@ -47,7 +47,6 @@ Contents: cdc_mbim dccp dctcp - decnet dns_resolver driver eql @@ -93,6 +92,7 @@ Contents: radiotap-headers rds regulatory + representors rxrpc sctp secid diff --git a/Documentation/networking/ip-sysctl.rst b/Documentation/networking/ip-sysctl.rst index 56cd4ea059b2..e7b3fa7bb3f7 100644 --- a/Documentation/networking/ip-sysctl.rst +++ b/Documentation/networking/ip-sysctl.rst @@ -1035,7 +1035,39 @@ tcp_limit_output_bytes - INTEGER tcp_challenge_ack_limit - INTEGER Limits number of Challenge ACK sent per second, as recommended in RFC 5961 (Improving TCP's Robustness to Blind In-Window Attacks) - Default: 1000 + Note that this per netns rate limit can allow some side channel + attacks and probably should not be enabled. + TCP stack implements per TCP socket limits anyway. + Default: INT_MAX (unlimited) + +tcp_ehash_entries - INTEGER + Show the number of hash buckets for TCP sockets in the current + networking namespace. + + A negative value means the networking namespace does not own its + hash buckets and shares the initial networking namespace's one. + +tcp_child_ehash_entries - INTEGER + Control the number of hash buckets for TCP sockets in the child + networking namespace, which must be set before clone() or unshare(). + + If the value is not 0, the kernel uses a value rounded up to 2^n + as the actual hash bucket size. 0 is a special value, meaning + the child networking namespace will share the initial networking + namespace's hash buckets. + + Note that the child will use the global one in case the kernel + fails to allocate enough memory. In addition, the global hash + buckets are spread over available NUMA nodes, but the allocation + of the child hash table depends on the current process's NUMA + policy, which could result in performance differences. + + Note also that the default value of tcp_max_tw_buckets and + tcp_max_syn_backlog depend on the hash bucket size. + + Possible values: 0, 2^n (n: 0 - 24 (16Mi)) + + Default: 0 UDP variables ============= diff --git a/Documentation/networking/ipvlan.rst b/Documentation/networking/ipvlan.rst index 694adcba36b0..0000c1d383bc 100644 --- a/Documentation/networking/ipvlan.rst +++ b/Documentation/networking/ipvlan.rst @@ -11,7 +11,7 @@ Initial Release: ================ This is conceptually very similar to the macvlan driver with one major exception of using L3 for mux-ing /demux-ing among slaves. This property makes -the master device share the L2 with it's slave devices. I have developed this +the master device share the L2 with its slave devices. I have developed this driver in conjunction with network namespaces and not sure if there is use case outside of it. diff --git a/Documentation/networking/l2tp.rst b/Documentation/networking/l2tp.rst index 498b382d25a0..7f383e99dbad 100644 --- a/Documentation/networking/l2tp.rst +++ b/Documentation/networking/l2tp.rst @@ -530,7 +530,7 @@ its tunnel close actions. For L2TPIP sockets, the socket's close handler initiates the same tunnel close actions. All sessions are first closed. Each session drops its tunnel ref. When the tunnel ref reaches zero, the tunnel puts its socket ref. When the socket is -eventually destroyed, it's sk_destruct finally frees the L2TP tunnel +eventually destroyed, its sk_destruct finally frees the L2TP tunnel context. Sessions diff --git a/Documentation/networking/mptcp-sysctl.rst b/Documentation/networking/mptcp-sysctl.rst index e263dfcc4b40..213510698014 100644 --- a/Documentation/networking/mptcp-sysctl.rst +++ b/Documentation/networking/mptcp-sysctl.rst @@ -47,7 +47,6 @@ allow_join_initial_addr_port - BOOLEAN Default: 1 pm_type - INTEGER - Set the default path manager type to use for each new MPTCP socket. In-kernel path management will control subflow connections and address advertisements according to diff --git a/Documentation/networking/nf_conntrack-sysctl.rst b/Documentation/networking/nf_conntrack-sysctl.rst index 834945ebc4cd..1120d71f28d7 100644 --- a/Documentation/networking/nf_conntrack-sysctl.rst +++ b/Documentation/networking/nf_conntrack-sysctl.rst @@ -70,15 +70,6 @@ nf_conntrack_generic_timeout - INTEGER (seconds) Default for generic timeout. This refers to layer 4 unknown/unsupported protocols. -nf_conntrack_helper - BOOLEAN - - 0 - disabled (default) - - not 0 - enabled - - Enable automatic conntrack helper assignment. - If disabled it is required to set up iptables rules to assign - helpers to connections. See the CT target description in the - iptables-extensions(8) man page for further information. - nf_conntrack_icmp_timeout - INTEGER (seconds) default 30 diff --git a/Documentation/networking/phy.rst b/Documentation/networking/phy.rst index 704f31da5167..06f4fcdb58b6 100644 --- a/Documentation/networking/phy.rst +++ b/Documentation/networking/phy.rst @@ -308,6 +308,21 @@ Some of the interface modes are described below: rate of 125Mpbs using a 4B/5B encoding scheme, resulting in an underlying data rate of 100Mpbs. +``PHY_INTERFACE_MODE_QUSGMII`` + This defines the Cisco the Quad USGMII mode, which is the Quad variant of + the USGMII (Universal SGMII) link. It's very similar to QSGMII, but uses + a Packet Control Header (PCH) instead of the 7 bytes preamble to carry not + only the port id, but also so-called "extensions". The only documented + extension so-far in the specification is the inclusion of timestamps, for + PTP-enabled PHYs. This mode isn't compatible with QSGMII, but offers the + same capabilities in terms of link speed and negociation. + +``PHY_INTERFACE_MODE_1000BASEKX`` + This is 1000BASE-X as defined by IEEE 802.3 Clause 36 with Clause 73 + autonegotiation. Generally, it will be used with a Clause 70 PMD. To + contrast with the 1000BASE-X phy mode used for Clause 38 and 39 PMDs, this + interface mode has different autonegotiation and only supports full duplex. + Pause frames / flow control =========================== diff --git a/Documentation/networking/representors.rst b/Documentation/networking/representors.rst new file mode 100644 index 000000000000..ee1f5cd54496 --- /dev/null +++ b/Documentation/networking/representors.rst @@ -0,0 +1,259 @@ +.. SPDX-License-Identifier: GPL-2.0 + +============================= +Network Function Representors +============================= + +This document describes the semantics and usage of representor netdevices, as +used to control internal switching on SmartNICs. For the closely-related port +representors on physical (multi-port) switches, see +:ref:`Documentation/networking/switchdev.rst <switchdev>`. + +Motivation +---------- + +Since the mid-2010s, network cards have started offering more complex +virtualisation capabilities than the legacy SR-IOV approach (with its simple +MAC/VLAN-based switching model) can support. This led to a desire to offload +software-defined networks (such as OpenVSwitch) to these NICs to specify the +network connectivity of each function. The resulting designs are variously +called SmartNICs or DPUs. + +Network function representors bring the standard Linux networking stack to +virtual switches and IOV devices. Just as each physical port of a Linux- +controlled switch has a separate netdev, so does each virtual port of a virtual +switch. +When the system boots, and before any offload is configured, all packets from +the virtual functions appear in the networking stack of the PF via the +representors. The PF can thus always communicate freely with the virtual +functions. +The PF can configure standard Linux forwarding between representors, the uplink +or any other netdev (routing, bridging, TC classifiers). + +Thus, a representor is both a control plane object (representing the function in +administrative commands) and a data plane object (one end of a virtual pipe). +As a virtual link endpoint, the representor can be configured like any other +netdevice; in some cases (e.g. link state) the representee will follow the +representor's configuration, while in others there are separate APIs to +configure the representee. + +Definitions +----------- + +This document uses the term "switchdev function" to refer to the PCIe function +which has administrative control over the virtual switch on the device. +Typically, this will be a PF, but conceivably a NIC could be configured to grant +these administrative privileges instead to a VF or SF (subfunction). +Depending on NIC design, a multi-port NIC might have a single switchdev function +for the whole device or might have a separate virtual switch, and hence +switchdev function, for each physical network port. +If the NIC supports nested switching, there might be separate switchdev +functions for each nested switch, in which case each switchdev function should +only create representors for the ports on the (sub-)switch it directly +administers. + +A "representee" is the object that a representor represents. So for example in +the case of a VF representor, the representee is the corresponding VF. + +What does a representor do? +--------------------------- + +A representor has three main roles. + +1. It is used to configure the network connection the representee sees, e.g. + link up/down, MTU, etc. For instance, bringing the representor + administratively UP should cause the representee to see a link up / carrier + on event. +2. It provides the slow path for traffic which does not hit any offloaded + fast-path rules in the virtual switch. Packets transmitted on the + representor netdevice should be delivered to the representee; packets + transmitted by the representee which fail to match any switching rule should + be received on the representor netdevice. (That is, there is a virtual pipe + connecting the representor to the representee, similar in concept to a veth + pair.) + This allows software switch implementations (such as OpenVSwitch or a Linux + bridge) to forward packets between representees and the rest of the network. +3. It acts as a handle by which switching rules (such as TC filters) can refer + to the representee, allowing these rules to be offloaded. + +The combination of 2) and 3) means that the behaviour (apart from performance) +should be the same whether a TC filter is offloaded or not. E.g. a TC rule +on a VF representor applies in software to packets received on that representor +netdevice, while in hardware offload it would apply to packets transmitted by +the representee VF. Conversely, a mirred egress redirect to a VF representor +corresponds in hardware to delivery directly to the representee VF. + +What functions should have a representor? +----------------------------------------- + +Essentially, for each virtual port on the device's internal switch, there +should be a representor. +Some vendors have chosen to omit representors for the uplink and the physical +network port, which can simplify usage (the uplink netdev becomes in effect the +physical port's representor) but does not generalise to devices with multiple +ports or uplinks. + +Thus, the following should all have representors: + + - VFs belonging to the switchdev function. + - Other PFs on the local PCIe controller, and any VFs belonging to them. + - PFs and VFs on external PCIe controllers on the device (e.g. for any embedded + System-on-Chip within the SmartNIC). + - PFs and VFs with other personalities, including network block devices (such + as a vDPA virtio-blk PF backed by remote/distributed storage), if (and only + if) their network access is implemented through a virtual switch port. [#]_ + Note that such functions can require a representor despite the representee + not having a netdev. + - Subfunctions (SFs) belonging to any of the above PFs or VFs, if they have + their own port on the switch (as opposed to using their parent PF's port). + - Any accelerators or plugins on the device whose interface to the network is + through a virtual switch port, even if they do not have a corresponding PCIe + PF or VF. + +This allows the entire switching behaviour of the NIC to be controlled through +representor TC rules. + +It is a common misunderstanding to conflate virtual ports with PCIe virtual +functions or their netdevs. While in simple cases there will be a 1:1 +correspondence between VF netdevices and VF representors, more advanced device +configurations may not follow this. +A PCIe function which does not have network access through the internal switch +(not even indirectly through the hardware implementation of whatever services +the function provides) should *not* have a representor (even if it has a +netdev). +Such a function has no switch virtual port for the representor to configure or +to be the other end of the virtual pipe. +The representor represents the virtual port, not the PCIe function nor the 'end +user' netdevice. + +.. [#] The concept here is that a hardware IP stack in the device performs the + translation between block DMA requests and network packets, so that only + network packets pass through the virtual port onto the switch. The network + access that the IP stack "sees" would then be configurable through tc rules; + e.g. its traffic might all be wrapped in a specific VLAN or VxLAN. However, + any needed configuration of the block device *qua* block device, not being a + networking entity, would not be appropriate for the representor and would + thus use some other channel such as devlink. + Contrast this with the case of a virtio-blk implementation which forwards the + DMA requests unchanged to another PF whose driver then initiates and + terminates IP traffic in software; in that case the DMA traffic would *not* + run over the virtual switch and the virtio-blk PF should thus *not* have a + representor. + +How are representors created? +----------------------------- + +The driver instance attached to the switchdev function should, for each virtual +port on the switch, create a pure-software netdevice which has some form of +in-kernel reference to the switchdev function's own netdevice or driver private +data (``netdev_priv()``). +This may be by enumerating ports at probe time, reacting dynamically to the +creation and destruction of ports at run time, or a combination of the two. + +The operations of the representor netdevice will generally involve acting +through the switchdev function. For example, ``ndo_start_xmit()`` might send +the packet through a hardware TX queue attached to the switchdev function, with +either packet metadata or queue configuration marking it for delivery to the +representee. + +How are representors identified? +-------------------------------- + +The representor netdevice should *not* directly refer to a PCIe device (e.g. +through ``net_dev->dev.parent`` / ``SET_NETDEV_DEV()``), either of the +representee or of the switchdev function. +Instead, it should implement the ``ndo_get_devlink_port()`` netdevice op, which +the kernel uses to provide the ``phys_switch_id`` and ``phys_port_name`` sysfs +nodes. (Some legacy drivers implement ``ndo_get_port_parent_id()`` and +``ndo_get_phys_port_name()`` directly, but this is deprecated.) See +:ref:`Documentation/networking/devlink/devlink-port.rst <devlink_port>` for the +details of this API. + +It is expected that userland will use this information (e.g. through udev rules) +to construct an appropriately informative name or alias for the netdevice. For +instance if the switchdev function is ``eth4`` then a representor with a +``phys_port_name`` of ``p0pf1vf2`` might be renamed ``eth4pf1vf2rep``. + +There are as yet no established conventions for naming representors which do not +correspond to PCIe functions (e.g. accelerators and plugins). + +How do representors interact with TC rules? +------------------------------------------- + +Any TC rule on a representor applies (in software TC) to packets received by +that representor netdevice. Thus, if the delivery part of the rule corresponds +to another port on the virtual switch, the driver may choose to offload it to +hardware, applying it to packets transmitted by the representee. + +Similarly, since a TC mirred egress action targeting the representor would (in +software) send the packet through the representor (and thus indirectly deliver +it to the representee), hardware offload should interpret this as delivery to +the representee. + +As a simple example, if ``PORT_DEV`` is the physical port representor and +``REP_DEV`` is a VF representor, the following rules:: + + tc filter add dev $REP_DEV parent ffff: protocol ipv4 flower \ + action mirred egress redirect dev $PORT_DEV + tc filter add dev $PORT_DEV parent ffff: protocol ipv4 flower skip_sw \ + action mirred egress mirror dev $REP_DEV + +would mean that all IPv4 packets from the VF are sent out the physical port, and +all IPv4 packets received on the physical port are delivered to the VF in +addition to ``PORT_DEV``. (Note that without ``skip_sw`` on the second rule, +the VF would get two copies, as the packet reception on ``PORT_DEV`` would +trigger the TC rule again and mirror the packet to ``REP_DEV``.) + +On devices without separate port and uplink representors, ``PORT_DEV`` would +instead be the switchdev function's own uplink netdevice. + +Of course the rules can (if supported by the NIC) include packet-modifying +actions (e.g. VLAN push/pop), which should be performed by the virtual switch. + +Tunnel encapsulation and decapsulation are rather more complicated, as they +involve a third netdevice (a tunnel netdev operating in metadata mode, such as +a VxLAN device created with ``ip link add vxlan0 type vxlan external``) and +require an IP address to be bound to the underlay device (e.g. switchdev +function uplink netdev or port representor). TC rules such as:: + + tc filter add dev $REP_DEV parent ffff: flower \ + action tunnel_key set id $VNI src_ip $LOCAL_IP dst_ip $REMOTE_IP \ + dst_port 4789 \ + action mirred egress redirect dev vxlan0 + tc filter add dev vxlan0 parent ffff: flower enc_src_ip $REMOTE_IP \ + enc_dst_ip $LOCAL_IP enc_key_id $VNI enc_dst_port 4789 \ + action tunnel_key unset action mirred egress redirect dev $REP_DEV + +where ``LOCAL_IP`` is an IP address bound to ``PORT_DEV``, and ``REMOTE_IP`` is +another IP address on the same subnet, mean that packets sent by the VF should +be VxLAN encapsulated and sent out the physical port (the driver has to deduce +this by a route lookup of ``LOCAL_IP`` leading to ``PORT_DEV``, and also +perform an ARP/neighbour table lookup to find the MAC addresses to use in the +outer Ethernet frame), while UDP packets received on the physical port with UDP +port 4789 should be parsed as VxLAN and, if their VSID matches ``$VNI``, +decapsulated and forwarded to the VF. + +If this all seems complicated, just remember the 'golden rule' of TC offload: +the hardware should ensure the same final results as if the packets were +processed through the slow path, traversed software TC (except ignoring any +``skip_hw`` rules and applying any ``skip_sw`` rules) and were transmitted or +received through the representor netdevices. + +Configuring the representee's MAC +--------------------------------- + +The representee's link state is controlled through the representor. Setting the +representor administratively UP or DOWN should cause carrier ON or OFF at the +representee. + +Setting an MTU on the representor should cause that same MTU to be reported to +the representee. +(On hardware that allows configuring separate and distinct MTU and MRU values, +the representor MTU should correspond to the representee's MRU and vice-versa.) + +Currently there is no way to use the representor to set the station permanent +MAC address of the representee; other methods available to do this include: + + - legacy SR-IOV (``ip link set DEVICE vf NUM mac LLADDR``) + - devlink port function (see **devlink-port(8)** and + :ref:`Documentation/networking/devlink/devlink-port.rst <devlink_port>`) diff --git a/Documentation/networking/rxrpc.rst b/Documentation/networking/rxrpc.rst index 39c2249c7aa7..39494a6ea739 100644 --- a/Documentation/networking/rxrpc.rst +++ b/Documentation/networking/rxrpc.rst @@ -1055,17 +1055,6 @@ The kernel interface functions are as follows: first function to change. Note that this must be called in TASK_RUNNING state. - (#) Get reply timestamp:: - - bool rxrpc_kernel_get_reply_time(struct socket *sock, - struct rxrpc_call *call, - ktime_t *_ts) - - This allows the timestamp on the first DATA packet of the reply of a - client call to be queried, provided that it is still in the Rx ring. If - successful, the timestamp will be stored into ``*_ts`` and true will be - returned; false will be returned otherwise. - (#) Get remote client epoch:: u32 rxrpc_kernel_get_epoch(struct socket *sock, diff --git a/Documentation/networking/smc-sysctl.rst b/Documentation/networking/smc-sysctl.rst index 742e90e6d822..6d8acdbe9be1 100644 --- a/Documentation/networking/smc-sysctl.rst +++ b/Documentation/networking/smc-sysctl.rst @@ -34,3 +34,28 @@ smcr_buf_type - INTEGER - 1 - Use virtually contiguous buffers - 2 - Mixed use of the two types. Try physically contiguous buffers first. If not available, use virtually contiguous buffers then. + +smcr_testlink_time - INTEGER + How frequently SMC-R link sends out TEST_LINK LLC messages to confirm + viability, after the last activity of connections on it. Value 0 means + disabling TEST_LINK. + + Default: 30 seconds. + +wmem - INTEGER + Initial size of send buffer used by SMC sockets. + The default value inherits from net.ipv4.tcp_wmem[1]. + + The minimum value is 16KiB and there is no hard limit for max value, but + only allowed 512KiB for SMC-R and 1MiB for SMC-D. + + Default: 16K + +rmem - INTEGER + Initial size of receive buffer (RMB) used by SMC sockets. + The default value inherits from net.ipv4.tcp_rmem[1]. + + The minimum value is 16KiB and there is no hard limit for max value, but + only allowed 512KiB for SMC-R and 1MiB for SMC-D. + + Default: 128K diff --git a/Documentation/networking/switchdev.rst b/Documentation/networking/switchdev.rst index f1f4e6a85a29..758f1dae3fce 100644 --- a/Documentation/networking/switchdev.rst +++ b/Documentation/networking/switchdev.rst @@ -1,5 +1,6 @@ .. SPDX-License-Identifier: GPL-2.0 .. include:: <isonum.txt> +.. _switchdev: =============================================== Ethernet switch device driver model (switchdev) @@ -159,7 +160,7 @@ tools such as iproute2. The switchdev driver can know a particular port's position in the topology by monitoring NETDEV_CHANGEUPPER notifications. For example, a port moved into a -bond will see it's upper master change. If that bond is moved into a bridge, +bond will see its upper master change. If that bond is moved into a bridge, the bond's upper master will change. And so on. The driver will track such movements to know what position a port is in in the overall topology by registering for netdevice events and acting on NETDEV_CHANGEUPPER. diff --git a/Documentation/process/5.Posting.rst b/Documentation/process/5.Posting.rst index 906235c11c24..d87f1fee4cbc 100644 --- a/Documentation/process/5.Posting.rst +++ b/Documentation/process/5.Posting.rst @@ -256,8 +256,10 @@ The tags in common use are: - Cc: the named person received a copy of the patch and had the opportunity to comment on it. -Be careful in the addition of tags to your patches: only Cc: is appropriate -for addition without the explicit permission of the person named. +Be careful in the addition of tags to your patches, as only Cc: is appropriate +for addition without the explicit permission of the person named; using +Reported-by: is fine most of the time as well, but ask for permission if +the bug was reported in private. Sending the patch diff --git a/Documentation/process/changes.rst b/Documentation/process/changes.rst index 19c286c23786..9a90197989dd 100644 --- a/Documentation/process/changes.rst +++ b/Documentation/process/changes.rst @@ -31,6 +31,8 @@ you probably needn't concern yourself with pcmciautils. ====================== =============== ======================================== GNU C 5.1 gcc --version Clang/LLVM (optional) 11.0.0 clang --version +Rust (optional) 1.62.0 rustc --version +bindgen (optional) 0.56.0 bindgen --version GNU make 3.81 make --version bash 4.2 bash --version binutils 2.23 ld -v @@ -80,6 +82,29 @@ kernels. Older releases aren't guaranteed to work, and we may drop workarounds from the kernel that were used to support older versions. Please see additional docs on :ref:`Building Linux with Clang/LLVM <kbuild_llvm>`. +Rust (optional) +--------------- + +A particular version of the Rust toolchain is required. Newer versions may or +may not work because the kernel depends on some unstable Rust features, for +the moment. + +Each Rust toolchain comes with several "components", some of which are required +(like ``rustc``) and some that are optional. The ``rust-src`` component (which +is optional) needs to be installed to build the kernel. Other components are +useful for developing. + +Please see Documentation/rust/quick-start.rst for instructions on how to +satisfy the build requirements of Rust support. In particular, the ``Makefile`` +target ``rustavailable`` is useful to check why the Rust toolchain may not +be detected. + +bindgen (optional) +------------------ + +``bindgen`` is used to generate the Rust bindings to the C side of the kernel. +It depends on ``libclang``. + Make ---- @@ -348,6 +373,12 @@ Sphinx Please see :ref:`sphinx_install` in :ref:`Documentation/doc-guide/sphinx.rst <sphinxdoc>` for details about Sphinx requirements. +rustdoc +------- + +``rustdoc`` is used to generate the documentation for Rust code. Please see +Documentation/rust/general-information.rst for more information. + Getting updated software ======================== @@ -364,6 +395,16 @@ Clang/LLVM - :ref:`Getting LLVM <getting_llvm>`. +Rust +---- + +- Documentation/rust/quick-start.rst. + +bindgen +------- + +- Documentation/rust/quick-start.rst. + Make ---- diff --git a/Documentation/process/code-of-conduct-interpretation.rst b/Documentation/process/code-of-conduct-interpretation.rst index e899f14a4ba2..922e0b547bc3 100644 --- a/Documentation/process/code-of-conduct-interpretation.rst +++ b/Documentation/process/code-of-conduct-interpretation.rst @@ -51,7 +51,7 @@ the Technical Advisory Board (TAB) or other maintainers if you're uncertain how to handle situations that come up. It will not be considered a violation report unless you want it to be. If you are uncertain about approaching the TAB or any other maintainers, please -reach out to our conflict mediator, Mishi Choudhary <mishi@linux.com>. +reach out to our conflict mediator, Joanna Lee <joanna.lee@gesmer.com>. In the end, "be kind to each other" is really what the end goal is for everybody. We know everyone is human and we all fail at times, but the @@ -127,10 +127,12 @@ are listed at https://kernel.org/code-of-conduct.html. Members can not access reports made before they joined or after they have left the committee. -The initial Code of Conduct Committee consists of volunteer members of -the TAB, as well as a professional mediator acting as a neutral third -party. The first task of the committee is to establish documented -processes, which will be made public. +The Code of Conduct Committee consists of volunteer community members +appointed by the TAB, as well as a professional mediator acting as a +neutral third party. The processes the Code of Conduct committee will +use to address reports is varied and will depend on the individual +circumstance, however, this file serves as documentation for the +general process used. Any member of the committee, including the mediator, can be contacted directly if a reporter does not wish to include the full committee in a @@ -141,16 +143,16 @@ processes (see above) and consults with the TAB as needed and appropriate, for instance to request and receive information about the kernel community. -Any decisions by the committee will be brought to the TAB, for -implementation of enforcement with the relevant maintainers if needed. -A decision by the Code of Conduct Committee can be overturned by the TAB -by a two-thirds vote. +Any decisions regarding enforcement recommendations will be brought to +the TAB for implementation of enforcement with the relevant maintainers +if needed. A decision by the Code of Conduct Committee can be overturned +by the TAB by a two-thirds vote. At quarterly intervals, the Code of Conduct Committee and TAB will provide a report summarizing the anonymised reports that the Code of Conduct committee has received and their status, as well details of any overridden decisions including complete and identifiable voting details. -We expect to establish a different process for Code of Conduct Committee -staffing beyond the bootstrap period. This document will be updated -with that information when this occurs. +Because how we interpret and enforce the Code of Conduct will evolve over +time, this document will be updated when necessary to reflect any +changes. diff --git a/Documentation/process/coding-style.rst b/Documentation/process/coding-style.rst index 03eb53fd029a..007e49ef6cec 100644 --- a/Documentation/process/coding-style.rst +++ b/Documentation/process/coding-style.rst @@ -1186,6 +1186,68 @@ expression used. For instance: #endif /* CONFIG_SOMETHING */ +22) Do not crash the kernel +--------------------------- + +In general, the decision to crash the kernel belongs to the user, rather +than to the kernel developer. + +Avoid panic() +************* + +panic() should be used with care and primarily only during system boot. +panic() is, for example, acceptable when running out of memory during boot and +not being able to continue. + +Use WARN() rather than BUG() +**************************** + +Do not add new code that uses any of the BUG() variants, such as BUG(), +BUG_ON(), or VM_BUG_ON(). Instead, use a WARN*() variant, preferably +WARN_ON_ONCE(), and possibly with recovery code. Recovery code is not +required if there is no reasonable way to at least partially recover. + +"I'm too lazy to do error handling" is not an excuse for using BUG(). Major +internal corruptions with no way of continuing may still use BUG(), but need +good justification. + +Use WARN_ON_ONCE() rather than WARN() or WARN_ON() +************************************************** + +WARN_ON_ONCE() is generally preferred over WARN() or WARN_ON(), because it +is common for a given warning condition, if it occurs at all, to occur +multiple times. This can fill up and wrap the kernel log, and can even slow +the system enough that the excessive logging turns into its own, additional +problem. + +Do not WARN lightly +******************* + +WARN*() is intended for unexpected, this-should-never-happen situations. +WARN*() macros are not to be used for anything that is expected to happen +during normal operation. These are not pre- or post-condition asserts, for +example. Again: WARN*() must not be used for a condition that is expected +to trigger easily, for example, by user space actions. pr_warn_once() is a +possible alternative, if you need to notify the user of a problem. + +Do not worry about panic_on_warn users +************************************** + +A few more words about panic_on_warn: Remember that ``panic_on_warn`` is an +available kernel option, and that many users set this option. This is why +there is a "Do not WARN lightly" writeup, above. However, the existence of +panic_on_warn users is not a valid reason to avoid the judicious use +WARN*(). That is because, whoever enables panic_on_warn has explicitly +asked the kernel to crash if a WARN*() fires, and such users must be +prepared to deal with the consequences of a system that is somewhat more +likely to crash. + +Use BUILD_BUG_ON() for compile-time assertions +********************************************** + +The use of BUILD_BUG_ON() is acceptable and encouraged, because it is a +compile-time assertion that has no effect at runtime. + Appendix I) References ---------------------- diff --git a/Documentation/process/deprecated.rst b/Documentation/process/deprecated.rst index a6e36d9c3d14..c8fd53a11a20 100644 --- a/Documentation/process/deprecated.rst +++ b/Documentation/process/deprecated.rst @@ -138,17 +138,20 @@ be NUL terminated. This can lead to various linear read overflows and other misbehavior due to the missing termination. It also NUL-pads the destination buffer if the source contents are shorter than the destination buffer size, which may be a needless performance penalty -for callers using only NUL-terminated strings. The safe replacement is +for callers using only NUL-terminated strings. + +When the destination is required to be NUL-terminated, the replacement is strscpy(), though care must be given to any cases where the return value of strncpy() was used, since strscpy() does not return a pointer to the destination, but rather a count of non-NUL bytes copied (or negative errno when it truncates). Any cases still needing NUL-padding should instead use strscpy_pad(). -If a caller is using non-NUL-terminated strings, strncpy() can -still be used, but destinations should be marked with the `__nonstring +If a caller is using non-NUL-terminated strings, strtomem() should be +used, and the destinations should be marked with the `__nonstring <https://gcc.gnu.org/onlinedocs/gcc/Common-Variable-Attributes.html>`_ -attribute to avoid future compiler warnings. +attribute to avoid future compiler warnings. For cases still needing +NUL-padding, strtomem_pad() can be used. strlcpy() --------- diff --git a/Documentation/process/index.rst b/Documentation/process/index.rst index 2ba2a1582bbe..d4b6217472b0 100644 --- a/Documentation/process/index.rst +++ b/Documentation/process/index.rst @@ -5,6 +5,7 @@ .. _process_index: +============================================= Working with the kernel development community ============================================= diff --git a/Documentation/process/maintainer-pgp-guide.rst b/Documentation/process/maintainer-pgp-guide.rst index 29e7d7b1cd44..40bfbd3b7648 100644 --- a/Documentation/process/maintainer-pgp-guide.rst +++ b/Documentation/process/maintainer-pgp-guide.rst @@ -121,57 +121,56 @@ edit your ``~/.gnupg/gpg-agent.conf`` file to set your own values:: to remove anything you had in place for older versions of GnuPG, as it may not be doing the right thing any more. -Set up a refresh cronjob -~~~~~~~~~~~~~~~~~~~~~~~~ - -You will need to regularly refresh your keyring in order to get the -latest changes on other people's public keys, which is best done with a -daily cronjob:: - - @daily /usr/bin/gpg2 --refresh >/dev/null 2>&1 - -Check the full path to your ``gpg`` or ``gpg2`` command and use the -``gpg2`` command if regular ``gpg`` for you is the legacy GnuPG v.1. - -.. _master_key: +.. _protect_your_key: -Protect your master PGP key -=========================== +Protect your PGP key +==================== This guide assumes that you already have a PGP key that you use for Linux kernel development purposes. If you do not yet have one, please see the "`Protecting Code Integrity`_" document mentioned earlier for guidance on how to create a new one. -You should also make a new key if your current one is weaker than 2048 bits -(RSA). - -Master key vs. Subkeys ----------------------- - -Subkeys are fully independent PGP keypairs that are tied to the "master" -key using certifying key signatures (certificates). It is important to -understand the following: - -1. There are no technical differences between the "master key" and "subkeys." -2. At creation time, we assign functional limitations to each key by - giving it specific capabilities. -3. A PGP key can have 4 capabilities: - - - **[S]** key can be used for signing - - **[E]** key can be used for encryption - - **[A]** key can be used for authentication - - **[C]** key can be used for certifying other keys - -4. A single key may have multiple capabilities. -5. A subkey is fully independent from the master key. A message - encrypted to a subkey cannot be decrypted with the master key. If you - lose your private subkey, it cannot be recreated from the master key - in any way. - -The key carrying the **[C]** (certify) capability is considered the -"master" key because it is the only key that can be used to indicate -relationship with other keys. Only the **[C]** key can be used to: +You should also make a new key if your current one is weaker than 2048 +bits (RSA). + +Understanding PGP Subkeys +------------------------- + +A PGP key rarely consists of a single keypair -- usually it is a +collection of independent subkeys that can be used for different +purposes based on their capabilities, assigned at their creation time. +PGP defines four capabilities that a key can have: + +- **[S]** keys can be used for signing +- **[E]** keys can be used for encryption +- **[A]** keys can be used for authentication +- **[C]** keys can be used for certifying other keys + +The key with the **[C]** capability is often called the "master" key, +but this terminology is misleading because it implies that the Certify +key can be used in place of any of other subkey on the same chain (like +a physical "master key" can be used to open the locks made for other +keys). Since this is not the case, this guide will refer to it as "the +Certify key" to avoid any ambiguity. + +It is critical to fully understand the following: + +1. All subkeys are fully independent from each other. If you lose a + private subkey, it cannot be restored or recreated from any other + private key on your chain. +2. With the exception of the Certify key, there can be multiple subkeys + with identical capabilities (e.g. you can have 2 valid encryption + subkeys, 3 valid signing subkeys, but only one valid certification + subkey). All subkeys are fully independent -- a message encrypted to + one **[E]** subkey cannot be decrypted with any other **[E]** subkey + you may also have. +3. A single subkey may have multiple capabilities (e.g. your **[C]** key + can also be your **[S]** key). + +The key carrying the **[C]** (certify) capability is the only key that +can be used to indicate relationship with other keys. Only the **[C]** +key can be used to: - add or revoke other keys (subkeys) with S/E/A capabilities - add, change or revoke identities (uids) associated with the key @@ -180,7 +179,7 @@ relationship with other keys. Only the **[C]** key can be used to: By default, GnuPG creates the following when generating new keys: -- A master key carrying both Certify and Sign capabilities (**[SC]**) +- One subkey carrying both Certify and Sign capabilities (**[SC]**) - A separate subkey with the Encryption capability (**[E]**) If you used the default parameters when generating your key, then that @@ -192,9 +191,6 @@ for example:: uid [ultimate] Alice Dev <adev@kernel.org> ssb rsa2048 2018-01-23 [E] [expires: 2020-01-23] -Any key carrying the **[C]** capability is your master key, regardless -of any other capabilities it may have assigned to it. - The long line under the ``sec`` entry is your key fingerprint -- whenever you see ``[fpr]`` in the examples below, that 40-character string is what it refers to. @@ -215,37 +211,30 @@ strong passphrase. To set it or change it, use:: Create a separate Signing subkey -------------------------------- -Our goal is to protect your master key by moving it to offline media, so -if you only have a combined **[SC]** key, then you should create a separate -signing subkey:: +Our goal is to protect your Certify key by moving it to offline media, +so if you only have a combined **[SC]** key, then you should create a +separate signing subkey:: $ gpg --quick-addkey [fpr] ed25519 sign -Remember to tell the keyservers about this change, so others can pull down -your new subkey:: - - $ gpg --send-key [fpr] - .. note:: ECC support in GnuPG GnuPG 2.1 and later has full support for Elliptic Curve Cryptography, with ability to combine ECC subkeys with traditional - RSA master keys. The main upside of ECC cryptography is that it is - much faster computationally and creates much smaller signatures when + RSA keys. The main upside of ECC cryptography is that it is much + faster computationally and creates much smaller signatures when compared byte for byte with 2048+ bit RSA keys. Unless you plan on using a smartcard device that does not support ECC operations, we recommend that you create an ECC signing subkey for your kernel work. - If for some reason you prefer to stay with RSA subkeys, just replace - "ed25519" with "rsa2048" in the above command. Additionally, if you - plan to use a hardware device that does not support ED25519 ECC - keys, like Nitrokey Pro or a Yubikey, then you should use - "nistp256" instead or "ed25519." + Note, that if you plan to use a hardware device that does not + support ED25519 ECC keys, you should choose "nistp256" instead or + "ed25519." -Back up your master key for disaster recovery ---------------------------------------------- +Back up your Certify key for disaster recovery +---------------------------------------------- The more signatures you have on your PGP key from other developers, the more reasons you have to create a backup version that lives on something @@ -277,9 +266,7 @@ home, such as your bank vault. Your printer is probably no longer a simple dumb device connected to your parallel port, but since the output is still encrypted with your passphrase, printing out even to "cloud-integrated" modern - printers should remain a relatively safe operation. One option is to - change the passphrase on your master key immediately after you are - done with paperkey. + printers should remain a relatively safe operation. Back up your whole GnuPG directory ---------------------------------- @@ -300,7 +287,7 @@ will use for backup purposes. You will need to encrypt them using LUKS -- refer to your distro's documentation on how to accomplish this. For the encryption passphrase, you can use the same one as on your -master key. +PGP key. Once the encryption process is over, re-insert the USB drive and make sure it gets properly mounted. Copy your entire ``.gnupg`` directory @@ -319,7 +306,7 @@ far away, because you'll need to use it every now and again for things like editing identities, adding or revoking subkeys, or signing other people's keys. -Remove the master key from your homedir +Remove the Certify key from your homedir ---------------------------------------- The files in our home directory are not as well protected as we like to @@ -334,7 +321,7 @@ think. They can be leaked or stolen via many different means: Protecting your key with a good passphrase greatly helps reduce the risk of any of the above, but passphrases can be discovered via keyloggers, shoulder-surfing, or any number of other means. For this reason, the -recommended setup is to remove your master key from your home directory +recommended setup is to remove your Certify key from your home directory and store it on offline storage. .. warning:: @@ -343,7 +330,7 @@ and store it on offline storage. your GnuPG directory in its entirety. What we are about to do will render your key useless if you do not have a usable backup! -First, identify the keygrip of your master key:: +First, identify the keygrip of your Certify key:: $ gpg --with-keygrip --list-key [fpr] @@ -359,7 +346,7 @@ The output will be something like this:: Keygrip = 3333000000000000000000000000000000000000 Find the keygrip entry that is beneath the ``pub`` line (right under the -master key fingerprint). This will correspond directly to a file in your +Certify key fingerprint). This will correspond directly to a file in your ``~/.gnupg`` directory:: $ cd ~/.gnupg/private-keys-v1.d @@ -369,13 +356,13 @@ master key fingerprint). This will correspond directly to a file in your 3333000000000000000000000000000000000000.key All you have to do is simply remove the .key file that corresponds to -the master keygrip:: +the Certify key keygrip:: $ cd ~/.gnupg/private-keys-v1.d $ rm 1111000000000000000000000000000000000000.key Now, if you issue the ``--list-secret-keys`` command, it will show that -the master key is missing (the ``#`` indicates it is not available):: +the Certify key is missing (the ``#`` indicates it is not available):: $ gpg --list-secret-keys sec# rsa2048 2018-01-24 [SC] [expires: 2020-01-24] @@ -404,7 +391,7 @@ file, which still contains your private keys. Move the subkeys to a dedicated crypto device ============================================= -Even though the master key is now safe from being leaked or stolen, the +Even though the Certify key is now safe from being leaked or stolen, the subkeys are still in your home directory. Anyone who manages to get their hands on those will be able to decrypt your communication or fake your signatures (if they know the passphrase). Furthermore, each time a @@ -447,7 +434,8 @@ functionality. There are several options available: - `Yubikey 5`_: proprietary hardware and software, but cheaper than Nitrokey Pro and comes available in the USB-C form that is more useful with newer laptops. Offers additional security features such as FIDO - U2F, among others, and now finally supports ECC keys (NISTP). + U2F, among others, and now finally supports NISTP and ED25519 ECC + keys. `LWN has a good review`_ of some of the above models, as well as several others. Your choice will depend on cost, shipping availability in your @@ -460,7 +448,7 @@ geographical region, and open/proprietary hardware considerations. Foundation. .. _`Nitrokey Start`: https://shop.nitrokey.com/shop/product/nitrokey-start-6 -.. _`Nitrokey Pro 2`: https://shop.nitrokey.com/shop/product/nitrokey-pro-2-3 +.. _`Nitrokey Pro 2`: https://shop.nitrokey.com/shop/product/nkpr2-nitrokey-pro-2-3 .. _`Yubikey 5`: https://www.yubico.com/products/yubikey-5-overview/ .. _Gnuk: https://www.fsij.org/doc-gnuk/ .. _`LWN has a good review`: https://lwn.net/Articles/736231/ @@ -627,10 +615,10 @@ Other common GnuPG operations Here is a quick reference for some common operations you'll need to do with your PGP key. -Mounting your master key offline storage -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +Mounting your safe offline storage +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -You will need your master key for any of the operations below, so you +You will need your Certify key for any of the operations below, so you will first need to mount your backup offline storage and tell GnuPG to use it:: @@ -644,7 +632,7 @@ your regular home directory location). Extending key expiration date ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -The master key has the default expiration date of 2 years from the date +The Certify key has the default expiration date of 2 years from the date of creation. This is done both for security reasons and to make obsolete keys eventually disappear from keyservers. @@ -685,6 +673,7 @@ remote end. .. _`Agent Forwarding over SSH`: https://wiki.gnupg.org/AgentForwarding +.. _pgp_with_git: Using PGP with Git ================== @@ -828,6 +817,63 @@ You can tell git to always sign commits:: .. _verify_identities: + +How to work with signed patches +------------------------------- + +It is possible to use your PGP key to sign patches sent to kernel +developer mailing lists. Since existing email signature mechanisms +(PGP-Mime or PGP-inline) tend to cause problems with regular code +review tasks, you should use the tool kernel.org created for this +purpose that puts cryptographic attestation signatures into message +headers (a-la DKIM): + +- `Patatt Patch Attestation`_ + +.. _`Patatt Patch Attestation`: https://pypi.org/project/patatt/ + +Installing and configuring patatt +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Patatt is packaged for many distributions already, so please check there +first. You can also install it from pypi using "``pip install patatt``". + +If you already have your PGP key configured with git (via the +``user.signingKey`` configuration parameter), then patatt requires no +further configuration. You can start signing your patches by installing +the git-send-email hook in the repository you want:: + + patatt install-hook + +Now any patches you send with ``git send-email`` will be automatically +signed with your cryptographic signature. + +Checking patatt signatures +~~~~~~~~~~~~~~~~~~~~~~~~~~ + +If you are using ``b4`` to retrieve and apply patches, then it will +automatically attempt to verify all DKIM and patatt signatures it +encounters, for example:: + + $ b4 am 20220720205013.890942-1-broonie@kernel.org + [...] + Checking attestation on all messages, may take a moment... + --- + ✓ [PATCH v1 1/3] kselftest/arm64: Correct buffer allocation for SVE Z registers + ✓ [PATCH v1 2/3] arm64/sve: Document our actual ABI for clearing registers on syscall + ✓ [PATCH v1 3/3] kselftest/arm64: Enforce actual ABI for SVE syscalls + --- + ✓ Signed: openpgp/broonie@kernel.org + ✓ Signed: DKIM/kernel.org + +.. note:: + + Patatt and b4 are still in active development and you should check + the latest documentation for these projects for any new or updated + features. + +.. _kernel_identities: + How to verify kernel developer identities ========================================= @@ -899,65 +945,17 @@ the new default in GnuPG v2). To set it, add (or modify) the trust-model tofu+pgp -How to use keyservers (more) safely ------------------------------------ - -If you get a "No public key" error when trying to validate someone's -tag, then you should attempt to lookup that key using a keyserver. It is -important to keep in mind that there is absolutely no guarantee that the -key you retrieve from PGP keyservers belongs to the actual person -- -that much is by design. You are supposed to use the Web of Trust to -establish key validity. - -How to properly maintain the Web of Trust is beyond the scope of this -document, simply because doing it properly requires both effort and -dedication that tends to be beyond the caring threshold of most human -beings. Here are some shortcuts that will help you reduce the risk of -importing a malicious key. - -First, let's say you've tried to run ``git verify-tag`` but it returned -an error saying the key is not found:: - - $ git verify-tag sunxi-fixes-for-4.15-2 - gpg: Signature made Sun 07 Jan 2018 10:51:55 PM EST - gpg: using RSA key DA73759BF8619E484E5A3B47389A54219C0F2430 - gpg: issuer "wens@...org" - gpg: Can't check signature: No public key - -Let's query the keyserver for more info about that key fingerprint (the -fingerprint probably belongs to a subkey, so we can't use it directly -without finding out the ID of the master key it is associated with):: - - $ gpg --search DA73759BF8619E484E5A3B47389A54219C0F2430 - gpg: data source: hkp://keys.gnupg.net - (1) Chen-Yu Tsai <wens@...org> - 4096 bit RSA key C94035C21B4F2AEB, created: 2017-03-14, expires: 2019-03-15 - Keys 1-1 of 1 for "DA73759BF8619E484E5A3B47389A54219C0F2430". Enter number(s), N)ext, or Q)uit > q - -Locate the ID of the master key in the output, in our example -``C94035C21B4F2AEB``. Now display the key of Linus Torvalds that you -have on your keyring:: - - $ gpg --list-key torvalds@kernel.org - pub rsa2048 2011-09-20 [SC] - ABAF11C65A2970B130ABE3C479BE3E4300411886 - uid [ unknown] Linus Torvalds <torvalds@kernel.org> - sub rsa2048 2011-09-20 [E] - -Next, find a trust path from Linus Torvalds to the key-id you found via ``gpg ---search`` of the unknown key. For this, you can use several tools including -https://github.com/mricon/wotmate, -https://git.kernel.org/pub/scm/docs/kernel/pgpkeys.git/tree/graphs, and -https://the.earth.li/~noodles/pathfind.html. - -If you get a few decent trust paths, then it's a pretty good indication -that it is a valid key. You can add it to your keyring from the -keyserver now:: - - $ gpg --recv-key C94035C21B4F2AEB - -This process is not perfect, and you are obviously trusting the -administrators of the PGP Pathfinder service to not be malicious (in -fact, this goes against :ref:`devs_not_infra`). However, if you -do not carefully maintain your own web of trust, then it is a marked -improvement over blindly trusting keyservers. +Using the kernel.org web of trust repository +-------------------------------------------- + +Kernel.org maintains a git repository with developers' public keys as a +replacement for replicating keyserver networks that have gone mostly +dark in the past few years. The full documentation for how to set up +that repository as your source of public keys can be found here: + +- `Kernel developer PGP Keyring`_ + +If you are a kernel developer, please consider submitting your key for +inclusion into that keyring. + +.. _`Kernel developer PGP Keyring`: https://korg.docs.kernel.org/pgpkeys.html diff --git a/Documentation/process/stable-kernel-rules.rst b/Documentation/process/stable-kernel-rules.rst index c61865e91f52..2fd8aa593a28 100644 --- a/Documentation/process/stable-kernel-rules.rst +++ b/Documentation/process/stable-kernel-rules.rst @@ -97,6 +97,12 @@ text, like this: commit <sha1> upstream. +or alternatively: + +.. code-block:: none + + [ Upstream commit <sha1> ] + Additionally, some patches submitted via :ref:`option_1` may have additional patch prerequisites which can be cherry-picked. This can be specified in the following format in the sign-off area: diff --git a/Documentation/process/submitting-patches.rst b/Documentation/process/submitting-patches.rst index be49d8f2601b..7dc94555417d 100644 --- a/Documentation/process/submitting-patches.rst +++ b/Documentation/process/submitting-patches.rst @@ -715,8 +715,8 @@ references. .. _backtraces: -Backtraces in commit mesages -^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +Backtraces in commit messages +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ Backtraces help document the call chain leading to a problem. However, not all backtraces are helpful. For example, early boot call chains are diff --git a/Documentation/rust/arch-support.rst b/Documentation/rust/arch-support.rst new file mode 100644 index 000000000000..6982b63775da --- /dev/null +++ b/Documentation/rust/arch-support.rst @@ -0,0 +1,19 @@ +.. SPDX-License-Identifier: GPL-2.0 + +Arch Support +============ + +Currently, the Rust compiler (``rustc``) uses LLVM for code generation, +which limits the supported architectures that can be targeted. In addition, +support for building the kernel with LLVM/Clang varies (please see +Documentation/kbuild/llvm.rst). This support is needed for ``bindgen`` +which uses ``libclang``. + +Below is a general summary of architectures that currently work. Level of +support corresponds to ``S`` values in the ``MAINTAINERS`` file. + +============ ================ ============================================== +Architecture Level of support Constraints +============ ================ ============================================== +``x86`` Maintained ``x86_64`` only. +============ ================ ============================================== diff --git a/Documentation/rust/coding-guidelines.rst b/Documentation/rust/coding-guidelines.rst new file mode 100644 index 000000000000..aa8ed082613e --- /dev/null +++ b/Documentation/rust/coding-guidelines.rst @@ -0,0 +1,216 @@ +.. SPDX-License-Identifier: GPL-2.0 + +Coding Guidelines +================= + +This document describes how to write Rust code in the kernel. + + +Style & formatting +------------------ + +The code should be formatted using ``rustfmt``. In this way, a person +contributing from time to time to the kernel does not need to learn and +remember one more style guide. More importantly, reviewers and maintainers +do not need to spend time pointing out style issues anymore, and thus +less patch roundtrips may be needed to land a change. + +.. note:: Conventions on comments and documentation are not checked by + ``rustfmt``. Thus those are still needed to be taken care of. + +The default settings of ``rustfmt`` are used. This means the idiomatic Rust +style is followed. For instance, 4 spaces are used for indentation rather +than tabs. + +It is convenient to instruct editors/IDEs to format while typing, +when saving or at commit time. However, if for some reason reformatting +the entire kernel Rust sources is needed at some point, the following can be +run:: + + make LLVM=1 rustfmt + +It is also possible to check if everything is formatted (printing a diff +otherwise), for instance for a CI, with:: + + make LLVM=1 rustfmtcheck + +Like ``clang-format`` for the rest of the kernel, ``rustfmt`` works on +individual files, and does not require a kernel configuration. Sometimes it may +even work with broken code. + + +Comments +-------- + +"Normal" comments (i.e. ``//``, rather than code documentation which starts +with ``///`` or ``//!``) are written in Markdown the same way as documentation +comments are, even though they will not be rendered. This improves consistency, +simplifies the rules and allows to move content between the two kinds of +comments more easily. For instance: + +.. code-block:: rust + + // `object` is ready to be handled now. + f(object); + +Furthermore, just like documentation, comments are capitalized at the beginning +of a sentence and ended with a period (even if it is a single sentence). This +includes ``// SAFETY:``, ``// TODO:`` and other "tagged" comments, e.g.: + +.. code-block:: rust + + // FIXME: The error should be handled properly. + +Comments should not be used for documentation purposes: comments are intended +for implementation details, not users. This distinction is useful even if the +reader of the source file is both an implementor and a user of an API. In fact, +sometimes it is useful to use both comments and documentation at the same time. +For instance, for a ``TODO`` list or to comment on the documentation itself. +For the latter case, comments can be inserted in the middle; that is, closer to +the line of documentation to be commented. For any other case, comments are +written after the documentation, e.g.: + +.. code-block:: rust + + /// Returns a new [`Foo`]. + /// + /// # Examples + /// + // TODO: Find a better example. + /// ``` + /// let foo = f(42); + /// ``` + // FIXME: Use fallible approach. + pub fn f(x: i32) -> Foo { + // ... + } + +One special kind of comments are the ``// SAFETY:`` comments. These must appear +before every ``unsafe`` block, and they explain why the code inside the block is +correct/sound, i.e. why it cannot trigger undefined behavior in any case, e.g.: + +.. code-block:: rust + + // SAFETY: `p` is valid by the safety requirements. + unsafe { *p = 0; } + +``// SAFETY:`` comments are not to be confused with the ``# Safety`` sections +in code documentation. ``# Safety`` sections specify the contract that callers +(for functions) or implementors (for traits) need to abide by. ``// SAFETY:`` +comments show why a call (for functions) or implementation (for traits) actually +respects the preconditions stated in a ``# Safety`` section or the language +reference. + + +Code documentation +------------------ + +Rust kernel code is not documented like C kernel code (i.e. via kernel-doc). +Instead, the usual system for documenting Rust code is used: the ``rustdoc`` +tool, which uses Markdown (a lightweight markup language). + +To learn Markdown, there are many guides available out there. For instance, +the one at: + + https://commonmark.org/help/ + +This is how a well-documented Rust function may look like: + +.. code-block:: rust + + /// Returns the contained [`Some`] value, consuming the `self` value, + /// without checking that the value is not [`None`]. + /// + /// # Safety + /// + /// Calling this method on [`None`] is *[undefined behavior]*. + /// + /// [undefined behavior]: https://doc.rust-lang.org/reference/behavior-considered-undefined.html + /// + /// # Examples + /// + /// ``` + /// let x = Some("air"); + /// assert_eq!(unsafe { x.unwrap_unchecked() }, "air"); + /// ``` + pub unsafe fn unwrap_unchecked(self) -> T { + match self { + Some(val) => val, + + // SAFETY: The safety contract must be upheld by the caller. + None => unsafe { hint::unreachable_unchecked() }, + } + } + +This example showcases a few ``rustdoc`` features and some conventions followed +in the kernel: + + - The first paragraph must be a single sentence briefly describing what + the documented item does. Further explanations must go in extra paragraphs. + + - Unsafe functions must document their safety preconditions under + a ``# Safety`` section. + + - While not shown here, if a function may panic, the conditions under which + that happens must be described under a ``# Panics`` section. + + Please note that panicking should be very rare and used only with a good + reason. In almost all cases, a fallible approach should be used, typically + returning a ``Result``. + + - If providing examples of usage would help readers, they must be written in + a section called ``# Examples``. + + - Rust items (functions, types, constants...) must be linked appropriately + (``rustdoc`` will create a link automatically). + + - Any ``unsafe`` block must be preceded by a ``// SAFETY:`` comment + describing why the code inside is sound. + + While sometimes the reason might look trivial and therefore unneeded, + writing these comments is not just a good way of documenting what has been + taken into account, but most importantly, it provides a way to know that + there are no *extra* implicit constraints. + +To learn more about how to write documentation for Rust and extra features, +please take a look at the ``rustdoc`` book at: + + https://doc.rust-lang.org/rustdoc/how-to-write-documentation.html + + +Naming +------ + +Rust kernel code follows the usual Rust naming conventions: + + https://rust-lang.github.io/api-guidelines/naming.html + +When existing C concepts (e.g. macros, functions, objects...) are wrapped into +a Rust abstraction, a name as close as reasonably possible to the C side should +be used in order to avoid confusion and to improve readability when switching +back and forth between the C and Rust sides. For instance, macros such as +``pr_info`` from C are named the same in the Rust side. + +Having said that, casing should be adjusted to follow the Rust naming +conventions, and namespacing introduced by modules and types should not be +repeated in the item names. For instance, when wrapping constants like: + +.. code-block:: c + + #define GPIO_LINE_DIRECTION_IN 0 + #define GPIO_LINE_DIRECTION_OUT 1 + +The equivalent in Rust may look like (ignoring documentation): + +.. code-block:: rust + + pub mod gpio { + pub enum LineDirection { + In = bindings::GPIO_LINE_DIRECTION_IN as _, + Out = bindings::GPIO_LINE_DIRECTION_OUT as _, + } + } + +That is, the equivalent of ``GPIO_LINE_DIRECTION_IN`` would be referred to as +``gpio::LineDirection::In``. In particular, it should not be named +``gpio::gpio_line_direction::GPIO_LINE_DIRECTION_IN``. diff --git a/Documentation/rust/general-information.rst b/Documentation/rust/general-information.rst new file mode 100644 index 000000000000..49029ee82e55 --- /dev/null +++ b/Documentation/rust/general-information.rst @@ -0,0 +1,79 @@ +.. SPDX-License-Identifier: GPL-2.0 + +General Information +=================== + +This document contains useful information to know when working with +the Rust support in the kernel. + + +Code documentation +------------------ + +Rust kernel code is documented using ``rustdoc``, its built-in documentation +generator. + +The generated HTML docs include integrated search, linked items (e.g. types, +functions, constants), source code, etc. They may be read at (TODO: link when +in mainline and generated alongside the rest of the documentation): + + http://kernel.org/ + +The docs can also be easily generated and read locally. This is quite fast +(same order as compiling the code itself) and no special tools or environment +are needed. This has the added advantage that they will be tailored to +the particular kernel configuration used. To generate them, use the ``rustdoc`` +target with the same invocation used for compilation, e.g.:: + + make LLVM=1 rustdoc + +To read the docs locally in your web browser, run e.g.:: + + xdg-open rust/doc/kernel/index.html + +To learn about how to write the documentation, please see coding-guidelines.rst. + + +Extra lints +----------- + +While ``rustc`` is a very helpful compiler, some extra lints and analyses are +available via ``clippy``, a Rust linter. To enable it, pass ``CLIPPY=1`` to +the same invocation used for compilation, e.g.:: + + make LLVM=1 CLIPPY=1 + +Please note that Clippy may change code generation, thus it should not be +enabled while building a production kernel. + + +Abstractions vs. bindings +------------------------- + +Abstractions are Rust code wrapping kernel functionality from the C side. + +In order to use functions and types from the C side, bindings are created. +Bindings are the declarations for Rust of those functions and types from +the C side. + +For instance, one may write a ``Mutex`` abstraction in Rust which wraps +a ``struct mutex`` from the C side and calls its functions through the bindings. + +Abstractions are not available for all the kernel internal APIs and concepts, +but it is intended that coverage is expanded as time goes on. "Leaf" modules +(e.g. drivers) should not use the C bindings directly. Instead, subsystems +should provide as-safe-as-possible abstractions as needed. + + +Conditional compilation +----------------------- + +Rust code has access to conditional compilation based on the kernel +configuration: + +.. code-block:: rust + + #[cfg(CONFIG_X)] // Enabled (`y` or `m`) + #[cfg(CONFIG_X="y")] // Enabled as a built-in (`y`) + #[cfg(CONFIG_X="m")] // Enabled as a module (`m`) + #[cfg(not(CONFIG_X))] // Disabled diff --git a/Documentation/rust/index.rst b/Documentation/rust/index.rst new file mode 100644 index 000000000000..4ae8c66b94fa --- /dev/null +++ b/Documentation/rust/index.rst @@ -0,0 +1,22 @@ +.. SPDX-License-Identifier: GPL-2.0 + +Rust +==== + +Documentation related to Rust within the kernel. To start using Rust +in the kernel, please read the quick-start.rst guide. + +.. toctree:: + :maxdepth: 1 + + quick-start + general-information + coding-guidelines + arch-support + +.. only:: subproject and html + + Indices + ======= + + * :ref:`genindex` diff --git a/Documentation/rust/quick-start.rst b/Documentation/rust/quick-start.rst new file mode 100644 index 000000000000..13b7744b1e27 --- /dev/null +++ b/Documentation/rust/quick-start.rst @@ -0,0 +1,232 @@ +.. SPDX-License-Identifier: GPL-2.0 + +Quick Start +=========== + +This document describes how to get started with kernel development in Rust. + + +Requirements: Building +---------------------- + +This section explains how to fetch the tools needed for building. + +Some of these requirements might be available from Linux distributions +under names like ``rustc``, ``rust-src``, ``rust-bindgen``, etc. However, +at the time of writing, they are likely not to be recent enough unless +the distribution tracks the latest releases. + +To easily check whether the requirements are met, the following target +can be used:: + + make LLVM=1 rustavailable + +This triggers the same logic used by Kconfig to determine whether +``RUST_IS_AVAILABLE`` should be enabled; but it also explains why not +if that is the case. + + +rustc +***** + +A particular version of the Rust compiler is required. Newer versions may or +may not work because, for the moment, the kernel depends on some unstable +Rust features. + +If ``rustup`` is being used, enter the checked out source code directory +and run:: + + rustup override set $(scripts/min-tool-version.sh rustc) + +Otherwise, fetch a standalone installer or install ``rustup`` from: + + https://www.rust-lang.org + + +Rust standard library source +**************************** + +The Rust standard library source is required because the build system will +cross-compile ``core`` and ``alloc``. + +If ``rustup`` is being used, run:: + + rustup component add rust-src + +The components are installed per toolchain, thus upgrading the Rust compiler +version later on requires re-adding the component. + +Otherwise, if a standalone installer is used, the Rust repository may be cloned +into the installation folder of the toolchain:: + + git clone --recurse-submodules \ + --branch $(scripts/min-tool-version.sh rustc) \ + https://github.com/rust-lang/rust \ + $(rustc --print sysroot)/lib/rustlib/src/rust + +In this case, upgrading the Rust compiler version later on requires manually +updating this clone. + + +libclang +******** + +``libclang`` (part of LLVM) is used by ``bindgen`` to understand the C code +in the kernel, which means LLVM needs to be installed; like when the kernel +is compiled with ``CC=clang`` or ``LLVM=1``. + +Linux distributions are likely to have a suitable one available, so it is +best to check that first. + +There are also some binaries for several systems and architectures uploaded at: + + https://releases.llvm.org/download.html + +Otherwise, building LLVM takes quite a while, but it is not a complex process: + + https://llvm.org/docs/GettingStarted.html#getting-the-source-code-and-building-llvm + +Please see Documentation/kbuild/llvm.rst for more information and further ways +to fetch pre-built releases and distribution packages. + + +bindgen +******* + +The bindings to the C side of the kernel are generated at build time using +the ``bindgen`` tool. A particular version is required. + +Install it via (note that this will download and build the tool from source):: + + cargo install --locked --version $(scripts/min-tool-version.sh bindgen) bindgen + + +Requirements: Developing +------------------------ + +This section explains how to fetch the tools needed for developing. That is, +they are not needed when just building the kernel. + + +rustfmt +******* + +The ``rustfmt`` tool is used to automatically format all the Rust kernel code, +including the generated C bindings (for details, please see +coding-guidelines.rst). + +If ``rustup`` is being used, its ``default`` profile already installs the tool, +thus nothing needs to be done. If another profile is being used, the component +can be installed manually:: + + rustup component add rustfmt + +The standalone installers also come with ``rustfmt``. + + +clippy +****** + +``clippy`` is a Rust linter. Running it provides extra warnings for Rust code. +It can be run by passing ``CLIPPY=1`` to ``make`` (for details, please see +general-information.rst). + +If ``rustup`` is being used, its ``default`` profile already installs the tool, +thus nothing needs to be done. If another profile is being used, the component +can be installed manually:: + + rustup component add clippy + +The standalone installers also come with ``clippy``. + + +cargo +***** + +``cargo`` is the Rust native build system. It is currently required to run +the tests since it is used to build a custom standard library that contains +the facilities provided by the custom ``alloc`` in the kernel. The tests can +be run using the ``rusttest`` Make target. + +If ``rustup`` is being used, all the profiles already install the tool, +thus nothing needs to be done. + +The standalone installers also come with ``cargo``. + + +rustdoc +******* + +``rustdoc`` is the documentation tool for Rust. It generates pretty HTML +documentation for Rust code (for details, please see +general-information.rst). + +``rustdoc`` is also used to test the examples provided in documented Rust code +(called doctests or documentation tests). The ``rusttest`` Make target uses +this feature. + +If ``rustup`` is being used, all the profiles already install the tool, +thus nothing needs to be done. + +The standalone installers also come with ``rustdoc``. + + +rust-analyzer +************* + +The `rust-analyzer <https://rust-analyzer.github.io/>`_ language server can +be used with many editors to enable syntax highlighting, completion, go to +definition, and other features. + +``rust-analyzer`` needs a configuration file, ``rust-project.json``, which +can be generated by the ``rust-analyzer`` Make target. + + +Configuration +------------- + +``Rust support`` (``CONFIG_RUST``) needs to be enabled in the ``General setup`` +menu. The option is only shown if a suitable Rust toolchain is found (see +above), as long as the other requirements are met. In turn, this will make +visible the rest of options that depend on Rust. + +Afterwards, go to:: + + Kernel hacking + -> Sample kernel code + -> Rust samples + +And enable some sample modules either as built-in or as loadable. + + +Building +-------- + +Building a kernel with a complete LLVM toolchain is the best supported setup +at the moment. That is:: + + make LLVM=1 + +For architectures that do not support a full LLVM toolchain, use:: + + make CC=clang + +Using GCC also works for some configurations, but it is very experimental at +the moment. + + +Hacking +------- + +To dive deeper, take a look at the source code of the samples +at ``samples/rust/``, the Rust support code under ``rust/`` and +the ``Rust hacking`` menu under ``Kernel hacking``. + +If GDB/Binutils is used and Rust symbols are not getting demangled, the reason +is the toolchain does not support Rust's new v0 mangling scheme yet. +There are a few ways out: + + - Install a newer release (GDB >= 10.2, Binutils >= 2.36). + + - Some versions of GDB (e.g. vanilla GDB 10.1) are able to use + the pre-demangled names embedded in the debug info (``CONFIG_DEBUG_INFO``). diff --git a/Documentation/scheduler/sched-design-CFS.rst b/Documentation/scheduler/sched-design-CFS.rst index 59b2d1fb4dc4..03db55504515 100644 --- a/Documentation/scheduler/sched-design-CFS.rst +++ b/Documentation/scheduler/sched-design-CFS.rst @@ -94,7 +94,7 @@ other HZ detail. Thus the CFS scheduler has no notion of "timeslices" in the way the previous scheduler had, and has no heuristics whatsoever. There is only one central tunable (you have to switch on CONFIG_SCHED_DEBUG): - /proc/sys/kernel/sched_min_granularity_ns + /sys/kernel/debug/sched/min_granularity_ns which can be used to tune the scheduler from "desktop" (i.e., low latencies) to "server" (i.e., good batching) workloads. It defaults to a setting suitable diff --git a/Documentation/security/landlock.rst b/Documentation/security/landlock.rst index 5c77730b4479..c0029d5d02eb 100644 --- a/Documentation/security/landlock.rst +++ b/Documentation/security/landlock.rst @@ -7,7 +7,7 @@ Landlock LSM: kernel documentation ================================== :Author: Mickaël Salaün -:Date: May 2022 +:Date: September 2022 Landlock's goal is to create scoped access-control (i.e. sandboxing). To harden a whole system, this feature should be available to any process, @@ -49,13 +49,13 @@ Filesystem access rights ------------------------ All access rights are tied to an inode and what can be accessed through it. -Reading the content of a directory doesn't imply to be allowed to read the +Reading the content of a directory does not imply to be allowed to read the content of a listed inode. Indeed, a file name is local to its parent directory, and an inode can be referenced by multiple file names thanks to (hard) links. Being able to unlink a file only has a direct impact on the directory, not the unlinked inode. This is the reason why -`LANDLOCK_ACCESS_FS_REMOVE_FILE` or `LANDLOCK_ACCESS_FS_REFER` are not allowed -to be tied to files but only to directories. +``LANDLOCK_ACCESS_FS_REMOVE_FILE`` or ``LANDLOCK_ACCESS_FS_REFER`` are not +allowed to be tied to files but only to directories. Tests ===== diff --git a/Documentation/sound/kernel-api/writing-an-alsa-driver.rst b/Documentation/sound/kernel-api/writing-an-alsa-driver.rst index 176b73583b7a..07a620c5ca74 100644 --- a/Documentation/sound/kernel-api/writing-an-alsa-driver.rst +++ b/Documentation/sound/kernel-api/writing-an-alsa-driver.rst @@ -3565,13 +3565,17 @@ given size. The second argument (type) and the third argument (device pointer) are dependent on the bus. For normal devices, pass the device pointer (typically identical as ``card->dev``) to the third argument with -``SNDRV_DMA_TYPE_DEV`` type. For the continuous buffer unrelated to the +``SNDRV_DMA_TYPE_DEV`` type. + +For the continuous buffer unrelated to the bus can be pre-allocated with ``SNDRV_DMA_TYPE_CONTINUOUS`` type. You can pass NULL to the device pointer in that case, which is the default mode implying to allocate with ``GFP_KERNEL`` flag. -If you need a different GFP flag, you can pass it by encoding the flag -into the device pointer via a special macro -:c:func:`snd_dma_continuous_data()`. +If you need a restricted (lower) address, set up the coherent DMA mask +bits for the device, and pass the device pointer, like the normal +device memory allocations. For this type, it's still allowed to pass +NULL to the device pointer, too, if no address restriction is needed. + For the scatter-gather buffers, use ``SNDRV_DMA_TYPE_DEV_SG`` with the device pointer (see the `Non-Contiguous Buffers`_ section). @@ -3811,15 +3815,6 @@ arguments here. Since each vmalloc call should succeed at any time, we don't need to pre-allocate the buffers like other continuous pages. -If you need the 32bit DMA allocation, pass the device pointer encoded -by :c:func:`snd_dma_continuous_data()` with ``GFP_KERNEL|__GFP_DMA32`` -argument. - -:: - - snd_pcm_set_managed_buffer_all(pcm, SNDRV_DMA_TYPE_VMALLOC, - snd_dma_continuous_data(GFP_KERNEL | __GFP_DMA32), 0, 0); - Proc Interface ============== diff --git a/Documentation/sphinx/kerneldoc-preamble.sty b/Documentation/sphinx/kerneldoc-preamble.sty index 2a29cbe51396..9707e033c8c4 100644 --- a/Documentation/sphinx/kerneldoc-preamble.sty +++ b/Documentation/sphinx/kerneldoc-preamble.sty @@ -70,8 +70,16 @@ % Translations have Asian (CJK) characters which are only displayed if % xeCJK is used +\usepackage{ifthen} +\newboolean{enablecjk} +\setboolean{enablecjk}{false} \IfFontExistsTF{Noto Sans CJK SC}{ - % Load xeCJK when CJK font is available + \IfFileExists{xeCJK.sty}{ + \setboolean{enablecjk}{true} + }{} +}{} +\ifthenelse{\boolean{enablecjk}}{ + % Load xeCJK when both the Noto Sans CJK font and xeCJK.sty are available. \usepackage{xeCJK} % Noto CJK fonts don't provide slant shape. [AutoFakeSlant] permits % its emulation. @@ -196,7 +204,7 @@ % Inactivate CJK after tableofcontents \apptocmd{\sphinxtableofcontents}{\kerneldocCJKoff}{}{} \xeCJKsetup{CJKspace = true}% For inter-phrase space of Korean TOC -}{ % No CJK font found +}{ % Don't enable CJK % Custom macros to on/off CJK and switch CJK fonts (Dummy) \newcommand{\kerneldocCJKon}{} \newcommand{\kerneldocCJKoff}{} @@ -204,14 +212,16 @@ %% and ignore the argument (#1) in their definitions, whole contents of %% CJK chapters can be ignored. \newcommand{\kerneldocBeginSC}[1]{% - %% Put a note on missing CJK fonts in place of zh_CN translation. - \begin{sphinxadmonition}{note}{Note on missing fonts:} + %% Put a note on missing CJK fonts or the xecjk package in place of + %% zh_CN translation. + \begin{sphinxadmonition}{note}{Note on missing fonts and a package:} Translations of Simplified Chinese (zh\_CN), Traditional Chinese (zh\_TW), Korean (ko\_KR), and Japanese (ja\_JP) were skipped - due to the lack of suitable font families. + due to the lack of suitable font families and/or the texlive-xecjk + package. If you want them, please install ``Noto Sans CJK'' font families - by following instructions from + along with the texlive-xecjk package by following instructions from \sphinxcode{./scripts/sphinx-pre-install}. Having optional ``Noto Serif CJK'' font families will improve the looks of those translations. diff --git a/Documentation/staging/index.rst b/Documentation/staging/index.rst index abd0d18254d2..ded8254bc0d7 100644 --- a/Documentation/staging/index.rst +++ b/Documentation/staging/index.rst @@ -14,45 +14,3 @@ Unsorted Documentation static-keys tee xz - -Atomic Types -============ - -.. raw:: latex - - \footnotesize - -.. include:: ../atomic_t.txt - :literal: - -.. raw:: latex - - \normalsize - -Atomic bitops -============= - -.. raw:: latex - - \footnotesize - -.. include:: ../atomic_bitops.txt - :literal: - -.. raw:: latex - - \normalsize - -Memory Barriers -=============== - -.. raw:: latex - - \footnotesize - -.. include:: ../memory-barriers.txt - :literal: - -.. raw:: latex - - \normalsize diff --git a/Documentation/subsystem-apis.rst b/Documentation/subsystem-apis.rst new file mode 100644 index 000000000000..af65004a80aa --- /dev/null +++ b/Documentation/subsystem-apis.rst @@ -0,0 +1,58 @@ +.. SPDX-License-Identifier: GPL-2.0 + +============================== +Kernel subsystem documentation +============================== + +These books get into the details of how specific kernel subsystems work +from the point of view of a kernel developer. Much of the information here +is taken directly from the kernel source, with supplemental material added +as needed (or at least as we managed to add it — probably *not* all that is +needed). + +**Fixme**: much more organizational work is needed here. + +.. toctree:: + :maxdepth: 1 + + driver-api/index + core-api/index + locking/index + accounting/index + block/index + cdrom/index + cpu-freq/index + fb/index + fpga/index + hid/index + i2c/index + iio/index + isdn/index + infiniband/index + leds/index + netlabel/index + networking/index + pcmcia/index + power/index + target/index + timers/index + spi/index + w1/index + watchdog/index + virt/index + input/index + hwmon/index + gpu/index + security/index + sound/index + crypto/index + filesystems/index + mm/index + bpf/index + usb/index + PCI/index + scsi/index + misc-devices/index + scheduler/index + mhi/index + peci/index diff --git a/Documentation/trace/histogram.rst b/Documentation/trace/histogram.rst index 859fd1b76c63..c1b685a38f6b 100644 --- a/Documentation/trace/histogram.rst +++ b/Documentation/trace/histogram.rst @@ -412,7 +412,7 @@ Extended error information Because the default sort key above is 'hitcount', the above shows a the list of call_sites by increasing hitcount, so that at the bottom we see the functions that made the most kmalloc calls during the - run. If instead we we wanted to see the top kmalloc callers in + run. If instead we wanted to see the top kmalloc callers in terms of the number of bytes requested rather than the number of calls, and we wanted the top caller to appear at the top, we can use the 'sort' parameter, along with the 'descending' modifier:: diff --git a/Documentation/trace/kprobes.rst b/Documentation/trace/kprobes.rst index f318bceda1e6..48cf778a2468 100644 --- a/Documentation/trace/kprobes.rst +++ b/Documentation/trace/kprobes.rst @@ -328,8 +328,8 @@ Configuring Kprobes =================== When configuring the kernel using make menuconfig/xconfig/oldconfig, -ensure that CONFIG_KPROBES is set to "y". Under "General setup", look -for "Kprobes". +ensure that CONFIG_KPROBES is set to "y", look for "Kprobes" under +"General architecture-dependent options". So that you can load and unload Kprobes-based instrumentation modules, make sure "Loadable module support" (CONFIG_MODULES) and "Module diff --git a/Documentation/trace/timerlat-tracer.rst b/Documentation/trace/timerlat-tracer.rst index d643c95c01eb..db17df312bc8 100644 --- a/Documentation/trace/timerlat-tracer.rst +++ b/Documentation/trace/timerlat-tracer.rst @@ -20,7 +20,7 @@ For example:: [root@f32 ~]# cd /sys/kernel/tracing/ [root@f32 tracing]# echo timerlat > current_tracer -It is possible to follow the trace by reading the trace trace file:: +It is possible to follow the trace by reading the trace file:: [root@f32 tracing]# cat trace # tracer: timerlat diff --git a/Documentation/translations/ja_JP/SubmittingPatches b/Documentation/translations/ja_JP/SubmittingPatches index 66ce0d8b0526..04deb77b20c6 100644 --- a/Documentation/translations/ja_JP/SubmittingPatches +++ b/Documentation/translations/ja_JP/SubmittingPatches @@ -35,8 +35,7 @@ Linux カーãƒãƒ«ã«å¤‰æ›´ã‚’åŠ ãˆãŸã„ã¨æ€ã£ã¦ã„る個人åˆã¯ä¼šç¤¾ã ã¦ã‚‚らãˆã‚„ã™ãã™ã‚‹æ案を集ã‚ãŸã‚‚ã®ã§ã™ã€‚ コードを投稿ã™ã‚‹å‰ã«ã€Documentation/process/submit-checklist.rst ã®é …目リストã«ç›® -を通ã—ã¦ãƒã‚§ãƒƒã‚¯ã—ã¦ãã ã•ã„。もã—ã‚ãªãŸãŒãƒ‰ãƒ©ã‚¤ãƒãƒ¼ã‚’投稿ã—よã†ã¨ã— -ã¦ã„ã‚‹ãªã‚‰ã€Documentation/process/submitting-drivers.rst ã«ã‚‚目を通ã—ã¦ãã ã•ã„。 +を通ã—ã¦ãƒã‚§ãƒƒã‚¯ã—ã¦ãã ã•ã„。 -------------------------------------------- セクション1 パッãƒã®ä½œã‚Šæ–¹ã¨é€ã‚Šæ–¹ diff --git a/Documentation/translations/zh_CN/IRQ.txt b/Documentation/translations/zh_CN/IRQ.txt deleted file mode 100644 index 9aec8dca4fcf..000000000000 --- a/Documentation/translations/zh_CN/IRQ.txt +++ /dev/null @@ -1,39 +0,0 @@ -Chinese translated version of Documentation/core-api/irq/index.rst - -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. - -Maintainer: Eric W. Biederman <ebiederman@xmission.com> -Chinese maintainer: Fu Wei <tekkamanninja@gmail.com> ---------------------------------------------------------------------- -Documentation/core-api/irq/index.rst çš„ä¸æ–‡ç¿»è¯‘ - -如果想评论或更新本文的内容，请直接è”ç³»åŽŸæ–‡æ¡£çš„ç»´æŠ¤è€…ã€‚å¦‚æžœä½ ä½¿ç”¨è‹±æ–‡ -交æµæœ‰å›°éš¾çš„è¯ï¼Œä¹Ÿå¯ä»¥å‘ä¸æ–‡ç‰ˆç»´æŠ¤è€…求助。如果本翻译更新ä¸åŠæ—¶æˆ–者翻 -译å˜åœ¨é—®é¢˜ï¼Œè¯·è”ç³»ä¸æ–‡ç‰ˆç»´æŠ¤è€…。 -英文版维护者： Eric W. Biederman <ebiederman@xmission.com> -ä¸æ–‡ç‰ˆç»´æŠ¤è€…： å‚…ç‚œ Fu Wei <tekkamanninja@gmail.com> -ä¸æ–‡ç‰ˆç¿»è¯‘者： å‚…ç‚œ Fu Wei <tekkamanninja@gmail.com> -ä¸æ–‡ç‰ˆæ ¡è¯‘者： å‚…ç‚œ Fu Wei <tekkamanninja@gmail.com> - - -以下为æ£æ–‡ ---------------------------------------------------------------------- -何为 IRQ? - -一个 IRQ 是æ¥è‡ªæŸä¸ªè®¾å¤‡çš„一个ä¸æ–请求。目å‰ï¼Œå®ƒä»¬å¯ä»¥æ¥è‡ªä¸€ä¸ªç¡¬ä»¶å¼•è„šï¼Œ -或æ¥è‡ªä¸€ä¸ªæ•°æ®åŒ…。多个设备å¯èƒ½è¿žæŽ¥åˆ°åŒä¸ªç¡¬ä»¶å¼•è„šï¼Œä»Žè€Œå…±äº«ä¸€ä¸ª IRQ。 - -一个 IRQ ç¼–å·æ˜¯ç”¨äºŽå‘ŠçŸ¥ç¡¬ä»¶ä¸æ–æºçš„å†…æ ¸æ ‡è¯†ã€‚é€šå¸¸æƒ…å†µä¸‹ï¼Œè¿™æ˜¯ä¸€ä¸ª -全局 irq_desc 数组的索引，但是除了在 linux/interrupt.h ä¸çš„实现， -具体的细节是体系结构特定的。 - -一个 IRQ ç¼–å·æ˜¯è®¾å¤‡ä¸ŠæŸä¸ªå¯èƒ½çš„ä¸æ–æºçš„枚举。通常情况下，枚举的编å·æ˜¯ -该引脚在系统内ä¸æ–控制器的所有输入引脚ä¸çš„ç¼–å·ã€‚对于 ISA 总线ä¸çš„情况， -枚举的是在两个 i8259 ä¸æ–æŽ§åˆ¶å™¨ä¸ 16 个输入引脚。 - -架构å¯ä»¥å¯¹ IRQ ç¼–å·æŒ‡å®šé¢å¤–çš„å«ä¹‰ï¼Œåœ¨ç¡¬ä»¶æ¶‰åŠä»»ä½•æ‰‹å·¥é…置的情况下， -是被æ倡的。ISA çš„ IRQ 是一个分é…这类é¢å¤–å«ä¹‰çš„典型例å。 diff --git a/Documentation/translations/zh_CN/PCI/acpi-info.rst b/Documentation/translations/zh_CN/PCI/acpi-info.rst new file mode 100644 index 000000000000..a35f39dcd858 --- /dev/null +++ b/Documentation/translations/zh_CN/PCI/acpi-info.rst @@ -0,0 +1,139 @@ +.. SPDX-License-Identifier: GPL-2.0 +.. include:: ../disclaimer-zh_CN.rst + +:Original: Documentation/PCI/acpi-info.rst + +:翻译: + + å¸å»¶è…¾ Yanteng Si <siyanteng@loongson.cn> + +:æ ¡è¯‘: + + +===================== +PCI主桥的ACPI注æ„事项 +===================== + +一般的规则是，ACPI命å空间应该æè¿°æ“作系统å¯èƒ½ä½¿ç”¨çš„所有东西，除éžæœ‰å…¶ä»–方法让æ“作系 +统找到它[1, 2]。 + +ä¾‹å¦‚ï¼Œæ²¡æœ‰æ ‡å‡†çš„ç¡¬ä»¶æœºåˆ¶æ¥æžšä¸¾PCI主桥，所以ACPI命å空间必须æè¿°æ¯ä¸ªä¸»æ¡¥ã€è®¿é—®å®ƒ +下é¢çš„PCIé…置空间的方法ã€ä¸»æ¡¥è½¬å‘到PCI的地å€ç©ºé—´çª—å£ï¼ˆä½¿ç”¨_CRS）以åŠä¼ 统的INTx +ä¸æ–的路由（使用_PRT）。 + +在主桥下é¢çš„PCI设备，通常ä¸éœ€è¦é€šè¿‡ACPIæ述。æ“作系统å¯ä»¥é€šè¿‡æ ‡å‡†çš„PCIæžšä¸¾æœºåˆ¶æ¥ +å‘现它们，使用é…置访问æ¥å‘现和识别设备，并读å–和测é‡å®ƒä»¬çš„BAR。然而，如果ACPI为它们 +æ供电æºç®¡ç†æˆ–çƒæ’拔功能，或者如果设备有由平å°ä¸æ–控制器连接的INTxä¸æ–，需è¦ä¸€ä¸ª_PRT +æ¥æ述这些连接，这ç§æƒ…况下ACPIå¯ä»¥æè¿°PCI设备。 + +ACPI资æºæ述是通过ACPI命å空间ä¸è®¾å¤‡çš„_CRS对象完æˆçš„[2]。_CRSå°±åƒä¸€ä¸ªé€šç”¨çš„PCI BAR： +æ“作系统å¯ä»¥è¯»å–_CRS并找出æ£åœ¨æ¶ˆè€—的资æºï¼Œå³ä½¿å®ƒæ²¡æœ‰è¯¥è®¾å¤‡çš„驱动程åº[3]。这一点很é‡è¦ï¼Œ +å› ä¸ºå®ƒæ„味ç€ä¸€ä¸ªæ—§çš„æ“作系统å¯ä»¥æ£ç¡®åœ°å·¥ä½œï¼Œå³ä½¿æ˜¯åœ¨æ“作系统ä¸çŸ¥é“的新设备的系统上。新设 +备å¯èƒ½ä»€ä¹ˆéƒ½ä¸åšï¼Œä½†æ“作系统至少å¯ä»¥ç¡®ä¿æ²¡æœ‰èµ„æºä¸Žå®ƒä»¬å†²çªã€‚ + +åƒMCFGã€HPETã€ECDTç‰é™æ€è¡¨ï¼Œä¸æ˜¯ä¿ç•™åœ°å€ç©ºé—´çš„机制。é™æ€è¡¨æ˜¯åœ¨æ“作系统在å¯åŠ¨åˆæœŸä¸”在它 +能够解æžACPI命å空间之å‰éœ€è¦çŸ¥é“的东西。如果定义了一个新的表，å³ä½¿æ—§çš„æ“作系统忽略了这 +个表，它也需è¦æ£å¸¸è¿è¡Œã€‚_CRSå…è®¸è¿™æ ·åšï¼Œå› 为它是通用的，å¯ä»¥è¢«æ—§çš„æ“作系统解æžï¼›è€Œé™æ€è¡¨ +则ä¸å…许。 + +如果æ“作系统è¦ç®¡ç†ä¸€ä¸ªé€šè¿‡ACPIæè¿°çš„ä¸å¯å‘现的设备，该设备将有一个特定的_HID/_CID，以 +告诉æ“作系统与之绑定的驱动程åºï¼Œå¹¶ä¸”_CRS告诉æ“作系统和驱动程åºè¯¥è®¾å¤‡çš„寄å˜å™¨åœ¨å“ªé‡Œã€‚ + +PCI主桥是PNP0A03或PNP0A08设备。它们的_CRS应该æ述它们所消耗的所有地å€ç©ºé—´ã€‚这包括它 +们转å‘到PCI总线上的所有窗å£ï¼Œä»¥åŠä¸è½¬å‘到PCI的主桥本身的寄å˜å™¨ã€‚主桥的寄å˜å™¨åŒ…括次è¦/下 +级总线寄å˜å™¨ï¼Œå†³å®šäº†æ¡¥ä¸‹é¢çš„总线范围，窗å£å¯„å˜å™¨æ述了桥洞，ç‰ç‰ã€‚è¿™äº›éƒ½æ˜¯è®¾å¤‡ç›¸å…³çš„ï¼Œéž +架构相关的东西，所以PNP0A03/PNP0A08驱动å¯ä»¥ç®¡ç†å®ƒä»¬çš„唯一方法是通过_PRS/_CRS/_SRS， +它包å«äº†ç‰¹å®šäºŽè®¾å¤‡çš„细节。主桥寄å˜å™¨ä¹ŸåŒ…括ECAMç©ºé—´ï¼Œå› ä¸ºå®ƒæ˜¯ç”±ä¸»æ¡¥æ¶ˆè€—çš„ã€‚ + +ACPI定义了一个Consumer/Producerä½æ¥åŒºåˆ†æ¡¥å¯„å˜å™¨ï¼ˆâ€œConsumerâ€ä¸‹æ–‡è¯‘作消费者）和 +桥洞（“Producerâ€ä¸‹æ–‡è¯‘作生产者）[4, 5]，但是早期的BIOS没有æ£ç¡®ä½¿ç”¨è¿™ä¸ªä½ã€‚其结果 +是，目å‰çš„ACPI规范åªä¸ºæ‰©å±•åœ°å€ç©ºé—´æ述符定义了消费者/生产者；在旧的QWord/Word/Word地 +å€ç©ºé—´æ述符ä¸ï¼Œè¯¥ä½åº”è¯¥è¢«å¿½ç•¥ã€‚å› æ¤ï¼Œæ“作系统必须å‡å®šæ‰€æœ‰çš„QWord/Word/Wordæ述符都是 +窗å£ã€‚ + +åœ¨å¢žåŠ æ‰©å±•åœ°å€ç©ºé—´æ述符之å‰ï¼Œæ¶ˆè´¹è€…/生产者的失败æ„味ç€æ²¡æœ‰åŠžæ³•æè¿°PNP0A03/PNP0A08设 +备本身的桥寄å˜å™¨ã€‚解决办法是在PNP0C02æ•æ‰å™¨ä¸æ述桥寄å˜å™¨ï¼ˆåŒ…括ECAM空间）[6]。 +除了ECAM之外，桥寄å˜å™¨ç©ºé—´åæ£æ˜¯ç‰¹å®šäºŽè®¾å¤‡çš„，所以通用的PNP0A03/PNP0A08驱动程 +åº(pci_root.c)没有必è¦äº†è§£å®ƒã€‚ + +新的架构应该能够在PNP0A03设备ä¸ä½¿ç”¨â€œæ¶ˆè´¹è€…â€æ‰©å±•åœ°å€ç©ºé—´æ述符，用于桥寄å˜å™¨ï¼ŒåŒ…括 +ECAM，尽管对[6]çš„ä¸¥æ ¼è§£é‡Šå¯èƒ½ç¦æ¢è¿™æ ·åšã€‚旧的x86å’Œia64å†…æ ¸å‡å®šæ‰€æœ‰çš„地å€ç©ºé—´æè¿° +符，包括“消费者â€æ‰©å±•åœ°å€ç©ºé—´çš„æ述符，都是窗å£ï¼Œæ‰€ä»¥åœ¨è¿™äº›æž¶æž„上以这ç§æ–¹å¼æ述桥寄 +å˜å™¨æ˜¯ä¸å®‰å…¨çš„。 + +PNP0C02“主æ¿â€è®¾å¤‡åŸºæœ¬ä¸Šæ˜¯ä¸‡èƒ½çš„。除了“ä¸è¦å°†è¿™äº›èµ„æºç”¨äºŽå…¶ä»–用途â€ä¹‹å¤–，没有其他的编 +ç¨‹æ¨¡åž‹ã€‚å› æ¤ï¼ŒPNP0C02 _CRS应该声明ACPI命å空间ä¸(1)没有被_CRS声明的任何其他设备对 +象的地å€ç©ºé—´ï¼Œ(2)ä¸åº”该被OS分é…给其他东西。 + +除éžæœ‰ä¸€ä¸ªæ ‡å‡†çš„固件接å£ç”¨äºŽé…置访问，例如ia64 SAL接å£[7]，å¦åˆ™PCIe规范è¦æ±‚使用增强 +åž‹é…置访问方法（ECAM）。主桥消耗ECAM内å˜åœ°å€ç©ºé—´å¹¶å°†å†…å˜è®¿é—®è½¬æ¢ä¸ºPCIé…置访问。该规范 +定义了ECAM地å€ç©ºé—´çš„布局和功能；åªæœ‰åœ°å€ç©ºé—´çš„基础是特定于设备的。ACPIæ“作系统从é™æ€ +MCFG表或PNP0A03设备ä¸çš„_CBA方法ä¸äº†è§£åŸºç¡€åœ°å€ã€‚ + +MCFG表必须æè¿°éžçƒæ’拔主桥的ECAM空间[8]。由于MCFG是一个é™æ€è¡¨ï¼Œä¸èƒ½é€šè¿‡çƒæ’拔更新， +PNP0A03设备ä¸çš„_CBA方法æ述了å¯çƒæ’拔主桥的ECAM空间[9]。请注æ„，对于MCFGå’Œ_CBA， +基å€æ€»æ˜¯å¯¹åº”于总线0，å³ä½¿æ¡¥å™¨ä¸‹é¢çš„总线范围（通过_CRS报告）ä¸ä»Ž0开始。 + + +[1] ACPI 6.2, sec 6.1: + 对于任何在éžæžšä¸¾ç±»åž‹çš„总线上的设备（例如，ISA总线），OSPMä¼šæžšä¸¾è®¾å¤‡çš„æ ‡è¯†ç¬¦ï¼ŒACPI + 系统固件必须为æ¯ä¸ªè®¾å¤‡æ供一个_HID对象...以使OSPM能够åšåˆ°è¿™ä¸€ç‚¹ã€‚ + +[2] ACPI 6.2, sec 3.7: + æ“作系统枚举主æ¿è®¾å¤‡æ—¶ï¼Œåªéœ€é€šè¿‡è¯»å–ACPI命å空间æ¥å¯»æ‰¾å…·æœ‰ç¡¬ä»¶ID的设备。 + + ACPI枚举的æ¯ä¸ªè®¾å¤‡éƒ½åŒ…括ACPI命å空间ä¸ACPI定义的对象，该对象报告设备å¯èƒ½å 用的硬 + 件资æº[_PRS]，报告设备当å‰ä½¿ç”¨çš„资æº[_CRS]的对象，以åŠé…置这些资æºçš„对象[_SRS]。 + 这些信æ¯è¢«å³æ’å³ç”¨æ“作系统（OSPM）用æ¥é…置设备。 + +[3] ACPI 6.2, sec 6.2: + OSPM使用设备é…置对象æ¥é…置通过ACPI列举的设备的硬件资æºã€‚设备é…置对象æä¾›äº†å…³äºŽå½“å‰ + å’Œå¯èƒ½çš„资æºéœ€æ±‚çš„ä¿¡æ¯ï¼Œå…±äº«èµ„æºä¹‹é—´çš„关系，以åŠé…置硬件资æºçš„方法。 + + 当OSPM枚举一个设备时，它调用_PRSæ¥ç¡®å®šè¯¥è®¾å¤‡çš„资æºéœ€æ±‚。它也å¯ä»¥è°ƒç”¨_CRSæ¥æ‰¾åˆ°è¯¥è®¾ + 备的当å‰èµ„æºè®¾ç½®ã€‚利用这些信æ¯ï¼Œå³æ’å³ç”¨ç³»ç»Ÿå†³å®šè®¾å¤‡åº”该消耗什么资æºï¼Œå¹¶é€šè¿‡è°ƒç”¨è®¾å¤‡ + çš„_SRS控制方法æ¥è®¾ç½®è¿™äº›èµ„æºã€‚ + + 在ACPIä¸ï¼Œè®¾å¤‡å¯ä»¥æ¶ˆè€—资æºï¼ˆä¾‹å¦‚ï¼Œä¼ ç»Ÿçš„é”®ç›˜ï¼‰ï¼Œæ供资æºï¼ˆä¾‹å¦‚，一个专有的PCI桥）， + 或者两者都åšã€‚除éžå¦æœ‰è§„定，设备的资æºè¢«å‡å®šä¸ºæ¥è‡ªè®¾å¤‡å±‚次结构ä¸è®¾å¤‡ä¸Šæ–¹æœ€è¿‘的匹é…资 + æºã€‚ + +[4] ACPI 6.2, sec 6.4.3.5.1, 2, 3, 4: + QWord/DWord/Word 地å€ç©ºé—´æ述符 (.1, .2, .3) + å¸¸è§„æ ‡å¿—: Bit [0] 被忽略。 + + 扩展地å€ç©ºé—´æ述符 (.4) + å¸¸è§„æ ‡å¿—: Bit [0] 消费者/生产者: + + * 1 – è¿™ä¸ªè®¾å¤‡æ¶ˆè´¹è¿™ä¸ªèµ„æº + * 0 – è¯¥è®¾å¤‡ç”Ÿäº§å’Œæ¶ˆè´¹è¯¥èµ„æº + +[5] ACPI 6.2, sec 19.6.43: + ResourceUsage指定内å˜èŒƒå›´æ˜¯ç”±è¿™ä¸ªè®¾å¤‡ï¼ˆResourceConsumerï¼‰æ¶ˆè´¹è¿˜æ˜¯ä¼ é€’ç»™å设备 + （ResourceProducer）。如果没有指定，那么就å‡å®šæ˜¯ResourceConsumer。 + +[6] PCI Firmware 3.2, sec 4.1.2: + 如果æ“作系统ä¸èƒ½åŽŸç”Ÿçš„懂得ä¿ç•™MMCFG区域，MMCFG区域必须由固件ä¿ç•™ã€‚在MCFG表ä¸æˆ–通 + 过_CBA方法（è§ç¬¬4.1.3节）报告的地å€èŒƒå›´å¿…须通过声明主æ¿èµ„æºæ¥ä¿ç•™ã€‚对于大多数系统， + 主æ¿èµ„æºå°†å‡ºçŽ°åœ¨ACPI命åç©ºé—´çš„æ ¹éƒ¨ï¼ˆåœ¨_SB下），在一个节点的_HID为EISAID（PNP0C0 + 2），在这ç§æƒ…况下的资æºä¸åº”该è¦æ±‚åœ¨æ ¹PCI总线的_CRS。这些资æºå¯ä»¥é€‰æ‹©åœ¨Int15 E820 + 或EFIGetMemoryMapä¸ä½œä¸ºä¿ç•™å†…å˜è¿”回，但必须始终通过ACPI作为主æ¿èµ„æºæŠ¥å‘Šã€‚ + +[7] PCI Express 4.0, sec 7.2.2: + 对于PC兼容的系统，或者没有实现å…许访问é…置空间的处ç†å™¨æž¶æž„特定固件接å£æ ‡å‡†çš„系统，需 + è¦ä½¿ç”¨æœ¬èŠ‚ä¸å®šä¹‰çš„ECAM。 + +[8] PCI Firmware 3.2, sec 4.1.2: + MCFG表是一个ACPI表，用于沟通的基础地å€å¯¹åº”çš„éžçƒçš„å¯ç§»åŠ¨çš„PCI段组范围内的PCI段组在 + å¯åŠ¨æ—¶æ供给æ“作系统。这对PC兼容系统æ¥è¯´æ˜¯å¿…需的。 + + MCFG表仅用于沟通在å¯åŠ¨æ—¶ç³»ç»Ÿå¯ç”¨çš„PCI段组对应的基å€ã€‚ + +[9] PCI Firmware 3.2, sec 4.1.3: + _CBA (Memory mapped Configuration Base Address) 控制方法是一个å¯é€‰çš„ACPI对 + 象，用于返回çƒæ’拔主桥的64ä½å†…å˜æ˜ å°„çš„é…置基å€ã€‚_CBA 返回的基å€æ˜¯ä¸Žå¤„ç†å™¨ç›¸å…³çš„地å€ã€‚ + _CBA 控制方法被评估为一个整数。 + + 这个控制方法出现在主桥对象下。当_CBA方法出现在一个活动的主桥对象下时，æ“作系统会评 + 估这个结构，以确定内å˜æ˜ å°„çš„é…置基å€ï¼Œå¯¹åº”于_CRS方法ä¸æŒ‡å®šçš„总线编å·èŒƒå›´çš„PCI段组。 + 一个包å«_CBA方法的ACPI命å空间对象也必须包å«ä¸€ä¸ªç›¸åº”çš„_SEG方法。 diff --git a/Documentation/translations/zh_CN/PCI/index.rst b/Documentation/translations/zh_CN/PCI/index.rst index 16acb2bd9b58..cbeb33c34a98 100644 --- a/Documentation/translations/zh_CN/PCI/index.rst +++ b/Documentation/translations/zh_CN/PCI/index.rst @@ -10,9 +10,6 @@ :æ ¡è¯‘: - -.. _cn_PCI_index.rst: - =================== Linux PCI总线å系统 =================== @@ -26,12 +23,12 @@ Linux PCI总线å系统 pci-iov-howto msi-howto sysfs-pci + acpi-info Todolist: - acpi-info - pci-error-recovery - pcieaer-howto - endpoint/index - boot-interrupts +* pci-error-recovery +* pcieaer-howto +* endpoint/index +* boot-interrupts diff --git a/Documentation/translations/zh_CN/admin-guide/README.rst b/Documentation/translations/zh_CN/admin-guide/README.rst index d20949e8bf6f..e679cbc3c89d 100644 --- a/Documentation/translations/zh_CN/admin-guide/README.rst +++ b/Documentation/translations/zh_CN/admin-guide/README.rst @@ -6,10 +6,10 @@ å´æƒ³æˆ Wu XiangCheng <bobwxc@email.cn> -Linuxå†…æ ¸5.x版本 <http://kernel.org/> +Linuxå†…æ ¸6.x版本 <http://kernel.org/> ========================================= -以下是Linux版本5çš„å‘行注记。仔细阅读它们， +以下是Linux版本6çš„å‘行注记。仔细阅读它们， å®ƒä»¬ä¼šå‘Šè¯‰ä½ è¿™äº›éƒ½æ˜¯ä»€ä¹ˆï¼Œè§£é‡Šå¦‚ä½•å®‰è£…å†…æ ¸ï¼Œä»¥åŠé‡åˆ°é—®é¢˜æ—¶è¯¥å¦‚何åšã€‚ 什么是Linux？ @@ -61,27 +61,27 @@ Linuxå†…æ ¸5.x版本 <http://kernel.org/> - 如果您è¦å®‰è£…完整的æºä»£ç ï¼Œè¯·æŠŠå†…æ ¸tar档案包放在您有æƒé™çš„目录ä¸ï¼ˆä¾‹å¦‚您 的主目录）并将其解包:: - xz -cd linux-5.x.tar.xz | tar xvf - + xz -cd linux-6.x.tar.xz | tar xvf - 将“Xâ€æ›¿æ¢æˆæœ€æ–°å†…æ ¸çš„ç‰ˆæœ¬å·ã€‚ ã€ä¸è¦ã€‘使用 /usr/src/linux 目录ï¼è¿™é‡Œæœ‰ä¸€ç»„åº“å¤´æ–‡ä»¶ä½¿ç”¨çš„å†…æ ¸å¤´æ–‡ä»¶ （通常是ä¸å®Œæ•´çš„）。它们应该与库匹é…，而ä¸æ˜¯è¢«å†…æ ¸çš„å˜åŒ–æžå¾—一团糟。 - - 您还å¯ä»¥é€šè¿‡æ‰“è¡¥ä¸åœ¨5.x版本之间å‡çº§ã€‚è¡¥ä¸ä»¥xzæ ¼å¼åˆ†å‘。è¦é€šè¿‡æ‰“è¡¥ä¸è¿›è¡Œ - 安装，请获å–所有较新的补ä¸æ–‡ä»¶ï¼Œè¿›å…¥å†…æ ¸æºä»£ç （linux-5.x）的目录并 + - 您还å¯ä»¥é€šè¿‡æ‰“è¡¥ä¸åœ¨6.x版本之间å‡çº§ã€‚è¡¥ä¸ä»¥xzæ ¼å¼åˆ†å‘。è¦é€šè¿‡æ‰“è¡¥ä¸è¿›è¡Œ + 安装，请获å–所有较新的补ä¸æ–‡ä»¶ï¼Œè¿›å…¥å†…æ ¸æºä»£ç （linux-6.x）的目录并 执行:: - xz -cd ../patch-5.x.xz | patch -p1 + xz -cd ../patch-6.x.xz | patch -p1 请ã€æŒ‰é¡ºåºã€‘替æ¢æ‰€æœ‰å¤§äºŽå½“å‰æºä»£ç æ ‘ç‰ˆæœ¬çš„â€œxâ€ï¼Œè¿™æ ·å°±å¯ä»¥äº†ã€‚您å¯èƒ½æƒ³è¦ åˆ é™¤å¤‡ä»½æ–‡ä»¶ï¼ˆæ–‡ä»¶å类似xxx~ 或 xxx.orig)，并确ä¿æ²¡æœ‰å¤±è´¥çš„è¡¥ä¸ï¼ˆæ–‡ä»¶å 类似xxx# 或 xxx.rej）。如果有，ä¸æ˜¯ä½ 就是我犯了错误。 - 与5.xå†…æ ¸çš„è¡¥ä¸ä¸åŒï¼Œ5.x.yå†…æ ¸ï¼ˆä¹Ÿç§°ä¸ºç¨³å®šç‰ˆå†…æ ¸ï¼‰çš„è¡¥ä¸ä¸æ˜¯å¢žé‡çš„，而是 - 直接应用于基本的5.xå†…æ ¸ã€‚ä¾‹å¦‚ï¼Œå¦‚æžœæ‚¨çš„åŸºæœ¬å†…æ ¸æ˜¯5.0，并且希望应用5.0.3 - è¡¥ä¸ï¼Œåˆ™ä¸åº”先应用5.0.1å’Œ5.0.2çš„è¡¥ä¸ã€‚类似地，如果您è¿è¡Œçš„是5.0.2å†…æ ¸ï¼Œ - 并且希望跳转到5.0.3，那么在应用5.0.3è¡¥ä¸ä¹‹å‰ï¼Œå¿…须首先撤销5.0.2è¡¥ä¸ + 与6.xå†…æ ¸çš„è¡¥ä¸ä¸åŒï¼Œ6.x.yå†…æ ¸ï¼ˆä¹Ÿç§°ä¸ºç¨³å®šç‰ˆå†…æ ¸ï¼‰çš„è¡¥ä¸ä¸æ˜¯å¢žé‡çš„，而是 + 直接应用于基本的6.xå†…æ ¸ã€‚ä¾‹å¦‚ï¼Œå¦‚æžœæ‚¨çš„åŸºæœ¬å†…æ ¸æ˜¯6.0，并且希望应用6.0.3 + è¡¥ä¸ï¼Œåˆ™ä¸åº”先应用6.0.1å’Œ6.0.2çš„è¡¥ä¸ã€‚类似地，如果您è¿è¡Œçš„是6.0.2å†…æ ¸ï¼Œ + 并且希望跳转到6.0.3，那么在应用6.0.3è¡¥ä¸ä¹‹å‰ï¼Œå¿…须首先撤销6.0.2è¡¥ä¸ ï¼ˆå³patch -R）。更多关于这方é¢çš„内容，请阅读 :ref:`Documentation/process/applying-patches.rst <applying_patches>` 。 @@ -103,7 +103,7 @@ Linuxå†…æ ¸5.x版本 <http://kernel.org/> 软件è¦æ±‚ --------- - 编译和è¿è¡Œ5.xå†…æ ¸éœ€è¦å„ç§è½¯ä»¶åŒ…的最新版本。请å‚考 + 编译和è¿è¡Œ6.xå†…æ ¸éœ€è¦å„ç§è½¯ä»¶åŒ…的最新版本。请å‚考 :ref:`Documentation/process/changes.rst <changes>` æ¥äº†è§£æœ€ä½Žç‰ˆæœ¬è¦æ±‚以åŠå¦‚何å‡çº§è½¯ä»¶åŒ…。请注æ„，使用过旧版本的这些包å¯èƒ½ä¼š å¯¼è‡´å¾ˆéš¾è¿½è¸ªçš„é—´æŽ¥é”™è¯¯ï¼Œå› æ¤ä¸è¦ä»¥ä¸ºåœ¨ç”Ÿæˆæˆ–æ“作过程ä¸å‡ºçŽ°æ˜Žæ˜¾é—®é¢˜æ—¶å¯ä»¥ @@ -116,12 +116,12 @@ Linuxå†…æ ¸5.x版本 <http://kernel.org/> ``make O=output/dir`` 选项å¯ä»¥ä¸ºè¾“出文件（包括 .config）指定备用ä½ç½®ã€‚ 例如:: - kernel source code: /usr/src/linux-5.x + kernel source code: /usr/src/linux-6.x build directory: /home/name/build/kernel è¦é…ç½®å’Œæž„å»ºå†…æ ¸ï¼Œè¯·ä½¿ç”¨:: - cd /usr/src/linux-5.x + cd /usr/src/linux-6.x make O=/home/name/build/kernel menuconfig make O=/home/name/build/kernel sudo make O=/home/name/build/kernel modules_install install @@ -227,8 +227,6 @@ Linuxå†…æ ¸5.x版本 <http://kernel.org/> - ç¡®ä¿æ‚¨è‡³å°‘有gcc 5.1å¯ç”¨ã€‚ 有关更多信æ¯ï¼Œè¯·å‚阅 :ref:`Documentation/process/changes.rst <changes>` 。 - 请注æ„，您ä»ç„¶å¯ä»¥ä½¿ç”¨æ¤å†…æ ¸è¿è¡Œa.out用户程åºã€‚ - - 执行 ``make`` æ¥åˆ›å»ºåŽ‹ç¼©å†…æ ¸æ˜ åƒã€‚如果您安装了lilo以适é…å†…æ ¸makefile， 那么也å¯ä»¥è¿›è¡Œ ``make install`` ，但是您å¯èƒ½éœ€è¦å…ˆæ£€æŸ¥ç‰¹å®šçš„lilo设置。 @@ -282,67 +280,12 @@ Linuxå†…æ ¸5.x版本 <http://kernel.org/> è‹¥é‡åˆ°é—®é¢˜ ----------- - - 如果您å‘现了一些å¯èƒ½ç”±äºŽå†…æ ¸ç¼ºé™·æ‰€å¯¼è‡´çš„é—®é¢˜ï¼Œè¯·æ£€æŸ¥MAINTAINERS（维护者） - 文件看看是å¦æœ‰äººä¸Žä»¤æ‚¨é‡åˆ°éº»çƒ¦çš„å†…æ ¸éƒ¨åˆ†ç›¸å…³ã€‚å¦‚æžœæ— äººåœ¨æ¤åˆ—出，那么第二 - 个最好的方案就是把它们å‘给我（torvalds@linux-foundation.org），也å¯èƒ½å‘é€ - 到任何其他相关的邮件列表或新闻组。 - - - 在所有的缺陷报告ä¸ï¼Œã€è¯·ã€‘å‘Šè¯‰æˆ‘ä»¬æ‚¨åœ¨è¯´ä»€ä¹ˆå†…æ ¸ï¼Œå¦‚ä½•å¤çŽ°é—®é¢˜ï¼Œä»¥åŠæ‚¨çš„ - 设置是什么的（使用您的常识）。如果问题是新的，请告诉我；如果问题是旧的， - 请å°è¯•å‘Šè¯‰æˆ‘您什么时候首次注æ„到它。 - - - 如果缺陷导致如下消æ¯:: - - unable to handle kernel paging request at address C0000010 - Oops: 0002 - EIP: 0010:XXXXXXXX - eax: xxxxxxxx ebx: xxxxxxxx ecx: xxxxxxxx edx: xxxxxxxx - esi: xxxxxxxx edi: xxxxxxxx ebp: xxxxxxxx - ds: xxxx es: xxxx fs: xxxx gs: xxxx - Pid: xx, process nr: xx - xx xx xx xx xx xx xx xx xx xx - - æˆ–è€…ç±»ä¼¼çš„å†…æ ¸è°ƒè¯•ä¿¡æ¯æ˜¾ç¤ºåœ¨å±å¹•ä¸Šæˆ–在系统日志里，请ã€å¦‚实】å¤åˆ¶å®ƒã€‚ - å¯èƒ½å¯¹ä½ æ¥è¯´è½¬å‚¨ï¼ˆdump）看起æ¥ä¸å¯ç†è§£ï¼Œä½†å®ƒç¡®å®žåŒ…å«å¯èƒ½æœ‰åŠ©äºŽè°ƒè¯•é—®é¢˜çš„ - ä¿¡æ¯ã€‚转储上方的文本也很é‡è¦ï¼šå®ƒè¯´æ˜Žäº†å†…æ ¸è½¬å‚¨ä»£ç çš„åŽŸå› ï¼ˆåœ¨ä¸Šé¢çš„示例ä¸ï¼Œ - æ˜¯ç”±äºŽå†…æ ¸æŒ‡é’ˆé”™è¯¯ï¼‰ã€‚æ›´å¤šå…³äºŽå¦‚ä½•ç†è§£è½¬å‚¨çš„ä¿¡æ¯ï¼Œè¯·å‚è§ - Documentation/admin-guide/bug-hunting.rst。 - - - 如果使用 CONFIG_KALLSYMS ç¼–è¯‘å†…æ ¸ï¼Œåˆ™å¯ä»¥æŒ‰åŽŸæ ·å‘é€è½¬å‚¨ï¼Œå¦åˆ™å¿…须使用 - ``ksymoops`` 程åºæ¥ç†è§£è½¬å‚¨ï¼ˆä½†é€šå¸¸é¦–选使用CONFIG_KALLSYMS编译）。 - æ¤å®žç”¨ç¨‹åºå¯ä»Ž - https://www.kernel.org/pub/linux/utils/kernel/ksymoops/ 下载。 - 或者，您å¯ä»¥æ‰‹åŠ¨æ‰§è¡Œè½¬å‚¨æŸ¥æ‰¾ï¼š - - - 在调试åƒä¸Šé¢è¿™æ ·çš„转储时，如果您å¯ä»¥æŸ¥æ‰¾EIP值的å«ä¹‰ï¼Œè¿™å°†éžå¸¸æœ‰å¸®åŠ©ã€‚ - åå…进制值本身对我或其他任何人都没有太大帮助：它会å–å†³äºŽç‰¹å®šçš„å†…æ ¸è®¾ç½®ã€‚ - 您应该åšçš„是从EIP行获å–åå…进制值（忽略 ``0010:`` ），然åŽåœ¨å†…æ ¸åå—列表 - ä¸æŸ¥æ‰¾å®ƒï¼Œä»¥æŸ¥çœ‹å“ªä¸ªå†…æ ¸å‡½æ•°åŒ…å«æœ‰é—®é¢˜çš„地å€ã€‚ - - è¦æ‰¾åˆ°å†…æ ¸å‡½æ•°å，您需è¦æ‰¾åˆ°ä¸Žæ˜¾ç¤ºç—‡çŠ¶çš„å†…æ ¸ç›¸å…³è”的系统二进制文件。就是 - 文件“linux/vmlinuxâ€ã€‚è¦æå–åå—åˆ—è¡¨å¹¶å°†å…¶ä¸Žå†…æ ¸å´©æºƒä¸çš„EIP进行匹é…， - 请执行:: - - nm vmlinux | sort | less - - 这将为您æ供一个按å‡åºæŽ’åºçš„å†…æ ¸åœ°å€åˆ—表，从ä¸å¾ˆå®¹æ˜“找到包å«æœ‰é—®é¢˜çš„åœ°å€ - 的函数。请注æ„ï¼Œå†…æ ¸è°ƒè¯•æ¶ˆæ¯æ供的地å€ä¸ä¸€å®šä¸Žå‡½æ•°åœ°å€å®Œå…¨åŒ¹é…（事实上， - 这是ä¸å¯èƒ½çš„ï¼‰ï¼Œå› æ¤æ‚¨ä¸èƒ½åªâ€œgrepâ€åˆ—表：ä¸è¿‡åˆ—表将为您æä¾›æ¯ä¸ªå†…æ ¸å‡½æ•° - çš„èµ·ç‚¹ï¼Œå› æ¤é€šè¿‡æŸ¥æ‰¾èµ·å§‹åœ°å€ä½ŽäºŽä½ æ£åœ¨æœç´¢çš„地å€ï¼Œä½†åŽä¸€ä¸ªå‡½æ•°çš„高于的 - å‡½æ•°ï¼Œä½ ä¼šæ‰¾åˆ°æ‚¨æƒ³è¦çš„。实际上，在您的问题报告ä¸åŠ 入一些“上下文â€å¯èƒ½æ˜¯ - 一个好主æ„ï¼Œç»™å‡ºç›¸å…³çš„ä¸Šä¸‹å‡ è¡Œã€‚ - - 如果您由于æŸäº›åŽŸå› æ— æ³•å®Œæˆä¸Šè¿°æ“ä½œï¼ˆå¦‚æ‚¨ä½¿ç”¨é¢„ç¼–è¯‘çš„å†…æ ¸æ˜ åƒæˆ–ç±»ä¼¼çš„æ˜ åƒï¼‰ï¼Œ - 请尽å¯èƒ½å¤šåœ°å‘Šè¯‰æˆ‘您的相关设置信æ¯ï¼Œè¿™ä¼šæœ‰æ‰€å¸®åŠ©ã€‚有关详细信æ¯è¯·é˜…读 - ‘Documentation/admin-guide/reporting-issues.rst’。 - - - 或者，您å¯ä»¥åœ¨æ£åœ¨è¿è¡Œçš„å†…æ ¸ä¸Šä½¿ç”¨gdb（åªè¯»çš„ï¼›å³ä¸èƒ½æ›´æ”¹å€¼æˆ–设置æ–点）。 - 为æ¤ï¼Œè¯·é¦–先使用-gç¼–è¯‘å†…æ ¸ï¼›é€‚å½“åœ°ç¼–è¾‘arch/x86/Makefile，然åŽæ‰§è¡Œ ``make - clean`` 。您还需è¦å¯ç”¨CONFIG_PROC_FS（通过 ``make config`` ）。 - - ä½¿ç”¨æ–°å†…æ ¸é‡æ–°å¯åŠ¨åŽï¼Œæ‰§è¡Œ ``gdb vmlinux /proc/kcore`` 。现在å¯ä»¥ä½¿ç”¨æ‰€æœ‰ - 普通的gdb命令。查找系统崩溃点的命令是 ``l *0xXXXXXXXX`` （将xxx替æ¢ä¸ºEIP - 值）。 - - 用gdbæ— æ³•è°ƒè¯•ä¸€ä¸ªå½“å‰æœªè¿è¡Œçš„å†…æ ¸æ˜¯ç”±äºŽgdbï¼ˆé”™è¯¯åœ°ï¼‰å¿½ç•¥äº†ç¼–è¯‘å†…æ ¸çš„èµ·å§‹ - å移é‡ã€‚ +如果您å‘现了一些å¯èƒ½ç”±äºŽå†…æ ¸ç¼ºé™·æ‰€å¯¼è‡´çš„é—®é¢˜ï¼Œè¯·å‚阅： +Documentation/translations/zh_CN/admin-guide/reporting-issues.rst 。 + +想è¦ç†è§£å†…æ ¸é”™è¯¯æŠ¥å‘Šï¼Œè¯·å‚阅： +Documentation/translations/zh_CN/admin-guide/bug-hunting.rst 。 + +更多用GDBè°ƒè¯•å†…æ ¸çš„ä¿¡æ¯ï¼Œè¯·å‚阅： +Documentation/translations/zh_CN/dev-tools/gdb-kernel-debugging.rst +å’Œ Documentation/dev-tools/kgdb.rst 。 diff --git a/Documentation/translations/zh_CN/admin-guide/bootconfig.rst b/Documentation/translations/zh_CN/admin-guide/bootconfig.rst new file mode 100644 index 000000000000..072d17f5f199 --- /dev/null +++ b/Documentation/translations/zh_CN/admin-guide/bootconfig.rst @@ -0,0 +1,293 @@ +.. SPDX-License-Identifier: GPL-2.0 + +.. include:: ../disclaimer-zh_CN.rst + +:Original: Documentation/admin-guide/bootconfig.rst + +:译者: å´æƒ³æˆ Wu XiangCheng <bobwxc@email.cn> + +======== +引导é…ç½® +======== + +:作者: Masami Hiramatsu <mhiramat@kernel.org> + +概述 +==== + +引导é…ç½®æ‰©å±•äº†çŽ°æœ‰çš„å†…æ ¸å‘½ä»¤è¡Œï¼Œä»¥ä¸€ç§æ›´æœ‰æ•ˆçŽ‡çš„æ–¹å¼åœ¨å¼•å¯¼å†…æ ¸æ—¶è¿›ä¸€æ¥æ”¯æŒ +键值数æ®ã€‚è¿™å…许管ç†å‘˜ä¼ 递一份结构化关键å—çš„é…置文件。 + +é…置文件è¯æ³• +============ + +引导é…置文件的è¯æ³•é‡‡ç”¨éžå¸¸ç®€å•çš„键值结构。æ¯ä¸ªå…³é”®å—由点连接的å•è¯ç»„æˆï¼Œé”® +和值由 ``=`` 连接。值以分å·ï¼ˆ ``;`` ）或æ¢è¡Œç¬¦ï¼ˆ ``\n`` ）结尾。数组值ä¸æ¯ +ä¸ªå…ƒç´ ç”±é€—å·ï¼ˆ ``,`` ）分隔。:: + + KEY[.WORD[...]] = VALUE[, VALUE2[...]][;] + +ä¸Žå†…æ ¸å‘½ä»¤è¡Œè¯æ³•ä¸åŒï¼Œé€—å·å’Œ ``=`` 周围å…è®¸æœ‰ç©ºæ ¼ã€‚ + +关键å—åªå…许包å«å—æ¯ã€æ•°å—ã€è¿žå—符（ ``-`` ）和下划线（ ``_`` ）。值å¯åŒ…å« +å¯æ‰“å°å—ç¬¦å’Œç©ºæ ¼ï¼Œä½†åˆ†å·ï¼ˆ ``;`` ）ã€æ¢è¡Œç¬¦ï¼ˆ ``\n`` ）ã€é€—å·ï¼ˆ ``,`` ）〠+井å·ï¼ˆ ``#`` ）和å³å¤§æ‹¬å·ï¼ˆ ``}`` ）ç‰åˆ†éš”符除外。 + +å¦‚æžœä½ éœ€è¦åœ¨å€¼ä¸ä½¿ç”¨è¿™äº›åˆ†éš”符，å¯ä»¥ç”¨åŒå¼•å·ï¼ˆ ``"VALUE"`` ）或å•å¼•å· +（ ``'VALUE'`` ）括起æ¥ã€‚注æ„，引å·æ— 法转义。 + +键的值å¯ä»¥ä¸ºç©ºæˆ–ä¸å˜åœ¨ã€‚这些键用于检查该键是å¦å˜åœ¨ï¼ˆç±»ä¼¼å¸ƒå°”值）。 + +键值è¯æ³• +-------- + +引导é…置文件è¯æ³•å…许用户通过大括å·åˆå¹¶é”®å部分相åŒçš„关键å—。例如:: + + foo.bar.baz = value1 + foo.bar.qux.quux = value2 + +也å¯ä»¥å†™æˆ:: + + foo.bar { + baz = value1 + qux.quux = value2 + } + +或者更紧凑一些，写æˆ:: + + foo.bar { baz = value1; qux.quux = value2 } + +在这两ç§æ ·å¼ä¸ï¼Œå¼•å¯¼è§£æžæ—¶ç›¸åŒçš„关键å—都会自动åˆå¹¶ã€‚å› æ¤å¯ä»¥è¿½åŠ ç±»ä¼¼çš„æ ‘æˆ– +键值。 + +相åŒå…³é”®å—的值 +-------------- + +ç¦æ¢ä¸¤ä¸ªæˆ–多个值或数组共享åŒä¸€ä¸ªå…³é”®å—。例如:: + + foo = bar, baz + foo = qux # !错误! 我们ä¸å¯ä»¥é‡å®šä¹‰ç›¸åŒçš„å…³é”®å— + +å¦‚æžœä½ æƒ³è¦æ›´æ–°å€¼ï¼Œå¿…须显å¼ä½¿ç”¨è¦†ç›–æ“作符 ``:=`` 。例如:: + + foo = bar, baz + foo := qux + +è¿™æ · ``foo`` 关键å—的值就å˜æˆäº† ``qux`` ã€‚è¿™å¯¹äºŽé€šè¿‡æ·»åŠ ï¼ˆéƒ¨åˆ†ï¼‰è‡ªå®šä¹‰å¼•å¯¼ +é…ç½®æ¥è¦†ç›–默认值éžå¸¸æœ‰ç”¨ï¼Œå…于解æžé»˜è®¤å¼•å¯¼é…置。 + +å¦‚æžœä½ æƒ³å¯¹çŽ°æœ‰å…³é”®å—è¿½åŠ å€¼ä½œä¸ºæ•°ç»„æˆå‘˜ï¼Œå¯ä»¥ä½¿ç”¨ ``+=`` æ“作符。例如:: + + foo = bar, baz + foo += qux + +è¿™æ ·ï¼Œ ``foo`` 关键å—å°±åŒæ—¶æ‹¥æœ‰äº† ``bar`` ， ``baz`` å’Œ ``qux`` 。 + +æ¤å¤–，父关键å—下å¯åŒæ—¶å˜åœ¨å€¼å’Œå关键å—。 +例如，下列é…置是å¯è¡Œçš„。:: + + foo = value1 + foo.bar = value2 + foo := value3 # 这会更新foo的值。 + +注æ„，裸值ä¸èƒ½ç›´æŽ¥æ”¾è¿›ç»“构化关键å—ä¸ï¼Œå¿…须在大括å·å¤–定义它。例如:: + + foo { + bar = value1 + bar { + baz = value2 + qux = value3 + } + } + +åŒæ—¶ï¼Œå…³é”®å—下值节点的顺åºæ˜¯å›ºå®šçš„。如果值和å关键å—åŒæ—¶å˜åœ¨ï¼Œå€¼æ°¸è¿œæ˜¯è¯¥å…³ +é”®å—的第一个åèŠ‚ç‚¹ã€‚å› æ¤å¦‚果用户先指定å关键å—，如:: + + foo.bar = value1 + foo = value2 + +则在程åºï¼ˆå’Œ/proc/bootconfig）ä¸ï¼Œå®ƒä¼šæŒ‰å¦‚下显示:: + + foo = value2 + foo.bar = value1 + +注释 +---- + +é…ç½®è¯æ³•æŽ¥å—shellè„šæœ¬é£Žæ ¼çš„æ³¨é‡Šã€‚æ³¨é‡Šä»¥äº•å·ï¼ˆ ``#`` ）开始，到æ¢è¡Œç¬¦ +（ ``\n`` ）结æŸã€‚ + +:: + + # comment line + foo = value # value is set to foo. + bar = 1, # 1st element + 2, # 2nd element + 3 # 3rd element + +会被解æžä¸º:: + + foo = value + bar = 1, 2, 3 + +注æ„ä½ ä¸èƒ½æŠŠæ³¨é‡Šæ”¾åœ¨å€¼å’Œåˆ†éš”符（ ``,`` 或 ``;`` ）之间。如下é…ç½®è¯æ³•æ˜¯é”™è¯¯çš„:: + + key = 1 # comment + ,2 + + +/proc/bootconfig +================ + +/proc/bootconfig是引导é…置的用户空间接å£ã€‚与/proc/cmdlineä¸åŒï¼Œæ¤æ–‡ä»¶å†…容以 +é”®å€¼åˆ—è¡¨æ ·å¼æ˜¾ç¤ºã€‚ +æ¯ä¸ªé”®å€¼å¯¹ä¸€è¡Œï¼Œæ ·å¼å¦‚下:: + + KEY[.WORDS...] = "[VALUE]"[,"VALUE2"...] + + +用引导é…ç½®å¼•å¯¼å†…æ ¸ +================== + +用引导é…ç½®å¼•å¯¼å†…æ ¸æœ‰ä¸¤ç§æ–¹æ³•ï¼šå°†å¼•å¯¼é…ç½®é™„åŠ åˆ°initrdé•œåƒæˆ–ç›´æŽ¥åµŒå…¥å†…æ ¸ä¸ã€‚ + +*initrd: initial RAM disk，åˆå§‹å†…å˜ç£ç›˜* + +将引导é…ç½®é™„åŠ åˆ°initrd +---------------------- + +由于默认情况下引导é…置文件是用initrdåŠ è½½çš„ï¼Œå› æ¤å®ƒå°†è¢«æ·»åŠ 到initrd（initramfs） +é•œåƒæ–‡ä»¶çš„末尾，其ä¸åŒ…å«å¡«å……ã€å¤§å°ã€æ ¡éªŒå€¼å’Œ12å—节幻数，如下所示:: + + [initrd][bootconfig][padding][size(le32)][checksum(le32)][#BOOTCONFIG\n] + +大å°å’Œæ ¡éªŒå€¼ä¸ºå°ç«¯åºå˜æ”¾çš„32ä½æ— 符å·å€¼ã€‚ + +当引导é…ç½®è¢«åŠ åˆ°initrdé•œåƒæ—¶ï¼Œæ•´ä¸ªæ–‡ä»¶å¤§å°ä¼šå¯¹é½åˆ°4å—节。空å—符（ ``\0`` ） +会填补对é½ç©ºéš™ã€‚å› æ¤ ``size`` 就是引导é…置文件的长度+å¡«å……çš„å—节。 + +Linuxå†…æ ¸åœ¨å†…å˜ä¸è§£ç initrdé•œåƒçš„最åŽéƒ¨åˆ†ä»¥èŽ·å–引导é…置数æ®ã€‚由于这ç§â€œèƒŒè´Ÿå¼â€ +的方法，åªè¦å¼•å¯¼åŠ è½½å™¨ä¼ é€’äº†æ£ç¡®çš„initrd文件大å°ï¼Œå°±æ— éœ€æ›´æ”¹æˆ–æ›´æ–°å¼•å¯¼åŠ è½½å™¨ +å’Œå†…æ ¸é•œåƒæœ¬èº«ã€‚å¦‚æžœå¼•å¯¼åŠ è½½å™¨æ„å¤–ä¼ é€’äº†æ›´é•¿çš„å¤§å°ï¼Œå†…æ ¸å°†æ— æ³•æ‰¾åˆ°å¼•å¯¼é…置数 +æ®ã€‚ + +Linuxå†…æ ¸åœ¨tools/bootconfig下æ供了 ``bootconfig`` 命令æ¥å®Œæˆæ¤æ“作，管ç†å‘˜ +å¯ä»¥ç”¨å®ƒä»Žinitrdé•œåƒä¸åˆ é™¤æˆ–è¿½åŠ é…ç½®æ–‡ä»¶ã€‚ä½ å¯ä»¥ç”¨ä»¥ä¸‹å‘½ä»¤æ¥æž„建它:: + + # make -C tools/bootconfig + +è¦å‘initrdé•œåƒæ·»åŠ ä½ çš„å¼•å¯¼é…置文件，请按如下命令æ“作（旧数æ®ä¼šè‡ªåŠ¨ç§»é™¤ï¼‰:: + + # tools/bootconfig/bootconfig -a your-config /boot/initrd.img-X.Y.Z + +è¦ä»Žé•œåƒä¸ç§»é™¤é…置，å¯ä»¥ä½¿ç”¨-d选项:: + + # tools/bootconfig/bootconfig -d /boot/initrd.img-X.Y.Z + +然åŽåœ¨å†…æ ¸å‘½ä»¤è¡Œä¸Šæ·»åŠ ``bootconfig`` å‘Šè¯‰å†…æ ¸åŽ»initrdæ–‡ä»¶æœ«å°¾å¯»æ‰¾å†…æ ¸é…置。 + +将引导é…ç½®åµŒå…¥å†…æ ¸ +------------------ + +å¦‚æžœä½ ä¸èƒ½ä½¿ç”¨initrd，也å¯ä»¥é€šè¿‡Kconfig选项将引导é…ç½®æ–‡ä»¶åµŒå…¥å†…æ ¸ä¸ã€‚在æ¤æƒ… +å†µä¸‹ï¼Œä½ éœ€è¦ç”¨ä»¥ä¸‹é€‰é¡¹é‡æ–°ç¼–è¯‘å†…æ ¸:: + + CONFIG_BOOT_CONFIG_EMBED=y + CONFIG_BOOT_CONFIG_EMBED_FILE="/引导é…ç½®/文件/çš„/路径" + +``CONFIG_BOOT_CONFIG_EMBED_FILE`` 需è¦ä»Žæºç æ ‘æˆ–å¯¹è±¡æ ‘å¼€å§‹çš„å¼•å¯¼é…置文件的 +ç»å¯¹/ç›¸å¯¹è·¯å¾„ã€‚å†…æ ¸ä¼šå°†å…¶åµŒå…¥ä½œä¸ºé»˜è®¤å¼•å¯¼é…置。 + +与将引导é…ç½®é™„åŠ åˆ°initrdä¸€æ ·ï¼Œä½ ä¹Ÿéœ€è¦åœ¨å†…æ ¸å‘½ä»¤è¡Œä¸Šæ·»åŠ ``bootconfig`` 告诉 +å†…æ ¸åŽ»å¯ç”¨å†…嵌的引导é…置。 + +注æ„，å³ä½¿ä½ å·²ç»è®¾ç½®äº†æ¤é€‰é¡¹ï¼Œä»å¯ç”¨é™„åŠ åˆ°initrd的其他引导é…置覆盖内嵌的引导 +é…置。 + +通过引导é…ç½®ä¼ é€’å†…æ ¸å‚æ•° +======================== + +é™¤äº†å†…æ ¸å‘½ä»¤è¡Œï¼Œå¼•å¯¼é…置也å¯ä»¥ç”¨äºŽä¼ é€’å†…æ ¸å‚数。所有 ``kernel`` 关键å—下的键 +å€¼å¯¹éƒ½å°†ç›´æŽ¥ä¼ é€’ç»™å†…æ ¸å‘½ä»¤è¡Œã€‚æ¤å¤–， ``init`` ä¸‹çš„é”®å€¼å¯¹å°†é€šè¿‡å‘½ä»¤è¡Œä¼ é€’ç»™ +init进程。å‚数按以下顺åºä¸Žç”¨æˆ·ç»™å®šçš„å†…æ ¸å‘½ä»¤è¡Œå—ç¬¦ä¸²ç›¸è¿žï¼Œå› æ¤å‘½ä»¤è¡Œå‚æ•°å¯ä»¥ +覆盖引导é…ç½®å‚数（这å–决于å系统如何处ç†å‚数，但通常å‰é¢çš„å‚数将被åŽé¢çš„å‚æ•° +覆盖）:: + + [bootconfig params][cmdline params] -- [bootconfig init params][cmdline init params] + +如果引导é…置文件给出的kernel/initå‚数是:: + + kernel { + root = 01234567-89ab-cdef-0123-456789abcd + } + init { + splash + } + +这将被å¤åˆ¶åˆ°å†…æ ¸å‘½ä»¤è¡Œå—符串ä¸ï¼Œå¦‚下所示:: + + root="01234567-89ab-cdef-0123-456789abcd" -- splash + +如果用户给出的其他命令行是:: + + ro bootconfig -- quiet + +则最åŽçš„å†…æ ¸å‘½ä»¤è¡Œå¦‚ä¸‹:: + + root="01234567-89ab-cdef-0123-456789abcd" ro bootconfig -- splash quiet + + +é…置文件的é™åˆ¶ +============== + +当å‰æœ€å¤§çš„é…置大å°æ˜¯32KB，关键å—总数（ä¸æ˜¯é”®å€¼æ¡ç›®ï¼‰å¿…须少于1024个节点。 +注æ„：这ä¸æ˜¯æ¡ç›®æ•°è€Œæ˜¯èŠ‚点数，æ¡ç›®å¿…须消耗超过2个节点（一个关键å—和一个值）。 +所以从ç†è®ºä¸Šè®²æœ€å¤š512个键值对。如果关键å—å¹³å‡åŒ…å«3个å•è¯ï¼Œåˆ™å¯æœ‰256个键值对。 +在大多数情况下，é…置项的数é‡å°†å°‘于100个æ¡ç›®ï¼Œå°äºŽ8KBï¼Œå› æ¤è¿™åº”该足够了。如果 +节点数超过1024，解æžå™¨å°†è¿”回错误，å³ä½¿æ–‡ä»¶å¤§å°å°äºŽ32KB。（请注æ„，æ¤æœ€å¤§å°ºå¯¸ +ä¸åŒ…括填充的空å—符。） +æ— è®ºå¦‚ä½•ï¼Œå› ä¸º ``bootconfig`` å‘½ä»¤åœ¨é™„åŠ å¯åŠ¨é…置到initrdæ˜ åƒæ—¶ä¼šéªŒè¯å®ƒï¼Œç”¨æˆ· +å¯ä»¥åœ¨å¼•å¯¼ä¹‹å‰æ³¨æ„到它。 + + +引导é…ç½®API +=========== + +用户å¯ä»¥æŸ¥è¯¢æˆ–é历键值对，也å¯ä»¥æŸ¥æ‰¾ï¼ˆå‰ç¼€ï¼‰æ ¹å…³é”®å—节点，并在查找该节点下的 +键值。 + +如果您有一个关键å—å—符串，则å¯ä»¥ç›´æŽ¥ä½¿ç”¨ xbc_find_value() 查询该键的值。如果 +ä½ æƒ³çŸ¥é“引导é…置里有哪些关键å—，å¯ä»¥ä½¿ç”¨ xbc_for_each_key_value() è¿ä»£é”®å€¼å¯¹ã€‚ +请注æ„，您需è¦ä½¿ç”¨ xbc_array_for_each_value() 访问数组的值，例如:: + + vnode = NULL; + xbc_find_value("key.word", &vnode); + if (vnode && xbc_node_is_array(vnode)) + xbc_array_for_each_value(vnode, value) { + printk("%s ", value); + } + +如果您想查找具有å‰ç¼€å—符串的键，å¯ä»¥ä½¿ç”¨ xbc_find_node() 通过å‰ç¼€å—符串查找 +节点，然åŽç”¨ xbc_node_for_each_key_value() è¿ä»£å‰ç¼€èŠ‚点下的键。 + +但最典型的用法是获å–å‰ç¼€ä¸‹çš„命å值或å‰ç¼€ä¸‹çš„命å数组，例如:: + + root = xbc_find_node("key.prefix"); + value = xbc_node_find_value(root, "option", &vnode); + ... + xbc_node_for_each_array_value(root, "array-option", value, anode) { + ... + } + +这将访问值“key.prefix.optionâ€çš„值和“key.prefix.array-optionâ€çš„数组。 + +é”是ä¸éœ€è¦çš„ï¼Œå› ä¸ºåœ¨åˆå§‹åŒ–之åŽé…ç½®åªè¯»ã€‚如果需è¦ä¿®æ”¹ï¼Œå¿…é¡»å¤åˆ¶æ‰€æœ‰æ•°æ®å’Œå…³é”®å—。 + + +函数与结构体 +============ + +相关定义的kernel-docå‚è§ï¼š + + - include/linux/bootconfig.h + - lib/bootconfig.c diff --git a/Documentation/translations/zh_CN/admin-guide/index.rst b/Documentation/translations/zh_CN/admin-guide/index.rst index 2f6970d0a032..ac2960da33e6 100644 --- a/Documentation/translations/zh_CN/admin-guide/index.rst +++ b/Documentation/translations/zh_CN/admin-guide/index.rst @@ -63,6 +63,7 @@ Todolist: .. toctree:: :maxdepth: 1 + bootconfig clearing-warn-once cpu-load cputopology @@ -80,7 +81,6 @@ Todolist: * binderfs * binfmt-misc * blockdev/index -* bootconfig * braille-console * btmrvl * cgroup-v1/index diff --git a/Documentation/translations/zh_CN/core-api/circular-buffers.rst b/Documentation/translations/zh_CN/core-api/circular-buffers.rst new file mode 100644 index 000000000000..694ad8e61070 --- /dev/null +++ b/Documentation/translations/zh_CN/core-api/circular-buffers.rst @@ -0,0 +1,210 @@ +.. SPDX-License-Identifier: GPL-2.0+ + +.. include:: ../disclaimer-zh_CN.rst + +:Original: Documentation/core-api/circular-buffers.rst + +:翻译: + + 周彬彬 Binbin Zhou <zhoubinbin@loongson.cn> + +:æ ¡è¯‘: + + å¸å»¶è…¾ Yanteng Si <siyanteng@loongson.cn> + å´æƒ³æˆ Wu Xiangcheng <bobwxc@email.cn> + 时奎亮 Alex Shi <alexs@kernel.org> + +========== +环形缓冲区 +========== + +:作者: David Howells <dhowells@redhat.com> +:作者: Paul E. McKenney <paulmck@linux.ibm.com> + + +Linux æ供了许多å¯ç”¨äºŽå®žçŽ°å¾ªçŽ¯ç¼“å†²çš„ç‰¹æ€§ã€‚æœ‰ä¸¤ç»„è¿™æ ·çš„ç‰¹æ€§ï¼š + + (1) 用于确定2次方大å°çš„缓冲区信æ¯çš„便利函数。 + + (2) å¯ä»¥ä»£æ›¿ç¼“冲区ä¸å¯¹è±¡çš„生产者和消费者共享é”的内å˜å±éšœã€‚ + +如下所述，è¦ä½¿ç”¨è¿™äº›è®¾æ–½ï¼Œåªéœ€è¦ä¸€ä¸ªç”Ÿäº§è€…和一个消费者。å¯ä»¥é€šè¿‡åºåˆ—化æ¥å¤„ç†å¤šä¸ª +生产者，并通过åºåˆ—化æ¥å¤„ç†å¤šä¸ªæ¶ˆè´¹è€…。 + +.. Contents: + + (*) 什么是环形缓冲区？ + + (*) 测é‡2次幂缓冲区 + + (*) 内å˜å±éšœä¸ŽçŽ¯å½¢ç¼“冲区的结åˆä½¿ç”¨ + - 生产者 + - 消费者 + + (*) 延伸阅读 + + + +什么是环形缓冲区？ +================== + +首先，什么是环形缓冲区？环形缓冲区是具有固定的有é™å¤§å°çš„缓冲区，它有两个索引： + + (1) 'head'索引 - ç”Ÿäº§è€…å°†å…ƒç´ æ’入缓冲区的ä½ç½®ã€‚ + + (2) 'tail'索引 - 消费者在缓冲区ä¸æ‰¾åˆ°ä¸‹ä¸€ä¸ªå…ƒç´ çš„ä½ç½®ã€‚ + +通常，当tail指针ç‰äºŽhead指针时，表明缓冲区是空的；而当head指针比tail指针少一个时， +表明缓冲区是满的。 + +æ·»åŠ å…ƒç´ æ—¶ï¼Œé€’å¢žheadç´¢å¼•ï¼›åˆ é™¤å…ƒç´ æ—¶ï¼Œé€’å¢žtail索引。tail索引ä¸åº”该跳过head索引， +两个索引在到达缓冲区末端时都应该被赋值为0，从而å…许海é‡çš„æ•°æ®æµè¿‡ç¼“冲区。 + +é€šå¸¸æƒ…å†µä¸‹ï¼Œå…ƒç´ éƒ½æœ‰ç›¸åŒçš„å•å…ƒå¤§å°ï¼Œä½†è¿™å¹¶ä¸æ˜¯ä½¿ç”¨ä»¥ä¸‹æŠ€æœ¯çš„ä¸¥æ ¼è¦æ±‚。如果è¦åœ¨ç¼“ +冲区ä¸åŒ…å«å¤šä¸ªå…ƒç´ 或å¯å˜å¤§å°çš„å…ƒç´ ï¼Œåˆ™ç´¢å¼•å¯ä»¥å¢žåŠ 超过1，å‰æ是两个索引都没有超过 +å¦ä¸€ä¸ªã€‚然而，实现者必须å°å¿ƒï¼Œå› 为超过一个å•ä½å¤§å°çš„区域å¯èƒ½ä¼šè¦†ç›–缓冲区的末端并 +且缓冲区会被分æˆä¸¤æ®µã€‚ + +测é‡2次幂缓冲区 +=============== + +计算任æ„大å°çš„环形缓冲区的å 用或剩余容é‡é€šå¸¸æ˜¯ä¸€ä¸ªè´¹æ—¶çš„æ“作，需è¦ä½¿ç”¨æ¨¡ï¼ˆé™¤æ³•ï¼‰ +指令。但是如果缓冲区的大å°ä¸º2次幂，则å¯ä»¥ä½¿ç”¨æ›´å¿«çš„按ä½ä¸ŽæŒ‡ä»¤ä»£æ›¿ã€‚ + +Linuxæ供了一组用于处ç†2次幂环形缓冲区的å®ã€‚å¯ä»¥é€šè¿‡ä»¥ä¸‹æ–¹å¼ä½¿ç”¨:: + + #include <linux/circ_buf.h> + +这些å®åŒ…括： + + (#) 测é‡ç¼“冲区的剩余容é‡:: + + CIRC_SPACE(head_index, tail_index, buffer_size); + + 返回缓冲区[1]ä¸å¯æ’å…¥å…ƒç´ çš„å‰©ä½™ç©ºé—´å¤§å°ã€‚ + + + (#) 测é‡ç¼“冲区ä¸çš„最大连ç»ç«‹å³å¯ç”¨ç©ºé—´:: + + CIRC_SPACE_TO_END(head_index, tail_index, buffer_size); + + 返回缓冲区[1]ä¸å‰©ä½™çš„è¿žç»ç©ºé—´çš„大å°ï¼Œå…ƒç´ å¯ä»¥ç«‹å³æ’入其ä¸ï¼Œè€Œä¸å¿…绕回到缓冲 + 区的开头。 + + + (#) 测é‡ç¼“冲区的使用数:: + + CIRC_CNT(head_index, tail_index, buffer_size); + + 返回当å‰å 用缓冲区[2]çš„å…ƒç´ æ•°é‡ã€‚ + + + (#) 测é‡ç¼“冲区的连ç»ä½¿ç”¨æ•°:: + + CIRC_CNT_TO_END(head_index, tail_index, buffer_size); + + 返回å¯ä»¥ä»Žç¼“冲区ä¸æå–çš„è¿žç»å…ƒç´ [2]çš„æ•°é‡ï¼Œè€Œä¸å¿…绕回到缓冲区的开头。 + +这里的æ¯ä¸€ä¸ªå®å义上都会返回一个介于0å’Œbuffer_size-1之间的值，但是： + + (1) CIRC_SPACE*()是为了在生产者ä¸ä½¿ç”¨ã€‚对生产者æ¥è¯´ï¼Œå®ƒä»¬å°†è¿”回一个下é™ï¼Œå› 为生 + 产者控制ç€head索引，但消费者å¯èƒ½ä»ç„¶åœ¨å¦ä¸€ä¸ªCPU上耗尽缓冲区并移动tail索引。 + + 对消费者æ¥è¯´ï¼Œå®ƒå°†æ˜¾ç¤ºä¸€ä¸ªä¸Šé™ï¼Œå› 为生产者å¯èƒ½æ£å¿™äºŽè€—尽空间。 + + (2) CIRC_CNT*()是为了在消费者ä¸ä½¿ç”¨ã€‚对消费者æ¥è¯´ï¼Œå®ƒä»¬å°†è¿”回一个下é™ï¼Œå› 为消费 + 者控制ç€tail索引，但生产者å¯èƒ½ä»ç„¶åœ¨å¦ä¸€ä¸ªCPU上填充缓冲区并移动head索引。 + + 对于生产者，它将显示一个上é™ï¼Œå› 为消费者å¯èƒ½æ£å¿™äºŽæ¸…空缓冲区。 + + (3) 对于第三方æ¥è¯´ï¼Œç”Ÿäº§è€…和消费者对索引的写入顺åºæ˜¯æ— 法ä¿è¯çš„ï¼Œå› ä¸ºå®ƒä»¬æ˜¯ç‹¬ç«‹çš„ï¼Œ + 而且å¯èƒ½æ˜¯åœ¨ä¸åŒçš„CPU上进行的，所以在这ç§æƒ…况下的结果åªæ˜¯ä¸€ç§çŒœæµ‹ï¼Œç”šè‡³å¯èƒ½ + 是错误的。 + +内å˜å±éšœä¸ŽçŽ¯å½¢ç¼“冲区的结åˆä½¿ç”¨ +============================== + +通过将内å˜å±éšœä¸ŽçŽ¯å½¢ç¼“冲区结åˆä½¿ç”¨ï¼Œå¯ä»¥é¿å…以下需求： + + (1) 使用å•ä¸ªé”æ¥æŽ§åˆ¶å¯¹ç¼“冲区两端的访问，从而å…许åŒæ—¶å¡«å……å’Œæ¸…ç©ºç¼“å†²åŒºï¼›ä»¥åŠ + + (2) 使用原å计数器æ“作。 + +这有两个方é¢ï¼šå¡«å……缓冲区的生产者和清空缓冲区的消费者。在任何时候，åªåº”有一个生产 +者在填充缓冲区，åŒæ ·çš„也åªåº”有一个消费者在清空缓冲区，但åŒæ–¹å¯ä»¥åŒæ—¶æ“作。 + + +生产者 +------ + +生产者看起æ¥åƒè¿™æ ·:: + + spin_lock(&producer_lock); + + unsigned long head = buffer->head; + /* spin_unlock()和下一个spin_lock()æ供必è¦çš„排åºã€‚ */ + unsigned long tail = READ_ONCE(buffer->tail); + + if (CIRC_SPACE(head, tail, buffer->size) >= 1) { + /* æ·»åŠ ä¸€ä¸ªå…ƒç´ åˆ°ç¼“å†²åŒº */ + struct item *item = buffer[head]; + + produce_item(item); + + smp_store_release(buffer->head, + (head + 1) & (buffer->size - 1)); + + /* wake_up()将确ä¿åœ¨å”¤é†’任何人之å‰æ交head */ + wake_up(consumer); + } + + spin_unlock(&producer_lock); + +这将表明CPU必须在head索引使其对消费者å¯ç”¨ä¹‹å‰å†™å…¥æ–°é¡¹ç›®çš„内容，åŒæ—¶CPU必须在唤醒 +消费者之å‰å†™å…¥ä¿®æ”¹åŽçš„head索引。 + +请注æ„，wake_up()并ä¸ä¿è¯ä»»ä½•å½¢å¼çš„å±éšœï¼Œé™¤éžç¡®å®žå”¤é†’了æŸäº›ä¸œè¥¿ã€‚å› æ¤æˆ‘们ä¸èƒ½ä¾é +它æ¥è¿›è¡ŒæŽ’åºã€‚但是数组ä¸å§‹ç»ˆæœ‰ä¸€ä¸ªå…ƒç´ ç•™ç©ºï¼Œå› æ¤ç”Ÿäº§è€…å¿…é¡»äº§ç”Ÿä¸¤ä¸ªå…ƒç´ ï¼Œç„¶åŽæ‰å¯ +èƒ½ç ´å消费者当å‰æ£åœ¨è¯»å–çš„å…ƒç´ ã€‚åŒæ—¶ï¼Œæ¶ˆè´¹è€…è¿žç»è°ƒç”¨ä¹‹é—´æˆå¯¹çš„解é”-åŠ é”æ供了索引 +读å–ï¼ˆæŒ‡ç¤ºæ¶ˆè´¹è€…å·²æ¸…ç©ºç»™å®šå…ƒç´ ï¼‰å’Œç”Ÿäº§è€…å¯¹è¯¥ç›¸åŒå…ƒç´ 的写入之间的必è¦é¡ºåºã€‚ + + +消费者 +------ + +消费者看起æ¥åƒè¿™æ ·:: + + spin_lock(&consumer_lock); + + /* 读å–该索引处的内容之å‰ï¼Œå…ˆè¯»å–索引 */ + unsigned long head = smp_load_acquire(buffer->head); + unsigned long tail = buffer->tail; + + if (CIRC_CNT(head, tail, buffer->size) >= 1) { + + /* 从缓冲区ä¸æå–ä¸€ä¸ªå…ƒç´ */ + struct item *item = buffer[tail]; + + consume_item(item); + + /* 在递增tail之å‰å®Œæˆå¯¹æ述符的读å–。 */ + smp_store_release(buffer->tail, + (tail + 1) & (buffer->size - 1)); + } + + spin_unlock(&consumer_lock); + +这表明CPU在读å–æ–°å…ƒç´ ä¹‹å‰ç¡®ä¿ç´¢å¼•æ˜¯æœ€æ–°çš„，然åŽåœ¨å†™å…¥æ–°çš„尾指针之å‰åº”ç¡®ä¿CPU已完 +æˆè¯»å–è¯¥å…ƒç´ ï¼Œè¿™å°†æ“¦é™¤è¯¥å…ƒç´ ã€‚ + +请注æ„，使用READ_ONCE()å’Œsmp_load_acquire()æ¥è¯»å–åå‘（head）索引。这å¯ä»¥é˜²æ¢ç¼–译 +器丢弃并é‡æ–°åŠ 载其缓å˜å€¼ã€‚如果您能确定åå‘（head）索引将仅使用一次，则这ä¸æ˜¯å¿…é¡» +的。smp_load_acquire()还å¯ä»¥å¼ºåˆ¶CPU对åŽç»çš„内å˜å¼•ç”¨è¿›è¡ŒæŽ’åºã€‚类似地，两ç§ç®—法都使 +用smp_store_release()æ¥å†™å…¥çº¿ç¨‹çš„索引。这记录了我们æ£åœ¨å†™å…¥å¯ä»¥å¹¶å‘读å–的内容的事 +实，以防æ¢ç¼–è¯‘å™¨ç ´åå˜å‚¨ï¼Œå¹¶å¼ºåˆ¶å¯¹ä»¥å‰çš„访问进行排åºã€‚ + + +延伸阅读 +======== + +关于Linux的内å˜å±éšœè®¾æ–½çš„æ述，请查看Documentation/memory-barriers.txt。 diff --git a/Documentation/translations/zh_CN/core-api/generic-radix-tree.rst b/Documentation/translations/zh_CN/core-api/generic-radix-tree.rst new file mode 100644 index 000000000000..eacd1d2ebddc --- /dev/null +++ b/Documentation/translations/zh_CN/core-api/generic-radix-tree.rst @@ -0,0 +1,23 @@ +.. SPDX-License-Identifier: GPL-2.0+ + +.. include:: ../disclaimer-zh_CN.rst + +:Original: Documentation/core-api/generic-radix-tree.rst + +:翻译: + + 周彬彬 Binbin Zhou <zhoubinbin@loongson.cn> + +=================== +é€šç”¨åŸºæ•°æ ‘/稀ç–数组 +=================== + +é€šç”¨åŸºæ•°æ ‘/稀ç–数组的相关内容请è§include/linux/generic-radix-tree.h文件ä¸çš„ +“DOC: Generic radix trees/sparse arraysâ€ã€‚ + +é€šç”¨åŸºæ•°æ ‘å‡½æ•° +-------------- + +该APIåœ¨ä»¥ä¸‹å†…æ ¸ä»£ç ä¸: + +include/linux/generic-radix-tree.h diff --git a/Documentation/translations/zh_CN/core-api/idr.rst b/Documentation/translations/zh_CN/core-api/idr.rst new file mode 100644 index 000000000000..97a16e76b81b --- /dev/null +++ b/Documentation/translations/zh_CN/core-api/idr.rst @@ -0,0 +1,80 @@ +.. SPDX-License-Identifier: GPL-2.0+ + +.. include:: ../disclaimer-zh_CN.rst + +:Original: Documentation/core-api/idr.rst + +:翻译: + + 周彬彬 Binbin Zhou <zhoubinbin@loongson.cn> + +:æ ¡è¯‘: + + å¸å»¶è…¾ Yanteng Si <siyanteng@loongson.cn> + å´æƒ³æˆ Wu Xiangcheng <bobwxc@email.cn> + 时奎亮 Alex Shi <alexs@kernel.org> + +====== +IDåˆ†é… +====== + +:作者: Matthew Wilcox + +概述 +==== + +è¦è§£å†³çš„一个常è§é—®é¢˜æ˜¯åˆ†é…æ ‡è¯†ç¬¦ï¼ˆIDsï¼‰ï¼›å®ƒé€šå¸¸æ˜¯æ ‡è¯†äº‹ç‰©çš„æ•°å—。比如包括文件æè¿° +符ã€è¿›ç¨‹IDã€ç½‘络åè®®ä¸çš„æ•°æ®åŒ…æ ‡è¯†ç¬¦ã€SCSIæ ‡è®°å’Œè®¾å¤‡å®žä¾‹ç¼–å·ã€‚IDRå’ŒIDA为这个问题 +æ供了一个åˆç†çš„解决方案，以é¿å…æ¯ä¸ªäººéƒ½è‡ªåˆ›ã€‚IDRæ供将IDæ˜ å°„åˆ°æŒ‡é’ˆçš„èƒ½åŠ›ï¼Œè€ŒIDA +ä»…æä¾›ID分é…ï¼Œå› æ¤å†…å˜æ•ˆçŽ‡æ›´é«˜ã€‚ + +IDR接å£å·²ç»è¢«åºŸå¼ƒï¼Œè¯·ä½¿ç”¨ ``XArray`` 。 + +IDR的用法 +========= + +首先åˆå§‹åŒ–一个IDR，对于é™æ€åˆ†é…çš„IDR使用DEFINE_IDR()，或者对于动æ€åˆ†é…çš„IDR使用 +idr_init()。 + +您å¯ä»¥è°ƒç”¨idr_alloc()æ¥åˆ†é…一个未使用的ID。通过调用idr_find()查询与该ID相关的指针， +并通过调用idr_remove()释放该ID。 + +如果需è¦æ›´æ”¹ä¸Žä¸€ä¸ªID相关è”的指针，å¯ä»¥è°ƒç”¨idr_replace()ã€‚è¿™æ ·åšçš„一个常è§åŽŸå› 是通 +过将 ``NULL`` æŒ‡é’ˆä¼ é€’ç»™åˆ†é…函数æ¥ä¿ç•™ID；用ä¿ç•™çš„IDåˆå§‹åŒ–对象，最åŽå°†åˆå§‹åŒ–的对 +象æ’å…¥IDR。 + +一些用户需è¦åˆ†é…大于 ``INT_MAX`` çš„ID。到目å‰ä¸ºæ¢ï¼Œæ‰€æœ‰è¿™äº›ç”¨æˆ·éƒ½æ»¡è¶³ ``UINT_MAX`` +çš„é™åˆ¶ï¼Œä»–们使用idr_alloc_u32()。如果您需è¦è¶…出u32çš„ID，我们将与您åˆä½œä»¥æ»¡è¶³æ‚¨çš„ +需求。 + +如果需è¦æŒ‰é¡ºåºåˆ†é…ID，å¯ä»¥ä½¿ç”¨idr_alloc_cyclic()。处ç†è¾ƒå¤§æ•°é‡çš„ID时，IDR的效率会 +é™ä½Žï¼Œæ‰€ä»¥ä½¿ç”¨è¿™ä¸ªå‡½æ•°ä¼šæœ‰ä¸€ç‚¹ä»£ä»·ã€‚ + +è¦å¯¹IDR使用的所有指针进行æ“作，您å¯ä»¥ä½¿ç”¨åŸºäºŽå›žè°ƒçš„idr_for_each()或è¿ä»£å™¨æ ·å¼çš„ +idr_for_each_entry()。您å¯èƒ½éœ€è¦ä½¿ç”¨idr_for_each_entry_continue()æ¥ç»§ç»è¿ä»£ã€‚如果 +è¿ä»£å™¨ä¸ç¬¦åˆæ‚¨çš„需求，您也å¯ä»¥ä½¿ç”¨idr_get_next()。 + +当使用完IDRåŽï¼Œæ‚¨å¯ä»¥è°ƒç”¨idr_destroy()æ¥é‡Šæ”¾IDRå 用的内å˜ã€‚这并ä¸ä¼šé‡Šæ”¾IDR指å‘çš„ +å¯¹è±¡ï¼›å¦‚æžœæ‚¨æƒ³è¿™æ ·åšï¼Œè¯·ä½¿ç”¨å…¶ä¸ä¸€ä¸ªè¿ä»£å™¨æ¥æ‰§è¡Œæ¤æ“作。 + +您å¯ä»¥ä½¿ç”¨idr_is_empty()æ¥æŸ¥çœ‹å½“å‰æ˜¯å¦åˆ†é…了任何ID。 + +如果在从IDR分é…一个新ID时需è¦å¸¦é”，您å¯èƒ½éœ€è¦ä¼ 递一组é™åˆ¶æ€§çš„GFPæ ‡å¿—ï¼Œä½†è¿™å¯èƒ½å¯¼ +致IDRæ— æ³•åˆ†é…内å˜ã€‚为了解决该问题，您å¯ä»¥åœ¨èŽ·å–é”之å‰è°ƒç”¨idr_preload()，然åŽåœ¨åˆ† +é…之åŽè°ƒç”¨idr_preload_end()。 + +IDRåŒæ¥çš„相关内容请è§include/linux/idr.h文件ä¸çš„“DOC: idr syncâ€ã€‚ + +IDA的用法 +========= + +IDA的用法的相关内容请è§lib/idr.c文件ä¸çš„“DOC: IDA descriptionâ€ã€‚ + +函数和数æ®ç»“æž„ +============== + +该APIåœ¨ä»¥ä¸‹å†…æ ¸ä»£ç ä¸: + +include/linux/idr.h + +lib/idr.c diff --git a/Documentation/translations/zh_CN/core-api/index.rst b/Documentation/translations/zh_CN/core-api/index.rst index 8a94ad87465d..37756d240b5e 100644 --- a/Documentation/translations/zh_CN/core-api/index.rst +++ b/Documentation/translations/zh_CN/core-api/index.rst @@ -44,15 +44,15 @@ assoc_array xarray rbtree + idr + circular-buffers + generic-radix-tree + packing Todolist: - idr - circular-buffers - generic-radix-tree - packing this_cpu_ops timekeeping errseq diff --git a/Documentation/translations/zh_CN/core-api/packing.rst b/Documentation/translations/zh_CN/core-api/packing.rst new file mode 100644 index 000000000000..c0aab3a349d0 --- /dev/null +++ b/Documentation/translations/zh_CN/core-api/packing.rst @@ -0,0 +1,160 @@ +.. SPDX-License-Identifier: GPL-2.0+ + +.. include:: ../disclaimer-zh_CN.rst + +:Original: Documentation/core-api/packing.rst + +:翻译: + + 周彬彬 Binbin Zhou <zhoubinbin@loongson.cn> + +:æ ¡è¯‘: + + å¸å»¶è…¾ Yanteng Si <siyanteng@loongson.cn> + å´æƒ³æˆ Wu Xiangcheng <bobwxc@email.cn> + 时奎亮 Alex Shi <alexs@kernel.org> + +======================== +通用的ä½åŸŸæ‰“包和解包函数 +======================== + +问题陈述 +-------- + +ä½¿ç”¨ç¡¬ä»¶æ—¶ï¼Œå¿…é¡»åœ¨å‡ ç§ä¸Žå…¶äº¤äº’的方法之间进行选择。 + +å¯ä»¥å°†æŒ‡é’ˆæ˜ 射到在硬件设备的内å˜åŒºä¸Šç²¾å¿ƒè®¾è®¡çš„结构体，并将其å—段作为结构æˆå‘˜ï¼ˆå¯ +能声明为ä½åŸŸï¼‰è®¿é—®ã€‚但是由于CPU和硬件设备之间潜在的å—节顺åºä¸åŒ¹é…，以这ç§æ–¹å¼ç¼–写 +代ç 会é™ä½Žå…¶å¯ç§»æ¤æ€§ã€‚ + +æ¤å¤–，必须密切注æ„将硬件文档ä¸çš„寄å˜å™¨å®šä¹‰è½¬æ¢ä¸ºç»“æž„çš„ä½åŸŸç´¢å¼•ã€‚æ¤å¤–，一些硬件 +（通常是网络设备）倾å‘于以è¿å任何åˆç†å—边界（有时甚至是64ä½ï¼‰çš„æ–¹å¼å¯¹å…¶å¯„å˜å™¨å— +æ®µè¿›è¡Œåˆ†ç»„ã€‚è¿™å°±é€ æˆäº†ä¸å¾—ä¸åœ¨ç»“æž„ä¸å®šä¹‰å¯„å˜å™¨å—段的“高â€å’Œâ€œä½Žâ€éƒ¨åˆ†çš„ä¸ä¾¿ã€‚ + +结构域定义的更å¯é 的替代方法是通过移动适当数é‡çš„ä½æ¥æå–所需的å—段。但这ä»ç„¶ä¸èƒ½ +防æ¢å—节顺åºä¸åŒ¹é…，除éžæ‰€æœ‰å†…å˜è®¿é—®éƒ½æ˜¯é€å—节执行的。æ¤å¤–，代ç 很容易å˜å¾—æ‚ä¹±æ— +ç« ï¼ŒåŒæ—¶å¯èƒ½ä¼šåœ¨æ‰€éœ€çš„许多ä½ç§»æ“作ä¸ä¸¢å¤±ä¸€äº›é«˜å±‚次的想法。 + +许多驱动程åºé‡‡ç”¨äº†ä½ç§»çš„方法，然åŽè¯•å›¾ç”¨å®šåˆ¶çš„å®æ¥å‡å°‘æ‚ä¹±æ— ç« çš„ä¸œè¥¿ï¼Œä½†æ›´å¤šçš„æ—¶ +候，这些å®æ‰€é‡‡ç”¨çš„æ·å¾„ä¾æ—§å¦¨ç¢äº†ä»£ç 真æ£çš„å¯ç§»æ¤æ€§ã€‚ + +解决方案 +-------- + +该API涉åŠ2个基本æ“作： + + - 将一个CPUå¯ä½¿ç”¨çš„æ•°å—打包到内å˜ç¼“冲区ä¸ï¼ˆå…·æœ‰ç¡¬ä»¶çº¦æŸ/特殊性）。 + - 将内å˜ç¼“冲区（具有硬件约æŸ/特殊性）解压缩为一个CPUå¯ä½¿ç”¨çš„æ•°å—。 + +该APIæ供了对所述硬件约æŸå’Œç‰¹æ®Šæ€§ä»¥åŠCPUå—节åºçš„æŠ½è±¡ï¼Œå› æ¤è¿™ä¸¤è€…之间å¯èƒ½ä¸åŒ¹é…。 + +这些API函数的基本å•å…ƒæ˜¯u64。从CPU的角度æ¥çœ‹ï¼Œä½63总是æ„味ç€å—节7çš„ä½å移é‡7，尽管 +åªæ˜¯é€»è¾‘上的。问题是：我们将这个比特放在内å˜çš„什么ä½ç½®ï¼Ÿ + +以下示例介ç»äº†æ‰“包u64å—段的内å˜å¸ƒå±€ã€‚打包缓冲区ä¸çš„å—节å移é‡å§‹ç»ˆé»˜è®¤ä¸º0，1...7。 +示例显示的是逻辑å—节和ä½æ‰€åœ¨çš„ä½ç½®ã€‚ + +1. é€šå¸¸æƒ…å†µä¸‹ï¼ˆæ— ç‰¹æ®Šæ€§ï¼‰ï¼Œæˆ‘ä»¬ä¼šè¿™æ ·åšï¼š + +:: + + 63 62 61 60 59 58 57 56 55 54 53 52 51 50 49 48 47 46 45 44 43 42 41 40 39 38 37 36 35 34 33 32 + 7 6 5 4 + 31 30 29 28 27 26 25 24 23 22 21 20 19 18 17 16 15 14 13 12 11 10 9 8 7 6 5 4 3 2 1 0 + 3 2 1 0 + +也就是说，CPUå¯ä½¿ç”¨çš„u64çš„MSByte(7)ä½äºŽå†…å˜å移é‡0处，而u64çš„LSByte(0)ä½äºŽå†…å˜å移é‡7处。 + +这对应于大多数人认为的“大端â€ï¼Œå…¶ä¸ä½i对应于数å—2^i。这在代ç 注释ä¸ä¹Ÿç§°ä¸ºâ€œé€»è¾‘â€ç¬¦å·ã€‚ + + +2. 如果设置了QUIRK_MSB_ON_THE_RIGHT，我们按如下方å¼æ“作： + +:: + + 56 57 58 59 60 61 62 63 48 49 50 51 52 53 54 55 40 41 42 43 44 45 46 47 32 33 34 35 36 37 38 39 + 7 6 5 4 + 24 25 26 27 28 29 30 31 16 17 18 19 20 21 22 23 8 9 10 11 12 13 14 15 0 1 2 3 4 5 6 7 + 3 2 1 0 + +也就是说，QUIRK_MSB_ON_THE_RIGHTä¸ä¼šå½±å“å—节定ä½ï¼Œä½†ä¼šå转å—节内的ä½å移é‡ã€‚ + + +3. 如果设置了QUIRK_LITTLE_ENDIAN，我们按如下方å¼æ“作： + +:: + + 39 38 37 36 35 34 33 32 47 46 45 44 43 42 41 40 55 54 53 52 51 50 49 48 63 62 61 60 59 58 57 56 + 4 5 6 7 + 7 6 5 4 3 2 1 0 15 14 13 12 11 10 9 8 23 22 21 20 19 18 17 16 31 30 29 28 27 26 25 24 + 0 1 2 3 + +å› æ¤ï¼ŒQUIRK_LITTLE_ENDIANæ„味ç€åœ¨å†…å˜åŒºåŸŸå†…，æ¯ä¸ª4å—节的å—çš„æ¯ä¸ªå—节都被放置在与 +该å—的边界相比的镜åƒä½ç½®ã€‚ + + +4. 如果设置了QUIRK_MSB_ON_THE_RIGHTå’ŒQUIRK_LITTLE_ENDIANï¼Œæˆ‘ä»¬è¿™æ ·åšï¼š + +:: + + 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 + 4 5 6 7 + 0 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 + 0 1 2 3 + + +5. 如果åªè®¾ç½®äº†QUIRK_LSW32_IS_FIRSTï¼Œæˆ‘ä»¬è¿™æ ·åšï¼š + +:: + + 31 30 29 28 27 26 25 24 23 22 21 20 19 18 17 16 15 14 13 12 11 10 9 8 7 6 5 4 3 2 1 0 + 3 2 1 0 + 63 62 61 60 59 58 57 56 55 54 53 52 51 50 49 48 47 46 45 44 43 42 41 40 39 38 37 36 35 34 33 32 + 7 6 5 4 + +在这ç§æƒ…况下，8å—节内å˜åŒºåŸŸè§£é‡Šå¦‚下：å‰4å—节对应最ä¸é‡è¦çš„4å—节的å—，åŽ4å—节对应 +æ›´é‡è¦çš„4å—节的å—。 + +6. 如果设置了QUIRK_LSW32_IS_FIRSTå’ŒQUIRK_MSB_ON_THE_RIGHTï¼Œæˆ‘ä»¬è¿™æ ·åšï¼š + +:: + + 24 25 26 27 28 29 30 31 16 17 18 19 20 21 22 23 8 9 10 11 12 13 14 15 0 1 2 3 4 5 6 7 + 3 2 1 0 + 56 57 58 59 60 61 62 63 48 49 50 51 52 53 54 55 40 41 42 43 44 45 46 47 32 33 34 35 36 37 38 39 + 7 6 5 4 + + +7. 如果设置了QUIRK_LSW32_IS_FIRSTå’ŒQUIRK_LITTLE_ENDIAN，则如下所示： + +:: + + 7 6 5 4 3 2 1 0 15 14 13 12 11 10 9 8 23 22 21 20 19 18 17 16 31 30 29 28 27 26 25 24 + 0 1 2 3 + 39 38 37 36 35 34 33 32 47 46 45 44 43 42 41 40 55 54 53 52 51 50 49 48 63 62 61 60 59 58 57 56 + 4 5 6 7 + + +8. 如果设置了QUIRK_LSW32_IS_FIRST，QUIRK_LITTLE_ENDIANå’ŒQUIRK_MSB_ON_THE_RIGHT， + 则如下所示： + +:: + + 0 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 + 0 1 2 3 + 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 + 4 5 6 7 + + +我们总是认为我们的å移é‡å¥½åƒæ²¡æœ‰ç‰¹æ®Šæ€§ï¼Œç„¶åŽåœ¨è®¿é—®å†…å˜åŒºåŸŸä¹‹å‰ç¿»è¯‘它们。 + +预期用途 +-------- + +选择使用该API的驱动程åºé¦–先需è¦ç¡®å®šä¸Šè¿°3ç§quirk组åˆï¼ˆå…±8ç§ï¼‰ä¸çš„哪一ç§ä¸Žç¡¬ä»¶æ–‡æ¡£ +ä¸æ述的相匹é…。然åŽï¼Œä»–们应该å°è£…packing()函数，创建一个新的xxx_packing()，使用 +适当的QUIRK_* one-hot ä½é›†åˆæ¥è°ƒç”¨å®ƒã€‚ + +packing()函数返回一个int类型的错误ç ，以防æ¢ç¨‹åºå‘˜ä½¿ç”¨ä¸æ£ç¡®çš„APIã€‚è¿™äº›é”™è¯¯é¢„è®¡ä¸ +会在è¿è¡Œæ—¶å‘ç”Ÿï¼Œå› æ¤xxx_packing()返回void并简å•åœ°æŽ¥å—这些错误是åˆç†çš„。它å¯ä»¥é€‰æ‹© +è½¬å‚¨æ ˆæˆ–æ‰“å°é”™è¯¯æ述。 diff --git a/Documentation/translations/zh_CN/devicetree/changesets.rst b/Documentation/translations/zh_CN/devicetree/changesets.rst new file mode 100644 index 000000000000..2ace05f3c377 --- /dev/null +++ b/Documentation/translations/zh_CN/devicetree/changesets.rst @@ -0,0 +1,37 @@ +.. SPDX-License-Identifier: GPL-2.0 +.. include:: ../disclaimer-zh_CN.rst + +:Original: Documentation/Devicetree/changesets.rst + +:翻译: + + å¸å»¶è…¾ Yanteng Si <siyanteng@loongson.cn> + +:æ ¡è¯‘: + + +============ +è®¾å¤‡æ ‘å˜æ›´é›† +============ + +è®¾å¤‡æ ‘å˜æ›´é›†æ˜¯ä¸€ç§æ–¹æ³•ï¼Œå®ƒå…è®¸äººä»¬ä»¥è¿™æ ·ä¸€ç§æ–¹å¼åœ¨å®žæ—¶æ ‘ä¸ä½¿ç”¨å˜åŒ–，å³è¦ä¹ˆä½¿ç”¨å…¨éƒ¨çš„ +å˜åŒ–，è¦ä¹ˆä¸ä½¿ç”¨ã€‚如果在使用å˜æ›´é›†çš„过程ä¸å‘ç”Ÿé”™è¯¯ï¼Œé‚£ä¹ˆæ ‘å°†è¢«å›žæ»šåˆ°ä¹‹å‰çš„状æ€ã€‚一个 +å˜æ›´é›†ä¹Ÿå¯ä»¥åœ¨ä½¿ç”¨åŽè¢«åˆ 除。 + +当一个å˜æ›´é›†è¢«ä½¿ç”¨æ—¶ï¼Œæ‰€æœ‰çš„改å˜åœ¨å‘出OF_RECONFIG通知器之å‰è¢«ä¸€æ¬¡æ€§ä½¿ç”¨åˆ°æ ‘上。这是 +为了让接收者在收到通知时看到一个完整的ã€ä¸€è‡´çš„æ ‘çš„çŠ¶æ€ã€‚ + +一个å˜åŒ–集的顺åºå¦‚下。 + +1. of_changeset_init() - åˆå§‹åŒ–一个å˜æ›´é›†ã€‚ + +2. 一些DTæ ‘å˜åŒ–的调用，of_changeset_attach_node(), of_changeset_detach_node(), + of_changeset_add_property(), of_changeset_remove_property, + of_changeset_update_property()æ¥å‡†å¤‡ä¸€ç»„å˜æ›´ã€‚æ¤æ—¶ä¸ä¼šå¯¹æ´»åŠ¨æ ‘åšä»»ä½•å˜æ›´ã€‚所有 + çš„å˜æ›´æ“作都记录在of_changesetçš„ `entries` 列表ä¸ã€‚ + +3. of_changeset_apply() - å°†å˜æ›´ä½¿ç”¨åˆ°æ ‘上。è¦ä¹ˆæ•´ä¸ªå˜æ›´é›†è¢«ä½¿ç”¨ï¼Œè¦ä¹ˆå¦‚果有错误， + æ ‘ä¼šè¢«æ¢å¤åˆ°ä¹‹å‰çš„状æ€ã€‚æ ¸å¿ƒé€šè¿‡é”ç¡®ä¿æ£ç¡®çš„顺åºã€‚如果需è¦çš„è¯ï¼Œå¯ä»¥ä½¿ç”¨ä¸€ä¸ªè§£é”çš„ + __of_changeset_apply版本。 + +如果一个æˆåŠŸä½¿ç”¨çš„å˜æ›´é›†éœ€è¦è¢«åˆ 除，å¯ä»¥ç”¨of_changeset_revert()æ¥å®Œæˆã€‚ diff --git a/Documentation/translations/zh_CN/devicetree/dynamic-resolution-notes.rst b/Documentation/translations/zh_CN/devicetree/dynamic-resolution-notes.rst new file mode 100644 index 000000000000..115190341305 --- /dev/null +++ b/Documentation/translations/zh_CN/devicetree/dynamic-resolution-notes.rst @@ -0,0 +1,31 @@ +.. SPDX-License-Identifier: GPL-2.0 +.. include:: ../disclaimer-zh_CN.rst + +:Original: Documentation/Devicetree/dynamic-resolution-notes.rst + +:翻译: + + å¸å»¶è…¾ Yanteng Si <siyanteng@loongson.cn> + +:æ ¡è¯‘: + +======================== +Devicetree动æ€è§£æžå™¨è¯´æ˜Ž +======================== + +本文æè¿°äº†å†…æ ¸å†…DeviceTree解æžå™¨çš„实现，它ä½äºŽdrivers/of/resolver.cä¸ã€‚ + +解æžå™¨å¦‚何工作？ +---------------- + +解æžå™¨è¢«èµ‹äºˆä¸€ä¸ªä»»æ„çš„æ ‘ä½œä¸ºè¾“å…¥ï¼Œè¯¥æ ‘ç”¨é€‚å½“çš„dtc选项编译，并有一个/plugin/æ ‡ç¾ã€‚这就产 +生了适当的__fixups__å’Œ__local_fixups__节点。 + +解æžå™¨ä¾æ¬¡é€šè¿‡ä»¥ä¸‹æ¥éª¤å·¥ä½œ: + +1. ä»Žå®žæ—¶æ ‘ä¸èŽ·å–æœ€å¤§çš„è®¾å¤‡æ ‘phandle值 + 1. +2. è°ƒæ•´æ ‘çš„æ‰€æœ‰æœ¬åœ° phandles，以解决这个é‡ã€‚ +3. 使用 __local__fixups__ 节点信æ¯ä»¥ç›¸åŒçš„é‡è°ƒæ•´æ‰€æœ‰æœ¬åœ°å¼•ç”¨ã€‚ +4. 对于__fixups__节点ä¸çš„æ¯ä¸ªå±žæ€§ï¼Œæ‰¾åˆ°å®ƒåœ¨å®žæ—¶æ ‘ä¸å¼•ç”¨çš„节点。这是用æ¥æ ‡è®°è¯¥èŠ‚ç‚¹çš„æ ‡ç¾ã€‚ +5. 检索fixupçš„ç›®æ ‡çš„phandle。 +6. 对于属性ä¸çš„æ¯ä¸ªfixup，找到节点:属性:å移的ä½ç½®ï¼Œå¹¶ç”¨phandle值替æ¢å®ƒã€‚ diff --git a/Documentation/translations/zh_CN/devicetree/index.rst b/Documentation/translations/zh_CN/devicetree/index.rst index 3fc355fe0037..7451dbfdd3e5 100644 --- a/Documentation/translations/zh_CN/devicetree/index.rst +++ b/Documentation/translations/zh_CN/devicetree/index.rst @@ -24,21 +24,16 @@ Open Firmware å’Œ Devicetree usage-model of_unittest - -Todolist: - -* kernel-api + kernel-api Devicetree Overlays =================== .. toctree:: :maxdepth: 1 -Todolist: - -* changesets -* dynamic-resolution-notes -* overlay-notes + changesets + dynamic-resolution-notes + overlay-notes Devicetree Bindings =================== diff --git a/Documentation/translations/zh_CN/devicetree/kernel-api.rst b/Documentation/translations/zh_CN/devicetree/kernel-api.rst new file mode 100644 index 000000000000..6aa3b685494e --- /dev/null +++ b/Documentation/translations/zh_CN/devicetree/kernel-api.rst @@ -0,0 +1,58 @@ +.. SPDX-License-Identifier: GPL-2.0 +.. include:: ../disclaimer-zh_CN.rst + +:Original: Documentation/Devicetree/kernel-api.rst + +:翻译: + + å¸å»¶è…¾ Yanteng Si <siyanteng@loongson.cn> + +:æ ¡è¯‘: + + +================= +å†…æ ¸ä¸çš„è®¾å¤‡æ ‘API +================= + +æ ¸å¿ƒå‡½æ•° +-------- + +该APIåœ¨ä»¥ä¸‹å†…æ ¸ä»£ç ä¸: + +drivers/of/base.c + +include/linux/of.h + +drivers/of/property.c + +include/linux/of_graph.h + +drivers/of/address.c + +drivers/of/irq.c + +drivers/of/fdt.c + +驱动模型函数 +------------ + +该APIåœ¨ä»¥ä¸‹å†…æ ¸ä»£ç ä¸: + +include/linux/of_device.h + +drivers/of/device.c + +include/linux/of_platform.h + +drivers/of/platform.c + +覆盖和动æ€DT函数 +---------------- + +该APIåœ¨ä»¥ä¸‹å†…æ ¸ä»£ç ä¸: + +drivers/of/resolver.c + +drivers/of/dynamic.c + +drivers/of/overlay.c diff --git a/Documentation/translations/zh_CN/devicetree/overlay-notes.rst b/Documentation/translations/zh_CN/devicetree/overlay-notes.rst new file mode 100644 index 000000000000..1bd482cb0a1b --- /dev/null +++ b/Documentation/translations/zh_CN/devicetree/overlay-notes.rst @@ -0,0 +1,140 @@ +.. SPDX-License-Identifier: GPL-2.0 +.. include:: ../disclaimer-zh_CN.rst + +:Original: Documentation/Devicetree/overlay-notes.rst + +:翻译: + + å¸å»¶è…¾ Yanteng Si <siyanteng@loongson.cn> + +:æ ¡è¯‘: + +============== +è®¾å¤‡æ ‘è¦†ç›–è¯´æ˜Ž +============== + +本文档æ述了drivers/of/overlay.cä¸çš„å†…æ ¸å†…è®¾å¤‡æ ‘è¦†ç›–åŠŸèƒ½çš„å®žçŽ°ï¼Œæ˜¯ +Documentation/devicetree/dynamic-resolution-notes.rst[1]çš„é…套文档。 + +覆盖如何工作 +------------ + +è®¾å¤‡æ ‘è¦†ç›–çš„ç›®çš„æ˜¯ä¿®æ”¹å†…æ ¸çš„å®žæ—¶æ ‘ï¼Œå¹¶ä½¿ä¿®æ”¹ä»¥åæ˜ å˜åŒ–çš„æ–¹å¼å½±å“å†…æ ¸çš„çŠ¶æ€ã€‚ +ç”±äºŽå†…æ ¸ä¸»è¦å¤„ç†çš„是设备，任何新的设备节点如果导致一个活动的设备，就应该创建它， +而如果设备节点被ç¦ç”¨æˆ–è¢«å…¨éƒ¨åˆ é™¤ï¼Œå—å½±å“的设备应该被å–消注册。 + +让我们举个例å，我们有一个fooæ¿ï¼Œå®ƒçš„åŸºæœ¬æ ‘å½¢å›¾å¦‚ä¸‹:: + + ---- foo.dts --------------------------------------------------------------- + /* FOOå¹³å° */ + /dts-v1/; + / { + compatible = "corp,foo"; + + /* å…±äº«çš„èµ„æº */ + res: res { + }; + + /* 芯片上的外围设备 */ + ocp: ocp { + /* 总是被实例化的外围设备 */ + peripheral1 { ... }; + }; + }; + ---- foo.dts --------------------------------------------------------------- + +覆盖bar.dts, +:: + + ---- bar.dts - æŒ‰æ ‡ç¾è¦†ç›–ç›®æ ‡ä½ç½® ---------------------------- + /dts-v1/; + /æ’件/; + &ocp { + /* bar外围 */ + bar { + compatible = "corp,bar"; + ... /* å„ç§å±žæ€§å’Œå节点 */ + }; + }; + ---- bar.dts --------------------------------------------------------------- + +å½“åŠ è½½ï¼ˆå¹¶æŒ‰ç…§[1]ä¸æè¿°çš„æ–¹å¼è§£å†³ï¼‰æ—¶ï¼Œåº”该产生foo+bar.dts:: + + ---- foo+bar.dts ----------------------------------------------------------- + /* FOOå¹³å° + bar外围 */ + / { + compatible = "corp,foo"; + + /* å…±äº«èµ„æº */ + res: res { + }; + + /* 芯片上的外围设备 */ + ocp: ocp { + /* 总是被实例化的外围设备 */ + peripheral1 { ... }; + + /* bar外围 */ + bar { + compatible = "corp,bar"; + ... /* å„ç§å±žæ€§å’Œå节点 */ + }; + }; + }; + ---- foo+bar.dts ----------------------------------------------------------- + +作为覆盖的结果，已ç»åˆ›å»ºäº†ä¸€ä¸ªæ–°çš„设备节点（barï¼‰ï¼Œå› æ¤å°†æ³¨å†Œä¸€ä¸ªbarå¹³å°è®¾å¤‡ï¼Œ +å¦‚æžœåŠ è½½äº†åŒ¹é…的设备驱动程åºï¼Œå°†æŒ‰é¢„期创建设备。 + +如果基础DTä¸æ˜¯ç”¨-@选项编译的，那么“&ocpâ€æ ‡ç¾å°†ä¸èƒ½ç”¨äºŽå°†è¦†ç›–节点解æžåˆ°åŸºç¡€ +DTä¸çš„适当ä½ç½®ã€‚在这ç§æƒ…况下，å¯ä»¥æä¾›ç›®æ ‡è·¯å¾„ã€‚é€šè¿‡æ ‡ç¾çš„ç›®æ ‡ä½ç½®çš„è¯æ³•æ˜¯æ¯” +è¾ƒå¥½çš„ï¼Œå› ä¸ºä¸ç®¡æ ‡ç¾åœ¨DTä¸å‡ºçŽ°åœ¨å“ªé‡Œï¼Œè¦†ç›–都å¯ä»¥è¢«åº”用到任何包å«æ ‡ç¾çš„基础DT上。 + +上é¢çš„bar.dts例åè¢«ä¿®æ”¹ä¸ºä½¿ç”¨ç›®æ ‡è·¯å¾„è¯æ³•ï¼Œå³ä¸º:: + + ---- bar.dts - é€šè¿‡æ˜Žç¡®çš„è·¯å¾„è¦†ç›–ç›®æ ‡ä½ç½® -------------------- + /dts-v1/; + /æ’件/; + &{/ocp} { + /* bar外围 */ + bar { + compatible = "corp,bar"; + ... /* å„ç§å¤–围设备和å节点 */ + } + }; + ---- bar.dts --------------------------------------------------------------- + + +å†…æ ¸ä¸å…³äºŽè¦†ç›–çš„API +------------------- + +该API相当容易使用。 + +1) 调用of_overlay_fdt_apply()æ¥åˆ›å»ºå’Œåº”用一个覆盖的å˜æ›´é›†ã€‚返回值是一个 + 错误或一个识别这个覆盖的cookie。 + +2) 调用of_overlay_remove()æ¥åˆ 除和清ç†å…ˆå‰é€šè¿‡è°ƒç”¨of_overlay_fdt_apply() + 而创建的覆盖å˜æ›´é›†ã€‚ä¸å…è®¸åˆ é™¤ä¸€ä¸ªè¢«å¦ä¸€ä¸ªè¦†ç›–的覆盖å˜åŒ–集。 + +最åŽï¼Œå¦‚æžœä½ éœ€è¦ä¸€æ¬¡æ€§åˆ 除所有的覆盖，åªéœ€è°ƒç”¨of_overlay_remove_all()， +它将以æ£ç¡®çš„顺åºåˆ 除æ¯ä¸€ä¸ªè¦†ç›–。 + +ä½ å¯ä»¥é€‰æ‹©æ³¨å†Œåœ¨è¦†ç›–æ“作ä¸è¢«è°ƒç”¨çš„é€šçŸ¥å™¨ã€‚è¯¦è§ +of_overlay_notifier_register/unregisterå’Œenum of_overlay_notify_action。 + +OF_OVERLAY_PRE_APPLYã€OF_OVERLAY_POST_APPLY或OF_OVERLAY_PRE_REMOVE +的通知器回调å¯ä»¥å˜å‚¨æŒ‡å‘覆盖层ä¸çš„è®¾å¤‡æ ‘èŠ‚ç‚¹æˆ–å…¶å†…å®¹çš„æŒ‡é’ˆï¼Œä½†è¿™äº›æŒ‡é’ˆä¸èƒ½æŒ +ç»åˆ°OF_OVERLAY_POST_REMOVE的通知器回调。在OF_OVERLAY_POST_REMOVE通 +知器被调用åŽï¼ŒåŒ…å«è¦†ç›–层的内å˜å°†è¢«kfree()ed。请注æ„，å³ä½¿OF_OVERLAY_POST_REMOVE +的通知器返回错误，内å˜ä¹Ÿä¼šè¢«kfree()ed。 + +drivers/of/dynamic.cä¸çš„å˜æ›´é›†é€šçŸ¥å™¨æ˜¯ç¬¬äºŒç§ç±»åž‹çš„通知器，å¯ä»¥é€šè¿‡åº”用或移除 +覆盖层æ¥è§¦å‘。这些通知器ä¸å…许在覆盖层或其内容ä¸å˜å‚¨æŒ‡å‘è®¾å¤‡æ ‘èŠ‚ç‚¹çš„æŒ‡é’ˆã€‚å½“åŒ…å« +覆盖层的内å˜å› 移除覆盖层而被释放时，覆盖层代ç 并ä¸èƒ½é˜²æ¢è¿™ç±»æŒ‡é’ˆä»ç„¶æœ‰æ•ˆã€‚ + +任何其他ä¿ç•™æŒ‡å‘覆盖层节点或数æ®çš„指针的代ç éƒ½è¢«è®¤ä¸ºæ˜¯ä¸€ä¸ªé”™è¯¯ï¼Œå› ä¸ºåœ¨ç§»é™¤è¦†ç›–å±‚ +åŽï¼Œè¯¥æŒ‡é’ˆå°†æŒ‡å‘已释放的内å˜ã€‚ + +覆盖层的用户必须特别注æ„系统上å‘生的整体æ“作，以确ä¿å…¶ä»–å†…æ ¸ä»£ç ä¸ä¿ç•™ä»»ä½•æŒ‡å‘覆 +盖层节点或数æ®çš„æŒ‡é’ˆã€‚ä»»ä½•æ— æ„ä¸ä½¿ç”¨è¿™ç§æŒ‡é’ˆçš„例å是，如果一个驱动或å系统模å—在 +应用了覆盖åŽè¢«åŠ 载，并且该驱动或å系统扫æäº†æ•´ä¸ªè®¾å¤‡æ ‘æˆ–å…¶å¤§éƒ¨åˆ†ï¼ŒåŒ…æ‹¬è¦†ç›–èŠ‚ç‚¹ã€‚ diff --git a/Documentation/translations/zh_CN/driver-api/gpio/index.rst b/Documentation/translations/zh_CN/driver-api/gpio/index.rst new file mode 100644 index 000000000000..9ab64e94aced --- /dev/null +++ b/Documentation/translations/zh_CN/driver-api/gpio/index.rst @@ -0,0 +1,69 @@ +.. SPDX-License-Identifier: GPL-2.0 + +.. include:: ../../disclaimer-zh_CN.rst + +:Original: Documentation/driver-api/gpio/index.rst + +:翻译: + + å¸å»¶è…¾ Yanteng Si <siyanteng@loongson.cn> + +:æ ¡è¯‘: + +======================= +通用型输入/输出（GPIO） +======================= + +目录: + +.. toctree:: + :maxdepth: 2 + + legacy + +Todolist: + +* intro +* using-gpio +* driver +* consumer +* board +* drivers-on-gpio +* bt8xxgpio + +æ ¸å¿ƒ +==== + +该APIåœ¨ä»¥ä¸‹å†…æ ¸ä»£ç ä¸: + +include/linux/gpio/driver.h + +drivers/gpio/gpiolib.c + +ACPIæ”¯æŒ +======== + +该APIåœ¨ä»¥ä¸‹å†…æ ¸ä»£ç ä¸: + +drivers/gpio/gpiolib-acpi.c + +è®¾å¤‡æ ‘æ”¯æŒ +========== + +该APIåœ¨ä»¥ä¸‹å†…æ ¸ä»£ç ä¸: + +drivers/gpio/gpiolib-of.c + +设备管ç†æ”¯æŒ +============ + +该APIåœ¨ä»¥ä¸‹å†…æ ¸ä»£ç ä¸: + +drivers/gpio/gpiolib-devres.c + +sysfs帮助（函数） +================= + +该APIåœ¨ä»¥ä¸‹å†…æ ¸ä»£ç ä¸: + +drivers/gpio/gpiolib-sysfs.c diff --git a/Documentation/translations/zh_CN/gpio.txt b/Documentation/translations/zh_CN/driver-api/gpio/legacy.rst index a23ee14fc927..6399521d0548 100644 --- a/Documentation/translations/zh_CN/gpio.txt +++ b/Documentation/translations/zh_CN/driver-api/gpio/legacy.rst @@ -1,39 +1,28 @@ -Chinese translated version of Documentation/admin-guide/gpio +.. SPDX-License-Identifier: GPL-2.0 -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 -Maintainer: Grant Likely <grant.likely@secretlab.ca> - Linus Walleij <linus.walleij@linaro.org> -Chinese maintainer: Fu Wei <tekkamanninja@gmail.com> ---------------------------------------------------------------------- -Documentation/admin-guide/gpio çš„ä¸æ–‡ç¿»è¯‘ +:Original: Documentation/driver-api/gpio/legacy.rst -如果想评论或更新本文的内容，请直接è”ç³»åŽŸæ–‡æ¡£çš„ç»´æŠ¤è€…ã€‚å¦‚æžœä½ ä½¿ç”¨è‹±æ–‡ -交æµæœ‰å›°éš¾çš„è¯ï¼Œä¹Ÿå¯ä»¥å‘ä¸æ–‡ç‰ˆç»´æŠ¤è€…求助。如果本翻译更新ä¸åŠæ—¶æˆ–者翻 -译å˜åœ¨é—®é¢˜ï¼Œè¯·è”ç³»ä¸æ–‡ç‰ˆç»´æŠ¤è€…。 -英文版维护者： Grant Likely <grant.likely@secretlab.ca> - Linus Walleij <linus.walleij@linaro.org> -ä¸æ–‡ç‰ˆç»´æŠ¤è€…： å‚…ç‚œ Fu Wei <tekkamanninja@gmail.com> -ä¸æ–‡ç‰ˆç¿»è¯‘者： å‚…ç‚œ Fu Wei <tekkamanninja@gmail.com> -ä¸æ–‡ç‰ˆæ ¡è¯‘者： å‚…ç‚œ Fu Wei <tekkamanninja@gmail.com> +:翻译: + å‚…ç‚œ Fu Wei <tekkamanninja@gmail.com> + å¸å»¶è…¾ Yanteng Si <siyanteng@loongson.cn> -以下为æ£æ–‡ ---------------------------------------------------------------------- -GPIO æŽ¥å£ +:æ ¡è¯‘: -本文档æ供了一个在Linux下访问GPIO的公约概述。 + +ä¼ ç»ŸGPIOæŽ¥å£ +============ + +本文档概述了Linux下的GPIO访问公约。 这些函数以 gpio_* 作为å‰ç¼€ã€‚其他的函数ä¸å…è®¸ä½¿ç”¨è¿™æ ·çš„å‰ç¼€æˆ–相关的 __gpio_* å‰ç¼€ã€‚ -什么是GPIO? -========== +什么是GPIO？ +============ "通用输入/输出å£"(GPIO)是一个çµæ´»çš„由软件控制的数å—ä¿¡å·ã€‚ä»–ä»¬å¯ ç”±å¤šç§èŠ¯ç‰‡æä¾›,且对于从事嵌入å¼å’Œå®šåˆ¶ç¡¬ä»¶çš„ Linux å¼€å‘者æ¥è¯´æ˜¯ 比较熟悉。æ¯ä¸ªGPIO 都代表一个连接到特定引脚或çƒæ …阵列(BGA)å°è£…ä¸ @@ -99,6 +88,7 @@ GPIO 公约 æ ‡è¯† GPIO --------- + GPIO æ˜¯é€šè¿‡æ— ç¬¦å·æ•´åž‹æ¥æ ‡è¯†çš„,范围是 0 到 MAX_INT。ä¿ç•™â€œè´Ÿâ€æ•° 用于其他目的,ä¾‹å¦‚æ ‡è¯†ä¿¡å·â€œåœ¨è¿™ä¸ªæ¿å上ä¸å¯ç”¨â€æˆ–指示错误。未接触底层 硬件的代ç 会忽略这些整数。 @@ -115,7 +105,7 @@ FPGA 的特定æ¿å上使用 80-95。编å·ä¸ä¸€å®šè¦è¿žç»,那些平å°ä¸ï¼ å¦‚æžœä½ è¦åˆå§‹åŒ–ä¸€ä¸ªå¸¦æœ‰æ— æ•ˆ GPIO ç¼–å·çš„结构体,å¯ä»¥ä½¿ç”¨ä¸€äº›è´Ÿç¼–ç (如"-EINVAL")，那将使其永远ä¸ä¼šæ˜¯æœ‰æ•ˆã€‚æ¥æµ‹è¯•è¿™æ ·ä¸€ä¸ªç»“构体ä¸çš„ç¼–å· -是å¦å…³è”一个 GPIOï¼Œä½ å¯ä½¿ç”¨ä»¥ä¸‹æ–言: +是å¦å…³è”一个 GPIOï¼Œä½ å¯ä½¿ç”¨ä»¥ä¸‹æ–言:: int gpio_is_valid(int number); @@ -128,11 +118,12 @@ FPGA 的特定æ¿å上使用 80-95。编å·ä¸ä¸€å®šè¦è¿žç»,那些平å°ä¸ï¼ 使用 GPIO --------- + 对于一个 GPIO，系统应该åšçš„第一件事情就是通过 gpio_request() 函数分é…它，è§ä¸‹æ–‡ã€‚ 接下æ¥æ˜¯è®¾ç½®I/Oæ–¹å‘，这通常是在æ¿çº§å¯åŠ¨ä»£ç ä¸ä¸ºæ‰€ä½¿ç”¨çš„ GPIO 设置 -platform_device 时完æˆã€‚ +platform_device 时完æˆ:: /* 设置为输入或输出, 返回 0 或负的错误代ç */ int gpio_direction_input(unsigned gpio); @@ -157,12 +148,13 @@ get/set(获å–/设置)函数调用没法返回错误,且有å¯èƒ½æ˜¯é…置错误 访问自旋é”安全的 GPIO -------------------- +--------------------- + 大多数 GPIO 控制器å¯ä»¥é€šè¿‡å†…å˜è¯»/写指令æ¥è®¿é—®ã€‚这些指令ä¸ä¼šä¼‘çœ ,å¯ä»¥ 安全地在硬(éžçº¿ç¨‹)ä¸æ–例程和类似的上下文ä¸å®Œæˆã€‚ 对于那些用 gpio_cansleep()测试总是返回失败的 GPIO(è§ä¸‹æ–‡)，使用 -以下的函数访问: +以下的函数访问:: /* GPIO 输入:返回零或éžé›¶ */ int gpio_get_value(unsigned gpio); @@ -188,17 +180,18 @@ GPIO值是布尔值，零表示低电平，éžé›¶è¡¨ç¤ºé«˜ç”µå¹³ã€‚当读å–一ä 访问å¯èƒ½ä¼‘çœ çš„ GPIO ------------------ +------------------- + æŸäº› GPIO 控制器必须通过基于总线(如 I2C 或 SPI)的消æ¯è®¿é—®ã€‚读或写这些 GPIO 值的命令需è¦ç‰å¾…其信æ¯æŽ’到队首æ‰å‘é€å‘½ä»¤ï¼Œå†èŽ·å¾—å…¶åé¦ˆã€‚æœŸé—´éœ€è¦ ä¼‘çœ ï¼Œè¿™ä¸èƒ½åœ¨ IRQ 例程(ä¸æ–上下文)ä¸æ‰§è¡Œã€‚ 支æŒæ¤ç±» GPIO çš„å¹³å°é€šè¿‡ä»¥ä¸‹å‡½æ•°è¿”回éžé›¶å€¼æ¥åŒºåˆ†å‡ºè¿™ç§ GPIO。(æ¤å‡½æ•°éœ€è¦ -一个之å‰é€šè¿‡ gpio_request 分é…到的有效 GPIO ç¼–å·): +一个之å‰é€šè¿‡ gpio_request 分é…到的有效 GPIO ç¼–å·):: int gpio_cansleep(unsigned gpio); -ä¸ºäº†è®¿é—®è¿™ç§ GPIO,å†…æ ¸å®šä¹‰äº†ä¸€å¥—ä¸åŒçš„函数: +ä¸ºäº†è®¿é—®è¿™ç§ GPIO,å†…æ ¸å®šä¹‰äº†ä¸€å¥—ä¸åŒçš„函数:: /* GPIO 输入:返回零或éžé›¶ ,å¯èƒ½ä¼šä¼‘çœ */ int gpio_get_value_cansleep(unsigned gpio); @@ -214,25 +207,26 @@ GPIO 值的命令需è¦ç‰å¾…其信æ¯æŽ’到队首æ‰å‘é€å‘½ä»¤ï¼Œå†èŽ·å¾—å…¶ 事实，这些处ç†ä¾‹ç¨‹å®žé™…上和自旋é”å®‰å…¨çš„å‡½æ•°æ˜¯ä¸€æ ·çš„ã€‚ ** 除æ¤ä¹‹å¤– ** 调用设置和é…ç½®æ¤ç±» GPIO 的函数也必须在å…è®¸ä¼‘çœ çš„ä¸Šä¸‹æ–‡ä¸ï¼Œ -å› ä¸ºå®ƒä»¬å¯èƒ½ä¹Ÿéœ€è¦è®¿é—® GPIO 控制器芯片: (这些设置函数通常在æ¿çº§å¯åŠ¨ä»£ç 或者 -驱动探测/æ–开代ç ä¸ï¼Œæ‰€ä»¥è¿™æ˜¯ä¸€ä¸ªå®¹æ˜“满足的约æŸæ¡ä»¶ã€‚) +å› ä¸ºå®ƒä»¬å¯èƒ½ä¹Ÿéœ€è¦è®¿é—® GPIO 控制器芯片 (这些设置函数通常在æ¿çº§å¯åŠ¨ä»£ç 或者 +驱动探测/æ–开代ç ä¸ï¼Œæ‰€ä»¥è¿™æ˜¯ä¸€ä¸ªå®¹æ˜“满足的约æŸæ¡ä»¶ã€‚) :: - gpio_direction_input() - gpio_direction_output() - gpio_request() + gpio_direction_input() + gpio_direction_output() + gpio_request() -## gpio_request_one() -## gpio_request_array() -## gpio_free_array() + ## gpio_request_one() + ## gpio_request_array() + ## gpio_free_array() - gpio_free() - gpio_set_debounce() + gpio_free() + gpio_set_debounce() 声明和释放 GPIO ----------------------------- -为了有助于æ•èŽ·ç³»ç»Ÿé…置错误,定义了两个函数。 +---------------- + +为了有助于æ•èŽ·ç³»ç»Ÿé…置错误,定义了两个函数:: /* 申请 GPIO, 返回 0 或负的错误代ç . * éžç©ºæ ‡ç¾å¯èƒ½æœ‰åŠ©äºŽè¯Šæ–. @@ -256,9 +250,9 @@ GPIO 值的命令需è¦ç‰å¾…其信æ¯æŽ’到队首æ‰å‘é€å‘½ä»¤ï¼Œå†èŽ·å¾—å…¶ æŸäº›å¹³å°å¯èƒ½ä¹Ÿä½¿ç”¨ GPIO 作为电æºç®¡ç†æ¿€æ´»ä¿¡å·(例如通过关é—未使用芯片区和 简å•åœ°å…³é—未使用时钟)。 -对于 GPIO 使用 pinctrl å系统已知的引脚，å系统应该被告知其使用情况； +对于 GPIO 使用引脚控制å系统已知的引脚，å系统应该被告知其使用情况； 一个 gpiolib 驱动的 .request()æ“作应调用 pinctrl_gpio_request()， -而 gpiolib 驱动的 .free()æ“作应调用 pinctrl_gpio_free()。pinctrl +而 gpiolib 驱动的 .free()æ“作应调用 pinctrl_gpio_free()。引脚控制 å系统å…许 pinctrl_gpio_request()在æŸä¸ªå¼•è„šæˆ–引脚组以å¤ç”¨å½¢å¼â€œå±žäºŽâ€ 一个设备时都æˆåŠŸè¿”回。 @@ -270,7 +264,7 @@ GPIO 值的命令需è¦ç‰å¾…其信æ¯æŽ’到队首æ‰å‘é€å‘½ä»¤ï¼Œå†èŽ·å¾—å…¶ æŸäº›å¹³å°å…许部分或所有 GPIO ä¿¡å·ä½¿ç”¨ä¸åŒçš„引脚。类似的，GPIO 或引脚的 其他方é¢ä¹Ÿéœ€è¦é…置，如上拉/下拉。平å°è½¯ä»¶åº”该在对这些 GPIO 调用 -gpio_request()å‰å°†è¿™ç±»ç»†èŠ‚é…置好，例如使用 pinctrl åç³»ç»Ÿçš„æ˜ å°„è¡¨ï¼Œ +gpio_request()å‰å°†è¿™ç±»ç»†èŠ‚é…置好，例如使用引脚控制åç³»ç»Ÿçš„æ˜ å°„è¡¨ï¼Œ 使得 GPIO çš„ç”¨æˆ·æ— é¡»å…³æ³¨è¿™äº›ç»†èŠ‚ã€‚ 还有一个值得注æ„的是在释放 GPIO å‰ï¼Œä½ å¿…é¡»åœæ¢ä½¿ç”¨å®ƒã€‚ @@ -278,7 +272,7 @@ gpio_request()å‰å°†è¿™ç±»ç»†èŠ‚é…置好，例如使用 pinctrl åç³»ç»Ÿçš„æ˜ æ³¨æ„:申请一个 GPIO 并没有以任何方å¼é…置它，åªä¸è¿‡æ ‡è¯†é‚£ä¸ª GPIO 处于使用 状æ€ã€‚必须有å¦å¤–的代ç æ¥å¤„ç†å¼•è„šé…ç½®(如控制 GPIO 使用的引脚ã€ä¸Šæ‹‰/下拉)。 -考虑到大多数情况下声明 GPIO 之åŽå°±ä¼šç«‹å³é…置它们,所以定义了以下三个辅助函数: +考虑到大多数情况下声明 GPIO 之åŽå°±ä¼šç«‹å³é…置它们,所以定义了以下三个辅助函数:: /* 申请一个 GPIO ä¿¡å·, åŒæ—¶é€šè¿‡ç‰¹å®šçš„'flags'åˆå§‹åŒ–é…ç½®, * 其他和 gpio_request()çš„å‚æ•°å’Œè¿”å›žå€¼ç›¸åŒ @@ -326,7 +320,7 @@ gpio_request()å‰å°†è¿™ç±»ç»†èŠ‚é…置好，例如使用 pinctrl åç³»ç»Ÿçš„æ˜ å°†æ¥è¿™äº›æ ‡å¿—å¯èƒ½æ‰©å±•åˆ°æ”¯æŒæ›´å¤šçš„属性。 更进一æ¥,为了更简å•åœ°å£°æ˜Ž/释放多个 GPIO,'struct gpio'被引进æ¥å°è£…所有 -这三个领域: +这三个领域:: struct gpio { unsigned gpio; @@ -334,7 +328,7 @@ gpio_request()å‰å°†è¿™ç±»ç»†èŠ‚é…置好，例如使用 pinctrl åç³»ç»Ÿçš„æ˜ const char *label; }; -一个典型的用例: +一个典型的用例:: static struct gpio leds_gpios[] = { { 32, GPIOF_OUT_INIT_HIGH, "Power LED" }, /* é»˜è®¤å¼€å¯ */ @@ -356,9 +350,10 @@ gpio_request()å‰å°†è¿™ç±»ç»†èŠ‚é…置好，例如使用 pinctrl åç³»ç»Ÿçš„æ˜ GPIO æ˜ å°„åˆ° IRQ --------------------- +---------------- + GPIO ç¼–å·æ˜¯æ— 符å·æ•´æ•°;IRQ ç¼–å·ä¹Ÿæ˜¯ã€‚这些构æˆäº†ä¸¤ä¸ªé€»è¾‘上ä¸åŒçš„命å空间 -(GPIO 0 ä¸ä¸€å®šä½¿ç”¨ IRQ 0)ã€‚ä½ å¯ä»¥é€šè¿‡ä»¥ä¸‹å‡½æ•°åœ¨å®ƒä»¬ä¹‹é—´å®žçŽ°æ˜ å°„: +(GPIO 0 ä¸ä¸€å®šä½¿ç”¨ IRQ 0)ã€‚ä½ å¯ä»¥é€šè¿‡ä»¥ä¸‹å‡½æ•°åœ¨å®ƒä»¬ä¹‹é—´å®žçŽ°æ˜ å°„:: /* æ˜ å°„ GPIO ç¼–å·åˆ° IRQ ç¼–å· */ int gpio_to_irq(unsigned gpio); @@ -384,7 +379,8 @@ irq_to_gpio()返回的éžé”™è¯¯å€¼å¤§å¤šæ•°é€šå¸¸å¯ä»¥è¢« gpio_get_value()æ‰€ä½ æ¨¡æ‹Ÿå¼€æ¼ä¿¡å· ----------------------------- +------------ + 有时在åªæœ‰ä½Žç”µå¹³ä¿¡å·ä½œä¸ºå®žé™…驱动结果(译者注:多个输出连接于一点，逻辑电平 结果为所有输出的逻辑与)的时候,共享的信å·çº¿éœ€è¦ä½¿ç”¨â€œå¼€æ¼â€ä¿¡å·ã€‚(è¯¥æœ¯è¯ é€‚ç”¨äºŽ CMOS 管；而 TTL 用“集电æžå¼€è·¯â€ã€‚)一个上拉电阻使信å·ä¸ºé«˜ç”µå¹³ã€‚è¿™ @@ -408,9 +404,44 @@ irq_to_gpio()返回的éžé”™è¯¯å€¼å¤§å¤šæ•°é€šå¸¸å¯ä»¥è¢« gpio_get_value()æ‰€ä½ è¿™ä¸ä¸€å®šæ˜¯é”™è¯¯çš„。一个常è§çš„例å就是 I2C 时钟的延长：一个需è¦è¾ƒæ…¢æ—¶é’Ÿçš„ 从设备延迟 SCK 的上å‡æ²¿ï¼Œè€Œ I2C 主设备相应地调整其信å·ä¼ 输速率。 +GPIO控制器和引脚控制å系统 +-------------------------- + +SOC上的GPIO控制器å¯èƒ½ä¸Žå¼•è„šæŽ§åˆ¶å系统紧密结åˆï¼Œå³å¼•è„šå¯ä»¥ä¸Žå¯é€‰çš„gpio功 +能一起被其他功能使用。我们已ç»æ¶µç›–äº†è¿™æ ·çš„æƒ…å†µï¼Œä¾‹å¦‚ä¸€ä¸ªGPIO控制器需è¦ä¿ +留一个引脚或通过调用以下任何一个引脚æ¥è®¾ç½®å…¶æ–¹å‘:: + + pinctrl_gpio_request() + pinctrl_gpio_free() + pinctrl_gpio_direction_input() + pinctrl_gpio_direction_output() + +但是，引脚控制å系统是如何将GPIOå·ç （这是一个全局事项）与æŸä¸ªå¼•è„šæŽ§åˆ¶å™¨ +上的æŸä¸ªå¼•è„šäº¤å‰å…³è”的？ + +这是通过注册引脚的“范围â€æ¥å®žçŽ°çš„，这基本上是交å‰å‚考表。这些æ述是在 +Documentation/driver-api/pin-control.rst + +虽然引脚分é…完全由引脚控制å系统管ç†ï¼Œä½†gpio（在gpiolib下）ä»ç”±gpio驱动 +维护。å¯èƒ½å‘生的情况是，SoCä¸çš„ä¸åŒå¼•è„šèŒƒå›´ç”±ä¸åŒçš„gpio驱动器管ç†ã€‚ + +这使得在调用 "pinctrl_gpio_request" 之å‰ï¼Œè®©gpio驱动å‘pin ctrlåç³» +统宣布它们的引脚范围是åˆç†çš„，以便在使用任何gpio之å‰è¦æ±‚引脚控制å系统准 +备相应的引脚。 + +为æ¤ï¼Œgpio控制器å¯ä»¥ç”¨å¼•è„šæŽ§åˆ¶å系统注册其引脚范围。目å‰æœ‰ä¸¤ç§æ–¹æ³•ï¼šæœ‰æˆ– +æ— DT。 + +关于对DT的支æŒï¼Œè¯·å‚考 Documentation/devicetree/bindings/gpio/gpio.txt. + +对于éžDT支æŒï¼Œç”¨æˆ·å¯ä»¥ç”¨é€‚当的å‚数调用gpiochip_add_pin_range()，将一 +系列的gpio引脚注册到引脚控制驱动上。为æ¤ï¼Œå¿…须将引脚控制设备的å称å—符串 +作为å‚æ•°ä¹‹ä¸€ä¼ ç»™è¿™ä¸ªç¨‹åºã€‚ + + +这些公约忽略了什么？ +==================== -这些公约忽略了什么? -================ 这些公约忽略的最大一件事就是引脚å¤ç”¨ï¼Œå› 为这属于高度芯片特定的属性且 没有å¯ç§»æ¤æ€§ã€‚æŸä¸ªå¹³å°å¯èƒ½ä¸éœ€è¦æ˜Žç¡®çš„å¤ç”¨ä¿¡æ¯ï¼›æœ‰çš„对于任æ„给定的引脚 å¯èƒ½åªæœ‰ä¸¤ä¸ªåŠŸèƒ½é€‰é¡¹ï¼›æœ‰çš„å¯èƒ½æ¯ä¸ªå¼•è„šæœ‰å…«ä¸ªåŠŸèƒ½é€‰é¡¹ï¼›æœ‰çš„å¯èƒ½å¯ä»¥å°† @@ -433,8 +464,9 @@ Linux 的系统。) 当å‰ï¼ŒåŠ¨æ€å®šä¹‰ GPIO 并ä¸æ˜¯æ ‡å‡†çš„，例如作为é…置一个带有æŸäº› GPIO 扩展器的 é™„åŠ ç”µè·¯æ¿çš„副作用。 -GPIO 实现者的框架 (å¯é€‰) -===================== +GPIO 实现者的框架（å¯é€‰ï¼‰ +========================= + å‰é¢æ到了，有一个å¯é€‰çš„实现框架，让平å°ä½¿ç”¨ç›¸åŒçš„编程接å£ï¼Œæ›´åŠ 简å•åœ°æ”¯æŒ ä¸åŒç§ç±»çš„ GPIO 控制器。这个框架称为"gpiolib"。 @@ -444,15 +476,16 @@ GPIO 实现者的框架 (å¯é€‰) 控制器驱动: gpio_chip -------------------- +--------------------- + 在框架ä¸æ¯ä¸ª GPIO 控制器都包装为一个 "struct gpio_chip"，他包å«äº† 该类型的æ¯ä¸ªæŽ§åˆ¶å™¨çš„常用信æ¯: - - 设置 GPIO æ–¹å‘的方法 - - 用于访问 GPIO 值的方法 - - 告知调用其方法是å¦å¯èƒ½ä¼‘çœ çš„æ ‡å¿— - - å¯é€‰çš„ debugfs ä¿¡æ¯å¯¼å‡ºæ–¹æ³• (显示类似上拉é…ç½®ä¸€æ ·çš„é¢å¤–状æ€) - - 诊æ–æ ‡ç¾ + - 设置 GPIO æ–¹å‘的方法 + - 用于访问 GPIO 值的方法 + - 告知调用其方法是å¦å¯èƒ½ä¼‘çœ çš„æ ‡å¿— + - å¯é€‰çš„ debugfs ä¿¡æ¯å¯¼å‡ºæ–¹æ³• (显示类似上拉é…ç½®ä¸€æ ·çš„é¢å¤–状æ€) + - 诊æ–æ ‡ç¾ ä¹ŸåŒ…å«äº†æ¥è‡ª device.platform_data çš„æ¯ä¸ªå®žä¾‹çš„æ•°æ®ï¼šå®ƒç¬¬ä¸€ä¸ª GPIO çš„ ç¼–å·å’Œå®ƒå¯ç”¨çš„ GPIO çš„æ•°é‡ã€‚ @@ -471,7 +504,8 @@ GPIO 实现者的框架 (å¯é€‰) å¹³å°æ”¯æŒ -------- +-------- + 为了支æŒè¿™ä¸ªæ¡†æž¶ï¼Œä¸€ä¸ªå¹³å°çš„ Kconfig 文件将会 "select"(选择) ARCH_REQUIRE_GPIOLIB 或 ARCH_WANT_OPTIONAL_GPIOLIB，并让它的 <asm/gpio.h> åŒ…å« <asm-generic/gpio.h>，åŒæ—¶å®šä¹‰ä¸‰ä¸ªæ–¹æ³•: @@ -489,7 +523,7 @@ ARCH_WANT_OPTIONAL_GPIOLIB æ„å‘³ç€ gpiolib æ ¸å¿ƒé»˜è®¤å…³é—,且用户å¯ä»¥ 如果这些选项都没被选择,该平å°å°±ä¸é€šè¿‡ GPIO-lib æ”¯æŒ GPIO,且代ç ä¸å¯ä»¥ 被用户使能。 -以下这些方法的实现å¯ä»¥ç›´æŽ¥ä½¿ç”¨æ¡†æž¶ä»£ç ,并总是通过 gpio_chip 调度: +以下这些方法的实现å¯ä»¥ç›´æŽ¥ä½¿ç”¨æ¡†æž¶ä»£ç ,并总是通过 gpio_chip 调度:: #define gpio_get_value __gpio_get_value #define gpio_set_value __gpio_set_value @@ -508,7 +542,8 @@ arch_initcall()或者更早的地方集æˆè¿›å¹³å°åˆå§‹åŒ–代ç ，使这些 G 且他们通常å¯ä»¥ä½œä¸º IRQ 使用。 æ¿çº§æ”¯æŒ -------- +-------- + 对于外部 GPIO 控制器(例如 I2C 或 SPI 扩展器ã€ä¸“用芯片ã€å¤šåŠŸèƒ½å™¨ä»¶ã€FPGA 或 CPLD)，大多数常用æ¿çº§ç‰¹å®šä»£ç 都å¯ä»¥æ³¨å†ŒæŽ§åˆ¶å™¨è®¾å¤‡ï¼Œå¹¶ä¿è¯ä»–ä»¬çš„é©±åŠ¨çŸ¥é“ gpiochip_add()所使用的 GPIO ç¼–å·ã€‚他们的起始编å·é€šå¸¸è·Ÿåœ¨å¹³å°ç‰¹å®šçš„ GPIO @@ -526,8 +561,9 @@ GPIO å¯ä»¥å·¥ä½œä¹‹åŽæ‰å¯è¢«æ³¨å†Œã€‚解决这类ä¾èµ–的的一ç§æ–¹æ³•æ˜¯ 设备å˜æˆæ— 效时移除它们。 -用户空间的 Sysfs 接å£(å¯é€‰) -======================== +用户空间的 Sysfs 接å£ï¼ˆå¯é€‰ï¼‰ +============================= + 使用“gpiolibâ€å®žçŽ°æ¡†æž¶çš„å¹³å°å¯ä»¥é€‰æ‹©é…置一个 GPIO çš„ sysfs 用户接å£ã€‚ è¿™ä¸åŒäºŽ debugfs 接å£ï¼Œå› 为它æ供的是对 GPIOæ–¹å‘和值的控制，而ä¸åªæ˜¾ç¤º 一个GPIO 的状æ€æ‘˜è¦ã€‚æ¤å¤–,它å¯ä»¥å‡ºçŽ°åœ¨æ²¡æœ‰è°ƒè¯•æ”¯æŒçš„产å“级系统ä¸ã€‚ @@ -548,6 +584,7 @@ GPIO å¯ä»¥å·¥ä½œä¹‹åŽæ‰å¯è¢«æ³¨å†Œã€‚解决这类ä¾èµ–的的一ç§æ–¹æ³•æ˜¯ Sysfs ä¸çš„路径 -------------- + 在/sys/class/gpio ä¸æœ‰ 3 类入å£: - 用于在用户空间控制 GPIO 的控制接å£; @@ -625,8 +662,9 @@ GPIO 控制器的路径类似 /sys/class/gpio/gpiochip42/ (对于从#42 GPIO ä»Žå†…æ ¸ä»£ç ä¸å¯¼å‡º -------------- -å†…æ ¸ä»£ç å¯ä»¥æ˜Žç¡®åœ°ç®¡ç†é‚£äº›å·²é€šè¿‡ gpio_request()申请的 GPIO 的导出: +---------------- + +å†…æ ¸ä»£ç å¯ä»¥æ˜Žç¡®åœ°ç®¡ç†é‚£äº›å·²é€šè¿‡ gpio_request()申请的 GPIO 的导出:: /* 导出 GPIO 到用户空间 */ int gpio_export(unsigned gpio, bool direction_may_change); @@ -648,3 +686,9 @@ GPIO 控制器的路径类似 /sys/class/gpio/gpiochip42/ (对于从#42 GPIO 在 GPIO 被导出之åŽï¼Œgpio_export_link()å…许在 sysfs 文件系统的任何地方 创建一个到这个 GPIO sysfs 节点的符å·é“¾æŽ¥ã€‚è¿™æ ·é©±åŠ¨å°±å¯ä»¥é€šè¿‡ä¸€ä¸ªæ述性的 åå—，在 sysfs ä¸ä»–们所拥有的设备下æ供一个(到这个 GPIO sysfs 节点的)接å£ã€‚ + + +APIå‚考 +======= + +本节ä¸åˆ—出的函数已被废弃。在新的代ç ä¸åº”该使用基于GPIOæ述符的API。 diff --git a/Documentation/translations/zh_CN/driver-api/index.rst b/Documentation/translations/zh_CN/driver-api/index.rst new file mode 100644 index 000000000000..ba354e1f4e6d --- /dev/null +++ b/Documentation/translations/zh_CN/driver-api/index.rst @@ -0,0 +1,132 @@ +.. SPDX-License-Identifier: GPL-2.0 + +.. include:: ../disclaimer-zh_CN.rst + +:Original: Documentation/driver-api/index.rst + +:翻译: + + å¸å»¶è…¾ Yanteng Si <siyanteng@loongson.cn> + +:æ ¡è¯‘: + +======================== +Linux驱动实现者的APIæŒ‡å— +======================== + +å†…æ ¸æ供了å„ç§å„æ ·çš„æŽ¥å£æ¥æ”¯æŒè®¾å¤‡é©±åŠ¨çš„å¼€å‘。这份文档åªæ˜¯å¯¹å…¶ä¸ä¸€äº›æŽ¥å£è¿›è¡Œäº† +一定程度的整ç†â€”—希望éšç€æ—¶é—´çš„推移，它能å˜å¾—更好ï¼å¯ç”¨çš„å°èŠ‚å¯ä»¥åœ¨ä¸‹é¢çœ‹åˆ°ã€‚ + +.. class:: toc-title + + 目录列表： + +.. toctree:: + :maxdepth: 2 + + gpio/index + io_ordering + +Todolist: + +* driver-model/index +* basics +* infrastructure +* ioctl +* early-userspace/index +* pm/index +* clk +* device-io +* dma-buf +* device_link +* component +* message-based +* infiniband +* aperture +* frame-buffer +* regulator +* reset +* iio/index +* input +* usb/index +* firewire +* pci/index +* cxl/index +* spi +* i2c +* ipmb +* ipmi +* i3c/index +* interconnect +* devfreq +* hsi +* edac +* scsi +* libata +* target +* mailbox +* mtdnand +* miscellaneous +* mei/index +* mtd/index +* mmc/index +* nvdimm/index +* w1 +* rapidio/index +* s390-drivers +* vme +* 80211/index +* uio-howto +* firmware/index +* pin-control +* md/index +* media/index +* misc_devices +* nfc/index +* dmaengine/index +* slimbus +* soundwire/index +* thermal/index +* fpga/index +* acpi/index +* auxiliary_bus +* backlight/lp855x-driver.rst +* connector +* console +* dcdbas +* eisa +* isa +* isapnp +* io-mapping +* generic-counter +* memory-devices/index +* men-chameleon-bus +* ntb +* nvmem +* parport-lowlevel +* pps +* ptp +* phy/index +* pwm +* pldmfw/index +* rfkill +* serial/index +* sm501 +* surface_aggregator/index +* switchtec +* sync_file +* tty/index +* vfio-mediated-device +* vfio +* vfio-pci-device-specific-driver-acceptance +* xilinx/index +* xillybus +* zorro +* hte/index + +.. only:: subproject and html + + Indices + ======= + + * :ref:`genindex` diff --git a/Documentation/translations/zh_CN/driver-api/io_ordering.rst b/Documentation/translations/zh_CN/driver-api/io_ordering.rst new file mode 100644 index 000000000000..4dbfa4ce92a0 --- /dev/null +++ b/Documentation/translations/zh_CN/driver-api/io_ordering.rst @@ -0,0 +1,60 @@ +.. SPDX-License-Identifier: GPL-2.0 + +.. include:: ../disclaimer-zh_CN.rst + +:Original: Documentation/driver-api/io_ordering.rst + +:翻译: + + æž—æ°¸å¬ Lin Yongting <linyongting@gmail.com> + å¸å»¶è…¾ Yanteng Si <siyanteng@loongson.cn> + +:æ ¡è¯‘: + +=========================== +对内å˜æ˜ 射地å€çš„I/Oå†™å…¥æŽ’åº +=========================== + +在æŸäº›å¹³å°ä¸Šï¼Œæ‰€è°“的内å˜æ˜ å°„I/O是弱顺åºã€‚在这些平å°ä¸Šï¼Œé©±åŠ¨å¼€å‘者有责任 +ä¿è¯I/O内å˜æ˜ 射地å€çš„写æ“作按程åºå›¾æ„的顺åºè¾¾åˆ°è®¾å¤‡ã€‚通常读å–一个“安全†+设备寄å˜å™¨æˆ–桥寄å˜å™¨ï¼Œè§¦å‘IO芯片清刷未处ç†çš„写æ“作到达设备åŽæ‰å¤„ç†è¯»æ“作， +而达到ä¿è¯ç›®çš„。驱动程åºé€šå¸¸åœ¨spinlockä¿æŠ¤çš„临界区退出之å‰ä½¿ç”¨è¿™ç§æŠ€æœ¯ã€‚ +这也å¯ä»¥ä¿è¯åŽé¢çš„写æ“作åªåœ¨å‰é¢çš„写æ“作之åŽåˆ°è¾¾è®¾å¤‡ï¼ˆè¿™éžå¸¸ç±»ä¼¼äºŽå†…å˜ +å±éšœæ“作，mb()，ä¸è¿‡ä»…适用于I/O）。 + +å‡è®¾ä¸€ä¸ªè®¾å¤‡é©±åŠ¨ç¨‹çš„具体例å:: + + ... + CPU A: spin_lock_irqsave(&dev_lock, flags) + CPU A: val = readl(my_status); + CPU A: ... + CPU A: writel(newval, ring_ptr); + CPU A: spin_unlock_irqrestore(&dev_lock, flags) + ... + CPU B: spin_lock_irqsave(&dev_lock, flags) + CPU B: val = readl(my_status); + CPU B: ... + CPU B: writel(newval2, ring_ptr); + CPU B: spin_unlock_irqrestore(&dev_lock, flags) + ... + +上述例åä¸ï¼Œè®¾å¤‡å¯èƒ½ä¼šå…ˆæŽ¥æ”¶åˆ°newval2的值，然åŽæŽ¥æ”¶åˆ°newval的值，问题就 +å‘生了。ä¸è¿‡å¾ˆå®¹æ˜“通过下é¢æ–¹æ³•æ¥ä¿®å¤:: + + ... + CPU A: spin_lock_irqsave(&dev_lock, flags) + CPU A: val = readl(my_status); + CPU A: ... + CPU A: writel(newval, ring_ptr); + CPU A: (void)readl(safe_register); /* é…置寄å˜å™¨ï¼Ÿ*/ + CPU A: spin_unlock_irqrestore(&dev_lock, flags) + ... + CPU B: spin_lock_irqsave(&dev_lock, flags) + CPU B: val = readl(my_status); + CPU B: ... + CPU B: writel(newval2, ring_ptr); + CPU B: (void)readl(safe_register); /* é…置寄å˜å™¨ï¼Ÿ*/ + CPU B: spin_unlock_irqrestore(&dev_lock, flags) + +在解决方案ä¸ï¼Œè¯»å–safe_register寄å˜å™¨ï¼Œè§¦å‘IO芯片清刷未处ç†çš„写æ“作， +å†å¤„ç†åŽé¢çš„读æ“作，防æ¢å¼•å‘æ•°æ®ä¸ä¸€è‡´é—®é¢˜ã€‚ diff --git a/Documentation/translations/zh_CN/index.rst b/Documentation/translations/zh_CN/index.rst index bf85baca8b3e..2fc60e60feb4 100644 --- a/Documentation/translations/zh_CN/index.rst +++ b/Documentation/translations/zh_CN/index.rst @@ -108,6 +108,7 @@ TODOList: :maxdepth: 2 core-api/index + driver-api/index locking/index accounting/index cpu-freq/index @@ -120,10 +121,10 @@ TODOList: scheduler/index mm/index peci/index + PCI/index TODOList: -* driver-api/index * block/index * cdrom/index * ide/index @@ -148,7 +149,6 @@ TODOList: * crypto/index * bpf/index * usb/index -* PCI/index * scsi/index * misc-devices/index * mhi/index diff --git a/Documentation/translations/zh_CN/io_ordering.txt b/Documentation/translations/zh_CN/io_ordering.txt deleted file mode 100644 index 7bb3086227ae..000000000000 --- a/Documentation/translations/zh_CN/io_ordering.txt +++ /dev/null @@ -1,67 +0,0 @@ -Chinese translated version of Documentation/driver-api/io_ordering.rst - -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. - -Chinese maintainer: Lin Yongting <linyongting@gmail.com> ---------------------------------------------------------------------- -Documentation/driver-api/io_ordering.rst çš„ä¸æ–‡ç¿»è¯‘ - -如果想评论或更新本文的内容，请直接è”ç³»åŽŸæ–‡æ¡£çš„ç»´æŠ¤è€…ã€‚å¦‚æžœä½ ä½¿ç”¨è‹±æ–‡ -交æµæœ‰å›°éš¾çš„è¯ï¼Œä¹Ÿå¯ä»¥å‘ä¸æ–‡ç‰ˆç»´æŠ¤è€…求助。如果本翻译更新ä¸åŠæ—¶æˆ–者翻 -译å˜åœ¨é—®é¢˜ï¼Œè¯·è”ç³»ä¸æ–‡ç‰ˆç»´æŠ¤è€…。 - -ä¸æ–‡ç‰ˆç»´æŠ¤è€…： æž—æ°¸å¬ Lin Yongting <linyongting@gmail.com> -ä¸æ–‡ç‰ˆç¿»è¯‘者： æž—æ°¸å¬ Lin Yongting <linyongting@gmail.com> -ä¸æ–‡ç‰ˆæ ¡è¯‘者： æž—æ°¸å¬ Lin Yongting <linyongting@gmail.com> - - -以下为æ£æ–‡ ---------------------------------------------------------------------- - -在æŸäº›å¹³å°ä¸Šï¼Œæ‰€è°“的内å˜æ˜ å°„I/O是弱顺åºã€‚在这些平å°ä¸Šï¼Œé©±åŠ¨å¼€å‘者有责任 -ä¿è¯I/O内å˜æ˜ 射地å€çš„写æ“作按程åºå›¾æ„的顺åºè¾¾åˆ°è®¾å¤‡ã€‚通常读å–一个“安全†-设备寄å˜å™¨æˆ–桥寄å˜å™¨ï¼Œè§¦å‘IO芯片清刷未处ç†çš„写æ“作到达设备åŽæ‰å¤„ç†è¯»æ“作， -而达到ä¿è¯ç›®çš„。驱动程åºé€šå¸¸åœ¨spinlockä¿æŠ¤çš„临界区退出之å‰ä½¿ç”¨è¿™ç§æŠ€æœ¯ã€‚ -这也å¯ä»¥ä¿è¯åŽé¢çš„写æ“作åªåœ¨å‰é¢çš„写æ“作之åŽåˆ°è¾¾è®¾å¤‡ï¼ˆè¿™éžå¸¸ç±»ä¼¼äºŽå†…å˜ -å±éšœæ“作，mb()，ä¸è¿‡ä»…适用于I/O）。 - -å‡è®¾ä¸€ä¸ªè®¾å¤‡é©±åŠ¨ç¨‹çš„具体例å： - - ... -CPU A: spin_lock_irqsave(&dev_lock, flags) -CPU A: val = readl(my_status); -CPU A: ... -CPU A: writel(newval, ring_ptr); -CPU A: spin_unlock_irqrestore(&dev_lock, flags) - ... -CPU B: spin_lock_irqsave(&dev_lock, flags) -CPU B: val = readl(my_status); -CPU B: ... -CPU B: writel(newval2, ring_ptr); -CPU B: spin_unlock_irqrestore(&dev_lock, flags) - ... - -上述例åä¸ï¼Œè®¾å¤‡å¯èƒ½ä¼šå…ˆæŽ¥æ”¶åˆ°newval2的值，然åŽæŽ¥æ”¶åˆ°newval的值，问题就 -å‘生了。ä¸è¿‡å¾ˆå®¹æ˜“通过下é¢æ–¹æ³•æ¥ä¿®å¤ï¼š - - ... -CPU A: spin_lock_irqsave(&dev_lock, flags) -CPU A: val = readl(my_status); -CPU A: ... -CPU A: writel(newval, ring_ptr); -CPU A: (void)readl(safe_register); /* é…置寄å˜å™¨ï¼Ÿ*/ -CPU A: spin_unlock_irqrestore(&dev_lock, flags) - ... -CPU B: spin_lock_irqsave(&dev_lock, flags) -CPU B: val = readl(my_status); -CPU B: ... -CPU B: writel(newval2, ring_ptr); -CPU B: (void)readl(safe_register); /* é…置寄å˜å™¨ï¼Ÿ*/ -CPU B: spin_unlock_irqrestore(&dev_lock, flags) - -在解决方案ä¸ï¼Œè¯»å–safe_register寄å˜å™¨ï¼Œè§¦å‘IO芯片清刷未处ç†çš„写æ“作， -å†å¤„ç†åŽé¢çš„读æ“作，防æ¢å¼•å‘æ•°æ®ä¸ä¸€è‡´é—®é¢˜ã€‚ diff --git a/Documentation/translations/zh_CN/oops-tracing.txt b/Documentation/translations/zh_CN/oops-tracing.txt deleted file mode 100644 index c5f3bda7abcb..000000000000 --- a/Documentation/translations/zh_CN/oops-tracing.txt +++ /dev/null @@ -1,212 +0,0 @@ -Chinese translated version of Documentation/admin-guide/bug-hunting.rst - -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. - -Chinese maintainer: Dave Young <hidave.darkstar@gmail.com> ---------------------------------------------------------------------- -Documentation/admin-guide/bug-hunting.rst çš„ä¸æ–‡ç¿»è¯‘ - -如果想评论或更新本文的内容，请直接è”ç³»åŽŸæ–‡æ¡£çš„ç»´æŠ¤è€…ã€‚å¦‚æžœä½ ä½¿ç”¨è‹±æ–‡ -交æµæœ‰å›°éš¾çš„è¯ï¼Œä¹Ÿå¯ä»¥å‘ä¸æ–‡ç‰ˆç»´æŠ¤è€…求助。如果本翻译更新ä¸åŠæ—¶æˆ–者翻 -译å˜åœ¨é—®é¢˜ï¼Œè¯·è”ç³»ä¸æ–‡ç‰ˆç»´æŠ¤è€…。 - -ä¸æ–‡ç‰ˆç»´æŠ¤è€…： æ¨ç‘ž Dave Young <hidave.darkstar@gmail.com> -ä¸æ–‡ç‰ˆç¿»è¯‘者： æ¨ç‘ž Dave Young <hidave.darkstar@gmail.com> -ä¸æ–‡ç‰ˆæ ¡è¯‘者： æŽé˜³ Li Yang <leoyang.li@nxp.com> - çŽ‹èª Wang Cong <xiyou.wangcong@gmail.com> - -以下为æ£æ–‡ ---------------------------------------------------------------------- - -注æ„： ksymoops 在2.6ä¸æ˜¯æ²¡æœ‰ç”¨çš„。 è¯·ä»¥åŽŸæœ‰æ ¼å¼ä½¿ç”¨Oops(æ¥è‡ªdmesg，ç‰ç‰)。 -å¿½ç•¥ä»»ä½•è¿™æ ·é‚£æ ·å…³äºŽâ€œè§£ç Oopsâ€æˆ–者“通过ksymoopsè¿è¡Œâ€çš„文档。 å¦‚æžœä½ è´´å‡ºè¿è¡Œè¿‡ -ksymoopsçš„æ¥è‡ª2.6çš„Oops，人们åªä¼šè®©ä½ é‡è´´ä¸€æ¬¡ã€‚ - -快速总结 -------------- - -å‘现Oops并å‘é€ç»™çœ‹ä¼¼ç›¸å…³çš„å†…æ ¸é¢†åŸŸçš„ç»´æŠ¤è€…ã€‚åˆ«å¤ªæ‹…å¿ƒå¯¹ä¸ä¸Šå·ã€‚å¦‚æžœä½ ä¸ç¡®å®šå°±å‘ç»™ -å’Œä½ æ‰€åšçš„事情相关的代ç 的负责人。 如果å¯é‡çŽ°è¯•ç€æè¿°æ€Žæ ·é‡æž„。 那甚至比oops更有 -价值。 - -å¦‚æžœä½ å¯¹äºŽå‘é€ç»™è°ä¸€æ— 所知， å‘ç»™linux-kernel@vger.kernel.orgã€‚æ„Ÿè°¢ä½ å¸®åŠ©Linux -å°½å¯èƒ½åœ°ç¨³å®šã€‚ - -Oops在哪里? ----------------------- - -通常Oops文本由klogdä»Žå†…æ ¸ç¼“å†²åŒºé‡Œè¯»å–å¹¶ä¼ ç»™syslogd，由syslogd写到syslog文件ä¸ï¼Œ -典型地是/var/log/messages(ä¾èµ–于/etc/syslog.conf)。有时klogd崩溃了,è¿™ç§æƒ…å†µä¸‹ä½ -能够è¿è¡Œdmesg > fileæ¥ä»Žå†…æ ¸ç¼“å†²åŒºä¸è¯»å–æ•°æ®å¹¶ä¿å˜ä¸‹æ¥ã€‚ å¦åˆ™ä½ å¯ä»¥ -cat /proc/kmsg > file， ç„¶è€Œä½ å¿…é¡»ä»‹å…¥ä¸æ¢ä¼ 输， kmsg是一个“永ä¸ç»“æŸçš„文件â€ã€‚如 -果机器崩溃ååˆ°ä½ ä¸èƒ½è¾“入命令或者ç£ç›˜ä¸å¯ç”¨é‚£ä¹ˆä½ 有三ç§é€‰æ‹©:- - -（1） 手抄å±å¹•ä¸Šçš„文本待机器é‡å¯åŽå†è¾“入计算机。 麻烦但如果没有针对崩溃的准备， -这是仅有的选择。 å¦å¤–ï¼Œä½ å¯ä»¥ç”¨æ•°ç 相机把å±å¹•æ‹ä¸‹æ¥-ä¸å¤ªå¥½ï¼Œä½†æ¯”没有强。 如果信 -æ¯æ»šåŠ¨åˆ°äº†ç»ˆç«¯çš„上é¢ï¼Œä½ 会å‘现以高分辩率å¯åŠ¨ï¼ˆæ¯”如，vga=791ï¼‰ä¼šè®©ä½ è¯»åˆ°æ›´å¤šçš„æ–‡ -本。（注æ„：这需è¦vesafb，所以对‘早期’的oops没有帮助） - -（2）用串å£ç»ˆç«¯å¯åŠ¨ï¼ˆè¯·å‚看Documentation/admin-guide/serial-console.rst），è¿è¡Œä¸€ä¸ªnull -modem到å¦ä¸€å°æœºå™¨å¹¶ç”¨ä½ 喜欢的通讯工具获å–输出。Minicom工作地很好。 - -（3）使用Kdump（请å‚看Documentation/admin-guide/kdump/kdump.rst）， -使用在Documentation/admin-guide/kdump/gdbmacros.txtä¸å®šä¹‰çš„dmesg gdbå®ï¼Œä»Žæ—§çš„内å˜ä¸æå–å†…æ ¸ -环形缓冲区。 - -å®Œæ•´ä¿¡æ¯ ----------------- - -注æ„：以下æ¥è‡ªäºŽLinus的邮件适用于2.4å†…æ ¸ã€‚ æˆ‘å› ä¸ºåŽ†å²åŽŸå› ä¿ç•™äº†å®ƒï¼Œå¹¶ä¸”å› ä¸ºå…¶ä¸ -一些信æ¯ä»ç„¶é€‚用。 特别注æ„的是，请忽略任何ksymoops的引用。 - -From: Linus Torvalds <torvalds@osdl.org> - -æ€Žæ ·è·Ÿè¸ªOops.. [原å‘到linux-kernel的一å°é‚®ä»¶] - -主è¦çš„çªé—¨æ˜¯æœ‰äº”年和这些烦人的oops消æ¯æ‰“交é“çš„ç»éªŒ;-) - -å®žé™…ä¸Šï¼Œä½ æœ‰åŠžæ³•ä½¿å®ƒæ›´ç®€å•ã€‚我有两个ä¸åŒçš„方法： - - gdb /usr/src/linux/vmlinux - gdb> disassemble <offending_function> - -那是å‘现问题的简å•åŠžæ³•ï¼Œè‡³å°‘如果bug报告åšçš„å¥½çš„æƒ…å†µä¸‹ï¼ˆè±¡è¿™ä¸ªä¸€æ ·-è¿è¡Œksymoops -得到oopså‘生的函数åŠå‡½æ•°å†…çš„å移）。 - -哦，如果报告å‘ç”Ÿçš„å†…æ ¸ä»¥ç›¸åŒçš„编译器和相似的é…置编译它会有帮助的。 - -å¦ä¸€ä»¶è¦åšçš„事是å汇编bug报告的“Codeâ€éƒ¨åˆ†ï¼šksymoops也会用æ£ç¡®çš„工具æ¥åšè¿™ä»¶äº‹ï¼Œ -ä½†å¦‚æžœæ²¡æœ‰é‚£äº›å·¥å…·ä½ å¯ä»¥å†™ä¸€ä¸ªå‚»ç¨‹åºï¼š - - char str[] = "\xXX\xXX\xXX..."; - main(){} - -并用gcc -g编译它然åŽæ‰§è¡Œâ€œdisassemble strâ€ï¼ˆXX部分是由Oops报告的值-ä½ å¯ä»¥ä»…剪切 -粘贴并用“\xâ€æ›¿æ¢ç©ºæ ¼-我就是这么åšçš„ï¼Œå› ä¸ºæˆ‘æ‡’å¾—å†™ç¨‹åºè‡ªåŠ¨åšè¿™ä¸€åˆ‡ï¼‰ã€‚ - -å¦å¤–ï¼Œä½ å¯ä»¥ç”¨scripts/decodecode这个shell脚本。它的使用方法是： -decodecode < oops.txt - -“Codeâ€ä¹‹åŽçš„åå…进制å—节å¯èƒ½ï¼ˆåœ¨æŸäº›æž¶æž„上）有一些当å‰æŒ‡ä»¤ä¹‹å‰çš„指令å—èŠ‚ä»¥åŠ -当å‰å’Œä¹‹åŽçš„指令å—节 - -Code: f9 0f 8d f9 00 00 00 8d 42 0c e8 dd 26 11 c7 a1 60 ea 2b f9 8b 50 08 a1 -64 ea 2b f9 8d 34 82 8b 1e 85 db 74 6d 8b 15 60 ea 2b f9 <8b> 43 04 39 42 54 -7e 04 40 89 42 54 8b 43 04 3b 05 00 f6 52 c0 - -最åŽï¼Œå¦‚æžœä½ æƒ³çŸ¥é“代ç æ¥è‡ªå“ªé‡Œï¼Œä½ å¯ä»¥ï¼š - - cd /usr/src/linux - make fs/buffer.s # 或任何产生BUG的文件 - -然åŽä½ 会比gdbå汇编更清楚的知é“å‘生了什么。 - -çŽ°åœ¨ï¼Œé—®é¢˜æ˜¯æŠŠä½ æ‰€æ‹¥æœ‰çš„æ‰€æœ‰æ•°æ®ç»“åˆèµ·æ¥ï¼šCæºç ï¼ˆå…³äºŽå®ƒåº”è¯¥æ€Žæ ·çš„ä¸€èˆ¬çŸ¥è¯†ï¼‰ï¼Œ -汇编代ç åŠå…¶å汇编得到的代ç （å¦å¤–还有从“oopsâ€æ¶ˆæ¯å¾—到的寄å˜å™¨çŠ¶æ€-对了解æ¯åçš„ -æŒ‡é’ˆæœ‰ç”¨ï¼Œè€Œä¸”å½“ä½ æœ‰äº†æ±‡ç¼–ä»£ç ä½ ä¹Ÿèƒ½æ‹¿å…¶å®ƒçš„å¯„å˜å™¨å’Œä»»ä½•å®ƒä»¬å¯¹åº”çš„C表达å¼åšåŒ¹é… -）。 - -å®žé™…ä¸Šï¼Œä½ ä»…éœ€çœ‹çœ‹å“ªé‡Œä¸åŒ¹é…（这个例å是“Codeâ€å汇编和编译器生æˆçš„代ç ä¸åŒ¹é…）。 -然åŽä½ é¡»è¦æ‰¾å‡ºä¸ºä»€ä¹ˆä¸åŒ¹é…。通常很简å•-ä½ çœ‹åˆ°ä»£ç 使用了空指针然åŽä½ 看代ç æƒ³çŸ¥é“ -空指针是怎么出现的，还有检查它是å¦åˆæ³•.. - -现在，如果明白这是一项耗时的工作而且需è¦ä¸€ä¸ç‚¹å„¿çš„专心，没错。这就是我为什么大多 -åªæ˜¯å¿½ç•¥é‚£äº›æ²¡æœ‰ç¬¦å·è¡¨ä¿¡æ¯çš„å´©æºƒæŠ¥å‘Šçš„åŽŸå› ï¼šç®€å•çš„说太难查找了（我有一些 -程åºç”¨äºŽåœ¨å†…æ ¸ä»£ç 段ä¸æœç´¢ç‰¹å®šçš„模å¼ï¼Œè€Œä¸”有时我也已ç»èƒ½æ‰¾å‡ºé‚£äº›å´©æºƒçš„地方，但是 -仅仅是找出æ£ç¡®çš„åºåˆ—也确实需è¦ç›¸å½“æ‰Žå®žçš„å†…æ ¸çŸ¥è¯†ï¼‰ - -_有时_会å‘生这ç§æƒ…况，我仅看到崩溃ä¸çš„å汇编代ç åºåˆ—， 然åŽæˆ‘马上就明白问题出在 -哪里。这时我æ‰æ„识到自己干这个工作已ç»å¤ªé•¿æ—¶é—´äº†;-) - - Linus - - ---------------------------------------------------------------------------- -关于Oops跟踪的注解： - -为了帮助Linuså’Œå…¶å®ƒå†…æ ¸å¼€å‘者，klogd纳入了大é‡çš„支æŒæ¥å¤„ç†ä¿æŠ¤é”™è¯¯ã€‚为了拥有对 -地å€è§£æžçš„完整支æŒè‡³å°‘应该使用1.3-pl3çš„sysklogd包。 - -当ä¿æŠ¤é”™è¯¯å‘生时，klogdå®ˆæŠ¤è¿›ç¨‹è‡ªåŠ¨æŠŠå†…æ ¸æ—¥å¿—ä¿¡æ¯ä¸çš„é‡è¦åœ°å€ç¿»è¯‘æˆå®ƒä»¬ç›¸åº”的符 -å·ã€‚ - -klogd执行两ç§ç±»åž‹çš„地å€è§£æžã€‚首先是é™æ€ç¿»è¯‘其次是动æ€ç¿»è¯‘。é™æ€ç¿»è¯‘å’Œksymoops -ä¸€æ ·ä½¿ç”¨System.map文件。为了åšé™æ€ç¿»è¯‘klogd守护进程必须在åˆå§‹åŒ–时能找到system -map文件。关于klogdæ€Žæ ·æœç´¢map文件请å‚看klogd手册页。 - -动æ€åœ°å€ç¿»è¯‘åœ¨ä½¿ç”¨å†…æ ¸å¯è£…载模å—时很é‡è¦ã€‚ å› ä¸ºå†…æ ¸æ¨¡å—的内å˜æ˜¯ä»Žå†…æ ¸åŠ¨æ€å†…å˜æ± -里分é…的，所以ä¸ç®¡æ˜¯æ¨¡å—开始ä½ç½®è¿˜æ˜¯æ¨¡å—ä¸å‡½æ•°å’Œç¬¦å·çš„ä½ç½®éƒ½ä¸æ˜¯å›ºå®šçš„。 - -å†…æ ¸æ”¯æŒå…许程åºå†³å®šè£…载哪些模å—和它们在内å˜ä¸ä½ç½®çš„系统调用。使用这些系统调用 -klogd守护进程生æˆä¸€å¼ 符å·è¡¨ç”¨äºŽè°ƒè¯•å‘生在å¯è£…载模å—ä¸çš„ä¿æŠ¤é”™è¯¯ã€‚ - -至少klogd会æ供产生ä¿æŠ¤é”™è¯¯çš„模å—å。还å¯æœ‰é¢å¤–的符å·ä¿¡æ¯ä¾›å¯è£…载模å—å¼€å‘者选择 -以从模å—ä¸è¾“出符å·ä¿¡æ¯ã€‚ - -å› ä¸ºå†…æ ¸æ¨¡å—环境å¯èƒ½æ˜¯åŠ¨æ€çš„，所以必须有一ç§æœºåˆ¶å½“模å—环境å‘生改å˜æ—¶æ¥é€šçŸ¥klogd -守护进程。 有一些å¯ç”¨çš„命令行选项å…许klogdå‘当å‰æ‰§è¡Œä¸çš„守护进程å‘é€ä¿¡å·ï¼Œå‘ŠçŸ¥ç¬¦ -å·ä¿¡æ¯åº”该被刷新了。 更多信æ¯è¯·å‚看klogd手册页。 - -sysklogdå‘布时包å«ä¸€ä¸ªè¡¥ä¸ä¿®æ”¹äº†modules-2.0.0åŒ…ï¼Œæ— è®ºä½•æ—¶ä¸€ä¸ªæ¨¡å—装载或者å¸è½½éƒ½ -会自动å‘klogdå‘é€ä¿¡å·ã€‚打上这个补ä¸æ供了必è¦çš„对调试å‘ç”ŸäºŽå†…æ ¸å¯è£…载模å—çš„ä¿æŠ¤ -é”™è¯¯çš„æ— ç¼æ”¯æŒã€‚ - -以下是被klogd处ç†è¿‡çš„å‘生在å¯è£…载模å—ä¸çš„一个ä¿æŠ¤é”™è¯¯ä¾‹å： ---------------------------------------------------------------------------- -Aug 29 09:51:01 blizard kernel: Unable to handle kernel paging request at virtual address f15e97cc -Aug 29 09:51:01 blizard kernel: current->tss.cr3 = 0062d000, %cr3 = 0062d000 -Aug 29 09:51:01 blizard kernel: *pde = 00000000 -Aug 29 09:51:01 blizard kernel: Oops: 0002 -Aug 29 09:51:01 blizard kernel: CPU: 0 -Aug 29 09:51:01 blizard kernel: EIP: 0010:[oops:_oops+16/3868] -Aug 29 09:51:01 blizard kernel: EFLAGS: 00010212 -Aug 29 09:51:01 blizard kernel: eax: 315e97cc ebx: 003a6f80 ecx: 001be77b edx: 00237c0c -Aug 29 09:51:01 blizard kernel: esi: 00000000 edi: bffffdb3 ebp: 00589f90 esp: 00589f8c -Aug 29 09:51:01 blizard kernel: ds: 0018 es: 0018 fs: 002b gs: 002b ss: 0018 -Aug 29 09:51:01 blizard kernel: Process oops_test (pid: 3374, process nr: 21, stackpage=00589000) -Aug 29 09:51:01 blizard kernel: Stack: 315e97cc 00589f98 0100b0b4 bffffed4 0012e38e 00240c64 003a6f80 00000001 -Aug 29 09:51:01 blizard kernel: 00000000 00237810 bfffff00 0010a7fa 00000003 00000001 00000000 bfffff00 -Aug 29 09:51:01 blizard kernel: bffffdb3 bffffed4 ffffffda 0000002b 0007002b 0000002b 0000002b 00000036 -Aug 29 09:51:01 blizard kernel: Call Trace: [oops:_oops_ioctl+48/80] [_sys_ioctl+254/272] [_system_call+82/128] -Aug 29 09:51:01 blizard kernel: Code: c7 00 05 00 00 00 eb 08 90 90 90 90 90 90 90 90 89 ec 5d c3 ---------------------------------------------------------------------------- - -Dr. G.W. Wettstein Oncology Research Div. Computing Facility -Roger Maris Cancer Center INTERNET: greg@wind.rmcc.com -820 4th St. N. -Fargo, ND 58122 -Phone: 701-234-7556 - - ---------------------------------------------------------------------------- -å—æ±¡æŸ“çš„å†…æ ¸ - -一些oops报告在程åºè®°æ•°å™¨ä¹‹åŽåŒ…å«å—符串'Tainted: 'ã€‚è¿™è¡¨æ˜Žå†…æ ¸å·²ç»è¢«ä¸€äº›ä¸œè¥¿ç»™æ±¡ -染了。 该å—符串之åŽç´§è·Ÿç€ä¸€ç³»åˆ—çš„ä½ç½®æ•æ„Ÿçš„å—符，æ¯ä¸ªä»£è¡¨ä¸€ä¸ªç‰¹å®šçš„污染值。 - - 1：'G'如果所有装载的模å—都有GPL或相容的许å¯è¯ï¼Œ'P'如果装载了任何的专有模å—。 -没有模å—MODULE_LICENSE或者带有insmod认为是与GPLä¸ç›¸å®¹çš„çš„MODULE_LICENSE的模å—被 -认定是专有的。 - - 2：'F'如果有任何通过“insmod -fâ€è¢«å¼ºåˆ¶è£…载的模å—，' '如果所有模å—都被æ£å¸¸è£…载。 - - 3：'S'如果oopså‘生在SMPå†…æ ¸ä¸ï¼Œè¿è¡ŒäºŽæ²¡æœ‰è¯æ˜Žå®‰å…¨è¿è¡Œå¤šå¤„ç†å™¨çš„硬件。 当å‰è¿™ç§ -情况仅é™äºŽå‡ ç§ä¸æ”¯æŒSMP的速龙处ç†å™¨ã€‚ - - 4：'R'如果模å—通过“insmod -fâ€è¢«å¼ºåˆ¶è£…载，' '如果所有模å—都被æ£å¸¸è£…载。 - - 5：'M'如果任何处ç†å™¨æŠ¥å‘Šäº†æœºå™¨æ£€æŸ¥å¼‚常，' '如果没有å‘生机器检查异常。 - - 6：'B'如果页释放函数å‘现了一个错误的页引用或者一些éžé¢„æœŸçš„é¡µæ ‡å¿—ã€‚ - - 7：'U'如果用户或者用户应用程åºç‰¹åˆ«è¯·æ±‚è®¾ç½®æ±¡æŸ“æ ‡å¿—ï¼Œå¦åˆ™' '。 - - 8：'D'å¦‚æžœå†…æ ¸åˆšåˆšæ»æŽ‰ï¼Œæ¯”如有OOPS或者BUG。 - -使用'Tainted: 'å—符串的主è¦åŽŸå› 是è¦å‘Šè¯‰å†…æ ¸è°ƒè¯•è€…ï¼Œè¿™æ˜¯å¦æ˜¯ä¸€ä¸ªå¹²å‡€çš„å†…æ ¸äº¦æˆ–å‘ -生了任何的ä¸æ£å¸¸çš„事。污染是永久的：å³ä½¿å‡ºé”™çš„模å—å·²ç»è¢«å¸è½½äº†ï¼Œæ±¡æŸ“值ä»ç„¶å˜åœ¨ï¼Œ -ä»¥è¡¨æ˜Žå†…æ ¸ä¸å†å€¼å¾—信任。 diff --git a/Documentation/translations/zh_CN/process/coding-style.rst b/Documentation/translations/zh_CN/process/coding-style.rst index 638d714bec83..fa28ef0a7fee 100644 --- a/Documentation/translations/zh_CN/process/coding-style.rst +++ b/Documentation/translations/zh_CN/process/coding-style.rst @@ -1,21 +1,23 @@ .. include:: ../disclaimer-zh_CN.rst -:Original: :ref:`Documentation/process/coding-style.rst <codingstyle>` +:Original: Documentation/process/coding-style.rst .. _cn_codingstyle: -译者:: +:译者: + - å¼ ä¹ Zhang Le <r0bertz@gentoo.org> + - Andy Deng <theandy.deng@gmail.com> + - å´æƒ³æˆ <bobwxc@email.cn> - ä¸æ–‡ç‰ˆç»´æŠ¤è€…： å¼ ä¹ Zhang Le <r0bertz@gentoo.org> - ä¸æ–‡ç‰ˆç¿»è¯‘者： å¼ ä¹ Zhang Le <r0bertz@gentoo.org> - ä¸æ–‡ç‰ˆæ ¡è¯‘者： çŽ‹èª Wang Cong <xiyou.wangcong@gmail.com> - wheelz <kernel.zeng@gmail.com> - 管æ—东 Xudong Guan <xudong.guan@gmail.com> - Li Zefan <lizf@cn.fujitsu.com> - Wang Chen <wangchen@cn.fujitsu.com> +:æ ¡è¯‘: + - çŽ‹èª Wang Cong <xiyou.wangcong@gmail.com> + - wheelz <kernel.zeng@gmail.com> + - 管æ—东 Xudong Guan <xudong.guan@gmail.com> + - Li Zefan <lizf@cn.fujitsu.com> + - Wang Chen <wangchen@cn.fujitsu.com> Linux å†…æ ¸ä»£ç é£Žæ ¼ -========================= +================== 这是一个简çŸçš„文档，æ述了 linux å†…æ ¸çš„é¦–é€‰ä»£ç é£Žæ ¼ã€‚ä»£ç é£Žæ ¼æ˜¯å› äººè€Œå¼‚çš„ï¼Œ 而且我ä¸æ„¿æ„æŠŠè‡ªå·±çš„è§‚ç‚¹å¼ºåŠ ç»™ä»»ä½•äººï¼Œä½†è¿™å°±åƒæˆ‘去åšä»»ä½•äº‹æƒ…都必须éµå¾ªçš„原则 @@ -29,7 +31,7 @@ Linux å†…æ ¸ä»£ç é£Žæ ¼ 1) 缩进 --------------- +------- 制表符是 8 个å—符，所以缩进也是 8 个å—符。有些异端è¿åŠ¨è¯•å›¾å°†ç¼©è¿›å˜ä¸º 4 (甚至 2ï¼) å—ç¬¦æ·±ï¼Œè¿™å‡ ä¹Žç›¸å½“äºŽå°è¯•å°†åœ†å‘¨çŽ‡çš„值定义为 3。 @@ -73,6 +75,22 @@ Linux å†…æ ¸ä»£ç é£Žæ ¼ if (condition) do_this; do_something_everytime; +ä¸è¦ä½¿ç”¨é€—å·æ¥é¿å…使用大括å·ï¼š + +.. code-block:: c + + if (condition) + do_this(), do_that(); + +使用大括å·åŒ…裹多è¯å¥ï¼š + +.. code-block:: c + + if (condition) { + do_this(); + do_that(); + } + 也ä¸è¦åœ¨ä¸€è¡Œé‡Œæ”¾å¤šä¸ªèµ‹å€¼è¯å¥ã€‚å†…æ ¸ä»£ç é£Žæ ¼è¶…çº§ç®€å•ã€‚就是é¿å…å¯èƒ½å¯¼è‡´åˆ«äººè¯¯è¯» 的表达å¼ã€‚ @@ -83,20 +101,25 @@ Linux å†…æ ¸ä»£ç é£Žæ ¼ 2) 把长的行和å—符串打散 ------------------------------- +----------------------- 代ç é£Žæ ¼çš„æ„义就在于使用平常使用的工具æ¥ç»´æŒä»£ç çš„å¯è¯»æ€§å’Œå¯ç»´æŠ¤æ€§ã€‚ æ¯ä¸€è¡Œçš„长度的é™åˆ¶æ˜¯ 80 列，我们强烈建议您éµå®ˆè¿™ä¸ªæƒ¯ä¾‹ã€‚ 长于 80 列的è¯å¥è¦æ‰“æ•£æˆæœ‰æ„义的片段。除éžè¶…过 80 åˆ—èƒ½æ˜¾è‘—å¢žåŠ å¯è¯»æ€§ï¼Œå¹¶ä¸”ä¸ -会éšè—ä¿¡æ¯ã€‚å片段è¦æ˜Žæ˜¾çŸäºŽæ¯ç‰‡æ®µï¼Œå¹¶æ˜Žæ˜¾é å³ã€‚è¿™åŒæ ·é€‚用于有ç€å¾ˆé•¿å‚数列表 -的函数头。然而，ç»å¯¹ä¸è¦æ‰“散对用户å¯è§çš„å—符串，例如 printk ä¿¡æ¯ï¼Œå› ä¸ºè¿™æ ·å°± +会éšè—ä¿¡æ¯ã€‚ + +å片段è¦æ˜Žæ˜¾çŸäºŽæ¯ç‰‡æ®µï¼Œå¹¶æ˜Žæ˜¾é å³ã€‚一ç§éžå¸¸å¸¸ç”¨çš„æ ·å¼æ˜¯å°†å体与函数左括å·å¯¹é½ã€‚ + +è¿™åŒæ ·é€‚用于有ç€å¾ˆé•¿å‚数列表的函数头。 + +然而，ç»å¯¹ä¸è¦æ‰“散对用户å¯è§çš„å—符串，例如 printk ä¿¡æ¯ï¼Œå› ä¸ºè¿™æ ·å°± 很难对它们 grep。 3) 大括å·å’Œç©ºæ ¼çš„放置 ------------------------------- +--------------------- C è¯è¨€é£Žæ ¼ä¸å¦å¤–一个常è§é—®é¢˜æ˜¯å¤§æ‹¬å·çš„放置。和缩进大å°ä¸åŒï¼Œé€‰æ‹©æˆ–弃用æŸç§æ”¾ ç½®ç–ç•¥å¹¶æ²¡æœ‰å¤šå°‘æŠ€æœ¯ä¸Šçš„åŽŸå› ï¼Œä¸è¿‡é¦–选的方å¼ï¼Œå°±åƒ Kernighan å’Œ Ritchie 展示 @@ -132,12 +155,12 @@ C è¯è¨€é£Žæ ¼ä¸å¦å¤–一个常è§é—®é¢˜æ˜¯å¤§æ‹¬å·çš„æ”¾ç½®ã€‚å’Œç¼©è¿›å¤§å° body of function } -全世界的异端å¯èƒ½ä¼šæŠ±æ€¨è¿™ä¸ªä¸ä¸€è‡´æ€§æ˜¯... 呃... ä¸ä¸€è‡´çš„，ä¸è¿‡æ‰€æœ‰æ€ç»´å¥å…¨çš„人 +全世界的异端å¯èƒ½ä¼šæŠ±æ€¨è¿™ä¸ªä¸ä¸€è‡´æ€§æ˜¯â€¦â€¦å‘ƒâ€¦â€¦ä¸ä¸€è‡´ï¼Œä¸è¿‡æ‰€æœ‰æ€ç»´å¥å…¨çš„人 éƒ½çŸ¥é“ (a) K&R 是 **æ£ç¡®çš„** 并且 (b) K&R 是æ£ç¡®çš„。æ¤å¤–，ä¸ç®¡æ€Žæ ·å‡½æ•°éƒ½æ˜¯ç‰¹ 殊的 (C 函数是ä¸èƒ½åµŒå¥—çš„)。 注æ„结æŸå¤§æ‹¬å·ç‹¬è‡ªå æ®ä¸€è¡Œï¼Œé™¤éžå®ƒåŽé¢è·Ÿç€åŒä¸€ä¸ªè¯å¥çš„剩余部分，也就是 do è¯ -å¥ä¸çš„ "while" 或者 if è¯å¥ä¸çš„ "else"，åƒè¿™æ ·ï¼š +å¥ä¸çš„ ``while`` 或者 if è¯å¥ä¸çš„ ``else`` ，åƒè¿™æ ·ï¼š .. code-block:: c @@ -191,7 +214,7 @@ C è¯è¨€é£Žæ ¼ä¸å¦å¤–一个常è§é—®é¢˜æ˜¯å¤§æ‹¬å·çš„æ”¾ç½®ã€‚å’Œç¼©è¿›å¤§å° } 3.1) ç©ºæ ¼ -******************** +********* Linux å†…æ ¸çš„ç©ºæ ¼ä½¿ç”¨æ–¹å¼ (主è¦) å–决于它是用于函数还是关键å—。(大多数) å…³é”®å— åŽè¦åŠ ä¸€ä¸ªç©ºæ ¼ã€‚å€¼å¾—æ³¨æ„的例外是 sizeof, typeof, alignof å’Œ __attribute__，这 @@ -254,7 +277,7 @@ Linux å†…æ ¸çš„ç©ºæ ¼ä½¿ç”¨æ–¹å¼ (主è¦) å–决于它是用于函数还是关é 4) 命å ------------------------------- +------- C 是一个简朴的è¯è¨€ï¼Œä½ 的命åä¹Ÿåº”è¯¥è¿™æ ·ã€‚å’Œ Modula-2 å’Œ Pascal 程åºå‘˜ä¸åŒï¼Œ C 程åºå‘˜ä¸ä½¿ç”¨ç±»ä¼¼ ThisVariableIsATemporaryCounter è¿™æ ·åŽä¸½çš„åå—。C 程åºå‘˜ä¼š @@ -275,11 +298,31 @@ C 程åºå‘˜ä¸ä½¿ç”¨ç±»ä¼¼ ThisVariableIsATemporaryCounter è¿™æ ·åŽä¸½çš„åå— å¯èƒ½çš„è¯ã€‚类似的， ``tmp`` å¯ä»¥ç”¨æ¥ç§°å‘¼ä»»æ„类型的临时å˜é‡ã€‚ å¦‚æžœä½ æ€•æ··æ·†äº†ä½ çš„æœ¬åœ°å˜é‡åï¼Œä½ å°±é‡åˆ°å¦ä¸€ä¸ªé—®é¢˜äº†ï¼Œå«åšå‡½æ•°å¢žé•¿è·å°”蒙失衡综 -åˆç—‡ã€‚请看第å…ç« (函数)。 +åˆå¾ã€‚请看第å…ç« (函数)。 +对于符å·å称和文档，é¿å…引入新的“master/slaveâ€ï¼ˆæˆ–独立于“masterâ€çš„“slaveâ€ï¼‰ +和“blacklist/whitelistâ€ã€‚ + +“master/slaveâ€æŽ¨è替æ¢ä¸ºï¼š + '{primary,main} / {secondary,replica,subordinate}' + '{initiator,requester} / {target,responder}' + '{controller,host} / {device,worker,proxy}' + 'leader/follower' + 'director/performer' + +“blacklist/whitelistâ€æŽ¨è替æ¢ä¸ºï¼š + 'denylist/allowlist' + 'blocklist/passlist' + +引入新用法的例外情况是：维护用户空间ABI/API，或更新现有（截至2020年）硬件或 +å议规范的代ç æ—¶è¦æ±‚这些术è¯ã€‚对于新规范，尽å¯èƒ½å°†æœ¯è¯çš„规范用法转æ¢ä¸ºå†…æ ¸ +ç¼–ç æ ‡å‡†ã€‚ + +.. warning:: + 以上主从ã€é»‘白åå•è§„则ä¸é€‚用于ä¸æ–‡æ–‡æ¡£ï¼Œè¯·å‹¿æ›´æ”¹ä¸æ–‡æœ¯è¯ï¼ 5) Typedef ------------ +---------- ä¸è¦ä½¿ç”¨ç±»ä¼¼ ``vps_t`` 之类的东西。 @@ -308,7 +351,7 @@ C 程åºå‘˜ä¸ä½¿ç”¨ç±»ä¼¼ ThisVariableIsATemporaryCounter è¿™æ ·åŽä¸½çš„åå— .. note:: - ä¸é€æ˜Žæ€§å’Œ "访问函数" 本身是ä¸å¥½çš„。我们使用 pte_t ç‰ç±»åž‹çš„åŽŸå› åœ¨äºŽçœŸ + ä¸é€æ˜Žæ€§å’Œâ€œè®¿é—®å‡½æ•°â€æœ¬èº«æ˜¯ä¸å¥½çš„。我们使用 pte_t ç‰ç±»åž‹çš„åŽŸå› åœ¨äºŽçœŸ 的是完全没有任何共用的å¯è®¿é—®ä¿¡æ¯ã€‚ (b) 清楚的整数类型，如æ¤ï¼Œè¿™å±‚抽象就å¯ä»¥ **帮助** 消除到底是 ``int`` 还是 @@ -353,7 +396,7 @@ C 程åºå‘˜ä¸ä½¿ç”¨ç±»ä¼¼ ThisVariableIsATemporaryCounter è¿™æ ·åŽä¸½çš„åå— 6) 函数 ------------------------------- +------- 函数应该简çŸè€Œæ¼‚亮，并且åªå®Œæˆä¸€ä»¶äº‹æƒ…。函数应该å¯ä»¥ä¸€å±æˆ–者两å±æ˜¾ç¤ºå®Œ (我们 éƒ½çŸ¥é“ ISO/ANSI å±å¹•å¤§å°æ˜¯ 80x24)，åªåšä¸€ä»¶äº‹æƒ…，而且把它åšå¥½ã€‚ @@ -383,12 +426,46 @@ C 程åºå‘˜ä¸ä½¿ç”¨ç±»ä¼¼ ThisVariableIsATemporaryCounter è¿™æ ·åŽä¸½çš„åå— } EXPORT_SYMBOL(system_is_up); -在函数原型ä¸ï¼ŒåŒ…å«å‡½æ•°å和它们的数æ®ç±»åž‹ã€‚虽然 C è¯è¨€é‡Œæ²¡æœ‰è¿™æ ·çš„è¦æ±‚，在 +6.1) 函数原型 +************* + +在函数原型ä¸åŒ…å«å‚æ•°å和它们的数æ®ç±»åž‹ã€‚虽然 C è¯è¨€é‡Œæ²¡æœ‰è¿™æ ·çš„è¦æ±‚，但在 Linux 里这是æ倡的åšæ³•ï¼Œå› ä¸ºè¿™æ ·å¯ä»¥å¾ˆç®€å•çš„给读者æ供更多的有价值的信æ¯ã€‚ +ä¸è¦åœ¨å‡½æ•°å£°æ˜Žé‡Œä½¿ç”¨ ``extern`` 关键å—ï¼Œå› ä¸ºè¿™ä¼šå¯¼è‡´ä»£ç è¡Œå˜é•¿ï¼Œå¹¶ä¸”ä¸æ˜¯ä¸¥æ ¼ +必需的。 + +写函数原型时，请ä¿æŒ `å…ƒç´ é¡ºåºè§„则 <https://lore.kernel.org/mm-commits/CAHk-=wiOCLRny5aifWNhr621kYrJwhfURsa0vFPeUEm8mF0ufg@mail.gmail.com/>`_ 。 +例如下列函数声明:: + + __init void * __must_check action(enum magic value, size_t size, u8 count, + char *fmt, ...) __printf(4, 5) __malloc; + +推èçš„å‡½æ•°åŽŸåž‹å…ƒç´ é¡ºåºæ˜¯ï¼š + +- 储å˜ç±»åž‹ï¼ˆä¸‹æ–¹çš„ ``static __always_inline`` ï¼Œæ³¨æ„ ``__always_inline`` + 技术上æ¥è®²æ˜¯ä¸ªå±žæ€§ä½†è¢«å½“åš ``inline`` ） +- 储å˜ç±»åž‹å±žæ€§ï¼ˆä¸Šæ–¹çš„ ``__init`` ——å³èŠ‚å£°æ˜Žï¼Œä½†ä¹Ÿåƒ ``__cold`` ） +- 返回类型（上方的 ``void *`` ） +- 返回类型属性（上方的 ``__must_check`` ） +- 函数å（上方的 ``action`` ） +- 函数å‚数（上方的 ``(enum magic value, size_t size, u8 count, char *fmt, ...)`` ， + 注æ„必须写上å‚æ•°å） +- 函数å‚数属性（上方的 ``__printf(4, 5)`` ） +- 函数行为属性（上方的 ``__malloc`` ） + +请注æ„，对于函数 **定义** （å³å®žé™…函数体），编译器ä¸å…许在函数å‚数之åŽæ·»åŠ 函 +æ•°å‚数属性。在这ç§æƒ…况下，它们应该跟éšå˜å‚¨ç±»åž‹å±žæ€§ï¼ˆä¾‹å¦‚，与上é¢çš„ **声明** +示例相比，请注æ„下é¢çš„ ``__printf(4, 5)`` çš„ä½ç½®å‘生了å˜åŒ–）:: + + static __always_inline __init __printf(4, 5) void * __must_check action(enum magic value, + size_t size, u8 count, char *fmt, ...) __malloc + { + ... + } 7) 集ä¸çš„函数退出途径 ------------------------------- +--------------------- 虽然被æŸäº›äººå£°ç§°å·²ç»è¿‡æ—¶ï¼Œä½†æ˜¯ goto è¯å¥çš„ç‰ä»·ç‰©è¿˜æ˜¯ç»å¸¸è¢«ç¼–译器所使用，具体 å½¢å¼æ˜¯æ— æ¡ä»¶è·³è½¬æŒ‡ä»¤ã€‚ @@ -432,7 +509,7 @@ Linux 里这是æ倡的åšæ³•ï¼Œå› ä¸ºè¿™æ ·å¯ä»¥å¾ˆç®€å•çš„给读者æä¾›æ› return result; } -一个需è¦æ³¨æ„的常è§é”™è¯¯æ˜¯ ``一个 err 错误`` ，就åƒè¿™æ ·ï¼š +一个需è¦æ³¨æ„的常è§é”™è¯¯æ˜¯ ``å• err 错误`` ，就åƒè¿™æ ·ï¼š .. code-block:: c @@ -456,19 +533,19 @@ Linux 里这是æ倡的åšæ³•ï¼Œå› ä¸ºè¿™æ ·å¯ä»¥å¾ˆç®€å•çš„给读者æä¾›æ› 8) 注释 ------------------------------- +------- 注释是好的，ä¸è¿‡æœ‰è¿‡åº¦æ³¨é‡Šçš„å±é™©ã€‚永远ä¸è¦åœ¨æ³¨é‡Šé‡Œè§£é‡Šä½ 的代ç 是如何è¿ä½œçš„： 更好的åšæ³•æ˜¯è®©åˆ«äººä¸€çœ‹ä½ 的代ç å°±å¯ä»¥æ˜Žç™½ï¼Œè§£é‡Šå†™çš„很差的代ç 是浪费时间。 -ä¸€èˆ¬çš„ï¼Œä½ æƒ³è¦ä½ çš„æ³¨é‡Šå‘Šè¯‰åˆ«äººä½ çš„ä»£ç åšäº†ä»€ä¹ˆï¼Œè€Œä¸æ˜¯æ€Žä¹ˆåšçš„ã€‚ä¹Ÿè¯·ä½ ä¸è¦æŠŠ +一般æ¥è¯´ä½ ç”¨æ³¨é‡Šå‘Šè¯‰åˆ«äººä½ çš„ä»£ç åšäº†ä»€ä¹ˆï¼Œè€Œä¸æ˜¯æ€Žä¹ˆåšçš„ã€‚ä¹Ÿè¯·ä½ ä¸è¦æŠŠ 注释放在一个函数体内部：如果函数å¤æ‚åˆ°ä½ éœ€è¦ç‹¬ç«‹çš„注释其ä¸çš„ä¸€éƒ¨åˆ†ï¼Œä½ å¾ˆå¯èƒ½ 需è¦å›žåˆ°ç¬¬å…ç« çœ‹ä¸€çœ‹ã€‚ä½ å¯ä»¥åšä¸€äº›å°æ³¨é‡Šæ¥æ³¨æ˜Žæˆ–è¦å‘ŠæŸäº›å¾ˆèªæ˜Ž (或者槽糕) çš„ åšæ³•ï¼Œä½†ä¸è¦åŠ å¤ªå¤šã€‚ä½ åº”è¯¥åšçš„，是把注释放在函数的头部，告诉人们它åšäº†ä»€ä¹ˆï¼Œ 也å¯ä»¥åŠ 上它åšè¿™äº›äº‹æƒ…çš„åŽŸå› ã€‚ -å½“æ³¨é‡Šå†…æ ¸ API 函数时，请使用 kernel-doc æ ¼å¼ã€‚请看 -Documentation/doc-guide/ å’Œ scripts/kernel-doc 以获得详细信æ¯ã€‚ +å½“æ³¨é‡Šå†…æ ¸ API 函数时，请使用 kernel-doc æ ¼å¼ã€‚è¯¦è§ +Documentation/translations/zh_CN/doc-guide/index.rst å’Œ scripts/kernel-doc 。 é•¿ (多行) æ³¨é‡Šçš„é¦–é€‰é£Žæ ¼æ˜¯ï¼š @@ -500,17 +577,18 @@ Documentation/doc-guide/ å’Œ scripts/kernel-doc 以获得详细信æ¯ã€‚ 9) ä½ å·²ç»æŠŠäº‹æƒ…弄糟了 ------------------------------- +--------------------- -è¿™æ²¡ä»€ä¹ˆï¼Œæˆ‘ä»¬éƒ½æ˜¯è¿™æ ·ã€‚å¯èƒ½ä½ 的使用了很长时间 Unix 的朋å‹å·²ç»å‘Šè¯‰ä½ +è¿™æ²¡ä»€ä¹ˆï¼Œæˆ‘ä»¬éƒ½æ˜¯è¿™æ ·ã€‚å¯èƒ½ä½ 长期使用 Unix 的朋å‹å·²ç»å‘Šè¯‰ä½ ``GNU emacs`` èƒ½è‡ªåŠ¨å¸®ä½ æ ¼å¼åŒ– C æºä»£ç ï¼Œè€Œä¸”ä½ ä¹Ÿæ³¨æ„åˆ°äº†ï¼Œç¡®å®žæ˜¯è¿™æ ·ï¼Œä¸è¿‡å®ƒ 所使用的默认值和我们想è¦çš„相去甚远 (实际上，甚至比éšæœºæ‰“的还è¦å·®â€”â€”æ— æ•°ä¸ªçŒ´å -在 GNU emacs 里打å—永远ä¸ä¼šåˆ›é€ 出一个好程åº) (译注：Infinite Monkey Theorem) +在 GNU emacs 里打å—永远ä¸ä¼šåˆ›é€ 出一个好程åº) +*(译注：Infinite Monkey Theorem)* æ‰€ä»¥ä½ è¦ä¹ˆæ”¾å¼ƒ GNU emacs，è¦ä¹ˆæ”¹å˜å®ƒè®©å®ƒä½¿ç”¨æ›´åˆç†çš„设定。è¦é‡‡ç”¨åŽä¸€ä¸ªæ–¹æ¡ˆï¼Œ ä½ å¯ä»¥æŠŠä¸‹é¢è¿™æ®µç²˜è´´åˆ°ä½ çš„ .emacs 文件里。 -.. code-block:: none +.. code-block:: elisp (defun c-lineup-arglist-tabs-only (ignored) "Line up argument lists by tabs, not spaces" @@ -529,7 +607,7 @@ Documentation/doc-guide/ å’Œ scripts/kernel-doc 以获得详细信æ¯ã€‚ (c-offsets-alist . ( (arglist-close . c-lineup-arglist-tabs-only) (arglist-cont-nonempty . - (c-lineup-gcc-asm-reg c-lineup-arglist-tabs-only)) + (c-lineup-gcc-asm-reg c-lineup-arglist-tabs-only)) (arglist-intro . +) (brace-list-intro . +) (c . c-lineup-C-comments) @@ -573,9 +651,14 @@ Documentation/doc-guide/ å’Œ scripts/kernel-doc 以获得详细信æ¯ã€‚ ``indent`` 有很多选项，特别是é‡æ–°æ ¼å¼åŒ–æ³¨é‡Šçš„æ—¶å€™ï¼Œä½ å¯èƒ½éœ€è¦çœ‹ä¸€ä¸‹å®ƒçš„手册。 ä¸è¿‡è®°ä½ï¼š ``indent`` ä¸èƒ½ä¿®æ£åçš„ç¼–ç¨‹ä¹ æƒ¯ã€‚ +请注æ„，您还å¯ä»¥ä½¿ç”¨ ``clang-format`` 工具帮助您处ç†è¿™äº›è§„则，快速自动é‡æ–°æ ¼ +å¼åŒ–部分代ç ，并审阅整个文件以å‘现代ç é£Žæ ¼é”™è¯¯ã€æ‰“å—错误和å¯èƒ½çš„æ”¹è¿›ã€‚å®ƒè¿˜å¯ +ä»¥æ–¹ä¾¿åœ°æŽ’åº ``#include`` ，对é½å˜é‡/å®ï¼Œé‡æŽ’文本和其他类似任务。 +è¯¦è§ Documentation/process/clang-format.rst 。 + 10) Kconfig é…置文件 ------------------------------- +-------------------- 对于é布æºç æ ‘çš„æ‰€æœ‰ Kconfig* é…置文件æ¥è¯´ï¼Œå®ƒä»¬ç¼©è¿›æ–¹å¼æœ‰æ‰€ä¸åŒã€‚ç´§æŒ¨ç€ ``config`` 定义的行，用一个制表符缩进，然而 help ä¿¡æ¯çš„缩进则é¢å¤–å¢žåŠ 2 个空 @@ -598,11 +681,11 @@ Documentation/doc-guide/ å’Œ scripts/kernel-doc 以获得详细信æ¯ã€‚ depends on ADFS_FS ... -è¦æŸ¥çœ‹é…置文件的完整文档，请看 Documentation/kbuild/kconfig-language.rst。 +è¦æŸ¥çœ‹é…置文件的完整文档，请看 Documentation/kbuild/kconfig-language.rst 。 11) æ•°æ®ç»“æž„ ------------------------------- +------------ 如果一个数æ®ç»“构，在创建和销æ¯å®ƒçš„å•çº¿æ‰§è¡ŒçŽ¯å¢ƒä¹‹å¤–å¯è§ï¼Œé‚£ä¹ˆå®ƒå¿…é¡»è¦æœ‰ä¸€ä¸ªå¼• ç”¨è®¡æ•°å™¨ã€‚å†…æ ¸é‡Œæ²¡æœ‰åžƒåœ¾æ”¶é›† (å¹¶ä¸”å†…æ ¸ä¹‹å¤–çš„åžƒåœ¾æ”¶é›†æ…¢ä¸”æ•ˆçŽ‡ä½Žä¸‹)，这æ„味ç€ä½ @@ -626,7 +709,7 @@ mm_count)，和文件系统 (``struct super_block``: s_count å’Œ s_active) ä¸æ‰ 12) å®ï¼Œæžšä¸¾å’ŒRTL ------------------------------- +----------------- 用于定义常é‡çš„å®çš„åå—åŠæžšä¸¾é‡Œçš„æ ‡ç¾éœ€è¦å¤§å†™ã€‚ @@ -638,7 +721,7 @@ mm_count)，和文件系统 (``struct super_block``: s_count å’Œ s_active) ä¸æ‰ å®çš„åå—请用大写å—æ¯ï¼Œä¸è¿‡å½¢å¦‚函数的å®çš„åå—å¯ä»¥ç”¨å°å†™å—æ¯ã€‚ -一般的，如果能写æˆå†…è”函数就ä¸è¦å†™æˆåƒå‡½æ•°çš„å®ã€‚ +通常如果能写æˆå†…è”函数就ä¸è¦å†™æˆåƒå‡½æ•°çš„å®ã€‚ å«æœ‰å¤šä¸ªè¯å¥çš„å®åº”该被包å«åœ¨ä¸€ä¸ª do-while 代ç å—里： @@ -696,18 +779,18 @@ mm_count)，和文件系统 (``struct super_block``: s_count å’Œ s_active) ä¸æ‰ (ret); \ }) -ret 是本地å˜é‡çš„通用åå— - __foo_ret æ›´ä¸å®¹æ˜“与一个已å˜åœ¨çš„å˜é‡å†²çªã€‚ +ret 是本地å˜é‡çš„通用åå——— __foo_ret æ›´ä¸å®¹æ˜“与一个已å˜åœ¨çš„å˜é‡å†²çªã€‚ cpp 手册对å®çš„讲解很详细。gcc internals 手册也详细讲解了 RTLï¼Œå†…æ ¸é‡Œçš„æ±‡ç¼–è¯ è¨€ç»å¸¸ç”¨åˆ°å®ƒã€‚ 13) 打å°å†…æ ¸æ¶ˆæ¯ ------------------------------- +---------------- -å†…æ ¸å¼€å‘者应该是å—过良好教育的。请一定注æ„å†…æ ¸ä¿¡æ¯çš„拼写，以给人以好的å°è±¡ã€‚ +å†…æ ¸å¼€å‘者应该看起æ¥æœ‰æ–‡åŒ–。请一定注æ„å†…æ ¸ä¿¡æ¯çš„拼写，以给人良好的å°è±¡ã€‚ ä¸è¦ç”¨ä¸è§„范的å•è¯æ¯”如 ``dont``，而è¦ç”¨ ``do not`` 或者 ``don't`` 。ä¿è¯è¿™äº›ä¿¡ -æ¯ç®€å•æ˜Žäº†,æ— æ§ä¹‰ã€‚ +æ¯ç®€å•æ˜Žäº†ã€æ— æ§ä¹‰ã€‚ å†…æ ¸ä¿¡æ¯ä¸å¿…以英文å¥å·ç»“æŸã€‚ @@ -724,17 +807,18 @@ dev_info() ç‰ç‰ã€‚对于那些ä¸å’ŒæŸä¸ªç‰¹å®šè®¾å¤‡ç›¸å…³è¿žçš„ä¿¡æ¯ï¼Œ<li 或设定了 CONFIG_DYNAMIC_DEBUG。实际这åŒæ ·æ˜¯ä¸ºäº† dev_dbg()，一个相关约定是在一 个已ç»å¼€å¯äº† DEBUG 时，使用 VERBOSE_DEBUG æ¥æ·»åŠ dev_vdbg()。 -许多å系统拥有 Kconfig 调试选项æ¥å¼€å¯ -DDEBUG 在对应的 Makefile 里é¢ï¼›åœ¨å…¶ä»– +许多å系统拥有 Kconfig 调试选项æ¥å¼€å¯å¯¹åº” Makefile 里é¢çš„ -DDEBUG；在其他 情况下，特殊文件使用 #define DEBUG。当一æ¡è°ƒè¯•ä¿¡æ¯éœ€è¦è¢«æ— æ¡ä»¶æ‰“å°æ—¶ï¼Œä¾‹å¦‚， 如果已ç»åŒ…å«ä¸€ä¸ªè°ƒè¯•ç›¸å…³çš„ #ifdef æ¡ä»¶ï¼Œprintk(KERN_DEBUG ...) å°±å¯è¢«ä½¿ç”¨ã€‚ 14) 分é…å†…å˜ ------------------------------- +------------ å†…æ ¸æ供了下é¢çš„一般用途的内å˜åˆ†é…函数： kmalloc(), kzalloc(), kmalloc_array(), kcalloc(), vmalloc() å’Œ vzalloc()。 -请å‚考 API 文档以获å–有关它们的详细信æ¯ã€‚ +请å‚考 API 文档以获å–有关它们的详细信æ¯ï¼š +Documentation/translations/zh_CN/core-api/memory-allocation.rst 。 ä¼ é€’ç»“æž„ä½“å¤§å°çš„首选形å¼æ˜¯è¿™æ ·çš„： @@ -761,11 +845,13 @@ kmalloc(), kzalloc(), kmalloc_array(), kcalloc(), vmalloc() å’Œ vzalloc()。 p = kcalloc(n, sizeof(...), ...); -两ç§å½¢å¼æ£€æŸ¥åˆ†é…å¤§å° n * sizeof(...) 的溢出，如果溢出返回 NULL。 +两ç§å½¢å¼éƒ½ä¼šæ£€æŸ¥åˆ†é… n * sizeof(...) 大å°æ—¶å†…å˜çš„溢出，如果溢出返回 NULL。 +在没有 __GFP_NOWARN 的情况下使用时，这些通用分é…函数都会在失败时å‘èµ·å †æ ˆè½¬å‚¨ï¼Œ +å› æ¤å½“返回NULL时，没有必è¦å‘出é¢å¤–的失败消æ¯ã€‚ 15) 内è”弊病 ------------------------------- +------------ 有一个常è§çš„误解是 ``内è”`` 是 gcc æ供的å¯ä»¥è®©ä»£ç è¿è¡Œæ›´å¿«çš„一个选项。虽然使 用内è”函数有时候是æ°å½“çš„ (比如作为一ç§æ›¿ä»£å®çš„æ–¹å¼ï¼Œè¯·çœ‹ç¬¬åäºŒç« )，ä¸è¿‡å¾ˆå¤šæƒ… @@ -786,7 +872,7 @@ inline gcc 也å¯ä»¥è‡ªåŠ¨ä½¿å…¶å†…è”。而且其他用户å¯èƒ½ä¼šè¦æ±‚移除 16) 函数返回值åŠå‘½å ------------------------------- +-------------------- 函数å¯ä»¥è¿”回多ç§ä¸åŒç±»åž‹çš„值，最常è§çš„一ç§æ˜¯è¡¨æ˜Žå‡½æ•°æ‰§è¡ŒæˆåŠŸæˆ–è€…å¤±è´¥çš„å€¼ã€‚è¿™æ · 的一个值å¯ä»¥è¡¨ç¤ºä¸ºä¸€ä¸ªé”™è¯¯ä»£ç æ•´æ•° (-Exxxï¼å¤±è´¥ï¼Œ0ï¼æˆåŠŸ) 或者一个 ``æˆåŠŸ`` @@ -797,7 +883,7 @@ inline gcc 也å¯ä»¥è‡ªåŠ¨ä½¿å…¶å†…è”。而且其他用户å¯èƒ½ä¼šè¦æ±‚移除 äº§ç”Ÿè¿™ç§ bug，请éµå¾ªä¸‹é¢çš„惯例:: 如果函数的åå—是一个动作或者强制性的命令，那么这个函数应该返回错误代 - ç 整数。如果是一个判æ–，那么函数应该返回一个 "æˆåŠŸ" 布尔值。 + ç 整数。如果是一个判æ–，那么函数应该返回一个“æˆåŠŸâ€å¸ƒå°”值。 比如， ``add work`` 是一个命令，所以 add_work() 在æˆåŠŸæ—¶è¿”回 0，在失败时返回 -EBUSYã€‚ç±»ä¼¼çš„ï¼Œå› ä¸º ``PCI device present`` 是一个判æ–，所以 pci_dev_present() @@ -806,13 +892,35 @@ inline gcc 也å¯ä»¥è‡ªåŠ¨ä½¿å…¶å†…è”。而且其他用户å¯èƒ½ä¼šè¦æ±‚移除 所有 EXPORTed 函数都必须éµå®ˆè¿™ä¸ªæƒ¯ä¾‹ï¼Œæ‰€æœ‰çš„公共函数也都应该如æ¤ã€‚ç§æœ‰ (static) 函数ä¸éœ€è¦å¦‚æ¤ï¼Œä½†æ˜¯æˆ‘们也推èè¿™æ ·åšã€‚ -返回值是实际计算结果而ä¸æ˜¯è®¡ç®—是å¦æˆåŠŸçš„æ ‡å¿—çš„å‡½æ•°ä¸å—æ¤æƒ¯ä¾‹çš„é™åˆ¶ã€‚一般的， +返回值是实际计算结果而ä¸æ˜¯è®¡ç®—是å¦æˆåŠŸçš„æ ‡å¿—çš„å‡½æ•°ä¸å—æ¤æƒ¯ä¾‹çš„é™åˆ¶ã€‚通常 他们通过返回一些æ£å¸¸å€¼èŒƒå›´ä¹‹å¤–的结果æ¥è¡¨ç¤ºå‡ºé”™ã€‚典型的例å是返回指针的函数， 他们使用 NULL 或者 ERR_PTR 机制æ¥æŠ¥å‘Šé”™è¯¯ã€‚ +17) 使用布尔类型 +---------------- + +Linuxå†…æ ¸å¸ƒå°”ï¼ˆbool）类型是C99 _Bool类型的别å。布尔值åªèƒ½ä¸º0或1，而对布尔的 +éšå¼æˆ–显å¼è½¬æ¢å°†è‡ªåŠ¨å°†å€¼è½¬æ¢ä¸ºtrue或false。在使用布尔类型时 **ä¸éœ€è¦** æž„é€ ï¼Œ +它会消除一类错误。 + +使用布尔值时，应使用trueå’Œfalse定义，而ä¸æ˜¯1å’Œ0。 -17) ä¸è¦é‡æ–°å‘æ˜Žå†…æ ¸å® ------------------------------- +å¸ƒå°”å‡½æ•°è¿”å›žç±»åž‹å’Œå †æ ˆå˜é‡æ€»æ˜¯å¯ä»¥åœ¨é€‚当的时候使用。鼓励使用布尔æ¥æ高å¯è¯»æ€§ï¼Œ +并且布尔值在å˜å‚¨æ—¶é€šå¸¸æ¯”“intâ€æ›´å¥½ã€‚ + +如果缓å˜è¡Œå¸ƒå±€æˆ–值的大å°å¾ˆé‡è¦ï¼Œè¯·ä¸è¦ä½¿ç”¨å¸ƒå°”ï¼Œå› ä¸ºå…¶å¤§å°å’Œå¯¹é½æ–¹å¼æ ¹æ®ç¼–译 +的体系结构而ä¸åŒã€‚针对对é½å’Œå¤§å°è¿›è¡Œä¼˜åŒ–的结构体ä¸åº”使用布尔。 + +如果一个结构体有多个true/false值，请考虑将它们åˆå¹¶ä¸ºå…·æœ‰1比特æˆå‘˜çš„ä½åŸŸï¼Œæˆ–使 +用适当的固定宽度类型，如u8。 + +类似地，对于函数å‚数，多个true/false值å¯ä»¥åˆå¹¶ä¸ºå•ä¸ªæŒ‰ä½çš„â€œæ ‡å¿—â€å‚数，如果调 +用点具有裸true/false常é‡ï¼Œâ€œæ ‡å¿—â€å‚数通常是更具å¯è¯»æ€§çš„替代方法。 + +总之，在结构体和å‚æ•°ä¸æœ‰é™åœ°ä½¿ç”¨å¸ƒå°”å¯ä»¥æ高å¯è¯»æ€§ã€‚ + +18) ä¸è¦é‡æ–°å‘æ˜Žå†…æ ¸å® +---------------------- 头文件 include/linux/kernel.h 包å«äº†ä¸€äº›å®ï¼Œä½ 应该使用它们，而ä¸è¦è‡ªå·±å†™ä¸€äº› 它们的å˜ç§ã€‚æ¯”å¦‚ï¼Œå¦‚æžœä½ éœ€è¦è®¡ç®—ä¸€ä¸ªæ•°ç»„çš„é•¿åº¦ï¼Œä½¿ç”¨è¿™ä¸ªå® @@ -832,11 +940,11 @@ inline gcc 也å¯ä»¥è‡ªåŠ¨ä½¿å…¶å†…è”。而且其他用户å¯èƒ½ä¼šè¦æ±‚移除 åœ¨ä½ çš„ä»£ç 里自己é‡æ–°å®šä¹‰ã€‚ -18) 编辑器模å¼è¡Œå’Œå…¶ä»–需è¦ç½—嗦的事情 --------------------------------------------------- +19) 编辑器模å¼è¡Œå’Œå…¶ä»–需è¦ç½—嗦的事情 +------------------------------------ 有一些编辑器å¯ä»¥è§£é‡ŠåµŒå…¥åœ¨æºæ–‡ä»¶é‡Œçš„ç”±ä¸€äº›ç‰¹æ®Šæ ‡è®°æ ‡æ˜Žçš„é…置信æ¯ã€‚比如，emacs -èƒ½å¤Ÿè§£é‡Šè¢«æ ‡è®°æˆè¿™æ ·çš„行： +能够解æžè¢«æ ‡è®°æˆè¿™æ ·çš„行： .. code-block:: c @@ -852,7 +960,7 @@ inline gcc 也å¯ä»¥è‡ªåŠ¨ä½¿å…¶å†…è”。而且其他用户å¯èƒ½ä¼šè¦æ±‚移除 End: */ -Vim èƒ½å¤Ÿè§£é‡Šè¿™æ ·çš„æ ‡è®°ï¼š +Vim 能够解æžè¿™æ ·çš„æ ‡è®°ï¼š .. code-block:: c @@ -863,8 +971,8 @@ Vim èƒ½å¤Ÿè§£é‡Šè¿™æ ·çš„æ ‡è®°ï¼š 的模å¼ï¼Œæˆ–者使用其他å¯ä»¥äº§ç”Ÿæ£ç¡®çš„缩进的巧妙方法。 -19) 内è”汇编 ------------------------------- +20) 内è”汇编 +------------ 在特定架构的代ç ä¸ï¼Œä½ å¯èƒ½éœ€è¦å†…è”汇编与 CPU 和平å°ç›¸å…³åŠŸèƒ½è¿žæŽ¥ã€‚需è¦è¿™ä¹ˆåšæ—¶ å°±ä¸è¦çŠ¹è±«ã€‚然而，当 C å¯ä»¥å®Œæˆå·¥ä½œæ—¶ï¼Œä¸è¦å¹³ç™½æ— 故地使用内è”汇编。在å¯èƒ½çš„情 @@ -880,8 +988,8 @@ Vim èƒ½å¤Ÿè§£é‡Šè¿™æ ·çš„æ ‡è®°ï¼š ç§»é™¤äº†ã€‚ä½ ä¸å¿…æ€»æ˜¯è¿™æ ·åšï¼Œå°½ç®¡ï¼Œè¿™ä¸å¿…è¦çš„举动会é™åˆ¶ä¼˜åŒ–。 在写一个包å«å¤šæ¡æŒ‡ä»¤çš„å•ä¸ªå†…è”汇编è¯å¥æ—¶ï¼ŒæŠŠæ¯æ¡æŒ‡ä»¤ç”¨å¼•å·åˆ†å‰²è€Œä¸”å„å 一行， -除了最åŽä¸€æ¡æŒ‡ä»¤å¤–，在æ¯ä¸ªæŒ‡ä»¤ç»“å°¾åŠ ä¸Š \n\t，让汇编输出时å¯ä»¥æ£ç¡®åœ°ç¼©è¿›ä¸‹ä¸€æ¡ -指令： +除了最åŽä¸€æ¡æŒ‡ä»¤å¤–，在æ¯ä¸ªæŒ‡ä»¤ç»“å°¾åŠ ä¸Š ``\n\t`` ，让汇编输出时å¯ä»¥æ£ç¡®åœ°ç¼©è¿› +下一æ¡æŒ‡ä»¤ï¼š .. code-block:: c @@ -890,10 +998,10 @@ Vim èƒ½å¤Ÿè§£é‡Šè¿™æ ·çš„æ ‡è®°ï¼š : /* outputs */ : /* inputs */ : /* clobbers */); -20) æ¡ä»¶ç¼–译 ------------------------------- +21) æ¡ä»¶ç¼–译 +------------ -åªè¦å¯èƒ½ï¼Œå°±ä¸è¦åœ¨ .c 文件里é¢ä½¿ç”¨é¢„处ç†æ¡ä»¶ (#if, #ifdef)ï¼›è¿™æ ·åšè®©ä»£ç æ›´éš¾ +åªè¦å¯èƒ½ï¼Œå°±ä¸è¦åœ¨ .c 文件里é¢ä½¿ç”¨é¢„处ç†æ¡ä»¶ (#if, #ifdef)ï¼›è¿™æ ·åšä¼šè®©ä»£ç æ›´éš¾ 阅读并且更难去跟踪逻辑。替代方案是，在头文件ä¸ç”¨é¢„处ç†æ¡ä»¶æ供给那些 .c 文件 使用，å†ç»™ #else æ供一个空桩 (no-op stub) 版本，然åŽåœ¨ .c æ–‡ä»¶å†…æ— æ¡ä»¶åœ°è°ƒç”¨ 那些 (定义在头文件内的) å‡½æ•°ã€‚è¿™æ ·åšï¼Œç¼–译器会é¿å…为桩函数 (stub) çš„è°ƒç”¨ç”Ÿæˆ @@ -904,8 +1012,8 @@ Vim èƒ½å¤Ÿè§£é‡Šè¿™æ ·çš„æ ‡è®°ï¼š æ¡ä»¶åˆ°è¿™ä¸ªè¾…助函数内。 å¦‚æžœä½ æœ‰ä¸€ä¸ªåœ¨ç‰¹å®šé…ç½®ä¸ï¼Œå¯èƒ½å˜æˆæœªä½¿ç”¨çš„函数或å˜é‡ï¼Œç¼–译器会è¦å‘Šå®ƒå®šä¹‰äº†ä½† -æœªä½¿ç”¨ï¼ŒæŠŠå®ƒæ ‡è®°ä¸º __maybe_unused 而ä¸æ˜¯å°†å®ƒåŒ…å«åœ¨ä¸€ä¸ªé¢„处ç†æ¡ä»¶ä¸ã€‚(然而，如 -果一个函数或å˜é‡æ€»æ˜¯æœªä½¿ç”¨ï¼Œå°±ç›´æŽ¥åˆ 除它。) +æœªä½¿ç”¨ï¼Œè¯·æŠŠå®ƒæ ‡è®°ä¸º __maybe_unused 而ä¸æ˜¯å°†å®ƒåŒ…å«åœ¨ä¸€ä¸ªé¢„处ç†æ¡ä»¶ä¸ã€‚(然而， +如果一个函数或å˜é‡æ€»æ˜¯æœªä½¿ç”¨ï¼Œå°±ç›´æŽ¥åˆ 除它。) 在代ç ä¸ï¼Œå°½å¯èƒ½åœ°ä½¿ç”¨ IS_ENABLED å®æ¥è½¬åŒ–æŸä¸ª Kconfig æ ‡è®°ä¸º C 的布尔 表达å¼ï¼Œå¹¶åœ¨ä¸€èˆ¬çš„ C æ¡ä»¶ä¸ä½¿ç”¨å®ƒï¼š @@ -931,23 +1039,45 @@ Vim èƒ½å¤Ÿè§£é‡Šè¿™æ ·çš„æ ‡è®°ï¼š #endif /* CONFIG_SOMETHING */ -附录 I) å‚考 -------------------- +附录 I) å‚考资料 +---------------- -The C Programming Language, 第二版 +The C Programming Language, 2nd Edition 作者：Brian W. Kernighan å’Œ Denni M. Ritchie. Prentice Hall, Inc., 1988. -ISBN 0-13-110362-8 (软皮), 0-13-110370-9 (硬皮). +ISBN 0-13-110362-8 (平装), 0-13-110370-9 (精装). + +.. note:: + + 《C程åºè®¾è®¡è¯è¨€ï¼ˆç¬¬2版）》 + 作者：[美] Brian W. Kernighan / [美] Dennis M. Ritchie + 译者：å¾å®æ–‡ / æŽå¿— / å°¤æ™‹å…ƒï¼ˆå®¡æ ¡ï¼‰ + 出版社：机械工业出版社，2019 + ISBN：9787111617945 The Practice of Programming 作者：Brian W. Kernighan å’Œ Rob Pike. Addison-Wesley, Inc., 1999. ISBN 0-201-61586-X. +.. note:: + + 《程åºè®¾è®¡å®žè·µã€‹ + 作者：[美] Brian W. Kernighan / [美] Rob Pike + 出版社：机械工业出版社，2005 + ISBN：9787111091578 + + 《程åºè®¾è®¡å®žè·µã€‹ + 作者：[美] Brian W. Kernighan / Rob Pike + 译者：裘宗燕 + 出版社：机械工业出版社，2000 + ISBN：9787111075738 + GNU 手册 - éµå¾ª K&R æ ‡å‡†å’Œæ¤æ–‡æœ¬ - cpp, gcc, gcc internals and indent, 都å¯ä»¥ä»Ž https://www.gnu.org/manual/ 找到 WG14 是 C è¯è¨€çš„å›½é™…æ ‡å‡†åŒ–å·¥ä½œç»„ï¼ŒURL: http://www.open-std.org/JTC1/SC22/WG14/ -Kernel process/coding-style.rst，作者 greg@kroah.com å‘表于 OLS 2002： +å†…æ ¸æ–‡æ¡£ Documentation/process/coding-style.rst， +作者 greg@kroah.com å‘表于 OLS 2002： http://www.kroah.com/linux/talks/ols_2002_kernel_codingstyle_talk/html/ diff --git a/Documentation/translations/zh_CN/process/email-clients.rst b/Documentation/translations/zh_CN/process/email-clients.rst index 102023651118..34d51cdadc7b 100644 --- a/Documentation/translations/zh_CN/process/email-clients.rst +++ b/Documentation/translations/zh_CN/process/email-clients.rst @@ -1,17 +1,20 @@ -.. _cn_email_clients: +.. SPDX-License-Identifier: GPL-2.0-or-later .. include:: ../disclaimer-zh_CN.rst -:Original: :ref:`Documentation/process/email-clients.rst <email_clients>` +.. _cn_email_clients: -译者:: +:Original: Documentation/process/email-clients.rst - ä¸æ–‡ç‰ˆç»´æŠ¤è€…： è´¾å¨å¨ Harry Wei <harryxiyou@gmail.com> - ä¸æ–‡ç‰ˆç¿»è¯‘者： è´¾å¨å¨ Harry Wei <harryxiyou@gmail.com> - 时奎亮 Alex Shi <alex.shi@linux.alibaba.com> - ä¸æ–‡ç‰ˆæ ¡è¯‘者： Yinglin Luan <synmyth@gmail.com> - Xiaochen Wang <wangxiaochen0@gmail.com> - yaxinsn <yaxinsn@163.com> +:译者: + - è´¾å¨å¨ Harry Wei <harryxiyou@gmail.com> + - 时奎亮 Alex Shi <alexs@kernel.org> + - å´æƒ³æˆ Wu XiangCheng <bobwxc@email.cn> + +:æ ¡è¯‘: + - Yinglin Luan <synmyth@gmail.com> + - Xiaochen Wang <wangxiaochen0@gmail.com> + - yaxinsn <yaxinsn@163.com> Linux邮件客户端é…ç½®ä¿¡æ¯ ======================= @@ -27,12 +30,17 @@ Git 改日志。如果工作æ£å¸¸ï¼Œå†å°†è¡¥ä¸å‘é€åˆ°ç›¸åº”的邮件列表。 -普通é…ç½® +通用é…ç½® -------- + Linuxå†…æ ¸è¡¥ä¸æ˜¯é€šè¿‡é‚®ä»¶è¢«æ交的，最好把补ä¸ä½œä¸ºé‚®ä»¶ä½“的内嵌文本。有些维护者 æŽ¥æ”¶é™„ä»¶ï¼Œä½†æ˜¯é™„ä»¶çš„å†…å®¹æ ¼å¼åº”该是"text/plain"。然而，附件一般是ä¸èµžæˆçš„， å› ä¸ºè¿™ä¼šä½¿è¡¥ä¸çš„引用部分在评论过程ä¸å˜çš„很困难。 +åŒæ—¶ä¹Ÿå¼ºçƒˆå»ºè®®åœ¨è¡¥ä¸æˆ–其他邮件的æ£æ–‡ä¸ä½¿ç”¨çº¯æ–‡æœ¬æ ¼å¼ã€‚https://useplaintext.email +有助于了解如何é…ç½®ä½ å–œæ¬¢çš„é‚®ä»¶å®¢æˆ·ç«¯ï¼Œå¹¶åœ¨æ‚¨è¿˜æ²¡æœ‰é¦–é€‰çš„æƒ…å†µä¸‹åˆ—å‡ºä¸€äº›æŽ¨èçš„ +客户端。 + 用æ¥å‘é€Linuxå†…æ ¸è¡¥ä¸çš„邮件客户端在å‘é€è¡¥ä¸æ—¶åº”该处于文本的原始状æ€ã€‚例如， 他们ä¸èƒ½æ”¹å˜æˆ–è€…åˆ é™¤åˆ¶è¡¨ç¬¦æˆ–è€…ç©ºæ ¼ï¼Œç”šè‡³æ˜¯åœ¨æ¯ä¸€è¡Œçš„开头或者结尾。 @@ -40,17 +48,17 @@ Linuxå†…æ ¸è¡¥ä¸æ˜¯é€šè¿‡é‚®ä»¶è¢«æ交的，最好把补ä¸ä½œä¸ºé‚®ä»¶ä½“çš„ ä¸è¦è®©ä½ 的邮件客户端进行自动æ¢è¡Œã€‚è¿™æ ·ä¹Ÿä¼šç ´åä½ çš„è¡¥ä¸ã€‚ -邮件客户端ä¸èƒ½æ”¹å˜æ–‡æœ¬çš„å—符集编ç æ–¹å¼ã€‚è¦å‘é€çš„è¡¥ä¸åªèƒ½æ˜¯ASCII或者UTF-8ç¼–ç æ–¹å¼ï¼Œ -å¦‚æžœä½ ä½¿ç”¨UTF-8ç¼–ç æ–¹å¼å‘é€é‚®ä»¶ï¼Œé‚£ä¹ˆä½ 将会é¿å…一些å¯èƒ½å‘生的å—符集问题。 +邮件客户端ä¸èƒ½æ”¹å˜æ–‡æœ¬çš„å—符集编ç æ–¹å¼ã€‚è¦å‘é€çš„è¡¥ä¸åªèƒ½æ˜¯ASCII或者UTF-8ç¼–ç +æ–¹å¼ï¼Œå¦‚æžœä½ ä½¿ç”¨UTF-8ç¼–ç æ–¹å¼å‘é€é‚®ä»¶ï¼Œé‚£ä¹ˆä½ 将会é¿å…一些å¯èƒ½å‘生的å—符集问题。 -邮件客户端应该形æˆå¹¶ä¸”ä¿æŒ References: 或者 In-Reply-To: æ ‡é¢˜ï¼Œé‚£ä¹ˆ -邮件è¯é¢˜å°±ä¸ä¼šä¸æ–。 +邮件客户端应该生æˆå¹¶ä¸”ä¿æŒâ€œReferences:â€æˆ–者“In-Reply-To:â€é‚®ä»¶å¤´ï¼Œè¿™æ ·é‚®ä»¶ä¼šè¯ +å°±ä¸ä¼šä¸æ–。 -å¤åˆ¶ç²˜å¸–(或者剪贴粘帖)通常ä¸èƒ½ç”¨äºŽè¡¥ä¸ï¼Œå› 为制表符会转æ¢ä¸ºç©ºæ ¼ã€‚使用xclipboard, xclip -或者xcutsel也许å¯ä»¥ï¼Œä½†æ˜¯æœ€å¥½æµ‹è¯•ä¸€ä¸‹æˆ–者é¿å…使用å¤åˆ¶ç²˜å¸–。 +å¤åˆ¶ç²˜å¸–(或者剪贴粘帖)通常ä¸èƒ½ç”¨äºŽè¡¥ä¸ï¼Œå› 为制表符会转æ¢ä¸ºç©ºæ ¼ã€‚使用xclipboard, +xclip或者xcutsel也许å¯ä»¥ï¼Œä½†æ˜¯æœ€å¥½æµ‹è¯•ä¸€ä¸‹æˆ–者é¿å…使用å¤åˆ¶ç²˜å¸–。 -ä¸è¦åœ¨ä½¿ç”¨PGP/GPGç½²å的邮件ä¸åŒ…å«è¡¥ä¸ã€‚è¿™æ ·ä¼šä½¿å¾—å¾ˆå¤šè„šæœ¬ä¸èƒ½è¯»å–å’Œé€‚ç”¨äºŽä½ çš„è¡¥ä¸ã€‚ -（这个问题应该是å¯ä»¥ä¿®å¤çš„） +ä¸è¦åœ¨ä½¿ç”¨PGP/GPGç¾å的邮件ä¸åŒ…å«è¡¥ä¸ã€‚è¿™æ ·ä¼šä½¿å¾—å¾ˆå¤šè„šæœ¬ä¸èƒ½è¯»å–å’Œé€‚ç”¨äºŽä½ çš„ +è¡¥ä¸ã€‚（这个问题应该是å¯ä»¥ä¿®å¤çš„） åœ¨ç»™å†…æ ¸é‚®ä»¶åˆ—è¡¨å‘é€è¡¥ä¸ä¹‹å‰ï¼Œç»™è‡ªå·±å‘é€ä¸€ä¸ªè¡¥ä¸æ˜¯ä¸ªä¸é”™çš„主æ„，ä¿å˜æŽ¥æ”¶åˆ°çš„ 邮件，将补ä¸ç”¨'patch'命令打上，如果æˆåŠŸäº†ï¼Œå†ç»™å†…æ ¸é‚®ä»¶åˆ—è¡¨å‘é€ã€‚ @@ -58,98 +66,133 @@ Linuxå†…æ ¸è¡¥ä¸æ˜¯é€šè¿‡é‚®ä»¶è¢«æ交的，最好把补ä¸ä½œä¸ºé‚®ä»¶ä½“çš„ 一些邮件客户端æ示 ------------------ + 这里给出一些详细的MUAé…ç½®æ示，å¯ä»¥ç”¨äºŽç»™Linuxå†…æ ¸å‘é€è¡¥ä¸ã€‚这些并ä¸æ„味是 所有的软件包é…置总结。 说明： -TUI = ä»¥æ–‡æœ¬ä¸ºåŸºç¡€çš„ç”¨æˆ·æŽ¥å£ -GUI = 图形界é¢ç”¨æˆ·æŽ¥å£ + +- TUI = ä»¥æ–‡æœ¬ä¸ºåŸºç¡€çš„ç”¨æˆ·æŽ¥å£ +- GUI = 图形界é¢ç”¨æˆ·æŽ¥å£ Alpine (TUI) -~~~~~~~~~~~~ +************ é…置选项： -在"Sending Preferences"部分： -- "Do Not Send Flowed Text"å¿…é¡»å¼€å¯ -- "Strip Whitespace Before Sending"å¿…é¡»å…³é— +在 :menuselection:`Sending Preferences` èœå•ï¼š + +- :menuselection:`Do Not Send Flowed Text` å¿…é¡»å¼€å¯ +- :menuselection:`Strip Whitespace Before Sending` å¿…é¡»å…³é— + +å½“å†™é‚®ä»¶æ—¶ï¼Œå…‰æ ‡åº”è¯¥æ”¾åœ¨è¡¥ä¸ä¼šå‡ºçŽ°çš„地方，然åŽæŒ‰ä¸‹ :kbd:`CTRL-R` 组åˆé”®ï¼Œä½¿æŒ‡ +定的补ä¸æ–‡ä»¶åµŒå…¥åˆ°é‚®ä»¶ä¸ã€‚ + +Claws Mail (GUI) +**************** + +å¯ä»¥ç”¨ï¼Œæœ‰äººç”¨å®ƒæˆåŠŸåœ°å‘过补ä¸ã€‚ -å½“å†™é‚®ä»¶æ—¶ï¼Œå…‰æ ‡åº”è¯¥æ”¾åœ¨è¡¥ä¸ä¼šå‡ºçŽ°çš„地方，然åŽæŒ‰ä¸‹CTRL-R组åˆé”®ï¼Œä½¿æŒ‡å®šçš„ -è¡¥ä¸æ–‡ä»¶åµŒå…¥åˆ°é‚®ä»¶ä¸ã€‚ +用 :menuselection:`Message-->Insert File` (:kbd:`CTRL-I`) 或外置编辑器æ’入补ä¸ã€‚ + +è‹¥è¦åœ¨Claws编辑窗å£é‡ä¿®æ”¹æ’入的补ä¸ï¼Œéœ€å…³é— +:menuselection:`Configuration-->Preferences-->Compose-->Wrapping` +çš„ `Auto wrapping` 。 Evolution (GUI) -~~~~~~~~~~~~~~~ +*************** -一些开å‘者æˆåŠŸçš„使用它å‘é€è¡¥ä¸ +一些开å‘者æˆåŠŸçš„使用它å‘é€è¡¥ä¸ã€‚ -当选择邮件选项：Preformat - 从Format->Heading->Preformatted (Ctrl-7)或者工具æ +撰写邮件时： +从 :menuselection:`æ ¼å¼-->段è½æ ·å¼-->é¢„æ ¼å¼åŒ–` (:kbd:`CTRL-7`) +或工具æ 选择 :menuselection:`é¢„æ ¼å¼åŒ–` ï¼› 然åŽä½¿ç”¨ï¼š - Insert->Text File... (Alt-n x)æ’入补ä¸æ–‡ä»¶ã€‚ +:menuselection:`æ’å…¥-->文本文件...` (:kbd:`ALT-N x`) æ’入补ä¸æ–‡ä»¶ã€‚ -ä½ è¿˜å¯ä»¥"diff -Nru old.c new.c | xclip"，选择Preformat，然åŽä½¿ç”¨ä¸é—´é”®è¿›è¡Œç²˜å¸–。 +ä½ è¿˜å¯ä»¥ ``diff -Nru old.c new.c | xclip`` ，选择 :menuselection:`é¢„æ ¼å¼åŒ–` ， +然åŽä½¿ç”¨é¼ æ ‡ä¸é”®è¿›è¡Œç²˜å¸–。 Kmail (GUI) -~~~~~~~~~~~ +*********** 一些开å‘者æˆåŠŸçš„使用它å‘é€è¡¥ä¸ã€‚ -默认设置ä¸ä¸ºHTMLæ ¼å¼æ˜¯åˆé€‚çš„ï¼›ä¸è¦å¯ç”¨å®ƒã€‚ +默认撰写设置ç¦ç”¨HTMLæ ¼å¼æ˜¯åˆé€‚çš„ï¼›ä¸è¦å¯ç”¨å®ƒã€‚ -当书写一å°é‚®ä»¶çš„时候，在选项下é¢ä¸è¦é€‰æ‹©è‡ªåŠ¨æ¢è¡Œã€‚å”¯ä¸€çš„ç¼ºç‚¹å°±æ˜¯ä½ åœ¨é‚®ä»¶ä¸è¾“入的任何文本 -都ä¸ä¼šè¢«è‡ªåŠ¨æ¢è¡Œï¼Œå› æ¤ä½ 必须在å‘é€è¡¥ä¸ä¹‹å‰æ‰‹åŠ¨æ¢è¡Œã€‚最简å•çš„方法就是å¯ç”¨è‡ªåŠ¨æ¢è¡Œæ¥ä¹¦å†™é‚®ä»¶ï¼Œ -然åŽæŠŠå®ƒä¿å˜ä¸ºè‰ç¨¿ã€‚ä¸€æ—¦ä½ åœ¨è‰ç¨¿ä¸å†æ¬¡æ‰“开它，它已ç»å…¨éƒ¨è‡ªåŠ¨æ¢è¡Œäº†ï¼Œé‚£ä¹ˆä½ 的邮件虽然没有 -选择自动æ¢è¡Œï¼Œä½†æ˜¯è¿˜ä¸ä¼šå¤±åŽ»å·²æœ‰çš„自动æ¢è¡Œã€‚ +当书写一å°é‚®ä»¶çš„时候，在选项下é¢ä¸è¦é€‰æ‹©è‡ªåŠ¨æ¢è¡Œã€‚å”¯ä¸€çš„ç¼ºç‚¹å°±æ˜¯ä½ åœ¨é‚®ä»¶ä¸è¾“ +入的任何文本都ä¸ä¼šè¢«è‡ªåŠ¨æ¢è¡Œï¼Œå› æ¤ä½ 必须在å‘é€è¡¥ä¸ä¹‹å‰æ‰‹åŠ¨æ¢è¡Œã€‚最简å•çš„方法 +就是å¯ç”¨è‡ªåŠ¨æ¢è¡Œæ¥ä¹¦å†™é‚®ä»¶ï¼Œç„¶åŽæŠŠå®ƒä¿å˜ä¸ºè‰ç¨¿ã€‚ä¸€æ—¦ä½ åœ¨è‰ç¨¿ä¸å†æ¬¡æ‰“开它，它 +å·²ç»å…¨éƒ¨è‡ªåŠ¨æ¢è¡Œäº†ï¼Œé‚£ä¹ˆä½ 的邮件虽然没有选择自动æ¢è¡Œï¼Œä½†æ˜¯è¿˜ä¸ä¼šå¤±åŽ»å·²æœ‰çš„自 +动æ¢è¡Œã€‚ -在邮件的底部，æ’入补ä¸ä¹‹å‰ï¼Œæ”¾ä¸Šå¸¸ç”¨çš„è¡¥ä¸å®šç•Œç¬¦ï¼šä¸‰ä¸ªè¿žå—å·(---)。 +在邮件的底部，æ’入补ä¸ä¹‹å‰ï¼Œæ”¾ä¸Šå¸¸ç”¨çš„è¡¥ä¸å®šç•Œç¬¦ï¼šä¸‰ä¸ªè¿žå—符(``---``)。 -然åŽåœ¨"Message"èœå•æ¡ç›®ï¼Œé€‰æ‹©æ’入文件，接ç€é€‰å–ä½ çš„è¡¥ä¸æ–‡ä»¶ã€‚还有一个é¢å¤–çš„é€‰é¡¹ï¼Œä½ å¯ä»¥ -通过它é…ç½®ä½ çš„é‚®ä»¶å»ºç«‹å·¥å…·æ èœå•ï¼Œè¿˜å¯ä»¥å¸¦ä¸Š"insert file"å›¾æ ‡ã€‚ +然åŽåœ¨ :menuselection:`信件` èœå•ï¼Œé€‰æ‹© :menuselection:`æ’入文本文件` ，接 +ç€é€‰å–ä½ çš„è¡¥ä¸æ–‡ä»¶ã€‚还有一个é¢å¤–çš„é€‰é¡¹ï¼Œä½ å¯ä»¥é€šè¿‡å®ƒé…ç½®ä½ çš„åˆ›å»ºæ–°é‚®ä»¶å·¥å…·æ ， +åŠ ä¸Š :menuselection:`æ’入文本文件` å›¾æ ‡ã€‚ -ä½ å¯ä»¥å®‰å…¨åœ°é€šè¿‡GPGæ ‡è®°é™„ä»¶ï¼Œä½†æ˜¯å†…åµŒè¡¥ä¸æœ€å¥½ä¸è¦ä½¿ç”¨GPGæ ‡è®°å®ƒä»¬ã€‚ä½œä¸ºå†…åµŒæ–‡æœ¬çš„ç¾å‘è¡¥ä¸ï¼Œ -当从GPGä¸æå–7ä½ç¼–ç 时会使他们å˜çš„æ›´åŠ å¤æ‚。 +将编辑器窗å£æ‹‰åˆ°è¶³å¤Ÿå®½é¿å…折行。对于KMail 1.13.5 (KDE 4.5.4)，它会在å‘é€é‚®ä»¶ +时对编辑器窗å£ä¸æ˜¾ç¤ºæŠ˜è¡Œçš„地方自动æ¢è¡Œã€‚在选项èœå•ä¸å–消自动æ¢è¡Œä»ä¸èƒ½è§£å†³ã€‚ +å› æ¤ï¼Œå¦‚æžœä½ çš„è¡¥ä¸ä¸æœ‰éžå¸¸é•¿çš„行，必须在å‘é€ä¹‹å‰æŠŠç¼–辑器窗å£æ‹‰å¾—éžå¸¸å®½ã€‚ +å‚è§ï¼šhttps://bugs.kde.org/show_bug.cgi?id=174034 -å¦‚æžœä½ éžè¦ä»¥é™„件的形å¼å‘é€è¡¥ä¸ï¼Œé‚£ä¹ˆå°±å³é”®ç‚¹å‡»é™„件，然åŽé€‰ä¸å±žæ€§ï¼Œçªå‡º"Suggest automatic -display"ï¼Œè¿™æ ·å†…åµŒé™„ä»¶æ›´å®¹æ˜“è®©è¯»è€…çœ‹åˆ°ã€‚ +ä½ å¯ä»¥å®‰å…¨åœ°ç”¨GPGç¾å附件，但是内嵌补ä¸æœ€å¥½ä¸è¦ä½¿ç”¨GPGç¾å它们。作为内嵌文本 +æ’入的ç¾åè¡¥ä¸å°†ä½¿å…¶éš¾ä»¥ä»Ž7-bitç¼–ç ä¸æå–。 -å½“ä½ è¦ä¿å˜å°†è¦å‘é€çš„内嵌文本补ä¸ï¼Œä½ å¯ä»¥ä»Žæ¶ˆæ¯åˆ—è¡¨çª—æ ¼é€‰æ‹©åŒ…å«è¡¥ä¸çš„邮件，然åŽå³å‡»é€‰æ‹© -"save as"ã€‚ä½ å¯ä»¥ä½¿ç”¨ä¸€ä¸ªæ²¡æœ‰æ›´æ”¹çš„包å«è¡¥ä¸çš„邮件，如果它是以æ£ç¡®çš„å½¢å¼ç»„æˆã€‚å½“ä½ æ£çœŸåœ¨å®ƒ -自己的窗å£ä¹‹ä¸‹å¯Ÿçœ‹ï¼Œé‚£æ—¶æ²¡æœ‰é€‰é¡¹å¯ä»¥ä¿å˜é‚®ä»¶--å·²ç»æœ‰ä¸€ä¸ªè¿™æ ·çš„bug被汇报到了kmailçš„bugzilla -并且希望这将会被处ç†ã€‚邮件是以åªé’ˆå¯¹æŸä¸ªç”¨æˆ·å¯è¯»å†™çš„æƒé™è¢«ä¿å˜çš„ï¼Œæ‰€ä»¥å¦‚æžœä½ æƒ³æŠŠé‚®ä»¶å¤åˆ¶åˆ°å…¶ä»–地方， -ä½ ä¸å¾—ä¸æŠŠä»–们的æƒé™æ”¹ä¸ºç»„或者整体å¯è¯»ã€‚ +å¦‚æžœä½ éžè¦ä»¥é™„件的形å¼å‘é€è¡¥ä¸ï¼Œé‚£ä¹ˆå°±å³é”®ç‚¹å‡»é™„件，然åŽé€‰æ‹© +:menuselection:`属性` ，打开 :menuselection:`建议自动显示` ，使附件内è”更容 +易让读者看到。 + +å½“ä½ è¦ä¿å˜å°†è¦å‘é€çš„内嵌文本补ä¸ï¼Œä½ å¯ä»¥ä»Žæ¶ˆæ¯åˆ—è¡¨çª—æ ¼é€‰æ‹©åŒ…å«è¡¥ä¸çš„邮件，然 +åŽå³é”®é€‰æ‹© :menuselection:`å¦å˜ä¸º` 。如果整个电å邮件的组æˆæ£ç¡®ï¼Œæ‚¨å¯ç›´æŽ¥å°† +其作为补ä¸ä½¿ç”¨ã€‚电å邮件以当å‰ç”¨æˆ·å¯è¯»å†™æƒé™ä¿å˜ï¼Œå› æ¤æ‚¨å¿…é¡» ``chmod`` ，以 +使其在å¤åˆ¶åˆ°åˆ«å¤„时用户组和其他人å¯è¯»ã€‚ Lotus Notes (GUI) -~~~~~~~~~~~~~~~~~ +***************** ä¸è¦ä½¿ç”¨å®ƒã€‚ +IBM Verse (Web GUI) +******************* + +åŒä¸Šæ¡ã€‚ + Mutt (TUI) -~~~~~~~~~~ +********** + +很多Linuxå¼€å‘人员使用mutt客户端，这è¯æ˜Žå®ƒè‚¯å®šå·¥ä½œå¾—éžå¸¸æ¼‚亮。 -很多Linuxå¼€å‘人员使用mutt客户端，所以è¯æ˜Žå®ƒè‚¯å®šå·¥ä½œçš„éžå¸¸æ¼‚亮。 +Muttä¸è‡ªå¸¦ç¼–辑器，所以ä¸ç®¡ä½ 使用什么编辑器，ä¸è‡ªåŠ¨æ–行就行。大多数编辑器都有 +:menuselection:`æ’入文件` 选项，它å¯ä»¥åœ¨ä¸æ”¹å˜æ–‡ä»¶å†…容的情况下æ’入文件。 -Muttä¸è‡ªå¸¦ç¼–辑器，所以ä¸ç®¡ä½ 使用什么编辑器都ä¸åº”该带有自动æ–行。大多数编辑器都带有 -一个"insert file"选项，它å¯ä»¥é€šè¿‡ä¸æ”¹å˜æ–‡ä»¶å†…容的方å¼æ’入文件。 +用 ``vim`` 作为mutt的编辑器:: -'vim'作为mutt的编辑器： set editor="vi" - 如果使用xclip，敲入以下命令 +如果使用xclip，敲入以下命令:: + :set paste - 按ä¸é”®ä¹‹å‰æˆ–者shift-insert或者使用 + +然åŽå†æŒ‰ä¸é”®æˆ–者shift-insert或者使用:: + :r filename -如果想è¦æŠŠè¡¥ä¸ä½œä¸ºå†…嵌文本。 -(a)ttach工作的很好，ä¸å¸¦æœ‰"set paste"。 +把补ä¸æ’入为内嵌文本。 +在未设置 ``set paste`` æ—¶(a)ttach工作的很好。 ä½ å¯ä»¥é€šè¿‡ ``git format-patch`` 生æˆè¡¥ä¸ï¼Œç„¶åŽç”¨ Muttå‘é€å®ƒä»¬:: - $ mutt -H 0001-some-bug-fix.patch + $ mutt -H 0001-some-bug-fix.patch é…置选项： + 它应该以默认设置的形å¼å·¥ä½œã€‚ -然而，把"send_charset"设置为"us-ascii::utf-8"也是一个ä¸é”™çš„主æ„。 +然而，把 ``send_charset`` 设置一下也是一个ä¸é”™çš„主æ„:: + + set send_charset="us-ascii:utf-8" Mutt 是高度å¯é…置的。 这里是个使用mutt通过 Gmail å‘é€çš„è¡¥ä¸çš„最å°é…ç½®:: @@ -178,71 +221,107 @@ Mutt 是高度å¯é…置的。 这里是个使用mutt通过 Gmail å‘é€çš„è¡¥ä¸ set from = "username@gmail.com" set use_from = yes -Mutt文档å«æœ‰æ›´å¤šä¿¡æ¯: +Mutt文档å«æœ‰æ›´å¤šä¿¡æ¯ï¼š - http://dev.mutt.org/trac/wiki/UseCases/Gmail + https://gitlab.com/muttmua/mutt/-/wikis/UseCases/Gmail - http://dev.mutt.org/doc/manual.html + http://www.mutt.org/doc/manual/ Pine (TUI) -~~~~~~~~~~ +********** Pineè¿‡åŽ»æœ‰ä¸€äº›ç©ºæ ¼åˆ å‡é—®é¢˜ï¼Œä½†æ˜¯è¿™äº›çŽ°åœ¨åº”该都被修å¤äº†ã€‚ -如果å¯ä»¥ï¼Œè¯·ä½¿ç”¨alpine(pine的继承者) +如果å¯ä»¥ï¼Œè¯·ä½¿ç”¨alpine（pine的继承者）。 é…置选项： -- 最近的版本需è¦æ¶ˆé™¤æµç¨‹æ–‡æœ¬ -- "no-strip-whitespace-before-send"选项也是需è¦çš„。 + +- æœ€è¿‘çš„ç‰ˆæœ¬éœ€è¦ ``quell-flowed-text`` +- ``no-strip-whitespace-before-send`` 选项也是需è¦çš„。 Sylpheed (GUI) -~~~~~~~~~~~~~~ +************** - 内嵌文本å¯ä»¥å¾ˆå¥½çš„工作（或者使用附件）。 - å…许使用外部的编辑器。 -- 对于目录较多时éžå¸¸æ…¢ã€‚ +- 收件箱较多时éžå¸¸æ…¢ã€‚ - 如果通过non-SSLè¿žæŽ¥ï¼Œæ— æ³•ä½¿ç”¨TLS SMTP授æƒã€‚ -- 在组æˆçª—å£ä¸æœ‰ä¸€ä¸ªå¾ˆæœ‰ç”¨çš„ruler bar。 -- 给地å€æœ¬ä¸æ·»åŠ 地å€å°±ä¸ä¼šæ£ç¡®çš„了解显示å。 +- 撰写窗å£çš„æ ‡å°ºå¾ˆæœ‰ç”¨ã€‚ +- 将地å€æ·»åŠ åˆ°é€šè®¯ç°¿æ—¶æ— æ³•æ£ç¡®ç†è§£æ˜¾ç¤ºçš„å称。 Thunderbird (GUI) -~~~~~~~~~~~~~~~~~ +***************** + +Thunderbird是Outlook的克隆版本，它很容易æŸå文本，但也有一些方法强制修æ£ã€‚ + +在完æˆä¿®æ”¹åŽï¼ˆåŒ…括安装扩展），您需è¦é‡æ–°å¯åŠ¨Thunderbird。 + +- å…许使用外部编辑器： + + 使用Thunderbirdå‘è¡¥ä¸æœ€ç®€å•çš„方法是使用扩展æ¥æ‰“开您最喜欢的外部编辑器。 + + 下é¢æ˜¯ä¸€äº›èƒ½å¤Ÿåšåˆ°è¿™ä¸€ç‚¹çš„æ‰©å±•æ ·ä¾‹ã€‚ + + - “External Editor Revived†+ + https://github.com/Frederick888/external-editor-revived + + https://addons.thunderbird.net/en-GB/thunderbird/addon/external-editor-revived/ + + 它需è¦å®‰è£…“本地消æ¯ä¸»æœºï¼ˆnative messaging host）â€ã€‚ + å‚è§ä»¥ä¸‹æ–‡æ¡£: + https://github.com/Frederick888/external-editor-revived/wiki + + - “External Editor†+ + https://github.com/exteditor/exteditor + + 下载并安装æ¤æ‰©å±•ï¼Œç„¶åŽæ‰“å¼€ :menuselection:`新建消æ¯` 窗å£, 用 + :menuselection:`查看-->工具æ -->自定义...` ç»™å®ƒå¢žåŠ ä¸€ä¸ªæŒ‰é’®ï¼Œç›´æŽ¥ç‚¹å‡»æ¤ + 按钮å³å¯ä½¿ç”¨å¤–置编辑器。 + + 请注æ„，“External Editorâ€è¦æ±‚ä½ çš„ç¼–è¾‘å™¨ä¸èƒ½fork，æ¢å¥è¯è¯´ï¼Œç¼–辑器必须在 + å…³é—å‰ä¸è¿”å›žã€‚ä½ å¯èƒ½éœ€è¦ä¼ 递é¢å¤–çš„å‚数或修改编辑器设置。最值得注æ„的是， + 如果您使用的是gvim，那么您必须将 :menuselection:`external editor` 设置的 + 编辑器å—段设置为 ``/usr/bin/gvim --nofork"`` （å‡è®¾å¯æ‰§è¡Œæ–‡ä»¶åœ¨ + ``/usr/bin`` ï¼‰ï¼Œä»¥ä¼ é€’ ``-f`` å‚数。如果您æ£åœ¨ä½¿ç”¨å…¶ä»–编辑器，请阅读其 + 手册了解如何处ç†ã€‚ -默认情况下，thunderbird很容易æŸå文本，但是还有一些方法å¯ä»¥å¼ºåˆ¶å®ƒå˜å¾—更好。 +è‹¥è¦ä¿®æ£å†…部编辑器，请执行以下æ“作： -- 在用户å¸å·è®¾ç½®é‡Œï¼Œç»„æˆå’Œå¯»å€ï¼Œä¸è¦é€‰æ‹©"Compose messages in HTML format"。 +- ä¿®æ”¹ä½ çš„Thunderbird设置，ä¸è¦ä½¿ç”¨ ``format=flowed`` ï¼ + 回到主窗å£ï¼ŒæŒ‰ç…§ + :menuselection:`主èœå•-->首选项-->常规-->é…置编辑器...` + 打开Thunderbirdçš„é…置编辑器。 -- ç¼–è¾‘ä½ çš„Thunderbirdé…置设置æ¥ä½¿å®ƒä¸è¦æ‹†è¡Œä½¿ç”¨ï¼šuser_pref("mailnews.wraplength", 0); + - å°† ``mailnews.send_plaintext_flowed`` 设为 ``false`` -- ç¼–è¾‘ä½ çš„Thunderbirdé…置设置，使它ä¸è¦ä½¿ç”¨"format=flowed"æ ¼å¼ï¼šuser_pref("mailnews. - send_plaintext_flowed", false); + - å°† ``mailnews.wraplength`` 从 ``72`` 改为 ``0`` -- ä½ éœ€è¦ä½¿Thunderbirdå˜ä¸ºé¢„å…ˆæ ¼å¼æ–¹å¼ï¼š - å¦‚æžœé»˜è®¤æƒ…å†µä¸‹ä½ ä¹¦å†™çš„æ˜¯HTMLæ ¼å¼ï¼Œé‚£ä¸æ˜¯å¾ˆéš¾ã€‚ä»…ä»…ä»Žæ ‡é¢˜æ 的下拉框ä¸é€‰æ‹©"Preformat"æ ¼å¼ã€‚ - å¦‚æžœé»˜è®¤æƒ…å†µä¸‹ä½ ä¹¦å†™çš„æ˜¯æ–‡æœ¬æ ¼å¼ï¼Œä½ ä¸å¾—把它改为HTMLæ ¼å¼ï¼ˆä»…仅作为一次性的）æ¥ä¹¦å†™æ–°çš„消æ¯ï¼Œ - 然åŽå¼ºåˆ¶ä½¿å®ƒå›žåˆ°æ–‡æœ¬æ ¼å¼ï¼Œå¦åˆ™å®ƒå°±ä¼šæ‹†è¡Œã€‚è¦å®žçŽ°å®ƒï¼Œåœ¨å†™ä¿¡çš„å›¾æ ‡ä¸Šä½¿ç”¨shifté”®æ¥ä½¿å®ƒå˜ä¸ºHTML - æ ¼å¼ï¼Œç„¶åŽæ ‡é¢˜æ 的下拉框ä¸é€‰æ‹©"Preformat"æ ¼å¼ã€‚ +- ä¸è¦å†™HTMLé‚®ä»¶ï¼ + 回到主窗å£ï¼Œæ‰“å¼€ + :menuselection:`主èœå•-->账户设置-->ä½ çš„@邮件.地å€-->通讯录/编写&地å€ç°¿` ， + 关掉 ``以HTMLæ ¼å¼ç¼–写消æ¯`` 。 -- å…许使用外部的编辑器： - 针对Thunderbird打补ä¸æœ€ç®€å•çš„方法就是使用一个"external editor"扩展，然åŽä½¿ç”¨ä½ 最喜欢的 - $EDITORæ¥è¯»å–或者åˆå¹¶è¡¥ä¸åˆ°æ–‡æœ¬ä¸ã€‚è¦å®žçŽ°å®ƒï¼Œå¯ä»¥ä¸‹è½½å¹¶ä¸”安装这个扩展，然åŽæ·»åŠ 一个使用它的 - 按键View->Toolbars->Customize...最åŽå½“ä½ ä¹¦å†™ä¿¡æ¯çš„时候仅仅点击它就å¯ä»¥äº†ã€‚ +- åªç”¨çº¯æ–‡æœ¬æ ¼å¼æŸ¥çœ‹é‚®ä»¶ï¼ + 回到主窗å£ï¼Œ :menuselection:`主èœå•-->查看-->消æ¯ä½“为-->纯文本` ï¼ TkRat (GUI) -~~~~~~~~~~~ +*********** å¯ä»¥ä½¿ç”¨å®ƒã€‚使用"Insert file..."或者外部的编辑器。 Gmail (Web GUI) -~~~~~~~~~~~~~~~ +*************** ä¸è¦ä½¿ç”¨å®ƒå‘é€è¡¥ä¸ã€‚ Gmail网页客户端自动地把制表符转æ¢ä¸ºç©ºæ ¼ã€‚ -虽然制表符转æ¢ä¸ºç©ºæ ¼é—®é¢˜å¯ä»¥è¢«å¤–部编辑器解决，åŒæ—¶å®ƒè¿˜ä¼šä½¿ç”¨å›žè½¦æ¢è¡ŒæŠŠæ¯è¡Œæ‹†åˆ†ä¸º78个å—符。 +虽然制表符转æ¢ä¸ºç©ºæ ¼é—®é¢˜å¯ä»¥è¢«å¤–部编辑器解决，但它åŒæ—¶è¿˜ä¼šä½¿ç”¨å›žè½¦æ¢è¡ŒæŠŠæ¯è¡Œ +拆分为78个å—符。 -å¦ä¸€ä¸ªé—®é¢˜æ˜¯Gmail还会把任何ä¸æ˜¯ASCIIçš„å—符的信æ¯æ”¹ä¸ºbase64ç¼–ç 。它把东西å˜çš„åƒæ¬§æ´²äººçš„åå—。 +å¦ä¸€ä¸ªé—®é¢˜æ˜¯Gmail还会把任何å«æœ‰éžASCIIçš„å—符的消æ¯æ”¹ç”¨base64ç¼–ç ，如欧洲人的 +åå—。 - ### diff --git a/Documentation/translations/zh_CN/process/submit-checklist.rst b/Documentation/translations/zh_CN/process/submit-checklist.rst index a64858d321fc..3d6ee21c74ae 100644 --- a/Documentation/translations/zh_CN/process/submit-checklist.rst +++ b/Documentation/translations/zh_CN/process/submit-checklist.rst @@ -1,105 +1,111 @@ .. include:: ../disclaimer-zh_CN.rst -:Original: :ref:`Documentation/process/submit-checklist.rst <submitchecklist>` -:Translator: Alex Shi <alex.shi@linux.alibaba.com> +:Original: Documentation/process/submit-checklist.rst +:Translator: + - Alex Shi <alexs@kernel.org> + - Wu XiangCheng <bobwxc@email.cn> .. _cn_submitchecklist: -Linuxå†…æ ¸è¡¥ä¸æäº¤æ¸…å• -~~~~~~~~~~~~~~~~~~~~~ +Linuxå†…æ ¸è¡¥ä¸æäº¤æ£€æŸ¥å• +~~~~~~~~~~~~~~~~~~~~~~~ 如果开å‘äººå‘˜å¸Œæœ›çœ‹åˆ°ä»–ä»¬çš„å†…æ ¸è¡¥ä¸æ交更快地被接å—，那么他们应该åšä¸€äº›åŸºæœ¬ 的事情。 -这些都是在 -:ref:`Documentation/translations/zh_CN/process/submitting-patches.rst <cn_submittingpatches>` +这些都是在 Documentation/translations/zh_CN/process/submitting-patches.rst 和其他有关æ交Linuxå†…æ ¸è¡¥ä¸çš„文档ä¸æ供的。 -1) 如果使用工具，则包括定义/声明该工具的文件。ä¸è¦ä¾èµ–于其他头文件拉入您使用 +1) 如果使用工具，则包括定义/声明该工具的文件。ä¸è¦ä¾èµ–其他头文件æ¥å¼•å…¥æ‚¨ä½¿ç”¨ 的头文件。 2) 干净的编译： - a) 使用适用或修改的 ``CONFIG`` 选项 ``=y``ã€``=m`` å’Œ ``=n`` 。没有GCC + a) 使用åˆé€‚çš„ ``CONFIG`` 选项 ``=y``ã€``=m`` å’Œ ``=n`` 。没有 ``gcc`` è¦å‘Š/错误，没有链接器è¦å‘Š/错误。 - b) 通过allnoconfigã€allmodconfig + b) 通过 ``allnoconfig`` 〠``allmodconfig`` c) 使用 ``O=builddir`` æ—¶å¯ä»¥æˆåŠŸç¼–译 -3) 通过使用本地交å‰ç¼–译工具或其他一些构建场在多个CPU体系结构上构建。 + d) 任何 Doucmentation/ 下的å˜æ›´éƒ½èƒ½æˆåŠŸæž„建且ä¸å¼•å…¥æ–°è¦å‘Š/错误。 + 用 ``make htmldocs`` 或 ``make pdfdocs`` 检验构建情况并修å¤é—®é¢˜ã€‚ + +3) 通过使用本地交å‰ç¼–译工具或其他一些构建设施在多个CPU体系结构上构建。 4) PPC64是一ç§å¾ˆå¥½çš„交å‰ç¼–è¯‘æ£€æŸ¥ä½“ç³»ç»“æž„ï¼Œå› ä¸ºå®ƒå€¾å‘于对64ä½çš„æ•°ä½¿ç”¨æ— ç¬¦å· é•¿æ•´åž‹ã€‚ -5) 如下所述 :ref:`Documentation/translations/zh_CN/process/coding-style.rst <cn_codingstyle>`. - 检查您的补ä¸æ˜¯å¦ä¸ºå¸¸è§„æ ·å¼ã€‚在æ交（ ``scripts/check patch.pl`` ）之å‰ï¼Œ - 使用补ä¸æ ·å¼æ£€æŸ¥å™¨æ£€æŸ¥æ˜¯å¦æœ‰è½»å¾®çš„冲çªã€‚您应该能够处ç†æ‚¨çš„è¡¥ä¸ä¸å˜åœ¨çš„所有 +5) 按 Documentation/translations/zh_CN/process/coding-style.rst 所述检查您的 + è¡¥ä¸æ˜¯å¦ä¸ºå¸¸è§„æ ·å¼ã€‚在æ交之å‰ä½¿ç”¨è¡¥ä¸æ ·å¼æ£€æŸ¥å™¨ ``scripts/checkpatch.pl`` + 检查是å¦æœ‰è½»å¾®çš„冲çªã€‚您应该能够处ç†æ‚¨çš„è¡¥ä¸ä¸å˜åœ¨çš„所有 è¿è§„行为。 -6) 任何新的或修改过的 ``CONFIG`` 选项都ä¸ä¼šå¼„è„é…ç½®èœå•ï¼Œå¹¶é»˜è®¤ä¸ºå…³é—ï¼Œé™¤éž - å®ƒä»¬ç¬¦åˆ ``Documentation/kbuild/kconfig-language.rst`` ä¸è®°å½•çš„异常æ¡ä»¶, - èœå•å±žæ€§ï¼šé»˜è®¤å€¼. +6) 任何新的或修改过的 ``CONFIG`` 选项都ä¸åº”æžä¹±é…ç½®èœå•ï¼Œå¹¶é»˜è®¤ä¸ºå…³é—ï¼Œé™¤éž + å®ƒä»¬ç¬¦åˆ ``Documentation/kbuild/kconfig-language.rst`` èœå•å±žæ€§ï¼šé»˜è®¤å€¼ä¸ + 记录的例外æ¡ä»¶ã€‚ 7) 所有新的 ``kconfig`` 选项都有帮助文本。 8) 已仔细审查了相关的 ``Kconfig`` 组åˆã€‚这很难用测试æ¥çº æ£â€”—脑力在这里是有 回报的。 -9) 用 sparse 检查干净。 +9) 通过 sparse 清查。 + （å‚è§ Documentation/translations/zh_CN/dev-tools/sparse.rst ） 10) 使用 ``make checkstack`` å’Œ ``make namespacecheck`` 并修å¤ä»–们å‘现的任何 问题。 .. note:: - ``checkstack`` å¹¶æ²¡æœ‰æ˜Žç¡®æŒ‡å‡ºé—®é¢˜ï¼Œä½†æ˜¯ä»»ä½•ä¸€ä¸ªåœ¨å †æ ˆä¸Šä½¿ç”¨è¶…è¿‡512 + ``checkstack`` 并ä¸ä¼šæ˜Žç¡®æŒ‡å‡ºé—®é¢˜ï¼Œä½†æ˜¯ä»»ä½•ä¸€ä¸ªåœ¨å †æ ˆä¸Šä½¿ç”¨è¶…过512 å—节的函数都å¯ä»¥è¿›è¡Œæ›´æ”¹ã€‚ -11) 包括 :ref:`kernel-doc <kernel_doc>` å†…æ ¸æ–‡æ¡£ä»¥è®°å½•å…¨å±€å†…æ ¸API。（é™æ€å‡½æ•° - ä¸éœ€è¦ï¼Œä½†ä¹Ÿå¯ä»¥ã€‚）使用 ``make htmldocs`` 或 ``make pdfdocs`` 检查 - :ref:`kernel-doc <kernel_doc>` 并修å¤ä»»ä½•é—®é¢˜ã€‚ +11) 包括 :ref:`kernel-doc <kernel_doc_zh>` å†…æ ¸æ–‡æ¡£ä»¥è®°å½•å…¨å±€å†…æ ¸API。（é™æ€ + 函数ä¸éœ€è¦ï¼Œä½†ä¹Ÿå¯ä»¥ã€‚）使用 ``make htmldocs`` 或 ``make pdfdocs`` 检查 + :ref:`kernel-doc <kernel_doc_zh>` 并修å¤ä»»ä½•é—®é¢˜ã€‚ -12) 通过以下选项åŒæ—¶å¯ç”¨çš„测试 ``CONFIG_PREEMPT``, ``CONFIG_DEBUG_PREEMPT``, +12) 通过以下选项åŒæ—¶å¯ç”¨çš„测试： ``CONFIG_PREEMPT``, ``CONFIG_DEBUG_PREEMPT``, ``CONFIG_DEBUG_SLAB``, ``CONFIG_DEBUG_PAGEALLOC``, ``CONFIG_DEBUG_MUTEXES``, ``CONFIG_DEBUG_SPINLOCK``, ``CONFIG_DEBUG_ATOMIC_SLEEP``, - ``CONFIG_PROVE_RCU`` and ``CONFIG_DEBUG_OBJECTS_RCU_HEAD`` - -13) å·²ç»è¿‡æž„建和è¿è¡Œæ—¶æµ‹è¯•ï¼ŒåŒ…括有或没有 ``CONFIG_SMP``, ``CONFIG_PREEMPT``. + ``CONFIG_PROVE_RCU`` å’Œ ``CONFIG_DEBUG_OBJECTS_RCU_HEAD`` 。 -14) 如果补ä¸ç¨‹åºå½±å“IO/ç£ç›˜ç‰ï¼šä½¿ç”¨æˆ–ä¸ä½¿ç”¨ ``CONFIG_LBDAF`` 进行测试。 +13) 在 ``CONFIG_SMP``, ``CONFIG_PREEMPT`` å¼€å¯å’Œå…³é—的情况下都进行构建和è¿è¡Œ + 时测试。 -15) 所有代ç 路径都已在å¯ç”¨æ‰€æœ‰lockdep功能的情况下è¿è¡Œã€‚ +14) 所有代ç 路径都已在å¯ç”¨æ‰€æœ‰æ»é”检测（lockdep）功能的情况下è¿è¡Œã€‚ -16) 所有新的/procæ¡ç›®éƒ½è®°å½•åœ¨ ``Documentation/`` +15) 所有新的 ``/proc`` æ¡ç›®éƒ½è®°å½•åœ¨ ``Documentation/`` -17) æ‰€æœ‰æ–°çš„å†…æ ¸å¼•å¯¼å‚数都记录在 +16) æ‰€æœ‰æ–°çš„å†…æ ¸å¼•å¯¼å‚数都记录在 Documentation/admin-guide/kernel-parameters.rst ä¸ã€‚ -18) 所有新的模å—å‚数都记录在 ``MODULE_PARM_DESC()`` +17) 所有新的模å—å‚数都记录在 ``MODULE_PARM_DESC()`` -19) 所有新的用户空间接å£éƒ½è®°å½•åœ¨ ``Documentation/ABI/`` ä¸ã€‚有关详细信æ¯ï¼Œ +18) 所有新的用户空间接å£éƒ½è®°å½•åœ¨ ``Documentation/ABI/`` ä¸ã€‚有关详细信æ¯ï¼Œ 请å‚阅 ``Documentation/ABI/README`` 。更改用户空间接å£çš„è¡¥ä¸åº”è¯¥æŠ„é€ linux-api@vger.kernel.org。 -20) 已通过至少注入slabå’Œpage分é…失败进行检查。请å‚阅 ``Documentation/fault-injection/`` +19) 已通过至少注入slabå’Œpage分é…失败进行检查。请å‚阅 ``Documentation/fault-injection/`` 。 如果新代ç æ˜¯å®žè´¨æ€§çš„ï¼Œé‚£ä¹ˆæ·»åŠ å系统特定的故障注入å¯èƒ½æ˜¯åˆé€‚的。 -21) æ–°æ·»åŠ çš„ä»£ç å·²ç»ç”¨ ``gcc -W`` 编译（使用 ``make EXTRA-CFLAGS=-W`` ）。这 +20) æ–°æ·»åŠ çš„ä»£ç å·²ç»ç”¨ ``gcc -W`` 编译（使用 ``make EXTRA-CFLAGS=-W`` ）。这 将产生大é‡å™ªå£°ï¼Œä½†å¯¹äºŽæŸ¥æ‰¾è¯¸å¦‚“è¦å‘Šï¼šæœ‰ç¬¦å·å’Œæ— 符å·ä¹‹é—´çš„比较â€ä¹‹ç±»çš„错误 很有用。 -22) 在它被åˆå¹¶åˆ°-mmè¡¥ä¸é›†ä¸ä¹‹åŽè¿›è¡Œæµ‹è¯•ï¼Œä»¥ç¡®ä¿å®ƒä»ç„¶ä¸Žæ‰€æœ‰å…¶ä»–排队的补ä¸ä»¥ +21) 在它被åˆå¹¶åˆ°-mmè¡¥ä¸é›†ä¸ä¹‹åŽè¿›è¡Œæµ‹è¯•ï¼Œä»¥ç¡®ä¿å®ƒä»ç„¶ä¸Žæ‰€æœ‰å…¶ä»–排队的补ä¸ä»¥ åŠVMã€VFS和其他å系统ä¸çš„å„ç§æ›´æ”¹ä¸€èµ·å·¥ä½œã€‚ -23) 所有内å˜å±éšœä¾‹å¦‚ ``barrier()``, ``rmb()``, ``wmb()`` 都需è¦æºä»£ç ä¸çš„注 +22) 所有内å˜å±éšœï¼ˆä¾‹å¦‚ ``barrier()``, ``rmb()``, ``wmb()`` ）都需è¦æºä»£ç 注 释æ¥è§£é‡Šå®ƒä»¬æ£åœ¨æ‰§è¡Œçš„æ“作åŠå…¶åŽŸå› 的逻辑。 -24) 如果补ä¸æ·»åŠ 了任何ioctl，那么也è¦æ›´æ–° ``Documentation/userspace-api/ioctl/ioctl-number.rst`` +23) 如果补ä¸æ·»åŠ 了任何ioctl，那么也è¦æ›´æ–° + ``Documentation/userspace-api/ioctl/ioctl-number.rst`` 。 -25) 如果修改åŽçš„æºä»£ç ä¾èµ–或使用与以下 ``Kconfig`` 符å·ç›¸å…³çš„ä»»ä½•å†…æ ¸API或 +24) 如果修改åŽçš„æºä»£ç ä¾èµ–或使用与以下 ``Kconfig`` 符å·ç›¸å…³çš„ä»»ä½•å†…æ ¸API或 功能，则在ç¦ç”¨ç›¸å…³ ``Kconfig`` 符å·å’Œ/或 ``=m`` （如果该选项å¯ç”¨ï¼‰çš„情况 下测试以下多个构建[并éžæ‰€æœ‰è¿™äº›éƒ½åŒæ—¶å˜åœ¨ï¼Œåªæ˜¯å®ƒä»¬çš„å„ç§/éšæœºç»„åˆ]： - ``CONFIG_SMP``, ``CONFIG_SYSFS``, ``CONFIG_PROC_FS``, ``CONFIG_INPUT``, ``CONFIG_PCI``, ``CONFIG_BLOCK``, ``CONFIG_PM``, ``CONFIG_MAGIC_SYSRQ``, - ``CONFIG_NET``, ``CONFIG_INET=n`` (但是åŽè€…ä¼´éš ``CONFIG_NET=y``). + ``CONFIG_SMP``, ``CONFIG_SYSFS``, ``CONFIG_PROC_FS``, ``CONFIG_INPUT``, + ``CONFIG_PCI``, ``CONFIG_BLOCK``, ``CONFIG_PM``, ``CONFIG_MAGIC_SYSRQ``, + ``CONFIG_NET``, ``CONFIG_INET=n`` （但是最åŽä¸€ä¸ªéœ€è¦ ``CONFIG_NET=y`` ）。 diff --git a/Documentation/translations/zh_CN/process/submitting-patches.rst b/Documentation/translations/zh_CN/process/submitting-patches.rst index ebb7f37575c1..f8978f02057c 100644 --- a/Documentation/translations/zh_CN/process/submitting-patches.rst +++ b/Documentation/translations/zh_CN/process/submitting-patches.rst @@ -1,142 +1,92 @@ -.. _cn_submittingpatches: +.. SPDX-License-Identifier: GPL-2.0-or-later .. include:: ../disclaimer-zh_CN.rst -:Original: :ref:`Documentation/process/submitting-patches.rst <submittingpatches>` +.. _cn_submittingpatches: + +:Original: Documentation/process/submitting-patches.rst -译者:: +:译者: + - 钟宇 TripleX Chung <xxx.phy@gmail.com> + - 时奎亮 Alex Shi <alexs@kernel.org> + - å´æƒ³æˆ Wu XiangCheng <bobwxc@email.cn> - ä¸æ–‡ç‰ˆç»´æŠ¤è€…： 钟宇 TripleX Chung <xxx.phy@gmail.com> - ä¸æ–‡ç‰ˆç¿»è¯‘者： 钟宇 TripleX Chung <xxx.phy@gmail.com> - 时奎亮 Alex Shi <alex.shi@linux.alibaba.com> - ä¸æ–‡ç‰ˆæ ¡è¯‘者： æŽé˜³ Li Yang <leoyang.li@nxp.com> - çŽ‹èª Wang Cong <xiyou.wangcong@gmail.com> +:æ ¡è¯‘: + - æŽé˜³ Li Yang <leoyang.li@nxp.com> + - çŽ‹èª Wang Cong <xiyou.wangcong@gmail.com> -å¦‚ä½•è®©ä½ çš„æ”¹åŠ¨è¿›å…¥å†…æ ¸ -====================== +æ交补ä¸ï¼šå¦‚ä½•è®©ä½ çš„æ”¹åŠ¨è¿›å…¥å†…æ ¸ +================================ 对于想è¦å°†æ”¹åŠ¨æ交到 Linux å†…æ ¸çš„ä¸ªäººæˆ–è€…å…¬å¸æ¥è¯´ï¼Œå¦‚æžœä¸ç†Ÿæ‚‰â€œè§„矩â€ï¼Œ -æ交的æµç¨‹ä¼šè®©äººç•æƒ§ã€‚本文档收集了一系列建议，这些建议å¯ä»¥å¤§å¤§çš„æé«˜ä½ +æ交的æµç¨‹ä¼šè®©äººç•æƒ§ã€‚本文档包å«äº†ä¸€ç³»åˆ—建议，å¯ä»¥å¤§å¤§æé«˜ä½ çš„æ”¹åŠ¨è¢«æŽ¥å—的机会. -以下文档å«æœ‰å¤§é‡ç®€æ´çš„建议， 具体请è§ï¼š -:ref:`Documentation/process <development_process_main>` -åŒæ ·ï¼Œ:ref:`Documentation/translations/zh_CN/process/submit-checklist.rst <cn_submitchecklist>` -给出在æ交代ç å‰éœ€è¦æ£€æŸ¥çš„项目的列表。 +本文档以较为简æ´çš„行文给出了大é‡å»ºè®®ã€‚å…³äºŽå†…æ ¸å¼€å‘æµç¨‹å¦‚何进行的详细信æ¯ï¼Œ +å‚è§ï¼š Documentation/translations/zh_CN/process/development-process.rst 。 +Documentation/translations/zh_CN/process/submit-checklist.rst 给出了一系列 +æ交补ä¸ä¹‹å‰è¦æ£€æŸ¥çš„äº‹é¡¹ã€‚è®¾å¤‡æ ‘ç›¸å…³çš„è¡¥ä¸ï¼Œè¯·å‚阅 +Documentation/devicetree/bindings/submitting-patches.rst 。 -å…¶ä¸è®¸å¤šæ¥éª¤æ述了Git版本控制系统的默认行为；如果您使用Gitæ¥å‡†å¤‡è¡¥ä¸ï¼Œ -您将å‘现它为您完æˆçš„大部分机械工作，尽管您ä»ç„¶éœ€è¦å‡†å¤‡å’Œè®°å½•ä¸€ç»„åˆç†çš„ -è¡¥ä¸ã€‚一般æ¥è¯´ï¼Œä½¿ç”¨gitå°†ä½¿æ‚¨ä½œä¸ºå†…æ ¸å¼€å‘人员的生活更轻æ¾ã€‚ +本文档å‡è®¾æ‚¨æ£åœ¨ä½¿ç”¨ ``git`` å‡†å¤‡ä½ çš„è¡¥ä¸ã€‚如果您ä¸ç†Ÿæ‚‰ ``git`` ，最好å¦ä¹ +å¦‚ä½•ä½¿ç”¨å®ƒï¼Œè¿™å°†ä½¿æ‚¨ä½œä¸ºå†…æ ¸å¼€å‘人员的生活å˜å¾—æ›´åŠ è½»æ¾ã€‚ +部分åç³»ç»Ÿå’Œç»´æŠ¤äººå‘˜çš„æ ‘æœ‰ä¸€äº›å…³äºŽå…¶å·¥ä½œæµç¨‹å’Œè¦æ±‚çš„é¢å¤–ä¿¡æ¯ï¼Œè¯·å‚阅 +Documentation/process/maintainer-handbooks.rst 。 -0) 获å–当å‰æºç æ ‘ ------------------ +获å–当å‰æºç æ ‘ +-------------- -如果您没有一个å¯ä»¥ä½¿ç”¨å½“å‰å†…æ ¸æºä»£ç çš„å˜å‚¨åº“，请使用git获å–ä¸€ä¸ªã€‚æ‚¨å°†è¦ -从主线å˜å‚¨åº“开始，它å¯ä»¥é€šè¿‡ä»¥ä¸‹æ–¹å¼èŽ·å–:: +如果您手头没有当å‰å†…æ ¸æºä»£ç çš„å˜å‚¨åº“，请使用 ``git`` 获å–一份。您需è¦å…ˆèŽ·å– +主线å˜å‚¨åº“，它å¯ä»¥é€šè¿‡ä»¥ä¸‹å‘½ä»¤æ‹‰å–:: - git clone git://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git + git clone git://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git -但是，请注æ„，您å¯èƒ½ä¸å¸Œæœ›ç›´æŽ¥é’ˆå¯¹ä¸»çº¿æ ‘进行开å‘。大多数åç³»ç»Ÿç»´æŠ¤äººå‘˜è¿ +但是，请注æ„，您å¯èƒ½ä¸æƒ³ç›´æŽ¥é’ˆå¯¹ä¸»çº¿æ ‘进行开å‘。大多数åç³»ç»Ÿç»´æŠ¤äººå‘˜è¿ è¡Œè‡ªå·±çš„æ ‘ï¼Œå¹¶å¸Œæœ›çœ‹åˆ°é’ˆå¯¹è¿™äº›æ ‘å‡†å¤‡çš„è¡¥ä¸ã€‚请å‚è§MAINTAINERS文件ä¸åç³» -统的 **T:** é¡¹ä»¥æŸ¥æ‰¾è¯¥æ ‘ï¼Œæˆ–è€…ç®€å•åœ°è¯¢é—®ç»´æŠ¤è€…è¯¥æ ‘æ˜¯å¦æœªåœ¨å…¶ä¸åˆ—出。 - -ä»ç„¶å¯ä»¥é€šè¿‡tarballsä¸‹è½½å†…æ ¸ç‰ˆæœ¬ï¼ˆå¦‚ä¸‹ä¸€èŠ‚æ‰€è¿°ï¼‰ï¼Œä½†è¿™æ˜¯è¿›è¡Œå†…æ ¸å¼€å‘çš„ -一ç§å›°éš¾çš„æ–¹å¼ã€‚ - -1) "diff -up" -------------- - -使用 "diff -up" 或者 "diff -uprN" æ¥åˆ›å»ºè¡¥ä¸ã€‚ - -æ‰€æœ‰å†…æ ¸çš„æ”¹åŠ¨ï¼Œéƒ½æ˜¯ä»¥è¡¥ä¸çš„å½¢å¼å‘ˆçŽ°çš„，补ä¸ç”± diff(1) 生æˆã€‚创建补ä¸çš„ -时候，è¦ç¡®è®¤å®ƒæ˜¯ä»¥ "unified diff" æ ¼å¼åˆ›å»ºçš„，这ç§æ ¼å¼ç”± diff(1) çš„ '-u' -å‚数生æˆã€‚而且，请使用 '-p' å‚æ•°ï¼Œé‚£æ ·ä¼šæ˜¾ç¤ºæ¯ä¸ªæ”¹åŠ¨æ‰€åœ¨çš„C函数，使得 -产生的补ä¸å®¹æ˜“读得多。补ä¸åº”è¯¥åŸºäºŽå†…æ ¸æºä»£ç æ ‘çš„æ ¹ç›®å½•ï¼Œè€Œä¸æ˜¯é‡Œè¾¹çš„ä»» -何å目录。 - -为一个å•ç‹¬çš„文件创建补ä¸ï¼Œä¸€èˆ¬æ¥è¯´è¿™æ ·åšå°±å¤Ÿäº†:: - - SRCTREE=linux - MYFILE=drivers/net/mydriver.c +统的 **T:** é¡¹ä»¥æŸ¥æ‰¾è¯¥æ ‘ï¼Œæˆ–è€…ç›´æŽ¥è¯¢é—®ç»´æŠ¤è€…è¯¥æ ‘æ˜¯å¦æœªåœ¨å…¶ä¸åˆ—出。 - cd $SRCTREE - cp $MYFILE $MYFILE.orig - vi $MYFILE # make your change - cd .. - diff -up $SRCTREE/$MYFILE{.orig,} > /tmp/patch +.. _zh_describe_changes: -为多个文件创建补ä¸ï¼Œä½ å¯ä»¥è§£å¼€ä¸€ä¸ªæ²¡æœ‰ä¿®æ”¹è¿‡çš„å†…æ ¸æºä»£ç æ ‘ï¼Œç„¶åŽå’Œä½ 自 -己的代ç æ ‘ä¹‹é—´åš diff 。例如:: - - MYSRC=/devel/linux - - tar xvfz linux-3.19.tar.gz - mv linux-3.19 linux-3.19-vanilla - diff -uprN -X linux-3.19-vanilla/Documentation/dontdiff \ - linux-3.19-vanilla $MYSRC > /tmp/patch - -"dontdiff" æ˜¯å†…æ ¸åœ¨ç¼–è¯‘çš„æ—¶å€™äº§ç”Ÿçš„æ–‡ä»¶çš„åˆ—è¡¨ï¼Œåˆ—è¡¨ä¸çš„文件在 diff(1) -产生的补ä¸é‡Œä¼šè¢«è·³è¿‡ã€‚ - -ç¡®å®šä½ çš„è¡¥ä¸é‡Œæ²¡æœ‰åŒ…å«ä»»ä½•ä¸å±žäºŽè¿™æ¬¡è¡¥ä¸æ交的é¢å¤–文件。记得在用diff(1) -生æˆè¡¥ä¸ä¹‹åŽï¼Œå®¡é˜…一次补ä¸ï¼Œä»¥ç¡®ä¿å‡†ç¡®ã€‚ - -å¦‚æžœä½ çš„æ”¹åŠ¨å¾ˆæ•£ä¹±ï¼Œä½ åº”è¯¥ç ”ç©¶ä¸€ä¸‹å¦‚ä½•å°†è¡¥ä¸åˆ†å‰²æˆç‹¬ç«‹çš„部分，将改动分 -割æˆä¸€ç³»åˆ—åˆä¹Žé€»è¾‘çš„æ¥éª¤ã€‚è¿™æ ·æ›´å®¹æ˜“è®©å…¶ä»–å†…æ ¸å¼€å‘è€…å®¡æ ¸ï¼Œå¦‚æžœä½ æƒ³ä½ çš„ -è¡¥ä¸è¢«æŽ¥å—，这是很é‡è¦çš„。请å‚阅： -:ref:`cn_split_changes` - -å¦‚æžœä½ ç”¨ ``git`` , ``git rebase -i`` å¯ä»¥å¸®åŠ©ä½ è¿™ä¸€ç‚¹ã€‚å¦‚æžœä½ ä¸ç”¨ ``git``, -``quilt`` <https://savannah.nongnu.org/projects/quilt> å¦å¤–一个æµè¡Œçš„选择。 - -.. _cn_describe_changes: - -2) æè¿°ä½ çš„æ”¹åŠ¨ ---------------- +æè¿°ä½ çš„æ”¹åŠ¨ +------------ æè¿°ä½ çš„é—®é¢˜ã€‚æ— è®ºæ‚¨çš„è¡¥ä¸æ˜¯ä¸€è¡Œé”™è¯¯ä¿®å¤è¿˜æ˜¯5000行新功能，都必须有一个潜在 -的问题激励您完æˆè¿™é¡¹å·¥ä½œã€‚让审稿人相信有一个问题值得解决，让他们读完第一段 -是有æ„义的。 +的问题激励您完æˆè¿™é¡¹å·¥ä½œã€‚说æœå®¡é˜…者相信有一个问题值得解决，让他们读完第一段 +åŽå°±èƒ½æ˜Žç™½è¿™ä¸€ç‚¹ã€‚ æ述用户å¯è§çš„å½±å“。直接崩溃和é”定是相当有说æœåŠ›çš„，但并ä¸æ˜¯æ‰€æœ‰çš„错误都那么 -æ˜Žç›®å¼ èƒ†ã€‚å³ä½¿åœ¨ä»£ç 审查期间å‘现了这个问题，也è¦æ述一下您认为它å¯èƒ½å¯¹ç”¨æˆ·äº§ +æ˜Žç›®å¼ èƒ†ã€‚å³ä½¿åœ¨ä»£ç 审阅期间å‘现了这个问题，也è¦æ述一下您认为它å¯èƒ½å¯¹ç”¨æˆ·äº§ 生的影å“。请记ä½ï¼Œå¤§å¤šæ•°Linux安装è¿è¡Œçš„å†…æ ¸æ¥è‡ªäºŒçº§ç¨³å®šæ ‘或特定于供应商/äº§å“ çš„æ ‘ï¼Œåªä»Žä¸Šæ¸¸ç²¾é€‰ç‰¹å®šçš„è¡¥ä¸ï¼Œå› æ¤è¯·åŒ…å«ä»»ä½•å¯ä»¥å¸®åŠ©æ‚¨å°†æ›´æ”¹å®šä½åˆ°ä¸‹æ¸¸çš„内容： 触å‘的场景ã€DMESG的摘录ã€å´©æºƒæè¿°ã€æ€§èƒ½å›žå½’ã€å»¶è¿Ÿå°–å³°ã€é”定ç‰ã€‚ -é‡åŒ–优化和æƒè¡¡ã€‚如果您声称在性能ã€å†…å˜æ¶ˆè€—ã€å †æ ˆå 用空间或二进制大å°æ–¹é¢æœ‰æ‰€ -改进，请包括支æŒå®ƒä»¬çš„æ•°å—。但也è¦æè¿°ä¸æ˜Žæ˜¾çš„æˆæœ¬ã€‚优化通常ä¸æ˜¯å…费的，而是 -在CPUã€å†…å˜å’Œå¯è¯»æ€§ä¹‹é—´è¿›è¡Œæƒè¡¡ï¼›æˆ–者，探索性的工作，在ä¸åŒçš„工作负载之间进 +è´¨é‡ä¼˜åŒ–å’Œæƒè¡¡ã€‚如果您声称在性能ã€å†…å˜æ¶ˆè€—ã€å †æ ˆå 用空间或二进制大å°æ–¹é¢æœ‰æ‰€ +改进，请包括支æŒå®ƒä»¬çš„æ•°æ®ã€‚但也è¦æè¿°ä¸æ˜Žæ˜¾çš„æˆæœ¬ã€‚优化通常ä¸æ˜¯é›¶æˆæœ¬çš„，而是 +在CPUã€å†…å˜å’Œå¯è¯»æ€§ä¹‹é—´è¿›è¡Œæƒè¡¡ï¼›æˆ–者，åšæŽ¢ç´¢æ€§çš„工作，在ä¸åŒçš„工作负载之间进 è¡Œæƒè¡¡ã€‚请æ述优化的预期缺点，以便审阅者å¯ä»¥æƒè¡¡æˆæœ¬å’Œæ”¶ç›Šã€‚ -一旦问题建立起æ¥ï¼Œå°±è¦è¯¦ç»†åœ°æ述一下您实际在åšä»€ä¹ˆã€‚对于审阅者æ¥è¯´ï¼Œç”¨ç®€å•çš„ -英è¯æ述代ç çš„å˜åŒ–是很é‡è¦çš„，以验è¯ä»£ç 的行为是å¦ç¬¦åˆæ‚¨çš„æ„愿。 +æ出问题之åŽï¼Œå°±è¦è¯¦ç»†åœ°æ述一下您实际在åšçš„技术细节。对于审阅者æ¥è¯´ï¼Œç”¨ç®€ç»ƒçš„ +英è¯æ述代ç çš„å˜åŒ–是很é‡è¦çš„，以验è¯ä»£ç 的行为是å¦ç¬¦åˆæ‚¨çš„æ„图。 -如果您将补ä¸æ述写在一个表å•ä¸ï¼Œè¿™ä¸ªè¡¨å•å¯ä»¥å¾ˆå®¹æ˜“地作为“æ交日志â€æ”¾å…¥Linux -çš„æºä»£ç 管ç†ç³»ç»Ÿgitä¸ï¼Œé‚£ä¹ˆç»´æŠ¤äººå‘˜å°†éžå¸¸æ„Ÿè°¢æ‚¨ã€‚è§ :ref:`cn_explicit_in_reply_to`. +如果您将补ä¸æ述写æˆâ€œæ ‡å‡†æ ¼å¼â€ï¼Œå¯ä»¥å¾ˆå®¹æ˜“地作为“æ交日志â€æ”¾å…¥Linuxçš„æºä»£ +ç 管ç†ç³»ç»Ÿ ``git`` ä¸ï¼Œé‚£ä¹ˆç»´æŠ¤äººå‘˜å°†éžå¸¸æ„Ÿè°¢æ‚¨ã€‚ +å‚è§ :ref:`zh_the_canonical_patch_format` 。 æ¯ä¸ªè¡¥ä¸åªè§£å†³ä¸€ä¸ªé—®é¢˜ã€‚å¦‚æžœä½ çš„æ述开始å˜é•¿ï¼Œè¿™å°±è¡¨æ˜Žä½ å¯èƒ½éœ€è¦æ‹†åˆ†ä½ çš„è¡¥ä¸ã€‚ -è¯·è§ :ref:`cn_split_changes` +è¯·è§ :ref:`zh_split_changes` 。 -æ交或é‡æ–°æ交修补程åºæˆ–修补程åºç³»åˆ—时，请包括完整的修补程åºè¯´æ˜Žå’Œç†ç”±ã€‚ä¸è¦ +æ交或é‡æ–°æ交补ä¸æˆ–è¡¥ä¸ç³»åˆ—时，请包括完整的补ä¸è¯´æ˜Žå’Œç†ç”±ã€‚ä¸è¦ åªè¯´è¿™æ˜¯è¡¥ä¸ï¼ˆç³»åˆ—ï¼‰çš„ç¬¬å‡ ç‰ˆã€‚ä¸è¦æœŸæœ›å系统维护人员引用更早的补ä¸ç‰ˆæœ¬æˆ–引用 URLæ¥æŸ¥æ‰¾è¡¥ä¸æ述并将其放入补ä¸ä¸ã€‚也就是说，补ä¸ï¼ˆç³»åˆ—）åŠå…¶æ述应该是独立的。 -这对维护人员和审查人员都有好处。一些评审者å¯èƒ½ç”šè‡³æ²¡æœ‰æ”¶åˆ°è¡¥ä¸çš„早期版本。 +这对维护人员和审阅者都有好处。一些审阅者å¯èƒ½ç”šè‡³æ²¡æœ‰æ”¶åˆ°è¡¥ä¸çš„早期版本。 -æè¿°ä½ åœ¨å‘½ä»¤è¯æ°”ä¸çš„å˜åŒ–，例如“make xyzzy do frotzâ€è€Œä¸æ˜¯â€œ[This patch]make +用祈使å¥æè¿°ä½ çš„å˜æ›´ï¼Œä¾‹å¦‚“make xyzzy do frotzâ€è€Œä¸æ˜¯â€œ[This patch]make xyzzy do frotzâ€æˆ–“[I]changed xyzzy to do frotzâ€ï¼Œå°±å¥½åƒä½ 在命令代ç åº“æ”¹å˜ å®ƒçš„è¡Œä¸ºä¸€æ ·ã€‚ -如果修补程åºä¿®å¤äº†ä¸€ä¸ªè®°å½•çš„bugæ¡ç›®ï¼Œè¯·æŒ‰ç¼–å·å’ŒURL引用该bugæ¡ç›®ã€‚如果补ä¸æ¥ -自邮件列表讨论，请给出邮件列表å˜æ¡£çš„URL；使用带有 ``Message-ID`` çš„ -https://lore.kernel.org/ é‡å®šå‘，以确ä¿é“¾æŽ¥ä¸ä¼šè¿‡æ—¶ã€‚ - -但是，在没有外部资æºçš„情况下，尽é‡è®©ä½ 的解释å¯ç†è§£ã€‚除了æ供邮件列表å˜æ¡£æˆ– -bugçš„URL之外，还è¦æ€»ç»“需è¦æ交补ä¸çš„相关讨论è¦ç‚¹ã€‚ - -如果您想è¦å¼•ç”¨ä¸€ä¸ªç‰¹å®šçš„æ交，ä¸è¦åªå¼•ç”¨æ交的 SHA-1 ID。还请包括æ交的一行 +如果您想è¦å¼•ç”¨ä¸€ä¸ªç‰¹å®šçš„æ交，ä¸è¦åªå¼•ç”¨æ交的SHA-1 ID。还请包括æ交的一行 摘è¦ï¼Œä»¥ä¾¿äºŽå®¡é˜…者了解它是关于什么的。例如:: Commit e21d2170f36602ae2708 ("video: remove unnecessary @@ -144,82 +94,104 @@ bugçš„URL之外，还è¦æ€»ç»“需è¦æ交补ä¸çš„相关讨论è¦ç‚¹ã€‚ platform_set_drvdata(), but left the variable "dev" unused, delete it. -您还应该确ä¿è‡³å°‘使用å‰12ä½ SHA-1 ID. å†…æ ¸å˜å‚¨åº“包å«*许多*对象，使与较çŸçš„ID +您还应该确ä¿è‡³å°‘使用å‰12ä½SHA-1 IDã€‚å†…æ ¸å˜å‚¨åº“åŒ…å« *许多* 对象，使较çŸçš„ID å‘生冲çªçš„å¯èƒ½æ€§å¾ˆå¤§ã€‚è®°ä½ï¼Œå³ä½¿çŽ°åœ¨ä¸ä¼šä¸Žæ‚¨çš„å…个å—符IDå‘生冲çªï¼Œè¿™ç§æƒ…况 -å¯èƒ½äº”å¹´åŽæ”¹å˜ã€‚ +也å¯èƒ½åœ¨äº”å¹´åŽæ”¹å˜ã€‚ + +如果该å˜æ›´çš„相关讨论或背景信æ¯å¯ä»¥åœ¨ç½‘ä¸ŠæŸ¥é˜…ï¼Œè¯·åŠ ä¸Šâ€œLink:â€æ ‡ç¾æŒ‡å‘它。例如 +ä½ çš„è¡¥ä¸ä¿®å¤äº†ä¸€ä¸ªç¼ºé™·ï¼Œéœ€è¦æ·»åŠ 一个带有URLçš„æ ‡ç¾æŒ‡å‘邮件列表å˜æ¡£æˆ–缺陷跟踪器 +的相关报告；如果该补ä¸æ˜¯ç”±ä¸€äº›æ—©å…ˆé‚®ä»¶åˆ—表讨论或网络上的记录引起的，请指å‘它。 + +当链接到邮件列表å˜æ¡£æ—¶ï¼Œè¯·é¦–选lore.kernel.org邮件å˜æ¡£æœåŠ¡ã€‚用邮件ä¸çš„ +``Message-ID`` 头（去掉尖括å·ï¼‰å¯ä»¥åˆ›å»ºé“¾æŽ¥URL。例如:: + + Link: https://lore.kernel.org/r/30th.anniversary.repost@klaava.Helsinki.FI/ + +请检查该链接以确ä¿å¯ç”¨ä¸”指å‘æ£ç¡®çš„邮件。 -如果修补程åºä¿®å¤äº†ç‰¹å®šæ交ä¸çš„错误，例如，使用 ``git bisct`` ï¼Œè¯·ä½¿ç”¨å¸¦æœ‰å‰ -12个å—符SHA-1 ID çš„"Fixes:"æ ‡è®°å’Œå•è¡Œæ‘˜è¦ã€‚为了简化ä¸è¦å°†æ ‡è®°æ‹†åˆ†ä¸ºå¤šä¸ªï¼Œ -è¡Œã€æ ‡è®°ä¸å—分æžè„šæœ¬â€œ75列æ¢è¡Œâ€è§„则的é™åˆ¶ã€‚例如:: +ä¸è¿‡ï¼Œåœ¨æ²¡æœ‰å¤–部资æºçš„情况下，也è¦å°½é‡è®©ä½ 的解释å¯ç†è§£ã€‚除了æ供邮件列表å˜æ¡£æˆ– +缺陷的URL之外，还è¦éœ€è¦æ€»ç»“该补ä¸çš„相关讨论è¦ç‚¹ã€‚ - Fixes: 54a4f0239f2e ("KVM: MMU: make kvm_mmu_zap_page() return the number of pages it actually freed") +如果补ä¸ä¿®å¤äº†ç‰¹å®šæ交ä¸çš„错误，例如使用 ``git bisct`` å‘现了一个问题，请使用 +带有å‰12个å—符SHA-1 ID的“Fixes:â€æ ‡ç¾å’Œå•è¡Œæ‘˜è¦ã€‚为了简化解æžè„šæœ¬ï¼Œä¸è¦å°†è¯¥ +æ ‡ç¾æ‹†åˆ†ä¸ºå¤šè¡Œï¼Œæ ‡ç¾ä¸å—“75列æ¢è¡Œâ€è§„则的é™åˆ¶ã€‚例如:: -下列 ``git config`` 设置å¯ä»¥æ·»åŠ 让 ``git log``, ``git show`` æ¼‚äº®çš„æ˜¾ç¤ºæ ¼å¼:: + Fixes: 54a4f0239f2e ("KVM: MMU: make kvm_mmu_zap_page() return the number of pages it actually freed") + +下列 ``git config`` 设置å¯ä»¥è®© ``git log``, ``git show`` å¢žåŠ ä¸Šè¿°é£Žæ ¼çš„æ˜¾ç¤ºæ ¼å¼:: [core] abbrev = 12 [pretty] fixes = Fixes: %h (\"%s\") -.. _cn_split_changes: +使用示例:: + + $ git log -1 --pretty=fixes 54a4f0239f2e + Fixes: 54a4f0239f2e ("KVM: MMU: make kvm_mmu_zap_page() return the number of pages it actually freed") -3) æ‹†åˆ†ä½ çš„æ”¹åŠ¨ ---------------- +.. _zh_split_changes: -å°†æ¯ä¸ªé€»è¾‘更改分隔æˆä¸€ä¸ªå•ç‹¬çš„è¡¥ä¸ã€‚ +æ‹†åˆ†ä½ çš„æ”¹åŠ¨ +------------ + +å°†æ¯ä¸ª **逻辑更改** 拆分æˆä¸€ä¸ªå•ç‹¬çš„è¡¥ä¸ã€‚ ä¾‹å¦‚ï¼Œå¦‚æžœä½ çš„æ”¹åŠ¨é‡ŒåŒæ—¶æœ‰bugä¿®æ£å’Œæ€§èƒ½ä¼˜åŒ–，那么把这些改动拆分到两个或 -者更多的补ä¸æ–‡ä»¶ä¸ã€‚å¦‚æžœä½ çš„æ”¹åŠ¨åŒ…å«å¯¹API的修改，并且修改了驱动程åºæ¥é€‚ -应这些新的API，那么把这些修改分æˆä¸¤ä¸ªè¡¥ä¸ã€‚ +者更多的补ä¸æ–‡ä»¶ä¸ã€‚å¦‚æžœä½ çš„æ”¹åŠ¨åŒ…å«å¯¹APIçš„ä¿®æ”¹ï¼Œå¹¶ä¸”å¢žåŠ äº†ä¸€ä¸ªä½¿ç”¨è¯¥æ–°API +的驱动，那么把这些修改分æˆä¸¤ä¸ªè¡¥ä¸ã€‚ å¦ä¸€æ–¹é¢ï¼Œå¦‚æžœä½ å°†ä¸€ä¸ªå•ç‹¬çš„改动åšæˆå¤šä¸ªè¡¥ä¸æ–‡ä»¶ï¼Œé‚£ä¹ˆå°†å®ƒä»¬åˆå¹¶æˆä¸€ä¸ª å•ç‹¬çš„è¡¥ä¸æ–‡ä»¶ã€‚è¿™æ ·ä¸€ä¸ªé€»è¾‘ä¸Šå•ç‹¬çš„改动åªè¢«åŒ…å«åœ¨ä¸€ä¸ªè¡¥ä¸æ–‡ä»¶é‡Œã€‚ -如果有一个补ä¸ä¾èµ–å¦å¤–一个补ä¸æ¥å®Œæˆå®ƒçš„改动，那没问题。简å•çš„åœ¨ä½ çš„è¡¥ -ä¸æ述里指出“这个补ä¸ä¾èµ–æŸè¡¥ä¸â€å°±å¥½äº†ã€‚ +需è¦è®°ä½çš„一点是，æ¯ä¸ªè¡¥ä¸çš„更改都应易于ç†è§£ï¼Œä»¥ä¾¿å®¡é˜…者验è¯ã€‚æ¯ä¸ªè¡¥ä¸éƒ½åº”该 +对其价值进行é˜è¿°ã€‚ + +如果有一个补ä¸ä¾èµ–å¦å¤–一个补ä¸æ¥å®Œæˆå®ƒçš„æ”¹åŠ¨ï¼Œé‚£æ²¡é—®é¢˜ã€‚ç›´æŽ¥åœ¨ä½ çš„è¡¥ +ä¸æ述里指出 **“这个补ä¸ä¾èµ–æŸè¡¥ä¸â€** 就好了。 -在将您的更改划分为一系列补ä¸æ—¶ï¼Œè¦ç‰¹åˆ«æ³¨æ„ç¡®ä¿å†…æ ¸åœ¨ç³»åˆ—ä¸çš„æ¯ä¸ªè¡¥ä¸ä¹‹åŽ -都能æ£å¸¸æž„建和è¿è¡Œã€‚使用 ``git bisect`` æ¥è¿½è¸ªé—®é¢˜çš„å¼€å‘者å¯èƒ½ä¼šåœ¨ä»»ä½•æ—¶ -å€™åˆ†å‰²ä½ çš„è¡¥ä¸ç³»åˆ—ï¼›å¦‚æžœä½ åœ¨ä¸é—´å¼•å…¥é”™è¯¯ï¼Œä»–们ä¸ä¼šæ„Ÿè°¢ä½ 。 +在将您的更改划分为一系列补ä¸æ—¶ï¼Œè¦ç‰¹åˆ«æ³¨æ„ç¡®ä¿å†…æ ¸åœ¨åº”ç”¨ç³»åˆ—ä¸çš„æ¯ä¸ªè¡¥ä¸ä¹‹åŽ +都能æ£å¸¸æž„建和è¿è¡Œã€‚使用 ``git bisect`` æ¥è¿½è¸ªé—®é¢˜çš„å¼€å‘者å¯èƒ½ä¼šåœ¨ä»»ä½•åœ°æ–¹åˆ† +å‰²ä½ çš„è¡¥ä¸ç³»åˆ—ï¼›å¦‚æžœä½ åœ¨ä¸é—´å¼•å…¥é”™è¯¯ï¼Œä»–们ä¸ä¼šæ„Ÿè°¢ä½ 。 -å¦‚æžœä½ ä¸èƒ½å°†è¡¥ä¸æµ“缩æˆæ›´å°‘的文件，那么æ¯æ¬¡å¤§çº¦å‘é€å‡º15个，然åŽç‰å¾…审查 +å¦‚æžœä½ ä¸èƒ½å°†è¡¥ä¸ç³»åˆ—浓缩得更å°ï¼Œé‚£ä¹ˆæ¯æ¬¡å¤§çº¦å‘é€å‡º15个补ä¸ï¼Œç„¶åŽç‰å¾…审阅 和集æˆã€‚ -4) æ£€æŸ¥ä½ çš„æ›´æ”¹é£Žæ ¼ -------------------- +æ£€æŸ¥ä½ çš„æ›´æ”¹é£Žæ ¼ +---------------- -检查您的补ä¸æ˜¯å¦å˜åœ¨åŸºæœ¬æ ·å¼å†²çªï¼Œè¯¦ç»†ä¿¡æ¯å¯åœ¨ -:ref:`Documentation/translations/zh_CN/process/coding-style.rst <cn_codingstyle>` -ä¸æ‰¾åˆ°ã€‚如果ä¸è¿™æ ·åšï¼Œåªä¼šæµªè´¹å®¡ç¨¿äººçš„æ—¶é—´ï¼Œå¹¶ä¸”ä¼šå¯¼è‡´ä½ çš„è¡¥ä¸è¢«æ‹’ç»ï¼Œç”šè‡³ +检查您的补ä¸æ˜¯å¦è¿åäº†åŸºæœ¬æ ·å¼è§„定，详细信æ¯å‚è§ +Documentation/translations/zh_CN/process/coding-style.rst +ä¸æ‰¾åˆ°ã€‚如果ä¸è¿™æ ·åšï¼Œåªä¼šæµªè´¹å®¡é˜…è€…çš„æ—¶é—´ï¼Œå¹¶ä¸”ä¼šå¯¼è‡´ä½ çš„è¡¥ä¸è¢«æ‹’ç»ï¼Œç”šè‡³ å¯èƒ½æ²¡æœ‰è¢«é˜…读。 一个é‡è¦çš„例外是在将代ç 从一个文件移动到å¦ä¸€ä¸ªæ–‡ä»¶æ—¶â€”—在这ç§æƒ…况下，您ä¸åº” 该在移动代ç çš„åŒä¸€ä¸ªè¡¥ä¸ä¸ä¿®æ”¹ç§»åŠ¨çš„代ç 。这清楚地æ述了移动代ç 和您的更改 -的行为。这大大有助于审查实际差异，并å…许工具更好地跟踪代ç 本身的历å²ã€‚ +的行为。这大大有助于审阅实际差异，并å…许工具更好地跟踪代ç 本身的历å²ã€‚ 在æ交之å‰ï¼Œä½¿ç”¨è¡¥ä¸æ ·å¼æ£€æŸ¥ç¨‹åºæ£€æŸ¥è¡¥ä¸ï¼ˆscripts/check patch.pl）。ä¸è¿‡ï¼Œ 请注æ„ï¼Œæ ·å¼æ£€æŸ¥ç¨‹åºåº”该被视为一个指å—，而ä¸æ˜¯ä½œä¸ºäººç±»åˆ¤æ–的替代å“。如果您 -的代ç 看起æ¥æ›´å¥½ï¼Œä½†æœ‰è¿è§„行为，那么最好ä¸è¦ä½¿ç”¨å®ƒã€‚ +的代ç 看起æ¥æ›´å¥½ï¼Œä½†æœ‰è¿è§„行为，那么最好别管它。 检查者报告三个级别： - ERROR：很å¯èƒ½å‡ºé”™çš„事情 - - WARNING：需è¦ä»”细审查的事项 + - WARNING：需è¦ä»”细审阅的事项 - CHECK：需è¦æ€è€ƒçš„事情 您应该能够判æ–您的补ä¸ä¸å˜åœ¨çš„所有è¿è§„行为。 -5) 选择补ä¸æ”¶ä»¶äºº ------------------ +选择补ä¸æ”¶ä»¶äºº +-------------- -您应该总是在任何补ä¸ä¸Šå¤åˆ¶ç›¸åº”çš„å系统维护人员，以获得他们维护的代ç ；查看 +您应该总是知会任何补ä¸ç›¸åº”代ç çš„å系统维护人员；查看 维护人员文件和æºä»£ç 修订历å²è®°å½•ï¼Œä»¥äº†è§£è¿™äº›ç»´æŠ¤äººå‘˜æ˜¯è°ã€‚脚本 -scripts/get_Maintainer.pl在这个æ¥éª¤ä¸éžå¸¸æœ‰ç”¨ã€‚如果您找ä¸åˆ°æ£åœ¨å·¥ä½œçš„å系统 +scripts/get_maintainer.pl在这个æ¥éª¤ä¸éžå¸¸æœ‰ç”¨ã€‚如果您找ä¸åˆ°æ£åœ¨å·¥ä½œçš„å系统 的维护人员，那么Andrew Morton（akpm@linux-foundation.org）将充当最åŽçš„维护 人员。 -您通常还应该选择至少一个邮件列表æ¥æŽ¥æ”¶è¡¥ä¸é›†çš„。linux-kernel@vger.kernel.org -作为最åŽä¸€ä¸ªè§£å†³åŠžæ³•çš„列表，但是这个列表上的体积已ç»å¼•èµ·äº†è®¸å¤šå¼€å‘人员的拒ç»ã€‚ +您通常还应该选择至少一个邮件列表æ¥æŽ¥æ”¶è¡¥ä¸é›†çš„副本。linux-kernel@vger.kernel.org +是所有补ä¸çš„默认列表，但是这个列表的æµé‡å·²ç»å¯¼è‡´äº†è®¸å¤šå¼€å‘人员ä¸å†çœ‹å®ƒã€‚ 在MAINTAINERS文件ä¸æŸ¥æ‰¾å系统特定的列表；您的补ä¸å¯èƒ½ä¼šåœ¨é‚£é‡Œå¾—到更多的关注。 ä¸è¿‡ï¼Œè¯·ä¸è¦å‘é€åžƒåœ¾é‚®ä»¶åˆ°æ— 关的列表。 @@ -229,189 +201,170 @@ http://vger.kernel.org/vger-lists.html 上找到它们的列表。ä¸è¿‡ï¼Œä¹Ÿæœ ä¸è¦ä¸€æ¬¡å‘é€è¶…过15个补ä¸åˆ°vger邮件列表ï¼ï¼ï¼ï¼ -Linus Torvalds 是决定改动能å¦è¿›å…¥ Linux å†…æ ¸çš„æœ€ç»ˆè£å†³è€…。他的 e-mail -地å€æ˜¯ <torvalds@linux-foundation.org> 。他收到的 e-mail 很多，所以一般 -çš„è¯´ï¼Œæœ€å¥½åˆ«ç»™ä»–å‘ e-mail。 - -如果您有修å¤å¯åˆ©ç”¨å®‰å…¨æ¼æ´žçš„è¡¥ä¸ï¼Œè¯·å°†è¯¥è¡¥ä¸å‘é€åˆ° security@kernel.org。对于 -严é‡çš„bug，å¯ä»¥è€ƒè™‘çŸæœŸæš‚åœä»¥å…许分销商å‘用户å‘布补ä¸ï¼›åœ¨è¿™ç§æƒ…况下，显然ä¸åº” -将补ä¸å‘é€åˆ°ä»»ä½•å…¬å…±åˆ—表。 +Linus Torvalds是决定改动能å¦è¿›å…¥ Linux å†…æ ¸çš„æœ€ç»ˆè£å†³è€…。他的邮件地å€æ˜¯ +torvalds@linux-foundation.org 。他收到的邮件很多，所以一般æ¥è¯´æœ€å¥½ **别** +给他å‘邮件。 -ä¿®å¤å·²å‘å¸ƒå†…æ ¸ä¸ä¸¥é‡é”™è¯¯çš„è¡¥ä¸ç¨‹åºåº”该指å‘ç¨³å®šç‰ˆç»´æŠ¤äººå‘˜ï¼Œæ–¹æ³•æ˜¯æ”¾è¿™æ ·çš„ä¸€è¡Œ:: +如果您有修å¤å¯åˆ©ç”¨å®‰å…¨æ¼æ´žçš„è¡¥ä¸ï¼Œè¯·å°†è¯¥è¡¥ä¸å‘é€åˆ° security@kernel.org 。对于 +严é‡çš„bug，å¯ä»¥è€ƒè™‘çŸæœŸç¦ä»¤ä»¥å…许分销商（有时间）å‘用户å‘布补ä¸ï¼›åœ¨è¿™ç§æƒ…况下， +显然ä¸åº”将补ä¸å‘é€åˆ°ä»»ä½•å…¬å…±åˆ—表。 +å‚è§ Documentation/translations/zh_CN/admin-guide/security-bugs.rst 。 - Cc: stable@vger.kernel.org +ä¿®å¤å·²å‘å¸ƒå†…æ ¸ä¸ä¸¥é‡é”™è¯¯çš„è¡¥ä¸ç¨‹åºåº”该抄é€ç»™ç¨³å®šç‰ˆç»´æŠ¤äººå‘˜ï¼Œæ–¹æ³•æ˜¯æŠŠä»¥ä¸‹åˆ—è¡Œ +放进补ä¸çš„ç¾å‡†åŒºï¼ˆæ³¨æ„，ä¸æ˜¯ç”µå邮件收件人）:: -进入补ä¸çš„ç¾å‡†åŒºï¼ˆæ³¨æ„，ä¸æ˜¯ç”µå邮件收件人）。除了这个文件之外，您还应该阅读 -:ref:`Documentation/process/stable-kernel-rules.rst <stable_kernel_rules>` + Cc: stable@vger.kernel.org -但是，请注æ„，一些å系统维护人员希望得出他们自己的结论，å³å“ªäº›è¡¥ä¸åº”该被放到 -ç¨³å®šçš„æ ‘ä¸Šã€‚å°¤å…¶æ˜¯ç½‘ç»œç»´æŠ¤äººå‘˜ï¼Œä¸å¸Œæœ›çœ‹åˆ°å•ä¸ªå¼€å‘人员在补ä¸ä¸æ·»åŠ åƒä¸Šé¢è¿™æ · -的行。 +除了本文件之外，您还应该阅读 +Documentation/translations/zh_CN/process/stable-kernel-rules.rst 。 -如果更改影å“åˆ°ç”¨æˆ·å’Œå†…æ ¸æŽ¥å£ï¼Œè¯·å‘手册页维护人员（如维护人员文件ä¸æ‰€åˆ—）å‘é€ +如果更改影å“åˆ°ç”¨æˆ·ä¾§å†…æ ¸æŽ¥å£ï¼Œè¯·å‘手册页维护人员（如维护人员文件ä¸æ‰€åˆ—）å‘é€ æ‰‹å†Œé¡µè¡¥ä¸ï¼Œæˆ–至少å‘é€æ›´æ”¹é€šçŸ¥ï¼Œä»¥ä¾¿ä¸€äº›ä¿¡æ¯è¿›å…¥æ‰‹å†Œé¡µã€‚还应将用户空间API -更改å¤åˆ¶åˆ° linux-api@vger.kernel.org。 +更改抄é€åˆ° linux-api@vger.kernel.org 。 -6) 没有 MIME ç¼–ç ，没有链接，没有压缩，没有附件，åªæœ‰çº¯æ–‡æœ¬ ------------------------------------------------------------ +ä¸è¦MIMEç¼–ç ，ä¸è¦é“¾æŽ¥ï¼Œä¸è¦åŽ‹ç¼©ï¼Œä¸è¦é™„件，åªè¦çº¯æ–‡æœ¬ +------------------------------------------------------ Linus å’Œå…¶ä»–çš„å†…æ ¸å¼€å‘者需è¦é˜…è¯»å’Œè¯„è®ºä½ æäº¤çš„æ”¹åŠ¨ã€‚å¯¹äºŽå†…æ ¸å¼€å‘者æ¥è¯´ -，å¯ä»¥â€œå¼•ç”¨â€ä½ 的改动很é‡è¦ï¼Œä½¿ç”¨ä¸€èˆ¬çš„ e-mail 工具，他们就å¯ä»¥åœ¨ä½ çš„ +，å¯ä»¥â€œå¼•ç”¨â€ä½ 的改动很é‡è¦ï¼Œä½¿ç”¨ä¸€èˆ¬çš„邮件工具，他们就å¯ä»¥åœ¨ä½ çš„ 代ç 的任何ä½ç½®æ·»åŠ 评论。 -å› ä¸ºè¿™ä¸ªåŽŸå› ï¼Œæ‰€æœ‰çš„æ交的补ä¸éƒ½æ˜¯ e-mail ä¸â€œå†…嵌â€çš„。 +å› ä¸ºè¿™ä¸ªåŽŸå› ï¼Œæ‰€æœ‰çš„æ交的补ä¸éƒ½æ˜¯é‚®ä»¶ä¸â€œå†…嵌â€çš„。最简å•ï¼ˆå’ŒæŽ¨è）的方法就 +是使用 ``git send-email`` 。https://git-send-email.io 有 ``git send-email`` +的交互å¼æ•™ç¨‹ã€‚ + +å¦‚æžœä½ é€‰æ‹©ä¸ç”¨ ``git send-email`` ： .. warning:: - å¦‚æžœä½ ä½¿ç”¨å‰ªåˆ‡-ç²˜è´´ä½ çš„è¡¥ä¸ï¼Œå°å¿ƒä½ 的编辑器的自动æ¢è¡ŒåŠŸèƒ½ç ´åä½ çš„è¡¥ä¸ -ä¸è¦å°†è¡¥ä¸ä½œä¸º MIME ç¼–ç 的附件，ä¸ç®¡æ˜¯å¦åŽ‹ç¼©ã€‚很多æµè¡Œçš„ e-mail è½¯ä»¶ä¸ -是任何时候都将 MIME ç¼–ç 的附件当作纯文本å‘é€çš„ï¼Œè¿™ä¼šä½¿å¾—åˆ«äººæ— æ³•åœ¨ä½ çš„ -代ç ä¸åŠ 评论。å¦å¤–，MIME ç¼–ç 的附件会让 Linus 多花一点时间æ¥å¤„ç†ï¼Œè¿™å°± -é™ä½Žäº†ä½ 的改动被接å—çš„å¯èƒ½æ€§ã€‚ + å¦‚æžœä½ ä½¿ç”¨å‰ªåˆ‡-ç²˜è´´ä½ çš„è¡¥ä¸ï¼Œå°å¿ƒä½ 的编辑器的自动æ¢è¡ŒåŠŸèƒ½ç ´åä½ çš„è¡¥ä¸ -ä¾‹å¤–ï¼šå¦‚æžœä½ çš„é‚®é€’å‘˜å¼„å了补ä¸ï¼Œé‚£ä¹ˆæœ‰äººå¯èƒ½ä¼šè¦æ±‚ä½ ä½¿ç”¨mimeé‡æ–°å‘é€è¡¥ä¸ +ä¸è¦å°†è¡¥ä¸ä½œä¸ºMIMEç¼–ç 的附件，ä¸ç®¡æ˜¯å¦åŽ‹ç¼©ã€‚很多æµè¡Œçš„é‚®ä»¶è½¯ä»¶ä¸ +是任何时候都将MIMEç¼–ç 的附件当作纯文本å‘é€çš„ï¼Œè¿™ä¼šä½¿å¾—åˆ«äººæ— æ³•åœ¨ä½ çš„ +代ç ä¸åŠ 评论。å¦å¤–，MIMEç¼–ç 的附件会让Linus多花一点时间æ¥å¤„ç†ï¼Œè¿™å°± +é™ä½Žäº†ä½ 的改动被接å—çš„å¯èƒ½æ€§ã€‚ -请å‚阅 :ref:`Documentation/translations/zh_CN/process/email-clients.rst <cn_email_clients>` -以获å–有关é…置电å邮件客户端以使其ä¸å—å½±å“地å‘é€ä¿®è¡¥ç¨‹åºçš„æ示。 +ä¾‹å¤–ï¼šå¦‚æžœä½ çš„é‚®è·¯æŸå了补ä¸ï¼Œé‚£ä¹ˆæœ‰äººå¯èƒ½ä¼šè¦æ±‚ä½ ä½¿ç”¨MIMEé‡æ–°å‘é€è¡¥ä¸ã€‚ -7) e-mail çš„å¤§å° ----------------- +请å‚阅 Documentation/translations/zh_CN/process/email-clients.rst +以获å–有关é…置电å邮件客户端以使其ä¸å—å½±å“地å‘é€è¡¥ä¸çš„æ示。 -大的改动对邮件列表ä¸åˆé€‚，对æŸäº›ç»´æŠ¤è€…也ä¸åˆé€‚ã€‚å¦‚æžœä½ çš„è¡¥ä¸ï¼Œåœ¨ä¸åŽ‹ç¼© -的情况下，超过了300kBï¼Œé‚£ä¹ˆä½ æœ€å¥½å°†è¡¥ä¸æ”¾åœ¨ä¸€ä¸ªèƒ½é€šè¿‡ internet è®¿é—®çš„æœ -务器上，然åŽç”¨æŒ‡å‘ä½ çš„è¡¥ä¸çš„ URL 替代。但是请注æ„，如果您的补ä¸è¶…过了 -300kbï¼Œé‚£ä¹ˆå®ƒå‡ ä¹Žè‚¯å®šéœ€è¦è¢«ç ´å。 +回å¤å®¡é˜…æ„è§ +------------ -8）回å¤è¯„审æ„è§ ---------------- +ä½ çš„è¡¥ä¸å‡ 乎肯定会得到审阅者对补ä¸æ”¹è¿›æ–¹æ³•çš„评论（以回å¤é‚®ä»¶çš„å½¢å¼ï¼‰ã€‚您必须 +对这些评论作出回应；让补ä¸è¢«å¿½ç•¥çš„一个好办法就是忽略审阅者的æ„è§ã€‚直接回å¤é‚® +件æ¥å›žåº”æ„è§å³å¯ã€‚ä¸ä¼šå¯¼è‡´ä»£ç 更改的æ„è§æˆ–é—®é¢˜å‡ ä¹Žè‚¯å®šä¼šå¸¦æ¥æ³¨é‡Šæˆ–å˜æ›´æ—¥å¿—çš„ +改å˜ï¼Œä»¥ä¾¿ä¸‹ä¸€ä¸ªå®¡é˜…者更好地了解æ£åœ¨å‘生的事情。 -ä½ çš„è¡¥ä¸å‡ 乎肯定会得到评审者对补ä¸æ”¹è¿›æ–¹æ³•çš„评论。您必须对这些评论作出 -回应；让补ä¸è¢«å¿½ç•¥çš„一个好办法就是忽略审阅者的æ„è§ã€‚ä¸ä¼šå¯¼è‡´ä»£ç 更改的 -æ„è§æˆ–é—®é¢˜å‡ ä¹Žè‚¯å®šä¼šå¸¦æ¥æ³¨é‡Šæˆ–å˜æ›´æ—¥å¿—的改å˜ï¼Œä»¥ä¾¿ä¸‹ä¸€ä¸ªè¯„审者更好地了解 -æ£åœ¨å‘生的事情。 +一定è¦å‘Šè¯‰å®¡é˜…è€…ä½ åœ¨åšä»€ä¹ˆæ”¹å˜ï¼Œå¹¶æ„Ÿè°¢ä»–们的时间。代ç 审阅是一个累人且耗时的 +过程，审阅者有时会å˜å¾—æš´èºã€‚å³ä½¿åœ¨è¿™ç§æƒ…况下，也è¦ç¤¼è²Œåœ°å›žåº”并解决他们指出的 +问题。当å‘é€ä¸‹ä¸€ç‰ˆæ—¶ï¼Œåœ¨å°é¢é‚®ä»¶æˆ–独立补ä¸é‡ŒåŠ 上 ``patch changelog`` 说明与 +å‰ä¸€ç‰ˆæœ¬çš„ä¸åŒä¹‹å¤„（å‚è§ :ref:`zh_the_canonical_patch_format` ）。 -一定è¦å‘Šè¯‰å®¡ç¨¿äººä½ 在åšä»€ä¹ˆæ”¹å˜ï¼Œå¹¶æ„Ÿè°¢ä»–们的时间。代ç 审查是一个累人且 -耗时的过程，审查人员有时会å˜å¾—æš´èºã€‚å³ä½¿åœ¨è¿™ç§æƒ…况下，也è¦ç¤¼è²Œåœ°å›žåº”并 -解决他们指出的问题。 +.. _zh_resend_reminders: -9）ä¸è¦æ³„气或ä¸è€çƒ¦ -------------------- +ä¸è¦æ³„气或ä¸è€çƒ¦ +---------------- -æ交更改åŽï¼Œè¯·è€å¿ƒç‰å¾…。审阅者是忙碌的人，å¯èƒ½æ— 法立å³è®¿é—®æ‚¨çš„修补程åºã€‚ +æ交更改åŽï¼Œè¯·è€å¿ƒç‰å¾…。审阅者是大忙人，å¯èƒ½æ— 法立å³å®¡é˜…您的补ä¸ã€‚ -æ›¾å‡ ä½•æ—¶ï¼Œè¡¥ä¸æ›¾åœ¨æ²¡æœ‰è¯„论的情况下消失在空白ä¸ï¼Œä½†å¼€å‘è¿‡ç¨‹æ¯”çŽ°åœ¨æ›´åŠ é¡ºåˆ©ã€‚ +æ›¾å‡ ä½•æ—¶ï¼Œè¡¥ä¸æ›¾åœ¨æ²¡æ”¶åˆ°è¯„论的情况下消失在虚空ä¸ï¼Œä½†çŽ°åœ¨å¼€å‘è¿‡ç¨‹åº”è¯¥æ›´åŠ é¡ºåˆ©äº†ã€‚ 您应该在一周左å³çš„时间内收到评论；如果没有收到评论，请确ä¿æ‚¨å·²å°†è¡¥ä¸å‘é€ -到æ£ç¡®çš„ä½ç½®ã€‚在é‡æ–°æ交或è”系审阅者之å‰è‡³å°‘ç‰å¾…一周-在诸如åˆå¹¶çª—å£ä¹‹ç±»çš„ +到æ£ç¡®çš„ä½ç½®ã€‚在é‡æ–°æ交或è”系审阅者之å‰è‡³å°‘ç‰å¾…一周——在诸如åˆå¹¶çª—å£ä¹‹ç±»çš„ ç¹å¿™æ—¶é—´å¯èƒ½æ›´é•¿ã€‚ -10）主题ä¸åŒ…å« PATCH --------------------- +在ç‰äº†å‡ 个星期åŽï¼Œç”¨å¸¦RESEND的主题é‡å‘è¡¥ä¸ä¹Ÿæ˜¯å¯ä»¥çš„:: -由于到linuså’Œlinuxå†…æ ¸çš„ç”µå邮件æµé‡å¾ˆé«˜ï¼Œé€šå¸¸ä¼šåœ¨ä¸»é¢˜è¡Œå‰é¢åŠ 上[PATCH] -å‰ç¼€. 这使Linuså’Œå…¶ä»–å†…æ ¸å¼€å‘人员更容易将补ä¸ä¸Žå…¶ä»–电å邮件讨论区分开。 + [PATCH Vx RESEND] sub/sys: Condensed patch summary -11）ç¾ç½²ä½ 的作å“-å¼€å‘è€…åŽŸå§‹è®¤è¯ -------------------------------- +å½“ä½ å‘布补ä¸ï¼ˆç³»åˆ—）修改版的时候，ä¸è¦åŠ 上“RESENDâ€â€”—“RESENDâ€åªé€‚ç”¨äºŽé‡ +æ–°æ交之å‰æœªç»ä¿®æ”¹çš„è¡¥ä¸ï¼ˆç³»åˆ—）。 -ä¸ºäº†åŠ å¼ºå¯¹è°åšäº†ä½•äº‹çš„追踪，尤其是对那些é€è¿‡å¥½å‡ 层的维护者的补ä¸ï¼Œæˆ‘们 -建议在å‘é€å‡ºåŽ»çš„è¡¥ä¸ä¸ŠåŠ 一个 “sign-off†的过程。 +主题ä¸åŒ…å« PATCH +---------------- -"sign-off" 是在补ä¸çš„注释的最åŽçš„简å•çš„一行文å—，认è¯ä½ 编写了它或者其他 +由于到Linuså’Œlinux-kernel的电å邮件æµé‡å¾ˆé«˜ï¼Œé€šå¸¸ä¼šåœ¨ä¸»é¢˜è¡Œå‰é¢åŠ 上[PATCH] +å‰ç¼€ã€‚这使Linuså’Œå…¶ä»–å†…æ ¸å¼€å‘人员更容易将补ä¸ä¸Žå…¶ä»–电å邮件讨论区分开。 + +``git send-email`` ä¼šè‡ªåŠ¨ä¸ºä½ åŠ ä¸Šã€‚ + +ç¾ç½²ä½ 的作å“——开å‘者æ¥æºè®¤è¯ +------------------------------ + +ä¸ºäº†åŠ å¼ºå¯¹è°åšäº†ä½•äº‹çš„追踪，尤其是对那些é€è¿‡å¥½å‡ 层维护者æ‰æœ€ç»ˆåˆ°è¾¾çš„è¡¥ä¸ï¼Œæˆ‘ +们在通过邮件å‘é€çš„è¡¥ä¸ä¸Šå¼•å…¥äº†â€œç¾ç½²ï¼ˆsign-off）â€æµç¨‹ã€‚ + +“ç¾ç½²â€æ˜¯åœ¨è¡¥ä¸æ³¨é‡Šæœ€åŽçš„一行简å•æ–‡å—，认è¯ä½ 编写了它或者其他 人有æƒåŠ›å°†å®ƒä½œä¸ºå¼€æ”¾æºä»£ç çš„è¡¥ä¸ä¼ 递。规则很简å•ï¼šå¦‚æžœä½ èƒ½è®¤è¯å¦‚下信æ¯: -å¼€å‘者æ¥æºè¯ä¹¦ 1.1 +å¼€å‘者æ¥æºè®¤è¯ 1.1 ^^^^^^^^^^^^^^^^^^ 对于本项目的贡献，我认è¯å¦‚下信æ¯ï¼š - （a）这些贡献是完全或者部分的由我创建，我有æƒåˆ©ä»¥æ–‡ä»¶ä¸æŒ‡å‡º + (a) 这些贡献是完全或者部分的由我创建，我有æƒåˆ©ä»¥æ–‡ä»¶ä¸æŒ‡å‡º 的开放æºä»£ç 许å¯è¯æ交它；或者 - （b）这些贡献基于以å‰çš„工作，æ®æˆ‘所知，这些以å‰çš„工作å—æ°å½“的开放 - æºä»£ç 许å¯è¯ä¿æŠ¤ï¼Œè€Œä¸”ï¼Œæ ¹æ®è®¸å¯è¯ï¼Œæˆ‘有æƒæ交修改åŽçš„贡献， + + (b) 这些贡献基于以å‰çš„工作，æ®æˆ‘所知，这些以å‰çš„工作å—æ°å½“的开放 + æºä»£ç 许å¯è¯ä¿æŠ¤ï¼Œè€Œä¸”ï¼Œæ ¹æ®æ–‡ä»¶ä¸æŒ‡å‡ºçš„许å¯è¯ï¼Œæˆ‘有æƒæ交修改åŽçš„贡献， æ— è®ºæ˜¯å®Œå…¨è¿˜æ˜¯éƒ¨åˆ†ç”±æˆ‘åˆ›é€ ï¼Œè¿™äº›è´¡çŒ®éƒ½ä½¿ç”¨åŒä¸€ä¸ªå¼€æ”¾æºä»£ç 许å¯è¯ - （除éžæˆ‘被å…许用其它的许å¯è¯ï¼‰ï¼Œæ£å¦‚文件ä¸æŒ‡å‡ºçš„；或者 - （c）这些贡献由认è¯ï¼ˆa），（b）或者（c）的人直接æ供给我，而 + （除éžæˆ‘被å…许用其它的许å¯è¯ï¼‰ï¼›æˆ–者 + + (c) 这些贡献由认è¯ï¼ˆa），（b）或者（c）的人直接æ供给我，而 且我没有修改它。 - （d）我ç†è§£å¹¶åŒæ„这个项目和贡献是公开的，贡献的记录（包括我 - 一起æ交的个人记录，包括 sign-off ）被永久维护并且å¯ä»¥å’Œè¿™ä¸ªé¡¹ç›® + + (d) 我ç†è§£å¹¶åŒæ„这个项目和贡献是公开的，贡献的记录（包括我 + 一起æ交的个人记录，包括sign-off）被永久维护并且å¯ä»¥å’Œè¿™ä¸ªé¡¹ç›® 或者开放æºä»£ç 的许å¯è¯åŒæ¥åœ°å†å‘行。 é‚£ä¹ˆåŠ å…¥è¿™æ ·ä¸€è¡Œ:: - Signed-off-by: Random J Developer <random@developer.example.org> - -ä½¿ç”¨ä½ çš„çœŸå（抱æ‰ï¼Œä¸èƒ½ä½¿ç”¨å‡å或者匿å。） - -有人在最åŽåŠ ä¸Šæ ‡ç¾ã€‚çŽ°åœ¨è¿™äº›ä¸œè¥¿ä¼šè¢«å¿½ç•¥ï¼Œä½†æ˜¯ä½ å¯ä»¥è¿™æ ·åšï¼Œæ¥æ ‡è®°å…¬å¸ -内部的过程，或者åªæ˜¯æŒ‡å‡ºå…³äºŽ sign-off 的一些特殊细节。 - -如果您是å系统或分支维护人员，有时需è¦ç¨å¾®ä¿®æ”¹æ”¶åˆ°çš„è¡¥ä¸ï¼Œä»¥ä¾¿åˆå¹¶å®ƒä»¬ï¼Œ -å› ä¸ºæ ‘å’Œæ交者ä¸çš„代ç ä¸å®Œå…¨ç›¸åŒã€‚å¦‚æžœä½ ä¸¥æ ¼éµå®ˆè§„则（cï¼‰ï¼Œä½ åº”è¯¥è¦æ±‚æ交者 -é‡æ–°å‘布，但这完全是在浪费时间和精力。规则（b）å…许您调整代ç ，但是更改一个 -æ交者的代ç 并让他认å¯æ‚¨çš„错误是éžå¸¸ä¸ç¤¼è²Œçš„。è¦è§£å†³æ¤é—®é¢˜ï¼Œå»ºè®®åœ¨æœ€åŽä¸€ä¸ª -ç”±ç¾åè¡Œå’Œæ‚¨çš„è¡Œä¹‹é—´æ·»åŠ ä¸€è¡Œï¼ŒæŒ‡ç¤ºæ›´æ”¹çš„æ€§è´¨ã€‚è™½ç„¶è¿™å¹¶ä¸æ˜¯å¼ºåˆ¶æ€§çš„，但似乎 -在æè¿°å‰åŠ 上您的邮件和/或姓å（全部用方括å·æ‹¬èµ·æ¥ï¼‰ï¼Œè¿™è¶³ä»¥è®©äººæ³¨æ„到您对最 -åŽä¸€åˆ†é’Ÿçš„更改负有责任。例如:: - - Signed-off-by: Random J Developer <random@developer.example.org> - [lucky@maintainer.example.org: struct foo moved from foo.c to foo.h] - Signed-off-by: Lucky K Maintainer <lucky@maintainer.example.org> - -如果您维护一个稳定的分支机构，åŒæ—¶å¸Œæœ›å¯¹ä½œè€…进行致谢ã€è·Ÿè¸ªæ›´æ”¹ã€åˆå¹¶ä¿®å¤å¹¶ -ä¿æŠ¤æ交者ä¸å—投诉，那么这ç§åšæ³•å°¤å…¶æœ‰ç”¨ã€‚请注æ„，在任何情况下都ä¸èƒ½æ›´æ”¹ä½œè€… -çš„ID（From å¤´ï¼‰ï¼Œå› ä¸ºå®ƒæ˜¯å‡ºçŽ°åœ¨æ›´æ”¹æ—¥å¿—ä¸çš„æ ‡è¯†ã€‚ - -对回åˆï¼ˆback-porters）的特别说明：在æ交消æ¯çš„顶部（主题行之åŽï¼‰æ’å…¥ä¸€ä¸ªè¡¥ä¸ -çš„èµ·æºæŒ‡ç¤ºä¼¼ä¹Žæ˜¯ä¸€ç§å¸¸è§ä¸”有用的实践，以便于跟踪。例如，下é¢æ˜¯æˆ‘们在3.x稳定 -版本ä¸çœ‹åˆ°çš„内容:: - - Date: Tue Oct 7 07:26:38 2014 -0400 - - libata: Un-break ATA blacklist - - commit 1c40279960bcd7d52dbdf1d466b20d24b99176c8 upstream. - -还有， è¿™é‡Œæ˜¯ä¸€ä¸ªæ—§ç‰ˆå†…æ ¸ä¸çš„一个回åˆè¡¥ä¸:: + Signed-off-by: Random J Developer <random@developer.example.org> - Date: Tue May 13 22:12:27 2008 +0200 +ä½¿ç”¨ä½ çš„çœŸå（抱æ‰ï¼Œä¸èƒ½ä½¿ç”¨å‡å或者匿å。）如果使用 ``git commit -s`` çš„è¯ +将会自动完æˆã€‚撤销也应当包å«â€œSigned-off-byâ€ï¼Œ ``git revert -s`` ä¼šå¸®ä½ æžå®šã€‚ - wireless, airo: waitbusy() won't delay +有些人会在最åŽåŠ 上é¢å¤–çš„æ ‡ç¾ã€‚çŽ°åœ¨è¿™äº›ä¸œè¥¿ä¼šè¢«å¿½ç•¥ï¼Œä½†æ˜¯ä½ å¯ä»¥è¿™æ ·åšï¼Œæ¥æ ‡è®° +å…¬å¸å†…部的过程，或者åªæ˜¯æŒ‡å‡ºå…³äºŽç¾ç½²çš„一些特殊细节。 - [backport of 2.6 commit b7acbdfbd1f277c1eb23f344f899cfa4cd0bf36a] +作者ç¾ç½²ä¹‹åŽçš„任何其他ç¾ç½²ï¼ˆSigned-off-by:'s）å‡æ¥è‡ªå¤„ç†å’Œä¼ 递补ä¸çš„人员，但 +未å‚与其开å‘。ç¾ç½²é“¾åº”当åæ˜ è¡¥ä¸ä¼ æ’åˆ°ç»´æŠ¤è€…å¹¶æœ€ç»ˆä¼ æ’到Linus所ç»è¿‡çš„ **真实** +路径，首个ç¾ç½²æŒ‡æ˜Žå•ä¸ªä½œè€…的主è¦ä½œè€…身份。 -12）何时使用Acked-by:，CC:，和Co-Developed by: ----------------------------------------------- +何时使用Acked-by:，CC:，和Co-Developed by: +------------------------------------------ -Singed-off-by: æ ‡è®°è¡¨ç¤ºç¾å者å‚与了补ä¸çš„å¼€å‘，或者他/她在补ä¸çš„ä¼ é€’è·¯å¾„ä¸ã€‚ +Singed-off-by: æ ‡ç¾è¡¨ç¤ºç¾å者å‚与了补ä¸çš„å¼€å‘，或者他/她在补ä¸çš„ä¼ é€’è·¯å¾„ä¸ã€‚ -如果一个人没有直接å‚与补ä¸çš„准备或处ç†ï¼Œä½†å¸Œæœ›è¡¨ç¤ºå¹¶è®°å½•ä»–们对补ä¸çš„批准， -那么他们å¯ä»¥è¦æ±‚在补ä¸çš„å˜æ›´æ—¥å¿—ä¸æ·»åŠ 一个 Acked-by: +如果一个人没有直接å‚与补ä¸çš„准备或处ç†ï¼Œä½†å¸Œæœ›è¡¨ç¤ºå¹¶è®°å½•ä»–们对补ä¸çš„批准/赞æˆï¼Œ +那么他们å¯ä»¥è¦æ±‚在补ä¸çš„å˜æ›´æ—¥å¿—ä¸æ·»åŠ 一个Acked-by:。 -Acked-by：通常由å—å½±å“代ç 的维护者使用，当该维护者既没有贡献也没有转å‘è¡¥ä¸æ—¶ã€‚ +Acked-by: 通常由å—å½±å“代ç 的维护者使用，当该维护者既没有贡献也没有转å‘è¡¥ä¸æ—¶ã€‚ -Acked-by: ä¸åƒç¾å—äººé‚£æ ·æ£å¼ã€‚这是一个记录，确认人至少审查了补ä¸ï¼Œå¹¶è¡¨ç¤ºæŽ¥å—。 -å› æ¤ï¼Œè¡¥ä¸åˆå¹¶æœ‰æ—¶ä¼šæ‰‹åŠ¨å°†Acker的“Yep，looks good to meâ€è½¬æ¢ä¸º Acked-By：（但 +Acked-by: ä¸åƒç¾ç½²é‚£æ ·æ£å¼ã€‚这是一个记录，确认人至少审阅了补ä¸ï¼Œå¹¶è¡¨ç¤ºæŽ¥å—。 +å› æ¤ï¼Œè¡¥ä¸åˆå¹¶æœ‰æ—¶ä¼šæ‰‹åŠ¨å°†Acker的“Yep，looks good to meâ€è½¬æ¢ä¸º Acked-By:（但 请注æ„，通常最好è¦æ±‚一个明确的Ack）。 Acked-by：ä¸ä¸€å®šè¡¨ç¤ºå¯¹æ•´ä¸ªè¡¥ä¸çš„确认。例如，如果一个补ä¸å½±å“多个å系统，并且 -有一个：æ¥è‡ªä¸€ä¸ªå系统维护者，那么这通常表示åªç¡®è®¤å½±å“维护者代ç 的部分。这里 -应该仔细判æ–。如有疑问，应å‚考邮件列表档案ä¸çš„原始讨论。 +有一个æ¥è‡ªæŸä¸ªå系统维护者的Acked-By:，那么这通常表示åªç¡®è®¤å½±å“维护者代ç 的部 +分。这里应该仔细判æ–。如有疑问，应å‚考邮件列表å˜æ¡£ä¸çš„原始讨论。 -如果æŸäººæœ‰æœºä¼šå¯¹è¡¥ä¸è¿›è¡Œè¯„论，但没有æä¾›æ¤ç±»è¯„论，您å¯ä»¥é€‰æ‹©åœ¨è¡¥ä¸ä¸æ·»åŠ ``Cc:`` -è¿™æ˜¯å”¯ä¸€ä¸€ä¸ªæ ‡ç¾ï¼Œå®ƒå¯ä»¥åœ¨æ²¡æœ‰è¢«å®ƒå‘½å的人显å¼æ“ä½œçš„æƒ…å†µä¸‹æ·»åŠ ï¼Œä½†å®ƒåº”è¯¥è¡¨æ˜Ž -这个人是在补ä¸ä¸ŠæŠ„é€çš„。讨论ä¸åŒ…å«äº†æ½œåœ¨åˆ©ç›Šç›¸å…³æ–¹ã€‚ +如果æŸäººæœ¬åº”有机会对补ä¸è¿›è¡Œè¯„论，但没有æä¾›æ¤ç±»è¯„论，您å¯ä»¥é€‰æ‹©åœ¨è¡¥ä¸ä¸æ·»åŠ +``Cc:`` 这是唯一å¯ä»¥åœ¨æ²¡æœ‰è¢«è¯¥äººæ˜Žç¡®åŒæ„çš„æƒ…å†µä¸‹æ·»åŠ çš„æ ‡ç¾â€”—但它应该表明 +这个人是在补ä¸ä¸ŠæŠ„é€çš„。æ¤æ ‡ç¾è®°å½•äº†è®¨è®ºä¸åŒ…å«çš„潜在利益相关方。 Co-developed-by: 声明补ä¸æ˜¯ç”±å¤šä¸ªå¼€å‘人员共åŒåˆ›å»ºçš„ï¼›å½“å‡ ä¸ªäººåœ¨ä¸€ä¸ªè¡¥ä¸ä¸Šå·¥ -作时，它用于将属性赋予共åŒä½œè€…（除了 From: æ‰€èµ‹äºˆçš„ä½œè€…ä¹‹å¤–ï¼‰ã€‚å› ä¸º -Co-developed-by: 表示作者身份，所以æ¯ä¸ªå…±åŒå¼€å‘人：必须紧跟在相关åˆä½œä½œè€…çš„ -ç¾å之åŽã€‚æ ‡å‡†çš„ç¾æ ¸ç¨‹åºè¦æ±‚ï¼šæ ‡è®°çš„ç¾æ ¸é¡ºåºåº”å°½å¯èƒ½åæ˜ è¡¥ä¸çš„时间历å²ï¼Œè€Œä¸ -管作者是通过 From ：还是由 Co-developed-by: å…±åŒå¼€å‘的。值得注æ„的是，最åŽä¸€ -个ç¾å—人：必须始终是æ交补ä¸çš„å¼€å‘人员。 +作时，它用于给出共åŒä½œè€…（除了From:æ‰€ç»™å‡ºçš„ä½œè€…ä¹‹å¤–ï¼‰ã€‚å› ä¸ºCo-developed-by: +表示作者身份，所以æ¯ä¸ªCo-developed-by:必须紧跟在相关åˆä½œä½œè€…çš„ç¾ç½²ä¹‹åŽã€‚æ ‡å‡† +ç¾ç½²ç¨‹åºè¦æ±‚Singed-off-by:æ ‡ç¾çš„顺åºåº”å°½å¯èƒ½åæ˜ è¡¥ä¸çš„时间历å²ï¼Œæ— 论作者是通 +过From:还是Co-developed-by:表明。值得注æ„的是，最åŽä¸€ä¸ªSinged-off-by:必须是 +æ交补ä¸çš„å¼€å‘人员。 -注æ„，当作者也是电åé‚®ä»¶æ ‡é¢˜â€œå‘件人：â€è¡Œä¸åˆ—出的人时，“From: â€ æ ‡è®°æ˜¯å¯é€‰çš„。 +注æ„，如果From:作者也是电åé‚®ä»¶æ ‡é¢˜çš„From:è¡Œä¸åˆ—出的人，则From:æ ‡ç¾æ˜¯å¯é€‰çš„。 -作者æ交的补ä¸ç¨‹åºç¤ºä¾‹:: +被From:作者æ交的补ä¸ç¤ºä¾‹:: <changelog> @@ -421,7 +374,7 @@ Co-developed-by: 表示作者身份，所以æ¯ä¸ªå…±åŒå¼€å‘人：必须紧跟 Signed-off-by: Second Co-Author <second@coauthor.example.org> Signed-off-by: From Author <from@author.example.org> -åˆä½œå¼€å‘者æ交的补ä¸ç¤ºä¾‹:: +被åˆä½œå¼€å‘者æ交的补ä¸ç¤ºä¾‹:: From: From Author <from@author.example.org> @@ -434,76 +387,85 @@ Co-developed-by: 表示作者身份，所以æ¯ä¸ªå…±åŒå¼€å‘人：必须紧跟 Signed-off-by: Submitting Co-Author <sub@coauthor.example.org> -13）使用报告人：ã€æµ‹è¯•äººï¼šã€å®¡æ ¸äººï¼šã€å»ºè®®äººï¼šã€ä¿®å¤äººï¼š --------------------------------------------------------- +使用Reported-by:ã€Tested-by:ã€Reviewed-by:ã€Suggested-by:å’ŒFixes: +----------------------------------------------------------------- Reported-by: 给那些å‘现错误并报告错误的人致谢，它希望激励他们在将æ¥å†æ¬¡å¸®åŠ© -我们。请注æ„，如果bug是以ç§æœ‰æ–¹å¼æŠ¥å‘Šçš„，那么在使用Reported-byæ ‡è®°ä¹‹å‰ï¼Œè¯· -先请求æƒé™ã€‚ +我们。请注æ„，如果bug是以ç§æœ‰æ–¹å¼æŠ¥å‘Šçš„，那么在使用Reported-byæ ‡ç¾ä¹‹å‰ï¼Œè¯· +先请求许å¯ã€‚æ¤æ ‡ç¾æ˜¯ä¸ºBug设计的；请ä¸è¦å°†å…¶ç”¨äºŽæ„Ÿè°¢åŠŸèƒ½è¯·æ±‚。 -Tested-by: æ ‡è®°è¡¨ç¤ºè¡¥ä¸å·²ç”±æŒ‡å®šçš„人（在æŸäº›çŽ¯å¢ƒä¸ï¼‰æˆåŠŸæµ‹è¯•ã€‚è¿™ä¸ªæ ‡ç¾é€šçŸ¥ -维护人员已ç»æ‰§è¡Œäº†ä¸€äº›æµ‹è¯•ï¼Œä¸ºå°†æ¥çš„è¡¥ä¸æ供了一ç§å®šä½æµ‹è¯•äººå‘˜çš„方法，并确 -ä¿æµ‹è¯•äººå‘˜çš„信誉。 +Tested-by: æ ‡ç¾è¡¨ç¤ºè¡¥ä¸å·²ç”±æŒ‡å®šçš„人（在æŸäº›çŽ¯å¢ƒä¸ï¼‰æˆåŠŸæµ‹è¯•ã€‚è¿™ä¸ªæ ‡ç¾é€šçŸ¥ +维护人员已ç»æ‰§è¡Œäº†ä¸€äº›æµ‹è¯•ï¼Œä¸ºå°†æ¥çš„è¡¥ä¸æ供了一ç§å®šä½æµ‹è¯•äººå‘˜çš„方法，并彰显测试人员的功劳。 -Reviewed-by：相åï¼Œæ ¹æ®å®¡æŸ¥äººçš„声明，表明该补ä¸å·²è¢«å®¡æŸ¥å¹¶è¢«è®¤ä¸ºæ˜¯å¯æŽ¥å—的： +Reviewed-byï¼šæ ¹æ®å®¡é˜…者的监ç£å£°æ˜Žï¼Œè¡¨æ˜Žè¯¥è¡¥ä¸å·²è¢«å®¡é˜…并被认为是å¯æŽ¥å—的： -审查人的监ç£å£°æ˜Ž +审阅者的监ç£å£°æ˜Ž ^^^^^^^^^^^^^^^^ -通过æ供我的 Reviewed-by，我声明： +通过æ供我的Reviewed-by:æ ‡ç¾ï¼Œæˆ‘声明： - (a) 我已ç»å¯¹è¿™ä¸ªè¡¥ä¸è¿›è¡Œäº†ä¸€æ¬¡æŠ€æœ¯å®¡æŸ¥ï¼Œä»¥è¯„估它是å¦é€‚åˆè¢«åŒ…å«åˆ° + (a) 我已ç»å¯¹è¿™ä¸ªè¡¥ä¸è¿›è¡Œäº†ä¸€æ¬¡æŠ€æœ¯å®¡é˜…，以评估它是å¦é€‚åˆè¢«åŒ…å«åˆ° ä¸»çº¿å†…æ ¸ä¸ã€‚ (b) 与补ä¸ç›¸å…³çš„任何问题ã€é¡¾è™‘或问题都已å馈给æ交者。我对æ交者对 我的评论的回应感到满æ„。 - (c) 虽然这一æ交å¯èƒ½ä¼šæ”¹è¿›ä¸€äº›ä¸œè¥¿ï¼Œä½†æˆ‘相信，æ¤æ—¶ï¼Œï¼ˆ1ï¼‰å¯¹å†…æ ¸ + (c) 虽然这一æ交å¯èƒ½ä»å¯è¢«æ”¹è¿›ï¼Œä½†æˆ‘相信，æ¤æ—¶ï¼Œï¼ˆ1ï¼‰å¯¹å†…æ ¸ 进行了有价值的修改，（2）没有包å«äº‰è®ºä¸æ¶‰åŠçš„已知问题。 - (d) 虽然我已ç»å®¡æŸ¥äº†è¡¥ä¸å¹¶è®¤ä¸ºå®ƒæ˜¯å¥å…¨çš„，但我ä¸ä¼šï¼ˆé™¤éžå¦æœ‰æ˜Žç¡® - 说明）作出任何ä¿è¯æˆ–ä¿è¯å®ƒå°†åœ¨ä»»ä½•ç»™å®šæƒ…况下实现其规定的目的 + (d) 虽然我已ç»å®¡é˜…了补ä¸å¹¶è®¤ä¸ºå®ƒæ˜¯å¥å…¨çš„，但我ä¸ä¼šï¼ˆé™¤éžå¦æœ‰æ˜Žç¡® + 说明）作出任何ä¿è¯æˆ–æ‹…ä¿å®ƒä¼šåœ¨ä»»ä½•ç»™å®šæƒ…况下实现其规定的目的 或æ£å¸¸è¿è¡Œã€‚ -Reviewed-by 是一ç§è§‚点声明，å³è¡¥ä¸æ˜¯å¯¹å†…æ ¸çš„é€‚å½“ä¿®æ”¹ï¼Œæ²¡æœ‰ä»»ä½•é—留的严é‡æŠ€æœ¯ -问题。任何感兴趣的审阅者（完æˆå·¥ä½œçš„人）都å¯ä»¥ä¸ºä¸€ä¸ªè¡¥ä¸æ供一个 Review-by -æ ‡ç¾ã€‚æ¤æ ‡ç¾ç”¨äºŽå‘审阅者æ供致谢，并通知维护者已在修补程åºä¸Šå®Œæˆçš„审阅程度。 -Reviewed-by: 当由已知了解主题区域并执行彻底检查的审阅者æä¾›æ—¶ï¼Œé€šå¸¸ä¼šå¢žåŠ +Reviewed-by是一ç§è§‚点声明，å³è¡¥ä¸æ˜¯å¯¹å†…æ ¸çš„é€‚å½“ä¿®æ”¹ï¼Œæ²¡æœ‰ä»»ä½•é—留的严é‡æŠ€æœ¯ +问题。任何感兴趣的审阅者（完æˆå·¥ä½œçš„人）都å¯ä»¥ä¸ºä¸€ä¸ªè¡¥ä¸æ供一个Reviewed-by +æ ‡ç¾ã€‚æ¤æ ‡ç¾ç”¨äºŽå‘审阅者æ供致谢，并通知维护者补ä¸çš„审阅进度。 +当Reviewed-by:æ ‡ç¾ç”±å·²çŸ¥äº†è§£ä¸»é¢˜åŒºåŸŸå¹¶æ‰§è¡Œå½»åº•æ£€æŸ¥çš„审阅者æä¾›æ—¶ï¼Œé€šå¸¸ä¼šå¢žåŠ è¡¥ä¸è¿›å…¥å†…æ ¸çš„å¯èƒ½æ€§ã€‚ +一旦从测试人员或审阅者的“Tested-byâ€å’Œâ€œReviewed-byâ€æ ‡ç¾å‡ºçŽ°åœ¨é‚®ä»¶åˆ—表ä¸ï¼Œ +作者应在å‘é€ä¸‹ä¸€ä¸ªç‰ˆæœ¬æ—¶å°†å…¶æ·»åŠ 到适用的补ä¸ä¸ã€‚但是，如果补ä¸åœ¨ä»¥ä¸‹ç‰ˆæœ¬ä¸å‘ +ç”Ÿäº†å®žè´¨æ€§æ›´æ”¹ï¼Œè¿™äº›æ ‡ç¾å¯èƒ½ä¸å†é€‚ç”¨ï¼Œå› æ¤åº”è¯¥åˆ é™¤ã€‚é€šå¸¸ï¼Œåœ¨è¡¥ä¸æ›´æ”¹æ—¥å¿—ä¸ +（在 ``---`` 分隔符之åŽï¼‰åº”该æåˆ°åˆ é™¤æŸäººçš„æµ‹è¯•è€…æˆ–å®¡é˜…è€…æ ‡ç¾ã€‚ + Suggested-by: 表示补ä¸çš„想法是由指定的人æ出的，并确ä¿å°†æ¤æƒ³æ³•å½’功于指定的 人。请注æ„，未ç»è®¸å¯ï¼Œä¸å¾—æ·»åŠ æ¤æ ‡ç¾ï¼Œç‰¹åˆ«æ˜¯å¦‚果该想法未在公共论å›ä¸Šå‘布。 -这就是说，如果我们勤快地致谢我们的创æ„者，他们很有希望在未æ¥å¾—到鼓舞，å†æ¬¡ +也就是说，如果我们勤快地致谢创æ„æ供者，他们将å—到鼓舞，很有希望在未æ¥å†æ¬¡ 帮助我们。 -Fixes: 指示补ä¸åœ¨ä»¥å‰çš„æ交ä¸ä¿®å¤äº†ä¸€ä¸ªé—®é¢˜ã€‚它å¯ä»¥å¾ˆå®¹æ˜“地确定错误的æ¥æºï¼Œ -这有助于检查错误修å¤ã€‚è¿™ä¸ªæ ‡è®°è¿˜å¸®åŠ©ç¨³å®šå†…æ ¸å›¢é˜Ÿç¡®å®šåº”è¯¥æŽ¥æ”¶ä¿®å¤çš„ç¨³å®šå†…æ ¸ -版本。这是指示补ä¸ä¿®å¤çš„错误的首选方法。请å‚阅 :ref:`cn_describe_changes` -æ述您的更改以了解更多详细信æ¯ã€‚ +Fixes: 指示补ä¸ä¿®å¤äº†ä¹‹å‰æ交的一个问题。它å¯ä»¥ä¾¿äºŽç¡®å®šé”™è¯¯çš„æ¥æºï¼Œè¿™æœ‰åŠ©äºŽ +检查错误修å¤ã€‚è¿™ä¸ªæ ‡ç¾è¿˜å¸®åŠ©ç¨³å®šå†…æ ¸å›¢é˜Ÿç¡®å®šåº”è¯¥æŽ¥æ”¶ä¿®å¤çš„ç¨³å®šå†…æ ¸ç‰ˆæœ¬ã€‚è¿™æ˜¯ +指示补ä¸ä¿®å¤çš„错误的首选方法。请å‚阅 :ref:`zh_describe_changes` 了解更多信æ¯ã€‚ -.. _cn_the_canonical_patch_format: +.. note:: -12ï¼‰æ ‡å‡†è¡¥ä¸æ ¼å¼ ----------------- + é™„åŠ Fixes:æ ‡ç¾ä¸ä¼šæ”¹å˜ç¨³å®šå†…æ ¸è§„åˆ™æµç¨‹ï¼Œä¹Ÿä¸æ”¹å˜æ‰€æœ‰ç¨³å®šç‰ˆè¡¥ä¸æŠ„é€ + stable@vger.kernel.orgçš„è¦æ±‚。有关更多信æ¯ï¼Œè¯·é˜…读 + Documentation/translations/zh_CN/process/stable-kernel-rules.rst 。 + +.. _zh_the_canonical_patch_format: + +æ ‡å‡†è¡¥ä¸æ ¼å¼ +------------ 本节æè¿°å¦‚ä½•æ ¼å¼åŒ–è¡¥ä¸æœ¬èº«ã€‚请注æ„，如果您的补ä¸å˜å‚¨åœ¨ ``Git`` å˜å‚¨åº“ä¸ï¼Œåˆ™ -å¯ä»¥ä½¿ç”¨ ``git format-patch`` 进行æ£ç¡®çš„è¡¥ä¸æ ¼å¼è®¾ç½®ã€‚ä½†æ˜¯ï¼Œè¿™äº›å·¥å…·æ— æ³•åˆ›å»º +å¯ä»¥ä½¿ç”¨ ``git format-patch`` 进行æ£ç¡®çš„è¡¥ä¸æ ¼å¼åŒ–ã€‚ä½†æ˜¯ï¼Œè¿™äº›å·¥å…·æ— æ³•åˆ›å»º å¿…è¦çš„æ–‡æœ¬ï¼Œå› æ¤è¯·åŠ¡å¿…阅读下é¢çš„说明。 -æ ‡å‡†çš„è¡¥ä¸ï¼Œæ ‡é¢˜è¡Œæ˜¯:: +æ ‡å‡†çš„è¡¥ä¸æ ‡é¢˜è¡Œæ˜¯:: Subject: [PATCH 001/123] å系统:一å¥è¯æ¦‚è¿° -æ ‡å‡†è¡¥ä¸çš„信体å˜åœ¨å¦‚下部分： +æ ‡å‡†è¡¥ä¸çš„信体包å«å¦‚下部分： - - 一个 "from" 行指出补ä¸ä½œè€…。åŽè·Ÿç©ºè¡Œï¼ˆä»…当å‘é€ä¿®è¡¥ç¨‹åºçš„人ä¸æ˜¯ä½œè€…æ—¶æ‰éœ€è¦ï¼‰ã€‚ + - 一个 ``from`` 行指出补ä¸ä½œè€…。åŽè·Ÿç©ºè¡Œï¼ˆä»…当å‘é€è¡¥ä¸çš„人ä¸æ˜¯ä½œè€…æ—¶æ‰éœ€è¦ï¼‰ã€‚ - - 解释的æ£æ–‡ï¼Œè¡Œä»¥75列包装，这将被å¤åˆ¶åˆ°æ°¸ä¹…å˜æ›´æ—¥å¿—æ¥æ述这个补ä¸ã€‚ + - 说明文å—，æ¯è¡Œæœ€é•¿75列，这将被å¤åˆ¶åˆ°æ°¸ä¹…å˜æ›´æ—¥å¿—æ¥æ述这个补ä¸ã€‚ - 一个空行 - - 上é¢æ述的“Signed-off-by†行，也将出现在更改日志ä¸ã€‚ + - 上述的 ``Signed-off-by:`` 行，也将出现在更改日志ä¸ã€‚ - åªåŒ…å« ``---`` çš„æ ‡è®°çº¿ã€‚ @@ -511,29 +473,29 @@ Fixes: 指示补ä¸åœ¨ä»¥å‰çš„æ交ä¸ä¿®å¤äº†ä¸€ä¸ªé—®é¢˜ã€‚它å¯ä»¥å¾ˆå®¹æ - 实际补ä¸ï¼ˆ ``diff`` 输出）。 -æ ‡é¢˜è¡Œçš„æ ¼å¼ï¼Œä½¿å¾—å¯¹æ ‡é¢˜è¡ŒæŒ‰å—æ¯åºæŽ’åºéžå¸¸çš„容易 - 很多 e-mail 客户端都 -å¯ä»¥æ”¯æŒ - å› ä¸ºåºåˆ—å·æ˜¯ç”¨é›¶å¡«å……的，所以按数å—排åºå’ŒæŒ‰å—æ¯æŽ’åºæ˜¯ä¸€æ ·çš„。 +æ ‡é¢˜è¡Œçš„æ ¼å¼ï¼Œä½¿å¾—å¯¹æ ‡é¢˜è¡ŒæŒ‰å—æ¯åºæŽ’åºéžå¸¸çš„容易——很多邮件客户端都 +å¯ä»¥æ”¯æŒâ€”â€”å› ä¸ºåºåˆ—å·æ˜¯ç”¨é›¶å¡«å……的，所以按数å—排åºå’ŒæŒ‰å—æ¯æŽ’åºæ˜¯ä¸€æ ·çš„。 -e-mail æ ‡é¢˜ä¸çš„“å系统â€æ ‡è¯†å“ªä¸ªå†…æ ¸å系统将被打补ä¸ã€‚ +é‚®ä»¶æ ‡é¢˜ä¸çš„“å系统â€æ ‡è¯†å“ªä¸ªå†…æ ¸å系统将被打补ä¸ã€‚ -e-mail æ ‡é¢˜ä¸çš„“一å¥è¯æ¦‚è¿°â€æ‰¼è¦çš„æè¿° e-mail ä¸çš„è¡¥ä¸ã€‚“一å¥è¯æ¦‚述†+é‚®ä»¶æ ‡é¢˜ä¸çš„“一å¥è¯æ¦‚è¿°â€æ‰¼è¦çš„æ述邮件ä¸çš„è¡¥ä¸ã€‚“一å¥è¯æ¦‚述†ä¸åº”该是一个文件å。对于一个补ä¸ç³»åˆ—（“补ä¸ç³»åˆ—â€æŒ‡ä¸€ç³»åˆ—的多个相关补 ä¸ï¼‰ï¼Œä¸è¦å¯¹æ¯ä¸ªè¡¥ä¸éƒ½ä½¿ç”¨åŒæ ·çš„“一å¥è¯æ¦‚è¿°â€ã€‚ -è®°ä½ e-mail 的“一å¥è¯æ¦‚è¿°â€ä¼šæˆä¸ºè¯¥è¡¥ä¸çš„å…¨å±€å”¯ä¸€æ ‡è¯†ã€‚å®ƒä¼šè”“å»¶åˆ° git +è®°ä½é‚®ä»¶çš„“一å¥è¯æ¦‚è¿°â€ä¼šæˆä¸ºè¯¥è¡¥ä¸çš„å…¨å±€å”¯ä¸€æ ‡è¯†ã€‚å®ƒä¼šè¿›å…¥ ``git`` 的改动记录里。然åŽâ€œä¸€å¥è¯æ¦‚è¿°â€ä¼šè¢«ç”¨åœ¨å¼€å‘者的讨论里，用æ¥æŒ‡ä»£è¿™ä¸ªè¡¥ -ä¸ã€‚用户将希望通过 google æ¥æœç´¢"一å¥è¯æ¦‚è¿°"æ¥æ‰¾åˆ°é‚£äº›è®¨è®ºè¿™ä¸ªè¡¥ä¸çš„æ–‡ +ä¸ã€‚用户将希望通过æœç´¢å¼•æ“Žæœç´¢â€œä¸€å¥è¯æ¦‚è¿°â€æ¥æ‰¾åˆ°é‚£äº›è®¨è®ºè¿™ä¸ªè¡¥ä¸çš„æ–‡ ç« ã€‚å½“äººä»¬åœ¨ä¸¤ä¸‰ä¸ªæœˆåŽä½¿ç”¨è¯¸å¦‚ ``gitk`` 或 ``git log --oneline`` 之类 的工具查看数åƒä¸ªè¡¥ä¸æ—¶ï¼Œä¹Ÿä¼šå¾ˆå¿«çœ‹åˆ°å®ƒã€‚ å‡ºäºŽè¿™äº›åŽŸå› ï¼Œæ¦‚è¿°å¿…é¡»ä¸è¶…过70-75个å—符，并且必须æè¿°è¡¥ä¸çš„更改以åŠä¸º -什么需è¦è¡¥ä¸ã€‚æ—¢è¦ç®€æ´åˆè¦æè¿°æ€§å¾ˆæœ‰æŒ‘æˆ˜æ€§ï¼Œä½†å†™å¾—å¥½çš„æ¦‚è¿°åº”è¯¥è¿™æ ·åšã€‚ +什么需è¦è¡¥ä¸ã€‚æ—¢è¦ç®€æ´åˆè¦æè¿°æ€§å¾ˆæœ‰æŒ‘æˆ˜æ€§ï¼Œä½†å†™å¾—å¥½çš„æ¦‚è¿°åº”è¯¥è¿™æ ·ã€‚ 概述的å‰ç¼€å¯ä»¥ç”¨æ–¹æ‹¬å·æ‹¬èµ·æ¥ï¼šâ€œSubject: [PATCH <tag>...] <概述>â€ã€‚æ ‡è®° ä¸è¢«è§†ä¸ºæ¦‚述的一部分，而是æ述应该如何处ç†è¡¥ä¸ã€‚如果补ä¸çš„å¤šä¸ªç‰ˆæœ¬å·²å‘ -é€å‡ºæ¥ä»¥å“应评审（å³â€œv1，v2，v3â€ï¼‰æˆ–“rfcâ€ï¼Œä»¥æŒ‡ç¤ºè¯„å®¡è¯·æ±‚ï¼Œé‚£ä¹ˆé€šç”¨æ ‡è®° -å¯èƒ½åŒ…括版本æ述符。如果一个补ä¸ç³»åˆ—ä¸æœ‰å››ä¸ªè¡¥ä¸ï¼Œé‚£ä¹ˆå„个补ä¸å¯ä»¥è¿™æ · -ç¼–å·ï¼š1/4ã€2/4ã€3/4ã€4/4。这å¯ä»¥ç¡®ä¿å¼€å‘人员了解补ä¸åº”用的顺åºï¼Œå¹¶ä¸”他们 +é€å‡ºæ¥ä»¥å“应评审（å³â€œv1，v2，v3â€ï¼‰åˆ™å¿…须包å«ç‰ˆæœ¬å·ï¼Œæˆ–包å«â€œRFCâ€ä»¥æŒ‡ç¤º +评审请求。如果一个补ä¸ç³»åˆ—ä¸æœ‰å››ä¸ªè¡¥ä¸ï¼Œé‚£ä¹ˆå„个补ä¸å¯ä»¥è¿™æ ·ç¼–å·ï¼š1/4ã€2/4〠+3/4ã€4/4。这å¯ä»¥ç¡®ä¿å¼€å‘人员了解补ä¸åº”用的顺åºï¼Œä¸” å·²ç»æŸ¥çœ‹æˆ–应用了补ä¸ç³»åˆ—ä¸çš„所有补ä¸ã€‚ ä¸€äº›æ ‡é¢˜çš„ä¾‹å:: @@ -541,95 +503,134 @@ e-mail æ ‡é¢˜ä¸çš„“一å¥è¯æ¦‚è¿°â€æ‰¼è¦çš„æè¿° e-mail ä¸çš„è¡¥ä¸ã€‚†Subject: [patch 2/5] ext2: improve scalability of bitmap searching Subject: [PATCHv2 001/207] x86: fix eflags tracking -"From" 行是信体里的最上é¢ä¸€è¡Œï¼Œå…·æœ‰å¦‚ä¸‹æ ¼å¼ï¼š +``From`` 行是信体里的最上é¢ä¸€è¡Œï¼Œå…·æœ‰å¦‚ä¸‹æ ¼å¼:: + From: Patch Author <author@example.com> -"From" 行指明在永久改动日志里，è°ä¼šè¢«ç¡®è®¤ä¸ºä½œè€…。如果没有 "From" 行，那 -么邮件头里的 "From: " 行会被用æ¥å†³å®šæ”¹åŠ¨æ—¥å¿—ä¸çš„作者。 +``From`` 行指明在永久改动日志里，è°ä¼šè¢«ç¡®è®¤ä¸ºä½œè€…。如果没有 ``From`` 行，那 +么邮件头里的 ``From:`` 行会被用æ¥å†³å®šæ”¹åŠ¨æ—¥å¿—ä¸çš„作者。 -说明的主题将会被æ交到永久的æºä»£ç æ”¹åŠ¨æ—¥å¿—é‡Œï¼Œå› æ¤å¯¹é‚£äº›æ—©å·²ç»ä¸è®°å¾—å’Œ -这个补ä¸ç›¸å…³çš„讨论细节的有能力的读者æ¥è¯´ï¼Œæ˜¯æœ‰æ„义的。包括补ä¸ç¨‹åºå®šä½ -é”™è¯¯çš„ï¼ˆå†…æ ¸æ—¥å¿—æ¶ˆæ¯ã€OOPS消æ¯ç‰ï¼‰ç—‡çŠ¶ï¼Œå¯¹äºŽæœç´¢æ交日志以寻找适用补ä¸çš„人 -尤其有用。如果一个补ä¸ä¿®å¤äº†ä¸€ä¸ªç¼–译失败，那么å¯èƒ½ä¸éœ€è¦åŒ…å«æ‰€æœ‰ç¼–译失败； +说明文å—将会被æ交到永久的æºä»£ç æ”¹åŠ¨æ—¥å¿—é‡Œï¼Œå› æ¤åº”针对那些早已ç»ä¸è®°å¾—和这 +个补ä¸ç›¸å…³çš„讨论细节的读者。包括补ä¸å¤„ç†çš„æ•…éšœç—‡çŠ¶ï¼ˆå†…æ ¸æ—¥å¿—æ¶ˆæ¯ã€oopsæ¶ˆæ¯ +ç‰ï¼‰ï¼Œè¿™å¯¹äºŽå¯èƒ½æ£åœ¨æœç´¢æ交日志以查找适用补ä¸çš„人特别有用。文本应该写得如 +æ¤è¯¦ç»†ï¼Œä»¥ä¾¿åœ¨æ•°å‘¨ã€æ•°æœˆç”šè‡³æ•°å¹´åŽé˜…读时，能够为读者æ供所需的细节信æ¯ï¼Œä»¥ +掌æ¡åˆ›å»ºè¡¥ä¸çš„ **åŽŸå› ** 。 + +如果一个补ä¸ä¿®å¤äº†ä¸€ä¸ªç¼–译失败，那么å¯èƒ½ä¸éœ€è¦åŒ…å« *所有* 编译失败； åªè¦è¶³å¤Ÿè®©æœç´¢è¡¥ä¸çš„äººèƒ½å¤Ÿæ‰¾åˆ°å®ƒå°±è¡Œäº†ã€‚ä¸Žæ¦‚è¿°ä¸€æ ·ï¼Œæ—¢è¦ç®€æ´åˆè¦æ述性。 -"---" æ ‡è®°è¡Œå¯¹äºŽè¡¥ä¸å¤„ç†å·¥å…·è¦æ‰¾åˆ°å“ªé‡Œæ˜¯æ”¹åŠ¨æ—¥å¿—ä¿¡æ¯çš„结æŸï¼Œæ˜¯ä¸å¯ç¼ºå°‘ +``---`` æ ‡è®°è¡Œå¯¹äºŽè¡¥ä¸å¤„ç†å·¥å…·è¦æ‰¾åˆ°å“ªé‡Œæ˜¯æ”¹åŠ¨æ—¥å¿—ä¿¡æ¯çš„结æŸï¼Œæ˜¯ä¸å¯ç¼ºå°‘ 的。 -对于 "---" æ ‡è®°ä¹‹åŽçš„é¢å¤–注解，一个好的用途就是用æ¥å†™ diffstat，用æ¥æ˜¾ -示修改了什么文件和æ¯ä¸ªæ–‡ä»¶éƒ½å¢žåŠ å’Œåˆ é™¤äº†å¤šå°‘è¡Œã€‚diffstat 对于比较大的补 -ä¸ç‰¹åˆ«æœ‰ç”¨ã€‚其余那些åªæ˜¯å’Œæ—¶åˆ»æˆ–者开å‘者相关的注解，ä¸åˆé€‚放到永久的改 -动日志里的，也应该放这里。 -使用 diffstat的选项 "-p 1 -w 70" è¿™æ ·æ–‡ä»¶åå°±ä¼šä»Žå†…æ ¸æºä»£ç æ ‘çš„ç›®å½•å¼€å§‹ +对于 ``---`` æ ‡è®°ä¹‹åŽçš„é¢å¤–注解，一个好的用途就是用æ¥å†™ ``diffstat`` ，用æ¥æ˜¾ +示修改了什么文件和æ¯ä¸ªæ–‡ä»¶éƒ½å¢žåŠ å’Œåˆ é™¤äº†å¤šå°‘è¡Œã€‚ ``diffstat`` 对于比较大的补 +ä¸ç‰¹åˆ«æœ‰ç”¨ã€‚ +使用 ``diffstat`` 的选项 ``-p 1 -w 70`` è¿™æ ·æ–‡ä»¶åå°±ä¼šä»Žå†…æ ¸æºä»£ç æ ‘çš„ç›®å½•å¼€å§‹ ，ä¸ä¼šå 用太宽的空间（很容易适åˆ80列的宽度，也许会有一些缩进。） +（ ``git`` 默认会生æˆåˆé€‚çš„diffstat。） + +其余那些åªé€‚用于当时或者与维护者相关的注解，ä¸åˆé€‚放到永久的改动日志里的，也 +应该放这里。较好的例å就是 ``è¡¥ä¸æ›´æ”¹è®°å½•`` ，记录了v1å’Œv2版本补ä¸ä¹‹é—´çš„差异。 + +请将æ¤ä¿¡æ¯æ”¾åœ¨å°†å˜æ›´æ—¥å¿—与补ä¸çš„其余部分分隔开的 ``---`` è¡Œ **之åŽ** 。版本 +ä¿¡æ¯ä¸æ˜¯æ交到gitæ ‘çš„å˜æ›´æ—¥å¿—的一部分。åªæ˜¯ä¾›å®¡é˜…äººå‘˜ä½¿ç”¨çš„é™„åŠ ä¿¡æ¯ã€‚如果将 +其放置在æäº¤æ ‡è®°ä¸Šæ–¹ï¼Œåˆ™éœ€è¦æ‰‹åŠ¨äº¤äº’æ‰èƒ½å°†å…¶åˆ 除。如果它ä½äºŽåˆ†éš”线以下，则在 +应用补ä¸æ—¶ä¼šè‡ªåŠ¨å‰¥ç¦»:: + + <commit message> + ... + Signed-off-by: Author <author@mail> + --- + V2 -> V3: Removed redundant helper function + V1 -> V2: Cleaned up coding style and addressed review comments -在åŽé¢çš„å‚考资料ä¸èƒ½çœ‹åˆ°é€‚当的补ä¸æ ¼å¼çš„更多细节。 + path/to/file | 5+++-- + ... -.. _cn_explicit_in_reply_to: +在åŽé¢çš„å‚考资料ä¸èƒ½çœ‹åˆ°æ£ç¡®è¡¥ä¸æ ¼å¼çš„更多细节。 -15) 明确回å¤é‚®ä»¶å¤´(In-Reply-To) -------------------------------- +.. _zh_backtraces: -æ‰‹åŠ¨æ·»åŠ å›žå¤è¡¥ä¸çš„çš„æ ‡é¢˜å¤´(In-Reply_To:) 是有帮助的（例如，使用 ``git send-email`` ） -将补ä¸ä¸Žä»¥å‰çš„相关讨论关è”èµ·æ¥ï¼Œä¾‹å¦‚，将bugä¿®å¤ç¨‹åºé“¾æŽ¥åˆ°ç”µå邮件和bug报告。 +æ交消æ¯ä¸çš„回溯（Backtraces） +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +回溯有助于记录导致问题的调用链。然而，并éžæ‰€æœ‰å›žæº¯éƒ½æœ‰å¸®åŠ©ã€‚例如，早期引导调 +用链是独特而明显的。而é€å—å¤åˆ¶å®Œæ•´çš„dmesgè¾“å‡ºåˆ™ä¼šå¢žåŠ æ—¶é—´æˆ³ã€æ¨¡å—列表ã€å¯„å˜ +å™¨å’Œå †æ ˆè½¬å‚¨ç‰åˆ†æ•£æ³¨æ„力的信æ¯ã€‚ + +å› æ¤ï¼Œæœ€æœ‰ç”¨çš„回溯应该从转储ä¸æå–相关信æ¯ï¼Œä»¥æ›´å®¹æ˜“集ä¸åœ¨çœŸå®žé—®é¢˜ä¸Šã€‚下é¢æ˜¯ +一个剪è£è‰¯å¥½çš„回溯示例:: + + unchecked MSR access error: WRMSR to 0xd51 (tried to write 0x0000000000000064) + at rIP: 0xffffffffae059994 (native_write_msr+0x4/0x20) + Call Trace: + mba_wrmsr + update_domains + rdtgroup_mkdir + +.. _zh_explicit_in_reply_to: + +明确回å¤é‚®ä»¶å¤´ï¼ˆIn-Reply-To） +----------------------------- + +æ‰‹åŠ¨æ·»åŠ å›žå¤è¡¥ä¸çš„的邮件头（In-Reply_To:）是有用的（例如，使用 ``git send-email`` ）， +å¯ä»¥å°†è¡¥ä¸ä¸Žä»¥å‰çš„相关讨论关è”èµ·æ¥ï¼Œä¾‹å¦‚，将bugè¡¥ä¸é“¾æŽ¥åˆ°ç”µå邮件和bug报告。 但是，对于多补ä¸ç³»åˆ—，最好é¿å…在回å¤æ—¶ä½¿ç”¨é“¾æŽ¥åˆ°è¯¥ç³»åˆ—çš„æ—§ç‰ˆæœ¬ã€‚è¿™æ ·ï¼Œ -è¡¥ä¸çš„多个版本就ä¸ä¼šæˆä¸ºç”µå邮件客户端ä¸æ— 法管ç†çš„引用åºåˆ—。如果链接有用， +è¡¥ä¸çš„多个版本就ä¸ä¼šæˆä¸ºç”µå邮件客户端ä¸æ— 法管ç†çš„å¼•ç”¨æ ‘ã€‚å¦‚æžœé“¾æŽ¥æœ‰ç”¨ï¼Œ å¯ä»¥ä½¿ç”¨ https://lore.kernel.org/ é‡å®šå‘器（例如，在å°é¢ç”µå邮件文本ä¸ï¼‰ 链接到补ä¸ç³»åˆ—的早期版本。 -16) å‘é€git pull请求 --------------------- - -如果您有一系列补ä¸ï¼Œé‚£ä¹ˆè®©ç»´æŠ¤äººå‘˜é€šè¿‡git pullæ“作将它们直接拉入å系统å˜å‚¨ -库å¯èƒ½æ˜¯æœ€æ–¹ä¾¿çš„。但是，请注æ„，从开å‘人员那里获å–è¡¥ä¸æ¯”从邮件列表ä¸èŽ·å–è¡¥ -ä¸éœ€è¦æ›´é«˜çš„ä¿¡ä»»åº¦ã€‚å› æ¤ï¼Œè®¸å¤šå系统维护人员ä¸æ„¿æ„接å—请求，特别是æ¥è‡ªæ–°çš„ -未知开å‘人员的请求。如果有疑问，您å¯ä»¥åœ¨å°é¢é‚®ä»¶ä¸ä½¿ç”¨pull 请求作为补ä¸ç³»åˆ— -æ£å¸¸å‘布的一个选项，让维护人员å¯ä»¥é€‰æ‹©ä½¿ç”¨å…¶ä¸ä¹‹ä¸€ã€‚ - -pull 请求的主题行ä¸åº”该有[Git Pull]。请求本身应该在一行ä¸åŒ…å«å˜å‚¨åº“å称和 -感兴趣的分支；它应该看起æ¥åƒ:: +ç»™å‡ºåŸºç¡€æ ‘ä¿¡æ¯ +-------------- - Please pull from +当其他开å‘人员收到您的补ä¸å¹¶å¼€å§‹å®¡é˜…时，知é“应该将您的工作放到代ç æ ‘åŽ†å²è®°å½• +ä¸çš„什么ä½ç½®é€šå¸¸å¾ˆæœ‰ç”¨ã€‚这对于自动化æŒç»é›†æˆæµæ°´ï¼ˆCI）特别有用，这些æµæ°´çº¿è¯• +图è¿è¡Œä¸€ç³»åˆ—测试，以便在维护人员开始审阅之å‰ç¡®å®šæ交的质é‡ã€‚ - git://jdelvare.pck.nerim.net/jdelvare-2.6 i2c-for-linus +如果您使用 ``git format-patch`` 生æˆè¡¥ä¸ï¼Œåˆ™å¯ä»¥é€šè¿‡ ``--base`` æ ‡å¿—åœ¨æäº¤ä¸ +自动包å«åŸºç¡€æ ‘ä¿¡æ¯ã€‚使用æ¤é€‰é¡¹æœ€ç®€å•ã€æœ€æ–¹ä¾¿çš„方法是é…åˆä¸»é¢˜åˆ†æ”¯:: - to get these changes: + $ git checkout -t -b my-topical-branch master + Branch 'my-topical-branch' set up to track local branch 'master'. + Switched to a new branch 'my-topical-branch' + [perform your edits and commits] -pull 请求还应该包å«ä¸€æ¡æ•´ä½“消æ¯ï¼Œè¯´æ˜Žè¯·æ±‚ä¸å°†åŒ…å«ä»€ä¹ˆï¼Œä¸€ä¸ªè¡¥ä¸æœ¬èº«çš„ ``Git shortlog`` -以åŠä¸€ä¸ªæ˜¾ç¤ºè¡¥ä¸ç³»åˆ—整体效果的 ``diffstat`` 。当然，将所有这些信æ¯æ”¶é›†åœ¨ä¸€èµ· -的最简å•æ–¹æ³•æ˜¯è®© ``git`` 使用 ``git request-pull`` 命令为您完æˆè¿™äº›å·¥ä½œã€‚ + $ git format-patch --base=auto --cover-letter -o outgoing/ master + outgoing/0000-cover-letter.patch + outgoing/0001-First-Commit.patch + outgoing/... -一些维护人员（包括Linus）希望看到æ¥è‡ªå·²ç¾åæäº¤çš„è¯·æ±‚ï¼›è¿™å¢žåŠ äº†ä»–ä»¬å¯¹ä½ çš„ -请求信心。特别是，在没有ç¾åæ ‡ç¾çš„情况下，Linus ä¸ä¼šä»Žåƒ Github è¿™æ ·çš„å…¬å…± -托管站点拉请求。 +å½“ä½ ç¼–è¾‘ ``outgoing/0000-cover-letter.patch`` 时，您会注æ„到在它的最底部有一 +è¡Œ ``base-commit:`` 尾注，它为审阅者和CI工具æ供了足够的信æ¯ä»¥æ£ç¡®æ‰§è¡Œ +``git am`` 而ä¸å¿…担心冲çª:: -创建æ¤ç±»ç¾å的第一æ¥æ˜¯ç”Ÿæˆä¸€ä¸ª GNRPG å¯†é’¥ï¼Œå¹¶ç”±ä¸€ä¸ªæˆ–å¤šä¸ªæ ¸å¿ƒå†…æ ¸å¼€å‘人员对 -其进行ç¾å。这一æ¥å¯¹æ–°å¼€å‘人员æ¥è¯´å¯èƒ½å¾ˆå›°éš¾ï¼Œä½†æ²¡æœ‰åŠžæ³•ç»•è¿‡å®ƒã€‚å‚åŠ ä¼šè®®æ˜¯ -找到å¯ä»¥ç¾ç½²æ‚¨çš„密钥的开å‘人员的好方法。 + $ git checkout -b patch-review [base-commit-id] + Switched to a new branch 'patch-review' + $ git am patches.mbox + Applying: First Commit + Applying: ... -一旦您在Git ä¸å‡†å¤‡äº†ä¸€ä¸ªæ‚¨å¸Œæœ›æœ‰äººæ‹‰çš„è¡¥ä¸ç³»åˆ—，就用 ``git tag -s`` 创建一 -个ç¾åæ ‡è®°ã€‚è¿™å°†åˆ›å»ºä¸€ä¸ªæ–°æ ‡è®°ï¼Œæ ‡è¯†è¯¥ç³»åˆ—ä¸çš„最åŽä¸€æ¬¡æ交，并包å«ç”¨æ‚¨çš„ç§ -钥创建的ç¾å。您还å¯ä»¥å°†changelogæ ·å¼çš„消æ¯æ·»åŠ åˆ°æ ‡è®°ä¸ï¼›è¿™æ˜¯ä¸€ä¸ªæ述拉请求 -整体效果的ç†æƒ³ä½ç½®ã€‚ +有关æ¤é€‰é¡¹çš„更多信æ¯ï¼Œè¯·å‚阅 ``man git-format-patch`` 。 -如果维护人员将è¦ä»Žä¸æå–çš„æ ‘ä¸æ˜¯æ‚¨æ£åœ¨ä½¿ç”¨çš„å˜å‚¨åº“，请ä¸è¦å¿˜è®°å°†å·²ç¾åçš„æ ‡è®° -显å¼æŽ¨é€åˆ°å…¬å…±æ ‘。 +.. note:: -生æˆæ‹‰è¯·æ±‚时，请使用已ç¾åçš„æ ‡è®°ä½œä¸ºç›®æ ‡ã€‚è¿™æ ·çš„å‘½ä»¤å¯ä»¥å®žçŽ°:: + ``--base`` 功能是在2.9.0版gitä¸å¼•å…¥çš„。 - git request-pull master git://my.public.tree/linux.git my-signed-tag +如果您ä¸ä½¿ç”¨gitæ ¼å¼åŒ–è¡¥ä¸ï¼Œä»ç„¶å¯ä»¥åŒ…å«ç›¸åŒçš„ ``base-commit`` 尾注，以指示您 +çš„å·¥ä½œæ‰€åŸºäºŽçš„æ ‘çš„æäº¤å“ˆå¸Œã€‚ä½ åº”è¯¥åœ¨å°é¢é‚®ä»¶æˆ–系列的第一个补ä¸ä¸æ·»åŠ 它，它应 +该放在 ``---`` 行的下é¢æˆ–所有其他内容之åŽï¼Œå³åªåœ¨ä½ 的电å邮件ç¾å之å‰ã€‚ å‚考文献 -------- -Andrew Morton, "The perfect patch" (tpp). +Andrew Morton，“完美的补ä¸â€ï¼ˆtpp） <https://www.ozlabs.org/~akpm/stuff/tpp.txt> -Jeff Garzik, "Linux kernel patch submission format". +Jeff Garzik，“Linuxå†…æ ¸è¡¥ä¸æäº¤æ ¼å¼â€ <https://web.archive.org/web/20180829112450/http://linux.yyz.us/patch-format.html> -Greg Kroah-Hartman, "How to piss off a kernel subsystem maintainer". +Greg Kroah-Hartman，“如何惹æ¼å†…æ ¸å系统维护人员†<http://www.kroah.com/log/linux/maintainer.html> <http://www.kroah.com/log/linux/maintainer-02.html> @@ -642,16 +643,15 @@ Greg Kroah-Hartman, "How to piss off a kernel subsystem maintainer". <http://www.kroah.com/log/linux/maintainer-06.html> -NO!!!! No more huge patch bombs to linux-kernel@vger.kernel.org people! +ä¸ï¼ï¼ï¼åˆ«å†å‘巨型补ä¸ç‚¸å¼¹ç»™linux-kernel@vger.kernel.orgçš„äººä»¬äº†ï¼ <https://lore.kernel.org/r/20050711.125305.08322243.davem@davemloft.net> -Kernel Documentation/process/coding-style.rst: - :ref:`Documentation/translations/zh_CN/process/coding-style.rst <cn_codingstyle>` +å†…æ ¸ Documentation/translations/zh_CN/process/coding-style.rst -Linus Torvalds's mail on the canonical patch format: +Linus Torvaldså…³äºŽæ ‡å‡†è¡¥ä¸æ ¼å¼çš„邮件 <https://lore.kernel.org/r/Pine.LNX.4.58.0504071023190.28951@ppc970.osdl.org> -Andi Kleen, "On submitting kernel patches" - Some strategies to get difficult or controversial changes in. +Andi Kleen，“æ交补ä¸ä¹‹è·¯â€ + 一些帮助åˆå…¥å›°éš¾æˆ–有争议的å˜æ›´çš„ç–略。 http://halobates.de/on-submitting-patches.pdf diff --git a/Documentation/translations/zh_CN/scheduler/sched-design-CFS.rst b/Documentation/translations/zh_CN/scheduler/sched-design-CFS.rst index 26b0f36f793d..3076402406c4 100644 --- a/Documentation/translations/zh_CN/scheduler/sched-design-CFS.rst +++ b/Documentation/translations/zh_CN/scheduler/sched-design-CFS.rst @@ -80,7 +80,7 @@ p->se.vruntime。一旦p->se.vruntimeå˜å¾—足够大，其它的任务将æˆä¸ºæ CFS使用纳秒粒度的计时，ä¸ä¾èµ–于任何jiffies或HZçš„ç»†èŠ‚ã€‚å› æ¤CFS并ä¸åƒä¹‹å‰çš„è°ƒåº¦å™¨é‚£æ · 有“时间片â€çš„概念，也没有任何å¯å‘å¼çš„设计。唯一å¯è°ƒçš„å‚æ•°ï¼ˆä½ éœ€è¦æ‰“å¼€CONFIG_SCHED_DEBUG）是： - /proc/sys/kernel/sched_min_granularity_ns + /sys/kernel/debug/sched/min_granularity_ns 它å¯ä»¥ç”¨æ¥å°†è°ƒåº¦å™¨ä»Žâ€œæ¡Œé¢â€æ¨¡å¼ï¼ˆä¹Ÿå°±æ˜¯ä½Žæ—¶å»¶ï¼‰è°ƒèŠ‚为“æœåŠ¡å™¨â€ï¼ˆä¹Ÿå°±æ˜¯é«˜æ‰¹å¤„ç†ï¼‰æ¨¡å¼ã€‚ 它的默认设置是适åˆæ¡Œé¢çš„工作负载。SCHED_BATCH也被CFS调度器模å—处ç†ã€‚ diff --git a/Documentation/translations/zh_TW/oops-tracing.txt b/Documentation/translations/zh_TW/oops-tracing.txt deleted file mode 100644 index be8e59f2abaf..000000000000 --- a/Documentation/translations/zh_TW/oops-tracing.txt +++ /dev/null @@ -1,212 +0,0 @@ -Chinese translated version of Documentation/admin-guide/bug-hunting.rst - -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. - -Traditional Chinese maintainer: Hu Haowen <src.res@email.cn> ---------------------------------------------------------------------- -Documentation/admin-guide/bug-hunting.rst çš„ç¹é«”ä¸æ–‡ç‰ˆç¿»è¯ - -如果想評論或更新本文的內容，請直接è¯ç¹«åŽŸæ–‡æª”çš„ç¶è·è€…ã€‚å¦‚æžœä½ ä½¿ç”¨è‹±æ–‡ -交æµæœ‰å›°é›£çš„話，也å¯ä»¥å‘ç¹é«”ä¸æ–‡ç‰ˆç¶è·è€…求助。如果本翻è¯æ›´æ–°ä¸åŠæ™‚或 -者翻è¯å˜åœ¨å•é¡Œï¼Œè«‹è¯ç¹«ç¹é«”ä¸æ–‡ç‰ˆç¶è·è€…。 - -ç¹é«”ä¸æ–‡ç‰ˆç¶è·è€…： 胡皓文 Hu Haowen <src.res@email.cn> -ç¹é«”ä¸æ–‡ç‰ˆç¿»è¯è€…： 胡皓文 Hu Haowen <src.res@email.cn> -ç¹é«”ä¸æ–‡ç‰ˆæ ¡è¯è€…： 胡皓文 Hu Haowen <src.res@email.cn> - -以下爲æ£æ–‡ ---------------------------------------------------------------------- - -注æ„： ksymoops 在2.6ä¸æ˜¯æ²’有用的。 è«‹ä»¥åŽŸæœ‰æ ¼å¼ä½¿ç”¨Oops(來自dmesg，ç‰ç‰)。 -忽略任何這樣那樣關於「解碼Oopsã€æˆ–者「通éŽksymoopsé‹è¡Œã€çš„文檔。 å¦‚æžœä½ è²¼å‡ºé‹è¡ŒéŽ -ksymoops的來自2.6çš„Oops，人們åªæœƒè®“ä½ é‡è²¼ä¸€æ¬¡ã€‚ - -å¿«é€Ÿç¸½çµ -------------- - -發ç¾Oops並發é€çµ¦çœ‹ä¼¼ç›¸é—œçš„å…§æ ¸é ˜åŸŸçš„ç¶è·è€…。別太擔心å°ä¸ä¸Šè™Ÿã€‚å¦‚æžœä½ ä¸ç¢ºå®šå°±ç™¼çµ¦ -å’Œä½ æ‰€åšçš„äº‹æƒ…ç›¸é—œçš„ä»£ç¢¼çš„è² è²¬äººã€‚ 如果å¯é‡ç¾è©¦è‘—æ述怎樣é‡æ§‹ã€‚ 那甚至比oops更有 -價值。 - -å¦‚æžœä½ å°æ–¼ç™¼é€çµ¦èª°ä¸€ç„¡æ‰€çŸ¥ï¼Œ 發給linux-kernel@vger.kernel.org。感è¬ä½ 幫助Linux -儘å¯èƒ½åœ°ç©©å®šã€‚ - -Oops在哪裡? ----------------------- - -通常Oops文本由klogdå¾žå…§æ ¸ç·©è¡å€é‡Œè®€å–並傳給syslogd，由syslogd寫到syslog文件ä¸ï¼Œ -典型地是/var/log/messages(ä¾è³´æ–¼/etc/syslog.conf)。有時klogd崩潰了,這種情æ³ä¸‹ä½ -èƒ½å¤ é‹è¡Œdmesg > fileä¾†å¾žå…§æ ¸ç·©è¡å€ä¸è®€å–數據並ä¿å˜ä¸‹ä¾†ã€‚ å¦å‰‡ä½ å¯ä»¥ -cat /proc/kmsg > file， ç„¶è€Œä½ å¿…é ˆä»‹å…¥ä¸æ¢å‚³è¼¸ï¼Œ kmsg是一個「永ä¸çµæŸçš„文件ã€ã€‚如 -æžœæ©Ÿå™¨å´©æ½°å£žåˆ°ä½ ä¸èƒ½è¼¸å…¥å‘½ä»¤æˆ–者ç£ç¢Ÿä¸å¯ç”¨é‚£éº¼ä½ 有三種é¸æ“‡:- - -（1） 手抄å±å¹•ä¸Šçš„文本待機器é‡å•“後å†è¼¸å…¥è¨ˆç®—機。 麻煩但如果沒有é‡å°å´©æ½°çš„準備， -這是僅有的é¸æ“‡ã€‚ å¦å¤–ï¼Œä½ å¯ä»¥ç”¨æ•¸ä½ç›¸æ©ŸæŠŠå±å¹•æ‹ä¸‹ä¾†-ä¸å¤ªå¥½ï¼Œä½†æ¯”沒有強。 如果信 -æ¯æ»¾å‹•åˆ°äº†çµ‚端的上é¢ï¼Œä½ 會發ç¾ä»¥é«˜åˆ†è¾¯çŽ‡å•“動（比如，vga=791ï¼‰æœƒè®“ä½ è®€åˆ°æ›´å¤šçš„æ–‡ -本。（注æ„：這需è¦vesafb，所以å°ã€Žæ—©æœŸã€çš„oops沒有幫助） - -（2）用串å£çµ‚端啓動（請åƒçœ‹Documentation/admin-guide/serial-console.rst），é‹è¡Œä¸€å€‹null -modem到å¦ä¸€å°æ©Ÿå™¨ä¸¦ç”¨ä½ å–œæ¡çš„通訊工具ç²å–輸出。Minicom工作地很好。 - -（3）使用Kdump（請åƒçœ‹Documentation/admin-guide/kdump/kdump.rst）， -使用在Documentation/admin-guide/kdump/gdbmacros.txtä¸å®šç¾©çš„dmesg gdbå®ï¼Œå¾žèˆŠçš„å…§å˜ä¸æå–å…§æ ¸ -環形緩è¡å€ã€‚ - -å®Œæ•´ä¿¡æ¯ ----------------- - -注æ„：以下來自於Linus的郵件é©ç”¨æ–¼2.4å…§æ ¸ã€‚ æˆ‘å› çˆ²æ·å²åŽŸå› ä¿ç•™äº†å®ƒï¼Œä¸¦ä¸”å› çˆ²å…¶ä¸ -一些信æ¯ä»ç„¶é©ç”¨ã€‚ 特別注æ„的是，請忽略任何ksymoops的引用。 - -From: Linus Torvalds <torvalds@osdl.org> - -怎樣跟蹤Oops.. [原發到linux-kernel的一å°éƒµä»¶] - -主è¦çš„竅門是有五年和這些煩人的oops消æ¯æ‰“交é“的經驗;-) - -å¯¦éš›ä¸Šï¼Œä½ æœ‰è¾¦æ³•ä½¿å®ƒæ›´ç°¡å–®ã€‚æˆ‘æœ‰å…©å€‹ä¸åŒçš„方法： - - gdb /usr/src/linux/vmlinux - gdb> disassemble <offending_function> - -那是發ç¾å•é¡Œçš„簡單辦法，至少如果bugå ±å‘Šåšçš„好的情æ³ä¸‹ï¼ˆè±¡é€™å€‹ä¸€æ¨£-é‹è¡Œksymoops -得到oops發生的函數åŠå‡½æ•¸å…§çš„å移）。 - -å“¦ï¼Œå¦‚æžœå ±å‘Šç™¼ç”Ÿçš„å…§æ ¸ä»¥ç›¸åŒçš„ç·¨è¯å™¨å’Œç›¸ä¼¼çš„é…置編è¯å®ƒæœƒæœ‰å¹«åŠ©çš„。 - -å¦ä¸€ä»¶è¦åšçš„事是å彙編bugå ±å‘Šçš„ã€ŒCodeã€éƒ¨åˆ†ï¼šksymoops也會用æ£ç¢ºçš„工具來åšé€™ä»¶äº‹ï¼Œ -ä½†å¦‚æžœæ²’æœ‰é‚£äº›å·¥å…·ä½ å¯ä»¥å¯«ä¸€å€‹å‚»ç¨‹åºï¼š - - char str[] = "\xXX\xXX\xXX..."; - main(){} - -並用gcc -gç·¨è¯å®ƒç„¶å¾ŒåŸ·è¡Œã€Œdisassemble strã€ï¼ˆXX部分是由Oopså ±å‘Šçš„å€¼-ä½ å¯ä»¥åƒ…剪切 -粘貼並用「\xã€æ›¿æ›ç©ºæ ¼-我就是這麼åšçš„ï¼Œå› çˆ²æˆ‘æ‡¶å¾—å¯«ç¨‹åºè‡ªå‹•åšé€™ä¸€åˆ‡ï¼‰ã€‚ - -å¦å¤–ï¼Œä½ å¯ä»¥ç”¨scripts/decodecode這個shell腳本。它的使用方法是： -decodecode < oops.txt - -「Codeã€ä¹‹å¾Œçš„åå…進ä½å—節å¯èƒ½ï¼ˆåœ¨æŸäº›æž¶æ§‹ä¸Šï¼‰æœ‰ä¸€äº›ç•¶å‰æŒ‡ä»¤ä¹‹å‰çš„指令å—ç¯€ä»¥åŠ -當å‰å’Œä¹‹å¾Œçš„指令å—節 - -Code: f9 0f 8d f9 00 00 00 8d 42 0c e8 dd 26 11 c7 a1 60 ea 2b f9 8b 50 08 a1 -64 ea 2b f9 8d 34 82 8b 1e 85 db 74 6d 8b 15 60 ea 2b f9 <8b> 43 04 39 42 54 -7e 04 40 89 42 54 8b 43 04 3b 05 00 f6 52 c0 - -æœ€å¾Œï¼Œå¦‚æžœä½ æƒ³çŸ¥é“ä»£ç¢¼ä¾†è‡ªå“ªè£¡ï¼Œä½ å¯ä»¥ï¼š - - cd /usr/src/linux - make fs/buffer.s # 或任何產生BUG的文件 - -ç„¶å¾Œä½ æœƒæ¯”gdbå彙編更清楚的知é“發生了什麼。 - -ç¾åœ¨ï¼Œå•é¡Œæ˜¯æŠŠä½ 所æ“有的所有數據çµåˆèµ·ä¾†ï¼šCæºç¢¼ï¼ˆé—œæ–¼å®ƒæ‡‰è©²æ€Žæ¨£çš„一般知è˜ï¼‰ï¼Œ -彙編代碼åŠå…¶å彙編得到的代碼（å¦å¤–還有從「oopsã€æ¶ˆæ¯å¾—到的寄å˜å™¨ç‹€æ…‹-å°äº†è§£æ¯€å£žçš„ -指é‡æœ‰ç”¨ï¼Œè€Œä¸”ç•¶ä½ æœ‰äº†å½™ç·¨ä»£ç¢¼ä½ ä¹Ÿèƒ½æ‹¿å…¶å®ƒçš„å¯„å˜å™¨å’Œä»»ä½•å®ƒå€‘å°æ‡‰çš„C表é”å¼åšåŒ¹é… -）。 - -å¯¦éš›ä¸Šï¼Œä½ åƒ…éœ€çœ‹çœ‹å“ªè£¡ä¸åŒ¹é…（這個例å是「Codeã€å彙編和編è¯å™¨ç”Ÿæˆçš„代碼ä¸åŒ¹é…）。 -ç„¶å¾Œä½ é ˆè¦æ‰¾å‡ºçˆ²ä»€éº¼ä¸åŒ¹é…。通常很簡單-ä½ çœ‹åˆ°ä»£ç¢¼ä½¿ç”¨äº†ç©ºæŒ‡é‡ç„¶å¾Œä½ çœ‹ä»£ç¢¼æƒ³çŸ¥é“ -空指é‡æ˜¯æ€Žéº¼å‡ºç¾çš„，還有檢查它是å¦åˆæ³•.. - -ç¾åœ¨ï¼Œå¦‚æžœæ˜Žç™½é€™æ˜¯ä¸€é …è€—æ™‚çš„å·¥ä½œè€Œä¸”éœ€è¦ä¸€ä¸é»žå…’的專心，沒錯。這就是我爲什麼大多 -åªæ˜¯å¿½ç•¥é‚£äº›æ²’有符號表信æ¯çš„å´©æ½°å ±å‘Šçš„åŽŸå› ï¼šç°¡å–®çš„èªªå¤ªé›£æŸ¥æ‰¾äº†ï¼ˆæˆ‘æœ‰ä¸€äº› -程åºç”¨æ–¼åœ¨å…§æ ¸ä»£ç¢¼æ®µä¸æœç´¢ç‰¹å®šçš„模å¼ï¼Œè€Œä¸”有時我也已經能找出那些崩潰的地方，但是 -僅僅是找出æ£ç¢ºçš„åºåˆ—也確實需è¦ç›¸ç•¶ç´®å¯¦çš„å…§æ ¸çŸ¥è˜ï¼‰ - -_有時_會發生這種情æ³ï¼Œæˆ‘僅看到崩潰ä¸çš„å彙編代碼åºåˆ—， 然後我馬上就明白å•é¡Œå‡ºåœ¨ -哪裡。這時我æ‰æ„è˜åˆ°è‡ªå·±å¹¹é€™å€‹å·¥ä½œå·²ç¶“太長時間了;-) - - Linus - - ---------------------------------------------------------------------------- -關於Oops跟蹤的註解： - -爲了幫助Linuså’Œå…¶å®ƒå…§æ ¸é–‹ç™¼è€…ï¼Œklogdç´å…¥äº†å¤§é‡çš„支æŒä¾†è™•ç†ä¿è·éŒ¯èª¤ã€‚爲了æ“æœ‰å° -地å€è§£æžçš„完整支æŒè‡³å°‘應該使用1.3-pl3çš„sysklogd包。 - -當ä¿è·éŒ¯èª¤ç™¼ç”Ÿæ™‚，klogd守è·é€²ç¨‹è‡ªå‹•æŠŠå…§æ ¸æ—¥èªŒä¿¡æ¯ä¸çš„é‡è¦åœ°å€ç¿»è¯æˆå®ƒå€‘相應的符 -號。 - -klogd執行兩種類型的地å€è§£æžã€‚首先是éœæ…‹ç¿»è¯å…¶æ¬¡æ˜¯å‹•æ…‹ç¿»è¯ã€‚éœæ…‹ç¿»è¯å’Œksymoops -一樣使用System.map文件。爲了åšéœæ…‹ç¿»è¯klogd守è·é€²ç¨‹å¿…é ˆåœ¨åˆå§‹åŒ–時能找到system -map文件。關於klogd怎樣æœç´¢map文件請åƒçœ‹klogd手冊é 。 - -動態地å€ç¿»è¯åœ¨ä½¿ç”¨å…§æ ¸å¯è£è¼‰æ¨¡å¡Šæ™‚很é‡è¦ã€‚ å› çˆ²å…§æ ¸æ¨¡å¡Šçš„å…§å˜æ˜¯å¾žå…§æ ¸å‹•æ…‹å…§å˜æ± -里分é…的，所以ä¸ç®¡æ˜¯æ¨¡å¡Šé–‹å§‹ä½ç½®é‚„是模塊ä¸å‡½æ•¸å’Œç¬¦è™Ÿçš„ä½ç½®éƒ½ä¸æ˜¯å›ºå®šçš„。 - -å…§æ ¸æ”¯æŒå…許程åºæ±ºå®šè£è¼‰å“ªäº›æ¨¡å¡Šå’Œå®ƒå€‘在內å˜ä¸ä½ç½®çš„系統調用。使用這些系統調用 -klogd守è·é€²ç¨‹ç”Ÿæˆä¸€å¼µç¬¦è™Ÿè¡¨ç”¨æ–¼èª¿è©¦ç™¼ç”Ÿåœ¨å¯è£è¼‰æ¨¡å¡Šä¸çš„ä¿è·éŒ¯èª¤ã€‚ - -至少klogd會æ供產生ä¿è·éŒ¯èª¤çš„模塊å。還å¯æœ‰é¡å¤–的符號信æ¯ä¾›å¯è£è¼‰æ¨¡å¡Šé–‹ç™¼è€…é¸æ“‡ -以從模塊ä¸è¼¸å‡ºç¬¦è™Ÿä¿¡æ¯ã€‚ - -å› çˆ²å…§æ ¸æ¨¡å¡Šç’°å¢ƒå¯èƒ½æ˜¯å‹•æ…‹çš„ï¼Œæ‰€ä»¥å¿…é ˆæœ‰ä¸€ç¨®æ©Ÿåˆ¶ç•¶æ¨¡å¡Šç’°å¢ƒç™¼ç”Ÿæ”¹è®Šæ™‚ä¾†é€šçŸ¥klogd -守è·é€²ç¨‹ã€‚ 有一些å¯ç”¨çš„命令行é¸é …å…許klogdå‘當å‰åŸ·è¡Œä¸çš„守è·é€²ç¨‹ç™¼é€ä¿¡è™Ÿï¼Œå‘ŠçŸ¥ç¬¦ -號信æ¯æ‡‰è©²è¢«åˆ·æ–°äº†ã€‚ 更多信æ¯è«‹åƒçœ‹klogd手冊é 。 - -sysklogd發布時包å«ä¸€å€‹è£œä¸ä¿®æ”¹äº†modules-2.0.0包，無論何時一個模塊è£è¼‰æˆ–者å¸è¼‰éƒ½ -會自動å‘klogd發é€ä¿¡è™Ÿã€‚打上這個補ä¸æ供了必è¦çš„å°èª¿è©¦ç™¼ç”Ÿæ–¼å…§æ ¸å¯è£è¼‰æ¨¡å¡Šçš„ä¿è· -錯誤的無縫支æŒã€‚ - -以下是被klogd處ç†éŽçš„發生在å¯è£è¼‰æ¨¡å¡Šä¸çš„一個ä¿è·éŒ¯èª¤ä¾‹å： ---------------------------------------------------------------------------- -Aug 29 09:51:01 blizard kernel: Unable to handle kernel paging request at virtual address f15e97cc -Aug 29 09:51:01 blizard kernel: current->tss.cr3 = 0062d000, %cr3 = 0062d000 -Aug 29 09:51:01 blizard kernel: *pde = 00000000 -Aug 29 09:51:01 blizard kernel: Oops: 0002 -Aug 29 09:51:01 blizard kernel: CPU: 0 -Aug 29 09:51:01 blizard kernel: EIP: 0010:[oops:_oops+16/3868] -Aug 29 09:51:01 blizard kernel: EFLAGS: 00010212 -Aug 29 09:51:01 blizard kernel: eax: 315e97cc ebx: 003a6f80 ecx: 001be77b edx: 00237c0c -Aug 29 09:51:01 blizard kernel: esi: 00000000 edi: bffffdb3 ebp: 00589f90 esp: 00589f8c -Aug 29 09:51:01 blizard kernel: ds: 0018 es: 0018 fs: 002b gs: 002b ss: 0018 -Aug 29 09:51:01 blizard kernel: Process oops_test (pid: 3374, process nr: 21, stackpage=00589000) -Aug 29 09:51:01 blizard kernel: Stack: 315e97cc 00589f98 0100b0b4 bffffed4 0012e38e 00240c64 003a6f80 00000001 -Aug 29 09:51:01 blizard kernel: 00000000 00237810 bfffff00 0010a7fa 00000003 00000001 00000000 bfffff00 -Aug 29 09:51:01 blizard kernel: bffffdb3 bffffed4 ffffffda 0000002b 0007002b 0000002b 0000002b 00000036 -Aug 29 09:51:01 blizard kernel: Call Trace: [oops:_oops_ioctl+48/80] [_sys_ioctl+254/272] [_system_call+82/128] -Aug 29 09:51:01 blizard kernel: Code: c7 00 05 00 00 00 eb 08 90 90 90 90 90 90 90 90 89 ec 5d c3 ---------------------------------------------------------------------------- - -Dr. G.W. Wettstein Oncology Research Div. Computing Facility -Roger Maris Cancer Center INTERNET: greg@wind.rmcc.com -820 4th St. N. -Fargo, ND 58122 -Phone: 701-234-7556 - - ---------------------------------------------------------------------------- -å—æ±™æŸ“çš„å…§æ ¸ - -一些oopså ±å‘Šåœ¨ç¨‹åºè¨˜æ•¸å™¨ä¹‹å¾ŒåŒ…å«å—符串'Tainted: 'ã€‚é€™è¡¨æ˜Žå…§æ ¸å·²ç¶“è¢«ä¸€äº›æ±è¥¿çµ¦æ±™ -染了。 該å—符串之後緊跟著一系列的ä½ç½®æ•æ„Ÿçš„å—符，æ¯å€‹ä»£è¡¨ä¸€å€‹ç‰¹å®šçš„汙染值。 - - 1：'G'如果所有è£è¼‰çš„模塊都有GPL或相容的許å¯è‰ï¼Œ'P'如果è£è¼‰äº†ä»»ä½•çš„專有模塊。 -沒有模塊MODULE_LICENSE或者帶有insmodèªçˆ²æ˜¯èˆ‡GPLä¸ç›¸å®¹çš„çš„MODULE_LICENSE的模塊被 -èªå®šæ˜¯å°ˆæœ‰çš„。 - - 2：'F'如果有任何通éŽã€Œinsmod -fã€è¢«å¼·åˆ¶è£è¼‰çš„模塊，' '如果所有模塊都被æ£å¸¸è£è¼‰ã€‚ - - 3：'S'如果oops發生在SMPå…§æ ¸ä¸ï¼Œé‹è¡Œæ–¼æ²’有è‰æ˜Žå®‰å…¨é‹è¡Œå¤šè™•ç†å™¨çš„硬體。 當å‰é€™ç¨® -情æ³åƒ…é™æ–¼å¹¾ç¨®ä¸æ”¯æŒSMP的速é¾è™•ç†å™¨ã€‚ - - 4：'R'如果模塊通éŽã€Œinsmod -fã€è¢«å¼·åˆ¶è£è¼‰ï¼Œ' '如果所有模塊都被æ£å¸¸è£è¼‰ã€‚ - - 5：'M'如果任何處ç†å™¨å ±å‘Šäº†æ©Ÿå™¨æª¢æŸ¥ç•°å¸¸ï¼Œ' '如果沒有發生機器檢查異常。 - - 6：'B'如果é 釋放函數發ç¾äº†ä¸€å€‹éŒ¯èª¤çš„é 引用或者一些éžé 期的é 標誌。 - - 7：'U'如果用戶或者用戶應用程å¼ç‰¹åˆ¥è«‹æ±‚è¨ç½®æ±™æŸ“標誌，å¦å‰‡' '。 - - 8：'D'å¦‚æžœå…§æ ¸å‰›å‰›æ»æŽ‰ï¼Œæ¯”如有OOPS或者BUG。 - -使用'Tainted: 'å—符串的主è¦åŽŸå› 是è¦å‘Šè¨´å…§æ ¸èª¿è©¦è€…，這是å¦æ˜¯ä¸€å€‹ä¹¾æ·¨çš„å…§æ ¸äº¦æˆ–ç™¼ -生了任何的ä¸æ£å¸¸çš„事。汙染是永久的：å³ä½¿å‡ºéŒ¯çš„模塊已經被å¸è¼‰äº†ï¼Œæ±™æŸ“值ä»ç„¶å˜åœ¨ï¼Œ -ä»¥è¡¨æ˜Žå…§æ ¸ä¸å†å€¼å¾—信任。 - diff --git a/Documentation/userspace-api/index.rst b/Documentation/userspace-api/index.rst index a61eac0c73f8..c78da9ce0ec4 100644 --- a/Documentation/userspace-api/index.rst +++ b/Documentation/userspace-api/index.rst @@ -26,6 +26,7 @@ place where this information is gathered. ioctl/index iommu media/index + netlink/index sysfs-platform_profile vduse futex2 diff --git a/Documentation/userspace-api/ioctl/ioctl-number.rst b/Documentation/userspace-api/ioctl/ioctl-number.rst index 3b985b19f39d..5f81e2a24a5c 100644 --- a/Documentation/userspace-api/ioctl/ioctl-number.rst +++ b/Documentation/userspace-api/ioctl/ioctl-number.rst @@ -308,7 +308,6 @@ Code Seq# Include File Comments 0x89 00-06 arch/x86/include/asm/sockios.h 0x89 0B-DF linux/sockios.h 0x89 E0-EF linux/sockios.h SIOCPROTOPRIVATE range -0x89 E0-EF linux/dn.h PROTOPRIVATE range 0x89 F0-FF linux/sockios.h SIOCDEVPRIVATE range 0x8B all linux/wireless.h 0x8C 00-3F WiNRADiO driver diff --git a/Documentation/userspace-api/landlock.rst b/Documentation/userspace-api/landlock.rst index b8ea59493964..cec780c2f497 100644 --- a/Documentation/userspace-api/landlock.rst +++ b/Documentation/userspace-api/landlock.rst @@ -8,7 +8,7 @@ Landlock: unprivileged access control ===================================== :Author: Mickaël Salaün -:Date: May 2022 +:Date: September 2022 The goal of Landlock is to enable to restrict ambient rights (e.g. global filesystem access) for a set of processes. Because Landlock is a stackable @@ -69,7 +69,7 @@ should try to protect users as much as possible whatever the kernel they are using. To avoid binary enforcement (i.e. either all security features or none), we can leverage a dedicated Landlock command to get the current version of the Landlock ABI and adapt the handled accesses. Let's check if we should -remove the `LANDLOCK_ACCESS_FS_REFER` access right which is only supported +remove the ``LANDLOCK_ACCESS_FS_REFER`` access right which is only supported starting with the second version of the ABI. .. code-block:: c @@ -128,7 +128,7 @@ descriptor. It may also be required to create rules following the same logic as explained for the ruleset creation, by filtering access rights according to the Landlock ABI version. In this example, this is not required because -`LANDLOCK_ACCESS_FS_REFER` is not allowed by any rule. +``LANDLOCK_ACCESS_FS_REFER`` is not allowed by any rule. We now have a ruleset with one rule allowing read access to ``/usr`` while denying all other handled accesses for the filesystem. The next step is to @@ -154,8 +154,8 @@ The current thread is now ready to sandbox itself with the ruleset. } close(ruleset_fd); -If the `landlock_restrict_self` system call succeeds, the current thread is now -restricted and this policy will be enforced on all its subsequently created +If the ``landlock_restrict_self`` system call succeeds, the current thread is +now restricted and this policy will be enforced on all its subsequently created children as well. Once a thread is landlocked, there is no way to remove its security policy; only adding more restrictions is allowed. These threads are now in a new Landlock domain, merge of their parent one (if any) with the new @@ -170,12 +170,13 @@ It is recommended setting access rights to file hierarchy leaves as much as possible. For instance, it is better to be able to have ``~/doc/`` as a read-only hierarchy and ``~/tmp/`` as a read-write hierarchy, compared to ``~/`` as a read-only hierarchy and ``~/tmp/`` as a read-write hierarchy. -Following this good practice leads to self-sufficient hierarchies that don't +Following this good practice leads to self-sufficient hierarchies that do not depend on their location (i.e. parent directories). This is particularly relevant when we want to allow linking or renaming. Indeed, having consistent access rights per directory enables to change the location of such directory without relying on the destination directory access rights (except those that -are required for this operation, see `LANDLOCK_ACCESS_FS_REFER` documentation). +are required for this operation, see ``LANDLOCK_ACCESS_FS_REFER`` +documentation). Having self-sufficient hierarchies also helps to tighten the required access rights to the minimal set of data. This also helps avoid sinkhole directories, i.e. directories where data can be linked to but not linked from. However, @@ -259,7 +260,7 @@ Backward and forward compatibility Landlock is designed to be compatible with past and future versions of the kernel. This is achieved thanks to the system call attributes and the -associated bitflags, particularly the ruleset's `handled_access_fs`. Making +associated bitflags, particularly the ruleset's ``handled_access_fs``. Making handled access right explicit enables the kernel and user space to have a clear contract with each other. This is required to make sure sandboxing will not get stricter with a system update, which could break applications. @@ -380,8 +381,8 @@ by the Documentation/admin-guide/cgroup-v1/memory.rst. Previous limitations ==================== -File renaming and linking (ABI 1) ---------------------------------- +File renaming and linking (ABI < 2) +----------------------------------- Because Landlock targets unprivileged access controls, it needs to properly handle composition of rules. Such property also implies rules nesting. @@ -394,7 +395,7 @@ according to the potentially lost constraints. To protect against privilege escalations through renaming or linking, and for the sake of simplicity, Landlock previously limited linking and renaming to the same directory. Starting with the Landlock ABI version 2, it is now possible to securely -control renaming and linking thanks to the new `LANDLOCK_ACCESS_FS_REFER` +control renaming and linking thanks to the new ``LANDLOCK_ACCESS_FS_REFER`` access right. .. _kernel_support: @@ -403,14 +404,14 @@ Kernel support ============== Landlock was first introduced in Linux 5.13 but it must be configured at build -time with `CONFIG_SECURITY_LANDLOCK=y`. Landlock must also be enabled at boot +time with ``CONFIG_SECURITY_LANDLOCK=y``. Landlock must also be enabled at boot time as the other security modules. The list of security modules enabled by -default is set with `CONFIG_LSM`. The kernel configuration should then -contains `CONFIG_LSM=landlock,[...]` with `[...]` as the list of other +default is set with ``CONFIG_LSM``. The kernel configuration should then +contains ``CONFIG_LSM=landlock,[...]`` with ``[...]`` as the list of other potentially useful security modules for the running system (see the -`CONFIG_LSM` help). +``CONFIG_LSM`` help). -If the running kernel doesn't have `landlock` in `CONFIG_LSM`, then we can +If the running kernel does not have ``landlock`` in ``CONFIG_LSM``, then we can still enable it by adding ``lsm=landlock,[...]`` to Documentation/admin-guide/kernel-parameters.rst thanks to the bootloader configuration. diff --git a/Documentation/userspace-api/netlink/index.rst b/Documentation/userspace-api/netlink/index.rst new file mode 100644 index 000000000000..b0c21538d97d --- /dev/null +++ b/Documentation/userspace-api/netlink/index.rst @@ -0,0 +1,12 @@ +.. SPDX-License-Identifier: BSD-3-Clause + +================ +Netlink Handbook +================ + +Netlink documentation for users. + +.. toctree:: + :maxdepth: 2 + + intro diff --git a/Documentation/userspace-api/netlink/intro.rst b/Documentation/userspace-api/netlink/intro.rst new file mode 100644 index 000000000000..0955e9f203d3 --- /dev/null +++ b/Documentation/userspace-api/netlink/intro.rst @@ -0,0 +1,681 @@ +.. SPDX-License-Identifier: BSD-3-Clause + +======================= +Introduction to Netlink +======================= + +Netlink is often described as an ioctl() replacement. +It aims to replace fixed-format C structures as supplied +to ioctl() with a format which allows an easy way to add +or extended the arguments. + +To achieve this Netlink uses a minimal fixed-format metadata header +followed by multiple attributes in the TLV (type, length, value) format. + +Unfortunately the protocol has evolved over the years, in an organic +and undocumented fashion, making it hard to coherently explain. +To make the most practical sense this document starts by describing +netlink as it is used today and dives into more "historical" uses +in later sections. + +Opening a socket +================ + +Netlink communication happens over sockets, a socket needs to be +opened first: + +.. code-block:: c + + fd = socket(AF_NETLINK, SOCK_RAW, NETLINK_GENERIC); + +The use of sockets allows for a natural way of exchanging information +in both directions (to and from the kernel). The operations are still +performed synchronously when applications send() the request but +a separate recv() system call is needed to read the reply. + +A very simplified flow of a Netlink "call" will therefore look +something like: + +.. code-block:: c + + fd = socket(AF_NETLINK, SOCK_RAW, NETLINK_GENERIC); + + /* format the request */ + send(fd, &request, sizeof(request)); + n = recv(fd, &response, RSP_BUFFER_SIZE); + /* interpret the response */ + +Netlink also provides natural support for "dumping", i.e. communicating +to user space all objects of a certain type (e.g. dumping all network +interfaces). + +.. code-block:: c + + fd = socket(AF_NETLINK, SOCK_RAW, NETLINK_GENERIC); + + /* format the dump request */ + send(fd, &request, sizeof(request)); + while (1) { + n = recv(fd, &buffer, RSP_BUFFER_SIZE); + /* one recv() call can read multiple messages, hence the loop below */ + for (nl_msg in buffer) { + if (nl_msg.nlmsg_type == NLMSG_DONE) + goto dump_finished; + /* process the object */ + } + } + dump_finished: + +The first two arguments of the socket() call require little explanation - +it is opening a Netlink socket, with all headers provided by the user +(hence NETLINK, RAW). The last argument is the protocol within Netlink. +This field used to identify the subsystem with which the socket will +communicate. + +Classic vs Generic Netlink +-------------------------- + +Initial implementation of Netlink depended on a static allocation +of IDs to subsystems and provided little supporting infrastructure. +Let us refer to those protocols collectively as **Classic Netlink**. +The list of them is defined on top of the ``include/uapi/linux/netlink.h`` +file, they include among others - general networking (NETLINK_ROUTE), +iSCSI (NETLINK_ISCSI), and audit (NETLINK_AUDIT). + +**Generic Netlink** (introduced in 2005) allows for dynamic registration of +subsystems (and subsystem ID allocation), introspection and simplifies +implementing the kernel side of the interface. + +The following section describes how to use Generic Netlink, as the +number of subsystems using Generic Netlink outnumbers the older +protocols by an order of magnitude. There are also no plans for adding +more Classic Netlink protocols to the kernel. +Basic information on how communicating with core networking parts of +the Linux kernel (or another of the 20 subsystems using Classic +Netlink) differs from Generic Netlink is provided later in this document. + +Generic Netlink +=============== + +In addition to the Netlink fixed metadata header each Netlink protocol +defines its own fixed metadata header. (Similarly to how network +headers stack - Ethernet > IP > TCP we have Netlink > Generic N. > Family.) + +A Netlink message always starts with struct nlmsghdr, which is followed +by a protocol-specific header. In case of Generic Netlink the protocol +header is struct genlmsghdr. + +The practical meaning of the fields in case of Generic Netlink is as follows: + +.. code-block:: c + + struct nlmsghdr { + __u32 nlmsg_len; /* Length of message including headers */ + __u16 nlmsg_type; /* Generic Netlink Family (subsystem) ID */ + __u16 nlmsg_flags; /* Flags - request or dump */ + __u32 nlmsg_seq; /* Sequence number */ + __u32 nlmsg_pid; /* Port ID, set to 0 */ + }; + struct genlmsghdr { + __u8 cmd; /* Command, as defined by the Family */ + __u8 version; /* Irrelevant, set to 1 */ + __u16 reserved; /* Reserved, set to 0 */ + }; + /* TLV attributes follow... */ + +In Classic Netlink :c:member:`nlmsghdr.nlmsg_type` used to identify +which operation within the subsystem the message was referring to +(e.g. get information about a netdev). Generic Netlink needs to mux +multiple subsystems in a single protocol so it uses this field to +identify the subsystem, and :c:member:`genlmsghdr.cmd` identifies +the operation instead. (See :ref:`res_fam` for +information on how to find the Family ID of the subsystem of interest.) +Note that the first 16 values (0 - 15) of this field are reserved for +control messages both in Classic Netlink and Generic Netlink. +See :ref:`nl_msg_type` for more details. + +There are 3 usual types of message exchanges on a Netlink socket: + + - performing a single action (``do``); + - dumping information (``dump``); + - getting asynchronous notifications (``multicast``). + +Classic Netlink is very flexible and presumably allows other types +of exchanges to happen, but in practice those are the three that get +used. + +Asynchronous notifications are sent by the kernel and received by +the user sockets which subscribed to them. ``do`` and ``dump`` requests +are initiated by the user. :c:member:`nlmsghdr.nlmsg_flags` should +be set as follows: + + - for ``do``: ``NLM_F_REQUEST | NLM_F_ACK`` + - for ``dump``: ``NLM_F_REQUEST | NLM_F_ACK | NLM_F_DUMP`` + +:c:member:`nlmsghdr.nlmsg_seq` should be a set to a monotonically +increasing value. The value gets echoed back in responses and doesn't +matter in practice, but setting it to an increasing value for each +message sent is considered good hygiene. The purpose of the field is +matching responses to requests. Asynchronous notifications will have +:c:member:`nlmsghdr.nlmsg_seq` of ``0``. + +:c:member:`nlmsghdr.nlmsg_pid` is the Netlink equivalent of an address. +This field can be set to ``0`` when talking to the kernel. +See :ref:`nlmsg_pid` for the (uncommon) uses of the field. + +The expected use for :c:member:`genlmsghdr.version` was to allow +versioning of the APIs provided by the subsystems. No subsystem to +date made significant use of this field, so setting it to ``1`` seems +like a safe bet. + +.. _nl_msg_type: + +Netlink message types +--------------------- + +As previously mentioned :c:member:`nlmsghdr.nlmsg_type` carries +protocol specific values but the first 16 identifiers are reserved +(first subsystem specific message type should be equal to +``NLMSG_MIN_TYPE`` which is ``0x10``). + +There are only 4 Netlink control messages defined: + + - ``NLMSG_NOOP`` - ignore the message, not used in practice; + - ``NLMSG_ERROR`` - carries the return code of an operation; + - ``NLMSG_DONE`` - marks the end of a dump; + - ``NLMSG_OVERRUN`` - socket buffer has overflown, not used to date. + +``NLMSG_ERROR`` and ``NLMSG_DONE`` are of practical importance. +They carry return codes for operations. Note that unless +the ``NLM_F_ACK`` flag is set on the request Netlink will not respond +with ``NLMSG_ERROR`` if there is no error. To avoid having to special-case +this quirk it is recommended to always set ``NLM_F_ACK``. + +The format of ``NLMSG_ERROR`` is described by struct nlmsgerr:: + + ---------------------------------------------- + | struct nlmsghdr - response header | + ---------------------------------------------- + | int error | + ---------------------------------------------- + | struct nlmsghdr - original request header | + ---------------------------------------------- + | ** optionally (1) payload of the request | + ---------------------------------------------- + | ** optionally (2) extended ACK | + ---------------------------------------------- + +There are two instances of struct nlmsghdr here, first of the response +and second of the request. ``NLMSG_ERROR`` carries the information about +the request which led to the error. This could be useful when trying +to match requests to responses or re-parse the request to dump it into +logs. + +The payload of the request is not echoed in messages reporting success +(``error == 0``) or if ``NETLINK_CAP_ACK`` setsockopt() was set. +The latter is common +and perhaps recommended as having to read a copy of every request back +from the kernel is rather wasteful. The absence of request payload +is indicated by ``NLM_F_CAPPED`` in :c:member:`nlmsghdr.nlmsg_flags`. + +The second optional element of ``NLMSG_ERROR`` are the extended ACK +attributes. See :ref:`ext_ack` for more details. The presence +of extended ACK is indicated by ``NLM_F_ACK_TLVS`` in +:c:member:`nlmsghdr.nlmsg_flags`. + +``NLMSG_DONE`` is simpler, the request is never echoed but the extended +ACK attributes may be present:: + + ---------------------------------------------- + | struct nlmsghdr - response header | + ---------------------------------------------- + | int error | + ---------------------------------------------- + | ** optionally extended ACK | + ---------------------------------------------- + +.. _res_fam: + +Resolving the Family ID +----------------------- + +This section explains how to find the Family ID of a subsystem. +It also serves as an example of Generic Netlink communication. + +Generic Netlink is itself a subsystem exposed via the Generic Netlink API. +To avoid a circular dependency Generic Netlink has a statically allocated +Family ID (``GENL_ID_CTRL`` which is equal to ``NLMSG_MIN_TYPE``). +The Generic Netlink family implements a command used to find out information +about other families (``CTRL_CMD_GETFAMILY``). + +To get information about the Generic Netlink family named for example +``"test1"`` we need to send a message on the previously opened Generic Netlink +socket. The message should target the Generic Netlink Family (1), be a +``do`` (2) call to ``CTRL_CMD_GETFAMILY`` (3). A ``dump`` version of this +call would make the kernel respond with information about *all* the families +it knows about. Last but not least the name of the family in question has +to be specified (4) as an attribute with the appropriate type:: + + struct nlmsghdr: + __u32 nlmsg_len: 32 + __u16 nlmsg_type: GENL_ID_CTRL // (1) + __u16 nlmsg_flags: NLM_F_REQUEST | NLM_F_ACK // (2) + __u32 nlmsg_seq: 1 + __u32 nlmsg_pid: 0 + + struct genlmsghdr: + __u8 cmd: CTRL_CMD_GETFAMILY // (3) + __u8 version: 2 /* or 1, doesn't matter */ + __u16 reserved: 0 + + struct nlattr: // (4) + __u16 nla_len: 10 + __u16 nla_type: CTRL_ATTR_FAMILY_NAME + char data: test1\0 + + (padding:) + char data: \0\0 + +The length fields in Netlink (:c:member:`nlmsghdr.nlmsg_len` +and :c:member:`nlattr.nla_len`) always *include* the header. +Attribute headers in netlink must be aligned to 4 bytes from the start +of the message, hence the extra ``\0\0`` after ``CTRL_ATTR_FAMILY_NAME``. +The attribute lengths *exclude* the padding. + +If the family is found kernel will reply with two messages, the response +with all the information about the family:: + + /* Message #1 - reply */ + struct nlmsghdr: + __u32 nlmsg_len: 136 + __u16 nlmsg_type: GENL_ID_CTRL + __u16 nlmsg_flags: 0 + __u32 nlmsg_seq: 1 /* echoed from our request */ + __u32 nlmsg_pid: 5831 /* The PID of our user space process */ + + struct genlmsghdr: + __u8 cmd: CTRL_CMD_GETFAMILY + __u8 version: 2 + __u16 reserved: 0 + + struct nlattr: + __u16 nla_len: 10 + __u16 nla_type: CTRL_ATTR_FAMILY_NAME + char data: test1\0 + + (padding:) + data: \0\0 + + struct nlattr: + __u16 nla_len: 6 + __u16 nla_type: CTRL_ATTR_FAMILY_ID + __u16: 123 /* The Family ID we are after */ + + (padding:) + char data: \0\0 + + struct nlattr: + __u16 nla_len: 9 + __u16 nla_type: CTRL_ATTR_FAMILY_VERSION + __u16: 1 + + /* ... etc, more attributes will follow. */ + +And the error code (success) since ``NLM_F_ACK`` had been set on the request:: + + /* Message #2 - the ACK */ + struct nlmsghdr: + __u32 nlmsg_len: 36 + __u16 nlmsg_type: NLMSG_ERROR + __u16 nlmsg_flags: NLM_F_CAPPED /* There won't be a payload */ + __u32 nlmsg_seq: 1 /* echoed from our request */ + __u32 nlmsg_pid: 5831 /* The PID of our user space process */ + + int error: 0 + + struct nlmsghdr: /* Copy of the request header as we sent it */ + __u32 nlmsg_len: 32 + __u16 nlmsg_type: GENL_ID_CTRL + __u16 nlmsg_flags: NLM_F_REQUEST | NLM_F_ACK + __u32 nlmsg_seq: 1 + __u32 nlmsg_pid: 0 + +The order of attributes (struct nlattr) is not guaranteed so the user +has to walk the attributes and parse them. + +Note that Generic Netlink sockets are not associated or bound to a single +family. A socket can be used to exchange messages with many different +families, selecting the recipient family on message-by-message basis using +the :c:member:`nlmsghdr.nlmsg_type` field. + +.. _ext_ack: + +Extended ACK +------------ + +Extended ACK controls reporting of additional error/warning TLVs +in ``NLMSG_ERROR`` and ``NLMSG_DONE`` messages. To maintain backward +compatibility this feature has to be explicitly enabled by setting +the ``NETLINK_EXT_ACK`` setsockopt() to ``1``. + +Types of extended ack attributes are defined in enum nlmsgerr_attrs. +The most commonly used attributes are ``NLMSGERR_ATTR_MSG``, +``NLMSGERR_ATTR_OFFS`` and ``NLMSGERR_ATTR_MISS_*``. + +``NLMSGERR_ATTR_MSG`` carries a message in English describing +the encountered problem. These messages are far more detailed +than what can be expressed thru standard UNIX error codes. + +``NLMSGERR_ATTR_OFFS`` points to the attribute which caused the problem. + +``NLMSGERR_ATTR_MISS_TYPE`` and ``NLMSGERR_ATTR_MISS_NEST`` +inform about a missing attribute. + +Extended ACKs can be reported on errors as well as in case of success. +The latter should be treated as a warning. + +Extended ACKs greatly improve the usability of Netlink and should +always be enabled, appropriately parsed and reported to the user. + +Advanced topics +=============== + +Dump consistency +---------------- + +Some of the data structures kernel uses for storing objects make +it hard to provide an atomic snapshot of all the objects in a dump +(without impacting the fast-paths updating them). + +Kernel may set the ``NLM_F_DUMP_INTR`` flag on any message in a dump +(including the ``NLMSG_DONE`` message) if the dump was interrupted and +may be inconsistent (e.g. missing objects). User space should retry +the dump if it sees the flag set. + +Introspection +------------- + +The basic introspection abilities are enabled by access to the Family +object as reported in :ref:`res_fam`. User can query information about +the Generic Netlink family, including which operations are supported +by the kernel and what attributes the kernel understands. +Family information includes the highest ID of an attribute kernel can parse, +a separate command (``CTRL_CMD_GETPOLICY``) provides detailed information +about supported attributes, including ranges of values the kernel accepts. + +Querying family information is useful in cases when user space needs +to make sure that the kernel has support for a feature before issuing +a request. + +.. _nlmsg_pid: + +nlmsg_pid +--------- + +:c:member:`nlmsghdr.nlmsg_pid` is the Netlink equivalent of an address. +It is referred to as Port ID, sometimes Process ID because for historical +reasons if the application does not select (bind() to) an explicit Port ID +kernel will automatically assign it the ID equal to its Process ID +(as reported by the getpid() system call). + +Similarly to the bind() semantics of the TCP/IP network protocols the value +of zero means "assign automatically", hence it is common for applications +to leave the :c:member:`nlmsghdr.nlmsg_pid` field initialized to ``0``. + +The field is still used today in rare cases when kernel needs to send +a unicast notification. User space application can use bind() to associate +its socket with a specific PID, it then communicates its PID to the kernel. +This way the kernel can reach the specific user space process. + +This sort of communication is utilized in UMH (User Mode Helper)-like +scenarios when kernel needs to trigger user space processing or ask user +space for a policy decision. + +Multicast notifications +----------------------- + +One of the strengths of Netlink is the ability to send event notifications +to user space. This is a unidirectional form of communication (kernel -> +user) and does not involve any control messages like ``NLMSG_ERROR`` or +``NLMSG_DONE``. + +For example the Generic Netlink family itself defines a set of multicast +notifications about registered families. When a new family is added the +sockets subscribed to the notifications will get the following message:: + + struct nlmsghdr: + __u32 nlmsg_len: 136 + __u16 nlmsg_type: GENL_ID_CTRL + __u16 nlmsg_flags: 0 + __u32 nlmsg_seq: 0 + __u32 nlmsg_pid: 0 + + struct genlmsghdr: + __u8 cmd: CTRL_CMD_NEWFAMILY + __u8 version: 2 + __u16 reserved: 0 + + struct nlattr: + __u16 nla_len: 10 + __u16 nla_type: CTRL_ATTR_FAMILY_NAME + char data: test1\0 + + (padding:) + data: \0\0 + + struct nlattr: + __u16 nla_len: 6 + __u16 nla_type: CTRL_ATTR_FAMILY_ID + __u16: 123 /* The Family ID we are after */ + + (padding:) + char data: \0\0 + + struct nlattr: + __u16 nla_len: 9 + __u16 nla_type: CTRL_ATTR_FAMILY_VERSION + __u16: 1 + + /* ... etc, more attributes will follow. */ + +The notification contains the same information as the response +to the ``CTRL_CMD_GETFAMILY`` request. + +The Netlink headers of the notification are mostly 0 and irrelevant. +The :c:member:`nlmsghdr.nlmsg_seq` may be either zero or a monotonically +increasing notification sequence number maintained by the family. + +To receive notifications the user socket must subscribe to the relevant +notification group. Much like the Family ID, the Group ID for a given +multicast group is dynamic and can be found inside the Family information. +The ``CTRL_ATTR_MCAST_GROUPS`` attribute contains nests with names +(``CTRL_ATTR_MCAST_GRP_NAME``) and IDs (``CTRL_ATTR_MCAST_GRP_ID``) of +the groups family. + +Once the Group ID is known a setsockopt() call adds the socket to the group: + +.. code-block:: c + + unsigned int group_id; + + /* .. find the group ID... */ + + setsockopt(fd, SOL_NETLINK, NETLINK_ADD_MEMBERSHIP, + &group_id, sizeof(group_id)); + +The socket will now receive notifications. + +It is recommended to use separate sockets for receiving notifications +and sending requests to the kernel. The asynchronous nature of notifications +means that they may get mixed in with the responses making the message +handling much harder. + +Buffer sizing +------------- + +Netlink sockets are datagram sockets rather than stream sockets, +meaning that each message must be received in its entirety by a single +recv()/recvmsg() system call. If the buffer provided by the user is too +short, the message will be truncated and the ``MSG_TRUNC`` flag set +in struct msghdr (struct msghdr is the second argument +of the recvmsg() system call, *not* a Netlink header). + +Upon truncation the remaining part of the message is discarded. + +Netlink expects that the user buffer will be at least 8kB or a page +size of the CPU architecture, whichever is bigger. Particular Netlink +families may, however, require a larger buffer. 32kB buffer is recommended +for most efficient handling of dumps (larger buffer fits more dumped +objects and therefore fewer recvmsg() calls are needed). + +Classic Netlink +=============== + +The main differences between Classic and Generic Netlink are the dynamic +allocation of subsystem identifiers and availability of introspection. +In theory the protocol does not differ significantly, however, in practice +Classic Netlink experimented with concepts which were abandoned in Generic +Netlink (really, they usually only found use in a small corner of a single +subsystem). This section is meant as an explainer of a few of such concepts, +with the explicit goal of giving the Generic Netlink +users the confidence to ignore them when reading the uAPI headers. + +Most of the concepts and examples here refer to the ``NETLINK_ROUTE`` family, +which covers much of the configuration of the Linux networking stack. +Real documentation of that family, deserves a chapter (or a book) of its own. + +Families +-------- + +Netlink refers to subsystems as families. This is a remnant of using +sockets and the concept of protocol families, which are part of message +demultiplexing in ``NETLINK_ROUTE``. + +Sadly every layer of encapsulation likes to refer to whatever it's carrying +as "families" making the term very confusing: + + 1. AF_NETLINK is a bona fide socket protocol family + 2. AF_NETLINK's documentation refers to what comes after its own + header (struct nlmsghdr) in a message as a "Family Header" + 3. Generic Netlink is a family for AF_NETLINK (struct genlmsghdr follows + struct nlmsghdr), yet it also calls its users "Families". + +Note that the Generic Netlink Family IDs are in a different "ID space" +and overlap with Classic Netlink protocol numbers (e.g. ``NETLINK_CRYPTO`` +has the Classic Netlink protocol ID of 21 which Generic Netlink will +happily allocate to one of its families as well). + +Strict checking +--------------- + +The ``NETLINK_GET_STRICT_CHK`` socket option enables strict input checking +in ``NETLINK_ROUTE``. It was needed because historically kernel did not +validate the fields of structures it didn't process. This made it impossible +to start using those fields later without risking regressions in applications +which initialized them incorrectly or not at all. + +``NETLINK_GET_STRICT_CHK`` declares that the application is initializing +all fields correctly. It also opts into validating that message does not +contain trailing data and requests that kernel rejects attributes with +type higher than largest attribute type known to the kernel. + +``NETLINK_GET_STRICT_CHK`` is not used outside of ``NETLINK_ROUTE``. + +Unknown attributes +------------------ + +Historically Netlink ignored all unknown attributes. The thinking was that +it would free the application from having to probe what kernel supports. +The application could make a request to change the state and check which +parts of the request "stuck". + +This is no longer the case for new Generic Netlink families and those opting +in to strict checking. See enum netlink_validation for validation types +performed. + +Fixed metadata and structures +----------------------------- + +Classic Netlink made liberal use of fixed-format structures within +the messages. Messages would commonly have a structure with +a considerable number of fields after struct nlmsghdr. It was also +common to put structures with multiple members inside attributes, +without breaking each member into an attribute of its own. + +This has caused problems with validation and extensibility and +therefore using binary structures is actively discouraged for new +attributes. + +Request types +------------- + +``NETLINK_ROUTE`` categorized requests into 4 types ``NEW``, ``DEL``, ``GET``, +and ``SET``. Each object can handle all or some of those requests +(objects being netdevs, routes, addresses, qdiscs etc.) Request type +is defined by the 2 lowest bits of the message type, so commands for +new objects would always be allocated with a stride of 4. + +Each object would also have it's own fixed metadata shared by all request +types (e.g. struct ifinfomsg for netdev requests, struct ifaddrmsg for address +requests, struct tcmsg for qdisc requests). + +Even though other protocols and Generic Netlink commands often use +the same verbs in their message names (``GET``, ``SET``) the concept +of request types did not find wider adoption. + +Notification echo +----------------- + +``NLM_F_ECHO`` requests for notifications resulting from the request +to be queued onto the requesting socket. This is useful to discover +the impact of the request. + +Note that this feature is not universally implemented. + +Other request-type-specific flags +--------------------------------- + +Classic Netlink defined various flags for its ``GET``, ``NEW`` +and ``DEL`` requests in the upper byte of nlmsg_flags in struct nlmsghdr. +Since request types have not been generalized the request type specific +flags are rarely used (and considered deprecated for new families). + +For ``GET`` - ``NLM_F_ROOT`` and ``NLM_F_MATCH`` are combined into +``NLM_F_DUMP``, and not used separately. ``NLM_F_ATOMIC`` is never used. + +For ``DEL`` - ``NLM_F_NONREC`` is only used by nftables and ``NLM_F_BULK`` +only by FDB some operations. + +The flags for ``NEW`` are used most commonly in classic Netlink. Unfortunately, +the meaning is not crystal clear. The following description is based on the +best guess of the intention of the authors, and in practice all families +stray from it in one way or another. ``NLM_F_REPLACE`` asks to replace +an existing object, if no matching object exists the operation should fail. +``NLM_F_EXCL`` has the opposite semantics and only succeeds if object already +existed. +``NLM_F_CREATE`` asks for the object to be created if it does not +exist, it can be combined with ``NLM_F_REPLACE`` and ``NLM_F_EXCL``. + +A comment in the main Netlink uAPI header states:: + + 4.4BSD ADD NLM_F_CREATE|NLM_F_EXCL + 4.4BSD CHANGE NLM_F_REPLACE + + True CHANGE NLM_F_CREATE|NLM_F_REPLACE + Append NLM_F_CREATE + Check NLM_F_EXCL + +which seems to indicate that those flags predate request types. +``NLM_F_REPLACE`` without ``NLM_F_CREATE`` was initially used instead +of ``SET`` commands. +``NLM_F_EXCL`` without ``NLM_F_CREATE`` was used to check if object exists +without creating it, presumably predating ``GET`` commands. + +``NLM_F_APPEND`` indicates that if one key can have multiple objects associated +with it (e.g. multiple next-hop objects for a route) the new object should be +added to the list rather than replacing the entire list. + +uAPI reference +============== + +.. kernel-doc:: include/uapi/linux/netlink.h diff --git a/Documentation/virt/kvm/x86/mmu.rst b/Documentation/virt/kvm/x86/mmu.rst index 8739120f4300..8364afa228ec 100644 --- a/Documentation/virt/kvm/x86/mmu.rst +++ b/Documentation/virt/kvm/x86/mmu.rst @@ -377,7 +377,7 @@ Emulating cr0.wp ================ If tdp is not enabled, the host must keep cr0.wp=1 so page write protection -works for the guest kernel, not guest guest userspace. When the guest +works for the guest kernel, not guest userspace. When the guest cr0.wp=1, this does not present a problem. However when the guest cr0.wp=0, we cannot map the permissions for gpte.u=1, gpte.w=0 to any spte (the semantics require allowing any guest kernel access plus user read access). diff --git a/Documentation/w1/masters/ds2490.rst b/Documentation/w1/masters/ds2490.rst index 7e5b50f9c0f5..842e7ae80424 100644 --- a/Documentation/w1/masters/ds2490.rst +++ b/Documentation/w1/masters/ds2490.rst @@ -52,7 +52,7 @@ Notes and limitations. clear the entire bulk in buffer. It would be possible to read the maximum buffer size to not run into this error condition, only extra bytes in the buffer is a logic error in the driver. The code should - should match reads and writes as well as data sizes. Reads and + match reads and writes as well as data sizes. Reads and writes are serialized and the status verifies that the chip is idle (and data is available) before the read is executed, so it should not happen. diff --git a/Documentation/w1/w1-generic.rst b/Documentation/w1/w1-generic.rst index da4e8b4e9b01..99255b6d0e53 100644 --- a/Documentation/w1/w1-generic.rst +++ b/Documentation/w1/w1-generic.rst @@ -113,7 +113,7 @@ generally only make sense when searching is disabled, as a search will redetect manually removed devices that are present and timeout manually added devices that aren't on the bus. -Bus searches occur at an interval, specified as a summ of timeout and +Bus searches occur at an interval, specified as a sum of timeout and timeout_us module parameters (either of which may be 0) for as long as w1_master_search remains greater than 0 or is -1. Each search attempt decrements w1_master_search by 1 (down to 0) and increments diff --git a/Documentation/x86/entry_64.rst b/Documentation/x86/entry_64.rst index e433e08f7018..0afdce3c06f4 100644 --- a/Documentation/x86/entry_64.rst +++ b/Documentation/x86/entry_64.rst @@ -33,8 +33,8 @@ Some of these entries are: - interrupt: An array of entries. Every IDT vector that doesn't explicitly point somewhere else gets set to the corresponding value in interrupts. These point to a whole array of - magically-generated functions that make their way to do_IRQ with - the interrupt number as a parameter. + magically-generated functions that make their way to common_interrupt() + with the interrupt number as a parameter. - APIC interrupts: Various special-purpose interrupts for things like TLB shootdown. diff --git a/Documentation/x86/microcode.rst b/Documentation/x86/microcode.rst index a320d37982ed..b627c6f36bcf 100644 --- a/Documentation/x86/microcode.rst +++ b/Documentation/x86/microcode.rst @@ -6,6 +6,7 @@ The Linux Microcode Loader :Authors: - Fenghua Yu <fenghua.yu@intel.com> - Borislav Petkov <bp@suse.de> + - Ashok Raj <ashok.raj@intel.com> The kernel has a x86 microcode loading facility which is supposed to provide microcode loading methods in the OS. Potential use cases are @@ -92,15 +93,8 @@ vendor's site. Late loading ============ -There are two legacy user space interfaces to load microcode, either through -/dev/cpu/microcode or through /sys/devices/system/cpu/microcode/reload file -in sysfs. - -The /dev/cpu/microcode method is deprecated because it needs a special -userspace tool for that. - -The easier method is simply installing the microcode packages your distro -supplies and running:: +You simply install the microcode packages your distro supplies and +run:: # echo 1 > /sys/devices/system/cpu/microcode/reload @@ -110,6 +104,110 @@ The loading mechanism looks for microcode blobs in /lib/firmware/{intel-ucode,amd-ucode}. The default distro installation packages already put them there. +Since kernel 5.19, late loading is not enabled by default. + +The /dev/cpu/microcode method has been removed in 5.19. + +Why is late loading dangerous? +============================== + +Synchronizing all CPUs +---------------------- + +The microcode engine which receives the microcode update is shared +between the two logical threads in a SMT system. Therefore, when +the update is executed on one SMT thread of the core, the sibling +"automatically" gets the update. + +Since the microcode can "simulate" MSRs too, while the microcode update +is in progress, those simulated MSRs transiently cease to exist. This +can result in unpredictable results if the SMT sibling thread happens to +be in the middle of an access to such an MSR. The usual observation is +that such MSR accesses cause #GPs to be raised to signal that former are +not present. + +The disappearing MSRs are just one common issue which is being observed. +Any other instruction that's being patched and gets concurrently +executed by the other SMT sibling, can also result in similar, +unpredictable behavior. + +To eliminate this case, a stop_machine()-based CPU synchronization was +introduced as a way to guarantee that all logical CPUs will not execute +any code but just wait in a spin loop, polling an atomic variable. + +While this took care of device or external interrupts, IPIs including +LVT ones, such as CMCI etc, it cannot address other special interrupts +that can't be shut off. Those are Machine Check (#MC), System Management +(#SMI) and Non-Maskable interrupts (#NMI). + +Machine Checks +-------------- + +Machine Checks (#MC) are non-maskable. There are two kinds of MCEs. +Fatal un-recoverable MCEs and recoverable MCEs. While un-recoverable +errors are fatal, recoverable errors can also happen in kernel context +are also treated as fatal by the kernel. + +On certain Intel machines, MCEs are also broadcast to all threads in a +system. If one thread is in the middle of executing WRMSR, a MCE will be +taken at the end of the flow. Either way, they will wait for the thread +performing the wrmsr(0x79) to rendezvous in the MCE handler and shutdown +eventually if any of the threads in the system fail to check in to the +MCE rendezvous. + +To be paranoid and get predictable behavior, the OS can choose to set +MCG_STATUS.MCIP. Since MCEs can be at most one in a system, if an +MCE was signaled, the above condition will promote to a system reset +automatically. OS can turn off MCIP at the end of the update for that +core. + +System Management Interrupt +--------------------------- + +SMIs are also broadcast to all CPUs in the platform. Microcode update +requests exclusive access to the core before writing to MSR 0x79. So if +it does happen such that, one thread is in WRMSR flow, and the 2nd got +an SMI, that thread will be stopped in the first instruction in the SMI +handler. + +Since the secondary thread is stopped in the first instruction in SMI, +there is very little chance that it would be in the middle of executing +an instruction being patched. Plus OS has no way to stop SMIs from +happening. + +Non-Maskable Interrupts +----------------------- + +When thread0 of a core is doing the microcode update, if thread1 is +pulled into NMI, that can cause unpredictable behavior due to the +reasons above. + +OS can choose a variety of methods to avoid running into this situation. + + +Is the microcode suitable for late loading? +------------------------------------------- + +Late loading is done when the system is fully operational and running +real workloads. Late loading behavior depends on what the base patch on +the CPU is before upgrading to the new patch. + +This is true for Intel CPUs. + +Consider, for example, a CPU has patch level 1 and the update is to +patch level 3. + +Between patch1 and patch3, patch2 might have deprecated a software-visible +feature. + +This is unacceptable if software is even potentially using that feature. +For instance, say MSR_X is no longer available after an update, +accessing that MSR will cause a #GP fault. + +Basically there is no way to declare a new microcode update suitable +for late-loading. This is another one of the problems that caused late +loading to be not enabled by default. + Builtin microcode ================= |
