diff --git a/Documentation/ABI/testing/sysfs-class-firmware-attributes b/Documentation/ABI/testing/sysfs-class-firmware-attributes index 90fdf935aa5e..13e31c6a0e9c 100644 --- a/Documentation/ABI/testing/sysfs-class-firmware-attributes +++ b/Documentation/ABI/testing/sysfs-class-firmware-attributes @@ -161,6 +161,15 @@ Description: power-on: Representing a password required to use the system + system-mgmt: + Representing System Management password. + See Lenovo extensions section for details + HDD: + Representing HDD password + See Lenovo extensions section for details + NVMe: + Representing NVMe password + See Lenovo extensions section for details mechanism: The means of authentication. This attribute is mandatory. @@ -207,6 +216,13 @@ Description: On Lenovo systems the following additional settings are available: + role: system-mgmt This gives the same authority as the bios-admin password to control + security related features. The authorities allocated can be set via + the BIOS menu SMP Access Control Policy + + role: HDD & NVMe This password is used to unlock access to the drive at boot. Note see + 'level' and 'index' extensions below. + lenovo_encoding: The encoding method that is used. This can be either "ascii" or "scancode". Default is set to "ascii" @@ -216,6 +232,22 @@ Description: two char code (e.g. "us", "fr", "gr") and may vary per platform. Default is set to "us" + level: + Available for HDD and NVMe authentication to set 'user' or 'master' + privilege level. + If only the user password is configured then this should be used to + unlock the drive at boot. If both master and user passwords are set + then either can be used. If a master password is set a user password + is required. + This attribute defaults to 'user' level + + index: + Used with HDD and NVME authentication to set the drive index + that is being referenced (e.g hdd0, hdd1 etc) + This attribute defaults to device 0. + + + What: /sys/class/firmware-attributes/*/attributes/pending_reboot Date: February 2021 KernelVersion: 5.11 diff --git a/Documentation/ABI/testing/sysfs-class-power b/Documentation/ABI/testing/sysfs-class-power index f7904efc4cfa..fde21d900420 100644 --- a/Documentation/ABI/testing/sysfs-class-power +++ b/Documentation/ABI/testing/sysfs-class-power @@ -413,7 +413,7 @@ Description: "Over voltage", "Unspecified failure", "Cold", "Watchdog timer expire", "Safety timer expire", "Over current", "Calibration required", "Warm", - "Cool", "Hot" + "Cool", "Hot", "No battery" What: /sys/class/power_supply//precharge_current Date: June 2017 @@ -455,6 +455,20 @@ Description: "Unknown", "Charging", "Discharging", "Not charging", "Full" +What: /sys/class/power_supply//charge_behaviour +Date: November 2021 +Contact: linux-pm@vger.kernel.org +Description: + Represents the charging behaviour. + + Access: Read, Write + + Valid values: + ================ ==================================== + auto: Charge normally, respect thresholds + inhibit-charge: Do not charge while AC is attached + force-discharge: Force discharge while AC is attached + What: /sys/class/power_supply//technology Date: May 2007 Contact: linux-pm@vger.kernel.org diff --git a/Documentation/ABI/testing/sysfs-fs-erofs b/Documentation/ABI/testing/sysfs-fs-erofs new file mode 100644 index 000000000000..05482374a741 --- /dev/null +++ b/Documentation/ABI/testing/sysfs-fs-erofs @@ -0,0 +1,16 @@ +What: /sys/fs/erofs/features/ +Date: November 2021 +Contact: "Huang Jianan" +Description: Shows all enabled kernel features. + Supported features: + zero_padding, compr_cfgs, big_pcluster, chunked_file, + device_table, compr_head2, sb_chksum. + +What: /sys/fs/erofs//sync_decompress +Date: November 2021 +Contact: "Huang Jianan" +Description: Control strategy of sync decompression + - 0 (default, auto): enable for readpage, and enable for + readahead on atomic contexts only, + - 1 (force on): enable for readpage and readahead. + - 2 (force off): disable for all situations. diff --git a/Documentation/ABI/testing/sysfs-fs-ubifs b/Documentation/ABI/testing/sysfs-fs-ubifs new file mode 100644 index 000000000000..af5afda30220 --- /dev/null +++ b/Documentation/ABI/testing/sysfs-fs-ubifs @@ -0,0 +1,35 @@ +What: /sys/fs/ubifsX_Y/error_magic +Date: October 2021 +KernelVersion: 5.16 +Contact: linux-mtd@lists.infradead.org +Description: + Exposes magic errors: every node starts with a magic number. + + This counter keeps track of the number of accesses of nodes + with a corrupted magic number. + + The counter is reset to 0 with a remount. + +What: /sys/fs/ubifsX_Y/error_node +Date: October 2021 +KernelVersion: 5.16 +Contact: linux-mtd@lists.infradead.org +Description: + Exposes node errors. Every node embeds its type. + + This counter keeps track of the number of accesses of nodes + with a corrupted node type. + + The counter is reset to 0 with a remount. + +What: /sys/fs/ubifsX_Y/error_crc +Date: October 2021 +KernelVersion: 5.16 +Contact: linux-mtd@lists.infradead.org +Description: + Exposes crc errors: every node embeds a crc checksum. + + This counter keeps track of the number of accesses of nodes + with a bad crc checksum. + + The counter is reset to 0 with a remount. diff --git a/Documentation/Makefile b/Documentation/Makefile index c3feb657b654..9f4bd42cef18 100644 --- a/Documentation/Makefile +++ b/Documentation/Makefile @@ -19,6 +19,8 @@ endif SPHINXBUILD = sphinx-build SPHINXOPTS = SPHINXDIRS = . +DOCS_THEME = +DOCS_CSS = _SPHINXDIRS = $(sort $(patsubst $(srctree)/Documentation/%/index.rst,%,$(wildcard $(srctree)/Documentation/*/index.rst))) SPHINX_CONF = conf.py PAPER = @@ -84,7 +86,10 @@ quiet_cmd_sphinx = SPHINX $@ --> file://$(abspath $(BUILDDIR)/$3/$4) -D version=$(KERNELVERSION) -D release=$(KERNELRELEASE) \ $(ALLSPHINXOPTS) \ $(abspath $(srctree)/$(src)/$5) \ - $(abspath $(BUILDDIR)/$3/$4) + $(abspath $(BUILDDIR)/$3/$4) && \ + if [ "x$(DOCS_CSS)" != "x" ]; then \ + cp $(if $(patsubst /%,,$(DOCS_CSS)),$(abspath $(srctree)/$(DOCS_CSS)),$(DOCS_CSS)) $(BUILDDIR)/$3/_static/; \ + fi htmldocs: @$(srctree)/scripts/sphinx-pre-install --version-check @@ -154,4 +159,8 @@ dochelp: @echo ' make SPHINX_CONF={conf-file} [target] use *additional* sphinx-build' @echo ' configuration. This is e.g. useful to build with nit-picking config.' @echo + @echo ' make DOCS_THEME={sphinx-theme} selects a different Sphinx theme.' + @echo + @echo ' make DOCS_CSS={a .css file} adds a DOCS_CSS override file for html/epub output.' + @echo @echo ' Default location for the generated documents is Documentation/output' diff --git a/Documentation/admin-guide/gpio/gpio-sim.rst b/Documentation/admin-guide/gpio/gpio-sim.rst new file mode 100644 index 000000000000..d8a90c81b9ee --- /dev/null +++ b/Documentation/admin-guide/gpio/gpio-sim.rst @@ -0,0 +1,134 @@ +.. SPDX-License-Identifier: GPL-2.0-or-later + +Configfs GPIO Simulator +======================= + +The configfs GPIO Simulator (gpio-sim) provides a way to create simulated GPIO +chips for testing purposes. The lines exposed by these chips can be accessed +using the standard GPIO character device interface as well as manipulated +using sysfs attributes. + +Creating simulated chips +------------------------ + +The gpio-sim module registers a configfs subsystem called ``'gpio-sim'``. For +details of the configfs filesystem, please refer to the configfs documentation. + +The user can create a hierarchy of configfs groups and items as well as modify +values of exposed attributes. Once the chip is instantiated, this hierarchy +will be translated to appropriate device properties. The general structure is: + +**Group:** ``/config/gpio-sim`` + +This is the top directory of the gpio-sim configfs tree. + +**Group:** ``/config/gpio-sim/gpio-device`` + +**Attribute:** ``/config/gpio-sim/gpio-device/dev_name`` + +**Attribute:** ``/config/gpio-sim/gpio-device/live`` + +This is a directory representing a GPIO platform device. The ``'dev_name'`` +attribute is read-only and allows the user-space to read the platform device +name (e.g. ``'gpio-sim.0'``). The ``'live'`` attribute allows to trigger the +actual creation of the device once it's fully configured. The accepted values +are: ``'1'`` to enable the simulated device and ``'0'`` to disable and tear +it down. + +**Group:** ``/config/gpio-sim/gpio-device/gpio-bankX`` + +**Attribute:** ``/config/gpio-sim/gpio-device/gpio-bankX/chip_name`` + +**Attribute:** ``/config/gpio-sim/gpio-device/gpio-bankX/num_lines`` + +This group represents a bank of GPIOs under the top platform device. The +``'chip_name'`` attribute is read-only and allows the user-space to read the +device name of the bank device. The ``'num_lines'`` attribute allows to specify +the number of lines exposed by this bank. + +**Group:** ``/config/gpio-sim/gpio-device/gpio-bankX/lineY`` + +**Attribute:** ``/config/gpio-sim/gpio-device/gpio-bankX/lineY/name`` + +This group represents a single line at the offset Y. The 'name' attribute +allows to set the line name as represented by the 'gpio-line-names' property. + +**Item:** ``/config/gpio-sim/gpio-device/gpio-bankX/lineY/hog`` + +**Attribute:** ``/config/gpio-sim/gpio-device/gpio-bankX/lineY/hog/name`` + +**Attribute:** ``/config/gpio-sim/gpio-device/gpio-bankX/lineY/hog/direction`` + +This item makes the gpio-sim module hog the associated line. The ``'name'`` +attribute specifies the in-kernel consumer name to use. The ``'direction'`` +attribute specifies the hog direction and must be one of: ``'input'``, +``'output-high'`` and ``'output-low'``. + +Inside each bank directory, there's a set of attributes that can be used to +configure the new chip. Additionally the user can ``mkdir()`` subdirectories +inside the chip's directory that allow to pass additional configuration for +specific lines. The name of those subdirectories must take the form of: +``'line'`` (e.g. ``'line0'``, ``'line20'``, etc.) as the name will be +used by the module to assign the config to the specific line at given offset. + +Once the confiuration is complete, the ``'live'`` attribute must be set to 1 in +order to instantiate the chip. It can be set back to 0 to destroy the simulated +chip. The module will synchronously wait for the new simulated device to be +successfully probed and if this doesn't happen, writing to ``'live'`` will +result in an error. + +Simulated GPIO chips can also be defined in device-tree. The compatible string +must be: ``"gpio-simulator"``. Supported properties are: + + ``"gpio-sim,label"`` - chip label + +Other standard GPIO properties (like ``"gpio-line-names"``, ``"ngpios"`` or +``"gpio-hog"``) are also supported. Please refer to the GPIO documentation for +details. + +An example device-tree code defining a GPIO simulator: + +.. code-block :: none + + gpio-sim { + compatible = "gpio-simulator"; + + bank0 { + gpio-controller; + #gpio-cells = <2>; + ngpios = <16>; + gpio-sim,label = "dt-bank0"; + gpio-line-names = "", "sim-foo", "", "sim-bar"; + }; + + bank1 { + gpio-controller; + #gpio-cells = <2>; + ngpios = <8>; + gpio-sim,label = "dt-bank1"; + + line3 { + gpio-hog; + gpios = <3 0>; + output-high; + line-name = "sim-hog-from-dt"; + }; + }; + }; + +Manipulating simulated lines +---------------------------- + +Each simulated GPIO chip creates a separate sysfs group under its device +directory for each exposed line +(e.g. ``/sys/devices/platform/gpio-sim.X/gpiochipY/``). The name of each group +is of the form: ``'sim_gpioX'`` where X is the offset of the line. Inside each +group there are two attibutes: + + ``pull`` - allows to read and set the current simulated pull setting for + every line, when writing the value must be one of: ``'pull-up'``, + ``'pull-down'`` + + ``value`` - allows to read the current value of the line which may be + different from the pull if the line is being driven from + user-space diff --git a/Documentation/admin-guide/hw-vuln/spectre.rst b/Documentation/admin-guide/hw-vuln/spectre.rst index ab7d402c1677..a2b22d5640ec 100644 --- a/Documentation/admin-guide/hw-vuln/spectre.rst +++ b/Documentation/admin-guide/hw-vuln/spectre.rst @@ -468,7 +468,7 @@ Spectre variant 2 before invoking any firmware code to prevent Spectre variant 2 exploits using the firmware. - Using kernel address space randomization (CONFIG_RANDOMIZE_SLAB=y + Using kernel address space randomization (CONFIG_RANDOMIZE_BASE=y and CONFIG_SLAB_FREELIST_RANDOM=y in the kernel configuration) makes attacks on the kernel generally more difficult. diff --git a/Documentation/arc/arc.rst b/Documentation/arc/arc.rst new file mode 100644 index 000000000000..6c4d978f3f4e --- /dev/null +++ b/Documentation/arc/arc.rst @@ -0,0 +1,85 @@ +.. SPDX-License-Identifier: GPL-2.0 + +Linux kernel for ARC processors +******************************* + +Other sources of information +############################ + +Below are some resources where more information can be found on +ARC processors and relevant open source projects. + +- ``_ - Community portal for open source on ARC. + Good place to start to find relevant FOSS projects, toolchain releases, + news items and more. + +- ``_ - + Home for all development activities regarding open source projects for + ARC processors. Some of the projects are forks of various upstream projects, + where "work in progress" is hosted prior to submission to upstream projects. + Other projects are developed by Synopsys and made available to community + as open source for use on ARC Processors. + +- `Official Synopsys ARC Processors website + `_ - + location, with access to some IP documentation (`Programmer's Reference + Manual, AKA PRM for ARC HS processors + `_) + and free versions of some commercial tools (`Free nSIM + `_ and + `MetaWare Light Edition `_). + Please note though, registration is required to access both the documentation and + the tools. + +Important note on ARC processors configurability +################################################ + +ARC processors are highly configurable and several configurable options +are supported in Linux. Some options are transparent to software +(i.e cache geometries, some can be detected at runtime and configured +and used accordingly, while some need to be explicitly selected or configured +in the kernel's configuration utility (AKA "make menuconfig"). + +However not all configurable options are supported when an ARC processor +is to run Linux. SoC design teams should refer to "Appendix E: +Configuration for ARC Linux" in the ARC HS Databook for configurability +guidelines. + +Following these guidelines and selecting valid configuration options +up front is critical to help prevent any unwanted issues during +SoC bringup and software development in general. + +Building the Linux kernel for ARC processors +############################################ + +The process of kernel building for ARC processors is the same as for any other +architecture and could be done in 2 ways: + +- Cross-compilation: process of compiling for ARC targets on a development + host with a different processor architecture (generally x86_64/amd64). +- Native compilation: process of compiling for ARC on a ARC platform + (hardware board or a simulator like QEMU) with complete development environment + (GNU toolchain, dtc, make etc) installed on the platform. + +In both cases, up-to-date GNU toolchain for ARC for the host is needed. +Synopsys offers prebuilt toolchain releases which can be used for this purpose, +available from: + +- Synopsys GNU toolchain releases: + ``_ + +- Linux kernel compilers collection: + ``_ + +- Bootlin's toolchain collection: ``_ + +Once the toolchain is installed in the system, make sure its "bin" folder +is added in your ``PATH`` environment variable. Then set ``ARCH=arc`` & +``CROSS_COMPILE=arc-linux`` (or whatever matches installed ARC toolchain prefix) +and then as usual ``make defconfig && make``. + +This will produce "vmlinux" file in the root of the kernel source tree +usable for loading on the target system via JTAG. +If you need to get an image usable with U-Boot bootloader, +type ``make uImage`` and ``uImage`` will be produced in ``arch/arc/boot`` +folder. diff --git a/Documentation/arc/features.rst b/Documentation/arc/features.rst new file mode 100644 index 000000000000..b793583d688a --- /dev/null +++ b/Documentation/arc/features.rst @@ -0,0 +1,3 @@ +.. SPDX-License-Identifier: GPL-2.0 + +.. kernel-feat:: $srctree/Documentation/features arc diff --git a/Documentation/arc/index.rst b/Documentation/arc/index.rst new file mode 100644 index 000000000000..7b098d4a5e3e --- /dev/null +++ b/Documentation/arc/index.rst @@ -0,0 +1,17 @@ +=================== +ARC architecture +=================== + +.. toctree:: + :maxdepth: 1 + + arc + + features + +.. only:: subproject and html + + Indices + ======= + + * :ref:`genindex` diff --git a/Documentation/arch.rst b/Documentation/arch.rst index f10bd32a5972..14bcd8294b93 100644 --- a/Documentation/arch.rst +++ b/Documentation/arch.rst @@ -9,6 +9,7 @@ implementation. .. toctree:: :maxdepth: 2 + arc/index arm/index arm64/index ia64/index diff --git a/Documentation/conf.py b/Documentation/conf.py index 76e5eb5cb62b..f07f2e9b9f2c 100644 --- a/Documentation/conf.py +++ b/Documentation/conf.py @@ -208,16 +208,86 @@ highlight_language = 'none' # The theme to use for HTML and HTML Help pages. See the documentation for # a list of builtin themes. -# The Read the Docs theme is available from -# - https://github.com/snide/sphinx_rtd_theme -# - https://pypi.python.org/pypi/sphinx_rtd_theme -# - python-sphinx-rtd-theme package (on Debian) -try: - import sphinx_rtd_theme - html_theme = 'sphinx_rtd_theme' - html_theme_path = [sphinx_rtd_theme.get_html_theme_path()] -except ImportError: - sys.stderr.write('Warning: The Sphinx \'sphinx_rtd_theme\' HTML theme was not found. Make sure you have the theme installed to produce pretty HTML output. Falling back to the default theme.\n') +# Default theme +html_theme = 'sphinx_rtd_theme' +html_css_files = [] + +if "DOCS_THEME" in os.environ: + html_theme = os.environ["DOCS_THEME"] + +if html_theme == 'sphinx_rtd_theme' or html_theme == 'sphinx_rtd_dark_mode': + # Read the Docs theme + try: + import sphinx_rtd_theme + html_theme_path = [sphinx_rtd_theme.get_html_theme_path()] + + # Add any paths that contain custom static files (such as style sheets) here, + # relative to this directory. They are copied after the builtin static files, + # so a file named "default.css" will overwrite the builtin "default.css". + html_css_files = [ + 'theme_overrides.css', + ] + + # Read the Docs dark mode override theme + if html_theme == 'sphinx_rtd_dark_mode': + try: + import sphinx_rtd_dark_mode + extensions.append('sphinx_rtd_dark_mode') + except ImportError: + html_theme == 'sphinx_rtd_theme' + + if html_theme == 'sphinx_rtd_theme': + # Add color-specific RTD normal mode + html_css_files.append('theme_rtd_colors.css') + + except ImportError: + html_theme = 'classic' + +if "DOCS_CSS" in os.environ: + css = os.environ["DOCS_CSS"].split(" ") + + for l in css: + html_css_files.append(l) + +if major <= 1 and minor < 8: + html_context = { + 'css_files': [], + } + + for l in html_css_files: + html_context['css_files'].append('_static/' + l) + +if html_theme == 'classic': + html_theme_options = { + 'rightsidebar': False, + 'stickysidebar': True, + 'collapsiblesidebar': True, + 'externalrefs': False, + + 'footerbgcolor': "white", + 'footertextcolor': "white", + 'sidebarbgcolor': "white", + 'sidebarbtncolor': "black", + 'sidebartextcolor': "black", + 'sidebarlinkcolor': "#686bff", + 'relbarbgcolor': "#133f52", + 'relbartextcolor': "white", + 'relbarlinkcolor': "white", + 'bgcolor': "white", + 'textcolor': "black", + 'headbgcolor': "#f2f2f2", + 'headtextcolor': "#20435c", + 'headlinkcolor': "#c60f0f", + 'linkcolor': "#355f7c", + 'visitedlinkcolor': "#355f7c", + 'codebgcolor': "#3f3f3f", + 'codetextcolor': "white", + + 'bodyfont': "serif", + 'headfont': "sans-serif", + } + +sys.stderr.write("Using %s theme\n" % html_theme) # Theme options are theme-specific and customize the look and feel of a theme # further. For a list of options available for each theme, see the @@ -246,20 +316,8 @@ except ImportError: # Add any paths that contain custom static files (such as style sheets) here, # relative to this directory. They are copied after the builtin static files, # so a file named "default.css" will overwrite the builtin "default.css". - html_static_path = ['sphinx-static'] -html_css_files = [ - 'theme_overrides.css', -] - -if major <= 1 and minor < 8: - html_context = { - 'css_files': [ - '_static/theme_overrides.css', - ], - } - # Add any extra paths that contain custom files (such as robots.txt or # .htaccess) here, relative to this directory. These files are copied # directly to the root of the documentation. diff --git a/Documentation/dev-tools/index.rst b/Documentation/dev-tools/index.rst index 010a2af1e7d9..4621eac290f4 100644 --- a/Documentation/dev-tools/index.rst +++ b/Documentation/dev-tools/index.rst @@ -32,6 +32,7 @@ Documentation/dev-tools/testing-overview.rst kgdb kselftest kunit/index + ktap .. only:: subproject and html diff --git a/Documentation/dev-tools/kcsan.rst b/Documentation/dev-tools/kcsan.rst index 7db43c7c09b8..3ae866dcc924 100644 --- a/Documentation/dev-tools/kcsan.rst +++ b/Documentation/dev-tools/kcsan.rst @@ -204,17 +204,17 @@ Ultimately this allows to determine the possible executions of concurrent code, and if that code is free from data races. KCSAN is aware of *marked atomic operations* (``READ_ONCE``, ``WRITE_ONCE``, -``atomic_*``, etc.), but is oblivious of any ordering guarantees and simply -assumes that memory barriers are placed correctly. In other words, KCSAN -assumes that as long as a plain access is not observed to race with another -conflicting access, memory operations are correctly ordered. +``atomic_*``, etc.), and a subset of ordering guarantees implied by memory +barriers. With ``CONFIG_KCSAN_WEAK_MEMORY=y``, KCSAN models load or store +buffering, and can detect missing ``smp_mb()``, ``smp_wmb()``, ``smp_rmb()``, +``smp_store_release()``, and all ``atomic_*`` operations with equivalent +implied barriers. -This means that KCSAN will not report *potential* data races due to missing -memory ordering. Developers should therefore carefully consider the required -memory ordering requirements that remain unchecked. If, however, missing -memory ordering (that is observable with a particular compiler and -architecture) leads to an observable data race (e.g. entering a critical -section erroneously), KCSAN would report the resulting data race. +Note, KCSAN will not report all data races due to missing memory ordering, +specifically where a memory barrier would be required to prohibit subsequent +memory operation from reordering before the barrier. Developers should +therefore carefully consider the required memory ordering requirements that +remain unchecked. Race Detection Beyond Data Races -------------------------------- @@ -268,6 +268,56 @@ marked operations, if all accesses to a variable that is accessed concurrently are properly marked, KCSAN will never trigger a watchpoint and therefore never report the accesses. +Modeling Weak Memory +~~~~~~~~~~~~~~~~~~~~ + +KCSAN's approach to detecting data races due to missing memory barriers is +based on modeling access reordering (with ``CONFIG_KCSAN_WEAK_MEMORY=y``). +Each plain memory access for which a watchpoint is set up, is also selected for +simulated reordering within the scope of its function (at most 1 in-flight +access). + +Once an access has been selected for reordering, it is checked along every +other access until the end of the function scope. If an appropriate memory +barrier is encountered, the access will no longer be considered for simulated +reordering. + +When the result of a memory operation should be ordered by a barrier, KCSAN can +then detect data races where the conflict only occurs as a result of a missing +barrier. Consider the example:: + + int x, flag; + void T1(void) + { + x = 1; // data race! + WRITE_ONCE(flag, 1); // correct: smp_store_release(&flag, 1) + } + void T2(void) + { + while (!READ_ONCE(flag)); // correct: smp_load_acquire(&flag) + ... = x; // data race! + } + +When weak memory modeling is enabled, KCSAN can consider ``x`` in ``T1`` for +simulated reordering. After the write of ``flag``, ``x`` is again checked for +concurrent accesses: because ``T2`` is able to proceed after the write of +``flag``, a data race is detected. With the correct barriers in place, ``x`` +would not be considered for reordering after the proper release of ``flag``, +and no data race would be detected. + +Deliberate trade-offs in complexity but also practical limitations mean only a +subset of data races due to missing memory barriers can be detected. With +currently available compiler support, the implementation is limited to modeling +the effects of "buffering" (delaying accesses), since the runtime cannot +"prefetch" accesses. Also recall that watchpoints are only set up for plain +accesses, and the only access type for which KCSAN simulates reordering. This +means reordering of marked accesses is not modeled. + +A consequence of the above is that acquire operations do not require barrier +instrumentation (no prefetching). Furthermore, marked accesses introducing +address or control dependencies do not require special handling (the marked +access cannot be reordered, later dependent accesses cannot be prefetched). + Key Properties ~~~~~~~~~~~~~~ @@ -290,8 +340,8 @@ Key Properties 4. **Detects Racy Writes from Devices:** Due to checking data values upon setting up watchpoints, racy writes from devices can also be detected. -5. **Memory Ordering:** KCSAN is *not* explicitly aware of the LKMM's ordering - rules; this may result in missed data races (false negatives). +5. **Memory Ordering:** KCSAN is aware of only a subset of LKMM ordering rules; + this may result in missed data races (false negatives). 6. **Analysis Accuracy:** For observed executions, due to using a sampling strategy, the analysis is *unsound* (false negatives possible), but aims to diff --git a/Documentation/dev-tools/kgdb.rst b/Documentation/dev-tools/kgdb.rst index 43456244651a..f83ba2601e55 100644 --- a/Documentation/dev-tools/kgdb.rst +++ b/Documentation/dev-tools/kgdb.rst @@ -402,7 +402,7 @@ This is a quick example of how to use kdb. 2. Enter the kernel debugger manually or by waiting for an oops or fault. There are several ways you can enter the kernel debugger manually; all involve using the :kbd:`SysRq-G`, which means you must have - enabled ``CONFIG_MAGIC_SysRq=y`` in your kernel config. + enabled ``CONFIG_MAGIC_SYSRQ=y`` in your kernel config. - When logged in as root or with a super user session you can run:: @@ -461,7 +461,7 @@ This is a quick example of how to use kdb with a keyboard. 2. Enter the kernel debugger manually or by waiting for an oops or fault. There are several ways you can enter the kernel debugger manually; all involve using the :kbd:`SysRq-G`, which means you must have - enabled ``CONFIG_MAGIC_SysRq=y`` in your kernel config. + enabled ``CONFIG_MAGIC_SYSRQ=y`` in your kernel config. - When logged in as root or with a super user session you can run:: @@ -557,7 +557,7 @@ Connecting with gdb to a serial port Example (using a directly connected port):: % gdb ./vmlinux - (gdb) set remotebaud 115200 + (gdb) set serial baud 115200 (gdb) target remote /dev/ttyS0 diff --git a/Documentation/dev-tools/ktap.rst b/Documentation/dev-tools/ktap.rst new file mode 100644 index 000000000000..878530cb9c27 --- /dev/null +++ b/Documentation/dev-tools/ktap.rst @@ -0,0 +1,298 @@ +.. SPDX-License-Identifier: GPL-2.0 + +======================================== +The Kernel Test Anything Protocol (KTAP) +======================================== + +TAP, or the Test Anything Protocol is a format for specifying test results used +by a number of projects. It's website and specification are found at this `link +`_. The Linux Kernel largely uses TAP output for test +results. However, Kernel testing frameworks have special needs for test results +which don't align with the original TAP specification. Thus, a "Kernel TAP" +(KTAP) format is specified to extend and alter TAP to support these use-cases. +This specification describes the generally accepted format of KTAP as it is +currently used in the kernel. + +KTAP test results describe a series of tests (which may be nested: i.e., test +can have subtests), each of which can contain both diagnostic data -- e.g., log +lines -- and a final result. The test structure and results are +machine-readable, whereas the diagnostic data is unstructured and is there to +aid human debugging. + +KTAP output is built from four different types of lines: +- Version lines +- Plan lines +- Test case result lines +- Diagnostic lines + +In general, valid KTAP output should also form valid TAP output, but some +information, in particular nested test results, may be lost. Also note that +there is a stagnant draft specification for TAP14, KTAP diverges from this in +a couple of places (notably the "Subtest" header), which are described where +relevant later in this document. + +Version lines +------------- + +All KTAP-formatted results begin with a "version line" which specifies which +version of the (K)TAP standard the result is compliant with. + +For example: +- "KTAP version 1" +- "TAP version 13" +- "TAP version 14" + +Note that, in KTAP, subtests also begin with a version line, which denotes the +start of the nested test results. This differs from TAP14, which uses a +separate "Subtest" line. + +While, going forward, "KTAP version 1" should be used by compliant tests, it +is expected that most parsers and other tooling will accept the other versions +listed here for compatibility with existing tests and frameworks. + +Plan lines +---------- + +A test plan provides the number of tests (or subtests) in the KTAP output. + +Plan lines must follow the format of "1..N" where N is the number of tests or subtests. +Plan lines follow version lines to indicate the number of nested tests. + +While there are cases where the number of tests is not known in advance -- in +which case the test plan may be omitted -- it is strongly recommended one is +present where possible. + +Test case result lines +---------------------- + +Test case result lines indicate the final status of a test. +They are required and must have the format: + +.. code-block:: + + [][ # [] []] + +The result can be either "ok", which indicates the test case passed, +or "not ok", which indicates that the test case failed. + + represents the number of the test being performed. The first test must +have the number 1 and the number then must increase by 1 for each additional +subtest within the same test at the same nesting level. + +The description is a description of the test, generally the name of +the test, and can be any string of words (can't include #). The +description is optional, but recommended. + +The directive and any diagnostic data is optional. If either are present, they +must follow a hash sign, "#". + +A directive is a keyword that indicates a different outcome for a test other +than passed and failed. The directive is optional, and consists of a single +keyword preceding the diagnostic data. In the event that a parser encounters +a directive it doesn't support, it should fall back to the "ok" / "not ok" +result. + +Currently accepted directives are: + +- "SKIP", which indicates a test was skipped (note the result of the test case + result line can be either "ok" or "not ok" if the SKIP directive is used) +- "TODO", which indicates that a test is not expected to pass at the moment, + e.g. because the feature it is testing is known to be broken. While this + directive is inherited from TAP, its use in the kernel is discouraged. +- "XFAIL", which indicates that a test is expected to fail. This is similar + to "TODO", above, and is used by some kselftest tests. +- “TIMEOUT”, which indicates a test has timed out (note the result of the test + case result line should be “not ok” if the TIMEOUT directive is used) +- “ERROR”, which indicates that the execution of a test has failed due to a + specific error that is included in the diagnostic data. (note the result of + the test case result line should be “not ok” if the ERROR directive is used) + +The diagnostic data is a plain-text field which contains any additional details +about why this result was produced. This is typically an error message for ERROR +or failed tests, or a description of missing dependencies for a SKIP result. + +The diagnostic data field is optional, and results which have neither a +directive nor any diagnostic data do not need to include the "#" field +separator. + +Example result lines include: + +.. code-block:: + + ok 1 test_case_name + +The test "test_case_name" passed. + +.. code-block:: + + not ok 1 test_case_name + +The test "test_case_name" failed. + +.. code-block:: + + ok 1 test # SKIP necessary dependency unavailable + +The test "test" was SKIPPED with the diagnostic message "necessary dependency +unavailable". + +.. code-block:: + + not ok 1 test # TIMEOUT 30 seconds + +The test "test" timed out, with diagnostic data "30 seconds". + +.. code-block:: + + ok 5 check return code # rcode=0 + +The test "check return code" passed, with additional diagnostic data “rcode=0” + + +Diagnostic lines +---------------- + +If tests wish to output any further information, they should do so using +"diagnostic lines". Diagnostic lines are optional, freeform text, and are +often used to describe what is being tested and any intermediate results in +more detail than the final result and diagnostic data line provides. + +Diagnostic lines are formatted as "# ", where the +description can be any string. Diagnostic lines can be anywhere in the test +output. As a rule, diagnostic lines regarding a test are directly before the +test result line for that test. + +Note that most tools will treat unknown lines (see below) as diagnostic lines, +even if they do not start with a "#": this is to capture any other useful +kernel output which may help debug the test. It is nevertheless recommended +that tests always prefix any diagnostic output they have with a "#" character. + +Unknown lines +------------- + +There may be lines within KTAP output that do not follow the format of one of +the four formats for lines described above. This is allowed, however, they will +not influence the status of the tests. + +Nested tests +------------ + +In KTAP, tests can be nested. This is done by having a test include within its +output an entire set of KTAP-formatted results. This can be used to categorize +and group related tests, or to split out different results from the same test. + +The "parent" test's result should consist of all of its subtests' results, +starting with another KTAP version line and test plan, and end with the overall +result. If one of the subtests fail, for example, the parent test should also +fail. + +Additionally, all result lines in a subtest should be indented. One level of +indentation is two spaces: " ". The indentation should begin at the version +line and should end before the parent test's result line. + +An example of a test with two nested subtests: + +.. code-block:: + + KTAP version 1 + 1..1 + KTAP version 1 + 1..2 + ok 1 test_1 + not ok 2 test_2 + # example failed + not ok 1 example + +An example format with multiple levels of nested testing: + +.. code-block:: + + KTAP version 1 + 1..2 + KTAP version 1 + 1..2 + KTAP version 1 + 1..2 + not ok 1 test_1 + ok 2 test_2 + not ok 1 test_3 + ok 2 test_4 # SKIP + not ok 1 example_test_1 + ok 2 example_test_2 + + +Major differences between TAP and KTAP +-------------------------------------- + +Note the major differences between the TAP and KTAP specification: +- yaml and json are not recommended in diagnostic messages +- TODO directive not recognized +- KTAP allows for an arbitrary number of tests to be nested + +The TAP14 specification does permit nested tests, but instead of using another +nested version line, uses a line of the form +"Subtest: " where is the name of the parent test. + +Example KTAP output +-------------------- +.. code-block:: + + KTAP version 1 + 1..1 + KTAP version 1 + 1..3 + KTAP version 1 + 1..1 + # test_1: initializing test_1 + ok 1 test_1 + ok 1 example_test_1 + KTAP version 1 + 1..2 + ok 1 test_1 # SKIP test_1 skipped + ok 2 test_2 + ok 2 example_test_2 + KTAP version 1 + 1..3 + ok 1 test_1 + # test_2: FAIL + not ok 2 test_2 + ok 3 test_3 # SKIP test_3 skipped + not ok 3 example_test_3 + not ok 1 main_test + +This output defines the following hierarchy: + +A single test called "main_test", which fails, and has three subtests: +- "example_test_1", which passes, and has one subtest: + + - "test_1", which passes, and outputs the diagnostic message "test_1: initializing test_1" + +- "example_test_2", which passes, and has two subtests: + + - "test_1", which is skipped, with the explanation "test_1 skipped" + - "test_2", which passes + +- "example_test_3", which fails, and has three subtests + + - "test_1", which passes + - "test_2", which outputs the diagnostic line "test_2: FAIL", and fails. + - "test_3", which is skipped with the explanation "test_3 skipped" + +Note that the individual subtests with the same names do not conflict, as they +are found in different parent tests. This output also exhibits some sensible +rules for "bubbling up" test results: a test fails if any of its subtests fail. +Skipped tests do not affect the result of the parent test (though it often +makes sense for a test to be marked skipped if _all_ of its subtests have been +skipped). + +See also: +--------- + +- The TAP specification: + https://testanything.org/tap-version-13-specification.html +- The (stagnant) TAP version 14 specification: + https://github.com/TestAnything/Specification/blob/tap-14-specification/specification.md +- The kselftest documentation: + Documentation/dev-tools/kselftest.rst +- The KUnit documentation: + Documentation/dev-tools/kunit/index.rst diff --git a/Documentation/dev-tools/kunit/architecture.rst b/Documentation/dev-tools/kunit/architecture.rst new file mode 100644 index 000000000000..aa2cea821e25 --- /dev/null +++ b/Documentation/dev-tools/kunit/architecture.rst @@ -0,0 +1,204 @@ +.. SPDX-License-Identifier: GPL-2.0 + +================== +KUnit Architecture +================== + +The KUnit architecture can be divided into two parts: + +- Kernel testing library +- kunit_tool (Command line test harness) + +In-Kernel Testing Framework +=========================== + +The kernel testing library supports KUnit tests written in C using +KUnit. KUnit tests are kernel code. KUnit does several things: + +- Organizes tests +- Reports test results +- Provides test utilities + +Test Cases +---------- + +The fundamental unit in KUnit is the test case. The KUnit test cases are +grouped into KUnit suites. A KUnit test case is a function with type +signature ``void (*)(struct kunit *test)``. +These test case functions are wrapped in a struct called +``struct kunit_case``. For code, see: + +.. kernel-doc:: include/kunit/test.h + :identifiers: kunit_case + +.. note: + ``generate_params`` is optional for non-parameterized tests. + +Each KUnit test case gets a ``struct kunit`` context +object passed to it that tracks a running test. The KUnit assertion +macros and other KUnit utilities use the ``struct kunit`` context +object. As an exception, there are two fields: + +- ``->priv``: The setup functions can use it to store arbitrary test + user data. + +- ``->param_value``: It contains the parameter value which can be + retrieved in the parameterized tests. + +Test Suites +----------- + +A KUnit suite includes a collection of test cases. The KUnit suites +are represented by the ``struct kunit_suite``. For example: + +.. code-block:: c + + static struct kunit_case example_test_cases[] = { + KUNIT_CASE(example_test_foo), + KUNIT_CASE(example_test_bar), + KUNIT_CASE(example_test_baz), + {} + }; + + static struct kunit_suite example_test_suite = { + .name = "example", + .init = example_test_init, + .exit = example_test_exit, + .test_cases = example_test_cases, + }; + kunit_test_suite(example_test_suite); + +In the above example, the test suite ``example_test_suite``, runs the +test cases ``example_test_foo``, ``example_test_bar``, and +``example_test_baz``. Before running the test, the ``example_test_init`` +is called and after running the test, ``example_test_exit`` is called. +The ``kunit_test_suite(example_test_suite)`` registers the test suite +with the KUnit test framework. + +Executor +-------- + +The KUnit executor can list and run built-in KUnit tests on boot. +The Test suites are stored in a linker section +called ``.kunit_test_suites``. For code, see: +https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/tree/include/asm-generic/vmlinux.lds.h?h=v5.15#n945. +The linker section consists of an array of pointers to +``struct kunit_suite``, and is populated by the ``kunit_test_suites()`` +macro. To run all tests compiled into the kernel, the KUnit executor +iterates over the linker section array. + +.. kernel-figure:: kunit_suitememorydiagram.svg + :alt: KUnit Suite Memory + + KUnit Suite Memory Diagram + +On the kernel boot, the KUnit executor uses the start and end addresses +of this section to iterate over and run all tests. For code, see: +https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/tree/lib/kunit/executor.c + +When built as a module, the ``kunit_test_suites()`` macro defines a +``module_init()`` function, which runs all the tests in the compilation +unit instead of utilizing the executor. + +In KUnit tests, some error classes do not affect other tests +or parts of the kernel, each KUnit case executes in a separate thread +context. For code, see: +https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/tree/lib/kunit/try-catch.c?h=v5.15#n58 + +Assertion Macros +---------------- + +KUnit tests verify state using expectations/assertions. +All expectations/assertions are formatted as: +``KUNIT_{EXPECT|ASSERT}_[_MSG](kunit, property[, message])`` + +- ``{EXPECT|ASSERT}`` determines whether the check is an assertion or an + expectation. + + - For an expectation, if the check fails, marks the test as failed + and logs the failure. + + - An assertion, on failure, causes the test case to terminate + immediately. + + - Assertions call function: + ``void __noreturn kunit_abort(struct kunit *)``. + + - ``kunit_abort`` calls function: + ``void __noreturn kunit_try_catch_throw(struct kunit_try_catch *try_catch)``. + + - ``kunit_try_catch_throw`` calls function: + ``void complete_and_exit(struct completion *, long) __noreturn;`` + and terminates the special thread context. + +- ```` denotes a check with options: ``TRUE`` (supplied property + has the boolean value “true”), ``EQ`` (two supplied properties are + equal), ``NOT_ERR_OR_NULL`` (supplied pointer is not null and does not + contain an “err” value). + +- ``[_MSG]`` prints a custom message on failure. + +Test Result Reporting +--------------------- +KUnit prints test results in KTAP format. KTAP is based on TAP14, see: +https://github.com/isaacs/testanything.github.io/blob/tap14/tap-version-14-specification.md. +KTAP (yet to be standardized format) works with KUnit and Kselftest. +The KUnit executor prints KTAP results to dmesg, and debugfs +(if configured). + +Parameterized Tests +------------------- + +Each KUnit parameterized test is associated with a collection of +parameters. The test is invoked multiple times, once for each parameter +value and the parameter is stored in the ``param_value`` field. +The test case includes a ``KUNIT_CASE_PARAM()`` macro that accepts a +generator function. +The generator function is passed the previous parameter and returns the next +parameter. It also provides a macro to generate common-case generators based on +arrays. + +For code, see: + +.. kernel-doc:: include/kunit/test.h + :identifiers: KUNIT_ARRAY_PARAM + + +kunit_tool (Command Line Test Harness) +====================================== + +kunit_tool is a Python script ``(tools/testing/kunit/kunit.py)`` +that can be used to configure, build, exec, parse and run (runs other +commands in order) test results. You can either run KUnit tests using +kunit_tool or can include KUnit in kernel and parse manually. + +- ``configure`` command generates the kernel ``.config`` from a + ``.kunitconfig`` file (and any architecture-specific options). + For some architectures, additional config options are specified in the + ``qemu_config`` Python script + (For example: ``tools/testing/kunit/qemu_configs/powerpc.py``). + It parses both the existing ``.config`` and the ``.kunitconfig`` files + and ensures that ``.config`` is a superset of ``.kunitconfig``. + If this is not the case, it will combine the two and run + ``make olddefconfig`` to regenerate the ``.config`` file. It then + verifies that ``.config`` is now a superset. This checks if all + Kconfig dependencies are correctly specified in ``.kunitconfig``. + ``kunit_config.py`` includes the parsing Kconfigs code. The code which + runs ``make olddefconfig`` is a part of ``kunit_kernel.py``. You can + invoke this command via: ``./tools/testing/kunit/kunit.py config`` and + generate a ``.config`` file. +- ``build`` runs ``make`` on the kernel tree with required options + (depends on the architecture and some options, for example: build_dir) + and reports any errors. + To build a KUnit kernel from the current ``.config``, you can use the + ``build`` argument: ``./tools/testing/kunit/kunit.py build``. +- ``exec`` command executes kernel results either directly (using + User-mode Linux configuration), or via an emulator such + as QEMU. It reads results from the log via standard + output (stdout), and passes them to ``parse`` to be parsed. + If you already have built a kernel with built-in KUnit tests, + you can run the kernel and display the test results with the ``exec`` + argument: ``./tools/testing/kunit/kunit.py exec``. +- ``parse`` extracts the KTAP output from a kernel log, parses + the test results, and prints a summary. For failed tests, any + diagnostic output will be included. diff --git a/Documentation/dev-tools/kunit/faq.rst b/Documentation/dev-tools/kunit/faq.rst index 5c6555d020f3..172e239791a8 100644 --- a/Documentation/dev-tools/kunit/faq.rst +++ b/Documentation/dev-tools/kunit/faq.rst @@ -4,56 +4,55 @@ Frequently Asked Questions ========================== -How is this different from Autotest, kselftest, etc? -==================================================== +How is this different from Autotest, kselftest, and so on? +========================================================== KUnit is a unit testing framework. Autotest, kselftest (and some others) are not. A `unit test `_ is supposed to -test a single unit of code in isolation, hence the name. A unit test should be -the finest granularity of testing and as such should allow all possible code -paths to be tested in the code under test; this is only possible if the code -under test is very small and does not have any external dependencies outside of +test a single unit of code in isolation and hence the name *unit test*. A unit +test should be the finest granularity of testing and should allow all possible +code paths to be tested in the code under test. This is only possible if the +code under test is small and does not have any external dependencies outside of the test's control like hardware. There are no testing frameworks currently available for the kernel that do not -require installing the kernel on a test machine or in a VM and all require -tests to be written in userspace and run on the kernel under test; this is true -for Autotest, kselftest, and some others, disqualifying any of them from being -considered unit testing frameworks. +require installing the kernel on a test machine or in a virtual machine. All +testing frameworks require tests to be written in userspace and run on the +kernel under test. This is true for Autotest, kselftest, and some others, +disqualifying any of them from being considered unit testing frameworks. Does KUnit support running on architectures other than UML? =========================================================== -Yes, well, mostly. +Yes, mostly. -For the most part, the KUnit core framework (what you use to write the tests) -can compile to any architecture; it compiles like just another part of the +For the most part, the KUnit core framework (what we use to write the tests) +can compile to any architecture. It compiles like just another part of the kernel and runs when the kernel boots, or when built as a module, when the -module is loaded. However, there is some infrastructure, -like the KUnit Wrapper (``tools/testing/kunit/kunit.py``) that does not support -other architectures. +module is loaded. However, there is infrastructure, like the KUnit Wrapper +(``tools/testing/kunit/kunit.py``) that does not support other architectures. -In short, this means that, yes, you can run KUnit on other architectures, but -it might require more work than using KUnit on UML. +In short, yes, you can run KUnit on other architectures, but it might require +more work than using KUnit on UML. For more information, see :ref:`kunit-on-non-uml`. -What is the difference between a unit test and these other kinds of tests? -========================================================================== +What is the difference between a unit test and other kinds of tests? +==================================================================== Most existing tests for the Linux kernel would be categorized as an integration test, or an end-to-end test. -- A unit test is supposed to test a single unit of code in isolation, hence the - name. A unit test should be the finest granularity of testing and as such - should allow all possible code paths to be tested in the code under test; this - is only possible if the code under test is very small and does not have any - external dependencies outside of the test's control like hardware. +- A unit test is supposed to test a single unit of code in isolation. A unit + test should be the finest granularity of testing and, as such, allows all + possible code paths to be tested in the code under test. This is only possible + if the code under test is small and does not have any external dependencies + outside of the test's control like hardware. - An integration test tests the interaction between a minimal set of components, usually just two or three. For example, someone might write an integration test to test the interaction between a driver and a piece of hardware, or to test the interaction between the userspace libraries the kernel provides and - the kernel itself; however, one of these tests would probably not test the + the kernel itself. However, one of these tests would probably not test the entire kernel along with hardware interactions and interactions with the userspace. - An end-to-end test usually tests the entire system from the perspective of the @@ -62,26 +61,26 @@ test, or an end-to-end test. hardware with a production userspace and then trying to exercise some behavior that depends on interactions between the hardware, the kernel, and userspace. -KUnit isn't working, what should I do? -====================================== +KUnit is not working, what should I do? +======================================= Unfortunately, there are a number of things which can break, but here are some things to try. -1. Try running ``./tools/testing/kunit/kunit.py run`` with the ``--raw_output`` +1. Run ``./tools/testing/kunit/kunit.py run`` with the ``--raw_output`` parameter. This might show details or error messages hidden by the kunit_tool parser. 2. Instead of running ``kunit.py run``, try running ``kunit.py config``, ``kunit.py build``, and ``kunit.py exec`` independently. This can help track down where an issue is occurring. (If you think the parser is at fault, you - can run it manually against stdin or a file with ``kunit.py parse``.) -3. Running the UML kernel directly can often reveal issues or error messages - kunit_tool ignores. This should be as simple as running ``./vmlinux`` after - building the UML kernel (e.g., by using ``kunit.py build``). Note that UML - has some unusual requirements (such as the host having a tmpfs filesystem - mounted), and has had issues in the past when built statically and the host - has KASLR enabled. (On older host kernels, you may need to run ``setarch - `uname -m` -R ./vmlinux`` to disable KASLR.) + can run it manually against ``stdin`` or a file with ``kunit.py parse``.) +3. Running the UML kernel directly can often reveal issues or error messages, + ``kunit_tool`` ignores. This should be as simple as running ``./vmlinux`` + after building the UML kernel (for example, by using ``kunit.py build``). + Note that UML has some unusual requirements (such as the host having a tmpfs + filesystem mounted), and has had issues in the past when built statically and + the host has KASLR enabled. (On older host kernels, you may need to run + ``setarch `uname -m` -R ./vmlinux`` to disable KASLR.) 4. Make sure the kernel .config has ``CONFIG_KUNIT=y`` and at least one test (e.g. ``CONFIG_KUNIT_EXAMPLE_TEST=y``). kunit_tool will keep its .config around, so you can see what config was used after running ``kunit.py run``. diff --git a/Documentation/dev-tools/kunit/index.rst b/Documentation/dev-tools/kunit/index.rst index 7af7dec83646..595205348d2d 100644 --- a/Documentation/dev-tools/kunit/index.rst +++ b/Documentation/dev-tools/kunit/index.rst @@ -1,13 +1,17 @@ .. SPDX-License-Identifier: GPL-2.0 -========================================= -KUnit - Unit Testing for the Linux Kernel -========================================= +================================= +KUnit - Linux Kernel Unit Testing +================================= .. toctree:: :maxdepth: 2 + :caption: Contents: start + architecture + run_wrapper + run_manual usage kunit-tool api/index @@ -16,82 +20,94 @@ KUnit - Unit Testing for the Linux Kernel tips running_tips -What is KUnit? -============== +This section details the kernel unit testing framework. -KUnit is a lightweight unit testing framework for the Linux kernel. +Introduction +============ -KUnit is heavily inspired by JUnit, Python's unittest.mock, and -Googletest/Googlemock for C++. KUnit provides facilities for defining unit test -cases, grouping related test cases into test suites, providing common -infrastructure for running tests, and much more. +KUnit (Kernel unit testing framework) provides a common framework for +unit tests within the Linux kernel. Using KUnit, you can define groups +of test cases called test suites. The tests either run on kernel boot +if built-in, or load as a module. KUnit automatically flags and reports +failed test cases in the kernel log. The test results appear in `TAP +(Test Anything Protocol) format `_. It is inspired by +JUnit, Python’s unittest.mock, and GoogleTest/GoogleMock (C++ unit testing +framework). -KUnit consists of a kernel component, which provides a set of macros for easily -writing unit tests. Tests written against KUnit will run on kernel boot if -built-in, or when loaded if built as a module. These tests write out results to -the kernel log in `TAP `_ format. +KUnit tests are part of the kernel, written in the C (programming) +language, and test parts of the Kernel implementation (example: a C +language function). Excluding build time, from invocation to +completion, KUnit can run around 100 tests in less than 10 seconds. +KUnit can test any kernel component, for example: file system, system +calls, memory management, device drivers and so on. -To make running these tests (and reading the results) easier, KUnit offers -:doc:`kunit_tool `, which builds a `User Mode Linux -`_ kernel, runs it, and parses the test -results. This provides a quick way of running KUnit tests during development, -without requiring a virtual machine or separate hardware. +KUnit follows the white-box testing approach. The test has access to +internal system functionality. KUnit runs in kernel space and is not +restricted to things exposed to user-space. -Get started now: Documentation/dev-tools/kunit/start.rst +In addition, KUnit has kunit_tool, a script (``tools/testing/kunit/kunit.py``) +that configures the Linux kernel, runs KUnit tests under QEMU or UML (`User Mode +Linux `_), parses the test results and +displays them in a user friendly manner. -Why KUnit? -========== +Features +-------- -A unit test is supposed to test a single unit of code in isolation, hence the -name. A unit test should be the finest granularity of testing and as such should -allow all possible code paths to be tested in the code under test; this is only -possible if the code under test is very small and does not have any external -dependencies outside of the test's control like hardware. +- Provides a framework for writing unit tests. +- Runs tests on any kernel architecture. +- Runs a test in milliseconds. -KUnit provides a common framework for unit tests within the kernel. +Prerequisites +------------- -KUnit tests can be run on most architectures, and most tests are architecture -independent. All built-in KUnit tests run on kernel startup. Alternatively, -KUnit and KUnit tests can be built as modules and tests will run when the test -module is loaded. +- Any Linux kernel compatible hardware. +- For Kernel under test, Linux kernel version 5.5 or greater. -.. note:: +Unit Testing +============ - KUnit can also run tests without needing a virtual machine or actual - hardware under User Mode Linux. User Mode Linux is a Linux architecture, - like ARM or x86, which compiles the kernel as a Linux executable. KUnit - can be used with UML either by building with ``ARCH=um`` (like any other - architecture), or by using :doc:`kunit_tool `. +A unit test tests a single unit of code in isolation. A unit test is the finest +granularity of testing and allows all possible code paths to be tested in the +code under test. This is possible if the code under test is small and does not +have any external dependencies outside of the test's control like hardware. -KUnit is fast. Excluding build time, from invocation to completion KUnit can run -several dozen tests in only 10 to 20 seconds; this might not sound like a big -deal to some people, but having such fast and easy to run tests fundamentally -changes the way you go about testing and even writing code in the first place. -Linus himself said in his `git talk at Google -`_: - "... a lot of people seem to think that performance is about doing the - same thing, just doing it faster, and that is not true. That is not what - performance is all about. If you can do something really fast, really - well, people will start using it differently." +Write Unit Tests +---------------- -In this context Linus was talking about branching and merging, -but this point also applies to testing. If your tests are slow, unreliable, are -difficult to write, and require a special setup or special hardware to run, -then you wait a lot longer to write tests, and you wait a lot longer to run -tests; this means that tests are likely to break, unlikely to test a lot of -things, and are unlikely to be rerun once they pass. If your tests are really -fast, you run them all the time, every time you make a change, and every time -someone sends you some code. Why trust that someone ran all their tests -correctly on every change when you can just run them yourself in less time than -it takes to read their test log? +To write good unit tests, there is a simple but powerful pattern: +Arrange-Act-Assert. This is a great way to structure test cases and +defines an order of operations. + +- Arrange inputs and targets: At the start of the test, arrange the data + that allows a function to work. Example: initialize a statement or + object. +- Act on the target behavior: Call your function/code under test. +- Assert expected outcome: Verify that the result (or resulting state) is as + expected. + +Unit Testing Advantages +----------------------- + +- Increases testing speed and development in the long run. +- Detects bugs at initial stage and therefore decreases bug fix cost + compared to acceptance testing. +- Improves code quality. +- Encourages writing testable code. How do I use it? ================ -* Documentation/dev-tools/kunit/start.rst - for new users of KUnit -* Documentation/dev-tools/kunit/tips.rst - for short examples of best practices -* Documentation/dev-tools/kunit/usage.rst - for a more detailed explanation of KUnit features -* Documentation/dev-tools/kunit/api/index.rst - for the list of KUnit APIs used for testing -* Documentation/dev-tools/kunit/kunit-tool.rst - for more information on the kunit_tool helper script -* Documentation/dev-tools/kunit/faq.rst - for answers to some common questions about KUnit +* Documentation/dev-tools/kunit/start.rst - for KUnit new users. +* Documentation/dev-tools/kunit/architecture.rst - KUnit architecture. +* Documentation/dev-tools/kunit/run_wrapper.rst - run kunit_tool. +* Documentation/dev-tools/kunit/run_manual.rst - run tests without kunit_tool. +* Documentation/dev-tools/kunit/usage.rst - write tests. +* Documentation/dev-tools/kunit/tips.rst - best practices with + examples. +* Documentation/dev-tools/kunit/api/index.rst - KUnit APIs + used for testing. +* Documentation/dev-tools/kunit/kunit-tool.rst - kunit_tool helper + script. +* Documentation/dev-tools/kunit/faq.rst - KUnit common questions and + answers. diff --git a/Documentation/dev-tools/kunit/kunit_suitememorydiagram.svg b/Documentation/dev-tools/kunit/kunit_suitememorydiagram.svg new file mode 100644 index 000000000000..cf8fddc27500 --- /dev/null +++ b/Documentation/dev-tools/kunit/kunit_suitememorydiagram.svg @@ -0,0 +1,81 @@ + + + + + + + + + + + + kunit_suite + + + + kunit_suite + + + + kunit_suite + + + + kunit_suite + + + + kunit_suite + + + + kunit_suite + + + + _kunit_suites_start + + + + _kunit_suites_end + + + .init.data + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + struct kunit_suite { const char name[256]; int (*init)(struct kunit *); void (*exit)(struct kunit *); struct kunit_case *test_cases; ...}; + + diff --git a/Documentation/dev-tools/kunit/run_manual.rst b/Documentation/dev-tools/kunit/run_manual.rst new file mode 100644 index 000000000000..e7b46421f247 --- /dev/null +++ b/Documentation/dev-tools/kunit/run_manual.rst @@ -0,0 +1,57 @@ +.. SPDX-License-Identifier: GPL-2.0 + +============================ +Run Tests without kunit_tool +============================ + +If we do not want to use kunit_tool (For example: we want to integrate +with other systems, or run tests on real hardware), we can +include KUnit in any kernel, read out results, and parse manually. + +.. note:: KUnit is not designed for use in a production system. It is + possible that tests may reduce the stability or security of + the system. + +Configure the Kernel +==================== + +KUnit tests can run without kunit_tool. This can be useful, if: + +- We have an existing kernel configuration to test. +- Need to run on real hardware (or using an emulator/VM kunit_tool + does not support). +- Wish to integrate with some existing testing systems. + +KUnit is configured with the ``CONFIG_KUNIT`` option, and individual +tests can also be built by enabling their config options in our +``.config``. KUnit tests usually (but don't always) have config options +ending in ``_KUNIT_TEST``. Most tests can either be built as a module, +or be built into the kernel. + +.. note :: + + We can enable the ``KUNIT_ALL_TESTS`` config option to + automatically enable all tests with satisfied dependencies. This is + a good way of quickly testing everything applicable to the current + config. + +Once we have built our kernel (and/or modules), it is simple to run +the tests. If the tests are built-in, they will run automatically on the +kernel boot. The results will be written to the kernel log (``dmesg``) +in TAP format. + +If the tests are built as modules, they will run when the module is +loaded. + +.. code-block :: bash + + # modprobe example-test + +The results will appear in TAP format in ``dmesg``. + +.. note :: + + If ``CONFIG_KUNIT_DEBUGFS`` is enabled, KUnit test results will + be accessible from the ``debugfs`` filesystem (if mounted). + They will be in ``/sys/kernel/debug/kunit//results``, in + TAP format. diff --git a/Documentation/dev-tools/kunit/run_wrapper.rst b/Documentation/dev-tools/kunit/run_wrapper.rst new file mode 100644 index 000000000000..653985ce9cae --- /dev/null +++ b/Documentation/dev-tools/kunit/run_wrapper.rst @@ -0,0 +1,247 @@ +.. SPDX-License-Identifier: GPL-2.0 + +========================= +Run Tests with kunit_tool +========================= + +We can either run KUnit tests using kunit_tool or can run tests +manually, and then use kunit_tool to parse the results. To run tests +manually, see: Documentation/dev-tools/kunit/run_manual.rst. +As long as we can build the kernel, we can run KUnit. + +kunit_tool is a Python script which configures and builds a kernel, runs +tests, and formats the test results. + +Run command: + +.. code-block:: + + ./tools/testing/kunit/kunit.py run + +We should see the following: + +.. code-block:: + + Generating .config... + Building KUnit kernel... + Starting KUnit kernel... + +We may want to use the following options: + +.. code-block:: + + ./tools/testing/kunit/kunit.py run --timeout=30 --jobs=`nproc --all + +- ``--timeout`` sets a maximum amount of time for tests to run. +- ``--jobs`` sets the number of threads to build the kernel. + +kunit_tool will generate a ``.kunitconfig`` with a default +configuration, if no other ``.kunitconfig`` file exists +(in the build directory). In addition, it verifies that the +generated ``.config`` file contains the ``CONFIG`` options in the +``.kunitconfig``. +It is also possible to pass a separate ``.kunitconfig`` fragment to +kunit_tool. This is useful if we have several different groups of +tests we want to run independently, or if we want to use pre-defined +test configs for certain subsystems. + +To use a different ``.kunitconfig`` file (such as one +provided to test a particular subsystem), pass it as an option: + +.. code-block:: + + ./tools/testing/kunit/kunit.py run --kunitconfig=fs/ext4/.kunitconfig + +To view kunit_tool flags (optional command-line arguments), run: + +.. code-block:: + + ./tools/testing/kunit/kunit.py run --help + +Create a ``.kunitconfig`` File +=============================== + +If we want to run a specific set of tests (rather than those listed +in the KUnit ``defconfig``), we can provide Kconfig options in the +``.kunitconfig`` file. For default .kunitconfig, see: +https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/tree/tools/testing/kunit/configs/default.config. +A ``.kunitconfig`` is a ``minconfig`` (a .config +generated by running ``make savedefconfig``), used for running a +specific set of tests. This file contains the regular Kernel configs +with specific test targets. The ``.kunitconfig`` also +contains any other config options required by the tests (For example: +dependencies for features under tests, configs that enable/disable +certain code blocks, arch configs and so on). + +To create a ``.kunitconfig``, using the KUnit ``defconfig``: + +.. code-block:: + + cd $PATH_TO_LINUX_REPO + cp tools/testing/kunit/configs/default.config .kunit/.kunitconfig + +We can then add any other Kconfig options. For example: + +.. code-block:: + + CONFIG_LIST_KUNIT_TEST=y + +kunit_tool ensures that all config options in ``.kunitconfig`` are +set in the kernel ``.config`` before running the tests. It warns if we +have not included the options dependencies. + +.. note:: Removing something from the ``.kunitconfig`` will + not rebuild the ``.config file``. The configuration is only + updated if the ``.kunitconfig`` is not a subset of ``.config``. + This means that we can use other tools + (For example: ``make menuconfig``) to adjust other config options. + The build dir needs to be set for ``make menuconfig`` to + work, therefore by default use ``make O=.kunit menuconfig``. + +Configure, Build, and Run Tests +=============================== + +If we want to make manual changes to the KUnit build process, we +can run part of the KUnit build process independently. +When running kunit_tool, from a ``.kunitconfig``, we can generate a +``.config`` by using the ``config`` argument: + +.. code-block:: + + ./tools/testing/kunit/kunit.py config + +To build a KUnit kernel from the current ``.config``, we can use the +``build`` argument: + +.. code-block:: + + ./tools/testing/kunit/kunit.py build + +If we already have built UML kernel with built-in KUnit tests, we +can run the kernel, and display the test results with the ``exec`` +argument: + +.. code-block:: + + ./tools/testing/kunit/kunit.py exec + +The ``run`` command discussed in section: **Run Tests with kunit_tool**, +is equivalent to running the above three commands in sequence. + +Parse Test Results +================== + +KUnit tests output displays results in TAP (Test Anything Protocol) +format. When running tests, kunit_tool parses this output and prints +a summary. To see the raw test results in TAP format, we can pass the +``--raw_output`` argument: + +.. code-block:: + + ./tools/testing/kunit/kunit.py run --raw_output + +If we have KUnit results in the raw TAP format, we can parse them and +print the human-readable summary with the ``parse`` command for +kunit_tool. This accepts a filename for an argument, or will read from +standard input. + +.. code-block:: bash + + # Reading from a file + ./tools/testing/kunit/kunit.py parse /var/log/dmesg + # Reading from stdin + dmesg | ./tools/testing/kunit/kunit.py parse + +Run Selected Test Suites +======================== + +By passing a bash style glob filter to the ``exec`` or ``run`` +commands, we can run a subset of the tests built into a kernel . For +example: if we only want to run KUnit resource tests, use: + +.. code-block:: + + ./tools/testing/kunit/kunit.py run 'kunit-resource*' + +This uses the standard glob format with wildcard characters. + +Run Tests on qemu +================= + +kunit_tool supports running tests on qemu as well as +via UML. To run tests on qemu, by default it requires two flags: + +- ``--arch``: Selects a configs collection (Kconfig, qemu config options + and so on), that allow KUnit tests to be run on the specified + architecture in a minimal way. The architecture argument is same as + the option name passed to the ``ARCH`` variable used by Kbuild. + Not all architectures currently support this flag, but we can use + ``--qemu_config`` to handle it. If ``um`` is passed (or this flag + is ignored), the tests will run via UML. Non-UML architectures, + for example: i386, x86_64, arm and so on; run on qemu. + +- ``--cross_compile``: Specifies the Kbuild toolchain. It passes the + same argument as passed to the ``CROSS_COMPILE`` variable used by + Kbuild. As a reminder, this will be the prefix for the toolchain + binaries such as GCC. For example: + + - ``sparc64-linux-gnu`` if we have the sparc toolchain installed on + our system. + + - ``$HOME/toolchains/microblaze/gcc-9.2.0-nolibc/microblaze-linux/bin/microblaze-linux`` + if we have downloaded the microblaze toolchain from the 0-day + website to a directory in our home directory called toolchains. + +If we want to run KUnit tests on an architecture not supported by +the ``--arch`` flag, or want to run KUnit tests on qemu using a +non-default configuration; then we can write our own``QemuConfig``. +These ``QemuConfigs`` are written in Python. They have an import line +``from..qemu_config import QemuArchParams`` at the top of the file. +The file must contain a variable called ``QEMU_ARCH`` that has an +instance of ``QemuArchParams`` assigned to it. See example in: +``tools/testing/kunit/qemu_configs/x86_64.py``. + +Once we have a ``QemuConfig``, we can pass it into kunit_tool, +using the ``--qemu_config`` flag. When used, this flag replaces the +``--arch`` flag. For example: using +``tools/testing/kunit/qemu_configs/x86_64.py``, the invocation appear +as + +.. code-block:: bash + + ./tools/testing/kunit/kunit.py run \ + --timeout=60 \ + --jobs=12 \ + --qemu_config=./tools/testing/kunit/qemu_configs/x86_64.py + +To run existing KUnit tests on non-UML architectures, see: +Documentation/dev-tools/kunit/non_uml.rst. + +Command-Line Arguments +====================== + +kunit_tool has a number of other command-line arguments which can +be useful for our test environment. Below the most commonly used +command line arguments: + +- ``--help``: Lists all available options. To list common options, + place ``--help`` before the command. To list options specific to that + command, place ``--help`` after the command. + + .. note:: Different commands (``config``, ``build``, ``run``, etc) + have different supported options. +- ``--build_dir``: Specifies kunit_tool build directory. It includes + the ``.kunitconfig``, ``.config`` files and compiled kernel. + +- ``--make_options``: Specifies additional options to pass to make, when + compiling a kernel (using ``build`` or ``run`` commands). For example: + to enable compiler warnings, we can pass ``--make_options W=1``. + +- ``--alltests``: Builds a UML kernel with all config options enabled + using ``make allyesconfig``. This allows us to run as many tests as + possible. + + .. note:: It is slow and prone to breakage as new options are + added or modified. Instead, enable all tests + which have satisfied dependencies by adding + ``CONFIG_KUNIT_ALL_TESTS=y`` to your ``.kunitconfig``. diff --git a/Documentation/dev-tools/kunit/start.rst b/Documentation/dev-tools/kunit/start.rst index 0a5e65540974..ad168d16968f 100644 --- a/Documentation/dev-tools/kunit/start.rst +++ b/Documentation/dev-tools/kunit/start.rst @@ -4,132 +4,137 @@ Getting Started =============== -Installing dependencies +Installing Dependencies ======================= -KUnit has the same dependencies as the Linux kernel. As long as you can build -the kernel, you can run KUnit. +KUnit has the same dependencies as the Linux kernel. As long as you can +build the kernel, you can run KUnit. -Running tests with the KUnit Wrapper -==================================== -Included with KUnit is a simple Python wrapper which runs tests under User Mode -Linux, and formats the test results. - -The wrapper can be run with: +Running tests with kunit_tool +============================= +kunit_tool is a Python script, which configures and builds a kernel, runs +tests, and formats the test results. From the kernel repository, you +can run kunit_tool: .. code-block:: bash ./tools/testing/kunit/kunit.py run -For more information on this wrapper (also called kunit_tool) check out the -Documentation/dev-tools/kunit/kunit-tool.rst page. +For more information on this wrapper, see: +Documentation/dev-tools/kunit/run_wrapper.rst. -Creating a .kunitconfig ------------------------ -If you want to run a specific set of tests (rather than those listed in the -KUnit defconfig), you can provide Kconfig options in the ``.kunitconfig`` file. -This file essentially contains the regular Kernel config, with the specific -test targets as well. The ``.kunitconfig`` should also contain any other config -options required by the tests. +Creating a ``.kunitconfig`` +--------------------------- -A good starting point for a ``.kunitconfig`` is the KUnit defconfig: +By default, kunit_tool runs a selection of tests. However, you can specify which +unit tests to run by creating a ``.kunitconfig`` file with kernel config options +that enable only a specific set of tests and their dependencies. +The ``.kunitconfig`` file contains a list of kconfig options which are required +to run the desired targets. The ``.kunitconfig`` also contains any other test +specific config options, such as test dependencies. For example: the +``FAT_FS`` tests - ``FAT_KUNIT_TEST``, depends on +``FAT_FS``. ``FAT_FS`` can be enabled by selecting either ``MSDOS_FS`` +or ``VFAT_FS``. To run ``FAT_KUNIT_TEST``, the ``.kunitconfig`` has: + +.. code-block:: none + + CONFIG_KUNIT=y + CONFIG_MSDOS_FS=y + CONFIG_FAT_KUNIT_TEST=y + +1. A good starting point for the ``.kunitconfig``, is the KUnit default + config. Run the command: .. code-block:: bash cd $PATH_TO_LINUX_REPO cp tools/testing/kunit/configs/default.config .kunitconfig -You can then add any other Kconfig options you wish, e.g.: +.. note :: + You may want to remove CONFIG_KUNIT_ALL_TESTS from the ``.kunitconfig`` as + it will enable a number of additional tests that you may not want. + +2. You can then add any other Kconfig options, for example: .. code-block:: none CONFIG_LIST_KUNIT_TEST=y -:doc:`kunit_tool ` will ensure that all config options set in -``.kunitconfig`` are set in the kernel ``.config`` before running the tests. -It'll warn you if you haven't included the dependencies of the options you're -using. +Before running the tests, kunit_tool ensures that all config options +set in ``.kunitconfig`` are set in the kernel ``.config``. It will warn +you if you have not included dependencies for the options used. -.. note:: +.. note :: If you change the ``.kunitconfig``, kunit.py will trigger a rebuild of the ``.config`` file. But you can edit the ``.config`` file directly or with tools like ``make menuconfig O=.kunit``. As long as its a superset of ``.kunitconfig``, kunit.py won't overwrite your changes. - -Running the tests (KUnit Wrapper) ---------------------------------- - -To make sure that everything is set up correctly, simply invoke the Python -wrapper from your kernel repo: +Running Tests (KUnit Wrapper) +----------------------------- +1. To make sure that everything is set up correctly, invoke the Python + wrapper from your kernel repository: .. code-block:: bash ./tools/testing/kunit/kunit.py run -.. note:: - You may want to run ``make mrproper`` first. - If everything worked correctly, you should see the following: -.. code-block:: bash +.. code-block:: Generating .config ... Building KUnit Kernel ... Starting KUnit Kernel ... -followed by a list of tests that are run. All of them should be passing. +The tests will pass or fail. -.. note:: - Because it is building a lot of sources for the first time, the - ``Building KUnit kernel`` step may take a while. +.. note :: + Because it is building a lot of sources for the first time, the + ``Building KUnit kernel`` may take a while. -Running tests without the KUnit Wrapper +Running Tests without the KUnit Wrapper ======================================= +If you do not want to use the KUnit Wrapper (for example: you want code +under test to integrate with other systems, or use a different/ +unsupported architecture or configuration), KUnit can be included in +any kernel, and the results are read out and parsed manually. -If you'd rather not use the KUnit Wrapper (if, for example, you need to -integrate with other systems, or use an architecture other than UML), KUnit can -be included in any kernel, and the results read out and parsed manually. +.. note :: + ``CONFIG_KUNIT`` should not be enabled in a production environment. + Enabling KUnit disables Kernel Address-Space Layout Randomization + (KASLR), and tests may affect the state of the kernel in ways not + suitable for production. -.. note:: - KUnit is not designed for use in a production system, and it's possible that - tests may reduce the stability or security of the system. - - - -Configuring the kernel +Configuring the Kernel ---------------------- +To enable KUnit itself, you need to enable the ``CONFIG_KUNIT`` Kconfig +option (under Kernel Hacking/Kernel Testing and Coverage in +``menuconfig``). From there, you can enable any KUnit tests. They +usually have config options ending in ``_KUNIT_TEST``. -In order to enable KUnit itself, you simply need to enable the ``CONFIG_KUNIT`` -Kconfig option (it's under Kernel Hacking/Kernel Testing and Coverage in -menuconfig). From there, you can enable any KUnit tests you want: they usually -have config options ending in ``_KUNIT_TEST``. +KUnit and KUnit tests can be compiled as modules. The tests in a module +will run when the module is loaded. -KUnit and KUnit tests can be compiled as modules: in this case the tests in a -module will be run when the module is loaded. - - -Running the tests (w/o KUnit Wrapper) +Running Tests (without KUnit Wrapper) ------------------------------------- +Build and run your kernel. In the kernel log, the test output is printed +out in the TAP format. This will only happen by default if KUnit/tests +are built-in. Otherwise the module will need to be loaded. -Build and run your kernel as usual. Test output will be written to the kernel -log in `TAP `_ format. +.. note :: + Some lines and/or data may get interspersed in the TAP output. -.. note:: - It's possible that there will be other lines and/or data interspersed in the - TAP output. - - -Writing your first test +Writing Your First Test ======================= +In your kernel repository, let's add some code that we can test. -In your kernel repo let's add some code that we can test. Create a file -``drivers/misc/example.h`` with the contents: +1. Create a file ``drivers/misc/example.h``, which includes: .. code-block:: c int misc_example_add(int left, int right); -create a file ``drivers/misc/example.c``: +2. Create a file ``drivers/misc/example.c``, which includes: .. code-block:: c @@ -142,21 +147,22 @@ create a file ``drivers/misc/example.c``: return left + right; } -Now add the following lines to ``drivers/misc/Kconfig``: +3. Add the following lines to ``drivers/misc/Kconfig``: .. code-block:: kconfig config MISC_EXAMPLE bool "My example" -and the following lines to ``drivers/misc/Makefile``: +4. Add the following lines to ``drivers/misc/Makefile``: .. code-block:: make obj-$(CONFIG_MISC_EXAMPLE) += example.o -Now we are ready to write the test. The test will be in -``drivers/misc/example-test.c``: +Now we are ready to write the test cases. + +1. Add the below test case in ``drivers/misc/example_test.c``: .. code-block:: c @@ -191,7 +197,7 @@ Now we are ready to write the test. The test will be in }; kunit_test_suite(misc_example_test_suite); -Now add the following to ``drivers/misc/Kconfig``: +2. Add the following lines to ``drivers/misc/Kconfig``: .. code-block:: kconfig @@ -200,20 +206,20 @@ Now add the following to ``drivers/misc/Kconfig``: depends on MISC_EXAMPLE && KUNIT=y default KUNIT_ALL_TESTS -and the following to ``drivers/misc/Makefile``: +3. Add the following lines to ``drivers/misc/Makefile``: .. code-block:: make - obj-$(CONFIG_MISC_EXAMPLE_TEST) += example-test.o + obj-$(CONFIG_MISC_EXAMPLE_TEST) += example_test.o -Now add it to your ``.kunitconfig``: +4. Add the following lines to ``.kunitconfig``: .. code-block:: none CONFIG_MISC_EXAMPLE=y CONFIG_MISC_EXAMPLE_TEST=y -Now you can run the test: +5. Run the test: .. code-block:: bash @@ -227,16 +233,23 @@ You should see the following failure: [16:08:57] [PASSED] misc-example:misc_example_add_test_basic [16:08:57] [FAILED] misc-example:misc_example_test_failure [16:08:57] EXPECTATION FAILED at drivers/misc/example-test.c:17 - [16:08:57] This test never passes. + [16:08:57] This test never passes. ... -Congrats! You just wrote your first KUnit test! +Congrats! You just wrote your first KUnit test. Next Steps ========== -* Check out the Documentation/dev-tools/kunit/tips.rst page for tips on - writing idiomatic KUnit tests. -* Check out the :doc:`running_tips` page for tips on - how to make running KUnit tests easier. -* Optional: see the :doc:`usage` page for a more - in-depth explanation of KUnit. + +* Documentation/dev-tools/kunit/architecture.rst - KUnit architecture. +* Documentation/dev-tools/kunit/run_wrapper.rst - run kunit_tool. +* Documentation/dev-tools/kunit/run_manual.rst - run tests without kunit_tool. +* Documentation/dev-tools/kunit/usage.rst - write tests. +* Documentation/dev-tools/kunit/tips.rst - best practices with + examples. +* Documentation/dev-tools/kunit/api/index.rst - KUnit APIs + used for testing. +* Documentation/dev-tools/kunit/kunit-tool.rst - kunit_tool helper + script. +* Documentation/dev-tools/kunit/faq.rst - KUnit common questions and + answers. diff --git a/Documentation/dev-tools/kunit/style.rst b/Documentation/dev-tools/kunit/style.rst index 8dbcdc552606..b6d0d7359f00 100644 --- a/Documentation/dev-tools/kunit/style.rst +++ b/Documentation/dev-tools/kunit/style.rst @@ -4,37 +4,36 @@ Test Style and Nomenclature =========================== -To make finding, writing, and using KUnit tests as simple as possible, it's +To make finding, writing, and using KUnit tests as simple as possible, it is strongly encouraged that they are named and written according to the guidelines -below. While it's possible to write KUnit tests which do not follow these rules, +below. While it is possible to write KUnit tests which do not follow these rules, they may break some tooling, may conflict with other tests, and may not be run automatically by testing systems. -It's recommended that you only deviate from these guidelines when: +It is recommended that you only deviate from these guidelines when: -1. Porting tests to KUnit which are already known with an existing name, or -2. Writing tests which would cause serious problems if automatically run (e.g., - non-deterministically producing false positives or negatives, or taking an - extremely long time to run). +1. Porting tests to KUnit which are already known with an existing name. +2. Writing tests which would cause serious problems if automatically run. For + example, non-deterministically producing false positives or negatives, or + taking a long time to run. Subsystems, Suites, and Tests ============================= -In order to make tests as easy to find as possible, they're grouped into suites -and subsystems. A test suite is a group of tests which test a related area of -the kernel, and a subsystem is a set of test suites which test different parts -of the same kernel subsystem or driver. +To make tests easy to find, they are grouped into suites and subsystems. A test +suite is a group of tests which test a related area of the kernel. A subsystem +is a set of test suites which test different parts of a kernel subsystem +or a driver. Subsystems ---------- Every test suite must belong to a subsystem. A subsystem is a collection of one or more KUnit test suites which test the same driver or part of the kernel. A -rule of thumb is that a test subsystem should match a single kernel module. If -the code being tested can't be compiled as a module, in many cases the subsystem -should correspond to a directory in the source tree or an entry in the -MAINTAINERS file. If unsure, follow the conventions set by tests in similar -areas. +test subsystem should match a single kernel module. If the code being tested +cannot be compiled as a module, in many cases the subsystem should correspond to +a directory in the source tree or an entry in the ``MAINTAINERS`` file. If +unsure, follow the conventions set by tests in similar areas. Test subsystems should be named after the code being tested, either after the module (wherever possible), or after the directory or files being tested. Test @@ -42,9 +41,8 @@ subsystems should be named to avoid ambiguity where necessary. If a test subsystem name has multiple components, they should be separated by underscores. *Do not* include "test" or "kunit" directly in the subsystem name -unless you are actually testing other tests or the kunit framework itself. - -Example subsystems could be: +unless we are actually testing other tests or the kunit framework itself. For +example, subsystems could be called: ``ext4`` Matches the module and filesystem name. @@ -56,48 +54,46 @@ Example subsystems could be: Has several components (``snd``, ``hda``, ``codec``, ``hdmi``) separated by underscores. Matches the module name. -Avoid names like these: +Avoid names as shown in examples below: ``linear-ranges`` Names should use underscores, not dashes, to separate words. Prefer ``linear_ranges``. ``qos-kunit-test`` - As well as using underscores, this name should not have "kunit-test" as a - suffix, and ``qos`` is ambiguous as a subsystem name. ``power_qos`` would be a - better name. + This name should use underscores, and not have "kunit-test" as a + suffix. ``qos`` is also ambiguous as a subsystem name, because several parts + of the kernel have a ``qos`` subsystem. ``power_qos`` would be a better name. ``pc_parallel_port`` The corresponding module name is ``parport_pc``, so this subsystem should also be named ``parport_pc``. .. note:: - The KUnit API and tools do not explicitly know about subsystems. They're - simply a way of categorising test suites and naming modules which - provides a simple, consistent way for humans to find and run tests. This - may change in the future, though. + The KUnit API and tools do not explicitly know about subsystems. They are + a way of categorizing test suites and naming modules which provides a + simple, consistent way for humans to find and run tests. This may change + in the future. Suites ------ KUnit tests are grouped into test suites, which cover a specific area of -functionality being tested. Test suites can have shared initialisation and -shutdown code which is run for all tests in the suite. -Not all subsystems will need to be split into multiple test suites (e.g. simple drivers). +functionality being tested. Test suites can have shared initialization and +shutdown code which is run for all tests in the suite. Not all subsystems need +to be split into multiple test suites (for example, simple drivers). Test suites are named after the subsystem they are part of. If a subsystem contains several suites, the specific area under test should be appended to the subsystem name, separated by an underscore. In the event that there are multiple types of test using KUnit within a -subsystem (e.g., both unit tests and integration tests), they should be put into -separate suites, with the type of test as the last element in the suite name. -Unless these tests are actually present, avoid using ``_test``, ``_unittest`` or -similar in the suite name. +subsystem (for example, both unit tests and integration tests), they should be +put into separate suites, with the type of test as the last element in the suite +name. Unless these tests are actually present, avoid using ``_test``, ``_unittest`` +or similar in the suite name. The full test suite name (including the subsystem name) should be specified as the ``.name`` member of the ``kunit_suite`` struct, and forms the base for the -module name (see below). - -Example test suites could include: +module name. For example, test suites could include: ``ext4_inode`` Part of the ``ext4`` subsystem, testing the ``inode`` area. @@ -109,26 +105,27 @@ Example test suites could include: The ``kasan`` subsystem has only one suite, so the suite name is the same as the subsystem name. -Avoid names like: +Avoid names, for example: ``ext4_ext4_inode`` - There's no reason to state the subsystem twice. + There is no reason to state the subsystem twice. ``property_entry`` The suite name is ambiguous without the subsystem name. ``kasan_integration_test`` Because there is only one suite in the ``kasan`` subsystem, the suite should - just be called ``kasan``. There's no need to redundantly add - ``integration_test``. Should a separate test suite with, for example, unit - tests be added, then that suite could be named ``kasan_unittest`` or similar. + just be called as ``kasan``. Do not redundantly add + ``integration_test``. It should be a separate test suite. For example, if the + unit tests are added, then that suite could be named as ``kasan_unittest`` or + similar. Test Cases ---------- Individual tests consist of a single function which tests a constrained -codepath, property, or function. In the test output, individual tests' results -will show up as subtests of the suite's results. +codepath, property, or function. In the test output, an individual test's +results will show up as subtests of the suite's results. -Tests should be named after what they're testing. This is often the name of the +Tests should be named after what they are testing. This is often the name of the function being tested, with a description of the input or codepath being tested. As tests are C functions, they should be named and written in accordance with the kernel coding style. @@ -136,7 +133,7 @@ the kernel coding style. .. note:: As tests are themselves functions, their names cannot conflict with other C identifiers in the kernel. This may require some creative - naming. It's a good idea to make your test functions `static` to avoid + naming. It is a good idea to make your test functions `static` to avoid polluting the global namespace. Example test names include: @@ -162,16 +159,16 @@ This Kconfig entry must: * be named ``CONFIG__KUNIT_TEST``: where is the name of the test suite. * be listed either alongside the config entries for the driver/subsystem being - tested, or be under [Kernel Hacking]→[Kernel Testing and Coverage] -* depend on ``CONFIG_KUNIT`` + tested, or be under [Kernel Hacking]->[Kernel Testing and Coverage] +* depend on ``CONFIG_KUNIT``. * be visible only if ``CONFIG_KUNIT_ALL_TESTS`` is not enabled. * have a default value of ``CONFIG_KUNIT_ALL_TESTS``. -* have a brief description of KUnit in the help text +* have a brief description of KUnit in the help text. -Unless there's a specific reason not to (e.g. the test is unable to be built as -a module), Kconfig entries for tests should be tristate. +If we are not able to meet above conditions (for example, the test is unable to +be built as a module), Kconfig entries for tests should be tristate. -An example Kconfig entry: +For example, a Kconfig entry might look like: .. code-block:: none @@ -182,8 +179,8 @@ An example Kconfig entry: help This builds unit tests for foo. - For more information on KUnit and unit tests in general, please refer - to the KUnit documentation in Documentation/dev-tools/kunit/. + For more information on KUnit and unit tests in general, + please refer to the KUnit documentation in Documentation/dev-tools/kunit/. If unsure, say N. diff --git a/Documentation/dev-tools/kunit/usage.rst b/Documentation/dev-tools/kunit/usage.rst index 63f1bb89ebf5..76af931a332c 100644 --- a/Documentation/dev-tools/kunit/usage.rst +++ b/Documentation/dev-tools/kunit/usage.rst @@ -1,57 +1,13 @@ .. SPDX-License-Identifier: GPL-2.0 -=========== -Using KUnit -=========== - -The purpose of this document is to describe what KUnit is, how it works, how it -is intended to be used, and all the concepts and terminology that are needed to -understand it. This guide assumes a working knowledge of the Linux kernel and -some basic knowledge of testing. - -For a high level introduction to KUnit, including setting up KUnit for your -project, see Documentation/dev-tools/kunit/start.rst. - -Organization of this document -============================= - -This document is organized into two main sections: Testing and Common Patterns. -The first covers what unit tests are and how to use KUnit to write them. The -second covers common testing patterns, e.g. how to isolate code and make it -possible to unit test code that was otherwise un-unit-testable. - -Testing -======= - -What is KUnit? --------------- - -"K" is short for "kernel" so "KUnit" is the "(Linux) Kernel Unit Testing -Framework." KUnit is intended first and foremost for writing unit tests; it is -general enough that it can be used to write integration tests; however, this is -a secondary goal. KUnit has no ambition of being the only testing framework for -the kernel; for example, it does not intend to be an end-to-end testing -framework. - -What is Unit Testing? ---------------------- - -A `unit test `_ is a test that -tests code at the smallest possible scope, a *unit* of code. In the C -programming language that's a function. - -Unit tests should be written for all the publicly exposed functions in a -compilation unit; so that is all the functions that are exported in either a -*class* (defined below) or all functions which are **not** static. - Writing Tests -------------- +============= Test Cases -~~~~~~~~~~ +---------- The fundamental unit in KUnit is the test case. A test case is a function with -the signature ``void (*)(struct kunit *test)``. It calls a function to be tested +the signature ``void (*)(struct kunit *test)``. It calls the function under test and then sets *expectations* for what should happen. For example: .. code-block:: c @@ -65,18 +21,19 @@ and then sets *expectations* for what should happen. For example: KUNIT_FAIL(test, "This test never passes."); } -In the above example ``example_test_success`` always passes because it does -nothing; no expectations are set, so all expectations pass. On the other hand -``example_test_failure`` always fails because it calls ``KUNIT_FAIL``, which is -a special expectation that logs a message and causes the test case to fail. +In the above example, ``example_test_success`` always passes because it does +nothing; no expectations are set, and therefore all expectations pass. On the +other hand ``example_test_failure`` always fails because it calls ``KUNIT_FAIL``, +which is a special expectation that logs a message and causes the test case to +fail. Expectations ~~~~~~~~~~~~ -An *expectation* is a way to specify that you expect a piece of code to do -something in a test. An expectation is called like a function. A test is made -by setting expectations about the behavior of a piece of code under test; when -one or more of the expectations fail, the test case fails and information about -the failure is logged. For example: +An *expectation* specifies that we expect a piece of code to do something in a +test. An expectation is called like a function. A test is made by setting +expectations about the behavior of a piece of code under test. When one or more +expectations fail, the test case fails and information about the failure is +logged. For example: .. code-block:: c @@ -86,29 +43,28 @@ the failure is logged. For example: KUNIT_EXPECT_EQ(test, 2, add(1, 1)); } -In the above example ``add_test_basic`` makes a number of assertions about the -behavior of a function called ``add``; the first parameter is always of type -``struct kunit *``, which contains information about the current test context; -the second parameter, in this case, is what the value is expected to be; the +In the above example, ``add_test_basic`` makes a number of assertions about the +behavior of a function called ``add``. The first parameter is always of type +``struct kunit *``, which contains information about the current test context. +The second parameter, in this case, is what the value is expected to be. The last value is what the value actually is. If ``add`` passes all of these expectations, the test case, ``add_test_basic`` will pass; if any one of these expectations fails, the test case will fail. -It is important to understand that a test case *fails* when any expectation is -violated; however, the test will continue running, potentially trying other -expectations until the test case ends or is otherwise terminated. This is as -opposed to *assertions* which are discussed later. +A test case *fails* when any expectation is violated; however, the test will +continue to run, and try other expectations until the test case ends or is +otherwise terminated. This is as opposed to *assertions* which are discussed +later. -To learn about more expectations supported by KUnit, see -Documentation/dev-tools/kunit/api/test.rst. +To learn about more KUnit expectations, see Documentation/dev-tools/kunit/api/test.rst. .. note:: - A single test case should be pretty short, pretty easy to understand, - focused on a single behavior. + A single test case should be short, easy to understand, and focused on a + single behavior. -For example, if we wanted to properly test the add function above, we would -create additional tests cases which would each test a different property that an -add function should have like this: +For example, if we want to rigorously test the ``add`` function above, create +additional tests cases which would test each property that an ``add`` function +should have as shown below: .. code-block:: c @@ -134,56 +90,43 @@ add function should have like this: KUNIT_EXPECT_EQ(test, INT_MIN, add(INT_MAX, 1)); } -Notice how it is immediately obvious what all the properties that we are testing -for are. - Assertions ~~~~~~~~~~ -KUnit also has the concept of an *assertion*. An assertion is just like an -expectation except the assertion immediately terminates the test case if it is -not satisfied. - -For example: +An assertion is like an expectation, except that the assertion immediately +terminates the test case if the condition is not satisfied. For example: .. code-block:: c - static void mock_test_do_expect_default_return(struct kunit *test) + static void test_sort(struct kunit *test) { - struct mock_test_context *ctx = test->priv; - struct mock *mock = ctx->mock; - int param0 = 5, param1 = -5; - const char *two_param_types[] = {"int", "int"}; - const void *two_params[] = {¶m0, ¶m1}; - const void *ret; - - ret = mock->do_expect(mock, - "test_printk", test_printk, - two_param_types, two_params, - ARRAY_SIZE(two_params)); - KUNIT_ASSERT_NOT_ERR_OR_NULL(test, ret); - KUNIT_EXPECT_EQ(test, -4, *((int *) ret)); + int *a, i, r = 1; + a = kunit_kmalloc_array(test, TEST_LEN, sizeof(*a), GFP_KERNEL); + KUNIT_ASSERT_NOT_ERR_OR_NULL(test, a); + for (i = 0; i < TEST_LEN; i++) { + r = (r * 725861) % 6599; + a[i] = r; + } + sort(a, TEST_LEN, sizeof(*a), cmpint, NULL); + for (i = 0; i < TEST_LEN-1; i++) + KUNIT_EXPECT_LE(test, a[i], a[i + 1]); } -In this example, the method under test should return a pointer to a value, so -if the pointer returned by the method is null or an errno, we don't want to -bother continuing the test since the following expectation could crash the test -case. `ASSERT_NOT_ERR_OR_NULL(...)` allows us to bail out of the test case if -the appropriate conditions have not been satisfied to complete the test. +In this example, the method under test should return pointer to a value. If the +pointer returns null or an errno, we want to stop the test since the following +expectation could crash the test case. `ASSERT_NOT_ERR_OR_NULL(...)` allows us +to bail out of the test case if the appropriate conditions are not satisfied to +complete the test. Test Suites ~~~~~~~~~~~ -Now obviously one unit test isn't very helpful; the power comes from having -many test cases covering all of a unit's behaviors. Consequently it is common -to have many *similar* tests; in order to reduce duplication in these closely -related tests most unit testing frameworks - including KUnit - provide the -concept of a *test suite*. A *test suite* is just a collection of test cases -for a unit of code with a set up function that gets invoked before every test -case and then a tear down function that gets invoked after every test case -completes. - -Example: +We need many test cases covering all the unit's behaviors. It is common to have +many similar tests. In order to reduce duplication in these closely related +tests, most unit testing frameworks (including KUnit) provide the concept of a +*test suite*. A test suite is a collection of test cases for a unit of code +with a setup function that gets invoked before every test case and then a tear +down function that gets invoked after every test case completes. For example: .. code-block:: c @@ -202,23 +145,48 @@ Example: }; kunit_test_suite(example_test_suite); -In the above example the test suite, ``example_test_suite``, would run the test -cases ``example_test_foo``, ``example_test_bar``, and ``example_test_baz``; -each would have ``example_test_init`` called immediately before it and would -have ``example_test_exit`` called immediately after it. +In the above example, the test suite ``example_test_suite`` would run the test +cases ``example_test_foo``, ``example_test_bar``, and ``example_test_baz``. Each +would have ``example_test_init`` called immediately before it and +``example_test_exit`` called immediately after it. ``kunit_test_suite(example_test_suite)`` registers the test suite with the KUnit test framework. .. note:: - A test case will only be run if it is associated with a test suite. + A test case will only run if it is associated with a test suite. -``kunit_test_suite(...)`` is a macro which tells the linker to put the specified -test suite in a special linker section so that it can be run by KUnit either -after late_init, or when the test module is loaded (depending on whether the -test was built in or not). +``kunit_test_suite(...)`` is a macro which tells the linker to put the +specified test suite in a special linker section so that it can be run by KUnit +either after ``late_init``, or when the test module is loaded (if the test was +built as a module). -For more information on these types of things see the -Documentation/dev-tools/kunit/api/test.rst. +For more information, see Documentation/dev-tools/kunit/api/test.rst. + +Writing Tests For Other Architectures +------------------------------------- + +It is better to write tests that run on UML to tests that only run under a +particular architecture. It is better to write tests that run under QEMU or +another easy to obtain (and monetarily free) software environment to a specific +piece of hardware. + +Nevertheless, there are still valid reasons to write a test that is architecture +or hardware specific. For example, we might want to test code that really +belongs in ``arch/some-arch/*``. Even so, try to write the test so that it does +not depend on physical hardware. Some of our test cases may not need hardware, +only few tests actually require the hardware to test it. When hardware is not +available, instead of disabling tests, we can skip them. + +Now that we have narrowed down exactly what bits are hardware specific, the +actual procedure for writing and running the tests is same as writing normal +KUnit tests. + +.. important:: + We may have to reset hardware state. If this is not possible, we may only + be able to run one test case per invocation. + +.. TODO(brendanhiggins@google.com): Add an actual example of an architecture- + dependent KUnit test. Common Patterns =============== @@ -226,43 +194,39 @@ Common Patterns Isolating Behavior ------------------ -The most important aspect of unit testing that other forms of testing do not -provide is the ability to limit the amount of code under test to a single unit. -In practice, this is only possible by being able to control what code gets run -when the unit under test calls a function and this is usually accomplished -through some sort of indirection where a function is exposed as part of an API -such that the definition of that function can be changed without affecting the -rest of the code base. In the kernel this primarily comes from two constructs, -classes, structs that contain function pointers that are provided by the -implementer, and architecture-specific functions which have definitions selected -at compile time. +Unit testing limits the amount of code under test to a single unit. It controls +what code gets run when the unit under test calls a function. Where a function +is exposed as part of an API such that the definition of that function can be +changed without affecting the rest of the code base. In the kernel, this comes +from two constructs: classes, which are structs that contain function pointers +provided by the implementer, and architecture-specific functions, which have +definitions selected at compile time. Classes ~~~~~~~ Classes are not a construct that is built into the C programming language; -however, it is an easily derived concept. Accordingly, pretty much every project -that does not use a standardized object oriented library (like GNOME's GObject) -has their own slightly different way of doing object oriented programming; the -Linux kernel is no exception. +however, it is an easily derived concept. Accordingly, in most cases, every +project that does not use a standardized object oriented library (like GNOME's +GObject) has their own slightly different way of doing object oriented +programming; the Linux kernel is no exception. The central concept in kernel object oriented programming is the class. In the kernel, a *class* is a struct that contains function pointers. This creates a contract between *implementers* and *users* since it forces them to use the -same function signature without having to call the function directly. In order -for it to truly be a class, the function pointers must specify that a pointer -to the class, known as a *class handle*, be one of the parameters; this makes -it possible for the member functions (also known as *methods*) to have access -to member variables (more commonly known as *fields*) allowing the same -implementation to have multiple *instances*. +same function signature without having to call the function directly. To be a +class, the function pointers must specify that a pointer to the class, known as +a *class handle*, be one of the parameters. Thus the member functions (also +known as *methods*) have access to member variables (also known as *fields*) +allowing the same implementation to have multiple *instances*. -Typically a class can be *overridden* by *child classes* by embedding the -*parent class* in the child class. Then when a method provided by the child -class is called, the child implementation knows that the pointer passed to it is -of a parent contained within the child; because of this, the child can compute -the pointer to itself because the pointer to the parent is always a fixed offset -from the pointer to the child; this offset is the offset of the parent contained -in the child struct. For example: +A class can be *overridden* by *child classes* by embedding the *parent class* +in the child class. Then when the child class *method* is called, the child +implementation knows that the pointer passed to it is of a parent contained +within the child. Thus, the child can compute the pointer to itself because the +pointer to the parent is always a fixed offset from the pointer to the child. +This offset is the offset of the parent contained in the child struct. For +example: .. code-block:: c @@ -290,8 +254,8 @@ in the child struct. For example: self->width = width; } -In this example (as in most kernel code) the operation of computing the pointer -to the child from the pointer to the parent is done by ``container_of``. +In this example, computing the pointer to the child from the pointer to the +parent is done by ``container_of``. Faking Classes ~~~~~~~~~~~~~~ @@ -300,14 +264,11 @@ In order to unit test a piece of code that calls a method in a class, the behavior of the method must be controllable, otherwise the test ceases to be a unit test and becomes an integration test. -A fake just provides an implementation of a piece of code that is different than -what runs in a production instance, but behaves identically from the standpoint -of the callers; this is usually done to replace a dependency that is hard to -deal with, or is slow. - -A good example for this might be implementing a fake EEPROM that just stores the -"contents" in an internal buffer. For example, let's assume we have a class that -represents an EEPROM: +A fake class implements a piece of code that is different than what runs in a +production instance, but behaves identical from the standpoint of the callers. +This is done to replace a dependency that is hard to deal with, or is slow. For +example, implementing a fake EEPROM that stores the "contents" in an +internal buffer. Assume we have a class that represents an EEPROM: .. code-block:: c @@ -316,7 +277,7 @@ represents an EEPROM: ssize_t (*write)(struct eeprom *this, size_t offset, const char *buffer, size_t count); }; -And we want to test some code that buffers writes to the EEPROM: +And we want to test code that buffers writes to the EEPROM: .. code-block:: c @@ -329,7 +290,7 @@ And we want to test some code that buffers writes to the EEPROM: struct eeprom_buffer *new_eeprom_buffer(struct eeprom *eeprom); void destroy_eeprom_buffer(struct eeprom *eeprom); -We can easily test this code by *faking out* the underlying EEPROM: +We can test this code by *faking out* the underlying EEPROM: .. code-block:: c @@ -456,14 +417,14 @@ We can now use it to test ``struct eeprom_buffer``: destroy_eeprom_buffer(ctx->eeprom_buffer); } -Testing against multiple inputs +Testing Against Multiple Inputs ------------------------------- -Testing just a few inputs might not be enough to have confidence that the code -works correctly, e.g. for a hash function. +Testing just a few inputs is not enough to ensure that the code works correctly, +for example: testing a hash function. -In such cases, it can be helpful to have a helper macro or function, e.g. this -fictitious example for ``sha1sum(1)`` +We can write a helper macro or function. The function is called for each input. +For example, to test ``sha1sum(1)``, we can write: .. code-block:: c @@ -475,16 +436,15 @@ fictitious example for ``sha1sum(1)`` TEST_SHA1("hello world", "2aae6c35c94fcfb415dbe95f408b9ce91ee846ed"); TEST_SHA1("hello world!", "430ce34d020724ed75a196dfc2ad67c77772d169"); +Note the use of the ``_MSG`` version of ``KUNIT_EXPECT_STREQ`` to print a more +detailed error and make the assertions clearer within the helper macros. -Note the use of ``KUNIT_EXPECT_STREQ_MSG`` to give more context when it fails -and make it easier to track down. (Yes, in this example, ``want`` is likely -going to be unique enough on its own). +The ``_MSG`` variants are useful when the same expectation is called multiple +times (in a loop or helper function) and thus the line number is not enough to +identify what failed, as shown below. -The ``_MSG`` variants are even more useful when the same expectation is called -multiple times (in a loop or helper function) and thus the line number isn't -enough to identify what failed, like below. - -In some cases, it can be helpful to write a *table-driven test* instead, e.g. +In complicated cases, we recommend using a *table-driven test* compared to the +helper macro variation, for example: .. code-block:: c @@ -513,17 +473,18 @@ In some cases, it can be helpful to write a *table-driven test* instead, e.g. } -There's more boilerplate involved, but it can: +There is more boilerplate code involved, but it can: -* be more readable when there are multiple inputs/outputs thanks to field names, +* be more readable when there are multiple inputs/outputs (due to field names). - * E.g. see ``fs/ext4/inode-test.c`` for an example of both. -* reduce duplication if test cases can be shared across multiple tests. + * For example, see ``fs/ext4/inode-test.c``. - * E.g. if we wanted to also test ``sha256sum``, we could add a ``sha256`` +* reduce duplication if test cases are shared across multiple tests. + + * For example: if we want to test ``sha256sum``, we could add a ``sha256`` field and reuse ``cases``. -* be converted to a "parameterized test", see below. +* be converted to a "parameterized test". Parameterized Testing ~~~~~~~~~~~~~~~~~~~~~ @@ -531,7 +492,7 @@ Parameterized Testing The table-driven testing pattern is common enough that KUnit has special support for it. -Reusing the same ``cases`` array from above, we can write the test as a +By reusing the same ``cases`` array from above, we can write the test as a "parameterized test" with the following. .. code-block:: c @@ -582,193 +543,160 @@ Reusing the same ``cases`` array from above, we can write the test as a .. _kunit-on-non-uml: -KUnit on non-UML architectures -============================== +Exiting Early on Failed Expectations +------------------------------------ -By default KUnit uses UML as a way to provide dependencies for code under test. -Under most circumstances KUnit's usage of UML should be treated as an -implementation detail of how KUnit works under the hood. Nevertheless, there -are instances where being able to run architecture-specific code or test -against real hardware is desirable. For these reasons KUnit supports running on -other architectures. +We can use ``KUNIT_EXPECT_EQ`` to mark the test as failed and continue +execution. In some cases, it is unsafe to continue. We can use the +``KUNIT_ASSERT`` variant to exit on failure. -Running existing KUnit tests on non-UML architectures ------------------------------------------------------ +.. code-block:: c -There are some special considerations when running existing KUnit tests on -non-UML architectures: + void example_test_user_alloc_function(struct kunit *test) + { + void *object = alloc_some_object_for_me(); -* Hardware may not be deterministic, so a test that always passes or fails - when run under UML may not always do so on real hardware. -* Hardware and VM environments may not be hermetic. KUnit tries its best to - provide a hermetic environment to run tests; however, it cannot manage state - that it doesn't know about outside of the kernel. Consequently, tests that - may be hermetic on UML may not be hermetic on other architectures. -* Some features and tooling may not be supported outside of UML. -* Hardware and VMs are slower than UML. + /* Make sure we got a valid pointer back. */ + KUNIT_ASSERT_NOT_ERR_OR_NULL(test, object); + do_something_with_object(object); + } -None of these are reasons not to run your KUnit tests on real hardware; they are -only things to be aware of when doing so. +Allocating Memory +----------------- -Currently, the KUnit Wrapper (``tools/testing/kunit/kunit.py``) (aka -kunit_tool) only fully supports running tests inside of UML and QEMU; however, -this is only due to our own time limitations as humans working on KUnit. It is -entirely possible to support other emulators and even actual hardware, but for -now QEMU and UML is what is fully supported within the KUnit Wrapper. Again, to -be clear, this is just the Wrapper. The actualy KUnit tests and the KUnit -library they are written in is fully architecture agnostic and can be used in -virtually any setup, you just won't have the benefit of typing a single command -out of the box and having everything magically work perfectly. +Where you might use ``kzalloc``, you can instead use ``kunit_kzalloc`` as KUnit +will then ensure that the memory is freed once the test completes. -Again, all core KUnit framework features are fully supported on all -architectures, and using them is straightforward: Most popular architectures -are supported directly in the KUnit Wrapper via QEMU. Currently, supported -architectures on QEMU include: +This is useful because it lets us use the ``KUNIT_ASSERT_EQ`` macros to exit +early from a test without having to worry about remembering to call ``kfree``. +For example: -* i386 -* x86_64 -* arm -* arm64 -* alpha -* powerpc -* riscv -* s390 -* sparc +.. code-block:: c -In order to run KUnit tests on one of these architectures via QEMU with the -KUnit wrapper, all you need to do is specify the flags ``--arch`` and -``--cross_compile`` when invoking the KUnit Wrapper. For example, we could run -the default KUnit tests on ARM in the following manner (assuming we have an ARM -toolchain installed): + void example_test_allocation(struct kunit *test) + { + char *buffer = kunit_kzalloc(test, 16, GFP_KERNEL); + /* Ensure allocation succeeded. */ + KUNIT_ASSERT_NOT_ERR_OR_NULL(test, buffer); -.. code-block:: bash - - tools/testing/kunit/kunit.py run --timeout=60 --jobs=12 --arch=arm --cross_compile=arm-linux-gnueabihf- - -Alternatively, if you want to run your tests on real hardware or in some other -emulation environment, all you need to do is to take your kunitconfig, your -Kconfig options for the tests you would like to run, and merge them into -whatever config your are using for your platform. That's it! - -For example, let's say you have the following kunitconfig: - -.. code-block:: none - - CONFIG_KUNIT=y - CONFIG_KUNIT_EXAMPLE_TEST=y - -If you wanted to run this test on an x86 VM, you might add the following config -options to your ``.config``: - -.. code-block:: none - - CONFIG_KUNIT=y - CONFIG_KUNIT_EXAMPLE_TEST=y - CONFIG_SERIAL_8250=y - CONFIG_SERIAL_8250_CONSOLE=y - -All these new options do is enable support for a common serial console needed -for logging. - -Next, you could build a kernel with these tests as follows: + KUNIT_ASSERT_STREQ(test, buffer, ""); + } -.. code-block:: bash +Testing Static Functions +------------------------ - make ARCH=x86 olddefconfig - make ARCH=x86 +If we do not want to expose functions or variables for testing, one option is to +conditionally ``#include`` the test file at the end of your .c file. For +example: -Once you have built a kernel, you could run it on QEMU as follows: +.. code-block:: c -.. code-block:: bash + /* In my_file.c */ - qemu-system-x86_64 -enable-kvm \ - -m 1024 \ - -kernel arch/x86_64/boot/bzImage \ - -append 'console=ttyS0' \ - --nographic + static int do_interesting_thing(); -Interspersed in the kernel logs you might see the following: + #ifdef CONFIG_MY_KUNIT_TEST + #include "my_kunit_test.c" + #endif -.. code-block:: none +Injecting Test-Only Code +------------------------ - TAP version 14 - # Subtest: example - 1..1 - # example_simple_test: initializing - ok 1 - example_simple_test - ok 1 - example +Similar to as shown above, we can add test-specific logic. For example: -Congratulations, you just ran a KUnit test on the x86 architecture! +.. code-block:: c -In a similar manner, kunit and kunit tests can also be built as modules, -so if you wanted to run tests in this way you might add the following config -options to your ``.config``: + /* In my_file.h */ -.. code-block:: none + #ifdef CONFIG_MY_KUNIT_TEST + /* Defined in my_kunit_test.c */ + void test_only_hook(void); + #else + void test_only_hook(void) { } + #endif - CONFIG_KUNIT=m - CONFIG_KUNIT_EXAMPLE_TEST=m +This test-only code can be made more useful by accessing the current ``kunit_test`` +as shown in next section: *Accessing The Current Test*. -Once the kernel is built and installed, a simple +Accessing The Current Test +-------------------------- -.. code-block:: bash +In some cases, we need to call test-only code from outside the test file. +For example, see example in section *Injecting Test-Only Code* or if +we are providing a fake implementation of an ops struct. Using +``kunit_test`` field in ``task_struct``, we can access it via +``current->kunit_test``. - modprobe example-test +The example below includes how to implement "mocking": -...will run the tests. +.. code-block:: c -.. note:: - Note that you should make sure your test depends on ``KUNIT=y`` in Kconfig - if the test does not support module build. Otherwise, it will trigger - compile errors if ``CONFIG_KUNIT`` is ``m``. + #include /* for current */ -Writing new tests for other architectures ------------------------------------------ + struct test_data { + int foo_result; + int want_foo_called_with; + }; -The first thing you must do is ask yourself whether it is necessary to write a -KUnit test for a specific architecture, and then whether it is necessary to -write that test for a particular piece of hardware. In general, writing a test -that depends on having access to a particular piece of hardware or software (not -included in the Linux source repo) should be avoided at all costs. + static int fake_foo(int arg) + { + struct kunit *test = current->kunit_test; + struct test_data *test_data = test->priv; -Even if you only ever plan on running your KUnit test on your hardware -configuration, other people may want to run your tests and may not have access -to your hardware. If you write your test to run on UML, then anyone can run your -tests without knowing anything about your particular setup, and you can still -run your tests on your hardware setup just by compiling for your architecture. + KUNIT_EXPECT_EQ(test, test_data->want_foo_called_with, arg); + return test_data->foo_result; + } -.. important:: - Always prefer tests that run on UML to tests that only run under a particular - architecture, and always prefer tests that run under QEMU or another easy - (and monetarily free) to obtain software environment to a specific piece of - hardware. + static void example_simple_test(struct kunit *test) + { + /* Assume priv (private, a member used to pass test data from + * the init function) is allocated in the suite's .init */ + struct test_data *test_data = test->priv; -Nevertheless, there are still valid reasons to write an architecture or hardware -specific test: for example, you might want to test some code that really belongs -in ``arch/some-arch/*``. Even so, try your best to write the test so that it -does not depend on physical hardware: if some of your test cases don't need the -hardware, only require the hardware for tests that actually need it. + test_data->foo_result = 42; + test_data->want_foo_called_with = 1; -Now that you have narrowed down exactly what bits are hardware specific, the -actual procedure for writing and running the tests is pretty much the same as -writing normal KUnit tests. One special caveat is that you have to reset -hardware state in between test cases; if this is not possible, you may only be -able to run one test case per invocation. + /* In a real test, we'd probably pass a pointer to fake_foo somewhere + * like an ops struct, etc. instead of calling it directly. */ + KUNIT_EXPECT_EQ(test, fake_foo(1), 42); + } -.. TODO(brendanhiggins@google.com): Add an actual example of an architecture- - dependent KUnit test. +In this example, we are using the ``priv`` member of ``struct kunit`` as a way +of passing data to the test from the init function. In general ``priv`` is +pointer that can be used for any user data. This is preferred over static +variables, as it avoids concurrency issues. -KUnit debugfs representation -============================ -When kunit test suites are initialized, they create an associated directory -in ``/sys/kernel/debug/kunit/``. The directory contains one file +Had we wanted something more flexible, we could have used a named ``kunit_resource``. +Each test can have multiple resources which have string names providing the same +flexibility as a ``priv`` member, but also, for example, allowing helper +functions to create resources without conflicting with each other. It is also +possible to define a clean up function for each resource, making it easy to +avoid resource leaks. For more information, see Documentation/dev-tools/kunit/api/test.rst. -- results: "cat results" displays results of each test case and the results - of the entire suite for the last test run. +Failing The Current Test +------------------------ + +If we want to fail the current test, we can use ``kunit_fail_current_test(fmt, args...)`` +which is defined in ```` and does not require pulling in ````. +For example, we have an option to enable some extra debug checks on some data +structures as shown below: + +.. code-block:: c + + #include + + #ifdef CONFIG_EXTRA_DEBUG_CHECKS + static void validate_my_data(struct data *data) + { + if (is_valid(data)) + return; + + kunit_fail_current_test("data %p is invalid", data); + + /* Normal, non-KUnit, error reporting code here. */ + } + #else + static void my_debug_function(void) { } + #endif -The debugfs representation is primarily of use when kunit test suites are -run in a native environment, either as modules or builtin. Having a way -to display results like this is valuable as otherwise results can be -intermixed with other events in dmesg output. The maximum size of each -results file is KUNIT_LOG_SIZE bytes (defined in ``include/kunit/test.h``). diff --git a/Documentation/devicetree/bindings/gpio/gpio-samsung.txt b/Documentation/devicetree/bindings/gpio/gpio-samsung.txt deleted file mode 100644 index 5375625e8cd2..000000000000 --- a/Documentation/devicetree/bindings/gpio/gpio-samsung.txt +++ /dev/null @@ -1,41 +0,0 @@ -Samsung Exynos4 GPIO Controller - -Required properties: -- compatible: Compatible property value should be "samsung,exynos4-gpio>". - -- reg: Physical base address of the controller and length of memory mapped - region. - -- #gpio-cells: Should be 4. The syntax of the gpio specifier used by client nodes - should be the following with values derived from the SoC user manual. - <[phandle of the gpio controller node] - [pin number within the gpio controller] - [mux function] - [flags and pull up/down] - [drive strength]> - - Values for gpio specifier: - - Pin number: is a value between 0 to 7. - - Flags and Pull Up/Down: 0 - Pull Up/Down Disabled. - 1 - Pull Down Enabled. - 3 - Pull Up Enabled. - Bit 16 (0x00010000) - Input is active low. - - Drive Strength: 0 - 1x, - 1 - 3x, - 2 - 2x, - 3 - 4x - -- gpio-controller: Specifies that the node is a gpio controller. -- #address-cells: should be 1. -- #size-cells: should be 1. - -Example: - - gpa0: gpio-controller@11400000 { - #address-cells = <1>; - #size-cells = <1>; - compatible = "samsung,exynos4-gpio"; - reg = <0x11400000 0x20>; - #gpio-cells = <4>; - gpio-controller; - }; diff --git a/Documentation/devicetree/bindings/gpio/gpio-vf610.yaml b/Documentation/devicetree/bindings/gpio/gpio-vf610.yaml index 19738a457a58..e1359391d3a4 100644 --- a/Documentation/devicetree/bindings/gpio/gpio-vf610.yaml +++ b/Documentation/devicetree/bindings/gpio/gpio-vf610.yaml @@ -24,6 +24,9 @@ properties: - items: - const: fsl,imx7ulp-gpio - const: fsl,vf610-gpio + - items: + - const: fsl,imx8ulp-gpio + - const: fsl,imx7ulp-gpio reg: description: The first reg tuple represents the PORT module, the second tuple diff --git a/Documentation/devicetree/bindings/gpio/mstar,msc313-gpio.yaml b/Documentation/devicetree/bindings/gpio/mstar,msc313-gpio.yaml index fe1e1c63ffe3..18fe90387b87 100644 --- a/Documentation/devicetree/bindings/gpio/mstar,msc313-gpio.yaml +++ b/Documentation/devicetree/bindings/gpio/mstar,msc313-gpio.yaml @@ -14,7 +14,9 @@ properties: pattern: "^gpio@[0-9a-f]+$" compatible: - const: mstar,msc313-gpio + enum: + - mstar,msc313-gpio + - sstar,ssd20xd-gpio reg: maxItems: 1 diff --git a/Documentation/devicetree/bindings/gpio/nvidia,tegra186-gpio.txt b/Documentation/devicetree/bindings/gpio/nvidia,tegra186-gpio.txt deleted file mode 100644 index adff16c71d21..000000000000 --- a/Documentation/devicetree/bindings/gpio/nvidia,tegra186-gpio.txt +++ /dev/null @@ -1,165 +0,0 @@ -NVIDIA Tegra186 GPIO controllers - -Tegra186 contains two GPIO controllers; a main controller and an "AON" -controller. This binding document applies to both controllers. The register -layouts for the controllers share many similarities, but also some significant -differences. Hence, this document describes closely related but different -bindings and compatible values. - -The Tegra186 GPIO controller allows software to set the IO direction of, and -read/write the value of, numerous GPIO signals. Routing of GPIO signals to -package balls is under the control of a separate pin controller HW block. Two -major sets of registers exist: - -a) Security registers, which allow configuration of allowed access to the GPIO -register set. These registers exist in a single contiguous block of physical -address space. The size of this block, and the security features available, -varies between the different GPIO controllers. - -Access to this set of registers is not necessary in all circumstances. Code -that wishes to configure access to the GPIO registers needs access to these -registers to do so. Code which simply wishes to read or write GPIO data does not -need access to these registers. - -b) GPIO registers, which allow manipulation of the GPIO signals. In some GPIO -controllers, these registers are exposed via multiple "physical aliases" in -address space, each of which access the same underlying state. See the hardware -documentation for rationale. Any particular GPIO client is expected to access -just one of these physical aliases. - -Tegra HW documentation describes a unified naming convention for all GPIOs -implemented by the SoC. Each GPIO is assigned to a port, and a port may control -a number of GPIOs. Thus, each GPIO is named according to an alphabetical port -name and an integer GPIO name within the port. For example, GPIO_PA0, GPIO_PN6, -or GPIO_PCC3. - -The number of ports implemented by each GPIO controller varies. The number of -implemented GPIOs within each port varies. GPIO registers within a controller -are grouped and laid out according to the port they affect. - -The mapping from port name to the GPIO controller that implements that port, and -the mapping from port name to register offset within a controller, are both -extremely non-linear. The header file -describes the port-level mapping. In that file, the naming convention for ports -matches the HW documentation. The values chosen for the names are alphabetically -sorted within a particular controller. Drivers need to map between the DT GPIO -IDs and HW register offsets using a lookup table. - -Each GPIO controller can generate a number of interrupt signals. Each signal -represents the aggregate status for all GPIOs within a set of ports. Thus, the -number of interrupt signals generated by a controller varies as a rough function -of the number of ports it implements. Note that the HW documentation refers to -both the overall controller HW module and the sets-of-ports as "controllers". - -Each GPIO controller in fact generates multiple interrupts signals for each set -of ports. Each GPIO may be configured to feed into a specific one of the -interrupt signals generated by a set-of-ports. The intent is for each generated -signal to be routed to a different CPU, thus allowing different CPUs to each -handle subsets of the interrupts within a port. The status of each of these -per-port-set signals is reported via a separate register. Thus, a driver needs -to know which status register to observe. This binding currently defines no -configuration mechanism for this. By default, drivers should use register -GPIO_${port}_INTERRUPT_STATUS_G1_0. Future revisions to the binding could -define a property to configure this. - -Required properties: -- compatible - Array of strings. - One of: - - "nvidia,tegra186-gpio". - - "nvidia,tegra186-gpio-aon". - - "nvidia,tegra194-gpio". - - "nvidia,tegra194-gpio-aon". -- reg-names - Array of strings. - Contains a list of names for the register spaces described by the reg - property. May contain the following entries, in any order: - - "gpio": Mandatory. GPIO control registers. This may cover either: - a) The single physical alias that this OS should use. - b) All physical aliases that exist in the controller. This is - appropriate when the OS is responsible for managing assignment of - the physical aliases. - - "security": Optional. Security configuration registers. - Users of this binding MUST look up entries in the reg property by name, - using this reg-names property to do so. -- reg - Array of (physical base address, length) tuples. - Must contain one entry per entry in the reg-names property, in a matching - order. -- interrupts - Array of interrupt specifiers. - The interrupt outputs from the HW block, one per set of ports, in the - order the HW manual describes them. The number of entries required varies - depending on compatible value: - - "nvidia,tegra186-gpio": 6 entries. - - "nvidia,tegra186-gpio-aon": 1 entry. - - "nvidia,tegra194-gpio": 6 entries. - - "nvidia,tegra194-gpio-aon": 1 entry. -- gpio-controller - Boolean. - Marks the device node as a GPIO controller/provider. -- #gpio-cells - Single-cell integer. - Must be <2>. - Indicates how many cells are used in a consumer's GPIO specifier. - In the specifier: - - The first cell is the pin number. - See . - - The second cell contains flags: - - Bit 0 specifies polarity - - 0: Active-high (normal). - - 1: Active-low (inverted). -- interrupt-controller - Boolean. - Marks the device node as an interrupt controller/provider. -- #interrupt-cells - Single-cell integer. - Must be <2>. - Indicates how many cells are used in a consumer's interrupt specifier. - In the specifier: - - The first cell is the GPIO number. - See . - - The second cell is contains flags: - - Bits [3:0] indicate trigger type and level: - - 1: Low-to-high edge triggered. - - 2: High-to-low edge triggered. - - 4: Active high level-sensitive. - - 8: Active low level-sensitive. - Valid combinations are 1, 2, 3, 4, 8. - -Example: - -#include - -gpio@2200000 { - compatible = "nvidia,tegra186-gpio"; - reg-names = "security", "gpio"; - reg = - <0x0 0x2200000 0x0 0x10000>, - <0x0 0x2210000 0x0 0x10000>; - interrupts = - <0 47 IRQ_TYPE_LEVEL_HIGH>, - <0 50 IRQ_TYPE_LEVEL_HIGH>, - <0 53 IRQ_TYPE_LEVEL_HIGH>, - <0 56 IRQ_TYPE_LEVEL_HIGH>, - <0 59 IRQ_TYPE_LEVEL_HIGH>, - <0 180 IRQ_TYPE_LEVEL_HIGH>; - gpio-controller; - #gpio-cells = <2>; - interrupt-controller; - #interrupt-cells = <2>; -}; - -gpio@c2f0000 { - compatible = "nvidia,tegra186-gpio-aon"; - reg-names = "security", "gpio"; - reg = - <0x0 0xc2f0000 0x0 0x1000>, - <0x0 0xc2f1000 0x0 0x1000>; - interrupts = - <0 60 IRQ_TYPE_LEVEL_HIGH>; - gpio-controller; - #gpio-cells = <2>; - interrupt-controller; - #interrupt-cells = <2>; -}; diff --git a/Documentation/devicetree/bindings/gpio/nvidia,tegra186-gpio.yaml b/Documentation/devicetree/bindings/gpio/nvidia,tegra186-gpio.yaml new file mode 100644 index 000000000000..4ef06b2ff1ff --- /dev/null +++ b/Documentation/devicetree/bindings/gpio/nvidia,tegra186-gpio.yaml @@ -0,0 +1,214 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/gpio/nvidia,tegra186-gpio.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: NVIDIA Tegra GPIO Controller (Tegra186 and later) + +maintainers: + - Thierry Reding + - Jon Hunter + +description: | + Tegra186 contains two GPIO controllers; a main controller and an "AON" + controller. This binding document applies to both controllers. The register + layouts for the controllers share many similarities, but also some + significant differences. Hence, this document describes closely related but + different bindings and compatible values. + + The Tegra186 GPIO controller allows software to set the IO direction of, + and read/write the value of, numerous GPIO signals. Routing of GPIO signals + to package balls is under the control of a separate pin controller hardware + block. Two major sets of registers exist: + + a) Security registers, which allow configuration of allowed access to the + GPIO register set. These registers exist in a single contiguous block + of physical address space. The size of this block, and the security + features available, varies between the different GPIO controllers. + + Access to this set of registers is not necessary in all circumstances. + Code that wishes to configure access to the GPIO registers needs access + to these registers to do so. Code which simply wishes to read or write + GPIO data does not need access to these registers. + + b) GPIO registers, which allow manipulation of the GPIO signals. In some + GPIO controllers, these registers are exposed via multiple "physical + aliases" in address space, each of which access the same underlying + state. See the hardware documentation for rationale. Any particular + GPIO client is expected to access just one of these physical aliases. + + Tegra HW documentation describes a unified naming convention for all GPIOs + implemented by the SoC. Each GPIO is assigned to a port, and a port may + control a number of GPIOs. Thus, each GPIO is named according to an + alphabetical port name and an integer GPIO name within the port. For + example, GPIO_PA0, GPIO_PN6, or GPIO_PCC3. + + The number of ports implemented by each GPIO controller varies. The number + of implemented GPIOs within each port varies. GPIO registers within a + controller are grouped and laid out according to the port they affect. + + The mapping from port name to the GPIO controller that implements that + port, and the mapping from port name to register offset within a + controller, are both extremely non-linear. The header file + describes the port-level mapping. In + that file, the naming convention for ports matches the HW documentation. + The values chosen for the names are alphabetically sorted within a + particular controller. Drivers need to map between the DT GPIO IDs and HW + register offsets using a lookup table. + + Each GPIO controller can generate a number of interrupt signals. Each + signal represents the aggregate status for all GPIOs within a set of + ports. Thus, the number of interrupt signals generated by a controller + varies as a rough function of the number of ports it implements. Note + that the HW documentation refers to both the overall controller HW + module and the sets-of-ports as "controllers". + + Each GPIO controller in fact generates multiple interrupts signals for + each set of ports. Each GPIO may be configured to feed into a specific + one of the interrupt signals generated by a set-of-ports. The intent is + for each generated signal to be routed to a different CPU, thus allowing + different CPUs to each handle subsets of the interrupts within a port. + The status of each of these per-port-set signals is reported via a + separate register. Thus, a driver needs to know which status register to + observe. This binding currently defines no configuration mechanism for + this. By default, drivers should use register + GPIO_${port}_INTERRUPT_STATUS_G1_0. Future revisions to the binding could + define a property to configure this. + +properties: + compatible: + enum: + - nvidia,tegra186-gpio + - nvidia,tegra186-gpio-aon + - nvidia,tegra194-gpio + - nvidia,tegra194-gpio-aon + - nvidia,tegra234-gpio + - nvidia,tegra234-gpio-aon + + reg-names: + items: + - const: security + - const: gpio + minItems: 1 + + reg: + items: + - description: Security configuration registers. + - description: | + GPIO control registers. This may cover either: + + a) The single physical alias that this OS should use. + b) All physical aliases that exist in the controller. This is + appropriate when the OS is responsible for managing assignment + of the physical aliases. + minItems: 1 + + interrupts: + description: The interrupt outputs from the HW block, one per set of + ports, in the order the HW manual describes them. The number of entries + required varies depending on compatible value. + + gpio-controller: true + + "#gpio-cells": + description: | + Indicates how many cells are used in a consumer's GPIO specifier. In the + specifier: + + - The first cell is the pin number. + See . + - The second cell contains flags: + - Bit 0 specifies polarity + - 0: Active-high (normal). + - 1: Active-low (inverted). + const: 2 + + interrupt-controller: true + + "#interrupt-cells": + description: | + Indicates how many cells are used in a consumer's interrupt specifier. + In the specifier: + + - The first cell is the GPIO number. + See . + - The second cell is contains flags: + - Bits [3:0] indicate trigger type and level: + - 1: Low-to-high edge triggered. + - 2: High-to-low edge triggered. + - 4: Active high level-sensitive. + - 8: Active low level-sensitive. + + Valid combinations are 1, 2, 3, 4, 8. + const: 2 + +allOf: + - if: + properties: + compatible: + contains: + enum: + - nvidia,tegra186-gpio + - nvidia,tegra194-gpio + - nvidia,tegra234-gpio + then: + properties: + interrupts: + minItems: 6 + maxItems: 48 + + - if: + properties: + compatible: + contains: + enum: + - nvidia,tegra186-gpio-aon + - nvidia,tegra194-gpio-aon + - nvidia,tegra234-gpio-aon + then: + properties: + interrupts: + minItems: 1 + maxItems: 4 + +required: + - compatible + - reg + - reg-names + - interrupts + +additionalProperties: false + +examples: + - | + #include + + gpio@2200000 { + compatible = "nvidia,tegra186-gpio"; + reg-names = "security", "gpio"; + reg = <0x2200000 0x10000>, + <0x2210000 0x10000>; + interrupts = <0 47 IRQ_TYPE_LEVEL_HIGH>, + <0 50 IRQ_TYPE_LEVEL_HIGH>, + <0 53 IRQ_TYPE_LEVEL_HIGH>, + <0 56 IRQ_TYPE_LEVEL_HIGH>, + <0 59 IRQ_TYPE_LEVEL_HIGH>, + <0 180 IRQ_TYPE_LEVEL_HIGH>; + gpio-controller; + #gpio-cells = <2>; + interrupt-controller; + #interrupt-cells = <2>; + }; + + gpio@c2f0000 { + compatible = "nvidia,tegra186-gpio-aon"; + reg-names = "security", "gpio"; + reg = <0xc2f0000 0x1000>, + <0xc2f1000 0x1000>; + interrupts = <0 60 IRQ_TYPE_LEVEL_HIGH>; + gpio-controller; + #gpio-cells = <2>; + interrupt-controller; + #interrupt-cells = <2>; + }; diff --git a/Documentation/devicetree/bindings/gpio/nvidia,tegra20-gpio.txt b/Documentation/devicetree/bindings/gpio/nvidia,tegra20-gpio.txt deleted file mode 100644 index 023c9526e5f8..000000000000 --- a/Documentation/devicetree/bindings/gpio/nvidia,tegra20-gpio.txt +++ /dev/null @@ -1,40 +0,0 @@ -NVIDIA Tegra GPIO controller - -Required properties: -- compatible : "nvidia,tegra-gpio" -- reg : Physical base address and length of the controller's registers. -- interrupts : The interrupt outputs from the controller. For Tegra20, - there should be 7 interrupts specified, and for Tegra30, there should - be 8 interrupts specified. -- #gpio-cells : Should be two. The first cell is the pin number and the - second cell is used to specify optional parameters: - - bit 0 specifies polarity (0 for normal, 1 for inverted) -- gpio-controller : Marks the device node as a GPIO controller. -- #interrupt-cells : Should be 2. - The first cell is the GPIO number. - The second cell is used to specify flags: - bits[3:0] trigger type and level flags: - 1 = low-to-high edge triggered. - 2 = high-to-low edge triggered. - 4 = active high level-sensitive. - 8 = active low level-sensitive. - Valid combinations are 1, 2, 3, 4, 8. -- interrupt-controller : Marks the device node as an interrupt controller. - -Example: - -gpio: gpio@6000d000 { - compatible = "nvidia,tegra20-gpio"; - reg = < 0x6000d000 0x1000 >; - interrupts = < 0 32 0x04 - 0 33 0x04 - 0 34 0x04 - 0 35 0x04 - 0 55 0x04 - 0 87 0x04 - 0 89 0x04 >; - #gpio-cells = <2>; - gpio-controller; - #interrupt-cells = <2>; - interrupt-controller; -}; diff --git a/Documentation/devicetree/bindings/gpio/nvidia,tegra20-gpio.yaml b/Documentation/devicetree/bindings/gpio/nvidia,tegra20-gpio.yaml new file mode 100644 index 000000000000..94b51749ee76 --- /dev/null +++ b/Documentation/devicetree/bindings/gpio/nvidia,tegra20-gpio.yaml @@ -0,0 +1,110 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/gpio/nvidia,tegra20-gpio.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: NVIDIA Tegra GPIO Controller (Tegra20 - Tegra210) + +maintainers: + - Thierry Reding + - Jon Hunter + +properties: + compatible: + oneOf: + - enum: + - nvidia,tegra20-gpio + - nvidia,tegra30-gpio + + - items: + - enum: + - nvidia,tegra114-gpio + - nvidia,tegra124-gpio + - nvidia,tegra210-gpio + - const: nvidia,tegra30-gpio + + reg: + maxItems: 1 + + interrupts: + description: The interrupt outputs from the controller. For Tegra20, + there should be 7 interrupts specified, and for Tegra30, there should + be 8 interrupts specified. + + "#gpio-cells": + description: The first cell is the pin number and the second cell is used + to specify the GPIO polarity (0 = active high, 1 = active low). + const: 2 + + gpio-controller: true + + gpio-ranges: + maxItems: 1 + + "#interrupt-cells": + description: | + Should be 2. The first cell is the GPIO number. The second cell is + used to specify flags: + + bits[3:0] trigger type and level flags: + 1 = low-to-high edge triggered. + 2 = high-to-low edge triggered. + 4 = active high level-sensitive. + 8 = active low level-sensitive. + + Valid combinations are 1, 2, 3, 4, 8. + const: 2 + + interrupt-controller: true + +allOf: + - if: + properties: + compatible: + contains: + const: nvidia,tegra30-gpio + then: + properties: + interrupts: + minItems: 8 + maxItems: 8 + else: + properties: + interrupts: + minItems: 7 + maxItems: 7 + +required: + - compatible + - reg + - interrupts + - "#gpio-cells" + - gpio-controller + - "#interrupt-cells" + - interrupt-controller + +additionalProperties: + type: object + required: + - gpio-hog + +examples: + - | + #include + + gpio: gpio@6000d000 { + compatible = "nvidia,tegra20-gpio"; + reg = <0x6000d000 0x1000>; + interrupts = , + , + , + , + , + , + ; + #gpio-cells = <2>; + gpio-controller; + #interrupt-cells = <2>; + interrupt-controller; + }; diff --git a/Documentation/devicetree/bindings/gpio/sifive,gpio.yaml b/Documentation/devicetree/bindings/gpio/sifive,gpio.yaml index c2902aac2514..e04349567eeb 100644 --- a/Documentation/devicetree/bindings/gpio/sifive,gpio.yaml +++ b/Documentation/devicetree/bindings/gpio/sifive,gpio.yaml @@ -77,7 +77,8 @@ examples: gpio@10060000 { compatible = "sifive,fu540-c000-gpio", "sifive,gpio0"; interrupt-parent = <&plic>; - interrupts = <7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22>; + interrupts = <7>, <8>, <9>, <10>, <11>, <12>, <13>, <14>, <15>, <16>, + <17>, <18>, <19>, <20>, <21>, <22>; reg = <0x10060000 0x1000>; clocks = <&tlclk PRCI_CLK_TLCLK>; gpio-controller; diff --git a/Documentation/devicetree/bindings/hwmon/ntc-thermistor.yaml b/Documentation/devicetree/bindings/hwmon/ntc-thermistor.yaml index 9e77cee07dbc..3d3b139a91a2 100644 --- a/Documentation/devicetree/bindings/hwmon/ntc-thermistor.yaml +++ b/Documentation/devicetree/bindings/hwmon/ntc-thermistor.yaml @@ -76,6 +76,7 @@ properties: - const: murata,ncp15wl333 - const: murata,ncp03wf104 - const: murata,ncp15xh103 + - const: samsung,1404-001221 # Deprecated "ntp," compatible strings - const: ntc,ncp15wb473 deprecated: true diff --git a/Documentation/devicetree/bindings/hwmon/ti,ina2xx.yaml b/Documentation/devicetree/bindings/hwmon/ti,ina2xx.yaml index 6f0443322a36..47af97bb4ced 100644 --- a/Documentation/devicetree/bindings/hwmon/ti,ina2xx.yaml +++ b/Documentation/devicetree/bindings/hwmon/ti,ina2xx.yaml @@ -26,6 +26,7 @@ properties: - ti,ina226 - ti,ina230 - ti,ina231 + - ti,ina238 reg: maxItems: 1 @@ -35,6 +36,27 @@ properties: Shunt resistor value in micro-Ohm. $ref: /schemas/types.yaml#/definitions/uint32 + ti,shunt-gain: + description: | + Programmable gain divisor for the shunt voltage accuracy and range. This + property only applies to devices that have configurable PGA/ADCRANGE. The + gain value is used configure the gain and to convert the shunt voltage, + current and power register values when reading measurements from the + device. + + For devices that have a configurable PGA (e.g. INA209, INA219, INA220), + the gain value maps directly with the PG bits of the config register. + + For devices that have ADCRANGE configuration (e.g. INA238) a shunt-gain + value of 1 maps to ADCRANGE=1 where no gain divisor is applied to the + shunt voltage, and a value of 4 maps to ADCRANGE=0 such that a wider + voltage range is used. + + The default value is device dependent, and is defined by the reset value + of PGA/ADCRANGE in the respective configuration registers. + $ref: /schemas/types.yaml#/definitions/uint32 + enum: [1, 2, 4, 8] + required: - compatible - reg diff --git a/Documentation/devicetree/bindings/input/hid-over-i2c.txt b/Documentation/devicetree/bindings/input/hid-over-i2c.txt index c76bafaf98d2..34c43d3bddfd 100644 --- a/Documentation/devicetree/bindings/input/hid-over-i2c.txt +++ b/Documentation/devicetree/bindings/input/hid-over-i2c.txt @@ -32,6 +32,8 @@ device-specific compatible properties, which should be used in addition to the - vdd-supply: phandle of the regulator that provides the supply voltage. - post-power-on-delay-ms: time required by the device after enabling its regulators or powering it on, before it is ready for communication. +- touchscreen-inverted-x: See touchscreen.txt +- touchscreen-inverted-y: See touchscreen.txt Example: diff --git a/Documentation/devicetree/bindings/memory-controllers/ti,gpmc.yaml b/Documentation/devicetree/bindings/memory-controllers/ti,gpmc.yaml index 25b42d68f9b3..64dc9d398d9a 100644 --- a/Documentation/devicetree/bindings/memory-controllers/ti,gpmc.yaml +++ b/Documentation/devicetree/bindings/memory-controllers/ti,gpmc.yaml @@ -23,13 +23,20 @@ properties: items: - enum: - ti,am3352-gpmc + - ti,am64-gpmc - ti,omap2420-gpmc - ti,omap2430-gpmc - ti,omap3430-gpmc - ti,omap4430-gpmc reg: - maxItems: 1 + minItems: 1 + maxItems: 2 + + reg-names: + items: + - const: cfg + - const: data interrupts: maxItems: 1 @@ -44,6 +51,9 @@ properties: items: - const: fck + power-domains: + maxItems: 1 + dmas: items: - description: DMA channel for GPMC NAND prefetch @@ -133,6 +143,17 @@ required: - "#address-cells" - "#size-cells" +allOf: + - if: + properties: + compatible: + contains: + const: ti,am64-gpmc + then: + required: + - reg-names + - power-domains + additionalProperties: false examples: diff --git a/Documentation/devicetree/bindings/mfd/bd9571mwv.txt b/Documentation/devicetree/bindings/mfd/bd9571mwv.txt deleted file mode 100644 index 1d6413e96c37..000000000000 --- a/Documentation/devicetree/bindings/mfd/bd9571mwv.txt +++ /dev/null @@ -1,69 +0,0 @@ -* ROHM BD9571MWV/BD9574MWF Power Management Integrated Circuit (PMIC) bindings - -Required properties: - - compatible : Should be "rohm,bd9571mwv" or "rohm,bd9574mwf". - - reg : I2C slave address. - - interrupts : The interrupt line the device is connected to. - - interrupt-controller : Marks the device node as an interrupt controller. - - #interrupt-cells : The number of cells to describe an IRQ, should be 2. - The first cell is the IRQ number. - The second cell is the flags, encoded as trigger - masks from ../interrupt-controller/interrupts.txt. - - gpio-controller : Marks the device node as a GPIO Controller. - - #gpio-cells : Should be two. The first cell is the pin number and - the second cell is used to specify flags. - See ../gpio/gpio.txt for more information. - - regulators: : List of child nodes that specify the regulator - initialization data. Child nodes must be named - after their hardware counterparts: - - vd09 - - vd18 - - vd25 - - vd33 - - dvfs - Each child node is defined using the standard - binding for regulators. - -Optional properties: - - rohm,ddr-backup-power : Value to use for DDR-Backup Power (default 0). - This is a bitmask that specifies which DDR power - rails need to be kept powered when backup mode is - entered, for system suspend: - - bit 0: DDR0 - - bit 1: DDR1 - - bit 2: DDR0C - - bit 3: DDR1C - These bits match the KEEPON_DDR* bits in the - documentation for the "BKUP Mode Cnt" register. - - rohm,rstbmode-level: The RSTB signal is configured for level mode, to - accommodate a toggle power switch (the RSTBMODE pin is - strapped low). - - rohm,rstbmode-pulse: The RSTB signal is configured for pulse mode, to - accommodate a momentary power switch (the RSTBMODE pin - is strapped high). - The two properties above are mutually exclusive. - -Example: - - pmic: pmic@30 { - compatible = "rohm,bd9571mwv"; - reg = <0x30>; - interrupt-parent = <&gpio2>; - interrupts = <0 IRQ_TYPE_LEVEL_LOW>; - interrupt-controller; - #interrupt-cells = <2>; - gpio-controller; - #gpio-cells = <2>; - rohm,ddr-backup-power = <0xf>; - rohm,rstbmode-pulse; - - regulators { - dvfs: dvfs { - regulator-name = "dvfs"; - regulator-min-microvolt = <750000>; - regulator-max-microvolt = <1030000>; - regulator-boot-on; - regulator-always-on; - }; - }; - }; diff --git a/Documentation/devicetree/bindings/mfd/brcm,twd.yaml b/Documentation/devicetree/bindings/mfd/brcm,twd.yaml new file mode 100644 index 000000000000..634526f790b8 --- /dev/null +++ b/Documentation/devicetree/bindings/mfd/brcm,twd.yaml @@ -0,0 +1,61 @@ +# SPDX-License-Identifier: GPL-2.0-only OR BSD-2-Clause +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/mfd/brcm,twd.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Broadcom's Timer-Watchdog (aka TWD) + +maintainers: + - Rafał Miłecki + +description: | + Broadcom has a Timer-Watchdog block used in multiple SoCs (e.g., BCM4908, + BCM63xx, BCM7038). There are few variants available (they differ slightly in + registers layout). This block consists of: timers, watchdog and optionally a + software reset handler. + +properties: + compatible: + items: + - enum: + - brcm,bcm4908-twd + - brcm,bcm7038-twd + - const: simple-mfd + - const: syscon + + reg: + maxItems: 1 + + ranges: true + + "#address-cells": + const: 1 + + "#size-cells": + const: 1 + +patternProperties: + '^watchdog@[a-f0-9]+$': + $ref: /schemas/watchdog/brcm,bcm7038-wdt.yaml + +additionalProperties: false + +required: + - reg + +examples: + - | + timer-mfd@ff800400 { + compatible = "brcm,bcm4908-twd", "simple-mfd", "syscon"; + reg = <0xff800400 0x4c>; + ranges = <0x00000000 0xff800400 0x4c>; + + #address-cells = <1>; + #size-cells = <1>; + + watchdog@28 { + compatible = "brcm,bcm7038-wdt"; + reg = <0x28 0x8>; + }; + }; diff --git a/Documentation/devicetree/bindings/mfd/da9063.txt b/Documentation/devicetree/bindings/mfd/da9063.txt index 8da879935c59..91b79a21d403 100644 --- a/Documentation/devicetree/bindings/mfd/da9063.txt +++ b/Documentation/devicetree/bindings/mfd/da9063.txt @@ -1,6 +1,6 @@ * Dialog DA9063/DA9063L Power Management Integrated Circuit (PMIC) -DA9093 consists of a large and varied group of sub-devices (I2C Only): +DA9063 consists of a large and varied group of sub-devices (I2C Only): Device Supply Names Description ------ ------------ ----------- diff --git a/Documentation/devicetree/bindings/mfd/google,cros-ec.yaml b/Documentation/devicetree/bindings/mfd/google,cros-ec.yaml index d793dd0316b7..0faa4da6c7c8 100644 --- a/Documentation/devicetree/bindings/mfd/google,cros-ec.yaml +++ b/Documentation/devicetree/bindings/mfd/google,cros-ec.yaml @@ -59,7 +59,7 @@ properties: whether this nvram is present or not. type: boolean - mtk,rpmsg-name: + mediatek,rpmsg-name: description: Must be defined if the cros-ec is a rpmsg device for a Mediatek ARM Cortex M4 Co-processor. Contains the name pf the rpmsg diff --git a/Documentation/devicetree/bindings/mfd/max77686.txt b/Documentation/devicetree/bindings/mfd/max77686.txt deleted file mode 100644 index 4447d074894a..000000000000 --- a/Documentation/devicetree/bindings/mfd/max77686.txt +++ /dev/null @@ -1,26 +0,0 @@ -Maxim MAX77686 multi-function device - -MAX77686 is a Multifunction device with PMIC, RTC and Charger on chip. It is -interfaced to host controller using i2c interface. PMIC and Charger submodules -are addressed using same i2c slave address whereas RTC submodule uses -different i2c slave address,presently for which we are statically creating i2c -client while probing.This document describes the binding for mfd device and -PMIC submodule. - -Bindings for the built-in 32k clock generator block and -regulators are defined in ../clk/maxim,max77686.txt and -../regulator/max77686.txt respectively. - -Required properties: -- compatible : Must be "maxim,max77686"; -- reg : Specifies the i2c slave address of PMIC block. -- interrupts : This i2c device has an IRQ line connected to the main SoC. - -Example: - - max77686: pmic@9 { - compatible = "maxim,max77686"; - interrupt-parent = <&wakeup_eint>; - interrupts = <26 IRQ_TYPE_LEVEL_LOW>; - reg = <0x09>; - }; diff --git a/Documentation/devicetree/bindings/mfd/maxim,max77686.yaml b/Documentation/devicetree/bindings/mfd/maxim,max77686.yaml new file mode 100644 index 000000000000..859655a789c3 --- /dev/null +++ b/Documentation/devicetree/bindings/mfd/maxim,max77686.yaml @@ -0,0 +1,132 @@ +# SPDX-License-Identifier: GPL-2.0-only OR BSD-2-Clause +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/mfd/maxim,max77686.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Maxim MAX77686 Power Management IC + +maintainers: + - Chanwoo Choi + - Krzysztof Kozlowski + +description: | + This is a part of device tree bindings for Maxim MAX77686 Power Management + Integrated Circuit (PMIC). + + The Maxim MAX77686 is a Power Management IC which includes voltage and + current regulators, RTC and clock outputs. + + The MAX77686 provides three 32.768khz clock outputs that can be controlled + (gated/ungated) over I2C. The clock IDs are defined as preprocessor macros + in dt-bindings/clock/maxim,max77686.h. + +properties: + compatible: + const: maxim,max77686 + + '#clock-cells': + const: 1 + + interrupts: + maxItems: 1 + + reg: + maxItems: 1 + + voltage-regulators: + $ref: ../regulator/maxim,max77686.yaml + description: + List of child nodes that specify the regulators. + + wakeup-source: true + +required: + - compatible + - '#clock-cells' + - reg + +additionalProperties: false + +examples: + - | + #include + #include + + i2c { + #address-cells = <1>; + #size-cells = <0>; + + max77686: pmic@9 { + compatible = "maxim,max77686"; + reg = <0x09>; + + interrupt-parent = <&gpx0>; + interrupts = <7 IRQ_TYPE_LEVEL_LOW>; + pinctrl-0 = <&max77686_irq>; + pinctrl-names = "default"; + wakeup-source; + #clock-cells = <1>; + + voltage-regulators { + LDO1 { + regulator-name = "VALIVE_1.0V_AP"; + regulator-min-microvolt = <1000000>; + regulator-max-microvolt = <1000000>; + regulator-always-on; + }; + + LDO2 { + regulator-name = "VM1M2_1.2V_AP"; + regulator-min-microvolt = <1200000>; + regulator-max-microvolt = <1200000>; + regulator-always-on; + regulator-state-mem { + regulator-on-in-suspend; + }; + }; + + // ... + + LDO22 { + regulator-name = "VMEM_VDD_2.8V"; + regulator-min-microvolt = <2800000>; + regulator-max-microvolt = <2800000>; + maxim,ena-gpios = <&gpk0 2 GPIO_ACTIVE_HIGH>; + }; + + // ... + + BUCK1 { + regulator-name = "VDD_MIF"; + regulator-min-microvolt = <850000>; + regulator-max-microvolt = <1100000>; + regulator-always-on; + regulator-boot-on; + regulator-state-mem { + regulator-off-in-suspend; + }; + }; + + BUCK2 { + regulator-name = "VDD_ARM"; + regulator-min-microvolt = <850000>; + regulator-max-microvolt = <1500000>; + regulator-always-on; + regulator-boot-on; + regulator-state-mem { + regulator-on-in-suspend; + }; + }; + + // ... + + BUCK9 { + regulator-name = "CAM_ISP_CORE_1.2V"; + regulator-min-microvolt = <1000000>; + regulator-max-microvolt = <1200000>; + maxim,ena-gpios = <&gpm0 3 GPIO_ACTIVE_HIGH>; + }; + }; + }; + }; diff --git a/Documentation/devicetree/bindings/mfd/rohm,bd70528-pmic.txt b/Documentation/devicetree/bindings/mfd/rohm,bd70528-pmic.txt deleted file mode 100644 index 386eec06cf08..000000000000 --- a/Documentation/devicetree/bindings/mfd/rohm,bd70528-pmic.txt +++ /dev/null @@ -1,102 +0,0 @@ -* ROHM BD70528 Power Management Integrated Circuit bindings - -BD70528MWV is an ultra-low quiescent current general purpose, single-chip, -power management IC for battery-powered portable devices. The IC -integrates 3 ultra-low current consumption buck converters, 3 LDOs and 2 -LED Drivers. Also included are 4 GPIOs, a real-time clock (RTC), a 32kHz -clock gate, high-accuracy VREF for use with an external ADC, flexible -dual-input power path, 10 bit SAR ADC for battery temperature monitor and -1S battery charger with scalable charge currents. - -Required properties: - - compatible : Should be "rohm,bd70528" - - reg : I2C slave address. - - interrupts : The interrupt line the device is connected to. - - interrupt-controller : To indicate BD70528 acts as an interrupt controller. - - #interrupt-cells : Should be 2. Usage is compliant to the 2 cells - variant of ../interrupt-controller/interrupts.txt - - gpio-controller : To indicate BD70528 acts as a GPIO controller. - - #gpio-cells : Should be 2. The first cell is the pin number and - the second cell is used to specify flags. See - ../gpio/gpio.txt for more information. - - #clock-cells : Should be 0. - - regulators: : List of child nodes that specify the regulators. - Please see ../regulator/rohm,bd70528-regulator.txt - -Optional properties: - - clock-output-names : Should contain name for output clock. - -Example: -/* External oscillator */ -osc: oscillator { - compatible = "fixed-clock"; - #clock-cells = <1>; - clock-frequency = <32768>; - clock-output-names = "osc"; -}; - -pmic: pmic@4b { - compatible = "rohm,bd70528"; - reg = <0x4b>; - interrupt-parent = <&gpio1>; - interrupts = <29 IRQ_TYPE_LEVEL_LOW>; - clocks = <&osc 0>; - #clock-cells = <0>; - clock-output-names = "bd70528-32k-out"; - #gpio-cells = <2>; - gpio-controller; - interrupt-controller; - #interrupt-cells = <2>; - - regulators { - buck1: BUCK1 { - regulator-name = "buck1"; - regulator-min-microvolt = <1200000>; - regulator-max-microvolt = <3400000>; - regulator-boot-on; - regulator-ramp-delay = <125>; - }; - buck2: BUCK2 { - regulator-name = "buck2"; - regulator-min-microvolt = <1200000>; - regulator-max-microvolt = <3300000>; - regulator-boot-on; - regulator-ramp-delay = <125>; - }; - buck3: BUCK3 { - regulator-name = "buck3"; - regulator-min-microvolt = <800000>; - regulator-max-microvolt = <1800000>; - regulator-boot-on; - regulator-ramp-delay = <250>; - }; - ldo1: LDO1 { - regulator-name = "ldo1"; - regulator-min-microvolt = <1650000>; - regulator-max-microvolt = <3300000>; - regulator-boot-on; - }; - ldo2: LDO2 { - regulator-name = "ldo2"; - regulator-min-microvolt = <1650000>; - regulator-max-microvolt = <3300000>; - regulator-boot-on; - }; - - ldo3: LDO3 { - regulator-name = "ldo3"; - regulator-min-microvolt = <1650000>; - regulator-max-microvolt = <3300000>; - }; - led_ldo1: LED_LDO1 { - regulator-name = "led_ldo1"; - regulator-min-microvolt = <200000>; - regulator-max-microvolt = <300000>; - }; - led_ldo2: LED_LDO2 { - regulator-name = "led_ldo2"; - regulator-min-microvolt = <200000>; - regulator-max-microvolt = <300000>; - }; - }; -}; diff --git a/Documentation/devicetree/bindings/mfd/rohm,bd9571mwv.yaml b/Documentation/devicetree/bindings/mfd/rohm,bd9571mwv.yaml new file mode 100644 index 000000000000..89f9efee465b --- /dev/null +++ b/Documentation/devicetree/bindings/mfd/rohm,bd9571mwv.yaml @@ -0,0 +1,127 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/mfd/rohm,bd9571mwv.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: ROHM BD9571MWV/BD9574MWF Power Management Integrated Circuit (PMIC) + +maintainers: + - Marek Vasut + +properties: + compatible: + enum: + - rohm,bd9571mwv + - rohm,bd9574mwf + + reg: + maxItems: 1 + + interrupts: + maxItems: 1 + + interrupt-controller: true + + '#interrupt-cells': + const: 2 + + gpio-controller: true + + '#gpio-cells': + const: 2 + + rohm,ddr-backup-power: + $ref: /schemas/types.yaml#/definitions/uint32 + minimum: 0x0 + maximum: 0xf + description: | + Value to use for DDR-Backup Power (default 0). + This is a bitmask that specifies which DDR power rails need to be kept + powered when backup mode is entered, for system suspend: + - bit 0: DDR0 + - bit 1: DDR1 + - bit 2: DDR0C + - bit 3: DDR1C + These bits match the KEEPON_DDR* bits in the documentation for the "BKUP + Mode Cnt" register. + + rohm,rstbmode-level: + $ref: /schemas/types.yaml#/definitions/flag + description: + The RSTB signal is configured for level mode, to accommodate a toggle + power switch (the RSTBMODE pin is strapped low). + + rohm,rstbmode-pulse: + $ref: /schemas/types.yaml#/definitions/flag + description: + The RSTB signal is configured for pulse mode, to accommodate a momentary + power switch (the RSTBMODE pin is strapped high). + + regulators: + type: object + description: + List of child nodes that specify the regulator initialization data. + Child nodes must be named after their hardware counterparts. + + patternProperties: + "^(vd09|vd18|vd25|vd33|dvfs)$": + type: object + $ref: ../regulator/regulator.yaml# + + properties: + regulator-name: + pattern: "^(vd09|vd18|vd25|vd33|dvfs)$" + + unevaluatedProperties: false + + additionalProperties: false + +additionalProperties: false + +required: + - compatible + - reg + - interrupts + - interrupt-controller + - '#interrupt-cells' + - gpio-controller + - '#gpio-cells' + +oneOf: + - required: + - rohm,rstbmode-level + - required: + - rohm,rstbmode-pulse + +examples: + - | + #include + + i2c { + #address-cells = <1>; + #size-cells = <0>; + + pmic: pmic@30 { + compatible = "rohm,bd9571mwv"; + reg = <0x30>; + interrupt-parent = <&gpio2>; + interrupts = <0 IRQ_TYPE_LEVEL_LOW>; + interrupt-controller; + #interrupt-cells = <2>; + gpio-controller; + #gpio-cells = <2>; + rohm,ddr-backup-power = <0xf>; + rohm,rstbmode-pulse; + + regulators { + dvfs: dvfs { + regulator-name = "dvfs"; + regulator-min-microvolt = <750000>; + regulator-max-microvolt = <1030000>; + regulator-boot-on; + regulator-always-on; + }; + }; + }; + }; diff --git a/Documentation/devicetree/bindings/mfd/syscon.yaml b/Documentation/devicetree/bindings/mfd/syscon.yaml index 5de16388a089..eeac1cbc5a17 100644 --- a/Documentation/devicetree/bindings/mfd/syscon.yaml +++ b/Documentation/devicetree/bindings/mfd/syscon.yaml @@ -39,6 +39,7 @@ properties: - allwinner,sun8i-v3s-system-controller - allwinner,sun50i-a64-system-controller - brcm,cru-clkset + - freecom,fsg-cs2-system-controller - hisilicon,dsa-subctrl - hisilicon,hi6220-sramctrl - hisilicon,pcie-sas-subctrl @@ -57,6 +58,7 @@ properties: - samsung,exynos4-sysreg - samsung,exynos5-sysreg - samsung,exynos5433-sysreg + - samsung,exynos850-sysreg - samsung,exynosautov9-sysreg - const: syscon diff --git a/Documentation/devicetree/bindings/mmc/arasan,sdhci.yaml b/Documentation/devicetree/bindings/mmc/arasan,sdhci.yaml index de6f076e0ece..83be9e93d221 100644 --- a/Documentation/devicetree/bindings/mmc/arasan,sdhci.yaml +++ b/Documentation/devicetree/bindings/mmc/arasan,sdhci.yaml @@ -118,6 +118,9 @@ properties: phy-names: const: phy_arasan + resets: + maxItems: 1 + arasan,soc-ctl-syscon: $ref: /schemas/types.yaml#/definitions/phandle description: diff --git a/Documentation/devicetree/bindings/mmc/arm,pl18x.yaml b/Documentation/devicetree/bindings/mmc/arm,pl18x.yaml index 47595cb483be..a4f74bec68a3 100644 --- a/Documentation/devicetree/bindings/mmc/arm,pl18x.yaml +++ b/Documentation/devicetree/bindings/mmc/arm,pl18x.yaml @@ -53,6 +53,12 @@ properties: items: - const: arm,pl18x - const: arm,primecell + - description: Entry for STMicroelectronics variant of PL18x. + This dedicated compatible is used by bootloaders. + items: + - const: st,stm32-sdmmc2 + - const: arm,pl18x + - const: arm,primecell clocks: description: One or two clocks, the "apb_pclk" and the "MCLK" @@ -60,6 +66,18 @@ properties: minItems: 1 maxItems: 2 + dmas: + maxItems: 2 + + dma-names: + oneOf: + - items: + - const: tx + - const: rx + - items: + - const: rx + - const: tx + power-domains: true resets: @@ -213,7 +231,6 @@ examples: arm,primecell-periphid = <0x10153180>; reg = <0x52007000 0x1000>; interrupts = <49>; - interrupt-names = "cmd_irq"; clocks = <&rcc 0>; clock-names = "apb_pclk"; resets = <&rcc 1>; diff --git a/Documentation/devicetree/bindings/mmc/brcm,sdhci-brcmstb.txt b/Documentation/devicetree/bindings/mmc/brcm,sdhci-brcmstb.txt deleted file mode 100644 index ae2074184528..000000000000 --- a/Documentation/devicetree/bindings/mmc/brcm,sdhci-brcmstb.txt +++ /dev/null @@ -1,53 +0,0 @@ -* BROADCOM BRCMSTB/BMIPS SDHCI Controller - -This file documents differences between the core properties in mmc.txt -and the properties used by the sdhci-brcmstb driver. - -NOTE: The driver disables all UHS speed modes by default and depends -on Device Tree properties to enable them for SoC/Board combinations -that support them. - -Required properties: -- compatible: should be one of the following - - "brcm,bcm7425-sdhci" - - "brcm,bcm7445-sdhci" - - "brcm,bcm7216-sdhci" - -Refer to clocks/clock-bindings.txt for generic clock consumer properties. - -Example: - - sdhci@84b0000 { - sd-uhs-sdr50; - sd-uhs-ddr50; - sd-uhs-sdr104; - sdhci,auto-cmd12; - compatible = "brcm,bcm7216-sdhci", - "brcm,bcm7445-sdhci", - "brcm,sdhci-brcmstb"; - reg = <0x84b0000 0x260 0x84b0300 0x200>; - reg-names = "host", "cfg"; - interrupts = <0x0 0x26 0x4>; - interrupt-names = "sdio0_0"; - clocks = <&scmi_clk 245>; - clock-names = "sw_sdio"; - }; - - sdhci@84b1000 { - mmc-ddr-1_8v; - mmc-hs200-1_8v; - mmc-hs400-1_8v; - mmc-hs400-enhanced-strobe; - supports-cqe; - non-removable; - bus-width = <0x8>; - compatible = "brcm,bcm7216-sdhci", - "brcm,bcm7445-sdhci", - "brcm,sdhci-brcmstb"; - reg = <0x84b1000 0x260 0x84b1300 0x200>; - reg-names = "host", "cfg"; - interrupts = <0x0 0x27 0x4>; - interrupt-names = "sdio1_0"; - clocks = <&scmi_clk 245>; - clock-names = "sw_sdio"; - }; diff --git a/Documentation/devicetree/bindings/mmc/brcm,sdhci-brcmstb.yaml b/Documentation/devicetree/bindings/mmc/brcm,sdhci-brcmstb.yaml new file mode 100644 index 000000000000..dccd5ad96981 --- /dev/null +++ b/Documentation/devicetree/bindings/mmc/brcm,sdhci-brcmstb.yaml @@ -0,0 +1,100 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/mmc/brcm,sdhci-brcmstb.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Broadcom BRCMSTB/BMIPS SDHCI Controller binding + +maintainers: + - Al Cooper + - Florian Fainelli + +allOf: + - $ref: mmc-controller.yaml# + +properties: + compatible: + oneOf: + - items: + - enum: + - brcm,bcm7216-sdhci + - const: brcm,bcm7445-sdhci + - const: brcm,sdhci-brcmstb + - items: + - enum: + - brcm,bcm7445-sdhci + - const: brcm,sdhci-brcmstb + - items: + - enum: + - brcm,bcm7425-sdhci + - const: brcm,sdhci-brcmstb + + reg: + minItems: 2 + + reg-names: + items: + - const: host + - const: cfg + + interrupts: + maxItems: 1 + + clocks: + maxItems: 1 + description: + handle to core clock for the sdhci controller. + + clock-names: + items: + - const: sw_sdio + + sdhci,auto-cmd12: + type: boolean + description: Specifies that controller should use auto CMD12 + +required: + - compatible + - reg + - interrupts + - clocks + +unevaluatedProperties: false + +examples: + - | + mmc@84b0000 { + sd-uhs-sdr50; + sd-uhs-ddr50; + sd-uhs-sdr104; + sdhci,auto-cmd12; + compatible = "brcm,bcm7216-sdhci", + "brcm,bcm7445-sdhci", + "brcm,sdhci-brcmstb"; + reg = <0x84b0000 0x260>, <0x84b0300 0x200>; + reg-names = "host", "cfg"; + interrupts = <0x0 0x26 0x4>; + interrupt-names = "sdio0_0"; + clocks = <&scmi_clk 245>; + clock-names = "sw_sdio"; + }; + + mmc@84b1000 { + mmc-ddr-1_8v; + mmc-hs200-1_8v; + mmc-hs400-1_8v; + mmc-hs400-enhanced-strobe; + supports-cqe; + non-removable; + bus-width = <0x8>; + compatible = "brcm,bcm7216-sdhci", + "brcm,bcm7445-sdhci", + "brcm,sdhci-brcmstb"; + reg = <0x84b1000 0x260>, <0x84b1300 0x200>; + reg-names = "host", "cfg"; + interrupts = <0x0 0x27 0x4>; + interrupt-names = "sdio1_0"; + clocks = <&scmi_clk 245>; + clock-names = "sw_sdio"; + }; diff --git a/Documentation/devicetree/bindings/mmc/exynos-dw-mshc.txt b/Documentation/devicetree/bindings/mmc/exynos-dw-mshc.txt index 0419a63f73a0..753e9d7d8956 100644 --- a/Documentation/devicetree/bindings/mmc/exynos-dw-mshc.txt +++ b/Documentation/devicetree/bindings/mmc/exynos-dw-mshc.txt @@ -22,6 +22,8 @@ Required Properties: specific extensions. - "samsung,exynos7-dw-mshc-smu": for controllers with Samsung Exynos7 specific extensions having an SMU. + - "axis,artpec8-dw-mshc": for controllers with ARTPEC-8 specific + extensions. * samsung,dw-mshc-ciu-div: Specifies the divider value for the card interface unit (ciu) clock. This property is applicable only for Exynos5 SoC's and diff --git a/Documentation/devicetree/bindings/mmc/fsl-imx-esdhc.yaml b/Documentation/devicetree/bindings/mmc/fsl-imx-esdhc.yaml index 19621a2f8beb..17acbc665f5a 100644 --- a/Documentation/devicetree/bindings/mmc/fsl-imx-esdhc.yaml +++ b/Documentation/devicetree/bindings/mmc/fsl-imx-esdhc.yaml @@ -34,6 +34,7 @@ properties: - fsl,imx6ull-usdhc - fsl,imx7d-usdhc - fsl,imx7ulp-usdhc + - fsl,imxrt1050-usdhc - nxp,s32g2-usdhc - items: - enum: @@ -44,6 +45,10 @@ properties: - fsl,imx8qm-usdhc - fsl,imx8qxp-usdhc - const: fsl,imx7d-usdhc + - items: + - enum: + - fsl,imx8ulp-usdhc + - const: fsl,imx8mm-usdhc reg: maxItems: 1 @@ -116,6 +121,9 @@ properties: - const: ahb - const: per + power-domains: + maxItems: 1 + pinctrl-names: oneOf: - minItems: 3 diff --git a/Documentation/devicetree/bindings/mmc/img-dw-mshc.txt b/Documentation/devicetree/bindings/mmc/img-dw-mshc.txt deleted file mode 100644 index c54e577eea07..000000000000 --- a/Documentation/devicetree/bindings/mmc/img-dw-mshc.txt +++ /dev/null @@ -1,28 +0,0 @@ -* Imagination specific extensions to the Synopsys Designware Mobile Storage - Host Controller - -The Synopsys designware mobile storage host controller is used to interface -a SoC with storage medium such as eMMC or SD/MMC cards. This file documents -differences between the core Synopsys dw mshc controller properties described -by synopsys-dw-mshc.txt and the properties used by the Imagination specific -extensions to the Synopsys Designware Mobile Storage Host Controller. - -Required Properties: - -* compatible: should be - - "img,pistachio-dw-mshc": for Pistachio SoCs - -Example: - - mmc@18142000 { - compatible = "img,pistachio-dw-mshc"; - reg = <0x18142000 0x400>; - interrupts = ; - - clocks = <&system_clk>, <&sdhost_clk>; - clock-names = "biu", "ciu"; - - fifo-depth = <0x20>; - bus-width = <4>; - disable-wp; - }; diff --git a/Documentation/devicetree/bindings/mmc/ingenic,mmc.yaml b/Documentation/devicetree/bindings/mmc/ingenic,mmc.yaml index 01d5c6da0eeb..2d10aedf2e00 100644 --- a/Documentation/devicetree/bindings/mmc/ingenic,mmc.yaml +++ b/Documentation/devicetree/bindings/mmc/ingenic,mmc.yaml @@ -39,14 +39,15 @@ properties: const: mmc dmas: - items: - - description: DMA controller phandle and request line for RX - - description: DMA controller phandle and request line for TX + minItems: 1 + maxItems: 2 dma-names: - items: - - const: rx - - const: tx + oneOf: + - items: + - const: rx + - const: tx + - const: tx-rx required: - compatible @@ -80,3 +81,27 @@ examples: <&dma JZ4780_DMA_MSC0_TX 0xffffffff>; dma-names = "rx", "tx"; }; + - | + #include + #include + /* + * Alternative version of the example above, + * but using one single DMA channel for both + * TX and RX. + */ + mmc1: mmc@13460000 { + compatible = "ingenic,jz4780-mmc"; + reg = <0x13460000 0x1000>; + + interrupt-parent = <&intc>; + interrupts = <36>; + + clocks = <&cgu JZ4780_CLK_MSC1>; + clock-names = "mmc"; + + cap-sd-highspeed; + cap-mmc-highspeed; + cap-sdio-irq; + dmas = <&dma JZ4780_DMA_MSC1_TX JZ4780_DMA_MSC1_RX 0xffffffff>; + dma-names = "tx-rx"; + }; diff --git a/Documentation/devicetree/bindings/mmc/mtk-sd.yaml b/Documentation/devicetree/bindings/mmc/mtk-sd.yaml index 82768a807294..faf89b0c918f 100644 --- a/Documentation/devicetree/bindings/mmc/mtk-sd.yaml +++ b/Documentation/devicetree/bindings/mmc/mtk-sd.yaml @@ -36,6 +36,9 @@ properties: - const: mediatek,mt8195-mmc - const: mediatek,mt8183-mmc + reg: + maxItems: 1 + clocks: description: Should contain phandle for the clock feeding the MMC controller. @@ -62,6 +65,9 @@ properties: - const: axi_cg - const: ahb_cg + interrupts: + maxItems: 1 + pinctrl-names: items: - const: default diff --git a/Documentation/devicetree/bindings/mmc/sdhci-am654.yaml b/Documentation/devicetree/bindings/mmc/sdhci-am654.yaml index 224303f5b913..9fbf16b3bc8d 100644 --- a/Documentation/devicetree/bindings/mmc/sdhci-am654.yaml +++ b/Documentation/devicetree/bindings/mmc/sdhci-am654.yaml @@ -48,6 +48,8 @@ properties: - const: clk_ahb - const: clk_xin + sdhci-caps-mask: true + # PHY output tap delays: # Used to delay the data valid window and align it to the sampling clock. # Binding needs to be provided for each supported speed mode otherwise the diff --git a/Documentation/devicetree/bindings/mmc/sdhci-msm.txt b/Documentation/devicetree/bindings/mmc/sdhci-msm.txt index 50841e2843fc..6a8cc261bf61 100644 --- a/Documentation/devicetree/bindings/mmc/sdhci-msm.txt +++ b/Documentation/devicetree/bindings/mmc/sdhci-msm.txt @@ -17,6 +17,7 @@ Required properties: "qcom,msm8974-sdhci", "qcom,sdhci-msm-v4" "qcom,msm8916-sdhci", "qcom,sdhci-msm-v4" "qcom,msm8992-sdhci", "qcom,sdhci-msm-v4" + "qcom,msm8994-sdhci", "qcom,sdhci-msm-v4" "qcom,msm8996-sdhci", "qcom,sdhci-msm-v4" "qcom,qcs404-sdhci", "qcom,sdhci-msm-v5" "qcom,sc7180-sdhci", "qcom,sdhci-msm-v5"; diff --git a/Documentation/devicetree/bindings/mmc/socfpga-dw-mshc.txt b/Documentation/devicetree/bindings/mmc/socfpga-dw-mshc.txt deleted file mode 100644 index 4897bea7e3f8..000000000000 --- a/Documentation/devicetree/bindings/mmc/socfpga-dw-mshc.txt +++ /dev/null @@ -1,23 +0,0 @@ -* Altera SOCFPGA specific extensions to the Synopsys Designware Mobile - Storage Host Controller - -The Synopsys designware mobile storage host controller is used to interface -a SoC with storage medium such as eMMC or SD/MMC cards. This file documents -differences between the core Synopsys dw mshc controller properties described -by synopsys-dw-mshc.txt and the properties used by the Altera SOCFPGA specific -extensions to the Synopsys Designware Mobile Storage Host Controller. - -Required Properties: - -* compatible: should be - - "altr,socfpga-dw-mshc": for Altera's SOCFPGA platform - -Example: - - mmc: dwmmc0@ff704000 { - compatible = "altr,socfpga-dw-mshc"; - reg = <0xff704000 0x1000>; - interrupts = <0 129 4>; - #address-cells = <1>; - #size-cells = <0>; - }; diff --git a/Documentation/devicetree/bindings/mmc/socionext,uniphier-sd.yaml b/Documentation/devicetree/bindings/mmc/socionext,uniphier-sd.yaml index 56f9ff12742d..a586fad0a46b 100644 --- a/Documentation/devicetree/bindings/mmc/socionext,uniphier-sd.yaml +++ b/Documentation/devicetree/bindings/mmc/socionext,uniphier-sd.yaml @@ -26,6 +26,12 @@ properties: clocks: maxItems: 1 + dmas: + maxItems: 1 + + dma-names: + const: rx-tx + reset-names: description: | There are three reset signals at maximum diff --git a/Documentation/devicetree/bindings/mmc/synopsys-dw-mshc.yaml b/Documentation/devicetree/bindings/mmc/synopsys-dw-mshc.yaml index 240abb6f102c..ae6d6fca79e2 100644 --- a/Documentation/devicetree/bindings/mmc/synopsys-dw-mshc.yaml +++ b/Documentation/devicetree/bindings/mmc/synopsys-dw-mshc.yaml @@ -15,7 +15,10 @@ maintainers: # Everything else is described in the common file properties: compatible: - const: snps,dw-mshc + enum: + - altr,socfpga-dw-mshc + - img,pistachio-dw-mshc + - snps,dw-mshc reg: maxItems: 1 diff --git a/Documentation/devicetree/bindings/mtd/jedec,spi-nor.yaml b/Documentation/devicetree/bindings/mtd/jedec,spi-nor.yaml index ed590d7c6e37..39421f7233e4 100644 --- a/Documentation/devicetree/bindings/mtd/jedec,spi-nor.yaml +++ b/Documentation/devicetree/bindings/mtd/jedec,spi-nor.yaml @@ -11,6 +11,7 @@ maintainers: allOf: - $ref: "mtd.yaml#" + - $ref: /schemas/spi/spi-peripheral-props.yaml# properties: compatible: @@ -88,7 +89,7 @@ patternProperties: "^otp(-[0-9]+)?$": type: object -additionalProperties: false +unevaluatedProperties: false examples: - | diff --git a/Documentation/devicetree/bindings/mtd/renesas-nandc.yaml b/Documentation/devicetree/bindings/mtd/renesas-nandc.yaml new file mode 100644 index 000000000000..2870d36361c4 --- /dev/null +++ b/Documentation/devicetree/bindings/mtd/renesas-nandc.yaml @@ -0,0 +1,61 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/mtd/renesas-nandc.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Renesas R-Car Gen3 & RZ/N1x NAND flash controller device tree bindings + +maintainers: + - Miquel Raynal + +allOf: + - $ref: "nand-controller.yaml" + +properties: + compatible: + oneOf: + - items: + - enum: + - renesas,r9a06g032-nandc + - const: renesas,rzn1-nandc + + reg: + maxItems: 1 + + interrupts: + maxItems: 1 + + clocks: + items: + - description: APB host controller clock + - description: External NAND bus clock + + clock-names: + items: + - const: hclk + - const: eclk + +required: + - compatible + - reg + - clocks + - clock-names + - interrupts + +unevaluatedProperties: false + +examples: + - | + #include + #include + + nand-controller@40102000 { + compatible = "renesas,r9a06g032-nandc", "renesas,rzn1-nandc"; + reg = <0x40102000 0x2000>; + interrupts = ; + clocks = <&sysctrl R9A06G032_HCLK_NAND>, <&sysctrl R9A06G032_CLK_NAND>; + clock-names = "hclk", "eclk"; + #address-cells = <1>; + #size-cells = <0>; + }; diff --git a/Documentation/devicetree/bindings/mtd/ti,gpmc-nand.yaml b/Documentation/devicetree/bindings/mtd/ti,gpmc-nand.yaml index beb26b9bcfb2..4ac198814b7a 100644 --- a/Documentation/devicetree/bindings/mtd/ti,gpmc-nand.yaml +++ b/Documentation/devicetree/bindings/mtd/ti,gpmc-nand.yaml @@ -16,7 +16,10 @@ description: properties: compatible: - const: ti,omap2-nand + items: + - enum: + - ti,am64-nand + - ti,omap2-nand reg: maxItems: 1 @@ -53,6 +56,11 @@ properties: enum: [8, 16] default: 8 + rb-gpios: + description: + GPIO connection to R/B signal from NAND chip + maxItems: 1 + patternProperties: "@[0-9a-f]+$": $ref: "/schemas/mtd/partitions/partition.yaml" diff --git a/Documentation/devicetree/bindings/power/reset/gpio-poweroff.txt b/Documentation/devicetree/bindings/power/reset/gpio-poweroff.txt deleted file mode 100644 index 3e56c1b34a4c..000000000000 --- a/Documentation/devicetree/bindings/power/reset/gpio-poweroff.txt +++ /dev/null @@ -1,41 +0,0 @@ -Driver a GPIO line that can be used to turn the power off. - -The driver supports both level triggered and edge triggered power off. -At driver load time, the driver will request the given gpio line and -install a handler to power off the system. If the optional properties -'input' is not found, the GPIO line will be driven in the inactive -state. Otherwise its configured as an input. - -When the power-off handler is called, the gpio is configured as an -output, and drive active, so triggering a level triggered power off -condition. This will also cause an inactive->active edge condition, so -triggering positive edge triggered power off. After a delay of 100ms, -the GPIO is set to inactive, thus causing an active->inactive edge, -triggering negative edge triggered power off. After another 100ms -delay the GPIO is driver active again. If the power is still on and -the CPU still running after a 3000ms delay, a WARN_ON(1) is emitted. - -Required properties: -- compatible : should be "gpio-poweroff". -- gpios : The GPIO to set high/low, see "gpios property" in - Documentation/devicetree/bindings/gpio/gpio.txt. If the pin should be - low to power down the board set it to "Active Low", otherwise set - gpio to "Active High". - -Optional properties: -- input : Initially configure the GPIO line as an input. Only reconfigure - it to an output when the power-off handler is called. If this optional - property is not specified, the GPIO is initialized as an output in its - inactive state. -- active-delay-ms: Delay (default 100) to wait after driving gpio active -- inactive-delay-ms: Delay (default 100) to wait after driving gpio inactive -- timeout-ms: Time to wait before asserting a WARN_ON(1). If nothing is - specified, 3000 ms is used. - -Examples: - -gpio-poweroff { - compatible = "gpio-poweroff"; - gpios = <&gpio 4 0>; - timeout-ms = <3000>; -}; diff --git a/Documentation/devicetree/bindings/power/reset/gpio-poweroff.yaml b/Documentation/devicetree/bindings/power/reset/gpio-poweroff.yaml new file mode 100644 index 000000000000..45d66c775115 --- /dev/null +++ b/Documentation/devicetree/bindings/power/reset/gpio-poweroff.yaml @@ -0,0 +1,59 @@ +# SPDX-License-Identifier: (GPL-2.0-only or BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/power/reset/gpio-poweroff.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: GPIO controlled power off + +maintainers: + - Sebastian Reichel + +description: > + System power off support via a GPIO line. When a shutdown is + executed the operating system is expected to switch the GPIO + from inactive to active. After a delay (active-delay-ms) it + is expected to be switched back to inactive. After another + delay (inactive-delay-ms) it is configured as active again. + Finally the operating system assumes the power off failed if + the system is still running after waiting some time (timeout-ms). + +properties: + compatible: + const: gpio-poweroff + + gpios: + maxItems: 1 + + input: + type: boolean + description: > + Initially configure the GPIO line as an input. Only reconfigure + it to an output when the power-off sequence is initiated. If this optional + property is not specified, the GPIO is initialized as an output in its inactive state. + + active-delay-ms: + default: 100 + description: Delay to wait after driving gpio active + + inactive-delay-ms: + default: 100 + description: Delay to wait after driving gpio inactive + + timeout-ms: + default: 3000 + description: Time to wait before assuming the power off sequence failed. + +required: + - compatible + - gpios + +additionalProperties: false + +examples: + - | + gpio-poweroff { + compatible = "gpio-poweroff"; + gpios = <&gpio 4 0>; + timeout-ms = <3000>; + }; diff --git a/Documentation/devicetree/bindings/power/supply/maxim,max77976.yaml b/Documentation/devicetree/bindings/power/supply/maxim,max77976.yaml new file mode 100644 index 000000000000..675b9b26d233 --- /dev/null +++ b/Documentation/devicetree/bindings/power/supply/maxim,max77976.yaml @@ -0,0 +1,44 @@ +# SPDX-License-Identifier: (GPL-2.0 OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/power/supply/maxim,max77976.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Maxim Integrated MAX77976 Battery charger + +maintainers: + - Luca Ceresoli + +description: | + The Maxim MAX77976 is a 19Vin / 5.5A, 1-Cell Li+ battery charger + configured via I2C. + +allOf: + - $ref: power-supply.yaml# + +properties: + compatible: + const: maxim,max77976 + + reg: + maxItems: 1 + +required: + - compatible + - reg + +unevaluatedProperties: false + +examples: + - | + i2c { + #address-cells = <1>; + #size-cells = <0>; + + charger@6b { + compatible = "maxim,max77976"; + reg = <0x6b>; + }; + }; + +... diff --git a/Documentation/devicetree/bindings/power/supply/qcom,pm8941-charger.yaml b/Documentation/devicetree/bindings/power/supply/qcom,pm8941-charger.yaml index bc8904872d1b..caeff68c66d5 100644 --- a/Documentation/devicetree/bindings/power/supply/qcom,pm8941-charger.yaml +++ b/Documentation/devicetree/bindings/power/supply/qcom,pm8941-charger.yaml @@ -11,7 +11,9 @@ maintainers: properties: compatible: - const: qcom,pm8941-charger + enum: + - qcom,pm8226-charger + - qcom,pm8941-charger reg: maxItems: 1 diff --git a/Documentation/devicetree/bindings/regulator/dlg,da9121.yaml b/Documentation/devicetree/bindings/regulator/dlg,da9121.yaml index 228018c87bea..24ace6e1e5ec 100644 --- a/Documentation/devicetree/bindings/regulator/dlg,da9121.yaml +++ b/Documentation/devicetree/bindings/regulator/dlg,da9121.yaml @@ -17,27 +17,39 @@ description: | Dialog Semiconductor DA9130 Single-channel 10A double-phase buck converter Dialog Semiconductor DA9131 Double-channel 5A single-phase buck converter Dialog Semiconductor DA9132 Double-channel 3A single-phase buck converter + Dialog Semiconductor DA9141 Single-channel 40A quad-phase buck converter + Dialog Semiconductor DA9142 Single-channel 20A double-phase buck converter - Current limits + Device parameter ranges - This is PER PHASE, and the current limit setting in the devices reflect - that with a maximum 10A limit. Allowing for transients at/near double - the rated current, this translates across the device range to per - channel figures as so... + The current limits can be set to at/near double the rated current per channel + to allow for transient peaks. + Current limit changes when the output is enabled are not supported, as a + precaution against undefined behaviour. - | DA9121 DA9122 DA9220 DA9217 DA9140 - | /DA9130 /DA9131 /DA9132 - ----------------------------------------------------------------------------- - Output current / channel | 10000000 5000000 3000000 6000000 40000000 - Output current / phase | 5000000 5000000 3000000 3000000 9500000 - ----------------------------------------------------------------------------- - Min regulator-min-microvolt| 300000 300000 300000 300000 500000 - Max regulator-max-microvolt| 1900000 1900000 1900000 1900000 1000000 - Device hardware default | 1000000 1000000 1000000 1000000 1000000 - ----------------------------------------------------------------------------- - Min regulator-min-microamp | 7000000 3500000 3500000 7000000 26000000 - Max regulator-max-microamp | 20000000 10000000 6000000 12000000 78000000 - Device hardware default | 15000000 7500000 5500000 11000000 58000000 + |----------------------------------------------| + | | range & reset default value | + | Device |------------------------------| + | | microvolt | microamp | + |----------------------------------------------| + | DA9121/DA9130 | Min: 300000 | Min: 7000000 | + | | Max: 1900000 | Max: 20000000 | + |----------------------------------------------| + | DA9121/DA9131 | Min: 300000 | Min: 3500000 | + | | Max: 1900000 | Max: 10000000 | + |----------------------------------------------| + | DA9121/DA9131 | Min: 300000 | Min: 3500000 | + | | Max: 1900000 | Max: 6000000 | + |----------------------------------------------| + | DA9217 | Min: 300000 | Min: 7000000 | + | | Max: 1900000 | Max: 12000000 | + |----------------------------------------------| + | DA9141 | Min: 300000 | Min: 26000000 | + | | Max: 1300000 | Max: 78000000 | + |----------------------------------------------| + | DA9142 | Min: 300000 | Min: 13000000 | + | | Max: 1300000 | Max: 39000000 | + |----------------------------------------------| properties: $nodename: @@ -51,7 +63,8 @@ properties: - dlg,da9130 - dlg,da9131 - dlg,da9132 - - dlg,da9140 + - dlg,da9141 + - dlg,da9142 reg: maxItems: 1 @@ -70,26 +83,24 @@ properties: regulators: type: object - $ref: regulator.yaml# description: | - This node defines the settings for the BUCK. The content of the - sub-node is defined by the standard binding for regulators; see regulator.yaml. - The DA9121 regulator is bound using their names listed below - buck1 - BUCK1 - buck2 - BUCK2 //DA9122, DA9220, DA9131, DA9132 only + List of regulators provided by the device patternProperties: "^buck([1-2])$": type: object $ref: regulator.yaml# + description: | + Properties for a single BUCK regulator properties: - regulator-mode: - maxItems: 1 - description: Defined in include/dt-bindings/regulator/dlg,da9121-regulator.h + regulator-name: + pattern: "^BUCK([1-2])$" + description: | + BUCK2 present in DA9122, DA9220, DA9131, DA9132 only regulator-initial-mode: - maxItems: 1 + enum: [ 0, 1, 2, 3 ] description: Defined in include/dt-bindings/regulator/dlg,da9121-regulator.h enable-gpios: @@ -98,6 +109,7 @@ properties: dlg,ripple-cancel: $ref: "/schemas/types.yaml#/definitions/uint32" + enum: [ 0, 1, 2, 3 ] description: | Defined in include/dt-bindings/regulator/dlg,da9121-regulator.h Only present on multi-channel devices (DA9122, DA9220, DA9131, DA9132) diff --git a/Documentation/devicetree/bindings/regulator/max77686.txt b/Documentation/devicetree/bindings/regulator/max77686.txt deleted file mode 100644 index ff3d2dec8c4b..000000000000 --- a/Documentation/devicetree/bindings/regulator/max77686.txt +++ /dev/null @@ -1,71 +0,0 @@ -Binding for Maxim MAX77686 regulators - -This is a part of the device tree bindings of MAX77686 multi-function device. -More information can be found in ../mfd/max77686.txt file. - -The MAX77686 PMIC has 9 high-efficiency Buck and 26 Low-DropOut (LDO) -regulators that can be controlled over I2C. - -Following properties should be present in main device node of the MFD chip. - -Optional node: -- voltage-regulators : The regulators of max77686 have to be instantiated - under subnode named "voltage-regulators" using the following format. - - regulator_name { - regulator-compatible = LDOn/BUCKn - standard regulator constraints.... - }; - refer Documentation/devicetree/bindings/regulator/regulator.txt - - The regulator node's name should be initialized with a string -to get matched with their hardware counterparts as follow: - - -LDOn : for LDOs, where n can lie in range 1 to 26. - example: LDO1, LDO2, LDO26. - -BUCKn : for BUCKs, where n can lie in range 1 to 9. - example: BUCK1, BUCK5, BUCK9. - - Regulators which can be turned off during system suspend: - -LDOn : 2, 6-8, 10-12, 14-16, - -BUCKn : 1-4. - Use standard regulator bindings for it ('regulator-off-in-suspend'). - - LDO20, LDO21, LDO22, BUCK8 and BUCK9 can be configured to GPIO enable - control. To turn this feature on this property must be added to the regulator - sub-node: - - maxim,ena-gpios : one GPIO specifier enable control (the gpio - flags are actually ignored and always - ACTIVE_HIGH is used) - -Example: - - max77686: pmic@9 { - compatible = "maxim,max77686"; - interrupt-parent = <&wakeup_eint>; - interrupts = <26 IRQ_TYPE_LEVEL_LOW>; - reg = <0x09>; - - voltage-regulators { - ldo11_reg: LDO11 { - regulator-name = "vdd_ldo11"; - regulator-min-microvolt = <1900000>; - regulator-max-microvolt = <1900000>; - regulator-always-on; - }; - - buck1_reg: BUCK1 { - regulator-name = "vdd_mif"; - regulator-min-microvolt = <950000>; - regulator-max-microvolt = <1300000>; - regulator-always-on; - regulator-boot-on; - }; - - buck9_reg: BUCK9 { - regulator-name = "CAM_ISP_CORE_1.2V"; - regulator-min-microvolt = <1000000>; - regulator-max-microvolt = <1200000>; - maxim,ena-gpios = <&gpm0 3 GPIO_ACTIVE_HIGH>; - }; - }; diff --git a/Documentation/devicetree/bindings/regulator/maxim,max20086.yaml b/Documentation/devicetree/bindings/regulator/maxim,max20086.yaml new file mode 100644 index 000000000000..05f72391185e --- /dev/null +++ b/Documentation/devicetree/bindings/regulator/maxim,max20086.yaml @@ -0,0 +1,106 @@ +# SPDX-License-Identifier: (GPL-2.0 OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/regulator/maxim,max20086.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Maxim Integrated MAX20086-MAX20089 Camera Power Protector + +maintainers: + - Laurent Pinchart + +description: | + The MAX20086-MAX20089 are dual/quad camera power protectors, designed to + deliver power over coax for radar and camera modules. They support + software-configurable output switching and monitoring. The output voltage and + current limit are fixed by the hardware design. + +properties: + compatible: + enum: + - maxim,max20086 + - maxim,max20087 + - maxim,max20088 + - maxim,max20089 + + reg: + maxItems: 1 + + enable-gpios: + maxItems: 1 + description: GPIO connected to the EN pin, active high + + in-supply: + description: Input supply for the camera outputs (IN pin, 3.0V to 15.0V) + + vdd-supply: + description: Input supply for the device (VDD pin, 3.0V to 5.5V) + + regulators: + type: object + + patternProperties: + "^OUT[1-4]$": + type: object + $ref: regulator.yaml# + + additionalProperties: false + +required: + - compatible + - reg + - in-supply + - vdd-supply + - regulators + +allOf: + - if: + properties: + compatible: + contains: + enum: + - maxim,max20088 + - maxim,max20089 + then: + properties: + regulators: + properties: + OUT3: false + OUT4: false + +additionalProperties: false + +examples: + - | + #include + + i2c { + #address-cells = <1>; + #size-cells = <0>; + + regulator@28 { + compatible = "maxim,max20087"; + reg = <0x28>; + + in-supply = <®_12v0>; + vdd-supply = <®_3v3>; + + enable-gpios = <&gpio 108 GPIO_ACTIVE_HIGH>; + + regulators { + OUT1 { + regulator-name = "VOUT1"; + }; + OUT2 { + regulator-name = "VOUT2"; + }; + OUT3 { + regulator-name = "VOUT3"; + }; + OUT4 { + regulator-name = "VOUT4"; + }; + }; + }; + }; +... diff --git a/Documentation/devicetree/bindings/regulator/maxim,max77686.yaml b/Documentation/devicetree/bindings/regulator/maxim,max77686.yaml new file mode 100644 index 000000000000..bb64b679f765 --- /dev/null +++ b/Documentation/devicetree/bindings/regulator/maxim,max77686.yaml @@ -0,0 +1,83 @@ +# SPDX-License-Identifier: GPL-2.0-only OR BSD-2-Clause +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/regulator/maxim,max77686.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Maxim MAX77686 Power Management IC regulators + +maintainers: + - Chanwoo Choi + - Krzysztof Kozlowski + +description: | + This is a part of device tree bindings for Maxim MAX77686 Power Management + Integrated Circuit (PMIC). + + The Maxim MAX77686 provides high-efficiency Buck and 26 Low-DropOut (LDO) + regulators. + + See also Documentation/devicetree/bindings/mfd/maxim,max77686.yaml for + additional information and example. + +patternProperties: + # 26 LDOs + "^LDO([1-9]|1[0-9]|2[3-6])$": + type: object + $ref: regulator.yaml# + unevaluatedProperties: false + description: | + Properties for single LDO regulator. + Regulators which can be turned off during system suspend: + LDO2, LDO6-8, LDO10-12, LDO14-16 + + required: + - regulator-name + + # LDO20-LDO22 with maxim,ena-gpios + "^LDO2[0-2]$": + type: object + $ref: regulator.yaml# + unevaluatedProperties: false + description: | + Properties for single LDO regulator. + + properties: + maxim,ena-gpios: + maxItems: 1 + description: | + GPIO specifier to enable the GPIO control (on/off) for regulator. + + required: + - regulator-name + + # 9 bucks + "^BUCK[1-7]$": + type: object + $ref: regulator.yaml# + unevaluatedProperties: false + description: | + Properties for single BUCK regulator. + Regulators which can be turned off during system suspend: + BUCK[1-4] + + required: + - regulator-name + + "^BUCK[89]$": + type: object + $ref: regulator.yaml# + unevaluatedProperties: false + description: | + Properties for single BUCK regulator. + + properties: + maxim,ena-gpios: + maxItems: 1 + description: | + GPIO specifier to enable the GPIO control (on/off) for regulator. + + required: + - regulator-name + +additionalProperties: false diff --git a/Documentation/devicetree/bindings/regulator/maxim,max8973.yaml b/Documentation/devicetree/bindings/regulator/maxim,max8973.yaml index 54522827265b..35c53e27f78c 100644 --- a/Documentation/devicetree/bindings/regulator/maxim,max8973.yaml +++ b/Documentation/devicetree/bindings/regulator/maxim,max8973.yaml @@ -86,6 +86,9 @@ properties: reg: maxItems: 1 + interrupts: + maxItems: 1 + required: - compatible - reg diff --git a/Documentation/devicetree/bindings/regulator/qcom,rpmh-regulator.yaml b/Documentation/devicetree/bindings/regulator/qcom,rpmh-regulator.yaml index b959504e0ea4..5c73d3f639c7 100644 --- a/Documentation/devicetree/bindings/regulator/qcom,rpmh-regulator.yaml +++ b/Documentation/devicetree/bindings/regulator/qcom,rpmh-regulator.yaml @@ -43,6 +43,7 @@ description: | For PM8150L, smps1 - smps8, ldo1 - ldo11, bob, flash, rgb For PM8350, smps1 - smps12, ldo1 - ldo10 For PM8350C, smps1 - smps10, ldo1 - ldo13, bob + For PM8450, smps1 - smps6, ldo1 - ldo4 For PM8998, smps1 - smps13, ldo1 - ldo28, lvs1 - lvs2 For PMI8998, bob For PMR735A, smps1 - smps3, ldo1 - ldo7 @@ -62,7 +63,9 @@ properties: - qcom,pm8150l-rpmh-regulators - qcom,pm8350-rpmh-regulators - qcom,pm8350c-rpmh-regulators + - qcom,pm8450-rpmh-regulators - qcom,pm8998-rpmh-regulators + - qcom,pmg1110-rpmh-regulators - qcom,pmi8998-rpmh-regulators - qcom,pmm8155au-rpmh-regulators - qcom,pmr735a-rpmh-regulators diff --git a/Documentation/devicetree/bindings/regulator/qcom,spmi-regulator.txt b/Documentation/devicetree/bindings/regulator/qcom,spmi-regulator.txt index 2b544059e029..c2a39b121b1b 100644 --- a/Documentation/devicetree/bindings/regulator/qcom,spmi-regulator.txt +++ b/Documentation/devicetree/bindings/regulator/qcom,spmi-regulator.txt @@ -6,6 +6,7 @@ Qualcomm SPMI Regulators Definition: must be one of: "qcom,pm8004-regulators" "qcom,pm8005-regulators" + "qcom,pm8226-regulators" "qcom,pm8841-regulators" "qcom,pm8916-regulators" "qcom,pm8941-regulators" diff --git a/Documentation/devicetree/bindings/regulator/regulator.yaml b/Documentation/devicetree/bindings/regulator/regulator.yaml index a6ae9ecae5cc..ed560ee8714e 100644 --- a/Documentation/devicetree/bindings/regulator/regulator.yaml +++ b/Documentation/devicetree/bindings/regulator/regulator.yaml @@ -218,7 +218,7 @@ properties: description: Array of maximum spread between voltages of coupled regulators in microvolts, each value in the array relates to the corresponding couple specified by the regulator-coupled-with property. - $ref: "/schemas/types.yaml#/definitions/uint32" + $ref: "/schemas/types.yaml#/definitions/uint32-array" regulator-max-step-microvolt: description: Maximum difference between current and target voltages diff --git a/Documentation/devicetree/bindings/regulator/rohm,bd70528-regulator.txt b/Documentation/devicetree/bindings/regulator/rohm,bd70528-regulator.txt deleted file mode 100644 index 698cfc3bc3dd..000000000000 --- a/Documentation/devicetree/bindings/regulator/rohm,bd70528-regulator.txt +++ /dev/null @@ -1,68 +0,0 @@ -ROHM BD70528 Power Management Integrated Circuit regulator bindings - -Required properties: - - regulator-name: should be "buck1", "buck2", "buck3", "ldo1", "ldo2", "ldo3", - "led_ldo1", "led_ldo2" - -List of regulators provided by this controller. BD70528 regulators node -should be sub node of the BD70528 MFD node. See BD70528 MFD bindings at -Documentation/devicetree/bindings/mfd/rohm,bd70528-pmic.txt - -The valid names for BD70528 regulator nodes are: -BUCK1, BUCK2, BUCK3, LDO1, LDO2, LDO3, LED_LDO1, LED_LDO2 - -Optional properties: -- Any optional property defined in bindings/regulator/regulator.txt - -Example: -regulators { - buck1: BUCK1 { - regulator-name = "buck1"; - regulator-min-microvolt = <1200000>; - regulator-max-microvolt = <3400000>; - regulator-boot-on; - regulator-ramp-delay = <125>; - }; - buck2: BUCK2 { - regulator-name = "buck2"; - regulator-min-microvolt = <1200000>; - regulator-max-microvolt = <3300000>; - regulator-boot-on; - regulator-ramp-delay = <125>; - }; - buck3: BUCK3 { - regulator-name = "buck3"; - regulator-min-microvolt = <800000>; - regulator-max-microvolt = <1800000>; - regulator-boot-on; - regulator-ramp-delay = <250>; - }; - ldo1: LDO1 { - regulator-name = "ldo1"; - regulator-min-microvolt = <1650000>; - regulator-max-microvolt = <3300000>; - regulator-boot-on; - }; - ldo2: LDO2 { - regulator-name = "ldo2"; - regulator-min-microvolt = <1650000>; - regulator-max-microvolt = <3300000>; - regulator-boot-on; - }; - - ldo3: LDO3 { - regulator-name = "ldo3"; - regulator-min-microvolt = <1650000>; - regulator-max-microvolt = <3300000>; - }; - led_ldo1: LED_LDO1 { - regulator-name = "led_ldo1"; - regulator-min-microvolt = <200000>; - regulator-max-microvolt = <300000>; - }; - led_ldo2: LED_LDO2 { - regulator-name = "led_ldo2"; - regulator-min-microvolt = <200000>; - regulator-max-microvolt = <300000>; - }; -}; diff --git a/Documentation/devicetree/bindings/regulator/samsung,s5m8767.yaml b/Documentation/devicetree/bindings/regulator/samsung,s5m8767.yaml index c98929a213e9..3c1617b66861 100644 --- a/Documentation/devicetree/bindings/regulator/samsung,s5m8767.yaml +++ b/Documentation/devicetree/bindings/regulator/samsung,s5m8767.yaml @@ -67,8 +67,9 @@ patternProperties: required: - regulator-name +properties: # 9 buck - "^BUCK9$": + BUCK9: type: object $ref: regulator.yaml# unevaluatedProperties: false diff --git a/Documentation/devicetree/bindings/spi/atmel,quadspi.yaml b/Documentation/devicetree/bindings/spi/atmel,quadspi.yaml new file mode 100644 index 000000000000..1d493add4053 --- /dev/null +++ b/Documentation/devicetree/bindings/spi/atmel,quadspi.yaml @@ -0,0 +1,99 @@ +# SPDX-License-Identifier: GPL-2.0-only OR BSD-2-Clause +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/spi/atmel,quadspi.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Atmel Quad Serial Peripheral Interface (QSPI) + +maintainers: + - Tudor Ambarus + +allOf: + - $ref: spi-controller.yaml# + +properties: + compatible: + enum: + - atmel,sama5d2-qspi + - microchip,sam9x60-qspi + - microchip,sama7g5-qspi + - microchip,sama7g5-ospi + + reg: + items: + - description: base registers + - description: mapped memory + + reg-names: + items: + - const: qspi_base + - const: qspi_mmap + + clocks: + minItems: 1 + items: + - description: peripheral clock + - description: system clock or generic clock, if available + + clock-names: + minItems: 1 + items: + - const: pclk + - enum: [ qspick, gclk ] + + interrupts: + maxItems: 1 + + dmas: + items: + - description: tx DMA channel + - description: rx DMA channel + + dma-names: + items: + - const: tx + - const: rx + + '#address-cells': + const: 1 + + '#size-cells': + const: 0 + +required: + - compatible + - reg + - reg-names + - interrupts + - clocks + - clock-names + - '#address-cells' + - '#size-cells' + +unevaluatedProperties: false + +examples: + - | + #include + #include + spi@f0020000 { + compatible = "atmel,sama5d2-qspi"; + reg = <0xf0020000 0x100>, <0xd0000000 0x8000000>; + reg-names = "qspi_base", "qspi_mmap"; + interrupts = <52 IRQ_TYPE_LEVEL_HIGH 7>; + clocks = <&pmc PMC_TYPE_PERIPHERAL 52>; + clock-names = "pclk"; + #address-cells = <1>; + #size-cells = <0>; + pinctrl-names = "default"; + pinctrl-0 = <&pinctrl_spi0_default>; + + flash@0 { + compatible = "jedec,spi-nor"; + spi-max-frequency = <50000000>; + reg = <0>; + spi-rx-bus-width = <4>; + spi-tx-bus-width = <4>; + }; + }; diff --git a/Documentation/devicetree/bindings/spi/atmel-quadspi.txt b/Documentation/devicetree/bindings/spi/atmel-quadspi.txt deleted file mode 100644 index 7c40ea694352..000000000000 --- a/Documentation/devicetree/bindings/spi/atmel-quadspi.txt +++ /dev/null @@ -1,37 +0,0 @@ -* Atmel Quad Serial Peripheral Interface (QSPI) - -Required properties: -- compatible: Should be one of the following: - - "atmel,sama5d2-qspi" - - "microchip,sam9x60-qspi" -- reg: Should contain the locations and lengths of the base registers - and the mapped memory. -- reg-names: Should contain the resource reg names: - - qspi_base: configuration register address space - - qspi_mmap: memory mapped address space -- interrupts: Should contain the interrupt for the device. -- clocks: Should reference the peripheral clock and the QSPI system - clock if available. -- clock-names: Should contain "pclk" for the peripheral clock and "qspick" - for the system clock when available. -- #address-cells: Should be <1>. -- #size-cells: Should be <0>. - -Example: - -spi@f0020000 { - compatible = "atmel,sama5d2-qspi"; - reg = <0xf0020000 0x100>, <0xd0000000 0x8000000>; - reg-names = "qspi_base", "qspi_mmap"; - interrupts = <52 IRQ_TYPE_LEVEL_HIGH 7>; - clocks = <&pmc PMC_TYPE_PERIPHERAL 52>; - clock-names = "pclk"; - #address-cells = <1>; - #size-cells = <0>; - pinctrl-names = "default"; - pinctrl-0 = <&pinctrl_spi0_default>; - - m25p80@0 { - ... - }; -}; diff --git a/Documentation/devicetree/bindings/spi/cdns,qspi-nor-peripheral-props.yaml b/Documentation/devicetree/bindings/spi/cdns,qspi-nor-peripheral-props.yaml new file mode 100644 index 000000000000..553601a441a7 --- /dev/null +++ b/Documentation/devicetree/bindings/spi/cdns,qspi-nor-peripheral-props.yaml @@ -0,0 +1,42 @@ +# SPDX-License-Identifier: (GPL-2.0 OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/spi/cdns,qspi-nor-peripheral-props.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Peripheral-specific properties for the Cadence QSPI controller. + +description: + See spi-peripheral-props.yaml for more info. + +maintainers: + - Pratyush Yadav + +properties: + # cdns,qspi-nor.yaml + cdns,read-delay: + $ref: /schemas/types.yaml#/definitions/uint32 + description: + Delay for read capture logic, in clock cycles. + + cdns,tshsl-ns: + description: + Delay in nanoseconds for the length that the master mode chip select + outputs are de-asserted between transactions. + + cdns,tsd2d-ns: + description: + Delay in nanoseconds between one chip select being de-activated + and the activation of another. + + cdns,tchsh-ns: + description: + Delay in nanoseconds between last bit of current transaction and + deasserting the device chip select (qspi_n_ss_out). + + cdns,tslch-ns: + description: + Delay in nanoseconds between setting qspi_n_ss_out low and + first bit transfer. + +additionalProperties: true diff --git a/Documentation/devicetree/bindings/spi/cdns,qspi-nor.yaml b/Documentation/devicetree/bindings/spi/cdns,qspi-nor.yaml index 037f41f58503..0a537fa3a641 100644 --- a/Documentation/devicetree/bindings/spi/cdns,qspi-nor.yaml +++ b/Documentation/devicetree/bindings/spi/cdns,qspi-nor.yaml @@ -87,39 +87,6 @@ properties: items: enum: [ qspi, qspi-ocp ] -# subnode's properties -patternProperties: - "@[0-9a-f]+$": - type: object - description: - Flash device uses the below defined properties in the subnode. - - properties: - cdns,read-delay: - $ref: /schemas/types.yaml#/definitions/uint32 - description: - Delay for read capture logic, in clock cycles. - - cdns,tshsl-ns: - description: - Delay in nanoseconds for the length that the master mode chip select - outputs are de-asserted between transactions. - - cdns,tsd2d-ns: - description: - Delay in nanoseconds between one chip select being de-activated - and the activation of another. - - cdns,tchsh-ns: - description: - Delay in nanoseconds between last bit of current transaction and - deasserting the device chip select (qspi_n_ss_out). - - cdns,tslch-ns: - description: - Delay in nanoseconds between setting qspi_n_ss_out low and - first bit transfer. - required: - compatible - reg diff --git a/Documentation/devicetree/bindings/spi/mediatek,spi-mtk-nor.yaml b/Documentation/devicetree/bindings/spi/mediatek,spi-mtk-nor.yaml index 7393f30535df..4e4694e3d539 100644 --- a/Documentation/devicetree/bindings/spi/mediatek,spi-mtk-nor.yaml +++ b/Documentation/devicetree/bindings/spi/mediatek,spi-mtk-nor.yaml @@ -43,14 +43,19 @@ properties: maxItems: 1 clocks: + minItems: 2 items: - description: clock used for spi bus - description: clock used for controller + - description: clock used for nor dma bus. this depends on hardware + design, so this is optional. clock-names: + minItems: 2 items: - const: spi - const: sf + - const: axi required: - compatible @@ -72,7 +77,7 @@ examples: nor_flash: spi@1100d000 { compatible = "mediatek,mt8173-nor"; reg = <0 0x1100d000 0 0xe0>; - interrupts = <&spi_flash_irq>; + interrupts = <1>; clocks = <&pericfg CLK_PERI_SPI>, <&topckgen CLK_TOP_SPINFI_IFR_SEL>; clock-names = "spi", "sf"; #address-cells = <1>; @@ -84,4 +89,3 @@ examples: }; }; }; - diff --git a/Documentation/devicetree/bindings/spi/renesas,rspi.yaml b/Documentation/devicetree/bindings/spi/renesas,rspi.yaml index 8397f60d80a2..76e6d9e52fc7 100644 --- a/Documentation/devicetree/bindings/spi/renesas,rspi.yaml +++ b/Documentation/devicetree/bindings/spi/renesas,rspi.yaml @@ -21,7 +21,8 @@ properties: - enum: - renesas,rspi-r7s72100 # RZ/A1H - renesas,rspi-r7s9210 # RZ/A2 - - const: renesas,rspi-rz # RZ/A + - renesas,r9a07g044-rspi # RZ/G2{L,LC} + - const: renesas,rspi-rz # RZ/A and RZ/G2{L,LC} - items: - enum: @@ -122,6 +123,7 @@ allOf: contains: enum: - renesas,qspi + - renesas,r9a07g044-rspi then: required: - resets diff --git a/Documentation/devicetree/bindings/spi/spi-controller.yaml b/Documentation/devicetree/bindings/spi/spi-controller.yaml index 8246891602e7..36b72518f565 100644 --- a/Documentation/devicetree/bindings/spi/spi-controller.yaml +++ b/Documentation/devicetree/bindings/spi/spi-controller.yaml @@ -94,73 +94,8 @@ patternProperties: "^.*@[0-9a-f]+$": type: object - properties: - compatible: - description: - Compatible of the SPI device. - - reg: - minItems: 1 - maxItems: 256 - items: - minimum: 0 - maximum: 256 - description: - Chip select used by the device. - - spi-3wire: - $ref: /schemas/types.yaml#/definitions/flag - description: - The device requires 3-wire mode. - - spi-cpha: - $ref: /schemas/types.yaml#/definitions/flag - description: - The device requires shifted clock phase (CPHA) mode. - - spi-cpol: - $ref: /schemas/types.yaml#/definitions/flag - description: - The device requires inverse clock polarity (CPOL) mode. - - spi-cs-high: - $ref: /schemas/types.yaml#/definitions/flag - description: - The device requires the chip select active high. - - spi-lsb-first: - $ref: /schemas/types.yaml#/definitions/flag - description: - The device requires the LSB first mode. - - spi-max-frequency: - $ref: /schemas/types.yaml#/definitions/uint32 - description: - Maximum SPI clocking speed of the device in Hz. - - spi-rx-bus-width: - description: - Bus width to the SPI bus used for read transfers. - If 0 is provided, then no RX will be possible on this device. - $ref: /schemas/types.yaml#/definitions/uint32 - enum: [0, 1, 2, 4, 8] - default: 1 - - spi-rx-delay-us: - description: - Delay, in microseconds, after a read transfer. - - spi-tx-bus-width: - description: - Bus width to the SPI bus used for write transfers. - If 0 is provided, then no TX will be possible on this device. - $ref: /schemas/types.yaml#/definitions/uint32 - enum: [0, 1, 2, 4, 8] - default: 1 - - spi-tx-delay-us: - description: - Delay, in microseconds, after a write transfer. + allOf: + - $ref: spi-peripheral-props.yaml required: - compatible diff --git a/Documentation/devicetree/bindings/spi/spi-fsl-lpspi.yaml b/Documentation/devicetree/bindings/spi/spi-fsl-lpspi.yaml index 312d8fee9dbb..1d46877fe46a 100644 --- a/Documentation/devicetree/bindings/spi/spi-fsl-lpspi.yaml +++ b/Documentation/devicetree/bindings/spi/spi-fsl-lpspi.yaml @@ -14,10 +14,13 @@ allOf: properties: compatible: - enum: - - fsl,imx7ulp-spi - - fsl,imx8qxp-spi - + oneOf: + - enum: + - fsl,imx7ulp-spi + - fsl,imx8qxp-spi + - items: + - const: fsl,imx8ulp-spi + - const: fsl,imx7ulp-spi reg: maxItems: 1 diff --git a/Documentation/devicetree/bindings/spi/spi-mux.yaml b/Documentation/devicetree/bindings/spi/spi-mux.yaml index 51c7622dc20b..7ea79f6d33f3 100644 --- a/Documentation/devicetree/bindings/spi/spi-mux.yaml +++ b/Documentation/devicetree/bindings/spi/spi-mux.yaml @@ -31,6 +31,7 @@ description: | allOf: - $ref: "/schemas/spi/spi-controller.yaml#" + - $ref: "/schemas/spi/spi-peripheral-props.yaml#" maintainers: - Chris Packham diff --git a/Documentation/devicetree/bindings/spi/spi-peripheral-props.yaml b/Documentation/devicetree/bindings/spi/spi-peripheral-props.yaml new file mode 100644 index 000000000000..5dd209206e88 --- /dev/null +++ b/Documentation/devicetree/bindings/spi/spi-peripheral-props.yaml @@ -0,0 +1,89 @@ +# SPDX-License-Identifier: (GPL-2.0 OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/spi/spi-peripheral-props.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Peripheral-specific properties for a SPI bus. + +description: + Many SPI controllers need to add properties to peripheral devices. They could + be common properties like spi-max-frequency, spi-cpha, etc. or they could be + controller specific like delay in clock or data lines, etc. These properties + need to be defined in the peripheral node because they are per-peripheral and + there can be multiple peripherals attached to a controller. All those + properties are listed here. The controller specific properties should go in + their own separate schema that should be referenced from here. + +maintainers: + - Pratyush Yadav + +properties: + reg: + minItems: 1 + maxItems: 256 + items: + minimum: 0 + maximum: 256 + description: + Chip select used by the device. + + spi-3wire: + $ref: /schemas/types.yaml#/definitions/flag + description: + The device requires 3-wire mode. + + spi-cpha: + $ref: /schemas/types.yaml#/definitions/flag + description: + The device requires shifted clock phase (CPHA) mode. + + spi-cpol: + $ref: /schemas/types.yaml#/definitions/flag + description: + The device requires inverse clock polarity (CPOL) mode. + + spi-cs-high: + $ref: /schemas/types.yaml#/definitions/flag + description: + The device requires the chip select active high. + + spi-lsb-first: + $ref: /schemas/types.yaml#/definitions/flag + description: + The device requires the LSB first mode. + + spi-max-frequency: + $ref: /schemas/types.yaml#/definitions/uint32 + description: + Maximum SPI clocking speed of the device in Hz. + + spi-rx-bus-width: + description: + Bus width to the SPI bus used for read transfers. + If 0 is provided, then no RX will be possible on this device. + $ref: /schemas/types.yaml#/definitions/uint32 + enum: [0, 1, 2, 4, 8] + default: 1 + + spi-rx-delay-us: + description: + Delay, in microseconds, after a read transfer. + + spi-tx-bus-width: + description: + Bus width to the SPI bus used for write transfers. + If 0 is provided, then no TX will be possible on this device. + $ref: /schemas/types.yaml#/definitions/uint32 + enum: [0, 1, 2, 4, 8] + default: 1 + + spi-tx-delay-us: + description: + Delay, in microseconds, after a write transfer. + +# The controller specific properties go here. +allOf: + - $ref: cdns,qspi-nor-peripheral-props.yaml# + +additionalProperties: true diff --git a/Documentation/devicetree/bindings/spi/spi-pl022.yaml b/Documentation/devicetree/bindings/spi/spi-pl022.yaml index a91d868e40c5..6d633728fc2b 100644 --- a/Documentation/devicetree/bindings/spi/spi-pl022.yaml +++ b/Documentation/devicetree/bindings/spi/spi-pl022.yaml @@ -72,6 +72,9 @@ properties: - const: rx - const: tx + resets: + maxItems: 1 + patternProperties: "^[a-zA-Z][a-zA-Z0-9,+\\-._]{0,63}@[0-9a-f]+$": type: object diff --git a/Documentation/devicetree/bindings/trivial-devices.yaml b/Documentation/devicetree/bindings/trivial-devices.yaml index 791079021f1b..c451ae82d8d7 100644 --- a/Documentation/devicetree/bindings/trivial-devices.yaml +++ b/Documentation/devicetree/bindings/trivial-devices.yaml @@ -73,6 +73,8 @@ properties: - dallas,ds4510 # Digital Thermometer and Thermostat - dallas,ds75 + # Delta AHE-50DC Open19 power shelf fan control module + - delta,ahe50dc-fan # Delta Electronics DPS-650-AB power supply - delta,dps650ab # Delta Electronics DPS920AB 920W 54V Power Supply @@ -121,8 +123,14 @@ properties: - ibm,cffps2 # Infineon IR36021 digital POL buck controller - infineon,ir36021 + # Infineon IR38060 Voltage Regulator + - infineon,ir38060 # Infineon IR38064 Voltage Regulator - infineon,ir38064 + # Infineon IR38164 Voltage Regulator + - infineon,ir38164 + # Infineon IR38263 Voltage Regulator + - infineon,ir38263 # Infineon SLB9635 (Soft-) I2C TPM (old protocol, max 100khz) - infineon,slb9635tt # Infineon SLB9645 I2C TPM (new protocol, max 400khz) diff --git a/Documentation/doc-guide/sphinx.rst b/Documentation/doc-guide/sphinx.rst index e445cb146efe..bb36f18ae9ac 100644 --- a/Documentation/doc-guide/sphinx.rst +++ b/Documentation/doc-guide/sphinx.rst @@ -138,6 +138,17 @@ To pass extra options to Sphinx, you can use the ``SPHINXOPTS`` make variable. For example, use ``make SPHINXOPTS=-v htmldocs`` to get more verbose output. +It is also possible to pass an extra DOCS_CSS overlay file, in order to customize +the html layout, by using the ``DOCS_CSS`` make variable. + +By default, the build will try to use the Read the Docs sphinx theme: + + https://github.com/readthedocs/sphinx_rtd_theme + +If the theme is not available, it will fall-back to the classic one. + +The Sphinx theme can be overridden by using the ``DOCS_THEME`` make variable. + To remove the generated documentation, run ``make cleandocs``. Writing Documentation @@ -250,12 +261,11 @@ please feel free to remove it. list tables ----------- -We recommend the use of *list table* formats. The *list table* formats are -double-stage lists. Compared to the ASCII-art they might not be as -comfortable for -readers of the text files. Their advantage is that they are easy to -create or modify and that the diff of a modification is much more meaningful, -because it is limited to the modified content. +The list-table formats can be useful for tables that are not easily laid +out in the usual Sphinx ASCII-art formats. These formats are nearly +impossible for readers of the plain-text documents to understand, though, +and should be avoided in the absence of a strong justification for their +use. The ``flat-table`` is a double-stage list similar to the ``list-table`` with some additional features: diff --git a/Documentation/features/core/thread-info-in-task/arch-support.txt b/Documentation/features/core/thread-info-in-task/arch-support.txt index 3361e86b0958..bc74d8beea72 100644 --- a/Documentation/features/core/thread-info-in-task/arch-support.txt +++ b/Documentation/features/core/thread-info-in-task/arch-support.txt @@ -8,7 +8,7 @@ ----------------------- | alpha: | TODO | | arc: | TODO | - | arm: | TODO | + | arm: | ok | | arm64: | ok | | csky: | TODO | | h8300: | TODO | diff --git a/Documentation/filesystems/erofs.rst b/Documentation/filesystems/erofs.rst index 01df283c7d04..7119aa213be7 100644 --- a/Documentation/filesystems/erofs.rst +++ b/Documentation/filesystems/erofs.rst @@ -93,6 +93,14 @@ dax A legacy option which is an alias for ``dax=always``. device=%s Specify a path to an extra device to be used together. =================== ========================================================= +Sysfs Entries +============= + +Information about mounted erofs file systems can be found in /sys/fs/erofs. +Each mounted filesystem will have a directory in /sys/fs/erofs based on its +device name (i.e., /sys/fs/erofs/sda). +(see also Documentation/ABI/testing/sysfs-fs-erofs) + On-disk details =============== diff --git a/Documentation/filesystems/idmappings.rst b/Documentation/filesystems/idmappings.rst index 1229a75ec75d..7a879ec3b6bf 100644 --- a/Documentation/filesystems/idmappings.rst +++ b/Documentation/filesystems/idmappings.rst @@ -952,75 +952,3 @@ The raw userspace id that is put on disk is ``u1000`` so when the user takes their home directory back to their home computer where they are assigned ``u1000`` using the initial idmapping and mount the filesystem with the initial idmapping they will see all those files owned by ``u1000``. - -Shortcircuting --------------- - -Currently, the implementation of idmapped mounts enforces that the filesystem -is mounted with the initial idmapping. The reason is simply that none of the -filesystems that we targeted were mountable with a non-initial idmapping. But -that might change soon enough. As we've seen above, thanks to the properties of -idmappings the translation works for both filesystems mounted with the initial -idmapping and filesystem with non-initial idmappings. - -Based on this current restriction to filesystem mounted with the initial -idmapping two noticeable shortcuts have been taken: - -1. We always stash a reference to the initial user namespace in ``struct - vfsmount``. Idmapped mounts are thus mounts that have a non-initial user - namespace attached to them. - - In order to support idmapped mounts this needs to be changed. Instead of - stashing the initial user namespace the user namespace the filesystem was - mounted with must be stashed. An idmapped mount is then any mount that has - a different user namespace attached then the filesystem was mounted with. - This has no user-visible consequences. - -2. The translation algorithms in ``mapped_fs*id()`` and ``i_*id_into_mnt()`` - are simplified. - - Let's consider ``mapped_fs*id()`` first. This function translates the - caller's kernel id into a kernel id in the filesystem's idmapping via - a mount's idmapping. The full algorithm is:: - - mapped_fsuid(kid): - /* Map the kernel id up into a userspace id in the mount's idmapping. */ - from_kuid(mount-idmapping, kid) = uid - - /* Map the userspace id down into a kernel id in the filesystem's idmapping. */ - make_kuid(filesystem-idmapping, uid) = kuid - - We know that the filesystem is always mounted with the initial idmapping as - we enforce this in ``mount_setattr()``. So this can be shortened to:: - - mapped_fsuid(kid): - /* Map the kernel id up into a userspace id in the mount's idmapping. */ - from_kuid(mount-idmapping, kid) = uid - - /* Map the userspace id down into a kernel id in the filesystem's idmapping. */ - KUIDT_INIT(uid) = kuid - - Similarly, for ``i_*id_into_mnt()`` which translated the filesystem's kernel - id into a mount's kernel id:: - - i_uid_into_mnt(kid): - /* Map the kernel id up into a userspace id in the filesystem's idmapping. */ - from_kuid(filesystem-idmapping, kid) = uid - - /* Map the userspace id down into a kernel id in the mounts's idmapping. */ - make_kuid(mount-idmapping, uid) = kuid - - Again, we know that the filesystem is always mounted with the initial - idmapping as we enforce this in ``mount_setattr()``. So this can be - shortened to:: - - i_uid_into_mnt(kid): - /* Map the kernel id up into a userspace id in the filesystem's idmapping. */ - __kuid_val(kid) = uid - - /* Map the userspace id down into a kernel id in the mounts's idmapping. */ - make_kuid(mount-idmapping, uid) = kuid - -Handling filesystems mounted with non-initial idmappings requires that the -translation functions be converted to their full form. They can still be -shortcircuited on non-idmapped mounts. This has no user-visible consequences. diff --git a/Documentation/filesystems/locking.rst b/Documentation/filesystems/locking.rst index d36fe79167b3..3f9b1497ebb8 100644 --- a/Documentation/filesystems/locking.rst +++ b/Documentation/filesystems/locking.rst @@ -169,7 +169,6 @@ prototypes:: int (*show_options)(struct seq_file *, struct dentry *); ssize_t (*quota_read)(struct super_block *, int, char *, size_t, loff_t); ssize_t (*quota_write)(struct super_block *, int, const char *, size_t, loff_t); - int (*bdev_try_to_free_page)(struct super_block*, struct page*, gfp_t); locking rules: All may block [not true, see below] @@ -194,7 +193,6 @@ umount_begin: no show_options: no (namespace_sem) quota_read: no (see below) quota_write: no (see below) -bdev_try_to_free_page: no (see below) ====================== ============ ======================== ->statfs() has s_umount (shared) when called by ustat(2) (native or @@ -210,9 +208,6 @@ dqio_sem) (unless an admin really wants to screw up something and writes to quota files with quotas on). For other details about locking see also dquot_operations section. -->bdev_try_to_free_page is called from the ->releasepage handler of -the block device inode. See there for more details. - file_system_type ================ diff --git a/Documentation/hwmon/asus_wmi_ec_sensors.rst b/Documentation/hwmon/asus_wmi_ec_sensors.rst new file mode 100644 index 000000000000..1b287f229e86 --- /dev/null +++ b/Documentation/hwmon/asus_wmi_ec_sensors.rst @@ -0,0 +1,38 @@ +.. SPDX-License-Identifier: GPL-2.0-or-later + +Kernel driver asus_wmi_ec_sensors +================================= + +Supported boards: + * PRIME X570-PRO, + * Pro WS X570-ACE, + * ROG CROSSHAIR VIII DARK HERO, + * ROG CROSSHAIR VIII FORMULA, + * ROG CROSSHAIR VIII HERO, + * ROG STRIX B550-E GAMING, + * ROG STRIX B550-I GAMING, + * ROG STRIX X570-E GAMING. + +Authors: + - Eugene Shalygin + +Description: +------------ +ASUS mainboards publish hardware monitoring information via Super I/O +chip and the ACPI embedded controller (EC) registers. Some of the sensors +are only available via the EC. + +ASUS WMI interface provides a method (BREC) to read data from EC registers, +which is utilized by this driver to publish those sensor readings to the +HWMON system. The driver is aware of and reads the following sensors: + +1. Chipset (PCH) temperature +2. CPU package temperature +3. Motherboard temperature +4. Readings from the T_Sensor header +5. VRM temperature +6. CPU_Opt fan RPM +7. Chipset fan RPM +8. Readings from the "Water flow meter" header (RPM) +9. Readings from the "Water In" and "Water Out" temperature headers +10. CPU current diff --git a/Documentation/hwmon/asus_wmi_sensors.rst b/Documentation/hwmon/asus_wmi_sensors.rst new file mode 100644 index 000000000000..8f2096cf5183 --- /dev/null +++ b/Documentation/hwmon/asus_wmi_sensors.rst @@ -0,0 +1,78 @@ +.. SPDX-License-Identifier: GPL-2.0-or-later + +Kernel driver asus_wmi_sensors +================================= + +Supported boards: + * PRIME X399-A, + * PRIME X470-PRO, + * ROG CROSSHAIR VI EXTREME, + * ROG CROSSHAIR VI HERO, + * ROG CROSSHAIR VI HERO (WI-FI AC), + * ROG CROSSHAIR VII HERO, + * ROG CROSSHAIR VII HERO (WI-FI), + * ROG STRIX B450-E GAMING, + * ROG STRIX B450-F GAMING, + * ROG STRIX B450-I GAMING, + * ROG STRIX X399-E GAMING, + * ROG STRIX X470-F GAMING, + * ROG STRIX X470-I GAMING, + * ROG ZENITH EXTREME, + * ROG ZENITH EXTREME ALPHA. + +Authors: + - Ed Brindley + +Description: +------------ +ASUS mainboards publish hardware monitoring information via WMI interface. + +ASUS WMI interface provides a methods to get list of sensors and values of +such, which is utilized by this driver to publish those sensor readings to the +HWMON system. + +The driver is aware of and reads the following sensors: + * CPU Core Voltage, + * CPU SOC Voltage, + * DRAM Voltage, + * VDDP Voltage, + * 1.8V PLL Voltage, + * +12V Voltage, + * +5V Voltage, + * 3VSB Voltage, + * VBAT Voltage, + * AVCC3 Voltage, + * SB 1.05V Voltage, + * CPU Core Voltage, + * CPU SOC Voltage, + * DRAM Voltage, + * CPU Fan RPM, + * Chassis Fan 1 RPM, + * Chassis Fan 2 RPM, + * Chassis Fan 3 RPM, + * HAMP Fan RPM, + * Water Pump RPM, + * CPU OPT RPM, + * Water Flow RPM, + * AIO Pump RPM, + * CPU Temperature, + * CPU Socket Temperature, + * Motherboard Temperature, + * Chipset Temperature, + * Tsensor 1 Temperature, + * CPU VRM Temperature, + * Water In, + * Water Out, + * CPU VRM Output Current. + +Known Issues: + * The WMI implementation in some of Asus' BIOSes is buggy. This can result in + fans stopping, fans getting stuck at max speed, or temperature readouts + getting stuck. This is not an issue with the driver, but the BIOS. The Prime + X470 Pro seems particularly bad for this. The more frequently the WMI + interface is polled the greater the potential for this to happen. Until you + have subjected your computer to an extended soak test while polling the + sensors frequently, don't leave you computer unattended. Upgrading to new + BIOS version with method version greater than or equal to two should + rectify the issue. + * A few boards report 12v voltages to be ~10v. diff --git a/Documentation/hwmon/ina238.rst b/Documentation/hwmon/ina238.rst new file mode 100644 index 000000000000..d9f479984420 --- /dev/null +++ b/Documentation/hwmon/ina238.rst @@ -0,0 +1,56 @@ +.. SPDX-License-Identifier: GPL-2.0-only + +Kernel driver ina238 +==================== + +Supported chips: + + * Texas Instruments INA238 + + Prefix: 'ina238' + + Addresses: I2C 0x40 - 0x4f + + Datasheet: + https://www.ti.com/lit/gpn/ina238 + +Author: Nathan Rossi + +Description +----------- + +The INA238 is a current shunt, power and temperature monitor with an I2C +interface. It includes a number of programmable functions including alerts, +conversion rate, sample averaging and selectable shunt voltage accuracy. + +The shunt value in micro-ohms can be set via platform data or device tree at +compile-time or via the shunt_resistor attribute in sysfs at run-time. Please +refer to the Documentation/devicetree/bindings/hwmon/ti,ina2xx.yaml for bindings +if the device tree is used. + +Sysfs entries +------------- + +======================= ======================================================= +in0_input Shunt voltage (mV) +in0_min Minimum shunt voltage threshold (mV) +in0_min_alarm Minimum shunt voltage alarm +in0_max Maximum shunt voltage threshold (mV) +in0_max_alarm Maximum shunt voltage alarm + +in1_input Bus voltage (mV) +in1_min Minimum bus voltage threshold (mV) +in1_min_alarm Minimum shunt voltage alarm +in1_max Maximum bus voltage threshold (mV) +in1_max_alarm Maximum shunt voltage alarm + +power1_input Power measurement (uW) +power1_max Maximum power threshold (uW) +power1_max_alarm Maximum power alarm + +curr1_input Current measurement (mA) + +temp1_input Die temperature measurement (mC) +temp1_max Maximum die temperature threshold (mC) +temp1_max_alarm Maximum die temperature alarm +======================= ======================================================= diff --git a/Documentation/hwmon/index.rst b/Documentation/hwmon/index.rst index 7046bf1870d9..df20022c741f 100644 --- a/Documentation/hwmon/index.rst +++ b/Documentation/hwmon/index.rst @@ -43,6 +43,8 @@ Hardware Monitoring Kernel Drivers asb100 asc7621 aspeed-pwm-tacho + asus_wmi_ec_sensors + asus_wmi_sensors bcm54140 bel-pfe bpa-rs600 @@ -76,6 +78,7 @@ Hardware Monitoring Kernel Drivers ibmpowernv ina209 ina2xx + ina238 ina3221 intel-m10-bmc-hwmon ir35221 @@ -142,6 +145,7 @@ Hardware Monitoring Kernel Drivers mlxreg-fan mp2888 mp2975 + mp5023 nct6683 nct6775 nct7802 @@ -150,6 +154,7 @@ Hardware Monitoring Kernel Drivers nsa320 ntc_thermistor nzxt-kraken2 + nzxt-smart2 occ pc87360 pc87427 diff --git a/Documentation/hwmon/ir38064.rst b/Documentation/hwmon/ir38064.rst index c455d755a267..e1148f21ea2a 100644 --- a/Documentation/hwmon/ir38064.rst +++ b/Documentation/hwmon/ir38064.rst @@ -3,14 +3,38 @@ Kernel driver ir38064 Supported chips: + * Infineon IR38060 + + Prefix: 'IR38060' + Addresses scanned: - + + Datasheet: Publicly available at the Infineon website + https://www.infineon.com/dgdl/Infineon-IR38060M-DS-v03_16-EN.pdf?fileId=5546d4625c167129015c3291ea9a4cee + * Infineon IR38064 Prefix: 'ir38064' Addresses scanned: - - Datasheet: Publicly available at the Infineon webiste + Datasheet: Publicly available at the Infineon website https://www.infineon.com/dgdl/Infineon-IR38064MTRPBF-DS-v03_07-EN.pdf?fileId=5546d462584d1d4a0158db0d9efb67ca + * Infineon IR38164 + + Prefix: 'ir38164' + Addresses scanned: - + + Datasheet: Publicly available at the Infineon website + https://www.infineon.com/dgdl/Infineon-IR38164M-DS-v02_02-EN.pdf?fileId=5546d462636cc8fb01640046efea1248 + + * Infineon ir38263 + + Prefix: 'ir38263' + Addresses scanned: - + + Datasheet: Publicly available at the Infineon website + https://www.infineon.com/dgdl/Infineon-IR38263M-DataSheet-v03_05-EN.pdf?fileId=5546d4625b62cd8a015bcf81f90a6e52 + Authors: - Maxim Sloyko - Patrick Venture @@ -18,7 +42,7 @@ Authors: Description ----------- -IR38064 is a Single-input Voltage, Synchronous Buck Regulator, DC-DC Converter. +IR38x6x are a Single-input Voltage, Synchronous Buck Regulator, DC-DC Converter. Usage Notes ----------- diff --git a/Documentation/hwmon/mp5023.rst b/Documentation/hwmon/mp5023.rst new file mode 100644 index 000000000000..af5ab1345a91 --- /dev/null +++ b/Documentation/hwmon/mp5023.rst @@ -0,0 +1,84 @@ +.. SPDX-License-Identifier: GPL-2.0 + +Kernel driver mp5023 +==================== + +Supported chips: + + * MPS MP5023 + + Prefix: 'mp5023' + + * Datasheet + + Publicly available at the MPS website : https://www.monolithicpower.com/en/mp5023.html + +Author: + + Howard Chiu + +Description +----------- + +This driver implements support for Monolithic Power Systems, Inc. (MPS) +MP5023 Hot-Swap Controller. + +Device complaint with: + +- PMBus rev 1.3 interface. + +Device supports direct format for reading input voltage, output voltage, +output current, input power and temperature. + +The driver exports the following attributes via the 'sysfs' files +for input voltage: + +**in1_input** + +**in1_label** + +**in1_max** + +**in1_max_alarm** + +**in1_min** + +**in1_min_alarm** + +The driver provides the following attributes for output voltage: + +**in2_input** + +**in2_label** + +**in2_alarm** + +The driver provides the following attributes for output current: + +**curr1_input** + +**curr1_label** + +**curr1_alarm** + +**curr1_max** + +The driver provides the following attributes for input power: + +**power1_input** + +**power1_label** + +**power1_alarm** + +The driver provides the following attributes for temperature: + +**temp1_input** + +**temp1_max** + +**temp1_max_alarm** + +**temp1_crit** + +**temp1_crit_alarm** diff --git a/Documentation/hwmon/nzxt-smart2.rst b/Documentation/hwmon/nzxt-smart2.rst new file mode 100644 index 000000000000..d9d1b2742665 --- /dev/null +++ b/Documentation/hwmon/nzxt-smart2.rst @@ -0,0 +1,62 @@ +.. SPDX-License-Identifier: GPL-2.0-or-later + +Kernel driver nzxt-smart2 +========================= + +Supported devices: + +- NZXT RGB & Fan controller +- NZXT Smart Device v2 + +Description +----------- + +This driver implements monitoring and control of fans plugged into the device. +Besides typical speed monitoring and PWM duty cycle control, voltage and current +is reported for every fan. + +The device also has two connectors for RGB LEDs; support for them isn't +implemented (mainly because there is no standardized sysfs interface). + +Also, the device has a noise sensor, but the sensor seems to be completely +useless (and very imprecise), so support for it isn't implemented too. + +Usage Notes +----------- + +The device should be autodetected, and the driver should load automatically. + +If fans are plugged in/unplugged while the system is powered on, the driver +must be reloaded to detect configuration changes; otherwise, new fans can't +be controlled (`pwm*` changes will be ignored). It is necessary because the +device has a dedicated "detect fans" command, and currently, it is executed only +during initialization. Speed, voltage, current monitoring will work even without +reload. As an alternative to reloading the module, a userspace tool (like +`liquidctl`_) can be used to run "detect fans" command through hidraw interface. + +The driver coexists with userspace tools that access the device through hidraw +interface with no known issues. + +.. _liquidctl: https://github.com/liquidctl/liquidctl + +Sysfs entries +------------- + +======================= ======================================================== +fan[1-3]_input Fan speed monitoring (in rpm). +curr[1-3]_input Current supplied to the fan (in milliamperes). +in[0-2]_input Voltage supplied to the fan (in millivolts). +pwm[1-3] Controls fan speed: PWM duty cycle for PWM-controlled + fans, voltage for other fans. Voltage can be changed in + 9-12 V range, but the value of the sysfs attribute is + always in 0-255 range (1 = 9V, 255 = 12V). Setting the + attribute to 0 turns off the fan completely. +pwm[1-3]_enable 1 if the fan can be controlled by writing to the + corresponding pwm* attribute, 0 otherwise. The device + can control only the fans it detected itself, so the + attribute is read-only. +pwm[1-3]_mode Read-only, 1 for PWM-controlled fans, 0 for other fans + (or if no fan connected). +update_interval The interval at which all inputs are updated (in + milliseconds). The default is 1000ms. Minimum is 250ms. +======================= ======================================================== diff --git a/Documentation/networking/rds.rst b/Documentation/networking/rds.rst index 44936c27ab3a..498395f5fbcb 100644 --- a/Documentation/networking/rds.rst +++ b/Documentation/networking/rds.rst @@ -1,6 +1,6 @@ .. SPDX-License-Identifier: GPL-2.0 -== +=== RDS === diff --git a/Documentation/process/5.Posting.rst b/Documentation/process/5.Posting.rst index 855a70b80269..bd36ecb29409 100644 --- a/Documentation/process/5.Posting.rst +++ b/Documentation/process/5.Posting.rst @@ -197,14 +197,29 @@ the build process, for example, or editor backup files) in the patch. The file "dontdiff" in the Documentation directory can help in this regard; pass it to diff with the "-X" option. -The tags mentioned above are used to describe how various developers have -been associated with the development of this patch. They are described in -detail in -the :ref:`Documentation/process/submitting-patches.rst ` -document; what follows here is a brief summary. Each of these lines has -the format: +The tags already briefly mentioned above are used to provide insights how +the patch came into being. They are described in detail in the +:ref:`Documentation/process/submitting-patches.rst ` +document; what follows here is a brief summary. -:: +One tag is used to refer to earlier commits which introduced problems fixed by +the patch:: + + Fixes: 1f2e3d4c5b6a ("The first line of the commit specified by the first 12 characters of its SHA-1 ID") + +Another tag is used for linking web pages with additional backgrounds or +details, for example a report about a bug fixed by the patch or a document +with a specification implemented by the patch:: + + Link: https://example.com/somewhere.html optional-other-stuff + +Many maintainers when applying a patch also add this tag to link to the +latest public review posting of the patch; often this is automatically done +by tools like b4 or a git hook like the one described in +'Documentation/maintainer/configure-git.rst'. + +A third kind of tag is used to document who was involved in the development of +the patch. Each of these uses this format:: tag: Full Name optional-other-stuff diff --git a/Documentation/process/submitting-patches.rst b/Documentation/process/submitting-patches.rst index 6b3aaed66fba..31ea120ce531 100644 --- a/Documentation/process/submitting-patches.rst +++ b/Documentation/process/submitting-patches.rst @@ -271,25 +271,6 @@ least a notification of the change, so that some information makes its way into the manual pages. User-space API changes should also be copied to linux-api@vger.kernel.org. -For small patches you may want to CC the Trivial Patch Monkey -trivial@kernel.org which collects "trivial" patches. Have a look -into the MAINTAINERS file for its current manager. - -Trivial patches must qualify for one of the following rules: - -- Spelling fixes in documentation -- Spelling fixes for errors which could break :manpage:`grep(1)` -- Warning fixes (cluttering with useless warnings is bad) -- Compilation fixes (only if they are actually correct) -- Runtime fixes (only if they actually fix things) -- Removing use of deprecated functions/macros -- Contact detail and documentation fixes -- Non-portable code replaced by portable code (even in arch-specific, - since people copy, as long as it's trivial) -- Any fix by the author/maintainer of the file (ie. patch monkey - in re-transmission mode) - - No MIME, no links, no compression, no attachments. Just plain text ------------------------------------------------------------------- diff --git a/Documentation/scheduler/sched-bwc.rst b/Documentation/scheduler/sched-bwc.rst index 173c14110c85..f166b182ff95 100644 --- a/Documentation/scheduler/sched-bwc.rst +++ b/Documentation/scheduler/sched-bwc.rst @@ -74,7 +74,6 @@ Quota, period and burst are managed within the cpu subsystem via cgroupfs. to cgroup v1. For cgroup v2, see :ref:`Documentation/admin-guide/cgroup-v2.rst `. -- cpu.cfs_quota_us: the total available run-time within a period (in - cpu.cfs_quota_us: run-time replenished within a period (in microseconds) - cpu.cfs_period_us: the length of a period (in microseconds) - cpu.stat: exports throttling statistics [explained further below] @@ -135,7 +134,7 @@ cpu.stat: of the group have been throttled. - nr_bursts: Number of periods burst occurs. - burst_time: Cumulative wall-time (in nanoseconds) that any CPUs has used - above quota in respective periods + above quota in respective periods. This interface is read-only. @@ -238,7 +237,7 @@ Examples additionally, in case accumulation has been done. With 50ms period, 20ms quota will be equivalent to 40% of 1 CPU. - And 10ms burst will be equivalent to 20% of 1 CPU. + And 10ms burst will be equivalent to 20% of 1 CPU:: # echo 20000 > cpu.cfs_quota_us /* quota = 20ms */ # echo 50000 > cpu.cfs_period_us /* period = 50ms */ diff --git a/Documentation/security/self-protection.rst b/Documentation/security/self-protection.rst index f584fb74b4ff..910668e665cb 100644 --- a/Documentation/security/self-protection.rst +++ b/Documentation/security/self-protection.rst @@ -81,8 +81,7 @@ of the kernel, gaining the protection of the kernel's strict memory permissions as described above. For variables that are initialized once at ``__init`` time, these can -be marked with the (new and under development) ``__ro_after_init`` -attribute. +be marked with the ``__ro_after_init`` attribute. What remains are variables that are updated rarely (e.g. GDT). These will need another infrastructure (similar to the temporary exceptions diff --git a/Documentation/sphinx-static/theme_overrides.css b/Documentation/sphinx-static/theme_overrides.css index 459ec5b29d68..f6f2b941a5d6 100644 --- a/Documentation/sphinx-static/theme_overrides.css +++ b/Documentation/sphinx-static/theme_overrides.css @@ -1,14 +1,14 @@ /* -*- coding: utf-8; mode: css -*- * * Sphinx HTML theme customization: read the doc - * + * Please don't add any color definition here, as the theme should + * work for both normal and dark modes. */ /* Improve contrast and increase size for easier reading. */ body { font-family: serif; - color: black; font-size: 100%; } @@ -16,17 +16,8 @@ h1, h2, .rst-content .toctree-wrapper p.caption, h3, h4, h5, h6, legend { font-family: sans-serif; } -.wy-menu-vertical li.current a { - color: #505050; -} - -.wy-menu-vertical li.on a, .wy-menu-vertical li.current > a { - color: #303030; -} - div[class^="highlight"] pre { font-family: monospace; - color: black; font-size: 100%; } @@ -104,13 +95,10 @@ div[class^="highlight"] pre { /* Menu selection and keystrokes */ span.menuselection { - color: blue; font-family: "Courier New", Courier, monospace } code.kbd, code.kbd span { - color: white; - background-color: darkblue; font-weight: bold; font-family: "Courier New", Courier, monospace } diff --git a/Documentation/sphinx-static/theme_rtd_colors.css b/Documentation/sphinx-static/theme_rtd_colors.css new file mode 100644 index 000000000000..55b6e1c3664b --- /dev/null +++ b/Documentation/sphinx-static/theme_rtd_colors.css @@ -0,0 +1,37 @@ +/* -*- coding: utf-8; mode: css -*- + * + * Sphinx HTML theme customization: color settings for RTD (non-dark) theme + * + */ + +/* Improve contrast and increase size for easier reading. */ + +body { + color: black; +} + +.wy-menu-vertical li.current a { + color: #505050; +} + +.wy-menu-vertical li.on a, .wy-menu-vertical li.current > a { + color: #303030; +} + +div[class^="highlight"] pre { + color: black; +} + +@media screen { + + /* Menu selection and keystrokes */ + + span.menuselection { + color: blue; + } + + code.kbd, code.kbd span { + color: white; + background-color: darkblue; + } +} diff --git a/Documentation/sphinx/automarkup.py b/Documentation/sphinx/automarkup.py index acf5473002f3..cc348b219fca 100644 --- a/Documentation/sphinx/automarkup.py +++ b/Documentation/sphinx/automarkup.py @@ -271,19 +271,30 @@ def get_c_namespace(app, docname): def auto_markup(app, doctree, name): global c_namespace c_namespace = get_c_namespace(app, name) + def text_but_not_a_reference(node): + # The nodes.literal test catches ``literal text``, its purpose is to + # avoid adding cross-references to functions that have been explicitly + # marked with cc:func:. + if not isinstance(node, nodes.Text) or isinstance(node.parent, nodes.literal): + return False + + child_of_reference = False + parent = node.parent + while parent: + if isinstance(parent, nodes.Referential): + child_of_reference = True + break + parent = parent.parent + return not child_of_reference + # # This loop could eventually be improved on. Someday maybe we # want a proper tree traversal with a lot of awareness of which # kinds of nodes to prune. But this works well for now. # - # The nodes.literal test catches ``literal text``, its purpose is to - # avoid adding cross-references to functions that have been explicitly - # marked with cc:func:. - # for para in doctree.traverse(nodes.paragraph): - for node in para.traverse(nodes.Text): - if not isinstance(node.parent, nodes.literal): - node.parent.replace(node, markup_refs(name, app, node)) + for node in para.traverse(condition=text_but_not_a_reference): + node.parent.replace(node, markup_refs(name, app, node)) def setup(app): app.connect('doctree-resolved', auto_markup) diff --git a/Documentation/sphinx/kernel_abi.py b/Documentation/sphinx/kernel_abi.py index efe760e410c4..4392b3cb4020 100644 --- a/Documentation/sphinx/kernel_abi.py +++ b/Documentation/sphinx/kernel_abi.py @@ -104,7 +104,7 @@ class KernelCmd(Directive): return nodeList def runCmd(self, cmd, **kwargs): - u"""Run command ``cmd`` and return it's stdout as unicode.""" + u"""Run command ``cmd`` and return its stdout as unicode.""" try: proc = subprocess.Popen( diff --git a/Documentation/sphinx/kernel_feat.py b/Documentation/sphinx/kernel_feat.py index c91ea2b27697..8138d69a6987 100644 --- a/Documentation/sphinx/kernel_feat.py +++ b/Documentation/sphinx/kernel_feat.py @@ -106,7 +106,7 @@ class KernelFeat(Directive): return nodeList def runCmd(self, cmd, **kwargs): - u"""Run command ``cmd`` and return it's stdout as unicode.""" + u"""Run command ``cmd`` and return its stdout as unicode.""" try: proc = subprocess.Popen( diff --git a/Documentation/spi/pxa2xx.rst b/Documentation/spi/pxa2xx.rst index 6312968acfe9..6347580826be 100644 --- a/Documentation/spi/pxa2xx.rst +++ b/Documentation/spi/pxa2xx.rst @@ -101,8 +101,7 @@ device. All fields are optional. u8 rx_threshold; u8 dma_burst_size; u32 timeout; - u8 enable_loopback; - void (*cs_control)(u32 command); + int gpio_cs; }; The "pxa2xx_spi_chip.tx_threshold" and "pxa2xx_spi_chip.rx_threshold" fields are @@ -128,16 +127,6 @@ dependent on the SPI bus speed ("spi_board_info.max_speed_hz") and the specific slave device. Please note that the PXA2xx SSP 1 does not support trailing byte timeouts and must busy-wait any trailing bytes. -The "pxa2xx_spi_chip.enable_loopback" field is used to place the SSP porting -into internal loopback mode. In this mode the SSP controller internally -connects the SSPTX pin to the SSPRX pin. This is useful for initial setup -testing. - -The "pxa2xx_spi_chip.cs_control" field is used to point to a board specific -function for asserting/deasserting a slave device chip select. If the field is -NULL, the pxa2xx_spi master controller driver assumes that the SSP port is -configured to use GPIO or SSPFRM instead. - NOTE: the SPI driver cannot control the chip select if SSPFRM is used, so the chipselect is dropped after each spi_transfer. Most devices need chip select asserted around the complete message. Use SSPFRM as a GPIO (through a descriptor) @@ -152,30 +141,12 @@ field. Below is a sample configuration using the PXA255 NSSP. :: - /* Chip Select control for the CS8415A SPI slave device */ - static void cs8415a_cs_control(u32 command) - { - if (command & PXA2XX_CS_ASSERT) - GPCR(2) = GPIO_bit(2); - else - GPSR(2) = GPIO_bit(2); - } - - /* Chip Select control for the CS8405A SPI slave device */ - static void cs8405a_cs_control(u32 command) - { - if (command & PXA2XX_CS_ASSERT) - GPCR(3) = GPIO_bit(3); - else - GPSR(3) = GPIO_bit(3); - } - static struct pxa2xx_spi_chip cs8415a_chip_info = { .tx_threshold = 8, /* SSP hardward FIFO threshold */ .rx_threshold = 8, /* SSP hardward FIFO threshold */ .dma_burst_size = 8, /* Byte wide transfers used so 8 byte bursts */ .timeout = 235, /* See Intel documentation */ - .cs_control = cs8415a_cs_control, /* Use external chip select */ + .gpio_cs = 2, /* Use external chip select */ }; static struct pxa2xx_spi_chip cs8405a_chip_info = { @@ -183,7 +154,7 @@ field. Below is a sample configuration using the PXA255 NSSP. .rx_threshold = 8, /* SSP hardward FIFO threshold */ .dma_burst_size = 8, /* Byte wide transfers used so 8 byte bursts */ .timeout = 235, /* See Intel documentation */ - .cs_control = cs8405a_cs_control, /* Use external chip select */ + .gpio_cs = 3, /* Use external chip select */ }; static struct spi_board_info streetracer_spi_board_info[] __initdata = { diff --git a/Documentation/spi/spidev.rst b/Documentation/spi/spidev.rst index f05dbc5ccdbc..369c657ba435 100644 --- a/Documentation/spi/spidev.rst +++ b/Documentation/spi/spidev.rst @@ -29,21 +29,49 @@ of the driver stack) that are not accessible to userspace. DEVICE CREATION, DRIVER BINDING =============================== -The simplest way to arrange to use this driver is to just list it in the -spi_board_info for a device as the driver it should use: the "modalias" -entry is "spidev", matching the name of the driver exposing this API. -Set up the other device characteristics (bits per word, SPI clocking, -chipselect polarity, etc) as usual, so you won't always need to override -them later. -(Sysfs also supports userspace driven binding/unbinding of drivers to -devices. That mechanism might be supported here in the future.) +The spidev driver contains lists of SPI devices that are supported for +the different hardware topology representations. -When you do that, the sysfs node for the SPI device will include a child -device node with a "dev" attribute that will be understood by udev or mdev. -(Larger systems will have "udev". Smaller ones may configure "mdev" into -busybox; it's less featureful, but often enough.) For a SPI device with -chipselect C on bus B, you should see: +The following are the SPI device tables supported by the spidev driver: + + - struct spi_device_id spidev_spi_ids[]: list of devices that can be + bound when these are defined using a struct spi_board_info with a + .modalias field matching one of the entries in the table. + + - struct of_device_id spidev_dt_ids[]: list of devices that can be + bound when these are defined using a Device Tree node that has a + compatible string matching one of the entries in the table. + + - struct acpi_device_id spidev_acpi_ids[]: list of devices that can + be bound when these are defined using a ACPI device object with a + _HID matching one of the entries in the table. + +You are encouraged to add an entry for your SPI device name to relevant +tables, if these don't already have an entry for the device. To do that, +post a patch for spidev to the linux-spi@vger.kernel.org mailing list. + +It used to be supported to define an SPI device using the "spidev" name. +For example, as .modalias = "spidev" or compatible = "spidev". But this +is no longer supported by the Linux kernel and instead a real SPI device +name as listed in one of the tables must be used. + +Not having a real SPI device name will lead to an error being printed and +the spidev driver failing to probe. + +Sysfs also supports userspace driven binding/unbinding of drivers to +devices that do not bind automatically using one of the tables above. +To make the spidev driver bind to such a device, use the following: + + echo spidev > /sys/bus/spi/devices/spiB.C/driver_override + echo spiB.C > /sys/bus/spi/drivers/spidev/bind + +When the spidev driver is bound to a SPI device, the sysfs node for the +device will include a child device node with a "dev" attribute that will +be understood by udev or mdev (udev replacement from BusyBox; it's less +featureful, but often enough). + +For a SPI device with chipselect C on bus B, you should see: /dev/spidevB.C ... character special device, major number 153 with diff --git a/Documentation/trace/boottime-trace.rst b/Documentation/trace/boottime-trace.rst index 6dcfbc64014d..d594597201fd 100644 --- a/Documentation/trace/boottime-trace.rst +++ b/Documentation/trace/boottime-trace.rst @@ -131,9 +131,7 @@ Ftrace Histogram Options Since it is too long to write a histogram action as a string for per-event action option, there are tree-style options under per-event 'hist' subkey for the histogram actions. For the detail of the each parameter, -please read the event histogram document [3]_. - -.. [3] See :ref:`Documentation/trace/histogram.rst ` +please read the event histogram document (Documentation/trace/histogram.rst) ftrace.[instance.INSTANCE.]event.GROUP.EVENT.hist.[N.]keys = KEY1[, KEY2[...]] Set histogram key parameters. (Mandatory) diff --git a/Documentation/translations/it_IT/process/submitting-patches.rst b/Documentation/translations/it_IT/process/submitting-patches.rst index c2fb712a1377..4fb5b3aa306d 100644 --- a/Documentation/translations/it_IT/process/submitting-patches.rst +++ b/Documentation/translations/it_IT/process/submitting-patches.rst @@ -276,25 +276,6 @@ cosicché l'informazione possa trovare la sua strada nel manuale. Le modifiche all'API dello spazio utente dovrebbero essere inviate in copia anche a linux-api@vger.kernel.org. -Per le piccole patch potreste aggiungere in CC l'indirizzo -*Trivial Patch Monkey trivial@kernel.org* che ha lo scopo di raccogliere -le patch "banali". Date uno sguardo al file MAINTAINERS per vedere chi -è l'attuale amministratore. - -Le patch banali devono rientrare in una delle seguenti categorie: - -- errori grammaticali nella documentazione -- errori grammaticali negli errori che potrebbero rompere :manpage:`grep(1)` -- correzione di avvisi di compilazione (riempirsi di avvisi inutili è negativo) -- correzione di errori di compilazione (solo se correggono qualcosa sul serio) -- rimozione di funzioni/macro deprecate -- sostituzione di codice non potabile con uno portabile (anche in codice - specifico per un'architettura, dato che le persone copiano, fintanto che - la modifica sia banale) -- qualsiasi modifica dell'autore/manutentore di un file (in pratica - "patch monkey" in modalità ritrasmissione) - - Niente: MIME, links, compressione, allegati. Solo puro testo ------------------------------------------------------------- diff --git a/Documentation/translations/ja_JP/SubmittingPatches b/Documentation/translations/ja_JP/SubmittingPatches index 6854f5add72e..0d308edef781 100644 --- a/Documentation/translations/ja_JP/SubmittingPatches +++ b/Documentation/translations/ja_JP/SubmittingPatches @@ -208,21 +208,6 @@ VGER.KERNEL.ORG でホスティングされているメーリングリストの たとえ、メンテナが #5 で反応がなかったとしても、メンテナのコードに変更を 加えたときには、いつもメンテナに CC するのを忘れないようにしてください。 -小さなパッチであれば、Trivial Patch Monkey(ちょっとしたパッチを集めている) -に CC してもいいです。その現管理者については MAINTAINERS -ファイルを見てください。ちょっとしたパッチとは以下のルールのどれか1つを満たして -いなければなりません。 - ・ドキュメントのスペルミスの修正 - ・grep(1) コマンドによる検索を困難にしているスペルの修正 - ・コンパイル時の警告の修正(無駄な警告が散乱することは好ましくないた - めです) - ・コンパイル問題の修正(それらの修正が本当に正しい場合に限る) - ・実行時の問題の修正(それらの修正が本当に問題を修正している場合に限る) - ・廃止予定の関数やマクロを使用しているコードの除去(例 check_region ) - ・問い合わせ先やドキュメントの修正 - ・移植性のないコードから移植性のあるコードへの置き換え(小さい範囲で - あればアーキテクチャ特有のことでも他の人がコピーできます) - ・作者やメンテナによる修正(すなわち patch monkey の再転送モード) 7) MIME やリンクや圧縮ファイルや添付ファイルではなくプレインテキストのみ diff --git a/Documentation/translations/zh_CN/PCI/index.rst b/Documentation/translations/zh_CN/PCI/index.rst index 5c96017e9f41..16acb2bd9b58 100644 --- a/Documentation/translations/zh_CN/PCI/index.rst +++ b/Documentation/translations/zh_CN/PCI/index.rst @@ -22,13 +22,14 @@ Linux PCI总线子系统 :numbered: pci - -Todolist: - pciebus-howto pci-iov-howto msi-howto sysfs-pci + + +Todolist: + acpi-info pci-error-recovery pcieaer-howto diff --git a/Documentation/translations/zh_CN/PCI/msi-howto.rst b/Documentation/translations/zh_CN/PCI/msi-howto.rst new file mode 100644 index 000000000000..7ea4d50cdad2 --- /dev/null +++ b/Documentation/translations/zh_CN/PCI/msi-howto.rst @@ -0,0 +1,233 @@ +.. SPDX-License-Identifier: GPL-2.0 +.. include:: +.. include:: ../disclaimer-zh_CN.rst + +:Original: Documentation/PCI/msi-howto.rst + +:翻译: + + 司延腾 Yanteng Si + +:校译: + + + +=========== +MSI驱动指南 +=========== + +:作者: Tom L Nguyen; Martine Silbermann; Matthew Wilcox + +:版权: 2003, 2008 Intel Corporation + +关于本指南 +========== + +本指南介绍了消息标记中断（MSI）的基本知识，使用MSI相对于传统中断机制的优势，如何 +改变你的驱动程序以使用MSI或MSI-X，以及在设备不支持MSI时可以尝试的一些基本诊断方法。 + + +什么是MSI? +========== + +信息信号中断是指从设备写到一个特殊的地址，导致CPU接收到一个中断。 + +MSI能力首次在PCI 2.2中规定，后来在PCI 3.0中得到增强，允许对每个中断进行单独屏蔽。 +MSI-X功能也随着PCI 3.0被引入。它比MSI支持每个设备更多的中断，并允许独立配置中断。 + +设备可以同时支持MSI和MSI-X，但一次只能启用一个。 + + +为什么用MSI? +============ + +有三个原因可以说明为什么使用MSI比传统的基于针脚的中断有优势。 + +基于针脚的PCI中断通常在几个设备之间共享。为了支持这一点，内核必须调用每个与中断相 +关的中断处理程序，这导致了整个系统性能的降低。MSI从不共享，所以这个问题不会出现。 + +当一个设备将数据写入内存，然后引发一个基于引脚的中断时，有可能在所有的数据到达内存 +之前，中断就已经到达了（这在PCI-PCI桥后面的设备中变得更有可能）。为了确保所有的数 +据已经到达内存中，中断处理程序必须在引发中断的设备上读取一个寄存器。PCI事务排序规 +则要求所有的数据在返回寄存器的值之前到达内存。使用MSI可以避免这个问题，因为中断产 +生的写入不能通过数据写入，所以当中断发生时，驱动程序知道所有的数据已经到达内存中。 + +PCI设备每个功能只能支持一个基于引脚的中断。通常情况下，驱动程序必须查询设备以找出 +发生了什么事件，这就减慢了对常见情况的中断处理。有了MSI，设备可以支持更多的中断， +允许每个中断被专门用于不同的目的。一种可能的设计是给不经常发生的情况（如错误）提供 +自己的中断，这使得驱动程序可以更有效地处理正常的中断处理路径。其他可能的设计包括给 +网卡的每个数据包队列或存储控制器的每个端口提供一个中断。 + + +如何使用MSI +=========== + +PCI设备被初始化为使用基于引脚的中断。设备驱动程序必须将设备设置为使用MSI或MSI-X。 +并非所有的机器都能正确地支持MSI，对于这些机器，下面描述的API将简单地失败，设备将 +继续使用基于引脚的中断。 + +加入内核对MSI的支持 +------------------- + +为了支持MSI或MSI-X，内核在构建时必须启用CONFIG_PCI_MSI选项。这个选项只在某些架 +构上可用，而且它可能取决于其他一些选项的设置。例如，在x86上，你必须同时启用X86_UP_APIC +或SMP，才能看到CONFIG_PCI_MSI选项。 + +使用MSI +------- + +大部分沉重的工作是在PCI层为驱动程序完成的。驱动程序只需要请求PCI层为这个设备设置 +MSI功能。 + +要自动使用MSI或MSI-X中断向量，请使用以下函数:: + + int pci_alloc_irq_vectors(struct pci_dev *dev, unsigned int min_vecs, + unsigned int max_vecs, unsigned int flags); + +它为一个PCI设备分配最多至max_vecs的中断向量。它返回分配的向量数量或一个负的错误。 +如果设备对最小数量的向量有要求，驱动程序可以传递一个min_vecs参数，设置为这个限制， +如果PCI核不能满足最小数量的向量，将返回-ENOSPC。 + +flags参数用来指定设备和驱动程序可以使用哪种类型的中断（PCI_IRQ_LEGACY, PCI_IRQ_MSI, +PCI_IRQ_MSIX）。一个方便的短语（PCI_IRQ_ALL_TYPES）也可以用来要求任何可能的中断类型。 +如果PCI_IRQ_AFFINITY标志被设置，pci_alloc_irq_vectors()将把中断分散到可用的CPU上。 + +要获得传递给require_irq()和free_irq()的Linux IRQ号码和向量，请使用以下函数:: + + int pci_irq_vector(struct pci_dev *dev, unsigned int nr); + +在删除设备之前，应使用以下功能释放任何已分配的资源:: + + void pci_free_irq_vectors(struct pci_dev *dev); + +如果一个设备同时支持MSI-X和MSI功能，这个API将优先使用MSI-X，而不是MSI。MSI-X支 +持1到2048之间的任何数量的中断。相比之下，MSI被限制为最多32个中断（而且必须是2的幂）。 +此外，MSI中断向量必须连续分配，所以系统可能无法为MSI分配像MSI-X那样多的向量。在一 +些平台上，MSI中断必须全部针对同一组CPU，而MSI-X中断可以全部针对不同的CPU。 + +如果一个设备既不支持MSI-X，也不支持MSI，它就会退回到一个传统的IRQ向量。 + +MSI或MSI-X中断的典型用法是分配尽可能多的向量，可能达到设备支持的极限。如果nvec大于 +设备支持的数量，它将自动被限制在支持的限度内，所以没有必要事先查询支持的向量的数量。:: + + nvec = pci_alloc_irq_vectors(pdev, 1, nvec, PCI_IRQ_ALL_TYPES) + if (nvec < 0) + goto out_err; + +如果一个驱动程序不能或不愿意处理可变数量的MSI中断，它可以要求一个特定数量的中断，将该 +数量作为“min_vecs“和“max_vecs“参数传递给pci_alloc_irq_vectors()函数。:: + + ret = pci_alloc_irq_vectors(pdev, nvec, nvec, PCI_IRQ_ALL_TYPES); + if (ret < 0) + goto out_err; + +上述请求类型的最臭名昭著的例子是为一个设备启用单一的MSI模式。它可以通过传递两个1作为 +'min_vecs'和'max_vecs'来实现:: + + ret = pci_alloc_irq_vectors(pdev, 1, 1, PCI_IRQ_ALL_TYPES); + if (ret < 0) + goto out_err; + +一些设备可能不支持使用传统的线路中断，在这种情况下，驱动程序可以指定只接受MSI或MSI-X。:: + + nvec = pci_alloc_irq_vectors(pdev, 1, nvec, PCI_IRQ_MSI | PCI_IRQ_MSIX); + if (nvec < 0) + goto out_err; + +传统API +----------- + +以下用于启用和禁用MSI或MSI-X中断的旧API不应该在新代码中使用:: + + pci_enable_msi() /* deprecated */ + pci_disable_msi() /* deprecated */ + pci_enable_msix_range() /* deprecated */ + pci_enable_msix_exact() /* deprecated */ + pci_disable_msix() /* deprecated */ + +此外，还有一些API来提供支持的MSI或MSI-X向量的数量：pci_msi_vec_count()和 +pci_msix_vec_count()。一般来说，应该避免使用这些方法，而是让pci_alloc_irq_vectors() +来限制向量的数量。如果你对向量的数量有合法的特殊用例，我们可能要重新审视这个决定， +并增加一个pci_nr_irq_vectors()助手，透明地处理MSI和MSI-X。 + +使用MSI时需要考虑的因素 +----------------------- + +自旋锁 +~~~~~~ + +大多数设备驱动程序都有一个每的自旋锁，在中断处理程序中被占用。对于基于引脚的中断 +或单一的MSI，没有必要禁用中断（Linux保证同一中断不会被重新输入）。如果一个设备 +使用多个中断，驱动程序必须在锁被持有的时候禁用中断。如果设备发出一个不同的中断， +驱动程序将死锁，试图递归地获取自旋锁。这种死锁可以通过使用spin_lock_irqsave() +或spin_lock_irq()来避免，它们可以禁用本地中断并获取锁（见《不可靠的锁定指南》）。 + +如何判断一个设备上是否启用了MSI/MSI-X +------------------------------------- + +使用“lspci -v“（以root身份）可能会显示一些具有“MSI“、“Message Signalled Interrupts“ +或“MSI-X“功能的设备。这些功能中的每一个都有一个“启用“标志，后面是“+“（启用） +或“-“（禁用）。 + + +MSI特性 +======= + +众所周知，一些PCI芯片组或设备不支持MSI。PCI协议栈提供了三种禁用MSI的方法: + +1. 全局的 +2. 在一个特定的桥后面的所有设备上 +3. 在单一设备上 + +全局禁用MSI +----------- + +一些主控芯片组根本无法正确支持MSI。如果我们幸运的话，制造商知道这一点，并在 +ACPI FADT表中指明了它。在这种情况下，Linux会自动禁用MSI。有些板卡在表中没 +有包括这一信息，因此我们必须自己检测它们。完整的列表可以在drivers/pci/quirks.c +中的quirk_disable_all_msi()函数附近找到。 + +如果你有一块有MSI问题的板子，你可以在内核命令行中传递pci=nomsi来禁用所有设 +备上的MSI。你最好把问题报告给linux-pci@vger.kernel.org，包括完整的 +“lspci -v“，这样我们就可以把这些怪癖添加到内核中。 + +禁用桥下的MSI +------------- + +一些PCI桥接器不能在总线之间正确地路由MSI。在这种情况下，必须在桥接器后面的所 +有设备上禁用MSI。 + +一些桥接器允许你通过改变PCI配置空间的一些位来启用MSI（特别是Hypertransport +芯片组，如nVidia nForce和Serverworks HT2000）。与主机芯片组一样，Linux大 +多知道它们，如果可以的话，会自动启用MSI。如果你有一个Linux不知道的网桥，你可以 +用你知道的任何方法在配置空间中启用MSI，然后通过以下方式在该网桥上启用MSI:: + + echo 1 > /sys/bus/pci/devices/$bridge/msi_bus + +其中$bridge是你所启用的桥的PCI地址（例如0000:00:0e.0）。 + +要禁用MSI，请回显0而不是1。改变这个值应该谨慎进行，因为它可能会破坏这个桥下面所 +有设备的中断处理。 + +同样，请通知 linux-pci@vger.kernel.org 任何需要特殊处理的桥。 + +在单一设备上关闭MSIs +-------------------- + +众所周知，有些设备的MSI实现是有问题的。通常情况下，这是在单个设备驱动程序中处理的， +但偶尔也有必要用一个古怪的方法来处理。一些驱动程序有一个选项可以禁用MSI的使用。虽然 +这对驱动程序的作者来说是一个方便的变通办法，但这不是一个好的做法，不应该被模仿。 + +寻找设备上MSI被禁用的原因 +------------------------- + +从以上三个部分，你可以看到有许多原因导致MSI没有在某个设备上被启用。你的第一步应该是 +仔细检查你的dmesg以确定你的机器是否启用了MSI。你还应该检查你的.config以确定你已经 +启用了CONFIG_PCI_MSI。 + +然后，“lspci -t“给出一个设备上面的网列表。读取 ``/sys/bus/pci/devices/*/msi_bus`` +将告诉你MSI是否被启用（1）或禁用（0）。如果在任何属于PCI根和设备之间的桥的msi_bus +文件中发现0，说明MSI被禁用。 + +也需要检查设备驱动程序，看它是否支持MSI。例如，它可能包含对带有PCI_IRQ_MSI或 +PCI_IRQ_MSIX标志的pci_alloc_irq_vectors（）的调用。 diff --git a/Documentation/translations/zh_CN/PCI/pci-iov-howto.rst b/Documentation/translations/zh_CN/PCI/pci-iov-howto.rst new file mode 100644 index 000000000000..fbc83dfdcead --- /dev/null +++ b/Documentation/translations/zh_CN/PCI/pci-iov-howto.rst @@ -0,0 +1,170 @@ +.. SPDX-License-Identifier: GPL-2.0 +.. include:: +.. include:: ../disclaimer-zh_CN.rst + +:Original: Documentation/PCI/pci-iov-howto.rst + +:翻译: + + 司延腾 Yanteng Si + +:校译: + + + +.. _cn_pci-iov-howto: + +========================== +PCI Express I/O 虚拟化指南 +========================== + +:版权: |copy| 2009 Intel Corporation +:作者: - Yu Zhao + - Donald Dutile + +概述 +==== + +什么是SR-IOV +------------ + +单根I/O虚拟化（SR-IOV）是一种PCI Express扩展功能，它使一个物理设备显示为多个 +虚拟设备。物理设备被称为物理功能（PF），而虚拟设备被称为虚拟功能（VF）。VF的分 +配可以由PF通过封装在该功能中的寄存器动态控制。默认情况下，该功能未被启用，PF表 +现为传统的PCIe设备。一旦开启，每个VF的PCI配置空间都可以通过自己的总线、设备和 +功能编号（路由ID）来访问。而且每个VF也有PCI内存空间，用于映射其寄存器集。VF设 +备驱动程序对寄存器集进行操作，这样它就可以发挥功能，并作为一个真正的现有PCI设备 +出现。 + +使用指南 +======== + +我怎样才能启用SR-IOV功能 +------------------------ + +有多种方法可用于SR-IOV的启用。在第一种方法中，设备驱动（PF驱动）将通过SR-IOV +核心提供的API控制功能的启用和禁用。如果硬件具有SR-IOV能力，加载其PF驱动器将启 +用它和与PF相关的所有VF。一些PF驱动需要设置一个模块参数，以确定要启用的VF的数量。 +在第二种方法中，对sysfs文件sriov_numvfs的写入将启用和禁用与PCIe PF相关的VF。 +这种方法实现了每个PF的VF启用/禁用值，而第一种方法则适用于同一设备的所有PF。此外， +PCI SRIOV核心支持确保启用/禁用操作是有效的，以减少同一检查在多个驱动程序中的重 +复，例如，如果启用VF，检查numvfs == 0，确保numvfs <= totalvfs。 +第二种方法是对新的/未来的VF设备的推荐方法。 + +我怎样才能使用虚拟功能 +---------------------- + +在内核中，VF被视为热插拔的PCI设备，所以它们应该能够以与真正的PCI设备相同的方式 +工作。VF需要的设备驱动与普通PCI设备的驱动相同。 + +开发者指南 +========== + +SR-IOV API +---------- + +用来开启SR-IOV功能: + +(a) 对于第一种方法，在驱动程序中:: + + int pci_enable_sriov(struct pci_dev *dev, int nr_virtfn); + +nr_virtfn'是要启用的VF的编号。 + +(b) 对于第二种方法，从sysfs:: + + echo 'nr_virtfn' > \ + /sys/bus/pci/devices//sriov_numvfs + +用来关闭SR-IOV功能: + +(a) 对于第一种方法，在驱动程序中:: + + void pci_disable_sriov(struct pci_dev *dev); + +(b) 对于第二种方法，从sysfs:: + + echo 0 > \ + /sys/bus/pci/devices//sriov_numvfs + +要想通过主机上的兼容驱动启用自动探测VF，在启用SR-IOV功能之前运行下面的命令。这 +是默认的行为。 +:: + + echo 1 > \ + /sys/bus/pci/devices//sriov_drivers_autoprobe + +要禁止主机上的兼容驱动自动探测VF，请在启用SR-IOV功能之前运行以下命令。更新这个 +入口不会影响已经被探测的VF。 +:: + + echo 0 > \ + /sys/bus/pci/devices//sriov_drivers_autoprobe + +用例 +---- + +下面的代码演示了SR-IOV API的用法 +:: + + static int dev_probe(struct pci_dev *dev, const struct pci_device_id *id) + { + pci_enable_sriov(dev, NR_VIRTFN); + + ... + + return 0; + } + + static void dev_remove(struct pci_dev *dev) + { + pci_disable_sriov(dev); + + ... + } + + static int dev_suspend(struct pci_dev *dev, pm_message_t state) + { + ... + + return 0; + } + + static int dev_resume(struct pci_dev *dev) + { + ... + + return 0; + } + + static void dev_shutdown(struct pci_dev *dev) + { + ... + } + + static int dev_sriov_configure(struct pci_dev *dev, int numvfs) + { + if (numvfs > 0) { + ... + pci_enable_sriov(dev, numvfs); + ... + return numvfs; + } + if (numvfs == 0) { + .... + pci_disable_sriov(dev); + ... + return 0; + } + } + + static struct pci_driver dev_driver = { + .name = "SR-IOV Physical Function driver", + .id_table = dev_id_table, + .probe = dev_probe, + .remove = dev_remove, + .suspend = dev_suspend, + .resume = dev_resume, + .shutdown = dev_shutdown, + .sriov_configure = dev_sriov_configure, + }; diff --git a/Documentation/translations/zh_CN/PCI/pciebus-howto.rst b/Documentation/translations/zh_CN/PCI/pciebus-howto.rst new file mode 100644 index 000000000000..65c4301f12cd --- /dev/null +++ b/Documentation/translations/zh_CN/PCI/pciebus-howto.rst @@ -0,0 +1,192 @@ +.. SPDX-License-Identifier: GPL-2.0 +.. include:: +.. include:: ../disclaimer-zh_CN.rst + +:Original: Documentation/PCI/pciebus-howto.rst + +:翻译: + + 司延腾 Yanteng Si + +:校译: + + + +.. _cn_pciebus-howto: + +=========================== +PCI Express端口总线驱动指南 +=========================== + +:作者: Tom L Nguyen tom.l.nguyen@intel.com 11/03/2004 +:版权: |copy| 2004 Intel Corporation + +关于本指南 +========== + +本指南介绍了PCI Express端口总线驱动程序的基本知识，并提供了如何使服务驱 +动程序在PCI Express端口总线驱动程序中注册/取消注册的介绍。 + + +什么是PCI Express端口总线驱动程序 +================================= + +一个PCI Express端口是一个逻辑的PCI-PCI桥结构。有两种类型的PCI Express端 +口：根端口和交换端口。根端口从PCI Express根综合体发起一个PCI Express链接， +交换端口将PCI Express链接连接到内部逻辑PCI总线。交换机端口，其二级总线代表 +交换机的内部路由逻辑，被称为交换机的上行端口。交换机的下行端口是从交换机的内部 +路由总线桥接到代表来自PCI Express交换机的下游PCI Express链接的总线。 + +一个PCI Express端口可以提供多达四个不同的功能，在本文中被称为服务，这取决于 +其端口类型。PCI Express端口的服务包括本地热拔插支持（HP）、电源管理事件支持（PME）、 +高级错误报告支持（AER）和虚拟通道支持（VC）。这些服务可以由一个复杂的驱动程序 +处理，也可以单独分布并由相应的服务驱动程序处理。 + +为什么要使用PCI Express端口总线驱动程序？ +========================================= + +在现有的Linux内核中，Linux设备驱动模型允许一个物理设备只由一个驱动处理。 +PCI Express端口是一个具有多个不同服务的PCI-PCI桥设备。为了保持一个干净和简 +单的解决方案，每个服务都可以有自己的软件服务驱动。在这种情况下，几个服务驱动将 +竞争一个PCI-PCI桥设备。例如，如果PCI Express根端口的本机热拔插服务驱动程序 +首先被加载，它就会要求一个PCI-PCI桥根端口。因此，内核不会为该根端口加载其他服 +务驱动。换句话说，使用当前的驱动模型，不可能让多个服务驱动同时加载并运行在 +PCI-PCI桥设备上。 + +为了使多个服务驱动程序同时运行，需要有一个PCI Express端口总线驱动程序，它管 +理所有填充的PCI Express端口，并根据需要将所有提供的服务请求分配给相应的服务 +驱动程序。下面列出了使用PCI Express端口总线驱动程序的一些关键优势: + + - 允许在一个PCI-PCI桥接端口设备上同时运行多个服务驱动。 + + - 允许以独立的分阶段方式实施服务驱动程序。 + + - 允许一个服务驱动程序在多个PCI-PCI桥接端口设备上运行。 + + - 管理和分配PCI-PCI桥接端口设备的资源给要求的服务驱动程序。 + +配置PCI Express端口总线驱动程序与服务驱动程序 +============================================= + +将PCI Express端口总线驱动支持纳入内核 +------------------------------------- + +包括PCI Express端口总线驱动程序取决于内核配置中是否包含PCI Express支持。当内核 +中的PCI Express支持被启用时，内核将自动包含PCI Express端口总线驱动程序作为内核 +驱动程序。 + +启用服务驱动支持 +---------------- + +PCI设备驱动是基于Linux设备驱动模型实现的。所有的服务驱动都是PCI设备驱动。如上所述， +一旦内核加载了PCI Express端口总线驱动程序，就不可能再加载任何服务驱动程序。为了满 +足PCI Express端口总线驱动程序模型，需要对现有的服务驱动程序进行一些最小的改变，其 +对现有的服务驱动程序的功能没有影响。 + +服务驱动程序需要使用下面所示的两个API，将其服务注册到PCI Express端口总线驱动程 +序中（见第5.2.1和5.2.2节）。在调用这些API之前，服务驱动程序必须初始化头文件 +/include/linux/pcieport_if.h中的pcie_port_service_driver数据结构。如果不这 +样做，将导致身份不匹配，从而使PCI Express端口总线驱动程序无法加载服务驱动程序。 + +pcie_port_service_register +~~~~~~~~~~~~~~~~~~~~~~~~~~ +:: + + int pcie_port_service_register(struct pcie_port_service_driver *new) + +这个API取代了Linux驱动模型的 pci_register_driver API。一个服务驱动应该总是在模 +块启动时调用 pcie_port_service_register。请注意，在服务驱动被加载后，诸如 +pci_enable_device(dev) 和 pci_set_master(dev) 的调用不再需要，因为这些调用由 +PCI端口总线驱动执行。 + +pcie_port_service_unregister +~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +:: + + void pcie_port_service_unregister(struct pcie_port_service_driver *new) + +pcie_port_service_unregister取代了Linux驱动模型的pci_unregister_driver。当一 +个模块退出时，它总是被服务驱动调用。 + +示例代码 +~~~~~~~~ + +下面是服务驱动代码示例，用于初始化端口服务的驱动程序数据结构。 +:: + + static struct pcie_port_service_id service_id[] = { { + .vendor = PCI_ANY_ID, + .device = PCI_ANY_ID, + .port_type = PCIE_RC_PORT, + .service_type = PCIE_PORT_SERVICE_AER, + }, { /* end: all zeroes */ } + }; + + static struct pcie_port_service_driver root_aerdrv = { + .name = (char *)device_name, + .id_table = &service_id[0], + + .probe = aerdrv_load, + .remove = aerdrv_unload, + + .suspend = aerdrv_suspend, + .resume = aerdrv_resume, + }; + +下面是一个注册/取消注册服务驱动的示例代码。 +:: + + static int __init aerdrv_service_init(void) + { + int retval = 0; + + retval = pcie_port_service_register(&root_aerdrv); + if (!retval) { + /* + * FIX ME + */ + } + return retval; + } + + static void __exit aerdrv_service_exit(void) + { + pcie_port_service_unregister(&root_aerdrv); + } + + module_init(aerdrv_service_init); + module_exit(aerdrv_service_exit); + +可能的资源冲突 +============== + +由于PCI-PCI桥接端口设备的所有服务驱动被允许同时运行，下面列出了一些可能的资源冲突和 +建议的解决方案。 + +MSI 和 MSI-X 向量资源 +--------------------- + +一旦设备上的MSI或MSI-X中断被启用，它就会一直保持这种模式，直到它们再次被禁用。由于同 +一个PCI-PCI桥接端口的服务驱动程序共享同一个物理设备，如果一个单独的服务驱动程序启用或 +禁用MSI/MSI-X模式，可能会导致不可预知的行为。 + +为了避免这种情况，所有的服务驱动程序都不允许在其设备上切换中断模式。PCI Express端口 +总线驱动程序负责确定中断模式，这对服务驱动程序来说应该是透明的。服务驱动程序只需要知道 +分配给结构体pcie_device的字段irq的向量IRQ，当PCI Express端口总线驱动程序探测每 +个服务驱动程序时，它被传入。服务驱动应该使用（struct pcie_device*）dev->irq来调用 +request_irq/free_irq。此外，中断模式被存储在struct pcie_device的interrupt_mode +字段中。 + +PCI内存/IO映射的区域 +-------------------- + +PCI Express电源管理（PME）、高级错误报告（AER）、热插拔（HP）和虚拟通道（VC）的服务 +驱动程序访问PCI Express端口的PCI配置空间。在所有情况下，访问的寄存器是相互独立的。这 +个补丁假定所有的服务驱动程序都会表现良好，不会覆盖其他服务驱动程序的配置设置。 + +PCI配置寄存器 +------------- + +每个服务驱动都在自己的功能结构体上运行PCI配置操作，除了PCI Express功能结构体，其中根控制 +寄存器和设备控制寄存器是在PME和AER之间共享。这个补丁假定所有的服务驱动都会表现良好，不会 +覆盖其他服务驱动的配置设置。 diff --git a/Documentation/translations/zh_CN/PCI/sysfs-pci.rst b/Documentation/translations/zh_CN/PCI/sysfs-pci.rst new file mode 100644 index 000000000000..0d75c2e99d52 --- /dev/null +++ b/Documentation/translations/zh_CN/PCI/sysfs-pci.rst @@ -0,0 +1,126 @@ +.. SPDX-License-Identifier: GPL-2.0 +.. include:: ../disclaimer-zh_CN.rst + +:Original: Documentation/PCI/sysfs-pci.rst + +:翻译: + + 司延腾 Yanteng Si + +:校译: + + + +======================== +通过sysfs访问PCI设备资源 +======================== + +sysfs，通常挂载在/sys，在支持它的平台上提供对PCI资源的访问。例如，一个特定的总线可能看起 +来像这样:: + + /sys/devices/pci0000:17 + |-- 0000:17:00.0 + | |-- class + | |-- config + | |-- device + | |-- enable + | |-- irq + | |-- local_cpus + | |-- remove + | |-- resource + | |-- resource0 + | |-- resource1 + | |-- resource2 + | |-- revision + | |-- rom + | |-- subsystem_device + | |-- subsystem_vendor + | `-- vendor + `-- ... + +最上面的元素描述了PCI域和总线号码。在这种情况下，域号是0000，总线号是17（两个值都是十六进制）。 +这个总线在0号插槽中包含一个单一功能的设备。为了方便起见，我们复制了域和总线的编号。在设备目录 +下有几个文件，每个文件都有自己的功能。 + + =================== ===================================================== + 文件 功能 + =================== ===================================================== + class PCI级别 (ascii, ro) + config PCI配置空间 (binary, rw) + device PCI设备 (ascii, ro) + enable 设备是否被启用 (ascii, rw) + irq IRQ编号 (ascii, ro) + local_cpus 临近CPU掩码(cpumask, ro) + remove 从内核的列表中删除设备 (ascii, wo) + resource PCI资源主机地址 (ascii, ro) + resource0..N PCI资源N，如果存在的话 (binary, mmap, rw\ [1]_) + resource0_wc..N_wc PCI WC映射资源N，如果可预取的话 (binary, mmap) + revision PCI修订版 (ascii, ro) + rom PCI ROM资源，如果存在的话 (binary, ro) + subsystem_device PCI子系统设备 (ascii, ro) + subsystem_vendor PCI子系统供应商 (ascii, ro) + vendor PCI供应商 (ascii, ro) + =================== ===================================================== + +:: + + ro - 只读文件 + rw - 文件是可读和可写的 + wo - 只写文件 + mmap - 文件是可移动的 + ascii - 文件包含ascii文本 + binary - 文件包含二进制数据 + cpumask - 文件包含一个cpumask类型的 + +.. [1] rw 仅适用于 IORESOURCE_IO（I/O 端口）区域 + +只读文件是信息性的，对它们的写入将被忽略，但 "rom "文件除外。可写文件可以用来在设备上执 +行操作（例如，改变配置空间，分离设备）。 mmapable文件可以通过偏移量为0的文件的mmap获得， +可以用来从用户空间进行实际的设备编程。注意，有些平台不支持某些资源的mmapping，所以一定要 +检查任何尝试的mmap的返回值。其中最值得注意的是I/O端口资源，它也提供读/写访问。 + +enable "文件提供了一个计数器，表明设备已经被启用了多少次。如果'enable'文件目前返回'4'， +而一个'1'被呼入它，它将返回'5'。向它呼入一个'0'会减少计数。不过，即使它返回到0，一些初始 +化可能也不会被逆转。 + +rom "文件很特别，因为它提供了对设备ROM文件的只读访问，如果有的话。然而，它在默认情况下是 +禁用的，所以应用程序应该在尝试读取调用之前将字符串 "1 "写入该文件以启用它，并在访问之后将 +"0 "写入该文件以禁用它。请注意，设备必须被启用，才能成功返回数据。如果驱动没有被绑定到设备 +上，可以使用上面提到的 "enable "文件将其启用。 + +remove "文件是用来移除PCI设备的，通过向该文件写入一个非零的整数。这并不涉及任何形式的热插 +拔功能，例如关闭设备的电源。该设备被从内核的PCI设备列表中移除，它的sysfs目录被移除，并且该 +设备将被从任何连接到它的驱动程序中移除。移除PCI根总线是不允许的。 + +通过sysfs访问原有资源 +--------------------- + +如果底层平台支持的话，传统的I/O端口和ISA内存资源也会在sysfs中提供。它们位于PCI类的层次结构 +中，例如:: + + /sys/class/pci_bus/0000:17/ + |-- bridge -> ../../../devices/pci0000:17 + |-- cpuaffinity + |-- legacy_io + `-- legacy_mem + +legacy_io文件是一个读/写文件，可以被应用程序用来做传统的端口I/O。应用程序应该打开该文件，寻 +找所需的端口（例如0x3e8），并进行1、2或4字节的读或写。legacy_mem文件应该被mmapped，其偏移 +量与所需的内存偏移量相对应，例如0xa0000用于VGA帧缓冲器。然后，应用程序可以简单地解除引用返回 +的指针（当然是在检查了错误之后）来访问遗留内存空间。 + +支持新平台上的PCI访问 +--------------------- + +为了支持上述的PCI资源映射，Linux平台代码最好定义ARCH_GENERIC_PCI_MMAP_RESOURCE并使用该 +功能的通用实现。为了支持通过/proc/bus/pci中的文件实现mmap()的历史接口，平台也可以设置 +HAVE_PCI_MMAP。 + +另外，设置了 HAVE_PCI_MMAP 的平台可以提供他们自己的 pci_mmap_page_range() 实现，而不是定 +义 ARCH_GENERIC_PCI_MMAP_RESOURCE。 + +支持PCI资源的写组合映射的平台必须定义arch_can_pci_mmap_wc()，当写组合被允许时，在运行时应 +评估为非零。支持I/O资源映射的平台同样定义arch_can_pci_mmap_io()。 + +遗留资源由HAVE_PCI_LEGACY定义保护。希望支持遗留功能的平台应该定义它并提供 pci_legacy_read, +pci_legacy_write 和 pci_mmap_legacy_page_range 函数。 diff --git a/Documentation/translations/zh_CN/accounting/delay-accounting.rst b/Documentation/translations/zh_CN/accounting/delay-accounting.rst new file mode 100644 index 000000000000..67d5606e5401 --- /dev/null +++ b/Documentation/translations/zh_CN/accounting/delay-accounting.rst @@ -0,0 +1,111 @@ +.. include:: ../disclaimer-zh_CN.rst + +:Original: Documentation/accounting/delay-accounting.rst + +:Translator: Yang Yang + +======== +延时计数 +======== + +任务在等待某些内核资源可用时，会造成延时。例如一个可运行的任务可能会等待 +一个空闲CPU来运行。 + +基于每任务的延时计数功能度量由以下情况造成的任务延时： + +a) 等待一个CPU（任务为可运行） +b) 完成由该任务发起的块I/O同步请求 +c) 页面交换 +d) 内存回收 + +并将这些统计信息通过taskstats接口提供给用户空间。 + +这些延时信息为适当的调整任务CPU优先级、io优先级、rss限制提供反馈。重要任务 +长期延时，表示可能需要提高其相关优先级。 + +通过使用taskstats接口，本功能还可提供一个线程组（对应传统Unix进程）所有任务 +（或线程）的总延时统计信息。此类汇总往往是需要的，由内核来完成更加高效。 + +用户空间的实体，特别是资源管理程序，可将延时统计信息汇总到任意组中。为实现 +这一点，任务的延时统计信息在其生命周期内和退出时皆可获取，从而确保可进行 +连续、完整的监控。 + +接口 +---- + +延时计数使用taskstats接口，该接口由本目录另一个单独的文档详细描述。Taskstats +向用户态返回一个通用数据结构，对应每pid或每tgid的统计信息。延时计数功能填写 +该数据结构的特定字段。见 + + include/linux/taskstats.h + +其描述了延时计数相关字段。系统通常以计数器形式返回 CPU、同步块 I/O、交换、内存 +回收等的累积延时。 + +取任务某计数器两个连续读数的差值，将得到任务在该时间间隔内等待对应资源的总延时。 + +当任务退出时，内核会将包含每任务的统计信息发送给用户空间，而无需额外的命令。 +若其为线程组最后一个退出的任务，内核还会发送每tgid的统计信息。更多详细信息见 +taskstats接口的描述。 + +tools/accounting目录中的用户空间程序getdelays.c提供了一些简单的命令，用以显示 +延时统计信息。其也是使用taskstats接口的示例。 + +用法 +---- + +使用以下配置编译内核:: + + CONFIG_TASK_DELAY_ACCT=y + CONFIG_TASKSTATS=y + +延时计数在启动时默认关闭。 +若需开启，在启动参数中增加:: + + delayacct + +本文后续的说明基于延时计数已开启。也可在系统运行时，使用sysctl的 +kernel.task_delayacct进行开关。注意，只有在启用延时计数后启动的 +任务才会有相关信息。 + +系统启动后，使用类似getdelays.c的工具获取任务或线程组（tgid）的延时信息。 + +getdelays命令的一般格式:: + + getdelays [-t tgid] [-p pid] [-c cmd...] + +获取pid为10的任务从系统启动后的延时信息:: + + # ./getdelays -p 10 + （输出信息和下例相似） + +获取所有tgid为5的任务从系统启动后的总延时信息:: + + # ./getdelays -t 5 + + + CPU count real total virtual total delay total + 7876 92005750 100000000 24001500 + IO count delay total + 0 0 + SWAP count delay total + 0 0 + RECLAIM count delay total + 0 0 + +获取指定简单命令运行时的延时信息:: + + # ./getdelays -c ls / + + bin data1 data3 data5 dev home media opt root srv sys usr + boot data2 data4 data6 etc lib mnt proc sbin subdomain tmp var + + + CPU count real total virtual total delay total + 6 4000250 4000000 0 + IO count delay total + 0 0 + SWAP count delay total + 0 0 + RECLAIM count delay total + 0 0 diff --git a/Documentation/translations/zh_CN/accounting/index.rst b/Documentation/translations/zh_CN/accounting/index.rst index 362e907b41f9..a34952e12a27 100644 --- a/Documentation/translations/zh_CN/accounting/index.rst +++ b/Documentation/translations/zh_CN/accounting/index.rst @@ -15,11 +15,11 @@ .. toctree:: :maxdepth: 1 + delay-accounting psi + taskstats Todolist: cgroupstats - delay-accounting - taskstats taskstats-struct diff --git a/Documentation/translations/zh_CN/accounting/taskstats.rst b/Documentation/translations/zh_CN/accounting/taskstats.rst new file mode 100644 index 000000000000..307ac5ce0e4b --- /dev/null +++ b/Documentation/translations/zh_CN/accounting/taskstats.rst @@ -0,0 +1,145 @@ +.. include:: ../disclaimer-zh_CN.rst + +:Original: Documentation/accounting/taskstats.rst + +:Translator: Yang Yang + +================ +每任务的统计接口 +================ + +Taskstats是一个基于netlink的接口，用于从内核向用户空间发送每任务及每进程的 +统计信息。 + +Taskstats设计目的： + +- 在任务生命周期内和退出时高效的提供统计信息 +- 统一不同计数子系统的接口 +- 支持未来计数系统的扩展 + +术语 +---- + +“pid”、“tid”、“任务”互换使用，用于描述由struct task_struct定义的标准 +Linux任务。“每pid的统计数据”等价于“每任务的统计数据”。 + +“tgid”、“进程”、“线程组”互换使用，用于描述共享mm_struct的任务集， +也就是传统的Unix进程。尽管使用了tgid这个词，即使一个任务是线程组组长， +对它的处理也没有什么不同。只要一个进程还有任何归属它的任务，它就被认为 +活着。 + +用法 +---- + +为了在任务生命周期内获得统计信息，用户空间需打开一个单播的netlink套接字 +（NETLINK_GENERIC族）然后发送指定pid或tgid的命令。响应消息中包含单个 +任务的统计信息（若指定了pid）或进程所有任务汇总的统计信息（若指定了tgid）。 + +为了在任务退出时获取统计信息，用户空间的监听者发送一个指定cpu掩码的注册命令。 +cpu掩码内的cpu上有任务退出时，每pid的统计信息将发送给注册成功的监听者。使用 +cpu掩码可以限制一个监听者收到的数据，并有助于对netlink接口进行流量控制，后文 +将进行更详细的解释。 + +如果正在退出的任务是线程组中最后一个退出的线程，额外一条包含每tgid统计信息的 +记录也将发送给用户空间。后者包含线程组中所有线程（包括过去和现在）的每pid统计 +信息总和。 + +getdelays.c是一个简单的示例，用以演示如何使用taskstats接口获取延迟统计信息。 +用户可注册cpu掩码、发送命令和处理响应、监听每tid/tgid退出数据、将收到的数据 +写入文件、通过增大接收缓冲区进行基本的流量控制。 + +接口 +---- + +内核用户接口封装在include/linux/taskstats.h。 + +为避免本文档随着接口的演进而过期，本文仅给出当前版本的概要。当本文与taskstats.h +不一致时，以taskstats.h为准。 + +struct taskstats是每pid和每tgid数据共用的计数结构体。它是版本化的，可在内核新增 +计数子系统时进行扩展。taskstats.h中定义了各字段及语义。 + +用户、内核空间的数据交换是属于NETLINK_GENERIC族的netlink消息，使用netlink属性 +接口。消息格式如下:: + + +----------+- - -+-------------+-------------------+ + | nlmsghdr | Pad | genlmsghdr | taskstats payload | + +----------+- - -+-------------+-------------------+ + +Taskstats载荷有三种类型： + +1. 命令：由用户发送给内核。获取指定pid/tgid数据的命令包含一个类型为 +TASKSTATS_CMD_ATTR_PID/TGID的属性，该属性包含u32的pid或tgid载荷。 +pid/tgid指示用户空间要统计的任务/进程。 + +注册/注销获取指定cpu集上退出数据的命令包含一个类型为 +TASKSTATS_CMD_ATTR_REGISTER/DEREGISTER_CPUMASK的属性，该属性包含cpu掩码载荷。 +cpu掩码是以ascii码表示，用逗号分隔的cpu范围。例如若需监听1,2,3,5,7,8号cpu的 +退出数据，cpu掩码表示为"1-3,5,7-8"。若用户空间在关闭监听套接字前忘了注销监听 +的cpu集，随着时间的推移，内核会清理此监听集。但是，出于提效的目的，建议明确 +执行注销。 + +2. 命令的应答：内核发出应答用户空间的命令。载荷有三类属性： + +a) TASKSTATS_TYPE_AGGR_PID/TGID： 本属性不包含载荷，用以指示其后为被统计对象 +的pig/tgid。 + +b) TASKSTATS_TYPE_PID/TGID：本属性的载荷为pig/tgid，其统计信息将被返回。 + +c) TASKSTATS_TYPE_STATS：本属性的载荷为一个struct taskstats实例。每pid和 +每tgid统计信息共用该结构体。 + +3. 内核会在任务退出时发送新消息。其载荷包含一系列以下类型的属性： + +a) TASKSTATS_TYPE_AGGR_PID：指示其后两个属性为pid+stats。 +b) TASKSTATS_TYPE_PID：包含退出任务的pid。 +c) TASKSTATS_TYPE_STATS：包含退出任务的每pid统计信息 +d) TASKSTATS_TYPE_AGGR_TGID：指示其后两个属性为tgid+stats。 +e) TASKSTATS_TYPE_TGID：包含任务所属进程的tgid +f) TASKSTATS_TYPE_STATS：包含退出任务所属进程的每tgid统计信息 + +每tgid的统计 +------------ + +除了每任务的统计信息，taskstats还提供每进程的统计信息，因为资源管理通常以进程 +粒度完成，并且仅在用户空间聚合任务统计信息效率低下且可能不准确（缺乏原子性）。 + +然而，除了每任务统计信息，在内核中维护每进程统计信息存在额外的时间和空间开销。 +为解决此问题，taskstats代码将退出任务的统计信息累积到进程范围的数据结构中。 +当进程最后一个任务退出时，累积的进程级数据也会发送到用户空间（与每任务数据一起）。 + +当用户查询每tgid数据时，内核将指定线程组中所有活动线程的统计信息相加，并添加到 +该线程组的累积总数（含之前退出的线程）。 + +扩展taskstats +------------- + +有两种方法可在未来修改内核扩展taskstats接口，以导出更多的每任务/进程统计信息： + +1. 在现有struct taskstats末尾增加字段。该结构体中的版本号确保了向后兼容性。 +用户空间将仅使用与其版本对应的结构体字段。 + +2. 定义单独的统计结构体并使用netlink属性接口返回对应的数据。由于用户空间独立 +处理每个netlink属性，所以总是可以忽略其不理解类型的属性（因为使用了旧版本接口）。 + +在1.和2.之间进行选择，属于权衡灵活性和开销的问题。若仅需增加少数字段，那么1.是 +首选方法，因为内核和用户空间无需承担处理新netlink属性的开销。但若新字段过多的 +扩展现有结构体，导致不同的用户空间计数程序不必要的接收大型结构体，而对结构体 +字段并不感兴趣，那么2.是值得的。 + +Taskstats的流量控制 +------------------- + +当退出任务数速率变大，监听者可能跟不上内核发送每tid/tgid退出数据的速率，而导致 +数据丢失。taskstats结构体变大、cpu数量上升，都会导致这种可能性增加。 + +为避免统计信息丢失，用户空间应执行以下操作中至少一项： + +- 增大监听者用于接收退出数据的netlink套接字接收缓存区。 + +- 创建更多的监听者，减少每个监听者监听的cpu数量。极端情况下可为每个cpu创建 + 一个监听者。用户还可考虑将监听者的cpu亲和性设置为监听cpu的子集，特别是当他们 + 仅监听一个cpu。 + +尽管采取了这些措施，若用户空间仍收到指示接收缓存区溢出的ENOBUFS错误消息， +则应采取其他措施处理数据丢失。 diff --git a/Documentation/translations/zh_CN/admin-guide/README.rst b/Documentation/translations/zh_CN/admin-guide/README.rst index 980eb20521cf..d20949e8bf6f 100644 --- a/Documentation/translations/zh_CN/admin-guide/README.rst +++ b/Documentation/translations/zh_CN/admin-guide/README.rst @@ -133,7 +133,7 @@ Linux内核5.x版本 即使只升级一个小版本，也不要跳过此步骤。每个版本中都会添加新的配置选项， 如果配置文件没有按预定设置，就会出现奇怪的问题。如果您想以最少的工作量 - 将现有配置升级到新版本，请使用 ``makeoldconfig`` ，它只会询问您新配置 + 将现有配置升级到新版本，请使用 ``make oldconfig`` ，它只会询问您新配置 选项的答案。 - 其他配置命令包括:: @@ -161,7 +161,7 @@ Linux内核5.x版本 "make ${PLATFORM}_defconfig" 使用arch/$arch/configs/${PLATFORM}_defconfig中 的默认选项值创建一个./.config文件。 - 用“makehelp”来获取您体系架构中所有可用平台的列表。 + 用“make help”来获取您体系架构中所有可用平台的列表。 "make allyesconfig" 通过尽可能将选项值设置为“y”，创建一个 @@ -197,9 +197,10 @@ Linux内核5.x版本 "make localyesconfig" 与localmodconfig类似，只是它会将所有模块选项转换 为内置（=y）。你可以同时通过LMC_KEEP保留模块。 - "make kvmconfig" 为kvm客体内核支持启用其他选项。 + "make kvm_guest.config" + 为kvm客户机内核支持启用其他选项。 - "make xenconfig" 为xen dom0客体内核支持启用其他选项。 + "make xen.config" 为xen dom0客户机内核支持启用其他选项。 "make tinyconfig" 配置尽可能小的内核。 @@ -229,7 +230,7 @@ Linux内核5.x版本 请注意，您仍然可以使用此内核运行a.out用户程序。 - 执行 ``make`` 来创建压缩内核映像。如果您安装了lilo以适配内核makefile， - 那么也可以进行 ``makeinstall`` ，但是您可能需要先检查特定的lilo设置。 + 那么也可以进行 ``make install`` ，但是您可能需要先检查特定的lilo设置。 实际安装必须以root身份执行，但任何正常构建都不需要。 无须徒然使用root身份。 diff --git a/Documentation/translations/zh_CN/admin-guide/cputopology.rst b/Documentation/translations/zh_CN/admin-guide/cputopology.rst new file mode 100644 index 000000000000..544d42f8f3fa --- /dev/null +++ b/Documentation/translations/zh_CN/admin-guide/cputopology.rst @@ -0,0 +1,96 @@ +.. SPDX-License-Identifier: GPL-2.0 +.. include:: ../disclaimer-zh_CN.rst + +:Original: Documentation/admin-guide/cputopology.rst + +:翻译: + + 唐艺舟 Tang Yizhou + +========================== +如何通过sysfs将CPU拓扑导出 +========================== + +CPU拓扑信息通过sysfs导出。显示的项（属性）和某些架构的/proc/cpuinfo输出相似。它们位于 +/sys/devices/system/cpu/cpuX/topology/。请阅读ABI文件： +Documentation/ABI/stable/sysfs-devices-system-cpu。 + +drivers/base/topology.c是体系结构中性的，它导出了这些属性。然而，die、cluster、book、 +draw这些层次结构相关的文件仅在体系结构提供了下文描述的宏的条件下被创建。 + +对于支持这个特性的体系结构，它必须在include/asm-XXX/topology.h中定义这些宏中的一部分:: + + #define topology_physical_package_id(cpu) + #define topology_die_id(cpu) + #define topology_cluster_id(cpu) + #define topology_core_id(cpu) + #define topology_book_id(cpu) + #define topology_drawer_id(cpu) + #define topology_sibling_cpumask(cpu) + #define topology_core_cpumask(cpu) + #define topology_cluster_cpumask(cpu) + #define topology_die_cpumask(cpu) + #define topology_book_cpumask(cpu) + #define topology_drawer_cpumask(cpu) + +``**_id macros`` 的类型是int。 +``**_cpumask macros`` 的类型是 ``(const) struct cpumask *`` 。后者和恰当的 +``**_siblings`` sysfs属性对应（除了topology_sibling_cpumask()，它和thread_siblings +对应）。 + +为了在所有体系结构上保持一致，include/linux/topology.h提供了上述所有宏的默认定义，以防 +它们未在include/asm-XXX/topology.h中定义: + +1) topology_physical_package_id: -1 +2) topology_die_id: -1 +3) topology_cluster_id: -1 +4) topology_core_id: 0 +5) topology_book_id: -1 +6) topology_drawer_id: -1 +7) topology_sibling_cpumask: 仅入参CPU +8) topology_core_cpumask: 仅入参CPU +9) topology_cluster_cpumask: 仅入参CPU +10) topology_die_cpumask: 仅入参CPU +11) topology_book_cpumask: 仅入参CPU +12) topology_drawer_cpumask: 仅入参CPU + +此外，CPU拓扑信息由/sys/devices/system/cpu提供，包含下述文件。输出对应的内部数据源放在 +方括号（"[]"）中。 + + =========== ================================================================== + kernel_max: 内核配置允许的最大CPU下标值。[NR_CPUS-1] + + offline: 由于热插拔移除或者超过内核允许的CPU上限（上文描述的kernel_max） + 导致未上线的CPU。[~cpu_online_mask + cpus >= NR_CPUS] + + online: 在线的CPU，可供调度使用。[cpu_online_mask] + + possible: 已被分配资源的CPU，如果它们CPU实际存在，可以上线。 + [cpu_possible_mask] + + present: 被系统识别实际存在的CPU。[cpu_present_mask] + =========== ================================================================== + +上述输出的格式和cpulist_parse()兼容[参见 ]。下面给些例子。 + +在本例中，系统中有64个CPU，但是CPU 32-63超过了kernel_max值，因为NR_CPUS配置项是32， +取值范围被限制为0..31。此外注意CPU2和4-31未上线，但是可以上线，因为它们同时存在于 +present和possible:: + + kernel_max: 31 + offline: 2,4-31,32-63 + online: 0-1,3 + possible: 0-31 + present: 0-31 + +在本例中，NR_CPUS配置项是128，但内核启动时设置possible_cpus=144。系统中有4个CPU， +CPU2被手动设置下线（也是唯一一个可以上线的CPU）:: + + kernel_max: 127 + offline: 2,4-127,128-143 + online: 0-1,3 + possible: 0-127 + present: 0-3 + +阅读Documentation/core-api/cpu_hotplug.rst可了解开机参数possible_cpus=NUM，同时还 +可以了解各种cpumask的信息。 diff --git a/Documentation/translations/zh_CN/admin-guide/index.rst b/Documentation/translations/zh_CN/admin-guide/index.rst index 83db84282562..548e57f4b3f1 100644 --- a/Documentation/translations/zh_CN/admin-guide/index.rst +++ b/Documentation/translations/zh_CN/admin-guide/index.rst @@ -65,6 +65,7 @@ Todolist: clearing-warn-once cpu-load + cputopology lockup-watchdogs unicode sysrq @@ -84,7 +85,6 @@ Todolist: cgroup-v1/index cgroup-v2 cifs/index - cputopology dell_rbu device-mapper/index edid diff --git a/Documentation/translations/zh_CN/cpu-freq/core.rst b/Documentation/translations/zh_CN/cpu-freq/core.rst index 0c6fd447ced6..b3c095306ffe 100644 --- a/Documentation/translations/zh_CN/cpu-freq/core.rst +++ b/Documentation/translations/zh_CN/cpu-freq/core.rst @@ -7,7 +7,9 @@ 司延腾 Yanteng Si -.. _cn_core.rst: +:校译: + + 唐艺舟 Tang Yizhou ==================================== CPUFreq核心和CPUFreq通知器的通用说明 @@ -29,10 +31,10 @@ CPUFreq核心和CPUFreq通知器的通用说明 ====================== cpufreq核心代码位于drivers/cpufreq/cpufreq.c中。这些cpufreq代码为CPUFreq架构的驱 -动程序（那些操作硬件切换频率的代码）以及 "通知器 "提供了一个标准化的接口。 -这些是设备驱动程序或需要了解策略变化的其它内核部分（如 ACPI 热量管理）或所有频率更改（除 -计时代码外），甚至需要强制确定速度限制的通知器（如 ARM 架构上的 LCD 驱动程序）。 -此外， 内核 "常数" loops_per_jiffy会根据频率变化而更新。 +动程序（那些执行硬件频率切换的代码）以及 "通知器" 提供了一个标准化的接口。 +包括设备驱动程序；需要了解策略变化（如 ACPI 热量管理），或所有频率变化（如计时代码）， +甚至需要强制限制为指定频率（如 ARM 架构上的 LCD 驱动程序）的其它内核组件。 +此外，内核 "常数" loops_per_jiffy 会根据频率变化而更新。 cpufreq策略的引用计数由 cpufreq_cpu_get 和 cpufreq_cpu_put 来完成，以确保 cpufreq 驱 动程序被正确地注册到核心中，并且驱动程序在 cpufreq_put_cpu 被调用之前不会被卸载。这也保证 @@ -41,7 +43,7 @@ cpufreq策略的引用计数由 cpufreq_cpu_get 和 cpufreq_cpu_put 来完成， 2. CPUFreq 通知器 ==================== -CPUFreq通知器符合标准的内核通知器接口。 +CPUFreq通知器遵循标准的内核通知器接口。 关于通知器的细节请参阅 linux/include/linux/notifier.h。 这里有两个不同的CPUfreq通知器 - 策略通知器和转换通知器。 @@ -69,20 +71,20 @@ CPUFreq通知器符合标准的内核通知器接口。 第三个参数是一个包含如下值的结构体cpufreq_freqs： -===== ==================== -cpu 受影响cpu的编号 +====== =============================== +policy 指向struct cpufreq_policy的指针 old 旧频率 new 新频率 flags cpufreq驱动的标志 -===== ==================== +====== =============================== 3. 含有Operating Performance Point (OPP)的CPUFreq表的生成 ================================================================== 关于OPP的细节请参阅 Documentation/power/opp.rst dev_pm_opp_init_cpufreq_table - - 这个功能提供了一个随时可用的转换程序，用来将OPP层关于可用频率的内部信息翻译成一种容易提供给 - cpufreq的格式。 + 这个函数提供了一个随时可用的转换例程，用来将OPP层关于可用频率的内部信息翻译成一种 + cpufreq易于处理的格式。 .. Warning:: diff --git a/Documentation/translations/zh_CN/cpu-freq/cpu-drivers.rst b/Documentation/translations/zh_CN/cpu-freq/cpu-drivers.rst index 0fc5d1495789..87a36044f828 100644 --- a/Documentation/translations/zh_CN/cpu-freq/cpu-drivers.rst +++ b/Documentation/translations/zh_CN/cpu-freq/cpu-drivers.rst @@ -8,7 +8,9 @@ 司延腾 Yanteng Si -.. _cn_cpu-drivers.rst: +:校译: + + 唐艺舟 Tang Yizhou ======================================= 如何实现一个新的CPUFreq处理器驱动程序？ @@ -38,14 +40,14 @@ 1. 怎么做？ =========== -如此，你刚刚得到了一个全新的CPU/芯片组及其数据手册，并希望为这个CPU/芯片组添加cpufreq +如果，你刚刚得到了一个全新的CPU/芯片组及其数据手册，并希望为这个CPU/芯片组添加cpufreq 支持？很好，这里有一些至关重要的提示： 1.1 初始化 ---------- -首先，在__initcall_level_7 (module_init())或更靠后的函数中检查这个内核是否 +首先，在 __initcall level 7 (module_init())或更靠后的函数中检查这个内核是否 运行在正确的CPU和正确的芯片组上。如果是，则使用cpufreq_register_driver()向 CPUfreq核心层注册一个cpufreq_driver结构体。 @@ -60,11 +62,11 @@ CPUfreq核心层注册一个cpufreq_driver结构体。 .setpolicy 或 .fast_switch 或 .target 或 .target_index - 差异见 下文。 -并且可选择 +其它可选成员 - .flags - cpufreq核的提示。 + .flags - 给cpufreq核心的提示。 - .driver_data - cpufreq驱动程序的特定数据。 + .driver_data - cpufreq驱动程序的特有数据。 .get_intermediate 和 target_intermediate - 用于在改变CPU频率时切换到稳定 的频率。 @@ -73,16 +75,16 @@ CPUfreq核心层注册一个cpufreq_driver结构体。 .bios_limit - 返回HW/BIOS对CPU的最大频率限制值。 - .exit - 一个指向per-policy清理函数的指针，该函数在cpu热插拔过程的CPU_POST_DEAD + .exit - 一个指向per-policy清理函数的指针，该函数在CPU热插拔过程的CPU_POST_DEAD 阶段被调用。 .suspend - 一个指向per-policy暂停函数的指针，该函数在关中断且在该策略的调节器停止 后被调用。 - .resume - 一个指向per-policy恢复函数的指针，该函数在关中断且在调节器再一次开始前被 + .resume - 一个指向per-policy恢复函数的指针，该函数在关中断且在调节器再一次启动前被 调用。 - .attr - 一个指向NULL结尾的"struct freq_attr"列表的指针，该函数允许导出值到 + .attr - 一个指向NULL结尾的"struct freq_attr"列表的指针，该列表允许导出值到 sysfs。 .boost_enabled - 如果设置，则启用提升(boost)频率。 @@ -93,95 +95,93 @@ CPUfreq核心层注册一个cpufreq_driver结构体。 1.2 Per-CPU 初始化 ------------------ -每当一个新的CPU被注册到设备模型中，或者在cpufreq驱动注册自己之后，如果此CPU的cpufreq策 -略不存在，则会调用per-policy的初始化函数cpufreq_driver.init。请注意，.init()和.exit()程序 -只对策略调用一次，而不是对策略管理的每个CPU调用一次。它需要一个 ``struct cpufreq_policy +每当一个新的CPU被注册到设备模型中，或者当cpufreq驱动注册自身之后，如果此CPU的cpufreq策 +略不存在，则会调用per-policy的初始化函数cpufreq_driver.init。请注意，.init()和.exit()例程 +只为某个策略调用一次，而不是对该策略管理的每个CPU调用一次。它需要一个 ``struct cpufreq_policy *policy`` 作为参数。现在该怎么做呢？ 如果有必要，请在你的CPU上激活CPUfreq功能支持。 -然后，驱动程序必须填写以下数值: +然后，驱动程序必须填写以下值: +-----------------------------------+--------------------------------------+ -|policy->cpuinfo.min_freq 和 | | -|policy->cpuinfo.max_freq | 该CPU支持的最低和最高频率（kHz） | -| | | -| | | +|policy->cpuinfo.min_freq和 | 该CPU支持的最低和最高频率（kHz） | +|policy->cpuinfo.max_freq | | +| | | +-----------------------------------+--------------------------------------+ -|policy->cpuinfo.transition_latency | | -| | CPU在两个频率之间切换所需的时间，以 | -| | 纳秒为单位（如适用，否则指定 | -| | CPUFREQ_ETERNAL） | +|policy->cpuinfo.transition_latency | CPU在两个频率之间切换所需的时间，以 | +| | 纳秒为单位（如不适用，设定为 | +| | CPUFREQ_ETERNAL） | +| | | +-----------------------------------+--------------------------------------+ -|policy->cur | 该CPU当前的工作频率(如适用) | -| | | +|policy->cur | 该CPU当前的工作频率(如适用) | +| | | +-----------------------------------+--------------------------------------+ -|policy->min, | | -|policy->max, | | -|policy->policy and, if necessary, | | -|policy->governor | 必须包含该cpu的 “默认策略”。稍后 | -| | 会用这些值调用 | -| | cpufreq_driver.verify and either | -| | cpufreq_driver.setpolicy or | -| | cpufreq_driver.target/target_index | -| | | +|policy->min, | 必须包含该CPU的"默认策略"。稍后 | +|policy->max, | 会用这些值调用 | +|policy->policy and, if necessary, | cpufreq_driver.verify和下面函数 | +|policy->governor | 之一：cpufreq_driver.setpolicy或 | +| | cpufreq_driver.target/target_index | +| | | +-----------------------------------+--------------------------------------+ -|policy->cpus | 用与这个CPU一起做DVFS的(在线+离线) | -| | CPU(即与它共享时钟/电压轨)的掩码更新 | -| | 这个 | -| | | +|policy->cpus | 该policy通过DVFS框架影响的全部CPU | +| | (即与本CPU共享"时钟/电压"对)构成 | +| | 掩码(同时包含在线和离线CPU)，用掩码 | +| | 更新本字段 | +| | | +-----------------------------------+--------------------------------------+ -对于设置其中的一些值(cpuinfo.min[max]_freq, policy->min[max])，频率表助手可能会有帮 +对于设置其中的一些值(cpuinfo.min[max]_freq, policy->min[max])，频率表辅助函数可能会有帮 助。关于它们的更多信息，请参见第2节。 1.3 验证 -------- -当用户决定设置一个新的策略(由 “policy,governor,min,max组成”)时，必须对这个策略进行验证， +当用户决定设置一个新的策略(由"policy,governor,min,max组成")时，必须对这个策略进行验证， 以便纠正不兼容的值。为了验证这些值，cpufreq_verify_within_limits(``struct cpufreq_policy *policy``, ``unsigned int min_freq``, ``unsigned int max_freq``)函数可能会有帮助。 -关于频率表助手的详细内容请参见第2节。 +关于频率表辅助函数的详细内容请参见第2节。 您需要确保至少有一个有效频率（或工作范围）在 policy->min 和 policy->max 范围内。如果有必 -要，先增加policy->max，只有在没有办法的情况下，才减少policy->min。 +要，先增大policy->max，只有在没有解决方案的情况下，才减小policy->min。 1.4 target 或 target_index 或 setpolicy 或 fast_switch? ------------------------------------------------------- -大多数cpufreq驱动甚至大多数cpu频率升降算法只允许将CPU频率设置为预定义的固定值。对于这些，你 +大多数cpufreq驱动甚至大多数CPU频率升降算法只允许将CPU频率设置为预定义的固定值。对于这些，你 可以使用->target()，->target_index()或->fast_switch()回调。 -有些cpufreq功能的处理器可以自己在某些限制之间切换频率。这些应使用->setpolicy()回调。 +有些具有硬件调频能力的处理器可以自行依据某些限制来切换CPU频率。它们应使用->setpolicy()回调。 1.5. target/target_index ------------------------ -target_index调用有两个参数：``struct cpufreq_policy * policy``和``unsigned int`` -索引(于列出的频率表)。 +target_index调用有两个参数： ``struct cpufreq_policy * policy`` 和 ``unsigned int`` +索引(用于索引频率表项)。 当调用这里时，CPUfreq驱动必须设置新的频率。实际频率必须由freq_table[index].frequency决定。 -它应该总是在错误的情况下恢复到之前的频率(即policy->restore_freq)，即使我们之前切换到中间频率。 +在发生错误的情况下总是应该恢复到之前的频率(即policy->restore_freq)，即使我们已经切换到了 +中间频率。 已弃用 ---------- -目标调用有三个参数。``struct cpufreq_policy * policy``, unsigned int target_frequency, +target调用有三个参数。``struct cpufreq_policy * policy``, unsigned int target_frequency, unsigned int relation. CPUfreq驱动在调用这里时必须设置新的频率。实际的频率必须使用以下规则来确定。 -- 紧跟 "目标频率"。 +- 尽量贴近"目标频率"。 - policy->min <= new_freq <= policy->max (这必须是有效的!!!) - 如果 relation==CPUFREQ_REL_L，尝试选择一个高于或等于 target_freq 的 new_freq。("L代表 最低，但不能低于") - 如果 relation==CPUFREQ_REL_H，尝试选择一个低于或等于 target_freq 的 new_freq。("H代表 最高，但不能高于") -这里，频率表助手可能会帮助你--详见第2节。 +这里，频率表辅助函数可能会帮助你 -- 详见第2节。 1.6. fast_switch ---------------- @@ -195,42 +195,43 @@ CPUfreq驱动在调用这里时必须设置新的频率。实际的频率必须 1.7 setpolicy ------------- -setpolicy调用只需要一个``struct cpufreq_policy * policy``作为参数。需要将处理器内或芯片组内动态频 +setpolicy调用只需要一个 ``struct cpufreq_policy * policy`` 作为参数。需要将处理器内或芯片组内动态频 率切换的下限设置为policy->min，上限设置为policy->max，如果支持的话，当policy->policy为 -CPUFREQ_POLICY_PERFORMANCE时选择面向性能的设置，当CPUFREQ_POLICY_POWERSAVE时选择面向省电的设置。 +CPUFREQ_POLICY_PERFORMANCE时选择面向性能的设置，为CPUFREQ_POLICY_POWERSAVE时选择面向省电的设置。 也可以查看drivers/cpufreq/longrun.c中的参考实现。 1.8 get_intermediate 和 target_intermediate -------------------------------------------- -仅适用于 target_index() 和 CPUFREQ_ASYNC_NOTIFICATION 未设置的驱动。 +仅适用于未设置 target_index() 和 CPUFREQ_ASYNC_NOTIFICATION 的驱动。 get_intermediate应该返回一个平台想要切换到的稳定的中间频率，target_intermediate()应该将CPU设置为 -该频率，然后再跳转到'index'对应的频率。核心会负责发送通知，驱动不必在target_intermediate()或 -target_index()中处理。 +该频率，然后再跳转到'index'对应的频率。cpufreq核心会负责发送通知，驱动不必在 +target_intermediate()或target_index()中处理它们。 -在驱动程序不想因为某个目标频率切换到中间频率的情况下，它们可以从get_intermediate()中返回'0'。在这种情况 -下，核心将直接调用->target_index()。 +在驱动程序不想为某个目标频率切换到中间频率的情况下，它们可以让get_intermediate()返回'0'。 +在这种情况下，cpufreq核心将直接调用->target_index()。 -注意：->target_index()应该在失败的情况下恢复到policy->restore_freq，因为core会为此发送通知。 +注意：->target_index()应该在发生失败的情况下将频率恢复到policy->restore_freq， +因为cpufreq核心会为此发送通知。 -2. 频率表助手 -============= +2. 频率表辅助函数 +================= -由于大多数cpufreq处理器只允许被设置为几个特定的频率，因此，一个带有一些函数的 “频率表”可能会辅助处理器驱动 -程序的一些工作。这样的 "频率表" 由一个cpufreq_frequency_table条目构成的数组组成，"driver_data" 中包 -含了驱动程序的具体数值，"frequency" 中包含了相应的频率，并设置了标志。在表的最后，需要添加一个 -cpufreq_frequency_table条目，频率设置为CPUFREQ_TABLE_END。而如果想跳过表中的一个条目，则将频率设置为 -CPUFREQ_ENTRY_INVALID。这些条目不需要按照任何特定的顺序排序，但如果它们是cpufreq 核心会对它们进行快速的DVFS， +由于大多数支持cpufreq的处理器只允许被设置为几个特定的频率，因此，"频率表"和一些相关函数可能会辅助处理器驱动 +程序的一些工作。这样的"频率表"是一个由struct cpufreq_frequency_table的条目构成的数组，"driver_data"成员包 +含驱动程序的专用值，"frequency"成员包含了相应的频率，此外还有标志成员。在表的最后，需要添加一个 +cpufreq_frequency_table条目，频率设置为CPUFREQ_TABLE_END。如果想跳过表中的一个条目，则将频率设置为 +CPUFREQ_ENTRY_INVALID。这些条目不需要按照任何特定的顺序排序，如果排序了，cpufreq核心执行DVFS会更快一点， 因为搜索最佳匹配会更快。 -如果策略在其policy->freq_table字段中包含一个有效的指针，cpufreq表就会被核心自动验证。 +如果在policy->freq_table字段中包含一个有效的频率表指针，频率表就会被cpufreq核心自动验证。 cpufreq_frequency_table_verify()保证至少有一个有效的频率在policy->min和policy->max范围内，并且所有其他 -标准都被满足。这对->verify调用很有帮助。 +准则都被满足。这对->verify调用很有帮助。 -cpufreq_frequency_table_target()是对应于->target阶段的频率表助手。只要把数值传递给这个函数，这个函数就会返 +cpufreq_frequency_table_target()是对应于->target阶段的频率表辅助函数。只要把值传递给这个函数，这个函数就会返 回包含CPU要设置的频率的频率表条目。 以下宏可以作为cpufreq_frequency_table的迭代器。 @@ -238,8 +239,8 @@ cpufreq_frequency_table_target()是对应于->target阶段的频率表助手。 cpufreq_for_each_entry(pos, table) - 遍历频率表的所有条目。 cpufreq_for_each_valid_entry(pos, table) - 该函数遍历所有条目，不包括CPUFREQ_ENTRY_INVALID频率。 -使用参数 "pos"-一个``cpufreq_frequency_table * `` 作为循环变量，使用参数 "table"-作为你想迭代 -的``cpufreq_frequency_table * `` 。 +使用参数"pos" -- 一个 ``cpufreq_frequency_table *`` 作为循环指针，使用参数"table" -- 作为你想迭代 +的 ``cpufreq_frequency_table *`` 。 例如:: @@ -250,5 +251,5 @@ cpufreq_for_each_valid_entry(pos, table) - 该函数遍历所有条目，不包 pos->frequency = ... } -如果你需要在driver_freq_table中处理pos的位置，不要减去指针，因为它的代价相当高。相反，使用宏 +如果你需要在driver_freq_table中处理pos的位置，不要做指针减法，因为它的代价相当高。作为替代，使用宏 cpufreq_for_each_entry_idx() 和 cpufreq_for_each_valid_entry_idx() 。 diff --git a/Documentation/translations/zh_CN/cpu-freq/cpufreq-stats.rst b/Documentation/translations/zh_CN/cpu-freq/cpufreq-stats.rst index f14423099d4b..e8fdba923cd5 100644 --- a/Documentation/translations/zh_CN/cpu-freq/cpufreq-stats.rst +++ b/Documentation/translations/zh_CN/cpu-freq/cpufreq-stats.rst @@ -8,13 +8,15 @@ 司延腾 Yanteng Si -.. _cn_cpufreq-stats.rst: +:校译: + + 唐艺舟 Tang Yizhou ========================================== sysfs CPUFreq Stats的一般说明 ========================================== -用户信息 +为使用者准备的信息 作者: Venkatesh Pallipadi @@ -29,17 +31,16 @@ sysfs CPUFreq Stats的一般说明 1. 简介 =============== -cpufreq-stats是一个为每个CPU提供CPU频率统计的驱动。 -这些统计数据在/sysfs中以一堆只读接口的形式提供。这个接口（在配置好后）将出现在 -/sysfs（/devices/system/cpu/cpuX/cpufreq/stats/）中cpufreq下的一个单 -独的目录中，提供给每个CPU。 -各种统计数据将在此目录下形成只读文件。 +cpufreq-stats是一种为每个CPU提供CPU频率统计的驱动。 +这些统计数据以/sysfs中一系列只读接口的形式呈现。cpufreq-stats接口（若已配置）将为每个CPU生成 +/sysfs（/devices/system/cpu/cpuX/cpufreq/stats/）中cpufreq目录下的stats目录。 +各项统计数据将在stats目录下形成对应的只读文件。 -此驱动是独立于任何可能运行在你所用CPU上的特定cpufreq_driver而设计的。因此，它将与所有 -cpufreq_driver一起工作。 +此驱动是以独立于任何可能运行在你所用CPU上的特定cpufreq_driver的方式设计的。因此，它将能和任何 +cpufreq_driver协同工作。 -2. 提供的统计数据(举例说明) +2. 已提供的统计数据(有例子) ===================================== cpufreq stats提供了以下统计数据（在下面详细解释）。 @@ -48,8 +49,8 @@ cpufreq stats提供了以下统计数据（在下面详细解释）。 - total_trans - trans_table -所有的统计数据将从统计驱动被载入的时间（或统计被重置的时间）开始，到某一统计数据被读取的时间为止。 -显然，统计驱动不会有任何关于统计驱动载入之前的频率转换信息。 +所有统计数据来自以下时间范围：从统计驱动被加载的时间（或统计数据被重置的时间）开始，到某一统计数据被读取的时间为止。 +显然，统计驱动不会保存它被加载之前的任何频率转换信息。 :: @@ -64,14 +65,14 @@ cpufreq stats提供了以下统计数据（在下面详细解释）。 - **reset** -只写属性，可用于重置统计计数器。这对于评估不同调节器下的系统行为非常有用，且无需重启。 +只写属性，可用于重置统计计数器。这对于评估不同调节器的系统行为非常有用，且无需重启。 - **time_in_state** -此项给出了这个CPU所支持的每个频率所花费的时间。cat输出的每一行都会有" -