tmakin/ack-tegra
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Merge 259f7d5e2b ("Merge tag 'thermal-6.9-rc1' of git://git.kernel.org/pub/scm/linux/kernel/git/rafael/linux-pm") into android-mainline

Browse Source 
Steps on the way to v6.9-rc1

Signed-off-by: Lee Jones <joneslee@google.com>
Change-Id: Iba3774ffbda85ab5bd6277ce6ef6e3d552d461d3
This commit is contained in:
Lee Jones
2024-04-15 14:57:02 +01:00
committed by Treehugger Robot
parent 320b35119e 259f7d5e2b
commit f48aa34a88
846 changed files with 76929 additions and 10391 deletions
Download Patch File Download Diff File Expand all files Collapse all files
Documentation/ABI/obsolete/sysfs-gpio
+2 -2
View File
@@ -28,5 +28,5 @@ Description:
/label ... (r/o) descriptive, not necessarily unique
/ngpio ... (r/o) number of GPIOs; numbered N to N + (ngpio - 1)
This ABI is deprecated and will be removed after 2020. It is
replaced with the GPIO character device.
This ABI is obsoleted by Documentation/ABI/testing/gpio-cdev and will be
removed after 2020.
Documentation/ABI/testing/debugfs-intel-iommu
+276
View File
@@ -0,0 +1,276 @@
What: /sys/kernel/debug/iommu/intel/iommu_regset
Date: December 2023
Contact: Jingqi Liu <Jingqi.liu@intel.com>
Description:
This file dumps all the register contents for each IOMMU device.
Example in Kabylake:
::
$ sudo cat /sys/kernel/debug/iommu/intel/iommu_regset
IOMMU: dmar0 Register Base Address: 26be37000
Name Offset Contents
VER 0x00 0x0000000000000010
GCMD 0x18 0x0000000000000000
GSTS 0x1c 0x00000000c7000000
FSTS 0x34 0x0000000000000000
FECTL 0x38 0x0000000000000000
[...]
IOMMU: dmar1 Register Base Address: fed90000
Name Offset Contents
VER 0x00 0x0000000000000010
GCMD 0x18 0x0000000000000000
GSTS 0x1c 0x00000000c7000000
FSTS 0x34 0x0000000000000000
FECTL 0x38 0x0000000000000000
[...]
IOMMU: dmar2 Register Base Address: fed91000
Name Offset Contents
VER 0x00 0x0000000000000010
GCMD 0x18 0x0000000000000000
GSTS 0x1c 0x00000000c7000000
FSTS 0x34 0x0000000000000000
FECTL 0x38 0x0000000000000000
[...]
What: /sys/kernel/debug/iommu/intel/ir_translation_struct
Date: December 2023
Contact: Jingqi Liu <Jingqi.liu@intel.com>
Description:
This file dumps the table entries for Interrupt
remapping and Interrupt posting.
Example in Kabylake:
::
$ sudo cat /sys/kernel/debug/iommu/intel/ir_translation_struct
Remapped Interrupt supported on IOMMU: dmar0
IR table address:100900000
Entry SrcID DstID Vct IRTE_high IRTE_low
0 00:0a.0 00000080 24 0000000000040050 000000800024000d
1 00:0a.0 00000001 ef 0000000000040050 0000000100ef000d
Remapped Interrupt supported on IOMMU: dmar1
IR table address:100300000
Entry SrcID DstID Vct IRTE_high IRTE_low
0 00:02.0 00000002 26 0000000000040010 000000020026000d
[...]
****
Posted Interrupt supported on IOMMU: dmar0
IR table address:100900000
Entry SrcID PDA_high PDA_low Vct IRTE_high IRTE_low
What: /sys/kernel/debug/iommu/intel/dmar_translation_struct
Date: December 2023
Contact: Jingqi Liu <Jingqi.liu@intel.com>
Description:
This file dumps Intel IOMMU DMA remapping tables, such
as root table, context table, PASID directory and PASID
table entries in debugfs. For legacy mode, it doesn't
support PASID, and hence PASID field is defaulted to
'-1' and other PASID related fields are invalid.
Example in Kabylake:
::
$ sudo cat /sys/kernel/debug/iommu/intel/dmar_translation_struct
IOMMU dmar1: Root Table Address: 0x103027000
B.D.F Root_entry
00:02.0 0x0000000000000000:0x000000010303e001
Context_entry
0x0000000000000102:0x000000010303f005
PASID PASID_table_entry
-1 0x0000000000000000:0x0000000000000000:0x0000000000000000
IOMMU dmar0: Root Table Address: 0x103028000
B.D.F Root_entry
00:0a.0 0x0000000000000000:0x00000001038a7001
Context_entry
0x0000000000000000:0x0000000103220e7d
PASID PASID_table_entry
0 0x0000000000000000:0x0000000000800002:0x00000001038a5089
[...]
What: /sys/kernel/debug/iommu/intel/invalidation_queue
Date: December 2023
Contact: Jingqi Liu <Jingqi.liu@intel.com>
Description:
This file exports invalidation queue internals of each
IOMMU device.
Example in Kabylake:
::
$ sudo cat /sys/kernel/debug/iommu/intel/invalidation_queue
Invalidation queue on IOMMU: dmar0
Base: 0x10022e000 Head: 20 Tail: 20
Index qw0 qw1 qw2
0 0000000000000014 0000000000000000 0000000000000000
1 0000000200000025 0000000100059c04 0000000000000000
2 0000000000000014 0000000000000000 0000000000000000
qw3 status
0000000000000000 0000000000000000
0000000000000000 0000000000000000
0000000000000000 0000000000000000
[...]
Invalidation queue on IOMMU: dmar1
Base: 0x10026e000 Head: 32 Tail: 32
Index qw0 qw1 status
0 0000000000000004 0000000000000000 0000000000000000
1 0000000200000025 0000000100059804 0000000000000000
2 0000000000000011 0000000000000000 0000000000000000
[...]
What: /sys/kernel/debug/iommu/intel/dmar_perf_latency
Date: December 2023
Contact: Jingqi Liu <Jingqi.liu@intel.com>
Description:
This file is used to control and show counts of
execution time ranges for various types per DMAR.
Firstly, write a value to
/sys/kernel/debug/iommu/intel/dmar_perf_latency
to enable sampling.
The possible values are as follows:
* 0 - disable sampling all latency data
* 1 - enable sampling IOTLB invalidation latency data
* 2 - enable sampling devTLB invalidation latency data
* 3 - enable sampling intr entry cache invalidation latency data
Next, read /sys/kernel/debug/iommu/intel/dmar_perf_latency gives
a snapshot of sampling result of all enabled monitors.
Examples in Kabylake:
::
1) Disable sampling all latency data:
$ sudo echo 0 > /sys/kernel/debug/iommu/intel/dmar_perf_latency
2) Enable sampling IOTLB invalidation latency data
$ sudo echo 1 > /sys/kernel/debug/iommu/intel/dmar_perf_latency
$ sudo cat /sys/kernel/debug/iommu/intel/dmar_perf_latency
IOMMU: dmar0 Register Base Address: 26be37000
<0.1us 0.1us-1us 1us-10us 10us-100us 100us-1ms
inv_iotlb 0 0 0 0 0
1ms-10ms >=10ms min(us) max(us) average(us)
inv_iotlb 0 0 0 0 0
[...]
IOMMU: dmar2 Register Base Address: fed91000
<0.1us 0.1us-1us 1us-10us 10us-100us 100us-1ms
inv_iotlb 0 0 18 0 0
1ms-10ms >=10ms min(us) max(us) average(us)
inv_iotlb 0 0 2 2 2
3) Enable sampling devTLB invalidation latency data
$ sudo echo 2 > /sys/kernel/debug/iommu/intel/dmar_perf_latency
$ sudo cat /sys/kernel/debug/iommu/intel/dmar_perf_latency
IOMMU: dmar0 Register Base Address: 26be37000
<0.1us 0.1us-1us 1us-10us 10us-100us 100us-1ms
inv_devtlb 0 0 0 0 0
>=10ms min(us) max(us) average(us)
inv_devtlb 0 0 0 0
[...]
What: /sys/kernel/debug/iommu/intel/<bdf>/domain_translation_struct
Date: December 2023
Contact: Jingqi Liu <Jingqi.liu@intel.com>
Description:
This file dumps a specified page table of Intel IOMMU
in legacy mode or scalable mode.
For a device that only supports legacy mode, dump its
page table by the debugfs file in the debugfs device
directory. e.g.
/sys/kernel/debug/iommu/intel/0000:00:02.0/domain_translation_struct.
For a device that supports scalable mode, dump the
page table of specified pasid by the debugfs file in
the debugfs pasid directory. e.g.
/sys/kernel/debug/iommu/intel/0000:00:02.0/1/domain_translation_struct.
Examples in Kabylake:
::
1) Dump the page table of device "0000:00:02.0" that only supports legacy mode.
$ sudo cat /sys/kernel/debug/iommu/intel/0000:00:02.0/domain_translation_struct
Device 0000:00:02.0 @0x1017f8000
IOVA_PFN PML5E PML4E
0x000000008d800 | 0x0000000000000000 0x00000001017f9003
0x000000008d801 | 0x0000000000000000 0x00000001017f9003
0x000000008d802 | 0x0000000000000000 0x00000001017f9003
PDPE PDE PTE
0x00000001017fa003 0x00000001017fb003 0x000000008d800003
0x00000001017fa003 0x00000001017fb003 0x000000008d801003
0x00000001017fa003 0x00000001017fb003 0x000000008d802003
[...]
2) Dump the page table of device "0000:00:0a.0" with PASID "1" that
supports scalable mode.
$ sudo cat /sys/kernel/debug/iommu/intel/0000:00:0a.0/1/domain_translation_struct
Device 0000:00:0a.0 with pasid 1 @0x10c112000
IOVA_PFN PML5E PML4E
0x0000000000000 | 0x0000000000000000 0x000000010df93003
0x0000000000001 | 0x0000000000000000 0x000000010df93003
0x0000000000002 | 0x0000000000000000 0x000000010df93003
PDPE PDE PTE
0x0000000106ae6003 0x0000000104b38003 0x0000000147c00803
0x0000000106ae6003 0x0000000104b38003 0x0000000147c01803
0x0000000106ae6003 0x0000000104b38003 0x0000000147c02803
[...]
Documentation/ABI/testing/gpio-cdev
+5 -4
View File
@@ -6,8 +6,9 @@ Description:
The character device files /dev/gpiochip* are the interface
between GPIO chips and userspace.
The ioctl(2)-based ABI is defined and documented in
[include/uapi]<linux/gpio.h>.
The ioctl(2)-based ABI is defined in
[include/uapi]<linux/gpio.h> and documented in
Documentation/userspace-api/gpio/chardev.rst.
The following file operations are supported:
@@ -17,8 +18,8 @@ Description:
ioctl(2)
Initiate various actions.
See the inline documentation in [include/uapi]<linux/gpio.h>
for descriptions of all ioctls.
See Documentation/userspace-api/gpio/chardev.rst
for a description of all ioctls.
close(2)
Stops and free up the I/O contexts that was associated
Documentation/ABI/testing/sysfs-class-hwmon
+27
View File
@@ -149,6 +149,15 @@ Description:
RW
What: /sys/class/hwmon/hwmonX/inY_fault
Description:
Reports a voltage hard failure (eg: shorted component)
- 1: Failed
- 0: Ok
RO
What: /sys/class/hwmon/hwmonX/cpuY_vid
Description:
CPU core reference voltage.
@@ -968,6 +977,15 @@ Description:
RW
What: /sys/class/hwmon/hwmonX/humidityY_max_alarm
Description:
Maximum humidity detection
- 0: OK
- 1: Maximum humidity detected
RO
What: /sys/class/hwmon/hwmonX/humidityY_max_hyst
Description:
Humidity hysteresis value for max limit.
@@ -987,6 +1005,15 @@ Description:
RW
What: /sys/class/hwmon/hwmonX/humidityY_min_alarm
Description:
Minimum humidity detection
- 0: OK
- 1: Minimum humidity detected
RO
What: /sys/class/hwmon/hwmonX/humidityY_min_hyst
Description:
Humidity hysteresis value for min limit.
Documentation/admin-guide/device-mapper/index.rst
+2
View File
@@ -34,6 +34,8 @@ Device Mapper
switch
thin-provisioning
unstriped
vdo-design
vdo
verity
writecache
zero
Documentation/admin-guide/device-mapper/vdo-design.rst
+633
View File
@@ -0,0 +1,633 @@
.. SPDX-License-Identifier: GPL-2.0-only
================
Design of dm-vdo
================
The dm-vdo (virtual data optimizer) target provides inline deduplication,
compression, zero-block elimination, and thin provisioning. A dm-vdo target
can be backed by up to 256TB of storage, and can present a logical size of
up to 4PB. This target was originally developed at Permabit Technology
Corp. starting in 2009. It was first released in 2013 and has been used in
production environments ever since. It was made open-source in 2017 after
Permabit was acquired by Red Hat. This document describes the design of
dm-vdo. For usage, see vdo.rst in the same directory as this file.
Because deduplication rates fall drastically as the block size increases, a
vdo target has a maximum block size of 4K. However, it can achieve
deduplication rates of 254:1, i.e. up to 254 copies of a given 4K block can
reference a single 4K of actual storage. It can achieve compression rates
of 14:1. All zero blocks consume no storage at all.
Theory of Operation
===================
The design of dm-vdo is based on the idea that deduplication is a two-part
problem. The first is to recognize duplicate data. The second is to avoid
storing multiple copies of those duplicates. Therefore, dm-vdo has two main
parts: a deduplication index (called UDS) that is used to discover
duplicate data, and a data store with a reference counted block map that
maps from logical block addresses to the actual storage location of the
data.
Zones and Threading
-------------------
Due to the complexity of data optimization, the number of metadata
structures involved in a single write operation to a vdo target is larger
than most other targets. Furthermore, because vdo must operate on small
block sizes in order to achieve good deduplication rates, acceptable
performance can only be achieved through parallelism. Therefore, vdo's
design attempts to be lock-free.
Most of a vdo's main data structures are designed to be easily divided into
"zones" such that any given bio must only access a single zone of any zoned
structure. Safety with minimal locking is achieved by ensuring that during
normal operation, each zone is assigned to a specific thread, and only that
thread will access the portion of the data structure in that zone.
Associated with each thread is a work queue. Each bio is associated with a
request object (the "data_vio") which will be added to a work queue when
the next phase of its operation requires access to the structures in the
zone associated with that queue.
Another way of thinking about this arrangement is that the work queue for
each zone has an implicit lock on the structures it manages for all its
operations, because vdo guarantees that no other thread will alter those
structures.
Although each structure is divided into zones, this division is not
reflected in the on-disk representation of each data structure. Therefore,
the number of zones for each structure, and hence the number of threads,
can be reconfigured each time a vdo target is started.
The Deduplication Index
-----------------------
In order to identify duplicate data efficiently, vdo was designed to
leverage some common characteristics of duplicate data. From empirical
observations, we gathered two key insights. The first is that in most data
sets with significant amounts of duplicate data, the duplicates tend to
have temporal locality. When a duplicate appears, it is more likely that
other duplicates will be detected, and that those duplicates will have been
written at about the same time. This is why the index keeps records in
temporal order. The second insight is that new data is more likely to
duplicate recent data than it is to duplicate older data and in general,
there are diminishing returns to looking further back in time. Therefore,
when the index is full, it should cull its oldest records to make space for
new ones. Another important idea behind the design of the index is that the
ultimate goal of deduplication is to reduce storage costs. Since there is a
trade-off between the storage saved and the resources expended to achieve
those savings, vdo does not attempt to find every last duplicate block. It
is sufficient to find and eliminate most of the redundancy.
Each block of data is hashed to produce a 16-byte block name. An index
record consists of this block name paired with the presumed location of
that data on the underlying storage. However, it is not possible to
guarantee that the index is accurate. In the most common case, this occurs
because it is too costly to update the index when a block is over-written
or discarded. Doing so would require either storing the block name along
with the blocks, which is difficult to do efficiently in block-based
storage, or reading and rehashing each block before overwriting it.
Inaccuracy can also result from a hash collision where two different blocks
have the same name. In practice, this is extremely unlikely, but because
vdo does not use a cryptographic hash, a malicious workload could be
constructed. Because of these inaccuracies, vdo treats the locations in the
index as hints, and reads each indicated block to verify that it is indeed
a duplicate before sharing the existing block with a new one.
Records are collected into groups called chapters. New records are added to
the newest chapter, called the open chapter. This chapter is stored in a
format optimized for adding and modifying records, and the content of the
open chapter is not finalized until it runs out of space for new records.
When the open chapter fills up, it is closed and a new open chapter is
created to collect new records.
Closing a chapter converts it to a different format which is optimized for
reading. The records are written to a series of record pages based on the
order in which they were received. This means that records with temporal
locality should be on a small number of pages, reducing the I/O required to
retrieve them. The chapter also compiles an index that indicates which
record page contains any given name. This index means that a request for a
name can determine exactly which record page may contain that record,
without having to load the entire chapter from storage. This index uses
only a subset of the block name as its key, so it cannot guarantee that an
index entry refers to the desired block name. It can only guarantee that if
there is a record for this name, it will be on the indicated page. Closed
chapters are read-only structures and their contents are never altered in
any way.
Once enough records have been written to fill up all the available index
space, the oldest chapter is removed to make space for new chapters. Any
time a request finds a matching record in the index, that record is copied
into the open chapter. This ensures that useful block names remain available
in the index, while unreferenced block names are forgotten over time.
In order to find records in older chapters, the index also maintains a
higher level structure called the volume index, which contains entries
mapping each block name to the chapter containing its newest record. This
mapping is updated as records for the block name are copied or updated,
ensuring that only the newest record for a given block name can be found.
An older record for a block name will no longer be found even though it has
not been deleted from its chapter. Like the chapter index, the volume index
uses only a subset of the block name as its key and can not definitively
say that a record exists for a name. It can only say which chapter would
contain the record if a record exists. The volume index is stored entirely
in memory and is saved to storage only when the vdo target is shut down.
From the viewpoint of a request for a particular block name, it will first
look up the name in the volume index. This search will either indicate that
the name is new, or which chapter to search. If it returns a chapter, the
request looks up its name in the chapter index. This will indicate either
that the name is new, or which record page to search. Finally, if it is not
new, the request will look for its name in the indicated record page.
This process may require up to two page reads per request (one for the
chapter index page and one for the request page). However, recently
accessed pages are cached so that these page reads can be amortized across
many block name requests.
The volume index and the chapter indexes are implemented using a
memory-efficient structure called a delta index. Instead of storing the
entire block name (the key) for each entry, the entries are sorted by name
and only the difference between adjacent keys (the delta) is stored.
Because we expect the hashes to be randomly distributed, the size of the
deltas follows an exponential distribution. Because of this distribution,
the deltas are expressed using a Huffman code to take up even less space.
The entire sorted list of keys is called a delta list. This structure
allows the index to use many fewer bytes per entry than a traditional hash
table, but it is slightly more expensive to look up entries, because a
request must read every entry in a delta list to add up the deltas in order
to find the record it needs. The delta index reduces this lookup cost by
splitting its key space into many sub-lists, each starting at a fixed key
value, so that each individual list is short.
The default index size can hold 64 million records, corresponding to about
256GB of data. This means that the index can identify duplicate data if the
original data was written within the last 256GB of writes. This range is
called the deduplication window. If new writes duplicate data that is older
than that, the index will not be able to find it because the records of the
older data have been removed. This means that if an application writes a
200 GB file to a vdo target and then immediately writes it again, the two
copies will deduplicate perfectly. Doing the same with a 500 GB file will
result in no deduplication, because the beginning of the file will no
longer be in the index by the time the second write begins (assuming there
is no duplication within the file itself).
If an application anticipates a data workload that will see useful
deduplication beyond the 256GB threshold, vdo can be configured to use a
larger index with a correspondingly larger deduplication window. (This
configuration can only be set when the target is created, not altered
later. It is important to consider the expected workload for a vdo target
before configuring it.) There are two ways to do this.
One way is to increase the memory size of the index, which also increases
the amount of backing storage required. Doubling the size of the index will
double the length of the deduplication window at the expense of doubling
the storage size and the memory requirements.
The other option is to enable sparse indexing. Sparse indexing increases
the deduplication window by a factor of 10, at the expense of also
increasing the storage size by a factor of 10. However with sparse
indexing, the memory requirements do not increase. The trade-off is
slightly more computation per request and a slight decrease in the amount
of deduplication detected. For most workloads with significant amounts of
duplicate data, sparse indexing will detect 97-99% of the deduplication
that a standard index will detect.
The vio and data_vio Structures
-------------------------------
A vio (short for Vdo I/O) is conceptually similar to a bio, with additional
fields and data to track vdo-specific information. A struct vio maintains a
pointer to a bio but also tracks other fields specific to the operation of
vdo. The vio is kept separate from its related bio because there are many
circumstances where vdo completes the bio but must continue to do work
related to deduplication or compression.
Metadata reads and writes, and other writes that originate within vdo, use
a struct vio directly. Application reads and writes use a larger structure
called a data_vio to track information about their progress. A struct
data_vio contain a struct vio and also includes several other fields
related to deduplication and other vdo features. The data_vio is the
primary unit of application work in vdo. Each data_vio proceeds through a
set of steps to handle the application data, after which it is reset and
returned to a pool of data_vios for reuse.
There is a fixed pool of 2048 data_vios. This number was chosen to bound
the amount of work that is required to recover from a crash. In addition,
benchmarks have indicated that increasing the size of the pool does not
significantly improve performance.
The Data Store
--------------
The data store is implemented by three main data structures, all of which
work in concert to reduce or amortize metadata updates across as many data
writes as possible.
*The Slab Depot*
Most of the vdo volume belongs to the slab depot. The depot contains a
collection of slabs. The slabs can be up to 32GB, and are divided into
three sections. Most of a slab consists of a linear sequence of 4K blocks.
These blocks are used either to store data, or to hold portions of the
block map (see below). In addition to the data blocks, each slab has a set
of reference counters, using 1 byte for each data block. Finally each slab
has a journal.
Reference updates are written to the slab journal. Slab journal blocks are
written out either when they are full, or when the recovery journal
requests they do so in order to allow the main recovery journal (see below)
to free up space. The slab journal is used both to ensure that the main
recovery journal can regularly free up space, and also to amortize the cost
of updating individual reference blocks. The reference counters are kept in
memory and are written out, a block at a time in oldest-dirtied-order, only
when there is a need to reclaim slab journal space. The write operations
are performed in the background as needed so they do not add latency to
particular I/O operations.
Each slab is independent of every other. They are assigned to "physical
zones" in round-robin fashion. If there are P physical zones, then slab n
is assigned to zone n mod P.
The slab depot maintains an additional small data structure, the "slab
summary," which is used to reduce the amount of work needed to come back
online after a crash. The slab summary maintains an entry for each slab
indicating whether or not the slab has ever been used, whether all of its
reference count updates have been persisted to storage, and approximately
how full it is. During recovery, each physical zone will attempt to recover
at least one slab, stopping whenever it has recovered a slab which has some
free blocks. Once each zone has some space, or has determined that none is
available, the target can resume normal operation in a degraded mode. Read
and write requests can be serviced, perhaps with degraded performance,
while the remainder of the dirty slabs are recovered.
*The Block Map*
The block map contains the logical to physical mapping. It can be thought
of as an array with one entry per logical address. Each entry is 5 bytes,
36 bits of which contain the physical block number which holds the data for
the given logical address. The other 4 bits are used to indicate the nature
of the mapping. Of the 16 possible states, one represents a logical address
which is unmapped (i.e. it has never been written, or has been discarded),
one represents an uncompressed block, and the other 14 states are used to
indicate that the mapped data is compressed, and which of the compression
slots in the compressed block contains the data for this logical address.
In practice, the array of mapping entries is divided into "block map
pages," each of which fits in a single 4K block. Each block map page
consists of a header and 812 mapping entries. Each mapping page is actually
a leaf of a radix tree which consists of block map pages at each level.
There are 60 radix trees which are assigned to "logical zones" in round
robin fashion. (If there are L logical zones, tree n will belong to zone n
mod L.) At each level, the trees are interleaved, so logical addresses
0-811 belong to tree 0, logical addresses 812-1623 belong to tree 1, and so
on. The interleaving is maintained all the way up to the 60 root nodes.
Choosing 60 trees results in an evenly distributed number of trees per zone
for a large number of possible logical zone counts. The storage for the 60
tree roots is allocated at format time. All other block map pages are
allocated out of the slabs as needed. This flexible allocation avoids the
need to pre-allocate space for the entire set of logical mappings and also
makes growing the logical size of a vdo relatively easy.
In operation, the block map maintains two caches. It is prohibitive to keep
the entire leaf level of the trees in memory, so each logical zone
maintains its own cache of leaf pages. The size of this cache is
configurable at target start time. The second cache is allocated at start
time, and is large enough to hold all the non-leaf pages of the entire
block map. This cache is populated as pages are needed.
*The Recovery Journal*
The recovery journal is used to amortize updates across the block map and
slab depot. Each write request causes an entry to be made in the journal.
Entries are either "data remappings" or "block map remappings." For a data
remapping, the journal records the logical address affected and its old and
new physical mappings. For a block map remapping, the journal records the
block map page number and the physical block allocated for it. Block map
pages are never reclaimed or repurposed, so the old mapping is always 0.
Each journal entry is an intent record summarizing the metadata updates
that are required for a data_vio. The recovery journal issues a flush
before each journal block write to ensure that the physical data for the
new block mappings in that block are stable on storage, and journal block
writes are all issued with the FUA bit set to ensure the recovery journal
entries themselves are stable. The journal entry and the data write it
represents must be stable on disk before the other metadata structures may
be updated to reflect the operation. These entries allow the vdo device to
reconstruct the logical to physical mappings after an unexpected
interruption such as a loss of power.
*Write Path*
All write I/O to vdo is asynchronous. Each bio will be acknowledged as soon
as vdo has done enough work to guarantee that it can complete the write
eventually. Generally, the data for acknowledged but unflushed write I/O
can be treated as though it is cached in memory. If an application
requires data to be stable on storage, it must issue a flush or write the
data with the FUA bit set like any other asynchronous I/O. Shutting down
the vdo target will also flush any remaining I/O.
Application write bios follow the steps outlined below.
1. A data_vio is obtained from the data_vio pool and associated with the
application bio. If there are no data_vios available, the incoming bio
will block until a data_vio is available. This provides back pressure
to the application. The data_vio pool is protected by a spin lock.
The newly acquired data_vio is reset and the bio's data is copied into
the data_vio if it is a write and the data is not all zeroes. The data
must be copied because the application bio can be acknowledged before
the data_vio processing is complete, which means later processing steps
will no longer have access to the application bio. The application bio
may also be smaller than 4K, in which case the data_vio will have
already read the underlying block and the data is instead copied over
the relevant portion of the larger block.
2. The data_vio places a claim (the "logical lock") on the logical address
of the bio. It is vital to prevent simultaneous modifications of the
same logical address, because deduplication involves sharing blocks.
This claim is implemented as an entry in a hashtable where the key is
the logical address and the value is a pointer to the data_vio
currently handling that address.
If a data_vio looks in the hashtable and finds that another data_vio is
already operating on that logical address, it waits until the previous
operation finishes. It also sends a message to inform the current
lock holder that it is waiting. Most notably, a new data_vio waiting
for a logical lock will flush the previous lock holder out of the
compression packer (step 8d) rather than allowing it to continue
waiting to be packed.
This stage requires the data_vio to get an implicit lock on the
appropriate logical zone to prevent concurrent modifications of the
hashtable. This implicit locking is handled by the zone divisions
described above.
3. The data_vio traverses the block map tree to ensure that all the
necessary internal tree nodes have been allocated, by trying to find
the leaf page for its logical address. If any interior tree page is
missing, it is allocated at this time out of the same physical storage
pool used to store application data.
a. If any page-node in the tree has not yet been allocated, it must be
allocated before the write can continue. This step requires the
data_vio to lock the page-node that needs to be allocated. This
lock, like the logical block lock in step 2, is a hashtable entry
that causes other data_vios to wait for the allocation process to
complete.
The implicit logical zone lock is released while the allocation is
happening, in order to allow other operations in the same logical
zone to proceed. The details of allocation are the same as in
step 4. Once a new node has been allocated, that node is added to
the tree using a similar process to adding a new data block mapping.
The data_vio journals the intent to add the new node to the block
map tree (step 10), updates the reference count of the new block
(step 11), and reacquires the implicit logical zone lock to add the
new mapping to the parent tree node (step 12). Once the tree is
updated, the data_vio proceeds down the tree. Any other data_vios
waiting on this allocation also proceed.
b. In the steady-state case, the block map tree nodes will already be
allocated, so the data_vio just traverses the tree until it finds
the required leaf node. The location of the mapping (the "block map
slot") is recorded in the data_vio so that later steps do not need
to traverse the tree again. The data_vio then releases the implicit
logical zone lock.
4. If the block is a zero block, skip to step 9. Otherwise, an attempt is
made to allocate a free data block. This allocation ensures that the
data_vio can write its data somewhere even if deduplication and
compression are not possible. This stage gets an implicit lock on a
physical zone to search for free space within that zone.
The data_vio will search each slab in a zone until it finds a free
block or decides there are none. If the first zone has no free space,
it will proceed to search the next physical zone by taking the implicit
lock for that zone and releasing the previous one until it finds a
free block or runs out of zones to search. The data_vio will acquire a
struct pbn_lock (the "physical block lock") on the free block. The
struct pbn_lock also has several fields to record the various kinds of
claims that data_vios can have on physical blocks. The pbn_lock is
added to a hashtable like the logical block locks in step 2. This
hashtable is also covered by the implicit physical zone lock. The
reference count of the free block is updated to prevent any other
data_vio from considering it free. The reference counters are a
sub-component of the slab and are thus also covered by the implicit
physical zone lock.
5. If an allocation was obtained, the data_vio has all the resources it
needs to complete the write. The application bio can safely be
acknowledged at this point. The acknowledgment happens on a separate
thread to prevent the application callback from blocking other data_vio
operations.
If an allocation could not be obtained, the data_vio continues to
attempt to deduplicate or compress the data, but the bio is not
acknowledged because the vdo device may be out of space.
6. At this point vdo must determine where to store the application data.
The data_vio's data is hashed and the hash (the "record name") is
recorded in the data_vio.
7. The data_vio reserves or joins a struct hash_lock, which manages all of
the data_vios currently writing the same data. Active hash locks are
tracked in a hashtable similar to the way logical block locks are
tracked in step 2. This hashtable is covered by the implicit lock on
the hash zone.
If there is no existing hash lock for this data_vio's record_name, the
data_vio obtains a hash lock from the pool, adds it to the hashtable,
and sets itself as the new hash lock's "agent." The hash_lock pool is
also covered by the implicit hash zone lock. The hash lock agent will
do all the work to decide where the application data will be
written. If a hash lock for the data_vio's record_name already exists,
and the data_vio's data is the same as the agent's data, the new
data_vio will wait for the agent to complete its work and then share
its result.
In the rare case that a hash lock exists for the data_vio's hash but
the data does not match the hash lock's agent, the data_vio skips to
step 8h and attempts to write its data directly. This can happen if two
different data blocks produce the same hash, for example.
8. The hash lock agent attempts to deduplicate or compress its data with
the following steps.
a. The agent initializes and sends its embedded deduplication request
(struct uds_request) to the deduplication index. This does not
require the data_vio to get any locks because the index components
manage their own locking. The data_vio waits until it either gets a
response from the index or times out.
b. If the deduplication index returns advice, the data_vio attempts to
obtain a physical block lock on the indicated physical address, in
order to read the data and verify that it is the same as the
data_vio's data, and that it can accept more references. If the
physical address is already locked by another data_vio, the data at
that address may soon be overwritten so it is not safe to use the
address for deduplication.
c. If the data matches and the physical block can add references, the
agent and any other data_vios waiting on it will record this
physical block as their new physical address and proceed to step 9
to record their new mapping. If there are more data_vios in the hash
lock than there are references available, one of the remaining
data_vios becomes the new agent and continues to step 8d as if no
valid advice was returned.
d. If no usable duplicate block was found, the agent first checks that
it has an allocated physical block (from step 3) that it can write
to. If the agent does not have an allocation, some other data_vio in
the hash lock that does have an allocation takes over as agent. If
none of the data_vios have an allocated physical block, these writes
are out of space, so they proceed to step 13 for cleanup.
e. The agent attempts to compress its data. If the data does not
compress, the data_vio will continue to step 8h to write its data
directly.
If the compressed size is small enough, the agent will release the
implicit hash zone lock and go to the packer (struct packer) where
it will be placed in a bin (struct packer_bin) along with other
data_vios. All compression operations require the implicit lock on
the packer zone.
The packer can combine up to 14 compressed blocks in a single 4k
data block. Compression is only helpful if vdo can pack at least 2
data_vios into a single data block. This means that a data_vio may
wait in the packer for an arbitrarily long time for other data_vios
to fill out the compressed block. There is a mechanism for vdo to
evict waiting data_vios when continuing to wait would cause
problems. Circumstances causing an eviction include an application
flush, device shutdown, or a subsequent data_vio trying to overwrite
the same logical block address. A data_vio may also be evicted from
the packer if it cannot be paired with any other compressed block
before more compressible blocks need to use its bin. An evicted
data_vio will proceed to step 8h to write its data directly.
f. If the agent fills a packer bin, either because all 14 of its slots
are used or because it has no remaining space, it is written out
using the allocated physical block from one of its data_vios. Step
8d has already ensured that an allocation is available.
g. Each data_vio sets the compressed block as its new physical address.
The data_vio obtains an implicit lock on the physical zone and
acquires the struct pbn_lock for the compressed block, which is
modified to be a shared lock. Then it releases the implicit physical
zone lock and proceeds to step 8i.
h. Any data_vio evicted from the packer will have an allocation from
step 3. It will write its data to that allocated physical block.
i. After the data is written, if the data_vio is the agent of a hash
lock, it will reacquire the implicit hash zone lock and share its
physical address with as many other data_vios in the hash lock as
possible. Each data_vio will then proceed to step 9 to record its
new mapping.
j. If the agent actually wrote new data (whether compressed or not),
the deduplication index is updated to reflect the location of the
new data. The agent then releases the implicit hash zone lock.
9. The data_vio determines the previous mapping of the logical address.
There is a cache for block map leaf pages (the "block map cache"),
because there are usually too many block map leaf nodes to store
entirely in memory. If the desired leaf page is not in the cache, the
data_vio will reserve a slot in the cache and load the desired page
into it, possibly evicting an older cached page. The data_vio then
finds the current physical address for this logical address (the "old
physical mapping"), if any, and records it. This step requires a lock
on the block map cache structures, covered by the implicit logical zone
lock.
10. The data_vio makes an entry in the recovery journal containing the
logical block address, the old physical mapping, and the new physical
mapping. Making this journal entry requires holding the implicit
recovery journal lock. The data_vio will wait in the journal until all
recovery blocks up to the one containing its entry have been written
and flushed to ensure the transaction is stable on storage.
11. Once the recovery journal entry is stable, the data_vio makes two slab
journal entries: an increment entry for the new mapping, and a
decrement entry for the old mapping. These two operations each require
holding a lock on the affected physical slab, covered by its implicit
physical zone lock. For correctness during recovery, the slab journal
entries in any given slab journal must be in the same order as the
corresponding recovery journal entries. Therefore, if the two entries
are in different zones, they are made concurrently, and if they are in
the same zone, the increment is always made before the decrement in
order to avoid underflow. After each slab journal entry is made in
memory, the associated reference count is also updated in memory.
12. Once both of the reference count updates are done, the data_vio
acquires the implicit logical zone lock and updates the
logical-to-physical mapping in the block map to point to the new
physical block. At this point the write operation is complete.
13. If the data_vio has a hash lock, it acquires the implicit hash zone
lock and releases its hash lock to the pool.
The data_vio then acquires the implicit physical zone lock and releases
the struct pbn_lock it holds for its allocated block. If it had an
allocation that it did not use, it also sets the reference count for
that block back to zero to free it for use by subsequent data_vios.
The data_vio then acquires the implicit logical zone lock and releases
the logical block lock acquired in step 2.
The application bio is then acknowledged if it has not previously been
acknowledged, and the data_vio is returned to the pool.
*Read Path*
An application read bio follows a much simpler set of steps. It does steps
1 and 2 in the write path to obtain a data_vio and lock its logical
address. If there is already a write data_vio in progress for that logical
address that is guaranteed to complete, the read data_vio will copy the
data from the write data_vio and return it. Otherwise, it will look up the
logical-to-physical mapping by traversing the block map tree as in step 3,
and then read and possibly decompress the indicated data at the indicated
physical block address. A read data_vio will not allocate block map tree
nodes if they are missing. If the interior block map nodes do not exist
yet, the logical block map address must still be unmapped and the read
data_vio will return all zeroes. A read data_vio handles cleanup and
acknowledgment as in step 13, although it only needs to release the logical
lock and return itself to the pool.
*Small Writes*
All storage within vdo is managed as 4KB blocks, but it can accept writes
as small as 512 bytes. Processing a write that is smaller than 4K requires
a read-modify-write operation that reads the relevant 4K block, copies the
new data over the approriate sectors of the block, and then launches a
write operation for the modified data block. The read and write stages of
this operation are nearly identical to the normal read and write
operations, and a single data_vio is used throughout this operation.
*Recovery*
When a vdo is restarted after a crash, it will attempt to recover from the
recovery journal. During the pre-resume phase of the next start, the
recovery journal is read. The increment portion of valid entries are played
into the block map. Next, valid entries are played, in order as required,
into the slab journals. Finally, each physical zone attempts to replay at
least one slab journal to reconstruct the reference counts of one slab.
Once each zone has some free space (or has determined that it has none),
the vdo comes back online, while the remainder of the slab journals are
used to reconstruct the rest of the reference counts in the background.
*Read-only Rebuild*
If a vdo encounters an unrecoverable error, it will enter read-only mode.
This mode indicates that some previously acknowledged data may have been
lost. The vdo may be instructed to rebuild as best it can in order to
return to a writable state. However, this is never done automatically due
to the possibility that data has been lost. During a read-only rebuild, the
block map is recovered from the recovery journal as before. However, the
reference counts are not rebuilt from the slab journals. Instead, the
reference counts are zeroed, the entire block map is traversed, and the
reference counts are updated from the block mappings. While this may lose
some data, it ensures that the block map and reference counts are
consistent with each other. This allows vdo to resume normal operation and
accept further writes.
Documentation/admin-guide/device-mapper/vdo.rst
+406
View File
@@ -0,0 +1,406 @@
.. SPDX-License-Identifier: GPL-2.0-only
dm-vdo
======
The dm-vdo (virtual data optimizer) device mapper target provides
block-level deduplication, compression, and thin provisioning. As a device
mapper target, it can add these features to the storage stack, compatible
with any file system. The vdo target does not protect against data
corruption, relying instead on integrity protection of the storage below
it. It is strongly recommended that lvm be used to manage vdo volumes. See
lvmvdo(7).
Userspace component
===================
Formatting a vdo volume requires the use of the 'vdoformat' tool, available
at:
https://github.com/dm-vdo/vdo/
In most cases, a vdo target will recover from a crash automatically the
next time it is started. In cases where it encountered an unrecoverable
error (either during normal operation or crash recovery) the target will
enter or come up in read-only mode. Because read-only mode is indicative of
data-loss, a positive action must be taken to bring vdo out of read-only
mode. The 'vdoforcerebuild' tool, available from the same repo, is used to
prepare a read-only vdo to exit read-only mode. After running this tool,
the vdo target will rebuild its metadata the next time it is
started. Although some data may be lost, the rebuilt vdo's metadata will be
internally consistent and the target will be writable again.
The repo also contains additional userspace tools which can be used to
inspect a vdo target's on-disk metadata. Fortunately, these tools are
rarely needed except by dm-vdo developers.
Metadata requirements
=====================
Each vdo volume reserves 3GB of space for metadata, or more depending on
its configuration. It is helpful to check that the space saved by
deduplication and compression is not cancelled out by the metadata
requirements. An estimation of the space saved for a specific dataset can
be computed with the vdo estimator tool, which is available at:
https://github.com/dm-vdo/vdoestimator/
Target interface
================
Table line
----------
::
<offset> <logical device size> vdo V4 <storage device>
<storage device size> <minimum I/O size> <block map cache size>
<block map era length> [optional arguments]
Required parameters:
offset:
The offset, in sectors, at which the vdo volume's logical
space begins.
logical device size:
The size of the device which the vdo volume will service,
in sectors. Must match the current logical size of the vdo
volume.
storage device:
The device holding the vdo volume's data and metadata.
storage device size:
The size of the device holding the vdo volume, as a number
of 4096-byte blocks. Must match the current size of the vdo
volume.
minimum I/O size:
The minimum I/O size for this vdo volume to accept, in
bytes. Valid values are 512 or 4096. The recommended value
is 4096.
block map cache size:
The size of the block map cache, as a number of 4096-byte
blocks. The minimum and recommended value is 32768 blocks.
If the logical thread count is non-zero, the cache size
must be at least 4096 blocks per logical thread.
block map era length:
The speed with which the block map cache writes out
modified block map pages. A smaller era length is likely to
reduce the amount of time spent rebuilding, at the cost of
increased block map writes during normal operation. The
maximum and recommended value is 16380; the minimum value
is 1.
Optional parameters:
--------------------
Some or all of these parameters may be specified as <key> <value> pairs.
Thread related parameters:
Different categories of work are assigned to separate thread groups, and
the number of threads in each group can be configured separately.
If <hash>, <logical>, and <physical> are all set to 0, the work handled by
all three thread types will be handled by a single thread. If any of these
values are non-zero, all of them must be non-zero.
ack:
The number of threads used to complete bios. Since
completing a bio calls an arbitrary completion function
outside the vdo volume, threads of this type allow the vdo
volume to continue processing requests even when bio
completion is slow. The default is 1.
bio:
The number of threads used to issue bios to the underlying
storage. Threads of this type allow the vdo volume to
continue processing requests even when bio submission is
slow. The default is 4.
bioRotationInterval:
The number of bios to enqueue on each bio thread before
switching to the next thread. The value must be greater
than 0 and not more than 1024; the default is 64.
cpu:
The number of threads used to do CPU-intensive work, such
as hashing and compression. The default is 1.
hash:
The number of threads used to manage data comparisons for
deduplication based on the hash value of data blocks. The
default is 0.
logical:
The number of threads used to manage caching and locking
based on the logical address of incoming bios. The default
is 0; the maximum is 60.
physical:
The number of threads used to manage administration of the
underlying storage device. At format time, a slab size for
the vdo is chosen; the vdo storage device must be large
enough to have at least 1 slab per physical thread. The
default is 0; the maximum is 16.
Miscellaneous parameters:
maxDiscard:
The maximum size of discard bio accepted, in 4096-byte
blocks. I/O requests to a vdo volume are normally split
into 4096-byte blocks, and processed up to 2048 at a time.
However, discard requests to a vdo volume can be
automatically split to a larger size, up to <maxDiscard>
4096-byte blocks in a single bio, and are limited to 1500
at a time. Increasing this value may provide better overall
performance, at the cost of increased latency for the
individual discard requests. The default and minimum is 1;
the maximum is UINT_MAX / 4096.
deduplication:
Whether deduplication is enabled. The default is 'on'; the
acceptable values are 'on' and 'off'.
compression:
Whether compression is enabled. The default is 'off'; the
acceptable values are 'on' and 'off'.
Device modification
-------------------
A modified table may be loaded into a running, non-suspended vdo volume.
The modifications will take effect when the device is next resumed. The
modifiable parameters are <logical device size>, <physical device size>,
<maxDiscard>, <compression>, and <deduplication>.
If the logical device size or physical device size are changed, upon
successful resume vdo will store the new values and require them on future
startups. These two parameters may not be decreased. The logical device
size may not exceed 4 PB. The physical device size must increase by at
least 32832 4096-byte blocks if at all, and must not exceed the size of the
underlying storage device. Additionally, when formatting the vdo device, a
slab size is chosen: the physical device size may never increase above the
size which provides 8192 slabs, and each increase must be large enough to
add at least one new slab.
Examples:
Start a previously-formatted vdo volume with 1 GB logical space and 1 GB
physical space, storing to /dev/dm-1 which has more than 1 GB of space.
::
dmsetup create vdo0 --table \
"0 2097152 vdo V4 /dev/dm-1 262144 4096 32768 16380"
Grow the logical size to 4 GB.
::
dmsetup reload vdo0 --table \
"0 8388608 vdo V4 /dev/dm-1 262144 4096 32768 16380"
dmsetup resume vdo0
Grow the physical size to 2 GB.
::
dmsetup reload vdo0 --table \
"0 8388608 vdo V4 /dev/dm-1 524288 4096 32768 16380"
dmsetup resume vdo0
Grow the physical size by 1 GB more and increase max discard sectors.
::
dmsetup reload vdo0 --table \
"0 10485760 vdo V4 /dev/dm-1 786432 4096 32768 16380 maxDiscard 8"
dmsetup resume vdo0
Stop the vdo volume.
::
dmsetup remove vdo0
Start the vdo volume again. Note that the logical and physical device sizes
must still match, but other parameters can change.
::
dmsetup create vdo1 --table \
"0 10485760 vdo V4 /dev/dm-1 786432 512 65550 5000 hash 1 logical 3 physical 2"
Messages
--------
All vdo devices accept messages in the form:
::
dmsetup message <target-name> 0 <message-name> <message-parameters>
The messages are:
stats:
Outputs the current view of the vdo statistics. Mostly used
by the vdostats userspace program to interpret the output
buffer.
dump:
Dumps many internal structures to the system log. This is
not always safe to run, so it should only be used to debug
a hung vdo. Optional parameters to specify structures to
dump are:
viopool: The pool of I/O requests incoming bios
pools: A synonym of 'viopool'
vdo: Most of the structures managing on-disk data
queues: Basic information about each vdo thread
threads: A synonym of 'queues'
default: Equivalent to 'queues vdo'
all: All of the above.
dump-on-shutdown:
Perform a default dump next time vdo shuts down.
Status
------
::
<device> <operating mode> <in recovery> <index state>
<compression state> <physical blocks used> <total physical blocks>
device:
The name of the vdo volume.
operating mode:
The current operating mode of the vdo volume; values may be
'normal', 'recovering' (the volume has detected an issue
with its metadata and is attempting to repair itself), and
'read-only' (an error has occurred that forces the vdo
volume to only support read operations and not writes).
in recovery:
Whether the vdo volume is currently in recovery mode;
values may be 'recovering' or '-' which indicates not
recovering.
index state:
The current state of the deduplication index in the vdo
volume; values may be 'closed', 'closing', 'error',
'offline', 'online', 'opening', and 'unknown'.
compression state:
The current state of compression in the vdo volume; values
may be 'offline' and 'online'.
used physical blocks:
The number of physical blocks in use by the vdo volume.
total physical blocks:
The total number of physical blocks the vdo volume may use;
the difference between this value and the
<used physical blocks> is the number of blocks the vdo
volume has left before being full.
Memory Requirements
===================
A vdo target requires a fixed 38 MB of RAM along with the following amounts
that scale with the target:
- 1.15 MB of RAM for each 1 MB of configured block map cache size. The
block map cache requires a minimum of 150 MB.
- 1.6 MB of RAM for each 1 TB of logical space.
- 268 MB of RAM for each 1 TB of physical storage managed by the volume.
The deduplication index requires additional memory which scales with the
size of the deduplication window. For dense indexes, the index requires 1
GB of RAM per 1 TB of window. For sparse indexes, the index requires 1 GB
of RAM per 10 TB of window. The index configuration is set when the target
is formatted and may not be modified.
Module Parameters
=================
The vdo driver has a numeric parameter 'log_level' which controls the
verbosity of logging from the driver. The default setting is 6
(LOGLEVEL_INFO and more severe messages).
Run-time Usage
==============
When using dm-vdo, it is important to be aware of the ways in which its
behavior differs from other storage targets.
- There is no guarantee that over-writes of existing blocks will succeed.
Because the underlying storage may be multiply referenced, over-writing
an existing block generally requires a vdo to have a free block
available.
- When blocks are no longer in use, sending a discard request for those
blocks lets the vdo release references for those blocks. If the vdo is
thinly provisioned, discarding unused blocks is essential to prevent the
target from running out of space. However, due to the sharing of
duplicate blocks, no discard request for any given logical block is
guaranteed to reclaim space.
- Assuming the underlying storage properly implements flush requests, vdo
is resilient against crashes, however, unflushed writes may or may not
persist after a crash.
- Each write to a vdo target entails a significant amount of processing.
However, much of the work is paralellizable. Therefore, vdo targets
achieve better throughput at higher I/O depths, and can support up 2048
requests in parallel.
Tuning
======
The vdo device has many options, and it can be difficult to make optimal
choices without perfect knowledge of the workload. Additionally, most
configuration options must be set when a vdo target is started, and cannot
be changed without shutting it down completely; the configuration cannot be
changed while the target is active. Ideally, tuning with simulated
workloads should be performed before deploying vdo in production
environments.
The most important value to adjust is the block map cache size. In order to
service a request for any logical address, a vdo must load the portion of
the block map which holds the relevant mapping. These mappings are cached.
Performance will suffer when the working set does not fit in the cache. By
default, a vdo allocates 128 MB of metadata cache in RAM to support
efficient access to 100 GB of logical space at a time. It should be scaled
up proportionally for larger working sets.
The logical and physical thread counts should also be adjusted. A logical
thread controls a disjoint section of the block map, so additional logical
threads increase parallelism and can increase throughput. Physical threads
control a disjoint section of the data blocks, so additional physical
threads can also increase throughput. However, excess threads can waste
resources and increase contention.
Bio submission threads control the parallelism involved in sending I/O to
the underlying storage; fewer threads mean there is more opportunity to
reorder I/O requests for performance benefit, but also that each I/O
request has to wait longer before being submitted.
Bio acknowledgment threads are used for finishing I/O requests. This is
done on dedicated threads since the amount of work required to execute a
bio's callback can not be controlled by the vdo itself. Usually one thread
is sufficient but additional threads may be beneficial, particularly when
bios have CPU-heavy callbacks.
CPU threads are used for hashing and for compression; in workloads with
compression enabled, more threads may result in higher throughput.
Hash threads are used to sort active requests by hash and determine whether
they should deduplicate; the most CPU intensive actions done by these
threads are comparison of 4096-byte data blocks. In most cases, a single
hash thread is sufficient.
Documentation/admin-guide/gpio/gpio-mockup.rst
+8
View File
@@ -3,6 +3,14 @@
GPIO Testing Driver
===================
.. note::
This module has been obsoleted by the more flexible gpio-sim.rst.
New developments should use that API and existing developments are
encouraged to migrate as soon as possible.
This module will continue to be maintained but no new features will be
added.
The GPIO Testing Driver (gpio-mockup) 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
Documentation/admin-guide/gpio/index.rst
+3 -3
View File
@@ -1,16 +1,16 @@
.. SPDX-License-Identifier: GPL-2.0
====
gpio
GPIO
====
.. toctree::
:maxdepth: 1
Character Device Userspace API <../../userspace-api/gpio/chardev>
gpio-aggregator
sysfs
gpio-mockup
gpio-sim
Obsolete APIs <obsolete>
.. only:: subproject and html
Documentation/admin-guide/gpio/obsolete.rst
+13
View File
@@ -0,0 +1,13 @@
.. SPDX-License-Identifier: GPL-2.0
==================
Obsolete GPIO APIs
==================
.. toctree::
:maxdepth: 1
Character Device Userspace API (v1) <../../userspace-api/gpio/chardev_v1>
Sysfs Interface <../../userspace-api/gpio/sysfs>
Mockup Testing Module <gpio-mockup>
Documentation/admin-guide/kernel-parameters.txt
+50 -45
View File
@@ -374,6 +374,11 @@
selects a performance level in this range and appropriate
to the current workload.
amd_prefcore=
[X86]
disable
Disable amd-pstate preferred core.
amijoy.map= [HW,JOY] Amiga joystick support
Map of devices attached to JOY0DAT and JOY1DAT
Format: <a>,<b>
@@ -1760,6 +1765,17 @@
(that will set all pages holding image data
during restoration read-only).
hibernate.compressor= [HIBERNATION] Compression algorithm to be
used with hibernation.
Format: { lzo | lz4 }
Default: lzo
lzo: Select LZO compression algorithm to
compress/decompress hibernation image.
lz4: Select LZ4 compression algorithm to
compress/decompress hibernation image.
highmem=nn[KMG] [KNL,BOOT,EARLY] forces the highmem zone to have an exact
size of <nn>. This works even on boxes that have no
highmem otherwise. This also works to reduce highmem
@@ -3775,10 +3791,6 @@
no5lvl [X86-64,RISCV,EARLY] Disable 5-level paging mode. Forces
kernel to use 4-level paging instead.
noaliencache [MM, NUMA, SLAB] Disables the allocation of alien
caches in the slab allocator. Saves per-node memory,
but will impact performance.
noalign [KNL,ARM]
noaltinstr [S390,EARLY] Disables alternative instructions
@@ -5949,11 +5961,42 @@
simeth= [IA-64]
simscsi=
slram= [HW,MTD]
slab_debug[=options[,slabs][;[options[,slabs]]...] [MM]
Enabling slab_debug allows one to determine the
culprit if slab objects become corrupted. Enabling
slab_debug can create guard zones around objects and
may poison objects when not in use. Also tracks the
last alloc / free. For more information see
Documentation/mm/slub.rst.
(slub_debug legacy name also accepted for now)
slab_max_order= [MM]
Determines the maximum allowed order for slabs.
A high setting may cause OOMs due to memory
fragmentation. For more information see
Documentation/mm/slub.rst.
(slub_max_order legacy name also accepted for now)
slab_merge [MM]
Enable merging of slabs with similar size when the
kernel is built without CONFIG_SLAB_MERGE_DEFAULT.
(slub_merge legacy name also accepted for now)
slab_min_objects= [MM]
The minimum number of objects per slab. SLUB will
increase the slab order up to slab_max_order to
generate a sufficiently large slab able to contain
the number of objects indicated. The higher the number
of objects the smaller the overhead of tracking slabs
and the less frequently locks need to be acquired.
For more information see Documentation/mm/slub.rst.
(slub_min_objects legacy name also accepted for now)
slab_min_order= [MM]
Determines the minimum page order for slabs. Must be
lower or equal to slab_max_order. For more information see
Documentation/mm/slub.rst.
(slub_min_order legacy name also accepted for now)
slab_nomerge [MM]
Disable merging of slabs with similar size. May be
@@ -5967,47 +6010,9 @@
unchanged). Debug options disable merging on their
own.
For more information see Documentation/mm/slub.rst.
(slub_nomerge legacy name also accepted for now)
slab_max_order= [MM, SLAB]
Determines the maximum allowed order for slabs.
A high setting may cause OOMs due to memory
fragmentation. Defaults to 1 for systems with
more than 32MB of RAM, 0 otherwise.
slub_debug[=options[,slabs][;[options[,slabs]]...] [MM, SLUB]
Enabling slub_debug allows one to determine the
culprit if slab objects become corrupted. Enabling
slub_debug can create guard zones around objects and
may poison objects when not in use. Also tracks the
last alloc / free. For more information see
Documentation/mm/slub.rst.
slub_max_order= [MM, SLUB]
Determines the maximum allowed order for slabs.
A high setting may cause OOMs due to memory
fragmentation. For more information see
Documentation/mm/slub.rst.
slub_min_objects= [MM, SLUB]
The minimum number of objects per slab. SLUB will
increase the slab order up to slub_max_order to
generate a sufficiently large slab able to contain
the number of objects indicated. The higher the number
of objects the smaller the overhead of tracking slabs
and the less frequently locks need to be acquired.
For more information see Documentation/mm/slub.rst.
slub_min_order= [MM, SLUB]
Determines the minimum page order for slabs. Must be
lower than slub_max_order.
For more information see Documentation/mm/slub.rst.
slub_merge [MM, SLUB]
Same with slab_merge.
slub_nomerge [MM, SLUB]
Same with slab_nomerge. This is supported for legacy.
See slab_nomerge for more information.
slram= [HW,MTD]
smart2= [HW]
Format: <io1>[,<io2>[,...,<io8>]]
Documentation/admin-guide/pm/amd-pstate.rst
+57 -2
View File
@@ -300,8 +300,8 @@ platforms. The AMD P-States mechanism is the more performance and energy
efficiency frequency management method on AMD processors.
AMD Pstate Driver Operation Modes
=================================
``amd-pstate`` Driver Operation Modes
======================================
``amd_pstate`` CPPC has 3 operation modes: autonomous (active) mode,
non-autonomous (passive) mode and guided autonomous (guided) mode.
@@ -353,6 +353,48 @@ is activated. In this mode, driver requests minimum and maximum performance
level and the platform autonomously selects a performance level in this range
and appropriate to the current workload.
``amd-pstate`` Preferred Core
=================================
The core frequency is subjected to the process variation in semiconductors.
Not all cores are able to reach the maximum frequency respecting the
infrastructure limits. Consequently, AMD has redefined the concept of
maximum frequency of a part. This means that a fraction of cores can reach
maximum frequency. To find the best process scheduling policy for a given
scenario, OS needs to know the core ordering informed by the platform through
highest performance capability register of the CPPC interface.
``amd-pstate`` preferred core enables the scheduler to prefer scheduling on
cores that can achieve a higher frequency with lower voltage. The preferred
core rankings can dynamically change based on the workload, platform conditions,
thermals and ageing.
The priority metric will be initialized by the ``amd-pstate`` driver. The ``amd-pstate``
driver will also determine whether or not ``amd-pstate`` preferred core is
supported by the platform.
``amd-pstate`` driver will provide an initial core ordering when the system boots.
The platform uses the CPPC interfaces to communicate the core ranking to the
operating system and scheduler to make sure that OS is choosing the cores
with highest performance firstly for scheduling the process. When ``amd-pstate``
driver receives a message with the highest performance change, it will
update the core ranking and set the cpu's priority.
``amd-pstate`` Preferred Core Switch
=====================================
Kernel Parameters
-----------------
``amd-pstate`` peferred core`` has two states: enable and disable.
Enable/disable states can be chosen by different kernel parameters.
Default enable ``amd-pstate`` preferred core.
``amd_prefcore=disable``
For systems that support ``amd-pstate`` preferred core, the core rankings will
always be advertised by the platform. But OS can choose to ignore that via the
kernel parameter ``amd_prefcore=disable``.
User Space Interface in ``sysfs`` - General
===========================================
@@ -385,6 +427,19 @@ control its functionality at the system level. They are located in the
to the operation mode represented by that string - or to be
unregistered in the "disable" case.
``prefcore``
Preferred core state of the driver: "enabled" or "disabled".
"enabled"
Enable the ``amd-pstate`` preferred core.
"disabled"
Disable the ``amd-pstate`` preferred core
This attribute is read-only to check the state of preferred core set
by the kernel parameter.
``cpupower`` tool support for ``amd-pstate``
===============================================
Documentation/devicetree/bindings/ata/ahci-mtk.txt
-51
View File
@@ -1,51 +0,0 @@
MediaTek Serial ATA controller
Required properties:
- compatible : Must be "mediatek,<chip>-ahci", "mediatek,mtk-ahci".
When using "mediatek,mtk-ahci" compatible strings, you
need SoC specific ones in addition, one of:
- "mediatek,mt7622-ahci"
- reg : Physical base addresses and length of register sets.
- interrupts : Interrupt associated with the SATA device.
- interrupt-names : Associated name must be: "hostc".
- clocks : A list of phandle and clock specifier pairs, one for each
entry in clock-names.
- clock-names : Associated names must be: "ahb", "axi", "asic", "rbc", "pm".
- phys : A phandle and PHY specifier pair for the PHY port.
- phy-names : Associated name must be: "sata-phy".
- ports-implemented : See ./ahci-platform.txt for details.
Optional properties:
- power-domains : A phandle and power domain specifier pair to the power
domain which is responsible for collapsing and restoring
power to the peripheral.
- resets : Must contain an entry for each entry in reset-names.
See ../reset/reset.txt for details.
- reset-names : Associated names must be: "axi", "sw", "reg".
- mediatek,phy-mode : A phandle to the system controller, used to enable
SATA function.
Example:
sata: sata@1a200000 {
compatible = "mediatek,mt7622-ahci",
"mediatek,mtk-ahci";
reg = <0 0x1a200000 0 0x1100>;
interrupts = <GIC_SPI 233 IRQ_TYPE_LEVEL_HIGH>;
interrupt-names = "hostc";
clocks = <&pciesys CLK_SATA_AHB_EN>,
<&pciesys CLK_SATA_AXI_EN>,
<&pciesys CLK_SATA_ASIC_EN>,
<&pciesys CLK_SATA_RBC_EN>,
<&pciesys CLK_SATA_PM_EN>;
clock-names = "ahb", "axi", "asic", "rbc", "pm";
phys = <&u3port1 PHY_TYPE_SATA>;
phy-names = "sata-phy";
ports-implemented = <0x1>;
power-domains = <&scpsys MT7622_POWER_DOMAIN_HIF0>;
resets = <&pciesys MT7622_SATA_AXI_BUS_RST>,
<&pciesys MT7622_SATA_PHY_SW_RST>,
<&pciesys MT7622_SATA_PHY_REG_RST>;
reset-names = "axi", "sw", "reg";
mediatek,phy-mode = <&pciesys>;
};
Documentation/devicetree/bindings/ata/atmel-at91_cf.txt
-19
View File
@@ -1,19 +0,0 @@
Atmel AT91RM9200 CompactFlash
Required properties:
- compatible : "atmel,at91rm9200-cf".
- reg : should specify localbus address and size used.
- gpios : specifies the gpio pins to control the CF device. Detect
and reset gpio's are mandatory while irq and vcc gpio's are
optional and may be set to 0 if not present.
Example:
compact-flash@50000000 {
compatible = "atmel,at91rm9200-cf";
reg = <0x50000000 0x30000000>;
gpios = <&pioC 13 0 /* irq */
&pioC 15 0 /* detect */
0 /* vcc */
&pioC 5 0 /* reset */
>;
};
Documentation/devicetree/bindings/ata/mediatek,mtk-ahci.yaml
+98
View File
@@ -0,0 +1,98 @@
# SPDX-License-Identifier: GPL-2.0-only OR BSD-2-Clause
%YAML 1.2
---
$id: http://devicetree.org/schemas/ata/mediatek,mtk-ahci.yaml#
$schema: http://devicetree.org/meta-schemas/core.yaml#
title: MediaTek Serial ATA controller
maintainers:
- Ryder Lee <ryder.lee@mediatek.com>
allOf:
- $ref: ahci-common.yaml#
properties:
compatible:
items:
- enum:
- mediatek,mt7622-ahci
- const: mediatek,mtk-ahci
reg:
maxItems: 1
interrupts:
maxItems: 1
interrupt-names:
const: hostc
clocks:
maxItems: 5
clock-names:
items:
- const: ahb
- const: axi
- const: asic
- const: rbc
- const: pm
power-domains:
maxItems: 1
resets:
maxItems: 3
reset-names:
items:
- const: axi
- const: sw
- const: reg
mediatek,phy-mode:
description: System controller phandle, used to enable SATA function
$ref: /schemas/types.yaml#/definitions/phandle
required:
- reg
- interrupts
- interrupt-names
- clocks
- clock-names
- phys
- phy-names
- ports-implemented
unevaluatedProperties: false
examples:
- |
#include <dt-bindings/clock/mt7622-clk.h>
#include <dt-bindings/interrupt-controller/arm-gic.h>
#include <dt-bindings/phy/phy.h>
#include <dt-bindings/power/mt7622-power.h>
#include <dt-bindings/reset/mt7622-reset.h>
sata@1a200000 {
compatible = "mediatek,mt7622-ahci", "mediatek,mtk-ahci";
reg = <0x1a200000 0x1100>;
interrupts = <GIC_SPI 233 IRQ_TYPE_LEVEL_HIGH>;
interrupt-names = "hostc";
clocks = <&pciesys CLK_SATA_AHB_EN>,
<&pciesys CLK_SATA_AXI_EN>,
<&pciesys CLK_SATA_ASIC_EN>,
<&pciesys CLK_SATA_RBC_EN>,
<&pciesys CLK_SATA_PM_EN>;
clock-names = "ahb", "axi", "asic", "rbc", "pm";
phys = <&u3port1 PHY_TYPE_SATA>;
phy-names = "sata-phy";
ports-implemented = <0x1>;
power-domains = <&scpsys MT7622_POWER_DOMAIN_HIF0>;
resets = <&pciesys MT7622_SATA_AXI_BUS_RST>,
<&pciesys MT7622_SATA_PHY_SW_RST>,
<&pciesys MT7622_SATA_PHY_REG_RST>;
reset-names = "axi", "sw", "reg";
mediatek,phy-mode = <&pciesys>;
};
Documentation/devicetree/bindings/gpio/aspeed,ast2400-gpio.yaml
+148
View File
@@ -0,0 +1,148 @@
# SPDX-License-Identifier: (GPL-2.0 OR BSD-2-Clause)
%YAML 1.2
---
$id: http://devicetree.org/schemas/gpio/aspeed,ast2400-gpio.yaml#
$schema: http://devicetree.org/meta-schemas/core.yaml#
title: Aspeed GPIO controller
maintainers:
- Andrew Jeffery <andrew@codeconstruct.com.au>
properties:
compatible:
enum:
- aspeed,ast2400-gpio
- aspeed,ast2500-gpio
- aspeed,ast2600-gpio
reg:
maxItems: 1
clocks:
maxItems: 1
description: The clock to use for debounce timings
gpio-controller: true
gpio-line-names:
minItems: 36
maxItems: 232
gpio-ranges: true
"#gpio-cells":
const: 2
interrupts:
maxItems: 1
interrupt-controller: true
"#interrupt-cells":
const: 2
ngpios:
minimum: 36
maximum: 232
required:
- compatible
- reg
- interrupts
- interrupt-controller
- "#interrupt-cells"
- gpio-controller
- "#gpio-cells"
allOf:
- if:
properties:
compatible:
contains:
const: aspeed,ast2400-gpio
then:
properties:
gpio-line-names:
minItems: 220
maxItems: 220
ngpios:
const: 220
- if:
properties:
compatible:
contains:
const: aspeed,ast2500-gpio
then:
properties:
gpio-line-names:
minItems: 232
maxItems: 232
ngpios:
const: 232
- if:
properties:
compatible:
contains:
const: aspeed,ast2600-gpio
then:
properties:
gpio-line-names:
minItems: 36
maxItems: 208
ngpios:
enum: [ 36, 208 ]
required:
- ngpios
additionalProperties: false
examples:
- |
gpio@1e780000 {
compatible = "aspeed,ast2400-gpio";
reg = <0x1e780000 0x1000>;
interrupts = <20>;
interrupt-controller;
#interrupt-cells = <2>;
gpio-controller;
#gpio-cells = <2>;
};
- |
gpio: gpio@1e780000 {
compatible = "aspeed,ast2500-gpio";
reg = <0x1e780000 0x200>;
interrupts = <20>;
interrupt-controller;
#interrupt-cells = <2>;
gpio-controller;
#gpio-cells = <2>;
gpio-ranges = <&pinctrl 0 0 232>;
};
- |
#include <dt-bindings/clock/ast2600-clock.h>
#include <dt-bindings/interrupt-controller/arm-gic.h>
#include <dt-bindings/interrupt-controller/irq.h>
gpio0: gpio@1e780000 {
compatible = "aspeed,ast2600-gpio";
reg = <0x1e780000 0x400>;
clocks = <&syscon ASPEED_CLK_APB2>;
interrupts = <GIC_SPI 40 IRQ_TYPE_LEVEL_HIGH>;
interrupt-controller;
#interrupt-cells = <2>;
#gpio-cells = <2>;
gpio-controller;
gpio-ranges = <&pinctrl 0 0 208>;
ngpios = <208>;
};
gpio1: gpio@1e780800 {
compatible = "aspeed,ast2600-gpio";
reg = <0x1e780800 0x800>;
clocks = <&syscon ASPEED_CLK_APB1>;
interrupts = <GIC_SPI 11 IRQ_TYPE_LEVEL_HIGH>;
interrupt-controller;
#interrupt-cells = <2>;
gpio-controller;
#gpio-cells = <2>;
gpio-ranges = <&pinctrl 0 208 36>;
ngpios = <36>;
};
Documentation/devicetree/bindings/gpio/gpio-aspeed.txt
-39
View File
@@ -1,39 +0,0 @@
Aspeed GPIO controller Device Tree Bindings
-------------------------------------------
Required properties:
- compatible : Either "aspeed,ast2400-gpio", "aspeed,ast2500-gpio",
or "aspeed,ast2600-gpio".
- #gpio-cells : Should be two
- First cell is the GPIO line number
- Second cell is used to specify optional
parameters (unused)
- reg : Address and length of the register set for the device
- gpio-controller : Marks the device node as a GPIO controller.
- interrupts : Interrupt specifier (see interrupt bindings for
details)
- interrupt-controller : Mark the GPIO controller as an interrupt-controller
Optional properties:
- clocks : A phandle to the clock to use for debounce timings
- ngpios : Number of GPIOs controlled by this controller. Should be set
when there are multiple GPIO controllers on a SoC (ast2600).
The gpio and interrupt properties are further described in their respective
bindings documentation:
- Documentation/devicetree/bindings/gpio/gpio.txt
- Documentation/devicetree/bindings/interrupt-controller/interrupts.txt
Example:
gpio@1e780000 {
#gpio-cells = <2>;
compatible = "aspeed,ast2400-gpio";
gpio-controller;
interrupts = <20>;
reg = <0x1e780000 0x1000>;
interrupt-controller;
};
Documentation/devicetree/bindings/gpio/gpio-mvebu.yaml
+1 -1
View File
@@ -115,7 +115,7 @@ allOf:
required:
- reg
unevaluatedProperties: true
unevaluatedProperties: false
examples:
- |
Documentation/devicetree/bindings/gpio/gpio-pca9570.yaml
+3
View File
@@ -28,6 +28,9 @@ properties:
minItems: 4
maxItems: 8
label:
description: A descriptive name for this device.
required:
- compatible
- reg
Documentation/devicetree/bindings/gpio/renesas,rcar-gpio.yaml
+1
View File
@@ -53,6 +53,7 @@ properties:
- renesas,gpio-r8a779a0 # R-Car V3U
- renesas,gpio-r8a779f0 # R-Car S4-8
- renesas,gpio-r8a779g0 # R-Car V4H
- renesas,gpio-r8a779h0 # R-Car V4M
- const: renesas,rcar-gen4-gpio # R-Car Gen4
reg:
Documentation/devicetree/bindings/hwmon/adi,adm1177.yaml
+4 -1
View File
@@ -46,7 +46,10 @@ required:
- compatible
- reg
additionalProperties: false
allOf:
- $ref: hwmon-common.yaml#
unevaluatedProperties: false
examples:
- |
Documentation/devicetree/bindings/hwmon/adi,adm1275.yaml
+2 -5
View File
@@ -33,10 +33,6 @@ properties:
reg:
maxItems: 1
shunt-resistor-micro-ohms:
description:
Shunt resistor value in micro-Ohm.
adi,volt-curr-sample-average:
description: |
Number of samples to be used to report voltage and current values.
@@ -50,6 +46,7 @@ properties:
enum: [1, 2, 4, 8, 16, 32, 64, 128]
allOf:
- $ref: hwmon-common.yaml#
- if:
properties:
compatible:
@@ -107,7 +104,7 @@ required:
- compatible
- reg
additionalProperties: false
unevaluatedProperties: false
examples:
- |
Documentation/devicetree/bindings/hwmon/adi,ltc2945.yaml
+4 -1
View File
@@ -31,7 +31,10 @@ required:
- compatible
- reg
additionalProperties: false
allOf:
- $ref: hwmon-common.yaml#
unevaluatedProperties: false
examples:
- |
Documentation/devicetree/bindings/hwmon/adi,ltc4282.yaml
+159
View File
@@ -0,0 +1,159 @@
# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
%YAML 1.2
---
$id: http://devicetree.org/schemas/hwmon/adi,ltc4282.yaml#
$schema: http://devicetree.org/meta-schemas/core.yaml#
title: Analog Devices LTC4282 I2C High Current Hot Swap Controller over I2C
maintainers:
- Nuno Sa <nuno.sa@analog.com>
description: |
Analog Devices LTC4282 I2C High Current Hot Swap Controller over I2C.
https://www.analog.com/media/en/technical-documentation/data-sheets/ltc4282.pdf
properties:
compatible:
enum:
- adi,ltc4282
reg:
maxItems: 1
vdd-supply: true
clocks:
maxItems: 1
'#clock-cells':
const: 0
adi,rsense-nano-ohms:
description: Value of the sense resistor.
adi,vin-mode-microvolt:
description:
Selects operating range for the Undervoltage, Overvoltage and Foldback
pins. Also for the ADC. Should be set to the nominal input voltage.
enum: [3300000, 5000000, 12000000, 24000000]
default: 12000000
adi,fet-bad-timeout-ms:
description:
From the moment a FET bad conditions is present, this property selects the
wait time/timeout for a FET-bad fault to be signaled. Setting this to 0,
disables FET bad faults to be reported.
default: 255
maximum: 255
adi,overvoltage-dividers:
description: |
Select which dividers to use for VDD Overvoltage detection. Note that
when the internal dividers are used the threshold is referenced to VDD.
The percentages in the datasheet are misleading since the actual values
to look for are in the "Absolute Maximum Ratings" table in the
"Comparator Inputs" section. In there there's a line for each of the 5%,
10% and 15% settings with the actual min, typical and max tolerances.
$ref: /schemas/types.yaml#/definitions/string
enum: [external, vdd_5_percent, vdd_10_percent, vdd_15_percent]
default: external
adi,undervoltage-dividers:
description: |
Select which dividers to use for VDD Overvoltage detection. Note that
when the internal dividers are used the threshold is referenced to VDD.
The percentages in the datasheet are misleading since the actual values
to look for are in the "Absolute Maximum Ratings" table in the
"Comparator Inputs" section. In there there's a line for each of the 5%,
10% and 15% settings with the actual min, typical and max tolerances.
$ref: /schemas/types.yaml#/definitions/string
enum: [external, vdd_5_percent, vdd_10_percent, vdd_15_percent]
default: external
adi,current-limit-sense-microvolt:
description:
The current limit sense voltage of the chip is adjustable between
12.5mV and 34.4mV in 3.1mV steps. This effectively limits the current
on the load.
enum: [12500, 15625, 18750, 21875, 25000, 28125, 31250, 34375]
default: 25000
adi,overcurrent-retry:
description:
If set, enables the chip to auto-retry 256 timer cycles after an
Overcurrent fault.
type: boolean
adi,overvoltage-retry-disable:
description:
If set, disables the chip to auto-retry 50ms after an Overvoltage fault.
It's enabled by default.
type: boolean
adi,undervoltage-retry-disable:
description:
If set, disables the chip to auto-retry 50ms after an Undervoltage fault.
It's enabled by default.
type: boolean
adi,fault-log-enable:
description:
If set, enables the FAULT_LOG and ADC_ALERT_LOG registers to be written
to the EEPROM when a fault bit transitions high and hence, will be
available after a power cycle (the chip loads the contents of
the EE_FAULT_LOG register - the one in EEPROM - into FAULT_LOG at boot).
type: boolean
adi,gpio1-mode:
description: Defines the function of the Pin. It can indicate that power is
good (PULL the pin low when power is not good) or that power is bad (Go
into high-z when power is not good).
$ref: /schemas/types.yaml#/definitions/string
enum: [power_bad, power_good]
default: power_good
adi,gpio2-mode:
description: Defines the function of the Pin. It can be set as the input for
the ADC or indicating that the MOSFET is in stress (dissipating power).
$ref: /schemas/types.yaml#/definitions/string
enum: [adc_input, stress_fet]
default: adc_input
adi,gpio3-monitor-enable:
description: If set, gpio3 is set as input for the ADC instead of gpio2.
type: boolean
allOf:
- if:
required:
- adi,gpio3-monitor-enable
then:
properties:
adi,gpio2-mode:
const: stress_fet
required:
- compatible
- reg
- adi,rsense-nano-ohms
additionalProperties: false
examples:
- |
i2c {
#address-cells = <1>;
#size-cells = <0>;
hwmon@50 {
compatible = "adi,ltc4282";
reg = <0x50>;
adi,rsense-nano-ohms = <500>;
adi,gpio1-mode = "power_good";
adi,gpio2-mode = "adc_input";
};
};
...
Documentation/devicetree/bindings/hwmon/amphenol,chipcap2.yaml
+77
View File
@@ -0,0 +1,77 @@
# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
%YAML 1.2
---
$id: http://devicetree.org/schemas/hwmon/amphenol,chipcap2.yaml#
$schema: http://devicetree.org/meta-schemas/core.yaml#
title: ChipCap 2 humidity and temperature iio sensor
maintainers:
- Javier Carrasco <javier.carrasco.cruz@gmail.com>
description: |
Relative humidity and temperature sensor on I2C bus.
Datasheets:
https://www.amphenol-sensors.com/en/telaire/humidity/527-humidity-sensors/3095-chipcap-2
properties:
compatible:
oneOf:
- const: amphenol,cc2d23
- items:
- enum:
- amphenol,cc2d23s
- amphenol,cc2d25
- amphenol,cc2d25s
- amphenol,cc2d33
- amphenol,cc2d33s
- amphenol,cc2d35
- amphenol,cc2d35s
- const: amphenol,cc2d23
reg:
maxItems: 1
interrupts:
items:
- description: measurement ready indicator
- description: low humidity alarm
- description: high humidity alarm
interrupt-names:
items:
- const: ready
- const: low
- const: high
vdd-supply:
description:
Dedicated, controllable supply-regulator to reset the device and
enter in command mode.
required:
- compatible
- reg
- vdd-supply
additionalProperties: false
examples:
- |
#include <dt-bindings/interrupt-controller/irq.h>
i2c {
#address-cells = <1>;
#size-cells = <0>;
humidity@28 {
compatible = "amphenol,cc2d23s", "amphenol,cc2d23";
reg = <0x28>;
interrupt-parent = <&gpio>;
interrupts = <4 IRQ_TYPE_EDGE_RISING>,
<5 IRQ_TYPE_EDGE_RISING>,
<6 IRQ_TYPE_EDGE_RISING>;
interrupt-names = "ready", "low", "high";
vdd-supply = <&reg_vdd>;
};
};
Documentation/devicetree/bindings/hwmon/aspeed,g6-pwm-tach.yaml
+71
View File
@@ -0,0 +1,71 @@
# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
# Copyright (C) 2023 Aspeed, Inc.
%YAML 1.2
---
$id: http://devicetree.org/schemas/hwmon/aspeed,g6-pwm-tach.yaml#
$schema: http://devicetree.org/meta-schemas/core.yaml#
title: ASPEED G6 PWM and Fan Tach controller
maintainers:
- Billy Tsai <billy_tsai@aspeedtech.com>
description: |
The ASPEED PWM controller can support up to 16 PWM outputs.
The ASPEED Fan Tacho controller can support up to 16 fan tach input.
They are independent hardware blocks, which are different from the
previous version of the ASPEED chip.
properties:
compatible:
enum:
- aspeed,ast2600-pwm-tach
reg:
maxItems: 1
clocks:
maxItems: 1
resets:
maxItems: 1
"#pwm-cells":
const: 3
patternProperties:
"^fan-[0-9]+$":
$ref: fan-common.yaml#
unevaluatedProperties: false
required:
- tach-ch
required:
- reg
- clocks
- resets
- "#pwm-cells"
- compatible
additionalProperties: false
examples:
- |
#include <dt-bindings/clock/aspeed-clock.h>
pwm_tach: pwm-tach-controller@1e610000 {
compatible = "aspeed,ast2600-pwm-tach";
reg = <0x1e610000 0x100>;
clocks = <&syscon ASPEED_CLK_AHB>;
resets = <&syscon ASPEED_RESET_PWM>;
#pwm-cells = <3>;
fan-0 {
tach-ch = /bits/ 8 <0x0>;
pwms = <&pwm_tach 0 40000 0>;
};
fan-1 {
tach-ch = /bits/ 8 <0x1 0x2>;
pwms = <&pwm_tach 1 40000 0>;
};
};
Documentation/devicetree/bindings/hwmon/fan-common.yaml
+79
View File
@@ -0,0 +1,79 @@
# SPDX-License-Identifier: GPL-2.0-only OR BSD-2-Clause
%YAML 1.2
---
$id: http://devicetree.org/schemas/hwmon/fan-common.yaml#
$schema: http://devicetree.org/meta-schemas/core.yaml#
title: Common Fan Properties
maintainers:
- Naresh Solanki <naresh.solanki@9elements.com>
- Billy Tsai <billy_tsai@aspeedtech.com>
properties:
max-rpm:
description:
Max RPM supported by fan.
$ref: /schemas/types.yaml#/definitions/uint32
maximum: 100000
min-rpm:
description:
Min RPM supported by fan.
$ref: /schemas/types.yaml#/definitions/uint32
maximum: 1000
pulses-per-revolution:
description:
The number of pulse from fan sensor per revolution.
$ref: /schemas/types.yaml#/definitions/uint32
maximum: 4
tach-div:
description:
Divisor for the tach sampling clock, which determines the sensitivity of the tach pin.
$ref: /schemas/types.yaml#/definitions/uint32
target-rpm:
description:
The default desired fan speed in RPM.
$ref: /schemas/types.yaml#/definitions/uint32
fan-driving-mode:
description:
Select the driving mode of the fan.(DC, PWM and so on)
$ref: /schemas/types.yaml#/definitions/string
enum: [ dc, pwm ]
pwms:
description:
PWM provider.
maxItems: 1
"#cooling-cells":
const: 2
cooling-levels:
description:
The control value which correspond to thermal cooling states.
$ref: /schemas/types.yaml#/definitions/uint32-array
tach-ch:
description:
The tach channel used for the fan.
$ref: /schemas/types.yaml#/definitions/uint8-array
label:
description:
Optional fan label
fan-supply:
description:
Power supply for fan.
reg:
maxItems: 1
additionalProperties: true
...
Documentation/devicetree/bindings/hwmon/hwmon-common.yaml
+19
View File
@@ -0,0 +1,19 @@
# SPDX-License-Identifier: GPL-2.0 OR BSD-2-Clause
%YAML 1.2
---
$id: http://devicetree.org/schemas/hwmon/hwmon-common.yaml#
$schema: http://devicetree.org/meta-schemas/core.yaml#
title: Hardware Monitoring Devices Common Properties
maintainers:
- Guenter Roeck <linux@roeck-us.net>
properties:
label:
description: A descriptive name for this device.
shunt-resistor-micro-ohms:
description: The value of current sense resistor.
additionalProperties: true
Documentation/devicetree/bindings/hwmon/lltc,ltc4151.yaml
+4 -1
View File
@@ -25,7 +25,10 @@ required:
- compatible
- reg
additionalProperties: false
allOf:
- $ref: hwmon-common.yaml#
unevaluatedProperties: false
examples:
- |
Documentation/devicetree/bindings/hwmon/lltc,ltc4286.yaml
+4 -5
View File
@@ -25,15 +25,14 @@ properties:
The default is 102.4 volts.
type: boolean
shunt-resistor-micro-ohms:
description:
Resistor value micro-ohms.
required:
- compatible
- reg
additionalProperties: false
allOf:
- $ref: hwmon-common.yaml#
unevaluatedProperties: false
examples:
- |
Documentation/devicetree/bindings/hwmon/lm75.yaml
+2 -1
View File
@@ -57,6 +57,7 @@ required:
- reg
allOf:
- $ref: hwmon-common.yaml#
- if:
not:
properties:
@@ -71,7 +72,7 @@ allOf:
properties:
interrupts: false
additionalProperties: false
unevaluatedProperties: false
examples:
- |
Documentation/devicetree/bindings/hwmon/nuvoton,nct6775.yaml
+1
View File
@@ -25,6 +25,7 @@ properties:
- nuvoton,nct6796
- nuvoton,nct6797
- nuvoton,nct6798
- nuvoton,nct6799
reg:
maxItems: 1
Documentation/devicetree/bindings/hwmon/pmbus/infineon,tda38640.yaml
+28
View File
@@ -30,6 +30,23 @@ properties:
unconnected(has internal pull-down).
type: boolean
interrupts:
maxItems: 1
regulators:
type: object
description:
list of regulators provided by this controller.
properties:
vout:
$ref: /schemas/regulator/regulator.yaml#
type: object
unevaluatedProperties: false
additionalProperties: false
required:
- compatible
- reg
@@ -38,6 +55,7 @@ additionalProperties: false
examples:
- |
#include <dt-bindings/interrupt-controller/irq.h>
i2c {
#address-cells = <1>;
#size-cells = <0>;
@@ -45,5 +63,15 @@ examples:
tda38640@40 {
compatible = "infineon,tda38640";
reg = <0x40>;
interrupt-parent = <&smb_pex_cpu0_event>;
interrupts = <10 IRQ_TYPE_LEVEL_LOW>;
regulators {
pvnn_main_cpu0: vout {
regulator-name = "pvnn_main_cpu0";
regulator-enable-ramp-delay = <200>;
};
};
};
};
Documentation/devicetree/bindings/hwmon/pmbus/ti,lm25066.yaml
+16 -1
View File
@@ -34,11 +34,26 @@ properties:
Shunt (sense) resistor value in micro-Ohms
default: 1000
regulators:
type: object
properties:
vout:
$ref: /schemas/regulator/regulator.yaml#
type: object
unevaluatedProperties: false
additionalProperties: false
required:
- compatible
- reg
additionalProperties: false
allOf:
- $ref: /schemas/hwmon/hwmon-common.yaml#
unevaluatedProperties: false
examples:
- |
Documentation/devicetree/bindings/hwmon/ti,ina2xx.yaml
+10 -1
View File
@@ -28,10 +28,14 @@ properties:
- ti,ina231
- ti,ina237
- ti,ina238
- ti,ina260
reg:
maxItems: 1
"#io-channel-cells":
const: 1
shunt-resistor:
description:
Shunt resistor value in micro-Ohm.
@@ -66,7 +70,10 @@ required:
- compatible
- reg
additionalProperties: false
allOf:
- $ref: hwmon-common.yaml#
unevaluatedProperties: false
examples:
- |
@@ -77,6 +84,8 @@ examples:
power-sensor@44 {
compatible = "ti,ina220";
reg = <0x44>;
#io-channel-cells = <1>;
label = "vdd_3v0";
shunt-resistor = <1000>;
vs-supply = <&vdd_3v0>;
};
Documentation/devicetree/bindings/hwmon/ti,tmp513.yaml
+4 -1
View File
@@ -72,7 +72,10 @@ required:
- compatible
- reg
additionalProperties: false
allOf:
- $ref: hwmon-common.yaml#
unevaluatedProperties: false
examples:
- |
Documentation/devicetree/bindings/hwmon/ti,tps23861.yaml
+4 -1
View File
@@ -35,7 +35,10 @@ required:
- compatible
- reg
additionalProperties: false
allOf:
- $ref: hwmon-common.yaml#
unevaluatedProperties: false
examples:
- |
Documentation/devicetree/bindings/iommu/arm,smmu.yaml
+16 -4
View File
@@ -83,6 +83,7 @@ properties:
- description: Qcom Adreno GPUs implementing "qcom,smmu-500" and "arm,mmu-500"
items:
- enum:
- qcom,qcm2290-smmu-500
- qcom,sa8775p-smmu-500
- qcom,sc7280-smmu-500
- qcom,sc8280xp-smmu-500
@@ -93,6 +94,7 @@ properties:
- qcom,sm8350-smmu-500
- qcom,sm8450-smmu-500
- qcom,sm8550-smmu-500
- qcom,sm8650-smmu-500
- const: qcom,adreno-smmu
- const: qcom,smmu-500
- const: arm,mmu-500
@@ -462,6 +464,7 @@ allOf:
compatible:
items:
- enum:
- qcom,qcm2290-smmu-500
- qcom,sm6115-smmu-500
- qcom,sm6125-smmu-500
- const: qcom,adreno-smmu
@@ -484,7 +487,12 @@ allOf:
- if:
properties:
compatible:
const: qcom,sm8450-smmu-500
items:
- const: qcom,sm8450-smmu-500
- const: qcom,adreno-smmu
- const: qcom,smmu-500
- const: arm,mmu-500
then:
properties:
clock-names:
@@ -508,7 +516,13 @@ allOf:
- if:
properties:
compatible:
const: qcom,sm8550-smmu-500
items:
- enum:
- qcom,sm8550-smmu-500
- qcom,sm8650-smmu-500
- const: qcom,adreno-smmu
- const: qcom,smmu-500
- const: arm,mmu-500
then:
properties:
clock-names:
@@ -534,7 +548,6 @@ allOf:
- cavium,smmu-v2
- marvell,ap806-smmu-500
- nvidia,smmu-500
- qcom,qcm2290-smmu-500
- qcom,qdu1000-smmu-500
- qcom,sc7180-smmu-500
- qcom,sc8180x-smmu-500
@@ -544,7 +557,6 @@ allOf:
- qcom,sdx65-smmu-500
- qcom,sm6350-smmu-500
- qcom,sm6375-smmu-500
- qcom,sm8650-smmu-500
- qcom,x1e80100-smmu-500
then:
properties:
Documentation/devicetree/bindings/mmc/fsl-imx-esdhc.yaml
+10 -1
View File
@@ -55,8 +55,9 @@ properties:
- enum:
- fsl,imx8mn-usdhc
- fsl,imx8mp-usdhc
- fsl,imx93-usdhc
- fsl,imx8ulp-usdhc
- fsl,imx93-usdhc
- fsl,imx95-usdhc
- const: fsl,imx8mm-usdhc
- items:
- enum:
@@ -162,6 +163,9 @@ properties:
- const: ahb
- const: per
iommus:
maxItems: 1
power-domains:
maxItems: 1
@@ -173,6 +177,11 @@ properties:
- const: state_100mhz
- const: state_200mhz
- const: sleep
- minItems: 2
items:
- const: default
- const: state_100mhz
- const: sleep
- minItems: 1
items:
- const: default
Documentation/devicetree/bindings/mmc/fsl-imx-mmc.yaml
+12
View File
@@ -24,6 +24,14 @@ properties:
reg:
maxItems: 1
clocks:
maxItems: 2
clock-names:
items:
- const: ipg
- const: per
interrupts:
maxItems: 1
@@ -34,6 +42,8 @@ properties:
const: rx-tx
required:
- clocks
- clock-names
- compatible
- reg
- interrupts
@@ -46,6 +56,8 @@ examples:
compatible = "fsl,imx27-mmc", "fsl,imx21-mmc";
reg = <0x10014000 0x1000>;
interrupts = <11>;
clocks = <&clks 29>, <&clks 60>;
clock-names = "ipg", "per";
dmas = <&dma 7>;
dma-names = "rx-tx";
bus-width = <4>;
Documentation/devicetree/bindings/mmc/hi3798cv200-dw-mshc.txt
-40
View File
@@ -1,40 +0,0 @@
* Hisilicon Hi3798CV200 specific extensions to the Synopsys Designware Mobile
Storage Host Controller
Read synopsys-dw-mshc.txt for more details
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 Hisilicon Hi3798CV200
specific extensions to the Synopsys Designware Mobile Storage Host Controller.
Required Properties:
- compatible: Should contain "hisilicon,hi3798cv200-dw-mshc".
- clocks: A list of phandle + clock-specifier pairs for the clocks listed
in clock-names.
- clock-names: Should contain the following:
"ciu" - The ciu clock described in synopsys-dw-mshc.txt.
"biu" - The biu clock described in synopsys-dw-mshc.txt.
"ciu-sample" - Hi3798CV200 extended phase clock for ciu sampling.
"ciu-drive" - Hi3798CV200 extended phase clock for ciu driving.
Example:
emmc: mmc@9830000 {
compatible = "hisilicon,hi3798cv200-dw-mshc";
reg = <0x9830000 0x10000>;
interrupts = <GIC_SPI 35 IRQ_TYPE_LEVEL_HIGH>;
clocks = <&crg HISTB_MMC_CIU_CLK>,
<&crg HISTB_MMC_BIU_CLK>,
<&crg HISTB_MMC_SAMPLE_CLK>,
<&crg HISTB_MMC_DRV_CLK>;
clock-names = "ciu", "biu", "ciu-sample", "ciu-drive";
fifo-depth = <256>;
clock-frequency = <200000000>;
cap-mmc-highspeed;
mmc-ddr-1_8v;
mmc-hs200-1_8v;
non-removable;
bus-width = <8>;
};
Documentation/devicetree/bindings/mmc/hisilicon,hi3798cv200-dw-mshc.yaml
+97
View File
@@ -0,0 +1,97 @@
# SPDX-License-Identifier: GPL-2.0-only OR BSD-2-Clause
%YAML 1.2
---
$id: http://devicetree.org/schemas/mmc/hisilicon,hi3798cv200-dw-mshc.yaml#
$schema: http://devicetree.org/meta-schemas/core.yaml#
title: Hisilicon HiSTB SoCs specific extensions to the Synopsys DWMMC controller
maintainers:
- Yang Xiwen <forbidden405@outlook.com>
properties:
compatible:
enum:
- hisilicon,hi3798cv200-dw-mshc
- hisilicon,hi3798mv200-dw-mshc
reg:
maxItems: 1
interrupts:
maxItems: 1
clocks:
items:
- description: bus interface unit clock
- description: card interface unit clock
- description: card input sample phase clock
- description: controller output drive phase clock
clock-names:
items:
- const: ciu
- const: biu
- const: ciu-sample
- const: ciu-drive
hisilicon,sap-dll-reg:
$ref: /schemas/types.yaml#/definitions/phandle-array
description: |
DWMMC core on Hi3798MV2x SoCs has a delay-locked-loop(DLL) attached to card data input path.
It is integrated into CRG core on the SoC and has to be controlled during tuning.
items:
- description: A phandle pointed to the CRG syscon node
- description: Sample DLL register offset in CRG address space
required:
- compatible
- reg
- interrupts
- clocks
- clock-names
allOf:
- $ref: synopsys-dw-mshc-common.yaml#
- if:
properties:
compatible:
contains:
const: hisilicon,hi3798mv200-dw-mshc
then:
required:
- hisilicon,sap-dll-reg
else:
properties:
hisilicon,sap-dll-reg: false
unevaluatedProperties: false
examples:
- |
#include <dt-bindings/clock/histb-clock.h>
#include <dt-bindings/interrupt-controller/arm-gic.h>
mmc@9830000 {
compatible = "hisilicon,hi3798cv200-dw-mshc";
reg = <0x9830000 0x10000>;
interrupts = <GIC_SPI 35 IRQ_TYPE_LEVEL_HIGH>;
clocks = <&crg HISTB_MMC_CIU_CLK>,
<&crg HISTB_MMC_BIU_CLK>,
<&crg HISTB_MMC_SAMPLE_CLK>,
<&crg HISTB_MMC_DRV_CLK>;
clock-names = "ciu", "biu", "ciu-sample", "ciu-drive";
resets = <&crg 0xa0 4>;
reset-names = "reset";
pinctrl-names = "default";
pinctrl-0 = <&emmc_pins_1 &emmc_pins_2
&emmc_pins_3 &emmc_pins_4>;
fifo-depth = <256>;
clock-frequency = <200000000>;
cap-mmc-highspeed;
mmc-ddr-1_8v;
mmc-hs200-1_8v;
non-removable;
bus-width = <8>;
};
Documentation/devicetree/bindings/mmc/renesas,sdhi.yaml
+1
View File
@@ -67,6 +67,7 @@ properties:
- renesas,sdhi-r8a779a0 # R-Car V3U
- renesas,sdhi-r8a779f0 # R-Car S4-8
- renesas,sdhi-r8a779g0 # R-Car V4H
- renesas,sdhi-r8a779h0 # R-Car V4M
- const: renesas,rcar-gen4-sdhi # R-Car Gen4
reg:
Documentation/devicetree/bindings/mmc/snps,dwcmshc-sdhci.yaml
+2
View File
@@ -19,6 +19,8 @@ properties:
- rockchip,rk3568-dwcmshc
- rockchip,rk3588-dwcmshc
- snps,dwcmshc-sdhci
- sophgo,cv1800b-dwcmshc
- sophgo,sg2002-dwcmshc
- thead,th1520-dwcmshc
reg:
Documentation/devicetree/bindings/opp/opp-v2-base.yaml
-2
View File
@@ -57,8 +57,6 @@ patternProperties:
specific binding.
minItems: 1
maxItems: 32
items:
maxItems: 1
opp-microvolt:
description: |
Documentation/devicetree/bindings/power/qcom,rpmpd.yaml
+2
View File
@@ -24,6 +24,8 @@ properties:
- qcom,msm8917-rpmpd
- qcom,msm8939-rpmpd
- qcom,msm8953-rpmpd
- qcom,msm8974-rpmpd
- qcom,msm8974pro-pma8084-rpmpd
- qcom,msm8976-rpmpd
- qcom,msm8994-rpmpd
- qcom,msm8996-rpmpd
Documentation/devicetree/bindings/pwm/atmel,hlcdc-pwm.yaml
+35
View File
@@ -0,0 +1,35 @@
# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
%YAML 1.2
---
$id: http://devicetree.org/schemas/pwm/atmel,hlcdc-pwm.yaml#
$schema: http://devicetree.org/meta-schemas/core.yaml#
title: Atmel's HLCDC's PWM controller
maintainers:
- Nicolas Ferre <nicolas.ferre@microchip.com>
- Alexandre Belloni <alexandre.belloni@bootlin.com>
- Claudiu Beznea <claudiu.beznea@tuxon.dev>
description:
The LCDC integrates a Pulse Width Modulation (PWM) Controller. This block
generates the LCD contrast control signal (LCD_PWM) that controls the
display's contrast by software. LCDC_PWM is an 8-bit PWM signal that can be
converted to an analog voltage with a simple passive filter. LCD display
panels have different backlight specifications in terms of minimum/maximum
values for PWM frequency. If the LCDC PWM frequency range does not match the
LCD display panel, it is possible to use the standalone PWM Controller to
drive the backlight.
properties:
compatible:
const: atmel,hlcdc-pwm
"#pwm-cells":
const: 3
required:
- compatible
- "#pwm-cells"
additionalProperties: false
Documentation/devicetree/bindings/pwm/atmel-hlcdc-pwm.txt
-29
View File
@@ -1,29 +0,0 @@
Device-Tree bindings for Atmel's HLCDC (High-end LCD Controller) PWM driver
The Atmel HLCDC PWM is subdevice of the HLCDC MFD device.
See ../mfd/atmel-hlcdc.txt for more details.
Required properties:
- compatible: value should be one of the following:
"atmel,hlcdc-pwm"
- pinctr-names: the pin control state names. Should contain "default".
- pinctrl-0: should contain the pinctrl states described by pinctrl
default.
- #pwm-cells: should be set to 3. This PWM chip use the default 3 cells
bindings defined in pwm.yaml in this directory.
Example:
hlcdc: hlcdc@f0030000 {
compatible = "atmel,sama5d3-hlcdc";
reg = <0xf0030000 0x2000>;
clocks = <&lcdc_clk>, <&lcdck>, <&clk32k>;
clock-names = "periph_clk","sys_clk", "slow_clk";
hlcdc_pwm: hlcdc-pwm {
compatible = "atmel,hlcdc-pwm";
pinctrl-names = "default";
pinctrl-0 = <&pinctrl_lcd_pwm>;
#pwm-cells = <3>;
};
};
Documentation/devicetree/bindings/pwm/marvell,pxa-pwm.yaml
+51
View File
@@ -0,0 +1,51 @@
# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
%YAML 1.2
---
$id: http://devicetree.org/schemas/pwm/marvell,pxa-pwm.yaml#
$schema: http://devicetree.org/meta-schemas/core.yaml#
title: Marvell PXA PWM
maintainers:
- Duje Mihanović <duje.mihanovic@skole.hr>
allOf:
- $ref: pwm.yaml#
properties:
compatible:
enum:
- marvell,pxa250-pwm
- marvell,pxa270-pwm
- marvell,pxa168-pwm
- marvell,pxa910-pwm
reg:
# Length should be 0x10
maxItems: 1
"#pwm-cells":
# Used for specifying the period length in nanoseconds
const: 1
clocks:
maxItems: 1
required:
- compatible
- reg
- "#pwm-cells"
- clocks
additionalProperties: false
examples:
- |
#include <dt-bindings/clock/pxa-clock.h>
pwm0: pwm@40b00000 {
compatible = "marvell,pxa250-pwm";
reg = <0x40b00000 0x10>;
#pwm-cells = <1>;
clocks = <&clks CLK_PWM0>;
};
Documentation/devicetree/bindings/pwm/mediatek,mt2712-pwm.yaml
+1
View File
@@ -24,6 +24,7 @@ properties:
- mediatek,mt7629-pwm
- mediatek,mt7981-pwm
- mediatek,mt7986-pwm
- mediatek,mt7988-pwm
- mediatek,mt8183-pwm
- mediatek,mt8365-pwm
- mediatek,mt8516-pwm
Documentation/devicetree/bindings/pwm/pwm-amlogic.yaml
+104 -11
View File
@@ -9,9 +9,6 @@ title: Amlogic PWM
maintainers:
- Heiner Kallweit <hkallweit1@gmail.com>
allOf:
- $ref: pwm.yaml#
properties:
compatible:
oneOf:
@@ -24,31 +21,40 @@ properties:
- amlogic,meson-g12a-ee-pwm
- amlogic,meson-g12a-ao-pwm-ab
- amlogic,meson-g12a-ao-pwm-cd
- amlogic,meson-s4-pwm
deprecated: true
- items:
- const: amlogic,meson-gx-pwm
- const: amlogic,meson-gxbb-pwm
deprecated: true
- items:
- const: amlogic,meson-gx-ao-pwm
- const: amlogic,meson-gxbb-ao-pwm
deprecated: true
- items:
- const: amlogic,meson8-pwm
- const: amlogic,meson8b-pwm
deprecated: true
- enum:
- amlogic,meson8-pwm-v2
- amlogic,meson-s4-pwm
- items:
- enum:
- amlogic,meson8b-pwm-v2
- amlogic,meson-gxbb-pwm-v2
- amlogic,meson-axg-pwm-v2
- amlogic,meson-g12-pwm-v2
- const: amlogic,meson8-pwm-v2
reg:
maxItems: 1
clocks:
minItems: 1
maxItems: 2
maxItems: 4
clock-names:
oneOf:
- items:
- enum: [clkin0, clkin1]
- items:
- const: clkin0
- const: clkin1
minItems: 1
maxItems: 2
"#pwm-cells":
const: 3
@@ -57,6 +63,79 @@ required:
- compatible
- reg
allOf:
- $ref: pwm.yaml#
- if:
properties:
compatible:
contains:
enum:
- amlogic,meson8-pwm
- amlogic,meson8b-pwm
- amlogic,meson-gxbb-pwm
- amlogic,meson-gxbb-ao-pwm
- amlogic,meson-axg-ee-pwm
- amlogic,meson-axg-ao-pwm
- amlogic,meson-g12a-ee-pwm
- amlogic,meson-g12a-ao-pwm-ab
- amlogic,meson-g12a-ao-pwm-cd
then:
# Obsolete historic bindings tied to the driver implementation
# The clocks provided here are meant to be matched with the input
# known (hard-coded) in the driver and used to select pwm clock
# source. Currently, the linux driver ignores this.
# This is kept to maintain ABI backward compatibility.
properties:
clocks:
maxItems: 2
clock-names:
oneOf:
- items:
- enum: [clkin0, clkin1]
- items:
- const: clkin0
- const: clkin1
# Newer binding where clock describe the actual clock inputs of the pwm
# block. These are necessary but some inputs may be grounded.
- if:
properties:
compatible:
contains:
enum:
- amlogic,meson8-pwm-v2
then:
properties:
clocks:
minItems: 1
items:
- description: input clock 0 of the pwm block
- description: input clock 1 of the pwm block
- description: input clock 2 of the pwm block
- description: input clock 3 of the pwm block
clock-names: false
required:
- clocks
# Newer IP block take a single input per channel, instead of 4 inputs
# for both channels
- if:
properties:
compatible:
contains:
enum:
- amlogic,meson-s4-pwm
then:
properties:
clocks:
items:
- description: input clock of PWM channel A
- description: input clock of PWM channel B
clock-names: false
required:
- clocks
additionalProperties: false
examples:
@@ -68,3 +147,17 @@ examples:
clock-names = "clkin0", "clkin1";
#pwm-cells = <3>;
};
- |
pwm@2000 {
compatible = "amlogic,meson8-pwm-v2";
reg = <0x1000 0x10>;
clocks = <&xtal>, <0>, <&fdiv4>, <&fdiv5>;
#pwm-cells = <3>;
};
- |
pwm@1000 {
compatible = "amlogic,meson-s4-pwm";
reg = <0x1000 0x10>;
clocks = <&pwm_src_a>, <&pwm_src_b>;
#pwm-cells = <3>;
};
Documentation/devicetree/bindings/pwm/pxa-pwm.txt
-30
View File
@@ -1,30 +0,0 @@
Marvell PWM controller
Required properties:
- compatible: should be one or more of:
- "marvell,pxa250-pwm"
- "marvell,pxa270-pwm"
- "marvell,pxa168-pwm"
- "marvell,pxa910-pwm"
- reg: Physical base address and length of the registers used by the PWM channel
Note that one device instance must be created for each PWM that is used, so the
length covers only the register window for one PWM output, not that of the
entire PWM controller. Currently length is 0x10 for all supported devices.
- #pwm-cells: Should be 1. This cell is used to specify the period in
nanoseconds.
Example PWM device node:
pwm0: pwm@40b00000 {
compatible = "marvell,pxa250-pwm";
reg = <0x40b00000 0x10>;
#pwm-cells = <1>;
};
Example PWM client node:
backlight {
compatible = "pwm-backlight";
pwms = <&pwm0 5000000>;
...
}
Documentation/devicetree/bindings/regulator/gpio-regulator.yaml
+3 -1
View File
@@ -47,6 +47,7 @@ properties:
1: HIGH
Default is LOW if nothing else is specified.
$ref: /schemas/types.yaml#/definitions/uint32-array
minItems: 1
maxItems: 8
items:
enum: [0, 1]
@@ -57,7 +58,8 @@ properties:
regulator and matching GPIO configurations to achieve them. If there are
no states in the "states" array, use a fixed regulator instead.
$ref: /schemas/types.yaml#/definitions/uint32-matrix
maxItems: 8
minItems: 2
maxItems: 256
items:
items:
- description: Voltage in microvolts
Documentation/devicetree/bindings/regulator/infineon,ir38060.yaml
+45
View File
@@ -0,0 +1,45 @@
# SPDX-License-Identifier: GPL-2.0-only OR BSD-2-Clause
%YAML 1.2
---
$id: http://devicetree.org/schemas/regulator/infineon,ir38060.yaml#
$schema: http://devicetree.org/meta-schemas/core.yaml#
title: Infineon Buck Regulators with PMBUS interfaces
maintainers:
- Not Me.
allOf:
- $ref: regulator.yaml#
properties:
compatible:
enum:
- infineon,ir38060
- infineon,ir38064
- infineon,ir38164
- infineon,ir38263
reg:
maxItems: 1
required:
- compatible
- reg
unevaluatedProperties: false
examples:
- |
i2c {
#address-cells = <1>;
#size-cells = <0>;
regulator@34 {
compatible = "infineon,ir38060";
reg = <0x34>;
regulator-min-microvolt = <437500>;
regulator-max-microvolt = <1387500>;
};
};
Documentation/devicetree/bindings/regulator/mcp16502-regulator.txt
-144
View File
@@ -1,144 +0,0 @@
MCP16502 PMIC
Required properties:
- compatible: "microchip,mcp16502"
- reg: I2C slave address
- lpm-gpios: GPIO for LPM pin. Note that this GPIO *must* remain high during
suspend-to-ram, keeping the PMIC into HIBERNATE mode; this
property is optional;
- regulators: A node that houses a sub-node for each regulator within
the device. Each sub-node is identified using the node's
name. The content of each sub-node is defined by the
standard binding for regulators; see regulator.txt.
Regulators of MCP16502 PMIC:
1) VDD_IO - Buck (1.2 - 3.7 V)
2) VDD_DDR - Buck (0.6 - 1.85 V)
3) VDD_CORE - Buck (0.6 - 1.85 V)
4) VDD_OTHER - BUCK (0.6 - 1.85 V)
5) LDO1 - LDO (1.2 - 3.7 V)
6) LDO2 - LDO (1.2 - 3.7 V)
Regulator modes:
2 - FPWM: higher precision, higher consumption
4 - AutoPFM: lower precision, lower consumption
Each regulator is defined using the standard binding for regulators.
Example:
mcp16502@5b {
compatible = "microchip,mcp16502";
reg = <0x5b>;
status = "okay";
lpm-gpios = <&pioBU 7 GPIO_ACTIVE_HIGH>;
regulators {
VDD_IO {
regulator-name = "VDD_IO";
regulator-min-microvolt = <1200000>;
regulator-max-microvolt = <3700000>;
regulator-initial-mode = <2>;
regulator-allowed-modes = <2>, <4>;
regulator-always-on;
regulator-state-standby {
regulator-on-in-suspend;
regulator-mode = <4>;
};
regulator-state-mem {
regulator-off-in-suspend;
regulator-mode = <4>;
};
};
VDD_DDR {
regulator-name = "VDD_DDR";
regulator-min-microvolt = <600000>;
regulator-max-microvolt = <1850000>;
regulator-initial-mode = <2>;
regulator-allowed-modes = <2>, <4>;
regulator-always-on;
regulator-state-standby {
regulator-on-in-suspend;
regulator-mode = <4>;
};
regulator-state-mem {
regulator-on-in-suspend;
regulator-mode = <4>;
};
};
VDD_CORE {
regulator-name = "VDD_CORE";
regulator-min-microvolt = <600000>;
regulator-max-microvolt = <1850000>;
regulator-initial-mode = <2>;
regulator-allowed-modes = <2>, <4>;
regulator-always-on;
regulator-state-standby {
regulator-on-in-suspend;
regulator-mode = <4>;
};
regulator-state-mem {
regulator-off-in-suspend;
regulator-mode = <4>;
};
};
VDD_OTHER {
regulator-name = "VDD_OTHER";
regulator-min-microvolt = <600000>;
regulator-max-microvolt = <1850000>;
regulator-initial-mode = <2>;
regulator-allowed-modes = <2>, <4>;
regulator-always-on;
regulator-state-standby {
regulator-on-in-suspend;
regulator-mode = <4>;
};
regulator-state-mem {
regulator-off-in-suspend;
regulator-mode = <4>;
};
};
LDO1 {
regulator-name = "LDO1";
regulator-min-microvolt = <1200000>;
regulator-max-microvolt = <3700000>;
regulator-always-on;
regulator-state-standby {
regulator-on-in-suspend;
};
regulator-state-mem {
regulator-off-in-suspend;
};
};
LDO2 {
regulator-name = "LDO2";
regulator-min-microvolt = <1200000>;
regulator-max-microvolt = <3700000>;
regulator-always-on;
regulator-state-standby {
regulator-on-in-suspend;
};
regulator-state-mem {
regulator-off-in-suspend;
};
};
};
};
Documentation/devicetree/bindings/regulator/microchip,mcp16502.yaml
+180
View File
@@ -0,0 +1,180 @@
# SPDX-License-Identifier: GPL-2.0-only OR BSD-2-Clause
%YAML 1.2
---
$id: http://devicetree.org/schemas/regulator/microchip,mcp16502.yaml#
$schema: http://devicetree.org/meta-schemas/core.yaml#
title: MCP16502 - High-Performance PMIC
maintainers:
- Andrei Simion <andrei.simion@microchip.com>
description:
The MCP16502 is an optimally integrated PMIC compatible
with Microchip's eMPUs(Embedded Microprocessor Units),
requiring Dynamic Voltage Scaling (DVS) with the use
of High-Performance mode (HPM).
properties:
compatible:
const: microchip,mcp16502
lpm-gpios:
maxItems: 1
description: GPIO for LPM pin.
Note that this GPIO must remain high during
suspend-to-ram, keeping the PMIC into HIBERNATE mode.
reg:
maxItems: 1
regulators:
type: object
additionalProperties: false
description: List of regulators and its properties.
patternProperties:
"^(VDD_(IO|CORE|DDR|OTHER)|LDO[1-2])$":
type: object
$ref: regulator.yaml#
unevaluatedProperties: false
properties:
regulator-initial-mode:
enum: [2, 4]
default: 2
description: Initial operating mode
regulator-allowed-modes:
items:
enum: [2, 4]
description: Supported modes
2 - FPWM higher precision, higher consumption
4 - AutoPFM lower precision, lower consumption
required:
- compatible
- reg
- regulators
additionalProperties: false
examples:
- |
i2c {
#address-cells = <1>;
#size-cells = <0>;
pmic@5b {
compatible = "microchip,mcp16502";
reg = <0x5b>;
regulators {
VDD_IO {
regulator-name = "VDD_IO";
regulator-min-microvolt = <3300000>;
regulator-max-microvolt = <3300000>;
regulator-initial-mode = <2>;
regulator-allowed-modes = <2>, <4>;
regulator-always-on;
regulator-state-standby {
regulator-on-in-suspend;
regulator-mode = <4>;
};
regulator-state-mem {
regulator-off-in-suspend;
regulator-mode = <4>;
};
};
VDD_DDR {
regulator-name = "VDD_DDR";
regulator-min-microvolt = <1350000>;
regulator-max-microvolt = <1350000>;
regulator-initial-mode = <2>;
regulator-allowed-modes = <2>, <4>;
regulator-always-on;
regulator-state-standby {
regulator-on-in-suspend;
regulator-mode = <4>;
};
regulator-state-mem {
regulator-on-in-suspend;
regulator-mode = <4>;
};
};
VDD_CORE {
regulator-name = "VDD_CORE";
regulator-min-microvolt = <1150000>;
regulator-max-microvolt = <1150000>;
regulator-initial-mode = <2>;
regulator-allowed-modes = <2>, <4>;
regulator-always-on;
regulator-state-standby {
regulator-on-in-suspend;
regulator-mode = <4>;
};
regulator-state-mem {
regulator-off-in-suspend;
regulator-mode = <4>;
};
};
VDD_OTHER {
regulator-name = "VDD_OTHER";
regulator-min-microvolt = <1050000>;
regulator-max-microvolt = <1250000>;
regulator-initial-mode = <2>;
regulator-allowed-modes = <2>, <4>;
regulator-always-on;
regulator-state-standby {
regulator-on-in-suspend;
regulator-mode = <4>;
};
regulator-state-mem {
regulator-off-in-suspend;
regulator-mode = <4>;
};
};
LDO1 {
regulator-name = "LDO1";
regulator-min-microvolt = <1800000>;
regulator-max-microvolt = <1800000>;
regulator-always-on;
regulator-state-standby {
regulator-on-in-suspend;
};
regulator-state-mem {
regulator-off-in-suspend;
};
};
LDO2 {
regulator-name = "LDO2";
regulator-min-microvolt = <1200000>;
regulator-max-microvolt = <3700000>;
regulator-always-on;
regulator-state-standby {
regulator-on-in-suspend;
};
regulator-state-mem {
regulator-off-in-suspend;
};
};
};
};
};
Documentation/devicetree/bindings/regulator/qcom,usb-vbus-regulator.yaml
+8 -2
View File
@@ -19,8 +19,14 @@ allOf:
properties:
compatible:
enum:
- qcom,pm8150b-vbus-reg
oneOf:
- enum:
- qcom,pm8150b-vbus-reg
- items:
- enum:
- qcom,pm4125-vbus-reg
- qcom,pm6150-vbus-reg
- const: qcom,pm8150b-vbus-reg
reg:
maxItems: 1
Documentation/devicetree/bindings/regulator/ti,tps65132.yaml
+84
View File
@@ -0,0 +1,84 @@
# SPDX-License-Identifier: GPL-2.0-only OR BSD-2-Clause
%YAML 1.2
---
$id: http://devicetree.org/schemas/regulator/ti,tps65132.yaml#
$schema: http://devicetree.org/meta-schemas/core.yaml#
title: TI TPS65132 Dual Output Power Regulators
maintainers:
- devicetree@vger.kernel.org
description: |
The TPS65132 is designed to supply positive/negative driven applications.
Datasheet is available at:
https://www.ti.com/lit/gpn/tps65132
properties:
compatible:
enum:
- ti,tps65132
reg:
maxItems: 1
patternProperties:
"^out[pn]$":
type: object
$ref: regulator.yaml#
unevaluatedProperties: false
description:
Properties for single regulator.
properties:
enable-gpios:
maxItems: 1
description:
GPIO specifier to enable the GPIO control (on/off) for regulator.
active-discharge-gpios:
maxItems: 1
description:
GPIO specifier to actively discharge the delay mechanism.
ti,active-discharge-time-us:
description: Regulator active discharge time in microseconds.
dependencies:
active-discharge-gpios: [ 'ti,active-discharge-time-us' ]
required:
- compatible
- reg
additionalProperties: false
examples:
- |
#include <dt-bindings/gpio/gpio.h>
i2c {
#address-cells = <1>;
#size-cells = <0>;
regulator@3e {
compatible = "ti,tps65132";
reg = <0x3e>;
outp {
regulator-name = "outp";
regulator-boot-on;
regulator-always-on;
enable-gpios = <&gpio 23 GPIO_ACTIVE_HIGH>;
};
outn {
regulator-name = "outn";
regulator-boot-on;
regulator-always-on;
regulator-active-discharge = <0>;
enable-gpios = <&gpio 40 GPIO_ACTIVE_HIGH>;
};
};
};
Documentation/devicetree/bindings/regulator/tps65132-regulator.txt
-46
View File
@@ -1,46 +0,0 @@
TPS65132 regulators
Required properties:
- compatible: "ti,tps65132"
- reg: I2C slave address
Optional Subnode:
Device supports two regulators OUTP and OUTN. A sub node within the
device node describe the properties of these regulators. The sub-node
names must be as follows:
-For regulator outp, the sub node name should be "outp".
-For regulator outn, the sub node name should be "outn".
-enable-gpios:(active high, output) Regulators are controlled by the input pins.
If it is connected to GPIO through host system then provide the
gpio number as per gpio.txt.
-active-discharge-gpios: (active high, output) Some configurations use delay mechanisms
on the enable pin, to keep the regulator enabled for some time after
the enable signal goes low. This GPIO is used to actively discharge
the delay mechanism. Requires specification of ti,active-discharge-time-us
-ti,active-discharge-time-us: how long the active discharge gpio should be
asserted for during active discharge, in microseconds.
Each regulator is defined using the standard binding for regulators.
Example:
tps65132@3e {
compatible = "ti,tps65132";
reg = <0x3e>;
outp {
regulator-name = "outp";
regulator-boot-on;
regulator-always-on;
enable-gpios = <&gpio 23 0>;
};
outn {
regulator-name = "outn";
regulator-boot-on;
regulator-always-on;
regulator-active-discharge = <0>;
enable-gpios = <&gpio 40 0>;
};
};
Documentation/devicetree/bindings/soc/imx/fsl,imx8mp-hdmi-blk-ctrl.yaml
+14 -8
View File
@@ -27,8 +27,8 @@ properties:
const: 1
power-domains:
minItems: 8
maxItems: 8
minItems: 10
maxItems: 10
power-domain-names:
items:
@@ -40,10 +40,12 @@ properties:
- const: trng
- const: hdmi-tx
- const: hdmi-tx-phy
- const: hdcp
- const: hrv
clocks:
minItems: 4
maxItems: 4
minItems: 5
maxItems: 5
clock-names:
items:
@@ -51,6 +53,7 @@ properties:
- const: axi
- const: ref_266m
- const: ref_24m
- const: fdcc
interconnects:
maxItems: 3
@@ -82,12 +85,15 @@ examples:
clocks = <&clk IMX8MP_CLK_HDMI_APB>,
<&clk IMX8MP_CLK_HDMI_ROOT>,
<&clk IMX8MP_CLK_HDMI_REF_266M>,
<&clk IMX8MP_CLK_HDMI_24M>;
clock-names = "apb", "axi", "ref_266m", "ref_24m";
<&clk IMX8MP_CLK_HDMI_24M>,
<&clk IMX8MP_CLK_HDMI_FDCC_TST>;
clock-names = "apb", "axi", "ref_266m", "ref_24m", "fdcc";
power-domains = <&pgc_hdmimix>, <&pgc_hdmimix>, <&pgc_hdmimix>,
<&pgc_hdmimix>, <&pgc_hdmimix>, <&pgc_hdmimix>,
<&pgc_hdmimix>, <&pgc_hdmi_phy>;
<&pgc_hdmimix>, <&pgc_hdmi_phy>,
<&pgc_hdmimix>, <&pgc_hdmimix>;
power-domain-names = "bus", "irqsteer", "lcdif", "pai", "pvi", "trng",
"hdmi-tx", "hdmi-tx-phy";
"hdmi-tx", "hdmi-tx-phy",
"hdcp", "hrv";
#power-domain-cells = <1>;
};
Documentation/devicetree/bindings/spi/atmel,at91rm9200-spi.yaml
-1
View File
@@ -22,7 +22,6 @@ properties:
- const: atmel,at91rm9200-spi
- items:
- const: microchip,sam9x7-spi
- const: microchip,sam9x60-spi
- const: atmel,at91rm9200-spi
reg:
Documentation/devicetree/bindings/spi/samsung,spi.yaml
+2 -2
View File
@@ -17,11 +17,13 @@ properties:
compatible:
oneOf:
- enum:
- google,gs101-spi
- samsung,s3c2443-spi # for S3C2443, S3C2416 and S3C2450
- samsung,s3c6410-spi
- samsung,s5pv210-spi # for S5PV210 and S5PC110
- samsung,exynos4210-spi
- samsung,exynos5433-spi
- samsung,exynos850-spi
- samsung,exynosautov9-spi
- tesla,fsd-spi
- const: samsung,exynos7-spi
@@ -74,8 +76,6 @@ required:
- compatible
- clocks
- clock-names
- dmas
- dma-names
- interrupts
- reg
Documentation/devicetree/bindings/spi/spi-controller.yaml
+27
View File
@@ -69,6 +69,21 @@ properties:
Should be generally avoided and be replaced by
spi-cs-high + ACTIVE_HIGH.
fifo-depth:
$ref: /schemas/types.yaml#/definitions/uint32
description:
Size of the RX and TX data FIFOs in bytes.
rx-fifo-depth:
$ref: /schemas/types.yaml#/definitions/uint32
description:
Size of the RX data FIFO in bytes.
tx-fifo-depth:
$ref: /schemas/types.yaml#/definitions/uint32
description:
Size of the TX data FIFO in bytes.
num-cs:
$ref: /schemas/types.yaml#/definitions/uint32
description:
@@ -116,6 +131,10 @@ patternProperties:
- compatible
- reg
dependencies:
rx-fifo-depth: [ tx-fifo-depth ]
tx-fifo-depth: [ rx-fifo-depth ]
allOf:
- if:
not:
@@ -129,6 +148,14 @@ allOf:
properties:
"#address-cells":
const: 0
- not:
required:
- fifo-depth
- rx-fifo-depth
- not:
required:
- fifo-depth
- tx-fifo-depth
additionalProperties: true
Documentation/devicetree/bindings/spi/spi-fsl-lpspi.yaml
+1
View File
@@ -22,6 +22,7 @@ properties:
- enum:
- fsl,imx8ulp-spi
- fsl,imx93-spi
- fsl,imx95-spi
- const: fsl,imx7ulp-spi
reg:
maxItems: 1
Documentation/devicetree/bindings/spi/spi-nxp-fspi.yaml
+12 -6
View File
@@ -15,12 +15,18 @@ allOf:
properties:
compatible:
enum:
- nxp,imx8dxl-fspi
- nxp,imx8mm-fspi
- nxp,imx8mp-fspi
- nxp,imx8qxp-fspi
- nxp,lx2160a-fspi
oneOf:
- enum:
- nxp,imx8dxl-fspi
- nxp,imx8mm-fspi
- nxp,imx8mp-fspi
- nxp,imx8qxp-fspi
- nxp,lx2160a-fspi
- items:
- enum:
- nxp,imx93-fspi
- nxp,imx95-fspi
- const: nxp,imx8mm-fspi
reg:
items:
Documentation/devicetree/bindings/trivial-devices.yaml
+4 -8
View File
@@ -47,6 +47,8 @@ properties:
- adi,lt7182s
# AMS iAQ-Core VOC Sensor
- ams,iaq-core
# Temperature monitoring of Astera Labs PT5161L PCIe retimer
- asteralabs,pt5161l
# i2c serial eeprom (24cxx)
- at,24c08
# ATSHA204 - i2c h/w symmetric crypto module
@@ -129,6 +131,8 @@ properties:
- mps,mp2975
# Monolithic Power Systems Inc. multi-phase hot-swap controller mp5990
- mps,mp5990
# Monolithic Power Systems Inc. synchronous step-down converter mpq8785
- mps,mpq8785
# Honeywell Humidicon HIH-6130 humidity/temperature sensor
- honeywell,hi6130
# IBM Common Form Factor Power Supply Versions (all versions)
@@ -139,14 +143,6 @@ 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 IRPS5401 Voltage Regulator (PMIC)
- infineon,irps5401
# Infineon TLV493D-A1B6 I2C 3D Magnetic Sensor
Documentation/devicetree/bindings/vendor-prefixes.yaml
+4
View File
@@ -109,6 +109,8 @@ patternProperties:
description: Amlogic, Inc.
"^ampere,.*":
description: Ampere Computing LLC
"^amphenol,.*":
description: Amphenol Advanced Sensors
"^ampire,.*":
description: Ampire Co., Ltd.
"^ams,.*":
@@ -161,6 +163,8 @@ patternProperties:
description: ASPEED Technology Inc.
"^asrock,.*":
description: ASRock Inc.
"^asteralabs,.*":
description: Astera Labs, Inc.
"^asus,.*":
description: AsusTek Computer Inc.
"^atheros,.*":
Documentation/driver-api/driver-model/devres.rst
+2 -1
View File
@@ -420,6 +420,7 @@ POWER
devm_reboot_mode_unregister()
PWM
devm_pwmchip_alloc()
devm_pwmchip_add()
devm_pwm_get()
devm_fwnode_pwm_get()
@@ -462,7 +463,7 @@ SLAVE DMA ENGINE
SPI
devm_spi_alloc_master()
devm_spi_alloc_slave()
devm_spi_register_master()
devm_spi_register_controller()
WATCHDOG
devm_watchdog_register_device()
Documentation/driver-api/gpio/consumer.rst
+5 -5
View File
@@ -222,9 +222,9 @@ Use the following calls to access GPIOs from an atomic context::
int gpiod_get_value(const struct gpio_desc *desc);
void gpiod_set_value(struct gpio_desc *desc, int value);
The values are boolean, zero for low, nonzero for high. When reading the value
of an output pin, the value returned should be what's seen on the pin. That
won't always match the specified output value, because of issues including
The values are boolean, zero for inactive, nonzero for active. When reading the
value of an output pin, the value returned should be what's seen on the pin.
That won't always match the specified output value, because of issues including
open-drain signaling and output latencies.
The get/set calls do not return errors because "invalid GPIO" should have been
@@ -277,11 +277,11 @@ switch their output to a high impedance value. The consumer should not need to
care. (For details read about open drain in driver.rst.)
With this, all the gpiod_set_(array)_value_xxx() functions interpret the
parameter "value" as "asserted" ("1") or "de-asserted" ("0"). The physical line
parameter "value" as "active" ("1") or "inactive" ("0"). The physical line
level will be driven accordingly.
As an example, if the active low property for a dedicated GPIO is set, and the
gpiod_set_(array)_value_xxx() passes "asserted" ("1"), the physical line level
gpiod_set_(array)_value_xxx() passes "active" ("1"), the physical line level
will be driven low.
To summarize::
Documentation/driver-api/pwm.rst
+6 -5
View File
@@ -143,11 +143,12 @@ to implement the pwm_*() functions itself. This means that it's impossible
to have multiple PWM drivers in the system. For this reason it's mandatory
for new drivers to use the generic PWM framework.
A new PWM controller/chip can be added using pwmchip_add() and removed
again with pwmchip_remove(). pwmchip_add() takes a filled in struct
pwm_chip as argument which provides a description of the PWM chip, the
number of PWM devices provided by the chip and the chip-specific
implementation of the supported PWM operations to the framework.
A new PWM controller/chip can be allocated using pwmchip_alloc(), then
registered using pwmchip_add() and removed again with pwmchip_remove(). To undo
pwmchip_alloc() use pwmchip_put(). pwmchip_add() takes a filled in struct
pwm_chip as argument which provides a description of the PWM chip, the number
of PWM devices provided by the chip and the chip-specific implementation of the
supported PWM operations to the framework.
When implementing polarity support in a PWM driver, make sure to respect the
signal conventions in the PWM framework. By definition, normal polarity
Documentation/firmware-guide/acpi/index.rst
-1
View File
@@ -14,7 +14,6 @@ ACPI Support
dsd/phy
enumeration
osi
method-customizing
method-tracing
DSD-properties-rules
debug
Documentation/firmware-guide/acpi/method-customizing.rst
-89
View File
@@ -1,89 +0,0 @@
.. SPDX-License-Identifier: GPL-2.0
=======================================
Linux ACPI Custom Control Method How To
=======================================
:Author: Zhang Rui <rui.zhang@intel.com>
Linux supports customizing ACPI control methods at runtime.
Users can use this to:
1. override an existing method which may not work correctly,
or just for debugging purposes.
2. insert a completely new method in order to create a missing
method such as _OFF, _ON, _STA, _INI, etc.
For these cases, it is far simpler to dynamically install a single
control method rather than override the entire DSDT, because kernel
rebuild/reboot is not needed and test result can be got in minutes.
.. note::
- Only ACPI METHOD can be overridden, any other object types like
"Device", "OperationRegion", are not recognized. Methods
declared inside scope operators are also not supported.
- The same ACPI control method can be overridden for many times,
and it's always the latest one that used by Linux/kernel.
- To get the ACPI debug object output (Store (AAAA, Debug)),
please run::
echo 1 > /sys/module/acpi/parameters/aml_debug_output
1. override an existing method
==============================
a) get the ACPI table via ACPI sysfs I/F. e.g. to get the DSDT,
just run "cat /sys/firmware/acpi/tables/DSDT > /tmp/dsdt.dat"
b) disassemble the table by running "iasl -d dsdt.dat".
c) rewrite the ASL code of the method and save it in a new file,
d) package the new file (psr.asl) to an ACPI table format.
Here is an example of a customized \_SB._AC._PSR method::
DefinitionBlock ("", "SSDT", 1, "", "", 0x20080715)
{
Method (\_SB_.AC._PSR, 0, NotSerialized)
{
Store ("In AC _PSR", Debug)
Return (ACON)
}
}
Note that the full pathname of the method in ACPI namespace
should be used.
e) assemble the file to generate the AML code of the method.
e.g. "iasl -vw 6084 psr.asl" (psr.aml is generated as a result)
If parameter "-vw 6084" is not supported by your iASL compiler,
please try a newer version.
f) mount debugfs by "mount -t debugfs none /sys/kernel/debug"
g) override the old method via the debugfs by running
"cat /tmp/psr.aml > /sys/kernel/debug/acpi/custom_method"
2. insert a new method
======================
This is easier than overriding an existing method.
We just need to create the ASL code of the method we want to
insert and then follow the step c) ~ g) in section 1.
3. undo your changes
====================
The "undo" operation is not supported for a new inserted method
right now, i.e. we can not remove a method currently.
For an overridden method, in order to undo your changes, please
save a copy of the method original ASL code in step c) section 1,
and redo step c) ~ g) to override the method with the original one.
.. note:: We can use a kernel with multiple custom ACPI method running,
But each individual write to debugfs can implement a SINGLE
method override. i.e. if we want to insert/override multiple
ACPI methods, we need to redo step c) ~ g) for multiple times.
.. note:: Be aware that root can mis-use this driver to modify arbitrary
memory and gain additional rights, if root's privileges got
restricted (for example if root is not allowed to load additional
modules after boot).
Documentation/hwmon/aspeed-g6-pwm-tach.rst
+26
View File
@@ -0,0 +1,26 @@
.. SPDX-License-Identifier: GPL-2.0-or-later
Kernel driver aspeed-g6-pwm-tach
=================================
Supported chips:
ASPEED AST2600
Authors:
<billy_tsai@aspeedtech.com>
Description:
------------
This driver implements support for ASPEED AST2600 Fan Tacho controller.
The controller supports up to 16 tachometer inputs.
The driver provides the following sensor accesses in sysfs:
=============== ======= ======================================================
fanX_input ro provide current fan rotation value in RPM as reported
by the fan to the device.
fanX_div rw Fan divisor: Supported value are power of 4 (1, 4, 16
64, ... 4194304)
The larger divisor, the less rpm accuracy and the less
affected by fan signal glitch.
=============== ======= ======================================================
Documentation/hwmon/asus_rog_ryujin.rst
+47
View File
@@ -0,0 +1,47 @@
.. SPDX-License-Identifier: GPL-2.0-or-later
Kernel driver asus_rog_ryujin
=============================
Supported devices:
* ASUS ROG RYUJIN II 360
Author: Aleksa Savic
Description
-----------
This driver enables hardware monitoring support for the listed ASUS ROG RYUJIN
all-in-one CPU liquid coolers. Available sensors are pump, internal and external
(controller) fan speed in RPM, their duties in PWM, as well as coolant temperature.
Attaching external fans to the controller is optional and allows them to be
controlled from the device. If not connected, the fan-related sensors will
report zeroes. The controller is a separate hardware unit that comes bundled
with the AIO and connects to it to allow fan control.
The addressable LCD screen is not supported in this driver and should
be controlled through userspace tools.
Usage notes
-----------
As these are USB HIDs, the driver can be loaded automatically by the kernel and
supports hot swapping.
Sysfs entries
-------------
=========== =============================================
fan1_input Pump speed (in rpm)
fan2_input Internal fan speed (in rpm)
fan3_input External (controller) fan 1 speed (in rpm)
fan4_input External (controller) fan 2 speed (in rpm)
fan5_input External (controller) fan 3 speed (in rpm)
fan6_input External (controller) fan 4 speed (in rpm)
temp1_input Coolant temperature (in millidegrees Celsius)
pwm1 Pump duty
pwm2 Internal fan duty
pwm3 External (controller) fan duty
=========== =============================================
Documentation/hwmon/chipcap2.rst
+73
View File
@@ -0,0 +1,73 @@
.. SPDX-License-Identifier: GPL-2.0-or-later
Kernel driver ChipCap2
======================
Supported chips:
* Amphenol CC2D23, CC2D23S, CC2D25, CC2D25S, CC2D33, CC2D33S, CC2D35, CC2D35S
Prefix: 'chipcap2'
Addresses scanned: -
Datasheet: https://www.amphenol-sensors.com/en/telaire/humidity/527-humidity-sensors/3095-chipcap-2
Author:
- Javier Carrasco <javier.carrasco.cruz@gmail.com>
Description
-----------
This driver implements support for the Amphenol ChipCap 2, a humidity and
temperature chip family. Temperature is measured in milli degrees celsius,
relative humidity is expressed as a per cent mille. The measurement ranges
are the following:
- Relative humidity: 0 to 100000 pcm (14-bit resolution)
- Temperature: -40000 to +125000 m°C (14-bit resolution)
The device communicates with the I2C protocol and uses the I2C address 0x28
by default.
Depending on the hardware configuration, up to two humidity alarms to control
minimum and maximum values are provided. Their thresholds and hystersis can be
configured via sysfs.
Thresholds and hysteris must be provided as a per cent mille. These values
might be truncated to match the 14-bit device resolution (6.1 pcm/LSB)
Known Issues
------------
The driver does not support I2C address and command window length modification.
sysfs-Interface
---------------
The following list includes the sysfs attributes that the driver always provides,
their permissions and a short description:
=============================== ======= ========================================
Name Perm Description
=============================== ======= ========================================
temp1_input: RO temperature input
humidity1_input: RO humidity input
=============================== ======= ========================================
The following list includes the sysfs attributes that the driver may provide
depending on the hardware configuration:
=============================== ======= ========================================
Name Perm Description
=============================== ======= ========================================
humidity1_min: RW humidity low limit. Measurements under
this limit trigger a humidity low alarm
humidity1_max: RW humidity high limit. Measurements above
this limit trigger a humidity high alarm
humidity1_min_hyst: RW humidity low hystersis
humidity1_max_hyst: RW humidity high hystersis
humidity1_min_alarm: RO humidity low alarm indicator
humidity1_max_alarm: RO humidity high alarm indicator
=============================== ======= ========================================
Documentation/hwmon/emc2305.rst
-1
View File
@@ -6,7 +6,6 @@ Kernel driver emc2305
Supported chips:
Microchip EMC2305, EMC2303, EMC2302, EMC2301
Addresses scanned: I2C 0x27, 0x2c, 0x2d, 0x2e, 0x2f, 0x4c, 0x4d
Prefixes: 'emc2305'
Datasheet: Publicly available at the Microchip website :
Documentation/hwmon/index.rst
+8
View File
@@ -44,13 +44,16 @@ Hardware Monitoring Kernel Drivers
aquacomputer_d5next
asb100
asc7621
aspeed-g6-pwm-tach
aspeed-pwm-tacho
asus_ec_sensors
asus_rog_ryujin
asus_wmi_sensors
bcm54140
bel-pfe
bpa-rs600
bt1-pvt
chipcap2
coretemp
corsair-cpro
corsair-psu
@@ -129,6 +132,7 @@ Hardware Monitoring Kernel Drivers
ltc4245
ltc4260
ltc4261
ltc4282
ltc4286
max127
max15301
@@ -163,6 +167,7 @@ Hardware Monitoring Kernel Drivers
mp2975
mp5023
mp5990
mpq8785
nct6683
nct6775
nct7802
@@ -171,6 +176,7 @@ Hardware Monitoring Kernel Drivers
nsa320
ntc_thermistor
nzxt-kraken2
nzxt-kraken3
nzxt-smart2
occ
oxp-sensors
@@ -185,6 +191,7 @@ Hardware Monitoring Kernel Drivers
pmbus
powerz
powr1220
pt5161l
pxe1610
pwm-fan
q54sj108a2
@@ -208,6 +215,7 @@ Hardware Monitoring Kernel Drivers
smsc47m1
sparx5-temp
stpddc60
surface_fan
sy7636a-hwmon
tc654
tc74
Documentation/hwmon/ltc4282.rst
+133
View File
@@ -0,0 +1,133 @@
.. SPDX-License-Identifier: GPL-2.0-only
Kernel drivers ltc4282
==========================================
Supported chips:
* Analog Devices LTC4282
Prefix: 'ltc4282'
Addresses scanned: - I2C 0x40 - 0x5A (7-bit)
Addresses scanned: - I2C 0x80 - 0xB4 with a step of 2 (8-bit)
Datasheet:
https://www.analog.com/media/en/technical-documentation/data-sheets/ltc4282.pdf
Author: Nuno Sá <nuno.sa@analog.com>
Description
___________
The LTC4282 hot swap controller allows a board to be safely inserted and removed
from a live backplane. Using one or more external N-channel pass transistors,
board supply voltage and inrush current are ramped up at an adjustable rate. An
I2C interface and onboard ADC allows for monitoring of board current, voltage,
power, energy and fault status. The device features analog foldback current
limiting and supply monitoring for applications from 2.9V to 33V. Dual 12V gate
drive allows high power applications to either share safe operating area across
parallel MOSFETs or support a 2-stage start-up that first charges the load
capacitance followed by enabling a low on-resistance path to the load. The
LTC4282 is well suited to high power applications because the precise monitoring
capability and accurate current limiting reduce the extremes in which both loads
and power supplies must safely operate. Non-volatile configuration allows for
flexibility in the autonomous generation of alerts and response to faults.
Sysfs entries
_____________
The following attributes are supported. Limits are read-write and all the other
attributes are read-only. Note that in0 and in1 are mutually exclusive. Enabling
one disables the other and disabling one enables the other.
======================= ==========================================
in0_input Output voltage (mV).
in0_min Undervoltage threshold
in0_max Overvoltage threshold
in0_lowest Lowest measured voltage
in0_highest Highest measured voltage
in0_reset_history Write 1 to reset in0 history.
Also clears fet bad and short fault logs.
in0_min_alarm Undervoltage alarm
in0_max_alarm Overvoltage alarm
in0_enable Enable/Disable VSOURCE monitoring
in0_fault Failure in the MOSFETs. Either bad or shorted FET.
in0_label Channel label (VSOURCE)
in1_input Input voltage (mV).
in1_min Undervoltage threshold
in1_max Overvoltage threshold
in1_lowest Lowest measured voltage
in1_highest Highest measured voltage
in1_reset_history Write 1 to reset in1 history.
Also clears over/undervoltage fault logs.
in1_min_alarm Undervoltage alarm
in1_max_alarm Overvoltage alarm
in1_lcrit_alarm Critical Undervoltage alarm
in1_crit_alarm Critical Overvoltage alarm
in1_enable Enable/Disable VDD monitoring
in1_label Channel label (VDD)
in2_input GPIO voltage (mV)
in2_min Undervoltage threshold
in2_max Overvoltage threshold
in2_lowest Lowest measured voltage
in2_highest Highest measured voltage
in2_reset_history Write 1 to reset in2 history
in2_min_alarm Undervoltage alarm
in2_max_alarm Overvoltage alarm
in2_label Channel label (VGPIO)
curr1_input Sense current (mA)
curr1_min Undercurrent threshold
curr1_max Overcurrent threshold
curr1_lowest Lowest measured current
curr1_highest Highest measured current
curr1_reset_history Write 1 to reset curr1 history.
Also clears overcurrent fault logs.
curr1_min_alarm Undercurrent alarm
curr1_max_alarm Overcurrent alarm
curr1_crit_alarm Critical Overcurrent alarm
curr1_label Channel label (ISENSE)
power1_input Power (in uW)
power1_min Low power threshold
power1_max High power threshold
power1_input_lowest Historical minimum power use
power1_input_highest Historical maximum power use
power1_reset_history Write 1 to reset power1 history.
Also clears power bad fault logs.
power1_min_alarm Low power alarm
power1_max_alarm High power alarm
power1_label Channel label (Power)
energy1_input Measured energy over time (in microJoule)
energy1_enable Enable/Disable Energy accumulation
======================= ==========================================
DebugFs entries
_______________
The chip also has a fault log register where failures can be logged. Hence,
as these are logging events, we give access to them in debugfs. Note that
even if some failure is detected in these logs, it does necessarily mean
that the failure is still present. As mentioned in the proper Sysfs entries,
these logs can be cleared by writing in the proper reset_history attribute.
.. warning:: The debugfs interface is subject to change without notice
and is only available when the kernel is compiled with
``CONFIG_DEBUG_FS`` defined.
``/sys/kernel/debug/ltc4282-hwmon[X]/``
contains the following attributes:
======================= ==========================================
power1_bad_fault_log Set to 1 by a power1 bad fault occurring.
in0_fet_short_fault_log Set to 1 when the ADC detects a FET-short fault.
in0_fet_bad_fault_log Set to 1 when a FET-BAD fault occurs.
in1_crit_fault_log Set to 1 by a VDD overvoltage fault occurring.
in1_lcrit_fault_log Set to 1 by a VDD undervoltage fault occurring.
curr1_crit_fault_log Set to 1 by an overcurrent fault occurring.
======================= ==========================================
Documentation/hwmon/max6620.rst
+1 -1
View File
@@ -11,7 +11,7 @@ Supported chips:
Addresses scanned: none
Datasheet: http://pdfserv.maxim-ic.com/en/ds/MAX6620.pdf
Datasheet: https://www.analog.com/media/en/technical-documentation/data-sheets/max6620.pdf
Authors:
- L\. Grunenberg <contact@lgrunenberg.de>
Documentation/hwmon/mpq8785.rst
+94
View File
@@ -0,0 +1,94 @@
.. SPDX-License-Identifier: GPL-2.0-only
Kernel driver mpq8785
=======================
Supported chips:
* MPS MPQ8785
Prefix: 'mpq8785'
Author: Charles Hsu <ythsu0511@gmail.com>
Description
-----------
The MPQ8785 is a fully integrated, PMBus-compatible, high-frequency, synchronous
buck converter. The MPQ8785 offers a very compact solution that achieves up to
40A output current per phase, with excellent load and line regulation over a
wide input supply range. The MPQ8785 operates at high efficiency over a wide
output current load range.
The PMBus interface provides converter configurations and key parameters
monitoring.
The MPQ8785 adopts MPS's proprietary multi-phase digital constant-on-time (MCOT)
control, which provides fast transient response and eases loop stabilization.
The MCOT scheme also allows multiple MPQ8785 devices to be connected in parallel
with excellent current sharing and phase interleaving for high-current
applications.
Fully integrated protection features include over-current protection (OCP),
over-voltage protection (OVP), under-voltage protection (UVP), and
over-temperature protection (OTP).
The MPQ8785 requires a minimal number of readily available, standard external
components, and is available in a TLGA (5mmx6mm) package.
Device compliant with:
- PMBus rev 1.3 interface.
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**
**in1_crit**
**in1_crit_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_max**
**curr1_max_alarm**
**curr1_crit**
**curr1_crit_alarm**
The driver provides the following attributes for temperature:
**temp1_input**
**temp1_max**
**temp1_max_alarm**
**temp1_crit**
**temp1_crit_alarm**
Documentation/hwmon/nct6683.rst
+1
View File
@@ -64,4 +64,5 @@ Intel DB85FL NCT6683D EC firmware version 1.0 build 04/03/13
ASRock X570 NCT6683D EC firmware version 1.0 build 06/28/19
ASRock X670E NCT6686D EC firmware version 1.0 build 05/19/22
MSI B550 NCT6687D EC firmware version 1.0 build 05/07/20
MSI X670-P NCT6687D EC firmware version 0.0 build 09/27/22
=============== ===============================================
Documentation/hwmon/nzxt-kraken3.rst
+74
View File
@@ -0,0 +1,74 @@
.. SPDX-License-Identifier: GPL-2.0-or-later
Kernel driver nzxt-kraken3
==========================
Supported devices:
* NZXT Kraken X53
* NZXT Kraken X63
* NZXT Kraken X73
* NZXT Kraken Z53
* NZXT Kraken Z63
* NZXT Kraken Z73
Author: Jonas Malaco, Aleksa Savic
Description
-----------
This driver enables hardware monitoring support for NZXT Kraken X53/X63/X73 and
Z53/Z63/Z73 all-in-one CPU liquid coolers. All models expose liquid temperature
and pump speed (in RPM), as well as PWM control (either as a fixed value
or through a temp-PWM curve). The Z-series models additionally expose the speed
and duty of an optionally connected fan, with the same PWM control capabilities.
Pump and fan duty control mode can be set through pwm[1-2]_enable, where 1 is
for the manual control mode and 2 is for the liquid temp to PWM curve mode.
Writing a 0 disables control of the channel through the driver after setting its
duty to 100%.
The temperature of the curves relates to the fixed [20-59] range, correlating to
the detected liquid temperature. Only PWM values (ranging from 0-255) can be set.
If in curve mode, setting point values should be done in moderation - the devices
require complete curves to be sent for each change; they can lock up or discard
the changes if they are too numerous at once. Suggestion is to set them while
in an another mode, and then apply them by switching to curve.
The devices can report if they are faulty. The driver supports that situation
and will issue a warning. This can also happen when the USB cable is connected,
but SATA power is not.
The addressable RGB LEDs and LCD screen (only on Z-series models) are not
supported in this driver, but can be controlled through existing userspace tools,
such as `liquidctl`_.
.. _liquidctl: https://github.com/liquidctl/liquidctl
Usage Notes
-----------
As these are USB HIDs, the driver can be loaded automatically by the kernel and
supports hot swapping.
Possible pwm_enable values are:
====== ==========================================================================
0 Set fan to 100%
1 Direct PWM mode (applies value in corresponding PWM entry)
2 Curve control mode (applies the temp-PWM duty curve based on coolant temp)
====== ==========================================================================
Sysfs entries
-------------
============================== ================================================================
fan1_input Pump speed (in rpm)
fan2_input Fan speed (in rpm)
temp1_input Coolant temperature (in millidegrees Celsius)
pwm1 Pump duty (value between 0-255)
pwm1_enable Pump duty control mode (0: disabled, 1: manual, 2: curve)
pwm2 Fan duty (value between 0-255)
pwm2_enable Fan duty control mode (0: disabled, 1: manual, 2: curve)
temp[1-2]_auto_point[1-40]_pwm Temp-PWM duty curves (for pump and fan), related to coolant temp
============================== ================================================================
Documentation/hwmon/oxp-sensors.rst
+1
View File
@@ -33,6 +33,7 @@ Currently the driver supports the following handhelds:
- AOK ZOE A1 PRO
- Aya Neo 2
- Aya Neo AIR
- Aya Neo AIR Plus (Mendocino)
- Aya Neo AIR Pro
- Aya Neo Geek
- OneXPlayer AMD
Documentation/hwmon/pt5161l.rst
+42
View File
@@ -0,0 +1,42 @@
.. SPDX-License-Identifier: GPL-2.0-or-later
Kernel driver pt5161l
=====================
Supported chips:
* Astera Labs PT5161L
Prefix: 'pt5161l'
Addresses scanned: I2C 0x20 - 0x27
Datasheet: Not publicly available.
Authors: Cosmo Chou <cosmo.chou@quantatw.com>
Description
-----------
This driver implements support for temperature monitoring of Astera Labs
PT5161L series PCIe retimer chips.
This driver implementation originates from the CSDK available at
https://github.com/facebook/openbmc/tree/helium/common/recipes-lib/retimer-v2.14
The communication protocol utilized is based on the I2C/SMBus standard.
Sysfs entries
----------------
================ ==============================================
temp1_input Measured temperature (in millidegrees Celsius)
================ ==============================================
Debugfs entries
----------------
================ ===============================
fw_load_status Firmware load status
fw_ver Firmware version of the retimer
heartbeat_status Heartbeat status
================ ===============================
Documentation/hwmon/sht3x.rst
+11
View File
@@ -65,6 +65,10 @@ When the temperature and humidity readings move back between the hysteresis
values, the alert bit is set to 0 and the alert pin on the sensor is set to
low.
The serial number exposed to debugfs allows for unique identification of the
sensors. For sts32, sts33 and sht33, the manufacturer provides calibration
certificates through an API.
sysfs-Interface
---------------
@@ -99,3 +103,10 @@ repeatability: write or read repeatability, higher repeatability means
- 1: medium repeatability
- 2: high repeatability
=================== ============================================================
debugfs-Interface
-----------------
=================== ============================================================
serial_number: unique serial number of the sensor in decimal
=================== ============================================================
Documentation/hwmon/surface_fan.rst
+25
View File
@@ -0,0 +1,25 @@
.. SPDX-License-Identifier: GPL-2.0-or-later
Kernel driver surface_fan
=========================
Supported Devices:
* Microsoft Surface Pro 9
Author: Ivor Wanders <ivor@iwanders.net>
Description
-----------
This provides monitoring of the fan found in some Microsoft Surface Pro devices,
like the Surface Pro 9. The fan is always controlled by the onboard controller.
Sysfs interface
---------------
======================= ======= =========================================
Name Perm Description
======================= ======= =========================================
``fan1_input`` RO Current fan speed in RPM.
======================= ======= =========================================
Documentation/mm/slub.rst
+30 -30
View File
@@ -9,7 +9,7 @@ SLUB can enable debugging only for selected slabs in order to avoid
an impact on overall system performance which may make a bug more
difficult to find.
In order to switch debugging on one can add an option ``slub_debug``
In order to switch debugging on one can add an option ``slab_debug``
to the kernel command line. That will enable full debugging for
all slabs.
@@ -26,16 +26,16 @@ be enabled on the command line. F.e. no tracking information will be
available without debugging on and validation can only partially
be performed if debugging was not switched on.
Some more sophisticated uses of slub_debug:
Some more sophisticated uses of slab_debug:
-------------------------------------------
Parameters may be given to ``slub_debug``. If none is specified then full
Parameters may be given to ``slab_debug``. If none is specified then full
debugging is enabled. Format:
slub_debug=<Debug-Options>
slab_debug=<Debug-Options>
Enable options for all slabs
slub_debug=<Debug-Options>,<slab name1>,<slab name2>,...
slab_debug=<Debug-Options>,<slab name1>,<slab name2>,...
Enable options only for select slabs (no spaces
after a comma)
@@ -60,23 +60,23 @@ Possible debug options are::
F.e. in order to boot just with sanity checks and red zoning one would specify::
slub_debug=FZ
slab_debug=FZ
Trying to find an issue in the dentry cache? Try::
slub_debug=,dentry
slab_debug=,dentry
to only enable debugging on the dentry cache. You may use an asterisk at the
end of the slab name, in order to cover all slabs with the same prefix. For
example, here's how you can poison the dentry cache as well as all kmalloc
slabs::
slub_debug=P,kmalloc-*,dentry
slab_debug=P,kmalloc-*,dentry
Red zoning and tracking may realign the slab. We can just apply sanity checks
to the dentry cache with::
slub_debug=F,dentry
slab_debug=F,dentry
Debugging options may require the minimum possible slab order to increase as
a result of storing the metadata (for example, caches with PAGE_SIZE object
@@ -84,20 +84,20 @@ sizes). This has a higher liklihood of resulting in slab allocation errors
in low memory situations or if there's high fragmentation of memory. To
switch off debugging for such caches by default, use::
slub_debug=O
slab_debug=O
You can apply different options to different list of slab names, using blocks
of options. This will enable red zoning for dentry and user tracking for
kmalloc. All other slabs will not get any debugging enabled::
slub_debug=Z,dentry;U,kmalloc-*
slab_debug=Z,dentry;U,kmalloc-*
You can also enable options (e.g. sanity checks and poisoning) for all caches
except some that are deemed too performance critical and don't need to be
debugged by specifying global debug options followed by a list of slab names
with "-" as options::
slub_debug=FZ;-,zs_handle,zspage
slab_debug=FZ;-,zs_handle,zspage
The state of each debug option for a slab can be found in the respective files
under::
@@ -105,7 +105,7 @@ under::
/sys/kernel/slab/<slab name>/
If the file contains 1, the option is enabled, 0 means disabled. The debug
options from the ``slub_debug`` parameter translate to the following files::
options from the ``slab_debug`` parameter translate to the following files::
F sanity_checks
Z red_zone
@@ -129,7 +129,7 @@ in order to reduce overhead and increase cache hotness of objects.
Slab validation
===============
SLUB can validate all object if the kernel was booted with slub_debug. In
SLUB can validate all object if the kernel was booted with slab_debug. In
order to do so you must have the ``slabinfo`` tool. Then you can do
::
@@ -150,29 +150,29 @@ list_lock once in a while to deal with partial slabs. That overhead is
governed by the order of the allocation for each slab. The allocations
can be influenced by kernel parameters:
.. slub_min_objects=x (default 4)
.. slub_min_order=x (default 0)
.. slub_max_order=x (default 3 (PAGE_ALLOC_COSTLY_ORDER))
.. slab_min_objects=x (default: automatically scaled by number of cpus)
.. slab_min_order=x (default 0)
.. slab_max_order=x (default 3 (PAGE_ALLOC_COSTLY_ORDER))
``slub_min_objects``
``slab_min_objects``
allows to specify how many objects must at least fit into one
slab in order for the allocation order to be acceptable. In
general slub will be able to perform this number of
allocations on a slab without consulting centralized resources
(list_lock) where contention may occur.
``slub_min_order``
``slab_min_order``
specifies a minimum order of slabs. A similar effect like
``slub_min_objects``.
``slab_min_objects``.
``slub_max_order``
specified the order at which ``slub_min_objects`` should no
``slab_max_order``
specified the order at which ``slab_min_objects`` should no
longer be checked. This is useful to avoid SLUB trying to
generate super large order pages to fit ``slub_min_objects``
generate super large order pages to fit ``slab_min_objects``
of a slab cache with large object sizes into one high order
page. Setting command line parameter
``debug_guardpage_minorder=N`` (N > 0), forces setting
``slub_max_order`` to 0, what cause minimum possible order of
``slab_max_order`` to 0, what cause minimum possible order of
slabs allocation.
SLUB Debug output
@@ -219,7 +219,7 @@ Here is a sample of slub debug output::
FIX kmalloc-8: Restoring Redzone 0xc90f6d28-0xc90f6d2b=0xcc
If SLUB encounters a corrupted object (full detection requires the kernel
to be booted with slub_debug) then the following output will be dumped
to be booted with slab_debug) then the following output will be dumped
into the syslog:
1. Description of the problem encountered
@@ -239,7 +239,7 @@ into the syslog:
pid=<pid of the process>
(Object allocation / free information is only available if SLAB_STORE_USER is
set for the slab. slub_debug sets that option)
set for the slab. slab_debug sets that option)
2. The object contents if an object was involved.
@@ -262,7 +262,7 @@ into the syslog:
the object boundary.
(Redzone information is only available if SLAB_RED_ZONE is set.
slub_debug sets that option)
slab_debug sets that option)
Padding <address> : <bytes>
Unused data to fill up the space in order to get the next object
@@ -296,7 +296,7 @@ Emergency operations
Minimal debugging (sanity checks alone) can be enabled by booting with::
slub_debug=F
slab_debug=F
This will be generally be enough to enable the resiliency features of slub
which will keep the system running even if a bad kernel component will
@@ -311,13 +311,13 @@ and enabling debugging only for that cache
I.e.::
slub_debug=F,dentry
slab_debug=F,dentry
If the corruption occurs by writing after the end of the object then it
may be advisable to enable a Redzone to avoid corrupting the beginning
of other objects::
slub_debug=FZ,dentry
slab_debug=FZ,dentry
Extended slabinfo mode and plotting
===================================
Documentation/power/energy-model.rst
+179 -4
View File
@@ -71,6 +71,31 @@ whose performance is scaled together. Performance domains generally have a
required to have the same micro-architecture. CPUs in different performance
domains can have different micro-architectures.
To better reflect power variation due to static power (leakage) the EM
supports runtime modifications of the power values. The mechanism relies on
RCU to free the modifiable EM perf_state table memory. Its user, the task
scheduler, also uses RCU to access this memory. The EM framework provides
API for allocating/freeing the new memory for the modifiable EM table.
The old memory is freed automatically using RCU callback mechanism when there
are no owners anymore for the given EM runtime table instance. This is tracked
using kref mechanism. The device driver which provided the new EM at runtime,
should call EM API to free it safely when it's no longer needed. The EM
framework will handle the clean-up when it's possible.
The kernel code which want to modify the EM values is protected from concurrent
access using a mutex. Therefore, the device driver code must run in sleeping
context when it tries to modify the EM.
With the runtime modifiable EM we switch from a 'single and during the entire
runtime static EM' (system property) design to a 'single EM which can be
changed during runtime according e.g. to the workload' (system and workload
property) design.
It is possible also to modify the CPU performance values for each EM's
performance state. Thus, the full power and performance profile (which
is an exponential curve) can be changed according e.g. to the workload
or system property.
2. Core APIs
------------
@@ -175,10 +200,82 @@ CPUfreq governor is in use in case of CPU device. Currently this calculation is
not provided for other type of devices.
More details about the above APIs can be found in ``<linux/energy_model.h>``
or in Section 2.4
or in Section 2.5
2.4 Description details of this API
2.4 Runtime modifications
^^^^^^^^^^^^^^^^^^^^^^^^^
Drivers willing to update the EM at runtime should use the following dedicated
function to allocate a new instance of the modified EM. The API is listed
below::
struct em_perf_table __rcu *em_table_alloc(struct em_perf_domain *pd);
This allows to allocate a structure which contains the new EM table with
also RCU and kref needed by the EM framework. The 'struct em_perf_table'
contains array 'struct em_perf_state state[]' which is a list of performance
states in ascending order. That list must be populated by the device driver
which wants to update the EM. The list of frequencies can be taken from
existing EM (created during boot). The content in the 'struct em_perf_state'
must be populated by the driver as well.
This is the API which does the EM update, using RCU pointers swap::
int em_dev_update_perf_domain(struct device *dev,
struct em_perf_table __rcu *new_table);
Drivers must provide a pointer to the allocated and initialized new EM
'struct em_perf_table'. That new EM will be safely used inside the EM framework
and will be visible to other sub-systems in the kernel (thermal, powercap).
The main design goal for this API is to be fast and avoid extra calculations
or memory allocations at runtime. When pre-computed EMs are available in the
device driver, than it should be possible to simply re-use them with low
performance overhead.
In order to free the EM, provided earlier by the driver (e.g. when the module
is unloaded), there is a need to call the API::
void em_table_free(struct em_perf_table __rcu *table);
It will allow the EM framework to safely remove the memory, when there is
no other sub-system using it, e.g. EAS.
To use the power values in other sub-systems (like thermal, powercap) there is
a need to call API which protects the reader and provide consistency of the EM
table data::
struct em_perf_state *em_perf_state_from_pd(struct em_perf_domain *pd);
It returns the 'struct em_perf_state' pointer which is an array of performance
states in ascending order.
This function must be called in the RCU read lock section (after the
rcu_read_lock()). When the EM table is not needed anymore there is a need to
call rcu_real_unlock(). In this way the EM safely uses the RCU read section
and protects the users. It also allows the EM framework to manage the memory
and free it. More details how to use it can be found in Section 3.2 in the
example driver.
There is dedicated API for device drivers to calculate em_perf_state::cost
values::
int em_dev_compute_costs(struct device *dev, struct em_perf_state *table,
int nr_states);
These 'cost' values from EM are used in EAS. The new EM table should be passed
together with the number of entries and device pointer. When the computation
of the cost values is done properly the return value from the function is 0.
The function takes care for right setting of inefficiency for each performance
state as well. It updates em_perf_state::flags accordingly.
Then such prepared new EM can be passed to the em_dev_update_perf_domain()
function, which will allow to use it.
More details about the above APIs can be found in ``<linux/energy_model.h>``
or in Section 3.2 with an example code showing simple implementation of the
updating mechanism in a device driver.
2.5 Description details of this API
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
.. kernel-doc:: include/linux/energy_model.h
:internal:
@@ -187,8 +284,11 @@ or in Section 2.4
:export:
3. Example driver
-----------------
3. Examples
-----------
3.1 Example driver with EM registration
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
The CPUFreq framework supports dedicated callback for registering
the EM for a given CPU(s) 'policy' object: cpufreq_driver::register_em().
@@ -242,3 +342,78 @@ EM framework::
39 static struct cpufreq_driver foo_cpufreq_driver = {
40 .register_em = foo_cpufreq_register_em,
41 };
3.2 Example driver with EM modification
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
This section provides a simple example of a thermal driver modifying the EM.
The driver implements a foo_thermal_em_update() function. The driver is woken
up periodically to check the temperature and modify the EM data::
-> drivers/soc/example/example_em_mod.c
01 static void foo_get_new_em(struct foo_context *ctx)
02 {
03 struct em_perf_table __rcu *em_table;
04 struct em_perf_state *table, *new_table;
05 struct device *dev = ctx->dev;
06 struct em_perf_domain *pd;
07 unsigned long freq;
08 int i, ret;
09
10 pd = em_pd_get(dev);
11 if (!pd)
12 return;
13
14 em_table = em_table_alloc(pd);
15 if (!em_table)
16 return;
17
18 new_table = em_table->state;
19
20 rcu_read_lock();
21 table = em_perf_state_from_pd(pd);
22 for (i = 0; i < pd->nr_perf_states; i++) {
23 freq = table[i].frequency;
24 foo_get_power_perf_values(dev, freq, &new_table[i]);
25 }
26 rcu_read_unlock();
27
28 /* Calculate 'cost' values for EAS */
29 ret = em_dev_compute_costs(dev, table, pd->nr_perf_states);
30 if (ret) {
31 dev_warn(dev, "EM: compute costs failed %d\n", ret);
32 em_free_table(em_table);
33 return;
34 }
35
36 ret = em_dev_update_perf_domain(dev, em_table);
37 if (ret) {
38 dev_warn(dev, "EM: update failed %d\n", ret);
39 em_free_table(em_table);
40 return;
41 }
42
43 /*
44 * Since it's one-time-update drop the usage counter.
45 * The EM framework will later free the table when needed.
46 */
47 em_table_free(em_table);
48 }
49
50 /*
51 * Function called periodically to check the temperature and
52 * update the EM if needed
53 */
54 static void foo_thermal_em_update(struct foo_context *ctx)
55 {
56 struct device *dev = ctx->dev;
57 int cpu;
58
59 ctx->temperature = foo_get_temp(dev, ctx);
60 if (ctx->temperature < FOO_EM_UPDATE_TEMP_THRESHOLD)
61 return;
62
63 foo_get_new_em(ctx);
64 }
Documentation/power/opp.rst
+1 -1
View File
@@ -305,7 +305,7 @@ dev_pm_opp_get_opp_count
{
/* Do things */
num_available = dev_pm_opp_get_opp_count(dev);
speeds = kzalloc(sizeof(u32) * num_available, GFP_KERNEL);
speeds = kcalloc(num_available, sizeof(u32), GFP_KERNEL);
/* populate the table in increasing order */
freq = 0;
while (!IS_ERR(opp = dev_pm_opp_find_freq_ceil(dev, &freq))) {
Documentation/power/pci.rst
+1 -1
View File
@@ -625,7 +625,7 @@ The PCI subsystem-level callbacks they correspond to::
pci_pm_poweroff()
pci_pm_poweroff_noirq()
work in analogy with pci_pm_suspend() and pci_pm_poweroff_noirq(), respectively,
work in analogy with pci_pm_suspend() and pci_pm_suspend_noirq(), respectively,
although they don't attempt to save the device's standard configuration
registers.
Documentation/power/runtime_pm.rst
+14 -9
View File
@@ -154,7 +154,7 @@ suspending the device are satisfied) and to queue up a suspend request for the
device in that case. If there is no idle callback, or if the callback returns
0, then the PM core will attempt to carry out a runtime suspend of the device,
also respecting devices configured for autosuspend. In essence this means a
call to pm_runtime_autosuspend() (do note that drivers needs to update the
call to __pm_runtime_autosuspend() (do note that drivers needs to update the
device last busy mark, pm_runtime_mark_last_busy(), to control the delay under
this circumstance). To prevent this (for example, if the callback routine has
started a delayed suspend), the routine must return a non-zero value. Negative
@@ -396,10 +396,9 @@ drivers/base/power/runtime.c and include/linux/pm_runtime.h:
nonzero, increment the counter and return 1; otherwise return 0 without
changing the counter
`int pm_runtime_get_if_active(struct device *dev, bool ign_usage_count);`
`int pm_runtime_get_if_active(struct device *dev);`
- return -EINVAL if 'power.disable_depth' is nonzero; otherwise, if the
runtime PM status is RPM_ACTIVE, and either ign_usage_count is true
or the device's usage_count is non-zero, increment the counter and
runtime PM status is RPM_ACTIVE, increment the counter and
return 1; otherwise return 0 without changing the counter
`void pm_runtime_put_noidle(struct device *dev);`
@@ -410,6 +409,10 @@ drivers/base/power/runtime.c and include/linux/pm_runtime.h:
pm_request_idle(dev) and return its result
`int pm_runtime_put_autosuspend(struct device *dev);`
- does the same as __pm_runtime_put_autosuspend() for now, but in the
future, will also call pm_runtime_mark_last_busy() as well, DO NOT USE!
`int __pm_runtime_put_autosuspend(struct device *dev);`
- decrement the device's usage counter; if the result is 0 then run
pm_request_autosuspend(dev) and return its result
@@ -540,6 +543,7 @@ It is safe to execute the following helper functions from interrupt context:
- pm_runtime_put_noidle()
- pm_runtime_put()
- pm_runtime_put_autosuspend()
- __pm_runtime_put_autosuspend()
- pm_runtime_enable()
- pm_suspend_ignore_children()
- pm_runtime_set_active()
@@ -730,6 +734,7 @@ out the following operations:
for it, respectively.
7. Generic subsystem callbacks
==============================
Subsystems may wish to conserve code space by using the set of generic power
management callbacks provided by the PM core, defined in
@@ -865,9 +870,9 @@ automatically be delayed until the desired period of inactivity has elapsed.
Inactivity is determined based on the power.last_busy field. Drivers should
call pm_runtime_mark_last_busy() to update this field after carrying out I/O,
typically just before calling pm_runtime_put_autosuspend(). The desired length
of the inactivity period is a matter of policy. Subsystems can set this length
initially by calling pm_runtime_set_autosuspend_delay(), but after device
typically just before calling __pm_runtime_put_autosuspend(). The desired
length of the inactivity period is a matter of policy. Subsystems can set this
length initially by calling pm_runtime_set_autosuspend_delay(), but after device
registration the length should be controlled by user space, using the
/sys/devices/.../power/autosuspend_delay_ms attribute.
@@ -878,7 +883,7 @@ instead of the non-autosuspend counterparts::
Instead of: pm_runtime_suspend use: pm_runtime_autosuspend;
Instead of: pm_schedule_suspend use: pm_request_autosuspend;
Instead of: pm_runtime_put use: pm_runtime_put_autosuspend;
Instead of: pm_runtime_put use: __pm_runtime_put_autosuspend;
Instead of: pm_runtime_put_sync use: pm_runtime_put_sync_autosuspend.
Drivers may also continue to use the non-autosuspend helper functions; they
@@ -917,7 +922,7 @@ Here is a schematic pseudo-code example::
lock(&foo->private_lock);
if (--foo->num_pending_requests == 0) {
pm_runtime_mark_last_busy(&foo->dev);
pm_runtime_put_autosuspend(&foo->dev);
__pm_runtime_put_autosuspend(&foo->dev);
} else {
foo_process_next_request(foo);
}
Documentation/spi/spi-summary.rst
+57 -57
View File
@@ -9,7 +9,7 @@ What is SPI?
The "Serial Peripheral Interface" (SPI) is a synchronous four wire serial
link used to connect microcontrollers to sensors, memory, and peripherals.
It's a simple "de facto" standard, not complicated enough to acquire a
standardization body. SPI uses a master/slave configuration.
standardization body. SPI uses a host/target configuration.
The three signal wires hold a clock (SCK, often on the order of 10 MHz),
and parallel data lines with "Master Out, Slave In" (MOSI) or "Master In,
@@ -19,14 +19,14 @@ commonly used. Each clock cycle shifts data out and data in; the clock
doesn't cycle except when there is a data bit to shift. Not all data bits
are used though; not every protocol uses those full duplex capabilities.
SPI masters use a fourth "chip select" line to activate a given SPI slave
SPI hosts use a fourth "chip select" line to activate a given SPI target
device, so those three signal wires may be connected to several chips
in parallel. All SPI slaves support chipselects; they are usually active
low signals, labeled nCSx for slave 'x' (e.g. nCS0). Some devices have
other signals, often including an interrupt to the master.
in parallel. All SPI targets support chipselects; they are usually active
low signals, labeled nCSx for target 'x' (e.g. nCS0). Some devices have
other signals, often including an interrupt to the host.
Unlike serial busses like USB or SMBus, even low level protocols for
SPI slave functions are usually not interoperable between vendors
SPI target functions are usually not interoperable between vendors
(except for commodities like SPI memory chips).
- SPI may be used for request/response style device protocols, as with
@@ -43,10 +43,10 @@ SPI slave functions are usually not interoperable between vendors
- Sometimes SPI is used to daisy-chain devices, like shift registers.
In the same way, SPI slaves will only rarely support any kind of automatic
discovery/enumeration protocol. The tree of slave devices accessible from
a given SPI master will normally be set up manually, with configuration
tables.
In the same way, SPI targets will only rarely support any kind of automatic
discovery/enumeration protocol. The tree of target devices accessible from
a given SPI host controller will normally be set up manually, with
configuration tables.
SPI is only one of the names used by such four-wire protocols, and
most controllers have no problem handling "MicroWire" (think of it as
@@ -62,8 +62,8 @@ course they won't handle full duplex transfers. You may find such
chips described as using "three wire" signaling: SCK, data, nCSx.
(That data line is sometimes called MOMI or SISO.)
Microcontrollers often support both master and slave sides of the SPI
protocol. This document (and Linux) supports both the master and slave
Microcontrollers often support both host and target sides of the SPI
protocol. This document (and Linux) supports both the host and target
sides of SPI interactions.
@@ -75,7 +75,7 @@ protocol supported by every MMC or SD memory card. (The older "DataFlash"
cards, predating MMC cards but using the same connectors and card shape,
support only SPI.) Some PC hardware uses SPI flash for BIOS code.
SPI slave chips range from digital/analog converters used for analog
SPI target chips range from digital/analog converters used for analog
sensors and codecs, to memory, to peripherals like USB controllers
or Ethernet adapters; and more.
@@ -118,8 +118,8 @@ starting low (CPOL=0) and data stabilized for sampling during the
trailing clock edge (CPHA=1), that's SPI mode 1.
Note that the clock mode is relevant as soon as the chipselect goes
active. So the master must set the clock to inactive before selecting
a slave, and the slave can tell the chosen polarity by sampling the
active. So the host must set the clock to inactive before selecting
a target, and the target can tell the chosen polarity by sampling the
clock level when its select line goes active. That's why many devices
support for example both modes 0 and 3: they don't care about polarity,
and always clock data in/out on rising clock edges.
@@ -142,13 +142,13 @@ There are two types of SPI driver, here called:
Controller drivers ...
controllers may be built into System-On-Chip
processors, and often support both Master and Slave roles.
processors, and often support both Controller and target roles.
These drivers touch hardware registers and may use DMA.
Or they can be PIO bitbangers, needing just GPIO pins.
Protocol drivers ...
these pass messages through the controller
driver to communicate with a Slave or Master device on the
driver to communicate with a target or Controller device on the
other side of an SPI link.
So for example one protocol driver might talk to the MTD layer to export
@@ -179,22 +179,22 @@ shows up in sysfs in several locations::
/sys/bus/spi/drivers/D ... driver for one or more spi*.* devices
/sys/class/spi_master/spiB ... symlink to a logical node which could hold
class related state for the SPI master controller managing bus "B".
class related state for the SPI host controller managing bus "B".
All spiB.* devices share one physical SPI bus segment, with SCLK,
MOSI, and MISO.
/sys/devices/.../CTLR/slave ... virtual file for (un)registering the
slave device for an SPI slave controller.
Writing the driver name of an SPI slave handler to this file
registers the slave device; writing "(null)" unregisters the slave
target device for an SPI target controller.
Writing the driver name of an SPI target handler to this file
registers the target device; writing "(null)" unregisters the target
device.
Reading from this file shows the name of the slave device ("(null)"
Reading from this file shows the name of the target device ("(null)"
if not registered).
/sys/class/spi_slave/spiB ... symlink to a logical node which could hold
class related state for the SPI slave controller on bus "B". When
class related state for the SPI target controller on bus "B". When
registered, a single spiB.* device is present here, possible sharing
the physical SPI bus segment with other SPI slave devices.
the physical SPI bus segment with other SPI target devices.
At this time, the only class-specific state is the bus number ("B" in "spiB"),
so those /sys/class entries are only useful to quickly identify busses.
@@ -270,10 +270,10 @@ same SOC controller is used. For example, on one board SPI might use
an external clock, where another derives the SPI clock from current
settings of some master clock.
Declare Slave Devices
^^^^^^^^^^^^^^^^^^^^^
Declare target Devices
^^^^^^^^^^^^^^^^^^^^^^
The second kind of information is a list of what SPI slave devices exist
The second kind of information is a list of what SPI target devices exist
on the target board, often with some board-specific data needed for the
driver to work correctly.
@@ -316,7 +316,7 @@ sharing a bus with a device that interprets chipselect "backwards" is
not possible until the infrastructure knows how to deselect it.
Then your board initialization code would register that table with the SPI
infrastructure, so that it's available later when the SPI master controller
infrastructure, so that it's available later when the SPI host controller
driver is registered::
spi_register_board_info(spi_board_info, ARRAY_SIZE(spi_board_info));
@@ -469,39 +469,39 @@ routines are available to allocate and zero-initialize an spi_message
with several transfers.
How do I write an "SPI Master Controller Driver"?
How do I write an "SPI Controller Driver"?
-------------------------------------------------
An SPI controller will probably be registered on the platform_bus; write
a driver to bind to the device, whichever bus is involved.
The main task of this type of driver is to provide an "spi_master".
Use spi_alloc_master() to allocate the master, and spi_master_get_devdata()
to get the driver-private data allocated for that device.
The main task of this type of driver is to provide an "spi_controller".
Use spi_alloc_host() to allocate the host controller, and
spi_controller_get_devdata() to get the driver-private data allocated for that
device.
::
struct spi_master *master;
struct spi_controller *ctlr;
struct CONTROLLER *c;
master = spi_alloc_master(dev, sizeof *c);
if (!master)
ctlr = spi_alloc_host(dev, sizeof *c);
if (!ctlr)
return -ENODEV;
c = spi_master_get_devdata(master);
c = spi_controller_get_devdata(ctlr);
The driver will initialize the fields of that spi_master, including the
bus number (maybe the same as the platform device ID) and three methods
used to interact with the SPI core and SPI protocol drivers. It will
also initialize its own internal state. (See below about bus numbering
and those methods.)
The driver will initialize the fields of that spi_controller, including the bus
number (maybe the same as the platform device ID) and three methods used to
interact with the SPI core and SPI protocol drivers. It will also initialize
its own internal state. (See below about bus numbering and those methods.)
After you initialize the spi_master, then use spi_register_master() to
After you initialize the spi_controller, then use spi_register_controller() to
publish it to the rest of the system. At that time, device nodes for the
controller and any predeclared spi devices will be made available, and
the driver model core will take care of binding them to drivers.
If you need to remove your SPI controller driver, spi_unregister_master()
will reverse the effect of spi_register_master().
If you need to remove your SPI controller driver, spi_unregister_controller()
will reverse the effect of spi_register_controller().
Bus Numbering
@@ -519,49 +519,49 @@ then be replaced by a dynamically assigned number. You'd then need to treat
this as a non-static configuration (see above).
SPI Master Methods
^^^^^^^^^^^^^^^^^^
SPI Host Controller Methods
^^^^^^^^^^^^^^^^^^^^^^^^^^^
``master->setup(struct spi_device *spi)``
``ctlr->setup(struct spi_device *spi)``
This sets up the device clock rate, SPI mode, and word sizes.
Drivers may change the defaults provided by board_info, and then
call spi_setup(spi) to invoke this routine. It may sleep.
Unless each SPI slave has its own configuration registers, don't
Unless each SPI target has its own configuration registers, don't
change them right away ... otherwise drivers could corrupt I/O
that's in progress for other SPI devices.
.. note::
BUG ALERT: for some reason the first version of
many spi_master drivers seems to get this wrong.
many spi_controller drivers seems to get this wrong.
When you code setup(), ASSUME that the controller
is actively processing transfers for another device.
``master->cleanup(struct spi_device *spi)``
``ctlr->cleanup(struct spi_device *spi)``
Your controller driver may use spi_device.controller_state to hold
state it dynamically associates with that device. If you do that,
be sure to provide the cleanup() method to free that state.
``master->prepare_transfer_hardware(struct spi_master *master)``
``ctlr->prepare_transfer_hardware(struct spi_controller *ctlr)``
This will be called by the queue mechanism to signal to the driver
that a message is coming in soon, so the subsystem requests the
driver to prepare the transfer hardware by issuing this call.
This may sleep.
``master->unprepare_transfer_hardware(struct spi_master *master)``
``ctlr->unprepare_transfer_hardware(struct spi_controller *ctlr)``
This will be called by the queue mechanism to signal to the driver
that there are no more messages pending in the queue and it may
relax the hardware (e.g. by power management calls). This may sleep.
``master->transfer_one_message(struct spi_master *master, struct spi_message *mesg)``
``ctlr->transfer_one_message(struct spi_controller *ctlr, struct spi_message *mesg)``
The subsystem calls the driver to transfer a single message while
queuing transfers that arrive in the meantime. When the driver is
finished with this message, it must call
spi_finalize_current_message() so the subsystem can issue the next
message. This may sleep.
``master->transfer_one(struct spi_master *master, struct spi_device *spi, struct spi_transfer *transfer)``
``ctrl->transfer_one(struct spi_controller *ctlr, struct spi_device *spi, struct spi_transfer *transfer)``
The subsystem calls the driver to transfer a single transfer while
queuing transfers that arrive in the meantime. When the driver is
finished with this transfer, it must call
@@ -576,15 +576,15 @@ SPI Master Methods
* 0: transfer is finished
* 1: transfer is still in progress
``master->set_cs_timing(struct spi_device *spi, u8 setup_clk_cycles, u8 hold_clk_cycles, u8 inactive_clk_cycles)``
This method allows SPI client drivers to request SPI master controller
``ctrl->set_cs_timing(struct spi_device *spi, u8 setup_clk_cycles, u8 hold_clk_cycles, u8 inactive_clk_cycles)``
This method allows SPI client drivers to request SPI host controller
for configuring device specific CS setup, hold and inactive timing
requirements.
Deprecated Methods
^^^^^^^^^^^^^^^^^^
``master->transfer(struct spi_device *spi, struct spi_message *message)``
``ctrl->transfer(struct spi_device *spi, struct spi_message *message)``
This must not sleep. Its responsibility is to arrange that the
transfer happens and its complete() callback is issued. The two
will normally happen later, after other transfers complete, and
Documentation/translations/zh_CN/power/opp.rst
+1 -1
View File
@@ -274,7 +274,7 @@ dev_pm_opp_get_opp_count
{
/* 做一些事情 */
num_available = dev_pm_opp_get_opp_count(dev);
speeds = kzalloc(sizeof(u32) * num_available, GFP_KERNEL);
speeds = kcalloc(num_available, sizeof(u32), GFP_KERNEL);
/* 按升序填充表 */
freq = 0;
while (!IS_ERR(opp = dev_pm_opp_find_freq_ceil(dev, &freq))) {
Documentation/userspace-api/gpio/chardev.rst
+116
View File
@@ -0,0 +1,116 @@
.. SPDX-License-Identifier: GPL-2.0
===================================
GPIO Character Device Userspace API
===================================
This is latest version (v2) of the character device API, as defined in
``include/uapi/linux/gpio.h.``
First added in 5.10.
.. note::
Do NOT abuse userspace APIs to control hardware that has proper kernel
drivers. There may already be a driver for your use case, and an existing
kernel driver is sure to provide a superior solution to bitbashing
from userspace.
Read Documentation/driver-api/gpio/drivers-on-gpio.rst to avoid reinventing
kernel wheels in userspace.
Similarly, for multi-function lines there may be other subsystems, such as
Documentation/spi/index.rst, Documentation/i2c/index.rst,
Documentation/driver-api/pwm.rst, Documentation/w1/index.rst etc, that
provide suitable drivers and APIs for your hardware.
Basic examples using the character device API can be found in ``tools/gpio/*``.
The API is based around two major objects, the :ref:`gpio-v2-chip` and the
:ref:`gpio-v2-line-request`.
.. _gpio-v2-chip:
Chip
====
The Chip represents a single GPIO chip and is exposed to userspace using device
files of the form ``/dev/gpiochipX``.
Each chip supports a number of GPIO lines,
:c:type:`chip.lines<gpiochip_info>`. Lines on the chip are identified by an
``offset`` in the range from 0 to ``chip.lines - 1``, i.e. `[0,chip.lines)`.
Lines are requested from the chip using gpio-v2-get-line-ioctl.rst
and the resulting line request is used to access the GPIO chip's lines or
monitor the lines for edge events.
Within this documentation, the file descriptor returned by calling `open()`
on the GPIO device file is referred to as ``chip_fd``.
Operations
----------
The following operations may be performed on the chip:
.. toctree::
:titlesonly:
Get Line <gpio-v2-get-line-ioctl>
Get Chip Info <gpio-get-chipinfo-ioctl>
Get Line Info <gpio-v2-get-lineinfo-ioctl>
Watch Line Info <gpio-v2-get-lineinfo-watch-ioctl>
Unwatch Line Info <gpio-get-lineinfo-unwatch-ioctl>
Read Line Info Changed Events <gpio-v2-lineinfo-changed-read>
.. _gpio-v2-line-request:
Line Request
============
Line requests are created by gpio-v2-get-line-ioctl.rst and provide
access to a set of requested lines. The line request is exposed to userspace
via the anonymous file descriptor returned in
:c:type:`request.fd<gpio_v2_line_request>` by gpio-v2-get-line-ioctl.rst.
Within this documentation, the line request file descriptor is referred to
as ``req_fd``.
Operations
----------
The following operations may be performed on the line request:
.. toctree::
:titlesonly:
Get Line Values <gpio-v2-line-get-values-ioctl>
Set Line Values <gpio-v2-line-set-values-ioctl>
Read Line Edge Events <gpio-v2-line-event-read>
Reconfigure Lines <gpio-v2-line-set-config-ioctl>
Types
=====
This section contains the structs and enums that are referenced by the API v2,
as defined in ``include/uapi/linux/gpio.h``.
.. kernel-doc:: include/uapi/linux/gpio.h
:identifiers:
gpio_v2_line_attr_id
gpio_v2_line_attribute
gpio_v2_line_changed_type
gpio_v2_line_config
gpio_v2_line_config_attribute
gpio_v2_line_event
gpio_v2_line_event_id
gpio_v2_line_flag
gpio_v2_line_info
gpio_v2_line_info_changed
gpio_v2_line_request
gpio_v2_line_values
gpiochip_info
.. toctree::
:hidden:
error-codes
Documentation/userspace-api/gpio/chardev_v1.rst
+131
View File
@@ -0,0 +1,131 @@
.. SPDX-License-Identifier: GPL-2.0
========================================
GPIO Character Device Userspace API (v1)
========================================
.. warning::
This API is obsoleted by chardev.rst (v2).
New developments should use the v2 API, and existing developments are
encouraged to migrate as soon as possible, as this API will be removed
in the future. The v2 API is a functional superset of the v1 API so any
v1 call can be directly translated to a v2 equivalent.
This interface will continue to be maintained for the migration period,
but new features will only be added to the new API.
First added in 4.8.
The API is based around three major objects, the :ref:`gpio-v1-chip`, the
:ref:`gpio-v1-line-handle`, and the :ref:`gpio-v1-line-event`.
Where "line event" is used in this document it refers to the request that can
monitor a line for edge events, not the edge events themselves.
.. _gpio-v1-chip:
Chip
====
The Chip represents a single GPIO chip and is exposed to userspace using device
files of the form ``/dev/gpiochipX``.
Each chip supports a number of GPIO lines,
:c:type:`chip.lines<gpiochip_info>`. Lines on the chip are identified by an
``offset`` in the range from 0 to ``chip.lines - 1``, i.e. `[0,chip.lines)`.
Lines are requested from the chip using either gpio-get-linehandle-ioctl.rst
and the resulting line handle is used to access the GPIO chip's lines, or
gpio-get-lineevent-ioctl.rst and the resulting line event is used to monitor
a GPIO line for edge events.
Within this documentation, the file descriptor returned by calling `open()`
on the GPIO device file is referred to as ``chip_fd``.
Operations
----------
The following operations may be performed on the chip:
.. toctree::
:titlesonly:
Get Line Handle <gpio-get-linehandle-ioctl>
Get Line Event <gpio-get-lineevent-ioctl>
Get Chip Info <gpio-get-chipinfo-ioctl>
Get Line Info <gpio-get-lineinfo-ioctl>
Watch Line Info <gpio-get-lineinfo-watch-ioctl>
Unwatch Line Info <gpio-get-lineinfo-unwatch-ioctl>
Read Line Info Changed Events <gpio-lineinfo-changed-read>
.. _gpio-v1-line-handle:
Line Handle
===========
Line handles are created by gpio-get-linehandle-ioctl.rst and provide
access to a set of requested lines. The line handle is exposed to userspace
via the anonymous file descriptor returned in
:c:type:`request.fd<gpiohandle_request>` by gpio-get-linehandle-ioctl.rst.
Within this documentation, the line handle file descriptor is referred to
as ``handle_fd``.
Operations
----------
The following operations may be performed on the line handle:
.. toctree::
:titlesonly:
Get Line Values <gpio-handle-get-line-values-ioctl>
Set Line Values <gpio-handle-set-line-values-ioctl>
Reconfigure Lines <gpio-handle-set-config-ioctl>
.. _gpio-v1-line-event:
Line Event
==========
Line events are created by gpio-get-lineevent-ioctl.rst and provide
access to a requested line. The line event is exposed to userspace
via the anonymous file descriptor returned in
:c:type:`request.fd<gpioevent_request>` by gpio-get-lineevent-ioctl.rst.
Within this documentation, the line event file descriptor is referred to
as ``event_fd``.
Operations
----------
The following operations may be performed on the line event:
.. toctree::
:titlesonly:
Get Line Value <gpio-handle-get-line-values-ioctl>
Read Line Edge Events <gpio-lineevent-data-read>
Types
=====
This section contains the structs that are referenced by the ABI v1.
The :c:type:`struct gpiochip_info<gpiochip_info>` is common to ABI v1 and v2.
.. kernel-doc:: include/uapi/linux/gpio.h
:identifiers:
gpioevent_data
gpioevent_request
gpiohandle_config
gpiohandle_data
gpiohandle_request
gpioline_info
gpioline_info_changed
.. toctree::
:hidden:
error-codes
Documentation/userspace-api/gpio/error-codes.rst
+79
View File
@@ -0,0 +1,79 @@
.. SPDX-License-Identifier: GPL-2.0
.. _gpio_errors:
*******************
GPIO Error Codes
*******************
.. _gpio-errors:
.. tabularcolumns:: |p{2.5cm}|p{15.0cm}|
.. flat-table:: Common GPIO error codes
:header-rows: 0
:stub-columns: 0
:widths: 1 16
- - ``EAGAIN`` (aka ``EWOULDBLOCK``)
- The device was opened in non-blocking mode and a read can't
be performed as there is no data available.
- - ``EBADF``
- The file descriptor is not valid.
- - ``EBUSY``
- The ioctl can't be handled because the device is busy. Typically
returned when an ioctl attempts something that would require the
usage of a resource that was already allocated. The ioctl must not
be retried without performing another action to fix the problem
first.
- - ``EFAULT``
- There was a failure while copying data from/to userspace, probably
caused by an invalid pointer reference.
- - ``EINVAL``
- One or more of the ioctl parameters are invalid or out of the
allowed range. This is a widely used error code.
- - ``ENODEV``
- Device not found or was removed.
- - ``ENOMEM``
- There's not enough memory to handle the desired operation.
- - ``EPERM``
- Permission denied. Typically returned in response to an attempt
to perform an action incompatible with the current line
configuration.
- - ``EIO``
- I/O error. Typically returned when there are problems communicating
with a hardware device or requesting features that hardware does not
support. This could indicate broken or flaky hardware.
It's a 'Something is wrong, I give up!' type of error.
- - ``ENXIO``
- Typically returned when a feature requiring interrupt support was
requested, but the line does not support interrupts.
.. note::
#. This list is not exhaustive; ioctls may return other error codes.
Since errors may have side effects such as a driver reset,
applications should abort on unexpected errors, or otherwise
assume that the device is in a bad state.
#. Request-specific error codes are listed in the individual
requests descriptions.
Documentation/userspace-api/gpio/gpio-get-chipinfo-ioctl.rst
+41
View File
@@ -0,0 +1,41 @@
.. SPDX-License-Identifier: GPL-2.0
.. _GPIO_GET_CHIPINFO_IOCTL:
***********************
GPIO_GET_CHIPINFO_IOCTL
***********************
Name
====
GPIO_GET_CHIPINFO_IOCTL - Get the publicly available information for a chip.
Synopsis
========
.. c:macro:: GPIO_GET_CHIPINFO_IOCTL
``int ioctl(int chip_fd, GPIO_GET_CHIPINFO_IOCTL, struct gpiochip_info *info)``
Arguments
=========
``chip_fd``
The file descriptor of the GPIO character device returned by `open()`.
``info``
The :c:type:`chip_info<gpiochip_info>` to be populated.
Description
===========
Gets the publicly available information for a particular GPIO chip.
Return Value
============
On success 0 and ``info`` is populated with the chip info.
On error -1 and the ``errno`` variable is set appropriately.
Common error codes are described in error-codes.rst.
Documentation/userspace-api/gpio/gpio-get-lineevent-ioctl.rst
+84
View File
@@ -0,0 +1,84 @@
.. SPDX-License-Identifier: GPL-2.0
.. _GPIO_GET_LINEEVENT_IOCTL:
************************
GPIO_GET_LINEEVENT_IOCTL
************************
.. warning::
This ioctl is part of chardev_v1.rst and is obsoleted by
gpio-v2-get-line-ioctl.rst.
Name
====
GPIO_GET_LINEEVENT_IOCTL - Request a line with edge detection from the kernel.
Synopsis
========
.. c:macro:: GPIO_GET_LINEEVENT_IOCTL
``int ioctl(int chip_fd, GPIO_GET_LINEEVENT_IOCTL, struct gpioevent_request *request)``
Arguments
=========
``chip_fd``
The file descriptor of the GPIO character device returned by `open()`.
``request``
The :c:type:`event_request<gpioevent_request>` specifying the line
to request and its configuration.
Description
===========
Request a line with edge detection from the kernel.
On success, the requesting process is granted exclusive access to the line
value and may receive events when edges are detected on the line, as
described in gpio-lineevent-data-read.rst.
The state of a line is guaranteed to remain as requested until the returned
file descriptor is closed. Once the file descriptor is closed, the state of
the line becomes uncontrolled from the userspace perspective, and may revert
to its default state.
Requesting a line already in use is an error (**EBUSY**).
Requesting edge detection on a line that does not support interrupts is an
error (**ENXIO**).
As with the :ref:`line handle<gpio-get-linehandle-config-support>`, the
bias configuration is best effort.
Closing the ``chip_fd`` has no effect on existing line events.
Configuration Rules
-------------------
The following configuration rules apply:
The line event is requested as an input, so no flags specific to output lines,
``GPIOHANDLE_REQUEST_OUTPUT``, ``GPIOHANDLE_REQUEST_OPEN_DRAIN``, or
``GPIOHANDLE_REQUEST_OPEN_SOURCE``, may be set.
Only one bias flag, ``GPIOHANDLE_REQUEST_BIAS_xxx``, may be set.
If no bias flags are set then the bias configuration is not changed.
The edge flags, ``GPIOEVENT_REQUEST_RISING_EDGE`` and
``GPIOEVENT_REQUEST_FALLING_EDGE``, may be combined to detect both rising
and falling edges.
Requesting an invalid configuration is an error (**EINVAL**).
Return Value
============
On success 0 and the :c:type:`request.fd<gpioevent_request>` contains the file
descriptor for the request.
On error -1 and the ``errno`` variable is set appropriately.
Common error codes are described in error-codes.rst.
Documentation/userspace-api/gpio/gpio-get-linehandle-ioctl.rst
+125
View File
@@ -0,0 +1,125 @@
.. SPDX-License-Identifier: GPL-2.0
.. _GPIO_GET_LINEHANDLE_IOCTL:
*************************
GPIO_GET_LINEHANDLE_IOCTL
*************************
.. warning::
This ioctl is part of chardev_v1.rst and is obsoleted by
gpio-v2-get-line-ioctl.rst.
Name
====
GPIO_GET_LINEHANDLE_IOCTL - Request a line or lines from the kernel.
Synopsis
========
.. c:macro:: GPIO_GET_LINEHANDLE_IOCTL
``int ioctl(int chip_fd, GPIO_GET_LINEHANDLE_IOCTL, struct gpiohandle_request *request)``
Arguments
=========
``chip_fd``
The file descriptor of the GPIO character device returned by `open()`.
``request``
The :c:type:`handle_request<gpiohandle_request>` specifying the lines to
request and their configuration.
Description
===========
Request a line or lines from the kernel.
While multiple lines may be requested, the same configuration applies to all
lines in the request.
On success, the requesting process is granted exclusive access to the line
value and write access to the line configuration.
The state of a line, including the value of output lines, is guaranteed to
remain as requested until the returned file descriptor is closed. Once the
file descriptor is closed, the state of the line becomes uncontrolled from
the userspace perspective, and may revert to its default state.
Requesting a line already in use is an error (**EBUSY**).
Closing the ``chip_fd`` has no effect on existing line handles.
.. _gpio-get-linehandle-config-rules:
Configuration Rules
-------------------
The following configuration rules apply:
The direction flags, ``GPIOHANDLE_REQUEST_INPUT`` and
``GPIOHANDLE_REQUEST_OUTPUT``, cannot be combined. If neither are set then the
only other flag that may be set is ``GPIOHANDLE_REQUEST_ACTIVE_LOW`` and the
line is requested "as-is" to allow reading of the line value without altering
the electrical configuration.
The drive flags, ``GPIOHANDLE_REQUEST_OPEN_xxx``, require the
``GPIOHANDLE_REQUEST_OUTPUT`` to be set.
Only one drive flag may be set.
If none are set then the line is assumed push-pull.
Only one bias flag, ``GPIOHANDLE_REQUEST_BIAS_xxx``, may be set, and
it requires a direction flag to also be set.
If no bias flags are set then the bias configuration is not changed.
Requesting an invalid configuration is an error (**EINVAL**).
.. _gpio-get-linehandle-config-support:
Configuration Support
---------------------
Where the requested configuration is not directly supported by the underlying
hardware and driver, the kernel applies one of these approaches:
- reject the request
- emulate the feature in software
- treat the feature as best effort
The approach applied depends on whether the feature can reasonably be emulated
in software, and the impact on the hardware and userspace if the feature is not
supported.
The approach applied for each feature is as follows:
============== ===========
Feature Approach
============== ===========
Bias best effort
Direction reject
Drive emulate
============== ===========
Bias is treated as best effort to allow userspace to apply the same
configuration for platforms that support internal bias as those that require
external bias.
Worst case the line floats rather than being biased as expected.
Drive is emulated by switching the line to an input when the line should not
be driven.
In all cases, the configuration reported by gpio-get-lineinfo-ioctl.rst
is the requested configuration, not the resulting hardware configuration.
Userspace cannot determine if a feature is supported in hardware, is
emulated, or is best effort.
Return Value
============
On success 0 and the :c:type:`request.fd<gpiohandle_request>` contains the
file descriptor for the request.
On error -1 and the ``errno`` variable is set appropriately.
Common error codes are described in error-codes.rst.
Documentation/userspace-api/gpio/gpio-get-lineinfo-ioctl.rst
+54
View File
@@ -0,0 +1,54 @@
.. SPDX-License-Identifier: GPL-2.0
.. _GPIO_GET_LINEINFO_IOCTL:
***********************
GPIO_GET_LINEINFO_IOCTL
***********************
.. warning::
This ioctl is part of chardev_v1.rst and is obsoleted by
gpio-v2-get-lineinfo-ioctl.rst.
Name
====
GPIO_GET_LINEINFO_IOCTL - Get the publicly available information for a line.
Synopsis
========
.. c:macro:: GPIO_GET_LINEINFO_IOCTL
``int ioctl(int chip_fd, GPIO_GET_LINEINFO_IOCTL, struct gpioline_info *info)``
Arguments
=========
``chip_fd``
The file descriptor of the GPIO character device returned by `open()`.
``info``
The :c:type:`line_info<gpioline_info>` to be populated, with the
``offset`` field set to indicate the line to be collected.
Description
===========
Get the publicly available information for a line.
This information is available independent of whether the line is in use.
.. note::
The line info does not include the line value.
The line must be requested using gpio-get-linehandle-ioctl.rst or
gpio-get-lineevent-ioctl.rst to access its value.
Return Value
============
On success 0 and ``info`` is populated with the chip info.
On error -1 and the ``errno`` variable is set appropriately.
Common error codes are described in error-codes.rst.

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