android/android_kernel_samsung_sm8650
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Merge daadb3bd0e ("Merge tag 'locking_core_for_v5.17_rc1' of git://git.kernel.org/pub/scm/linux/kernel/git/tip/tip") into android-mainline

Browse Source 
Steps on the way to 5.17-rc1

Signed-off-by: Greg Kroah-Hartman <gregkh@google.com>
Change-Id: Ib4196f71a9514ee2dbc5c868ffa356f40ed4c319
This commit is contained in:
Greg Kroah-Hartman 2022-01-12 15:40:52 +01:00
commit 2c9f5bc8ed
1029 changed files with 43155 additions and 18700 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

32
Documentation/ABI/testing/sysfs-class-firmware-attributes
View File

@ -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

16
Documentation/ABI/testing/sysfs-class-power
View File

@ -413,7 +413,7 @@ Description:
"Over voltage", "Unspecified failure", "Cold",
"Watchdog timer expire", "Safety timer expire",
"Over current", "Calibration required", "Warm",
"Cool", "Hot"
"Cool", "Hot", "No battery"
What: /sys/class/power_supply/<supply_name>/precharge_current
Date: June 2017
@ -455,6 +455,20 @@ Description:
"Unknown", "Charging", "Discharging",
"Not charging", "Full"
What: /sys/class/power_supply/<supply_name>/charge_behaviour
Date: November 2021
Contact: linux-pm@vger.kernel.org
Description:
Represents the charging behaviour.
Access: Read, Write
Valid values:
================ ====================================
auto: Charge normally, respect thresholds
inhibit-charge: Do not charge while AC is attached
force-discharge: Force discharge while AC is attached
What: /sys/class/power_supply/<supply_name>/technology
Date: May 2007
Contact: linux-pm@vger.kernel.org

16
Documentation/ABI/testing/sysfs-fs-erofs Normal file
View File

@ -0,0 +1,16 @@
What: /sys/fs/erofs/features/
Date: November 2021
Contact: "Huang Jianan" <huangjianan@oppo.com>
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/<disk>/sync_decompress
Date: November 2021
Contact: "Huang Jianan" <huangjianan@oppo.com>
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.

35
Documentation/ABI/testing/sysfs-fs-ubifs Normal file
View File

@ -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.

11
Documentation/Makefile
View File

@ -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'

134
Documentation/admin-guide/gpio/gpio-sim.rst Normal file
View File

@ -0,0 +1,134 @@
.. SPDX-License-Identifier: GPL-2.0-or-later
Configfs GPIO Simulator
=======================
The configfs GPIO Simulator (gpio-sim) provides a way to create simulated GPIO
chips for testing purposes. The lines exposed by these chips can be accessed
using the standard GPIO character device interface as well as manipulated
using sysfs attributes.
Creating simulated chips
------------------------
The gpio-sim module registers a configfs subsystem called ``'gpio-sim'``. For
details of the configfs filesystem, please refer to the configfs documentation.
The user can create a hierarchy of configfs groups and items as well as modify
values of exposed attributes. Once the chip is instantiated, this hierarchy
will be translated to appropriate device properties. The general structure is:
**Group:** ``/config/gpio-sim``
This is the top directory of the gpio-sim configfs tree.
**Group:** ``/config/gpio-sim/gpio-device``
**Attribute:** ``/config/gpio-sim/gpio-device/dev_name``
**Attribute:** ``/config/gpio-sim/gpio-device/live``
This is a directory representing a GPIO platform device. The ``'dev_name'``
attribute is read-only and allows the user-space to read the platform device
name (e.g. ``'gpio-sim.0'``). The ``'live'`` attribute allows to trigger the
actual creation of the device once it's fully configured. The accepted values
are: ``'1'`` to enable the simulated device and ``'0'`` to disable and tear
it down.
**Group:** ``/config/gpio-sim/gpio-device/gpio-bankX``
**Attribute:** ``/config/gpio-sim/gpio-device/gpio-bankX/chip_name``
**Attribute:** ``/config/gpio-sim/gpio-device/gpio-bankX/num_lines``
This group represents a bank of GPIOs under the top platform device. The
``'chip_name'`` attribute is read-only and allows the user-space to read the
device name of the bank device. The ``'num_lines'`` attribute allows to specify
the number of lines exposed by this bank.
**Group:** ``/config/gpio-sim/gpio-device/gpio-bankX/lineY``
**Attribute:** ``/config/gpio-sim/gpio-device/gpio-bankX/lineY/name``
This group represents a single line at the offset Y. The 'name' attribute
allows to set the line name as represented by the 'gpio-line-names' property.
**Item:** ``/config/gpio-sim/gpio-device/gpio-bankX/lineY/hog``
**Attribute:** ``/config/gpio-sim/gpio-device/gpio-bankX/lineY/hog/name``
**Attribute:** ``/config/gpio-sim/gpio-device/gpio-bankX/lineY/hog/direction``
This item makes the gpio-sim module hog the associated line. The ``'name'``
attribute specifies the in-kernel consumer name to use. The ``'direction'``
attribute specifies the hog direction and must be one of: ``'input'``,
``'output-high'`` and ``'output-low'``.
Inside each bank directory, there's a set of attributes that can be used to
configure the new chip. Additionally the user can ``mkdir()`` subdirectories
inside the chip's directory that allow to pass additional configuration for
specific lines. The name of those subdirectories must take the form of:
``'line<offset>'`` (e.g. ``'line0'``, ``'line20'``, etc.) as the name will be
used by the module to assign the config to the specific line at given offset.
Once the confiuration is complete, the ``'live'`` attribute must be set to 1 in
order to instantiate the chip. It can be set back to 0 to destroy the simulated
chip. The module will synchronously wait for the new simulated device to be
successfully probed and if this doesn't happen, writing to ``'live'`` will
result in an error.
Simulated GPIO chips can also be defined in device-tree. The compatible string
must be: ``"gpio-simulator"``. Supported properties are:
``"gpio-sim,label"`` - chip label
Other standard GPIO properties (like ``"gpio-line-names"``, ``"ngpios"`` or
``"gpio-hog"``) are also supported. Please refer to the GPIO documentation for
details.
An example device-tree code defining a GPIO simulator:
.. code-block :: none
gpio-sim {
compatible = "gpio-simulator";
bank0 {
gpio-controller;
#gpio-cells = <2>;
ngpios = <16>;
gpio-sim,label = "dt-bank0";
gpio-line-names = "", "sim-foo", "", "sim-bar";
};
bank1 {
gpio-controller;
#gpio-cells = <2>;
ngpios = <8>;
gpio-sim,label = "dt-bank1";
line3 {
gpio-hog;
gpios = <3 0>;
output-high;
line-name = "sim-hog-from-dt";
};
};
};
Manipulating simulated lines
----------------------------
Each simulated GPIO chip creates a separate sysfs group under its device
directory for each exposed line
(e.g. ``/sys/devices/platform/gpio-sim.X/gpiochipY/``). The name of each group
is of the form: ``'sim_gpioX'`` where X is the offset of the line. Inside each
group there are two attibutes:
``pull`` - allows to read and set the current simulated pull setting for
every line, when writing the value must be one of: ``'pull-up'``,
``'pull-down'``
``value`` - allows to read the current value of the line which may be
different from the pull if the line is being driven from
user-space

2
Documentation/admin-guide/hw-vuln/spectre.rst
View File

@ -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.

85
Documentation/arc/arc.rst Normal file
View File

@ -0,0 +1,85 @@
.. SPDX-License-Identifier: GPL-2.0
Linux kernel for ARC processors
*******************************
Other sources of information
############################
Below are some resources where more information can be found on
ARC processors and relevant open source projects.
- `<https://embarc.org>`_ - Community portal for open source on ARC.
Good place to start to find relevant FOSS projects, toolchain releases,
news items and more.
- `<https://github.com/foss-for-synopsys-dwc-arc-processors>`_ -
Home for all development activities regarding open source projects for
ARC processors. Some of the projects are forks of various upstream projects,
where "work in progress" is hosted prior to submission to upstream projects.
Other projects are developed by Synopsys and made available to community
as open source for use on ARC Processors.
- `Official Synopsys ARC Processors website
<https://www.synopsys.com/designware-ip/processor-solutions.html>`_ -
location, with access to some IP documentation (`Programmer's Reference
Manual, AKA PRM for ARC HS processors
<https://www.synopsys.com/dw/doc.php/ds/cc/programmers-reference-manual-ARC-HS.pdf>`_)
and free versions of some commercial tools (`Free nSIM
<https://www.synopsys.com/cgi-bin/dwarcnsim/req1.cgi>`_ and
`MetaWare Light Edition <https://www.synopsys.com/cgi-bin/arcmwtk_lite/reg1.cgi>`_).
Please note though, registration is required to access both the documentation and
the tools.
Important note on ARC processors configurability
################################################
ARC processors are highly configurable and several configurable options
are supported in Linux. Some options are transparent to software
(i.e cache geometries, some can be detected at runtime and configured
and used accordingly, while some need to be explicitly selected or configured
in the kernel's configuration utility (AKA "make menuconfig").
However not all configurable options are supported when an ARC processor
is to run Linux. SoC design teams should refer to "Appendix E:
Configuration for ARC Linux" in the ARC HS Databook for configurability
guidelines.
Following these guidelines and selecting valid configuration options
up front is critical to help prevent any unwanted issues during
SoC bringup and software development in general.
Building the Linux kernel for ARC processors
############################################
The process of kernel building for ARC processors is the same as for any other
architecture and could be done in 2 ways:
- Cross-compilation: process of compiling for ARC targets on a development
host with a different processor architecture (generally x86_64/amd64).
- Native compilation: process of compiling for ARC on a ARC platform
(hardware board or a simulator like QEMU) with complete development environment
(GNU toolchain, dtc, make etc) installed on the platform.
In both cases, up-to-date GNU toolchain for ARC for the host is needed.
Synopsys offers prebuilt toolchain releases which can be used for this purpose,
available from:
- Synopsys GNU toolchain releases:
`<https://github.com/foss-for-synopsys-dwc-arc-processors/toolchain/releases>`_
- Linux kernel compilers collection:
`<https://mirrors.edge.kernel.org/pub/tools/crosstool>`_
- Bootlin's toolchain collection: `<https://toolchains.bootlin.com>`_
Once the toolchain is installed in the system, make sure its "bin" folder
is added in your ``PATH`` environment variable. Then set ``ARCH=arc`` &
``CROSS_COMPILE=arc-linux`` (or whatever matches installed ARC toolchain prefix)
and then as usual ``make defconfig && make``.
This will produce "vmlinux" file in the root of the kernel source tree
usable for loading on the target system via JTAG.
If you need to get an image usable with U-Boot bootloader,
type ``make uImage`` and ``uImage`` will be produced in ``arch/arc/boot``
folder.

3
Documentation/arc/features.rst Normal file
View File

@ -0,0 +1,3 @@
.. SPDX-License-Identifier: GPL-2.0
.. kernel-feat:: $srctree/Documentation/features arc

17
Documentation/arc/index.rst Normal file
View File

@ -0,0 +1,17 @@
===================
ARC architecture
===================
.. toctree::
:maxdepth: 1
arc
features
.. only:: subproject and html
Indices
=======
* :ref:`genindex`

1
Documentation/arch.rst
View File

@ -9,6 +9,7 @@ implementation.
.. toctree::
:maxdepth: 2
arc/index
arm/index
arm64/index
ia64/index

102
Documentation/conf.py
View File

@ -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.

1
Documentation/dev-tools/index.rst
View File

@ -32,6 +32,7 @@ Documentation/dev-tools/testing-overview.rst
kgdb
kselftest
kunit/index
ktap
.. only:: subproject and html

74
Documentation/dev-tools/kcsan.rst
View File

@ -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

6
Documentation/dev-tools/kgdb.rst
View File

@ -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

298
Documentation/dev-tools/ktap.rst Normal file
View File

@ -0,0 +1,298 @@
.. SPDX-License-Identifier: GPL-2.0
========================================
The Kernel Test Anything Protocol (KTAP)
========================================
TAP, or the Test Anything Protocol is a format for specifying test results used
by a number of projects. It's website and specification are found at this `link
<https://testanything.org/>`_. The Linux Kernel largely uses TAP output for test
results. However, Kernel testing frameworks have special needs for test results
which don't align with the original TAP specification. Thus, a "Kernel TAP"
(KTAP) format is specified to extend and alter TAP to support these use-cases.
This specification describes the generally accepted format of KTAP as it is
currently used in the kernel.
KTAP test results describe a series of tests (which may be nested: i.e., test
can have subtests), each of which can contain both diagnostic data -- e.g., log
lines -- and a final result. The test structure and results are
machine-readable, whereas the diagnostic data is unstructured and is there to
aid human debugging.
KTAP output is built from four different types of lines:
- Version lines
- Plan lines
- Test case result lines
- Diagnostic lines
In general, valid KTAP output should also form valid TAP output, but some
information, in particular nested test results, may be lost. Also note that
there is a stagnant draft specification for TAP14, KTAP diverges from this in
a couple of places (notably the "Subtest" header), which are described where
relevant later in this document.
Version lines
-------------
All KTAP-formatted results begin with a "version line" which specifies which
version of the (K)TAP standard the result is compliant with.
For example:
- "KTAP version 1"
- "TAP version 13"
- "TAP version 14"
Note that, in KTAP, subtests also begin with a version line, which denotes the
start of the nested test results. This differs from TAP14, which uses a
separate "Subtest" line.
While, going forward, "KTAP version 1" should be used by compliant tests, it
is expected that most parsers and other tooling will accept the other versions
listed here for compatibility with existing tests and frameworks.
Plan lines
----------
A test plan provides the number of tests (or subtests) in the KTAP output.
Plan lines must follow the format of "1..N" where N is the number of tests or subtests.
Plan lines follow version lines to indicate the number of nested tests.
While there are cases where the number of tests is not known in advance -- in
which case the test plan may be omitted -- it is strongly recommended one is
present where possible.
Test case result lines
----------------------
Test case result lines indicate the final status of a test.
They are required and must have the format:
.. code-block::
<result> <number> [<description>][ # [<directive>] [<diagnostic data>]]
The result can be either "ok", which indicates the test case passed,
or "not ok", which indicates that the test case failed.
<number> represents the number of the test being performed. The first test must
have the number 1 and the number then must increase by 1 for each additional
subtest within the same test at the same nesting level.
The description is a description of the test, generally the name of
the test, and can be any string of words (can't include #). The
description is optional, but recommended.
The directive and any diagnostic data is optional. If either are present, they
must follow a hash sign, "#".
A directive is a keyword that indicates a different outcome for a test other
than passed and failed. The directive is optional, and consists of a single
keyword preceding the diagnostic data. In the event that a parser encounters
a directive it doesn't support, it should fall back to the "ok" / "not ok"
result.
Currently accepted directives are:
- "SKIP", which indicates a test was skipped (note the result of the test case
result line can be either "ok" or "not ok" if the SKIP directive is used)
- "TODO", which indicates that a test is not expected to pass at the moment,
e.g. because the feature it is testing is known to be broken. While this
directive is inherited from TAP, its use in the kernel is discouraged.
- "XFAIL", which indicates that a test is expected to fail. This is similar
to "TODO", above, and is used by some kselftest tests.
- “TIMEOUT”, which indicates a test has timed out (note the result of the test
case result line should be “not ok” if the TIMEOUT directive is used)
- “ERROR”, which indicates that the execution of a test has failed due to a
specific error that is included in the diagnostic data. (note the result of
the test case result line should be “not ok” if the ERROR directive is used)
The diagnostic data is a plain-text field which contains any additional details
about why this result was produced. This is typically an error message for ERROR
or failed tests, or a description of missing dependencies for a SKIP result.
The diagnostic data field is optional, and results which have neither a
directive nor any diagnostic data do not need to include the "#" field
separator.
Example result lines include:
.. code-block::
ok 1 test_case_name
The test "test_case_name" passed.
.. code-block::
not ok 1 test_case_name
The test "test_case_name" failed.
.. code-block::
ok 1 test # SKIP necessary dependency unavailable
The test "test" was SKIPPED with the diagnostic message "necessary dependency
unavailable".
.. code-block::
not ok 1 test # TIMEOUT 30 seconds
The test "test" timed out, with diagnostic data "30 seconds".
.. code-block::
ok 5 check return code # rcode=0
The test "check return code" passed, with additional diagnostic data “rcode=0”
Diagnostic lines
----------------
If tests wish to output any further information, they should do so using
"diagnostic lines". Diagnostic lines are optional, freeform text, and are
often used to describe what is being tested and any intermediate results in
more detail than the final result and diagnostic data line provides.
Diagnostic lines are formatted as "# <diagnostic_description>", where the
description can be any string. Diagnostic lines can be anywhere in the test
output. As a rule, diagnostic lines regarding a test are directly before the
test result line for that test.
Note that most tools will treat unknown lines (see below) as diagnostic lines,
even if they do not start with a "#": this is to capture any other useful
kernel output which may help debug the test. It is nevertheless recommended
that tests always prefix any diagnostic output they have with a "#" character.
Unknown lines
-------------
There may be lines within KTAP output that do not follow the format of one of
the four formats for lines described above. This is allowed, however, they will
not influence the status of the tests.
Nested tests
------------
In KTAP, tests can be nested. This is done by having a test include within its
output an entire set of KTAP-formatted results. This can be used to categorize
and group related tests, or to split out different results from the same test.
The "parent" test's result should consist of all of its subtests' results,
starting with another KTAP version line and test plan, and end with the overall
result. If one of the subtests fail, for example, the parent test should also
fail.
Additionally, all result lines in a subtest should be indented. One level of
indentation is two spaces: " ". The indentation should begin at the version
line and should end before the parent test's result line.
An example of a test with two nested subtests:
.. code-block::
KTAP version 1
1..1
KTAP version 1
1..2
ok 1 test_1
not ok 2 test_2
# example failed
not ok 1 example
An example format with multiple levels of nested testing:
.. code-block::
KTAP version 1
1..2
KTAP version 1
1..2
KTAP version 1
1..2
not ok 1 test_1
ok 2 test_2
not ok 1 test_3
ok 2 test_4 # SKIP
not ok 1 example_test_1
ok 2 example_test_2
Major differences between TAP and KTAP
--------------------------------------
Note the major differences between the TAP and KTAP specification:
- yaml and json are not recommended in diagnostic messages
- TODO directive not recognized
- KTAP allows for an arbitrary number of tests to be nested
The TAP14 specification does permit nested tests, but instead of using another
nested version line, uses a line of the form
"Subtest: <name>" where <name> is the name of the parent test.
Example KTAP output
--------------------
.. code-block::
KTAP version 1
1..1
KTAP version 1
1..3
KTAP version 1
1..1
# test_1: initializing test_1
ok 1 test_1
ok 1 example_test_1
KTAP version 1
1..2
ok 1 test_1 # SKIP test_1 skipped
ok 2 test_2
ok 2 example_test_2
KTAP version 1
1..3
ok 1 test_1
# test_2: FAIL
not ok 2 test_2
ok 3 test_3 # SKIP test_3 skipped
not ok 3 example_test_3
not ok 1 main_test
This output defines the following hierarchy:
A single test called "main_test", which fails, and has three subtests:
- "example_test_1", which passes, and has one subtest:
- "test_1", which passes, and outputs the diagnostic message "test_1: initializing test_1"
- "example_test_2", which passes, and has two subtests:
- "test_1", which is skipped, with the explanation "test_1 skipped"
- "test_2", which passes
- "example_test_3", which fails, and has three subtests
- "test_1", which passes
- "test_2", which outputs the diagnostic line "test_2: FAIL", and fails.
- "test_3", which is skipped with the explanation "test_3 skipped"
Note that the individual subtests with the same names do not conflict, as they
are found in different parent tests. This output also exhibits some sensible
rules for "bubbling up" test results: a test fails if any of its subtests fail.
Skipped tests do not affect the result of the parent test (though it often
makes sense for a test to be marked skipped if _all_ of its subtests have been
skipped).
See also:
---------
- The TAP specification:
https://testanything.org/tap-version-13-specification.html
- The (stagnant) TAP version 14 specification:
https://github.com/TestAnything/Specification/blob/tap-14-specification/specification.md
- The kselftest documentation:
Documentation/dev-tools/kselftest.rst
- The KUnit documentation:
Documentation/dev-tools/kunit/index.rst

204
Documentation/dev-tools/kunit/architecture.rst Normal file
View File

@ -0,0 +1,204 @@
.. SPDX-License-Identifier: GPL-2.0
==================
KUnit Architecture
==================
The KUnit architecture can be divided into two parts:
- Kernel testing library
- kunit_tool (Command line test harness)
In-Kernel Testing Framework
===========================
The kernel testing library supports KUnit tests written in C using
KUnit. KUnit tests are kernel code. KUnit does several things:
- Organizes tests
- Reports test results
- Provides test utilities
Test Cases
----------
The fundamental unit in KUnit is the test case. The KUnit test cases are
grouped into KUnit suites. A KUnit test case is a function with type
signature ``void (*)(struct kunit *test)``.
These test case functions are wrapped in a struct called
``struct kunit_case``. For code, see:
.. kernel-doc:: include/kunit/test.h
:identifiers: kunit_case
.. note:
``generate_params`` is optional for non-parameterized tests.
Each KUnit test case gets a ``struct kunit`` context
object passed to it that tracks a running test. The KUnit assertion
macros and other KUnit utilities use the ``struct kunit`` context
object. As an exception, there are two fields:
- ``->priv``: The setup functions can use it to store arbitrary test
user data.
- ``->param_value``: It contains the parameter value which can be
retrieved in the parameterized tests.
Test Suites
-----------
A KUnit suite includes a collection of test cases. The KUnit suites
are represented by the ``struct kunit_suite``. For example:
.. code-block:: c
static struct kunit_case example_test_cases[] = {
KUNIT_CASE(example_test_foo),
KUNIT_CASE(example_test_bar),
KUNIT_CASE(example_test_baz),
{}
};
static struct kunit_suite example_test_suite = {
.name = "example",
.init = example_test_init,
.exit = example_test_exit,
.test_cases = example_test_cases,
};
kunit_test_suite(example_test_suite);
In the above example, the test suite ``example_test_suite``, runs the
test cases ``example_test_foo``, ``example_test_bar``, and
``example_test_baz``. Before running the test, the ``example_test_init``
is called and after running the test, ``example_test_exit`` is called.
The ``kunit_test_suite(example_test_suite)`` registers the test suite
with the KUnit test framework.
Executor
--------
The KUnit executor can list and run built-in KUnit tests on boot.
The Test suites are stored in a linker section
called ``.kunit_test_suites``. For code, see:
https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/tree/include/asm-generic/vmlinux.lds.h?h=v5.15#n945.
The linker section consists of an array of pointers to
``struct kunit_suite``, and is populated by the ``kunit_test_suites()``
macro. To run all tests compiled into the kernel, the KUnit executor
iterates over the linker section array.
.. kernel-figure:: kunit_suitememorydiagram.svg
:alt: KUnit Suite Memory
KUnit Suite Memory Diagram
On the kernel boot, the KUnit executor uses the start and end addresses
of this section to iterate over and run all tests. For code, see:
https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/tree/lib/kunit/executor.c
When built as a module, the ``kunit_test_suites()`` macro defines a
``module_init()`` function, which runs all the tests in the compilation
unit instead of utilizing the executor.
In KUnit tests, some error classes do not affect other tests
or parts of the kernel, each KUnit case executes in a separate thread
context. For code, see:
https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/tree/lib/kunit/try-catch.c?h=v5.15#n58
Assertion Macros
----------------
KUnit tests verify state using expectations/assertions.
All expectations/assertions are formatted as:
``KUNIT_{EXPECT|ASSERT}_<op>[_MSG](kunit, property[, message])``
- ``{EXPECT|ASSERT}`` determines whether the check is an assertion or an
expectation.
- For an expectation, if the check fails, marks the test as failed
and logs the failure.
- An assertion, on failure, causes the test case to terminate
immediately.
- Assertions call function:
``void __noreturn kunit_abort(struct kunit *)``.
- ``kunit_abort`` calls function:
``void __noreturn kunit_try_catch_throw(struct kunit_try_catch *try_catch)``.
- ``kunit_try_catch_throw`` calls function:
``void complete_and_exit(struct completion *, long) __noreturn;``
and terminates the special thread context.
- ``<op>`` denotes a check with options: ``TRUE`` (supplied property
has the boolean value “true”), ``EQ`` (two supplied properties are
equal), ``NOT_ERR_OR_NULL`` (supplied pointer is not null and does not
contain an “err” value).
- ``[_MSG]`` prints a custom message on failure.
Test Result Reporting
---------------------
KUnit prints test results in KTAP format. KTAP is based on TAP14, see:
https://github.com/isaacs/testanything.github.io/blob/tap14/tap-version-14-specification.md.
KTAP (yet to be standardized format) works with KUnit and Kselftest.
The KUnit executor prints KTAP results to dmesg, and debugfs
(if configured).
Parameterized Tests
-------------------
Each KUnit parameterized test is associated with a collection of
parameters. The test is invoked multiple times, once for each parameter
value and the parameter is stored in the ``param_value`` field.
The test case includes a ``KUNIT_CASE_PARAM()`` macro that accepts a
generator function.
The generator function is passed the previous parameter and returns the next
parameter. It also provides a macro to generate common-case generators based on
arrays.
For code, see:
.. kernel-doc:: include/kunit/test.h
:identifiers: KUNIT_ARRAY_PARAM
kunit_tool (Command Line Test Harness)
======================================
kunit_tool is a Python script ``(tools/testing/kunit/kunit.py)``
that can be used to configure, build, exec, parse and run (runs other
commands in order) test results. You can either run KUnit tests using
kunit_tool or can include KUnit in kernel and parse manually.
- ``configure`` command generates the kernel ``.config`` from a
``.kunitconfig`` file (and any architecture-specific options).
For some architectures, additional config options are specified in the
``qemu_config`` Python script
(For example: ``tools/testing/kunit/qemu_configs/powerpc.py``).
It parses both the existing ``.config`` and the ``.kunitconfig`` files
and ensures that ``.config`` is a superset of ``.kunitconfig``.
If this is not the case, it will combine the two and run
``make olddefconfig`` to regenerate the ``.config`` file. It then
verifies that ``.config`` is now a superset. This checks if all
Kconfig dependencies are correctly specified in ``.kunitconfig``.
``kunit_config.py`` includes the parsing Kconfigs code. The code which
runs ``make olddefconfig`` is a part of ``kunit_kernel.py``. You can
invoke this command via: ``./tools/testing/kunit/kunit.py config`` and
generate a ``.config`` file.
- ``build`` runs ``make`` on the kernel tree with required options
(depends on the architecture and some options, for example: build_dir)
and reports any errors.
To build a KUnit kernel from the current ``.config``, you can use the
``build`` argument: ``./tools/testing/kunit/kunit.py build``.
- ``exec`` command executes kernel results either directly (using
User-mode Linux configuration), or via an emulator such
as QEMU. It reads results from the log via standard
output (stdout), and passes them to ``parse`` to be parsed.
If you already have built a kernel with built-in KUnit tests,
you can run the kernel and display the test results with the ``exec``
argument: ``./tools/testing/kunit/kunit.py exec``.
- ``parse`` extracts the KTAP output from a kernel log, parses
the test results, and prints a summary. For failed tests, any
diagnostic output will be included.

73
Documentation/dev-tools/kunit/faq.rst
View File

@ -4,56 +4,55 @@
Frequently Asked Questions
==========================
How is this different from Autotest, kselftest, etc?
====================================================
How is this different from Autotest, kselftest, and so on?
==========================================================
KUnit is a unit testing framework. Autotest, kselftest (and some others) are
not.
A `unit test <https://martinfowler.com/bliki/UnitTest.html>`_ is supposed to
test a single unit of code in isolation, hence the name. A unit test should be
the finest granularity of testing and as such should allow all possible code
paths to be tested in the code under test; this is only possible if the code
under test is very small and does not have any external dependencies outside of
test a single unit of code in isolation and hence the name *unit test*. A unit
test should be the finest granularity of testing and should allow all possible
code paths to be tested in the code under test. This is only possible if the
code under test is small and does not have any external dependencies outside of
the test's control like hardware.
There are no testing frameworks currently available for the kernel that do not
require installing the kernel on a test machine or in a VM and all require
tests to be written in userspace and run on the kernel under test; this is true
for Autotest, kselftest, and some others, disqualifying any of them from being
considered unit testing frameworks.
require installing the kernel on a test machine or in a virtual machine. All
testing frameworks require tests to be written in userspace and run on the
kernel under test. This is true for Autotest, kselftest, and some others,
disqualifying any of them from being considered unit testing frameworks.
Does KUnit support running on architectures other than UML?
===========================================================
Yes, well, mostly.
Yes, mostly.
For the most part, the KUnit core framework (what you use to write the tests)
can compile to any architecture; it compiles like just another part of the
For the most part, the KUnit core framework (what we use to write the tests)
can compile to any architecture. It compiles like just another part of the
kernel and runs when the kernel boots, or when built as a module, when the
module is loaded. However, there is some infrastructure,
like the KUnit Wrapper (``tools/testing/kunit/kunit.py``) that does not support
other architectures.
module is loaded. However, there is infrastructure, like the KUnit Wrapper
(``tools/testing/kunit/kunit.py``) that does not support other architectures.
In short, this means that, yes, you can run KUnit on other architectures, but
it might require more work than using KUnit on UML.
In short, yes, you can run KUnit on other architectures, but it might require
more work than using KUnit on UML.
For more information, see :ref:`kunit-on-non-uml`.
What is the difference between a unit test and these other kinds of tests?
==========================================================================
What is the difference between a unit test and other kinds of tests?
====================================================================
Most existing tests for the Linux kernel would be categorized as an integration
test, or an end-to-end test.
- A unit test is supposed to test a single unit of code in isolation, hence the
name. A unit test should be the finest granularity of testing and as such
should allow all possible code paths to be tested in the code under test; this
is only possible if the code under test is very small and does not have any
external dependencies outside of the test's control like hardware.
- A unit test is supposed to test a single unit of code in isolation. A unit
test should be the finest granularity of testing and, as such, allows all
possible code paths to be tested in the code under test. This is only possible
if the code under test is small and does not have any external dependencies
outside of the test's control like hardware.
- An integration test tests the interaction between a minimal set of components,
usually just two or three. For example, someone might write an integration
test to test the interaction between a driver and a piece of hardware, or to
test the interaction between the userspace libraries the kernel provides and
the kernel itself; however, one of these tests would probably not test the
the kernel itself. However, one of these tests would probably not test the
entire kernel along with hardware interactions and interactions with the
userspace.
- An end-to-end test usually tests the entire system from the perspective of the
@ -62,26 +61,26 @@ test, or an end-to-end test.
hardware with a production userspace and then trying to exercise some behavior
that depends on interactions between the hardware, the kernel, and userspace.
KUnit isn't working, what should I do?
======================================
KUnit is not working, what should I do?
=======================================
Unfortunately, there are a number of things which can break, but here are some
things to try.
1. Try running ``./tools/testing/kunit/kunit.py run`` with the ``--raw_output``
1. Run ``./tools/testing/kunit/kunit.py run`` with the ``--raw_output``
parameter. This might show details or error messages hidden by the kunit_tool
parser.
2. Instead of running ``kunit.py run``, try running ``kunit.py config``,
``kunit.py build``, and ``kunit.py exec`` independently. This can help track
down where an issue is occurring. (If you think the parser is at fault, you
can run it manually against stdin or a file with ``kunit.py parse``.)
3. Running the UML kernel directly can often reveal issues or error messages
kunit_tool ignores. This should be as simple as running ``./vmlinux`` after
building the UML kernel (e.g., by using ``kunit.py build``). Note that UML
has some unusual requirements (such as the host having a tmpfs filesystem
mounted), and has had issues in the past when built statically and the host
has KASLR enabled. (On older host kernels, you may need to run ``setarch
`uname -m` -R ./vmlinux`` to disable KASLR.)
can run it manually against ``stdin`` or a file with ``kunit.py parse``.)
3. Running the UML kernel directly can often reveal issues or error messages,
``kunit_tool`` ignores. This should be as simple as running ``./vmlinux``
after building the UML kernel (for example, by using ``kunit.py build``).
Note that UML has some unusual requirements (such as the host having a tmpfs
filesystem mounted), and has had issues in the past when built statically and
the host has KASLR enabled. (On older host kernels, you may need to run
``setarch `uname -m` -R ./vmlinux`` to disable KASLR.)
4. Make sure the kernel .config has ``CONFIG_KUNIT=y`` and at least one test
(e.g. ``CONFIG_KUNIT_EXAMPLE_TEST=y``). kunit_tool will keep its .config
around, so you can see what config was used after running ``kunit.py run``.

144
Documentation/dev-tools/kunit/index.rst
View File

@ -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 <https://testanything.org/>`_. 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 <https://testanything.org/>`_ 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 <kunit-tool>`, which builds a `User Mode Linux
<http://user-mode-linux.sourceforge.net>`_ kernel, runs it, and parses the test
results. This provides a quick way of running KUnit tests during development,
without requiring a virtual machine or separate hardware.
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 <http://user-mode-linux.sourceforge.net/>`_), 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 <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
<https://gist.github.com/lorn/1272686/revisions#diff-53c65572127855f1b003db4064a94573R874>`_:
"... a lot of people seem to think that performance is about doing the
same thing, just doing it faster, and that is not true. That is not what
performance is all about. If you can do something really fast, really
well, people will start using it differently."
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.

81
Documentation/dev-tools/kunit/kunit_suitememorydiagram.svg Normal file
View File

@ -0,0 +1,81 @@
<?xml version="1.0" encoding="UTF-8"?>
<svg width="796.93" height="555.73" version="1.1" viewBox="0 0 796.93 555.73" xmlns="http://www.w3.org/2000/svg">
<g transform="translate(-13.724 -17.943)">
<g fill="#dad4d4" fill-opacity=".91765" stroke="#1a1a1a">
<rect x="323.56" y="18.443" width="115.75" height="41.331"/>
<rect x="323.56" y="463.09" width="115.75" height="41.331"/>
<rect x="323.56" y="531.84" width="115.75" height="41.331"/>
<rect x="323.56" y="88.931" width="115.75" height="74.231"/>
</g>
<g>
<rect x="323.56" y="421.76" width="115.75" height="41.331" fill="#b9dbc6" stroke="#1a1a1a"/>
<text x="328.00888" y="446.61826" fill="#000000" font-family="sans-serif" font-size="16px" style="line-height:1.25" xml:space="preserve"><tspan x="328.00888" y="446.61826" font-family="monospace" font-size="16px">kunit_suite</tspan></text>
</g>
<g transform="translate(0 -258.6)">
<rect x="323.56" y="421.76" width="115.75" height="41.331" fill="#b9dbc6" stroke="#1a1a1a"/>
<text x="328.00888" y="446.61826" fill="#000000" font-family="sans-serif" font-size="16px" style="line-height:1.25" xml:space="preserve"><tspan x="328.00888" y="446.61826" font-family="monospace" font-size="16px">kunit_suite</tspan></text>
</g>
<g transform="translate(0 -217.27)">
<rect x="323.56" y="421.76" width="115.75" height="41.331" fill="#b9dbc6" stroke="#1a1a1a"/>
<text x="328.00888" y="446.61826" fill="#000000" font-family="sans-serif" font-size="16px" style="line-height:1.25" xml:space="preserve"><tspan x="328.00888" y="446.61826" font-family="monospace" font-size="16px">kunit_suite</tspan></text>
</g>
<g transform="translate(0 -175.94)">
<rect x="323.56" y="421.76" width="115.75" height="41.331" fill="#b9dbc6" stroke="#1a1a1a"/>
<text x="328.00888" y="446.61826" fill="#000000" font-family="sans-serif" font-size="16px" style="line-height:1.25" xml:space="preserve"><tspan x="328.00888" y="446.61826" font-family="monospace" font-size="16px">kunit_suite</tspan></text>
</g>
<g transform="translate(0 -134.61)">
<rect x="323.56" y="421.76" width="115.75" height="41.331" fill="#b9dbc6" stroke="#1a1a1a"/>
<text x="328.00888" y="446.61826" fill="#000000" font-family="sans-serif" font-size="16px" style="line-height:1.25" xml:space="preserve"><tspan x="328.00888" y="446.61826" font-family="monospace" font-size="16px">kunit_suite</tspan></text>
</g>
<g transform="translate(0 -41.331)">
<rect x="323.56" y="421.76" width="115.75" height="41.331" fill="#b9dbc6" stroke="#1a1a1a"/>
<text x="328.00888" y="446.61826" fill="#000000" font-family="sans-serif" font-size="16px" style="line-height:1.25" xml:space="preserve"><tspan x="328.00888" y="446.61826" font-family="monospace" font-size="16px">kunit_suite</tspan></text>
</g>
<g transform="translate(3.4459e-5 -.71088)">
<rect x="502.19" y="143.16" width="201.13" height="41.331" fill="#dad4d4" fill-opacity=".91765" stroke="#1a1a1a"/>
<text x="512.02319" y="168.02026" font-family="sans-serif" font-size="16px" style="line-height:1.25" xml:space="preserve"><tspan x="512.02319" y="168.02026" font-family="monospace">_kunit_suites_start</tspan></text>
</g>
<g transform="translate(3.0518e-5 -3.1753)">
<rect x="502.19" y="445.69" width="201.13" height="41.331" fill="#dad4d4" fill-opacity=".91765" stroke="#1a1a1a"/>
<text x="521.61694" y="470.54846" font-family="sans-serif" font-size="16px" style="line-height:1.25" xml:space="preserve"><tspan x="521.61694" y="470.54846" font-family="monospace">_kunit_suites_end</tspan></text>
</g>
<rect x="14.224" y="277.78" width="134.47" height="41.331" fill="#dad4d4" fill-opacity=".91765" stroke="#1a1a1a"/>
<text x="32.062176" y="304.41287" font-family="sans-serif" font-size="16px" style="line-height:1.25" xml:space="preserve"><tspan x="32.062176" y="304.41287" font-family="monospace">.init.data</tspan></text>
<g transform="translate(217.98 145.12)" stroke="#1a1a1a">
<circle cx="149.97" cy="373.01" r="3.4012"/>
<circle cx="163.46" cy="373.01" r="3.4012"/>
<circle cx="176.95" cy="373.01" r="3.4012"/>
</g>
<g transform="translate(217.98 -298.66)" stroke="#1a1a1a">
<circle cx="149.97" cy="373.01" r="3.4012"/>
<circle cx="163.46" cy="373.01" r="3.4012"/>
<circle cx="176.95" cy="373.01" r="3.4012"/>
</g>
<g stroke="#1a1a1a">
<rect x="323.56" y="328.49" width="115.75" height="51.549" fill="#b9dbc6"/>
<g transform="translate(217.98 -18.75)">
<circle cx="149.97" cy="373.01" r="3.4012"/>
<circle cx="163.46" cy="373.01" r="3.4012"/>
<circle cx="176.95" cy="373.01" r="3.4012"/>
</g>
</g>
<g transform="scale(1.0933 .9147)" stroke-width="32.937" aria-label="{">
<path d="m275.49 545.57c-35.836-8.432-47.43-24.769-47.957-64.821v-88.536c-0.527-44.795-10.54-57.97-49.538-67.456 38.998-10.013 49.011-23.715 49.538-67.983v-88.536c0.527-40.052 12.121-56.389 47.957-64.821v-5.797c-65.348 0-85.901 17.391-86.955 73.253v93.806c-0.527 36.89-10.013 50.065-44.795 59.551 34.782 10.013 44.268 23.188 44.795 60.078v93.279c1.581 56.389 21.607 73.78 86.955 73.78z"/>
</g>
<g transform="scale(1.1071 .90325)" stroke-width="14.44" aria-label="{">
<path d="m461.46 443.55c-15.711-3.6967-20.794-10.859-21.025-28.418v-38.815c-0.23104-19.639-4.6209-25.415-21.718-29.574 17.097-4.3898 21.487-10.397 21.718-29.805v-38.815c0.23105-17.559 5.314-24.722 21.025-28.418v-2.5415c-28.649 0-37.66 7.6244-38.122 32.115v41.126c-0.23105 16.173-4.3898 21.949-19.639 26.108 15.249 4.3898 19.408 10.166 19.639 26.339v40.895c0.69313 24.722 9.4728 32.346 38.122 32.346z"/>
</g>
<path d="m449.55 161.84v2.5h49.504v-2.5z" color="#000000" style="-inkscape-stroke:none"/>
<g fill-rule="evenodd">
<path d="m443.78 163.09 8.65-5v10z" color="#000000" stroke-width="1pt" style="-inkscape-stroke:none"/>
<path d="m453.1 156.94-10.648 6.1543 0.99804 0.57812 9.6504 5.5781zm-1.334 2.3125v7.6856l-6.6504-3.8438z" color="#000000" style="-inkscape-stroke:none"/>
</g>
<path d="m449.55 461.91v2.5h49.504v-2.5z" color="#000000" style="-inkscape-stroke:none"/>
<g fill-rule="evenodd">
<path d="m443.78 463.16 8.65-5v10z" color="#000000" stroke-width="1pt" style="-inkscape-stroke:none"/>
<path d="m453.1 457-10.648 6.1562 0.99804 0.57617 9.6504 5.5781zm-1.334 2.3125v7.6856l-6.6504-3.8438z" color="#000000" style="-inkscape-stroke:none"/>
</g>
<rect x="515.64" y="223.9" width="294.52" height="178.49" fill="#dad4d4" fill-opacity=".91765" stroke="#1a1a1a"/>
<text x="523.33319" y="262.52542" font-family="monospace" font-size="14.667px" style="line-height:1.25" xml:space="preserve"><tspan x="523.33319" y="262.52542"><tspan fill="#008000" font-family="monospace" font-size="14.667px" font-weight="bold">struct</tspan> kunit_suite {</tspan><tspan x="523.33319" y="280.8588"><tspan fill="#008000" font-family="monospace" font-size="14.667px" font-weight="bold"> const char</tspan> name[<tspan fill="#ff00ff" font-size="14.667px">256</tspan>];</tspan><tspan x="523.33319" y="299.19217"> <tspan fill="#008000" font-family="monospace" font-size="14.667px" font-weight="bold">int</tspan> (*init)(<tspan fill="#008000" font-family="monospace" font-size="14.667px" font-weight="bold">struct</tspan> kunit *);</tspan><tspan x="523.33319" y="317.52554"> <tspan fill="#008000" font-family="monospace" font-size="14.667px" font-weight="bold">void</tspan> (*exit)(<tspan fill="#008000" font-family="monospace" font-size="14.667px" font-weight="bold">struct</tspan> kunit *);</tspan><tspan x="523.33319" y="335.85892"> <tspan fill="#008000" font-family="monospace" font-size="14.667px" font-weight="bold">struct</tspan> kunit_case *test_cases;</tspan><tspan x="523.33319" y="354.19229"> ...</tspan><tspan x="523.33319" y="372.52567">};</tspan></text>
</g>
</svg>
Side by Side

After

Width:  |  Height:  |  Size: 7.6 KiB

57
Documentation/dev-tools/kunit/run_manual.rst Normal file
View File

@ -0,0 +1,57 @@
.. SPDX-License-Identifier: GPL-2.0
============================
Run Tests without kunit_tool
============================
If we do not want to use kunit_tool (For example: we want to integrate
with other systems, or run tests on real hardware), we can
include KUnit in any kernel, read out results, and parse manually.
.. note:: KUnit is not designed for use in a production system. It is
possible that tests may reduce the stability or security of
the system.
Configure the Kernel
====================
KUnit tests can run without kunit_tool. This can be useful, if:
- We have an existing kernel configuration to test.
- Need to run on real hardware (or using an emulator/VM kunit_tool
does not support).
- Wish to integrate with some existing testing systems.
KUnit is configured with the ``CONFIG_KUNIT`` option, and individual
tests can also be built by enabling their config options in our
``.config``. KUnit tests usually (but don't always) have config options
ending in ``_KUNIT_TEST``. Most tests can either be built as a module,
or be built into the kernel.
.. note ::
We can enable the ``KUNIT_ALL_TESTS`` config option to
automatically enable all tests with satisfied dependencies. This is
a good way of quickly testing everything applicable to the current
config.
Once we have built our kernel (and/or modules), it is simple to run
the tests. If the tests are built-in, they will run automatically on the
kernel boot. The results will be written to the kernel log (``dmesg``)
in TAP format.
If the tests are built as modules, they will run when the module is
loaded.
.. code-block :: bash
# modprobe example-test
The results will appear in TAP format in ``dmesg``.
.. note ::
If ``CONFIG_KUNIT_DEBUGFS`` is enabled, KUnit test results will
be accessible from the ``debugfs`` filesystem (if mounted).
They will be in ``/sys/kernel/debug/kunit/<test_suite>/results``, in
TAP format.

247
Documentation/dev-tools/kunit/run_wrapper.rst Normal file
View File

@ -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``.

187
Documentation/dev-tools/kunit/start.rst
View File

@ -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 <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 <https://testanything.org/>`_ 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.

105
Documentation/dev-tools/kunit/style.rst
View File

@ -4,37 +4,36 @@
Test Style and Nomenclature
===========================
To make finding, writing, and using KUnit tests as simple as possible, it's
To make finding, writing, and using KUnit tests as simple as possible, it is
strongly encouraged that they are named and written according to the guidelines
below. While it's possible to write KUnit tests which do not follow these rules,
below. While it is possible to write KUnit tests which do not follow these rules,
they may break some tooling, may conflict with other tests, and may not be run
automatically by testing systems.
It's recommended that you only deviate from these guidelines when:
It is recommended that you only deviate from these guidelines when:
1. Porting tests to KUnit which are already known with an existing name, or
2. Writing tests which would cause serious problems if automatically run (e.g.,
non-deterministically producing false positives or negatives, or taking an
extremely long time to run).
1. Porting tests to KUnit which are already known with an existing name.
2. Writing tests which would cause serious problems if automatically run. For
example, non-deterministically producing false positives or negatives, or
taking a long time to run.
Subsystems, Suites, and Tests
=============================
In order to make tests as easy to find as possible, they're grouped into suites
and subsystems. A test suite is a group of tests which test a related area of
the kernel, and a subsystem is a set of test suites which test different parts
of the same kernel subsystem or driver.
To make tests easy to find, they are grouped into suites and subsystems. A test
suite is a group of tests which test a related area of the kernel. A subsystem
is a set of test suites which test different parts of a kernel subsystem
or a driver.
Subsystems
----------
Every test suite must belong to a subsystem. A subsystem is a collection of one
or more KUnit test suites which test the same driver or part of the kernel. A
rule of thumb is that a test subsystem should match a single kernel module. If
the code being tested can't be compiled as a module, in many cases the subsystem
should correspond to a directory in the source tree or an entry in the
MAINTAINERS file. If unsure, follow the conventions set by tests in similar
areas.
test subsystem should match a single kernel module. If the code being tested
cannot be compiled as a module, in many cases the subsystem should correspond to
a directory in the source tree or an entry in the ``MAINTAINERS`` file. If
unsure, follow the conventions set by tests in similar areas.
Test subsystems should be named after the code being tested, either after the
module (wherever possible), or after the directory or files being tested. Test
@ -42,9 +41,8 @@ subsystems should be named to avoid ambiguity where necessary.
If a test subsystem name has multiple components, they should be separated by
underscores. *Do not* include "test" or "kunit" directly in the subsystem name
unless you are actually testing other tests or the kunit framework itself.
Example subsystems could be:
unless we are actually testing other tests or the kunit framework itself. For
example, subsystems could be called:
``ext4``
Matches the module and filesystem name.
@ -56,48 +54,46 @@ Example subsystems could be:
Has several components (``snd``, ``hda``, ``codec``, ``hdmi``) separated by
underscores. Matches the module name.
Avoid names like these:
Avoid names as shown in examples below:
``linear-ranges``
Names should use underscores, not dashes, to separate words. Prefer
``linear_ranges``.
``qos-kunit-test``
As well as using underscores, this name should not have "kunit-test" as a
suffix, and ``qos`` is ambiguous as a subsystem name. ``power_qos`` would be a
better name.
This name should use underscores, and not have "kunit-test" as a
suffix. ``qos`` is also ambiguous as a subsystem name, because several parts
of the kernel have a ``qos`` subsystem. ``power_qos`` would be a better name.
``pc_parallel_port``
The corresponding module name is ``parport_pc``, so this subsystem should also
be named ``parport_pc``.
.. note::
The KUnit API and tools do not explicitly know about subsystems. They're
simply a way of categorising test suites and naming modules which
provides a simple, consistent way for humans to find and run tests. This
may change in the future, though.
The KUnit API and tools do not explicitly know about subsystems. They are
a way of categorizing test suites and naming modules which provides a
simple, consistent way for humans to find and run tests. This may change
in the future.
Suites
------
KUnit tests are grouped into test suites, which cover a specific area of
functionality being tested. Test suites can have shared initialisation and
shutdown code which is run for all tests in the suite.
Not all subsystems will need to be split into multiple test suites (e.g. simple drivers).
functionality being tested. Test suites can have shared initialization and
shutdown code which is run for all tests in the suite. Not all subsystems need
to be split into multiple test suites (for example, simple drivers).
Test suites are named after the subsystem they are part of. If a subsystem
contains several suites, the specific area under test should be appended to the
subsystem name, separated by an underscore.
In the event that there are multiple types of test using KUnit within a
subsystem (e.g., both unit tests and integration tests), they should be put into
separate suites, with the type of test as the last element in the suite name.
Unless these tests are actually present, avoid using ``_test``, ``_unittest`` or
similar in the suite name.
subsystem (for example, both unit tests and integration tests), they should be
put into separate suites, with the type of test as the last element in the suite
name. Unless these tests are actually present, avoid using ``_test``, ``_unittest``
or similar in the suite name.
The full test suite name (including the subsystem name) should be specified as
the ``.name`` member of the ``kunit_suite`` struct, and forms the base for the
module name (see below).
Example test suites could include:
module name. For example, test suites could include:
``ext4_inode``
Part of the ``ext4`` subsystem, testing the ``inode`` area.
@ -109,26 +105,27 @@ Example test suites could include:
The ``kasan`` subsystem has only one suite, so the suite name is the same as
the subsystem name.
Avoid names like:
Avoid names, for example:
``ext4_ext4_inode``
There's no reason to state the subsystem twice.
There is no reason to state the subsystem twice.
``property_entry``
The suite name is ambiguous without the subsystem name.
``kasan_integration_test``
Because there is only one suite in the ``kasan`` subsystem, the suite should
just be called ``kasan``. There's no need to redundantly add
``integration_test``. Should a separate test suite with, for example, unit
tests be added, then that suite could be named ``kasan_unittest`` or similar.
just be called as ``kasan``. Do not redundantly add
``integration_test``. It should be a separate test suite. For example, if the
unit tests are added, then that suite could be named as ``kasan_unittest`` or
similar.
Test Cases
----------
Individual tests consist of a single function which tests a constrained
codepath, property, or function. In the test output, individual tests' results
will show up as subtests of the suite's results.
codepath, property, or function. In the test output, an individual test's
results will show up as subtests of the suite's results.
Tests should be named after what they're testing. This is often the name of the
Tests should be named after what they are testing. This is often the name of the
function being tested, with a description of the input or codepath being tested.
As tests are C functions, they should be named and written in accordance with
the kernel coding style.
@ -136,7 +133,7 @@ the kernel coding style.
.. note::
As tests are themselves functions, their names cannot conflict with
other C identifiers in the kernel. This may require some creative
naming. It's a good idea to make your test functions `static` to avoid
naming. It is a good idea to make your test functions `static` to avoid
polluting the global namespace.
Example test names include:
@ -162,16 +159,16 @@ This Kconfig entry must:
* be named ``CONFIG_<name>_KUNIT_TEST``: where <name> is the name of the test
suite.
* be listed either alongside the config entries for the driver/subsystem being
tested, or be under [Kernel Hacking]→[Kernel Testing and Coverage]
* depend on ``CONFIG_KUNIT``
tested, or be under [Kernel Hacking]->[Kernel Testing and Coverage]
* depend on ``CONFIG_KUNIT``.
* be visible only if ``CONFIG_KUNIT_ALL_TESTS`` is not enabled.
* have a default value of ``CONFIG_KUNIT_ALL_TESTS``.
* have a brief description of KUnit in the help text
* have a brief description of KUnit in the help text.
Unless there's a specific reason not to (e.g. the test is unable to be built as
a module), Kconfig entries for tests should be tristate.
If we are not able to meet above conditions (for example, the test is unable to
be built as a module), Kconfig entries for tests should be tristate.
An example Kconfig entry:
For example, a Kconfig entry might look like:
.. code-block:: none
@ -182,8 +179,8 @@ An example Kconfig entry:
help
This builds unit tests for foo.
For more information on KUnit and unit tests in general, please refer
to the KUnit documentation in Documentation/dev-tools/kunit/.
For more information on KUnit and unit tests in general,
please refer to the KUnit documentation in Documentation/dev-tools/kunit/.
If unsure, say N.

588
Documentation/dev-tools/kunit/usage.rst
View File

@ -1,57 +1,13 @@
.. SPDX-License-Identifier: GPL-2.0
===========
Using KUnit
===========
The purpose of this document is to describe what KUnit is, how it works, how it
is intended to be used, and all the concepts and terminology that are needed to
understand it. This guide assumes a working knowledge of the Linux kernel and
some basic knowledge of testing.
For a high level introduction to KUnit, including setting up KUnit for your
project, see Documentation/dev-tools/kunit/start.rst.
Organization of this document
=============================
This document is organized into two main sections: Testing and Common Patterns.
The first covers what unit tests are and how to use KUnit to write them. The
second covers common testing patterns, e.g. how to isolate code and make it
possible to unit test code that was otherwise un-unit-testable.
Testing
=======
What is KUnit?
--------------
"K" is short for "kernel" so "KUnit" is the "(Linux) Kernel Unit Testing
Framework." KUnit is intended first and foremost for writing unit tests; it is
general enough that it can be used to write integration tests; however, this is
a secondary goal. KUnit has no ambition of being the only testing framework for
the kernel; for example, it does not intend to be an end-to-end testing
framework.
What is Unit Testing?
---------------------
A `unit test <https://martinfowler.com/bliki/UnitTest.html>`_ is a test that
tests code at the smallest possible scope, a *unit* of code. In the C
programming language that's a function.
Unit tests should be written for all the publicly exposed functions in a
compilation unit; so that is all the functions that are exported in either a
*class* (defined below) or all functions which are **not** static.
Writing Tests
-------------
=============
Test Cases
~~~~~~~~~~
----------
The fundamental unit in KUnit is the test case. A test case is a function with
the signature ``void (*)(struct kunit *test)``. It calls a function to be tested
the signature ``void (*)(struct kunit *test)``. It calls the function under test
and then sets *expectations* for what should happen. For example:
.. code-block:: c
@ -65,18 +21,19 @@ and then sets *expectations* for what should happen. For example:
KUNIT_FAIL(test, "This test never passes.");
}
In the above example ``example_test_success`` always passes because it does
nothing; no expectations are set, so all expectations pass. On the other hand
``example_test_failure`` always fails because it calls ``KUNIT_FAIL``, which is
a special expectation that logs a message and causes the test case to fail.
In the above example, ``example_test_success`` always passes because it does
nothing; no expectations are set, and therefore all expectations pass. On the
other hand ``example_test_failure`` always fails because it calls ``KUNIT_FAIL``,
which is a special expectation that logs a message and causes the test case to
fail.
Expectations
~~~~~~~~~~~~
An *expectation* is a way to specify that you expect a piece of code to do
something in a test. An expectation is called like a function. A test is made
by setting expectations about the behavior of a piece of code under test; when
one or more of the expectations fail, the test case fails and information about
the failure is logged. For example:
An *expectation* specifies that we expect a piece of code to do something in a
test. An expectation is called like a function. A test is made by setting
expectations about the behavior of a piece of code under test. When one or more
expectations fail, the test case fails and information about the failure is
logged. For example:
.. code-block:: c
@ -86,29 +43,28 @@ the failure is logged. For example:
KUNIT_EXPECT_EQ(test, 2, add(1, 1));
}
In the above example ``add_test_basic`` makes a number of assertions about the
behavior of a function called ``add``; the first parameter is always of type
``struct kunit *``, which contains information about the current test context;
the second parameter, in this case, is what the value is expected to be; the
In the above example, ``add_test_basic`` makes a number of assertions about the
behavior of a function called ``add``. The first parameter is always of type
``struct kunit *``, which contains information about the current test context.
The second parameter, in this case, is what the value is expected to be. The
last value is what the value actually is. If ``add`` passes all of these
expectations, the test case, ``add_test_basic`` will pass; if any one of these
expectations fails, the test case will fail.
It is important to understand that a test case *fails* when any expectation is
violated; however, the test will continue running, potentially trying other
expectations until the test case ends or is otherwise terminated. This is as
opposed to *assertions* which are discussed later.
A test case *fails* when any expectation is violated; however, the test will
continue to run, and try other expectations until the test case ends or is
otherwise terminated. This is as opposed to *assertions* which are discussed
later.
To learn about more expectations supported by KUnit, see
Documentation/dev-tools/kunit/api/test.rst.
To learn about more KUnit expectations, see Documentation/dev-tools/kunit/api/test.rst.
.. note::
A single test case should be pretty short, pretty easy to understand,
focused on a single behavior.
A single test case should be short, easy to understand, and focused on a
single behavior.
For example, if we wanted to properly test the add function above, we would
create additional tests cases which would each test a different property that an
add function should have like this:
For example, if we want to rigorously test the ``add`` function above, create
additional tests cases which would test each property that an ``add`` function
should have as shown below:
.. code-block:: c
@ -134,56 +90,43 @@ add function should have like this:
KUNIT_EXPECT_EQ(test, INT_MIN, add(INT_MAX, 1));
}
Notice how it is immediately obvious what all the properties that we are testing
for are.
Assertions
~~~~~~~~~~
KUnit also has the concept of an *assertion*. An assertion is just like an
expectation except the assertion immediately terminates the test case if it is
not satisfied.
For example:
An assertion is like an expectation, except that the assertion immediately
terminates the test case if the condition is not satisfied. For example:
.. code-block:: c
static void mock_test_do_expect_default_return(struct kunit *test)
static void test_sort(struct kunit *test)
{
struct mock_test_context *ctx = test->priv;
struct mock *mock = ctx->mock;
int param0 = 5, param1 = -5;
const char *two_param_types[] = {"int", "int"};
const void *two_params[] = {&param0, &param1};
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 <linux/sched.h> /* 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/<test-suite>``. 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 ``<kunit/test-bug.h>`` and does not require pulling in ``<kunit/test.h>``.
For example, we have an option to enable some extra debug checks on some data
structures as shown below:
.. code-block:: c
#include <kunit/test-bug.h>
#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``).

41
Documentation/devicetree/bindings/gpio/gpio-samsung.txt
View File

@ -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;
};

3
Documentation/devicetree/bindings/gpio/gpio-vf610.yaml
View File

@ -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

4
Documentation/devicetree/bindings/gpio/mstar,msc313-gpio.yaml
View File

@ -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

165
Documentation/devicetree/bindings/gpio/nvidia,tegra186-gpio.txt
View File

@ -1,165 +0,0 @@
NVIDIA Tegra186 GPIO controllers
Tegra186 contains two GPIO controllers; a main controller and an "AON"
controller. This binding document applies to both controllers. The register
layouts for the controllers share many similarities, but also some significant
differences. Hence, this document describes closely related but different
bindings and compatible values.
The Tegra186 GPIO controller allows software to set the IO direction of, and
read/write the value of, numerous GPIO signals. Routing of GPIO signals to
package balls is under the control of a separate pin controller HW block. Two
major sets of registers exist:
a) Security registers, which allow configuration of allowed access to the GPIO
register set. These registers exist in a single contiguous block of physical
address space. The size of this block, and the security features available,
varies between the different GPIO controllers.
Access to this set of registers is not necessary in all circumstances. Code
that wishes to configure access to the GPIO registers needs access to these
registers to do so. Code which simply wishes to read or write GPIO data does not
need access to these registers.
b) GPIO registers, which allow manipulation of the GPIO signals. In some GPIO
controllers, these registers are exposed via multiple "physical aliases" in
address space, each of which access the same underlying state. See the hardware
documentation for rationale. Any particular GPIO client is expected to access
just one of these physical aliases.
Tegra HW documentation describes a unified naming convention for all GPIOs
implemented by the SoC. Each GPIO is assigned to a port, and a port may control
a number of GPIOs. Thus, each GPIO is named according to an alphabetical port
name and an integer GPIO name within the port. For example, GPIO_PA0, GPIO_PN6,
or GPIO_PCC3.
The number of ports implemented by each GPIO controller varies. The number of
implemented GPIOs within each port varies. GPIO registers within a controller
are grouped and laid out according to the port they affect.
The mapping from port name to the GPIO controller that implements that port, and
the mapping from port name to register offset within a controller, are both
extremely non-linear. The header file <dt-bindings/gpio/tegra186-gpio.h>
describes the port-level mapping. In that file, the naming convention for ports
matches the HW documentation. The values chosen for the names are alphabetically
sorted within a particular controller. Drivers need to map between the DT GPIO
IDs and HW register offsets using a lookup table.
Each GPIO controller can generate a number of interrupt signals. Each signal
represents the aggregate status for all GPIOs within a set of ports. Thus, the
number of interrupt signals generated by a controller varies as a rough function
of the number of ports it implements. Note that the HW documentation refers to
both the overall controller HW module and the sets-of-ports as "controllers".
Each GPIO controller in fact generates multiple interrupts signals for each set
of ports. Each GPIO may be configured to feed into a specific one of the
interrupt signals generated by a set-of-ports. The intent is for each generated
signal to be routed to a different CPU, thus allowing different CPUs to each
handle subsets of the interrupts within a port. The status of each of these
per-port-set signals is reported via a separate register. Thus, a driver needs
to know which status register to observe. This binding currently defines no
configuration mechanism for this. By default, drivers should use register
GPIO_${port}_INTERRUPT_STATUS_G1_0. Future revisions to the binding could
define a property to configure this.
Required properties:
- compatible
Array of strings.
One of:
- "nvidia,tegra186-gpio".
- "nvidia,tegra186-gpio-aon".
- "nvidia,tegra194-gpio".
- "nvidia,tegra194-gpio-aon".
- reg-names
Array of strings.
Contains a list of names for the register spaces described by the reg
property. May contain the following entries, in any order:
- "gpio": Mandatory. GPIO control registers. This may cover either:
a) The single physical alias that this OS should use.
b) All physical aliases that exist in the controller. This is
appropriate when the OS is responsible for managing assignment of
the physical aliases.
- "security": Optional. Security configuration registers.
Users of this binding MUST look up entries in the reg property by name,
using this reg-names property to do so.
- reg
Array of (physical base address, length) tuples.
Must contain one entry per entry in the reg-names property, in a matching
order.
- interrupts
Array of interrupt specifiers.
The interrupt outputs from the HW block, one per set of ports, in the
order the HW manual describes them. The number of entries required varies
depending on compatible value:
- "nvidia,tegra186-gpio": 6 entries.
- "nvidia,tegra186-gpio-aon": 1 entry.
- "nvidia,tegra194-gpio": 6 entries.
- "nvidia,tegra194-gpio-aon": 1 entry.
- gpio-controller
Boolean.
Marks the device node as a GPIO controller/provider.
- #gpio-cells
Single-cell integer.
Must be <2>.
Indicates how many cells are used in a consumer's GPIO specifier.
In the specifier:
- The first cell is the pin number.
See <dt-bindings/gpio/tegra186-gpio.h>.
- The second cell contains flags:
- Bit 0 specifies polarity
- 0: Active-high (normal).
- 1: Active-low (inverted).
- interrupt-controller
Boolean.
Marks the device node as an interrupt controller/provider.
- #interrupt-cells
Single-cell integer.
Must be <2>.
Indicates how many cells are used in a consumer's interrupt specifier.
In the specifier:
- The first cell is the GPIO number.
See <dt-bindings/gpio/tegra186-gpio.h>.
- The second cell is contains flags:
- Bits [3:0] indicate trigger type and level:
- 1: Low-to-high edge triggered.
- 2: High-to-low edge triggered.
- 4: Active high level-sensitive.
- 8: Active low level-sensitive.
Valid combinations are 1, 2, 3, 4, 8.
Example:
#include <dt-bindings/interrupt-controller/irq.h>
gpio@2200000 {
compatible = "nvidia,tegra186-gpio";
reg-names = "security", "gpio";
reg =
<0x0 0x2200000 0x0 0x10000>,
<0x0 0x2210000 0x0 0x10000>;
interrupts =
<0 47 IRQ_TYPE_LEVEL_HIGH>,
<0 50 IRQ_TYPE_LEVEL_HIGH>,
<0 53 IRQ_TYPE_LEVEL_HIGH>,
<0 56 IRQ_TYPE_LEVEL_HIGH>,
<0 59 IRQ_TYPE_LEVEL_HIGH>,
<0 180 IRQ_TYPE_LEVEL_HIGH>;
gpio-controller;
#gpio-cells = <2>;
interrupt-controller;
#interrupt-cells = <2>;
};
gpio@c2f0000 {
compatible = "nvidia,tegra186-gpio-aon";
reg-names = "security", "gpio";
reg =
<0x0 0xc2f0000 0x0 0x1000>,
<0x0 0xc2f1000 0x0 0x1000>;
interrupts =
<0 60 IRQ_TYPE_LEVEL_HIGH>;
gpio-controller;
#gpio-cells = <2>;
interrupt-controller;
#interrupt-cells = <2>;
};

214
Documentation/devicetree/bindings/gpio/nvidia,tegra186-gpio.yaml Normal file
View File

@ -0,0 +1,214 @@
# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
%YAML 1.2
---
$id: http://devicetree.org/schemas/gpio/nvidia,tegra186-gpio.yaml#
$schema: http://devicetree.org/meta-schemas/core.yaml#
title: NVIDIA Tegra GPIO Controller (Tegra186 and later)
maintainers:
- Thierry Reding <thierry.reding@gmail.com>
- Jon Hunter <jonathanh@nvidia.com>
description: |
Tegra186 contains two GPIO controllers; a main controller and an "AON"
controller. This binding document applies to both controllers. The register
layouts for the controllers share many similarities, but also some
significant differences. Hence, this document describes closely related but
different bindings and compatible values.
The Tegra186 GPIO controller allows software to set the IO direction of,
and read/write the value of, numerous GPIO signals. Routing of GPIO signals
to package balls is under the control of a separate pin controller hardware
block. Two major sets of registers exist:
a) Security registers, which allow configuration of allowed access to the
GPIO register set. These registers exist in a single contiguous block
of physical address space. The size of this block, and the security
features available, varies between the different GPIO controllers.
Access to this set of registers is not necessary in all circumstances.
Code that wishes to configure access to the GPIO registers needs access
to these registers to do so. Code which simply wishes to read or write
GPIO data does not need access to these registers.
b) GPIO registers, which allow manipulation of the GPIO signals. In some
GPIO controllers, these registers are exposed via multiple "physical
aliases" in address space, each of which access the same underlying
state. See the hardware documentation for rationale. Any particular
GPIO client is expected to access just one of these physical aliases.
Tegra HW documentation describes a unified naming convention for all GPIOs
implemented by the SoC. Each GPIO is assigned to a port, and a port may
control a number of GPIOs. Thus, each GPIO is named according to an
alphabetical port name and an integer GPIO name within the port. For
example, GPIO_PA0, GPIO_PN6, or GPIO_PCC3.
The number of ports implemented by each GPIO controller varies. The number
of implemented GPIOs within each port varies. GPIO registers within a
controller are grouped and laid out according to the port they affect.
The mapping from port name to the GPIO controller that implements that
port, and the mapping from port name to register offset within a
controller, are both extremely non-linear. The header file
<dt-bindings/gpio/tegra186-gpio.h> describes the port-level mapping. In
that file, the naming convention for ports matches the HW documentation.
The values chosen for the names are alphabetically sorted within a
particular controller. Drivers need to map between the DT GPIO IDs and HW
register offsets using a lookup table.
Each GPIO controller can generate a number of interrupt signals. Each
signal represents the aggregate status for all GPIOs within a set of
ports. Thus, the number of interrupt signals generated by a controller
varies as a rough function of the number of ports it implements. Note
that the HW documentation refers to both the overall controller HW
module and the sets-of-ports as "controllers".
Each GPIO controller in fact generates multiple interrupts signals for
each set of ports. Each GPIO may be configured to feed into a specific
one of the interrupt signals generated by a set-of-ports. The intent is
for each generated signal to be routed to a different CPU, thus allowing
different CPUs to each handle subsets of the interrupts within a port.
The status of each of these per-port-set signals is reported via a
separate register. Thus, a driver needs to know which status register to
observe. This binding currently defines no configuration mechanism for
this. By default, drivers should use register
GPIO_${port}_INTERRUPT_STATUS_G1_0. Future revisions to the binding could
define a property to configure this.
properties:
compatible:
enum:
- nvidia,tegra186-gpio
- nvidia,tegra186-gpio-aon
- nvidia,tegra194-gpio
- nvidia,tegra194-gpio-aon
- nvidia,tegra234-gpio
- nvidia,tegra234-gpio-aon
reg-names:
items:
- const: security
- const: gpio
minItems: 1
reg:
items:
- description: Security configuration registers.
- description: |
GPIO control registers. This may cover either:
a) The single physical alias that this OS should use.
b) All physical aliases that exist in the controller. This is
appropriate when the OS is responsible for managing assignment
of the physical aliases.
minItems: 1
interrupts:
description: The interrupt outputs from the HW block, one per set of
ports, in the order the HW manual describes them. The number of entries
required varies depending on compatible value.
gpio-controller: true
"#gpio-cells":
description: |
Indicates how many cells are used in a consumer's GPIO specifier. In the
specifier:
- The first cell is the pin number.
See <dt-bindings/gpio/tegra186-gpio.h>.
- The second cell contains flags:
- Bit 0 specifies polarity
- 0: Active-high (normal).
- 1: Active-low (inverted).
const: 2
interrupt-controller: true
"#interrupt-cells":
description: |
Indicates how many cells are used in a consumer's interrupt specifier.
In the specifier:
- The first cell is the GPIO number.
See <dt-bindings/gpio/tegra186-gpio.h>.
- The second cell is contains flags:
- Bits [3:0] indicate trigger type and level:
- 1: Low-to-high edge triggered.
- 2: High-to-low edge triggered.
- 4: Active high level-sensitive.
- 8: Active low level-sensitive.
Valid combinations are 1, 2, 3, 4, 8.
const: 2
allOf:
- if:
properties:
compatible:
contains:
enum:
- nvidia,tegra186-gpio
- nvidia,tegra194-gpio
- nvidia,tegra234-gpio
then:
properties:
interrupts:
minItems: 6
maxItems: 48
- if:
properties:
compatible:
contains:
enum:
- nvidia,tegra186-gpio-aon
- nvidia,tegra194-gpio-aon
- nvidia,tegra234-gpio-aon
then:
properties:
interrupts:
minItems: 1
maxItems: 4
required:
- compatible
- reg
- reg-names
- interrupts
additionalProperties: false
examples:
- |
#include <dt-bindings/interrupt-controller/irq.h>
gpio@2200000 {
compatible = "nvidia,tegra186-gpio";
reg-names = "security", "gpio";
reg = <0x2200000 0x10000>,
<0x2210000 0x10000>;
interrupts = <0 47 IRQ_TYPE_LEVEL_HIGH>,
<0 50 IRQ_TYPE_LEVEL_HIGH>,
<0 53 IRQ_TYPE_LEVEL_HIGH>,
<0 56 IRQ_TYPE_LEVEL_HIGH>,
<0 59 IRQ_TYPE_LEVEL_HIGH>,
<0 180 IRQ_TYPE_LEVEL_HIGH>;
gpio-controller;
#gpio-cells = <2>;
interrupt-controller;
#interrupt-cells = <2>;
};
gpio@c2f0000 {
compatible = "nvidia,tegra186-gpio-aon";
reg-names = "security", "gpio";
reg = <0xc2f0000 0x1000>,
<0xc2f1000 0x1000>;
interrupts = <0 60 IRQ_TYPE_LEVEL_HIGH>;
gpio-controller;
#gpio-cells = <2>;
interrupt-controller;
#interrupt-cells = <2>;
};

40
Documentation/devicetree/bindings/gpio/nvidia,tegra20-gpio.txt
View File

@ -1,40 +0,0 @@
NVIDIA Tegra GPIO controller
Required properties:
- compatible : "nvidia,tegra<chip>-gpio"
- reg : Physical base address and length of the controller's registers.
- interrupts : The interrupt outputs from the controller. For Tegra20,
there should be 7 interrupts specified, and for Tegra30, there should
be 8 interrupts specified.
- #gpio-cells : Should be two. The first cell is the pin number and the
second cell is used to specify optional parameters:
- bit 0 specifies polarity (0 for normal, 1 for inverted)
- gpio-controller : Marks the device node as a GPIO controller.
- #interrupt-cells : Should be 2.
The first cell is the GPIO number.
The second cell is used to specify flags:
bits[3:0] trigger type and level flags:
1 = low-to-high edge triggered.
2 = high-to-low edge triggered.
4 = active high level-sensitive.
8 = active low level-sensitive.
Valid combinations are 1, 2, 3, 4, 8.
- interrupt-controller : Marks the device node as an interrupt controller.
Example:
gpio: gpio@6000d000 {
compatible = "nvidia,tegra20-gpio";
reg = < 0x6000d000 0x1000 >;
interrupts = < 0 32 0x04
0 33 0x04
0 34 0x04
0 35 0x04
0 55 0x04
0 87 0x04
0 89 0x04 >;
#gpio-cells = <2>;
gpio-controller;
#interrupt-cells = <2>;
interrupt-controller;
};

110
Documentation/devicetree/bindings/gpio/nvidia,tegra20-gpio.yaml Normal file
View File

@ -0,0 +1,110 @@
# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
%YAML 1.2
---
$id: http://devicetree.org/schemas/gpio/nvidia,tegra20-gpio.yaml#
$schema: http://devicetree.org/meta-schemas/core.yaml#
title: NVIDIA Tegra GPIO Controller (Tegra20 - Tegra210)
maintainers:
- Thierry Reding <thierry.reding@gmail.com>
- Jon Hunter <jonathanh@nvidia.com>
properties:
compatible:
oneOf:
- enum:
- nvidia,tegra20-gpio
- nvidia,tegra30-gpio
- items:
- enum:
- nvidia,tegra114-gpio
- nvidia,tegra124-gpio
- nvidia,tegra210-gpio
- const: nvidia,tegra30-gpio
reg:
maxItems: 1
interrupts:
description: The interrupt outputs from the controller. For Tegra20,
there should be 7 interrupts specified, and for Tegra30, there should
be 8 interrupts specified.
"#gpio-cells":
description: The first cell is the pin number and the second cell is used
to specify the GPIO polarity (0 = active high, 1 = active low).
const: 2
gpio-controller: true
gpio-ranges:
maxItems: 1
"#interrupt-cells":
description: |
Should be 2. The first cell is the GPIO number. The second cell is
used to specify flags:
bits[3:0] trigger type and level flags:
1 = low-to-high edge triggered.
2 = high-to-low edge triggered.
4 = active high level-sensitive.
8 = active low level-sensitive.
Valid combinations are 1, 2, 3, 4, 8.
const: 2
interrupt-controller: true
allOf:
- if:
properties:
compatible:
contains:
const: nvidia,tegra30-gpio
then:
properties:
interrupts:
minItems: 8
maxItems: 8
else:
properties:
interrupts:
minItems: 7
maxItems: 7
required:
- compatible
- reg
- interrupts
- "#gpio-cells"
- gpio-controller
- "#interrupt-cells"
- interrupt-controller
additionalProperties:
type: object
required:
- gpio-hog
examples:
- |
#include <dt-bindings/interrupt-controller/arm-gic.h>
gpio: gpio@6000d000 {
compatible = "nvidia,tegra20-gpio";
reg = <0x6000d000 0x1000>;
interrupts = <GIC_SPI 32 IRQ_TYPE_LEVEL_HIGH>,
<GIC_SPI 33 IRQ_TYPE_LEVEL_HIGH>,
<GIC_SPI 34 IRQ_TYPE_LEVEL_HIGH>,
<GIC_SPI 35 IRQ_TYPE_LEVEL_HIGH>,
<GIC_SPI 55 IRQ_TYPE_LEVEL_HIGH>,
<GIC_SPI 87 IRQ_TYPE_LEVEL_HIGH>,
<GIC_SPI 89 IRQ_TYPE_LEVEL_HIGH>;
#gpio-cells = <2>;
gpio-controller;
#interrupt-cells = <2>;
interrupt-controller;
};

3
Documentation/devicetree/bindings/gpio/sifive,gpio.yaml
View File

@ -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;

1
Documentation/devicetree/bindings/hwmon/ntc-thermistor.yaml
View File

@ -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

22
Documentation/devicetree/bindings/hwmon/ti,ina2xx.yaml
View File

@ -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

2
Documentation/devicetree/bindings/input/hid-over-i2c.txt
View File

@ -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:

23
Documentation/devicetree/bindings/memory-controllers/ti,gpmc.yaml
View File

@ -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:

69
Documentation/devicetree/bindings/mfd/bd9571mwv.txt
View File

@ -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;
};
};
};

61
Documentation/devicetree/bindings/mfd/brcm,twd.yaml Normal file
View File

@ -0,0 +1,61 @@
# SPDX-License-Identifier: GPL-2.0-only OR BSD-2-Clause
%YAML 1.2
---
$id: http://devicetree.org/schemas/mfd/brcm,twd.yaml#
$schema: http://devicetree.org/meta-schemas/core.yaml#
title: Broadcom's Timer-Watchdog (aka TWD)
maintainers:
- Rafał Miłecki <rafal@milecki.pl>
description: |
Broadcom has a Timer-Watchdog block used in multiple SoCs (e.g., BCM4908,
BCM63xx, BCM7038). There are few variants available (they differ slightly in
registers layout). This block consists of: timers, watchdog and optionally a
software reset handler.
properties:
compatible:
items:
- enum:
- brcm,bcm4908-twd
- brcm,bcm7038-twd
- const: simple-mfd
- const: syscon
reg:
maxItems: 1
ranges: true
"#address-cells":
const: 1
"#size-cells":
const: 1
patternProperties:
'^watchdog@[a-f0-9]+$':
$ref: /schemas/watchdog/brcm,bcm7038-wdt.yaml
additionalProperties: false
required:
- reg
examples:
- |
timer-mfd@ff800400 {
compatible = "brcm,bcm4908-twd", "simple-mfd", "syscon";
reg = <0xff800400 0x4c>;
ranges = <0x00000000 0xff800400 0x4c>;
#address-cells = <1>;
#size-cells = <1>;
watchdog@28 {
compatible = "brcm,bcm7038-wdt";
reg = <0x28 0x8>;
};
};

2
Documentation/devicetree/bindings/mfd/da9063.txt
View File

@ -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
------ ------------ -----------

2
Documentation/devicetree/bindings/mfd/google,cros-ec.yaml
View File

@ -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

26
Documentation/devicetree/bindings/mfd/max77686.txt
View File

@ -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>;
};

132
Documentation/devicetree/bindings/mfd/maxim,max77686.yaml Normal file
View File

@ -0,0 +1,132 @@
# SPDX-License-Identifier: GPL-2.0-only OR BSD-2-Clause
%YAML 1.2
---
$id: http://devicetree.org/schemas/mfd/maxim,max77686.yaml#
$schema: http://devicetree.org/meta-schemas/core.yaml#
title: Maxim MAX77686 Power Management IC
maintainers:
- Chanwoo Choi <cw00.choi@samsung.com>
- Krzysztof Kozlowski <krzysztof.kozlowski@canonical.com>
description: |
This is a part of device tree bindings for Maxim MAX77686 Power Management
Integrated Circuit (PMIC).
The Maxim MAX77686 is a Power Management IC which includes voltage and
current regulators, RTC and clock outputs.
The MAX77686 provides three 32.768khz clock outputs that can be controlled
(gated/ungated) over I2C. The clock IDs are defined as preprocessor macros
in dt-bindings/clock/maxim,max77686.h.
properties:
compatible:
const: maxim,max77686
'#clock-cells':
const: 1
interrupts:
maxItems: 1
reg:
maxItems: 1
voltage-regulators:
$ref: ../regulator/maxim,max77686.yaml
description:
List of child nodes that specify the regulators.
wakeup-source: true
required:
- compatible
- '#clock-cells'
- reg
additionalProperties: false
examples:
- |
#include <dt-bindings/gpio/gpio.h>
#include <dt-bindings/interrupt-controller/irq.h>
i2c {
#address-cells = <1>;
#size-cells = <0>;
max77686: pmic@9 {
compatible = "maxim,max77686";
reg = <0x09>;
interrupt-parent = <&gpx0>;
interrupts = <7 IRQ_TYPE_LEVEL_LOW>;
pinctrl-0 = <&max77686_irq>;
pinctrl-names = "default";
wakeup-source;
#clock-cells = <1>;
voltage-regulators {
LDO1 {
regulator-name = "VALIVE_1.0V_AP";
regulator-min-microvolt = <1000000>;
regulator-max-microvolt = <1000000>;
regulator-always-on;
};
LDO2 {
regulator-name = "VM1M2_1.2V_AP";
regulator-min-microvolt = <1200000>;
regulator-max-microvolt = <1200000>;
regulator-always-on;
regulator-state-mem {
regulator-on-in-suspend;
};
};
// ...
LDO22 {
regulator-name = "VMEM_VDD_2.8V";
regulator-min-microvolt = <2800000>;
regulator-max-microvolt = <2800000>;
maxim,ena-gpios = <&gpk0 2 GPIO_ACTIVE_HIGH>;
};
// ...
BUCK1 {
regulator-name = "VDD_MIF";
regulator-min-microvolt = <850000>;
regulator-max-microvolt = <1100000>;
regulator-always-on;
regulator-boot-on;
regulator-state-mem {
regulator-off-in-suspend;
};
};
BUCK2 {
regulator-name = "VDD_ARM";
regulator-min-microvolt = <850000>;
regulator-max-microvolt = <1500000>;
regulator-always-on;
regulator-boot-on;
regulator-state-mem {
regulator-on-in-suspend;
};
};
// ...
BUCK9 {
regulator-name = "CAM_ISP_CORE_1.2V";
regulator-min-microvolt = <1000000>;
regulator-max-microvolt = <1200000>;
maxim,ena-gpios = <&gpm0 3 GPIO_ACTIVE_HIGH>;
};
};
};
};

102
Documentation/devicetree/bindings/mfd/rohm,bd70528-pmic.txt
View File

@ -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>;
};
};
};

127
Documentation/devicetree/bindings/mfd/rohm,bd9571mwv.yaml Normal file
View File

@ -0,0 +1,127 @@
# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
%YAML 1.2
---
$id: http://devicetree.org/schemas/mfd/rohm,bd9571mwv.yaml#
$schema: http://devicetree.org/meta-schemas/core.yaml#
title: ROHM BD9571MWV/BD9574MWF Power Management Integrated Circuit (PMIC)
maintainers:
- Marek Vasut <marek.vasut@gmail.com>
properties:
compatible:
enum:
- rohm,bd9571mwv
- rohm,bd9574mwf
reg:
maxItems: 1
interrupts:
maxItems: 1
interrupt-controller: true
'#interrupt-cells':
const: 2
gpio-controller: true
'#gpio-cells':
const: 2
rohm,ddr-backup-power:
$ref: /schemas/types.yaml#/definitions/uint32
minimum: 0x0
maximum: 0xf
description: |
Value to use for DDR-Backup Power (default 0).
This is a bitmask that specifies which DDR power rails need to be kept
powered when backup mode is entered, for system suspend:
- bit 0: DDR0
- bit 1: DDR1
- bit 2: DDR0C
- bit 3: DDR1C
These bits match the KEEPON_DDR* bits in the documentation for the "BKUP
Mode Cnt" register.
rohm,rstbmode-level:
$ref: /schemas/types.yaml#/definitions/flag
description:
The RSTB signal is configured for level mode, to accommodate a toggle
power switch (the RSTBMODE pin is strapped low).
rohm,rstbmode-pulse:
$ref: /schemas/types.yaml#/definitions/flag
description:
The RSTB signal is configured for pulse mode, to accommodate a momentary
power switch (the RSTBMODE pin is strapped high).
regulators:
type: object
description:
List of child nodes that specify the regulator initialization data.
Child nodes must be named after their hardware counterparts.
patternProperties:
"^(vd09|vd18|vd25|vd33|dvfs)$":
type: object
$ref: ../regulator/regulator.yaml#
properties:
regulator-name:
pattern: "^(vd09|vd18|vd25|vd33|dvfs)$"
unevaluatedProperties: false
additionalProperties: false
additionalProperties: false
required:
- compatible
- reg
- interrupts
- interrupt-controller
- '#interrupt-cells'
- gpio-controller
- '#gpio-cells'
oneOf:
- required:
- rohm,rstbmode-level
- required:
- rohm,rstbmode-pulse
examples:
- |
#include <dt-bindings/interrupt-controller/irq.h>
i2c {
#address-cells = <1>;
#size-cells = <0>;
pmic: pmic@30 {
compatible = "rohm,bd9571mwv";
reg = <0x30>;
interrupt-parent = <&gpio2>;
interrupts = <0 IRQ_TYPE_LEVEL_LOW>;
interrupt-controller;
#interrupt-cells = <2>;
gpio-controller;
#gpio-cells = <2>;
rohm,ddr-backup-power = <0xf>;
rohm,rstbmode-pulse;
regulators {
dvfs: dvfs {
regulator-name = "dvfs";
regulator-min-microvolt = <750000>;
regulator-max-microvolt = <1030000>;
regulator-boot-on;
regulator-always-on;
};
};
};
};

2
Documentation/devicetree/bindings/mfd/syscon.yaml
View File

@ -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

3
Documentation/devicetree/bindings/mmc/arasan,sdhci.yaml
View File

@ -118,6 +118,9 @@ properties:
phy-names:
const: phy_arasan
resets:
maxItems: 1
arasan,soc-ctl-syscon:
$ref: /schemas/types.yaml#/definitions/phandle
description:

19
Documentation/devicetree/bindings/mmc/arm,pl18x.yaml
View File

@ -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>;

53
Documentation/devicetree/bindings/mmc/brcm,sdhci-brcmstb.txt
View File

@ -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";
};

100
Documentation/devicetree/bindings/mmc/brcm,sdhci-brcmstb.yaml Normal file
View File

@ -0,0 +1,100 @@
# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
%YAML 1.2
---
$id: http://devicetree.org/schemas/mmc/brcm,sdhci-brcmstb.yaml#
$schema: http://devicetree.org/meta-schemas/core.yaml#
title: Broadcom BRCMSTB/BMIPS SDHCI Controller binding
maintainers:
- Al Cooper <alcooperx@gmail.com>
- Florian Fainelli <f.fainelli@gmail.com>
allOf:
- $ref: mmc-controller.yaml#
properties:
compatible:
oneOf:
- items:
- enum:
- brcm,bcm7216-sdhci
- const: brcm,bcm7445-sdhci
- const: brcm,sdhci-brcmstb
- items:
- enum:
- brcm,bcm7445-sdhci
- const: brcm,sdhci-brcmstb
- items:
- enum:
- brcm,bcm7425-sdhci
- const: brcm,sdhci-brcmstb
reg:
minItems: 2
reg-names:
items:
- const: host
- const: cfg
interrupts:
maxItems: 1
clocks:
maxItems: 1
description:
handle to core clock for the sdhci controller.
clock-names:
items:
- const: sw_sdio
sdhci,auto-cmd12:
type: boolean
description: Specifies that controller should use auto CMD12
required:
- compatible
- reg
- interrupts
- clocks
unevaluatedProperties: false
examples:
- |
mmc@84b0000 {
sd-uhs-sdr50;
sd-uhs-ddr50;
sd-uhs-sdr104;
sdhci,auto-cmd12;
compatible = "brcm,bcm7216-sdhci",
"brcm,bcm7445-sdhci",
"brcm,sdhci-brcmstb";
reg = <0x84b0000 0x260>, <0x84b0300 0x200>;
reg-names = "host", "cfg";
interrupts = <0x0 0x26 0x4>;
interrupt-names = "sdio0_0";
clocks = <&scmi_clk 245>;
clock-names = "sw_sdio";
};
mmc@84b1000 {
mmc-ddr-1_8v;
mmc-hs200-1_8v;
mmc-hs400-1_8v;
mmc-hs400-enhanced-strobe;
supports-cqe;
non-removable;
bus-width = <0x8>;
compatible = "brcm,bcm7216-sdhci",
"brcm,bcm7445-sdhci",
"brcm,sdhci-brcmstb";
reg = <0x84b1000 0x260>, <0x84b1300 0x200>;
reg-names = "host", "cfg";
interrupts = <0x0 0x27 0x4>;
interrupt-names = "sdio1_0";
clocks = <&scmi_clk 245>;
clock-names = "sw_sdio";
};

2
Documentation/devicetree/bindings/mmc/exynos-dw-mshc.txt
View File

@ -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

8
Documentation/devicetree/bindings/mmc/fsl-imx-esdhc.yaml
View File

@ -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

28
Documentation/devicetree/bindings/mmc/img-dw-mshc.txt
View File

@ -1,28 +0,0 @@
* Imagination specific extensions to the Synopsys Designware Mobile Storage
Host Controller
The Synopsys designware mobile storage host controller is used to interface
a SoC with storage medium such as eMMC or SD/MMC cards. This file documents
differences between the core Synopsys dw mshc controller properties described
by synopsys-dw-mshc.txt and the properties used by the Imagination specific
extensions to the Synopsys Designware Mobile Storage Host Controller.
Required Properties:
* compatible: should be
- "img,pistachio-dw-mshc": for Pistachio SoCs
Example:
mmc@18142000 {
compatible = "img,pistachio-dw-mshc";
reg = <0x18142000 0x400>;
interrupts = <GIC_SHARED 39 IRQ_TYPE_LEVEL_HIGH>;
clocks = <&system_clk>, <&sdhost_clk>;
clock-names = "biu", "ciu";
fifo-depth = <0x20>;
bus-width = <4>;
disable-wp;
};

37
Documentation/devicetree/bindings/mmc/ingenic,mmc.yaml
View File

@ -39,14 +39,15 @@ properties:
const: mmc
dmas:
items:
- description: DMA controller phandle and request line for RX
- description: DMA controller phandle and request line for TX
minItems: 1
maxItems: 2
dma-names:
items:
- const: rx
- const: tx
oneOf:
- items:
- const: rx
- const: tx
- const: tx-rx
required:
- compatible
@ -80,3 +81,27 @@ examples:
<&dma JZ4780_DMA_MSC0_TX 0xffffffff>;
dma-names = "rx", "tx";
};
- |
#include <dt-bindings/clock/ingenic,jz4780-cgu.h>
#include <dt-bindings/dma/jz4780-dma.h>
/*
* Alternative version of the example above,
* but using one single DMA channel for both
* TX and RX.
*/
mmc1: mmc@13460000 {
compatible = "ingenic,jz4780-mmc";
reg = <0x13460000 0x1000>;
interrupt-parent = <&intc>;
interrupts = <36>;
clocks = <&cgu JZ4780_CLK_MSC1>;
clock-names = "mmc";
cap-sd-highspeed;
cap-mmc-highspeed;
cap-sdio-irq;
dmas = <&dma JZ4780_DMA_MSC1_TX JZ4780_DMA_MSC1_RX 0xffffffff>;
dma-names = "tx-rx";
};

6
Documentation/devicetree/bindings/mmc/mtk-sd.yaml
View File

@ -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

2
Documentation/devicetree/bindings/mmc/sdhci-am654.yaml
View File

@ -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

1
Documentation/devicetree/bindings/mmc/sdhci-msm.txt
View File

@ -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";

23
Documentation/devicetree/bindings/mmc/socfpga-dw-mshc.txt
View File

@ -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>;
};

6
Documentation/devicetree/bindings/mmc/socionext,uniphier-sd.yaml
View File

@ -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

5
Documentation/devicetree/bindings/mmc/synopsys-dw-mshc.yaml
View File

@ -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

3
Documentation/devicetree/bindings/mtd/jedec,spi-nor.yaml
View File

@ -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:
- |

61
Documentation/devicetree/bindings/mtd/renesas-nandc.yaml Normal file
View File

@ -0,0 +1,61 @@
# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
%YAML 1.2
---
$id: http://devicetree.org/schemas/mtd/renesas-nandc.yaml#
$schema: http://devicetree.org/meta-schemas/core.yaml#
title: Renesas R-Car Gen3 & RZ/N1x NAND flash controller device tree bindings
maintainers:
- Miquel Raynal <miquel.raynal@bootlin.com>
allOf:
- $ref: "nand-controller.yaml"
properties:
compatible:
oneOf:
- items:
- enum:
- renesas,r9a06g032-nandc
- const: renesas,rzn1-nandc
reg:
maxItems: 1
interrupts:
maxItems: 1
clocks:
items:
- description: APB host controller clock
- description: External NAND bus clock
clock-names:
items:
- const: hclk
- const: eclk
required:
- compatible
- reg
- clocks
- clock-names
- interrupts
unevaluatedProperties: false
examples:
- |
#include <dt-bindings/interrupt-controller/arm-gic.h>
#include <dt-bindings/clock/r9a06g032-sysctrl.h>
nand-controller@40102000 {
compatible = "renesas,r9a06g032-nandc", "renesas,rzn1-nandc";
reg = <0x40102000 0x2000>;
interrupts = <GIC_SPI 58 IRQ_TYPE_LEVEL_HIGH>;
clocks = <&sysctrl R9A06G032_HCLK_NAND>, <&sysctrl R9A06G032_CLK_NAND>;
clock-names = "hclk", "eclk";
#address-cells = <1>;
#size-cells = <0>;
};

10
Documentation/devicetree/bindings/mtd/ti,gpmc-nand.yaml
View File

@ -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"

41
Documentation/devicetree/bindings/power/reset/gpio-poweroff.txt
View File

@ -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>;
};

59
Documentation/devicetree/bindings/power/reset/gpio-poweroff.yaml Normal file
View File

@ -0,0 +1,59 @@
# SPDX-License-Identifier: (GPL-2.0-only or BSD-2-Clause)
%YAML 1.2
---
$id: http://devicetree.org/schemas/power/reset/gpio-poweroff.yaml#
$schema: http://devicetree.org/meta-schemas/core.yaml#
title: GPIO controlled power off
maintainers:
- Sebastian Reichel <sre@kernel.org>
description: >
System power off support via a GPIO line. When a shutdown is
executed the operating system is expected to switch the GPIO
from inactive to active. After a delay (active-delay-ms) it
is expected to be switched back to inactive. After another
delay (inactive-delay-ms) it is configured as active again.
Finally the operating system assumes the power off failed if
the system is still running after waiting some time (timeout-ms).
properties:
compatible:
const: gpio-poweroff
gpios:
maxItems: 1
input:
type: boolean
description: >
Initially configure the GPIO line as an input. Only reconfigure
it to an output when the power-off sequence is initiated. If this optional
property is not specified, the GPIO is initialized as an output in its inactive state.
active-delay-ms:
default: 100
description: Delay to wait after driving gpio active
inactive-delay-ms:
default: 100
description: Delay to wait after driving gpio inactive
timeout-ms:
default: 3000
description: Time to wait before assuming the power off sequence failed.
required:
- compatible
- gpios
additionalProperties: false
examples:
- |
gpio-poweroff {
compatible = "gpio-poweroff";
gpios = <&gpio 4 0>;
timeout-ms = <3000>;
};

44
Documentation/devicetree/bindings/power/supply/maxim,max77976.yaml Normal file
View File

@ -0,0 +1,44 @@
# SPDX-License-Identifier: (GPL-2.0 OR BSD-2-Clause)
%YAML 1.2
---
$id: http://devicetree.org/schemas/power/supply/maxim,max77976.yaml#
$schema: http://devicetree.org/meta-schemas/core.yaml#
title: Maxim Integrated MAX77976 Battery charger
maintainers:
- Luca Ceresoli <luca@lucaceresoli.net>
description: |
The Maxim MAX77976 is a 19Vin / 5.5A, 1-Cell Li+ battery charger
configured via I2C.
allOf:
- $ref: power-supply.yaml#
properties:
compatible:
const: maxim,max77976
reg:
maxItems: 1
required:
- compatible
- reg
unevaluatedProperties: false
examples:
- |
i2c {
#address-cells = <1>;
#size-cells = <0>;
charger@6b {
compatible = "maxim,max77976";
reg = <0x6b>;
};
};
...

4
Documentation/devicetree/bindings/power/supply/qcom,pm8941-charger.yaml
View File

@ -11,7 +11,9 @@ maintainers:
properties:
compatible:
const: qcom,pm8941-charger
enum:
- qcom,pm8226-charger
- qcom,pm8941-charger
reg:
maxItems: 1

70
Documentation/devicetree/bindings/regulator/dlg,da9121.yaml
View File

@ -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)

71
Documentation/devicetree/bindings/regulator/max77686.txt
View File

@ -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>;
};
};

106
Documentation/devicetree/bindings/regulator/maxim,max20086.yaml Normal file
View File

@ -0,0 +1,106 @@
# SPDX-License-Identifier: (GPL-2.0 OR BSD-2-Clause)
%YAML 1.2
---
$id: http://devicetree.org/schemas/regulator/maxim,max20086.yaml#
$schema: http://devicetree.org/meta-schemas/core.yaml#
title: Maxim Integrated MAX20086-MAX20089 Camera Power Protector
maintainers:
- Laurent Pinchart <laurent.pinchart@ideasonboard.com>
description: |
The MAX20086-MAX20089 are dual/quad camera power protectors, designed to
deliver power over coax for radar and camera modules. They support
software-configurable output switching and monitoring. The output voltage and
current limit are fixed by the hardware design.
properties:
compatible:
enum:
- maxim,max20086
- maxim,max20087
- maxim,max20088
- maxim,max20089
reg:
maxItems: 1
enable-gpios:
maxItems: 1
description: GPIO connected to the EN pin, active high
in-supply:
description: Input supply for the camera outputs (IN pin, 3.0V to 15.0V)
vdd-supply:
description: Input supply for the device (VDD pin, 3.0V to 5.5V)
regulators:
type: object
patternProperties:
"^OUT[1-4]$":
type: object
$ref: regulator.yaml#
additionalProperties: false
required:
- compatible
- reg
- in-supply
- vdd-supply
- regulators
allOf:
- if:
properties:
compatible:
contains:
enum:
- maxim,max20088
- maxim,max20089
then:
properties:
regulators:
properties:
OUT3: false
OUT4: false
additionalProperties: false
examples:
- |
#include <dt-bindings/gpio/gpio.h>
i2c {
#address-cells = <1>;
#size-cells = <0>;
regulator@28 {
compatible = "maxim,max20087";
reg = <0x28>;
in-supply = <&reg_12v0>;
vdd-supply = <&reg_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";
};
};
};
};
...

83
Documentation/devicetree/bindings/regulator/maxim,max77686.yaml Normal file
View File

@ -0,0 +1,83 @@
# SPDX-License-Identifier: GPL-2.0-only OR BSD-2-Clause
%YAML 1.2
---
$id: http://devicetree.org/schemas/regulator/maxim,max77686.yaml#
$schema: http://devicetree.org/meta-schemas/core.yaml#
title: Maxim MAX77686 Power Management IC regulators
maintainers:
- Chanwoo Choi <cw00.choi@samsung.com>
- Krzysztof Kozlowski <krzysztof.kozlowski@canonical.com>
description: |
This is a part of device tree bindings for Maxim MAX77686 Power Management
Integrated Circuit (PMIC).
The Maxim MAX77686 provides high-efficiency Buck and 26 Low-DropOut (LDO)
regulators.
See also Documentation/devicetree/bindings/mfd/maxim,max77686.yaml for
additional information and example.
patternProperties:
# 26 LDOs
"^LDO([1-9]|1[0-9]|2[3-6])$":
type: object
$ref: regulator.yaml#
unevaluatedProperties: false
description: |
Properties for single LDO regulator.
Regulators which can be turned off during system suspend:
LDO2, LDO6-8, LDO10-12, LDO14-16
required:
- regulator-name
# LDO20-LDO22 with maxim,ena-gpios
"^LDO2[0-2]$":
type: object
$ref: regulator.yaml#
unevaluatedProperties: false
description: |
Properties for single LDO regulator.
properties:
maxim,ena-gpios:
maxItems: 1
description: |
GPIO specifier to enable the GPIO control (on/off) for regulator.
required:
- regulator-name
# 9 bucks
"^BUCK[1-7]$":
type: object
$ref: regulator.yaml#
unevaluatedProperties: false
description: |
Properties for single BUCK regulator.
Regulators which can be turned off during system suspend:
BUCK[1-4]
required:
- regulator-name
"^BUCK[89]$":
type: object
$ref: regulator.yaml#
unevaluatedProperties: false
description: |
Properties for single BUCK regulator.
properties:
maxim,ena-gpios:
maxItems: 1
description: |
GPIO specifier to enable the GPIO control (on/off) for regulator.
required:
- regulator-name
additionalProperties: false

3
Documentation/devicetree/bindings/regulator/maxim,max8973.yaml
View File

@ -86,6 +86,9 @@ properties:
reg:
maxItems: 1
interrupts:
maxItems: 1
required:
- compatible
- reg

3
Documentation/devicetree/bindings/regulator/qcom,rpmh-regulator.yaml
View File

@ -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

1
Documentation/devicetree/bindings/regulator/qcom,spmi-regulator.txt
View File

@ -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"

2
Documentation/devicetree/bindings/regulator/regulator.yaml
View File

@ -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

68
Documentation/devicetree/bindings/regulator/rohm,bd70528-regulator.txt
View File

@ -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>;
};
};

3
Documentation/devicetree/bindings/regulator/samsung,s5m8767.yaml
View File

@ -67,8 +67,9 @@ patternProperties:
required:
- regulator-name
properties:
# 9 buck
"^BUCK9$":
BUCK9:
type: object
$ref: regulator.yaml#
unevaluatedProperties: false

99
Documentation/devicetree/bindings/spi/atmel,quadspi.yaml Normal file
View File

@ -0,0 +1,99 @@
# SPDX-License-Identifier: GPL-2.0-only OR BSD-2-Clause
%YAML 1.2
---
$id: http://devicetree.org/schemas/spi/atmel,quadspi.yaml#
$schema: http://devicetree.org/meta-schemas/core.yaml#
title: Atmel Quad Serial Peripheral Interface (QSPI)
maintainers:
- Tudor Ambarus <tudor.ambarus@microchip.com>
allOf:
- $ref: spi-controller.yaml#
properties:
compatible:
enum:
- atmel,sama5d2-qspi
- microchip,sam9x60-qspi
- microchip,sama7g5-qspi
- microchip,sama7g5-ospi
reg:
items:
- description: base registers
- description: mapped memory
reg-names:
items:
- const: qspi_base
- const: qspi_mmap
clocks:
minItems: 1
items:
- description: peripheral clock
- description: system clock or generic clock, if available
clock-names:
minItems: 1
items:
- const: pclk
- enum: [ qspick, gclk ]
interrupts:
maxItems: 1
dmas:
items:
- description: tx DMA channel
- description: rx DMA channel
dma-names:
items:
- const: tx
- const: rx
'#address-cells':
const: 1
'#size-cells':
const: 0
required:
- compatible
- reg
- reg-names
- interrupts
- clocks
- clock-names
- '#address-cells'
- '#size-cells'
unevaluatedProperties: false
examples:
- |
#include <dt-bindings/interrupt-controller/irq.h>
#include <dt-bindings/clock/at91.h>
spi@f0020000 {
compatible = "atmel,sama5d2-qspi";
reg = <0xf0020000 0x100>, <0xd0000000 0x8000000>;
reg-names = "qspi_base", "qspi_mmap";
interrupts = <52 IRQ_TYPE_LEVEL_HIGH 7>;
clocks = <&pmc PMC_TYPE_PERIPHERAL 52>;
clock-names = "pclk";
#address-cells = <1>;
#size-cells = <0>;
pinctrl-names = "default";
pinctrl-0 = <&pinctrl_spi0_default>;
flash@0 {
compatible = "jedec,spi-nor";
spi-max-frequency = <50000000>;
reg = <0>;
spi-rx-bus-width = <4>;
spi-tx-bus-width = <4>;
};
};

37
Documentation/devicetree/bindings/spi/atmel-quadspi.txt
View File

@ -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 {
...
};
};

42
Documentation/devicetree/bindings/spi/cdns,qspi-nor-peripheral-props.yaml Normal file
View File

@ -0,0 +1,42 @@
# SPDX-License-Identifier: (GPL-2.0 OR BSD-2-Clause)
%YAML 1.2
---
$id: http://devicetree.org/schemas/spi/cdns,qspi-nor-peripheral-props.yaml#
$schema: http://devicetree.org/meta-schemas/core.yaml#
title: Peripheral-specific properties for the Cadence QSPI controller.
description:
See spi-peripheral-props.yaml for more info.
maintainers:
- Pratyush Yadav <p.yadav@ti.com>
properties:
# cdns,qspi-nor.yaml
cdns,read-delay:
$ref: /schemas/types.yaml#/definitions/uint32
description:
Delay for read capture logic, in clock cycles.
cdns,tshsl-ns:
description:
Delay in nanoseconds for the length that the master mode chip select
outputs are de-asserted between transactions.
cdns,tsd2d-ns:
description:
Delay in nanoseconds between one chip select being de-activated
and the activation of another.
cdns,tchsh-ns:
description:
Delay in nanoseconds between last bit of current transaction and
deasserting the device chip select (qspi_n_ss_out).
cdns,tslch-ns:
description:
Delay in nanoseconds between setting qspi_n_ss_out low and
first bit transfer.
additionalProperties: true

33
Documentation/devicetree/bindings/spi/cdns,qspi-nor.yaml
View File

@ -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

8
Documentation/devicetree/bindings/spi/mediatek,spi-mtk-nor.yaml
View File

@ -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:
};
};
};

4
Documentation/devicetree/bindings/spi/renesas,rspi.yaml
View File

@ -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

69
Documentation/devicetree/bindings/spi/spi-controller.yaml
View File

@ -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

11
Documentation/devicetree/bindings/spi/spi-fsl-lpspi.yaml
View File

@ -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

1
Documentation/devicetree/bindings/spi/spi-mux.yaml
View File

@ -31,6 +31,7 @@ description: |
allOf:
- $ref: "/schemas/spi/spi-controller.yaml#"
- $ref: "/schemas/spi/spi-peripheral-props.yaml#"
maintainers:
- Chris Packham <chris.packham@alliedtelesis.co.nz>

89
Documentation/devicetree/bindings/spi/spi-peripheral-props.yaml Normal file
View File

@ -0,0 +1,89 @@
# SPDX-License-Identifier: (GPL-2.0 OR BSD-2-Clause)
%YAML 1.2
---
$id: http://devicetree.org/schemas/spi/spi-peripheral-props.yaml#
$schema: http://devicetree.org/meta-schemas/core.yaml#
title: Peripheral-specific properties for a SPI bus.
description:
Many SPI controllers need to add properties to peripheral devices. They could
be common properties like spi-max-frequency, spi-cpha, etc. or they could be
controller specific like delay in clock or data lines, etc. These properties
need to be defined in the peripheral node because they are per-peripheral and
there can be multiple peripherals attached to a controller. All those
properties are listed here. The controller specific properties should go in
their own separate schema that should be referenced from here.
maintainers:
- Pratyush Yadav <p.yadav@ti.com>
properties:
reg:
minItems: 1
maxItems: 256
items:
minimum: 0
maximum: 256
description:
Chip select used by the device.
spi-3wire:
$ref: /schemas/types.yaml#/definitions/flag
description:
The device requires 3-wire mode.
spi-cpha:
$ref: /schemas/types.yaml#/definitions/flag
description:
The device requires shifted clock phase (CPHA) mode.
spi-cpol:
$ref: /schemas/types.yaml#/definitions/flag
description:
The device requires inverse clock polarity (CPOL) mode.
spi-cs-high:
$ref: /schemas/types.yaml#/definitions/flag
description:
The device requires the chip select active high.
spi-lsb-first:
$ref: /schemas/types.yaml#/definitions/flag
description:
The device requires the LSB first mode.
spi-max-frequency:
$ref: /schemas/types.yaml#/definitions/uint32
description:
Maximum SPI clocking speed of the device in Hz.
spi-rx-bus-width:
description:
Bus width to the SPI bus used for read transfers.
If 0 is provided, then no RX will be possible on this device.
$ref: /schemas/types.yaml#/definitions/uint32
enum: [0, 1, 2, 4, 8]
default: 1
spi-rx-delay-us:
description:
Delay, in microseconds, after a read transfer.
spi-tx-bus-width:
description:
Bus width to the SPI bus used for write transfers.
If 0 is provided, then no TX will be possible on this device.
$ref: /schemas/types.yaml#/definitions/uint32
enum: [0, 1, 2, 4, 8]
default: 1
spi-tx-delay-us:
description:
Delay, in microseconds, after a write transfer.
# The controller specific properties go here.
allOf:
- $ref: cdns,qspi-nor-peripheral-props.yaml#
additionalProperties: true

3
Documentation/devicetree/bindings/spi/spi-pl022.yaml
View File

@ -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

8
Documentation/devicetree/bindings/trivial-devices.yaml
View File

@ -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)

22
Documentation/doc-guide/sphinx.rst
View File

@ -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:

2
Documentation/features/core/thread-info-in-task/arch-support.txt
View File

@ -8,7 +8,7 @@
-----------------------
| alpha: | TODO |
| arc: | TODO |
| arm: | TODO |
| arm: | ok |
| arm64: | ok |
| csky: | TODO |
| h8300: | TODO |

8
Documentation/filesystems/erofs.rst
View File

@ -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
===============

72
Documentation/filesystems/idmappings.rst
View File

@ -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.

5
Documentation/filesystems/locking.rst
View File

@ -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
================

38
Documentation/hwmon/asus_wmi_ec_sensors.rst Normal file
View File

@ -0,0 +1,38 @@
.. SPDX-License-Identifier: GPL-2.0-or-later
Kernel driver asus_wmi_ec_sensors
=================================
Supported boards:
* PRIME X570-PRO,
* Pro WS X570-ACE,
* ROG CROSSHAIR VIII DARK HERO,
* ROG CROSSHAIR VIII FORMULA,
* ROG CROSSHAIR VIII HERO,
* ROG STRIX B550-E GAMING,
* ROG STRIX B550-I GAMING,
* ROG STRIX X570-E GAMING.
Authors:
- Eugene Shalygin <eugene.shalygin@gmail.com>
Description:
------------
ASUS mainboards publish hardware monitoring information via Super I/O
chip and the ACPI embedded controller (EC) registers. Some of the sensors
are only available via the EC.
ASUS WMI interface provides a method (BREC) to read data from EC registers,
which is utilized by this driver to publish those sensor readings to the
HWMON system. The driver is aware of and reads the following sensors:
1. Chipset (PCH) temperature
2. CPU package temperature
3. Motherboard temperature
4. Readings from the T_Sensor header
5. VRM temperature
6. CPU_Opt fan RPM
7. Chipset fan RPM
8. Readings from the "Water flow meter" header (RPM)
9. Readings from the "Water In" and "Water Out" temperature headers
10. CPU current

78
Documentation/hwmon/asus_wmi_sensors.rst Normal file
View File

@ -0,0 +1,78 @@
.. SPDX-License-Identifier: GPL-2.0-or-later
Kernel driver asus_wmi_sensors
=================================
Supported boards:
* PRIME X399-A,
* PRIME X470-PRO,
* ROG CROSSHAIR VI EXTREME,
* ROG CROSSHAIR VI HERO,
* ROG CROSSHAIR VI HERO (WI-FI AC),
* ROG CROSSHAIR VII HERO,
* ROG CROSSHAIR VII HERO (WI-FI),
* ROG STRIX B450-E GAMING,
* ROG STRIX B450-F GAMING,
* ROG STRIX B450-I GAMING,
* ROG STRIX X399-E GAMING,
* ROG STRIX X470-F GAMING,
* ROG STRIX X470-I GAMING,
* ROG ZENITH EXTREME,
* ROG ZENITH EXTREME ALPHA.
Authors:
- Ed Brindley <kernel@maidavale.org>
Description:
------------
ASUS mainboards publish hardware monitoring information via WMI interface.
ASUS WMI interface provides a methods to get list of sensors and values of
such, which is utilized by this driver to publish those sensor readings to the
HWMON system.
The driver is aware of and reads the following sensors:
* CPU Core Voltage,
* CPU SOC Voltage,
* DRAM Voltage,
* VDDP Voltage,
* 1.8V PLL Voltage,
* +12V Voltage,
* +5V Voltage,
* 3VSB Voltage,
* VBAT Voltage,
* AVCC3 Voltage,
* SB 1.05V Voltage,
* CPU Core Voltage,
* CPU SOC Voltage,
* DRAM Voltage,
* CPU Fan RPM,
* Chassis Fan 1 RPM,
* Chassis Fan 2 RPM,
* Chassis Fan 3 RPM,
* HAMP Fan RPM,
* Water Pump RPM,
* CPU OPT RPM,
* Water Flow RPM,
* AIO Pump RPM,
* CPU Temperature,
* CPU Socket Temperature,
* Motherboard Temperature,
* Chipset Temperature,
* Tsensor 1 Temperature,
* CPU VRM Temperature,
* Water In,
* Water Out,
* CPU VRM Output Current.
Known Issues:
* The WMI implementation in some of Asus' BIOSes is buggy. This can result in
fans stopping, fans getting stuck at max speed, or temperature readouts
getting stuck. This is not an issue with the driver, but the BIOS. The Prime
X470 Pro seems particularly bad for this. The more frequently the WMI
interface is polled the greater the potential for this to happen. Until you
have subjected your computer to an extended soak test while polling the
sensors frequently, don't leave you computer unattended. Upgrading to new
BIOS version with method version greater than or equal to two should
rectify the issue.
* A few boards report 12v voltages to be ~10v.

56
Documentation/hwmon/ina238.rst Normal file
View File

@ -0,0 +1,56 @@
.. SPDX-License-Identifier: GPL-2.0-only
Kernel driver ina238
====================
Supported chips:
* Texas Instruments INA238
Prefix: 'ina238'
Addresses: I2C 0x40 - 0x4f
Datasheet:
https://www.ti.com/lit/gpn/ina238
Author: Nathan Rossi <nathan.rossi@digi.com>
Description
-----------
The INA238 is a current shunt, power and temperature monitor with an I2C
interface. It includes a number of programmable functions including alerts,
conversion rate, sample averaging and selectable shunt voltage accuracy.
The shunt value in micro-ohms can be set via platform data or device tree at
compile-time or via the shunt_resistor attribute in sysfs at run-time. Please
refer to the Documentation/devicetree/bindings/hwmon/ti,ina2xx.yaml for bindings
if the device tree is used.
Sysfs entries
-------------
======================= =======================================================
in0_input Shunt voltage (mV)
in0_min Minimum shunt voltage threshold (mV)
in0_min_alarm Minimum shunt voltage alarm
in0_max Maximum shunt voltage threshold (mV)
in0_max_alarm Maximum shunt voltage alarm
in1_input Bus voltage (mV)
in1_min Minimum bus voltage threshold (mV)
in1_min_alarm Minimum shunt voltage alarm
in1_max Maximum bus voltage threshold (mV)
in1_max_alarm Maximum shunt voltage alarm
power1_input Power measurement (uW)
power1_max Maximum power threshold (uW)
power1_max_alarm Maximum power alarm
curr1_input Current measurement (mA)
temp1_input Die temperature measurement (mC)
temp1_max Maximum die temperature threshold (mC)
temp1_max_alarm Maximum die temperature alarm
======================= =======================================================

5
Documentation/hwmon/index.rst
View File

@ -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

28
Documentation/hwmon/ir38064.rst
View File

@ -3,14 +3,38 @@ Kernel driver ir38064
Supported chips:
* Infineon IR38060
Prefix: 'IR38060'
Addresses scanned: -
Datasheet: Publicly available at the Infineon website
https://www.infineon.com/dgdl/Infineon-IR38060M-DS-v03_16-EN.pdf?fileId=5546d4625c167129015c3291ea9a4cee
* Infineon IR38064
Prefix: 'ir38064'
Addresses scanned: -
Datasheet: Publicly available at the Infineon webiste
Datasheet: Publicly available at the Infineon website
https://www.infineon.com/dgdl/Infineon-IR38064MTRPBF-DS-v03_07-EN.pdf?fileId=5546d462584d1d4a0158db0d9efb67ca
* Infineon IR38164
Prefix: 'ir38164'
Addresses scanned: -
Datasheet: Publicly available at the Infineon website
https://www.infineon.com/dgdl/Infineon-IR38164M-DS-v02_02-EN.pdf?fileId=5546d462636cc8fb01640046efea1248
* Infineon ir38263
Prefix: 'ir38263'
Addresses scanned: -
Datasheet: Publicly available at the Infineon website
https://www.infineon.com/dgdl/Infineon-IR38263M-DataSheet-v03_05-EN.pdf?fileId=5546d4625b62cd8a015bcf81f90a6e52
Authors:
- Maxim Sloyko <maxims@google.com>
- Patrick Venture <venture@google.com>
@ -18,7 +42,7 @@ Authors:
Description
-----------
IR38064 is a Single-input Voltage, Synchronous Buck Regulator, DC-DC Converter.
IR38x6x are a Single-input Voltage, Synchronous Buck Regulator, DC-DC Converter.
Usage Notes
-----------

84
Documentation/hwmon/mp5023.rst Normal file
View File

@ -0,0 +1,84 @@
.. SPDX-License-Identifier: GPL-2.0
Kernel driver mp5023
====================
Supported chips:
* MPS MP5023
Prefix: 'mp5023'
* Datasheet
Publicly available at the MPS website : https://www.monolithicpower.com/en/mp5023.html
Author:
Howard Chiu <howard.chiu@quantatw.com>
Description
-----------
This driver implements support for Monolithic Power Systems, Inc. (MPS)
MP5023 Hot-Swap Controller.
Device complaint with:
- PMBus rev 1.3 interface.
Device supports direct format for reading input voltage, output voltage,
output current, input power and temperature.
The driver exports the following attributes via the 'sysfs' files
for input voltage:
**in1_input**
**in1_label**
**in1_max**
**in1_max_alarm**
**in1_min**
**in1_min_alarm**
The driver provides the following attributes for output voltage:
**in2_input**
**in2_label**
**in2_alarm**
The driver provides the following attributes for output current:
**curr1_input**
**curr1_label**
**curr1_alarm**
**curr1_max**
The driver provides the following attributes for input power:
**power1_input**
**power1_label**
**power1_alarm**
The driver provides the following attributes for temperature:
**temp1_input**
**temp1_max**
**temp1_max_alarm**
**temp1_crit**
**temp1_crit_alarm**

Some files were not shown because too many files have changed in this diff Show More